@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/SwipeStack/__tests__/SwipeStack.test.tsx

@@ -0,0 +1,169 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { SwipeStack } from '../SwipeStack';
+import { SwipeStackCard } from '../SwipeStackCard';
+import { SWIPE_STACK_TRANSITION_MS } from '../../../hooks/useSwipeStack';
+
+// jsdom doesn't implement pointer capture — stub it as a no-op so
+// `e.currentTarget.setPointerCapture(...)` doesn't throw.
+beforeEach(() => {
+  if (!HTMLElement.prototype.setPointerCapture) {
+    HTMLElement.prototype.setPointerCapture = vi.fn();
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+});
+
+function pointer(x: number, y: number) {
+  return { clientX: x, clientY: y, pointerId: 1 };
+}
+
+function renderStack(onSwipe = vi.fn()) {
+  const utils = render(
+    <SwipeStack
+      aria-label="Today's agenda"
+      directions={{
+        up: { label: 'Done', icon: 'check' },
+        down: { label: 'Defer', icon: 'history' },
+      }}
+      onSwipe={onSwipe}
+    >
+      <SwipeStackCard cardId="a">Card A</SwipeStackCard>
+      <SwipeStackCard cardId="b">Card B</SwipeStackCard>
+      <SwipeStackCard cardId="c">Card C</SwipeStackCard>
+    </SwipeStack>,
+  );
+  return { ...utils, onSwipe };
+}
+
+describe('SwipeStack', () => {
+  it('renders the topmost card', () => {
+    const { getByText, queryByText } = renderStack();
+    expect(getByText('Card A')).toBeDefined();
+    expect(queryByText('Card C')).toBeNull();
+  });
+
+  it('labels the swipeable region', () => {
+    const { getByRole } = renderStack();
+    expect(getByRole('region', { name: "Today's agenda" })).toBeDefined();
+  });
+
+  it('only renders a fallback button for configured directions', () => {
+    const { getByRole, queryByRole } = renderStack();
+    expect(getByRole('button', { name: 'Done' })).toBeDefined();
+    expect(getByRole('button', { name: 'Defer' })).toBeDefined();
+    expect(queryByRole('button', { name: 'Skip' })).toBeNull();
+  });
+
+  it('calls onSwipe with the direction and cardId when a drag crosses threshold', () => {
+    const { getByText, onSwipe } = renderStack();
+    const card = getByText('Card A');
+    fireEvent.pointerDown(card, pointer(0, 0));
+    fireEvent.pointerMove(card, pointer(0, -200));
+    fireEvent.pointerUp(card, pointer(0, -200));
+    expect(onSwipe).toHaveBeenCalledWith('up', 'a');
+  });
+
+  it('does not call onSwipe when dragging toward a direction that is not configured', () => {
+    const { getByText, onSwipe } = renderStack();
+    const card = getByText('Card A');
+    fireEvent.pointerDown(card, pointer(0, 0));
+    fireEvent.pointerMove(card, pointer(200, 0));
+    fireEvent.pointerUp(card, pointer(200, 0));
+    expect(onSwipe).not.toHaveBeenCalled();
+  });
+
+  it('calls onSwipe when a fallback button is clicked, without any drag', () => {
+    const { getByRole, onSwipe } = renderStack();
+    fireEvent.click(getByRole('button', { name: 'Defer' }));
+    expect(onSwipe).toHaveBeenCalledWith('down', 'a');
+  });
+
+  it('advances to the next card only after the exit animation completes', () => {
+    vi.useFakeTimers();
+    const { getByRole, getByText, queryByText } = renderStack();
+    expect(getByText('Card A')).toBeDefined();
+
+    fireEvent.click(getByRole('button', { name: 'Done' }));
+    // Still mid-animation — the committed card stays put (so the fling-out
+    // it already started doesn't get cut off by a remount) and is still the
+    // one the fallback buttons act on; Card B is already visible as the
+    // peek behind it, but only decoratively (aria-hidden, not interactive).
+    expect(getByText('Card A')).toBeDefined();
+    const peekedB = getByText('Card B');
+    expect(peekedB.closest('[aria-hidden="true"]')).not.toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(SWIPE_STACK_TRANSITION_MS);
+    });
+    expect(queryByText('Card A')).toBeNull();
+    expect(getByText('Card B').closest('[aria-hidden="true"]')).toBeNull();
+  });
+
+  it('never shows a dismissed card again, even if the caller still passes it as a child', () => {
+    vi.useFakeTimers();
+    const onSwipe = vi.fn();
+    const directions = { up: { label: 'Done', icon: 'check' as const } };
+    const { getByRole, getByText, queryByText, rerender } = render(
+      <SwipeStack aria-label="Today's agenda" directions={directions} onSwipe={onSwipe}>
+        <SwipeStackCard cardId="a">Card A</SwipeStackCard>
+        <SwipeStackCard cardId="b">Card B</SwipeStackCard>
+      </SwipeStack>,
+    );
+    fireEvent.click(getByRole('button', { name: 'Done' }));
+    act(() => {
+      vi.advanceTimersByTime(SWIPE_STACK_TRANSITION_MS);
+    });
+    expect(getByText('Card B')).toBeDefined();
+
+    // Re-render with the exact same children — a caller slow to remove the
+    // dismissed card from its own data. SwipeStack must not show it again.
+    rerender(
+      <SwipeStack aria-label="Today's agenda" directions={directions} onSwipe={onSwipe}>
+        <SwipeStackCard cardId="a">Card A</SwipeStackCard>
+        <SwipeStackCard cardId="b">Card B</SwipeStackCard>
+      </SwipeStack>,
+    );
+    expect(queryByText('Card A')).toBeNull();
+    expect(getByText('Card B')).toBeDefined();
+  });
+});
+
+describe('SwipeStack dev-mode child-type guard', () => {
+  function renderWithStrayChild() {
+    return render(
+      <SwipeStack aria-label="Today's agenda" directions={{}} onSwipe={() => {}}>
+        <SwipeStackCard cardId="a">Card A</SwipeStackCard>
+        {/* stray non-SwipeStackCard child */}
+        <div>oops</div>
+      </SwipeStack>,
+    );
+  }
+
+  it('warns via console.error in development, mentioning the offending child', () => {
+    const originalEnv = process.env.NODE_ENV;
+    vi.stubEnv('NODE_ENV', 'development');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => renderWithStrayChild()).not.toThrow();
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('<div>'));
+    vi.stubEnv('NODE_ENV', originalEnv ?? 'test');
+  });
+
+  it('does not call console.error in production', () => {
+    const originalEnv = process.env.NODE_ENV;
+    vi.stubEnv('NODE_ENV', 'production');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => renderWithStrayChild()).not.toThrow();
+
+    expect(errorSpy).not.toHaveBeenCalled();
+    vi.stubEnv('NODE_ENV', originalEnv ?? 'test');
+  });
+});

