@weasel-js/labkit 1.2.0 → 1.3.0

package/src/lab/index.ts

@@ -2,7 +2,9 @@ export type { LabProps } from './Lab';
 export { Lab } from './Lab';
 export type { LabContextValue } from './LabContext';
 export { LabContext, useLabContext } from './LabContext';
+export type { LabPaletteProps } from './LabPalette';
+export { LabPalette } from './LabPalette';
 export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
-export type { WorkspaceProps } from './Workspace';
+export type { TrialLayout, WorkspaceProps } from './Workspace';
 export { Workspace } from './Workspace';

package/src/layers/AGENTS.md

@@ -46,7 +46,7 @@ This is intended for legend/HUD layers that should never be toggled off. Visibil
 
 ## Drag handle customization
 
-The drag handle is a button with text content `⋮⋮` and class `lk-layer-list__handle`. Its row height is hardcoded to `28px` for delta computation (`moveDrag` in `LayerList.tsx`). If you change row height in CSS, update the `rowHeight` constant to match.
+The drag handle is a button with class `lk-layer-list__handle` holding `<DragHandleGlyph>` (from `@weasel-js/ui`), the same grip `LayerStack` uses. Its padding is transparent and cancelled by an equal negative margin, so the grab target is larger than the drawn dots without widening the row. Row pitch — height plus row gap — is measured from the DOM when a drag starts, so restyling the row does not skew drag distance. It used to be a hardcoded `28`, which had already drifted from the rendered height by the time it was found.
 
 Pointer capture is acquired on `pointerdown` and released on `pointerup`, so dragging works across the document without requiring window-level listeners.
 

package/src/layers/LayerList.less

@@ -1,8 +1,10 @@
+// No padding of its own: whatever mounts the list insets it. The sidebar
+// section body already does, and a second inset here put the grip 22px off a
+// 161px-wide sidebar's edge.
 .lk-layer-list {
   display: flex;
   flex-direction: column;
-  gap: 2px;
-  padding: var(--wzl-space-sm);
+  gap: 1px;
 }
 
 .lk-layer-list__empty {
@@ -14,9 +16,9 @@
 .lk-layer-list__row {
   display: flex;
   align-items: center;
-  gap: var(--wzl-space-sm);
-  padding: 4px 6px;
-  border-radius: 3px;
+  gap: var(--wzl-space-xs);
+  padding: 1px 2px;
+  border-radius: var(--wzl-radius-sm);
   user-select: none;
 }
 
@@ -33,10 +35,28 @@
   opacity: 0.7;
 }
 
