ggaction 0.0.12 → 0.0.15

package/src/actions/theme/state.js

@@ -0,0 +1,160 @@
+import {
+  cloneAndFreeze,
+  freezeOwned,
+  isPlainObject
+} from "../../core/immutable.js";
+import {
+  normalizeThemeDefinition,
+  resolveThemeTokens
+} from "../../theme/defaults.js";
+
+export const LOCAL_THEME_OWNER = "local";
+
+function ownArray(value) {
+  return freezeOwned([...(value ?? [])]);
+}
+
+function requireThemeScope(value) {
+  if (!["self", "descendants"].includes(value)) {
+    throw new Error(`Unsupported theme scope "${value}".`);
+  }
+  return value;
+}
+
+function requireThemeOwner(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("Theme frame owner must be a non-empty string.");
+  }
+  return value;
+}
+
+export function compositionThemeOwner(id, scope = "descendants") {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Composition theme owner requires a non-empty id.");
+  }
+  requireThemeScope(scope);
+  return scope === "self" ? `composition:${id}:self` : `composition:${id}`;
+}
+
+export function createThemeFrame({
+  owner = LOCAL_THEME_OWNER,
+  scope = "self",
+  definition
+}) {
+  const normalized = normalizeThemeDefinition(definition);
+  return freezeOwned({
+    owner: requireThemeOwner(owner),
+    scope: requireThemeScope(scope),
+    name: normalized.name,
+    tokens: normalized.tokens
+  });
+}
+
+export function upsertThemeFrame(frames = [], frame) {
+  if (!Array.isArray(frames)) {
+    throw new TypeError("Theme frames must be an array.");
+  }
+  if (!isPlainObject(frame)) {
+    throw new TypeError("Theme frame must be a plain object.");
+  }
+  return freezeOwned([
+    ...frames.filter(current => current.owner !== frame.owner),
+    frame
+  ]);
+}
+
+export function removeThemeFrameOwner(frames = [], owner) {
+  if (!Array.isArray(frames)) {
+    throw new TypeError("Theme frames must be an array.");
+  }
+  requireThemeOwner(owner);
+  const next = frames.filter(frame => frame.owner !== owner);
+  return freezeOwned({
+    frames: freezeOwned(next),
+    removed: next.length !== frames.length
+  });
+}
+
+export function moveLocalThemeScope(localOrder = [], scope) {
+  if (!Array.isArray(localOrder)) {
+    throw new TypeError("Theme localOrder must be an array.");
+  }
+  requireThemeScope(scope);
+  return freezeOwned([
+    ...localOrder.filter(current => current !== scope),
+    scope
+  ]);
+}
+
+function ownCanonicalThemeState(state, composition) {
+  const frames = ownArray(state.frames);
+  const localOrder = ownArray(state.localOrder);
+  const overrides = ownArray(state.overrides);
+  const result = { frames, localOrder, overrides };
+  if (composition || state.descendantFrames !== undefined) {
+    result.descendantFrames = ownArray(state.descendantFrames);
+  }
+  return cloneAndFreeze(result);
+}
+
+export function normalizeThemeState(state, { composition = false } = {}) {
+  if (state === undefined) {
+    return freezeOwned({
+      frames: freezeOwned([]),
+      ...(composition ? { descendantFrames: freezeOwned([]) } : {}),
+      localOrder: freezeOwned([]),
+      overrides: freezeOwned([])
+    });
+  }
+  if (!isPlainObject(state)) {
+    throw new TypeError("Program theme state must be a plain object.");
+  }
+  if (Array.isArray(state.frames)) {
+    return ownCanonicalThemeState(state, composition);
+  }
+
+  const name = state.name ?? "light";
+  const tokens = state.tokens ?? {};
+  const scope = state.scope ?? "self";
+  const origin = state.origin?.ownerCompositionId;
+  const owner = origin === undefined
+    ? LOCAL_THEME_OWNER
+    : compositionThemeOwner(origin, "descendants");
+  const frame = createThemeFrame({
+    owner,
+    scope,
+    definition: { base: name, tokens }
+  });
+  return freezeOwned({
+    frames: freezeOwned([frame]),
+    ...(composition && scope === "descendants"
+      ? { descendantFrames: freezeOwned([frame]) }
+      : composition
+        ? { descendantFrames: freezeOwned([]) }
+        : {}),
+    localOrder: origin === undefined ? freezeOwned([scope]) : freezeOwned([]),
+    overrides: cloneAndFreeze(state.overrides ?? [])
+  });
+}
+
+export function resolveEffectiveThemeFrame(state) {
+  const frames = state?.frames;
+  return Array.isArray(frames) ? frames.at(-1) : undefined;
+}
+
+export function resolveEffectiveThemeTokens(state) {
+  const frame = resolveEffectiveThemeFrame(state);
+  return frame === undefined
+    ? resolveThemeTokens("light")
+    : resolveThemeTokens({ base: frame.name, tokens: frame.tokens });
+}
+
+export function setThemeStateOverrides(state, overrides) {
+  if (!Array.isArray(overrides)) {
+    throw new TypeError("Theme overrides must be an array.");
+  }
+  return freezeOwned({
+    ...state,
+    overrides: cloneAndFreeze([...overrides].sort())
+  });
+}

