@weasel-js/labkit 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/dist/_dts/{DrawCommand-CitWPxMY.d.ts → DrawCommand-BkZztJsW.d.ts} +59 -1
  2. package/dist/_dts/{index-C6Yze7sQ.d.ts → index-CFlDPeZh.d.ts} +30 -1
  3. package/dist/_dts/{types-Si4Fw-1F.d.ts → types-x92Kfeme.d.ts} +14 -0
  4. package/dist/_dts/{useExperimentState-CJn2hHzd.d.ts → useExperimentState-D7EQnnwJ.d.ts} +47 -0
  5. package/dist/canvas/index.d.ts +13 -2
  6. package/dist/canvas/index.js +2 -2
  7. package/dist/{chunk-54IQ2DX7.js → chunk-574LJAV4.js} +3 -3
  8. package/dist/chunk-574LJAV4.js.map +1 -0
  9. package/dist/{chunk-VLAHRJOC.js → chunk-5R2ATYPJ.js} +2 -2
  10. package/dist/{chunk-VLAHRJOC.js.map → chunk-5R2ATYPJ.js.map} +1 -1
  11. package/dist/{chunk-R4TACNW7.js → chunk-BAPZPDDA.js} +631 -591
  12. package/dist/chunk-BAPZPDDA.js.map +1 -0
  13. package/dist/{chunk-PWC7AQZM.js → chunk-CPUJ3QXL.js} +2 -2
  14. package/dist/chunk-CPUJ3QXL.js.map +1 -0
  15. package/dist/{chunk-2ZRE7WGQ.js → chunk-DEWXYFEU.js} +6 -6
  16. package/dist/chunk-DEWXYFEU.js.map +1 -0
  17. package/dist/{chunk-3P56ZCCJ.js → chunk-DWV7SFKR.js} +601 -269
  18. package/dist/chunk-DWV7SFKR.js.map +1 -0
  19. package/dist/{chunk-53XSBIUK.js → chunk-KSTEW2AF.js} +18 -2
  20. package/dist/chunk-KSTEW2AF.js.map +1 -0
  21. package/dist/{chunk-HXZHVU4G.js → chunk-PMAU3SEE.js} +3 -3
  22. package/dist/chunk-PMAU3SEE.js.map +1 -0
  23. package/dist/{chunk-7BKDG73Z.js → chunk-RL2LOLNI.js} +2 -2
  24. package/dist/chunk-RL2LOLNI.js.map +1 -0
  25. package/dist/{chunk-2QNYYL3V.js → chunk-SFL7NFKN.js} +2 -2
  26. package/dist/chunk-SFL7NFKN.js.map +1 -0
  27. package/dist/controls/index.d.ts +4 -2
  28. package/dist/controls/index.js +1 -1
  29. package/dist/dragdrop/index.d.ts +2 -2
  30. package/dist/index.d.ts +180 -15
  31. package/dist/index.js +146 -37
  32. package/dist/index.js.map +1 -1
  33. package/dist/layers/index.d.ts +6 -3
  34. package/dist/layers/index.js +1 -1
  35. package/dist/passthrough/weasel-canvas.d.ts +5 -1
  36. package/dist/passthrough/weasel-canvas.js +1 -1
  37. package/dist/passthrough/weasel-ui.d.ts +444 -7
  38. package/dist/passthrough/weasel-ui.js +2 -2
  39. package/dist/primitives/index.d.ts +13 -0
  40. package/dist/primitives/index.js +2 -2
  41. package/dist/state/index.d.ts +16 -3
  42. package/dist/state/index.js +2 -2
  43. package/dist/state/index.js.map +1 -1
  44. package/dist/styles.css +163 -6
  45. package/dist/ui/layers/index.d.ts +5 -0
  46. package/dist/ui/layers/index.js +3 -3
  47. package/dist/undo/index.d.ts +17 -2
  48. package/dist/undo/index.js +1 -1
  49. package/package.json +2 -1
  50. package/src/canvas/CanvasStack.tsx +4 -0
  51. package/src/canvas/CanvasStackContext.ts +3 -0
  52. package/src/canvas/canvasCoords.ts +2 -0
  53. package/src/canvas/useLayerScheduler.ts +2 -0
  54. package/src/controls/ControlPanel.tsx +2 -0
  55. package/src/controls/types.ts +14 -0
  56. package/src/instrument/capabilityDetector.ts +3 -0
  57. package/src/instrument/defineInstrument.ts +2 -0
  58. package/src/instrument/types.ts +29 -0
  59. package/src/instrument/validateConfigSchema.ts +5 -0
  60. package/src/lab/Lab.tsx +17 -2
  61. package/src/lab/LabContext.ts +6 -0
  62. package/src/lab/LabShell.tsx +4 -0
  63. package/src/lab/WorkspaceGrid.less +37 -5
  64. package/src/lab/WorkspaceGrid.stories.tsx +16 -0
  65. package/src/lab/WorkspaceGrid.test.tsx +84 -10
  66. package/src/lab/WorkspaceGrid.tsx +188 -12
  67. package/src/lab/index.ts +0 -2
  68. package/src/layers/LayerList.tsx +3 -0
  69. package/src/primitives/FpsMeter.tsx +1 -0
  70. package/src/primitives/ScaleIndicator.tsx +4 -0
  71. package/src/primitives/Sidebar.tsx +3 -0
  72. package/src/primitives/StatusBar.tsx +3 -0
  73. package/src/primitives/Toolbar.tsx +6 -0
  74. package/src/state/SingletonExperiment.tsx +1 -0
  75. package/src/state/adapters.ts +8 -0
  76. package/src/state/context.tsx +9 -0
  77. package/src/state/helpers.ts +13 -1
  78. package/src/state/store.test.ts +2 -1
  79. package/src/state/store.ts +25 -0
  80. package/src/state/types.ts +20 -0
  81. package/src/state/useExperimentState.ts +3 -0
  82. package/src/test-setup.ts +19 -0
  83. package/src/ui/layers/LayerStack.tsx +5 -0
  84. package/src/ui/properties/CurveField.tsx +4 -1
  85. package/src/ui/properties/EffectCard.tsx +12 -0
  86. package/src/ui/properties/PropertyGroup.tsx +1 -0
  87. package/src/ui/properties/PropertyPanel.tsx +28 -0
  88. package/src/undo/eventBus.ts +4 -0
  89. package/src/undo/undoStack.ts +11 -0
  90. package/src/workspace/DefaultSidebar.tsx +3 -0
  91. package/src/workspace/DefaultStatusBar.tsx +3 -0
  92. package/src/workspace/DefaultToolbar.tsx +3 -0
  93. package/src/workspace/Workspace.stories.tsx +1 -0
  94. package/src/workspace/Workspace.test.tsx +1 -0
  95. package/src/workspace/Workspace.tsx +3 -0
  96. package/src/workspace/WorkspaceChrome.tsx +4 -0
  97. package/src/workspace/index.ts +1 -0
  98. package/src/workspace/slotTypes.ts +9 -0
  99. package/src/workspace/workspaceOps.test.ts +34 -1
  100. package/src/workspace/workspaceOps.ts +24 -0
  101. package/dist/chunk-2QNYYL3V.js.map +0 -1
  102. package/dist/chunk-2ZRE7WGQ.js.map +0 -1
  103. package/dist/chunk-3P56ZCCJ.js.map +0 -1
  104. package/dist/chunk-53XSBIUK.js.map +0 -1
  105. package/dist/chunk-54IQ2DX7.js.map +0 -1
  106. package/dist/chunk-7BKDG73Z.js.map +0 -1
  107. package/dist/chunk-HXZHVU4G.js.map +0 -1
  108. package/dist/chunk-PWC7AQZM.js.map +0 -1
  109. package/dist/chunk-R4TACNW7.js.map +0 -1
  110. package/src/lab/gridDims.test.ts +0 -35
  111. package/src/lab/gridDims.ts +0 -11
