ggaction 0.0.13 → 0.0.15

package/src/actions/theme/state.js

@@ -0,0 +1,160 @@
+import {
+  cloneAndFreeze,
+  freezeOwned,
+  isPlainObject
+} from "../../core/immutable.js";
+import {
+  normalizeThemeDefinition,
+  resolveThemeTokens
+} from "../../theme/defaults.js";
+
+export const LOCAL_THEME_OWNER = "local";
+
+function ownArray(value) {
+  return freezeOwned([...(value ?? [])]);
+}
+
+function requireThemeScope(value) {
+  if (!["self", "descendants"].includes(value)) {
+    throw new Error(`Unsupported theme scope "${value}".`);
+  }
+  return value;
+}
+
+function requireThemeOwner(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("Theme frame owner must be a non-empty string.");
+  }
+  return value;
+}
+
+export function compositionThemeOwner(id, scope = "descendants") {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Composition theme owner requires a non-empty id.");
+  }
+  requireThemeScope(scope);
+  return scope === "self" ? `composition:${id}:self` : `composition:${id}`;
+}
+
+export function createThemeFrame({
+  owner = LOCAL_THEME_OWNER,
+  scope = "self",
+  definition
+}) {
+  const normalized = normalizeThemeDefinition(definition);
+  return freezeOwned({
+    owner: requireThemeOwner(owner),
+    scope: requireThemeScope(scope),
+    name: normalized.name,
+    tokens: normalized.tokens
+  });
+}
+
+export function upsertThemeFrame(frames = [], frame) {
+  if (!Array.isArray(frames)) {
+    throw new TypeError("Theme frames must be an array.");
+  }
+  if (!isPlainObject(frame)) {
+    throw new TypeError("Theme frame must be a plain object.");
+  }
+  return freezeOwned([
+    ...frames.filter(current => current.owner !== frame.owner),
+    frame
+  ]);
+}
+
+export function removeThemeFrameOwner(frames = [], owner) {
+  if (!Array.isArray(frames)) {
+    throw new TypeError("Theme frames must be an array.");
+  }
+  requireThemeOwner(owner);
+  const next = frames.filter(frame => frame.owner !== owner);
+  return freezeOwned({
+    frames: freezeOwned(next),
+    removed: next.length !== frames.length
+  });
+}
+
+export function moveLocalThemeScope(localOrder = [], scope) {
+  if (!Array.isArray(localOrder)) {
+    throw new TypeError("Theme localOrder must be an array.");
+  }
+  requireThemeScope(scope);
+  return freezeOwned([
+    ...localOrder.filter(current => current !== scope),
+    scope
+  ]);
+}
+
+function ownCanonicalThemeState(state, composition) {
+  const frames = ownArray(state.frames);
+  const localOrder = ownArray(state.localOrder);
+  const overrides = ownArray(state.overrides);
+  const result = { frames, localOrder, overrides };
+  if (composition || state.descendantFrames !== undefined) {
+    result.descendantFrames = ownArray(state.descendantFrames);
+  }
+  return cloneAndFreeze(result);
+}
+
+export function normalizeThemeState(state, { composition = false } = {}) {
+  if (state === undefined) {
+    return freezeOwned({
+      frames: freezeOwned([]),
+      ...(composition ? { descendantFrames: freezeOwned([]) } : {}),
+      localOrder: freezeOwned([]),
+      overrides: freezeOwned([])
+    });
+  }
+  if (!isPlainObject(state)) {
+    throw new TypeError("Program theme state must be a plain object.");
+  }
+  if (Array.isArray(state.frames)) {
+    return ownCanonicalThemeState(state, composition);
+  }
+
+  const name = state.name ?? "light";
+  const tokens = state.tokens ?? {};
+  const scope = state.scope ?? "self";
+  const origin = state.origin?.ownerCompositionId;
+  const owner = origin === undefined
+    ? LOCAL_THEME_OWNER
+    : compositionThemeOwner(origin, "descendants");
+  const frame = createThemeFrame({
+    owner,
+    scope,
+    definition: { base: name, tokens }
+  });
+  return freezeOwned({
+    frames: freezeOwned([frame]),
+    ...(composition && scope === "descendants"
+      ? { descendantFrames: freezeOwned([frame]) }
+      : composition
+        ? { descendantFrames: freezeOwned([]) }
+        : {}),
+    localOrder: origin === undefined ? freezeOwned([scope]) : freezeOwned([]),
+    overrides: cloneAndFreeze(state.overrides ?? [])
+  });
+}
+
+export function resolveEffectiveThemeFrame(state) {
+  const frames = state?.frames;
+  return Array.isArray(frames) ? frames.at(-1) : undefined;
+}
+
+export function resolveEffectiveThemeTokens(state) {
+  const frame = resolveEffectiveThemeFrame(state);
+  return frame === undefined
+    ? resolveThemeTokens("light")
+    : resolveThemeTokens({ base: frame.name, tokens: frame.tokens });
+}
+
+export function setThemeStateOverrides(state, overrides) {
+  if (!Array.isArray(overrides)) {
+    throw new TypeError("Theme overrides must be an array.");
+  }
+  return freezeOwned({
+    ...state,
+    overrides: cloneAndFreeze([...overrides].sort())
+  });
+}

