semiotic 3.7.4 → 3.8.0

package/dist/components/recipes/recipeLegend.d.ts

@@ -0,0 +1,109 @@
+import type { ReactElement } from "react";
+import type { LegendGroup } from "../types/legendTypes";
+import { type NetworkSymbolName } from "../stream/symbolPath";
+/**
+ * `legendGroupsFrom` — build the `LegendGroup[]` a custom-layout recipe passes
+ * through `frameProps.legend` (`{ legendGroups }`). All four custom-chart HOCs
+ * disable the built-in legend because the *layout* owns color/shape/size; without
+ * this, authors hand-roll the `LegendGroup` shape (its `styleFn`, custom-glyph
+ * `type` render functions, swatch sizing). This closes that gap without the frame
+ * having to guess the author's encoding — the recipe declares each channel and
+ * gets back a ready-to-render array.
+ *
+ * One group is emitted per provided channel, in order: **color → symbol → size**.
+ * Pure / SSR-safe.
+ *
+ * @example
+ * ```tsx
+ * <NetworkCustomChart
+ *   layout={packedClusterMatrix}
+ *   frameProps={{ legend: { legendGroups: legendGroupsFrom({
+ *     colorMap: CATEGORY_COLORS, colorLabel: "Category",
+ *     symbolMap: CLASS_SHAPES, symbolLabel: "Class",
+ *     sizeStops: [200, 2000, 8000], sizeRadius: r, sizeLabel: "Mass (kg)",
+ *   }) } }}
+ * />
+ * ```
+ */
+export interface LegendGroupsInput {
+    /** `{category → color}` map → one swatch per entry, in insertion order. */
+    colorMap?: Record<string, string>;
+    /** Or explicit category keys, with `color` resolving each to a color. */
+    keys?: string[];
+    /** Resolve a key → color (e.g. a recipe's `ctx.resolveColor`). Used with `keys`. */
+    color?: (key: string) => string;
+    /** Color-group heading. @default "" */
+    colorLabel?: string;
+    /** Color swatch glyph — a filled square or a line stroke. @default "fill" */
+    colorType?: "fill" | "line";
+    /** `{category → glyph shape}` map → one shape swatch per entry. */
+    symbolMap?: Record<string, NetworkSymbolName>;
+    /** Fill for the shape swatches (shape, not color, is the encoding here).
+     *  @default "var(--semiotic-text, currentColor)" */
+    symbolColor?: string;
+    /** Symbol-group heading. @default "" */
+    symbolLabel?: string;
+    /** Reference values → circle swatches sized by the mark scale. */
+    sizeStops?: number[];
+    /** Map a value → radius (px) — pass the recipe's own radius scale so the
+     *  legend circles match the marks exactly. Required to draw the size group. */
+    sizeRadius?: (v: number) => number;
+    /** Format a size stop for its label. @default `String` */
+    sizeFormat?: (v: number) => string;
+    /** Size swatch circle fill. @default "var(--semiotic-text, currentColor)" */
+    sizeColor?: string;
+    /** Size-group heading. @default "" */
+    sizeLabel?: string;
+}
+export declare function legendGroupsFrom(input: LegendGroupsInput): LegendGroup[];
+export interface LegendSwatch {
+    /** Legend entry label. */
+    label: string;
+    /** Filled-square swatch color (the categorical / fill case). */
+    color?: string;
+    /** Line-stroke swatch color (a horizontal bar — for line-series legends). */
+    line?: string;
+    /** Glyph-shape swatch (the per-datum shape channel). */
+    shape?: NetworkSymbolName;
+    /** Diagonal-hatch swatch (percentile / uncertainty bands). Line color comes
+     *  from `color`, falling back to the label color. */
+    hatch?: boolean;
+}
+export interface LegendSwatchesProps {
+    entries: LegendSwatch[];
+    /** Top-left x of the legend block, in plot coordinates. */
+    x: number;
+    /** Top-left y of the legend block, in plot coordinates. */
+    y: number;
+    /** Stack entries down (`vertical`) or flow them across (`horizontal`).
+     *  @default "vertical" */
+    orientation?: "vertical" | "horizontal";
+    /** Swatch box size in px. @default 14 */
+    swatchSize?: number;
+    /** Row height (vertical) / inter-entry gap (horizontal), px. @default 8 (+ swatch) */
+    gap?: number;
+    /** Gap between a swatch and its label, px. @default 6 */
+    labelGap?: number;
+    /** @default 12 */
+    fontSize?: number;
+    /** Label color. @default "var(--semiotic-text-secondary, #888)" */
+    color?: string;
+    className?: string;
+    keyId?: string | number;
+}
+/**
+ * A self-contained SVG legend a custom layout draws in its `overlays` — the
+ * portable counterpart to {@link legendGroupsFrom} (which feeds the *frame's*
+ * legend via `frameProps.legend`). Custom charts disable the built-in legend,
+ * so this renders swatch + label rows directly: fill squares, line bars, glyph
+ * shapes, and diagonal-hatch swatches, stacked or flowed. `pointerEvents: none`.
+ *
+ * @example
+ * ```ts
+ * legendSwatches({
+ *   x: 0, y: 0, orientation: "horizontal",
+ *   entries: SPHERES.map((s) => ({ label: s, color: COLORS[s] })),
+ * })
+ * ```
+ */
+export declare function legendSwatches(p: LegendSwatchesProps): ReactElement;

