@kitn.ai/ui 0.15.0 → 0.16.0

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

@@ -0,0 +1,103 @@
+/** Bumped on any BREAKING change to the shapes below. Additive/optional fields do not bump it. */
+export declare const CARD_CONTRACT_VERSION: "1";
+/** A card the agent/server asks the chat to render. `data` conforms to the card
+ *  type's own published JSON Schema (one schema per `type`). */
+export interface CardEnvelope<TType extends string = string, TData = unknown> {
+    type: TType;
+    id: string;
+    data: TData;
+    title?: string;
+    /** Set when the user has resolved this card; renders the chromed read-only view. */
+    resolution?: CardResolution;
+}
+/** Context the host pushes to every card; updated when it changes (theme, etc.). */
+export interface CardContext {
+    theme: {
+        mode: 'light' | 'dark';
+        tokens?: Record<string, string>;
+    };
+    locale: string;
+    conversationId?: string;
+    /** Remote (iframe) cards only: short-lived signed token. Never long-lived. */
+    authToken?: string;
+    /** Host-resolved a11y prefs (e.g. reduced-motion, which doesn't cross the iframe). */
+    a11y?: {
+        reducedMotion?: boolean;
+    };
+}
+/** Everything a card can ask the host to do. The host authorizes + routes each. */
+export type CardEvent = {
+    kind: 'ready';
+    cardId: string;
+} | {
+    kind: 'submit';
+    cardId: string;
+    data: unknown;
+} | {
+    kind: 'action';
+    cardId: string;
+    action: string;
+    payload?: unknown;
+} | {
+    kind: 'send-prompt';
+    cardId: string;
+    text: string;
+    mode?: 'compose' | 'send';
+    context?: unknown;
+} | {
+    kind: 'open';
+    cardId: string;
+    url: string;
+    target?: 'tab' | 'artifact';
+} | {
+    kind: 'resize';
+    cardId: string;
+    height: number;
+} | {
+    kind: 'state';
+    cardId: string;
+    patch: unknown;
+} | {
+    kind: 'dismiss';
+    cardId: string;
+} | {
+    kind: 'error';
+    cardId: string;
+    message: string;
+};
+export type CardEventKind = CardEvent['kind'];
+/** How a card was resolved by the user — the re-hydration channel for the chromed
+ *  read-only state. Mirrors the two terminal CardEvents (minus `cardId`): the
+ *  resolution is just the event that resolved the card. `at` is optional ISO-8601
+ *  provenance (data only; never rendered). Additive — does not bump the contract
+ *  version. */
+export type CardResolution = {
+    kind: 'action';
+    action: string;
+    payload?: unknown;
+    at?: string;
+} | {
+    kind: 'submit';
+    data: unknown;
+    at?: string;
+};
+/** What every card is handed (via native context or the iframe bridge). */
+export interface CardHost {
+    context(): CardContext;
+    emit(event: CardEvent): void;
+}
+/** How the host routes each verb. Consumers supply handlers; defaults applied otherwise. */
+export interface CardPolicy {
+    onSubmit?: (cardId: string, data: unknown) => void;
+    onAction?: (cardId: string, action: string, payload?: unknown) => void;
+    onSendPrompt?: (text: string, opts: {
+        mode: 'compose' | 'send';
+        context?: unknown;
+    }) => void;
+    onOpen?: (url: string, target: 'tab' | 'artifact') => void;
+    onState?: (cardId: string, patch: unknown) => void;
+    onDismiss?: (cardId: string) => void;
+    onError?: (cardId: string, message: string) => void;
+    /** Cap on send-prompt: 'compose' (default) forbids silent sends. 'send' to allow. */
+    maxSendPromptMode?: 'compose' | 'send';
+}

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

