semiotic 3.7.5 → 3.8.1

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

@@ -51,6 +51,13 @@ export interface AnnotationLayoutConfig {
     responsive?: boolean | {
         minWidth?: number;
     };
+    /**
+     * Mobile annotation policy. This composes the existing responsive + density +
+     * progressive-disclosure passes into a phone-friendly default: keep the core
+     * notes persistent, collapse secondary notes, and prefer short/mobile copy
+     * when provided. Off by default.
+     */
+    mobile?: boolean | AnnotationMobileConfig;
     /**
      * M5 — cohesion mode (Rahman et al.'s "Cohesion"). `"blended"` lets notes
      * adopt the chart's visual language (mark colors / chart typography — the
@@ -69,6 +76,28 @@ export interface AnnotationLayoutConfig {
     audience?: AnnotationAudience;
 }
 export type AnnotationCohesion = "blended" | "layer";
+export interface AnnotationMobileConfig {
+    /** Width at or below which mobile behavior activates. Default 480px. */
+    breakpoint?: number;
+    /** Plot-only, callout-list, or hybrid mobile note behavior. */
+    strategy?: "plot" | "callout-list" | "hybrid";
+    /** Max persistent notes at phone width. Default 2. */
+    maxAnnotations?: number;
+    /** Maximum notes expected to move into an external mobile callout list. */
+    maxCalloutItems?: number;
+    /** Minimum notes kept regardless of budget. Default 1. */
+    minVisible?: number;
+    /** Keep shed notes hidden/revealable rather than dropping them. Default true. */
+    progressiveDisclosure?: boolean;
+    /** Responsive breakpoint override. Defaults to `breakpoint`. */
+    responsive?: boolean | {
+        minWidth?: number;
+    };
+    /** Annotation cohesion to apply at phone width. */
+    cohesion?: AnnotationCohesion;
+    /** Prefer annotation.mobileText / shortText for label text. Default true. */
+    preferShortText?: boolean;
+}
 /** Structural subset of `AudienceProfile` the annotation layer reads — anything
  *  with a per-chart `familiarity` map satisfies it, so a real `AudienceProfile`
  *  can be passed directly without coupling `recipes` to the `ai` module. */

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

