@kitn.ai/ui 0.16.0 → 0.18.0

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

@@ -0,0 +1,65 @@
+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';
+/** Imperative handle exposed via `controllerRef` — surfaces the compare's latent
+ *  capabilities (commit a pick by candidate id, focus the roving tab stop) so the
+ *  `<kai-compare>` facade can forward them as instance methods (Pattern C). */
+export interface ResponseCompareController {
+    /** Commit a pick by candidate id — same path as the "Pick this" button: emits
+     *  onSelect + optimistically collapses (single-shot; inert while streaming or
+     *  already resolved). No-op for an unknown id. */
+    select(candidateId: string): void;
+    /** Focus the current roving tab stop (the focused candidate's "Pick this" radio). */
+    focus(options?: FocusOptions): void;
+}
+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;
+    /** Receive the imperative controller once mounted. The `<kai-compare>` facade
+     *  forwards these as element methods (select/focus). */
+    controllerRef?: (controller: ResponseCompareController) => void;
+    /** 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/screen.d.ts

@@ -0,0 +1,46 @@
+import { Accessor, JSX } from 'solid-js';
+/** Imperative open controller, handed to a parent (the kai-screen facade) via
+ *  `controllerRef` so it can drive/observe open state with `wireDisclosure`. */
+export interface ScreenController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
+export interface ScreenProps {
+    /** The screen body. */
+    children?: JSX.Element;
+    /** Header title text. A projected `title` slot overrides this. */
+    title?: JSX.Element;
+    /** Header title slot content (the facade's `<slot name="title" />`). Overrides `title`. */
+    titleSlot?: JSX.Element;
+    /** Header trailing cluster (the facade's `<slot name="actions" />`). */
+    actions?: JSX.Element;
+    /** Controlled open state. When set, the component never changes it itself;
+     *  drive it from `onOpenChange`. Omit for uncontrolled (internal) state. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    /** Show the back button (default true). */
+    back?: boolean;
+    /** Skip marking sibling elements inert/aria-hidden while open. */
+    noInert?: boolean;
+    /** The custom-element host, whose siblings get inert-ed while open. */
+    host?: () => HTMLElement | undefined;
+    /** Fires whenever open wants to change (back button / method). */
+    onOpenChange?: (open: boolean) => void;
+    /** Back navigation intent: the back button or Escape. */
+    onBack?: () => void;
+    /** Receive the open controller once mounted. */
+    controllerRef?: (api: ScreenController) => void;
+    /** Receive the focusable surface node so the facade's `focus()` can target it. */
+    surfaceRef?: (el: HTMLElement) => void;
+}
+/**
+ * Screen is the presentational full-bleed overlay surface. It owns the hard parts
+ * of being a takeover: it fills its mount point while open, marks sibling
+ * elements `inert` + `aria-hidden` (the standard modal pattern), moves focus into
+ * the surface on open and restores it on close, fires `onBack` on Escape, and
+ * runs an enter/exit transition that honors `prefers-reduced-motion`. When closed
+ * it is removed from layout (no space, not focusable). The developer owns the swap
+ * (their own routing flips `open`); this owns being the overlay.
+ */
+export declare function Screen(props: ScreenProps): JSX.Element;

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

