ggaction 0.0.15 → 0.0.17

package/src/selectors/datasets.js

@@ -1,3 +1,5 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findDataset(program, id) {
   return program.semanticSpec.datasets.find(dataset => dataset.id === id);
 }
@@ -20,7 +22,7 @@ export function hasDatasetOwner(program, id) {
 export function resolveDatasetReference(program, id, label = "Dataset") {
   const matches = currentOwnerMatches(program, id);
   if (matches.length > 1) {
-    throw new Error(`${label} logical owner "${id}" is ambiguous.`);
+    throw annotateError(new Error(`${label} logical owner "${id}" is ambiguous.`), { code: "ambiguous-resource", resourceId: id, candidates: matches.map(match => match.current) });
   }
   const resolved = matches.length === 1 ? matches[0].current : id;
   const dataset = findDataset(program, resolved);
@@ -28,7 +30,7 @@ export function resolveDatasetReference(program, id, label = "Dataset") {
     const kind = label.toLowerCase().includes("source")
       ? "source dataset"
       : "dataset";
-    throw new Error(`Unknown ${kind} "${id}" does not exist.`);
+    throw annotateError(new Error(`Unknown ${kind} "${id}" does not exist.`), { code: "missing-resource", resourceId: id });
   }
   return dataset;
 }
@@ -43,19 +45,19 @@ export function findDatasetConsumer(program, source) {
 
 export function requireDataset(program, id, label = `Dataset "${id}"`) {
   const dataset = findDataset(program, id);
-  if (dataset === undefined) throw new Error(`${label} does not exist.`);
+  if (dataset === undefined) throw annotateError(new Error(`${label} does not exist.`), { code: "missing-resource", resourceId: id });
   return dataset;
 }
 
 export function requireMaterializedDataset(program, id) {
   const dataset = resolveDatasetReference(program, id, "Dataset");
-  if (dataset === undefined) throw new Error(`Unknown dataset "${id}".`);
+  if (dataset === undefined) throw annotateError(new Error(`Unknown dataset "${id}".`), { code: "missing-resource", resourceId: id });
   if (!Array.isArray(dataset.values)) {
-    throw new Error(
+    throw annotateError(new Error(
       `Dataset "${id}" requires materialized values. ` +
       "createDerivedData stores a definition only; use the corresponding " +
       "value-producing data action before creating a chart or mark."
-    );
+    ), { code: "incompatible-resource", resourceId: id });
   }
   return dataset;
 }

package/src/selectors/layers.js

@@ -1,3 +1,5 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findLayer(program, id) {
   return program.semanticSpec.layers.find(layer => layer.id === id);
 }
@@ -12,7 +14,7 @@ export function hasLayer(program, id) {
 
 export function requireLayer(program, id, label = `Layer "${id}"`) {
   const layer = findLayer(program, id);
-  if (layer === undefined) throw new Error(`${label} does not exist.`);
+  if (layer === undefined) throw annotateError(new Error(`${label} does not exist.`), { code: "missing-resource", resourceId: id });
   return layer;
 }
 
@@ -26,12 +28,12 @@ export function resolveEligibleLayer(program, {
   const candidates = program.semanticSpec.layers.filter(predicate);
   if (target !== undefined) {
     const selected = candidates.find(layer => layer.id === target);
-    if (selected === undefined) throw new Error(`Unknown ${label} ${targetOption} "${target}".`);
+    if (selected === undefined) throw annotateError(new Error(`Unknown ${label} ${targetOption} "${target}".`), { code: findLayer(program, target) ? "incompatible-resource" : "missing-resource", resourceId: target, optionPath: targetOption });
     return selected;
   }
   const selected = candidates.find(layer => layer.id === current);
   if (selected !== undefined) return selected;
   if (candidates.length === 1) return candidates[0];
-  if (candidates.length === 0) throw new Error(`${label} requires an eligible layer.`);
-  throw new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`);
+  if (candidates.length === 0) throw annotateError(new Error(`${label} requires an eligible layer.`), { code: "missing-resource", optionPath: targetOption });
+  throw annotateError(new Error(`${label} ${targetOption} is ambiguous; provide ${targetOption}.`), { code: "ambiguous-resource", optionPath: targetOption, candidates: candidates.map(layer => layer.id) });
 }

package/src/selectors/markOwners.js

@@ -0,0 +1,46 @@
+import { findLayer } from "./layers.js";
+
+export function ownedChildren(program, id) {
+  const config = program.markConfigs[id] ?? {};
+  return [
+    config.errorBar?.lowerCapId,
+    config.errorBar?.upperCapId,
+    config.errorBand?.lowerBoundaryId,
+    config.errorBand?.upperBoundaryId,
+    config.regression?.bandId,
+    config.regression?.lineId,
+    config.boxPlot?.whiskerId,
+    config.boxPlot?.medianId,
+    config.boxPlot?.outlierId,
+    config.gradientPlot?.centerId,
+    config.intervalPlot?.intervalId,
+    config.endpointPlot?.roles?.stemId,
+    config.endpointPlot?.roles?.startId,
+    config.endpointPlot?.roles?.connectorId,
+    ...(config.raincloudPlot?.ownedChildIds ?? [])
+  ].concat(
+    program.semanticSpec.layers
+      .filter(layer => layer.source === id)
+      .map(layer => layer.id)
+  ).concat(
+    program.semanticSpec.layers
+      .filter(layer =>
+        program.markConfigs[layer.id]?.statisticalReference?.source === id
+      )
+      .map(layer => layer.id)
+  ).filter(child => child !== undefined && child !== id && findLayer(program, child) !== undefined);
+}
+
+export function ownership(program) {
+  const ownerByChild = new Map();
+  for (const layer of program.semanticSpec.layers) {
+    for (const child of ownedChildren(program, layer.id)) {
+      if (program.markConfigs[child]?.statisticalReference !== undefined) {
+        continue;
+      }
+      ownerByChild.set(child, layer.id);
+    }
+  }
+  return ownerByChild;
+}
+

package/src/selectors/scales.js

@@ -1,21 +1,23 @@
+import { annotateError } from "../core/diagnostics.js";
+
 export function findSemanticScale(program, id) {
   return program.semanticSpec.scales.find(scale => scale.id === id);
 }
 
 export function requireSemanticScale(program, id) {
   const scale = findSemanticScale(program, id);
-  if (scale === undefined) throw new Error(`Unknown scale "${id}".`);
+  if (scale === undefined) throw annotateError(new Error(`Unknown scale "${id}".`), { code: "missing-resource", resourceId: id });
   return scale;
 }
 
 export function requireResolvedScale(program, id, type) {
-  const scale = program.resolvedScales[id];
+  const scale = Object.hasOwn(program.resolvedScales, id) ? program.resolvedScales[id] : undefined;
   if (scale === undefined || (type !== undefined && scale.type !== type)) {
-    throw new Error(
+    throw annotateError(new Error(
       type === undefined
         ? `Unknown resolved scale "${id}".`
         : `Expected resolved ${type} scale "${id}".`
-    );
+    ), { code: scale === undefined ? "missing-resource" : "incompatible-resource", resourceId: id });
   }
   return scale;
 }

package/src/theme/defaults.js

@@ -1,4 +1,5 @@
-export const DEFAULT_FONT_FAMILY = "sans-serif";
+import { DEFAULT_FONT_FAMILY } from "../core/font.js";
+export { DEFAULT_FONT_FAMILY };
 
 export const DEFAULT_POINT_RADIUS = 3;
 

package/src/version.js

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

package/types/accessibility.d.ts

@@ -0,0 +1,37 @@
+import type { ChartProgram } from "./program.js";
+import type { BasicChartProgram } from "./basic.js";
+
+export interface AccessibleColumn {
+  readonly key: string;
+  readonly role: string;
+  readonly component: string;
+  readonly field?: string;
+  readonly aggregate?: string;
+  readonly unit?: "utc-milliseconds";
+}
+export interface AccessibleRow {
+  readonly component: string;
+  readonly series: Readonly<Record<string, unknown>>;
+  readonly values: Readonly<Record<string, unknown>>;
+}
+export interface AccessibleOwnerView {
+  readonly ownerId: string;
+  readonly markType: string;
+  readonly columns: readonly AccessibleColumn[];
+  readonly rows: readonly AccessibleRow[];
+  readonly units: Readonly<Record<string, "utc-milliseconds">>;
+}
+export interface AccessibleChildView {
+  readonly ownerId: string;
+  readonly kind: "composition-child";
+  readonly title: string | null;
+  readonly facet?: Readonly<Record<string, unknown>>;
+  readonly views: readonly AccessibleView[];
+}
+export type AccessibleView = AccessibleOwnerView | AccessibleChildView;
+export interface AccessibleData {
+  readonly schemaVersion: 1;
+  readonly title: string | null;
+  readonly views: readonly AccessibleView[];
+}
+export function exportAccessibleData(program: ChartProgram | BasicChartProgram, options?: { readonly target?: string }): AccessibleData;

package/types/basic.d.ts

@@ -1,4 +1,4 @@
-import type { ChartProgram, BasicSeriesLayoutOptions } from "./program.js";
+import type { ChartProgram, BasicSeriesLayoutOptions, CreateDataOptions } from "./program.js";
 
 export type {
   AxisLabelOptions,
@@ -17,6 +17,7 @@ export type {
   CompleteAxisOptions,
   CreateAxesOptions,
   CreateBarPlotOptions,
+  CreateDataOptions,
   CreateGridOptions,
   CreateGuidesOptions,
   CreateHeatmapOptions,
@@ -111,7 +112,8 @@ type RebindMethod<T> = T extends (...args: infer Args) => ChartProgram
 
 export type BasicChartProgram =
   Pick<ChartProgram, BasicStateKey> &
-  { readonly [Key in BasicMethodKey]: RebindMethod<ChartProgram[Key]> } &
+  { readonly [Key in Exclude<BasicMethodKey, "createData">]: RebindMethod<ChartProgram[Key]> } &
+  { createData<Row extends object>(options: CreateDataOptions<Row>): BasicChartProgram } &
   { readonly layoutSeries: (options: BasicSeriesLayoutOptions) => BasicChartProgram };
 
 export function chart(): BasicChartProgram;

package/types/diagnostics.d.ts

@@ -0,0 +1,15 @@
+export type ErrorCode = "invalid-option" | "invalid-value" | "missing-resource" |
+  "ambiguous-resource" | "incompatible-resource" | "resource-in-use" |
+  "resource-limit" | "unsupported-format" | "action-failed";
+
+export interface ErrorDetails {
+  readonly code: ErrorCode;
+  readonly operation?: string;
+  readonly optionPath?: string;
+  readonly resourceId?: string;
+  readonly candidates?: readonly string[];
+  readonly limit?: number;
+  readonly actual?: number;
+}
+
+export function getErrorDetails(error: unknown): ErrorDetails | undefined;

package/types/index.d.ts

@@ -1,6 +1,11 @@
 import type { ChartProgram, CompositionOptions } from "./program.js";
 
 export type {
+  TextMetricFontWeight,
+  TextMeasurement,
+  TextMetricsProfile,
+  ApplyTextMetricsOptions,
+  ReviseDataOptions,
   ActionOptions,
   AxisFormat,
   AxisFormatString,

package/types/inspection.d.ts

@@ -0,0 +1,17 @@
+import type { BasicChartProgram } from "./basic.js";
+import type { ChartProgram, DatasetSchema } from "./program.js";
+export type ProgramInput = ChartProgram | BasicChartProgram;
+export interface ResourceRef { readonly kind: "data" | "mark" | "scale" | "coordinate" | "guide" | "canvas" | "composition"; readonly id: string; readonly childPath?: readonly string[]; }
+export interface InspectionTarget { readonly kind: "data" | "mark" | "scale" | "coordinate" | "guide"; readonly id: string; readonly childPath?: readonly string[]; }
+export interface Finding { readonly severity: "error" | "warning" | "info"; readonly code: string; readonly reason: string; readonly message: string; readonly resource?: ResourceRef; readonly optionPath?: string; }
+export interface CheckResult { readonly name: string; readonly status: "not_run" | "passed" | "failed" | "not_applicable"; readonly evidencePaths: readonly string[]; readonly findings: readonly Finding[]; }
+export interface ParameterDefinition { readonly path: string; readonly kind: "field" | "enum" | "number" | "string" | "boolean" | "range" | "array" | "object" | "resource"; readonly required: boolean; readonly active: boolean; readonly choices?: readonly (string | number | boolean | null)[]; readonly minimum?: number; readonly maximum?: number; readonly unit?: string; readonly fieldRole?: string; }
+export interface ActionDescription { readonly version: 1; readonly action: string; readonly applicability: "supported" | "needs-input" | "incompatible" | "unsupported" | "unverified"; readonly parameterDefinitions: readonly ParameterDefinition[]; readonly requirements: readonly { readonly reason: string; readonly optionPath?: string }[]; readonly checks: readonly CheckResult[]; readonly findings: readonly Finding[]; }
+export interface Change { readonly resource: ResourceRef; readonly operation: "add" | "remove" | "modify"; readonly effect: "data" | "binding" | "structure" | "scale" | "guide" | "style"; readonly roles: readonly string[]; }
+export interface ProgramComparison { readonly version: 1; readonly equivalence: "equal" | "different" | "unknown"; readonly completeProgramComparison: boolean; readonly changes: readonly Change[]; readonly affected: readonly ResourceRef[]; readonly findings: readonly Finding[]; }
+export interface OwnerInspection { readonly owner: ResourceRef; readonly grain: "item" | "series" | "composite" | "unknown"; readonly rawRows: number | null; readonly logicalDataItems: number | null; readonly drawablePrimitives: number | null; readonly visibleCandidates: number | null; readonly flags: readonly { readonly reason: "opacity-zero" | "zero-size" | "outside-clip" | "missing-skipped"; readonly count: number | null }[]; readonly bounds: Readonly<{x:number;y:number;width:number;height:number}> | null; readonly sourceRefs: readonly ResourceRef[]; readonly checks: readonly CheckResult[]; }
+export interface ProgramInspection { readonly version: 1; readonly views: readonly OwnerInspection[]; readonly calculations: readonly unknown[]; readonly checks: readonly CheckResult[]; readonly findings: readonly Finding[]; readonly coverage: Readonly<{partial:boolean;unsupported:readonly ResourceRef[]}>; }
+export function getDatasetSchema(program: ProgramInput, options: {readonly data:string;readonly childPath?:readonly string[]}): Readonly<{data:string;schema:DatasetSchema}>;
+export function describeAction(program: ProgramInput, options: {readonly action:string;readonly target?:InspectionTarget;readonly options?:Readonly<Record<string,unknown>>}): ActionDescription;
+export function comparePrograms(before: ProgramInput, after: ProgramInput, options?: {readonly target?:InspectionTarget}): ProgramComparison;
+export function inspectProgram(program: ProgramInput, options?: {readonly target?:InspectionTarget}): ProgramInspection;

package/types/pdf.d.ts

@@ -24,3 +24,12 @@ export function renderToPDF(
   program: Pick<ChartProgram, "graphicSpec">,
   options: PDFRenderOptions
 ): Promise<PDFRenderResult>;
+
+export interface PDFBufferResult extends Omit<PDFRenderResult, "output"> {
+  readonly buffer: Uint8Array;
+}
+
+export function renderToPDFBuffer(
+  program: Pick<ChartProgram, "graphicSpec">,
+  options?: { metadata?: PDFMetadata }
+): Promise<PDFBufferResult>;

package/types/persistence.d.ts

@@ -0,0 +1,7 @@
+import type { ChartProgram } from "./program.js";
+import type { BasicChartProgram } from "./basic.js";
+
+export function serializeProgram(program: ChartProgram | BasicChartProgram): string;
+export function deserializeProgram(text: string): ChartProgram;
+export function serializeGraphic(program: Pick<ChartProgram, "graphicSpec">): string;
+export function deserializeGraphic(text: string): Readonly<Pick<ChartProgram, "graphicSpec">>;

package/types/png.d.ts

@@ -12,3 +12,12 @@ export function renderToPNG(
   program: Pick<ChartProgram, "graphicSpec">,
   options: { output: string; pixelRatio?: number }
 ): Promise<PNGRenderResult>;
+
+export interface PNGBufferResult extends Omit<PNGRenderResult, "output"> {
+  readonly buffer: Uint8Array;
+}
+
+export function renderToPNGBuffer(
+  program: Pick<ChartProgram, "graphicSpec">,
+  options?: { pixelRatio?: number }
+): Promise<PNGBufferResult>;