package/dist/index.d.ts CHANGED
@@ -1,42 +1,47 @@
1
1
  export { CanvasLayerDescriptor, CanvasStack, CanvasStackContext, CanvasStackContextValue, CanvasStackProps, screenToWorld, worldToScreen } from './canvas/index.js';
2
2
  export { ControlPanel } from './controls/index.js';
3
- import { C as ConfigField } from './_dts/types-Si4Fw-1F.js';
4
- export { a as CheckboxField, b as ColorField, c as ConfigFieldBase, d as ConfigFieldType, N as NumberField, S as SelectField, e as SelectOption, f as SliderField, T as TextField } from './_dts/types-Si4Fw-1F.js';
5
- import { I as Instrument } from './_dts/index-C6Yze7sQ.js';
6
- export { C as CanvasCapability, a as CanvasLayer, D as DragDropCapability, b as DragFeedback, H as HitResult, L as LayerCapability, c as LayerDescriptor, P as PaletteItem, d as Point, R as RenderContext, S as SystemEvent, U as UndoCapability, V as ViewTransform } from './_dts/index-C6Yze7sQ.js';
3
+ import { C as ConfigField } from './_dts/types-x92Kfeme.js';
4
+ export { a as CheckboxField, b as ColorField, c as ConfigFieldBase, d as ConfigFieldType, N as NumberField, S as SelectField, e as SelectOption, f as SliderField, T as TextField } from './_dts/types-x92Kfeme.js';
5
+ import { I as Instrument } from './_dts/index-CFlDPeZh.js';
6
+ export { C as CanvasCapability, a as CanvasLayer, D as DragDropCapability, b as DragFeedback, H as HitResult, L as LayerCapability, c as LayerDescriptor, P as PaletteItem, d as Point, R as RenderContext, S as SystemEvent, U as UndoCapability, V as ViewTransform } from './_dts/index-CFlDPeZh.js';
7
7
  import * as react_jsx_runtime from 'react/jsx-runtime';
