@syncfusion/ej2-office-common 35.1.37

package/src/features/diagrams/constants.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SmartArt / DrawingML diagram constants.
+ *
+ * Citations:
+ * - ECMA-376-1 5th ed. §14.2.3–§14.2.6 (diagram parts)
+ * - ECMA-376-1 Part 1 Transitional namespaces (schemas.openxmlformats.org)
+ * - ECMA-376 Strict namespaces (purl.oclc.org/ooxml/…)
+ * - dml-diagram.xsd CT_RelIds / content types
+ * - [MS-ODRAWXML] §2.1.3 / §2.10 diagramDrawing extension
+ * - Requirement docs/requirements/smart-art-diagrams.md §16.1–§16.2
+ */
+/** DrawingML diagram namespace (Transitional). dml-diagram.xsd targetNamespace. */
+export declare const DGM_NAMESPACE = "http://schemas.openxmlformats.org/drawingml/2006/diagram";
+/** DrawingML diagram namespace (Strict). Accepted on parse only. */
+export declare const DGM_NAMESPACE_STRICT = "http://purl.oclc.org/ooxml/drawingml/diagram";
+/** DrawingML main namespace (Transitional). */
+export declare const A_NAMESPACE = "http://schemas.openxmlformats.org/drawingml/2006/main";
+/** DrawingML main namespace (Strict). Accepted on parse only. */
+export declare const A_NAMESPACE_STRICT = "http://purl.oclc.org/ooxml/drawingml/main";
+/** Office document relationships namespace (Transitional). */
+export declare const R_NAMESPACE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/** Office document relationships namespace (Strict). Accepted on parse only. */
+export declare const R_NAMESPACE_STRICT = "http://purl.oclc.org/ooxml/officeDocument/relationships";
+/** WordprocessingML namespace (Transitional) — host w:drawing. */
+export declare const W_NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+/** WordprocessingML Drawing (wp:) namespace (Transitional). */
+export declare const WP_NAMESPACE = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+/**
+ * Microsoft Office Drawing diagram extension namespace (`dsp:`).
+ * [MS-ODRAWXML] §2.1.3.
+ */
+export declare const DSP_NAMESPACE = "http://schemas.microsoft.com/office/drawing/2008/diagram";
+/**
+ * Diagram 2010 extension namespace used by `dgm14:recolorImg`.
+ * URI of the extension: C62137D5-CB1D-491b-B009-E17868A290BF
+ */
+export declare const DGM14_NAMESPACE = "http://schemas.microsoft.com/office/drawing/2010/diagram";
+/** dgm14:recolorImg extension URI (a:ext/@uri). */
+export declare const DGM14_RECOLOR_IMG_EXT_URI = "C62137D5-CB1D-491b-B009-E17868A290BF";
+/**
+ * Microsoft dataModelExt extension URI on dataModel/extLst/a:ext.
+ * [MS-ODRAWXML] §2.10.1.1 — Word-observed package shape.
+ */
+export declare const MS_DIAGRAM_DATA_MODEL_EXT_URI = "http://schemas.microsoft.com/office/drawing/2008/diagram";
+/**
+ * a:graphicData@uri identifying a DrawingML diagram (SmartArt host).
+ * ECMA-376 / dml-diagram.xsd; requirement §16.3.
+ */
+export declare const DIAGRAM_GRAPHIC_DATA_URI = "http://schemas.openxmlformats.org/drawingml/2006/diagram";
+/** Strict form of DIAGRAM_GRAPHIC_DATA_URI — accepted on read. */
+export declare const DIAGRAM_GRAPHIC_DATA_URI_STRICT = "http://purl.oclc.org/ooxml/drawingml/diagram";
+export declare const DIAGRAM_DATA_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawingml.diagramData+xml";
+export declare const DIAGRAM_LAYOUT_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawingml.diagramLayout+xml";
+/**
+ * Quick style part content type. Note: content type uses `diagramStyle`
+ * while the relationship type uses `diagramQuickStyle` (requirement §16.2).
+ */
+export declare const DIAGRAM_QUICK_STYLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawingml.diagramStyle+xml";
+export declare const DIAGRAM_COLORS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawingml.diagramColors+xml";
+/** Microsoft cached diagram drawing part. [MS-ODRAWXML] §2.1.3. */
+export declare const DIAGRAM_DRAWING_CONTENT_TYPE = "application/vnd.ms-office.drawingml.diagramDrawing+xml";
+export declare const DIAGRAM_DATA_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData";
+export declare const DIAGRAM_LAYOUT_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramLayout";
+export declare const DIAGRAM_QUICK_STYLE_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramQuickStyle";
+export declare const DIAGRAM_COLORS_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramColors";
+/** Microsoft cached drawing relationship. [MS-ODRAWXML] §2.1.3. */
+export declare const DIAGRAM_DRAWING_RELATIONSHIP_TYPE = "http://schemas.microsoft.com/office/2007/relationships/diagramDrawing";
+/** Feature id used in run-leaf `{ type: 'feature', featureId: 'diagrams', … }`. */
+export declare const DIAGRAMS_FEATURE_ID = "diagrams";
+/**
+ * Soft guards for untrusted diagram graphs (security.md).
+ * Surface via typed errors; do not silently truncate.
+ */
+export declare const MAX_DIAGRAM_POINTS = 10000;
+export declare const MAX_DIAGRAM_CONNECTIONS = 20000;
+/** True when uri identifies a diagram graphicData (Transitional or Strict). */
+export declare function isDiagramGraphicDataUri(uri: string | null | undefined): boolean;
+/** True when namespace is dgm Transitional or Strict. */
+export declare function isDgmNamespace(ns: string | null | undefined): boolean;
+/** True when namespace is DrawingML main Transitional or Strict. */
+export declare function isANamespace(ns: string | null | undefined): boolean;
+/** True when namespace is relationships Transitional or Strict. */
+export declare function isRNamespace(ns: string | null | undefined): boolean;

