@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/components/element/UiChatQuickLink.vue

@@ -0,0 +1,319 @@
+<script setup lang="ts">
+import type { RichSegment } from '../../../shared/rich-text'
+import type { NavigationDestination as RouteLocationRaw } from '../../shared/navigation'
+import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import type { ChatEntityRef } from './eject-menu'
+import { useRoute, useState } from 'nuxt/app'
+import { computed } from 'vue'
+import { NuxtLink, UiIcon, UiRichText } from '#components'
+import { buildChatDeepLinkQuery } from './eject-menu'
+import { useEjectTracker } from './eject-tracker'
+
+/**
+ * UiChatQuickLink — a surface-scoped box of preset, tokenized questions that open
+ * AI Chat already seeded and grounded.
+ *
+ * ## Why this exists (it replaces the eject affordance's chat item)
+ *
+ * `UiEjectMenu`'s "Open in AI Chat" hides one good question behind a kebab, and in
+ * practice the seed was authored per *card* — so ~47 of ~58 ejects ended up as
+ * duplicated site-level seeds whose only difference was hardcoded prose. That is
+ * the wrong grain: the user doesn't want "ask about this card", they want the one
+ * question that spans the five cards they'd otherwise have to assemble by hand.
+ *
+ * This component inverts it. An SEO expert reading a competitor page knows that
+ * "how do I capture their traffic?" is answered by Keyword Gaps + Top Keywords +
+ * Backlinks + Quick Wins + Shared Keywords together. We hand the user that
+ * question directly, in the open, and let the chat assemble the data. **The
+ * component's job is teaching**: one well-chosen question replaces knowing which
+ * sections to read in what order.
+ *
+ * ## What it is not
+ *
+ * Not the ambient "Ask AI" affordance DESIGN.md's Avoid list bans. It doesn't
+ * float, it doesn't follow scroll, it isn't a persistent drawer. It's a fixed,
+ * in-flow artifact whose questions are **hand-authored per surface and passed in
+ * by the page** — never generated, never generic. If a surface can't name 3–4
+ * questions its own data actually answers, it doesn't get one. A long list is a
+ * menu, not a teaching aid.
+ *
+ * ## Contract
+ *
+ * - Questions are templates: `{token}` placeholders are resolved from `tokens`.
+ *   A question whose tokens can't all be resolved is **dropped**, so a raw
+ *   `{competitorDomain}` can never reach the screen. Nothing resolvable → the
+ *   whole box renders nothing.
+ * - Clicking a question navigates (`:to`) with the chat deep-link query built by
+ *   `buildChatDeepLinkQuery` — the exact same path `UiEjectMenu`'s "Open in AI
+ *   Chat" takes, so `<ProChatPanel>` self-opens in place and hydrates `entity` /
+ *   `filter` server-side. There is deliberately no second route into chat.
+ * - Respects the per-user AI opt-out and the per-site AI availability flag, same
+ *   as `UiEjectMenu`; renders nothing when either is off.
+ * - Reports through the same `useEjectTracker()` seam (`open-chat`), so quick
+ *   links land in the existing eject telemetry rather than a parallel stream.
+ *
+ * ```vue
+ * <UiChatQuickLink
+ *   :questions="[
+ *     { text: 'How do I capture {competitorDomain}\'s traffic?', hint: 'Reads gaps, top keywords and backlinks together' },
+ *   ]"
+ *   :tokens="{ competitorDomain: competitor.domain }"
+ *   :entity="chatEntity.competitor(competitor.domain)"
+ *   :filter="{ siteId }"
+ *   :track="{ kind: 'competitor' }"
+ * />
+ * ```
+ */
+
+/**
+ * A token value. A bare string interpolates as plain text; `{ domain }` renders
+ * through the shared `domain` RichSegment — favicon + host — so the entity the
+ * question is about is something the eye lands on rather than prose it has to
+ * read. The seed sent to the model is always the plain text either way.
+ */
+export type ChatQuickToken = string | number | { domain: string }
+
+export interface ChatQuickQuestion {
+  /**
+   * The question, as a template. `{token}` placeholders resolve from the `tokens`
+   * prop; an unresolvable token drops the question rather than rendering the
+   * placeholder. Write it as the user would ask it, first person, one sentence.
+   */
+  text: string
+  /** Short visible label for compact layouts. The full question remains the chat seed and accessible name. */
+  label?: string
+  /** Per-question entity override; falls back to the box-level `entity`. */
+  entity?: ChatEntityRef
+  /** Extra deep-link filter merged over the box-level `filter`. */
+  filter?: Record<string, unknown>
+  /** Telemetry sub-variant for this specific question. */
+  variant?: string
+}
+
+const {
+  questions,
+  tokens,
+  entity,
+  filter,
+  to,
+  title = 'Ask AI Chat',
+  description,
+  compact = false,
+  icon = 'ai',
+  autoSend = true,
+  track,
+} = defineProps<{
+  /** Hand-authored questions for THIS surface. Keep to 3–4. */
+  questions: ChatQuickQuestion[]
+  /**
+   * Values for the `{token}` placeholders in each question's `text`. Empty or
+   * nullish values drop the questions that reference them, which is how a
+   * half-loaded page degrades to fewer questions instead of broken ones.
+   * Pass `{ domain }` for an entity that should render as a favicon token.
+   */
+  tokens?: Record<string, ChatQuickToken | null | undefined>
+  /**
+   * Default chat entity for every question. Build it through `chatEntity.*`
+   * (eject-menu.ts) — a bare id or raw URL fails scheme parsing and the server
+   * hydrate silently skips, so the chat answers ungrounded.
+   */
+  entity?: ChatEntityRef
+  /** Default deep-link filter, e.g. `{ siteId }`. */
+  filter?: Record<string, unknown>
+  /**
+   * Navigation target. Omit (the default) to stay in place: the deep-link keys
+   * merge over the current route's query and `<ProChatPanel>` self-opens as a
+   * slide-over. Only set `/pro/dashboard/chat` when an in-place slide-over can't
+   * open (already inside an overlay, or chat IS the destination).
+   */
+  to?: RouteLocationRaw
+  /** Box heading. Keep it a plain noun phrase, not a CTA. */
+  title?: string
+  /** Optional one-line framing above the questions. */
+  description?: string
+  /** Compact question bubbles without a card shell, suitable for a parent card's footer or side column. */
+  compact?: boolean
+  /** Leading glyph. `ai` is the standalone-chat-CTA glyph (DESIGN: one label, one glyph). */
+  icon?: UiIconName
+  /**
+   * Fire the question as the first message on open. True by default: these are
+   * complete, self-contained questions, so the user should get an answer rather
+   * than a pre-filled box they have to press enter on.
+   */
+  autoSend?: boolean
+  /** Telemetry enrichment; `kind` is the surface's domain entity ('competitor', 'query', …). */
+  track?: { kind?: string, variant?: string }
+}>()
+
+const route = useRoute()
+const trackEject = useEjectTracker()
+
+// Same two gates UiEjectMenu honours: the per-user AI opt-out (useAiSettings) and
+// the per-site AI availability flag set by the site layouts.
+const aiEnabled = useState<boolean>('pro:ai-enabled', () => true)
+const siteAiAvailable = useState<boolean>('pro:ai-site-available', () => true)
+
+const TOKEN_RE = /\{(\w+)\}/g
+
+function tokenText(value: ChatQuickToken | null | undefined): string | null {
+  if (value === null || value === undefined)
+    return null
+  const text = typeof value === 'object' && value !== null ? value.domain : String(value)
+  return text.trim() === '' ? null : text
+}
+
+/**
+ * Resolve `{token}` placeholders into BOTH representations at once:
+ *
+ * - `text` — the plain sentence. This is what seeds the model, and it must stay
+ *   plain: a favicon is a rendering, not something you can say to a model.
+ * - `segments` — the same sentence as typed `RichSegment`s, so a `{ domain }`
+ *   token renders through the shared `domain` segment (favicon + host) rather
+ *   than as bare prose. Reuses `UiRichText`'s vocabulary rather than minting a
+ *   second token treatment; the repo already carries one complaint about a site
+ *   rendered two different ways.
+ *
+ * Returns null when any token is missing or blank, so the caller drops the
+ * question instead of shipping a placeholder to the screen — or to the model.
+ */
+function interpolate(template: string): { text: string, segments: RichSegment[] } | null {
+  const segments: RichSegment[] = []
+  let text = ''
+  let cursor = 0
+  let missing = false
+
+  for (const match of template.matchAll(TOKEN_RE)) {
+    const [placeholder, key] = match
+    const at = match.index!
+    const value = tokens?.[key!]
+    const resolvedText = tokenText(value)
+    if (resolvedText === null) {
+      missing = true
+      break
+    }
+    if (at > cursor) {
+      const literal = template.slice(cursor, at)
+      text += literal
+      // UiRichText injects the inter-segment space (`spacing="none"` skips it
+      // before leftward-binding punctuation), so the literal run is trimmed —
+      // otherwise every gap would be doubled. `text` keeps the real spacing,
+      // because that string is what seeds the model.
+      segments.push({ kind: 'text', text: literal.trim() })
+    }
+    text += resolvedText
+    // Only an explicitly-typed token becomes a rich segment. A bare string stays
+    // text — inferring "looks like a hostname" would misfire on any keyword
+    // carrying a dot.
+    // `typeof null === 'object'`, so the null check is load-bearing, not
+    // defensive: without it this narrows to `{ domain: string } | null` and
+    // reads `.domain` off null. Unreachable today (`tokenText` returns null for
+    // a nullish value and we've already broken out), but the type is the guard.
+    segments.push(
+      value !== null && typeof value === 'object'
+        ? { kind: 'domain', text: resolvedText, domain: value.domain }
+        : { kind: 'text', text: resolvedText },
+    )
+    cursor = at + placeholder.length
+  }
+
+  if (missing)
+    return null
+
+  if (cursor < template.length) {
+    const tail = template.slice(cursor)
+    text += tail
+    segments.push({ kind: 'text', text: tail.trim() })
+  }
+  return { text, segments }
+}
+
+interface ResolvedQuestion {
+  key: string
+  text: string
+  label?: string
+  segments: RichSegment[]
+  variant?: string
+  to: RouteLocationRaw
+}
+
+const resolved = computed<ResolvedQuestion[]>(() => {
+  const out: ResolvedQuestion[] = []
+  for (const q of questions) {
+    const parsed = interpolate(q.text)
+    if (!parsed)
+      continue
+    const { text, segments } = parsed
+    const mergedFilter = filter || q.filter ? { ...filter, ...q.filter } : undefined
+    const link = {
+      entity: q.entity ?? entity,
+      filter: mergedFilter,
+      seed: text,
+      autoSend,
+    }
+    // Identical to UiEjectMenu's buildChatTarget: no target → merge the deep-link
+    // keys over the current query (preserving the surface's own tab/filter/sort
+    // state) and let the in-place panel pick them up.
+    const target: RouteLocationRaw = !to
+      ? { query: buildChatDeepLinkQuery(route.query, link) }
+      : typeof to === 'string'
+        ? { path: to, query: buildChatDeepLinkQuery({}, link) }
+        : { ...to, query: buildChatDeepLinkQuery(to.query ?? {}, link) }
+    out.push({ key: text, text, label: q.label, segments, variant: q.variant, to: target })
+  }
+  return out
+})
+
+// Author-time guard for the entity mistake the ChatEntityRef template type can't
+// catch: a raw URL, whose "https" prefix satisfies `${string}:${string}` but is no
+// registered hydrate scheme — the question would open chat without its grounding.
+if (import.meta.dev && entity) {
+  const scheme = entity.slice(0, entity.indexOf(':'))
+  if (!/^[a-z][a-z-]*$/.test(scheme) || scheme === 'http' || scheme === 'https')
+    console.warn(`[UiChatQuickLink] entity "${entity}" has no registered hydrate scheme — build it via chatEntity.* (eject-menu.ts) or hydration silently skips.`)
+}
+
+const visible = computed(() => aiEnabled.value && siteAiAvailable.value && resolved.value.length > 0)
+
+function onPick(q: ResolvedQuestion) {
+  trackEject({ action: 'open-chat', kind: track?.kind, variant: q.variant ?? track?.variant })
+}
+</script>
+
+<template>
+  <div
+    v-if="visible"
+    role="group"
+    :aria-label="title"
+    :class="compact ? 'flex flex-col gap-1.5 px-3 py-3 sm:flex-row sm:flex-wrap sm:items-center sm:gap-x-3' : 'rounded-lg border border-default bg-elevated/40'"
+  >
+    <div class="flex shrink-0 items-center gap-2" :class="compact ? '' : 'px-3 pt-2.5 pb-2'">
+      <UiIcon :name="icon" class="size-3.5 shrink-0 text-dimmed" aria-hidden="true" />
+      <span :class="compact ? 'text-xs font-medium text-muted' : 'text-label'">{{ title }}</span>
+    </div>
+    <p v-if="description" :class="compact ? 'w-full text-sm text-muted' : 'px-3 pb-2 text-xs text-muted'">
+      {{ description }}
+    </p>
+    <ul :class="compact ? 'flex min-w-0 flex-wrap gap-1' : 'divide-y divide-default border-t border-default'">
+      <li v-for="q in resolved" :key="q.key">
+        <NuxtLink
+          :to="q.to"
+          :aria-label="compact && q.label ? q.text : undefined"
+          class="group flex gap-2 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset"
+          :class="compact ? 'min-h-11 items-center rounded-xl rounded-bl-sm border border-default/40 bg-elevated/30 px-2 py-1.5 hover:border-default hover:bg-elevated/60 sm:min-h-7 sm:py-0.5' : 'items-start px-3 py-2.5 hover:bg-elevated/60'"
+          @click="onPick(q)"
+        >
+          <span class="min-w-0 flex-1 whitespace-pre-wrap text-sm" :class="compact ? 'text-muted transition-colors group-hover:text-default group-focus-visible:text-default' : 'text-default'">
+            <template v-if="compact && q.label">{{ q.label }}</template>
+            <UiRichText v-else :segments="q.segments" size="inherit" spacing="none" />
+          </span>
+          <UiIcon
+            v-if="!compact"
+            name="arrow-up-right"
+            class="mt-0.5 size-3.5 shrink-0 text-dimmed transition-colors group-hover:text-default"
+            aria-hidden="true"
+          />
+        </NuxtLink>
+      </li>
+    </ul>
+  </div>
+</template>

