ggaction 0.0.2 → 0.0.4

package/src/actions/errorBars/index.js

@@ -1,7 +1,10 @@
 import { createErrorBarCap } from "./components.js";
 import { createErrorBar } from "./create.js";
+import { editErrorBar, rematerializeErrorBar } from "./edit.js";
 
 export function registerErrorBarActions(ProgramClass) {
   ProgramClass.prototype.createErrorBarCap = createErrorBarCap;
   ProgramClass.prototype.createErrorBar = createErrorBar;
+  ProgramClass.prototype.editErrorBar = editErrorBar;
+  ProgramClass.prototype.rematerializeErrorBar = rematerializeErrorBar;
 }

package/src/actions/errorBars/options.js

@@ -0,0 +1,52 @@
+import {
+  validateKeys,
+  validatePositiveFinite
+} from "../../core/validation.js";
+import {
+  normalizeStrokeDashPattern,
+  validateOpacityValue
+} from "../../grammar/scales/index.js";
+import {
+  validateRuleStroke,
+  validateRuleStrokeWidth
+} from "../../grammar/ruleAppearance.js";
+
+export const ERROR_BAR_EDIT_OPTIONS = Object.freeze([
+  "target", "caps", "capSize", "stroke", "strokeWidth",
+  "strokeDash", "opacity"
+]);
+
+export function resolveErrorBarAppearance(args, {
+  defaults,
+  operation
+}) {
+  validateKeys(args, ERROR_BAR_EDIT_OPTIONS, operation);
+  const caps = args.caps ?? defaults.caps;
+  if (typeof caps !== "boolean") {
+    throw new TypeError(`${operation} caps must be a boolean.`);
+  }
+  const capSize = args.capSize ?? defaults.capSize;
+  validatePositiveFinite(capSize, `${operation} capSize`);
+  const stroke = validateRuleStroke(
+    args.stroke ?? defaults.stroke,
+    `${operation} stroke`
+  );
+  const strokeWidth = validateRuleStrokeWidth(
+    args.strokeWidth ?? defaults.strokeWidth,
+    `${operation} strokeWidth`
+  );
+  const strokeDash = args.strokeDash ?? defaults.strokeDash;
+  normalizeStrokeDashPattern(strokeDash);
+  const opacity = validateOpacityValue(
+    args.opacity ?? defaults.opacity,
+    `${operation} opacity`
+  );
+  return {
+    caps,
+    capSize,
+    stroke,
+    strokeWidth,
+    strokeDash,
+    opacity
+  };
+}

package/src/actions/facets/actions.js

