ggaction 0.0.23 → 0.0.26

package/src/selectors/plotComposition.js

@@ -0,0 +1,115 @@
+import { findLayer } from './layers.js';
+import { ownership, ownedChildren } from './markOwners.js';
+import { resolveEligibleLayer } from './layers.js';
+import { findCoordinate } from './coordinates.js';
+
+const sameUnit = new Set(['mean', 'median', 'min', 'max', 'q1', 'q3', 'quantile', 'lower', 'upper', 'center', 'value', 'ciLower', 'ciUpper', 'stderr', 'stdev', 'iqr']);
+export function measurementUnit(operations = []) {
+  return operations.filter(op => !sameUnit.has(op)).join(':') || 'value';
+}
+
+// Resolve provenance, never generated field-name conventions. Stops at an
+// ordinary source (including a user-authored filtered/transformed dataset).
+export function compositionChannel(program, encoding, data) {
+  if (!encoding?.field && encoding?.aggregate !== 'count') return undefined;
+  let field = encoding.field, current = data, fields, derived;
+  const operations = encoding.aggregate ? [encoding.aggregate] : [];
+  const visited = new Set();
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const dataset = program.semanticSpec.datasets.find(d => d.id === current);
+    let recognized = false;
+    for (const t of [...(dataset?.transform ?? [])].reverse()) {
+      const key = Array.isArray(t.as) ? t.as.indexOf(field) : Object.entries(t.as ?? {}).find(([, value]) => value === field)?.[0];
+      if (t.type === 'summary') {
+        const a = t.aggregates.find(a => a.as === field);
+        if (a) { field = a.field ?? field; operations.unshift(typeof a.op==='string'?a.op:a.op.op); }
+        recognized = true;
+      } else if (['boxSummary', 'boxOutlier', 'gradientProfile', 'interval'].includes(t.type)) {
+        if (key !== undefined && key !== 'category') { field = t.field; operations.unshift(key === 'count' ? 'count' : key === 'center' ? t.center ?? 'median' : 'quantile'); }
+        recognized = true;
+      } else if (t.type === 'density') {
+        if (key === 0 || key === 1) { field = t.field; if (key === 1) { operations.unshift('density'); derived = { normalization: t.normalization, weight: t.weight }; } }
+        recognized = true;
+      } else if (t.type === 'ecdf') {
+        if (key !== undefined) { field = t.field; if (key !== 'value') operations.unshift(key === 'probability' ? 'probability' : 'cumulative-count'); }
+        recognized = true;
+      } else if (t.type === 'bin2d') {
+        if (key?.startsWith('x')) field = t.x;
+        else if (key?.startsWith('y')) field = t.y;
+        else if (key === 'count') { field = undefined; fields = [t.x, t.y]; operations.unshift('count'); }
+        recognized = true;
+      } else if (t.type === 'horizon') {
+        if (key === 'x') field = t.x.field;
+        else { field = t.y.field; operations.unshift('folded'); derived = { bands:t.bands, baseline:t.baseline, extent:t.extent, resolve:t.resolve }; }
+        recognized = true;
+      } else if (t.type === 'fold') {
+        if (key === 'key' || key === 'value') { field = undefined; fields = t.fields; operations.unshift(key === 'key' ? 'dimensions' : 'profile'); }
+        recognized = true;
+      } else if (t.type === 'regression' || t.type === 'complete') recognized = true;
+      else if (t.type === 'filter' && Object.values(program.markConfigs).some(config =>
+        (config.raincloudPlot?.ownedData ?? config.endpointPlot?.ownedData ?? []).includes(current))) {
+        // These filters implement one facade's complete-case population; they
+        // do not introduce a user-selected data source or new field meaning.
+        recognized = true;
+      }
+    }
+    if (!recognized || !dataset.source) break;
+    current = dataset.source;
+  }
+  if (encoding.stack === 'normalize' || encoding.stack?.mode === 'normalize') operations.push('normalized');
+  return { ...(field === undefined ? {} : { field }), ...(fields ? { fields } : {}), fieldType: encoding.fieldType,
+    scale: encoding.scale, data: current, measurement: { unit: measurementUnit(operations), operations,
+      ...(derived ? { parameters: derived } : {}) },
+    ...(encoding.bin === undefined ? {} : { bin: encoding.bin }),
+    ...(encoding.temporalUnit === undefined ? {} : { temporalUnit: encoding.temporalUnit }) };
+}
+
+export function plotComposition(program, target) {
+  const owners = ownership(program);
+  // Public IDs of compound facades can differ from their concrete owner.
+  if (target && !findLayer(program, target)) target = program.semanticSpec.layers.find(l => program.markConfigs[l.id]?.raincloudPlot?.id === target)?.id ?? target;
+  while (owners.has(target)) target = owners.get(target);
+  const layer = resolveEligibleLayer(program, { target, label: 'plot composition', predicate: l => !owners.has(l.id) && !l.derivedBindings?.overlay && l.data !== undefined });
+  const owned = new Set([layer.id]);
+  const visit = id => { for (const child of ownedChildren(program, id)) if (!owned.has(child)) { owned.add(child); visit(child); } };
+  visit(layer.id);
+  const channels = Object.fromEntries(Object.entries(layer.encoding ?? {}).flatMap(([channel, encoding]) => {
+    const value = compositionChannel(program, encoding, layer.data); return value ? [[channel, value]] : [];
+  }));
+  if (layer.mark.type === 'arc' && ['count','sum'].includes(layer.encoding.theta?.aggregate)) {
+    channels.theta.measurement = { unit:'partition', operations:['partition'], parameters:{
+      aggregate:layer.encoding.theta.aggregate, ...(layer.encoding.theta.weight ? {weight:layer.encoding.theta.weight} : {})
+    } };
+  }
+  const dimensionEncoding = layer.encoding?.parallel?.dimensions;
+  const dimensions = dimensionEncoding?.map(e => compositionChannel(program, e, layer.data));
+  const data = Object.values(channels).find(c => c.data)?.data ?? layer.data;
+  const config = program.markConfigs[layer.id] ?? {};
+  return { version:1, owner:layer.id, ownedMarks:[...owned], data, coordinate:findCoordinate(program,layer.coordinate),
+    mark:layer.mark.type, channels, ...(dimensions ? { dimensions } : {}),
+    ...(config.compositionRole ? { role:config.compositionRole } : {}),
+    ...(layer.encoding.group ? { groupBy:layer.encoding.group.field ?? layer.encoding.group.fields } : {}) };
+}
+
+// Re-encoding one independent consumer must not silently change the meaning of
+// a resource still used by another plot. A new explicit scale remains possible.
+export function assertSharedPositionMeaning(program, layer, channel, encoding) {
+  const previous = layer.encoding?.[channel];
+  const companion = {x:'y',y:'x',theta:'radius',radius:'theta'}[channel];
+  // New marks can inherit an incomplete position while their first bindings are authored.
+  if (!layer.encoding?.[companion] && !(layer.mark.type==='arc' && layer.encoding?.theta?.aggregate)) return;
+  if (!previous?.scale || previous.scale !== encoding.scale) return;
+  const before = compositionChannel(program, previous, layer.data);
+  const after = compositionChannel(program, encoding, layer.data);
+  const signature = role => role && JSON.stringify([role.field, role.fields, role.fieldType,
+    role.measurement.unit, role.temporalUnit]);
+  if (!before || !after || signature(before) === signature(after)) return;
+  const owners = ownership(program);
+  const owner = id => { while (owners.has(id)) id = owners.get(id); return id; };
+  const conflict = program.semanticSpec.layers.find(other => other.id !== layer.id &&
+    owner(other.id) !== owner(layer.id) && !other.derivedBindings?.overlay &&
+    other.encoding?.[channel]?.scale === previous.scale &&
+    signature(compositionChannel(program, other.encoding[channel], other.data)) === signature(before));
+  if (conflict) throw new Error(`Scale "${previous.scale}" is shared with plot "${owner(conflict.id)}". Keep the same positional meaning or supply a different scale.id.`);
+}

