@kitn.ai/ui 0.27.0 → 0.29.0

package/src/elements/attachments.tsx

@@ -1,140 +0,0 @@
-import { For, Show } from 'solid-js';
-import { defineWebComponent } from './define';
-import {
-  Attachments,
-  Attachment,
-  AttachmentPreview,
-  AttachmentInfo,
-  AttachmentRemove,
-  AttachmentHoverCard,
-  AttachmentHoverCardTrigger,
-  AttachmentHoverCardContent,
-  AttachmentEmpty,
-  getAttachmentLabel,
-  getMediaCategory,
-  type AttachmentData,
-  type AttachmentVariant,
-} from '../components/attachments';
-
-interface Props extends Record<string, unknown> {
-  /** The attachments to render. Omit (or pass an empty array) for the empty
-   *  state, which shows `emptyText` if set and nothing otherwise. Set as a JS
-   *  property (array). Each item's `url` must be a `data:` URI or an https
-   *  URL, never `URL.createObjectURL`: a `blob:` URL previews here but the
-   *  wire encoders (`toOpenAIMessages`/`toAnthropicMessages`) refuse it. */
-  items?: AttachmentData[];
-  /** Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. */
-  variant?: AttachmentVariant;
-  /** Wrap each item in a hover card that previews its details. */
-  hoverCard?: boolean;
-  /** Show a remove button per item; clicking it fires a `kai-remove` event. */
-  removable?: boolean;
-  /** Also show the media type beneath the filename (non-grid variants). */
-  showMediaType?: boolean;
-  /** Text shown when `items` is empty. */
-  emptyText?: string;
-}
-
-/** Events fired by `<kai-attachments>`. */
-interface Events {
-  /** A remove button was clicked. */
-  'kai-remove': { id: string };
-}
-
-/**
- * `<kai-attachments>` — the exemplar for the "collapse a compound primitive to
- * ONE configurable element" pattern (Route 1). The presentation knobs that the
- * SolidJS layer expresses by composing sub-parts (`<AttachmentPreview>`,
- * `<AttachmentInfo>`, `<AttachmentHoverCard>`, `<AttachmentRemove>`) become
- * attributes/flags here:
- *
- *   - icon + label .......... `variant="inline"`
- *   - visual + hover card .... `variant="grid" hover-card`
- *   - removable chips ........ add `removable` (emits `kai-remove` → { id })
- *
- * Data in via the `items` property; the only interaction (`remove`) comes back
- * as an event. For fully-custom hover content, the SolidJS primitives remain the
- * escape hatch (a templated slot — "Route 2" — is a deliberate future add).
- */
-defineWebComponent<Props, Events>('kai-attachments', {
-  items: [],
-  variant: 'grid',
-  hoverCard: false,
-  removable: false,
-  showMediaType: false,
-  emptyText: undefined,
-}, (props, { dispatch, flag }) => {
-  const variant = () => props.variant ?? 'grid';
-  const hoverCard = () => flag('hoverCard');
-  const removable = () => flag('removable');
-  const showMediaType = () => flag('showMediaType');
-
-  return (
-    <Show
-      when={props.items?.length}
-      fallback={<Show when={props.emptyText}><AttachmentEmpty>{props.emptyText}</AttachmentEmpty></Show>}
-    >
-      <Attachments variant={variant()}>
-        <For each={props.items ?? []}>
-          {(item) => (
-            <Attachment
-              data={item}
-              onRemove={removable() ? () => dispatch('kai-remove', { id: item.id }) : undefined}
-            >
-              <Show
-                when={hoverCard()}
-                fallback={
-                  <>
-                    <AttachmentPreview />
-                    {/* Rendered for EVERY variant now. `AttachmentInfo` decides
-                        what a grid tile gets — a visible caption for a non-image
-                        tile, nothing for an image, which is the only tile that
-                        really is a self-contained visual. */}
-                    <AttachmentInfo showMediaType={showMediaType()} />
-                  </>
-                }
-              >
-                {/* The trigger carries the layout itself — a bare inline <span>
-                    collapses inline/list rows. Grid wraps just the tile (the
-                    label/details surface in the hover card instead). */}
-                <AttachmentHoverCard>
-                  <AttachmentHoverCardTrigger
-                    class={variant() === 'grid'
-                      ? 'block size-full'
-                      : `flex items-center gap-1.5${variant() === 'list' ? ' w-full' : ''}`}
-                  >
-                    <AttachmentPreview />
-                    <AttachmentInfo showMediaType={showMediaType()} />
-                  </AttachmentHoverCardTrigger>
-                  <AttachmentHoverCardContent>
-                    {/* For image attachments, preview the actual thumbnail;
-                        otherwise fall back to the label + media-type details. */}
-                    <Show
-                      when={getMediaCategory(item) === 'image' && item.type === 'file' && item.url}
-                      fallback={
-                        <>
-                          <div class="text-body font-medium">{getAttachmentLabel(item)}</div>
-                          <Show when={item.mediaType}>
-                            <div class="text-muted-foreground text-caption">{item.mediaType}</div>
-                          </Show>
-                        </>
-                      }
-                    >
-                      <img
-                        part="preview"
-                        src={item.url}
-                        alt={getAttachmentLabel(item)}
-                        class="block max-h-64 max-w-xs rounded object-contain"
-                      />
-                    </Show>
-                  </AttachmentHoverCardContent>
-                </AttachmentHoverCard>
-              </Show>
-              <AttachmentRemove />
-            </Attachment>
-          )}
-        </For>
-      </Attachments>
-    </Show>
-  );
-});

