ggaction 0.0.21 → 0.0.23

package/src/renderers/transitionScene.js

@@ -0,0 +1,67 @@
+import { validateGraphicClip } from '../grammar/schemas/graphicClip.js';
+import { validateConcreteGraphicProperties } from '../grammar/schemas/concreteGraphic.js';
+import { requireSingleOrderedGraphicByType, walkGraphicTreeEvents } from "../grammar/schemas/graphicTree.js";
+function opaqueKey(value) {
+  let hash = 2166136261;
+  for (const char of JSON.stringify(value)) hash = Math.imul(hash ^ char.charCodeAt(0), 16777619);
+  return (hash >>> 0).toString(36);
+}
+
+export function collectTransitionGraphics(graphicSpec, identities) {
+  const { id: root, object: canvas } = requireSingleOrderedGraphicByType(graphicSpec, "canvas");
+  const { width, height } = canvas.properties ?? {};
+  if (![width, height].every(n => Number.isFinite(n) && n >= 0)) throw new TypeError('Scene requires finite nonnegative Canvas dimensions.');
+  const nodes = [], stack = [{ x: 0, y: 0, clip: [0, 0, width, height], clips: [] }];
+  const used = new Map();
+  const add = (id, graphic, suffix = "") => {
+    if (graphic.type === "collection") {
+      for (const [index, item] of (graphic.items ?? []).entries()) add(item.id ?? id, item, `${suffix}/${index}`);
+      return;
+    }
+    validateConcreteGraphicProperties(graphic.type, graphic.properties);
+    const frame = stack.at(-1);
+    const identity = identities.get(id);
+    const base = identity?.key ?? `graphic:${opaqueKey([id, suffix])}`;
+    const count = used.get(base) ?? 0; used.set(base, count + 1);
+    nodes.push({ key: `${base}#${count}`, type: graphic.type,
+      topology: identity?.topology ?? "",
+      properties: graphic.properties,
+      offset: [frame.x, frame.y], clip: frame.clip, clips: frame.clips });
+  };
+  const background = (id, object) => {
+    const p = object.properties;
+    if (p.background !== undefined) add(`${id}/background`, { type: "rect", properties: {
+      x: 0, y: 0, width: p.width, height: p.height, fill: p.background,
+      stroke: "none", strokeWidth: 0
+    } });
+  };
+  background(root, canvas);
+  walkGraphicTreeEvents(graphicSpec, {
+    enter({ id, object }) {
+      if (id === root) return;
+      if (object.type === "canvas") {
+        const p = object.properties, parent = stack.at(-1);
+        if (![p.x, p.y, p.width, p.height].every(Number.isFinite) || p.width < 0 || p.height < 0) throw new TypeError('Invalid nested Canvas geometry.');
+        const x = parent.x + p.x, y = parent.y + p.y;
+        const left = Math.max(x, parent.clip[0]), top = Math.max(y, parent.clip[1]);
+        stack.push({ x, y, clips: [...parent.clips, [x, y, p.width, p.height]], clip: [left, top,
+          Math.max(0, Math.min(x + p.width, parent.clip[0] + parent.clip[2]) - left),
+          Math.max(0, Math.min(y + p.height, parent.clip[1] + parent.clip[3]) - top)] });
+        background(id, object);
+      } else {
+        if (object.clip !== undefined) {
+          const rect = validateGraphicClip(object.clip, object.type), parent = stack.at(-1);
+          const left = Math.max(parent.x + rect.x, parent.clip[0]);
+          const top = Math.max(parent.y + rect.y, parent.clip[1]);
+          stack.push({ ...parent, clips: [...parent.clips, [parent.x + rect.x, parent.y + rect.y, rect.width, rect.height]], clip: [left, top,
+            Math.max(0, Math.min(parent.x + rect.x + rect.width, parent.clip[0] + parent.clip[2]) - left),
+            Math.max(0, Math.min(parent.y + rect.y + rect.height, parent.clip[1] + parent.clip[3]) - top)] });
+        }
+        if (object.type !== "collection" && !Array.isArray(object.items)) add(id, object);
+      }
+    },
+    item({ id, object, owner }) { add(id, { ...object, type: object.type ?? owner.type }); },
+    exit({ id, object }) { if (id !== root && (object.type === "canvas" || object.clip !== undefined)) stack.pop(); }
+  });
+  return { version: 2, width, height, nodes };
+}

