@weasel-js/labkit 1.6.1 → 1.7.1

package/src/primitives/Readout.browser.test.tsx

@@ -0,0 +1,137 @@
+import '@weasel-js/theme/tokens.css';
+import '@weasel-js/theme/fonts.css';
+import '../styles.less';
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, expect, test } from 'vitest';
+import { Readout, type ReadoutRow } from './Readout';
+
+function must<T>(el: T | null): T {
+  if (el == null) throw new Error('expected an element');
+  return el;
+}
+
+// Right alignment, the figure column's minimum width and a height that holds
+// while values come and go are all layout, which only a real browser has.
+
+afterEach(cleanup);
+
+const FIGURE_SPACE = ' ';
+
+const rows = (withValues: boolean): ReadoutRow[] => [
+  {
+    label: 'Lock margin',
+    value: withValues ? <span data-v>locked +47.9°</span> : undefined,
+    status: 'success',
+  },
+  { label: 'Score', value: withValues ? <span data-v>{`${FIGURE_SPACE}0.145`}</span> : undefined },
+  { label: 'Error', value: withValues ? <span data-v>12.345</span> : undefined, status: 'danger' },
+];
+
+const box = (el: Element) => el.getBoundingClientRect();
+
+test('values sit right-aligned at the edge of the list', () => {
+  const { container } = render(
+    <div style={{ width: 320 }}>
+      <Readout rows={rows(true)} />
+    </div>,
+  );
+  const dl = must(container.querySelector('dl'));
+  const values = [...container.querySelectorAll('[data-v]')];
+  expect(values).toHaveLength(3);
+  for (const v of values) expect(Math.abs(box(v).right - box(dl).right)).toBeLessThan(0.5);
+  expect(box(values[0]).width).not.toBeCloseTo(box(values[2]).width, 0);
+});
+
+test('figures are equal width, so padding lines a column up on the decimal point', async () => {
+  // 1 and 8 differ in width wherever digits are proportional, as they are in
+  // the theme's display face, which has no tabular figures to switch on.
+  const { container } = render(
+    <div style={{ width: 320, fontFamily: 'var(--wzl-font-display)' }}>
+      <Readout
+        rows={[
+          { label: 'a', value: <span data-v>{`${FIGURE_SPACE}1.111`}</span> },
+          { label: 'b', value: <span data-v>88.888</span> },
+        ]}
+      />
+    </div>,
+  );
+  await document.fonts.ready;
+  const [narrow, wide] = [...container.querySelectorAll('[data-v]')];
+  expect(Math.abs(box(narrow).width - box(wide).width)).toBeLessThan(0.5);
+});
+
+test('the value column holds a minimum width in a shrink-wrapped readout', () => {
+  const { container } = render(
+    <div style={{ width: 'max-content' }}>
+      <Readout rows={[{ label: 'n', value: <span data-v>1</span> }]} />
+    </div>,
+  );
+  const digit = box(must(container.querySelector('[data-v]'))).width;
+  const dd = box(must(container.querySelector('dd'))).width;
+  expect(dd).toBeGreaterThanOrEqual(8 * digit - 0.5);
+});
+
+test('rows keep their place and the list its height while values are absent', () => {
+  const { container, rerender } = render(
+    <div style={{ width: 320 }}>
+      <Readout rows={rows(true)} />
+    </div>,
+  );
+  const dl = () => must(container.querySelector('dl'));
+  const rowHeights = () => [...dl().children].map((r) => box(r).height);
+  const withValues = { list: box(dl()).height, rows: rowHeights() };
+  rerender(
+    <div style={{ width: 320 }}>
+      <Readout rows={rows(false)} />
+    </div>,
+  );
+  expect(dl().querySelectorAll('[data-empty]')).toHaveLength(3);
+  expect(box(dl()).height).toBeCloseTo(withValues.list, 1);
+  expect(rowHeights()).toEqual(withValues.rows);
+});
+
+test('a status dot is drawn before its value, on the same line', () => {
+  const { container } = render(
+    <div style={{ width: 320 }}>
+      <Readout rows={rows(true)} />
+    </div>,
+  );
+  const dd = must(container.querySelector('dd'));
+  const dot = box(must(dd.querySelector('[aria-hidden]')));
+  const value = box(must(dd.querySelector('[data-v]')));
+  expect(dot.width).toBeGreaterThan(0);
+  expect(dot.right).toBeLessThanOrEqual(value.left);
+  expect(dot.top).toBeGreaterThanOrEqual(value.top - 1);
+  expect(dot.bottom).toBeLessThanOrEqual(value.bottom + 1);
+});
+
+test('a text row wraps inside a figures readout instead of overflowing it', () => {
+  const { container } = render(
+    <div style={{ width: 300, fontFamily: 'var(--wzl-font-display)' }}>
+      <Readout
+        rows={[
+          { label: 'Score', value: <span data-v>0.145</span> },
+          {
+            label: 'Sides',
+            value: (
+              <span data-t>
+                1 flat, 2 tab, 3 blank, 4 blank, 5 flat, 6 tab, 7 blank, 8 blank, 9 flat
+              </span>
+            ),
+            values: 'text',
+          },
+        ]}
+      />
+    </div>,
+  );
+  const dl = must(container.querySelector('dl'));
+  expect(dl.scrollWidth).toBeLessThanOrEqual(dl.clientWidth);
+  const text = must(container.querySelector('[data-t]'));
+  expect(box(text).right).toBeLessThanOrEqual(box(dl).right + 0.5);
+  expect(box(text).height).toBeGreaterThan(
+    box(must(container.querySelector('[data-v]'))).height * 1.5,
+  );
+  expect(
+    Math.abs(box(must(container.querySelector('[data-v]'))).right - box(dl).right),
+  ).toBeLessThan(0.5);
+});