package/src/actions/violinPlots/create.js

@@ -2,6 +2,7 @@ import { action } from "../../core/action.js";
 import { validateOptionObject } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
 import {
   applyFacadeGuides,
   normalizeAppearance,
@@ -20,12 +21,13 @@ const OPTIONS = Object.freeze([
 ]);
 const POSITION_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
 const DENSITY_OPTIONS = Object.freeze([
-  "bandwidth", "extent", "steps", "kernel", "normalization", "width", "side"
+  "bandwidth", "extent", "steps", "kernel", "normalization", "weight", "width", "side"
 ]);
 const WIDTH_OPTIONS = Object.freeze(["band", "resolve"]);
 const SPLIT_OPTIONS = Object.freeze(["field", "domain"]);
 const AREA_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth", "curve"
+  "fill", "opacity", "stroke", "strokeWidth", "curve",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 const CATEGORICAL_TYPES = Object.freeze(["nominal", "ordinal"]);
 const OPERATION = "createViolinPlot";
@@ -221,6 +223,7 @@ export const createViolinPlot = action(
           steps: transform.steps,
           kernel: transform.kernel,
           normalization: transform.normalization,
+          ...(transform.weight === undefined ? {} : { weight: transform.weight }),
           width: transform.placement.width,
           side: transform.placement.side
         },

package/src/actions/violinPlots/edit.js

@@ -181,6 +181,7 @@ export const editViolinPlot = action(
           steps: transform.steps,
           kernel: transform.kernel,
           normalization: transform.normalization,
+          ...(transform.weight === undefined ? {} : { weight: transform.weight }),
           width: transform.placement.width,
           side: transform.placement.side
         }

package/src/core/action.js

@@ -1,6 +1,7 @@
 import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
 
 const metadataByWrappedAction = new WeakMap();
+const implementationByWrappedAction = new WeakMap();
 let actionCompletionHook;
 
 export function setActionCompletionHook(hook) {
@@ -14,6 +15,14 @@ export function getWrappedActionMetadata(value) {
   return metadataByWrappedAction.get(value);
 }
 
+export function invokeWrappedActionImplementation(value, program, args = {}) {
+  const implementation = implementationByWrappedAction.get(value);
+  if (implementation === undefined) {
+    throw new TypeError("Expected an action created by action().");
+  }
+  return implementation.call(program, args);
+}
+
 function summarizeObject(value, ancestors = new WeakSet()) {
   if (ancestors.has(value)) {
     throw new TypeError("Action arguments must not contain circular references.");
@@ -161,5 +170,6 @@ export function action(metadata, implementation) {
   };
 
   metadataByWrappedAction.set(wrappedAction, ownedMetadata);
+  implementationByWrappedAction.set(wrappedAction, implementation);
   return wrappedAction;
 }

package/src/core/compositionState.js

@@ -150,8 +150,13 @@ function validateFacetSpec(compositionSpec) {
         "compositionSpec.facet.repeat requires target, channel, and fields."
       );
     }
+    const repeatChannel = ["x", "y", "theta", "r"].includes(repeat.channel) ||
+      (isPlainObject(repeat.channel) &&
+        Object.keys(repeat.channel).length === 1 &&
+        typeof repeat.channel.parallelDimension === "string" &&
+        repeat.channel.parallelDimension.length > 0);
     if (typeof repeat.target !== "string" || repeat.target.length === 0 ||
-        !["x", "y"].includes(repeat.channel) ||
+        !repeatChannel ||
         !Array.isArray(repeat.fields) || repeat.fields.length === 0 ||
         repeat.fields.some(field => typeof field !== "string" || field.length === 0) ||
         new Set(repeat.fields).size !== repeat.fields.length) {

package/src/core/programState.js

@@ -4,6 +4,7 @@ import {
   isOwned,
   isPlainObject
 } from "./immutable.js";
+import { removeMaterializationConfig } from "./materializationState.js";
 
 export function ownProgramState(value) {
   return isOwned(value) ? value : cloneAndFreeze(value);
@@ -26,3 +27,22 @@ export function ownChildPrograms(children, ProgramClass) {
   }
   return freezeOwned(owned);
 }
+
+// Semantic entries, resolved scale caches, and physical current-resource IDs
+// are removed by editSemantic. A logical data owner also retains its own ID
+// and replay configuration; release those non-semantic references after the
+// domain's dependency validation and before the primitive deletion.
+export function releaseNamedResourceOwnership(program, { kind, id, dataOwner }) {
+  if (kind !== "data") return program;
+  const materializationConfigs = dataOwner === undefined
+    ? program.materializationConfigs
+    : removeMaterializationConfig(
+        program.materializationConfigs,
+        ["data", dataOwner.family, dataOwner.owner]
+      ).value;
+  const context = program.context.currentData === id
+    ? freezeOwned({ ...program.context, currentData: undefined })
+    : program.context;
+  if (context === program.context && materializationConfigs === program.materializationConfigs) return program;
+  return program._clone({ context, materializationConfigs });
+}

package/src/core/resourceReferences.js

@@ -0,0 +1,332 @@
+import { freezeOwned, isPlainObject } from "./immutable.js";
+import { validateUserId } from "./identifiers.js";
+
+export const RESOURCE_KINDS = Object.freeze([
+  "data", "scale", "coordinate", "mark", "selection"
+]);
+
+const DATA_VALUE_KEYS = new Set([
+  "data", "dataset", "dataId", "filteredData", "originalData",
+  "outlierDataId", "profileId", "summaryId"
+]);
+const DATA_SOURCE_CONFIGS = new Set([
+  "boxPlot", "density", "ecdfPlot", "endpointPlot", "errorBand", "errorBar",
+  "gradientPlot", "horizon", "intervalPlot", "markFilter", "raincloudPlot",
+  "regression", "violinPlot"
+]);
+const MARK_ID_KEYS = new Set([
+  "bandId", "bodyId", "centerId", "connectorId", "intervalId", "lineId",
+  "lowerBoundaryId", "lowerCapId", "medianId", "outlierId", "startId",
+  "stemId", "upperBoundaryId", "upperCapId", "whiskerId"
+]);
+
+function ownedPath(path) {
+  return freezeOwned([...path]);
+}
+
+function reference(kind, id, ownerKind, ownerId, path, strength = "live") {
+  if (typeof id !== "string" || id.length === 0) return undefined;
+  return freezeOwned({
+    kind,
+    id,
+    ownerKind,
+    ownerId,
+    path: ownedPath(path),
+    strength
+  });
+}
+
+function append(references, value) {
+  if (value !== undefined) references.push(value);
+}
+
+function collectKnownKeys(value, path, visit) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => collectKnownKeys(item, [...path, index], visit));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    visit(key, child, [...path, key], path);
+    collectKnownKeys(child, [...path, key], visit);
+  }
+}
+
+export function canonicalResourcePath(path) {
+  if (!Array.isArray(path)) {
+    throw new TypeError("Resource reference path must be an array.");
+  }
+  return path.map(part => {
+    if (Number.isInteger(part) && part >= 0) return `[${part}]`;
+    if (typeof part !== "string" || part.length === 0) {
+      throw new TypeError("Resource reference path parts must be names or indexes.");
+    }
+    return `.${part}`;
+  }).join("");
+}
+
+export function collectSemanticDataReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    append(references, reference("data", layer.data, "layer", layer.id, ["data"]));
+  }
+  for (const dataset of program.semanticSpec.datasets) {
+    append(references, reference(
+      "data", dataset.source, "dataset", dataset.id, ["source"]
+    ));
+  }
+  return freezeOwned(references);
+}
+
+export function collectSemanticScaleReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    for (const [channel, encoding] of Object.entries(layer.encoding ?? {})) {
+      append(references, reference(
+        "scale", encoding?.scale, "layer", layer.id,
+        ["encoding", channel, "scale"]
+      ));
+      if (channel === "parallel") {
+        for (const [index, dimension] of (encoding?.dimensions ?? []).entries()) {
+          append(references, reference(
+            "scale", dimension.scale, "layer", layer.id,
+            ["encoding", "parallel", "dimensions", index, "scale"]
+          ));
+        }
+      }
+    }
+  }
+  collectKnownKeys(program.semanticSpec.guides, [], (key, value, path) => {
+    if (key === "scale") {
+      append(references, reference(
+        "scale", value, "semanticGuide", "guides", path
+      ));
+    } else if (key === "scales" && Array.isArray(value)) {
+      value.forEach((id, index) => append(references, reference(
+        "scale", id, "semanticGuide", "guides", [...path, index]
+      )));
+    }
+  });
+  return freezeOwned(references);
+}
+
+export function collectSemanticCoordinateReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    append(references, reference(
+      "coordinate", layer.coordinate, "layer", layer.id, ["coordinate"]
+    ));
+  }
+  collectKnownKeys(program.semanticSpec.guides, [], (key, value, path) => {
+    if (key === "coordinate") {
+      append(references, reference(
+        "coordinate", value, "semanticGuide", "guides", path
+      ));
+    }
+  });
+  return freezeOwned(references);
+}
+
+export function collectMarkConfigReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    append(references, reference(
+      "mark", layer.source, "layer", layer.id, ["source"]
+    ));
+  }
+  for (const [ownerId, config] of Object.entries(program.markConfigs)) {
+    collectKnownKeys(config, [], (key, value, path, parentPath) => {
+      if (DATA_VALUE_KEYS.has(key)) {
+        append(references, reference("data", value, "markConfig", ownerId, path));
+      }
+      const root = parentPath[0];
+      if (key === "source" && DATA_SOURCE_CONFIGS.has(root)) {
+        append(references, reference("data", value, "markConfig", ownerId, path));
+      }
+      if (key === "coordinate") {
+        append(references, reference(
+          "coordinate", value, "markConfig", ownerId, path
+        ));
+      }
+      if ((key === "scale" || key.endsWith("Scale")) && typeof value === "string") {
+        append(references, reference("scale", value, "markConfig", ownerId, path));
+      } else if (key === "scale" && isPlainObject(value)) {
+        append(references, reference(
+          "scale", value.id, "markConfig", ownerId, [...path, "id"]
+        ));
+      }
+      if (MARK_ID_KEYS.has(key)) {
+        append(references, reference("mark", value, "markConfig", ownerId, path));
+      }
+      if (
+        (root === "errorBandBoundary" && key === "owner") ||
+        (parentPath.length === 0 && key === "boxSpanOwner") ||
+        (root === "raincloudPlot" && (
+          key === "ownerId" || parentPath[1] === "childIds" ||
+          parentPath[1] === "ownedChildIds"
+        ))
+      ) {
+        append(references, reference("mark", value, "markConfig", ownerId, path));
+      }
+    });
+    append(references, reference(
+      "mark", config.statisticalReference?.source,
+      "markConfig", ownerId, ["statisticalReference", "source"]
+    ));
+    for (const [index, id] of (
+      config.raincloudPlot?.ownedChildIds ?? []
+    ).entries()) {
+      append(references, reference(
+        "mark", id, "markConfig", ownerId,
+        ["raincloudPlot", "ownedChildIds", index]
+      ));
+    }
+    const selection = config.labelAuthoring?.selection;
+    if (selection?.kind === "named") {
+      append(references, reference(
+        "selection", selection.id, "markConfig", ownerId,
+        ["labelAuthoring", "selection", "id"]
+      ));
+    }
+  }
+  return freezeOwned(references);
+}
+
+export function collectGuideConfigReferences(program) {
+  const references = [];
+  for (const [family, configs] of Object.entries(program.guideConfigs ?? {})) {
+    collectKnownKeys(configs, [], (key, value, path, parentPath) => {
+      const ownerId = parentPath.length === 0 ? family : parentPath.join(".");
+      const relativePath = parentPath.length === 0
+        ? path
+        : path.slice(parentPath.length);
+      if (key === "scale") {
+        append(references, reference(
+          "scale", value, family, ownerId, relativePath
+        ));
+      } else if (key === "scales" && Array.isArray(value)) {
+        value.forEach((id, index) => append(references, reference(
+          "scale", id, family, ownerId, [...relativePath, index]
+        )));
+      } else if (key === "coordinate") {
+        append(references, reference(
+          "coordinate", value, family, ownerId, relativePath
+        ));
+      } else if (key === "target") {
+        append(references, reference(
+          "mark", value, family, ownerId, relativePath
+        ));
+      }
+    });
+  }
+  return freezeOwned(references);
+}
+
+export function collectSelectionReferences(program) {
+  const references = [];
+  for (const [id, config] of Object.entries(
+    program.materializationConfigs.selections ?? {}
+  )) {
+    append(references, reference(
+      "mark", config.target, "selection", id, ["target"]
+    ));
+  }
+  for (const [id, config] of Object.entries(
+    program.materializationConfigs.highlights ?? {}
+  )) {
+    append(references, reference(
+      "mark", config.target, "highlight", id, ["target"]
+    ));
+    append(references, reference(
+      "selection", config.selection, "highlight", id, ["selection"]
+    ));
+  }
+  return freezeOwned(references);
+}
+
+export function collectDataOwnerReferences(program) {
+  const references = [];
+  for (const [family, owners] of Object.entries(
+    program.materializationConfigs.data ?? {}
+  )) {
+    for (const [owner, config] of Object.entries(owners ?? {})) {
+      for (const key of ["current", "source", "previous"]) {
+        append(references, reference(
+          "data", config?.[key], "dataOwner", owner,
+          ["data", family, owner, key]
+        ));
+      }
+    }
+  }
+  return freezeOwned(references);
+}
+
+export function collectCompositionReferences(program) {
+  const references = [];
+  const composition = program.compositionSpec;
+  if (composition?.type !== "facet") return freezeOwned(references);
+  append(references, reference(
+    "data", composition.facet.data, "composition", composition.id,
+    ["facet", "data"]
+  ));
+  append(references, reference(
+    "mark", composition.facet.repeat?.target, "composition", composition.id,
+    ["facet", "repeat", "target"]
+  ));
+  return freezeOwned(references);
+}
+
+export function collectContextReferences(program) {
+  const references = [];
+  for (const [key, kind] of Object.entries({
+    currentData: "data",
+    currentScale: "scale",
+    currentCoordinate: "coordinate",
+    currentMark: "mark",
+    currentSelection: "selection"
+  })) {
+    append(references, reference(
+      kind, program.context[key], "context", "program", [key], "context"
+    ));
+  }
+  return freezeOwned(references);
+}
+
+function referenceKey(value) {
+  return [
+    value.kind, value.id, value.ownerKind, value.ownerId,
+    canonicalResourcePath(value.path), value.strength
+  ].join("\u0000");
+}
+
+function compareReferences(left, right) {
+  const leftKey = [
+    left.ownerKind, left.ownerId, canonicalResourcePath(left.path),
+    left.kind, left.id, left.strength
+  ].join("\u0000");
+  const rightKey = [
+    right.ownerKind, right.ownerId, canonicalResourcePath(right.path),
+    right.kind, right.id, right.strength
+  ].join("\u0000");
+  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+}
+
+export function collectResourceReferences(program, { kind, id }) {
+  if (!RESOURCE_KINDS.includes(kind)) {
+    throw new Error(`Unknown resource kind "${kind}".`);
+  }
+  const target = validateUserId(id, "Resource id");
+  const combined = [
+    ...collectSemanticDataReferences(program),
+    ...collectSemanticScaleReferences(program),
+    ...collectSemanticCoordinateReferences(program),
+    ...collectMarkConfigReferences(program),
+    ...collectGuideConfigReferences(program),
+    ...collectSelectionReferences(program),
+    ...collectDataOwnerReferences(program),
+    ...collectCompositionReferences(program),
+    ...collectContextReferences(program)
+  ].filter(value => value.kind === kind && value.id === target);
+  const unique = new Map(combined.map(value => [referenceKey(value), value]));
+  return freezeOwned([...unique.values()].sort(compareReferences));
+}

