@weasel-js/labkit 1.4.4 → 1.5.1

package/src/chrome/regions/PaletteRegion.test.tsx

@@ -1,15 +1,17 @@
 import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { RegionContribution, ToolSlotContext } from '../types';
 import { PaletteRegion } from './PaletteRegion';
 
 const Glyph = () => <svg />;
 
-function ctxWith(activeToolId: string | null, setActiveTool = vi.fn()) {
-  return { trialId: 't1', activeToolId, setActiveTool } as unknown as TrialChromeContext;
+// The region reads a tool slot and nothing else, so the fixture is a real
+// `ToolSlotContext` rather than a faked trial.
+function ctxWith(activeToolId: string | null, setActiveTool = vi.fn()): ToolSlotContext {
+  return { activeToolId, setActiveTool };
 }
 
-function tool(id: string): TrialContribution {
+function tool(id: string): RegionContribution<ToolSlotContext> {
   return { id, region: 'palette', item: { icon: Glyph, label: id } };
 }
 

package/src/chrome/regions/PaletteRegion.tsx

@@ -1,16 +1,23 @@
 import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
 import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { RegionContribution, ToolItem, ToolSlotContext, TrialChromeContext } from '../types';
 
 /** Props for `<PaletteRegion>`. */
-export interface PaletteRegionProps {
-  contributions: readonly TrialContribution[];
-  ctx: TrialChromeContext;
+export interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeContext> {
+  contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+  ctx: TCtx;
+  /** Which region's items to lay out. The lab's rail names the same box
+   *  `palette` too, so this only moves for a chrome that does not. */
+  region?: string;
 }
 
-/** A trial's tool strip. Selection lives in the trial's or the lab's tool
- *  slot; this region only reflects it. */
-export function PaletteRegion({ contributions, ctx }: PaletteRegionProps) {
+/** A tool strip: a trial's, or the lab's. Selection lives in whichever tool
+ *  slot the context carries; this region only reflects it. */
+export function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>({
+  contributions,
+  ctx,
+  region = 'palette',
+}: PaletteRegionProps<TCtx>) {
   const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>('vertical');
   if (contributions.length === 0) return null;
   return (
@@ -25,8 +32,8 @@ export function PaletteRegion({ contributions, ctx }: PaletteRegionProps) {
       <ToolGroup orientation="vertical">
         {contributions.map((c) => {
           if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
-          if (c.region !== 'palette' || !c.item) return null;
-          const { icon: Icon, label, shortcut, disabled } = c.item;
+          if (c.region !== region || !c.item) return null;
+          const { icon: Icon, label, shortcut, disabled } = c.item as ToolItem;
           return (
             <ToolButton
               key={c.id}

package/src/chrome/regions/SidebarRegion.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { expect } from '@weasel-js/forge/play';
+import { LabRoot } from '../../lab/LabRoot';
+import type { SidebarSlotContext } from '../types';
+import { SidebarRegion } from './SidebarRegion';
+
+const meta: Meta<typeof SidebarRegion> = {
+  title: 'labkit/Chrome/SidebarRegion',
+  component: SidebarRegion,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof SidebarRegion>;
+
+const ctx: SidebarSlotContext = { collapsedSections: {}, setSectionCollapsed: () => {} };
+
+// jsdom has no layout, so this runs in the browser story projects.
+export const LastSectionFillsItsPane: Story = {
+  render: () => (
+    <LabRoot>
+      <div className="lk-lab__aside" data-testid="pane" style={{ height: 400 }}>
+        <SidebarRegion
+          ctx={ctx}
+          contributions={[
+            { id: 'first', region: 'sidebar', item: { title: 'First', body: <p>one</p> } },
+            { id: 'last', region: 'sidebar', item: { title: 'Last', body: <p>two</p> } },
+          ]}
+        />
+      </div>
+    </LabRoot>
+  ),
+  play: async ({ canvasElement }) => {
+    const pane = canvasElement.querySelector('[data-testid="pane"]') as HTMLElement;
+    const sections = [...pane.querySelectorAll<HTMLElement>('.lk-sidebar-section')];
+    const first = sections[0] as HTMLElement;
+    const last = sections[sections.length - 1] as HTMLElement;
+    await expect(Math.round(last.getBoundingClientRect().bottom)).toBe(
+      Math.round(pane.getBoundingClientRect().bottom),
+    );
+    await expect(getComputedStyle(last).borderBottomWidth).toBe('0px');
+    await expect(getComputedStyle(first).borderBottomWidth).not.toBe('0px');
+  },
+};

package/src/chrome/regions/SidebarRegion.tsx

@@ -1,10 +1,17 @@
 import type { ReactNode } from 'react';
-import type { SidebarSection, TrialChromeContext, TrialContribution } from '../types';
+import type {
+  RegionContribution,
+  SidebarSection,
+  SidebarSlotContext,
+  TrialChromeContext,
+} from '../types';
 
 /** Props for `<SidebarRegion>`. */
-export interface SidebarRegionProps {
-  contributions: readonly TrialContribution[];
-  ctx: TrialChromeContext;
+export interface SidebarRegionProps<TCtx extends SidebarSlotContext = TrialChromeContext> {
+  contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+  ctx: TCtx;
+  /** Which region's items to lay out. */
+  region?: string;
 }
 
 function Section({
@@ -48,17 +55,22 @@ function Section({
   );
 }
 
-/** Lays a trial's `sidebar` contributions out as titled, collapsible sections.
- *  A section the trial has torn out is not rendered here — `Trial` portals its
- *  body into the workspace instead. */
-export function SidebarRegion({ contributions, ctx }: SidebarRegionProps) {
+/** Lays `sidebar` contributions out as titled, collapsible sections — a
+ *  trial's, or the lab's. A section the trial has torn out is not rendered
+ *  here — `Trial` portals its body into the workspace instead. A context with
+ *  no `undockPanel` offers no tear-out. */
+export function SidebarRegion<TCtx extends SidebarSlotContext = TrialChromeContext>({
+  contributions,
+  ctx,
+  region = 'sidebar',
+}: SidebarRegionProps<TCtx>) {
   if (contributions.length === 0) return null;
   return (
     <>
       {contributions.map((c) => {
         if (c.render) return <div key={c.id}>{c.render(ctx)}</div>;
-        if (c.region !== 'sidebar' || !c.item) return null;
-        if (ctx.undockedPanels.includes(c.id)) return null;
+        if (c.region !== region || !c.item) return null;
+        if (ctx.undockedPanels?.includes(c.id)) return null;
         const item = c.item as SidebarSection;
         return (
           <Section
@@ -67,9 +79,9 @@ export function SidebarRegion({ contributions, ctx }: SidebarRegionProps) {
             collapsed={ctx.collapsedSections[c.id] ?? item.defaultCollapsed ?? false}
             onCollapsedChange={(next) => ctx.setSectionCollapsed(c.id, next)}
             onUndock={
-              item.undockable === false
-                ? undefined
-                : () => ctx.undockPanel(c.id, item.undockAs ?? 'tile')
+              ctx.undockPanel && item.undockable !== false
+                ? () => ctx.undockPanel?.(c.id, item.undockAs ?? 'tile')
+                : undefined
             }
           >
             {item.body}

package/src/chrome/regions/StatusRegion.tsx

@@ -1,14 +1,20 @@
 import { StatusBar } from '../../primitives/StatusBar';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { RegionContribution, StatusReadout, TrialChromeContext } from '../types';
 
 /** Props for `<StatusRegion>`. */
-export interface StatusRegionProps {
-  contributions: readonly TrialContribution[];
-  ctx: TrialChromeContext;
+export interface StatusRegionProps<TCtx = TrialChromeContext> {
+  contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+  ctx: TCtx;
+  /** Which region's readouts to lay out; the lab's footer is `footer`. */
+  region?: string;
 }
 
-/** Lays a trial's `status` contributions out as readouts. */
-export function StatusRegion({ contributions, ctx }: StatusRegionProps) {
+/** Lays a bar's readouts out. */
+export function StatusRegion<TCtx = TrialChromeContext>({
+  contributions,
+  ctx,
+  region = 'status',
+}: StatusRegionProps<TCtx>) {
   if (contributions.length === 0) return null;
   return (
     <StatusBar>
@@ -19,10 +25,11 @@ export function StatusRegion({ contributions, ctx }: StatusRegionProps) {
               {c.render(ctx)}
             </StatusBar.Section>
           );
-        if (c.region !== 'status' || !c.item) return null;
+        if (c.region !== region || !c.item) return null;
+        const item = c.item as StatusReadout;
         return (
           <StatusBar.Section key={c.id} end={c.end}>
-            <span title={c.item.title}>{c.item.text}</span>
+            <span title={item.title}>{item.text}</span>
           </StatusBar.Section>
         );
       })}

package/src/chrome/regions/ToolbarRegion.tsx

@@ -1,24 +1,28 @@
 import type { ReactNode } from 'react';
 import { Toolbar } from '../../primitives/Toolbar';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { RegionContribution, ToolbarItem, TrialChromeContext } from '../types';
 
 /** Props for `<ToolbarRegion>`. */
-export interface ToolbarRegionProps {
-  contributions: readonly TrialContribution[];
-  ctx: TrialChromeContext;
+export interface ToolbarRegionProps<TCtx = TrialChromeContext> {
+  contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+  ctx: TCtx;
+  /** Which region's items to lay out; the lab's action bar is `header`. */
+  region?: string;
+  /** The bar's accessible name. */
+  label?: string;
 }
 
-interface Group {
+interface Group<TCtx> {
   key: string;
   end: boolean;
-  entries: TrialContribution[];
+  entries: RegionContribution<TCtx>[];
 }
 
 /** Bucket by group, preserving first-appearance order. Ungrouped
  *  contributions each become their own bucket so they stay in place. */
-function groupsOf(contributions: readonly TrialContribution[]): Group[] {
-  const groups: Group[] = [];
-  const byKey = new Map<string, Group>();
+function groupsOf<TCtx>(contributions: readonly RegionContribution<TCtx>[]): Group<TCtx>[] {
+  const groups: Group<TCtx>[] = [];
+  const byKey = new Map<string, Group<TCtx>>();
   for (const c of contributions) {
     if (c.group == null) {
       groups.push({ key: c.id, end: c.end ?? false, entries: [c] });
@@ -35,10 +39,19 @@ function groupsOf(contributions: readonly TrialContribution[]): Group[] {
   return groups;
 }
 
-function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
+function renderEntry<TCtx>(c: RegionContribution<TCtx>, ctx: TCtx, region: string): ReactNode {
   if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
-  if (c.region !== 'toolbar' || !c.item) return null;
-  const { icon: Icon, label, shortcut, disabled, danger, showLabel, pressed, onActivate } = c.item;
+  if (c.region !== region || !c.item) return null;
+  const {
+    icon: Icon,
+    label,
+    shortcut,
+    disabled,
+    danger,
+    showLabel,
+    pressed,
+    onActivate,
+  } = c.item as ToolbarItem<TCtx>;
   return (
     <Toolbar.Button
       key={c.id}
@@ -56,15 +69,20 @@ function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
   );
 }
 
-/** Lays a trial's `toolbar` contributions out, grouped by their `group`. */
-export function ToolbarRegion({ contributions, ctx }: ToolbarRegionProps) {
+/** Lays a bar's contributions out, grouped by their `group`. */
+export function ToolbarRegion<TCtx = TrialChromeContext>({
+  contributions,
+  ctx,
+  region = 'toolbar',
+  label = 'Trial actions',
+}: ToolbarRegionProps<TCtx>) {
   if (contributions.length === 0) return null;
   const groups = groupsOf(contributions);
   return (
-    <Toolbar aria-label="Trial actions">
+    <Toolbar aria-label={label}>
       {groups.map((g) => (
         <Toolbar.Group key={g.key} end={g.end} aria-label={g.key}>
-          {g.entries.map((c) => renderEntry(c, ctx))}
+          {g.entries.map((c) => renderEntry(c, ctx, region))}
         </Toolbar.Group>
       ))}
     </Toolbar>

package/src/chrome/types.ts

@@ -4,14 +4,15 @@ import type { ConfigField } from '../controls/types';
 import type { SavedSnapshot } from '../state/types';
 
 /** A named position in a trial's chrome. Content is not a region — that is
- *  the instrument. */
+ *  the instrument. The lab's own boxes are named in `LabRegion`. */
 export type TrialRegion = 'titlebar' | 'toolbar' | 'palette' | 'sidebar' | 'viewport' | 'status';
 
 /** An icon component taking a pixel size, as `@weasel-js/ui` glyphs do. */
 export type IconComponent = ComponentType<{ size?: number }>;
 
-/** A button in the trial toolbar. */
-export interface ToolbarItem {
+/** A button in a toolbar. `TCtx` is the chrome context its `onActivate` is
+ *  handed — a trial's, or the lab's for a lab-level bar. */
+export interface ToolbarItem<TCtx = TrialChromeContext> {
   icon: IconComponent;
   label: string;
   /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
@@ -24,10 +25,10 @@ export interface ToolbarItem {
   pressed?: boolean;
   /** Render the label beside the glyph rather than only in the tooltip. */
   showLabel?: boolean;
-  /** Handed the trial's chrome context, so a contribution declared from the
-   *  lab can reach `ctx.saveSnapshot()` and the rest without the `render`
-   *  escape. A zero-argument handler stays valid. */
-  onActivate: (ctx: TrialChromeContext) => void;
+  /** Handed the chrome context it was declared against, so a contribution can
+   *  reach `ctx.saveSnapshot()` and the rest without the `render` escape. A
+   *  zero-argument handler stays valid. */
+  onActivate: (ctx: TCtx) => void;
 }
 
 /** A selectable tool in the palette region. */
@@ -52,12 +53,12 @@ export interface SidebarSection {
 }
 
 /** A control acting on the view of the trial, not on the trial. */
-export interface ViewportControl {
+export interface ViewportControl<TCtx = TrialChromeContext> {
   icon: IconComponent;
   label: string;
   disabled?: boolean;
   /** Handed the trial's chrome context, as `ToolbarItem.onActivate` is. */
-  onActivate: (ctx: TrialChromeContext) => void;
+  onActivate: (ctx: TCtx) => void;
 }
 
 /** A readout in the status bar. */
@@ -68,8 +69,8 @@ export interface StatusReadout {
   title?: string;
 }
 
-/** What every contribution shares. */
-interface ContributionBase {
+/** What every contribution shares, whichever chrome it is declared against. */
+export interface ContributionBase {
   id: string;
   /** Groups sort by first appearance; items sort within a group by
    *  declaration order. Contributions with no group sort after grouped ones. */
@@ -96,18 +97,49 @@ export type TrialContribution =
       render: (ctx: TrialChromeContext) => ReactNode;
     });
 
+/**
+ * A tool slot a region can reflect and write. Both chrome contexts carry one:
+ * a trial's resolves to the lab's when its instrument declares no tools.
+ */
+export interface ToolSlotContext {
+  activeToolId: string | null;
+  setActiveTool: (id: string) => void;
+}
+
+/** What a sidebar region reflects and writes: which sections are folded, and —
+ *  where the chrome can tear a section out — where it goes. A trial supplies
+ *  all four; a lab supplies the fold state only. */
+export interface SidebarSlotContext {
+  collapsedSections: Readonly<Record<string, boolean>>;
+  setSectionCollapsed: (key: string, collapsed: boolean) => void;
+  undockedPanels?: readonly string[];
+  undockPanel?: (sectionId: string, as?: 'tile' | 'floating') => void;
+}
+
+/**
+ * A contribution as a region renderer sees it. A renderer checks the region
+ * name against its own and narrows `item` itself, which is what lets one
+ * renderer serve both chromes — the trial's and the lab's — without knowing
+ * which context it was handed.
+ */
+export interface RegionContribution<TCtx> extends ContributionBase {
+  region: string;
+  item?: unknown;
+  render?: (ctx: TCtx) => ReactNode;
+}
+
 /**
  * Everything a contribution can read about the trial it is being rendered
  * into. Replaces the three separate slot contexts, which each carried a
  * hand-picked subset.
  */
-export interface TrialChromeContext {
+export interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext {
   trialId: string;
   instrumentName: string;
-  /** What the title bar reads, which is the instrument's name until something
-   *  calls `setTitle`. */
+  /** What the title bar reads, which is the instrument's title (or, lacking
+   *  one, its name) until something calls `setTitle`. */
   title: string;
-  /** Retitle this trial; `null` restores the instrument name. Persisted with
+  /** Retitle this trial; `null` restores the instrument's title. Persisted with
    *  the trial, so a title survives a reload. */
   setTitle: (title: string | null) => void;
   isLastTrial: boolean;
@@ -133,6 +165,9 @@ export interface TrialChromeContext {
    *  `config`, since a builder schema has no `ConfigField[]` form. */
   configFields: ConfigField[];
   config: unknown;
+  /** The trial's unpinned paths. `config` stays raw, so a control drawn from
+   *  it sits at the value un-pinning writes back. */
+  auto: ReadonlySet<string>;
   setConfig: (key: string, value: unknown) => void;
 
   /** Which of this trial's collapsible sections are folded. A sidebar
@@ -157,9 +192,4 @@ export interface TrialChromeContext {
   clone: () => void;
   reset: () => void;
   close: () => void;
-
-  /** Resolved active tool: the trial's slot, or the lab's when the trial has
-   *  none. Null when neither holds one. */
-  activeToolId: string | null;
-  setActiveTool: (id: string) => void;
 }

package/src/config/auto.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { auto, isAuto } from './auto';
+
+describe('auto', () => {
+  it('is a symbol distinct from every ordinary config value', () => {
+    expect(typeof auto).toBe('symbol');
+    expect(isAuto(auto)).toBe(true);
+    for (const v of [undefined, null, 0, '', 'auto', false, Symbol('auto'), {}]) {
+      expect(isAuto(v)).toBe(false);
+    }
+  });
+});

package/src/config/auto.ts

@@ -0,0 +1,15 @@
+/**
+ * Written at a config path to mean "do not pin this — let the instrument
+ * decide". Accepted by `setConfig`, by a trial's `configSeed`, and by
+ * `.initial()` in a schema. It is normalized into the trial's set of unpinned
+ * paths on the way into the store and is never itself stored, so a serialized
+ * trial contains no sentinel and the last pinned value survives.
+ */
+export const auto: unique symbol = Symbol('weasel.auto');
+
+/** The type of the `auto` sentinel, for widening a value parameter. */
+export type Auto = typeof auto;
+
+export function isAuto(value: unknown): value is Auto {
+  return value === auto;
+}

package/src/config/autoConfig.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { auto } from './auto';
+import { autoPathsOf, resolveAutoConfig } from './autoConfig';
+import { f } from './builder';
+import { resolveConfigSchema } from './resolve';
+
+const schema = f.schema({
+  width: f.number(432),
+  gap: f.number(12).auto((c) => (c.width as number) / 24),
+  cols: f.number(3).initial(auto),
+  grid: f.group({ size: f.number(8).auto(() => 99) }),
+});
+const resolved = resolveConfigSchema(schema);
+const raw = { width: 432, gap: 12, cols: 3, grid: { size: 8 } };
+
+describe('autoPathsOf', () => {
+  it('lists the dotted paths a schema starts auto', () => {
+    expect(autoPathsOf(resolved)).toEqual(['cols']);
+  });
+
+  it('reaches leaves nested under a group', () => {
+    const nested = resolveConfigSchema(
+      f.schema({ grid: f.group({ size: f.number(8).initial(auto) }) }),
+    );
+    expect(autoPathsOf(nested)).toEqual(['grid.size']);
+  });
+});
+
+describe('resolveAutoConfig', () => {
+  it('leaves a config with nothing auto exactly as it was', () => {
+    expect(resolveAutoConfig(resolved, raw, new Set())).toEqual(raw);
+  });
+
+  it('replaces an auto path that has a resolver with the computed value', () => {
+    const out = resolveAutoConfig(resolved, raw, new Set(['gap']));
+    expect(out.gap).toBe(18);
+    expect(out.width).toBe(432);
+  });
+
+  it('deletes an auto path that has no resolver', () => {
+    const out = resolveAutoConfig(resolved, raw, new Set(['cols'])) as Record<string, unknown>;
+    expect('cols' in out).toBe(false);
+  });
+
+  it('resolves a leaf nested under a group', () => {
+    const out = resolveAutoConfig(resolved, raw, new Set(['grid.size'])) as {
+      grid: { size: number };
+    };
+    expect(out.grid.size).toBe(99);
+  });
+
+  it('lets one resolver read another auto path, already resolved', () => {
+    const chained = resolveConfigSchema(
+      f.schema({
+        a: f.number(1).auto(() => 10),
+        b: f.number(2).auto((c) => (c.a as number) * 3),
+      }),
+    );
+    const out = resolveAutoConfig(chained, { a: 1, b: 2 }, new Set(['a', 'b'])) as {
+      a: number;
+      b: number;
+    };
+    expect(out).toEqual({ a: 10, b: 30 });
+  });
+
+  it('resolves a dependency declared after its dependent', () => {
+    const backward = resolveConfigSchema(
+      f.schema({
+        b: f.number(2).auto((c) => (c.a as number) * 3),
+        a: f.number(1).auto(() => 10),
+      }),
+    );
+    const out = resolveAutoConfig(backward, { a: 1, b: 2 }, new Set(['a', 'b'])) as {
+      a: number;
+      b: number;
+    };
+    expect(out).toEqual({ a: 10, b: 30 });
+  });
+
+  it('throws naming the path when resolvers cycle', () => {
+    const cyclic = resolveConfigSchema(
+      f.schema({
+        a: f.number(1).auto((c) => (c.b as number) + 1),
+        b: f.number(2).auto((c) => (c.a as number) + 1),
+      }),
+    );
+    expect(() => resolveAutoConfig(cyclic, { a: 1, b: 2 }, new Set(['a', 'b']))).toThrow(/cycle/i);
+    expect(() => resolveAutoConfig(cyclic, { a: 1, b: 2 }, new Set(['a', 'b']))).toThrow(/"a"/);
+  });
+
+  it('throws on a resolver that reads its own path', () => {
+    const selfish = resolveConfigSchema(
+      f.schema({ a: f.number(1).auto((c) => (c.a as number) + 1) }),
+    );
+    expect(() => resolveAutoConfig(selfish, { a: 1 }, new Set(['a']))).toThrow(/cycle/i);
+  });
+
+  it('ignores an auto path the schema does not have', () => {
+    expect(resolveAutoConfig(resolved, raw, new Set(['gone']))).toEqual(raw);
+  });
+
+  it('does not mutate the config it was given', () => {
+    const before = structuredClone(raw);
+    resolveAutoConfig(resolved, raw, new Set(['gap', 'grid.size']));
+    expect(raw).toEqual(before);
+  });
+});