package/src/primitives/Readout.less

@@ -0,0 +1,12 @@
+.lk-readout {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-4);
+  min-width: 0;
+}
+
+.lk-readout__footer {
+  min-width: 0;
+  font-size: var(--wzl-font-size-sm);
+  color: var(--wzl-fg-muted);
+}

package/src/primitives/Readout.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { useState } from 'react';
+import { Readout } from './Readout';
+
+const meta: Meta<typeof Readout> = {
+  title: 'labkit/Primitives/Readout',
+  component: Readout,
+};
+export default meta;
+
+type Story = StoryObj<typeof Readout>;
+
+const FIGURE_SPACE = ' ';
+
+export const Measurements: Story = {
+  tags: ['gallery'],
+  args: {
+    rows: [
+      { label: 'Lock margin', value: 'locked +47.9°', status: 'success' },
+      { label: 'Score', value: `${FIGURE_SPACE}0.145` },
+      { label: 'Residual', value: `${FIGURE_SPACE}3.020` },
+      { label: 'Overshoot', value: 'over 12.345', status: 'danger' },
+    ],
+  },
+};
+
+export const WithTitleAndNote: Story = {
+  args: {
+    title: 'Fit',
+    rows: [
+      { label: 'Score', value: '0.145' },
+      { label: 'Iterations', value: `${FIGURE_SPACE}${FIGURE_SPACE}42` },
+    ],
+    children: 'Scores under 0.2 converge within one pass.',
+  },
+};
+
+/** Values vanish while the cursor is off the picture; the rows hold their
+ *  place and the readout its height. */
+export const ValuesComeAndGo: Story = {
+  render: () => {
+    const [on, setOn] = useState(true);
+    return (
+      <div>
+        <button type="button" onClick={() => setOn((v) => !v)}>
+          {on ? 'Hide values' : 'Show values'}
+        </button>
+        <Readout
+          rows={[
+            { label: 'x', value: on ? `${FIGURE_SPACE}12.50` : undefined },
+            { label: 'y', value: on ? '-3.75' : undefined },
+            { label: 'Hit', value: on ? 'inside' : undefined, status: on ? 'success' : undefined },
+          ]}
+        />
+      </div>
+    );
+  },
+};

package/src/primitives/Readout.test.tsx

