@erclx/canon 5.52.0 → 5.54.0

package/src/teach/browser/sidebar.ts

@@ -1,233 +0,0 @@
-import { focusLine } from '@/teach/browser/focus-line'
-
-/**
- * `focusLine` is declared in the page ahead of this function by `compile`, so
- * the call below reaches the one source the unit test exercises.
- */
-export function sidebar(breakpoint: number): void {
-  var root = document.documentElement
-  var found = document.querySelector<HTMLElement>('.sb')
-  if (!found) return
-  var panel = found
-
-  var fold = document.querySelector<HTMLElement>('.sb-fold')
-  var narrow = matchMedia('(max-width: ' + breakpoint + 'px)')
-
-  var FOCUSABLE =
-    "a[href], button:not([disabled]), summary, input, [tabindex]:not([tabindex='-1'])"
-
-  function panelStops() {
-    return Array.prototype.slice
-      .call(panel.querySelectorAll(FOCUSABLE))
-      .filter(function (el: HTMLElement) {
-        return el.offsetParent !== null || el === document.activeElement
-      }) as HTMLElement[]
-  }
-
-  /* The focus return belongs here rather than on the close control, because all
-     three routes out land here and only one of them used to move focus. The
-     shut panel takes visibility: hidden 180ms later, so a reader who pressed
-     Escape kept focus on a control that then disappeared under them and the
-     browser dropped them at the top of the document. */
-  function shut() {
-    var inside = panel.contains(document.activeElement)
-    root.classList.add('sb-shut')
-    try {
-      localStorage.setItem('teach-sb', 'shut')
-    } catch {}
-    if (inside && fold) fold.focus()
-  }
-
-  if (fold)
-    fold.addEventListener('click', function () {
-      root.classList.toggle('sb-shut')
-      try {
-        localStorage.setItem(
-          'teach-sb',
-          root.classList.contains('sb-shut') ? 'shut' : 'open',
-        )
-      } catch {}
-      /* An overlay takes focus with it. Without this a keyboard reader opens the
-       panel and goes on tabbing through the lesson behind the scrim. */
-      if (!narrow.matches || root.classList.contains('sb-shut')) return
-      var first = panel.querySelector<HTMLElement>('a, button, summary, input')
-      if (first) first.focus()
-    })
-
-  var scrim = document.createElement('div')
-  scrim.className = 'sb-scrim'
-  document.body.appendChild(scrim)
-  scrim.addEventListener('click', shut)
-
-  document.addEventListener('keydown', function (e) {
-    if (e.key === 'Escape' && narrow.matches) {
-      shut()
-      return
-    }
-
-    /* The scrim says the lesson is unavailable, so Tab must not reach it.
-       Moving focus into the panel on open only defers this by however many
-       controls the panel holds. */
-    if (e.key !== 'Tab') return
-    if (!narrow.matches || root.classList.contains('sb-shut')) return
-
-    var stops = panelStops()
-    if (!stops.length) return
-
-    var first = stops[0]
-    var last = stops[stops.length - 1]
-
-    if (!panel.contains(document.activeElement)) {
-      ;(e.shiftKey ? last : first).focus()
-      e.preventDefault()
-    } else if (e.shiftKey && document.activeElement === first) {
-      last.focus()
-      e.preventDefault()
-    } else if (!e.shiftKey && document.activeElement === last) {
-      first.focus()
-      e.preventDefault()
-    }
-  })
-
-  /* The panel covers the masthead and the toggle that opened it, so it carries
-     its own way out rather than leaving the scrim as the only route. */
-  var close = document.createElement('button')
-  close.type = 'button'
-  close.className = 'sb-close'
-  close.setAttribute('aria-label', 'Close the course panel')
-  close.textContent = '×'
-  close.addEventListener('click', shut)
-  panel.appendChild(close)
-
-  var MIN = 208,
-    MAX = 296,
-    DEF = 256
-  var grip = document.querySelector<HTMLElement>('.sb-grip')
-  var lastWidth = parseInt(root.style.getPropertyValue('--sb-w'), 10) || DEF
-
-  function setWidth(px: number, save: boolean) {
-    var w = Math.max(MIN, Math.min(MAX, Math.round(px)))
-    root.style.setProperty('--sb-w', w + 'px')
-    lastWidth = w
-    if (save) {
-      try {
-        localStorage.setItem('teach-sb-w', String(w))
-      } catch {}
-    }
-  }
-
-  if (grip) {
-    var handle = grip
-    var dragging = false
-    handle.addEventListener('pointerdown', function (e) {
-      dragging = true
-      handle.setPointerCapture(e.pointerId)
-      root.classList.add('sb-drag')
-      e.preventDefault()
-    })
-    handle.addEventListener('pointermove', function (e) {
-      if (dragging) setWidth(e.clientX, false)
-    })
-    handle.addEventListener('pointerup', function (e) {
-      if (!dragging) return
-      dragging = false
-      root.classList.remove('sb-drag')
-      handle.releasePointerCapture(e.pointerId)
-      setWidth(lastWidth, true)
-    })
-    handle.addEventListener('dblclick', function () {
-      setWidth(DEF, true)
-    })
-    handle.addEventListener('keydown', function (e) {
-      var step = e.shiftKey ? 32 : 8
-      if (e.key === 'ArrowLeft') {
-        setWidth(lastWidth - step, true)
-        e.preventDefault()
-      } else if (e.key === 'ArrowRight') {
-        setWidth(lastWidth + step, true)
-        e.preventDefault()
-      } else if (e.key === 'Home') {
-        setWidth(DEF, true)
-        e.preventDefault()
-      }
-    })
-  }
-
-  var filter = document.querySelector<HTMLInputElement>('.sb-filter input')
-  if (filter) {
-    var box = filter
-    box.addEventListener('input', function () {
-      var q = box.value.trim().toLowerCase()
-      document
-        .querySelectorAll<HTMLElement>('.sb-list > li')
-        .forEach(function (li) {
-          li.classList.toggle(
-            'hide',
-            q !== '' &&
-              (li.textContent as string).toLowerCase().indexOf(q) === -1,
-          )
-        })
-    })
-  }
-
-  var slot = document.querySelector('.sb-out-slot')
-  var hs = Array.prototype.slice.call(
-    document.querySelectorAll('main h2'),
-  ) as HTMLElement[]
-  var links: HTMLElement[] = []
-
-  if (slot && hs.length) {
-    var list = document.createElement('ul')
-    list.className = 'sb-out'
-    hs.forEach(function (h, i) {
-      if (!h.id) h.id = 's' + i
-      var li = document.createElement('li')
-      var a = document.createElement('a')
-      a.href = '#' + h.id
-      a.textContent = (h.textContent as string).trim()
-      li.appendChild(a)
-      list.appendChild(li)
-    })
-    ;(slot.parentNode as Node).replaceChild(list, slot)
-    links = Array.prototype.slice.call(list.querySelectorAll('a'))
-  }
-
-  /* The bar reports position inside the lesson, which nothing reported before
-     the segmented track retired. The breadcrumb's last segment carries the
-     lesson title once the real one has scrolled off. */
-  var bar = document.querySelector<HTMLElement>('.bar')
-  var here = document.querySelector('.crumb-here')
-  var h1 = document.querySelector('main h1')
-  var counter = here ? (here.textContent as string).trim() : ''
-  var title = h1 ? (h1.textContent as string).trim() : ''
-
-  function sync() {
-    var max = document.documentElement.scrollHeight - innerHeight
-    if (bar) {
-      var pct = max > 0 ? Math.min(100, Math.max(0, (scrollY / max) * 100)) : 0
-      bar.style.setProperty('--read', pct.toFixed(1) + '%')
-    }
-
-    if (here && h1 && title && counter) {
-      var want = h1.getBoundingClientRect().bottom < 56 ? title : counter
-      if (here.textContent !== want) here.textContent = want
-    }
-
-    if (links.length) {
-      /* Nothing is marked until a heading has actually passed the line, so the
-         first section is not reported as current while the title is on screen. */
-      var best = -1
-      var line = focusLine(scrollY, max, innerHeight)
-      for (var i = 0; i < hs.length; i++) {
-        if (hs[i].getBoundingClientRect().top <= line) best = i
-      }
-      links.forEach(function (l, j) {
-        l.classList.toggle('on', j === best)
-      })
-    }
-  }
-
-  addEventListener('scroll', sync, { passive: true })
-  addEventListener('resize', sync)
-  sync()
-}

package/src/teach/browser/theme.ts

@@ -1,18 +0,0 @@
-export function theme(): void {
-  var r = document.documentElement
-  try {
-    var s = localStorage.getItem('course-theme')
-    if (s) r.dataset.theme = s
-  } catch {}
-  document.addEventListener('click', function (e) {
-    var b = (e.target as Element).closest('.theme')
-    if (!b) return
-    var d =
-      r.dataset.theme === 'dark' ||
-      (!r.dataset.theme && matchMedia('(prefers-color-scheme: dark)').matches)
-    r.dataset.theme = d ? 'light' : 'dark'
-    try {
-      localStorage.setItem('course-theme', r.dataset.theme)
-    } catch {}
-  })
-}

package/src/teach/components/code.tsx

@@ -1,24 +0,0 @@
-/** @jsxImportSource ../html */
-import { highlight } from '@/teach/highlight'
-import type { Element } from '@/teach/html/jsx-runtime'
-import { raw } from '@/teach/html/raw'
-
-export interface CodeProps {
-  /** A highlight.js language name or alias. Unregistered ones render plain. */
-  readonly lang?: string
-  readonly text: string
-}
-
-/**
- * The one way code reaches a lesson body. The highlighter escapes every source
- * character before wrapping tokens in spans, which is what makes passing its
- * output through `raw` safe.
- */
-export function Code({ lang, text }: CodeProps): Element {
-  const className = lang === undefined ? 'hljs' : `hljs language-${lang}`
-  return (
-    <pre>
-      <code class={className}>{raw(highlight(text, lang).html)}</code>
-    </pre>
-  )
-}

package/src/teach/components/heading.tsx

@@ -1,11 +0,0 @@
-/** @jsxImportSource ../html */
-import type { Child, Element } from '@/teach/html/jsx-runtime'
-
-export interface HeadingProps {
-  readonly level: 1 | 2
-  readonly children: Child
-}
-
-export function Heading({ level, children }: HeadingProps): Element {
-  return level === 1 ? <h1>{children}</h1> : <h2>{children}</h2>
-}

package/src/teach/components/list.tsx

@@ -1,17 +0,0 @@
-/** @jsxImportSource ../html */
-import type { Child, Element } from '@/teach/html/jsx-runtime'
-
-export interface ListProps {
-  readonly ordered?: boolean
-  readonly items: readonly Child[]
-}
-
-/**
- * Composes an item per entry rather than taking pre-built `<li>` children, so
- * every list in a lesson escapes the same way regardless of what the caller
- * hands in.
- */
-export function List({ ordered, items }: ListProps): Element {
-  const rendered = items.map((item) => <li>{item}</li>)
-  return ordered ? <ol>{rendered}</ol> : <ul>{rendered}</ul>
-}

package/src/teach/components/paragraph.tsx

@@ -1,29 +0,0 @@
-/** @jsxImportSource ../html */
-import type { Child, Element } from '@/teach/html/jsx-runtime'
-
-export interface ParagraphProps {
-  /** The lesson's dek, read back by `extractLessonMeta` in `@/teach/nav`. */
-  readonly lede?: boolean
-  /** Reference numbers, each linking to the `Refs` item carrying that id. */
-  readonly cites?: readonly number[]
-  readonly children: Child
-}
-
-export function Paragraph({ lede, cites, children }: ParagraphProps): Element {
-  const markers = (cites ?? []).map((cite) => (
-    <sup class="cite">
-      <a href={`#r${cite}`}>{cite}</a>
-    </sup>
-  ))
-  return lede ? (
-    <p class="lede">
-      {children}
-      {markers}
-    </p>
-  ) : (
-    <p>
-      {children}
-      {markers}
-    </p>
-  )
-}

package/src/teach/components/refs.tsx

@@ -1,28 +0,0 @@
-/** @jsxImportSource ../html */
-import type { Element } from '@/teach/html/jsx-runtime'
-
-export interface Reference {
-  readonly title: string
-  readonly url?: string
-  readonly note?: string
-}
-
-export interface RefsProps {
-  readonly items: readonly Reference[]
-}
-
-/**
- * Numbers each item from 1 so its `id` matches the `#r<n>` a cited
- * `Paragraph` links to. The caller has already checked every `url` parses as
- * http or https, since attribute escaping does not stop a `javascript:` href.
- */
-export function Refs({ items }: RefsProps): Element {
-  const rendered = items.map(({ title, url, note }, index) => (
-    <li id={`r${index + 1}`}>
-      <cite>{title}</cite>
-      {note === undefined ? null : `. ${note}`}
-      {url === undefined ? null : [' ', <a href={url}>{new URL(url).host}</a>]}
-    </li>
-  ))
-  return <ol class="refs">{rendered}</ol>
-}

package/src/teach/cross-references.ts

@@ -1,78 +0,0 @@
-export interface LessonReferencesLinked {
-  readonly html: string
-  /** Four-digit numbers naming no lesson, each once, in first-seen order. */
-  readonly unresolved: readonly string[]
-}
-
-/**
- * A mention a learner would read as pointing at another lesson. The whitespace
- * is captured rather than normalized, since a prettier-wrapped lesson can break
- * a mention across a line.
- */
-const MENTION = /\b(lesson|Lesson)(\s+)(\d{4})\b/g
-
-/**
- * A link nav wrote on an earlier run, and the only kind it may rewrite. The
- * close tag allows whitespace before its `>`, which is how prettier wraps it.
- */
-const OWNED_LINK = /<a\s[^>]*\bdata-lesson-ref\b[^>]*>([\s\S]*?)<\/a\s*>/g
-
-/**
- * A comment, a raw-text element taken whole so a `<` inside a script never
- * reads as a tag, any other tag, or the text between tags.
- */
-const TOKEN =
-  /<!--[\s\S]*?-->|<(script|style)\b[\s\S]*?<\/\1\s*>|<\/?[a-zA-Z][^>]*>|[^<]+|</g
-
-const TAG_NAME = /^<(\/?)([a-zA-Z][a-zA-Z0-9-]*)/
-
-/**
- * Elements whose text stays plain. A link inside a quiz `label` navigates on
- * the click meant to pick an option, and one inside `summary` fights the
- * toggle.
- */
-const SKIPPED = new Set(['a', 'code', 'pre', 'label', 'summary'])
-
-/**
- * Links every "lesson NNNN" mention in a lesson's authored region to the
- * sibling file carrying that number, and reports the numbers naming no lesson.
- * A link carrying `data-lesson-ref` is nav's own, so it is unwrapped and
- * resolved again from its text, which re-points it after a slug rename and
- * drops it once its target is gone. An author's own `<a>` is never touched.
- */
-export function linkLessonReferences(
-  html: string,
-  targets: ReadonlyMap<string, string>,
-  current: string,
-): LessonReferencesLinked {
-  const unresolved: string[] = []
-  let depth = 0
-
-  const linkText = (text: string): string =>
-    text.replace(MENTION, (mention, word, space, number: string) => {
-      const target = targets.get(number)
-      if (target === current) return mention
-      if (target === undefined) {
-        if (!unresolved.includes(number)) unresolved.push(number)
-        return mention
-      }
-      return `<a href="${target}" data-lesson-ref>${word}${space}${number}</a>`
-    })
-
-  const unwrapped = html.replace(OWNED_LINK, (_link, text: string) => text)
-
-  const rewritten = unwrapped.replace(TOKEN, (token) => {
-    if (!token.startsWith('<') || token === '<') {
-      return depth === 0 ? linkText(token) : token
-    }
-
-    const tag = TAG_NAME.exec(token)
-    if (tag === null || !SKIPPED.has(tag[2].toLowerCase())) return token
-
-    if (tag[1] === '/') depth = Math.max(0, depth - 1)
-    else if (!token.endsWith('/>')) depth += 1
-    return token
-  })
-
-  return { html: rewritten, unresolved }
-}

package/src/teach/fonts.ts

@@ -1,16 +0,0 @@
-/**
- * The faces a teach page embeds: the design module's own `FONT_FACES` for
- * everything a lesson reads and for code, plus the hand-drawn pair teach
- * needs for its figures, both from `@/design/fonts`.
- */
-
-import {
-  FONT_FACES,
-  HAND_DRAWN_FONT_FACES,
-  type FontFace,
-} from '@/design/fonts'
-
-export const TEACH_FONT_FACES: readonly FontFace[] = [
-  ...FONT_FACES,
-  ...HAND_DRAWN_FONT_FACES,
-]

package/src/teach/highlight.ts

@@ -1,71 +0,0 @@
-import hljs from 'highlight.js/lib/core'
-import bash from 'highlight.js/lib/languages/bash'
-import css from 'highlight.js/lib/languages/css'
-import diff from 'highlight.js/lib/languages/diff'
-import dockerfile from 'highlight.js/lib/languages/dockerfile'
-import go from 'highlight.js/lib/languages/go'
-import javascript from 'highlight.js/lib/languages/javascript'
-import json from 'highlight.js/lib/languages/json'
-import markdown from 'highlight.js/lib/languages/markdown'
-import python from 'highlight.js/lib/languages/python'
-import shell from 'highlight.js/lib/languages/shell'
-import sql from 'highlight.js/lib/languages/sql'
-import typescript from 'highlight.js/lib/languages/typescript'
-import xml from 'highlight.js/lib/languages/xml'
-import yaml from 'highlight.js/lib/languages/yaml'
-
-/**
- * A fixed set rather than all of highlight.js, since each grammar costs load
- * time and a workspace rarely reaches past these. An unlisted language renders
- * plain rather than refusing, so adding one here is the whole change.
- */
-const LANGUAGES = {
-  bash,
-  css,
-  diff,
-  dockerfile,
-  go,
-  javascript,
-  json,
-  markdown,
-  python,
-  shell,
-  sql,
-  typescript,
-  xml,
-  yaml,
-}
-
-for (const [name, grammar] of Object.entries(LANGUAGES)) {
-  hljs.registerLanguage(name, grammar)
-}
-
-export interface Highlighted {
-  /** Markup safe to embed inside `<code>`: every source character escaped. */
-  readonly html: string
-  /** The language as asked for, or `undefined` when it rendered plain. */
-  readonly language: string | undefined
-}
-
-function escapeCode(text: string): string {
-  return text
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-}
-
-/**
- * Highlights code at build time into `hljs-*` class spans the teach
- * stylesheet colors, so an emitted page needs no script. An absent or
- * unregistered language falls back to escaped plain text rather than
- * throwing or guessing.
- */
-export function highlight(text: string, lang?: string): Highlighted {
-  if (lang === undefined || hljs.getLanguage(lang) === undefined) {
-    return { html: escapeCode(text), language: undefined }
-  }
-  return {
-    html: hljs.highlight(text, { language: lang, ignoreIllegals: true }).value,
-    language: lang,
-  }
-}

package/src/teach/html/jsx-dev-runtime.ts

@@ -1,13 +0,0 @@
-/**
- * Bun resolves this module rather than `jsx-runtime` at run time (spike 1,
- * `.canon/groundwork/56-teach-render-layer/08-spikes.md`), so every export a
- * caller might reach through either entry point has to exist here too.
- */
-export {
-  Fragment,
-  jsx,
-  jsx as jsxDEV,
-  jsxs,
-  render,
-  type JSX,
-} from './jsx-runtime'

