udi-yac 0.2.4 → 0.3.0

package/dist/src/utils/specMutations.d.ts

@@ -20,26 +20,82 @@ import { UDIGrammar } from 'udi-toolkit/react';
  */
 export declare function setMappingFieldByEncoding(spec: UDIGrammar, encoding: string, newField: string): UDIGrammar;
 /**
- * Collect the set of source-field names that are referenced by any
- * schema-defining operator in `spec.transformation`. A mapping whose
- * `field` belongs to this set should not be offered as tweakable — swapping
- * it via VizTweak would leave the transformation pipeline referencing the
- * old field while the mapping points at a new field that the pipeline's
- * output no longer contains, producing a silently-broken chart.
- *
- * Schema-defining operators — covered here:
- *   groupby   row keys of the output
+ * Collect the set of source-field names referenced by an operator we cannot
+ * swap in-place. A mapping whose `field` belongs to this set is not offered as
+ * a plain field swap — rewriting only the mapping would leave the pipeline
+ * pointing at the old field, producing a silently-broken chart.
+ *
+ * Locked operators — no supported swap:
  *   binby     `.field` becomes bin input; output replaces the row schema
- *   rollup    each aggregation's `.field` is an input to the op; when a
- *             mapping references that same field elsewhere, orphaning it
- *             breaks the rollup
- *   kde       `.field` is the density-estimation input
  *   join      `.on` fields define the join key
  *
- * Schema-preserving / free-form operators — skipped intentionally:
- *   filter    string expression; row-count-only effect, schema unchanged
+ * NOT locked (swappable via a transform-aware mutation instead):
+ *   groupby   swappable via swapDimensionField — rewrites the groupby entry
+ *             (and dependent rollup output columns) alongside the mapping
+ *   rollup    each aggregation's `.field` is swappable via swapMeasureField —
+ *             the mapping references the rollup *output* column, not the input
+ *   kde       swappable via swapPlainField — the density input; its output
+ *             `sample` column is named after the field, so a plain field swap
+ *             renames kde.field + kde.output.sample alongside the mapping
+ *
+ * Skipped (schema-preserving; don't lock a swap, but ARE followed when the
+ * swapped field is fully replaced — see swapPlainField / applyRenamePlan):
+ *   filter    row-count-only effect, schema unchanged
  *   orderby   sort only; schema unchanged
- *   derive    only creates new output fields; expressions are opaque strings
- *             (would need a parser to extract source-field references safely)
+ *   derive    only creates new output fields
  */
 export declare function collectLockedFields(spec: UDIGrammar): Set<string>;
+/** The group-by dimension field names referenced anywhere in the pipeline. */
+export declare function collectGroupbyFields(spec: UDIGrammar): Set<string>;
+export interface RollupOutput {
+    op?: string;
+    field?: string;
+}
+/**
+ * Map each rollup *output column name* to its aggregation. Encoding mappings
+ * reference these output names (e.g. `sex_count`, `avg_age`), not the raw
+ * input field — so this is how the tweak UI recognises an aggregated measure
+ * and decides whether it has a swappable input `field` (count/frequency don't).
+ * Last write wins if two rollups reuse a name (grammar disallows this anyway).
+ */
+export declare function collectRollupOutputs(spec: UDIGrammar): Record<string, RollupOutput>;
+/**
+ * Swap the group-by dimension shown on ONE encoding (e.g. the x axis, sex →
+ * race), keeping the aggregation. The mapping rewrite is scoped to `encoding`,
+ * so a field shared by another encoding (a bar with `x=sex` AND `color=sex`) is
+ * not disturbed.
+ *
+ * The groupby is kept consistent with what the chart displays:
+ *   - if the old field is no longer shown anywhere, it is replaced by `newField`
+ *     in the groupby, and any rollup output column embedding it (`sex_count`) is
+ *     renamed (`race_count`) so labels track the swap;
+ *   - if the old field is still shown on another encoding, `newField` is instead
+ *     added to the groupby (the chart now groups by both) and nothing else is
+ *     renamed.
+ *
+ * Returns the same reference on a no-op (encoding absent, or already newField).
+ */
+export declare function swapDimensionField(spec: UDIGrammar, encoding: string, newField: string): UDIGrammar;
+/**
+ * Swap a plain (non-aggregated, non-groupby) field shown on ONE encoding, and
+ * follow that field through the pipeline. A raw source field can also drive
+ * `orderby` and `filter` steps (e.g. a CDF orders by the plotted field and
+ * derives a percentile from that order, and drops its nulls) — rewriting only
+ * the mapping would leave the chart ordered/filtered by the old field while
+ * plotted against the new one. So:
+ *   - rewrite only the edited encoding's mapping (scoped, like the dimension swap);
+ *   - if the old field is still shown on another encoding, stop there (ambiguous
+ *     which axis the transforms belong to — mirror swapDimensionField);
+ *   - otherwise rename the old field → new field in orderby + filter refs.
+ *
+ * Returns the same reference on a no-op.
+ */
+export declare function swapPlainField(spec: UDIGrammar, encoding: string, newField: string): UDIGrammar;
+/**
+ * Swap the input field of an aggregated measure (e.g. mean of age → mean of
+ * weight). `outputKey` is the rollup output column the encoding is bound to.
+ * Renames that rollup's `.field`, renames the output column if it embeds the
+ * old field name (`avg_age` → `avg_weight`), and updates the encoding / orderby
+ * refs that pointed at it. Leaves the group-by dimension untouched.
+ */
+export declare function swapMeasureField(spec: UDIGrammar, outputKey: string, newField: string): UDIGrammar;