@weasel-js/labkit 1.4.4 → 1.5.1

package/src/config/types.ts

@@ -1,4 +1,10 @@
-import type { PrefGroup, PrefLeaf, PrefRenderer } from '@weasel-js/ui';
+import type {
+  PrefGroup,
+  PrefLeaf,
+  PrefNumberFormat,
+  PrefNumberUnit,
+  PrefRenderer,
+} from '@weasel-js/ui';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -25,6 +31,13 @@ export interface Annotations {
   max?: number;
   step?: number;
   suffix?: string;
+  /** How a number's value is shown. `compact` abbreviates from a thousand up. */
+  format?: PrefNumberFormat;
+  /** Display-unit conversion for a number stored in a canonical unit — the
+   *  value, its bounds and its step all convert at the control's edge. */
+  unit?: PrefNumberUnit;
+  /** A color leaf's value carries alpha (`#rrggbbaa`) and its row edits it. */
+  alpha?: boolean;
   control?: string;
   options?: readonly ConfigOption[];
   placeholder?: string;
@@ -74,6 +87,10 @@ export interface SectionSpec {
    *  whether or not it was given a panel-wide `collapse`; a fold the reader
    *  has since toggled outranks it. */
   collapsed?: boolean;
+  /** Where the section's rows put their labels, over the panel's `layout`. */
+  layout?: 'block' | 'inline';
+  /** How the section packs its rows, over the panel's `pack`. */
+  pack?: 'auto' | 'pairs' | 'one-up';
 }
 
 /** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
@@ -95,12 +112,27 @@ export interface ResolvedConfig {
 export interface SectionOption {
   label: string;
   collapsed?: boolean;
+  /** Where the section's rows put their labels, over the panel's `layout`. */
+  layout?: 'block' | 'inline';
+  /** How the section packs its rows, over the panel's `pack`. */
+  pack?: 'auto' | 'pairs' | 'one-up';
 }
 
 /** Per-node extras that do not belong on a `PrefLeaf`. */
 export interface NodeOptions extends BranchOptions {
   render?: ControlRenderer;
-  validate?: (leaf: PrefLeaf) => string[];
+  /** 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 lets
+   *  the ghosted control draw a real value and keeps the instrument off
+   *  `?? compute()`. */
+  autoResolve?: (config: Record<string, unknown>) => unknown;
+  /** The leaf starts auto rather than pinned at its default. Set by
+   *  `.initial(auto)`. */
+  unpinned?: boolean;
+  /** The leaf can never be auto: the row takes no pin dot and ignores the
+   *  gesture. For a value the instrument cannot receive as `undefined`. */
+  manual?: boolean;
 }
 
 /** What a branch can say about itself, beyond its children. */

package/src/config/useResolvedConfig.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import { resolveAutoConfig } from './autoConfig';
+import type { ResolvedConfig } from './types';
+
+const NONE: ReadonlySet<string> = new Set();
+
+/**
+ * The config an instrument reads: the stored one with every unpinned path
+ * resolved. The single place resolution happens, so `Trial` and
+ * `useTrialState` cannot disagree about what an instrument is looking at.
+ */
+export function useResolvedConfig<TC>(
+  schema: ResolvedConfig | undefined,
+  config: TC,
+  autoPaths: readonly string[] | undefined,
+): { config: TC; auto: ReadonlySet<string> } {
+  const auto = useMemo(
+    () => (autoPaths && autoPaths.length > 0 ? new Set(autoPaths) : NONE),
+    [autoPaths],
+  );
+  const resolvedConfig = useMemo(
+    () => (schema ? resolveAutoConfig(schema, config, auto) : config),
+    [schema, config, auto],
+  );
+  return { config: resolvedConfig, auto };
+}

