@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/utils/vue.ts

@@ -0,0 +1,57 @@
+import type { VNode } from 'vue'
+import { getCurrentInstance, toValue } from 'vue'
+
+/**
+ * Helper function to check if the current setup-script component has a named listener
+ *
+ * @param name
+ */
+export function hasListener(name: string): boolean {
+  const instance = getCurrentInstance()
+  const handler = `on${name.slice(0, 1).toUpperCase()}${name.slice(1)}`
+  return !!instance?.vnode.props && (handler in instance.vnode.props)
+}
+
+type Slot = (() => VNode[]) | undefined
+
+/**
+ * Helper function to render a slot's text content
+ *
+ * @param slot
+ */
+export function getSlotTextContent(slot: Slot): string {
+  if (!slot) {
+    return ''
+  }
+  return slot().map((node: VNode): string => {
+    if (typeof node.children === 'string') {
+      return node.children
+    }
+    else if (Array.isArray(node.children)) {
+      return getSlotTextContent(() => node.children as VNode[])
+    }
+    return ''
+  }).join(' ').trim()
+}
+
+export function deepUnref<T>(obj: T): T {
+  const value = toValue(obj)
+
+  if (!value || typeof value !== 'object') {
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(deepUnref) as T
+  }
+
+  const result: Record<string, unknown> = {}
+  for (const key in value) {
+    // Skip Vue's internal ref properties
+    if (key.startsWith('__v_') || key === '_rawValue' || key === '_value') {
+      continue
+    }
+    result[key] = deepUnref(value[key])
+  }
+  return result as T
+}

package/build/design-system.ts

@@ -0,0 +1,69 @@
+import type { ModuleOptions as IconModuleOptions } from '@nuxt/icon'
+import type { NuxtOptions } from 'nuxt/schema'
+import type { IconSet } from '../shared/icons'
+import { addTemplate, defineNuxtModule } from 'nuxt/kit'
+import { iconAliasMap, iconBundleList, parseIconSet } from '../shared/icons'
+import { externalLinkMarkerCss } from './external-links'
+
+export interface DesignSystemOptions {
+  /**
+   * The icon set every semantic icon role renders from. Defaults to hugeicons.
+   * Install the matching `@iconify-json/<set>` collection in the app.
+   */
+  iconSet?: IconSet
+  /**
+   * Load Nuxt SEO's Hubot Sans and Fira Code faces as global families, so
+   * every page preloads them. Defaults to false: a site sets its own families
+   * through `fonts.families` and the `--font-*` tokens. The layer's
+   * `modules:before` hook reads it, because @nuxt/fonts reads its families
+   * when it installs, which can come before this module's setup.
+   */
+  fonts?: boolean
+  /**
+   * Hosts that count as this site. An absolute prose link to one of them gets
+   * no external-link arrow. Defaults to none, so every absolute http(s) link
+   * is marked. Matches a substring of the href after `//`, so list `www.` too.
+   */
+  internalLinkHosts?: string[]
+}
+
+/**
+ * Build-time brand choices for an app that extends the design system. Set them
+ * under `designSystem` in the app's Nuxt config.
+ *
+ * Every semantic icon role, and its synonyms, becomes a global @nuxt/icon alias
+ * for the chosen set. Role names then resolve everywhere: raw Nuxt UI components
+ * (`<UButton icon="next">`), data-array `icon:` fields, `<Icon name="next">`,
+ * content, app.config slots, and UiIcon/UiButton, which pass the name straight
+ * through. Resolution happens here, so the role registry never ships to the
+ * client runtime. The client bundle holds only the chosen set's role icons, and
+ * the server icon bundle (`icon-server-bundle.ts`) reads that list, so both
+ * follow the choice.
+ *
+ * Alias values MUST be `prefix:name`, not `i-...`: @nuxt/icon re-prefixes an
+ * alias target with `i-`, so an `i-` value becomes a broken `i-i-...`.
+ * `iconAliasMap` handles that and the synonyms.
+ *
+ * The layer lists this module before `@nuxt/ui`, which installs @nuxt/icon, so
+ * the options are in place before @nuxt/icon reads them.
+ */
+export default defineNuxtModule<DesignSystemOptions>({
+  meta: { name: '@nuxtseo/design-system', configKey: 'designSystem' },
+  setup(options, nuxt) {
+    const iconSet = parseIconSet(options.iconSet)
+    // @nuxt/icon adds no `icon` key to the NuxtOptions type.
+    const opts = nuxt.options as NuxtOptions & { icon?: IconModuleOptions }
+    const icon = opts.icon ??= {}
+    // An alias the app declares itself wins over a role of the same name.
+    icon.aliases = { ...iconAliasMap(iconSet), ...icon.aliases }
+    icon.clientBundle ??= {}
+    icon.clientBundle.icons = [...new Set([...iconBundleList(iconSet), ...(icon.clientBundle.icons ?? [])])]
+
+    const externalLinks = addTemplate({
+      filename: 'design-system/external-links.css',
+      getContents: () => externalLinkMarkerCss(options.internalLinkHosts ?? []),
+      write: true,
+    })
+    nuxt.options.css.push(externalLinks.dst)
+  },
+})

