ggaction 0.0.2 → 0.0.4

package/src/grammar/ticks.js

@@ -125,13 +125,7 @@ function pad(value) {
   return String(value).padStart(2, "0");
 }
 
-export function formatTimeTick(value, domain) {
-  if (!Number.isFinite(value)) {
-    throw new TypeError("Time tick value must be a finite timestamp.");
-  }
-
-  const [low, high] = validateTimeDomain(domain);
-  const span = high - low;
+function formatTimePrecision(value, precision) {
   const date = new Date(value);
   const year = String(date.getUTCFullYear()).padStart(4, "0");
   const month = pad(date.getUTCMonth() + 1);
@@ -139,11 +133,54 @@ export function formatTimeTick(value, domain) {
   const hour = pad(date.getUTCHours());
   const minute = pad(date.getUTCMinutes());
   const second = pad(date.getUTCSeconds());
+  const millisecond = String(date.getUTCMilliseconds()).padStart(3, "0");
+
+  if (precision === 0) return year;
+  if (precision === 1) return `${year}-${month}`;
+  if (precision === 2) return `${year}-${month}-${day}`;
+  if (precision === 3) return `${year}-${month}-${day} ${hour}:${minute}`;
+  if (precision === 4) return `${hour}:${minute}`;
+  if (precision === 5) return `${hour}:${minute}:${second}`;
+  return `${hour}:${minute}:${second}.${millisecond}`;
+}
+
+function timePrecision(domain) {
+  const [low, high] = validateTimeDomain(domain);
+  const span = high - low;
+
+  if (span >= 2 * YEAR) return 0;
+  if (span >= 60 * DAY) return 1;
+  if (span >= 2 * DAY) return 2;
+  if (span >= 2 * HOUR) return 3;
+  if (span >= 2 * MINUTE) return 4;
+  return 5;
+}
+
+export function formatTimeTick(value, domain) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError("Time tick value must be a finite timestamp.");
+  }
+  return formatTimePrecision(value, timePrecision(domain));
+}
+
+function distinguishesTicks(values, labels) {
+  const timestamps = new Map();
+  for (let index = 0; index < values.length; index += 1) {
+    const previous = timestamps.get(labels[index]);
+    if (previous !== undefined && previous !== values[index]) return false;
+    timestamps.set(labels[index], values[index]);
+  }
+  return true;
+}
 
-  if (span >= 2 * YEAR) return year;
-  if (span >= 60 * DAY) return `${year}-${month}`;
-  if (span >= 2 * DAY) return `${year}-${month}-${day}`;
-  if (span >= 2 * HOUR) return `${year}-${month}-${day} ${hour}:00`;
-  if (span >= 2 * MINUTE) return `${hour}:${minute}`;
-  return `${hour}:${minute}:${second}`;
+export function formatTimeTicks(values, domain) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError("Time tick values must be finite timestamps.");
+  }
+  const initial = timePrecision(domain);
+  for (let precision = initial; precision <= 6; precision += 1) {
+    const labels = values.map(value => formatTimePrecision(value, precision));
+    if (distinguishesTicks(values, labels)) return cloneAndFreeze(labels);
+  }
+  return cloneAndFreeze(values.map(value => String(value)));
 }

package/src/grammar/transforms.js

@@ -4,7 +4,7 @@ import { validateDensityTransform } from "./density.js";
 import { validateFilterTransform } from "./filter.js";
 import { validateIntervalTransform } from "./interval.js";
 import { validateMarkFilterTransform } from "./markFilter.js";
