@weasel-js/labkit 1.5.2 → 1.6.1

package/src/config/sectionTree.test.ts

@@ -0,0 +1,152 @@
+import { isPrefLeaf, type PrefGroup } from '@weasel-js/ui';
+import { describe, expect, it } from 'vitest';
+import { f } from './builder';
+import { resolveConfigSchema } from './resolve';
+import { sectionTree } from './sectionTree';
+
+const groupAt = (g: PrefGroup, key: string) => {
+  const child = g.children[key];
+  if (!child || isPrefLeaf(child)) throw new Error(`${key} is not a group`);
+  return child;
+};
+
+describe('sectionTree', () => {
+  it('makes each root section a top-level group, in schema order', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        lift: f.number(1).section('View'),
+        beat: f.number(2).section('Playback'),
+        spread: f.number(3).section('View'),
+      }),
+    );
+    const { group } = sectionTree(resolved, { lift: 1, beat: 2, spread: 3 });
+    expect(Object.keys(group.children)).toEqual(['view', 'playback']);
+    expect(groupAt(group, 'view').name).toBe('View');
+    expect(Object.keys(groupAt(group, 'view').children)).toEqual(['lift', 'spread']);
+    expect(Object.keys(groupAt(group, 'playback').children)).toEqual(['beat']);
+  });
+
+  it('brings a group a section names in whole, so the rail can indent it', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        cards: f
+          .group({ floor: f.number(1), cap: f.number(2) })
+          .section('View')
+          .label('Cards'),
+      }),
+    );
+    const { group } = sectionTree(resolved, { cards: { floor: 1, cap: 2 } });
+    const cards = groupAt(groupAt(group, 'view'), 'cards');
+    expect(cards.name).toBe('Cards');
+    expect(Object.keys(cards.children)).toEqual(['floor', 'cap']);
+  });
+
+  it('renests the config to mirror the tree', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        cards: f.group({ floor: f.number(1) }).section('View'),
+        beat: f.number(2).section('Playback'),
+      }),
+    );
+    const { values } = sectionTree(resolved, { cards: { floor: 7 }, beat: 9 });
+    expect(values).toEqual({ view: { cards: { floor: 7 } }, playback: { beat: 9 } });
+  });
+
+  it('cuts what showIf rules out, at any depth', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        lineNumbers: f.boolean(true).section('View'),
+        listing: f
+          .group({
+            dim: f.number(1).showIf((c) => c.lineNumbers === true),
+            weight: f.number(0),
+          })
+          .section('View'),
+      }),
+    );
+    const on = sectionTree(resolved, { lineNumbers: true, listing: { dim: 1, weight: 0 } });
+    expect(Object.keys(groupAt(groupAt(on.group, 'view'), 'listing').children)).toEqual([
+      'dim',
+      'weight',
+    ]);
+    const off = sectionTree(resolved, { lineNumbers: false, listing: { dim: 1, weight: 0 } });
+    expect(Object.keys(groupAt(groupAt(off.group, 'view'), 'listing').children)).toEqual([
+      'weight',
+    ]);
+  });
+
+  it('drops a section nothing in it is showing, rather than opening it onto nothing', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        mode: f.enum<string>('a', ['a', 'b']).section('View'),
+        glow: f
+          .number(1)
+          .section('Diff')
+          .showIf((c) => c.mode === 'b'),
+      }),
+    );
+    expect(Object.keys(sectionTree(resolved, { mode: 'b', glow: 1 }).group.children)).toEqual([
+      'view',
+      'diff',
+    ]);
+    expect(Object.keys(sectionTree(resolved, { mode: 'a', glow: 1 }).group.children)).toEqual([
+      'view',
+    ]);
+  });
+
+  it('keeps a hidden leaf out unless asked for it', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        seed: f.number(1).hidden().section('Debug'),
+        route: f.boolean(true).section('Debug'),
+      }),
+    );
+    expect(Object.keys(groupAt(sectionTree(resolved, {}).group, 'debug').children)).toEqual([
+      'route',
+    ]);
+    expect(Object.keys(groupAt(sectionTree(resolved, {}, true).group, 'debug').children)).toEqual([
+      'seed',
+      'route',
+    ]);
+  });
+
+  it('leaves a node no section claimed at the top level', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({ lift: f.number(1).section('View'), loose: f.number(2) }),
+    );
+    const { group, values } = sectionTree(resolved, { lift: 1, loose: 2 });
+    expect(Object.keys(group.children)).toEqual(['view', 'loose']);
+    expect(values.loose).toBe(2);
+  });
+
+  it('pathAt gives back the config path a rail path stands for', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        cards: f.group({ floor: f.number(1) }).section('View'),
+        loose: f.number(2),
+      }),
+    );
+    const { pathAt } = sectionTree(resolved, { cards: { floor: 1 }, loose: 2 });
+    expect(pathAt('view.cards.floor')).toBe('cards.floor');
+    expect(pathAt('loose')).toBe('loose');
+  });
+
+  it('keys two sections whose labels slug the same apart', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({ a: f.number(1).section('Hold on'), b: f.number(2).section('Hold-on') }),
+    );
+    const { group } = sectionTree(resolved, { a: 1, b: 2 });
+    expect(Object.keys(group.children)).toEqual(['hold-on', 'hold-on-2']);
+  });
+
+  it('ignores a section nested under a group, which buckets rows in a pane', () => {
+    const resolved = resolveConfigSchema(
+      f.schema({
+        cards: f.group({ floor: f.number(1).section('Size') }).section('View'),
+      }),
+    );
+    const { group } = sectionTree(resolved, { cards: { floor: 1 } });
+    expect(Object.keys(group.children)).toEqual(['view']);
+    expect(Object.keys(groupAt(groupAt(group, 'view'), 'cards').children)).toEqual(['floor']);
+  });
+});