package/src/components/SystemBanner/SystemBanner.module.css

@@ -3,6 +3,16 @@
   top: 0;
   /* Sits above sidebar rail (z-index ~10) but below dialogs/overlays (z-index 100) */
   z-index: 50;
+  /* WebKit momentum-scroll re-tiling quirk: a position: sticky element with
+     no compositing layer of its own can go stale/blank for a stretch of
+     frames during a fast scroll on iOS Safari instead of repainting at its
+     stuck position. translateZ(0) promotes it to its own layer, rasterized
+     independently of the scroller's tile grid. See
+     docs/architecture-rules.md — found and fixed across three sticky
+     elements in sovereign-tasks, applied here proactively since this
+     component is exactly the same pattern (sticky, inside scrolling
+     content). */
+  transform: translateZ(0);
   display: flex;
   align-items: center;
   justify-content: center;

package/src/components/Table/Table.module.css

@@ -20,11 +20,11 @@
 }
 
 .head .row {
-  border-bottom: 1px solid var(--sv-color-border-strong);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border-strong);
 }
 
 .body .row {
-  border-bottom: 1px solid var(--sv-color-border);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
 }
 
 .body .row:last-child {

package/src/components/Tabs/Tabs.module.css

@@ -1,6 +1,6 @@
 .tablist {
   display: flex;
-  border-bottom: 1px solid var(--sv-color-border);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
   /* Horizontal scroll on mobile — scrollbar hidden for clean appearance */
   overflow-x: auto;
   scrollbar-width: none;

package/src/components/TagInput/TagInput.module.css

@@ -15,7 +15,7 @@
   padding: 5px var(--sv-space-2);
   color: var(--sv-color-text-primary);
   background: var(--sv-color-surface);
-  border: 1px solid var(--sv-color-border-strong);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border-strong);
   border-radius: var(--sv-radius-md);
   transition:
     border-color 0.15s ease,
@@ -50,7 +50,7 @@
   padding-inline: var(--sv-space-2) 2px;
   color: var(--sv-color-text-primary);
   background: var(--sv-color-surface-sunken);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-full);
   font-family: var(--sv-font-family);
   font-size: var(--sv-font-size-xs);

