@bendyline/squisq-formats 2.1.0 → 2.2.0

package/src/ooxml/themeReader.ts

@@ -1,197 +0,0 @@
-/**
- * OOXML theme reader — parses a `theme1.xml` part (DrawingML `a:theme`)
- * into normalized color and font schemes.
- *
- * Shared by DOCX/PPTX/XLSX theme inference: all three formats carry the same
- * theme part shape, differing only in where the part hangs (document/master/
- * workbook relationships). This module never fails hard — unreadable slots
- * degrade to fallbacks or absence, with a warning per degradation.
- */
-
-import type { OoxmlPackage } from './types.js';
-import { getPartRelationships, getPartXml } from './reader.js';
-import { NS_DRAWINGML, REL_THEME } from './namespaces.js';
-import { baseDirOf, findRelByType, resolveTarget } from './readUtils.js';
-
-/**
- * The clrScheme slots as normalized `#rrggbb` strings. The four surface/text
- * slots always resolve (falling back to black/white when degraded); accent and
- * hyperlink slots are omitted when unresolvable.
- */
-export interface OoxmlColorScheme {
-  dk1: string;
-  lt1: string;
-  dk2: string;
-  lt2: string;
-  accent1?: string;
-  accent2?: string;
-  accent3?: string;
-  accent4?: string;
-  accent5?: string;
-  accent6?: string;
-  hlink?: string;
-  folHlink?: string;
-}
-
-export interface OoxmlFontScheme {
-  /** `a:fontScheme > a:majorFont > a:latin@typeface` (headings). */
-  majorLatin?: string;
-  /** `a:fontScheme > a:minorFont > a:latin@typeface` (body). */
-  minorLatin?: string;
-}
-
-export interface OoxmlTheme {
-  /** `a:theme@name` (e.g. "Office Theme", "Ion"). */
-  name?: string;
-  /** Absent when the theme carries no parseable `a:clrScheme`. */
-  colors?: OoxmlColorScheme;
-  /** Absent when the theme carries no `a:fontScheme` latin typefaces. */
-  fonts?: OoxmlFontScheme;
-  warnings: string[];
-}
-
-const HEX6_RE = /^[0-9a-fA-F]{6}$/;
-
-/** Well-known sysClr values that resolve without a `lastClr` hint. */
-const SYS_COLOR_DEFAULTS: Record<string, string> = {
-  windowText: '000000',
-  window: 'ffffff',
-};
-
-/**
- * Resolve one clrScheme slot element to a `#rrggbb` string, or null.
- * Only the base color matters for theming — trailing transform children
- * (`a:lumMod`, `a:tint`, …) are ignored.
- */
-function resolveSchemeColor(slot: Element): string | null {
-  for (let i = 0; i < slot.childNodes.length; i++) {
-    const child = slot.childNodes[i];
-    if (!child || child.nodeType !== 1) continue;
-    const el = child as Element;
-    if (el.localName === 'srgbClr') {
-      const val = el.getAttribute('val');
-      return val && HEX6_RE.test(val) ? `#${val.toLowerCase()}` : null;
-    }
-    if (el.localName === 'sysClr') {
-      const lastClr = el.getAttribute('lastClr');
-      if (lastClr && HEX6_RE.test(lastClr)) return `#${lastClr.toLowerCase()}`;
-      const val = el.getAttribute('val');
-      const known = val ? SYS_COLOR_DEFAULTS[val] : undefined;
-      return known ? `#${known}` : null;
-    }
-    // Any other color form (schemeClr self-reference, prstClr, …) is
-    // unresolvable without a full DrawingML color pipeline.
-    return null;
-  }
-  return null;
-}
-
-function firstNS(parent: Element | Document, local: string): Element | null {
-  const els = parent.getElementsByTagNameNS(NS_DRAWINGML, local);
-  return els.length > 0 ? els[0]! : null;
-}
-
-function parseColorScheme(clrScheme: Element, warnings: string[]): OoxmlColorScheme {
-  const resolve = (slotName: string): string | null => {
-    const slot = firstNS(clrScheme, slotName);
-    if (!slot) return null;
-    return resolveSchemeColor(slot);
-  };
-
-  const dk1 = resolve('dk1');
-  const lt1 = resolve('lt1');
-  if (!dk1) warnings.push('theme: dk1 color could not be resolved; using #000000');
-  if (!lt1) warnings.push('theme: lt1 color could not be resolved; using #ffffff');
-
-  const dk2 = resolve('dk2');
-  const lt2 = resolve('lt2');
-
-  const colors: OoxmlColorScheme = {
-    dk1: dk1 ?? '#000000',
-    lt1: lt1 ?? '#ffffff',
-    dk2: dk2 ?? dk1 ?? '#000000',
-    lt2: lt2 ?? lt1 ?? '#ffffff',
-  };
-
-  for (const slot of ['accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6'] as const) {
-    const hex = resolve(slot);
-    if (hex) colors[slot] = hex;
-    else warnings.push(`theme: ${slot} color could not be resolved; dropped`);
-  }
-  for (const slot of ['hlink', 'folHlink'] as const) {
-    const hex = resolve(slot);
-    if (hex) colors[slot] = hex;
-  }
-  return colors;
-}
-
-function parseFontScheme(fontScheme: Element, warnings: string[]): OoxmlFontScheme | undefined {
-  const readLatin = (fontName: 'majorFont' | 'minorFont'): string | undefined => {
-    const font = firstNS(fontScheme, fontName);
-    if (!font) return undefined;
-    const latin = firstNS(font, 'latin');
-    const typeface = latin?.getAttribute('typeface')?.trim();
-    if (!typeface) {
-      warnings.push(`theme: ${fontName} has no latin typeface`);
-      return undefined;
-    }
-    return typeface;
-  };
-
-  const majorLatin = readLatin('majorFont');
-  const minorLatin = readLatin('minorFont');
-  if (!majorLatin && !minorLatin) return undefined;
-  return {
-    ...(majorLatin ? { majorLatin } : {}),
-    ...(minorLatin ? { minorLatin } : {}),
-  };
-}
-
-/** Parse an already-loaded theme part Document. */
-export function parseThemeXml(themeDoc: Document): OoxmlTheme {
-  const warnings: string[] = [];
-
-  const root = firstNS(themeDoc, 'theme');
-  const name = root?.getAttribute('name')?.trim() || undefined;
-
-  const clrScheme = firstNS(themeDoc, 'clrScheme');
-  let colors: OoxmlColorScheme | undefined;
-  if (clrScheme) {
-    colors = parseColorScheme(clrScheme, warnings);
-  } else {
-    warnings.push('theme: no clrScheme found');
-  }
-
-  const fontScheme = firstNS(themeDoc, 'fontScheme');
-  let fonts: OoxmlFontScheme | undefined;
-  if (fontScheme) {
-    fonts = parseFontScheme(fontScheme, warnings);
-  } else {
-    warnings.push('theme: no fontScheme found');
-  }
-
-  return {
-    ...(name ? { name } : {}),
-    ...(colors ? { colors } : {}),
-    ...(fonts ? { fonts } : {}),
-    warnings,
-  };
-}
-
-/**
- * Resolve the theme part related from `fromPartPath` (via `REL_THEME`) and
- * parse it. Returns null when the part has no theme relationship or the
- * target part is missing — callers decide whether that's an error.
- */
-export async function readThemePart(
-  pkg: OoxmlPackage,
-  fromPartPath: string,
-): Promise<OoxmlTheme | null> {
-  const rels = await getPartRelationships(pkg, fromPartPath);
-  const rel = findRelByType(rels, REL_THEME);
-  if (!rel) return null;
-  const themePath = resolveTarget(baseDirOf(fromPartPath), rel.target);
-  const doc = await getPartXml(pkg, themePath);
-  if (!doc) return null;
-  return parseThemeXml(doc);
-}

