@weasel-js/labkit 0.1.0

package/src/passthrough/weasel-ui.ts

@@ -0,0 +1,150 @@
+/**
+ * Re-exports from `@weasel-js/ui` so consumers import primitives
+ * through `@weasel-js/labkit/weasel-ui` rather than depending on the
+ * weasel-ui package directly. Lets labkit swap implementations in the
+ * future without consumer churn.
+ */
+
+export {
+  ActionBar,
+  type ActionBarProps,
+  ActionsBar,
+  type ActionsBarItem,
+  type ActionsBarProps,
+  type ActionsBarSize,
+  type ActionsBarVariant,
+  type AddPointMode,
+  type AnchorRenderProps,
+  type AxesSettings,
+  Badge,
+  type BadgeProps,
+  type BadgeShape,
+  type BadgeSize,
+  type BadgeTone,
+  type BadgeVariant,
+  type BoundsCtx,
+  type BuiltInEdgeName,
+  Button,
+  type ButtonProps,
+  type ButtonSize,
+  type ButtonVariant,
+  Checkbox,
+  type CheckboxProps,
+  type ChromaCurve,
+  type ChromaCurvePoint,
+  ComboBox,
+  ComboBoxItem,
+  type ComboBoxItemProps,
+  type ComboBoxOption,
+  type ComboBoxProps,
+  type ControlPoint,
+  type CurveDomain,
+  CurveEditor,
+  type CurveEditorProps,
+  chromaAt,
+  DataGrid,
+  type DataGridColumn,
+  type DataGridProps,
+  Dialog,
+  type DialogProps,
+  detectPlatform,
+  dlog,
+  EDGE_PROFILES,
+  type EdgeCap,
+  type EdgeProfile,
+  type EndpointMode,
+  Field,
+  type FieldOrientation,
+  type FieldProps,
+  type FillSettings,
+  fieldClasses,
+  formatNumber,
+  formatShortcut,
+  formatShortcutParts,
+  type GradientTrackOpts,
+  type GridSettings,
+  Input,
+  type InputProps,
+  type InterpolationMode,
+  inferKeycapKind,
+  isDebugEnabled,
+  KeyCap,
+  type KeyCapProps,
+  type KeyCapVariant,
+  type KeycapKind,
+  KeySequence,
+  type KeySequenceProps,
+  type KeySpec,
+  keyGlyph,
+  keySpecFromKey,
+  keySpecsFromMods,
+  type LayerListItem,
+  type LogicalMod,
+  type LogicalModSpec,
+  MINUS_SIGN,
+  NumberField,
+  type NumberFieldProps,
+  OptionsBar,
+  type OptionsBarItem,
+  type OptionsBarProps,
+  type OptionsBarSize,
+  type OptionsBarVariant,
+  oklchToHex,
+  type Platform,
+  Plot2D,
+  type Plot2DCoords,
+  type Plot2DHandle,
+  type Plot2DProps,
+  PointPlotter,
+  type PointPlotterProps,
+  Powerline,
+  type PowerlineProps,
+  type PowerlineSegment,
+  paintGradientTrack,
+  Radio,
+  RadioGroup,
+  type RadioGroupProps,
+  type RadioProps,
+  RangeSlider,
+  type RangeSliderProps,
+  type ReorderDragHandlers,
+  type ReorderDragState,
+  Select,
+  SelectItem,
+  type SelectItemProps,
+  type SelectOption,
+  type SelectProps,
+  Sidebar,
+  SidebarPanel,
+  type SidebarPanelProps,
+  type SidebarProps,
+  Slider,
+  type SliderProps,
+  Switch,
+  type SwitchProps,
+  Tab,
+  TabList,
+  type TabListProps,
+  TabPanel,
+  type TabPanelProps,
+  type TabProps,
+  Tabs,
+  type TabsProps,
+  type Thumb,
+  type ThumbRenderCtx,
+  type ThumbShape,
+  ToggleBar,
+  type ToggleBarItem,
+  type ToggleBarProps,
+  type ToggleBarSize,
+  type ToggleBarVariant,
+  ToolButton,
+  type ToolButtonProps,
+  ToolGroup,
+  type ToolGroupProps,
+  ToolPalette,
+  type ToolPaletteProps,
+  type TrackCtx,
+  type UseReorderDragListOptions,
+  useReorderDragList,
+} from '@weasel-js/ui';

package/src/primitives/FpsMeter.less

