@weasel-js/labkit 1.4.0 → 1.4.2

package/src/trial/TrialChrome.tsx

@@ -62,6 +62,10 @@ export interface TrialChromeProps {
 
 const NO_OP = (): void => {};
 
+/** One frozen empty map, so a trial that has folded nothing keeps a stable
+ *  context identity across renders. */
+const NO_SECTIONS: Readonly<Record<string, boolean>> = Object.freeze({});
+
 /** The frame around a running instrument. Builds one chrome context, assembles
  *  the contributions the instrument, the runtime and the lab declare, and hands
  *  each region its slice. */
@@ -85,6 +89,8 @@ export function TrialChrome({
   if (!storeCtx) throw new Error('[labkit] TrialChrome requires <LabStoreProvider>');
   const updateTrialView = useStore(storeCtx.store, (s) => s.updateTrialView);
   const updateTrialSidebarWidth = useStore(storeCtx.store, (s) => s.updateTrialSidebarWidth);
+  const setTrialTitle = useStore(storeCtx.store, (s) => s.setTrialTitle);
+  const setTrialSectionCollapsed = useStore(storeCtx.store, (s) => s.setTrialSectionCollapsed);
   const updateTrialConfig = useStore(storeCtx.store, (s) => s.updateTrialConfig);
   const updateTrialState = useStore(storeCtx.store, (s) => s.updateTrialState);
   const undockPanelAction = useStore(storeCtx.store, (s) => s.undockPanel);
@@ -104,6 +110,9 @@ export function TrialChrome({
 
   const configSchema = useConfigSchema(instrument);
 
+  const title = record.title ?? record.instrumentName;
+  const collapsedSections = record.collapsedSections ?? NO_SECTIONS;
+
   const ctx = useMemo<TrialChromeContext>(() => {
     const setZoom = (z: number): void => {
       if (!view2d) return;
@@ -112,6 +121,8 @@ export function TrialChrome({
     return {
       trialId,
       instrumentName: record.instrumentName,
+      title,
+      setTitle: (next) => setTrialTitle(trialId, next),
       isLastTrial,
       zoom: view2d ? view2d.zoom : null,
       setZoom,
@@ -138,6 +149,8 @@ export function TrialChrome({
           updateTrialState(trialId, nextState as never);
         }
       },
+      collapsedSections,
+      setSectionCollapsed: (key, collapsed) => setTrialSectionCollapsed(trialId, key, collapsed),
       undockedPanels: undockedIds,
       undockPanel: (sectionId, as) => undockPanelAction(trialId, sectionId, as),
       dockPanel: (sectionId) => dockPanelAction(trialId, sectionId),
@@ -155,6 +168,7 @@ export function TrialChrome({
     record,
     instrument,
     lab,
+    title,
     isLastTrial,
     updateTrialView,
     updateTrialConfig,
@@ -168,6 +182,9 @@ export function TrialChrome({
     undockedIds,
     undockPanelAction,
     dockPanelAction,
+    setTrialTitle,
+    setTrialSectionCollapsed,
+    collapsedSections,
   ]);
 
   const contributions = useMemo(
@@ -203,11 +220,14 @@ export function TrialChrome({
   return (
     <section
       className="lk-trial"
-      aria-label={`Trial ${record.instrumentName}`}
+      aria-label={`Trial ${title}`}
       tabIndex={-1}
       onKeyDown={handleKeyDown}
     >
-      <TrialTitleBar title={record.instrumentName}>
+      <TrialTitleBar
+        title={title}
+        lead={<TitleBarRegion placement="lead" contributions={inRegion('titlebar')} ctx={ctx} />}
+      >
         <TitleBarRegion contributions={inRegion('titlebar')} ctx={ctx} />
       </TrialTitleBar>
       <div className="lk-trial__toolbar">

package/src/trial/TrialTitleBar.tsx

@@ -6,15 +6,18 @@ import { useTrialDrag } from './TrialDragContext';
 /** Props for `<TrialTitleBar>`. */
 export interface TrialTitleBarProps {
   title: string;
+  /** Rendered at the leading edge, before the title. */
+  lead?: ReactNode;
   children?: ReactNode;
 }
 
 // `useDragHandle` needs a node id and windease's DragProvider, so the draggable
 // form is a separate component rather than a conditional hook.
-function Draggable({ nodeId, title, children }: TrialTitleBarProps & { nodeId: NodeId }) {
+function Draggable({ nodeId, title, lead, children }: TrialTitleBarProps & { nodeId: NodeId }) {
   const handlers = useDragHandle(nodeId);
   return (
     <div className="lk-trial__titlebar lk-trial__titlebar--draggable" {...handlers}>
+      {lead}
       <span className="lk-trial__title">{title}</span>
       {children}
     </div>
@@ -24,16 +27,17 @@ function Draggable({ nodeId, title, children }: TrialTitleBarProps & { nodeId: N
 /** A trial's title bar. When the workspace allows reordering the whole bar is
  *  the drag surface — there is no separate grip, because a window's title bar
  *  is already the thing you expect to drag. */
-export function TrialTitleBar({ title, children }: TrialTitleBarProps) {
+export function TrialTitleBar({ title, lead, children }: TrialTitleBarProps) {
   const drag = useTrialDrag();
   if (drag)
     return (
-      <Draggable nodeId={drag.nodeId} title={title}>
+      <Draggable nodeId={drag.nodeId} title={title} lead={lead}>
         {children}
       </Draggable>
     );
   return (
     <div className="lk-trial__titlebar">
+      {lead}
       <span className="lk-trial__title">{title}</span>
       {children}
     </div>

package/src/trial/index.ts

@@ -4,6 +4,7 @@ export type { TrialBodyProps } from './TrialBody';
 export { TrialBody } from './TrialBody';
 export type { TrialChromeProps, UndoBindings } from './TrialChrome';
 export { TrialChrome } from './TrialChrome';
+export type { AddTrialOptions } from './trialOps';
 export {
   addTrial,
   cloneTrial,

package/src/trial/trialOps.test.ts

@@ -26,7 +26,23 @@ const counterWithCanvas: Instrument<CounterState, CounterConfig> = {
   },
 };
 
-const instruments: Instrument[] = [counter as Instrument, counterWithCanvas as Instrument];
+interface SubjectConfig {
+  subject: string;
+  zoom: number;
+}
+
+const subjectInstrument: Instrument<{ label: string }, SubjectConfig> = {
+  name: 'Subject',
+  defaultConfig: () => ({ subject: 'none', zoom: 1 }),
+  initialState: (config) => ({ label: config.subject.toUpperCase() }),
+  render: () => null,
+};
+
+const instruments: Instrument[] = [
+  counter as Instrument,
+  counterWithCanvas as Instrument,
+  subjectInstrument as Instrument,
+];
 
 function head<T>(arr: T[]): T {
   const first = arr[0];
@@ -69,6 +85,28 @@ describe('addTrial', () => {
     addTrial(arr, instruments, 'Counter');
     expect(arr).toHaveLength(0);
   });
+
+  it('overlays a seed config on the instrument defaults', () => {
+    const out = addTrial([], instruments, 'Subject', { config: { subject: 'brick' } });
+    expect(out[0]?.config).toEqual({ subject: 'brick', zoom: 1 });
+  });
+
+  it('seeds the config before initialState reads it', () => {
+    const out = addTrial([], instruments, 'Subject', { config: { subject: 'brick' } });
+    expect(out[0]?.state).toEqual({ label: 'BRICK' });
+  });
+
+  it('gives each trial the seed it was opened with', () => {
+    const a = addTrial([], instruments, 'Subject', { config: { subject: 'one' } });
+    const b = addTrial(a, instruments, 'Subject', { config: { subject: 'two' } });
+    expect(b.map((t) => (t.config as SubjectConfig).subject)).toEqual(['one', 'two']);
+    expect(b.map((t) => (t.state as { label: string }).label)).toEqual(['ONE', 'TWO']);
+  });
+
+  it('ignores a seed key whose value is undefined', () => {
+    const out = addTrial([], instruments, 'Subject', { config: { subject: undefined } });
+    expect(out[0]?.config).toEqual({ subject: 'none', zoom: 1 });
+  });
 });
 
 describe('cloneTrial', () => {
@@ -139,6 +177,16 @@ describe('resetTrial', () => {
     resetTrial(arr, head(arr).id, instruments);
     expect((arr[0]?.config as CounterConfig).step).toBe(99);
   });
+
+  it('restores the seed the trial was opened with, not the bare defaults', () => {
+    let arr = addTrial([], instruments, 'Subject', { config: { subject: 'one' } });
+    arr = addTrial(arr, instruments, 'Subject', { config: { subject: 'two' } });
+    head(arr).config = { subject: 'edited', zoom: 4 } as SubjectConfig;
+    const reset = resetTrial(arr, head(arr).id, instruments);
+    expect(reset[0]?.config).toEqual({ subject: 'one', zoom: 1 });
+    expect(reset[0]?.state).toEqual({ label: 'ONE' });
+    expect(reset[1]?.config).toEqual({ subject: 'two', zoom: 1 });
+  });
 });
 
 describe('reorderTrials', () => {

package/src/trial/trialOps.ts

@@ -19,15 +19,36 @@ function initialView(instrument: Instrument): TrialRecord['view'] {
   return declared ? structuredClone(declared) : { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
 }
 
-/** Append a new trial running `instrumentName`, at that instrument's
- *  default config and initial state. */
+/** What a trial opens on beyond its instrument's own defaults. */
+export interface AddTrialOptions<TC = Record<string, unknown>> {
+  /** Overlaid on `defaultConfig()` before `initialState` reads it, so a trial
+   *  opened on a subject is running that subject from its first frame. Keys
+   *  whose value is `undefined` are left to the default. */
+  config?: Partial<TC>;
+}
+
+/** `defaultConfig()` with `seed` written over it. Config is flat — a leaf's
+ *  path is its config key — so this is the whole merge. */
+function seedConfig<TC>(defaults: TC, seed: Partial<TC> | undefined): TC {
+  if (!seed) return defaults;
+  const out = { ...defaults };
+  for (const [key, value] of Object.entries(seed)) {
+    if (value !== undefined) (out as Record<string, unknown>)[key] = value;
+  }
+  return out;
+}
+
+/** Append a new trial running `instrumentName`, at that instrument's default
+ *  config — with `options.config` written over it — and the initial state
+ *  that config produces. */
 export function addTrial(
   trials: TrialRecord[],
   instruments: InstrumentList,
   instrumentName: string,
+  options: AddTrialOptions = {},
 ): TrialRecord[] {
   const instrument = findInstrument(instruments, instrumentName);
-  const config = instrument.defaultConfig();
+  const config = seedConfig(instrument.defaultConfig(), options.config);
   const state = instrument.initialState(config);
   const record: TrialRecord = {
     id: crypto.randomUUID(),
@@ -37,6 +58,7 @@ export function addTrial(
     view: initialView(instrument),
     undoStack: { past: [], future: [] },
   };
+  if (options.config) record.configSeed = options.config;
   return [...trials, record];
 }
 
@@ -65,8 +87,8 @@ export function closeTrial(trials: TrialRecord[], id: string): TrialRecord[] {
   return next.length === trials.length ? trials : next;
 }
 
-/** Return a trial to its instrument's defaults, keeping its id and its
- *  place in the list. */
+/** Return a trial to what it opened on — its instrument's defaults under the
+ *  seed `addTrial` was given — keeping its id and its place in the list. */
 export function resetTrial(
   trials: TrialRecord[],
   id: string,
@@ -76,7 +98,7 @@ export function resetTrial(
   const current = trials[idx];
   if (!current) return trials;
   const instrument = findInstrument(instruments, current.instrumentName);
-  const config = instrument.defaultConfig();
+  const config = seedConfig(instrument.defaultConfig(), current.configSeed);
   const state = instrument.initialState(config);
   const reset: TrialRecord = {
     ...current,