@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/shared/icons/ui-slots.ts

@@ -0,0 +1,58 @@
+import type { ICON_ALIASES, IconRole } from './registry'
+
+type SemanticUiIcon = IconRole | keyof typeof ICON_ALIASES
+
+/**
+ * Nuxt UI's complete icon-slot vocabulary, expressed only in design-system
+ * roles. Keeping this in build-time app config prevents Nuxt UI from adding
+ * its default Lucide set beside the curated client bundle.
+ */
+export const UI_ICON_SLOTS = {
+  arrowDown: 'down',
+  arrowLeft: 'back',
+  arrowRight: 'next',
+  arrowUp: 'up',
+  caution: 'caution',
+  check: 'check',
+  chevronDoubleLeft: 'page-first',
+  chevronDoubleRight: 'page-last',
+  chevronDown: 'expand',
+  chevronLeft: 'chevron-left',
+  chevronRight: 'chevron-right',
+  chevronUp: 'collapse',
+  close: 'close',
+  copy: 'copy',
+  copyCheck: 'success',
+  dark: 'dark',
+  document: 'file',
+  drag: 'grip',
+  ellipsis: 'more-horizontal',
+  error: 'error',
+  external: 'external',
+  eye: 'view',
+  eyeOff: 'hide',
+  file: 'file',
+  folder: 'folder',
+  folderOpen: 'folder',
+  hash: 'hash',
+  info: 'info',
+  light: 'light',
+  loading: 'loading',
+  menu: 'menu',
+  minus: 'minus',
+  next: 'next',
+  note: 'note',
+  panelClose: 'back',
+  panelOpen: 'next',
+  plus: 'add',
+  prev: 'back',
+  reload: 'refresh',
+  search: 'search',
+  stop: 'stop',
+  star: 'star',
+  success: 'success',
+  system: 'system',
+  tip: 'tip',
+  upload: 'upload',
+  warning: 'warning',
+} as const satisfies Record<string, SemanticUiIcon>

package/shared/markdown.ts

@@ -0,0 +1,44 @@
+import rangi from '@comark/nuxt/plugins/rangi'
+import security from '@comark/nuxt/plugins/security'
+import { contentRangiTheme } from './rangi'
+
+export const markdownOptions = { registerDefaultPlugins: false }
+
+export const markdownPlugins = [rangi({
+  classPrefix: 'rangi',
+  lineNumbers: true,
+  preStyles: false,
+  theme: contentRangiTheme,
+}), security({
+  allowedTags: [
+    'p',
+    'a',
+    'strong',
+    'em',
+    's',
+    'del',
+    'code',
+    'pre',
+    'span',
+    'br',
+    'hr',
+    'blockquote',
+    'ul',
+    'ol',
+    'li',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'table',
+    'thead',
+    'tbody',
+    'tr',
+    'th',
+    'td',
+  ],
+  allowedProtocols: ['http', 'https', 'mailto'],
+  allowDataImages: false,
+})]

package/shared/motion.ts

