mosage 0.2.0 → 0.8.0

package/src/app/lib/docx/fonts.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import {
+  eastAsiaLangFromFonts,
+  fontKindOf,
+  isCjkFace,
+  parseFontFamily,
+  pickFonts,
+  standInFor,
+} from './fonts';
+
+describe('parseFontFamily', () => {
+  it('splits on commas outside quotes and drops the quotes', () => {
+    expect(parseFontFamily('"Noto Serif TC", \'Source Han Serif\', serif')).toEqual([
+      'Noto Serif TC',
+      'Source Han Serif',
+      'serif',
+    ]);
+    expect(parseFontFamily('"Font, With Comma", Arial')).toEqual(['Font, With Comma', 'Arial']);
+  });
+});
+
+describe('pickFonts', () => {
+  it('skips system aliases Word cannot look up', () => {
+    expect(pickFonts('-apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif')).toEqual({
+      ascii: 'Inter',
+    });
+  });
+
+  it('names a real face for a stack of generics only', () => {
+    expect(pickFonts('system-ui, sans-serif')).toEqual({ ascii: 'Arial' });
+    expect(pickFonts('ui-monospace, monospace')).toEqual({ ascii: 'Courier New' });
+    expect(pickFonts('serif')).toEqual({ ascii: 'Times New Roman' });
+  });
+
+  /* 主題指定的中文字型必須寫進 w:eastAsia，否則 Word 會換字型、斷行跟著變。 */
+  it('keeps the theme’s CJK face for East Asian text', () => {
+    expect(pickFonts('"Noto Serif TC", serif')).toEqual({
+      ascii: 'Noto Serif TC',
+      eastAsia: 'Noto Serif TC',
+    });
+    expect(pickFonts('"Inter", "Noto Sans TC", sans-serif')).toEqual({
+      ascii: 'Inter',
+      eastAsia: 'Noto Sans TC',
+    });
+    expect(pickFonts('"微軟正黑體", sans-serif')).toEqual({
+      ascii: '微軟正黑體',
+      eastAsia: '微軟正黑體',
+    });
+  });
+
+  /* 小型大寫的拉丁字型（Playfair Display SC）和 HK Grotesk 不是中日韓字型。 */
+  it('does not take a Latin small-caps or "HK" family for a CJK face', () => {
+    for (const name of ['Playfair Display SC', 'Alegreya Sans SC', 'Amatic SC', 'HK Grotesk']) {
+      expect(isCjkFace(name)).toBe(false);
+    }
+    for (const name of ['Noto Serif SC', 'Noto Sans CJK TC', 'LXGW WenKai TC', 'Chiron Hei HK']) {
+      expect(isCjkFace(name)).toBe(true);
+    }
+    expect(pickFonts('"Playfair Display SC", serif')).toEqual({ ascii: 'Playfair Display SC' });
+    expect(pickFonts('"HK Grotesk", "Noto Sans TC", sans-serif')).toEqual({
+      ascii: 'HK Grotesk',
+      eastAsia: 'Noto Sans TC',
+    });
+  });
+
+  it('leaves the East Asian face to Word when the theme names none', () => {
+    expect(pickFonts('"Century Gothic", Arial, sans-serif')).toEqual({ ascii: 'Century Gothic' });
+    expect(isCjkFace('Century Gothic')).toBe(false);
+  });
+
+  it('ignores emoji faces at the end of a stack', () => {
+    expect(pickFonts('"Apple Color Emoji", "Segoe UI Emoji", sans-serif')).toEqual({
+      ascii: 'Arial',
+    });
+  });
+});
+
+describe('eastAsiaLangFromFonts', () => {
+  it('reads the language from the face name', () => {
+    expect(eastAsiaLangFromFonts(['Noto Sans TC'])).toBe('zh-TW');
+    expect(eastAsiaLangFromFonts(['PingFang SC'])).toBe('zh-CN');
+    expect(eastAsiaLangFromFonts(['Noto Sans HK'])).toBe('zh-HK');
+    expect(eastAsiaLangFromFonts(['Hiragino Sans'])).toBe('ja-JP');
+    expect(eastAsiaLangFromFonts(['Noto Sans KR'])).toBe('ko-KR');
+  });
+
+  it('guesses nothing from a face that does not say', () => {
+    expect(eastAsiaLangFromFonts(['Source Han Sans'])).toBeUndefined();
+    expect(eastAsiaLangFromFonts([])).toBeUndefined();
+  });
+});
+
+describe('standInFor', () => {
+  /* 沒有字族資訊時，Word 會把缺少的字型一律換成 Times New Roman。 */
+  it('tells Word what kind of face to substitute for a missing one', () => {
+    expect(fontKindOf('"Inter", system-ui, sans-serif')).toBe('sans');
+    expect(fontKindOf('"Noto Serif TC", serif')).toBe('serif');
+    expect(fontKindOf('"JetBrains Mono", monospace')).toBe('mono');
+    expect(standInFor({ name: 'Inter', kind: 'sans', eastAsia: false }, undefined)).toEqual({
+      altName: 'Arial',
+      charset: '00',
+      family: 'swiss',
+      pitch: 'variable',
+    });
+    expect(
+      standInFor({ name: 'JetBrains Mono', kind: 'mono', eastAsia: false }, undefined),
+    ).toMatchObject({
+      altName: 'Courier New',
+      family: 'modern',
+      pitch: 'fixed',
+    });
+  });
+
+  it('stands a CJK face in with one for the same language', () => {
+    expect(standInFor({ name: 'Noto Serif TC', kind: 'serif', eastAsia: true }, 'zh-TW')).toEqual({
+      altName: 'PMingLiU',
+      charset: '88',
+      family: 'roman',
+      pitch: 'variable',
+    });
+    expect(
+      standInFor({ name: 'Noto Sans JP', kind: 'sans', eastAsia: true }, 'ja-JP'),
+    ).toMatchObject({
+      altName: 'Yu Gothic',
+      charset: '80',
+    });
+    // No language, no guess at a face — only the family.
+    expect(
+      standInFor({ name: 'Source Han Sans', kind: 'sans', eastAsia: true }, undefined),
+    ).toEqual({
+      charset: '00',
+      family: 'swiss',
+      pitch: 'variable',
+    });
+  });
+});

