@kitn.ai/ui 0.16.0 → 0.18.0

package/src/elements/coachmark.tsx

@@ -0,0 +1,90 @@
+import { defineWebComponent } from './define';
+import { Coachmark, type CoachmarkController } from '../components/coachmark';
+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). Set `el.open = true`, or
+   *  `<kai-coachmark open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** The bold title. Named `headline` because `title` collides with the global
+   *  `HTMLElement.title` attribute (it throws at registration). */
+  headline?: string;
+  /** A small badge pill beside the headline (e.g. "New"). */
+  badge?: string;
+  /** Floating placement relative to the anchor (default `bottom`). */
+  placement?: string;
+  /** Color tone: `primary` (default, theme accent), `info` (blue), `success`
+   *  (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues. */
+  tone?: 'primary' | 'info' | 'success' | 'warning' | 'error';
+  /** Render the arrow that points at the anchor (default `true`). Set
+   *  `arrow="false"` for a plain bubble with no pointer. */
+  arrow?: boolean;
+}
+
+/** Events fired by `<kai-coachmark>`. */
+interface Events {
+  /** The × dismiss button was pressed. The consumer records that this hint was
+   *  seen so it won't show again. */
+  'kai-dismiss': Record<string, never>;
+  /** The coachmark opened or closed (a method, the ×, or a driven `open`). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-coachmark>` — an anchored onboarding hint bubble with an arrow. It WRAPS
+ * a trigger (the default slot) and points a primary-colored bubble at it: a small
+ * `badge` pill, a bold `headline`, the `content` slot body, and a dismiss ×.
+ *
+ * ```html
+ * <kai-coachmark default-open headline="Cowork has a new home" badge="New">
+ *   <button>Cowork</button>
+ *   <span slot="content">Chat with Claude or switch to Cowork from here.</span>
+ * </kai-coachmark>
+ * <script type="module">
+ *   document.querySelector('kai-coachmark')
+ *     .addEventListener('kai-dismiss', () => localStorage.setItem('cowork-hint', 'seen'));
+ * </script>
+ * ```
+ *
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
+ * Parts: `bubble` · `arrow` · `badge` · `title` · `dismiss`.
+ */
+defineWebComponent<Props, Events>('kai-coachmark', {
+  open: undefined,
+  defaultOpen: undefined,
+  headline: undefined,
+  badge: undefined,
+  placement: undefined,
+  tone: undefined,
+  arrow: true,
+}, (props, ctx) => {
+  const { flag, dispatch } = ctx;
+  let api: CoachmarkController | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle. See ./disclosure. This is the SOLE emitter of kai-open-change.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  // headline/badge are scalar string props (NOT slots) — pass through directly so
+  // the component's own `Show when={…}` gating drives whether each region renders.
+  // The body is the `content` slot; an empty `<slot>` renders nothing.
+  return (
+    <Coachmark
+      defaultOpen={flag('defaultOpen')}
+      arrow={flag('arrow')}
+      placement={props.placement as never}
+      tone={props.tone as 'primary' | 'info' | 'success' | 'warning' | 'error' | undefined}
+      headline={props.headline as string | undefined}
+      badge={props.badge as string | undefined}
+      content={<slot name="content" />}
+      controllerRef={(a) => (api = a)}
+      onDismiss={() => dispatch('kai-dismiss', {})}
+    >
+      <slot />
+    </Coachmark>
+  );
+});

package/src/elements/command.tsx

