@weasel-js/labkit 1.3.0-pre.0 → 1.4.0-pre.0

package/src/chrome/regions/PaletteRegion.tsx

@@ -1,4 +1,5 @@
 import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
+import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
 import type { TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<PaletteRegion>`. */
@@ -10,13 +11,16 @@ export interface PaletteRegionProps {
 /** 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) {
+  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>('vertical');
   if (contributions.length === 0) return null;
   return (
     <div
+      ref={ref}
       className="lk-palette-region"
       role="toolbar"
       aria-label="Tools"
       aria-orientation="vertical"
+      onKeyDown={onKeyDown}
     >
       <ToolGroup orientation="vertical">
         {contributions.map((c) => {

package/src/chrome/regions/SidebarRegion.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 import { useState } from 'react';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { SidebarSection, TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<SidebarRegion>`. */
 export interface SidebarRegionProps {
@@ -11,29 +11,46 @@ export interface SidebarRegionProps {
 function Section({
   title,
   defaultCollapsed,
+  onUndock,
   children,
 }: {
   title: string;
   defaultCollapsed: boolean;
+  onUndock?: () => void;
   children: ReactNode;
 }) {
   const [collapsed, setCollapsed] = useState(defaultCollapsed);
   return (
     <section className="lk-sidebar-section">
-      <button
-        type="button"
-        className="lk-sidebar-section__head"
-        aria-expanded={!collapsed}
-        onClick={() => setCollapsed((c) => !c)}
-      >
-        {title}
-      </button>
+      <div className="lk-sidebar-section__bar">
+        <button
+          type="button"
+          className="lk-sidebar-section__head"
+          aria-expanded={!collapsed}
+          onClick={() => setCollapsed((c) => !c)}
+        >
+          {title}
+        </button>
+        {onUndock ? (
+          <button
+            type="button"
+            className="lk-sidebar-section__undock"
+            aria-label={`Undock ${title}`}
+            title={`Undock ${title}`}
+            onClick={onUndock}
+          >
+            ⧉
+          </button>
+        ) : null}
+      </div>
       {collapsed ? null : <div className="lk-sidebar-section__body">{children}</div>}
     </section>
   );
 }
 
-/** Lays a trial's `sidebar` contributions out as titled, collapsible sections. */
+/** 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) {
   if (contributions.length === 0) return null;
   return (
@@ -41,13 +58,20 @@ export function SidebarRegion({ contributions, ctx }: SidebarRegionProps) {
       {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;
+        const item = c.item as SidebarSection;
         return (
           <Section
             key={c.id}
-            title={c.item.title}
-            defaultCollapsed={c.item.defaultCollapsed ?? false}
+            title={item.title}
+            defaultCollapsed={item.defaultCollapsed ?? false}
+            onUndock={
+              item.undockable === false
+                ? undefined
+                : () => ctx.undockPanel(c.id, item.undockAs ?? 'tile')
+            }
           >
-            {c.item.body}
+            {item.body}
           </Section>
         );
       })}

package/src/chrome/regions/ToolbarRegion.tsx

@@ -38,13 +38,14 @@ function groupsOf(contributions: readonly TrialContribution[]): Group[] {
 function renderEntry(c: TrialContribution, ctx: TrialChromeContext): 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 } = c.item;
+  const { icon: Icon, label, shortcut, disabled, danger, showLabel, pressed } = c.item;
   return (
     <Toolbar.Button
       key={c.id}
       iconOnly={!showLabel}
       variant={danger ? 'danger' : 'default'}
       disabled={disabled}
+      pressed={pressed}
       aria-label={label}
       title={shortcut ? `${label} (${shortcut})` : label}
       onClick={c.item.onActivate}

package/src/chrome/regions/ViewportRegion.tsx

@@ -1,3 +1,4 @@
+import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
 import type { TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<ViewportRegion>`. */
@@ -11,9 +12,16 @@ export interface ViewportRegionProps {
  * rather than in the toolbar, which acts on the trial itself.
  */
 export function ViewportRegion({ contributions, ctx }: ViewportRegionProps) {
+  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
   if (contributions.length === 0) return null;
   return (
-    <div className="lk-viewport-controls" role="toolbar" aria-label="View">
+    <div
+      ref={ref}
+      className="lk-viewport-controls"
+      role="toolbar"
+      aria-label="View"
+      onKeyDown={onKeyDown}
+    >
       {contributions.map((c) => {
         if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
         if (c.region !== 'viewport' || !c.item) return null;

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

@@ -6,7 +6,12 @@ import { StatusRegion } from './StatusRegion';
 import { ViewportRegion } from './ViewportRegion';
 
 const Glyph = () => <svg />;
-const ctx = { trialId: 't1' } as unknown as TrialChromeContext;
+const ctx = {
+  trialId: 't1',
+  undockedPanels: [],
+  undockPanel: () => {},
+  dockPanel: () => {},
+} as unknown as TrialChromeContext;
 
 describe('SidebarRegion', () => {
   it('renders nothing when empty', () => {

package/src/chrome/types.ts

@@ -19,6 +19,9 @@ export interface ToolbarItem {
   disabled?: boolean;
   /** Reddens on hover. For actions that discard work. */
   danger?: boolean;
+  /** A toggle rather than a command: renders `aria-pressed` and reads as held
+   *  down while true. */
+  pressed?: boolean;
   /** Render the label beside the glyph rather than only in the tooltip. */
   showLabel?: boolean;
   onActivate: () => void;
@@ -37,6 +40,11 @@ export interface SidebarSection {
   title: string;
   /** Starts collapsed. The open/closed state itself is the region's. */
   defaultCollapsed?: boolean;
+  /** Offer the tear-out control. On by default; a section that only makes
+   *  sense beside its trial sets this false. */
+  undockable?: boolean;
+  /** Where the tear-out control sends it. Default `'tile'`. */
+  undockAs?: 'tile' | 'floating';
   body: ReactNode;
 }
 
@@ -103,6 +111,11 @@ export interface TrialChromeContext {
   undo: () => void;
   redo: () => void;
 
+  /** Whether the trial's loupe is turned on. False for an instrument that
+   *  declares none, whose chrome offers no way to turn one on. */
+  loupeOn: boolean;
+  toggleLoupe: () => void;
+
   /** The instrument's controls, resolved against the lab's rules. Always
    *  populated: a legacy `configSchema()` is adapted into the same shape. */
   configSchema: ResolvedConfig;
@@ -112,6 +125,13 @@ export interface TrialChromeContext {
   config: unknown;
   setConfig: (key: string, value: unknown) => void;
 
+  /** Section ids this trial currently has torn out of its sidebar. */
+  undockedPanels: readonly string[];
+  /** Tear a sidebar section out into the workspace. */
+  undockPanel: (sectionId: string, as?: 'tile' | 'floating') => void;
+  /** Put a torn-out section back in the sidebar. */
+  dockPanel: (sectionId: string) => void;
+
   savedSnapshots: SavedSnapshot[];
   saveSnapshot: (name?: string) => void;
   loadSnapshot: (snapshotId: string) => void;

package/src/config/builder.test.ts

@@ -20,7 +20,13 @@ describe('builder', () => {
   it('keeps the subclass across a chain, so kind-specific methods survive', () => {
     const n = f.number(20).label('A').range(5, 80).describe('help').step(5);
     expect(n.kind).toBe('number');
-    expect(n.annotations).toMatchObject({ name: 'A', description: 'help', min: 5, max: 80, step: 5 });
+    expect(n.annotations).toMatchObject({
+      name: 'A',
+      description: 'help',
+      min: 5,
+      max: 80,
+      step: 5,
+    });
   });
 
   it('keeps a custom node kind across a chain', () => {

package/src/config/builder.ts

@@ -29,11 +29,7 @@ abstract class BaseNode<T> implements ConfigNode<T> {
   /** Clone into the same subclass. Subclasses with extra constructor
    *  arguments override this. */
   protected with(annotations: Annotations, options: NodeOptions): this {
-    const Ctor = this.constructor as new (
-      d: T,
-      a: Annotations,
-      o: NodeOptions,
-    ) => this;
+    const Ctor = this.constructor as new (d: T, a: Annotations, o: NodeOptions) => this;
     return new Ctor(this.default, annotations, options);
   }
 

package/src/config/resolve.test.ts

@@ -54,8 +54,7 @@ describe('resolveConfigSchema', () => {
   });
 
   it('a consumer rule claims an f.value kind before the built-in', () => {
-    const colorByName: ConfigRule = (ctx) =>
-      ctx.key.endsWith('Color') ? { kind: 'color' } : null;
+    const colorByName: ConfigRule = (ctx) => (ctx.key.endsWith('Color') ? { kind: 'color' } : null);
     const r = resolveConfigSchema(f.schema({ tintColor: f.value('#fff') }), [colorByName]);
     expect(leafAt(r, 'tintColor').kind).toBe('color');
   });

package/src/controls/ControlPanel.stories.tsx

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
 import { f } from '../config/builder';
 import { resolveConfigSchema } from '../config/resolve';
 import type { ConfigRule, ControlRenderer } from '../config/types';
-import { PropertyRow } from '../ui/properties/PropertyPanel';
 import { ControlPanel } from './ControlPanel';
 import type { ConfigField } from './types';
 
@@ -141,9 +141,48 @@ export const CustomControl: Story = {
   ),
 };
 
+const described = f.schema({
+  frequency: f
+    .number(2)
+    .range(0.1, 10)
+    .step(0.1)
+    .describe('Cycles per second the oscillator runs at.'),
+  amplitude: f.number(0.5).range(0, 1).step(0.05),
+  showGrid: f.boolean(true).describe('Draw the alignment grid behind the plot.'),
+  wave: f
+    .enum('sine', [
+      { value: 'sine', label: 'Sine' },
+      { value: 'square', label: 'Square' },
+    ])
+    .describe('Waveform the generator emits.'),
+  title: f.string('My experiment'),
+  tint: f.color('#3a86ff').describe('Plot line color.'),
+});
+
+/** A leaf with a `describe(...)` gets an \u24d8 beside its label whose tooltip
+ *  carries the text; leaves without one stay bare. */
+export const Described: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(described, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(described.defaults());
+    return (
+      <ControlPanel
+        schema={schema}
+        config={config}
+        setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+      />
+    );
+  },
+};
+
 const conditional = f.schema({
   showGrid: f.boolean(true),
-  cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing').showIf((c) => c.showGrid === true),
+  cellSize: f
+    .number(20)
+    .range(5, 80)
+    .step(5)
+    .label('Grid spacing')
+    .showIf((c) => c.showGrid === true),
 });
 
 /** `showIf` hides the row while the value stays in config. Toggle the

package/src/controls/ControlPanel.test.tsx

@@ -1,10 +1,10 @@
 import { fireEvent, render, screen } from '@testing-library/react';
-import { afterEach, describe, expect, it, vi } from 'vitest';
 import { TOOL_PREF_KINDS, type ToolPrefKind } from '@weasel-js/core';
 import type { PrefLeaf } from '@weasel-js/ui';
-import type { ResolvedConfig } from '../config/types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { f } from '../config/builder';
 import { resolveConfigSchema } from '../config/resolve';
+import type { ResolvedConfig } from '../config/types';
 import { ControlPanel } from './ControlPanel';
 import type { ConfigField } from './types';
 
@@ -188,6 +188,21 @@ describe('<ControlPanel> schema', () => {
     render(<ControlPanel schema={schema} config={{}} setConfig={vi.fn()} />);
     expect(screen.getByLabelText('Tint')).toHaveValue('#123456');
   });
+
+  it('hangs a described leaf\u2019s description off a help affordance, and leaves an undescribed leaf bare', () => {
+    const schema = resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true).describe('Draw the alignment grid.'),
+        snap: f.boolean(true),
+      }),
+      [],
+    );
+    render(
+      <ControlPanel schema={schema} config={{ showGrid: true, snap: true }} setConfig={vi.fn()} />,
+    );
+    expect(screen.getByRole('button', { name: 'About Show grid' })).toBeInTheDocument();
+    expect(screen.getAllByRole('button', { name: /^About / })).toHaveLength(1);
+  });
 });
 
 describe('<ControlPanel> renderers', () => {
@@ -205,7 +220,7 @@ describe('<ControlPanel> renderers', () => {
     expect(screen.queryByText('by-kind')).not.toBeInTheDocument();
   });
 
-  it('a lab renderer for the path beats the node\'s own .render', () => {
+  it("a lab renderer for the path beats the node's own .render", () => {
     const schema = resolveConfigSchema(
       f.schema({ tint: f.color('#ffffff').render(() => <span>by-node</span>) }),
       [],
@@ -252,7 +267,7 @@ describe('<ControlPanel> renderers', () => {
 
   it('a renderer returning null collapses the row', () => {
     const schema = resolveConfigSchema(f.schema({ tint: f.color('#ffffff') }), []);
-    const { container } = render(
+    render(
       <ControlPanel
         schema={schema}
         config={{ tint: '#ffffff' }}
@@ -260,7 +275,7 @@ describe('<ControlPanel> renderers', () => {
         renderers={{ color: () => null }}
       />,
     );
-    expect(container.querySelector('.lk-property-row')).toBeNull();
+    expect(screen.queryByText('Tint')).toBeNull();
   });
 });
 
@@ -274,7 +289,11 @@ describe('<ControlPanel> visibility and sections', () => {
       [],
     );
     const { rerender } = render(
-      <ControlPanel schema={schema} config={{ showGrid: true, cellSize: 20 }} setConfig={vi.fn()} />,
+      <ControlPanel
+        schema={schema}
+        config={{ showGrid: true, cellSize: 20 }}
+        setConfig={vi.fn()}
+      />,
     );
     expect(screen.getByLabelText('Cell size')).toBeInTheDocument();
     rerender(
@@ -302,11 +321,11 @@ describe('<ControlPanel> visibility and sections', () => {
       f.schema({ showGrid: f.boolean(true), seed: f.number(0).section('Advanced') }),
       [],
     );
-    const { container } = render(
+    render(
       <ControlPanel schema={schema} config={{ showGrid: true, seed: 0 }} setConfig={vi.fn()} />,
     );
     expect(screen.getByText('Advanced')).toBeInTheDocument();
-    const group = container.querySelector('.lk-property-group');
+    const group = screen.getByRole('heading', { name: 'Advanced' }).parentElement;
     expect(group).not.toBeNull();
     expect(group?.textContent).toContain('Seed');
     expect(group?.textContent).not.toContain('Show grid');
@@ -335,7 +354,10 @@ describe('<ControlPanel> built-in kind coverage', () => {
         schema={schemaWith(
           { kind: 'paint', name: 'Fill', description: '', default: null },
           {
-            kind: 'object', name: 'Stroke', description: '', default: {},
+            kind: 'object',
+            name: 'Stroke',
+            description: '',
+            default: {},
             children: { width: { kind: 'number', name: 'Width', description: '', default: 1 } },
           },
         )}
@@ -360,3 +382,41 @@ describe('<ControlPanel> built-in kind coverage', () => {
     ).toThrow(/spline/);
   });
 });
+
+describe('<ControlPanel> packing', () => {
+  const schema = resolveConfigSchema(
+    f.schema({ width: f.number(256), title: f.string('a'), tint: f.color('#ff0000') }),
+    [],
+  );
+  const config = { width: 256, title: 'a', tint: '#ff0000' };
+  // jsdom lays out no grid, so the class the grid rules key off is the proxy
+  // for "these rows pair" — a layout assertion is not available here.
+  const list = (container: HTMLElement) => container.querySelector('.lk-control-panel');
+  const rowOf = (name: string) => screen.getByLabelText(name).closest('label');
+
+  it('packs two rows to a line by default', () => {
+    const { container } = render(
+      <ControlPanel schema={schema} config={config} setConfig={vi.fn()} />,
+    );
+    expect(list(container)?.className).toMatch(/listPairs/);
+    expect(rowOf('Width')?.className).not.toMatch(/span/);
+  });
+
+  it('gives every row its own line under one-up', () => {
+    const { container } = render(
+      <ControlPanel schema={schema} config={config} setConfig={vi.fn()} pack="one-up" />,
+    );
+    expect(list(container)?.className).not.toMatch(/listPairs/);
+  });
+
+  it('spans the rows that need the width under auto, and pairs the rest', () => {
+    render(<ControlPanel schema={schema} config={config} setConfig={vi.fn()} pack="auto" />);
+    expect(rowOf('Title')?.className).toMatch(/span/);
+    expect(rowOf('Width')?.className).not.toMatch(/span/);
+  });
+
+  it('passes its layout down to the rows', () => {
+    render(<ControlPanel schema={schema} config={config} setConfig={vi.fn()} layout="inline" />);
+    expect(rowOf('Width')?.className).toMatch(/rowInline/);
+  });
+});