@bendyline/squisq-formats 2.1.0 → 2.2.0

package/src/infer/index.ts

@@ -1,199 +0,0 @@
-/**
- * @bendyline/squisq-formats Infer Module
- *
- * "Infer theme and layouts from a file import": read the OOXML theme
- * (colors + fonts) out of a DOCX/PPTX/XLSX file and compile it into a
- * Squisq `Theme`; for PPTX, optionally derive custom layout templates
- * from the deck's slide layouts/masters.
- *
- * Consumers:
- *   - the editor's theme customizer surfaces (upload / drag-drop a file)
- *   - the PPTX importer (theme + layouts ride along as frontmatter)
- *
- * PDF is deliberately unsupported: PDF files carry no theme tables, so
- * inference would produce a mostly-default theme. `inferThemeFromFile`
- * rejects PDF bytes with a clear `ConversionError`.
- */
-
-import type { CustomTemplateDefinition, Theme } from '@bendyline/squisq/schemas';
-import { openPackage, throwIfOoxmlAborted } from '../ooxml/reader.js';
-import type { OoxmlOpenOptions } from '../ooxml/reader.js';
-import type { OoxmlPackage } from '../ooxml/types.js';
-import { ConversionError } from '../registry/errors.js';
-import type { ExtractedFileTheme, InferSourceFormat } from './types.js';
-import { extractDocxTheme, extractPptxTheme, extractXlsxTheme } from './extract.js';
-import { colorHintsFromExtraction, compileExtractedTheme } from './mapTheme.js';
-
-export type { ExtractedFileTheme, InferSourceFormat, SchemeSlot } from './types.js';
-export { extractDocxTheme, extractPptxTheme, extractXlsxTheme } from './extract.js';
-export type { CompileExtractedOptions, MappedThemePartial } from './mapTheme.js';
-export {
-  colorHintsFromExtraction,
-  compileExtractedTheme,
-  extractedThemeToPartial,
-} from './mapTheme.js';
-
-export interface InferThemeOptions extends OoxmlOpenOptions {
-  /** Skip sniffing when the caller already knows the format (e.g. from the extension). */
-  format?: InferSourceFormat;
-  /** PPTX only: also derive custom layout templates from slide layouts/masters. */
-  inferLayouts?: boolean;
-  /** Preferred display name for the compiled theme (e.g. the file's basename). */
-  nameHint?: string;
-}
-
-export interface InferredFileTheme {
-  /** Compiled, validated Squisq theme (`custom-<slug>` id, seeds recorded). */
-  theme: Theme;
-  /** Raw extraction, for callers mapping into their own editing model. */
-  extraction: ExtractedFileTheme;
-  /** Present only for PPTX with `inferLayouts` and ≥1 non-redundant layout. */
-  layouts?: CustomTemplateDefinition[];
-  /** Non-fatal notes: sysClr fallbacks, dropped accents, skipped layouts, … */
-  warnings: string[];
-}
-
-async function looksLikePdf(data: ArrayBuffer | Blob, signal?: AbortSignal): Promise<boolean> {
-  throwIfOoxmlAborted(signal);
-  // Duck-typed (not instanceof): buffers routinely cross realms in test
-  // environments and web workers. Blobs carry `size`; ArrayBuffers carry
-  // `byteLength`.
-  let head: Uint8Array | null = null;
-  const blob = data as Blob;
-  if (
-    typeof blob.size === 'number' &&
-    typeof blob.slice === 'function' &&
-    typeof blob.arrayBuffer === 'function'
-  ) {
-    head = new Uint8Array(await waitForAbortable(blob.slice(0, 5).arrayBuffer(), signal));
-  } else if (typeof (data as ArrayBuffer).byteLength === 'number') {
-    const buf = data as ArrayBuffer;
-    head = new Uint8Array(buf, 0, Math.min(5, buf.byteLength));
-  }
-  throwIfOoxmlAborted(signal);
-  if (!head || head.length < 4) return false;
-  // '%PDF'
-  return head[0] === 0x25 && head[1] === 0x50 && head[2] === 0x44 && head[3] === 0x46;
-}
-
-function waitForAbortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
-  throwIfOoxmlAborted(signal);
-  if (!signal) return work;
-  return new Promise<T>((resolve, reject) => {
-    let settled = false;
-    const finish = (complete: () => void): void => {
-      if (settled) return;
-      settled = true;
-      signal.removeEventListener('abort', handleAbort);
-      complete();
-    };
-    const handleAbort = (): void =>
-      finish(() => reject(signal.reason ?? new Error('OOXML operation was cancelled')));
-    signal.addEventListener('abort', handleAbort, { once: true });
-    if (signal.aborted) handleAbort();
-    work.then(
-      (value) => finish(() => resolve(value)),
-      (error: unknown) => finish(() => reject(error)),
-    );
-  });
-}
-
-/**
- * Classify an opened package from its already-parsed content types.
- * (Deliberately not the registry's byte sniffer — that re-parses the zip
- * and carries `dbk` semantics this path doesn't want.)
- */
-function sniffOoxmlFormat(pkg: OoxmlPackage): InferSourceFormat | undefined {
-  const values = [...pkg.contentTypes.overrides.values(), ...pkg.contentTypes.defaults.values()];
-  for (const ct of values) {
-    if (ct.includes('wordprocessingml')) return 'docx';
-    if (ct.includes('presentationml')) return 'pptx';
-    if (ct.includes('spreadsheetml')) return 'xlsx';
-  }
-  return undefined;
-}
-
-const EXTRACTORS: Record<
-  InferSourceFormat,
-  (pkg: OoxmlPackage) => Promise<ExtractedFileTheme | null>
-> = {
-  docx: extractDocxTheme,
-  pptx: extractPptxTheme,
-  xlsx: extractXlsxTheme,
-};
-
-/**
- * Infer a Squisq theme (and, for PPTX, optionally custom layout templates)
- * from an office file's bytes.
- *
- * Throws `ConversionError`:
- *   - `unsupported-input` for PDF bytes (no theme tables to read)
- *   - `invalid-input` for non-OOXML data or files with no theme part
- */
-export async function inferThemeFromFile(
-  data: ArrayBuffer | Blob,
-  options: InferThemeOptions = {},
-): Promise<InferredFileTheme> {
-  throwIfOoxmlAborted(options.signal);
-  if (await looksLikePdf(data, options.signal)) {
-    throw new ConversionError(
-      'unsupported-input',
-      'PDF theme inference is not supported — PDF files carry no theme color/font tables.',
-      { format: 'pdf' },
-    );
-  }
-
-  let pkg: OoxmlPackage;
-  try {
-    pkg = await openPackage(data, options);
-  } catch (err: unknown) {
-    if (options.signal?.aborted) throw options.signal.reason ?? err;
-    throw new ConversionError(
-      'invalid-input',
-      'Could not read this file as a Word, PowerPoint, or Excel document.',
-      { cause: err },
-    );
-  }
-
-  const format = options.format ?? sniffOoxmlFormat(pkg);
-  throwIfOoxmlAborted(options.signal);
-  if (!format) {
-    throw new ConversionError(
-      'invalid-input',
-      'Not a Word, PowerPoint, or Excel document — no theme to infer.',
-    );
-  }
-
-  const extraction = await EXTRACTORS[format](pkg);
-  throwIfOoxmlAborted(options.signal);
-  if (!extraction) {
-    throw new ConversionError('invalid-input', 'No theme part found in this file.', { format });
-  }
-
-  const { theme, warnings: mapWarnings } = compileExtractedTheme(extraction, {
-    nameHint: options.nameHint,
-  });
-  throwIfOoxmlAborted(options.signal);
-  const warnings = [...extraction.warnings, ...mapWarnings];
-
-  let layouts: CustomTemplateDefinition[] | undefined;
-  if (options.inferLayouts) {
-    if (format !== 'pptx') {
-      warnings.push('Layout inference is only available for PowerPoint files; skipped.');
-    } else {
-      const { analyzePptxLayouts } = await import('../pptx/layouts.js');
-      const analysis = await analyzePptxLayouts(pkg, {
-        colors: colorHintsFromExtraction(extraction),
-        signal: options.signal,
-      });
-      warnings.push(...analysis.warnings);
-      const defs = analysis.layouts
-        .map((l) => (l.verdict.kind === 'custom' ? l.verdict.def : null))
-        .filter((d): d is CustomTemplateDefinition => d !== null);
-      if (defs.length > 0) layouts = defs;
-    }
-  }
-
-  throwIfOoxmlAborted(options.signal);
-  return { theme, extraction, ...(layouts ? { layouts } : {}), warnings };
-}

