@kitn.ai/ui 0.14.1

package/src/ui/overlay.tsx

@@ -0,0 +1,158 @@
+import {
+  createSignal, createEffect, onCleanup, splitProps, type Accessor, type JSX,
+} from 'solid-js';
+import { Dynamic } from 'solid-js/web';
+import {
+  computePosition, autoUpdate, offset, flip, shift, arrow, hide, type Placement,
+} from '@floating-ui/dom';
+
+/**
+ * Keep a node mounted through its CSS exit animation.
+ * Open  -> present=true, state='open'  (enter animation via base classes)
+ * Close -> state='closed' (data-closed triggers tw-animate-css animate-out),
+ *          then unmount on `animationend`. If no animation is defined
+ *          (e.g. jsdom), unmount on the next microtask.
+ */
+export function createPresence(show: Accessor<boolean>) {
+  const [present, setPresent] = createSignal(show());
+  const [state, setState] = createSignal<'open' | 'closed'>(show() ? 'open' : 'closed');
+  let node: Element | undefined;
+  let generation = 0;
+  const setRef = (el: Element) => { node = el; };
+
+  createEffect((prev: boolean | undefined) => {
+    const visible = show();
+    if (visible) {
+      generation++;
+      setPresent(true);
+      setState('open');
+    } else if (prev) {
+      setState('closed');
+      const el = node;
+      const hasAnim = el && (() => {
+        const cs = getComputedStyle(el);
+        return cs.animationName !== 'none' && parseFloat(cs.animationDuration || '0') > 0;
+      })();
+      if (!el || !hasAnim) {
+        const gen = ++generation;
+        queueMicrotask(() => { if (gen === generation) setPresent(false); });
+        return visible;
+      }
+      const animEl = el as HTMLElement;
+      const onEnd = (e: AnimationEvent) => {
+        if (e.target !== animEl) return;
+        animEl.removeEventListener('animationend', onEnd);
+        setPresent(false);
+      };
+      animEl.addEventListener('animationend', onEnd);
+      onCleanup(() => animEl.removeEventListener('animationend', onEnd));
+    }
+    return visible;
+  });
+
+  return { present, state, setRef };
+}
+
+export type AsTag = string | ((props: Record<string, any>) => JSX.Element);
+
+/**
+ * Polymorphic element. `as` may be a tag name (default 'span') or a render
+ * function that receives the forwarded props (render-prop style `as={fn}`).
+ * Uses splitProps (NOT destructuring) so reactive forwarded props such as
+ * aria-expanded stay reactive. All extra props (incl. `ref`, event handlers,
+ * aria-*) are forwarded. `children` is left in `rest` so it forwards naturally.
+ */
+export function As(props: { as?: AsTag; children?: JSX.Element; [k: string]: any }) {
+  const [local, rest] = splitProps(props, ['as']);
+  if (typeof local.as === 'function') return local.as(rest);
+  return <Dynamic component={local.as ?? 'span'} {...rest} />;
+}
+
+export interface UsePositionOptions {
+  placement?: Placement;
+  gutter?: number;
+  arrowEl?: Accessor<HTMLElement | undefined>;
+}
+
+/**
+ * Position `floating` relative to `reference` using fixed strategy + autoUpdate,
+ * so the element tracks the trigger on scroll/resize (fix DD-2). Writes
+ * position into the returned `pos` signal; caller applies it as inline style.
+ *
+ * `options` (placement/gutter) are read at setup time — pass static values;
+ * reactive option changes won't reposition until the next autoUpdate tick.
+ */
+export function usePosition(
+  reference: Accessor<HTMLElement | undefined>,
+  floating: Accessor<HTMLElement | undefined>,
+  options: UsePositionOptions = {},
+) {
+  const [pos, setPos] = createSignal<{ x: number; y: number; placement: Placement }>(
+    { x: 0, y: 0, placement: options.placement ?? 'bottom' },
+  );
+  const [arrowPos, setArrowPos] = createSignal<{ x?: number; y?: number }>({});
+  // True when the trigger has scrolled out of view (clipped by an ancestor or the
+  // viewport). Callers should hide the floating node so it doesn't stick to the
+  // edge — Floating UI's `hide` middleware. autoUpdate keeps this live on scroll.
+  const [hidden, setHidden] = createSignal(false);
+
+  createEffect(() => {
+    const ref = reference();
+    const float = floating();
+    if (!ref || !float) return;
+    const update = () => {
+      // `hide()` is read last so it reflects the final, shifted/flipped position.
+      const middleware = [offset(options.gutter ?? 8), flip(), shift({ padding: 8 })];
+      const aEl = options.arrowEl?.();
+      if (aEl) middleware.push(arrow({ element: aEl }));
+      middleware.push(hide());
+      computePosition(ref, float, {
+        placement: options.placement ?? 'bottom',
+        strategy: 'fixed',
+        middleware,
+      }).then(({ x, y, placement, middlewareData }) => {
+        setPos({ x, y, placement });
+        if (middlewareData.arrow) setArrowPos({ x: middlewareData.arrow.x, y: middlewareData.arrow.y });
+        setHidden(!!middlewareData.hide?.referenceHidden);
+      });
+    };
+    const cleanup = autoUpdate(ref, float, update);
+    onCleanup(cleanup);
+  });
+
+  return { pos, arrowPos, hidden };
+}
+
+export type DismissReason = 'escape' | 'outside';
+
+export interface UseDismissOptions {
+  enabled: Accessor<boolean>;
+  onDismiss: (reason: DismissReason) => void;
+  /** Elements considered "inside" (trigger + content). Pointerdown outside all of them dismisses. */
+  refs: () => (HTMLElement | undefined)[];
+}
+
+/**
+ * Escape key + outside-pointerdown dismissal. Does NOT lock page scroll (fix DD-1).
+ *
+ * `onDismiss` and `refs` are captured at call time (component setup), which is
+ * fine in SolidJS since components don't re-run — ensure they close over mutable
+ * variables, not stale values.
+ */
+export function useDismiss(opts: UseDismissOptions) {
+  createEffect(() => {
+    if (!opts.enabled()) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') opts.onDismiss('escape'); };
+    const onPointer = (e: PointerEvent) => {
+      const target = e.target as Node;
+      const inside = opts.refs().some((el) => el && el.contains(target));
+      if (!inside) opts.onDismiss('outside');
+    };
+    document.addEventListener('keydown', onKey);
+    document.addEventListener('pointerdown', onPointer, true);
+    onCleanup(() => {
+      document.removeEventListener('keydown', onKey);
+      document.removeEventListener('pointerdown', onPointer, true);
+    });
+  });
+}

