semiotic 3.7.5 → 3.8.0

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

@@ -1,169 +1,215 @@
 import type { Datum } from "../charts/shared/datumTypes";
-import type { CustomLayout } from "../stream/customLayout";
 import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
-import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
-import type { GofishLambda } from "./gofishLambdas";
 /**
- * Experimental GoFish Frontend IR → Semiotic custom-layout adapter.
+ * Experimental GoFish **DisplayList** → Semiotic custom-layout adapter.
  *
- * This is the GoFish analogue of `fromVegaLite`. Where `fromVegaLite` maps a
- * Vega-Lite spec onto a built-in HOC component + props, `unstable_fromGofishIR` maps a
- * GoFish *Frontend IR* document (the JSON artifact GoFish's `to_ir` /
- * serialization frontend emits — see the `gofish-ir` package) onto Semiotic's
- * custom-layout surface.
+ * GoFish's `toDisplayList({ w, h })` is the post-layout *render IR*: a flat,
+ * ordered list of positioned primitives in absolute viewport pixels. The layout
+ * solve has already run — operators, constraints, channels, and the coordinate
+ * transforms are all consumed, so a polar petal arrives as a baked `path`, a
+ * treemap cell as a baked `rect`. Josh Pollock shipped this stage specifically
+ * for this adapter (it is the analogue of running a chart to SVG but stopping
+ * one step earlier, before backend emission).
  *
- * Unlike a recognizer, this *interprets* the spec: `unstable_fromGofishIR` picks a
- * frame family, then hands the IR to `interpretGofishIR` (see
- * `gofishInterpreter.ts`), which walks `data → operators → mark` and executes
- * `group`/`spread`/`stack`/`scatter`/`treemap`/`layer`, the `polar`/`unit`
- * coordinate transforms, mark channels through scales, and `connect`/`ref`/
- * `arrow` relations. The two sanctioned non-grammar paths — `derive` and
- * `mark-fn` — resolve through the lambda registry. Any spec built from the
- * supported grammar renders; it is not limited to known archetypes.
+ * That makes the adapter's job small and faithful: GoFish owns the geometry; we
+ * map each item onto Semiotic's custom-layout surface *by its `role`*, exactly
+ * as the reference backends do (`displayListToSVG` emits SVG tags; we emit
+ * scene-nodes + overlays):
  *
- * Frame family (hybrid): `arrow`/pointer specs → network; the boba volume
- * signature → ordinal (Semiotic owns the category axis, the interpreter owns
- * the within-cup composition); everything else → XY. The Python Tutor memory
- * diagram is a genuinely bespoke diagram beyond the grammar, so it stays a
- * chart-level escape hatch rendered by `gofishPythonTutorNetworkLayout`.
+ * - **`role: "overlay"`** — chrome (axis ticks, labels, glyph detail). Rendered
+ *   verbatim into one ordered SVG overlay layer (a JSX port of GoFish's
+ *   reference `displayListToSVG`), so painter order and every `kind` — including
+ *   warped `path`s, `image`s, and Porter-Duff `composite`/`mask` graphs — stay
+ *   pixel-faithful.
+ * - **`role: "node"`** — data-bearing marks. Rendered into the same SVG layer
+ *   *and* given a transparent hit-rect scene node carrying the item's `datum`,
+ *   so Semiotic stays authoritative for hit-testing, tooltips, `onObservation`,
+ *   cross-chart selection, keyboard a11y, and SSR mark-count evidence.
  *
- * Scope: GoFish Frontend IR v0. This is a PR-preview adapter named
- * `unstable-gofish-ir-adapter`, not a release API commitment. Constructs outside the interpreter's
- * allocation model (`table`, `cut`, `mask`, free-form `.constrain`, …) record
- * a warning and fall back rather than silently mis-rendering.
+ * Because a display list is **viewport-baked** — solved at one `{ w, h }`, not
+ * cacheable — the result always mounts on `NetworkCustomChart` (the scale-free
+ * family: plot-relative pixel coordinates, no data scales to fight the baked
+ * geometry). The adapter surfaces the document's `viewport` as `width`/`height`;
+ * the list is only valid at that size, so on resize or data change the host
+ * re-calls `toDisplayList` and re-runs the adapter rather than rescaling an old
+ * document.
+ *
+ * Scope: GoFish DisplayList IR v0 (`ir: "gofish-display-list"`). This is a
+ * PR-preview adapter named `unstable-gofish-displaylist-adapter`, exposed from
+ * `semiotic/experimental`; it is not a release API commitment.
  */