package/src/components/Textarea/Textarea.module.css

@@ -7,7 +7,7 @@
   line-height: 1.5;
   color: var(--sv-color-text-primary);
   background-color: var(--sv-color-surface);
-  border: 1px solid var(--sv-color-border-strong);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border-strong);
   border-radius: var(--sv-radius-md);
   resize: vertical;
   transition:
@@ -37,3 +37,11 @@
   cursor: not-allowed;
   resize: none;
 }
+
+/* Height is driven by the `autoGrow` layout effect (Textarea.tsx), not the
+   user — resize: none avoids a drag handle that would fight it; overflow
+   hidden avoids a scrollbar flashing on between the old and new height. */
+.textareaAutoGrow {
+  overflow: hidden;
+  resize: none;
+}

package/src/components/Textarea/Textarea.tsx

@@ -1,15 +1,38 @@
+'use client';
+
+import { useLayoutEffect, useRef } from 'react';
 import type { TextareaHTMLAttributes } from 'react';
 import styles from './Textarea.module.css';
 
-export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  /** Grows the field's own height to fit its content as it's typed, instead
+   *  of scrolling internally or leaving the user to drag-resize — e.g. an
+   *  editable title that should read as a heading, not a fixed-size form
+   *  field. Disables manual resize (`resize: none`) since a height driven by
+   *  content and a user-draggable height would fight each other. `rows` is
+   *  still honoured as the starting/minimum height. */
+  autoGrow?: boolean;
+}
 
 /**
  * Textarea — the primitive multi-line text field. Presentational and
- * RSC-safe: it forwards all native textarea props to the underlying
+ * RSC-safe unless `autoGrow` is used (client-only, needs a layout
+ * measurement). Forwards all native textarea props to the underlying
  * `<textarea>`. Styling references `--sv-*` tokens via CSS Modules; there
  * are no hardcoded values.
  */
-export function Textarea({ className, rows = 4, ...rest }: TextareaProps) {
-  const classes = [styles.textarea, className].filter(Boolean).join(' ');
-  return <textarea rows={rows} className={classes} {...rest} />;
+export function Textarea({ className, rows = 4, autoGrow = false, ...rest }: TextareaProps) {
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!autoGrow || !el) return;
+    el.style.height = 'auto';
+    el.style.height = `${el.scrollHeight}px`;
+  }, [autoGrow, rest.value, rest.defaultValue]);
+
+  const classes = [styles.textarea, autoGrow ? styles.textareaAutoGrow : '', className]
+    .filter(Boolean)
+    .join(' ');
+  return <textarea ref={ref} rows={rows} className={classes} {...rest} />;
 }

package/src/components/Textarea/__tests__/Textarea.test.tsx

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, render, screen } from '@testing-library/react';
 import { Textarea } from '../Textarea';
 
@@ -26,4 +26,26 @@ describe('Textarea', () => {
     render(<Textarea aria-label="field" disabled />);
     expect((screen.getByLabelText('field') as HTMLTextAreaElement).disabled).toBe(true);
   });