@@ -0,0 +1,120 @@
+/**
+ * Motion presets — the JS half of the design system's motion vocabulary,
+ * driven by motion-v (`<m.*>` elements). The CSS half is the `--ease-*`
+ * easings + route keyframes in global.css.
+ *
+ *   - springs         named spring transitions, reused everywhere
+ *   - liftPresets     hover / press transforms (counterpart of --elevation-hover)
+ *   - entrancePresets mount reveals — fade / fadeUp / pop
+ *   - stagger*        list-reveal orchestration
+ *
+ * Every consumer gates motion behind `useReducedMotion()` — see `entranceProps()`
+ * and the `UiButton` `lift` computed for the pattern.
+ *
+ * SSR note: a motion-v entrance bound on the server ships its hidden `initial`
+ * frame, and Vue keeps that style through hydration. Under reduced motion
+ * nothing moves it out, so the content stays invisible. Components bind
+ * entrances through `useEntranceMotion()`, which binds nothing on the server
+ * or during hydration.
+ */
+
+/* ─── Springs ─────────────────────────────────────────────────────────────
+   Named motion-v `transition` configs. Reuse rather than hand-tuning. */
+export const springs = {
+  /** Quick, minimal overshoot — toggles, small reveals. */
+  snappy: { type: 'spring', stiffness: 380, damping: 26, mass: 0.6 },
+  /** Balanced, unhurried — the default for entrances and content shifts. */
+  smooth: { type: 'spring', stiffness: 210, damping: 26, mass: 0.9 },
+  /** Soft, slow settle — large surfaces, drawers. */
+  gentle: { type: 'spring', stiffness: 180, damping: 24, mass: 1 },
+} as const
+
+/* ─── Lift ────────────────────────────────────────────────────────────────
+   Hover / press transforms. The CSS counterpart is `--elevation-hover`; this
+   is the JS half. Shared so buttons, cards, and links lift with one feel. */
+export type LiftIntensity = 'subtle' | 'default' | 'cta'
+
+export interface LiftPreset {
+  hover: { scale: number, y: number }
+  tap: { scale: number, y: number }
+  transition: { type: 'spring', stiffness: number, damping: number, mass: number }
+}
+
+export const liftPresets: Record<LiftIntensity, LiftPreset> = {
+  /** Barely-there nudge — crisp, quick, no overshoot (high damping). */
+  subtle: {
+    hover: { scale: 1.012, y: -1 },
+    tap: { scale: 0.99, y: 0 },
+    transition: { type: 'spring', stiffness: 420, damping: 30, mass: 0.5 },
+  },
+  /** Restrained lift with a touch of spring: the standard. */
+  default: {
+    hover: { scale: 1.025, y: -2 },
+    tap: { scale: 0.98, y: 0 },
+    transition: { type: 'spring', stiffness: 320, damping: 21, mass: 0.8 },
+  },
+  /** Emphatic lift: visible overshoot with a controlled settle. */
+  cta: {
+    hover: { scale: 1.045, y: -4 },
+    tap: { scale: 0.96, y: 0 },
+    transition: { type: 'spring', stiffness: 240, damping: 15, mass: 1.1 },
+  },
+}
+
+/* ─── Entrance ────────────────────────────────────────────────────────────
+   Mount reveals for `<m.*>` elements. Components bind them with `useEntranceMotion()`,
+   which handles reduced motion and server rendering. */
+export type EntranceName = 'fade' | 'fadeUp' | 'pop'
+
+export interface EntrancePreset {
+  initial: Record<string, number>
+  enter: Record<string, number>
+  transition: Record<string, unknown>
+}
+
+export const entrancePresets: Record<EntranceName, EntrancePreset> = {
+  fade: {
+    initial: { opacity: 0 },
+    enter: { opacity: 1 },
+    transition: { duration: 0.45, ease: 'easeOut' },
+  },
+  fadeUp: {
+    initial: { opacity: 0, y: 12 },
+    enter: { opacity: 1, y: 0 },
+    // A long, mildly-eased tween — not a spring and not an aggressive easeOut;
+    // both front-load the change and read as rushed. A gentle easeOut over
+    // 600ms spreads the motion so the entrance is graceful and watchable.
+    transition: { duration: 0.6, ease: 'easeOut' },
+  },
+  pop: {
+    initial: { opacity: 0, scale: 0.94 },
+    enter: { opacity: 1, scale: 1 },
+    transition: springs.smooth,
+  },
+}
+
+/**
+ * v-bind helper — returns motion-v `{ initial, animate, transition }`, or `{}`
+ *  when reduced motion is on (the element then mounts in its resting state).
+ */
+export function entranceProps(preset: EntrancePreset, reduced?: boolean) {
+  if (reduced)
+    return {}
+  return { initial: preset.initial, animate: preset.enter, transition: preset.transition }
+}
+
+/* ─── Stagger ─────────────────────────────────────────────────────────────
+   List-reveal orchestration. The parent `<m.*>` binds `staggerContainer`, each
+   child `<m.*>` binds `staggerChild`; children animate in sequence. */
+export const staggerContainer = {
+  initial: 'initial',
+  animate: 'animate',
+  variants: { animate: { transition: { staggerChildren: 0.05 } } },
+} as const
+
+export const staggerChild = {
+  variants: {
+    initial: { opacity: 0, y: 6 },
+    animate: { opacity: 1, y: 0, transition: springs.smooth },
+  },
+} as const

