@erclx/canon 5.20.0 → 5.21.0

package/src/slides/convert/chart.ts

@@ -0,0 +1,165 @@
+import type PptxGenJS from 'pptxgenjs'
+import { position, type Rect } from '@/slides/convert/shapes'
+
+/**
+ * A `<figure data-chart="...">` holding a `<table>` lands as a native chart.
+ * The table stays the page's accessible source and is not also drawn. Its
+ * header row names the series and its first column names the categories.
+ */
+
+export const CHART_TYPES = ['bar', 'line', 'area', 'pie', 'doughnut'] as const
+export type ChartType = (typeof CHART_TYPES)[number]
+
+export interface ChartRecord {
+  readonly selector: string
+  readonly box: Rect
+  /** The raw `data-chart` value, checked against `CHART_TYPES` here. */
+  readonly type: string
+  readonly hasLabels: boolean
+  /** The figure's `<figcaption>`, when it has one. */
+  readonly title?: string
+  readonly rows: readonly (readonly string[])[]
+}
+
+export interface ChartTheme {
+  /** Series colors in order, repeated past the last. */
+  readonly colors: readonly string[]
+  readonly ink: string
+  readonly muted: string
+  readonly face: string
+}
+
+export interface ChartSeries {
+  readonly name: string
+  readonly labels: readonly string[]
+  /** `null` is an empty cell, which the chart draws as a gap. */
+  readonly values: readonly (number | null)[]
+}
+
+export type ChartPlan =
+  | {
+      readonly status: 'chart'
+      readonly type: ChartType
+      readonly data: readonly ChartSeries[]
+      readonly options: PptxGenJS.IChartOpts
+    }
+  | {
+      readonly status: 'refused'
+      readonly selector: string
+      readonly message: string
+    }
+
+export interface ColorRole {
+  readonly name: string
+  readonly hex: string
+}
+
+/** The grounds a series would vanish into. */
+const GROUND_ROLES = new Set(['--color-background', '--color-surface'])
+
+const NUMBER = /^-?(\d+\.?\d*|\.\d+)$/
+
+/**
+ * A comma counts as a thousands separator only where it groups in threes, so a
+ * comma-decimal `3,5` refuses rather than reading as 35.
+ */
+const GROUPED = /^-?\d{1,3}(,\d{3})+(\.\d+)?$/
+
+const isChartType = (value: string): value is ChartType =>
+  (CHART_TYPES as readonly string[]).includes(value)
+
+/**
+ * The accent, then every other declared color role in token order except the
+ * grounds, each color once. No project declares a chart palette, so the
+ * project's own roles stand in for one.
+ */
+export function seriesColors(
+  accent: string,
+  roles: readonly ColorRole[],
+): string[] {
+  const colors = [accent]
+  for (const role of roles) {
+    if (GROUND_ROLES.has(role.name) || colors.includes(role.hex)) continue
+    colors.push(role.hex)
+  }
+  return colors
+}
+
+function cycle(colors: readonly string[], count: number): string[] {
+  return Array.from(
+    { length: count },
+    (_, index) => colors[index % colors.length] ?? '',
+  )
+}
+
+export function planChart(record: ChartRecord, theme: ChartTheme): ChartPlan {
+  const refuse = (message: string): ChartPlan => ({
+    status: 'refused',
+    selector: record.selector,
+    message,
+  })
+  if (!isChartType(record.type)) {
+    return refuse(
+      `data-chart "${record.type}" is not one of ${CHART_TYPES.join(', ')}`,
+    )
+  }
+  const [header = [], ...body] = record.rows
+  if (header.length < 2 || body.length === 0) {
+    return refuse(
+      'the table needs a header row and at least one data row of two cells',
+    )
+  }
+
+  const labels = body.map((row) => row[0] ?? '')
+  const data: ChartSeries[] = []
+  for (let column = 1; column < header.length; column += 1) {
+    const values: (number | null)[] = []
+    for (const [index, row] of body.entries()) {
+      const text = (row[column] ?? '').trim()
+      if (text === '') {
+        values.push(null)
+        continue
+      }
+      const bare = GROUPED.test(text) ? text.replace(/,/g, '') : text
+      if (!NUMBER.test(bare)) {
+        return refuse(
+          `cell "${text}" at row ${index + 2}, column ${column + 1} is not a number`,
+        )
+      }
+      values.push(Number(bare))
+    }
+    data.push({ name: header[column] ?? '', labels, values })
+  }
+
+  const isRound = record.type === 'pie' || record.type === 'doughnut'
+  return {
+    status: 'chart',
+    type: record.type,
+    data,
+    options: {
+      ...position(record.box),
+      chartColors: cycle(theme.colors, isRound ? labels.length : data.length),
+      displayBlanksAs: 'gap',
+      showValue: record.hasLabels,
+      dataLabelColor: theme.ink,
+      dataLabelFontFace: theme.face,
+      showLegend: isRound || data.length > 1,
+      legendPos: 'b',
+      legendColor: theme.ink,
+      legendFontFace: theme.face,
+      catAxisLabelColor: theme.muted,
+      catAxisLabelFontFace: theme.face,
+      valAxisLabelColor: theme.muted,
+      valAxisLabelFontFace: theme.face,
+      ...(record.title
+        ? {
+            showTitle: true,
+            title: record.title,
+            titleColor: theme.ink,
+            titleFontFace: theme.face,
+            altText: record.title,
+          }
+        : {}),
+    },
+  }
+}

