ggaction 0.0.13 → 0.0.15

package/src/actions/selection/actions.js

@@ -2,7 +2,9 @@ import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateKeys } from "../../core/validation.js";
-import { resolveEligibleLayer } from "../../selectors/layers.js";
+import { collectResourceReferences } from "../../core/resourceReferences.js";
+import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
+import { isSourceOwnedText } from "../../grammar/text.js";
 import { transformPointHighlightChild } from "../../materialization/selection/point.js";
 import {
   transformPathHighlightProperties,
@@ -22,6 +24,10 @@ import {
   normalizeDimOthers,
   validateUnitInterval
 } from "../../materialization/selection/styles.js";
+import {
+  normalizeThemeState,
+  resolveEffectiveThemeTokens
+} from "../theme/state.js";
 
 const SELECTOR_KEYS = Object.freeze([
   "grain", "field", "channel", "property", "op", "value", "values", "min", "max",
@@ -58,32 +64,38 @@ function resolveTarget(program, target, label = "mark selection") {
 }
 
 function hasLegendSelection(program, target, selection) {
-  const legend = program.guideConfigs.legend?.series ??
-    program.guideConfigs.legend?.color;
   const selector = program.materializationConfigs.selections?.[selection]?.selector;
-  return legend?.target === target &&
-    selector?.field !== undefined &&
-    selector.field === legend.field;
+  const layer = findLayer(program, target);
+  const field = selector?.field ?? layer?.encoding?.[selector?.channel]?.field;
+  if (field === undefined) return false;
+  return ["series", "color", "stroke"].some(kind => {
+    const legend = program.guideConfigs.legend?.[kind];
+    return legend?.target === target && legend.field === field &&
+      (selector?.channel === undefined || legend.channels.includes(selector.channel));
+  });
 }
 
-function categoricalLegendKind(program, target) {
-  return ["series", "color"].find(
+function categoricalLegendKinds(program, target) {
+  return ["series", "color", "stroke"].filter(
     kind => program.guideConfigs.legend?.[kind]?.target === target
   );
 }
 
 function resetCategoricalLegendSymbols(program, target) {
-  const kind = categoricalLegendKind(program, target);
-  if (kind === undefined) return program;
+  const kinds = categoricalLegendKinds(program, target);
+  if (kinds.length === 0) return program;
   let next = program;
-  for (const id of legendGraphicIds(kind).filter(id => id.includes("Symbol"))) {
-    const graphic = next.graphicSpec.objects[id];
-    if (graphic === undefined) continue;
-    next = graphic.type === "collection"
-      ? next.editGraphics({ target: id, property: "items", value: [] })
-      : next.editGraphics({ target: id, property: "length", value: 0 });
+  for (const kind of kinds) {
+    for (const id of legendGraphicIds(kind).filter(id => id.includes("Symbol"))) {
+      const graphic = next.graphicSpec.objects[id];
+      if (graphic === undefined) continue;
+      next = graphic.type === "collection"
+        ? next.editGraphics({ target: id, property: "items", value: [] })
+        : next.editGraphics({ target: id, property: "length", value: 0 });
+    }
+    next = next.rematerializeLegendSymbols({ kind });
   }
-  return next.rematerializeLegendSymbols();
+  return next;
 }
 
 function targetHighlightEntries(program, target) {
@@ -91,7 +103,32 @@ function targetHighlightEntries(program, target) {
     .filter(([, config]) => config.target === target);
 }
 
-function rebuildTargetHighlights(program, target) {
+function namedLabelDependents(program, selection) {
+  const referenced = new Set(collectResourceReferences(program, {
+    kind: "selection",
+    id: selection
+  }).filter(reference =>
+    reference.ownerKind === "markConfig" &&
+    reference.path.join(".") === "labelAuthoring.selection.id"
+  ).map(reference => reference.ownerId));
+  return Object.entries(program.markConfigs)
+    .filter(([id, config]) => {
+      const layer = findLayer(program, id);
+      return isSourceOwnedText(layer) &&
+        config?.labelAuthoring?.selection?.kind === "named" &&
+        referenced.has(id);
+    })
+    .map(([id]) => id)
+    .sort();
+}
+
+function rematerializeLabels(program, ids) {
+  let next = program;
+  for (const id of ids) next = next.rematerializeTextMark({ id });
+  return next;
+}
+
+function rebuildTargetHighlights(program, target, { labels = [] } = {}) {
   const layer = resolveTarget(program, target, "highlight mark");
   const highlights = targetHighlightEntries(program, target);
   let baseline = program;
@@ -105,12 +142,26 @@ function rebuildTargetHighlights(program, target) {
   baseline = baseline[requireSelectionPolicy(
     layer.mark.type
   ).rematerializeOp]({ id: target });
+  baseline = rematerializeLabels(baseline, labels);
   baseline = resetCategoricalLegendSymbols(baseline, target);
   return highlights.length === 0
     ? baseline
     : baseline.rematerializeMarkHighlights({ target, highlights });
 }
 
+export function rematerializeLabelsBeforeHighlights(
+  program,
+  target,
+  labels,
+  { skipWithoutHighlights = false } = {}
+) {
+  return targetHighlightEntries(program, target).length === 0
+    ? skipWithoutHighlights
+      ? program
+      : rematerializeLabels(program, labels)
+    : rebuildTargetHighlights(program, target, { labels });
+}
+
 function selectedKeys(args, resolved) {
   if (args.keys === undefined) return resolved.keys;
   if (!Array.isArray(args.keys) || !args.keys.every(key =>
@@ -155,9 +206,10 @@ function editSelectedItems(
 }
 
 function applyHighlight(program, config, keys) {
+  const style = resolveHighlightStyle(program, config);
   let next = program[requireSelectionPolicy(config.markType).applyHighlightOp]({
     selection: config.selection,
-    style: config.style,
+    style,
     keys
   });
   if (config.dimOthers !== false) {
@@ -172,6 +224,60 @@ function applyHighlight(program, config, keys) {
     : next;
 }
 
+function highlightPaintProperty(markType) {
+  return ["line", "rule", "tick"].includes(markType) ? "stroke" : "fill";
+}
+
+function requestedPaintSource(args, markType, style) {
+  const property = highlightPaintProperty(markType);
+  const explicit = args.color !== undefined || args[property] !== undefined;
+  if (explicit) return "explicit";
+  return Object.hasOwn(style, property) ? "theme" : "preserve";
+}
+
+function tracePaintSource(program, id, config) {
+  let source;
+  for (const node of program.trace.children) {
+    if (node.op !== "highlightMarks") continue;
+    const requestedId = node.args.selection ?? node.args.id ??
+      `${node.args.target ?? config.target}Selection`;
+    if (requestedId !== id) continue;
+    const property = highlightPaintProperty(config.markType);
+    const explicit = node.args.color !== undefined ||
+      node.args[property] !== undefined;
+    source = explicit
+      ? "explicit"
+      : Object.hasOwn(config.style, property) ? "theme" : "preserve";
+  }
+  return source ?? "explicit";
+}
+
+function normalizeStoredHighlightConfig(program, id, config) {
+  return config.paintSource === undefined
+    ? { ...config, paintSource: tracePaintSource(program, id, config) }
+    : config;
+}
+
+function resolveHighlightStyle(program, config) {
+  if (config.paintSource !== "theme") return config.style;
+  const property = highlightPaintProperty(config.markType);
+  return {
+    ...config.style,
+    [property]: resolveEffectiveThemeTokens(normalizeThemeState(
+      program.materializationConfigs.theme
+    )).highlight
+  };
+}
+
+export function rematerializeThemeHighlights(program) {
+  const targets = [...new Set(Object.values(
+    program.materializationConfigs.highlights ?? {}
+  ).map(config => config.target))];
+  let next = program;
+  for (const target of targets) next = rebuildTargetHighlights(next, target);
+  return next;
+}
+
 export const selectMarks = action(
   { op: "selectMarks", description: "Create one reusable selection over final mark items." },
   function (args = {}) {
@@ -198,7 +304,7 @@ export const editMarkSelection = action(
       current.definition.target,
       selectorFrom(args)
     );
-    const next = this
+    let next = this
       ._withSelectionConfig(current.id, {
         target: current.definition.target,
         selector: replacement.selector
@@ -207,9 +313,15 @@ export const editMarkSelection = action(
     const hasDependentHighlight = Object.values(
       next.materializationConfigs.highlights ?? {}
     ).some(config => config.selection === current.id);
-    return hasDependentHighlight
-      ? rebuildTargetHighlights(next, current.definition.target)
-      : next;
+    const labels = namedLabelDependents(this, current.id);
+    if (hasDependentHighlight) {
+      return rematerializeLabelsBeforeHighlights(
+        next,
+        current.definition.target,
+        labels
+      );
+    }
+    return rematerializeLabels(next, labels);
   }
 );
 
@@ -245,6 +357,12 @@ export const removeMarkSelection = action(
   function (args = {}) {
     validateKeys(args, REMOVE_SELECTION_OPTIONS, "removeMarkSelection");
     const current = resolveStoredSelection(this, args.selection);
+    const labelDependents = namedLabelDependents(this, current.id);
+    if (labelDependents.length > 0) {
+      throw new Error(
+        `Selection "${current.id}" is referenced by attached labels: ${labelDependents.join(", ")}.`
+      );
+    }
     const hasDependentHighlight = Object.values(
       this.materializationConfigs.highlights ?? {}
     ).some(config => config.selection === current.id);
@@ -287,6 +405,15 @@ function transformRectangularProperties(properties, style, offset = false) {
   };
 }
 
+function transformRectangularHighlightChild(item, style, offset) {
+  return {
+    ...item,
+    properties: item.type === "path"
+      ? transformPathHighlightProperties(item.properties, style)
+      : transformRectangularProperties(item.properties, style, offset)
+  };
+}
+
 function applyRectangularHighlight(
   program,
   args,
@@ -301,12 +428,8 @@ function applyRectangularHighlight(
     throw new Error(`${operation} requires a ${markType} selection.`);
   }
   if (keys.length === 0) return program;
-  return editSelectedItems(program, resolved, keys, item => ({
-    ...item,
-    properties: transformRectangularProperties(
-      item.properties, args.style, offset
-    )
-  }));
+  return editSelectedItems(program, resolved, keys, item =>
+    transformRectangularHighlightChild(item, args.style, offset));
 }
 
 export const applyBarHighlight = action(
@@ -415,7 +538,7 @@ export const rematerializeMarkHighlights = action(
     }
     const prepared = args.highlights.map(([id, config]) => ({
       id,
-      config,
+      config: normalizeStoredHighlightConfig(this, id, config),
       keys: resolveStoredSelection(this, config.selection).keys
     }));
     let next = this;
@@ -492,6 +615,7 @@ export const highlightMarks = action(
       selection,
       markType: layer.mark.type,
       style,
+      paintSource: requestedPaintSource(args, layer.mark.type, style),
       dimOthers,
       bringToFront
     };

package/src/actions/selection/index.js

@@ -9,12 +9,15 @@ import {
   highlightMarks,
   placeSelectedMarkItemsLast,
   rematerializeMarkHighlights,
+  rematerializeThemeHighlights,
   removeMarkHighlight,
   removeMarkSelection,
   selectMarks
 } from "./actions.js";
+import { registerThemeHighlightReconciler } from "../theme/reconcile.js";
 
 export function registerSelectionActions(ProgramClass) {
+  registerThemeHighlightReconciler(rematerializeThemeHighlights);
   ProgramClass.prototype.selectMarks = selectMarks;
   ProgramClass.prototype.editMarkSelection = editMarkSelection;
   ProgramClass.prototype.removeMarkHighlight = removeMarkHighlight;

package/src/actions/theme/actions.js

@@ -1,25 +1,71 @@
 import { action } from "../../core/action.js";
 import { noOptions, validateOptionObject } from "../../core/validation.js";
-import { THEME_NAMES } from "../../theme/defaults.js";
+import { normalizeThemeDefinition } from "../../theme/defaults.js";
+import {
+  LOCAL_THEME_OWNER,
+  createThemeFrame,
+  moveLocalThemeScope,
+  normalizeThemeState,
+  removeThemeFrameOwner,
+  upsertThemeFrame
+} from "./state.js";
+
+let compositionThemeHandlers;
+
+export function registerCompositionThemeHandlers(handlers) {
+  if (handlers === undefined ||
+      typeof handlers.apply !== "function" ||
+      typeof handlers.remove !== "function") {
+    throw new TypeError("Composition theme handlers must provide apply and remove functions.");
+  }
+  compositionThemeHandlers = handlers;
+}
+
+function requireCompositionThemeHandlers() {
+  if (compositionThemeHandlers === undefined) {
+    throw new Error("Composition theme actions are unavailable from this entry point.");
+  }
+  return compositionThemeHandlers;
+}
 
 export const applyTheme = action(
   {
     op: "applyTheme",
-    description: "Apply persistent visual defaults to the chart program."
+    description: "Apply persistent visual defaults to the chart program.",
+    scope: "any"
   },
   function (args = {}) {
-    validateOptionObject(args, ["theme"], "applyTheme", {
+    validateOptionObject(args, ["theme", "scope"], "applyTheme", {
       allowEmpty: false,
       emptyMessage: "applyTheme requires theme.",
       emptyError: Error
     });
-    if (!THEME_NAMES.includes(args.theme)) {
-      throw new Error(`Unsupported theme "${args.theme}".`);
+    if (!Object.hasOwn(args, "theme")) {
+      throw new Error("applyTheme requires theme.");
     }
-    const previous = this.materializationConfigs.theme;
+    const definition = normalizeThemeDefinition(args.theme);
+    if (args.scope !== undefined &&
+        !["self", "descendants"].includes(args.scope)) {
+      throw new Error(`Unsupported theme scope "${args.scope}".`);
+    }
+    if (this.compositionSpec !== undefined) {
+      return requireCompositionThemeHandlers().apply(
+        this,
+        { base: definition.name, tokens: definition.tokens },
+        args.scope ?? "descendants"
+      );
+    }
+    const scope = "self";
+    const previous = normalizeThemeState(this.materializationConfigs.theme);
+    const frame = createThemeFrame({
+      owner: LOCAL_THEME_OWNER,
+      scope,
+      definition: { base: definition.name, tokens: definition.tokens }
+    });
     return this._withMaterializationConfig(["theme"], {
-      name: args.theme,
-      overrides: previous?.overrides ?? []
+      ...previous,
+      frames: upsertThemeFrame(previous.frames, frame),
+      localOrder: moveLocalThemeScope(previous.localOrder, scope)
     });
   }
 );
@@ -27,17 +73,26 @@ export const applyTheme = action(
 export const removeTheme = action(
   {
     op: "removeTheme",
-    description: "Remove program theme defaults while preserving local styles."
+    description: "Remove program theme defaults while preserving local styles.",
+    scope: "any"
   },
   function (args = {}) {
     noOptions(args, "removeTheme");
-    if (this.materializationConfigs.theme === undefined) {
+    if (this.compositionSpec !== undefined) {
+      return requireCompositionThemeHandlers().remove(this);
+    }
+    const previous = normalizeThemeState(this.materializationConfigs.theme);
+    const removed = removeThemeFrameOwner(
+      previous.frames,
+      LOCAL_THEME_OWNER
+    );
+    if (!removed.removed) {
       throw new Error("removeTheme requires an active program theme.");
     }
     return this._withMaterializationConfig(["theme"], {
-      ...this.materializationConfigs.theme,
-      name: "light",
-      removing: true
+      ...previous,
+      frames: removed.frames,
+      localOrder: previous.localOrder.filter(scope => scope !== "self")
     });
   }
 );

package/src/actions/theme/composition.js

@@ -0,0 +1,238 @@
+import { freezeOwned } from "../../core/immutable.js";
+import { materializeCompositionGraphics } from
+  "../../materialization/composition.js";
+import { materializeFacetGraphics } from "../../materialization/facets.js";
+import {
+  compositionThemeOwner,
+  createThemeFrame,
+  moveLocalThemeScope,
+  normalizeThemeState,
+  removeThemeFrameOwner,
+  upsertThemeFrame
+} from "./state.js";
+import { reconcileProgramTheme } from "./reconcile.js";
+
+const DESCRIPTION = "Apply inherited visual defaults to a composition child.";
+
+function materializeComposition(program) {
+  return program.compositionSpec.type === "facet"
+    ? materializeFacetGraphics(program)
+    : materializeCompositionGraphics(program);
+}
+
+function withThemeState(program, state) {
+  return program._withMaterializationConfig(["theme"], state);
+}
+
+function addFrame(program, frame, { descendants, local = false }) {
+  const composition = program.compositionSpec !== undefined;
+  const previous = normalizeThemeState(
+    program.materializationConfigs.theme,
+    { composition }
+  );
+  return withThemeState(program, {
+    ...previous,
+    frames: upsertThemeFrame(previous.frames, frame),
+    ...(composition
+      ? {
+          descendantFrames: descendants
+            ? upsertThemeFrame(previous.descendantFrames, frame)
+            : previous.descendantFrames
+        }
+      : {}),
+    localOrder: local
+      ? moveLocalThemeScope(previous.localOrder, frame.scope)
+      : previous.localOrder
+  });
+}
+
+function removeFrame(program, owner, { descendants, localScope }) {
+  const composition = program.compositionSpec !== undefined;
+  const previous = normalizeThemeState(
+    program.materializationConfigs.theme,
+    { composition }
+  );
+  const root = removeThemeFrameOwner(previous.frames, owner);
+  const policies = composition && descendants
+    ? removeThemeFrameOwner(previous.descendantFrames, owner)
+    : { frames: previous.descendantFrames, removed: false };
+  return {
+    program: withThemeState(program, {
+      ...previous,
+      frames: root.frames,
+      ...(composition ? { descendantFrames: policies.frames } : {}),
+      localOrder: localScope === undefined
+        ? previous.localOrder
+        : freezeOwned(previous.localOrder.filter(scope => scope !== localScope))
+    }),
+    removed: root.removed || policies.removed
+  };
+}
+
+function inheritedMetadata(op) {
+  return freezeOwned({ op, description: DESCRIPTION, scope: "any" });
+}
+
+function enterInheritedAction(program, op, frame) {
+  return program._enterAction({
+    op,
+    description: DESCRIPTION,
+    args: op === "applyTheme"
+      ? freezeOwned({
+          theme: freezeOwned({
+            base: frame.name,
+            tokens: frame.tokens
+          }),
+          scope: "descendants",
+          inheritedFrom: frame.owner
+        })
+      : freezeOwned({ inheritedFrom: frame.owner })
+  });
+}
+
+function applyInheritedFrame(program, frame) {
+  const source = program;
+  let next = enterInheritedAction(program, "applyTheme", frame);
+  next = addFrame(next, frame, {
+    descendants: next.compositionSpec !== undefined
+  });
+
+  if (next.compositionSpec !== undefined) {
+    const children = Object.fromEntries(
+      next.compositionSpec.children.map(id => [
+        id,
+        applyInheritedFrame(next.children[id], frame)
+      ])
+    );
+    next = next._withCompositionState({
+      children,
+      compositionSpec: next.compositionSpec
+    });
+    next = materializeComposition(next);
+  }
+
+  next = reconcileProgramTheme(next, {
+    source,
+    metadata: inheritedMetadata("applyTheme")
+  });
+  return next._exitAction();
+}
+
+function removeInheritedFrame(program, frame) {
+  const source = program;
+  let next = enterInheritedAction(program, "removeTheme", frame);
+  const removed = removeFrame(next, frame.owner, {
+    descendants: next.compositionSpec !== undefined
+  });
+  next = removed.program;
+
+  if (next.compositionSpec !== undefined) {
+    const children = Object.fromEntries(
+      next.compositionSpec.children.map(id => [
+        id,
+        removeInheritedFrame(next.children[id], frame)
+      ])
+    );
+    next = next._withCompositionState({
+      children,
+      compositionSpec: next.compositionSpec
+    });
+    next = materializeComposition(next);
+  }
+
+  next = reconcileProgramTheme(next, {
+    source,
+    metadata: inheritedMetadata("removeTheme")
+  });
+  return next._exitAction();
+}
+
+export function applyCompositionTheme(program, definition, scope) {
+  const id = program.compositionSpec.id;
+  const frame = createThemeFrame({
+    owner: compositionThemeOwner(id, scope),
+    scope,
+    definition
+  });
+  let next = addFrame(program, frame, {
+    descendants: scope === "descendants",
+    local: true
+  });
+  if (scope !== "descendants") return next;
+
+  const children = Object.fromEntries(
+    next.compositionSpec.children.map(childId => [
+      childId,
+      applyInheritedFrame(next.children[childId], frame)
+    ])
+  );
+  next = next._withCompositionState({
+    children,
+    compositionSpec: next.compositionSpec
+  });
+  return materializeComposition(next);
+}
+
+export function removeCompositionTheme(program) {
+  const state = normalizeThemeState(
+    program.materializationConfigs.theme,
+    { composition: true }
+  );
+  const scope = state.localOrder.at(-1);
+  if (scope === undefined) {
+    throw new Error("removeTheme requires an active program theme.");
+  }
+  const owner = compositionThemeOwner(program.compositionSpec.id, scope);
+  const frame = state.frames.find(current => current.owner === owner) ??
+    state.descendantFrames.find(current => current.owner === owner);
+  if (frame === undefined) {
+    throw new Error("removeTheme requires an active program theme.");
+  }
+
+  let next = removeFrame(program, owner, {
+    descendants: scope === "descendants",
+    localScope: scope
+  }).program;
+  if (scope !== "descendants") return next;
+
+  const children = Object.fromEntries(
+    next.compositionSpec.children.map(id => [
+      id,
+      removeInheritedFrame(next.children[id], frame)
+    ])
+  );
+  next = next._withCompositionState({
+    children,
+    compositionSpec: next.compositionSpec
+  });
+  return materializeComposition(next);
+}
+
+export function replayCompositionThemeState(program, storedState) {
+  if (storedState === undefined) return program;
+  const state = normalizeThemeState(storedState, { composition: true });
+  let next = withThemeState(program, state);
+  for (const frame of state.descendantFrames) {
+    const children = Object.fromEntries(
+      next.compositionSpec.children.map(id => [
+        id,
+        applyInheritedFrame(next.children[id], frame)
+      ])
+    );
+    next = next._withCompositionState({
+      children,
+      compositionSpec: next.compositionSpec
+    });
+  }
+  return materializeComposition(next);
+}
+
+export function replayInheritedThemeFrames(program, storedState) {
+  if (storedState === undefined) return program;
+  const state = normalizeThemeState(storedState, { composition: true });
+  let next = program;
+  for (const frame of state.descendantFrames) {
+    next = applyInheritedFrame(next, frame);
+  }
+  return next;
+}

package/src/actions/theme/index.js

@@ -1,8 +1,15 @@
 import { setActionCompletionHook } from "../../core/action.js";
-import { applyTheme, removeTheme } from "./actions.js";
+import {
+  applyTheme,
+  registerCompositionThemeHandlers,
+  removeTheme
+} from "./actions.js";
 import { reconcileProgramTheme } from "./reconcile.js";
 
-export function registerThemeActions(ProgramClass) {
+export function registerThemeActions(ProgramClass, compositionHandlers) {
+  if (compositionHandlers !== undefined) {
+    registerCompositionThemeHandlers(compositionHandlers);
+  }
   ProgramClass.prototype.applyTheme = applyTheme;
   ProgramClass.prototype.removeTheme = removeTheme;
   setActionCompletionHook(reconcileProgramTheme);