@weasel-js/labkit 1.7.0 → 1.7.2

package/src/config/auto.ts

@@ -10,6 +10,7 @@ export const auto: unique symbol = Symbol('weasel.auto');
 /** The type of the `auto` sentinel, for widening a value parameter. */
 export type Auto = typeof auto;
 
+/** Whether `value` is the `auto` sentinel. */
 export function isAuto(value: unknown): value is Auto {
   return value === auto;
 }

package/src/config/builder.ts

@@ -124,6 +124,7 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
   }
 }
 
+/** A numeric leaf, built by `f.number`. */
 export class NumberNode extends BaseNode<number> {
   readonly kind = 'number';
 
@@ -169,6 +170,7 @@ export class NumberNode extends BaseNode<number> {
   }
 }
 
+/** A true/false leaf, built by `f.boolean`; a checkbox unless `.toggle()`. */
 export class BooleanNode extends BaseNode<boolean> {
   readonly kind = 'boolean';
 
@@ -178,6 +180,7 @@ export class BooleanNode extends BaseNode<boolean> {
   }
 }
 
+/** A text leaf, built by `f.string`. */
 export class StringNode extends BaseNode<string> {
   readonly kind = 'string';
 
@@ -195,6 +198,7 @@ export class StringNode extends BaseNode<string> {
   }
 }
 
+/** A string-list leaf, built by `f.list`. */
 export class ListNode extends BaseNode<string[]> {
   readonly kind = 'list';
 
@@ -204,6 +208,7 @@ export class ListNode extends BaseNode<string[]> {
   }
 }
 
+/** A color leaf holding a hex string, built by `f.color`. */
 export class ColorNode extends BaseNode<string> {
   readonly kind = 'color';
 
@@ -214,6 +219,7 @@ export class ColorNode extends BaseNode<string> {
   }
 }
 