package/src/actions/titles/actions.js

@@ -1,3 +1,4 @@
+import { withGuideLayoutValidation } from "../../materialization/guides/layout.js";
 import { action } from "../../core/action.js";
 import { noOptions } from "../../core/validation.js";
 import {
@@ -92,7 +93,7 @@ function titleTextAction(kind, create) {
   return action({
     op,
     description: `${create ? "Create" : "Rematerialize"} chart ${kind} text.`
-  }, function (args = {}) {
+  }, withGuideLayoutValidation(function (args = {}) {
     noOptions(args, op);
     const config = requireTitleConfig(this);
     if (create && this.graphicSpec.objects[id] !== undefined) {
@@ -111,7 +112,7 @@ function titleTextAction(kind, create) {
       ...(component.lines.length > 1 ? { length: component.lines.length } : {}),
       ...resolveCanvasGraphicPlacement(this)
     })[`edit${suffix}`]();
-  });
+  }));
 }
 
 export const editTitleText = titleTextAction("title", false);
@@ -121,7 +122,7 @@ export const createSubtitleText = titleTextAction("subtitle", true);
 
 export const rematerializeTitle = action(
   { op: "rematerializeTitle", description: "Rematerialize chart title graphics." },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     noOptions(args, "rematerializeTitle");
     requireTitleConfig(this);
     if (this.graphicSpec.objects.chartTitle?.type !== "text") {
@@ -138,7 +139,7 @@ export const rematerializeTitle = action(
       next = next.editGraphics({ target: "chartSubtitle", remove: true });
     }
     return next;
-  }
+  })
 );
 
 export const createTitle = action(
@@ -147,7 +148,7 @@ export const createTitle = action(
     description: "Create a chart title and optional subtitle.",
     scope: "any"
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     assertTitleScope(this, "createTitle");
     const options = normalizeTitleOptions(args);
     if (Object.keys(this.semanticSpec.title).length > 0) {
@@ -172,7 +173,7 @@ export const createTitle = action(
     next = next.createTitleText();
     if (subtitle !== undefined) next = next.createSubtitleText();
     return next;
-  }
+  })
 );
 
 export const editTitle = action(
@@ -181,7 +182,7 @@ export const editTitle = action(
     description: "Edit one stable chart title resource.",
     scope: "any"
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     assertTitleScope(this, "editTitle");
     if (this.semanticSpec.title.text === undefined) {
       throw new Error("editTitle requires an existing chart title.");
@@ -210,7 +211,7 @@ export const editTitle = action(
     }
     resolveTitleLayout(next, normalized.config);
     return next.rematerializeTitle();
-  }
+  })
 );
 
 export const removeTitle = action(
@@ -219,7 +220,7 @@ export const removeTitle = action(
     description: "Remove the complete chart title resource.",
     scope: "any"
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     assertTitleScope(this, "removeTitle");
     noOptions(args, "removeTitle");
     if (
@@ -246,5 +247,5 @@ export const removeTitle = action(
     return next.compositionSpec?.type === "facet"
       ? next.materializeComposition()
       : next;
-  }
+  })
 );

package/src/actions/titles/resolve.js

@@ -7,12 +7,10 @@ import {
   validatePositiveFinite
 } from "../../core/validation.js";
 import { resolveGraphicBounds } from "../../layout/canvas.js";
