@kitn.ai/ui 0.17.0 → 0.18.1

package/dist/ui/editable-label.d.ts

@@ -0,0 +1,26 @@
+import { JSX } from 'solid-js';
+export interface EditableLabelProps {
+    /** The label text. */
+    value: string;
+    /** Controlled edit state. When it flips true the field opens; double-click and
+     *  the host's `edit()` open it too. */
+    editing?: boolean;
+    /** Placeholder shown while editing (and as muted text when the value is empty). */
+    placeholder?: string;
+    /** Disable entering edit mode. */
+    disabled?: boolean;
+    /** Fires on commit (Enter / blur) with the new value — ONLY when it changed. */
+    onRename?: (value: string) => void;
+    /** Fires on Esc (cancel); the text is restored. */
+    onCancel?: () => void;
+    class?: string;
+}
+/**
+ * `EditableLabel`: inline rename. Shows `value` as text; double-click (or the
+ * `editing` prop, or a host `edit()`) swaps in an autofocused `Input` with the
+ * text pre-selected. Enter or blur commits (fires `onRename` only when the value
+ * changed); Esc cancels (fires `onCancel`, restores the text). Both exit editing.
+ *
+ * Parts: `text` (the read view), `input` (the field while editing).
+ */
+export declare function EditableLabel(props: EditableLabelProps): JSX.Element;

package/dist/ui/hover-card.d.ts

@@ -1,9 +1,21 @@
-import { JSX } from 'solid-js';
+import { JSX, Accessor } from 'solid-js';
 import { Placement } from '@floating-ui/dom';
