@kitn.ai/ui 0.14.1

package/src/elements/model-switcher.declarative.test.tsx

@@ -0,0 +1,130 @@
+/**
+ * Unit tests for the declarative `<kai-model>` light-DOM API of
+ * `<kai-model-switcher>`.
+ *
+ * Strategy: the `defineWebComponent` call registers a real Shadow-DOM custom
+ * element which requires a full browser environment (Constructable Stylesheets,
+ * shadow roots, etc.) and is therefore not suitable for jsdom unit tests.
+ * Instead we:
+ *   1. Test the exported `parseKaiModelElement` helper in isolation — it has no
+ *      DOM dependencies beyond `Element`, which jsdom provides perfectly.
+ *   2. Test that the merged list of prop + slotted models combines correctly,
+ *      mirroring the pattern used in `prompt-suggestions.declarative.test.tsx`.
+ */
+import { describe, it, expect } from 'vitest';
+import { parseKaiModelElement } from './model-switcher';
+import type { ModelOption } from '../types';
+
+// ---------------------------------------------------------------------------
+// parseKaiModelElement — pure helper
+// ---------------------------------------------------------------------------
+
+describe('parseKaiModelElement', () => {
+  function makeNode(textContent: string, id?: string, provider?: string): Element {
+    const el = document.createElement('kai-model');
+    el.textContent = textContent;
+    if (id !== undefined) el.setAttribute('id', id);
+    if (provider !== undefined) el.setAttribute('provider', provider);
+    return el;
+  }
+
+  it('maps textContent to name', () => {
+    const item = parseKaiModelElement(makeNode('GPT-4o', 'gpt-4o'));
+    expect(item.name).toBe('GPT-4o');
+  });
+
+  it('maps the id attribute to id', () => {
+    const item = parseKaiModelElement(makeNode('GPT-4o', 'gpt-4o'));
+    expect(item.id).toBe('gpt-4o');
+  });
+
+  it('maps the provider attribute to provider', () => {
+    const item = parseKaiModelElement(makeNode('GPT-4o', 'gpt-4o', 'OpenAI'));
+    expect(item.provider).toBe('OpenAI');
+  });
+
+  it('sets provider to undefined when the attribute is absent', () => {
+    const item = parseKaiModelElement(makeNode('Claude Sonnet', 'sonnet'));
+    expect(item.provider).toBeUndefined();
+  });
+
+  it('trims leading/trailing whitespace from textContent (name)', () => {
+    const item = parseKaiModelElement(makeNode('  Claude Sonnet  ', 'sonnet'));
+    expect(item.name).toBe('Claude Sonnet');
+  });
+
+  it('returns empty string for id when id attribute is absent', () => {
+    const item = parseKaiModelElement(makeNode('GPT-4o'));
+    expect(item.id).toBe('');
+  });
+
+  it('produces the full ModelOption shape', () => {
+    const item = parseKaiModelElement(makeNode('GPT-4o', 'gpt-4o', 'OpenAI'));
+    expect(item).toEqual<ModelOption>({ id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI', description: undefined, group: undefined });
+  });
+
+  it('maps the description and group attributes', () => {
+    const el = document.createElement('kai-model');
+    el.textContent = 'GPT-4o';
+    el.setAttribute('id', 'gpt-4o');
+    el.setAttribute('description', 'Flagship model');
+    el.setAttribute('group', 'Legacy models');
+    const item = parseKaiModelElement(el);
+    expect(item.description).toBe('Flagship model');
+    expect(item.group).toBe('Legacy models');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Merge logic: prop models + slotted models combine correctly
+// ---------------------------------------------------------------------------
+
+describe('prop + declarative merge', () => {
+  function makeNode(textContent: string, id: string, provider?: string): Element {
+    const el = document.createElement('kai-model');
+    el.textContent = textContent;
+    el.setAttribute('id', id);
+    if (provider !== undefined) el.setAttribute('provider', provider);
+    return el;
+  }
+
+  it('renders prop items before declarative (slotted) items', () => {
+    const propModels: ModelOption[] = [{ id: 'opus', name: 'Claude Opus', provider: 'Anthropic' }];
+    const slottedModels = [makeNode('GPT-4o', 'gpt-4o', 'OpenAI')].map(parseKaiModelElement);
+    const merged = [...propModels, ...slottedModels];
+    expect(merged).toHaveLength(2);
+    expect(merged[0].id).toBe('opus');
+    expect(merged[1].id).toBe('gpt-4o');
+  });
+
+  it('works with only declarative children (empty prop array)', () => {
+    const slottedModels = [
+      makeNode('GPT-4o', 'gpt-4o', 'OpenAI'),
+      makeNode('GPT-4o mini', 'gpt-4o-mini', 'OpenAI'),
+    ].map(parseKaiModelElement);
+    const merged = [...[], ...slottedModels];
+    expect(merged).toHaveLength(2);
+    expect(merged[0]).toMatchObject({ id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' });
+    expect(merged[1]).toMatchObject({ id: 'gpt-4o-mini', name: 'GPT-4o mini', provider: 'OpenAI' });
+  });
+
+  it('works with only prop models (no declarative children)', () => {
+    const propModels: ModelOption[] = [
+      { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+      { id: 'haiku', name: 'Claude Haiku', provider: 'Anthropic' },
+    ];
+    const merged = [...propModels, ...([] as ModelOption[])];
+    expect(merged).toHaveLength(2);
+    expect(merged[0].id).toBe('sonnet');
+    expect(merged[1].id).toBe('haiku');
+  });
+
+  it('parseKaiModelElement produces items with the correct event payload key (id → modelId)', () => {
+    // Confirm the parsed `id` field is what gets dispatched as `modelId` in kai-model-change.
+    // The element fires: dispatch('kai-model-change', { modelId }) where modelId = item.id.
+    const node = makeNode('GPT-4o', 'gpt-4o', 'OpenAI');
+    const parsed = parseKaiModelElement(node);
+    // The model-switcher component passes item.id as the modelId in the event.
+    expect(parsed.id).toBe('gpt-4o'); // this becomes e.detail.modelId
+  });
+});

package/src/elements/model-switcher.stories.tsx

@@ -0,0 +1,198 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { ModelOption } from '../types';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-model-switcher': JSX.HTMLAttributes<HTMLElement>;
+      /** Light-DOM data carrier for declarative model options inside `<kai-model-switcher>`. */
+      'kai-model': JSX.HTMLAttributes<HTMLElement> & {
+        id?: string;
+        provider?: string;
+        description?: string;
+        group?: string;
+      };
+    }
+  }
+}
+
+const models: ModelOption[] = [
+  { id: 'opus', name: 'Claude Opus', provider: 'Anthropic' },
+  { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+  { id: 'haiku', name: 'Claude Haiku', provider: 'Anthropic' },
+];
+
+/** Render `<kai-model-switcher>` with `models` set as a property; tracks selection. */
+function SwitcherElement(props: { models: ModelOption[]; current?: string }) {
+  let el: (HTMLElement & { models?: ModelOption[]; currentModel?: string }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.models = props.models;
+    el.currentModel = props.current ?? props.models[0]?.id;
+    // reflect the selection back so the trigger label updates
+    el.addEventListener('kai-model-change', (e) => {
+      const ev = e as CustomEvent<{ modelId: string }>;
+      el!.currentModel = ev.detail.modelId;
+    });
+  });
+  return (
+    <kai-model-switcher ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-model-switcher id="ms"></kai-model-switcher>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const ms = document.getElementById('ms');
+  ms.models = [
+    { id: 'opus', name: 'Claude Opus', provider: 'Anthropic' },
+    { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+  ];
+  ms.currentModel = 'opus';
+  ms.addEventListener('kai-model-change', (e) => { ms.currentModel = e.detail.modelId; });
+</script>`;
+
+const meta = {
+  title: 'Components/ModelSwitcher',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-model-switcher'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-model-switcher', [
+          '`<kai-model-switcher>` is the framework-agnostic **web component** for picking the active model — a dropdown showing each model\'s name and provider — isolated in **Shadow DOM**. It mirrors the switcher inside `<kai-chat>` as a standalone, composable piece.',
+          '**When to use:** building your own chat header and want the model picker on its own. In SolidJS, use the `ModelSwitcher` primitive.',
+          '**Placement:** inline in the chat header or toolbar, typically to the left of the context meter; it is a compact `inline-block` dropdown trigger that fits naturally beside other header controls.',
+          "**How to use — property API:** register once with `import '@kitn.ai/ui/elements'`, set the `models` **property** (each item: `{ id, name, provider? }`) and optionally `currentModel`, and listen for the `kai-model-change` **CustomEvent** (payload: `{ modelId }`). Note: like the underlying primitive, it only renders when more than one model is provided.",
+          "**How to use — declarative API:** compose `<kai-model>` light-DOM children instead of (or in addition to) setting the `models` property. Each `<kai-model id=\"gpt-4o\" provider=\"OpenAI\">GPT-4o</kai-model>` carries `id` (required), `provider` (optional), and a text label as its content. Children are hidden data carriers — no JS property assignment needed. Prop `models` items render first; `<kai-model>` children follow.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A three-model picker; selecting updates the trigger label. */
+export const Default: Story = {
+  render: () => <SwitcherElement models={models} current="opus" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Raw data — the `models` array shape that `<kai-model-switcher>` consumes. */
+export const Data: Story = {
+  name: 'Data',
+  render: () => (
+    <pre style={{ padding: '16px', 'font-size': '13px' }}>
+      {JSON.stringify(
+        [
+          { id: 'opus', name: 'Claude Opus', provider: 'Anthropic' },
+          { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+          { id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' },
+        ],
+        null,
+        2,
+      )}
+    </pre>
+  ),
+};
+
+const DECLARATIVE_HTML_SNIPPET = `<!-- Works in any framework or plain HTML — no JS property assignment needed -->
+<kai-model-switcher id="ms">
+  <kai-model id="gpt-4o" provider="OpenAI">GPT-4o</kai-model>
+  <kai-model id="gpt-4o-mini" provider="OpenAI">GPT-4o mini</kai-model>
+  <kai-model id="claude-sonnet" provider="Anthropic">Claude Sonnet</kai-model>
+</kai-model-switcher>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  document.getElementById('ms').addEventListener('kai-model-change', (e) => {
+    console.log('selected model:', e.detail.modelId);
+  });
+</script>`;
+
+/**
+ * Declare each model option as a `<kai-model>` child element — no `models`
+ * property or JS array wiring needed. The `id` attribute is the model identifier
+ * emitted in `kai-model-change`; `provider` is optional; `textContent` is the
+ * display label. Children are light-DOM data carriers hidden by the Shadow DOM.
+ * Mix with the `models` prop: prop items render first, declarative children after.
+ * Note: the switcher only renders when more than one model is provided.
+ */
+export const DeclarativeModels: Story = {
+  name: 'Declarative Models (kai-model)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.addEventListener('kai-model-change', (e) =>
+        console.log('kai-model-change', (e as CustomEvent<{ modelId: string }>).detail.modelId),
+      );
+    });
+    return (
+      <kai-model-switcher
+        ref={(e) => (el = e as HTMLElement)}
+        style={{ display: 'inline-block', padding: '40px' }}
+      >
+        <kai-model id="gpt-4o" provider="OpenAI">GPT-4o</kai-model>
+        <kai-model id="gpt-4o-mini" provider="OpenAI">GPT-4o mini</kai-model>
+        <kai-model id="claude-sonnet" provider="Anthropic">Claude Sonnet</kai-model>
+      </kai-model-switcher>
+    );
+  },
+  parameters: {
+    docs: {
+      source: { code: DECLARATIVE_HTML_SNIPPET, language: 'html' },
+    },
+  },
+};
+
+const GROUPED_HTML_SNIPPET = `<kai-model-switcher id="ms">
+  <kai-model id="gpt-5.5" description="Flagship model">GPT-5.5</kai-model>
+  <kai-model id="gpt-4o" group="Legacy models">GPT-4o</kai-model>
+  <kai-model id="gpt-4.1" group="Legacy models">GPT-4.1</kai-model>
+</kai-model-switcher>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  document.getElementById('ms').addEventListener('kai-model-change', (e) => {
+    console.log('selected model:', e.detail.modelId);
+  });
+</script>`;
+
+/**
+ * Rich rows + a collapsible group via `<kai-model>` attributes: `description`
+ * renders as the row subtitle, and children sharing a `group` collect under a
+ * collapsible section — the ChatGPT-style "Legacy models" pattern.
+ */
+export const GroupedModels: Story = {
+  name: 'Grouped & Described (kai-model)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.addEventListener('kai-model-change', (e) =>
+        console.log('kai-model-change', (e as CustomEvent<{ modelId: string }>).detail.modelId),
+      );
+    });
+    return (
+      <kai-model-switcher ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }}>
+        <kai-model id="gpt-5.5" description="Flagship model">GPT-5.5</kai-model>
+        <kai-model id="gpt-5.5-mini" description="Faster, lighter">GPT-5.5 mini</kai-model>
+        <kai-model id="gpt-4o" group="Legacy models">GPT-4o</kai-model>
+        <kai-model id="gpt-4.1" group="Legacy models">GPT-4.1</kai-model>
+      </kai-model-switcher>
+    );
+  },
+  parameters: { docs: { source: { code: GROUPED_HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/model-switcher.tsx

@@ -0,0 +1,93 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { ModelSwitcher } from '../components/model-switcher';
+import type { ModelOption } from '../types';
+
+interface Props extends Record<string, unknown> {
+  /** The selectable models. Set as a JS property (array). */
+  models: ModelOption[];
+  /** The currently-selected model id. Defaults to the first model. */
+  currentModel?: string;
+}
+
+/** Events fired by `<kai-model-switcher>`. */
+interface Events {
+  /** A model was selected. */
+  'kai-model-change': { modelId: string };
+}
+
+/**
+ * Parse a single light-DOM `<kai-model>` element into a `ModelOption` descriptor.
+ * Attribute mapping:
+ *  - `id`        → ModelOption.id
+ *  - textContent    → ModelOption.name
+ *  - `provider`     → ModelOption.provider (optional)
+ *  - `description`  → ModelOption.description (optional subtitle)
+ *  - `group`        → ModelOption.group (optional collapsible section)
+ */
+export function parseKaiModelElement(n: Element): ModelOption {
+  return {
+    id: n.getAttribute('id') ?? '',
+    name: n.textContent?.trim() ?? '',
+    provider: n.getAttribute('provider') ?? undefined,
+    description: n.getAttribute('description') ?? undefined,
+    group: n.getAttribute('group') ?? undefined,
+  };
+}
+
+/**
+ * `<kai-model-switcher>` — an event-emitting leaf element. Data in via the
+ * `models` property, selection out via a `kai-model-change` event. Mirrors the
+ * header switcher inside `<kai-chat>` as a standalone, composable piece.
+ *
+ * Note: like the underlying primitive, this only renders when more than one
+ * model is provided.
+ *
+ * **How to use:**
+ *
+ * _Property API_ — set `models` as a JS property and listen for `kai-model-change`:
+ * ```js
+ * el.models = [{ id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' }];
+ * el.addEventListener('kai-model-change', (e) => console.log(e.detail.modelId));
+ * ```
+ *
+ * _Declarative child API_ — compose `<kai-model>` light-DOM children (no JS needed):
+ * ```html
+ * <kai-model-switcher>
+ *   <kai-model id="gpt-4o" provider="OpenAI">GPT-4o</kai-model>
+ *   <kai-model id="gpt-4o-mini" provider="OpenAI">GPT-4o mini</kai-model>
+ * </kai-model-switcher>
+ * ```
+ * Each `<kai-model>` child carries `id` (required), `provider` (optional), and
+ * a text label as its `textContent`. Children are light-DOM data carriers hidden
+ * by Shadow DOM. Prop `models` items render first; declarative children follow.
+ */
+defineWebComponent<Props, Events>('kai-model-switcher', {
+  models: [],
+  currentModel: undefined,
+}, (props, { dispatch, element }) => {
+  // Read declarative <kai-model> children from light DOM.
+  // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
+  const [slottedModels, setSlottedModels] = createSignal<ModelOption[]>([]);
+  onMount(() => {
+    const read = () => {
+      const nodes = [...element.querySelectorAll('kai-model')];
+      setSlottedModels(nodes.map(parseKaiModelElement));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  // Merge prop models (first) with declarative children (after).
+  const allModels = () => [...(props.models ?? []), ...slottedModels()];
+
+  return (
+    <ModelSwitcher
+      models={allModels()}
+      currentModelId={props.currentModel ?? allModels()[0]?.id ?? ''}
+      onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
+    />
+  );
+});

package/src/elements/popover.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, Show, For } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-popover': JSX.HTMLAttributes<HTMLElement> & { placement?: string; gutter?: number | string; open?: boolean };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<kai-popover placement="bottom-start">
+  <button slot="trigger">GPT-5.5 ▾</button>
+  <div>
+    <button>GPT-5.5 — Flagship model</button>
+    <button>Legacy models ▾</button>
+  </div>
+</kai-popover>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+  document.querySelector('kai-popover')
+    .addEventListener('kai-open-change', (e) => console.log('open:', e.detail.open));
+</script>`;
+
+const meta = {
+  title: 'Components/Popover',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-popover'),
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: specDescription('kai-popover', [
+        '`<kai-popover>` is the framework-agnostic **web component** for a button-and-popover card — a trigger that toggles a floating panel of arbitrary content, isolated in **Shadow DOM**. In SolidJS, use the `Popover` primitive.',
+        '**When to use:** a "button + card" affordance — a header model menu, a settings popover, an account dropdown with mixed controls. For a flat list of commands, use a menu instead.',
+        '**How to use:** slot the control as `slot="trigger"` and the panel as the default slot. Clicking the trigger toggles; Escape or an outside click closes (clicks inside do not). It fires `kai-open-change` with `{ open }` and accepts an `open` property for controlled use.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+const rowStyle = { display: 'flex', 'align-items': 'center', gap: '8px', width: '100%', padding: '6px 8px', 'border-radius': '6px', border: 'none', background: 'transparent', cursor: 'pointer', 'text-align': 'left' as const, font: 'inherit', color: 'var(--color-foreground)' };
+const LEGACY = ['GPT-4o', 'GPT-4.1', 'GPT-4o mini'];
+
+/** A ChatGPT-style model menu — a flagship row and an expandable group, slotted
+ *  as the popover panel. The trigger and content are your light-DOM markup. */
+export const ModelMenu: Story = {
+  render: () => {
+    let el: HTMLElement | undefined;
+    const [legacyOpen, setLegacyOpen] = createSignal(false);
+    onMount(() => el?.addEventListener('kai-open-change', (e) => console.log('kai-open-change', (e as CustomEvent<{ open: boolean }>).detail.open)));
+    return (
+      <kai-popover ref={(e) => (el = e as HTMLElement)} placement="bottom-start">
+        <button slot="trigger" style={{ padding: '6px 12px', 'border-radius': '8px', border: '1px solid var(--color-border)', background: 'transparent', color: 'var(--color-foreground)', cursor: 'pointer', font: 'inherit' }}>
+          GPT-5.5 ▾
+        </button>
+        <div style={{ width: '15rem' }}>
+          <button type="button" style={rowStyle}>
+            <span style={{ 'font-weight': 600 }}>GPT-5.5</span>
+            <span style={{ 'font-size': '12px', color: 'var(--color-muted-foreground)' }}>Flagship</span>
+          </button>
+          <button type="button" style={rowStyle} aria-expanded={legacyOpen()} onClick={() => setLegacyOpen(!legacyOpen())}>
+            Legacy models {legacyOpen() ? '▴' : '▾'}
+          </button>
+          <Show when={legacyOpen()}>
+            <For each={LEGACY}>{(m) => <button type="button" style={{ ...rowStyle, 'padding-left': '28px' }}>{m}</button>}</For>
+          </Show>
+        </div>
+      </kai-popover>
+    );
+  },
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/popover.tsx

@@ -0,0 +1,59 @@
+import { defineWebComponent } from './define';
+import { Popover } from '../ui/popover';
+import type { Placement } from '@floating-ui/dom';
+
+interface Props extends Record<string, unknown> {
+  /** Floating placement relative to the trigger (floating-ui placement). */
+  placement?: Placement;
+  /** Gap in px between the trigger and the panel. */
+  gutter?: number;
+  /** Controlled open state. Set as a JS property (`el.open = true`) to drive the
+   *  popover from your app; omit for the default click-to-toggle behaviour. */
+  open?: boolean;
+}
+
+/** Events fired by `<kai-popover>`. */
+interface Events {
+  /** The popover wants to open or close (click, Escape, or outside-click). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-popover>` — a button-and-popover primitive: a trigger that toggles a
+ * floating panel of arbitrary content. The panel is a `role="dialog"` region
+ * (not a menu), so it can hold model rows, toggle switches, nested groups, or
+ * any markup — the building block for ChatGPT-style header menus and similar
+ * "button + popover card" affordances.
+ *
+ * **How to use** — slot a trigger and the panel content:
+ * ```html
+ * <kai-popover placement="bottom-start">
+ *   <button slot="trigger">ChatGPT ⌄</button>
+ *   <div>
+ *     <p><strong>GPT-5.5</strong> — Flagship model</p>
+ *     <button>Legacy models</button>
+ *   </div>
+ * </kai-popover>
+ * ```
+ *
+ * The default slot is the panel; the `trigger` slot is the control. Clicking the
+ * trigger toggles the panel; Escape or an outside click closes it (clicks inside
+ * the panel do not). It fires `kai-open-change` with `{ open }` on every change,
+ * and accepts an `open` JS property for controlled use.
+ */
+defineWebComponent<Props, Events>('kai-popover', {
+  placement: 'bottom-start',
+  gutter: 6,
+  open: undefined,
+}, (props, { dispatch, element }) => (
+  <Popover
+    trigger={<slot name="trigger" />}
+    placement={props.placement as Placement}
+    gutter={props.gutter}
+    open={props.open}
+    boundary={() => element}
+    onOpenChange={(open) => dispatch('kai-open-change', { open })}
+  >
+    <slot />
+  </Popover>
+));