cursedbelt 5.59.0 → 5.63.0

package/src/react/components/ColorSwatches.spec.tsx

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { ColorSwatches } from './ColorSwatches.js';
+
+afterEach(cleanup);
+
+// guardrails-ignore no-hardcoded-colors: task 2829 — a colour picker's test data; the browser's well speaks only hex, so hex is the subject
+const [BLUE, GREEN, RED, CUSTOM, PICKED] = ['#2563eb', '#16a34a', '#DC2626', '#123456', '#ABCDEF'];
+const PRESETS = [BLUE, GREEN, RED];
+
+describe('ColorSwatches', () => {
+  test('the presets are ONE radiogroup, named, one radio per dot, then the any-colour well', () => {
+    const { getByRole, getAllByRole, getByLabelText } = render(
+      <ColorSwatches aria-label='Accent' presets={PRESETS} value={BLUE} onChange={() => {}} />,
+    );
+    expect(getByRole('radiogroup').getAttribute('aria-label')).toBe('Accent');
+    expect(getAllByRole('radio')).toHaveLength(3);
+    const well = getByLabelText('Any colour') as HTMLInputElement;
+    expect(well.type).toBe('color');
+  });
+
+  test('a preset value checks its dot — case-insensitively — and leaves the well unchecked', () => {
+    const { getAllByRole, container } = render(<ColorSwatches presets={PRESETS} value={RED.toLowerCase()} onChange={() => {}} />);
+    const checked = getAllByRole('radio').filter((radio) => radio.getAttribute('aria-checked') === 'true');
+    expect(checked.map((radio) => radio.getAttribute('aria-label'))).toEqual([RED]);
+    expect(container.querySelector('[data-slot="color-swatches-custom"]')?.getAttribute('data-state')).toBe('unchecked');
+  });
+
+  test('🔴 a colour outside the presets checks the WELL, which wears it — no preset lights (task 2829)', () => {
+    const { getAllByRole, container, getByLabelText } = render(<ColorSwatches presets={PRESETS} value={CUSTOM} onChange={() => {}} />);
+    expect(getAllByRole('radio').some((radio) => radio.getAttribute('aria-checked') === 'true')).toBe(false);
+    const custom = container.querySelector<HTMLElement>('[data-slot="color-swatches-custom"]');
+    expect(custom?.getAttribute('data-state')).toBe('checked');
+    expect(custom?.getAttribute('style')).toContain(CUSTOM);
+    expect((getByLabelText('Any colour') as HTMLInputElement).value).toBe(CUSTOM);
+  });
+
+  test('with no custom colour the well is painted from the theme ramp, not literals', () => {
+    const { container } = render(<ColorSwatches presets={PRESETS} value={BLUE} onChange={() => {}} />);
+    const custom = container.querySelector<HTMLElement>('[data-slot="color-swatches-custom"]');
+    expect(custom?.getAttribute('style')).toContain('var(--chart-1)');
+  });
+
+  test('picking a dot reports its preset; picking in the well reports lower-case hex', () => {
+    const picked: string[] = [];
+    const { getAllByRole, getByLabelText } = render(<ColorSwatches presets={PRESETS} value={BLUE} onChange={(c) => picked.push(c)} />);
+    fireEvent.click(getAllByRole('radio')[1] as HTMLElement);
+    fireEvent.change(getByLabelText('Any colour'), { target: { value: PICKED } });
+    expect(picked).toEqual([GREEN, PICKED.toLowerCase()]);
+  });
+
+  test('the well follows a value changed from outside', () => {
+    const { getByLabelText, rerender } = render(<ColorSwatches presets={PRESETS} value={CUSTOM} onChange={() => {}} />);
+    rerender(<ColorSwatches presets={PRESETS} value={GREEN} onChange={() => {}} />);
+    expect((getByLabelText('Any colour') as HTMLInputElement).value).toBe(GREEN);
+  });
+
+  test('`custom={false}` is the presets alone', () => {
+    const { queryByLabelText } = render(<ColorSwatches presets={PRESETS} value={undefined} custom={false} onChange={() => {}} />);
+    expect(queryByLabelText('Any colour')).toBeNull();
+  });
+});

package/src/react/components/ColorSwatches.tsx