+
+  it('does not apply the auto-grow class by default', () => {
+    render(<Textarea aria-label="field" />);
+    expect(screen.getByLabelText('field').className).not.toMatch(/textareaAutoGrow/);
+  });
+
+  it('applies the auto-grow class and sizes height to scrollHeight when autoGrow is set', () => {
+    // jsdom has no real layout engine — scrollHeight is always 0, so it must
+    // be stubbed on the prototype before mount (same pattern as
+    // MessageScroller's own tests) for useLayoutEffect's synchronous
+    // on-mount measurement to read anything meaningful. This only proves the
+    // effect reads scrollHeight and writes it back as `style.height`, not
+    // that real pixel math is correct.
+    const scrollHeightSpy = vi
+      .spyOn(HTMLTextAreaElement.prototype, 'scrollHeight', 'get')
+      .mockReturnValue(88);
+    render(<Textarea aria-label="field" autoGrow defaultValue="hello" />);
+    const el = screen.getByLabelText('field') as HTMLTextAreaElement;
+    expect(el.className).toMatch(/textareaAutoGrow/);
+    expect(el.style.height).toBe('88px');
+    scrollHeightSpy.mockRestore();
+  });
 });

package/src/components/ThreeColumnLayout/ThreeColumnLayout.module.css

@@ -0,0 +1,35 @@
+.shell {
+  display: flex;
+  height: 100%;
+  overflow: hidden;
+}
+
+.sidebar {
+  flex-shrink: 0;
+  overflow-y: auto;
+  background: var(--sv-color-surface-raised);
+  border-right: var(--sv-border-width-hairline) solid var(--sv-color-border);
+}
+
+/*
+ * `display: none`, not `width: 0` — a zero-width flex item still paints its
+ * own `border-right` as a 1px hairline down the edge of the viewport, which
+ * reads as a stray line rather than a hidden column.
+ */
+.sidebarHidden {
+  display: none;
+}
+
+.main {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  background: var(--sv-color-surface);
+}
+
+.detail {
+  flex-shrink: 0;
+  overflow-y: auto;
+  background: var(--sv-color-surface-raised);
+  border-left: var(--sv-border-width-hairline) solid var(--sv-color-border);
+}

package/src/components/ThreeColumnLayout/ThreeColumnLayout.stories.tsx