package/src/elements/audio-visualizer.tsx

@@ -1,227 +0,0 @@
-import type { JSX } from 'solid-js';
-import { AudioVisualizer, type ShaderSpec, type VisualizerVariant } from '../components/audio-visualizer';
-import type { VisualizerSize } from '../components/audio-visualizer/sizes';
-import { defineWebComponent, type WebComponentContext } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** Look to render: `bar` (default), `grid`, `radial`, `wave`, `aurora`, `custom`.
-   *  `aura` is accepted as a LiveKit-markup alias for `aurora`. Attribute: `variant`. */
-  variant?: string;
-  /** `idle` (default), `connecting`, `listening`, `thinking`, `speaking`,
-   *  `disconnected` (connection down: the dead, flat look). LiveKit's
-   *  room-lifecycle state names are accepted as aliases. Attribute: `state`. */
-  state?: string;
-  /** `icon` | `sm` | `md` (default) | `lg` | `xl`. Attribute: `size`. */
-  size?: string;
-  /** Bars to draw. Bar and radial only. Attribute: `bar-count`. */
-  barCount?: number;
-  /** Grid only: rows and columns of the (always square) grid. Attribute: `count`. */
-  count?: number;
-  /** Radial only: ring distance from center, in px. Attribute: `radius`. */
-  radius?: number;
-  /** Grid only: ring distance for the connecting animation, in cells. Attribute: `spread`. */
-  spread?: number;
-  /** Grid only: ms between scripted frames. Attribute: `interval`. */
-  interval?: number;
-  /** CSS color for the geometry, overriding the inherited `currentColor`. Attribute: `color`. */
-  color?: string;
-  /** Shader variants only: pattern density, 0..1. Attribute: `complexity`. */
-  complexity?: number;
-  /** Setting this makes the element an announced image (`role="img"`) instead of
-   *  decorative (`aria-hidden`). Attribute: `label`. */
-  label?: string;
-  /** Live microphone or WebRTC audio to analyze. JS property only. NOTE: amplitude
-   *  renders only while state is "speaking" unless listening-amplitude is set; every
-   *  other state plays its scripted animation and ignores the audio. */
-  stream?: MediaStream;
-  /** An `<audio>` or `<video>` element to tap for its audio. JS property only. NOTE:
-   *  amplitude renders only while state is "speaking" unless listening-amplitude is
-   *  set; every other state plays its scripted animation and ignores the audio. */
-  audioElement?: HTMLMediaElement;
-  /** Pre-computed levels, 0..1. Set this and no AudioContext is ever built, which is
-   *  what keeps headless/SSR rendering and browser-speech-synthesis playback (which
-   *  exposes no audio node) free of Web Audio entirely. JS property only. A new
-   *  array reference is required for each update; mutating the existing array in
-   *  place will not re-render. NOTE: amplitude renders only while state is "speaking"
-   *  unless listening-amplitude is set; every other state plays its scripted
-   *  animation and ignores the audio. */
-  bands?: number[];
-  /** Render live amplitude during the listening state as well, using the same
-   *  presentation as speaking. Off by default, which keeps LiveKit parity: amplitude
-   *  from stream, audio-element or bands renders only while state is "speaking". Set
-   *  it to show a real mic-level picture while the user is the one talking. Boolean.
-   *  Attribute: `listening-amplitude` (a bare attribute means true; reflected, so the
-   *  property reads back what the attribute set). */
-  listeningAmplitude?: boolean;
-  /** Custom fragment shader for `variant="custom"`. JS property only. */
-  shader?: ShaderSpec;
-  /** Shader variants only: keep animating while scrolled off screen. Off by default,
-   *  which stops drawing and releases the WebGL context until the element comes back
-   *  (browsers ration contexts to roughly 16 a page). Does not override
-   *  `prefers-reduced-motion`. Attribute: `animate-when-not-visible`. */
-  animateWhenNotVisible?: boolean;
-}
-
-/**
- * Parse a numeric attribute or JS property value. Attribute values arrive as
- * strings, so a missing or non-numeric one must resolve to `undefined` (which
- * the composed component then defaults itself), never `NaN`, which would
- * poison the downstream geometry (bar counts, radii, grid dimensions).
- */
-export function num(value: unknown): number | undefined {
-  if (value == null || value === '') return undefined;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : undefined;
-}
-
-/**
- * The facade's render logic, extracted to a named function so it can be
- * exercised directly in tests (a plain Solid component call, no shadow DOM
- * involved) without needing `defineWebComponent`'s browser-only custom-element
- * upgrade path. Identical to what was previously an inline arrow passed to
- * `defineWebComponent` below, plus forwarding the resolved theme (see `dark`
- * below) once that context field existed to forward.
- *
- * `ctx` is optional so the existing declarative test (which calls this
- * directly with just `props`, the way it did before `dark` existed) keeps
- * working unchanged. `defineWebComponent` always supplies a real one; the
- * `false` fallback only matters for that reduced, no-shadow-DOM call path.
- */
-export function AudioVisualizerFacade(
-  props: Props,
-  ctx?: Partial<Pick<WebComponentContext, 'dark' | 'flag' | 'reflectFlag'>>,
-): JSX.Element {
-  // Every element already resolves `theme='light'|'dark'|'auto'` against a
-  // live `prefers-color-scheme` listener in `defineWebComponent` (see
-  // `createDarkMode`), to drive the `.dark` class every element's content
-  // sits inside. A WebGL shader cannot read that class or a CSS custom
-  // property, so `<kai-audio-visualizer variant="aurora">` needs the ALREADY
-  // -RESOLVED boolean forwarded explicitly instead. Passing it through as a
-  // definite 'light'/'dark' (never 'auto') means the resolution RULE itself
-  // -- explicit wins, 'auto' follows the media query -- lives in exactly one
-  // place (`createDarkMode`); this is a plain relay, not a second
-  // implementation of that rule.
-  const dark = ctx?.dark?.() ?? false;
-
-  // `flag` is what makes a BARE attribute
-  // (`<kai-audio-visualizer animate-when-not-visible>`) mean true:
-  // component-register parses a valueless boolean attribute to `undefined`, so
-  // the prop alone cannot tell it apart from an absent one. Same helper every
-  // other boolean-attribute element uses, so the coercion rule lives in one
-  // place. The `props` fallback only covers the ctx-less direct-call path the
-  // declarative test uses, where there is no host element carrying an
-  // attribute at all.
-  const animateWhenNotVisible = ctx?.flag
-    ? ctx.flag('animateWhenNotVisible')
-    : props.animateWhenNotVisible === true;
-
-  // Same bare-attribute coercion for the second boolean on this element.
-  const listeningAmplitude = ctx?.flag
-    ? ctx.flag('listeningAmplitude')
-    : props.listeningAmplitude === true;
-
-  // Reflected (kai-dock precedent, findings G-05): without this,
-  // `<kai-audio-visualizer listening-amplitude>` would leave
-  // `el.listeningAmplitude === undefined` even while the element honours the
-  // attribute, because toggleAttribute's empty-string write-back parses to
-  // undefined. See WebComponentContext.reflectFlag. `animateWhenNotVisible`
-  // predates the reflectFlag seam and is deliberately left as-is here; if it
-  // ever earns reflection that is its own change, not a rider on this one.
-  ctx?.reflectFlag?.('listeningAmplitude');
-
-  return (
-    <AudioVisualizer
-      variant={props.variant as VisualizerVariant | undefined}
-      state={props.state as string | undefined}
-      size={props.size as VisualizerSize | undefined}
-      barCount={num(props.barCount)}
-      count={num(props.count)}
-      radius={num(props.radius)}
-      spread={num(props.spread)}
-      interval={num(props.interval)}
-      color={props.color as string | undefined}
-      complexity={num(props.complexity)}
-      label={props.label as string | undefined}
-      stream={props.stream as MediaStream | undefined}
-      audioElement={props.audioElement as HTMLMediaElement | undefined}
-      bands={props.bands as number[] | undefined}
-      listeningAmplitude={listeningAmplitude}
-      shader={props.shader as ShaderSpec | undefined}
-      animateWhenNotVisible={animateWhenNotVisible}
-      theme={dark ? 'dark' : 'light'}
-    />
-  );
-}
-
-/**
- * `<kai-audio-visualizer>` renders live audio as bars, a grid, a ring, a wave,
- * or a glowing aurora. It also animates from `state` alone with no audio at
- * all, which is what you want when the source cannot be tapped (browser
- * speech synthesis exposes no audio node).
- *
- * ```html
- * <kai-audio-visualizer variant="bar" state="speaking" size="md"></kai-audio-visualizer>
- * <kai-audio-visualizer variant="radial" size="lg" bar-count="24"></kai-audio-visualizer>
- * ```
- *
- * Audio sources and rich data are JS properties, never attributes:
- * ```js
- * el.stream = micStream            // MediaStream
- * el.audioElement = audioRef       // HTMLMediaElement
- * el.bands = [0.2, 0.8, 0.4]       // pre-computed, skips Web Audio; new array each update
- * el.shader = { fragment: glsl }   // variant="custom" only
- * ```
- *
- * Audio drives the geometry only while `state="speaking"`. Every other state
- * plays its scripted animation, so a mic stream attached during `listening`
- * changes nothing by default (LiveKit parity). Set `listening-amplitude` to
- * render real amplitude while the USER is the one talking:
- * ```html
- * <kai-audio-visualizer state="listening" listening-amplitude></kai-audio-visualizer>
- * ```
- *
- * Size tiers are fixed pixel designs, but the element never clips: in a
- * container narrower than the tier's natural footprint the whole picture
- * scales down proportionally to fit, and returns to the exact designed
- * metrics as soon as the space is back. Nothing to configure.
- *
- * The `wave`, `aurora`, and `custom` variants render through WebGL, and a
- * browser only allows about 16 live WebGL contexts per page. So a shader
- * variant scrolled off screen stops drawing and hands its context back,
- * picking up where it left off when it returns. Opt out per element when a
- * visualizer must keep running unseen:
- *
- * ```html
- * <kai-audio-visualizer variant="wave" animate-when-not-visible></kai-audio-visualizer>
- * ```
- *
- * This is a display element: no methods, no events.
- *
- * Restyle from outside via `::part(bar)` / `::part(cell)` / `::part(canvas)`,
- * the bar and cell parts each carrying `data-kai-index` and `data-kai-highlighted`.
- */
-defineWebComponent<Props>('kai-audio-visualizer', {
-  variant: 'bar',
-  state: 'idle',
-  size: 'md',
-  barCount: undefined,
-  count: undefined,
-  radius: undefined,
-  spread: undefined,
-  interval: undefined,
-  color: undefined,
-  complexity: undefined,
-  label: undefined,
-  stream: undefined,
-  audioElement: undefined,
-  bands: undefined,
-  // `undefined`, not `false`, for the same resolveFlag reason as
-  // `animateWhenNotVisible` below.
-  listeningAmplitude: undefined,
-  shader: undefined,
-  // `undefined`, not `false`: `resolveFlag` short-circuits on an explicit
-  // `false` prop value, so a `false` default would beat a bare
-  // `animate-when-not-visible` attribute if component-register ever left the
-  // default in place instead of writing `undefined` for a valueless attribute.
-  animateWhenNotVisible: undefined,
-}, AudioVisualizerFacade);

