semiotic 3.7.5 → 3.8.1

package/spec/v0.1/chart-capability.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://semiotic.dev/spec/v0.1/chart-capability.schema.json",
+  "title": "IDID Chart Capability",
+  "description": "A library-neutral, declarative description of what a chart is good at, so an agent or a heuristic engine can rank it against a dataset and an intent WITHOUT executing any rendering library. This is the serializable subset of a chart's capability — the imperative gates (fits, buildProps, scoring functions) a host library may attach are implementation details and are intentionally NOT part of the portable spec. See ./README.md for the field-status convention (x-idid-status).",
+  "type": "object",
+  "required": ["component", "rubric"],
+  "additionalProperties": true,
+  "properties": {
+    "specVersion": {
+      "type": "string",
+      "const": "0.1",
+      "description": "The IDID portability spec version this descriptor targets.",
+      "x-idid-status": "spec"
+    },
+    "component": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable name of the chart this descriptor is about (e.g. \"BarChart\", \"SankeyDiagram\"). The portable identity of the chart; how a host resolves it to a renderer is a binding concern.",
+      "x-idid-status": "shipped"
+    },
+    "family": {
+      "type": "string",
+      "description": "Coarse chart family. Open string — recognized values are listed in examples but a host may use its own taxonomy.",
+      "examples": ["xy", "ordinal", "network", "hierarchy", "geo", "value", "custom"],
+      "x-idid-status": "shipped"
+    },
+    "importPath": {
+      "type": "string",
+      "description": "Where the implementing library exposes the chart (e.g. \"semiotic/ordinal\"). Advisory; a binding may ignore it.",
+      "x-idid-status": "shipped"
+    },
+    "rubric": {
+      "$ref": "#/$defs/rubric",
+      "description": "Audience-independent base rubric, before any audience override or variant delta."
+    },
+    "intentScores": {
+      "type": "object",
+      "description": "Per-intent suitability, 0–5. Missing intents default to 0. Keys are intent ids — the 13 built-in ids are in $defs/intentId, and hosts may register custom intents (open string).",
+      "propertyNames": { "type": "string" },
+      "additionalProperties": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 5
+      },
+      "x-idid-status": "shipped"
+    },
+    "variants": {
+      "type": "array",
+      "description": "Settings that meaningfully change what the chart is good for (e.g. a streamgraph variant of a stacked area). Deltas are additive against the base intentScores/rubric and clamped to range by the consumer.",
+      "items": { "$ref": "#/$defs/variant" },
+      "x-idid-status": "shipped"
+    },
+    "caveats": {
+      "type": "array",
+      "description": "Static, audience-independent caveats this chart always carries (e.g. \"log scale skipped for negative values\"). The portable form of a host's dynamic caveat function: the host may emit additional data-dependent caveats at runtime.",
+      "items": { "type": "string" },
+      "x-idid-status": "shipped"
+    },
+    "mobile": {
+      "$ref": "#/$defs/mobile",
+      "description": "Phone-specific design contract for mobile audits and responsive adapters. This lets custom charts and interoperability-generated charts declare how they preserve the task at small widths.",
+      "x-idid-status": "shipped"
+    },
+    "tags": {
+      "type": "array",
+      "description": "Free-form classification tags consumers can filter on.",
+      "items": { "type": "string" },
+      "x-idid-status": "shipped"
+    }
+  },
+  "$defs": {
+    "rubric": {
+      "type": "object",
+      "title": "Chart Rubric",
+      "description": "Three 1–5 axes. familiarity = how well-known the chart is to a general audience; accuracy = how faithfully it represents the data; precision = how readable individual values are.",
+      "required": ["familiarity", "accuracy", "precision"],
+      "additionalProperties": false,
+      "properties": {
+        "familiarity": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "accuracy": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "precision": { "type": "integer", "minimum": 1, "maximum": 5 }
+      }
+    },
+    "variant": {
+      "type": "object",
+      "title": "Chart Variant",
+      "required": ["key", "label"],
+      "additionalProperties": true,
+      "properties": {
+        "key": { "type": "string", "description": "Stable variant identifier within the capability." },
+        "label": { "type": "string" },
+        "description": { "type": "string" },
+        "intentDeltas": {
+          "type": "object",
+          "description": "Additive per-intent score deltas (e.g. {\"trend\": 1, \"part-to-whole\": -2}).",
+          "propertyNames": { "type": "string" },
+          "additionalProperties": { "type": "number" }
+        },
+        "rubricDeltas": {
+          "type": "object",
+          "description": "Additive rubric deltas — usually small (e.g. smoothing trades precision for familiarity).",
+          "additionalProperties": false,
+          "properties": {
+            "familiarity": { "type": "number" },
+            "accuracy": { "type": "number" },
+            "precision": { "type": "number" }
+          }
+        },
+        "caveats": { "type": "array", "items": { "type": "string" } },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "props": {
+          "type": "object",
+          "description": "Implementation-specific props the host merges to realize this variant. Opaque to the spec; a non-Semiotic host may ignore it.",
+          "x-idid-status": "shipped"
+        }
+      }
+    },
+    "mobile": {
+      "type": "object",
+      "title": "Mobile Capability",
+      "additionalProperties": true,
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "description": "Overall mobile design strategy, e.g. responsive, small-multiples, summary-cards, direct-labels, fixed-artboard."
+        },
+        "responsive": { "type": "boolean" },
+        "supportsResponsiveLayout": { "type": "boolean" },
+        "breakpoints": { "type": "array", "items": { "type": "number" } },
+        "minViewportWidth": { "type": "number", "minimum": 0 },
+        "maxMarks": { "type": "number", "minimum": 0 },
+        "maxAnnotations": { "type": "number", "minimum": 0 },
+        "minimumHitTarget": { "type": "number", "minimum": 0 },
+        "summary": { "oneOf": [{ "type": "boolean" }, { "type": "string" }] },
+        "interaction": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "primary": { "type": "string" },
+            "alternatives": { "type": "array", "items": { "type": "string" } },
+            "hoverFallback": { "type": "string" },
+            "targetSize": { "type": "number", "minimum": 0 }
+          }
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "strategy": { "type": "string" },
+            "minFontSize": { "type": "number", "minimum": 0 }
+          }
+        },
+        "custom": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "dataBearingSceneNodes": { "type": "boolean" },
+            "stableIds": { "type": "boolean" },
+            "navigationGranularity": { "type": "string" }
+          }
+        }
+      }
+    },
+    "intentId": {
+      "title": "Intent",
+      "description": "Communicative intent the chart is being ranked for. The 13 built-in ids are below; hosts may register additional intents, so this is an open string in practice.",
+      "type": "string",
+      "examples": [
+        "trend",
+        "compare-series",
+        "compare-categories",
+        "rank",
+        "part-to-whole",
+        "distribution",
+        "correlation",
+        "flow",
+        "hierarchy",
+        "geo",
+        "outlier-detection",
+        "composition-over-time",
+        "change-detection"
+      ]
+    }
+  }
+}

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

