semiotic 3.7.3 → 3.7.5

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

@@ -0,0 +1,52 @@
+import type { CustomLayout } from "../stream/customLayout";
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { GofishGlyphMark } from "./gofish";
+import type { GofishLambda } from "./gofishLambdas";
+import type { GofishRootIR } from "./gofishIR";
+/**
+ * GoFish IR interpreter.
+ *
+ * Walks a `data → operators → mark` tree and *executes* the grammar —
+ * `group`/`spread`/`stack`/`scatter`/`treemap`/`layer`, the `polar`/`unit`
+ * coordinate transforms, mark channels through scales, and `connect`/`ref`/
+ * `arrow` relations — emitting positioned primitives. This is a real
+ * translator, not a recognizer: any spec built from these constructs renders.
+ *
+ * It is NOT GoFish's full constraint solver. GoFish elaborates `spread` to
+ * `layer + distribute + align` over a linear-system bbox; we implement the
+ * deterministic allocation/accumulation model the common acyclic specs reduce
+ * to. Constructs outside it (`table`, `cut`, `mask`, `over`/`inside`/`xor`,
+ * free-form `.constrain`) record a warning and fall back, never silently
+ * mis-render. The two sanctioned non-grammar paths — `derive` and `mark-fn`
+ * lambdas — resolve through the lambda registry.
+ */
+export interface InterpretOptions {
+    /** Per-call lambda overrides for `derive`/`mark-fn` (merged over the registry). */
+    lambdas?: Record<string, GofishLambda>;
+    /** Collected warnings for unsupported constructs / unresolved lambdas. */
+    warnings?: string[];
+}
+/** XY binding — the default for free-coordinate GoFish charts. */
+export declare function interpretToXYLayout(root: GofishRootIR, options?: InterpretOptions): CustomLayout;
+/**
+ * Ordinal binding — the top-level categorical `spread`/`group` maps to the
+ * frame's o-scale (one band per category); each category's subtree is
+ * interpreted within its full band column. A pictorial glyph that declares a
+ * `unit` coord with `fit: "uniform"` then scales aspect-correctly to fill the
+ * column (e.g. boba cups). Emits one data-bearing hit rect per category + the
+ * interpreted glyph as overlays.
+ *
+ * `config.glyphWidthRatio` (alias `cupWidthRatio`) insets the glyph column
+ * horizontally so neighboring glyphs breathe; default 0.9.
+ */
+export declare function interpretToOrdinalLayout(root: GofishRootIR, categoryAccessor: string, options?: InterpretOptions): OrdinalCustomLayout;
+/** Interpret a root to raw marks (for tests / custom hosts). */
+export declare function interpretToMarks(root: GofishRootIR, frame: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, resolveColor?: (key: string) => string, options?: InterpretOptions): {
+    marks: GofishGlyphMark[];
+    warnings: string[];
+};

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

