@appinternalleads/ui 0.2.0

package/src/ds/blockDisplay.tsx

@@ -0,0 +1,493 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import {
+  Box, Icon, MotionView, Pressable, Scroll, Text, useSwap, useTick, useTween,
+} from '../core';
+import { blockRadii, useDs, type Status } from '../tokens';
+import { MetaChip } from './blocks';
+
+/**
+ * **Solarium Building Blocks — display.** S2 Header meta · D2 Dot · D3 Progress bar · D5 Avatar
+ * group · D7 Check item · D8 Code block · D10 Media slot. (D1, D6, D9 are in `blocks.tsx`; D4 Stat
+ * is `StatCard`/`StatTile`.) Colour reads `useDs()`; nothing here names a hex.
+ */
+
+/* ── S2 · Header meta ────────────────────────────────────────────────────── */
+
+/**
+ * **Count, chip or timestamp, at meta size — tabular, never wraps.** A string is drawn as meta
+ * text; anything else (a `MetaChip`) is placed as-is. `BlockCard`'s `meta` slot renders through this.
+ */
+export function HeaderMeta({ children }: { children: ReactNode }) {
+  if (typeof children !== 'string') return <Box style={{ flexShrink: 0 }}>{children}</Box>;
+  return (
+    <Text variant="caption" color="textSecondary" numeric numberOfLines={1} style={{ fontSize: 12, flexShrink: 0 }}>
+      {children}
+    </Text>
+  );
+}
+
+/* ── M5 · Tick number ─────────────────────────────────────────────────────── */
+
+/**
+ * **A number that changes by cross-fading — M5 (Solarium 0.2.0).** The old value fades out while the
+ * new one fades in, both in the same cell, at `--motion-state`; nothing travels (the Building Blocks
+ * handoff's ±100% slide was retired by 0.2.0). Reduced motion: it simply changes. Only the current
+ * value is in the accessibility tree — the leaving layer is `aria-hidden`.
+ */
+export function TickNumber({
+  value, format = n => n.toLocaleString('en-US'), fontSize = 30, label, tone,
+}: {
+  value: number;
+  format?: (n: number) => string;
+  fontSize?: number;
+  /** What the number counts, for a screen reader: "API calls". */
+  label?: string;
+  /** Ink. Default the primary text colour. */
+  tone?: 'default' | 'apricot';
+}) {
+  const { colors } = useDs();
+  const { previous, progress } = useTick(value);
+  const style = {
+    fontSize, lineHeight: Math.round(fontSize * 1.2), fontWeight: '600' as const,
+    color: tone === 'apricot' ? colors.status.needsUser : colors.textPrimary,
+  };
+  return (
+    <Box style={{ alignSelf: 'flex-start' }} aria-label={label ? `${label}: ${format(value)}` : undefined} role={label ? 'img' : undefined}>
+      <MotionView style={{ opacity: progress }}>
+        <Text numeric style={style}>{format(value)}</Text>
+      </MotionView>
+      {previous !== null ? (
+        <MotionView aria-hidden style={{ position: 'absolute', left: 0, top: 0, opacity: progress.interpolate({ inputRange: [0, 1], outputRange: [1, 0] }) }}>
+          <Text numeric style={style}>{format(previous)}</Text>
+        </MotionView>
+      ) : null}
+    </Box>
+  );
+}
+
+/* ── M11 · Skeleton ──────────────────────────────────────────────────────── */
+
+/**
+ * **A skeleton pill** — `--line-soft`, no shimmer. Solarium 0.2.0's M11: *"follows existing
+ * Skeleton; no added shimmer"* — the bars inside a white shell already say "loading", and a moving
+ * band is exactly the kind of decoration 0.2.0 removed.
+ */
+export function SkeletonBar({ width = '100%', height = 14 }: { width?: `${number}%` | number; height?: number }) {
+  const { colors } = useDs();
+  return <Box height={height} radius="pill" width={width} style={{ backgroundColor: colors.band }} />;
+}
+
+/* ── D2 · Dot ────────────────────────────────────────────────────────────── */
+
+export type DotTone = Status | 'unread' | 'bullet';
+
+/**
+ * **Status, unread, bullet — always paired with a label.** The label is required by the type:
+ * a dot on its own is colour carrying meaning, which the handoff's own rule forbids.
+ */
+export function Dot({ tone, label, size = 8 }: { tone: DotTone; label: string; size?: number }) {
+  const { colors } = useDs();
+  const fill = tone === 'unread' ? colors.accentFill
+    : tone === 'bullet' ? colors.textTertiary
+    : colors.status[tone];
+  return (
+    <Box row align="center" gap="s2">
+      <Box width={size} height={size} radius="pill" style={{ backgroundColor: fill }} />
+      <Text variant="caption" color="textPrimary">{label}</Text>
+    </Box>
+  );
+}
+
+/* ── D3 · Progress bar ───────────────────────────────────────────────────── */
+
+/** At or past this fraction the bar turns apricot and says so in words. */
+export const NEAR_LIMIT = 0.8;
+
+/**
+ * The fill's meaning. `limit` (default) is the Building Blocks bar: mint, apricot at `NEAR_LIMIT` with
+ * copy. The rest are the onboarding handoff's fixed tones (B5): `accent` — a task in flight (upload,
+ * import; coral, 6px); `neutral` — a share of a whole (muted ink, 4px); `ink` / `success` /
+ * `attention` — a total under / exactly at / over its budget. Every tone keeps its words in
+ * `aria-valuetext`: colour never carries the state alone.
+ */
+export type ProgressTone = 'limit' | 'accent' | 'neutral' | 'ink' | 'success' | 'attention';
+
+const TONE_HEIGHT: Record<ProgressTone, number> = { limit: 8, accent: 6, neutral: 4, ink: 8, success: 8, attention: 8 };
+
+/**
+ * **A track and a fill — D3.** The fill tweens at `--motion-state` (M6); under reduced motion it
+ * jumps. `bare` drops the label row (the caller draws its own text beside it) but keeps the
+ * `progressbar` role and its name.
+ *
+ * The handoff says "<50% mint" and "≥80% apricot" and names nothing between; `limit` keeps mint up
+ * to the limit rather than inventing a third band (HANDOFF §6).
+ */
+export function ProgressBar({
+  label, value, max = 100, format, tone = 'limit', height, bare = false, track = 'band',
+}: {
+  label: string;
+  value: number;
+  max?: number;
+  /** The value in words. Default `n%`. */
+  format?: (value: number, max: number) => string;
+  tone?: ProgressTone;
+  /** Track height. Default by tone: 8, or 6 (`accent`), or 4 (`neutral`). */
+  height?: number;
+  /** No label row — the caller shows the figures itself. */
+  bare?: boolean;
+  /** `surface` puts the track in white — for a bar inside a well. */
+  track?: 'band' | 'surface';
+}) {
+  const { colors } = useDs();
+  const fraction = max > 0 ? Math.min(1, Math.max(0, value / max)) : 0;
+  const near = tone === 'limit' && fraction >= NEAR_LIMIT;
+  const base = format ? format(value, max) : `${Math.round(fraction * 100)}%`;
+  const text = near ? `${base} · near limit` : base;
+  const width = useTween(fraction);
+  const h = height ?? TONE_HEIGHT[tone];
+  const fill = tone === 'limit' ? (near ? colors.status.needsUser : colors.status.executed)
+    : tone === 'accent' ? colors.accentFill
+    : tone === 'neutral' ? colors.textSecondary
+    : tone === 'ink' ? colors.textPrimary
+    : tone === 'success' ? colors.status.executed
+    : colors.status.needsUser;
+
+  const bar = (
+    <Box
+      height={h}
+      radius="pill"
+      role="progressbar"
+      aria-label={label}
+      aria-valuenow={Math.round(value)}
+      aria-valuemin={0}
+      aria-valuemax={max}
+      aria-valuetext={text}
+      style={{ backgroundColor: track === 'surface' ? colors.surface1 : colors.band, overflow: 'hidden' }}>
+      <MotionView
+        style={{
+          height: h,
+          borderRadius: h / 2,
+          backgroundColor: fill,
+          width: width.interpolate({ inputRange: [0, 1], outputRange: ['0%', '100%'] }),
+        }}
+      />
+    </Box>
+  );
+  if (bare) return bar;
+
+  return (
+    <Box gap="s1">
+      <Box row justify="space-between" gap="s2">
+        <Text variant="caption" color="textPrimary" numberOfLines={1} style={{ flexShrink: 1 }}>{label}</Text>
+        <Text
+          variant="caption"
+          numeric
+          numberOfLines={1}
+          style={{ fontSize: 12, color: near ? colors.status.needsUser : colors.textSecondary, fontWeight: near ? '600' : '400' }}>
+          {text}
+        </Text>
+      </Box>
+      {bar}
+    </Box>
+  );
+}
+
+/* ── D4 · Stat well (onboarding B9) ─────────────────────────────────────── */
+
+/** Where a total stands against its budget. */
+export type Allocation = 'under' | 'exact' | 'over';
+
+export function allocationOf(value: number, total: number): Allocation {
+  return value === total ? 'exact' : value > total ? 'over' : 'under';
+}
+
+/**
+ * **A value against a fixed total, in a well — D4 as the onboarding handoff draws it (B9).**
+ * "Allocated" and a unit hint; the value at 24/600 cross-fading on change (M5) followed by
+ * "of $25,000"; an 8px bar on a white track, ink under the total, mint exactly at it, apricot over
+ * it. The bar is a `progressbar` whose value is the percentage and whose text says the state.
+ */
+export function StatWell({
+  label, hint, value, total, format = n => n.toLocaleString('en-US'),
+}: {
+  label: string;
+  hint?: string;
+  value: number;
+  total: number;
+  format?: (n: number) => string;
+}) {
+  const { colors } = useDs();
+  const state = allocationOf(value, total);
+  const pct = total > 0 ? Math.round((value / total) * 100) : 0;
+  const words = state === 'exact' ? 'fully allocated' : state === 'over' ? `over by ${format(value - total)}` : `${format(total - value)} remaining`;
+  return (
+    <Box gap="s2" style={{ borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken, paddingVertical: 14, paddingHorizontal: 16 }}>
+      <Box row justify="space-between" gap="s2">
+        <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{label}</Text>
+        {hint ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }} numberOfLines={1}>{hint}</Text> : null}
+      </Box>
+      <Box row align="flex-end" gap="s2" wrap>
+        <TickNumber value={value} format={format} fontSize={24} tone={state === 'over' ? 'apricot' : 'default'} label={label} />
+        <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 13, paddingBottom: 4 }}>{`of ${format(total)}`}</Text>
+      </Box>
+      <ProgressBar
+        bare
+        track="surface"
+        label={`${label}: ${pct}% of ${format(total)}`}
+        value={Math.min(value, total)}
+        max={total}
+        format={() => `${pct}% · ${words}`}
+        tone={state === 'exact' ? 'success' : state === 'over' ? 'attention' : 'ink'}
+      />
+    </Box>
+  );
+}
+
+/* ── B8 · Status chip (M9) ───────────────────────────────────────────────── */
+
+export type StateChipTone = 'neutral' | 'success' | 'attention';
+
+/**
+ * **A header status chip whose label cross-fades when it changes — M9 (onboarding B8).** Neutral is
+ * a count ("2 selected"); success is mint with a dot ("Saved"); attention is apricot with a dot
+ * ("Needs attention"). The word carries the state; the colour repeats it.
+ */
+export function StateChip({ tone = 'neutral', children, dot }: {
+  tone?: StateChipTone;
+  children: string;
+  /**
+   * The 6px dot. Default: on for success and attention, off for neutral — as before. Batch 3 turns
+   * it on for a neutral state that is live ("Now", "1 pending") and off for a quiet success ("All read").
+   */
+  dot?: boolean;
+}) {
+  const { colors } = useDs();
+  const fade = useSwap(`${tone}:${children}:${dot}`);
+  const withDot = dot ?? tone !== 'neutral';
+  const custom = tone === 'neutral' ? withDot : !withDot;
+  const ground = tone === 'neutral' ? colors.band : tone === 'success' ? colors.statusBg.executed : colors.statusBg.needsUser;
+  const ink = tone === 'neutral' ? colors.textSecondary : tone === 'success' ? colors.status.executed : colors.status.needsUser;
+  return (
+    <MotionView style={{ opacity: fade }}>
+      {custom ? (
+        <Box row align="center" alignSelf="flex-start" gap="s1" height={24} radius="pill" style={{ paddingHorizontal: 10, backgroundColor: ground }}>
+          {withDot ? <Box width={6} height={6} radius="pill" style={{ backgroundColor: ink }} /> : null}
+          <Text variant="caption" numeric numberOfLines={1} style={{ color: ink, fontSize: 12, lineHeight: 16, fontWeight: '600' }}>{children}</Text>
+        </Box>
+      ) : tone === 'neutral'
+        ? <MetaChip kind="count" hue="neutral">{children}</MetaChip>
+        : <MetaChip kind="status" status={tone === 'success' ? 'executed' : 'needsUser'}>{children}</MetaChip>}
+    </MotionView>
+  );
+}
+
+/* ── D5 · Avatar group ───────────────────────────────────────────────────── */
+
+export type AvatarPerson = { id: string; name: string; initials: string };
+
+/**
+ * **32px circles, −8px overlap, a 2px ring, "+n" after `max`.** One image with one name for a
+ * screen reader — "Maya K., Jon L., Ana R. and 2 more" — rather than five unlabelled circles.
+ * Avatars are people, not categories, so they take the neutral well rather than a hue.
+ */
+export function AvatarGroup({ people, max = 3, size = 32, total, fill = 'well' }: {
+  people: AvatarPerson[];
+  max?: number;
+  size?: number;
+  /** How many people there are in all, when `people` lists only some — "+117" of 120 registrants. */
+  total?: number;
+  /** `band`: the line-soft ground with ink initials (batch 3's Event Reminder). Default: the well. */
+  fill?: 'well' | 'band';
+}) {
+  const { colors } = useDs();
+  const shown = people.slice(0, max);
+  const rest = Math.max(total ?? people.length, people.length) - shown.length;
+  const name = rest > 0
+    ? `${shown.map(p => p.name).join(', ')} and ${rest} more`
+    : shown.map(p => p.name).join(', ');
+  const circle = (key: string, text: string, i: number) => (
+    <Box
+      key={key}
+      width={size}
+      height={size}
+      align="center"
+      justify="center"
+      radius="pill"
+      style={{
+        marginLeft: i === 0 ? 0 : -8,
+        backgroundColor: fill === 'band' ? colors.band : colors.surfaceSunken,
+        borderWidth: 2,
+        borderColor: colors.surface1,
+      }}>
+      <Text variant="caption" numeric style={{ fontSize: 11, fontWeight: '600', color: fill === 'band' ? colors.textPrimary : colors.textSecondary }}>{text}</Text>
+    </Box>
+  );
+  return (
+    <Box row align="center" role="img" aria-label={name} alignSelf="flex-start">
+      {shown.map((p, i) => circle(p.id, p.initials, i))}
+      {rest > 0 ? circle('rest', `+${rest}`, shown.length) : null}
+    </Box>
+  );
+}
+
+/* ── D7 · Check item ─────────────────────────────────────────────────────── */
+
+export type CheckItemState = 'pass' | 'pending' | 'fail';
+
+const CHECK_WORD: Record<CheckItemState, string> = { pass: 'Met', pending: 'Not yet', fail: 'Not met' };
+
+/**
+ * **A requirement and whether it is met — pass, pending, fail.** An 18px circle: pass is mint with
+ * a tick, pending is a hollow `controlBorder` ring, fail is apricot with a cross. The glyph carries
+ * its word for a screen reader. "Fail only after submit" is the caller's rule: show `pending`
+ * until the user has tried, so a form does not open covered in failures.
+ */
+export function CheckItem({ state, children }: { state: CheckItemState; children: string }) {
+  const { colors } = useDs();
+  const skin = state === 'pass'
+    ? { bg: colors.statusBg.executed, ink: colors.status.executed, border: colors.statusBg.executed }
+    : state === 'fail'
+      ? { bg: colors.statusBg.needsUser, ink: colors.status.needsUser, border: colors.statusBg.needsUser }
+      : { bg: colors.surface1, ink: colors.textSecondary, border: colors.controlBorder };
+  return (
+    <Box row align="center" gap="s2" role="listitem">
+      <Box
+        width={18}
+        height={18}
+        align="center"
+        justify="center"
+        radius="pill"
+        style={{ backgroundColor: skin.bg, borderWidth: 1.5, borderColor: skin.border }}>
+        {state === 'pass' ? <Icon name="check" size={11} color={skin.ink} label={CHECK_WORD.pass} /> : null}
+        {state === 'fail' ? <Icon name="close" size={11} color={skin.ink} label={CHECK_WORD.fail} /> : null}
+        {state === 'pending' ? <Box aria-label={CHECK_WORD.pending} role="img" /> : null}
+      </Box>
+      <Text variant="caption" color={state === 'pending' ? 'textSecondary' : 'textPrimary'} style={{ flexShrink: 1 }}>
+        {children}
+      </Text>
+    </Box>
+  );
+}
+
+/** A list of `CheckItem`s — the list semantics a screen reader needs to count them. */
+export function CheckList({ label, children }: { label: string; children: ReactNode }) {
+  return <Box role="list" aria-label={label} gap="s2">{children}</Box>;
+}
+
+/* ── D8 · Code block ─────────────────────────────────────────────────────── */
+
+/** How long "Copied" stays before the button returns to "Copy". */
+export const COPIED_MS = 1600;
+
+/**
+ * **Mono 12/1.6 in a well, with Copy.** Long lines scroll horizontally inside the well rather than
+ * wrap (wrapping JSON changes what it looks like it says) or push the page wider.
+ *
+ * `onCopy` is the host's clipboard — React Native has none built in. Omitted on the web, the
+ * browser clipboard is used when it exists. The confirmation swaps in (M4) and is announced.
+ */
+export function CodeBlock({
+  code, label = 'Code', onCopy, bare = false, minHeight,
+}: {
+  code: string;
+  label?: string;
+  onCopy?: (code: string) => void | Promise<void>;
+  /**
+   * Just the code: white, a 1px line-soft edge, padding 12, no header and no Copy — for a preview
+   * well that owns its own label and Copy (the onboarding Export Format).
+   */
+  bare?: boolean;
+  minHeight?: number;
+}) {
+  const { colors, fonts } = useDs();
+  if (bare) {
+    return (
+      <Box style={{ borderRadius: blockRadii.inset, backgroundColor: colors.surface1, borderWidth: 1, borderColor: colors.hairline, minHeight }}>
+        <Scroll horizontal indicator p="s3">
+          <Text style={{ fontFamily: fonts.mono, fontSize: 12, lineHeight: 19, color: colors.textPrimary }}>{code}</Text>
+        </Scroll>
+      </Box>
+    );
+  }
+  return <CodeBlockWithCopy code={code} label={label} onCopy={onCopy} />;
+}
+
+function CodeBlockWithCopy({ code, label, onCopy }: { code: string; label: string; onCopy?: (code: string) => void | Promise<void> }) {
+  const { colors, fonts } = useDs();
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+  const fade = useSwap(copied ? 'copied' : 'copy');
+
+  const copy = async () => {
+    const clip = (globalThis as { navigator?: { clipboard?: { writeText: (s: string) => Promise<void> } } }).navigator?.clipboard;
+    try {
+      if (onCopy) await onCopy(code);
+      else await clip?.writeText(code);
+    } catch {
+      return; // a refused clipboard is not "Copied"
+    }
+    setCopied(true);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setCopied(false), COPIED_MS);
+  };
+
+  return (
+    <Box style={{ borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken }}>
+      <Box row justify="space-between" align="center" px="s3" pt="s2">
+        <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{label}</Text>
+        <Pressable onPress={copy} aria-label={copied ? 'Copied' : `Copy ${label.toLowerCase()}`} px="s2" py="s1" radius="field">
+          <MotionView style={{ opacity: fade, flexDirection: 'row', alignItems: 'center', gap: 4 }}>
+            {copied ? <Icon name="check" size={12} color={colors.status.executed} /> : null}
+            <Text variant="caption" style={{ fontSize: 12, fontWeight: '600', color: copied ? colors.status.executed : colors.textPrimary }}>
+              {copied ? 'Copied' : 'Copy'}
+            </Text>
+          </MotionView>
+        </Pressable>
+      </Box>
+      <Box role="status" aria-live="polite" style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', opacity: 0 }}>
+        <Text>{copied ? `${label} copied` : ''}</Text>
+      </Box>
+      <Scroll horizontal indicator px="s3" py="s2">
+        <Text style={{ fontFamily: fonts.mono, fontSize: 12, lineHeight: 19, color: colors.textPrimary }}>{code}</Text>
+      </Scroll>
+    </Box>
+  );
+}
+
+/* ── D10 · Media slot ────────────────────────────────────────────────────── */
+
+/**
+ * **A fixed-ratio frame: the space is reserved before the media arrives, so nothing shifts.**
+ * Empty, it is the well with its label. `caption` is the text form of what the media shows —
+ * a QR code's setup key — because an image of a code is useless to anyone who cannot scan it.
+ */
+export function MediaSlot({
+  ratio = 1, label, caption, children, maxWidth = 200,
+}: {
+  /** width / height. */
+  ratio?: number;
+  label: string;
+  caption?: ReactNode;
+  children?: ReactNode;
+  maxWidth?: number;
+}) {
+  const { colors } = useDs();
+  return (
+    <Box gap="s2" style={{ width: '100%', maxWidth }}>
+      <Box
+        role="img"
+        aria-label={label}
+        align="center"
+        justify="center"
+        style={{ width: '100%', aspectRatio: ratio, borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken, overflow: 'hidden' }}>
+        {children ?? <Text variant="caption" color="textSecondary">{label}</Text>}
+      </Box>
+      {caption !== undefined ? (
+        typeof caption === 'string'
+          ? <Text variant="caption" mono color="textPrimary" style={{ fontSize: 12 }}>{caption}</Text>
+          : caption
+      ) : null}
+    </Box>
+  );
+}

