@vibeuncle/gpgb-ui 0.2.0

package/src/components/ConfirmDialog.tsx

@@ -0,0 +1,22 @@
+'use client'
+import type { ReactNode } from 'react'
+import { Modal } from './Modal'
+import { Button } from './Button'
+import { t } from '../copy'
+import type { Lang } from '../copy'
+
+/** Confirm before a destructive or irreversible action. Name the action in `confirmLabel` ("删除海报", not "确定"). */
+export function ConfirmDialog({ open, onCancel, onConfirm, title, children, confirmLabel, cancelLabel, danger, busy, lang }: {
+  open: boolean; onCancel: () => void; onConfirm: () => void; title: string; children?: ReactNode
+  confirmLabel?: string; cancelLabel?: string; danger?: boolean; busy?: boolean; lang?: Lang
+}) {
+  return (
+    <Modal open={open} onClose={onCancel} title={title} lang={lang}
+      footer={<>
+        <Button variant="outline" onClick={onCancel} disabled={busy}>{cancelLabel ?? t(lang, 'cancel')}</Button>
+        <Button variant={danger ? 'danger' : 'primary'} onClick={onConfirm} aria-busy={busy || undefined}>{confirmLabel ?? t(lang, 'confirm')}</Button>
+      </>}>
+      {children}
+    </Modal>
+  )
+}

package/src/components/Field.tsx