@@ -0,0 +1,12 @@
+import { JSX } from 'solid-js';
+import { CardContext, CardHost, CardPolicy } from './card-contract';
+export interface CardProviderProps {
+    /** Ambient context, static or a reactive getter. */
+    context: CardContext | (() => CardContext);
+    /** Routing policy applied to every emitted event. */
+    policy?: CardPolicy;
+    children: JSX.Element;
+}
+export declare function CardProvider(props: CardProviderProps): JSX.Element;
+/** Read the current CardHost. `undefined` when no provider is present (bare card). */
+export declare function useCardHost(): CardHost | undefined;

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

@@ -0,0 +1,17 @@
+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;
+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

@@ -0,0 +1,8 @@
+import { CardEnvelope, CardEvent, CardResolution } from './card-contract';
+/** 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;
+/** Return a new cards array with the envelope matching `event.cardId` stamped with its
+ *  resolution. Non-terminal events or an unknown cardId return the SAME array reference
+ *  (cheap no-op; safe to call on every event). Never mutates the input. */
+export declare function applyResolution(cards: CardEnvelope[], event: CardEvent): CardEnvelope[];

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

@@ -0,0 +1,12 @@
+import { CardEvent, CardPolicy } from './card-contract';
+/** 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
+ *  routes. NB: this is deliberately different from defineWebComponent's built-in
+ *  non-bubbling dispatch. */
+export declare function emitCardEvent(element: HTMLElement, event: CardEvent): void;
+/** Apply the contract's policy to one event. The ONE place routing lives. */
+export declare function routeCardEvent(policy: CardPolicy | undefined, event: CardEvent): void;
+/** Attach a host-level `kai-card` listener that routes every bubbling card event
+ *  through `policy`. Returns an unsubscribe fn. For the bare-element path. */
+export declare function listenForCardEvents(root: HTMLElement | Document, policy: CardPolicy): () => void;

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