package/shared/rangi.ts

@@ -0,0 +1,60 @@
+import type { ShjThemePair, ShjToken } from 'rangi'
+import { tokenize } from 'rangi'
+import { githubDark, githubLight } from 'rangi/themes'
+
+// @harlan-zw/comark-content also exports `contentRangiTheme`, but only from its
+// build-time module entry, which pulls `@nuxt/kit` and `node:` builtins. This
+// file is imported by Vue components (`ModuleInstall`, `SiteConfigQuickSetup`,
+// the docs nav) and by `shared/markdown.ts`, so it must stay client-safe. The
+// two definitions are identical apart from the theme name; keep them in step.
+export const contentRangiTheme: ShjThemePair = {
+  light: {
+    ...githubLight,
+    name: 'nuxtseo-github-light-aa',
+    tokens: { ...githubLight.tokens, cmnt: '#57606a' },
+  },
+  dark: githubDark,
+}
+
+export interface HighlightedCode {
+  className: string
+  html: string
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}
+
+function tokenStyle(token: ShjToken, appearance: 'adaptive' | 'dark'): string {
+  const light = contentRangiTheme.light.tokens[token]
+  const dark = contentRangiTheme.dark.tokens[token]
+  const color = appearance === 'dark'
+    ? dark
+    : light && dark && light !== dark ? `light-dark(${light},${dark})` : light ?? dark
+  return [color ? `color:${color}` : '', token === 'cmnt' ? 'font-style:italic' : ''].filter(Boolean).join(';')
+}
+
+export function highlightCode(code: string, lang: string, appearance: 'adaptive' | 'dark' = 'adaptive'): HighlightedCode {
+  const requestedLanguage = lang.toLowerCase().replace(/[^a-z0-9-]/g, '') || 'plain'
+  const language = requestedLanguage === 'dotenv' || requestedLanguage === 'env' ? 'ini' : requestedLanguage
+  const html = tokenize(code, { lang: language }).map((token) => {
+    const value = escapeHtml(token.text)
+    if (!token.type)
+      return value
+    const style = tokenStyle(token.type, appearance)
+    return style ? `<span style="${style}">${value}</span>` : value
+  }).join('')
+
+  return {
+    html,
+    className: `rangi shj-lang-${requestedLanguage}`,
+  }
+}
+
+export function inlineHighlightedCode(code: string, lang: string): string {
+  const highlighted = highlightCode(code, lang)
+  return `<code class="${highlighted.className}">${highlighted.html}</code>`
+}

package/shared/rich-text.ts

