@kitn.ai/ui 0.20.1 → 0.22.0

package/src/elements/chat.tsx

@@ -2,7 +2,11 @@ import { createEffect, createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
 import { CHAT_SLOTS, readSlots } from './slots';
 import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
+import { cardComponentsFromTags } from './message';
+import { createMessagesGuard } from './validate-messages';
 import type { AttachmentData } from '../components/attachments';
+import type { RejectedAttachment } from './default-input';
+import type { ChatMessage } from './chat-types';
 import type { TriggerDef } from '../components/composer';
 import type { ComposerDoc } from '../primitives/composer-model';
 import type { ProseSize } from '../primitives/chat-config';
@@ -10,7 +14,56 @@ import type { ModelOption } from '../types';
 
 type Props = Omit<ChatThreadProps,
   'class' | 'onValueChange' | 'onSubmit' | 'onAttachmentsChange' | 'onSuggestionClick' | 'onModelChange'
-  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef'> & Record<string, unknown>;
+  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'messages'
+  | 'accept' | 'onAttachmentsRejected'> & Record<string, unknown> & {
+    /** Which attachment media types the user may stage, in HTML `accept` syntax:
+     *  `<kai-chat accept="image/*,application/pdf">`. A plain string, so unlike
+     *  `messages` it DOES work as an attribute. Omitted means no filter.
+     *
+     *  MEDIA TYPES ONLY -- exact (`image/png`) or subtype wildcard (`text/*`).
+     *  HTML allows a file extension here and this does not: `accept=".py"` THROWS
+     *  with the entry named, rather than silently resolving to a picker that
+     *  accepts nothing.
+     *
+     *  It can only NARROW what the kit can already encode: `accept="image/*"`
+     *  resolves to the four image formats both APIs take, not to every image type
+     *  the OS offers. Pass the SAME string to `toOpenAIMessages(msgs, { accept })`
+     *  and the picker and the wire cannot disagree -- both resolve it through
+     *  `resolveMediaPolicy` against one declaration. That declaration is readable
+     *  as `encodableMediaTypes()` from `@kitn.ai/ui/wire`, if you would rather
+     *  build your own picker than use this prop. */
+    accept?: string;
+    /** The full message thread to render, newest last. Each entry carries its
+     *  role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS
+     *  property (`el.messages = [...]`); a NEW array reference per streaming
+     *  chunk re-renders (mutating in place does not). Omit for an empty thread.
+     *
+     *  Re-declared here (rather than inherited from `ChatThreadProps`) because
+     *  the ELEMENT registers a `[]` default and renders the empty state without
+     *  it, while the SolidJS `<ChatThread>` component still requires it. The
+     *  facade hands it a validated array either way. Matches `<kai-thread>`. */
+    messages?: ChatMessage[];
+    /** Optional card type -> custom-element tag overrides/additions for `card`
+     *  parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a
+     *  plain string map (not the `CardTagMap` alias) so the generated React
+     *  wrapper inlines it instead of emitting an unresolved named type. */
+    cardTypes?: Record<string, string>;
+    /** JSON Schemas for the card types this app renders, keyed by envelope type. The
+     *  companion of `cardTypes`, which says what DRAWS a card while this says what a
+     *  VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas
+     *  = { 'pricing-table': pricingSchema }`, never an attribute.
+     *  `createCardRegistry(...).validationSchemas` is exactly this shape.
+     *
+     *  Without it the kit validates its own seven built-ins and leaves your own card
+     *  type, the one your app actually cares about, as the only unchecked thing on
+     *  screen. A schema here WINS over a built-in of the same name.
+     *
+     *  Typed `Record<string, object>` rather than `Record<string, JsonSchema>`
+     *  deliberately: an imported `.json` schema widens `"type"` to `string`, and an
+     *  authored one carries `$schema`/`title`/`description`/`additionalProperties`,
+     *  so the tighter type would reject both of the normal ways to supply one. */
+    cardSchemas?: Record<string, object>;
+  };
 
 interface Events {
   /** User submitted a message. */
@@ -20,6 +73,11 @@ interface Events {
   /** The staged attachments changed (file added or removed). Carries the full
    *  current list so a consumer can react in real time. */
   'kai-attachments-change': { attachments: AttachmentData[] };
+  /** One or more picked files were refused because `accept` excluded them. The
+   *  element renders NO message of its own: it reports the facts (name, media
+   *  type, whether the kit could have sent it) and what the user should see is
+   *  the application's call. Only ever fires when `accept` is set. */
+  'kai-attachments-rejected': { rejected: RejectedAttachment[] };
   /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
   'kai-suggestion-click': { value: string };
   /** An action button on a message was clicked. `action` is the built-in name or
@@ -40,8 +98,14 @@ defineWebComponent<Props, Events>('kai-chat', {
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
   search: false, voice: false, triggers: undefined, kindIcons: undefined,
-  actionsReveal: 'always',
+  actionsReveal: 'always', cardTypes: undefined, cardSchemas: undefined, accept: undefined,
 }, (props, { dispatch, flag, element, expose }) => {
+  // `messages` is an untyped boundary: a consumer can hand it anything at
+  // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
+  // the invalid entries rather than let `groupMessageParts` throw deep inside a
+  // render pass, which would blank the whole chat instead of one message.
+  const validMessages = createMessagesGuard('kai-chat');
+
   // Slot detection is driven by the CHAT_SLOTS registry (single source of truth)
   // so slot names never drift between the view, the facade, and the docs.
   const [slots, setSlots] = createSignal<Record<string, boolean>>({});
@@ -62,16 +126,35 @@ defineWebComponent<Props, Events>('kai-chat', {
   // (focus the composer, clear it, send programmatically, scroll the thread).
   let controller: ChatThreadController | undefined;
   expose({
+    /** Focus the composer, meaning the contenteditable (or textarea) inside the
+     *  shadow root. A native `focus()` on the host lands on the host itself and
+     *  never reaches it, so this is the only way to focus the input
+     *  programmatically. */
     focus: (options?: FocusOptions) => controller?.focus(options),
+    /** Blur whatever currently holds focus inside the shadow root. The companion
+     *  to `focus()`, for the same reason: a native `blur()` on the host misses
+     *  the real focus target. */
     blur: () => (element.shadowRoot?.activeElement as HTMLElement | null)?.blur(),
+    /** Empty the COMPOSER: drops the draft text and every staged attachment, then
+     *  fires `kai-value-change` with `''`. It does NOT touch the thread. `messages`
+     *  is the consumer's own state, so clearing history stays the consumer's call. */
     clear: () => controller?.clear(),
+    /** Submit whatever the composer currently holds, on the same path as Enter or
+     *  the send button: fires `kai-submit` with that value plus the staged
+     *  attachments, then drops the attachments. It takes no argument, so to send
+     *  text the user never typed, set `el.value` first. There is no empty-check,
+     *  so an empty composer still fires. The draft is cleared afterwards only when
+     *  `value` is uncontrolled; a controlled host owns its value and clears it
+     *  itself. Named `send`, not `submit`, to match the shared vocabulary. */
     send: () => controller?.send(),
+    /** Scroll the message viewport to the newest message. Defaults to `'smooth'`;
+     *  pass `'instant'` to jump without animating. */
     scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
   });
 
   return (
   <ChatThread
-    messages={props.messages} value={props.value as string | ComposerDoc | undefined} placeholder={props.placeholder as string}
+    messages={validMessages(props.messages)} value={props.value as string | ComposerDoc | undefined} placeholder={props.placeholder as string}
     loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
     suggestionMode={props.suggestionMode as 'submit' | 'fill'} persistSuggestions={flag('persistSuggestions')}
     proseSize={props.proseSize as ProseSize}
@@ -82,9 +165,13 @@ defineWebComponent<Props, Events>('kai-chat', {
     triggers={props.triggers as TriggerDef[] | undefined}
     kindIcons={props.kindIcons as Record<string, string> | undefined}
     actionsReveal={props.actionsReveal as 'always' | 'hover'}
+    cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
+    cardSchemas={props.cardSchemas as Record<string, object> | undefined}
     onValueChange={(value) => dispatch('kai-value-change', { value })}
     onSubmit={(detail) => dispatch('kai-submit', detail)}
+    accept={props.accept as string | undefined}
     onAttachmentsChange={(attachments) => dispatch('kai-attachments-change', { attachments })}
+    onAttachmentsRejected={(rejected) => dispatch('kai-attachments-rejected', { rejected })}
     onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
     onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
     onMessageAction={(detail) => dispatch('kai-message-action', detail)}

package/src/elements/choice.tsx

@@ -6,7 +6,7 @@ interface Props extends Record<string, unknown> {
   /** The choice definition (the CardEnvelope.data). Set as a JS PROPERTY:
    *  `el.data = { prompt, options:[…], allowOther?, submitLabel? }`. Import
    *  `ChoiceCardData` from `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: ChoiceCardData;
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
@@ -14,7 +14,7 @@ interface Props extends Record<string, unknown> {
   /** Set when the user resolved this card; renders the read-only view. Property:
    *  `el.resolution = { kind:'action', action:'…' }`. */
   resolution?: Record<string, unknown>;
-  /** Controlled selection — the selected option id. When set, the consumer owns
+  /** Controlled selection: the selected option id. When set, the consumer owns
    *  the current pick (RadioGroup `value`). Attribute: `value`. */
   value?: string;
   /** Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`. */
@@ -68,23 +68,23 @@ defineWebComponent<Props, Events>(
     expose({
       /** Focus the radiogroup roving tab stop (or the Other input when selected). */
       focus: (options?: FocusOptions) => controller?.focus(options),
-      /** Select an option by id locally — no emit, fires kai-value-change (same as
-       *  a row click). Lets a consumer pre-highlight or drive selection externally. */
+      /** Select an option by id locally: no emit, fires kai-value-change (same as a
+       *  row click). Lets a consumer pre-highlight or drive selection externally. */
       select: (optionId: string) => controller?.select(optionId),
-      /** Submit the current selection — emits the `action` verb on kai-card and
+      /** Submit the current selection: emits the `action` verb on kai-card and
        *  resolves the card (single-shot). Named `send`, not `submit`, per the shared
        *  vocabulary. */
       send: () => controller?.send(),
-      /** Trigger the dismiss path — emits `dismiss` on kai-card and optimistically
+      /** Trigger the dismiss path: emits `dismiss` on kai-card and optimistically
        *  collapses the card to its re-openable stub. */
       dismiss: () => controller?.dismiss(),
-      /** Re-open a dismissed card from its stub — emits `reopen` on kai-card. */
+      /** Re-open a dismissed card from its stub: emits `reopen` on kai-card. */
       reopen: () => controller?.reopen(),
     });
 
     return (
       <ChoiceCard
-        data={props.data as ChoiceCardData | undefined}
+        data={props.data}
         cardId={props.cardId ?? (element.id || 'kai-choice')}
         heading={props.heading}
         resolution={props.resolution as CardResolution | undefined}

package/src/elements/coachmark.tsx

@@ -17,7 +17,7 @@ interface Props extends Record<string, unknown> {
   /** 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. */
+   *  (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. */

package/src/elements/command.tsx

@@ -1,30 +1,15 @@
 import { createEffect, createMemo, createSignal, createUniqueId, on } from 'solid-js';
 import { CommandList, type CommandGroup } from '../ui/command';
 import { defineWebComponent } from './define';
+import type { KaiCommandItem } from './element-data-types';
 
-/**
- * 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;
-}
+// The item shape lives in ./element-data-types so the ROOT entry can re-export it
+// (a per-element module's shipped .d.ts is `export {};`). Re-exported here so
+// `import type { KaiCommandItem } from './command'` keeps working.
+export type { KaiCommandItem } from './element-data-types';
 
 interface Props extends Record<string, unknown> {
-  /** Flat list of items. Set as a JS property — not an HTML attribute. */
+  /** Flat list of items. Set as a JS property, not an HTML attribute. */
   items?: KaiCommandItem[];
   /** Placeholder text for the search input. */
   placeholder?: string;
@@ -37,7 +22,7 @@ interface Events {
   '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
+  /** 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. */
@@ -169,7 +154,7 @@ defineWebComponent<Props, Events>('kai-command', {
       element.shadowRoot
         ?.querySelector<HTMLInputElement>('input[role="combobox"], input')
         ?.blur(),
-    /** Reset the search query to empty — re-showing all items — and fire
+    /** Reset the search query to empty, re-showing all items, and fire
      *  `kai-query-change` with `''`. Mirrors the Escape-key behavior. */
     clear: () => {
       setQuery('');

package/src/elements/compare.tsx

@@ -17,8 +17,8 @@ interface Props extends Record<string, unknown> {
   /** 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: `'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;
@@ -77,10 +77,11 @@ defineWebComponent<Props, Events>(
     // 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). */
+      /** Programmatically commit a pick by candidate id, on the 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. */