@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/jexlFilters.d.ts

@@ -4,33 +4,24 @@ import type { Reversible } from '../ui/filterMenuItems.ts';
  * The two-tier feature-filter contract, shared by every display offering a
  * "Filter by..." row. Two tiers because the setting has two authors:
  *
- * - the **`jexlFilters` config slot** on `baseLinearDisplayConfigSchema`, which
- *   an admin declares in a track config. It stores expressions **unprefixed**,
- *   because config-slot values are deferred-evaluation and a stored `jexl:` is
- *   what marks a slot as a callback — so the prefix goes on at read time, in
- *   `configuredJexlFilters`.
- * - the **`jexlFiltersSetting` display property**, which the dialog writes and
- *   which stores them already prefixed (the runtime convention). Set — *even to
- *   an empty list* — it replaces the config tier entirely, which is what makes
- *   "clear the filters an admin declared" expressible.
+ * - the **`filter` config slot**, which an admin declares in a track config:
+ *   `jexlFilterConfigSchemaFields` in display-kit, spread by the canvas base
+ *   display schema, the mark display schema and the shared multi-sample
+ *   variant schema — the three whose models read it.
+ * - the **`filterSetting` display property**, which the dialog writes. Set —
+ *   *even to an empty list* — it replaces the config tier entirely, which is
+ *   what makes "clear the filters an admin declared" expressible.
  *
- * Every display implemented one half of this and a different half each:
- * `LinearBasicDisplay` had both tiers, `LDDisplay` had the slot alone, and the
- * multi-sample variant displays had a property literally named `jexlFilters`
- * that shadowed the inherited slot, so a config filter on one of those tracks
- * was read by nothing and reported no error. Neither of the last two prefixed,
- * so a filter following the slot's own documented convention reached
- * `stringToJexlExpression` unprefixed and threw inside the worker.
+ * Both hold `jexl:` expressions and refuse a bare string.
  */
 export interface JexlFilterSource {
     /**
-     * The dialog's override, `jexl:`-prefixed. `undefined` means "follow the
-     * config slot"; an empty array means "the user cleared them".
+     * The dialog's override. `undefined` means "follow the config slot"; an
+     * empty array means "the user cleared them".
      */
-    jexlFiltersSetting?: readonly string[];
+    filterSetting?: readonly string[];
     /**
-     * The config tier, `jexl:`-prefixed — in practice
-     * `configuredJexlFilters(self)`. A member rather than a read this module does
+     * The config tier — in practice `configuredJexlFilters(self)`. A member rather than a read this module does
      * itself, so the two things that consume this contract off a **duck-typed**
      * model — LD's structural menu builder and its shape test — need no live
      * config node to answer a count with.
@@ -45,17 +36,19 @@ export interface JexlFilterSource {
  * cannot satisfy.
  */
 export interface JexlFilterModel extends JexlFilterSource {
-    setJexlFilters: (filters?: string[]) => void;
+    setFilter: (filters?: string[]) => void;
 }
+/** The `filterSetting` property, for a display model to declare. */
+export declare const FilterSetting: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>>;
 /**
- * What the `jexlFilters` config slot alone declares, `jexl:`-prefixed. The slot
- * stores them unprefixed and every runtime consumer wants them prefixed, so the
- * prefixing happens once, here — this is what a display's `configuredFilters`
- * member is.
+ * A snapshot's v4 `jexlFiltersSetting` as `filterSetting`, for the
+ * `preProcessSnapshot` of the model declaring {@link FilterSetting}.
  */
+export declare function liftRetiredFilterSetting<T>(snap: T): T;
+/** What the `filter` config slot alone declares: a display's `configuredFilters`. */
 export declare function configuredJexlFilters(self: Parameters<typeof getConf>[0]): string[];
 /**
- * The filters actually applied, `jexl:`-prefixed — the single source of truth
+ * The filters actually applied — the single source of truth
  * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
  * filters show up and are editable), and for the narrowing count below.
  */

package/esm/util/jexlFilters.js

@@ -1,25 +1,37 @@
 // own module, not the configuration barrel: that barrel re-exports modules
 // which import this one, and a value import back into it is the cycle shape
 // `openFeatureWidget` documents
+import { types } from '@jbrowse/mobx-state-tree';
 import { getConf } from '../configuration/getConf.js';
 import { ensureJexlPrefix } from './jexlStrings.js';
+import { JexlExpressionString } from './types/mst.js';
+/** The `filterSetting` property, for a display model to declare. */
+export const FilterSetting = types.maybe(types.array(JexlExpressionString));
 /**
- * What the `jexlFilters` config slot alone declares, `jexl:`-prefixed. The slot
- * stores them unprefixed and every runtime consumer wants them prefixed, so the
- * prefixing happens once, here — this is what a display's `configuredFilters`
- * member is.
+ * A snapshot's v4 `jexlFiltersSetting` as `filterSetting`, for the
+ * `preProcessSnapshot` of the model declaring {@link FilterSetting}.
  */
+export function liftRetiredFilterSetting(snap) {
+    if (!snap || typeof snap !== 'object' || !('jexlFiltersSetting' in snap)) {
+        return snap;
+    }
+    const { jexlFiltersSetting, ...rest } = snap;
+    return (Array.isArray(jexlFiltersSetting) && !('filterSetting' in rest)
+        ? { ...rest, filterSetting: jexlFiltersSetting.map(ensureJexlPrefix) }
+        : rest);
+}
+/** What the `filter` config slot alone declares: a display's `configuredFilters`. */
 export function configuredJexlFilters(self) {
-    return getConf(self, 'jexlFilters').map(ensureJexlPrefix);
+    return getConf(self, 'filter');
 }
 /**
- * The filters actually applied, `jexl:`-prefixed — the single source of truth
+ * The filters actually applied — the single source of truth
  * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
  * filters show up and are editable), and for the narrowing count below.
  */
 export function activeJexlFilters(self) {
-    const { jexlFiltersSetting } = self;
-    return jexlFiltersSetting ? [...jexlFiltersSetting] : self.configuredFilters();
+    const { filterSetting } = self;
+    return filterSetting ? [...filterSetting] : self.configuredFilters();
 }
 /**
  * The `Reversible` a display declares for its jexl filters.
@@ -34,16 +46,16 @@ export function activeJexlFilters(self) {
  * restoring the config default, which the group clear already is.
  */
 export function jexlFilterNarrowing(self) {
-    const override = self.jexlFiltersSetting;
+    const override = self.filterSetting;
     const configured = self.configuredFilters();
     return {
         count: override !== undefined &&
             (override.length !== configured.length ||
-                override.some((f, i) => ensureJexlPrefix(f) !== configured[i]))
+                override.some((f, i) => f !== configured[i]))
             ? 1
             : 0,
         clear: () => {
-            self.setJexlFilters(undefined);
+            self.setFilter(undefined);
         },
     };
 }