package/src/features/diagrams/constants.js

@@ -0,0 +1,101 @@
+/**
+ * SmartArt / DrawingML diagram constants.
+ *
+ * Citations:
+ * - ECMA-376-1 5th ed. §14.2.3–§14.2.6 (diagram parts)
+ * - ECMA-376-1 Part 1 Transitional namespaces (schemas.openxmlformats.org)
+ * - ECMA-376 Strict namespaces (purl.oclc.org/ooxml/…)
+ * - dml-diagram.xsd CT_RelIds / content types
+ * - [MS-ODRAWXML] §2.1.3 / §2.10 diagramDrawing extension
+ * - Requirement docs/requirements/smart-art-diagrams.md §16.1–§16.2
+ */
+/** DrawingML diagram namespace (Transitional). dml-diagram.xsd targetNamespace. */
+export var DGM_NAMESPACE = 'http://schemas.openxmlformats.org/drawingml/2006/diagram';
+/** DrawingML diagram namespace (Strict). Accepted on parse only. */
+export var DGM_NAMESPACE_STRICT = 'http://purl.oclc.org/ooxml/drawingml/diagram';
+/** DrawingML main namespace (Transitional). */
+export var A_NAMESPACE = 'http://schemas.openxmlformats.org/drawingml/2006/main';
+/** DrawingML main namespace (Strict). Accepted on parse only. */
+export var A_NAMESPACE_STRICT = 'http://purl.oclc.org/ooxml/drawingml/main';
+/** Office document relationships namespace (Transitional). */
+export var R_NAMESPACE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+/** Office document relationships namespace (Strict). Accepted on parse only. */
+export var R_NAMESPACE_STRICT = 'http://purl.oclc.org/ooxml/officeDocument/relationships';
+/** WordprocessingML namespace (Transitional) — host w:drawing. */
+export var W_NAMESPACE = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+/** WordprocessingML Drawing (wp:) namespace (Transitional). */
+export var WP_NAMESPACE = 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing';
+/**
+ * Microsoft Office Drawing diagram extension namespace (`dsp:`).
+ * [MS-ODRAWXML] §2.1.3.
+ */
+export var DSP_NAMESPACE = 'http://schemas.microsoft.com/office/drawing/2008/diagram';
+/**
+ * Diagram 2010 extension namespace used by `dgm14:recolorImg`.
+ * URI of the extension: C62137D5-CB1D-491b-B009-E17868A290BF
+ */
+export var DGM14_NAMESPACE = 'http://schemas.microsoft.com/office/drawing/2010/diagram';
+/** dgm14:recolorImg extension URI (a:ext/@uri). */
+export var DGM14_RECOLOR_IMG_EXT_URI = 'C62137D5-CB1D-491b-B009-E17868A290BF';
+/**
+ * Microsoft dataModelExt extension URI on dataModel/extLst/a:ext.
+ * [MS-ODRAWXML] §2.10.1.1 — Word-observed package shape.
+ */
+export var MS_DIAGRAM_DATA_MODEL_EXT_URI = 'http://schemas.microsoft.com/office/drawing/2008/diagram';
+/**
+ * a:graphicData@uri identifying a DrawingML diagram (SmartArt host).
+ * ECMA-376 / dml-diagram.xsd; requirement §16.3.
+ */
+export var DIAGRAM_GRAPHIC_DATA_URI = 'http://schemas.openxmlformats.org/drawingml/2006/diagram';
+/** Strict form of DIAGRAM_GRAPHIC_DATA_URI — accepted on read. */
+export var DIAGRAM_GRAPHIC_DATA_URI_STRICT = 'http://purl.oclc.org/ooxml/drawingml/diagram';
+// ── Content types (ECMA-376-1 §14.2.3–§14.2.6; [MS-ODRAWXML] drawing) ──
+export var DIAGRAM_DATA_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.diagramData+xml';
+export var DIAGRAM_LAYOUT_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.diagramLayout+xml';
+/**
+ * Quick style part content type. Note: content type uses `diagramStyle`
+ * while the relationship type uses `diagramQuickStyle` (requirement §16.2).
+ */
+export var DIAGRAM_QUICK_STYLE_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.diagramStyle+xml';
+export var DIAGRAM_COLORS_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.diagramColors+xml';
+/** Microsoft cached diagram drawing part. [MS-ODRAWXML] §2.1.3. */
+export var DIAGRAM_DRAWING_CONTENT_TYPE = 'application/vnd.ms-office.drawingml.diagramDrawing+xml';
+// ── Relationship types ──
+export var DIAGRAM_DATA_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData';
+export var DIAGRAM_LAYOUT_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramLayout';
+export var DIAGRAM_QUICK_STYLE_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramQuickStyle';
+export var DIAGRAM_COLORS_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramColors';
+/** Microsoft cached drawing relationship. [MS-ODRAWXML] §2.1.3. */
+export var DIAGRAM_DRAWING_RELATIONSHIP_TYPE = 'http://schemas.microsoft.com/office/2007/relationships/diagramDrawing';
+/** Feature id used in run-leaf `{ type: 'feature', featureId: 'diagrams', … }`. */
+export var DIAGRAMS_FEATURE_ID = 'diagrams';
+/**
+ * Soft guards for untrusted diagram graphs (security.md).
+ * Surface via typed errors; do not silently truncate.
+ */
+export var MAX_DIAGRAM_POINTS = 10000;
+export var MAX_DIAGRAM_CONNECTIONS = 20000;
+/** True when uri identifies a diagram graphicData (Transitional or Strict). */
+export function isDiagramGraphicDataUri(uri) {
+    if (uri == null || uri === '')
+        return false;
+    return uri === DIAGRAM_GRAPHIC_DATA_URI || uri === DIAGRAM_GRAPHIC_DATA_URI_STRICT;
+}
+/** True when namespace is dgm Transitional or Strict. */
+export function isDgmNamespace(ns) {
+    if (ns == null || ns === '')
+        return false;
+    return ns === DGM_NAMESPACE || ns === DGM_NAMESPACE_STRICT;
+}
+/** True when namespace is DrawingML main Transitional or Strict. */
+export function isANamespace(ns) {
+    if (ns == null || ns === '')
+        return false;
+    return ns === A_NAMESPACE || ns === A_NAMESPACE_STRICT;
+}
+/** True when namespace is relationships Transitional or Strict. */
+export function isRNamespace(ns) {
+    if (ns == null || ns === '')
+        return false;
+    return ns === R_NAMESPACE || ns === R_NAMESPACE_STRICT;
+}

