ggaction 0.0.22 → 0.0.24

package/src/persistence/validation.js

@@ -1,3 +1,6 @@
+import { validateFacetAxisPolicy } from "../core/facetAxisPolicy.js";
+import { resolveFacetFamily } from "../grammar/facets/dependencies.js";
+import { validateRegressionPlacement } from "../grammar/regression/parameters.js";
 import { validateGraphicClip } from "../grammar/schemas/graphicClip.js";
 import { validatePointShape } from "../grammar/pointShapes.js";
 import {deriveLookupRows,sameLookupValue} from "../grammar/lookup.js";
@@ -27,7 +30,8 @@ import { isContinuousSizeScaleType } from "../grammar/scales/size.js";
 import { validateGraphicItemLimit } from "../core/validation.js";
 import { LEGEND_TITLE_STYLE_KEYS, validateLegendTitleAlignment } from "../grammar/legendTitleStyle.js";
 import { validateGuideDash, normalizeGuideDashMap } from "../grammar/guideDash.js";
-import { validateAxisTextPlacement } from "../grammar/axisTextPlacement.js";
+import { validateAxisLabelFlushThreshold, validateAxisTextPlacement,
+  axisLabelHasText } from "../grammar/axisTextPlacement.js";
 import { validateTickSelectionRounding, axisTickSelection } from "../grammar/ticks.js";
 import { validateAreaPaintConfig } from "../grammar/areaPaint.js";
 import { validateOptionObject, validateKeys, validatePositiveFinite, validateNonNegativeFinite, validateNonEmptyString, validateGeneratedItemLimit } from "../core/validation.js";