@@ -0,0 +1,25 @@
+export interface JsonSchema {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+    const?: unknown;
+    enum?: unknown[];
+    required?: string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    [key: `x-${string}`]: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Validate `value` against the lean JSON-Schema subset. */
+export declare function validateAgainstSchema(schema: JsonSchema, value: unknown): ValidationResult;

package/dist/primitives/chat-config.d.ts

@@ -0,0 +1,31 @@
+import { Accessor, JSX } from 'solid-js';
+export type ProseSize = 'xs' | 'sm' | 'base' | 'lg';
+export interface ChatConfigValue {
+    /** Prose/text size for messages, markdown, and UI elements */
+    proseSize: Accessor<ProseSize>;
+    /** Shiki theme for code blocks */
+    codeTheme: Accessor<string>;
+    /** Node the kit's overlays portal into; undefined → document.body */
+    portalMount: Accessor<HTMLElement | undefined>;
+    /** Whether code blocks are syntax-highlighted; false → plain text, no Shiki loaded */
+    codeHighlight: Accessor<boolean>;
+}
+export interface ChatConfigProps {
+    proseSize?: ProseSize;
+    codeTheme?: string;
+    portalMount?: HTMLElement;
+    codeHighlight?: boolean;
+    children: JSX.Element;
+}
+/**
+ * Provides chat-wide appearance settings to all child components.
+ * Set once at the top level — MessageContent, Markdown, CodeBlock,
+ * ConversationList, and PromptInput all read from this.
+ */
+export declare function ChatConfig(props: ChatConfigProps): JSX.Element;
+/** Read the current chat config. Returns defaults if no provider is present. */
+export declare function useChatConfig(): ChatConfigValue;
+/** Maps prose size to Tailwind prose class */
+export declare function proseClass(size: ProseSize): string;
+/** Maps prose size to a text class for non-prose elements (sidebar, input) */
+export declare function textClass(size: ProseSize): string;

package/dist/primitives/controllable.d.ts

@@ -0,0 +1,13 @@
+import { Accessor } from 'solid-js';
+/**
+ * The controlled/uncontrolled state pattern, as a reusable signal.
+ *
+ * `controlled` is an accessor for the controlling prop: when it returns a value,
+ * that value wins (controlled mode); when it returns `undefined`, the component
+ * manages its own state seeded from `initial` (uncontrolled mode). The returned
+ * setter always writes the internal value — harmless (masked) while controlled,
+ * authoritative while uncontrolled — so a single call site works in both modes.
+ *
+ * Mirrors `props.value ?? internal()` used elsewhere in the kit, without effects.
+ */
+export declare function createControllableSignal(controlled: Accessor<boolean | undefined>, initial: boolean): [Accessor<boolean>, (value: boolean) => void];

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

@@ -0,0 +1,65 @@
+import { CardEnvelope } from './card-contract';
+/** Media provider for an embed card. */
+export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
+/** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */
+export interface EmbedCardData {
+    /** Media provider. 'generic' frames `url` directly. */
+    provider: EmbedProvider;
+    /** Provider video id (youtube/vimeo) when not parsing from `url`. */
+    id?: string;
+    /** Full media/watch/embed URL. */
+    url?: string;
+    /** Accessible iframe title + poster label. */
+    title?: string;
+    /** Thumbnail before play; derived for youtube/vimeo when omitted. */
+    poster?: string;
+    /** Start offset, seconds. */
+    start?: number;
+    /** Player aspect ratio. Default '16:9'. */
+    aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
+}
+/** The full envelope an agent/server emits for an embed card. */
+export type EmbedCardEnvelope = CardEnvelope<'embed', EmbedCardData>;
+/** The `type` discriminator for embed cards. */
+export declare const EMBED_CARD_TYPE: "embed";
+export interface ResolvedEmbed {
+    /** The iframe src loaded on play (already including autoplay/start params). */
+    embedUrl: string;
+    /** Poster/thumbnail to show before play (derived when not supplied). */
+    posterUrl?: string;
+    /** sandbox attribute for the player iframe. */
+    sandbox: string;
+    /** allow attribute (fullscreen, encrypted-media, picture-in-picture, …). */
+    allow: string;
+}
+/**
+ * App opt-in: allow `generic` embeds whose origin is in this list. Origins are
+ * normalized via the URL parser (scheme + host + port). Only https origins are
+ * accepted (a non-https origin is ignored). Call once at app startup.
+ */
+export declare function configureEmbedAllowlist(origins: string[]): void;
+/** True when `url`'s origin has been allowlisted for `generic` embeds. */
+export declare function isGenericOriginAllowed(url: string): boolean;
+/** Test-only: clear the generic allowlist so tests stay isolated. */
+export declare function __resetEmbedAllowlistForTests(): void;
+/** Extract a YouTube id from a watch / youtu.be / shorts / embed URL. */
+export declare function parseYouTubeId(url: string): string | undefined;
+/** Extract a Vimeo id from a vimeo.com/<id> (or player.vimeo.com/video/<id>) URL. */
+export declare function parseVimeoId(url: string): string | undefined;
+/**
+ * Resolve an EmbedCardData to an embeddable player URL + poster + sandbox/allow.
+ * Throws (with a human message) on a missing/invalid provider id, a non-https
+ * generic URL, or a generic origin not in the app allowlist — the card turns these
+ * into an inline error + an `error` event.
+ */
+export declare function resolveEmbed(data: EmbedCardData): ResolvedEmbed;
+/**
+ * The canonical "watch on the provider" URL for the optional fallback affordance
+ * (emitted as `open`/target:'tab' when an embed is blocked). Returns `undefined`
+ * when there is nothing useful to link to.
+ */
+export declare function watchUrl(data: EmbedCardData): string | undefined;
+/** Human-readable provider label for the fallback affordance ("Open on YouTube"). */
+export declare function providerLabel(provider: EmbedProvider): string;
+/** CSS aspect-ratio value for a card's aspectRatio (default 16:9). */
+export declare function aspectRatioValue(aspectRatio: EmbedCardData['aspectRatio']): string;

package/dist/primitives/highlighter.d.ts

@@ -0,0 +1,23 @@
+type Loader = () => Promise<unknown>;
+export interface CodeHighlightingOptions {
+    /** Turn highlighting on/off globally. When false, code renders as plain text. */
+    enabled?: boolean;
+    /** Register/override language loaders, e.g. `{ ruby: () => import('@shikijs/langs/ruby') }`. */
+    languages?: Record<string, Loader>;
+    /** Register/override theme loaders. */
+    themes?: Record<string, Loader>;
+    /** Map short names to canonical language keys, e.g. `{ vue: 'html' }`. */
+    aliases?: Record<string, string>;
+}
+/**
+ * Highlight `code` as `lang` with `theme`, returning HTML. Loads only what's
+ * needed, on demand. Falls back to escaped plain `<pre><code>` when highlighting
+ * is disabled, the language has no registered loader, or anything fails.
+ */
+export declare function highlight(code: string, lang: string, theme: string): Promise<string>;
+/** Register additional languages/themes/aliases, or disable highlighting entirely. */
+export declare function configureCodeHighlighting(options: CodeHighlightingOptions): void;
+export declare function isCodeHighlightingEnabled(): boolean;
+/** Test helper — reset the singleton and registries to defaults. */
+export declare function __resetCodeHighlightingForTests(): void;
+export {};

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

@@ -0,0 +1,47 @@
+import { CardEnvelope } from './card-contract';
+/** 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. */
+    url: string;
+    /** og:title — falls back to the domain. */
+    title?: string;
+    /** og:description — clamped to 3 lines. */
+    description?: string;
+    /** og:image — degrades gracefully when missing/broken. */
+    image?: string;
+    /** Alt for the preview image (defaults to title / decorative). */
+    imageAlt?: string;
+    /** Site favicon. */
+    favicon?: string;
+    /** Display domain; derived from `url` when omitted. */
+    domain?: string;
+    /** og:site_name; preferred over `domain` when present. */
+    siteName?: string;
+}
+/** The full envelope an agent/server emits for a link preview card. */
+export type LinkPreviewEnvelope = CardEnvelope<'link', LinkPreviewData>;
+/** The `type` discriminator for link preview cards. */
+export declare const LINK_PREVIEW_TYPE: "link";
+/** App-supplied resolver: a bare URL → (partial) OG metadata. Usually hits YOUR backend. */
+export type LinkMetadataFetcher = (url: string) => Promise<Partial<LinkPreviewData>>;
+/**
+ * App opt-in: supply a function (usually hitting YOUR backend/proxy) that resolves
+ * a bare URL to OG metadata. CORS forbids reading cross-origin HTML in the browser,
+ * so there is intentionally NO default network implementation.
+ */
+export declare function configureLinkPreview(opts: {
+    fetchMetadata: LinkMetadataFetcher;
+}): void;
+/** True when an app has registered a fetcher (the bare-URL path is available). */
+export declare function hasLinkPreviewFetcher(): boolean;
+/**
+ * Used by LinkPreview ONLY when the envelope lacks metadata AND a fetcher is set.
+ * Returns the merged metadata or throws (card shows its fallback/error state).
+ */
+export declare function resolveLinkMetadata(url: string): Promise<Partial<LinkPreviewData>>;
+/** Test-only: clear the configured fetcher so tests stay isolated. */
+export declare function __resetLinkPreviewForTests(): void;
+/** Derive a clean display domain from a URL (strips a leading `www.`). `undefined` if unparseable. */
+export declare function deriveDomain(url: string): string | undefined;
+/** True when `url` is a syntactically valid http(s) URL (the only renderable link schemes). */
+export declare function isRenderableLink(url: string): boolean;

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