@@ -0,0 +1,209 @@
+import { createEffect, createMemo, createSignal, createUniqueId, on } from 'solid-js';
+import { CommandList, type CommandGroup } from '../ui/command';
+import { defineWebComponent } from './define';
+
+/**
+ * A single command/mention item for `<kai-command>`.
+ *
+ * Set `items` as a JS property (array ref) — not an HTML attribute.
+ */
+export interface KaiCommandItem {
+  /** Unique identifier emitted in `kai-select`. */
+  id: string;
+  /** Display name shown in the list row. */
+  label: string;
+  /** Named icon (e.g. "search"), image URL / data-URI, or plain text. */
+  icon?: string;
+  /** Muted supplementary text (e.g. a file path or a short description). */
+  description?: string;
+  /** Optional keyboard shortcut shown as right-aligned key caps; uses the
+   *  kai-kbd `keys` syntax (e.g. "Mod+K", "Alt+1"). */
+  shortcut?: string;
+  /** Group name that buckets this item under a section header. */
+  group?: string;
+}
+
+interface Props extends Record<string, unknown> {
+  /** Flat list of items. Set as a JS property — not an HTML attribute. */
+  items?: KaiCommandItem[];
+  /** Placeholder text for the search input. */
+  placeholder?: string;
+  /** Label shown when no items match the current query. */
+  emptyLabel?: string;
+}
+
+interface Events {
+  /** Fired when the user selects an item (click or Enter). */
+  'kai-select': { id: string };
+  /** Fired on every keystroke in the search input. */
+  'kai-query-change': { value: string };
+  /** Fired when the highlighted/active item changes — via Arrow keys or when
+   *  filtering re-clamps the active row. `id` is the newly active item's id, or
+   *  `undefined` when no item is active (e.g. the filtered list is empty). Lets a
+   *  host preview the active item without committing a selection. */
+  'kai-active-change': { id: string | undefined };
+}
+
+/**
+ * `<kai-command>` — a grouped, filterable command/mention palette.
+ *
+ * Set the `items` property in JavaScript (array, not attribute), listen for
+ * `kai-select` to know which item was picked, and `kai-query-change` to mirror
+ * the search query to your own logic (e.g. async server-side filtering).
+ *
+ * ```html
+ * <kai-command placeholder="Search…"></kai-command>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const el = document.querySelector('kai-command');
+ *   el.items = [
+ *     { id: 'foo', label: 'Foo', icon: 'search', shortcut: 'Mod+K', group: 'Recent' },
+ *   ];
+ *   el.addEventListener('kai-select', (e) => console.log(e.detail.id));
+ * </script>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-command', {
+  items: undefined,
+  placeholder: undefined,
+  emptyLabel: undefined,
+}, (props, { dispatch, element, expose }) => {
+  const listboxId = createUniqueId();
+  const [query, setQuery] = createSignal('');
+  const [activeId, setActiveId] = createSignal<string | undefined>(undefined);
+
+  /** Items cast to the correct type; defaults to empty array. */
+  const allItems = () => (props.items as KaiCommandItem[] | undefined) ?? [];
+
+  /** Items filtered by the current query (label or description, case-insensitive). */
+  const filteredItems = createMemo<KaiCommandItem[]>(() => {
+    const q = query().toLowerCase();
+    if (!q) return allItems();
+    return allItems().filter(
+      (item) =>
+        item.label.toLowerCase().includes(q) ||
+        (item.description?.toLowerCase().includes(q) ?? false),
+    );
+  });
+
+  /** Filtered items grouped by `group`, preserving first-appearance order. */
+  const groupedItems = createMemo<CommandGroup[]>(() => {
+    const groups: CommandGroup[] = [];
+    for (const item of filteredItems()) {
+      let g = groups.find((x) => x.group === item.group);
+      if (!g) {
+        g = { group: item.group, items: [] };
+        groups.push(g);
+      }
+      g.items.push({ id: item.id, label: item.label, icon: item.icon, description: item.description, shortcut: item.shortcut });
+    }
+    return groups;
+  });
+
+  /** Flat ordered array of filtered item ids — used for keyboard navigation. */
+  const flatIds = createMemo<string[]>(() => filteredItems().map((item) => item.id));
+
+  /** Clamp/reset activeId when the filtered list changes. */
+  createEffect(() => {
+    const ids = flatIds();
+    const current = activeId();
+    if (!current || !ids.includes(current)) {
+      setActiveId(ids[0]);
+    }
+  });
+
+  /** Mirror the active/highlighted item out as `kai-active-change` whenever it
+   *  changes (Arrow keys or a filter-driven re-clamp). Skips the initial settle
+   *  by only firing when the value actually differs from the previous one. */
+  createEffect(on(activeId, (id, prev) => {
+    if (id !== prev) dispatch('kai-active-change', { id });
+  }));
+
+  function select(id: string) {
+    dispatch('kai-select', { id });
+  }
+
+  function handleInput(e: Event) {
+    const value = (e.currentTarget as HTMLInputElement).value;
+    setQuery(value);
+    dispatch('kai-query-change', { value });
+  }
+
+  function handleKeyDown(e: KeyboardEvent) {
+    const ids = flatIds();
+    if (!ids.length) return;
+
+    const current = activeId();
+    const idx = current !== undefined ? ids.indexOf(current) : -1;
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setActiveId(ids[(idx + 1) % ids.length]);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setActiveId(ids[(idx - 1 + ids.length) % ids.length]);
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      const id = activeId();
+      if (id !== undefined) select(id);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      setQuery('');
+      dispatch('kai-query-change', { value: '' });
+    }
+  }
+
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // Counterpart to the kai-* events: lets a host make the palette type-ready and
+  // reset its query without reaching into the shadow root.
+  expose({
+    /** Focus the search combobox input inside the shadow root so the palette is
+     *  type-ready on demand (Shadow-DOM autofocus is unreliable, so hosts call
+     *  this after opening the palette). */
+    focus: (options?: FocusOptions) =>
+      element.shadowRoot
+        ?.querySelector<HTMLInputElement>('input[role="combobox"], input')
+        ?.focus(options),
+    /** Blur the focused search input. */
+    blur: () =>
+      element.shadowRoot
+        ?.querySelector<HTMLInputElement>('input[role="combobox"], input')
+        ?.blur(),
+    /** Reset the search query to empty — re-showing all items — and fire
+     *  `kai-query-change` with `''`. Mirrors the Escape-key behavior. */
+    clear: () => {
+      setQuery('');
+      dispatch('kai-query-change', { value: '' });
+    },
+  });
+
+  return (
+    <div class="flex flex-col overflow-hidden">
+      <div class="border-b border-border px-3 py-2">
+        <input
+          type="text"
+          role="combobox"
+          aria-expanded="true"
+          aria-haspopup="listbox"
+          aria-autocomplete="list"
+          aria-controls={listboxId}
+          value={query()}
+          placeholder={(props.placeholder as string | undefined) ?? 'Search…'}
+          class="w-full bg-transparent text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none"
+          onInput={handleInput}
+          onKeyDown={handleKeyDown}
+        />
+      </div>
+      <div class="overflow-y-auto max-h-[320px]">
+        <CommandList
+          id={listboxId}
+          ariaLabel="Results"
+          groups={groupedItems()}
+          activeId={activeId()}
+          onSelect={select}
+          emptyLabel={(props.emptyLabel as string | undefined) ?? 'No results'}
+        />
+      </div>
+    </div>
+  );
+});

