@sovereignfs/ui 0.21.3 → 0.33.0

package/src/components/Sheet/Sheet.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
+import styles from './Sheet.module.css';
+
+export interface SheetProps {
+  /** Whether the sheet is shown. When false, nothing renders. */
+  open: boolean;
+  /** Called on Esc, or the built-in `OverlayHeader`'s close button. There is
+   *  no scrim to tap — a Sheet replaces the content area it fills, not a
+   *  layer floating above it (see the component doc comment). */
+  onClose: () => void;
+  /** Accessible name for the sheet. Defaults to `title` when omitted. */
+  'aria-label'?: string;
+  /** Renders a built-in `OverlayHeader` (title + close, optional back button
+   *  and trailing action). Omit when the content supplies its own header —
+   *  e.g. a form whose title doubles as an editable field. */
+  title?: string;
+  /** Forwarded to `OverlayHeader` — see its own `onBack` doc. Has no effect
+   *  without `title`. */
+  onBack?: () => void;
+  /** Forwarded to `OverlayHeader`'s trailing-action slot. Has no effect
+   *  without `title`. */
+  headerAction?: ReactNode;
+  /**
+   * Which edge the panel slides in from. Defaults to `'bottom'` (detail
+   * views, forms — content the user is reaching down into). `'top'` suits a
+   * short options/actions menu opened from a header button near the top of
+   * the screen, where sliding up from the bottom would travel past empty
+   * space before reaching content that visually belongs near the trigger.
+   */
+  slideFrom?: 'bottom' | 'top';
+  children: ReactNode;
+}
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+// Matches --sv-motion-duration-base (Sheet.module.css) — see Dialog.tsx's
+// identical constant for why this stays a plain JS number.
+const MOTION_DURATION_MS = 250;
+
+/**
+ * Sheet — a full-page overlay that replaces a plugin's content area between
+ * the shell's fixed header and footer (RFC 0013's mobile chrome stays visible
+ * and interactive around it), sliding in from an edge instead of centering
+ * like `Dialog`. Promoted from the tasks plugin's `MobileFullPageOverlay`
+ * (now the reference pattern for this component). Desktop has no equivalent
+ * presentation — a desktop layout shows the same content inline (columns,
+ * panes) instead of mounting a `Sheet` at all; this component is for the
+ * mobile case specifically.
+ *
+ * Unlike `Dialog`/`Drawer` there is no scrim: a Sheet visually *replaces* the
+ * region it covers rather than floating a layer above it, so there is no
+ * "outside" to tap-dismiss. Behaviour: Esc dismisses; focus moves into the
+ * panel on open and is restored on close; Tab is trapped within the panel;
+ * animated open/close via the same two-phase mount as `Dialog`/`Drawer`,
+ * respecting `prefers-reduced-motion`.
+ */
+export function Sheet({
+  open,
+  onClose,
+  'aria-label': ariaLabel,
+  title,
+  onBack,
+  headerAction,
+  slideFrom = 'bottom',
+  children,
+}: SheetProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+  const reducedMotion = usePrefersReducedMotion();
+  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+
+  useEffect(() => {
+    if (!mounted) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [mounted]);
+
+  useEffect(() => {
+    if (!mounted) return;
+    previouslyFocused.current = document.activeElement as HTMLElement | null;
+    const panel = panelRef.current;
+    const first = panel?.querySelector<HTMLElement>(FOCUSABLE);
+    (first ?? panel)?.focus();
+    return () => previouslyFocused.current?.focus();
+  }, [mounted]);
+
+  useEffect(() => {
+    if (!open) return;
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      const panel = panelRef.current;
+      if (!panel) return;
+      const focusable = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];
+      const first = focusable[0];
+      const last = focusable.at(-1);
+      if (!first || !last) {
+        e.preventDefault();
+        return;
+      }
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [open, onClose]);
+
+  if (!mounted) return null;
+
+  return (
+    <div
+      ref={panelRef}
+      role="dialog"
+      aria-modal="true"
+      aria-label={ariaLabel ?? title}
+      tabIndex={-1}
+      className={[
+        styles.panel,
+        slideFrom === 'top' ? styles.panelFromTop : '',
+        phase === 'open' ? styles.panelOpen : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {title && (
+        <OverlayHeader title={title} onClose={onClose} onBack={onBack} action={headerAction} />
+      )}
+      {/* Content is always the scroll container — with or without a header —
+          so a header's sibling stays fixed and any content-owned internal
+          sticky positioning (e.g. a form's own sub-header) resolves against
+          this same scrolling ancestor either way. */}
+      <div className={styles.content}>{children}</div>
+    </div>
+  );
+}

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

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Sheet } from '../Sheet';
+
+// Sheet's exit animation reads prefers-reduced-motion via matchMedia, which
+// jsdom does not implement — see Dialog.test.tsx's identical setup.
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+describe('Sheet', () => {
+  beforeEach(installMatchMedia);
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders nothing when closed', () => {
+    render(
+      <Sheet open={false} onClose={() => {}}>
+        Body
+      </Sheet>,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('renders the panel with its accessible name when open', () => {
+    render(
+      <Sheet open onClose={() => {}} aria-label="Task detail">
+        Body
+      </Sheet>,
+    );
+    const panel = screen.getByRole('dialog', { name: 'Task detail' });
+    expect(panel.getAttribute('aria-modal')).toBe('true');
+  });
+
+  it('falls back to title for the accessible name when aria-label is omitted', () => {
+    render(
+      <Sheet open onClose={() => {}} title="Edit list">
+        Body
+      </Sheet>,
+    );
+    expect(screen.getByRole('dialog', { name: 'Edit list' })).toBeTruthy();
+  });
+
+  it('does not render OverlayHeader when title is omitted (headerless escape hatch)', () => {
+    render(
+      <Sheet open onClose={() => {}} aria-label="Custom">
+        <button type="button">Own close button</button>
+      </Sheet>,
+    );
+    // Only the content's own button — no OverlayHeader close button.
+    expect(screen.getAllByRole('button')).toHaveLength(1);
+  });
+
+  it('renders OverlayHeader (title + close) when title is provided', () => {
+    const onClose = vi.fn();
+    render(
+      <Sheet open onClose={onClose} title="Edit list">
+        Body
+      </Sheet>,
+    );
+    expect(screen.getByText('Edit list')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('calls onClose on Escape', () => {
+    const onClose = vi.fn();
+    render(
+      <Sheet open onClose={onClose} aria-label="Panel">
+        Body
+      </Sheet>,
+    );
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('applies the top slide-from variant class', () => {
+    render(
+      <Sheet open onClose={() => {}} aria-label="Menu" slideFrom="top">
+        Body
+      </Sheet>,
+    );
+    expect(screen.getByRole('dialog').className).toMatch(/panelFromTop/);
+  });
+});

package/src/components/SplitPane/SplitPane.module.css

@@ -0,0 +1,85 @@
+.splitPane {
+  display: grid;
+  grid-template-columns:
+    minmax(0, var(--split-pane-primary-size, 50%)) 12px
+    minmax(0, calc(100% - var(--split-pane-primary-size, 50%)));
+  width: 100%;
+  min-height: 320px;
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  overflow: hidden;
+  background: var(--sv-color-surface);
+}
+
+.splitPane:not(:has(.handle)) {
+  grid-template-columns:
+    minmax(0, var(--split-pane-primary-size, 50%))
+    minmax(0, calc(100% - var(--split-pane-primary-size, 50%)));
+}
+
+.pane {
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+  background: var(--sv-color-surface);
+}
+
+.pane + .pane {
+  border-left: 1px solid var(--sv-color-border);
+}
+
+.handle {
+  position: relative;
+  width: 12px;
+  min-width: 12px;
+  padding: 0;
+  border: 0;
+  border-inline: 1px solid var(--sv-color-border);
+  cursor: col-resize;
+  background: var(--sv-color-surface-sunken);
+}
+
+.handle::before {
+  position: absolute;
+  inset-block: 50%;
+  inset-inline: 50%;
+  width: 2px;
+  height: 40px;
+  content: '';
+  background: var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-full);
+  transform: translate(-50%, -50%);
+}
+
+@media (hover: hover) {
+  .handle:hover {
+    background: var(--sv-color-accent-subtle);
+  }
+}
+
+.handle:focus-visible {
+  background: var(--sv-color-accent-subtle);
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+@media (max-width: 720px) {
+  .splitPane,
+  .splitPane:not(:has(.handle)) {
+    grid-template-columns: 1fr;
+    min-height: 0;
+  }
+
+  .handle {
+    display: none;
+  }
+
+  .pane {
+    min-height: 220px;
+  }
+
+  .pane + .pane {
+    border-top: 1px solid var(--sv-color-border);
+    border-left: 0;
+  }
+}

package/src/components/SplitPane/SplitPane.stories.tsx

@@ -0,0 +1,160 @@
+import type { ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { SplitPane } from './SplitPane';
+import { CodeTextarea } from '../CodeTextarea/CodeTextarea';
+import { StatusBadge } from '../StatusBadge/StatusBadge';
+
+const editorText = `# Release plan
+
+- Confirm copy
+- Preview page
+- Commit changes
+`;
+
+function PaneShell({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        minHeight: '100%',
+        flexDirection: 'column',
+        gap: 'var(--sv-space-3)',
+        padding: 'var(--sv-space-4)',
+        fontFamily: 'var(--sv-font-family)',
+      }}
+    >
+      <h3
+        style={{
+          margin: 0,
+          fontSize: 'var(--sv-font-size-sm)',
+          color: 'var(--sv-color-text-primary)',
+        }}
+      >
+        {title}
+      </h3>
+      {children}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Components/SplitPane',
+  component: SplitPane,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Responsive two-pane layout for editor/preview and list/detail workflows. Drag or use arrow keys on the separator.',
+      },
+    },
+  },
+  args: {
+    primary: <PaneShell title="Primary">Primary pane</PaneShell>,
+    secondary: <PaneShell title="Secondary">Secondary pane</PaneShell>,
+  },
+} satisfies Meta<typeof SplitPane>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <SplitPane
+      primary={
+        <PaneShell title="Editor">
+          <CodeTextarea aria-label="Markdown editor" defaultValue={editorText} />
+        </PaneShell>
+      }
+      secondary={
+        <PaneShell title="Preview">
+          <article style={{ lineHeight: 1.6, color: 'var(--sv-color-text-primary)' }}>
+            <h2 style={{ marginTop: 0 }}>Release plan</h2>
+            <ul>
+              <li>Confirm copy</li>
+              <li>Preview page</li>
+              <li>Commit changes</li>
+            </ul>
+          </article>
+        </PaneShell>
+      }
+    />
+  ),
+};
+
+export const FixedPanes: Story = {
+  render: () => (
+    <SplitPane
+      resizable={false}
+      defaultPrimarySize={38}
+      primary={
+        <PaneShell title="Files">
+          {['index.md', 'release-notes.md', 'about.md'].map((file) => (
+            <div
+              key={file}
+              style={{
+                display: 'flex',
+                justifyContent: 'space-between',
+                gap: 'var(--sv-space-3)',
+                padding: 'var(--sv-space-2) 0',
+                borderBottom: '1px solid var(--sv-color-border)',
+              }}
+            >
+              <span>{file}</span>
+              <StatusBadge status={file === 'release-notes.md' ? 'draft' : 'synced'} />
+            </div>
+          ))}
+        </PaneShell>
+      }
+      secondary={
+        <PaneShell title="Details">
+          <p style={{ margin: 0, color: 'var(--sv-color-text-muted)' }}>
+            Select a file to inspect frontmatter, sync state, and publish history.
+          </p>
+        </PaneShell>
+      }
+    />
+  ),
+};
+
+export const KeyboardResizable: Story = {
+  render: () => (
+    <SplitPane
+      defaultPrimarySize={45}
+      minPrimarySize={25}
+      maxPrimarySize={75}
+      resizeLabel="Resize editor and preview panes with arrow keys"
+      primary={<PaneShell title="Keyboard">Focus the separator and press arrow keys.</PaneShell>}
+      secondary={<PaneShell title="Preview">Shift+Arrow resizes in larger steps.</PaneShell>}
+    />
+  ),
+};
+
+export const LongContent: Story = {
+  render: () => (
+    <SplitPane
+      primary={
+        <PaneShell title="Long list">
+          {Array.from({ length: 28 }, (_, index) => (
+            <div key={index} style={{ paddingBlock: 'var(--sv-space-2)' }}>
+              Content item {index + 1}
+            </div>
+          ))}
+        </PaneShell>
+      }
+      secondary={<PaneShell title="Preview">Each pane scrolls independently.</PaneShell>}
+    />
+  ),
+};
+
+export const Mobile: Story = {
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+  },
+  render: () => (
+    <SplitPane
+      primary={<PaneShell title="Editor">This pane appears first on narrow screens.</PaneShell>}
+      secondary={<PaneShell title="Preview">The second pane stacks below it.</PaneShell>}
+    />
+  ),
+};

package/src/components/SplitPane/SplitPane.tsx

@@ -0,0 +1,149 @@
+'use client';
+
+import type {
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
+  ReactNode,
+} from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import styles from './SplitPane.module.css';
+
+export interface SplitPaneProps {
+  primary: ReactNode;
+  secondary: ReactNode;
+  defaultPrimarySize?: number;
+  minPrimarySize?: number;
+  maxPrimarySize?: number;
+  resizable?: boolean;
+  primaryLabel?: string;
+  secondaryLabel?: string;
+  resizeLabel?: string;
+  className?: string;
+}
+
+const clampSize = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);
+
+/**
+ * SplitPane — responsive two-pane layout for editor/preview and list/detail
+ * workflows. Desktop panes can be resized; narrow viewports fall back to a
+ * stable single-column stack.
+ */
+export function SplitPane({
+  primary,
+  secondary,
+  defaultPrimarySize = 50,
+  minPrimarySize = 30,
+  maxPrimarySize = 70,
+  resizable = true,
+  primaryLabel = 'Primary pane',
+  secondaryLabel = 'Secondary pane',
+  resizeLabel = 'Resize panes',
+  className,
+}: SplitPaneProps) {
+  const initialSize = clampSize(defaultPrimarySize, minPrimarySize, maxPrimarySize);
+  const [primarySize, setPrimarySize] = useState(initialSize);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const dragState = useRef<{ pointerId: number } | null>(null);
+
+  const updateFromClientX = useCallback(
+    (clientX: number) => {
+      const rect = containerRef.current?.getBoundingClientRect();
+      if (!rect || rect.width === 0) {
+        return;
+      }
+
+      const next = ((clientX - rect.left) / rect.width) * 100;
+      setPrimarySize(clampSize(next, minPrimarySize, maxPrimarySize));
+    },
+    [maxPrimarySize, minPrimarySize],
+  );
+
+  useEffect(() => {
+    const handlePointerMove = (event: globalThis.PointerEvent) => {
+      if (!dragState.current || event.pointerId !== dragState.current.pointerId) {
+        return;
+      }
+      updateFromClientX(event.clientX);
+    };
+
+    const stopDragging = (event: globalThis.PointerEvent) => {
+      if (!dragState.current || event.pointerId !== dragState.current.pointerId) {
+        return;
+      }
+      dragState.current = null;
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+    };
+
+    window.addEventListener('pointermove', handlePointerMove);
+    window.addEventListener('pointerup', stopDragging);
+    window.addEventListener('pointercancel', stopDragging);
+
+    return () => {
+      window.removeEventListener('pointermove', handlePointerMove);
+      window.removeEventListener('pointerup', stopDragging);
+      window.removeEventListener('pointercancel', stopDragging);
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+    };
+  }, [updateFromClientX]);
+
+  const startDragging = (event: ReactPointerEvent<HTMLButtonElement>) => {
+    if (!resizable) {
+      return;
+    }
+    dragState.current = { pointerId: event.pointerId };
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+    event.currentTarget.setPointerCapture(event.pointerId);
+  };
+
+  const resizeWithKeyboard = (event: ReactKeyboardEvent<HTMLButtonElement>) => {
+    const step = event.shiftKey ? 10 : 5;
+    if (event.key === 'ArrowLeft') {
+      event.preventDefault();
+      setPrimarySize((size) => clampSize(size - step, minPrimarySize, maxPrimarySize));
+    }
+    if (event.key === 'ArrowRight') {
+      event.preventDefault();
+      setPrimarySize((size) => clampSize(size + step, minPrimarySize, maxPrimarySize));
+    }
+    if (event.key === 'Home') {
+      event.preventDefault();
+      setPrimarySize(minPrimarySize);
+    }
+    if (event.key === 'End') {
+      event.preventDefault();
+      setPrimarySize(maxPrimarySize);
+    }
+  };
+
+  const style = {
+    '--split-pane-primary-size': `${primarySize}%`,
+  } as CSSProperties;
+
+  return (
+    <div
+      ref={containerRef}
+      className={[styles.splitPane, className].filter(Boolean).join(' ')}
+      style={style}
+    >
+      <section className={styles.pane} aria-label={primaryLabel}>
+        {primary}
+      </section>
+      {resizable && (
+        <button
+          type="button"
+          className={styles.handle}
+          aria-label={`${resizeLabel}, primary pane ${Math.round(primarySize)} percent`}
+          onPointerDown={startDragging}
+          onKeyDown={resizeWithKeyboard}
+        />
+      )}
+      <section className={styles.pane} aria-label={secondaryLabel}>
+        {secondary}
+      </section>
+    </div>
+  );
+}

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

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { SplitPane } from '../SplitPane';
+
+afterEach(cleanup);
+
+describe('SplitPane', () => {
+  it('renders labeled panes and a resize button', () => {
+    render(
+      <SplitPane
+        primary={<p>Editor</p>}
+        secondary={<p>Preview</p>}
+        primaryLabel="Editor pane"
+        secondaryLabel="Preview pane"
+      />,
+    );
+
+    expect(screen.getByRole('region', { name: 'Editor pane' })).toBeDefined();
+    expect(screen.getByRole('region', { name: 'Preview pane' })).toBeDefined();
+    expect(screen.getByRole('button', { name: /Resize panes/ })).toBeDefined();
+  });
+
+  it('omits the resize button when not resizable', () => {
+    render(<SplitPane primary={<p>List</p>} secondary={<p>Detail</p>} resizable={false} />);
+
+    expect(screen.queryByRole('button', { name: /Resize panes/ })).toBeNull();
+  });
+
+  it('resizes with keyboard controls', () => {
+    render(
+      <SplitPane
+        primary={<p>Editor</p>}
+        secondary={<p>Preview</p>}
+        defaultPrimarySize={50}
+        minPrimarySize={30}
+        maxPrimarySize={70}
+      />,
+    );
+
+    const separator = screen.getByRole('button', { name: /Resize panes/ });
+    fireEvent.keyDown(separator, { key: 'ArrowRight' });
+    expect(separator.getAttribute('aria-label')).toContain('55 percent');
+
+    fireEvent.keyDown(separator, { key: 'Home' });
+    expect(separator.getAttribute('aria-label')).toContain('30 percent');
+
+    fireEvent.keyDown(separator, { key: 'End' });
+    expect(separator.getAttribute('aria-label')).toContain('70 percent');
+  });
+});