@master/internal-site 0.0.0-stage → 0.1.0

package/src/docs-shell/utils/highlight-code-core.ts

@@ -0,0 +1,146 @@
+import type { HighlighterCore, ShikiTransformer } from 'shiki/core'
+import { transformerNotationDiff, transformerNotationFocus, transformerNotationHighlight, transformerRemoveLineBreak } from '@shikijs/transformers'
+import clsx from 'clsx'
+import { dedent } from 'ts-dedent'
+import { beautifyCSS } from '../utils/beautify-css'
+import beautifyJS from '../utils/beautify-js'
+import { beautifyHTML } from '../utils/beautify-html'
+import createHighlighter, { theme } from './create-highlighter'
+import transformerNotationWordMark from './transformer-notation-word-mark'
+import { defu } from 'defu'
+
+export type HighlightOptions = {
+  lang: string,
+  inline?: boolean,
+  beautify?: boolean
+  dedent?: boolean | 'block'
+  className?: string
+  [key: string]: unknown
+  transformers?: ShikiTransformer[]
+}
+
+/** Notation classes Shiki's transformers add to a line, read back as its `data-mark`. */
+const lineMarks = { added: 'notation-added', removed: 'notation-removed', active: 'notation-active' } as const
+export interface HighlightAdapter {
+  languages?: import('shiki/core').LanguageRegistration[]
+  resolveLanguage?: (language: string) => string
+  transformers?: (language: string, options: HighlightOptions) => ShikiTransformer[]
+}
+
+export function createCodeHighlighter(adapter: HighlightAdapter = {}) {
+  let highlighterPromise: Promise<HighlighterCore> | undefined
+  return async function highlightCode(code: string, options: HighlightOptions) {
+  options = defu(options, {
+    lang: 'plaintext',
+    inline: false,
+    beautify: false,
+    dedent: true,
+    mergeWhitespaces: false
+  } as HighlightOptions) as HighlightOptions
+  const transformers: ShikiTransformer[] = []
+  const lang = options.lang
+  const shikiLang = adapter.resolveLanguage?.(lang) ?? lang
+  if (options.beautify) {
+    switch (lang) {
+      case 'css':
+        code = beautifyCSS(code)
+        break
+      case 'html':
+        code = beautifyHTML(code)
+        break
+      default:
+        code = beautifyJS(code)
+        break
+    }
+  }
+  if (options.inline) {
+    transformers.push({
+      line(hast) {
+        hast.properties!.class = ''
+      },
+      code(element) {
+        element.properties!.class = clsx('shiki', options.className)
+      },
+      root(root) {
+        const code = (root.children![0] as any).children![0]
+        root.children = [code]
+      }
+    })
+  } else {
+    transformers.push(
+      transformerNotationDiff({
+        classLineAdd: lineMarks.added,
+        classLineRemove: lineMarks.removed,
+      }),
+      transformerRemoveLineBreak(),
+      transformerNotationWordMark(),
+      transformerNotationHighlight({
+        classActiveLine: lineMarks.active,
+      }),
+      transformerNotationFocus({
+        classActiveLine: 'focus',
+      }),
+      {
+        pre(element) {
+          element!.properties!.class = clsx(element!.properties!.class, options.className)
+          delete element!.properties!.style
+        },
+        code(element) {
+          delete element!.properties!.class
+          // Lines are `ui-code-line` parts; a notation's line state becomes their `data-mark`.
+          for (const line of element.children) {
+            if (line.type !== 'element') continue
+            const raw = line.properties.class
+            const classes = new Set((Array.isArray(raw) ? raw.map(String) : String(raw ?? '').split(/\s+/)).filter(Boolean))
+            for (const [mark, className] of Object.entries(lineMarks)) {
+              if (classes.delete(className)) line.properties.dataMark = mark
+            }
+            // An array: the Master CSS transformer finds lines by an exact `line` entry.
+            line.properties.class = [...classes, 'ui-code-line']
+          }
+        },
+      }
+    )
+  }
+  transformers.push(...(adapter.transformers?.(lang, options) ?? []))
+  if (options.transformers) {
+    transformers.push(...options.transformers)
+  }
+  const normalizedCode = options.dedent === false
+    ? trimCodeBlockBoundary(code)
+    : options.dedent === 'block'
+      ? dedentCodeBlock(code)
+      : dedent(code).trim()
+  const hast = (await (highlighterPromise ??= createHighlighter(adapter.languages))).codeToHast(normalizedCode, {
+    ...options,
+    lang: shikiLang,
+    theme,
+    transformers,
+  })
+  return hast
+}
+
+}
+
+export default createCodeHighlighter()
+
+function trimCodeBlockBoundary(code: string): string {
+  return code.replace(/^\r?\n/, '').replace(/\r?\n$/, '')
+}
+
+function dedentCodeBlock(code: string): string {
+  code = trimCodeBlockBoundary(code)
+  const lines = code.split(/\r?\n/)
+  const firstCodeLine = lines.find((line) => line.trim())
+  if (!firstCodeLine || !countIndent(firstCodeLine)) return code
+  const commonIndent = lines.reduce((minIndent, line) => {
+    if (!line.trim()) return minIndent
+    return Math.min(minIndent, countIndent(line))
+  }, Infinity)
+  if (!Number.isFinite(commonIndent) || commonIndent === 0) return code
+  return lines.map((line) => line.trim() ? line.slice(commonIndent) : '').join('\n')
+}
+
+function countIndent(line: string): number {
+  return line.match(/^[\t ]*/)?.[0].length ?? 0
+}

