@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/tables/borders.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Customer-facing table/cell border facades (`Border` / `Borders`).
+ *
+ * Backed by internal `TableBorder` bags; unknown `@w:val` tokens stay on the
+ * wire bag and do not surface as public BorderStyle values.
+ * `space` lives on Borders only (not on Border).
+ */
+import { BorderStyle } from '../document/page-setup';
+import { Color } from '../document/color';
+import { TableBorder, TableBorders, TableCellBorders } from './tbl-pr';
+/** @private */
+export declare type BorderBagHost = {
+    readEdge(key: BorderEdgeKey): TableBorder | undefined;
+    writeEdge(key: BorderEdgeKey, edge: TableBorder | undefined): void;
+};
+/**
+ * Keys for outer and inside edges (no diagonals on the public surface).
+ *
+ * @private
+ */
+export declare type BorderEdgeKey = 'top' | 'bottom' | 'left' | 'right' | 'insideH' | 'insideV';
+/**
+ * One border edge.
+ *
+ * @public
+ */
+export declare class Border {
+    private readonly host;
+    private readonly key;
+    /**
+     * @private
+     */
+    constructor(host: BorderBagHost, key: BorderEdgeKey);
+    private current;
+    private commit;
+    /**
+     * Wire `@w:val` for commits. When the edge has no style yet, default to
+     * `'single'` so color/size/space/shadow survive `serializeBorderEdge`
+     * (which requires `w:val`) and round-trip through tblPr XML — same as
+     * paragraph border faces.
+     * @private
+     */
+    private styleWireForCommit;
+    /** Line style. Unknown loaded values return the public default and round-trip. */
+    borderType: BorderStyle;
+    /**
+     * Hex RGB or `'auto'`.
+     * Setter also accepts a {@link Color} enum value and optional leading `#` on hex strings.
+     * Getter always returns the OOXML wire string.
+     * Setting color without a prior `borderType` defaults the edge to single so the edge serializes.
+     */
+    color: string | Color;
+    /**
+     * Thickness in points (public); stored as eighths of a point on the wire.
+     * Setting lineWidth without a prior `borderType` defaults the edge to single so the edge serializes.
+     */
+    lineWidth: number;
+    /** Shadow flag (`w:shadow`). */
+    shadow: boolean;
+    /**
+     * @private
+     * Internal edge space (points) used by Borders.space.
+     */
+    readSpacePoints(): number;
+    /**
+     * @private
+     */
+    writeSpacePoints(value: number): void;
+}
+/**
+ * Aggregate borders for a table or cell (no public diagonals).
+ *
+ * @public
+ */
+export declare class Borders {
+    private readonly host;
+    private readonly topBorder;
+    private readonly bottomBorder;
+    private readonly leftBorder;
+    private readonly rightBorder;
+    private readonly horizontalBorder;
+    private readonly verticalBorder;
+    private readonly includeInside;
+    /**
+     * @private
+     */
+    constructor(host: BorderBagHost, includeInside?: boolean);
+    readonly top: Border;
+    readonly bottom: Border;
+    readonly left: Border;
+    readonly right: Border;
+    readonly horizontal: Border;
+    readonly vertical: Border;
+    private aggregateKeys;
+    private edgeAt;
+    /**
+     * Common border type across applicable edges.
+     * Mixed or absent edges return the public default (BorderStyle.None).
+     */
+    borderType: BorderStyle;
+    /**
+     * Common border color across applicable edges.
+     * Mixed edges return the public default (`'auto'`).
+     * Setter accepts hex/`'auto'`, optional leading `#`, or a {@link Color} enum value.
+     */
+    color: string | Color;
+    lineWidth: number;
+    /**
+     * Common edge w:space (points) across applicable edges.
+     * Mixed values return the public default 0.
+     */
+    space: number;
+    shadow: boolean;
+}
+/**
+ * Host that reads/writes a full TableBorders bag via callbacks.
+ *
+ * @private
+ */
+export declare function createTableBordersHost(read: () => TableBorders | undefined, write: (value: TableBorders | undefined) => void): BorderBagHost;
+/**
+ * Host for cell borders; preserves diagonal edges when rewriting.
+ *
+ * @private
+ */
+export declare function createCellBordersHost(read: () => TableCellBorders | undefined, write: (value: TableCellBorders | undefined) => void): BorderBagHost;

package/src/features/tables/borders.js