package/app/components/element/UiChip.vue

@@ -0,0 +1,101 @@
+<script setup lang="ts">
+import type { SemanticStatus } from '../../composables/semanticColors'
+import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import { computed } from 'vue'
+import { UiIcon } from '#components'
+import { semanticColors } from '../../composables/semanticColors'
+
+/**
+ * UiChip — the single chip/badge primitive, driven by a semantic `purpose`
+ * prop the same way UiButton is driven by `purpose`. There is no raw
+ * `variant`/`color` knob: each purpose resolves to a fixed treatment so chip
+ * intent reads consistently everywhere.
+ *
+ *   - `status`  semantic state (health, sync, validation). Colour comes from
+ *               the data-bound `status` prop on an AA-safe neutral surface.
+ *   - `count`   quantity / category metadata — neutral outline.
+ *   - `tag`     low-emphasis label / removable filter — muted fill.
+ *   - `accent`  standout marker (e.g. NEW) — inverted neutral.
+ *   - `brand`   deliberate brand marker (e.g. "Pro", "Most popular") — subtle
+ *               violet. Reserved for genuine brand markers; do not spray (it
+ *               spends the 60/30/10 accent budget).
+ *
+ * Maps onto UiButton's purposes: accent↔cta, count↔secondary, tag↔quiet,
+ * status='error'↔danger.
+ */
+
+const {
+  purpose = 'status',
+  status = 'neutral',
+  size = 'xs',
+  icon,
+  removable = false,
+  mono = false,
+  tabular = false,
+  label,
+} = defineProps<{
+  purpose?: 'status' | 'count' | 'tag' | 'accent' | 'brand'
+  /** Semantic status — only honoured when purpose='status'. */
+  status?: SemanticStatus
+  size?: 'xs' | 'sm' | 'md'
+  icon?: UiIconName
+  removable?: boolean
+  mono?: boolean
+  tabular?: boolean
+  /** Chip text, used to give the remove button a unique accessible name
+   *  ("Remove <label>"). Falls back to "Remove" when omitted. */
+  label?: string
+}>()
+
+const emit = defineEmits<{
+  remove: []
+}>()
+
+const sizeClass = {
+  xs: 'text-mini px-2 py-0.5 rounded-md gap-1',
+  sm: 'text-xs px-2.5 py-1 rounded-md gap-1.5',
+  md: 'text-sm px-2.5 py-1 rounded-md gap-1.5',
+} as const
+
+const colorClass = computed(() => {
+  switch (purpose) {
+    case 'count':
+      return 'border border-default bg-default text-muted'
+    case 'tag':
+      return 'bg-accented text-muted'
+    case 'accent':
+      return 'bg-inverted text-inverted'
+    case 'brand':
+      return 'bg-primary/10 text-primary'
+    case 'status':
+    default: {
+      const c = semanticColors[status]
+      return `border bg-default ${c.border} ${c.text}`
+    }
+  }
+})
+</script>
+
+<template>
+  <span
+    class="inline-flex items-center font-medium whitespace-nowrap"
+    :class="[
+      sizeClass[size],
+      colorClass,
+      mono && 'font-mono',
+      tabular && 'tabular-nums',
+    ]"
+  >
+    <UiIcon v-if="icon" :name="icon" class="size-3 shrink-0" aria-hidden="true" />
+    <slot />
+    <button
+      v-if="removable"
+      type="button"
+      class="-mr-0.5 inline-flex cursor-pointer items-center justify-center rounded-sm opacity-60 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+      :aria-label="label ? `Remove ${label}` : 'Remove'"
+      @click.stop="emit('remove')"
+    >
+      <UiIcon name="close" class="size-3" aria-hidden="true" />
+    </button>
+  </span>
+</template>