-export declare const EXPERIMENTAL_GOFISH_ADAPTER_NAME = "unstable-gofish-ir-adapter";
-/** Explicit field-accessor channel form, emitted by `field(name)`. */
-export interface GofishFieldAccessor {
-    type: "field";
-    name: string;
-    measure?: string;
+export declare const EXPERIMENTAL_GOFISH_ADAPTER_NAME = "unstable-gofish-displaylist-adapter";
+/** Resolved paint carried by a display item. */
+export interface GofishDisplayStyle {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    fillOpacity?: number;
+    /** CSS `mix-blend-mode`. */
+    mixBlendMode?: string;
+    /** SVG `stroke-dasharray`. */
+    strokeDasharray?: string;
+    /** A `url(#id)` reference to a user-supplied filter def. */
+    filter?: string;
 }
-/** A data-driven channel value, emitted by `datum(v)` / `v(...)`. */
-export interface GofishDatumValue {
-    type: "datum";
-    datum?: unknown;
-    offset?: number;
-    [key: string]: unknown;
+/** One source row, or the rows of an aggregate mark. Provenance, not a binding. */
+export type GofishDisplayDatum = Record<string, unknown> | Array<Record<string, unknown>>;
+export interface GofishDisplayItemBase {
+    style?: GofishDisplayStyle;
+    datum?: GofishDisplayDatum;
+    /** `"node"` (data-bearing) or `"overlay"` (chrome). Defaults to `"node"`. */
+    role?: "node" | "overlay";
+    id?: string;
 }
-/** The right-hand side of a mark or operator channel (`h: …`, `fill: …`). */
-export type GofishChannelValue = string | number | boolean | null | GofishFieldAccessor | GofishDatumValue | {
-    __gofish_lambda: string;
-};
-export interface GofishOperatorIR {
-    type: string;
-    by?: string;
-    dir?: "x" | "y";
-    x?: GofishChannelValue;
-    y?: GofishChannelValue;
-    spacing?: number | [number, number];
-    [key: string]: unknown;
+export interface GofishRectItem extends GofishDisplayItemBase {
+    kind: "rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rx?: number;
+    ry?: number;
 }
-export interface GofishMarkIR {
-    type: string;
-    __combinator?: true;
-    children?: GofishMarkIR[];
-    source?: GofishMarkIR;
-    options?: Record<string, unknown>;
-    origin?: {
-        name?: string;
-    };
-    name?: string;
-    [key: string]: unknown;
+export interface GofishEllipseItem extends GofishDisplayItemBase {
+    kind: "ellipse";
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
 }
-export interface GofishChartIR {
-    type: "chart";
-    data?: GofishDataIR | null;
-    operators?: GofishOperatorIR[];
-    mark: GofishMarkIR;
-    options?: Record<string, unknown>;
-    connect?: GofishMarkIR;
-    name?: string;
+export interface GofishPathItem extends GofishDisplayItemBase {
+    kind: "path";
+    /** SVG path data in absolute pixels (coordinate transform already applied). */
+    d: string;
 }
-export interface GofishLayerIR {
-    type: "layer";
-    charts: GofishChartIR[];
-    options?: Record<string, unknown>;
+export interface GofishTextItem extends GofishDisplayItemBase {
+    kind: "text";
+    x: number;
+    y: number;
+    text: string;
+    fontSize?: number;
+    fontFamily?: string;
+    textAnchor?: "start" | "middle" | "end";
+    dominantBaseline?: "auto" | "central" | "middle" | "hanging" | "mathematical";
+    /** Rotation in degrees about `(x, y)` (SVG `rotate(deg, x, y)` convention). */
+    rotate?: number;
 }
-export interface GofishRawMarkIR {
-    type: "raw-mark";
-    mark: GofishMarkIR;
-    options?: Record<string, unknown>;
+export interface GofishImageItem extends GofishDisplayItemBase {
+    kind: "image";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    href: string;
+    preserveAspectRatio?: string;
 }
-export type GofishDataIR = {
-    type: "inline";
-    rows: Array<Record<string, unknown>>;
-} | {
-    type: "select";
-    layer: string;
-    mode?: "one" | "all";
-} | {
-    type: "external";
-    id?: string;
-};
-export type GofishRootIR = GofishChartIR | GofishLayerIR | GofishRawMarkIR;
-export interface GofishIRDocument {
+export interface GofishGroupItem extends GofishDisplayItemBase {
+    kind: "group";
+    transform: {
+        translate?: [number, number];
+        scale?: [number, number];
+    };
+    children: GofishDisplayItem[];
+}
+export interface GofishCompositeItem extends GofishDisplayItemBase {
+    kind: "composite";
+    operator: "over" | "atop" | "in" | "out" | "xor";
+    blendMode?: string;
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    source: GofishDisplayItem[];
+    dest: GofishDisplayItem[];
+}
+export interface GofishMaskItem extends GofishDisplayItemBase {
+    kind: "mask";
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    mask: GofishDisplayItem[];
+    content: GofishDisplayItem[];
+}
+export type GofishDisplayItem = GofishRectItem | GofishEllipseItem | GofishPathItem | GofishTextItem | GofishImageItem | GofishGroupItem | GofishCompositeItem | GofishMaskItem;
+export interface GofishDisplayListDocument {
     irVersion: number;
     ir: string;
     $schema?: string;
-    root: GofishRootIR;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    items: GofishDisplayItem[];
 }
-export type GofishChartFamily = "xy" | "network" | "ordinal";
-export type GofishRecipeName = 
-/** XY / ordinal charts are produced by the IR interpreter, not a named recipe. */
-"gofishInterpreter"
-/** The Python Tutor memory diagram is a bespoke network glyph (chart-level escape hatch). */
- | "gofishPythonTutorNetworkLayout";
 /**
- * The translated chart, spreadable into `XYCustomChart` / `NetworkCustomChart`.
- * Mirrors `fromVegaLite`'s `{ component, props, warnings }` for the
- * custom-layout surface.
+ * The translated chart, spreadable into `NetworkCustomChart`. Mirrors
+ * `fromVegaLite`'s `{ component, props, warnings }` for the custom-layout
+ * surface — a baked display list is always scale-free, so the family is fixed.
  */
 export interface GofishChartConfig {
-    family: GofishChartFamily;
-    /** Which `gofish.tsx` recipe the IR resolved to. */
-    recipe: GofishRecipeName;
-    /** Layout function to pass as `layout` on `XYCustomChart` — null otherwise. */
-    layout: CustomLayout<Record<string, unknown>> | null;
-    /** Layout function to pass as `layout` on `NetworkCustomChart` — null otherwise. */
-    networkLayout: NetworkCustomLayout<Record<string, unknown>> | null;
-    /** Layout function to pass as `layout` on `OrdinalCustomChart` — null otherwise. */
-    ordinalLayout: OrdinalCustomLayout<Record<string, unknown>> | null;
-    /** Accessor config derived from the IR; pass as `layoutConfig`. */
-    layoutConfig: Record<string, unknown>;
-    /** Category accessor for ordinal charts (the frame builds the o-scale from it). */
-    categoryAccessor?: string;
-    /** Value accessor for ordinal charts (the frame builds the r-scale from it). */
-    valueAccessor?: string;
-    /** Inline data to seed the chart (`data` / `pushMany`). Empty for network. */
-    data: Datum[];
-    /** Node/edge graph for `NetworkCustomChart` (memory diagram only). */
-    graph: {
-        nodes: Datum[];
-        edges: Datum[];
-    } | null;
+    /** Always `"network"`: absolute-pixel primitives have no data scales. */
+    family: "network";
+    /** Pass as `layout` on `NetworkCustomChart`. */
+    networkLayout: NetworkCustomLayout<{
+        displayList?: GofishDisplayListDocument;
+    }>;
+    /**
+     * Pass as `layoutConfig`. Carries the document so a host can swap the baked
+     * list through `layoutConfig` (the cheap re-render path) without re-ingesting
+     * the `nodes` topology.
+     */
+    layoutConfig: {
+        displayList: GofishDisplayListDocument;
+    };
+    /** Row data from `role:"node"` items — pass as `nodes` (seeds non-empty state + selection). */
+    nodes: Datum[];
+    /** A display list is a flat primitive list — no relational edges. */
+    edges: Datum[];
+    /**
+     * The viewport this list was solved at. Use as the chart `width`/`height`
+     * (with `margin={0}`); the geometry is only valid at this size.
+     */
+    width: number;
+    height: number;
     irVersion: number;
     warnings?: string[];
 }
 export interface FromGofishIROptions {
-    /** Force a frame family instead of inferring it. */
-    family?: GofishChartFamily;
-    /** Per-call `derive`/`mark-fn` lambda overrides (merged over the registry). */
-    lambdas?: Record<string, GofishLambda>;
+    /**
+     * Override the document carried in `layoutConfig` (rarely needed — the
+     * returned `layoutConfig.displayList` already holds the parsed document).
+     */
+    displayList?: GofishDisplayListDocument;
 }
 /**
- * Translate a GoFish Frontend IR document into a Semiotic custom-layout config
- * by *interpreting* the spec.
+ * Translate a GoFish DisplayList document into a Semiotic custom-layout config
+ * for `NetworkCustomChart`.
  *
  * @example
  * ```tsx
  * import { unstable_fromGofishIR } from "semiotic/experimental"
- * import { XYCustomChart } from "semiotic/xy"
+ * import { NetworkCustomChart } from "semiotic/network"
+ *
+ * // In a host, the document comes from GoFish's layout pass:
+ * //   const doc = await chart(data).flow(...).mark(...).toDisplayList({ w, h })
+ * const cfg = unstable_fromGofishIR(doc)
  *
- * const cfg = unstable_fromGofishIR(flowerIR)
- * <XYCustomChart data={cfg.data} layout={cfg.layout} />
+ * <NetworkCustomChart
+ *   nodes={cfg.nodes}
+ *   layout={cfg.networkLayout}
+ *   layoutConfig={cfg.layoutConfig}
+ *   width={cfg.width}
+ *   height={cfg.height}
+ *   margin={0}
+ * />
  * ```
  */
-export declare function unstable_fromGofishIR(doc: GofishIRDocument, options?: FromGofishIROptions): GofishChartConfig;
+export declare function unstable_fromGofishIR(doc: GofishDisplayListDocument, options?: FromGofishIROptions): GofishChartConfig;
 /** @deprecated Internal compatibility alias for the temporary GoFish PR preview. */
 export declare const fromGofishIR: typeof unstable_fromGofishIR;

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

@@ -1,89 +1,38 @@
-import type { GofishIRDocument } from "./gofishIR";
-/** The Python Tutor heap/stack snapshot, inlined as a single IR data row. */
-export declare const pythonTutorDiagramRow: {
-    kind: string;
-    stack: ({
-        name: string;
-        value: {
-            pointer: number;
-        };
-    } | {
-        name: string;
-        value: string;
-    })[];
-    heap: {
-        values: (string | {
-            pointer: number;
-        })[];
-    }[];
-    heapArrangement: (number | null)[][];
-};
+import type { GofishDisplayListDocument } from "./gofishIR";
+import { gofishDisplayListExamples as generatedExamples } from "./gofishDisplayListFixtures.generated";
 /**
- * Deterministic Titanic passenger sample (no RNG), mirroring the docs page so
- * the IR document is self-contained. Kept modest per class so the inline rows
- * stay reasonable to ship and display.
- */
-export declare function buildTitanicSampleRows(): Array<Record<string, unknown>>;
-/**
- * A meadow: one green stem per lake (a `scatter` placing each lake's bar at its
- * x), topped by a polar fan of species petals. Single-chart form so the
- * interpreter renders it directly: `scatter(by:lake)` → per lake a `layer` of
- * a stem `rect` (height = summed catch) and a `polar` `stack` of `petal`s
- * around the angle axis.
- */
-export declare const flowerIR: GofishIRDocument;
-/**
- * A row of pictorial bottles, one per category, each filled to its `amount`
- * percentage. Grammar-first with one `derive`: `bottleGeometry` emits the
- * per-bottle normalized geometry under `_b`; the marks render it with the
- * reusable `image` + clip primitives — an `image` of the bottle silhouette, a
- * green fill `rect` clipped to that silhouette, a fill line, a percentage
- * label, a category label, and a transparent hit rect carrying the datum.
- */
-export declare const bottleIR: GofishIRDocument;
-/**
- * Stacked species bars laid out radially per lake (polar coord), with one
- * cross-lake ribbon per species connecting the matching segments.
- */
-export declare const polarRibbonIR: GofishIRDocument;
-/**
- * A bar chart that's treemap-filled and circle-filled: a `spread` lays one
- * equal-width bar per passenger class whose HEIGHT encodes the class's total
- * fare (`sizeBy`), and that bar rectangle becomes a squarified `treemap` of its
- * passengers — every fare-sized cell rendered as an inscribed circle coloured
- * by survival.
- */
-export declare const titanicCircleTreemapIR: GofishIRDocument;
-/**
- * A Python Tutor runtime memory diagram: a global frame of variable bindings
- * whose pointers arrow into a heap of linked tuples. Encoded as a `layer` of a
- * `spread` (frame + heap) plus `arrow` connectors over `ref`s; the snapshot
- * itself travels as a single inline data row consumed by the network recipe.
- */
-export declare const pythonMemoryIR: GofishIRDocument;
-/**
- * A boba-shop menu: four bubble-tea drinks spread along the category axis, each
- * fully data-driven. Per drink, the tea + tapioca + ice volumes (plus the
- * cup-size parameters) add up to a total volume that determines the drink
- * height; the pearls stack at the bottom and the ice floats at the surface — so
- * "Extra Boba" grows a taller pearl bed, "Light Ice" reads as mostly tea, and
- * "Mega" is a bigger cup of everything.
+ * Canonical GoFish **DisplayList** documents for the adapter gallery.
+ *
+ * Most are *real* baked render-IR documents — the output of `gofish-graphics`'
+ * `toDisplayList({ w, h })` layout pass — generated by
+ * `scripts/gen-gofish-fixtures.ts` and checked in so the adapter tests and the
+ * `/interoperability/gofish` page stay deterministic and never depend on the
+ * GoFish nightly at runtime. Each stands in for what a host gets by calling
+ * `await spec.toDisplayList({ w, h })`.
+ *
+ * The one exception is **boba**, which is *hand-written* (`gofishBobaHandwritten.ts`,
+ * no `gofish-graphics` at all) — the counter-proof that the DisplayList is an
+ * open, host-emittable format, not something only GoFish can produce.
  *
- * Grammar-first, per the "follow the spec as far as it can" rule: the cup, tea,
- * straw, and lid are real `polygon`/`line` marks and the pearls/ice are real
- * `circle`/`rect` marks. The one genuinely non-grammar step — the
- * frustum-volume → drink-height solve and tapioca/ice packing — lives in a
- * single `derive` lambda (`bobaGeometry`) that emits each cup's geometry the
- * marks read (`_g.*`) plus a shared `_g.box` aspect for the `uniform` unit fit,
- * so the cups sit on one shelf with aligned straws. Derived from Krist
- * Wongsuphasawat's "Boba Science" notebook. Routed to the ordinal frame.
+ * Regenerate the baked set after a GoFish bump with:
+ *   `node --experimental-strip-types scripts/gen-gofish-fixtures.ts --write`
  */
-export declare const bobaIR: GofishIRDocument;
+export declare const flowerIR: GofishDisplayListDocument;
+export declare const polarribbonIR: GofishDisplayListDocument;
+export declare const treemapIR: GofishDisplayListDocument;
+export declare const bottleIR: GofishDisplayListDocument;
+export declare const bobaIR: GofishDisplayListDocument;
+export declare const pythonIR: GofishDisplayListDocument;
 export interface GofishIRExample {
-    key: "flower" | "bottle" | "polar" | "titanic" | "python" | "boba";
+    /** Generated keys (derived so new baked fixtures never drift this) plus the hand-written `boba`. */
+    key: (typeof generatedExamples)[number]["key"] | "boba";
     label: string;
-    doc: GofishIRDocument;
+    doc: GofishDisplayListDocument;
+    /** A one-line note on what the document demonstrates. */
+    blurb: string;
+    /** The upstream example this mirrors. */
     source: string;
+    /** True for the hand-emitted document (no GoFish bake). */
+    handWritten?: boolean;
 }
-/** All five examples, in gallery order. */
 export declare const gofishIRExamples: readonly GofishIRExample[];

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

@@ -0,0 +1,87 @@
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * `intervalLanesLayout` — a Gantt / swimlane timeline as an `OrdinalCustomChart`
+ * layout. Each ordinal **lane** holds events that occupy a `[start, end]` span on
+ * a shared time axis; concurrent events within a lane are packed into stacked
+ * sub-tracks ({@link packIntervals}). The recipe emits one real, hit-tested,
+ * theme-colored rect per event (so every bar inherits keyboard nav, tooltips,
+ * selection, and transitions) and draws lane labels, optional period bands, and
+ * a time axis in `overlays`.
+ *
+ * Sibling to `flextreeLayout` / `dagreLayout`. The complement to a
+ * concurrency line — see {@link activeCountOverDomain}.
+ *
+ * @example
+ * ```tsx
+ * import { OrdinalCustomChart } from "semiotic/ordinal"
+ * import { intervalLanesLayout } from "semiotic/recipes"
+ *
+ * <OrdinalCustomChart
+ *   data={wars}
+ *   layout={intervalLanesLayout}
+ *   categoryAccessor="sphere"
+ *   valueAccessor="startYear"
+ *   oExtent={SPHERES}
+ *   layoutConfig={{
+ *     laneAccessor: "sphere", startAccessor: "startYear", endAccessor: "endYear",
+ *     domain: [1775, 2015], unit: 1, color: (d, lane) => COLORS[lane],
+ *     axisTicks: [1800, 1850, 1900, 1950, 2000],
+ *   }}
+ *   width={900} height={620}
+ * />
+ * ```
+ */
+export interface IntervalLanesConfig<T = Datum> {
+    /** Which lane each record belongs to. */
+    laneAccessor: string | ((d: T) => string);
+    /** Interval start, in the same units as `domain`. */
+    startAccessor: string | ((d: T) => number);
+    /** Interval end, in the same units as `domain`. */
+    endAccessor: string | ((d: T) => number);
+    /** `[min, max]` of the time axis. */
+    domain: [number, number];
+    /** Lane order. @default the chart's `o` scale domain (its `oExtent`), else the
+     *  distinct lane values in first-seen order. */
+    lanes?: string[];
+    /** Per-record fill. @default `ctx.resolveColor(lane)`. */
+    color?: (d: T, lane: string) => string;
+    /** Stable id per record → bar transition identity. @default none */
+    idAccessor?: string | ((d: T) => string);
+    /** Extend each bar this many domain units past `end`, so inclusive whole-unit
+     *  intervals (e.g. years) fill their final unit. @default 0 */
+    unit?: number;
+    /** Vertical gap between stacked sub-tracks, px. @default 1.5 */
+    barGap?: number;
+    /** Minimum rendered interval width, px. Keeps zero- and short-duration
+     *  events visible and hoverable on long domains. @default 2 */
+    minBarWidth?: number;
+    /** @default 3.5 */
+    minBarHeight?: number;
+    /** @default 10 */
+    maxBarHeight?: number;
+    /** Vertical padding inside each lane, px. @default 7 */
+    lanePadding?: number;
+    /** Bar corner radius, px. @default 2 */
+    cornerRadius?: number;
+    /** Reserve this many px at the bottom (for a caller-drawn strip, e.g. a
+     *  concurrency line). Lanes fill the remaining height. @default 0 */
+    bottomInset?: number;
+    /** Draw a label to the left of each lane. @default true */
+    showLaneLabels?: boolean;
+    /** Gap between the plot's left edge and lane labels, px. @default 12 */
+    laneLabelGap?: number;
+    /** Alternating background period bands across the full plot height. */
+    periods?: Array<{
+        start: number;
+        end: number;
+        name?: string;
+    }>;
+    /** Draw a top time axis with gridlines. @default true */
+    showAxis?: boolean;
+    /** Explicit axis tick values. @default ~7 evenly-spaced across `domain`. */
+    axisTicks?: number[];
+    /** Format axis tick labels. @default `String` */
+    tickFormat?: (v: number) => string;
+}
+export declare const intervalLanesLayout: OrdinalCustomLayout<IntervalLanesConfig>;

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

@@ -0,0 +1,80 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Interval (Gantt/timeline) packing + temporal-density helpers — the generic
+ * geometry behind any "events that overlap in time" view. A swimlane/Gantt
+ * layout packs concurrent intervals into sub-tracks; its natural companion is a
+ * concurrency line counting how many intervals are active over the domain.
+ *
+ * Pure / SSR-safe. Accessors may be a field name or a function.
+ */
+type Accessor<T> = string | ((item: T) => number);
+export interface PackedInterval<T> {
+    /** The original item. */
+    item: T;
+    /** Zero-based sub-track index the greedy packer assigned. Concurrent
+     *  intervals get distinct tracks; non-overlapping intervals reuse a track. */
+    track: number;
+}
+export interface PackIntervalsResult<T> {
+    /** Each input item paired with its assigned sub-track. Input order preserved
+     *  unless `sort` is left on (the default), which sorts by start ascending. */
+    packed: PackedInterval<T>[];
+    /** Number of sub-tracks used — the lane needs this many rows. */
+    trackCount: number;
+}
+export interface PackIntervalsOptions<T> {
+    /** Interval start accessor. @default `"start"` */
+    start?: Accessor<T>;
+    /** Interval end accessor. @default `"end"` */
+    end?: Accessor<T>;
+    /** Sort by start ascending (then longest-first) before packing — the stable,
+     *  gap-minimizing order. Set `false` if the input is already ordered and you
+     *  want that order preserved. @default true */
+    sort?: boolean;
+}
+/**
+ * Greedy interval packing: assign each interval to the first sub-track whose
+ * last interval has already ended, otherwise open a new track. The textbook
+ * Gantt/swimlane packer. O(n·tracks).
+ *
+ * @example
+ * ```ts
+ * const { packed, trackCount } = packIntervals(wars, { start: "startTime", end: "endTime" })
+ * // bar y = laneTop + track * (barHeight + gap)
+ * ```
+ */
+export declare function packIntervals<T = Datum>(items: readonly T[], options?: PackIntervalsOptions<T>): PackIntervalsResult<T>;
+export interface ActiveCount {
+    /** Domain position (e.g. a year). */
+    value: number;
+    /** Number of intervals active at this position. */
+    count: number;
+}
+export interface ActiveCountOptions<T> {
+    /** Interval start accessor. @default `"start"` */
+    start?: Accessor<T>;
+    /** Interval end accessor. @default `"end"` */
+    end?: Accessor<T>;
+    /** `[min, max]` domain to sample across (inclusive of both ends). */
+    domain: [number, number];
+    /** Sample spacing. @default 1 */
+    step?: number;
+    /** Count an interval active at position `v` when `start <= v <= end`
+     *  (`"closed"`, the default — natural for whole-unit intervals like years),
+     *  or when `start <= v < end` (`"half-open"`). @default "closed" */
+    bounds?: "closed" | "half-open";
+}
+/**
+ * Count how many intervals are active at each sampled position across a domain —
+ * the concurrency series you draw as a step line beneath packed interval lanes.
+ *
+ * @example
+ * ```ts
+ * const counts = activeCountOverDomain(wars, {
+ *   start: "startYear", end: "endYear", domain: [1775, 2015],
+ * })
+ * // → [{ value: 1775, count: 1 }, { value: 1776, count: 2 }, ...]
+ * ```
+ */
+export declare function activeCountOverDomain<T = Datum>(items: readonly T[], options: ActiveCountOptions<T>): ActiveCount[];
+export {};