8
8
  import * as react from 'react';
9
9
  import { ReactNode } from 'react';
10
- import { S as StorageAdapter, o as LabMode, W as WorkspaceRecord, e as SavedSnapshot } from './_dts/useExperimentState-CJn2hHzd.js';
11
- export { C as CreateLabStoreOptions, E as ExperimentStateHandle, b as LabStoreContext, c as LabStoreProvider, d as LabStoreState, U as UndoStack, f as WorkspaceIdContext, g as WorkspaceIdProvider, i as createMemoryAdapter, l as localStorageAdapter, n as noneAdapter, s as sessionStorageAdapter, u as urlHashAdapter, j as useExperimentState, k as useLabStore, m as useWorkspaceId } from './_dts/useExperimentState-CJn2hHzd.js';
10
+ import { S as StorageAdapter, o as LabMode, W as WorkspaceRecord, e as SavedSnapshot } from './_dts/useExperimentState-D7EQnnwJ.js';
11
+ export { C as CreateLabStoreOptions, E as ExperimentStateHandle, b as LabStoreContext, c as LabStoreProvider, d as LabStoreState, U as UndoStack, f as WorkspaceIdContext, g as WorkspaceIdProvider, i as createMemoryAdapter, l as localStorageAdapter, n as noneAdapter, s as sessionStorageAdapter, u as urlHashAdapter, j as useExperimentState, k as useLabStore, m as useWorkspaceId } from './_dts/useExperimentState-D7EQnnwJ.js';
12
12
  export { LayerList, LayerListProps } from './layers/index.js';
13
13
  export { FpsMeter, ScaleIndicator, ScaleIndicatorProps, Sidebar, SidebarProps, StatusBar, StatusBarProps, Toolbar, ToolbarProps } from './primitives/index.js';
14
14
  export { LayerStack, LayerStackItem, LayerStackProps } from './ui/layers/index.js';
