@ai-matrx/office 0.8.12 → 0.8.13

package/dist/collab-sheets-transform.d.cts

@@ -42,9 +42,10 @@ interface SheetRange {
  * `census.test.ts` fails when an emitted id is missing or a declared id is stale.
  *
  * Covered in C5a: cell values and styles, row/column insert, remove and move, merge/unmerge, row height,
- * column width, worksheet name. Formulas are C5b, ranged resources C5c; both are barriers until then.
+ * column width, worksheet name. C5b: formula text in cells (`f`, array `ref`) and defined names. Shared
+ * formulas (`si`) stay barriers (see transform.ts cellBarrier); ranged resources are C5c.
  */
-type SheetFamily = "cell" | "structure" | "merge" | "size" | "name";
+type SheetFamily = "cell" | "structure" | "merge" | "size" | "name" | "defname";
 interface CoveredEntry {
     readonly kind: "covered";
     readonly family: SheetFamily;
@@ -57,8 +58,8 @@ interface NeverEntry {
 }
 interface BarrierEntry {
     readonly kind: "barrier";
-    /** The unit that owns its transform (C5b formulas, C5c resources) or "X" (no unit yet). */
-    readonly until: "C5b" | "C5c" | "X";
+    /** The unit that owns its transform (C5c resources) or "X" (no unit yet). */
+    readonly until: "C5c" | "X";
     readonly reason: string;
 }
 type RegistryEntry = CoveredEntry | NeverEntry | BarrierEntry;
@@ -102,7 +103,7 @@ declare function mapIndex(op: AxisOp, i: number): number | null;
  */
 declare function transformAxis(x: AxisOp, y: AxisOp, side: Side): AxisOp[] | null;
 
-declare const SHEET_TRANSFORMER_VERSION = "c5a-1";
+declare const SHEET_TRANSFORMER_VERSION = "c5b-1";
 /**
  * Pairs the fuzz proved divergent (or that have no transform yet), as unordered mutation-id pairs, with the
  * failing seed. Each returns a Barrier until it has its own correct transform under a new proto.
@@ -133,13 +134,24 @@ declare function mergeThrough(s: Structural, m: SheetRange): {
 declare function exactMergeRemovals(group: SheetGroup, merges: Readonly<Record<string, readonly SheetRange[]>>): SheetMutation[];
 type Cell = Record<string, unknown> | null;
 /** The content slot of a cell. A traveling entry that touches content must carry all of them (see completeCellContent). */
-declare const CONTENT_KEYS: readonly ["v", "t", "p", "f", "si", "custom"];
+declare const CONTENT_KEYS: readonly ["v", "t", "p", "f", "si", "custom", "ref", "xf", "ft", "fd"];
 /**
  * Completes a captured cell entry's content slot from the sender's post-state, so content writes are full
  * replacements (an entry that sets `v` alone would otherwise keep a stale `p` on some seats). C6's capture
  * calls this per touched cell with the cell as it stands right after the command.
  */
 declare function completeCellContent(entry: Cell, post: Record<string, unknown> | null | undefined): Cell;
+/** Params that travel for the transformer only; `forApply` strips them before Univer sees the mutation. */
+declare const SIDE_CAR_PARAMS: readonly ["refSheets", "previousName", "derived"];
+declare function forApply(m: SheetMutation): SheetMutation;
+/**
+ * Capture-time annotation (C6 calls it per group, like completeCellContent): every op whose formula text
+ * qualifies a reference with a sheet name gets `refSheets`, and every set-defined-name gets `previousName`
+ * (the name its id had before the command; null for a new name). Rewrites that follow a structural op, a
+ * rename or a defined-name change in the same group are marked `derived`. `sheets` is sheet id → name and
+ * `definedNames` defined-name id → name, both read right before the command ran.
+ */
+declare function annotateFormulas(group: SheetGroup, sheets: Readonly<Record<string, string>>, definedNames: Readonly<Record<string, string>>): SheetMutation[];
 /** x over y for single mutations. */
 declare function transformMutation(x: SheetMutation, y: SheetMutation, side: Side): TransformResult;
 /** Command group x rewritten to apply after command group y. One Barrier makes the whole group a barrier. */
@@ -156,4 +168,50 @@ declare const sheetTransformer: {
     isNoop(op: SheetGroup): boolean;
 };
 
-export { type Axis, type AxisOp, type Barrier, type BarrierEntry, CONTENT_KEYS, type CoveredEntry, type NeverEntry, PAIR_BARRIERS, type RegistryEntry, SHEET_MUTATIONS, SHEET_TRANSFORMER_VERSION, type SheetFamily, type SheetGroup, type SheetMutation, type SheetRange, type Side, type TransformResult, type Transformed, allowParams, cellRef, completeCellContent, exactMergeRemovals, isBarrier, mapIndex, mergeThrough, sheetTransformer, transformAxis, transformGroup, transformMutation };
+/** Sheet name → sheet id (null: the name is no sheet of this workbook). */
+type RefSheets = Readonly<Record<string, string | null>>;
+/** What changed under a formula: rows/columns of one sheet, or one sheet's name. */
+type RefChange = {
+    readonly kind: "axis";
+    readonly sheet: string;
+    readonly axis: Axis;
+    readonly op: AxisOp;
+} | {
+    readonly kind: "rename";
+    readonly sheet: string;
+    readonly name: string;
+} | {
+    readonly kind: "defined-name";
+    readonly from: string;
+    readonly to: string | null;
+};
+interface FormulaCtx {
+    /** The sheet the formula lives in (its unqualified references point here). */
+    readonly ownSheet: string;
+    readonly refSheets: RefSheets | undefined;
+    /** Defined names keep the sheet qualifier of a moved reference (sheets-formula `preserveSheetQualifier`). */
+    readonly keepQualifier?: boolean;
+}
+declare const REF_ERROR = "#REF!";
+declare const isFormulaText: (f: unknown) => f is string;
+/** Why a formula cannot be transformed (null = it can). */
+declare function formulaBarrier(text: string, ctx: FormulaCtx): string | null;
+interface Rewritten {
+    readonly text: string;
+    readonly changed: boolean;
+}
+/**
+ * The formula (or defined-name ref string) after `change`, exactly as Univer rewrites it: every reference into
+ * the changed sheet moves (or becomes #REF!), and once anything changed every other reference is re-serialized
+ * (`updateRefOffset`). Returns a reason string when the text cannot be transformed.
+ */
+declare function rewriteFormula(text: string, ctx: FormulaCtx, change: RefChange): Rewritten | string;
+/**
+ * An op's `refSheets` after a rename: the renamed sheet answers to its new name only, and a name that was
+ * no sheet before now names it. Unchanged (same object) when the rename touches nothing it lists.
+ */
+declare function refSheetsAfter(refSheets: RefSheets | undefined, change: RefChange): RefSheets | undefined;
+/** `refSheets` for the given formula texts: every sheet name they qualify a reference with, resolved now. */
+declare function refSheetsFor(texts: Iterable<string>, sheets: Readonly<Record<string, string>>): RefSheets | undefined;
+
+export { type Axis, type AxisOp, type Barrier, type BarrierEntry, CONTENT_KEYS, type CoveredEntry, type FormulaCtx, type NeverEntry, PAIR_BARRIERS, REF_ERROR, type RefChange, type RefSheets, type RegistryEntry, type Rewritten, SHEET_MUTATIONS, SHEET_TRANSFORMER_VERSION, SIDE_CAR_PARAMS, type SheetFamily, type SheetGroup, type SheetMutation, type SheetRange, type Side, type TransformResult, type Transformed, allowParams, annotateFormulas, cellRef, completeCellContent, exactMergeRemovals, forApply, formulaBarrier, isBarrier, isFormulaText, mapIndex, mergeThrough, refSheetsAfter, refSheetsFor, rewriteFormula, sheetTransformer, transformAxis, transformGroup, transformMutation };

package/dist/collab-sheets-transform.d.ts

@@ -42,9 +42,10 @@ interface SheetRange {
  * `census.test.ts` fails when an emitted id is missing or a declared id is stale.
  *
  * Covered in C5a: cell values and styles, row/column insert, remove and move, merge/unmerge, row height,
- * column width, worksheet name. Formulas are C5b, ranged resources C5c; both are barriers until then.
+ * column width, worksheet name. C5b: formula text in cells (`f`, array `ref`) and defined names. Shared
+ * formulas (`si`) stay barriers (see transform.ts cellBarrier); ranged resources are C5c.
  */
-type SheetFamily = "cell" | "structure" | "merge" | "size" | "name";
+type SheetFamily = "cell" | "structure" | "merge" | "size" | "name" | "defname";
 interface CoveredEntry {
     readonly kind: "covered";
     readonly family: SheetFamily;
@@ -57,8 +58,8 @@ interface NeverEntry {
 }
 interface BarrierEntry {
     readonly kind: "barrier";
-    /** The unit that owns its transform (C5b formulas, C5c resources) or "X" (no unit yet). */
-    readonly until: "C5b" | "C5c" | "X";
+    /** The unit that owns its transform (C5c resources) or "X" (no unit yet). */
+    readonly until: "C5c" | "X";
     readonly reason: string;
 }
 type RegistryEntry = CoveredEntry | NeverEntry | BarrierEntry;
@@ -102,7 +103,7 @@ declare function mapIndex(op: AxisOp, i: number): number | null;
  */
 declare function transformAxis(x: AxisOp, y: AxisOp, side: Side): AxisOp[] | null;
 
-declare const SHEET_TRANSFORMER_VERSION = "c5a-1";
+declare const SHEET_TRANSFORMER_VERSION = "c5b-1";
 /**
  * Pairs the fuzz proved divergent (or that have no transform yet), as unordered mutation-id pairs, with the
  * failing seed. Each returns a Barrier until it has its own correct transform under a new proto.
@@ -133,13 +134,24 @@ declare function mergeThrough(s: Structural, m: SheetRange): {
 declare function exactMergeRemovals(group: SheetGroup, merges: Readonly<Record<string, readonly SheetRange[]>>): SheetMutation[];
 type Cell = Record<string, unknown> | null;
 /** The content slot of a cell. A traveling entry that touches content must carry all of them (see completeCellContent). */
-declare const CONTENT_KEYS: readonly ["v", "t", "p", "f", "si", "custom"];
+declare const CONTENT_KEYS: readonly ["v", "t", "p", "f", "si", "custom", "ref", "xf", "ft", "fd"];
 /**
  * Completes a captured cell entry's content slot from the sender's post-state, so content writes are full
  * replacements (an entry that sets `v` alone would otherwise keep a stale `p` on some seats). C6's capture
  * calls this per touched cell with the cell as it stands right after the command.
  */
 declare function completeCellContent(entry: Cell, post: Record<string, unknown> | null | undefined): Cell;
+/** Params that travel for the transformer only; `forApply` strips them before Univer sees the mutation. */
+declare const SIDE_CAR_PARAMS: readonly ["refSheets", "previousName", "derived"];
+declare function forApply(m: SheetMutation): SheetMutation;
+/**
+ * Capture-time annotation (C6 calls it per group, like completeCellContent): every op whose formula text
+ * qualifies a reference with a sheet name gets `refSheets`, and every set-defined-name gets `previousName`
+ * (the name its id had before the command; null for a new name). Rewrites that follow a structural op, a
+ * rename or a defined-name change in the same group are marked `derived`. `sheets` is sheet id → name and
+ * `definedNames` defined-name id → name, both read right before the command ran.
+ */
+declare function annotateFormulas(group: SheetGroup, sheets: Readonly<Record<string, string>>, definedNames: Readonly<Record<string, string>>): SheetMutation[];
 /** x over y for single mutations. */
 declare function transformMutation(x: SheetMutation, y: SheetMutation, side: Side): TransformResult;
 /** Command group x rewritten to apply after command group y. One Barrier makes the whole group a barrier. */
@@ -156,4 +168,50 @@ declare const sheetTransformer: {
     isNoop(op: SheetGroup): boolean;
 };
 
-export { type Axis, type AxisOp, type Barrier, type BarrierEntry, CONTENT_KEYS, type CoveredEntry, type NeverEntry, PAIR_BARRIERS, type RegistryEntry, SHEET_MUTATIONS, SHEET_TRANSFORMER_VERSION, type SheetFamily, type SheetGroup, type SheetMutation, type SheetRange, type Side, type TransformResult, type Transformed, allowParams, cellRef, completeCellContent, exactMergeRemovals, isBarrier, mapIndex, mergeThrough, sheetTransformer, transformAxis, transformGroup, transformMutation };
+/** Sheet name → sheet id (null: the name is no sheet of this workbook). */
+type RefSheets = Readonly<Record<string, string | null>>;
+/** What changed under a formula: rows/columns of one sheet, or one sheet's name. */
+type RefChange = {
+    readonly kind: "axis";
+    readonly sheet: string;
+    readonly axis: Axis;
+    readonly op: AxisOp;
+} | {
+    readonly kind: "rename";
+    readonly sheet: string;
+    readonly name: string;
+} | {
+    readonly kind: "defined-name";
+    readonly from: string;
+    readonly to: string | null;
+};
+interface FormulaCtx {
+    /** The sheet the formula lives in (its unqualified references point here). */
+    readonly ownSheet: string;
+    readonly refSheets: RefSheets | undefined;
+    /** Defined names keep the sheet qualifier of a moved reference (sheets-formula `preserveSheetQualifier`). */
+    readonly keepQualifier?: boolean;
+}
+declare const REF_ERROR = "#REF!";
+declare const isFormulaText: (f: unknown) => f is string;
+/** Why a formula cannot be transformed (null = it can). */
+declare function formulaBarrier(text: string, ctx: FormulaCtx): string | null;
+interface Rewritten {
+    readonly text: string;
+    readonly changed: boolean;
+}
+/**
+ * The formula (or defined-name ref string) after `change`, exactly as Univer rewrites it: every reference into
+ * the changed sheet moves (or becomes #REF!), and once anything changed every other reference is re-serialized
+ * (`updateRefOffset`). Returns a reason string when the text cannot be transformed.
+ */
+declare function rewriteFormula(text: string, ctx: FormulaCtx, change: RefChange): Rewritten | string;
+/**
+ * An op's `refSheets` after a rename: the renamed sheet answers to its new name only, and a name that was
+ * no sheet before now names it. Unchanged (same object) when the rename touches nothing it lists.
+ */
+declare function refSheetsAfter(refSheets: RefSheets | undefined, change: RefChange): RefSheets | undefined;
+/** `refSheets` for the given formula texts: every sheet name they qualify a reference with, resolved now. */
+declare function refSheetsFor(texts: Iterable<string>, sheets: Readonly<Record<string, string>>): RefSheets | undefined;
+
+export { type Axis, type AxisOp, type Barrier, type BarrierEntry, CONTENT_KEYS, type CoveredEntry, type FormulaCtx, type NeverEntry, PAIR_BARRIERS, REF_ERROR, type RefChange, type RefSheets, type RegistryEntry, type Rewritten, SHEET_MUTATIONS, SHEET_TRANSFORMER_VERSION, SIDE_CAR_PARAMS, type SheetFamily, type SheetGroup, type SheetMutation, type SheetRange, type Side, type TransformResult, type Transformed, allowParams, annotateFormulas, cellRef, completeCellContent, exactMergeRemovals, forApply, formulaBarrier, isBarrier, isFormulaText, mapIndex, mergeThrough, refSheetsAfter, refSheetsFor, rewriteFormula, sheetTransformer, transformAxis, transformGroup, transformMutation };