@toclocoinc/lattice-grid 1.100.0 → 1.100.1

package/CHANGELOG.md

@@ -9,6 +9,22 @@ and what it means for a grid already in production.
 
 ## [Unreleased]
 
+## [1.100.1] - 2026-10-13
+
+### Added
+
+- **A `color` form control: a swatch field with a preset palette, a custom saturation/lightness picker and typed hex** (BACKLOG-0002252).
+  - The field shows a swatch and the current value as hex text; clicking the swatch or the trailing icon, pressing Enter on the field, or Alt+Down opens a popover under the field (flipped above when there is no room), closed by outside click, Escape or a selection, with focus returning to the field.
+  - The popover's palette view shows rows of preset swatches — ten hues in five shades by default, `palette: string[][]` to replace them, `grayShades: false` to drop the default grey row — plus a row of `customColors`, extended (newest first, deduplicated, at most ten) by every colour picked in the picker view; each extension fires `customColorsChange`. A "Custom colour" button switches to the picker view: a saturation/lightness plane, a hue slider, hex and R/G/B inputs and a preview, committing on Select or Enter and discarding on Escape or Back. `mode: 'palette' | 'picker'` picks the opening view and `pickerOnly: true` removes the palette view.
+  - The value is a lowercase `#rrggbb` string or `null`. `setValue` normalises `#rgb`, `#rrggbb` and `rgb(r, g, b)`; anything else is refused with a warning and the value is unchanged. `editable` (default true) lets the text part be typed into — a valid hex commits on Enter or blur, an invalid one keeps the old value with a catalogue message — and `editable: false` makes it read-only. `clearable: true` adds a control that sets `null`.
+  - The richtext control's text-colour popover now draws through the same shared palette and swatch grid, so the two popovers match.
+
+### Fixed
+
+- Form combo: a combo that loads its options a page at a time and opens with a value already selected now draws `selectedTemplate` and its chips with the option `resolveLabels` returned, so the template sees `{ value, label, … }` for the resolved option rather than the raw value. (BACKLOG-0002258)
+
+- Form items: an item's own `props` object now reaches the control, so a custom control registered with `registerControl` receives its settings in `create(el, item, api)`; unrecognised top-level keys still join the same bag. `FormItemConfig.props` is typed. (BACKLOG-0002259)
+
 ## [1.100.0] - 2026-10-12
 
 ### Added

package/README.md

@@ -7,7 +7,7 @@ tiles and map views, all reading the same rows, filters and theme. Vanilla
 JavaScript, no runtime dependencies, no build step; adapters for React, Vue,
 Svelte, Web Components and htmx, Angular compiled inside the package.
 
-Version 1.100.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.100.1 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/angular/fesm2022/toclocoinc-lattice-grid-angular.mjs

@@ -862,7 +862,7 @@ const VIEWER_EVENTS$1 = Object.freeze({
     ]),
 
     form: Object.freeze([
-        'beforeChange', 'change', 'input', 'click', 'focus', 'blur', 'validated', 'complete',
+        'beforeChange', 'change', 'input', 'click', 'focus', 'blur', 'validated', 'complete', 'customColorsChange',
     ]),
 });
 