@@ -0,0 +1,50 @@
+/** Minimal shape of the pdf.js module + objects we rely on. */
+export interface PdfViewportLike {
+    width: number;
+    height: number;
+}
+export interface PdfPageLike {
+    getViewport(opts: {
+        scale: number;
+    }): PdfViewportLike;
+    render(opts: {
+        canvasContext: CanvasRenderingContext2D | null;
+        viewport: PdfViewportLike;
+    }): {
+        promise: Promise<void>;
+    };
+}
+export interface PdfDocumentLike {
+    numPages: number;
+    getPage(n: number): Promise<PdfPageLike>;
+}
+export interface PdfjsLike {
+    getDocument(src: {
+        url: string;
+    }): {
+        promise: Promise<PdfDocumentLike>;
+    };
+    GlobalWorkerOptions: {
+        workerSrc: string;
+    };
+}
+export interface PdfPreviewOptions {
+    /** Turn inline PDF rendering on/off globally. When false, always show the card. */
+    enabled?: boolean;
+    /** Override the pdf.js module loader (self-host / CSP / version pin). */
+    load?: () => Promise<PdfjsLike>;
+    /** Worker URL. Default = the matching jsDelivr worker for the pinned version. */
+    workerSrc?: string;
+}
+export declare function configurePdfPreview(options: PdfPreviewOptions): void;
+export declare function isPdfPreviewEnabled(): boolean;
+export declare function __resetPdfPreviewForTests(): void;
+/**
+ * Render EVERY page of the PDF at `url` into `container` as stacked <canvas>
+ * elements fit to `pxWidth` CSS pixels (rendered at devicePixelRatio for
+ * crispness). Clears `container` first. Resolves `{ pages }`. THROWS on
+ * load / CORS / parse failure — the caller catches and shows the fallback card.
+ */
+export declare function renderPdfInto(url: string, container: HTMLElement, pxWidth: number): Promise<{
+    pages: number;
+}>;