package/src/ui/popover.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { fn } from 'storybook/test';
+import { createSignal, Show, For } from 'solid-js';
+import { Popover, type PopoverProps } from './popover';
+import { Switch } from './switch';
+import { Button } from './button';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Popover',
+  component: Popover,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'A **popover**: a trigger that toggles a floating panel of arbitrary content. Unlike `Dropdown` (a `role="menu"` with roving focus), the panel is a `role="dialog"` region, so it holds anything — model rows, toggles, nested groups.',
+        '**When to use:** a "button + card" affordance — a header model menu, a settings popover, an account dropdown with mixed controls. For a simple list of commands, use `Dropdown` instead.',
+        '**How to use:** pass the control as `trigger` and the panel as `children`. Clicking the trigger toggles; Escape or an outside click closes (clicks inside do not). Uncontrolled by default; pass `open` + `onOpenChange` to control it.',
+        '**Placement:** chat headers, toolbars, and anywhere a compact control should reveal a richer card.',
+      ]),
+    },
+  },
+  argTypes: {
+    placement: {
+      control: 'select',
+      options: ['bottom-start', 'bottom', 'bottom-end', 'top-start', 'top', 'top-end', 'left', 'right'],
+      description: 'Floating placement relative to the trigger.',
+      table: { defaultValue: { summary: 'bottom-start' } },
+    },
+    gutter: { control: 'number', description: 'Gap in px between trigger and panel.', table: { defaultValue: { summary: '6' } } },
+    open: { control: 'boolean', description: 'Controlled open state. Omit for click-to-toggle.' },
+  },
+  args: { placement: 'bottom-start', onOpenChange: fn() },
+} satisfies Meta<typeof Popover>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const LEGACY = ['GPT-4o', 'GPT-4.1', 'GPT-4o mini'];
+const row = 'flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-foreground hover:bg-muted';
+
+/** A model menu rebuilt from the primitive — flagship row, an expandable group,
+ *  and a Switch — the kind of card a plain menu can't hold. */
+export const ModelMenu: Story = {
+  render: (args: Partial<PopoverProps>) => {
+    const [legacyOpen, setLegacyOpen] = createSignal(false);
+    return (
+      <Popover {...args} trigger={<Button variant="ghost" size="sm">GPT-5.5 ▾</Button>}>
+        <div style={{ width: '15rem' }}>
+          <button type="button" class={row}>
+            <span style={{ 'font-weight': 600 }}>GPT-5.5</span>
+            <span class="text-caption text-muted-foreground">Flagship</span>
+          </button>
+          <button type="button" class={row} aria-expanded={legacyOpen()} onClick={() => setLegacyOpen(!legacyOpen())}>
+            Legacy models {legacyOpen() ? '▴' : '▾'}
+          </button>
+          <Show when={legacyOpen()}>
+            <For each={LEGACY}>{(m) => <button type="button" class={row} style={{ 'padding-left': '1.75rem' }}>{m}</button>}</For>
+          </Show>
+          <div style={{ height: '1px', margin: '4px 0', background: 'var(--color-border)' }} />
+          <div class={row} style={{ 'justify-content': 'space-between' }}>
+            <span>Temporary chat</span>
+            <Switch label="Temporary chat" />
+          </div>
+        </div>
+      </Popover>
+    );
+  },
+};
+
+/** Minimal — a trigger and a small card. */
+export const Basic: Story = {
+  render: (args: Partial<PopoverProps>) => (
+    <Popover {...args} trigger={<Button size="sm">Open</Button>}>
+      <div style={{ width: '12rem', padding: '0.5rem' }} class="text-sm text-foreground">
+        Any content goes here — this is a <code>role="dialog"</code> panel.
+      </div>
+    </Popover>
+  ),
+};