package/src/controls/AutoControls.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { useState } from 'react';
+import { applyConfigWrite } from '../config/autoConfig';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
+import { ControlPanel } from './ControlPanel';
+
+/**
+ * The ghosting and the muted accent are CSS, and jsdom resolves neither
+ * `var()` nor `color-mix()`. This story is the only place they can be checked.
+ */
+const meta: Meta<typeof ControlPanel> = {
+  title: 'labkit/Controls/AutoControls',
+  component: ControlPanel,
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof ControlPanel>;
+
+const schema = f.schema({
+  width: f.number(432).range(64, 1024).label('Width'),
+  gap: f
+    .number(12)
+    .range(0, 48)
+    .suffix('px')
+    .auto((c) => Math.round((c.width as number) / 24))
+    .label('Gap'),
+  cols: f.number(3).range(1, 12).label('Columns'),
+  wave: f.enum('sine', ['sine', 'square', 'triangle']).label('Wave'),
+  mode: f.enum('fit', ['fit', 'fill']).radio().label('Mode'),
+  showGrid: f.boolean(true).label('Show grid'),
+  title: f.string('My experiment').placeholder('Title…').label('Title'),
+  tint: f.color('#3a86ff').label('Tint'),
+  seed: f.number(1).range(0, 99).manual().label('Seed'),
+});
+
+const resolved = resolveConfigSchema(schema, []);
+
+/** Every path the panel will draw ghosted, except the `.manual()` one. */
+const EVERY_AUTO = ['gap', 'cols', 'wave', 'mode', 'showGrid', 'title', 'tint'];
+
+function Panel({ start }: { start: readonly string[] }) {
+  const [state, setState] = useState(() => ({
+    config: schema.defaults() as Record<string, unknown>,
+    autoPaths: start,
+  }));
+  return (
+    <ControlPanel
+      schema={resolved}
+      config={state.config}
+      auto={new Set(state.autoPaths)}
+      setConfig={(path, value) =>
+        setState((prev) => applyConfigWrite(prev.config, prev.autoPaths, path, value))
+      }
+    />
+  );
+}
+
+function Pair() {
+  return (
+    <div style={{ display: 'flex', gap: 32, alignItems: 'flex-start' }}>
+      <div style={{ flex: '1 1 0', minWidth: 0 }}>
+        <h3>Pinned</h3>
+        <Panel start={[]} />
+      </div>
+      <div style={{ flex: '1 1 0', minWidth: 0 }}>
+        <h3>Auto</h3>
+        <Panel start={EVERY_AUTO} />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Both states of every row kind, side by side. What to look at: an auto row's
+ * control keeps no accent color, its readout reads `auto · 18 px` rather than a
+ * number, and the pin dot appears only under the pointer — except on an auto
+ * row, where it stays. `Seed` is `.manual()` and takes no dot at all.
+ */
+export const BothStates: Story = {
+  render: () => <Pair />,
+};
+
+/** One panel to shift-click around in: the handle must not move as it toggles. */
+export const Interactive: Story = {
+  render: () => <Panel start={['gap']} />,
+};

package/src/controls/ControlPanel.stories.tsx

@@ -1,4 +1,5 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ANGLE_RADIANS, prefUnit } from '@weasel-js/core';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
 import { f } from '../config/builder';
@@ -234,3 +235,43 @@ export const Nested: Story = {
     );
   },
 };
+
+const degrees = prefUnit(ANGLE_RADIANS, 'deg', { precision: 1 });
+
+const presentation = f.schema({
+  x: f.number(120).label('X').pair('Offset'),
+  y: f.number(-40).label('Y').pair('Offset'),
+  spin: f
+    .number(Math.PI / 4)
+    .range(0, Math.PI * 2)
+    .unit(degrees)
+    .label('Rotation'),
+  nudge: f
+    .number(Math.PI / 180)
+    .input()
+    .unit(degrees)
+    .label('Nudge'),
+  tint: f.color('#3a86ffcc').alpha().label('Tint'),
+  opaque: f.color('#3a86ff').label('Grid'),
+});
+
+/** The three presentation fields a leaf can declare: `pair` puts `X` and `Y`
+ *  on one row the pair names, `unit` stores radians and edits degrees, and
+ *  `alpha` gives the swatch an opacity track and stores `#rrggbbaa`. The dump
+ *  shows what each control actually wrote. */
+export const Presentation: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(presentation, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(presentation.defaults());
+    return (
+      <>
+        <ControlPanel
+          schema={schema}
+          config={config}
+          setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
+        />
+        <pre>{JSON.stringify(config, null, 2)}</pre>
+      </>
+    );
+  },
+};