ggaction 0.0.15 → 0.0.17

package/types/program.d.ts

@@ -1,6 +1,21 @@
 import type { RegisteredExtensionActions } from "./extension.js";
 
 export type TemporalInputUnit = "auto" | "year" | "timestamp";
+export type TextMetricFontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+export interface TextMeasurement {
+  readonly text: string;
+  readonly fontFamily: string;
+  readonly fontSize: number;
+  readonly fontWeight: TextMetricFontWeight;
+  readonly width: number;
+}
+export interface TextMetricsProfile {
+  readonly schemaVersion: 1;
+  readonly id: string;
+  readonly measurements: readonly TextMeasurement[];
+}
+export interface ApplyTextMetricsOptions { profile: TextMetricsProfile; }
+
 export type ThemeName = "light" | "dark";
 export interface ThemeTokens {
   background: string;
@@ -324,21 +339,29 @@ export type DensityPlacement =
 export type FilterComparison =
   | { op: "eq" | "neq"; value: unknown }
   | { op: "lt" | "lte" | "gt" | "gte"; value: number | string };
-export type FilterRange = {
-  min: number | string;
-  max: number | string;
-  inclusive?: boolean;
-};
+type FilterBound = number | string;
+type FilterRangeBounds =
+  | { min: FilterBound; max?: FilterBound }
+  | { min?: FilterBound; max: FilterBound };
+type FilterRangeClosure =
+  | { inclusive?: boolean; minInclusive?: never; maxInclusive?: never }
+  | { inclusive?: never; minInclusive?: boolean; maxInclusive?: boolean };
+export type FilterRange = FilterRangeBounds & FilterRangeClosure;
 export type FilterModeOptions =
-  | { oneOf: readonly unknown[]; predicate?: never; range?: never }
-  | { oneOf?: never; predicate: FilterComparison; range?: never }
-  | { oneOf?: never; predicate?: never; range: FilterRange };
+  | { oneOf: readonly [DatasetScalar, ...DatasetScalar[]]; noneOf?: never; predicate?: never; range?: never }
+  | { oneOf?: never; noneOf: readonly [DatasetScalar, ...DatasetScalar[]]; predicate?: never; range?: never }
+  | { oneOf?: never; noneOf?: never; predicate: FilterComparison; range?: never }
+  | { oneOf?: never; noneOf?: never; predicate?: never; range: FilterRange };
 export type FilterDataOptions = {
   id: string;
   source?: string;
   field: string;
+  nulls?: "include" | "exclude";
 } & FilterModeOptions;
 export type DatasetScalar = string | number | boolean | null;
+export type RegressionPredictOptions =
+  | { values: readonly [number, ...number[]]; domain?: never; steps?: never }
+  | { values?: never; domain: readonly [number, number]; steps: number };
 export type DisplayLabelMap = ReadonlyArray<Readonly<{
   value: DatasetScalar;
   label: string;
@@ -349,10 +372,12 @@ export interface DisplayLabelOptions {
 export type DatasetFilterTransform = {
   type: "filter";
   field: string;
+  nulls?: "include" | "exclude";
 } & (
-  | { oneOf: readonly DatasetScalar[]; predicate?: never; range?: never }
-  | { oneOf?: never; predicate: FilterComparison; range?: never }
-  | { oneOf?: never; predicate?: never; range: FilterRange }
+  | { oneOf: readonly DatasetScalar[]; noneOf?: never; predicate?: never; range?: never }
+  | { oneOf?: never; noneOf: readonly DatasetScalar[]; predicate?: never; range?: never }
+  | { oneOf?: never; noneOf?: never; predicate: FilterComparison; range?: never }
+  | { oneOf?: never; noneOf?: never; predicate?: never; range: FilterRange }
 );
 export type DatasetRegressionTransform = {
   type: "regression";
@@ -360,24 +385,22 @@ export type DatasetRegressionTransform = {
   y: string;
   groupBy?: string;
 } & (
-  | {
+  | ({
       method: "linear";
-      interval: "mean" | "prediction";
       degree?: never;
       span?: never;
-    } & (
+    } & ({ interval: false; confidenceMethod?: never; level?: never; confidence?: never } | ({ interval: "mean" | "prediction" } & (
       | { confidenceMethod: ConfidenceIntervalMethod; level: number; confidence?: never }
       | { confidence: number; confidenceMethod?: never; level?: never }
-    )
-  | {
+    ))))
+  | ({
       method: "polynomial";
       degree: number;
-      interval: "mean" | "prediction";
       span?: never;
-    } & (
+    } & ({ interval: false; confidenceMethod?: never; level?: never; confidence?: never } | ({ interval: "mean" | "prediction" } & (
       | { confidenceMethod: ConfidenceIntervalMethod; level: number; confidence?: never }
       | { confidence: number; confidenceMethod?: never; level?: never }
-    )
+    ))))
   | {
       method: "loess";
       span: number;
@@ -387,7 +410,7 @@ export type DatasetRegressionTransform = {
       confidence?: never;
       interval?: never;
     }
-);
+) & { readonly predict?: RegressionPredictOptions; readonly missing?: "error" | "drop" };
 export interface DatasetDensityTransform {
   type: "density";
   field: string;
@@ -398,6 +421,7 @@ export interface DatasetDensityTransform {
   kernel?: DensityKernel;
   normalization?: DensityNormalization;
   weight?: StatisticalWeight;
+  missing?: "error" | "drop";
   as: readonly [string, string];
   resolve: "shared";
   placement?: {
@@ -485,6 +509,7 @@ export type DatasetIntervalTransform = {
   field: string;
   groupBy: readonly string[];
   as: DatasetIntervalOutputFields;
+  missing?: "error" | "drop";
 } & (
   | {
       center: "mean";
@@ -588,6 +613,21 @@ export interface DatasetWindowTransform {
   readonly operations: readonly DatasetWindowOperation[];
   readonly temporalUnit?: TemporalInputUnit;
 }
+export interface SortKey {
+  field: string;
+  order?: "ascending" | "descending";
+  nulls?: "first" | "last";
+  temporalUnit?: "year" | "timestamp";
+}
+export interface DatasetSortTransform {
+  readonly type: "sort";
+  readonly sortBy: readonly {
+    readonly field: string;
+    readonly order: "ascending" | "descending";
+    readonly nulls: "first" | "last";
+    readonly temporalUnit?: "year" | "timestamp";
+  }[];
+}
 export interface ECDFOutputFields {
   value: string;
   cumulative: string;
@@ -700,6 +740,7 @@ export interface DatasetBinTransform {
   readonly includeEmpty: boolean;
   readonly members: boolean;
   readonly weight?: StatisticalWeight;
+  readonly missing?: "error" | "drop";
   readonly as: {
     readonly lower: string;
     readonly upper: string;
@@ -856,6 +897,7 @@ export type DatasetTransform =
   | DatasetFilterTransform
   | DatasetFoldTransform
   | DatasetRegressionTransform
+  | DatasetSortTransform
   | DatasetDensityTransform
   | DatasetECDFTransform
   | DatasetHorizonTransform
@@ -887,6 +929,8 @@ export interface DatasetSummaryTransform {
   aggregates: readonly SummaryAggregateOptions[];
   members?: string;
   weight?: StatisticalWeight;
+  missing?: "error" | "drop";
+  empty?: "null" | "identity";
 }
 export interface SummaryAggregateOptions {
   op: AggregateOperation;
@@ -900,6 +944,18 @@ export interface SummaryDataOptions {
   aggregates: readonly SummaryAggregateOptions[];
   members?: string;
   weight?: StatisticalWeight;
+  missing?: "error" | "drop";
+  empty?: "null" | "identity";
+}
+export interface SortedDataOptions {
+  id: string;
+  source?: string;
+  sortBy: readonly [SortKey, ...SortKey[]];
+}
+export interface EditSortedDataOptions {
+  target: string;
+  sortBy: readonly [SortKey, ...SortKey[]];
+  dependents?: DerivedDataDependents;
 }
 export interface BindMarkDataOptions {
   target: string;
@@ -1079,19 +1135,57 @@ export interface TraceNode {
 
 export interface SemanticDataset {
   readonly id: string;
+  readonly schema: DatasetSchema;
   readonly values?: readonly Readonly<Record<string, unknown>>[];
   readonly source?: string;
   readonly transform?: readonly Readonly<Record<string, unknown>>[];
   readonly [key: string]: unknown;
 }
 
+export type DatasetStorageType =
+  | "number"
+  | "string"
+  | "boolean"
+  | "array"
+  | "object"
+  | "unknown"
+  | "mixed";
+export interface DatasetFieldLineage {
+  readonly inputs: readonly Readonly<{ data: string; field: string }>[];
+  readonly owner: string;
+  readonly role: string;
+}
+export interface DatasetSchemaField {
+  readonly name: string;
+  readonly storageType: DatasetStorageType;
+  readonly nullable: boolean;
+  readonly optional: boolean;
+  readonly lineage?: DatasetFieldLineage;
+}
+export interface DatasetSchema {
+  readonly version: 1;
+  readonly completeness: "known" | "unknown";
+  readonly origin: "declared" | "inferred" | "derived";
+  readonly fields: readonly DatasetSchemaField[];
+}
+export interface SourceSchemaField {
+  name: string;
+  storageType: Exclude<DatasetStorageType, "unknown" | "mixed">;
+  nullable?: boolean;
+  optional?: boolean;
+}
+export interface SourceSchemaInput {
+  fields: readonly SourceSchemaField[];
+}
+
 export interface SemanticLayer {
   readonly id: string;
   readonly data?: string;
   readonly source?: string;
   readonly coordinate?: string;
-  readonly mark?: Readonly<{ type?: string; missing?: "error" | "break"; [key: string]: unknown }>;
+  readonly mark?: Readonly<{ type?: string; missing?: "error" | "break" | "skip"; [key: string]: unknown }>;
   readonly layout?: Readonly<{ mode?: ColorLayout }>;
+  readonly derivedBindings?: Readonly<{ regression?: Readonly<{ mode: "follow"; roles: readonly ["data", "x", "y"] }> }>;
   readonly encoding?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
   readonly [key: string]: unknown;
 }
@@ -1100,6 +1194,7 @@ export interface SemanticScale {
   readonly id: string;
   readonly type?: ScaleType;
   readonly domain?: "auto" | readonly unknown[];
+  readonly emptyDomain?: "preserve" | "require-explicit";
   readonly range?: ScaleRange;
   readonly [key: string]: unknown;
 }
@@ -1542,6 +1637,7 @@ export interface ScaleOptions {
   id?: string;
   type?: ScaleType;
   domain?: "auto" | readonly unknown[];
+  emptyDomain?: "preserve" | "require-explicit";
   range?: ScaleRange;
   nice?: boolean;
   zero?: boolean;
@@ -1687,6 +1783,7 @@ export interface EditScaleOptions {
   id?: string;
   type?: ScaleType;
   domain?: "auto" | readonly unknown[];
+  emptyDomain?: "preserve" | "require-explicit";
   range?: ScaleRange;
   nice?: boolean;
   zero?: boolean;
@@ -2002,6 +2099,7 @@ export interface DensityDataOptions {
   kernel?: DensityKernel;
   normalization?: DensityNormalization;
   weight?: StatisticalWeight;
+  missing?: "error" | "drop";
   as?: readonly [string, string];
 }
 
@@ -2097,6 +2195,7 @@ export interface IntervalDataOptions {
   extent?: IntervalExtent;
   method?: ConfidenceIntervalMethod;
   level?: number;
+  missing?: "error" | "drop";
   as?: IntervalOutputFields;
 }
 
@@ -2169,6 +2268,7 @@ export type BinDataOptions = {
   includeEmpty?: boolean;
   members?: boolean;
   weight?: StatisticalWeight;
+  missing?: "error" | "drop";
   as?: BinDataOutputFields;
 } & BinDataMode;
 
@@ -2311,7 +2411,22 @@ type FocusedWeightedDerivedDataEdit<T, Weight> = {
   : never);
 
 export type EditComputedDataOptions = FocusedDerivedDataEdit<ComputedDataOptions>;
-export type EditFilteredDataOptions = FocusedDerivedDataEdit<FilterDataOptions>;
+export type FilterRangePatch = FilterRangeClosure & {
+  min?: FilterBound | false;
+  max?: FilterBound | false;
+};
+type FilterModePatch =
+  | { oneOf: readonly [DatasetScalar, ...DatasetScalar[]]; noneOf?: never; predicate?: never; range?: never }
+  | { oneOf?: never; noneOf: readonly [DatasetScalar, ...DatasetScalar[]]; predicate?: never; range?: never }
+  | { oneOf?: never; noneOf?: never; predicate: FilterComparison; range?: never }
+  | { oneOf?: never; noneOf?: never; predicate?: never; range: FilterRangePatch }
+  | { oneOf?: never; noneOf?: never; predicate?: never; range?: never };
+export type EditFilteredDataOptions = FilterModePatch & {
+  target: string;
+  field?: string;
+  nulls?: "include" | "exclude" | false;
+  dependents?: DerivedDataDependents;
+};
 export type EditFoldDataOptions = FocusedDerivedDataEdit<FoldDataOptions>;
 export type EditSummaryDataOptions = FocusedWeightedDerivedDataEdit<
   SummaryDataOptions,
@@ -3675,6 +3790,7 @@ export interface TextMarkOptions {
   /** Explicit source mark. Mutually exclusive with data; may be incomplete. */
   source?: string;
   text?: unknown;
+  missing?: "error" | "skip";
   fill?: string;
   opacity?: number;
   fontSize?: number;
@@ -3738,6 +3854,7 @@ export interface RemoveLabelLayoutOptions {
 export interface RectMarkOptions extends RectStyleDetails {
   id?: string;
   data?: string;
+  missing?: "error" | "skip";
   fill?: string;
   opacity?: number;
   stroke?: string | false;
@@ -4145,7 +4262,8 @@ type RegressionParameterOptions =
       confidenceMethod?: ConfidenceIntervalMethod;
       level?: number;
       confidence?: number;
-      interval?: RegressionInterval;
+      interval?: RegressionInterval | false;
+      predict?: RegressionPredictOptions;
     }
   | {
       method: "polynomial";
@@ -4154,7 +4272,8 @@ type RegressionParameterOptions =
       confidenceMethod?: ConfidenceIntervalMethod;
       level?: number;
       confidence?: number;
-      interval?: RegressionInterval;
+      interval?: RegressionInterval | false;
+      predict?: RegressionPredictOptions;
     }
   | {
       method: "loess";
@@ -4164,6 +4283,7 @@ type RegressionParameterOptions =
       level?: never;
       confidence?: never;
       interval?: never;
+      predict?: RegressionPredictOptions;
     };
 
 export type RegressionDataOptions = {
@@ -4172,6 +4292,7 @@ export type RegressionDataOptions = {
   x: string;
   y: string;
   groupBy?: string;
+  missing?: "error" | "drop";
 } & RegressionParameterOptions;
 
 type RegressionCommonOptions = {
@@ -4180,6 +4301,8 @@ type RegressionCommonOptions = {
   y?: string;
   groupBy?: string | false;
   line?: StrokeStyleDetails & { strokeWidth?: number; curve?: CurveInterpolation };
+  sourceBinding?: "fixed" | "follow";
+  missing?: "error" | "drop";
 };
 
 export type RegressionOptions = RegressionCommonOptions & (
@@ -4206,9 +4329,12 @@ export interface EditRegressionOptions {
   confidenceMethod?: ConfidenceIntervalMethod;
   level?: number;
   confidence?: number;
-  interval?: RegressionInterval;
+  interval?: RegressionInterval | false;
+  missing?: "error" | "drop";
+  predict?: RegressionPredictOptions | false;
   band?: false | RegressionBandOptions;
   line?: StrokeStyleDetails & { strokeWidth?: number; curve?: CurveInterpolation };
+  sourceBinding?: "fixed" | "follow";
 }
 
 export interface RemoveAxisOptions {
@@ -4474,6 +4600,22 @@ export interface EditTitleOptions
 
 export interface ChartProgram extends RegisteredExtensionActions {}
 
+type StoredCell<T> = T extends (...args: never[]) => unknown ? never
+  : T extends readonly (infer Value)[] ? readonly StoredCell<Value>[]
+  : T extends object ? { readonly [Key in keyof T]: StoredCell<T[Key]> }
+  : T;
+
+export interface CreateDataOptions<Row extends object> {
+  id?: string;
+  values: readonly (Row extends readonly unknown[] ? never : Row & StoredCell<Row>)[];
+  schema?: SourceSchemaInput;
+}
+
+export interface ReviseDataOptions<Row extends object> extends CreateDataOptions<Row> {
+  source: string;
+  id: string;
+}
+
 export class ChartProgram {
   constructor(state?: ActionOptions);
   readonly semanticSpec: SemanticSpec;
@@ -4489,9 +4631,12 @@ export class ChartProgram {
   createCanvas(options?: CanvasOptions): ChartProgram;
   editCanvas(options: CanvasOptions): ChartProgram;
   fitCanvas(options?: FitCanvasOptions): ChartProgram;
+  applyTextMetrics(options: ApplyTextMetricsOptions): ChartProgram;
+  removeTextMetrics(): ChartProgram;
   applyTheme(options: ApplyThemeOptions): ChartProgram;
   removeTheme(): ChartProgram;
-  createData(options: { id?: string; values: readonly unknown[] }): ChartProgram;
+  createData<Row extends object>(options: CreateDataOptions<Row>): ChartProgram;
+  reviseData<Row extends object>(options: ReviseDataOptions<Row>): ChartProgram;
   removeData(options: RemoveResourceOptions): ChartProgram;
   removeScale(options: RemoveResourceOptions): ChartProgram;
   removeCoordinate(options: RemoveResourceOptions): ChartProgram;
@@ -4519,6 +4664,7 @@ export class ChartProgram {
   createTimeUnitData(options: TimeUnitDataOptions): ChartProgram;
   createWindowData(options: WindowDataOptions): ChartProgram;
   createBin2DData(options: Bin2DDataOptions): ChartProgram;
+  createSortedData(options: SortedDataOptions): ChartProgram;
   editDerivedData(options: EditDerivedDataOptions): ChartProgram;
   editComputedData(options: EditComputedDataOptions): ChartProgram;
   editFilteredData(options: EditFilteredDataOptions): ChartProgram;
@@ -4530,6 +4676,7 @@ export class ChartProgram {
   editDensityData(options: EditDensityDataOptions): ChartProgram;
   editStackData(options: EditStackDataOptions): ChartProgram;
   editRegressionData(options: EditRegressionDataOptions): ChartProgram;
+  editSortedData(options: EditSortedDataOptions): ChartProgram;
   editIntervalData(options: EditIntervalDataOptions): ChartProgram;
   editECDFData(options: EditECDFDataOptions): ChartProgram;
   editNormalizedData(options: EditNormalizedDataOptions): ChartProgram;
@@ -4540,6 +4687,7 @@ export class ChartProgram {
   createPointMark(options?: StrokeStyleDetails & {
     id?: string;
     data?: string;
+    missing?: "error" | "skip";
     shape?: PointShape;
     fill?: string;
     opacity?: number;
@@ -4548,6 +4696,7 @@ export class ChartProgram {
   }): ChartProgram;
   editPointMark(options: StrokeStyleDetails & {
     target?: string;
+    missing?: "error" | "skip";
     shape?: PointShape;
     fill?: string;
     opacity?: number;
@@ -4557,6 +4706,7 @@ export class ChartProgram {
   createTickMark(options?: StrokeStyleDetails & {
     id?: string;
     data?: string;
+    missing?: "error" | "skip";
     length?: number;
     stroke?: string;
     strokeWidth?: number;
@@ -4564,6 +4714,7 @@ export class ChartProgram {
   }): ChartProgram;
   editTickMark(options: StrokeStyleDetails & {
     target?: string;
+    missing?: "error" | "skip";
     length?: number;
     stroke?: string;
     strokeWidth?: number;
@@ -4593,6 +4744,7 @@ export class ChartProgram {
   createBarMark(options?: RectStyleDetails & {
     id?: string;
     data?: string;
+    missing?: "error" | "skip";
     fill?: string;
     opacity?: number;
     stroke?: FilledMarkStroke;
@@ -4600,6 +4752,7 @@ export class ChartProgram {
   }): ChartProgram;
   editBarMark(options: RectStyleDetails & {
     target?: string;
+    missing?: "error" | "skip";
     fill?: string;
     opacity?: number;
     stroke?: FilledMarkStroke;
@@ -4636,8 +4789,8 @@ export class ChartProgram {
   }): ChartProgram;
   createRectMark(options?: RectMarkOptions): ChartProgram;
   editRectMark(options: EditRectMarkOptions): ChartProgram;
-  createRuleMark(options?: { id?: string; data?: string } & RuleStyleOptions): ChartProgram;
-  editRuleMark(options: { target?: string } & RuleStyleOptions): ChartProgram;
+  createRuleMark(options?: { id?: string; data?: string; missing?: "error" | "skip" } & RuleStyleOptions): ChartProgram;
+  editRuleMark(options: { target?: string; missing?: "error" | "skip" } & RuleStyleOptions): ChartProgram;
   createTextMark(options?: TextMarkOptions): ChartProgram;
   createMarkLabels(options?: CreateMarkLabelsOptions): ChartProgram;
   editMarkLabelSelection(options: EditMarkLabelSelectionOptions): ChartProgram;