@@ -0,0 +1,100 @@
+import { type CSSProperties, useEffect, useRef } from 'react';
+import { cn } from '../lib/cn.js';
+import { TAP_TARGET_SQUARE } from '../lib/tapTarget.js';
+import { SwatchPicker } from './SwatchPicker.js';
+
+export interface ColorSwatchesProps {
+  /** The preset dots, in order. Any CSS colour; a 6-digit hex is what the custom well can open on. */
+  presets: readonly string[];
+  /** The current colour — one of the presets, or any other colour picked through the well. */
+  value: string | undefined;
+  onChange: (color: string) => void;
+  /** Offer a last dot for any colour (the browser's own colour well). Default `true`. */
+  custom?: boolean;
+  /** The custom dot's accessible name. Default "Any colour". */
+  customLabel?: string;
+  /** Dot diameter, as `SwatchPicker`'s: `sm` 1.5rem, `md` (default) 1.75rem, `lg` 2.25rem. */
+  size?: 'sm' | 'md' | 'lg';
+  /** Accessible name for the preset group (default "Colour"). */
+  'aria-label'?: string;
+  className?: string;
+}
+
+const SIZE = { sm: 'size-6', md: 'size-7', lg: 'size-9' } as const;
+const HEX6 = /^#[0-9a-f]{6}$/i;
+/** The any-colour dot before a custom colour is picked: the theme's categorical ramp, round the dial. */
+const RAMP =
+  'conic-gradient(var(--chart-1), var(--chart-2), var(--chart-3), var(--chart-4), var(--chart-5), var(--chart-6), var(--chart-7), var(--chart-8), var(--chart-1))';
+
+/**
+ * `ColorSwatches` — an accent picker drawn as ONE row of dots: the presets, then a last dot for
+ * any colour. The preset dots are a {@link SwatchPicker} radiogroup (Radix: radio semantics,
+ * roving tabindex, arrow keys move the choice); the last dot is the browser's colour well, laid
+ * invisibly over a dot painted with the theme's categorical ramp, and becomes that colour —
+ * ringed as the current one — once a colour outside the presets is picked.
+ *
+ * desk drew this twice by hand (its component and list template pages, forge task 2829): a row
+ * of raw buttons, one of them with a raw `<input type="color">` behind an opt-out and the other
+ * with no custom colour at all. `ColorField` is a full-width hex field; this is the compact
+ * "pick an accent for this thing" control, and the next app that wants one takes it from here.
+ *
+ * Matching is case-insensitive, and what the well reports is lower-case hex, so a stored
+ * `#2563EB` still lights its preset.
+ */
+export function ColorSwatches({
+  presets,
+  value,
+  onChange,
+  custom = true,
+  customLabel = 'Any colour',
+  size = 'md',
+  'aria-label': ariaLabel = 'Colour',
+  className,
+}: ColorSwatchesProps) {
+  const current = value?.toLowerCase();
+  const isPreset = current !== undefined && presets.some((color) => color.toLowerCase() === current);
+  const isCustom = current !== undefined && current !== '' && !isPreset;
+  // The well opens on the current colour when it is one it can show. It is uncontrolled and kept
+  // in step here, because a controlled colour input needs a hex for "nothing chosen" and there is
+  // no honest one to write.
+  const wellHex = current !== undefined && HEX6.test(current) ? current : undefined;
+  const well = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    if (well.current && wellHex && well.current.value !== wellHex) well.current.value = wellHex;
+  }, [wellHex]);
+  return (
+    <div data-slot='color-swatches' className={cn('flex flex-wrap items-center gap-1.5', className)}>
+      <SwatchPicker
+        aria-label={ariaLabel}
+        size={size}
+        options={presets.map((color) => ({ value: color.toLowerCase(), color, label: color }))}
+        value={isPreset ? current : undefined}
+        onChange={onChange}
+      />
+      {custom ? (
+        <label
+          data-slot='color-swatches-custom'
+          data-state={isCustom ? 'checked' : 'unchecked'}
+          style={{ '--cb-swatch-fill': isCustom ? value : RAMP } as CSSProperties}
+          className={cn(
+            'relative inline-flex flex-none cursor-pointer rounded-full [background:var(--cb-swatch-fill,var(--muted))] border border-border/40 transition-transform',
+            SIZE[size],
+            TAP_TARGET_SQUARE,
+            'hover:scale-110 focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-1',
+            'data-[state=checked]:ring-2 data-[state=checked]:ring-foreground data-[state=checked]:ring-offset-1',
+          )}
+        >
+          <input
+            // guardrails-ignore no-raw-inputs: task 2829 — the browser's own colour well, laid invisibly over the last dot; a hex field is ColorField's job, not a dot's
+            type='color'
+            ref={well}
+            aria-label={customLabel}
+            defaultValue={wellHex}
+            onChange={(event) => onChange(event.target.value.toLowerCase())}
+            className='absolute inset-0 m-0 size-full cursor-pointer appearance-none border-0 p-0 opacity-0'
+          />
+        </label>
+      ) : null}
+    </div>
+  );
+}