package/src/infer/mapTheme.ts

@@ -1,176 +0,0 @@
-/**
- * Map a raw OOXML theme extraction onto a compiled Squisq `Theme`.
- *
- * Only a handful of seeds are taken from the file (lead accents, background,
- * text, major/minor fonts); `compileTheme` derives the rest of the palette
- * via OKLCh so the result is always a complete, validated theme that stays
- * re-editable in the customizer (seeds are recorded on `Theme.seedColors`).
- */
-
-import type {
-  DeepPartial,
-  Theme,
-  ThemeColorScheme,
-  ThemeSeedColors,
-} from '@bendyline/squisq/schemas';
-import {
-  accentToColorScheme,
-  compileTheme,
-  contrastRatio,
-  isHex,
-  matchFontFamily,
-  relativeLuminance,
-} from '@bendyline/squisq/schemas';
-import type { PptxColorHints } from '../pptx/layouts.js';
-import type { ExtractedFileTheme } from './types.js';
-
-export interface CompileExtractedOptions {
-  /** Preferred display name for the compiled theme (e.g. the file's basename). */
-  nameHint?: string;
-}
-
-export interface MappedThemePartial {
-  partial: DeepPartial<Theme>;
-  warnings: string[];
-}
-
-/** Neutral primary used when a theme resolves no usable accent slots. */
-const FALLBACK_PRIMARY = '#3182ce';
-
-/** Accents closer to the background than this contrast are dropped (near-invisible). */
-const MIN_ACCENT_CONTRAST = 1.3;
-
-const ACCENT_SLOTS = ['accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6'] as const;
-
-/** Companion slot providing `backgroundLight` for each background slot. */
-const COMPANION_SLOT = { lt1: 'lt2', dk1: 'dk2', lt2: 'lt1', dk2: 'dk1' } as const;
-
-function slugify(name: string): string {
-  const slug = name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return slug || 'imported';
-}
-
-/**
- * Build the `DeepPartial<Theme>` for an extraction. Exported for tests; most
- * callers want {@link compileExtractedTheme}.
- */
-export function extractedThemeToPartial(
-  extraction: ExtractedFileTheme,
-  opts: CompileExtractedOptions = {},
-): MappedThemePartial {
-  const warnings: string[] = [];
-  const { colors, colorMap, fonts } = extraction;
-
-  const name = opts.nameHint?.trim() || extraction.themeName || 'Imported Theme';
-  const partial: DeepPartial<Theme> = {
-    id: `custom-${slugify(name)}`,
-    name,
-    description: `Imported from a ${extraction.sourceFormat} file${
-      extraction.themeName ? ` (theme "${extraction.themeName}")` : ''
-    }.`,
-  };
-
-  if (colors) {
-    const primary = colors.accent1 ?? colors.accent2;
-    if (!primary) {
-      warnings.push('theme: no usable accent colors; primary defaults to Squisq blue');
-    }
-
-    let background: string | undefined = colors[colorMap.bg1];
-    let text: string | undefined = colors[colorMap.tx1];
-    // Pathological color maps can land background and text on similar
-    // surfaces; when they don't contrast, let the compiler derive both
-    // from the primary instead of shipping unreadable seeds.
-    if (
-      background &&
-      text &&
-      Math.abs(relativeLuminance(background) - relativeLuminance(text)) < 0.2
-    ) {
-      warnings.push('theme: background and text colors are too close; deriving surfaces instead');
-      background = undefined;
-      text = undefined;
-    }
-
-    const seeds: ThemeSeedColors = {
-      primary: primary ?? FALLBACK_PRIMARY,
-      ...(colors.accent2 ? { secondary: colors.accent2 } : {}),
-      ...(colors.accent3 ? { accent: colors.accent3 } : {}),
-      ...(background ? { background } : {}),
-      ...(text ? { text } : {}),
-    };
-    partial.seedColors = seeds;
-
-    const explicitColors: DeepPartial<Theme>['colors'] = {};
-    const companion = background ? colors[COMPANION_SLOT[colorMap.bg1]] : undefined;
-    if (background && companion && companion !== background) {
-      explicitColors.backgroundLight = companion;
-    }
-    if (colors.hlink && isHex(colors.hlink)) {
-      explicitColors.highlight = colors.hlink;
-    }
-    if (Object.keys(explicitColors).length > 0) partial.colors = explicitColors;
-
-    const schemes: Record<string, ThemeColorScheme> = {};
-    const seenHexes = new Set<string>();
-    const schemeBackground = background ?? colors[colorMap.bg1];
-    for (const slot of ACCENT_SLOTS) {
-      const hex = colors[slot];
-      if (!hex || seenHexes.has(hex)) continue;
-      if (schemeBackground && contrastRatio(hex, schemeBackground) < MIN_ACCENT_CONTRAST) {
-        warnings.push(`theme: ${slot} is too close to the background; dropped from accents`);
-        continue;
-      }
-      seenHexes.add(hex);
-      schemes[slot] = accentToColorScheme(hex);
-    }
-    if (Object.keys(schemes).length > 0) partial.colorSchemes = schemes;
-  }
-
-  if (fonts?.majorLatin || fonts?.minorLatin) {
-    partial.typography = {
-      ...(fonts.majorLatin ? { titleFont: matchFontFamily(fonts.majorLatin) } : {}),
-      ...(fonts.minorLatin ? { bodyFont: matchFontFamily(fonts.minorLatin) } : {}),
-    };
-  }
-
-  return { partial, warnings };
-}
-
-/**
- * Compile an extraction into a full validated Squisq theme. Mapping warnings
- * (dropped accents, low-contrast surfaces) are returned alongside; extraction
- * warnings stay on `extraction.warnings`.
- */
-export function compileExtractedTheme(
-  extraction: ExtractedFileTheme,
-  opts: CompileExtractedOptions = {},
-): { theme: Theme; warnings: string[] } {
-  const { partial, warnings } = extractedThemeToPartial(extraction, opts);
-  return { theme: compileTheme(partial), warnings };
-}
-
-/**
- * Build the color hints the PPTX layout generator uses to resolve scheme
- * color references (`a:schemeClr val="accent1"`, `bg1`, `tx1`, …) on
- * decorative shapes.
- */
-export function colorHintsFromExtraction(extraction: ExtractedFileTheme): PptxColorHints {
-  const { colors, colorMap } = extraction;
-  if (!colors) return {};
-  const schemeColors: Record<string, string> = {};
-  for (const [slot, hex] of Object.entries(colors)) {
-    if (typeof hex === 'string') schemeColors[slot] = hex;
-  }
-  const background = colors[colorMap.bg1];
-  const text = colors[colorMap.tx1];
-  if (background) schemeColors['bg1'] = background;
-  if (text) schemeColors['tx1'] = text;
-  return {
-    ...(background ? { background } : {}),
-    ...(text ? { text } : {}),
-    schemeColors,
-  };
-}