-import { validateRegressionTransform } from "./regression.js";
+import { validateRegressionTransform } from "./regression/index.js";
 
 const TRANSFORM_VALIDATORS = Object.freeze({
   boxOutlier: validateBoxTransform,

package/src/index.js

@@ -1,2 +1,3 @@
 export { chart } from "./ChartProgram.js";
+export { hconcat, vconcat } from "./composition.js";
 export { render } from "./renderers/canvas/index.js";

package/src/layout/composition.js

@@ -0,0 +1,310 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const DIRECTIONS = Object.freeze(["horizontal", "vertical"]);
+const ALIGNMENTS = Object.freeze(["start", "center", "end"]);
+const SIZE_MODES = Object.freeze(["auto", "explicit"]);
+const PADDING_KEYS = Object.freeze(["top", "right", "bottom", "left"]);
+
+export const DEFAULT_COMPOSITION_LAYOUT = cloneAndFreeze({
+  gap: 16,
+  align: "center",
+  padding: { top: 0, right: 0, bottom: 0, left: 0 }
+});
+
+export function validateCompositionSpacing(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+
+function validatePaddingBase(base) {
+  if (!isPlainObject(base)) {
+    throw new TypeError("Composition padding base must be a plain object.");
+  }
+  for (const key of PADDING_KEYS) {
+    validateCompositionSpacing(base[key], `Composition padding.${key}`);
+  }
+  return base;
+}
+
+export function normalizeCompositionPadding(
+  padding,
+  base = DEFAULT_COMPOSITION_LAYOUT.padding
+) {
+  validatePaddingBase(base);
+  if (Number.isFinite(padding)) {
+    validateCompositionSpacing(padding, "Composition padding");
+    return cloneAndFreeze({
+      top: padding,
+      right: padding,
+      bottom: padding,
+      left: padding
+    });
+  }
+  if (!isPlainObject(padding)) {
+    throw new TypeError("Composition padding must be a number or a plain object.");
+  }
+  const keys = Object.keys(padding);
+  if (keys.length === 0) {
+    throw new TypeError("Composition padding object must contain at least one side.");
+  }
+  for (const key of keys) {
+    if (!PADDING_KEYS.includes(key)) {
+      throw new Error(`Unknown composition padding option "${key}".`);
+    }
+    validateCompositionSpacing(padding[key], `Composition padding.${key}`);
+  }
+  return cloneAndFreeze({ ...base, ...padding });
+}
+
+function normalizeDirection(direction) {
+  if (!DIRECTIONS.includes(direction)) {
+    throw new Error(
+      `Unknown composition direction "${direction}"; expected horizontal or vertical.`
+    );
+  }
+  return direction;
+}
+
+export function normalizeCompositionAlign(align) {
+  if (!ALIGNMENTS.includes(align)) {
+    throw new Error(
+      `Unknown composition align "${align}"; expected start, center, or end.`
+    );
+  }
+  return align;
+}
+
+export function normalizeCompositionChildren(children) {
+  if (!Array.isArray(children) || children.length === 0) {
+    throw new TypeError("Composition layout requires a non-empty children array.");
+  }
+  const ids = new Set();
+  return children.map((child, index) => {
+    if (!isPlainObject(child)) {
+      throw new TypeError(`Composition child ${index} must be a plain object.`);
+    }
+    const unknown = Object.keys(child).find(
+      key => !["id", "width", "height", "widthMode", "heightMode"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(`Unknown composition child property "${unknown}".`);
+    }
+    if (typeof child.id !== "string" || child.id.length === 0) {
+      throw new TypeError(`Composition child ${index} requires a non-empty id.`);
+    }
+    if (ids.has(child.id)) {
+      throw new Error(`Duplicate composition child id "${child.id}".`);
+    }
+    ids.add(child.id);
+    for (const dimension of ["width", "height"]) {
+      if (!Number.isFinite(child[dimension]) || child[dimension] <= 0) {
+        throw new RangeError(
+          `Composition child "${child.id}" ${dimension} must be a positive finite number.`
+        );
+      }
+      const mode = child[`${dimension}Mode`] ?? "explicit";
+      if (!SIZE_MODES.includes(mode)) {
+        throw new Error(
+          `Unknown composition child ${dimension} mode "${mode}"; expected auto or explicit.`
+        );
+      }
+    }
+    return cloneAndFreeze({
+      id: child.id,
+      width: child.width,
+      height: child.height,
+      widthMode: child.widthMode ?? "explicit",
+      heightMode: child.heightMode ?? "explicit"
+    });
+  });
+}
+
+function normalizeAutoCrossSize(children, horizontal) {
+  const dimension = horizontal ? "height" : "width";
+  const mode = `${dimension}Mode`;
+  const sharedSize = Math.max(...children.map(child => child[dimension]));
+  return children.map(child => cloneAndFreeze({
+    ...child,
+    [dimension]: child[mode] === "auto" ? sharedSize : child[dimension]
+  }));
+}
+
+function placementSize(child) {
+  return {
+    id: child.id,
+    width: child.width,
+    height: child.height
+  };
+}
+
+function crossOffset(remaining, align) {
+  if (align === "start") return 0;
+  if (align === "end") return remaining;
+  return remaining / 2;
+}
+
+export function resolveCompositionLayout({
+  direction,
+  children,
+  gap = DEFAULT_COMPOSITION_LAYOUT.gap,
+  align = DEFAULT_COMPOSITION_LAYOUT.align,
+  padding = DEFAULT_COMPOSITION_LAYOUT.padding
+} = {}) {
+  const resolvedDirection = normalizeDirection(direction);
+  const resolvedChildren = normalizeCompositionChildren(children);
+  const resolvedGap = validateCompositionSpacing(gap, "Composition gap");
+  const resolvedAlign = normalizeCompositionAlign(align);
+  const resolvedPadding = normalizeCompositionPadding(padding);
+  const horizontal = resolvedDirection === "horizontal";
+  const sizedChildren = normalizeAutoCrossSize(resolvedChildren, horizontal);
+  const contentWidth = horizontal
+    ? sizedChildren.reduce((sum, child) => sum + child.width, 0) +
+      resolvedGap * (sizedChildren.length - 1)
+    : Math.max(...sizedChildren.map(child => child.width));
+  const contentHeight = horizontal
+    ? Math.max(...sizedChildren.map(child => child.height))
+    : sizedChildren.reduce((sum, child) => sum + child.height, 0) +
+      resolvedGap * (sizedChildren.length - 1);
+  let cursor = horizontal ? resolvedPadding.left : resolvedPadding.top;
+  const placements = sizedChildren.map(child => {
+    const placement = horizontal
+      ? {
+          ...placementSize(child),
+          x: cursor,
+          y: resolvedPadding.top + crossOffset(
+            contentHeight - child.height,
+            resolvedAlign
+          )
+        }
+      : {
+          ...placementSize(child),
+          x: resolvedPadding.left + crossOffset(
+            contentWidth - child.width,
+            resolvedAlign
+          ),
+          y: cursor
+        };
+    cursor += (horizontal ? child.width : child.height) + resolvedGap;
+    return placement;
+  });
+  return cloneAndFreeze({
+    direction: resolvedDirection,
+    gap: resolvedGap,
+    align: resolvedAlign,
+    padding: resolvedPadding,
+    width: resolvedPadding.left + contentWidth + resolvedPadding.right,
+    height: resolvedPadding.top + contentHeight + resolvedPadding.bottom,
+    children: placements
+  });
+}
+
+export function resolveCompositionSnapshotPlacement({
+  direction,
+  align,
+  placement,
+  width,
+  height
+} = {}) {
+  const resolvedDirection = normalizeDirection(direction);
+  const resolvedAlign = normalizeCompositionAlign(align);
+  validatePlacedBounds(placement, "Composition snapshot placement");
+  if (!Number.isFinite(width) || width <= 0) {
+    throw new RangeError("Composition snapshot width must be a positive finite number.");
+  }
+  if (!Number.isFinite(height) || height <= 0) {
+    throw new RangeError("Composition snapshot height must be a positive finite number.");
+  }
+  if (width > placement.width || height > placement.height) {
+    throw new RangeError("Composition snapshot must fit its resolved placement.");
+  }
+  const horizontal = resolvedDirection === "horizontal";
+  return cloneAndFreeze({
+    x: placement.x + (horizontal
+      ? 0
+      : crossOffset(placement.width - width, resolvedAlign)),
+    y: placement.y + (horizontal
+      ? crossOffset(placement.height - height, resolvedAlign)
+      : 0),
+    width,
+    height
+  });
+}
+
+function validatePlacedBounds(value, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  for (const property of ["x", "y", "width", "height"]) {
+    if (!Number.isFinite(value[property])) {
+      throw new TypeError(`${label}.${property} must be finite.`);
+    }
+  }
+  if (value.width <= 0 || value.height <= 0) {
+    throw new RangeError(`${label} width and height must be positive.`);
+  }
+  return value;
+}
+
+export function resolvePlacedPlotBounds({ placements, plots } = {}) {
+  if (!Array.isArray(placements) || placements.length === 0) {
+    throw new TypeError("Placed plot bounds require non-empty placements.");
+  }
+  if (!Array.isArray(plots) || plots.length !== placements.length) {
+    throw new TypeError("Placed plot bounds require one local plot per placement.");
+  }
+  const plotById = new Map();
+  for (const [index, plot] of plots.entries()) {
+    if (!isPlainObject(plot) || typeof plot.id !== "string" || plot.id.length === 0) {
+      throw new TypeError(`Placed plot ${index} requires a non-empty id.`);
+    }
+    if (plotById.has(plot.id)) {
+      throw new Error(`Duplicate placed plot id "${plot.id}".`);
+    }
+    plotById.set(plot.id, validatePlacedBounds(plot, `Placed plot "${plot.id}"`));
+  }
+  const translated = placements.map((placement, index) => {
+    if (
+      !isPlainObject(placement) ||
+      typeof placement.id !== "string" ||
+      placement.id.length === 0
+    ) {
+      throw new TypeError(`Plot placement ${index} requires a non-empty id.`);
+    }
+    validatePlacedBounds(placement, `Plot placement "${placement.id}"`);
+    const plot = plotById.get(placement.id);
+    if (plot === undefined) {
+      throw new Error(`Missing local plot bounds for "${placement.id}".`);
+    }
+    if (
+      plot.x < 0 || plot.y < 0 ||
+      plot.x + plot.width > placement.width ||
+      plot.y + plot.height > placement.height
+    ) {
+      throw new RangeError(
+        `Local plot bounds for "${placement.id}" must fit its placement.`
+      );
+    }
+    plotById.delete(placement.id);
+    return {
+      left: placement.x + plot.x,
+      top: placement.y + plot.y,
+      right: placement.x + plot.x + plot.width,
+      bottom: placement.y + plot.y + plot.height
+    };
+  });
+  if (plotById.size > 0) {
+    throw new Error(`Unknown placed plot id "${plotById.keys().next().value}".`);
+  }
+  const left = Math.min(...translated.map(bounds => bounds.left));
+  const top = Math.min(...translated.map(bounds => bounds.top));
+  const right = Math.max(...translated.map(bounds => bounds.right));
+  const bottom = Math.max(...translated.map(bounds => bounds.bottom));
+  return cloneAndFreeze({
+    x: left,
+    y: top,
+    width: right - left,
+    height: bottom - top
+  });
+}

package/src/layout/facets.js

@@ -0,0 +1,131 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import {
+  DEFAULT_COMPOSITION_LAYOUT,
+  normalizeCompositionAlign,
+  normalizeCompositionChildren,
+  normalizeCompositionPadding,
+  validateCompositionSpacing
+} from "./composition.js";
+
+export const DEFAULT_FACET_LEGEND_GAP = 18;
+export const DEFAULT_FACET_LEGEND_WIDTH = 132;
+
+function resolveColumns(columns, count) {
+  const value = columns ?? count;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError("Facet columns must be a positive integer.");
+  }
+  return Math.min(value, count);
+}
+
+function alignedOffset(remaining, align) {
+  if (align === "start") return 0;
+  if (align === "end") return remaining;
+  return remaining / 2;
+}
+
+export function resolveFacetLayout({
+  children,
+  columns,
+  gap = DEFAULT_COMPOSITION_LAYOUT.gap,
+  align = DEFAULT_COMPOSITION_LAYOUT.align,
+  padding = DEFAULT_COMPOSITION_LAYOUT.padding,
+  titleHeight = 0,
+  sharedLegend = false,
+  sharedLegendGap = DEFAULT_FACET_LEGEND_GAP,
+  sharedLegendWidth = DEFAULT_FACET_LEGEND_WIDTH
+} = {}) {
+  const values = children?.map(child => child?.value);
+  const resolvedChildren = normalizeCompositionChildren(children?.map(
+    ({ value: _value, ...child }) => child
+  ));
+  const resolvedColumns = resolveColumns(columns, resolvedChildren.length);
+  const resolvedGap = validateCompositionSpacing(gap, "Facet gap");
+  const resolvedAlign = normalizeCompositionAlign(align);
+  const resolvedPadding = normalizeCompositionPadding(padding);
+  const resolvedTitleHeight = validateCompositionSpacing(
+    titleHeight,
+    "Facet title height"
+  );
+  if (typeof sharedLegend !== "boolean") {
+    throw new TypeError("Facet sharedLegend must be a boolean.");
+  }
+  const legendGap = validateCompositionSpacing(
+    sharedLegendGap,
+    "Facet shared legend gap"
+  );
+  const legendWidth = validateCompositionSpacing(
+    sharedLegendWidth,
+    "Facet shared legend width"
+  );
+  const rowCount = Math.ceil(resolvedChildren.length / resolvedColumns);
+  const columnWidths = Array.from({ length: resolvedColumns }, (_, column) =>
+    Math.max(...resolvedChildren
+      .filter((_, index) => index % resolvedColumns === column)
+      .map(child => child.width))
+  );
+  const rowHeights = Array.from({ length: rowCount }, (_, row) =>
+    Math.max(...resolvedChildren
+      .slice(row * resolvedColumns, (row + 1) * resolvedColumns)
+      .map(child => child.height))
+  );
+  const columnStarts = columnWidths.map((_, column) =>
+    resolvedPadding.left + columnWidths
+      .slice(0, column)
+      .reduce((sum, width) => sum + width, 0) + resolvedGap * column
+  );
+  const rowStarts = rowHeights.map((_, row) =>
+    resolvedTitleHeight + resolvedPadding.top + rowHeights
+      .slice(0, row)
+      .reduce((sum, height) => sum + height, 0) + resolvedGap * row
+  );
+  const placements = resolvedChildren.map((child, index) => {
+    const column = index % resolvedColumns;
+    const row = Math.floor(index / resolvedColumns);
+    return {
+      id: child.id,
+      value: values[index],
+      column,
+      row,
+      x: columnStarts[column] + alignedOffset(
+        columnWidths[column] - child.width,
+        resolvedAlign
+      ),
+      y: rowStarts[row] + alignedOffset(
+        rowHeights[row] - child.height,
+        resolvedAlign
+      ),
+      width: child.width,
+      height: child.height
+    };
+  });
+  const gridWidth = resolvedPadding.left +
+    columnWidths.reduce((sum, width) => sum + width, 0) +
+    resolvedGap * Math.max(0, resolvedColumns - 1) +
+    resolvedPadding.right;
+  const gridHeight = resolvedTitleHeight + resolvedPadding.top +
+    rowHeights.reduce((sum, height) => sum + height, 0) +
+    resolvedGap * Math.max(0, rowCount - 1) +
+    resolvedPadding.bottom;
+  return cloneAndFreeze({
+    columns: resolvedColumns,
+    rows: rowCount,
+    gap: resolvedGap,
+    align: resolvedAlign,
+    padding: resolvedPadding,
+    titleHeight: resolvedTitleHeight,
+    gridWidth,
+    width: gridWidth + (sharedLegend
+      ? legendGap + legendWidth
+      : 0),
+    height: gridHeight,
+    children: placements,
+    ...(sharedLegend ? {
+      legend: {
+        x: gridWidth + legendGap,
+        y: resolvedTitleHeight + resolvedPadding.top + 30,
+        width: legendWidth
+      }
+    } : {})
+  });
+}

package/src/layout/title.js

@@ -55,6 +55,12 @@ export function alignedTitleAnchor(start, length, blockLength, align) {
   return start + length - blockLength / 2;
 }
 
+export function alignedTextAnchor(start, length, align) {
+  if (align === "left") return start;
+  if (align === "center") return start + length / 2;
+  return start + length;
+}
+
 function axisAlignedTextBounds({ x, y, text, style, align, rotation }) {
   const width = measureTextWidth(text, style);
   const left = align === "left" ? 0 : align === "center" ? -width / 2 : -width;

package/src/materialization/bars/aggregate.js

@@ -4,13 +4,16 @@ import {
   resolveBarChannels,
   resolveBarColorLayout
 } from "../../grammar/bars/policy.js";
-import { layoutSeriesPartition } from "../../grammar/seriesLayout.js";
+import {
+  DEFAULT_SERIES_BASELINE,
+  layoutSeriesPartition
+} from "../../grammar/seriesLayout.js";
 import {
   isDiscretePositionScaleType,
   mapContinuousScaleValues,
   mapOrdinalPositionValues,
   mapSequentialColors
-} from "../../grammar/scales.js";
+} from "../../grammar/scales/index.js";
 import {
   DEFAULT_BAR_FILL,
   DEFAULT_BAR_STROKE,
@@ -66,7 +69,7 @@ export function deriveAggregateRectangles(required, resolved, widthConfig) {
     widthConfig,
     Math.abs(categoryScale.bandwidth ?? categoryScale.step)
   );
-  const baseline = layout === "overlay" ? measureScale.domain[0] : 0;
+  const baseline = DEFAULT_SERIES_BASELINE;
   const continuousColor = colorEncoding?.fieldType === "quantitative";
   if (continuousColor) {
     const mappedColors = mapSequentialColors(