15
15
  export { EventBus, EventListener, clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo/index.js';
16
16
  import 'zustand/vanilla';
17
17
 
18
+ /** Which optional capabilities an instrument declared — what the workspace
19
+ * consults to decide which chrome to show. */
18
20
  interface CapabilityFlags {
19
21
  hasCanvas: boolean;
20
22
  hasLayers: boolean;
21
23
  hasDragDrop: boolean;
22
24
  hasUndo: boolean;
23
25
  }
26
+ /** Read an instrument's declared capabilities off its definition. */
24
27
  declare function detectCapabilities(instrument: Instrument<unknown, unknown>): CapabilityFlags;
25
28
 
29
+ /** Identity at runtime; exists so an instrument's state and config types are
30
+ * inferred from the spec rather than having to be written out. */
26
31
  declare function defineInstrument<TS, TC>(spec: Instrument<TS, TC>): Instrument<TS, TC>;
27
32
 
33
+ /** Whether a config schema is usable, and every problem found rather than
34
+ * just the first. */
28
35
  interface ValidationResult {
29
36
  valid: boolean;
30
37
  errors: string[];
31
38
  }
39
+ /** Check a config schema for the mistakes that would otherwise surface as a
40
+ * silently broken control: empty or duplicate keys, unknown field types, and
41
+ * fields whose own constraints do not hold. */
32
42
  declare function validateConfigSchema(fields: ConfigField[]): ValidationResult;
33
43
 
34
- interface GridDims {
35
- cols: number;
36
- rows: number;
37
- }
38
- declare function gridDims(count: number): GridDims;
39
-
44
+ /** Props for `<Lab>`. */
40
45
  interface LabProps {
41
46
  instruments: Instrument[];
42
47
  defaultInstrument: string;
@@ -53,8 +58,13 @@ interface LabProps {
53
58
  title?: string;
54
59
  children?: ReactNode;
55
60
  }
61
+ /** The lab runtime: creates the store, provides it, and renders one workspace
62
+ * per record in a grid. Each workspace runs one of `instruments`. */
56
63
  declare function Lab({ instruments, defaultInstrument, storage, storageKey, mode, nebula, title, children, }: LabProps): react_jsx_runtime.JSX.Element;
57
64
 
65
+ /** Lab-wide state and commands: the available instruments, the open
66
+ * workspaces and the operations over them, saved snapshots, and the color
67
+ * mode. */
58
68
  interface LabContextValue {
59
69
  instruments: Instrument[];
60
70
  workspaces: WorkspaceRecord[];
@@ -62,6 +72,7 @@ interface LabContextValue {
62
72
  cloneWorkspace: (id: string) => void;
63
73
  closeWorkspace: (id: string) => void;
64
74
  resetWorkspace: (id: string) => void;
75
+ reorderWorkspaces: (ids: readonly string[]) => void;
65
76
  savedSnapshots: SavedSnapshot[];
66
77
  saveSnapshot: (workspaceId: string, name?: string) => void;
67
78
  loadSnapshot: (workspaceId: string, snapshotId: string) => void;
@@ -69,9 +80,12 @@ interface LabContextValue {
69
80
  mode: LabMode;
70
81
  setMode: (m: LabMode) => void;
71
82
  }
83
+ /** Context carrying the surrounding lab. Prefer `useLabContext`. */
72
84
  declare const LabContext: react.Context<LabContextValue | null>;
85
+ /** The surrounding lab. Throws outside a `<Lab>`. */
73
86
  declare function useLabContext(): LabContextValue;
74
87
 
88
+ /** Props for `<LabShell>`. */
75
89
  interface LabShellProps {
76
90
  title: string;
77
91
  children: ReactNode;
@@ -82,14 +96,73 @@ interface LabShellProps {
82
96
  /** Color mode. "auto" (default) follows prefers-color-scheme. */
83
97
  mode?: LabMode;
84
98
  }
99
+ /** Page frame for a lab: a titled header, a body, and an optional footer,
100
+ * themed for the resolved color mode. Presentational only — use `<Lab>` when
101
+ * the workspace runtime is wanted too. */
85
102
  declare function LabShell({ title, children, header, footer, mode }: LabShellProps): react_jsx_runtime.JSX.Element;
86
103
 
104
+ /** A tile's persisted extent, keyed by the id its caller gave it. Grid resizes
105
+ * write `span`; `size` is here because a strategy swap would write that. */
106
+ type WorkspaceLayout = Record<string, {
107
+ size?: {
108
+ w?: number;
109
+ h?: number;
110
+ };
111
+ span?: {
112
+ cols?: number;
113
+ rows?: number;
114
+ };
115
+ }>;
87
116
  interface WorkspaceGridProps {
88
117
  children: ReactNode;
118
+ /**
119
+ * Stable id per child, positionally matched. Supply these whenever a tile
120
+ * can be closed from the middle: without them a tile is identified by its
121
+ * position, so closing one shifts every id after it and the panes inherit
122
+ * each other's dragged extents. `layout` and `reorderable` both key off
123
+ * these, so neither means much without them.
124
+ */
125
+ ids?: readonly string[];
126
+ /** Draggable seams between tiles. Off by default — an even tiling is the
127
+ * behavior every existing caller has. */
128
+ resizable?: boolean;
129
+ /** Let a tile be dragged to a new position. Off by default. The grid never
130
+ * reorders `children` itself: it reports the order a drop would produce and
131
+ * the caller commits it. */
132
+ reorderable?: boolean;
133
+ /** The full id list a drop would produce, in its new order. */
134
+ onReorder?: (ids: string[]) => void;
135
+ /** Extents from a previous session, applied to tiles as they register. */
136
+ layout?: WorkspaceLayout;
137
+ /** Fires when a tile's extent changes. Persist it and hand it back as
138
+ * `layout` to make a resize survive a reload. */
139
+ onLayoutChange?: (layout: WorkspaceLayout) => void;
140
+ gap?: number;
141
+ padding?: number;
142
+ /**
143
+ * Fixed tiling extent. Omit in an app — the grid measures its own box. Supply
144
+ * it where nothing measures, notably jsdom: at a zero measurement the grid
145
+ * renders no tiles at all.
146
+ */
147
+ viewport?: {
148
+ w: number;
149
+ h: number;
150
+ };
89
151
  }
90
- declare function WorkspaceGrid({ children }: WorkspaceGridProps): react_jsx_runtime.JSX.Element;
152
+ /**
153
+ * Auto-balanced tiling of workspaces, `ceil(sqrt(n))` columns wide.
154
+ *
155
+ * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
156
+ * laid out by CSS — `windease/styles.css` (folded into
157
+ * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
158
+ */
159
+ declare function WorkspaceGrid({ children, ids, resizable, reorderable, onReorder, layout, onLayoutChange, gap, padding, viewport, }: WorkspaceGridProps): react_jsx_runtime.JSX.Element;
91
160
 
92
161
  type TokenValue = string | number | readonly (string | number)[];
162
+ /**
163
+ * A single design token as authored, before aliases are resolved: a DTCG-shaped
164
+ * `{ type, value }` pair where `value` may still be a `{ref}` to another token.
165
+ */
93
166
  interface RawToken {
94
167
  readonly type: string;
95
168
  readonly value: TokenValue;
@@ -97,8 +170,17 @@ interface RawToken {
97
170
  readonly alpha?: number | undefined;
98
171
  readonly description?: string | undefined;
99
172
  }
173
+ /** A token graph flattened to one level, keyed by token name (no `--wzl-`
174
+ * prefix). Still unresolved — see `ResolvedTokenMap` for the output side. */
100
175
  type FlatTokens = Record<string, RawToken>;
101
176
 
177
+ /**
178
+ * A theme: a named set of design tokens, organized into a mode-invariant layer
179
+ * plus one layer per mode (light, dark, …), optionally extending another theme.
180
+ * Tokens are held unresolved — aliases between them are collapsed later by
181
+ * `resolveTheme`, so an override of a base primitive still reaches everything
182
+ * that references it.
183
+ */
102
184
  interface Theme {
103
185
  readonly name: string;
104
186
  readonly extends: Theme | null;
@@ -114,6 +196,8 @@ interface Theme {
114
196
  */
115
197
  declare const interstellarTheme: Theme;
116
198
 
199
+ /** An annotation drawn over a curve plot: a shaded band across a range of x,
200
+ * or a vertical line at one x. */
117
201
  type CurveMark = {
118
202
  kind: 'band';
119
203
  x: [number, number];
@@ -123,6 +207,7 @@ type CurveMark = {
123
207
  x: number;
124
208
  color?: string;
125
209
  };
210
+ /** Props for `<CurveField>`. */
126
211
  interface CurveFieldProps {
127
212
  /** Flat [x0, y0, x1, y1, …] — matches how curve-as-array configs
128
213
  * serialize in JSON snapshots. */
@@ -148,12 +233,16 @@ interface CurveFieldProps {
148
233
  */
149
234
  declare function CurveField({ values, min, max, step, width, height, defaults, onChange, marks, }: CurveFieldProps): react_jsx_runtime.JSX.Element;
150
235
 
236
+ /** Props for `<Subpanel>`. */
151
237
  interface SubpanelProps {
152
238
  title: ReactNode;
153
239
  children: ReactNode;
154
240
  className?: string;
155
241
  }
242
+ /** A typographic divider inside a property list: a small title flanked by a
243
+ * rule. Purely a heading — use `<PropertyGroup>` for a bordered section. */
156
244
  declare function Subpanel({ title, children, className }: SubpanelProps): react_jsx_runtime.JSX.Element;
245
+ /** Props for `<EffectCard>`. */
157
246
  interface EffectCardProps {
158
247
  /** Card title rendered in the title bar (e.g. effect kind label or a select). */
159
248
  title: ReactNode;
@@ -183,10 +272,15 @@ interface EffectCardProps {
183
272
  children?: ReactNode;
184
273
  className?: string;
185
274
  }
275
+ /** An accented, collapsible card for one item in a list of like things —
276
+ * effects, layers, tails. The accent color rebinds the theme accent token
277
+ * within the card, so its controls pick it up too. */
186
278
  declare function EffectCard({ title, primary, accent, index, expanded, onToggleExpanded, onRemove, draggable, onPressHandle, onReleaseHandle, onDragStart, onDragEnd, onDragOver, onDragLeave, onDrop, dragging, children, className, }: EffectCardProps): react_jsx_runtime.JSX.Element;
279
+ /** The minimum an item must carry to appear in an `<EffectCardList>`. */
187
280
  interface EffectCardListItem {
188
281
  id: string | number;
189
282
  }
283
+ /** Props for `<EffectCardList>`. */
190
284
  interface EffectCardListProps<T extends EffectCardListItem> {
191
285
  items: ReadonlyArray<T>;
192
286
  renderItem: (item: T, helpers: {
@@ -201,8 +295,12 @@ interface EffectCardListProps<T extends EffectCardListItem> {
201
295
  /** IDs to render expanded on first mount. Defaults to all collapsed. */
202
296
  defaultExpandedIds?: ReadonlyArray<T['id']>;
203
297
  }
298
+ /** A drag-reorderable list of `<EffectCard>`s. Owns the expanded and dragging
299
+ * state and hands it back to `renderItem`, so the caller only supplies each
300
+ * card's contents. */
204
301
  declare function EffectCardList<T extends EffectCardListItem>({ items, renderItem, onReorder, empty, defaultExpandedIds, }: EffectCardListProps<T>): react_jsx_runtime.JSX.Element;
205
302
 
303
+ /** Props for `<PropertyGroup>`. */
206
304
  interface PropertyGroupProps {
207
305
  /** Title rendered between two rules at the top of the group. */
208
306
  title: ReactNode;
@@ -225,13 +323,18 @@ interface PropertyGroupProps {
225
323
  */
226
324
  declare function PropertyGroup({ title, hidden, children, className, pack, }: PropertyGroupProps): react_jsx_runtime.JSX.Element | null;
227
325
 
326
+ /** Props for `<PropertyPanel>`. */
228
327
  interface PropertyPanelProps {
229
328
  title?: ReactNode;
230
329
  children: ReactNode;
231
330
  className?: string;
232
331
  }
332
+ /** A titled panel holding property rows — the sidebar container the rest of
333
+ * this module's components fill. */
233
334
  declare function PropertyPanel({ title, children, className }: PropertyPanelProps): react_jsx_runtime.JSX.Element;
335
+ /** How a property list packs its rows into two columns. */
234
336
  type PropertyListPack = 'auto-color' | 'pairs';
337
+ /** Props for `<PropertyList>`. */
235
338
  interface PropertyListProps {
236
339
  children: ReactNode;
237
340
  className?: string;
@@ -250,8 +353,11 @@ interface PropertyListProps {
250
353
  * nest inside <PropertyPanel/> for the standard glass card.
251
354
  */
252
355
  declare function PropertyList({ children, className, pack }: PropertyListProps): react_jsx_runtime.JSX.Element;
356
+ /** Which control shape a row holds, which decides its intrinsic layout. */
253
357
  type PropertyRowVariant = 'default' | 'color' | 'checkbox';
358
+ /** Whether a row's label sits above its control or beside it. */
254
359
  type PropertyRowLayout = 'block' | 'inline';
360
+ /** Props for `<PropertyRow>`. */
255
361
  interface PropertyRowProps {
256
362
  label: ReactNode;
257
363
  /** Right-aligned readout shown next to the label (e.g. current value). */
@@ -267,7 +373,10 @@ interface PropertyRowProps {
267
373
  htmlFor?: string;
268
374
  className?: string;
269
375
  }
376
+ /** The label-plus-control frame every typed row below is built from. Use it
377
+ * directly for a control this module does not cover. */
270
378
  declare function PropertyRow({ label, readout, variant, layout, children, htmlFor, className, }: PropertyRowProps): react_jsx_runtime.JSX.Element;
379
+ /** Props for `<SliderRow>`. */
271
380
  interface SliderRowProps {
272
381
  label: ReactNode;
273
382
  value: number;
@@ -285,7 +394,10 @@ interface SliderRowProps {
285
394
  unit?: ReactNode;
286
395
  layout?: PropertyRowLayout;
287
396
  }
397
+ /** A bounded number edited by dragging, with a live readout whose precision
398
+ * follows `step`. */
288
399
  declare function SliderRow({ label, value, min, max, step, onChange, format, unit, layout, }: SliderRowProps): react_jsx_runtime.JSX.Element;
400
+ /** Props for `<ColorRow>`. */
289
401
  interface ColorRowProps {
290
402
  label: ReactNode;
291
403
  value: string;
@@ -299,13 +411,17 @@ interface ColorRowProps {
299
411
  */
300
412
  alphaDisabled?: boolean;
301
413
  }
414
+ /** A color swatch, optionally with an alpha slider beneath it. */
302
415
  declare function ColorRow({ label, value, onChange, alpha, onAlphaChange, alphaDisabled, }: ColorRowProps): react_jsx_runtime.JSX.Element;
416
+ /** Props for `<CheckboxRow>`. */
303
417
  interface CheckboxRowProps {
304
418
  label: ReactNode;
305
419
  value: boolean;
306
420
  onChange: (next: boolean) => void;
307
421
  }
422
+ /** A boolean checkbox. */
308
423
  declare function CheckboxRow({ label, value, onChange }: CheckboxRowProps): react_jsx_runtime.JSX.Element;
424
+ /** Props for `<TextRow>`. */
309
425
  interface TextRowProps {
310
426
  label: ReactNode;
311
427
  value: string;
@@ -314,7 +430,9 @@ interface TextRowProps {
314
430
  maxLength?: number;
315
431
  layout?: PropertyRowLayout;
316
432
  }
433
+ /** A single-line text input. */
317
434
  declare function TextRow({ label, value, onChange, placeholder, maxLength, layout }: TextRowProps): react_jsx_runtime.JSX.Element;
435
+ /** Props for `<NumberRow>`. */
318
436
  interface NumberRowProps {
319
437
  label: ReactNode;
320
438
  value: number;
@@ -325,11 +443,14 @@ interface NumberRowProps {
325
443
  placeholder?: string;
326
444
  layout?: PropertyRowLayout;
327
445
  }
446
+ /** A number typed directly. Reach for `<SliderRow>` when the range matters
447
+ * more than the exact value. */
328
448
  declare function NumberRow({ label, value, onChange, min, max, step, placeholder, layout, }: NumberRowProps): react_jsx_runtime.JSX.Element;
329
449
  interface SelectOption<T extends string> {
330
450
  value: T;
331
451
  label: ReactNode;
332
452
  }
453
+ /** Props for `<SelectRow>`. */
333
454
  interface SelectRowProps<T extends string> {
334
455
  label: ReactNode;
335
456
  value: T;
@@ -337,7 +458,10 @@ interface SelectRowProps<T extends string> {
337
458
  onChange: (next: T) => void;
338
459
  layout?: PropertyRowLayout;
339
460
  }
461
+ /** A dropdown over a fixed set of choices. Prefer `<ToggleRow>` when there
462
+ * are only two or three and they should all stay visible. */
340
463
  declare function SelectRow<T extends string>({ label, value, options, onChange, layout, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
464
+ /** Props for `<ToggleRow>`. */
341
465
  interface ToggleRowProps<T extends string> {
342
466
  label: ReactNode;
343
467
  value: T;
@@ -345,8 +469,12 @@ interface ToggleRowProps<T extends string> {
345
469
  onChange: (next: T) => void;
346
470
  layout?: PropertyRowLayout;
347
471
  }
472
+ /** A segmented control: the same choice as a select, with every option
473
+ * visible at once. */
348
474
  declare function ToggleRow<T extends string>({ label, value, options, onChange, layout, }: ToggleRowProps<T>): react_jsx_runtime.JSX.Element;
349
475
 
476
+ /** What a workspace hands its toolbar: which instrument is running, the undo
477
+ * state and commands, the zoom controls, and the snapshot commands. */
350
478
  interface WorkspaceToolbarContext {
351
479
  workspaceId: string;
352
480
  instrumentName: string;
@@ -369,6 +497,8 @@ interface WorkspaceToolbarContext {
369
497
  close: () => void;
370
498
  isLastWorkspace: boolean;
371
499
  }
500
+ /** What a workspace hands its sidebar: the instrument's config schema, its
501
+ * current values, and the setter. */
372
502
  interface WorkspaceSidebarContext {
373
503
  workspaceId: string;
374
504
  instrumentName: string;
@@ -376,33 +506,50 @@ interface WorkspaceSidebarContext {
376
506
  config: unknown;
377
507
  setConfig: (key: string, value: unknown) => void;
378
508
  }
509
+ /** What a workspace hands its status bar. */
379
510
  interface WorkspaceStatusBarContext {
380
511
  workspaceId: string;
381
512
  instrumentName: string;
382
513
  zoom: number;
383
514
  }
515
+ /** Replaces a workspace's toolbar. Receives everything the default one uses,
516
+ * so a custom toolbar need not reach into the store. */
384
517
  type ToolbarSlot = (ctx: WorkspaceToolbarContext) => ReactNode;
518
+ /** Replaces a workspace's sidebar. */
385
519
  type SidebarSlot = (ctx: WorkspaceSidebarContext) => ReactNode;
520
+ /** Replaces a workspace's status bar. */
386
521
  type StatusBarSlot = (ctx: WorkspaceStatusBarContext) => ReactNode;
387
522
 
523
+ /** Props for `<DefaultSidebar>`. */
388
524
  interface DefaultSidebarProps {
389
525
  ctx: WorkspaceSidebarContext;
390
526
  }
527
+ /** The sidebar a workspace renders when no `sidebar` slot is supplied: a
528
+ * control panel over the instrument's config schema. */
391
529
  declare function DefaultSidebar({ ctx }: DefaultSidebarProps): react_jsx_runtime.JSX.Element;
392
530
 
531
+ /** Props for `<DefaultStatusBar>`. */
393
532
  interface DefaultStatusBarProps {
394
533
  ctx: WorkspaceStatusBarContext;
395
534
  }
535
+ /** The status bar a workspace renders when no `statusBar` slot is supplied:
536
+ * the instrument's name and the current zoom. */
396
537
  declare function DefaultStatusBar({ ctx }: DefaultStatusBarProps): react_jsx_runtime.JSX.Element;
397
538
 
539
+ /** Props for `<DefaultToolbar>`. */
398
540
  interface DefaultToolbarProps {
399
541
  ctx: WorkspaceToolbarContext;
400
542
  }
543
+ /** The toolbar a workspace renders when no `toolbar` slot is supplied. Only
544
+ * shows the controls the instrument's declared capabilities support. */
401
545
  declare function DefaultToolbar({ ctx }: DefaultToolbarProps): react_jsx_runtime.JSX.Element;
402
546
 
547
+ /** Props for `<Workspace>`. */
403
548
  interface WorkspaceProps {
404
549
  id: string;
405
550
  }
551
+ /** Renders one workspace from the lab store: looks up its record and
552
+ * instrument, and mounts the instrument inside the workspace chrome. */
406
553
  declare function Workspace({ id }: WorkspaceProps): react_jsx_runtime.JSX.Element;
407
554
 
408
555
  interface UndoBindings {
@@ -411,6 +558,7 @@ interface UndoBindings {
411
558
  undo: () => void;
412
559
  redo: () => void;
413
560
  }
561
+ /** Props for `<WorkspaceChrome>`. */
414
562
  interface WorkspaceChromeProps {
415
563
  workspaceId: string;
416
564
  record: WorkspaceRecord;
@@ -423,12 +571,29 @@ interface WorkspaceChromeProps {
423
571
  sidebarExtras?: ReactNode;
424
572
  children: ReactNode;
425
573
  }
574
+ /** The frame around a running instrument — toolbar, sidebar, status bar —
575
+ * each replaceable by a slot. Assembles the slot contexts and wires the undo
576
+ * keyboard shortcuts. */
426
577
  declare function WorkspaceChrome({ workspaceId, record, instrument, isLastWorkspace, toolbar, sidebar, statusBar, undoBindings, sidebarExtras, children, }: WorkspaceChromeProps): react_jsx_runtime.JSX.Element;
427
578
 
579
+ /** Append a new workspace running `instrumentName`, at that instrument's
580
+ * default config and initial state. */
428
581
  declare function addWorkspace(workspaces: WorkspaceRecord[], instruments: Instrument[], instrumentName: string): WorkspaceRecord[];
582
+ /** Insert a deep copy of a workspace directly after it. The copy starts with
583
+ * an empty undo history — the original's is not shared. */
429
584
  declare function cloneWorkspace(workspaces: WorkspaceRecord[], id: string): WorkspaceRecord[];
585
+ /** Remove a workspace, unless it is the last one — a lab always has at least
586
+ * one. */
430
587
  declare function closeWorkspace(workspaces: WorkspaceRecord[], id: string): WorkspaceRecord[];
588
+ /** Return a workspace to its instrument's defaults, keeping its id and its
589
+ * place in the list. */
431
590
  declare function resetWorkspace(workspaces: WorkspaceRecord[], id: string, instruments: Instrument[]): WorkspaceRecord[];
591
+ /**
592
+ * Reorder to match `ids`. Ids the list doesn't mention keep their relative
593
+ * order at the end, and ids it names that no longer exist are dropped — a
594
+ * reorder that raced a close should not resurrect the closed workspace.
595
+ */
596
+ declare function reorderWorkspaces(workspaces: WorkspaceRecord[], ids: readonly string[]): WorkspaceRecord[];
432
597
 
433
- export { CheckboxRow, ColorRow, ConfigField, CurveField, DefaultSidebar, DefaultStatusBar, DefaultToolbar, EffectCard, EffectCardList, Instrument, Lab, LabContext, LabMode, LabShell, NumberRow, PropertyGroup, PropertyList, PropertyPanel, PropertyRow, SavedSnapshot, SelectRow, SliderRow, StorageAdapter, Subpanel, TextRow, ToggleRow, Workspace, WorkspaceChrome, WorkspaceGrid, WorkspaceRecord, addWorkspace, cloneWorkspace, closeWorkspace, defineInstrument, detectCapabilities, gridDims, interstellarTheme, resetWorkspace, useLabContext, validateConfigSchema };
434
- export type { CapabilityFlags, CheckboxRowProps, ColorRowProps, CurveFieldProps, CurveMark, DefaultSidebarProps, DefaultStatusBarProps, DefaultToolbarProps, EffectCardListItem, EffectCardListProps, EffectCardProps, GridDims, LabContextValue, LabProps, LabShellProps, NumberRowProps, PropertyGroupProps, PropertyListPack, PropertyListProps, PropertyPanelProps, PropertyRowLayout, PropertyRowProps, PropertyRowVariant, SelectRowProps, SidebarSlot, SliderRowProps, StatusBarSlot, SubpanelProps, TextRowProps, ToggleRowProps, ToolbarSlot, ValidationResult, WorkspaceChromeProps, WorkspaceGridProps, WorkspaceProps, WorkspaceSidebarContext, WorkspaceStatusBarContext, WorkspaceToolbarContext };
598
+ export { CheckboxRow, ColorRow, ConfigField, CurveField, DefaultSidebar, DefaultStatusBar, DefaultToolbar, EffectCard, EffectCardList, Instrument, Lab, LabContext, LabMode, LabShell, NumberRow, PropertyGroup, PropertyList, PropertyPanel, PropertyRow, SavedSnapshot, SelectRow, SliderRow, StorageAdapter, Subpanel, TextRow, ToggleRow, Workspace, WorkspaceChrome, WorkspaceGrid, WorkspaceRecord, addWorkspace, cloneWorkspace, closeWorkspace, defineInstrument, detectCapabilities, interstellarTheme, reorderWorkspaces, resetWorkspace, useLabContext, validateConfigSchema };
599
+ export type { CapabilityFlags, CheckboxRowProps, ColorRowProps, CurveFieldProps, CurveMark, DefaultSidebarProps, DefaultStatusBarProps, DefaultToolbarProps, EffectCardListItem, EffectCardListProps, EffectCardProps, LabContextValue, LabProps, LabShellProps, NumberRowProps, PropertyGroupProps, PropertyListPack, PropertyListProps, PropertyPanelProps, PropertyRowLayout, PropertyRowProps, PropertyRowVariant, SelectRowProps, SidebarSlot, SliderRowProps, StatusBarSlot, SubpanelProps, TextRowProps, ToggleRowProps, ToolbarSlot, ValidationResult, WorkspaceChromeProps, WorkspaceGridProps, WorkspaceProps, WorkspaceSidebarContext, WorkspaceStatusBarContext, WorkspaceToolbarContext };