package/src/core/vocabulary.js

@@ -13,13 +13,13 @@ export const MARK_TYPES = Object.freeze([
 export const MARK_GRAPHIC_TYPES = Object.freeze({
   point: Object.freeze(["circle", "rect", "path", "collection"]),
   line: Object.freeze(["path"]),
-  bar: Object.freeze(["rect"]),
+  bar: Object.freeze(["rect", "collection"]),
   area: Object.freeze(["path"]),
   arc: Object.freeze(["path"]),
   rule: Object.freeze(["line"]),
   tick: Object.freeze(["line"]),
   text: Object.freeze(["text"]),
-  rect: Object.freeze(["rect"])
+  rect: Object.freeze(["rect", "collection"])
 });
 
 export const ENCODING_CHANNELS = Object.freeze([
@@ -32,6 +32,7 @@ export const ENCODING_CHANNELS = Object.freeze([
   "theta",
   "radius",
   "color",
+  "stroke",
   "strokeDash",
   "strokeWidth",
   "size",
@@ -155,13 +156,21 @@ export const FACET_SCALE_CHANNELS = Object.freeze([
   "y",
   "xOffset",
   "yOffset",
+  "theta",
+  "r",
   "color",
+  "stroke",
   "size",
   "shape",
   "opacity",
-  "strokeDash"
+  "strokeDash",
+  "parallelDimensions"
 ]);
 
+export function facetSemanticChannel(channel) {
+  return channel === "r" ? "radius" : channel;
+}
+
 export const FACET_SCALE_RESOLUTIONS = Object.freeze([
   "shared",
   "independent"
@@ -198,6 +207,7 @@ export const STACK_MODES = Object.freeze(["zero", "normalize", "center"]);
 
 export const CATEGORICAL_LEGEND_CHANNELS = Object.freeze([
   "color",
+  "stroke",
   "strokeDash",
   "shape"
 ]);
@@ -212,9 +222,12 @@ export const LEGEND_CHANNELS = Object.freeze([
 export const LEGEND_CONFIG_KINDS = Object.freeze([
   "series",
   "color",
+  "stroke",
   "size",
   "gradient",
   "interval",
+  "strokeGradient",
+  "strokeInterval",
   "opacity",
   "strokeWidth"
 ]);