@weasel-js/labkit 1.4.2 → 1.4.4

package/src/controls/ControlPanel.tsx

@@ -2,12 +2,15 @@ import { isBuiltinToolPref } from '@weasel-js/core';
 import {
   CheckboxRow,
   ColorRow,
+  isPrefLeaf,
   NumberRow,
+  type PrefGroup,
   type PrefLeaf,
   type PropertyAlign,
   type PropertyDensity,
   PropertyGroup,
   PropertyList,
+  type PropertyListPack,
   PropertyRow,
   type PropertyRowLayout,
   SelectRow,
@@ -15,9 +18,10 @@ import {
   TextRow,
   ToggleRow,
 } from '@weasel-js/ui';
-import { type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import { Fragment, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
 import { fromConfigFields } from '../config/fromConfigField';
-import type { ControlRenderer, ResolvedConfig } from '../config/types';
+import { schemaNodeAtPath, valueAtPath } from '../config/path';
+import type { ControlRenderer, ResolvedConfig, SectionSpec } from '../config/types';
 import { isLeafVisible } from '../config/visible';
 import type { ConfigField } from './types';
 
@@ -37,7 +41,9 @@ export interface ControlPanelProps<TC extends Record<string, unknown>> {
   /** @deprecated Pass `schema`. A field list is adapted into one internally. */
   fields?: ConfigField[];
   config: TC;
-  setConfig: (key: keyof TC, value: unknown) => void;
+  /** Writes one value. The path is dotted for a leaf inside an `f.group`, and
+   *  the bare key for one at the root. */
+  setConfig: (path: string, value: unknown) => void;
   /**
    * Control overrides and app-defined kinds, PrefsForm-style. Keys are config
    * paths (checked first) or leaf kinds. A renderer returning `null` collapses
@@ -58,16 +64,21 @@ export interface ControlPanelProps<TC extends Record<string, unknown>> {
   align?: PropertyAlign;
   /**
    * Fold each section away behind a twisty, starting `'open'` or `'closed'`.
-   * Unset draws the heading alone, as the panel always has.
+   * Unset draws the heading alone, as the panel always has — unless a section
+   * in the schema declares how it opens, which makes that section foldable on
+   * its own and outranks this for that one section.
    */
   collapse?: 'open' | 'closed';
   /**
-   * Which sections are folded, keyed by section label. Given, the panel keeps
-   * no state of its own: every toggle arrives at `onCollapse` instead, which
-   * is where a lab that remembers a trial's sections writes them.
+   * Which sections are folded, keyed as `onCollapse` reports them. Given, the
+   * panel keeps no state of its own: every toggle arrives at `onCollapse`
+   * instead, which is where a lab that remembers a trial's sections writes
+   * them.
    */
   collapsed?: Readonly<Record<string, boolean>>;
-  onCollapse?: (label: string, collapsed: boolean) => void;
+  /** A fold moved. The key is a section's label — prefixed by its group's
+   *  dotted path when the section sits inside one — or a group's own path. */
+  onCollapse?: (key: string, collapsed: boolean) => void;
   /** Draw leaves marked `hidden`. */
   showHidden?: boolean;
   className?: string;
@@ -94,27 +105,75 @@ export function ControlPanel<TC extends Record<string, unknown>>({
 }: ControlPanelProps<TC>) {
   const resolved = useMemo(() => schema ?? fromConfigFields(fields ?? []), [schema, fields]);
 
-  const paths = Object.keys(resolved.group.children);
-  const sectioned = new Set(resolved.sections.flatMap((s) => s.paths));
-  const loose = paths.filter((p) => !sectioned.has(p));
+  const gridPack: PropertyListPack = pack === 'one-up' ? 'auto-color' : 'pairs';
+  // A section that declares how it opens is foldable whether or not the lab
+  // asked for folds — there is nothing else for the declaration to mean.
+  const folds =
+    collapse !== undefined ||
+    collapsed !== undefined ||
+    onCollapse !== undefined ||
+    resolved.sections.some((s) => s.collapsed !== undefined);
+  const startsFolded = collapse === 'closed';
 
-  const row = (path: string): ReactNode => (
-    <ControlRow
-      key={path}
-      path={path}
-      resolved={resolved}
-      config={config}
-      setConfig={setConfig}
-      renderers={renderers}
-      pack={pack}
-      layout={layout}
-      showHidden={showHidden}
-    />
-  );
+  const fold = (key: string, declared?: boolean) => ({
+    pack: gridPack,
+    collapsible: folds,
+    defaultCollapsed: declared ?? startsFolded,
+    collapsed: collapsed ? (collapsed[key] ?? declared ?? startsFolded) : undefined,
+    onCollapsedChange: onCollapse ? (next: boolean) => onCollapse(key, next) : undefined,
+  });
+
+  /** One node, which is either a group to recurse into or a row to draw. */
+  const node = (path: string): ReactNode => {
+    const found = schemaNodeAtPath(resolved.group, path);
+    if (!found) return null;
+    if (!isLeafVisible(resolved, path, config as Record<string, unknown>, showHidden)) return null;
+    if (isPrefLeaf(found)) {
+      return (
+        <ControlRow
+          key={path}
+          path={path}
+          leaf={found}
+          resolved={resolved}
+          config={config}
+          setConfig={setConfig}
+          renderers={renderers}
+          pack={pack}
+          layout={layout}
+        />
+      );
+    }
+    // A group with no name organizes without heading it — core's rule for an
+    // empty `PrefGroup.name` — so it contributes its rows and no chrome.
+    if (found.name === '') return <Fragment key={path}>{body(found, path)}</Fragment>;
+    return (
+      <PropertyGroup key={path} title={found.name} {...fold(path)}>
+        {body(found, path)}
+      </PropertyGroup>
+    );
+  };
+
+  /** One group's children: its loose nodes, then its sections. */
+  const body = (group: PrefGroup, at: string): ReactNode => {
+    const sections = resolved.sections.filter((s) => s.at === at);
+    const sectioned = new Set(sections.flatMap((s) => s.paths));
+    const paths = Object.keys(group.children).map((key) => (at === '' ? key : `${at}.${key}`));
+    return (
+      <>
+        {paths.filter((p) => !sectioned.has(p)).map(node)}
+        {sections.map((section) => (
+          <PropertyGroup
+            key={sectionKey(section)}
+            title={section.label}
+            {...fold(sectionKey(section), section.collapsed)}
+          >
+            {section.paths.map(node)}
+          </PropertyGroup>
+        ))}
+      </>
+    );
+  };
 
-  const gridPack = pack === 'one-up' ? 'auto-color' : 'pairs';
-  const folds = collapse !== undefined || collapsed !== undefined || onCollapse !== undefined;
-  const startsFolded = collapse === 'closed';
   return (
     <PropertyList
       pack={gridPack}
@@ -122,33 +181,27 @@ export function ControlPanel<TC extends Record<string, unknown>>({
       align={align}
       className={className ? `lk-control-panel ${className}` : 'lk-control-panel'}
     >
-      {loose.map(row)}
-      {resolved.sections.map((section) => (
-        <PropertyGroup
-          key={section.label}
-          title={section.label}
-          pack={gridPack}
-          collapsible={folds}
-          defaultCollapsed={startsFolded}
-          collapsed={collapsed ? (collapsed[section.label] ?? startsFolded) : undefined}
-          onCollapsedChange={onCollapse ? (next) => onCollapse(section.label, next) : undefined}
-        >
-          {section.paths.map(row)}
-        </PropertyGroup>
-      ))}
+      {body(resolved.group, '')}
     </PropertyList>
   );
 }
 
+/** How a section is keyed for folding: its label at the root, and its group's
+ *  path in front of it anywhere else, so two groups may both have an
+ *  `Advanced`. */
+function sectionKey(section: SectionSpec): string {
+  return section.at === '' ? section.label : `${section.at}.${section.label}`;
+}
+
 interface ControlRowProps<TC extends Record<string, unknown>> {
   path: string;
+  leaf: PrefLeaf;
   resolved: ResolvedConfig;
   config: TC;
-  setConfig: (key: keyof TC, value: unknown) => void;
+  setConfig: (path: string, value: unknown) => void;
   renderers?: Record<string, ControlRenderer>;
   pack: ControlPack;
   layout?: PropertyRowLayout;
-  showHidden: boolean;
 }
 
 /** Reads a labkit-only extra off a leaf. `PrefLeaf` has no field for these,
@@ -159,21 +212,17 @@ function extra<T>(leaf: PrefLeaf, key: string): T | undefined {
 
 function ControlRow<TC extends Record<string, unknown>>({
   path,
+  leaf,
   resolved,
   config,
   setConfig,
   renderers,
   pack,
   layout,
-  showHidden,
 }: ControlRowProps<TC>) {
-  const leaf = resolved.group.children[path] as PrefLeaf | undefined;
-  if (!leaf || !('kind' in leaf)) return null;
-  if (!isLeafVisible(resolved, path, config as Record<string, unknown>, showHidden)) return null;
-
-  const write = (value: unknown): void => setConfig(path as keyof TC, value);
+  const write = (value: unknown): void => setConfig(path, value);
   const fallback = extra<unknown>(leaf, 'default');
-  const value = config[path] ?? fallback;
+  const value = valueAtPath(config, path) ?? fallback;
 
   // Most specific wins, and within a tier the lab's entry beats the
   // instrument's: controls[path] -> node .render -> controls[kind] -> built-in.

package/src/index.ts

@@ -76,7 +76,7 @@ export {
   createAnnotationScene,
   createAnnotationStore,
   fracContains,
-  fracIntersects,
+  fracEncloses,
   fracToWorld,
   isStale,
   roundFrac,
@@ -145,25 +145,40 @@ export {
   zoomAt,
 } from './canvas';
 export * from './chrome';
-export { f } from './config/builder';
+export { f, isConfigBranch } from './config/builder';
 export { fromConfigFields } from './config/fromConfigField';
+export {
+  fillConfigDefaults,
+  hasConfigPath,
+  schemaNodeAtPath,
+  valueAtPath,
+  withValueAtPath,
+} from './config/path';
 export { resolveConfigSchema } from './config/resolve';
 export { applyRules, builtinRules, titleCase } from './config/rules';
 export type {
   Annotations,
+  BranchAnnotations,
+  BranchOptions,
+  ConfigBranch,
+  ConfigEntry,
   ConfigNode,
   ConfigOf,
   ConfigOption,
+  ConfigPath,
   ConfigRule,
   ConfigRuleContext,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
+  EntryValue,
   InferConfig,
   LeafPatch,
   NodeOptions,
   NodeValue,
   ResolvedConfig,
   SectionSpec,
+  ValueAtPath,
 } from './config/types';
 export { useConfigSchema } from './config/useConfigSchema';
 export { isLeafVisible } from './config/visible';

package/src/instrument/serializers.ts

@@ -0,0 +1,36 @@
+import type { InstrumentSerializers } from '../state/types';
+import type { InstrumentList } from './types';
+
+/**
+ * Each instrument's default config, keyed by name — what `createLabStore`
+ * fills a stored config's gaps from, so one saved before its schema grew a
+ * branch still loads.
+ */
+export function configDefaultsOf(instruments: InstrumentList): Record<string, () => unknown> {
+  const out: Record<string, () => unknown> = {};
+  for (const instrument of instruments) out[instrument.name] = () => instrument.defaultConfig();
+  return out;
+}
+
+/**
+ * The `serialize` / `deserialize` an instrument list declares, keyed by
+ * instrument name — what `createLabStore` needs to rebuild a trial's state
+ * from storage.
+ *
+ * An instrument declaring neither gets no entry, which is what leaves a
+ * JSON-safe state to pass through untouched.
+ */
+export function serializersOf(instruments: InstrumentList): InstrumentSerializers {
+  const out: InstrumentSerializers = {};
+  for (const instrument of instruments) {
+    const { name, serialize, deserialize } = instrument;
+    if (!serialize && !deserialize) continue;
+    out[name] = {
+      ...(serialize ? { serialize: (state: unknown) => serialize(state) } : {}),
+      ...(deserialize
+        ? { deserialize: (data: unknown, config: unknown) => deserialize(data, config) }
+        : {}),
+    };
+  }
+  return out;
+}

package/src/instrument/types.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react';
 import type { AnnotationsCapability } from '../annotations/types';
 import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
-import type { ConfigSchema } from '../config/types';
+import type { ConfigPath, ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
 import type { LoupeDeclaration } from '../loupe/types';
@@ -15,7 +15,9 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   state: TS;
   config: TC;
   setState: (next: TS | ((prev: TS) => TS)) => void;
-  setConfig: (key: keyof TC, value: unknown) => void;
+  /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+   *  an `f.group`, `'cellSize'` for one at the root. */
+  setConfig: (path: ConfigPath<TC>, value: unknown) => void;
   /** labkit persists `view` and restores it on Reset without ever reading
    *  into it. */
   trial: TrialInfo & {

package/src/lab/Lab.test.tsx

@@ -1,7 +1,9 @@
 import { act, render, screen } from '@testing-library/react';
 import type { ReactNode } from 'react';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { Instrument } from '../instrument/types';
+import { createMemoryAdapter } from '../state/adapters';
+import { labDocumentKey } from '../state/document';
 import { Lab } from './Lab';
 import { LabContext, type LabContextValue } from './LabContext';
 
@@ -135,4 +137,30 @@ describe('<Lab>', () => {
       /Unknown instrument/,
     );
   });
+
+  // The store reads its serializers while it is being built, so `<Lab>` is
+  // the only thing positioned to collect them off the instruments. They went
+  // uncollected for months, and an instrument holding anything JSON drops
+  // lost it with no error.
+  it('gives the store the serializers its instruments declare', () => {
+    vi.useFakeTimers();
+    const storage = createMemoryAdapter();
+    const mapped: Instrument = {
+      ...stub,
+      name: 'Mapped',
+      initialState: () => ({ seen: new Set(['a']) }),
+      serialize: (state) => ({ seen: [...(state as { seen: Set<string> }).seen] }),
+      deserialize: (data) => ({ seen: new Set((data as { seen: string[] }).seen) }),
+    };
+
+    render(
+      <Lab instruments={[mapped]} defaultInstrument="Mapped" storage={storage} storageKey="s" />,
+    );
+    act(() => vi.advanceTimersByTime(500));
+    expect(storage.read(labDocumentKey('s')) ?? '').toContain('"seen":["a"]');
+    vi.useRealTimers();
+
+    mountLab({ instruments: [mapped], defaultInstrument: 'Mapped', storage, storageKey: 's' });
+    expect((labRef?.trials[0]?.state as { seen: Set<string> }).seen).toEqual(new Set(['a']));
+  });
 });

package/src/lab/Lab.tsx

@@ -11,6 +11,7 @@ import {
 import { useStore } from 'zustand/react';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigRule, ControlRenderer } from '../config/types';
+import { configDefaultsOf, serializersOf } from '../instrument/serializers';
 import type { InstrumentList } from '../instrument/types';
 import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
@@ -78,7 +79,15 @@ function buildStore(
   storageKey: string,
   initialMode: LabMode,
 ): LabStore {
-  const store = createLabStore({ storageKey, storage, initialMode });
+  // Hydration reads the serializers, so they go in with the store rather than
+  // being registered onto it afterwards.
+  const store = createLabStore({
+    storageKey,
+    storage,
+    initialMode,
+    serializers: serializersOf(instruments),
+    configDefaults: configDefaultsOf(instruments),
+  });
   if (store.getState().trials.length === 0) {
     const seeded = addTrialOp([], instruments, defaultInstrument);
     const record = seeded[0];

package/src/lab/LabShell.test.tsx

@@ -39,6 +39,14 @@ describe('LabShell', () => {
     expect(root.getAttribute('data-wzl-mode')).toMatch(/^(light|dark)$/);
   });
 
+  // The overlays weasel-ui ships default to the nearest portal host, and
+  // `.lk-root` is where labkit's element defaults live — not the themed
+  // wrapper above it.
+  test('marks lk-root as the portal host for overlays', () => {
+    const { container } = render(<LabShell title="t">x</LabShell>);
+    expect(container.querySelector('.lk-root')?.hasAttribute('data-wzl-portal-host')).toBe(true);
+  });
+
   test('always applies lk-root class', () => {
     const { container } = render(<LabShell title="t">x</LabShell>);
     expect(container.querySelector('.lk-root')).not.toBeNull();

package/src/lab/LabShell.tsx

@@ -2,6 +2,8 @@ import { ThemeProvider, useThemeOptional } from '@weasel-js/theme/react';
 import type { ReactNode } from 'react';
 import type { LabMode } from '../state/types';
 import { interstellarTheme } from '../theme/interstellar';
+import type { LabPage } from './LabSwitcher';
+import { LabSwitcher } from './LabSwitcher';
 import { useResolvedMode } from './useSystemMode';
 
 /** Props for `<LabShell>`. */
@@ -14,19 +16,31 @@ export interface LabShellProps {
   footer?: ReactNode;
   /** Color mode. "auto" (default) follows prefers-color-scheme. */
   mode?: LabMode;
+  /** The project's other labs. Given two or more, the title becomes the way
+   *  to reach them; given none, it stays a plain heading. */
+  pages?: readonly LabPage[];
+  /** The path the switcher reads to mark the open page. Defaults to the
+   *  current location. */
+  path?: string;
 }
 
 /** Page frame for a lab: a titled header, a body, and an optional footer,
  *  themed for the resolved color mode. Presentational only — use `<Lab>` when
  *  the trial runtime is wanted too. */
-export function LabShell({ title, children, header, footer, mode = 'auto' }: LabShellProps) {
+export function LabShell({ title, children, header, footer, mode = 'auto',
+                          pages, path }: LabShellProps) {
   const resolved = useResolvedMode(mode);
   const outer = useThemeOptional();
 
   const shell = (
-    <div className="lk-root lk-shell">
+    // Overlays portal here rather than to the themed wrapper above: `.lk-root`
+    // carries the element defaults a lab's bare markup is styled by.
+    <div className="lk-root lk-shell" data-wzl-portal-host="">
       <header className="lk-shell-header">
-        <h1 className="lk-shell-title">{title}</h1>
+        {pages && pages.length > 0
+          ? <LabSwitcher title={title} pages={pages} path={path}
+                         className="lk-shell-title" />
+          : <h1 className="lk-shell-title">{title}</h1>}
         {header && <div className="lk-shell-header-actions">{header}</div>}
       </header>
       <main className="lk-shell-body">{children}</main>

package/src/lab/LabSwitcher.less

@@ -0,0 +1,85 @@
+.lk-switcher {
+  position: relative;
+  display: inline-block;
+}
+
+.lk-switcher-title {
+  margin: 0;
+  font-size: var(--wzl-font-size-xl);
+  line-height: var(--wzl-line-height-tight, 1.2);
+}
+
+.lk-switcher-trigger {
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--wzl-space-xs);
+  // The title IS the control, so it keeps the title's type and gives up every
+  // other button affordance until it is pointed at.
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+
+  &:hover { color: var(--wzl-text-accent, var(--wzl-text)); }
+
+  &:focus-visible {
+    outline: 2px solid var(--wzl-focus-ring, currentColor);
+    outline-offset: 2px;
+    border-radius: var(--wzl-radius-sm, 2px);
+  }
+}
+
+.lk-switcher-caret {
+  // Sized in em so it tracks the title rather than needing a second rule per
+  // heading size.
+  width: 0.36em;
+  height: 0.36em;
+  border-right: 0.09em solid currentColor;
+  border-bottom: 0.09em solid currentColor;
+  transform: translateY(-0.18em) rotate(45deg);
+  opacity: 0.6;
+}
+
+.lk-switcher-trigger[aria-expanded='true'] .lk-switcher-caret {
+  transform: translateY(0.06em) rotate(-135deg);
+}
+
+.lk-switcher-menu {
+  position: absolute;
+  top: calc(100% + var(--wzl-space-xs));
+  left: 0;
+  z-index: var(--wzl-z-popover, 60);
+  min-width: max(100%, 11rem);
+  display: flex;
+  flex-direction: column;
+  padding: var(--wzl-space-xs);
+  background: var(--wzl-surface-raised);
+  border: 1px solid var(--wzl-border);
+  border-radius: var(--wzl-radius-md, 6px);
+  box-shadow: var(--wzl-shadow-md, 0 6px 20px rgb(0 0 0 / 35%));
+}
+
+.lk-switcher-item {
+  padding: var(--wzl-space-xs) var(--wzl-space-sm);
+  border-radius: var(--wzl-radius-sm, 3px);
+  color: var(--wzl-text);
+  font-size: var(--wzl-font-size-md);
+  text-decoration: none;
+  white-space: nowrap;
+
+  &:hover { background: var(--wzl-surface-hover, var(--wzl-surface)); }
+
+  &:focus-visible {
+    outline: 2px solid var(--wzl-focus-ring, currentColor);
+    outline-offset: -2px;
+  }
+}
+
+// The open page stays in the list rather than being filtered out: a menu that
+// drops its current entry shifts every other one as you move between pages.
+.lk-switcher-item[aria-current='page'] {
+  color: var(--wzl-text-strong, var(--wzl-text));
+  font-weight: var(--wzl-font-weight-semibold, 600);
+}

package/src/lab/LabSwitcher.test.tsx

@@ -0,0 +1,96 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { currentPage, LabSwitcher } from './LabSwitcher';
+import { LabShell } from './LabShell';
+
+const PAGES = [
+  { href: '/corpus', label: 'Wall' },
+  { href: '/stats', label: 'Dashboard' },
+  { href: '/ingest', label: 'Ingestion' },
+];
+
+const open = () => fireEvent.click(screen.getByRole('button', { name: /corpus stats/ }));
+
+describe('currentPage', () => {
+  it('matches a bare path', () => {
+    expect(currentPage('/stats', PAGES)).toBe(1);
+  });
+
+  it('survives a query string, a trailing slash and a leftover extension', () => {
+    // A dev server maps `/stats` to `stats.html` and serves both spellings, so
+    // an old bookmark must still resolve to the same page.
+    for (const path of ['/stats?kind=base', '/stats/', '/stats.html',
+                        '/lab/stats.html#top']) {
+      expect(currentPage(path, PAGES)).toBe(1);
+    }
+  });
+
+  it('reports -1 for a page that is not one of them', () => {
+    expect(currentPage('/bench', PAGES)).toBe(-1);
+  });
+});
+
+describe('<LabSwitcher>', () => {
+  it('shows the title and nothing else until it is opened', () => {
+    render(<LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />);
+    expect(screen.getByRole('button', { name: /corpus stats/ })).toHaveAttribute(
+      'aria-expanded', 'false');
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
+
+  it('opens a menu of every lab, the open one included', () => {
+    // Filtering the current page out shifts every other entry as you move
+    // between pages, so it stays and is marked instead.
+    render(<LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />);
+    open();
+    const items = screen.getAllByRole('menuitem');
+    expect(items.map((i) => i.textContent)).toEqual(['Wall', 'Dashboard', 'Ingestion']);
+    expect(items[1]).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('offers real links, so cmd-click and the back button keep working', () => {
+    // These are separate documents. A <select> would fire a change event and
+    // get none of the three for free.
+    render(<LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />);
+    open();
+    expect(screen.getByRole('menuitem', { name: 'Wall' }).tagName).toBe('A');
+    expect(screen.getByRole('menuitem', { name: 'Wall' })).toHaveAttribute(
+      'href', '/corpus');
+  });
+
+  it('closes on Escape and on a press outside it', () => {
+    render(
+      <div>
+        <LabSwitcher title="corpus stats" pages={PAGES} path="/stats" />
+        <button type="button">elsewhere</button>
+      </div>);
+    open();
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(screen.queryByRole('menu')).toBeNull();
+
+    open();
+    fireEvent.pointerDown(screen.getByRole('button', { name: 'elsewhere' }));
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
+
+  it('stays a plain heading when there is nowhere to switch to', () => {
+    // A disclosure arrow promising a menu of the page you are already on is
+    // worse than no control.
+    render(<LabSwitcher title="corpus stats" pages={[PAGES[1]!]} path="/stats" />);
+    expect(screen.getByRole('heading', { name: 'corpus stats' })).toBeInTheDocument();
+    expect(screen.queryByRole('button')).toBeNull();
+  });
+});
+
+describe('<LabShell> with pages', () => {
+  it('turns its title into the switcher', () => {
+    render(<LabShell title="corpus stats" pages={PAGES} path="/stats">body</LabShell>);
+    expect(screen.getByRole('button', { name: /corpus stats/ })).toBeInTheDocument();
+  });
+
+  it('leaves the title alone when no pages are given', () => {
+    render(<LabShell title="corpus stats">body</LabShell>);
+    expect(screen.getByRole('heading', { name: 'corpus stats' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /corpus stats/ })).toBeNull();
+  });
+});