@pfern/elements 0.1.11 → 0.2.0

package/src/mathml.js

@@ -0,0 +1,340 @@
+/**
+ * MathML tag helpers (curated).
+ *
+ * This module is intentionally small and focused on the subset that’s useful
+ * for building expression visualizers and teaching tools (e.g. Content MathML
+ * trees with `<apply>`, plus a handful of Presentation MathML helpers).
+ *
+ * The Elements.js runtime supports rendering *any* MathML tag name as a vnode
+ * (e.g. `['apply', {}, ...]`). These helpers exist for ergonomics and docs.
+ */
+
+const isPropsObject = x =>
+  typeof x === 'object'
+  && x !== null
+  && !Array.isArray(x)
+  && !(typeof Node !== 'undefined' && x instanceof Node)
+
+/**
+ * @param {string} tag
+ * @returns {import('./core/types.js').ElementsElementHelper<any>}
+ */
+const createTagHelper = tag => (...args) => {
+  const hasFirstArg = args.length > 0
+  const [propsOrChild, ...children] = args
+  const props = hasFirstArg && isPropsObject(propsOrChild) ? propsOrChild : {}
+  const actualChildren = !hasFirstArg
+    ? []
+    : props === propsOrChild
+      ? children
+      : [propsOrChild, ...children]
+  return /** @type {import('./core/types.js').ElementsVNode} */ (
+    [tag, props, ...actualChildren]
+  )
+}
+
+/**
+ * <math>
+ * The root element of a MathML expression.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/math
+ */
+export const math = createTagHelper('math')
+
+/**
+ * <mrow>
+ * Groups sub-expressions without introducing visible separators.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mrow
+ */
+export const mrow = createTagHelper('mrow')
+
+/**
+ * <mi>
+ * Identifier (variable/function name).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mi
+ */
+export const mi = createTagHelper('mi')
+
+/**
+ * <mo>
+ * Operator (e.g. "+", "→", parentheses).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mo
+ */
+export const mo = createTagHelper('mo')
+
+/**
+ * <mn>
+ * Number literal.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mn
+ */
+export const mn = createTagHelper('mn')
+
+/**
+ * <mtext>
+ * Text inside math layout.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mtext
+ */
+export const mtext = createTagHelper('mtext')
+
+/**
+ * <mspace>
+ * Spacing control.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mspace
+ */
+export const mspace = createTagHelper('mspace')
+
+/**
+ * <mstyle>
+ * Styling wrapper for MathML subtree.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mstyle
+ */
+export const mstyle = createTagHelper('mstyle')
+
+/**
+ * <menclose>
+ * Encloses content (e.g. boxes, circles).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/menclose
+ */
+export const menclose = createTagHelper('menclose')
+
+/**
+ * <mfenced>
+ * Convenience fencing wrapper (parentheses, brackets).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mfenced
+ */
+export const mfenced = createTagHelper('mfenced')
+
+/**
+ * <msup>
+ * Superscript.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/msup
+ */
+export const msup = createTagHelper('msup')
+
+/**
+ * <msub>
+ * Subscript.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/msub
+ */
+export const msub = createTagHelper('msub')
+
+/**
+ * <msubsup>
+ * Subscript + superscript.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/msubsup
+ */
+export const msubsup = createTagHelper('msubsup')
+
+/**
+ * <mfrac>
+ * Fraction.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mfrac
+ */
+export const mfrac = createTagHelper('mfrac')
+
+/**
+ * <msqrt>
+ * Square root.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/msqrt
+ */
+export const msqrt = createTagHelper('msqrt')
+
+/**
+ * <mroot>
+ * Root with explicit index.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mroot
+ */
+export const mroot = createTagHelper('mroot')
+
+/**
+ * <munder>
+ * Under-script.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/munder
+ */
+export const munder = createTagHelper('munder')
+
+/**
+ * <mover>
+ * Over-script.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mover
+ */
+export const mover = createTagHelper('mover')
+
+/**
+ * <munderover>
+ * Under + over script.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/munderover
+ */
+export const munderover = createTagHelper('munderover')
+
+/**
+ * <mtable>
+ * Table layout.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mtable
+ */
+export const mtable = createTagHelper('mtable')
+
+/**
+ * <mtr>
+ * Table row.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mtr
+ */
+export const mtr = createTagHelper('mtr')
+
+/**
+ * <mtd>
+ * Table cell.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/mtd
+ */
+export const mtd = createTagHelper('mtd')
+
+/**
+ * <semantics>
+ * Attach semantic annotations to a presentation tree.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/semantics
+ */
+export const semantics = createTagHelper('semantics')
+
+/**
+ * <annotation>
+ * A textual annotation inside <semantics>.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/annotation
+ */
+export const annotation = createTagHelper('annotation')
+
+/**
+ * <annotation-xml>
+ * An XML annotation inside <semantics>.
+ *
+ * Exported as `annotationXml` because of the dash in the tag name.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/annotation-xml
+ */
+export const annotationXml = createTagHelper('annotation-xml')
+
+/**
+ * <apply>
+ * Content MathML application node: first child is the operator, remaining
+ * children are arguments.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/apply
+ */
+export const apply = createTagHelper('apply')
+
+/**
+ * <ci>
+ * Content MathML identifier.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/ci
+ */
+export const ci = createTagHelper('ci')
+
+/**
+ * <cn>
+ * Content MathML number.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/cn
+ */
+export const cn = createTagHelper('cn')
+
+/**
+ * <csymbol>
+ * Content MathML symbol (often with a content dictionary via `cd`).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/csymbol
+ */
+export const csymbol = createTagHelper('csymbol')
+
+/**
+ * <bind>
+ * Content MathML binding node (e.g. lambda).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/bind
+ */
+export const bind = createTagHelper('bind')
+
+/**
+ * <bvar>
+ * Bound variable (used under <bind>).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/bvar
+ */
+export const bvar = createTagHelper('bvar')
+
+/**
+ * <lambda>
+ * Lambda binder operator (typically inside <bind>).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/lambda
+ */
+export const lambda = createTagHelper('lambda')
+
+/**
+ * <set>
+ * Content MathML set constructor (often under <apply>).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/set
+ */
+export const set = createTagHelper('set')
+
+/**
+ * <list>
+ * Content MathML list constructor (often under <apply>).
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/list
+ */
+export const list = createTagHelper('list')
+
+/**
+ * <vector>
+ * Content MathML vector constructor.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/vector
+ */
+export const vector = createTagHelper('vector')
+
+/**
+ * <matrix>
+ * Content MathML matrix constructor.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/matrix
+ */
+export const matrix = createTagHelper('matrix')
+
+/**
+ * <matrixrow>
+ * Content MathML matrix row.
+ * https://developer.mozilla.org/en-US/docs/Web/MathML/Element/matrixrow
+ */
+export const matrixrow = createTagHelper('matrixrow')
+
+/**
+ * A map of curated MathML helpers.
+ */
+export const mathml = /** @type {const} */ ({
+  math,
+  mrow,
+  mi,
+  mo,
+  mn,
+  mtext,
+  mspace,
+  mstyle,
+  menclose,
+  mfenced,
+  msup,
+  msub,
+  msubsup,
+  mfrac,
+  msqrt,
+  mroot,
+  munder,
+  mover,
+  munderover,
+  mtable,
+  mtr,
+  mtd,
+  semantics,
+  annotation,
+  annotationXml,
+  apply,
+  ci,
+  cn,
+  csymbol,
+  bind,
+  bvar,
+  lambda,
+  set,
+  list,
+  vector,
+  matrix,
+  matrixrow
+})
+

