@erclx/canon 5.19.0 → 5.21.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,7 +35,10 @@ import {
   type RefusedLink,
 } from '@/slides/convert/shapes'
 import {
+  type BandOverride,
   ID_ATTRIBUTE,
+  readTheme,
+  type SlideMeta,
   type WalkedSlide,
   walkSlide,
 } from '@/slides/convert/walk'
@@ -22,7 +47,8 @@ import {
  * 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.
  *
  * 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 +71,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 +93,9 @@ export type ExportResult =
       readonly slideCount: number
       readonly fallbacks: readonly SlideFallback[]
       readonly refusedLinks: readonly SlideRefusedLink[]
+      readonly refusedCharts: readonly RefusedChart[]
+      /** What the deck master could not take from the project's tokens. */
+      readonly notices: readonly string[]
     }
   | {
       readonly status: 'refused'
@@ -102,6 +139,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 +167,35 @@ 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 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,12 +206,48 @@ export async function exportHtmlDeck(
       refusedLinks.push(
         ...plan.refusedLinks.map((each) => ({ ...each, slide: slideNumber })),
       )
-      const slide = pptx.addSlide()
-      slide.background = { color: walked.background.hex }
+      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 [opIndex, op] of plan.ops.entries()) {
         const name = `canon-${slideNumber}-${opIndex + 1}`
         await draw(page, slide, { slide: slideNumber, name }, 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)
+    }
+    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(
@@ -164,12 +262,12 @@ export async function exportHtmlDeck(
   if (!(written instanceof Uint8Array)) {
     return refused('export-failed', 'pptxgenjs returned no buffer')
   }
-  const deck = await applyPatches(written, patches)
+  const patched = await applyPatches(written, patches)
 
   mkdirSync(outDir, { recursive: true })
   const fileName = `${basename(sourceDir)}.pptx`
   const pptxPath = join(outDir, fileName)
-  writeFileSync(pptxPath, deck)
+  writeFileSync(pptxPath, patched)
 
   let mirrorPath: string | undefined
   if (options.mirror) {
@@ -185,9 +283,113 @@ export async function exportHtmlDeck(
     slideCount: files.length,
     fallbacks,
     refusedLinks,
+    refusedCharts,
+    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 +399,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 +417,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> {

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) }
+      : {}),
+  }
+}

package/src/slides/convert/shapes.ts

@@ -150,7 +150,7 @@ const PT_PER_PX = 0.75
 const inches = (px: number): number => px / PX_PER_INCH
 const points = (px: number): number => px * PT_PER_PX
 
-function position(box: Rect): PptxGenJS.PositionProps {
+export function position(box: Rect): PptxGenJS.PositionProps {
   return {
     x: inches(box.x),
     y: inches(box.y),