@ggts-sh/spec 0.43.0

package/src/artifact.ts

@@ -0,0 +1,81 @@
+/**
+ * JSON Schema artifact builder (decision 0004: TypeBox `Type.Module`
+ * named-defs form is the shippable schema).
+ *
+ * Publish-time transforms applied here, exactly as the decision record
+ * prescribes:
+ *  1. `$ref: "Name"` (TypeBox $id-anchored refs) -> `#/$defs/Name`
+ *     (standard JSON Pointer form; strict provider subsets need it).
+ *  2. `patternProperties: { "^(.*)$": S }` (TypeBox `Type.Record` emission)
+ *     -> `additionalProperties: S` (semantically identical for that pattern,
+ *     and inside the portable keyword set).
+ *  3. Per-def `$id` markers removed (the artifact anchors defs under $defs).
+ *
+ * `scripts/emit-schema.ts` writes the result to `schema/v0.json`; a test
+ * asserts the committed artifact matches a fresh build (staleness guard).
+ */
+import { PlotSpecSchema } from "./schema.js";
+
+// TypeBox 0.x emitted `^(.*)$`; TypeBox 1.x emits `^.*$`. Both are
+// "match any property name" records and rewrite to additionalProperties.
+const RECORD_PATTERNS = new Set(["^(.*)$", "^.*$"]);
+
+function transform(node: unknown, defNames: ReadonlySet<string>): unknown {
+  if (Array.isArray(node)) return node.map((n) => transform(n, defNames));
+  if (typeof node !== "object" || node === null) return node;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    if (key === "$id" && typeof value === "string" && defNames.has(value)) continue;
+    if (key === "$ref" && typeof value === "string" && defNames.has(value)) {
+      out[key] = `#/$defs/${value}`;
+      continue;
+    }
+    if (
+      key === "patternProperties" &&
+      typeof value === "object" &&
+      value !== null &&
+      Object.keys(value).length === 1
+    ) {
+      const pattern = Object.keys(value)[0]!;
+      if (RECORD_PATTERNS.has(pattern)) {
+        out["additionalProperties"] = transform(
+          (value as Record<string, unknown>)[pattern],
+          defNames,
+        );
+        continue;
+      }
+    }
+    out[key] = transform(value, defNames);
+  }
+  return out;
+}
+
+/** Version tag of the published schema artifact (`schema/v0.json`). */
+export const SCHEMA_VERSION = "v0";
+
+/**
+ * Build the publishable JSON Schema document (plain data, deterministic).
+ * The v0 schema remains explicitly unstable; served from the repo until
+ * hosting infrastructure exists (no $id URL is claimed yet).
+ */
+export function buildSchemaArtifact(): Record<string, unknown> {
+  // JSON round-trip drops TypeBox's symbol keys and proves JSON-plainness.
+  const raw = JSON.parse(JSON.stringify(PlotSpecSchema)) as {
+    $defs: Record<string, unknown>;
+    $ref: string;
+  };
+  const defNames = new Set(Object.keys(raw.$defs));
+  const transformed = transform(raw, defNames) as Record<string, unknown>;
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "ggts PortableSpec",
+    description:
+      "A ggts plot specification (schema v0 — UNSTABLE; served from the repo until schema hosting exists).",
+    ...transformed,
+  };
+}
+
+/** The artifact serialized exactly as `schema/v0.json` is committed. */
+export function schemaArtifactJSON(): string {
+  return JSON.stringify(buildSchemaArtifact(), null, 2) + "\n";
+}

package/src/builder-core.ts