@@ -0,0 +1,145 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * GoFish escape-hatch lambda registry.
+ *
+ * GoFish's serialized IR cannot carry function bodies, so `derive` (a
+ * `(rows) => rows'` data transform) and `mark-fn` (a `(datum) => drawing`
+ * custom glyph) travel as a `lambdaId` that the host resolves through a
+ * bridge. This module is that bridge for the Semiotic interpreter: register a
+ * function under the id the IR references and `interpretGofishIR` will call it
+ * where the grammar genuinely can't reach.
+ *
+ * This is the *only* sanctioned non-grammar path. A spec that resolves to pure
+ * operators + marks needs no lambdas; one that reaches a `derive`/`mark-fn`
+ * names the computation here.
+ */
+export interface DeriveLambda {
+    kind: "derive";
+    /** Transform the in-scope rows — add columns, or emit new rows. */
+    fn: (rows: Datum[]) => Datum[];
+}
+export interface MarkFnLambda {
+    kind: "mark-fn";
+    /**
+     * Draw a bespoke glyph for one datum inside its allocated unit frame
+     * (coordinates in [0,1], mapped to pixels by the interpreter). Returns
+     * primitive marks the interpreter splices into the scene.
+     */
+    fn: (datum: Datum, frame: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }) => GofishLambdaPrimitive[];
+}
+export type GofishLambda = DeriveLambda | MarkFnLambda;
+/** A primitive a `mark-fn` may emit (unit coords). Mirrors the glyph vocabulary. */
+export type GofishLambdaPrimitive = {
+    kind: "polygon";
+    points: Array<[number, number]>;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+} | {
+    kind: "circle";
+    x: number;
+    y: number;
+    r: number;
+    fill?: string;
+    stroke?: string;
+    opacity?: number;
+} | {
+    kind: "rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fill?: string;
+    stroke?: string;
+    opacity?: number;
+    rotate?: number;
+} | {
+    kind: "text";
+    x: number;
+    y: number;
+    text: string;
+    fill?: string;
+    fontSize?: number;
+};
+/** Register a `derive`/`mark-fn` implementation under the id the IR references. */
+export declare function registerGofishLambda(id: string, lambda: GofishLambda): () => void;
+export declare function unregisterGofishLambda(id: string): void;
+export declare function getGofishLambda(id: string): GofishLambda | undefined;
+/** Merge a per-call lambda map over the module registry (per-call wins). */
+export declare function resolveLambda(id: string, perCall?: Record<string, GofishLambda>): GofishLambda | undefined;
+export interface BobaCellGeometry {
+    cup: Array<[number, number]>;
+    tea: Array<[number, number]> | null;
+    straw: Array<[number, number]> | null;
+    /** Thick rim/lid bar across the cup top. */
+    lid: {
+        x1: number;
+        x2: number;
+        y: number;
+    };
+    pearls: Array<{
+        x: number;
+        y: number;
+        r: number;
+        fill: string;
+    }>;
+    ice: Array<{
+        x: number;
+        y: number;
+        w: number;
+        rot: number;
+        fill: string;
+    }>;
+    /** Content box `[bw, bh]` for the `uniform` unit fit; shared across the menu. */
+    box: [number, number];
+    numBobas: number;
+    numIce: number;
+    teaVolume: number;
+    bobaVolume: number;
+    iceVolume: number;
+    totalVolume: number;
+    cupStroke: string;
+}
+/** Single-cup convenience (normalizes against itself). */
+export declare function computeBobaCellGeometry(row: Datum): BobaCellGeometry;
+/**
+ * The built-in `bobaGeometry` derive: solve every cup, then attach `_g`
+ * (geometry against the shared menu-wide normalization) plus the fixed fills
+ * the marks read.
+ */
+export declare const bobaGeometryLambda: DeriveLambda;
+export interface BottleCellGeometry {
+    silhouette: Array<[number, number]>;
+    imageHref: string;
+    fill: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    fillLine: {
+        x1: number;
+        x2: number;
+        y: number;
+    };
+    pct: {
+        x: number;
+        y: number;
+        text: string;
+    };
+    label: {
+        x: number;
+        y: number;
+        text: string;
+    };
+    fillFill: string;
+}
+export declare function computeBottleCellGeometry(row: Datum): BottleCellGeometry;
+/** The built-in `bottleGeometry` derive: attach `_b` (normalized geometry) per bottle. */
+export declare const bottleGeometryLambda: DeriveLambda;

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