package/dist/components/recipes/recipeUtils.d.ts

@@ -5,6 +5,50 @@ import type { Datum } from "../charts/shared/datumTypes";
  * the boundary and lets the layout body call a single function.
  */
 export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) => T)): (d: Datum) => T;
+/**
+ * Read a field off a network-ingest wrapper (`node.data.<key>`) or the node
+ * itself, with a fallback. Network recipes receive `RealtimeNode`/`RealtimeEdge`
+ * wrappers whose user data lives under `.data`; several recipes (lineageDag,
+ * mermaidDag, packedClusterMatrix, …) each re-declared this identical reader, so
+ * it lives here once. Returns `unknown` — narrow at the call site.
+ */
+export declare function readField(d: unknown, key: string, fallback: unknown): unknown;
+/**
+ * Return the **raw user datum** from a value that may be a frame wrapper.
+ *
+ * Stream Frames and custom-layout scene nodes carry the user's object under
+ * `.data` (a `RealtimeNode` / `SceneDatum` wrapper), and some interaction
+ * payloads nest it under `.datum` (hit-test results, certain tooltip inputs) —
+ * the wrapped-vs-raw split that bites every `onObservation` consumer. This
+ * collapses all of it: `unwrapDatum(value)` always yields the object you
+ * passed in, whether the frame wrapped it (either way) or not.
+ *
+ * This is **the** unwrap path for both `onObservation` handlers and
+ * `frameProps.tooltipContent` renderers — call it once on the incoming value
+ * instead of hand-rolling `x.data ?? x` guards (and never pre-unwrap the
+ * argument yourself: `unwrapDatum(x?.data ?? x)` can double-unwrap a raw datum
+ * that legitimately carries a `data` field).
+ *
+ * Heuristic footgun: any value with a top-level `data` (or `datum`) property is
+ * treated as a wrapper. If your *raw* datum legitimately has its own such
+ * field, this returns that field instead of the datum — rename the field or
+ * read it directly.
+ *
+ * @example
+ * ```ts
+ * onObservation={(o) => {
+ *   if (o.type === "hover") setActive(unwrapDatum(o.datum))
+ * }}
+ * ```
+ */
+export declare function unwrapDatum<T = Datum>(value: unknown): T | null;
+/**
+ * Group items into a `Map` keyed by a derived string. Insertion order is
+ * preserved both for keys and within each bucket — recipes rely on stable
+ * ordering for deterministic layout. Several recipes re-declared this; it lives
+ * here once.
+ */
+export declare function groupBy<T>(items: readonly T[], key: (item: T) => string): Map<string, T[]>;
 /**
  * Build a datum object whose own-properties are safe to set from
  * user-supplied accessor names. `Object.create(null)` produces a
@@ -25,3 +69,116 @@ export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) =>
  * scattered across each recipe's inner loops.
  */
 export declare function createSafeDatum(populate: (set: (key: string, value: unknown) => void) => void): Datum;