@@ -0,0 +1,527 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+/**
+ * Customer-facing table/cell border facades (`Border` / `Borders`).
+ *
+ * Backed by internal `TableBorder` bags; unknown `@w:val` tokens stay on the
+ * wire bag and do not surface as public BorderStyle values.
+ * `space` lives on Borders only (not on Border).
+ */
+import { BorderStyle } from '../document/page-setup';
+import { colorToHexWire, normalizeColorHex } from '../document/color';
+import { borderStyleFromWire, borderStyleToWire, isKnownBorderWire } from './border-style-map';
+var ALL_EDGE_KEYS = ['top', 'bottom', 'left', 'right', 'insideH', 'insideV'];
+var OUTER_EDGE_KEYS = ['top', 'bottom', 'left', 'right'];
+var DEFAULT_BORDER_TYPE = BorderStyle.None;
+var DEFAULT_COLOR = 'auto';
+var DEFAULT_LINE_WIDTH = 0;
+var DEFAULT_SPACE = 0;
+var DEFAULT_SHADOW = false;
+function requireFiniteNonNegative(value, label) {
+    if (typeof value !== 'number' || !isFinite(value) || value < 0) {
+        throw new RangeError(label + ' must be a finite non-negative number');
+    }
+}
+function isBorderStyleValue(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    if (isKnownBorderWire(value)) {
+        return true;
+    }
+    if (borderStyleFromWire(value) !== undefined) {
+        return true;
+    }
+    var keys = Object.keys(BorderStyle);
+    for (var i = 0; i < keys.length; i += 1) {
+        if (BorderStyle[keys[i]] === value) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalize border color input to OOXML wire (`RRGGBB` / `'auto'`).
+ * {@link Color} becomes hex; {@link Color.Transparent} maps to `'auto'`.
+ * Strings may include a leading `#`.
+ * @private
+ */
+function borderColorToWire(value) {
+    if (typeof value === 'number') {
+        var hex_1 = colorToHexWire(value);
+        return hex_1.length > 0 ? hex_1 : 'auto';
+    }
+    if (typeof value !== 'string') {
+        throw new RangeError('Border color must be a string, Color, or hex color');
+    }
+    var raw = value.trim();
+    if (raw.length === 0) {
+        throw new RangeError('Border color must be a non-empty string');
+    }
+    if (raw.toLowerCase() === 'auto') {
+        return 'auto';
+    }
+    var hex = normalizeColorHex(raw);
+    if (hex !== undefined) {
+        return hex;
+    }
+    // Preserve unknown loaded tokens for round-trip (e.g. theme-ish values).
+    return value;
+}
+/**
+ * One border edge.
+ *
+ * @public
+ */
+var Border = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function Border(host, key) {
+        this.host = host;
+        this.key = key;
+    }
+    Border.prototype.current = function () {
+        var edge = this.host.readEdge(this.key);
+        return edge !== undefined ? edge : {};
+    };
+    Border.prototype.commit = function (next) {
+        var has = next.style !== undefined ||
+            next.color !== undefined ||
+            next.size !== undefined ||
+            next.space !== undefined ||
+            next.shadow !== undefined;
+        this.host.writeEdge(this.key, has ? next : undefined);
+    };
+    /**
+     * Wire `@w:val` for commits. When the edge has no style yet, default to
+     * `'single'` so color/size/space/shadow survive `serializeBorderEdge`
+     * (which requires `w:val`) and round-trip through tblPr XML — same as
+     * paragraph border faces.
+     * @private
+     */
+    Border.prototype.styleWireForCommit = function (cur) {
+        return cur.style !== undefined ? cur.style : 'single';
+    };
+    Object.defineProperty(Border.prototype, "borderType", {
+        /** Line style. Unknown loaded values return the public default and round-trip. */
+        get: function () {
+            var style = this.current().style;
+            if (style === undefined) {
+                return DEFAULT_BORDER_TYPE;
+            }
+            var mapped = borderStyleFromWire(style);
+            return mapped !== undefined ? mapped : DEFAULT_BORDER_TYPE;
+        },
+        set: function (value) {
+            if (!isBorderStyleValue(value)) {
+                throw new RangeError('Unsupported BorderStyle value');
+            }
+            var cur = this.current();
+            this.commit({
+                style: borderStyleToWire(value),
+                color: cur.color,
+                size: cur.size,
+                space: cur.space,
+                shadow: cur.shadow,
+            });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Border.prototype, "color", {
+        /**
+         * Hex RGB or `'auto'`.
+         * Setter also accepts a {@link Color} enum value and optional leading `#` on hex strings.
+         * Getter always returns the OOXML wire string.
+         * Setting color without a prior `borderType` defaults the edge to single so the edge serializes.
+         */
+        get: function () {
+            var c = this.current().color;
+            return c !== undefined ? c : DEFAULT_COLOR;
+        },
+        set: function (value) {
+            var wire = borderColorToWire(value);
+            var cur = this.current();
+            this.commit({
+                style: this.styleWireForCommit(cur),
+                color: wire,
+                size: cur.size,
+                space: cur.space,
+                shadow: cur.shadow,
+            });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Border.prototype, "lineWidth", {
+        /**
+         * Thickness in points (public); stored as eighths of a point on the wire.
+         * Setting lineWidth without a prior `borderType` defaults the edge to single so the edge serializes.
+         */
+        get: function () {
+            var size = this.current().size;
+            return size !== undefined ? size / 8 : DEFAULT_LINE_WIDTH;
+        },
+        set: function (value) {
+            requireFiniteNonNegative(value, 'Border lineWidth');
+            var cur = this.current();
+            this.commit({
+                style: this.styleWireForCommit(cur),
+                color: cur.color,
+                size: Math.round(value * 8),
+                space: cur.space,
+                shadow: cur.shadow,
+            });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Border.prototype, "shadow", {
+        /** Shadow flag (`w:shadow`). */
+        get: function () {
+            var s = this.current().shadow;
+            return s !== undefined ? s : DEFAULT_SHADOW;
+        },
+        set: function (value) {
+            if (typeof value !== 'boolean') {
+                throw new RangeError('Border shadow must be a boolean');
+            }
+            var cur = this.current();
+            this.commit({
+                style: this.styleWireForCommit(cur),
+                color: cur.color,
+                size: cur.size,
+                space: cur.space,
+                shadow: value,
+            });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     * Internal edge space (points) used by Borders.space.
+     */
+    Border.prototype.readSpacePoints = function () {
+        var s = this.current().space;
+        return s !== undefined ? s : DEFAULT_SPACE;
+    };
+    /**
+     * @private
+     */
+    Border.prototype.writeSpacePoints = function (value) {
+        requireFiniteNonNegative(value, 'Borders space');
+        var cur = this.current();
+        this.commit({
+            style: this.styleWireForCommit(cur),
+            color: cur.color,
+            size: cur.size,
+            space: value,
+            shadow: cur.shadow,
+        });
+    };
+    return Border;
+}());
+export { Border };
+/**
+ * Aggregate borders for a table or cell (no public diagonals).
+ *
+ * @public
+ */
+var Borders = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function Borders(host, includeInside) {
+        if (includeInside === void 0) { includeInside = true; }
+        this.host = host;
+        this.includeInside = includeInside;
+        this.topBorder = new Border(host, 'top');
+        this.bottomBorder = new Border(host, 'bottom');
+        this.leftBorder = new Border(host, 'left');
+        this.rightBorder = new Border(host, 'right');
+        this.horizontalBorder = new Border(host, 'insideH');
+        this.verticalBorder = new Border(host, 'insideV');
+    }
+    Object.defineProperty(Borders.prototype, "top", {
+        get: function () {
+            return this.topBorder;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "bottom", {
+        get: function () {
+            return this.bottomBorder;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "left", {
+        get: function () {
+            return this.leftBorder;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "right", {
+        get: function () {
+            return this.rightBorder;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "horizontal", {
+        get: function () {
+            return this.horizontalBorder;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "vertical", {
+        get: function () {
+            return this.verticalBorder;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Borders.prototype.aggregateKeys = function () {
+        return this.includeInside ? ALL_EDGE_KEYS : OUTER_EDGE_KEYS;
+    };
+    Borders.prototype.edgeAt = function (key) {
+        return new Border(this.host, key);
+    };
+    Object.defineProperty(Borders.prototype, "borderType", {
+        /**
+         * Common border type across applicable edges.
+         * Mixed or absent edges return the public default (BorderStyle.None).
+         */
+        get: function () {
+            var keys = this.aggregateKeys();
+            var common;
+            var saw = false;
+            for (var i = 0; i < keys.length; i += 1) {
+                var t = this.edgeAt(keys[i]).borderType;
+                if (!saw) {
+                    common = t;
+                    saw = true;
+                }
+                else if (t !== common) {
+                    return DEFAULT_BORDER_TYPE;
+                }
+            }
+            return common !== undefined ? common : DEFAULT_BORDER_TYPE;
+        },
+        set: function (value) {
+            if (!isBorderStyleValue(value)) {
+                throw new RangeError('Unsupported BorderStyle value');
+            }
+            var keys = this.aggregateKeys();
+            for (var i = 0; i < keys.length; i += 1) {
+                this.edgeAt(keys[i]).borderType = value;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "color", {
+        /**
+         * Common border color across applicable edges.
+         * Mixed edges return the public default (`'auto'`).
+         * Setter accepts hex/`'auto'`, optional leading `#`, or a {@link Color} enum value.
+         */
+        get: function () {
+            var keys = this.aggregateKeys();
+            var common;
+            var saw = false;
+            for (var i = 0; i < keys.length; i += 1) {
+                var c = this.edgeAt(keys[i]).color;
+                if (!saw) {
+                    common = c;
+                    saw = true;
+                }
+                else if (c !== common) {
+                    return DEFAULT_COLOR;
+                }
+            }
+            return common !== undefined ? common : DEFAULT_COLOR;
+        },
+        set: function (value) {
+            var keys = this.aggregateKeys();
+            for (var i = 0; i < keys.length; i += 1) {
+                this.edgeAt(keys[i]).color = value;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "lineWidth", {
+        get: function () {
+            var keys = this.aggregateKeys();
+            var common;
+            var saw = false;
+            for (var i = 0; i < keys.length; i += 1) {
+                var w = this.edgeAt(keys[i]).lineWidth;
+                if (!saw) {
+                    common = w;
+                    saw = true;
+                }
+                else if (w !== common) {
+                    return DEFAULT_LINE_WIDTH;
+                }
+            }
+            return common !== undefined ? common : DEFAULT_LINE_WIDTH;
+        },
+        set: function (value) {
+            requireFiniteNonNegative(value, 'Borders lineWidth');
+            var keys = this.aggregateKeys();
+            for (var i = 0; i < keys.length; i += 1) {
+                this.edgeAt(keys[i]).lineWidth = value;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "space", {
+        /**
+         * Common edge w:space (points) across applicable edges.
+         * Mixed values return the public default 0.
+         */
+        get: function () {
+            var keys = this.aggregateKeys();
+            var common;
+            var saw = false;
+            for (var i = 0; i < keys.length; i += 1) {
+                var s = this.edgeAt(keys[i]).readSpacePoints();
+                if (!saw) {
+                    common = s;
+                    saw = true;
+                }
+                else if (s !== common) {
+                    return DEFAULT_SPACE;
+                }
+            }
+            return common !== undefined ? common : DEFAULT_SPACE;
+        },
+        set: function (value) {
+            requireFiniteNonNegative(value, 'Borders space');
+            var keys = this.aggregateKeys();
+            for (var i = 0; i < keys.length; i += 1) {
+                this.edgeAt(keys[i]).writeSpacePoints(value);
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Borders.prototype, "shadow", {
+        get: function () {
+            var keys = this.aggregateKeys();
+            var common;
+            var saw = false;
+            for (var i = 0; i < keys.length; i += 1) {
+                var s = this.edgeAt(keys[i]).shadow;
+                if (!saw) {
+                    common = s;
+                    saw = true;
+                }
+                else if (s !== common) {
+                    return DEFAULT_SHADOW;
+                }
+            }
+            return common !== undefined ? common : DEFAULT_SHADOW;
+        },
+        set: function (value) {
+            if (typeof value !== 'boolean') {
+                throw new RangeError('Borders shadow must be a boolean');
+            }
+            var keys = this.aggregateKeys();
+            for (var i = 0; i < keys.length; i += 1) {
+                this.edgeAt(keys[i]).shadow = value;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return Borders;
+}());
+export { Borders };
+/**
+ * Host that reads/writes a full TableBorders bag via callbacks.
+ *
+ * @private
+ */
+export function createTableBordersHost(read, write) {
+    return {
+        readEdge: function (key) {
+            var bag = read();
+            if (bag === undefined) {
+                return undefined;
+            }
+            return bag[key];
+        },
+        writeEdge: function (key, edge) {
+            var prev = read();
+            var next = prev !== undefined ? __assign({}, prev) : {};
+            var mutable = next;
+            if (edge === undefined) {
+                delete mutable[key];
+            }
+            else {
+                mutable[key] = edge;
+            }
+            var has = next.top !== undefined ||
+                next.bottom !== undefined ||
+                next.left !== undefined ||
+                next.right !== undefined ||
+                next.insideH !== undefined ||
+                next.insideV !== undefined;
+            write(has ? next : undefined);
+        },
+    };
+}
+/**
+ * Host for cell borders; preserves diagonal edges when rewriting.
+ *
+ * @private
+ */
+export function createCellBordersHost(read, write) {
+    return {
+        readEdge: function (key) {
+            var bag = read();
+            if (bag === undefined) {
+                return undefined;
+            }
+            return bag[key];
+        },
+        writeEdge: function (key, edge) {
+            var prev = read();
+            var next = prev !== undefined ? __assign({}, prev) : {};
+            var mutable = next;
+            if (edge === undefined) {
+                delete mutable[key];
+            }
+            else {
+                mutable[key] = edge;
+            }
+            var has = next.top !== undefined ||
+                next.bottom !== undefined ||
+                next.left !== undefined ||
+                next.right !== undefined ||
+                next.insideH !== undefined ||
+                next.insideV !== undefined ||
+                next.tl2br !== undefined ||
+                next.tr2bl !== undefined;
+            write(has ? next : undefined);
+        },
+    };
+}