package/src/scene.js

@@ -0,0 +1,89 @@
+import { collectTransitionGraphics } from "./renderers/transitionScene.js";
+export { renderTransitionScene } from "./renderers/canvas/scene.js";
+import { renderTransitionGraphics } from "./renderers/svgSerialization.js";
+import { resolveMarkItems, findSelectionPolicy } from "./materialization/selection/policies/index.js";
+import { namespaceGraphicId } from "./selectors/graphicCapacity.js";
+import { findLayer } from "./selectors/layers.js";
+import { findDataset } from "./selectors/datasets.js";
+import { cloneAndFreeze } from "./core/immutable.js";
+
+const scenes = new WeakMap(), canvasScenes = new WeakMap();
+function canonical(value) {
+  if (value instanceof Date) return `date:${value.toISOString()}`;
+  if (typeof value === "number" && !Number.isFinite(value)) return `number:${value}`;
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+}
+// Opaque deterministic keys; public consumers never depend on private graphic paths.
+function token(value) {
+  const string = canonical(value); let a = 2166136261, b = 5381;
+  for (let i = 0; i < string.length; i++) {
+    a = Math.imul(a ^ string.charCodeAt(i), 16777619);
+    b = Math.imul(b, 33) ^ string.charCodeAt(i);
+  }
+  return `${(a >>> 0).toString(36)}-${(b >>> 0).toString(36)}`;
+}
+function identities(program, project = id => id, scope = "", result = new Map()) {
+  for (const layer of program.semanticSpec.layers) {
+    const dataset = findDataset(program, layer.data);
+    if (!dataset || !findSelectionPolicy(layer.mark?.type)) continue;
+    let root = dataset; const visited = new Set();
+    while (root.source && !visited.has(root.id)) {
+      visited.add(root.id); const parent = findDataset(program, root.source);
+      if (!parent) break; root = parent;
+    }
+    // Value+occurrence preserves duplicates, filters and sorting without relying on
+    // derived array indexes. Unresolvable derived provenance deliberately fades.
+    const rowTokens = new WeakMap();
+    const rowToken = row => {
+      if (!rowTokens.has(row)) rowTokens.set(row, token(row));
+      return rowTokens.get(row);
+    };
+    let items;
+    try { items = resolveMarkItems(program, layer.id); }
+    catch { continue; } // Incomplete/unsupported selections keep conservative graphic keys.
+    for (const item of items) {
+      const members = item.members.map(rowToken);
+      const membership = [...members].sort();
+      const key = token([scope, root.id, layer.id, membership]);
+      const topology = ["line", "area"].includes(layer.mark.type) ? token(members) : "";
+      for (const [index, id] of item.graphicIds.entries()) {
+        result.set(project(id), { key: `${key}/${index}`, topology });
+      }
+    }
+  }
+  // Named guides match by semantic role; text collections match by label value,
+  // not tick array index, so domain changes never rename one tick into another.
+  for (const [id, object] of Object.entries(program.graphicSpec.objects)) {
+    if (!result.has(project(id))) result.set(project(id), { key: token([scope, id]), topology: "" });
+    if (object.type === "canvas") result.set(`${project(id)}/background`, { key: token([scope, id, "background"]), topology: "" });
+    for (const item of object.items ?? []) if (!result.has(project(item.id))) {
+      result.set(project(item.id), { key: token([scope, id, item.properties]), topology: "" });
+    }
+    const layer = findLayer(program, id);
+    if (!layer && object.type === "text") {
+      for (const item of object.items ?? []) result.set(project(item.id), {
+        key: token([scope, id, item.properties.text]), topology: ""
+      });
+    }
+  }
+  for (const childId of program.compositionSpec?.children ?? []) {
+    const child = program.children[childId];
+    const facet = program.compositionSpec.type === "facet" || program.compositionSpec.type === "facetGrid";
+    identities(child, id => project(namespaceGraphicId(`${program.compositionSpec.id}-${childId}`, id)),
+      facet ? scope : `${scope}/${childId}`, result);
+  }
+  return result;
+}
+
+/** Read-only, browser-safe, structured-cloneable scene for animation consumers. */
+export function createTransitionScene(program, { format = "svg" } = {}) {
+  if (!["svg", "canvas"].includes(format)) throw new TypeError("Unknown transition scene format.");
+  const cache = format === "canvas" ? canvasScenes : scenes;
+  if (!program?.semanticSpec || !program?.graphicSpec) throw new TypeError("createTransitionScene requires a ChartProgram.");
+  if (cache.has(program)) return cache.get(program);
+  const scene = cloneAndFreeze((format === "canvas" ? collectTransitionGraphics : renderTransitionGraphics)(program.graphicSpec, identities(program)));
+  cache.set(program, scene);
+  return scene;
+}