@@ -0,0 +1,162 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateOptionObject,
+  validatePositiveFinite
+} from "../../core/validation.js";
+import { resolveFacetDefinition } from "../../grammar/facets/index.js";
+import { normalizeFacetScalePolicies } from
+  "../../grammar/facets/scales.js";
+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 { rebindLayerData, replayDerivedData } from "./replay.js";
+import { composeFacetGuides } from "./guides.js";
+
+const FACET_OPTIONS = Object.freeze([
+  "id", "field", "data", "columns", "gap", "align", "padding", "scales",
+  "guides"
+]);
+const GUIDE_OPTIONS = Object.freeze(["axes", "legend"]);
+const HEADER_OPTIONS = Object.freeze([
+  "fontSize", "fontFamily", "fontWeight", "color", "offset"
+]);
+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 };
+  validateOptionObject(guides, GUIDE_OPTIONS, "facet.guides");
+  const axes = guides.axes ?? "each";
+  if (!["each", "outer"].includes(axes)) {
+    throw new Error('facet guides.axes must be "each" or "outer".');
+  }
+  const legend = guides.legend ?? false;
+  if (legend !== false && legend !== "shared") {
+    throw new Error('facet guides.legend must be false or "shared".');
+  }
+  return { axes, legend };
+}
+
+function normalizeHeaderPatch(args, previous) {
+  validateOptionObject(args, HEADER_OPTIONS, "editFacetHeaders", {
+    allowEmpty: false,
+    emptyMessage: "editFacetHeaders requires at least one change."
+  });
+  const next = { ...previous, ...args };
+  validatePositiveFinite(next.fontSize, "Facet header fontSize");
+  validateNonEmptyString(next.fontFamily, "Facet header fontFamily");
+  validateNonEmptyString(next.color, "Facet header color");
+  validateNonNegativeFinite(next.offset, "Facet header offset");
+  if (!(
+    (typeof next.fontWeight === "string" && next.fontWeight.length > 0) ||
+    Number.isFinite(next.fontWeight)
+  )) {
+    throw new TypeError("Facet header fontWeight must be a non-empty string or number.");
+  }
+  return next;
+}
+
+function requireFacetProgram(program, operation) {
+  program._assertCompositionProgram(operation);
+  if (program.compositionSpec.type !== "facet") {
+    throw new Error(`${operation} requires a facet composition.`);
+  }
+}
+
+export const facet = action(
+  {
+    op: "facet",
+    description: "Repeat one direct-source chart by field value."
+  },
+  function (args = {}) {
+    validateOptionObject(args, FACET_OPTIONS, "facet");
+    const guides = normalizeGuides(args.guides);
+    const definition = resolveFacetDefinition(this.semanticSpec, args);
+    const scalePolicies = normalizeFacetScalePolicies(
+      this.semanticSpec,
+      args.scales ?? {}
+    );
+    const derived = deriveFacetChildren(this, definition, {
+      closeInheritedAction: true,
+      stripTitle: true,
+      scales: args.scales ?? {}
+    });
+    const preflight = resolveFacetLayout({
+      children: definition.cells.map(cell => ({
+        ...compositionChildDescriptor(cell.id, derived.children[cell.id]),
+        value: cell.value
+      })),
+      ...(Object.hasOwn(args, "columns") ? { columns: args.columns } : {}),
+      ...(Object.hasOwn(args, "gap") ? { gap: args.gap } : {}),
+      ...(Object.hasOwn(args, "align") ? { align: args.align } : {}),
+      ...(Object.hasOwn(args, "padding") ? { padding: args.padding } : {}),
+      sharedLegend: guides.legend === "shared"
+    });
+    const compositionSpec = {
+      id: definition.id,
+      type: "facet",
+      children: definition.cells.map(cell => cell.id),
+      columns: preflight.columns,
+      gap: preflight.gap,
+      align: preflight.align,
+      padding: preflight.padding,
+      facet: {
+        data: definition.data,
+        field: definition.field,
+        values: definition.values,
+        scales: scalePolicies.channels,
+        guides
+      }
+    };
+    let next = this
+      ._withCompositionState({
+        children: derived.children,
+        compositionSpec
+      })
+      ._withMaterializationConfig(["facets", definition.id], {
+        headers: DEFAULT_HEADERS
+      });
+    for (const id of compositionSpec.children) {
+      next = next.useProgram({ id });
+    }
+    return next.materializeComposition();
+  }
+);
+
+export const editFacetHeaders = action(
+  {
+    op: "editFacetHeaders",
+    description: "Edit parent-owned facet header appearance.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    requireFacetProgram(this, "editFacetHeaders");
+    const id = this.compositionSpec.id;
+    const config = this.materializationConfigs.facets?.[id];
+    if (!isPlainObject(config?.headers)) {
+      throw new Error(`Facet "${id}" requires header configuration.`);
+    }
+    const headers = normalizeHeaderPatch(args, config.headers);
+    return this
+      ._withMaterializationConfig(["facets", id], { ...config, headers })
+      .materializeComposition();
+  }
+);
+
+export function registerFacetActions(ProgramClass) {
+  ProgramClass.prototype.replayDerivedData = replayDerivedData;
+  ProgramClass.prototype.rebindLayerData = rebindLayerData;
+  ProgramClass.prototype.composeFacetGuides = composeFacetGuides;
+  ProgramClass.prototype.facet = facet;
+  ProgramClass.prototype.editFacetHeaders = editFacetHeaders;
+}

package/src/actions/facets/derive.js

