@syncfusion/ej2-office-common 35.1.37

package/src/features/ink/ink-parser.js

@@ -0,0 +1,671 @@
+/**
+ * InkML element-tree → {@link OfficeInk} parser ([MS-ODRAWXML] §2.1.4).
+ *
+ * The caller supplies an OpenXml element tree; this module never reads bytes
+ * and never expands entities. Count guards are surfaced via
+ * {@link getLastInkParseDiagnostics} for consumer limits policy.
+ */
+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);
+};
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+import { XML_NAMESPACE } from '../../core/xml/model';
+import { INKML_NAMESPACE } from './constants';
+import { createDecodedInk } from './ink-model';
+import { unitValueToPoints } from './ink-units';
+import { elementText, getAttr, isInkMlElement } from './ink-xml';
+import { decodeTrace } from './trace-codec';
+/**
+ * Diagnostic code for untokenizable / empty-result malformed traces.
+ *
+ * @public
+ */
+export var DIAG_INVALID_INK_TRACE = 'content/invalid-ink-trace';
+var RECOGNIZED_CHANNELS = new Set(['X', 'Y', 'Z', 'S', 'T', 'SN', 'F', 'TP', 'BP', 'OTx', 'OTy', 'OA', 'OE', 'OR', 'RP', 'RR', 'RY', 'TW', 'TH', 'TC']);
+var RECOGNIZED_CHANNEL_UNITS = new Set(['dev', 'in', 'cm', 'deg', 'rad', 's', 'lb', 'g']);
+/** §2.1.4 ignore-list local names (skipped, never persisted). */
+var IGNORE_LOCAL_NAMES = new Set(['timestamp', 'canvas', 'canvasTransform', 'mapping', 'bind', 'table', 'matrix', 'traceView', 'annotation', 'annotationXML', 'channelProperty', 'traceProperty', 'brushPropertyRef', 'intermittentInfo', 'latency', 'sampleRate', 'sampleRateExact', 'srcRef', 'channelRef']);
+var BRUSH_PROP_NAMES = new Set(['width', 'height', 'color', 'transparency', 'tip', 'rasterop', 'antialiased', 'fittocurve', 'ignorepressure', 'inkeffects', 'anchorx', 'anchory', 'scalefactor']);
+var EFFECT_TOKENS = new Map([
+    ['none', 'none'],
+    ['pencil', 'pencil'],
+    ['rainbow', 'rainbow'],
+    ['galaxy', 'galaxy'],
+    ['lava', 'lava'],
+    ['ocean', 'ocean'],
+    ['rosegold', 'roseGold'],
+    ['gold', 'gold'],
+    ['silver', 'silver'],
+    ['bronze', 'bronze'],
+]);
+/** Parse defaults ([MS-ODRAWXML] §2.1.4 / OfficeParser). */
+var DEFAULT_WIDTH_CM = 0.053;
+var DEFAULT_HEIGHT_CM = 0.001;
+var DEFAULT_COLOR = '#000000';
+var DEFAULT_TIP = 'ellipse';
+var DEFAULT_RASTER_OP = 'copyPen';
+var DEFAULT_CONTEXT_REF = '#ctx0';
+var lastDiagnostics = {
+    items: [],
+    traceCount: 0,
+    packetCount: 0,
+    pointCount: 0,
+    channelValueCount: 0
+};
+/**
+ * Diagnostics from the most recent {@link parseInkXml} invocation.
+ *
+ * @public
+ */
+export function getLastInkParseDiagnostics() {
+    return lastDiagnostics;
+}
+/**
+ * Parse an InkML `ink` root element tree into a branded {@link OfficeInk}.
+ *
+ * Source: [MS-ODRAWXML] §2.1.4; W3C InkML 1.0; `docs/specs/ink-shared-codec.md`.
+ *
+ * @public
+ */
+export function parseInkXml(root) {
+    var e_1, _a, e_2, _b;
+    var diagnostics = [];
+    var packetCount = 0;
+    var pointCount = 0;
+    var channelValueCount = 0;
+    var brushes = [];
+    var contexts = [];
+    var traces = [];
+    var treeRoots = [];
+    if (!isInkRoot(root)) {
+        lastDiagnostics = {
+            items: diagnostics,
+            traceCount: 0,
+            packetCount: 0,
+            pointCount: 0,
+            channelValueCount: 0
+        };
+        return createDecodedInk({
+            traces: [],
+            brushes: []
+        });
+    }
+    // First pass: definitions (at most one considered; extras ignored after first)
+    var sawDefinitions = false;
+    try {
+        for (var _c = __values(root.children), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var child = _d.value;
+            if (child.kind !== 'element' || !isInkMlElement(child)) {
+                continue;
+            }
+            var name_1 = child.localName;
+            if (IGNORE_LOCAL_NAMES.has(name_1)) {
+                continue;
+            }
+            if (name_1 === 'definitions') {
+                if (sawDefinitions) {
+                    continue;
+                }
+                sawDefinitions = true;
+                parseDefinitions(child, brushes, contexts);
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    try {
+        // Second pass: traces / groups in document order (C# only walks root children)
+        for (var _e = __values(root.children), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var child = _f.value;
+            if (child.kind !== 'element' || !isInkMlElement(child)) {
+                continue;
+            }
+            var name_2 = child.localName;
+            if (IGNORE_LOCAL_NAMES.has(name_2) || name_2 === 'definitions') {
+                continue;
+            }
+            if (name_2 === 'trace') {
+                var _g = parseTraceElement(child, traces.length), trace = _g.trace, node = _g.node, stats = _g.stats, diagnostic = _g.diagnostic;
+                traces.push(trace);
+                treeRoots.push(node);
+                packetCount += stats.packetCount;
+                pointCount += stats.pointCount;
+                channelValueCount += stats.channelValueCount;
+                if (diagnostic !== undefined) {
+                    diagnostics.push(diagnostic);
+                }
+            }
+            else if (name_2 === 'traceGroup') {
+                var group = parseTraceGroup(child, traces, diagnostics, function (s) {
+                    packetCount += s.packetCount;
+                    pointCount += s.pointCount;
+                    channelValueCount += s.channelValueCount;
+                });
+                if (group.children.length > 0) {
+                    treeRoots.push(group);
+                }
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    lastDiagnostics = {
+        items: diagnostics,
+        traceCount: traces.length,
+        packetCount: packetCount,
+        pointCount: pointCount,
+        channelValueCount: channelValueCount
+    };
+    return createDecodedInk(__assign({ traces: traces,
+        brushes: brushes }, (contexts.length > 0 ? {
+        contexts: contexts
+    } : {}), (traces.length > 0 ? {
+        traceTree: treeRoots
+    } : {})));
+}
+function isInkRoot(el) {
+    if (el.localName !== 'ink') {
+        return false;
+    }
+    return isInkMlElement(el) || el.namespaceUri === INKML_NAMESPACE;
+}
+function parseDefinitions(def, brushes, contexts) {
+    var e_3, _a;
+    try {
+        for (var _b = __values(def.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (child.kind !== 'element' || !isInkMlElement(child)) {
+                continue;
+            }
+            if (IGNORE_LOCAL_NAMES.has(child.localName)) {
+                continue;
+            }
+            if (child.localName === 'brush') {
+                brushes.push(parseBrush(child));
+            }
+            else if (child.localName === 'context') {
+                var ctx = parseContext(child);
+                if (ctx !== undefined) {
+                    contexts.push(ctx);
+                }
+            }
+            // context only under definitions (already here); ignore elsewhere handled by root walk
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+}
+function parseContext(el) {
+    var e_4, _a;
+    var rawId = readXmlId(el);
+    if (rawId === undefined || rawId.length === 0) {
+        // Still accept context without id using a synthetic key? Spec requires id for inkSource;
+        // skip malformed context without id.
+        return undefined;
+    }
+    var id = ensureHash(rawId);
+    var inkSourceId;
+    var channels = [];
+    try {
+        for (var _b = __values(el.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (child.kind !== 'element' || !isInkMlElement(child)) {
+                continue;
+            }
+            if (IGNORE_LOCAL_NAMES.has(child.localName)) {
+                continue;
+            }
+            if (child.localName === 'inkSource') {
+                var srcId = readXmlId(child);
+                if (srcId !== undefined && srcId.length > 0) {
+                    inkSourceId = srcId;
+                }
+                // Walk inkSource for nested traceFormat as Office often nests it here
+                collectChannelsFrom(child, channels);
+            }
+            else if (child.localName === 'traceFormat') {
+                collectChannelsFrom(child, channels);
+            }
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    var ctx = {
+        id: id,
+        channels: channels
+    };
+    if (inkSourceId !== undefined) {
+        ctx.inkSourceId = inkSourceId;
+    }
+    return ctx;
+}
+function collectChannelsFrom(el, channels) {
+    var e_5, _a;
+    var _loop_1 = function (child) {
+        if (child.kind !== 'element' || !isInkMlElement(child)) {
+            return "continue";
+        }
+        if (child.localName === 'traceFormat') {
+            collectChannelsFrom(child, channels);
+            return "continue";
+        }
+        if (child.localName !== 'channel') {
+            return "continue";
+        }
+        var name_3 = function () {
+            var _nc = getAttr(child, 'name');
+            return _nc != null ? _nc : '';
+        }();
+        if (!RECOGNIZED_CHANNELS.has(name_3)) {
+            return "continue";
+        }
+        var ch = {
+            name: name_3
+        };
+        var type = getAttr(child, 'type');
+        if (type !== undefined) {
+            ch.type = type;
+        }
+        var min = getAttr(child, 'min');
+        if (min !== undefined) {
+            ch.min = min;
+        }
+        var max = getAttr(child, 'max');
+        if (max !== undefined) {
+            ch.max = max;
+        }
+        var units = getAttr(child, 'units');
+        if (units !== undefined && RECOGNIZED_CHANNEL_UNITS.has(units)) {
+            ch.units = units;
+        }
+        else if (units !== undefined) {
+            // Preserve units string even if outside short list (cm always recognized)
+            ch.units = units;
+        }
+        // orientation / respectTo ignored
+        channels.push(ch);
+    };
+    try {
+        for (var _b = __values(el.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            _loop_1(child);
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_5) throw e_5.error; }
+    }
+}
+function parseBrush(el) {
+    var e_6, _a;
+    var rawId = function () {
+        var _nc = readXmlId(el);
+        return _nc != null ? _nc : '';
+    }();
+    var id = ensureHash(rawId.length > 0 ? rawId : 'br0');
+    // Defaults (parse §2.1.4) — size stored in points after unit conversion
+    var widthPt = unitValueToPoints(DEFAULT_WIDTH_CM, 'cm');
+    var heightPt = unitValueToPoints(DEFAULT_HEIGHT_CM, 'cm');
+    var units = 'cm';
+    var color = DEFAULT_COLOR;
+    var tip = DEFAULT_TIP;
+    var rasterOp = DEFAULT_RASTER_OP;
+    var ignorePressure = false;
+    var inkEffect = 'none';
+    var anchorX;
+    var anchorY;
+    var scaleFactor;
+    var transparency;
+    var antiAliased;
+    var fitToCurve;
+    var sawWidth = false;
+    var sawHeight = false;
+    var _loop_2 = function (child) {
+        if (child.kind !== 'element' || !isInkMlElement(child)) {
+            return "continue";
+        }
+        if (child.localName !== 'brushProperty') {
+            return "continue";
+        }
+        var nameRaw = getAttr(child, 'name');
+        if (nameRaw === undefined) {
+            return "continue";
+        }
+        var name_4 = nameRaw.trim().toLowerCase();
+        if (!BRUSH_PROP_NAMES.has(name_4)) {
+            return "continue";
+        }
+        var valueRaw = function () {
+            var _nc = getAttr(child, 'value');
+            return _nc != null ? _nc : '';
+        }();
+        var unitsAttr = getAttr(child, 'units');
+        switch (name_4) {
+            case 'width':
+                {
+                    var n = parseLengthNumber(valueRaw);
+                    if (n !== undefined) {
+                        var u = unitsAttr != null ? unitsAttr : 'cm';
+                        widthPt = unitValueToPoints(n, u);
+                        if (!sawHeight) {
+                            units = u;
+                        }
+                        sawWidth = true;
+                        units = u;
+                    }
+                    break;
+                }
+            case 'height':
+                {
+                    var n = parseLengthNumber(valueRaw);
+                    if (n !== undefined) {
+                        var u = unitsAttr != null ? unitsAttr : units;
+                        heightPt = unitValueToPoints(n, u);
+                        sawHeight = true;
+                        if (unitsAttr !== undefined) {
+                            units = unitsAttr;
+                        }
+                    }
+                    break;
+                }
+            case 'color':
+                {
+                    var hex = normalizeColor(valueRaw);
+                    if (hex !== undefined) {
+                        color = hex;
+                    }
+                    break;
+                }
+            case 'tip':
+                {
+                    if (valueRaw.length > 0) {
+                        tip = valueRaw;
+                    }
+                    break;
+                }
+            case 'rasterop':
+                {
+                    if (valueRaw.length > 0) {
+                        rasterOp = valueRaw;
+                    }
+                    break;
+                }
+            case 'ignorepressure':
+                {
+                    ignorePressure = parseBoolish(valueRaw);
+                    break;
+                }
+            case 'inkeffects':
+                {
+                    var token = valueRaw.trim().toLowerCase().replace(/[_\s-]/g, '');
+                    var mapped = EFFECT_TOKENS.get(token);
+                    if (mapped !== undefined) {
+                        inkEffect = mapped;
+                    }
+                    break;
+                }
+            case 'anchorx':
+                {
+                    anchorX = valueRaw;
+                    break;
+                }
+            case 'anchory':
+                {
+                    anchorY = valueRaw;
+                    break;
+                }
+            case 'scalefactor':
+                {
+                    scaleFactor = valueRaw;
+                    break;
+                }
+            case 'transparency':
+                {
+                    var n = Number(valueRaw);
+                    if (Number.isFinite(n)) {
+                        transparency = n;
+                    }
+                    break;
+                }
+            case 'antialiased':
+                {
+                    antiAliased = parseBoolish(valueRaw);
+                    break;
+                }
+            case 'fittocurve':
+                {
+                    fitToCurve = parseBoolish(valueRaw);
+                    break;
+                }
+            default:
+                break;
+        }
+    };
+    try {
+        for (var _b = __values(el.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            _loop_2(child);
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+    // If neither width nor height units seen, keep cm (default source unit)
+    if (!sawWidth && !sawHeight) {
+        units = 'cm';
+    }
+    var brush = {
+        id: id,
+        color: color,
+        size: {
+            width: widthPt,
+            height: heightPt
+        },
+        units: units,
+        inkEffect: inkEffect,
+        ignorePressure: ignorePressure,
+        tip: tip,
+        rasterOp: rasterOp
+    };
+    if (anchorX !== undefined) {
+        brush.anchorX = anchorX;
+    }
+    if (anchorY !== undefined) {
+        brush.anchorY = anchorY;
+    }
+    if (scaleFactor !== undefined) {
+        brush.scaleFactor = scaleFactor;
+    }
+    if (transparency !== undefined) {
+        brush.transparency = transparency;
+    }
+    if (antiAliased !== undefined) {
+        brush.antiAliased = antiAliased;
+    }
+    if (fitToCurve !== undefined) {
+        brush.fitToCurve = fitToCurve;
+    }
+    return brush;
+}
+function parseTraceElement(el, traceIndex) {
+    var brushRefRaw = function () {
+        var _nc = getAttr(el, 'brushRef');
+        return _nc != null ? _nc : '';
+    }();
+    var contextRefRaw = function () {
+        var _nc = getAttr(el, 'contextRef');
+        return _nc != null ? _nc : '';
+    }();
+    var timeOffset = getAttr(el, 'timeOffset');
+    var text = elementText(el).trim();
+    var decoded = decodeTrace(text);
+    var diagnostic;
+    // Malformed: non-empty text that produced zero points → diagnostic
+    if (text.length > 0 && decoded.points.length === 0) {
+        diagnostic = {
+            code: DIAG_INVALID_INK_TRACE,
+            message: 'malformed or untokenizable ink trace text',
+            traceIndex: traceIndex
+        };
+    }
+    var trace = {
+        points: decoded.points.map(function (p) { return ({
+            x: p.x,
+            y: p.y
+        }); }),
+        brushRef: brushRefRaw.length > 0 ? ensureHash(brushRefRaw.replace(/^#/, '')) : '',
+        contextRef: contextRefRaw.length > 0 ? ensureHash(contextRefRaw.replace(/^#/, '')) : DEFAULT_CONTEXT_REF
+    };
+    // Preserve brushRef as given with hash; empty string means unset
+    if (brushRefRaw.length > 0) {
+        trace.brushRef = brushRefRaw.startsWith('#') ? brushRefRaw : ensureHash(brushRefRaw);
+    }
+    if (timeOffset !== undefined) {
+        trace.timeOffset = timeOffset;
+    }
+    return {
+        trace: trace,
+        node: {
+            kind: 'trace',
+            traceIndex: traceIndex
+        },
+        stats: {
+            packetCount: decoded.stats.packetCount,
+            pointCount: decoded.stats.pointCount,
+            channelValueCount: decoded.stats.channelValueCount
+        },
+        diagnostic: diagnostic
+    };
+}
+function parseTraceGroup(el, traces, diagnostics, onStats) {
+    var e_7, _a;
+    var children = [];
+    try {
+        for (var _b = __values(el.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (child.kind !== 'element' || !isInkMlElement(child)) {
+                continue;
+            }
+            if (IGNORE_LOCAL_NAMES.has(child.localName)) {
+                // annotationXML / annotation: ignored per §2.1.4 (decision: do not retain)
+                continue;
+            }
+            if (child.localName === 'trace') {
+                var _d = parseTraceElement(child, traces.length), trace = _d.trace, node = _d.node, stats = _d.stats, diagnostic = _d.diagnostic;
+                traces.push(trace);
+                children.push(node);
+                onStats(stats);
+                if (diagnostic !== undefined) {
+                    diagnostics.push(diagnostic);
+                }
+            }
+            else if (child.localName === 'traceGroup') {
+                var nested = parseTraceGroup(child, traces, diagnostics, onStats);
+                if (nested.children.length > 0) {
+                    children.push(nested);
+                }
+            }
+        }
+    }
+    catch (e_7_1) { e_7 = { error: e_7_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_7) throw e_7.error; }
+    }
+    return {
+        kind: 'group',
+        children: children
+    };
+}
+function readXmlId(el) {
+    var fromNs = getAttr(el, 'id', XML_NAMESPACE);
+    if (fromNs !== undefined) {
+        return fromNs;
+    }
+    return getAttr(el, 'id');
+}
+function ensureHash(id) {
+    return id.startsWith('#') ? id : "#" + id;
+}
+function parseLengthNumber(raw) {
+    var s = raw.trim();
+    if (s.length === 0) {
+        return undefined;
+    }
+    // GetPointValue: leading `.` → `0.`
+    if (s.startsWith('.')) {
+        s = "0" + s;
+    }
+    var n = Number(s);
+    return Number.isFinite(n) ? n : undefined;
+}
+function normalizeColor(raw) {
+    var s = raw.trim();
+    if (s.length === 0) {
+        return undefined;
+    }
+    if (!s.startsWith('#')) {
+        s = "#" + s;
+    }
+    // Accept #RGB or #RRGGBB
+    if (/^#[0-9A-Fa-f]{6}$/.test(s) || /^#[0-9A-Fa-f]{3}$/.test(s)) {
+        if (s.length === 4) {
+            var r = s.charAt(1);
+            var g = s.charAt(2);
+            var b = s.charAt(3);
+            return ("#" + r + r + g + g + b + b).toUpperCase();
+        }
+        return s.toUpperCase();
+    }
+    return undefined;
+}
+function parseBoolish(raw) {
+    var s = raw.trim().toLowerCase();
+    return s === '1' || s === 'true';
+}

package/src/features/ink/ink-serializer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * {@link OfficeInk} → InkML element tree serializer ([MS-ODRAWXML] §2.1.4).
+ *
+ * Trace text is always {@link encodeTrace} from points — never stored XML text.
+ * Brush property order matches `docs/specs/ink-shared-codec.md` / TASK-9003.
+ */
+import { OpenXmlElement } from '../../core/xml/model';
+import { OfficeInk } from './ink-model';
+/**
+ * Serialize an {@link OfficeInk} DOM to an InkML `ink` root element.
+ *
+ * Source: [MS-ODRAWXML] §2.1.4; `docs/specs/ink-shared-codec.md` Serializer behavior.
+ *
+ * @private
+ */
+export declare function serializeInkXml(ink: OfficeInk): OpenXmlElement;