@@ -215,6 +219,8 @@ export function validateProgramState(program, path, { allowMissingLookupSchemas
     validateAuthoredFacetLegend(program, program.compositionSpec.facet.guides.legend);
   }
   if (program.compositionSpec?.type === "facet") {
+    validateFacetAxisPolicy(program.compositionSpec.facet.guides.axes,
+      resolveFacetFamily(program.semanticSpec).family, program.compositionSpec.facet.repeat !== undefined);
     const headers = program.materializationConfigs.facets?.[program.compositionSpec.id]?.headers;
     if (headers !== undefined) validateFacetHeaderRotations(headers);
     if (headers?.row?.title !== undefined && program.compositionSpec.facet.grid === undefined) {
@@ -231,6 +237,23 @@ export function validateProgramState(program, path, { allowMissingLookupSchemas
   }
   const cartesianOwners = cartesianAxisOwners(program);
   for (const [id, axis] of Object.entries(program.guideConfigs.axis ?? {})) {
+    if (isPlainObject(axis?.title?.offset)) {
+      if (!cartesianOwners.some(owner => owner.id === id)) throw invalidSnapshot("Relative title offset requires a Cartesian axis owner.", path);
+      validateAxisTextPlacement(axis.title, { title: true });
+      if (axis.title.inferredOffset === true) throw invalidSnapshot("Relative title offset cannot be inferred.", path);
+      const owner = cartesianOwners.find(owner => owner.id === id);
+      const labels = program.graphicSpec.objects[axisGraphicIds(owner.channel, id)[2]];
+      // Composition parents retain source intent, not local unit graphics.
+      // Their retained unit/children are validated through the same unit rule.
+      if (axis.labels?.position !== axis.title.position || (program.compositionSpec === undefined &&
+          !(labels?.items ?? (labels ? [labels] : [])).some(item => axisLabelHasText(item.properties)))) {
+        throw invalidSnapshot("Relative title offset requires nonempty same-side labels.", path);
+      }
+    }
+    if (axis?.labels?.flushThreshold !== undefined) {
+      if (!cartesianOwners.some(owner => owner.id === id)) throw invalidSnapshot("Label flushThreshold requires a Cartesian axis owner.", path);
+      validateAxisLabelFlushThreshold(axis.labels.flushThreshold);
+    }
     for (const config of [axis?.ticks, axis?.labels]) {
       if (config === undefined || !Object.hasOwn(config, "rounding")) continue;
       if (!cartesianOwners.some(owner => owner.id === id)) {
@@ -463,6 +486,7 @@ export function validateProgramState(program, path, { allowMissingLookupSchemas
     }
   }
   for (const id of Object.keys(program.markConfigs)) {
+    validateRegressionPlacement(program.markConfigs[id].regression?.placement);
     requestedMarkClip(program.markConfigs[id]);
     validateMarkClipCoordinate(program, resources.get("mark").get(id), program.markConfigs[id].clip);
     if (!resources.get("mark").has(id)) throw invalidSnapshot(`Mark config "${id}" has no layer owner.`, path);

package/src/version.js

@@ -1,2 +1,2 @@
 // Must match package.json; enforced by the snapshot producer-version test.
-export const packageVersion = "0.0.22";
+export const packageVersion = "0.0.24";

package/types/basic.d.ts

@@ -10,11 +10,13 @@ export type {
   CartesianGuideDashMap,
   AxisTicksAndLabelsOptions,
   AxisTitleOptions,
+  AxisTitleOffset,
   DisplayLabelMap,
   DisplayLabelOptions,
   ApplyThemeOptions,
   BarWidthOptions,
   BasicSeriesLayoutOptions,
+  Bin2DAssignment,
   Bin2DDataOptions,
   CanvasOptions,
   ColorEncodingOptions,

package/types/index.d.ts

@@ -27,6 +27,7 @@ export type {
   AxisTicksAndLabelsOptions,
   AxisTickStyleOptions,
   AxisTitleOptions,
+  AxisTitleOffset,
   AxisValue,
   DisplayLabelMap,
   DisplayLabelOptions,
@@ -36,6 +37,7 @@ export type {
   BinnedHeatmapColorOptions,
   BinnedHeatmapOptions,
   BinnedHeatmapPositionChannel,
+  Bin2DAssignment,
   Bin2DCounts,
   Bin2DDataOptions,
   Bin2DExtent,
@@ -287,6 +289,7 @@ export type {
   FieldType,
   FillPaint,
   FacetCompositionSpec,
+  FacetGap,
   FacetGuideOptions,
   FacetOptions,
   FacetTopLaneMode,

package/types/program.d.ts

@@ -100,6 +100,7 @@ export type CurveInterpolation =
   | "basis"
   | "cardinal"
   | "monotone"
+  | "monotone-steffen"
   | "natural";
 export type DashStyle = "solid" | "dashed" | "dotted" | "dashdot";
 export type DashPattern = readonly number[];
@@ -163,13 +164,15 @@ export interface CompositionOptions {
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
 }
+/** Facets may set independent axis gaps; concat continues to require a number. */
+export type FacetGap = number | Readonly<{ x: number; y: number }>;
 export interface EditCompositionLayoutOptions {
   columns?: number;
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
-  /** Interpret gap between child canvases (default) or inner plot regions. */
-  spacing?: "canvas" | "plot";
+  /** Interpret gap between child canvases (default), inner plots, or retained full content (wrapped facets). */
+  spacing?: "canvas" | "plot" | "content";
   /** Share existing top margin with parent title and headers; requires plot spacing. Stacked restores the default. */
   topLane?: FacetTopLaneMode;
 }
@@ -213,7 +216,7 @@ interface StoredFacetLegendIntent {
   readonly groups: Readonly<Record<string, unknown>>;
 }
 export interface FacetGuideOptions {
-  axes?: "each" | "outer";
+  axes?: "each" | "outer" | { x?: "each" | "outer"; y?: "each" | "outer" };
   legend?: false | "shared" | LegendOptions;
 }
 export interface FacetOptions {
@@ -223,14 +226,14 @@ export interface FacetOptions {
   data?: string;
   values?: readonly DatasetScalar[];
   columns?: number;
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
   guides?: FacetGuideOptions;
   headers?: FacetHeadersOptions;
-  /** Interpret gap between child canvases (default) or inner plot regions. */
-  spacing?: "canvas" | "plot";
+  /** Interpret gap between child canvases (default), inner plots, or retained full content (wrapped facets). */
+  spacing?: "canvas" | "plot" | "content";
   /** Share the existing top margin rather than adding title/header reservations. Requires plot spacing. */
   topLane?: FacetTopLaneMode;
 }
@@ -244,13 +247,13 @@ export interface FacetGridOptions {
   rows: FacetGridRole;
   columns: FacetGridRole;
   combinations?: "observed" | "full";
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
   guides?: FacetGuideOptions;
   headers?: FacetHeadersOptions;
-  /** Interpret gap between child canvases (default) or inner plot regions. */
+  /** Interpret gap between child canvases (default), inner plots, or retained full content (wrapped facets). */
   spacing?: "canvas" | "plot";
   /** Share the existing top margin rather than adding title/header reservations. Requires plot spacing. */
   topLane?: FacetTopLaneMode;
@@ -261,14 +264,14 @@ export interface RepeatChartsOptions {
   channel: "x" | "y" | "theta" | "r" | { parallelDimension: string };
   fields: readonly [string, ...string[]];
   columns?: number;
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
   guides?: FacetGuideOptions;
   headers?: FacetHeadersOptions;
-  /** Interpret gap between child canvases (default) or inner plot regions. */
-  spacing?: "canvas" | "plot";
+  /** Interpret gap between child canvases (default), inner plots, or retained full content (wrapped facets). */
+  spacing?: "canvas" | "plot" | "content";
   /** Share the existing top margin rather than adding title/header reservations. Requires plot spacing. */
   topLane?: FacetTopLaneMode;
 }
@@ -294,7 +297,7 @@ export interface EditFacetHeadersOptions {
   color?: string;
   offset?: number;
   /** Content follows concrete mark bounds with plot spacing; plot preserves existing placement. */
-  anchor?: "plot" | "content";
+  anchor?: "plot" | "content" | "view";
   role?: FacetHeaderRole;
   labelMap?: DisplayLabelMap | "auto";
   side?: FacetHeaderSide;
@@ -324,10 +327,10 @@ export interface FacetCompositionSpec {
   readonly type: "facet";
   readonly children: readonly string[];
   readonly columns: number;
-  readonly spacing?: "canvas" | "plot";
+  readonly spacing?: "canvas" | "plot" | "content";
   /** Canonical opt-in intent; stacked is represented by omission. */
   readonly topLane?: "shared";
-  readonly gap: number;
+  readonly gap: FacetGap;
   readonly align: CompositionAlign;
   readonly padding: Readonly<Required<CompositionPadding>>;
   readonly facet: {
@@ -354,7 +357,7 @@ export interface FacetCompositionSpec {
     };
     readonly scales: Readonly<Required<FacetScaleResolutions>>;
     readonly guides: {
-      readonly axes: "each" | "outer";
+      readonly axes: "each" | "outer" | { readonly x: "each" | "outer"; readonly y: "each" | "outer" };
       readonly legend: false | "shared" | Readonly<LegendOptions> | StoredFacetLegendIntent;
     };
   };
@@ -735,6 +738,7 @@ export type TimeUnit =
   | "week"
   | "weekday";
 type DatasetTimeUnitTransformBase = {
+  readonly missing?: "error" | "null";
   readonly type: "timeUnit";
   readonly field: string;
   readonly temporalUnit?: TemporalInputUnit;
@@ -753,6 +757,7 @@ export type DatasetTimeUnitTransform = DatasetTimeUnitTransformBase & (
       readonly weekRule: "calendar" | "iso";
     }
 );
+export type Bin2DAssignment = "edges" | "step";
 export interface Bin2DCounts {
   x: number;
   y: number;
@@ -779,6 +784,7 @@ export interface DatasetBin2DOutputFields {
 }
 export interface DatasetBin2DTransform {
   readonly type: "bin2d";
+  readonly assignment?: "step";
   readonly x: string;
   readonly y: string;
   readonly bins: Readonly<Bin2DCounts>;
@@ -1467,6 +1473,8 @@ export interface CartesianAxisLabelStyleOptions extends AxisLabelStyleOptions {
   colorMap?: CartesianAxisLabelColorMap | "auto";
   /** Keep unrotated label bounds inside the mapped axis span; defaults to false. */
   flush?: boolean;
+  /** Only flush mapped ticks within this non-negative distance of a range edge. Auto restores all-label containment. */
+  flushThreshold?: number | "auto";
   /** Signed displacement from the mapped tick position, independent of outward offset. */
   alongOffset?: number;
 }
@@ -1492,6 +1500,7 @@ export interface AxisTicksAndLabelsOptions<P extends string> {
   ticks?: CartesianAxisTickStyleOptions;
   labels?: CartesianAxisLabelStyleOptions & AxisLabelLayoutOptions & DisplayLabelOptions;
 }
+export type AxisTitleOffset = number | Readonly<{ from: "labels"; gap: number }>;
 export interface AxisTitleOptions<P extends string> {
   /** Axis resource identity; omission prefers canonical, then a unique named owner. */
   target?: string;
@@ -1506,8 +1515,8 @@ export interface AxisTitleOptions<P extends string> {
   scale?: string;
   position?: P;
   at?: "start" | "center" | "end" | number;
-  /** Signed distance from the axis frame: positive outward, negative inward. */
-  offset?: number;
+  /** Signed distance from the axis frame, or a nonnegative gap outside same-owner labels. */
+  offset?: AxisTitleOffset;
   rotation?: RotationInput;
   color?: string;
   fontSize?: number;
@@ -2496,6 +2505,8 @@ export interface ECDFDataOptions {
 }
 
 type TimeUnitDataBaseOptions = {
+  /** Preserve null or absent inputs as null buckets; defaults to strict errors. */
+  missing?: "error" | "null";
   id: string;
   source?: string;
   field: string;
@@ -2669,6 +2680,7 @@ export interface Bin2DDataOptions {
   y: string;
   bins?: number | Bin2DCounts;
   extent?: Bin2DExtent;
+  assignment?: "edges" | "step";
   includeEmpty?: boolean;
   members?: boolean;
   as?: Bin2DOutputFields;
@@ -2681,6 +2693,7 @@ export interface EditBin2DDataOptions {
   y?: string;
   bins?: number | Bin2DCounts;
   extent?: Bin2DExtent;
+  assignment?: "edges" | "step";
   includeEmpty?: boolean;
   members?: boolean;
   as?: DatasetBin2DOutputFields;
@@ -4039,6 +4052,7 @@ export interface BinnedHeatmapColorOptions {
 export interface HeatmapBinOptions {
   bins?: number | Bin2DCounts;
   extent?: Bin2DExtent;
+  assignment?: "edges" | "step";
   includeEmpty?: boolean;
 }
 
@@ -4800,6 +4814,7 @@ export interface EditRegressionStatisticsDataOptions {
 }
 
 type RegressionCommonOptions = {
+  placement?: "source" | "plot-last";
   target?: string;
   x?: string;
   y?: string;
@@ -4825,6 +4840,7 @@ export type RegressionOptions = RegressionCommonOptions & (
 );
 
 export interface EditRegressionOptions {
+  placement?: "source" | "plot-last";
   target?: string;
   data?: string;
   x?: string;
@@ -5187,6 +5203,8 @@ export interface TitleOptions {
   maxWidth?: number;
   wrap?: "word" | "character";
   lineHeight?: number;
+  /** Subtitle-only line spacing; overrides lineHeight without requiring maxWidth. */
+  subtitleLineHeight?: number;
   titleStyle?: TitleTextStyleOptions;
   subtitleStyle?: TitleTextStyleOptions;
 }