@kitn.ai/ui 0.16.0 → 0.17.0

package/README.md

@@ -11,7 +11,7 @@ It can be consumed two ways:
 
 - **~50 composable components** across three layers: headless primitives → accessible UI primitives (built in-house, WCAG 2.1 AA — no third-party UI dependency) → AI feature components.
 - **Shadow-DOM web components** — zero CSS conflicts in any host. The host's styles can't leak in; the kit's Tailwind can't leak out.
-- **Lightweight by design** — a markdown-only `<kai-chat>` is **~110 KB gzip** (one file). Syntax highlighting (Shiki) is loaded **on demand, per-language, with no WASM** — and never loads at all if you don't render code.
+- **Load it your way** — register every element in one import, cherry-pick per-element with a bundler, or drop in a CDN autoloader that loads each on demand. Syntax highlighting loads lazily, per language, only when you render code.
 - **Tailwind v4** design tokens — rebrand by overriding `--color-*` custom properties.
 
 ## Install
@@ -43,6 +43,10 @@ npm run build   # emits dist/kitn-chat.es.js
   <script type="module">
     import '@kitn.ai/ui/elements';
 
+    // Registration is async (SSR-safe) — wait for the element to be defined
+    // before setting properties, or the upgrade clobbers them.
+    await customElements.whenDefined('kai-chat');
+
     const chat = document.querySelector('kai-chat');
 
     // Rich data is set as JS properties (not HTML attributes)
@@ -50,8 +54,8 @@ npm run build   # emits dist/kitn-chat.es.js
       { id: '1', role: 'assistant', content: 'Hello! How can I help?' },
     ];
 