package/src/react/components/EditorPage.spec.tsx

@@ -38,6 +38,24 @@ describe('EditorPage', () => {
     expect(view.getByLabelText('Show names')).toBeTruthy();
   });
 
+  test('each side scrolls on its own through the form kit’s scroller (forge task 2827)', () => {
+    const view = render(<Page />);
+    expect(view.getByLabelText('Name').closest('.cbfk-page-form')?.classList.contains('cbfk-scroll')).toBe(true);
+    expect(view.getByRole('region', { name: 'Card' }).classList.contains('cbfk-scroll')).toBe(true);
+  });
+
+  test('a focused field is scrolled into view, as ScrollArea does (forge task 2827)', async () => {
+    const view = render(<Page />);
+    const field = view.getByLabelText('Name');
+    let scrolled = 0;
+    field.scrollIntoView = () => {
+      scrolled++;
+    };
+    fireEvent.focus(field);
+    await Promise.resolve();
+    expect(scrolled).toBe(1);
+  });
+
   test('the form is quiet by default — Linear’s look, inside .cbfk-quiet', () => {
     const view = render(<Page />);
     expect(view.getByLabelText('Name').closest('.cbfk-quiet')).not.toBeNull();

package/src/react/components/EditorPage.tsx

@@ -10,11 +10,13 @@ import {
   useRef,
   useState,
 } from 'react';
+import { useCaretInView } from '../hooks/useCaretInView.js';
 import { useDiscardGuard } from '../hooks/useDiscardGuard.js';
 import { cn } from '../lib/cn.js';
 import { UnstyledButton } from './UnstyledButton.js';
 import './formKit.css';
 import './editorPage.css';
+import './scrollRegion.css';
 
 export interface EditorPageProps {
   /** What is being made or changed — *"New template"*, *"Edit Dynatrace"*. The page's heading. */
@@ -113,6 +115,9 @@ export function EditorPage({
   const titleId = useId();
   const formId = useId();
   const previewId = useId();
+  // `.cbfk-scroll`'s other half: ScrollArea's explicit scroll-into-view on focus, for a browser
+  // that ignores scroll-padding on its own (forge task 2827).
+  const onFocusCapture = useCaretInView();
 
   const { guardedClose, discardOverlay, isConfirming, cancelDiscard } = useDiscardGuard({ onClose: onBack, isDirty });
 
@@ -227,7 +232,7 @@ export function EditorPage({
         className='cbfk-page-split'
         style={{ '--cbfk-page-split': `${(split * 100).toFixed(2)}%` } as CSSProperties}
       >
-        <div id={formId} className={cn('cbfk-page-form', quiet && 'cbfk-quiet')}>
+        <div id={formId} className={cn('cbfk-page-form cbfk-scroll', quiet && 'cbfk-quiet')} onFocusCapture={onFocusCapture}>
           <div className='cbfk-page-form-inner'>{children}</div>
         </div>
         {/* biome-ignore lint/a11y/useSemanticElements: WAI-ARIA's window splitter is a focusable separator with a value; an <hr> is a static rule that takes neither. */}
@@ -248,7 +253,12 @@ export function EditorPage({
           onKeyDown={onDividerKey}
           onDoubleClick={() => commit(defaultSplit)}
         />
-        <section id={previewId} className='cbfk-page-preview' aria-label={previewLabel}>
+        <section
+          id={previewId}
+          className='cbfk-page-preview cbfk-scroll'
+          aria-label={previewLabel}
+          onFocusCapture={onFocusCapture}
+        >
           <div className='cbfk-page-preview-head'>
             <p className='cbfk-page-preview-label'>{previewLabel}</p>
             {previewTools ? <div className='cbfk-page-preview-tools'>{previewTools}</div> : null}

package/src/react/components/FormPreviewLayout.tsx

@@ -2,6 +2,7 @@ import { ChevronDown } from 'lucide-react';
 import { type ReactNode, useId, useState } from 'react';
 import { cn } from '../lib/cn.js';
 import './formKit.css';
+import './scrollRegion.css';
 
 export interface FormPreviewLayoutProps {
   /** The configuration column — names, pickers, the short fields. */
@@ -80,7 +81,7 @@ export function FormPreviewLayout({
             <ChevronDown aria-hidden />
           </button>
           <p className='cbfk-split-head'>{previewLabel}</p>
-          <div id={bodyId} className='cbfk-split-body'>
+          <div id={bodyId} className='cbfk-split-body cbfk-scroll'>
             {preview}
           </div>
         </section>

package/src/react/components/PropertyList.spec.tsx

@@ -107,4 +107,37 @@ describe('PropertyList', () => {
     expect(dl?.getAttribute('data-density')).toBe('compact');
     expect(container.querySelectorAll('dt')).toHaveLength(1);
   });
+  test('a row carries what the app hangs off it — a class, a data attribute — on the row itself (task 2823)', () => {
+    const { container } = render(
+      <PropertyList>
+        <Property label='Command' className='app-row' data-type='code' data-overridden='true'>
+          kubectl logs
+        </Property>
+      </PropertyList>,
+    );
+    const row = container.querySelector('dl > div');
+    expect(row?.className).toContain('contents');
+    expect(row?.className).toContain('app-row');
+    expect(row?.getAttribute('data-type')).toBe('code');
+    expect(row?.getAttribute('data-overridden')).toBe('true');
+    expect(row?.querySelector('dt')?.textContent).toBe('Command');
+  });
+
+  test('a stacked fact spans both tracks — its label above, its value the whole width (task 2823)', () => {
+    const { container } = render(
+      <PropertyList>
+        <Property label='Command' stacked>
+          <pre>kubectl logs -f deploy/api</pre>
+        </Property>
+        <Property label='Owner'>Ada</Property>
+      </PropertyList>,
+    );
+    const [stacked, inline] = [...container.querySelectorAll('dl > div')];
+    expect(stacked?.getAttribute('data-stacked')).toBe('true');
+    expect(stacked?.querySelector('dt')?.className).toContain('col-span-full');
+    expect(stacked?.querySelector('dd')?.className).toContain('col-span-full');
+    expect(stacked?.querySelector('dd')?.className).not.toMatch(/(^|\s)items-center(\s|$)/);
+    expect(inline?.hasAttribute('data-stacked')).toBe(false);
+    expect(inline?.querySelector('dt')?.className).not.toContain('col-span-full');
+  });
 });

package/src/react/components/PropertyList.tsx

@@ -45,7 +45,7 @@ export function PropertyList({ density = "comfortable", className, children, ...
 	);
 }
 
-export interface PropertyProps {
+export interface PropertyProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
 	/** What the fact is. Plain words, sentence case (CPY-9). */
 	label: ReactNode;
 	/** A 16px mark before the value — Linear's status ring, a person, a calendar. */
@@ -56,18 +56,42 @@ export interface PropertyProps {
 	mono?: boolean;
 	/** Trailing controls that belong to this fact — a copy button, a reset (FRM-6). */
 	action?: ReactNode;
+	/**
+	 * The value takes the list's whole width, under its label — a code block, an image, a
+	 * paragraph that a value column would squeeze to a word per line. The label stays in the
+	 * same muted voice, so a stacked fact still reads as one of the list's.
+	 */
+	stacked?: boolean;
 	children: ReactNode;
 }
 
-/** One fact. Renders nothing when its value is absent, so a caller never filters by hand. */
-export function Property({ label, icon, empty = false, mono = false, action, children }: PropertyProps) {
+/**
+ * One fact. Renders nothing when its value is absent, so a caller never filters by hand.
+ *
+ * The row is a `display: contents` wrapper, so the label and value sit on the LIST's shared
+ * tracks. Anything else given to it — a `className`, a `data-type`, a `data-tone` — lands on that
+ * wrapper, which is what lets an app hang its own customising (a highlighted override, a row a
+ * test finds by type, tools shown on `:hover`) off the row without hand-rolling one (desk, task
+ * 2823: ten `<dl>`s whose rows each carried exactly that).
+ */
+export function Property({ label, icon, empty = false, mono = false, action, stacked = false, className, children, ...row }: PropertyProps) {
 	if (children === undefined || children === null || children === "" || children === false) return null;
 	return (
-		<div className="contents">
-			<dt className="m-0 flex min-h-[var(--control-h-sm)] min-w-0 items-center font-normal text-[var(--muted-foreground)] group-data-[density=compact]/properties:min-h-6 group-data-[density=compact]/properties:items-start">
+		<div {...row} data-stacked={stacked ? "true" : undefined} className={cn("contents", className)}>
+			<dt
+				className={cn(
+					"m-0 flex min-h-[var(--control-h-sm)] min-w-0 items-center font-normal text-[var(--muted-foreground)] group-data-[density=compact]/properties:min-h-6 group-data-[density=compact]/properties:items-start",
+					stacked && "col-span-full",
+				)}
+			>
 				<span className="truncate">{label}</span>
 			</dt>
-			<dd className="m-0 flex min-h-[var(--control-h-sm)] min-w-0 items-center gap-2 group-data-[density=compact]/properties:min-h-6 group-data-[density=compact]/properties:items-start">
+			<dd
+				className={cn(
+					"m-0 flex min-h-[var(--control-h-sm)] min-w-0 items-center gap-2 group-data-[density=compact]/properties:min-h-6 group-data-[density=compact]/properties:items-start",
+					stacked && "col-span-full items-start pb-2",
+				)}
+			>
 				{icon ? (
 					<span aria-hidden="true" className="flex size-4 flex-none items-center justify-center text-[var(--muted-foreground)]">
 						{icon}
@@ -79,6 +103,7 @@ export function Property({ label, icon, empty = false, mono = false, action, chi
 					data-slot="property-value"
 					className={cn(
 						"min-w-0",
+						stacked && "w-full",
 						mono ? "break-all font-mono" : "break-words",
 						empty ? "text-[var(--muted-foreground)]" : "text-[var(--foreground)]",
 					)}

package/src/react/components/SwatchPicker.spec.tsx

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { type SwatchOption, SwatchPicker } from './SwatchPicker.js';
+
+afterEach(cleanup);
+
+const OPTIONS: SwatchOption[] = [
+  { value: '', none: true, label: 'No colour' },
+  { value: '1', color: 'var(--chart-1)', label: 'Red' },
+  { value: '2', color: 'var(--chart-2)', label: 'Green' },
+  { value: '3', color: 'var(--chart-3)', label: 'Blue' },
+];
+
+/** Radix's roving focus moves on a timeout, so an arrow key lands a tick later. */
+const tick = () => act(() => new Promise<void>((resolve) => setTimeout(resolve, 0)));
+
+const radios = (getAllByRole: (role: string) => HTMLElement[]) => getAllByRole('radio');
+
+describe('SwatchPicker', () => {
+  test('one named radiogroup, one radio per swatch, named by its label — and no native `title` (DESIGN.md §4)', () => {
+    const { getByRole, getAllByRole, container } = render(
+      <SwatchPicker aria-label='Card colour' options={OPTIONS} value='2' onChange={() => {}} />,
+    );
+    expect(getByRole('radiogroup').getAttribute('aria-label')).toBe('Card colour');
+    expect(radios(getAllByRole).map((r) => r.getAttribute('aria-label'))).toEqual(['No colour', 'Red', 'Green', 'Blue']);
+    expect(radios(getAllByRole).map((r) => r.getAttribute('aria-checked'))).toEqual(['false', 'false', 'true', 'false']);
+    expect(container.querySelector('[title]')).toBeNull();
+  });
+
+  test('a `none` option is the ground struck through, marked `data-swatch="none"`, with no check glyph', () => {
+    const { getAllByRole } = render(<SwatchPicker options={OPTIONS} value='' onChange={() => {}} />);
+    const none = radios(getAllByRole)[0] as HTMLElement;
+    expect(none.getAttribute('data-swatch')).toBe('none');
+    expect(none.getAttribute('aria-checked')).toBe('true');
+    expect(none.getAttribute('style')).toContain('var(--card)');
+    expect(none.querySelector('svg')).toBeNull();
+  });
+
+  test('`columns` lays the swatches out as a grid that many across; `tile` squares them', () => {
+    const { getByRole, getAllByRole } = render(
+      <SwatchPicker options={OPTIONS} value={undefined} onChange={() => {}} columns={2} shape='tile' />,
+    );
+    const group = getByRole('radiogroup');
+    expect(group.className).toContain('grid');
+    expect(group.getAttribute('style')).toContain('repeat(2, max-content)');
+    expect(radios(getAllByRole)[1]?.className).toContain('rounded-sm');
+  });
+
+  test('automatic (default): picking an unchecked swatch reports it; the checked one does not report again', () => {
+    const picked: string[] = [];
+    const { getAllByRole } = render(<SwatchPicker options={OPTIONS} value='2' onChange={(v) => picked.push(v)} />);
+    fireEvent.click(radios(getAllByRole)[3] as HTMLElement);
+    fireEvent.click(radios(getAllByRole)[2] as HTMLElement);
+    expect(picked).toEqual(['3']);
+  });
+
+  test('🔴 manual: an arrow key moves focus WITHOUT picking (a format menu would apply and close on it)', async () => {
+    const picked: string[] = [];
+    const { getAllByRole } = render(
+      <SwatchPicker options={OPTIONS} value='1' activationMode='manual' onChange={(v) => picked.push(v)} />,
+    );
+    const red = radios(getAllByRole)[1] as HTMLElement;
+    act(() => red.focus());
+    fireEvent.keyDown(red, { key: 'ArrowRight' });
+    await tick();
+    expect(document.activeElement?.getAttribute('aria-label')).toBe('Green');
+    fireEvent.keyUp(document.activeElement as HTMLElement, { key: 'ArrowRight' });
+    expect(picked).toEqual([]);
+  });
+
+  test('automatic: the same arrow key DOES pick — the radio pattern, which manual opts out of', async () => {
+    const picked: string[] = [];
+    const { getAllByRole } = render(<SwatchPicker options={OPTIONS} value='1' onChange={(v) => picked.push(v)} />);
+    const red = radios(getAllByRole)[1] as HTMLElement;
+    act(() => red.focus());
+    fireEvent.keyDown(red, { key: 'ArrowRight' });
+    await tick();
+    fireEvent.keyUp(document.activeElement as HTMLElement, { key: 'ArrowRight' });
+    expect(picked).toEqual(['2']);
+  });
+
+  test('🔴 manual: Enter picks the focused swatch, and a click on the CHECKED swatch reports it again', () => {
+    const picked: string[] = [];
+    const { getAllByRole } = render(
+      <SwatchPicker options={OPTIONS} value='1' activationMode='manual' onChange={(v) => picked.push(v)} />,
+    );
+    fireEvent.keyDown(radios(getAllByRole)[3] as HTMLElement, { key: 'Enter' });
+    fireEvent.click(radios(getAllByRole)[1] as HTMLElement);
+    fireEvent.click(radios(getAllByRole)[0] as HTMLElement);
+    expect(picked).toEqual(['3', '1', '']);
+  });
+});

package/src/react/components/SwatchPicker.tsx

@@ -1,80 +1,166 @@
 import * as RadioGroup from '@radix-ui/react-radio-group';
 import { Check } from 'lucide-react';
+import { type CSSProperties, useRef } from 'react';
 import { cn } from '../lib/cn.js';
 import { TAP_TARGET_SQUARE } from '../lib/tapTarget.js';
+import { Tooltip } from './Tooltip.js';
 
-export interface SwatchOption<T extends string = string> {
+interface SwatchOptionBase<T extends string> {
   /** Stable value reported by `onChange` (an id, an index-as-string, a hex…). */
   value: T;
-  /** Any CSS color — hex, `var(--chart-1)`, `oklch(…)`. Fills the swatch. */
-  color: string;
-  /** Accessible name; defaults to the value. */
+  /** Accessible name, and the tooltip; defaults to the value. */
   label?: string;
   disabled?: boolean;
 }
 
+/** One swatch: a colour — or, with `none`, the "no colour" choice, drawn as the ground struck through. */
+export type SwatchOption<T extends string = string> = SwatchOptionBase<T> &
+  (
+    | {
+        /** Any CSS color — hex, `var(--chart-1)`, `oklch(…)`. Fills the swatch. */
+        color: string;
+        none?: undefined;
+      }
+    | {
+        /** The "no colour" swatch (a fill cleared, an accent removed): the card ground with a slash. */
+        none: true;
+        color?: undefined;
+      }
+  );
+
 export interface SwatchPickerProps<T extends string = string> {
   options: SwatchOption<T>[];
   value: T | undefined;
   onChange: (value: T) => void;
   /** Swatch diameter: `sm` 1.5rem, `md` (default) 1.75rem, `lg` 2.25rem. */
   size?: 'sm' | 'md' | 'lg';
+  /** `dot` (default) is round; `tile` is a rounded square — a palette's chip (Excel's colour grid). */
+  shape?: 'dot' | 'tile';
+  /** Lay the swatches out as a grid this many across (a 2-D palette) instead of one wrapping row. */
+  columns?: number;
+  /**
+   * `automatic` (default): the arrow keys move the choice, as a radio group's do — right for a
+   * value being SET (an accent, a series colour). `manual`: the arrows only move focus, and
+   * Enter, Space or a click picks — including the swatch already checked, which reports again.
+   * Right for a palette that APPLIES a colour (a format menu, a selection's toolbar), where every
+   * arrow press would otherwise be an edit and the first one would close the menu. The words are
+   * Radix Tabs' `activationMode`.
+   */
+  activationMode?: 'automatic' | 'manual';
   /** Accessible name for the group (default "Color"). */
   'aria-label'?: string;
   className?: string;
 }
 
 const SIZE = { sm: 'size-6', md: 'size-7', lg: 'size-9' } as const;
+const SHAPE = { dot: 'rounded-full', tile: 'rounded-sm' } as const;
+/** "No colour": the card ground, struck through corner to corner in the destructive hue. */
+const NONE_FILL =
+  'linear-gradient(135deg, transparent calc(50% - 1px), var(--destructive) calc(50% - 1px) calc(50% + 1px), transparent calc(50% + 1px)), var(--card)';
 
 /**
  * A discrete color-swatch radio group — pick ONE color from a fixed palette
- * (chart series colors, namespace hues, label tints). Radix `RadioGroup`
- * supplies the radiogroup ARIA pattern, roving tabindex, and arrow-key
- * navigation; the check glyph marks the selection.
+ * (chart series colors, namespace hues, label tints, a format menu's grid). Radix
+ * `RadioGroup` supplies the radiogroup ARIA pattern, roving tabindex, and arrow-key
+ * navigation; the check glyph and a ring mark the selection, and each swatch names
+ * itself in the belt's `Tooltip` — on focus as well as hover, which a native `title`
+ * never does (DESIGN.md §4, `no-raw-title-attr`).
  *
  * This is the shared primitive for every "row of color dots" UI. For the nav
  * accent picker (presets + custom hex + reset) see `ColorSwatchGrid`, which
- * composes this with a native color input.
+ * composes this with a native color input; for an accent row with an any-colour
+ * well, `ColorSwatches`.
+ *
+ * The checked ring keys off `aria-checked`, not Radix's `data-state`: the tooltip's
+ * own trigger writes `data-state` (open/closed) onto the same element.
  */
 export function SwatchPicker<T extends string = string>({
   options,
   value,
   onChange,
   size = 'md',
+  shape = 'dot',
+  columns,
+  activationMode = 'automatic',
   'aria-label': ariaLabel = 'Color',
   className,
 }: SwatchPickerProps<T>) {
+  const manual = activationMode === 'manual';
+  // Radix checks the radio an arrow key lands on by calling `click()` from inside its focus
+  // handler. In manual mode that one click is vetoed: our `onFocus` runs first and raises this
+  // flag until the focus event's dispatch is over, and `onClick` refuses Radix's check while it
+  // is up. (Preventing the FOCUS would skip it too, but the tooltip reads that as "do not open",
+  // and the arrow keys are exactly when a swatch's name is wanted.)
+  const focusing = useRef(false);
+  const grid: CSSProperties | undefined = columns ? { gridTemplateColumns: `repeat(${columns}, max-content)` } : undefined;
   return (
     <RadioGroup.Root
       aria-label={ariaLabel}
       value={value ?? ''}
       onValueChange={(v) => onChange(v as T)}
-      className={cn('flex flex-wrap items-center gap-1.5', className)}
+      data-slot='swatch-picker'
+      style={grid}
+      className={cn(columns ? 'grid' : 'flex flex-wrap', 'items-center gap-1.5', className)}
     >
-      {options.map((opt) => (
-        <RadioGroup.Item
-          key={opt.value}
-          value={opt.value}
-          disabled={opt.disabled}
-          aria-label={opt.label ?? opt.value}
-          title={opt.label ?? opt.value}
-          style={{ backgroundColor: opt.color }}
-          className={cn(
-            'inline-flex items-center justify-center rounded-full border border-border/40 transition-transform',
-            SIZE[size],
-            // A finger needs 44px (DESIGN.md §5): the swatch itself grows on a coarse pointer, since
-            // the colour IS the button. A 28px one failed e2e/touch-targets (forge task 2514).
-            TAP_TARGET_SQUARE,
-            'hover:scale-110 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
-            'data-[state=checked]:ring-2 data-[state=checked]:ring-foreground data-[state=checked]:ring-offset-1',
-            'disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:scale-100',
-          )}
-        >
-          <RadioGroup.Indicator asChild>
-            <Check className='size-3.5 text-white mix-blend-difference' aria-hidden />
-          </RadioGroup.Indicator>
-        </RadioGroup.Item>
-      ))}
+      {options.map((opt) => {
+        const name = opt.label ?? opt.value;
+        return (
+          <Tooltip key={opt.value} content={name}>
+            <RadioGroup.Item
+              value={opt.value}
+              disabled={opt.disabled}
+              aria-label={name}
+              data-swatch={opt.none ? 'none' : opt.value}
+              style={{ background: opt.none ? NONE_FILL : opt.color }}
+              onFocus={
+                manual
+                  ? () => {
+                      focusing.current = true;
+                      queueMicrotask(() => {
+                        focusing.current = false;
+                      });
+                    }
+                  : undefined
+              }
+              onClick={
+                manual
+                  ? (event) => {
+                      if (focusing.current) event.preventDefault();
+                      else if (opt.value === value) onChange(opt.value);
+                    }
+                  : undefined
+              }
+              onKeyDown={
+                manual
+                  ? (event) => {
+                      if (event.key !== 'Enter') return;
+                      event.preventDefault();
+                      onChange(opt.value);
+                    }
+                  : undefined
+              }
+              className={cn(
+                'inline-flex items-center justify-center border border-border/40 transition-transform',
+                SIZE[size],
+                SHAPE[shape],
+                // A finger needs 44px (DESIGN.md §5): the swatch itself grows on a coarse pointer, since
+                // the colour IS the button. A 28px one failed e2e/touch-targets (forge task 2514).
+                TAP_TARGET_SQUARE,
+                'hover:scale-110 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+                'aria-checked:ring-2 aria-checked:ring-foreground aria-checked:ring-offset-1',
+                'disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:scale-100',
+              )}
+            >
+              {/* The slash IS the "no colour" mark; a check over it would read as a second glyph. */}
+              {opt.none ? null : (
+                <RadioGroup.Indicator asChild>
+                  <Check className='size-3.5 text-white mix-blend-difference' aria-hidden />
+                </RadioGroup.Indicator>
+              )}
+            </RadioGroup.Item>
+          </Tooltip>
+        );
+      })}
     </RadioGroup.Root>
   );
 }