@@ -0,0 +1,129 @@
+import type { ReactNode } from "react";
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Level of detail for a node glyph.
+ * - `full`    container + icon + type label + truncated name + store-slot chips
+ * - `compact` container + icon + truncated name
+ * - `icon`    container + icon only
+ * - `dot`     a single ~5px circle (minimap density)
+ */
+export type LineageLod = "full" | "compact" | "icon" | "dot";
+export interface LineageStoreSlot {
+    storeName: string;
+    slotIndex: number;
+}
+export interface LineageDagConfig {
+    /** Number of layers (x domain). Computed from node `x` extents when omitted. */
+    layerCount?: number;
+    /** Largest layer's row count (y domain). Computed from the data when omitted. */
+    maxLayerSize?: number;
+    /** Target full-glyph width / height in px. Shrunk to fit the plot. @default 172 / 54 */
+    nodeWidth?: number;
+    nodeHeight?: number;
+    /** Minimum gap reserved between glyphs when fitting. @default 26 / 18 */
+    minGapX?: number;
+    minGapY?: number;
+    /** Force a level of detail; `"auto"` derives it from the fitted glyph size. @default "auto" */
+    lod?: LineageLod | "auto";
+    /**
+     * Caller-supplied "reachable" set. When present, nodes/edges **outside**
+     * it dim to `dimOpacity`. This is the controlled-dimming channel: the host
+     * computes the set (e.g. downstream BFS of the hovered node) and re-renders.
+     * Independent of, and composes with, `NetworkLayoutContext.selection`.
+     */
+    reachableIds?: Iterable<string> | null;
+    /** Currently-selected node id — drawn with the selection ring. Host-owned. */
+    selectedId?: string | null;
+    /** Opacity for dimmed (out-of-reach / unselected) marks. @default 0.14 */
+    dimOpacity?: number;
+    /** Logical layer index (0 = leftmost). @default "x" */
+    layerAccessor?: string;
+    /** Logical row offset within the layer (centered on 0). @default "y" */
+    rowAccessor?: string;
+    /** Node partition → fill family. @default "partition" */
+    partitionAccessor?: string;
+    /** Node semantic → icon. @default "semantic" */
+    semanticAccessor?: string;
+    /** Human label. @default "label" */
+    labelAccessor?: string;
+    /** Store list — `string[]` or `{storeName,slotIndex}[]`. @default "stores" */
+    storesAccessor?: string;
+    /** Edge "closes a cycle" flag. @default "isBackEdge" */
+    backEdgeAccessor?: string;
+    /** Edge type, drives edge color. @default "edgeType" */
+    edgeTypeAccessor?: string;
+    /** Fill per partition. Overridable; recipe ships dark-theme-friendly defaults. */
+    partitionColors?: Partial<Record<string, string>>;
+    /** Edge stroke per edgeType, plus `back` for back-edges. */
+    edgeColors?: Partial<Record<string, string>>;
+    /** Selection-ring stroke. @default var(--semiotic-focus, #ffcc33) */
+    accentColor?: string;
+    /** Container border stroke. @default var(--semiotic-border, #555) */
+    borderColor?: string;
+    /** Draw the store-slot chips in `full` LOD. @default true */
+    showStoreChips?: boolean;
+    /** Chip fill. @default var(--semiotic-info, #6a8caf) */
+    storeChipColor?: string;
+    /** Base edge opacity (non-dimmed). @default 0.5 */
+    edgeOpacity?: number;
+    /** Forward-edge stroke width in px. @default 1.25 */
+    edgeWidth?: number;
+    /** Back-edge stroke width in px. @default `edgeWidth`, else 1.5 */
+    backEdgeWidth?: number;
+    /**
+     * Render the per-node icon. Receives the resolved semantic/partition, the
+     * pixel size to draw within, and a color hint. Return any SVG node. When
+     * omitted a labelled fallback chip is drawn. The demo passes a KStreams
+     * icon set here — keeping the recipe domain-agnostic.
+     */
+    renderIcon?: (info: {
+        semantic: string;
+        partition: string;
+        size: number;
+        color: string;
+        node: Datum;
+    }) => ReactNode;
+    /** Small type label shown above the name in `full` LOD. @default the semantic. */
+    typeLabel?: (info: {
+        semantic: string;
+        partition: string;
+        node: Datum;
+    }) => string;
+}
+/**
+ * `lineageDagLayout` — a reusable layout recipe for **pre-positioned layered
+ * lineage / DAG graphs** with rich, composite node glyphs. Used here for the
+ * Kafka Streams topology viewer, but domain-agnostic: it reads logical
+ * `x` (layer) / `y` (row) coordinates the caller already computed (e.g. from a
+ * `dagLayoutFromGraph` pipeline) and maps them into the plot — it never runs a
+ * force sim or re-lays-out, so output is deterministic.
+ *
+ * **Composite glyphs as one hit-testable unit.** Each node emits exactly one
+ * `rect` (or `circle` in `dot` LOD) scene node — that single mark owns the
+ * canvas hit area and carries the node datum/id. All glyph chrome (semantic
+ * icon, type label, truncated name, per-store chips, selection ring) is drawn
+ * in the returned `overlays` layer, which is `pointer-events: none`, so it
+ * decorates without ever intercepting a hover. Hover/click therefore always
+ * resolve to the underlying node as a unit — see §5.2(a) of the spec.
+ *
+ * **Controlled dimming + selection, from outside.** `config.reachableIds`
+ * (host-computed set) dims everything outside it; `config.selectedId` draws
+ * the selection ring; both are owned by the host, never by the frame. The
+ * shared `NetworkLayoutContext.selection` predicate (from `LinkedCharts`)
+ * composes on top — a node dims if excluded by *either* cue.
+ *
+ * @example
+ * ```tsx
+ * import { NetworkCustomChart } from "semiotic/network"
+ * import { lineageDagLayout } from "semiotic/recipes"
+ *
+ * <NetworkCustomChart
+ *   nodes={dagNodes}   // each: { id, x: layer, y: row, partition, semantic, stores, label }
+ *   edges={dagEdges}   // each: { source, target, edgeType, isBackEdge }
+ *   layout={lineageDagLayout}
+ *   layoutConfig={{ layerCount, maxLayerSize, reachableIds, selectedId }}
+ * />
+ * ```
+ */
+export declare const lineageDagLayout: NetworkCustomLayout<LineageDagConfig>;

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