@@ -0,0 +1,200 @@
+import { freezeOwned } from "../../core/immutable.js";
+import { resolveHistogramBins } from "../../grammar/histogram.js";
+import { readQuantitativeField } from "../../grammar/scales/index.js";
+import { BAR_GRAINS, resolveBarGrain } from "../../grammar/bars/policy.js";
+import { resolveFacetScaleDomains } from "../../grammar/facets/scales.js";
+import {
+  applyMaterializationPlan,
+  planScaleGuideRematerialization
+} from "../../materialization/dependencies.js";
+import { getMarkMaterializationStep } from "../../materialization/marks/index.js";
+import { buildMaterializationPlan } from "../../materialization/planner.js";
+import { requireDataset } from "../../selectors/datasets.js";
+import { requireLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+
+function sharedHistogramBoundaries(program) {
+  const boundaries = new Map();
+  for (const layer of program.semanticSpec.layers) {
+    if (
+      layer.mark?.type !== "bar" ||
+      resolveBarGrain(layer) !== BAR_GRAINS.histogram
+    ) {
+      continue;
+    }
+    const x = layer.encoding.x;
+    const scale = findSemanticScale(program, x.scale);
+    const dataset = requireDataset(program, layer.data);
+    const values = readQuantitativeField(dataset.values, x.field);
+    boundaries.set(layer.id, resolveHistogramBins({
+      values,
+      bin: x.bin,
+      domain: scale.domain,
+      nice: scale.nice ?? true,
+      zero: scale.zero ?? false
+    }).boundaries);
+  }
+  return boundaries;
+}
+
+function applySharedHistogramBoundaries(program, layerId, boundaries) {
+  if (boundaries === undefined) return program;
+  const layer = requireLayer(program, layerId);
+  let next = program;
+  for (const property of ["maxBins", "step"]) {
+    if (Object.hasOwn(layer.encoding.x.bin, property)) {
+      next = next.editSemantic({
+        property: `layer[${layerId}].encoding.x.bin.${property}`,
+        remove: true
+      });
+    }
+  }
+  return next.editSemantic({
+    property: `layer[${layerId}].encoding.x.bin.boundaries`,
+    value: boundaries
+  });
+}
+
+function replayDatasetId(cell, owner) {
+  return `${cell.id}-${owner}-data`;
+}
+
+function cellMaterializationPlan(program) {
+  const scaleIds = [...new Set(program.semanticSpec.layers.flatMap(layer =>
+    Object.values(layer.encoding ?? {})
+      .map(encoding => encoding?.scale)
+      .filter(id => id !== undefined)
+  ))];
+  const scales = scaleIds.map(id => ({
+    op: "rematerializeScale",
+    args: { id, guides: false, marks: false }
+  }));
+  return buildMaterializationPlan({ scales });
+}
+
+function deriveCellProgram(base, definition, cell, histogramBoundaries) {
+  let child = base.filterData({
+    id: cell.data,
+    source: definition.data,
+    field: definition.field,
+    oneOf: [cell.value]
+  });
+  const datasets = new Map([[definition.data, cell.data]]);
+  for (const replay of definition.dependencies.replay) {
+    const source = datasets.get(replay.source);
+    if (source === undefined) {
+      throw new Error(
+        `Facet replay source "${replay.source}" is not available in cell "${cell.id}".`
+      );
+    }
+    const id = replayDatasetId(cell, replay.id);
+    child = child.replayDerivedData({
+      id,
+      source,
+      transform: replay.transform
+    });
+    datasets.set(replay.id, id);
+  }
+  for (const layer of definition.dependencies.layers) {
+    const data = datasets.get(layer.data);
+    if (data === undefined) {
+      throw new Error(
+        `Facet layer "${layer.id}" has no replayed dataset in cell "${cell.id}".`
+      );
+    }
+    child = child.rebindLayerData({ id: layer.id, data });
+    child = applySharedHistogramBoundaries(
+      child,
+      layer.id,
+      histogramBoundaries.get(layer.id)
+    );
+  }
+  return applyMaterializationPlan(child, cellMaterializationPlan(child));
+}
+
+function applyResolvedDomains(program, childId, resolution, baseResolved) {
+  let next = program;
+  for (const [id, scaleResolution] of Object.entries(resolution.scales)) {
+    const current = next.resolvedScales[id];
+    if (current === undefined) {
+      throw new Error(`Facet child "${childId}" is missing resolved scale "${id}".`);
+    }
+    const shared = scaleResolution.policy === "shared"
+      ? baseResolved?.[id]
+      : undefined;
+    next = next._withResolvedScale(id, {
+      ...current,
+      ...shared,
+      domain: scaleResolution.childDomains[childId]
+    });
+  }
+  const marks = next.semanticSpec.layers.flatMap(layer => {
+    const step = getMarkMaterializationStep(next, layer);
+    if (step === undefined) return [];
+    return ["bar", "line", "area"].includes(layer.mark?.type)
+      ? [{ ...step, args: { ...step.args, scales: false } }]
+      : [step];
+  });
+  const guides = Object.keys(resolution.scales).flatMap(id =>
+    planScaleGuideRematerialization(next, id)
+  );
+  return applyMaterializationPlan(
+    next,
+    buildMaterializationPlan({ marks, guides })
+  );
+}
+
+export function deriveFacetChildren(
+  base,
+  definition,
+  {
+    closeInheritedAction = false,
+    stripTitle = false,
+    scales = {}
+  } = {}
+) {
+  const template = stripTitle && base.semanticSpec.title.text !== undefined
+    ? base.removeTitle()
+    : base;
+  const resolutionRequest = scales ?? {};
+  const xPolicy = resolutionRequest.x ?? "shared";
+  const bins = xPolicy === "shared"
+    ? sharedHistogramBoundaries(template)
+    : new Map();
+  const independentlyResolved = Object.fromEntries(definition.cells.map(cell => [
+    cell.id,
+    deriveCellProgram(template, definition, cell, bins)
+  ]));
+  const resolution = resolveFacetScaleDomains(
+    template.semanticSpec,
+    Object.fromEntries(Object.entries(independentlyResolved).map(([id, child]) => [
+      id,
+      child.resolvedScales
+    ])),
+    resolutionRequest,
+    template.resolvedScales
+  );
+  const resolvedChildren = Object.fromEntries(
+    Object.entries(independentlyResolved).map(([id, child]) => [
+      id,
+      applyResolvedDomains(child, id, resolution, template.resolvedScales)
+    ])
+  );
+  const sharedScales = Object.fromEntries(
+    Object.entries(resolution.scales)
+      .filter(([, value]) => value.policy === "shared")
+      .map(([id]) => [id, resolvedChildren[definition.cells[0].id].resolvedScales[id]])
+  );
+  return freezeOwned({
+    children: freezeOwned(Object.fromEntries(
+      Object.entries(resolvedChildren).map(([id, child]) => [
+        id,
+        closeInheritedAction
+          ? child._exitAction()
+          : child
+      ])
+    )),
+    sharedScales: freezeOwned(sharedScales),
+    resolution
+  });
+}

package/src/actions/facets/guides.js

@@ -0,0 +1,16 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+import { applyFacetGuideComposition } from
+  "../../materialization/facetGuides/index.js";
+
+export const composeFacetGuides = action(
+  {
+    op: "composeFacetGuides",
+    description: "Apply outer-axis ownership and promote shared facet legends.",
+    scope: "composition"
+  },
+  function ({ layout, plot } = {}) {
+    validateKeys({ layout, plot }, ["layout", "plot"], "composeFacetGuides");
+    return applyFacetGuideComposition(this, { layout, plot });
+  }
+);

package/src/actions/facets/index.js

@@ -0,0 +1 @@
+export { registerFacetActions } from "./actions.js";

package/src/actions/facets/replay.js

@@ -0,0 +1,69 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { hasDataset } from "../../selectors/datasets.js";
+import { requireLayer } from "../../selectors/layers.js";
+
+const REPLAY_OPTIONS = Object.freeze(["id", "source", "transform"]);
+const REBIND_OPTIONS = Object.freeze(["id", "data"]);
+const MATERIALIZERS = Object.freeze({
+  filter: "materializeFilteredData",
+  regression: "materializeRegressionData",
+  density: "materializeDensityData",
+  interval: "materializeIntervalData",
+  boxSummary: "materializeBoxSummaryData",
+  boxOutlier: "materializeBoxOutlierData"
+});
+
+function requestedTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("replayDerivedData transform must be a plain object.");
+  }
+  const materialize = MATERIALIZERS[transform.type];
+  if (materialize === undefined) {
+    throw new Error(
+      `replayDerivedData does not support transform "${transform.type ?? "unknown"}".`
+    );
+  }
+  if (transform.type !== "density") return { transform, materialize };
+  const { resolved: _resolved, ...requested } = transform;
+  return { transform: requested, materialize };
+}
+
+export const replayDerivedData = action(
+  {
+    op: "replayDerivedData",
+    description: "Replay one stored derived-data transform for a facet cell."
+  },
+  function (args = {}) {
+    validateKeys(args, REPLAY_OPTIONS, "replayDerivedData");
+    const id = validateUserId(args.id, "Facet replay dataset id");
+    const source = validateUserId(args.source, "Facet replay source id");
+    const resolved = requestedTransform(args.transform);
+    return this
+      .createDerivedData({ id, source, transform: [resolved.transform] })
+      [resolved.materialize]({ id });
+  }
+);
+
+export const rebindLayerData = action(
+  {
+    op: "rebindLayerData",
+    description: "Rebind one facet-cell layer to its replayed dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, REBIND_OPTIONS, "rebindLayerData");
+    const id = validateUserId(args.id, "Facet layer id");
+    const data = validateUserId(args.data, "Facet layer dataset id");
+    requireLayer(this, id);
+    if (!hasDataset(this, data)) {
+      throw new Error(`Facet layer dataset "${data}" does not exist.`);
+    }
+    return this.editSemantic({
+      property: `layer[${id}].data`,
+      value: data
+    });
+  }
+);
+

