@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/shared/error-state.ts

@@ -0,0 +1,150 @@
+import type { UiIcon } from './ui-icons'
+import { toWidgetFailure, WIDGET_FAILURE_COPY } from './widget-failure'
+
+/**
+ * What `UiErrorState` is allowed to say, and where the words came from.
+ *
+ * The old prop was `string | { message: string }`. Both arms rendered their
+ * string, so a caught query error and a hand-written sentence were the same
+ * type. Six pro pages passed the caught error, and ofetch writes the request
+ * into `message`: `[GET] "/api/pro/v1/sites/<id>/search/status": 500 Internal
+ * Server Error`. That put an internal route and a site id on a customer's
+ * screen, and credentials have reached error strings the same way before.
+ *
+ * The tag now records provenance, which is the thing the two arms never agreed
+ * on. A `wire` value is a caught object. It is typed `unknown`, so no template
+ * can read a string off it; only the HTTP status code is read, and only to pick
+ * copy this file owns. A `copy` value is a sentence the caller wrote, which is
+ * safe to render because a person chose the words.
+ *
+ * A caller can no longer pass a caught error where copy is expected: the free
+ * tools keep rendering their own vetted copy through `errorCopy`, and a pro
+ * page must say `wireError` and accept classified copy instead.
+ */
+export type ErrorStateSource
+  = | { readonly _tag: 'wire', readonly error: unknown }
+    | { readonly _tag: 'copy', readonly title: string, readonly detail?: string }
+    | {
+      readonly _tag: 'rate-limited'
+      readonly detail: string
+      readonly resetAt?: Date
+      readonly retryAfter?: number
+    }
+
+/**
+ * Classify a caught value. The component reads its status code and nothing else.
+ *
+ * Pass the raw error. Wrapping it in `new Error(someMessage)` throws away the
+ * status code the classifier needs and buys no safety.
+ */
+export function wireError(error: unknown): ErrorStateSource {
+  return { _tag: 'wire', error }
+}
+
+/**
+ * Render a sentence the caller wrote. Use it for copy a person authored.
+ *
+ * Never pass an error's `message` through here. Use `wireError` for a caught
+ * value, so the status code picks the copy.
+ */
+export function errorCopy(title: string, detail?: string): ErrorStateSource {
+  return { _tag: 'copy', title, detail }
+}
+
+/**
+ * A quota refusal the caller already parsed, with the reset it read from the
+ * response headers. `wireError` covers a 429 too, but it cannot state a reset
+ * time, because a status code carries none.
+ */
+export function rateLimited(
+  detail: string,
+  reset?: { resetAt?: Date, retryAfter?: number },
+): ErrorStateSource {
+  return { _tag: 'rate-limited', detail, resetAt: reset?.resetAt, retryAfter: reset?.retryAfter }
+}
+
+/**
+ * The next-step line under the message.
+ *
+ * Tagged because the two kinds behave differently: a `timing` line states a
+ * real reset the caller measured and always shows, while a `generic` line is
+ * filler that an `#action` slot replaces with something better.
+ */
+export type ErrorStateNextStep
+  = | { readonly _tag: 'timing', readonly text: string }
+    | { readonly _tag: 'generic', readonly text: string }
+
+/** Everything the template renders. No field holds a caught value. */
+export interface ErrorStateView {
+  readonly tone: 'error' | 'warning'
+  readonly icon: UiIcon
+  /** What happened. */
+  readonly title: string
+  /** What to do about it, when the failure is specific enough to say. */
+  readonly detail: string | null
+  readonly nextStep: ErrorStateNextStep | null
+  /** Whether retrying the same request can succeed. */
+  readonly retryable: boolean
+}
+
+const GENERIC_NEXT_STEP = 'Try again in a moment. If it keeps happening, contact support.'
+
+function resetHint(source: { resetAt?: Date, retryAfter?: number }, now: number): string | null {
+  if (source.retryAfter)
+    return `Try again in ${source.retryAfter} seconds`
+
+  if (!source.resetAt)
+    return null
+
+  const remaining = source.resetAt.getTime() - now
+  if (remaining <= 0)
+    return null
+  if (remaining < 60_000)
+    return `Resets in ${Math.ceil(remaining / 1000)} seconds`
+  if (remaining < 3_600_000)
+    return `Resets in ${Math.ceil(remaining / 60_000)} minutes`
+  return 'Resets at midnight UTC'
+}
+
+/**
+ * Turn a source into the words on screen. Pure: pass the clock in, so the
+ * reset hint is testable and the component owns no time.
+ */
+export function resolveErrorState(source: ErrorStateSource, now: number): ErrorStateView {
+  if (source._tag === 'copy') {
+    return {
+      tone: 'error',
+      icon: 'caution',
+      title: source.title,
+      detail: source.detail ?? null,
+      nextStep: { _tag: 'generic', text: GENERIC_NEXT_STEP },
+      retryable: true,
+    }
+  }
+
+  if (source._tag === 'rate-limited') {
+    const hint = resetHint(source, now)
+    return {
+      tone: 'warning',
+      icon: 'clock',
+      title: WIDGET_FAILURE_COPY['rate-limited'].title,
+      detail: source.detail,
+      nextStep: hint
+        ? { _tag: 'timing', text: hint }
+        : { _tag: 'generic', text: WIDGET_FAILURE_COPY['rate-limited'].body },
+      retryable: true,
+    }
+  }
+
+  const failure = toWidgetFailure(source.error)
+  const copy = WIDGET_FAILURE_COPY[failure._tag]
+  const limited = failure._tag === 'rate-limited'
+  return {
+    tone: limited ? 'warning' : 'error',
+    icon: limited ? 'clock' : 'caution',
+    title: copy.title,
+    detail: copy.body,
+    nextStep: null,
+    retryable: copy.retryable,
+  }
+}