package/src/ds/blockLayout.tsx

@@ -0,0 +1,145 @@
+import { Children, useState, type ReactNode } from 'react';
+import { Box, Pressable, Text } from '../core';
+import { blockRadii, space, useDs } from '../tokens';
+
+/**
+ * **Solarium Building Blocks — layout.** S4 Card grid · S5 Two-panel.
+ *
+ * Structure only. Neither draws a card: the grid places whatever cards it is given (normally
+ * `BlockCard`s) and the two-panel places a sidebar beside a list. Both measure their OWN width
+ * rather than the viewport's, because a block embedded in a 400px side panel on a desktop is a
+ * phone-width block — the container-query rule `OutputWidgetShell` already follows.
+ */
+
+/* ── S4 · Card grid ──────────────────────────────────────────────────────── */
+
+/** Columns for a container `width` wide: as many `minItem`-wide columns as fit, 1..`max`. Pure. */
+export function gridColumns(width: number, minItem: number, max: number, gap: number): number {
+  if (width <= 0) return 1;
+  return Math.max(1, Math.min(max, Math.floor((width + gap) / (minItem + gap))));
+}
+
+/**
+ * **1–3 columns, each at least 160px; an odd last tile never stretches.** Every tile is exactly one
+ * column wide — a flex-grow grid would stretch a lone last tile across the row and make it read as
+ * the most important card on the page.
+ */
+export function CardGrid({
+  children, minItemWidth = 160, maxColumns = 3, gap = 's3', label,
+}: {
+  children: ReactNode;
+  minItemWidth?: number;
+  maxColumns?: 1 | 2 | 3;
+  gap?: 's2' | 's3' | 's4';
+  /** A name when the grid is a meaningful group ("Dashboards"). Rendered as a list. */
+  label?: string;
+}) {
+  const [width, setWidth] = useState(0);
+  const g = GAP[gap];
+  const cols = gridColumns(width, minItemWidth, maxColumns, g);
+  const tile = width > 0 ? (width - g * (cols - 1)) / cols : undefined;
+  return (
+    <Box
+      row
+      wrap
+      role={label ? 'list' : undefined}
+      aria-label={label}
+      onLayout={e => setWidth(e.nativeEvent.layout.width)}
+      style={{ gap: g, width: '100%' }}>
+      {Children.toArray(children).map((child, i) => (
+        <Box key={i} role={label ? 'listitem' : undefined} style={{ width: tile ?? '100%', minWidth: 0 }}>
+          {child}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+const GAP: Record<'s2' | 's3' | 's4', number> = { s2: space.s2, s3: space.s3, s4: space.s4 };
+
+/* ── S5 · Two-panel ──────────────────────────────────────────────────────── */
+
+/** Below this container width the sidebar stacks above the list. */
+export const TWO_PANEL_STACK = 560;
+
+/** The sidebar's width for a container: 28% of it, clamped to 112–240. Pure. */
+export function sidebarWidth(width: number): number {
+  return Math.round(Math.min(240, Math.max(112, width * 0.28)));
+}
+
+/**
+ * **A sidebar (112–240px) beside a list; stacked below 560px.** The sidebar is a navigation
+ * region named by `label`; the list is whatever `children` is. Stacked, the sidebar becomes a
+ * wrapping row of the same items above the list, so no filter is ever hidden behind a toggle.
+ */
+export function TwoPanel({
+  label, sidebar, children,
+}: {
+  /** The sidebar's name — "Filters", "Folders". */
+  label: string;
+  sidebar: ReactNode;
+  children: ReactNode;
+}) {
+  const { colors } = useDs();
+  const [width, setWidth] = useState(0);
+  const stacked = width > 0 && width < TWO_PANEL_STACK;
+  return (
+    <Box
+      row={!stacked}
+      gap="s3"
+      onLayout={e => setWidth(e.nativeEvent.layout.width)}
+      style={{ width: '100%' }}>
+      <Box
+        role="navigation"
+        aria-label={label}
+        p="s1"
+        gap="s1"
+        row={stacked}
+        wrap={stacked}
+        style={{
+          width: stacked ? '100%' : sidebarWidth(width || TWO_PANEL_STACK),
+          borderRadius: blockRadii.inset,
+          backgroundColor: colors.surfaceSunken,
+          alignSelf: stacked ? 'stretch' : 'flex-start',
+        }}>
+        {sidebar}
+      </Box>
+      <Box flex={stacked ? undefined : 1} style={{ minWidth: 0 }}>{children}</Box>
+    </Box>
+  );
+}
+
+/**
+ * **One sidebar item: 26px, radius 6; the selected one is white with ink text.** `aria-current`
+ * marks it, because in a sidebar the selection is *where you are*, not a toggle.
+ */
+export function PanelItem({
+  label, count, selected, onPress,
+}: {
+  label: string;
+  /** Right-aligned, tabular — the number of results this item holds. */
+  count?: number;
+  selected: boolean;
+  onPress: () => void;
+}) {
+  const { colors } = useDs();
+  return (
+    <Pressable
+      onPress={onPress}
+      aria-current={selected ? 'page' : undefined}
+      aria-label={count === undefined ? label : `${label}, ${count}`}
+      row
+      justify="space-between"
+      gap="s2"
+      px="s2"
+      minHeight={26}
+      style={{
+        borderRadius: blockRadii.tile,
+        backgroundColor: selected ? colors.surface1 : undefined,
+        boxShadow: selected ? `0 1px 2px ${colors.hairlineStrong}` : undefined,
+      }}>
+      <Text variant="caption" color={selected ? 'textPrimary' : 'textSecondary'} numberOfLines={1} style={{ fontSize: 12, fontWeight: selected ? '600' : '400' }}>{label}</Text>
+      {count !== undefined ? <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 11 }}>{String(count)}</Text> : null}
+    </Pressable>
+  );
+}