@kitn.ai/ui 0.16.0 → 0.18.0

package/src/ui/pane.tsx

@@ -0,0 +1,193 @@
+import { type JSX, Show } from 'solid-js';
+import { Maximize2, Minimize2, X, Columns2, PanelRight } from 'lucide-solid';
+import { cn } from '../utils/cn';
+
+/** 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 const PANE_STATUS_BG: Record<PaneStatusTone, string> = {
+  working: 'bg-tool-blue',
+  idle: 'bg-muted-foreground',
+  done: 'bg-tool-green',
+  error: 'bg-tool-red',
+  blocked: 'bg-tool-amber',
+};
+
+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;
+}
+
+/** A header window-control: a square, muted icon button. */
+function ControlButton(props: { label: string; onClick?: () => void; children: JSX.Element }) {
+  return (
+    <button
+      type="button"
+      aria-label={props.label}
+      onClick={() => props.onClick?.()}
+      class="flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground opacity-80 transition-colors hover:bg-hover hover:text-foreground hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      {props.children}
+    </button>
+  );
+}
+
+/**
+ * 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 function Pane(props: PaneProps) {
+  return (
+    <div
+      data-pane
+      class={cn(
+        'flex h-full min-h-0 flex-col overflow-hidden rounded-xl border bg-surface',
+        props.focused ? 'border-ring ring-2 ring-inset ring-ring/35' : 'border-border',
+        props.class,
+      )}
+    >
+      <div
+        part="header"
+        class="flex shrink-0 items-center gap-2.5 border-b border-border px-3 py-2"
+      >
+        <Show when={props.leading}>
+          <span class="flex shrink-0 items-center text-muted-foreground">{props.leading}</span>
+        </Show>
+        <div class="flex min-w-0 flex-col">
+          <span class="truncate text-sm font-medium leading-tight text-foreground">{props.title}</span>
+          <Show when={props.subtitle}>
+            <span class="truncate text-xs leading-tight text-muted-foreground">{props.subtitle}</span>
+          </Show>
+        </div>
+        <Show when={props.status}>
+          {(status) => (
+            <span
+              class="flex shrink-0 items-center gap-1.5 text-xs text-muted-foreground"
+              role={status().label ? 'status' : undefined}
+              aria-label={status().label}
+            >
+              <span class="relative flex size-2">
+                <Show when={status().pulse}>
+                  <span
+                    aria-hidden="true"
+                    class={cn(
+                      'absolute inline-flex h-full w-full animate-ping rounded-full opacity-75 motion-reduce:hidden',
+                      PANE_STATUS_BG[status().tone],
+                    )}
+                  />
+                </Show>
+                <span
+                  aria-hidden="true"
+                  class={cn('relative inline-flex size-2 rounded-full', PANE_STATUS_BG[status().tone])}
+                />
+              </span>
+              <Show when={status().label}>
+                <span class="truncate">{status().label}</span>
+              </Show>
+            </span>
+          )}
+        </Show>
+        <div part="controls" class="ml-auto flex shrink-0 items-center gap-0.5">
+          {props.actions}
+          <Show when={props.onSplit}>
+            <ControlButton label="Split pane" onClick={props.onSplit}>
+              <Columns2 class="size-4" aria-hidden="true" />
+            </ControlButton>
+          </Show>
+          <Show when={props.onDock}>
+            <ControlButton label="Dock pane" onClick={props.onDock}>
+              <PanelRight class="size-4" aria-hidden="true" />
+            </ControlButton>
+          </Show>
+          <ControlButton
+            label={props.maximized ? 'Restore pane' : 'Maximize pane'}
+            onClick={props.onMaximize}
+          >
+            <Show when={props.maximized} fallback={<Maximize2 class="size-4" aria-hidden="true" />}>
+              <Minimize2 class="size-4" aria-hidden="true" />
+            </Show>
+          </ControlButton>
+          <ControlButton label="Close pane" onClick={props.onClose}>
+            <X class="size-4" aria-hidden="true" />
+          </ControlButton>
+        </div>
+      </div>
+
+      <div part="body" class="min-h-0 flex-1 overflow-y-auto">
+        {props.children}
+      </div>
+
+      <Show when={props.footer}>
+        <div part="footer" class="shrink-0 border-t border-border">
+          {props.footer}
+        </div>
+      </Show>
+    </div>
+  );
+}

package/src/ui/popover.tsx

@@ -1,8 +1,12 @@
-import { createSignal, Show, type JSX } from 'solid-js';
+import { createSignal, Show, type JSX, type Accessor } from 'solid-js';
 import type { Placement } from '@floating-ui/dom';
 import { cn } from '../utils/cn';
 import { createPresence, usePosition, useDismiss } from './overlay';
 
+/** 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;
@@ -17,8 +21,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;
@@ -45,10 +53,16 @@ export function Popover(props: PopoverProps) {
     props.onOpenChange?.(v);
   };
 
+  // Hand the open controller up to a parent (e.g. the kai-popover facade) so it
+  // can drive/observe open state via wireDisclosure.
+  props.controllerRef?.({ open: isOpen, setOpen });
+
   const presence = createPresence(isOpen);
   const position = usePosition(trigger, panel, {
     placement: props.placement ?? 'bottom-start',
     gutter: props.gutter ?? 6,
+    // Trigger removed from the DOM -> close so the panel portal doesn't orphan.
+    onDisconnect: () => setOpen(false),
   });
   useDismiss({
     enabled: isOpen,
@@ -61,7 +75,7 @@ export function Popover(props: PopoverProps) {
       <span
         ref={setTrigger}
         style={{ display: 'inline-flex' }}
-        onClick={() => setOpen(!isOpen())}
+        onClick={() => { if (!props.disabled) setOpen(!isOpen()); }}
       >
         {props.trigger}
       </span>

package/src/ui/progress-bar.tsx

@@ -0,0 +1,83 @@
+import { type JSX, Show, splitProps, createUniqueId } from 'solid-js';
+import { cn } from '../utils/cn';
+
+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 const TONE_FILL: Record<ProgressTone, string> = {
+  primary: 'bg-primary',
+  success: 'bg-tool-green',
+  warning: 'bg-tool-amber',
+  error: 'bg-tool-red',
+  info: 'bg-tool-blue',
+};
+
+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 function ProgressBar(props: ProgressBarProps) {
+  const [local, rest] = splitProps(props, [
+    'value', 'max', 'label', 'tone', 'class', 'aria-label', 'aria-labelledby',
+  ]);
+  const labelId = createUniqueId();
+  const max = () => local.max ?? 100;
+  // Clamp value into [0, max]; drive both the fill width and aria-valuenow off it
+  // so the bar and the announced value stay consistent.
+  const clamped = () => {
+    const m = max();
+    if (!(m > 0)) return 0;
+    return Math.max(0, Math.min(local.value, m));
+  };
+  const percent = () => {
+    const m = max();
+    return m > 0 ? (clamped() / m) * 100 : 0;
+  };
+  // The progressbar must always carry an accessible name. Prefer the rendered
+  // visible label; else a caller-supplied aria-labelledby/aria-label; else a
+  // generic default so the bar is never nameless (axe `aria-progressbar-name`).
+  const labelledBy = () => (local.label ? labelId : local['aria-labelledby']);
+  const ariaLabel = () =>
+    local.label || local['aria-labelledby'] ? undefined : local['aria-label'] ?? 'Progress';
+  return (
+    <div class={cn('flex flex-col gap-1', local.class)} {...rest}>
+      <Show when={local.label}>
+        <span id={labelId} class="text-xs text-muted-foreground">{local.label}</span>
+      </Show>
+      <div
+        part="track"
+        role="progressbar"
+        aria-valuenow={clamped()}
+        aria-valuemin={0}
+        aria-valuemax={max()}
+        aria-labelledby={labelledBy()}
+        aria-label={ariaLabel()}
+        class="h-1.5 w-full overflow-hidden rounded-full bg-surface-strong"
+      >
+        <div
+          part="fill"
+          class={cn(
+            'h-full rounded-full motion-safe:transition-[width] motion-safe:duration-500 motion-safe:ease-out',
+            TONE_FILL[local.tone ?? 'primary'],
+          )}
+          style={{ width: `${percent()}%` }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/ui/prompt-dock.tsx

@@ -0,0 +1,145 @@
+import { type JSX, Show } from 'solid-js';
+import { cn } from '../utils/cn';
+
+/** 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;
+}
+
+/** Shared base styling for a lip region; per-region classes append/override it. */
+const LIP_BASE = 'px-3 py-2 text-sm leading-snug text-muted-foreground';
+
+/**
+ * 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 function PromptDock(props: PromptDockProps) {
+  const frame = (): PromptDockFrame => props.frame ?? 'inset';
+  const appearance = (): PromptDockAppearance => props.appearance ?? 'soft';
+  // `appearance` drives the surface (background / border / radius); `frame` drives the
+  // inset (padding). The two axes are independent.
+  const filled = () => appearance() === 'soft' || appearance() === 'filled';
+  const bordered = () => appearance() === 'soft' || appearance() === 'outlined';
+  return (
+    <div
+      data-prompt-dock
+      part="tray"
+      // Surface / border / radius / inset live in the tokenized inline style so the
+      // var fallbacks resolve and external overrides win; only the structural
+      // flex + gap stay in classes.
+      class={cn('flex flex-col gap-1.5', props.class)}
+      style={{
+        background: filled()
+          ? 'var(--kai-prompt-dock-surface, var(--color-surface-sunken))'
+          : 'transparent',
+        border: bordered()
+          ? '1px solid var(--kai-prompt-dock-border, var(--color-border))'
+          : '0',
+        'border-radius':
+          appearance() === 'plain' ? '0' : 'var(--kai-prompt-dock-radius, 1.25rem)',
+        padding:
+          frame() === 'none'
+            ? '0'
+            : frame() === 'edge'
+              ? 'var(--kai-prompt-dock-inset, 0.375rem) 0'
+              : 'var(--kai-prompt-dock-inset, 0.375rem)',
+      }}
+    >
+      <Show when={props.top}>
+        <div part="top" class={cn(LIP_BASE, props.topClass)}>{props.top}</div>
+      </Show>
+      {props.children}
+      <Show when={props.bottom}>
+        <div part="bottom" class={cn(LIP_BASE, props.bottomClass)}>{props.bottom}</div>
+      </Show>
+    </div>
+  );
+}

package/src/ui/resizable.tsx

@@ -53,6 +53,51 @@ export function resolveToPx(value: SizeValue | undefined, containerPx: number):
   return Number.isFinite(n) ? (n / 100) * containerPx : undefined;
 }
 
+/** Parse a CSS length we can statically clamp (`px` or `%` only). */
+function parseStaticLen(v: string): { n: number; unit: 'px' | '%' } | null {
+  const m = /^\s*(-?\d*\.?\d+)(px|%)\s*$/.exec(v);
+  return m ? { n: parseFloat(m[1]), unit: m[2] as 'px' | '%' } : null;
+}
+
+/**
+ * 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 function clampBasis(
+  basis: string | undefined,
+  min: string | undefined,
+  max: string | undefined,
+): string | undefined {
+  if (basis === undefined) return undefined;
+  // Static fast-path: when the basis and every present bound share ONE unit
+  // (all px or all %), the clamp is computable at author time, so emit a bare
+  // value. This avoids a needless clamp()/min()/max() wrapper (and keeps jsdom
+  // from reducing an all-px clamp() to calc()). MIXED units (e.g. a `%` basis
+  // against a `px` max) can only resolve against the live container, so they
+  // keep the CSS function and clamp at layout time.
+  const b = parseStaticLen(basis);
+  const lo = min === undefined ? undefined : parseStaticLen(min);
+  const hi = max === undefined ? undefined : parseStaticLen(max);
+  if (b && (min === undefined || lo?.unit === b.unit) && (max === undefined || hi?.unit === b.unit)) {
+    // CSS clamp(MIN, VAL, MAX) === max(MIN, min(VAL, MAX)).
+    let n = b.n;
+    if (hi) n = Math.min(n, hi.n);
+    if (lo) n = Math.max(n, lo.n);
+    return `${n}${b.unit}`;
+  }
+  if (min !== undefined && max !== undefined) return `clamp(${min}, ${basis}, ${max})`;
+  if (max !== undefined) return `min(${basis}, ${max})`;
+  if (min !== undefined) return `max(${min}, ${basis})`;
+  return basis;
+}
+
 // --- ResizablePanelGroup ---
 
 export interface ResizablePanelGroupProps extends JSX.HTMLAttributes<HTMLDivElement> {
@@ -112,8 +157,31 @@ function ResizablePanel(props: ResizablePanelProps) {
   // main axis to content size — the bug this replaces.) Mirrors the
   // `<kai-resizable>` web-component panel and the Shoelace/Web Awesome grid layout.
   // min:0 on BOTH axes enables shrink-to-scroll; overflow hidden.
+  // Effective min/max as CSS lengths, sourced from the typed `minSize`/`maxSize`
+  // props OR — when absent — from the `data-min-size`/`-pct` (and `-max-`)
+  // attributes a consumer may pass directly. The `kai-workspace` rail does the
+  // latter (`<ResizablePanel data-min-size="240" data-max-size="420">`). A bare
+  // `data-*-size` is pixels, `data-*-size-pct` is percent — the same convention
+  // the handle reads at drag time, so the initial clamp matches the drag clamp.
+  const effectiveBound = (
+    localVal: SizeValue | undefined,
+    pxAttr: unknown,
+    pctAttr: unknown,
+  ): string | undefined => {
+    const fromProp = normalizeSize(localVal);
+    if (fromProp !== undefined) return fromProp;
+    const px = pxAttr == null ? '' : String(pxAttr).trim();
+    if (px !== '') { const n = parseFloat(px); if (Number.isFinite(n)) return `${n}px`; }
+    const pct = pctAttr == null ? '' : String(pctAttr).trim();
+    if (pct !== '') { const n = parseFloat(pct); if (Number.isFinite(n)) return `${n}%`; }
+    return undefined;
+  };
+
   const sizeStyle = (): Record<string, string> => {
-    const basis = normalizeSize(local.defaultSize);
+    const r = rest as Record<string, unknown>;
+    const minB = effectiveBound(local.minSize, r['data-min-size'], r['data-min-size-pct']);
+    const maxB = effectiveBound(local.maxSize, r['data-max-size'], r['data-max-size-pct']);
+    const basis = clampBasis(normalizeSize(local.defaultSize), minB, maxB);
     const base: Record<string, string> = basis !== undefined
       ? { 'flex-basis': basis, 'flex-grow': '0', 'flex-shrink': '0' }
       : { flex: '1 1 0%' };

package/src/ui/scroll-area.tsx

@@ -1,14 +1,25 @@
 import { type JSX, splitProps } from 'solid-js';
 import { cn } from '../utils/cn';
 
-export interface ScrollAreaProps extends JSX.HTMLAttributes<HTMLDivElement> { children: JSX.Element; }
+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 function ScrollArea(props: ScrollAreaProps) {
-  const [local, rest] = splitProps(props, ['children', 'class']);
+  const [local, rest] = splitProps(props, ['children', 'class', 'orientation']);
+  const overflow = () =>
+    local.orientation === 'horizontal' ? 'overflow-x-auto overflow-y-hidden'
+      : local.orientation === 'both' ? 'overflow-auto'
+        : 'overflow-y-auto overflow-x-hidden';
   return (
     // tabindex=0 keeps the scroll region reachable by keyboard when it has no
     // focusable descendants (WCAG 2.1.1 — axe `scrollable-region-focusable`).
-    <div tabindex={0} class={cn('overflow-y-auto scrollbar-thin', local.class)} {...rest}>
+    <div tabindex={0} class={cn(overflow(), 'scrollbar-thin', local.class)} {...rest}>
       {local.children}
     </div>
   );