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

package/src/primitives/FloatingPanel.test.tsx

@@ -0,0 +1,240 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { FloatingPanel } from './FloatingPanel';
+
+// The shared stub reports one size for every element, which makes the panel and
+// its container the same box. Report per-target sizes instead so placement math
+// has something real to chew on. Keyed by class, because `observe()` fires
+// synchronously inside the effect — before a test could register an element.
+const sizes = { host: { w: 400, h: 300 }, panel: { w: 100, h: 40 } };
+const realRO = globalThis.ResizeObserver;
+
+beforeEach(() => {
+  localStorage.clear();
+  sizes.host = { w: 400, h: 300 };
+  sizes.panel = { w: 100, h: 40 };
+  globalThis.ResizeObserver = class {
+    #cb: ResizeObserverCallback;
+    constructor(cb: ResizeObserverCallback) {
+      this.#cb = cb;
+    }
+    observe(target: Element) {
+      const { w, h } = target.classList.contains('lk-floating-panel') ? sizes.panel : sizes.host;
+      const contentRect = { width: w, height: h, x: 0, y: 0, top: 0, left: 0 };
+      this.#cb([{ target, contentRect } as ResizeObserverEntry], this);
+    }
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  globalThis.ResizeObserver = realRO;
+});
+
+/** Renders a panel in a 400x300 host, the panel itself measuring 100x40. */
+function renderPanel(ui: React.ReactElement) {
+  const result = render(<div>{ui}</div>);
+  return { ...result, panel: result.container.querySelector('.lk-floating-panel') as HTMLElement };
+}
+
+describe('FloatingPanel', () => {
+  it('renders its children', () => {
+    render(<FloatingPanel>hello</FloatingPanel>);
+    expect(screen.getByText('hello')).toBeInTheDocument();
+  });
+
+  it('is absolutely positioned so it floats over whatever it sits in', () => {
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    expect(panel.style.position).toBe('absolute');
+  });
+
+  it('accepts an extra class name', () => {
+    const { container } = render(<FloatingPanel className="is-mine">x</FloatingPanel>);
+    expect(container.querySelector('.lk-floating-panel')?.className).toContain('is-mine');
+  });
+
+  it('rests in the bottom-left corner by default, one inset in', () => {
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    expect(panel.style.left).toBe('12px');
+    expect(panel.style.top).toBe('248px'); // 300 - 40 - 12
+  });
+
+  it('honors the anchor it is given', () => {
+    const { panel } = renderPanel(<FloatingPanel anchor="top-right">x</FloatingPanel>);
+    expect(panel.style.left).toBe('288px'); // 400 - 100 - 12
+    expect(panel.style.top).toBe('12px');
+  });
+
+  it('honors a custom inset', () => {
+    const { panel } = renderPanel(
+      <FloatingPanel anchor="top-left" inset={30}>
+        x
+      </FloatingPanel>,
+    );
+    expect(panel.style.left).toBe('30px');
+    expect(panel.style.top).toBe('30px');
+  });
+
+  it('stays hidden until it has been measured and placed', () => {
+    sizes.panel = { w: 0, h: 0 };
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    // The strategy withholds an item with no size, so there is no rect to paint.
+    expect(panel.getAttribute('data-placed')).toBeNull();
+  });
+
+  it('measures its border box, so padding does not push it past a corner', () => {
+    // Same content box, but 8px padding and a 1px border on every side.
+    const realObserve = globalThis.ResizeObserver;
+    globalThis.ResizeObserver = class {
+      #cb: ResizeObserverCallback;
+      constructor(cb: ResizeObserverCallback) {
+        this.#cb = cb;
+      }
+      observe(target: Element) {
+        const isPanel = target.classList.contains('lk-floating-panel');
+        const { w, h } = isPanel ? sizes.panel : sizes.host;
+        const contentRect = { width: w, height: h, x: 0, y: 0, top: 0, left: 0 };
+        const entry = {
+          target,
+          contentRect,
+          ...(isPanel ? { borderBoxSize: [{ inlineSize: w + 18, blockSize: h + 18 }] } : {}),
+        };
+        this.#cb([entry as unknown as ResizeObserverEntry], this);
+      }
+      unobserve() {}
+      disconnect() {}
+    } as unknown as typeof ResizeObserver;
+    const { panel } = renderPanel(<FloatingPanel anchor="top-right">x</FloatingPanel>);
+    globalThis.ResizeObserver = realObserve;
+    expect(panel.style.left).toBe('270px'); // 400 - (100 + 18) - 12
+  });
+
+  it('marks itself placed once it has a rect', () => {
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    expect(panel.dataset.placed).toBe('true');
+  });
+});
+
+describe('FloatingPanel dragging', () => {
+  it('marks itself dragging between pointerdown and pointerup', () => {
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    expect(panel.dataset.dragging).toBe('true');
+    fireEvent.pointerUp(panel);
+    expect(panel.dataset.dragging).toBeUndefined();
+  });
+
+  it('moves with the pointer, accumulating across moves', () => {
+    const { panel } = renderPanel(<FloatingPanel anchor="top-left">x</FloatingPanel>);
+    expect(panel.style.left).toBe('12px');
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(panel, { clientX: 200, clientY: 180 });
+    expect(panel.style.left).toBe('100px');
+    expect(panel.style.top).toBe('80px');
+    fireEvent.pointerMove(panel, { clientX: 250, clientY: 180 });
+    expect(panel.style.left).toBe('150px');
+    expect(panel.style.top).toBe('80px');
+  });
+
+  it('snaps to a corner when dropped near one', () => {
+    const { panel } = renderPanel(<FloatingPanel anchor="top-left">x</FloatingPanel>);
+    fireEvent.pointerDown(panel, { clientX: 0, clientY: 0 });
+    // Aim at the bottom-right corner; the snap threshold captures it.
+    fireEvent.pointerMove(panel, { clientX: 400, clientY: 300 });
+    expect(panel.style.left).toBe('288px'); // 400 - 100 - 12
+    expect(panel.style.top).toBe('248px'); // 300 - 40 - 12
+  });
+
+  it('refuses a corner it was not given', () => {
+    const { panel } = renderPanel(
+      <FloatingPanel anchor="top-left" snapCorners={['top-left']}>
+        x
+      </FloatingPanel>,
+    );
+    fireEvent.pointerDown(panel, { clientX: 0, clientY: 0 });
+    fireEvent.pointerMove(panel, { clientX: 400, clientY: 300 });
+    // Clamped inside the container, but not snapped to the bottom-right inset.
+    expect(panel.style.left).toBe('300px');
+    expect(panel.style.top).toBe('260px');
+  });
+
+  it('does not start a drag from an interactive child', () => {
+    const { panel } = renderPanel(
+      <FloatingPanel>
+        <button type="button">press</button>
+      </FloatingPanel>,
+    );
+    fireEvent.pointerDown(screen.getByRole('button'), { clientX: 10, clientY: 10 });
+    expect(panel.dataset.dragging).toBeUndefined();
+  });
+
+  it('does not start a drag from a child opting out', () => {
+    const { panel } = renderPanel(
+      <FloatingPanel>
+        <span data-no-drag="">nope</span>
+      </FloatingPanel>,
+    );
+    fireEvent.pointerDown(screen.getByText('nope'), { clientX: 10, clientY: 10 });
+    expect(panel.dataset.dragging).toBeUndefined();
+  });
+
+  it('stops the pointerdown reaching a pan/zoom surface underneath', () => {
+    const onDown = vi.fn();
+    const { container } = render(
+      <div onPointerDown={onDown}>
+        <FloatingPanel>x</FloatingPanel>
+      </div>,
+    );
+    fireEvent.pointerDown(container.querySelector('.lk-floating-panel') as HTMLElement, {
+      clientX: 5,
+      clientY: 5,
+    });
+    expect(onDown).not.toHaveBeenCalled();
+  });
+
+  it('lets a pointerdown on an interactive child through to the surface', () => {
+    const onDown = vi.fn();
+    render(
+      <div onPointerDown={onDown}>
+        <FloatingPanel>
+          <button type="button">press</button>
+        </FloatingPanel>
+      </div>,
+    );
+    fireEvent.pointerDown(screen.getByRole('button'), { clientX: 5, clientY: 5 });
+    expect(onDown).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('FloatingPanel persistence', () => {
+  it('writes its placement under the given key once dragged', () => {
+    const { panel } = renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>);
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(panel, { clientX: 140, clientY: 160 });
+    fireEvent.pointerUp(panel);
+    const stored = JSON.parse(localStorage.getItem('k') ?? 'null');
+    expect(stored).toMatchObject({ x: expect.any(Number), y: expect.any(Number) });
+    expect(stored).toHaveProperty('anchor');
+  });
+
+  it('restores what it stored on a later mount', () => {
+    localStorage.setItem('k', JSON.stringify({ x: 140, y: 90, anchor: null }));
+    const { panel } = renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>);
+    expect(panel.style.left).toBe('140px');
+    expect(panel.style.top).toBe('90px');
+  });
+
+  it('writes nothing when no key is given', () => {
+    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(panel, { clientX: 140, clientY: 160 });
+    fireEvent.pointerUp(panel);
+    expect(localStorage.length).toBe(0);
+  });
+
+  it('survives a corrupt stored value rather than throwing', () => {
+    localStorage.setItem('k', '{{{');
+    expect(() => renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>)).not.toThrow();
+  });
+});

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