@@ -0,0 +1,276 @@
+/**
+ * Fluent builder core: state, layer/facet/coord/labs/theme/spec.
+ * Geom sugar mixin: builder-geoms.ts. Scale sugar mixin: builder-scales.ts.
+ * Public GGBuilder: builder.ts.
+ */
+import {
+  coordFixed,
+  coordPolar,
+  coordRadial,
+  coordSf,
+  coordTransform,
+  type CoordFixedOptions,
+  type CoordPolarOptions,
+  type CoordRadialOptions,
+  type CoordSfOptions,
+  type CoordTransformOptions,
+} from "./coord-helpers.js";
+import type { AesInput, FacetInput, LayerInput, SpecInput } from "./normalize.js";
+import { normalize } from "./normalize.js";
+import {
+  calendarDateFields,
+  toAuthoringDataRef,
+  toDataRef,
+  type AuthoringDataRef,
+  type DataInput,
+} from "./builder-data.js";
+import type {
+  A11yMode,
+  GuidesSpec,
+  Labs,
+  LegendSpec,
+  PortableSpec,
+  PositionParams,
+  RenderBackend,
+  Scales,
+  ThemeName,
+  ThemeSpec,
+} from "./schema.js";
+import type { GGBuilder } from "./builder.js";
+
+interface BuilderState {
+  readonly data?: AuthoringDataRef;
+  readonly aes?: AesInput;
+  readonly layers: readonly LayerInput[];
+  readonly facet?: FacetInput;
+  readonly coord?: SpecInput["coord"];
+  readonly a11y?: A11yMode;
+  readonly scales?: Scales;
+  readonly guides?: GuidesSpec;
+  readonly legend?: LegendSpec;
+  readonly labs?: Labs;
+  readonly theme?: ThemeName | ThemeSpec;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/** Assemble a LayerInput from a geom name and sugar options. */
+export function layerFrom(
+  geom: LayerInput["geom"],
+  options: {
+    aes?: AesInput;
+    render?: RenderBackend;
+    position?: string;
+    positionParams?: PositionParams;
+    stat?: string;
+    data?: DataInput;
+    inspect?: false;
+  },
+): LayerInput {
+  const {
+    aes: layerAes,
+    render,
+    position,
+    positionParams,
+    stat,
+    data,
+    inspect,
+    ...params
+  } = options;
+  // Do not snapshot here: every geom sugar path is `this.layer(layerFrom(...))`,
+  // and `layer()` is the single defensive-copy point (#1280). Snapshotting in
+  // both places deep-copied every row twice on `geom*({ data })`.
+  const withData = data === undefined ? {} : { data: data as LayerInput["data"] };
+  return {
+    geom,
+    ...(stat !== undefined && { stat }),
+    ...(position !== undefined && { position }),
+    ...(positionParams !== undefined && { positionParams }),
+    ...(render !== undefined && { render }),
+    ...(inspect !== undefined && { inspect }),
+    ...(layerAes !== undefined && { aes: layerAes }),
+    ...withData,
+    ...(Object.keys(params).length > 0 && { params }),
+  } as LayerInput;
+}
+
+/**
+ * Immutable plot builder core (layer/facet/coord/labs/theme/spec).
+ * Geom sugar: WithBuilderGeoms. Scale sugar: WithBuilderScales.
+ * Final public class is GGBuilder (builder.ts). Not a public package export.
+ */
+export class GGBuilderCore {
+  readonly #state: BuilderState;
+
+  constructor(state: BuilderState) {
+    this.#state = state;
+  }
+
+  /**
+   * Clone with a state patch. Uses `this.constructor` so the WithBuilderScales
+   * subclass (GGBuilder) is preserved across immutable transitions.
+   */
+  #with(patch: Partial<BuilderState>): GGBuilder {
+    return new (this.constructor as new (state: BuilderState) => GGBuilder)({
+      ...this.#state,
+      ...patch,
+    });
+  }
+
+  /** Add a layer (canonical form — the geom* methods are sugar for this). */
+  layer(layer: LayerInput): GGBuilder {
+    // Sole snapshot for layer data: geom sugar and direct `.layer({ data })`
+    // both land here. Later mutation of caller-owned arrays cannot leak into
+    // `.spec()`; portable Date→ISO conversion still happens in `toPortable`.
+    if (layer.data === undefined) {
+      return this.#with({ layers: [...this.#state.layers, layer] });
+    }
+    // layer.data may be raw DataInput (geom sugar) or an AuthoringDataRef
+    // already; toAuthoringDataRef accepts both.
+    const snapped = {
+      ...layer,
+      data: toAuthoringDataRef(layer.data),
+    } as LayerInput;
+    return this.#with({ layers: [...this.#state.layers, snapped] });
+  }
+
+  /**
+   * Facet into small multiples: wrap form ({ wrap, ncol? }) or grid form
+   * ({ rows, cols }). Bare strings are field shorthand. Field objects accept
+   * closed `levels` order and a display `labels` map. `strip.position` is
+   * top/bottom/left/right (default top); `strip.show: false` hides strip
+   * chrome. scales controls per-panel positional-scale freedom ("fixed" default).
+   */
+  facet(facet: FacetInput): GGBuilder {
+    return this.#with({ facet });
+  }
+
+  /** Set the coordinate system ("flip" is shorthand for { type: "flip" }). */
+  coord(coord: SpecInput["coord"] | "flip"): GGBuilder {
+    return this.#with({ coord: coord === "flip" ? { type: "flip" } : coord });
+  }
+
+  /** Sugar for .coord("flip") — THE horizontal-composition mechanism. */
+  coordFlip(): GGBuilder {
+    return this.coord("flip");
+  }
+
+  /** Configure a post-stat coordinate transform (distinct from scale transforms). */
+  coordTransform(options: CoordTransformOptions = {}): GGBuilder {
+    return this.coord(coordTransform(options));
+  }
+
+  /** Preserve a physical y-unit/x-unit ratio in the fitted data rectangle. */
+  coordFixed(options: CoordFixedOptions = {}): GGBuilder {
+    return this.coord(coordFixed(options));
+  }
+
+  /** Equal-unit spelling of coordFixed(). */
+  coordEqual(options: CoordFixedOptions = {}): GGBuilder {
+    return this.coord(coordFixed(options));
+  }
+
+  /**
+   * Fixed-aspect coordinates for already-projected geom_sf maps (ggplot2
+   * coord_sf subset; #809). No CRS reproject in v1.
+   */
+  coordSf(options: CoordSfOptions = {}): GGBuilder {
+    return this.coord(coordSf(options));
+  }
+
+  /**
+   * Polar/radial coordinates (ggplot2 coord_radial). Pie charts use
+   * theta: "y" with expand: false on a stacked bar/col.
+   */
+  coordRadial(options: CoordRadialOptions = {}): GGBuilder {
+    return this.coord(coordRadial(options));
+  }
+
+  /**
+   * ggplot2 coord_polar alias — emits type "radial" with polar defaults
+   * (clip on; direction -1 → reverse theta).
+   */
+  coordPolar(options: CoordPolarOptions = {}): GGBuilder {
+    return this.coord(coordPolar(options));
+  }
+
+  /** Set the accessibility mode ("force-svg" keeps every layer in SVG). */
+  a11y(mode: A11yMode): GGBuilder {
+    return this.#with({ a11y: mode });
+  }
+
+  /** Configure scales (merged per scale over previous calls). */
+  scales(scales: Scales): GGBuilder {
+    return this.#with({ scales: { ...this.#state.scales, ...scales } });
+  }
+
+  /** Configure appearance-only guides (merged per aesthetic over previous calls). */
+  guides(guides: GuidesSpec): GGBuilder {
+    return this.#with({ guides: { ...this.#state.guides, ...guides } });
+  }
+
+  /** Configure the legacy legend entry order (merged over previous calls). */
+  legend(legend: LegendSpec): GGBuilder {
+    return this.#with({ legend: { ...this.#state.legend, ...legend } });
+  }
+
+  /** Set the theme: a registered name or an object with role overrides. */
+  theme(theme: ThemeName | ThemeSpec): GGBuilder {
+    return this.#with({ theme });
+  }
+
+  /** Set human-readable labels (merged over previously set labels). */
+  labs(labs: Labs): GGBuilder {
+    return this.#with({ labs: { ...this.#state.labs, ...labs } });
+  }
+
+  /**
+   * Normalize only: channel shorthand, geom defaults, aes inheritance.
+   * Does not load TypeBox — the render pipeline runs structural gates; agents
+   * that need full schema validation should call {@link spec} (full package)
+   * or `validate()` explicitly.
+   */
+  toPortable(): PortableSpec {
+    const {
+      data,
+      aes: plotAes,
+      layers,
+      facet,
+      coord,
+      a11y,
+      scales,
+      guides,
+      legend,
+      labs,
+      theme,
+      width,
+      height,
+    } = this.#state;
+    const calendarFields = calendarDateFields(this.#state);
+    const portableLayers = layers.map((layer) => {
+      if (layer.data === undefined) return layer;
+      // layer() stores AuthoringDataRef snapshots as LayerInput.data; portable
+      // ISO conversion runs here with the final calendar-date field set.
+      return {
+        ...layer,
+        data: toDataRef(layer.data, calendarFields),
+      };
+    });
+    const input: SpecInput = {
+      ...(data !== undefined && { data: toDataRef(data, calendarFields) }),
+      ...(plotAes !== undefined && { aes: plotAes }),
+      layers: portableLayers,
+      ...(facet !== undefined && { facet }),
+      ...(coord !== undefined && { coord }),
+      ...(a11y !== undefined && { a11y }),
+      ...(scales !== undefined && { scales }),
+      ...(guides !== undefined && { guides }),
+      ...(legend !== undefined && { legend }),
+      ...(labs !== undefined && { labs }),
+      ...(theme !== undefined && { theme }),
+      ...(width !== undefined && { width }),
+      ...(height !== undefined && { height }),
+    };
+    return normalize(input);
+  }
+}

package/src/builder-data.ts

@@ -0,0 +1,156 @@
+/**
+ * Builder/Svelte authoring data conversion.
+ *
+ * Accepts rows, columns, or named DataRef forms with Date cells; snapshots
+ * inputs immutably for `gg()`; and materializes portable CellValue data
+ * (ISO date/datetime strings) for `.spec()`. Geom sugar and GGBuilder live
+ * in builder.ts.
+ */
+
+import type { AesInput } from "./normalize.js";
+import type { CellValue, DataRef, Scales } from "./schema.js";
+
+/** A builder/Svelte data cell. Dates canonicalize to ISO before validation. */
+export type AuthoringCellValue = CellValue | Date;
+export type AuthoringRows = readonly Readonly<Record<string, AuthoringCellValue>>[];
+export type AuthoringColumns = Readonly<Record<string, readonly AuthoringCellValue[]>>;
+export type AuthoringDataRef =
+  | { values: AuthoringRows }
+  | { columns: AuthoringColumns }
+  | { name: string };
+
+/** Data accepted by gg(): authoring rows, columns, or a data reference. */
+export type DataInput = AuthoringRows | AuthoringColumns | AuthoringDataRef;
+
+function isDataRef(data: DataInput): data is AuthoringDataRef {
+  if (Array.isArray(data)) return false;
+  const keys = Object.keys(data);
+  if (keys.length !== 1) return false;
+  const key = keys[0]!;
+  if (key === "name") return typeof (data as { name: unknown }).name === "string";
+  if (key === "values") return Array.isArray((data as { values: unknown }).values);
+  if (key === "columns") {
+    const columns = (data as { columns: unknown }).columns;
+    return typeof columns === "object" && columns !== null && !Array.isArray(columns);
+  }
+  return false;
+}
+
+function snapshotCell(value: AuthoringCellValue): AuthoringCellValue {
+  return value instanceof Date ? new Date(value.getTime()) : value;
+}
+
+/** True when any cell is a Date (needs clone-on-snapshot / ISO materialization). */
+function columnHasDate(values: readonly AuthoringCellValue[]): boolean {
+  for (let i = 0; i < values.length; i++) {
+    if (values[i] instanceof Date) return true;
+  }
+  return false;
+}
+
+function snapshotRows(rows: AuthoringRows): Record<string, AuthoringCellValue>[] {
+  return rows.map((row) =>
+    Object.fromEntries(Object.entries(row).map(([key, value]) => [key, snapshotCell(value)])),
+  );
+}
+
+function snapshotColumns(columns: AuthoringColumns): Record<string, AuthoringCellValue[]> {
+  return Object.fromEntries(
+    Object.entries(columns).map(([key, values]) => {
+      // No Date cells: shallow-copy the column (slice) instead of per-cell map.
+      // Isolates length/index mutation; ~4× faster on 30k-point competitive data.
+      if (!columnHasDate(values)) return [key, values.slice()];
+      return [key, values.map((value) => snapshotCell(value))];
+    }),
+  );
+}
+
+export function toAuthoringDataRef(data: DataInput): AuthoringDataRef {
+  if (Array.isArray(data)) return { values: snapshotRows(data as AuthoringRows) };
+  if (isDataRef(data)) {
+    if ("name" in data) return data;
+    if ("values" in data) return { values: snapshotRows(data.values) };
+    return { columns: snapshotColumns(data.columns) };
+  }
+  return { columns: snapshotColumns(data as AuthoringColumns) };
+}
+
+function portableCell(value: AuthoringCellValue, calendarDate: boolean): CellValue {
+  if (!(value instanceof Date)) return value;
+  const iso = value.toISOString();
+  return calendarDate ? iso.slice(0, 10) : iso;
+}
+
+function portableRows(
+  rows: AuthoringRows,
+  calendarFields: ReadonlySet<string>,
+): Record<string, CellValue>[] {
+  return rows.map((row) =>
+    Object.fromEntries(
+      Object.entries(row).map(([key, value]) => [
+        key,
+        portableCell(value, calendarFields.has(key)),
+      ]),
+    ),
+  );
+}
+
+function portableColumns(
+  columns: AuthoringColumns,
+  calendarFields: ReadonlySet<string>,
+): Record<string, CellValue[]> {
+  return Object.fromEntries(
+    Object.entries(columns).map(([key, values]) => {
+      // Already-snapshotted non-Date columns need no ISO rewrite — share the
+      // array. Second O(n) map was a top cost on line-3×10k toPortable().
+      if (!calendarFields.has(key) && !columnHasDate(values)) {
+        return [key, values as CellValue[]];
+      }
+      return [key, values.map((value) => portableCell(value, calendarFields.has(key)))];
+    }),
+  );
+}
+
+export function toDataRef(data: AuthoringDataRef, calendarFields: ReadonlySet<string>): DataRef {
+  if ("name" in data) return data;
+  if ("values" in data) return { values: portableRows(data.values, calendarFields) };
+  return { columns: portableColumns(data.columns, calendarFields) };
+}
+
+function mappedField(value: AesInput[keyof AesInput]): string | null {
+  if (typeof value === "string") return value;
+  return value !== undefined && value !== null && "field" in value ? value.field : null;
+}
+
+/** Minimal state slice needed to decide calendar-date ISO truncation. */
+export interface BuilderCalendarSource {
+  readonly aes?: AesInput;
+  readonly layers: readonly { readonly aes?: AesInput }[];
+  readonly scales?: Scales;
+}
+
+/** Fields mapped on scales with temporalKind "date" (calendar ISO date cells). */
+export function calendarDateFields(state: BuilderCalendarSource): ReadonlySet<string> {
+  const fields = new Set<string>();
+  const mappings = [
+    ["x", ["x", "xmin", "xmax", "xend"]],
+    ["y", ["y", "ymin", "ymax", "yend"]],
+    ["color", ["color"]],
+    ["fill", ["fill"]],
+    ["size", ["size"]],
+    ["linewidth", ["linewidth"]],
+    ["alpha", ["alpha"]],
+  ] as const;
+  for (const [scale, channels] of mappings) {
+    if (state.scales?.[scale]?.temporalKind !== "date") continue;
+    for (const channel of channels) {
+      const plotField = mappedField(state.aes?.[channel]);
+      if (plotField !== null) fields.add(plotField);
+      for (const layer of state.layers) {
+        const layerField = mappedField(layer.aes?.[channel]);
+        if (layerField !== null) fields.add(layerField);
+      }
+    }
+  }
+  return fields;
+}