ggaction 0.0.1

package/src/actions/guides/legends/categorical/recipes.js

@@ -0,0 +1,120 @@
+import { isPlainObject } from "../../../../core/immutable.js";
+import {
+  nonEmptyString,
+  nonNegative,
+  positive,
+  validateKeys
+} from "./validation.js";
+
+const LAYER_OPTIONS = Object.freeze({
+  line: Object.freeze(["type", "length", "lineWidth"]),
+  point: Object.freeze([
+    "type",
+    "shape",
+    "size",
+    "fill",
+    "stroke",
+    "strokeWidth"
+  ]),
+  swatch: Object.freeze([
+    "type",
+    "width",
+    "height",
+    "stroke",
+    "strokeWidth"
+  ])
+});
+
+function defaultRecipe(kind) {
+  return kind === "series"
+    ? { layers: [{ type: "line", length: 32, lineWidth: 2 }] }
+    : {
+        layers: [{
+          type: "swatch",
+          width: 14,
+          height: 12,
+          stroke: "white",
+          strokeWidth: 0.5
+        }]
+      };
+}
+
+function normalizeLayer(layer) {
+  if (!isPlainObject(layer) || !Object.hasOwn(LAYER_OPTIONS, layer.type)) {
+    throw new Error("Legend symbol layer type must be line, point, or swatch.");
+  }
+  validateKeys(
+    layer,
+    LAYER_OPTIONS[layer.type],
+    `createLegend.symbol.${layer.type}`
+  );
+  if (layer.type === "line") {
+    const normalized = { length: 32, lineWidth: 2, ...layer };
+    positive(normalized.length, "Legend line symbol length");
+    nonNegative(normalized.lineWidth, "Legend line symbol lineWidth");
+    return normalized;
+  }
+  if (layer.type === "point") {
+    const normalized = {
+      shape: "circle",
+      size: 5,
+      stroke: "white",
+      strokeWidth: 0,
+      ...layer
+    };
+    if (normalized.shape !== "circle") {
+      throw new Error(`Unsupported legend point shape "${normalized.shape}".`);
+    }
+    positive(normalized.size, "Legend point symbol size");
+    nonEmptyString(normalized.stroke, "Legend point symbol stroke");
+    nonNegative(normalized.strokeWidth, "Legend point symbol strokeWidth");
+    if (normalized.fill !== undefined) {
+      nonEmptyString(normalized.fill, "Legend point symbol fill");
+    }
+    return normalized;
+  }
+  const normalized = {
+    width: 14,
+    height: 12,
+    stroke: "white",
+    strokeWidth: 0.5,
+    ...layer
+  };
+  positive(normalized.width, "Legend swatch width");
+  positive(normalized.height, "Legend swatch height");
+  nonEmptyString(normalized.stroke, "Legend swatch stroke");
+  nonNegative(normalized.strokeWidth, "Legend swatch strokeWidth");
+  return normalized;
+}
+
+export function normalizeRecipe(symbol, kind) {
+  if (symbol === undefined || symbol === "auto") return defaultRecipe(kind);
+  if (!isPlainObject(symbol)) {
+    throw new TypeError('createLegend.symbol must be "auto" or a plain object.');
+  }
+
+  let layers;
+  if (Object.hasOwn(symbol, "layers")) {
+    validateKeys(symbol, ["layers"], "createLegend.symbol");
+    if (!Array.isArray(symbol.layers) || symbol.layers.length === 0) {
+      throw new TypeError("Legend symbol layers must be a non-empty array.");
+    }
+    layers = symbol.layers.map(normalizeLayer);
+  } else if (kind === "series") {
+    validateKeys(symbol, ["length", "lineWidth"], "createLegend.symbol");
+    layers = [normalizeLayer({ type: "line", ...symbol })];
+  } else {
+    validateKeys(
+      symbol,
+      ["width", "height", "stroke", "strokeWidth"],
+      "createLegend.symbol"
+    );
+    layers = [normalizeLayer({ type: "swatch", ...symbol })];
+  }
+
+  const types = layers.map(layer => layer.type);
+  if (new Set(types).size !== types.length) {
+    throw new Error("Legend symbol recipe supports at most one layer per type.");
+  }
+  return { layers };
+}