package/src/router.js

@@ -0,0 +1,51 @@
+// Router utilities.
+//
+// `onNavigate(fn)` registers a callback that should re-render your app when the
+// URL changes (via History API navigation or back/forward).
+//
+// The callback is invoked on a microtask after `popstate` so it can safely run
+// outside of any current declarative event update.
+
+let current = null
+let installed = false
+let scheduled = false
+
+const defer = fn =>
+  typeof window.queueMicrotask === 'function'
+    ? window.queueMicrotask(fn)
+    : Promise.resolve().then(fn)
+
+const schedule = () => {
+  if (typeof current !== 'function') return
+  if (scheduled) return
+  scheduled = true
+  defer(() => {
+    scheduled = false
+    typeof current === 'function' && current()
+  })
+}
+
+const onPopState = () => schedule()
+
+export const hasNavigateHandler = () => typeof current === 'function'
+
+export const onNavigate = (fn, { immediate = false } = {}) => {
+  current = fn
+
+  if (typeof window !== 'undefined' && !installed) {
+    window.addEventListener('popstate', onPopState)
+    installed = true
+  }
+
+  immediate && schedule()
+
+  return () => {
+    if (current !== fn) return
+    current = null
+
+    if (typeof window !== 'undefined' && installed) {
+      window.removeEventListener('popstate', onPopState)
+      installed = false
+    }
+  }
+}

package/src/ssr.js