@@ -0,0 +1,45 @@
+import { useId } from 'react'
+import type { InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from 'react'
+import { cn } from '../cn'
+
+interface FieldProps {
+  label: string
+  hint?: string
+  error?: string
+  children: (props: { id: string; 'aria-invalid'?: true; 'aria-describedby'?: string }) => ReactNode
+}
+
+/** Label + control + hint/error, wired for a11y. */
+export function Field({ label, hint, error, children }: FieldProps) {
+  const id = useId()
+  const descId = hint || error ? `${id}-desc` : undefined
+  return (
+    <div>
+      <label className="ds-label" htmlFor={id}>{label}</label>
+      {children({ id, 'aria-invalid': error ? true : undefined, 'aria-describedby': descId })}
+      {error ? <p id={descId} className="ds-error" role="alert">{error}</p>
+        : hint ? <p id={descId} className="ds-hint mt-1.5">{hint}</p> : null}
+    </div>
+  )
+}
+
+export function Input({ className, small, ...rest }: InputHTMLAttributes<HTMLInputElement> & { small?: boolean }) {
+  return <input className={cn('ds-input', small && 'ds-input-sm', className)} {...rest} />
+}
+
+export function Textarea({ className, ...rest }: TextareaHTMLAttributes<HTMLTextAreaElement>) {
+  return <textarea className={cn('ds-input', className)} {...rest} />
+}
+
+export function Select({ className, ...rest }: SelectHTMLAttributes<HTMLSelectElement>) {
+  return <select className={cn('ds-input', className)} {...rest} />
+}
+
+export function Switch({ checked, onChange, label, disabled }: {
+  checked: boolean; onChange: (v: boolean) => void; label: string; disabled?: boolean
+}) {
+  return (
+    <button type="button" role="switch" aria-checked={checked} aria-label={label} disabled={disabled}
+      className="ds-switch" onClick={() => onChange(!checked)} />
+  )
+}

package/src/components/Layout.tsx

@@ -0,0 +1,62 @@
+'use client'
+
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+import { t } from '../copy'
+import type { Lang } from '../copy'
+import { useLink } from '../link'
+
+/** Standard page: header, main, footer. Content width via `ds-container`. */
+export function PageShell({ header, children, footer }: { header?: ReactNode; children: ReactNode; footer?: ReactNode }) {
+  return (
+    <div className="ds-page">
+      {header}
+      <main id="main" className="ds-container py-10">{children}</main>
+      {footer}
+    </div>
+  )
+}
+
+/** Single centred card on paper: sign-in, invite, confirmation, not-found. */
+export function CenteredPage({ children }: { children: ReactNode }) {
+  return <div className="ds-page-centered"><main id="main" className="ds-card">{children}</main></div>
+}
+
+/** Page title row: serif title + description on the left, actions on the right (primary action first on phones). */
+export function PageTitle({ title, description, actions, breadcrumbs }: { title: string; description?: string; actions?: ReactNode; breadcrumbs?: ReactNode }) {
+  return (
+    <div className="mb-9">
+      {breadcrumbs && <div className="mb-3">{breadcrumbs}</div>}
+      <div className="ds-page-title !mb-0">
+        <div className="min-w-0">
+          <h1 className="font-display text-4xl font-medium sm:text-5xl">{title}</h1>
+          {description && <p className="mt-3 max-w-[44em] text-[13px] leading-[1.85] text-ink-soft">{description}</p>}
+        </div>
+        {actions && <div className="flex flex-wrap items-center gap-2">{actions}</div>}
+      </div>
+    </div>
+  )
+}
+
+/** Sidebar + content (editor, settings, admin). Sidebar is sticky from `lg`; on phones put its content in a Sheet instead. */
+export function SidebarLayout({ aside, children, wide }: { aside: ReactNode; children: ReactNode; wide?: boolean }) {
+  return <div className={cn('ds-shell', wide && 'ds-shell-wide')}><aside>{aside}</aside><div className="min-w-0">{children}</div></div>
+}
+
+export function SiteFooter({ logoSrc, logoAlt = '大道大商', links = [], note, lang }: {
+  logoSrc?: string; logoAlt?: string; links?: Array<{ label: string; href: string }>; note?: string; lang?: Lang
+}) {
+  const Link = useLink()
+  return (
+    <footer className="ds-footer">
+      <div className="ds-container flex flex-wrap items-center justify-between gap-x-6 gap-y-3">
+        <div className="flex items-center gap-3">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          {logoSrc && <img src={logoSrc} alt={logoAlt} className="brand-logo h-5 w-auto opacity-80" />}
+          <span>{note ?? `© ${new Date().getFullYear()} ${t(lang, 'copyright')}`}</span>
+        </div>
+        {links.length > 0 && <nav aria-label="Footer" className="flex flex-wrap gap-x-5 gap-y-1">{links.map(l => <Link key={l.href} href={l.href}>{l.label}</Link>)}</nav>}
+      </div>
+    </footer>
+  )
+}

package/src/components/Modal.tsx

@@ -0,0 +1,35 @@
+'use client'
+import { useId, useRef } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { X } from 'lucide-react'
+import { t } from '../copy'
+import type { Lang } from '../copy'
+import { useFocusTrap, useScrollLock } from '../hooks'
+
+/** Dialog: focus moves in and loops, Esc + backdrop close, focus returns to the opener, scroll locked, labelled.
+ *  Footer buttons: outline "cancel" then the primary action. For a task that needs neither interruption nor protected focus, use a page, not a modal. */
+export function Modal({ open, onClose, title, children, footer, lang, closeLabel }: {
+  open: boolean; onClose: () => void; title: string; children: ReactNode; footer?: ReactNode; lang?: Lang; closeLabel?: string
+}) {
+  const titleId = useId()
+  const ref = useRef<HTMLDivElement>(null)
+  useFocusTrap(open, ref, onClose)
+  useScrollLock(open)
+  if (!open) return null
+  return createPortal(
+    <div className="ds-backdrop" onClick={onClose}>
+      <div ref={ref} className="ds-modal" role="dialog" aria-modal="true" aria-labelledby={titleId} onClick={e => e.stopPropagation()}>
+        <div className="mb-4 flex items-start justify-between gap-4">
+          <h2 id={titleId} className="font-display text-xl text-ink">{title}</h2>
+          <button type="button" className="ds-btn ds-btn-ghost ds-btn-icon" onClick={onClose} aria-label={closeLabel ?? t(lang, 'close')}>
+            <X size={18} />
+          </button>
+        </div>
+        <div className="text-sm text-ink-soft">{children}</div>
+        {footer && <div className="mt-6 flex justify-end gap-2">{footer}</div>}
+      </div>
+    </div>,
+    document.body,
+  )
+}

package/src/components/Nav.tsx

@@ -0,0 +1,98 @@
+'use client'
+import { ChevronRight, Menu as MenuIcon, Check } from 'lucide-react'
+import type { ReactNode } from 'react'
+import { cn } from '../cn'
+import { t } from '../copy'
+import type { Lang } from '../copy'
+import { Sheet } from './Sheet'
+import { useLink } from '../link'
+
+export interface NavItem { label: string; href: string; icon?: ReactNode; current?: boolean }
+
+/** Header navigation: pill links, current page = accent-soft wash with aria-current="page". Hide on phones; use NavDrawer there. */
+export function NavLinks({ items, lang, className }: { items: NavItem[]; lang?: Lang; className?: string }) {
+  const Link = useLink()
+  return (
+    <nav aria-label={t(lang, 'mainNav')} className={cn('flex items-center gap-1', className)}>
+      {items.map(i => (
+        <Link key={i.href} href={i.href} className="ds-nav-link" aria-current={i.current ? 'page' : undefined}>{i.icon}{i.label}</Link>
+      ))}
+    </nav>
+  )
+}
+
+/** Phone navigation: hamburger button + left drawer. Place the button in the header, visible below `md`. */
+export function NavDrawer({ items, open, onOpenChange, title, footer, lang }: {
+  items: NavItem[]; open: boolean; onOpenChange: (v: boolean) => void; title?: string; footer?: ReactNode; lang?: Lang
+}) {
+  const Link = useLink()
+  return (
+    <Sheet open={open} onClose={() => onOpenChange(false)} side="left" title={title ?? t(lang, 'menu')} lang={lang}>
+      <nav aria-label={t(lang, 'mainNav')} className="flex flex-col gap-1">
+        {items.map(i => (
+          <Link key={i.href} href={i.href} className="ds-drawer-link" aria-current={i.current ? 'page' : undefined} onClick={() => onOpenChange(false)}>{i.icon}{i.label}</Link>
+        ))}
+      </nav>
+      {footer && <div className="mt-6 border-t border-border-soft pt-4">{footer}</div>}
+    </Sheet>
+  )
+}
+
+export function MenuButton({ onClick, expanded, lang }: { onClick: () => void; expanded?: boolean; lang?: Lang }) {
+  return (
+    <button type="button" className="ds-btn ds-btn-ghost ds-btn-icon" onClick={onClick} aria-label={t(lang, 'openMenu')} aria-expanded={expanded} aria-haspopup="dialog">
+      <MenuIcon size={20} />
+    </button>
+  )
+}
+
+/** Where you are. The last item is the current page and is not a link. */
+export function Breadcrumbs({ items, lang }: { items: Array<{ label: string; href?: string }>; lang?: Lang }) {
+  const Link = useLink()
+  return (
+    <nav aria-label={t(lang, 'breadcrumb')}>
+      <ol className="ds-crumbs">
+        {items.map((c, i) => {
+          const last = i === items.length - 1
+          return (
+            <li key={i}>
+              {last || !c.href ? <span aria-current={last ? 'page' : undefined}>{c.label}</span> : <Link href={c.href} className="ds-link">{c.label}</Link>}
+              {!last && <ChevronRight size={14} aria-hidden className="text-ink-faint" />}
+            </li>
+          )
+        })}
+      </ol>
+    </nav>
+  )
+}
+
+/** Multi-step flow progress. On phones only the current step shows its label. `current` is zero-based. */
+export function StepIndicator({ steps, current, lang }: { steps: string[]; current: number; lang?: Lang }) {
+  return (
+    <ol className="ds-steps" aria-label={t(lang, 'steps')}>
+      {steps.map((label, i) => {
+        const state = i < current ? 'done' : i === current ? 'current' : 'todo'
+        return (
+          <li key={i} className="flex items-center gap-1">
+            {i > 0 && <span className="ds-step-line" aria-hidden />}
+            <span className="ds-step" data-state={state} aria-current={state === 'current' ? 'step' : undefined}>
+              <span className="ds-step-dot">{state === 'done' ? <Check size={12} strokeWidth={3} aria-hidden /> : i + 1}</span>
+              <span className="ds-step-label">{label}</span>
+            </span>
+          </li>
+        )
+      })}
+    </ol>
+  )
+}
+
+/** 中 / EN switch. Controlled; the app owns persistence (cookie, route, or state). */
+export function LangToggle({ value, onChange, lang }: { value: Lang; onChange: (v: Lang) => void; lang?: Lang }) {
+  return (
+    <div className="ds-tabs" role="group" aria-label={t(lang ?? value, 'language')}>
+      {(['zh', 'en'] as const).map(l => (
+        <button key={l} type="button" className="ds-tab" aria-pressed={value === l} lang={l} onClick={() => onChange(l)}>{l === 'zh' ? '中' : 'EN'}</button>
+      ))}
+    </div>
+  )
+}

package/src/components/Popover.tsx

@@ -0,0 +1,99 @@
+'use client'
+import { cloneElement, useCallback, useEffect, useId, useRef, useState } from 'react'
+import type { KeyboardEvent, ReactElement, ReactNode } from 'react'
+import { Check } from 'lucide-react'
+import { cn } from '../cn'
+import { useDismiss } from '../hooks'
+import { useLink } from '../link'
+
+type Align = 'start' | 'end'
+
+/** Anchored panel for small forms or extra detail. Not for menus (use Menu) or hints (use Tooltip). `trigger` must be one button element. */
+export function Popover({ trigger, children, align = 'start', label }: {
+  trigger: ReactElement<Record<string, unknown>>; children: ReactNode; align?: Align; label: string
+}) {
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+  const id = useId()
+  const close = useCallback(() => setOpen(false), [])
+  useDismiss(open, ref, close)
+  return (
+    <div className="ds-popover-wrap" ref={ref}>
+      {cloneElement(trigger, { 'aria-haspopup': 'dialog', 'aria-expanded': open, 'aria-controls': open ? id : undefined, onClick: () => setOpen(o => !o) })}
+      {open && <div id={id} role="dialog" aria-label={label} className={cn('ds-popover ds-popover-body', align === 'end' ? 'ds-popover-end' : 'ds-popover-start')}>{children}</div>}
+    </div>
+  )
+}
+
+export type MenuEntry =
+  | { type?: 'item'; label: string; onSelect?: () => void; href?: string; icon?: ReactNode; danger?: boolean; disabled?: boolean; checked?: boolean; hint?: string }
+  | { type: 'separator' }
+  | { type: 'label'; label: string }
+
+/** Dropdown menu. Arrow keys / Home / End move, Esc closes and returns focus to the trigger, Enter or Space selects.
+ *  `trigger` must be one button element. Items with `href` render as links. Opens below; align="end" for right-edge triggers. */
+export function Menu({ trigger, items, align = 'start', label }: {
+  trigger: ReactElement<Record<string, unknown>>; items: MenuEntry[]; align?: Align; label: string
+}) {
+  const Link = useLink()
+  const [open, setOpen] = useState(false)
+  const wrap = useRef<HTMLDivElement>(null)
+  const list = useRef<HTMLDivElement>(null)
+  const id = useId()
+  const close = useCallback((refocus = false) => {
+    setOpen(false)
+    if (refocus) wrap.current?.querySelector<HTMLElement>('[aria-haspopup]')?.focus()
+  }, [])
+  useDismiss(open, wrap, () => setOpen(false))
+
+  const enabled = () => Array.from(list.current?.querySelectorAll<HTMLElement>('[role^="menuitem"]:not([aria-disabled="true"])') ?? [])
+  const focusAt = (i: number) => { const e = enabled(); if (e.length) e[(i + e.length) % e.length].focus() }
+  // Focus moves in an effect right after the menu commits (not rAF), so it is deterministic.
+  const pendingFocus = useRef<'first' | 'last' | null>(null)
+  useEffect(() => {
+    if (open && pendingFocus.current) { focusAt(pendingFocus.current === 'last' ? -1 : 0); pendingFocus.current = null }
+  }, [open])
+  const openAndFocus = (last = false) => {
+    pendingFocus.current = last ? 'last' : 'first'
+    if (open) { focusAt(last ? -1 : 0); pendingFocus.current = null } else setOpen(true)
+  }
+
+  const onTriggerKey = (e: KeyboardEvent) => {
+    if (e.key === 'ArrowDown') { e.preventDefault(); openAndFocus() }
+    if (e.key === 'ArrowUp') { e.preventDefault(); openAndFocus(true) }
+  }
+  const onListKey = (e: KeyboardEvent) => {
+    const e2 = enabled(); const i = e2.indexOf(document.activeElement as HTMLElement)
+    if (e.key === 'ArrowDown') { e.preventDefault(); focusAt(i + 1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); focusAt(i - 1) }
+    else if (e.key === 'Home') { e.preventDefault(); focusAt(0) }
+    else if (e.key === 'End') { e.preventDefault(); focusAt(-1) }
+    else if (e.key === 'Escape') { e.preventDefault(); close(true) }
+    else if (e.key === 'Tab') close()
+  }
+
+  return (
+    <div className="ds-popover-wrap" ref={wrap}>
+      {cloneElement(trigger, { 'aria-haspopup': 'menu', 'aria-expanded': open, 'aria-controls': open ? id : undefined, onClick: () => (open ? close() : openAndFocus()), onKeyDown: onTriggerKey })}
+      {open && (
+        <div id={id} ref={list} role="menu" aria-label={label} onKeyDown={onListKey}
+          className={cn('ds-popover', align === 'end' ? 'ds-popover-end' : 'ds-popover-start')}>
+          {items.map((it, i) => {
+            if (it.type === 'separator') return <div key={i} role="separator" className="ds-menu-sep" />
+            if (it.type === 'label') return <div key={i} className="ds-menu-label" aria-hidden>{it.label}</div>
+            const cls = cn('ds-menu-item', it.danger && 'ds-menu-item-danger')
+            const inner = <>
+              {it.icon}<span>{it.label}</span>
+              {it.checked ? <Check size={16} className="ml-auto" aria-hidden /> : it.hint ? <span className="ds-menu-hint">{it.hint}</span> : null}
+            </>
+            const role = it.checked !== undefined ? 'menuitemradio' : 'menuitem'
+            return it.href
+              ? <Link key={i} role={role} aria-checked={it.checked} aria-disabled={it.disabled || undefined} href={it.href} className={cls} tabIndex={-1} onClick={() => close()}>{inner}</Link>
+              : <button key={i} type="button" role={role} aria-checked={it.checked} aria-disabled={it.disabled || undefined} className={cls} tabIndex={-1}
+                  onClick={() => { if (it.disabled) return; it.onSelect?.(); close(true) }}>{inner}</button>
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/Sheet.tsx

@@ -0,0 +1,32 @@
+'use client'
+import { useRef } from 'react'
+import type { ReactNode } from 'react'
+import { X } from 'lucide-react'
+import { t } from '../copy'
+import type { Lang } from '../copy'
+import { useFocusTrap, useScrollLock } from '../hooks'
+
+/** Bottom sheet (phone: pickers, secondary panels) or left drawer (mobile nav). Stays mounted so it can slide; closed = inert.
+ *  Children render only after the first open, so heavy content doesn't load until needed. */
+export function Sheet({ open, onClose, title, side = 'bottom', children, lang }: {
+  open: boolean; onClose: () => void; title: string; side?: 'bottom' | 'left'; children: ReactNode; lang?: Lang
+}) {
+  const ref = useRef<HTMLDivElement>(null)
+  const opened = useRef(open)
+  if (open) opened.current = true
+  useFocusTrap(open, ref, onClose)
+  useScrollLock(open)
+  return (
+    <div className="ds-sheet-root" data-open={open} inert={!open} aria-hidden={!open}>
+      <div className="ds-sheet-scrim" onClick={onClose} />
+      <div ref={ref} className={`ds-sheet ds-sheet-${side}`} role="dialog" aria-modal="true" aria-label={title}>
+        {side === 'bottom' && <div className="ds-sheet-grab" aria-hidden />}
+        <div className="ds-sheet-head">
+          <h2 className="font-display text-base text-ink">{title}</h2>
+          <button type="button" className="ds-btn ds-btn-ghost ds-btn-icon" onClick={onClose} aria-label={t(lang, 'close')}><X size={18} /></button>
+        </div>
+        <div className="ds-sheet-body">{opened.current ? children : null}</div>
+      </div>
+    </div>
+  )
+}

package/src/components/SiteHeader.tsx

@@ -0,0 +1,33 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useLink } from '../link'
+
+/** Brand header: graphic logo, a hairline divider, then the app title, optional desktop nav, actions right. Copy `assets/logo/daoshang-horizontal-mark-dark.png`
+ *  into the app's public/logo/ and pass '/logo/daoshang-horizontal-mark-dark.png'. The dark-slate mark flips to light via .brand-logo.
+ *  Phones: pass `menuButton` (see MenuButton + NavDrawer) and hide `nav` below `md` (NavLinks className="hidden md:flex"). */
+export function SiteHeader({ logoSrc, logoAlt = '大道大商', title, nav, actions, menuButton, href = '/', containerClassName = 'ds-container', homeLabel }: {
+  logoSrc: string; logoAlt?: string; title?: string; nav?: ReactNode; actions?: ReactNode; menuButton?: ReactNode; href?: string
+  /** Width/gutter of the header content. Default `ds-container` (72rem). Narrow apps pass e.g. 'mx-auto max-w-2xl px-5' to line up with their page column. */
+  containerClassName?: string
+  /** aria-label for the logo link when there is no title (e.g. "接龙 首页"). */
+  homeLabel?: string
+}) {
+  const Link = useLink()
+  return (
+    <header className="ds-header">
+      <a href="#main" className="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-50 ds-btn ds-btn-primary">Skip to content</a>
+      <div className={`${containerClassName} flex items-center justify-between gap-x-4 gap-y-2 py-4`}>
+        <div className="flex min-w-0 items-center gap-3">
+          {menuButton && <div className="md:hidden">{menuButton}</div>}
+          <Link href={href} aria-label={homeLabel} className="flex min-w-0 items-center gap-4">
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img src={logoSrc} alt={logoAlt} className="brand-logo h-6 w-auto shrink-0" />
+            {title && <><span className="ds-brand-divider" aria-hidden /><span className="font-display truncate text-lg text-ink">{title}</span></>}
+          </Link>
+        </div>
+        {nav && <div className="hidden md:block">{nav}</div>}
+        {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+      </div>
+    </header>
+  )
+}

package/src/components/Stamp.tsx

@@ -0,0 +1,12 @@
+import { Check } from 'lucide-react'
+import { cn } from '../cn'
+
+/** The brand's seal: an orange stamp that lands once on a meaningful success (published, saved, signed up).
+ *  Mount it when the success happens; remount (change `key`) to replay. Use at most one per view. */
+export function Stamp({ large, label = '完成', className }: { large?: boolean; label?: string; className?: string }) {
+  return (
+    <span className={cn('ds-stamp', large && 'ds-stamp-lg', className)} role="img" aria-label={label}>
+      <Check size={large ? 40 : 28} strokeWidth={2.5} aria-hidden />
+    </span>
+  )
+}

package/src/components/Surface.tsx

@@ -0,0 +1,35 @@
+import type { HTMLAttributes } from 'react'
+import { cn } from '../cn'
+
+export function Card({ interactive, className, ...rest }: HTMLAttributes<HTMLDivElement> & { interactive?: boolean }) {
+  return <div className={cn('ds-card', interactive && 'ds-card-interactive', className)} {...rest} />
+}
+
+export type BadgeTone = 'accent' | 'ink' | 'tint' | 'outline' | 'danger'
+export function Badge({ tone = 'tint', small, className, ...rest }:
+  HTMLAttributes<HTMLSpanElement> & { tone?: BadgeTone; small?: boolean }) {
+  return <span className={cn('ds-badge', `ds-badge-${tone}`, small && 'ds-badge-sm', className)} {...rest} />
+}
+
+export function EmptyState({ title, hint, action }: { title: string; hint?: string; action?: React.ReactNode }) {
+  return (
+    <div className="ds-empty">
+      <p className="font-display text-lg text-ink">{title}</p>
+      {hint && <p className="ds-hint mt-2">{hint}</p>}
+      {action && <div className="mt-5">{action}</div>}
+    </div>
+  )
+}
+
+export function Skeleton({ className }: { className?: string }) {
+  return <div className={cn('ds-skeleton', className)} aria-hidden />
+}
+
+export function Spinner({ label = '加载中' }: { label?: string }) {
+  return <div className="ds-spinner" role="status" aria-label={label} />
+}
+
+export function Alert({ tone, className, ...rest }: HTMLAttributes<HTMLDivElement> & { tone?: 'danger' | 'warn' }) {
+  return <div role={tone === 'danger' ? 'alert' : 'status'}
+    className={cn('ds-alert', tone && `ds-alert-${tone}`, className)} {...rest} />
+}

package/src/components/Tabs.tsx

@@ -0,0 +1,20 @@
+import { cn } from '../cn'
+
+export function Tabs<T extends string>({ items, value, onChange, label, className }: {
+  items: ReadonlyArray<{ value: T; label: string }>
+  value: T
+  onChange: (v: T) => void
+  label: string
+  className?: string
+}) {
+  return (
+    <div className={cn('ds-tabs', className)} role="tablist" aria-label={label}>
+      {items.map(it => (
+        <button key={it.value} type="button" role="tab" className="ds-tab"
+          aria-selected={it.value === value} onClick={() => onChange(it.value)}>
+          {it.label}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/components/Toast.tsx

@@ -0,0 +1,16 @@
+'use client'
+import { useEffect } from 'react'
+import { cn } from '../cn'
+
+/** Controlled toast: render when `message` is set; it calls onDone after `ms`. */
+export function Toast({ message, tone, onDone, ms = 3000 }: {
+  message: string | null; tone?: 'error'; onDone: () => void; ms?: number
+}) {
+  useEffect(() => {
+    if (!message) return
+    const t = setTimeout(onDone, ms)
+    return () => clearTimeout(t)
+  }, [message, ms, onDone])
+  if (!message) return null
+  return <div role={tone === 'error' ? 'alert' : 'status'} className={cn('ds-toast', tone === 'error' && 'ds-toast-error')}>{message}</div>
+}

package/src/components/Tooltip.tsx

@@ -0,0 +1,15 @@
+import { cloneElement, useId } from 'react'
+import type { ReactElement } from 'react'
+import { cn } from '../cn'
+
+/** Short, non-essential hint (a name for an icon button, a keyboard shortcut). Shows on hover and keyboard focus after 350ms; hidden on touch.
+ *  Never put required information here. Child must be one focusable element. */
+export function Tooltip({ label, children, placement = 'top' }: { label: string; children: ReactElement<Record<string, unknown>>; placement?: 'top' | 'bottom' }) {
+  const id = useId()
+  return (
+    <span className={cn('ds-tip-wrap', placement === 'bottom' && 'ds-tip-bottom')}>
+      {cloneElement(children, { 'aria-describedby': id })}
+      <span id={id} role="tooltip" className="ds-tip">{label}</span>
+    </span>
+  )
+}

package/src/copy.ts

@@ -0,0 +1,20 @@
+/** Standard UI strings. Chinese is primary; components default to 'zh' and accept `lang`. See "Content & voice" in DESIGN_SYSTEM.md. */
+export type Lang = 'zh' | 'en'
+
+export const labels = {
+  zh: {
+    cancel: '取消', confirm: '确认', save: '保存', delete: '删除', close: '关闭', retry: '重试', back: '返回', next: '下一步',
+    done: '完成', loading: '加载中', search: '搜索', menu: '菜单', openMenu: '打开菜单', mainNav: '主导航', breadcrumb: '当前位置',
+    steps: '步骤', language: '语言', signIn: '登录', signOut: '退出登录', settings: '设置', help: '帮助', workspace: '工作区',
+    switchWorkspace: '切换工作区', account: '账户', viewer: '仅查看', copyright: '版权所有',
+  },
+  en: {
+    cancel: 'Cancel', confirm: 'Confirm', save: 'Save', delete: 'Delete', close: 'Close', retry: 'Try again', back: 'Back', next: 'Next',
+    done: 'Done', loading: 'Loading', search: 'Search', menu: 'Menu', openMenu: 'Open menu', mainNav: 'Main navigation', breadcrumb: 'Breadcrumb',
+    steps: 'Steps', language: 'Language', signIn: 'Sign in', signOut: 'Sign out', settings: 'Settings', help: 'Help', workspace: 'Workspace',
+    switchWorkspace: 'Switch workspace', account: 'Account', viewer: 'View only', copyright: 'All rights reserved',
+  },
+} as const
+
+export type LabelKey = keyof typeof labels.zh
+export const t = (lang: Lang | undefined, key: LabelKey) => labels[lang ?? 'zh'][key]

package/src/hooks.ts

@@ -0,0 +1,50 @@
+'use client'
+import { useEffect } from 'react'
+import type { RefObject } from 'react'
+
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])'
+
+/** While `open`: moves focus into `ref`, loops Tab inside it, calls onEscape on Esc, and restores focus on close. */
+export function useFocusTrap(open: boolean, ref: RefObject<HTMLElement | null>, onEscape: () => void) {
+  useEffect(() => {
+    if (!open) return
+    const prev = document.activeElement as HTMLElement | null
+    const el = ref.current
+    const items = () => (el ? Array.from(el.querySelectorAll<HTMLElement>(FOCUSABLE)) : [])
+    ;(items()[0] ?? el)?.focus()
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') { e.stopPropagation(); onEscape(); return }
+      if (e.key !== 'Tab') return
+      const list = items()
+      if (!list.length) { e.preventDefault(); return }
+      const first = list[0], last = list[list.length - 1]
+      if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus() }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus() }
+    }
+    document.addEventListener('keydown', onKey)
+    return () => { document.removeEventListener('keydown', onKey); prev?.focus?.() }
+  }, [open, ref, onEscape])
+}
+
+/** Closes on outside pointer-down or Esc while `open`. */
+export function useDismiss(open: boolean, ref: RefObject<HTMLElement | null>, onDismiss: () => void) {
+  useEffect(() => {
+    if (!open) return
+    const down = (e: MouseEvent | TouchEvent) => { if (ref.current && !ref.current.contains(e.target as Node)) onDismiss() }
+    const key = (e: KeyboardEvent) => { if (e.key === 'Escape') onDismiss() }
+    document.addEventListener('mousedown', down)
+    document.addEventListener('touchstart', down)
+    document.addEventListener('keydown', key)
+    return () => { document.removeEventListener('mousedown', down); document.removeEventListener('touchstart', down); document.removeEventListener('keydown', key) }
+  }, [open, ref, onDismiss])
+}
+
+/** Locks page scroll while `locked`. */
+export function useScrollLock(locked: boolean) {
+  useEffect(() => {
+    if (!locked) return
+    const prev = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => { document.body.style.overflow = prev }
+  }, [locked])
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './cn'
+export * from './components/Button'
+export * from './components/Field'
+export * from './components/Surface'
+export * from './components/Tabs'
+export * from './components/Modal'
+export * from './components/Toast'
+export * from './components/SiteHeader'
+export * from './components/Popover'
+export * from './components/Tooltip'
+export * from './components/ConfirmDialog'
+export * from './components/Sheet'
+export * from './components/Nav'
+export * from './components/Account'
+export * from './components/Layout'
+export * from './copy'
+export * from './hooks'
+export * from './components/Stamp'
+export * from './link'

package/src/link.tsx

@@ -0,0 +1,12 @@
+'use client'
+import { createContext, useContext } from 'react'
+import type { ElementType } from 'react'
+
+const LinkContext = createContext<ElementType>('a')
+
+/** Tell the design-system components which link component to render, once, near the root:
+ *  `<LinkProvider value={Link}>` with `import Link from 'next/link'`. Default is a plain `<a>` (full page loads). */
+export const LinkProvider = LinkContext.Provider
+
+/** The link component for the current app. Use for any internal navigation inside design-system components. */
+export const useLink = () => useContext(LinkContext)