@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/document/length.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Measurement helpers for the document API.
+ *
+ * Public authoring values are plain `number` values in **typographic points**
+ * (1 pt = 1/72 in). Conversion to OOXML storage units (twips, half-points, EMU)
+ * happens only at the parse/serialize boundary.
+ *
+ * Factors:
+ * - 1 pt = 20 twips
+ * - 1 pt = 2 half-points (`w:sz`)
+ * - 1 pt = 12_700 EMU (DrawingML)
+ * - 1 in = 72 pt = 914_400 EMU
+ *
+ * @packageDocumentation
+ */
+/**
+ * Storage EMU brand for DrawingML extents (`wp:extent/@cx|cy`, etc.).
+ *
+ * Prefer plain point `number` on public authoring APIs. Package-private
+ * codecs brand raw EMU integers at the wire boundary only.
+ *
+ * @internal
+ */
+export declare type Emus = number & {
+    readonly __brand: 'Emus';
+};
+/**
+ * Half-points brand for `w:sz` / position wire values.
+ * Package-private; public authoring uses plain point `number`.
+ *
+ * @internal
+ */
+export declare type HalfPoints = number & {
+    readonly __brand: 'HalfPoints';
+};
+/**
+ * @internal Convert points → integer EMUs for DrawingML extents.
+ */
+export declare function pointToEmus(points: number): Emus;
+/**
+ * @internal Points → integer EMUs for DrawingML coordinates that allow 0 / negative
+ * (`dist*`, `wp:posOffset`, `wp:simplePos`). Prefer {@link pointToEmus} for extents.
+ *
+ * Brands as {@link Emus} without the positive-only guard in {@link emus}.
+ */
+export declare function pointToCoordinateEmus(points: number): Emus;
+/**
+ * @internal Convert points → half-points for `w:sz`, clamped to Word range.
+ */
+export declare function pointToHalfPoints(points: number): HalfPoints;
+/**
+ * @internal Points → signed half-points (no clamp; allows negative `w:position` / `w:kern`).
+ */
+export declare function pointToSignedHalfPoints(points: number): number;
+/**
+ * @internal Convert points → integer twips (half-away-from-zero).
+ */
+export declare function pointToTwips(points: number): number;
+/**
+ * @internal Twips → points (signed values allowed).
+ */
+export declare function twipsToPoint(twips: number): number;
+/**
+ * @internal Raw EMU integer → points.
+ */
+export declare function emuToPoint(emu: number): number;
+/**
+ * @internal Half-points → points (signed values allowed for position).
+ */
+export declare function halfPointsToPoint(halfPointsValue: number): number;
+/**
+ * @internal Add two point measures.
+ */
+export declare function addPoints(a: number, b: number): number;
+/**
+ * @internal Scale a point measure by a finite factor.
+ */
+export declare function scalePoint(points: number, factor: number): number;
+/**
+ * @internal Inches → points (package-private authoring helper).
+ */
+export declare function inchesToPoint(value: number): number;
+/**
+ * @internal Centimeters → points.
+ */
+export declare function cmToPoint(value: number): number;
+/**
+ * @internal Millimeters → points.
+ */
+export declare function mmToPoint(value: number): number;
+/**
+ * @internal CSS pixels at 96 DPI → points.
+ */
+export declare function pxToPoint(value: number): number;
+/**
+ * @internal Half-points brand for run storage.
+ */
+export declare function halfPoints(value: number): HalfPoints;
+/**
+ * @internal Positive EMU brand for DrawingML storage.
+ */
+export declare function emus(value: number): Emus;
+/**
+ * @internal @deprecated Prefer {@link pointToEmus}.
+ * Residual alias — do not use in new code.
+ */
+export declare function lengthToEmus(points: number): Emus;
+/**
+ * @internal @deprecated Prefer {@link pointToHalfPoints}.
+ * Residual alias — do not use in new code.
+ */
+export declare function lengthToHalfPoints(points: number): HalfPoints;
+/** @internal Conversion constants for tests and bridges. */
+export declare const LengthUnits: {
+    EMU_PER_INCH: number;
+    EMU_PER_PT: number;
+    EMU_PER_TWIP: number;
+    EMU_PER_HALF_POINT: number;
+    EMU_PER_CM: number;
+    EMU_PER_MM: number;
+    EMU_PER_PX_96DPI: number;
+    TWIPS_PER_PT: number;
+    HALF_POINTS_PER_PT: number;
+    PT_PER_INCH: number;
+};
+/** @internal @deprecated Use plain point `number`. */
+export declare type Length = number;
+/** @internal @deprecated Use plain point `number`. */
+export declare type Point = number;
+/** @internal @deprecated Pass point numbers directly. */
+export declare function Pt(value: number): number;
+/** @internal @deprecated Use {@link inchesToPoint}. */
+export declare function Inches(value: number): number;
+/** @internal @deprecated Use {@link cmToPoint}. */
+export declare function Cm(value: number): number;
+/** @internal @deprecated Use {@link mmToPoint}. */
+export declare function Mm(value: number): number;
+/** @internal @deprecated Use {@link pxToPoint}. */
+export declare function Px(value: number): number;
+/** @internal @deprecated Use {@link twipsToPoint}. */
+export declare function Twips(value: number): number;
+/** @internal @deprecated Use {@link emuToPoint}. */
+export declare function Emu(value: number): number;
+/** @internal @deprecated Use {@link addPoints}. */
+export declare function add(a: number, b: number): number;
+/** @internal @deprecated Use {@link scalePoint}. */
+export declare function scale(points: number, factor: number): number;
+/**
+ * @internal @deprecated Public API uses plain point numbers — do not call.
+ * Identity helper retained only so residual dual-gap call sites compile during migration.
+ */
+export declare function Point(value: number): number;