package/src/ui/popover.test.tsx

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup, fireEvent } from '@solidjs/testing-library';
+import { Popover } from './popover';
+
+afterEach(cleanup);
+
+// createPresence unmounts on a microtask when there is no exit animation (jsdom),
+// so flush the queue before asserting a closed popover has left the DOM.
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('Popover', () => {
+  it('renders the trigger and hides the content until opened', () => {
+    const { getByText, queryByText } = render(() => (
+      <Popover trigger={<button>Open menu</button>}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    expect(getByText('Open menu')).toBeInTheDocument();
+    expect(queryByText('Panel body')).not.toBeInTheDocument();
+  });
+
+  it('opens on trigger click and calls onOpenChange(true)', () => {
+    const onOpenChange = vi.fn();
+    const { getByText, queryByText } = render(() => (
+      <Popover trigger={<button>Open menu</button>} onOpenChange={onOpenChange}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    fireEvent.click(getByText('Open menu'));
+    expect(queryByText('Panel body')).toBeInTheDocument();
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it('toggles closed on a second trigger click and calls onOpenChange(false)', async () => {
+    const onOpenChange = vi.fn();
+    const { getByText, queryByText } = render(() => (
+      <Popover trigger={<button>Open menu</button>} onOpenChange={onOpenChange}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    const trigger = getByText('Open menu');
+    fireEvent.click(trigger);
+    expect(queryByText('Panel body')).toBeInTheDocument();
+    fireEvent.click(trigger);
+    await tick();
+    expect(queryByText('Panel body')).not.toBeInTheDocument();
+    expect(onOpenChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it('closes on Escape', async () => {
+    const { getByText, queryByText } = render(() => (
+      <Popover trigger={<button>Open menu</button>}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    fireEvent.click(getByText('Open menu'));
+    expect(queryByText('Panel body')).toBeInTheDocument();
+    fireEvent.keyDown(document, { key: 'Escape' });
+    await tick();
+    expect(queryByText('Panel body')).not.toBeInTheDocument();
+  });
+
+  it('stays open when clicking inside the panel, closes on an outside pointerdown', async () => {
+    const { getByText, queryByText } = render(() => (
+      <Popover trigger={<button>Open menu</button>}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    fireEvent.click(getByText('Open menu'));
+    fireEvent.pointerDown(getByText('Panel body'));
+    expect(queryByText('Panel body')).toBeInTheDocument();
+    fireEvent.pointerDown(document.body);
+    await tick();
+    expect(queryByText('Panel body')).not.toBeInTheDocument();
+  });
+
+  it('respects the controlled open prop', () => {
+    const { queryByText } = render(() => (
+      <Popover open trigger={<button>Open menu</button>}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    expect(queryByText('Panel body')).toBeInTheDocument();
+  });
+
+  it('does not change its own state when controlled — defers to onOpenChange', () => {
+    const onOpenChange = vi.fn();
+    const { getByText, queryByText } = render(() => (
+      <Popover open={false} trigger={<button>Open menu</button>} onOpenChange={onOpenChange}>
+        <div>Panel body</div>
+      </Popover>
+    ));
+    fireEvent.click(getByText('Open menu'));
+    // controlled: stays closed until the parent flips `open`
+    expect(queryByText('Panel body')).not.toBeInTheDocument();
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+});

package/src/ui/popover.tsx

@@ -0,0 +1,92 @@
+import { createSignal, Show, type JSX } from 'solid-js';
+import type { Placement } from '@floating-ui/dom';
+import { cn } from '../utils/cn';
+import { createPresence, usePosition, useDismiss } from './overlay';
+
+export interface PopoverProps {
+  /** The trigger content (e.g. a button). Clicking it toggles the popover. */
+  trigger: JSX.Element;
+  /** The popover panel content — arbitrary nodes (rows, toggles, nested groups). */
+  children: JSX.Element;
+  /** Floating placement relative to the trigger. */
+  placement?: Placement;
+  /** Gap in px between trigger and panel. */
+  gutter?: number;
+  /** Controlled open state. When set, the component never changes it itself —
+   *  drive it from `onOpenChange`. Omit for uncontrolled (internal) state. */
+  open?: boolean;
+  /** Initial open state when uncontrolled. */
+  defaultOpen?: boolean;
+  /** Fires whenever the popover wants to open or close. */
+  onOpenChange?: (open: boolean) => 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;
+  /** Class applied to the floating panel. */
+  class?: string;
+}
+
+/**
+ * A general popover: a trigger that toggles a floating panel of arbitrary
+ * content. Unlike `Dropdown` (role="menu" + roving focus), the panel is a
+ * `role="dialog"` region, so it can hold model rows, toggles, nested groups —
+ * anything. Positioning, exit animation, and Escape/outside-click dismissal
+ * come from the shared overlay primitives.
+ */
+export function Popover(props: PopoverProps) {
+  const [internalOpen, setInternalOpen] = createSignal(props.defaultOpen ?? false);
+  const [trigger, setTrigger] = createSignal<HTMLElement>();
+  const [panel, setPanel] = createSignal<HTMLElement>();
+
+  const isControlled = () => props.open !== undefined;
+  const isOpen = () => (isControlled() ? !!props.open : internalOpen());
+  const setOpen = (v: boolean) => {
+    if (!isControlled()) setInternalOpen(v);
+    props.onOpenChange?.(v);
+  };
+
+  const presence = createPresence(isOpen);
+  const position = usePosition(trigger, panel, {
+    placement: props.placement ?? 'bottom-start',
+    gutter: props.gutter ?? 6,
+  });
+  useDismiss({
+    enabled: isOpen,
+    onDismiss: () => setOpen(false),
+    refs: () => [trigger(), panel(), props.boundary?.()],
+  });
+
+  return (
+    <>
+      <span
+        ref={setTrigger}
+        style={{ display: 'inline-flex' }}
+        onClick={() => setOpen(!isOpen())}
+      >
+        {props.trigger}
+      </span>
+      <Show when={presence.present()}>
+        <div
+          ref={(el) => { setPanel(el); presence.setRef(el); }}
+          role="dialog"
+          data-expanded={presence.state() === 'open' ? '' : undefined}
+          data-closed={presence.state() === 'closed' ? '' : undefined}
+          style={{
+            position: 'fixed', left: `${position.pos().x}px`, top: `${position.pos().y}px`,
+            // hide (without unmounting) when the trigger scrolls out of view
+            visibility: position.hidden() ? 'hidden' : 'visible',
+            'pointer-events': position.hidden() ? 'none' : undefined,
+          }}
+          class={cn(
+            // text-sm is a sensible menu default; slotted content can override it.
+            'z-50 min-w-[12rem] rounded-lg bg-card p-1 text-sm kai-elevation',
+            'animate-in fade-in-0 zoom-in-95 data-[closed]:animate-out data-[closed]:fade-out-0 data-[closed]:zoom-out-95',
+            props.class,
+          )}
+        >
+          {props.children}
+        </div>
+      </Show>
+    </>
+  );
+}

package/src/ui/resizable.stories.tsx

@@ -0,0 +1,236 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { fn } from 'storybook/test';
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle, Resizable } from './resizable';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Primitives/Resizable',
+  component: ResizablePanelGroup,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      controls: { exclude: ['use:eventListener'] },
+      description: componentDescription([
+        'A **resizable split layout**: `ResizablePanelGroup` lays out `ResizablePanel` children along an axis, divided by a draggable `ResizableHandle`.',
+        '**When to use:** to let users adjust the relative size of two or more regions — e.g. a collapsible sidebar next to the main chat, or a chat pane next to an inspector.',
+        '**How to use:** wrap panels in `ResizablePanelGroup` and set `orientation` (`horizontal` row / `vertical` column). Give panels a `defaultSize` (percent) and optional `minSize`/`maxSize`; min/max are read from `data-min-size`/`data-max-size` attributes at drag time. Place a `ResizableHandle` (add `withHandle` for a visible grip) between panels. The group needs a sized container (height/width).',
+        '**Placement:** app shells — sidebar + conversation, conversation + context/inspector panels, or stacked editor/preview regions.',
+      ]),
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+      description: 'Axis the panels are laid out along.',
+      table: { defaultValue: { summary: 'horizontal' } },
+    },
+  },
+  args: {
+    orientation: 'horizontal',
+  },
+  render: (args) => (
+    <div class="h-48 w-full max-w-2xl rounded-lg border border-border overflow-hidden">
+      <ResizablePanelGroup {...args}>
+        <ResizablePanel defaultSize={30} data-min-size="100" data-max-size="400">
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Sidebar</span>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle withHandle />
+        <ResizablePanel>
+          <div class="flex h-full items-center justify-center p-4">
+            <span class="text-sm text-muted-foreground">Content</span>
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  ),
+} satisfies Meta<typeof ResizablePanelGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — flip the orientation, then drag the handle. */
+export const Playground: Story = {
+  ...src(`<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel defaultSize={30} data-min-size="100" data-max-size="400">
+    Sidebar
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel>Content</ResizablePanel>
+</ResizablePanelGroup>`),
+};
+
+export const Horizontal: Story = {
+  args: { orientation: 'horizontal' },
+  ...src(`<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel defaultSize={30} data-min-size="100" data-max-size="400">
+    Sidebar
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel>Content</ResizablePanel>
+</ResizablePanelGroup>`),
+};
+
+/** Stacked top/bottom split (showcase). */
+export const Vertical: Story = {
+  render: () => (
+    <div class="h-96 w-full max-w-md rounded-lg border border-border overflow-hidden">
+      <ResizablePanelGroup orientation="vertical">
+        <ResizablePanel defaultSize={40} data-min-size="60" data-max-size="300">
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Top</span>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle withHandle />
+        <ResizablePanel>
+          <div class="flex h-full items-center justify-center p-4">
+            <span class="text-sm text-muted-foreground">Bottom</span>
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  ),
+  ...src(`<ResizablePanelGroup orientation="vertical">
+  <ResizablePanel defaultSize={40} data-min-size="60" data-max-size="300">
+    Top
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel>Bottom</ResizablePanel>
+</ResizablePanelGroup>`),
+};
+
+/** Three panels with two handles (showcase). */
+export const ThreePanels: Story = {
+  name: 'Three Panels',
+  render: () => (
+    <div class="h-48 w-full max-w-2xl rounded-lg border border-border overflow-hidden">
+      <ResizablePanelGroup orientation="horizontal">
+        <ResizablePanel defaultSize={25} data-min-size="80" data-max-size="300">
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Left</span>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel>
+          <div class="flex h-full items-center justify-center p-4">
+            <span class="text-sm text-muted-foreground">Center</span>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel defaultSize={25} data-min-size="80" data-max-size="300">
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Right</span>
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  ),
+  ...src(`<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel defaultSize={25} data-min-size="80" data-max-size="300">Left</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel>Center</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={25} data-min-size="80" data-max-size="300">Right</ResizablePanel>
+</ResizablePanelGroup>`),
+};
+
+/** Handle without a visible grip; reports drag deltas via `onPanelResize` (showcase). */
+export const NoHandle: Story = {
+  name: 'Without Handle',
+  render: () => (
+    <div class="h-48 w-full max-w-2xl rounded-lg border border-border overflow-hidden">
+      <ResizablePanelGroup orientation="horizontal">
+        <ResizablePanel defaultSize={40}>
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Panel A</span>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle onPanelResize={fn()} />
+        <ResizablePanel>
+          <div class="flex h-full items-center justify-center p-4">
+            <span class="text-sm text-muted-foreground">Panel B</span>
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  ),
+  ...src(`<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel defaultSize={40}>Panel A</ResizablePanel>
+  <ResizableHandle onPanelResize={(delta) => console.log(delta)} />
+  <ResizablePanel>Panel B</ResizablePanel>
+</ResizablePanelGroup>`),
+};
+
+/**
+ * The `Resizable` convenience: pass `ResizablePanel` children and it
+ * auto-inserts a handle between each visible pair. A `locked` panel makes its
+ * neighbouring handle a static (non-draggable) divider; a `hidden` panel drops
+ * its divider entirely.
+ */
+export const ConvenienceGroup: Story = {
+  name: 'Resizable (convenience)',
+  render: () => (
+    <div class="h-48 w-full max-w-2xl rounded-lg border border-border overflow-hidden">
+      <Resizable orientation="horizontal" withHandle onChange={(sizes) => console.log('sizes', sizes)}>
+        <ResizablePanel defaultSize="240px" locked>
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Locked sidebar (240px)</span>
+          </div>
+        </ResizablePanel>
+        <ResizablePanel>
+          <div class="flex h-full items-center justify-center p-4">
+            <span class="text-sm text-muted-foreground">Chat</span>
+          </div>
+        </ResizablePanel>
+        <ResizablePanel defaultSize="30%" minSize="160px">
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">Preview</span>
+          </div>
+        </ResizablePanel>
+      </Resizable>
+    </div>
+  ),
+  ...src(`<Resizable orientation="horizontal" withHandle onChange={(sizes) => console.log(sizes)}>
+  <ResizablePanel defaultSize="240px" locked>Locked sidebar</ResizablePanel>
+  <ResizablePanel>Chat</ResizablePanel>
+  <ResizablePanel defaultSize="30%" minSize="160px">Preview</ResizablePanel>
+</Resizable>`),
+};
+
+/**
+ * Min/max + keyboard: focus the handle (Tab) and use ←/→ to nudge, Home/End to
+ * jump to the panel's min/max. Sizes accept px or %.
+ */
+export const MinMaxKeyboard: Story = {
+  name: 'Min/Max + Keyboard',
+  render: () => (
+    <div class="h-48 w-full max-w-2xl rounded-lg border border-border overflow-hidden">
+      <ResizablePanelGroup orientation="horizontal">
+        <ResizablePanel defaultSize="30%" minSize="120px" maxSize="50%">
+          <div class="flex h-full items-center justify-center bg-muted/30 p-4">
+            <span class="text-sm text-muted-foreground">min 120px · max 50%</span>
+          </div>
+        </ResizablePanel>
+        <ResizableHandle withHandle />
+        <ResizablePanel minSize="160px">
+          <div class="flex h-full items-center justify-center p-4">
+            <span class="text-sm text-muted-foreground">Content (min 160px)</span>
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  ),
+  ...src(`<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel defaultSize="30%" minSize="120px" maxSize="50%">Sidebar</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel minSize="160px">Content</ResizablePanel>
+</ResizablePanelGroup>`),
+};