package/app/components/element/UiConfirmDialog.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import type { ConfirmTone } from '../../composables/useConfirm'
+import { UiButton, UiIcon, UModal } from '#components'
+
+/**
+ * UiConfirmDialog: the one "are you sure" for an action that is hard to undo.
+ *
+ * Open it through `useConfirm()`, which resolves `true` for the confirm button
+ * and `false` for Cancel, Escape, or a click outside. The dialog never runs the
+ * action itself, so the caller keeps its own pending state and error handling.
+ *
+ * Focus lands on Cancel for a `danger` tone, so Enter on a stray keypress
+ * cancels. A `default` tone focuses the confirm button.
+ */
+const {
+  title,
+  description,
+  confirmLabel,
+  cancelLabel = 'Cancel',
+  tone = 'danger',
+} = defineProps<{
+  /** A question that names the action and its object: "Disconnect Google?" */
+  title: string
+  /** The consequence, in one or two short sentences. */
+  description?: string
+  /** A verb for the action: "Disconnect", "Remove", "Delete". Never "OK". */
+  confirmLabel: string
+  cancelLabel?: string
+  tone?: ConfirmTone
+}>()
+
+const emit = defineEmits<{
+  /** `true` confirms. Nuxt UI's overlay resolves the open promise with it. */
+  close: [confirmed: boolean]
+}>()
+
+// Reka focuses the first focusable element unless this handler moves focus.
+// Pick the button by tone instead of trusting the DOM order.
+function onOpenAutoFocus(event: Event): void {
+  const root = event.target instanceof HTMLElement ? event.target : null
+  const target = root?.querySelector<HTMLElement>(`[data-confirm-focus="${tone === 'danger' ? 'cancel' : 'confirm'}"]`)
+  if (!target)
+    return
+  event.preventDefault()
+  target.focus()
+}
+</script>
+
+<template>
+  <UModal
+    :title="title"
+    :description="description"
+    :close="false"
+    :content="{ onOpenAutoFocus }"
+    :ui="{ content: 'sm:max-w-md', description: 'text-pretty' }"
+  >
+    <!-- The title slot keeps Nuxt UI's DialogTitle, so the dialog stays named
+         by its question. The icon is decoration. -->
+    <template #title>
+      <span class="inline-flex items-center gap-2">
+        <UiIcon v-if="tone === 'danger'" name="warning" class="size-4 shrink-0 text-error" aria-hidden="true" />
+        {{ title }}
+      </span>
+    </template>
+    <template #footer>
+      <div class="flex w-full flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+        <UiButton
+          purpose="quiet"
+          class="min-h-11 sm:min-h-0"
+          data-confirm-focus="cancel"
+          :label="cancelLabel"
+          @click="emit('close', false)"
+        />
+        <UiButton
+          :purpose="tone === 'danger' ? 'danger' : 'cta'"
+          class="min-h-11 sm:min-h-0"
+          data-confirm-focus="confirm"
+          :label="confirmLabel"
+          @click="emit('close', true)"
+        />
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/element/UiCopyButton.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import { useClipboard } from '@vueuse/core'
+import { computed } from 'vue'
+import { UiButton } from '#components'
+
+/**
+ * UiCopyButton: copy one string, then confirm it.
+ *
+ * The icon turns into a check and a visible label reads "Copied" for two
+ * seconds. A polite live region says "Copied" too, so a screen reader hears
+ * the result of a press that changes nothing else on the page.
+ *
+ * Without `label` the button is icon-only, and `ariaLabel` names it. Name it
+ * after the thing it copies ("Copy endpoint"), not after the action alone.
+ */
+defineOptions({ inheritAttrs: false })
+
+const {
+  text,
+  label,
+  ariaLabel = 'Copy',
+  copiedLabel = 'Copied',
+  purpose = 'quiet',
+  size = 'xs',
+  block = false,
+  disabled = false,
+} = defineProps<{
+  /** The string the press puts on the clipboard. */
+  text: string
+  /** Visible label. Omit for an icon-only button. */
+  label?: string
+  /** Accessible name of an icon-only button. A visible `label` names it otherwise. */
+  ariaLabel?: string
+  /** Visible label and announcement after a copy. */
+  copiedLabel?: string
+  purpose?: 'cta' | 'secondary' | 'quiet'
+  size?: 'xs' | 'sm' | 'md' | 'lg'
+  /** Fill the width of the parent. Labelled buttons only. */
+  block?: boolean
+  disabled?: boolean
+}>()
+
+const emit = defineEmits<{
+  /** The copy finished. Use it for telemetry. */
+  copied: [text: string]
+}>()
+
+const { copy, copied } = useClipboard({ legacy: true, copiedDuring: 2000 })
+
+const icon = computed<UiIconName>(() => copied.value ? 'check' : 'copy')
+
+function onClick(): void {
+  // `useClipboard` sets `copied` only when the write lands, and falls back
+  // to execCommand with `legacy`. A write that still fails leaves the label
+  // on "Copy" and its rejection reaches the global handler.
+  void copy(text).then(() => {
+    if (copied.value)
+      emit('copied', text)
+  })
+}
+</script>
+
+<template>
+  <span data-ui="UiCopyButton" class="contents">
+    <UiButton
+      v-if="label"
+      :purpose="purpose"
+      :size="size"
+      :icon="icon"
+      :disabled="disabled"
+      :block="block"
+      :label="copied ? copiedLabel : label"
+      v-bind="$attrs"
+      @click="onClick"
+    />
+    <UiButton
+      v-else
+      :purpose="purpose"
+      :size="size"
+      :icon="icon"
+      :disabled="disabled"
+      :aria-label="ariaLabel"
+      v-bind="$attrs"
+      class="min-h-11 min-w-11 [@media(pointer:fine)]:min-h-8 [@media(pointer:fine)]:min-w-8"
+      @click="onClick"
+    />
+    <span class="sr-only" role="status" aria-live="polite">{{ copied ? copiedLabel : '' }}</span>
+  </span>
+</template>