package/src/actions/guides/applicability.js

@@ -0,0 +1,113 @@
+import {
+  BAR_ORIENTATIONS,
+  resolveBarOrientation
+} from "../../grammar/bars/policy.js";
+import {
+  CARTESIAN_POSITION_CHANNELS,
+  POLAR_POSITION_CHANNELS
+} from "../../core/vocabulary.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+
+function hasEncoding(program, channel, { scaled = false, grid = false } = {}) {
+  return program.semanticSpec.layers.some(layer => {
+    const encoding = layer.encoding?.[channel];
+    if (!scaled && !grid) return encoding !== undefined;
+    if (encoding?.scale === undefined) return false;
+    if (!grid || POLAR_POSITION_CHANNELS.includes(channel)) return true;
+    const type = findSemanticScale(program, encoding.scale)?.type;
+    return type !== undefined && !["ordinal", "band", "point"].includes(type);
+  });
+}
+
+function positionalApplicability(program, channels) {
+  return Object.freeze(Object.fromEntries(
+    channels.map(channel => [
+      channel,
+      Object.freeze({
+        axis: hasEncoding(program, channel),
+        grid: hasEncoding(program, channel, { grid: true })
+      })
+    ])
+  ));
+}
+
+export function hasInferableLegend(program) {
+  return program.semanticSpec.layers.some(layer =>
+    (layer.mark?.type === "point" &&
+      layer.encoding?.opacity?.scale !== undefined) ||
+    (layer.mark?.type === "point" &&
+      layer.encoding?.size?.scale !== undefined) ||
+    (layer.mark?.type === "point" &&
+      layer.encoding?.color?.scale !== undefined &&
+      (layer.encoding?.shape?.scale !== undefined ||
+        ["sequential", "quantize", "quantile", "threshold"].includes(
+          findSemanticScale(program, layer.encoding.color.scale)?.type
+        ))) ||
+    (layer.mark?.type === "line" &&
+      ["color", "strokeDash"].some(
+        channel => layer.encoding?.[channel]?.scale !== undefined
+      )) ||
+    (["bar", "area", "arc", "rect"].includes(layer.mark?.type) &&
+      layer.encoding?.color?.scale !== undefined)
+  );
+}
+
+export function resolveGuideApplicability(program) {
+  const cartesian = positionalApplicability(
+    program,
+    CARTESIAN_POSITION_CHANNELS
+  );
+  const polar = positionalApplicability(program, POLAR_POSITION_CHANNELS);
+  return Object.freeze({
+    axes: Object.freeze({
+      cartesian: CARTESIAN_POSITION_CHANNELS.some(
+        channel => cartesian[channel].axis
+      ),
+      polar: POLAR_POSITION_CHANNELS.some(channel => polar[channel].axis)
+    }),
+    grid: Object.freeze({
+      cartesian: CARTESIAN_POSITION_CHANNELS.some(
+        channel => cartesian[channel].grid
+      ),
+      polar: POLAR_POSITION_CHANNELS.some(channel => polar[channel].grid),
+      directions: Object.freeze({
+        horizontal: cartesian.y.grid,
+        vertical: cartesian.x.grid,
+        theta: polar.theta.grid,
+        radial: polar.radius.grid
+      })
+    }),
+    legend: hasInferableLegend(program)
+  });
+}
+
+export function resolveAutomaticGridOptions(program) {
+  const applicability = resolveGuideApplicability(program);
+  const directions = applicability.grid.directions;
+  if (applicability.grid.polar && !applicability.grid.cartesian) {
+    return Object.freeze({
+      ...(directions.theta ? { theta: {} } : {}),
+      ...(directions.radial ? { radial: {} } : {})
+    });
+  }
+
+  const barOrientations = program.semanticSpec.layers
+    .map(resolveBarOrientation)
+    .filter(Boolean);
+  const positionedLayers = program.semanticSpec.layers.filter(
+    layer => layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
+  );
+  const horizontalQuantitative = positionedLayers.length > 0 &&
+    positionedLayers.every(layer =>
+      layer.encoding.x.fieldType === "quantitative" &&
+      ["nominal", "ordinal", "temporal"].includes(layer.encoding.y.fieldType)
+    );
+  if (
+    horizontalQuantitative ||
+    (barOrientations.length > 0 &&
+      barOrientations.every(value => value === BAR_ORIENTATIONS.horizontal))
+  ) {
+    return Object.freeze({ horizontal: false, vertical: {} });
+  }
+  return Object.freeze({ horizontal: {}, vertical: false });
+}