@@ -0,0 +1,14 @@
+.lk-fps-meter {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--lk-spacing-xs);
+  font-family: var(--lk-font-mono);
+  font-size: var(--lk-font-size-sm);
+  color: var(--lk-text-muted);
+}
+
+.lk-fps-meter-value {
+  color: var(--lk-text);
+  min-width: 2.5ch;
+  text-align: right;
+}

package/src/primitives/FpsMeter.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { FpsMeter } from './FpsMeter';
+
+const meta: Meta<typeof FpsMeter> = {
+  title: 'labkit/Primitives/FpsMeter',
+  component: FpsMeter,
+};
+export default meta;
+
+type Story = StoryObj<typeof FpsMeter>;
+
+export const Default: Story = {
+  render: () => <FpsMeter />,
+};

package/src/primitives/FpsMeter.test.tsx

@@ -0,0 +1,38 @@
+import { act, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { FpsMeter } from './FpsMeter';
+
+describe('FpsMeter', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test('renders an FPS label', () => {
+    render(<FpsMeter />);
+    expect(screen.getByText(/fps/i)).toBeInTheDocument();
+  });
+
+  test('uses lk-fps-meter class', () => {
+    const { container } = render(<FpsMeter />);
+    expect((container.firstChild as HTMLElement).className).toBe('lk-fps-meter');
+  });
+
+  test('updates after a tick', () => {
+    let raf: FrameRequestCallback | null = null;
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      raf = cb;
+      return 1;
+    });
+    vi.stubGlobal('cancelAnimationFrame', () => {});
+
+    render(<FpsMeter />);
+    act(() => {
+      raf?.(0);
+      raf?.(16.67);
+      raf?.(33.34);
+    });
+    expect(screen.getByText(/FPS\s+\d+/)).toBeInTheDocument();
+
+    vi.unstubAllGlobals();
+  });
+});

package/src/primitives/FpsMeter.tsx

@@ -0,0 +1,36 @@
+import { useEffect, useRef, useState } from 'react';
+import { rollingAverage } from './fpsAverage';
+
+const SAMPLE_WINDOW = 30;
+
+export function FpsMeter() {
+  const [fps, setFps] = useState(0);
+  const samplesRef = useRef<number[]>([]);
+  const lastTimeRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    let rafId = 0;
+    const tick = (time: number) => {
+      const last = lastTimeRef.current;
+      if (last !== null) {
+        const delta = time - last;
+        if (delta > 0) {
+          const samples = samplesRef.current;
+          samples.push(1000 / delta);
+          if (samples.length > SAMPLE_WINDOW) samples.shift();
+          setFps(rollingAverage(samples));
+        }
+      }
+      lastTimeRef.current = time;
+      rafId = requestAnimationFrame(tick);
+    };
+    rafId = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(rafId);
+  }, []);
+
+  return (
+    <div className="lk-fps-meter">
+      <span className="lk-fps-meter-value">FPS {fps}</span>
+    </div>
+  );
+}

package/src/primitives/ScaleIndicator.less

@@ -0,0 +1,25 @@
+.lk-scale-indicator {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--lk-spacing-xs);
+  font-family: var(--lk-font-mono);
+  font-size: var(--lk-font-size-sm);
+  color: var(--lk-text-muted);
+}
+
+.lk-scale-indicator-bar {
+  height: 6px;
+  border: 1px solid var(--lk-text-muted);
+  border-top: none;
+  background: linear-gradient(
+    to right,
+    var(--lk-text-muted) 1px,
+    transparent 1px,
+    transparent calc(100% - 1px),
+    var(--lk-text-muted) calc(100% - 1px)
+  );
+}
+
+.lk-scale-indicator-label {
+  white-space: nowrap;
+}

package/src/primitives/ScaleIndicator.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ScaleIndicator } from './ScaleIndicator';
+
+const meta: Meta<typeof ScaleIndicator> = {
+  title: 'labkit/Primitives/ScaleIndicator',
+  component: ScaleIndicator,
+  args: { unit: 'ft', pixelsPerUnit: 50 },
+};
+export default meta;
+
+type Story = StoryObj<typeof ScaleIndicator>;
+
+export const NoZoom: Story = { args: { zoom: 1 } };
+export const ZoomedIn: Story = { args: { zoom: 4 } };
+export const ZoomedOut: Story = { args: { zoom: 0.25 } };
+export const Meters: Story = { args: { zoom: 1, unit: 'm', pixelsPerUnit: 100 } };

