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

package/src/primitives/Sidebar.less

@@ -2,8 +2,10 @@
   display: flex;
   flex-direction: column;
   width: 280px;
+  flex: 1 1 auto;
   background: var(--wzl-surface-raised);
-  border-left: 1px solid var(--wzl-border);
+  border-right: 1px solid var(--wzl-border);
+  min-height: 0;
   transition: width 150ms ease;
 
   &--collapsed {
@@ -21,7 +23,7 @@
 
 .lk-sidebar-title {
   flex: 1;
-  font-weight: 600;
+  font-weight: var(--wzl-font-weight-bold);
   color: var(--wzl-fg);
   font-size: var(--wzl-font-size);
 
@@ -55,3 +57,31 @@
     display: none;
   }
 }
+
+.lk-sidebar-section {
+  border-bottom: var(--wzl-border-w) solid var(--wzl-line-subtle);
+}
+
+.lk-sidebar-section__head {
+  width: 100%;
+  padding: var(--wzl-space-xs);
+  border: 0;
+  background: transparent;
+  color: var(--wzl-fg-muted);
+  font-family: var(--wzl-font-display);
+  font-size: var(--wzl-font-size-sm);
+  letter-spacing: 0.08em;
+  text-align: left;
+  text-transform: uppercase;
+  cursor: pointer;
+
+  &:hover {
+    color: var(--wzl-fg);
+  }
+}
+
+// The section body is the only thing that insets a panel — the panels
+// themselves carry no padding, so this is the whole gutter.
+.lk-sidebar-section__body {
+  padding: 0 var(--wzl-space-xs) var(--wzl-space-xs);
+}

package/src/primitives/StatusBar.less

@@ -18,4 +18,11 @@
   border-right: 1px solid var(--wzl-line-subtle);
 
   &:last-child { border-right: none; }
+
+  &--end {
+    margin-left: auto;
+  }
+
+  // A section pushed to the end already reads as separated by the gap.
+  &:has(+ &--end) { border-right: none; }
 }

package/src/primitives/StatusBar.tsx

@@ -10,11 +10,18 @@ export function StatusBar({ children }: StatusBarProps) {
   return <div className="lk-status-bar">{children}</div>;
 }
 
-interface SectionProps {
+/** Props for `<StatusBar.Section>`. */
+export interface StatusBarSectionProps {
   children: ReactNode;
+  /** Pushes this section, and everything after it, to the far end. */
+  end?: boolean;
 }
-function Section({ children }: SectionProps) {
-  return <span className="lk-status-bar-section">{children}</span>;
+function Section({ children, end }: StatusBarSectionProps) {
+  return (
+    <span className={`lk-status-bar-section${end ? ' lk-status-bar-section--end' : ''}`}>
+      {children}
+    </span>
+  );
 }
 
 /** One readout within a status bar. */

package/src/primitives/Toolbar.less

@@ -1,15 +1,20 @@
 .lk-toolbar {
+  // A trial toolbar is chrome around the instrument, not a page's own control
+  // strip, so it runs a compact control height. Overriding the token rather
+  // than the button keeps the slider and number field in step with it.
+  --wzl-control-h: 22px;
+
   display: flex;
   align-items: center;
   gap: var(--wzl-space-sm);
-  padding: var(--wzl-space-xs) var(--wzl-space-sm);
+  padding: 2px var(--wzl-space-sm);
   background: var(--wzl-surface-raised);
   border-bottom: 1px solid var(--wzl-border);
-  min-height: calc(var(--wzl-control-h) + 2 * var(--wzl-space-xs));
+  min-height: calc(var(--wzl-control-h) + 4px);
 }
 
 .lk-toolbar-title {
-  font-weight: 600;
+  font-weight: var(--wzl-font-weight-bold);
   color: var(--wzl-fg);
   margin-right: var(--wzl-space-sm);
 }
@@ -18,7 +23,35 @@
   flex: 1;
 }
 
+.lk-toolbar-group {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  min-width: 0;
+
+  // The rule belongs between groups, so it rides on the group rather than
+  // being a separate node the caller has to remember to interleave.
+  & + & {
+    padding-left: var(--wzl-space-sm);
+    border-left: 1px solid var(--wzl-line-subtle);
+  }
+
+  &--end {
+    margin-left: auto;
+  }
+
+  // A group pushed to the end already reads as separated by the gap.
+  &--end + &,
+  & + &--end {
+    border-left: none;
+    padding-left: 0;
+  }
+}
+
 .lk-toolbar-button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--wzl-space-xs);
   height: var(--wzl-control-h);
   padding: 0 var(--wzl-space-sm);
   font-size: var(--wzl-font-size);