@@ -0,0 +1,34 @@
+/**
+ * `RichSegment` — the typed inline-token vocabulary for action/entity prose.
+ *
+ * Pinned contract (both the design-system `UiRichText` renderer and pro-actions's
+ * `action-display.ts` build against exactly this shape). pro-actions mirrors this
+ * type structurally with a "keep in sync" comment (ADR-0042: design-system MAY
+ * know the shape, never the runtime that produces it). Supersedes the retired
+ * `UiActionTitle` / `ActionTitleSegment` regex-recovered vocabulary (deleted
+ * Phase 4, sprint-action-typed-rendering, 2026-07-29).
+ *
+ * A segment is never parsed from prose at render time — it is produced upstream
+ * by a typed why-template, so every token here already carries its own display
+ * data (no regex, no string surgery in the renderer).
+ */
+export type RichSegment
+  = | { kind: 'text', text: string }
+  /** Renders ' · ' — a calm, aria-hidden divider between segments. */
+    | { kind: 'sep' }
+  /** Quoted mono run (keyword treatment). */
+    | { kind: 'keyword', text: string, to?: string, tooltip?: string }
+  /** Social @handle. */
+    | { kind: 'handle', text: string, to?: string }
+  /** Compacted path; the full URL belongs in the tooltip/title, not the label. */
+    | { kind: 'page', text: string, url: string, to?: string, tooltip?: string }
+  /** Favicon + host. `external` opens the domain itself in a new tab. */
+    | { kind: 'domain', text: string, domain: string, external?: boolean, to?: string }
+  /** Numerals-display, tabular figure. */
+    | { kind: 'metric', text: string, tooltip?: string }
+  /** '#8' with `UiPositionMetric`-style quality bands. */
+    | { kind: 'position', text: string, position: number }
+  /** '19 → 26' linked pair. Colour rides ONLY on an explicit `good`; otherwise neutral. */
+    | { kind: 'delta', from: string, to: string, direction: 'up' | 'down' | 'flat', good?: boolean, tooltip?: string }
+  /** Selectors, rule ids — mono, unquoted (distinct from `keyword`). */
+    | { kind: 'code', text: string }

package/shared/ui-icons.ts

@@ -0,0 +1,6 @@
+/**
+ * Back-compat shim — the icon system now lives in `./icons`.
+ * See `./icons/registry.ts` for the role vocabulary and `./icons/index.ts` for
+ * the resolver + active-set switch.
+ */
+export * from './icons'

package/shared/utils/urls.ts

@@ -0,0 +1,64 @@
+export function getLastPathSegment(path: string) {
+  const segments = path.split('/')
+  return segments.slice(-1).join('/')
+}
+
+export function getPathSegments(path: string, size: number): string {
+  const segments = path.split('/')
+
+  if (segments.length <= size)
+    return path
+
+  return segments.slice(0, size + 1).join('/')
+}
+
+/**
+ * Strip a URL down to a human-readable label: drop the protocol, a leading
+ * `www.`, the `sc-domain:` prefix, and any trailing slash. Bare domains and
+ * paths pass through cleaned.
+ */
+export function prettifyUrl(input: string | null | undefined): string {
+  if (!input)
+    return ''
+  return input
+    .trim()
+    .replace(/^sc-domain:/i, '')
+    .replace(/^[a-z][\w+.-]*:\/\//i, '')
+    .replace(/^www\./i, '')
+    .replace(/\/+$/, '')
+}
+
+/**
+ * Best-effort hostname extraction for favicon lookups. Falls back to the
+ * cleaned input when it isn't a parseable absolute URL.
+ */
+export function urlHostname(input: string | null | undefined): string {
+  if (!input)
+    return ''
+  const cleaned = input.trim().replace(/^sc-domain:/i, '')
+  const withProto = /^[a-z][\w+.-]*:\/\//i.test(cleaned) ? cleaned : `https://${cleaned}`
+  try {
+    return new URL(withProto).hostname.replace(/^www\./i, '')
+  }
+  catch {
+    return prettifyUrl(cleaned).split('/')[0] ?? ''
+  }
+}
+
+/**
+ * The URL itself when it is an absolute `http:` or `https:` URL, else
+ * `undefined`. Every `href` built from stored or caller data goes through
+ * this: a `javascript:` value in an anchor runs script on click, and the
+ * `scheme://` shape test it replaces let `javascript://%0A…` through.
+ */
+export function safeHttpHref(input: string | null | undefined): string | undefined {
+  if (!input)
+    return undefined
+  try {
+    return /^https?:$/.test(new URL(input).protocol) ? input : undefined
+  }
+  catch {
+    // Not an absolute URL, so there is nothing safe to link to.
+    return undefined
+  }
+}

package/types/index.ts

@@ -0,0 +1 @@
+export * from './ui'