@@ -0,0 +1,152 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { ThreeColumnLayout } from './ThreeColumnLayout';
+
+function Block({
+  title,
+  children,
+  padded = true,
+}: {
+  title: string;
+  children?: React.ReactNode;
+  padded?: boolean;
+}) {
+  return (
+    <div
+      style={{
+        height: '100%',
+        padding: padded ? 'var(--sv-space-4)' : 0,
+        fontFamily: 'var(--sv-font-family)',
+      }}
+    >
+      <h3
+        style={{
+          margin: '0 0 var(--sv-space-2)',
+          fontSize: 'var(--sv-font-size-sm)',
+          color: 'var(--sv-color-text-primary)',
+        }}
+      >
+        {title}
+      </h3>
+      {children}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Components/ThreeColumnLayout',
+  component: ThreeColumnLayout,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Sidebar + main + optional detail column, for the common "list app" shape. Purely positional: pass 2 children for sidebar+main, or 3 for sidebar+main+detail. The layout has no awareness of what is inside each slot and no responsive behavior of its own.',
+      },
+    },
+  },
+  args: {
+    children: [<Block key="sidebar" title="Sidebar" />, <Block key="main" title="Main" />],
+  },
+} satisfies Meta<typeof ThreeColumnLayout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The canonical two-child usage — sidebar + main, no detail column. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ height: '480px' }}>
+      <ThreeColumnLayout>
+        <Block title="Sidebar">
+          <ul style={{ margin: 0, paddingLeft: 'var(--sv-space-4)' }}>
+            <li>Groceries</li>
+            <li>Work</li>
+            <li>Personal</li>
+          </ul>
+        </Block>
+        <Block title="Main">No item selected — main fills the full remaining width.</Block>
+      </ThreeColumnLayout>
+    </div>
+  ),
+};
+
+export const ThreeColumns: Story = {
+  render: () => (
+    <div style={{ height: '480px' }}>
+      <ThreeColumnLayout>
+        <Block title="Sidebar">
+          <ul style={{ margin: 0, paddingLeft: 'var(--sv-space-4)' }}>
+            <li>Groceries</li>
+            <li>Work</li>
+            <li>Personal</li>
+          </ul>
+        </Block>
+        <Block title="Main">
+          <ul style={{ margin: 0, paddingLeft: 'var(--sv-space-4)' }}>
+            <li>Buy milk</li>
+            <li>Buy eggs</li>
+          </ul>
+        </Block>
+        <Block title="Detail">Editing "Buy milk" — notes, due date, etc.</Block>
+      </ThreeColumnLayout>
+    </div>
+  ),
+};
+
+export const CustomWidths: Story = {
+  render: () => (
+    <div style={{ height: '480px' }}>
+      <ThreeColumnLayout sidebarWidth={200} detailWidth={440}>
+        <Block title="Sidebar (200px)">Narrower nav column.</Block>
+        <Block title="Main">Fills whatever space is left.</Block>
+        <Block title="Detail (440px)">Wider detail column for a richer editor.</Block>
+      </ThreeColumnLayout>
+    </div>
+  ),
+};
+
+/** Demonstrates the intended usage: the detail column appears only once
+ *  something is selected, by conditionally including the third child. */
+export const ConditionalDetail: Story = {
+  render: function Render() {
+    const [selectedId, setSelectedId] = useState<string | null>(null);
+    const items = ['Buy milk', 'Buy eggs', 'Call plumber'];
+
+    return (
+      <div style={{ height: '480px' }}>
+        <ThreeColumnLayout>
+          <Block title="Sidebar">Lists</Block>
+          <Block title="Main" padded={false}>
+            <div style={{ padding: 'var(--sv-space-4)' }}>
+              {items.map((item) => (
+                <button
+                  key={item}
+                  type="button"
+                  onClick={() => setSelectedId(item)}
+                  style={{
+                    display: 'block',
+                    width: '100%',
+                    textAlign: 'left',
+                    padding: 'var(--sv-space-2)',
+                    marginBottom: 'var(--sv-space-1)',
+                    background:
+                      selectedId === item ? 'var(--sv-color-accent-subtle)' : 'transparent',
+                    border: 'none',
+                    borderRadius: 'var(--sv-radius-sm)',
+                    cursor: 'pointer',
+                    font: 'inherit',
+                    color: 'var(--sv-color-text-primary)',
+                  }}
+                >
+                  {item}
+                </button>
+              ))}
+            </div>
+          </Block>
+          {selectedId && <Block title="Detail">Editing "{selectedId}"</Block>}
+        </ThreeColumnLayout>
+      </div>
+    );
+  },
+};