package/src/docs-shell/utils/highlight-code.ts

@@ -0,0 +1 @@
+export { default } from 'virtual:master-site/highlight'

package/src/docs-shell/utils/highlighted-code-text.ts

@@ -0,0 +1,27 @@
+import type { Element, Root, RootContent } from 'hast'
+
+function hasLineClass(element: Element): boolean {
+  const classes = element.properties?.class
+  if (Array.isArray(classes)) return classes.includes('line')
+  return typeof classes === 'string' && classes.split(/\s+/).includes('line')
+}
+
+function textContent(node: RootContent): string {
+  if (node.type === 'text') return node.value
+  if (node.type !== 'element') return ''
+  return node.children.map(textContent).join('')
+}
+
+/** Copy Shiki's rendered lines, without trailing whitespace left by notation markers. */
+export default function highlightedCodeText(root: Root): string {
+  const lines: string[] = []
+  const visit = (nodes: RootContent[]) => {
+    for (const node of nodes) {
+      if (node.type !== 'element') continue
+      if (hasLineClass(node)) lines.push(node.children.map(textContent).join('').replace(/[\t ]+$/u, ''))
+      else visit(node.children)
+    }
+  }
+  visit(root.children)
+  return lines.join('\n')
+}

package/src/docs-shell/utils/i18n-pathname.ts

