@kitn.ai/ui 0.20.1 → 0.21.0

package/dist/primitives/card-component-types.d.ts

@@ -0,0 +1,11 @@
+import { Component } from 'solid-js';
+import { CardEnvelope, CardHost } from './card-contract.js';
+/** Solid renderer for one envelope. `host` is the resolved CardHost so each wrapper
+ *  can bridge its card's emit convention (form/confirm/tasks take `host`;
+ *  link/embed take `onEmit`). */
+export type CardComponent = Component<{
+    envelope: CardEnvelope;
+    host?: CardHost;
+}>;
+/** Solid layer: envelope type → the component that draws it. */
+export type CardComponentMap = Record<string, CardComponent>;

package/dist/primitives/card-data-types.d.ts

@@ -0,0 +1,196 @@
+import { CardEnvelope } from './card-contract.js';
+export type ConfirmActionStyle = 'primary' | 'default' | 'destructive';
+export type ConfirmTone = 'default' | 'warning' | 'danger';
+export type ConfirmAction = {
+    id: string;
+    label: string;
+    style?: ConfirmActionStyle;
+    payload?: unknown;
+    default?: boolean;
+};
+export type ConfirmCardData = {
+    heading?: string;
+    body?: string;
+    tone?: ConfirmTone;
+    actions: ConfirmAction[];
+    dismissible?: boolean;
+};
+export type ConfirmCardEnvelope = CardEnvelope<'confirm', ConfirmCardData>;
+export type ChoiceOptionMedia = {
+    image?: string;
+    imageAlt?: string;
+    icon?: string;
+};
+export type ChoiceOption = {
+    id: string;
+    label: string;
+    description?: string;
+    media?: ChoiceOptionMedia;
+    meta?: string;
+    recommended?: boolean;
+    disabled?: boolean;
+    payload?: unknown;
+};
+export type ChoiceAllowOther = boolean | {
+    label?: string;
+    placeholder?: string;
+};
+export type ChoiceCardData = {
+    prompt?: string;
+    options: ChoiceOption[];
+    allowOther?: ChoiceAllowOther;
+    submitLabel?: string;
+    dismissible?: boolean;
+};
+export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
+export type TasksTask = {
+    id: string;
+    label: string;
+    description?: string;
+    checked?: boolean;
+    disabled?: boolean;
+};
+export type TasksCardData = {
+    /**
+     * `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;
+    confirmLabel?: string;
+    allowEmpty?: boolean;
+    min?: number;
+    max?: number;
+    dismissible?: boolean;
+};
+export type TasksCardResult = {
+    selected: string[];
+};
+export type TasksCardEnvelope = CardEnvelope<'tasks', TasksCardData>;
+/** A field definition (the JSON Schema subset kai-form renders). */
+export type FormField = {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    format?: 'email' | 'uri' | 'url' | 'date' | 'date-time' | 'time';
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    items?: FormField | {
+        enum: unknown[];
+    };
+    properties?: Record<string, FormField>;
+    required?: string[];
+    readOnly?: boolean;
+    'x-kai-widget'?: 'textarea' | 'slider' | 'rating' | 'radio' | 'select' | 'checkbox' | 'password' | 'switch';
+    'x-kai-placeholder'?: string;
+    'x-kai-step'?: number;
+};
+/** The form definition = CardEnvelope.data for type:'form'. */
+export type FormDefinition = {
+    type: 'object';
+    title?: string;
+    description?: string;
+    required?: string[];
+    properties: Record<string, FormField>;
+    'x-kai-order'?: string[];
+    'x-kai-inlineMax'?: number;
+    'x-kai-submitLabel'?: string;
+    'x-kai-dismissible'?: boolean;
+    'x-kai-actions'?: {
+        id: string;
+        label: string;
+        variant?: 'default' | 'ghost' | 'outline';
+    }[];
+};
+export type FormCardEnvelope = CardEnvelope<'form', FormDefinition>;
+/**
+ * One file behind an artifact card: the Code tab's tree row, plus where the
+ * preview loads it.
+ *
+ * The SAME declaration the `FileTree` primitive uses — `components/file-tree.tsx`
+ * re-exports this as `FileTreeFile` and `components/artifact.tsx` aliases that to
+ * `ArtifactFile`, so there is one shape here and not a copy of one. It is authored
+ * in this file rather than in file-tree.tsx for this module's whole reason: it is
+ * reachable from `ArtifactCardData`, so leaving it in a `.tsx` would put TS6142
+ * back on any Node/no-DOM project that names an artifact card payload, and the
+ * extraction would have moved four of five types and quietly failed on the fifth.
+ * It mirrors `artifact.schema.json`'s `files[].items`, which carries the same
+ * fields with `additionalProperties: false`.
+ */
+export type ArtifactCardFile = {
+    /** Tree label/key. Folders are built from `/`-delimited segments. */
+    path: string;
+    /** Where the preview loads it (CDN/S3/dev-server/API). */
+    url?: string;
+    /** Source for the Code tab. */
+    code?: string;
+    /** Language id for syntax highlighting (e.g. `html`, `css`, `tsx`). */
+    language?: string;
+    /** Kind — drives the icon + whether Code applies. */
+    type?: 'html' | 'pdf' | 'image' | 'other';
+    /** Lines added vs the base. Rendered as a trailing `+N` stat (success hue,
+     *  tabular-nums). Only shown when present; omit for a plain file row. */
+    additions?: number;
+    /** Lines removed vs the base. Rendered as a trailing `-N` stat (error hue). */
+    deletions?: number;
+    /** Change status vs the base. Drives a small trailing status letter in the
+     *  conventional VCS hue (added=green, modified=amber, deleted=red,
+     *  renamed=blue, untracked=muted). Only shown when present. */
+    status?: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked';
+};
+/** Which view an artifact card opens on. */
+export type ArtifactCardTab = 'preview' | 'code';
+/** The `artifact` card payload: a deliberately NARROW subset of `ArtifactProps`.
+ *
+ *  A card envelope is written by a model, so the surface it can reach has to be
+ *  the part that describes WHAT to show, not how the viewer behaves. Toolbar
+ *  composition (`showNav`/`showTabs`/…), view-state (`maximized`), the iframe
+ *  `sandbox` and the imperative `controllerRef` are all host concerns and stay
+ *  off the wire — a model must not be able to widen its own sandbox or hide the
+ *  chrome the user needs to inspect what it built. */
+export type ArtifactCardData = {
+    /** URL the preview iframe frames. */
+    src?: string;
+    /** Files for the Code tab's tree (+ each file's preview `url`). */
+    files?: ArtifactCardFile[];
+    /** Which view the card OPENS on: `preview` (default) or `code`.
+     *
+     *  Seed only, and deliberately so. This card exists to be revised — `addCard`
+     *  upserts on `envelope.id` — and a revision hands the same live component a
+     *  new envelope. Were this wired to `Artifact`'s CONTROLLED `tab` prop, every
+     *  revision would re-assert it and yank a user who had switched views back to
+     *  the model's choice. A model cannot move the user between tabs after the
+     *  first render; the user's choice wins. */
+    tab?: ArtifactCardTab;
+    /** Path of the file selected in the tree when the card first renders.
+     *
+     *  Seed only, for the same reason as `tab`, but achieved differently:
+     *  `Artifact` has a `defaultTab` prop to seed the tab and no `defaultActiveFile`
+     *  counterpart, so this is read ONCE via `untrack` at setup and handed over as
+     *  a static value. That leaves `Artifact`'s unconditional
+     *  `createEffect(() => setActiveFile(local.activeFile))` with nothing reactive
+     *  to track, so it runs once instead of resetting the user's selection on
+     *  every revision. Keep it static — passing `props.data.activeFile` straight
+     *  through would silently restore that bug. */
+    activeFile?: string;
+    /** Friendly address shown INSTEAD of the real url. Use when `src` is not
+     *  consumer-facing (e.g. a `data:` blob) so a clean address is shown. */
+    displayUrl?: string;
+    /** Frame height. A bare number is px; a string is any CSS length. Defaults to
+     *  `DEFAULT_ARTIFACT_CARD_HEIGHT` — see the note on ArtifactCard. */
+    height?: number | string;
+};
+export type ArtifactCardEnvelope = CardEnvelope<'artifact', ArtifactCardData>;

package/dist/primitives/card-host.d.ts

@@ -1,5 +1,5 @@
 import { JSX } from 'solid-js';
-import { CardContext, CardHost, CardPolicy } from './card-contract';
+import { CardContext, CardHost, CardPolicy } from './card-contract.js';
 export interface CardProviderProps {
     /** Ambient context, static or a reactive getter. */
     context: CardContext | (() => CardContext);

package/dist/primitives/card-recovery.d.ts

@@ -1,4 +1,4 @@
-import { CardEnvelope, CardPolicy, CardResolution } from './card-contract';
+import { CardEnvelope, CardPolicy, CardResolution } from './card-contract.js';
 /** The minimal toast surface this helper needs. Inject a real adapter (e.g. one
  *  backed by `kai-toast-region`) — this module never imports the toast itself. */
 export interface RecoveryToast {
@@ -44,7 +44,7 @@ export interface DismissRecoveryOptions {
 export declare function defaultIsReopenable(env: ReopenEnv, staleAfterMs?: number): boolean;
 /**
  * Build the `{ onDismiss, onReopen }` policy handlers for the card dismiss/recovery
- * flow over a host store (`get`/`set`).
+ * flow over a host store (`get`/`set`). Both handlers are always returned.
  *
  * - `onDismiss(cardId)` — stamps `{ kind:'dismissed', at }` immutably and, when a
  *   `toast` is injected, shows "Dismissed" with an Undo that restores the card's
@@ -52,4 +52,4 @@ export declare function defaultIsReopenable(env: ReopenEnv, staleAfterMs?: numbe
  * - `onReopen(cardId)` — clears the resolution (live) when `isReopenable`, else
  *   stamps `{ kind:'expired', at }`.
  */
-export declare function dismissRecovery(opts: DismissRecoveryOptions): Pick<CardPolicy, 'onDismiss' | 'onReopen'>;
+export declare function dismissRecovery(opts: DismissRecoveryOptions): Required<Pick<CardPolicy, 'onDismiss' | 'onReopen'>>;

package/dist/primitives/card-registry.d.ts

@@ -1,17 +1,7 @@
-import { Component } from 'solid-js';
-import { CardEnvelope, CardHost } from './card-contract';
-/** Solid renderer for one envelope. `host` is the resolved CardHost so each wrapper
- *  can bridge its card's emit convention (form/confirm/tasks take `host`;
- *  link/embed take `onEmit`). */
-export type CardComponent = Component<{
-    envelope: CardEnvelope;
-    host?: CardHost;
-}>;
-export type CardComponentMap = Record<string, CardComponent>;
-/** Web-component layer: envelope type → kai-* tag name. */
-export type CardTagMap = Record<string, string>;
-export declare const BUILTIN_CARD_TAGS: CardTagMap;
+import { CardComponentMap } from './card-component-types.js';
+export { BUILTIN_CARD_TAGS, mergeCardTags } from './card-tags.js';
+export type { CardTagMap } from './card-tags.js';
+export type { CardComponent, CardComponentMap } from './card-component-types.js';
 export declare const BUILTIN_CARD_COMPONENTS: CardComponentMap;
 /** Built-ins with the consumer's overrides merged on top (consumer wins). */
 export declare function mergeCardComponents(types?: CardComponentMap): CardComponentMap;
-export declare function mergeCardTags(types?: CardTagMap): CardTagMap;

package/dist/primitives/card-resolution.d.ts

@@ -1,4 +1,4 @@
-import { CardEnvelope, CardEvent, CardResolution } from './card-contract';
+import { CardEnvelope, CardEvent, CardResolution } from './card-contract.js';
 /** Map a terminal CardEvent (`action` | `submit`) to a CardResolution.
  *  Returns undefined for every non-terminal verb (ready/error/resize/state/…). */
 export declare function resolutionFromEvent(event: CardEvent): CardResolution | undefined;

package/dist/primitives/card-routing.d.ts

@@ -1,4 +1,4 @@
-import { CardEvent, CardPolicy } from './card-contract';
+import { CardEvent, CardPolicy } from './card-contract.js';
 /** The single contract event name. */
 export declare const CARD_EVENT_NAME = "kai-card";
 /** Dispatch a CardEvent as the bubbling, composed `kai-card` event a host listener

package/dist/primitives/card-tags.d.ts

@@ -0,0 +1,11 @@
+/** Web-component layer: envelope type → kai-* tag name. */
+export type CardTagMap = Record<string, string>;
+/**
+ * The seven built-in card types and the element that draws each one.
+ *
+ * Note `link` → `kai-link-preview`: the one entry that is NOT `kai-<type>`, and the
+ * reason inferring these from the tag list is a guess rather than a lookup.
+ */
+export declare const BUILTIN_CARD_TAGS: CardTagMap;
+/** Built-ins with the consumer's overrides merged on top (consumer wins). */
+export declare function mergeCardTags(types?: CardTagMap): CardTagMap;

package/dist/primitives/card-validate-cards.d.ts

@@ -0,0 +1,57 @@
+import { JsonSchema, ValidationIssue } from './card-validate.js';
+import { ValidatedCardType } from './card-validate-schemas.js';
+export type { ValidatedCardType } from './card-validate-schemas.js';
+export { CARD_VALIDATION_SCHEMAS } from './card-validate-schemas.js';
+/** How badly a failed constraint hurts the rendered card. */
+export type CardValidationTier = 'hard' | 'soft';
+export interface CardValidationIssue extends ValidationIssue {
+    tier: CardValidationTier;
+}
+export interface CardValidationReport {
+    /** True when nothing failed. A SOFT-only report is not `ok`. */
+    ok: boolean;
+    /** `hard` if any issue is hard, else `soft` if any issue is soft, else `ok`. */
+    tier: CardValidationTier | 'ok';
+    /** Every failure, hard and soft, in the validator's order. */
+    issues: CardValidationIssue[];
+    /** The hard issues only. Non-empty exactly when `tier === 'hard'`. */
+    hard: CardValidationIssue[];
+    /** One line naming the failing field paths. Safe to render and to log. */
+    summary: string;
+}
+/** True when this envelope type has a BUILT-IN projected schema to validate against. */
+export declare function isValidatedCardType(type: string): type is ValidatedCardType;
+/**
+ * Validate a card envelope's `data` against the schema for `type`.
+ *
+ * Returns `null` when there is no schema for the type at all. Returning `null` rather
+ * than an empty pass keeps "we checked and it was fine" distinguishable from "there
+ * was nothing to check", so a caller cannot report the second as the first.
+ *
+ * @param schemas consumer-registered schemas by card type, normally
+ * `registry.validationSchemas` from `createCardRegistry`. Without it this function
+ * knows only the seven built-ins, which would mean a developer's own pricing-table
+ * card, registered perfectly legally through `cardTypes`, is the one card in the app
+ * nothing checks. The custom entry wins over a built-in of the same name; see
+ * {@link schemaFor}.
+ *
+ * A consumer schema is used AS AUTHORED rather than through the build-time lean
+ * projection the built-ins get, because that projection is a bundle-size measure and
+ * cannot run over a schema this package has never seen. The practical difference is
+ * only weight: `validateAgainstSchema` ignores every keyword it does not implement, so
+ * a custom schema is checked to exactly the same depth as a built-in, with the same
+ * NOT_ENFORCED gaps (no `allOf`/`anyOf`/`oneOf`/`if`, no `$ref`, no
+ * `additionalProperties`, no `format`).
+ */
+export declare function validateCardData(type: string, data: unknown, schemas?: Readonly<Record<string, JsonSchema>>): CardValidationReport | null;
+/**
+ * The message both native dispatchers put on the `error` CardEvent.
+ *
+ * Spelled once, here, and prefixed `invalid card data:` to match what
+ * provider-runtime.ts already emits for the remote transport, so a consumer's
+ * `policy.onError` sees the same string shape regardless of which transport the card
+ * arrived through.
+ */
+export declare function cardValidationMessage(report: CardValidationReport): string;
+/** Exposed for the tier-coverage test, which asserts it against the validator. */
+export declare const TIERS_BY_KEYWORD: Readonly<Record<string, CardValidationTier>>;

package/dist/primitives/card-validate-generator.testlib.d.ts

@@ -0,0 +1,20 @@
+/** One keyword the projection could not account for, with where it was found. */
+export interface UnclassifiedKeyword {
+    path: string;
+    keyword: string;
+}
+export interface CardValidationGenerator {
+    CARD_TYPES: string[];
+    STRIPPED: Readonly<Record<string, string>>;
+    NOT_ENFORCED: Readonly<Record<string, string>>;
+    OUT_FILE: string;
+    enforcedKeywords(source?: string): Set<string>;
+    scanUnclassified(doc: unknown, enforced: Set<string>): UnclassifiedKeyword[];
+    projectSchema(doc: unknown, enforced: Set<string>): Record<string, unknown> | undefined;
+    build(): {
+        enforced: Set<string>;
+        projections: Record<string, unknown>;
+        source: string;
+    };
+}
+export declare function loadGenerator(): Promise<CardValidationGenerator>;

package/dist/primitives/card-validate-schemas.d.ts

@@ -0,0 +1,17 @@
+import { JsonSchema } from './card-validate.js';
+/** The built-in `CardEnvelope.type` values that have a schema to validate against. */
+export type ValidatedCardType = "artifact" | "choice" | "confirm" | "embed" | "form" | "link" | "tasks";
+/**
+ * One widening cast, at the module boundary, for the same reason
+ * src/schemas/index.ts has one: TypeScript infers `string` for a `"type"` member
+ * written as a literal in an object literal, while `JsonSchema['type']` is a union
+ * of string literals, so these documents are not assignable without it. The
+ * alternative (`as const` throughout) makes every `required` array `readonly`,
+ * which `JsonSchema` does not accept either.
+ *
+ * The cast is not a claim about the contents. What it would otherwise hide is
+ * checked by the sync test, which re-runs this generator and compares byte for byte.
+ */
+export declare const CARD_VALIDATION_SCHEMAS: Readonly<Record<ValidatedCardType, JsonSchema>>;
+/** The card types this projection covers, in a stable order. */
+export declare const VALIDATED_CARD_TYPES: readonly ValidatedCardType[];

package/dist/primitives/card-validate.d.ts

@@ -17,9 +17,33 @@ export interface JsonSchema {
     uniqueItems?: boolean;
     [key: `x-${string}`]: unknown;
 }
+/**
+ * One failed constraint, with the KEYWORD that failed kept separate from the prose.
+ *
+ * `errors` (the string form) is what every existing caller reads and it is unchanged.
+ * This structured twin exists because the native card dispatcher has to TIER a
+ * failure (a missing `required` field means the card cannot render, a `maxItems`
+ * overrun means it renders five buttons instead of four), and the only honest way to
+ * tell those apart is the keyword. Re-parsing the prose to recover it would be a
+ * second, silently-drifting copy of the same fact.
+ */
+export interface ValidationIssue {
+    /** Where, in readable form: `(root)`, `(root).actions`, `(root).actions[0].id`. */
+    path: string;
+    /** The JSON Schema keyword that failed. `required` for a missing property. */
+    keyword: string;
+    /** The human-readable message; identical to the matching entry in `errors`. */
+    message: string;
+}
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
+    /**
+     * The same failures as `errors`, one-for-one and in the same order, with the
+     * keyword and path kept as data. Added alongside `errors` rather than replacing
+     * it so no existing caller changes.
+     */
+    issues: ValidationIssue[];
 }
 /** Validate `value` against the lean JSON-Schema subset. */
 export declare function validateAgainstSchema(schema: JsonSchema, value: unknown): ValidationResult;

package/dist/primitives/create-kai-chat.d.ts

@@ -1,6 +1,6 @@
-import { ChatMessage } from '../elements/chat-types';
-import { AttachmentData } from '../components/attachments';
-import { AssistantStream, SetMessages } from '../state';
+import { ChatMessage } from '../elements/chat-types.js';
+import { AttachmentData } from '../components/attachments.js';
+import { AssistantStream, SetMessages } from '../state.js';
 export interface CreateKaiChatOptions {
     /** Seed messages, read once at creation and copied. Later changes are ignored — drive updates through the returned ops. */
     initialMessages?: ChatMessage[];

package/dist/primitives/embed-providers.d.ts

@@ -1,4 +1,4 @@
-import { CardEnvelope } from './card-contract';
+import { CardEnvelope } from './card-contract.js';
 /** Media provider for an embed card. */
 export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
 /** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */

package/dist/primitives/link-preview.d.ts

@@ -1,4 +1,4 @@
-import { CardEnvelope } from './card-contract';
+import { CardEnvelope } from './card-contract.js';
 /** Rich link / Open-Graph preview payload. The card renders from this; it never fetches. */
 export interface LinkPreviewData {
     /** Canonical destination; opened via the contract `open` verb. */

package/dist/primitives/message-feedback.d.ts

@@ -1,4 +1,4 @@
-import { ChatMessage, FeedbackVote } from '../elements/chat-types';
+import { ChatMessage, FeedbackVote } from '../elements/chat-types.js';
 /** Detail shape emitted by the action row. `state` is present only for the
  *  toggleable feedback votes: `'on'` when a vote is set, `'off'` when cleared.
  *  Copy / regenerate / edit / custom actions omit it. */
@@ -24,7 +24,7 @@ export interface MessageFeedback {
     /** Whether a message's copy button should currently show its check. */
     isCopied: (id: string) => boolean;
     /** Route a clicked action through copy / vote / passthrough handling. */
-    handleAction: (m: Pick<ChatMessage, 'id' | 'content' | 'feedback'>, action: string) => void;
+    handleAction: (m: Pick<ChatMessage, 'id' | 'parts' | 'feedback'>, action: string) => void;
 }
 /**
  * Create the action-row feedback controller for one message list (or one

package/dist/primitives/toast-store.d.ts

@@ -1,4 +1,4 @@
-import { ToastPosition } from '../components/toast';
+import { ToastPosition } from '../components/toast.js';
 export type ToastVariant = 'neutral' | 'success' | 'warning' | 'error' | 'info';
 /** Visual treatment: `'pill'` (default, compact single-line) or `'card'` (richer
  *  rounded card with an optional description line). */