package/app/shared/icons.ts

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

package/app/shared/motion.ts

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

package/app/shared/nav.ts

@@ -0,0 +1,38 @@
+export interface UiNavStability {
+  icon: string
+  tooltip: string
+}
+
+export interface UiNavSetup {
+  /**
+   * One short imperative word naming what the user owes this row — "Connect",
+   * "Confirm". Rendered verbatim in an outline chip, so anything longer than a
+   * single word is a layout bug; the full state goes in `tooltip`.
+   */
+  verb: string
+  tooltip: string
+  tone?: 'primary' | 'warning'
+}
+
+export interface UiNavLink {
+  label: string
+  to: string
+  icon?: string
+  disabled?: boolean
+  title?: string
+  badge?: string
+  badgeColor?: 'primary' | 'warning' | 'neutral'
+  setup?: UiNavSetup | null
+  stability?: UiNavStability | null
+  pending?: boolean
+  pendingTooltip?: string
+  /** Optional text-tone lift for a small subset of peer navigation items. */
+  textTone?: 'highlighted'
+  active?: (path: string) => boolean
+  /**
+   * Opt out of NuxtLink's idle route-chunk prefetch. Set `false` on links to
+   * explorer-sized routes (hundreds of KB) that sit in an always-visible nav —
+   * the sidebar would otherwise pull them on every page view.
+   */
+  prefetch?: boolean
+}

package/app/shared/navigation.ts

@@ -0,0 +1,5 @@
+import type { RouteLocationAsPathGeneric, RouteLocationAsRelative } from 'vue-router'
+
+// Keep named routes and their params typed. URL paths stay open, like string URLs.
+// Vue props cannot expand every generated path variant in a large RouteMap.
+export type NavigationDestination = string | RouteLocationAsRelative | RouteLocationAsPathGeneric

package/app/shared/static-terminal.ts

@@ -0,0 +1,14 @@
+export interface UiStaticTerminalLine {
+  /** The command without the shell prompt. */
+  command: string
+  /** Show a shell prompt. Set false for source code or configuration. */
+  prompt?: boolean
+  /** A shell comment shown before the command. */
+  note?: string
+  /** Static output shown after the command. */
+  output?: string
+  /** Rangi language for the command. */
+  language?: string
+  /** Rangi language for the output. */
+  outputLanguage?: string
+}

package/app/shared/table-export.ts