@@ -0,0 +1,44 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+/**
+ * Layered flowchart layout for the Mermaid adapter (and any pre-layered DAG).
+ *
+ * A Mermaid flowchart is a directed acyclic graph, not a force graph — so it
+ * should render as a *layered diagram* with shape-appropriate node glyphs,
+ * directional arrows, and edge labels, the way Mermaid draws it. This recipe
+ * does exactly that from the `layer`/`row` coordinates `fromMermaid` already
+ * computes (longest-path layering), so it needs **no layout engine and no new
+ * dependency**. It ships in `semiotic/recipes`, so it tree-shakes — you only
+ * pull it in if you use it.
+ *
+ * For large or dense graphs where crossing-minimization matters, run a real
+ * Sugiyama layouter (the BYO `dagre` recipe, or `d3-dag`) to assign
+ * `layer`/`row`, then render with this layout — the rendering and the
+ * positioning are deliberately separate concerns.
+ *
+ * Pure, SSR-safe: hit-testable rects are emitted as scene nodes; all visual
+ * chrome (shape glyphs, labels, edges, arrowheads, edge labels) is an SVG
+ * `overlays` group painted on top, in plot-relative coordinates.
+ */
+export type MermaidDirection = "TD" | "TB" | "BT" | "LR" | "RL";
+export interface MermaidDagConfig {
+    /** Flow direction. TD/TB top-down, BT bottom-up, LR left-right, RL right-left. @default "TD" */
+    direction?: MermaidDirection;
+    /** Glyph width / height in px (shrunk to fit). @default 150 / 46 */
+    nodeWidth?: number;
+    nodeHeight?: number;
+    /** Node field accessors. @default "layer" / "row" / "label" / "shape" */
+    layerAccessor?: string;
+    rowAccessor?: string;
+    labelAccessor?: string;
+    shapeAccessor?: string;
+    /** Edge label field. @default "label" */
+    edgeLabelAccessor?: string;
+    /** Colors (CSS vars by default so they follow the theme). */
+    nodeFill?: string;
+    nodeStroke?: string;
+    textColor?: string;
+    edgeColor?: string;
+    /** Stroke for decision (diamond) glyphs. */
+    accentColor?: string;
+}
+export declare const mermaidDagLayout: NetworkCustomLayout<MermaidDagConfig>;

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

