@pfern/elements 0.1.10 → 0.2.0

package/src/core/events.js

@@ -0,0 +1,143 @@
+/**
+ * Declarative DOM event wrappers.
+ *
+ * Elements.js treats DOM events as a place to *declare* the next UI tree:
+ * if an event handler returns a vnode, the closest component boundary is
+ * replaced with the rendered result.
+ */
+
+export const isEventProp = (key, value) =>
+  key.startsWith('on') && typeof value === 'function'
+
+export const isFormEventProp = key => /^(oninput|onsubmit|onchange)$/.test(key)
+export const isSubmitEventProp = key => key === 'onsubmit'
+export const isValueEventProp = key => /^(oninput|onchange)$/.test(key)
+
+export const getNearestRoot = (el, isRoot) =>
+  !el || isRoot(el) ? el : getNearestRoot(el.parentNode, isRoot)
+
+const isThenable = x =>
+  !!x
+  && (typeof x === 'object' || typeof x === 'function')
+  && typeof x.then === 'function'
+
+
+const getHref = el =>
+  typeof el?.getAttribute === 'function'
+    ? el.getAttribute('href')
+    : el?.attributes?.href ?? el?.href
+
+const isPlainLeftClick = event =>
+  event?.button == null
+    ? false
+    : event.button === 0
+      && !event.defaultPrevented
+      && !event.metaKey
+      && !event.ctrlKey
+      && !event.shiftKey
+      && !event.altKey
+
+const shouldPreventDefaultOnUpdate = (env, event) =>
+  env.key === 'onclick'
+  && env.el?.tagName?.toLowerCase?.() === 'a'
+  && !!getHref(env.el)
+  && event?.cancelable !== false
+  && typeof event?.preventDefault === 'function'
+  && isPlainLeftClick(event)
+
+const describeListener = ({ el, key }) =>
+  `Listener '${key}' on <${el.tagName.toLowerCase()}>`
+
+const withEventRoot = (env, eventRoot, fn) => {
+  const prevEventRoot = env.getCurrentEventRoot()
+  const restoreEventRoot = () => env.setCurrentEventRoot(prevEventRoot)
+  env.setCurrentEventRoot(eventRoot)
+
+  let result
+  try { result = fn() }
+  catch (err) { restoreEventRoot(); throw err }
+
+  return !isThenable(result)
+    ? (restoreEventRoot(), result)
+    : result.then(
+      value => (restoreEventRoot(), value),
+      err => { restoreEventRoot(); throw err }
+    )
+}
+
+const warnPassiveReturn = (env, resolved) =>
+  resolved === undefined
+    ? console.warn(
+      `${describeListener(env)} returned nothing.\n`
+        + 'If you intended a UI update, return a vnode array like: '
+        + 'div({}, ...)'
+    )
+    : !Array.isArray(resolved)
+      ? console.warn(
+        `${describeListener(env)} returned "${resolved}".\n`
+          + 'If you intended a UI update, return a vnode array like: '
+          + 'div({}, ...).\n'
+          + 'Otherwise, return undefined (or nothing) for native event '
+          + 'listener behavior.'
+      )
+      : undefined
+
+/**
+ * Wrap an event handler so it can return a vnode to trigger an update.
+ *
+ * @param {{
+ *   el: any,
+ *   key: string,
+ *   handler: Function,
+ *   isRoot: (el: any) => boolean,
+ *   renderTree:
+ *     (node: any, isRoot?: boolean, namespaceURI?: string | null) => any,
+ *   getCurrentEventRoot: () => any,
+ *   setCurrentEventRoot: (el: any) => void,
+ *   debug: boolean
+ * }} env
+ */
+export const createDeclarativeEventHandler = env =>
+  (...args) => {
+    const eventRoot = getNearestRoot(env.el, env.isRoot)
+    if (!eventRoot) return
+
+    return withEventRoot(env, eventRoot, () => {
+      const event = args[0]
+      const isFormEvent = isFormEventProp(env.key)
+      const isSubmitEvent = isSubmitEventProp(env.key)
+      const isValueEvent = isValueEventProp(env.key)
+
+      const arg =
+        isSubmitEvent
+          ? event?.target?.elements || null
+          : isValueEvent
+            ? event?.target?.value
+            : null
+
+      const result = isFormEvent
+        ? env.handler.call(env.el, arg, event)
+        : env.handler.call(env.el, event)
+
+      const handleResult = resolved => {
+        isSubmitEvent && resolved !== undefined && event.preventDefault()
+
+        env.debug && warnPassiveReturn(env, resolved)
+
+        Array.isArray(resolved)
+          && shouldPreventDefaultOnUpdate(env, event)
+          && event.preventDefault()
+
+        if (!Array.isArray(resolved)) return resolved
+
+        const parent = eventRoot.parentNode
+        if (!parent) return resolved
+
+        const replacement = env.renderTree(resolved, true)
+        parent.replaceChild(replacement, eventRoot)
+        return resolved
+      }
+
+      return isThenable(result) ? result.then(handleResult) : handleResult(result)
+    })
+  }