package/esm/util/jexlStrings.d.ts

@@ -1,6 +1,6 @@
 export interface JexlExpression {
     eval(context?: Record<string, unknown>): unknown;
-    _exprStr?: string;
+    readonly source?: string;
 }
 export interface JexlInstance {
     compile(code: string): JexlExpression;
@@ -11,9 +11,8 @@ export declare function isJexl(str: unknown): str is string;
 /** Add the `jexl:` prefix unless the string already carries it. */
 export declare function ensureJexlPrefix(code: string): string;
 /**
- * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
- * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
- * wrapper.
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
  *
  * @param str - string of code like `jexl:...`
  * @param jexl - the instance whose registered functions the expression may call

package/esm/util/jexlStrings.js

@@ -8,9 +8,8 @@ export function ensureJexlPrefix(code) {
     return isJexl(code) ? code : `${JEXL_PREFIX}${code}`;
 }
 /**
- * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
- * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
- * wrapper.
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
  *
  * @param str - string of code like `jexl:...`
  * @param jexl - the instance whose registered functions the expression may call

package/esm/util/layouts/GranularRectLayout.d.ts

@@ -17,9 +17,16 @@ export default class GranularRectLayout {
         hardRowLimit?: number;
     });
     /**
+     * `lower` gives the rows lying wholly at or past `lower.top` px below the
+     * rect's top a span of their own.
+     *
      * @returns top position for the rect, or Null if laying
      *  out the rect would exceed maxHeight
      */
-    addRect(id: string, left: number, right: number, height: number): number | null;
+    addRect(id: string, left: number, right: number, height: number, lower?: {
+        top: number;
+        left: number;
+        right: number;
+    }): number | null;
     private getOrCreateRow;
 }