package/src/selectors/selectionTargets.js

@@ -0,0 +1,19 @@
+import { ownedChildren } from './markOwners.js';
+import { findLayer } from './layers.js';
+
+export function highlightTargets(program, target) {
+  const owners = Object.entries(program.markConfigs).filter(([, config]) => config.raincloudPlot?.id === target);
+  const root = findLayer(program, target)?.id ?? (owners.length === 1 ? owners[0][0] : undefined);
+  if (!root) return [target];
+  const result = new Set([root]);
+  const visit = id => {
+    for (const child of ownedChildren(program, id)) {
+      // Independent overlays and statistical additions keep their own scope.
+      const layer = findLayer(program, child);
+      if (layer.derivedBindings?.overlay || program.markConfigs[child]?.statisticalReference || layer.mark.type === 'text') continue;
+      if (!result.has(child)) { result.add(child); visit(child); }
+    }
+  };
+  visit(root);
+  return [...result];
+}

package/src/version.js

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

package/types/basic.d.ts

@@ -1,4 +1,4 @@
-import type { ChartProgram, BasicSeriesLayoutOptions, CreateDataOptions } from "./program.js";
+import type { ChartProgram, BasicSeriesLayoutOptions, CreateDataOptions, ScopedActionTarget } from "./program.js";
 
 export type {
   LinearNiceCountOptions,
@@ -10,11 +10,13 @@ export type {
   CartesianGuideDashMap,
   AxisTicksAndLabelsOptions,
   AxisTitleOptions,
+  AxisTitleOffset,
   DisplayLabelMap,
   DisplayLabelOptions,
   ApplyThemeOptions,
   BarWidthOptions,
   BasicSeriesLayoutOptions,
+  Bin2DAssignment,
   Bin2DDataOptions,
   CanvasOptions,
   ColorEncodingOptions,
@@ -117,7 +119,7 @@ type BasicMethodKey =
   | "createGuides";
 
 type RebindMethod<T> = T extends (...args: infer Args) => ChartProgram
-  ? (...args: Args) => BasicChartProgram
+  ? (...args: { [K in keyof Args]: Exclude<Args[K], { target: ScopedActionTarget | readonly unknown[] }> }) => BasicChartProgram
   : never;
 
 export type BasicChartProgram =

package/types/index.d.ts

@@ -1,6 +1,10 @@
 import type { ChartProgram, CompositionOptions } from "./program.js";
 
 export type {
+  CreateOverlayOptions,
+  EditOverlayOptions,
+  OverlayLineAppearance,
+  OverlayPointAppearance,
   LinearNiceCountOptions,
   AxisTickRounding,
   ArcInnerRadius,
@@ -27,6 +31,7 @@ export type {
   AxisTicksAndLabelsOptions,
   AxisTickStyleOptions,
   AxisTitleOptions,
+  AxisTitleOffset,
   AxisValue,
   DisplayLabelMap,
   DisplayLabelOptions,
@@ -36,6 +41,7 @@ export type {
   BinnedHeatmapColorOptions,
   BinnedHeatmapOptions,
   BinnedHeatmapPositionChannel,
+  Bin2DAssignment,
   Bin2DCounts,
   Bin2DDataOptions,
   Bin2DExtent,
@@ -71,6 +77,13 @@ export type {
   NamedCompleteAxis,
   ConcatCompositionSpec,
   CompositionAlign,
+  CompositionShares,
+  ScopedActionTarget,
+  ActionTargetList,
+  TargetedOptions,
+  EditCompositionScalesOptions,
+  AdjacentPlotSpecification,
+  CreateAdjacentPlotOptions,
   CompositionOptions,
   EditFacetSourceOptions,
   FacetHeaderRole,
@@ -287,6 +300,7 @@ export type {
   FieldType,
   FillPaint,
   FacetCompositionSpec,
+  FacetGap,
   FacetGuideOptions,
   FacetOptions,
   FacetTopLaneMode,

package/types/inspection.d.ts

@@ -15,3 +15,37 @@ export function getDatasetSchema(program: ProgramInput, options: {readonly data:
 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;
+
+export interface PlotCompositionChannel {
+  readonly field?: string;
+  readonly fields?: readonly string[];
+  readonly fieldType: string;
+  readonly scale: string;
+  readonly data: string;
+  readonly measurement: Readonly<{ unit: string; operations: readonly string[]; parameters?: Readonly<Record<string, unknown>> }>;
+  readonly bin?: Readonly<Record<string, unknown>>;
+  readonly temporalUnit?: string;
+}
+export interface PlotComposition {
+  readonly version: 1;
+  readonly owner: string;
+  readonly ownedMarks: readonly string[];
+  readonly data: string;
+  readonly coordinate?: Readonly<{ id: string; type: string }>;
+  readonly mark: string;
+  readonly channels: Readonly<Record<string, PlotCompositionChannel>>;
+  readonly dimensions?: readonly PlotCompositionChannel[];
+  readonly role?: string;
+  readonly groupBy?: string | readonly string[];
+}
+export function getPlotComposition(program: ProgramInput, options?: { readonly target?: string | { readonly childPath: readonly string[]; readonly id: string }; readonly childPath?: readonly string[] }): PlotComposition;
+
+export interface MarkItemInspection {
+  readonly key: string; readonly target: string; readonly markType: string; readonly grain: "item" | "stack";
+  readonly fields: Readonly<Record<string, unknown>>; readonly channels: Readonly<Record<string, unknown>>;
+  readonly properties: Readonly<Record<string, unknown>>;
+  readonly geometry: readonly {readonly type: string; readonly properties: Readonly<Record<string, unknown>>}[];
+  readonly rows: readonly { readonly data: string; readonly index: number }[];
+  readonly bounds: Readonly<{left:number;top:number;right:number;bottom:number}> | null;
+}
+export function getMarkItems(program: ProgramInput, options?: {target?: string | {childPath?:readonly string[];id:string};grain?:"item"|"stack"}): readonly MarkItemInspection[];