+/** Imperative open controller, handed to a parent (e.g. the kai-hover-card facade)
+ *  via `controllerRef` so it can drive/observe open state. */
+export interface HoverCardController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
 export interface HoverCardRootProps {
     children: JSX.Element;
     openDelay?: number;
     closeDelay?: number;
+    /** Initial open state (uncontrolled seed). */
+    defaultOpen?: boolean;
+    /** When true, hover/focus never opens the card. */
+    disabled?: boolean;
+    /** Receive the open controller (open accessor + setOpen) once mounted. */
+    controllerRef?: (api: HoverCardController) => void;
 }
 export declare function HoverCardRoot(props: HoverCardRootProps): JSX.Element;
 export interface HoverCardTriggerProps {

package/dist/ui/icon.d.ts

@@ -0,0 +1,18 @@
+import { JSX } from 'solid-js';
+/** Render an item icon.
+ *
+ *  Resolution order:
+ *  1. Known icon name (e.g. `"paperclip"`) → lucide-solid component.
+ *  2. URL / absolute path / data-URI → `<img>`.
+ *  3. Anything else → `<span>` text fallback.
+ *  Returns `null` when `icon` is undefined/empty.
+ *
+ *  The img and span branches render different markup, so they accept different
+ *  class options: `imgClass` for the `<img>`, `spanClass` for the `<span>`.
+ *  `class` is a shared fallback. Pass `ariaHidden` to mark the span decorative. */
+export declare function renderIcon(icon: string | undefined, opts?: {
+    class?: string;
+    imgClass?: string;
+    spanClass?: string;
+    ariaHidden?: boolean;
+}): JSX.Element;

package/dist/ui/input.d.ts

@@ -0,0 +1,33 @@
+import { JSX } from 'solid-js';
+export interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'onInput' | 'onChange' | 'size'> {
+    /** Field label rendered above the control and linked via `for`/`id`. */
+    label?: string;
+    /** Helper text rendered below the control. */
+    hint?: string;
+    /** Error text; rendered below the control and flips the field invalid. */
+    error?: string;
+    /** Control density. Defaults to `md`. */
+    size?: 'sm' | 'md';
+    /** Force the invalid (destructive-border) state without an `error` string. */
+    invalid?: boolean;
+    /** Leading affix (icon, unit). Rendered inside the field row, before the input. */
+    leading?: JSX.Element;
+    /** Trailing affix (icon, inline button). Rendered inside the field row, after the input. */
+    trailing?: JSX.Element;
+    /** Fires per keystroke with the current value. */
+    onValueInput?: (value: string) => void;
+    /** Fires on commit (blur) with the current value. */
+    onValueChange?: (value: string) => void;
+}
+export declare const FIELD_BASE = "w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 disabled:pointer-events-none";
+/**
+ * `Input`: the token-themed single-line text field shell. A label/hint/error
+ * stack around a field row that holds an optional `leading` affix, the
+ * `<input>`, and an optional `trailing` affix. The shared border/background/ring
+ * styling lives here (the single field source the form widgets build on).
+ *
+ * Parts: `field` (the bordered control), `input`, `label`, `hint`.
+ * a11y: a generated id links `<label for>`; `invalid`/`error` set `aria-invalid`;
+ * the hint/error text is linked via `aria-describedby`.
+ */
+export declare function Input(props: InputProps): JSX.Element;

package/dist/ui/kbd.d.ts

@@ -0,0 +1,21 @@
+import { JSX } from 'solid-js';
+export type KbdPlatform = 'auto' | 'mac' | 'other';
+export interface KbdProps extends JSX.HTMLAttributes<HTMLElement> {
+    /** Shortcut spec — tokens joined by `+` (e.g. `Mod+Shift+K`). When omitted,
+     *  children render verbatim. Display only; `kai-kbd` does not bind keys. */
+    keys?: string;
+    /** Glyph platform. `mac` uses ⌘/⌥; `other` uses Ctrl. `auto` (default for the
+     *  facade) sniffs the OS, SSR-safe (falls back to `other` on the server). */
+    platform?: KbdPlatform;
+    /** Cap size. Defaults to `md`. */
+    size?: 'sm' | 'md';
+}
+/**
+ * `Kbd`: a keyboard-shortcut display. Splits `keys` on `+`, maps each token to a
+ * platform glyph (`Mod` → ⌘ on mac else Ctrl, `Shift` → ⇧, `ArrowUp` → ↑, …) and
+ * renders each as an inset `part="key"` cap, with an empty `part="separator"` hook
+ * between caps. Token-driven, light + dark. Display only — it does not bind keys.
+ *
+ * When `keys` is omitted, the children render verbatim (use any custom content).
+ */
+export declare function Kbd(props: KbdProps): JSX.Element;

package/dist/ui/nav.d.ts

@@ -0,0 +1,62 @@
+import { JSX } from 'solid-js';
+/** Status tone for a nav item's dot. `primary` is the theme accent; the rest use
+ *  the kit's tool hues (the same colors as kai-status / kai-progress-bar). Generic
+ *  enough for thread/onboarding states (success = "Completed", info = "Working")
+ *  and task-run states (neutral = queued, info = running, success = done,
+ *  error = failed). */
+export type NavStatusTone = 'primary' | 'info' | 'success' | 'warning' | 'error' | 'neutral';
+/** A small colored status indicator on a nav row. The `label` (when set) is folded
+ *  into the row's accessible name; `pulse` adds an animated ping ring. */
+export interface NavItemStatus {
+    tone: NavStatusTone;
+    /** Short status word ("Working", "Failed"). Shown as muted text and announced. */
+    label?: string;
+    /** Animated ping ring (disabled under prefers-reduced-motion). */
+    pulse?: boolean;
+}
+export interface KaiNavItem {
+    id: string;
+    label?: string;
+    /** Leading icon: a named icon, an image URL / data-URI, or plain text. */
+    icon?: string;
+    /** Trailing text pill (e.g. "Beta"). */
+    badge?: string;
+    /** Trailing icon (a named icon), e.g. an edit/compose affordance. */
+    trailing?: string;
+    disabled?: boolean;
+    /** Nested items. When present, the row becomes a collapsible group: a parent
+     *  row with a disclosure chevron over an indented child list. Recurses for
+     *  arbitrary depth (primarily 2 levels, e.g. project -> threads). */
+    children?: KaiNavItem[];
+    /** A small colored status dot (+ optional label) on the row. */
+    status?: NavItemStatus;
+    /** Right-aligned muted trailing text (e.g. a relative time, "24d ago").
+     *  Distinct from `trailing` (a hover icon). */
+    meta?: string;
+    /** An interactive trailing action button (`icon` is a named icon; `label` is
+     *  its accessible name). Activating it fires `onItemAction` and does NOT select
+     *  the row. Distinct from `trailing` (a decorative hover icon, not a button). */
+    action?: {
+        icon: string;
+        label: string;
+    };
+    /** Render an interactive trailing close (×) button. Activating it fires
+     *  `onItemClose` and does NOT select the row. */
+    closable?: boolean;
+}
+export interface NavProps extends JSX.HTMLAttributes<HTMLElement> {
+    items?: KaiNavItem[];
+    /** Active item id (drives aria-current + the selected look). */
+    value?: string;
+    onItemSelect?: (id: string) => void;
+    /** A row's trailing `action` button was activated (not a select). */
+    onItemAction?: (id: string, action?: {
+        icon: string;
+        label: string;
+    }) => void;
+    /** A `closable` row's trailing close button was activated (not a select). */
+    onItemClose?: (id: string) => void;
+    /** Ids of group items collapsed on first render. Groups default to expanded. */
+    defaultCollapsed?: string[];
+}
+export declare function Nav(props: NavProps): JSX.Element;

package/dist/ui/notice.d.ts

@@ -0,0 +1,31 @@
+import { JSX } from 'solid-js';
+export type NoticeSeverity = 'neutral' | 'info' | 'warning' | 'error' | 'success';
+/** The default leading icon for a notice: `null` when `icon="none"`, the named
+ *  icon when one is given, else the severity glyph. Exported so the `kai-notice`
+ *  facade can use it as the fallback inside a `slot="icon"` escape hatch. */
+export declare function noticeIconNode(severity: NoticeSeverity, icon?: string): JSX.Element;
+export interface NoticeProps {
+    severity?: NoticeSeverity;
+    /** Leading icon: omit for the severity default, `"none"` to hide it, or a named
+     *  icon to override. */
+    icon?: string;
+    /** A custom icon node that replaces the icon region entirely (the `kai-notice`
+     *  facade passes a `slot="icon"` here, with the default icon as its fallback). */
+    iconSlot?: JSX.Element;
+    /** Render a dismiss (×) button that hides the notice and calls `onDismiss`. */
+    dismissible?: boolean;
+    /** Called after the notice is dismissed. */
+    onDismiss?: () => void;
+    /** The message. */
+    children: JSX.Element;
+    /** Optional trailing action (e.g. a link). */
+    action?: JSX.Element;
+    class?: string;
+}
+/**
+ * A self-contained inline notice / alert: a leading severity icon, a message, an
+ * optional trailing action, and an optional dismiss. Carries the right a11y role
+ * (`alert` for errors, `status` otherwise). Placement is the consumer's — this is
+ * just the notice box.
+ */
+export declare function Notice(props: NoticeProps): JSX.Element;

package/dist/ui/overlay.d.ts

@@ -29,6 +29,18 @@ export interface UsePositionOptions {
     placement?: Placement;
     gutter?: number;
     arrowEl?: Accessor<HTMLElement | undefined>;
+    /**
+     * Fired ONCE when the reference (anchor) "goes away" — either removed from the
+     * document OR hidden behind an `inert` ancestor (e.g. a modal/takeover that
+     * inert-s the background while open). In both cases the anchor is no longer a
+     * valid, interactive target, so the caller should close the overlay and unmount
+     * its portal instead of leaving it orphaned (floating over an inert background or
+     * anchored to a node that no longer exists). Anchored overlays portal OUT of the
+     * trigger's subtree, so Solid's onCleanup does not catch an anchor that is
+     * removed/inerted independently of the overlay component. Wire this to set the
+     * overlay's open state to false.
+     */
+    onDisconnect?: () => void;
 }
 /**
  * Position `floating` relative to `reference` using fixed strategy + autoUpdate,

package/dist/ui/pane-grid.d.ts

@@ -0,0 +1,58 @@
+import { JSX } from 'solid-js';
+export interface PaneGridProps {
+    /** The panes - arbitrary N. Each top-level child is one tile in the grid. */
+    children: JSX.Element;
+    /** Minimum width of every pane, in px, before columns drop / the grid scrolls.
+     *  Defaults to `280`. */
+    minPaneWidth?: number;
+    /** Minimum height of every pane, in px, before the grid scrolls vertically.
+     *  Defaults to `200`. */
+    minPaneHeight?: number;
+    /** Column cap when the container is wide. Columns fill up to this many, then drop
+     *  to fewer as the container narrows. Defaults to `3`. */
+    maxColumns?: number;
+    /** Gap between panes - any CSS length. Defaults to the kit gap
+     *  (`var(--kai-pane-grid-gap, 0.5rem)`). */
+    gap?: string;
+    /** When set to a valid child index, render ONLY that pane full-bleed (a single
+     *  filling cell) - a simple maximize hook the consumer drives. `null`/`undefined`
+     *  (or an out-of-range index) shows the full tiled grid. */
+    maximizedIndex?: number | null;
+    /** Extra classes for the grid container. */
+    class?: string;
+}
+/**
+ * PaneGrid - an N-pane responsive tiling grid with a min-size + scroll floor.
+ *
+ * Lays an arbitrary number of panes out in a CSS grid that fills up to
+ * `maxColumns` columns when wide, then DROPS columns (maxColumns -> ... -> 1) as
+ * the container narrows - so panes never squish below their minimums. Once even one
+ * column can't hold a pane at `minPaneWidth`, the grid SCROLLS instead of shrinking
+ * the panes; rows are kept at least `minPaneHeight` tall the same way. Because new
+ * rows stack downward, the overflow is preferentially VERTICAL - horizontal scroll
+ * only appears when the container is narrower than a single pane's minimum.
+ *
+ * This generalizes the hand-rolled center grid from the Split Workspace demo, where
+ * `kai-resizable` (capped at 3 panes) couldn't express an arbitrary-N tiled grid.
+ *
+ * Column track (computed from the props):
+ *
+ *   repeat(auto-fit, minmax(max(<minPaneWidth>px, (100% - <gaps>) / <maxColumns>), 1fr))
+ *
+ * where `<gaps>` is the total inter-column gap at the cap, `(maxColumns - 1) * gap`.
+ * The inner `max()` is the floor: each track is at least `minPaneWidth`, and at most
+ * `1fr`; the `(100% - gaps) / maxColumns` term is the per-column width WHEN the cap is
+ * filled, so `auto-fit` never packs in more than `maxColumns` columns. As the
+ * container shrinks past the point where a column can be `minPaneWidth` wide, a column
+ * drops; below one pane's minimum, the `overflow:auto` + `min-w-0`/`min-h-0` container
+ * scrolls.
+ *
+ * Maximize: when `maximizedIndex` points at a child, only that pane renders, in a
+ * single `1fr` x `1fr` cell that fills the grid. Restore by clearing the prop.
+ *
+ * The gap default reads `--kai-pane-grid-gap` (fallback `0.5rem`), so a consumer can
+ * retune spacing from outside without passing the prop. Everything is tokenized
+ * (surface/border come from whatever the panes use) - no hardcoded colors, so it
+ * reads correctly in light and dark.
+ */
+export declare function PaneGrid(props: PaneGridProps): JSX.Element;

