feat(render): add refs, onNodeMount, and element-specific attrs 🍞

NeaByteLab · NeaByteLab · commit e30593d52d1c · 2026-03-09T08:04:29.000+07:00
- Export el from Schema2UI.el in index
- Add scrollMargin to Style and Types.Style
- Add iframe loading (eager/lazy) and label for→htmlFor in Attrs
- Add RenderOptions (refs, onNodeMount, signal) and pass through render/renderNode
- Alias DOM Element as DomElement in Main to avoid clash with Element class
diff --git a/src/Render/Attrs.ts b/src/Render/Attrs.ts
@@ -52,6 +52,14 @@ export default class Attrs {
         element.decoding = stringifiedValue as 'async' | 'sync' | 'auto'
         continue
       }
+      if (
+        key === 'loading' &&
+        element instanceof HTMLIFrameElement &&
+        typeof value === 'string'
+      ) {
+        element.loading = stringifiedValue as 'eager' | 'lazy'
+        continue
+      }
       if (key === 'download' && element instanceof HTMLAnchorElement) {
         if (value === undefined || value === null || value === false) {
           element.download = ''
@@ -61,6 +69,11 @@ export default class Attrs {
         }
         continue
       }
+      if (key === 'for' && element instanceof HTMLLabelElement) {
+        element.setAttribute('for', stringifiedValue)
+        element.htmlFor = stringifiedValue
+        continue
+      }
       try {
         element.setAttribute(key, stringifiedValue)
       } catch {
diff --git a/src/Render/Main.ts b/src/Render/Main.ts
@@ -1,27 +1,30 @@
 import type * as Types from '@app/Types.ts'
 import Constant from '@app/Constant.ts'
 import Attrs from '@app/Render/Attrs.ts'
+import Element from '@app/Render/Element.ts'
 import Layout from '@app/Render/Layout.ts'
-import RenderElement from '@app/Render/Element.ts'
 import Style from '@app/Render/Style.ts'
 
+/** DOM Element type alias (avoid clash with imported Element class). */
+type DomElement = InstanceType<typeof globalThis.Element>
+
 /**
  * Renders schema to DOM.
  * @description Builds elements from nodes and applies layout and style.
  */
 export default class Render {
   /** SVG root tag name. */
-  static readonly svgTagName: string = RenderElement.svgTagName
+  static readonly svgTagName: string = Element.svgTagName
   /** Template element tag name. */
-  static readonly templateTagName: string = RenderElement.templateTagName
+  static readonly templateTagName: string = Element.templateTagName
 
   /**
    * Apply attribute map to element.
    * @description Sets class, value, style string, and generic attributes.
    * @param element - Target DOM element
    * @param attrs - Attribute key-value map
    */
-  static applyAttrs(element: Element, attrs: Types.Attrs): void {
+  static applyAttrs(element: DomElement, attrs: Types.Attrs): void {
     Attrs.applyAttrs(element, attrs)
   }
 
@@ -63,26 +66,55 @@ export default class Render {
    * @param isSvg - Whether parent is SVG context
    * @returns Created DOM element
    */
-  static createElementForNode(node: Types.Node, doc: Document, isSvg: boolean): Element {
-    return RenderElement.createElementForNode(node, doc, isSvg)
+  static createElementForNode(node: Types.Node, doc: Document, isSvg: boolean): DomElement {
+    return Element.createElementForNode(node, doc, isSvg)
   }
 
   /**
    * Render schema root into container.
-   * @description Appends each root node result to container.
+   * @description Appends each root node result to container; optional refs and onNodeMount.
    * @param schema - Frozen schema
    * @param container - Target HTML element
+   * @param options - Optional refs map and onNodeMount callback
    */
-  static render(schema: Types.Schema, container: HTMLElement): void {
+  static render(schema: Types.Schema, container: HTMLElement, options?: Types.RenderOptions): void {
     const ownerDoc = container.ownerDocument ?? document
+    let renderContext:
+      | {
+        refs?: Map<string, DomElement>
+        onNodeMount?: (node: Types.Node, element: DomElement) => void
+        mounted?: Array<{ node: Types.Node; element: DomElement }>
+      }
+      | undefined
+    if (options) {
+      renderContext = {}
+      if (options.refs !== undefined) {
+        renderContext.refs = options.refs
+      }
+      if (options.onNodeMount !== undefined) {
+        renderContext.onNodeMount = options.onNodeMount
+        renderContext.mounted = []
+      }
+      if (Object.keys(renderContext).length === 0) {
+        renderContext = undefined
+      }
+    }
     for (const node of schema.root) {
-      const result = Render.renderNode(node, ownerDoc, false)
-      if (result instanceof DocumentFragment) {
-        while (result.firstChild) {
-          container.appendChild(result.firstChild)
+      const nodeResult = Render.renderNode(node, ownerDoc, false, renderContext)
+      if (nodeResult instanceof DocumentFragment) {
+        while (nodeResult.firstChild) {
+          container.appendChild(nodeResult.firstChild)
         }
       } else {
-        container.appendChild(result)
+        container.appendChild(nodeResult)
+      }
+      if (renderContext?.refs && node.id) {
+        renderContext.refs.set(node.id, nodeResult as DomElement)
+      }
+    }
+    if (renderContext?.onNodeMount && renderContext.mounted) {
+      for (const { node, element } of renderContext.mounted) {
+        renderContext.onNodeMount(node, element)
       }
     }
   }
@@ -93,16 +125,27 @@ export default class Render {
    * @param node - Schema node
    * @param doc - Document to create in
    * @param parentIsSvg - Whether parent is SVG context
+   * @param renderContext - Optional context for refs and onNodeMount
    * @returns Created element or DocumentFragment for template
    */
   static renderNode(
     node: Types.Node,
     doc: Document,
-    parentIsSvg: boolean
-  ): Element | DocumentFragment {
-    const tag = node.type
-    const isSvg = parentIsSvg || tag === Render.svgTagName
+    parentIsSvg: boolean,
+    renderContext?: {
+      refs?: Map<string, DomElement>
+      mounted?: Array<{ node: Types.Node; element: DomElement }>
+    }
+  ): DomElement | DocumentFragment {
+    const tagName = node.type
+    const isSvg = parentIsSvg || tagName === Render.svgTagName
     const element = Render.createElementForNode(node, doc, isSvg)
+    if (renderContext?.refs && node.id) {
+      renderContext.refs.set(node.id, element as DomElement)
+    }
+    if (renderContext?.mounted) {
+      renderContext.mounted.push({ node, element: element as DomElement })
+    }
     if (node.id && element instanceof HTMLElement) {
       element.id = node.id
     }
@@ -130,21 +173,27 @@ export default class Render {
         element.appendChild(doc.createTextNode(node.content))
       }
     }
-    if (!Constant.voidTags.has(tag) && node.children && node.children.length > 0) {
-      let target: DocumentFragment | Element
+    if (!Constant.voidTags.has(tagName) && node.children && node.children.length > 0) {
+      let appendTarget: DocumentFragment | DomElement
       if (element instanceof HTMLTemplateElement) {
-        target = element.content
+        appendTarget = element.content
       } else {
-        target = element
+        appendTarget = element
       }
       for (const child of node.children) {
-        const childResult = Render.renderNode(child, doc, isSvg)
+        const childResult = Render.renderNode(child, doc, isSvg, renderContext)
         if (childResult instanceof DocumentFragment) {
           while (childResult.firstChild) {
-            target.appendChild(childResult.firstChild)
+            appendTarget.appendChild(childResult.firstChild)
           }
         } else {
-          target.appendChild(childResult)
+          appendTarget.appendChild(childResult)
+        }
+        if (renderContext?.refs && child.id) {
+          renderContext.refs.set(child.id, childResult as DomElement)
+        }
+        if (renderContext?.mounted) {
+          renderContext.mounted.push({ node: child, element: childResult as DomElement })
         }
       }
     }
diff --git a/src/Render/Style.ts b/src/Render/Style.ts
@@ -46,6 +46,9 @@ export default class Style {
     if (style.transition) {
       elementStyle.transition = style.transition
     }
+    if (style.scrollMargin) {
+      elementStyle.scrollMargin = style.scrollMargin
+    }
   }
 
   /**
diff --git a/src/Types.ts b/src/Types.ts
@@ -63,15 +63,28 @@ export type Schema = {
   readonly root: readonly Node[]
 }
 
+/**
+ * Options passed to render for refs and lifecycle.
+ * @description Optional refs map and onNodeMount callback.
+ */
+export type RenderOptions = {
+  /** Optional AbortSignal for future listener cleanup. */
+  signal?: AbortSignal
+  /** Callback invoked after each node element is mounted (appended to parent). */
+  onNodeMount?: (node: Node, element: Element) => void
+  /** Map to populate with node id → element for nodes that have an id. */
+  refs?: Map<string, Element>
+}
+
 /**
  * Default export shape: create and render.
  * @description Returned when calling Schema2UI().
  */
 export type Schema2UIDefault = {
   /** Create schema from definition */
   create: (definition: Definition | unknown) => Schema
-  /** Render schema into container element */
-  render: (schema: Schema, container: HTMLElement) => void
+  /** Render schema into container element. */
+  render: (schema: Schema, container: HTMLElement, options?: RenderOptions) => void
 }
 
 /**
@@ -107,6 +120,8 @@ export type Style = {
   opacity?: string
   /** Padding (CSS padding) */
   padding?: string
+  /** Scroll margin (CSS scroll-margin). */
+  scrollMargin?: string
   /** Border or stroke (→ border) */
   stroke?: string
   /** Transition (CSS transition) */
diff --git a/src/index.ts b/src/index.ts
@@ -63,12 +63,13 @@ class Schema2UI {
 
   /**
    * Render schema into container element.
-   * @description Appends each root node DOM to container.
+   * @description Appends root node DOM to container; optional refs and onNodeMount.
    * @param schema - Frozen schema
    * @param container - Target HTML element
+   * @param options - Optional refs map and onNodeMount callback
    */
-  static render(schema: Types.Schema, container: HTMLElement): void {
-    Render.render(schema, container)
+  static render(schema: Types.Schema, container: HTMLElement, options?: Types.RenderOptions): void {
+    Render.render(schema, container, options)
   }
 }
 
@@ -87,13 +88,18 @@ export function create(definition: Types.Definition | unknown): Types.Schema {
  * @description Delegates to Schema2UI.render.
  * @param schema - Frozen schema
  * @param container - Target HTML element
+ * @param options - Optional refs map and onNodeMount callback
  */
-export function render(schema: Types.Schema, container: HTMLElement): void {
-  return Schema2UI.render(schema, container)
+export function render(
+  schema: Types.Schema,
+  container: HTMLElement,
+  options?: Types.RenderOptions
+): void {
+  return Schema2UI.render(schema, container, options)
 }
 
-/** Element helper namespace (root, node, tag aliases). */
-export const el: Types.El = Schema2UI.defaultExport.el
+/** Element helper namespace (from Schema2UI.el). */
+export const el: Types.El = Schema2UI.el
 
 /** Re-export Types namespace from Types.ts. */
 export type * as Types from '@app/Types.ts'

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,9 @@ export default class Style {`
`46`	`46`	`if (style.transition) {`
`47`	`47`	`elementStyle.transition = style.transition`
`48`	`48`	`}`
	`49`	`+ if (style.scrollMargin) {`
	`50`	`+ elementStyle.scrollMargin = style.scrollMargin`
	`51`	`+ }`
`49`	`52`	`}`
`50`	`53`
`51`	`54`	`/**`