ggaction 0.0.16 → 0.0.18

package/src/persistence.js

@@ -1,10 +1,16 @@
 import { ChartProgram } from "./ChartProgram.js";
 import { BasicChartProgram } from "./BasicChartProgram.js";
-import { cloneAndFreeze } from "./core/immutable.js";
+import { cloneAndFreeze, freezeOwned } from "./core/immutable.js";
 import { hasRegisteredExtension, isBuiltinProgramClass } from "./core/extensionRegistry.js";
 import { packageVersion } from "./version.js";
-import { decodeValue, encodeValue, invalidSnapshot } from "./persistence/codec.js";
+import { decodeValue, encodeValue, encodeSharedValue, invalidSnapshot } from "./persistence/codec.js";
 import { exactKeys, requireObject, STATE_KEYS, validateGraphic, validateProgramState, validateTrace } from "./persistence/validation.js";
+import {
+  deriveTransformSchema,
+  inferDatasetSchema,
+  validateDatasetSchema
+} from "./grammar/datasetSchema.js";
+import { restoreResolvedScaleBindings } from "./actions/scales/preview.js";
 
 function canonicalState(program, extensions, path = "payload") {
   if (!(program instanceof ChartProgram || program instanceof BasicChartProgram) || !isBuiltinProgramClass(program.constructor)) {
@@ -19,7 +25,7 @@ function canonicalState(program, extensions, path = "payload") {
 }
 
 function envelope(kind, payload, extensions = []) {
-  return JSON.stringify({ schemaVersion: 1, kind, packageVersion, extensions, payload: encodeValue(payload) });
+  return JSON.stringify({ schemaVersion: kind === "editable" ? 3 : 1, kind, packageVersion, extensions, payload: kind === "editable" ? encodeSharedValue(payload) : encodeValue(payload) });
 }
 
 function readEnvelope(text, kind) {
@@ -27,24 +33,87 @@ function readEnvelope(text, kind) {
   let value;
   try { value = JSON.parse(text); } catch { throw invalidSnapshot("Snapshot must be valid JSON.", "snapshot"); }
   exactKeys(value, ["schemaVersion", "kind", "packageVersion", "extensions", "payload"], "snapshot");
-  if (value.schemaVersion !== 1 || value.kind !== kind) throw invalidSnapshot(`Unsupported snapshot schema or kind; expected schema 1 ${kind}.`, "snapshot");
+  const versions = kind === "editable" ? [1, 2, 3] : [1];
+  if (!versions.includes(value.schemaVersion) || value.kind !== kind) {
+    throw invalidSnapshot(
+      `Unsupported snapshot schema or kind; expected schema ${versions.join(" or ")} ${kind}.`,
+      "snapshot"
+    );
+  }
   if (typeof value.packageVersion !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value.packageVersion)) throw invalidSnapshot("Invalid snapshot packageVersion.", "snapshot.packageVersion");
   if (!Array.isArray(value.extensions) || new Set(value.extensions).size !== value.extensions.length ||
       value.extensions.some(name => typeof name !== "string" || !hasRegisteredExtension(name)) || (kind === "graphic" && value.extensions.length)) {
     throw invalidSnapshot("Snapshot requires unknown, duplicate, or inapplicable extensions.", "snapshot.extensions");
   }
+  if (value.schemaVersion < 3 && value.payload?.[0] === "shared") {
+    throw invalidSnapshot("Shared array payloads require editable snapshot version 3.", "snapshot.payload");
+  }
   return { ...value, payload: decodeValue(value.payload) };
 }
 
-function restoreState(state, extensions, path = "payload") {
+function restoreState(state, extensions, path = "payload", { requireSchemas = false } = {}) {
   exactKeys(state, STATE_KEYS, path);
   if (!Array.isArray(state.actionStack) || state.actionStack.length) throw invalidSnapshot("Snapshot actionStack must be empty.", `${path}.actionStack`);
   requireObject(state.children, `${path}.children`);
   validateTrace(state.trace, ChartProgram, extensions, `${path}.trace`);
-  const children = Object.fromEntries(Object.entries(state.children).map(([id, child]) => [id, restoreState(child, extensions, `${path}.children.${id}`)]));
+  const children = Object.fromEntries(Object.entries(state.children).map(([id, child]) => [id, restoreState(
+    child,
+    extensions,
+    `${path}.children.${id}`,
+    { requireSchemas }
+  )]));
   const program = new ChartProgram({ ...state, children });
   validateProgramState(program, path);
-  return program;
+  if (requireSchemas) {
+    for (const dataset of program.semanticSpec.datasets) {
+      if (dataset.schema === undefined) {
+        throw invalidSnapshot(`Dataset "${dataset.id}" requires schema in editable snapshot version 2 or later.`, `${path}.semanticSpec.datasets`);
+      }
+      validateDatasetSchema(dataset.schema);
+    }
+  }
+  return restoreResolvedScaleBindings(program);
+}
+
+function migrateStateSchemas(state) {
+  const datasets = state.semanticSpec.datasets;
+  const byId = new Map(datasets.map(dataset => [dataset.id, dataset]));
+  const schemas = new Map();
+  const active = new Set();
+  function schemaFor(id) {
+    if (schemas.has(id)) return schemas.get(id);
+    if (active.has(id)) throw invalidSnapshot(`Cyclic data source "${id}".`, "payload.semanticSpec.datasets");
+    active.add(id);
+    const dataset = byId.get(id);
+    let schema;
+    if (dataset.schema !== undefined) {
+      schema = validateDatasetSchema(dataset.schema);
+    } else if (dataset.source === undefined) {
+      schema = inferDatasetSchema(dataset.values ?? []);
+    } else {
+      const sourceSchema = schemaFor(dataset.source);
+      schema = deriveTransformSchema(
+        sourceSchema,
+        dataset.transform?.[0] ?? {},
+        dataset.values,
+        { sourceId: dataset.source, ownerId: dataset.id }
+      );
+    }
+    active.delete(id);
+    schemas.set(id, schema);
+    return schema;
+  }
+  const semanticSpec = {
+    ...state.semanticSpec,
+    datasets: datasets.map(dataset => ({ ...dataset, schema: schemaFor(dataset.id) }))
+  };
+  return {
+    ...state,
+    semanticSpec,
+    children: Object.fromEntries(Object.entries(state.children).map(
+      ([id, child]) => [id, migrateStateSchemas(child)]
+    ))
+  };
 }
 
 export function serializeProgram(program) {
@@ -52,10 +121,27 @@ export function serializeProgram(program) {
   return envelope("editable", canonicalState(program, extensions), [...extensions].sort());
 }
 
+// Decoding creates fresh plain containers. Own them once across the whole graph
+// so child constructors retain shared immutable data instead of copying each pool.
+function ownDecodedState(value, seen = new WeakSet()) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  for (const child of Object.values(value)) ownDecodedState(child, seen);
+  freezeOwned(value);
+}
+
 export function deserializeProgram(text) {
   const stored = readEnvelope(text, "editable");
   const extensions = new Set();
-  const program = restoreState(stored.payload, extensions);
+  let payload = stored.payload;
+  if (stored.schemaVersion === 1) {
+    // Validate the historical state before adding any inferred metadata. Migration
+    // must never repair an invalid reference graph or malformed payload.
+    restoreState(payload, new Set());
+    payload = migrateStateSchemas(payload);
+  }
+  ownDecodedState(payload);
+  const program = restoreState(payload, extensions, "payload", { requireSchemas: true });
   if (extensions.size !== stored.extensions.length || stored.extensions.some(name => !extensions.has(name))) {
     throw invalidSnapshot("Snapshot extensions must exactly match its action traces.", "snapshot.extensions");
   }

package/src/renderers/canvas/circle.js

@@ -1,3 +1,4 @@
+import { resolveCanvasSolidPaint } from "./fill.js";
 import { requireFiniteProperty } from "./validation.js";
 import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
@@ -25,7 +26,7 @@ function drawCircle(context, child, collectionId) {
     throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
   }
 
-  context.fillStyle = properties.fill;
+  context.fillStyle = resolveCanvasSolidPaint(properties.fill);
   context.globalAlpha = opacity;
   context.beginPath();
   context.arc(x, y, radius, 0, Math.PI * 2);
@@ -44,8 +45,10 @@ function drawCircle(context, child, collectionId) {
         `Graphic "${graphicId}" requires a non-negative strokeWidth.`
       );
     }
-    applyCanvasStroke(context, properties);
-    context.stroke();
+    if (strokeWidth > 0) {
+      applyCanvasStroke(context, properties);
+      context.stroke();
+    }
   }
 }
 

package/src/renderers/canvas/fill.js

@@ -4,10 +4,16 @@ import {
 } from "../../grammar/paint.js";
 import { resolveCanvasGradientCoordinates } from "./native.js";
 
+// SVG's no-paint keyword is not a valid Canvas color assignment. Assign a real
+// transparent color so the backend cannot retain a previous opaque paint.
+export function resolveCanvasSolidPaint(paint) {
+  return paint === "none" ? "rgba(0,0,0,0)" : paint;
+}
+
 export function applyCanvasFill(context, fill, bounds, graphicId) {
   validateFillPaint(fill, `${graphicId}.fill`);
   if (!isLinearGradientPaint(fill)) {
-    context.fillStyle = fill;
+    context.fillStyle = resolveCanvasSolidPaint(fill);
     return fill;
   }
   if (typeof context.createLinearGradient !== "function") {

package/src/renderers/canvas/index.js

@@ -1,3 +1,4 @@
+import { resolveCanvasSolidPaint } from "./fill.js";
 import { annotateError } from "../../core/diagnostics.js";
 import { drawCircleGraphic } from "./circle.js";
 import { drawLineGraphic } from "./line.js";
@@ -81,7 +82,7 @@ function fillCanvasBackground(context, id, canvas, width, height) {
     );
   }
   context.globalAlpha = 1;
-  context.fillStyle = canvas.properties.background;
+  context.fillStyle = resolveCanvasSolidPaint(canvas.properties.background);
   context.fillRect(0, 0, width, height);
 }
 

package/src/renderers/canvas/line.js

@@ -33,6 +33,7 @@ function drawLine(context, child, collectionId) {
     throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
   }
 
+  if (strokeWidth === 0) return;
   context.globalAlpha = opacity;
   applyCanvasStroke(context, properties, properties.strokeDash ?? []);
   context.beginPath();

package/src/renderers/canvas/path.js

@@ -82,7 +82,7 @@ function drawPath(context, child, collectionId) {
     applyCanvasFill(context, properties.fill, bounds, graphicId);
     context.fill();
   }
-  if (hasStroke) {
+  if (hasStroke && strokeWidth > 0) {
     applyCanvasStroke(context, properties, strokeDash);
     context.stroke();
   }

package/src/renderers/canvas/rect.js

@@ -43,14 +43,17 @@ function drawRect(context, child, collectionId) {
     bottom: y + height
   }, graphicId);
   context.fillRect(x, y, width, height);
-  applyCanvasStroke(context, properties);
-  context.beginPath();
-  context.moveTo(x, y);
-  context.lineTo(x + width, y);
-  context.lineTo(x + width, y + height);
-  context.lineTo(x, y + height);
-  context.lineTo(x, y);
-  context.stroke();
+  // Canvas ignores lineWidth = 0 and would retain a previous nonzero width.
+  if (strokeWidth > 0) {
+    applyCanvasStroke(context, properties);
+    context.beginPath();
+    context.moveTo(x, y);
+    context.lineTo(x + width, y);
+    context.lineTo(x + width, y + height);
+    context.lineTo(x, y + height);
+    context.lineTo(x, y);
+    context.stroke();
+  }
 }
 
 export function drawRectGraphic(context, id, graphic) {

package/src/renderers/canvas/stroke.js

@@ -1,8 +1,9 @@
+import { resolveCanvasSolidPaint } from "./fill.js";
 import { resolveStrokeDetails } from "../../grammar/strokeStyle.js";
 
 export function applyCanvasStroke(context, properties, strokeDash = []) {
   const details = resolveStrokeDetails(properties);
-  context.strokeStyle = properties.stroke;
+  context.strokeStyle = resolveCanvasSolidPaint(properties.stroke);
   context.lineWidth = properties.strokeWidth;
   context.lineCap = details.lineCap;
   context.lineJoin = details.lineJoin;

package/src/renderers/canvas/text.js

@@ -1,3 +1,4 @@
+import { resolveCanvasSolidPaint } from "./fill.js";
 import { requireFiniteProperty, requireStringProperty } from "./validation.js";
 import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
@@ -72,15 +73,16 @@ function drawText(context, child, collectionId) {
   context.save();
 
   try {
-    context.fillStyle = fill;
+    context.fillStyle = resolveCanvasSolidPaint(fill);
     context.globalAlpha = opacity;
     const rendererFontWeight = normalizeRendererFontWeight(fontWeight);
-    context.font = `${rendererFontWeight} ${fontSize}px ${fontFamily}`;
+    context.font = `${properties.fontStyle === "italic" ? "italic " : ""}${rendererFontWeight} ${fontSize}px ${fontFamily}`;
     context.textAlign = textAlign;
     context.textBaseline = textBaseline;
     context.translate(x, y);
     context.rotate(rotation);
-    context.fillText(text, 0, 0);
+    if (properties.lines === undefined) context.fillText(text, 0, 0);
+    else for (const line of properties.lines) context.fillText(line.text, line.x, line.y);
   } finally {
     context.restore();
   }

package/src/renderers/svg.js

@@ -419,13 +419,16 @@ function serializeText(state, graphicId, properties) {
     ["font-family", fontFamily],
     ["font-size", formatNumber(fontSize)],
     ["font-weight", normalizeRendererFontWeight(fontWeight)],
+    ["font-style", properties.fontStyle],
     ["text-anchor", TEXT_ANCHORS[textAlign]],
     ["dominant-baseline", DOMINANT_BASELINES[textBaseline]],
     ["opacity", formatNumber(opacity)],
     ["transform", rotation === 0
       ? undefined
       : `rotate(${formatNumber(rotationDegrees)} ${formatNumber(x)} ${formatNumber(y)})`]
-  ], escapeText(text));
+  ], properties.lines === undefined ? escapeText(text) : properties.lines.map(line =>
+    element("tspan", [["x", formatNumber(x + line.x)], ["y", formatNumber(y + line.y)]], escapeText(line.text))
+  ).join(""));
 }
 
 function serializeConcreteGraphic(state, id, graphic) {

package/src/selectors/layers.js

@@ -37,3 +37,22 @@ export function resolveEligibleLayer(program, {
   if (candidates.length === 0) throw annotateError(new Error(`${label} requires an eligible layer.`), { code: "missing-resource", optionPath: targetOption });
   throw annotateError(new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`), { code: "ambiguous-resource", optionPath: targetOption, candidates: candidates.map(layer => layer.id) });
 }
+
+// Configured composite plots retain their established owner errors while sharing
+// the explicit/current/unique resolution order.
+export function resolveConfiguredOwner(program, requested, {
+  config, operation, kind, article = "a", materialized = false, missing, ambiguous
+}, validateUserId) {
+  const eligible = program.semanticSpec.layers.filter(layer => {
+    const value = program.markConfigs[layer.id]?.[config];
+    return materialized ? value?.materialized === true : value !== undefined;
+  });
+  const id = requested === undefined ? program.context.currentMark
+    : validateUserId(requested, `${kind[0].toUpperCase() + kind.slice(1)}-plot owner id`);
+  const owner = eligible.find(layer => layer.id === id);
+  if (owner !== undefined) return owner;
+  if (requested !== undefined) throw new Error(`Unknown ${kind}-plot owner "${id}".`);
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) throw new Error(missing ?? `${operation} requires ${article} ${kind} plot.`);
+  throw new Error(ambiguous ?? `${operation} target is ambiguous; provide target.`);
+}

package/src/theme/defaults.js

@@ -2,6 +2,9 @@ import { DEFAULT_FONT_FAMILY } from "../core/font.js";
 export { DEFAULT_FONT_FAMILY };
 
 export const DEFAULT_POINT_RADIUS = 3;
+export const AXIS_LABEL_FONT_SIZES = Object.freeze({ cartesian: 12, polar: 11, parallel: 11 });
+export const AXIS_TITLE_FONT_SIZE = 13;
+export const DEFAULT_VERTICAL_LEGEND_ITEM_GAP = 18;
 
 export const DEFAULT_COLORS = Object.freeze({
   mark: "#4c78a8",
@@ -42,7 +45,8 @@ export const THEME_TOKEN_KEYS = Object.freeze([
   "referenceBand",
   "gradientCenter",
   "highlight",
-  "fontFamily"
+  "fontFamily", "axisLabel", "axisLabelFontFamily", "axisTitleFontFamily",
+  "axisLabelFontSize", "axisTitleFontSize"
 ]);
 
 const THEME_DEFINITION_KEYS = Object.freeze(["base", "tokens"]);
@@ -120,7 +124,9 @@ function normalizeThemeTokens(tokens) {
   validateKeys(tokens, THEME_TOKEN_KEYS, "applyTheme theme.tokens");
   const normalized = {};
   for (const [key, value] of Object.entries(tokens)) {
-    validateNonEmptyString(value, `applyTheme theme.tokens.${key}`);
+    if (key.endsWith("FontSize")) {
+      if (!Number.isFinite(value) || value <= 0) throw new RangeError(`applyTheme theme.tokens.${key} must be positive and finite.`);
+    } else validateNonEmptyString(value, `applyTheme theme.tokens.${key}`);
     normalized[key] = value;
   }
   return own(normalized);

package/src/version.js

@@ -1,2 +1,2 @@
 // Must match package.json; enforced by the snapshot producer-version test.
-export const packageVersion = "0.0.16";
+export const packageVersion = "0.0.18";

package/types/basic.d.ts

@@ -17,6 +17,7 @@ export type {
   CompleteAxisOptions,
   CreateAxesOptions,
   CreateBarPlotOptions,
+  BarRangePositionChannel,
   CreateDataOptions,
   CreateGridOptions,
   CreateGuidesOptions,

package/types/index.d.ts

@@ -1,6 +1,8 @@
 import type { ChartProgram, CompositionOptions } from "./program.js";
 
 export type {
+  ArcInnerRadius,
+  PieRadiusChannel,
   TextMetricFontWeight,
   TextMeasurement,
   TextMetricsProfile,
@@ -27,6 +29,7 @@ export type {
   DisplayLabelOptions,
   BarWidthOptions,
   BoxPlotOptions,
+  BoxPlotSummaryFields,
   BinnedHeatmapColorOptions,
   BinnedHeatmapOptions,
   BinnedHeatmapPositionChannel,
@@ -117,6 +120,7 @@ export type {
   CreateGuidesOptions,
   CreateGridOptions,
   CreateBarPlotOptions,
+  BarRangePositionChannel,
   CreateHeatmapOptions,
   CreateHistogramOptions,
   CreatePiePlotOptions,
@@ -166,6 +170,7 @@ export type {
   StripPixelJitterOptions,
   CreateParallelCoordinatesOptions,
   CreateScatterPlotOptions,
+  CreateTextPlotOptions,
   CreateIntervalPlotOptions,
   CreateRegressionPlotOptions,
   CreateDotPlotOptions,
@@ -241,6 +246,7 @@ export type {
   EditHorizonOptions,
   EditCompositionLayoutOptions,
   EditFacetHeadersOptions,
+  FacetHeadersOptions,
   EditAxisOptions,
   EditGradientPlotOptions,
   EditViolinPlotOptions,
@@ -375,6 +381,7 @@ export type {
   ScaleType,
   ShapeScaleOptions,
   SizeScaleOptions,
+  CategoricalSizeScaleOptions,
   StackMode,
   StackDataMode,
   StackDataOptions,

package/types/inspection.d.ts

@@ -0,0 +1,17 @@
+import type { BasicChartProgram } from "./basic.js";
+import type { ChartProgram, DatasetSchema } from "./program.js";
+export type ProgramInput = ChartProgram | BasicChartProgram;
+export interface ResourceRef { readonly kind: "data" | "mark" | "scale" | "coordinate" | "guide" | "canvas" | "composition"; readonly id: string; readonly childPath?: readonly string[]; }
+export interface InspectionTarget { readonly kind: "data" | "mark" | "scale" | "coordinate" | "guide"; readonly id: string; readonly childPath?: readonly string[]; }
+export interface Finding { readonly severity: "error" | "warning" | "info"; readonly code: string; readonly reason: string; readonly message: string; readonly resource?: ResourceRef; readonly optionPath?: string; }
+export interface CheckResult { readonly name: string; readonly status: "not_run" | "passed" | "failed" | "not_applicable"; readonly evidencePaths: readonly string[]; readonly findings: readonly Finding[]; }
+export interface ParameterDefinition { readonly path: string; readonly kind: "field" | "enum" | "number" | "string" | "boolean" | "range" | "array" | "object" | "resource"; readonly required: boolean; readonly active: boolean; readonly choices?: readonly (string | number | boolean | null)[]; readonly minimum?: number; readonly maximum?: number; readonly unit?: string; readonly fieldRole?: string; }
+export interface ActionDescription { readonly version: 1; readonly action: string; readonly applicability: "supported" | "needs-input" | "incompatible" | "unsupported" | "unverified"; readonly parameterDefinitions: readonly ParameterDefinition[]; readonly requirements: readonly { readonly reason: string; readonly optionPath?: string }[]; readonly checks: readonly CheckResult[]; readonly findings: readonly Finding[]; }
+export interface Change { readonly resource: ResourceRef; readonly operation: "add" | "remove" | "modify"; readonly effect: "data" | "binding" | "structure" | "scale" | "guide" | "style"; readonly roles: readonly string[]; }
+export interface ProgramComparison { readonly version: 1; readonly equivalence: "equal" | "different" | "unknown"; readonly completeProgramComparison: boolean; readonly changes: readonly Change[]; readonly affected: readonly ResourceRef[]; readonly findings: readonly Finding[]; }
+export interface OwnerInspection { readonly owner: ResourceRef; readonly grain: "item" | "series" | "composite" | "unknown"; readonly rawRows: number | null; readonly logicalDataItems: number | null; readonly drawablePrimitives: number | null; readonly visibleCandidates: number | null; readonly flags: readonly { readonly reason: "opacity-zero" | "zero-size" | "outside-clip" | "missing-skipped"; readonly count: number | null }[]; readonly bounds: Readonly<{x:number;y:number;width:number;height:number}> | null; readonly sourceRefs: readonly ResourceRef[]; readonly checks: readonly CheckResult[]; }
+export interface ProgramInspection { readonly version: 1; readonly views: readonly OwnerInspection[]; readonly calculations: readonly unknown[]; readonly checks: readonly CheckResult[]; readonly findings: readonly Finding[]; readonly coverage: Readonly<{partial:boolean;unsupported:readonly ResourceRef[]}>; }
+export function getDatasetSchema(program: ProgramInput, options: {readonly data:string;readonly childPath?:readonly string[]}): Readonly<{data:string;schema:DatasetSchema}>;
+export function describeAction(program: ProgramInput, options: {readonly action:string;readonly target?:InspectionTarget;readonly options?:Readonly<Record<string,unknown>>}): ActionDescription;
+export function comparePrograms(before: ProgramInput, after: ProgramInput, options?: {readonly target?:InspectionTarget}): ProgramComparison;
+export function inspectProgram(program: ProgramInput, options?: {readonly target?:InspectionTarget}): ProgramInspection;