package/dist/ui/pane-group.d.ts

@@ -0,0 +1,77 @@
+import { JSX } from 'solid-js';
+import { PaneStatusTone } from './pane';
+/** The work state of a tab's agent/process, mapped to the kit's tool / status
+ *  hues — the SAME vocabulary as {@link './pane'.PaneStatus} and the AgentCard:
+ *  working = blue, idle = muted, done = green, error = red, blocked = amber. */
+export interface PaneTabStatus {
+    /** Which hue the numbered badge takes. */
+    tone: PaneStatusTone;
+    /** Optional status word shown on the active tab, on hover, and always for a
+     *  needs-attention / error tab. Without it only the badge color carries state. */
+    label?: string;
+    /** Animate a ping ring around the badge — for the live `working` state.
+     *  Respects prefers-reduced-motion. */
+    pulse?: boolean;
+}
+/** One tab in a {@link PaneGroup}: an agent/window shown in the strip. */
+export interface PaneTab {
+    /** Stable id, emitted as the selected value throughout. */
+    id: string;
+    /** The tab name (the agent / window title). */
+    name: string;
+    /** Run status — drives the numbered badge color + the status word. Defaults to
+     *  an `idle` (muted) badge with no word. */
+    status?: PaneTabStatus;
+    /** Raise the attention treatment: an amber ring + the status word always shown.
+     *  The "this one wants you" signal. */
+    needsAttention?: boolean;
+    /** The keyboard NUMBER shown inside the badge (the ⌥-jump hint). Defaults to the
+     *  tab's 1-based position in the strip. */
+    number?: number;
+}
+export interface PaneGroupProps {
+    /** The tabs, left → right. Each is one agent/window in the group. */
+    tabs: PaneTab[];
+    /** The active tab id. Defaults to the first tab. Drive it from `onTabChange`. */
+    active?: string;
+    /** A tab was selected (click, Enter/Space, or arrow-key move). */
+    onTabChange?: (id: string) => void;
+    /** A tab's close (×) was clicked. The consumer drops the tab from `tabs`. */
+    onTabClose?: (id: string) => void;
+    /** A tab's "…" overflow was clicked. The consumer wires the actual menu; the
+     *  group only surfaces the affordance. Omit to hide the "…" button. */
+    onTabMenu?: (id: string) => void;
+    /** Highlight the frame with a ring/border to mark this as the ACTIVE group in a
+     *  multi-group layout. */
+    focused?: boolean;
+    /** The active pane's body — the consumer owns it and swaps it on `onTabChange`. */
+    children?: JSX.Element;
+    /** Extra classes for the outer frame. */
+    class?: string;
+}
+/**
+ * PaneGroup — an editor group: a TAB STRIP (numbered-status-badge tabs) over a
+ * single CONTENT area showing the active tab's pane body. The reusable "one column
+ * = a group of agents shown as tabs" primitive from the Multi-Agent Workspace,
+ * extracted from the hand-rolled group in the Split Workspace demo.
+ *
+ * Each tab leads with a small TONE-COLORED NUMBERED BADGE — the color encodes the
+ * agent's run status, the digit is its keyboard (⌥-jump) number, unifying status +
+ * hint into one element — then the name, then the status WORD (shown on the active
+ * tab, on hover, and always for a needs-attention / error tab), an optional "…"
+ * overflow, and a close "×". The active tab is highlighted; a needs-attention tab
+ * carries an amber ring even when inactive.
+ *
+ * Composition: the group owns the tab UX; the CONSUMER owns the pane content. It
+ * renders `children` as the active pane's body and swaps it in response to
+ * `onTabChange`. Selection-only — it never routes content itself.
+ *
+ * Accessibility: a `role="group"` ("Open panes") strip of real `<button>` tab
+ * activators (NOT `role="tab"`, so the strip can legally own the per-tab menu/close
+ * buttons) with roving tabindex + Arrow/Home/End navigation; the active activator is
+ * marked `aria-current="true"`, and the body is the `role="tabpanel"`. Colors are all
+ * token-backed (surface / border / ring / tool-*), so it reads in light and dark.
+ * The strip, each tab, and the body are exposed via `::part(tabs|tab|body)` for
+ * the `kai-pane-group` facade. Give the group a bounded height for the body scroll.
+ */
+export declare function PaneGroup(props: PaneGroupProps): JSX.Element;

