@kitn.ai/ui 0.17.0 → 0.18.1

package/src/elements/card.tsx

@@ -1,40 +1,133 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
-import { Card } from '../components/card';
+import { Card, type CardAppearance, type CardOrientation } from '../ui/card';
 
 interface Props extends Record<string, unknown> {
-  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
-  heading?: string;
-  /** Supporting text under the heading. Attribute: `description`. */
-  description?: string;
-  /** When set, the card renders its inline error state instead of the body.
-   *  Attribute: `error-message`. */
-  errorMessage?: string;
-  /** Compact spacing for dense lists. Attribute: `dense`. */
+  /** Surface treatment: `outlined` (default) | `filled` | `plain` | `accent`.
+   *  Attribute: `appearance`. */
+  appearance?: CardAppearance;
+  /** `vertical` (default, media on top) | `horizontal` (media at the start) |
+   *  `responsive` (horizontal when the card's container is wide enough, else
+   *  vertical — a container query on the card's own width). Attribute: `orientation`. */
+  orientation?: CardOrientation;
+  /** The card width below which a `responsive` card collapses to vertical and the
+   *  footer actions stack. A CSS length; default `28rem`. Attribute: `collapse`. */
+  collapse?: string;
+  /** Tighter spacing for dense lists. Attribute: `dense`. */
   dense?: boolean;
+  /** Show a close (×) that hides the card and emits `kai-dismiss`. Attribute:
+   *  `dismissible`. Off by default. */
+  dismissible?: boolean;
+  /** Render the whole card as a link. Attribute: `href`. Wins over `clickable`. */
+  href?: string;
+  /** `target` for the `href` anchor. Attribute: `target`. */
+  target?: string;
+  /** `rel` for the `href` anchor. Attribute: `rel`. */
+  rel?: string;
+  /** Make the whole card a button (`role="button"`, Enter/Space, hover affordance)
+   *  that emits `kai-card-click`. Attribute: `clickable`. Ignored when `href` is set. */
+  clickable?: boolean;
 }
 
+/** Events fired by `<kai-card>`. */
+interface Events {
+  /** The card was dismissed via its × (it also hides itself). */
+  'kai-dismiss': void;
+  /** A `clickable`/`href` card was activated (click, or Enter/Space). */
+  'kai-card-click': void;
+}
+
+/** The named slots whose occupancy gates a card region. An empty `<slot>` is
+ *  always a truthy node, so the facade tracks which are actually filled and only
+ *  passes those regions to the primitive. */
+const SLOT_NAMES = ['media', 'header', 'header-actions', 'footer', 'footer-actions'] as const;
+type SlotName = (typeof SLOT_NAMES)[number];
+
 /**
- * `<kai-card>` — the shared, presentational card chrome every native card composes
- * from: an optional media region (`slot="media"`), a heading + description, a body
- * (default slot), an actions footer (`slot="actions"`), and one consistent inline
- * **error** state (`error-message`). It emits **no** events and reads no context —
- * it is chrome only; the cards that compose it (e.g. `<kai-form>`) own the contract
- * interaction. Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ * `<kai-card>` — the kit's presentational card, modeled on the WebAwesome card:
+ * ONE element whose flexibility comes from a few structural slots, `appearance`
+ * and `orientation` variants, themeable `::part`s, and a single
+ * `--kai-card-spacing` knob. The title/description are not slots — they are body
+ * (default slot) or `slot="header"` content you mark up yourself.
+ *
+ * Slots: `media` (full-bleed image/video/illustration), `header` + `header-actions`,
+ * the default slot (body), `footer` + `footer-actions`.
+ *
+ * Behaviors (all OFF by default): `dismissible` (× → `kai-dismiss`), and
+ * `href`/`clickable` (whole card a link/button → `kai-card-click`). A
+ * clickable/href card must NOT also contain action buttons.
+ *
+ * ```html
+ * <kai-card appearance="filled" dismissible>
+ *   <div slot="media"><img src="…" alt="…" /></div>
+ *   <h3 slot="header">2× usage</h3>
+ *   Do more with a higher session limit.
+ *   <kai-button slot="footer-actions">Start task</kai-button>
+ * </kai-card>
+ * ```
  */