package/src/ooxml/types.ts

@@ -1,103 +0,0 @@
-/**
- * OOXML Types
- *
- * Shared type definitions for all Office Open XML formats (DOCX, PPTX, XLSX).
- * These model the common structural elements of the OOXML package format:
- * relationships, content types, and core properties.
- */
-
-// ============================================
-// Package
-// ============================================
-
-/**
- * An opened OOXML package. Instances are created only by `openPackage`; the
- * archive remains private so every part read goes through the bounded reader.
- */
-declare const ooxmlPackageBrand: unique symbol;
-export interface OoxmlPackage {
-  /** Nominal brand: callers cannot manually construct a safety-bypassing package. */
-  readonly [ooxmlPackageBrand]: never;
-  /** Parsed [Content_Types].xml entries */
-  readonly contentTypes: ContentTypeMap;
-  /** Root-level relationships (_rels/.rels) */
-  readonly rootRelationships: readonly Relationship[];
-}
-
-/**
- * Content type map built from [Content_Types].xml.
- * Maps part paths → content type strings plus extension defaults.
- */
-export interface ContentTypeMap {
-  /** Explicit overrides: partName → contentType */
-  overrides: Map<string, string>;
-  /** Default extensions: extension → contentType */
-  defaults: Map<string, string>;
-}
-
-// ============================================
-// Relationships
-// ============================================
-
-/**
- * An OOXML relationship entry (from any _rels/*.rels file).
- */
-export interface Relationship {
-  /** Relationship ID (e.g., "rId1") */
-  id: string;
-  /** Relationship type URI (e.g., "http://...officedocument/...") */
-  type: string;
-  /** Target path or URL */
-  target: string;
-  /** "Internal" (default) or "External" for hyperlinks */
-  targetMode?: 'Internal' | 'External';
-}
-
-// ============================================
-// Core Properties
-// ============================================
-
-/**
- * Document core properties from docProps/core.xml (Dublin Core metadata).
- */
-export interface CoreProperties {
-  title?: string;
-  subject?: string;
-  creator?: string;
-  keywords?: string;
-  description?: string;
-  lastModifiedBy?: string;
-  revision?: string;
-  created?: string;
-  modified?: string;
-}
-
-// ============================================
-// Package Builder
-// ============================================
-
-/**
- * A part (file) that will be written into an OOXML package.
- */
-export interface PackagePart {
-  /** Path within the ZIP (e.g., "word/document.xml") */
-  path: string;
-  /** XML or text content (mutually exclusive with binaryContent) */
-  content?: string;
-  /** Binary content (mutually exclusive with content) */
-  binaryContent?: ArrayBuffer | Uint8Array;
-  /** MIME content type for [Content_Types].xml */
-  contentType: string;
-}
-
-/**
- * A relationship to be written into a _rels/*.rels file.
- * `sourcePart` identifies which part the relationship belongs to.
- * Use "" (empty string) for root-level relationships (_rels/.rels).
- */
-export interface PendingRelationship {
-  /** The part this relationship belongs to ("" for root) */
-  sourcePart: string;
-  /** The relationship entry */
-  relationship: Relationship;
-}