package/src/elements/autoloader.ts

@@ -1,89 +0,0 @@
-// The kai-* autoloader (opt-in, additive — the Web Awesome model).
-//
-// Include this ONE module (via a CDN/static `<script type="module">` tag) and it
-// watches the DOM for undefined kai-* elements and dynamically imports each
-// element's module on demand — so a page that only uses <kai-chat> never downloads
-// the others. The register-all bundle (@kitn.ai/ui/elements) stays the default;
-// this is the delivery for NO-BUILD / CDN / static-served pages.
-//
-// IMPORTANT — this is a CDN / static-file pattern (it resolves sibling element
-// modules relative to its own URL). It is NOT importable through a bundler: Vite /
-// webpack relocate `import.meta.url` away from the element files and cannot analyze
-// the dynamic import, so it 404s. In a BUNDLED app use per-element imports
-// (`import '@kitn.ai/ui/elements/<el>'`) or the register-all bundle. (Advanced: host
-// dist/elements/ yourself and call setAutoloaderBasePath('<url>/') before use.)
-//
-// Tag → module is resolved through the generated manifest (filenames don't always
-// equal the tag, and some modules register more than one tag), and modules are
-// fetched relative to THIS module's URL.
-import manifest from './element-manifest.json';
-
-const tagToModule: Record<string, string> = manifest.tags;
-const inFlight = new Set<string>();
-
-// Base = the directory of this module. Computed via string ops on import.meta.url
-// (NOT `new URL('./x', import.meta.url)`, which Vite rewrites into a static-asset
-// glob that resolves to undefined at runtime).
-const BASE = import.meta.url.slice(0, import.meta.url.lastIndexOf('/') + 1);
-
-/** Override where element modules are fetched from (e.g. a CDN). Call before use. */
-let baseOverride: string | null = null;
-export function setAutoloaderBasePath(path: string): void {
-  baseOverride = path.endsWith('/') ? path : path + '/';
-}
-
-async function register(tag: string): Promise<void> {
-  if (customElements.get(tag) || inFlight.has(tag)) return;
-  const file = tagToModule[tag];
-  if (!file) return; // not one of ours
-  inFlight.add(tag);
-  try {
-    await import(/* @vite-ignore */ `${baseOverride ?? BASE}${file}.js`);
-  } catch (err) {
-    inFlight.delete(tag);
-    warnOnce(tag, err);
-  }
-}
-
-// One actionable warning per session (the failure is almost always "imported
-// through a bundler" — see the header note), instead of a silent per-tag error.
-let warned = false;
-function warnOnce(tag: string, err: unknown): void {
-  if (warned) return;
-  warned = true;
-  const msg = (err as { message?: string })?.message ?? String(err);
-  // eslint-disable-next-line no-console
-  console.warn(
-    `[kai-autoloader] could not load "${tag}" (${msg}). The autoloader is a CDN / ` +
-      `static-file tool — load it from a <script type="module" src=".../@kitn.ai/ui/dist/elements/autoloader.js">. ` +
-      `It is NOT importable through a bundler. In a bundled app, register elements with per-element imports ` +
-      `(import '@kitn.ai/ui/elements/<el>') or the register-all bundle (import '@kitn.ai/ui/elements'). To drive ` +
-      `the autoloader from a bundler, host dist/elements/ and call setAutoloaderBasePath('<url>/') before use.`,
-  );
-}
-
-function discover(root: ParentNode | Element): void {
-  const tags = new Set<string>();
-  const self = (root as Element).tagName?.toLowerCase?.();
-  if (self && self in tagToModule && !customElements.get(self)) tags.add(self);
-  root.querySelectorAll?.(':not(:defined)').forEach((el) => {
-    const t = el.tagName.toLowerCase();
-    if (t in tagToModule) tags.add(t);
-  });
-  tags.forEach(register);
-}
-
-/** Start watching `root` (default: the whole document) for undefined kai-* elements. */
-export function startAutoloader(root: ParentNode = document): void {
-  discover(root as Element);
-  new MutationObserver((mutations) => {
-    for (const m of mutations)
-      for (const node of m.addedNodes)
-        if (node.nodeType === 1) discover(node as Element);
-  }).observe(document.documentElement, { childList: true, subtree: true });
-}
-
-// Self-start on import (the <script type="module"> use case). Deferred to a
-// microtask so a consumer that calls setAutoloaderBasePath() right after importing
-// (the advanced bundler-from-CDN path) takes effect before the first discovery pass.
-if (typeof document !== 'undefined') queueMicrotask(() => startAutoloader());