-import { resolveConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
 import {
   alignedTextAnchor,
   alignedTitleAnchor,
   buildTitleReadingBlock,
-  layoutBoundsIntersect,
   resolveTitleComponentBounds,
   unionTitleBounds
 } from "../../layout/title.js";
@@ -176,35 +174,7 @@ export function requireTitleConfig(program) {
   return program.titleConfig;
 }
 
-function reservedGraphicIds(program, position) {
-  const ids = [];
-  const axisChannel = ["top", "bottom"].includes(position) ? "x" : "y";
-  const axis = program.guideConfigs.axis?.[axisChannel];
-  if (axis && Object.values(axis).some(config => config?.position === position)) {
-    const prefix = axisChannel === "x" ? "xAxis" : "yAxis";
-    ids.push(`${prefix}Line`, `${prefix}Ticks`, `${prefix}Labels`, `${prefix}Title`);
-  }
-  const prefixes = {
-    series: "seriesLegend",
-    color: "colorLegend",
-    gradient: "colorGradient",
-    opacity: "opacityLegend"
-  };
-  for (const [kind, config] of Object.entries(program.guideConfigs.legend ?? {})) {
-    if (config?.position !== position || prefixes[kind] === undefined) continue;
-    ids.push(...Object.keys(program.graphicSpec.objects).filter(
-      id => id.startsWith(prefixes[kind])
-    ));
-    if (kind === "series" && program.guideConfigs.legend?.size !== undefined) {
-      ids.push(...Object.keys(program.graphicSpec.objects).filter(
-        id => id.startsWith("sizeLegend")
-      ));
-    }
-  }
-  return [...new Set(ids)];
-}
-
-function validateLayout(program, position, titleBounds, plot, canvas) {
+function validateLayout(position, titleBounds, plot, canvas) {
   if (
     titleBounds.left < 0 || titleBounds.top < 0 ||
     titleBounds.right > canvas.width || titleBounds.bottom > canvas.height
@@ -220,14 +190,6 @@ function validateLayout(program, position, titleBounds, plot, canvas) {
   if (!outsidePlot) {
     throw new Error(`Chart title requires more ${position}-margin space.`);
   }
-  for (const id of reservedGraphicIds(program, position)) {
-    const bounds = program.graphicSpec.objects[id] === undefined
-      ? undefined
-      : resolveConcreteGraphicBounds(program.graphicSpec, id);
-    if (bounds !== undefined && layoutBoundsIntersect(titleBounds, bounds)) {
-      throw new Error(`Chart title and ${position} guides require more margin space.`);
-    }
-  }
 }
 
 export function resolveTitleLayout(program, config) {
@@ -293,7 +255,6 @@ export function resolveTitleLayout(program, config) {
       : [resolveTitleComponentBounds(subtitle, config.subtitleStyle)])
   ]);
   validateLayout(
-    program,
     config.position,
     titleBounds,
     plot,

package/src/actions/violinPlots/create.js

@@ -1,6 +1,8 @@
 import { action } from "../../core/action.js";
 import { validateOptionObject } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
 import {
   applyFacadeGuides,
   normalizeAppearance,
@@ -19,16 +21,16 @@ const OPTIONS = Object.freeze([
 ]);
 const POSITION_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
 const DENSITY_OPTIONS = Object.freeze([
-  "bandwidth", "extent", "steps", "kernel", "normalization", "width"
+  "bandwidth", "extent", "steps", "kernel", "normalization", "weight", "width", "side"
 ]);
 const WIDTH_OPTIONS = Object.freeze(["band", "resolve"]);
 const SPLIT_OPTIONS = Object.freeze(["field", "domain"]);
 const AREA_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth", "curve"
+  "fill", "opacity", "stroke", "strokeWidth", "curve",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 const CATEGORICAL_TYPES = Object.freeze(["nominal", "ordinal"]);
 const OPERATION = "createViolinPlot";
-const ROLE_ERROR = `${OPERATION} requires one categorical axis and one quantitative axis.`;
 
 function inferFieldType(dataset, encoding, label) {
   if (encoding.fieldType !== undefined) return encoding.fieldType;
@@ -44,7 +46,7 @@ function inferFieldType(dataset, encoding, label) {
   return values.every(Number.isFinite) ? "quantitative" : "nominal";
 }
 
-function normalizePosition(dataset, value, label) {
+export function normalizeViolinPosition(dataset, value, label) {
   const encoding = normalizeFieldEncoding(value, label);
   validateOptionObject(encoding, POSITION_OPTIONS, label);
   return {
@@ -53,6 +55,54 @@ function normalizePosition(dataset, value, label) {
   };
 }
 
+export function resolveViolinRoles(dataset, xValue, yValue, operation) {
+  const x = normalizeViolinPosition(dataset, xValue, `${operation} x`);
+  const y = normalizeViolinPosition(dataset, yValue, `${operation} y`);
+  const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
+  const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
+  const roleError = `${operation} requires one categorical axis and one quantitative axis.`;
+  if (xCategorical === yCategorical || (
+    x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
+  )) {
+    throw new Error(roleError);
+  }
+  const category = xCategorical ? x : y;
+  const value = xCategorical ? y : x;
+  if (value.fieldType !== "quantitative") throw new Error(roleError);
+  return {
+    x,
+    y,
+    category,
+    value,
+    orientation: xCategorical ? "vertical" : "horizontal",
+    densityChannel: xCategorical ? "x" : "y"
+  };
+}
+
+export function resolveViolinSplit(value, category, operation, { removable = false } = {}) {
+  if (removable && value === false) return undefined;
+  if (value === undefined) return undefined;
+  validateOptionObject(value, SPLIT_OPTIONS, `${operation} split`);
+  if (typeof value.field !== "string" || value.field.length === 0) {
+    throw new TypeError(`${operation} split.field must be a non-empty string.`);
+  }
+  const split = { ...value };
+  if (split.field === category.field) {
+    throw new Error(`${operation} split field must differ from its category field.`);
+  }
+  return split;
+}
+
+export function resolveViolinDensity(value, current = {}, operation = OPERATION) {
+  if (value !== undefined) {
+    validateOptionObject(value, DENSITY_OPTIONS, `${operation} density`);
+    if (value.width !== undefined) {
+      validateOptionObject(value.width, WIDTH_OPTIONS, `${operation} density.width`);
+    }
+  }
+  return { ...current, ...(value ?? {}) };
+}
+
 function axisGuideOptions(value, field) {
   if (value === false) return false;
   return {
@@ -95,31 +145,9 @@ export const createViolinPlot = action(
     });
     const data = resolveFacadeData(this, args.data, OPERATION);
     const dataset = findDataset(this, data);
-    const x = normalizePosition(dataset, args.x, `${OPERATION} x`);
-    const y = normalizePosition(dataset, args.y, `${OPERATION} y`);
-    const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
-    const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
-    if (xCategorical === yCategorical || (
-      x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
-    )) {
-      throw new Error(ROLE_ERROR);
-    }
-    const category = xCategorical ? x : y;
-    const value = xCategorical ? y : x;
-    if (value.fieldType !== "quantitative") {
-      throw new Error(ROLE_ERROR);
-    }
-    let split = args.split;
-    if (split !== undefined) {
-      validateOptionObject(split, SPLIT_OPTIONS, `${OPERATION} split`);
-      if (typeof split.field !== "string" || split.field.length === 0) {
-        throw new TypeError(`${OPERATION} split.field must be a non-empty string.`);
-      }
-      split = { ...split };
-    }
-    if (split?.field === category.field) {
-      throw new Error(`${OPERATION} split field must differ from its category field.`);
-    }
+    const roles = resolveViolinRoles(dataset, args.x, args.y, OPERATION);
+    const { x, y, category, value } = roles;
+    const split = resolveViolinSplit(args.split, category, OPERATION);
     const color = normalizeEncoding(args.color, `${OPERATION} color`);
     if (
       color !== undefined &&
@@ -129,18 +157,8 @@ export const createViolinPlot = action(
         `${OPERATION} color must encode its category or split field.`
       );
     }
-    const density = args.density === undefined ? {} : args.density;
-    if (args.density !== undefined) {
-      validateOptionObject(density, DENSITY_OPTIONS, `${OPERATION} density`);
-      if (density.width !== undefined) {
-        validateOptionObject(
-          density.width,
-          WIDTH_OPTIONS,
-          `${OPERATION} density.width`
-        );
-      }
-    }
-    const { width: densityWidth, ...densityOptions } = density;
+    const density = resolveViolinDensity(args.density);
+    const { width: densityWidth, side: densitySide, ...densityOptions } = density;
     const area = normalizeAppearance(
       args.area,
       AREA_OPTIONS,
@@ -174,18 +192,47 @@ export const createViolinPlot = action(
       source: data,
       field: value.field,
       groupBy: category.field,
-      densityChannel: xCategorical ? "x" : "y",
+      densityChannel: roles.densityChannel,
       ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
       ...(value.scale === undefined ? {} : { valueScale: value.scale }),
       ...densityOptions,
       placement: {
         type: "category",
+        ...(densitySide === undefined ? {} : { side: densitySide }),
         ...(densityWidth === undefined ? {} : { width: densityWidth }),
         ...(split === undefined ? {} : { split }),
         ...(category.scale === undefined ? {} : { scale: category.scale })
       }
     });
     if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
-    return applyFacadeGuides(next, guides);
+    next = applyFacadeGuides(next, guides, id, args.guides ?? {});
+    const transform = findDataset(next, findLayer(next, id).data).transform[0];
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      violinPlot: {
+        materialized: true,
+        source: data,
+        orientation: roles.orientation,
+        category: category.field,
+        categoryType: category.fieldType,
+        value: value.field,
+        split: transform.placement.split,
+        density: {
+          bandwidth: transform.bandwidth,
+          extent: transform.extent,
+          steps: transform.steps,
+          kernel: transform.kernel,
+          normalization: transform.normalization,
+          ...(transform.weight === undefined ? {} : { weight: transform.weight }),
+          width: transform.placement.width,
+          side: transform.placement.side
+        },
+        colorRole: color === undefined
+          ? undefined
+          : color.field === category.field
+            ? "category"
+            : color.field === split?.field ? "split" : undefined
+      }
+    });
   }
 );