@@ -0,0 +1,36 @@
+import type { ExportColumn } from '../utils/export-download'
+
+/** The part of a TanStack row an export reads. */
+export interface ExportableRow {
+  getValue: <TValue>(columnId: string) => TValue
+}
+
+/** The part of a TanStack table an export reads. */
+export interface ExportableTable<R extends ExportableRow> {
+  getPrePaginatedRowModel: () => { rows: R[] }
+  getVisibleLeafColumns: () => ReadonlyArray<{
+    id: string
+    accessorFn?: unknown
+    columnDef: { header?: unknown }
+  }>
+}
+
+/**
+ * Every row of a client-side table after its filters and sort, before paging,
+ * with one export column per visible data column. A display column with no
+ * accessor, such as row actions, is left out. A column whose header is not a
+ * plain string exports under its column id.
+ *
+ * Pagination is the only thing an export skips: a user who exports page 1 of 4
+ * expects the whole table.
+ */
+export function uiTableExport<R extends ExportableRow>(table: ExportableTable<R>): { rows: R[], columns: ExportColumn<R>[] } {
+  const columns = table.getVisibleLeafColumns()
+    .filter(column => column.accessorFn !== undefined)
+    .map((column): ExportColumn<R> => ({
+      key: column.id,
+      header: typeof column.columnDef.header === 'string' && column.columnDef.header !== '' ? column.columnDef.header : column.id,
+      value: row => row.getValue(column.id),
+    }))
+  return { rows: table.getPrePaginatedRowModel().rows, columns }
+}

package/app/shared/table.ts

@@ -0,0 +1,105 @@
+import type { ColumnDef } from '@tanstack/table-core'
+import {
+  columnFilteringFeature,
+  columnOrderingFeature,
+  columnVisibilityFeature,
+  createExpandedRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  rowExpandingFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_datetime,
+  sortFn_text,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export type UiTableSize = 'xs' | 'sm' | 'md'
+export type UiTableAlign = 'left' | 'center' | 'right'
+
+export const uiTableCellSizeClass: Record<UiTableSize, string> = {
+  xs: 'h-11 py-1 sm:h-8',
+  sm: 'h-11 py-1 sm:h-10',
+  md: 'h-11 py-2 sm:h-10',
+}
+
+export const uiTableSkeletonSizeClass: Record<UiTableSize, string> = {
+  xs: 'h-4',
+  sm: 'h-4',
+  md: 'h-6',
+}
+
+export type UiTableVisibleFrom = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+export interface UiTableCellProps {
+  align?: UiTableAlign
+  numeric?: boolean
+  visibleFrom?: UiTableVisibleFrom
+}
+
+export interface UiTableColumnMeta extends UiTableCellProps {
+  noPadding?: boolean
+  stableData?: boolean
+  tooltip?: string
+  headClass?: string
+  cellClass?: string
+  rowHeader?: boolean
+  ui?: { td?: { base?: string } }
+}
+
+export const uiTableFeatures = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  columnOrderingFeature,
+  columnVisibilityFeature,
+  rowExpandingFeature,
+  expandedRowModel: createExpandedRowModel(),
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  // Auto sorting picks one of these names for a string or Date column. Left
+  // unregistered, it falls back to a plain `<` compare, so "Page2" sorts
+  // before "page1" and "page10" before "page2".
+  sortFns: {
+    alphanumeric: sortFn_alphanumeric,
+    datetime: sortFn_datetime,
+    text: sortFn_text,
+  },
+})
+
+export type UiTableFeatures = typeof uiTableFeatures
+export type UiTableColumn<T extends object> = ColumnDef<UiTableFeatures, T, unknown> & UiTableColumnMeta
+export type UiTableRowId<T> = string | ((row: T) => string)
+
+/**
+ * A row's id: the `rowId` key or function, else the row's own `id`. A row with
+ * no usable id falls back to its index. Without that fallback every such row
+ * shared the id "", so selection, expansion and keys collided across rows. The
+ * fallback is prefixed: a bare index collided with a real id such as "1".
+ */
+export function resolveUiTableRowId<T extends object>(row: T, index: number, rowId?: UiTableRowId<T>): string {
+  const record = row as Record<string, unknown>
+  const id = rowId === undefined
+    ? record.id
+    : typeof rowId === 'function'
+      ? rowId(row)
+      : record[rowId]
+  if (typeof id === 'string' && id !== '')
+    return id
+  if (typeof id === 'number')
+    return String(id)
+  return `__index:${index}`
+}
+
+export const uiTableVisibleFromClass: Record<UiTableVisibleFrom, string> = {
+  'sm': 'hidden sm:table-cell',
+  'md': 'hidden md:table-cell',
+  'lg': 'hidden lg:table-cell',
+  'xl': 'hidden xl:table-cell',
+  '2xl': 'hidden 2xl:table-cell',
+}

