@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/styles.d.ts

@@ -0,0 +1,138 @@
+import { type Alignment, type Border, type Color, type DifferentialStyle, type Fill, type Font, type NamedCellStyle, type Protection, type TableStyleTable } from '../../core/style.ts';
+import { type TableStyle } from '../../core/table-style.ts';
+/** A cell's style facets as the writer composes them: cell overrides atop row/column defaults. */
+export interface CellStyle {
+    readonly fill?: Fill | undefined;
+    readonly numFmt?: string | undefined;
+    readonly font?: Font | undefined;
+    readonly border?: Border | undefined;
+    readonly alignment?: Alignment | undefined;
+    readonly protection?: Protection | undefined;
+    /** The quote-prefix flag — an attribute on the xf, not a shared sub-table entry. */
+    readonly quotePrefix?: boolean | undefined;
+    /** The `xfId` link into `cellStyleXfs` — the named cell style this format inherits from (0 = Normal). */
+    readonly xfId?: number | undefined;
+}
+/** What a {@link StyleRegistry} needs from its workbook before any style is interned. */
+export interface StyleRegistryOptions {
+    /**
+     * The font every cell naming none of its own renders in — emitted as id 0. Take it from
+     * {@link Workbook.defaultFont}, which resolves the authored/declared/theme chain and guarantees a
+     * complete entry. Omitted, the registry falls back to the Office default.
+     */
+    readonly defaultFont?: Font;
+    /**
+     * The default font the *source package* declared, when a workbook was read
+     * ({@link Workbook.declaredDefaultFont}). It also interns to id 0, which is what lets an authored
+     * default font reach cells the reader had already resolved.
+     *
+     * The reader flattens font 0 onto every xf that names it, so a cell that merely inherited the
+     * file's default arrives carrying it as a concrete face. That face is an artefact of reading, not
+     * an authored intent — in the source file the cell said nothing about its font — so it must
+     * collapse back to id 0 and follow the new default rather than pin itself to the old one through a
+     * custom entry.
+     */
+    readonly declaredDefaultFont?: Font;
+}
+export declare class StyleRegistry {
+    #private;
+    constructor(options?: StyleRegistryOptions);
+    /**
+     * The `<cellXfs>` index for a composed cell/row/column style. A style with no facet needs
+     * no entry and resolves to the default xf 0, so its owner emits no `s` attribute at all.
+     */
+    styleId(style: CellStyle): number;
+    /**
+     * Seed the named cell styles (`<cellStyleXfs>`/`<cellStyles>`) read from a file, in place of the
+     * lone default, interning each style's facets into the shared sub-tables so its `fillId`/`fontId`/…
+     * references stay valid against the rebuilt tables. Index 0 stays Normal. A cell's `xfId` indexes
+     * this table, so it must be seeded before any {@link styleId} that carries an `xfId`.
+     */
+    seedNamedStyles(styles: readonly NamedCellStyle[]): void;
+    /**
+     * Seed the differential-style table with fragments read from a file, keeping each `<dxf>…</dxf>`
+     * verbatim and at its original index. Call once before any {@link differentialStyleId}; authored
+     * styles append after these.
+     *
+     * **Index stability is a contract, not an implementation detail.** A `dxfId` is an index into this
+     * one table, and more than one preserved construct resolves through it: a conditional-formatting
+     * rule's `dxfId`, and every `<tableStyleElement dxfId="…">` inside a preserved `<tableStyle>` (see
+     * {@link seedTableStyles}). Those constructs are carried as opaque XML precisely *because* the
+     * indices they name do not move. Renumbering, reordering, or de-duplicating the seeded entries
+     * would silently re-point every one of them at a different format — a change no schema check and no
+     * round-trip of our own can catch, because the file stays perfectly valid and merely renders wrong.
+     */
+    seedDifferentialStyles(fragments: readonly string[]): void;
+    /**
+     * Seed the custom indexed-color palette (`<colors><indexedColors>`) read from a file, each entry a
+     * verbatim `<rgbColor rgb="…"/>` fragment. Re-emitting it unchanged is what keeps an `indexed="…"`
+     * colour reference resolving to the RGB the source intended. An empty list leaves the workbook on
+     * the default palette and emits no `<colors>` element.
+     */
+    seedIndexedColors(fragments: readonly string[]): void;
+    /**
+     * Seed the most-recently-used colour swatches (`<colors><mruColors>`) read from a file, each entry a
+     * verbatim `<color rgb="…"/>` fragment. An empty list emits no `<mruColors>` element.
+     */
+    seedMruColors(fragments: readonly string[]): void;
+    /**
+     * Seed the custom table-style definitions (`<tableStyles>`) read from a file, each `<tableStyle>`
+     * kept verbatim so a table's `tableStyleInfo/@name` still resolves and each element's `dxfId` still
+     * indexes the differential-style table {@link seedDifferentialStyles} preserves at its original
+     * indices. Replaces any block already held.
+     */
+    seedTableStyles(table: TableStyleTable): void;
+    /**
+     * Serialise a table style authored on the workbook, interning each element's formatting into the
+     * differential-style table and emitting the `dxfId` that reaches it. Call after
+     * {@link seedTableStyles}, whose preserved definitions these append after.
+     *
+     * A definition here **replaces** a preserved one of the same name. Two `<tableStyle>` elements
+     * sharing a name is ambiguous — a table's `tableStyleInfo/@name` would reach whichever a consumer
+     * happened to index first — so authoring a name the source already used is read as overriding it,
+     * which is what asking for it means.
+     */
+    addTableStyle(style: TableStyle): void;
+    /**
+     * Intern an authored differential style, returning the `<dxfs>` index that references it — a
+     * conditional-formatting rule's `dxfId`, or a table style element's. Identical styles collapse to
+     * one entry, whichever feature asked for them, so a highlight rule and a table style's header row
+     * painted the same way share a single `<dxf>`.
+     *
+     * Authored entries append after the seeded ones ({@link seedDifferentialStyles}), which is what
+     * keeps every preserved reference pointing where it did.
+     */
+    differentialStyleId(style: DifferentialStyle): number;
+    /** Serialise the accumulated table into a complete, valid styles.xml part. */
+    toXml(): string;
+}
+/**
+ * Extract the custom indexed-color palette (`<colors><indexedColors>`) from styles.xml as verbatim
+ * `<rgbColor rgb="…"/>` fragments, or an empty list when the file rides the default palette. Kept raw
+ * — rather than parsed into RGB and re-serialised — so the exact entries (count, order, casing) a
+ * source file declared survive a round-trip and every `indexed="…"` reference keeps its RGB.
+ */
+export declare function parseIndexedColors(stylesXml: string): string[];
+/**
+ * Extract the most-recently-used colour swatches (`<colors><mruColors>`) from styles.xml as verbatim
+ * `<color .../>` fragments, or an empty list when the file declares none. Kept raw for the same reason
+ * the indexed palette is: the list is the author's own working set of colours and the model has no
+ * use for its contents, only for not losing them.
+ */
+export declare function parseMruColors(stylesXml: string): string[];
+/**
+ * Extract the `<tableStyles>` block from styles.xml: each `<tableStyle>` definition verbatim, plus the
+ * container's nominated `defaultTableStyle`/`defaultPivotStyle`. See {@link TableStyleTable} for why
+ * the definitions stay raw while the two names are decoded.
+ *
+ * A file with no such block — or with the self-closing `count="0"` container Excel writes when it has
+ * only defaults to state — yields an empty {@link TableStyleTable.styles} and whichever names it did
+ * carry.
+ */
+export declare function parseTableStyles(stylesXml: string): TableStyleTable;
+export declare function fontXml(font: Font, nameTag?: 'name' | 'rFont'): string;
+export declare function dxfXml(style: DifferentialStyle): string;
+export declare function colorAttrs(color: Color): string;
+export declare function parseColor(attrs: {
+    readonly [k: string]: string;
+}): Color;