package/src/primitives/ScaleIndicator.test.tsx

@@ -0,0 +1,46 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { CanvasStackContext } from '../canvas/CanvasStackContext';
+import { ScaleIndicator } from './ScaleIndicator';
+
+describe('ScaleIndicator', () => {
+  test('renders the unit label', () => {
+    render(<ScaleIndicator zoom={1} pixelsPerUnit={50} unit="ft" />);
+    expect(screen.getByText(/ft/)).toBeInTheDocument();
+  });
+
+  test('shows scale value scaled by zoom', () => {
+    render(<ScaleIndicator zoom={2} pixelsPerUnit={50} unit="ft" />);
+    expect(screen.getByText(/1\s*ft/)).toBeInTheDocument();
+  });
+
+  test('rounds bar to a nice number when target spans multiple units', () => {
+    // zoom=0.5, pixelsPerUnit=50 → effective 25 px/unit → 100px ≈ 4 units → niceNumber → 5
+    render(<ScaleIndicator zoom={0.5} pixelsPerUnit={50} unit="ft" />);
+    expect(screen.getByText(/5\s*ft/)).toBeInTheDocument();
+  });
+
+  test('uses lk-scale-indicator class', () => {
+    const { container } = render(<ScaleIndicator zoom={1} pixelsPerUnit={50} unit="ft" />);
+    expect((container.firstChild as HTMLElement).className).toBe('lk-scale-indicator');
+  });
+
+  test('reads zoom from CanvasStackContext when prop omitted', () => {
+    render(
+      <CanvasStackContext.Provider value={{ view: { zoom: 2.5, pan: { x: 0, y: 0 } } }}>
+        <ScaleIndicator pixelsPerUnit={50} unit="ft" />
+      </CanvasStackContext.Provider>,
+    );
+    // zoom 2.5 × 50 = 125 px/unit → niceNumber(100/125 = 0.8) → 1
+    expect(screen.getByText(/1\s*ft/)).toBeInTheDocument();
+  });
+
+  test('explicit zoom prop overrides context', () => {
+    render(
+      <CanvasStackContext.Provider value={{ view: { zoom: 100, pan: { x: 0, y: 0 } } }}>
+        <ScaleIndicator zoom={1} pixelsPerUnit={50} unit="ft" />
+      </CanvasStackContext.Provider>,
+    );
+    expect(screen.getByText(/2\s*ft/)).toBeInTheDocument();
+  });
+});

package/src/primitives/ScaleIndicator.tsx

@@ -0,0 +1,48 @@
+import { useContext } from 'react';
+import { CanvasStackContext } from '../canvas/CanvasStackContext';
+
+export interface ScaleIndicatorProps {
+  /** Current view zoom factor. If omitted, reads from CanvasStackContext. Defaults to 1. */
+  zoom?: number;
+  /** World pixels per unit at zoom=1. Default: 1. */
+  pixelsPerUnit?: number;
+  /** Unit label. Default: 'px'. */
+  unit?: string;
+  /** Target bar width in display pixels. Default: 100. */
+  targetWidth?: number;
+}
+
+// Rounds n to a "nice" number — 1, 2, 5, 10, 20, 50, ...
+function niceNumber(n: number): number {
+  if (n <= 0) return 1;
+  const exp = Math.floor(Math.log10(n));
+  const fraction = n / 10 ** exp;
+  let nice: number;
+  if (fraction < 1.5) nice = 1;
+  else if (fraction < 3.5) nice = 2;
+  else if (fraction < 7.5) nice = 5;
+  else nice = 10;
+  return nice * 10 ** exp;
+}
+
+export function ScaleIndicator({
+  zoom,
+  pixelsPerUnit = 1,
+  unit = 'px',
+  targetWidth = 100,
+}: ScaleIndicatorProps) {
+  const ctxValue = useContext(CanvasStackContext);
+  const effectiveZoom = zoom ?? ctxValue?.view.zoom ?? 1;
+  const effectivePxPerUnit = pixelsPerUnit * effectiveZoom;
+  const targetUnits = targetWidth / effectivePxPerUnit;
+  const niceUnits = niceNumber(targetUnits);
+  const barWidth = niceUnits * effectivePxPerUnit;
+  return (
+    <div className="lk-scale-indicator" role="img" aria-label={`Scale: ${niceUnits} ${unit}`}>
+      <div className="lk-scale-indicator-bar" style={{ width: `${barWidth}px` }} />
+      <span className="lk-scale-indicator-label">
+        {niceUnits} {unit}
+      </span>
+    </div>
+  );
+}