package/app/shared/ui-icons.ts

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

package/app/shared/view-state.ts

@@ -0,0 +1,85 @@
+/**
+ * What an async data region shows: one of four states, decided in one place.
+ *
+ * A region used to take `loading` and `items` and render its empty copy for
+ * anything else. A failed read left `items` empty, so the Search Console
+ * Overview told a user "No queries in this window" while the server returned a
+ * 503. A read that had not started yet did the same. The empty copy is a claim
+ * about the user's data, and only a successful answer can make it.
+ *
+ * So a region takes this union instead. `empty` exists only when a read
+ * succeeded and held nothing, and a template switches on `_tag`, so no branch
+ * can show the empty copy for a failure or for a read still in flight.
+ */
+export type ViewState<T>
+  = | { readonly _tag: 'loading' }
+    | { readonly _tag: 'error', readonly error: unknown }
+    | { readonly _tag: 'empty' }
+    | {
+      readonly _tag: 'data'
+      readonly data: T
+      /**
+       * A later read failed while an earlier answer is still on screen. The
+       * region keeps the rows and says the refresh failed, so a failed refresh
+       * never throws away evidence and never passes for fresh data.
+       */
+      readonly refreshError: unknown
+    }
+
+export type ViewStateTag = ViewState<unknown>['_tag']
+
+export interface ViewStateInput<T> {
+  /** A read is in flight. */
+  readonly pending: boolean
+  /** The last read's failure. Any falsy value means it did not fail. */
+  readonly error: unknown
+  /**
+   * The last successful answer. `null` or `undefined` means no read has
+   * succeeded yet, which covers a read that has not started: on the server, or
+   * before its inputs resolve.
+   */
+  readonly data: T | null | undefined
+  /** Whether a successful answer holds nothing to show. */
+  readonly isEmpty: (data: T) => boolean
+}
+
+const LOADING: ViewState<never> = { _tag: 'loading' }
+const EMPTY: ViewState<never> = { _tag: 'empty' }
+
+/**
+ * Decide the state of a region. Pure.
+ *
+ * The order is the contract:
+ * 1. A read in flight is `loading`.
+ * 2. A failure with nothing to show is `error`, never `empty`.
+ * 3. No answer yet is `loading`, never `empty`.
+ * 4. A successful answer with nothing in it is `empty`.
+ * 5. Anything else is `data`, with the failure of a later read, if any.
+ */
+export function viewState<T>(input: ViewStateInput<T>): ViewState<T> {
+  if (input.pending)
+    return LOADING
+  const failed = Boolean(input.error)
+  const answer = input.data
+  if (answer === null || answer === undefined)
+    return failed ? { _tag: 'error', error: input.error } : LOADING
+  if (input.isEmpty(answer))
+    return failed ? { _tag: 'error', error: input.error } : EMPTY
+  return { _tag: 'data', data: answer, refreshError: failed ? input.error : null }
+}
+
+/** `viewState` for a list: an answer with no rows is `empty`. */
+export function listViewState<L extends readonly unknown[]>(input: Omit<ViewStateInput<L>, 'isEmpty'>): ViewState<L> {
+  return viewState<L>({ ...input, isEmpty: rows => rows.length === 0 })
+}
+
+/**
+ * Reshape the answer of a `data` state and keep every other state. A list that
+ * maps its rows for display, such as table rows built from query rows, keeps
+ * the state its read decided.
+ */
+export function mapViewState<A, B>(state: ViewState<A>, map: (data: A) => B): ViewState<B> {
+  return state._tag === 'data'
+    ? { _tag: 'data', data: map(state.data), refreshError: state.refreshError }
+    : state
+}

package/app/shared/widget-failure.ts

