@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/autofilter.js

@@ -1,7 +1,7 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { decodeRange, encodeAddress } from './address.js';
-import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+import { boundedRect, decodeRange, encodeRect } from './address.js';
+import { isDeletedSpan, shiftIndex, shiftRect } from './grid-shift.js';
 export const isCustomFilterOperator = tokenSet({
     equal: true,
     notEqual: true,
@@ -12,15 +12,16 @@ export const isCustomFilterOperator = tokenSet({
 });
 export function canonicalizeAutoFilter(input) {
     const ref = typeof input === 'string' ? input : input.ref;
-    const { top, left, bottom, right, dimensions } = decodeRange(ref);
-    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
-        throw new AuthoringError(`autofilter range "${ref}" must be a bounded rectangle`);
+    const decoded = decodeRange(ref);
+    const rect = boundedRect(decoded);
+    if (rect === undefined) {
+        throw new AuthoringError(`autofilter range ${quoted(ref)} must be a bounded rectangle`);
     }
     if (typeof input === 'string')
-        return { ref: dimensions, columns: [] };
-    const width = right - left + 1;
+        return { ref: decoded.dimensions, columns: [] };
+    const width = rect.right - rect.left + 1;
     return {
-        ref: dimensions,
+        ref: decoded.dimensions,
         columns: input.columns.map((column) => canonicalizeColumn(column, width)),
     };
 }
@@ -28,35 +29,35 @@ function canonicalizeColumn(column, width) {
     if (!Number.isInteger(column.colId) || column.colId < 0 || column.colId >= width) {
         throw new AuthoringError(`autofilter colId ${column.colId} is outside the filter range`);
     }
-    if (column.criteria.kind === 'custom') {
-        const count = column.criteria.predicates.length;
-        if (count < 1 || count > 2) {
-            throw new AuthoringError(`a custom filter needs one or two predicates, got ${count}`);
-        }
+    const criteria = column.criteria;
+    if (criteria.kind === 'values') {
+        return { colId: column.colId, criteria: { ...criteria, values: [...criteria.values] } };
     }
-    return column;
+    const count = criteria.predicates.length;
+    if (count < 1 || count > 2) {
+        throw new AuthoringError(`a custom filter needs one or two predicates, got ${count}`);
+    }
+    return {
+        colId: column.colId,
+        criteria: { ...criteria, predicates: criteria.predicates.map((predicate) => ({ ...predicate })) },
+    };
 }
-export function shiftAutoFilter(filter, axis, start, count, delta) {
-    const { top, left, bottom, right } = decodeRange(filter.ref);
-    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+export function shiftAutoFilter(filter, splice) {
+    const rect = boundedRect(decodeRange(filter.ref));
+    if (rect === undefined)
         return filter;
-    }
-    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
-    if (isDeletedSpan(lo, hi, start, count))
+    const moved = shiftRect(rect, splice);
+    if (moved === undefined)
         return undefined;
-    const movedLo = shiftIndex(lo, start, count, delta, axis);
-    const movedHi = shiftIndex(hi, start, count, delta, axis);
-    if (axis === 'row') {
-        const ref = `${encodeAddress(left, movedLo)}:${encodeAddress(right, movedHi)}`;
+    const ref = encodeRect(moved);
+    if (splice.axis === 'row')
         return { ref, columns: filter.columns };
-    }
-    const ref = `${encodeAddress(movedLo, top)}:${encodeAddress(movedHi, bottom)}`;
     const columns = [];
     for (const column of filter.columns) {
-        const absolute = left + column.colId;
-        if (isDeletedSpan(absolute, absolute, start, count))
+        const absolute = rect.left + column.colId;
+        if (isDeletedSpan(absolute, absolute, splice))
             continue;
-        columns.push({ ...column, colId: shiftIndex(absolute, start, count, delta, axis) - movedLo });
+        columns.push({ ...column, colId: shiftIndex(absolute, splice) - moved.left });
     }
     return { ref, columns };
 }

package/dist/core/axis-handle.d.ts

@@ -3,6 +3,8 @@ export declare abstract class AxisHandle<P extends object> {
     protected abstract propertiesOf(): P | undefined;
     /** This position's format record, created if it does not exist yet. */
     protected abstract ensureProperties(): P;
+    /** Remove this position's format record entirely, so nothing is left declaring the line. */
+    protected abstract dropProperties(): void;
     protected read<K extends keyof P>(key: K): P[K] | undefined;
     protected write<K extends keyof P>(key: K, value: P[K]): void;
 }

package/dist/core/axis-handle.js

@@ -5,8 +5,11 @@ export class AxisHandle {
     write(key, value) {
         if (value === undefined) {
             const properties = this.propertiesOf();
-            if (properties !== undefined)
-                delete properties[key];
+            if (properties === undefined)
+                return;
+            delete properties[key];
+            if (Object.keys(properties).length === 0)
+                this.dropProperties();
             return;
         }
         this.ensureProperties()[key] = value;

package/dist/core/cell.d.ts

@@ -139,9 +139,10 @@ export declare class Cell {
     set note(note: string | undefined);
 }
 /**
- * Whether a cell carries formatting of its own: one of the {@link CellStyle} facets, the quote-prefix
- * flag, or a link to a named style. Driven by {@link CELL_STYLE_FACETS}, so a facet added to the
- * tuple reaches every "is this cell blank" decision without anyone remembering to widen a literal.
+ * Whether a cell carries formatting of its own: any {@link CellContent} facet, which is the six shared
+ * style facets plus the quote-prefix flag and the link to a named style. Driven by
+ * {@link CELL_CONTENT_FACETS}, so a facet added to the tuple reaches every "is this cell blank"
+ * decision without anyone remembering to widen a literal.
  *
  * Row- and column-inherited formatting is not the cell's own and does not count. Neither does a
  * note: it lives in the comments part, not the cell's `<c>` element, so a writer deciding whether an

package/dist/core/cell.js

@@ -1,6 +1,6 @@
 import { assertColumnInBounds, assertRowInBounds, encodeAddress } from './address.js';
 import { NAMED_STYLE_ID } from './internal.js';
-import { assignStyleFacets, CELL_STYLE_FACETS, } from './style.js';
+import { assignContentFacets, assignStyleFacets, CELL_CONTENT_FACETS, } from './style.js';
 import { cellValueToText, coerceCellValue, detectValueType, } from './value.js';
 export class Cell {
     row;
@@ -107,9 +107,7 @@ export class Cell {
     }
 }
 export function cellHasOwnStyle(cell) {
-    return (CELL_STYLE_FACETS.some((facet) => cell[facet] !== undefined) ||
-        cell.quotePrefix === true ||
-        cell[NAMED_STYLE_ID] !== undefined);
+    return CELL_CONTENT_FACETS.some((facet) => cell[facet] !== undefined);
 }
 export function cellCarriesContent(cell) {
     return cell.value !== null || cell.note !== undefined || cellHasOwnStyle(cell);
@@ -119,7 +117,7 @@ export function applyCellStyle(cell, style) {
 }
 export function copyCellContent(source, target) {
     target.value = source.value;
-    applyCellStyle(target, source);
+    assignContentFacets(target, source);
     target.note = source.note;
 }
 export function cellToModel(cell) {
@@ -129,6 +127,6 @@ export function cellToModel(cell) {
         value: cell.value,
         note: cell.note,
     };
-    assignStyleFacets(model, cell);
+    assignContentFacets(model, cell);
     return model;
 }

package/dist/core/clone.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How far a copy of one field goes.
+ *
+ * - `'value'`: assign it. Correct for a scalar, and for anything genuinely immutable.
+ * - `'record'`: `{...v}`. A flat object whose own fields are scalars.
+ * - `'values'`: `[...v]`. An array of scalars.
+ * - `'records'`: `v.map(x => ({...x}))`. An array of flat objects.
+ * - a function: the field's own clone, for a nested type that has a plan of its own.
+ */
+export type CloneStrategy<V> = 'value' | 'record' | 'values' | 'records' | ((value: V) => V);
+/**
+ * One strategy per field of `T`. The `Record` is what makes a missing field a compile error.
+ *
+ * A field's strategy sees the field's type without `undefined`, because {@link cloneWith} skips an
+ * absent field rather than handing it over. Under `exactOptionalPropertyTypes` a facet declared
+ * `font?: Font | undefined` keeps that `undefined` through `Required`, so without the exclusion a
+ * nested type's own clone function would not satisfy its own field's strategy.
+ */
+export type ClonePlan<T> = {
+    readonly [K in keyof Required<T>]-?: CloneStrategy<Exclude<Required<T>[K], undefined>>;
+};
+/**
+ * Copy `source` according to `plan`, leaving a field absent when the source leaves it absent.
+ *
+ * Absent rather than `undefined`: every one of these types declares its optional fields under
+ * `exactOptionalPropertyTypes`, where a present-but-undefined key is a different shape from a missing
+ * one, and a round-trip that fabricated the first would report formatting a cell does not have.
+ */
+export declare function cloneWith<T extends object>(source: T, plan: ClonePlan<T>): T;

package/dist/core/clone.js

@@ -0,0 +1,24 @@
+export function cloneWith(source, plan) {
+    const out = {};
+    for (const key of Object.keys(plan)) {
+        const value = source[key];
+        if (value === undefined)
+            continue;
+        out[key] = applyStrategy(value, plan[key]);
+    }
+    return out;
+}
+function applyStrategy(value, strategy) {
+    if (typeof strategy === 'function')
+        return strategy(value);
+    switch (strategy) {
+        case 'value':
+            return value;
+        case 'record':
+            return { ...value };
+        case 'values':
+            return [...value];
+        case 'records':
+            return value.map((entry) => ({ ...entry }));
+    }
+}

package/dist/core/color-resolution.js

@@ -1,5 +1,6 @@
+import { hex } from '../hex.js';
 import { parseArgb } from './style.js';
-import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from './theme.js';
+import { DEFAULT_THEME_COLOR_SCHEME, isThemeRgb, THEME_COLOR_SLOTS, } from './theme.js';
 export const DEFAULT_INDEXED_COLORS = [
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
@@ -31,7 +32,7 @@ function resolveBase(color, context) {
         if (slot === undefined)
             return undefined;
         const value = (context.theme ?? DEFAULT_THEME_COLOR_SCHEME)[slot];
-        return value === undefined ? undefined : `FF${value.toUpperCase()}`;
+        return value !== undefined && isThemeRgb(value) ? `FF${value.toUpperCase()}` : undefined;
     }
     if (color.indexed !== undefined) {
         if (SYSTEM_INDEXED_COLORS.has(color.indexed))
@@ -102,8 +103,5 @@ function hueToChannel(p, q, offset) {
     return p;
 }
 function channelHex(value) {
-    return Math.round(clamp01(value) * 255)
-        .toString(16)
-        .toUpperCase()
-        .padStart(2, '0');
+    return hex(Math.round(clamp01(value) * 255), 2);
 }

package/dist/core/column.d.ts

@@ -21,6 +21,7 @@ export declare class Column extends AxisHandle<ColumnProperties> {
     get properties(): Readonly<ColumnProperties> | undefined;
     protected propertiesOf(): ColumnProperties | undefined;
     protected ensureProperties(): ColumnProperties;
+    protected dropProperties(): void;
     /**
      * Stable key naming this column so a keyed-object row (see {@link Worksheet.addRow}) can place a
      * value under it by name rather than position. In-memory only: never serialized to OOXML.

package/dist/core/column.js

@@ -1,4 +1,4 @@
-import { assertColumnInBounds, encodeAddress, numberToColumn } from './address.js';
+import { assertColumnInBounds, assertRowInBounds, numberToColumn } from './address.js';
 import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
 export class Column extends AxisHandle {
@@ -22,6 +22,9 @@ export class Column extends AxisHandle {
     ensureProperties() {
         return this.#sheet[INTERNAL].ensureColumnProperties(this.index);
     }
+    dropProperties() {
+        this.#sheet[INTERNAL].dropColumnProperties(this.index);
+    }
     get key() {
         return this.read('key');
     }
@@ -89,7 +92,8 @@ export class Column extends AxisHandle {
         this.write('protection', protection);
     }
     getCell(row) {
-        return this.#sheet.getCell(encodeAddress(this.index, row));
+        assertRowInBounds(row);
+        return this.#sheet[INTERNAL].masterAt(row, this.index);
     }
     get cells() {
         return this.#sheet[INTERNAL].columnCells(this.index);

package/dist/core/comment-thread.d.ts

@@ -55,11 +55,15 @@ export interface Comment {
     /** Brace-wrapped GUID identifying this message, preserved verbatim from the file. */
     readonly id: string;
     /**
-     * Who wrote it, resolved through the workbook registry. Absent when the file recorded no author or
-     * named an id the registry does not hold; {@link personId} distinguishes those two cases.
+     * Who wrote it, resolved through the workbook registry. Absent when the file recorded no author, or
+     * named an id the registry does not hold, which Excel treats the same way.
      */
     readonly author?: Person;
-    /** The author's {@link Person.id} exactly as written; absent when the file recorded no author. */
+    /**
+     * The author's {@link Person.id}, which must be registered ({@link Workbook.addPerson}) by the time
+     * the workbook is written. Absent for a message with no recorded author, which is written under the
+     * null GUID Excel uses for one and shown by Excel as "Author".
+     */
     readonly personId?: string;
     /**
      * When it was written, verbatim. Excel writes local wall-clock with fractional seconds and no

package/dist/core/comment-thread.js

@@ -1,9 +1,10 @@
+import { quoted } from '../errors.js';
 const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})\}?$/i;
 export function commentThreadGuid(value, what) {
     const match = GUID.exec(value.trim());
     if (match === null) {
         throw new SyntaxError(`${what} must be a GUID: Excel writes threaded-comment ids as ` +
-            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got "${value}"`);
+            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", but got ${quoted(value)}`);
     }
     return `{${match.slice(1).join('-').toUpperCase()}}`;
 }

package/dist/core/conditional-formatting-overlay.d.ts

@@ -1,4 +1,5 @@
 import { type ConditionalFormatting } from './conditional-formatting.ts';
+import type { AxisSplice } from './grid-shift.ts';
 export declare class ConditionalFormattingOverlay {
     #private;
     /**
@@ -6,6 +7,10 @@ export declare class ConditionalFormattingOverlay {
      * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
      * rule set. The block is stored once against the range, defensively copied so the getter never hands
      * back a reference into the caller's object.
+     *
+     * @throws {AuthoringError} when `formatting.ref` names no area at all. A rule set attached to
+     * nothing formats no cell and is written back as the same unreadable text, so it is a mistake worth
+     * surfacing at the call. The reader does not reach this: it drops such a block at its own boundary.
      */
     add(formatting: ConditionalFormatting): void;
     /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
@@ -14,7 +19,12 @@ export declare class ConditionalFormattingOverlay {
      * Re-anchor every rule set through a row or column splice, so a highlight keeps covering the cells
      * it was written for. A rule set whose every target area fell inside a deleted span goes with them.
      */
-    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
+    shift(splice: AxisSplice): void;
+    /**
+     * Rewrite every rule's formulae, and the value of each scale anchor whose type is `formula`, through
+     * `rewrite`, keeping a rule set nothing in which changed as the same object.
+     */
+    mapFormulas(rewrite: (formula: string) => string): void;
     /** Drop every conditional formatting, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/conditional-formatting-overlay.js

@@ -1,23 +1,50 @@
+import { AuthoringError, quoted } from '../errors.js';
 import { cloneConditionalFormatting } from './conditional-formatting.js';
 import { replaceContents } from './containers.js';
-import { shiftSqref } from './merge.js';
+import { decodeSqrefRects, shiftSqref } from './merge.js';
 export class ConditionalFormattingOverlay {
     #entries = [];
     add(formatting) {
+        if (decodeSqrefRects(formatting.ref).length === 0) {
+            throw new AuthoringError(`conditional formatting range ${quoted(formatting.ref)} names no cells`);
+        }
         this.#entries.push(cloneConditionalFormatting(formatting));
     }
     get entries() {
         return this.#entries;
     }
-    shift(axis, start, count, delta) {
+    shift(splice) {
         const entries = [];
         for (const entry of this.#entries) {
-            const ref = shiftSqref(entry.ref, axis, start, count, delta);
+            const ref = shiftSqref(entry.ref, splice);
             if (ref !== undefined)
                 entries.push({ ...entry, ref });
         }
         replaceContents(this.#entries, entries);
     }
+    mapFormulas(rewrite) {
+        for (const [index, entry] of this.#entries.entries()) {
+            let changed = false;
+            const rules = entry.rules.map((rule) => {
+                const formulae = rule.formulae?.map((operand) => typeof operand === 'string' ? rewrite(operand) : operand);
+                const cfvo = rule.cfvo?.map((anchor) => anchor.type === 'formula' && typeof anchor.value === 'string'
+                    ? { ...anchor, value: rewrite(anchor.value) }
+                    : anchor);
+                const formulaeMoved = formulae?.some((operand, i) => operand !== rule.formulae?.[i]) ?? false;
+                const cfvoMoved = cfvo?.some((anchor, i) => anchor.value !== rule.cfvo?.[i]?.value) ?? false;
+                if (!formulaeMoved && !cfvoMoved)
+                    return rule;
+                changed = true;
+                return {
+                    ...rule,
+                    ...(formulae === undefined ? {} : { formulae }),
+                    ...(cfvo === undefined ? {} : { cfvo }),
+                };
+            });
+            if (changed)
+                this.#entries[index] = { ...entry, rules };
+        }
+    }
     clear() {
         this.#entries.length = 0;
     }

package/dist/core/conditional-formatting.d.ts

@@ -1,16 +1,31 @@
-import type { Color, DifferentialStyle } from './style.ts';
-/** How a {@link CfValueObject} reads its `value`: `ST_CfvoType` verbatim. */
-export type CfValueObjectType = 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+import { type ClonePlan } from './clone.ts';
+import type { AssertNever } from './internal.ts';
+import { type Color } from './style.ts';
+import type { DifferentialStyle } from './workbook-styles.ts';
+/**
+ * How a {@link CfValueObject} reads its `value`: `ST_CfvoType` verbatim, with the `autoMin` and
+ * `autoMax` the 2009 extension adds.
+ */
+export type CfValueObjectType = 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula' | 'autoMin' | 'autoMax';
 /** Narrow a raw `<cfvo type>` token to a known {@link CfValueObjectType}. */
 export declare const isCfValueObjectType: (value: string) => value is CfValueObjectType;
 /**
  * One anchor of a colour-scale, data-bar, or icon-set scale: a "conditional format value object".
  * `type` names how `value` is read: a literal `num`, a `percent`/`percentile` of the range, a
  * `formula`, or the range's own `min`/`max` (which carry no value).
+ *
+ * `autoMin` and `autoMax` are the automatic anchors Excel 2010 gives a new data bar, and carry no value
+ * either. Only the extension form spells them, so a data bar using one is written with its extension,
+ * its classic element saying `min` or `max` in their place as Excel's does.
  */
 export interface CfValueObject {
     type: CfValueObjectType;
     value?: number | string;
+    /**
+     * Whether a value equal to this threshold reaches it. `false` makes an icon set's threshold a strict
+     * `>` rather than the `>=` the schema defaults to.
+     */
+    gte?: boolean;
 }
 /**
  * What a rule tests, as `<cfRule type>` carries it: `ST_CfType` verbatim.
@@ -37,21 +52,49 @@ export declare const isConditionalFormattingOperator: (value: string) => value i
 export type CfTimePeriod = 'today' | 'yesterday' | 'tomorrow' | 'last7Days' | 'thisMonth' | 'lastMonth' | 'nextMonth' | 'thisWeek' | 'lastWeek' | 'nextWeek';
 /** Narrow a raw `<cfRule timePeriod>` token to a known {@link CfTimePeriod}. */
 export declare const isCfTimePeriod: (value: string) => value is CfTimePeriod;
+/**
+ * Which way a data bar grows, as `ST_DataBarDirection` enumerates it: `context` follows the sheet's
+ * reading direction.
+ */
+export type DataBarDirection = 'context' | 'leftToRight' | 'rightToLeft';
+/** Narrow a raw `<x14:dataBar direction>` token to a known {@link DataBarDirection}. */
+export declare const isDataBarDirection: (value: string) => value is DataBarDirection;
+/**
+ * Where a data bar draws the axis between its negative and positive bars, as `ST_DataBarAxisPosition`
+ * enumerates it: where the values put it, at the middle of the cell, or nowhere, which grows a
+ * negative bar the way a positive one grows.
+ */
+export type DataBarAxisPosition = 'automatic' | 'middle' | 'none';
+/** Narrow a raw `<x14:dataBar axisPosition>` token to a known {@link DataBarAxisPosition}. */
+export declare const isDataBarAxisPosition: (value: string) => value is DataBarAxisPosition;
 /**
  * The named icon family an `iconSet` rule draws from, as `ST_IconSetType` enumerates it. The leading
  * digit is the number of icons, which is also how many {@link CfValueObject} anchors the rule needs.
  *
- * The 2009 extension adds three more families (`3Stars`, `3Triangles`, `5Boxes`) under its own
- * namespace. They are absent here because the classic `<iconSet>` element this list types cannot
- * carry them; a file using one states it in the extension, which the library round-trips verbatim.
+ * `3Stars`, `3Triangles` and `5Boxes` are the families the 2009 extension added. The classic
+ * `<iconSet>` element cannot name them, so a rule drawing from one is written in the extension form.
  */
-export type IconSetType = '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters';
+export type IconSetType = '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters' | '3Stars' | '3Triangles' | '5Boxes';
 /** Narrow a raw `<iconSet iconSet>` token to a known {@link IconSetType}. */
 export declare const isIconSetType: (value: string) => value is IconSetType;
+/** The families only the 2009 extension can name: a rule drawing from one is written there. */
+export declare function isExtensionIconSet(iconSet: IconSetType): boolean;
+/** The family a custom icon comes from: any {@link IconSetType}, or `NoIcons` for a threshold showing none. */
+export type CfIconSetType = IconSetType | 'NoIcons';
+/** Narrow a raw `<x14:cfIcon iconSet>` token to a known {@link CfIconSetType}. */
+export declare function isCfIconSetType(value: string): value is CfIconSetType;
+/** One threshold's icon in a custom icon set: icon number `iconId`, from 0, of the family `iconSet`. */
+export interface CfIcon {
+    iconSet: CfIconSetType;
+    iconId: number;
+}
 /**
  * A single conditional-formatting rule. `type` is the OOXML cfRule type; the remaining fields carry
  * the operands that type needs and are absent otherwise. A rule the library does not model in depth
  * still preserves `type`, `priority`, `operator`, `formulae`, and `dxfId` across a round-trip.
+ *
+ * A data bar's facets marked as x14 properties have no place in the classic `<dataBar>` element, so a
+ * bar carrying any of them, or an automatic anchor, is written with a linked `<x14:dataBar>` as well.
  */
 export interface ConditionalFormattingRule {
     type: ConditionalFormattingType;
@@ -75,14 +118,48 @@ export interface ConditionalFormattingRule {
     color?: Color;
     /** A colorScale's colours, one per {@link cfvo}. */
     colors?: Color[];
-    /** A dataBar's gradient-fill flag. Lives only in the x14 extension, not the classic element. */
+    /** A dataBar's shortest bar, as a percentage of the cell. */
+    minLength?: number;
+    /** A dataBar's longest bar, as a percentage of the cell. */
+    maxLength?: number;
+    /** A dataBar's gradient-fill flag. An x14 property. */
     gradient?: boolean;
-    /** A dataBar's fill colour for negative values. An x14 extension property. */
+    /** Whether a dataBar has a border, in {@link borderColor}. An x14 property. */
+    border?: boolean;
+    /** A dataBar's border colour. An x14 property. */
+    borderColor?: Color;
+    /** Which way a dataBar grows. An x14 property. */
+    direction?: DataBarDirection;
+    /** A dataBar's fill colour for negative values. An x14 property. */
     negativeFillColor?: Color;
+    /** A dataBar's border colour for negative values. An x14 property. */
+    negativeBorderColor?: Color;
+    /**
+     * Whether a dataBar fills a negative bar in its positive colour rather than
+     * {@link negativeFillColor}. An x14 property.
+     */
+    negativeBarColorSameAsPositive?: boolean;
+    /**
+     * Whether a dataBar borders a negative bar in its positive border colour rather than
+     * {@link negativeBorderColor}. An x14 property.
+     */
+    negativeBarBorderColorSameAsPositive?: boolean;
+    /** Where a dataBar draws the axis between negative and positive bars. An x14 property. */
+    axisPosition?: DataBarAxisPosition;
     /** A dataBar's axis colour (the zero line between positive and negative bars). An x14 property. */
     axisColor?: Color;
     /** An iconSet's named icon family (e.g. `3TrafficLights1`). */
     iconSet?: IconSetType;
+    /**
+     * A custom iconSet's icons, one per {@link cfvo} threshold in order, each replacing the icon
+     * {@link iconSet} would show there. Only the extension form carries them, so a rule with icons is
+     * written in it.
+     */
+    icons?: CfIcon[];
+    /** iconSet: the icons in reverse order, the highest threshold showing the family's first icon. */
+    reverse?: boolean;
+    /** dataBar / iconSet: whether the cell still shows its value beside the bar or icon. */
+    showValue?: boolean;
     /** top10 rank cutoff. */
     rank?: number;
     /** top10: the rank is a percentage rather than a count. */
@@ -98,13 +175,32 @@ export interface ConditionalFormattingRule {
     /** timePeriod window (`today`, `lastWeek`, …). */
     timePeriod?: CfTimePeriod;
 }
-/** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref`: one or more
+/**
+ * A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref`: one or more
  * space-separated areas (`"A1:C1 A3:C3 A5:C5"`), the shape Excel writes when one rule is applied to
- * several non-contiguous selections at once. */
+ * several non-contiguous selections at once.
+ *
+ * `extended` marks a set stored in the 2009 extension form (`<x14:conditionalFormatting>` inside the
+ * worksheet `<extLst>`), where Excel puts a rule whose formula reaches another sheet. The reader sets
+ * it for a set found in that form so a round-trip writes the set back there. A rule only that form can
+ * express, one drawing from a 2009 icon family or carrying custom icons, is written there whatever the
+ * flag says.
+ */
 export interface ConditionalFormatting {
     ref: string;
     rules: ConditionalFormattingRule[];
+    extended?: boolean;
 }
 /** A defensive deep copy, so a stored conditional formatting never aliases the caller's object nor
  * any of its nested arrays (rules, formulae, cfvo, colours) or the differential style. */
 export declare function cloneConditionalFormatting(cf: ConditionalFormatting): ConditionalFormatting;
+/**
+ * Whether a rule needs the extension form: it names a family or custom icons the classic element has
+ * no way to spell.
+ */
+export declare function ruleNeedsExtension(rule: ConditionalFormattingRule): boolean;
+declare const RULE_CLONE: ClonePlan<ConditionalFormattingRule>;
+export type EveryRuleFieldIsCloned = AssertNever<Exclude<keyof Required<ConditionalFormattingRule>, keyof typeof RULE_CLONE>>;
+declare const STYLE_CLONE: ClonePlan<DifferentialStyle>;
+export type EveryDifferentialStyleFieldIsCloned = AssertNever<Exclude<keyof Required<DifferentialStyle>, keyof typeof STYLE_CLONE>>;
+export {};