@kitn.ai/ui 0.25.2 → 0.27.0

package/src/elements/diagnostic-events.ts

@@ -0,0 +1,114 @@
+// The ELEMENT-layer diagnostic events: what the `kai-*` custom elements SAW a
+// consumer do to them.
+//
+// The wire events answer "did the data arrive". These answer the other half —
+// "the data is right and the UI still is not updating" — which is a different
+// failure with a different cause and, until now, no evidence at all. All three
+// causes are documented in root CLAUDE.md's `kai-` contract section, and every
+// one of them is silent by construction:
+//
+//   1. An array or object prop set as an HTML ATTRIBUTE. `component-register`
+//      parses attributes with a `JSON.parse` whose `catch` returns the raw
+//      string, so `el.setAttribute('messages', arr)` assigns the literal text
+//      `"[object Object],[object Object]"` to the property and pushes THAT into
+//      the Solid signal. Nothing throws, nothing logs, nothing renders.
+//   2. The SAME array reference handed back. solid-element creates one signal
+//      per prop and sets it with `set(() => v)`; Solid's default equality is
+//      `===`, so re-assigning the identical reference notifies nothing.
+//   3. A NEW array whose items are all the previous item objects. The array
+//      notifies, but the lists render through reference-keyed `<For>`s, so no
+//      row is re-invoked and nothing on screen changes.
+//
+// ZERO IMPORTS, DELIBERATELY. These are type declarations only, so this file is
+// erased at build. That is what lets `wire/diagnostics.ts` name them in its
+// union without `wire/` acquiring a runtime dependency on `elements/` — which
+// would be a real layering inversion, and would drag the element bundle into
+// every consumer that only parses streams.
+//
+// METADATA ONLY, by the same rule the wire events follow: if a value comes from
+// the model, the end user, or the app's data it is PAYLOAD; if it describes the
+// shape, size, timing or identity of that value it is METADATA. A tag name, a
+// prop name, a kind, a count and a length are all identity or shape. A prop's
+// VALUE never appears in any field below — `valuePreview` is a shape
+// description built from a closed vocabulary, never the text itself. Pinned by
+// `element-diagnostics-payload.test.ts`, which plants a sentinel inside every
+// prop value it sets and asserts it never reaches a serialized event.
+
+/** The envelope, structurally identical to `WireDiagnosticBase`. Restated here
+ *  rather than imported so this file keeps its zero-import property; the two are
+ *  kept in step by `element-diagnostics.test.ts`, which asserts every emitted
+ *  element event carries a `type` and a numeric `t`. */
+export interface ElementDiagnosticBase {
+  type: string;
+  /** `Date.now()` at emission. */
+  t: number;
+}
+
+/** Which contract was broken. A closed vocabulary, so a panel keys its own
+ *  explanation off the kind and never needs prose from the kit. */
+export type ElementViolationKind =
+  /** A non-scalar prop received a value through the ATTRIBUTE channel. The
+   *  attribute cannot carry an array or an object, so the property now holds a
+   *  string and the element renders nothing. */
+  | 'array-prop-as-attribute'
+  /** A list prop was set to the array reference it already held. Solid compares
+   *  with `===`, so this notified nothing — a no-op write. */
+  | 'same-array-reference'
+  /** A list prop received a NEW array of the SAME length whose every item is
+   *  reference-identical to the previous array's. The array notified, but every
+   *  row's identity is unchanged, so a reference-keyed `<For>` re-invokes none
+   *  of them. The classic "I mutated the item and copied the array" case.
+   *
+   *  NOTE what this deliberately does NOT claim: the kit cannot know an item
+   *  "changed" without comparing its CONTENT, and content is payload. So this
+   *  reports the structurally knowable fact — an update that cannot render —
+   *  and leaves the question of whether the consumer meant anything by it to
+   *  the consumer, who is the only one who can answer it. */
+  | 'mutated-in-place';
+
+/** A consumer broke one of the three `kai-` contract rules on a live element. */
+export interface ElementViolationEvent extends ElementDiagnosticBase {
+  type: 'element.violation';
+  kind: ElementViolationKind;
+  /** The custom-element tag, e.g. `kai-chat`. */
+  tag: string;
+  /** The camelCase prop name, e.g. `messages`. */
+  prop: string;
+  /**
+   * SHAPE of the offending value, never its content. `array-prop-as-attribute`
+   * only. A closed vocabulary:
+   *
+   *   `[object Object]`      one object stringified into the attribute
+   *   `[object Object] x N`  an array of N objects stringified — the common case
+   *   `json:number`          the attribute held valid JSON, but a scalar
+   *   `json:boolean`         "
+   *   `json:null`            "
+   *   `string(len=N)`        anything else: the LENGTH of the text, never the text
+   *   `empty-attribute`      a bare attribute on a prop that needs a value
+   */
+  valuePreview?: string;
+  /** Element count of the array involved. `same-array-reference` and
+   *  `mutated-in-place` only. A length is shape, not content. */
+  length?: number;
+}
+
+/** Which `kai-*` elements are DEFINED in this realm right now.
+ *
+ *  The question behind it is hydration: an SSR page whose markup contains
+ *  `<kai-chat>` but whose element bundle never loaded shows empty boxes and no
+ *  error, because an undefined custom element is a valid, inert HTMLElement.
+ *  The SSR starters already answer this by hand for a hard-coded handful
+ *  (`HydrationBadge.tsx`); this is the same answer over the whole manifest. */
+export interface ElementRegistryEvent extends ElementDiagnosticBase {
+  type: 'element.registry';
+  /** Tags `customElements.get()` resolved. */
+  defined: string[];
+  /** Tags in the manifest that are NOT defined in this realm. Named for what it
+   *  is rather than `undefined`, which is a miserable key to read in a panel. */
+  notDefined: string[];
+  /** `defined.length + notDefined.length`. Present so a panel can show "62 of
+   *  79" without trusting itself to add up two arrays it may have truncated. */
+  total: number;
+}
+
+export type ElementDiagnosticEvent = ElementViolationEvent | ElementRegistryEvent;