package/src/elements/compare.tsx

@@ -0,0 +1,110 @@
+import { defineWebComponent } from './define';
+import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
+import { ResponseCompare, type CompareLayout } from '../components/response-compare';
+import type {
+  ResponseCompareData,
+  CompareSelection,
+  ResponseCompareController,
+} from '../components/response-compare';
+
+interface Props extends Record<string, unknown> {
+  /** The compare definition (prompt + the two candidates). Set as a JS PROPERTY:
+   *  `el.data = { prompt, candidates: [A, B], collapse? }`. Import
+   *  `ResponseCompareData` from `@kitn.ai/ui` for the full shape. */
+  data?: Record<string, unknown>;
+  /** Stable id correlating every emitted event. Attribute: `compare-id`. */
+  compareId?: string;
+  /** Re-hydrate / control the user's pick. Set as a JS PROPERTY:
+   *  `el.selection = { chosenId, rejectedIds }`. Renders the collapsed winner. */
+  selection?: Record<string, unknown>;
+  /** Layout: `'auto'` (default — columns when wide, tabs when narrow, by CONTAINER
+   *  width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`. */
+  layout?: CompareLayout;
+  /** Prose/text size for the rendered candidates. Attribute: `prose-size`. */
+  proseSize?: ProseSize;
+  /** Shiki theme for code blocks in the candidates. Attribute: `code-theme`. */
+  codeTheme?: string;
+  /** Whether code blocks are syntax-highlighted. Attribute: `code-highlight`. */
+  codeHighlight?: boolean;
+}
+
+interface Events extends Record<string, unknown> {
+  /** The user committed a pick. `detail` = `{ chosenId, rejectedIds, at }`. */
+  'kai-compare-select': CompareSelection;
+  /** Both candidates have settled and the pick is live. */
+  'kai-ready': { compareId: string };
+  /** The definition was unusable. */
+  'kai-error': { compareId: string; message: string };
+}
+
+/**
+ * `<kai-compare>` — a **dual-response comparison** (set via the `data` property):
+ * two assistant candidates for the same prompt, rendered side-by-side (or as tabs),
+ * each exactly like an assistant message (reasoning + tools + attachments +
+ * markdown). The user **picks** the better one — a COMMIT, not a Submit — which
+ * fires a non-bubbling **`kai-compare-select`** CustomEvent off the host
+ * (`{ chosenId, rejectedIds:[other], at }`) for the consumer to send a
+ * `(prompt, chosen, rejected)` preference pair. The card optimistically collapses
+ * to the chosen candidate. Single-shot.
+ *
+ * Both candidates can stream (push a fresh `data` reference per chunk); the pick is
+ * disabled with a per-column shimmer until BOTH settle, then `kai-ready` fires. The
+ * columns are a WAI-ARIA radiogroup with roving tabindex (Arrow keys move A↔B,
+ * Enter/Space picks). `kai-error` fires for a malformed definition. Isolated in
+ * Shadow DOM; theme-aware via the shared tokens.
+ */
+defineWebComponent<Props, Events>(
+  'kai-compare',
+  {
+    data: undefined,
+    compareId: undefined,
+    selection: undefined,
+    layout: 'auto',
+    proseSize: undefined,
+    codeTheme: undefined,
+    codeHighlight: undefined,
+  },
+  (props, { element, dispatch, expose }) => {
+    const compareId = (): string => props.compareId ?? (element.id || 'kai-compare');
+    // Inherit the shadow-root portal mount from the outer ChatConfig that
+    // defineWebComponent installs, so candidate-body overlays (hover cards,
+    // tooltips) stay inside the shadow root.
+    const outer = useChatConfig();
+
+    // ── Imperative API (instance methods on the host) ──────────────────────────
+    // Pattern C: ResponseCompare owns the pick + roving-focus state and hands up a
+    // controller; the facade captures it and exposes delegating methods. The
+    // component's own callbacks still fire (select → onSelect → kai-compare-select).
+    let controller: ResponseCompareController | undefined;
+    expose({
+      /** Programmatically commit a pick by candidate id — same path as the "Pick
+       *  this" button: fires kai-compare-select and optimistically collapses
+       *  (single-shot; inert while streaming or already resolved). `select` does
+       *  NOT collide with the `selection` prop (distinct identifier). */
+      select: (candidateId: string) => controller?.select(candidateId),
+      /** Focus the current roving tab stop (the focused candidate's "Pick this"
+       *  radio) so a consumer can move keyboard focus into the radiogroup. */
+      focus: (options?: FocusOptions) => controller?.focus(options),
+    });
+
+    return (
+      <ChatConfig
+        proseSize={props.proseSize}
+        codeTheme={props.codeTheme}
+        codeHighlight={props.codeHighlight}
+        portalMount={outer.portalMount()}
+      >
+        <ResponseCompare
+          data={props.data as ResponseCompareData | undefined}
+          compareId={compareId()}
+          selection={props.selection as CompareSelection | undefined}
+          layout={(props.layout as CompareLayout | undefined) ?? 'auto'}
+          controllerRef={(c) => (controller = c)}
+          onSelect={(sel) => dispatch('kai-compare-select', sel)}
+          onReady={() => dispatch('kai-ready', { compareId: compareId() })}
+          onError={(message) => dispatch('kai-error', { compareId: compareId(), message })}
+        />
+      </ChatConfig>
+    );
+  },
+);