package/src/app/lib/docx/fonts.ts

@@ -0,0 +1,166 @@
+import type { FontSet } from './model';
+
+/**
+ * Names in a CSS stack that are not faces Word can look up. The browser
+ * resolves them to whatever the system uses; Word would take them literally and
+ * fall back to Times New Roman.
+ */
+const NOT_A_FACE = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'emoji',
+  'math',
+  'fangsong',
+  '-apple-system',
+  'blinkmacsystemfont',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+]);
+
+const EMOJI_FACE = /emoji|symbol/i;
+
+/**
+ * Faces that carry CJK glyphs. Matched by name because there is nothing else to
+ * go on — the stack is text — and a name in any non-Latin script is taken as one too.
+ * Deliberately not a bare "Gothic": Century Gothic is a Latin face.
+ */
+const CJK_FACE =
+  /\bCJK\b|Source Han|PingFang|Hiragino|Meiryo|JhengHei|YaHei|SimSun|SimHei|MingLiU|DFKai|BiauKai|LiGothic|LiSung|LiHei|Heiti|Songti|Kaiti|STSong|FangSong|Malgun|Batang|Gulim|Dotum|Nanum|Apple SD Gothic|Yu Gothic|Mincho|MS P?Gothic|[^ -\u024F]/i;
+
+/** Splits a computed `font-family` into names, quotes removed, order kept. */
+export function parseFontFamily(value: string): string[] {
+  const names: string[] = [];
+  let current = '';
+  let quote: string | null = null;
+  for (const ch of value) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === ',') {
+      if (current.trim()) names.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) names.push(current.trim());
+  return names;
+}
+
+/**
+ * A region cut named at the end — "Noto Sans TC", "Chiron Hei HK". Case matters,
+ * and SC counts only on a family that has CJK cuts: "Playfair Display SC" and
+ * "Alegreya Sans SC" are small caps, and "HK Grotesk" is Latin.
+ */
+const CJK_REGION = /\s(?:TC|HK|JP|KR)$|\b(?:Noto|LXGW|WenKai|Sarasa|HarmonyOS|Chiron)\b.*\sSC$/;
+
+export function isCjkFace(name: string): boolean {
+  return CJK_FACE.test(name) || CJK_REGION.test(name);
+}
+
+export type FontKind = 'sans' | 'serif' | 'mono';
+
+/** What the stack falls back to — the only thing it says about the face's design. */
+export function fontKindOf(fontFamily: string): FontKind {
+  for (const name of parseFontFamily(fontFamily).map((n) => n.toLowerCase())) {
+    if (name === 'serif' || name === 'ui-serif') return 'serif';
+    if (name === 'monospace' || name === 'ui-monospace') return 'mono';
+  }
+  return 'sans';
+}
+
+const LATIN_STANDIN: Record<FontKind, string> = {
+  sans: 'Arial',
+  serif: 'Times New Roman',
+  mono: 'Courier New',
+};
+
+/**
+ * The faces Word should ask for, taken in the theme's own order: the first real
+ * face for Latin text, and the first CJK face for East Asian text. When the
+ * stack names no CJK face the East Asian slot is left empty, so Word picks its
+ * own for the language instead of being told to set Chinese in Arial.
+ */
+export function pickFonts(fontFamily: string): FontSet {
+  const names = parseFontFamily(fontFamily);
+  const faces = names.filter(
+    (name) => !NOT_A_FACE.has(name.toLowerCase()) && !EMOJI_FACE.test(name),
+  );
+  const ascii = faces[0] ?? LATIN_STANDIN[fontKindOf(fontFamily)];
+  const eastAsia = faces.find(isCjkFace);
+  return eastAsia ? { ascii, eastAsia } : { ascii };
+}
+
+/**
+ * The language tag Word uses for line breaking and proofing of East Asian
+ * text, read from the face names. Nothing is guessed from the text itself: Han
+ * characters alone do not say whether a document is Traditional or Simplified.
+ */
+export function eastAsiaLangFromFonts(faces: string[]): string | undefined {
+  for (const face of faces) {
+    if (/\bHK\b/.test(face)) return 'zh-HK';
+    if (/\bTC\b|JhengHei|MingLiU|DFKai|BiauKai|LiGothic|LiSung/i.test(face)) return 'zh-TW';
+    if (/\bSC\b|YaHei|SimSun|SimHei/i.test(face)) return 'zh-CN';
+    if (/\bJP\b|Hiragino|Meiryo|Mincho|Yu Gothic|MS P?Gothic/i.test(face)) return 'ja-JP';
+    if (/\bKR\b|Malgun|Batang|Gulim|Dotum|Nanum/i.test(face)) return 'ko-KR';
+  }
+  return undefined;
+}
+
+const CJK_STANDIN: Record<string, { sans: string; serif: string; charset: string }> = {
+  'zh-TW': { sans: 'Microsoft JhengHei', serif: 'PMingLiU', charset: '88' },
+  'zh-HK': { sans: 'Microsoft JhengHei', serif: 'PMingLiU', charset: '88' },
+  'zh-CN': { sans: 'Microsoft YaHei', serif: 'SimSun', charset: '86' },
+  'ja-JP': { sans: 'Yu Gothic', serif: 'Yu Mincho', charset: '80' },
+  'ko-KR': { sans: 'Malgun Gothic', serif: 'Batang', charset: '81' },
+};
+
+export type FontDeclaration = {
+  name: string;
+  kind: FontKind;
+  /** Used for East Asian text, so it wants a CJK face in its place. */
+  eastAsia: boolean;
+};
+
+/**
+ * Where Word should look when the face is not installed. Without a family,
+ * Word substitutes Times New Roman for any missing face — a sans-serif theme
+ * would arrive in a serif on every machine that lacks the exact face.
+ */
+export function standInFor(
+  font: FontDeclaration,
+  eastAsiaLang: string | undefined,
+): {
+  altName?: string;
+  charset: string;
+  family: 'swiss' | 'roman' | 'modern';
+  pitch: 'variable' | 'fixed';
+} {
+  const family = font.kind === 'serif' ? 'roman' : font.kind === 'mono' ? 'modern' : 'swiss';
+  const pitch = font.kind === 'mono' ? 'fixed' : 'variable';
+  if (font.eastAsia) {
+    const cjk = eastAsiaLang ? CJK_STANDIN[eastAsiaLang] : undefined;
+    if (!cjk) return { charset: '00', family, pitch };
+    const altName = font.kind === 'serif' ? cjk.serif : cjk.sans;
+    return {
+      altName: altName === font.name ? undefined : altName,
+      charset: cjk.charset,
+      family,
+      pitch,
+    };
+  }
+  const altName = LATIN_STANDIN[font.kind];
+  return { altName: altName === font.name ? undefined : altName, charset: '00', family, pitch };
+}