package/dist/ui/pane.d.ts

@@ -0,0 +1,78 @@
+import { JSX } from 'solid-js';
+/** The work state of the pane's agent/process. Drives a tone-colored status dot
+ *  (and optional label) in the header. */
+export type PaneStatusTone = 'working' | 'idle' | 'done' | 'error' | 'blocked';
+export interface PaneStatus {
+    /** The tone — maps to a semantic status hue (see {@link PANE_STATUS_BG}). */
+    tone: PaneStatusTone;
+    /** Optional text beside the dot (e.g. "Running tests…"). Without it the dot is
+     *  decorative and only the color carries meaning. */
+    label?: string;
+    /** Animate a ping ring on the dot — for the live `working` state. Respects
+     *  prefers-reduced-motion. */
+    pulse?: boolean;
+}
+/** tone → status-dot color utility, backed by the kit's tool-* / muted tokens so
+ *  it reads correctly in BOTH light and dark without hardcoded colors.
+ *  - `working` → blue (in-flight)
+ *  - `idle`    → neutral muted (waiting)
+ *  - `done`    → green (complete)
+ *  - `error`   → red (failed)
+ *  - `blocked` → amber (needs input / stalled) */
+export declare const PANE_STATUS_BG: Record<PaneStatusTone, string>;
+export interface PaneProps {
+    /** A glyph/avatar shown before the title (an agent icon, a model avatar). */
+    leading?: JSX.Element;
+    /** The pane title — the agent / window name. */
+    title: string;
+    /** A role / label shown under the title (e.g. "Reviewer", "claude-sonnet"). */
+    subtitle?: string;
+    /** A tone-colored status dot (+ optional label) in the header. */
+    status?: PaneStatus;
+    /** Extra header controls, placed BEFORE the built-in window controls. */
+    actions?: JSX.Element;
+    /** The pane body — scrolls inside a `min-h-0 flex-1 overflow-y-auto` region. */
+    children?: JSX.Element;
+    /** A pinned row below the body (e.g. a composer). Stays put while the body scrolls. */
+    footer?: JSX.Element;
+    /** Highlight the frame with a ring/border to signal the ACTIVE pane. */
+    focused?: boolean;
+    /** Show the restore glyph (Minimize2) instead of maximize (Maximize2). */
+    maximized?: boolean;
+    /** Maximize/restore window control. */
+    onMaximize?: () => void;
+    /** Close window control. */
+    onClose?: () => void;
+    /** Optional split control — the button only renders when this is provided. */
+    onSplit?: () => void;
+    /** Optional dock-to-side control — the button only renders when this is provided. */
+    onDock?: () => void;
+    /** Extra classes for the outer frame. */
+    class?: string;
+}
+/**
+ * Pane — a reusable framed panel for a multi-agent workspace: a header (leading
+ * glyph + title/subtitle + status dot + actions + window controls), a scrolling
+ * body, and an optional pinned footer (e.g. a composer). It is the "pane frame"
+ * every agent tile otherwise re-hand-rolls.
+ *
+ * Layout: the outer frame is a column flexbox; the header and footer hold their
+ * height (`shrink-0`) while the body takes the rest (`min-h-0 flex-1
+ * overflow-y-auto`) so content scrolls INSIDE the pane. Give the pane a bounded
+ * height (a fixed parent, or `h-full` inside a grid/flex track) for the scroll to
+ * engage; the body imposes no padding so content controls its own.
+ *
+ * Window controls (right side of the header): maximize/restore (Maximize2 ↔
+ * Minimize2, toggled by `maximized`) and close (X) are always present; split
+ * (Columns2) and dock (PanelRight) only render when `onSplit` / `onDock` are
+ * passed. Each fires its callback prop.
+ *
+ * States: `focused` paints a ring + accent border to mark the active pane;
+ * `maximized` swaps the maximize glyph for restore.
+ *
+ * Colors come entirely from design tokens (surface / border / ring / tool-*),
+ * so it reads correctly in light and dark with no hardcoded values. The header,
+ * body, footer, and window-control cluster are exposed via
+ * `::part(header|body|footer|controls)` for the `kai-pane` facade.
+ */
+export declare function Pane(props: PaneProps): JSX.Element;