@@ -1,207 +0,0 @@
-import * as React from "react";
-import type { ReactNode } from "react";
-import type { CustomLayout, LayoutContext } from "../stream/customLayout";
-import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
-import type { Datum } from "../charts/shared/datumTypes";
-import type { Style } from "../stream/types";
-import type { BezierPoint } from "../stream/networkTypes";
-export type GofishGlyphMark = {
-    kind: "rect";
-    id: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    style?: Style;
-    datum?: Datum;
-    group?: string;
-    interactive?: boolean;
-    rx?: number;
-    /** Clip this mark to an SVG path (pixel coords) — e.g. a fill to a silhouette. */
-    clipPath?: string;
-} | {
-    kind: "image";
-    id: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    href: string;
-    /** @default "none" — stretch to the box; "xMidYMid meet" to letterbox. */
-    preserveAspectRatio?: string;
-    opacity?: number;
-    /** Clip the image to an SVG path (pixel coords). */
-    clipPath?: string;
-} | {
-    kind: "circle";
-    id: string;
-    cx: number;
-    cy: number;
-    r: number;
-    style?: Style;
-    datum?: Datum;
-    group?: string;
-    interactive?: boolean;
-} | {
-    kind: "area";
-    id: string;
-    topPath: [number, number][];
-    bottomPath: [number, number][];
-    style?: Style;
-    datum?: Datum[];
-    group?: string;
-} | {
-    kind: "path";
-    id: string;
-    d: string;
-    style?: Style;
-    datum?: Datum;
-    group?: string;
-    clipPath?: string;
-} | {
-    kind: "line";
-    id: string;
-    x1: number;
-    y1: number;
-    x2: number;
-    y2: number;
-    style?: Style;
-} | {
-    kind: "text";
-    id: string;
-    x: number;
-    y: number;
-    text: ReactNode;
-    style?: Style;
-    fontSize?: number;
-    fontWeight?: number | string;
-    textAnchor?: "start" | "middle" | "end";
-    dominantBaseline?: React.SVGProps<SVGTextElement>["dominantBaseline"];
-    transform?: string;
-};
-export interface GofishGlyphLayer {
-    marks: GofishGlyphMark[];
-    overlays?: ReactNode;
-}
-export interface HitRectForGlyphOptions {
-    id: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    datum?: Datum;
-    group?: string;
-    style?: Style;
-    rx?: number;
-}
-export type GofishGlyphSolver<C extends object> = (ctx: LayoutContext<C>) => GofishGlyphLayer;
-export declare function hitRectForGlyph(options: HitRectForGlyphOptions): GofishGlyphMark;
-export declare function overlayGroup(children: ReactNode, className?: string): ReactNode;
-/**
- * Compile a small GoFish-style mark vocabulary to a Semiotic custom layout.
- *
- * Rects, circles, and areas become normal scene nodes when interactive is not
- * false, so Semiotic owns hit testing, transitions, decay, SSR evidence, and
- * tooltips. Rich glyph chrome such as petal paths, labels, bottle silhouettes,
- * and arrows is rendered as pointer-events-none SVG overlay content.
- */
-export declare function createGofishGlyphLayout<C extends object>(solve: GofishGlyphSolver<C>): CustomLayout<C>;
-export interface GofishFlowerConfig {
-    lakeAccessor?: string | ((d: Datum) => string);
-    speciesAccessor?: string | ((d: Datum) => string);
-    countAccessor?: string | ((d: Datum) => number);
-    xAccessor?: string | ((d: Datum) => number);
-    flowerRadius?: number;
-    stemWidth?: number;
-}
-export interface GofishBottleConfig {
-    categoryAccessor?: string | ((d: Datum) => string);
-    amountAccessor?: string | ((d: Datum) => number);
-    bottleWidth?: number;
-    bottleHeight?: number;
-}
-export interface GofishPolarRibbonConfig {
-    lakeAccessor?: string | ((d: Datum) => string);
-    speciesAccessor?: string | ((d: Datum) => string);
-    countAccessor?: string | ((d: Datum) => number);
-    innerRadius?: number;
-    outerRadius?: number;
-}
-export interface GofishTitanicCircleTreemapConfig {
-    classAccessor?: string | ((d: Datum) => string | number);
-    survivedAccessor?: string | ((d: Datum) => string | number | boolean);
-    fareAccessor?: string | ((d: Datum) => number);
-    padding?: number;
-}
-export interface PythonTutorPointer {
-    pointer: number;
-}
-export interface PythonTutorBinding {
-    name: string;
-    value: string | PythonTutorPointer;
-}
-export interface PythonTutorTuple {
-    values: Array<string | PythonTutorPointer>;
-}
-export interface PythonTutorDiagram {
-    stack: PythonTutorBinding[];
-    heap: PythonTutorTuple[];
-    heapArrangement: Array<Array<number | null>>;
-}
-export interface GofishPythonTutorConfig {
-    diagram?: PythonTutorDiagram;
-    cellWidth?: number;
-    cellHeight?: number;
-    heapGap?: number;
-}
-export interface PythonTutorMemoryGraph {
-    nodes: Datum[];
-    edges: Datum[];
-}
-export declare function buildPythonTutorMemoryGraph(diagram: PythonTutorDiagram): PythonTutorMemoryGraph;
-export declare const gofishFlowerLayout: CustomLayout<GofishFlowerConfig>;
-export declare const gofishBottleFillLayout: CustomLayout<GofishBottleConfig>;
-export declare const gofishPolarRibbonLayout: CustomLayout<GofishPolarRibbonConfig>;
-export declare const gofishTitanicCircleTreemapLayout: CustomLayout<GofishTitanicCircleTreemapConfig>;
-export declare const gofishPythonTutorLayout: CustomLayout<GofishPythonTutorConfig>;
-export declare const gofishPythonTutorNetworkLayout: NetworkCustomLayout<GofishPythonTutorConfig>;
-export declare function pointerCurve(start: [number, number], end: [number, number]): {
-    d: string;
-    points: [BezierPoint, BezierPoint, BezierPoint, BezierPoint];
-};
-interface TreemapStripRegion<T> {
-    id: string;
-    rows: T[];
-    value: number;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-interface PackedCircle<T> {
-    row: T;
-    index: number;
-    x: number;
-    y: number;
-    r: number;
-}
-export declare function layoutTreemapStrip<T>(entries: Array<{
-    id: string;
-    rows: T[];
-    value: number;
-    heightValue?: number;
-}>, bounds: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}, gap: number): Array<TreemapStripRegion<T>>;
-export declare function packCirclesInRect<T>(rows: T[], region: TreemapStripRegion<T>, value: (row: T) => number, gap: number): Array<PackedCircle<T>>;
-export declare function datumFromFields(fields: Record<string, unknown>): Datum;
-export declare function stableGlyphId(value: string): string;
-export declare function polarPoint(cx: number, cy: number, r: number, angle: number): [number, number];
-export declare function petalPath(cx: number, cy: number, innerR: number, outerR: number, start: number, end: number): string;
-export declare function polarBandPath(cx: number, cy: number, innerR: number, outerR: number, start: number, end: number): string;
-export declare function smoothClosedPath(points: [number, number][]): string;
-export declare function bottlePath(x: number, y: number, w: number, h: number): string;
-export {};

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

@@ -1,52 +0,0 @@
-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

@@ -1,145 +0,0 @@
-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;