package/dist/primitives/use-auto-resize.d.ts

@@ -0,0 +1,8 @@
+interface UseAutoResizeOptions {
+    maxHeight?: number;
+}
+export declare function useAutoResize(options?: UseAutoResizeOptions): {
+    ref: (el: HTMLTextAreaElement) => void;
+    resize: () => void;
+};
+export {};

package/dist/primitives/use-resize-observer.d.ts

@@ -0,0 +1 @@
+export declare function observeContentHeight(el: Element, onHeight: (height: number) => void): () => void;

package/dist/primitives/use-stick-to-bottom.d.ts

@@ -0,0 +1,5 @@
+export declare function useStickToBottom(): {
+    ref: (el: HTMLElement) => void;
+    isAtBottom: import('solid-js').Accessor<boolean>;
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+};

package/dist/primitives/use-text-stream.d.ts

@@ -0,0 +1,19 @@
+export interface UseTextStreamOptions {
+    mode: 'typewriter' | 'fade';
+    speed?: number;
+    characterChunkSize?: number;
+    fadeDuration?: number;
+}
+export interface TextStreamSegment {
+    text: string;
+    index: number;
+}
+export declare function useTextStream(options: UseTextStreamOptions): {
+    displayedText: import('solid-js').Accessor<string>;
+    isComplete: import('solid-js').Accessor<boolean>;
+    segments: import('solid-js').Accessor<TextStreamSegment[]>;
+    startStreaming: (source: string | AsyncIterable<string>) => void;
+    pause: () => void;
+    resume: () => void;
+    reset: () => void;
+};

package/dist/primitives/use-voice-recorder.d.ts

@@ -0,0 +1,9 @@
+export interface UseVoiceRecorderOptions {
+    mimeType?: string;
+}
+export declare function useVoiceRecorder(options?: UseVoiceRecorderOptions): {
+    isRecording: import('solid-js').Accessor<boolean>;
+    error: import('solid-js').Accessor<string | null>;
+    start: () => Promise<Blob>;
+    stop: () => void;
+};