@kitnai/chat 0.7.0 → 0.8.1

package/src/ui/resizable.tsx

@@ -1,16 +1,57 @@
-import { type JSX, splitProps, createSignal, createContext, useContext, onCleanup, children as resolveChildren } from 'solid-js';
+import { type JSX, splitProps, createSignal, createContext, useContext, For, Show, children as resolveChildren } from 'solid-js';
 import { cn } from '../utils/cn';
 
 // --- Types ---
 
 type Orientation = 'horizontal' | 'vertical';
 
+/** A size value: a number (percent), `"25%"` (percent), or `"280px"` (pixels). */
+export type SizeValue = number | string;
+
 interface ResizableContextValue {
   orientation: Orientation;
-  registerPanel: (id: string, opts: { defaultSize?: number; minSize?: number; maxSize?: number }) => void;
 }
 
-const ResizableContext = createContext<ResizableContextValue>();
+export const ResizableContext = createContext<ResizableContextValue>();
+
+/**
+ * Normalize a px-or-% size into a CSS length string usable as `flex-basis`.
+ * - number → percent (`30` → `"30%"`)
+ * - `"25%"` → percent passthrough
+ * - `"280px"` → pixel passthrough
+ * Returns `undefined` for unset values (caller falls back to flexible `flex: 1`).
+ */
+export function normalizeSize(value: SizeValue | undefined): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'number') return Number.isFinite(value) ? `${value}%` : undefined;
+  const trimmed = value.trim();
+  if (trimmed === '') return undefined;
+  if (trimmed.endsWith('%') || trimmed.endsWith('px')) return trimmed;
+  // bare numeric string → percent
+  const n = Number(trimmed);
+  return Number.isFinite(n) ? `${n}%` : undefined;
+}
+
+/**
+ * Resolve a px-or-% size to pixels, given the container's main-axis size.
+ * Used to seed `data-min-size` / `data-max-size` (which the handle reads as px).
+ * Returns `undefined` when the value is unset.
+ */
+export function resolveToPx(value: SizeValue | undefined, containerPx: number): number | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'number') return Number.isFinite(value) ? (value / 100) * containerPx : undefined;
+  const trimmed = value.trim();
+  if (trimmed.endsWith('px')) {
+    const n = parseFloat(trimmed);
+    return Number.isFinite(n) ? n : undefined;
+  }
+  if (trimmed.endsWith('%')) {
+    const n = parseFloat(trimmed);
+    return Number.isFinite(n) ? (n / 100) * containerPx : undefined;
+  }
+  const n = Number(trimmed);
+  return Number.isFinite(n) ? (n / 100) * containerPx : undefined;
+}
 
 // --- ResizablePanelGroup ---
 