@@ -0,0 +1,166 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { NetworkSymbolName } from "../stream/symbolPath";
+/**
+ * Config for {@link packedClusterMatrix}. Accessors read `node.data.<field>`
+ * (the ingest wrapper) and fall back to the node itself.
+ */
+export interface PackedClusterMatrixConfig {
+    /** Categorical field → matrix column. @default "column" */
+    columnAccessor?: string;
+    /** Categorical field → matrix row (stacked within a column). @default "row" */
+    rowAccessor?: string;
+    /** Numeric field → glyph size (area-encoded). Constant size when omitted. */
+    sizeAccessor?: string;
+    /** Categorical field → glyph hue (via `ctx.resolveColor`). */
+    colorAccessor?: string;
+    /** Fixed hue per category value. Wins over `ctx.resolveColor` for mapped keys —
+     *  the right choice for editorial graphics with a semantic palette. */
+    colorMap?: Record<string, string>;
+    /** Categorical field → glyph shape. Auto-assigned shapes when no `symbolMap`. */
+    symbolAccessor?: string;
+    /** Numeric/date field → lightness shade of the hue (the fourth channel). */
+    shadeAccessor?: string;
+    /** Boolean field → small center dot on the glyph (e.g. a flagged subset). */
+    markerAccessor?: string;
+    /** Explicit column order; otherwise columns sort by count, largest first. */
+    columnOrder?: string[];
+    /** Explicit row order **bottom→top**; otherwise rows sort by count, largest at bottom. */
+    rowOrder?: string[];
+    /** Map a class value to a named glyph (the base mark BECOMES that shape).
+     *  Unmapped values get auto-assigned. Mutually exclusive with `iconAccessor`. */
+    symbolMap?: Record<string, NetworkSymbolName>;
+    /** Shape when no `symbolAccessor` is set. @default "circle" */
+    defaultSymbol?: NetworkSymbolName;
+    /** Categorical field whose value selects an OPTIONAL stroked icon drawn inside
+     *  the (filled circle) base mark — the "most marks are plain circles, a few
+     *  carry an icon" model. Only values present in `iconMap` get an icon. */
+    iconAccessor?: string;
+    /** Map an icon-field value to a glyph. Values omitted here render as a plain
+     *  circle (no icon) — so a single dominant class stays unmarked. */
+    iconMap?: Record<string, NetworkSymbolName>;
+    /** Stroke color of the inner icon. @default "rgba(255,255,255,0.92)" */
+    iconColor?: string;
+    /** Inner-icon stroke width. @default 1 */
+    iconStrokeWidth?: number;
+    /** Inner-icon size as a fraction of the base circle radius. @default 0.72 */
+    iconScale?: number;
+    /** Glyph radius range in px (area = πr²). @default [2, 8] */
+    sizeRange?: [number, number];
+    /** Size value domain. @default data extent */
+    sizeDomain?: [number, number];
+    /** Cap total glyph area at this fraction of the plot; radii scale down to fit
+     *  (keeps clusters packable / non-overlapping on smaller canvases). @default 0.4 */
+    maxAreaFraction?: number;
+    /** How far the shade travels from the base hue (0..1). @default 0.72 */
+    shadeStrength?: number;
+    /** Shade value domain. @default data extent (dates auto-parsed) */
+    shadeDomain?: [number, number];
+    /** Flip the shade ramp (default: low → light, high → dark). */
+    shadeReverse?: boolean;
+    /** Row layout. `"banded"`: orbit rows are aligned global bands (one y-range
+     *  spanning all columns → row labels align, one enclosure per band spans the
+     *  columns, a column is only as tall as its highest occupied band). `"stacked"`:
+     *  each column stacks its own rows independently (cell height ∝ that column's
+     *  count; rows do NOT align). @default "banded" */
+    rowMode?: "banded" | "stacked";
+    /** `"proportional"` (mosaic: cell area ∝ count) or `"uniform"` grid. @default "proportional" */
+    cellSizing?: "proportional" | "uniform";
+    /** Exponent applied to counts when sizing columns/cells. `1` = strict area ∝
+     *  count; `<1` softens the range so small columns stay legible. @default 1 */
+    proportionExponent?: number;
+    /** Gap between columns in px. @default 16 */
+    columnGap?: number;
+    /** Gap between stacked cells in px. @default 12 */
+    rowGap?: number;
+    /** Collision padding between glyphs in px. @default 1 */
+    packPadding?: number;
+    /** Relaxation passes for the packing (capped at 14; a near-uniform seed needs
+     *  few). Higher = tidier/slower. @default 12 */
+    iterations?: number;
+    /** Draw a rounded enclosure hugging each cluster. @default true */
+    showEnclosures?: boolean;
+    enclosureColor?: string;
+    enclosureRadius?: number;
+    enclosureOpacity?: number;
+    enclosureWidth?: number;
+    /** Column header labels across the top. @default true */
+    showColumnHeaders?: boolean;
+    /** Row labels down the left. @default true */
+    showRowLabels?: boolean;
+    columnLabel?: (col: string) => string;
+    rowLabel?: (row: string) => string;
+    headerColor?: string;
+    labelColor?: string;
+    headerFontSize?: number;
+    labelFontSize?: number;
+    /** Top space reserved for headers. @default 26 */
+    headerHeight?: number;
+    /** Left space reserved for row labels. @default 66 */
+    labelWidth?: number;
+    /** Bottom margin reserved for callout labels (only when `callouts` is set). @default 30 */
+    footerHeight?: number;
+    markStroke?: string;
+    markStrokeWidth?: number;
+    /** Center-dot color for `markerAccessor` hits. @default "#ffffff" */
+    markerColor?: string;
+    /** Dim every glyph that doesn't match the highlight. A single `{field,value}`
+     *  or an array (AND — a glyph must match all to stay lit, e.g. a region×orbit
+     *  cell). Drives legend / nav-tree highlighting. */
+    highlight?: {
+        field: string;
+        value: string;
+    } | {
+        field: string;
+        value: string;
+    }[] | null;
+    /** Opacity for dimmed glyphs. @default 0.16 */
+    dimOpacity?: number;
+    /** Editorial leader-line callouts to specific marks. Each picks the first mark
+     *  whose `datum[field] === value` and draws a ring + connector + label. `at`
+     *  places the label: a y in [0,1] of the plot ("1" = bottom) and the label
+     *  tracks the mark's x, or an explicit `{x,y}` in plot px. */
+    callouts?: Array<{
+        field: string;
+        value: string;
+        label: string;
+        at?: number | {
+            x: number;
+            y: number;
+        };
+        connector?: "straight" | "elbow" | "curve";
+    }>;
+    calloutColor?: string;
+}
+/**
+ * `packedClusterMatrix` — a reusable network layout that arranges a flat set of
+ * records into a **matrix of densely-packed clusters**: one column per value of
+ * `columnAccessor`, cells stacked within a column per value of `rowAccessor`,
+ * each cell a beeswarm of variable-radius glyphs. In `"proportional"` sizing the
+ * column widths and cell heights track counts (a mosaic), so a cell's area is
+ * proportional to its record count and packing density stays roughly uniform.
+ *
+ * Each record renders as a **four-channel glyph**: shape (`symbolAccessor`),
+ * hue (`colorAccessor`), size (`sizeAccessor`, area-encoded), and lightness
+ * shade (`shadeAccessor`). Packing is deterministic (seeded `d3-force`) and the
+ * geometry is cached, so hover/selection/filter re-runs re-style without
+ * re-packing. Built to recreate small-multiples beeswarm graphics (e.g. Nadieh
+ * Bremer's "Satellites in Space").
+ *
+ * @example
+ * ```tsx
+ * import { NetworkCustomChart } from "semiotic/network"
+ * import { packedClusterMatrix } from "semiotic/recipes"
+ *
+ * <NetworkCustomChart
+ *   nodes={satellites}            // each: { id, region, orbit, mass, category, klass, launch }
+ *   layout={packedClusterMatrix}
+ *   colorScheme={categoryColors}
+ *   layoutConfig={{
+ *     columnAccessor: "region", rowAccessor: "orbit",
+ *     sizeAccessor: "mass", colorAccessor: "category",
+ *     symbolAccessor: "klass", shadeAccessor: "launch",
+ *   }}
+ * />
+ * ```
+ */
+export declare const packedClusterMatrix: NetworkCustomLayout<PackedClusterMatrixConfig>;

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