package/dist/ui/popover.d.ts

@@ -1,5 +1,11 @@
-import { JSX } from 'solid-js';
+import { JSX, Accessor } from 'solid-js';
 import { Placement } from '@floating-ui/dom';
+/** Imperative open controller, handed to a parent (e.g. the kai-popover facade)
+ *  via `controllerRef` so it can drive/observe open state. */
+export interface PopoverController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
 export interface PopoverProps {
     /** The trigger content (e.g. a button). Clicking it toggles the popover. */
     trigger: JSX.Element;
@@ -14,8 +20,12 @@ export interface PopoverProps {
     open?: boolean;
     /** Initial open state when uncontrolled. */
     defaultOpen?: boolean;
+    /** When true, clicking the trigger never opens the popover. */
+    disabled?: boolean;
     /** Fires whenever the popover wants to open or close. */
     onOpenChange?: (open: boolean) => void;
+    /** Receive the open controller (open accessor + setOpen) once mounted. */
+    controllerRef?: (api: PopoverController) => void;
     /** Extra elements counted as "inside" for outside-click dismissal — e.g. the
      *  custom-element host, so clicks on slotted panel content don't dismiss. */
     boundary?: () => HTMLElement | undefined;

package/dist/ui/progress-bar.d.ts

@@ -0,0 +1,23 @@
+import { JSX } from 'solid-js';
+export type ProgressTone = 'primary' | 'success' | 'warning' | 'error' | 'info';
+/** Fill hue per `tone`. `primary` is the theme accent; the rest use the kit's
+ *  tool hues (the same colors as kai-status / kai-notice). */
+export declare const TONE_FILL: Record<ProgressTone, string>;
+export interface ProgressBarProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    /** Current progress value (0..max). */
+    value: number;
+    /** The value `value` runs to. Defaults to 100. */
+    max?: number;
+    /** Optional caption above the track. */
+    label?: string;
+    /** Fill color. Defaults to `primary`. Override via `::part(fill)` for custom hues. */
+    tone?: ProgressTone;
+}
+/**
+ * A thin determinate progress bar: a rounded track with a `bg-primary` fill whose
+ * width is `value / max`, clamped to 0..100%. Theme-aware (track = `bg-surface-strong`,
+ * fill = `bg-primary`). Set `tone` for a semantic fill hue. Restyle via
+ * `::part(track)` / `::part(fill)`. The fill width transitions smoothly under
+ * `prefers-reduced-motion: no-preference`.
+ */
+export declare function ProgressBar(props: ProgressBarProps): JSX.Element;

package/dist/ui/prompt-dock.d.ts

@@ -0,0 +1,96 @@
+import { JSX } from 'solid-js';
+/** How the tray frames the input — the SPATIAL axis (padding/inset only).
+ *  Orthogonal to {@link PromptDockAppearance}, which controls the surface.
+ *  - `inset` (default) — uniform inset frames the input on ALL edges (the classic look).
+ *  - `edge` — top/bottom inset only; the input sits FLUSH left/right so the lips span
+ *    the full width.
+ *  - `none` — no inset at all; the lips attach directly to the input as a plain stack. */
+export type PromptDockFrame = 'inset' | 'edge' | 'none';
+/** How the tray surface looks — the VISUAL axis (background / border / radius only).
+ *  Orthogonal to {@link PromptDockFrame}, which controls the spatial inset. Works like
+ *  a button variant.
+ *  - `soft` (default) — sunken surface + border + radius (the classic look).
+ *  - `outlined` — transparent surface + border + radius.
+ *  - `filled` — sunken surface, no border, + radius.
+ *  - `plain` — transparent surface, no border, no radius (truly bare). */
+export type PromptDockAppearance = 'soft' | 'outlined' | 'filled' | 'plain';
+export interface PromptDockProps {
+    /** Optional content for the recessed band ABOVE the input (a notice, a hint).
+     *  When omitted, no top lip renders and only the input shows. */
+    top?: JSX.Element;
+    /** Optional content for the recessed band BELOW the input (a mode / control row).
+     *  When omitted, no bottom lip renders. */
+    bottom?: JSX.Element;
+    /** Extra classes for the TOP lip wrapper, merged over the default band styling.
+     *  Use this to give the top region its own surface (e.g. a tinted notice) without
+     *  affecting the bottom. The eventual `kai-prompt-dock` element will expose the
+     *  same region via `::part(top)`. */
+    topClass?: string;
+    /** Extra classes for the BOTTOM lip wrapper, merged over the default band styling.
+     *  The eventual `kai-prompt-dock` element will expose this region via
+     *  `::part(bottom)`. */
+    bottomClass?: string;
+    /** How the tray frames the input — the SPATIAL inset only. Defaults to `'inset'`
+     *  (the classic recessed look), so existing consumers are unaffected.
+     *  See {@link PromptDockFrame}. */
+    frame?: PromptDockFrame;
+    /** How the tray surface looks — the VISUAL axis (background / border / radius),
+     *  orthogonal to `frame`. Defaults to `'soft'` (the classic look), so existing
+     *  consumers are unaffected. See {@link PromptDockAppearance}. */
+    appearance?: PromptDockAppearance;
+    /** The prompt input - the raised card that floats on the tray. */
+    children: JSX.Element;
+    /** Extra classes for the outer tray. */
+    class?: string;
+}
+/**
+ * PromptDock - a recessed tray that frames a prompt input and can extend with
+ * optional "lip" regions above and/or below it.
+ *
+ * The model: the input stays the prominent, fully-rounded RAISED card; the lips
+ * sit in a slightly darker, RECESSED band tucked above and/or below it, sharing
+ * the tray's outer rounding so the whole thing reads as one cohesive control.
+ * When nothing is slotted top or bottom, only the input shows: no visible lip.
+ *
+ * Styling splits into two ORTHOGONAL axes so the spatial framing and the surface
+ * can be set independently (like a button's size vs. its variant):
+ *
+ * `frame` - the SPATIAL inset (padding only):
+ *   - `inset` (default) - a small, uniform inset frames the input on EVERY side
+ *     (the tray padding plus the flex gap give a ~6px frame). The classic look.
+ *   - `edge` - top/bottom inset only; the input is FLUSH on the left / right so the
+ *     lips span the full width. Matches the Claude Code / Codex references, where the
+ *     lip is a top/bottom phenomenon.
+ *   - `none` - no inset at all; the lips attach directly to the input as a plain
+ *     vertical stack. The lips keep their own internal padding so content still has
+ *     breathing room.
+ *
+ * `appearance` - the SURFACE (background / border / radius):
+ *   - `soft` (default) - sunken surface + border + radius (the classic look).
+ *   - `outlined` - transparent surface + border + radius.
+ *   - `filled` - sunken surface, no border, + radius.
+ *   - `plain` - transparent surface, no border, no radius (truly bare).
+ *
+ * The two are independent: e.g. `frame="none" appearance="plain"` is a bare stack,
+ * while `frame="inset" appearance="outlined"` keeps the inset but drops the fill.
+ *
+ * Surface, border, radius and inset come from four CSS custom-property TOKENS, so
+ * a consumer can fine-tune the chrome without touching internals (override the var
+ * from outside; the variant chooses the structure). Each is referenced with a
+ * fallback so it resolves stand-alone:
+ *   - `--kai-prompt-dock-surface` - tray background (default `var(--color-surface-sunken)`)
+ *   - `--kai-prompt-dock-border`  - tray border color (default `var(--color-border)`)
+ *   - `--kai-prompt-dock-radius`  - outer radius (default `1.25rem`)
+ *   - `--kai-prompt-dock-inset`   - frame thickness around the input (default `0.375rem`)
+ *
+ * Colors default to the surface tokens (surface-sunken for the tray and lips; the
+ * input brings its own raised bg-surface), so it reads correctly in both light and
+ * dark themes without hardcoded colors. The top and bottom lips are independently
+ * styleable via `topClass` / `bottomClass` (e.g. a tinted notice up top over a
+ * neutral control row below).
+ *
+ * The eventual `kai-prompt-dock` element will expose the same three regions via
+ * `::part(tray)` / `::part(top)` / `::part(bottom)`; the primitive's equivalent
+ * hooks are the `class` / `topClass` / `bottomClass` props.
+ */
+export declare function PromptDock(props: PromptDockProps): JSX.Element;

package/dist/ui/resizable.d.ts

@@ -20,6 +20,18 @@ export declare function normalizeSize(value: SizeValue | undefined): string | un
  * Returns `undefined` when the value is unset.
  */
 export declare function resolveToPx(value: SizeValue | undefined, containerPx: number): number | undefined;
+/**
+ * Build a panel's INITIAL `flex-basis`, clamped into its `[min, max]` bounds so
+ * it never PAINTS past its max (or below its min). The drag handler already
+ * clamps, but only once a drag begins — without this, a percentage default on a
+ * wide container (e.g. `40%` against a `480px` max) renders wider than max and
+ * then SNAPS to max on the first resize. Uses CSS `clamp()`/`min()`/`max()` so
+ * the bound is enforced at layout time against the live container size, with
+ * MIXED units (a `%` default vs a `px` max) resolving correctly — no JS measure.
+ * `basis`/`min`/`max` are already-normalized CSS lengths (see `normalizeSize`);
+ * an undefined `basis` stays undefined → the caller falls back to flexible.
+ */
+export declare function clampBasis(basis: string | undefined, min: string | undefined, max: string | undefined): string | undefined;
 export interface ResizablePanelGroupProps extends JSX.HTMLAttributes<HTMLDivElement> {
     orientation?: Orientation;
     children: JSX.Element;

package/dist/ui/scroll-area.d.ts

@@ -1,5 +1,9 @@
 import { JSX } from 'solid-js';
+export type ScrollOrientation = 'vertical' | 'horizontal' | 'both';
 export interface ScrollAreaProps extends JSX.HTMLAttributes<HTMLDivElement> {
     children: JSX.Element;
+    /** Which axis scrolls. `vertical` (default) · `horizontal` · `both`. The cross
+     *  axis is clamped to `hidden` so content can't overflow it. */
+    orientation?: ScrollOrientation;
 }
 export declare function ScrollArea(props: ScrollAreaProps): JSX.Element;