package/src/slides/convert/deck.ts

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+/**
+ * What belongs to the deck rather than to one slide, read from `deck.json`
+ * beside the slides. A slide overrides a band through attributes on its own
+ * `<body>`, which `walk.ts` reads.
+ */
+
+export const DECK_FILE = 'deck.json'
+
+export const BAND_SLOTS = ['left', 'center', 'right'] as const
+export type BandSlot = (typeof BAND_SLOTS)[number]
+
+export interface Band {
+  readonly show: boolean
+  readonly left?: string
+  readonly center?: string
+  readonly right?: string
+}
+
+export interface DeckConfig {
+  readonly title: string
+  readonly header: Band
+  readonly footer: Band
+  /** Drawn at the right of the footer, so they show only where it does. */
+  readonly slideNumbers: boolean
+  /** Absolute, resolved against the deck folder. */
+  readonly mark?: string
+}
+
+export type DeckRead =
+  | { readonly status: 'read'; readonly deck: DeckConfig }
+  | {
+      readonly status: 'refused'
+      readonly field: string
+      readonly message: string
+    }
+
+const DECK_FIELDS = new Set([
+  'title',
+  'header',
+  'footer',
+  'slideNumbers',
+  'mark',
+])
+const BAND_FIELDS = new Set<string>(['show', ...BAND_SLOTS])
+
+class FieldError extends Error {
+  constructor(
+    readonly field: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function rejectUnknown(
+  record: Record<string, unknown>,
+  known: ReadonlySet<string>,
+  prefix: string,
+): void {
+  const unknown = Object.keys(record).find((key) => !known.has(key))
+  if (unknown !== undefined) {
+    throw new FieldError(
+      `${prefix}${unknown}`,
+      `unknown field ${prefix}${unknown}`,
+    )
+  }
+}
+
+function stringField(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string') {
+    throw new FieldError(field, `${field} must be a string`)
+  }
+  return value
+}
+
+function booleanField(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'boolean') {
+    throw new FieldError(field, `${field} must be true or false`)
+  }
+  return value
+}
+
+/**
+ * A declared band merges over its default, so `{ "center": "x" }` keeps the
+ * footer's title on the left. Declaring any text turns a band on unless it
+ * also says `show: false`.
+ */
+function band(value: unknown, field: string, fallback: Band): Band {
+  if (value === undefined) return fallback
+  if (!isRecord(value)) {
+    throw new FieldError(field, `${field} must be an object`)
+  }
+  rejectUnknown(value, BAND_FIELDS, `${field}.`)
+  const slots: { -readonly [slot in BandSlot]?: string } = {}
+  for (const slot of BAND_SLOTS) {
+    const text = stringField(value[slot], `${field}.${slot}`)
+    if (text !== undefined) slots[slot] = text
+  }
+  const show =
+    booleanField(value.show, `${field}.show`) ??
+    (Object.keys(slots).length > 0 || fallback.show)
+  return { ...fallback, ...slots, show }
+}
+
+function parse(raw: unknown, folder: string): DeckConfig {
+  if (!isRecord(raw)) {
+    throw new FieldError(DECK_FILE, `${DECK_FILE} must hold an object`)
+  }
+  rejectUnknown(raw, DECK_FIELDS, '')
+  const title = stringField(raw.title, 'title') ?? basename(folder)
+  const header = band(raw.header, 'header', { show: false })
+  const footer = band(raw.footer, 'footer', { show: true, left: title })
+  const slideNumbers = booleanField(raw.slideNumbers, 'slideNumbers') ?? true
+  if (slideNumbers && footer.right !== undefined) {
+    throw new FieldError(
+      'footer.right',
+      'footer.right is where slide numbers sit. Set slideNumbers to false to use it',
+    )
+  }
+  const markPath = stringField(raw.mark, 'mark')
+  let mark: string | undefined
+  if (markPath !== undefined) {
+    mark = join(folder, markPath)
+    if (!existsSync(mark) || !statSync(mark).isFile()) {
+      throw new FieldError('mark', `mark ${mark} does not exist`)
+    }
+  }
+  return { title, header, footer, slideNumbers, mark }
+}
+
+export function readDeck(folder: string): DeckRead {
+  const path = join(folder, DECK_FILE)
+  let raw: unknown = {}
+  if (existsSync(path)) {
+    try {
+      raw = JSON.parse(readFileSync(path, 'utf8'))
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      return {
+        status: 'refused',
+        field: DECK_FILE,
+        message: `${path}: not valid JSON (${reason})`,
+      }
+    }
+  }
+  try {
+    return { status: 'read', deck: parse(raw, folder) }
+  } catch (error) {
+    if (!(error instanceof FieldError)) throw error
+    return {
+      status: 'refused',
+      field: error.field,
+      message: `${path}: ${error.message}`,
+    }
+  }
+}

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> {