-    // Events are CustomEvents dispatched on the element (they do not bubble)
-    chat.addEventListener('submit', (e) => {
+    // Events are non-bubbling kai-* CustomEvents dispatched on the element
+    chat.addEventListener('kai-submit', (e) => {
       console.log('user sent:', e.detail.value);
     });
   </script>
@@ -73,7 +77,7 @@ The element bundle is a self-contained ES module — load it directly from [jsDe
 <kai-chat></kai-chat>
 ```
 
-The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitn.ai/ui@0.4.0/dist/kitn-chat.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release. SolidJS and the kit's CSS are bundled in, and the lazy code-highlighting chunks load from the same CDN on demand. To override design tokens, also include `theme.css`:
+The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitn.ai/ui@0.16.0/dist/kitn-chat.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release. SolidJS and the kit's CSS are bundled in, and the lazy code-highlighting chunks load from the same CDN on demand. To override design tokens, also include `theme.css`:
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kitn.ai/ui/theme.css">
@@ -109,7 +113,7 @@ function App() {
 }
 ```
 
-The SolidJS entry (`.`) is the kit's raw source (`src/index.ts`) — your bundler compiles it, so it tree-shakes to just what you import.
+The SolidJS entry (`.`) ships compiled — your bundler tree-shakes it to just the components you import.
 
 ## Integrations
 
@@ -127,10 +131,13 @@ The components are deliberately **transport-agnostic**: `<kai-chat>` just render
 <script type="module">
   import '@kitn.ai/ui/elements';
 
+  // Registration is async (SSR-safe) — wait for the element before using it.
+  await customElements.whenDefined('kai-chat');
+
   const chat = document.getElementById('chat');
   chat.messages = [];
 
-  chat.addEventListener('submit', async (e) => {
+  chat.addEventListener('kai-submit', async (e) => {
     const text = e.detail.value.trim();
     if (!text) return;
 
@@ -392,12 +399,20 @@ cd examples/vue && npm install && npm run dev
 - **[docs/web-components.md](docs/web-components.md)** — full element API: every property, event, and the `ChatMessage` schema.
 - **[llms.txt](llms.txt)** / **[llms-full.txt](llms-full.txt)** — dense machine-readable references for AI coding agents.
 
-## Bundle size
+## Loading
+
+Three ways to load the elements — register all (the simple default), cherry-pick per-element, or a CDN autoloader:
+
+| How you load | What it does |
+|---|---|
+| `import '@kitn.ai/ui/elements'` | registers every element — the simple default |
+| `import '@kitn.ai/ui/elements/chat'` | one element, bundler tree-shakes |
+| `import '@kitn.ai/ui/autoloader'` (opt-in **DOM autoloader**) | loads each element's module **on demand** as `<kai-*>` appears |
 
-| Scenario | Loaded |
-|---|--:|
-| `<kai-chat>`, markdown only (no code blocks) | **~110 KB gzip** (~413 KB raw), one file |
-| + a code block | adds Shiki core + JS engine + that language + theme, lazily |
-| Highlighting disabled | Shiki never loads |
+The autoloader watches the DOM (initial scan + `MutationObserver`) and dynamically imports only the
+elements actually present — so a page with just `<kai-chat>` never downloads the others. It's additive:
+the register-all bundle stays the default. (Direct per-element imports and the autoloader are client-side;
+SSR apps use the register-all `@kitn.ai/ui/elements` or render client-only.)
 
-The build is ES-module only — a UMD/IIFE build can't code-split and would inline every lazy chunk into one multi-MB file, so it's intentionally omitted.
+Code highlighting (Shiki) is always lazy — loaded per-language on first code block, with no WASM, and never
+at all if you don't render code. The build is ES-module only (a UMD/IIFE build can't code-split).

package/dist/components/chat-thread.d.ts

@@ -1,4 +1,5 @@
 import { AttachmentData } from './attachments';
+import { MessageActionDetail } from '../primitives/message-feedback';
 import { SlashCommandItem } from './slash-command';
 import { ChatMessage } from '../elements/chat-types';
 import { ProseSize } from '../primitives/chat-config';
@@ -82,10 +83,7 @@ export interface ChatThreadProps {
     }) => void;
     onSuggestionClick?: (value: string) => void;
     onModelChange?: (modelId: string) => void;
-    onMessageAction?: (detail: {
-        messageId: string;
-        action: string;
-    }) => void;
+    onMessageAction?: (detail: MessageActionDetail) => void;
     onSearch?: () => void;
     onVoice?: () => void;
     onSlashSelect?: (command: SlashCommandItem) => void;

package/dist/components/choice-card.d.ts

@@ -24,6 +24,7 @@ export interface ChoiceCardData {
     options: ChoiceOption[];
     allowOther?: ChoiceAllowOther;
     submitLabel?: string;
+    dismissible?: boolean;
 }
 export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
 export declare const CHOICE_CARD_TYPE: "choice";

package/dist/components/dismissed-stub.d.ts

@@ -0,0 +1,22 @@
+import { JSX } from 'solid-js';
+/** The card types that render a dismissed stub, mapped to their intent verb. */
+export type DismissedCardType = 'confirm' | 'choice' | 'form' | 'tasks';
+/** Map a card `type` to its dismissed-stub intent label ("Proposed:", "Choose:",
+ *  "Form:", "Tasks:"). Falls back to a capitalized type for unknown card types. */
+export declare function stubIntent(type: string): string;
+export interface DismissedStubProps {
+    /** The card type, used to derive the intent label ("Proposed:" etc.). */
+    type: string;
+    /** The card's title/heading; shown after the intent label. Falls back gracefully. */
+    title?: string;
+    /** Re-open handler. The owning card emits `{ kind:'reopen', cardId }`. */
+    onReopen: () => void;
+    /** The Reopen button label. Default 'Reopen'. */
+    reopenLabel?: string;
+    class?: string;
+}
+/**
+ * `DismissedStub` — the compact stub a card collapses to after it's been dismissed.
+ * Group-labelled for a11y; the Reopen affordance is a ghost button.
+ */
+export declare function DismissedStub(props: DismissedStubProps): JSX.Element;

package/dist/components/message.d.ts

@@ -1,5 +1,7 @@
 import { JSX } from 'solid-js';
-import { ChatMessageAction, CustomAction } from '../elements/chat-types';
+import { ChatMessageAction, CustomAction, FeedbackVote } from '../elements/chat-types';
+import { ToolPart } from './tool';
+import { AttachmentData } from './attachments';
 export interface MessageProps extends JSX.HTMLAttributes<HTMLDivElement> {
     children: JSX.Element;
 }
@@ -28,6 +30,13 @@ export interface MessageActionBarProps {
     reveal?: 'always' | 'hover';
     /** Fired with the built-in name or the custom action id when a button is clicked. */
     onAction: (id: string) => void;
+    /** The active feedback vote. When `'like'`/`'dislike'` is set, that button is
+     *  marked pressed (filled) and the OTHER vote button animates out. `undefined`
+     *  shows both. Pure/prop-driven so the bar survives re-renders. */
+    activeFeedback?: FeedbackVote;
+    /** When true, the `copy` button shows its emerald check icon instead of the
+     *  copy glyph (cleared by the owner after ~2s). */
+    copied?: boolean;
     class?: string;
 }
 /**
@@ -36,8 +45,56 @@ export interface MessageActionBarProps {
  * descriptors use their `label` plus `actionIcon(icon)` (label-only when the
  * icon is unknown or absent). `reveal="hover"` makes the bar fade in on the
  * parent `.group`'s hover.
+ *
+ * Pure/prop-driven: feedback (`activeFeedback`) and copy (`copied`) state are
+ * owned by the parent facade and passed in — the bar holds no internal signals,
+ * so it survives the new-array-per-chunk re-renders of a streaming thread. With
+ * a vote active, the chosen `like`/`dislike` button is marked `aria-pressed` +
+ * filled and the other vote button collapses its width (sliding the active thumb
+ * into its place) via a 0fr↔1fr grid transition. The
+ * `copy` button swaps to an emerald check while `copied`.
  */
 declare function MessageActionBar(props: MessageActionBarProps): JSX.Element;
+export interface MessageBodyProps {
+    /** The message text/markdown. */
+    content: string;
+    /** Optional collapsible reasoning block, rendered above the content. */
+    reasoning?: {
+        text: string;
+        label?: string;
+    };
+    /** Tool-call parts, rendered above the content. */
+    tools?: ToolPart[];
+    /** Inline attachment previews, rendered above the content. */
+    attachments?: AttachmentData[];
+    /** Whether this is a user message (right-aligned bubble) vs an assistant
+     *  message (full-width transparent). */
+    isUser: boolean;
+    /** Whether the content renders as markdown. */
+    markdown: boolean;
+    /** Action-bar entries — built-in names and/or custom descriptors. When empty
+     *  the bar is not rendered. */
+    actions?: (ChatMessageAction | CustomAction)[];
+    /** `'always'` (default) keeps the bar visible; `'hover'` reveals it on parent
+     *  `.group` hover. */
+    actionsReveal?: 'always' | 'hover';
+    /** Fired with the built-in name or custom id when an action is clicked. */
+    onAction?: (id: string) => void;
+    /** The currently-active feedback vote, so the bar can mark like/dislike and
+     *  hide the other. */
+    activeFeedback?: FeedbackVote;
+    /** When true, the copy button shows its "copied" check icon. */
+    copied?: boolean;
+}
+/**
+ * The shared message body: an optional reasoning block, tool calls, inline
+ * attachments, the content bubble, and the action bar — in that order. This is
+ * the single source of truth for how a message renders, consumed by `ChatThread`
+ * (the `<For>` over `messages`), the standalone `<kai-message>` facade, and (in
+ * future) `kai-compare` for each candidate. Pure/prop-driven: all interaction
+ * state (copied, feedback vote) is owned above and passed in.
+ */
+declare function MessageBody(props: MessageBodyProps): JSX.Element;
 export interface MessageActionProps {
     tooltip: string;
     children: JSX.Element;
@@ -51,4 +108,4 @@ export interface MessageCopyButtonProps {
     class?: string;
 }
 declare function MessageCopyButton(props: MessageCopyButtonProps): JSX.Element;
-export { Message, MessageAvatar, MessageContent, MessageActions, MessageActionBar, MessageAction, MessageCopyButton };
+export { Message, MessageAvatar, MessageContent, MessageActions, MessageActionBar, MessageBody, MessageAction, MessageCopyButton };

package/dist/components/response-compare-types.d.ts

@@ -0,0 +1,66 @@
+import { ToolPart } from './tool';
+import { AttachmentData } from './attachments';
+/** One assistant response in a comparison. Rendered identically to an assistant
+ *  message (reasoning + tools + attachments + markdown content) via `MessageBody`. */
+export interface CompareCandidate {
+    /** Stable id, unique within the pair; echoed back in the selection. */
+    id: string;
+    /** The response text/markdown. */
+    content: string;
+    /** Optional collapsible reasoning block. */
+    reasoning?: {
+        text: string;
+        label?: string;
+    };
+    /** Tool-call parts rendered above the content. */
+    tools?: ToolPart[];
+    /** Inline attachment previews rendered above the content. */
+    attachments?: AttachmentData[];
+    /** Optional short column label (e.g. "A" / "B" / "Concise"). */
+    label?: string;
+    /** Optional model name shown as a sub-label. */
+    model?: string;
+    /** When true this candidate is still streaming — its pick control is disabled
+     *  and a per-column shimmer shows until it (and its sibling) settle. */
+    streaming?: boolean;
+}
+/** The two-candidate tuple. Enforced at the type level; validated at runtime by
+ *  `normalizeCandidates`. */
+export type ComparePair = [CompareCandidate, CompareCandidate];
+/** How the card collapses once the user picks. `'winner'` (default) shows just the
+ *  chosen candidate's body; `'none'` keeps both columns but marks the choice. */
+export type CompareCollapse = 'winner' | 'none';
+/** The compare definition (set as the `data` JS property on `<kai-compare>`). */
+export interface ResponseCompareData {
+    /** Optional prompt/question shown above the two columns. */
+    prompt?: string;
+    /** Exactly two candidates: [A, B]. */
+    candidates: ComparePair;
+    /** Collapse behaviour after a pick. Default `'winner'`. */
+    collapse?: CompareCollapse;
+}
+/** Emitted (and re-hydratable) when the user picks. The consumer pairs
+ *  `(prompt, chosenId, rejectedIds)` for preference capture / RLHF. */
+export interface CompareSelection {
+    /** The id of the chosen candidate. */
+    chosenId: string;
+    /** The id(s) of the rejected candidate(s) — for a pair, the other one. */
+    rejectedIds: string[];
+    /** Epoch ms when the pick was made. */
+    at?: number;
+}
+/**
+ * Validate + normalize the candidate list. A compare requires EXACTLY two
+ * candidates with unique, non-empty string ids. Returns the usable pair, or an
+ * error message when the definition is unusable (rendered as an inline error /
+ * emitted as a `kai-error`). Modeled on `normalizeOptions`.
+ */
+export declare function normalizeCandidates(candidates: unknown): {
+    candidates: ComparePair | null;
+    error?: string;
+};
+/** Build the selection payload for choosing `chosenId` out of the pair (the other
+ *  candidate is the rejected one). Stamps `at` with the current time. */
+export declare function buildSelection(pair: ComparePair, chosenId: string): CompareSelection;
+/** Whether any candidate in the pair is still streaming (pick stays disabled). */
+export declare function isAnyStreaming(pair: ComparePair | null): boolean;

package/dist/components/response-compare.d.ts

@@ -0,0 +1,51 @@
+import { JSX, Accessor } from 'solid-js';
+import { CompareSelection, ResponseCompareData } from './response-compare-types';
+export type { CompareCandidate, ComparePair, CompareCollapse, ResponseCompareData, CompareSelection, } from './response-compare-types';
+export { normalizeCandidates, buildSelection, isAnyStreaming } from './response-compare-types';
+export type CompareLayout = 'auto' | 'columns' | 'tabs';
+export interface ResolvedController<T> {
+    value: Accessor<T | undefined>;
+    isResolved: Accessor<boolean>;
+    isOptimistic: Accessor<boolean>;
+    setLocal: (v: T) => void;
+}
+export declare function useResolved<T>(opts: {
+    prop: Accessor<T | undefined>;
+    data: Accessor<unknown>;
+}): ResolvedController<T>;
+export interface ResponseCompareProps {
+    /** The compare definition (prompt + the two candidates). */
+    data?: ResponseCompareData;
+    /** Stable id correlating every emitted event. */
+    compareId?: string;
+    /** Re-hydrate / control the selection. Renders the collapsed winner. Set as a
+     *  JS property: `el.selection = { chosenId, rejectedIds }`. */
+    selection?: CompareSelection;
+    /** Layout. `'columns'` = side-by-side; `'tabs'` = one candidate at a time with
+     *  pills to switch; `'auto'` (default) uses a CONTAINER query — columns when the
+     *  component is ≥640px wide, tabs when narrower (e.g. on a phone). */
+    layout?: CompareLayout;
+    class?: string;
+    /** Fired when the user commits a pick. */
+    onSelect?: (sel: CompareSelection) => void;
+    /** Fired once both candidates have settled (stopped streaming) and a valid
+     *  definition is shown. */
+    onReady?: () => void;
+    /** Fired for an unusable definition (inline error state). */
+    onError?: (message: string) => void;
+}
+/**
+ * `ResponseCompare` — a dual-response comparison. Two assistant candidates for the
+ * same prompt render side-by-side (or as tabs), each via `MessageBody` so a
+ * candidate reads exactly like an assistant message (reasoning + tools +
+ * attachments + markdown). The pick is a COMMIT, not a Submit: clicking "Pick this"
+ * (or Enter on the focused column) computes `{ chosenId, rejectedIds:[other], at }`,
+ * optimistically collapses to the chosen candidate's body, and calls `onSelect` for
+ * the consumer to send a `(prompt, chosen, rejected)` preference pair. Single-shot.
+ *
+ * While EITHER candidate is `streaming`, both pick controls are disabled and the
+ * streaming column shows a `TextShimmer`; `onReady` fires once both settle. The two
+ * columns are a WAI-ARIA radiogroup with roving tabindex (Arrow keys move A↔B,
+ * Enter/Space picks). Emits `onError` for a malformed definition.
+ */
+export declare function ResponseCompare(props: ResponseCompareProps): JSX.Element;

package/dist/components/tasks-card.d.ts

@@ -16,6 +16,7 @@ export interface TasksCardData {
     allowEmpty?: boolean;
     min?: number;
     max?: number;
+    dismissible?: boolean;
 }
 export interface TasksCardResult {
     selected: string[];

package/dist/components/toast.d.ts

@@ -0,0 +1,48 @@
+import { ToastItem, ToastVariant } from '../primitives/toast-store';
+export type { ToastItem, ToastVariant };
+/** Why a toast went away — surfaced to `onDismiss` (and the facade event). */
+export type ToastDismissReason = 'timeout' | 'close' | 'action';
+export type ToastPosition = 'top-center' | 'top-right' | 'top-left' | 'bottom-center' | 'bottom-right' | 'bottom-left';
+export interface ToastRegionProps {
+    /** The toasts to render. Newest is shown on top. Set as a JS property on the
+     *  element; mutate by passing a new array reference. */
+    toasts: ToastItem[];
+    /** Where the stack anchors. Defaults to `'top-center'`. */
+    position?: ToastPosition;
+    /** Max simultaneously-visible toasts; the rest queue and promote as slots
+     *  free up. Defaults to `3`. */
+    max?: number;
+    /** Stacking: 'expanded' (default, full column) | 'collapsed' (Sonner-style
+     *  pile that expands on hover/focus). Attribute: stack. */
+    stack?: 'expanded' | 'collapsed';
+    /** When set, this region renders only the toasts scoped to that element and
+     *  anchors over its bounds (top-center), following it on scroll/resize. Unset =
+     *  the global, viewport-anchored region. */
+    target?: HTMLElement;
+    /** Fired when a toast leaves, with the reason. */
+    onDismiss?: (id: string, reason: ToastDismissReason) => void;
+    /** Fired when a toast's action button is pressed. */
+    onAction?: (id: string, label: string) => void;
+}
+interface ToastProps {
+    item: ToastItem;
+    onDismiss: (reason: ToastDismissReason) => void;
+    onAction?: (label: string) => void;
+    /** Hold the auto-dismiss timer (the region sets this true while the whole stack
+     *  is hovered/expanded, so peers don't dismiss out from under the cursor). */
+    paused?: boolean;
+}
+/**
+ * A single toast pill. Auto-dismisses after its (action-floored) duration, holds
+ * the timer while hovered (this pill) OR while `paused` (the whole stack is
+ * hovered), and animates in/out via `createPresence`. Pure + prop-driven — the
+ * parent `ToastRegion` owns the list + queue.
+ */
+export declare function Toast(props: ToastProps): import("solid-js").JSX.Element;
+/**
+ * Renders a stack of toasts at a viewport edge. Caps the visible count at `max`
+ * (newest on top); overflow waits in a queue and is promoted as visible toasts
+ * leave. `aria-live=polite` / `role=region` so screen readers announce new
+ * toasts without stealing focus.
+ */
+export declare function ToastRegion(props: ToastRegionProps): import("solid-js").JSX.Element;

package/dist/components/use-card-resolution.d.ts

@@ -1,12 +1,16 @@
 import { Accessor } from 'solid-js';
 import { CardResolution } from '../primitives/card-contract';
-export interface ResolutionController {
-    resolution: Accessor<CardResolution | undefined>;
+export interface ResolutionController<R extends CardResolution = CardResolution> {
+    resolution: Accessor<R | undefined>;
     isResolved: Accessor<boolean>;
+    /** A finished resolution the user can't take back here (action | submit | expired). */
+    isTerminal: Accessor<boolean>;
+    /** A deferred resolution (`dismissed`) — set aside, still re-openable. */
+    isDeferred: Accessor<boolean>;
     isOptimistic: Accessor<boolean>;
-    setLocal: (r: CardResolution) => void;
+    setLocal: (r: R) => void;
 }
-export declare function useCardResolution(opts: {
-    prop: Accessor<CardResolution | undefined>;
+export declare function useCardResolution<R extends CardResolution = CardResolution>(opts: {
+    prop: Accessor<R | undefined>;
     data: Accessor<unknown>;
-}): ResolutionController;
+}): ResolutionController<R>;