package/src/ooxml/writer.ts

@@ -1,339 +0,0 @@
-/**
- * OOXML Package Writer
- *
- * Builds OOXML archives (.docx, .pptx, .xlsx) from parts.
- * Handles automatic generation of [Content_Types].xml and
- * _rels/*.rels files from the registered parts and relationships.
- */
-
-import JSZip from 'jszip';
-import type { CoreProperties, PackagePart, PendingRelationship, Relationship } from './types.js';
-import {
-  NS_CONTENT_TYPES,
-  NS_RELATIONSHIPS,
-  NS_CORE_PROPERTIES,
-  NS_DC,
-  NS_DCTERMS,
-  NS_XSI,
-  CONTENT_TYPE_RELATIONSHIPS,
-  CONTENT_TYPE_CORE_PROPERTIES,
-  REL_CORE_PROPERTIES,
-} from './namespaces.js';
-import { xmlDeclaration, escapeXml } from './xmlUtils.js';
-import { assertSafeZipPath } from '../shared/zipSafety.js';
-
-// ============================================
-// Package Builder
-// ============================================
-
-/**
- * Mutable builder for constructing an OOXML package.
- *
- * Add parts, relationships, and core properties, then call `toBlob()`
- * or `toArrayBuffer()` to produce the final ZIP archive.
- *
- * @example
- * ```ts
- * const builder = createPackage();
- * builder.addPart('word/document.xml', documentXml, CONTENT_TYPE_DOCX_DOCUMENT);
- * builder.addRelationship('', {
- *   id: 'rId1',
- *   type: REL_OFFICE_DOCUMENT,
- *   target: 'word/document.xml',
- * });
- * const blob = await builder.toBlob();
- * ```
- */
-export interface OoxmlPackageBuilder {
-  /**
-   * Add an XML or text part to the package.
-   *
-   * @param path - Path within the archive (e.g., "word/document.xml")
-   * @param content - XML string content
-   * @param contentType - MIME content type for [Content_Types].xml
-   */
-  addPart(path: string, content: string, contentType: string): void;
-
-  /**
-   * Add a binary part to the package (e.g., an image).
-   *
-   * @param path - Path within the archive (e.g., "word/media/image1.png")
-   * @param data - Binary content
-   * @param contentType - MIME content type (e.g., "image/png")
-   */
-  addBinaryPart(path: string, data: ArrayBuffer | Uint8Array, contentType: string): void;
-
-  /**
-   * Register a relationship.
-   *
-   * @param sourcePart - The part this relationship belongs to (e.g., "word/document.xml").
-   *   Use "" (empty string) for root-level relationships (_rels/.rels).
-   * @param rel - The relationship entry
-   */
-  addRelationship(sourcePart: string, rel: Relationship): void;
-
-  /**
-   * Set core document properties (docProps/core.xml).
-   * Calling this multiple times overwrites previous values.
-   */
-  setCoreProperties(props: CoreProperties): void;
-
-  /**
-   * Assemble the final OOXML package as a Blob.
-   * Generates [Content_Types].xml and all _rels/*.rels files automatically.
-   */
-  toBlob(): Promise<Blob>;
-
-  /**
-   * Assemble the final OOXML package as an ArrayBuffer.
-   */
-  toArrayBuffer(): Promise<ArrayBuffer>;
-}
-
-/**
- * Create a new OOXML package builder.
- */
-export function createPackage(): OoxmlPackageBuilder {
-  const parts: PackagePart[] = [];
-  const relationships: PendingRelationship[] = [];
-  let coreProps: CoreProperties | undefined;
-
-  return {
-    addPart(path, content, contentType) {
-      assertSafeZipPath(path);
-      parts.push({ path, content, contentType });
-    },
-
-    addBinaryPart(path, data, contentType) {
-      assertSafeZipPath(path);
-      parts.push({ path, binaryContent: data, contentType });
-    },
-
-    addRelationship(sourcePart, rel) {
-      if (sourcePart) assertSafeZipPath(sourcePart);
-      relationships.push({ sourcePart, relationship: rel });
-    },
-
-    setCoreProperties(props) {
-      coreProps = props;
-    },
-
-    async toBlob() {
-      const zip = assemble(parts, relationships, coreProps);
-      return zip.generateAsync({ type: 'blob' });
-    },
-
-    async toArrayBuffer() {
-      const zip = assemble(parts, relationships, coreProps);
-      return zip.generateAsync({ type: 'arraybuffer' });
-    },
-  };
-}
-
-// ============================================
-// Assembly
-// ============================================
-
-/**
- * Assemble a JSZip archive from parts, relationships, and core properties.
- */
-function assemble(
-  parts: PackagePart[],
-  relationships: PendingRelationship[],
-  coreProps?: CoreProperties,
-): JSZip {
-  const zip = new JSZip();
-  // Assembly must be idempotent: callers may request both Blob and
-  // ArrayBuffer representations from one builder. Never append generated
-  // relationships to the builder-owned array.
-  const assembledRelationships = relationships.slice();
-
-  // Write content parts
-  for (const part of parts) {
-    if (part.content !== undefined) {
-      zip.file(part.path, part.content);
-    } else if (part.binaryContent !== undefined) {
-      zip.file(part.path, part.binaryContent);
-    }
-  }
-
-  // Add core properties if set
-  if (coreProps) {
-    const coreXml = buildCorePropertiesXml(coreProps);
-    zip.file('docProps/core.xml', coreXml);
-
-    // Add the generated relationship unless the caller already supplied it.
-    if (
-      !assembledRelationships.some(
-        ({ sourcePart, relationship }) =>
-          sourcePart === '' && relationship.type === REL_CORE_PROPERTIES,
-      )
-    ) {
-      const ids = new Set(assembledRelationships.map(({ relationship }) => relationship.id));
-      let nextId = 100;
-      while (ids.has(`rId${nextId}`)) nextId++;
-      assembledRelationships.push({
-        sourcePart: '',
-        relationship: {
-          id: `rId${nextId}`,
-          type: REL_CORE_PROPERTIES,
-          target: 'docProps/core.xml',
-        },
-      });
-    }
-  }
-
-  // Build and write [Content_Types].xml
-  zip.file('[Content_Types].xml', buildContentTypesXml(parts, coreProps));
-
-  // Build and write _rels/*.rels files
-  const relsBySource = groupRelationshipsBySource(assembledRelationships);
-  for (const [sourcePart, rels] of relsBySource) {
-    const relsPath = sourcePart === '' ? '_rels/.rels' : buildRelsPath(sourcePart);
-    zip.file(relsPath, buildRelationshipsXml(rels));
-  }
-
-  return zip;
-}
-
-// ============================================
-// [Content_Types].xml
-// ============================================
-
-function buildContentTypesXml(parts: PackagePart[], coreProps?: CoreProperties): string {
-  const lines: string[] = [xmlDeclaration()];
-  lines.push(`<Types xmlns="${NS_CONTENT_TYPES}">`);
-
-  // Default extension types
-  const extensionTypes = new Map<string, string>();
-  extensionTypes.set('rels', CONTENT_TYPE_RELATIONSHIPS);
-  extensionTypes.set('xml', 'application/xml');
-
-  // Collect extensions from binary parts (e.g., png, jpeg)
-  for (const part of parts) {
-    if (part.binaryContent !== undefined) {
-      const ext = getExtension(part.path);
-      if (ext && !extensionTypes.has(ext)) {
-        extensionTypes.set(ext, part.contentType);
-      }
-    }
-  }
-
-  for (const [ext, ct] of extensionTypes) {
-    lines.push(`  <Default Extension="${escapeXml(ext)}" ContentType="${escapeXml(ct)}"/>`);
-  }
-
-  // Override entries for each XML part
-  for (const part of parts) {
-    if (part.content !== undefined) {
-      lines.push(
-        `  <Override PartName="/${escapeXml(part.path)}" ContentType="${escapeXml(part.contentType)}"/>`,
-      );
-    }
-  }
-
-  // Core properties override
-  if (coreProps) {
-    lines.push(
-      `  <Override PartName="/docProps/core.xml" ContentType="${CONTENT_TYPE_CORE_PROPERTIES}"/>`,
-    );
-  }
-
-  lines.push('</Types>');
-  return lines.join('\n');
-}
-
-// ============================================
-// Relationships XML
-// ============================================
-
-function buildRelationshipsXml(rels: Relationship[]): string {
-  const lines: string[] = [xmlDeclaration()];
-  lines.push(`<Relationships xmlns="${NS_RELATIONSHIPS}">`);
-
-  for (const rel of rels) {
-    const attrs: string[] = [
-      `Id="${escapeXml(rel.id)}"`,
-      `Type="${escapeXml(rel.type)}"`,
-      `Target="${escapeXml(rel.target)}"`,
-    ];
-    if (rel.targetMode) {
-      attrs.push(`TargetMode="${escapeXml(rel.targetMode)}"`);
-    }
-    lines.push(`  <Relationship ${attrs.join(' ')}/>`);
-  }
-
-  lines.push('</Relationships>');
-  return lines.join('\n');
-}
-
-// ============================================
-// Core Properties XML
-// ============================================
-
-function buildCorePropertiesXml(props: CoreProperties): string {
-  const lines: string[] = [xmlDeclaration()];
-  lines.push(
-    `<cp:coreProperties` +
-      ` xmlns:cp="${NS_CORE_PROPERTIES}"` +
-      ` xmlns:dc="${NS_DC}"` +
-      ` xmlns:dcterms="${NS_DCTERMS}"` +
-      ` xmlns:xsi="${NS_XSI}">`,
-  );
-
-  if (props.title) lines.push(`  <dc:title>${escapeXml(props.title)}</dc:title>`);
-  if (props.subject) lines.push(`  <dc:subject>${escapeXml(props.subject)}</dc:subject>`);
-  if (props.creator) lines.push(`  <dc:creator>${escapeXml(props.creator)}</dc:creator>`);
-  if (props.description)
-    lines.push(`  <dc:description>${escapeXml(props.description)}</dc:description>`);
-  if (props.keywords) lines.push(`  <cp:keywords>${escapeXml(props.keywords)}</cp:keywords>`);
-  if (props.lastModifiedBy)
-    lines.push(`  <cp:lastModifiedBy>${escapeXml(props.lastModifiedBy)}</cp:lastModifiedBy>`);
-  if (props.revision) lines.push(`  <cp:revision>${escapeXml(props.revision)}</cp:revision>`);
-  if (props.created) {
-    lines.push(
-      `  <dcterms:created xsi:type="dcterms:W3CDTF">${escapeXml(props.created)}</dcterms:created>`,
-    );
-  }
-  if (props.modified) {
-    lines.push(
-      `  <dcterms:modified xsi:type="dcterms:W3CDTF">${escapeXml(props.modified)}</dcterms:modified>`,
-    );
-  }
-
-  lines.push('</cp:coreProperties>');
-  return lines.join('\n');
-}
-
-// ============================================
-// Helpers
-// ============================================
-
-function getExtension(path: string): string | undefined {
-  const dot = path.lastIndexOf('.');
-  if (dot === -1) return undefined;
-  return path.substring(dot + 1).toLowerCase();
-}
-
-function buildRelsPath(partPath: string): string {
-  const lastSlash = partPath.lastIndexOf('/');
-  if (lastSlash === -1) {
-    return `_rels/${partPath}.rels`;
-  }
-  const dir = partPath.substring(0, lastSlash);
-  const file = partPath.substring(lastSlash + 1);
-  return `${dir}/_rels/${file}.rels`;
-}
-
-function groupRelationshipsBySource(pending: PendingRelationship[]): Map<string, Relationship[]> {
-  const grouped = new Map<string, Relationship[]>();
-  for (const { sourcePart, relationship } of pending) {
-    let list = grouped.get(sourcePart);
-    if (!list) {
-      list = [];
-      grouped.set(sourcePart, list);
-    }
-    list.push(relationship);
-  }
-  return grouped;
-}