@weasel-js/labkit 1.6.0 → 1.7.0

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="mine" rows={[]} />);
+    expect(must(container.firstElementChild).className).toMatch(/\blk-readout\b.*\bmine\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/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 },
@@ -468,7 +468,15 @@ function PanelsAndRows() {
               onAlphaChange={setAlpha}
             />
             <PropertyField kind="color" label="Stroke" value={stroke} onChange={setStroke} />
-            <PropertyField kind="number" label="Count" value={count} min={0} max={100} step={1} onChange={setCount} />
+            <PropertyField
+              kind="number"
+              label="Count"
+              value={count}
+              min={0}
+              max={100}
+              step={1}
+              onChange={setCount}
+            />
             <PropertyField
               kind="enum"
               label="Line cap"
@@ -494,7 +502,16 @@ function PanelsAndRows() {
             <PropertyField kind="string" label="Label" value={label} onChange={setLabel} />
             <PropertyField kind="boolean" label="Visible" value={visible} onChange={setVisible} />
             <PropertyGroup title="Bevel" defaultCollapsed>
-              <PropertyField kind="number" control="slider" label="Rings" value={32} min={4} max={96} step={1} onChange={() => {}} />
+              <PropertyField
+                kind="number"
+                control="slider"
+                label="Rings"
+                value={32}
+                min={4}
+                max={96}
+                step={1}
+                onChange={() => {}}
+              />
             </PropertyGroup>
           </PropertyList>
         </PropertyPanel>

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/labRecords.test.ts

@@ -96,7 +96,10 @@ describe('documents and records', () => {
       ['trial:z', { instrumentName: 'T', order: 0 }],
       ['trial:m', { instrumentName: 'T', order: 0 }],
     ]);
-    expect((joined?.doc.trials as { id: string }[]).map((t) => t.id)).toEqual(['m', 'z']);
+    expect((joined?.doc.trials as { id: string }[] | undefined)?.map((t) => t.id)).toEqual([
+      'm',
+      'z',
+    ]);
   });
 
   it('is null without a meta record', () => {

package/src/state/store.test.ts

@@ -84,7 +84,7 @@ describe('updateTrialState', () => {
     s.getState().updateTrialState('w1', (prev: unknown) => ({
       n: (prev as { n: number }).n + 1,
     }));
-    expect((s.getState().trials[0]?.state as { n: number }).n).toBe(2);
+    expect((s.getState().trials[0]?.state as { n: number } | undefined)?.n).toBe(2);
   });
 });
 
@@ -99,8 +99,8 @@ describe('updateTrialConfig', () => {
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
     s.getState().updateTrialConfig('w1', 'x', 99);
-    expect((s.getState().trials[0]?.config as { x: number }).x).toBe(99);
-    expect((s.getState().trials[0]?.config as { y: number }).y).toBe(2);
+    expect((s.getState().trials[0]?.config as { x: number } | undefined)?.x).toBe(99);
+    expect((s.getState().trials[0]?.config as { y: number } | undefined)?.y).toBe(2);
   });
 
   it('writes down a dotted path without disturbing its siblings', () => {
@@ -161,7 +161,7 @@ describe('save/load/delete snapshots', () => {
     s.getState().updateTrialState('w1', { n: 99 });
     const snapId = s.getState().savedSnapshots[0]?.id ?? '';
     s.getState().loadSnapshot(snapId, 'w1');
-    expect((s.getState().trials[0]?.state as { n: number }).n).toBe(5);
+    expect((s.getState().trials[0]?.state as { n: number } | undefined)?.n).toBe(5);
   });
 
   it('loadSnapshot restores the auto paths the trial had when saved', () => {
@@ -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/usePersistedState.test.tsx

@@ -109,7 +109,7 @@ describe('usePersistedState', () => {
     );
     await screen.findByLabelText('a');
     act(() => screen.getByText('set a').click());
-    expect(shown('b')).toBe('color');
+    await waitFor(() => expect(shown('b')).toBe('color'));
   });
 
   it("re-renders with another tab's write", async () => {

package/src/state/useTrialState.test.tsx

@@ -173,7 +173,7 @@ describe('auto paths', () => {
     store.getState().updateTrialConfig('w1', 'gap', 30);
     const rec = store.getState().trials[0];
     expect(rec?.auto).toBeUndefined();
-    expect((rec?.config as { gap: number }).gap).toBe(30);
+    expect((rec?.config as { gap: number } | undefined)?.gap).toBe(30);
   });
 
   it('does not allocate a new record when the path is already auto', () => {

package/src/styles.less

@@ -14,6 +14,7 @@
 @import './primitives/FpsMeter.less';
 @import './primitives/ScaleIndicator.less';
 @import './primitives/Legend.less';
+@import './primitives/Readout.less';
 @import './primitives/FloatingPanel.less';
 @import './lab/Lab.less';
 @import './trial/Trial.less';
@@ -23,6 +24,8 @@
 @import './controls/ControlPanel.less';
 @import './canvas/CanvasStack.less';
 @import './canvas/Stage.less';
+@import './canvas/LinkedCursor.less';
+@import './overview/TrialOverview.less';
 @import './loupe/Loupe.less';
 @import './annotations/Annotations.less';
 @import './dragdrop/Palette.less';

package/src/theme/Interstellar.stories.tsx

@@ -1,15 +1,13 @@
 import type { Meta, StoryObj } from '@weasel-js/forge';
 import type { TokenName } from '@weasel-js/theme';
 import { useTheme } from '@weasel-js/theme/react';
-import {
-  PropertyField,
-  PropertyList,
-  PropertyPanel,
-} from '@weasel-js/ui';
+import { PropertyField, PropertyList, PropertyPanel } from '@weasel-js/ui';
 import './Interstellar.stories.less';
+import { decimal } from '@weasel-js/quantity';
 
 const meta: Meta = {
   title: 'labkit/Themes/Interstellar',
+  tags: ['gallery'],
   parameters: {
     docs: {
       description: {
@@ -154,7 +152,7 @@ function LivePanelPreview() {
             max={1}
             step={0.01}
             onChange={() => {}}
-            format={(v) => v.toFixed(2)}
+            display={decimal({ places: 2 })}
           />
           <PropertyField kind="color" label="Fill" value="#b08adb" onChange={() => {}} />
           <PropertyField kind="color" label="Stroke" value="#1a1428" onChange={() => {}} />