@@ -0,0 +1,98 @@
+export type LocalePrefixMode = 'always' | 'canonical'
+
+export interface LocalizePathnameOptions {
+  defaultLocale: string
+  locale: string
+  locales: readonly string[]
+  localePrefixMode?: LocalePrefixMode
+  localizablePathnameRoots?: readonly string[]
+}
+
+const nonPagePathnameRoots = new Set([
+  '_next',
+  'api',
+  'assets',
+  'cdn',
+  'fonts',
+  'images',
+  'og',
+  'search'
+])
+
+export function localizePathname(href: string, {
+  defaultLocale,
+  locale,
+  locales,
+  localePrefixMode = 'canonical',
+  localizablePathnameRoots
+}: LocalizePathnameOptions) {
+  if (!href || !href.startsWith('/') || href.startsWith('//')) return href
+
+  const parsedHref = parseLocalHref(href)
+  if (!parsedHref || findPathnameLocale(parsedHref.pathname, locales)) return href
+  if (!isLocalizablePathname(parsedHref.pathname, localizablePathnameRoots)) return href
+
+  if (locale === defaultLocale && localePrefixMode !== 'always') return href
+
+  const localizedPathname = `/${locale}${parsedHref.pathname === '/' ? '' : parsedHref.pathname}`
+  return localizedPathname + parsedHref.suffix
+}
+
+export function canonicalizeDefaultLocalePathname(href: string, defaultLocale: string) {
+  const parsedHref = parseLocalHref(href)
+  if (!parsedHref) return href
+
+  const defaultLocalePrefix = `/${defaultLocale}`
+  if (parsedHref.pathname === defaultLocalePrefix) {
+    return '/' + parsedHref.suffix
+  }
+
+  if (parsedHref.pathname.startsWith(defaultLocalePrefix + '/')) {
+    return parsedHref.pathname.slice(defaultLocalePrefix.length) + parsedHref.suffix
+  }
+
+  return href
+}
+
+function parseLocalHref(href: string) {
+  const endIndex = firstPathnameEndIndex(href)
+  const pathname = href.slice(0, endIndex)
+  if (!pathname.startsWith('/')) return
+
+  return {
+    pathname,
+    suffix: href.slice(endIndex)
+  }
+}
+
+function firstPathnameEndIndex(href: string) {
+  const queryIndex = href.indexOf('?')
+  const hashIndex = href.indexOf('#')
+  if (queryIndex === -1) return hashIndex === -1 ? href.length : hashIndex
+  if (hashIndex === -1) return queryIndex
+  return Math.min(queryIndex, hashIndex)
+}
+
+function findPathnameLocale(pathname: string, locales: readonly string[]) {
+  const firstSegment = getFirstPathnameSegment(pathname)
+  return firstSegment && locales.includes(firstSegment)
+}
+
+function isLocalizablePathname(pathname: string, localizablePathnameRoots?: readonly string[]) {
+  if (pathname === '/') return true
+  if (hasFileExtension(pathname)) return false
+
+  const firstSegment = getFirstPathnameSegment(pathname)
+  if (!firstSegment || nonPagePathnameRoots.has(firstSegment)) return false
+
+  return !localizablePathnameRoots?.length || localizablePathnameRoots.includes(firstSegment)
+}
+
+function hasFileExtension(pathname: string) {
+  const lastSegment = pathname.split('/').pop() || ''
+  return /\.[^./]+$/.test(lastSegment)
+}
+
+function getFirstPathnameSegment(pathname: string) {
+  return pathname.split('/')[1] || ''
+}

package/src/docs-shell/utils/i18n.ts

@@ -0,0 +1,12 @@
+export async function createTranslation(locale: string, dictionaries: Record<string, () => Promise<any>>): Promise<(text: any) => string> {
+  const translations = await importTranslations(locale, dictionaries)
+  return (text: any) => (translations)[text || ''] || text
+}
+
+export const importTranslations = async (locale: string, dictionaries: Record<string, () => Promise<any>>) => {
+  if (!locale) {
+    throw new Error('locale is required')
+  }
+  const load = dictionaries[locale as keyof typeof dictionaries]
+  return await load()
+}

package/src/docs-shell/utils/is-date-within-seven-days.ts

@@ -0,0 +1,16 @@
+export default function isDateWithinSevenDays(dateString: string) {
+  // 获取当前日期
+  const currentDate = new Date()
+
+  // 将字符串转换为日期对象
+  const date = new Date(dateString)
+
+  // 计算日期差异（以毫秒为单位）
+  const difference = currentDate.getTime() - date.getTime()
+
+  // 将毫秒转换为天数
+  const daysDifference = Math.ceil(difference / (1000 * 3600 * 24))
+
+  // 判断是否在7天内
+  return daysDifference < 7
+}

package/src/docs-shell/utils/isBrowser.ts

@@ -0,0 +1 @@
+export const isBrowser = typeof window !== 'undefined'

package/src/docs-shell/utils/isInteractOutside.ts

@@ -0,0 +1,16 @@
+export function isInteractOutside(
+  target: Element,
+  event: any,
+  senseEdge = 0
+): boolean {
+  const x = event.clientX
+  const y = event.clientY
+  const rect = target.getBoundingClientRect()
+  const top = rect.top
+  const left = rect.left
+
+  return top > y + senseEdge
+    || top + rect.height < y - senseEdge
+    || left > x + senseEdge
+    || left + rect.width < x - senseEdge
+}

package/src/docs-shell/utils/markdown-tree.ts

