@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/xlsx/conditional-formatting.d.ts

@@ -1,33 +1,53 @@
-import { type ConditionalFormatting } from '../../core/conditional-formatting.ts';
+import { type ConditionalFormatting, type ConditionalFormattingRule } from '../../core/conditional-formatting.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
 import { type CollectingPass } from '../../xml/xml-read.ts';
 import type { StyleRegistry } from './styles.ts';
 /**
- * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
- * insertion order. Returns '' when the sheet has none. A rule missing a `priority` is assigned the
- * next free one, so the output always satisfies Excel's requirement that every cfRule carry one.
+ * What the classic pass and the extension pass must agree on about a sheet's conditional formats,
+ * decided once and handed to both. A classic data bar's link and the `<x14:cfRule>` it names have to
+ * carry one id, and two rules in different forms must not be numbered alike, and each pass deriving its
+ * half itself makes both agreements hold by the two walks happening to visit the rules in one order.
  */
-export declare function conditionalFormattingsXml(formattings: readonly ConditionalFormatting[], styles: StyleRegistry): string;
+export interface ConditionalFormattingPlan {
+    /** Every rule's priority: its own, or the next one free after every priority before it. */
+    readonly priorities: ReadonlyMap<ConditionalFormattingRule, number>;
+    /**
+     * The id of every rule with an `<x14:cfRule>`: a rule written wholly in the extension, and a classic
+     * data bar whose extra facets ride there. A rule absent from the map needs no extension.
+     */
+    readonly extensionIds: ReadonlyMap<ConditionalFormattingRule, string>;
+}
+/** Plan a sheet's conditional formats, in insertion order, for both serialisers. */
+export declare function planConditionalFormatting(formattings: readonly ConditionalFormatting[]): ConditionalFormattingPlan;
 /**
- * The worksheet `<extLst>` `<ext>` carrying the x14 data-bar extensions, or '' when no data bar needs
- * one. Each extension's `<x14:cfRule id>` is read from the same {@link dataBarExtLinks} map the classic
- * pass uses for the `<x14:id>` its cfRule carries, so the two ends of a link always match. Emitted bare
- * (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single `<extLst>` beside the
- * data-validation extension.
+ * Serialise the classic `<conditionalFormatting>` blocks of a sheet, in insertion order, leaving out
+ * every rule {@link conditionalFormattingsExtXml} writes in the extension form. Returns '' when no rule
+ * remains.
+ *
+ * A rule's formulas, its operands and a `formula` anchor alike, are stored with the function prefixes
+ * a cell formula takes, as Excel stores them; `formulaNames` is `formulaNamesInScope` for the sheet.
  */
-export declare function conditionalFormattingsExtXml(formattings: readonly ConditionalFormatting[]): string;
+export declare function conditionalFormattingsXml(formattings: readonly ConditionalFormatting[], styles: StyleRegistry, plan: ConditionalFormattingPlan, formulaNames: ReadonlySet<string>): string;
 /**
- * A pass reading a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
- * blocks supply every rule; the x14 extension (`<x14:conditionalFormatting>` inside `<extLst>`) is
- * read only to enrich a classic data bar with the facets the classic element cannot carry (the
- * gradient flag and the negative-fill and axis colours) matched by the shared id the two ends link
- * on. An extension rule with no classic counterpart (a rule that lives only in x14) is ignored, so it
- * is never half-read into a broken classic rule.
+ * The worksheet `<extLst>` `<ext>` carrying the sheet's extension-form conditional formats, or '' when
+ * it needs none: every rule written wholly there, grouped under its set's range, and every classic data
+ * bar's extra facets, under the id the plan gave the link its cfRule carries. Emitted bare (no
+ * `<extLst>` wrapper) so the worksheet serialiser can gather it into a single `<extLst>` beside the
+ * data-validation extension.
  */
-export declare function conditionalFormattingPass(): CollectingPass<ConditionalFormatting[]>;
+export declare function conditionalFormattingsExtXml(formattings: readonly ConditionalFormatting[], styles: StyleRegistry, plan: ConditionalFormattingPlan, formulaNames: ReadonlySet<string>): string;
 /**
- * Extract the differential-style (`<dxf>`) fragments from styles.xml, each verbatim. Preserving the
- * raw XML, rather than reparsing and re-serialising, is what keeps a foreign dxf's number format a
- * real format code on re-write instead of a coerced `"[object Object]"`, and keeps every conditional
- * formatting's `dxfId` index pointing at the same style it did in the source file.
+ * A pass reading a worksheet's conditional formatting into the model, from both forms.
+ *
+ * The classic `<conditionalFormatting>` blocks come first. Each `<x14:conditionalFormatting>` in the
+ * worksheet extension that follows them is read as a set of its own, marked `extended`, unless its rule
+ * is a data bar a classic rule links to by id: that one only completes the classic rule with the facets
+ * and automatic anchors the classic element cannot carry. An extension rule's inline style is handed to
+ * `adoptDifferentialStyle`, which answers the index the rule then holds as its `dxfId`.
+ *
+ * A rule's formulas shed their function prefixes as a cell formula's do, against `definedNames`, the
+ * workbook's names as `definedNameKeys` spells them.
  */
-export declare function parseDxfs(stylesXml: string): string[];
+export declare function conditionalFormattingPass(definedNames: ReadonlySet<string>, adoptDifferentialStyle: (fragment: string) => number): CollectingPass<ConditionalFormatting[]>;
+/** Fold parsed conditional formattings onto a sheet, each bound to its original range. */
+export declare function applyConditionalFormattings(sheet: Worksheet, blocks: readonly ConditionalFormatting[]): void;