package/src/teach/html/jsx-runtime.ts

@@ -1,113 +0,0 @@
-import { escape, isRaw, raw, type RawMarkup } from './raw'
-
-export type Child =
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
-  | RawMarkup
-  | readonly Child[]
-
-export interface Props {
-  readonly children?: Child
-  readonly [key: string]: unknown
-}
-
-/**
- * What a component returns and what `jsx` produces: markup already rendered,
- * carrying the same brand `raw` gives an author's own escape hatch. One brand
- * for both is what lets a parent's `{children}` compose a child's output
- * without escaping it a second time, since a plain string cannot say whether
- * it is author text or already-rendered markup.
- */
-export type Element = RawMarkup
-
-export type Component<P extends Props = Props> = (props: P) => Element
-
-export const Fragment = Symbol('Fragment')
-
-const ARIA_PREFIX = 'aria-'
-
-const VOID_ELEMENTS = new Set([
-  'area',
-  'base',
-  'br',
-  'col',
-  'embed',
-  'hr',
-  'img',
-  'input',
-  'link',
-  'meta',
-  'source',
-  'track',
-  'wbr',
-])
-
-function renderChild(child: Child): string {
-  if (child === null || child === undefined || typeof child === 'boolean') {
-    return ''
-  }
-  if (typeof child === 'number') return String(child)
-  if (typeof child === 'string') return escape(child)
-  if (isRaw(child)) return child.html
-  return child.map(renderChild).join('')
-}
-
-/**
- * ARIA takes the literal word for a boolean, where HTML boolean attributes
- * take presence or absence. Spike 1's first draft rendered a bare
- * `aria-disabled` for `true` and dropped `aria-disabled={false}` entirely,
- * silently removing state a screen reader reads.
- */
-function renderAttribute(key: string, value: unknown): string {
-  if (key.startsWith(ARIA_PREFIX) && typeof value === 'boolean') {
-    return ` ${key}="${value}"`
-  }
-  if (value === undefined || value === null || value === false) return ''
-  if (value === true) return ` ${key}`
-  if (isRaw(value)) return ` ${key}="${escape(value.html)}"`
-  return ` ${key}="${escape(String(value))}"`
-}
-
-function renderAttributes(props: Props): string {
-  return Object.entries(props)
-    .filter(([key]) => key !== 'children')
-    .map(([key, value]) => renderAttribute(key, value))
-    .join('')
-}
-
-export function jsx(
-  type: string | Component | typeof Fragment,
-  props: Props,
-): Element {
-  if (type === Fragment) return raw(renderChild(props.children ?? null))
-  if (typeof type === 'function') return type(props)
-
-  const attrs = renderAttributes(props)
-  if (VOID_ELEMENTS.has(type)) return raw(`<${type}${attrs}>`)
-
-  return raw(
-    `<${type}${attrs}>${renderChild(props.children ?? null)}</${type}>`,
-  )
-}
-
-export const jsxs = jsx
-
-/** Unwraps a rendered element to the plain string a file writes to disk. */
-export function render(element: Element): string {
-  return element.html
-}
-
-export namespace JSX {
-  export type Element = RawMarkup
-
-  export interface ElementChildrenAttribute {
-    children: Record<string, never>
-  }
-
-  export interface IntrinsicElements {
-    [name: string]: Props
-  }
-}

package/src/teach/html/raw.ts

@@ -1,28 +0,0 @@
-const RAW = Symbol('raw')
-
-/**
- * Markup already rendered, exempt from the escaping every other string
- * receives. `raw` is the only way to produce one, so a lesson has to opt in
- * explicitly rather than an author text string accidentally passing through
- * unescaped.
- */
-export interface RawMarkup {
-  readonly [RAW]: true
-  readonly html: string
-}
-
-export function raw(html: string): RawMarkup {
-  return { [RAW]: true, html }
-}
-
-export function isRaw(value: unknown): value is RawMarkup {
-  return typeof value === 'object' && value !== null && RAW in value
-}
-
-export function escape(value: string): string {
-  return value
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-}