package/src/components/ThreeColumnLayout/ThreeColumnLayout.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { Children } from 'react';
+import type { ReactNode } from 'react';
+import styles from './ThreeColumnLayout.module.css';
+
+export interface ThreeColumnLayoutProps {
+  /**
+   * Exactly 2 (sidebar, main) or 3 (sidebar, main, detail) elements. Omit
+   * the third child entirely to render two columns — e.g.
+   * `{selected && <Detail />}` — React.Children.toArray drops falsy
+   * children, so no separate `detail` prop is needed to make that
+   * conditional.
+   */
+  children: ReactNode;
+  /** px. Fixed width of the first (leftmost) column. Default 280. */
+  sidebarWidth?: number;
+  /** px. Fixed width of the third column, when present. Default 360. */
+  detailWidth?: number;
+  /**
+   * Hides the sidebar column entirely — no width, no border, no layout box
+   * — while keeping it mounted and every sibling in its own stable position.
+   *
+   * Prefer this over conditionally omitting the sidebar child, or swapping
+   * to a different wrapper when collapsed. Omitting it shifts `main` into
+   * the sidebar slot, and swapping the surrounding element type unmounts
+   * `main`'s entire subtree — silently discarding its React state (a live
+   * stream, unsent composer text, an in-memory-only conversation) on every
+   * collapse toggle. Found live in Warden, whose chat column lost all of
+   * that each time the sidebar was shown or hidden.
+   */
+  sidebarHidden?: boolean;
+  className?: string;
+}
+
+/**
+ * ThreeColumnLayout — sidebar + main + optional detail column, for the
+ * common "list app" shape (a list sidebar, a primary content list, and a
+ * detail pane that only takes up space once something is selected).
+ *
+ * Purely positional and structural — it has no awareness of what's inside
+ * each slot (no injected landmarks/labels; those belong to the children
+ * themselves) and no responsive behavior of its own. Collapsing further at
+ * narrow desktop/tablet widths (e.g. swapping the detail column for an
+ * overlay) is the consuming plugin's decision; below the mobile breakpoint,
+ * compose with ResponsiveSurface to fork to a different tree entirely.
+ */
+export function ThreeColumnLayout({
+  children,
+  sidebarWidth = 280,
+  detailWidth = 360,
+  sidebarHidden = false,
+  className,
+}: ThreeColumnLayoutProps) {
+  const items = Children.toArray(children);
+
+  if (process.env.NODE_ENV !== 'production' && (items.length < 2 || items.length > 3)) {
+    console.warn(
+      `[ThreeColumnLayout] Expects 2 or 3 children (sidebar, main, optional detail); received ${items.length}.`,
+    );
+  }
+
+  const [sidebar, main, detail] = items;
+
+  return (
+    <div className={[styles.shell, className].filter(Boolean).join(' ')}>
+      {/* `hidden` (not just the class) so the column leaves the
+          accessibility tree and the tab order too, rather than staying
+          reachable by keyboard while invisible. */}
+      <div
+        className={[styles.sidebar, sidebarHidden && styles.sidebarHidden]
+          .filter(Boolean)
+          .join(' ')}
+        style={sidebarHidden ? undefined : { width: sidebarWidth }}
+        hidden={sidebarHidden}
+      >
+        {sidebar}
+      </div>
+      <div className={styles.main}>{main}</div>
+      {detail && (
+        <div className={styles.detail} style={{ width: detailWidth }}>
+          {detail}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/ThreeColumnLayout/__tests__/ThreeColumnLayout.test.tsx

@@ -0,0 +1,78 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { ThreeColumnLayout } from '../ThreeColumnLayout';
+
+afterEach(cleanup);
+
+describe('ThreeColumnLayout', () => {
+  it('renders two columns and no detail column when only sidebar + main are given', () => {
+    render(
+      <ThreeColumnLayout>
+        <nav>Sidebar</nav>
+        <main>Main</main>
+      </ThreeColumnLayout>,
+    );
+
+    expect(screen.getByText('Sidebar')).toBeDefined();
+    expect(screen.getByText('Main')).toBeDefined();
+  });
+
+  it('renders the detail column when a third child is given', () => {
+    render(
+      <ThreeColumnLayout>
+        <nav>Sidebar</nav>
+        <main>Main</main>
+        <aside>Detail</aside>
+      </ThreeColumnLayout>,
+    );
+
+    expect(screen.getByText('Detail')).toBeDefined();
+  });
+
+  it('omits the detail column when the third child is conditionally falsy', () => {
+    const selected = false;
+    render(
+      <ThreeColumnLayout>
+        <nav>Sidebar</nav>
+        <main>Main</main>
+        {selected && <aside>Detail</aside>}
+      </ThreeColumnLayout>,
+    );
+
+    expect(screen.queryByText('Detail')).toBeNull();
+  });
+
+  it('applies sidebarWidth and detailWidth as inline widths', () => {
+    render(
+      <ThreeColumnLayout sidebarWidth={240} detailWidth={320}>
+        <nav>Sidebar</nav>
+        <main>Main</main>
+        <aside>Detail</aside>
+      </ThreeColumnLayout>,
+    );
+
+    expect(screen.getByText('Sidebar').parentElement?.style.width).toBe('240px');
+    expect(screen.getByText('Detail').parentElement?.style.width).toBe('320px');
+  });
+
+  it('warns in development when given fewer than 2 or more than 3 children', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    render(<ThreeColumnLayout>{[<main key="only">Only</main>]}</ThreeColumnLayout>);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('received 1'));
+
+    warn.mockClear();
+    render(
+      <ThreeColumnLayout>
+        <nav>A</nav>
+        <main>B</main>
+        <aside>C</aside>
+        <aside>D</aside>
+      </ThreeColumnLayout>,
+    );
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('received 4'));
+
+    warn.mockRestore();
+  });
+});