ggaction 0.0.2 → 0.0.3

package/src/grammar/facets/guides.js

@@ -0,0 +1,257 @@
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
+
+const LEGEND_FAMILIES = Object.freeze({
+  series: "categorical",
+  color: "categorical",
+  gradient: "gradient",
+  interval: "discretized",
+  size: "size",
+  opacity: "opacity"
+});
+
+function requirePlacements(placements) {
+  if (!Array.isArray(placements) || placements.length === 0) {
+    throw new Error("Facet outer axes require occupied cell placements.");
+  }
+  const ids = new Set();
+  const slots = new Set();
+  for (const placement of placements) {
+    if (!isPlainObject(placement) || typeof placement.id !== "string") {
+      throw new TypeError("Facet cell placement requires a string id.");
+    }
+    if (
+      !Number.isInteger(placement.row) || placement.row < 0 ||
+      !Number.isInteger(placement.column) || placement.column < 0
+    ) {
+      throw new RangeError("Facet cell row and column must be non-negative integers.");
+    }
+    if (ids.has(placement.id)) {
+      throw new Error(`Facet cell placement id "${placement.id}" is duplicated.`);
+    }
+    const slot = `${placement.row}:${placement.column}`;
+    if (slots.has(slot)) {
+      throw new Error(`Facet cell slot ${slot} is occupied more than once.`);
+    }
+    ids.add(placement.id);
+    slots.add(slot);
+  }
+  return placements;
+}
+
+function validateBounds(bounds, label) {
+  if (!isPlainObject(bounds)) {
+    throw new TypeError(`${label} must be a plain bounds object.`);
+  }
+  for (const property of ["x", "y", "width", "height"]) {
+    if (!Number.isFinite(bounds[property])) {
+      throw new TypeError(`${label}.${property} must be finite.`);
+    }
+  }
+  if (bounds.width < 0 || bounds.height < 0) {
+    throw new RangeError(`${label} width and height must be non-negative.`);
+  }
+  return bounds;
+}
+
+function translatedBounds(placement, bounds, channel) {
+  if (bounds === undefined) return undefined;
+  validateBounds(bounds, `Facet ${channel} axis bounds for "${placement.id}"`);
+  if (!Number.isFinite(placement.x) || !Number.isFinite(placement.y)) {
+    throw new TypeError(
+      `Facet cell "${placement.id}" requires finite x/y for concrete axis placement.`
+    );
+  }
+  return {
+    x: placement.x + bounds.x,
+    y: placement.y + bounds.y,
+    width: bounds.width,
+    height: bounds.height
+  };
+}
+
+export function resolveFacetOuterAxes({ placements, axisBounds = {} } = {}) {
+  const cells = requirePlacements(placements);
+  if (!isPlainObject(axisBounds)) {
+    throw new TypeError("Facet axisBounds must be a plain object.");
+  }
+  const bottomByColumn = new Map();
+  const leftByRow = new Map();
+  for (const cell of cells) {
+    const bottom = bottomByColumn.get(cell.column);
+    if (bottom === undefined || cell.row > bottom.row) {
+      bottomByColumn.set(cell.column, cell);
+    }
+    const left = leftByRow.get(cell.row);
+    if (left === undefined || cell.column < left.column) {
+      leftByRow.set(cell.row, cell);
+    }
+  }
+  const xOwners = new Set([...bottomByColumn.values()].map(cell => cell.id));
+  const yOwners = new Set([...leftByRow.values()].map(cell => cell.id));
+  return cloneAndFreeze({
+    x: cells.filter(cell => xOwners.has(cell.id)).map(cell => cell.id),
+    y: cells.filter(cell => yOwners.has(cell.id)).map(cell => cell.id),
+    children: Object.fromEntries(cells.map(cell => {
+      const x = xOwners.has(cell.id);
+      const y = yOwners.has(cell.id);
+      const bounds = axisBounds[cell.id] ?? {};
+      return [cell.id, {
+        x,
+        y,
+        bounds: {
+          ...(x && bounds.x !== undefined
+            ? { x: translatedBounds(cell, bounds.x, "x") }
+            : {}),
+          ...(y && bounds.y !== undefined
+            ? { y: translatedBounds(cell, bounds.y, "y") }
+            : {})
+        }
+      }];
+    }))
+  });
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.keys(value).sort().map(key => [key, stableValue(value[key])])
+    );
+  }
+  return value;
+}
+
+function comparableConfig(config) {
+  const { target: _target, ...rest } = config;
+  return stableValue(rest);
+}
+
+function sameValue(left, right) {
+  return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
+}
+
+function requireLegendChildren(children) {
+  if (!Array.isArray(children) || children.length === 0) {
+    throw new Error("Shared facet legend requires at least one child.");
+  }
+  return children.map(child => {
+    if (!isPlainObject(child) || typeof child.id !== "string") {
+      throw new TypeError("Shared facet legend child requires a string id.");
+    }
+    const legends = child.guideConfigs?.legend;
+    if (!isPlainObject(legends) || Object.keys(legends).length === 0) {
+      throw new Error(`Facet child "${child.id}" has no materialized legend config.`);
+    }
+    if (!isPlainObject(child.resolvedScales)) {
+      throw new Error(`Facet child "${child.id}" has no resolved scales.`);
+    }
+    return { ...child, legends };
+  });
+}
+
+function scaleIds(config) {
+  const ids = config.scales ?? (config.scale === undefined ? [] : [config.scale]);
+  if (!Array.isArray(ids) || ids.length === 0 || !ids.every(id =>
+    typeof id === "string" && id.length > 0
+  )) {
+    throw new Error(`Shared ${config.kind} legend requires resolved scale ids.`);
+  }
+  return ids;
+}
+
+export function resolveSharedFacetLegends(children) {
+  const normalized = requireLegendChildren(children);
+  const first = normalized[0];
+  const kinds = Object.keys(first.legends);
+  const entries = kinds.map(kind => {
+    const family = LEGEND_FAMILIES[kind];
+    if (family === undefined) {
+      throw new Error(`Unsupported shared facet legend kind "${kind}".`);
+    }
+    const config = first.legends[kind];
+    if (
+      !isPlainObject(config) ||
+      (config.kind !== undefined && config.kind !== kind)
+    ) {
+      throw new Error(`Facet child "${first.id}" has invalid ${kind} legend config.`);
+    }
+    const scales = scaleIds(config);
+    const resolvedScales = Object.fromEntries(scales.map(id => {
+      const scale = first.resolvedScales[id];
+      if (!isPlainObject(scale)) {
+        throw new Error(`Facet child "${first.id}" is missing legend scale "${id}".`);
+      }
+      return [id, scale];
+    }));
+    for (const child of normalized.slice(1)) {
+      const candidate = child.legends[kind];
+      if (
+        !isPlainObject(candidate) ||
+        !sameValue(comparableConfig(config), comparableConfig(candidate))
+      ) {
+        throw new Error(
+          `Facet child "${child.id}" has an incompatible ${kind} legend config.`
+        );
+      }
+      for (const id of scales) {
+        if (!sameValue(resolvedScales[id], child.resolvedScales[id])) {
+          throw new Error(
+            `Facet child "${child.id}" has an incompatible resolved legend scale "${id}".`
+          );
+        }
+      }
+    }
+    return { kind, family, scales, config, resolvedScales };
+  });
+  for (const child of normalized.slice(1)) {
+    const childKinds = Object.keys(child.legends);
+    if (!sameValue([...kinds].sort(), [...childKinds].sort())) {
+      throw new Error(`Facet child "${child.id}" has incompatible legend kinds.`);
+    }
+  }
+  return cloneAndFreeze({ source: first.id, entries });
+}
+
+export function planFacetGuideOwnership({
+  placements,
+  children,
+  axes = "outer",
+  legend = "shared",
+  sharedLegends
+} = {}) {
+  const cells = requirePlacements(placements);
+  if (!Array.isArray(children) || children.length !== cells.length) {
+    throw new Error("Facet guide ownership requires one child descriptor per placement.");
+  }
+  if (!["each", "outer"].includes(axes)) {
+    throw new Error("Facet axes must be each or outer.");
+  }
+  if (![false, "shared"].includes(legend)) {
+    throw new Error("Facet legend must be false or shared.");
+  }
+  const byId = new Map(children.map(child => [child.id, child]));
+  if (byId.size !== cells.length || cells.some(cell => !byId.has(cell.id))) {
+    throw new Error("Facet guide child ids must match occupied placements exactly.");
+  }
+  const outer = resolveFacetOuterAxes({ placements: cells });
+  if (legend === "shared" && !isPlainObject(sharedLegends)) {
+    throw new Error("Shared facet legend ownership requires a compatibility plan.");
+  }
+  return cloneAndFreeze({
+    children: Object.fromEntries(cells.map(cell => {
+      const descriptor = byId.get(cell.id);
+      const presentAxes = descriptor.axes ?? [];
+      const keepAxes = axes === "each"
+        ? presentAxes
+        : presentAxes.filter(channel => outer.children[cell.id][channel]);
+      return [cell.id, {
+        keepAxes,
+        removeAxes: presentAxes.filter(channel => !keepAxes.includes(channel)),
+        removeLegends: legend === "shared" ? descriptor.legendKinds ?? [] : []
+      }];
+    })),
+    parent: legend === "shared"
+      ? { legends: sharedLegends.entries, promoteFrom: sharedLegends.source }
+      : { legends: [] }
+  });
+}