+/**
+ * A `{field, value}` highlight target — or an array of them, AND-combined (a
+ * datum must match every entry to count as a match, e.g. a region×orbit cell).
+ * `value` is coerced to a string before comparison; a nullish `value` matches
+ * anything (so `{ field, value: null }` is a no-op constraint).
+ */
+export type HighlightMatch = {
+    field: string;
+    value: unknown;
+} | ReadonlyArray<{
+    field: string;
+    value: unknown;
+}>;
+/**
+ * Whether `datum` satisfies a `{field, value}` highlight (or every entry of an
+ * array). A nullish/empty `highlight` matches everything — the "no highlight
+ * active" case. Several recipes hand-rolled this exact field/value loop.
+ */
+export declare function matchesHighlight(datum: Datum, highlight: HighlightMatch | null | undefined): boolean;
+export interface DimOptions {
+    /** A datum is lit only if this predicate passes (e.g. a shared-selection
+     *  predicate, or `parallelCoordinates`'s `highlightFn`). Omit ⇒ no constraint. */
+    predicate?: ((d: Datum) => boolean) | null;
+    /** A datum is lit only if it matches this `{field, value}` (or all, for an
+     *  array). Omit ⇒ no constraint. Composes with `predicate` (both must pass). */
+    highlight?: HighlightMatch | null;
+    /** Opacity used when no cue is active (nothing is dimmed). @default 1 */
+    baseOpacity?: number;
+    /** Opacity for marks that don't match an active cue. @default 0.16 */
+    dimOpacity?: number;
+    /** Additive opacity boost for matching marks when a cue is active, capped at 1
+     *  (e.g. `parallelCoordinates` lifts its 0.45 line opacity by 0.4 on match). @default 0 */
+    brighten?: number;
+}
+/**
+ * The highlight/dim opacity rule, shared across custom-layout recipes. A mark is
+ * "lit" when it satisfies **every** active cue (`highlight` AND `predicate`); if
+ * no cue is active nothing is dimmed and every mark gets `baseOpacity`. Lit marks
+ * get `min(1, baseOpacity + brighten)`, dimmed marks get `dimOpacity`.
+ *
+ * This is the one rule `packedClusterMatrix` and `parallelCoordinates` each
+ * hand-rolled; centralizing it keeps the "matching marks stay lit, the rest dim"
+ * behavior identical. (Recipes whose dimming composes several cues with priority
+ * and rescue rules — e.g. `lineageDag`'s reach-set-over-selection — keep their
+ * bespoke logic; this helper is for the common AND-of-cues case.)
+ */
+export declare function dimFor(datum: Datum, opts?: DimOptions): number;
+/**
+ * Join layout-affecting inputs into a stable content-signature string. Pass the
+ * primitives that change the geometry (dimensions, gaps, orders, a per-datum
+ * fingerprint) — NOT styling/interaction inputs (color, shade, highlight) — so a
+ * re-style or a returning resize reuses a cached layout instead of recomputing it.
+ * Pairs with {@link LayoutCache}.
+ */
+export declare function signatureKey(parts: ReadonlyArray<string | number | boolean | null | undefined>): string;
+/**
+ * A tiny bounded geometry cache for expensive layouts (force packing, tree/DAG
+ * positioning). Key it with a {@link signatureKey} of the layout-affecting inputs
+ * so re-styling on interaction never re-runs the layout.
+ *
+ * **The sharp edge:** on `NetworkCustomChart`/`*CustomChart`, `ctx.nodes` is a
+ * *fresh array each `buildScene`* and a `layoutConfig` change re-runs the layout
+ * without re-ingesting topology — so cache by *content* (a fingerprint of the
+ * data), never by array identity. Over `maxSize` distinct keys it clears wholesale
+ * (these layouts churn a handful of signatures, not thousands).
+ */
+export declare class LayoutCache<V> {
+    private readonly maxSize;
+    private store;
+    constructor(maxSize?: number);
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    /** Return the cached value for `key`, or compute + store it on a miss. */
+    getOrCompute(key: string, compute: () => V): V;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * A reusable lightness shader for one base color. Interpolating in CIELAB keeps
+ * the hue and chroma roughly fixed while only lightness moves, so a categorical
+ * hue can carry a second *continuous* channel as shade (e.g. age, recency).
+ *
+ * The returned function takes `t ∈ [0,1]`: `0` lightens toward white, `1`
+ * darkens toward black, `0.5` returns the base. `strength` (0..1) caps how far
+ * each direction travels. Pure / SSR-safe — no DOM. Build once per base color
+ * (it captures two interpolators) and call per datum.
+ */
+export declare function makeShade(baseColor: string, strength?: number): (t: number) => string;
+/** One-shot form of {@link makeShade}: perceptual lightness shade of `baseColor`. */
+export declare function shade(baseColor: string, t: number, strength?: number): string;
+/** Build a scene-node `datum` from a flat field map (a thin wrapper over
+ *  {@link createSafeDatum}, used by recipes that synthesize per-glyph data). */
+export declare function datumFromFields(fields: Record<string, unknown>): Datum;
+/** A stable, URL/key-safe id from an arbitrary label — for keyed overlays and
+ *  transition identity (`"Extra Boba" → "extra-boba"`). */
+export declare function stableGlyphId(value: string): string;
+/** Clamp `value` into `[min, max]`. The one-liner every layout re-declares to
+ *  keep a radius, opacity, or pixel position inside its valid range. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Coerce to a finite non-negative number. Shared by tally/token helpers so
+ *  non-finite inputs fail closed instead of leaking NaN into geometry. */
+export declare function nonNegativeFinite(value: number | undefined): number;
+/** Arithmetic mean of a numeric list; `0` for an empty list (so it's safe to
+ *  feed an unfiltered slice). Recipes average angles, positions, and weights. */
+export declare function mean(values: readonly number[]): number;
+/**
+ * Turn a hex color (`#rgb` or `#rrggbb`) into an `rgba(…)` string at `alpha`.
+ * The dimming-by-alpha helper a custom layout reaches for when it must express
+ * hover/selection fade as a *fill color* (e.g. inside a recipe's `resolveColor`
+ * callback, where the frame's opacity channel isn't available). Non-hex input
+ * is returned unchanged so it composes with CSS-var / `rgb()` colors.
+ */
+export declare function withAlpha(color: string, alpha: number): string;

package/dist/components/recipes/runs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Run-length encoding for sequential/categorical series — the "collapse a
+ * per-step categorical field into drawable runs" operation that condition
+ * strips, status timelines, and calendar ribbons all need. A custom layout
+ * draws one rect per run instead of one per step.
+ *
+ * Pure / SSR-safe. Several custom charts re-derived this with three slightly
+ * different signatures (value-change by index, value-change by domain coord,
+ * boolean-present); this is the single form that covers all three.
+ */
+export interface Run<V> {
+    /** The constant value over the run. */
+    value: V;
+    /** Run start on the domain axis — the array index of the first item, or the
+     *  `coord` of the first item when `coord` is supplied. Inclusive. */
+    start: number;
+    /** Run end on the domain axis. Half-open: the run covers `[start, end)`. With
+     *  `coord`, this is the next item's coord (or the last coord + `step` for the
+     *  final run / a run that precedes a gap). Without `coord`, the index after
+     *  the run's last item. */
+    end: number;
+    /** Number of consecutive items in the run. */
+    count: number;
+    /** Index of the run's first item in the input array. */
+    startIndex: number;
+    /** Index of the run's last item in the input array (inclusive). */
+    endIndex: number;
+}
+export interface RunOptions<T, V> {
+    /** Map an item to its position on the domain axis (e.g. day-of-year). When
+     *  omitted, the array index is used and runs are index-based. A gap in
+     *  `coord` (a jump larger than `step`) closes the current run. */
+    coord?: (item: T, index: number) => number;
+    /** Width of one item on the domain axis — closes the final run and detects
+     *  gaps when `coord` is supplied. @default 1 */
+    step?: number;
+    /** Custom equality for grouping adjacent items. @default `Object.is` */
+    equals?: (a: V, b: V) => boolean;
+    /** Presence mode: only items with a truthy value form runs; falsy items break
+     *  the current run and are excluded entirely (the boolean condition-strip
+     *  variant). @default false */
+    truthyOnly?: boolean;
+}
+/**
+ * Collapse a sequential series into runs of equal adjacent values.
+ *
+ * @example value-change runs over a domain coordinate (a condition ring/strip)
+ * ```ts
+ * runs(days, (d) => d.condition, { coord: (d) => d.day, step: 1 })
+ * // → [{ value: "clear", start: 0, end: 5, count: 5, ... }, ...]
+ * ```
+ * @example boolean present/absent runs (a "freezing days" strip)
+ * ```ts
+ * runs(days, (d) => d.belowFreezing, { truthyOnly: true })
+ * ```
+ */
+export declare function runs<T, V = unknown>(items: readonly T[], value: (item: T, index: number) => V, opts?: RunOptions<T, V>): Run<V>[];
+/** Alias for {@link runs} — the textbook name for the transform. */
+export declare const runLengthEncode: typeof runs;

package/dist/components/recipes/tokenEncoding.d.ts

@@ -0,0 +1,157 @@
+export type TokenType = "dot" | "icon" | "glyph";
+export type TokenSemantics = "observed-unit" | "unitized-measure" | "possible-outcome" | "posterior-sample" | "hypothetical-case" | "risk-case" | "topic-anchor" | "decorative";
+export type TokenCountStrategy = "actual" | "unitized" | "fixed-denominator" | "quantile" | "sample" | "posterior-sample" | "random-sample";
+export type TokenLayout = "row" | "column" | "grid" | "stack" | "bar-segment" | "waffle" | "beeswarm" | "dotplot" | "quantile-strip" | "small-multiple";
+export type TokenLabelPolicy = "text-plus-token" | "text-plus-icon" | "text-only" | "token-only" | "icon-only" | "none";
+export type TokenTaskIntent = "precise-comparison" | "frequency-reasoning" | "probability-estimation" | "risk-communication" | "memory" | "editorial-engagement" | "public-explanation" | "support-decision" | "measure" | "estimate probability" | "understand risk" | "remember" | "decide";
+export type TokenCapabilityIntent = "compare-categories" | "distribution" | "part-to-whole" | "rank" | "outlier-detection";
+export interface TokenEncoding {
+    tokenType: TokenType;
+    tokenSemantics: TokenSemantics;
+    countStrategy: TokenCountStrategy;
+    layout?: TokenLayout;
+    /** Named icon/glyph key in host code; Semiotic keeps this semantic, not visual. */
+    token?: string;
+    icon?: string;
+    /** Value represented by one complete token for unitized measures. */
+    unitValue?: number;
+    /** Alias for `unitValue`, matching the lower-level `unitize` helper. */
+    unit?: number;
+    /** Human-readable meaning, e.g. "one token = 1,000 commuters". */
+    unitMeaning?: string;
+    tokenCount?: number;
+    maxTokens?: number;
+    minFraction?: number;
+    numerator?: number;
+    denominator?: number;
+    labelPolicy?: TokenLabelPolicy;
+    seed?: number;
+}
+export interface TokenGeneratorInput<D = unknown> {
+    value?: number;
+    /** Scenario/projection endpoint for `unitized` tallies. */
+    rangeValue?: number;
+    numerator?: number;
+    denominator?: number;
+    samples?: readonly number[];
+    data?: readonly D[];
+    valueAccessor?: keyof D | ((d: D) => number);
+}
+export interface VisualToken<D = unknown> {
+    index: number;
+    tokenType: TokenType;
+    tokenSemantics: TokenSemantics;
+    countStrategy: TokenCountStrategy;
+    fraction: number;
+    startFraction: number;
+    value: number;
+    start: number;
+    end: number;
+    unitValue?: number;
+    unitMeaning?: string;
+    highlighted?: boolean;
+    /** Marks a token as the projected/scenario extension of a range tally. */
+    range?: "scenario";
+    quantile?: number;
+    sample?: number;
+    datum?: D;
+}
+export type TokenDiagnosticCode = "TOKEN_SEMANTICS_UNCLEAR" | "MISSING_COUNT_STRATEGY" | "ICON_ONLY_LABELS" | "TOO_MANY_VISIBLE_TOKENS" | "DECORATIVE_PICTOGRAPHS" | "TOKEN_STRATEGY_MISMATCH" | "MISSING_UNIT_VALUE" | "MISSING_UNIT_MEANING";
+export interface TokenDiagnostic {
+    code: TokenDiagnosticCode;
+    severity: "warning" | "info";
+    message: string;
+}
+export interface TokenDiagnosticsContext {
+    visibleTokens?: number;
+    maxRecommendedTokens?: number;
+}
+export interface TokenSet<D = unknown> {
+    tokens: VisualToken<D>[];
+    encoding: TokenEncoding;
+    /**
+     * Strategy-specific source total: value-space for `unitized`/numeric `actual`,
+     * denominator for `fixed-denominator`, sample count for sample/quantile
+     * strategies, and observed datum count for data-backed `actual`.
+     */
+    total: number;
+    /**
+     * Strategy-specific visible amount: represented value for `unitized`, visible
+     * token count for fixed-denominator/sample/quantile/data-backed actual.
+     */
+    shown: number;
+    overflow: boolean;
+    numerator?: number;
+    denominator?: number;
+    unitValue?: number;
+    /** Projected/scenario endpoint when input.rangeValue is supplied. */
+    rangeTotal?: number;
+    /** Tokens extending a unitized tally from total to rangeTotal. */
+    rangeTokens?: VisualToken<D>[];
+    diagnostics: TokenDiagnostic[];
+}
+export interface TokenGridOptions {
+    x?: number;
+    y?: number;
+    columns?: number;
+    rows?: number;
+    cellWidth?: number;
+    cellHeight?: number;
+    gutter?: number;
+    flow?: "row" | "column";
+    columnDirection?: "right" | "left";
+    rowDirection?: "down" | "up";
+    /** Anchor within each cell for the returned point. `[0.5, 1]` is useful for feet-down glyphs. */
+    anchor?: [number, number];
+}
+export interface PositionedToken<D = unknown> extends VisualToken<D> {
+    x: number;
+    y: number;
+    row: number;
+    column: number;
+}
+export interface TokenEncodingSuggestion {
+    recommendedEncoding: string;
+    tokenEncoding?: TokenEncoding;
+    rationale: string;
+    warnings: TokenDiagnostic[];
+    alternatives: string[];
+}
+export interface SuggestTokenEncodingInput {
+    taskIntent: TokenTaskIntent;
+    dataType?: "count" | "measure" | "distribution" | "probability" | "risk" | "category";
+    audience?: "expert" | "general-public" | "internal";
+    precisionNeed?: "low" | "medium" | "high";
+    availableSpace?: "small" | "medium" | "large";
+    concreteEntity?: string;
+}
+export declare function normalizeTokenEncoding(encoding: TokenEncoding): TokenEncoding;
+/**
+ * Generate visible token records from a semantic token encoding.
+ *
+ * This is the frame-agnostic bridge between the strategy layer ("each token
+ * is a case / unit / possible outcome") and today's glyph/dot/icon renderers.
+ * `unitized` delegates to `unitize`, so fractional final glyphs keep the same
+ * ISOTYPE partial-fill convention used by existing custom layouts.
+ */
+export declare function generateTokens<D = unknown>(input: number | readonly number[] | TokenGeneratorInput<D>, encoding: TokenEncoding): TokenSet<D>;
+/**
+ * Position generated tokens in a deterministic row/column grid. The returned
+ * `(x, y)` is the anchor point inside each cell, so use `[0.5, 1]` for
+ * baseline-standing ISOTYPE glyphs and `[0.5, 0.5]` for centered dots/icons.
+ */
+export declare function layoutTokenGrid<D = unknown>(tokenSetOrTokens: TokenSet<D> | readonly VisualToken<D>[], options?: TokenGridOptions): PositionedToken<D>[];
+export declare function diagnoseTokenEncoding(encoding: Partial<TokenEncoding>, context?: TokenDiagnosticsContext): TokenDiagnostic[];
+/**
+ * Bridge token-task intents into the chart capability taxonomy used by
+ * `suggestCharts`. Human-friendly aliases normalize first, so callers can use
+ * either the canonical token intent (`probability-estimation`) or the UI label
+ * alias (`estimate probability`).
+ */
+export declare function tokenTaskIntentToCapabilityIntents(intent: TokenTaskIntent): TokenCapabilityIntent[];
+/**
+ * Task-aware defaults for tokenized reasoning. This does not render a chart;
+ * it returns the semantic encoding Semiotic/IDID can explain, critique, or
+ * hand to `generateTokens` before a custom layout stamps dots/icons/glyphs.
+ */
+export declare function suggestTokenEncoding(input: SuggestTokenEncodingInput): TokenEncodingSuggestion;

package/dist/components/recipes/tokenLayer.d.ts

@@ -0,0 +1,79 @@
+import type { GlyphDef } from "../stream/glyphDef";
+import type { SceneAccessibilityMetadata, SceneDatum, SceneNode, Style } from "../stream/types";
+import type { SymbolName } from "../stream/symbolPath";
+import { type PositionedToken, type TokenEncoding, type TokenGeneratorInput, type TokenGridOptions, type TokenLayout, type TokenSet, type VisualToken } from "./tokenEncoding";
+export type TokenLayerInput<D> = number | readonly number[] | TokenGeneratorInput<D> | TokenSet<D>;
+export type TokenLayerValue<T, D> = T | ((token: PositionedToken<D>) => T | undefined);
+export interface TokenPosition {
+    x: number;
+    y: number;
+    row?: number;
+    column?: number;
+}
+export interface TokenLayerOptions<D = unknown> extends TokenGridOptions {
+    /** Override the encoding's preferred layout for this placement. */
+    layout?: TokenLayout;
+    /** Plot-space width used to infer grid columns or normalize quantile strips. */
+    width?: number;
+    /** Plot-space height used to normalize quantile strips. */
+    height?: number;
+    /** Rendered glyph height / symbol diameter / dot diameter. @default 12
+     *  For user-facing ISOTYPE/icon arrays, prefer 16px+ in the final layout. */
+    tokenSize?: TokenLayerValue<number, D>;
+    /** Dot radius. Defaults to half tokenSize. */
+    radius?: TokenLayerValue<number, D>;
+    /** Primary mark paint. Prefer passing ctx.resolveColor(...) from custom layouts. */
+    color?: TokenLayerValue<string, D>;
+    /** Paint for unhighlighted fixed-denominator tokens. */
+    inactiveColor?: TokenLayerValue<string, D>;
+    /** Paint for projected/scenario range tokens when includeRange is true. */
+    rangeColor?: TokenLayerValue<string, D>;
+    /** Accent paint for glyph role fills. */
+    accent?: TokenLayerValue<string, D>;
+    /** Ghost paint for partial glyph fills. */
+    ghostColor?: TokenLayerValue<string | undefined, D>;
+    /** Symbol shape for dot/icon fallback rendering. */
+    symbolType?: TokenLayerValue<SymbolName, D>;
+    /** Custom origin-centered SVG path for symbol nodes. */
+    symbolPath?: TokenLayerValue<string | undefined, D>;
+    /** Composite pictogram definition for icon/glyph tokens. */
+    glyph?: TokenLayerValue<GlyphDef | undefined, D>;
+    /** Partial-fill axis for glyph tokens. */
+    fractionDirection?: TokenLayerValue<"horizontal" | "vertical", D>;
+    rotation?: TokenLayerValue<number | undefined, D>;
+    style?: TokenLayerValue<Style | undefined, D>;
+    datum?: TokenLayerValue<SceneDatum, D>;
+    accessibleDatum?: TokenLayerValue<SceneAccessibilityMetadata["accessibleDatum"], D>;
+    accessibility?: TokenLayerValue<SceneAccessibilityMetadata["accessibility"], D>;
+    pointId?: TokenLayerValue<string | undefined, D>;
+    idPrefix?: string;
+    include?: (token: PositionedToken<D>) => boolean;
+    /** Render `TokenSet.rangeTokens` after base tokens for unitized scenario tallies. */
+    includeRange?: boolean;
+    /** Custom placement hook for scale-driven strips, stacks, map clusters, etc. */
+    positionToken?: (token: VisualToken<D>, index: number, tokens: readonly VisualToken<D>[]) => TokenPosition;
+    /** Maps a sample/value to plot-space x for quantile/sample strips. */
+    valueToX?: (value: number, token: VisualToken<D>) => number;
+    /** Maps a sample/value to plot-space y for quantile/sample strips. */
+    valueToY?: (value: number, token: VisualToken<D>) => number;
+}
+export interface TokenLayerConfig<D = unknown> {
+    input: TokenLayerInput<D>;
+    encoding?: TokenEncoding;
+    options?: TokenLayerOptions<D>;
+}
+export interface TokenLayerResult<D = unknown> {
+    tokenSet: TokenSet<D>;
+    positionedTokens: PositionedToken<D>[];
+    nodes: SceneNode[];
+}
+/**
+ * Frame-agnostic rendering helper for tokenized reasoning.
+ *
+ * `tokenLayer` is the scene-node bridge for ISOTYPE/icon arrays, risk grids,
+ * quantile dotplots, and hybrid bar-token layouts. It creates the semantic
+ * tokens, positions them, and returns ordinary Semiotic scene nodes so custom
+ * charts still get canvas/SVG rendering, hit testing, keyboard navigation,
+ * pointId annotations, transitions, and accessible table rows.
+ */
+export declare function tokenLayer<D = unknown>({ input, encoding, options, }: TokenLayerConfig<D>): TokenLayerResult<D>;