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

package/src/primitives/FloatingPanel.tsx

@@ -0,0 +1,190 @@
+import type React from 'react';
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  type Corner,
+  DEFAULT_ANCHOR,
+  DEFAULT_INSET,
+  FLOATING_DRAG_PREFIX,
+  type FloatingPlacement,
+  floatingStrategy,
+} from 'windease';
+
+/** The strategy holds a map keyed by item id; a panel is always a lone item. */
+const ITEM_ID = 'panel';
+
+/** Props for `<FloatingPanel>`. */
+export interface FloatingPanelProps {
+  children: ReactNode;
+  /** Corner it rests in before it has ever been dragged. Default `'bottom-left'`. */
+  anchor?: Corner;
+  /** Corners that may capture it. Default: all four. */
+  snapCorners?: readonly Corner[];
+  /** Pixels in from a corner when snapped. Default 12. */
+  inset?: number;
+  /** localStorage key to remember its position under. Omit to forget on reload. */
+  storageKey?: string;
+  className?: string;
+}
+
+/**
+ * The panel's footprint is its border box — `contentRect` excludes padding and
+ * border, which would place a panel that then overflows its corner by exactly
+ * that much.
+ */
+function borderBoxOf(entry: ResizeObserverEntry): { w: number; h: number } {
+  const box = entry.borderBoxSize?.[0];
+  if (box) return { w: box.inlineSize, h: box.blockSize };
+  return { w: entry.contentRect.width, h: entry.contentRect.height };
+}
+
+/** A pointerdown on one of these is the child's, not a drag. */
+function isInteractive(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  return target.closest('input, button, a, select, textarea, [data-no-drag]') !== null;
+}
+
+function readStored(key: string | undefined): FloatingPlacement | null {
+  if (!key) return null;
+  try {
+    const raw = localStorage.getItem(key);
+    return raw ? (JSON.parse(raw) as FloatingPlacement) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A draggable box that floats over its offset parent and snaps to its corners.
+ *
+ * Drives windease's `floatingStrategy` as a pure function rather than mounting a
+ * windease container: a lab overlay has one item and no zone tree, so the node
+ * model would be all cost. Pointer handling is therefore this component's, and
+ * windease's own affordance rendering never participates.
+ */
+export function FloatingPanel({
+  children,
+  anchor = DEFAULT_ANCHOR,
+  snapCorners,
+  inset = DEFAULT_INSET,
+  storageKey,
+  className,
+}: FloatingPanelProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const strategy = useMemo(() => floatingStrategy(), []);
+  const options = useMemo(() => ({ defaultAnchor: anchor, inset }), [anchor, inset]);
+
+  const [container, setContainer] = useState({ w: 0, h: 0 });
+  const [size, setSize] = useState({ w: 0, h: 0 });
+  const [place, setPlace] = useState<FloatingPlacement>(
+    () => readStored(storageKey) ?? { x: 0, y: 0, anchor },
+  );
+
+  useEffect(() => {
+    if (!storageKey) return;
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(place));
+    } catch {
+      // A full or disabled store is not worth failing a lab over.
+    }
+  }, [place, storageKey]);
+
+  const item = useMemo(
+    () => ({
+      id: ITEM_ID,
+      meta: { floating: true, ...(snapCorners ? { snapCorners: [...snapCorners] } : {}) },
+      natural: size,
+    }),
+    [size, snapCorners],
+  );
+
+  useEffect(() => {
+    const el = ref.current;
+    const parent = el?.offsetParent ?? el?.parentElement;
+    if (!el || !parent) return;
+    // Sizes come off the entry, not the DOM: jsdom reports 0 for every
+    // clientWidth/offsetWidth, and an unmeasured item is withheld from layout.
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.target === parent) {
+          setContainer({ w: entry.contentRect.width, h: entry.contentRect.height });
+        } else {
+          setSize(borderBoxOf(entry));
+        }
+      }
+    });
+    observer.observe(parent);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const rect = strategy
+    .layout({
+      items: [item],
+      container,
+      state: { at: { [ITEM_ID]: place }, inner: undefined },
+      options,
+    })
+    .placements.get(ITEM_ID);
+
+  const dragging = useRef<{ x: number; y: number } | null>(null);
+  const [isDragging, setDragging] = useState(false);
+
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (isInteractive(e.target)) return;
+    // The canvas stack underneath owns pan/zoom on the same pointer events.
+    e.stopPropagation();
+    dragging.current = { x: e.clientX, y: e.clientY };
+    setDragging(true);
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+  };
+
+  const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const from = dragging.current;
+    if (!from) return;
+    const dx = e.clientX - from.x;
+    const dy = e.clientY - from.y;
+    if (dx === 0 && dy === 0) return;
+    dragging.current = { x: e.clientX, y: e.clientY };
+    setPlace(
+      (prev) =>
+        strategy.reduce?.(
+          { at: { [ITEM_ID]: prev }, inner: undefined },
+          {
+            affordanceId: `${FLOATING_DRAG_PREFIX}${ITEM_ID}`,
+            kind: 'drag',
+            payload: { dx, dy },
+          },
+          { container, options, items: [item] },
+        ).at[ITEM_ID] ?? prev,
+    );
+  };
+
+  const endDrag = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (!dragging.current) return;
+    dragging.current = null;
+    setDragging(false);
+    e.currentTarget.releasePointerCapture?.(e.pointerId);
+  };
+
+  return (
+    <div
+      className={className ? `lk-floating-panel ${className}` : 'lk-floating-panel'}
+      data-dragging={isDragging ? 'true' : undefined}
+      data-placed={rect ? 'true' : undefined}
+      onPointerCancel={endDrag}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={endDrag}
+      ref={ref}
+      style={
+        {
+          position: 'absolute',
+          left: `${rect?.x ?? 0}px`,
+          top: `${rect?.y ?? 0}px`,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </div>
+  );
+}

package/src/primitives/FpsMeter.test.tsx

@@ -35,4 +35,48 @@ describe('FpsMeter', () => {
 
     vi.unstubAllGlobals();
   });
+
+  test('does not report a fabricated rate after a spell in a background tab', () => {
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      frames.push(cb);
+      return frames.length;
+    });
+    vi.stubGlobal('cancelAnimationFrame', () => {});
+    const setHidden = (next: boolean) => {
+      Object.defineProperty(document, 'hidden', { configurable: true, get: () => next });
+      document.dispatchEvent(new Event('visibilitychange'));
+    };
+
+    const run = (t: number) => {
+      const due = frames.splice(0, frames.length);
+      for (const cb of due) cb(t);
+    };
+
+    render(<FpsMeter />);
+    act(() => {
+      run(0);
+      run(16.67);
+      run(33.34);
+    });
+    const before = screen.getByText(/FPS\s+\d+/).textContent;
+
+    // An hour hidden. The frame that lands on resume is not a 60-minute frame,
+    // and must not enter the rolling average as one.
+    act(() => {
+      setHidden(true);
+    });
+    act(() => {
+      setHidden(false);
+    });
+    act(() => {
+      run(3_600_000);
+      run(3_600_016.67);
+    });
+
+    expect(screen.getByText(/FPS\s+\d+/).textContent).toBe(before);
+
+    setHidden(false);
+    vi.unstubAllGlobals();
+  });
 });