package/src/selectors/axes.js

@@ -1 +1 @@
-const p=Object.freeze(["x","y"]),w=Object.freeze(["line","ticks","labels","title"]);function x(n){const e=n.semanticSpec?.guides?.axis??{},a=(n.guideConfigs??n.materializationConfigs?.guides)?.axis??{};return[...new Set([...Object.keys(e),...Object.keys(a)])].flatMap(i=>{const s=Object.hasOwn(e,i)?e[i]:void 0,c=Object.hasOwn(a,i)?a[i]:void 0,d=p.includes(i)?i:s?.channel;if(!p.includes(d))return[];const t=[...new Set((n.semanticSpec.layers??[]).filter(f=>f.encoding?.[d]?.scale===s?.scale).map(f=>f.coordinate).filter(Boolean))];return[{id:i,channel:d,semantic:s,config:c,scale:s?.scale,coordinate:s?.coordinate??(t.length===1?t[0]:void 0),named:i!==d,sides:[...new Set(i!==d?[s.position]:w.map(f=>c?.[f]?.position).filter(Boolean))]}]})}function g(n,e){return n===e?{}:{target:n}}function O(n,e,a={},{create:i=!1,whole:s=!1}={}){const c=x(n),d=c.filter(r=>r.channel===e);let t;if(Object.hasOwn(a,"target")){const r=a.target;if(t=c.find(l=>l.id===r),t===void 0||t.channel!==e)throw new Error(`Unknown ${e}-axis target "${r}".`)}else if(t=d.find(r=>r.id===e),t===void 0){if(d.length>1)throw new Error(`Multiple ${e}-axes require an explicit target.`);t=d[0]}const{target:f,...o}=a,u=t?.id??e;if(!t?.named&&o.position!==void 0&&c.some(r=>r.named)){const r=[...new Set((n.semanticSpec.layers??[]).filter(l=>l.encoding?.[e]?.scale===(o.scale??t?.scale??e)).map(l=>l.coordinate).filter(Boolean))];m(n,{id:u,channel:e,coordinate:t?.coordinate??(r.length===1?r[0]:void 0),position:o.position})}if(t?.named){if(o.scale!==void 0&&o.scale!==t.scale||o.coordinate!==void 0&&o.coordinate!==t.coordinate)throw new Error(`Axis "${u}" resource binding does not match the requested filter.`);if(!s&&o.position!==void 0&&o.position!==t.semantic.position)throw new Error(`Named axis "${u}" components share one side; edit the complete axis position.`);i&&(o.scale??=t.scale),s||(o.position??=t.semantic.position)}return{id:u,owner:t,options:o}}function m(n,{id:e,channel:a,coordinate:i,position:s}){for(const c of x(n))if(c.id!==e&&c.coordinate===i&&c.sides.includes(s))throw new Error(`Axis side "${s}" is already occupied on coordinate "${i}".`)}function b(n,e=n){const a=["Line","Ticks","Labels","Title"];if(e!==n)return a.map(s=>`axis_${e}__${s}`);const i=n==="radius"?"radial":n;return a.map(s=>`${i}Axis${s}`)}export{m as assertCartesianAxisSideAvailable,b as axisGraphicIds,g as axisTargetArgs,x as cartesianAxisOwners,O as selectCartesianAxis};
+const u=Object.freeze(["x","y"]),x=Object.freeze(["line","ticks","labels","title"]),m=x,g=Object.freeze({line:"parallelAxisLines",ticks:"parallelAxisTicks",labels:"parallelAxisLabels",title:"parallelAxisTitles"});function A(i){const e=i.semanticSpec?.guides?.axis??{},a=(i.guideConfigs??i.materializationConfigs?.guides)?.axis??{};return[...new Set([...Object.keys(e),...Object.keys(a)])].flatMap(n=>{const s=Object.hasOwn(e,n)?e[n]:void 0,c=Object.hasOwn(a,n)?a[n]:void 0,l=u.includes(n)?n:s?.channel;if(!u.includes(l))return[];const t=[...new Set((i.semanticSpec.layers??[]).filter(d=>d.encoding?.[l]?.scale===s?.scale).map(d=>d.coordinate).filter(Boolean))];return[{id:n,channel:l,semantic:s,config:c,scale:s?.scale,coordinate:s?.coordinate??(t.length===1?t[0]:void 0),named:n!==l,sides:[...new Set(n!==l?[s.position]:x.map(d=>c?.[d]?.position).filter(Boolean))]}]})}function b(i,e){return i===e?{}:{target:i}}function S(i,e,a={},{create:n=!1,whole:s=!1}={}){const c=A(i),l=c.filter(r=>r.channel===e);let t;if(Object.hasOwn(a,"target")){const r=a.target;if(t=c.find(f=>f.id===r),t===void 0||t.channel!==e)throw new Error(`Unknown ${e}-axis target "${r}".`)}else if(t=l.find(r=>r.id===e),t===void 0){if(l.length>1)throw new Error(`Multiple ${e}-axes require an explicit target.`);t=l[0]}const{target:d,...o}=a,p=t?.id??e;if(!t?.named&&o.position!==void 0&&c.some(r=>r.named)){const r=[...new Set((i.semanticSpec.layers??[]).filter(f=>f.encoding?.[e]?.scale===(o.scale??t?.scale??e)).map(f=>f.coordinate).filter(Boolean))];w(i,{id:p,channel:e,coordinate:t?.coordinate??(r.length===1?r[0]:void 0),position:o.position})}if(t?.named){if(o.scale!==void 0&&o.scale!==t.scale||o.coordinate!==void 0&&o.coordinate!==t.coordinate)throw new Error(`Axis "${p}" resource binding does not match the requested filter.`);if(!s&&o.position!==void 0&&o.position!==t.semantic.position)throw new Error(`Named axis "${p}" components share one side; edit the complete axis position.`);n&&(o.scale??=t.scale),s||(o.position??=t.semantic.position)}return{id:p,owner:t,options:o}}function w(i,{id:e,channel:a,coordinate:n,position:s}){for(const c of A(i))if(c.id!==e&&c.coordinate===n&&c.sides.includes(s))throw new Error(`Axis side "${s}" is already occupied on coordinate "${n}".`)}function O(i,e=i){if(i==="parallel"&&e===i)return["parallelAxisLines","parallelAxisTicks","parallelAxisLabels","parallelAxisTitles"];const a=["Line","Ticks","Labels","Title"];if(e!==i)return a.map(s=>`axis_${e}__${s}`);const n=i==="radius"?"radial":i;return a.map(s=>`${n}Axis${s}`)}export{g as PARALLEL_AXIS_GRAPHICS,m as PARALLEL_AXIS_PARTS,w as assertCartesianAxisSideAvailable,O as axisGraphicIds,b as axisTargetArgs,A as cartesianAxisOwners,S as selectCartesianAxis};

