ggaction 0.0.7 → 0.0.8

package/src/grammar/direction.js

@@ -0,0 +1,46 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import { readQuantitativeField } from "./scales/index.js";
+
+function finite(value, label) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${label} must be finite.`);
+  }
+  return value;
+}
+
+export function directionVector(degrees) {
+  const radians = finite(degrees, "Direction degrees") * Math.PI / 180;
+  return cloneAndFreeze({
+    x: Math.sin(radians),
+    y: -Math.cos(radians)
+  });
+}
+
+export function centeredDirectionalSegment({ x, y, degrees = 0, length }) {
+  const centerX = finite(x, "Directional segment x");
+  const centerY = finite(y, "Directional segment y");
+  const resolvedLength = finite(length, "Directional segment length");
+  if (resolvedLength <= 0) {
+    throw new RangeError("Directional segment length must be positive.");
+  }
+  const vector = directionVector(degrees);
+  const half = resolvedLength / 2;
+  return cloneAndFreeze({
+    x1: centerX - vector.x * half,
+    y1: centerY - vector.y * half,
+    x2: centerX + vector.x * half,
+    y2: centerY + vector.y * half
+  });
+}
+
+export function resolveDirectionValues(rows, encoding) {
+  if (encoding === undefined) return undefined;
+  if (Object.hasOwn(encoding, "datum")) {
+    const value = finite(encoding.datum, "Direction value");
+    return cloneAndFreeze(rows.map(() => value));
+  }
+  if (encoding.fieldType !== "quantitative") {
+    throw new Error("Direction field must be quantitative.");
+  }
+  return readQuantitativeField(rows, encoding.field);
+}

package/src/grammar/facets/index.js

@@ -5,7 +5,7 @@ import { planFacetDependencies } from "./dependencies.js";
 import { readNominalField } from "../scales/index.js";
 
 const SUPPORTED_MARKS = new Set([
-  "point", "line", "area", "bar", "rule", "rect"
+  "point", "line", "area", "bar", "rule", "tick", "rect"
 ]);
 const SUPPORTED_BAR_GRAINS = new Set([
   BAR_GRAINS.histogram,

package/src/grammar/pointShapes.js

@@ -77,6 +77,12 @@ function shapePolygon(shape) {
     { x: -1, y: -arm }, { x: -arm, y: -arm }
   ];
   return {
+    square: [
+      { x: -1, y: -1 },
+      { x: 1, y: -1 },
+      { x: 1, y: 1 },
+      { x: -1, y: 1 }
+    ],
     diamond: [
       { x: 0, y: -1 },
       { x: 1, y: 0 },
@@ -120,7 +126,8 @@ export function createPointShapeGraphic({
   fill,
   stroke,
   strokeWidth,
-  opacity
+  opacity,
+  angle
 }) {
   const validated = validatePointShape(shape);
   if (![x, y, area].every(Number.isFinite) || area < 0) {
@@ -130,13 +137,16 @@ export function createPointShapeGraphic({
     throw new TypeError("Point shape fill must be a non-empty string.");
   }
   const shared = appearance(fill, stroke, strokeWidth, opacity);
+  if (angle !== undefined && !Number.isFinite(angle)) {
+    throw new TypeError("Point shape angle must be finite degrees.");
+  }
   if (validated === "circle") {
     return {
       type: "circle",
       properties: { x, y, radius: Math.sqrt(area / Math.PI), ...shared }
     };
   }
-  if (validated === "square") {
+  if (validated === "square" && angle === undefined) {
     const side = Math.sqrt(area);
     return {
       type: "rect",
@@ -155,7 +165,12 @@ export function createPointShapeGraphic({
     type: "path",
     properties: {
       commands: buildLinearPathCommands(
-        normalizePolygon(shapePolygon(validated), x, y, area),
+        normalizePolygon(
+          rotate(shapePolygon(validated), (angle ?? 0) * Math.PI / 180),
+          x,
+          y,
+          area
+        ),
         { close: true }
       ),
       ...shared
@@ -163,7 +178,12 @@ export function createPointShapeGraphic({
   };
 }
 
-export function resolvePointShapeExtent({ shape, area, strokeWidth = 0 }) {
+export function resolvePointShapeExtent({
+  shape,
+  area,
+  strokeWidth = 0,
+  angle
+}) {
   const validated = validatePointShape(shape);
   if (!Number.isFinite(area) || area < 0) {
     throw new TypeError("Point shape area must be finite and non-negative.");
@@ -176,11 +196,19 @@ export function resolvePointShapeExtent({ shape, area, strokeWidth = 0 }) {
     const radius = Math.sqrt(area / Math.PI) + strokeExtent;
     return cloneAndFreeze({ x: radius, y: radius });
   }
-  if (validated === "square") {
+  if (angle !== undefined && !Number.isFinite(angle)) {
+    throw new TypeError("Point shape angle must be finite degrees.");
+  }
+  if (validated === "square" && angle === undefined) {
     const halfSide = Math.sqrt(area) / 2 + strokeExtent;
     return cloneAndFreeze({ x: halfSide, y: halfSide });
   }
-  const points = normalizePolygon(shapePolygon(validated), 0, 0, area);
+  const points = normalizePolygon(
+    rotate(shapePolygon(validated), (angle ?? 0) * Math.PI / 180),
+    0,
+    0,
+    area
+  );
   return cloneAndFreeze({
     x: Math.max(0, ...points.map(point => Math.abs(point.x))) + strokeExtent,
     y: Math.max(0, ...points.map(point => Math.abs(point.y))) + strokeExtent

package/src/grammar/positionCompatibility.js

@@ -23,6 +23,10 @@ export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
     y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
   }),
+  tick: Object.freeze({
+    x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+  }),
   bar: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
     y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])

package/src/grammar/schemas/semanticPath.js

@@ -31,7 +31,8 @@ const ENCODING_PATHS = Object.freeze([
   "encoding.parallel.missing",
   ...CARTESIAN_POSITION_CHANNELS.flatMap(channel => [
     `encoding.${channel}.aggregate`,
-    `encoding.${channel}.stack`
+    `encoding.${channel}.stack`,
+    `encoding.${channel}.categoryOrder`
   ])
 ]);
 

package/src/grammar/seriesLayout.js

@@ -35,13 +35,13 @@ export function layoutSeriesPartition(
     ));
   }
 
-  if (layout === "stack" || layout === "fill") {
+  if (["stack", "fill", "center"].includes(layout)) {
     if (values.some(value => value < 0)) {
       throw new RangeError(`${layout} layout requires non-negative values.`);
     }
     const total = values.reduce((sum, value) => sum + value, 0);
     if (layout === "fill" && total === 0) return cloneAndFreeze([]);
-    let offset = 0;
+    let offset = layout === "center" ? -total / 2 : 0;
     return cloneAndFreeze(values.flatMap((value, index) => {
       if (value === 0) return [];
       const resolvedValue = layout === "fill" ? value / total : value;
@@ -78,6 +78,14 @@ export function resolveSeriesLayoutDomainValues(partitions, layout) {
       ...partition
     ]);
   }
+  if (layout === "center") {
+    return partitions.flatMap(partition => {
+      const segments = layoutSeriesPartition(partition, layout);
+      return segments.length === 0
+        ? [DEFAULT_SERIES_BASELINE]
+        : segments.flatMap(segment => [segment.start, segment.end]);
+    });
+  }
   return partitions.flatMap(partition =>
     layoutSeriesPartition(partition, layout).flatMap(segment => [
       segment.start,

package/src/grammar/timeUnit.js

@@ -0,0 +1,108 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { normalizeTemporalValue } from "./scales/fields.js";
+
+export const TIME_UNITS = cloneAndFreeze([
+  "year",
+  "quarter",
+  "month",
+  "day",
+  "hour",
+  "minute",
+  "second"
+]);
+
+const TRANSFORM_KEYS = Object.freeze(["type", "field", "unit", "as"]);
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function rejectUnknownKeys(value) {
+  const unknown = Object.keys(value).find(key => !TRANSFORM_KEYS.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown time-unit transform property "${unknown}".`);
+  }
+}
+
+export function validateTimeUnitTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Time-unit transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform);
+  if (transform.type !== "timeUnit") {
+    throw new Error(`Unsupported time-unit transform "${transform.type}".`);
+  }
+  const field = requireField(transform.field, "Time-unit field");
+  const output = requireField(transform.as, "Time-unit output field");
+  if (field === output) {
+    throw new Error("Time-unit input and output fields must be distinct.");
+  }
+  if (!TIME_UNITS.includes(transform.unit)) {
+    throw new Error(`Unsupported time unit "${transform.unit}".`);
+  }
+  return transform;
+}
+
+export function normalizeTimeUnitTransform({ field, unit, as } = {}) {
+  const transform = { type: "timeUnit", field, unit, as };
+  validateTimeUnitTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+function utcTimestamp(year, month = 0, day = 1, hour = 0, minute = 0) {
+  const date = new Date(0);
+  date.setUTCFullYear(year, month, day);
+  date.setUTCHours(hour, minute, 0, 0);
+  return date.getTime();
+}
+
+export function floorUtcTimeUnit(timestamp, unit) {
+  if (!Number.isFinite(timestamp)) {
+    throw new TypeError("Time-unit timestamp must be finite.");
+  }
+  if (!TIME_UNITS.includes(unit)) {
+    throw new Error(`Unsupported time unit "${unit}".`);
+  }
+  const date = new Date(timestamp);
+  if (!Number.isFinite(date.getTime())) {
+    throw new TypeError("Time-unit timestamp must represent a valid date.");
+  }
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth();
+  if (unit === "year") return utcTimestamp(year);
+  if (unit === "quarter") return utcTimestamp(year, Math.floor(month / 3) * 3);
+  if (unit === "month") return utcTimestamp(year, month);
+  const day = date.getUTCDate();
+  if (unit === "day") return utcTimestamp(year, month, day);
+  const hour = date.getUTCHours();
+  if (unit === "hour") return utcTimestamp(year, month, day, hour);
+  const minute = date.getUTCMinutes();
+  if (unit === "minute") return utcTimestamp(year, month, day, hour, minute);
+  return Math.floor(timestamp / 1000) * 1000;
+}
+
+export function deriveTimeUnitRows(rows, transform) {
+  validateTimeUnitTransform(transform);
+  if (!Array.isArray(rows) || !rows.every(isPlainObject)) {
+    throw new TypeError("Time-unit source must contain plain row objects.");
+  }
+  const values = rows.map((row, index) => {
+    if (!Object.hasOwn(row, transform.field)) {
+      throw new Error(
+        `Time-unit source does not contain field "${transform.field}" at row ${index}.`
+      );
+    }
+    if (Object.hasOwn(row, transform.as)) {
+      throw new Error(`Time-unit output field "${transform.as}" already exists.`);
+    }
+    const timestamp = normalizeTemporalValue(row[transform.field], transform.field, index);
+    return {
+      ...row,
+      [transform.as]: floorUtcTimeUnit(timestamp, transform.unit)
+    };
+  });
+  return cloneAndFreeze(values);
+}

package/src/grammar/transforms.js

@@ -18,6 +18,7 @@ import {
 import { validateMarkFilterTransform } from "./markFilter.js";
 import { validateRegressionTransform } from "./regression/index.js";
 import { validateWindowTransform } from "./window.js";
+import { validateTimeUnitTransform } from "./timeUnit.js";
 
 function requestedDensityTransform(transform) {
   const { resolved: _resolved, ...requested } = transform;
@@ -94,6 +95,11 @@ const TRANSFORM_POLICIES = Object.freeze({
     materializeOp: "materializeRegressionData",
     facetTopology: "statistical"
   }),
+  timeUnit: Object.freeze({
+    validate: validateTimeUnitTransform,
+    materializeOp: "materializeTimeUnitData",
+    facetTopology: "rowPreserving"
+  }),
   window: Object.freeze({
     validate: validateWindowTransform,
     materializeOp: "materializeWindowData",

package/src/grammar/window.js

@@ -6,10 +6,13 @@ const TRANSFORM_KEYS = Object.freeze([
 const SORT_KEYS = Object.freeze(["field", "order"]);
 const ORDER_VALUES = Object.freeze(["ascending", "descending"]);
 const OPERATION_VALUES = Object.freeze([
-  "rowNumber", "rank", "denseRank", "cumulativeSum", "lag", "lead"
+  "rowNumber", "rank", "denseRank", "cumulativeSum", "lag", "lead",
+  "movingMean", "movingSum"
 ]);
 const POSITION_OPERATIONS = new Set(["rowNumber", "rank", "denseRank"]);
 const OFFSET_OPERATIONS = new Set(["lag", "lead"]);
+const MOVING_OPERATIONS = new Set(["movingMean", "movingSum"]);
+const FRAME_KEYS = Object.freeze(["preceding", "following"]);
 
 function requireField(value, label) {
   if (typeof value !== "string" || value.length === 0) {
@@ -63,9 +66,29 @@ function operationKeys(operation) {
   if (OFFSET_OPERATIONS.has(operation.op)) {
     return ["op", "field", "as", "offset", "default"];
   }
+  if (MOVING_OPERATIONS.has(operation.op)) {
+    return ["op", "field", "as", "frame"];
+  }
   return ["op"];
 }
 
+function validateFrame(frame, operation) {
+  if (!isPlainObject(frame)) {
+    throw new TypeError(`Window ${operation} frame must be a plain object.`);
+  }
+  rejectUnknownKeys(frame, FRAME_KEYS, `window ${operation} frame`);
+  if (!Number.isInteger(frame.preceding) || frame.preceding < 0) {
+    throw new RangeError(
+      `Window ${operation} frame preceding must be a non-negative integer.`
+    );
+  }
+  if (!Number.isInteger(frame.following) || frame.following < 0) {
+    throw new RangeError(
+      `Window ${operation} frame following must be a non-negative integer.`
+    );
+  }
+}
+
 function validateOperations(operations, sortBy) {
   if (!Array.isArray(operations) || operations.length === 0) {
     throw new TypeError("Window operations must be a non-empty array.");
@@ -98,6 +121,9 @@ function validateOperations(operations, sortBy) {
         throw new TypeError(`Window ${operation.op} requires a default value.`);
       }
     }
+    if (MOVING_OPERATIONS.has(operation.op)) {
+      validateFrame(operation.frame, operation.op);
+    }
   });
 }
 
@@ -132,14 +158,26 @@ function normalizeSortBy(value) {
 function normalizeOperations(value) {
   if (!Array.isArray(value)) return value;
   return value.map(operation => {
-    if (!isPlainObject(operation) || !OFFSET_OPERATIONS.has(operation.op)) {
+    if (!isPlainObject(operation)) {
       return operation;
     }
-    return {
-      ...operation,
-      offset: operation.offset ?? 1,
-      default: Object.hasOwn(operation, "default") ? operation.default : null
-    };
+    if (OFFSET_OPERATIONS.has(operation.op)) {
+      return {
+        ...operation,
+        offset: operation.offset ?? 1,
+        default: Object.hasOwn(operation, "default") ? operation.default : null
+      };
+    }
+    if (MOVING_OPERATIONS.has(operation.op) && isPlainObject(operation.frame)) {
+      return {
+        ...operation,
+        frame: {
+          ...operation.frame,
+          following: operation.frame.following ?? 0
+        }
+      };
+    }
+    return operation;
   });
 }
 
@@ -305,6 +343,34 @@ function applyOperation(partition, operation, sortBy) {
     }
     return;
   }
+  if (MOVING_OPERATIONS.has(operation.op)) {
+    partition.forEach((entry, index) => {
+      const first = Math.max(0, index - operation.frame.preceding);
+      const last = Math.min(
+        partition.length - 1,
+        index + operation.frame.following
+      );
+      let total = 0;
+      for (let peerIndex = first; peerIndex <= last; peerIndex += 1) {
+        const value = partition[peerIndex].row[operation.field];
+        if (!Number.isFinite(value)) {
+          throw new TypeError(
+            `Window ${operation.op} field "${operation.field}" must contain finite numbers.`
+          );
+        }
+        total += value;
+        if (!Number.isFinite(total)) {
+          throw new RangeError(
+            `Window ${operation.op} output "${operation.as}" must be finite.`
+          );
+        }
+      }
+      entry.row[operation.as] = operation.op === "movingMean"
+        ? total / (last - first + 1)
+        : total;
+    });
+    return;
+  }
   const direction = operation.op === "lag" ? -1 : 1;
   partition.forEach((entry, index) => {
     const peer = partition[index + direction * operation.offset];