semiotic 3.7.5 → 3.8.0

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

@@ -0,0 +1,67 @@
+/**
+ * Process-physics chrome kit — stage bays, capacity badges, absorb basins,
+ * feature sockets, and flow spines for ProcessFlow / custom process layouts.
+ *
+ * Theme via CSS vars (with solid fallbacks so chrome never goes blank):
+ *   --semiotic-process-floor, --semiotic-process-lane, --semiotic-process-border
+ *   --semiotic-process-text, --semiotic-process-muted
+ *   --semiotic-success / warning / danger / info for semantic stage roles
+ */
+import * as React from "react";
+export interface ProcessChromeStage {
+    id: string;
+    label: string;
+    x0: number;
+    x1: number;
+    x: number;
+    width: number;
+    count?: number;
+    capacity?: number;
+    /** Reader-facing capacity badge; defaults to the numeric `cap` label. */
+    capacityLabel?: string;
+    /** Override stage badges without hiding capacity badges across the layout. */
+    showBadge?: boolean;
+    absorb?: boolean;
+    portalTarget?: string;
+    queueDepth?: number;
+    processed?: number;
+}
+export interface ProcessChromeGroup {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+    absorbed?: number;
+    total?: number;
+    complete?: boolean;
+}
+export interface ProcessChromeLayout {
+    width: number;
+    height: number;
+    left: number;
+    right: number;
+    topY: number;
+    bottomY: number;
+    midY: number;
+    stages: readonly ProcessChromeStage[];
+    groups?: readonly ProcessChromeGroup[];
+}
+export interface ProcessChromeOptions {
+    showFlowSpine?: boolean;
+    showStageCounts?: boolean;
+    showCapacityBadges?: boolean;
+    showGroupSockets?: boolean;
+    /** Fit stage labels to the stage band instead of drawing fixed-width pills. */
+    stageLabelMode?: "auto" | "full" | "compact" | "none";
+    /**
+     * When true, stage bays are stroke-only (transparent fill) so particles
+     * and paired charts remain visible through the gate geometry.
+     */
+    outlineStages?: boolean;
+    testId?: string;
+}
+/**
+ * SVG process chrome for overlays / backgroundGraphics.
+ * Pure presentational — call from ProcessFlowChart or PhysicsCustomChart.
+ */
+export declare function processChrome(layout: ProcessChromeLayout, options?: ProcessChromeOptions): React.ReactElement;

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

@@ -0,0 +1,54 @@
+/**
+ * Serializable stage-journey state derived from physics region events.
+ *
+ * Keep this reducer independent from a live physics runtime so authors can
+ * replay, compare, persist, and project the same event stream deterministically.
+ */
+import type { StreamPhysicsRegionEvent } from "../stream/physics/StreamPhysicsFrame";
+export interface ProcessJourneyStage {
+    id: string;
+    label?: string;
+}
+export interface ProcessJourneyEntityState {
+    id: string;
+    currentStageId?: string;
+    furthestStageId?: string;
+    furthestStageIndex: number;
+    visitedStageIds: string[];
+    visitsByStage: Record<string, number>;
+    firstEnteredAt: Record<string, number>;
+    lastEnteredAt: Record<string, number>;
+    regressionCount: number;
+}
+export interface ProcessJourneyLedger {
+    stages: ProcessJourneyStage[];
+    bodyIds: string[];
+    entities: Record<string, ProcessJourneyEntityState>;
+}
+type ProcessJourneyRegionEvent = Pick<StreamPhysicsRegionEvent, "bodyId" | "datum" | "region">;
+export interface ProcessJourneyUpdateOptions {
+    entityId?: (event: ProcessJourneyRegionEvent) => string;
+    stageId?: (event: ProcessJourneyRegionEvent) => string | undefined;
+}
+export interface ProcessJourneyRow {
+    id: string;
+    label: string;
+    reached: number;
+    entered: number;
+    total: number;
+    conversion: number;
+    fromPrevious: number;
+    dropoff: number;
+    visits: number;
+    repeatVisits: number;
+}
+/** Create serializable journey state for a known or initially empty cohort. */
+export declare function createProcessJourneyLedger(options: {
+    stages: readonly ProcessJourneyStage[];
+    bodyIds?: readonly string[];
+}): ProcessJourneyLedger;
+/** Reduce a stage-region enter into unique reach and visit-aware entity state. */
+export declare function updateProcessJourney(previous: ProcessJourneyLedger, event: Pick<StreamPhysicsRegionEvent, "type" | "bodyId" | "datum" | "observation" | "region">, options?: ProcessJourneyUpdateOptions): ProcessJourneyLedger;
+/** Convert a live journey ledger into stable stage reach and conversion rows. */
+export declare function processJourneyRows(ledger: ProcessJourneyLedger): ProcessJourneyRow[];
+export {};

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