@@ -8,7 +8,15 @@ export interface TasksTask {
     disabled?: boolean;
 }
 export interface TasksCardData {
-    mode?: 'select';
+    /**
+     * `select` (default) = checkbox rows + a confirm button that emits the contract
+     * `submit`. `progress` = an onboarding/checklist look: a header `done / total`
+     * count, circular indicators, per-item title + muted description, and NO confirm
+     * button (checking a row is itself the terminal action). Both share the same
+     * selection model (toggle by id, the `max` gate, `kai-value-change`); `progress`
+     * is purely a presentational variant.
+     */
+    mode?: 'select' | 'progress';
     heading?: string;
     tasks: TasksTask[];
     selectAll?: boolean;
@@ -16,6 +24,7 @@ export interface TasksCardData {
     allowEmpty?: boolean;
     min?: number;
     max?: number;
+    dismissible?: boolean;
 }
 export interface TasksCardResult {
     selected: string[];
@@ -39,12 +48,36 @@ export declare function selectAllState(tasks: TasksTask[], selected: Set<string>
 /** Whether select-all should be shown: requested AND not blocked by `max` (since
  *  "all" would violate max). */
 export declare function showSelectAll(data: TasksCardData, tasks: TasksTask[]): boolean;
+/** Whether the card is in the onboarding-checklist `progress` look (no confirm). */
+export declare function isProgressMode(data: TasksCardData): boolean;
+/** The header progress count (`done` checked / `total` rows) for `progress` mode. */
+export declare function progressCount(tasks: TasksTask[], selected: Set<string>): {
+    done: number;
+    total: number;
+};
 /** Whether confirm is enabled for the current selection count. */
 export declare function canConfirm(data: TasksCardData, count: number): boolean;
 /** Whether an unchecked row is blocked because `max` is reached. */
 export declare function isMaxReached(data: TasksCardData, count: number): boolean;
 /** The disabled-reason text for confirm (for aria-describedby), or undefined. */
 export declare function confirmReason(data: TasksCardData, count: number): string | undefined;
+/** Imperative handle exposed via `controllerRef` — surfaces the tasks card's latent
+ *  selection model (set the checked ids, toggle one, confirm, focus the group,
+ *  dismiss/reopen) so the `<kai-tasks>` facade can forward them as instance methods. */
+export interface TasksCardController {
+    /** Set the checked ids (local-only, no emit), respecting disabled/max. No arg = select all toggleable rows. */
+    select(taskIds?: string[]): void;
+    /** Toggle one task by id, honoring the max gate. */
+    toggle(taskId: string, checked?: boolean): void;
+    /** Confirm the current selection (only when allowed) — emits `submit` + resolves. */
+    send(): void;
+    /** Focus the task group (select-all checkbox if shown, else the first row). */
+    focus(options?: FocusOptions): void;
+    /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+    dismiss(): void;
+    /** Re-open a dismissed card from its stub (emit `reopen`). */
+    reopen(): void;
+}
 export interface TasksCardProps {
     /** The tasks definition (CardEnvelope.data). */
     data?: TasksCardData;
@@ -60,6 +93,22 @@ export interface TasksCardProps {
     class?: string;
     /** When set, render the chromed read-only summary instead of the interactive controls. */
     resolution?: CardResolution;
+    /** Controlled selection (task ids) — when set, this wins over internal state. */
+    value?: string[];
+    /** Uncontrolled initial selection (task ids), overlaying per-task `checked`. */
+    defaultValue?: string[];
+    /** Freeze the whole list + Confirm. */
+    disabled?: boolean;
+    /** Display-only: rows can't be toggled and show the default cursor (no pointer,
+     *  no hover background, no focus ring). Keeps the visual content as-is — this only
+     *  drops the interactive affordances + a11y exposure. */
+    readonly?: boolean;
+    /** Fires on every selection change with the selected ids (distinct from submit). */
+    onValueChange?: (payload: {
+        value: string[];
+    }) => void;
+    /** Receive the imperative controller once mounted. */
+    controllerRef?: (controller: TasksCardController) => void;
 }
 /**
  * `TasksCard` — a selectable task/plan list (checkbox rows + optional select-all

package/dist/components/toast.d.ts

@@ -0,0 +1,58 @@
+import { ToastItem, ToastVariant, ToastAppearance } from '../primitives/toast-store';
+export type { ToastItem, ToastVariant, ToastAppearance };
+/** 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';
+    /** Region-level default appearance for toasts that don't set their own. A
+     *  per-toast `appearance` always wins. Defaults to `'pill'`. */
+    appearance?: ToastAppearance;
+    /** Region-level default inverse treatment for toasts that don't set their own.
+     *  A per-toast `inverse` always wins. Defaults to `false`. */
+    inverse?: boolean;
+    /** 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;
+    /** Region-level default appearance, used when the item doesn't set its own. */
+    appearance?: ToastAppearance;
+    /** Region-level default inverse, used when the item doesn't set its own. */
+    inverse?: 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/tool-types.d.ts

@@ -0,0 +1,10 @@
+/** A tool-call part rendered by <Tool>. Pure type — kept JSX-free so it can be
+ *  imported by the framework-neutral state core and the React typecheck pass. */
+export interface ToolPart {
+    type: string;
+    state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    toolCallId?: string;
+    errorText?: string;
+}

package/dist/components/tool.d.ts

@@ -1,15 +1,15 @@
 import { JSX } from 'solid-js';
-export interface ToolPart {
-    type: string;
-    state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
-    input?: Record<string, unknown>;
-    output?: Record<string, unknown>;
-    toolCallId?: string;
-    errorText?: string;
-}
+import { CollapsibleController } from '../ui/collapsible';
+import { ToolPart } from './tool-types';
+export type { ToolPart } from './tool-types';
 export interface ToolProps {
     toolPart: ToolPart;
     defaultOpen?: boolean;
+    /** Gate the disclosure trigger (programmatic control still works). */
+    disabled?: boolean;
+    /** Receive the open controller once mounted (forwarded from the Collapsible),
+     *  so a parent (the kai-tool facade) can drive/observe open state. */
+    controllerRef?: (api: CollapsibleController) => void;
     class?: string;
 }
 declare function Tool(props: ToolProps): 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>;

package/dist/components/voice-input.d.ts

@@ -1,7 +1,34 @@
+/** Imperative handle exposed via `controllerRef` — surfaces the recorder's latent
+ *  start/stop so the `<kai-voice-input>` facade can forward them as instance
+ *  methods (push-to-talk). Both run the SAME getUserMedia → blob → transcription
+ *  path as clicking the mic, so manual + programmatic emit identically. */
+export interface VoiceInputController {
+    /** Begin recording programmatically (same path as clicking the mic). */
+    start(): void;
+    /** Stop the in-progress recording (produces the blob → onTranscribe). */
+    stop(): void;
+}
 export interface VoiceInputProps {
     onTranscribe: (audio: Blob) => Promise<string>;
     onTranscription: (text: string) => void;
     disabled?: boolean;
     class?: string;
+    /** Host supplied a `transcribe` callback. When true the MediaRecorder →
+     *  onTranscribe path runs. When false the component prefers native
+     *  SpeechRecognition (capable browsers), falling back to record-only. */
+    hasTranscribe?: boolean;
+    /** BCP-47 language tag for native recognition (e.g. `en-US`). */
+    lang?: string;
+    /** Emit live partial transcripts via `onInterim` (native path only). */
+    interim?: boolean;
+    /** Live partial transcript from native recognition (when `interim`). */
+    onInterim?: (text: string) => void;
+    /** Fires whenever recording starts or stops. Guarded against the spurious
+     *  initial `false` — only true transitions emit (the facade maps this to
+     *  kai-recording-change). */
+    onRecordingChange?: (recording: boolean) => void;
+    /** Receive the imperative controller once mounted. The `<kai-voice-input>`
+     *  facade forwards these as element methods (start/stop). */
+    controllerRef?: (controller: VoiceInputController) => void;
 }
 export declare function VoiceInput(props: VoiceInputProps): import("solid-js").JSX.Element;

package/dist/components/voice-output.d.ts

@@ -0,0 +1,33 @@
+/** Imperative handle exposed via `controllerRef` — surfaces the playback controls
+ *  so the `<kai-voice-output>` facade can forward them as instance methods. Both
+ *  the native (speechSynthesis) and model (synthesize → Audio) paths run through
+ *  these, so manual clicks and programmatic calls behave identically. */
+export interface VoiceOutputController {
+    /** Speak the current `text` (native by default, model if `synthesize` is set). */
+    speak(): void;
+    /** Pause playback (resumable). */
+    pause(): void;
+    /** Resume paused playback. */
+    resume(): void;
+    /** Stop playback and reset. */
+    stop(): void;
+}
+export interface VoiceOutputProps {
+    /** The utterance to read aloud. */
+    text: string;
+    /** Speak automatically when `text` is set/changed. */
+    autoplay?: boolean;
+    /** TTS model seam: given text, return an audio Blob to play. When set, the
+     *  native speechSynthesis path is bypassed. Mirrors VoiceInput's `onTranscribe`. */
+    onSynthesize?: (text: string) => Promise<Blob>;
+    /** Fires whenever playback starts or stops. */
+    onSpeakingChange?: (speaking: boolean) => void;
+    /** Fires once the model path resolves audio (model path only). */
+    onSynthesized?: (blob: Blob) => void;
+    disabled?: boolean;
+    class?: string;
+    /** Receive the imperative controller once mounted. The `<kai-voice-output>`
+     *  facade forwards these as element methods (speak/pause/resume/stop). */
+    controllerRef?: (controller: VoiceOutputController) => void;
+}
+export declare function VoiceOutput(props: VoiceOutputProps): import("solid-js").JSX.Element;