package/src/features/document/length.js

@@ -0,0 +1,245 @@
+/**
+ * Measurement helpers for the document API.
+ *
+ * Public authoring values are plain `number` values in **typographic points**
+ * (1 pt = 1/72 in). Conversion to OOXML storage units (twips, half-points, EMU)
+ * happens only at the parse/serialize boundary.
+ *
+ * Factors:
+ * - 1 pt = 20 twips
+ * - 1 pt = 2 half-points (`w:sz`)
+ * - 1 pt = 12_700 EMU (DrawingML)
+ * - 1 in = 72 pt = 914_400 EMU
+ *
+ * @packageDocumentation
+ */
+/** @internal EMU per inch (DrawingML). */
+var EMU_PER_INCH = 914400;
+/** @internal EMU per point. */
+var EMU_PER_PT = 12700;
+/** @internal EMU per twip. */
+var EMU_PER_TWIP = 635;
+/** @internal EMU per half-point. */
+var EMU_PER_HALF_POINT = 6350;
+/** @internal EMU per centimeter. */
+var EMU_PER_CM = 360000;
+/** @internal EMU per millimeter. */
+var EMU_PER_MM = 36000;
+/** @internal EMU per CSS px at 96 DPI. */
+var EMU_PER_PX_96DPI = 9525;
+/** @internal Twips per point. */
+var TWIPS_PER_PT = 20;
+/** @internal Half-points per point. */
+var HALF_POINTS_PER_PT = 2;
+/** @internal Points per inch. */
+var PT_PER_INCH = 72;
+function assertFinite(name, value) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(name + " must be finite, got " + String(value));
+    }
+}
+/**
+ * @internal Convert points → integer EMUs for DrawingML extents.
+ */
+export function pointToEmus(points) {
+    assertFinite('points', points);
+    var rounded = Math.round(points * EMU_PER_PT);
+    if (rounded <= 0) {
+        throw new RangeError("Image dimensions must be positive, got " + String(rounded) + " EMU");
+    }
+    return rounded;
+}
+/**
+ * @internal Points → integer EMUs for DrawingML coordinates that allow 0 / negative
+ * (`dist*`, `wp:posOffset`, `wp:simplePos`). Prefer {@link pointToEmus} for extents.
+ *
+ * Brands as {@link Emus} without the positive-only guard in {@link emus}.
+ */
+export function pointToCoordinateEmus(points) {
+    assertFinite('points', points);
+    return Math.round(points * EMU_PER_PT);
+}
+/**
+ * @internal Convert points → half-points for `w:sz`, clamped to Word range.
+ */
+export function pointToHalfPoints(points) {
+    assertFinite('points', points);
+    var halfPointsValue = Math.round(points * HALF_POINTS_PER_PT);
+    var clamped = Math.min(Math.max(halfPointsValue, 0), 3276);
+    if (clamped <= 0) {
+        throw new RangeError("Font size must be positive, got " + String(clamped) + " half-points");
+    }
+    return clamped;
+}
+/**
+ * @internal Points → signed half-points (no clamp; allows negative `w:position` / `w:kern`).
+ */
+export function pointToSignedHalfPoints(points) {
+    assertFinite('points', points);
+    return Math.round(points * HALF_POINTS_PER_PT);
+}
+/**
+ * @internal Convert points → integer twips (half-away-from-zero).
+ */
+export function pointToTwips(points) {
+    assertFinite('points', points);
+    return Math.round(points * TWIPS_PER_PT);
+}
+/**
+ * @internal Twips → points (signed values allowed).
+ */
+export function twipsToPoint(twips) {
+    assertFinite('twips', twips);
+    return twips / TWIPS_PER_PT;
+}
+/**
+ * @internal Raw EMU integer → points.
+ */
+export function emuToPoint(emu) {
+    assertFinite('emu', emu);
+    return emu / EMU_PER_PT;
+}
+/**
+ * @internal Half-points → points (signed values allowed for position).
+ */
+export function halfPointsToPoint(halfPointsValue) {
+    assertFinite('halfPoints', halfPointsValue);
+    return halfPointsValue / HALF_POINTS_PER_PT;
+}
+/**
+ * @internal Add two point measures.
+ */
+export function addPoints(a, b) {
+    assertFinite('a', a);
+    assertFinite('b', b);
+    return a + b;
+}
+/**
+ * @internal Scale a point measure by a finite factor.
+ */
+export function scalePoint(points, factor) {
+    assertFinite('points', points);
+    assertFinite('Scale factor', factor);
+    return points * factor;
+}
+/**
+ * @internal Inches → points (package-private authoring helper).
+ */
+export function inchesToPoint(value) {
+    assertFinite('inches', value);
+    return value * PT_PER_INCH;
+}
+/**
+ * @internal Centimeters → points.
+ */
+export function cmToPoint(value) {
+    assertFinite('cm', value);
+    return (value * EMU_PER_CM) / EMU_PER_PT;
+}
+/**
+ * @internal Millimeters → points.
+ */
+export function mmToPoint(value) {
+    assertFinite('mm', value);
+    return (value * EMU_PER_MM) / EMU_PER_PT;
+}
+/**
+ * @internal CSS pixels at 96 DPI → points.
+ */
+export function pxToPoint(value) {
+    assertFinite('px', value);
+    return (value * EMU_PER_PX_96DPI) / EMU_PER_PT;
+}
+/**
+ * @internal Half-points brand for run storage.
+ */
+export function halfPoints(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError("Half-points must be a non-negative integer, got " + String(value));
+    }
+    return value;
+}
+/**
+ * @internal Positive EMU brand for DrawingML storage.
+ */
+export function emus(value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new RangeError("EMUs must be a positive integer, got " + String(value));
+    }
+    return value;
+}
+/**
+ * @internal @deprecated Prefer {@link pointToEmus}.
+ * Residual alias — do not use in new code.
+ */
+export function lengthToEmus(points) {
+    return pointToEmus(points);
+}
+/**
+ * @internal @deprecated Prefer {@link pointToHalfPoints}.
+ * Residual alias — do not use in new code.
+ */
+export function lengthToHalfPoints(points) {
+    return pointToHalfPoints(points);
+}
+/** @internal Conversion constants for tests and bridges. */
+export var LengthUnits = {
+    EMU_PER_INCH: EMU_PER_INCH,
+    EMU_PER_PT: EMU_PER_PT,
+    EMU_PER_TWIP: EMU_PER_TWIP,
+    EMU_PER_HALF_POINT: EMU_PER_HALF_POINT,
+    EMU_PER_CM: EMU_PER_CM,
+    EMU_PER_MM: EMU_PER_MM,
+    EMU_PER_PX_96DPI: EMU_PER_PX_96DPI,
+    TWIPS_PER_PT: TWIPS_PER_PT,
+    HALF_POINTS_PER_PT: HALF_POINTS_PER_PT,
+    PT_PER_INCH: PT_PER_INCH,
+};
+/** @internal @deprecated Pass point numbers directly. */
+export function Pt(value) {
+    assertFinite('Pt', value);
+    return value;
+}
+/** @internal @deprecated Use {@link inchesToPoint}. */
+export function Inches(value) {
+    return inchesToPoint(value);
+}
+/** @internal @deprecated Use {@link cmToPoint}. */
+export function Cm(value) {
+    return cmToPoint(value);
+}
+/** @internal @deprecated Use {@link mmToPoint}. */
+export function Mm(value) {
+    return mmToPoint(value);
+}
+/** @internal @deprecated Use {@link pxToPoint}. */
+export function Px(value) {
+    return pxToPoint(value);
+}
+/** @internal @deprecated Use {@link twipsToPoint}. */
+export function Twips(value) {
+    return twipsToPoint(value);
+}
+/** @internal @deprecated Use {@link emuToPoint}. */
+export function Emu(value) {
+    if (!Number.isInteger(value)) {
+        throw new RangeError("Emu must be an integer, got " + String(value));
+    }
+    return emuToPoint(value);
+}
+/** @internal @deprecated Use {@link addPoints}. */
+export function add(a, b) {
+    return addPoints(a, b);
+}
+/** @internal @deprecated Use {@link scalePoint}. */
+export function scale(points, factor) {
+    return scalePoint(points, factor);
+}
+/**
+ * @internal @deprecated Public API uses plain point numbers — do not call.
+ * Identity helper retained only so residual dual-gap call sites compile during migration.
+ */
+export function Point(value) {
+    assertFinite('points', value);
+    return value;
+}