package/esm/util/layouts/GranularRectLayout.js

@@ -49,10 +49,13 @@ export default class GranularRectLayout {
         this.maxHeight = Math.ceil(maxHeight / this.pitchY);
     }
     /**
+     * `lower` gives the rows lying wholly at or past `lower.top` px below the
+     * rect's top a span of their own.
+     *
      * @returns top position for the rect, or Null if laying
      *  out the rect would exceed maxHeight
      */
-    addRect(id, left, right, height) {
+    addRect(id, left, right, height, lower) {
         const pitchX = this.pitchX;
         const pitchY = this.pitchY;
         // if we have already laid it out, return its layout
@@ -65,12 +68,19 @@ export default class GranularRectLayout {
         const pLeft = Math.trunc(left / pitchX);
         const pRight = Math.trunc(right / pitchX);
         const pHeight = Math.ceil(height / pitchY);
+        const pLowerTop = lower ? Math.ceil(lower.top / pitchY) : pHeight;
         const rectangle = {
             l: pLeft,
             r: pRight,
             top: null,
             h: pHeight,
         };
+        const lowerSpan = lower
+            ? {
+                l: Math.trunc(lower.left / pitchX),
+                r: Math.trunc(lower.right / pitchX),
+            }
+            : rectangle;
         // Allow features to start at any position up to maxHeight
         // Features starting at maxHeight or beyond are filtered out, but features
         // that start below maxHeight and extend past it are allowed
@@ -84,7 +94,10 @@ export default class GranularRectLayout {
         // between them still spans y, because y < top + pHeight — so nothing between
         // can fit. `top = y` plus the loop's own increment is that jump, and it turns
         // the scan from O(rows * pHeight) into O(rows): without it, a rect pHeight
-        // rows tall re-tests the row that blocked it pHeight times over.
+        // rows tall re-tests the row that blocked it pHeight times over. Moving
+        // the rect down only moves y up within it, so a hit above the lower span
+        // blocks every top to y, and a hit in the lower span blocks just the tops
+        // keeping y there: the jump goes to the first top putting y above it.
         outer: for (; top <= maxTop; top += 1) {
             // Check all rows that this rectangle would occupy
             const maxY = top + pHeight;
@@ -97,13 +110,17 @@ export default class GranularRectLayout {
                 const intervals = row.getIntervals();
                 const len = intervals.length;
                 if (len > 0) {
+                    const inLower = y - top >= pLowerTop;
+                    const l = inLower ? lowerSpan.l : pLeft;
+                    const r = inLower ? lowerSpan.r : pRight;
+                    const blockedTop = inLower ? y - pLowerTop : y;
                     if (len < 40) {
                         // Linear scan for small arrays
                         for (let i = 0; i < len; i += 2) {
                             const start = intervals[i];
                             const end = intervals[i + 1];
-                            if (end > pLeft && start < pRight) {
-                                top = y;
+                            if (end > l && start < r) {
+                                top = blockedTop;
                                 continue outer;
                             }
                         }
@@ -115,7 +132,7 @@ export default class GranularRectLayout {
                         while (low < high) {
                             const mid = (low + high) >>> 1;
                             const midIdx = mid << 1;
-                            if (intervals[midIdx + 1] <= pLeft) {
+                            if (intervals[midIdx + 1] <= l) {
                                 low = mid + 1;
                             }
                             else {
@@ -125,8 +142,8 @@ export default class GranularRectLayout {
                         const idx = low << 1;
                         if (idx < len) {
                             const start = intervals[idx];
-                            if (start < pRight) {
-                                top = y;
+                            if (start < r) {
+                                top = blockedTop;
                                 continue outer;
                             }
                         }
@@ -143,7 +160,7 @@ export default class GranularRectLayout {
         rectangle.top = top;
         const yEnd = top + pHeight;
         for (let y = top; y < yEnd; y += 1) {
-            this.getOrCreateRow(y).addRect(rectangle);
+            this.getOrCreateRow(y).addRect(y - top >= pLowerTop ? lowerSpan : rectangle);
         }
         return top * pitchY;
     }

package/esm/util/lazyAfterAttach.d.ts

@@ -0,0 +1,13 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export declare function runLazyAfterAttach<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>): void;

package/esm/util/lazyAfterAttach.js

@@ -0,0 +1,31 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export function runLazyAfterAttach(self, load) {
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    ;
+    (async () => {
+        try {
+            const install = await load();
+            if (isAlive(self)) {
+                install(self);
+            }
+        }
+        catch (e) {
+            if (isAlive(self)) {
+                console.error(e);
+                getNotificationSink(self).notifyError(`${e}`, e);
+            }
+        }
+    })();
+}

package/esm/util/lazyWithPreload.d.ts

@@ -0,0 +1,19 @@
+import type { AnyReactComponentType } from './types/util.ts';
+/**
+ * `React.lazy` that also exposes the import it wraps, so code that knows a
+ * component is about to render (a session naming a view, a track being shown)
+ * can start the download instead of waiting for React to reach it. A failed
+ * load is not kept, so the render that follows tries again.
+ *
+ * Once the import has landed, the first render gets the module synchronously.
+ * React.lazy suspends on any promise, settled or not, and React holds a
+ * suspended boundary's reveal for 300 ms after its fallback commits, so a
+ * preloaded component nested under another cost that 300 ms per level.
+ */
+export declare function lazyWithPreload<T extends AnyReactComponentType>(factory: () => Promise<{
+    default: T;
+}>): import("react").LazyExoticComponent<T> & {
+    preload: () => Promise<{
+        default: T;
+    }>;
+};

package/esm/util/lazyWithPreload.js

@@ -0,0 +1,27 @@
+import { lazy } from 'react';
+/**
+ * `React.lazy` that also exposes the import it wraps, so code that knows a
+ * component is about to render (a session naming a view, a track being shown)
+ * can start the download instead of waiting for React to reach it. A failed
+ * load is not kept, so the render that follows tries again.
+ *
+ * Once the import has landed, the first render gets the module synchronously.
+ * React.lazy suspends on any promise, settled or not, and React holds a
+ * suspended boundary's reveal for 300 ms after its fallback commits, so a
+ * preloaded component nested under another cost that 300 ms per level.
+ */
+export function lazyWithPreload(factory) {
+    let loaded;
+    let loading;
+    const load = () => (loading ??= factory().then(module => (loaded = module), (error) => {
+        loading = undefined;
+        throw error;
+    }));
+    const settled = (module) => ({
+        // eslint-disable-next-line unicorn/no-thenable -- React.lazy takes a module synchronously only from a then that calls back at once
+        then: (resolve) => {
+            resolve(module);
+        },
+    });
+    return Object.assign(lazy(() => (loaded ? settled(loaded) : load())), { preload: load });
+}

package/esm/util/legendCandidates.d.ts

@@ -0,0 +1,72 @@
+import type { CategoricalEntry, CategoricalScale } from '../ui/colorScale.ts';
+import type { LegendSwatch } from '../ui/legendSpec.ts';
+import type { CategoricalField } from './categoricalField.ts';
+export interface LegendCandidate {
+    rowIndex: number;
+    value: string;
+    color: number;
+}
+export interface LegendEntry {
+    values: string[];
+    color: number;
+}
+export declare const MAX_LEGEND_ENTRIES = 30;
+export declare const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, value, color) combinations a packer walks
+ * past, in first-seen order and bounded, so the main thread never re-walks the
+ * features. Deduped on the whole triple: a row of the union lists every value
+ * painted in its color, so a second value on that color has to still be in the
+ * list to reach it.
+ */
+export declare function createLegendCandidateCollector(maxCandidates?: number): {
+    candidates: LegendCandidate[];
+    add(rowIndex: number, value: string, color: number): void;
+};
+export interface LegendCandidateSource {
+    candidates: readonly LegendCandidate[];
+    rowPaintsCandidateColor: (rowIndex: number) => boolean;
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color listing every value painted in it, colors in first-seen
+ * order. Keyed by color rather than by value because hiding a category hides
+ * features BY color, so two values sharing one color are one row that names
+ * both; a value met in two colors stays with the first.
+ *
+ * `[]` when there are more than `maxEntries` distinct colors, where the data is
+ * not a categorical vocabulary. `regions` is consumed lazily.
+ */
+export declare function unionLegendCandidates<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, maxEntries?: number): LegendEntry[];
+/**
+ * A source whose every entry is a candidate its one row paints: the entries of
+ * a scale table `encodeFeatures` resolved, or any walk that met each value in
+ * one color.
+ */
+export declare function everyRowPaints(entries: readonly {
+    value: string;
+    color: number;
+}[]): LegendCandidateSource;
+/**
+ * The one categorical key a color channel derives from what a worker painted:
+ * the union above over the loaded regions, each row a painted color naming
+ * every value in it through `field` and ordered by it, and nothing where the
+ * rows would say nothing (`legendIsReadable`). A display resolving its own colors hands the
+ * candidates its packer recorded; one resolved by `encodeFeatures` hands the
+ * entries of the scale tables that came back. Either way the key lists what
+ * the painting holds, and a `closed` field's domain besides once anything
+ * painted. `title` heads it in place of the field's name, `''` heading
+ * nothing, and `swatches` draws a row as something other than its color's box.
+ * `besides` are the colors of rows a display lists beside these, which the
+ * one-color test counts and the length test does not.
+ */
+export declare function derivedColorScale<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, { id, field, title, maxItems, swatches, besides, }: {
+    id: string;
+    field: CategoricalField;
+    title?: string;
+    maxItems?: number;
+    swatches?: (row: CategoricalEntry & {
+        color: string;
+    }) => LegendSwatch[];
+    besides?: readonly string[];
+}): CategoricalScale[];

package/esm/util/legendCandidates.js

@@ -0,0 +1,138 @@
+import { MAX_LEGEND_ITEMS, legendIsReadable } from '../ui/legendSpec.js';
+import { abgrToCssRgba, cssColorToABGR } from './colorBits.js';
+// How many distinct colors a derived key may name and still BE a key. Past this
+// the data is not a categorical vocabulary (a track keyed by unique per-feature
+// names), and a list of every feature is the thing a key exists instead of.
+//
+// A different question from `legendIsReadable`'s lower bar, which asks whether a
+// key a display already has is worth the rows it costs.
+export const MAX_LEGEND_ENTRIES = 30;
+// Bound on the candidate list one region ships. Far above MAX_LEGEND_ENTRIES, so
+// a vocabulary that is categorical at all crosses whole, and a track with a name
+// per feature ships a prefix that reads the same way it would have.
+export const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, value, color) combinations a packer walks
+ * past, in first-seen order and bounded, so the main thread never re-walks the
+ * features. Deduped on the whole triple: a row of the union lists every value
+ * painted in its color, so a second value on that color has to still be in the
+ * list to reach it.
+ */
+export function createLegendCandidateCollector(maxCandidates = MAX_LEGEND_CANDIDATES) {
+    const candidates = [];
+    const seen = new Set();
+    return {
+        candidates,
+        add(rowIndex, value, color) {
+            const id = `${rowIndex}\u0000${color}\u0000${value}`;
+            if (candidates.length < maxCandidates && !seen.has(id)) {
+                seen.add(id);
+                candidates.push({ rowIndex, value, color });
+            }
+        },
+    };
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color listing every value painted in it, colors in first-seen
+ * order. Keyed by color rather than by value because hiding a category hides
+ * features BY color, so two values sharing one color are one row that names
+ * both; a value met in two colors stays with the first.
+ *
+ * `[]` when there are more than `maxEntries` distinct colors, where the data is
+ * not a categorical vocabulary. `regions` is consumed lazily.
+ */
+export function unionLegendCandidates(regions, resolve, maxEntries = MAX_LEGEND_ENTRIES) {
+    const rows = new Map();
+    const seenValues = new Set();
+    for (const region of regions) {
+        const { candidates, rowPaintsCandidateColor } = resolve(region);
+        for (const { rowIndex, value, color } of candidates) {
+            if (!rowPaintsCandidateColor(rowIndex) || seenValues.has(value)) {
+                continue;
+            }
+            seenValues.add(value);
+            const row = rows.get(color);
+            if (row) {
+                row.values.push(value);
+            }
+            else {
+                rows.set(color, { values: [value], color });
+                if (rows.size > maxEntries) {
+                    return [];
+                }
+            }
+        }
+    }
+    return [...rows.values()];
+}
+/**
+ * A source whose every entry is a candidate its one row paints: the entries of
+ * a scale table `encodeFeatures` resolved, or any walk that met each value in
+ * one color.
+ */
+export function everyRowPaints(entries) {
+    return {
+        candidates: entries.map(({ value, color }) => ({
+            rowIndex: 0,
+            value,
+            color,
+        })),
+        rowPaintsCandidateColor: () => true,
+    };
+}
+/**
+ * The one categorical key a color channel derives from what a worker painted:
+ * the union above over the loaded regions, each row a painted color naming
+ * every value in it through `field` and ordered by it, and nothing where the
+ * rows would say nothing (`legendIsReadable`). A display resolving its own colors hands the
+ * candidates its packer recorded; one resolved by `encodeFeatures` hands the
+ * entries of the scale tables that came back. Either way the key lists what
+ * the painting holds, and a `closed` field's domain besides once anything
+ * painted. `title` heads it in place of the field's name, `''` heading
+ * nothing, and `swatches` draws a row as something other than its color's box.
+ * `besides` are the colors of rows a display lists beside these, which the
+ * one-color test counts and the length test does not.
+ */
+export function derivedColorScale(regions, resolve, { id, field, title = field.field, maxItems, swatches, besides = [], }) {
+    const painted = unionLegendCandidates(regions, resolve).map(({ values, color }) => {
+        const sorted = values.toSorted(field.compare);
+        const value = sorted[0];
+        return {
+            value,
+            values: sorted,
+            label: sorted.map(v => field.label(v)).join(', '),
+            color: abgrToCssRgba(color),
+            ...(value === '' ? { missing: true } : {}),
+        };
+    });
+    const named = new Set(painted.flatMap(e => e.values));
+    const unpainted = field.closed && painted.length > 0
+        ? field.domain
+            .filter(value => !named.has(value))
+            .map(value => ({
+            value,
+            label: field.label(value),
+            color: abgrToCssRgba(cssColorToABGR(field.color(value))),
+        }))
+        : [];
+    const entries = [...painted, ...unpainted].sort((a, b) => field.compare(a.value, b.value));
+    const beside = besides.map(color => ({
+        label: '',
+        color: abgrToCssRgba(cssColorToABGR(color)),
+    }));
+    return painted.length > 0 &&
+        legendIsReadable([...entries, ...beside], (maxItems ?? MAX_LEGEND_ITEMS) + beside.length)
+        ? [
+            {
+                kind: 'categorical',
+                id,
+                ...(title ? { title } : {}),
+                ...(field.domain.length > 0 ? { domain: field.domain } : {}),
+                entries: swatches
+                    ? entries.map(row => ({ ...row, swatches: swatches(row) }))
+                    : entries,
+            },
+        ]
+        : [];
+}

package/esm/util/localStorage.js

@@ -12,10 +12,10 @@ export const { available: localStorageAvailable, getItem: localStorageGetItem, s
 // and has to be announced by hand. Missing that half is what let two components
 // on one key show different values until one of them remounted.
 //
-// Announcing is deliberately not folded into localStorageSetItem. The
-// grid-bookmark widget persists its list from an autorun over the list, so a
-// write that called its own subscriber back would re-enter that autorun and
-// write again, forever. A writer says when its write is news.
+// Announcing is deliberately not folded into localStorageSetItem. A writer
+// that persists from an autorun over its own state would, if its write called
+// its own subscriber back, re-enter that autorun and write again, forever. A
+// writer says when its write is news.
 const listeners = new Map();
 // Installed on the first subscription rather than at module scope, so importing
 // this file from a worker or a test never touches `window`.