@qijenchen/design-system 0.1.0-beta.3

package/src/components/Toast/toast.tsx

@@ -0,0 +1,129 @@
+import * as React from 'react'
+import { Toaster as SonnerToaster, toast as sonnerToast } from 'sonner'
+import { Notice, useInverseTheme, type NoticeVariant } from '@/design-system/components/Notice/notice'
+import { Button } from '@/design-system/components/Button/button'
+
+/**
+ * Toast — 非阻斷式浮動通知
+ *
+ * ── Container 三層結構（所有 variant 統一） ──
+ *
+ * 1. Shadow wrapper: rounded-lg + elevation-200（永遠在頁面 theme 解析）
+ * 2. Bg layer: bg-{color}（有色相 variant 在頁面 theme 解析）
+ * 3. Theme layer: data-theme + text-foreground（content token re-resolve）
+ *
+ * neutral/success(inverse): bg + theme 同層（bg-surface-raised 需要跟 data-theme 一起翻轉）
+ * info/error(dark): bg 在 outer,theme 在 inner
+ * warning(light always): bg 在 outer,theme="light" 在 inner
+ */
+
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export type ToastVariant = NoticeVariant
+
+export interface ToastOptions {
+  variant?: ToastVariant
+  title: string
+  description?: string
+  action?: { label: string; onClick: () => void }
+  duration?: number
+}
+
+function ToastInner({
+  id,
+  variant = 'neutral',
+  action,
+  ...rest
+}: ToastOptions & { id: string | number }) {
+  const inverseTheme = useInverseTheme()
+  const isInverse = variant === 'neutral' || variant === 'success'
+  const dismiss = () => sonnerToast.dismiss(id)
+
+  const actionButton = action ? (
+    <Button variant="tertiary" size="xs" onClick={action.onClick}>{action.label}</Button>
+  ) : undefined
+
+  // ── Live region 由 outer Toast wrapper 擁有(WAI-ARIA + spec L59-60 canonical) ──
+  // Notice(inner layout)不再帶 role,避免 nested live region。
+  // - error / warning → role="alert" + aria-live="assertive"(中斷朗讀)
+  // - info / success / neutral → role="status" + aria-live="polite"(空閒朗讀)
+  const isCritical = variant === 'error' || variant === 'warning'
+  const liveRole = isCritical ? 'alert' : 'status'
+  const liveLevel = isCritical ? 'assertive' : 'polite'
+
+  // ── 1. Shadow wrapper（統一,永遠在頁面 theme） ──
+  // ── 2+3. Bg + theme layer ──
+
+  if (isInverse) {
+    // bg-surface-raised 需要跟 data-theme 同層翻轉
+    return (
+      <div role={liveRole} aria-live={liveLevel} className="rounded-lg overflow-hidden" style={{ boxShadow: 'var(--elevation-200)' }}>
+        <div data-theme={inverseTheme} className="bg-surface-raised text-foreground">
+          <Notice variant={variant} iconClassName={variant === 'success' ? 'text-success' : undefined}
+            endContent={actionButton} onDismiss={dismiss} {...rest} />
+        </div>
+      </div>
+    )
+  }
+
+  const bg = variant === 'warning' ? 'bg-warning' : variant === 'error' ? 'bg-error' : 'bg-info'
+  const theme = variant === 'warning' ? 'light' : 'dark'
+
+  return (
+    <div role={liveRole} aria-live={liveLevel} className="rounded-lg overflow-hidden" style={{ boxShadow: 'var(--elevation-200)' }}>
+      <div className={bg}>
+        <div data-theme={theme} className="text-foreground">
+          <Notice variant={variant} endContent={actionButton} onDismiss={dismiss} {...rest} />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export function toast(options: ToastOptions) {
+  const { duration = 4000, ...rest } = options
+  return sonnerToast.custom((id) => <ToastInner id={id} {...rest} />, { duration })
+}
+
+export interface ToasterProps {
+  position?: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'
+}
+
+// shadcn canonical:forwardRef + displayName 統一。Sonner Toaster portal-renders
+// 到 document body,ref 對 Toaster 本身無實際 DOM 節點可接(portal 逃逸),
+// 但保留 forwardRef 簽名以符合 DS 統一 API(consumer 可 typecheck 傳 ref,
+// 與其他 DS 元件一致)。
+const Toaster = React.forwardRef<HTMLDivElement, ToasterProps>(
+  ({ position = 'bottom-right', ...props }, _ref) => {
+    return (
+      <SonnerToaster
+        position={position}
+        toastOptions={{ unstyled: true, className: 'w-[360px]' }}
+        {...props}
+      />
+    )
+  },
+)
+Toaster.displayName = 'Toaster'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const toastMeta = {
+  component: 'Toast',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+    neutral: { when: '非狀態通知;一般 announcement / tip' },
+    info: { when: '資訊性提示(新版本 / 同步完成)' },
+    success: { when: '成功確認(已寄送 / 付款完成)' },
+    warning: { when: '可恢復警告(未儲存 / 連線不穩)' },
+    error: { when: '錯誤(匯入失敗 / 權限不足);action prop 可加重試' },
+  },
+  sizes: {},
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-error', 'bg-info', 'bg-surface-raised', 'bg-warning'],
+    fg: ['text-foreground'],
+    ring: [],
+  },
+} as const
+
+export { Toaster }