package/src/elements/avatar.tsx

@@ -1,33 +0,0 @@
-import { Avatar } from '../ui/avatar';
-import { defineWebComponent } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** Image URL/data-URI. When absent, the `fallback` initials show instead. */
-  src?: string;
-  /** Alt text for the image. Defaults to `fallback`. */
-  alt?: string;
-  /** Short text shown when there's no image, usually initials (e.g. "JD", "AI"). */
-  fallback?: string;
-  /** Size token: `sm` | `md` (default) | `lg`. */
-  size?: 'sm' | 'md' | 'lg';
-}
-
-/**
- * `<kai-avatar>` — a person/entity avatar: a rounded image that falls back to
- * initials when there's no `src`. This is an *identity* badge (the thing next to
- * a message or in a conversation list), not a generic icon — for a glyph, use an
- * `icon` prop on another element.
- *
- * ```html
- * <kai-avatar src="/me.jpg" fallback="JD"></kai-avatar>
- * <kai-avatar fallback="AI" size="sm"></kai-avatar>
- * ```
- */
-defineWebComponent<Props>('kai-avatar', {
-  src: undefined,
-  alt: undefined,
-  fallback: '',
-  size: 'md',
-}, (props) => (
-  <Avatar src={props.src} alt={props.alt} fallback={props.fallback ?? ''} size={props.size ?? 'md'} />
-));