@@ -27,15 +60,29 @@
   border: 1px solid transparent;
   border-radius: var(--wzl-radius-md);
   cursor: pointer;
+  white-space: nowrap;
+
+  &--icon {
+    padding: 0;
+    width: var(--wzl-control-h);
+    justify-content: center;
+  }
 
   &:hover:not(:disabled) {
     background: var(--wzl-surface);
     border-color: var(--wzl-border);
   }
+
+  &--danger:hover:not(:disabled) {
+    color: var(--wzl-danger);
+    border-color: var(--wzl-danger);
+  }
+
   &:focus-visible {
     outline: 2px solid var(--wzl-focus-ring);
     outline-offset: 1px;
   }
+
   &:disabled {
     color: var(--wzl-fg-subtle);
     cursor: not-allowed;

package/src/primitives/Toolbar.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import { describe, expect, test } from 'vitest';
 import { Toolbar } from './Toolbar';
 
@@ -63,3 +63,69 @@ describe('Toolbar', () => {
     expect(screen.getByRole('button', { name: 'X' })).toBeDisabled();
   });
 });
+
+function threeButtons() {
+  return render(
+    <Toolbar aria-label="Trial actions">
+      <Toolbar.Group aria-label="History">
+        <Toolbar.Button onClick={() => {}} title="Undo">
+          U
+        </Toolbar.Button>
+        <Toolbar.Button onClick={() => {}} title="Redo">
+          R
+        </Toolbar.Button>
+      </Toolbar.Group>
+      <Toolbar.Button onClick={() => {}} title="Close">
+        X
+      </Toolbar.Button>
+    </Toolbar>,
+  );
+}
+
+describe('Toolbar keyboard contract', () => {
+  test('claims the toolbar role and is nameable', () => {
+    threeButtons();
+    expect(screen.getByRole('toolbar', { name: 'Trial actions' })).toBeInTheDocument();
+  });
+
+  test('keeps exactly one button in the tab order', () => {
+    threeButtons();
+    const inOrder = screen.getAllByRole('button').filter((b) => b.tabIndex === 0);
+    expect(inOrder).toHaveLength(1);
+  });
+
+  test('keeps one tab stop when a button becomes enabled', async () => {
+    function Bar({ busy }: { busy: boolean }) {
+      return (
+        <Toolbar aria-label="Trial actions">
+          <Toolbar.Button onClick={() => {}} title="Undo" disabled={busy}>
+            U
+          </Toolbar.Button>
+          <Toolbar.Button onClick={() => {}} title="Close">
+            X
+          </Toolbar.Button>
+        </Toolbar>
+      );
+    }
+    const { rerender } = render(<Bar busy />);
+    rerender(<Bar busy={false} />);
+    await waitFor(() => {
+      const inOrder = screen
+        .getAllByRole<HTMLButtonElement>('button')
+        .filter((b) => !b.disabled && b.tabIndex === 0);
+      expect(inOrder).toHaveLength(1);
+    });
+  });
+
+  test('moves focus with the arrow keys, wrapping at the end', async () => {
+    const { default: userEvent } = await import('@testing-library/user-event');
+    const user = userEvent.setup();
+    threeButtons();
+    await user.tab();
+    expect(screen.getByTitle('Undo')).toHaveFocus();
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByTitle('Redo')).toHaveFocus();
+    await user.keyboard('{ArrowRight}{ArrowRight}');
+    expect(screen.getByTitle('Undo')).toHaveFocus();
+  });
+});

package/src/primitives/Toolbar.tsx

@@ -1,14 +1,29 @@
 import type { MouseEventHandler, ReactNode } from 'react';