@@ -24,7 +65,7 @@ function ResizablePanelGroup(props: ResizablePanelGroupProps) {
   const orientation = () => local.orientation ?? 'horizontal';
 
   return (
-    <ResizableContext.Provider value={{ orientation: orientation(), registerPanel: () => {} }}>
+    <ResizableContext.Provider value={{ orientation: orientation() }}>
       <div
         class={cn(
           'flex h-full w-full',
@@ -43,27 +84,76 @@ function ResizablePanelGroup(props: ResizablePanelGroupProps) {
 // --- ResizablePanel ---
 
 export interface ResizablePanelProps extends JSX.HTMLAttributes<HTMLDivElement> {
-  defaultSize?: number;
-  minSize?: number;
-  maxSize?: number;
+  /** Initial main-axis size: number/`"25%"` (percent) or `"280px"` (pixels). Omitted → flexible. */
+  defaultSize?: SizeValue;
+  /** Minimum size during resize (px or %). */
+  minSize?: SizeValue;
+  /** Maximum size during resize (px or %). */
+  maxSize?: SizeValue;
+  /** When true, the panel's size is fixed and adjacent handles are non-draggable. */
+  locked?: boolean;
+  /** When true, the panel is not visible (used by the `Resizable` convenience to drop dividers). */
+  hidden?: boolean;
   children: JSX.Element;
 }
 
 function ResizablePanel(props: ResizablePanelProps) {
-  const [local, rest] = splitProps(props, ['defaultSize', 'minSize', 'maxSize', 'children', 'class', 'style']);
+  const [local, rest] = splitProps(props, [
+    'defaultSize', 'minSize', 'maxSize', 'locked', 'hidden', 'children', 'class', 'style',
+  ]);
+  // GRID-FILL model: the panel sizes itself on the MAIN axis via flex-basis (or
+  // flex:1 when flexible) as a flex item of the group — the handle rewrites that
+  // basis, so the drag math is plain flex. For the FILL it is itself a
+  // `display:grid` with a single `minmax(0,1fr)` cell on BOTH axes: a grid item
+  // (the child) stretches to fill its cell on both axes by default, and `1fr` of
+  // a definite-sized grid is a *definite* length — so arbitrary child content
+  // fills the panel on width AND height without needing `height:100%`, in both
+  // orientations. (A flex panel only stretches the CROSS axis, collapsing the
+  // main axis to content size — the bug this replaces.) Mirrors the
+  // `<kc-resizable>` web-component panel and the Shoelace/Web Awesome grid layout.
+  // min:0 on BOTH axes enables shrink-to-scroll; overflow hidden.
+  const sizeStyle = (): Record<string, string> => {
+    const basis = normalizeSize(local.defaultSize);
+    const base: Record<string, string> = basis !== undefined
+      ? { 'flex-basis': basis, 'flex-grow': '0', 'flex-shrink': '0' }
+      : { flex: '1 1 0%' };
+    return {
+      ...base,
+      display: 'grid',
+      'grid-template-rows': 'minmax(0, 1fr)',
+      'grid-template-columns': 'minmax(0, 1fr)',
+      'min-width': '0',
+      'min-height': '0',
+    };
+  };
 
-  const sizeStyle = () => {
-    const s = local.defaultSize;
-    if (s !== undefined) {
-      return { 'flex-basis': `${s}%`, 'flex-grow': '0', 'flex-shrink': '0' };
-    }
-    return { flex: '1 1 0%' };
+  // Reflect min/max to data-* in pixels where statically resolvable. The handle
+  // reads `data-min-size`/`data-max-size` (as px) at drag time. Percent values
+  // are resolved against the container by the handle at drag time when expressed
+  // as `data-min-size-pct` / `data-max-size-pct`; pixel values go straight to
+  // `data-min-size` / `data-max-size`.
+  const dataAttrs = () => {
+    const out: Record<string, string | undefined> = {};
+    const setBound = (val: SizeValue | undefined, pxKey: string, pctKey: string) => {
+      if (val === undefined || val === null || val === '') return;
+      if (typeof val === 'number') { out[pctKey] = String(val); return; }
+      const t = val.trim();
+      if (t.endsWith('px')) out[pxKey] = String(parseFloat(t));
+      else if (t.endsWith('%')) out[pctKey] = String(parseFloat(t));
+      else if (Number.isFinite(Number(t))) out[pctKey] = t;
+    };
+    setBound(local.minSize, 'data-min-size', 'data-min-size-pct');
+    setBound(local.maxSize, 'data-max-size', 'data-max-size-pct');
+    return out;
   };
 
   return (
     <div
       class={cn('overflow-hidden', local.class)}
       style={{ ...sizeStyle(), ...(typeof local.style === 'object' ? local.style : {}) }}
+      data-locked={local.locked ? '' : undefined}
+      hidden={local.hidden || undefined}
+      {...dataAttrs()}
       {...rest}
     >
       {local.children}
@@ -76,13 +166,38 @@ function ResizablePanel(props: ResizablePanelProps) {
 export interface ResizableHandleProps extends JSX.HTMLAttributes<HTMLDivElement> {
   withHandle?: boolean;
   onPanelResize?: (delta: number) => void;
+  /** Keyboard nudge step in pixels (default 16). Home/End jump to min/max. */
+  keyboardStep?: number;
+  /** Render as a static, non-interactive divider (e.g. between locked panels). */
+  static?: boolean;
+  /** Explicit axis; overrides `ResizableContext`. Needed by facades that render
+   * handles outside a context provider (e.g. `<kc-resizable>`). */
+  orientation?: Orientation;
+}
+
+/** Read a panel's min/max bound (px), resolving percent against the container. */
+function readBound(el: HTMLElement, kind: 'min' | 'max', containerPx: number, fallback: number): number {
+  const px = el.dataset[kind === 'min' ? 'minSize' : 'maxSize'];
+  if (px !== undefined && px !== '') {
+    const n = parseFloat(px);
+    if (Number.isFinite(n)) return n;
+  }
+  const pct = el.dataset[kind === 'min' ? 'minSizePct' : 'maxSizePct'];
+  if (pct !== undefined && pct !== '') {
+    const n = parseFloat(pct);
+    if (Number.isFinite(n)) return (n / 100) * containerPx;
+  }
+  return fallback;
 }
 
 function ResizableHandle(props: ResizableHandleProps) {
-  const [local, rest] = splitProps(props, ['withHandle', 'onPanelResize', 'class']);
+  const [local, rest] = splitProps(props, [
+    'withHandle', 'onPanelResize', 'class', 'keyboardStep', 'static', 'orientation',
+  ]);
   const ctx = useContext(ResizableContext);
-  const orientation = () => ctx?.orientation ?? 'horizontal';
+  const orientation = () => local.orientation ?? ctx?.orientation ?? 'horizontal';
   const [isDragging, setIsDragging] = createSignal(false);
+  const isStatic = () => !!local.static;
 
   let startPos = 0;
   let prevEl: HTMLElement | null = null;
@@ -90,7 +205,11 @@ function ResizableHandle(props: ResizableHandleProps) {
   let prevSize = 0;
   let nextSize = 0;
 
+  const isHoriz = () => orientation() === 'horizontal';
+  const dim = (): 'width' | 'height' => (isHoriz() ? 'width' : 'height');
+
   const handlePointerDown = (e: PointerEvent) => {
+    if (isStatic()) return;
     const handle = e.currentTarget as HTMLElement;
     prevEl = handle.previousElementSibling as HTMLElement;
     nextEl = handle.nextElementSibling as HTMLElement;
@@ -101,33 +220,52 @@ function ResizableHandle(props: ResizableHandleProps) {
     setIsDragging(true);
     handle.setPointerCapture(e.pointerId);
 
-    if (orientation() === 'horizontal') {
-      startPos = e.clientX;
-      prevSize = prevEl.getBoundingClientRect().width;
-      nextSize = nextEl.getBoundingClientRect().width;
-    } else {
-      startPos = e.clientY;
-      prevSize = prevEl.getBoundingClientRect().height;
-      nextSize = nextEl.getBoundingClientRect().height;
-    }
+    startPos = isHoriz() ? e.clientX : e.clientY;
+    prevSize = prevEl.getBoundingClientRect()[dim()];
+    nextSize = nextEl.getBoundingClientRect()[dim()];
   };
 
   const handlePointerMove = (e: PointerEvent) => {
     if (!isDragging() || !prevEl || !nextEl) return;
 
-    const currentPos = orientation() === 'horizontal' ? e.clientX : e.clientY;
+    const currentPos = isHoriz() ? e.clientX : e.clientY;
     const delta = currentPos - startPos;
+    applyDelta(delta);
+  };
 
-    const newPrevSize = prevSize + delta;
-    const newNextSize = nextSize - delta;
-
-    // Get min/max from data attributes or use defaults
-    const prevMin = parseInt(prevEl.dataset.minSize || '0', 10);
-    const prevMax = parseInt(prevEl.dataset.maxSize || '999999', 10);
-    const nextMin = parseInt(nextEl.dataset.minSize || '0', 10);
-    const nextMax = parseInt(nextEl.dataset.maxSize || '999999', 10);
-
-    if (newPrevSize < prevMin || newNextSize < nextMin || newPrevSize > prevMax || newNextSize > nextMax) return;
+  /**
+   * Apply a pixel delta to the adjacent panels. The delta is CLAMPED (not
+   * rejected) so the dragged panel lands exactly on the nearest min/max bound
+   * — this avoids the stair-step where a step that would cross a bound was
+   * dropped wholesale, leaving the panel short of its limit.
+   */
+  function applyDelta(delta: number): boolean {
+    if (!prevEl || !nextEl) return false;
+    const container = prevEl.parentElement;
+    const containerPx = container ? container.getBoundingClientRect()[dim()] : 0;
+
+    const prevMin = readBound(prevEl, 'min', containerPx, 0);
+    const prevMax = readBound(prevEl, 'max', containerPx, 999999);
+    const nextMin = readBound(nextEl, 'min', containerPx, 0);
+    const nextMax = readBound(nextEl, 'max', containerPx, 999999);
+
+    // Clamp the delta to the tightest bound across both panels. prev grows by
+    // +delta, next shrinks by -delta (and vice versa), so each bound maps to a
+    // limit on delta. Intersect them all, then clamp the requested delta.
+    let lo = -Infinity; // most-negative allowed delta
+    let hi = Infinity;  // most-positive allowed delta
+    // prev: prevSize + delta in [prevMin, prevMax]
+    lo = Math.max(lo, prevMin - prevSize);
+    hi = Math.min(hi, prevMax - prevSize);
+    // next: nextSize - delta in [nextMin, nextMax] → delta in [nextSize-nextMax, nextSize-nextMin]
+    lo = Math.max(lo, nextSize - nextMax);
+    hi = Math.min(hi, nextSize - nextMin);
+
+    if (lo > hi) return false; // no feasible delta (contradictory bounds)
+    const clamped = Math.max(lo, Math.min(hi, delta));
+
+    const newPrevSize = prevSize + clamped;
+    const newNextSize = nextSize - clamped;
 
     prevEl.style.flexBasis = `${newPrevSize}px`;
     prevEl.style.flexGrow = '0';
@@ -136,44 +274,103 @@ function ResizableHandle(props: ResizableHandleProps) {
     nextEl.style.flexGrow = '0';
     nextEl.style.flexShrink = '0';
 
-    local.onPanelResize?.(delta);
-  };
+    local.onPanelResize?.(clamped);
+    return true;
+  }
+
+  /**
+   * Convert the pixel flex-basis on the TWO adjacent panels to percentages of
+   * the container, INDEPENDENTLY of one another. With >2 panels, `nextPct` is
+   * NOT `100 - prevPct` (that would steal the other panels' space and overflow
+   * the container) — each panel's percent is its own pixel size over the total.
+   * All other panels are left untouched.
+   */
+  function settleToPercent() {
+    if (!prevEl || !nextEl) return;
+    const container = prevEl.parentElement;
+    if (!container) return;
+    const total = container.getBoundingClientRect()[dim()];
+    if (total <= 0) return;
+    const prevPct = (prevEl.getBoundingClientRect()[dim()] / total) * 100;
+    const nextPct = (nextEl.getBoundingClientRect()[dim()] / total) * 100;
+    prevEl.style.flexBasis = `${prevPct}%`;
+    nextEl.style.flexBasis = `${nextPct}%`;
+  }
 
   const handlePointerUp = () => {
-    // Convert pixel flex-basis to percentages so panels scale with window resize
-    if (prevEl && nextEl) {
-      const container = prevEl.parentElement;
-      if (container) {
-        const totalSize = orientation() === 'horizontal'
-          ? container.getBoundingClientRect().width
-          : container.getBoundingClientRect().height;
-        const handleSize = (prevEl.nextElementSibling as HTMLElement)?.getBoundingClientRect()[
-          orientation() === 'horizontal' ? 'width' : 'height'
-        ] ?? 0;
-        const available = totalSize - handleSize;
-        if (available > 0) {
-          const prevPct = (prevEl.getBoundingClientRect()[orientation() === 'horizontal' ? 'width' : 'height'] / available) * 100;
-          const nextPct = 100 - prevPct;
-          prevEl.style.flexBasis = `${prevPct}%`;
-          nextEl.style.flexBasis = `${nextPct}%`;
-        }
-      }
-    }
+    settleToPercent();
     setIsDragging(false);
     prevEl = null;
     nextEl = null;
   };
 
-  const isHoriz = () => orientation() === 'horizontal';
+  // --- Keyboard resize ---
+  const aria = createSignal(50);
+  const [valueNow, setValueNow] = aria;
+
+  /** Seed prev/next refs + sizes for a keyboard nudge starting from a key event. */
+  function beginKeyboard(handle: HTMLElement) {
+    prevEl = handle.previousElementSibling as HTMLElement;
+    nextEl = handle.nextElementSibling as HTMLElement;
+    if (!prevEl || !nextEl) return false;
+    prevSize = prevEl.getBoundingClientRect()[dim()];
+    nextSize = nextEl.getBoundingClientRect()[dim()];
+    return true;
+  }
+
+  function updateAria() {
+    if (!prevEl) return;
+    const container = prevEl.parentElement;
+    if (!container) return;
+    const total = container.getBoundingClientRect()[dim()];
+    if (total <= 0) return;
+    const pct = (prevEl.getBoundingClientRect()[dim()] / total) * 100;
+    setValueNow(Math.round(pct));
+  }
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (isStatic()) return;
+    const handle = e.currentTarget as HTMLElement;
+    const step = local.keyboardStep ?? 16;
+    const horiz = isHoriz();
+    const decKey = horiz ? 'ArrowLeft' : 'ArrowUp';
+    const incKey = horiz ? 'ArrowRight' : 'ArrowDown';
+
+    let delta: number | 'min' | 'max' | null = null;
+    if (e.key === decKey) delta = -step;
+    else if (e.key === incKey) delta = step;
+    else if (e.key === 'Home') delta = 'min';
+    else if (e.key === 'End') delta = 'max';
+    else return;
+
+    e.preventDefault();
+    if (!beginKeyboard(handle)) return;
+
+    if (delta === 'min') {
+      // Shrink prev to its minimum.
+      const container = prevEl!.parentElement;
+      const containerPx = container ? container.getBoundingClientRect()[dim()] : 0;
+      const prevMin = readBound(prevEl!, 'min', containerPx, 0);
+      applyDelta(prevMin - prevSize);
+    } else if (delta === 'max') {
+      const container = prevEl!.parentElement;
+      const containerPx = container ? container.getBoundingClientRect()[dim()] : 0;
+      const prevMax = readBound(prevEl!, 'max', containerPx, 999999);
+      applyDelta(prevMax - prevSize);
+    } else {
+      applyDelta(delta);
+    }
+    updateAria();
+    settleToPercent();
+    prevEl = null;
+    nextEl = null;
+  };
 
   return (
     <div
-      class={cn(
-        'relative flex items-center justify-center',
-        local.class
-      )}
+      class={cn('relative flex items-center justify-center', local.class)}
       style={{
-        cursor: isHoriz() ? 'col-resize' : 'row-resize',
+        cursor: isStatic() ? 'default' : isHoriz() ? 'col-resize' : 'row-resize',
         [isHoriz() ? 'width' : 'height']: '8px',
         'background': isDragging() ? 'var(--color-muted-foreground, #98989f)' : 'transparent',
         'opacity': isDragging() ? '0.3' : '1',
@@ -181,24 +378,28 @@ function ResizableHandle(props: ResizableHandleProps) {
       onPointerDown={handlePointerDown}
       onPointerMove={handlePointerMove}
       onPointerUp={handlePointerUp}
+      onKeyDown={handleKeyDown}
       role="separator"
-      tabIndex={0}
+      tabIndex={isStatic() ? undefined : 0}
       data-orientation={orientation()}
+      data-static={isStatic() ? '' : undefined}
+      aria-orientation={isHoriz() ? 'vertical' : 'horizontal'}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={valueNow()}
       {...rest}
     >
-      {local.withHandle && (
+      <Show when={local.withHandle}>
         <div
           class={cn(
             'z-10 flex items-center justify-center',
-            orientation() === 'horizontal'
-              ? 'h-6 w-3 flex-col'
-              : 'h-3 w-6 flex-row',
+            isHoriz() ? 'h-6 w-3 flex-col' : 'h-3 w-6 flex-row',
           )}
         >
           <svg
             class={cn(
               'text-muted-foreground/40',
-              orientation() === 'horizontal' ? 'h-3 w-2' : 'h-2 w-3 rotate-90'
+              isHoriz() ? 'h-3 w-2' : 'h-2 w-3 rotate-90'
             )}
             viewBox="0 0 4 8"
             fill="currentColor"
@@ -211,9 +412,88 @@ function ResizableHandle(props: ResizableHandleProps) {
             <circle cx="3" cy="6.5" r="0.6" />
           </svg>
         </div>
-      )}
+      </Show>
     </div>
   );
 }
 
-export { ResizablePanelGroup, ResizablePanel, ResizableHandle };
+// --- Resizable (convenience: auto-inserts handles between visible panels) ---
+
+export interface ResizableProps {
+  orientation?: Orientation;
+  /** Fired on drag-end / keyboard resize / visibility change with the current panel sizes (percent). */
+  onChange?: (sizes: number[]) => void;
+  /** Show a visible grip on each interactive handle. */
+  withHandle?: boolean;
+  class?: string;
+  /** `ResizablePanel` children. */
+  children: JSX.Element;
+}
+
+/**
+ * Convenience group that takes `ResizablePanel` children and AUTO-INSERTS a
+ * `ResizableHandle` between each pair of visible (non-`hidden`) panels. A handle
+ * is interactive only between two unlocked neighbors; otherwise it renders as a
+ * static divider. Power users who need manual control can keep using
+ * `ResizablePanelGroup` + explicit `ResizableHandle`s.
+ */
+function Resizable(props: ResizableProps) {
+  const [local] = splitProps(props, ['orientation', 'onChange', 'withHandle', 'class', 'children']);
+  const orientation = () => local.orientation ?? 'horizontal';
+
+  // Resolve children to the actual panel elements so we can read their props.
+  const resolved = resolveChildren(() => local.children);
+
+  const panels = (): { el: Element; locked: boolean; hidden: boolean }[] => {
+    const arr = resolved.toArray().filter((c): c is Element => c instanceof Element);
+    return arr.map((el) => ({
+      el,
+      locked: el.hasAttribute('data-locked'),
+      hidden: (el as HTMLElement).hidden || el.hasAttribute('hidden'),
+    }));
+  };
+
+  const visible = () => panels().filter((p) => !p.hidden);
+
+  function emitChange() {
+    if (!local.onChange) return;
+    const sizes = visible().map((p) => {
+      const r = (p.el as HTMLElement).getBoundingClientRect();
+      const parent = (p.el as HTMLElement).parentElement;
+      const total = parent ? parent.getBoundingClientRect()[orientation() === 'horizontal' ? 'width' : 'height'] : 0;
+      const dimVal = r[orientation() === 'horizontal' ? 'width' : 'height'];
+      return total > 0 ? Math.round((dimVal / total) * 100) : 0;
+    });
+    local.onChange(sizes);
+  }
+
+  return (
+    <ResizableContext.Provider value={{ orientation: orientation() }}>
+      <div
+        class={cn(
+          'flex h-full w-full',
+          orientation() === 'vertical' ? 'flex-col' : 'flex-row',
+          local.class,
+        )}
+        data-orientation={orientation()}
+      >
+        <For each={visible()}>
+          {(panel, i) => (
+            <>
+              <Show when={i() > 0}>
+                <ResizableHandle
+                  withHandle={local.withHandle}
+                  static={panel.locked || visible()[i() - 1]?.locked}
+                  onPanelResize={() => emitChange()}
+                />
+              </Show>
+              {panel.el as unknown as JSX.Element}
+            </>
+          )}
+        </For>
+      </div>
+    </ResizableContext.Provider>
+  );
+}
+
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle, Resizable };

package/src/ui/scroll-area.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { For } from 'solid-js';
 import { ScrollArea } from './scroll-area';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/ScrollArea',
@@ -9,13 +10,11 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A vertically scrollable container with thin, themed scrollbars (`scrollbar-thin` + muted thumb, transparent track). A thin styling layer over native overflow — no custom scroll hijacking, so momentum, keyboard, and accessibility behave exactly like the platform expects. Constrain it with a height (or let a flex parent bound it) and overflow content scrolls.',
-          '**When to use:** any bounded region whose content can exceed its height — the conversation/history sidebar, a long menu, a tall card body.',
-          '**How to use:** set a height via `class` and drop the scrollable content inside. All other div props (e.g. `aria-label`) are forwarded.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A vertically scrollable container with thin, themed scrollbars (`scrollbar-thin` + muted thumb, transparent track). A thin styling layer over native overflow — no custom scroll hijacking, so momentum, keyboard, and accessibility behave exactly like the platform expects. Constrain it with a height (or let a flex parent bound it) and overflow content scrolls.',
+        '**When to use:** any bounded region whose content can exceed its height — the conversation/history sidebar, a long menu, a tall card body.',
+        '**How to use:** set a height via `class` and drop the scrollable content inside. All other div props (e.g. `aria-label`) are forwarded.',
+      ]),
     },
   },
   render: () => (

package/src/ui/scroll-area.tsx

@@ -6,7 +6,9 @@ export interface ScrollAreaProps extends JSX.HTMLAttributes<HTMLDivElement> { ch
 export function ScrollArea(props: ScrollAreaProps) {
   const [local, rest] = splitProps(props, ['children', 'class']);
   return (
-    <div class={cn('overflow-y-auto scrollbar-thin', local.class)} {...rest}>
+    // 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}>
       {local.children}
     </div>
   );

package/src/ui/separator.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Separator } from './separator';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/Separator',
@@ -9,14 +10,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A thin **divider** line (a `role="separator"` element) that visually splits content either horizontally or vertically.',
-          '**When to use:** to separate stacked sections, group items in a menu/list, or divide inline controls in a toolbar.',
-          '**How to use:** set `orientation` to `horizontal` (full-width line) or `vertical` (full-height line). For a vertical separator, give the parent a height so the line has something to fill.',
-          '**Placement:** between message groups, in dropdown/menu sections, header toolbars, and between sidebar regions.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A thin **divider** line (a `role="separator"` element) that visually splits content either horizontally or vertically.',
+        '**When to use:** to separate stacked sections, group items in a menu/list, or divide inline controls in a toolbar.',
+        '**How to use:** set `orientation` to `horizontal` (full-width line) or `vertical` (full-height line). For a vertical separator, give the parent a height so the line has something to fill.',
+        '**Placement:** between message groups, in dropdown/menu sections, header toolbars, and between sidebar regions.',
+      ]),
     },
   },
   argTypes: {

package/src/ui/skeleton.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Skeleton } from './skeleton';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/Skeleton',
@@ -9,14 +10,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A pulsing **placeholder** block used to indicate loading content. It has no shape of its own — size and rounding come from the `class` you pass.',
-          '**When to use:** while content (messages, lists, cards, tool output) is loading, to preserve layout and signal progress without a spinner.',
-          '**How to use:** compose one or more `Skeleton` elements and set width/height/rounding via utility classes (e.g. `class="h-4 w-3/4"`). Build skeletons that mirror the real layout they replace.',
-          '**Placement:** message bubbles, conversation lists, code blocks, tool calls, input areas, and full-page loading states.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A pulsing **placeholder** block used to indicate loading content. It has no shape of its own — size and rounding come from the `class` you pass.',
+        '**When to use:** while content (messages, lists, cards, tool output) is loading, to preserve layout and signal progress without a spinner.',
+        '**How to use:** compose one or more `Skeleton` elements and set width/height/rounding via utility classes (e.g. `class="h-4 w-3/4"`). Build skeletons that mirror the real layout they replace.',
+        '**Placement:** message bubbles, conversation lists, code blocks, tool calls, input areas, and full-page loading states.',
+      ]),
     },
   },
   argTypes: {