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

package/src/lab/LabPalette.tsx

@@ -0,0 +1,34 @@
+import { useContext } from 'react';
+import { useStore } from 'zustand/react';
+import { PaletteRegion } from '../chrome/regions/PaletteRegion';
+import type { TrialChromeContext, TrialContribution } from '../chrome/types';
+import { LabStoreContext } from '../state/context';
+import type { TrialTool } from '../tools/types';
+
+/** Props for `<LabPalette>`. */
+export interface LabPaletteProps {
+  tools: readonly TrialTool[];
+}
+
+/** The lab's tool strip. Writes the lab's tool slot, which every trial whose
+ *  instrument declares no tools of its own resolves to. */
+export function LabPalette({ tools }: LabPaletteProps) {
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] LabPalette requires <LabStoreProvider>');
+  const activeToolId = useStore(storeCtx.store, (s) => s.activeToolId);
+  const setLabTool = useStore(storeCtx.store, (s) => s.setLabTool);
+
+  const contributions: TrialContribution[] = tools.map((t) => ({
+    id: t.id,
+    region: 'palette',
+    group: t.group,
+    item: { icon: t.icon, label: t.label, shortcut: t.shortcut },
+  }));
+
+  const ctx = {
+    activeToolId,
+    setActiveTool: setLabTool,
+  } as unknown as TrialChromeContext;
+
+  return <PaletteRegion contributions={contributions} ctx={ctx} />;
+}

package/src/lab/LabShell.less

@@ -6,6 +6,12 @@
   background: var(--wzl-surface);
 }
 
+// Standalone, the shell owns its surface. Inside `<Lab>` that surface is the
+// one thing between the viewer and `.lk-lab`'s nebula, so it steps aside.
+.lk-lab > .lk-shell {
+  background: transparent;
+}
+
 .lk-shell-header {
   display: flex;
   align-items: center;
@@ -18,8 +24,8 @@
 
 .lk-shell-title {
   margin: 0;
-  font-size: 16px;
-  font-weight: 600;
+  font-size: var(--wzl-font-size-xl);
+  font-weight: var(--wzl-font-weight-bold);
   color: var(--wzl-fg);
 }
 
@@ -33,7 +39,19 @@
   flex: 1;
   min-height: 0;
   overflow: auto;
-  padding: var(--wzl-space-md);
+  padding: var(--lk-workspace-pad);
+}
+
+// `.lk-shell-body` is a block container, so `flex: 1` here resolves to nothing
+// and the workspace's `height: 100%` collapses to zero.
+.lk-lab__body {
+  display: flex;
+  height: 100%;
+  min-height: 0;
+
+  > .lk-workspace {
+    min-width: 0;
+  }
 }
 
 .lk-shell-footer {
@@ -43,3 +61,32 @@
   color: var(--wzl-fg-muted);
   font-size: var(--wzl-font-size-sm);
 }
+
+.lk-lab-header__add {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--wzl-space-xs);
+}
+
+// `Select` is a form field and defaults to `width: 100%`. Left to resolve that
+// against a shrink-to-fit header row it swallows the slack, which pushed the
+// consumer's own header content down to min-content and wrapped the row to
+// three lines. See the `.lk-root` prefix convention in theme/base.less.
+.lk-root .lk-lab-header__add-select {
+  width: 160px;
+}
+
+// The mode toggle is a preference, not a primary action: it sits quiet until
+// the pointer is on it.
+.lk-lab-header__mode {
+  opacity: 0.75;
+  // A consumer's own header content shares this row and does not shrink, so
+  // without this the segments compress past their labels and the pill track
+  // disappears entirely.
+  flex-shrink: 0;
+
+  &:hover,
+  &:focus-within {
+    opacity: 1;
+  }
+}

package/src/lab/Workspace.less

@@ -5,36 +5,7 @@
   min-height: 0;
 }
 
-// Only rendered when `reorderable` — a tile is full of controls, so the drag
-// target has to be its own strip rather than the whole pane.
 .lk-trial-tile {
-  display: flex;
-  flex-direction: column;
   height: 100%;
-
-  &__grip {
-    flex: 0 0 auto;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    height: 14px;
-    cursor: grab;
-    border-radius: var(--wzl-radius-sm) var(--wzl-radius-sm) 0 0;
-    background: var(--wzl-surface-sunken);
-
-    &:active { cursor: grabbing; }
-  }
-
-  &__grip-dots {
-    width: 28px;
-    height: 3px;
-    border-radius: 999px;
-    background: var(--wzl-fg-muted);
-    opacity: 0.5;
-  }
-
-  &__body {
-    flex: 1;
-    min-height: 0;
-  }
+  min-height: 0;
 }

