@erclx/canon 5.20.0 → 5.22.0

package/src/slides/convert/export.ts

@@ -1,4 +1,10 @@
-import { copyFileSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import {
+  copyFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs'
 import { basename, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import JSZip from 'jszip'
@@ -6,6 +12,22 @@ import type { Browser, Page } from 'playwright-core'
 import PptxGenJS from 'pptxgenjs'
 import { isBrowserMissing, isEngineMissing } from '@/browser/engine'
 import { resolveFrameTokens } from '@/canvas/tokens'
+import {
+  type ChartTheme,
+  planChart,
+  seriesColors,
+} from '@/slides/convert/chart'
+import { type DeckConfig, readDeck } from '@/slides/convert/deck'
+import {
+  bandTexts,
+  buildMaster,
+  type DeckTheme,
+  deckTheme,
+  type MarkSize,
+  type MasterBands,
+  masterName,
+  slideNumberProps,
+} from '@/slides/convert/master'
 import {
   type DrawOp,
   type Fallback,
@@ -13,16 +35,30 @@ import {
   type RefusedLink,
 } from '@/slides/convert/shapes'
 import {
+  type BandOverride,
   ID_ATTRIBUTE,
+  readTheme,
+  type SlideMeta,
   type WalkedSlide,
   walkSlide,
 } from '@/slides/convert/walk'
+import { embedFonts, type FontNotice } from '@/slides/package/fonts'
+import {
+  type EntranceSpec,
+  entranceShapes,
+  type MotionNotice,
+  type SlideMotionEdit,
+  writeMotion,
+} from '@/slides/package/motion'
 
 /**
  * Turns a folder of HTML slides into one editable deck. Chromium lays each
  * slide out at 1280 by 720 in the project's tokens, `walkSlide` reads what it
  * placed, `planSlide` maps the records onto shapes, and an element whose CSS has
- * no mapping lands as a screenshot of itself.
+ * no mapping lands as a screenshot of itself. The first slide's computed tokens
+ * build the masters, and `deck.json` sets the bands they carry. Once pptxgenjs
+ * has written the package, `src/slides/package/` adds the transitions,
+ * entrances, and embedded faces it declares nothing for.
  *
  * Every browser reference this feature adds lives here, and the command reaches
  * it through a dynamic import so no other command resolves the engine.
@@ -45,8 +81,16 @@ export interface SlideRefusedLink extends RefusedLink {
   readonly slide: number
 }
 
+/** A chart left out of the deck, with the reason the report prints. */
+export interface RefusedChart {
+  readonly slide: number
+  readonly selector: string
+  readonly message: string
+}
+
 export type ExportRefusal =
   | 'empty-source'
+  | 'deck-invalid'
   | 'engine-missing'
   | 'browser-missing'
   | 'export-failed'
@@ -59,6 +103,13 @@ export type ExportResult =
       readonly slideCount: number
       readonly fallbacks: readonly SlideFallback[]
       readonly refusedLinks: readonly SlideRefusedLink[]
+      readonly refusedCharts: readonly RefusedChart[]
+      /** Transitions and entrances left out, each with the reason. */
+      readonly refusedMotion: readonly MotionNotice[]
+      /** Faces `deck.json` lists that the deck does not carry, with the reason. */
+      readonly refusedFonts: readonly FontNotice[]
+      /** What the deck master could not take from the project's tokens. */
+      readonly notices: readonly string[]
     }
   | {
       readonly status: 'refused'
@@ -102,6 +153,11 @@ export async function exportHtmlDeck(
   if (files.length === 0) {
     return refused('empty-source', `${sourceDir} holds no .html slides`)
   }
+  const deckRead = readDeck(sourceDir)
+  if (deckRead.status === 'refused') {
+    return refused('deck-invalid', deckRead.message)
+  }
+  const deck = deckRead.deck
 
   let chromium: typeof import('playwright-core').chromium
   try {
@@ -125,15 +181,36 @@ export async function exportHtmlDeck(
   const tokens = resolveFrameTokens(options.root).css
   const pptx = new PptxGenJS()
   pptx.layout = 'LAYOUT_WIDE'
+  pptx.title = deck.title
   const fallbacks: SlideFallback[] = []
   const refusedLinks: SlideRefusedLink[] = []
+  const refusedCharts: RefusedChart[] = []
   const patches: Patch[] = []
+  const motions: SlideMotionEdit[] = []
+  const notices: string[] = []
 
   try {
     const page = await browser.newPage({
       viewport: { width: SLIDE_WIDTH, height: SLIDE_HEIGHT },
       deviceScaleFactor: SCREENSHOT_SCALE,
     })
+    await prepare(page, files[0] ?? '', tokens)
+    const reading = await page.evaluate(readTheme)
+    const read = deckTheme(reading)
+    const theme = read.theme
+    notices.push(...read.notices)
+    const drifted: number[] = []
+    const chartTheme: ChartTheme = {
+      colors: seriesColors(theme.accent, reading.roles),
+      ink: theme.ink,
+      muted: theme.muted,
+      face: theme.face,
+    }
+    pptx.theme = { headFontFace: theme.face, bodyFontFace: theme.face }
+    const markSize = deck.mark ? await measure(page, deck.mark) : undefined
+    const masters = new Set<string>()
+    const sections = new Sections(deck.title, declaresSections(files))
+
     for (const [index, file] of files.entries()) {
       const slideNumber = index + 1
       const walked = await layOut(page, file, tokens)
@@ -144,13 +221,66 @@ export async function exportHtmlDeck(
       refusedLinks.push(
         ...plan.refusedLinks.map((each) => ({ ...each, slide: slideNumber })),
       )
-      const slide = pptx.addSlide()
-      slide.background = { color: walked.background.hex }
-      for (const [opIndex, op] of plan.ops.entries()) {
-        const name = `canon-${slideNumber}-${opIndex + 1}`
-        await draw(page, slide, { slide: slideNumber, name }, op, patches)
+      const { textToken } = walked.meta
+      if (textToken !== undefined && textToken !== theme.ink) {
+        drifted.push(slideNumber)
+      }
+      // pptxgenjs binds a slide to its master at creation, so the bands this
+      // slide keeps decide the master before any shape is added.
+      const bands = masterBands(deck, walked.meta)
+      const master = masterName(bands)
+      if (!masters.has(master)) {
+        pptx.defineSlideMaster(buildMaster(deck, theme, bands, markSize))
+        masters.add(master)
+      }
+      const sectionTitle = sections.titleFor(walked.meta, pptx)
+      const slide = pptx.addSlide({
+        masterName: master,
+        ...(sectionTitle ? { sectionTitle } : {}),
+      })
+      if (walked.background.hex !== theme.background) {
+        slide.background = { color: walked.background.hex }
+      }
+      if (walked.meta.isHidden) slide.hidden = true
+      for (const op of plan.ops) {
+        await draw(page, slide, slideNumber, op, patches)
+      }
+      for (const record of walked.charts) {
+        const chart = planChart(record, chartTheme)
+        if (chart.status === 'refused') {
+          refusedCharts.push({ ...chart, slide: slideNumber })
+          continue
+        }
+        slide.addChart(chart.type, [...chart.data], chart.options)
+      }
+      drawOverrides(slide, deck, theme, walked.meta)
+      if (walked.meta.notes) slide.addNotes(walked.meta.notes)
+      const { transition } = walked.meta
+      const roots = new Set(
+        walked.entrances.flatMap(({ record }) =>
+          record === null ? [] : [record],
+        ),
+      )
+      const entrances = walked.entrances.map(
+        ({ record, ...spec }): EntranceSpec => ({
+          ...spec,
+          shapes: entranceShapes(record, walked.records, plan.names, roots),
+        }),
+      )
+      if (transition || entrances.length > 0) {
+        motions.push({
+          slide: slideNumber,
+          motion: { ...(transition ? { transition } : {}), entrances },
+        })
       }
     }
+    if (drifted.length > 0) {
+      const noun = drifted.length === 1 ? 'slide' : 'slides'
+      const verb = drifted.length === 1 ? 'sets' : 'set'
+      notices.push(
+        `${noun} ${drifted.join(', ')} ${verb} a --color-text apart from the master, so ${drifted.length === 1 ? 'its' : 'their'} bands keep the master colors`,
+      )
+    }
   } catch (error) {
     return refused(
       'export-failed',
@@ -164,12 +294,32 @@ export async function exportHtmlDeck(
   if (!(written instanceof Uint8Array)) {
     return refused('export-failed', 'pptxgenjs returned no buffer')
   }
-  const deck = await applyPatches(written, patches)
+  // A deck needing no edit keeps the bytes pptxgenjs wrote.
+  let packaged: Uint8Array = written
+  const refusedMotion: MotionNotice[] = []
+  const refusedFonts: FontNotice[] = []
+  if (patches.length > 0 || motions.length > 0 || deck.fonts.length > 0) {
+    const zip = await JSZip.loadAsync(written)
+    await applyPatches(zip, patches)
+    refusedMotion.push(...(await writeMotion(zip, motions)))
+    const faces = deck.fonts.map((font) => ({
+      family: font.family,
+      weight: font.weight,
+      style: font.style,
+      path: font.source,
+      bytes: readFileSync(font.path),
+    }))
+    refusedFonts.push(...(await embedFonts(zip, faces)))
+    packaged = await zip.generateAsync({
+      type: 'nodebuffer',
+      compression: 'DEFLATE',
+    })
+  }
 
   mkdirSync(outDir, { recursive: true })
   const fileName = `${basename(sourceDir)}.pptx`
   const pptxPath = join(outDir, fileName)
-  writeFileSync(pptxPath, deck)
+  writeFileSync(pptxPath, packaged)
 
   let mirrorPath: string | undefined
   if (options.mirror) {
@@ -185,9 +335,115 @@ export async function exportHtmlDeck(
     slideCount: files.length,
     fallbacks,
     refusedLinks,
+    refusedCharts,
+    refusedMotion,
+    refusedFonts,
+    notices,
   }
 }
 
+/**
+ * A band stays on the master unless the deck has it off anyway, so a slide
+ * hiding only the header keeps the master's footer and numbers.
+ */
+function masterBands(deck: DeckConfig, meta: SlideMeta): MasterBands {
+  return {
+    header: deck.header.show && meta.header.kind === 'master',
+    footer: deck.footer.show && meta.footer.kind === 'master',
+  }
+}
+
+type Override = Extract<BandOverride, { readonly kind: 'override' }>
+
+/** The slide's slots over the deck's, so overriding the center keeps the title. */
+function mergeBand(override: Override, base: DeckConfig['header']) {
+  return {
+    left: override.left ?? base.left,
+    center: override.center ?? base.center,
+    right: override.right ?? base.right,
+  }
+}
+
+function drawOverrides(
+  slide: PptxGenJS.Slide,
+  deck: DeckConfig,
+  theme: DeckTheme,
+  meta: SlideMeta,
+): void {
+  if (meta.header.kind === 'override') {
+    const band = mergeBand(meta.header, deck.header)
+    const hasMark = deck.mark !== undefined
+    for (const text of bandTexts(band, 'header', theme, { hasMark })) {
+      slide.addText(text.text, text.options)
+    }
+  }
+  if (meta.footer.kind === 'override') {
+    const band = mergeBand(meta.footer, deck.footer)
+    for (const text of bandTexts(band, 'footer', theme)) {
+      slide.addText(text.text, text.options)
+    }
+    if (deck.slideNumbers && band.right === undefined) {
+      slide.slideNumber = slideNumberProps(theme)
+    }
+  }
+}
+
+/**
+ * A slide's `data-section` opens a section the slides after it stay in.
+ * PowerPoint wants every slide in a section once any exists, so slides ahead of
+ * the first declared one open a section named after the deck.
+ *
+ * pptxgenjs files a slide under the first section carrying its title, so a
+ * title the deck returns to takes a numbered suffix rather than sending the
+ * slide back into the earlier section, which PowerPoint reads as a broken list.
+ */
+export class Sections {
+  /** The title as declared, and as written once a repeat is numbered. */
+  private declared: string | undefined
+  private current: string | undefined
+  private readonly opened = new Map<string, number>()
+
+  constructor(
+    private readonly deckTitle: string,
+    private readonly isUsed: boolean,
+  ) {}
+
+  titleFor(meta: SlideMeta, pptx: PptxGenJS): string | undefined {
+    if (!this.isUsed) return undefined
+    const isContinuing =
+      meta.section === undefined || meta.section === this.declared
+    if (isContinuing && this.current !== undefined) return this.current
+    const title = meta.section ?? this.deckTitle
+    const count = (this.opened.get(title) ?? 0) + 1
+    this.opened.set(title, count)
+    this.declared = title
+    this.current = count === 1 ? title : `${title} (${count})`
+    pptx.addSection({ title: this.current })
+    return this.current
+  }
+}
+
+/**
+ * Whether any slide declares a section, read from the source ahead of layout,
+ * since the first slide is placed before the last is laid out.
+ */
+function declaresSections(files: readonly string[]): boolean {
+  return files.some((file) =>
+    /<body\b[^>]*\sdata-section\s*=/i.test(readFileSync(file, 'utf8')),
+  )
+}
+
+/** The mark's intrinsic size as Chromium decodes it, square where unknown. */
+async function measure(page: Page, path: string): Promise<MarkSize> {
+  const size = await page.evaluate(async (src) => {
+    const image = new Image()
+    image.src = src
+    await image.decode().catch(() => undefined)
+    return { width: image.naturalWidth, height: image.naturalHeight }
+  }, pathToFileURL(path).href)
+  return size.width > 0 && size.height > 0 ? size : { width: 1, height: 1 }
+}
+
 /**
  * The tokens go in ahead of the slide's own styles, so a slide reads
  * `var(--color-*)` from the project and can still override any of it.
@@ -197,6 +453,15 @@ async function layOut(
   file: string,
   tokens: string,
 ): Promise<WalkedSlide> {
+  await prepare(page, file, tokens)
+  return page.evaluate(walkSlide, ID_ATTRIBUTE)
+}
+
+async function prepare(
+  page: Page,
+  file: string,
+  tokens: string,
+): Promise<void> {
   await page.goto(pathToFileURL(file).href, { waitUntil: 'load' })
   if (tokens) {
     await page.evaluate((css) => {
@@ -206,7 +471,6 @@ async function layOut(
     }, tokens)
   }
   await page.evaluate(() => document.fonts.ready.then(() => undefined))
-  return page.evaluate(walkSlide, ID_ATTRIBUTE)
 }
 
 async function screenshot(page: Page, id: number): Promise<Buffer> {
@@ -227,10 +491,11 @@ const base64 = (bytes: Buffer | string): string =>
 async function draw(
   page: Page,
   slide: PptxGenJS.Slide,
-  target: { readonly slide: number; readonly name: string },
+  slideNumber: number,
   op: DrawOp,
   patches: Patch[],
 ): Promise<void> {
+  const target = { slide: slideNumber, name: op.options.objectName ?? '' }
   if (op.kind === 'shape') {
     slide.addShape(op.shape, op.options)
   } else if (op.kind === 'text') {
@@ -238,18 +503,13 @@ async function draw(
   } else if (op.kind === 'table') {
     slide.addTable(op.rows, op.options)
   } else if (op.kind === 'image') {
-    slide.addImage({
-      ...op.options,
-      ...imageSource(op.src),
-      objectName: target.name,
-    })
+    slide.addImage({ ...op.options, ...imageSource(op.src) })
     if (op.radius > 0) patches.push({ ...target, radius: op.radius })
     if (op.frame) slide.addShape(op.radius > 0 ? 'roundRect' : 'rect', op.frame)
   } else if (op.kind === 'svg') {
     slide.addImage({
       ...op.options,
       data: `image/svg+xml;base64,${base64(op.markup)}`,
-      objectName: target.name,
     })
     patches.push({ ...target, png: await screenshot(page, op.id) })
   } else {
@@ -262,14 +522,13 @@ async function draw(
  * Two things pptxgenjs cannot write, fixed in the package it wrote. An SVG's
  * PNG fallback comes out as the SVG's own bytes under a `.png` name in Node, so
  * a viewer that cannot draw SVG gets a broken image, and a picture takes no
- * corner radius. Each patched picture is found by the object name `draw` gave
- * it, which is the only handle the written XML keeps.
+ * corner radius. Each patched picture is found by the object name `planSlide`
+ * gave it, which is the only handle the written XML keeps.
  */
 async function applyPatches(
-  deck: Uint8Array,
+  zip: JSZip,
   patches: readonly Patch[],
-): Promise<Buffer> {
-  const zip = await JSZip.loadAsync(deck)
+): Promise<void> {
   const bySlide = Map.groupBy(patches, (patch) => patch.slide)
   for (const [slideNumber, slidePatches] of bySlide) {
     const slidePath = `ppt/slides/slide${slideNumber}.xml`
@@ -294,7 +553,6 @@ async function applyPatches(
     }
     zip.file(slidePath, xml)
   }
-  return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' })
 }
 
 function pictureXml(xml: string, name: string): string | undefined {

package/src/slides/convert/master.ts

@@ -0,0 +1,195 @@
+import type PptxGenJS from 'pptxgenjs'
+import {
+  BAND_SLOTS,
+  type Band,
+  type BandSlot,
+  type DeckConfig,
+} from '@/slides/convert/deck'
+import { fontFace } from '@/slides/convert/shapes'
+
+/**
+ * The deck's master, built from the project's own tokens as the page computed
+ * them rather than from the toolkit's design module. A slide that hides or
+ * overrides a band takes a master without that band, so editing the footer
+ * once in PowerPoint reaches every slide still on the master's own.
+ */
+
+export interface DeckTheme {
+  readonly background: string
+  readonly ink: string
+  readonly muted: string
+  readonly accent: string
+  readonly face: string
+}
+
+/** What the first slide computed, read in the page by `readTheme`. */
+export interface ThemeReading {
+  /** Each role's `--color-*` value as hex, absent where none is declared. */
+  readonly tokens: {
+    readonly background?: string
+    readonly text?: string
+    readonly muted?: string
+    readonly accent?: string
+  }
+  readonly body: { readonly background: string; readonly color: string }
+  readonly fontFamily: string
+  /** Every declared `--color-*` property in sheet order, for chart series. */
+  readonly roles: readonly { readonly name: string; readonly hex: string }[]
+}
+
+export interface MasterBands {
+  readonly header: boolean
+  readonly footer: boolean
+}
+
+/** Intrinsic pixel size, which sets the mark's aspect inside its box. */
+export interface MarkSize {
+  readonly width: number
+  readonly height: number
+}
+
+const SLIDE_W = 13.333
+const MARGIN = 0.5
+const BAND_H = 0.4
+const HEADER_Y = 0.2
+const FOOTER_Y = 7.5 - 0.2 - BAND_H
+const SLOT_W = (SLIDE_W - 2 * MARGIN) / 3
+const NUMBER_W = 1
+const MARK_BOX = { w: 1.2, h: BAND_H }
+const BAND_PT = 10
+
+/**
+ * A missing role falls back to what the slide's body computed, never to the
+ * toolkit's palette, which would put Canon's colors on another project's deck.
+ */
+export function deckTheme(reading: ThemeReading): {
+  readonly theme: DeckTheme
+  readonly notices: readonly string[]
+} {
+  const { tokens, body } = reading
+  const missing = (
+    [
+      ['background', tokens.background],
+      ['text', tokens.text],
+      ['muted', tokens.muted],
+      ['accent', tokens.accent],
+    ] as const
+  )
+    .filter(([, value]) => value === undefined)
+    .map(([role]) => `--color-${role}`)
+  return {
+    theme: {
+      background: tokens.background ?? body.background,
+      ink: tokens.text ?? body.color,
+      muted: tokens.muted ?? body.color,
+      accent: tokens.accent ?? body.color,
+      face: fontFace(reading.fontFamily),
+    },
+    notices:
+      missing.length === 0
+        ? []
+        : [
+            `no ${missing.join(' or ')} token, so the deck master takes the slide body ${missing.length === 1 ? 'color for it' : 'color for them'}`,
+          ],
+  }
+}
+
+export function masterName(bands: MasterBands): string {
+  const parts = [bands.header && 'header', bands.footer && 'footer'].filter(
+    Boolean,
+  )
+  return parts.length === 0 ? 'canon-bare' : `canon-${parts.join('-')}`
+}
+
+const SLOT_ALIGN: Record<BandSlot, PptxGenJS.HAlign> = {
+  left: 'left',
+  center: 'center',
+  right: 'right',
+}
+
+/**
+ * One text object per filled slot. The master draws these for a band it
+ * carries, and a slide overriding a band draws its own through the same call.
+ */
+export function bandTexts(
+  band: Omit<Band, 'show'>,
+  kind: 'header' | 'footer',
+  theme: DeckTheme,
+  options: { readonly hasMark?: boolean } = {},
+): { readonly text: string; readonly options: PptxGenJS.TextPropsOptions }[] {
+  return BAND_SLOTS.flatMap((slot, index) => {
+    const text = band[slot]
+    if (!text) return []
+    const isMarkSlot = kind === 'header' && slot === 'right' && options.hasMark
+    return [
+      {
+        text,
+        options: {
+          x: MARGIN + index * SLOT_W,
+          y: kind === 'header' ? HEADER_Y : FOOTER_Y,
+          w: SLOT_W - (isMarkSlot ? MARK_BOX.w + 0.1 : 0),
+          h: BAND_H,
+          margin: 0,
+          align: SLOT_ALIGN[slot],
+          valign: 'middle',
+          fontFace: theme.face,
+          fontSize: BAND_PT,
+          color: kind === 'header' ? theme.ink : theme.muted,
+        },
+      },
+    ]
+  })
+}
+
+/** The right of the footer, which `deck.json` keeps free while numbers show. */
+export function slideNumberProps(theme: DeckTheme): PptxGenJS.SlideNumberProps {
+  return {
+    x: SLIDE_W - MARGIN - NUMBER_W,
+    y: FOOTER_Y,
+    w: NUMBER_W,
+    h: BAND_H,
+    margin: 0,
+    align: 'right',
+    valign: 'middle',
+    fontFace: theme.face,
+    fontSize: BAND_PT,
+    color: theme.accent,
+  }
+}
+
+function markImage(path: string, size: MarkSize): PptxGenJS.ImageProps {
+  const scale = Math.min(MARK_BOX.w / size.width, MARK_BOX.h / size.height)
+  const w = Math.round(size.width * scale * 1000) / 1000
+  const h = Math.round(size.height * scale * 1000) / 1000
+  return { path, x: SLIDE_W - MARGIN - w, y: HEADER_Y, w, h }
+}
+
+export function buildMaster(
+  deck: DeckConfig,
+  theme: DeckTheme,
+  bands: MasterBands,
+  markSize: MarkSize = { width: 1, height: 1 },
+): PptxGenJS.SlideMasterProps {
+  const hasHeader = bands.header && deck.header.show
+  const hasFooter = bands.footer && deck.footer.show
+  const hasMark = deck.mark !== undefined
+  const objects: NonNullable<PptxGenJS.SlideMasterProps['objects']> = [
+    ...(deck.mark ? [{ image: markImage(deck.mark, markSize) }] : []),
+    ...(hasHeader
+      ? bandTexts(deck.header, 'header', theme, { hasMark }).map((text) => ({
+          text,
+        }))
+      : []),
+    ...(hasFooter
+      ? bandTexts(deck.footer, 'footer', theme).map((text) => ({ text }))
+      : []),
+  ]
+  return {
+    title: masterName(bands),
+    background: { color: theme.background },
+    objects,
+    ...(hasFooter && deck.slideNumbers
+      ? { slideNumber: slideNumberProps(theme) }
+      : {}),
+  }
+}