# @vscode/component-explorer

Core library for the [Component Explorer](../../README.md). Contains the fixture API, property schemas, fixture registry, and the Explorer React UI.

## Fixture API

### `defineFixture(options)`

Defines a single component fixture.

```tsx
import { defineFixture } from '@vscode/component-explorer';

export default defineFixture({
  properties: [
    { type: 'string', name: 'label', defaultValue: 'Click me' },
    { type: 'boolean', name: 'disabled', defaultValue: false },
  ],
  render: (container, props) => {
    const root = createRoot(container);
    root.render(<Button label={props.label as string} disabled={props.disabled as boolean} />);
    return { dispose: () => root.unmount() };
  },
});
```

Options:

| Option | Type | Default | Description |
|---|---|---|---|
| `render` | `(container, props) => Disposable` | **(required)** | Renders the component. Must return `{ dispose() }` for cleanup. |
| `properties` | `PropertySchema[]` | `[]` | Configurable properties shown in the properties panel. |
| `isolation` | `'shadow-dom' \| 'iframe'` | `'shadow-dom'` | Component isolation strategy. |
| `displayMode` | `DisplayMode` | `{ type: 'component' }` | `'component'` for natural size, or `'page'` with viewport presets. |
| `styles` | `StyleDefinition[]` | — | Stylesheets injected into the shadow root (shadow-dom isolation only). |
| `background` | `'light' \| 'dark'` | `'light'` | Preview canvas background pattern. |
| `description` | `string` | — | Documentation description. |

### `defineFixtureGroup(entries)`

Groups multiple fixtures (supports nesting):

```tsx
import { defineFixture, defineFixtureGroup } from '@vscode/component-explorer';

export default defineFixtureGroup({
  Primary: defineFixture({ render: (c) => { /* ... */ } }),
  Secondary: defineFixture({ render: (c) => { /* ... */ } }),
  Nested: defineFixtureGroup({
    Small: defineFixture({ render: (c) => { /* ... */ } }),
  }),
});
```

### `defineFixtureVariants(variants)`

Defines a flat set of variants rendered side-by-side:

```tsx
import { defineFixture, defineFixtureVariants } from '@vscode/component-explorer';

defineFixtureVariants({
  Small: defineFixture({ render: (c) => { /* ... */ } }),
  Medium: defineFixture({ render: (c) => { /* ... */ } }),
  Large: defineFixture({ render: (c) => { /* ... */ } }),
});
```

## Property Types

| Type | Fields | Description |
|---|---|---|
| `boolean` | `name`, `defaultValue` | Toggle checkbox |
| `string` | `name`, `defaultValue`, `multiline?` | Text input (or textarea) |
| `number` | `name`, `defaultValue`, `min?`, `max?`, `step?` | Number input with optional range |
| `enum` | `name`, `defaultValue`, `options` | Dropdown select |

All property types support an optional `description` field.

## Explorer UI Components

The package exports the full Explorer UI as React components:

| Export | Description |
|---|---|
| `Explorer` | Main explorer component (tree + preview + properties panel). |
| `ExplorerApp` | Standalone class that mounts the explorer into a DOM element. |
| `ExplorerModel` | Observable-based view model powering the explorer state. |
| `TreeView`, `TreeItem` | Tree navigation components. |
| `TitleBar`, `TitleBarButton` | Title bar chrome. |
| `LeftSidebar`, `RightSidebar` | Layout sidebar panels. |

## Core Utilities

| Export | Description |
|---|---|
| `FixtureRegistry` | Observable registry of discovered fixtures. |
| `createFixtureTree` | Builds a `FixtureNode` tree from registered fixtures. |
| `getDefaultPropertyValues` | Extracts default values from a `PropertySchema[]`. |
| `VIEWPORT_SIZES` | Built-in viewport preset dimensions (`mobile`, `tablet`, `desktop`). |

## Styles

Import `@vscode/component-explorer/styles.css` for the default explorer stylesheet. VS Code theme stylesheets are also available under `@vscode/component-explorer/vscode-styles/*`.