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

package/src/primitives/JobProgress.tsx

@@ -0,0 +1,65 @@
+import { ErrorIcon, WarningIcon } from '@weasel-js/ui';
+import type { JobHandle } from '../job/types';
+
+/** Props for `<JobProgress>`. */
+export interface JobProgressProps {
+  job: JobHandle;
+  className?: string;
+}
+
+/** A running job's progress, failures and outcome. Determinate once the job
+ *  reports a total; a job that cannot count up front never sends one, so the
+ *  bar stays indeterminate rather than inventing a denominator. */
+export function JobProgress({ job, className }: JobProgressProps) {
+  const { status, done, total, failures, error } = job;
+  if (status === 'idle') return null;
+
+  const determinate = total !== null && total > 0;
+  const fraction = determinate ? Math.min(1, done / total) : 0;
+  const cls = ['lk-job', `lk-job--${status}`, className].filter(Boolean).join(' ');
+
+  return (
+    <div className={cls}>
+      <div
+        className={`lk-job__track${determinate ? '' : ' lk-job__track--indeterminate'}`}
+        role="progressbar"
+        aria-label="Job progress"
+        aria-valuenow={determinate ? done : undefined}
+        aria-valuemin={determinate ? 0 : undefined}
+        aria-valuemax={determinate ? total : undefined}
+      >
+        {/* Scaling a full-width bar keeps the fill off the layout path, so
+            progress updates never reflow the status bar. */}
+        <div
+          className="lk-job__fill"
+          style={{ transform: `scaleX(${determinate ? fraction : 1})` }}
+        />
+      </div>
+
+      <span className="lk-job__count">
+        {done}
+        {determinate ? ` / ${total}` : ''}
+      </span>
+
+      {failures.length > 0 && (
+        <span className="lk-job__failures" title={failures.map((f) => f.error).join('\n')}>
+          <WarningIcon size={14} />
+          {failures.length} failed
+        </span>
+      )}
+
+      {error && (
+        <span className="lk-job__error" title={error}>
+          <ErrorIcon size={14} />
+          {error}
+        </span>
+      )}
+
+      {status === 'running' && (
+        <button type="button" className="lk-job__cancel" onClick={job.cancel}>
+          Cancel
+        </button>
+      )}
+    </div>
+  );
+}

package/src/primitives/Legend.less

@@ -0,0 +1,47 @@
+.lk-legend {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-family: var(--wzl-font-mono);
+  font-size: var(--wzl-font-size-sm);
+  line-height: 1.4;
+  color: var(--wzl-fg-muted);
+}
+
+.lk-legend__row {
+  display: flex;
+  align-items: center;
+  gap: var(--wzl-space-sm);
+  padding: 1px 0;
+  white-space: nowrap;
+}
+
+.lk-legend__swatch {
+  flex: none;
+  width: 15px;
+}
+
+.lk-legend__swatch--line {
+  height: 4px;
+  border-radius: var(--wzl-radius-sm);
+  background: var(--lk-legend-ink);
+}
+
+.lk-legend__swatch--dash {
+  height: 0;
+  border-top: 2px dashed var(--lk-legend-ink);
+}
+
+.lk-legend__swatch--dot {
+  width: 6px;
+  height: 6px;
+  margin: 0 4px 0 5px;
+  border-radius: 50%;
+  background: var(--lk-legend-ink);
+}
+
+.lk-legend__swatch--band {
+  height: 9px;
+  border-radius: var(--wzl-radius-sm);
+  background: var(--lk-legend-ink);
+}

package/src/primitives/Legend.stories.tsx

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Legend } from './Legend';
+
+const meta: Meta<typeof Legend> = {
+  title: 'labkit/Primitives/Legend',
+  component: Legend,
+};
+export default meta;
+
+type Story = StoryObj<typeof Legend>;
+
+export const AllMarks: Story = {
+  args: {
+    entries: [
+      { key: 'contour', label: 'contour', color: '#7d7f86' },
+      { key: 'floor', label: 'bend floor', color: '#9a9ca3', mark: 'dash' },
+      { key: 'authored', label: 'authored', color: '#2aa87a', mark: 'dot' },
+      { key: 'replaced', label: 'replaced', color: 'rgba(255,107,96,.28)', mark: 'band' },
+    ],
+  },
+};
+
+export const DefaultMark: Story = {
+  args: {
+    entries: [
+      { key: 'a', label: 'input', color: '#4c9be8' },
+      { key: 'b', label: 'output', color: '#e8a04c' },
+    ],
+  },
+};
+
+export const Empty: Story = { args: { entries: [] } };