@@ -0,0 +1,22 @@
+import { remark } from 'remark'
+import gfm from 'remark-gfm'
+import Slugger from 'github-slugger'
+import resolveHeading from './resolve-heading'
+
+const parser = remark().use(gfm)
+export const markdownTree = (source: string) => parser.parse(source)
+
+export function markdownHeadings(source: string) {
+  const slugger = new Slugger()
+  const headings: { id: string; title: string; depth: number }[] = []
+  function visit(node: any) {
+    if (node.type === 'heading' && (node.depth === 2 || node.depth === 3)) {
+      const title = node.children.filter((child: any) => child.type === 'text' || child.type === 'inlineCode').map((child: any) => child.value).join(' ').trim()
+      const resolved = resolveHeading(title, slugger.slug(title))
+      headings.push({ id: resolved.id!, title: resolved.title, depth: node.depth })
+    }
+    node.children?.forEach(visit)
+  }
+  visit(markdownTree(source))
+  return headings
+}

package/src/docs-shell/utils/metadata.ts

@@ -0,0 +1,25 @@
+import type { DefinedMetadata, Metadata } from '../types/Metadata'
+
+const contentFolder = '/site/content'
+
+/**
+ * Derive the canonical pathname and repository source path from a page's `metadata.ts`
+ * location under `site/content`. The machine-specific `fileURL` is dropped because
+ * metadata reaches island props, category data and client bundles.
+ */
+export default function define({ fileURL, ...metadata }: Metadata) {
+  const file = decodeURI(fileURL)
+  const index = file.indexOf(contentFolder + '/')
+  if (index === -1) {
+    throw new Error('Invalid metadata fileURL: ' + file)
+  }
+  const directory = file.slice(index + contentFolder.length + 1).split('/').slice(0, -1)
+  const pathname = '/' + directory
+    .filter((basename: string) => !basename.startsWith('('))
+    .join('/')
+  return {
+    ...metadata,
+    sourcePath: ['site/content', ...directory, 'content.mdx'].join('/'),
+    pathname
+  } as DefinedMetadata
+}

package/src/docs-shell/utils/prepared-code.ts

@@ -0,0 +1,21 @@
+import type { Root } from 'hast'
+import highlightedCodeText from './highlighted-code-text'
+
+export interface PreparedCode {
+  /** The complete highlighted `<pre>`. */
+  html: string
+  text: string
+}
+
+/** Store trusted Shiki HTML so a page renders the block without highlighting it again. */
+export async function prepareCode(tree: Root): Promise<PreparedCode> {
+  const pre = tree.children[0]
+  if (pre?.type !== 'element' || pre.tagName !== 'pre' || tree.children.length !== 1) {
+    throw new Error('Expected one highlighted code block')
+  }
+  const { hastToHtml } = await import('shiki/core')
+  return {
+    html: hastToHtml(tree),
+    text: highlightedCodeText(tree)
+  }
+}

package/src/docs-shell/utils/resolve-heading.d.ts

@@ -0,0 +1 @@
+export default function resolveHeading(title: string, id?: string): { title: string; id?: string; className?: string }

package/src/docs-shell/utils/resolve-heading.js