+/** A fixed-choice leaf, built by `f.enum`; a select unless `.radio()`. */
 export class EnumNode<T extends string> extends BaseNode<T> {
   readonly kind = 'enum';
 

package/src/config/types.ts

@@ -14,7 +14,8 @@ export interface ConfigOption {
   value: string;
   label: string;
   /** A glyph in weasel-ui's icon set (`IconName`). A segmented row draws it in
-   *  place of `label`, which stays the accessible name and becomes the tooltip. */
+   *  place of `label`, which stays the accessible name and becomes the tooltip;
+   *  a select draws it beside `label`. */
   icon?: string;
 }
 

package/src/controls/ControlMatrix.less

@@ -0,0 +1,245 @@
+// A settings-by-scopes grid. Built to sit beside a ControlPanel in a ~360px
+// sidebar: the label column takes what seven value columns leave, and every cell
+// is a fixed-height button so the rows rule up evenly.
+.lk-control-matrix {
+  min-width: 0;
+}
+
+.lk-control-matrix__table {
+  width: 100%;
+  table-layout: fixed;
+  border-collapse: collapse;
+  font-family: var(--wzl-font-ui);
+  font-size: var(--wzl-font-size-xs);
+  color: var(--wzl-fg);
+}
+
+.lk-control-matrix__corner {
+  width: var(--lk-control-matrix-label-width, 30%);
+}
+
+.lk-control-matrix__head,
+.lk-control-matrix__label {
+  font-family: var(--wzl-font-display);
+  font-weight: var(--wzl-font-weight-light);
+  font-size: var(--wzl-font-size-sm);
+  line-height: var(--wzl-leading-snug);
+  color: var(--wzl-fg-muted);
+  text-transform: var(--wzl-params-label-case, uppercase);
+  letter-spacing: var(--wzl-params-label-tracking, var(--wzl-tracking-wide));
+}
+
+.lk-control-matrix__head {
+  padding: 0 0 var(--wzl-space-2);
+  text-align: center;
+  font-size: var(--wzl-font-size-2xs);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+// The fallback scope every other column inherits from.
+.lk-control-matrix__head.is-first {
+  color: var(--wzl-fg);
+  font-weight: var(--wzl-font-weight-medium);
+}
+
+.lk-control-matrix__head-text {
+  text-decoration: none;
+  cursor: default;
+}
+
+.lk-control-matrix__head-button {
+  width: 100%;
+  padding: 0;
+  border: 0;
+  border-radius: var(--wzl-radius-sm);
+  background: none;
+  color: inherit;
+  font: inherit;
+  letter-spacing: var(--wzl-params-label-tracking, var(--wzl-tracking-wide));
+  text-transform: var(--wzl-params-label-case, uppercase);
+  cursor: pointer;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.lk-control-matrix__head-button:hover {
+  color: var(--wzl-fg);
+  background: var(--wzl-surface-hover);
+}
+
+.lk-control-matrix__label {
+  padding: 0 var(--wzl-space-2) 0 0;
+  text-align: start;
+  white-space: nowrap;
+}
+
+// The text truncates; the help glyph after it never does.
+.lk-control-matrix__label-text {
+  display: inline-block;
+  max-width: calc(100% - 1.4em);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  vertical-align: middle;
+}
+
+.lk-control-matrix__cell {
+  padding: 1px;
+  height: var(--wzl-control-h-sm);
+  text-align: center;
+  vertical-align: middle;
+}
+
+.lk-control-matrix__cell.is-missing {
+  color: var(--wzl-fg-subtle);
+}
+
+// Inherited: the value in effect, but not chosen here.
+.lk-control-matrix__cell.is-inherited > * {
+  opacity: 0.4;
+}
+
+// Every cell control fills its cell, so the cell is the click target.
+.lk-control-matrix__value,
+.lk-control-matrix__switch {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: var(--wzl-control-h-sm);
+  padding: 0 var(--wzl-space-1);
+  border: 1px solid transparent;
+  border-radius: var(--wzl-radius-sm);
+  background: none;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.lk-control-matrix__value {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  line-height: calc(var(--wzl-control-h-sm) - 2px);
+}
+
+.lk-control-matrix__value.is-number {
+  .numeric();
+  text-align: end;
+  // A column of numbers is read down, so it keeps every digit: a glow of
+  // 0.35 cut to `0…` says nothing.
+  text-overflow: clip;
+}
+
+.lk-control-matrix__value:hover,
+.lk-control-matrix__switch:hover {
+  border-color: var(--wzl-border);
+  background: var(--wzl-surface-hover);
+}
+
+.lk-control-matrix__value:focus-visible,
+.lk-control-matrix__switch:focus-visible,
+.lk-control-matrix__swatch:focus-visible,
+.lk-control-matrix__head-button:focus-visible {
+  outline: 2px solid var(--wzl-focus-ring);
+  outline-offset: -1px;
+}
+
+// A small switch, drawn with the same parts as weasel-ui's.
+.lk-control-matrix__track {
+  position: relative;
+  flex: 0 0 auto;
+  width: 20px;
+  height: 12px;
+  background: var(--wzl-surface-sunken);
+  border: 1px solid var(--wzl-border-strong);
+  border-radius: var(--wzl-radius-pill);
+  transition: background-color var(--wzl-motion-fast), border-color var(--wzl-motion-fast);
+}
+
+.lk-control-matrix__thumb {
+  position: absolute;
+  top: 1px;
+  left: 1px;
+  width: 8px;
+  height: 8px;
+  background: var(--wzl-fg);
+  border-radius: 50%;
+  transition: transform var(--wzl-motion-fast);
+}
+
+.lk-control-matrix__switch[aria-checked='true'] .lk-control-matrix__track {
+  background: var(--wzl-accent-strong);
+  border-color: var(--wzl-accent-strong);
+}
+
+.lk-control-matrix__switch[aria-checked='true'] .lk-control-matrix__thumb {
+  transform: translateX(8px);
+  background: var(--wzl-fg-on-accent);
+}
+
+.lk-control-matrix__swatch {
+  display: block;
+  width: 100%;
+  height: var(--wzl-control-h-xs);
+  padding: 0;
+  border: 1px solid var(--wzl-border);
+  border-radius: var(--wzl-radius-sm);
+  background: none;
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.lk-control-matrix__swatch::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.lk-control-matrix__swatch::-webkit-color-swatch {
+  border: 0;
+  border-radius: var(--wzl-radius-sm);
+}
+
+.lk-control-matrix__swatch::-moz-color-swatch {
+  border: 0;
+  border-radius: var(--wzl-radius-sm);
+}
+
+.lk-control-matrix__chip {
+  display: inline-block;
+  width: 22px;
+  height: var(--wzl-control-h-xs);
+  border: 1px solid var(--wzl-border);
+  border-radius: var(--wzl-radius-sm);
+  background: var(--lk-chip);
+  vertical-align: middle;
+}
+
+.lk-control-matrix__chip.is-unset {
+  border-style: dashed;
+  background: none;
+}
+
+.lk-control-matrix__popover {
+  outline: none;
+}
+
+.lk-control-matrix__editor {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-3);
+  inline-size: 240px;
+  padding: var(--wzl-space-4);
+  background: var(--wzl-surface-raised);
+  border: 1px solid var(--wzl-border);
+  border-radius: var(--wzl-radius-md);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
+  outline: none;
+}
+
+.lk-control-matrix__editor-actions {
+  display: flex;
+  justify-content: flex-end;
+}

package/src/controls/ControlMatrix.stories.less

@@ -0,0 +1,13 @@
+// A sidebar-width frame for the ControlMatrix stories.
+.lk-control-matrix-story {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-5);
+  width: 360px;
+}
+
+.lk-control-matrix-story__note {
+  margin: 0;
+  color: var(--wzl-fg-muted);
+  font-size: var(--wzl-font-size-sm);
+}

package/src/controls/ControlMatrix.stories.tsx

@@ -0,0 +1,135 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { useMemo, useState } from 'react';
+import { isAuto } from '../config/auto';
+import { f } from '../config/builder';
+import { valueAtPath, withValueAtPath } from '../config/path';
+import { resolveConfigSchema } from '../config/resolve';
+import { ControlMatrix, type ControlMatrixColumn } from './ControlMatrix';
+import { ControlPanel } from './ControlPanel';
+import './ControlMatrix.stories.less';
+
+const meta: Meta<typeof ControlMatrix> = {
+  title: 'labkit/Controls/ControlMatrix',
+  component: ControlMatrix,
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof ControlMatrix>;
+
+const look = () => ({
+  background: f.boolean(true).describe('Paint the box behind the primitive.'),
+  fill: f.color('#2f5d8a'),
+  border: f.number(1).range(0, 4).step(0.5).input().suffix('px'),
+  shading: f.enum('flat', [
+    { value: 'flat', label: 'Flat' },
+    { value: 'soft', label: 'Soft' },
+    { value: 'bevel', label: 'Bevel' },
+  ]),
+  glow: f.number(0).range(0, 1).step(0.05).describe('Halo strength around the primitive.'),
+});
+
+const primitives = ['window', 'page', 'slab', 'row', 'tile', 'arrow'] as const;
+const LOOK_KEYS = Object.keys(look()) as (keyof ReturnType<typeof look>)[];
+
+const config = f.schema({
+  looks: f.group({
+    defaults: f.group(look()),
+    window: f.group(look()),
+    page: f.group(look()),
+    slab: f.group(look()),
+    row: f.group(look()),
+    tile: f.group(look()),
+    // An arrow is a line: it has nothing to fill and no box behind it.
+    arrow: f.group({ border: look().border, shading: look().shading, glow: look().glow }),
+  }),
+});
+
+const columns: ControlMatrixColumn[] = [
+  { key: 'looks.defaults', label: 'Def', title: 'Defaults' },
+  { key: 'looks.window', label: 'Win', title: 'Window' },
+  { key: 'looks.page', label: 'Page', title: 'Page' },
+  { key: 'looks.slab', label: 'Slab', title: 'Slab' },
+  { key: 'looks.row', label: 'Row', title: 'Row' },
+  { key: 'looks.tile', label: 'Tile', title: 'Tile' },
+  { key: 'looks.arrow', label: 'Arr', title: 'Arrow' },
+];
+const rows = LOOK_KEYS.map((key) => ({ key }));
+
+/**
+ * The store the consumer keeps: Defaults always, a primitive's setting only
+ * once it is pinned. A missing value inherits.
+ */
+function useLooks() {
+  const schema = useMemo(() => resolveConfigSchema(config, []), []);
+  const [stored, setStored] = useState<Record<string, unknown>>(() => ({
+    looks: {
+      defaults: config.defaults().looks.defaults,
+      window: { fill: '#6b3f8f', glow: 0.35 },
+      arrow: { border: 2 },
+    },
+  }));
+  const autoPaths = new Set<string>();
+  let shown: Record<string, unknown> = stored;
+  for (const p of primitives) {
+    for (const key of LOOK_KEYS) {
+      const path = `looks.${p}.${key}`;
+      if (valueAtPath(stored, path) !== undefined) continue;
+      autoPaths.add(path);
+      shown = withValueAtPath(shown, path, valueAtPath(stored, `looks.defaults.${key}`));
+    }
+  }
+  const setConfig = (path: string, value: unknown) =>
+    setStored((prev) => withValueAtPath(prev, path, isAuto(value) ? undefined : value));
+  return { schema, shown, autoPaths, setConfig };
+}
+
+/** Six primitives and their Defaults in a 360px sidebar. Click a cell to edit
+ *  it, Option-click a pinned one to hand it back to Defaults. */
+export const Looks: Story = {
+  render: function Render() {
+    const { schema, shown, autoPaths, setConfig } = useLooks();
+    const [focused, setFocused] = useState<string | null>(null);
+    return (
+      <div className="lk-control-matrix-story">
+        <ControlMatrix
+          title="Looks"
+          schema={schema}
+          columns={columns}
+          rows={rows}
+          config={shown}
+          auto={autoPaths}
+          setConfig={setConfig}
+          onColumnClick={(c) => setFocused(c.title ?? c.label)}
+        />
+        {focused ? <p className="lk-control-matrix-story__note">Clicked {focused}</p> : null}
+      </div>
+    );
+  },
+};
+
+/** The matrix under the panel it sits beside, to check the two read as one family. */
+export const BesideControlPanel: Story = {
+  render: function Render() {
+    const { schema, shown, autoPaths, setConfig } = useLooks();
+    return (
+      <div className="lk-control-matrix-story">
+        <ControlPanel
+          title="Defaults"
+          schema={resolveConfigSchema(f.schema(look()), [])}
+          config={valueAtPath(shown, 'looks.defaults') as Record<string, unknown>}
+          setConfig={(path, value) => setConfig(`looks.defaults.${path}`, value)}
+        />
+        <ControlMatrix
+          title="Per primitive"
+          schema={schema}
+          columns={columns}
+          rows={rows}
+          config={shown}
+          auto={autoPaths}
+          setConfig={setConfig}
+        />
+      </div>
+    );
+  },
+};

package/src/controls/ControlMatrix.test.tsx

@@ -0,0 +1,206 @@
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { auto } from '../config/auto';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
+import { ControlMatrix, type ControlMatrixColumn } from './ControlMatrix';
+
+const look = () => ({
+  background: f.boolean(true).label('Background'),
+  fill: f.color('#336699').label('Fill'),
+  glow: f.number(0.25).range(0, 1).step(0.05).label('Glow').describe('Halo around the shape.'),
+  shading: f.enum('flat', [
+    { value: 'flat', label: 'Flat' },
+    { value: 'soft', label: 'Soft' },
+  ]),
+});
+
+const schema = resolveConfigSchema(
+  f.schema({
+    looks: f.group({
+      defaults: f.group(look()),
+      window: f.group(look()),
+      // An arrow has no fill.
+      arrow: f.group({ background: look().background, glow: look().glow, shading: look().shading }),
+    }),
+  }),
+  [],
+);
+
+const columns: ControlMatrixColumn[] = [
+  { key: 'looks.defaults', label: 'Def', title: 'Defaults' },
+  { key: 'looks.window', label: 'Win', title: 'Window' },
+  { key: 'looks.arrow', label: 'Arr', title: 'Arrow' },
+];
+const rows = [{ key: 'background' }, { key: 'fill' }, { key: 'glow' }, { key: 'shading' }];
+
+const value = { background: true, fill: '#336699', glow: 0.25, shading: 'flat' };
+const config = {
+  looks: {
+    defaults: value,
+    window: { ...value, glow: 0.5 },
+    arrow: { background: true, glow: 0.25, shading: 'soft' },
+  },
+};
+
+function setup(over: Partial<Parameters<typeof ControlMatrix>[0]> = {}) {
+  const setConfig = vi.fn();
+  const utils = render(
+    <ControlMatrix
+      schema={schema}
+      columns={columns}
+      rows={rows}
+      config={config}
+      auto={new Set(['looks.window.background', 'looks.window.fill', 'looks.arrow.glow'])}
+      setConfig={setConfig}
+      {...over}
+    />,
+  );
+  return { setConfig, ...utils };
+}
+
+const cell = (name: string) => screen.getByLabelText(name, { exact: false });
+
+describe('<ControlMatrix>', () => {
+  it('draws a table of settings by scopes, labels from the schema', () => {
+    setup();
+    const table = screen.getByRole('table');
+    expect(
+      within(table)
+        .getAllByRole('columnheader')
+        .map((h) => h.textContent),
+    ).toEqual(['Def', 'Win', 'Arr']);
+    expect(
+      within(table)
+        .getAllByRole('rowheader')
+        .map((h) => h.textContent),
+    ).toEqual(['Background', 'Fill', 'Glowⓘ', 'Shading']);
+    expect(screen.getByRole('button', { name: 'About Glow' })).toBeTruthy();
+  });
+
+  it('shows numbers at their step precision and enums by label', () => {
+    setup();
+    expect(cell('Defaults Glow').textContent).toBe('0.25');
+    expect(cell('Window Glow').textContent).toBe('0.50');
+    expect(cell('Arrow Shading').textContent).toBe('Soft');
+  });
+
+  it('draws a dash for a scope with no such setting', () => {
+    setup();
+    const none = screen.getByLabelText('Arrow has no Fill');
+    expect(none.textContent).toBe('—');
+    expect(none.closest('td')?.className).toMatch(/is-missing/);
+    expect(none.closest('td')?.querySelector('button, input')).toBeNull();
+  });
+
+  it('ghosts an inherited cell and names where it inherits from', () => {
+    setup();
+    const inherited = screen.getByRole('switch', { name: 'Window Background, from Defaults' });
+    expect(inherited.closest('td')?.className).toMatch(/is-inherited/);
+    const pinned = screen.getByRole('switch', { name: 'Defaults Background' });
+    expect(pinned.closest('td')?.className).not.toMatch(/is-inherited/);
+  });
+
+  it('takes the inherit hint from a prop', () => {
+    setup({ inheritHint: (c) => `${c.title} follows the default` });
+    expect(
+      screen.getByRole('switch', { name: 'Window Background, Window follows the default' }),
+    ).toBeTruthy();
+  });
+
+  it('flips a boolean in place, which pins it', () => {
+    const { setConfig } = setup();
+    fireEvent.click(screen.getByRole('switch', { name: /^Window Background/ }));
+    expect(setConfig).toHaveBeenCalledWith('looks.window.background', false);
+  });
+
+  it('opens a color picker in place, which pins it', () => {
+    const { setConfig } = setup();
+    const swatch = cell('Window Fill') as HTMLInputElement;
+    expect(swatch.type).toBe('color');
+    fireEvent.change(swatch, { target: { value: '#ff0000' } });
+    expect(setConfig).toHaveBeenCalledWith('looks.window.fill', '#ff0000');
+  });
+
+  it('draws an unset color as unset, and clears a set one from its popover', () => {
+    const edge = resolveConfigSchema(
+      f.schema({
+        a: f.group({ edge: f.color('').label('Edge') }),
+        b: f.group({ edge: f.color('').label('Edge') }),
+      }),
+      [],
+    );
+    const setConfig = vi.fn();
+    render(
+      <ControlMatrix
+        schema={edge}
+        columns={[
+          { key: 'a', label: 'A', title: 'Alpha' },
+          { key: 'b', label: 'B', title: 'Beta' },
+        ]}
+        rows={[{ key: 'edge' }]}
+        config={{ a: { edge: null }, b: { edge: '#ff0000' } }}
+        auto={new Set()}
+        setConfig={setConfig}
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Alpha Edge, unset' })).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Beta Edge' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Clear' }));
+    expect(setConfig).toHaveBeenCalledWith('b.edge', null);
+  });
+
+  it('edits any other cell in a popover holding the panel control, which pins it', () => {
+    const { setConfig } = setup();
+    fireEvent.click(cell('Window Glow'));
+    const dialog = screen.getByRole('dialog', { name: 'Window Glow' });
+    fireEvent.change(within(dialog).getByRole('slider'), { target: { value: '0.75' } });
+    expect(setConfig).toHaveBeenCalledWith('looks.window.glow', 0.75);
+  });
+
+  it('unpins from the popover with Inherit, disabled while already inherited', () => {
+    const { setConfig, unmount } = setup();
+    fireEvent.click(cell('Window Glow'));
+    const inherit = screen.getByRole('button', { name: 'Inherit' });
+    expect(inherit).not.toBeDisabled();
+    fireEvent.click(inherit);
+    expect(setConfig).toHaveBeenCalledWith('looks.window.glow', auto);
+    unmount();
+
+    setup();
+    fireEvent.click(cell('Arrow Glow'));
+    expect(screen.getByRole('button', { name: 'Inherit' })).toBeDisabled();
+  });
+
+  it('has no Inherit for the fallback column', () => {
+    setup();
+    fireEvent.click(cell('Defaults Glow'));
+    expect(screen.getByRole('dialog', { name: 'Defaults Glow' })).toBeTruthy();
+    expect(screen.queryByRole('button', { name: 'Inherit' })).toBeNull();
+  });
+
+  it('unpins a pinned cell on Alt-click, without flipping or opening it', () => {
+    const { setConfig } = setup();
+    fireEvent.click(cell('Window Glow'), { altKey: true });
+    expect(setConfig).toHaveBeenCalledWith('looks.window.glow', auto);
+    expect(screen.queryByRole('dialog')).toBeNull();
+
+    setConfig.mockClear();
+    fireEvent.click(screen.getByRole('switch', { name: 'Defaults Background' }), { altKey: true });
+    fireEvent.click(screen.getByRole('switch', { name: /^Window Background/ }), { altKey: true });
+    // The fallback cannot inherit, and an inherited cell is already unpinned.
+    expect(setConfig).not.toHaveBeenCalled();
+  });
+
+  it('calls onColumnClick from a header button', () => {
+    const onColumnClick = vi.fn();
+    setup({ onColumnClick });
+    fireEvent.click(screen.getByRole('button', { name: 'Window' }));
+    expect(onColumnClick).toHaveBeenCalledWith(columns[1]);
+  });
+
+  it('draws plain headers without onColumnClick', () => {
+    setup();
+    expect(screen.queryByRole('button', { name: 'Window' })).toBeNull();
+  });
+});