-.lk-layer-list__handle {
+// Prefixed with `.lk-root` to outrank base.less's `:where(button)` default,
+// which would otherwise wrap this grip in a 24px chrome box with a border, an
+// elevated fill and 12px of side padding — around a glyph a third that size.
+.lk-root .lk-layer-list__handle {
+  display: inline-flex;
+  align-items: center;
+  height: auto;
+  // Transparent, so the grab target is comfortable while nothing but the dots
+  // is drawn. The negative margin keeps it from widening the row.
+  padding: 4px;
+  margin: -4px;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
   cursor: grab;
   color: var(--wzl-fg-muted);
-  font-family: monospace;
+}
+
+.lk-root .lk-layer-list__handle:hover {
+  color: var(--wzl-fg);
 }
 
 .lk-layer-list__handle:active {
@@ -51,3 +71,7 @@
   flex: 1;
   font-size: var(--wzl-font-size-sm);
 }
+
+.lk-layer-list input[type='checkbox'] {
+  accent-color: var(--wzl-accent);
+}

package/src/layers/LayerList.tsx

@@ -1,5 +1,6 @@
 import { type PointerEvent, useRef, useState } from 'react';
 import type { LayerDescriptor } from '../instrument/types';
+import { DragHandleGlyph } from '../passthrough/weasel-ui';
 
 /** Props for `<LayerList>`. */
 export interface LayerListProps {
@@ -14,6 +15,8 @@ interface DragState {
   pointerId: number;
   fromIndex: number;
   startY: number;
+  /** Row height plus row gap, measured when the drag starts. */
+  pitch: number;
 }
 
 /** A reorderable list of layers with per-layer visibility toggles. Layers
@@ -34,15 +37,25 @@ export function LayerList({ layers, visibility, onReorder, onToggle, className }
 
   const startDrag = (e: PointerEvent<HTMLElement>, index: number) => {
     e.currentTarget.setPointerCapture(e.pointerId);
-    dragRef.current = { pointerId: e.pointerId, fromIndex: index, startY: e.clientY };
+    // Measured at grab time rather than hardcoded: a restyle that changes row
+    // height or gap would otherwise silently skew every drag distance.
+    const row = e.currentTarget.closest('.lk-layer-list__row');
+    const list = row?.parentElement;
+    const gap = list ? Number.parseFloat(getComputedStyle(list).rowGap) || 0 : 0;
+    const pitch = row ? row.getBoundingClientRect().height + gap : 0;
+    dragRef.current = {
+      pointerId: e.pointerId,
+      fromIndex: index,
+      startY: e.clientY,
+      pitch: pitch > 0 ? pitch : 1,
+    };
     setDragIndex(index);
   };
 
   const moveDrag = (e: PointerEvent<HTMLElement>) => {
     const drag = dragRef.current;
     if (!drag || drag.pointerId !== e.pointerId) return;
-    const rowHeight = 28;
-    const delta = Math.round((e.clientY - drag.startY) / rowHeight);
+    const delta = Math.round((e.clientY - drag.startY) / drag.pitch);
     const target = Math.min(reorderable.length - 1, Math.max(0, drag.fromIndex + delta));
     setDragIndex(target);
   };
@@ -82,7 +95,7 @@ export function LayerList({ layers, visibility, onReorder, onToggle, className }
               onPointerMove={moveDrag}
               onPointerUp={endDrag}
             >
-              ⋮⋮
+              <DragHandleGlyph size={13} />
             </button>
             <input
               className="lk-layer-list__check"

package/src/passthrough/weasel-ui.ts

@@ -24,6 +24,7 @@ export {
   type BadgeVariant,
   type BoundsCtx,
   type BuiltInEdgeName,
+  type BuiltinPref,
   Button,
   type ButtonProps,
   type ButtonSize,
@@ -47,6 +48,8 @@ export {
   type DataGridProps,
   Dialog,
   type DialogProps,
+  DragHandleGlyph,
+  type DragHandleGlyphProps,
   detectPlatform,
   dlog,
   EDGE_PROFILES,
@@ -68,6 +71,7 @@ export {
   type InterpolationMode,
   inferKeycapKind,
   isDebugEnabled,
+  isPrefLeaf,
   KeyCap,
   type KeyCapProps,
   type KeyCapVariant,
@@ -79,6 +83,9 @@ export {
   keySpecFromKey,
   keySpecsFromMods,
   type LayerListItem,
+  LayerStack,
+  type LayerStackItem,
+  type LayerStackProps,
   type LogicalMod,
   type LogicalModSpec,
   MINUS_SIGN,
@@ -100,7 +107,27 @@ export {
   Powerline,
   type PowerlineProps,
   type PowerlineSegment,
+  type PrefBoolean,
+  type PrefBooleanControl,
+  type PrefColor,
+  type PrefCustom,
+  type PrefEnum,
+  type PrefEnumControl,
+  type PrefEnumEncoding,
+  type PrefGroup,
+  type PrefKind,
+  type PrefLeaf,
+  type PrefNumber,
+  type PrefNumberControl,
+  type PrefNumberUnit,
+  type PrefObject,
+  type PrefPaint,
+  type PrefRenderContext,
+  type PrefRenderer,
+  type PrefString,
+  type PrefStringControl,
   paintGradientTrack,
+  prefValueAtPath,
   Radio,
   RadioGroup,
   type RadioGroupProps,
@@ -151,4 +178,5 @@ export {
   type UseRovingTabIndexOptions,
   useReorderDragList,
   useRovingTabIndex,
+  visiblePrefSubtree,
 } from '@weasel-js/ui';

package/src/primitives/FloatingPanel.less

@@ -0,0 +1,28 @@
+.lk-floating-panel {
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+  background: var(--wzl-surface);
+  border: var(--wzl-border-w) solid var(--wzl-border);
+  border-radius: var(--wzl-radius-md);
+  padding: var(--wzl-space-sm);
+  box-shadow: 0 6px 18px rgb(0 0 0 / 40%);
+}
+
+// An item with no measured size is withheld from layout, so the first paint
+// would otherwise land at the top-left before jumping to its anchor.
+.lk-floating-panel:not([data-placed='true']) {
+  visibility: hidden;
+}
+
+.lk-floating-panel[data-dragging='true'] {
+  cursor: grabbing;
+}
+
+.lk-floating-panel-story-host {
+  position: relative;
+  width: 520px;
+  height: 340px;
+  background: var(--wzl-surface-sunken);
+  border: var(--wzl-border-w) solid var(--wzl-border);
+}

package/src/primitives/FloatingPanel.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { FloatingPanel } from './FloatingPanel';
+import { Legend } from './Legend';
+
+// The panel positions against its offset parent, so a story needs a sized,
+// positioned host or there is nothing for it to float in.
+const meta: Meta<typeof FloatingPanel> = {
+  title: 'labkit/Primitives/FloatingPanel',
+  component: FloatingPanel,
+  decorators: [
+    (Story) => (
+      <div className="lk-floating-panel-story-host">
+        <Story />
+      </div>
+    ),
+  ],
+  args: { children: 'drag me' },
+};
+export default meta;
+
+type Story = StoryObj<typeof FloatingPanel>;
+
+export const BottomLeft: Story = {};
+
+export const TopRight: Story = { args: { anchor: 'top-right' } };
+
+export const TwoCornersOnly: Story = {
+  args: { anchor: 'top-left', snapCorners: ['top-left', 'bottom-right'] },
+};
+
+export const HoldingALegend: Story = {
+  args: {
+    anchor: 'bottom-right',
+    children: (
+      <Legend
+        entries={[
+          { key: 'contour', label: 'contour', color: '#7d7f86' },
+          { key: 'floor', label: 'bend floor', color: '#9a9ca3', mark: 'dash' },
+          { key: 'authored', label: 'authored', color: '#2aa87a', mark: 'dot' },
+        ]}
+      />
+    ),
+  },
+};
+
+export const Remembered: Story = { args: { storageKey: 'labkit.story.panel' } };

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