package/src/elements/dialog.tsx

@@ -10,6 +10,44 @@ interface Props extends Record<string, unknown> {
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
+  /**
+   * Accessible name for the modal, used when no `header` slot is projected:
+   * `<kai-dialog label="Delete workspace">`. A projected `header` WINS over this
+   * (it becomes `aria-labelledby`), because ARIA resolves `aria-labelledby` ahead
+   * of `aria-label` and the visible heading is the name both a sighted and a
+   * screen-reader user can be talked through. Defaults to `Dialog` so a modal is
+   * never nameless.
+   */
+  label?: string;
+}
+
+/**
+ * The fallback accessible name.
+ *
+ * DELIBERATELY GENERIC, and a decision rather than a placeholder. A modal with no
+ * name at all fails WCAG and axe's `aria-dialog-name`; "Dialog, dialog" is merely
+ * redundant, and between the two the redundant one is strictly better — it is also
+ * what Shoelace and WebAwesome ship. The kit cannot know what a given modal is about,
+ * so inventing something specific here would be a worse default than saying nothing
+ * extra. Consumers name it properly with `label` or by projecting a `header`.
+ */
+const DEFAULT_LABEL = 'Dialog';
+
+/**
+ * The consumer's label, or the fallback — with "no label" meaning every way a
+ * consumer can arrive at one.
+ *
+ * The declared default is a SEED, not a floor: component-register writes the prop
+ * back as `null` when the attribute is removed and does NOT restore the declared
+ * value, so `props.label` is legitimately `null`/`undefined` at runtime. An empty or
+ * whitespace-only string is the same situation wearing a name — `aria-label=""` is a
+ * `role="dialog"` with no accessible name, i.e. the exact defect this exists to
+ * prevent, reached through the attribute that was supposed to prevent it. Each of
+ * those routes is a row in tests/elements/dialog.test.tsx, because a mutation run
+ * showed the plain `??` was uncovered.
+ */
+function resolveLabel(label: unknown): string {
+  return typeof label === 'string' && label.trim() !== '' ? label : DEFAULT_LABEL;
 }
 
 /** Events fired by `<kai-dialog>`. */