@@ -0,0 +1,175 @@
+/** @fileoverview Server-side rendering / static site generation helpers.
+ *
+ * Elements.js treats UI as a pure function tree that produces declarative
+ * “vnode” arrays:
+ *
+ *   ['div', { id: 'x' }, 'Hello']
+ *
+ * In the browser, `render()` evaluates this AST into real DOM nodes. For
+ * build-time prerendering (SSG) or server-side rendering (SSR),
+ * `toHtmlString()` walks the same AST and prints HTML.
+ *
+ * Design notes:
+ * - This is intentionally “dumb printing”, not hydration. Event handlers and
+ *   other imperative props (functions) are dropped.
+ * - `innerHTML` is treated as an explicit escape hatch: it is inserted verbatim
+ *   and children are ignored.
+ * - Boolean attribute rules mirror DOM assignment in `core/props.js`: -
+ *   `aria-*` / `data-*` booleans become `"true"` / `"false"`.  - other booleans
+ *   are present when true, omitted when false.
+ *
+ * The long-term goal is that vnode arrays act as a small, Lisp-like
+ * cons-structure / AST: they can be evaluated into DOM, or serialized back into
+ * markup, or translated into other equivalent encodings.
+ */
+
+const voidTags = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr'
+])
+
+const isObject = x =>
+  typeof x === 'object'
+  && x !== null
+  && !Array.isArray(x)
+
+const escapeText = s =>
+  String(s)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+
+const escapeAttr = s =>
+  String(s)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('\'', '&#39;')
+
+const toKebab = s =>
+  String(s)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replaceAll('_', '-')
+    .toLowerCase()
+
+const styleToString = style => {
+  if (!isObject(style)) return ''
+  const keys = Object.keys(style)
+  if (keys.length === 0) return ''
+
+  return keys
+    .filter(k => style[k] != null && style[k] !== false)
+    .map(k => `${k.startsWith('--') ? k : toKebab(k)}:${String(style[k])}`)
+    .join(';')
+}
+
+const shouldDropProp = (key, value) => {
+  if (key == null) return true
+  if (key === 'innerHTML') return true
+  if (String(key).startsWith('__')) return true
+  if (typeof value === 'function') return true
+  if (key === 'ontick') return true
+  return false
+}
+
+const attrsToString = props => {
+  if (!isObject(props)) return ''
+
+  const normalized = props.class == null && props.className != null
+    ? { ...props, class: props.className }
+    : props
+
+  const keys = Object.keys(normalized)
+    .filter(k => !shouldDropProp(k, normalized[k]))
+    .sort()
+
+  let out = ''
+  for (const key of keys) {
+    const value = normalized[key]
+    if (value == null || value === false) {
+      // Preserve `aria-*` / `data-*` boolean semantics for false.
+      if (typeof value === 'boolean'
+        && (key.startsWith('aria-') || key.startsWith('data-')))
+        out += ` ${key}="false"`
+      continue
+    }
+
+    if (key === 'style' && isObject(value)) {
+      const cssText = styleToString(value)
+      cssText && (out += ` style="${escapeAttr(cssText)}"`)
+      continue
+    }
+
+    if (typeof value === 'boolean') {
+      if (key.startsWith('aria-') || key.startsWith('data-')) {
+        out += ` ${key}="${value ? 'true' : 'false'}"`
+      } else if (value) {
+        out += ` ${key}`
+      }
+      continue
+    }
+
+    out += ` ${key}="${escapeAttr(value)}"`
+  }
+  return out
+}
+
+const toHtmlStringInner = vnode => {
+  const type = typeof vnode
+  if (vnode == null || vnode === false) return ''
+  if (type === 'string' || type === 'number') return escapeText(vnode)
+
+  if (!Array.isArray(vnode) || vnode.length === 0) return ''
+
+  const tag = vnode[0]
+
+  // Explicit fragments render children without a wrapper tag.
+  if (tag === 'fragment') {
+    let out = ''
+    for (let i = 2; i < vnode.length; i++) out += toHtmlStringInner(vnode[i])
+    return out
+  }
+
+  if (typeof tag !== 'string') return ''
+
+  /** @type {Record<string, any>} */
+  const props = isObject(vnode[1]) ? vnode[1] : {}
+  const attrs = attrsToString(props)
+
+  if (voidTags.has(tag)) return `<${tag}${attrs}>`
+
+  const hasInnerHtml = 'innerHTML' in props
+  const inner = hasInnerHtml
+    ? String(props.innerHTML ?? '')
+    : (() => {
+      let out = ''
+      for (let i = 2; i < vnode.length; i++) out += toHtmlStringInner(vnode[i])
+      return out
+    })()
+
+  return `<${tag}${attrs}>${inner}</${tag}>`
+}
+
+/**
+ * Serialize a vnode tree to an HTML string (SSR/SSG).
+ *
+ * @param {import('./core/types.js').ElementsVNode | string | number | null | undefined | false} vnode
+ * @param {{ doctype?: boolean }} [options]
+ * @returns {string}
+ */
+export const toHtmlString = (vnode, { doctype = false } = {}) =>
+  `${doctype ? '<!doctype html>' : ''}${toHtmlStringInner(vnode)}`
+