package/src/core/props.js

@@ -0,0 +1,177 @@
+/**
+ * Element property assignment.
+ *
+ * The props object is treated as:
+ * - DOM events: `on*` functions (wrapped to support vnode returns)
+ * - Hooks: non-DOM behavior such as `ontick`
+ * - Styling: `style` objects
+ * - Everything else: attributes (including SVG namespace handling)
+ */
+
+import { createDeclarativeEventHandler, isEventProp } from './events.js'
+import { startTickLoop, stopTickLoop } from './tick.js'
+
+const isObject = x =>
+  typeof x === 'object'
+  && x !== null
+
+const deleteKey = (obj, key) =>
+  (delete obj[String(key)], undefined)
+
+const isX3DOMReadyFor = el =>
+  (x3d => !x3d || !!x3d.runtime)(el?.closest?.('x3d'))
+
+const propertyExceptions = {
+  value: 'value',
+  checked: 'checked',
+  selected: 'selected',
+  disabled: 'disabled',
+  multiple: 'multiple',
+  muted: 'muted',
+  volume: 'volume',
+  currentTime: 'currentTime',
+  playbackRate: 'playbackRate',
+  open: 'open',
+  indeterminate: 'indeterminate'
+}
+
+const propertyExceptionDefaults = {
+  value: '',
+  checked: false,
+  selected: false,
+  disabled: false,
+  multiple: false,
+  muted: false,
+  volume: 1,
+  currentTime: 0,
+  playbackRate: 1,
+  open: false,
+  indeterminate: false
+}
+
+const removeAttribute = (el, key) =>
+  typeof el.removeAttribute === 'function'
+    ? el.removeAttribute(key)
+    : el.attributes ? deleteKey(el.attributes, key) : undefined
+
+const clearStyle = el =>
+  (style =>
+    !style
+      ? undefined
+      : 'cssText' in style
+        ? (style.cssText = '', undefined)
+        : (Object.keys(style).forEach(k => delete style[k]), undefined)
+  )(el?.style)
+
+const clearInnerHTML = el =>
+  el.innerHTML = ''
+
+const clearEventProp = (el, key) =>
+  el[key] = null
+
+const clearPropertyException = (el, key) =>
+  key in propertyExceptions && key in el
+    ? (el[propertyExceptions[key]] = propertyExceptionDefaults[key], undefined)
+    : undefined
+
+const clearTick = el =>
+  (el.ontick = null, stopTickLoop(el))
+
+const clearProp = (el, key) =>
+  key === 'ontick' ? clearTick(el)
+    : key === 'style' ? clearStyle(el)
+      : key === 'innerHTML' ? clearInnerHTML(el)
+        : key in propertyExceptions ? clearPropertyException(el, key)
+          : key.startsWith('on') ? clearEventProp(el, key)
+            : removeAttribute(el, key)
+
+/**
+ * Remove props that existed previously but are absent in the next vnode.
+ *
+ * This keeps updates symmetric: setting a prop then omitting it later clears it
+ * from the DOM element.
+ *
+ * @param {any} el
+ * @param {Record<string, any>} prevProps
+ * @param {Record<string, any>} nextProps
+ */
+export const removeMissingProps = (el, prevProps, nextProps) => {
+  const keys = Object.keys(prevProps)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    !(key in nextProps) && clearProp(el, key)
+  }
+}
+
+/**
+ * Assign props to a DOM element.
+ *
+ * @param {any} el
+ * @param {Record<string, any>} props
+ * @param {{
+ *   svgNS: string,
+ *   debug: boolean,
+ *   isRoot: (el: any) => boolean,
+ *   renderTree: (node: any, isRoot?: boolean, namespaceURI?: string | null) =>
+ *     any,
+ *   getCurrentEventRoot: () => any,
+ *   setCurrentEventRoot: (el: any) => void
+ * }} env
+ */
+export const assignProperties = (el, props, env) => {
+  const isSvg = el.namespaceURI === env.svgNS
+  const keys = Object.keys(props)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    const value = props[key]
+
+    if (key === 'ontick' && typeof value === 'function') {
+      el.ontick = value
+      startTickLoop(el, value, { ready: isX3DOMReadyFor })
+      continue
+    }
+
+    if (key in propertyExceptions && key in el) {
+      el[propertyExceptions[key]] = value
+      continue
+    }
+
+    if (isEventProp(key, value)) {
+      el[key] = createDeclarativeEventHandler({
+        el,
+        key,
+        handler: value,
+        isRoot: env.isRoot,
+        renderTree: env.renderTree,
+        getCurrentEventRoot: env.getCurrentEventRoot,
+        setCurrentEventRoot: env.setCurrentEventRoot,
+        debug: env.debug
+      })
+      continue
+    }
+
+    if (key === 'style' && isObject(value)) {
+      Object.assign(el.style, value)
+      continue
+    }
+
+    if (key === 'innerHTML') {
+      el.innerHTML = value
+      continue
+    }
+
+    if (typeof value === 'boolean') {
+      if (key.startsWith('aria-') || key.startsWith('data-')) {
+        const str = value ? 'true' : 'false'
+        isSvg ? el.setAttributeNS(null, key, str) : el.setAttribute(key, str)
+      } else if (value) {
+        isSvg ? el.setAttributeNS(null, key, '') : el.setAttribute(key, '')
+      } else {
+        removeAttribute(el, key)
+      }
+      continue
+    }
+
+    isSvg ? el.setAttributeNS(null, key, value) : el.setAttribute(key, value)
+  }
+}