package/src/actions/guides/legends/categorical/resolve.js

@@ -0,0 +1,131 @@
+import { validateUserId } from "../../../../core/identifiers.js";
+import { sameOrderedValues } from "../../../../core/validation.js";
+import { CHANNELS } from "./options.js";
+import { nonEmptyString } from "./validation.js";
+import { findLayer } from "../../../../selectors/layers.js";
+import { findSemanticScale } from "../../../../selectors/scales.js";
+
+function isCategoricalTarget(layer) {
+  if (["line", "point"].includes(layer?.mark?.type)) {
+    return CHANNELS.some(
+      channel => layer.encoding?.[channel]?.scale !== undefined
+    );
+  }
+  return ["bar", "area"].includes(layer?.mark?.type) &&
+    layer.encoding?.color?.scale !== undefined;
+}
+
+export function resolveTarget(program, requested) {
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Legend target id");
+    const layer = findLayer(program, id);
+    if (!isCategoricalTarget(layer)) {
+      throw new Error(`Unknown categorical legend target "${id}".`);
+    }
+    return layer;
+  }
+
+  const current = findLayer(program, program.context.currentMark);
+  if (isCategoricalTarget(current)) return current;
+  const candidates = program.semanticSpec.layers.filter(isCategoricalTarget);
+  if (candidates.length !== 1) {
+    throw new Error(
+      "createLegend requires target when the categorical mark is ambiguous."
+    );
+  }
+  return candidates[0];
+}
+
+export const sameValues = sameOrderedValues;
+
+export function resolveLegendKind(layer, requestedChannels) {
+  if (["bar", "area"].includes(layer.mark.type)) return "color";
+  if (
+    layer.mark.type === "point" &&
+    sameValues(requestedChannels, ["color"])
+  ) {
+    return "color";
+  }
+  return "series";
+}
+
+function resolveOrdinalScales(program, scaleIds) {
+  const scales = scaleIds.map(id => {
+    const semantic = findSemanticScale(program, id);
+    const concrete = program.resolvedScales[id];
+    if (semantic?.type !== "ordinal" || concrete?.type !== "ordinal") {
+      throw new Error(`Legend requires resolved ordinal scale "${id}".`);
+    }
+    if (!Array.isArray(concrete.domain) || concrete.domain.length === 0) {
+      throw new Error(`Legend scale "${id}" requires a non-empty domain.`);
+    }
+    return concrete;
+  });
+  if (scales.slice(1).some(scale => !sameValues(scale.domain, scales[0].domain))) {
+    throw new Error("Combined legend scales must have identical ordered domains.");
+  }
+  return { scales, domain: scales[0].domain };
+}
+
+export function resolveDefinition(program, layer, requestedChannels, requestedTitle) {
+  const kind = resolveLegendKind(layer, requestedChannels);
+  const channels = requestedChannels ?? (kind === "color"
+    ? ["color"]
+    : CHANNELS.filter(
+        channel => layer.encoding?.[channel]?.scale !== undefined
+      ));
+  if (
+    !Array.isArray(channels) ||
+    channels.length === 0 ||
+    !channels.every(channel => CHANNELS.includes(channel)) ||
+    new Set(channels).size !== channels.length
+  ) {
+    throw new Error(
+      "Legend channels must be a non-empty unique color/strokeDash/shape array."
+    );
+  }
+  if (kind === "color" && !sameValues(channels, ["color"])) {
+    throw new Error("Color legends currently support only the color channel.");
+  }
+
+  const encodings = channels.map(channel => {
+    const encoding = layer.encoding?.[channel];
+    if (encoding?.scale === undefined) {
+      throw new Error(`Legend target does not encode channel "${channel}".`);
+    }
+    return { channel, encoding };
+  });
+  const fields = new Set(encodings.map(item => item.encoding.field));
+  if (fields.size !== 1) {
+    throw new Error("Combined legend channels must encode the same field.");
+  }
+  const scales = encodings.map(item => item.encoding.scale);
+  const resolved = resolveOrdinalScales(program, scales);
+  const field = [...fields][0];
+  return {
+    kind,
+    channels,
+    scales,
+    field,
+    title: nonEmptyString(requestedTitle ?? field, "Legend title"),
+    domain: resolved.domain
+  };
+}
+
+export function resolveCurrentDefinition(program, config) {
+  const layer = findLayer(program, config.target);
+  if (layer === undefined) {
+    throw new Error(`Unknown categorical legend target "${config.target}".`);
+  }
+  const guide = program.semanticSpec.guides.legend?.[config.kind];
+  if (guide === undefined) {
+    throw new Error("Legend rematerialization requires semantic guide state.");
+  }
+  const channels = config.kind === "series" ? guide.channels : ["color"];
+  return resolveDefinition(
+    program,
+    layer,
+    channels,
+    config.inferredTitle === true ? undefined : guide.title
+  );
+}