package/src/primitives/Legend.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { Legend } from './Legend';
+
+const entries = [
+  { key: 'contour', label: 'contour', color: '#7d7f86' },
+  { key: 'floor', label: 'bend floor', color: '#9a9ca3', mark: 'dash' as const },
+  { key: 'authored', label: 'authored', color: '#2aa87a', mark: 'dot' as const },
+  { key: 'replaced', label: 'replaced', color: 'rgba(255,107,96,.28)', mark: 'band' as const },
+];
+
+describe('Legend', () => {
+  it('renders one row per entry', () => {
+    const { container } = render(<Legend entries={entries} />);
+    expect(container.querySelectorAll('.lk-legend__row')).toHaveLength(4);
+  });
+
+  it('shows every label as text', () => {
+    render(<Legend entries={entries} />);
+    for (const e of entries) expect(screen.getByText(e.label)).toBeInTheDocument();
+  });
+
+  it('marks each swatch with its shape, defaulting to a line', () => {
+    const { container } = render(<Legend entries={entries} />);
+    const swatches = container.querySelectorAll('.lk-legend__swatch');
+    expect(swatches[0]?.className).toContain('lk-legend__swatch--line');
+    expect(swatches[1]?.className).toContain('lk-legend__swatch--dash');
+    expect(swatches[2]?.className).toContain('lk-legend__swatch--dot');
+    expect(swatches[3]?.className).toContain('lk-legend__swatch--band');
+  });
+
+  it('hides swatches from assistive tech, leaving the label to carry meaning', () => {
+    const { container } = render(<Legend entries={entries} />);
+    for (const s of container.querySelectorAll('.lk-legend__swatch')) {
+      expect(s.getAttribute('aria-hidden')).toBe('true');
+    }
+  });
+
+  it('takes its color from the entry', () => {
+    const { container } = render(
+      <Legend entries={[{ key: 'contour', label: 'contour', color: '#7d7f86' }]} />,
+    );
+    const swatch = container.querySelector('.lk-legend__swatch') as HTMLElement;
+    expect(swatch.style.getPropertyValue('--lk-legend-ink')).toBe('#7d7f86');
+  });
+
+  it('renders nothing but an empty list for no entries', () => {
+    const { container } = render(<Legend entries={[]} />);
+    expect(container.querySelectorAll('.lk-legend__row')).toHaveLength(0);
+    expect(container.querySelector('.lk-legend')).toBeInTheDocument();
+  });
+
+  it('accepts an extra class name', () => {
+    const { container } = render(<Legend entries={[]} className="is-mine" />);
+    expect(container.querySelector('.lk-legend')?.className).toContain('is-mine');
+  });
+});

package/src/primitives/Legend.tsx

@@ -0,0 +1,40 @@
+import type { CSSProperties } from 'react';
+
+/** How a legend entry's swatch is drawn, matching how the thing looks on canvas. */
+export type LegendMark = 'line' | 'dash' | 'dot' | 'band';
+
+/** One row of a legend: a swatch and what it means. */
+export interface LegendEntry {
+  key: string;
+  label: string;
+  color: string;
+  /** Defaults to `'line'`. */
+  mark?: LegendMark;
+}
+
+/** Props for `<Legend>`. */
+export interface LegendProps {
+  entries: readonly LegendEntry[];
+  className?: string;
+}
+
+/** A color key. Presentational only — no handlers, no state, no hover behavior. */
+export function Legend({ entries, className }: LegendProps) {
+  return (
+    <ul className={className ? `lk-legend ${className}` : 'lk-legend'}>
+      {entries.map((entry) => {
+        const mark = entry.mark ?? 'line';
+        return (
+          <li className="lk-legend__row" key={entry.key}>
+            <span
+              aria-hidden="true"
+              className={`lk-legend__swatch lk-legend__swatch--${mark}`}
+              style={{ '--lk-legend-ink': entry.color } as CSSProperties}
+            />
+            <span className="lk-legend__label">{entry.label}</span>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

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;
+    }
+  }
+}