@weasel-js/labkit 1.7.1 → 1.7.2

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