package/src/infer/types.ts

@@ -1,27 +0,0 @@
-/**
- * Shared types for file-import theme inference.
- */
-
-import type { OoxmlColorScheme, OoxmlFontScheme } from '../ooxml/themeReader.js';
-
-/** Source formats theme inference supports. PDF carries no theme tables. */
-export type InferSourceFormat = 'docx' | 'pptx' | 'xlsx';
-
-/** The four surface/text scheme slots a color map can point at. */
-export type SchemeSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2';
-
-/**
- * Raw theme extraction from one office file, before mapping onto a Squisq
- * `Theme`. `colorMap` records which scheme slots back the document's
- * background/text — PPTX masters carry `<p:clrMap bg1=… tx1=…>` and DOCX may
- * carry `w:clrSchemeMapping`; dark decks map `bg1="dk1"` and invert here.
- */
-export interface ExtractedFileTheme {
-  sourceFormat: InferSourceFormat;
-  /** `a:theme@name` when present (e.g. "Office Theme", "Ion"). */
-  themeName?: string;
-  colors?: OoxmlColorScheme;
-  colorMap: { bg1: SchemeSlot; tx1: SchemeSlot };
-  fonts?: OoxmlFontScheme;
-  warnings: string[];
-}

package/src/ooxml/index.ts