package/build/external-links.ts

@@ -0,0 +1,38 @@
+/**
+ * The external-link arrow on outbound prose links. Only an absolute http(s)
+ * link that leaves the site gets it; a relative link never matches, and a
+ * link around an image is excluded because the arrow would hang off the
+ * corner of the figure.
+ *
+ * Which hosts count as this site is a brand choice, so the rules are built
+ * from `designSystem.internalLinkHosts`. A CSS custom property cannot feed an
+ * attribute selector, so the hosts have to reach the selector at build time.
+ *
+ * The marker is a background on a pseudo-element whose only content is a
+ * no-break space: the NBSP glues the arrow to the last word, so it can never
+ * orphan onto a line of its own, and there is no text for a screen reader to
+ * announce. The mask resolves `currentColor` against the image's own initial
+ * colour, which is opaque black, so the arrow always paints in the link's
+ * colour and the CSS holds no colour of its own.
+ */
+export function externalLinkMarkerCss(internalHosts: readonly string[]): string {
+  const own = internalHosts
+    .map(host => `:not([href*="//${host.replace(/["\\]/g, '\\$&')}"])`)
+    .join('')
+  const link = `a.prose-link[href^="http"]${own}:not(:has(img))`
+  return `${link}::after {
+  content: '\\00a0';
+  padding-inline-end: 0.72em;
+  background-color: currentcolor;
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M7 7h10v10'/%3E%3Cpath d='M7 17 17 7'/%3E%3C/svg%3E");
+  mask-repeat: no-repeat;
+  mask-position: right center;
+  mask-size: 0.72em 0.72em;
+  opacity: 0.65;
+  vertical-align: baseline;
+}
+${link}:hover::after {
+  opacity: 1;
+}
+`
+}

package/build/fonts.ts

@@ -0,0 +1,39 @@
+import type { FontFamilyManualOverride } from '@nuxt/fonts'
+
+/**
+ * Nuxt SEO's own faces, self-hosted from this layer's `public/fonts/`. Builds
+ * never download them from a provider, so an app build does not depend on
+ * Google Fonts availability. Hubot Sans keeps its variable weight and width
+ * axes for the design tokens.
+ *
+ * A site loads them only when it sets `designSystem: { fonts: true }`. A
+ * global family is preloaded on every page, so a site with its own type stack
+ * would otherwise pay for two faces it never renders.
+ */
+export const NUXT_SEO_FONT_FAMILIES: readonly FontFamilyManualOverride[] = [
+  {
+    name: 'Hubot Sans',
+    src: '/fonts/hubot-sans-var-latin.woff2',
+    weight: '200 900',
+    stretch: '75% 125%',
+    style: 'normal',
+    global: true,
+  },
+  {
+    name: 'Fira Code',
+    src: '/fonts/fira-code-var-latin.woff2',
+    weight: '400 500',
+    style: 'normal',
+    global: true,
+  },
+]
+
+/**
+ * The font families @nuxt/fonts should register. With `enabled`, Nuxt SEO's
+ * faces come first and the app's own families follow; without it, the app's
+ * families pass through unchanged.
+ */
+export function withNuxtSeoFonts<T>(families: readonly T[] | undefined, enabled: boolean | undefined): Array<T | FontFamilyManualOverride> {
+  const own = families ?? []
+  return enabled === true ? [...NUXT_SEO_FONT_FAMILIES, ...own] : [...own]
+}