@@ -40,6 +78,10 @@ interface Events {
  * the dialog. Focus moves into the panel on open and is restored on close, and a
  * basic Tab focus trap keeps keyboard focus inside while open.
  *
+ * The dialog is always named: a projected `header` becomes its `aria-labelledby`,
+ * and otherwise `label` becomes its `aria-label` (defaulting to `Dialog`). The
+ * header wins when both are present, since ARIA ranks `aria-labelledby` first.
+ *
  * Open state is the standard disclosure surface: settable+reflecting `open`,
  * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
  * It also exposes `focus()` to move focus to the panel. Parts: `backdrop` ·
@@ -48,6 +90,7 @@ interface Events {
 defineWebComponent<Props, Events>('kai-dialog', {
   open: undefined,
   defaultOpen: undefined,
+  label: DEFAULT_LABEL,
 }, (props, ctx) => {
   const { flag, element, expose } = ctx;
   let api: DialogController | undefined;
@@ -87,6 +130,10 @@ defineWebComponent<Props, Events>('kai-dialog', {
   return (
     <Dialog
       defaultOpen={flag('defaultOpen')}
+      // The primitive already ranks these correctly — it emits `aria-labelledby` when
+      // a header is present and `aria-label` only when one is not — so the facade just
+      // has to HAND the name over, which is the wiring that was missing.
+      aria-label={resolveLabel(props.label)}
       header={hasHeader() ? <slot name="header" /> : undefined}
       footer={hasFooter() ? <slot name="footer" /> : undefined}
       controllerRef={(a) => (api = a)}

package/src/elements/disclosure.ts

@@ -37,22 +37,23 @@ export function wireDisclosure<E extends { 'kai-open-change': { open: boolean }
   getApi: () => OpenController | undefined,
   openProp: () => unknown,
 ): void {
-  const { element, dispatch, flag, expose } = ctx;
+  const { element, dispatch, flag, reflectFlag, expose } = ctx;
   let prev: boolean | undefined;
 
-  // Reflect internal open → the `[open]` host attribute + fire kai-open-change.
-  createEffect(() => {
-    const api = getApi();
-    if (!api) return;
-    const o = api.open();
-    element.toggleAttribute('open', o);
-    if (prev !== undefined && prev !== o) dispatch('kai-open-change', { open: o } as E['kai-open-change']);
-    prev = o;
-  });
-
   // External `open` prop/attr → drive internal state. Only when the consumer has
   // EXPLICITLY set it (so a defaultOpen seed survives mount); the equality guard
-  // keeps the reflect above from looping back through the prop.
+  // keeps the reflect below from looping back through the prop.
+  //
+  // THIS RUNS FIRST, AND THE ORDER IS THE FIX FOR A REAL DEFECT. It used to run
+  // second, after the outward reflection — which on the very first pass read a
+  // controller still in its default CLOSED state and called
+  // `toggleAttribute('open', false)`, DELETING the author's attribute before anything
+  // had read it. This effect then saw no attribute and a prop that
+  // component-register had parsed to `undefined`, concluded nothing was asked for,
+  // and left the element shut. Net result: `<kai-reasoning open>` — the plain HTML
+  // spelling the `open` prop's own doc advertises — never opened; only `default-open`
+  // did. Reading intent IN before reflecting state OUT is what makes the author's
+  // attribute survive long enough to mean something.
   createEffect(() => {
     const api = getApi();
     if (!api) return;
@@ -62,6 +63,27 @@ export function wireDisclosure<E extends { 'kai-open-change': { open: boolean }
     if (desired !== untrack(api.open)) api.setOpen(desired);
   });
 
+  // Reflect internal open → the `[open]` host attribute.
+  //
+  // Through `reflectFlag`, whose SOURCE is the controller rather than the prop — this
+  // element's truth is its internal open signal, not `props.open`. It also installs
+  // the read-back accessor, which this wiring needed and did not have: `el.open = true`
+  // used to leave `el.open === undefined`, exactly as `kai-chat`'s `loading` did
+  // (findings G-05). Returning `undefined` before the primitive has handed its
+  // controller up leaves the author's `<el open>` attribute alone.
+  reflectFlag('open', () => getApi()?.open());
+
+  // kai-open-change, fired once per change. Separate from the reflection above
+  // because it is a notification, not a reflection; both run in the same batch, so
+  // splitting them changes nothing observable about the ordering.
+  createEffect(() => {
+    const api = getApi();
+    if (!api) return;
+    const o = api.open();
+    if (prev !== undefined && prev !== o) dispatch('kai-open-change', { open: o } as E['kai-open-change']);
+    prev = o;
+  });
+
   expose({
     /** Open it programmatically (no-op while disabled). */
     show: () => { if (!flag('disabled')) getApi()?.setOpen(true); },

package/src/elements/dock.tsx

@@ -0,0 +1,215 @@
+import { untrack } from 'solid-js';
+import { defineWebComponent } from './define';
+import {
+  Dock, DockCloseGlyph, DockLauncherGlyph,
+  type DockController, type DockFocusOnOpen, type DockPosition,
+} from '../ui/dock';
+import { wireDisclosure } from './disclosure';
+
+interface Props extends Record<string, unknown> {
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute; the element still self-manages on the launcher and Escape). Set
+   *  `el.open = true`, or `<kai-dock open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Which corner the dock sits in. Logical, so `-end` follows the writing direction
+   *  and an RTL page docks on the left. Attribute: `position`. */
+  position?: DockPosition;
+  /** The widget's NAME. Derives the panel's accessible name and both launcher names
+   *  (`Open ${label}` / `Close ${label}`). Defaults to `Chat`. */
+  label?: string;
+  /** i18n override for the launcher's name while closed (default `Open ${label}`). */
+  openLabel?: string;
+  /** i18n override for the launcher's name while open (default `Close ${label}`). */
+  closeLabel?: string;
+  /** Show the unread dot. YOURS: it renders only while closed, and the dock never
+   *  writes it back. Clear it in your `kai-open-change` handler. */
+  unread?: boolean;
+  /** Disable the launcher; `show()` and `toggle()` are gated on it. */
+  disabled?: boolean;
+  /** Suppress the dock's own built-in mobile close X. Set this when your slotted
+   *  panel content supplies its own close affordance (e.g. a `<kai-chat
+   *  slot="header-end">` close button), otherwise the two stack. TRADEOFF: the
+   *  mobile panel reserves a padding band above its content so the built-in X
+   *  never paints over slotted content; that band stays reserved unless you set
+   *  this true, so only set it once your own control is actually in place.
+   *  Attribute: `hide-close`. */
+  hideClose?: boolean;
+  /** Where focus lands on open: `content` (default, the first element you slotted),
+   *  `panel`, or `none`. Attribute: `focus-on-open`. */
+  focusOnOpen?: DockFocusOnOpen;
+}
+
+/** Events fired by `<kai-dock>`. */
+interface Events {
+  /** The dock opened or closed (the launcher, Escape, a driven `open`, or a method). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-dock>` — the corner launcher: a floating button pinned to a corner of the
+ * viewport, and a panel above it holding whatever you slot in. This is the "chat
+ * bubble in the bottom-right" affordance. (Not to be confused with
+ * `<kai-prompt-dock>`, which is a recessed tray that frames a prompt INPUT and does
+ * not float, launch or open anything.)
+ *
+ * **How to use** — slot the surface, and let the dock own the button:
+ * ```html
+ * <kai-dock label="Aurora support">
+ *   <kai-chat slot="panel" chat-title="Aurora Support"></kai-chat>
+ * </kai-dock>
+ * ```
+ *
+ * The panel is content-agnostic: a `<kai-chat>`, a form, your own element. The dock
+ * never reads or types it. `slot="launcher"` / `slot="launcher-open"` swap the icon
+ * INSIDE the built-in button — the button itself is never slotted away, because the
+ * dock owns `aria-expanded`, `aria-controls`, the toggle wiring and the focus return,
+ * and a replaced button would take all four with it.
+ *
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`. It
+ * also exposes `focus()` — the panel while open, the launcher while closed.
+ *
+ * Neither `default-open` nor `open` moves focus at mount. A widget docked on someone
+ * else's page does not get to steal focus on load, which is the one place this
+ * element differs from `<kai-dialog>`, where a modal opened at mount takes focus on
+ * purpose. Opening it later does move focus, per `focus-on-open`.
+ *
+ * Closed does not mean gone: the panel keeps its layout box (`visibility: hidden` +
+ * `inert`), so a thread inside it never re-measures from zero and a reply that lands
+ * while closed is really there. `unread` is yours to set and yours to clear; the dot
+ * just stops rendering while open.
+ *
+ * Escape closes only while the dock holds focus, and is never swallowed — a widget
+ * docked on someone else's page does not get to eat their Escape. There is no focus
+ * trap; the page stays usable, which is the point of "docked".
+ *
+ * Geometry is CSS custom properties, not props: `--kai-dock-width` ·
+ * `--kai-dock-height` · `--kai-dock-inset` · `--kai-dock-gap` · `--kai-dock-radius` ·
+ * `--kai-dock-z` · `--kai-dock-launcher-size`. Narrow viewports go full-bleed by
+ * default. Parts: `launcher` · `panel` · `badge`.
+ *
+ * Put it as a body-level child: a `transform` / `filter` / `contain` ancestor makes
+ * `position: fixed` resolve against that ancestor instead of the viewport.
+ *
+ * **Migrating a hand-rolled widget onto this element changes two behaviours**, both
+ * deliberately, so check them rather than assuming a drop-in:
+ *
+ * 1. **Escape is scoped to the dock.** Hand-rolled versions of this widget typically
+ *    listen on `document` and close on any Escape anywhere on the page. This one
+ *    closes only while the dock holds focus, and never stops the event. If your app
+ *    relied on Escape-anywhere, that is now the host page's key again.
+ * 2. **The panel keeps its layout box while closed.** It is hidden with
+ *    `visibility` + `inert`, not `display: none`, and is never unmounted, so whatever
+ *    you slot in KEEPS RENDERING in the background: a stream still folds in, timers
+ *    still run, and heights stay measured. That is what makes `unread` honest and
+ *    what stops a reopened thread re-measuring from zero, but it does mean a panel
+ *    that was free while `display: none` no longer is.
+ */
+defineWebComponent<Props, Events>('kai-dock', {
+  open: undefined,
+  defaultOpen: undefined,
+  position: 'bottom-end',
+  label: 'Chat',
+  openLabel: undefined,
+  closeLabel: undefined,
+  unread: undefined,
+  disabled: undefined,
+  hideClose: undefined,
+  focusOnOpen: 'content',
+}, (props, ctx) => {
+  const { flag, element, expose, reflectFlag } = ctx;
+  let api: DockController | undefined;
+  let panel: HTMLElement | undefined;
+  let launcher: HTMLButtonElement | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle. See ./disclosure — and note it is the SOLE emitter of the
+  // event, so the primitive's onOpenChange is deliberately not wired here.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  // The other three booleans get the same read-back treatment, for the same reason:
+  // `<kai-dock unread>` parses to `undefined`, so without this the property would
+  // contradict the attribute that set it (findings G-05). Reflecting `unread` syncs
+  // the ATTRIBUTE to the prop and never changes the VALUE — the dock still never
+  // decides that a message has been read.
+  reflectFlag('unread');
+  reflectFlag('disabled');
+  reflectFlag('defaultOpen');
+  reflectFlag('hideClose');
+
+  // Seed the primitive from EITHER spelling, read once at upgrade.
+  //
+  // `open` is folded in here rather than left to wireDisclosure's effect on purpose.
+  // That effect runs a tick after mount, so `<kai-dock open>` would mount closed and
+  // then transition — which the primitive's focus effect would correctly read as a
+  // real open and steal focus with, on page load, on someone else's page. Seeding
+  // makes mount a non-event for both spellings; wireDisclosure's effect then finds
+  // the value already correct and its equality guard makes it a no-op.
+  //
+  // UNTRACKED, and that is not defensive noise — it is the fix for a real defect this
+  // element shipped for about ten minutes. A facade body runs inside the tracking
+  // scope that inserts it, so a bare `flag('open')` here subscribes the WHOLE FACADE
+  // to `open`: every toggle re-ran it, which re-created the `<Dock>`, its panel div
+  // and its controller. The visible symptoms were far away from the cause — focus
+  // never moved (each fresh focus effect was re-seeded with the current state, so it
+  // saw no transition) and `kai-open-change` never fired (wireDisclosure had latched
+  // the first, discarded controller). Reading a prop at the top level of a facade is
+  // the general trap; `untrack` is how you say "seed", and it is what makes this a
+  // seed rather than a subscription.
+  const seed = untrack(() => flag('open') || flag('defaultOpen'));
+
+  expose({
+    /** Move focus to the panel while open, or to the launcher while closed. */
+    focus: (options?: FocusOptions) =>
+      (api?.open() ? panel : launcher)?.focus(options),
+  });
+
+  // The `content` focus target: the first element assigned to the panel. Read off the
+  // live slots rather than off `element.children`, so it is the ASSIGNMENT that
+  // decides — a child whose `slot` attribute changes moves with it, and a comment or
+  // whitespace text node is not mistaken for content.
+  const contentTarget = () => {
+    const slots = panel?.querySelectorAll('slot');
+    for (const slot of Array.from(slots ?? [])) {
+      const first = (slot as HTMLSlotElement).assignedElements()[0];
+      if (first instanceof HTMLElement) return first;
+    }
+    return undefined;
+  };
+
+  return (
+    <Dock
+      defaultOpen={seed}
+      position={props.position as DockPosition}
+      label={props.label as string}
+      openLabel={props.openLabel as string | undefined}
+      closeLabel={props.closeLabel as string | undefined}
+      unread={flag('unread')}
+      disabled={flag('disabled')}
+      hideClose={flag('hideClose')}
+      focusOnOpen={props.focusOnOpen as DockFocusOnOpen}
+      contentTarget={contentTarget}
+      controllerRef={(a) => (api = a)}
+      panelRef={(el) => (panel = el)}
+      launcherRef={(el) => (launcher = el)}
+      // NATIVE SLOT FALLBACK does the whole icon chain, with no occupancy tracking and
+      // no MutationObserver: an unfilled slot renders its fallback content, and a slot
+      // nested in another slot's fallback still receives its own assignment. So
+      // `launcher-open` wins while open; failing that the consumer's `launcher` glyph
+      // STAYS rather than morphing into a built-in ✕ that clashes with their art;
+      // failing that the built-in ✕. Both defaults are the primitive's own, imported
+      // rather than re-drawn here.
+      launcher={<slot name="launcher"><DockLauncherGlyph /></slot>}
+      launcherOpen={(
+        <slot name="launcher-open">
+          <slot name="launcher"><DockCloseGlyph /></slot>
+        </slot>
+      )}
+    >
+      <slot name="panel" />
+      <slot />
+    </Dock>
+  );
+});

package/src/elements/dropdown.tsx

@@ -0,0 +1,123 @@
+import { Show } from 'solid-js';
+import { MoreHorizontal } from 'lucide-solid';
+import { Dropdown, DropdownTrigger, DropdownContent, type DropdownController } from '../ui/dropdown';
+import { renderIcon } from '../ui/icon';
+import { cn } from '../utils/cn';
+import { defineWebComponent } from './define';
+import { wireDisclosure } from './disclosure';
+
+interface Props extends Record<string, unknown> {
+  /** Built-in trigger: leading icon (a named icon like `"plus"`, an image
+   *  URL/data-URI, or text). A slotted `slot="trigger"` overrides it. */
+  triggerIcon?: string;
+  /** Built-in trigger: a text label. This is the trigger's VISIBLE text, so it is
+   *  also its accessible name, and `label` does not override it: an accessible
+   *  name that does not contain the visible text is unreachable by speech input
+   *  (WCAG 2.5.3, Label in Name). Same rule `kai-menu` follows. */
+  triggerLabel?: string;
+  /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
+  triggerIconTrailing?: string;
+  /** Accessible name for a trigger with no visible label. Ignored when
+   *  `triggerLabel` is set, which is already the visible name. It DOES name a
+   *  slotted `slot="trigger"`, which is VISUAL content with the name supplied
+   *  separately: the same two-slot distinction `kai-menu` documents. */
+  label?: string;
+  /** Stretch the trigger to the full width of its container (a block row).
+   *  Attribute: `full`. */
+  full?: boolean;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute, the menu still self-manages on click/keyboard). Set `el.open = true`,
+   *  or `<kai-dropdown open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger: click/keyboard and `show()` no longer open the menu. */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-dropdown>`. */
+interface Events {
+  /** The menu opened or closed (click, keyboard, Escape, outside-click, or a method). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-dropdown>` — a trigger plus a floating menu surface you fill yourself.
+ *
+ * The sibling of `<kai-menu>`, split by who owns the menu body: `kai-menu` renders
+ * a JSON `items` tree for you, this one gives you the surface and lets you slot
+ * ARBITRARY markup into it — the shape a framework consumer needs when the rows
+ * are their own components rather than data.
+ *
+ * ```html
+ * <kai-dropdown label="Row actions">
+ *   <span slot="trigger">&#8942;</span>
+ *   <div role="menuitem" tabindex="-1">Rename</div>
+ *   <div role="menuitem" tabindex="-1">Duplicate</div>
+ * </kai-dropdown>
+ * ```
+ *
+ * The default slot is the menu body; `trigger` is the control it anchors to. It
+ * fires `kai-open-change` with `{ open }` on every change, accepts `open` /
+ * `defaultOpen` / `disabled`, and exposes `show()` / `hide()` / `toggle()`.
+ *
+ * KEYBOARD: give each row `role="menuitem"` and it joins roving focus. ArrowUp/Down,
+ * Home/End and typeahead reach SLOTTED rows because `menuItems()` in
+ * `../ui/dropdown.tsx` walks the flat tree rather than querying the shadow tree,
+ * which contains none of the light-DOM nodes a `<slot>` projects. Rows carrying
+ * `aria-disabled="true"` are skipped.
+ */
+defineWebComponent<Props, Events>('kai-dropdown', {
+  triggerIcon: undefined,
+  triggerLabel: undefined,
+  triggerIconTrailing: undefined,
+  label: undefined,
+  full: false,
+  open: undefined,
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { flag } = ctx;
+  let api: DropdownController | undefined;
+
+  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. See ./disclosure.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  return (
+    <>
+      {/* The host shrinks to the trigger by default (UA inline); `full` makes it a
+          block whose trigger fills the width — the kai-button/kai-menu pattern. */}
+      <style>{':host([full]){display:block}'}</style>
+      <Dropdown
+        defaultOpen={flag('defaultOpen')}
+        disabled={flag('disabled')}
+        controllerRef={(a) => (api = a)}
+      >
+        <DropdownTrigger
+          class={cn(
+            'inline-flex items-center rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            props.triggerLabel
+              ? 'gap-1.5 px-2 py-1.5 text-sm font-medium text-muted-foreground hover:bg-accent hover:text-foreground'
+              : 'justify-center p-1.5 text-foreground hover:bg-muted',
+            flag('full') && 'w-full',
+          )}
+          // A visible `triggerLabel` IS the name, so `label` must not be layered
+          // over it: aria-label REPLACES the computed name, locking speech-input
+          // users out (WCAG 2.5.3). Same rule kai-menu and kai-button follow.
+          aria-label={props.triggerLabel ? undefined : (props.label ?? 'Open menu')}
+        >
+          <slot name="trigger">
+            <Show when={props.triggerIcon}>{renderIcon(props.triggerIcon, { class: 'size-4 shrink-0' })}</Show>
+            <Show when={props.triggerLabel}>{props.triggerLabel}</Show>
+            <Show when={props.triggerIconTrailing}>{renderIcon(props.triggerIconTrailing, { class: 'size-3.5 shrink-0 opacity-60' })}</Show>
+            <Show when={!props.triggerIcon && !props.triggerLabel}><MoreHorizontal class="size-4" /></Show>
+          </slot>
+        </DropdownTrigger>
+        <DropdownContent class="min-w-[10rem]">
+          <slot />
+        </DropdownContent>
+      </Dropdown>
+    </>
+  );
+});

package/src/elements/element-data-types.ts

@@ -36,6 +36,46 @@ export interface KaiSegmentedOption {
   icon?: string;
 }
 
+/** A single row of `<kai-radio-group>`.
+ *
+ *  Distinct from the Solid `RadioOption`, whose `label` and `description` are JSX
+ *  nodes: on the element both are plain strings, because an element property has to
+ *  survive being assigned from HTML/React/Vue/Svelte with no framework in between. */
+export interface KaiRadioOption {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+/** A single row of `<kai-checkbox-group>`.
+ *
+ *  Distinct from the Solid `CheckboxOption`, whose `value` is generic and whose
+ *  `label` and `description` are JSX nodes: on the element all three are plain
+ *  strings, because an element property has to survive being assigned from
+ *  HTML/React/Vue/Svelte with no framework in between. Structurally identical to
+ *  `KaiRadioOption`, and kept as its own name anyway: the two elements are free to
+ *  diverge, and a consumer typing a checkbox list should not have to import the radio
+ *  group's type to do it. */
+export interface KaiCheckboxOption {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+/** A single choice in `<kai-select>`.
+ *
+ *  Distinct from the Solid `SelectOption`, whose `value` is generic: on the element
+ *  it is a string, because a native `<option>`'s value is a string and an element
+ *  property has to survive being assigned from HTML/React/Vue/Svelte with no
+ *  framework in between. `label` defaults to `value`. */
+export interface KaiSelectOption {
+  value: string;
+  label?: string;
+  disabled?: boolean;
+}
+
 /** A single citation in `<kai-sources>`' `sources` property. Also the shape
  *  `<kai-source>` light-DOM children are parsed into. */
 export interface KaiSourceItem {