package/src/primitives/Sidebar.less

@@ -0,0 +1,57 @@
+.lk-sidebar {
+  display: flex;
+  flex-direction: column;
+  width: 280px;
+  background: var(--lk-bg-elevated);
+  border-left: 1px solid var(--lk-border);
+  transition: width 150ms ease;
+
+  &--collapsed {
+    width: 32px;
+  }
+}
+
+.lk-sidebar-header {
+  display: flex;
+  align-items: center;
+  padding: var(--lk-spacing-xs) var(--lk-spacing-sm);
+  border-bottom: 1px solid var(--lk-divider);
+  min-height: var(--lk-control-height);
+}
+
+.lk-sidebar-title {
+  flex: 1;
+  font-weight: 600;
+  color: var(--lk-text);
+  font-size: var(--lk-font-size);
+
+  .lk-sidebar--collapsed & {
+    display: none;
+  }
+}
+
+.lk-sidebar-toggle {
+  height: 24px;
+  width: 24px;
+  padding: 0;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--lk-radius-sm);
+  color: var(--lk-text-muted);
+  cursor: pointer;
+
+  &:hover {
+    background: var(--lk-bg);
+    color: var(--lk-text);
+  }
+}
+
+.lk-sidebar-body {
+  flex: 1;
+  overflow: auto;
+  padding: var(--lk-spacing-sm);
+
+  .lk-sidebar--collapsed & {
+    display: none;
+  }
+}

package/src/primitives/Sidebar.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { Sidebar } from './Sidebar';
+
+const meta: Meta<typeof Sidebar> = {
+  title: 'labkit/Primitives/Sidebar',
+  component: Sidebar,
+};
+export default meta;
+
+type Story = StoryObj<typeof Sidebar>;
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ display: 'flex', height: 400 }}>
+      <div style={{ flex: 1 }}>main content area</div>
+      <Sidebar title="Controls">
+        <p>One slider here</p>
+        <p>Another slider</p>
+      </Sidebar>
+    </div>
+  ),
+};
+
+export const Collapsible: Story = {
+  render: function Render() {
+    const [collapsed, setCollapsed] = useState(false);
+    return (
+      <div style={{ display: 'flex', height: 400 }}>
+        <div style={{ flex: 1, padding: 16 }}>main content area</div>
+        <Sidebar title="Controls" collapsed={collapsed} onToggle={() => setCollapsed((c) => !c)}>
+          <p>One slider here</p>
+          <p>Another slider</p>
+        </Sidebar>
+      </div>
+    );
+  },
+};

package/src/primitives/Sidebar.test.tsx

@@ -0,0 +1,74 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { Sidebar } from './Sidebar';
+
+describe('Sidebar', () => {
+  test('renders children when expanded (default)', () => {
+    render(
+      <Sidebar>
+        <p>content</p>
+      </Sidebar>,
+    );
+    expect(screen.getByText('content')).toBeInTheDocument();
+  });
+
+  test('renders title when provided', () => {
+    render(
+      <Sidebar title="Controls">
+        <p>x</p>
+      </Sidebar>,
+    );
+    expect(screen.getByText('Controls')).toBeInTheDocument();
+  });
+
+  test('marks the sidebar collapsed and nests body inside the collapsed root', () => {
+    const { container } = render(
+      <Sidebar collapsed>
+        <p>content</p>
+      </Sidebar>,
+    );
+    const root = container.querySelector('.lk-sidebar');
+    const body = container.querySelector('.lk-sidebar-body');
+    expect(root).not.toBeNull();
+    expect(body).not.toBeNull();
+    expect(root?.classList.contains('lk-sidebar--collapsed')).toBe(true);
+    // Body is still rendered (children stay in DOM), but lives inside the collapsed
+    // root so the CSS rule `.lk-sidebar--collapsed .lk-sidebar-body { display:none }` applies.
+    expect(body?.parentElement).toBe(root);
+    expect(body?.textContent).toBe('content');
+  });
+
+  test('toggle button calls onToggle when clicked', () => {
+    let toggled = false;
+    render(
+      <Sidebar
+        title="C"
+        onToggle={() => {
+          toggled = true;
+        }}
+      >
+        <p>x</p>
+      </Sidebar>,
+    );
+    screen.getByRole('button', { name: /collapse|expand/i }).click();
+    expect(toggled).toBe(true);
+  });
+
+  test('shows expand label when collapsed', () => {
+    render(
+      <Sidebar title="C" collapsed onToggle={() => {}}>
+        <p>x</p>
+      </Sidebar>,
+    );
+    expect(screen.getByRole('button', { name: /expand/i })).toBeInTheDocument();
+  });
+
+  test('shows collapse label when expanded', () => {
+    render(
+      <Sidebar title="C" onToggle={() => {}}>
+        <p>x</p>
+      </Sidebar>,
+    );
+    expect(screen.getByRole('button', { name: /collapse/i })).toBeInTheDocument();
+  });
+});