@@ -3459,6 +3459,8 @@ class LatticeFormComponent extends LatticeViewerBase {
         this.validated = new EventEmitter();
 
         this.complete = new EventEmitter();
+
+        this.customColorsChange = new EventEmitter();
     }
 
     mount(element, config) {
@@ -3466,7 +3468,7 @@ class LatticeFormComponent extends LatticeViewerBase {
         return createForm(element, config);
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.7", ngImport: i0, type: LatticeFormComponent, deps: null, target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.1.7", type: LatticeFormComponent, isStandalone: true, selector: "lattice-form", inputs: { config: "config" }, outputs: { beforeChange: "beforeChange", change: "change", input: "input", click: "click", focus: "focus", blur: "blur", validated: "validated", complete: "complete" }, usesInheritance: true, ngImport: i0, template: '', isInline: true, styles: [":host{display:block}\n"] }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.1.7", type: LatticeFormComponent, isStandalone: true, selector: "lattice-form", inputs: { config: "config" }, outputs: { beforeChange: "beforeChange", change: "change", input: "input", click: "click", focus: "focus", blur: "blur", validated: "validated", complete: "complete", customColorsChange: "customColorsChange" }, usesInheritance: true, ngImport: i0, template: '', isInline: true, styles: [":host{display:block}\n"] }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.7", ngImport: i0, type: LatticeFormComponent, decorators: [{
             type: Component,
@@ -3489,6 +3491,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.7", ngImpor
                 type: Output
             }], complete: [{
                 type: Output
+            }], customColorsChange: [{
+                type: Output
             }] } });
 
 class LatticeDesignerComponent {

package/angular/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.100.0",
+  "version": "1.100.1",
   "type": "module",
   "sideEffects": false,
   "module": "./fesm2022/toclocoinc-lattice-grid-angular.mjs",

package/angular/types/toclocoinc-lattice-grid-angular.d.ts

@@ -1580,6 +1580,8 @@ declare class LatticeFormComponent extends LatticeViewerBase<Form> {
     readonly validated: EventEmitter<any>;
     /** The viewer's `complete` event: every box of an `otp` item is now filled. */
     readonly complete: EventEmitter<any>;
+    /** The viewer's `customColorsChange` event: a `color` item's remembered custom colours changed. */
+    readonly customColorsChange: EventEmitter<any>;
     /**
      * Build the form. `createForm(el, config)` takes its host element directly.
      * @param element the host element
@@ -1588,7 +1590,7 @@ declare class LatticeFormComponent extends LatticeViewerBase<Form> {
      */
     protected mount(element: HTMLElement, config: Props): Form;
     static ɵfac: i0.ɵɵFactoryDeclaration<LatticeFormComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<LatticeFormComponent, "lattice-form", never, { "config": { "alias": "config"; "required": false; }; }, { "beforeChange": "beforeChange"; "change": "change"; "input": "input"; "click": "click"; "focus": "focus"; "blur": "blur"; "validated": "validated"; "complete": "complete"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LatticeFormComponent, "lattice-form", never, { "config": { "alias": "config"; "required": false; }; }, { "beforeChange": "beforeChange"; "change": "change"; "input": "input"; "click": "click"; "focus": "focus"; "blur": "blur"; "validated": "validated"; "complete": "complete"; "customColorsChange": "customColorsChange"; }, never, never, true, never>;
 }
 
 declare class LatticeDesignerComponent implements OnChanges, OnDestroy {

package/docs/API.html

@@ -382,7 +382,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">API reference · v1.100.0</p>
+    <p class="rail__sub">API reference · v1.100.1</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start</span>
@@ -583,7 +583,7 @@
     </header>
 
     <p class="chips">
-      <span class="chip">Version 1.100.0</span>
+      <span class="chip">Version 1.100.1</span>
       <span class="chip">Zero dependencies</span>
       <span class="chip"><a href="api-detail.html">Developer guide &rarr;</a></span>
     </p>
@@ -3505,7 +3505,7 @@ grid.destroy();
       <table>
         <thead><tr><th>Member</th><th>Returns</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.100.0'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
+          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.100.1'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
           <tr><td class="sig">get(key)</td><td class="type">unknown</td><td class="desc">Read any configuration key.</td></tr>
           <tr><td class="sig">set(key, value)</td><td class="type">void</td><td class="desc">Write one key. Every key is live; nothing needs a rebuild.</td></tr>
           <tr><td class="sig">setAll(values)</td><td class="type">void</td><td class="desc">Write several in one pass. Emits one <code>config:changed</code> for the batch, not one per key.</td></tr>
@@ -16681,7 +16681,7 @@ group.destroy();
     <code>visibleWhen</code>/<code>readOnlyWhen</code>/<code>requiredWhen</code> rules re-evaluate as values commit; and a
     three-step wizard's <code>next()</code>/<code>back()</code>/<code>goToStep()</code> gate each forward move on the step's
     validation &mdash; with the real Chrome assertions in <code>test/form-browser.test.js</code>.</p>
-    <pre data-run="js" data-expect="false|true|1|3|false|true|true|true|true|true" data-covers="export:registerControl config:FormConfig.steps config:FormConfig.stepOrientation config:FormItemConfig.visibleWhen config:FormItemConfig.readOnlyWhen config:FormItemConfig.requiredWhen method:form.next method:form.back method:form.goToStep"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
+    <pre data-run="js" data-expect="false|true|1|3|false|true|true|true|true|true" data-covers="export:registerControl config:FormItemConfig.props config:FormConfig.steps config:FormConfig.stepOrientation config:FormItemConfig.visibleWhen config:FormItemConfig.readOnlyWhen config:FormItemConfig.requiredWhen method:form.next method:form.back method:form.goToStep"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
 <span class="kw">const</span> { registerControl, createForm } = <span class="kw">await</span> import('../packages/modules/form/index.js');
 
 <span class="cmt">// A custom control type is a first-class item: it round-trips through the form API.</span>
@@ -16689,6 +16689,7 @@ registerControl('star', {
   create(el, item, api) {
     <span class="kw">const</span> input = el.ownerDocument.createElement('input');
     input.className = 'star-input';
+    input.setAttribute('data-max', String(item.props.max)); // the item's own `props` bag carries the control's settings
     el.appendChild(input);
   },
   getValue(el) { <span class="kw">return</span> el.querySelector('.star-input').value; },
@@ -16704,7 +16705,7 @@ registerControl('star', {
       { type: 'input', name: 'code', label: 'Code' },
     ] },
     { id: 'two', label: 'Two', rows: [
-      { type: 'star', name: 'rating', label: 'Rating', value: '3' },
+      { type: 'star', name: 'rating', label: 'Rating', value: '3', props: { max: 5 } },
       { type: 'input', name: 'note', label: 'Note', visibleWhen: { name: 'rating', equals: '5' } },
       { type: 'input', name: 'review', label: 'Review', readOnlyWhen: { name: 'rating', in: ['4', '5'] } },
     ] },
@@ -17109,6 +17110,56 @@ form.setValue({ tags: [<span class="str">'c'</span>, <span class="str">'a'</span
 <span class="kw">const</span> requiredFails = form.validate();                          <span class="cmt">// false — allowEmpty + required, nothing picked</span>
 
 <span class="kw">return</span> [started, clicked, ordered, capped, requiredFails].join('|');</code></pre>
+    <h3 id="form-color-example">A colour swatch field: palette, custom colours, clearable and read-only, executed</h3>
+    <p class="section-note">A <code>color</code> item's swatch or trailing icon opens a popover under the field: the
+    palette view's shared swatch grid (ten hues in five shades, a grey row, and a <code>customColors</code> row),
+    <code>grayShades: false</code> dropping the grey row, <code>clearable</code> adding a control that sets
+    <code>null</code>, <code>editable: false</code> making the text part read-only, and <code>pickerOnly</code> with
+    <code>mode: 'picker'</code> opening straight on the saturation/lightness picker with no palette view &mdash; with
+    the keyboard model, the computed swatch colours and the light/dark popover surface asserted in
+    <code>test/form-color-browser.test.js</code>.</p>
+    <pre data-run="js" data-expect="56|#cf7030|true|#ff0000||50|true|true|false" data-covers="export:createForm method:form.getItem method:form.getValue config:FormItemConfig.value config:FormItemConfig.clearable config:FormItemConfig.customColors config:FormItemConfig.editable config:FormItemConfig.grayShades config:FormItemConfig.pickerOnly config:FormItemConfig.mode"><code>const { createTestDom, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
+const { createForm } = await import('../packages/modules/form/index.js');
+
+const { root } = createTestDom();
+const form = createForm(root, { rows: [
+  { type: 'color', name: 'brand', label: 'Brand', value: '#1a2b3c', clearable: true, customColors: ['#112233'] },
+  { type: 'color', name: 'bg', label: 'Background', grayShades: false },
+  { type: 'color', name: 'locked', label: 'Locked', value: '#ff0000', editable: false },
+  { type: 'color', name: 'po', label: 'Picker only', pickerOnly: true, mode: 'picker' },
+] });
+
+// Palette view: the shared swatch grid (ten hues x five shades, the grey row, one custom colour).
+const brandEl = form.getItem('brand').el.querySelector('.lat-form__color');
+brandEl.querySelector('.lat-form__color-toggle').dispatchEvent(new TestEvent('click', { bubbles: true }));
+const popover = brandEl.querySelector('.lat-form__color-popover');
+const swatchCount = popover.querySelectorAll('.lat-form__swatch').length;   // 56 = 50 + grey row (5) + custom (1)
+popover.querySelectorAll('.lat-form__swatch')[7].dispatchEvent(new TestEvent('click', { bubbles: true }));
+const picked = form.getValue().brand;                                      // the clicked swatch's hex
+const closed = popover.hidden;                                             // true — a selection closes the popover
+
+// setValue normalises rgb(); clear sets null.
+form.getItem('brand').setValue('rgb(255, 0, 0)');
+const normalized = form.getValue().brand;                                  // '#ff0000'
+brandEl.querySelector('.lat-form__color-clear').dispatchEvent(new TestEvent('click', { bubbles: true }));
+const cleared = form.getValue().brand;                                     // null
+
+// grayShades: false drops the grey row.
+const bgEl = form.getItem('bg').el.querySelector('.lat-form__color');
+bgEl.querySelector('.lat-form__color-toggle').dispatchEvent(new TestEvent('click', { bubbles: true }));
+const noGraySwatchCount = bgEl.querySelector('.lat-form__color-popover').querySelectorAll('.lat-form__swatch').length;  // 50
+
+// editable: false leaves the text part read-only.
+const lockedReadOnly = form.getItem('locked').el.querySelector('.lat-form__color-input').readOnly;  // true
+
+// pickerOnly + mode: 'picker' opens straight on the picker, with no palette and no Back button.
+const poEl = form.getItem('po').el.querySelector('.lat-form__color');
+poEl.querySelector('.lat-form__color-toggle').dispatchEvent(new TestEvent('click', { bubbles: true }));
+const poPopover = poEl.querySelector('.lat-form__color-popover');
+const poHasPicker = !!poPopover.querySelector('.lat-form__color-picker');   // true
+const poHasBack = !!poPopover.querySelector('.lat-form__color-back');      // false
+
+return [swatchCount, picked, closed, normalized, cleared, noGraySwatchCount, lockedReadOnly, poHasPicker, poHasBack].join('|');</code></pre>
     <h3 id="form-password-otp-example">Password reveal and one-time-code entry, executed</h3>
     <p class="section-note">A <code>password</code> input's reveal button renders inside the field with its catalogue name and
     <code>aria-pressed</code>, and <code>reveal: false</code> drops it; an <code>otp</code> item renders <code>length</code>
@@ -31882,11 +31933,12 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
       </table>
     </div>
     <h4 id="type-FormItemConfig">FormItemConfig</h4>
-    <p class="section-note">One form item: a control (`input`, `number`, `textarea`, `checkbox`, `button`, `combo`, `select`, `radiogroup`, `checkboxgroup`, `toggle`, `datepicker`, `file`, `richtext`, `rating`, `stage`, `chips`) or the read-only `text` display, with the per-item options.</p>
+    <p class="section-note">One form item: a control (`input`, `number`, `textarea`, `checkbox`, `button`, `combo`, `select`, `radiogroup`, `checkboxgroup`, `toggle`, `datepicker`, `file`, `richtext`, `rating`, `stage`, `chips`, `otp`, `color`) or the read-only `text` display, with the per-item options.</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
+          <tr><td class="name">props</td><td class="type">Record&lt;string, unknown&gt;</td><td class="desc">A control's own settings bag. A custom control registered with `registerControl` reads its settings from `item.props` in `create()`; any top-level key the form does not recognise joins the same bag (BACKLOG-0002259). <small>(optional)</small></td></tr>
           <tr><td class="name">type</td><td class="type">string</td><td class="desc">The control type — a built-in or a type registered with `registerControl`. Defaults to `input`. <small>(optional)</small></td></tr>
           <tr><td class="name">name</td><td class="type">string</td><td class="desc">The item's name, for `getItem(name)` and `getValue()`/`setValue()`. <small>(optional)</small></td></tr>
           <tr><td class="name">label</td><td class="type">string</td><td class="desc">The label text, associated to the control for screen readers. <small>(optional)</small></td></tr>
@@ -31912,7 +31964,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">subtype</td><td class="type"><a href="#type-FormInputSubtype">FormInputSubtype</a> <small class="literals">'text' | 'email' | 'password' | 'url'</small></td><td class="desc">The native input subtype for an `input` item. <small>(optional)</small></td></tr>
           <tr><td class="name">reveal</td><td class="type">boolean</td><td class="desc">Show the reveal button inside a `password` input (default true); `false` turns it off. <small>(optional)</small></td></tr>
           <tr><td class="name">length</td><td class="type">number</td><td class="desc">The box count of an `otp` item (default 6). <small>(optional)</small></td></tr>
-          <tr><td class="name">mode</td><td class="type">'numeric' | 'alphanumeric' | <a href="#type-FormPickerMode">FormPickerMode</a></td><td class="desc">The `otp` characters — `numeric` (default) or `alphanumeric` — or the `datepicker` mode: `date`, `date-time` or `time` (BACKLOG-0002142). <small>(optional)</small></td></tr>
+          <tr><td class="name">mode</td><td class="type">'numeric' | 'alphanumeric' | <a href="#type-FormPickerMode">FormPickerMode</a> | <a href="#type-FormColorMode">FormColorMode</a></td><td class="desc">The `otp` characters — `numeric` (default) or `alphanumeric` — the `datepicker` mode: `date`, `date-time` or `time` (BACKLOG-0002142) — or the `color` item's opening popover view (BACKLOG-0002252). <small>(optional)</small></td></tr>
           <tr><td class="name">mask</td><td class="type">boolean</td><td class="desc">Hide each `otp` box's glyph with the password disc. <small>(optional)</small></td></tr>
           <tr><td class="name">step</td><td class="type">number</td><td class="desc">The number step, for a `number` item. <small>(optional)</small></td></tr>
           <tr><td class="name">format</td><td class="type"><a href="#type-NumberFormat">NumberFormat</a> | string</td><td class="desc">The number format a `number` item displays when blurred, the same shape a grid number column takes — a `NumberFormat` spec (which may name `pattern`) or a bare pattern string like `'#,##0.00'` (BACKLOG-0002176, BACKLOG-0002181). The value stays a number; only the display is formatted. <small>(optional)</small></td></tr>
@@ -31964,7 +32016,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">sanitizePaste</td><td class="type">boolean</td><td class="desc">Sanitise pasted HTML in a `richtext` item (default true). <small>(optional)</small></td></tr>
           <tr><td class="name">allowHalf</td><td class="type">boolean</td><td class="desc">Allow half steps for a `rating` item. <small>(optional)</small></td></tr>
           <tr><td class="name">allowClear</td><td class="type">boolean</td><td class="desc">Allow a second click to clear a `rating` item back to zero. <small>(optional)</small></td></tr>
-          <tr><td class="name">icon</td><td class="type">string | Element | false</td><td class="desc">The icon of a `button` — a name from the grid's icon set, an image URL or data: URI, or an element — the glyph name of a `rating` item (`star` or `heart`), or the drop-area icon of a `file` item — a glyph name from the file module's sprite set, an SVG markup string, an element, or `false` for none (BACKLOG-0002204). <small>(optional)</small></td></tr>
+          <tr><td class="name">icon</td><td class="type">string | Element | false</td><td class="desc">The icon of a `button` — a name from the grid's icon set, an image URL or data: URI, or an element — the glyph name of a `rating` item (`star` or `heart`), the drop-area icon of a `file` item — a glyph name from the file module's sprite set, an SVG markup string, an element, or `false` for none (BACKLOG-0002204) — or the glyph name a `color` item's trailing toggle draws instead of its default chevron (BACKLOG-0002252). <small>(optional)</small></td></tr>
           <tr><td class="name">icons</td><td class="type">{ filled?: string; empty?: string }</td><td class="desc">The filled and empty glyph names for a `rating` item. <small>(optional)</small></td></tr>
           <tr><td class="name">labels</td><td class="type">string[]</td><td class="desc">One label per rating icon, for the `title` and the announced value. <small>(optional)</small></td></tr>
           <tr><td class="name">showValue</td><td class="type">boolean</td><td class="desc">Show the numeric value beside a `rating` item. <small>(optional)</small></td></tr>
@@ -31988,6 +32040,12 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">showIcons</td><td class="type">boolean</td><td class="desc">Whether a `stage` item shows its check glyphs (default true). <small>(optional)</small></td></tr>
           <tr><td class="name">allowEmpty</td><td class="type">boolean</td><td class="desc">Allow a single-mode `chips` item to be left with nothing selected. <small>(optional)</small></td></tr>
           <tr><td class="name">wrap</td><td class="type">boolean</td><td class="desc">Wrap a `chips` item's pills onto several lines (default), or keep them on one scrolling row when false. <small>(optional)</small></td></tr>
+          <tr><td class="name">palette</td><td class="type">string[][]</td><td class="desc">The rows of preset swatches a `color` item's palette view shows, replacing the shared default (ten hues in five shades) (BACKLOG-0002252). <small>(optional)</small></td></tr>
+          <tr><td class="name">grayShades</td><td class="type">boolean</td><td class="desc">Show a `color` item's grey row under its palette (default true); `false` drops it (BACKLOG-0002252). <small>(optional)</small></td></tr>
+          <tr><td class="name">customColors</td><td class="type">string[]</td><td class="desc">A `color` item's custom-colours row to start with — extended, newest first and deduplicated to at most ten, by every colour picked in the picker view (BACKLOG-0002252). <small>(optional)</small></td></tr>
+          <tr><td class="name">pickerOnly</td><td class="type">boolean</td><td class="desc">Remove a `color` item's palette view, leaving only the picker (BACKLOG-0002252). <small>(optional)</small></td></tr>
+          <tr><td class="name">editable</td><td class="type">boolean</td><td class="desc">Let a `color` item's text part be typed into (default true); `false` makes it read-only, so only the popover sets the value (BACKLOG-0002252). <small>(optional)</small></td></tr>
+          <tr><td class="name">clearable</td><td class="type">boolean</td><td class="desc">Show a `color` item's clear control, setting the value to `null` (BACKLOG-0002252). <small>(optional)</small></td></tr>
           <tr><td class="name">[key: string]</td><td class="type">unknown</td><td class="desc">Extra per-control options, kept for later controls.</td></tr>
         </tbody>
       </table>
@@ -32159,6 +32217,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">blur</td><td class="type">FormFocusEvent</td><td class="desc">The item that lost focus.</td></tr>
           <tr><td class="name">validated</td><td class="type"><a href="#type-FormValidatedEvent">FormValidatedEvent</a></td><td class="desc">A validation run, item or whole form, with its failures.</td></tr>
           <tr><td class="name">complete</td><td class="type">FormCompleteEvent</td><td class="desc">Every box of an `otp` item is now filled.</td></tr>
+          <tr><td class="name">customColorsChange</td><td class="type"><a href="#type-FormColorCustomColorsEvent">FormColorCustomColorsEvent</a></td><td class="desc">A `color` item's custom-colours row, extended.</td></tr>
         </tbody>
       </table>
     </div>
@@ -32185,6 +32244,16 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         </tbody>
       </table>
     </div>
+    <h4 id="type-FormColorCustomColorsEvent">FormColorCustomColorsEvent</h4>
+    <p class="section-note">A `customColorsChange` payload: a `color` item's custom-colours row gained a newly picked colour (BACKLOG-0002252).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">colors</td><td class="type">string[]</td><td class="desc">The custom-colours list after the addition — newest first, deduplicated, at most ten entries.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h4 id="type-FormBeforeChangeEvent">FormBeforeChangeEvent</h4>
     <p class="section-note">A `beforeChange` payload. A handler refuses the commit by calling `preventDefault(reason?)` or returning `false` (or a Promise of either).</p>
     <div class="table-wrap">
@@ -32322,6 +32391,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">blur</td><td class="desc">An item's control lost focus.</td><td class="type">FormFocusEvent</td><td class="desc">&mdash;</td></tr>
           <tr><td class="name">validated</td><td class="desc">One or more items were validated, with the failures.</td><td class="type"><a href="#type-FormValidatedEvent">FormValidatedEvent</a></td><td class="desc">no</td></tr>
           <tr><td class="name">complete</td><td class="desc">Every box of an `otp` item is now filled.</td><td class="type">FormCompleteEvent</td><td class="desc">&mdash;</td></tr>
+          <tr><td class="name">customColorsChange</td><td class="desc">A `color` item's custom-colours row gained a newly picked colour (BACKLOG-0002252).</td><td class="type"><a href="#type-FormColorCustomColorsEvent">FormColorCustomColorsEvent</a></td><td class="desc">no</td></tr>
         </tbody>
       </table>
     </div>
@@ -37308,9 +37378,13 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
     <p class="section-note">A button's visual weight: theme-token colours, light and dark.</p>
     <p class="type-def"><code>type FormButtonVariant = 'primary' | 'secondary' | 'tonal' | 'outline' | 'text' | 'danger'</code></p>
     <p class="section-note"><small>Declared in <code>lattice-grid/modules/form</code>.</small></p>
+    <h4 id="type-FormColorMode">FormColorMode</h4>
+    <p class="section-note">The opening view of a `color` item's popover (BACKLOG-0002252): the preset palette (default) or the custom picker.</p>
+    <p class="type-def"><code>type FormColorMode = 'palette' | 'picker'</code></p>
+    <p class="section-note"><small>Declared in <code>lattice-grid/modules/form</code>.</small></p>
     <h4 id="type-FormControlType">FormControlType</h4>
     <p class="section-note">The control types a form item may name.</p>
-    <p class="type-def"><code>type FormControlType = 'input' | 'number' | 'textarea' | 'checkbox' | 'button' | 'text' | 'combo' | 'select' | 'radiogroup' | 'checkboxgroup' | 'toggle' | 'datepicker' | 'file' | 'richtext' | 'rating' | 'stage' | 'chips' | 'otp'</code></p>
+    <p class="type-def"><code>type FormControlType = 'input' | 'number' | 'textarea' | 'checkbox' | 'button' | 'text' | 'combo' | 'select' | 'radiogroup' | 'checkboxgroup' | 'toggle' | 'datepicker' | 'file' | 'richtext' | 'rating' | 'stage' | 'chips' | 'otp' | 'color'</code></p>
     <p class="section-note"><small>Declared in <code>lattice-grid/modules/form</code>.</small></p>
     <h4 id="type-FormDensity">FormDensity</h4>
     <p class="section-note">The density levels a form accepts — the grid's own presets.</p>
@@ -37318,7 +37392,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
     <p class="section-note"><small>Declared in <code>lattice-grid/modules/form</code>.</small></p>
     <h4 id="type-FormEventName">FormEventName</h4>
     <p class="section-note">The events a form raises, on `form.on()` (BACKLOG-0002141). The form's own, not a grid's. `on()` warns once on any other name. The cancellable `beforeChange` runs before a committed edit is stored, on the same contract the grid core uses: call `preventDefault(reason?)` on the payload, or return `false`; a veto reverts the control to its committed value. The past-tense events — `change`, `input`, `click`, `focus` and `blur` — report an edit already made and carry no `preventDefault`.</p>
-    <p class="type-def"><code>type FormEventName = 'beforeChange' | 'change' | 'input' | 'click' | 'focus' | 'blur' | 'validated' | 'complete'</code></p>
+    <p class="type-def"><code>type FormEventName = 'beforeChange' | 'change' | 'input' | 'click' | 'focus' | 'blur' | 'validated' | 'complete' | 'customColorsChange'</code></p>
     <p class="section-note"><small>Declared in <code>lattice-grid/modules/form</code>.</small></p>
     <h4 id="type-FormGroupEventName">FormGroupEventName</h4>
     <p class="section-note">The group's events — the two names its `on()` accepts.</p>
@@ -38106,7 +38180,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
 <!-- END GENERATED TYPE REFERENCE -->
 
     <footer>
-      Lattice Grid 1.100.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+      Lattice Grid 1.100.1 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
       This document describes the behaviour of the shipped library. Where this guide and the code
       disagree, the code wins: please <a href="https://www.latticegrid.dev">tell us</a>.
     </footer>

package/docs/api/adapters.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Adapters API Reference — Lattice Grid 1.100.0</title>
+<title>Adapters API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/ai.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>AI API Reference — Lattice Grid 1.100.0</title>
+<title>AI API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/alarms.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Alarms API Reference — Lattice Grid 1.100.0</title>
+<title>Alarms API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/calendar.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Calendar API Reference — Lattice Grid 1.100.0</title>
+<title>Calendar API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/charts.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Charts API Reference — Lattice Grid 1.100.0</title>
+<title>Charts API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/dashboard.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Dashboard API Reference — Lattice Grid 1.100.0</title>
+<title>Dashboard API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/data-router.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Data router API Reference — Lattice Grid 1.100.0</title>
+<title>Data router API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/deckgl.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>deck.gl API Reference — Lattice Grid 1.100.0</title>
+<title>deck.gl API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/designer.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Designer API Reference — Lattice Grid 1.100.0</title>
+<title>Designer API Reference — Lattice Grid 1.100.1</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an