package/src/lab/Workspace.surface.test.tsx

@@ -0,0 +1,49 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import type { SurfaceHandle } from '../surface/useTiledSurface';
+import { Workspace } from './Workspace';
+
+function fakeHandle(): SurfaceHandle {
+  return {
+    invalidate: vi.fn(),
+    invalidateAll: vi.fn(),
+    invalidateRects: vi.fn(),
+    registerTile: vi.fn(),
+    containerRef: vi.fn(),
+  };
+}
+
+describe('Workspace with a surface above it', () => {
+  it('invalidates rects when the tile set changes, because a re-tile moves tiles', () => {
+    const handle = fakeHandle();
+    const { rerender } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
+          <div>a</div>
+        </Workspace>
+      </SurfaceContext.Provider>,
+    );
+    (handle.invalidateRects as ReturnType<typeof vi.fn>).mockClear();
+
+    rerender(
+      <SurfaceContext.Provider value={handle}>
+        <Workspace ids={['a', 'b']} viewport={{ w: 800, h: 600 }}>
+          <div>a</div>
+          <div>b</div>
+        </Workspace>
+      </SurfaceContext.Provider>,
+    );
+
+    expect(handle.invalidateRects).toHaveBeenCalled();
+  });
+
+  it('renders unchanged with no surface above it', () => {
+    const { getByText } = render(
+      <Workspace ids={['a']} viewport={{ w: 800, h: 600 }}>
+        <div>a</div>
+      </Workspace>,
+    );
+    expect(getByText('a')).toBeInTheDocument();
+  });
+});

package/src/lab/Workspace.test.tsx

@@ -1,7 +1,15 @@
 import { render, screen } from '@testing-library/react';
 import { describe, expect, test, vi } from 'vitest';
+import { useTrialDrag } from '../trial/TrialDragContext';
 import { Workspace } from './Workspace';
 
