@office-open/core 0.3.0

package/dist/_chunks/values-BrGywpRh.d.mts

@@ -0,0 +1,400 @@
+//#region src/values.d.ts
+/**
+ * Runtime validation and type conversion functions for OOXML specification values.
+ *
+ * This module provides runtime checks and cleanup for value types in the OOXML spec
+ * that aren't easily expressed through the TypeScript type system alone. These
+ * validators help prevent silent failures and corrupted documents by enforcing
+ * spec-compliant values at runtime.
+ *
+ * @module
+ */
+/**
+ * A measurement value with optional sign and unit suffix.
+ *
+ * Supports units: mm (millimeters), cm (centimeters), in (inches),
+ * pt (points), pc (picas), pi (picas).
+ *
+ * Pattern: `-?[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)`
+ *
+ * @example
+ * ```typescript
+ * const measure: UniversalMeasure = "10.5mm";
+ * const negative: UniversalMeasure = "-5pt";
+ * ```
+ */
+type UniversalMeasure = `${"-" | ""}${number}${"mm" | "cm" | "in" | "pt" | "pc" | "pi"}`;
+/**
+ * A positive measurement value with unit suffix.
+ *
+ * Same as UniversalMeasure but restricted to positive values only.
+ *
+ * Reference: ST_PositiveUniversalMeasure in OOXML specification
+ *
+ * @example
+ * ```typescript
+ * const measure: PositiveUniversalMeasure = "10.5mm";
+ * ```
+ */
+type PositiveUniversalMeasure = `${number}${"mm" | "cm" | "in" | "pt" | "pc" | "pi"}`;
+/**
+ * A percentage value with optional sign.
+ *
+ * Pattern: `-?[0-9]+(\.[0-9]+)?%`
+ *
+ * Reference: ST_Percentage in OOXML specification
+ *
+ * @example
+ * ```typescript
+ * const percent: Percentage = "50%";
+ * const negative: Percentage = "-10.5%";
+ * ```
+ */
+type Percentage = `${"-" | ""}${number}%`;
+/**
+ * A positive percentage value.
+ *
+ * Same as Percentage but restricted to positive values only.
+ *
+ * Reference: ST_PositivePercentage in OOXML specification
+ *
+ * @example
+ * ```typescript
+ * const percent: PositivePercentage = "50%";
+ * ```
+ */
+type PositivePercentage = `${number}%`;
+/**
+ * A relative measurement value using em or ex units.
+ *
+ * Used in VML text boxes for font-relative measurements.
+ *
+ * @example
+ * ```typescript
+ * const measure: RelativeMeasure = "2em";
+ * const negative: RelativeMeasure = "-0.5ex";
+ * ```
+ */
+type RelativeMeasure = `${"-" | ""}${number}${"em" | "ex"}`;
+/**
+ * Validates and converts a number to an integer (decimal number).
+ *
+ * Reference: ST_DecimalNumber in OOXML specification
+ *
+ * @param val - The number to validate and convert
+ * @returns The floored integer value
+ * @throws Error if the value is NaN
+ *
+ * @example
+ * ```typescript
+ * const num = decimalNumber(10.7); // Returns 10
+ * const negative = decimalNumber(-5.3); // Returns -5
+ * ```
+ */
+declare const decimalNumber: (val: number) => number;
+/**
+ * Validates and converts a number to a positive integer (unsigned decimal number).
+ *
+ * Reference: ST_UnsignedDecimalNumber in OOXML specification
+ *
+ * @param val - The number to validate and convert
+ * @returns The floored positive integer value
+ * @throws Error if the value is NaN or negative
+ *
+ * @example
+ * ```typescript
+ * const num = unsignedDecimalNumber(10.7); // Returns 10
+ * const invalid = unsignedDecimalNumber(-5); // Throws Error
+ * ```
+ */
+declare const unsignedDecimalNumber: (val: number) => number;
+/**
+ * Validates a long hexadecimal number (4 bytes / 8 characters).
+ *
+ * Reference: ST_LongHexNumber in OOXML specification
+ *
+ * @param val - The hexadecimal string to validate
+ * @returns The validated hexadecimal string
+ * @throws Error if the value is not a valid 8-character hex string
+ *
+ * @example
+ * ```typescript
+ * const hex = longHexNumber("ABCD1234"); // Valid
+ * ```
+ */
+declare const longHexNumber: (val: string) => string;
+/**
+ * Validates a short hexadecimal number (2 bytes / 4 characters).
+ *
+ * Reference: ST_ShortHexNumber in OOXML specification
+ *
+ * @param val - The hexadecimal string to validate
+ * @returns The validated hexadecimal string
+ * @throws Error if the value is not a valid 4-character hex string
+ *
+ * @example
+ * ```typescript
+ * const hex = shortHexNumber("AB12"); // Valid
+ * ```
+ */
+declare const shortHexNumber: (val: string) => string;
+/**
+ * Validates a single-byte hexadecimal number (1 byte / 2 characters).
+ *
+ * Reference: ST_UcharHexNumber in OOXML specification
+ *
+ * @param val - The hexadecimal string to validate
+ * @returns The validated hexadecimal string
+ * @throws Error if the value is not a valid 2-character hex string
+ *
+ * @example
+ * ```typescript
+ * const hex = uCharHexNumber("FF"); // Valid
+ * ```
+ */
+declare const uCharHexNumber: (val: string) => string;
+/**
+ * Normalizes a universal measure value by parsing and reformatting.
+ *
+ * Ensures the numeric portion is properly formatted while preserving the unit.
+ *
+ * Reference: ST_UniversalMeasure in OOXML specification
+ *
+ * @param val - The universal measure string to normalize
+ * @returns The normalized universal measure
+ *
+ * @example
+ * ```typescript
+ * const measure = universalMeasureValue("10.500mm"); // Returns "10.5mm"
+ * ```
+ */
+declare const universalMeasureValue: (val: UniversalMeasure) => UniversalMeasure;
+/**
+ * Validates and normalizes a positive universal measure value.
+ *
+ * Reference: ST_PositiveUniversalMeasure in OOXML specification
+ *
+ * @param val - The positive universal measure string to validate
+ * @returns The normalized positive universal measure
+ * @throws Error if the value is negative
+ *
+ * @example
+ * ```typescript
+ * const measure = positiveUniversalMeasureValue("10.5mm"); // Valid
+ * const invalid = positiveUniversalMeasureValue("-5mm"); // Throws Error
+ * ```
+ */
+declare const positiveUniversalMeasureValue: (val: PositiveUniversalMeasure) => PositiveUniversalMeasure;
+/**
+ * Validates and normalizes a hexadecimal color value.
+ *
+ * Accepts either "auto" or a 6-character RGB hex value (with or without # prefix).
+ * The # prefix is commonly used but technically invalid in OOXML, so it is stripped
+ * for strict compliance.
+ *
+ * Reference: ST_HexColor in OOXML specification
+ *
+ * @param val - The color value to validate ("auto" or hex color)
+ * @returns The normalized color value
+ * @throws Error if the hex color is invalid
+ *
+ * @example
+ * ```typescript
+ * const color1 = hexColorValue("auto"); // Returns "auto"
+ * const color2 = hexColorValue("FF0000"); // Returns "FF0000"
+ * const color3 = hexColorValue("#00FF00"); // Returns "00FF00" (# stripped)
+ * ```
+ */
+declare const hexColorValue: (val: string) => string;
+/**
+ * Validates a signed TWIP measurement value.
+ *
+ * Accepts either a universal measure string or a numeric TWIP value.
+ *
+ * Reference: ST_SignedTwipsMeasure in OOXML specification
+ *
+ * @param val - The measurement value (universal measure or number)
+ * @returns The normalized measurement value
+ *
+ * @example
+ * ```typescript
+ * const measure1 = signedTwipsMeasureValue("10mm");
+ * const measure2 = signedTwipsMeasureValue(1440); // 1 inch in TWIP
+ * ```
+ */
+declare const signedTwipsMeasureValue: (val: UniversalMeasure | number) => UniversalMeasure | number;
+/**
+ * Validates a half-point (HPS) measurement value.
+ *
+ * Accepts either a positive universal measure string or a positive number.
+ * HPS (half-points) are commonly used for font sizes.
+ *
+ * Reference: ST_HpsMeasure in OOXML specification
+ *
+ * @param val - The measurement value (positive universal measure or number)
+ * @returns The normalized measurement value
+ *
+ * @example
+ * ```typescript
+ * const fontSize1 = hpsMeasureValue("12pt");
+ * const fontSize2 = hpsMeasureValue(24); // 12pt in half-points
+ * ```
+ */
+declare const hpsMeasureValue: (val: PositiveUniversalMeasure | number) => string | number;
+/**
+ * Validates a signed half-point (HPS) measurement value.
+ *
+ * Accepts either a universal measure string or a numeric value.
+ *
+ * Reference: ST_SignedHpsMeasure in OOXML specification
+ *
+ * @param val - The measurement value (universal measure or number)
+ * @returns The normalized measurement value
+ *
+ * @example
+ * ```typescript
+ * const spacing1 = signedHpsMeasureValue("6pt");
+ * const spacing2 = signedHpsMeasureValue(-12); // Negative spacing
+ * ```
+ */
+declare const signedHpsMeasureValue: (val: UniversalMeasure | number) => string | number;
+/**
+ * Validates a positive TWIP measurement value.
+ *
+ * Accepts either a positive universal measure string or a positive number.
+ *
+ * Reference: ST_TwipsMeasure in OOXML specification
+ *
+ * @param val - The measurement value (positive universal measure or number)
+ * @returns The normalized measurement value
+ *
+ * @example
+ * ```typescript
+ * const width1 = twipsMeasureValue("25.4mm");
+ * const width2 = twipsMeasureValue(1440); // 1 inch in TWIP
+ * ```
+ */
+declare const twipsMeasureValue: (val: PositiveUniversalMeasure | number) => PositiveUniversalMeasure | number;
+/**
+ * Normalizes a percentage value by parsing and reformatting.
+ *
+ * Reference: ST_Percentage in OOXML specification
+ *
+ * @param val - The percentage string to normalize
+ * @returns The normalized percentage
+ *
+ * @example
+ * ```typescript
+ * const percent = percentageValue("50.000%"); // Returns "50%"
+ * ```
+ */
+declare const percentageValue: (val: Percentage) => Percentage;
+/**
+ * Validates a measurement value that can be expressed as a number, percentage, or universal measure.
+ *
+ * Reference: ST_MeasurementOrPercent in OOXML specification
+ *
+ * @param val - The measurement value (number, percentage, or universal measure)
+ * @returns The normalized measurement value
+ *
+ * @example
+ * ```typescript
+ * const measure1 = measurementOrPercentValue(100); // Unqualified number
+ * const measure2 = measurementOrPercentValue("50%"); // Percentage
+ * const measure3 = measurementOrPercentValue("10mm"); // Universal measure
+ * ```
+ */
+declare const measurementOrPercentValue: (val: number | Percentage | UniversalMeasure) => number | UniversalMeasure | Percentage;
+/**
+ * Validates an eighth-point measurement value.
+ *
+ * Eighth-points are used for fine-grained measurements in text formatting.
+ *
+ * Reference: ST_EighthPointMeasure in OOXML specification
+ *
+ * @param val - The measurement value in eighth-points
+ * @returns The validated positive integer value
+ *
+ * @example
+ * ```typescript
+ * const measure = eighthPointMeasureValue(16); // 2 points
+ * ```
+ */
+declare const eighthPointMeasureValue: (val: number) => number;
+/**
+ * Validates a point measurement value.
+ *
+ * Reference: ST_PointMeasure in OOXML specification
+ *
+ * @param val - The measurement value in points
+ * @returns The validated positive integer value
+ *
+ * @example
+ * ```typescript
+ * const fontSize = pointMeasureValue(12); // 12pt
+ * ```
+ */
+declare const pointMeasureValue: (val: number) => number;
+/**
+ * Converts a JavaScript Date object to an ISO 8601 date-time string.
+ *
+ * The format is CCYY-MM-DDThh:mm:ss.sssZ where T is a literal and Z indicates UTC.
+ * This matches the xsd:dateTime format required by OOXML.
+ *
+ * Reference: ST_DateTime in OOXML specification
+ *
+ * @param val - The Date object to convert
+ * @returns An ISO 8601 formatted date-time string
+ *
+ * @example
+ * ```typescript
+ * const now = new Date();
+ * const timestamp = dateTimeValue(now); // Returns "2024-01-15T10:30:00.000Z"
+ * ```
+ */
+declare const dateTimeValue: (val: Date) => string;
+/**
+ * Theme color values used throughout OOXML for referencing document theme colors.
+ *
+ * Reference: ST_ThemeColor in OOXML specification
+ *
+ * @publicApi
+ */
+declare const ThemeColor: {
+  readonly DARK1: "dark1";
+  readonly LIGHT1: "light1";
+  readonly DARK2: "dark2";
+  readonly LIGHT2: "light2";
+  readonly ACCENT1: "accent1";
+  readonly ACCENT2: "accent2";
+  readonly ACCENT3: "accent3";
+  readonly ACCENT4: "accent4";
+  readonly ACCENT5: "accent5";
+  readonly ACCENT6: "accent6";
+  readonly HYPERLINK: "hyperlink";
+  readonly FOLLOWED_HYPERLINK: "followedHyperlink";
+  readonly NONE: "none";
+  readonly BACKGROUND1: "background1";
+  readonly TEXT1: "text1";
+  readonly BACKGROUND2: "background2";
+  readonly TEXT2: "text2";
+};
+/**
+ * Theme font values used for referencing document theme fonts.
+ *
+ * Reference: ST_Theme in OOXML specification
+ *
+ * @publicApi
+ */
+declare const ThemeFont: {
+  readonly MAJOR_EAST_ASIA: "majorEastAsia";
+  readonly MAJOR_BIDI: "majorBidi";
+  readonly MAJOR_ASCII: "majorAscii";
+  readonly MAJOR_H_ANSI: "majorHAnsi";
+  readonly MINOR_EAST_ASIA: "minorEastAsia";
+  readonly MINOR_BIDI: "minorBidi";
+  readonly MINOR_ASCII: "minorAscii";
+  readonly MINOR_H_ANSI: "minorHAnsi";
+};
+//#endregion
+export { universalMeasureValue as C, uCharHexNumber as S, positiveUniversalMeasureValue as _, ThemeColor as a, signedTwipsMeasureValue as b, dateTimeValue as c, hexColorValue as d, hpsMeasureValue as f, pointMeasureValue as g, percentageValue as h, RelativeMeasure as i, decimalNumber as l, measurementOrPercentValue as m, PositivePercentage as n, ThemeFont as o, longHexNumber as p, PositiveUniversalMeasure as r, UniversalMeasure as s, Percentage as t, eighthPointMeasureValue as u, shortHexNumber as v, unsignedDecimalNumber as w, twipsMeasureValue as x, signedHpsMeasureValue as y };