package/src/core/tags.js

@@ -0,0 +1,225 @@
+/** @internal */
+export const htmlTagNames = /** @type {const} */ ([
+  // Document metadata
+  'html',
+  'head',
+  'base',
+  'link',
+  'meta',
+  'title',
+
+  // Sections
+  'body',
+  'header',
+  'hgroup',
+  'nav',
+  'main',
+  'section',
+  'article',
+  'aside',
+  'footer',
+  'address',
+
+  // Text content
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'hr',
+  'menu',
+  'pre',
+  'blockquote',
+  'ol',
+  'ul',
+  'li',
+  'dl',
+  'dt',
+  'dd',
+  'figure',
+  'figcaption',
+  'div',
+
+  // Inline text semantics
+  'a',
+  'abbr',
+  'b',
+  'bdi',
+  'bdo',
+  'br',
+  'cite',
+  'code',
+  'data',
+  'dfn',
+  'em',
+  'i',
+  'kbd',
+  'mark',
+  'q',
+  'rb',
+  'rp',
+  'rt',
+  'rtc',
+  'ruby',
+  's',
+  'samp',
+  'small',
+  'span',
+  'strong',
+  'sub',
+  'sup',
+  'time',
+  'u',
+  'var',
+  'wbr',
+
+  // Edits
+  'ins',
+  'del',
+
+  // Embedded content
+  'img',
+  'iframe',
+  'embed',
+  'object',
+  'param',
+  'video',
+  'audio',
+  'source',
+  'track',
+  'picture',
+
+  // Table content
+  'table',
+  'caption',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'th',
+  'td',
+  'colgroup',
+  'col',
+
+  // Forms
+  'form',
+  'fieldset',
+  'legend',
+  'label',
+  'input',
+  'button',
+  'select',
+  'datalist',
+  'optgroup',
+  'option',
+  'textarea',
+  'output',
+  'progress',
+  'meter',
+
+  // Interactive elements
+  'details',
+  'search',
+  'summary',
+  'dialog',
+  'slot',
+  'template',
+
+  // Scripting and style
+  'script',
+  'noscript',
+  'style',
+
+  // Web components and others
+  'canvas',
+  'picture',
+  'map',
+  'area',
+  'slot'
+])
+
+/** @internal */
+export const svgTagNames = /** @type {const} */ ([
+  // Animation elements
+  'animate',
+  'animateMotion',
+  'animateTransform',
+  'mpath',
+  'set',
+
+  // Basic shapes
+  'circle',
+  'ellipse',
+  'line',
+  'path',
+  'polygon',
+  'polyline',
+  'rect',
+
+  // Container / structural
+  'defs',
+  'g',
+  'marker',
+  'mask',
+  'pattern',
+  'svg',
+  'switch',
+  'symbol',
+  'use',
+
+  // Descriptive
+  'desc',
+  'metadata',
+  'title',
+
+  // Filter primitives
+  'filter',
+  'feBlend',
+  'feColorMatrix',
+  'feComponentTransfer',
+  'feComposite',
+  'feConvolveMatrix',
+  'feDiffuseLighting',
+  'feDisplacementMap',
+  'feDistantLight',
+  'feDropShadow',
+  'feFlood',
+  'feFuncA',
+  'feFuncB',
+  'feFuncG',
+  'feFuncR',
+  'feGaussianBlur',
+  'feImage',
+  'feMerge',
+  'feMergeNode',
+  'feMorphology',
+  'feOffset',
+  'fePointLight',
+  'feSpecularLighting',
+  'feSpotLight',
+  'feTile',
+  'feTurbulence',
+
+  // Gradient / paint servers
+  'linearGradient',
+  'radialGradient',
+  'stop',
+
+  // Graphics elements
+  'image',
+  'foreignObject', // included in graphics section as non‑standard children
+
+  // Text and text-path
+  'text',
+  'textPath',
+  'tspan',
+
+  // Scripting/style
+  'script',
+  'style',
+
+  // View
+  'view'
+])