package/src/components/Tooltip/tooltip.tsx

@@ -0,0 +1,68 @@
+import * as React from "react"
+import * as TooltipPrimitive from "@radix-ui/react-tooltip"
+
+import { cn } from "@/lib/utils"
+import { OVERLAY_SIDE_OFFSET, OVERLAY_COLLISION_PADDING } from "@/design-system/tokens/elevation/overlay-geometry"
+import { HOVER_DELAY_PLAIN_MS } from "@/design-system/tokens/motion/motion"
+
+// 2026-05-18 ship per user 拍板 #3A:Tooltip Provider 預設 delayDuration 對齊 motion token SSOT。
+// Radix 預設 700ms 過保守(被 Material 150-200 / MUI 100 / Atlassian 300 集體驗證),DS 統一用
+// `--hover-delay-plain` (500ms,JS mirror `HOVER_DELAY_PLAIN_MS`)。Consumer 仍可 per-instance override。
+// 2026-05-21 D5 Phase B codex 抓 comment 200 vs token 500 drift → 註解 500ms 對齊 motion.css:27 SSOT。
+const TooltipProvider = ({ delayDuration = HOVER_DELAY_PLAIN_MS, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>) => (
+  <TooltipPrimitive.Provider delayDuration={delayDuration} {...props} />
+)
+
+const Tooltip = ({ delayDuration = HOVER_DELAY_PLAIN_MS, ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) => (
+  <TooltipPrimitive.Root delayDuration={delayDuration} {...props} />
+)
+
+const TooltipTrigger = TooltipPrimitive.Trigger
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(({ className, sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, style, children, ...props }, ref) => (
+  // collisionPadding default 8px:避免 tooltip 貼 viewport 邊(Radix avoidCollisions 預設 true 但 padding 0 會貼邊)
+  // 對齊 HoverCard canonical 避免 viewport edge clipping
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      collisionPadding={collisionPadding}
+      className={cn(
+        "z-50 overflow-hidden rounded-md px-3 py-2 text-body font-normal text-on-emphasis bg-tooltip max-w-[280px]",
+        "animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 motion-reduce:animate-none motion-reduce:zoom-in-100",
+        "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        "origin-[var(--radix-tooltip-content-transform-origin)]",
+        className
+      )}
+      style={{ boxShadow: 'var(--elevation-200)', ...style }}
+      {...props}
+    >
+      <div data-theme="dark" className="contents">{children}</div>
+    </TooltipPrimitive.Content>
+  </TooltipPrimitive.Portal>
+))
+TooltipContent.displayName = TooltipPrimitive.Content.displayName
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const tooltipMeta = {
+  component: 'Tooltip',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: [],
+    fg: [],
+    ring: [],
+  },
+} as const
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }