@codename/deck 0.0.0-stage → 0.1.0

package/src/look.js

@@ -0,0 +1,124 @@
+// A deck's look: a design system's few tokens (paper, ink, primary, a voice for its type), from a
+// named look, then the project's, then the deck's own `themeConfig`, as Slidev names a theme's
+// settings. Light and dark are both worked out from them: each colour kept at its hue, deepened or
+// lightened until it reads at AA on the paper it sits on (4.5:1 for words, 3:1 for a chart's
+// marks), so a brain's or a person's colours can't make a slide unreadable. Pure.
+
+/** @typedef {{ paper: string, ink: string, primary: string, voice: string, radius: number, muted?: string, soft?: string, dark?: Record<string, string>, fonts?: { heading: string[], body: string[] } }} Tokens */
+/** @typedef {{ paper: string, ink: string, muted: string, line: string, primary: string, onPrimary: string, soft: string, series: string[] }} Scheme */
+
+/** Looks a deck can name (`theme:`), each a handful of tokens. */
+export const LOOKS = /** @type {Record<string, Tokens>} */ ({
+  default: { paper: '#fffdf8', ink: '#1d1b16', primary: '#f7c531', voice: 'calm', radius: 10 },
+  ocean: { paper: '#f6fafb', ink: '#0d2530', primary: '#0f766e', voice: 'calm', radius: 6 },
+  ember: { paper: '#fff8f3', ink: '#2a160c', primary: '#d9480f', voice: 'bold', radius: 2 },
+  ink: { paper: '#ffffff', ink: '#111111', primary: '#3b5bdb', voice: 'elegant', radius: 0 },
+})
+
+/** Type for each voice: the device's faces, so a deck needs nothing to download to look right. */
+export const VOICES = /** @type {Record<string, { heading: string, body: string }>} */ ({
+  calm: { heading: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, "Noto Sans", sans-serif', body: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, "Noto Sans", sans-serif' },
+  elegant: { heading: 'ui-serif, "Iowan Old Style", Georgia, "Noto Serif", serif', body: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif' },
+  bold: { heading: '"Avenir Next Condensed", "Arial Narrow", ui-sans-serif, system-ui, sans-serif', body: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif' },
+  friendly: { heading: 'ui-rounded, "SF Pro Rounded", "Nunito", system-ui, sans-serif', body: 'ui-rounded, "SF Pro Rounded", system-ui, sans-serif' },
+})
+
+/**
+ * The tokens a deck's settings give, over the project's look and a named one.
+ * @param {Record<string, any>} settings @param {Partial<Tokens>} [project]
+ * @returns {Tokens}
+ */
+export function tokensOf(settings, project = {}) {
+  const named = LOOKS[String(settings.theme ?? '')] ?? LOOKS.default
+  const own = typeof settings.themeConfig === 'object' && settings.themeConfig ? settings.themeConfig : {}
+  /** @type {Tokens} */
+  const tokens = { ...named, ...clean(project), ...clean(own) }
+  if (!VOICES[tokens.voice]) tokens.voice = 'calm'
+  return tokens
+}
+
+/** @param {Record<string, any>} given @returns {Partial<Tokens>} */
+function clean(given) {
+  /** @type {Partial<Tokens>} */
+  const kept = {}
+  for (const key of /** @type {const} */ (['paper', 'ink', 'primary', 'muted', 'soft'])) if (typeof given[key] === 'string' && hex(given[key])) kept[key] = given[key]
+  if (given.dark && typeof given.dark === 'object') kept.dark = Object.fromEntries(Object.entries(given.dark).filter(([, v]) => typeof v === 'string' && hex(v)))
+  if (given.fonts && Array.isArray(given.fonts.heading) && Array.isArray(given.fonts.body)) kept.fonts = { heading: given.fonts.heading.map(String), body: given.fonts.body.map(String) }
+  if (typeof given.voice === 'string') kept.voice = given.voice
+  if (typeof given.radius === 'number') kept.radius = given.radius
+  return kept
+}
+
+/**
+ * Light or dark, worked out from the tokens: dark swaps paper and ink and lifts the primary.
+ * @param {Tokens} tokens @param {'light' | 'dark'} scheme @returns {Scheme}
+ */
+export function schemeOf(tokens, scheme) {
+  const light = hex(tokens.paper) ?? [255, 253, 248], dark = hex(tokens.ink) ?? [29, 27, 22]
+  // A kit's own dark colours where it gives them (a design system's dark mode), else worked out.
+  const own = scheme === 'dark' ? tokens.dark ?? {} : {}
+  const paper = round(hex(own.paper ?? '') ?? (scheme === 'dark' ? mix(dark, [0, 0, 0], 0.35) : light))
+  const ink = round(hex(own.ink ?? '') ?? (scheme === 'dark' ? mix(light, [255, 255, 255], 0.2) : dark))
+  const primary = hex(own.primary ?? tokens.primary) ?? [247, 197, 49]
+  // The primary as a fill keeps its own colour; as words or marks it is made to read on the paper.
+  const text = readable(primary, paper, 4.5)
+  const onPrimary = contrast(ink, primary) >= contrast(paper, primary) ? ink : paper
+  const series = [0, 1, 2, 3, 4, 5].map((n) => readable(rotate(primary, n * 57), paper, 3))
+  return {
+    paper: css(paper), ink: css(ink), muted: css(readable(round(hex(own.muted ?? (scheme === 'light' ? tokens.muted ?? '' : '')) ?? mix(ink, paper, 0.38)), paper, 4.5)), line: css(mix(ink, paper, 0.82)),
+    primary: css(text), onPrimary: css(onPrimary), soft: css(hex(own.soft ?? (scheme === 'light' ? tokens.soft ?? '' : '')) ?? mix(primary, paper, 0.78)), series: series.map(css),
+  }
+}
+
+/** @param {string} value @returns {[number, number, number] | null} */
+export function hex(value) {
+  const m = /^#?([\da-f]{3}|[\da-f]{6})$/i.exec(String(value).trim())
+  if (!m) return null
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1]
+  return /** @type {[number, number, number]} */ ([0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)))
+}
+
+/** @param {number[]} rgb */
+export const css = (rgb) => `#${rgb.map((c) => Math.round(Math.max(0, Math.min(255, c))).toString(16).padStart(2, '0')).join('')}`
+
+/** A colour as it will be written: whole numbers, so that it reads at the ratio checked. @param {number[]} c */
+const round = (c) => /** @type {[number, number, number]} */ (c.map((v) => Math.round(Math.max(0, Math.min(255, v)))))
+
+/** @param {number[]} a @param {number[]} b @param {number} t */
+const mix = (a, b, t) => /** @type {[number, number, number]} */ (a.map((c, i) => c + (b[i] - c) * t))
+
+/** @param {number[]} rgb */
+function luminance(rgb) {
+  const [r, g, b] = rgb.map((c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4 })
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/** WCAG's contrast ratio. @param {number[]} a @param {number[]} b */
+export function contrast(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p)
+  return (x + 0.05) / (y + 0.05)
+}
+
+/**
+ * The colour, its hue kept, deepened or lightened toward black or white until it reads at the
+ * ratio on the paper. @param {number[]} colour @param {number[]} paper @param {number} ratio
+ */
+export function readable(colour, paper, ratio) {
+  const toward = luminance(paper) > 0.18 ? [0, 0, 0] : [255, 255, 255]
+  let t = 0, out = round(colour)
+  while (contrast(out, paper) < ratio && t < 1) out = round(mix(colour, toward, (t = Math.min(1, t + 0.02))))
+  return out
+}
+
+/** The colour turned round the colour wheel. @param {number[]} rgb @param {number} degrees */
+function rotate(rgb, degrees) {
+  const [r, g, b] = rgb.map((c) => c / 255)
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2
+  const d = max - min
+  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1))
+  let h = d === 0 ? 0 : max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+  h = (h * 60 + degrees + 360) % 360
+  const c = (1 - Math.abs(2 * l - 1)) * Math.max(s, 0.55), x = c * (1 - Math.abs(((h / 60) % 2) - 1)), m = l - c / 2
+  const [p, q, u] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x]
+  return [p + m, q + m, u + m].map((v) => v * 255)
+}