@@ -0,0 +1,19 @@
+export default function resolveHeading(title, id) {
+  const explicit = typeof title === 'string' && title.match(/\s+\{#([\w-]+)\}$/)
+  if (explicit) {
+    title = title.slice(0, explicit.index)
+    id = explicit[1]
+  }
+  const words = title?.split?.(' ')
+
+  if (words?.pop() === '[sr-only]') {
+    return {
+      title: words.join(' '),
+      id: id
+        ?.replace('-sr-only', '')
+        ?.replace('-[sr-only]', ''),
+      className: 'sr-only'
+    }
+  }
+  return { title, id }
+}

package/src/docs-shell/utils/search-pages.ts

@@ -0,0 +1,271 @@
+import FastGlob from 'fast-glob'
+import Slugger from 'github-slugger'
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { mdxjsEsm } from 'micromark-extension-mdxjs-esm'
+import { mdxjsEsmFromMarkdown } from 'mdast-util-mdxjs-esm'
+import * as acorn from 'acorn'
+import resolveHeading from './resolve-heading.js'
+import { writeIfChangedSync } from '../../scripts/write-if-changed'
+import { localizePathname, type LocalePrefixMode } from './i18n-pathname.js'
+
+const DEFAULT_METADATA_GLOB = './content/**/*metadata.ts'
+
+export interface SearchNode {
+  id?: string
+  tag?: string
+  text: string
+}
+
+export interface SearchPage {
+  category?: string
+  description: string
+  disabled?: boolean
+  identifiers?: SearchNode[]
+  nodes: SearchNode[]
+  title: string
+  url: string
+}
+
+export interface SearchPageEntry {
+  content?: string
+  localizedContent?: Record<string, string>
+  metadata: Record<string, any>
+  metadataPath?: string
+}
+
+export interface LoadSearchPageEntriesOptions {
+  cwd?: string
+  metadataGlob?: string
+}
+
+export interface CreateSearchPageOptions {
+  defaultLocale: string
+  entry: SearchPageEntry
+  locale: string
+  translate?: Translate
+}
+
+export interface GenerateSearchPagesOptions extends LoadSearchPageEntriesOptions {
+  defaultLocale: string
+  dictionariesDir?: string
+  locales: readonly string[]
+  outDir?: string
+  write?: boolean
+}
+
+type Translate = (text: string) => string
+
+interface MdxNode {
+  children?: MdxNode[]
+  depth?: number
+  type: string
+  value?: string
+}
+
+export async function generateSearchPages({
+  cwd = process.cwd(),
+  defaultLocale,
+  dictionariesDir = resolve(cwd, 'public/dictionaries'),
+  locales,
+  metadataGlob,
+  outDir = resolve(cwd, 'public/search'),
+  write = true
+}: GenerateSearchPagesOptions): Promise<Record<string, SearchPage[]>> {
+  const entries = await loadSearchPageEntries({ cwd, metadataGlob })
+  const result: Record<string, SearchPage[]> = {}
+  if (write) mkdirSync(outDir, { recursive: true })
+
+  for (const locale of locales) {
+    const translations = loadDictionaryTranslations(dictionariesDir, locale)
+    const translate = createDictionaryTranslate(translations)
+    const pages = entries
+      .map((entry) => createSearchPage({ defaultLocale, entry, locale, translate }))
+      .sort((a, b) => a.url.localeCompare(b.url))
+    result[locale] = pages
+    if (write) {
+      const filename = resolve(outDir, `${locale}.json`)
+      writeIfChangedSync(filename, JSON.stringify(pages))
+      console.log(`產生 ${filename} (${pages.length} search pages)`)
+    }
+  }
+  return result
+}
+
+export async function loadSearchPageEntries({
+  cwd = process.cwd(),
+  metadataGlob = DEFAULT_METADATA_GLOB
+}: LoadSearchPageEntriesOptions = {}): Promise<SearchPageEntry[]> {
+  const metadataPaths = FastGlob.sync(metadataGlob, { cwd })
+    .filter((metadataPath) => (existsSync(resolve(cwd, dirname(metadataPath), 'page.astro')) || existsSync(resolve(cwd, dirname(metadataPath), 'content.mdx'))))
+    .sort()
+
+  return await Promise.all(metadataPaths.map(async (metadataPath) => {
+    const metadataModule = await import(pathToFileURL(resolve(cwd, metadataPath)).href)
+    const contentPath = resolve(cwd, dirname(metadataPath), 'content.mdx')
+    const contentDir = resolve(cwd, dirname(metadataPath))
+    return {
+      content: existsSync(contentPath) ? readFileSync(contentPath, 'utf8') : undefined,
+      localizedContent: loadLocalizedContent(contentDir),
+      metadata: metadataModule.default,
+      metadataPath
+    }
+  }))
+}
+
+export function createSearchPage({
+  defaultLocale,
+  entry,
+  locale,
+  translate = (text) => text
+}: CreateSearchPageOptions): SearchPage {
+  const { metadata } = entry
+  const title = translate(resolveMetadataString(metadata.title))
+  const description = translate(resolveMetadataString(metadata.description))
+  const category = translate(resolveMetadataString(metadata.category))
+  const content = entry.localizedContent?.[locale] ?? entry.content
+  const page: SearchPage = {
+    category,
+    description,
+    disabled: Boolean(metadata.disabled),
+    nodes: content ? extractSearchNodesFromMdx(content) : [],
+    title,
+    url: createLocalizedPathname(metadata.pathname, locale, defaultLocale)
+  }
+
+  return page
+}
+
+function loadLocalizedContent(contentDir: string): Record<string, string> {
+  const localizedContent: Record<string, string> = {}
+  const entries = FastGlob.sync('content.*.mdx', { cwd: contentDir })
+  for (const entry of entries) {
+    const match = entry.match(/^content\.([^.]+)\.mdx$/)
+    if (!match) continue
+    localizedContent[match[1]] = readFileSync(resolve(contentDir, entry), 'utf8')
+  }
+  return localizedContent
+}
+
+export function createDictionaryTranslate(translations: Record<string, string>): Translate {
+  return (text) => translations[text || ''] || text
+}
+
+export function loadDictionaryTranslations(dictionariesDir: string, locale: string): Record<string, string> {
+  const filename = resolve(dictionariesDir, `${locale}.json`)
+  if (!existsSync(filename)) return {}
+  return JSON.parse(readFileSync(filename, 'utf8')) as Record<string, string>
+}
+
+export function createLocalizedPathname(pathname: string, locale: string, defaultLocale: string, localePrefixMode: LocalePrefixMode = 'canonical') {
+  const normalizedPathname = pathname.startsWith('/') ? pathname : `/${pathname}`
+  return localizePathname(normalizedPathname, {
+    defaultLocale,
+    locale,
+    locales: [defaultLocale, locale],
+    localePrefixMode
+  })
+}
+
+export function extractSearchNodesFromMdx(source: string): SearchNode[] {
+  const tree = fromMarkdown(source, {
+    extensions: [mdxjsEsm({ acorn, addResult: true })],
+    mdastExtensions: [mdxjsEsmFromMarkdown()]
+  }) as MdxNode
+  const nodes: SearchNode[] = []
+  const slugger = new Slugger()
+  appendSearchNodes(tree.children ?? [], nodes, slugger)
+  return nodes
+}
+
+function appendSearchNodes(children: MdxNode[], nodes: SearchNode[], slugger: Slugger) {
+  for (const child of children) {
+    appendSearchNode(child, nodes, slugger)
+  }
+}
+
+function appendSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger) {
+  switch (node.type) {
+    case 'heading':
+      appendHeadingSearchNode(node, nodes, slugger)
+      return
+    case 'paragraph':
+      appendTextSearchNode(nodes, collectText(node), 'p')
+      return
+    case 'code':
+      appendTextSearchNode(nodes, node.value ?? '', 'code')
+      return
+    case 'list':
+      for (const child of node.children ?? []) {
+        appendTextSearchNode(nodes, collectText(child), 'li')
+      }
+      return
+    case 'blockquote':
+      appendSearchNodes(node.children ?? [], nodes, slugger)
+      return
+    case 'mdxjsEsm':
+    case 'html':
+    case 'break':
+    case 'thematicBreak':
+      return
+    default:
+      if (node.children?.length) {
+        appendSearchNodes(node.children, nodes, slugger)
+      }
+  }
+}
+
+function appendHeadingSearchNode(node: MdxNode, nodes: SearchNode[], slugger: Slugger) {
+  const text = normalizeSearchText((node.children ?? []).filter(child => child.type === 'text' || child.type === 'inlineCode').map(child => child.value).join(' '))
+  if (!text) return
+
+  const tag = node.depth ? `h${node.depth}` : 'h'
+  if (node.depth === 2 || node.depth === 3) {
+    const resolved = resolveHeading(text, slugger.slug(text))
+    appendTextSearchNode(nodes, resolved.title, tag, resolved.id)
+    return
+  }
+
+  appendTextSearchNode(nodes, text, tag)
+}
+
+function appendTextSearchNode(nodes: SearchNode[], text: string, tag: string, id?: string) {
+  const normalizedText = normalizeSearchText(text)
+  if (!normalizedText) return
+  nodes.push({
+    ...(id ? { id } : {}),
+    tag,
+    text: normalizedText
+  })
+}
+
+function collectText(node: MdxNode): string {
+  switch (node.type) {
+    case 'text':
+    case 'inlineCode':
+    case 'code':
+      return node.value ?? ''
+    case 'html':
+    case 'mdxjsEsm':
+      return ''
+    default:
+      return node.children?.map(collectText).join('') ?? ''
+  }
+}
+
+function normalizeSearchText(text: string) {
+  return text.replace(/&nbsp;/g, ' ').replace(/\s+/g, ' ').trim()
+}
+
+function resolveMetadataString(value: any): string {
+  if (!value) return ''
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (typeof value === 'object') {
+    if ('absolute' in value) return resolveMetadataString(value.absolute)
+    if ('default' in value) return resolveMetadataString(value.default)
+  }
+  return String(value)
+}