@@ -1,111 +0,0 @@
-/**
- * @bendyline/squisq-formats OOXML Module
- *
- * Shared infrastructure for reading and writing Office Open XML packages
- * (DOCX, PPTX, XLSX). Provides ZIP archive handling, relationship management,
- * content type assembly, XML utilities, and core property parsing.
- *
- * This module is consumed by the format-specific modules (docx/, pptx/, xlsx/)
- * and can also be imported directly by advanced consumers.
- *
- * @example
- * ```ts
- * import { createPackage, openPackage } from '@bendyline/squisq-formats/ooxml';
- * ```
- */
-
-// Types
-export type {
-  OoxmlPackage,
-  ContentTypeMap,
-  Relationship,
-  CoreProperties,
-  PackagePart,
-  PendingRelationship,
-} from './types.js';
-
-// Reader
-export type { OoxmlOpenOptions } from './reader.js';
-export { ZipSafetyError } from '../shared/zipSafety.js';
-export type {
-  ZipSafetyLimits,
-  ZipSafetyErrorCode,
-  ZipSafetyErrorOptions,
-} from '../shared/zipSafety.js';
-export {
-  openPackage,
-  getPartRelationships,
-  getPartXml,
-  getPartBinary,
-  getCoreProperties,
-} from './reader.js';
-
-// Read utilities
-export { attrNS, baseDirOf, resolveTarget, findRelByType } from './readUtils.js';
-
-// Theme reader
-export type { OoxmlColorScheme, OoxmlFontScheme, OoxmlTheme } from './themeReader.js';
-export { parseThemeXml, readThemePart } from './themeReader.js';
-
-// Writer
-export type { OoxmlPackageBuilder } from './writer.js';
-export { createPackage } from './writer.js';
-
-// XML Utilities
-export {
-  xmlDeclaration,
-  escapeXml,
-  attrString,
-  selfClosingElement,
-  xmlElement,
-  textElement,
-} from './xmlUtils.js';
-
-// Namespace constants
-export {
-  NS_RELATIONSHIPS,
-  NS_CONTENT_TYPES,
-  REL_OFFICE_DOCUMENT,
-  REL_CORE_PROPERTIES,
-  REL_EXTENDED_PROPERTIES,
-  REL_STYLES,
-  REL_NUMBERING,
-  REL_FONT_TABLE,
-  REL_SETTINGS,
-  REL_HYPERLINK,
-  REL_IMAGE,
-  REL_FOOTNOTES,
-  REL_THEME,
-  NS_WML,
-  NS_PML,
-  NS_SML,
-  NS_DRAWINGML,
-  NS_WP_DRAWING,
-  NS_PICTURE,
-  NS_DC,
-  NS_DCTERMS,
-  NS_CORE_PROPERTIES,
-  NS_XSI,
-  NS_MC,
-  NS_R,
-  CONTENT_TYPE_RELATIONSHIPS,
-  CONTENT_TYPE_CORE_PROPERTIES,
-  CONTENT_TYPE_DOCX_DOCUMENT,
-  CONTENT_TYPE_DOCX_STYLES,
-  CONTENT_TYPE_DOCX_NUMBERING,
-  CONTENT_TYPE_DOCX_SETTINGS,
-  CONTENT_TYPE_DOCX_FONT_TABLE,
-  CONTENT_TYPE_DOCX_FOOTNOTES,
-  CONTENT_TYPE_PPTX_PRESENTATION,
-  CONTENT_TYPE_PPTX_SLIDE,
-  CONTENT_TYPE_PPTX_SLIDE_LAYOUT,
-  CONTENT_TYPE_PPTX_SLIDE_MASTER,
-  CONTENT_TYPE_PPTX_THEME,
-  REL_SLIDE,
-  REL_SLIDE_LAYOUT,
-  REL_SLIDE_MASTER,
-  CONTENT_TYPE_XLSX_WORKBOOK,
-  CONTENT_TYPE_XLSX_WORKSHEET,
-  CONTENT_TYPE_XLSX_STYLES,
-  REL_WORKSHEET,
-} from './namespaces.js';