@@ -0,0 +1,300 @@
+/**
+ * Process-physics authoring kit.
+ *
+ * Pure helpers that turn stage / membrane / route / capacity *declarations*
+ * into colliders, regionEffects, body-group specs, and settled-projection
+ * rows — the recurring geometry that process demos (stakeholder journey,
+ * merge pressure, gauntlets) otherwise re-derive by hand.
+ *
+ * Use with StreamPhysicsFrame / PhysicsCustomChart / ProcessFlow HOCs.
+ * Dynamics stay on the frame; these functions only emit declarative specs.
+ */
+import type { PhysicsColliderBodyFilter, PhysicsColliderSpec } from "../stream/physics/PhysicsKernel";
+import type { PhysicsSemanticItem, StreamPhysicsRegionEffect, StreamPhysicsRegionKind, StreamPhysicsRegionVector } from "../stream/physics/StreamPhysicsFrame";
+import type { Style } from "../stream/types";
+import type { Datum } from "../charts/shared/datumTypes";
+export type ProcessVolumeShape = "lane" | "bowtie" | "funnel";
+export interface ProcessStageDef {
+    id: string;
+    label?: string;
+    description?: string;
+    /** Relative width share. Defaults to equal shares. */
+    share?: number;
+    kind?: StreamPhysicsRegionKind | string;
+}
+export interface ProcessMembraneDef {
+    id: string;
+    label?: string;
+    description?: string;
+    /**
+     * Position along the process axis as a fraction of the left approach
+     * (bowtie) or full width (lane/funnel). 0 = start, 1 = end of that span.
+     */
+    offset: number;
+    /** 0–1 cost: maps to damping and energyDelta. */
+    cost: number;
+    /** Vertical center offset in plot px (visual wobble). */
+    wobble?: number;
+    color?: string;
+    /** Override membrane band width in px. */
+    width?: number;
+    dampingScale?: number;
+    bodyStyle?: Style;
+    metadata?: unknown;
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+}
+export interface ProcessVolumeLayoutOptions {
+    width: number;
+    height: number;
+    stages: readonly ProcessStageDef[];
+    shape?: ProcessVolumeShape;
+    padX?: number;
+    padY?: number;
+    /**
+     * Bowtie: vertical pinch height as a fraction of usable height
+     * (default 0.18). Lane ignores this.
+     */
+    pinchRatio?: number;
+    /**
+     * Plot-pixel offset added to the ratio-derived pinch height. Recompute the
+     * layout with a live metric here to move bowtie/funnel walls and boundaries
+     * as one. Lane geometry is unaffected.
+     */
+    pinchHeightOffset?: number;
+    /**
+     * Bowtie: which stage index is the center "pinch" band
+     * (default: middle stage).
+     */
+    centerStageIndex?: number;
+    membranes?: readonly ProcessMembraneDef[];
+    idPrefix?: string;
+    friction?: number;
+    restitution?: number;
+    wallThickness?: number;
+    /**
+     * When true (default), membrane regionEffects are included on the layout.
+     * Force fields / charge gates / portals are composed separately.
+     */
+    includeMembraneRegions?: boolean;
+    membraneDampingScale?: number;
+}
+export interface ProcessVolumeStageBand {
+    id: string;
+    label?: string;
+    description?: string;
+    kind?: StreamPhysicsRegionKind | string;
+    index: number;
+    x0: number;
+    x1: number;
+    /** Center x of the stage band. */
+    x: number;
+    width: number;
+    /** Center y of the stage slice's axis-aligned physical envelope. */
+    y: number;
+    /** Height of the stage slice's axis-aligned physical envelope. */
+    height: number;
+}
+export interface ProcessVolumeMembraneBand extends ProcessMembraneDef {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ProcessVolumeLayout {
+    shape: ProcessVolumeShape;
+    width: number;
+    height: number;
+    padX: number;
+    padY: number;
+    left: number;
+    right: number;
+    topY: number;
+    bottomY: number;
+    midY: number;
+    centerLeft: number;
+    centerRight: number;
+    /** Resolved interior height of the bowtie/funnel pinch in plot pixels. */
+    pinchHeight: number;
+    pinchTop: number;
+    pinchBottom: number;
+    stages: ProcessVolumeStageBand[];
+    membranes: ProcessVolumeMembraneBand[];
+    colliders: PhysicsColliderSpec[];
+    regionEffects: StreamPhysicsRegionEffect[];
+    /** Interior height of the volume at x (top/bottom boundary). */
+    boundaryY: (x: number, side: "top" | "bottom") => number;
+}
+/**
+ * Build a horizontal process volume: stage bands, optional membranes, and
+ * shape-specific wall colliders (`lane` | `bowtie` | `funnel`).
+ */
+export declare function processStageLayout(options: ProcessVolumeLayoutOptions): ProcessVolumeLayout;
+export interface ProcessRegionBaseOptions {
+    id: string;
+    label?: string;
+    description?: string;
+    kind?: StreamPhysicsRegionKind;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    bodyFilter?: PhysicsColliderBodyFilter;
+    collider?: StreamPhysicsRegionEffect["collider"];
+    colliderThickness?: number;
+    friction?: number;
+    restitution?: number;
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+    metadata?: unknown;
+    bodyStyle?: Style;
+    attributes?: StreamPhysicsRegionEffect["attributes"];
+    onEnter?: StreamPhysicsRegionEffect["onEnter"];
+    onExit?: StreamPhysicsRegionEffect["onExit"];
+}
+export interface ProcessStageRegionOptions {
+    /** Region ids become `${idPrefix}:${stageId}`. Defaults to `stage`. */
+    idPrefix?: string;
+    insetX?: number;
+    insetY?: number;
+    bodyFilter?: PhysicsColliderBodyFilter;
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+    metadata?: Record<string, unknown> | ((stage: ProcessVolumeStageBand) => Record<string, unknown>);
+}
+/** Build one observation region from every stage's physical envelope. */
+export declare function processStageRegions(layout: ProcessVolumeLayout, options?: ProcessStageRegionOptions): StreamPhysicsRegionEffect[];
+/** Permeable information membrane: damps and taxes energy, does not block. */
+export declare function membraneRegion(options: ProcessRegionBaseOptions & {
+    cost: number;
+    dampingScale?: number;
+    energyScale?: number;
+    color?: string;
+}): StreamPhysicsRegionEffect;
+/** Charge gate: stamps charge/energy when a body enters. */
+export declare function chargeGateRegion(options: ProcessRegionBaseOptions & {
+    charge?: StreamPhysicsRegionEffect["charge"];
+    energyDelta?: number;
+    impulseOnEnter?: StreamPhysicsRegionVector;
+}): StreamPhysicsRegionEffect;
+/** Conveyor / route surface: continuous force while overlapping. */
+export declare function routeSurfaceRegion(options: ProcessRegionBaseOptions & {
+    force?: StreamPhysicsRegionVector | number;
+    damping?: number;
+}): StreamPhysicsRegionEffect;
+/**
+ * Pressure field: drag rises with occupancy (or a precomputed pressure).
+ * For live occupancy coupling, pass `occupancy` each rebuild or a force
+ * function via the frame's regionEffects after counting active bodies.
+ */
+export declare function pressureFieldRegion(options: ProcessRegionBaseOptions & {
+    /** Occupancy or precomputed pressure scalar. */
+    pressure?: number;
+    occupancy?: number;
+    baseDamping?: number;
+    dampingPerUnit?: number;
+    energyPerUnit?: number;
+    force?: StreamPhysicsRegionVector;
+}): StreamPhysicsRegionEffect;
+/**
+ * Capacitated stage region: marks capacity metadata and optional force/damping.
+ * Pair with `createCapacityQueueController({ regionId })` (or ProcessFlowChart
+ * `liveCapacity`) for a live FIFO queue that drains at unitsPerSecond.
+ */
+export declare function capacitatedRegion(options: ProcessRegionBaseOptions & {
+    capacity: number;
+    unitsPerSecond?: number;
+    force?: StreamPhysicsRegionVector | number;
+    damping?: number;
+    charge?: StreamPhysicsRegionEffect["charge"];
+}): StreamPhysicsRegionEffect;
+/** Portal / rework loop: impulse or force that redirects bodies. */
+export declare function portalRegion(options: ProcessRegionBaseOptions & {
+    force?: StreamPhysicsRegionVector;
+    impulseOnEnter?: StreamPhysicsRegionVector;
+    damping?: number;
+    targetStage?: string;
+}): StreamPhysicsRegionEffect;
+/** Absorbing sink (merge basin, completion socket). */
+export declare function absorbRegion(options: ProcessRegionBaseOptions & {
+    force?: StreamPhysicsRegionVector | number;
+    damping?: number;
+    charge?: StreamPhysicsRegionEffect["charge"];
+}): StreamPhysicsRegionEffect;
+/** Generic force field (commitment, leadership, etc.). */
+export declare function forceFieldRegion(options: ProcessRegionBaseOptions & {
+    force?: StreamPhysicsRegionVector;
+    damping?: number;
+    energyDelta?: number;
+}): StreamPhysicsRegionEffect;
+export interface BodyGroupSpecOptions<TDatum extends Datum = Datum> {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    bodyIds?: readonly string[];
+    datum?: TDatum;
+    state?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** Anchor point for tethers / chrome. */
+    anchor?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Completion rule consumed by `groupCompletionRows` and available to
+     * ProcessFlow / custom controllers as group metadata.
+     */
+    completion?: {
+        mode: "allMembersAbsorbed" | "anyAbsorbed" | "threshold";
+        targetZone?: string;
+        /** Required absorbed member value when mode is `threshold`. */
+        threshold?: number;
+        /**
+         * Optional per-member values used by threshold completion and progress
+         * readouts. Members without an entry have value 1.
+         */
+        valueByBodyId?: Readonly<Record<string, number>>;
+    };
+    tether?: {
+        stiffness?: number;
+        visible?: boolean;
+        restLength?: number;
+    };
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+}
+export interface BodyGroupSpec<TDatum extends Datum = Datum> {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    bodyIds?: readonly string[];
+    datum?: TDatum;
+    state?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+    completion?: BodyGroupSpecOptions<TDatum>["completion"];
+    tether?: BodyGroupSpecOptions<TDatum>["tether"];
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+}
+export declare function bodyGroupSpec<TDatum extends Datum = Datum>(options: BodyGroupSpecOptions<TDatum>): BodyGroupSpec<TDatum>;
+export declare function processLaneWalls(options: {
+    idPrefix?: string;
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    friction?: number;
+    restitution?: number;
+    thickness?: number;
+    openEnds?: boolean;
+}): PhysicsColliderSpec[];
+export { aggregateRegionCounts, groupCompletionRows, regionCountsToProjectionRows } from "./processAggregates";
+export type { RegionCountBucket, RegionCountMap } from "./processAggregates";
+export { stageTargetInVolume } from "./processVolumeGeometry";

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

@@ -0,0 +1,28 @@
+/** Renderable polygons derived from the same geometry as process barriers. */
+import type { ProcessVolumeLayout } from "./processPhysics";
+export type ProcessVolumePoint = [x: number, y: number];
+export type ProcessVolumePolygonRole = "volume" | "incoming" | "center" | "outgoing";
+export interface ProcessVolumePolygon {
+    id: ProcessVolumePolygonRole;
+    role: ProcessVolumePolygonRole;
+    /** Clockwise points suitable for SVG, Canvas, or custom mark renderers. */
+    points: ProcessVolumePoint[];
+}
+/** Sample a spawn or spring target inside a stage and its physical walls. */
+export declare function stageTargetInVolume(layout: ProcessVolumeLayout, stageId: string, options?: {
+    random?: () => number;
+    /** Horizontal position inside the stage as 0–1 (default 0.5). */
+    along?: number;
+    jitterX?: number;
+    padY?: number;
+}): {
+    x: number;
+    y: number;
+};
+/**
+ * Derive visible process panels from a processStageLayout result.
+ *
+ * The returned edges share coordinates with the layout's physical wall
+ * colliders, keeping rendered boundaries and collision geometry synchronized.
+ */
+export declare function processVolumePolygons(layout: ProcessVolumeLayout): ProcessVolumePolygon[];

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

@@ -0,0 +1,69 @@
+/**
+ * Radial coordinate kit — the angle ⟂ radius primitives a bespoke radial chart
+ * needs when it encodes *two independent continuous channels* (angle = one
+ * field, radius = another) and so can't use a built-in band-and-radius radial
+ * scale. The radial analogue of the `bandLabel` / `roundedEnclosure` chrome kit.
+ *
+ * Pure / SSR-safe, dependency-free (no d3-scale / d3-shape, to keep the recipes
+ * bundle lean). Complements the `radialGeometry` helpers in `semiotic/utils`
+ * (`sweepToAngles` / `valueToAngle`) which target gauge-style single-value arcs.
+ *
+ * **Angle convention:** `0` points up (12 o'clock); angle increases **clockwise**
+ * (the d3-pie / d3-arc convention). Angles are in **radians**. This matches the
+ * SVG renderer and reads naturally for day-of-year / clock / compass charts.
+ */
+/** One full turn in radians. */
+export declare const TAU: number;
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface PolarOptions {
+    /** Center of the polar system in plot coordinates. @default `{ x: 0, y: 0 }`
+     *  (radial ordinal layouts are already center-translated). */
+    center?: Point;
+}
+/**
+ * Convert a polar `(angle, radius)` to Cartesian `(x, y)` in the kit's
+ * convention (0 = up, clockwise). Inverse of {@link xyToAngle}.
+ */
+export declare function polarToXY(angle: number, radius: number, opts?: PolarOptions): Point;
+/**
+ * The angle (radians, 0 = up, clockwise, range `[0, TAU)`) of a point relative
+ * to the center — the inverse of {@link polarToXY}, for turning a pointer
+ * position into a domain value (e.g. a circular brush handle drag).
+ */
+export declare function xyToAngle(x: number, y: number, opts?: PolarOptions): number;
+export interface AngleScaleOptions {
+    /** Angle (radians) at the domain start. @default 0 (up) */
+    startAngle?: number;
+    /** Angle (radians) at the domain end. @default {@link TAU} (full clockwise turn) */
+    endAngle?: number;
+}
+/**
+ * A linear scale from a data domain to angles (radians). The continuous-angle
+ * companion to a band scale: `angleScale([0, 365])` maps day-of-year to a full
+ * clockwise turn from the top.
+ */
+export declare function angleScale(domain: readonly [number, number], opts?: AngleScaleOptions): (value: number) => number;
+/**
+ * A linear scale from a data domain to a pixel radius range. The radial analogue
+ * of a y-scale: `radiusScale([-10, 110], [0, 180])` maps temperature to radius.
+ */
+export declare function radiusScale(domain: readonly [number, number], range: readonly [number, number]): (value: number) => number;
+export type RingArcOptions = PolarOptions;
+/**
+ * SVG path string for an **annular sector** (a ring arc) between two angles and
+ * two radii — the radial bar / brush-arc / envelope-band primitive the radial
+ * examples hand-rolled with `d3.arc`. Angles in the kit convention (0 = up,
+ * clockwise, radians). Handles three cases:
+ *
+ *   - `innerRadius <= 0` → a pie wedge (lines to center).
+ *   - a full turn (`|endAngle − startAngle| ≥ TAU`) → a complete ring/annulus
+ *     (drawn as two half-arcs so SVG can render the closed loop).
+ *   - otherwise → a standard annular sector.
+ *
+ * For a clean ring pass `startAngle < endAngle` (clockwise). A wrap-around range
+ * (e.g. a brush from day 350→20) should be split into two calls by the caller.
+ */
+export declare function ringArcPath(startAngle: number, endAngle: number, innerRadius: number, outerRadius: number, opts?: RingArcOptions): string;

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

@@ -0,0 +1,2 @@
+/** Deterministic PRNG (mulberry32). Returns a function yielding [0, 1). */
+export declare function mulberry32(seed: number): () => number;

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

@@ -64,6 +64,97 @@ export interface BandLabelProps {
 /** 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 interface HatchFillOptions {
+    /** Unique pattern id, referenced by the returned `fill`. */
+    id: string;
+    /** Line color. @default "currentColor" */
+    color?: string;
+    /** Hatch angle in degrees. @default 45 */
+    angle?: number;
+    /** Spacing between lines, px. @default 8 */
+    spacing?: number;
+    /** Line width, px. @default 1 */
+    strokeWidth?: number;
+    /** Line opacity. @default 0.5 */
+    opacity?: number;
+}
+/**
+ * A diagonal-hatch SVG fill — for percentile envelopes, uncertainty bands, and
+ * "projected/estimated" regions. Returns a `<pattern>` `def` to drop in (any
+ * `<defs>`, or anywhere in the SVG tree) and a `fill` URL referencing it, so the
+ * chart band and a {@link legendSwatches} hatch swatch read identically instead
+ * of each hand-rolling a `<pattern>` (the per-example drift this removes).
+ *
+ * The SVG analogue of the canvas `createHatchPattern` (`semiotic/utils`); use
+ * this for SVG overlays / `foregroundGraphics`, that one for canvas pieceStyle.
+ *
+ * @example
+ * ```ts
+ * const hatch = hatchFill({ id: "envelope", color: "var(--semiotic-text-secondary)" })
+ * // <>{hatch.def}<path d={bandPath} fill={hatch.fill} /></>
+ * ```
+ */
+export declare function hatchFill(opts: HatchFillOptions): {
+    def: ReactElement;
+    fill: string;
+};
+export type AxisOrient = "bottom" | "top" | "left" | "right";
+export interface LinearAxisProps {
+    /** Value → pixel along the axis. Pass any scale function — a `radiusScale`,
+     *  a d3 scale, or an inline `(v) => (v - d0) / (d1 - d0) * width`. */
+    scale: (value: number) => number;
+    /** The tick values to draw. */
+    ticks: number[];
+    /** Axis side. `bottom`/`top` run horizontally (ticks vary x); `left`/`right`
+     *  run vertically (ticks vary y). @default "bottom" */
+    orient?: AxisOrient;
+    /** Cross-axis position of the axis line — the `y` for a horizontal axis, the
+     *  `x` for a vertical one. @default 0 */
+    offset?: number;
+    /** Tick-mark length (px), drawn outward from the axis toward the labels.
+     *  `0` draws labels with no tick marks (the bare year-axis case). @default 6 */
+    tickLength?: number;
+    /** Extend each tick *into* the plot as a gridline of this length (px). The
+     *  tick + gridline render as one continuous line. @default 0 */
+    gridLength?: number;
+    /** Dash pattern for the gridline portion (e.g. `"3 5"`). */
+    gridDasharray?: string;
+    /** Format a tick value for its label. @default `String` */
+    format?: (v: number) => string;
+    /** @default 11 */
+    fontSize?: number;
+    fontWeight?: number | string;
+    /** Tick + label color. @default "var(--semiotic-text-secondary, #888)" */
+    color?: string;
+    /** Gridline color, if different from `color`. */
+    gridColor?: string;
+    /** Gap between a tick's end and its label (px). @default 4 */
+    labelGap?: number;
+    /** Override label `text-anchor`. Defaults follow `orient`. */
+    labelAnchor?: "start" | "middle" | "end";
+    /** Anchor the first tick label `start` and the last `end` so edge labels stay
+     *  inside the plot (pairs with `axisExtent="exact"`). Horizontal axes only.
+     *  @default false */
+    edgeAnchor?: boolean;
+    className?: string;
+    keyId?: string | number;
+}
+/**
+ * A linear tick axis drawn from *any* scale, for custom-layout `overlays` — the
+ * bespoke-scale escape hatch for axes (the built-in `showAxes` only works for
+ * layouts that respect the standard scale). Sibling to {@link bandLabel}: emits
+ * tick marks, optional gridlines, and labels as `pointerEvents: "none"` SVG.
+ *
+ * @example a top time-axis with gridlines running down the plot
+ * ```ts
+ * linearAxis({
+ *   scale: (year) => ((year - 1775) / (2015 - 1775)) * plot.width,
+ *   ticks: [1800, 1850, 1900, 1950, 2000],
+ *   orient: "top", gridLength: plot.height, gridDasharray: "3 5", edgeAnchor: true,
+ * })
+ * ```
+ */
+export declare function linearAxis(p: LinearAxisProps): ReactElement;
 export type CalloutConnector = "straight" | "elbow" | "curve";
 export interface MarkCalloutProps {
     /** The anchored mark (a position a custom layout emitted). */

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

@@ -0,0 +1,42 @@
+import * as React from "react";
+import type { GlyphDef } from "../stream/glyphDef";
+/**
+ * `<Glyph>` — render a {@link GlyphDef} as plain SVG.
+ *
+ * The React face of the composite-pictogram system: the same definition a
+ * custom layout stamps as `glyph` scene nodes (canvas + SSR) renders here for
+ * everything that lives in JSX — overlay chrome, `legendSwatches`-style keys,
+ * recipe icon callbacks (e.g. `lineageDagLayout`'s `renderIcon`), and page
+ * furniture. One definition, three surfaces, no drift.
+ *
+ * Positioning is deliberately chrome-shaped: the definition's **top-left**
+ * corner lands at (`x`, `y`) and `size` is the rendered height (width follows
+ * the viewBox aspect). The definition's `anchor` is a scene-node concern —
+ * layouts use it to stand signs on baselines — and is ignored here, where the
+ * caller owns placement.
+ */
+export interface GlyphProps {
+    def: GlyphDef;
+    /** Rendered height in px; width follows the definition's viewBox aspect. @default 24 */
+    size?: number;
+    /** Primary paint for parts declaring `"color"`. @default "currentColor" */
+    color?: string;
+    /** Accent paint for parts declaring `"accent"`. @default "#ffffff" */
+    accent?: string;
+    /** Partial fill 0–1 — pair with the `unitize` recipe's `fraction`. @default 1 */
+    fraction?: number;
+    /** Where the partial fill begins, 0–1 (range boundary signs). @default 0 */
+    fractionStart?: number;
+    /** Partial-fill axis. @default "horizontal" */
+    fractionDirection?: "horizontal" | "vertical";
+    /** Ghost paint drawn at full extent beneath a partial fill so the whole
+     *  sign stays countable. */
+    ghostColor?: string;
+    /** Top-left x of the definition box in the parent SVG. @default 0 */
+    x?: number;
+    /** Top-left y of the definition box in the parent SVG. @default 0 */
+    y?: number;
+    opacity?: number;
+    className?: string;
+}
+export declare function Glyph({ def, size, color, accent, fraction, fractionStart, fractionDirection, ghostColor, x, y, opacity, className, }: GlyphProps): React.ReactElement | null;