ggaction 0.0.2 → 0.0.3

package/src/materialization/selection/styles.js

@@ -80,30 +80,30 @@ export function normalizePointHighlightStyle(args) {
   };
 }
 
-export function normalizeBarHighlightStyle(args) {
+function normalizeRectangularHighlightStyle(args, mark) {
   for (const option of ["shape", "size", "offset", "strokeDash"]) {
     if (args[option] !== undefined) {
-      throw new Error(`Bar highlight does not support ${option}.`);
+      throw new Error(`${mark} highlight does not support ${option}.`);
     }
   }
   if (args.color !== undefined && args.fill !== undefined) {
-    throw new Error("Bar highlight accepts color or fill, not both.");
+    throw new Error(`${mark} highlight accepts color or fill, not both.`);
   }
   const fill = validateNonEmptyString(
     args.fill ?? args.color ?? DEFAULT_COLORS.highlight,
-    "Bar highlight fill"
+    `${mark} highlight fill`
   );
   const opacity = args.opacity === undefined
     ? undefined
-    : validateUnitInterval(args.opacity, "Bar highlight opacity");
+    : validateUnitInterval(args.opacity, `${mark} highlight opacity`);
   const stroke = args.stroke === undefined
     ? undefined
-    : validateNonEmptyString(args.stroke, "Bar highlight stroke");
+    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
   const strokeWidth = args.strokeWidth === undefined
     ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, "Bar highlight strokeWidth");
+    : validateNonNegativeFinite(args.strokeWidth, `${mark} highlight strokeWidth`);
   if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error("Bar highlight strokeWidth requires stroke.");
+    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
   }
   return {
     fill,
@@ -113,6 +113,14 @@ export function normalizeBarHighlightStyle(args) {
   };
 }
 