package/src/grammar/facets/scales.js

@@ -0,0 +1,254 @@
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
+import {
+  FACET_SCALE_CHANNELS,
+  FACET_SCALE_RESOLUTIONS
+} from "../../core/vocabulary.js";
+import { resolveHistogramBins } from "../histogram.js";
+import {
+  hasOrdinalDomain,
+  isDiscretizedColorScaleType,
+  validateCompleteScaleType
+} from "../scales/types.js";
+
+export { FACET_SCALE_CHANNELS } from "../../core/vocabulary.js";
+
+const RESOLUTION_VALUES = new Set(FACET_SCALE_RESOLUTIONS);
+
+function requireScaleDefinitions(semanticSpec) {
+  if (!isPlainObject(semanticSpec)) {
+    throw new TypeError("Facet scale resolution requires a semantic spec.");
+  }
+  if (!Array.isArray(semanticSpec.layers) || semanticSpec.layers.length === 0) {
+    throw new Error("Facet scale resolution requires at least one layer.");
+  }
+  if (!Array.isArray(semanticSpec.scales)) {
+    throw new Error("Facet scale resolution requires semantic scales.");
+  }
+  const scales = new Map();
+  for (const scale of semanticSpec.scales) {
+    if (!isPlainObject(scale) || typeof scale.id !== "string") {
+      throw new TypeError("Facet semantic scales require string ids.");
+    }
+    if (scales.has(scale.id)) {
+      throw new Error(`Facet semantic scale id "${scale.id}" is duplicated.`);
+    }
+    validateCompleteScaleType(scale.type);
+    scales.set(scale.id, scale);
+  }
+  return scales;
+}
+
+function normalizeRequestedPolicies(requested) {
+  if (!isPlainObject(requested)) {
+    throw new TypeError("Facet scales must be a plain object.");
+  }
+  const unknown = Object.keys(requested).find(
+    key => !FACET_SCALE_CHANNELS.includes(key)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown facet scale channel "${unknown}".`);
+  }
+  const normalized = {};
+  for (const channel of FACET_SCALE_CHANNELS) {
+    const policy = requested[channel] ?? "shared";
+    if (!RESOLUTION_VALUES.has(policy)) {
+      throw new Error(
+        `Facet scale channel "${channel}" must be shared or independent.`
+      );
+    }
+    normalized[channel] = policy;
+  }
+  return normalized;
+}
+
+function usedScaleChannels(semanticSpec, scales) {
+  const used = new Map();
+  for (const layer of semanticSpec.layers) {
+    for (const channel of FACET_SCALE_CHANNELS) {
+      const id = layer.encoding?.[channel]?.scale;
+      if (id === undefined) continue;
+      if (!scales.has(id)) {
+        throw new Error(
+          `Facet layer "${layer.id}" references missing scale "${id}".`
+        );
+      }
+      if (!used.has(id)) used.set(id, new Set());
+      used.get(id).add(channel);
+    }
+  }
+  return used;
+}
+
+export function normalizeFacetScalePolicies(semanticSpec, requested = {}) {
+  const scales = requireScaleDefinitions(semanticSpec);
+  const channels = normalizeRequestedPolicies(requested);
+  const used = usedScaleChannels(semanticSpec, scales);
+  for (const channel of Object.keys(requested)) {
+    const applicable = semanticSpec.layers.some(
+      layer => layer.encoding?.[channel]?.scale !== undefined
+    );
+    if (!applicable) {
+      throw new Error(
+        `Facet scale channel "${channel}" is not used by an affected layer.`
+      );
+    }
+  }
+  const scalePolicies = {};
+  for (const [id, channelSet] of used) {
+    const attached = [...channelSet];
+    const policies = [...new Set(attached.map(channel => channels[channel]))];
+    if (policies.length !== 1) {
+      throw new Error(
+        `Facet scale "${id}" has conflicting channel policies for ${attached.join(", ")}.`
+      );
+    }
+    scalePolicies[id] = {
+      policy: policies[0],
+      channels: attached
+    };
+  }
+  return cloneAndFreeze({ channels, scales: scalePolicies });
+}
+
+function requireChildDomains(resolvedByChild, scaleId) {
+  if (!isPlainObject(resolvedByChild) || Object.keys(resolvedByChild).length === 0) {
+    throw new Error("Facet scale domains require at least one resolved child.");
+  }
+  return Object.fromEntries(Object.entries(resolvedByChild).map(([childId, scales]) => {
+    const domain = scales?.[scaleId]?.domain;
+    if (!Array.isArray(domain) || domain.length === 0) {
+      throw new Error(
+        `Facet child "${childId}" is missing resolved domain for scale "${scaleId}".`
+      );
+    }
+    return [childId, domain];
+  }));
+}
+
+function continuousUnion(domains, id) {
+  if (!domains.every(domain =>
+    domain.length === 2 && domain.every(Number.isFinite)
+  )) {
+    throw new TypeError(`Facet shared scale "${id}" requires finite pair domains.`);
+  }
+  return [
+    Math.min(...domains.map(domain => Math.min(...domain))),
+    Math.max(...domains.map(domain => Math.max(...domain)))
+  ];
+}
+
+function stableUnion(domains) {
+  const output = [];
+  for (const domain of domains) {
+    for (const value of domain) {
+      if (!output.some(candidate => Object.is(candidate, value))) output.push(value);
+    }
+  }
+  return output;
+}
+
+function sharedAutoDomain(scale, domains, baseResolved) {
+  if (hasOrdinalDomain(scale.type)) {
+    return Array.isArray(baseResolved?.domain)
+      ? baseResolved.domain
+      : stableUnion(domains);
+  }
+  if (scale.type === "quantile") {
+    const merged = domains.flat();
+    if (!merged.every(Number.isFinite)) {
+      throw new TypeError(
+        `Facet shared quantile scale "${scale.id}" requires finite sample domains.`
+      );
+    }
+    return merged;
+  }
+  if (isDiscretizedColorScaleType(scale.type) && scale.type === "threshold") {
+    throw new Error(`Facet threshold scale "${scale.id}" requires an explicit domain.`);
+  }
+  return continuousUnion(domains, scale.id);
+}
+
+export function resolveFacetScaleDomains(
+  semanticSpec,
+  resolvedByChild,
+  requested = {},
+  baseResolved = undefined
+) {
+  const scales = requireScaleDefinitions(semanticSpec);
+  const normalized = normalizeFacetScalePolicies(semanticSpec, requested);
+  const resolved = {};
+  for (const [id, scalePolicy] of Object.entries(normalized.scales)) {
+    const scale = scales.get(id);
+    const observed = requireChildDomains(resolvedByChild, id);
+    const childIds = Object.keys(observed);
+    const explicit = scale.domain !== "auto";
+    if (scalePolicy.policy === "independent") {
+      resolved[id] = {
+        ...scalePolicy,
+        childDomains: Object.fromEntries(childIds.map(childId => [
+          childId,
+          explicit ? scale.domain : observed[childId]
+        ]))
+      };
+      continue;
+    }
+    const domain = explicit
+      ? scale.domain
+      : sharedAutoDomain(
+          scale,
+          Object.values(observed),
+          baseResolved?.[id]
+        );
+    resolved[id] = {
+      ...scalePolicy,
+      domain,
+      childDomains: Object.fromEntries(childIds.map(childId => [childId, domain]))
+    };
+  }
+  return cloneAndFreeze({
+    channels: normalized.channels,
+    scales: resolved
+  });
+}
+
+export function resolveFacetHistogramBoundaries({
+  policy = "shared",
+  valuesByChild,
+  bin,
+  domain = "auto",
+  nice = true,
+  zero = false
+} = {}) {
+  if (!RESOLUTION_VALUES.has(policy)) {
+    throw new Error("Facet histogram policy must be shared or independent.");
+  }
+  if (!isPlainObject(valuesByChild) || Object.keys(valuesByChild).length === 0) {
+    throw new Error("Facet histogram boundaries require child values.");
+  }
+  const entries = Object.entries(valuesByChild);
+  for (const [id, values] of entries) {
+    if (!Array.isArray(values) || values.length === 0 || !values.every(Number.isFinite)) {
+      throw new TypeError(`Facet histogram child "${id}" requires finite values.`);
+    }
+  }
+  if (policy === "shared") {
+    const boundaries = resolveHistogramBins({
+      values: entries.flatMap(([, values]) => values),
+      bin,
+      domain,
+      nice,
+      zero
+    }).boundaries;
+    return cloneAndFreeze({
+      policy,
+      childBoundaries: Object.fromEntries(entries.map(([id]) => [id, boundaries]))
+    });
+  }
+  return cloneAndFreeze({
+    policy,
+    childBoundaries: Object.fromEntries(entries.map(([id, values]) => [
+      id,
+      resolveHistogramBins({ values, bin, domain, nice, zero }).boundaries
+    ]))
+  });
+}

package/src/grammar/facets.js

@@ -0,0 +1,122 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateUserId } from "../core/identifiers.js";
+import { BAR_GRAINS, resolveBarGrain } from "./bars/policy.js";
+import { planFacetDependencies } from "./facets/dependencies.js";
+import { readNominalField } from "./scales.js";
+
+const SUPPORTED_MARKS = new Set(["point", "line", "area", "bar", "rule"]);
+const SUPPORTED_BAR_GRAINS = new Set([
+  BAR_GRAINS.histogram,
+  BAR_GRAINS.aggregate,
+  BAR_GRAINS.ranged
+]);
+
+function requireFacetField(field) {
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError("facet requires a non-empty field.");
+  }
+  return field;
+}
+
+function requireSupportedLayer(layer) {
+  if (!SUPPORTED_MARKS.has(layer.mark?.type)) {
+    throw new Error(
+      `facet does not support mark "${layer.id}" of type ${layer.mark?.type ?? "incomplete"}.`
+    );
+  }
+  if (
+    layer.mark.type === "bar" &&
+    !SUPPORTED_BAR_GRAINS.has(resolveBarGrain(layer))
+  ) {
+    throw new Error(
+      `facet requires bar mark "${layer.id}" to be a complete histogram, aggregate, or ranged bar.`
+    );
+  }
+  if (
+    layer.encoding?.x?.scale === undefined ||
+    layer.encoding?.y?.scale === undefined
+  ) {
+    throw new Error(
+      `Facet layer "${layer.id}" must be a complete materializable Cartesian mark.`
+    );
+  }
+  if (typeof layer.data !== "string" || layer.data.length === 0) {
+    throw new Error(`Facet layer "${layer.id}" requires a dataset.`);
+  }
+}
+
+function requireSupportedLayers(semanticSpec) {
+  if (!Array.isArray(semanticSpec.layers) || semanticSpec.layers.length === 0) {
+    throw new Error("facet requires at least one materializable layer.");
+  }
+  for (const layer of semanticSpec.layers) requireSupportedLayer(layer);
+}
+
+function requirePartitionDataset(semanticSpec, id) {
+  const dataset = semanticSpec.datasets?.find(candidate => candidate.id === id);
+  if (dataset === undefined) {
+    throw new Error(`Facet dataset "${id}" does not exist.`);
+  }
+  if (!Array.isArray(dataset.values)) {
+    throw new TypeError(`Facet dataset "${id}" requires array values.`);
+  }
+  return dataset;
+}
+
+function uniqueInOrder(values) {
+  return [...new Set(values)];
+}
+
+function resolveValues(observed, requested) {
+  if (requested === undefined) return observed;
+  if (!Array.isArray(requested) || requested.length === 0) {
+    throw new TypeError("facet values must be a non-empty array when provided.");
+  }
+  const normalized = readNominalField(
+    requested.map(value => ({ value })),
+    "value"
+  );
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error("facet values must be unique.");
+  }
+  const missing = normalized.find(value => !observed.includes(value));
+  if (missing !== undefined) {
+    throw new Error(`facet value ${JSON.stringify(missing)} is not present in the source field.`);
+  }
+  return normalized;
+}
+
+export function resolveFacetDefinition(semanticSpec, options = {}) {
+  if (!isPlainObject(semanticSpec)) {
+    throw new TypeError("resolveFacetDefinition requires a semantic spec.");
+  }
+  if (!isPlainObject(options)) {
+    throw new TypeError("Facet options must be a plain object.");
+  }
+  const field = requireFacetField(options.field);
+  const id = validateUserId(options.id ?? "facet", "Facet id");
+  requireSupportedLayers(semanticSpec);
+  const dependencies = planFacetDependencies(semanticSpec, {
+    field,
+    ...(options.data === undefined ? {} : { data: options.data })
+  });
+  const data = dependencies.anchor;
+  const dataset = requirePartitionDataset(semanticSpec, data);
+  const observed = uniqueInOrder(readNominalField(dataset.values, field));
+  if (observed.length === 0) {
+    throw new Error(`facet field "${field}" has no values.`);
+  }
+  const values = resolveValues(observed, options.values);
+  return cloneAndFreeze({
+    id,
+    data,
+    field,
+    values,
+    dependencies,
+    cells: values.map((value, index) => ({
+      id: `${id}-cell-${index + 1}`,
+      data: `${id}-cell-${index + 1}-data`,
+      value
+    }))
+  });
+}