package/src/selectors/datasets.js

@@ -4,6 +4,7 @@ export function findDataset(program, id) {
   return program.semanticSpec.datasets.find(dataset => dataset.id === id);
 }
 
+
 function currentOwnerMatches(program, id) {
   const families = program.materializationConfigs.data ?? {};
   return Object.entries(families).flatMap(([family, owners]) =>

package/src/selectors/grids.js

@@ -0,0 +1,9 @@
+export function gridNames(direction) {
+  const prefix = direction === "horizontal" ? "Horizontal" : "Vertical";
+  return {
+    channel: direction === "horizontal" ? "y" : "x",
+    create: `create${prefix}Grid`,
+    rematerialize: `rematerialize${prefix}Grid`,
+    graphic: `${direction}GridLines`
+  };
+}

package/src/selectors/markClip.js

@@ -0,0 +1,28 @@
+import { requireCoordinate } from "./coordinates.js";
+import { findLayer } from "./layers.js";
+
+export function requestedMarkClip(options) {
+  if (!Object.hasOwn(options, "clip")) return {};
+  if (typeof options.clip !== "boolean") throw new TypeError("Mark clip must be a boolean.");
+  return {clip: options.clip};
+}
+
+export function markClipPositionOwner(program, layer) {
+  return layer?.mark?.type === "text" && layer.source !== undefined
+    ? findLayer(program, layer.source) : layer;
+}
+
+export function validateMarkClipCoordinate(program, layer, clip, requestedType) {
+  if (clip !== undefined && !["point", "line", "area", "bar", "rect", "rule", "text", "tick"].includes(layer?.mark?.type)) {
+    throw new Error("Mark clip requires a supported Cartesian mark family.");
+  }
+  if (clip !== true) return;
+  layer = markClipPositionOwner(program, layer);
+  const type = requestedType ?? (layer?.coordinate === undefined ? undefined : requireCoordinate(program, layer.coordinate).type);
+  if (type !== undefined && type !== "cartesian") {
+    throw new Error("Mark clip requires a Cartesian coordinate.");
+  }
+  if (["theta", "radius", "parallel"].some(channel => layer?.encoding?.[channel] !== undefined)) {
+    throw new Error("Mark clip requires Cartesian position encodings.");
+  }
+}

package/src/selectors/raincloud.js

@@ -0,0 +1,7 @@
+// A facade ID is distinct from a materialized child ID. Only an explicit
+// facade target requests an operation over the complete observation population.
+export function findRaincloudParent(program, target) {
+  if (target === undefined) return undefined;
+  return Object.values(program.markConfigs).map(config => config.raincloudPlot)
+    .find(config => config?.materialized === true && config.id === target);
+}

package/src/version.js

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

package/types/basic.d.ts

@@ -1,6 +1,9 @@
 import type { ChartProgram, BasicSeriesLayoutOptions, CreateDataOptions } from "./program.js";
 
 export type {
+  LinearNiceCountOptions,
+  PointPolygonShape,
+  AxisTickRounding,
   AxisLabelOptions,
   AxisLineStyleOptions,
   AxisTickOptions,
@@ -21,6 +24,8 @@ export type {
   CreateBarPlotOptions,
   BarRangePositionChannel,
   CreateDataOptions,
+  FlattenDataOptions,
+  LookupDataOptions,
   CreateGridOptions,
   CreateGuidesOptions,
   CreateHeatmapOptions,
@@ -65,6 +70,8 @@ type BasicMethodKey =
   | "applyTheme"
   | "removeTheme"
   | "createData"
+  | "createFlattenData"
+  | "createLookupData"
   | "createPointMark"
   | "createLineMark"
   | "createBarMark"

package/types/index.d.ts

@@ -1,6 +1,8 @@
 import type { ChartProgram, CompositionOptions } from "./program.js";
 
 export type {
+  LinearNiceCountOptions,
+  AxisTickRounding,
   ArcInnerRadius,
   PieRadiusChannel,
   TextMetricFontWeight,
@@ -251,6 +253,8 @@ export type {
   EditCompositionLayoutOptions,
   EditFacetHeadersOptions,
   FacetHeadersOptions,
+  FacetHeaderTitleOptions,
+  EditAxesOptions,
   EditAxisOptions,
   EditGradientPlotOptions,
   EditViolinPlotOptions,
@@ -285,10 +289,12 @@ export type {
   FacetCompositionSpec,
   FacetGuideOptions,
   FacetOptions,
+  FacetTopLaneMode,
   FacetGridOptions,
   FacetGridRole,
   FacetScaleResolution,
   FacetScaleResolutions,
+  GraphicClipRect,
   GraphicObject,
   GraphicSpec,
   GraphicType,
@@ -349,6 +355,7 @@ export type {
   ParallelDimension,
   ParallelMissingPolicy,
   PointShape,
+  PointPolygonShape,
   PreGriddedHeatmapOptions,
   MarkSelector,
   MarkGraphicProperty,
@@ -434,6 +441,7 @@ export type {
   RemoveMarkLabelsOptions,
   CreateAnnotationOptions,
   ReferenceStatistic,
+  CreateStatisticalReferenceOptions,
   CreateReferenceLineOptions,
   CreateReferenceBandOptions,
   XAxisPosition,