@office-open/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Demo Macro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @office-open/core
+
+![npm version](https://img.shields.io/npm/v/@office-open/core)
+![npm downloads](https://img.shields.io/npm/dw/@office-open/core)
+![npm license](https://img.shields.io/npm/l/@office-open/core)
+
+> Shared OOXML infrastructure: XmlComponent, value validators, unit converters, chart types, and SmartArt definitions.
+
+## Features
+
+- **XmlComponent Framework** - Base classes for building OOXML element trees with dynamic namespace support
+- **Value Validators** - Runtime validation for OOXML spec types (ST_HexColor, ST_OnOff, ST_DecimalNumber, etc.)
+- **Unit Converters** - TWIP and EMU conversions (mm/in/pt/px)
+- **Chart Components** - Shared chart types (bar, line, pie, area, scatter) and chart collection for DOCX/PPTX
+- **SmartArt Components** - Data model, tree-to-model converter, collection, and built-in layout/style/color definitions
+- **ID Generators** - Sequential numeric IDs, nanoid, SHA-1 hash, UUID v4
+- **OOXML Compliance** - All types verified against ISO/IEC 29500-4 XSD schemas
+
+## Installation
+
+```bash
+# Install with npm
+$ npm install @office-open/core
+
+# Install with pnpm
+$ pnpm add @office-open/core
+```
+
+## Quick Start
+
+```typescript
+import {
+    OnOffElement,
+    StringValueElement,
+    BuilderElement,
+    StringContainer,
+    hexColorValue,
+    decimalNumber,
+    convertMillimetersToTwip,
+    uniqueNumericIdCreator,
+} from "@office-open/core";
+
+// CT_OnOff — dynamic namespace prefix per XSD spec
+new OnOffElement("w:b", false);
+// → { "w:b": { _attr: { "w:val": false } } }
+
+new OnOffElement("m:hideBot", false);
+// → { "m:hideBot": { _attr: { "m:val": false } } }
+
+// Builder with attributes + children
+new BuilderElement({
+    name: "w:r",
+    attributes: { lang: { key: "xml:lang", value: "en-US" } },
+    children: [new StringContainer("w:t", "Hello")],
+});
+
+// Value validators
+hexColorValue("#FF0000"); // → "FF0000"
+hexColorValue("auto"); // → "auto"
+decimalNumber(10.7); // → 10
+
+// Unit converters
+convertMillimetersToTwip(25.4); // → 1440 (1 inch)
+convertPixelsToEmu(100); // → 952500
+convertInchesToEmu(1); // → 914400
+convertPointsToEmu(12); // → 152400
+
+// ID generators
+const gen = uniqueNumericIdCreator();
+gen(); // → 1, 2, 3, ...
+```
+
+## OOXML Schema Compliance
+
+| Type                 | XSD Reference                                  |
+| -------------------- | ---------------------------------------------- |
+| `ThemeColor`         | `ST_ThemeColor` (17 values)                    |
+| `ThemeFont`          | `ST_Theme` (8 values)                          |
+| `UniversalMeasure`   | `ST_UniversalMeasure` (mm, cm, in, pt, pc, pi) |
+| `Percentage`         | `ST_Percentage`                                |
+| `hexColorValue`      | `ST_HexColor` (auto + 3-byte hexBinary)        |
+| `OnOffElement`       | `CT_OnOff` (dynamic namespace prefix)          |
+| `HpsMeasureElement`  | `CT_HpsMeasure`                                |
+| `StringValueElement` | `CT_String`                                    |
+
+## Exports
+
+| Path                         | Contents                                            |
+| ---------------------------- | --------------------------------------------------- |
+| `@office-open/core`          | XmlComponent, validators, converters, ID generators |
+| `@office-open/core/values`   | Validators + ThemeColor/ThemeFont only              |
+| `@office-open/core/chart`    | Chart types, series data, chart collection, title   |
+| `@office-open/core/smartart` | SmartArt data model, tree-to-model, definitions     |
+
+## Benchmark
+
+| Operation                     | hz    |
+| ----------------------------- | ----- |
+| `decimalNumber`               | ~21M  |
+| `hexColorValue` (6-char hex)  | ~13M  |
+| `uniqueNumericIdCreator`      | ~21M  |
+| `uniqueId` (nanoid)           | ~3.3M |
+| `uniqueUuid`                  | ~2M   |
+| `OnOffElement (true)`         | ~13M  |
+| `OnOffElement (false)`        | ~1.7M |
+| `BuilderElement` (attributes) | ~2M   |
+| `BuilderElement` (children)   | ~2.3M |
+
+## License
+
+- [MIT](LICENSE) © [Demo Macro](https://imst.xyz/)

package/dist/_chunks/id-generators-Ch07cHW1.mjs

@@ -0,0 +1,72 @@
+import hash from "hash.js";
+import { customAlphabet, nanoid } from "nanoid/non-secure";
+//#region src/converters.ts
+/**
+* OOXML unit conversion utilities.
+*
+* @module
+*/
+/**
+* Converts millimeters to TWIP (twentieths of a point).
+*/
+const convertMillimetersToTwip = (millimeters) => Math.floor(millimeters / 25.4 * 72 * 20);
+/**
+* Converts inches to TWIP (twentieths of a point).
+*/
+const convertInchesToTwip = (inches) => Math.floor(inches * 72 * 20);
+/**
+* Converts pixels to EMU (96 DPI).
+*/
+const convertPixelsToEmu = (pixels) => Math.round(pixels * 9525);
+/**
+* Converts EMU to pixels (96 DPI).
+*/
+const convertEmuToPixels = (emus) => Math.round(emus / 9525);
+/**
+* Converts inches to EMU.
+*/
+const convertInchesToEmu = (inches) => Math.round(inches * 914400);
+/**
+* Converts EMU to inches.
+*/
+const convertEmuToInches = (emus) => emus / 914400;
+/**
+* Converts points to EMU.
+*/
+const convertPointsToEmu = (points) => Math.round(points * 12700);
+/**
+* Converts EMU to points.
+*/
+const convertEmuToPoints = (emus) => emus / 12700;
+//#endregion
+//#region src/id-generators.ts
+/**
+* Unique ID generation utilities.
+*
+* @module
+*/
+/**
+* Creates a unique numeric ID generator with sequential numbering.
+*/
+const uniqueNumericIdCreator = (initial = 0) => {
+	let currentCount = initial;
+	return () => ++currentCount;
+};
+/**
+* Generates a unique lowercase alphanumeric ID using nanoid.
+*/
+const uniqueId = () => nanoid().toLowerCase();
+/**
+* Generates a SHA-1 hash of the provided data.
+*/
+const hashedId = (data) => hash.sha1().update(data instanceof ArrayBuffer ? new Uint8Array(data) : data).digest("hex");
+/**
+* Generates a random hexadecimal string of specified length.
+*/
+const generateUuidPart = (count) => customAlphabet("1234567890abcdef", count)();
+/**
+* Generates a UUID v4-style unique identifier.
+*/
+const uniqueUuid = () => `${generateUuidPart(8)}-${generateUuidPart(4)}-${generateUuidPart(4)}-${generateUuidPart(4)}-${generateUuidPart(12)}`;
+//#endregion
+export { convertEmuToInches as a, convertInchesToEmu as c, convertPixelsToEmu as d, convertPointsToEmu as f, uniqueUuid as i, convertInchesToTwip as l, uniqueId as n, convertEmuToPixels as o, uniqueNumericIdCreator as r, convertEmuToPoints as s, hashedId as t, convertMillimetersToTwip as u };

package/dist/_chunks/index-3uVYzs32.d.mts

@@ -0,0 +1,241 @@
+import { r as PositiveUniversalMeasure } from "./values-BrGywpRh.mjs";
+import { Element } from "@office-open/xml";
+
+//#region src/xml-components/types.d.ts
+/**
+ * XML-serializable object types for OOXML document generation.
+ *
+ * @module
+ */
+/**
+ * Attributes for an XML element.
+ */
+type IXmlAttribute = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Object that can be serialized to XML.
+ */
+type IXmlableObject = Readonly<Record<string, any>>;
+//#endregion
+//#region src/xml-components/base.d.ts
+/**
+ * Context object passed through the XML tree during serialization.
+ *
+ * @typeParam TFileData - The type of the root file data object (format-specific)
+ */
+interface IContext<TFileData = unknown> {
+  /** The root file data object being serialized (format-specific). */
+  readonly fileData?: TFileData;
+  /** Current traversal stack of components (mutable for performance). */
+  readonly stack: IXmlableObject[];
+}
+/**
+ * Abstract base class for all XML components.
+ */
+declare abstract class BaseXmlComponent {
+  /** The XML element name for this component (e.g., "w:p" for paragraph). */
+  protected readonly rootKey: string;
+  constructor(rootKey: string);
+  /**
+   * Prepares this component for XML serialization.
+   *
+   * @param context - The serialization context
+   * @returns The XML-serializable object, or undefined to exclude from output
+   */
+  abstract prepForXml(context: IContext): IXmlableObject | undefined;
+}
+//#endregion
+//#region src/xml-components/component.d.ts
+/**
+ * Empty object singleton used for empty XML elements.
+ *
+ * @internal
+ */
+declare const EMPTY_OBJECT: {};
+/**
+ * Base class for all XML components in OOXML documents.
+ */
+declare abstract class XmlComponent extends BaseXmlComponent {
+  /**
+   * Array of child components, text nodes, and attributes.
+   */
+  root: (BaseXmlComponent | IXmlableObject | string)[];
+  constructor(rootKey: string);
+  /**
+   * Prepares this component and its children for XML serialization.
+   */
+  prepForXml(context: IContext): IXmlableObject | undefined;
+  /**
+   * @deprecated Internal use only.
+   */
+  addChildElement(child: BaseXmlComponent | string): XmlComponent;
+}
+/**
+ * XML component that is excluded from output if it has no meaningful content.
+ */
+declare abstract class IgnoreIfEmptyXmlComponent extends XmlComponent {
+  private readonly includeIfEmpty;
+  constructor(rootKey: string, includeIfEmpty?: boolean);
+  prepForXml(context: IContext): IXmlableObject | undefined;
+}
+//#endregion
+//#region src/xml-components/attributes.d.ts
+/**
+ * Maps TypeScript property names to their XML attribute names.
+ */
+type AttributeMap<T> = Record<keyof T, string>;
+/**
+ * Simple attribute data as a key-value record.
+ */
+type AttributeData = Record<string, boolean | number | string>;
+/**
+ * Structured attribute payload with explicit key-value mapping.
+ */
+type AttributePayload<T> = { readonly [P in keyof T]: {
+  readonly key: string;
+  readonly value: T[P];
+} };
+/**
+ * Base class for creating XML attributes with automatic name mapping.
+ */
+declare abstract class XmlAttributeComponent<T extends Record<string, any>> extends BaseXmlComponent {
+  private readonly root;
+  /** Optional mapping from property names to XML attribute names. */
+  protected readonly xmlKeys?: AttributeMap<T>;
+  constructor(root: T);
+  prepForXml(_: IContext): IXmlableObject;
+}
+/**
+ * Next-generation attribute component with explicit key-value pairs.
+ */
+declare class NextAttributeComponent<T> extends BaseXmlComponent {
+  private readonly root;
+  constructor(root: AttributePayload<T>);
+  prepForXml(_: IContext): IXmlableObject;
+}
+//#endregion
+//#region src/xml-components/elements.d.ts
+/**
+ * Build a CT_OnOff XML object without allocating any XmlComponent.
+ * `val=true` returns a frozen singleton (cached per name).
+ */
+declare function onOffObj(name: string, val?: boolean | undefined): IXmlableObject;
+/**
+ * Build a CT_HpsMeasure XML object (half-point size) without allocation.
+ */
+declare function hpsMeasureObj(name: string, val: number | PositiveUniversalMeasure): IXmlableObject;
+/**
+ * Build a CT_String XML object (string value attribute) without allocation.
+ */
+declare function stringValObj(name: string, val: string): IXmlableObject;
+/**
+ * Build a numeric value attribute XML object without allocation.
+ */
+declare function numberValObj(name: string, val: number): IXmlableObject;
+/**
+ * Build a string enum value attribute XML object without allocation.
+ */
+declare function stringEnumValObj<T extends string>(name: string, val: T): IXmlableObject;
+/**
+ * Build an element wrapping a text string without allocation.
+ */
+declare function stringContainerObj(name: string, val: string): IXmlableObject;
+/**
+ * XML element representing a boolean on/off value (CT_OnOff).
+ * @deprecated Use `onOffObj()` for hot-path code.
+ */
+declare class OnOffElement extends XmlComponent {
+  constructor(name: string, val?: boolean | undefined);
+}
+/**
+ * XML element representing a half-point size measurement (CT_HpsMeasure).
+ * @deprecated Use `hpsMeasureObj()` for hot-path code.
+ */
+declare class HpsMeasureElement extends XmlComponent {
+  constructor(name: string, val: number | PositiveUniversalMeasure);
+}
+/**
+ * XML element representing an empty element (CT_Empty).
+ */
+declare class EmptyElement extends XmlComponent {}
+/**
+ * XML element with a string value attribute (CT_String).
+ * @deprecated Use `stringValObj()` for hot-path code.
+ */
+declare class StringValueElement extends XmlComponent {
+  constructor(name: string, val: string);
+}
+/**
+ * XML element with a numeric value attribute.
+ * @deprecated Use `numberValObj()` for hot-path code.
+ */
+declare class NumberValueElement extends XmlComponent {
+  constructor(name: string, val: number);
+}
+/**
+ * XML element with a string enum value attribute.
+ * @deprecated Use `stringEnumValObj()` for hot-path code.
+ */
+declare class StringEnumValueElement<T extends string> extends XmlComponent {
+  constructor(name: string, val: T);
+}
+/**
+ * XML element containing text content.
+ * @deprecated Use `stringContainerObj()` for hot-path code.
+ */
+declare class StringContainer extends XmlComponent {
+  constructor(name: string, val: string);
+}
+/**
+ * Flexible XML element builder with explicit attribute and child configuration.
+ */
+declare class BuilderElement<T = {}> extends XmlComponent {
+  constructor({
+    name,
+    attributes,
+    children
+  }: {
+    readonly name: string;
+    readonly attributes?: AttributePayload<T>;
+    readonly children?: readonly (BaseXmlComponent | string)[];
+  });
+}
+/**
+ * Creates a NextAttributeComponent with explicit XML attribute keys.
+ */
+declare const chartAttr: (attrs: Record<string, string | number | boolean>) => BaseXmlComponent;
+/**
+ * Wraps a component in a named XmlComponent element.
+ */
+declare function wrapEl(elementName: string, child: BaseXmlComponent): XmlComponent;
+//#endregion
+//#region src/xml-components/imported.d.ts
+/**
+ * Converts an xml-js Element into an XmlComponent tree.
+ */
+declare const convertToXmlComponent: (element: Element) => ImportedXmlComponent | string | undefined;
+/**
+ * XML component representing imported XML content.
+ */
+declare class ImportedXmlComponent extends XmlComponent {
+  static fromXmlString(importedContent: string): ImportedXmlComponent;
+  constructor(rootKey: string, _attr?: any);
+  push(xmlComponent: XmlComponent | string): void;
+}
+/**
+ * Represents attributes for imported root elements.
+ */
+declare class ImportedRootElementAttributes extends XmlComponent {
+  private readonly _attr;
+  constructor(_attr: any);
+  prepForXml(_: IContext): IXmlableObject;
+}
+//#endregion
+//#region src/xml-components/initializable.d.ts
+/**
+ * XML component that can be initialized from another component.
+ */
+declare abstract class InitializableXmlComponent extends XmlComponent {
+  constructor(rootKey: string, initComponent?: XmlComponent);
+}
+//#endregion
+export { IContext as A, AttributePayload as C, IgnoreIfEmptyXmlComponent as D, EMPTY_OBJECT as E, IXmlableObject as M, XmlComponent as O, AttributeMap as S, XmlAttributeComponent as T, stringContainerObj as _, BuilderElement as a, wrapEl as b, NumberValueElement as c, StringEnumValueElement as d, StringValueElement as f, onOffObj as g, numberValObj as h, convertToXmlComponent as i, IXmlAttribute as j, BaseXmlComponent as k, OnOffElement as l, hpsMeasureObj as m, ImportedRootElementAttributes as n, EmptyElement as o, chartAttr as p, ImportedXmlComponent as r, HpsMeasureElement as s, InitializableXmlComponent as t, StringContainer as u, stringEnumValObj as v, NextAttributeComponent as w, AttributeData as x, stringValObj as y };