@@ -0,0 +1,93 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import * as labkit from '../index';
+import { Readout } from './Readout';
+
+function must<T>(el: T | null): T {
+  if (el == null) throw new Error('expected an element');
+  return el;
+}
+
+describe('Readout', () => {
+  it('renders its rows as one <dl>, in order, each a label and a value', () => {
+    const { container } = render(
+      <Readout
+        rows={[
+          { label: 'Lock margin', value: '+47.9°' },
+          { label: 'Score', value: '0.145' },
+        ]}
+      />,
+    );
+    const dl = must(container.querySelector('dl'));
+    expect([...dl.querySelectorAll('dt')].map((d) => d.textContent)).toEqual([
+      'Lock margin',
+      'Score',
+    ]);
+    expect([...dl.querySelectorAll('dd')].map((d) => d.textContent)).toEqual(['+47.9°', '0.145']);
+  });
+
+  it('sets its values as figures', () => {
+    const { container } = render(<Readout rows={[{ label: 'a', value: '1' }]} />);
+    expect(must(container.querySelector('dl')).getAttribute('data-values')).toBe('figures');
+  });
+
+  it('keeps a row whose value is absent, showing a dash', () => {
+    const { container } = render(
+      <Readout
+        rows={[
+          { label: 'Lock margin', value: undefined },
+          { label: 'Score', value: '0.145' },
+        ]}
+      />,
+    );
+    expect(container.querySelectorAll('dl > div')).toHaveLength(2);
+    expect(must(container.querySelector('dd')).textContent).toBe('–');
+  });
+
+  it('marks a row with its status', () => {
+    const { container } = render(
+      <Readout rows={[{ label: 'Lock', value: 'locked', status: 'success' }]} />,
+    );
+    expect(must(container.querySelector('dl > div')).getAttribute('data-status')).toBe('success');
+  });
+
+  it('puts its children below the rows', () => {
+    const { container } = render(
+      <Readout rows={[{ label: 'a', value: '1' }]}>
+        <p>note</p>
+      </Readout>,
+    );
+    const root = must(container.firstElementChild);
+    expect(root.className).toContain('lk-readout');
+    const note = screen.getByText('note');
+    expect(
+      must(root.querySelector('dl')).compareDocumentPosition(note) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(note.closest('dl')).toBeNull();
+  });
+
+  it('draws no footer without children', () => {
+    const { container } = render(<Readout rows={[{ label: 'a', value: '1' }]} />);
+    expect(container.querySelector('.lk-readout__footer')).toBeNull();
+  });
+
+  it('names the list by its title', () => {
+    render(<Readout title="Measure" rows={[{ label: 'a', value: '1' }]} />);
+    const heading = screen.getByRole('heading', { name: 'Measure' });
+    expect(
+      must(must(heading.parentElement).querySelector('dl')).getAttribute('aria-labelledby'),
+    ).toBe(heading.id);
+  });
+
+  it('merges a consumer className on its root', () => {
+    const { container } = render(<Readout className="is-mine" rows={[]} />);
+    expect(must(container.firstElementChild).className).toMatch(/\blk-readout\b.*\bis-mine\b/);
+  });
+
+  it('is exported from the labkit barrel, with the list it is built on', () => {
+    expect(labkit.Readout).toBe(Readout);
+    expect(typeof labkit.DetailList).toBe('function');
+    expect(typeof labkit.DetailRow).toBe('function');
+  });
+});

package/src/primitives/Readout.tsx

@@ -0,0 +1,56 @@
+import { DetailList, type DetailListValues, DetailRow, type DetailRowStatus } from '@weasel-js/ui';
+import type { ReactNode } from 'react';
+
+/** One measurement in a {@link Readout}. */
+export interface ReadoutRow {
+  /** React key. Defaults to `label` when that is a string, else the row's index. */
+  key?: string;
+  label: ReactNode;
+  /** `null` or `undefined` keeps the row in place showing an en dash, so the
+   *  readout holds its height while a measurement comes and goes. */
+  value?: ReactNode;
+  /** A dot in the status color before the value. Color is never the only
+   *  signal: the value has to say the same thing in words. */
+  status?: DetailRowStatus;
+  /** `text` sets this row's value as wrapping prose instead of a figure. */
+  values?: DetailListValues;
+}
+
+/** Props for {@link Readout}. */
+export interface ReadoutProps {
+  rows: readonly ReadoutRow[];
+  /** Heading above the rows, which also names the list. */
+  title?: ReactNode;
+  /** Drawn below the rows — a small table, a note. */
+  children?: ReactNode;
+  className?: string;
+}
+
+/**
+ * Values a lab only reads — measurements shown beside its picture, such as
+ * "Lock margin +47.9°". A {@link DetailList} set as figures: labels take the
+ * params label recipe and `--wzl-params-label-width` rail, so a readout lines
+ * up with a `ControlPanel` beside it, and values sit right-aligned in the mono
+ * face with spaces kept, so figure-space padding aligns a column on its
+ * decimal point. Rows compose by hand as `DetailRow`s inside a `DetailList`
+ * with `values="figures"`.
+ */
+export function Readout({ rows, title, children, className }: ReadoutProps) {
+  return (
+    <div className={className ? `lk-readout ${className}` : 'lk-readout'}>
+      <DetailList title={title} values="figures">
+        {rows.map((row, i) => (
+          <DetailRow
+            key={row.key ?? (typeof row.label === 'string' ? row.label : i)}
+            label={row.label}
+            status={row.status}
+            values={row.values}
+          >
+            {row.value}
+          </DetailRow>
+        ))}
+      </DetailList>
+      {children != null && <div className="lk-readout__footer">{children}</div>}
+    </div>
+  );
+}

package/src/primitives/Split.tsx

@@ -1,3 +1,4 @@
+import { useLatest } from '@weasel-js/core';
 import { type ReactNode, useEffect, useMemo, useRef } from 'react';
 import { asNodeId, createNode, Store, stripStrategy } from 'windease';
 import { type ChromeMap, Container, Provider, StrategyRegistryProvider } from 'windease/react';
@@ -42,6 +43,65 @@ export interface SplitProps {
   viewport?: { w: number; h: number };
 }
 
+interface SplitInit {
+  side: 'start' | 'end';
+  label: string;
+  sidebarWidth: number;
+  minWidth: number;
+  maxWidth: number;
+  contentMinWidth: number;
+}
+
+/** A strip holding the sidebar and the content pane, sized as the first render asks. */
+function createSplitStore({
+  side,
+  label,
+  sidebarWidth,
+  minWidth,
+  maxWidth,
+  contentMinWidth,
+}: SplitInit): Store {
+  const store = new Store();
+  store.registerNode(
+    createNode({
+      kind: 'zone',
+      id: ZONE_ID,
+      // A strip's seam resizes the pane before it, which on the end side is the
+      // content; 'neighbor' has the seam size the sidebar after it too.
+      container: {
+        strategyId: 'strip',
+        config: {
+          axis: 'x',
+          resizable: true,
+          ...(side === 'end' ? { resizeMode: 'neighbor' } : {}),
+        },
+      },
+    }),
+  );
+  const sidebarNode = createNode({
+    kind: 'sidebar',
+    id: SIDEBAR_ID,
+    parentId: ZONE_ID,
+    meta: { title: label },
+    placement: { size: { w: sidebarWidth } },
+    hints: { minSize: { w: minWidth, h: 0 }, maxSize: { w: maxWidth, h: 0 } },
+  });
+  const contentNode = createNode({
+    kind: 'content',
+    id: CONTENT_ID,
+    parentId: ZONE_ID,
+    meta: { title: 'Content' },
+    hints: { minSize: { w: contentMinWidth, h: 0 } },
+  });
+  // A strip lays its children out in registration order.
+  for (const node of side === 'end' ? [contentNode, sidebarNode] : [sidebarNode, contentNode]) {
+    store.registerNode(node);
+  }
+  store.showNode(SIDEBAR_ID);
+  store.showNode(CONTENT_ID);
+  return store;
+}
+
 /**
  * A sidebar and a content pane as a two-pane strip with a draggable seam.
  *
@@ -70,45 +130,14 @@ export function Split({
   // stretches its panes to the container's height and never reads `h`.
   const storeRef = useRef<Store | null>(null);
   if (storeRef.current === null) {
-    const store = new Store();
-    store.registerNode(
-      createNode({
-        kind: 'zone',
-        id: ZONE_ID,
-        // A strip's seam resizes the pane before it, which on the end side is the
-        // content; 'neighbor' has the seam size the sidebar after it too.
-        container: {
-          strategyId: 'strip',
-          config: {
-            axis: 'x',
-            resizable: true,
-            ...(side === 'end' ? { resizeMode: 'neighbor' } : {}),
-          },
-        },
-      }),
-    );
-    const sidebarNode = createNode({
-      kind: 'sidebar',
-      id: SIDEBAR_ID,
-      parentId: ZONE_ID,
-      meta: { title: label },
-      placement: { size: { w: width ?? defaultWidth } },
-      hints: { minSize: { w: minWidth, h: 0 }, maxSize: { w: maxWidth, h: 0 } },
-    });
-    const contentNode = createNode({
-      kind: 'content',
-      id: CONTENT_ID,
-      parentId: ZONE_ID,
-      meta: { title: 'Content' },
-      hints: { minSize: { w: contentMinWidth, h: 0 } },
+    storeRef.current = createSplitStore({
+      side,
+      label,
+      sidebarWidth: width ?? defaultWidth,
+      minWidth,
+      maxWidth,
+      contentMinWidth,
     });
-    // A strip lays its children out in registration order.
-    for (const node of side === 'end' ? [contentNode, sidebarNode] : [sidebarNode, contentNode]) {
-      store.registerNode(node);
-    }
-    store.showNode(SIDEBAR_ID);
-    store.showNode(CONTENT_ID);
-    storeRef.current = store;
   }
   const store = storeRef.current;
 
@@ -134,8 +163,7 @@ export function Split({
     store.patchPlacement(SIDEBAR_ID, { size: { w: width } });
   }, [store, width]);
 
-  const onWidthChangeRef = useRef(onWidthChange);
-  onWidthChangeRef.current = onWidthChange;
+  const onWidthChangeRef = useLatest(onWidthChange);
   useEffect(
     () =>
       store.events.on('node.placementChanged', () => {
@@ -148,7 +176,7 @@ export function Split({
         widthRef.current = next;
         onWidthChangeRef.current?.(next);
       }),
-    [store],
+    [onWidthChangeRef, store],
   );
 
   const chrome = useMemo<ChromeMap>(

package/src/primitives/Toolbar.tsx

@@ -1,5 +1,5 @@
 import type { MouseEventHandler, ReactNode } from 'react';
-import { useRovingTabIndex } from './useRovingTabIndex';
+import { useRovingTabIndex } from '../passthrough/weasel-ui';
 
 /** Props for `<Toolbar>`. */
 export interface ToolbarProps {
@@ -12,10 +12,10 @@ export interface ToolbarProps {
 /** A horizontal bar of controls. Fill it with `<Toolbar.Title>`,
  *  `<Toolbar.Group>`, `<Toolbar.Button>` and `<Toolbar.Spacer>`. */
 export function Toolbar({ children, 'aria-label': ariaLabel }: ToolbarProps) {
-  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
+  const { rootRef, onKeyDown } = useRovingTabIndex<HTMLDivElement>({ orientation: 'horizontal' });
   return (
     <div
-      ref={ref}
+      ref={rootRef}
       className="lk-toolbar"
       role="toolbar"
       aria-label={ariaLabel}

package/src/primitives/ZoomControl.less

@@ -13,8 +13,7 @@
   }
 }
 
-// The slider is a weasel-ui component whose module class sets `width`.
-// See the `.lk-root` prefix convention in theme/base.less.
+// Under `.lk-root` to outrank theme/base.less's element defaults; see its prefix convention.
 .lk-root {
   .lk-zoom {
     // Narrow enough to sit in a trial toolbar, wide enough for the octave

package/src/primitives/index.ts

@@ -5,6 +5,8 @@ export type { JobProgressProps } from './JobProgress';
 export { JobProgress } from './JobProgress';
 export type { LegendEntry, LegendMark, LegendProps } from './Legend';
 export { Legend } from './Legend';
+export type { ReadoutProps, ReadoutRow } from './Readout';
+export { Readout } from './Readout';
 export type { ScaleIndicatorProps } from './ScaleIndicator';
 export { ScaleIndicator } from './ScaleIndicator';
 export type { SplitProps } from './Split';

package/src/specimen/Specimen.stories.tsx

@@ -3,6 +3,7 @@ import { Specimen } from './Specimen';
 
 const meta: Meta<typeof Specimen> = {
   title: 'labkit/Specimen',
+  tags: ['gallery'],
   component: Specimen,
   parameters: { layout: 'fullscreen' },
 };

package/src/specimen/Specimen.tsx

@@ -1,4 +1,4 @@
-import type { FillStyle, GradientFill, Track } from '@weasel-js/core';
+import type { FillStyle, Track } from '@weasel-js/core';
 import {
   Badge,
   type Band,
@@ -321,7 +321,7 @@ function FieldsAndPickers() {
   const [rate, setRate] = useState(1);
   const [width, setWidth] = useState(6);
   const [color, setColor] = useState('#b08adbff');
-  const [gradient, setGradient] = useState<GradientFill>({
+  const [gradient, setGradient] = useState<FillStyle>({
     fill: 'linear-gradient',
     from: { x: 0.1, y: 0.1 },
     to: { x: 0.9, y: 0.9 },
@@ -666,7 +666,6 @@ function ToolChrome() {
               label={id}
               shortcut={id.slice(0, 1).toUpperCase()}
               active={tool === id}
-              tabbable={tool === id}
               onClick={() => setTool(id)}
             />
           ))}

package/src/state/Persistence.browser.test.tsx

@@ -0,0 +1,47 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, expect, test } from 'vitest';
+import { createIndexedDbAdapter } from './adapters';
+import { Persistence } from './Persistence';
+import { usePersistedState } from './usePersistedState';
+
+// jsdom only has fake-indexeddb, an imitation; this goes through the browser's own.
+
+afterEach(cleanup);
+
+function Tab() {
+  const [tab, setTab] = usePersistedState('tab', 'shape');
+  return (
+    <p>
+      <output aria-label="tab">{tab}</output>
+      <button type="button" onClick={() => setTab('color')}>
+        choose color
+      </button>
+    </p>
+  );
+}
+
+const mount = (storage: ReturnType<typeof createIndexedDbAdapter>) =>
+  render(
+    <Persistence storageKey="test" storage={storage} fallback={<p>loading</p>}>
+      <Tab />
+    </Persistence>,
+  );
+
+test('a value survives a remount through real IndexedDB', async () => {
+  const database = `labkit-browser-test-${Date.now()}`;
+
+  const first = mount(createIndexedDbAdapter({ database }));
+  await waitFor(() => expect(screen.getByLabelText('tab').textContent).toBe('shape'));
+  fireEvent.click(screen.getByText('choose color'));
+  await waitFor(() => expect(screen.getByLabelText('tab').textContent).toBe('color'));
+
+  // Unmounting closes the provider, whose deferred close sends the queued write.
+  first.unmount();
+  await new Promise((r) => setTimeout(r, 100));
+
+  // A fresh adapter, so nothing it reads can come from the first one's memory.
+  mount(createIndexedDbAdapter({ database }));
+  await waitFor(() => expect(screen.getByLabelText('tab').textContent).toBe('color'), {
+    timeout: 3000,
+  });
+});

package/src/state/store.test.ts

@@ -420,7 +420,11 @@ describe('setInstruments', () => {
     store.getState().addTrial(mappedTrial);
     store.getState().setInstruments([{ ...small, name: 'Mapped' }]);
     store.getState().saveSnapshot('m', 'one');
-    expect(store.getState().savedSnapshots[0]?.state).toEqual({ seen: new Set(['a']) });
+    // By tag, not `toEqual(new Set(…))`: under jsdom structuredClone hands back Node's Set.
+    const seen = (store.getState().savedSnapshots[0]?.state as { seen: Set<string> } | undefined)
+      ?.seen;
+    expect(Object.prototype.toString.call(seen)).toBe('[object Set]');
+    expect([...seen!]).toEqual(['a']);
   });
 
   it('changes neither hooks nor state when a new default config throws', () => {

package/src/state/undock.ts

@@ -8,10 +8,13 @@ export interface UndockedPanel {
 /** Undocked panels, keyed by {@link panelKey}. */
 export type UndockedPanels = Record<string, UndockedPanel>;
 
+/** The `UndockedPanels` key for one trial's section. */
 export function panelKey(trialId: string, sectionId: string): string {
   return `${trialId}::${sectionId}`;
 }
 
+/** `panels` with the section marked undocked `as` a tile or a floating panel,
+ *  replacing any earlier entry for it. Returns a new record. */
 export function undockPanel(
   panels: UndockedPanels,
   trialId: string,