@erclx/canon 5.14.1 → 5.16.0

package/src/serve/static.ts

@@ -13,7 +13,7 @@ export const SERVE_HOST = '127.0.0.1'
 export const DEFAULT_PORT = 8787
 
 /** How far past the requested port to look before refusing. */
-const PORT_ATTEMPTS = 20
+export const PORT_ATTEMPTS = 20
 
 const DEFAULT_ENTRY = 'index.html'
 
@@ -216,23 +216,23 @@ export function shouldWalkPast(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | null)?.code === 'EADDRINUSE'
 }
 
+type BoundServer = ReturnType<typeof Bun.serve>
+
 /**
  * Picks a listening port, starting at the requested one and walking forward.
  * A busy port is the ordinary case rather than a failure, since a preview of
  * one workspace is routinely open while another is started.
+ *
+ * Takes the bind as a parameter so every surface that serves walks ports the
+ * same way, whatever routes it binds.
  */
-function listen(
-  root: string,
+export function bindFirstFree(
   first: number,
-  index: boolean,
-): { server: ReturnType<typeof Bun.serve>; port: number } | undefined {
+  bind: (port: number) => BoundServer,
+): { server: BoundServer; port: number } | undefined {
   for (let port = first; port < first + PORT_ATTEMPTS; port++) {
     try {
-      const server = Bun.serve({
-        hostname: SERVE_HOST,
-        port,
-        fetch: (request) => respond(root, request, index),
-      })
+      const server = bind(port)
       /**
        * The bound port rather than the requested one. Port 0 asks the OS to
        * choose, so reporting the request builds a URL pointing at nothing.
@@ -245,7 +245,7 @@ function listen(
        * Contention is the one cause worth walking past. A permission failure
        * or an unavailable interface swallowed here would be retried twenty
        * times and then reported as a port range being full, which names a
-       * cause nothing checked. `startServer` turns the rethrow into a refusal.
+       * cause nothing checked. The caller turns the rethrow into a refusal.
        */
       if (!shouldWalkPast(error)) throw error
     }
@@ -253,6 +253,20 @@ function listen(
   return undefined
 }
 
+function listen(
+  root: string,
+  first: number,
+  index: boolean,
+): { server: BoundServer; port: number } | undefined {
+  return bindFirstFree(first, (port) =>
+    Bun.serve({
+      hostname: SERVE_HOST,
+      port,
+      fetch: (request) => respond(root, request, index),
+    }),
+  )
+}
+
 export async function respond(
   root: string,
   request: Request,

package/src/surface-root.ts

@@ -43,7 +43,6 @@ export const SURFACE_ENTRIES: readonly string[] = [
   'DESIGN.md',
   'context',
   'wireframes',
-  'decisions',
   'canon',
 ]
 

package/src/teach/browser/compile.ts

@@ -0,0 +1,44 @@
+type BrowserFunction = (...args: never[]) => unknown
+
+const transpiler = new Bun.Transpiler({ loader: 'ts' })
+
+const MODULE_SYNTAX = /^\s*(import|export)\b/m
+
+/**
+ * `</script>` inside a serialized argument would end the block early, and
+ * `<` is the same character to the JavaScript parser.
+ */
+function serialize(args: readonly unknown[]): string {
+  return JSON.stringify(args).slice(1, -1).replace(/</g, '\\u003c')
+}
+
+/**
+ * Turns a browser module's function into the `<script>` a page carries. The
+ * transpiler does not bundle, so a module is self-contained: whatever it
+ * calls but does not define arrives as a named function in `helpers`, and a
+ * value it needs arrives in `args`. Output holding module syntax throws, since
+ * a script block with an `import` fails in the browser with nothing in the
+ * type checker to say so.
+ */
+export function compileScript(
+  run: BrowserFunction,
+  args: readonly unknown[] = [],
+  helpers: readonly BrowserFunction[] = [],
+): string {
+  const source = helpers.length
+    ? `(function () {\n${helpers.map(String).join('\n')}\nreturn ${run};\n})()`
+    : String(run)
+  // A bare expression statement is dead code to the transpiler and comes back
+  // empty, so the source rides an export that it must keep.
+  const code = transpiler
+    .transformSync(`export default ${source}`)
+    .trim()
+    .replace(/^export default /, '')
+    .replace(/;$/, '')
+
+  if (MODULE_SYNTAX.test(code)) {
+    throw new Error(`Browser module ${run.name} left import or export syntax`)
+  }
+
+  return `<script>(${code})(${serialize(args)})</script>`
+}

package/src/teach/browser/dismiss.ts

@@ -0,0 +1,76 @@
+export function dismiss(): void {
+  var MENUS = 'details.jump[open], details.sb-ws[open]'
+
+  function close(except: Element | null) {
+    document.querySelectorAll<HTMLDetailsElement>(MENUS).forEach(function (d) {
+      if (d !== except) d.open = false
+    })
+  }
+  document.addEventListener('click', function (e) {
+    var inside = (e.target as Element).closest('details.jump, details.sb-ws')
+    close(inside)
+  })
+  document.addEventListener('keydown', function (e) {
+    if (e.key !== 'Escape') return
+    var open = document.querySelector<HTMLDetailsElement>(MENUS)
+    if (!open) return
+    open.open = false
+    var s = open.querySelector('summary')
+    if (s) s.focus()
+  })
+
+  /* Hover intent on the breadcrumb only. The sidebar's workspace switcher stays
+     click-only on purpose: its panel opens directly over the lesson list, which
+     is where the pointer is headed, so hovering it would cover the thing
+     being reached for. The breadcrumb's panel drops over body text instead. */
+  var OPEN = 120,
+    SHUT = 260
+
+  document
+    .querySelectorAll<HTMLDetailsElement>('details.jump')
+    .forEach(function (d) {
+      var host = d.closest('.crumb-item') || d
+      var timer: ReturnType<typeof setTimeout> | undefined
+      var openedByHover = false
+
+      function arm(want: boolean) {
+        clearTimeout(timer)
+        timer = setTimeout(
+          function () {
+            if (want) close(d)
+            d.open = want
+          },
+          want ? OPEN : SHUT,
+        )
+      }
+
+      host.addEventListener('mouseenter', function () {
+        if (!d.open) openedByHover = true
+        arm(true)
+      })
+      host.addEventListener('mouseleave', function () {
+        openedByHover = false
+        arm(false)
+      })
+      /* Keeps it open while the pointer is inside the panel, without cancelling a
+       pending open, which is what silently disabled this on one of two menus. */
+      d.addEventListener('mouseenter', function () {
+        if (d.open) clearTimeout(timer)
+      })
+
+      /* Hover and click were wired to one disclosure and fought: hover opened the
+       panel, then the summary's native click toggled what hover had already
+       opened, so reaching for an item shut it. A click on a panel hover opened
+       keeps it open, and a second click closes. The click path stays live for
+       touch, where no hover exists, and for the keyboard, where Enter is the
+       only way in. */
+      var summary = d.querySelector('summary')
+      if (summary)
+        summary.addEventListener('click', function (e) {
+          if (d.open && openedByHover) {
+            e.preventDefault()
+            openedByHover = false
+          }
+        })
+    })
+}

package/src/teach/browser/focus-line.ts

@@ -0,0 +1,19 @@
+/**
+ * The outline rail's focus-line ramp. It runs from near the top at scroll 0 to
+ * the viewport's bottom edge at max scroll, so the last heading is reachable
+ * however little content trails it. A ramp ending 120px short of the edge left
+ * a heading with under 120px after it permanently unmarked, since its top never
+ * fell below the line even at max scroll.
+ *
+ * The sidebar script embeds this function's own source, so a test exercises
+ * what the browser runs.
+ */
+export function focusLine(
+  scrollY: number,
+  max: number,
+  innerHeight: number,
+): number {
+  if (max <= 0) return innerHeight
+  var progress = Math.min(1, Math.max(0, scrollY / max))
+  return 120 + progress * Math.max(0, innerHeight - 120)
+}

package/src/teach/browser/glossary-filter.ts

@@ -0,0 +1,44 @@
+export function glossaryFilter(): void {
+  var input = document.getElementById('gfilter') as HTMLInputElement | null
+  var list = document.getElementById('gloss')
+  var count = document.getElementById('gloss-count')
+  if (!input || !list) return
+  var field = input
+  var terms = list
+  function updateGroups() {
+    terms.querySelectorAll('.gloss-group').forEach(function (heading) {
+      var el = heading.nextElementSibling as HTMLElement | null
+      var any = false
+      while (el && !el.classList.contains('gloss-group')) {
+        if (el.style.display !== 'none') any = true
+        el = el.nextElementSibling as HTMLElement | null
+      }
+      ;(heading as HTMLElement).style.display = any ? '' : 'none'
+    })
+  }
+  field.addEventListener('input', function () {
+    var q = field.value.toLowerCase()
+    var n = 0
+    terms.querySelectorAll<HTMLElement>('.gterm').forEach(function (entry) {
+      var match = (entry.textContent as string).toLowerCase().includes(q)
+      entry.style.display = match ? '' : 'none'
+      if (match) n++
+    })
+    terms.classList.toggle('none', n === 0)
+    updateGroups()
+    if (count) {
+      var total = terms.querySelectorAll('.gterm').length
+      count.textContent =
+        (n === total ? total : n + ' of ' + total) +
+        (total === 1 ? ' term' : ' terms')
+    }
+  })
+  var clear = terms.querySelector('.clear')
+  if (clear) {
+    clear.addEventListener('click', function () {
+      field.value = ''
+      field.dispatchEvent(new Event('input'))
+      field.focus()
+    })
+  }
+}

package/src/teach/browser/head.ts

@@ -0,0 +1,30 @@
+/**
+ * The panel's state, settled before the first paint rather than after it. An
+ * arm that set the narrow default afterwards slid the panel in and back out on
+ * every load, and a restored custom width animated in from the default.
+ *
+ * A listing page starts shut because the body already lists what the panel
+ * would, and a lesson starts open because there the panel is the only
+ * cross-lesson navigation on the page. A stored preference beats both. A count
+ * threshold on its own was built and reverted, since it hides the panel on a
+ * lesson too.
+ */
+export function head(page: 'index' | 'lesson', breakpoint: number): void {
+  var r = document.documentElement
+  var s: string | null = null
+  r.dataset.page = page
+  if (matchMedia('(max-width: ' + breakpoint + 'px)').matches) {
+    r.classList.add('sb-shut')
+    return
+  }
+  try {
+    s = localStorage.getItem('teach-sb')
+  } catch (e) {}
+  var idx = r.dataset.page === 'index'
+  if (s === 'shut' || (s === null && idx)) r.classList.add('sb-shut')
+  var w: string | null = null
+  try {
+    w = localStorage.getItem('teach-sb-w')
+  } catch (e) {}
+  if (w) r.style.setProperty('--sb-w', w + 'px')
+}

package/src/teach/browser/quiz.ts

@@ -0,0 +1,19 @@
+/**
+ * What reveals feedback in a lesson written with button options. The radio
+ * shape needs none of it.
+ */
+export function quiz(): void {
+  document.querySelectorAll<HTMLElement>('.q').forEach(function (q) {
+    var f = q.querySelector('.fb') as HTMLElement
+    q.querySelectorAll<HTMLElement>('.opt').forEach(function (b) {
+      b.addEventListener('click', function () {
+        if (f.classList.contains('show')) return
+        q.querySelectorAll<HTMLElement>('.opt').forEach(function (o) {
+          o.dataset.state =
+            o.dataset.a === '1' ? 'right' : o === b ? 'chosen' : 'wrong'
+        })
+        f.classList.add('show')
+      })
+    })
+  })
+}

package/src/teach/browser/sidebar.ts

@@ -0,0 +1,233 @@
+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 (e) {}
+    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 (e) {}
+      /* 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 (e) {}
+    }
+  }
+
+  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

@@ -0,0 +1,18 @@
+export function theme(): void {
+  var r = document.documentElement
+  try {
+    var s = localStorage.getItem('course-theme')
+    if (s) r.dataset.theme = s
+  } catch (e) {}
+  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 (e) {}
+  })
+}