@erclx/canon 5.21.0 → 5.22.0

package/src/slides/package/fonts.ts

@@ -0,0 +1,297 @@
+import type JSZip from 'jszip'
+
+/**
+ * Embeds the deck's typeface in the written package, which pptxgenjs cannot do.
+ * PowerPoint reads an embedded face as an Embedded OpenType 2.2 container
+ * around the TrueType or OpenType data, stored as `ppt/fonts/fontN.fntdata`
+ * and listed in `presentation.xml`. The header is built from the face's own
+ * `OS/2`, `head`, and `name` tables, laid out per the W3C EOT submission:
+ * https://www.w3.org/submissions/EOT/
+ */
+
+export interface EmbedFace {
+  readonly family: string
+  readonly weight: number
+  readonly style: 'normal' | 'italic'
+  /** As `deck.json` wrote it, which every notice names. */
+  readonly path: string
+  readonly bytes: Uint8Array
+}
+
+export interface FontNotice {
+  readonly path: string
+  readonly message: string
+}
+
+export type EotResult =
+  | { readonly status: 'embeddable'; readonly eot: Buffer }
+  | { readonly status: 'refused'; readonly message: string }
+
+/** `fsType` bits from the OpenType `OS/2` table. */
+const RESTRICTED = 0x0002
+const BITMAP_ONLY = 0x0200
+
+const SFNT_VERSIONS = new Set([0x00010000, 0x74727565, 0x4f54544f])
+const WRAPPED: Readonly<Record<number, string>> = {
+  0x774f4632: 'woff2',
+  0x774f4646: 'woff',
+  0x74746366: 'a font collection',
+}
+
+const UNDECODABLE = 'it could not be decoded as a TrueType or OpenType font'
+
+interface Table {
+  readonly offset: number
+  readonly length: number
+}
+
+function tables(font: Buffer): Map<string, Table> {
+  const found = new Map<string, Table>()
+  const count = font.readUInt16BE(4)
+  for (let index = 0; index < count; index += 1) {
+    const at = 12 + index * 16
+    const offset = font.readUInt32BE(at + 8)
+    const length = font.readUInt32BE(at + 12)
+    if (offset + length > font.length) throw new RangeError('table overruns')
+    found.set(font.toString('latin1', at, at + 4), { offset, length })
+  }
+  return found
+}
+
+/**
+ * The Windows platform's strings, in UTF-16, preferring US English where a
+ * face carries several languages.
+ */
+function names(font: Buffer, table: Table): Map<number, Buffer> {
+  const found = new Map<number, { language: number; bytes: Buffer }>()
+  const count = font.readUInt16BE(table.offset + 2)
+  const strings = table.offset + font.readUInt16BE(table.offset + 4)
+  for (let index = 0; index < count; index += 1) {
+    const at = table.offset + 6 + index * 12
+    if (font.readUInt16BE(at) !== 3) continue
+    const language = font.readUInt16BE(at + 4)
+    const id = font.readUInt16BE(at + 6)
+    const length = font.readUInt16BE(at + 8)
+    const start = strings + font.readUInt16BE(at + 10)
+    if (start + length > font.length) throw new RangeError('name overruns')
+    const held = found.get(id)
+    if (held && (held.language === 0x0409 || language !== 0x0409)) continue
+    const bytes = Buffer.from(font.subarray(start, start + length)).swap16()
+    found.set(id, { language, bytes })
+  }
+  return new Map([...found].map(([id, { bytes }]) => [id, bytes]))
+}
+
+function sized(bytes: Buffer = Buffer.alloc(0)): Buffer {
+  const size = Buffer.alloc(2)
+  size.writeUInt16LE(bytes.length)
+  return Buffer.concat([size, bytes])
+}
+
+function header(font: Buffer, os2: number, head: number): Buffer {
+  const fixed = Buffer.alloc(80)
+  fixed.writeUInt32LE(font.length, 4)
+  fixed.writeUInt32LE(0x00020002, 8)
+  font.copy(fixed, 16, os2 + 32, os2 + 42)
+  fixed.writeUInt8(1, 26)
+  fixed.writeUInt8(font.readUInt16BE(os2 + 62) & 1, 27)
+  fixed.writeUInt32LE(font.readUInt16BE(os2 + 4), 28)
+  fixed.writeUInt16LE(font.readUInt16BE(os2 + 8), 32)
+  fixed.writeUInt16LE(0x504c, 34)
+  for (let index = 0; index < 4; index += 1) {
+    fixed.writeUInt32LE(font.readUInt32BE(os2 + 42 + index * 4), 36 + index * 4)
+  }
+  for (let index = 0; index < 2; index += 1) {
+    fixed.writeUInt32LE(font.readUInt32BE(os2 + 78 + index * 4), 52 + index * 4)
+  }
+  fixed.writeUInt32LE(font.readUInt32BE(head + 8), 60)
+  return fixed
+}
+
+/**
+ * The EOT container around one face, or the reason it may not travel. A face
+ * whose license restricts embedding or allows a bitmap only is refused, as is
+ * a variable face, which PowerPoint does not embed. Editable and print-preview
+ * embedding both pass, since the deck is meant to be edited.
+ */
+export function eotOf(bytes: Uint8Array): EotResult {
+  const font = Buffer.from(bytes)
+  const refused = (message: string): EotResult => ({
+    status: 'refused',
+    message,
+  })
+  if (font.length < 12) return refused(UNDECODABLE)
+  const version = font.readUInt32BE(0)
+  const wrapped = WRAPPED[version]
+  if (wrapped) {
+    return refused(
+      `it is ${wrapped}. Supply the TrueType or OpenType file instead`,
+    )
+  }
+  if (!SFNT_VERSIONS.has(version)) return refused(UNDECODABLE)
+  try {
+    const found = tables(font)
+    const os2 = found.get('OS/2')
+    const head = found.get('head')
+    const name = found.get('name')
+    // Version 0 of OS/2 stops before the code page ranges the header copies.
+    if (!os2 || os2.length < 86 || !head || head.length < 12 || !name) {
+      return refused(UNDECODABLE)
+    }
+    const fsType = font.readUInt16BE(os2.offset + 8)
+    if (fsType & RESTRICTED) {
+      return refused('its license forbids embedding (fsType restricted)')
+    }
+    if (fsType & BITMAP_ONLY) {
+      return refused('its license allows bitmap embedding only (fsType 0x0200)')
+    }
+    if (found.has('fvar')) {
+      return refused(
+        'it is a variable font, which PowerPoint does not embed. Supply a static instance',
+      )
+    }
+    const strings = names(font, name)
+    const padding = Buffer.alloc(2)
+    // RootStringCheckSum, EUDCCodePage, Padding6, SignatureSize, EUDCFlags,
+    // and EUDCFontSize, all zero for a face with no root string or EUDC data.
+    const tail = Buffer.alloc(20)
+    const eot = Buffer.concat([
+      header(font, os2.offset, head.offset),
+      padding,
+      sized(strings.get(1)),
+      padding,
+      sized(strings.get(2)),
+      padding,
+      sized(strings.get(5)),
+      padding,
+      sized(strings.get(4)),
+      padding,
+      sized(),
+      tail,
+      font,
+    ])
+    eot.writeUInt32LE(eot.length, 0)
+    return { status: 'embeddable', eot }
+  } catch (error) {
+    if (error instanceof RangeError) return refused(UNDECODABLE)
+    throw error
+  }
+}
+
+type Slot = 'regular' | 'bold' | 'italic' | 'boldItalic'
+
+/** The child order `<p:embeddedFont>` requires. */
+const SLOTS: readonly Slot[] = ['regular', 'bold', 'italic', 'boldItalic']
+
+/** PowerPoint keeps four faces a family, so a weight from 600 reads as bold. */
+function slotOf(face: EmbedFace): Slot {
+  const isBold = face.weight >= 600
+  if (face.style === 'italic') return isBold ? 'boldItalic' : 'italic'
+  return isBold ? 'bold' : 'regular'
+}
+
+const FONT_RELATIONSHIP =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/font'
+const NOTES_SIZE = /<p:notesSz\b[^>]*\/>/
+
+const escapeXml = (value: string): string =>
+  value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+
+/**
+ * Embeds each face the deck lists and returns one notice per face left out.
+ * The font list goes after `<p:notesSz>`, where the schema orders it, and a
+ * package missing that anchor embeds nothing rather than placing it elsewhere.
+ */
+export async function embedFonts(
+  zip: JSZip,
+  faces: readonly EmbedFace[],
+): Promise<FontNotice[]> {
+  const notices: FontNotice[] = []
+  const families = new Map<string, Map<Slot, number>>()
+  const parts: Buffer[] = []
+
+  for (const face of faces) {
+    const result = eotOf(face.bytes)
+    if (result.status === 'refused') {
+      notices.push({ path: face.path, message: result.message })
+      continue
+    }
+    const slots = families.get(face.family) ?? new Map<Slot, number>()
+    const slot = slotOf(face)
+    if (slots.has(slot)) {
+      notices.push({
+        path: face.path,
+        message: `${face.family} already embeds a ${slot} face, and PowerPoint holds one per slot`,
+      })
+      continue
+    }
+    parts.push(result.eot)
+    slots.set(slot, parts.length)
+    families.set(face.family, slots)
+  }
+  if (parts.length === 0) return notices
+
+  const presentationPath = 'ppt/presentation.xml'
+  const relsPath = 'ppt/_rels/presentation.xml.rels'
+  const typesPath = '[Content_Types].xml'
+  const [presentation, rels, types] = await Promise.all(
+    [presentationPath, relsPath, typesPath].map(
+      async (path) => (await zip.file(path)?.async('string')) ?? '',
+    ),
+  )
+  if (!presentation || !NOTES_SIZE.test(presentation)) {
+    const message = 'the deck has no <p:notesSz> to anchor the font list after'
+    return [
+      ...notices,
+      ...faces
+        .filter((face) => !notices.some((notice) => notice.path === face.path))
+        .map((face) => ({ path: face.path, message })),
+    ]
+  }
+
+  const id = (part: number): string => `rIdCanonFont${part}`
+  parts.forEach((eot, index) => {
+    zip.file(`ppt/fonts/font${index + 1}.fntdata`, eot)
+  })
+  const relationships = parts
+    .map(
+      (_, index) =>
+        `<Relationship Id="${id(index + 1)}" Type="${FONT_RELATIONSHIP}" Target="fonts/font${index + 1}.fntdata"/>`,
+    )
+    .join('')
+  zip.file(
+    relsPath,
+    rels.replace('</Relationships>', `${relationships}</Relationships>`),
+  )
+  if (!types.includes('Extension="fntdata"')) {
+    zip.file(
+      typesPath,
+      types.replace(
+        /(<Types\b[^>]*>)/,
+        '$1<Default Extension="fntdata" ContentType="application/x-fontdata"/>',
+      ),
+    )
+  }
+  const list = [...families]
+    .map(([family, slots]) => {
+      const children = SLOTS.flatMap((slot) => {
+        const part = slots.get(slot)
+        return part ? [`<p:${slot} r:id="${id(part)}"/>`] : []
+      })
+      return `<p:embeddedFont><p:font typeface="${escapeXml(family)}"/>${children.join('')}</p:embeddedFont>`
+    })
+    .join('')
+  zip.file(
+    presentationPath,
+    presentation
+      .replace(
+        NOTES_SIZE,
+        (anchor) => `${anchor}<p:embeddedFontLst>${list}</p:embeddedFontLst>`,
+      )
+      .replace('<p:presentation ', '<p:presentation embedTrueTypeFonts="1" '),
+  )
+  return notices
+}

