@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/drawing/sp-pr.d.ts

@@ -0,0 +1,396 @@
+/**
+ * `wps:spPr` fill/line/geometry codec (TASK-8048).
+ *
+ * Schema cites (transitional `dml-main.xsd`; ECMA-376-1 §20.1):
+ * - `CT_ShapeProperties` sequence: `a:xfrm`, `EG_Geometry` (`custGeom` |
+ *   `prstGeom`), `EG_FillProperties`, `a:ln`, `EG_EffectProperties`, `scene3d`,
+ *   `sp3d`, `extLst`
+ * - `CT_PresetGeometry2D`: `@prst` (`ST_ShapeType`) + `a:avLst` child
+ * - `CT_NoFillProperties` (empty); `CT_SolidColorFillProperties` (single
+ *   `EG_ColorChoice` child — `a:srgbClr` here)
+ * - `CT_LineProperties` sequence: `EG_LineFillProperties`, `EG_LineDashProperties`
+ *   (`a:prstDash @val` `ST_PresetLineDashVal`), `EG_LineJoinProperties`,
+ *   `a:headEnd`/`a:tailEnd` (`CT_LineEndProperties` `@type` `ST_LineEndType`);
+ *   `@w` (`ST_LineWidth` EMU 0…20116800), `@cap` (`ST_LineCap`)
+ * - `a:headEnd`/`a:tailEnd` arrow types are schema tokens (`ST_LineEndType`).
+ *   ShapeRequirements Arrow Settings (begin/end type + size) maps to these;
+ *   sizes (`sm|med|lg`) are residual-OK for MVP but the type enums are modeled.
+ * - `wps:style` `lnRef`/`fillRef`/`effectRef`/`fontRef` — theme formatting is
+ *   **residual**: getters return `undefined`/`'theme'` discriminant instead of
+ *   inventing solid colors (GO: don't invent theme resolution).
+ *
+ * Unknown fill kinds (`gradFill`, `blipFill`, `pattFill`, `grpFill`) and effect
+ * siblings (`effectLst`, `scene3d`, `sp3d`) stay residual — GO Q9 deferred.
+ *
+ * @packageDocumentation
+ */
+import { Emus } from '../document/length';
+import { OpenXmlElement } from '../../core/xml/index';
+/**
+ * DrawingML line preset dash (`ST_PresetLineDashVal` / `a:prstDash/@val`).
+ *
+ * Members are schema wire tokens. Prefer these constants over raw strings.
+ *
+ * @public
+ */
+/**
+ * DrawingML line dash style for public LineFormat APIs.
+ *
+ * Preset members match `ST_PresetLineDashVal` / `a:prstDash/@val` wire tokens.
+ * `Unknown` is model-only (custom dash, residual, or unrecognized). Never
+ * serialize `Unknown` as `a:prstDash/@val`.
+ *
+ * @public
+ */
+export declare const LineDashing: {
+    Solid: "solid";
+    Dot: "dot";
+    Dash: "dash";
+    LargeDash: "lgDash";
+    DashDot: "dashDot";
+    LargeDashDot: "lgDashDot";
+    LargeDashDotDot: "lgDashDotDot";
+    SystemDash: "sysDash";
+    SystemDot: "sysDot";
+    SystemDashDot: "sysDashDot";
+    SystemDashDotDot: "sysDashDotDot";
+    Unknown: "unknown";
+};
+/**
+ * One of the `LineDashing` tokens.
+ * @public
+ */
+export declare type LineDashing = (typeof LineDashing)[keyof typeof LineDashing];
+/**
+ * Closed set of public LineDashing values.
+ * @public
+ */
+export declare const LINE_DASHING_VALUES: ReadonlyArray<"unknown" | "dash" | "dot" | "solid" | "lgDash" | "dashDot" | "lgDashDot" | "lgDashDotDot" | "sysDash" | "sysDot" | "sysDashDot" | "sysDashDotDot">;
+/**
+ * Whether `value` is a public LineDashing token (including Unknown).
+ * @public
+ */
+export declare function isLineDashing(value: string): value is LineDashing;
+/**
+ * Specifies how open line ends are capped (`ST_LineCap` / `a:ln/@cap`).
+ *
+ * Prefer these constants over raw strings when setting line cap style.
+ *
+ * @public
+ */
+export declare const LineCap: {
+    /**
+     * Round cap at each open end of the stroke.
+     * @public
+     */
+    Round: "rnd";
+    /**
+     * Square cap extending half the line width past each open end.
+     * @public
+     */
+    Square: "sq";
+    /**
+     * Flat cap that ends exactly at the line endpoint.
+     * @public
+     */
+    Flat: "flat";
+};
+/**
+ * One of the `LineCap` tokens.
+ * @public
+ */
+export declare type LineCap = (typeof LineCap)[keyof typeof LineCap];
+/**
+ * Closed set of `ST_LineCap` wire tokens.
+ * @public
+ */
+export declare const LINE_CAP_VALUES: ReadonlyArray<"rnd" | "sq" | "flat">;
+/**
+ * Specifies the arrowhead shape drawn at the beginning or end of a line
+ * (`ST_LineEndType` / `a:headEnd|a:tailEnd/@type`).
+ *
+ * Prefer these constants over raw strings when setting line end type.
+ *
+ * @public
+ */
+export declare const LineEndType: {
+    /**
+     * No arrowhead at the line end.
+     * @public
+     */
+    None: "none";
+    /**
+     * Filled triangular arrowhead.
+     * @public
+     */
+    Triangle: "triangle";
+    /**
+     * Stealth (indented) arrowhead.
+     * @public
+     */
+    Stealth: "stealth";
+    /**
+     * Diamond-shaped line end marker.
+     * @public
+     */
+    Diamond: "diamond";
+    /**
+     * Oval line end marker.
+     * @public
+     */
+    Oval: "oval";
+    /**
+     * Open arrowhead.
+     * @public
+     */
+    Arrow: "arrow";
+};
+/**
+ * One of the `LineEndType` tokens.
+ * @public
+ */
+export declare type LineEndType = (typeof LineEndType)[keyof typeof LineEndType];
+/**
+ * Closed set of `ST_LineEndType` wire tokens.
+ * @public
+ */
+export declare const LINE_END_TYPE_VALUES: ReadonlyArray<"none" | "triangle" | "diamond" | "stealth" | "oval" | "arrow">;
+/**
+ * DrawingML arrow end size tokens (`ST_LineEndWidth` / `ST_LineEndLength`).
+ * @public
+ */
+export declare const LINE_END_SIZE_VALUES: ReadonlyArray<"sm" | "med" | "lg">;
+/**
+ * DrawingML arrow end size (`sm` | `med` | `lg`).
+ * @public
+ */
+export declare type LineEndSize = (typeof LINE_END_SIZE_VALUES)[number];
+/**
+ * Shape line fill kind discriminant (`EG_LineFillProperties` MVP).
+ *
+ * Members are model tokens (not a single XSD enum). Prefer these constants
+ * over raw strings when authoring {@link ShapeLine}.
+ *
+ * @public
+ */
+export declare const ShapeLineKind: {
+    Solid: "solid";
+    None: "none";
+    Theme: "theme";
+    Unknown: "unknown";
+};
+/**
+ * One of the `ShapeLineKind` tokens.
+ * @public
+ */
+export declare type ShapeLineKind = (typeof ShapeLineKind)[keyof typeof ShapeLineKind];
+/**
+ * Whether `value` is a schema `ST_LineCap` token.
+ *
+ * @private
+ */
+export declare function isLineCap(value: string): value is LineCap;
+/**
+ * Whether `value` is a schema `ST_LineEndType` token.
+ *
+ * @private
+ */
+export declare function isLineEndType(value: string): value is LineEndType;
+/**
+ * Whether `value` is a schema `ST_LineEndWidth`/`ST_LineEndLength` token.
+ *
+ * @private
+ */
+export declare function isLineEndSize(value: string): value is LineEndSize;
+/**
+ * Shape fill model (`EG_FillProperties` MVP subset).
+ *
+ * Discriminated by `kind`:
+ * - `solid` — explicit `a:solidFill` with six-digit sRGB
+ * - `none` — `a:noFill`
+ * - `theme` — theme reference only (`wps:style` / non-sRGB color choice); not resolved
+ * - `pattern` — residual `a:pattFill` (preset token when present)
+ * - `unknown` — other residual fill kinds (`gradFill`, `blipFill`, `grpFill`, …)
+ *
+ * Only `solid` and `none` are authorable on {@link ShapeOptions.fill}.
+ *
+ * @public
+ */
+export declare type ShapeFill = {
+    readonly kind: 'solid';
+    readonly srgb: string;
+    /**
+     * DrawingML `a:alpha/@val` (0…100000 = 0%…100% opacity).
+     * Omitted means fully opaque.
+     * @private
+     */
+    readonly alpha?: number | undefined;
+} | {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'theme';
+} | {
+    readonly kind: 'pattern';
+    readonly preset: string | undefined;
+} | {
+    readonly kind: 'unknown';
+};
+/**
+ * Shape line model (`CT_LineProperties` MVP subset).
+ *
+ * Discriminated by {@link ShapeLine.kind}. Only `solid` and `none` are
+ * authorable on {@link ShapeOptions.line}. Theme and unknown paths preserve
+ * residual markup without inventing colors or dash styles.
+ *
+ * Arrow begin/end types map to `a:headEnd`/`a:tailEnd` (`ST_LineEndType`).
+ * Dash maps to `a:prstDash` (`ST_LineDashingVal`); custom dash stays residual.
+ *
+ * @public
+ */
+export interface ShapeLine {
+    /**
+     * Line fill kind (`solid` | `none` | `theme` | `unknown`).
+     * Prefer {@link ShapeLineKind} constants when authoring.
+     */
+    readonly kind: ShapeLineKind;
+    /**
+     * `a:ln/@w` width in EMU (`ST_LineWidth`, 0…20116800).
+     *
+     * @private
+     */
+    readonly widthEmu: Emus | undefined;
+    /** `a:ln/a:solidFill/a:srgbClr/@val` when line is solid (six hex digits). */
+    readonly srgbColor: string | undefined;
+    /**
+     * DrawingML `a:alpha/@val` under line solid fill (0…100000 opacity).
+     * @private
+     */
+    readonly alpha: number | undefined;
+    /** `a:ln/a:prstDash/@val` (`ST_LineDashingVal`). Prefer {@link LineDashing}. */
+    readonly dash: LineDashing | undefined;
+    /** `a:ln/@cap` (`ST_LineCap`). Prefer {@link LineCap}. */
+    readonly cap: LineCap | undefined;
+    /** `a:ln/a:headEnd/@type` (`ST_LineEndType`). Prefer {@link LineEndType}. */
+    readonly beginArrowType: LineEndType | undefined;
+    /** `a:ln/a:headEnd/@w` (`ST_LineEndWidth`). */
+    readonly beginArrowSize: LineEndSize | undefined;
+    /** `a:ln/a:tailEnd/@type` (`ST_LineEndType`). Prefer {@link LineEndType}. */
+    readonly endArrowType: LineEndType | undefined;
+    /** `a:ln/a:tailEnd/@w` (and length when paired; see OOXML mapping). */
+    readonly endArrowSize: LineEndSize | undefined;
+    /**
+     * True when residual line markup is present (`a:custDash`, unmodeled join, …)
+     * and the line is not fully represented by the typed fields.
+     *
+     * @private
+     */
+    readonly residual: boolean;
+}
+/**
+ * @private
+ * Geometry + fill + line state read from `wps:spPr`. */
+export interface ShapePropertiesState {
+    /** `a:prstGeom/@prst` (validated ST_ShapeType); `custGeom` reads `undefined`. */
+    readonly presetGeometry: string | undefined;
+    readonly useCustomGeometry: boolean;
+    readonly fill: ShapeFill | undefined;
+    readonly line: ShapeLine | undefined;
+    /** Theme formatting present (`wps:style` sibling). */
+    readonly hasThemeStyle: boolean;
+}
+/**
+ * Shallow child lookup under `root` (direct element children only).
+ * Use for children of a known `wps:spPr` or `a:ln` parent.
+ *
+ * @private
+ */
+export declare function findSpPrElement(root: OpenXmlElement, namespaceUri: string, localName: string): OpenXmlElement | undefined;
+/**
+ * Read the sRGB color from a `CT_SolidColorFillProperties` (or `a:ln` fill).
+ * Only `a:srgbClr` is typed (GO MVP); other `EG_ColorChoice` members read as
+ * theme-ish `undefined` so the typed surface never invents values.
+ */
+export declare function solidFillSrgb(parent: OpenXmlElement): string | undefined;
+/**
+ * Read DrawingML `a:alpha/@val` under a solid-fill parent (0…100000 opacity units).
+ * @private
+ */
+export declare function solidFillAlpha(parent: OpenXmlElement): number | undefined;
+/**
+ * Convert public transparency percent (0–100) to DrawingML alpha (0–100000 opacity).
+ * @private
+ */
+export declare function transparencyToAlpha(transparency: number): number;
+/**
+ * Convert DrawingML alpha (0–100000 opacity) to public transparency percent (0–100).
+ * @private
+ */
+export declare function alphaToTransparency(alpha: number | undefined): number;
+/**
+ * Read `wps:spPr` geometry/fill/line MVP state.
+ *
+ * Residual hosts are dual MC AlternateContent trees (`w:drawing` /
+ * `mc:AlternateContent` / `mc:Choice` / `wp:anchor` / `a:graphic` /
+ * `wps:wsp`), so `wps:spPr` and sibling `wps:style` are located with a deep
+ * walk. Children of the found `spPr` stay shallow.
+ *
+ * Cites: `CT_ShapeProperties` sequence + `EG_FillProperties`/`CT_LineProperties`
+ * (dml-main.xsd); `wps:style` residual theme formatting (CT_ShapeStyle).
+ */
+export declare function readShapePropertiesState(residual: OpenXmlElement): ShapePropertiesState;
+/**
+ * Build the fill element for modeled fill MVP. Throws on non-solid/none kinds
+ * (those go through residual).
+ */
+export declare function buildFillElement(fill: ShapeFill): OpenXmlElement;
+/**
+ * Build `a:ln` from the modeled MVP subset; residual line children (join,
+ * custDash) are not re-emitted on this path.
+ */
+export declare function buildLineElement(line: {
+    readonly kind: 'solid' | 'none';
+    readonly widthEmu?: Emus | undefined;
+    readonly srgb?: string | undefined;
+    readonly alpha?: number | undefined;
+    readonly dash?: LineDashing | undefined;
+    readonly cap?: LineCap | undefined;
+    readonly beginArrowType?: LineEndType | undefined;
+    readonly beginArrowSize?: LineEndSize | undefined;
+    readonly endArrowType?: LineEndType | undefined;
+    readonly endArrowSize?: LineEndSize | undefined;
+}): OpenXmlElement;
+/**
+ * Compound line style for shape outlines (public model).
+ * Single is the only modeled style in the current codec; other values stay residual-safe.
+ * @public
+ */
+export declare const LineStyle: {
+    Single: "single";
+};
+/** @public */
+export declare type LineStyle = (typeof LineStyle)[keyof typeof LineStyle];
+/**
+ * Arrowhead style at a line end. Maps 1:1 to DrawingML `ST_LineEndType`.
+ * @public
+ */
+export declare const ArrowheadStyle: {
+    None: "none";
+    Triangle: "triangle";
+    Stealth: "stealth";
+    Diamond: "diamond";
+    Oval: "oval";
+    Arrow: "arrow";
+};
+/** @public */
+export declare type ArrowheadStyle = (typeof ArrowheadStyle)[keyof typeof ArrowheadStyle];
+/**
+ * Arrowhead size (`ST_LineEndWidth` / `ST_LineEndLength`).
+ * @public
+ */
+export declare const ArrowheadSize: {
+    Small: "sm";
+    Medium: "med";
+    Large: "lg";
+};
+/** @public */
+export declare type ArrowheadSize = (typeof ArrowheadSize)[keyof typeof ArrowheadSize];