package/src/actions/guides/legends/categorical/symbols.js

@@ -0,0 +1,280 @@
+import { action } from "../../../../core/action.js";
+import {
+  activeConfig,
+  graphic,
+  layerFor,
+  noOptions,
+  resolveAppearance,
+  resolveLayout,
+  symbolGraphic,
+  symbolWidth
+} from "./layout.js";
+import { resolveLegendGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+import { createPointShapeGraphic } from "../../../../grammar/pointShapes.js";
+import { resolveStoredSelection } from "../../../../materialization/selection/state.js";
+
+function exactLegendSelection(program, config, highlight) {
+  if (highlight.target !== config.target) return undefined;
+  const resolved = resolveStoredSelection(program, highlight.selection);
+  const selected = new Set(resolved.keys);
+  const groups = config.domain.map(value =>
+    resolved.items.filter(item => item.fields?.[config.field] === value)
+  );
+  if (
+    groups.some(group => group.length === 0) ||
+    resolved.items.some(item => !config.domain.includes(item.fields?.[config.field]))
+  ) return undefined;
+  const states = groups.map(group => {
+    const count = group.filter(item => selected.has(item.key)).length;
+    return count === 0 ? false : count === group.length ? true : undefined;
+  });
+  return states.includes(undefined) ? undefined : states;
+}
+
+function legendLayerStyle(layer, style) {
+  if (layer.type === "line") {
+    return Object.fromEntries(
+      ["stroke", "strokeWidth", "strokeDash", "opacity"]
+        .flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
+    );
+  }
+  if (layer.type === "swatch") {
+    return Object.fromEntries(
+      ["fill", "stroke", "strokeWidth", "opacity"]
+        .flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
+    );
+  }
+  return Object.fromEntries(
+    ["fill", "stroke", "strokeWidth", "opacity"]
+      .flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
+  );
+}
+
+function makeEditSymbol(type) {
+  const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[type];
+  const op = `editLegendSymbol${suffix}`;
+  return action(
+    { op, description: `Rematerialize categorical legend ${type} symbols.` },
+    function (args = {}) {
+      noOptions(args, op);
+      const { config } = activeConfig(this);
+      const layer = layerFor(config, type);
+      const id = symbolGraphic(config, type);
+      const dynamicPoint = type === "point" && config.channels.includes("shape");
+      const expected = dynamicPoint
+        ? "collection"
+        : { line: "line", point: "circle", swatch: "rect" }[type];
+      if (this.graphicSpec.objects[id]?.type !== expected) {
+        throw new Error(`${op} requires existing ${type} symbols.`);
+      }
+      const layout = resolveLayout(this, config);
+      const appearance = resolveAppearance(this, config);
+      let next = this;
+      if (!dynamicPoint) {
+        next = next.editGraphics({
+          target: id,
+          property: "length",
+          value: config.domain.length
+        });
+      }
+      if (type === "line") {
+        const x1 = layout.symbolX.map(
+          value => value + (symbolWidth(config) - layer.length) / 2
+        );
+        return next
+          .editGraphics({ target: id, property: "x1", value: x1 })
+          .editGraphics({ target: id, property: "y1", value: layout.itemY })
+          .editGraphics({
+            target: id,
+            property: "x2",
+            value: x1.map(value => value + layer.length)
+          })
+          .editGraphics({ target: id, property: "y2", value: layout.itemY })
+          .editGraphics({ target: id, property: "stroke", value: appearance.colors })
+          .editGraphics({ target: id, property: "strokeWidth", value: layer.lineWidth })
+          .editGraphics({ target: id, property: "strokeDash", value: appearance.dashes });
+      }
+      if (type === "point") {
+        const x = layout.symbolX.map(value => value + symbolWidth(config) / 2);
+        if (dynamicPoint) {
+          const items = config.domain.map((_, index) => {
+            const fill = layer.fill ?? appearance.colors[index];
+            return createPointShapeGraphic({
+              shape: appearance.shapes[index],
+              x: x[index],
+              y: layout.itemY[index],
+              area: Math.PI * layer.size ** 2,
+              fill,
+              stroke: layer.stroke,
+              strokeWidth: layer.strokeWidth
+            });
+          });
+          return next.editGraphics({
+            target: id,
+            property: "items",
+            value: items
+          });
+        }
+        return next
+          .editGraphics({ target: id, property: "x", value: x })
+          .editGraphics({ target: id, property: "y", value: layout.itemY })
+          .editGraphics({ target: id, property: "radius", value: layer.size })
+          .editGraphics({
+            target: id,
+            property: "fill",
+            value: layer.fill ?? appearance.colors
+          })
+          .editGraphics({ target: id, property: "stroke", value: layer.stroke })
+          .editGraphics({ target: id, property: "strokeWidth", value: layer.strokeWidth });
+      }
+      const x = layout.symbolX.map(
+        value => value + (symbolWidth(config) - layer.width) / 2
+      );
+      return next
+        .editGraphics({ target: id, property: "x", value: x })
+        .editGraphics({
+          target: id,
+          property: "y",
+          value: layout.itemY.map(value => value - layer.height / 2)
+        })
+        .editGraphics({ target: id, property: "width", value: layer.width })
+        .editGraphics({ target: id, property: "height", value: layer.height })
+        .editGraphics({ target: id, property: "fill", value: appearance.colors })
+        .editGraphics({ target: id, property: "stroke", value: layer.stroke })
+        .editGraphics({ target: id, property: "strokeWidth", value: layer.strokeWidth });
+    }
+  );
+}
+
+function makeCreateSymbol(type, edit) {
+  const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[type];
+  const op = `createLegendSymbol${suffix}`;
+  return action(
+    { op, description: `Create categorical legend ${type} symbols.` },
+    function (args = {}) {
+      noOptions(args, op);
+      const { config } = activeConfig(this);
+      layerFor(config, type);
+      const id = symbolGraphic(config, type);
+      if (this.graphicSpec.objects[id] !== undefined) {
+        throw new Error(`${op} requires missing ${type} symbols.`);
+      }
+      const graphicType = type === "point" && config.channels.includes("shape")
+        ? "collection"
+        : { line: "line", point: "circle", swatch: "rect" }[type];
+      return this
+        .createGraphics({
+          id,
+          type: graphicType,
+          ...resolveLegendGraphicPlacement(this),
+          ...(this.graphicSpec.objects[graphic(config, "Labels")] === undefined
+            ? {}
+            : { before: graphic(config, "Labels") }),
+          ...(graphicType === "collection"
+            ? {}
+            : { length: config.domain.length })
+        })
+        [edit]();
+    }
+  );
+}
+
+export const editLegendSymbolLines = makeEditSymbol("line");
+export const editLegendSymbolPoints = makeEditSymbol("point");
+export const editLegendSymbolSwatches = makeEditSymbol("swatch");
+export const createLegendSymbolLines = makeCreateSymbol(
+  "line",
+  "editLegendSymbolLines"
+);
+export const createLegendSymbolPoints = makeCreateSymbol(
+  "point",
+  "editLegendSymbolPoints"
+);
+export const createLegendSymbolSwatches = makeCreateSymbol(
+  "swatch",
+  "editLegendSymbolSwatches"
+);
+
+export const createLegendSymbols = action(
+  { op: "createLegendSymbols", description: "Create layered legend symbols." },
+  function (args = {}) {
+    noOptions(args, "createLegendSymbols");
+    const { config } = activeConfig(this);
+    let next = this;
+    for (const layer of config.symbol.layers) {
+      const operation = {
+        line: "createLegendSymbolLines",
+        point: "createLegendSymbolPoints",
+        swatch: "createLegendSymbolSwatches"
+      }[layer.type];
+      next = next[operation]();
+    }
+    return next;
+  }
+);
+
+export const editLegendSymbols = action(
+  { op: "editLegendSymbols", description: "Rematerialize layered legend symbols." },
+  function (args = {}) {
+    noOptions(args, "editLegendSymbols");
+    const { config } = activeConfig(this);
+    let next = this;
+    for (const layer of config.symbol.layers) {
+      const operation = {
+        line: "editLegendSymbolLines",
+        point: "editLegendSymbolPoints",
+        swatch: "editLegendSymbolSwatches"
+      }[layer.type];
+      next = next[operation]();
+    }
+    return next;
+  }
+);
+
+export const rematerializeLegendHighlights = action(
+  {
+    op: "rematerializeLegendHighlights",
+    description: "Reflect exact categorical mark highlights in legend symbols."
+  },
+  function (args = {}) {
+    noOptions(args, "rematerializeLegendHighlights");
+    const hasCategorical =
+      this.guideConfigs.legend?.series !== undefined ||
+      this.guideConfigs.legend?.color !== undefined;
+    if (!hasCategorical) return this;
+    const { config } = activeConfig(this);
+    const highlights = Object.values(
+      this.materializationConfigs.highlights ?? {}
+    ).map(highlight => ({
+      highlight,
+      states: exactLegendSelection(this, config, highlight)
+    })).filter(entry => entry.states !== undefined);
+    if (highlights.length === 0) return this;
+
+    let next = this.editLegendSymbols();
+    for (const { highlight, states } of highlights) {
+      for (const layer of config.symbol.layers) {
+        const id = symbolGraphic(config, layer.type);
+        const graphic = next.graphicSpec.objects[id];
+        const selectedStyle = legendLayerStyle(layer, highlight.style);
+        const dimOpacity = highlight.dimOthers === false
+          ? undefined
+          : highlight.dimOthers.opacity;
+        next = next.editGraphics({
+          target: id,
+          property: "items",
+          value: graphic.items.map((child, index) => ({
+            type: child.type ?? graphic.type,
+            properties: states[index]
+              ? { ...child.properties, ...selectedStyle }
+              : dimOpacity === undefined
+                ? child.properties
+                : { ...child.properties, opacity: dimOpacity }
+          }))
+        });
+      }
+    }
+    return next;
+  }
+);

package/src/actions/guides/legends/categorical/validation.js

@@ -0,0 +1,27 @@
+import { isPlainObject } from "../../../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite
+} from "../../../../core/validation.js";
+
+export { validateKeys };
+
+export function validateObject(value, supported, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  validateKeys(value, supported, label);
+}
+
+export const nonEmptyString = validateNonEmptyString;
+export const nonNegative = validateNonNegativeFinite;
+export const positive = validatePositiveFinite;
+
+export function validateFontWeight(value, label) {
+  if (typeof value !== "string" && !Number.isFinite(value)) {
+    throw new TypeError(`${label} must be a string or number.`);
+  }
+  return value;
+}