@ai-matrx/content-ir-react 0.22.0 → 0.24.0

package/dist/kind-kit.d.ts

@@ -0,0 +1,418 @@
+import * as React from 'react';
+import { MatrxCopyMenuProps } from '@ai-matrx/alchemy/react/workspace';
+
+/**
+ * The kit's HOST SLOTS. The kit never imports app code; the three things it cannot own are
+ * handed in once by the host through `setKindKitHost`:
+ *   - `CopyButtons`   the copy bar `KindHeaderBar` renders for its `copy` prop;
+ *   - `ReadEmpty`     what `SortableList` / `TagList` show instead of an empty state while a
+ *                     read has not succeeded;
+ *   - `ReadStaleNotice` the notice above rows left on screen by a failed refresh.
+ * Each default is honest and working: a plain Copy button, and text that says what happened.
+ * State lives on globalThis under a Symbol.for key so two copies of the package share one host.
+ */
+
+/**
+ * The copy bar's props: exactly the design system's `MatrxCopyMenuProps`, so a host registers its
+ * own `CopyButtons` (which takes that shape) with no adapter. Type-only: no runtime import.
+ */
+type KindKitCopyProps = MatrxCopyMenuProps;
+type ReadStatus = "loading" | "error" | "ready";
+/** A read's outcome, handed to a list primitive's `read` prop. */
+interface ReadOutcome {
+    status: ReadStatus;
+    /** The failure itself, or a truthy flag when the read only says it failed. */
+    error?: unknown;
+    onRetry?: (() => void) | undefined;
+    /** What was read, in the reader's words: "your tasks". */
+    what?: string | undefined;
+    /** A successful read has already produced a value. */
+    hasData?: boolean | undefined;
+}
+interface KindKitReadEmptyProps {
+    read?: ReadOutcome | undefined;
+    loading?: React.ReactNode;
+    children?: React.ReactNode;
+}
+interface KindKitReadStaleNoticeProps {
+    read?: ReadOutcome | undefined;
+    className?: string;
+}
+interface KindKitHost {
+    CopyButtons: React.ComponentType<KindKitCopyProps>;
+    ReadEmpty: React.ComponentType<KindKitReadEmptyProps>;
+    ReadStaleNotice: React.ComponentType<KindKitReadStaleNoticeProps>;
+}
+/** Default copy bar: one "Copy" button that writes the `human` text (else the JSON) to the clipboard. */
+declare function DefaultCopyButtons({ label, human, json, size, className }: KindKitCopyProps): React.JSX.Element;
+/** Default: loading says it is loading; an error says what failed (with retry); ready shows the host's empty state. */
+declare function DefaultReadEmpty({ read, loading, children }: KindKitReadEmptyProps): React.JSX.Element;
+/** Default: when the latest read failed, the rows on screen may be out of date; says so, with retry. */
+declare function DefaultReadStaleNotice({ read, className }: KindKitReadStaleNoticeProps): React.JSX.Element | null;
+/** Register the host's copy bar and read notices. Call once at boot; a slot left out keeps its default. */
+declare function setKindKitHost(host: Partial<KindKitHost>): void;
+/** The slots in force: the host's where registered, the defaults elsewhere. */
+declare function getKindKitHost(): KindKitHost;
+/** Clear every registered slot (tests, hot reload). */
+declare function resetKindKitHost(): void;
+
+/**
+ * SortableList — drag-to-reorder list for kind components.
+ *
+ * The mandated reorder UX, built once: while a row is dragged, the rows it
+ * passes DISPLACE (translate) out of the way and a SHADOWED placeholder marks
+ * exactly where the item will land. Native HTML5 drag-and-drop (no deps); a
+ * grab handle starts the drag (so text and inputs inside rows stay usable);
+ * up/down buttons are the keyboard + touch fallback; `onRemove` adds an inline
+ * remove control. Contract: `kind-kit/README.md`.
+ *
+ * Sandbox-safe by construction: imports only react, the design system,
+ * and `cn`.
+ */
+
+interface SortableRenderContext {
+    index: number;
+    /** True for the row currently being dragged (rendered as the placeholder). */
+    isDragging: boolean;
+}
+interface SortableListProps<T> {
+    /** Current order. Treated as read-only; the new order arrives via `onReorder`. */
+    items: readonly T[];
+    /**
+     * Stable key per item. Default: the item itself when it is a string, else
+     * `item.id` / `item.key` when present, else the index (unstable — pass one).
+     */
+    getKey?: (item: T, index: number) => string;
+    /** Called with the full reordered array after a drop or an arrow press. */
+    onReorder: (items: T[]) => void;
+    /**
+     * Row content. Default: the item when it is a string/number, else its
+     * `label` / `title` / `name` / `text` field, else `JSON.stringify`.
+     */
+    renderItem?: (item: T, ctx: SortableRenderContext) => React.ReactNode;
+    /** When set, every row gets an inline remove (X) control. */
+    onRemove?: (item: T, index: number) => void;
+    /** Disables drag, arrows and remove (rows still render). */
+    disabled?: boolean;
+    /** Hide the up/down arrow buttons (drag only). Default false. */
+    hideArrows?: boolean;
+    /** Shown when `items` is empty. */
+    emptyState?: React.ReactNode;
+    /**
+     * The outcome of the read behind the rows (RC-B12 r13). `emptyState` shows
+     * only after a read that succeeded; a failed read shows the failure + retry.
+     */
+    read?: ReadOutcome;
+    /** Wrapper `<ul>` className. */
+    className?: string;
+    /** Per-row className (applied to every `<li>`). */
+    itemClassName?: string;
+    /** Accessible name for the list. */
+    ariaLabel?: string;
+}
+declare function SortableList<T>({ items, getKey, onReorder, renderItem, onRemove, disabled, hideArrows, emptyState, read, className, itemClassName, ariaLabel, }: SortableListProps<T>): React.JSX.Element | null;
+
+/**
+ * KindPanelGrid — content-aware responsive grid for side-by-side panels.
+ *
+ * Never more columns than the content can afford: every track is at least
+ * `minColumnWidth` (default 280px) wide, the column count is whatever fits
+ * (`auto-fit`), and every panel in a row stretches to the same height so the
+ * panels' footers line up. Pair with `KindPanel` (its `footer` is pinned to
+ * the bottom). Contract: `kind-kit/README.md`.
+ */
+
+declare const GAP_PX: {
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+};
+interface KindPanelGridProps {
+    children: React.ReactNode;
+    /** Minimum width (px) of a column before the grid drops a column. Default 280. */
+    minColumnWidth?: number;
+    /** Hard ceiling on columns, however wide the container is. */
+    maxColumns?: number;
+    /** Space between panels. Default "md" (12px). */
+    gap?: keyof typeof GAP_PX;
+    /**
+     * "auto-fit" (default): a short last row lets panels grow to fill the width.
+     * "auto-fill": tracks stay the same width and the row is left short.
+     */
+    fill?: "auto-fit" | "auto-fill";
+    className?: string;
+}
+declare function KindPanelGrid({ children, minColumnWidth, maxColumns, gap, fill, className, }: KindPanelGridProps): React.JSX.Element;
+
+type KindKitIcon = React.ComponentType<{
+    className?: string;
+}> | React.ReactElement<{
+    className?: string;
+}>;
+/** Render either icon authoring form without treating an element as a component type. */
+declare function renderKindKitIcon(icon: KindKitIcon | undefined, className: string): React.ReactElement | null;
+
+/**
+ * KindPanel — the standard panel for a kind component's sub-sections (a
+ * keyword bucket, an option card, a section of results).
+ *
+ * Layout is fixed so agent-authored panels come out right by construction:
+ *  - compact header: icon · title (wraps, never squeezed) · count · ≤2 inline
+ *    actions · an overflow menu that absorbs EVERY other control (no control
+ *    row ever gets crammed);
+ *  - full-width subline (a rationale, a hint) on its own line UNDER the
+ *    header — never beside the title;
+ *  - body;
+ *  - `footer` pinned to the bottom (flex column + mt-auto) so "Add" rows
+ *    line up across sibling panels in a `KindPanelGrid`.
+ * Contract: `kind-kit/README.md`.
+ */
+
+interface KindPanelMenuItem {
+    label: string;
+    onSelect: () => void;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    disabled?: boolean;
+    /** Renders in the destructive colour (delete, clear, reset). */
+    destructive?: boolean;
+    /** Draws a separator ABOVE this item. */
+    separatorBefore?: boolean;
+}
+interface KindPanelProps {
+    /** Header title. Wraps onto extra lines rather than truncating. */
+    title: React.ReactNode;
+    /** Lucide component or an already-created icon element shown before the title. */
+    icon?: KindKitIcon;
+    /** Count pill after the title (e.g. number of items). */
+    count?: number | string;
+    /** Any extra pill/badge after the count (a status, a score). */
+    badge?: React.ReactNode;
+    /** Shows a spinner in the header while this panel's data is still arriving. */
+    streaming?: boolean;
+    /**
+     * At most one or two compact controls rendered inline on the right of the
+     * header (a toggle, a tiny icon button). Put everything else in `menuItems`.
+     */
+    actions?: React.ReactNode;
+    /** Controls collapsed into the header's overflow (⋯) menu. */
+    menuItems?: KindPanelMenuItem[];
+    /** Full-width line under the header — a rationale, a hint. Never beside the title. */
+    subline?: React.ReactNode;
+    /** Panel body. */
+    children?: React.ReactNode;
+    /** Pinned to the bottom of the panel (an "Add" row, a summary, a copy bar). */
+    footer?: React.ReactNode;
+    /** "card" (default): bordered card. "bare": no border/background — the host IS the chrome. */
+    variant?: "card" | "bare";
+    /** Tighter paddings for dense lists. */
+    dense?: boolean;
+    className?: string;
+    /** className for the body wrapper. */
+    bodyClassName?: string;
+}
+declare function KindPanel({ title, icon, count, badge, streaming, actions, menuItems, subline, children, footer, variant, dense, className, bodyClassName, }: KindPanelProps): React.JSX.Element;
+
+/**
+ * KindHeaderBar — the standard compact header of a kind component:
+ * icon · title (the instance's `title_key` value) · at-a-glance stats · the
+ * copy bar (the host's `CopyButtons` slot: Copy / Copy-for-AI / JSON / Export from builders
+ * the caller supplies). One row that wraps on narrow widths; the copy bar
+ * stays on the right. Contract: `kind-kit/README.md`.
+ */
+
+interface KindHeaderStat {
+    /** Short label, e.g. "keywords". */
+    label: string;
+    /** The number/text, e.g. 42 or "3 buckets". */
+    value: React.ReactNode;
+    /** Lucide component or an already-created icon element. */
+    icon?: KindKitIcon;
+    /** Optional hover text. */
+    title?: string;
+}
+interface KindHeaderBarProps {
+    /** The instance title (usually `data[title_key]`). */
+    title: React.ReactNode;
+    /** Lucide component or an already-created icon element. */
+    icon?: KindKitIcon;
+    /** Small muted line under the title (a primary keyword, a subtitle). */
+    subtitle?: React.ReactNode;
+    /** At-a-glance numbers rendered as compact "value label" stats. */
+    stats?: KindHeaderStat[];
+    /** Shows a spinner + "Streaming" while the instance is still arriving. */
+    streaming?: boolean;
+    /** Word shown beside the spinner. Default "Streaming". */
+    streamingLabel?: string;
+    /**
+     * The copy bar. Pass the builders you have — `human` (text), `agent`
+     * (payload or string), `json` (raw record), `export` (download items) and
+     * the `label` used in toasts. Omit to render no copy bar.
+     */
+    copy?: Omit<KindKitCopyProps, "size" | "className">;
+    /** Extra controls rendered between the stats and the copy bar. */
+    actions?: React.ReactNode;
+    /** "sm" (default) for in-chat blocks; "md" for page-level kind surfaces. */
+    size?: "sm" | "md";
+    className?: string;
+}
+declare function KindHeaderBar({ title, icon, subtitle, stats, streaming, streamingLabel, copy, actions, size, className, }: KindHeaderBarProps): React.JSX.Element;
+
+/**
+ * KindActionButton — the one-click door from a kind component to a host
+ * Action. Wraps the component's `runAction(key, input)` prop (the ONLY
+ * side-effect channel; it never throws, it returns an `{ok}` envelope), with
+ * a busy state, no double fire, an optional inline confirm that states the
+ * consequence, and a one-line inline error (the host already toasts).
+ * Contract: `kind-kit/README.md`.
+ */
+
+type KindActionEnvelope = {
+    ok: true;
+    result?: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+interface KindActionButtonProps {
+    /** The component's `runAction` prop, passed straight through. */
+    runAction: (key: string, input: unknown) => Promise<KindActionEnvelope>;
+    /** Action key, e.g. "run_shortcut". */
+    action: string;
+    /** The action input, or a function that builds it at click time. */
+    input: unknown | (() => unknown);
+    /** Short label. Also the aria-label/tooltip when `compact`. */
+    label: string;
+    /** Lucide component or an already-created icon element. */
+    icon?: KindKitIcon;
+    /** Label while running. Defaults to `label`. */
+    busyLabel?: string;
+    /** One-sentence consequence. When set, the first click asks to confirm. */
+    confirm?: string;
+    onDone?: (result: unknown) => void;
+    onError?: (error: string) => void;
+    variant?: "default" | "primary" | "destructive" | "success" | "outline" | "secondary" | "ghost" | "subtle";
+    /** Icon-only with tooltip + aria-label, for menus and header rows. */
+    compact?: boolean;
+    disabled?: boolean;
+    className?: string;
+}
+declare function KindActionButton({ runAction, action, input, label, icon, busyLabel, confirm, onDone, onError, variant, compact, disabled, className, }: KindActionButtonProps): React.JSX.Element;
+
+/**
+ * StreamingSkeleton + useStreamingValue — the "before data lands" kit.
+ *
+ * A kind component receives partial `data` on every envelope flush while the
+ * agent streams: fields are absent, arrays are short, strings are cut. The
+ * skeleton mimics the layout the real content will have (list / cards /
+ * table / text) for the instant before anything arrives; the helpers make
+ * field reads tolerant so a component never crashes on a half-built
+ * instance and never flickers a value away. Contract:
+ * `kind-kit/README.md`.
+ */
+
+interface StreamingSkeletonProps {
+    /** Layout to mimic. Default "list". */
+    layout?: "list" | "cards" | "table" | "text";
+    /** Rows (list/table/text lines) or cards. Default 3. */
+    rows?: number;
+    /** Columns for "table" / "cards". Default 3 (table) / 2 (cards). */
+    columns?: number;
+    /** Render a title bar line above the body. Default true. */
+    header?: boolean;
+    /** Accessible label. Default "Loading". */
+    label?: string;
+    className?: string;
+}
+declare function StreamingSkeleton({ layout, rows, columns, header, label, className, }: StreamingSkeletonProps): React.JSX.Element;
+/**
+ * Sticky, tolerant read of a value that may be absent mid-stream.
+ *
+ * Returns the latest DEFINED value seen (so a re-parse that momentarily drops
+ * a field does not blank the UI), `fallback` until one arrives, and `arrived`
+ * once any real value has been observed. Implemented with the React
+ * "remember the previous render" pattern (state updated during render), so
+ * pass a FIELD READ (`data?.summary`) — never an expression that builds a
+ * new object/array on every render (`data?.items ?? []`), which would
+ * re-trigger the update each render.
+ */
+declare function useStreamingValue<T>(value: T | null | undefined, fallback: T): {
+    value: T;
+    arrived: boolean;
+};
+/** `value` when it is an array, else `[]` — for `data.items` that is not there yet. */
+declare function streamList<T = unknown>(value: unknown): T[];
+/** `value` when it is a non-empty string, else `fallback` ("" by default). */
+declare function streamText(value: unknown, fallback?: string): string;
+
+/**
+ * KeywordChip + TagList — chips that WRAP, never truncate.
+ *
+ * A keyword / tag / phrase is always shown in full: the chip wraps its text
+ * onto extra lines inside the chip, and the list wraps chips onto extra rows.
+ * Optional select (checkbox-like toggle), remove (X) and inline edit
+ * (pencil → input, Enter commits, Esc cancels). `TagList` adds an inline
+ * "Add" input at the end when `onAdd` is given. Contract:
+ * `kind-kit/README.md`.
+ */
+
+interface KeywordChipProps {
+    /** The phrase. Rendered in full — wraps, never truncates. */
+    label: string;
+    /** Small trailing detail (a count, a volume, a score). */
+    meta?: React.ReactNode;
+    /** Lucide component or an already-created icon element. */
+    icon?: KindKitIcon;
+    /** Selected state; pass `onSelect` to make the chip a toggle. */
+    selected?: boolean;
+    /** Makes the chip a toggle; called with the next selected state. */
+    onSelect?: ((selected: boolean) => void) | undefined;
+    /** Adds an X control. */
+    onRemove?: (() => void) | undefined;
+    /** Enables inline edit (pencil control + double-click); called with the committed text. */
+    onEdit?: ((next: string) => void) | undefined;
+    /** Greys the chip and disables select/remove/edit. */
+    disabled?: boolean | undefined;
+    tone?: "default" | "primary" | "muted" | undefined;
+    size?: "sm" | "md";
+    className?: string;
+}
+declare function KeywordChip({ label, meta, icon, selected, onSelect, onRemove, onEdit, disabled, tone, size, className, }: KeywordChipProps): React.JSX.Element;
+interface TagItem {
+    label: string;
+    /** Stable key; defaults to `label`. */
+    key?: string;
+    meta?: React.ReactNode;
+    disabled?: boolean;
+}
+interface TagListProps {
+    /** Phrases, as strings or `{ label, key?, meta?, disabled? }` objects. */
+    items: readonly (string | TagItem)[];
+    /** Selected keys (label when no key). Pass with `onToggle` for selectable chips. */
+    selected?: readonly string[];
+    /** Makes chips toggles; called with (key, nextSelected). */
+    onToggle?: (key: string, selected: boolean) => void;
+    /** Adds an X on every chip; called with (key, index). */
+    onRemove?: (key: string, index: number) => void;
+    /** Enables inline edit on every chip; called with (key, index, nextLabel). */
+    onEdit?: (key: string, index: number, next: string) => void;
+    /** Renders an inline "Add" input at the end; called with the trimmed text. */
+    onAdd?: (label: string) => void;
+    /** Placeholder of the add input. Default "Add…". */
+    addPlaceholder?: string;
+    /** Shown when `items` is empty (and there is no add input). */
+    emptyState?: React.ReactNode;
+    /**
+     * The outcome of the read behind the rows (RC-B12 r13). `emptyState` shows
+     * only after a read that succeeded; a failed read shows the failure + retry.
+     */
+    read?: ReadOutcome;
+    tone?: KeywordChipProps["tone"];
+    size?: KeywordChipProps["size"];
+    disabled?: boolean;
+    className?: string;
+}
+declare function TagList({ items, selected, onToggle, onRemove, onEdit, onAdd, addPlaceholder, emptyState, read, tone, size, disabled, className, }: TagListProps): React.JSX.Element | null;
+
+export { DefaultCopyButtons, DefaultReadEmpty, DefaultReadStaleNotice, KeywordChip, type KeywordChipProps, KindActionButton, type KindActionButtonProps, type KindActionEnvelope, KindHeaderBar, type KindHeaderBarProps, type KindHeaderStat, type KindKitCopyProps, type KindKitHost, type KindKitIcon, type KindKitReadEmptyProps, type KindKitReadStaleNoticeProps, KindPanel, KindPanelGrid, type KindPanelGridProps, type KindPanelMenuItem, type KindPanelProps, type ReadOutcome, type ReadStatus, SortableList, type SortableListProps, type SortableRenderContext, StreamingSkeleton, type StreamingSkeletonProps, type TagItem, TagList, type TagListProps, getKindKitHost, renderKindKitIcon, resetKindKitHost, setKindKitHost, streamList, streamText, useStreamingValue };