package/src/elements/badge.tsx

@@ -1,32 +0,0 @@
-import { Badge } from '../ui/badge';
-import { defineWebComponent } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** `default` (muted pill) · `count` (compact number badge) · `citation`
-   *  (filled primary, for inline citation markers). Defaults to `default`. */
-  variant?: 'default' | 'count' | 'citation';
-}
-
-/**
- * `<kai-badge>` — a small pill for labels, status, counts, or citation markers.
- * Put the content as light-DOM text.
- *
- * ```html
- * <kai-badge>Beta</kai-badge>
- * <kai-badge variant="count">3</kai-badge>
- * <kai-badge variant="citation">1</kai-badge>
- * ```
- * Restyle via `::part(badge)`.
- */
-defineWebComponent<Props>('kai-badge', {
-  variant: 'default',
-}, (props) => (
-  <>
-    {/* Base sets `:host{display:block}`; a badge/pill flows inline with text and
-        beside sibling badges, so inline-flex like kai-button. */}
-    <style>{':host{display:inline-flex}'}</style>
-    <Badge variant={props.variant ?? 'default'} part="badge">
-      <slot />
-    </Badge>
-  </>
-));

package/src/elements/button.tsx

@@ -1,149 +0,0 @@
-import { Show } from 'solid-js';
-import { Button } from '../ui/button';
-import { renderIcon } from '../ui/icon';
-import { defineWebComponent } from './define';
-import { createSlotText } from './slot-text';
-
-interface Props extends Record<string, unknown> {
-  /** Visual style. `default` (filled), `subtle` (muted text, hover tint, the
-   *  toolbar icon look), `ghost` (transparent, hover fill), `outline`, or
-   *  `destructive`. Defaults to `default`. */
-  variant?: 'default' | 'subtle' | 'ghost' | 'outline' | 'destructive';
-  /** Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` /
-   *  `md` / `lg` size text buttons. Defaults to `md`. */
-  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
-  /** Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI,
-   *  or plain text. Renders before any slotted label. */
-  icon?: string;
-  /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
-  iconTrailing?: string;
-  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored
-   *  when you slot visible text, which already names the button. An `aria-label`
-   *  on top of visible text REPLACES that name rather than adding to it, so a
-   *  button reading "Save" that answers to "Submit" is unusable by speech input
-   *  (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm`
-   *  size hides the slot, which makes the button icon-only whatever you slotted,
-   *  so `label` is what names it there. */
-  label?: string;
-  /** Disable the button (non-interactive, dimmed). */
-  disabled?: boolean;
-  /** Stretch the button to the full width of its container (a block button),
-   *  e.g. a card CTA or a stacked action. Attribute: `full`. */
-  full?: boolean;
-  /** Justify the button's content: `start`, `center` (default), or `end`.
-   *  Combine with `full` for a full-width, left-aligned button. */
-  align?: 'start' | 'center' | 'end';
-  /** Native button `type`. Defaults to `button` (so it never submits a form). */
-  type?: 'button' | 'submit' | 'reset';
-}
-
-/** Events fired by `<kai-button>`. */
-interface Events {
-  /** The button was activated (pointer or keyboard). Carries no detail. The
-   *  native `click` also bubbles (composed) for consumers who prefer it. */
-  'kai-click': void;
-}
-
-/**
- * `<kai-button>` — the kit's button as a drop-in element, so consumers compose
- * polished, theme-aware controls instead of hand-rolling `<button>` + inline
- * hover styles. Put the label as light-DOM text; use `icon` for a leading glyph
- * and `label` to name an icon-only button.
- *
- * ```html
- * <kai-button variant="subtle" size="icon" icon="mic" label="Voice input"></kai-button>
- * <kai-button variant="ghost" icon-trailing="chevron-down">High</kai-button>
- * <kai-button>Send</kai-button>
- * <kai-button label="Ship"><svg slot="icon" viewBox="0 0 24 24">…</svg></kai-button>
- * ```
- *
- * The `icon` prop renders a curated/URL icon; for anything else, slot your own
- * inline SVG via `slot="icon"` (it wins over `icon`). Restyle via `::part(button)`.
- * Emits `kai-click`.
- */
-defineWebComponent<Props, Events>('kai-button', {
-  variant: 'default',
-  size: 'md',
-  icon: undefined,
-  iconTrailing: undefined,
-  label: undefined,
-  disabled: false,
-  full: false,
-  align: 'center',
-  type: 'button',
-}, (props, { dispatch, flag, element, expose }) => {
-  // `icon` / `icon-sm` are square, icon-ONLY sizes: suppress the text label and
-  // trailing icon so a stray label doesn't get cramped into the square (the
-  // `label` prop still names it for assistive tech).
-  const iconOnly = () => props.size === 'icon' || props.size === 'icon-sm';
-
-  // Slotted text names the button by itself (name-from-contents reaches through
-  // the slot), so `label` must NOT be emitted on top of it: aria-label REPLACES
-  // the computed name, and a name that disagrees with the visible text locks
-  // speech-input users out of the control (WCAG 2.5.3). This is what the `label`
-  // doc has always promised, and what `kai-checkpoint` already does.
-  //
-  // `flatten` so a consumer who wraps <kai-button> in their own component and
-  // forwards a <slot> still counts as having visible text. Safe here because the
-  // default slot has no fallback content — see createSlotText.
-  const slotted = createSlotText({ flatten: true });
-
-  // The name to emit, or nothing. An `icon`/`icon-sm` size does not render the
-  // default slot at all, so whatever was slotted is INVISIBLE and `label` is the
-  // only name available — dropping it there would leave icon buttons nameless,
-  // which is the worse bug.
-  const ariaLabel = () => (!iconOnly() && slotted.hasText() ? undefined : props.label);
-
-  // ── Imperative API (instance methods on the host) ──────────────────────────
-  // The real <button> lives in the shadow root, so native focus()/blur()/click()
-  // on the host hit the wrapper, not the control. Forward to the inner button.
-  // These shadow the inherited HTMLElement methods — intended; expose() uses
-  // defineProperty so the override sticks. No collision with the props above.
-  expose({
-    /** Focus the inner `<button>` (host.focus() would focus the wrapper). */
-    focus: (options?: FocusOptions) =>
-      element.shadowRoot?.querySelector('button')?.focus(options),
-    /** Blur the inner `<button>`. */
-    blur: () => element.shadowRoot?.querySelector('button')?.blur(),
-    /** Programmatically activate the button. Runs the same path as a user
-     *  click and fires kai-click. Forwarding to the inner button means
-     *  `disabled` is respected automatically. */
-    click: () => element.shadowRoot?.querySelector('button')?.click(),
-  });
-  return (
-    <>
-      {/* The host shrinks to the label by default (inline-flex), so a text button
-          is only as wide as its content — until a parent stretches it. A text
-          button's inner control is w-full, so when the host IS stretched (a flex
-          column with items-stretch, e.g. a card's collapsed footer, or an explicit
-          `full`) the button fills it. `full` forces that standalone (a block CTA).
-          Icon buttons stay square (no w-full). */}
-      <style>{':host{display:inline-flex}:host([full]){display:block}'}</style>
-    <Button
-      part="button"
-      variant={props.variant ?? 'default'}
-      size={props.size ?? 'md'}
-      align={props.align ?? 'center'}
-      full={flag('full') || !iconOnly()}
-      type={props.type ?? 'button'}
-      disabled={flag('disabled')}
-      aria-label={ariaLabel()}
-      onClick={() => dispatch('kai-click')}
-    >
-      {/* Leading icon: a slotted SVG (slot="icon") wins — drop in any icon
-          library or your own; otherwise the `icon` prop renders a curated/URL one. */}
-      <slot name="icon">
-        <Show when={props.icon}>
-          {renderIcon(props.icon, { class: 'size-4 shrink-0', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}
-        </Show>
-      </slot>
-      <Show when={!iconOnly()}>
-        <slot ref={slotted.ref} />
-      </Show>
-      <Show when={props.iconTrailing && !iconOnly()}>
-        {renderIcon(props.iconTrailing, { class: 'size-4 shrink-0 opacity-60', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}
-      </Show>
-    </Button>
-    </>
-  );
-});