+export function normalizeBarHighlightStyle(args) {
+  return normalizeRectangularHighlightStyle(args, "Bar");
+}
+
+export function normalizeRectHighlightStyle(args) {
+  return normalizeRectangularHighlightStyle(args, "Rect");
+}
+
 function rejectHighlightOptions(args, mark, options) {
   for (const option of options) {
     if (args[option] !== undefined) {
@@ -154,28 +162,28 @@ export function normalizeStrokeHighlightStyle(args, mark) {
   };
 }
 
-export function normalizeAreaHighlightStyle(args) {
-  rejectHighlightOptions(args, "Area", ["shape", "size", "strokeDash"]);
+export function normalizeAreaHighlightStyle(args, mark = "Area") {
+  rejectHighlightOptions(args, mark, ["shape", "size", "strokeDash"]);
   if (args.color !== undefined && args.fill !== undefined) {
-    throw new Error("Area highlight accepts color or fill, not both.");
+    throw new Error(`${mark} highlight accepts color or fill, not both.`);
   }
   const stroke = args.stroke === undefined
     ? undefined
-    : validateNonEmptyString(args.stroke, "Area highlight stroke");
+    : validateNonEmptyString(args.stroke, `${mark} highlight stroke`);
   const strokeWidth = args.strokeWidth === undefined
     ? undefined
-    : validateNonNegativeFinite(args.strokeWidth, "Area highlight strokeWidth");
+    : validateNonNegativeFinite(args.strokeWidth, `${mark} highlight strokeWidth`);
   if (strokeWidth !== undefined && stroke === undefined) {
-    throw new Error("Area highlight strokeWidth requires stroke.");
+    throw new Error(`${mark} highlight strokeWidth requires stroke.`);
   }
   return {
     fill: validateNonEmptyString(
       args.fill ?? args.color ?? DEFAULT_COLORS.highlight,
-      "Area highlight fill"
+      `${mark} highlight fill`
     ),
     ...(args.opacity === undefined
       ? {}
-      : { opacity: validateUnitInterval(args.opacity, "Area highlight opacity") }),
+      : { opacity: validateUnitInterval(args.opacity, `${mark} highlight opacity`) }),
     ...(stroke === undefined ? {} : { stroke }),
     ...(strokeWidth === undefined ? {} : { strokeWidth }),
     offset: normalizeOffset(args.offset)

package/src/materialization/text.js

@@ -0,0 +1,156 @@
+import { resolveBarChannels } from "../grammar/bars/policy.js";
+import { formatTextValue } from "../grammar/text.js";
+import { findDataset } from "../selectors/datasets.js";
+import { findLayer } from "../selectors/layers.js";
+import { resolveMarkItems } from "./selection/policies/index.js";
+import { mapScaleConsumerValues } from "./scales/map.js";
+import { resolveRowEncodingValues } from "./rowEncoding.js";
+
+function sourceValue(item, source, field) {
+  if (Object.hasOwn(item.fields, field)) return item.fields[field];
+  for (const [channel, encoding] of Object.entries(source.encoding ?? {})) {
+    if (encoding?.field !== field || item.channels[channel] === undefined) continue;
+    if (source.mark.type === "bar" && item.channels[`${channel}2`] !== undefined) {
+      return item.channels[`${channel}2`];
+    }
+    return item.channels[channel];
+  }
+  if (item.members.length === 1 && Object.hasOwn(item.members[0], field)) {
+    return item.members[0][field];
+  }
+  return undefined;
+}
+
+function barAnchor(program, source, item) {
+  const channels = resolveBarChannels(source);
+  const measure = channels.measure;
+  const endpoint = item.channels[`${measure}2`];
+  const scale = program.resolvedScales[source.encoding[measure].scale];
+  const mapped = endpoint === undefined || scale === undefined
+    ? undefined
+    : mapScaleConsumerValues([endpoint], scale, measure)[0];
+  return measure === "x"
+    ? {
+        x: mapped ?? item.properties.x + item.properties.width,
+        y: item.properties.y + item.properties.height / 2
+      }
+    : {
+        x: item.properties.x + item.properties.width / 2,
+        y: mapped ?? item.properties.y
+      };
+}
+
+function sourceAnchor(program, source, item) {
+  if (source.mark.type === "bar") return barAnchor(program, source, item);
+  if (source.mark.type === "rect") {
+    return {
+      x: item.properties.x + item.properties.width / 2,
+      y: item.properties.y + item.properties.height / 2
+    };
+  }
+  if (source.mark.type === "rule") {
+    return {
+      x: item.properties.x2,
+      y: item.properties.y2
+    };
+  }
+  return { x: item.properties.x, y: item.properties.y };
+}
+
+function contentValue(encoding, rowOrItem, source) {
+  return Object.hasOwn(encoding, "field")
+    ? source === undefined
+      ? rowOrItem[encoding.field]
+      : sourceValue(rowOrItem, source, encoding.field)
+    : encoding.datum;
+}
+
+function concreteItem(config, position, value, format) {
+  const text = formatTextValue(value, format);
+  const x = position.x;
+  const y = position.y;
+  if (text === undefined || !Number.isFinite(x) || !Number.isFinite(y)) {
+    return undefined;
+  }
+  return {
+    type: "text",
+    properties: {
+      x: x + config.dx,
+      y: y + config.dy,
+      text,
+      fill: config.fill,
+      opacity: config.opacity,
+      fontSize: config.fontSize,
+      fontFamily: config.fontFamily,
+      fontWeight: config.fontWeight,
+      textAlign: config.align,
+      textBaseline: config.baseline,
+      rotation: config.rotation
+    }
+  };
+}
+
+function relativeLuminance(color) {
+  if (typeof color !== "string" || !/^#[0-9a-f]{6}$/i.test(color)) {
+    return undefined;
+  }
+  const channels = [1, 3, 5].map(offset =>
+    Number.parseInt(color.slice(offset, offset + 2), 16) / 255
+  ).map(value => value <= 0.04045
+    ? value / 12.92
+    : ((value + 0.055) / 1.055) ** 2.4
+  );
+  return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2];
+}
+
+function sourceTextConfig(config, source, item) {
+  if (source.mark.type !== "rect" || config.fillExplicit === true) return config;
+  const luminance = relativeLuminance(item.properties.fill);
+  if (luminance === undefined) return config;
+  return {
+    ...config,
+    fill: luminance >= 0.26 ? "#0f172a" : "#f8fafc"
+  };
+}
+
+function resolveSourceTextItems(program, layer, config) {
+  const source = findLayer(program, layer.source);
+  if (source === undefined) {
+    throw new Error(`Text mark "${layer.id}" requires source layer "${layer.source}".`);
+  }
+  const items = resolveMarkItems(program, source.id);
+  return items.flatMap(item => {
+    const concrete = concreteItem(
+      sourceTextConfig(config, source, item),
+      sourceAnchor(program, source, item),
+      contentValue(layer.encoding.text, item, source),
+      layer.encoding.text.format
+    );
+    return concrete === undefined ? [] : [concrete];
+  });
+}
+
+function resolveRowTextItems(program, layer, config) {
+  const dataset = findDataset(program, layer.data);
+  if (dataset === undefined) {
+    throw new Error(`Text mark "${layer.id}" requires an existing dataset.`);
+  }
+  const x = resolveRowEncodingValues(program, layer, dataset, "x");
+  const y = resolveRowEncodingValues(program, layer, dataset, "y");
+  if (x === undefined || y === undefined) return [];
+  return dataset.values.flatMap((row, index) => {
+    const concrete = concreteItem(
+      config,
+      { x: x[index], y: y[index] },
+      contentValue(layer.encoding.text, row),
+      layer.encoding.text.format
+    );
+    return concrete === undefined ? [] : [concrete];
+  });
+}
+
+export function resolveTextGraphicItems(program, layer, config) {
+  return layer.source === undefined
+    ? resolveRowTextItems(program, layer, config)
+    : resolveSourceTextItems(program, layer, config);
+}

package/src/renderers/canvas/index.js

@@ -4,7 +4,10 @@ import { drawPathGraphic } from "./path.js";
 import { drawRectGraphic } from "./rect.js";
 import { drawTextGraphic } from "./text.js";
 import { requireFiniteProperty } from "./validation.js";
-import { walkGraphicDrawOrder } from "../../grammar/schemas/graphicTree.js";
+import {
+  requireSingleOrderedGraphicByType,
+  walkGraphicTreeEvents
+} from "../../grammar/schemas/graphicTree.js";
 
 const DRAWERS = Object.freeze({
   circle: drawCircleGraphic,
@@ -46,16 +49,41 @@ function requireCanvasContext(context) {
   }
 }
 
-function findCanvas(graphicSpec) {
-  const canvasIds = graphicSpec.order.filter(
-    id => graphicSpec.objects[id]?.type === "canvas"
-  );
+function requireContextMethod(context, method, label) {
+  if (typeof context[method] !== "function") {
+    throw new TypeError(`${label} requires Canvas context ${method}().`);
+  }
+}
 
-  if (canvasIds.length !== 1) {
-    throw new Error("graphicSpec must contain exactly one ordered canvas.");
+function fillCanvasBackground(context, id, canvas, width, height) {
+  if (canvas.properties.background === undefined) return;
+  if (typeof canvas.properties.background !== "string") {
+    throw new Error(
+      `Graphic "${id}" requires a string background property.`
+    );
   }
+  context.globalAlpha = 1;
+  context.fillStyle = canvas.properties.background;
+  context.fillRect(0, 0, width, height);
+}
 
-  return { id: canvasIds[0], graphic: graphicSpec.objects[canvasIds[0]] };
+function enterNestedCanvas(context, id, canvas) {
+  const properties = canvas.properties ?? {};
+  const x = requireFiniteProperty(properties, "x", id);
+  const y = requireFiniteProperty(properties, "y", id);
+  const width = requireFiniteProperty(properties, "width", id);
+  const height = requireFiniteProperty(properties, "height", id);
+  if (width < 0 || height < 0) {
+    throw new Error(`Nested Canvas "${id}" width and height must not be negative.`);
+  }
+  requireContextMethod(context, "rect", `Nested Canvas "${id}"`);
+  requireContextMethod(context, "clip", `Nested Canvas "${id}"`);
+  context.save();
+  context.translate(x, y);
+  context.beginPath();
+  context.rect(0, 0, width, height);
+  context.clip();
+  fillCanvasBackground(context, id, canvas, width, height);
 }
 
 export function render(program, context, { pixelRatio = 1 } = {}) {
@@ -77,7 +105,8 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
     throw new RangeError("render pixelRatio must be a positive finite number.");
   }
 
-  const { id: canvasId, graphic: canvas } = findCanvas(graphicSpec);
+  const { id: canvasId, object: canvas } =
+    requireSingleOrderedGraphicByType(graphicSpec, "canvas");
   const width = requireFiniteProperty(canvas.properties ?? {}, "width", canvasId);
   const height = requireFiniteProperty(
     canvas.properties ?? {},
@@ -97,20 +126,37 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
     context.scale(pixelRatio, pixelRatio);
     context.clearRect(0, 0, width, height);
 
-    if (canvas.properties.background !== undefined) {
-      if (typeof canvas.properties.background !== "string") {
-        throw new Error(
-          `Graphic "${canvasId}" requires a string background property.`
-        );
+    fillCanvasBackground(context, canvasId, canvas, width, height);
+
+    walkGraphicTreeEvents(graphicSpec, {
+      enter({ id, object }) {
+        if (id === canvasId) return;
+        if (object.type === "canvas") {
+          enterNestedCanvas(context, id, object);
+          return;
+        }
+        if (object.type === "collection") {
+          context.save();
+          return;
+        }
+        if (!Array.isArray(object.items)) {
+          drawConcreteGraphic(context, id, object);
+        }
+      },
+      item({ id, object, owner }) {
+        drawConcreteGraphic(context, id, {
+          ...object,
+          type: object.type ?? owner.type
+        });
+      },
+      exit({ id, object }) {
+        if (
+          id !== canvasId &&
+          (object.type === "collection" || object.type === "canvas")
+        ) {
+          context.restore();
+        }
       }
-
-      context.globalAlpha = 1;
-      context.fillStyle = canvas.properties.background;
-      context.fillRect(0, 0, width, height);
-    }
-
-    walkGraphicDrawOrder(graphicSpec, ({ id, object }) => {
-      if (id !== canvasId) drawConcreteGraphic(context, id, object);
     });
   } finally {
     context.restore();

package/types/extension.d.ts

@@ -6,6 +6,7 @@ export { ChartProgram };
 export interface ActionMetadata {
   op: string;
   description: string;
+  scope?: "unit" | "composition" | "any";
 }
 
 export function action<TOptions extends ActionOptions = ActionOptions>(

package/types/index.d.ts

@@ -1,4 +1,4 @@
-import type { ChartProgram } from "./program.js";
+import type { ChartProgram, CompositionOptions } from "./program.js";
 
 export type {
   ActionOptions,
@@ -18,19 +18,56 @@ export type {
   ColorLayout,
   ColorEncodingOptions,
   CompleteAxisOptions,
+  ConcatCompositionSpec,
+  CompositionAlign,
+  CompositionOptions,
+  CompositionPadding,
+  CompositionProgramEntry,
+  CompositionSpec,
   ChartProgram,
   ConcretePathCommand,
   CurveInterpolation,
+  CreateDerivedDataOptions,
   CreateAxesOptions,
+  CreateCoordinateOptions,
+  CreateGuidesOptions,
   CreateGridOptions,
+  CreateRegressionBandOptions,
+  CreateRegressionLineOptions,
+  CreateScaleOptions,
   DashPattern,
   DashScaleOptions,
   DashStyle,
+  DatasetDensityTransform,
+  DatasetFilterTransform,
+  DatasetIntervalOutputFields,
+  DatasetIntervalTransform,
+  DatasetRegressionTransform,
+  DatasetScalar,
+  DatasetTransform,
   EditGraphicsOptions,
+  EditCompositionLayoutOptions,
+  EditFacetHeadersOptions,
+  EditAxisOptions,
+  EditGridDirectionsOptions,
   EditGridOptions,
+  EditErrorBandBoundaryOptions,
+  EditErrorBandOptions,
+  EditErrorBarOptions,
+  EditBoxPlotOptions,
+  EditLegendBorderOptions,
+  EditLegendLabelsOptions,
+  EditLegendLayoutOptions,
+  EditLegendSymbolsOptions,
+  EditLegendTitleOptions,
   EditScaleOptions,
   EditSemanticOptions,
   FieldType,
+  FacetCompositionSpec,
+  FacetGuideOptions,
+  FacetOptions,
+  FacetScaleResolution,
+  FacetScaleResolutions,
   GraphicObject,
   GraphicSpec,
   GraphicType,
@@ -57,23 +94,41 @@ export type {
   RegressionInterval,
   RegressionMethod,
   RegressionOptions,
+  RectMarkOptions,
+  ReplaceCompositionChildOptions,
+  EditRegressionOptions,
+  EditRectMarkOptions,
+  RemoveAxisOptions,
+  RemoveGridOptions,
+  RemoveLegendOptions,
+  RemoveMarkOptions,
   ScaleRange,
   ScaleOptions,
   ScaleType,
   StackMode,
+  SemanticCoordinate,
+  SemanticDataset,
+  SemanticLayer,
+  SemanticScale,
   SemanticSpec,
   SelectMarksOptions,
   StrokeDashEncodingOptions,
   TraceNode,
   TitleOptions,
   EditTitleOptions,
+  EditTextMarkOptions,
   TitleTextStyleOptions,
+  TextEncodingOptions,
+  TextFormat,
+  TextMarkOptions,
   XAxisPosition,
   YAxisPosition,
   XOffsetEncodingOptions
 } from "./program.js";
 
 export function chart(): ChartProgram;
+export function hconcat(options: CompositionOptions): ChartProgram;
+export function vconcat(options: CompositionOptions): ChartProgram;
 export function render(
   program: Pick<ChartProgram, "graphicSpec">,
   context: CanvasRenderingContext2D,