@erclx/canon 4.75.1 → 4.77.0

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

@@ -0,0 +1,113 @@
+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

@@ -0,0 +1,28 @@
+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;')
+}

package/src/teach/render-fixture.tsx

@@ -0,0 +1,95 @@
+/** @jsxImportSource ./html */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { TEACH_STYLESHEET_COMPONENTS } from '@/design/components'
+import { buildDesignCss } from '@/design/css'
+import { TEACH_FONT_FACES } from '@/teach/fonts'
+import { Heading } from '@/teach/components/heading'
+import { List } from '@/teach/components/list'
+import { Paragraph } from '@/teach/components/paragraph'
+import { render } from '@/teach/html/jsx-runtime'
+
+/**
+ * Regenerates the committed fixture lesson under
+ * `examples/teach/00-fixture/`, the same shape `examples/slides/showcase.md`
+ * takes against its own hand-rendered snapshot. Run with
+ * `bun src/teach/render-fixture.tsx` after a component changes shape.
+ */
+
+const FIXTURE_ROOT = join(
+  import.meta.dir,
+  '..',
+  '..',
+  'examples',
+  'teach',
+  '00-fixture',
+)
+const LESSON_TITLE = 'Compass bearings'
+const LESSON_FILE = '0001-compass-bearings.html'
+
+const STEPS = [
+  'Point the direction-of-travel arrow at the landmark.',
+  'Rotate the bezel until the orienting arrow lines up with the needle.',
+  'Read the bearing where the direction-of-travel arrow meets the bezel.',
+]
+
+const body = (
+  <>
+    <Heading level={1}>{LESSON_TITLE}</Heading>
+    <Paragraph lede>
+      A bearing is the compass direction from where you stand to whatever you
+      are aiming at, measured clockwise from north.
+    </Paragraph>
+    <Paragraph>
+      Hold the compass level and let the needle settle before reading anything
+      off it. A bearing taken while walking or tilted reads confidently and
+      wrong.
+    </Paragraph>
+    <Paragraph>
+      Three steps turn a sighted landmark into a number you can act on:
+    </Paragraph>
+    <List ordered items={STEPS} />
+    <Paragraph>
+      The same three steps run in reverse turn a bearing on a map into a
+      direction to walk, which is the only reason to learn them in this order.
+    </Paragraph>
+  </>
+)
+
+function page(title: string, main: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<link rel="stylesheet" href="../assets/course.css">
+</head>
+<body>
+<main class="wide-body">
+${main}
+</main>
+</body>
+</html>
+`
+}
+
+async function main(): Promise<void> {
+  await mkdir(join(FIXTURE_ROOT, 'lessons'), { recursive: true })
+  await mkdir(join(FIXTURE_ROOT, 'assets'), { recursive: true })
+
+  await writeFile(
+    join(FIXTURE_ROOT, 'assets', 'course.css'),
+    buildDesignCss(undefined, {
+      embedFonts: TEACH_FONT_FACES,
+      components: TEACH_STYLESHEET_COMPONENTS,
+    }),
+  )
+
+  await writeFile(
+    join(FIXTURE_ROOT, 'lessons', LESSON_FILE),
+    page(LESSON_TITLE, render(body)),
+  )
+}
+
+await main()

package/tsconfig.json

@@ -3,6 +3,7 @@
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "jsx": "react-jsx",
     "types": ["bun-types"],
     "strict": true,
     "skipLibCheck": true,