feat: improved hooks and DOM triggering

Author: harlan-zw

packages/dom/README.md

@@ -0,0 +1,12 @@
+# @unhead/dom
+
+## Install
+
+```bash
+# yarn add @unhead/dom
+npm install @unhead/dom
+```
+
+## Documentation
+
+See the [@unhead/dom](https://unhead.harlanzw.com/guide/getting-started/how-it-works#unheaddom) for how this works.

packages/dom/src/renderDOMHead.ts

@@ -1,5 +1,5 @@
 import { TagsWithInnerContent, createElement } from 'zhead'
-import type { DomRenderTagContext, HeadClient } from '@unhead/schema'
+import type { BeforeRenderContext, DomRenderTagContext, Unhead } from '@unhead/schema'
 import { setAttributesWithSideEffects } from './setAttributesWithSideEffects'
 
 export interface RenderDomHeadOptions {
@@ -12,16 +12,22 @@ export interface RenderDomHeadOptions {
 /**
  * Render the head tags to the DOM.
  */
-export async function renderDOMHead<T extends HeadClient<any>>(head: T, options: RenderDomHeadOptions = {}) {
+export async function renderDOMHead<T extends Unhead<any>>(head: T, options: RenderDomHeadOptions = {}) {
   const dom: Document = options.document || window.document
 
   const tags = await head.resolveTags()
 
-  await head.hooks.callHook('dom:beforeRender', { head, tags, document: dom })
+  const context: BeforeRenderContext = { shouldRender: true, tags }
+  await head.hooks.callHook('dom:beforeRender', context)
+  // allow integrations to block to the render
+  if (!context.shouldRender)
+    return
 
-  for (const tag of tags) {
-    const renderCtx: DomRenderTagContext = { tag, document: dom, head }
+  for (const tag of context.tags) {
+    const renderCtx: DomRenderTagContext = { shouldRender: true, tag }
     await head.hooks.callHook('dom:renderTag', renderCtx)
+    if (!renderCtx.shouldRender)
+      return
 
     const entry = head.headEntries().find(e => e._i === Number(tag._e))!
 
@@ -94,12 +100,13 @@ export let domUpdatePromise: Promise<void> | null = null
 /**
  * Queue a debounced update of the DOM head.
  */
-export async function debouncedRenderDOMHead<T extends HeadClient<any>>(delayedFn: (fn: () => void) => void, head: T, options: RenderDomHeadOptions = {}) {
+export async function debouncedRenderDOMHead<T extends Unhead<any>>(head: T, options: RenderDomHeadOptions & { delayFn?: (fn: () => void) => void } = {}) {
   // within the debounced dom update we need to compute all the tags so that watchEffects still works
   function doDomUpdate() {
     domUpdatePromise = null
     return renderDOMHead(head, options)
   }
-
-  return domUpdatePromise = domUpdatePromise || new Promise(resolve => delayedFn(() => resolve(doDomUpdate())))
+  // we want to delay for the hydration chunking
+  const delayFn = options.delayFn || (fn => setTimeout(fn, 25))
+  return domUpdatePromise = domUpdatePromise || new Promise(resolve => delayFn(() => resolve(doDomUpdate())))
 }

packages/dom/src/setAttributesWithSideEffects.ts

@@ -1,9 +1,9 @@
-import type { HeadClient, HeadEntry, HeadTag } from '@unhead/schema'
+import type { HeadEntry, HeadTag, Unhead } from '@unhead/schema'
 
 /**
  * Set attributes on a DOM element, while adding entry side effects.
  */
-export function setAttributesWithSideEffects(head: HeadClient, $el: Element, entry: HeadEntry<any>, tag: HeadTag) {
+export function setAttributesWithSideEffects(head: Unhead, $el: Element, entry: HeadEntry<any>, tag: HeadTag) {
   const attrs = tag.props || {}
   const sdeKey = `${tag._p}:attr`
 

packages/schema/src/head.ts

@@ -12,11 +12,11 @@ export type SideEffectsRecord = Record<string, () => void>
 
 export type RuntimeMode = 'server' | 'client' | 'all'
 
-export interface HeadEntry<T> {
+export interface HeadEntry<Input> {
   /**
    * User provided input for the entry.
    */
-  input: T
+  input: Input
   /**
    * The mode that the entry should be used in.
    *
@@ -42,13 +42,13 @@ export type HeadPlugin = Omit<CreateHeadOptions, 'plugins'>
 /**
  * An active head entry provides an API to manipulate it.
  */
-export interface ActiveHeadEntry<T> {
+export interface ActiveHeadEntry<Input> {
   /**
    * Updates the entry with new input.
    *
    * Will first clear any side effects for previous input.
    */
-  patch: (resolvedInput: T) => void
+  patch: (input: Input) => void
   /**
    * Dispose the entry, removing it from the active head.
    *
@@ -58,6 +58,8 @@ export interface ActiveHeadEntry<T> {
 }
 
 export interface CreateHeadOptions {
+  domDelayFn?: (fn: () => void) => void
+  document?: Document
   plugins?: HeadPlugin[]
   hooks?: NestedHooks<HeadHooks>
 }
@@ -66,15 +68,15 @@ export interface HeadEntryOptions {
   mode?: RuntimeMode
 }
 
-export interface HeadClient<T extends {} = Head> {
+export interface Unhead<Input extends {} = Head> {
   /**
    * The active head entries.
    */
-  headEntries: () => HeadEntry<T>[]
+  headEntries: () => HeadEntry<Input>[]
   /**
    * Create a new head entry.
    */
-  push: (entry: T, options?: HeadEntryOptions) => ActiveHeadEntry<T>
+  push: (entry: Input, options?: HeadEntryOptions) => ActiveHeadEntry<Input>
   /**
    * Resolve tags from head entries.
    */

packages/schema/src/hooks.ts

@@ -1,4 +1,4 @@
-import type { HeadClient, HeadEntry } from './head'
+import type { HeadEntry, Unhead } from './head'
 import type { HeadTag } from './tags'
 
 export type HookResult = Promise<void> | void
@@ -12,20 +12,22 @@ export interface SSRHeadPayload {
 }
 
 export interface EntryResolveCtx<T> { tags: HeadTag[]; entries: HeadEntry<T>[] }
-export interface DomRenderTagContext { head: HeadClient; tag: HeadTag; document: Document }
+export interface DomRenderTagContext { shouldRender: boolean; tag: HeadTag }
+export interface BeforeRenderContext { shouldRender: boolean; tags: HeadTag[] }
+export interface SSRRenderContext { tags: HeadTag[]; html: SSRHeadPayload }
 
 export interface HeadHooks {
-  'init': (ctx: HeadClient<any>) => HookResult
-  'entries:updated': (ctx: HeadClient<any>) => HookResult
+  'init': (ctx: Unhead<any>) => HookResult
+  'entries:updated': (ctx: Unhead<any>) => HookResult
   'entries:resolve': (ctx: EntryResolveCtx<any>) => HookResult
   'tag:normalise': (ctx: { tag: HeadTag; entry: HeadEntry<any> }) => HookResult
   'tags:resolve': (ctx: { tags: HeadTag[] }) => HookResult
 
   // @unhead/dom
-  'dom:beforeRender': (ctx: { head: HeadClient; tags: HeadTag[]; document: Document }) => HookResult
+  'dom:beforeRender': (ctx: BeforeRenderContext) => HookResult
   'dom:renderTag': (ctx: DomRenderTagContext) => HookResult
 
   // @unhead/ssr
-  'ssr:beforeRender': (ctx: { tags: HeadTag[] }) => HookResult
-  'ssr:render': (ctx: { tags: HeadTag[]; html: SSRHeadPayload }) => HookResult
+  'ssr:beforeRender': (ctx: BeforeRenderContext) => HookResult
+  'ssr:render': (ctx: SSRRenderContext) => HookResult
 }

packages/ssr/src/renderSSRHead.ts

@@ -1,12 +1,21 @@
 import { ssrRenderTags } from 'zhead'
-import type { HeadClient, SSRHeadPayload } from '@unhead/schema'
+import type { BeforeRenderContext, SSRHeadPayload, SSRRenderContext, Unhead } from '@unhead/schema'
 
-export async function renderSSRHead<T extends {}>(ctx: HeadClient<T>) {
-  const tags = await ctx.resolveTags()
-  const beforeRenderCtx = { tags }
-  await ctx.hooks.callHook('ssr:beforeRender', beforeRenderCtx)
+export async function renderSSRHead<T extends {}>(head: Unhead<T>) {
+  const tags = await head.resolveTags()
+  const beforeRenderCtx: BeforeRenderContext = { shouldRender: true, tags }
+  if (!beforeRenderCtx.shouldRender) {
+    return {
+      headTags: '',
+      bodyTags: '',
+      bodyTagsOpen: '',
+      htmlAttrs: '',
+      bodyAttrs: '',
+    }
+  }
+  await head.hooks.callHook('ssr:beforeRender', beforeRenderCtx)
   const html: SSRHeadPayload = ssrRenderTags(beforeRenderCtx.tags)
-  const renderCXx = { tags, html }
-  await ctx.hooks.callHook('ssr:render', renderCXx)
-  return renderCXx.html
+  const renderCtx: SSRRenderContext = { tags, html }
+  await head.hooks.callHook('ssr:render', renderCtx)
+  return renderCtx.html
 }

packages/unhead/src/createHead.ts

@@ -1,7 +1,7 @@
 import { createHooks } from 'hookable'
-import type { CreateHeadOptions, Head, HeadClient, HeadEntry, HeadHooks, HeadPlugin, HeadTag, SideEffectsRecord } from '@unhead/schema'
+import type { CreateHeadOptions, Head, HeadEntry, HeadHooks, HeadPlugin, HeadTag, SideEffectsRecord, Unhead } from '@unhead/schema'
 import { setActiveHead } from './runtime/state'
-import { DedupesTagsPlugin, DeprecatedTagAttrPlugin, SortTagsPlugin, TitleTemplatePlugin } from './plugin'
+import { DedupesTagsPlugin, DeprecatedTagAttrPlugin, PatchDomOnEntryUpdatesPlugin, SortTagsPlugin, TitleTemplatePlugin } from './plugin'
 import { normaliseEntryTags } from './normalise'
 
 export function createHead<T extends {} = Head>(options: CreateHeadOptions = {}) {
@@ -11,7 +11,7 @@ export function createHead<T extends {} = Head>(options: CreateHeadOptions = {})
   // counter for keeping unique ids of head object entries
   let entryId = 0
   const hooks = createHooks<HeadHooks>()
-  if (options.hooks)
+  if (options?.hooks)
     hooks.addHooks(options.hooks)
 
   const plugins: HeadPlugin[] = [
@@ -20,13 +20,14 @@ export function createHead<T extends {} = Head>(options: CreateHeadOptions = {})
     DedupesTagsPlugin(),
     SortTagsPlugin(),
     TitleTemplatePlugin(),
+    PatchDomOnEntryUpdatesPlugin({ document: options?.document, delayFn: options?.domDelayFn }),
   ]
   plugins.push(...(options.plugins || []))
   plugins.forEach(plugin => hooks.addHooks(plugin.hooks || {}))
 
   const triggerUpdate = () => hooks.callHook('entries:updated', head)
 
-  const head: HeadClient<T> = {
+  const head: Unhead<T> = {
     _removeQueuedSideEffect(key) {
       delete _sde[key]
     },

packages/unhead/src/plugin/index.ts

@@ -3,3 +3,4 @@ export * from './sortTagsPlugin'
 export * from './titleTemplatePlugin'
 export * from './deprecatedTagAttrPlugin'
 export * from './hydratesStatePlugin/hydratesStatePlugin'
+export * from './patchDomOnEntryUpdatesPlugin'

packages/unhead/src/plugin/patchDomOnEntryUpdatesPlugin.ts

@@ -0,0 +1,26 @@
+import { defineHeadPlugin } from '../defineHeadPlugin'
+import type { RenderDomHeadOptions } from '@unhead/dom'
+
+interface TriggerDomPatchingOnUpdatesPluginOptions extends RenderDomHeadOptions {
+  delayFn?: (fn: () => void) => void
+}
+
+export const PatchDomOnEntryUpdatesPlugin = (options?: TriggerDomPatchingOnUpdatesPluginOptions) => {
+  return defineHeadPlugin({
+    hooks: {
+      'entries:updated': function (head) {
+        // only if we have a document, avoid unhead/dom in ssr
+        if (typeof options?.document === 'undefined' && typeof window === 'undefined')
+          return
+        let delayFn = options?.delayFn
+        if (!delayFn && typeof requestAnimationFrame !== 'undefined')
+          delayFn = requestAnimationFrame
+
+        // async load the renderDOMHead function
+        import('@unhead/dom').then(({ debouncedRenderDOMHead }) => {
+          debouncedRenderDOMHead(head, { document: options?.document || window.document, delayFn })
+        })
+      },
+    },
+  })
+}

packages/unhead/src/runtime/state.ts

@@ -1,7 +1,7 @@
-import type { HeadClient } from '@unhead/schema'
+import type { Unhead } from '@unhead/schema'
 
-export let activeHead: HeadClient<any> | undefined
+export let activeHead: Unhead<any> | undefined
 
-export const setActiveHead = <T extends HeadClient> (head: T | undefined) => (activeHead = head)
+export const setActiveHead = <T extends Unhead> (head: T | undefined) => (activeHead = head)
 
-export const getActiveHead = <T extends HeadClient> () => activeHead as T
+export const getActiveHead = <T extends Unhead> () => activeHead as T