gofish-ir 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# gofish-ir
+
+Serialized intermediate representation (IR) for GoFish chart specifications.
+
+This package provides the canonical TypeScript types, runtime validator, and
+(coming soon) JSON Schema for the JSON-serializable form of a GoFish chart —
+the artifact produced by the v3 fluent API at construction time, consumed by
+downstream tools (the renderer, the Python bridge, and the Olli accessibility
+adapter).
+
+## Status
+
+**v0 — frontend stage only.** This release publishes the IR captured at the
+_frontend_ of the GoFish compiler: the chart specification before macro
+expansion and elaboration. The schema matches the existing widget wire
+format exactly (lowercase `type` discriminators, `__combinator` flag on
+combinator-form marks, channel slots accept strings/numbers/sentinels). This
+is intentional — v0 is "publish what already exists" so consumers can ship
+against a typed schema today.
+
+Subsequent breaking releases will layer in the design improvements documented
+in the architecture essay at
+[`apps/docs/docs/internals/frontend/serialization.md`](../../apps/docs/docs/internals/frontend/serialization.md):
+PascalCase type tags, the `field`/`datum`/`literal` channel-expression split,
+the `__combinator` removal, side-table-free inline annotation, etc. Each is a
+lockstep migration across Python + JS + Olli.
+
+## Usage
+
+```ts
+import { Frontend } from "gofish-ir";
+
+const spec: Frontend.FrontendIRDocument = {
+  irVersion: 0,
+  ir: "gofish-frontend",
+  root: {
+    type: "chart",
+    data: { type: "inline", rows: [{ category: "A", value: 5 }] },
+    operators: [{ type: "spread", by: "category", dir: "x" }],
+    mark: { type: "rect", h: "value" },
+  },
+};
+
+const result = Frontend.validate(spec);
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+## Design
+
+See
+[`apps/docs/docs/internals/frontend/serialization.md`](../../apps/docs/docs/internals/frontend/serialization.md)
+for the full design discussion: schema-shape decisions, multi-stage strategy,
+prior-art lineage (ESTree/Babel, GHC HsSyn/HIE, Lean Syntax/Expr, Vega-Lite),
+and what v0.1+ will change.

package/dist/frontend/examples.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical example frontend-IR documents.
+ *
+ * These are the testbed for the validator and serve as worked examples for
+ * downstream consumers (Olli, the Python wrapper, alternative renderers).
+ * Each example covers a distinct shape of the schema.
+ */
+import type { FrontendIRDocument } from "./schema.js";
+/**
+ * A simple bar chart:
+ *   chart(seafood).flow(spread({by: "lake", dir: "x"}))
+ *                 .mark(rect({h: "count", fill: "species"}).name("bars"))
+ *
+ * Exercises: chart root, inline data, single operator, leaf mark with channel
+ * properties, the `.name()` user-supplied name via `origin.name`.
+ */
+export declare const exampleBarChart: FrontendIRDocument;
+/**
+ * A layer of two charts on the same canvas.
+ *
+ * Exercises: layer root, multiple chart children, the `select`-style data
+ * reference (one chart selects from a named layer in the other).
+ */
+export declare const exampleLayer: FrontendIRDocument;
+/**
+ * A scatter chart: data → scatter operator with explicit x/y channels.
+ *
+ * Exercises: scatter operator with channel values, leaf mark without label.
+ */
+export declare const exampleScatter: FrontendIRDocument;
+/**
+ * A treemap, built combinator-form: a `treemap` combinator wraps rect leaves.
+ *
+ * Exercises: combinator-form mark in the mark tree (with `__combinator: true`),
+ * nested children.
+ */
+export declare const exampleTreemap: FrontendIRDocument;
+/**
+ * A bare mark not wrapped in a chart (e.g. an icon or static decoration).
+ *
+ * Exercises: raw-mark root, simple leaf mark with literal channel values.
+ */
+export declare const exampleCustomMark: FrontendIRDocument;
+export declare const allExamples: ReadonlyArray<{
+    name: string;
+    doc: FrontendIRDocument;
+}>;
+//# sourceMappingURL=examples.d.ts.map

package/dist/frontend/examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../../src/frontend/examples.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,kBAuB7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,kBAmB1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,kBAgB5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,kBAoB5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,kBAa/B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,kBAAkB,CAAC;CACzB,CAMA,CAAC"}

package/dist/frontend/examples.js

@@ -0,0 +1,140 @@
+/**
+ * Canonical example frontend-IR documents.
+ *
+ * These are the testbed for the validator and serve as worked examples for
+ * downstream consumers (Olli, the Python wrapper, alternative renderers).
+ * Each example covers a distinct shape of the schema.
+ */
+/**
+ * A simple bar chart:
+ *   chart(seafood).flow(spread({by: "lake", dir: "x"}))
+ *                 .mark(rect({h: "count", fill: "species"}).name("bars"))
+ *
+ * Exercises: chart root, inline data, single operator, leaf mark with channel
+ * properties, the `.name()` user-supplied name via `origin.name`.
+ */
+export const exampleBarChart = {
+    irVersion: 0,
+    ir: "gofish-frontend",
+    root: {
+        type: "chart",
+        data: {
+            type: "inline",
+            rows: [
+                { lake: "A", species: "trout", count: 12 },
+                { lake: "A", species: "bass", count: 8 },
+                { lake: "B", species: "trout", count: 5 },
+                { lake: "B", species: "bass", count: 14 },
+            ],
+        },
+        operators: [{ type: "spread", by: "lake", dir: "x" }],
+        mark: {
+            type: "rect",
+            origin: { name: "bars" },
+            h: "count",
+            fill: "species",
+        },
+        options: { w: 500, h: 300, axes: true },
+    },
+};
+/**
+ * A layer of two charts on the same canvas.
+ *
+ * Exercises: layer root, multiple chart children, the `select`-style data
+ * reference (one chart selects from a named layer in the other).
+ */
+export const exampleLayer = {
+    irVersion: 0,
+    ir: "gofish-frontend",
+    root: {
+        type: "layer",
+        charts: [
+            {
+                type: "chart",
+                data: { type: "inline", rows: [{ x: 1, y: 2 }] },
+                operators: [{ type: "scatter", x: "x", y: "y" }],
+                mark: { type: "circle", origin: { name: "points" }, r: 4 },
+            },
+            {
+                type: "chart",
+                data: { type: "select", layer: "points" },
+                mark: { type: "ref", selection: "points" },
+            },
+        ],
+    },
+};
+/**
+ * A scatter chart: data → scatter operator with explicit x/y channels.
+ *
+ * Exercises: scatter operator with channel values, leaf mark without label.
+ */
+export const exampleScatter = {
+    irVersion: 0,
+    ir: "gofish-frontend",
+    root: {
+        type: "chart",
+        data: {
+            type: "inline",
+            rows: [
+                { mpg: 22, hp: 110 },
+                { mpg: 19, hp: 150 },
+                { mpg: 30, hp: 88 },
+            ],
+        },
+        operators: [{ type: "scatter", x: "hp", y: "mpg" }],
+        mark: { type: "circle", r: 3, fill: "steelblue" },
+    },
+};
+/**
+ * A treemap, built combinator-form: a `treemap` combinator wraps rect leaves.
+ *
+ * Exercises: combinator-form mark in the mark tree (with `__combinator: true`),
+ * nested children.
+ */
+export const exampleTreemap = {
+    irVersion: 0,
+    ir: "gofish-frontend",
+    root: {
+        type: "chart",
+        data: {
+            type: "inline",
+            rows: [
+                { region: "north", value: 100 },
+                { region: "south", value: 60 },
+                { region: "east", value: 80 },
+            ],
+        },
+        mark: {
+            type: "treemap",
+            __combinator: true,
+            options: { valueField: "value" },
+            children: [{ type: "rect", fill: "region" }],
+        },
+    },
+};
+/**
+ * A bare mark not wrapped in a chart (e.g. an icon or static decoration).
+ *
+ * Exercises: raw-mark root, simple leaf mark with literal channel values.
+ */
+export const exampleCustomMark = {
+    irVersion: 0,
+    ir: "gofish-frontend",
+    root: {
+        type: "raw-mark",
+        mark: {
+            type: "text",
+            origin: { name: "title" },
+            text: "Catch by Lake",
+            fontSize: 16,
+        },
+        options: { w: 200, h: 40 },
+    },
+};
+export const allExamples = [
+    { name: "bar chart", doc: exampleBarChart },
+    { name: "layer", doc: exampleLayer },
+    { name: "scatter", doc: exampleScatter },
+    { name: "treemap", doc: exampleTreemap },
+    { name: "raw-mark", doc: exampleCustomMark },
+];

package/dist/frontend/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./schema.js";
+export { validate, type ValidationResult, type ValidationError, } from "./validate.js";
+export { exampleBarChart, exampleLayer, exampleScatter, exampleTreemap, exampleCustomMark, allExamples, } from "./examples.js";
+export { FRONTEND_IR_JSON_SCHEMA } from "./jsonSchema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/frontend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/frontend/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,QAAQ,EACR,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/frontend/index.js

@@ -0,0 +1,4 @@
+export * from "./schema.js";
+export { validate, } from "./validate.js";
+export { exampleBarChart, exampleLayer, exampleScatter, exampleTreemap, exampleCustomMark, allExamples, } from "./examples.js";
+export { FRONTEND_IR_JSON_SCHEMA } from "./jsonSchema.js";

package/dist/frontend/jsonSchema.d.ts

@@ -0,0 +1,393 @@
+/**
+ * Hand-written JSON Schema for the GoFish frontend IR (v0).
+ *
+ * Structural only — defines the document shape, the discriminator unions
+ * for operators / marks / channel values, and the validity envelope. Full
+ * field-level coverage matches `validate.ts`; this file is the wire
+ * artifact (consumed by external tooling, language servers, and the
+ * Python wrapper's parity-test harness).
+ */
+export declare const FRONTEND_IR_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://gofish.graphics/schema/frontend/v0.json";
+    readonly title: "GoFish Frontend IR";
+    readonly description: "Source-level chart specification produced by the v3 fluent API.";
+    readonly type: "object";
+    readonly required: readonly ["irVersion", "ir", "root"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly irVersion: {
+            readonly const: 0;
+        };
+        readonly ir: {
+            readonly const: "gofish-frontend";
+        };
+        readonly $schema: {
+            readonly type: "string";
+        };
+        readonly root: {
+            readonly $ref: "#/$defs/Root";
+        };
+    };
+    readonly $defs: {
+        readonly Root: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/ChartIR";
+            }, {
+                readonly $ref: "#/$defs/LayerIR";
+            }, {
+                readonly $ref: "#/$defs/RawMarkIR";
+            }];
+        };
+        readonly Origin: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly stack: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly Meta: {
+            readonly type: "object";
+            readonly description: "Optional inline annotations populated by later passes. v0 emitters leave it absent.";
+        };
+        readonly DataIR: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["type", "rows"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "inline";
+                    };
+                    readonly rows: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                        };
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["type", "layer"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "select";
+                    };
+                    readonly layer: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["type"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "external";
+                    };
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly ChartIR: {
+            readonly type: "object";
+            readonly required: readonly ["type", "mark"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "chart";
+                };
+                readonly data: {
+                    readonly oneOf: readonly [{
+                        readonly $ref: "#/$defs/DataIR";
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly operators: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/OperatorIR";
+                    };
+                };
+                readonly mark: {
+                    readonly $ref: "#/$defs/MarkIR";
+                };
+                readonly options: {
+                    readonly type: "object";
+                };
+                readonly zOrder: {
+                    readonly type: "number";
+                };
+                readonly origin: {
+                    readonly $ref: "#/$defs/Origin";
+                };
+                readonly meta: {
+                    readonly $ref: "#/$defs/Meta";
+                };
+            };
+        };
+        readonly LayerIR: {
+            readonly type: "object";
+            readonly required: readonly ["type", "charts"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "layer";
+                };
+                readonly charts: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ChartIR";
+                    };
+                };
+                readonly options: {
+                    readonly type: "object";
+                };
+                readonly origin: {
+                    readonly $ref: "#/$defs/Origin";
+                };
+                readonly meta: {
+                    readonly $ref: "#/$defs/Meta";
+                };
+            };
+        };
+        readonly RawMarkIR: {
+            readonly type: "object";
+            readonly required: readonly ["type", "mark"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "raw-mark";
+                };
+                readonly mark: {
+                    readonly $ref: "#/$defs/MarkIR";
+                };
+                readonly options: {
+                    readonly type: "object";
+                };
+                readonly origin: {
+                    readonly $ref: "#/$defs/Origin";
+                };
+                readonly meta: {
+                    readonly $ref: "#/$defs/Meta";
+                };
+            };
+        };
+        readonly OperatorIR: {
+            readonly type: "object";
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly enum: readonly ["derive", "spread", "stack", "group", "scatter", "table", "log"];
+                };
+            };
+        };
+        readonly MarkIR: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/LeafMarkIR";
+            }, {
+                readonly $ref: "#/$defs/CombinatorMarkIR";
+            }, {
+                readonly $ref: "#/$defs/RefMarkIR";
+            }];
+        };
+        readonly LeafMarkIR: {
+            readonly type: "object";
+            readonly required: readonly ["type"];
+            readonly properties: {
+                readonly type: {
+                    readonly enum: readonly ["rect", "circle", "line", "area", "blank", "ellipse", "petal", "text", "image", "polygon", "mark-fn"];
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly label: {
+                    readonly $ref: "#/$defs/LabelIR";
+                };
+                readonly constraints: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ConstraintIR";
+                    };
+                };
+                readonly zOrder: {
+                    readonly type: "number";
+                };
+            };
+        };
+        readonly CombinatorMarkIR: {
+            readonly type: "object";
+            readonly required: readonly ["type", "__combinator", "children"];
+            readonly properties: {
+                readonly type: {
+                    readonly enum: readonly ["spread", "stack", "scatter", "group", "table", "layer", "arrow", "connect", "treemap", "over", "inside", "xor", "out", "atop", "mask"];
+                };
+                readonly __combinator: {
+                    readonly const: true;
+                };
+                readonly options: {
+                    readonly type: "object";
+                };
+                readonly children: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/MarkIR";
+                    };
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly label: {
+                    readonly $ref: "#/$defs/LabelIR";
+                };
+                readonly constraints: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ConstraintIR";
+                    };
+                };
+                readonly zOrder: {
+                    readonly type: "number";
+                };
+            };
+        };
+        readonly RefMarkIR: {
+            readonly type: "object";
+            readonly required: readonly ["type", "selection"];
+            readonly properties: {
+                readonly type: {
+                    readonly const: "ref";
+                };
+                readonly selection: {
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                    }, {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly oneOf: readonly [{
+                                readonly type: "string";
+                            }, {
+                                readonly type: "number";
+                            }];
+                        };
+                    }];
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly label: {
+                    readonly $ref: "#/$defs/LabelIR";
+                };
+                readonly zOrder: {
+                    readonly type: "number";
+                };
+            };
+        };
+        readonly LabelIR: {
+            readonly oneOf: readonly [{
+                readonly type: "boolean";
+            }, {
+                readonly type: "string";
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["accessor"];
+                readonly properties: {
+                    readonly accessor: {
+                        readonly type: "string";
+                    };
+                    readonly position: {
+                        readonly type: "string";
+                    };
+                    readonly fontSize: {
+                        readonly type: "number";
+                    };
+                    readonly color: {
+                        readonly type: "string";
+                    };
+                    readonly offset: {
+                        readonly type: "number";
+                    };
+                    readonly minSpace: {
+                        readonly type: "number";
+                    };
+                    readonly rotate: {
+                        readonly type: "number";
+                    };
+                };
+            }];
+        };
+        readonly ConstraintIR: {
+            readonly type: "object";
+            readonly required: readonly ["type", "refs"];
+            readonly properties: {
+                readonly type: {
+                    readonly enum: readonly ["align", "distribute", "zAbove", "zBelow"];
+                };
+                readonly options: {
+                    readonly type: "object";
+                };
+                readonly refs: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly ChannelValue: {
+            readonly description: "Right-hand side of a channel slot. Bare primitives for the shorthand path; tagged objects for the explicit field/datum/literal constructors and Python-bridge sentinels.";
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "number";
+            }, {
+                readonly type: "boolean";
+            }, {
+                readonly type: "null";
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["type", "name"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "field";
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["type", "value"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "literal";
+                    };
+                    readonly value: {};
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["type", "datum"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "datum";
+                    };
+                    readonly datum: {};
+                    readonly measure: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["__gofish_lambda"];
+                readonly properties: {
+                    readonly __gofish_lambda: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+    };
+};
+//# sourceMappingURL=jsonSchema.d.ts.map

package/dist/frontend/jsonSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonSchema.d.ts","sourceRoot":"","sources":["../../src/frontend/jsonSchema.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsR1B,CAAC"}