package/src/primitives/Sidebar.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+
+export interface SidebarProps {
+  children: ReactNode;
+  title?: string;
+  collapsed?: boolean;
+  onToggle?: () => void;
+}
+
+export function Sidebar({ children, title, collapsed = false, onToggle }: SidebarProps) {
+  const className = `lk-sidebar${collapsed ? ' lk-sidebar--collapsed' : ''}`;
+  return (
+    <aside className={className}>
+      {(title || onToggle) && (
+        <div className="lk-sidebar-header">
+          {title && <span className="lk-sidebar-title">{title}</span>}
+          {onToggle && (
+            <button
+              type="button"
+              className="lk-sidebar-toggle"
+              onClick={onToggle}
+              aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+            >
+              {collapsed ? '›' : '‹'}
+            </button>
+          )}
+        </div>
+      )}
+      <div className="lk-sidebar-body">{children}</div>
+    </aside>
+  );
+}

package/src/primitives/StatusBar.less

@@ -0,0 +1,21 @@
+.lk-status-bar {
+  display: flex;
+  align-items: center;
+  gap: var(--lk-spacing-md);
+  padding: var(--lk-spacing-xs) var(--lk-spacing-sm);
+  background: var(--lk-bg-elevated);
+  border-top: 1px solid var(--lk-border);
+  font-size: var(--lk-font-size-sm);
+  color: var(--lk-text-muted);
+  font-family: var(--lk-font-mono);
+}
+
+.lk-status-bar-section {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--lk-spacing-xs);
+  padding: 0 var(--lk-spacing-xs);
+  border-right: 1px solid var(--lk-divider);
+
+  &:last-child { border-right: none; }
+}

package/src/primitives/StatusBar.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { StatusBar } from './StatusBar';
+
+const meta: Meta<typeof StatusBar> = {
+  title: 'labkit/Primitives/StatusBar',
+  component: StatusBar,
+};
+export default meta;
+
+type Story = StoryObj<typeof StatusBar>;
+
+export const Plain: Story = {
+  render: () => <StatusBar>Ready</StatusBar>,
+};
+
+export const Sections: Story = {
+  render: () => (
+    <StatusBar>
+      <StatusBar.Section>Items: 12</StatusBar.Section>
+      <StatusBar.Section>Zoom: 100%</StatusBar.Section>
+      <StatusBar.Section>FPS: 60</StatusBar.Section>
+    </StatusBar>
+  ),
+};

package/src/primitives/StatusBar.test.tsx

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { StatusBar } from './StatusBar';
+
+describe('StatusBar', () => {
+  test('renders children', () => {
+    render(<StatusBar>3 items</StatusBar>);
+    expect(screen.getByText('3 items')).toBeInTheDocument();
+  });
+
+  test('uses lk-status-bar class', () => {
+    const { container } = render(<StatusBar>x</StatusBar>);
+    expect((container.firstChild as HTMLElement).className).toBe('lk-status-bar');
+  });
+
+  test('renders multiple section children separated', () => {
+    const { container } = render(
+      <StatusBar>
+        <StatusBar.Section>left</StatusBar.Section>
+        <StatusBar.Section>right</StatusBar.Section>
+      </StatusBar>,
+    );
+    expect(container.querySelectorAll('.lk-status-bar-section').length).toBe(2);
+  });
+});

package/src/primitives/StatusBar.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+
+export interface StatusBarProps {
+  children: ReactNode;
+}
+
+export function StatusBar({ children }: StatusBarProps) {
+  return <div className="lk-status-bar">{children}</div>;
+}
+
+interface SectionProps {
+  children: ReactNode;
+}
+function Section({ children }: SectionProps) {
+  return <span className="lk-status-bar-section">{children}</span>;
+}
+
+StatusBar.Section = Section;