package/src/core/tick.js

@@ -0,0 +1,116 @@
+/**
+ * Tick engine for `ontick`.
+ *
+ * `ontick` is a hook (not a DOM event) that runs a handler once per frame.
+ * It is intentionally minimal: it schedules via `requestAnimationFrame`,
+ * threads optional context, and provides a `dt` in milliseconds.
+ *
+ * The engine is generic and can be used with any element; callers may provide
+ * a `ready(el)` predicate to gate ticking on external readiness (e.g. X3DOM
+ * runtime availability).
+ */
+
+const tickStateMap = new WeakMap()
+
+export const isConnected = el =>
+  typeof el?.isConnected === 'boolean' ? el.isConnected : !!el?.parentNode
+
+const isThenable = x =>
+  !!x
+  && (typeof x === 'object' || typeof x === 'function')
+  && typeof x.then === 'function'
+
+export const stopTickLoop = el =>
+  (state =>
+    !state ? undefined
+      : (state.running = false,
+      state.rafId != null
+          && typeof window?.cancelAnimationFrame === 'function'
+          && window.cancelAnimationFrame(state.rafId),
+      tickStateMap.delete(el),
+      undefined)
+  )(tickStateMap.get(el))
+
+/**
+ * Start (or restart) a tick loop for an element.
+ *
+ * The handler signature is:
+ *
+ * ```js
+ * (el, ctx, dtMs) => nextCtx | undefined
+ * ```
+ *
+ * Returning `undefined` preserves the previous `ctx`. Returning any other value
+ * replaces `ctx` for the next tick.
+ *
+ * If the handler throws (or returns a Promise), ticking stops.
+ *
+ * @template Ctx
+ * @param {Element} el
+ * @param {(el: Element, ctx: any, dtMs: number) => (any | void)} handler
+ * @param {{ ready?: (el: Element) => boolean }} [options]
+ */
+export const startTickLoop = (el, handler, { ready = () => true } = {}) => {
+  const canTick =
+    typeof window !== 'undefined'
+    && typeof window.requestAnimationFrame === 'function'
+
+  if (!canTick) return
+
+  const existing = tickStateMap.get(el)
+
+  if (existing?.handler === handler
+    && existing?.ready === ready
+    && existing?.running) return
+
+  existing && stopTickLoop(el)
+
+  const state = {
+    handler,
+    ready,
+    ctx: undefined,
+    lastTime: null,
+    rafId: null,
+    wasConnected: false,
+    running: true
+  }
+
+  tickStateMap.set(el, state)
+
+  const step = t => {
+    const connected = isConnected(el)
+    if (!state.running || (!connected && state.wasConnected))
+      return stopTickLoop(el)
+
+    if (!connected) {
+      state.lastTime = null
+      state.rafId = window.requestAnimationFrame(step)
+      return
+    }
+
+    state.wasConnected = true
+
+    if (!ready(el)) {
+      state.lastTime = null
+      state.rafId = window.requestAnimationFrame(step)
+      return
+    }
+
+    const dt = state.lastTime == null ? 0 : t - state.lastTime
+    state.lastTime = t
+
+    let next
+    try { next = handler.call(el, el, state.ctx, dt) }
+    catch (err) { stopTickLoop(el); throw err }
+
+    if (isThenable(next)) {
+      stopTickLoop(el)
+      throw new TypeError('ontick must be synchronous (no Promises).')
+    }
+
+    next !== undefined && (state.ctx = next)
+    state.running && (state.rafId = window.requestAnimationFrame(step))
+  }
+
+  state.rafId = window.requestAnimationFrame(step)
+}