package/build/icon-server-bundle.ts

@@ -0,0 +1,276 @@
+import type { ModuleOptions as IconModuleOptions } from '@nuxt/icon'
+import type { Nuxt, NuxtOptions } from 'nuxt/schema'
+import { existsSync, realpathSync } from 'node:fs'
+import { glob, readFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { collectionNames, resolveBundleIcons } from '@nuxt/icon/utils'
+import { addPlugin, addTemplate, addTypeTemplate, defineNuxtModule, useLogger } from 'nuxt/kit'
+import { countryCodeToFlagIcon, countryData } from '../app/utils/countries'
+
+// Server icon bundle: icon data for SSR only.
+//
+// The client bundle holds the active role set and a few brand marks. A raw
+// `i-*` id outside it made @nuxt/icon fetch the icon from api.iconify.design
+// during SSR, and the response waited for that fetch (up to its 1500 ms
+// timeout) on every isolate that had not loaded that icon set yet.
+//
+// This module collects every raw icon id in the app's source, in the listed
+// dependency code, and the ids the app builds at runtime. A server-only plugin
+// registers their data. The browser bundle does not change: SSR writes each
+// icon's CSS into the page. The plugin also removes the Iconify API from the
+// server, so an id outside both bundles renders empty without a request. The
+// browser then loads it.
+//
+// A production build fails when a scanned id has no icon data, and when the
+// final server output names an id that neither bundle holds.
+
+/** A raw icon id in `prefix:name` form, and the files that name it. */
+export type IconSources = Map<string, string[]>
+
+export type ServerIconCollection = Awaited<ReturnType<typeof resolveBundleIcons>>['collections'][number]
+
+export interface ServerIconBundle {
+  collections: ServerIconCollection[]
+  count: number
+  sizeKb: number
+  /** Ids with no icon data: a typo, or a collection that is not installed. */
+  unresolved: Array<{ icon: string, files: string[] }>
+  /** `packages` entries with no installed directory. */
+  missingPackages: string[]
+}
+
+export interface BuildServerIconBundleInput {
+  /** Directories to scan for raw icon ids. */
+  roots: string[]
+  /**
+   * Dependency directories to scan, as `<package>/<path>`, for example
+   * `@gscdump/sdk/dist`. List a dependency whose code names raw ids that the
+   * app renders.
+   */
+  packages: string[]
+  /** Ids the app builds at runtime, which a source scan cannot see. */
+  runtimeIcons: Iterable<string>
+  /** Ids the client bundle already registers on the server. */
+  clientIcons: Iterable<string>
+  /** Directories that resolve the installed packages and `@iconify-json/*` collections. */
+  resolvePaths: string[]
+}
+
+const SOURCE_GLOB = '**/*.{vue,ts,tsx,js,mjs,md,yml,yaml}'
+// Type unions, tests and tooling name icons that no build ships. Server code
+// stays in: Nitro bundles it into the server output that the output check reads.
+const SKIPPED_SEGMENT = /\/(?:node_modules|\.nuxt[^/]*|\.output|\.data|\.wrangler|dist|types|tests?|scripts|migrations[^/]*)(?:\/|$)/
+const SKIPPED_FILE = /\.(?:d|test|spec)\.ts$/
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+// Longest prefix first, like @nuxt/icon's resolver, so `i-simple-icons-x` is
+// `simple-icons:x` and not `simple:icons-x`.
+const PREFIX = `(${[...collectionNames].sort((a, b) => b.length - a.length).map(escapeRegExp).join('|')})`
+const NAME = '([a-z0-9]+(?:-[a-z0-9]+)*)'
+// `i-lucide-x`, `i-lucide:x`, or a quoted `'lucide:x'`. A template prefix
+// such as `i-vscode-icons-file-type-${ext}` is not an id.
+const SOURCE_ICON = new RegExp(`\\bi-${PREFIX}[-:]${NAME}\\b(?![-a-z0-9]*\\$\\{)|(?<=['"\`])${PREFIX}:${NAME}(?=['"\`])`, 'g')
+const RAW_ICON = new RegExp(`^(?:i-)?${PREFIX}[-:]${NAME}$`)
+
+/** `i-circle-flags-de` or `circle-flags:de` to `circle-flags:de`. */
+function toIconId(icon: string): string {
+  const match = RAW_ICON.exec(icon)
+  return match ? `${match[1]}:${match[2]}` : icon
+}
+
+/** Raw icon ids that `code` names, as `prefix:name`. */
+function iconIdsIn(code: string): Set<string> {
+  const icons = new Set<string>()
+  for (const match of code.matchAll(SOURCE_ICON))
+    icons.add(match[1] ? `${match[1]}:${match[2]}` : `${match[3]}:${match[4]}`)
+  return icons
+}
+
+export async function scanIconSources(roots: string[]): Promise<IconSources> {
+  const sources: IconSources = new Map()
+  const seen = new Set<string>()
+  for (const root of roots) {
+    for await (const file of glob(SOURCE_GLOB, { cwd: root, exclude: path => SKIPPED_SEGMENT.test(`/${path}`) })) {
+      const path = `${root}/${file}`
+      if (seen.has(path) || SKIPPED_FILE.test(file))
+        continue
+      seen.add(path)
+      for (const icon of iconIdsIn(await readFile(path, 'utf8')))
+        sources.set(icon, [...sources.get(icon) ?? [], path])
+    }
+  }
+  return sources
+}
+
+/** `@gscdump/sdk/dist` to the `dist` directory of the installed `@gscdump/sdk`. */
+function resolvePackageDir(entry: string, resolvePaths: string[]): string | undefined {
+  const parts = entry.split('/')
+  const nameParts = entry.startsWith('@') ? 2 : 1
+  const name = parts.slice(0, nameParts).join('/')
+  for (const base of resolvePaths) {
+    for (let dir = base; ; dir = dirname(dir)) {
+      const packageDir = join(dir, 'node_modules', name)
+      if (existsSync(join(packageDir, 'package.json'))) {
+        const scanned = join(realpathSync(packageDir), ...parts.slice(nameParts))
+        return existsSync(scanned) ? scanned : undefined
+      }
+      if (dirname(dir) === dir)
+        break
+    }
+  }
+  return undefined
+}
+
+/** Flag ids that `countryCodeToFlagIcon` builds at runtime for country tables. */
+export function countryFlagIcons(): string[] {
+  const icons = Object.keys(countryData).map(code => countryCodeToFlagIcon(code))
+  return [...new Set(icons.filter(icon => icon.startsWith('i-')).map(toIconId))]
+}
+
+export async function buildServerIconBundle(input: BuildServerIconBundleInput): Promise<ServerIconBundle> {
+  const packageDirs = input.packages.map(entry => [entry, resolvePackageDir(entry, input.resolvePaths)] as const)
+  const sources = await scanIconSources([...input.roots, ...packageDirs.flatMap(([, dir]) => dir ? [dir] : [])])
+  const clientIcons = new Set(Array.from(input.clientIcons, toIconId))
+  const icons = [...new Set([...sources.keys(), ...Array.from(input.runtimeIcons, toIconId)])]
+    .filter(icon => !clientIcons.has(icon))
+  const { collections, count, failed } = await resolveBundleIcons({ icons, resolvePaths: input.resolvePaths })
+  return {
+    collections,
+    count,
+    sizeKb: Buffer.byteLength(JSON.stringify(collections)) / 1024,
+    unresolved: failed.sort().map(icon => ({ icon, files: sources.get(icon) ?? [] })),
+    missingPackages: packageDirs.flatMap(([entry, dir]) => dir ? [] : [entry]),
+  }
+}
+
+/**
+ * Ids that the server output names but neither bundle holds. SSR renders them
+ * empty. Template prefixes such as `i-vscode-icons-file-type-${ext}` are left
+ * out, because no bundle can hold every id they build.
+ */
+export function unbundledServerIcons(
+  chunks: Iterable<{ fileName: string, code: string }>,
+  bundle: Pick<ServerIconBundle, 'collections'>,
+  clientIcons: Iterable<string>,
+): Array<{ icon: string, files: string[] }> {
+  const bundled = new Set(Array.from(clientIcons, toIconId))
+  for (const collection of bundle.collections) {
+    for (const name of [...Object.keys(collection.icons), ...Object.keys(collection.aliases ?? {})])
+      bundled.add(`${collection.prefix}:${name}`)
+  }
+  const missing = new Map<string, string[]>()
+  for (const { fileName, code } of chunks) {
+    for (const icon of iconIdsIn(code)) {
+      if (!bundled.has(icon))
+        missing.set(icon, [...missing.get(icon) ?? [], fileName])
+    }
+  }
+  return [...missing].sort(([a], [b]) => a.localeCompare(b)).map(([icon, files]) => ({ icon, files }))
+}
+
+export function renderServerIconBundle(bundle: Pick<ServerIconBundle, 'collections'>): string {
+  return `export const collections = JSON.parse(${JSON.stringify(JSON.stringify(bundle.collections))})\n`
+}
+
+function scanRoots(nuxt: Nuxt): string[] {
+  const layers = nuxt.options._layers.map(layer => layer.config.rootDir)
+  // Local modules ship runtime code outside any layer, for example the Site nav.
+  const modules = nuxt.options._installedModules
+    .map(installed => installed.entryPath)
+    .filter((path): path is string => !!path && isAbsolute(path) && !path.includes('/node_modules/'))
+    .map(path => dirname(path))
+  return [...new Set([...layers, ...modules])]
+}
+
+// Build-blocking ceiling for the uncompressed icon data. Pro held 530 icons,
+// 406 KB, on 2026-10-29. Country flags took 161 KB, and Nuxt UI's default and
+// code-block icons took about 60 KB.
+const SIZE_LIMIT_KB = 512
+
+export interface IconServerBundleOptions {
+  /** Dependency directories to scan, as `<package>/<path>`. See {@link BuildServerIconBundleInput.packages}. */
+  packages: string[]
+}
+
+export function iconServerBundleModule(options: IconServerBundleOptions) {
+  return defineNuxtModule({
+    meta: { name: 'nuxtseo-icon-server-bundle' },
+    setup(_options, nuxt) {
+      const logger = useLogger('icon-server-bundle')
+      // @nuxt/icon adds no `icon` key to the NuxtOptions type.
+      const clientIcons = () => (nuxt.options as NuxtOptions & { icon?: IconModuleOptions }).icon?.clientBundle?.icons ?? []
+
+      // One scan per process. In dev, restart to bundle an id added after start.
+      let pending: Promise<ServerIconBundle> | undefined
+      const loadBundle = () => pending ??= buildServerIconBundle({
+        roots: scanRoots(nuxt),
+        packages: options.packages,
+        runtimeIcons: countryFlagIcons(),
+        clientIcons: clientIcons(),
+        resolvePaths: [...new Set([nuxt.options.rootDir, nuxt.options.workspaceDir, ...nuxt.options._layers.map(layer => layer.config.rootDir)])],
+      })
+      const report = (problem: string) => {
+        if (!nuxt.options.dev)
+          throw new Error(`[icon-server-bundle] ${problem}`)
+        logger.warn(problem)
+      }
+
+      // Check before the bundler runs. A throw inside a template is reported as
+      // a missing `#build` file instead of this message.
+      nuxt.hook('build:before', async () => {
+        if (nuxt.options._prepare)
+          return
+        const bundle = await loadBundle()
+        const problems: string[] = []
+        if (bundle.unresolved.length) {
+          const list = bundle.unresolved.map(({ icon, files }) => `  - ${icon} ${files.map(file => relative(nuxt.options.workspaceDir, file)).join(', ')}`)
+          problems.push(`These icon ids have no icon data. Fix the name, or install its @iconify-json collection:\n${list.join('\n')}`)
+        }
+        if (bundle.missingPackages.length)
+          problems.push(`These \`packages\` entries have no installed directory. Install the package, or remove the entry:\n${bundle.missingPackages.map(entry => `  - ${entry}`).join('\n')}`)
+        if (bundle.sizeKb > SIZE_LIMIT_KB)
+          problems.push(`The server icon bundle is ${bundle.sizeKb.toFixed(1)} KB, over its ${SIZE_LIMIT_KB} KB limit.`)
+        if (problems.length)
+          report(problems.join('\n'))
+        logger.info(`Server icon bundle: ${bundle.count} icons, ${bundle.sizeKb.toFixed(1)} KB uncompressed.`)
+      })
+
+      // The scan reads source files and the listed dependencies. This check
+      // reads what Nitro ships, so it also finds an id in a dependency that
+      // `packages` leaves out.
+      nuxt.hook('nitro:init', (nitro) => {
+        nitro.hooks.hook('rollup:before', (_nitro, rollupConfig) => {
+          const plugins = rollupConfig.plugins
+          rollupConfig.plugins = [...(Array.isArray(plugins) ? plugins : [plugins]), {
+            name: 'nuxtseo:icon-server-bundle-check',
+            async generateBundle(_options, output) {
+              const chunks = Object.values(output).flatMap(file => file.type === 'chunk' ? [file] : [])
+              const missing = unbundledServerIcons(chunks, await loadBundle(), clientIcons())
+              if (!missing.length)
+                return
+              const list = missing.map(({ icon, files }) => `  - ${icon} ${files.join(', ')}`)
+              report(`The server output names these icon ids, and neither icon bundle holds them. SSR renders them empty. If a dependency names an id, add its directory to the \`packages\` option:\n${list.join('\n')}`)
+            },
+          }]
+        })
+      })
+
+      addTemplate({
+        filename: 'icon-server-bundle.mjs',
+        getContents: async () => renderServerIconBundle(await loadBundle()),
+      })
+      addTypeTemplate({
+        filename: 'types/icon-server-bundle.d.ts',
+        getContents: () => `declare module '#build/icon-server-bundle.mjs' {
+  export const collections: import(${JSON.stringify(fileURLToPath(new URL('./icon-server-bundle', import.meta.url)))}).ServerIconCollection[]
+}
+`,
+      })
+      addPlugin({
+        src: fileURLToPath(new URL('./runtime/icon-server-bundle', import.meta.url)),
+        mode: 'server',
+      })
+    },
+  })
+}

package/build/runtime/icon-server-bundle.ts

@@ -0,0 +1,29 @@
+import type { IconifyAPIModule } from '@iconify/vue'
+import { _api, addCollection } from '@iconify/vue'
+import { defineNuxtPlugin } from 'nuxt/app'
+import { collections } from '#build/icon-server-bundle.mjs'
+
+// Answers every Iconify API query as "not found" without a request. On the
+// server an icon outside the client and server bundles renders empty at once,
+// and the browser loads it after hydration. The response never waits on
+// api.iconify.design.
+const offlineApi: IconifyAPIModule = {
+  prepare: (provider, prefix, icons) => [{ type: 'icons', provider, prefix, icons }],
+  send: (_host, _params, respond) => respond('abort', 404),
+}
+
+// Iconify keeps icons and API modules in module scope, so one setup serves
+// every request in the isolate.
+let installed = false
+
+export default defineNuxtPlugin({
+  name: 'design-system:icon-server-bundle',
+  setup() {
+    if (installed)
+      return
+    installed = true
+    _api.setAPIModule('', offlineApi)
+    for (const collection of collections)
+      addCollection(collection)
+  },
+})