package/src/features/diagrams/diagram-data-model.d.ts

@@ -0,0 +1,148 @@
+/**
+ * DiagramDataModel — CT_DataModel view/API.
+ *
+ * Citations:
+ * - dml-diagram.xsd CT_DataModel, CT_Pt, CT_Cxn, ST_PtType, ST_CxnType, ST_ModelId
+ * - Requirement docs/requirements/smart-art-diagrams.md §12 (maintenance API)
+ * - ECMA-376 DrawingML diagram data part
+ */
+import { ElementNode } from './element-tree';
+declare const DIAGRAM_DATA_MODEL_BRAND: unique symbol;
+/** ST_PtType (dml-diagram.xsd). Default: node. */
+export declare type DiagramPointType = 'node' | 'asst' | 'doc' | 'pres' | 'parTrans' | 'sibTrans';
+/**
+ * ST_CxnType (dml-diagram.xsd). XSD default: **parOf**.
+ * (Some narrative docs say presOf; implementers MUST use XSD default parOf.)
+ */
+export declare type DiagramConnectionType = 'parOf' | 'presOf' | 'presParOf' | 'unknownRelationship';
+/** ST_ModelId: int or GUID string as stored in markup. */
+export declare type ModelId = string;
+export interface DiagramPointProps {
+    readonly modelId: ModelId;
+    /** Default `node` per XSD. */
+    readonly type?: DiagramPointType;
+    /** Default `"0"` per XSD cxnId. */
+    readonly cxnId?: ModelId;
+    /**
+     * Opaque element-tree fragment for prSet / spPr / t / extLst children
+     * preserved for round-trip. Callers of setNodeText replace text under `t`.
+     */
+    readonly body?: ElementNode | null;
+}
+export interface DiagramConnectionProps {
+    readonly modelId: ModelId;
+    /** Default `parOf` per XSD. */
+    readonly type?: DiagramConnectionType;
+    readonly srcId: ModelId;
+    readonly destId: ModelId;
+    readonly srcOrd: number;
+    readonly destOrd: number;
+    readonly parTransId?: ModelId;
+    readonly sibTransId?: ModelId;
+    readonly presId?: string;
+    readonly body?: ElementNode | null;
+}
+export interface DiagramPoint {
+    modelId: ModelId;
+    type: DiagramPointType;
+    cxnId: ModelId;
+    /** Mutable body subtree (prSet/spPr/t/extLst). */
+    body: ElementNode | null;
+}
+export interface DiagramConnection {
+    modelId: ModelId;
+    type: DiagramConnectionType;
+    srcId: ModelId;
+    destId: ModelId;
+    srcOrd: number;
+    destOrd: number;
+    parTransId: ModelId;
+    sibTransId: ModelId;
+    presId: string;
+    body: ElementNode | null;
+}
+export interface DiagramDataModelInit {
+    readonly points?: ReadonlyArray<DiagramPointProps>;
+    readonly connections?: ReadonlyArray<DiagramConnectionProps>;
+    /** bg / whole / extLst preserved as opaque trees. */
+    readonly background?: ElementNode | null;
+    readonly whole?: ElementNode | null;
+    readonly extLst?: ElementNode | null;
+}
+/**
+ * Mutable CT_DataModel graph.
+ * Identity: `instanceof DiagramDataModel` and brand symbol.
+ */
+export declare class DiagramDataModel {
+    readonly [DIAGRAM_DATA_MODEL_BRAND]: true;
+    private readonly _points;
+    private readonly _connections;
+    private _background;
+    private _whole;
+    private _extLst;
+    private _dirty;
+    /** Optional original part bytes when loaded clean (D14). */
+    private _originalBytes;
+    constructor(init?: DiagramDataModelInit);
+    readonly dirty: boolean;
+    /** Mark dirty and drop original bytes (must reserialize). */
+    markDirty(): void;
+    /** Clear dirty after successful apply; optionally stash bytes. */
+    clearDirty(originalBytes?: Uint8Array | null): void;
+    readonly originalBytes: Uint8Array | null;
+    setOriginalBytes(bytes: Uint8Array | null): void;
+    readonly points: ReadonlyArray<DiagramPoint>;
+    readonly connections: ReadonlyArray<DiagramConnection>;
+    background: ElementNode | null;
+    whole: ElementNode | null;
+    extLst: ElementNode | null;
+    pointCount(): number;
+    connectionCount(): number;
+    getPoint(modelId: ModelId): DiagramPoint | undefined;
+    getConnection(modelId: ModelId): DiagramConnection | undefined;
+    /**
+     * Document point (`type=doc`) if present — typically the root of the logical tree.
+     */
+    documentPoint(): DiagramPoint | undefined;
+    /**
+     * Child node points under `parentId` via parOf connections, ordered by srcOrd.
+     * Requirement §12 hierarchy helpers.
+     */
+    childrenOf(parentId: ModelId): DiagramPoint[];
+    /** Parent via reverse parOf (first match). */
+    parentOf(nodeId: ModelId): DiagramPoint | undefined;
+    /**
+     * Replace text content of the point's `t` (dgm:t / a:t shape) body fragment.
+     * If no body/`t` exists, creates a minimal text body hook for the serializer.
+     * Requirement §12 setNodeText.
+     */
+    setNodeText(modelId: ModelId, value: string): void;
+    /** Read text from point body (`t` localName preferred). */
+    getNodeText(modelId: ModelId): string | undefined;
+    addPoint(props: DiagramPointProps): DiagramPoint;
+    addConnection(props: DiagramConnectionProps): DiagramConnection;
+    /**
+     * Append a child node under parent via parOf.
+     * Creates point + connection; assigns next srcOrd.
+     */
+    appendChild(parentId: ModelId, child: DiagramPointProps, connectionModelId: ModelId): {
+        point: DiagramPoint;
+        connection: DiagramConnection;
+    };
+    /**
+     * Remove a node and its incident connections (and optionally subtree).
+     * When `recursive` is true, removes descendants via parOf.
+     */
+    removeNode(modelId: ModelId, recursive?: boolean): void;
+    /**
+     * Deep clone of the model (new instance, dirty=false unless copyDirty).
+     */
+    clone(options?: {
+        copyDirty?: boolean;
+    }): DiagramDataModel;
+}
+/**
+ * @private
+ */
+export declare function isDiagramDataModel(value: unknown): value is DiagramDataModel;
+export {};