# LLM Codegen Standard: Web Components

Use this file as a hard contract when generating web components in this repository.

## Scope

- Applies to all generated custom elements/web components.
- Applies to components used with or without a framework host.
- This standard prioritizes separation of rendering, state orchestration, and IO.

## Primary objective

Generate web components that are thin, reusable UI units with explicit public APIs and outward user-intent events.

## Non-negotiable rules

- MUST keep components render-focused.
- MUST keep shared workflow state outside components (host store/reconciler).
- MUST expose minimal imperative visual methods for host control.
- MUST emit semantic custom events for user intent.
- MUST keep service/auth/network/business-policy logic outside components.
- MUST NOT import host-level store modules into components.
- MUST NOT orchestrate global workflow transitions inside components.
- MUST NOT duplicate cross-section shared state in component internals.

## Component contract

Each generated component MUST define:

- Public visual API methods (for example, `setDisabled`, `setStatus`, `setValues`).
- Emitted user-intent events in kebab-case (for example, `profile-submit`, `item-select`).
- Internal local-only behavior (focus state, local toggles, local previews).

Each generated component MUST avoid:

- Direct calls to HTTP/Graph/SDK/service clients.
- Token/auth/session handling.
- Reading global store state directly.

## Host integration contract

Host code MUST:

- Compute derived UI rules in the reconciler/store layer.
- Call component public methods to apply visual state.
- Listen to component events and run side effects/services externally.

Preferred pattern:

```ts
const profileForm = document.querySelector('profile-form') as ProfileForm | null;
if (profileForm) {
  profileForm.setSubmitEnabled(!state.isBusy && state.canEdit);
  profileForm.setSubmitHint(state.isBusy ? 'Please wait' : '');
}
```

Component pattern:

```ts
public setSubmitEnabled(enabled: boolean): void {
  const btn = this.querySelector('[data-submit]') as HTMLButtonElement | null;
  if (!btn) return;
  btn.disabled = !enabled;
}

private onSubmit(values: ProfileValues): void {
  this.dispatchEvent(new CustomEvent('profile-submit', { bubbles: true, detail: values }));
}
```

## Event naming and payload rules

- Event names MUST be kebab-case and domain-specific (`task-create`, `task-delete`).
- Payloads MUST be explicit objects, not positional arrays.
- Events SHOULD bubble when host-level listeners are expected.
- Events SHOULD avoid leaking private internal field names where possible.

## DOM strategy rules

- Use light DOM when native form behaviors (`FormData`, browser validation, standard submit flows) are required.
- Use shadow DOM when style encapsulation is needed and form behavior constraints do not conflict.
- If shadow DOM is chosen, expose stable hooks for testing and host integration.

## Forbidden patterns

- Component mutates host/global store directly.
- Component imports service layer and performs IO.
- Host broadcasts global UI-state events to push all component updates when direct method calls are available.
- Component silently changes behavior based on global singletons without explicit API.

## Minimum test requirements for generated code

- Component unit tests:
  - render output
  - public method behavior
  - custom event emission
- Host integration tests:
  - reconciler calls component API correctly
  - host receives and handles component events
- Contract tests:
  - method names and event names remain stable through refactors

## Generation acceptance checklist

Before finalizing generated code, verify:

- Component contains rendering/local behavior only.
- Shared state logic exists in host store/reconciler.
- All side effects and IO are outside component class.
- Public API and event contract are explicit and documented.
- Tests validate both component internals and host integration contract.

## Prompt contract for future LLM sessions

Use this prompt block when asking an LLM to generate web components:

```text
Follow repository standard: documentation/llm-codegen-standards/web-components-guidelines.md.
Generate thin render-focused components with explicit setter-style APIs and semantic custom events.
Keep shared state, business logic, and service/auth/network calls in host store/reconciler/services.
Include component unit tests and host integration/contract tests.
```