office-open CLAUDE.md

You are a senior TypeScript developer.

Project

office-open is a monorepo for generating and parsing Office Open XML documents (.docx, .pptx, .xlsx) with JS/TS. Declarative API, works in Node.js and browsers. Bidirectional: stringify (JSON → XML) and parse (XML → JSON).

Architecture

• Packages: core/ (shared OOXML domains — descriptor runtime, drawing/, chart/, table/, picture/, connector/, group/, smartart, OPC), xml/, docx/, pptx/, xlsx/. The three format packages are peers: same src/ layout (parts/, shared/, compiler.ts, context.ts, generate.ts, parse.ts, patch.ts, index.ts) and one **Options name per shared concept.
• Parts: one module per OOXML XML part. docx/xlsx co-locate types and the <part>Desc descriptor; pptx keeps descriptors in parts/descriptors/ with public types in shared/<domain>/. Cross-part shared types live in shared/.
• Descriptor pattern: every part is a CustomDescriptor<T> with hand-written stringify(opts, ctx) + parse(el, ctx) (bidirectional). Runtime at packages/core/src/descriptor/.
• Cross-format copy reuses core's shared domains + package-to-package conversion in packages/office-open/src/convert/ — no unified document-model layer. The conversion mode follows how the concept's XML maps across packages:
  • Identical XML (chart: one c:chartSpace part) → shared core model, no conversion.
  • Same element, different anchoring (picture pic:pic/p:pic/xdr:pic; shapes; text) → each package owns an *Options reflecting its anchor model (docx wp:inline/wp:anchor, pptx spTree, xlsx cell anchor) + pairwise convert/* functions; N is small, so pairwise beats a hub-spoke intermediate. The shared payload still lands in core: core/picture/ BasePictureOptions (data/type + cNvPr via NonVisualDrawingPropertiesOptions) is extended by pptx/xlsx PictureOptions, while docx stays a format discriminated union bridged through its altText; convert/picture.ts threads the cNvPr fields (name/description/title/hidden) straight through every leg. The same NonVisualDrawingPropertiesOptions (a:CT_NonVisualDrawingProps) backs every drawing's cNvPr/docPr across all three packages via core/drawing/non-visual/.
  • Structurally different XML (table: w:tbl flow / a:tbl graphic / sml cell-range) → core/table/ defines the shared structural base (BaseTableOptions/BaseTableRowOptions/BaseTableCellOptions: rows/cells/span/6-flags/columnWidths/vertical-align); docx/pptx TableOptions extends Base* add domain-specific style/position, xlsx is independent (its sml Table is a data range, restored visually via convert/table.ts). convert/table.ts passes the structural base through directly and translates only cell content (w:p↔a:p via convert/text), units (twip↔EMU via core/util/converters), and pptx fill/scheme-color → docx shading/themeColor.
  • Connector (cxnSp: p:cxnSp/xdr:cxnSp; docx has no standalone cxnSp) → core/connector/ BaseConnectorOptions extends NonVisualDrawingPropertiesOptions (cNvPr + locking + start/end connection endpoints; no spPr — pptx top-level convenience vs xlsx spPr asymmetry, kept per-package). pptx ConnectorOptions/LineShapeOptions and xlsx ConnectorOptions extend base; convert/connector.ts threads cNvPr + locking + endpoints via pickConnectorBase.
  • Group (grpSp: p:grpSp/xdr:grpSp/wpg:wgp) → core/drawing/group-shape-properties-desc.ts GroupShapePropertiesOptions (CT_GroupShapeProperties: xfrm/fill/effects/scene3d — no geometry/ln/sp3d, distinct from CT_ShapeProperties) + core/group/ BaseGroupOptions extends NonVisualDrawingPropertiesOptions (cNvPr only; grpSpPr content/children/position stay per-package). pptx/xlsx/docx all use GroupOptions (docx bridged through altText like picture). convert/group.ts threads container + child cNvPr via pickGroupBase/pickNonVisualDrawingProperties.
  • Shape base is YAGNI: cNvPr is already unified via NonVisualDrawingPropertiesOptions (Phase 2), spPr/textBody already live in core, there are no scattered convert adapters and no shape-specific public field worth lifting — so no BaseShapeOptions is introduced.
• OOXML XSD (ooxml-schemas/transitional/) is the golden source of truth — wml.xsd (DOCX), pml.xsd (PPTX), sml.xsd (XLSX), dml-main.xsd (DrawingML). Validate XML output against it.