-defineWebComponent<Props>('kai-card', {
-  heading: undefined,
-  description: undefined,
-  errorMessage: undefined,
+defineWebComponent<Props, Events>('kai-card', {
+  appearance: 'outlined',
+  orientation: 'vertical',
+  collapse: '28rem',
   dense: false,
-}, (props, { flag }) => (
-  <Card
-    heading={props.heading}
-    description={props.description}
-    errorMessage={props.errorMessage}
-    dense={flag('dense')}
-    media={<slot name="media" />}
-    actions={<slot name="actions" />}
-  >
-    <slot />
-  </Card>
-));
+  dismissible: false,
+  href: undefined,
+  target: undefined,
+  rel: undefined,
+  clickable: false,
+}, (props, { element, dispatch, flag }) => {
+  // Track which named slots are filled, plus whether the default slot (body) has
+  // any content. Re-read on child mutations so streamed/late content lights up
+  // its region. An unfilled region is never rendered (no stray padding/divider).
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({
+    'media': false, 'header': false, 'header-actions': false, 'footer': false, 'footer-actions': false,
+  });
+  const [hasBody, setHasBody] = createSignal(false);
+
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+      // Body = any direct child without a slot attribute (element, or non-blank text).
+      setHasBody(
+        Array.from(element.childNodes).some(
+          (n) =>
+            (n.nodeType === Node.ELEMENT_NODE && !(n as Element).hasAttribute('slot')) ||
+            (n.nodeType === Node.TEXT_NODE && (n.textContent ?? '').trim() !== ''),
+        ),
+      );
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, characterData: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const region = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  return (
+    <Card
+      appearance={props.appearance as CardAppearance}
+      orientation={props.orientation as CardOrientation}
+      collapse={props.collapse as string}
+      dense={flag('dense')}
+      dismissible={flag('dismissible')}
+      href={props.href}
+      target={props.target}
+      rel={props.rel}
+      clickable={flag('clickable')}
+      onDismiss={() => dispatch('kai-dismiss')}
+      onCardClick={() => dispatch('kai-card-click')}
+      media={region('media')}
+      header={region('header')}
+      headerActions={region('header-actions')}
+      footer={region('footer')}
+      footerActions={region('footer-actions')}
+      hasBody={hasBody()}
+    >
+      <slot />
+    </Card>
+  );
+});

package/src/elements/cards.tsx

@@ -4,10 +4,10 @@
 // `kai-card` events through an optional `policy`. The raw events keep bubbling past
 // <kai-cards> (composed) so document-level listeners still work. Unknown types render
 // the Solid CardFallback inline and emit a contract `error`.
-import { For, Show, createEffect, onCleanup, onMount, type JSX } from 'solid-js';
+import { For, Show, createEffect, createSignal, on, onCleanup, onMount, type JSX } from 'solid-js';
 import { Dynamic } from 'solid-js/web';
 import { defineWebComponent } from './define';
-import type { CardEnvelope, CardEvent, CardPolicy } from '../primitives/card-contract';
+import type { CardEnvelope, CardEvent, CardPolicy, CardResolution } from '../primitives/card-contract';
 import { CARD_EVENT_NAME, emitCardEvent, routeCardEvent } from '../primitives/card-routing';
 import { mergeCardTags } from '../primitives/card-registry';
 import { CardFallback } from '../components/card-fallback';
@@ -30,6 +30,33 @@ interface Props extends Record<string, unknown> {
   policy?: CardPolicy;
 }
 