package/src/app/lib/docx/media.ts

@@ -0,0 +1,102 @@
+import { drawToPng } from '../rasterize';
+import type { Media } from './model';
+
+type Format = 'png' | 'jpeg' | 'gif';
+
+function sniff(bytes: Uint8Array): Format | null {
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
+    return 'png';
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'jpeg';
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return 'gif';
+  return null;
+}
+
+type Picture = { bytes: Uint8Array; type: Format; drawn: boolean };
+
+async function png(source: CanvasImageSource, size: { width: number; height: number }) {
+  const blob = await drawToPng(source, size);
+  return { bytes: new Uint8Array(await blob.arrayBuffer()), type: 'png' as const, drawn: true };
+}
+
+/** A picture's own bytes when Word reads the format; otherwise what the browser decoded. */
+async function readImage(img: HTMLImageElement, source: string, size: DOMRect): Promise<Picture> {
+  // SVG, WebP, AVIF: formats Word may not open, so their bytes would be discarded anyway.
+  if (!/\.(?:svg|webp|avif)(?:[?#]|$)/i.test(source)) {
+    try {
+      const response = await fetch(source);
+      if (response.ok) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const type = sniff(bytes);
+        if (type) return { bytes, type, drawn: false };
+      }
+    } catch {
+      /* Drawn below from what the page already decoded. */
+    }
+  }
+  return png(img, size);
+}
+
+/** Cropped, rounded, or filtered on the page: the file is not what the reader sees. */
+function reshaped(img: HTMLImageElement): boolean {
+  const cs = getComputedStyle(img);
+  return (
+    cs.objectFit !== 'fill' ||
+    cs.borderRadius !== '0px' ||
+    cs.clipPath !== 'none' ||
+    cs.filter !== 'none'
+  );
+}
+
+function same(a: Uint8Array, b: Uint8Array): boolean {
+  if (a === b) return true;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** The package's pictures, each stored once however many times the document shows it. */
+export class MediaStore {
+  readonly media: Media[] = [];
+  private readonly bySource = new Map<string, number>();
+  /** By byte length: two different pictures of exactly one size are rare, and told apart byte by byte. */
+  private readonly byLength = new Map<number, number[]>();
+
+  constructor(private readonly rasterize: (el: Element) => Promise<Uint8Array | null>) {}
+
+  /** The index of a picture of `el`, or null when none could be made. */
+  async of(el: Element, rect: DOMRect): Promise<number | null> {
+    const img = el instanceof HTMLImageElement ? el : null;
+    const source = img && !reshaped(img) ? img.currentSrc || img.src : '';
+    const known = source ? this.bySource.get(source) : undefined;
+    if (known !== undefined) return known;
+
+    let picture: Picture | null = null;
+    try {
+      if (img && source) picture = await readImage(img, source, rect);
+      else if (el instanceof HTMLCanvasElement) picture = await png(el, rect);
+      else {
+        const bytes = await this.rasterize(el);
+        picture = bytes && { bytes, type: 'png', drawn: true };
+      }
+    } catch {
+      // A cross-origin picture taints the canvas and cannot be read back.
+      return null;
+    }
+    if (!picture) return null;
+
+    // Matched on what was drawn, not on what drew it: two canvases with the
+    // same markup can hold different charts, and one SVG in two colours is two
+    // pictures — while the logo in every section's footer is still one.
+    const { bytes, type } = picture;
+    const candidates = this.byLength.get(bytes.length) ?? [];
+    let index = candidates.find((i) => same(this.media[i].bytes, bytes));
+    if (index === undefined) {
+      index = this.media.length;
+      this.media.push({ name: `image${index + 1}.${type}`, contentType: `image/${type}`, bytes });
+      this.byLength.set(bytes.length, [...candidates, index]);
+    }
+    // Only the file itself stands for its URL. A drawing of it is the size it was
+    // drawn at, and the same logo larger on another page needs its own.
+    if (source && !picture.drawn) this.bySource.set(source, index);
+    return index;
+  }
+}

package/src/app/lib/docx/model.ts

@@ -0,0 +1,206 @@
+import type { FontDeclaration } from './fonts';
+
+/**
+ * What a document looks like once it has been read out of the DOM and before
+ * it is written as WordprocessingML.
+ *
+ * Everything is already in Word's units — twips (1/20 pt) for lengths,
+ * half-points for type sizes, EMU for drawings, six-digit hex for colours — so
+ * the writer is plain string assembly and can be tested without a browser.
+ */
+
+export type FontSet = {
+  /** Latin text: `w:ascii`, `w:hAnsi`, `w:cs`. */
+  ascii: string;
+  /** Han, kana, hangul: `w:eastAsia`. Absent when the theme names no CJK face. */
+  eastAsia?: string;
+};
+
+export type RunStyle = {
+  fonts: FontSet;
+  /** Half-points. */
+  size: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strike: boolean;
+  color: string;
+  /** Background behind the run — inline code, a highlight. */
+  shading?: string;
+  vertAlign?: 'superscript' | 'subscript';
+  caps?: boolean;
+  smallCaps?: boolean;
+  /** Letter spacing, twips. */
+  spacing?: number;
+};
+
+export type LinkTarget = { url: string } | { anchor: string };
+
+export type Inline =
+  | { type: 'text'; text: string; style: RunStyle; link?: LinkTarget }
+  /** `style` keeps an empty line in preformatted text at the text's own size. */
+  | { type: 'break'; style?: RunStyle }
+  | { type: 'tab' }
+  | { type: 'field'; instr: string; cached: string; style: RunStyle; link?: LinkTarget }
+  /** `style` is the marker as it rendered; its colour becomes the reference style's. */
+  | { type: 'footnote'; id: number; style: RunStyle }
+  | { type: 'image'; image: ImageRef; link?: LinkTarget };
+
+export type ImageRef = {
+  /** Index into `DocxModel.media`. */
+  media: number;
+  /** EMU. */
+  width: number;
+  height: number;
+  alt: string;
+};
+
+export type BorderStyle = 'single' | 'dashed' | 'dotted' | 'double';
+
+export type Border = {
+  style: BorderStyle;
+  /** Eighths of a point. */
+  size: number;
+  color: string;
+  /** Distance from the text, points. */
+  space: number;
+};
+
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+
+export type Sides = Record<Side, number>;
+
+export type Borders = Partial<Record<Side, Border>>;
+
+export type TabStop = {
+  align: 'left' | 'center' | 'right';
+  /** Twips from the text column's leading edge. */
+  pos: number;
+  leader?: 'dot' | 'hyphen' | 'underscore';
+};
+
+export type ParagraphProps = {
+  align?: 'left' | 'center' | 'right' | 'both';
+  spaceBefore?: number;
+  spaceAfter?: number;
+  /** Line height, twips. `atLeast` unless `lineExact`. */
+  line?: number;
+  lineExact?: boolean;
+  indentLeft?: number;
+  indentRight?: number;
+  /** Negative is a hanging indent. */
+  firstLine?: number;
+  borders?: Borders;
+  shading?: string;
+  tabs?: TabStop[];
+  keepNext?: boolean;
+  pageBreakBefore?: boolean;
+  /** Right to left. */
+  bidi?: boolean;
+  /** Size of the paragraph mark, half-points — keeps an empty rule paragraph thin. */
+  markSize?: number;
+};
+
+export type ParagraphRole =
+  | 'body'
+  | 'heading'
+  | 'title'
+  | 'subtitle'
+  | 'toc'
+  | 'caption'
+  | 'list'
+  | 'footnote'
+  | 'header'
+  | 'footer';
+
+export type Paragraph = {
+  type: 'paragraph';
+  role: ParagraphRole;
+  /** Heading level 1–6, or contents level 1–9. */
+  level?: number;
+  inlines: Inline[];
+  props: ParagraphProps;
+  list?: { num: number; level: number };
+  bookmark?: string;
+  /** A field that spans paragraphs — the table of contents. */
+  field?: { begin?: string; end?: boolean };
+};
+
+export type TableCell = {
+  blocks: Block[];
+  span: number;
+  merge?: 'restart' | 'continue';
+  width: number;
+  shading?: string;
+  borders: Borders;
+  /** Cell padding, twips. */
+  margins: Sides;
+  vAlign?: 'center' | 'bottom';
+};
+
+export type TableRow = { cells: TableCell[]; header: boolean };
+
+export type Table = {
+  type: 'table';
+  /** Twips, one per grid column. */
+  columns: number[];
+  rows: TableRow[];
+  align?: 'center';
+  indent?: number;
+};
+
+export type Block = Paragraph | Table;
+
+export type PageSetup = {
+  /** Twips; wider than tall is landscape. */
+  width: number;
+  height: number;
+  margin: Sides;
+  /** Distance from the top edge of the sheet to the top of the header. */
+  header: number;
+  /** Distance from the bottom edge of the sheet to the bottom of the footer. */
+  footer: number;
+};
+
+export type Section = {
+  blocks: Block[];
+  header?: Paragraph[];
+  footer?: Paragraph[];
+  /** The section's first page, when its footer is not the running one there — empty is hidden. */
+  footerFirst?: Paragraph[];
+  page: PageSetup;
+};
+
+export type Footnote = { id: number; blocks: Block[] };
+
+export type ListKind =
+  | 'disc'
+  | 'circle'
+  | 'square'
+  | 'decimal'
+  | 'lowerLetter'
+  | 'upperLetter'
+  | 'lowerRoman'
+  | 'upperRoman';
+
+export type ListInstance = { id: number; kind: ListKind; level: number; start: number };
+
+export type Media = { name: string; contentType: string; bytes: Uint8Array };
+
+export type DocxModel = {
+  title: string;
+  subject?: string;
+  author?: string;
+  /** ISO 8601. */
+  created?: string;
+  sections: Section[];
+  footnotes: Footnote[];
+  lists: ListInstance[];
+  media: Media[];
+  /** Heading sizes from the design, half-points — for levels the document never uses. */
+  headingSizes?: number[];
+  /** Page colour, when the design's paper is not white. */
+  background?: string;
+  /** Every face the runs name, with what Word should use in its place. */
+  fonts?: FontDeclaration[];
+};