+/** Reports whether its tile supplied a drag source — the title bar is the
+ *  drag surface now, so there is no grip element to assert on. */
+function DragProbe({ label }: { label: string }) {
+  const drag = useTrialDrag();
+  return <div data-testid={`drag-${label}`}>{drag ? 'draggable' : 'static'}</div>;
+}
+
 const VIEWPORT = { w: 800, h: 600 };
 
 describe('Workspace', () => {
@@ -88,13 +96,14 @@ describe('Workspace', () => {
     const onReorder = vi.fn();
     const { container } = render(
       <Workspace ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
-        <div>a</div>
-        <div>b</div>
+        <DragProbe label="a" />
+        <DragProbe label="b" />
       </Workspace>,
     );
-    // The grid is controlled: it renders a handle per tile and commits nothing
-    // itself. Order still comes from `ids`.
-    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(2);
+    // The grid is controlled: each tile offers itself as a drag source and
+    // commits nothing itself. Order still comes from `ids`.
+    expect(screen.getByTestId('drag-a')).toHaveTextContent('draggable');
+    expect(screen.getByTestId('drag-b')).toHaveTextContent('draggable');
     expect(onReorder).not.toHaveBeenCalled();
     const nodes = [...container.querySelectorAll('[data-node]')].map((el) =>
       el.getAttribute('data-node'),
@@ -102,13 +111,14 @@ describe('Workspace', () => {
     expect(nodes).toEqual(['a', 'b']);
   });
 
-  test('renders no drag handles unless reorderable', () => {
-    const { container } = render(
+  test('offers no drag source unless reorderable', () => {
+    render(
       <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
-        <div>a</div>
-        <div>b</div>
+        <DragProbe label="a" />
+        <DragProbe label="b" />
       </Workspace>,
     );
-    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(0);
+    expect(screen.getByTestId('drag-a')).toHaveTextContent('static');
+    expect(screen.getByTestId('drag-b')).toHaveTextContent('static');
   });
 });

package/src/lab/Workspace.tsx

@@ -11,12 +11,14 @@ import { asNodeId, createNode, gridStrategy, type NodeId, Store } from 'windease
 import {
   type ChromeMap,
   Container,
-  DragHandle,
   DragProvider,
   Provider,
   StrategyRegistryProvider,
 } from 'windease/react';
 
+import { useSurfaceOptional } from '../surface/useSurfaceTile';
+import { TrialDragContext } from '../trial/TrialDragContext';
+
 const ZONE_ID = asNodeId('lk-workspace');
 const STRATEGIES = { grid: gridStrategy as never };
 const KIND = 'trial';
@@ -93,7 +95,7 @@ export function Workspace({
   const items = Children.toArray(children);
   const idKey = ids ? ids.join(',') : `#${items.length}`;
   // biome-ignore lint/correctness/useExhaustiveDependencies: idKey is the stable projection of items/ids; depending on those directly rebuilds every render and re-runs the sync effect forever
-  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]);
+  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Held in refs rather than depended on: a fresh object each render would
   // re-run the sync effect, and only a newly registered tile reads `layout`.
@@ -119,6 +121,10 @@ export function Workspace({
   }
   const store = storeRef.current;
 
+  // A tile that only moves reports nothing to a ResizeObserver, and only this
+  // component knows the grid moved one. Optional: a lab may own no surface.
+  const surface = useSurfaceOptional();
+
   useLayoutEffect(() => {
     store.updateContainerConfig(ZONE_ID, { resizable, gap, padding });
   }, [store, resizable, gap, padding]);
@@ -139,6 +145,13 @@ export function Workspace({
     store.setChildOrder(ZONE_ID, [...nodeIds]);
   }, [store, nodeIds]);
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: nodeIds is the signal that the tile set changed — a re-tile moves tiles without resizing any — not a value this reads
+  useEffect(() => {
+    if (!surface) return;
+    surface.invalidateRects();
+    return store.events.on('node.placementChanged', () => surface.invalidateRects());
+  }, [store, surface, nodeIds]); // eslint-disable-line react-hooks/exhaustive-deps
+
   useEffect(() => {
     if (!onLayoutChange) return;
     return store.events.on('node.placementChanged', () => {
@@ -162,14 +175,11 @@ export function Workspace({
       [KIND]: ({ node }) => {
         const content = byId.get(node.id) ?? null;
         if (!reorderable) return content;
-        // A tile is full of controls, so the whole thing can't be the handle.
         return (
-          <div className="lk-trial-tile">
-            <DragHandle nodeId={node.id} className="lk-trial-tile__grip">
-              <span className="lk-trial-tile__grip-dots" aria-hidden="true" />
-            </DragHandle>
-            <div className="lk-trial-tile__body">{content}</div>
-          </div>
+          // No grip strip: the trial's own title bar is the drag surface.
+          <TrialDragContext.Provider value={{ nodeId: node.id }}>
+            <div className="lk-trial-tile">{content}</div>
+          </TrialDragContext.Provider>
         );
       },
     };

package/src/lab/index.ts

@@ -2,6 +2,8 @@ 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';

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>`, 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 '../primitives/DragHandleGlyph';
 
 /** 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

@@ -114,6 +114,29 @@ export {
   Select,
   SelectItem,
   type SelectItemProps,
+  type BuiltinPref,
+  isPrefLeaf,
+  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,
+  prefValueAtPath,
+  visiblePrefSubtree,
   type SelectOption,
   type SelectProps,
   Sidebar,

package/src/primitives/DragHandleGlyph.tsx

@@ -0,0 +1,29 @@
+/** Props for `<DragHandleGlyph>`. */
+export interface DragHandleGlyphProps {
+  /** Height in px; width scales with it. Default 16. */
+  size?: number;
+}
+
+/** The two-column dot grip used on anything draggable by a handle.
+ *
+ *  Deliberately not part of `@weasel-js/ui`'s icon register: that register is
+ *  outline strokes at a fixed weight, and a grip is filled dots. Forcing it in
+ *  would either break the register's rule or produce a worse glyph. */
+export function DragHandleGlyph({ size = 16 }: DragHandleGlyphProps) {
+  return (
+    <svg
+      width={(size * 8) / 16}
+      height={size}
+      viewBox="0 0 8 16"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <circle cx="2" cy="3" r="1.1" />
+      <circle cx="6" cy="3" r="1.1" />
+      <circle cx="2" cy="8" r="1.1" />
+      <circle cx="6" cy="8" r="1.1" />
+      <circle cx="2" cy="13" r="1.1" />
+      <circle cx="6" cy="13" r="1.1" />
+    </svg>
+  );
+}

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