@@ -0,0 +1,100 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * Recipe chrome kit — small, framework-level building blocks for the decoration
+ * that custom-layout recipes draw in their `overlays` layer: group enclosures,
+ * band/axis labels, and leader-line callouts to a mark.
+ *
+ * These were each hand-rolled per recipe (packedClusterMatrix drew enclosures,
+ * marimekko/bullet/parallelCoordinates placed band labels, the satellites
+ * graphic needed callouts to specific marks). Centralizing them keeps chrome
+ * consistent and lets new recipes opt in instead of re-deriving the geometry.
+ *
+ * All return plain SVG React elements with `pointerEvents: "none"`, so they
+ * decorate without intercepting canvas hit-testing. Pure / SSR-safe.
+ */
+export interface RoundedEnclosureProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Corner radius. @default 10 */
+    radius?: number;
+    stroke?: string;
+    /** @default 1.5 */
+    strokeWidth?: number;
+    /** @default 0.6 */
+    opacity?: number;
+    /** @default "none" */
+    fill?: string;
+    strokeDasharray?: string;
+    className?: string;
+    keyId?: string | number;
+}
+/** A rounded rectangle around a group of marks (a cell, a row/column band, a cluster). */
+export declare function roundedEnclosure(p: RoundedEnclosureProps): ReactElement;
+/** Bounding box of a set of points (each optionally a circle of radius `r`), padded.
+ *  The usual precursor to {@link roundedEnclosure}. Returns null for an empty set. */
+export declare function boundsOf(points: ReadonlyArray<{
+    x: number;
+    y: number;
+    r?: number;
+}>, pad?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export interface BandLabelProps {
+    text: string;
+    x: number;
+    y: number;
+    /** @default "middle" */
+    anchor?: "start" | "middle" | "end";
+    /** @default "middle" */
+    baseline?: "middle" | "hanging" | "auto";
+    /** Hide the label if its estimated width exceeds this (px). */
+    maxWidth?: number;
+    /** @default 12 */
+    fontSize?: number;
+    fontWeight?: number | string;
+    color?: string;
+    className?: string;
+    keyId?: string | number;
+}
+/** A label placed at a band/axis position, suppressed when it would overflow
+ *  `maxWidth` (the dedup pattern marimekko/parallelCoordinates hand-roll). */
+export declare function bandLabel(p: BandLabelProps): ReactElement | null;
+export type CalloutConnector = "straight" | "elbow" | "curve";
+export interface MarkCalloutProps {
+    /** The anchored mark (a position a custom layout emitted). */
+    markX: number;
+    markY: number;
+    /** Where the label text sits. */
+    labelX: number;
+    labelY: number;
+    label: ReactNode;
+    /** @default "straight" */
+    connector?: CalloutConnector;
+    /** Draw a ring of this radius around the mark (editorial highlight). */
+    markRadius?: number;
+    stroke?: string;
+    /** @default 1 */
+    strokeWidth?: number;
+    color?: string;
+    /** @default 11 */
+    fontSize?: number;
+    fontWeight?: number | string;
+    /** text-anchor for the label. @default "middle" */
+    labelAnchor?: "start" | "middle" | "end";
+    /** @default "hanging" */
+    labelBaseline?: "middle" | "hanging" | "auto";
+    className?: string;
+    keyId?: string | number;
+}
+/**
+ * A leader line connecting a label to a mark, with an optional ring around the
+ * mark — the editorial-callout pattern. Custom-layout recipes use it because
+ * the annotation system can't anchor to a mark a layout emits at runtime; the
+ * recipe knows the packed position and can call this directly.
+ */
+export declare function markCallout(p: MarkCalloutProps): ReactElement;