package/src/primitives/FpsMeter.tsx

@@ -1,3 +1,4 @@
+import { useVisibleRaf } from '@weasel-js/core';
 import { useEffect, useRef, useState } from 'react';
 import { rollingAverage } from './fpsAverage';
 
@@ -8,10 +9,10 @@ export function FpsMeter() {
   const [fps, setFps] = useState(0);
   const samplesRef = useRef<number[]>([]);
   const lastTimeRef = useRef<number | null>(null);
+  const rootRef = useRef<HTMLDivElement | null>(null);
 
-  useEffect(() => {
-    let rafId = 0;
-    const tick = (time: number) => {
+  const loop = useVisibleRaf(
+    (time) => {
       const last = lastTimeRef.current;
       if (last !== null) {
         const delta = time - last;
@@ -23,14 +24,24 @@ export function FpsMeter() {
         }
       }
       lastTimeRef.current = time;
-      rafId = requestAnimationFrame(tick);
-    };
-    rafId = requestAnimationFrame(tick);
-    return () => cancelAnimationFrame(rafId);
-  }, []);
+      loop.request();
+    },
+    {
+      target: rootRef,
+      // The gap spent suspended is not a frame that took an hour to draw.
+      onResume: () => {
+        lastTimeRef.current = null;
+      },
+    },
+  );
+
+  useEffect(() => {
+    loop.request();
+    return () => loop.cancel();
+  }, [loop]);
 
   return (
-    <div className="lk-fps-meter">
+    <div className="lk-fps-meter" ref={rootRef}>
       <span className="lk-fps-meter-value">FPS {fps}</span>
     </div>
   );

package/src/primitives/JobProgress.less

@@ -0,0 +1,69 @@
+.lk-job {
+  display: flex;
+  align-items: center;
+  gap: var(--wzl-space-sm);
+  min-width: 0;
+  font-size: var(--wzl-font-size-sm);
+  color: var(--wzl-fg-muted);
+
+  &__track {
+    flex: 0 1 120px;
+    height: 3px;
+    border-radius: var(--wzl-radius-pill);
+    overflow: hidden;
+    background: color-mix(in srgb, currentColor 18%, transparent);
+  }
+
+  &__fill {
+    height: 100%;
+    background: var(--wzl-accent);
+    transform-origin: left center;
+    transition: transform 120ms linear;
+  }
+
+  // A job that never reports a total sweeps instead of filling, so the bar
+  // says "working" without implying a position.
+  &__track--indeterminate &__fill,
+  &__track--indeterminate > .lk-job__fill {
+    animation: lk-job-sweep 1.1s ease-in-out infinite;
+    transform-origin: center;
+  }
+
+  &__count {
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+  }
+
+  &__failures,
+  &__error {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__failures { color: var(--wzl-warning); }
+  &__error { color: var(--wzl-danger); }
+
+  &__cancel {
+    height: 20px;
+    padding: 0 var(--wzl-space-sm);
+    font-size: var(--wzl-font-size-sm);
+  }
+
+  &--error &__fill { background: var(--wzl-danger); }
+  &--done &__fill { background: color-mix(in srgb, var(--wzl-accent) 55%, transparent); }
+}
+
+@keyframes lk-job-sweep {
+  0%   { transform: scaleX(0.15) translateX(-260%); }
+  50%  { transform: scaleX(0.5) translateX(0); }
+  100% { transform: scaleX(0.15) translateX(260%); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .lk-job__track--indeterminate > .lk-job__fill { animation: none; transform: scaleX(0.35); }
+}

package/src/primitives/JobProgress.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { JobHandle } from '../job/types';
+import { JobProgress } from './JobProgress';
+
+const base: JobHandle = {
+  status: 'running',
+  done: 0,
+  total: null,
+  failures: [],
+  error: null,
+  start: () => {},
+  cancel: () => {},
+};
+
+const meta: Meta<typeof JobProgress> = {
+  title: 'labkit/primitives/JobProgress',
+  component: JobProgress,
+};
+export default meta;
+type Story = StoryObj<typeof JobProgress>;
+
+/** A job that reported a total drives a determinate bar. */
+export const Determinate: Story = {
+  args: { job: { ...base, done: 34, total: 120 } },
+};
+
+/** A job that never reports a total sweeps instead, so the bar says "working"
+ *  without implying a position. */
+export const Indeterminate: Story = { args: { job: { ...base, done: 34 } } };
+
+export const WithFailures: Story = {
+  args: {
+    job: {
+      ...base,
+      done: 120,
+      total: 120,
+      status: 'done',
+      failures: [
+        { index: 3, error: 'timed out' },
+        { index: 91, error: 'bad input' },
+      ],
+    },
+  },
+};
+
+export const Failed: Story = {
+  args: { job: { ...base, done: 12, total: 120, status: 'error', error: 'worker crashed' } },
+};

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