ggaction 0.0.13 → 0.0.15

package/src/actions/facets/actions.js

@@ -11,6 +11,8 @@ import {
   resolveFacetDefinition,
   resolveFacetGridDefinition
 } from "../../grammar/facets/index.js";
+import { collectFacetScaleBindings, resolveFacetFamily } from
+  "../../grammar/facets/dependencies.js";
 import {
   FACET_SCALE_CHANNELS,
   normalizeFacetScalePolicies
@@ -18,14 +20,21 @@ import {
 import { resolveFacetLayout } from "../../layout/facets.js";
 import { compositionChildDescriptor } from
   "../../materialization/composition.js";
-import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../theme/defaults.js";
 import { deriveFacetChildren } from "./derive.js";
 import { resolveFacetChildrenScales } from "./derive.js";
 import { replayDerivedData } from "./replay.js";
 import { composeFacetGuides } from "./guides.js";
 import { applyCompositionState } from "../composition/actions.js";
+import { replayCompositionThemeState } from "../theme/composition.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import { normalizeDisplayLabelMap } from "../../grammar/displayLabels.js";
+import {
+  createDefaultFacetHeaders,
+  normalizeFacetHeadersConfig,
+  resolveFacetHeaderConfig
+} from "../../materialization/facetHeaders.js";
 
 const FACET_OPTIONS = Object.freeze([
   "id", "field", "data", "values", "columns", "gap", "align", "padding", "scales",
@@ -42,15 +51,12 @@ const REPEAT_OPTIONS = Object.freeze([
 const SOURCE_EDIT_OPTIONS = Object.freeze(["program"]);
 const GUIDE_OPTIONS = Object.freeze(["axes", "legend"]);
 const HEADER_OPTIONS = Object.freeze([
-  "fontSize", "fontFamily", "fontWeight", "color", "offset"
+  "fontSize", "fontFamily", "fontWeight", "color", "offset", "role",
+  "labelMap", "side", "align"
+]);
+const HEADER_STYLE_OPTIONS = Object.freeze([
+  "fontSize", "fontFamily", "fontWeight", "color", "offset", "align"
 ]);
-const DEFAULT_HEADERS = Object.freeze({
-  fontSize: 12,
-  fontFamily: DEFAULT_FONT_FAMILY,
-  fontWeight: 600,
-  color: DEFAULT_COLORS.strongText,
-  offset: 10
-});
 
 function normalizeGuides(guides) {
   if (guides === undefined) return { axes: "each", legend: false };
@@ -74,11 +80,14 @@ function requireFacetProgram(program, operation) {
 }
 
 function usedFacetScalePolicies(program, policies) {
-  return Object.fromEntries(FACET_SCALE_CHANNELS.flatMap(channel =>
-    program.semanticSpec.layers.some(
-      layer => layer.encoding?.[channel]?.scale !== undefined
-    ) ? [[channel, policies[channel]]] : []
-  ));
+  const used = new Set(
+    collectFacetScaleBindings(program.semanticSpec).map(binding => binding.policyKey)
+  );
+  return Object.fromEntries(
+    FACET_SCALE_CHANNELS.flatMap(channel =>
+      used.has(channel) ? [[channel, policies[channel]]] : []
+    )
+  );
 }
 
 function facetUnitTemplate(program) {
@@ -96,6 +105,9 @@ function facetUnitTemplate(program) {
     resolvedScales: program.resolvedScales,
     materializationConfigs: freezeOwned({
       ...unitConfigs,
+      ...(seed.materializationConfigs.theme === undefined
+        ? {}
+        : { theme: seed.materializationConfigs.theme }),
       ...(seed.materializationConfigs.guides === undefined
         ? {}
         : { guides: seed.materializationConfigs.guides }),
@@ -145,11 +157,7 @@ function rederiveFacet(program, { scales, guides }) {
         columns: current.facet.grid.columns,
         combinations: current.facet.grid.combinations
       });
-  const request = Object.fromEntries(FACET_SCALE_CHANNELS.flatMap(channel =>
-    program.semanticSpec.layers.some(
-      layer => layer.encoding?.[channel]?.scale !== undefined
-    ) ? [[channel, scales[channel]]] : []
-  ));
+  const request = usedFacetScalePolicies(program, scales);
   const normalized = normalizeFacetScalePolicies(program.semanticSpec, request);
   const template = facetUnitTemplate(program);
   const derived = deriveFacetChildren(template, definition, {
@@ -184,6 +192,9 @@ export const facet = action(
     validateOptionObject(args, FACET_OPTIONS, "facet");
     const guides = normalizeGuides(args.guides);
     const definition = resolveFacetDefinition(this.semanticSpec, args);
+    if (definition.family !== "cartesian" && guides.axes === "outer") {
+      throw new Error("Polar and Parallel facets do not support outer axes.");
+    }
     const scalePolicies = normalizeFacetScalePolicies(
       this.semanticSpec,
       args.scales ?? {}
@@ -222,7 +233,7 @@ export const facet = action(
     };
     return applyCompositionState(
       this._withMaterializationConfig(["facets", definition.id], {
-        headers: DEFAULT_HEADERS
+        headers: createDefaultFacetHeaders()
       }),
       {
         children: derived.children,
@@ -238,8 +249,20 @@ function resolveRepeatDefinition(program, args) {
     throw new TypeError("repeatCharts options must be a plain object.");
   }
   const id = validateUserId(args.id ?? "repeat", "Repeat id");
-  if (!["x", "y"].includes(args.channel)) {
-    throw new Error('repeatCharts channel must be "x" or "y".');
+  const parallelChannel = isPlainObject(args.channel);
+  if (parallelChannel) {
+    const keys = Object.keys(args.channel);
+    if (keys.length !== 1 || keys[0] !== "parallelDimension" ||
+        typeof args.channel.parallelDimension !== "string" ||
+        args.channel.parallelDimension.length === 0) {
+      throw new Error(
+        "repeatCharts Parallel channel must contain exactly one non-empty parallelDimension."
+      );
+    }
+  } else if (!["x", "y", "theta", "r"].includes(args.channel)) {
+    throw new Error(
+      'repeatCharts channel must be "x", "y", "theta", "r", or one parallelDimension.'
+    );
   }
   if (!Array.isArray(args.fields) || args.fields.length === 0 ||
       args.fields.some(field => typeof field !== "string" || field.length === 0)) {
@@ -248,29 +271,53 @@ function resolveRepeatDefinition(program, args) {
   if (new Set(args.fields).size !== args.fields.length) {
     throw new Error("repeatCharts fields must be unique.");
   }
-  const eligible = program.semanticSpec.layers.filter(layer =>
-    layer.encoding?.x?.scale !== undefined &&
-    layer.encoding?.y?.scale !== undefined &&
-    layer.encoding?.[args.channel]?.field !== undefined &&
-    ["point", "line", "area", "bar", "rule", "tick", "rect"].includes(layer.mark?.type)
-  );
+  const family = resolveFacetFamily(program.semanticSpec).family;
+  const semanticChannel = args.channel === "r" ? "radius" : args.channel;
+  const eligible = program.semanticSpec.layers.filter(layer => {
+    if (parallelChannel) {
+      const matches = (layer.encoding?.parallel?.dimensions ?? []).filter(
+        dimension => dimension.field === args.channel.parallelDimension
+      );
+      return family === "parallel" && layer.mark?.type === "line" && matches.length === 1;
+    }
+    if (["x", "y"].includes(args.channel)) {
+      return family === "cartesian" &&
+        layer.encoding?.x?.scale !== undefined &&
+        layer.encoding?.y?.scale !== undefined &&
+        layer.encoding?.[args.channel]?.field !== undefined &&
+        ["point", "line", "area", "bar", "rule", "tick", "rect"].includes(layer.mark?.type);
+    }
+    const role = program.markConfigs[layer.id]?.compositionRole;
+    if (family !== "polar" || ["pie", "radar"].includes(role)) return false;
+    return ["point", "line", "arc"].includes(layer.mark?.type) &&
+      layer.encoding?.[semanticChannel]?.field !== undefined;
+  });
   let target;
   if (args.target !== undefined) {
     target = validateUserId(args.target, "Repeat target");
     if (!eligible.some(layer => layer.id === target)) {
-      throw new Error(`repeatCharts target "${target}" is not an eligible Cartesian mark.`);
+      throw new Error(
+        `repeatCharts target "${target}" is not eligible for the requested field role.`
+      );
     }
   } else if (eligible.length === 1) {
     target = eligible[0].id;
   } else {
     throw new Error(
       eligible.length === 0
-        ? "repeatCharts requires one complete Cartesian mark."
+        ? "repeatCharts requires one eligible complete mark for the requested field role."
         : "repeatCharts target is ambiguous; provide target."
     );
   }
-  if (program.semanticSpec.layers.length !== 1) {
-    throw new Error("repeatCharts currently supports one direct Cartesian mark only.");
+  const unrelatedLayers = program.semanticSpec.layers.filter(layer => {
+    if (layer.id === target) return false;
+    const attachedLabel = layer.mark?.type === "text" && layer.source === target;
+    const statisticalReference = program.markConfigs[layer.id]
+      ?.statisticalReference?.source === target;
+    return !attachedLabel && !statisticalReference;
+  });
+  if (unrelatedLayers.length > 0) {
+    throw new Error("repeatCharts currently supports one direct mark only.");
   }
   const config = program.markConfigs[target] ?? {};
   const composite = [
@@ -285,14 +332,23 @@ function resolveRepeatDefinition(program, args) {
   if (dataset?.transform?.length > 0) {
     throw new Error("repeatCharts does not rewrite a derived dataset dependency.");
   }
-  const encoding = layer.encoding[args.channel];
+  const encoding = parallelChannel
+    ? layer.encoding.parallel
+    : layer.encoding[semanticChannel];
+  const dimensionIndex = parallelChannel
+    ? encoding.dimensions.findIndex(
+        dimension => dimension.field === args.channel.parallelDimension
+      )
+    : undefined;
   return {
     id,
     target,
-    channel: args.channel,
+    channel: parallelChannel ? { ...args.channel } : args.channel,
+    policyKey: parallelChannel ? "parallelDimensions" : args.channel,
     fields: [...args.fields],
     data: layer.data,
     encoding,
+    ...(dimensionIndex === undefined ? {} : { dimensionIndex }),
     cells: args.fields.map((field, index) => ({
       id: `${id}-field-${index + 1}`,
       field,
@@ -316,15 +372,52 @@ function repeatEncodingArgs(definition, field) {
   };
 }
 
+function parallelRepeatDimensions(program, definition, field) {
+  return definition.encoding.dimensions.map((dimension, index) => {
+    const semanticScale = findSemanticScale(program, dimension.scale);
+    if (semanticScale === undefined) {
+      throw new Error(`repeatCharts Parallel dimension scale "${dimension.scale}" is missing.`);
+    }
+    const { id: _id, ...scale } = semanticScale;
+    void _id;
+    const replacement = index === definition.dimensionIndex;
+    return {
+      field: replacement ? field : dimension.field,
+      fieldType: dimension.fieldType,
+      title: replacement && dimension.title === dimension.field
+        ? field
+        : dimension.title,
+      scale
+    };
+  });
+}
+
+function deriveRepeatedProgram(template, definition, field) {
+  if (isPlainObject(definition.channel)) {
+    return template.encodeParallelCoordinates({
+      target: definition.target,
+      coordinate: findLayer(template, definition.target).coordinate,
+      dimensions: parallelRepeatDimensions(template, definition, field),
+      ...(definition.encoding.key === undefined ? {} : { key: definition.encoding.key }),
+      missing: definition.encoding.missing
+    });
+  }
+  const operation = {
+    x: "encodeX",
+    y: "encodeY",
+    theta: "encodeTheta",
+    r: "encodeR"
+  }[definition.channel];
+  return template[operation](repeatEncodingArgs(definition, field));
+}
+
 function deriveRepeatChildren(base, definition, scales, closeInheritedAction) {
   const template = base.semanticSpec.title.text === undefined
     ? base
     : base.removeTitle();
   const independentlyResolved = Object.fromEntries(definition.cells.map(cell => [
     cell.id,
-    template[definition.channel === "x" ? "encodeX" : "encodeY"](
-      repeatEncodingArgs(definition, cell.field)
-    )
+    deriveRepeatedProgram(template, definition, cell.field)
   ]));
   return resolveFacetChildrenScales(
     template,
@@ -338,7 +431,7 @@ function deriveRepeatChildren(base, definition, scales, closeInheritedAction) {
 export const repeatCharts = action(
   {
     op: "repeatCharts",
-    description: "Repeat one direct Cartesian chart across an ordered field list."
+    description: "Repeat one direct chart across an ordered field-role list."
   },
   function (args = {}) {
     validateOptionObject(args, REPEAT_OPTIONS, "repeatCharts");
@@ -349,7 +442,7 @@ export const repeatCharts = action(
     const definition = resolveRepeatDefinition(this, args);
     const requestedScales = {
       ...(args.scales ?? {}),
-      [definition.channel]: args.scales?.[definition.channel] ?? "independent"
+      [definition.policyKey]: args.scales?.[definition.policyKey] ?? "independent"
     };
     const scalePolicies = normalizeFacetScalePolicies(
       this.semanticSpec,
@@ -394,7 +487,7 @@ export const repeatCharts = action(
     };
     return applyCompositionState(
       this._withMaterializationConfig(["facets", definition.id], {
-        headers: DEFAULT_HEADERS
+        headers: createDefaultFacetHeaders()
       }),
       { children: derived.children, compositionSpec },
       compositionSpec.children
@@ -411,6 +504,9 @@ export const facetGrid = action(
     validateOptionObject(args, FACET_GRID_OPTIONS, "facetGrid");
     const guides = normalizeGuides(args.guides);
     const definition = resolveFacetGridDefinition(this.semanticSpec, args);
+    if (definition.family !== "cartesian" && guides.axes === "outer") {
+      throw new Error("Polar and Parallel facets do not support outer axes.");
+    }
     const scalePolicies = normalizeFacetScalePolicies(
       this.semanticSpec,
       args.scales ?? {}
@@ -461,7 +557,7 @@ export const facetGrid = action(
     };
     return applyCompositionState(
       this._withMaterializationConfig(["facets", definition.id], {
-        headers: DEFAULT_HEADERS
+        headers: createDefaultFacetHeaders()
       }),
       { children: derived.children, compositionSpec },
       compositionSpec.children
@@ -486,18 +582,73 @@ export const editFacetHeaders = action(
       allowEmpty: false,
       emptyMessage: "editFacetHeaders requires at least one change."
     });
-    const headers = { ...config.headers, ...args };
-    validatePositiveFinite(headers.fontSize, "Facet header fontSize");
-    validateNonEmptyString(headers.fontFamily, "Facet header fontFamily");
-    validateNonEmptyString(headers.color, "Facet header color");
-    validateNonNegativeFinite(headers.offset, "Facet header offset");
-    if (!(
-      (typeof headers.fontWeight === "string" && headers.fontWeight.length > 0) ||
-      Number.isFinite(headers.fontWeight)
-    )) {
-      throw new TypeError(
-        "Facet header fontWeight must be a non-empty string or number."
-      );
+    const role = args.role ?? "all";
+    if (!["all", "row", "column"].includes(role)) {
+      throw new Error(`Unknown facet header role "${role}".`);
+    }
+    if (role === "all" && Object.hasOwn(args, "side")) {
+      throw new Error("editFacetHeaders side requires an explicit row or column role.");
+    }
+    if (role === "row" && this.compositionSpec.facet.grid === undefined) {
+      throw new Error("editFacetHeaders row role requires a row-column facet grid.");
+    }
+    if (Object.hasOwn(args, "side")) {
+      const sides = role === "row" ? ["left", "right"] : ["top", "bottom"];
+      if (!sides.includes(args.side)) {
+        throw new Error(`editFacetHeaders ${role} side must be ${sides.join(" or ")}.`);
+      }
+    }
+    if (Object.hasOwn(args, "align") &&
+        !["start", "center", "end"].includes(args.align)) {
+      throw new Error("editFacetHeaders align must be start, center, or end.");
+    }
+    if (role === "all" && Object.keys(args).every(key => key === "role")) {
+      throw new Error("editFacetHeaders requires at least one change.");
+    }
+    const current = normalizeFacetHeadersConfig(config.headers);
+    const owner = role === "all" ? "common" : role;
+    const patch = { ...current[owner] };
+    for (const key of HEADER_STYLE_OPTIONS) {
+      if (Object.hasOwn(args, key)) patch[key] = args[key];
+    }
+    if (Object.hasOwn(args, "side")) patch.side = args.side;
+    if (Object.hasOwn(args, "labelMap")) {
+      if (args.labelMap === "auto") delete patch.labelMap;
+      else {
+        patch.labelMap = normalizeDisplayLabelMap(
+          args.labelMap,
+          `editFacetHeaders ${role} labelMap`
+        );
+      }
+    }
+    const headers = {
+      ...current,
+      ...(role === "all" ? {} : { mode: "roles" }),
+      [owner]: patch
+    };
+    for (const headerRole of ["all", "row", "column"]) {
+      const resolved = resolveFacetHeaderConfig(headers, headerRole);
+      validatePositiveFinite(resolved.fontSize, `Facet ${headerRole} header fontSize`);
+      validateNonEmptyString(resolved.fontFamily, `Facet ${headerRole} header fontFamily`);
+      validateNonEmptyString(resolved.color, `Facet ${headerRole} header color`);
+      validateNonNegativeFinite(resolved.offset, `Facet ${headerRole} header offset`);
+      if (!(
+        (typeof resolved.fontWeight === "string" && resolved.fontWeight.length > 0) ||
+        Number.isFinite(resolved.fontWeight)
+      )) {
+        throw new TypeError(
+          `Facet ${headerRole} header fontWeight must be a non-empty string or number.`
+        );
+      }
+      if (!["start", "center", "end"].includes(resolved.align)) {
+        throw new Error(`Facet ${headerRole} header align must be start, center, or end.`);
+      }
+      if (resolved.labelMap !== undefined) {
+        normalizeDisplayLabelMap(
+          resolved.labelMap,
+          `Facet ${headerRole} header labelMap`
+        );
+      }
     }
     return this
       ._withMaterializationConfig(["facets", id], { ...config, headers })
@@ -518,8 +669,8 @@ export const editFacetScales = action(
       emptyMessage: "editFacetScales requires at least one channel policy change."
     });
     for (const channel of Object.keys(args)) {
-      if (!this.semanticSpec.layers.some(
-        layer => layer.encoding?.[channel]?.scale !== undefined
+      if (!collectFacetScaleBindings(this.semanticSpec).some(
+        binding => binding.policyKey === channel
       )) {
         throw new Error(
           `Facet scale channel "${channel}" is not used by an affected layer.`
@@ -554,6 +705,10 @@ export const editFacetGuides = action(
     });
     const current = this.compositionSpec.facet;
     const guides = normalizeGuides({ ...current.guides, ...args });
+    const family = resolveFacetFamily(this.semanticSpec).family;
+    if (family !== "cartesian" && guides.axes === "outer") {
+      throw new Error("Polar and Parallel facets do not support outer axes.");
+    }
     if (current.repeat !== undefined && guides.axes === "outer") {
       throw new Error("repeatCharts does not promote axes across different repeated fields.");
     }
@@ -574,11 +729,33 @@ function adoptUnitState(program, actionOwner) {
   if (program.actionStack.length !== 0) {
     throw new Error("editFacetSource program has an unfinished action stack.");
   }
+  const seedId = actionOwner.compositionSpec.children.find(id =>
+    actionOwner.children[id]?.semanticSpec.layers.length > 0
+  ) ?? actionOwner.compositionSpec.children[0];
+  const retained = actionOwner.children[seedId]?.materializationConfigs ?? {};
+  const {
+    canvas: _retainedCanvas,
+    theme: _retainedTheme,
+    facets: _retainedFacets,
+    ...retainedRecipe
+  } = retained;
+  void _retainedCanvas;
+  void _retainedTheme;
+  void _retainedFacets;
   return new actionOwner.constructor({
     semanticSpec: program.semanticSpec,
     graphicSpec: program.graphicSpec,
     resolvedScales: program.resolvedScales,
-    materializationConfigs: program.materializationConfigs,
+    materializationConfigs: freezeOwned({
+      ...program.materializationConfigs,
+      ...retainedRecipe,
+      ...(program.materializationConfigs.canvas === undefined
+        ? {}
+        : { canvas: program.materializationConfigs.canvas }),
+      ...(program.materializationConfigs.theme === undefined
+        ? {}
+        : { theme: program.materializationConfigs.theme })
+    }),
     children: {},
     context: program.context,
     trace: actionOwner.trace,
@@ -653,7 +830,10 @@ export const editFacetSource = action(
         ...this.semanticSpec.title
       });
     }
-    return revised;
+    return replayCompositionThemeState(
+      revised,
+      this.materializationConfigs.theme
+    );
   }
 );