package/src/features/document/load-options.d.ts

@@ -0,0 +1,14 @@
+import { ResourceLimitOverrides } from '../../core/security/limits';
+/**
+ * Options for {@link WordDocument.open}, {@link WordDocument.openSync}, and
+ * {@link WordDocument.openAsync}.
+ *
+ * @public
+ */
+export interface LoadOptions {
+    /**
+     * Overrides for ZIP and XML resource limits. Unspecified fields keep the
+     * defaults in `.agent/policies/security.md`.
+     */
+    readonly limits?: ResourceLimitOverrides;
+}

package/src/features/document/locale-ids.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Windows LCID values for run language properties (`w:lang`).
+ *
+ * Enum member names use underscore BCP-47 style (`en_US`) matching the public
+ * DocIO-oriented API. Wire values remain BCP-47 with hyphens (`en-US`).
+ *
+ * @public
+ */
+export declare enum LocaleIDs {
+    /** Unspecified / cleared language. */
+    None = 0,
+    af_ZA = 1078,
+    sq_AL = 1052,
+    am_ET = 1118,
+    ar_SA = 1025,
+    ar_IQ = 2049,
+    ar_EG = 3073,
+    ar_LY = 4097,
+    ar_DZ = 5121,
+    ar_MA = 6145,
+    ar_TN = 7169,
+    ar_OM = 8193,
+    ar_YE = 9217,
+    ar_SY = 10241,
+    ar_JO = 11265,
+    ar_LB = 12289,
+    ar_KW = 13313,
+    ar_AE = 14337,
+    ar_BH = 15361,
+    ar_QA = 16385,
+    hy_AM = 1067,
+    as_IN = 1101,
+    az_AZ_Latn = 1068,
+    az_AZ_Cyrl = 2092,
+    eu_ES = 1069,
+    be_BY = 1059,
+    bn_IN = 1093,
+    bn_BD = 2117,
+    bs_BA_Latn = 5146,
+    bs_BA_Cyrl = 8218,
+    bg_BG = 1026,
+    my_MM = 1109,
+    ca_ES = 1027,
+    zh_TW = 1028,
+    zh_CN = 2052,
+    zh_HK = 3076,
+    zh_SG = 4100,
+    zh_MO = 5124,
+    hr_HR = 1050,
+    hr_BA = 4122,
+    cs_CZ = 1029,
+    da_DK = 1030,
+    prs_AF = 1164,
+    dv_MV = 1125,
+    nl_NL = 1043,
+    nl_BE = 2067,
+    en_US = 1033,
+    en_GB = 2057,
+    en_AU = 3081,
+    en_CA = 4105,
+    en_NZ = 5129,
+    en_IE = 6153,
+    en_ZA = 7177,
+    en_JM = 8201,
+    en_CB = 9225,
+    en_BZ = 10249,
+    en_TT = 11273,
+    en_ZW = 12297,
+    en_PH = 13321,
+    en_IN = 16393,
+    en_MY = 17417,
+    en_SG = 18441,
+    et_EE = 1061,
+    fo_FO = 1080,
+    fil_PH = 1124,
+    fi_FI = 1035,
+    fr_FR = 1036,
+    fr_BE = 2060,
+    fr_CA = 3084,
+    fr_CH = 4108,
+    fr_LU = 5132,
+    fr_MC = 6156,
+    fy_NL = 1122,
+    gl_ES = 1110,
+    ka_GE = 1079,
+    de_DE = 1031,
+    de_CH = 2055,
+    de_AT = 3079,
+    de_LU = 4103,
+    de_LI = 5127,
+    el_GR = 1032,
+    gu_IN = 1095,
+    ha_NG_Latn = 1128,
+    he_IL = 1037,
+    hi_IN = 1081,
+    hu_HU = 1038,
+    is_IS = 1039,
+    ig_NG = 1136,
+    id_ID = 1057,
+    iu_CA_Latn = 2141,
+    iu_CA_Cans = 1117,
+    ga_IE = 2108,
+    xh_ZA = 1076,
+    zu_ZA = 1077,
+    it_IT = 1040,
+    it_CH = 2064,
+    ja_JP = 1041,
+    kn_IN = 1099,
+    kk_KZ = 1087,
+    km_KH = 1107,
+    quc_GT = 1158,
+    rw_RW = 1159,
+    sw_KE = 1089,
+    kok_IN = 1111,
+    ko_KR = 1042,
+    ky_KG = 1088,
+    lo_LA = 1108,
+    lv_LV = 1062,
+    lt_LT = 1063,
+    dsb_DE = 2094,
+    lb_LU = 1134,
+    mk_MK = 1071,
+    ms_MY = 1086,
+    ms_BN = 2110,
+    ml_IN = 1100,
+    mt_MT = 1082,
+    mi_NZ = 1153,
+    arn_CL = 1146,
+    mr_IN = 1102,
+    mn_MN = 1104,
+    mn_CN = 2128,
+    ne_NP = 1121,
+    nb_NO = 1044,
+    nn_NO = 2068,
+    oc_FR = 1154,
+    or_IN = 1096,
+    ps_AF = 1123,
+    fa_IR = 1065,
+    pl_PL = 1045,
+    pt_BR = 1046,
+    pt_PT = 2070,
+    pa_IN = 1094,
+    quz_BO = 1131,
+    quz_EC = 2155,
+    quz_PE = 3179,
+    ro_RO = 1048,
+    rm_CH = 1047,
+    ru_RU = 1049,
+    smn_FI = 9275,
+    smj_NO = 4155,
+    smj_SE = 5179,
+    se_NO = 3131,
+    se_SE = 1083,
+    se_FI = 2107,
+    sms_FI = 8251,
+    sma_NO = 6203,
+    sma_SE = 7227,
+    sa_IN = 1103,
+    sr_SP_Cyrl = 3098,
+    sr_SP_Latn = 2074,
+    sr_BA_Cyrl = 7194,
+    sr_BA_Latn = 5146,
+    nso_ZA = 1132,
+    tn_ZA = 1074,
+    si_LK = 1115,
+    sk_SK = 1051,
+    sl_SI = 1060,
+    es_ES_tradnl = 1034,
+    es_MX = 2058,
+    es_ES = 3082,
+    es_GT = 4106,
+    es_CR = 5130,
+    es_PA = 6154,
+    es_DO = 7178,
+    es_VE = 8202,
+    es_CO = 9226,
+    es_PE = 10250,
+    es_AR = 11274,
+    es_EC = 12298,
+    es_CL = 13322,
+    es_UY = 14346,
+    es_PY = 15370,
+    es_BO = 16394,
+    es_SV = 17418,
+    es_HN = 18442,
+    es_NI = 19466,
+    es_PR = 20490,
+    es_US = 21514,
+    sv_SE = 1053,
+    sv_FI = 2077,
+    syr_SY = 1114,
+    tg_TJ_Cyrl = 1064,
+    ta_IN = 1097,
+    tt_RU = 1092,
+    te_IN = 1098,
+    th_TH = 1054,
+    bo_CN = 1105,
+    ti_ER = 2163,
+    ti_ET = 1139,
+    ts_ZA = 1073,
+    tr_TR = 1055,
+    tk_TM = 1090,
+    uk_UA = 1058,
+    hsb_DE = 1070,
+    ur_PK = 1056,
+    ug_CN = 1152,
+    uz_UZ_Latn = 1091,
+    uz_UZ_Cyrl = 2115,
+    vi_VN = 1066,
+    cy_GB = 1106,
+    wo_SN = 1160,
+    sah_RU = 1157,
+    ii_CN = 1144,
+    yo_NG = 1130
+}
+/**
+ * Convert a `w:lang` BCP-47 value to {@link LocaleIDs}.
+ * Unknown tags return {@link LocaleIDs.None}.
+ * @private
+ */
+export declare function localeIdFromBcp47(raw: string | undefined): LocaleIDs;
+/**
+ * Convert {@link LocaleIDs} to the BCP-47 string written on `w:lang`.
+ * {@link LocaleIDs.None} returns `undefined` (omit attribute).
+ * @private
+ */
+export declare function localeIdToBcp47(id: LocaleIDs): string | undefined;