+/** Events fired by `<kai-cards>`. */
+interface Events {
+  /** A child card transitioned to a resolved/deferred state (an action was chosen,
+   *  a form/tasks submission landed, or it was dismissed) — re-emitted off the host
+   *  as a non-bubbling convenience event so a consumer can observe resolution
+   *  centrally without diffing the cards array. `detail` = `{ cardId, resolution }`.
+   *  (A `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire
+   *  this — observe reopen via the underlying bubbling `kai-card` event.) */
+  'kai-card-resolved': { cardId: string; resolution: CardResolution };
+}
+
+/** Map a terminal/deferred child CardEvent to the CardResolution it produces. Returns
+ *  `undefined` for events that don't resolve a card (ready/error/etc.) and for
+ *  `reopen` (which clears resolution → no CardResolution to convey). */
+function resolutionFromEvent(e: CardEvent): CardResolution | undefined {
+  switch (e.kind) {
+    case 'action':
+      return { kind: 'action', action: e.action, payload: e.payload };
+    case 'submit':
+      return { kind: 'submit', data: e.data };
+    case 'dismiss':
+      return { kind: 'dismissed' };
+    default:
+      return undefined;
+  }
+}
+
 /** A single resolved child: a known kai-* tag (props set imperatively) or the fallback. */
 function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string; emit: (e: CardEvent) => void }): JSX.Element {
   let ref: HTMLElement | undefined;
@@ -41,6 +68,9 @@ function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string;
     if (props.envelope.title != null) (ref as unknown as { heading: string }).heading = props.envelope.title;
     (ref as unknown as { resolution: unknown }).resolution = props.envelope.resolution;
     ref.setAttribute('theme', props.theme);
+    // Stable, queryable id so the host's getCard()/resolve() can find this child
+    // node without relying on the (private, scalar-only) cardId property reflecting.
+    ref.setAttribute('data-card-id', props.envelope.id);
   });
   // Hoist the unknown-type error emit to onMount to avoid side-effect-in-JSX lint issue
   // and to ensure exactly one error fires.
@@ -59,20 +89,64 @@ function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string;
   );
 }
 
