fix: SerializableHead input support and exports

harlan-zw · harlan-zw · commit b67d6dd3da43 · 2025-02-27T13:25:40.000+11:00
diff --git a/packages/unhead/src/composables.ts b/packages/unhead/src/composables.ts
@@ -2,19 +2,22 @@ import type {
   ActiveHeadEntry,
   HeadEntryOptions,
   HeadSafe,
+  ResolvableHead,
+  SerializableHead,
   Unhead,
   UseSeoMetaInput,
 } from './types'
 import { FlatMetaPlugin } from './plugins/flatMeta'
 import { SafeInputPlugin } from './plugins/safe'
 
-export function useHead<T extends Unhead<any>>(unhead: T, input: Parameters<T['push']>[0] = {}, options: HeadEntryOptions = {}): ReturnType<T['push']> {
-  return unhead.push(input, options) as ReturnType<T['push']>
+export function useHead<T extends Unhead<any>>(unhead: T, input: ResolvableHead | SerializableHead = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<ResolvableHead | SerializableHead> {
+  return unhead.push(input, options) as ActiveHeadEntry<ResolvableHead | SerializableHead>
 }
 
 export function useHeadSafe<T extends Unhead<any>>(unhead: T, input: HeadSafe = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<HeadSafe> {
   unhead.use(SafeInputPlugin)
-  return useHead(unhead, input, Object.assign(options, { _safe: true }))
+  // @ts-expect-error untyped
+  return useHead(unhead, input, Object.assign(options, { _safe: true })) as ActiveHeadEntry<HeadSafe>
 }
 
 export function useSeoMeta<T extends Unhead<any>>(unhead: T, input: UseSeoMetaInput = {}, options?: HeadEntryOptions): ActiveHeadEntry<UseSeoMetaInput> {
diff --git a/packages/unhead/src/scripts/useScript.ts b/packages/unhead/src/scripts/useScript.ts
@@ -1,5 +1,5 @@
 import type {
-  ResolvedHead,
+  SerializableHead,
   Unhead,
 } from '../types'
 import type {
@@ -136,7 +136,7 @@ export function useScript<T extends Record<symbol | string, any> = Record<symbol
         const $url = new URL(src)
         href = `${$url.protocol}//${$url.host}`
       }
-      const link: Required<ResolvedHead>['link'][0] = {
+      const link: Required<SerializableHead>['link'][0] = {
         href,
         rel,
         crossorigin: input.crossorigin || isCrossOrigin ? 'anonymous' : undefined,
@@ -154,7 +154,7 @@ export function useScript<T extends Record<symbol | string, any> = Record<symbol
       script._triggerPromises = [] // clear any pending promises
       if (!script.entry) {
         syncStatus('loading')
-        const defaults: Required<ResolvedHead>['script'][0] = {
+        const defaults: Required<SerializableHead>['script'][0] = {
           defer: true,
           fetchpriority: 'low',
         }
diff --git a/packages/unhead/src/server/util/extractUnheadInputFromHtml.ts b/packages/unhead/src/server/util/extractUnheadInputFromHtml.ts
@@ -1,4 +1,4 @@
-import type { ResolvedHead } from '../../types'
+import type { SerializableHead } from '../../types'
 
 const Attrs = /(\w+)(?:=["']([^"']*)["'])?/g
 const HtmlTag = /<html[^>]*>/
@@ -9,34 +9,35 @@ const ClosingTags = /<(title|script|style)[^>]*>[\s\S]*?<\/\1>/g
 // eslint-disable-next-line regexp/no-misleading-capturing-group
 const NewLines = /(\n\s*)+/g
 
-function extractAttributes(tag: string) {
+function extractAttributes<K extends 'htmlAttrs' | 'bodyAttrs' | 'meta'>(tag: string): SerializableHead[K] {
   // inner should be between the < and > (non greedy), split on ' ' and after index 0
   const inner = tag.match(/<([^>]*)>/)?.[1].split(' ').slice(1).join(' ')
   if (!inner)
-    return {}
+    return {} as SerializableHead[K]
   const attrs = inner.match(Attrs)
-  return attrs?.reduce((acc, attr) => {
+  return (attrs?.reduce((acc, attr) => {
     const sep = attr.indexOf('=')
     const key = sep > 0 ? attr.slice(0, sep) : attr
     const val = sep > 0 ? attr.slice(sep + 1).slice(1, -1) : true
     return { ...acc, [key]: val }
-  }, {}) || {}
+  }, {}) || {}) as SerializableHead[K]
 }
 
 export function extractUnheadInputFromHtml(html: string) {
-  const input: ResolvedHead<any> = {}
-  input.htmlAttrs = extractAttributes(html.match(HtmlTag)?.[0] || '')
+  const input = {} as SerializableHead
+  input.htmlAttrs = extractAttributes<'htmlAttrs'>(html.match(HtmlTag)?.[0] || '')
   html = html.replace(HtmlTag, '<html>')
 
-  input.bodyAttrs = extractAttributes(html.match(BodyTag)?.[0] || '')
+  input.bodyAttrs = extractAttributes<'bodyAttrs'>(html.match(BodyTag)?.[0] || '')
   html = html.replace(BodyTag, '<body>')
 
   const innerHead = html.match(HeadContent)?.[1] || ''
   innerHead.match(SelfClosingTags)?.forEach((s) => {
     html = html.replace(s, '')
     const tag = s.split(' ')[0].slice(1) as 'meta'
     input[tag] = input[tag] || []
-    input[tag].push(extractAttributes(s) as any)
+    // @ts-expect-error untyped
+    input[tag].push(extractAttributes<'meta'>(s))
   })
 
   innerHead.match(ClosingTags)
diff --git a/packages/unhead/src/types/head.ts b/packages/unhead/src/types/head.ts
@@ -1,7 +1,7 @@
 import type { Hookable, NestedHooks } from 'hookable'
 import type { HeadHooks } from './hooks'
 import type { DomPluginOptions } from './plugins'
-import type { ResolvableHead } from './schema'
+import type { ResolvableHead, SerializableHead } from './schema'
 import type { HeadTag, ProcessesTemplateParams, ResolvesDuplicates, TagPosition, TagPriority, TemplateParams } from './tags'
 
 /**
@@ -110,7 +110,7 @@ export interface CreateHeadOptions {
    *
    * Any tags here are added with low priority.
    */
-  init?: (ResolvableHead<any> | undefined)[]
+  init?: (ResolvableHead<any> | SerializableHead<any> | undefined)[]
   /**
    * Disable the Capo.js tag sorting algorithm.
    *
@@ -158,7 +158,7 @@ export interface HeadEntryOptions extends TagPosition, TagPriority, ProcessesTem
   _index?: number
 }
 
-export interface Unhead<Input = ResolvableHead> {
+export interface Unhead<Input = ResolvableHead | SerializableHead> {
   /**
    * Registered plugins.
    */
diff --git a/packages/unhead/src/types/schema/head.ts b/packages/unhead/src/types/schema/head.ts
@@ -52,13 +52,13 @@ export interface BodyAttr extends Omit<BaseBodyAttr, 'class' | 'style'> {
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class
    */
-  class?: MaybeArray<string> | Record<string, boolean>
+  class?: MaybeArray<ResolvableValue<Stringable>> | Record<string, ResolvableValue<boolean>>
   /**
    * The style attribute contains CSS styling declarations to be applied to the element.
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
    */
-  style?: MaybeArray<string> | Record<string, ResolvableValue<string>>
+  style?: MaybeArray<ResolvableValue<Stringable>> | Record<string, ResolvableValue<Stringable>>
 }
 
 export interface HtmlAttr extends Omit<_HtmlAttributes, 'class' | 'style'> {
@@ -67,13 +67,13 @@ export interface HtmlAttr extends Omit<_HtmlAttributes, 'class' | 'style'> {
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class
    */
-  class?: MaybeArray<string> | Record<string, boolean>
+  class?: MaybeArray<ResolvableValue<Stringable>> | Record<string, ResolvableValue<boolean>>
   /**
    * The style attribute contains CSS styling declarations to be applied to the element.
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
    */
-  style?: MaybeArray<string> | Record<string, ResolvableValue<string>>
+  style?: MaybeArray<ResolvableValue<Stringable>> | Record<string, ResolvableValue<Stringable>>
 }
 
 export interface BaseMeta extends Omit<_Meta, 'content'> {
@@ -193,7 +193,7 @@ export interface ResolvableHead<E extends MergeHead = SchemaAugmentations> exten
   bodyAttrs?: ResolvableValue<BodyAttributes<E['bodyAttrs']>>
 }
 
-export interface ResolvedHead<E extends MergeHead = ResolvedSchemaAugmentations> extends HeadUtils {
+export interface NormalizedHead<E extends MergeHead = ResolvedSchemaAugmentations> extends HeadUtils {
   title?: ResolvedTitle
   base?: ResolvedBase<E['base']>
   link?: ResolvedLink<E['link']>[]
@@ -205,9 +205,34 @@ export interface ResolvedHead<E extends MergeHead = ResolvedSchemaAugmentations>
   bodyAttrs?: ResolvedBodyAttributes<E['bodyAttrs']>
 }
 
-export type Head = ResolvableHead & ResolvedHead
+type AsSerializable<S extends keyof ResolvedSchemaAugmentations> = ResolvedSchemaAugmentations[S] & DataKeys
+
+export interface SerializableHead<E extends MergeHead = ResolvedSchemaAugmentations> {
+  /**
+   * Generate the title from a template.
+   *
+   * Should include a `%s` placeholder for the title, for example `%s - My Site`.
+   */
+  titleTemplate?: string
+  /**
+   * Variables used to substitute in the title and meta content.
+   */
+  templateParams?: Record<string, Record<string, string | boolean | number> | string | boolean | number>
+  title?: string | ({ textContent: string } & ResolvedSchemaAugmentations['title'])
+  base?: Partial<Merge<ResolvedSchemaAugmentations['base'], _Base>> & DefinedValueOrEmptyObject<E['base']>
+  link?: (LinkBase & AsSerializable<'link'> & HttpEventAttributes)[]
+  meta?: (_Meta & AsSerializable<'meta'>)[]
+  style?: (_Style & AsSerializable<'style'>)[]
+  script?: (ScriptBase & AsSerializable<'script'> & HttpEventAttributes)[]
+  noscript?: (_Noscript & AsSerializable<'noscript'>)[]
+  htmlAttrs?: _HtmlAttributes & AsSerializable<'htmlAttrs'>
+  bodyAttrs?: BaseBodyAttr & AsSerializable<'bodyAttrs'> & BodyEvents
+}
+
+export type Head = SerializableHead
+export type ResolvedHead = SerializableHead
 
 export type UseSeoMetaInput = MetaFlatInput & { title?: Title, titleTemplate?: TitleTemplate }
-export type UseHeadInput<T extends MergeHead = MergeHead> = ResolvableHead<T>
+export type UseHeadInput<T extends MergeHead = MergeHead> = ResolvableHead<T> | SerializableHead<T>
 
 export { type BodyEvents, type DataKeys, type HttpEventAttributes, type LinkBase, type MetaFlatInput, type ScriptBase }
diff --git a/packages/unhead/test/unit/types.test.ts b/packages/unhead/test/unit/types.test.ts
@@ -1,3 +1,4 @@
+import type { SerializableHead } from '../../src/types'
 import { useHead, useHeadSafe, useSeoMeta } from '../../src/composables'
 import { createHead } from '../../src/server'
 
@@ -56,4 +57,30 @@ describe('types', () => {
       },
     })
   })
+  it('types SerializableHead', () => {
+    const head = createHead()
+    const input: SerializableHead = {
+      title: 'Hello',
+      meta: [
+        { name: 'description', content: 'Static content' },
+        { property: 'og:image', content: 'https://example.com/1.jpg' },
+      ],
+      script: [
+        { src: 'https://example.com/script.js' },
+      ],
+      link: [
+        { rel: 'stylesheet', href: 'style1.css' },
+      ],
+      // Validate HTML attributes
+      htmlAttrs: {
+        lang: 'en',
+        class: 'dark',
+      },
+      // Validate body attributes
+      bodyAttrs: {
+        class: 'bg-gray-100',
+      },
+    }
+    useHead(head, input)
+  })
 })
diff --git a/packages/vue/src/types/index.ts b/packages/vue/src/types/index.ts
@@ -1,4 +1,4 @@
 export type * from './safeSchema'
 export type * from './schema'
 export type * from './util'
-export type { ActiveHeadEntry, Head, HeadEntryOptions, HeadTag, MergeHead, RenderSSRHeadOptions, ResolvableHead, ResolvedBase, ResolvedBodyAttributes, ResolvedHead, ResolvedHtmlAttributes, ResolvedLink, ResolvedMeta, ResolvedNoscript, ResolvedScript, ResolvedStyle, ResolvedTitle, ResolvedTitleTemplate, Unhead } from 'unhead/types'
+export type { ActiveHeadEntry, Head, HeadEntryOptions, HeadTag, MergeHead, NormalizedHead, RenderSSRHeadOptions, ResolvableHead, ResolvedBase, ResolvedBodyAttributes, ResolvedHtmlAttributes, ResolvedLink, ResolvedMeta, ResolvedNoscript, ResolvedScript, ResolvedStyle, ResolvedTitle, ResolvedTitleTemplate, SerializableHead, Unhead } from 'unhead/types'
diff --git a/packages/vue/src/utils.ts b/packages/vue/src/utils.ts
@@ -1,4 +1,3 @@
-import type { ResolvedHead } from 'unhead/types'
 import { walkResolver } from 'unhead/utils'
 import { VueResolver } from './resolver'
 
@@ -7,7 +6,7 @@ export * from 'unhead/utils'
 /**
  * @deprecated Use head.resolveTags() instead
  */
-export function resolveUnrefHeadInput(input: any): ResolvedHead {
+export function resolveUnrefHeadInput<T extends Record<string, any>>(input: T): T {
   return walkResolver(input, VueResolver)
 }
 