package/src/parse.js

@@ -0,0 +1,180 @@
+// A deck's Markdown read as Slidev reads it (@slidev/parser's rules): slides between `---` lines;
+// a `---` line followed by a line that isn't empty opens that slide's settings, YAML up to the next
+// `---` line (or a ```yaml block at the slide's top); the first slide's settings are the deck's
+// too (its headmatter); the last HTML comment at a slide's end is the speaker's notes; `::name::`
+// on its own line starts a layout's slot. Fenced code and comments never split a slide. Every slide
+// and slot keeps where it starts in the source, so an edit made on a slide goes back to its words.
+// Read too, as brains write them even when asked for Slidev: Pandoc's and Quarto's fenced divs,
+// `::: notes` as the notes, and `:::: columns` holding `::: column`s as slots (what is above them
+// the heading, each column a slot, what is under them the foot), never rewritten.
+// Pure: no DOM, no Markdown parser.
+import { parseYaml } from './yaml.js'
+
+/** @typedef {{ name: string, text: string, start: number }} Slot */
+/** @typedef {{ index: number, start: number, end: number, settings: Record<string, any>, slots: Slot[], notes: string, title: string }} Slide */
+/** @typedef {{ settings: Record<string, any>, slides: Slide[] }} Deck */
+
+const SLOT = /^::([\w-]+)::\s*$/
+
+/** @param {string} source @returns {Deck} */
+export function parseDeck(source) {
+  const text = source.replace(/\r\n?/g, '\n')
+  const lines = text.split('\n')
+  const offsets = [0]
+  for (const line of lines) offsets.push(/** @type {number} */ (offsets.at(-1)) + line.length + 1)
+  /** @type {{ start: number, end: number, matter: [number, number] | null }[]} */
+  const ranges = []
+  let start = 0, matter = /** @type {[number, number] | null} */ (null), comment = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trimEnd()
+    if (comment) { comment = commentGoesOn(line, true); continue }
+    if (line.startsWith('---') && !/^---\s*-/.test(line)) {
+      if (i > start || matter) ranges.push({ start, end: i, matter })
+      matter = null
+      start = i + 1
+      // Settings only when settings follow (a `key:` line), not words: Slidev would take a heading
+      // there for settings and lose the slide, as decks brains write often start `---`, `# Title`.
+      if (line[3] !== '-' && lines[i + 1]?.trim() && /^\s*([\w-]+\s*:|#\s)/.test(lines[i + 1]) && !/^#{1,6}\s/.test(lines[i + 1])) {
+        let j = i + 1
+        while (j < lines.length && lines[j].trimEnd() !== '---') j++
+        matter = [i + 1, j]
+        i = j
+        start = j + 1
+      }
+    } else if (/^\s*(`{3,}|~{3,})/.test(line)) {
+      const fence = /** @type {RegExpExecArray} */ (/^\s*(`{3,}|~{3,})/.exec(line))[1]
+      let j = i + 1
+      while (j < lines.length && !lines[j].trimStart().startsWith(fence)) j++
+      if (j < lines.length) i = j
+    } else comment = commentGoesOn(line, false)
+  }
+  if (start < lines.length || matter) ranges.push({ start, end: lines.length, matter })
+  // No `---` at all, as a document or a Pandoc deck is written: a slide at each heading of the first
+  // two levels, as Pandoc's slide level does, the headmatter staying with the first.
+  const last = /** @type {{ start: number, end: number, matter: [number, number] | null }} */ (ranges.at(-1))
+  if (ranges.length === 1 && last) {
+    let fence = ''
+    const heads = []
+    for (let i = last.start; i < last.end; i++) {
+      const mark = /^\s*(`{3,}|~{3,})/.exec(lines[i])?.[1]
+      if (fence) { if (mark && lines[i].trimStart().startsWith(fence)) fence = '' }
+      else if (mark) fence = mark
+      else if (/^#{1,2}\s+\S/.test(lines[i])) heads.push(i)
+    }
+    if (heads.length >= 2) {
+      ranges.pop()
+      const cuts = heads[0] > last.start && !lines.slice(last.start, heads[0]).some((line) => line.trim()) ? heads : [last.start, ...heads.slice(heads[0] === last.start ? 1 : 0)]
+      cuts.forEach((at, k) => ranges.push({ start: k === 0 ? last.start : at, end: cuts[k + 1] ?? last.end, matter: k === 0 ? last.matter : null }))
+    }
+  }
+  const slides = ranges.map(({ start, end, matter }, index) => slide(lines, offsets, start, end, matter, index))
+    .filter((one, i) => i === 0 || one.slots.some((slot) => slot.text.trim()) || Object.keys(one.settings).length)
+  slides.forEach((one, i) => { one.index = i })
+  return { settings: slides[0]?.settings ?? {}, slides }
+}
+
+/**
+ * Pandoc's columns, as the lines where each slot starts: the first column `left`, the next `right`
+ * (or `middle`, then `right`, for three), the line after the columns `bottom`. The fences' own lines
+ * are left as they are and drawn as nothing. @param {string[]} lines @returns {Map<number, string>}
+ */
+function columnsOf(lines) {
+  /** @type {Map<number, string>} */
+  const starts = new Map()
+  const open = lines.findIndex((line) => /^:{3,}[ \t]*\{?[ \t]*\.?columns\b/.test(line))
+  if (open < 0) return starts
+  const fence = /** @type {RegExpExecArray} */ (/^:+/.exec(lines[open]))[0]
+  const close = lines.findIndex((line, i) => i > open && line.trim() === fence)
+  const cols = lines.map((line, i) => [line, i]).filter(([line, i]) => Number(i) > open && (close < 0 || Number(i) < close) && /^:{3,}[ \t]*\{?[ \t]*\.?col(umn)?\b/.test(String(line))).map(([, i]) => Number(i))
+  if (cols.length < 2) return starts
+  const names = cols.length === 2 ? ['left', 'right'] : ['left', 'middle', 'right', ...cols.slice(3).map((_, k) => `col-${k + 4}`)]
+  cols.forEach((at, k) => starts.set(at, names[k]))
+  if (close > 0 && lines.slice(close + 1).some((line) => line.trim())) starts.set(close, 'bottom')
+  return starts
+}
+
+/** Whether a comment is still open at this line's end. @param {string} line @param {boolean} open */
+function commentGoesOn(line, open) {
+  let at = 0
+  for (;;) {
+    if (open) {
+      const end = line.indexOf('-->', at)
+      if (end < 0) return true
+      open = false
+      at = end + 3
+    } else {
+      const begin = line.indexOf('<!--', at)
+      if (begin < 0) return false
+      const end = line.indexOf('-->', begin + 4)
+      if (end < 0) return true
+      at = end + 3
+    }
+  }
+}
+
+/**
+ * @param {string[]} lines @param {number[]} offsets @param {number} from @param {number} to
+ * @param {[number, number] | null} matter @param {number} index @returns {Slide}
+ */
+function slide(lines, offsets, from, to, matter, index) {
+  let settings = matter ? parseYaml(lines.slice(matter[0], matter[1]).join('\n')) : {}
+  let top = from
+  // Slidev's other way to write settings: a ```yaml block at the slide's top.
+  while (top < to && !lines[top].trim()) top++
+  if (!matter && /^```ya?ml\s*$/.test(lines[top] ?? '')) {
+    let j = top + 1
+    while (j < to && !lines[j].startsWith('```')) j++
+    settings = parseYaml(lines.slice(top + 1, j).join('\n'))
+    from = j + 1
+  }
+  let body = lines.slice(from, to).join('\n')
+  let notes = ''
+  // remark's `???` and reveal.js's `Note:`: what follows, to the slide's end, is the notes.
+  const after = /^(\?\?\?|Notes?:)[ \t]*(.*)$/m.exec(body)
+  if (after && after.index !== undefined && !/^```/m.test(body.slice(after.index))) {
+    notes = [after[2], body.slice(after.index + after[0].length)].join('\n').trim()
+    body = body.slice(0, after.index)
+  }
+  // reveal.js's <aside class="notes">, wherever on the slide, as Pandoc's below.
+  body = body.replace(/<aside\b[^>]*class=["']?notes["']?[^>]*>([\s\S]*?)<\/aside>/gi, (all, text) => {
+    notes += (notes ? '\n' : '') + text.replace(/<[^>]*>/g, ' ').replace(/[ \t]+/g, ' ').trim()
+    return all.replace(/[^\n]/g, ' ')
+  })
+  // Pandoc's notes, wherever on the slide: kept as the notes, blanked in place so offsets stay.
+  body = body.replace(/^(:{3,})[ \t]*\{?[ \t]*\.?notes[ \t]*\}?[ \t]*\n([\s\S]*?)\n\1[ \t]*$/gm, (all, _, text) => {
+    notes += (notes ? '\n' : '') + text.trim()
+    return all.replace(/[^\n]/g, ' ')
+  })
+  const comments = [...body.matchAll(/<!--([\s\S]*?)-->/g)]
+  const last = comments.at(-1)
+  if (last && last.index !== undefined && !body.slice(last.index + last[0].length).trim()) {
+    notes = [last[1].trim(), notes].filter(Boolean).join('\n')
+    body = body.slice(0, last.index)
+  }
+  // Each slot's text is the source's own, from where it starts, so offsets in it are the source's.
+  /** @type {Slot[]} */
+  const slots = []
+  let name = 'default', first = from, fence = ''
+  /** @type {string[]} */
+  let taken = []
+  const push = () => slots.push({ name, text: taken.join('\n'), start: offsets[first] })
+  const columns = columnsOf(body.split('\n'))
+  for (const [i, line] of body.split('\n').entries()) {
+    const mark = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+    const marker = SLOT.exec(line) ?? (columns.has(i) ? [line, /** @type {string} */ (columns.get(i))] : null)
+    if (fence) { if (mark && line.trimStart().startsWith(fence)) fence = '' }
+    else if (mark) fence = mark
+    else if (marker) {
+      push()
+      name = marker[1]
+      taken = []
+      first = from + i + 1
+      continue
+    }
+    taken.push(line)
+  }
+  push()
+  const kept = slots.filter((slot, i) => i > 0 || slot.text.trim() || slots.length === 1)
+  const heading = /^#{1,6}\s+(.+)$/m.exec(body.replace(/^```[\s\S]*?^```/gm, ''))
+  return { index, start: offsets[matter ? matter[0] - 1 : from], end: offsets[to] - 1, settings, slots: kept, notes, title: String(settings.title ?? heading?.[1] ?? '').trim() }
+}

package/src/pictures.js

@@ -0,0 +1,47 @@
+// Pictures held inside a deck, for a file that leaves its host: each picture the deck names by an
+// address of the host's own (a project's file, a relative path) becomes a data: address holding the
+// picture itself, in the Markdown's images (`![words](place)`) and in a slide's settings (`image`,
+// `background`, `backgroundImage`). Pictures on the web stay links unless asked for, and nothing else
+// in the text moves. Pure but for the host's `read`, which gives a picture's bytes and type.
+
+const SETTINGS = /^(\s*(?:image|background|backgroundImage)\s*:\s*)(['"]?)([^'"\n#]+?)\2(\s*(?:#.*)?)$/gm
+const IMAGE = /(!\[[^\]\n]*\]\()(<[^>\n]+>|[^\s)\n]+)((?:\s+(?:"[^"\n]*"|'[^'\n]*'))?\))/g
+
+/** @param {string} place */
+const held = (place) => /^data:/i.test(place)
+/** @param {string} place */
+const web = (place) => /^(https?:)?\/\//i.test(place)
+
+/** @param {Uint8Array} bytes */
+function base64(bytes) {
+  let text = ''
+  for (let i = 0; i < bytes.length; i += 0x8000) text += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  return btoa(text)
+}
+
+/**
+ * The deck with its pictures inside it.
+ * @param {string} source
+ * @param {(place: string) => Promise<{ type: string, bytes: Uint8Array } | null>} read
+ * @param {{ web?: boolean, largest?: number }} [options] `web`: pictures on the web too; `largest`: bytes past which a picture stays a link
+ * @returns {Promise<{ source: string, inlined: string[], missing: string[], kept: string[] }>}
+ */
+export async function inlinePictures(source, read, { web: fromWeb = false, largest = 8 * 1024 * 1024 } = {}) {
+  /** @type {Map<string, string | null>} */
+  const found = new Map()
+  const places = [...source.matchAll(IMAGE)].map((m) => m[2].replace(/^<|>$/g, '')).concat([...source.matchAll(SETTINGS)].map((m) => m[3].trim()))
+  const inlined = [], missing = [], kept = []
+  for (const place of new Set(places)) {
+    if (held(place) || (web(place) && !fromWeb) || /^(#|mailto:|javascript:)/i.test(place)) continue
+    const picture = await read(place).catch(() => null)
+    if (!picture || !/^image\/(png|jpeg|gif|webp|avif|svg\+xml)$/.test(picture.type)) { missing.push(place); found.set(place, null); continue }
+    if (picture.bytes.length > largest) { kept.push(place); found.set(place, null); continue }
+    found.set(place, `data:${picture.type};base64,${base64(picture.bytes)}`)
+    inlined.push(place)
+  }
+  const swap = (/** @type {string} */ place) => found.get(place) ?? null
+  const out = source
+    .replace(IMAGE, (all, open, place, close) => { const data = swap(place.replace(/^<|>$/g, '')); return data ? `${open}${data}${close}` : all })
+    .replace(SETTINGS, (all, key, quote, place, rest) => { const data = swap(place.trim()); return data ? `${key}${quote}${data}${quote}${rest}` : all })
+  return { source: out, inlined, missing, kept }
+}