@@ -0,0 +1,126 @@
+/**
+ * Why an async region failed, in the only terms the UI is allowed to state.
+ *
+ * The tag is derived from an HTTP status code, which is a number. It is never
+ * derived from an error's `message`. `message` on a failed fetch is developer
+ * text that quotes the request: ofetch renders `[GET] "/api/pro/sites/42/…":
+ * 500 Internal Server Error`. Rendering that puts an internal route, a site id,
+ * and any query string on a customer's screen. Credentials have leaked this way
+ * before, so the widget layer holds no path from a wire string to the DOM.
+ *
+ * `unknown` covers every input this cannot place: a network drop, an abort, a
+ * response-schema mismatch, a plain `Error`, `null`. Those carry no status.
+ */
+export type WidgetFailure
+  = | { readonly _tag: 'signed-out' }
+    | { readonly _tag: 'no-access' }
+    | { readonly _tag: 'missing' }
+    | { readonly _tag: 'rate-limited' }
+    | { readonly _tag: 'rejected' }
+    | { readonly _tag: 'server' }
+    | { readonly _tag: 'unknown' }
+
+export type WidgetFailureTag = WidgetFailure['_tag']
+
+export interface WidgetFailureCopy {
+  /** What happened. */
+  readonly title: string
+  /** What to do next. */
+  readonly body: string
+  /**
+   * Whether retrying the same read can succeed. A retry button on a 401 or a
+   * 403 is advice that cannot work, so those branches hide it.
+   */
+  readonly retryable: boolean
+}
+
+/**
+ * The copy for every failure the UI can show.
+ *
+ * `satisfies Record<WidgetFailureTag, WidgetFailureCopy>` is the guard: a new
+ * tag fails the typecheck here until someone writes its copy, so no failure can
+ * reach a customer without one.
+ */
+export const WIDGET_FAILURE_COPY = {
+  'signed-out': {
+    title: 'Your session ended',
+    body: 'Sign in again to load this data.',
+    retryable: false,
+  },
+  'no-access': {
+    title: 'Access denied',
+    body: 'Ask a teammate to grant you access.',
+    retryable: false,
+  },
+  'missing': {
+    title: 'Not found',
+    body: 'This data moved or was removed.',
+    retryable: false,
+  },
+  'rate-limited': {
+    title: 'Too many requests',
+    body: 'Wait a moment, then retry.',
+    retryable: true,
+  },
+  'rejected': {
+    title: 'The request was rejected',
+    body: 'Reload the page, then try again.',
+    retryable: true,
+  },
+  'server': {
+    title: 'The server failed',
+    body: 'We logged this failure. Retry in a moment.',
+    retryable: true,
+  },
+  'unknown': {
+    title: 'This data failed to load',
+    body: 'Check your connection, then retry.',
+    retryable: true,
+  },
+} as const satisfies Record<WidgetFailureTag, WidgetFailureCopy>
+
+/**
+ * HTTP status from any error shape.
+ *
+ * Twin of `queryErrorStatusCode` in `layers/core/app/utils/rpc.ts`. It is copied
+ * rather than imported because ADR-0042 lets `design-system` import `core` for
+ * types only. Both read the same four fields; keep them in step.
+ */
+function statusCodeOf(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object')
+    return undefined
+  const e = error as {
+    statusCode?: unknown
+    status?: unknown
+    data?: { statusCode?: unknown }
+    response?: { status?: unknown }
+  }
+  const candidate = [e.statusCode, e.status, e.data?.statusCode, e.response?.status]
+    .find(value => typeof value === 'number')
+  return typeof candidate === 'number' ? candidate : undefined
+}
+
+/**
+ * Parse an arbitrary caught value once, at the widget boundary, into the tag the
+ * template trusts. Everything inward of this function is safe to render.
+ */
+export function toWidgetFailure(error: unknown): WidgetFailure {
+  const status = statusCodeOf(error)
+  if (status === 401)
+    return { _tag: 'signed-out' }
+  if (status === 403)
+    return { _tag: 'no-access' }
+  if (status === 404)
+    return { _tag: 'missing' }
+  if (status === 429)
+    return { _tag: 'rate-limited' }
+  if (status !== undefined && status >= 400 && status < 500)
+    return { _tag: 'rejected' }
+  if (status !== undefined && status >= 500)
+    return { _tag: 'server' }
+  return { _tag: 'unknown' }
+}
+
+export function widgetFailureCopy(error: unknown): WidgetFailureCopy {
+  return WIDGET_FAILURE_COPY[toWidgetFailure(error)._tag]
+}