package/src/config/sectionTree.ts

@@ -0,0 +1,134 @@
+import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
+import { valueAtPath } from './path';
+import type { ResolvedConfig } from './types';
+import { isLeafVisible } from './visible';
+
+/**
+ * A resolved schema rearranged so its sections are groups.
+ *
+ * `PrefsForm`'s rail navigates the schema tree — top-level groups are its
+ * items, their group children indent under them. A resolved schema keeps its
+ * sections beside the tree instead, so a flat schema's rail comes out as one
+ * unnamed item however many headings the panel draws. This puts the sections
+ * where the rail looks for them.
+ */
+export interface SectionTree {
+  /** The rail's schema. Top-level children are the schema's root sections,
+   *  followed by any root node no section claimed. */
+  group: PrefGroup;
+  /** `config` renested to mirror `group` — the value tree `PrefsForm` takes. */
+  values: Record<string, unknown>;
+  /** The config path a path within `group` stands for. */
+  pathAt: (railPath: string) => string;
+}
+
+/** Structural rather than `isPrefLeaf`, so the config entry stays free of a
+ *  runtime import from ui. */
+function isLeaf(node: PrefLeaf | PrefGroup): node is PrefLeaf {
+  return 'kind' in node;
+}
+
+/** A section label as an object key: no dots, since a dotted path is how every
+ *  caller addresses a node, and a label is free to hold one. */
+function slugOf(label: string, taken: ReadonlySet<string>): string {
+  const base =
+    label
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '') || 'section';
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n += 1) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`;
+}
+
+/** A subtree with everything `showIf` or `hidden` rules out cut away, or null
+ *  when that is all of it. A group whose children all went is not a rail item
+ *  the reader can open onto nothing. */
+function prune(
+  resolved: ResolvedConfig,
+  group: PrefGroup,
+  at: string,
+  config: Record<string, unknown>,
+  showHidden: boolean,
+): PrefGroup | null {
+  const children: PrefGroup['children'] = {};
+  for (const [key, child] of Object.entries(group.children)) {
+    const path = at === '' ? key : `${at}.${key}`;
+    if (!isLeafVisible(resolved, path, config, showHidden)) continue;
+    if (isLeaf(child)) {
+      children[key] = child;
+      continue;
+    }
+    const kept = prune(resolved, child, path, config, showHidden);
+    if (kept) children[key] = kept;
+  }
+  return Object.keys(children).length === 0 ? null : { ...group, children };
+}
+
+/**
+ * Turn a resolved schema's root sections into the top level of a `PrefGroup`,
+ * for `PrefsForm`'s rail layout.
+ *
+ * A section naming a group brings that group in whole, so it lands as an
+ * indented rail item; a section naming a leaf drops it loose into the
+ * section's own pane. Sections nested under a group are left alone — they
+ * bucket rows inside a pane, which is the panel's job and not the rail's.
+ */
+export function sectionTree(
+  resolved: ResolvedConfig,
+  config: Record<string, unknown>,
+  showHidden = false,
+): SectionTree {
+  const children: PrefGroup['children'] = {};
+  const values: Record<string, unknown> = {};
+  const slugs = new Set<string>();
+  const claimed = new Set<string>();
+
+  for (const section of resolved.sections) {
+    if (section.at !== '') continue;
+    const kept: PrefGroup['children'] = {};
+    const held: Record<string, unknown> = {};
+    for (const path of section.paths) {
+      claimed.add(path);
+      const child = resolved.group.children[path];
+      if (!child || !isLeafVisible(resolved, path, config, showHidden)) continue;
+      if (isLeaf(child)) {
+        kept[path] = child;
+      } else {
+        const subtree = prune(resolved, child, path, config, showHidden);
+        if (!subtree) continue;
+        kept[path] = subtree;
+      }
+      held[path] = valueAtPath(config, path);
+    }
+    if (Object.keys(kept).length === 0) continue;
+    const slug = slugOf(section.label, slugs);
+    slugs.add(slug);
+    children[slug] = { name: section.label, children: kept };
+    values[slug] = held;
+  }
+
+  // Whatever no section claimed stays at the top level, where `prefRailItems`
+  // gathers loose leaves into one item named for the root.
+  for (const [key, child] of Object.entries(resolved.group.children)) {
+    if (claimed.has(key) || !isLeafVisible(resolved, key, config, showHidden)) continue;
+    if (isLeaf(child)) {
+      children[key] = child;
+    } else {
+      const subtree = prune(resolved, child, key, config, showHidden);
+      if (!subtree) continue;
+      children[key] = subtree;
+    }
+    values[key] = valueAtPath(config, key);
+  }
+
+  return {
+    group: { name: resolved.group.name, children },
+    values,
+    pathAt: (railPath) => {
+      const cut = railPath.indexOf('.');
+      const head = cut === -1 ? railPath : railPath.slice(0, cut);
+      if (!slugs.has(head)) return railPath;
+      return cut === -1 ? '' : railPath.slice(cut + 1);
+    },
+  };
+}

package/src/config/types.ts

@@ -5,6 +5,7 @@ import type {
   PrefNumberUnit,
   PrefRenderer,
 } from '@weasel-js/ui';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -104,6 +105,23 @@ export interface ResolvedConfig {
   showIf: ReadonlyMap<string, (config: Record<string, unknown>) => boolean>;
   /** Node-level `.render` overrides, keyed by path. */
   renderers: Readonly<Record<string, ControlRenderer>>;
+  /** Node-level `.dialog` rows, keyed by path. */
+  dialogs: Readonly<Record<string, DialogSpec>>;
+}
+
+/** Options for a row drawn as a button that opens a dialog. */
+export interface InDialogOptions {
+  /** What the row's button shows of the value. Defaults to a list joined with
+   *  commas, or the value itself. */
+  summary?: (value: unknown) => ReactNode;
+  /** The dialog's heading. Defaults to the row's label. */
+  title?: ReactNode;
+}
+
+/** A `.dialog` row: `body` is the dialog's content, handed the context a row
+ *  renderer gets. */
+export interface DialogSpec extends InDialogOptions {
+  body: ControlRenderer;
 }
 
 /** How a node names the section it belongs to: the heading, and how that
@@ -121,6 +139,9 @@ export interface SectionOption {
 /** Per-node extras that do not belong on a `PrefLeaf`. */
 export interface NodeOptions extends BranchOptions {
   render?: ControlRenderer;
+  /** Draw the row as a button that opens a dialog. Set by `.dialog`; the
+   *  config entry records it, and `ControlPanel` draws it. */
+  dialog?: DialogSpec;
   /** Errors for this leaf under `config`, the instrument's whole config. */
   validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[];
   /** Computes this leaf's value while it is auto. Attaching one is what gives

package/src/controls/ControlPanel.less

@@ -2,8 +2,12 @@
 // from PropertyPanel.less. This class remains as the consumer-facing hook.
 // It carries no padding: whatever mounts the panel insets it, and a second
 // inset here doubled the gutter inside an already narrow sidebar.
+// A select row aligns to its value's baseline by default, which sits a label
+// lower than the centered rows around it — here those neighbors are sliders and
+// checkboxes, so a column of labels stepped at every dropdown.
 .lk-control-panel {
   padding: 0;
+  --wzl-prop-row-align-text: center;
 }
 
 // A cell in a paired row, with the caption naming the knob it holds. Case,

package/src/controls/ControlPanel.stories.tsx

@@ -1,6 +1,6 @@
 import { ANGLE_RADIANS, prefUnit } from '@weasel-js/core';
 import type { Meta, StoryObj } from '@weasel-js/forge';
-import { PropertyRow } from '@weasel-js/ui';
+import { type PrefNumberUnit, PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
 import { f } from '../config/builder';
 import { withValueAtPath } from '../config/path';
@@ -285,7 +285,9 @@ const inline = f.schema({
   lift: f.number(0.2).range(0, 1).step(0.05),
   opacity: f.number(0.45).range(0, 1).step(0.05),
   iconSet: f.enum('small', ['small', 'large']).label('Icon set'),
-  drawAsIcons: f.string('**/node_modules/**').label('Draw as icons'),
+  drawAsIcons: f
+    .list(['**/node_modules/**', '**/dist/**', 'package-lock.json'])
+    .label('Draw as icons'),
   detail: f.number(1200).range(0, 4000).suffix('nodes'),
   showCameraRoute: f.boolean(false).toggle().label('Show camera route'),
   routeColor: f.enum('sweep', ['sweep', 'depth']).label('Route color'),
@@ -316,3 +318,54 @@ export const Inline: Story = {
     );
   },
 };
+
+const shownIn = (suffix: string): PrefNumberUnit => ({
+  toDisplay: (v) => v,
+  fromDisplay: (v) => v,
+  suffix,
+});
+
+/** Every slider in astv's right sidebar, for sizing readouts against real ranges, steps and units. */
+const sidebarSliders = f.schema({
+  aimNoise: f.number(0).range(0, 0.6).step(0.02).label('Aim noise'),
+  transition: f.number(600).range(0, 1200).step(50).unit(shownIn('ms')).label('Transition'),
+  sweep: f.number(12).range(0, 40).step(0.5).label('Text motion'),
+  beat: f.number(1600).range(400, 6000).step(100).unit(shownIn('ms')).label('Beat'),
+  tourSeed: f.number(1).range(1, 99).step(1).label('Tour seed'),
+  hold: f.number(1200).range(0, 4000).step(10).unit(shownIn('ms')).label('Demo hold'),
+  scrollRows: f.number(3).range(1, 12).step(1).label('Lines'),
+  pad: f.number(0.5).range(0, 4).step(0.25).label('Window pad'),
+  folderPad: f.number(1).range(0, 4).step(0.1).label('Folder pad'),
+  levels: f.number(2).range(0, 6).step(1).label('Levels'),
+  glyphs: f.number(1_000_000).range(0, 2_000_000).step(2000).format('compact').label('Glyphs'),
+  names: f.number(40).range(0, 200).step(5).label('Names'),
+  labels: f.number(0).range(0, 30).step(1).label('Labels'),
+  text: f.number(100).range(50, 250).step(5).unit(shownIn('%')).label('Text'),
+  lift: f.number(0.8).range(0, 4).step(0.1).label('Lift'),
+  opacity: f.number(0.6).range(0.1, 1).step(0.05).label('Opacity'),
+  detail: f.number(300).range(20, 4000).step(20).label('Nodes'),
+  reachStep: f.number(600).range(200, 2000).step(100).unit(shownIn('ms')).label('Reach step'),
+  width: f.number(2).range(1, 24).step(0.5).unit(shownIn('px')).label('Width'),
+  minimapSize: f.number(280).range(120, 600).step(20).label('Minimap size'),
+});
+
+/** astv's sidebar sliders paired two to a row, at the narrowest width a two-up sidebar should support:
+ *  300px at compact and comfortable. Roomy needs 352px; at 300 its longest labels push readouts out of the row. */
+export const SidebarSliders: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(sidebarSliders, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(sidebarSliders.defaults());
+    return (
+      <div style={{ width: 300 }}>
+        <ControlPanel
+          schema={schema}
+          config={config}
+          setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
+          layout="inline"
+          align="center"
+          pack="pairs"
+        />
+      </div>
+    );
+  },
+};

package/src/controls/ControlPanel.test.tsx

@@ -187,7 +187,11 @@ describe('<ControlPanel> schema', () => {
       [],
     );
     render(
-      <ControlPanel schema={schema} config={{ showGrid: true, snap: false }} setConfig={setConfig} />,
+      <ControlPanel
+        schema={schema}
+        config={{ showGrid: true, snap: false }}
+        setConfig={setConfig}
+      />,
     );
     expect(screen.getByRole('checkbox', { name: 'Show grid' })).toBeInTheDocument();
     const sw = screen.getByRole('switch', { name: 'Snap' });
@@ -368,6 +372,7 @@ describe('<ControlPanel> built-in kind coverage', () => {
     sections: [],
     showIf: new Map(),
     renderers: {},
+    dialogs: {},
   });
 
   it('declines paint and object with a named row rather than a blank one', () => {
@@ -478,7 +483,7 @@ describe('<ControlPanel> format', () => {
         setConfig={vi.fn()}
       />,
     );
-    expect(screen.getByDisplayValue('2.0M')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('2.00M')).toBeInTheDocument();
   });
 });
 
@@ -493,7 +498,9 @@ describe('<ControlPanel> group descriptions', () => {
       }),
       [],
     );
-    render(<ControlPanel schema={schema} config={{ grid: { cellSize: 20 } }} setConfig={vi.fn()} />);
+    render(
+      <ControlPanel schema={schema} config={{ grid: { cellSize: 20 } }} setConfig={vi.fn()} />,
+    );
     const note = screen.getByText('How the background lattice is spaced.');
     const field = screen.getByLabelText('Cell size');
     expect(note.compareDocumentPosition(field) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
@@ -1064,3 +1071,33 @@ describe('<ControlPanel> color alpha', () => {
     expect(screen.queryByLabelText('Tint opacity')).toBeNull();
   });
 });
+
+describe('<ControlPanel> title, stance and tone', () => {
+  const fields: ConfigField[] = [{ key: 'on', label: 'On', type: 'checkbox', default: true }];
+
+  it('renders the bare list when given none of them', () => {
+    const { container } = render(
+      <ControlPanel fields={fields} config={{ on: true }} setConfig={vi.fn()} />,
+    );
+    expect(container.firstElementChild?.classList.contains('lk-control-panel')).toBe(true);
+    expect(container.querySelector('[data-stance], h2')).toBeNull();
+  });
+
+  it('wraps its rows in a panel carrying them when asked', () => {
+    const { container } = render(
+      <ControlPanel
+        title="View"
+        stance="scope"
+        tone={1}
+        fields={fields}
+        config={{ on: true }}
+        setConfig={vi.fn()}
+      />,
+    );
+    const panel = container.firstElementChild as HTMLElement;
+    expect(panel.dataset.stance).toBe('scope');
+    expect(panel.dataset.tone).toBe('1');
+    expect(screen.getByRole('heading', { name: 'View' })).toBeTruthy();
+    expect(panel.querySelector('.lk-control-panel')).not.toBeNull();
+  });
+});