# Project Instructions

This project is a UI component library `@api-client/ui` built with [Lit](https://lit.dev/).

## Getting Started

1.  **Install Dependencies**:
    ```bash
    npm install
    ```

## Development Commands

*   **Start Dev Server**:
    ```bash
    npm run dev
    ```
    Starts the development server using `@web/dev-server` and watches for changes. Serves the `demo` folder found at `demo/index.html`.

*   **Build Project**:
    ```bash
    npm run build
    ```
    Compiles TypeScript and copies assets. generated output resides in `build/src/`. Uses `wireit` for caching.

*   **Run Tests**:
    ```bash
    npm test
    ```
    Runs tests using `@web/test-runner` with Playwright (Chromium).
    To target a single file: `npm test -- --files=".tmp/test/**/MyComponent.test.js"`

*   **Watch Tests**:
    ```bash
    npm run test:watch
    ```

*   **Lint & Format**:
    ```bash
    npm run lint
    npm run format
    ```

*   **Releasing**:
    See [RELEASE.md](./RELEASE.md) and [RELEASE_SETUP.md](./RELEASE_SETUP.md).

## Architecture & Core Concepts

**Application → Activities → Fragments** (Mirrors Android Lifecycle)
- **Lifecycle**: Created → Attached → Started → Resumed → Paused → Stopped → Detached → Destroyed.
- **Key Files** (`src/core/`):
    - `Application.ts`: Top-level container, owns `ActivityManager`.
    - `Activity.ts`: Screen-level logic + fragment orchestration.
    - `Fragment.ts`: Reusable UI segments. **Never assume global singletons.**
- **Rule**: Always use manager APIs (`addFragment`, `showFragment`) rather than manual DOM manipulation.

## Component & Folder Conventions

- **Paths**:
    - `src/md/`: Base Material-style components.
    - `src/elements/`: Business / composite elements.
- **Structure**: `component/` directory containing:
    - `internals/`: Base class logic.
    - `YourThing.ts`: Public element file registration (`@customElement`).
    - `*.styles.ts`: Styles.
- **Registration**: Do NOT use the legacy `src/define/` folder. Register in the public element file.
- **Exports**: Add new exports explicitly to `src/index.ts`.

## Lit Patterns (Enforced)

- **State**: Use `@property` for public API, `@state` for internal reactive state.
- **Initialization**: Initialize boolean props in the constructor.
- **Order**: constructor → lifecycle overrides → helpers → render methods.
- **DOM Querying**: Use `@query` for internal DOM, `@queryAssignedElements` for slots.
- **Styles**: Import from sibling `*.styles.ts`. Assign `static styles` only on the final registered class, not in `internals/` base classes.
- **Theming**: Expose style hooks with `part` attributes; prefer CSS vars for theming.

## Interaction & Intent System

Use **Intent Events** for navigation and cross-component actions. Do not reference Activities directly.

```ts
this.dispatchEvent(new CustomEvent('startactivity', {
  detail: { intent: { action: 'user.profile', data: { id } } }
}));
```

Activities listen for these events to decide fragment transitions.

## State Management

- **Controllers**: Reusable logic lives in `src/controllers/` (e.g., `ActionController`, `LiveDataController`).
- **Guidelines**:
    - Compose controllers rather than duplicating state wiring.
    - Keep side-effects isolated.
    - Document expected lifecycle usage.

## Styling & MD3

- Use **MD3 tokens** via CSS custom properties.
- No ad-hoc color literals.
- Use `this._internals.states.add('--error')` instead of custom class names for component states where feasible.
- Component-specific tokens go in component styles; do not put global resets there.

## Testing Norms

- **Location**: Co-locate tests under `test/` mirroring source paths.
- **Helpers**: Use `test/helpers/` and `window.testUtils`.
- **Async**: After validating a property change, ALWAYS `await el.updateComplete`.
- **Assertions**: Prefer Chai Assert API.

## Workflow: Adding a New Component

1.  **Create Directory**: Under `src/md/` or `src/elements/`.
2.  **Base Logic**: `internals/YourThingBase.ts`.
3.  **Styles**: `YourThing.styles.ts`.
4.  **Registration**: `YourThing.ts`:
    ```ts
    @customElement('ui-your-thing')
    export class UiYourThing extends YourThingBase { static override styles = [styles] }
    ```
5.  **Export**: Add to `src/index.ts`.
6.  **Demo**: Add to `demo/[category]/your-thing/`.
7.  **Test**: Add to `test/`.

## Common Pitfalls

- Direct DOM mutation of fragments (use manager).
- Adding styles to the base class (must live on registered element).
- Using stale legacy `define/` patterns.
- Skipping `await el.updateComplete` in tests.
- Hard-coded colors instead of tokens.

## External Dependencies

- Models come from `@api-client/core`.
- `monaco-editor` is ISOLATED in `src/elements/code-editor/`. Do not import it elsewhere.

## Wireit

This project uses [wireit](https://github.com/google/wireit) for script dependency management and caching.