+import { useRovingTabIndex } from './useRovingTabIndex';
 
 /** Props for `<Toolbar>`. */
 export interface ToolbarProps {
   children: ReactNode;
+  /** Names the toolbar for assistive tech. Required by the APG pattern when a
+   *  view holds more than one. */
+  'aria-label'?: string;
 }
 
 /** A horizontal bar of controls. Fill it with `<Toolbar.Title>`,
- *  `<Toolbar.Button>` and `<Toolbar.Spacer>`. */
-export function Toolbar({ children }: ToolbarProps) {
-  return <div className="lk-toolbar">{children}</div>;
+ *  `<Toolbar.Group>`, `<Toolbar.Button>` and `<Toolbar.Spacer>`. */
+export function Toolbar({ children, 'aria-label': ariaLabel }: ToolbarProps) {
+  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
+  return (
+    <div
+      ref={ref}
+      className="lk-toolbar"
+      role="toolbar"
+      aria-label={ariaLabel}
+      onKeyDown={onKeyDown}
+    >
+      {children}
+    </div>
+  );
 }
 
 interface TitleProps {
@@ -18,20 +33,69 @@ function Title({ children }: TitleProps) {
   return <span className="lk-toolbar-title">{children}</span>;
 }
 
-interface ButtonProps {
+/** Props for `<Toolbar.Group>`. */
+export interface ToolbarGroupProps {
+  children: ReactNode;
+  /** Pushes this group, and everything after it, to the far end. */
+  end?: boolean;
+  'aria-label'?: string;
+}
+
+/** Related controls, kept tight and ruled off from their neighbors. Group
+ *  rather than separate with repeated `<Toolbar.Spacer>`: consecutive spacers
+ *  share the free space, so every gap collapses to the same slack and the bar
+ *  reads as one undifferentiated run. */
+function Group({ children, end, 'aria-label': ariaLabel }: ToolbarGroupProps) {
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: a group inside role="toolbar" is the APG pattern; the rule is local and cannot see the parent. <fieldset> means form controls, needs a <legend> to be named, and its UA min-width breaks flex children.
+    <div
+      className={`lk-toolbar-group${end ? ' lk-toolbar-group--end' : ''}`}
+      role="group"
+      aria-label={ariaLabel}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Props for `<Toolbar.Button>`. */
+export interface ToolbarButtonProps {
   children: ReactNode;
   onClick: MouseEventHandler<HTMLButtonElement>;
   disabled?: boolean;
   title?: string;
+  /** Required when `children` is an icon with no text of its own. */
+  'aria-label'?: string;
+  /** `danger` reddens on hover — for actions that discard work. */
+  variant?: 'default' | 'danger';
+  /** Square, for a button whose whole content is one glyph. */
+  iconOnly?: boolean;
 }
-function Button({ children, onClick, disabled, title }: ButtonProps) {
+
+function Button({
+  children,
+  onClick,
+  disabled,
+  title,
+  'aria-label': ariaLabel,
+  variant = 'default',
+  iconOnly,
+}: ToolbarButtonProps) {
+  const cls = [
+    'lk-toolbar-button',
+    variant === 'danger' && 'lk-toolbar-button--danger',
+    iconOnly && 'lk-toolbar-button--icon',
+  ]
+    .filter(Boolean)
+    .join(' ');
   return (
     <button
       type="button"
-      className="lk-toolbar-button"
+      className={cls}
       onClick={onClick}
       disabled={disabled}
       title={title}
+      aria-label={ariaLabel ?? title}
     >
       {children}
     </button>
@@ -44,6 +108,8 @@ function Spacer() {
 
 /** A label within a toolbar. */
 Toolbar.Title = Title;
+/** A ruled-off run of related controls. */
+Toolbar.Group = Group;
 /** A button within a toolbar. */
 Toolbar.Button = Button;
 /** Flexible space that pushes what follows to the far end of the toolbar. */

package/src/primitives/ZoomControl.less

@@ -0,0 +1,31 @@
+.lk-zoom {
+  display: flex;
+  align-items: center;
+  gap: var(--wzl-space-sm);
+  min-width: 0;
+
+  &__slider {
+    flex: 0 1 108px;
+  }
+
+  &__field {
+    flex: 0 0 auto;
+  }
+}
+
+// Both children are weasel-ui components whose module classes set `width`.
+// See the `.lk-root` prefix convention in theme/base.less.
+.lk-root {
+  .lk-zoom {
+    // Narrow enough to sit in a trial toolbar, wide enough for the octave
+    // detents to be separately hittable.
+    &__slider {
+      width: 108px;
+      min-width: 64px;
+    }
+
+    &__field {
+      width: 62px;
+    }
+  }
+}

package/src/primitives/ZoomControl.tsx

@@ -0,0 +1,76 @@
+import { NumberField, Slider } from '../passthrough/weasel-ui';
+
+/** Props for `<ZoomControl>`. */
+export interface ZoomControlProps {
+  /** Current zoom as a scale factor: 1 is actual size. */
+  zoom: number;
+  /** Fired continuously while the slider drags. */
+  onZoomChange: (zoom: number) => void;
+  /** Fired when a drag settles or the field is committed. Defaults to
+   *  `onZoomChange`. */
+  onZoomCommit?: (zoom: number) => void;
+  /** Smallest selectable zoom. Defaults to 0.1 (10%). */
+  min?: number;
+  /** Largest selectable zoom. Defaults to 8 (800%). */
+  max?: number;
+  className?: string;
+}
+
+// Zoom is perceptually geometric — halving is as big a step as doubling — so
+// the slider runs on log2 and 100% lands mid-track for a symmetric range.
+const toTrack = (zoom: number): number => Math.log2(zoom);
+const fromTrack = (v: number): number => 2 ** v;
+
+const clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, v));
+
+/** Zoom as a log-scaled slider with an editable percentage beside it. Pair it
+ *  with zoom-in / zoom-out buttons in a `<Toolbar.Group>`; this component owns
+ *  only the continuous part. */
+export function ZoomControl({
+  zoom,
+  onZoomChange,
+  onZoomCommit,
+  min = 0.1,
+  max = 8,
+  className,
+}: ZoomControlProps) {
+  const commit = onZoomCommit ?? onZoomChange;
+  const emit = (track: number, done: boolean): void => {
+    const next = clamp(fromTrack(track), min, max);
+    (done ? commit : onZoomChange)(next);
+  };
+
+  return (
+    <div className={`lk-zoom${className ? ` ${className}` : ''}`}>
+      <Slider
+        className="lk-zoom__slider"
+        ariaLabel="Zoom"
+        min={toTrack(min)}
+        max={toTrack(max)}
+        // Detents at the octaves plus actual size, so 25/50/100/200/400% are
+        // reachable by drag rather than only by typing.
+        stops={[-2, -1, 0, 1, 2]}
+        thumbs={[{ value: clamp(toTrack(zoom), toTrack(min), toTrack(max)) }]}
+        onInput={(next) => emit(next[0].value, false)}
+        onChange={(next) => emit(next[0].value, true)}
+        readoutPlacement="none"
+      />
+      {/* `style: 'percent'` formats a fraction, so the field carries the scale
+          factor itself and renders 0.5 as "50%". */}
+      <NumberField
+        className="lk-zoom__field"
+        aria-label="Zoom"
+        value={zoom}
+        minValue={min}
+        maxValue={max}
+        step={0.01}
+        hideSteppers
+        formatOptions={{ style: 'percent', maximumFractionDigits: 0 }}
+        onChange={(next) => {
+          if (!Number.isFinite(next)) return;
+          commit(clamp(next, min, max));
+        }}
+      />
+    </div>
+  );
+}

package/src/primitives/floating.entry.test.tsx

@@ -0,0 +1,14 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { FloatingPanel, Legend } from '../index';
+
+describe('floating public entry', () => {
+  it('reaches a consumer from the package entry point alone', () => {
+    const { container } = render(
+      <FloatingPanel>
+        <Legend entries={[{ key: 'a', label: 'a', color: '#fff' }]} />
+      </FloatingPanel>,
+    );
+    expect(container.querySelector('.lk-floating-panel .lk-legend')).toBeInTheDocument();
+  });
+});

package/src/primitives/index.ts

@@ -1,9 +1,17 @@
+export type { FloatingPanelProps } from './FloatingPanel';
+export { FloatingPanel } from './FloatingPanel';
 export { FpsMeter } from './FpsMeter';
+export type { JobProgressProps } from './JobProgress';
+export { JobProgress } from './JobProgress';
+export type { LegendEntry, LegendMark, LegendProps } from './Legend';
+export { Legend } from './Legend';
 export type { ScaleIndicatorProps } from './ScaleIndicator';
 export { ScaleIndicator } from './ScaleIndicator';
 export type { SidebarProps } from './Sidebar';
 export { Sidebar } from './Sidebar';
-export type { StatusBarProps } from './StatusBar';
+export type { StatusBarProps, StatusBarSectionProps } from './StatusBar';
 export { StatusBar } from './StatusBar';
-export type { ToolbarProps } from './Toolbar';
+export type { ToolbarButtonProps, ToolbarGroupProps, ToolbarProps } from './Toolbar';
 export { Toolbar } from './Toolbar';
+export type { ZoomControlProps } from './ZoomControl';
+export { ZoomControl } from './ZoomControl';

package/src/primitives/useRovingTabIndex.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { nextIndex } from './useRovingTabIndex';
+
+describe('nextIndex', () => {
+  it('steps forward and wraps', () => {
+    expect(nextIndex(0, 'ArrowRight', 3)).toBe(1);
+    expect(nextIndex(2, 'ArrowRight', 3)).toBe(0);
+  });
+
+  it('steps back and wraps', () => {
+    expect(nextIndex(1, 'ArrowLeft', 3)).toBe(0);
+    expect(nextIndex(0, 'ArrowLeft', 3)).toBe(2);
+  });
+
+  it('jumps to the ends', () => {
+    expect(nextIndex(1, 'Home', 3)).toBe(0);
+    expect(nextIndex(1, 'End', 3)).toBe(2);
+  });
+
+  it('returns null for a key it does not handle', () => {
+    expect(nextIndex(1, 'Enter', 3)).toBeNull();
+  });
+
+  it('returns null when there is nothing to move to', () => {
+    expect(nextIndex(0, 'ArrowRight', 0)).toBeNull();
+  });
+});

package/src/primitives/useRovingTabIndex.ts

@@ -0,0 +1,79 @@
+import { type KeyboardEvent, useCallback, useEffect, useRef } from 'react';
+
+/** Where a key takes focus within `count` items, or null if it does not move it. */
+export function nextIndex(current: number, key: string, count: number): number | null {
+  if (count === 0) return null;
+  switch (key) {
+    case 'ArrowRight':
+      return (current + 1) % count;
+    case 'ArrowLeft':
+      return (current - 1 + count) % count;
+    case 'Home':
+      return 0;
+    case 'End':
+      return count - 1;
+    default:
+      return null;
+  }
+}
+
+/**
+ * The APG roving-tabindex contract: exactly one item in the tab order, arrows
+ * moving focus within. `tabIndex` is written onto the DOM nodes rather than
+ * threaded through props, because the items are arbitrary children — the
+ * container never sees them as a list it could index.
+ */
+export function useRovingTabIndex<T extends HTMLElement>() {
+  const ref = useRef<T | null>(null);
+  const stop = useRef(0);
+
+  const items = useCallback(
+    (): HTMLElement[] =>
+      ref.current
+        ? Array.from(
+            ref.current.querySelectorAll<HTMLElement>('button:not([disabled]), [role="button"]'),
+          )
+        : [],
+    [],
+  );
+
+  const setTabStop = useCallback(
+    (index: number) => {
+      const found = items();
+      const at = Math.min(Math.max(index, 0), Math.max(found.length - 1, 0));
+      stop.current = at;
+      for (const [i, el] of found.entries()) el.tabIndex = i === at ? 0 : -1;
+    },
+    [items],
+  );
+
+  // Re-establish the tab stop whenever the item set changes — a trial's toolbar
+  // contributions are dynamic, and `disabled` moves a button in and out of the
+  // set without touching the child list. The focused item keeps the stop.
+  useEffect(() => {
+    const resync = () => {
+      const focused = items().indexOf(document.activeElement as HTMLElement);
+      setTabStop(focused === -1 ? stop.current : focused);
+    };
+    resync();
+    if (!ref.current) return;
+    const mo = new MutationObserver(resync);
+    mo.observe(ref.current, { childList: true, subtree: true, attributeFilter: ['disabled'] });
+    return () => mo.disconnect();
+  }, [items, setTabStop]);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<T>) => {
+      const found = items();
+      const current = found.indexOf(document.activeElement as HTMLElement);
+      const next = nextIndex(current === -1 ? 0 : current, e.key, found.length);
+      if (next === null) return;
+      e.preventDefault();
+      found[next]?.focus();
+      setTabStop(next);
+    },
+    [items, setTabStop],
+  );
+
+  return { ref, onKeyDown };
+}

package/src/state/store.ts

@@ -39,6 +39,8 @@ export interface LabStoreActions {
   deleteSnapshot: (snapshotId: string) => void;
   listSnapshots: (trialId?: string) => SavedSnapshot[];
   setMode: (mode: LabMode) => void;
+  setLabTool: (id: string | null) => void;
+  setTrialTool: (trialId: string, id: string | null) => void;
   setLayout: (layout: Record<string, unknown>) => void;
 }
 
@@ -70,6 +72,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     savedSnapshots: hydratedSnapshots,
     mode: hydratedMode,
     layout: hydratedLayout,
+    activeToolId: null,
 
     addTrial: (record) => {
       set((s) => ({
@@ -114,9 +117,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
 
     updateTrialView: (id, view) => {
       set((s) => ({
-        trials: s.trials.map((w) =>
-          w.id === id && !Object.is(view, w.view) ? { ...w, view } : w,
-        ),
+        trials: s.trials.map((w) => (w.id === id && !Object.is(view, w.view) ? { ...w, view } : w)),
       }));
       scheduleFlush();
     },
@@ -203,6 +204,13 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
+    setLabTool: (id) => set({ activeToolId: id }),
+
+    setTrialTool: (trialId, id) =>
+      set((s) => ({
+        trials: s.trials.map((t) => (t.id === trialId ? { ...t, activeToolId: id } : t)),
+      })),
+
     setLayout: (layout) => {
       set({ layout });
       scheduleFlush();