-defineWebComponent<Props>(
+defineWebComponent<Props, Events>(
   'kai-cards',
   { cards: undefined, types: undefined, policy: undefined },
-  (props, { element }) => {
+  (props, { element, dispatch, expose }) => {
+    // Local working copy of the card list. The `cards` PROP still drives rendering
+    // (a new prop array re-seeds this), but holding a settable copy lets the
+    // imperative resolve()/dismiss() methods flip one envelope's resolution and
+    // re-render the matching child — the imperative twin of a consumer cloning +
+    // reassigning the whole cards array. `on(..., { defer: true })` re-seeds only on
+    // a genuine prop change (mount uses the createSignal seed below), preserving any
+    // pending imperative resolution until the consumer supplies a new prop array.
+    const [cards, setCards] = createSignal<CardEnvelope[]>(props.cards ?? []);
+    createEffect(on(() => props.cards, (next) => setCards(next ?? []), { defer: true }));
+
     // Route children's bubbling kai-card events through the policy. Attached to the host
     // element so composed events from each child's shadow root are caught as they bubble.
     // The handler reads `props.policy` at EVENT time (not mount time) so setting
     // `el.policy` after the element is in the DOM — the standard host pattern — works.
     onMount(() => {
-      const handler = (e: Event) =>
-        routeCardEvent(props.policy ?? {}, (e as CustomEvent<CardEvent>).detail);
+      const handler = (e: Event) => {
+        const detail = (e as CustomEvent<CardEvent>).detail;
+        routeCardEvent(props.policy ?? {}, detail);
+        // Additionally re-emit the non-bubbling convenience event when a child
+        // transitions to a resolved/deferred state — alongside (not instead of) the
+        // existing policy routing + the raw bubbling kai-card event.
+        const resolution = resolutionFromEvent(detail);
+        if (resolution) dispatch('kai-card-resolved', { cardId: detail.cardId, resolution });
+      };
       element.addEventListener(CARD_EVENT_NAME, handler as EventListener);
       onCleanup(() => element.removeEventListener(CARD_EVENT_NAME, handler as EventListener));
     });
+
+    // ── Imperative API (instance methods on the host) ──────────────────────────
+    // Pattern B: the methods operate on the facade's own working copy + the rendered
+    // child DOM nodes. Resolving an envelope sets its `resolution`, which flows down
+    // through CardSlot's effect (sets the child's `resolution` prop) so the child
+    // re-renders into its chromed read-only view.
+    const resolveCard = (cardId: string, resolution: CardResolution) =>
+      setCards((list) =>
+        list.some((env) => env.id === cardId)
+          ? list.map((env) => (env.id === cardId ? { ...env, resolution } : env))
+          : list,
+      );
+    expose({
+      /** Programmatically resolve a child card by id: set that envelope's
+       *  `resolution` so the child re-renders into its read-only/resolved view — the
+       *  imperative twin of the consumer mutating the cards array. No-op for an
+       *  unknown id. */
+      resolve: (cardId: string, resolution: CardResolution) => resolveCard(cardId, resolution),
+      /** Collapse a card to its re-openable stub from the host side — convenience for
+       *  `resolve(cardId, { kind: 'dismissed' })`. */
+      dismiss: (cardId: string) => resolveCard(cardId, { kind: 'dismissed' }),
+      /** Return the live child element node for a card id (or null) so consumers can
+       *  call that card's own methods (focus/expand/…) without a shadow-DOM query. */
+      getCard: (cardId: string): HTMLElement | null =>
+        element.shadowRoot?.querySelector<HTMLElement>(`[data-card-id="${CSS.escape(cardId)}"]`) ?? null,
+    });
+
     // Read the facade's REACTIVE `theme` prop, not element.getAttribute (which is
     // not a tracked dependency) — otherwise a theme change on <kai-cards> after the
     // children first render never propagates, leaving each child card stuck on its
@@ -81,7 +155,7 @@ defineWebComponent<Props>(
     const tags = () => mergeCardTags(props.types);
     return (
       <div class="flex flex-col gap-3">
-        <For each={props.cards ?? []}>
+        <For each={cards()}>
           {(env) => (
             <CardSlot
               envelope={env}

package/src/elements/chain-of-thought.tsx

@@ -1,49 +1,74 @@
-import { For, Show, createSignal, onMount, onCleanup } from 'solid-js';
+import { createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import {
-  ChainOfThought,
-  ChainOfThoughtStep,
-  ChainOfThoughtTrigger,
-  ChainOfThoughtContent,
-  ChainOfThoughtItem,
+  ChainOfThoughtAccordion,
+  type ChainOfThoughtController,
+  type ChainOfThoughtStepData,
+  type ChainOfThoughtType,
 } from '../components/chain-of-thought';
 
-interface Step {
-  /** The step's heading (the always-visible trigger). */
-  label: string;
-  /** Optional expandable detail. */
-  content?: string;
-}
+/**
+ * A reasoning step descriptor.
+ *
+ * `id` is an OPTIONAL stable key. The Accordion's open-set keys (used by `value`,
+ * `defaultValue`, the `kai-value-change` payload, and the index→key resolution
+ * behind the methods) are `step.id` when present, else `String(index)`. Set `id`
+ * if you want to drive/observe a step by a meaningful key rather than position.
+ */
+type Step = ChainOfThoughtStepData;
 
 interface Props extends Record<string, unknown> {
   /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to
-   *  this one data model (Route 1). */
+   *  this one data model (Route 1). Each `{ label, content?, id? }`. */
   steps: Step[];
+  /** Open mode: `'multiple'` (default — any number of steps open at once) or
+   *  `'single'` (at most one open; opening a step closes the others). */
+  type?: ChainOfThoughtType;
+  /** Controlled open step key(s). When set, it WINS over user interaction (the
+   *  consumer owns the open set). String in `single` mode, string[] in
+   *  `multiple` mode. Set as a JS property. */
+  value?: string | string[];
+  /** Uncontrolled INITIAL open step key(s) — seeds which steps render expanded.
+   *  Ignored once `value` is provided. Set as a JS property. */
+  defaultValue?: string | string[];
+}
+
+/** Events fired by `<kai-chain-of-thought>`. */
+interface Events {
+  /** The open set changed — by user click OR an expand()/collapse()/toggle()
+   *  call. `value` is a string in `single` mode, a string[] in `multiple` mode.
+   *  (Maps Radix Accordion's onValueChange.) */
+  'kai-value-change': { value: string | string[] };
 }
 
 /** Parse a single light-DOM `<kai-step>` element into a `Step` descriptor.
  *  Attribute mapping:
  *   - `label`       → Step.label   (the always-visible heading)
+ *   - `step-id`     → Step.id      (optional stable open-set key)
  *   - textContent   → Step.content (optional expandable detail)
  */
 export function parseKaiStepElement(n: Element): Step {
   return {
     label: n.getAttribute('label') ?? '',
     content: n.textContent?.trim() || undefined,
+    id: n.getAttribute('step-id') ?? undefined,
   };
 }
 
 /**
  * `<kai-chain-of-thought>` — step-by-step reasoning with connectors and
- * per-step collapsible detail.
+ * per-step collapsible detail. An Accordion: by default every step is
+ * independently collapsible (`type="multiple"`, all closed); set
+ * `type="single"` for one-open-at-a-time.
  *
  * **Route 1 — JS property:** set the `steps` property to an array of
- * `{ label, content? }` objects.
+ * `{ label, content?, id? }` objects.
  *
  * **Route 2 — declarative children:** compose `<kai-step>` child elements in
  * light DOM (hidden by the Shadow DOM — pure data carriers). The `label`
  * attribute becomes the step heading; `textContent` becomes the expandable
- * detail. Children are merged after any prop steps.
+ * detail; an optional `step-id` becomes the open-set key. Children are merged
+ * after any prop steps.
  *
  * ```html
  * <kai-chain-of-thought>
@@ -53,9 +78,12 @@ export function parseKaiStepElement(n: Element): Step {
  * </kai-chain-of-thought>
  * ```
  */
-defineWebComponent<Props>('kai-chain-of-thought', {
+defineWebComponent<Props, Events>('kai-chain-of-thought', {
   steps: [],
-}, (props, { element }) => {
+  type: undefined,
+  value: undefined,
+  defaultValue: undefined,
+}, (props, { element, dispatch, expose }) => {
   // Read declarative <kai-step> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedSteps, setSlottedSteps] = createSignal<Step[]>([]);
@@ -73,20 +101,37 @@ defineWebComponent<Props>('kai-chain-of-thought', {
   // Prop steps first; declarative children appended after.
   const allSteps = () => [...props.steps, ...slottedSteps()];
 
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // Pattern C: the Accordion component owns the open-set; the facade captures its
+  // controller and exposes index-based methods. Every setter routes through the
+  // component's onValueChange (handleValueChange below) — the single emit point —
+  // so user clicks AND method calls both fire kai-value-change. No prop collisions:
+  // the only props are steps/type/value/defaultValue.
+  let controller: ChainOfThoughtController | undefined;
+  expose({
+    /** Open one step's detail by index, or — with no arg — ALL steps. In `single`
+     *  mode opening one step closes the others (expand-all keeps the last). */
+    expand: (index?: number) => controller?.expand(index),
+    /** Close one step's detail by index, or — with no arg — ALL steps. */
+    collapse: (index?: number) => controller?.collapse(index),
+    /** Flip one step's open state by index. */
+    toggle: (index?: number) => controller?.toggle(index),
+  });
+
+  // Single emit point for the open set — both user clicks and the methods above
+  // flow through the component's onValueChange to here.
+  const handleValueChange = (value: string | string[]) => {
+    dispatch('kai-value-change', { value });
+  };
+
   return (
-    <ChainOfThought>
-      <For each={allSteps()}>
-        {(step, i) => (
-          <ChainOfThoughtStep isLast={i() === allSteps().length - 1}>
-            <ChainOfThoughtTrigger>{step.label}</ChainOfThoughtTrigger>
-            <Show when={step.content}>
-              <ChainOfThoughtContent>
-                <ChainOfThoughtItem>{step.content}</ChainOfThoughtItem>
-              </ChainOfThoughtContent>
-            </Show>
-          </ChainOfThoughtStep>
-        )}
-      </For>
-    </ChainOfThought>
+    <ChainOfThoughtAccordion
+      steps={allSteps()}
+      type={props.type as ChainOfThoughtType | undefined}
+      value={props.value as string | string[] | undefined}
+      defaultValue={props.defaultValue as string | string[] | undefined}
+      onValueChange={handleValueChange}
+      controllerRef={(c) => (controller = c)}
+    />
   );
 });

package/src/elements/chat-scope-picker.tsx

@@ -1,5 +1,7 @@
 import { defineWebComponent } from './define';
 import { ChatScopePicker } from '../components/chat-scope-picker';
+import { wireDisclosure } from './disclosure';
+import type { DropdownController } from '../ui/dropdown';
 import type { SearchFilters } from '../types';
 
 interface Props extends Record<string, unknown> {
@@ -9,12 +11,22 @@ interface Props extends Record<string, unknown> {
   availableTags: string[];
   /** The label shown on the trigger for the active scope. */
   currentLabel?: string;
+  /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected
+   *  to the `open` attribute, the dropdown still self-manages on click/keyboard).
+   *  Set `el.open = true`, or `<kai-scope-picker 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 dropdown. */
+  disabled?: boolean;
 }
 
 /** Events fired by `<kai-scope-picker>`. */
 interface Events {
   /** A scope was chosen (`undefined` filters = "All Content"). */
   'kai-scope-change': { filters: SearchFilters | undefined };
+  /** The scope dropdown opened or closed (by click, keyboard, Escape, outside-click, or a method). */
+  'kai-open-change': { open: boolean };
 }
 
 /**
@@ -26,11 +38,26 @@ defineWebComponent<Props, Events>('kai-scope-picker', {
   availableAuthors: [],
   availableTags: [],
   currentLabel: 'All Content',
-}, (props, { dispatch }) => (
-  <ChatScopePicker
-    currentLabel={props.currentLabel ?? 'All Content'}
-    availableAuthors={props.availableAuthors}
-    availableTags={props.availableTags}
-    onScopeChange={(filters) => dispatch('kai-scope-change', { filters })}
-  />
-));
+  open: undefined,
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { dispatch, 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 (
+    <ChatScopePicker
+      currentLabel={props.currentLabel ?? 'All Content'}
+      availableAuthors={props.availableAuthors}
+      availableTags={props.availableTags}
+      onScopeChange={(filters) => dispatch('kai-scope-change', { filters })}
+      defaultOpen={flag('defaultOpen')}
+      disabled={flag('disabled')}
+      controllerRef={(a) => (api = a)}
+    />
+  );
+});

package/src/elements/chat-types.ts

@@ -1,5 +1,5 @@
-import type { ToolPart } from '../components/tool';
-import type { AttachmentData } from '../components/attachments';
+import type { ToolPart } from '../components/tool-types';
+import type { AttachmentData } from '../components/attachment-types';
 
 /** The five built-in action buttons (each carries its own curated icon + label). */
 export type ChatMessageAction = 'copy' | 'like' | 'dislike' | 'regenerate' | 'edit';