@@ -0,0 +1,119 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Axis-fixed force layout — "one axis is data, relax the other." Pins each
+ * node's position on one axis from a data field (e.g. year → y) and settles the
+ * free axis with edge attraction, an anchor spring, and **rectangular**
+ * (label-box-aware) collision. The distinct, reusable layout family none of the
+ * hierarchical recipes (`flextree`, `dagre`, `lineageDag`, `mermaidDag`) cover —
+ * a chronological influence/genealogy network where time is structural and the
+ * graph determines the cross-axis arrangement.
+ *
+ * Rectangular collision ({@link rectCollide}) is the differentiator over plain
+ * d3-force, whose `forceCollide` only separates circles — text labels are boxes.
+ *
+ * Two entry points:
+ *  - {@link axisFixedForcePositions} — the pure positioner. Returns positioned
+ *    boxes; pair with art-directed `overlays` + `networkHitTarget` for full
+ *    control over how nodes/edges look.
+ *  - {@link axisFixedForceLayout} — a ready `NetworkCustomLayout` that emits
+ *    default rect nodes, curved edges, and labels (sibling to `dagreLayout`).
+ */
+export interface CollisionBox {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface RectCollideOptions {
+    /** Free axis to separate boxes along. @default "x" */
+    axis?: "x" | "y";
+    /** Minimum gap to maintain between box edges, px. @default 0 */
+    padding?: number;
+    /** Fraction of each overlap resolved in this pass (0..1). @default 0.5 */
+    strength?: number;
+}
+/**
+ * One pass of rectangular collision separation. Returns the per-box displacement
+ * along the free axis — add it to a force accumulator (as the axis-fixed settle
+ * does) or apply it directly. Two boxes interact only when they overlap on the
+ * cross axis *and* the free axis, so distant rows never push each other. The
+ * box-aware separation every text-heavy network needs (labels are rectangles,
+ * not points). Pure / deterministic (symmetric ties broken by id order).
+ */
+export declare function rectCollide(boxes: readonly CollisionBox[], opts?: RectCollideOptions): Map<string, number>;
+export interface AxisFixedForceConfig {
+    /** Field (or fn) giving the fixed-axis data value, e.g. a year. */
+    fixedAccessor: string | ((d: Datum) => number);
+    /** `[min, max]` of the fixed value, mapped to the pinned pixel axis. */
+    fixedDomain: [number, number];
+    /** Which axis is pinned from data. @default "y" (year → y, relax x). */
+    fixedAxis?: "x" | "y";
+    /** Node id accessor. @default "id" */
+    idAccessor?: string | ((d: Datum) => string);
+    /** Edge source-id accessor. @default "source" */
+    sourceAccessor?: string | ((e: Datum) => string);
+    /** Edge target-id accessor. @default "target" */
+    targetAccessor?: string | ((e: Datum) => string);
+    /** Box size per node (label-aware). @default `{ width: 60, height: 34 }` */
+    size?: (d: Datum) => {
+        width: number;
+        height: number;
+    };
+    /** Settle iterations. @default 180 */
+    iterations?: number;
+    /** Edge attraction along the free axis. @default 0.012 */
+    attraction?: number;
+    /** Spring strength pulling each node back to its initial spread. @default 0.003 */
+    anchorStrength?: number;
+    /** Collision separation strength. @default 0.12 */
+    collisionStrength?: number;
+    /** Gap maintained between boxes, px. @default 15 */
+    collisionPadding?: number;
+    /** Inset from the plot edges on the free axis, px. @default 42 */
+    edgePadding?: number;
+    /** Inset from the plot edges on the fixed axis, px. @default 16 */
+    fixedPadding?: number;
+    /** Per-iteration force damping. @default 0.72 */
+    damping?: number;
+    /** Widen the settled solution about its center (1 = leave as-is). @default 1 */
+    spread?: number;
+}
+export interface PositionedNode {
+    /** The raw user datum (unwrapped from any frame node wrapper). */
+    data: Datum;
+    id: string;
+    /** Center x in plot coordinates. */
+    x: number;
+    /** Center y in plot coordinates. */
+    y: number;
+    width: number;
+    height: number;
+    /** The fixed-axis data value used (e.g. the year). */
+    fixedValue: number;
+}
+export interface AxisFixedForceResult {
+    positioned: PositionedNode[];
+    byId: Map<string, PositionedNode>;
+}
+interface PlotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The pure positioner. Settles `nodes` against `edges` with one axis pinned from
+ * data, returning centered boxes. Deterministic for a given input + config.
+ */
+export declare function axisFixedForcePositions(nodes: readonly Datum[], edges: readonly Datum[], plot: PlotRect, config: AxisFixedForceConfig): AxisFixedForceResult;
+/**
+ * A ready-to-use `NetworkCustomLayout` wrapping {@link axisFixedForcePositions}:
+ * emits a rect node per node, a curved edge per edge ({@link curvedEdgePath},
+ * fanned by index), and a centered label. Hand it straight to a
+ * `NetworkCustomChart`'s `layout` for a quick chronological force graph; reach
+ * for the positioner directly when you want art-directed overlays.
+ */
+export declare const axisFixedForceLayout: NetworkCustomLayout<AxisFixedForceConfig>;
+export {};

package/dist/components/recipes/{gofishBoba.d.ts → boba.d.ts}

@@ -1,6 +1,6 @@
 import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
 import type { Datum } from "../charts/shared/datumTypes";
-export interface GofishBobaConfig {
+export interface BobaConfig {
     /** Category — one cup per distinct value. @default "name" */
     categoryAccessor?: string | ((d: Datum) => string);
     /** Tea volume (cm³). @default field "teaVolume" → 450 */
@@ -20,4 +20,4 @@ export interface GofishBobaConfig {
     /** Fraction of each band the cup glyph may occupy. @default 0.82 */
     cupWidthRatio?: number;
 }
-export declare const gofishBobaLayout: OrdinalCustomLayout<GofishBobaConfig>;
+export declare const bobaLayout: OrdinalCustomLayout<BobaConfig>;

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

@@ -0,0 +1,39 @@
+/**
+ * Cyclical (wrap-around) interval math for any periodic axis — day-of-year,
+ * hour-of-day, compass bearing, phase. A radial/circular brush, a clock chart,
+ * or a seasonal ribbon re-derives this; it lives here once.
+ *
+ * Pure / SSR-safe. All functions are domain-agnostic: pass the period of the
+ * cycle (365 for day-of-year, 24 for hour-of-day, 360 for degrees, `2π` for
+ * radians).
+ */
+/**
+ * Wrap a value into the half-open cycle `[min, min + period)`. Handles negatives
+ * and multiple wraps. `wrapValue(370, 365) → 5`, `wrapValue(-1, 365) → 364`.
+ */
+export declare function wrapValue(value: number, period: number, min?: number): number;
+/**
+ * The signed shortest step from `from` to `to` around the cycle. Result is in
+ * `(-period/2, period/2]`: positive goes forward (increasing), negative
+ * backward, taking whichever way around is shorter. The delta a drag handler
+ * applies so dragging a circular range never "unwinds" the long way round.
+ */
+export declare function shortestArcDelta(from: number, to: number, period: number): number;
+/**
+ * Whether `value` falls within the inclusive cyclic range `[start, end]`. When
+ * `start <= end` it's a normal interval; when `start > end` the range wraps past
+ * the period boundary (e.g. a Dec→Feb winter window), so membership is
+ * `value >= start || value <= end`. Values are compared as given — wrap them
+ * with {@link wrapValue} first if they may be out of range.
+ */
+export declare function cyclicRangeContains(value: number, start: number, end: number): boolean;
+/**
+ * Filter items whose accessor value falls in the cyclic range `[start, end]`
+ * (inclusive), handling the wrap-around case. The generic replacement for the
+ * hand-rolled "if start<=end filter once, else union two filters" pattern.
+ *
+ * When the range wraps, items are returned in two contiguous arcs (the
+ * `[start, period)` arc first, then the `[min, end]` arc) so a downstream
+ * consumer reading them in order walks the selection the way the eye does.
+ */
+export declare function selectCyclicRange<T>(items: readonly T[], accessor: (item: T) => number, start: number, end: number): T[];

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

@@ -0,0 +1,103 @@
+/**
+ * Edge-router kit — shared SVG-path builders for custom **network** layouts that
+ * draw their own edges in `overlays` (or emit `sceneEdges` of type `curved`).
+ * Every hand-built influence/lineage diagram re-derives bezier control points,
+ * box exit/entry anchors, and a fan-out bend to keep parallel edges from
+ * overlapping; this centralizes that geometry.
+ *
+ * Pure / SSR-safe. Complements the network `sceneEdges` `bezier` / `curved`
+ * types and the annotation `connector: { type: "curve" }` option.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A box positioned by its **center** (what force/constraint layouts produce). */
+export interface CenteredBox {
+    cx: number;
+    cy: number;
+    width: number;
+    height: number;
+}
+export type EdgeOrientation = "vertical" | "horizontal";
+export interface CurvedEdgeOptions {
+    /** Which axis the edge mainly travels along. `"vertical"` flows top↔bottom
+     *  (control points share x); `"horizontal"` flows left↔right. @default "vertical" */
+    orientation?: EdgeOrientation;
+    /** Cross-axis offset of the curve's midpoint, in px — fan parallel edges apart.
+     *  Feed it {@link fanOutBend}. @default 0 */
+    bend?: number;
+    /** Below this along-axis distance the endpoints are nearly side-by-side, so a
+     *  straight S-curve would collapse; the router draws a sideways bow instead.
+     *  @default 18 */
+    minAlong?: number;
+}
+/**
+ * A smooth cubic-bezier edge between two points. For a top-to-bottom flow the
+ * control points sit at the vertical midpoint (offset by `bend`), giving the
+ * familiar S-curve; when the two ends are nearly level it falls back to a
+ * quadratic side-bow so the edge stays visible. Generalizes the bespoke
+ * "S-curve, with a short-hop side-bow for near-parallel pairs" router.
+ */
+export declare function curvedEdgePath(from: Point, to: Point, opts?: CurvedEdgeOptions): string;
+/**
+ * An orthogonal "elbow" edge — two right-angle bends through the midpoint of the
+ * travel axis. The step-router alternative to {@link curvedEdgePath} for
+ * dataflow/lineage diagrams that prefer rectilinear edges.
+ */
+export declare function orthogonalEdgePath(from: Point, to: Point, opts?: {
+    orientation?: EdgeOrientation;
+}): string;
+export interface BoxEdgeAnchorOptions {
+    orientation?: EdgeOrientation;
+}
+/**
+ * Resolve where an edge leaves the source box and meets the target box. For a
+ * vertical flow it exits the bottom-center and enters the top-center when the
+ * target is below (and vice-versa); horizontal uses right/left centers. Removes
+ * the per-recipe "compute startY/endY from half-heights and direction" block.
+ */
+export declare function boxEdgeAnchors(source: CenteredBox, target: CenteredBox, opts?: BoxEdgeAnchorOptions): {
+    from: Point;
+    to: Point;
+};
+export interface FanOutBendOptions {
+    /** Total number of parallel edges, for a centered fan: edge `(count-1)/2`
+     *  gets bend 0. Ignored when `modulo` is set. */
+    count?: number;
+    /** Cross-axis spacing between adjacent fanned edges, in px. @default 5 */
+    spread?: number;
+    /** Cycle bends through `modulo` evenly-spaced offsets centered on 0 — useful
+     *  when you don't know the per-pair count and just want global variety. */
+    modulo?: number;
+}
+/**
+ * A cross-axis bend offset that fans parallel edges apart so they don't overlap.
+ * Pass an edge's index; with `count` it centers a fan (`0` at the middle edge),
+ * with `modulo` it cycles through a fixed set of offsets. Feed the result to
+ * {@link curvedEdgePath}'s `bend`.
+ */
+export declare function fanOutBend(index: number, opts?: FanOutBendOptions): number;
+/** A cubic Bézier as its four control points (start, two handles, end). */
+export interface CubicCurve {
+    p0: Point;
+    p1: Point;
+    p2: Point;
+    p3: Point;
+}
+/**
+ * Evaluate the point on a cubic Bézier at parameter `t ∈ [0, 1]`. The companion
+ * to {@link curvedEdgePath} / {@link cubicPath} for the case the path string
+ * can't cover: *placing a mark along the curve* — a station node at `t = 0.5`,
+ * an arrowhead at the end, a label at the third. `t = 0` is `p0`, `t = 1` is `p3`.
+ */
+export declare function cubicPoint(curve: CubicCurve, t: number): Point;
+/**
+ * The (unnormalized) tangent vector of a cubic Bézier at `t` — the curve's
+ * derivative. Normalize it (e.g. with `normalizePoint` from the vector kit) to
+ * orient an arrowhead or grow a branch normal to the curve. Points in the
+ * direction of increasing `t`.
+ */
+export declare function cubicTangent(curve: CubicCurve, t: number): Point;
+/** Serialize a {@link CubicCurve} to an SVG `M…C…` path string. */
+export declare function cubicPath(curve: CubicCurve): string;

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

@@ -0,0 +1,48 @@
+/**
+ * Seeded, deterministic force layout for custom network charts.
+ *
+ * `ForceDirectedGraph` runs a force simulation internally, but `NetworkCustomChart`
+ * expects pre-computed positions — and there was no reproducible positioner to
+ * feed it. This is a compact spring/repulsion/gravity sim with a seeded PRNG, so
+ * the same graph + seed always produces the same layout (change the seed to get a
+ * different one — useful for "re-run the layout" interactions). Positions are
+ * returned normalized to [0, 1], so you map them into the plot yourself.
+ *
+ * Synchronous and deterministic: it settles before returning, so consumers get
+ * stable coordinates without running an interactive simulation.
+ */
+import type { GraphNode, GraphEdge, Point } from "./networkAnalysis";
+export { mulberry32 } from "./random";
+export interface ForceLayoutOptions {
+    /** PRNG seed — same seed ⇒ same layout. @default 1 */
+    seed?: number;
+    /** Simulation iterations. @default 260 */
+    iterations?: number;
+    /** Repulsion strength between every pair of nodes. @default 5200 */
+    repulsion?: number;
+    /** Target edge length in the virtual (pre-normalization) space. @default 165 */
+    linkDistance?: number;
+    /** Spring stiffness pulling connected nodes to `linkDistance`. @default 0.045 */
+    linkStrength?: number;
+    /** Gravity toward the center (keeps disconnected pieces on screen). @default 0.018 */
+    centerStrength?: number;
+    /** Per-step velocity damping. @default 0.84 */
+    damping?: number;
+    /** Node collision radius in virtual layout units. @default 12 */
+    nodeRadius?: number | ((node: GraphNode) => number);
+    /** Extra collision spacing in virtual layout units. @default 3 */
+    nodePadding?: number;
+    /** Inset kept clear at the edges of the normalized box. @default 0.06 */
+    inset?: number;
+}
+/**
+ * Lay a graph out with a seeded force simulation. Returns node id → {x, y} with
+ * both in [0, 1].
+ *
+ * @example
+ * ```ts
+ * const pos = forceLayout(nodes, edges, { seed: 7 })
+ * // in a NetworkCustomChart layout: cx = plot.x + pos[node.id].x * plot.width
+ * ```
+ */
+export declare function forceLayout(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, options?: ForceLayoutOptions): Record<string, Point>;

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

@@ -0,0 +1,17 @@
+import { type ForceLayoutOptions } from "./forceLayout";
+import type { GraphEdge, GraphNode, Point } from "./networkAnalysis";
+import { type ForceLayoutExecution } from "../stream/layouts/forceLayoutWorkerClient";
+export interface ForceLayoutAsyncOptions extends ForceLayoutOptions {
+    /** Choose worker execution, synchronous execution, or an automatic cost threshold. */
+    execution?: ForceLayoutExecution;
+    /** Abort pending worker execution. */
+    signal?: AbortSignal;
+    /** Override the automatic `iterations × (nodes + edges)` worker threshold. */
+    workerThreshold?: number;
+}
+/**
+ * Asynchronous counterpart to {@link forceLayout}. Large layouts run in a
+ * short-lived module worker; small, server-side, or unsupported environments
+ * fall back to the same deterministic synchronous implementation.
+ */
+export declare function forceLayoutAsync(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, options?: ForceLayoutAsyncOptions): Promise<Record<string, Point>>;

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

@@ -0,0 +1,3 @@
+import type { GofishDisplayListDocument } from "./gofishIR";
+/** The hand-emitted boba DisplayList document (computed once, deterministic). */
+export declare const bobaDisplayList: GofishDisplayListDocument;

package/dist/components/recipes/gofishDisplayListFixtures.generated.d.ts

@@ -0,0 +1,37 @@
+import type { DisplayList } from "gofish-ir";
+type DisplayListDocument = DisplayList.DisplayListDocument;
+/**
+ * Flower meadow — GoFish's real flower chart, verbatim: a meadow where each lake is a green stem (a bar whose height is the lake's total catch) topped by a polar fan of petals, one per species, sized by count. It is layer([stems, flowers]) — the flowers selectAll the stems and stack a polar petal fan on each. The composition's root is a combinator (no ChartBuilder.toDisplayList), so it is baked through GoFish's mark-resolution contract; see gofish-displaylist-findings.md.
+ * Source: https://gofish.graphics/js/examples/flower-chart.html
+ */
+export declare const flowerDisplayList: DisplayListDocument;
+/**
+ * Polar ribbon chart — GoFish's polar ribbon chart, verbatim: the catch stacked radially per lake under a clock() projection, then a smooth area ribbon drawn across the lakes for each species (selectAll the bars, group by species). The wrap, the open gap, and the bumped ribbons are all baked into absolute-pixel paths; the radial bars keep their datum (hit targets), the ribbons are area chrome. Root is a layer({ coord: clock() }) combinator, baked through GoFish's mark-resolution contract — see gofish-displaylist-findings.md.
+ * Source: https://gofish.graphics/js/examples/polar-ribbon-chart.html
+ */
+export declare const polarribbonDisplayList: DisplayListDocument;
+/**
+ * Fare circle treemap — GoFish's titanic fare circle treemap, verbatim: faceted by passenger class (facet by pclass, dir x), then a squarify-circle treemap per facet sizing each passenger by fare (sort desc, so fares run large→small) and colouring by survival. Three blocks — big first-class circles, then a field of tiny third-class ones. Every circle is a data node carrying its passenger; the facet labels/legend are chrome.
+ * Source: https://gofish.graphics/js/examples/titanic-fare-circle-treemap.html
+ */
+export declare const treemapDisplayList: DisplayListDocument;
+/**
+ * Bottle fill pictorial — GoFish's real bottle-fill technique: a fill rect sized by amount is color-composited *inside* the bottle silhouette via paint({ blendMode: 'color' }), so the liquid reads as rising within the bottle (not a bar behind a picture). Bakes to a composite item; the adapter harvests the composite's datum so each bottle keeps hit-testing and tooltips.
+ * Source: https://gofish.graphics/js/examples/bottle-fill-chart.html
+ */
+export declare const bottleDisplayList: DisplayListDocument;
+/**
+ * Python memory diagram — A Python Tutor runtime memory diagram: a Global Frame of variables (c, d → pointers; x = 5) whose arrows fan into a heap of tuples, with tuple cells pointing on to further tuples. NOTE: GoFish's own example is not a portable spec — it relies on ~250 lines of unpublished story helpers (globalFrame/heap/tuple/Arrow). This is a best-effort reconstruction from GoFish primitives only (rect/text/Arrow/ref + .name()). It is also vertically flipped vs the live example: a free-space Layer baked through toDisplayList orients y-down differently than .render() (GoFish issue #143/#16). See gofish-displaylist-findings.md §6.
+ * Source: https://gofish.graphics/js/examples/python-tutor-memory-diagram.html
+ */
+export declare const pythonDisplayList: DisplayListDocument;
+export interface GofishDisplayListExample {
+    key: "bars" | "flower" | "polarribbon" | "treemap" | "bottle" | "python";
+    label: string;
+    source: string;
+    blurb: string;
+    doc: DisplayListDocument;
+}
+/** All baked gallery fixtures, in display order. */
+export declare const gofishDisplayListExamples: readonly GofishDisplayListExample[];
+export {};