package/src/slides/package/motion.ts

@@ -0,0 +1,316 @@
+import type JSZip from 'jszip'
+
+/**
+ * Slide transitions and entrance animations, written into a slide's XML after
+ * pptxgenjs has written it, since pptxgenjs declares neither. A slide states
+ * them in its HTML, `walk.ts` reads the attributes, and the converter resolves
+ * each animated element to the object names `planSlide` gave its shapes. This
+ * module turns those names into the shape ids the written XML assigned.
+ */
+
+export interface TransitionSpec {
+  readonly effect: string
+  readonly duration?: string
+}
+
+export interface EntranceSpec {
+  /** The element that declared it, which every notice names. */
+  readonly selector: string
+  readonly effect: string
+  readonly order?: string
+  readonly duration?: string
+  /** Every shape drawn from the element and the elements inside it. */
+  readonly shapes: readonly string[]
+}
+
+export interface SlideMotion {
+  readonly transition?: TransitionSpec
+  readonly entrances: readonly EntranceSpec[]
+}
+
+export interface MotionResult {
+  readonly xml: string
+  readonly notices: readonly string[]
+}
+
+/** A slide's motion, numbered as the package numbers its slide parts. */
+export interface SlideMotionEdit {
+  readonly slide: number
+  readonly motion: SlideMotion
+}
+
+export interface MotionNotice {
+  readonly slide: number
+  readonly message: string
+}
+
+/** The child element `<p:transition>` holds, each in its default direction. */
+const TRANSITIONS: Readonly<Record<string, string>> = {
+  fade: '<p:fade/>',
+  push: '<p:push/>',
+  wipe: '<p:wipe/>',
+  cover: '<p:cover/>',
+}
+
+/**
+ * The strict schema states a transition's length only as one of three speeds,
+ * 0.5, 0.75, and 1 second. A length in milliseconds needs the PowerPoint 2010
+ * extension namespace, so a declared duration rounds to the nearest speed.
+ */
+function speedOf(duration: number | undefined): 'fast' | 'med' | 'slow' {
+  if (duration === undefined) return 'med'
+  if (duration < 625) return 'fast'
+  return duration < 875 ? 'med' : 'slow'
+}
+
+type Behaviors = (spid: string, duration: number, next: () => number) => string
+
+const target = (spid: string): string =>
+  `<p:tgtEl><p:spTgt spid="${spid}"/></p:tgtEl>`
+
+const animEffect =
+  (filter: string): Behaviors =>
+  (spid, duration, next) =>
+    `<p:animEffect transition="in" filter="${filter}"><p:cBhvr><p:cTn id="${next()}" dur="${duration}"/>${target(spid)}</p:cBhvr></p:animEffect>`
+
+function anim(
+  spid: string,
+  duration: number,
+  id: number,
+  attribute: string,
+  from: string,
+  to: string,
+): string {
+  return `<p:anim calcmode="lin" valueType="num"><p:cBhvr additive="base"><p:cTn id="${id}" dur="${duration}" fill="hold"/>${target(spid)}<p:attrNameLst><p:attrName>${attribute}</p:attrName></p:attrNameLst></p:cBhvr><p:tavLst><p:tav tm="0"><p:val><p:strVal val="${from}"/></p:val></p:tav><p:tav tm="100000"><p:val><p:strVal val="${to}"/></p:val></p:tav></p:tavLst></p:anim>`
+}
+
+interface Preset {
+  readonly id: number
+  readonly subtype: number
+  readonly behaviors: Behaviors
+}
+
+/**
+ * PowerPoint's own preset ids, so the effect shows by name in its animation
+ * pane. Fly comes in from the bottom and wipe from the left, the directions
+ * PowerPoint picks when none is chosen. A wipe filter names the edge the
+ * reveal starts from, so from the left pairs with `wipe(left)`.
+ */
+const ENTRANCES: Readonly<Record<string, Preset>> = {
+  fade: { id: 10, subtype: 0, behaviors: animEffect('fade') },
+  fly: {
+    id: 2,
+    subtype: 4,
+    behaviors: (spid, duration, next) =>
+      anim(spid, duration, next(), 'ppt_x', '#ppt_x', '#ppt_x') +
+      anim(spid, duration, next(), 'ppt_y', '1+#ppt_h/2', '#ppt_y'),
+  },
+  wipe: { id: 22, subtype: 8, behaviors: animEffect('wipe(left)') },
+  zoom: {
+    id: 53,
+    subtype: 16,
+    behaviors: (spid, duration, next) =>
+      anim(spid, duration, next(), 'ppt_w', '0', '#ppt_w') +
+      anim(spid, duration, next(), 'ppt_h', '0', '#ppt_h') +
+      animEffect('fade')(spid, duration, next),
+  },
+}
+
+const DEFAULT_ENTRANCE_MS = 500
+
+const ANCHOR = '</p:clrMapOvr>'
+
+const list = (names: readonly string[]): string =>
+  `${names.slice(0, -1).join(', ')}, or ${names.at(-1)}`
+
+/**
+ * The object names an entrance on `root` brings in: every shape drawn from it
+ * and from the elements inside it, so a card's box and its text arrive on one
+ * click. A descendant in `roots` declares its own entrance and keeps its
+ * subtree for that click. A record follows its parent in document order, which
+ * lets one pass collect the subtree.
+ */
+export function entranceShapes(
+  root: number | null,
+  records: readonly { readonly id: number; readonly parent: number | null }[],
+  names: readonly { readonly record: number; readonly name: string }[],
+  roots: ReadonlySet<number>,
+): string[] {
+  if (root === null) return []
+  const subtree = new Set([root])
+  for (const record of records) {
+    const isOwnEntrance = roots.has(record.id)
+    if (
+      record.parent !== null &&
+      subtree.has(record.parent) &&
+      !isOwnEntrance
+    ) {
+      subtree.add(record.id)
+    }
+  }
+  return names
+    .filter((named) => subtree.has(named.record))
+    .map((named) => named.name)
+}
+
+/** Milliseconds from `500`, `500ms`, or `0.5s`, or undefined when unreadable. */
+export function millisecondsOf(value: string | undefined): number | undefined {
+  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s)?\s*$/.exec(value ?? '')
+  if (!match?.[1]) return undefined
+  const amount = Number(match[1])
+  return Math.round(match[2] === 's' ? amount * 1000 : amount)
+}
+
+/**
+ * pptxgenjs numbers a table `n * slideNumber + 1` and every other shape by its
+ * index plus two, so a table can share an id with a shape beside it. A timing
+ * target has to name one shape, so each repeat after the first takes a fresh id.
+ */
+function uniqueIds(xml: string): string {
+  const pattern = /<p:cNvPr id="(\d+)"/g
+  let highest = Math.max(
+    0,
+    ...[...xml.matchAll(pattern)].map((match) => Number(match[1])),
+  )
+  const seen = new Set<string>()
+  return xml.replace(pattern, (whole, id: string) => {
+    if (!seen.has(id)) {
+      seen.add(id)
+      return whole
+    }
+    highest += 1
+    return `<p:cNvPr id="${highest}"`
+  })
+}
+
+function shapeIds(xml: string): Map<string, string> {
+  const ids = new Map<string, string>()
+  for (const [, id, name] of xml.matchAll(
+    /<p:cNvPr id="(\d+)" name="([^"]*)"/g,
+  )) {
+    if (id && name && !ids.has(name)) ids.set(name, id)
+  }
+  return ids
+}
+
+interface Click {
+  readonly preset: Preset
+  readonly duration: number
+  readonly spids: readonly string[]
+}
+
+function timingXml(clicks: readonly Click[]): string {
+  let counter = 2
+  const next = (): number => {
+    counter += 1
+    return counter
+  }
+  const pars = clicks.map((click) => {
+    const outer = next()
+    const inner = next()
+    const effects = click.spids.map((spid, index) => {
+      const nodeType = index === 0 ? 'clickEffect' : 'withEffect'
+      const effect = next()
+      const visible = `<p:set><p:cBhvr><p:cTn id="${next()}" dur="1" fill="hold"><p:stCondLst><p:cond delay="0"/></p:stCondLst></p:cTn>${target(spid)}<p:attrNameLst><p:attrName>style.visibility</p:attrName></p:attrNameLst></p:cBhvr><p:to><p:strVal val="visible"/></p:to></p:set>`
+      const behaviors = click.preset.behaviors(spid, click.duration, next)
+      return `<p:par><p:cTn id="${effect}" presetID="${click.preset.id}" presetClass="entr" presetSubtype="${click.preset.subtype}" fill="hold" nodeType="${nodeType}"><p:stCondLst><p:cond delay="0"/></p:stCondLst><p:childTnLst>${visible}${behaviors}</p:childTnLst></p:cTn></p:par>`
+    })
+    return `<p:par><p:cTn id="${outer}" fill="hold"><p:stCondLst><p:cond delay="indefinite"/></p:stCondLst><p:childTnLst><p:par><p:cTn id="${inner}" fill="hold"><p:stCondLst><p:cond delay="0"/></p:stCondLst><p:childTnLst>${effects.join('')}</p:childTnLst></p:cTn></p:par></p:childTnLst></p:cTn></p:par>`
+  })
+  return `<p:timing><p:tnLst><p:par><p:cTn id="1" dur="indefinite" restart="never" nodeType="tmRoot"><p:childTnLst><p:seq concurrent="1" nextAc="seek"><p:cTn id="2" dur="indefinite" nodeType="mainSeq"><p:childTnLst>${pars.join('')}</p:childTnLst></p:cTn><p:prevCondLst><p:cond evt="onPrev" delay="0"><p:tgtEl><p:sldTgt/></p:tgtEl></p:cond></p:prevCondLst><p:nextCondLst><p:cond evt="onNext" delay="0"><p:tgtEl><p:sldTgt/></p:tgtEl></p:cond></p:nextCondLst></p:seq></p:childTnLst></p:cTn></p:par></p:tnLst></p:timing>`
+}
+
+/** Declared order first, then document order for ties and for no order. */
+function ordered(entrances: readonly EntranceSpec[]): EntranceSpec[] {
+  const rank = (entrance: EntranceSpec): number => {
+    const order = Number.parseFloat(entrance.order ?? '')
+    return Number.isFinite(order) ? order : Number.POSITIVE_INFINITY
+  }
+  return entrances.toSorted((a, b) => rank(a) - rank(b))
+}
+
+/**
+ * Inserts the transition and an on-click main sequence after the slide's color
+ * map override, where the schema orders them. Each entrance is one click, and
+ * every shape drawn from its element comes in on that click together. A slide
+ * missing the anchor is returned unchanged rather than patched elsewhere.
+ */
+export function addMotion(xml: string, motion: SlideMotion): MotionResult {
+  const notices: string[] = []
+  let transition = ''
+  if (motion.transition) {
+    const element = TRANSITIONS[motion.transition.effect]
+    if (element) {
+      const speed = speedOf(millisecondsOf(motion.transition.duration))
+      transition = `<p:transition spd="${speed}">${element}</p:transition>`
+    } else {
+      notices.push(
+        `unknown transition ${motion.transition.effect}. Use ${list(Object.keys(TRANSITIONS))}`,
+      )
+    }
+  }
+
+  const numbered = uniqueIds(xml)
+  const ids = shapeIds(numbered)
+  const clicks: Click[] = []
+  for (const entrance of ordered(motion.entrances)) {
+    const preset = ENTRANCES[entrance.effect]
+    if (!preset) {
+      notices.push(
+        `${entrance.selector}: unknown entrance ${entrance.effect}. Use ${list(Object.keys(ENTRANCES))}`,
+      )
+      continue
+    }
+    const spids = entrance.shapes.flatMap((name) => {
+      const id = ids.get(name)
+      return id ? [id] : []
+    })
+    if (spids.length === 0) {
+      notices.push(
+        `${entrance.selector}: draws no shape, so its entrance has nothing to animate`,
+      )
+      continue
+    }
+    const duration = millisecondsOf(entrance.duration) ?? DEFAULT_ENTRANCE_MS
+    clicks.push({ preset, duration, spids })
+  }
+
+  const timing = clicks.length > 0 ? timingXml(clicks) : ''
+  if (!transition && !timing) return { xml, notices }
+  if (!xml.includes(ANCHOR)) {
+    return {
+      xml,
+      notices: [
+        ...notices,
+        `no ${ANCHOR} to anchor motion after, so none was written`,
+      ],
+    }
+  }
+  return {
+    xml: (timing ? numbered : xml).replace(
+      ANCHOR,
+      `${ANCHOR}${transition}${timing}`,
+    ),
+    notices,
+  }
+}
+
+/** Writes each slide's motion into the opened package and returns its notices. */
+export async function writeMotion(
+  zip: JSZip,
+  edits: readonly SlideMotionEdit[],
+): Promise<MotionNotice[]> {
+  const notices: MotionNotice[] = []
+  for (const { slide, motion } of edits) {
+    const path = `ppt/slides/slide${slide}.xml`
+    const xml = await zip.file(path)?.async('string')
+    if (xml === undefined) {
+      notices.push({ slide, message: `no ${path} in the written deck` })
+      continue
+    }
+    const result = addMotion(xml, motion)
+    if (result.xml !== xml) zip.file(path, result.xml)
+    notices.push(...result.notices.map((message) => ({ slide, message })))
+  }
+  return notices
+}