@ploykit/ui 0.5.0 → 0.6.2

package/src/components/OnboardingChecklist.tsx

@@ -0,0 +1,114 @@
+
+import { useEffect, useState, type ReactNode } from 'react'
+import { X } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { Progress, ProgressLabel, ProgressValue } from './ui/progress'
+import { Button } from './ui/button'
+import { useAuth } from '@ploykit/hooks'
+
+export interface OnboardingItem {
+  key: string
+  label: string
+  done: boolean
+  onClick?: () => void
+}
+
+export interface OnboardingChecklistProps {
+  
+  items?: OnboardingItem[]
+  
+  storageKey?: string
+  title?: string
+}
+
+const DISMISS_KEY = 'pk_onboarding_dismissed'
+
+function defaultItems(hasWorkspaces: boolean): OnboardingItem[] {
+  return [
+    { key: 'create-workspace', label: '创建第一个工作区', done: hasWorkspaces },
+  ]
+}
+
+export function OnboardingChecklist({
+  items, storageKey = DISMISS_KEY, title = '开始使用',
+}: OnboardingChecklistProps = {}) {
+  const { user, workspaces } = useAuth()
+  
+  
+  const [dismissed, setDismissed] = useState(false)
+  useEffect(() => {
+    try {
+      setDismissed(localStorage.getItem(storageKey) === '1')
+    } catch {
+      /* localStorage 不可用（隐私模式等）按未关闭处理——effect 期兜底，非渲染期吞异常 */
+    }
+  }, [storageKey])
+
+  
+  const list = items ?? (user ? defaultItems(workspaces.length > 0) : [])
+  if (!user || dismissed || list.length === 0) return null
+
+  const doneCount = list.filter((i) => i.done).length
+  const pct = Math.round((doneCount / list.length) * 100)
+  const allDone = doneCount === list.length
+
+  const dismiss = () => {
+    try {
+      localStorage.setItem(storageKey, '1')
+    } catch {
+      /* 隐私模式等场景忽略持久化失败 */
+    }
+    setDismissed(true)
+  }
+
+  return (
+    <section className="w-full rounded-xl border bg-card p-4 shadow-xs">
+      <div className="flex items-start justify-between gap-2">
+        <div>
+          <h3 className="text-sm font-semibold">{title}</h3>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            {allDone ? '全部完成，开始你的旅程吧！' : `已完成 ${doneCount}/${list.length} 项`}
+          </p>
+        </div>
+        <Button variant="ghost" size="icon-sm" aria-label="关闭引导清单" onClick={dismiss}>
+          <X />
+        </Button>
+      </div>
+
+      <Progress value={pct} className="mt-3">
+        <ProgressLabel>{allDone ? '完成' : '进度'}</ProgressLabel>
+        <ProgressValue />
+      </Progress>
+
+      <ul className="mt-4 space-y-2">
+        {list.map((item) => (
+          <li key={item.key}>
+            <button
+              type="button"
+              onClick={item.done ? undefined : item.onClick}
+              disabled={item.done}
+              className={cn(
+                'flex w-full items-center gap-3 rounded-lg border px-3 py-2 text-left text-sm transition-colors',
+                item.done
+                  ? 'border-transparent bg-muted/50 text-muted-foreground'
+                  : 'border-border hover:bg-accent hover:text-accent-foreground',
+                !item.done && !item.onClick && 'cursor-default',
+              )}
+            >
+              <span
+                aria-hidden="true"
+                className={cn(
+                  'flex size-5 shrink-0 items-center justify-center rounded-full border text-xs',
+                  item.done ? 'border-primary bg-primary text-primary-foreground' : 'border-input',
+                )}
+              >
+                {item.done ? '✓' : ''}
+              </span>
+              <span className={cn(item.done && 'line-through')}>{item.label}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}

package/src/components/Page.tsx

@@ -0,0 +1,67 @@
+
+import { type ReactNode } from 'react'
+import { Inbox, TriangleAlert } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { Button } from './ui/button'
+import {
+  Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent,
+} from './ui/empty'
+
+
+
+export function PageHeader({ title, description, actions }: {
+  title: string; description?: string; actions?: ReactNode
+}) {
+  return (
+    <div className="mb-6 flex flex-wrap items-start justify-between gap-4">
+      <div className="min-w-0">
+        <h1 className="text-2xl font-bold text-foreground">{title}</h1>
+        {description && <p className="mt-1 max-w-2xl text-sm text-muted-foreground">{description}</p>}
+      </div>
+      {actions && <div className="flex shrink-0 gap-2">{actions}</div>}
+    </div>
+  )
+}
+
+export function PageLoading({ label = '加载中…' }: { label?: string }) {
+  
+  
+  return (
+    <div className="flex items-center justify-center py-12" role="status" aria-live="polite">
+      <div className="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground/20 border-t-primary" />
+      <span className="ml-3 text-sm text-muted-foreground">{label}</span>
+    </div>
+  )
+}
+
+export function PageEmpty({ label = '暂无数据', hint }: { label?: string; hint?: string }) {
+  return (
+    <Empty className="py-8">
+      <EmptyHeader>
+        <EmptyMedia variant="icon">
+          <Inbox aria-hidden="true" />
+        </EmptyMedia>
+        <EmptyTitle>{label}</EmptyTitle>
+        {hint && <EmptyDescription>{hint}</EmptyDescription>}
+      </EmptyHeader>
+    </Empty>
+  )
+}
+
+export function PageError({ message, onRetry }: { message: string; onRetry?: () => void }) {
+  return (
+    <Empty className="py-8" role="alert">
+      <EmptyHeader>
+        <EmptyMedia variant="icon" className="bg-destructive/10 text-destructive">
+          <TriangleAlert aria-hidden="true" />
+        </EmptyMedia>
+        <EmptyTitle className="text-destructive">{message}</EmptyTitle>
+        {onRetry && (
+          <EmptyContent>
+            <Button variant="outline" onClick={onRetry}>重试</Button>
+          </EmptyContent>
+        )}
+      </EmptyHeader>
+    </Empty>
+  )
+}

package/src/components/ReauthDialog.tsx

@@ -0,0 +1,94 @@
+import { useState } from 'react'
+import { ShieldCheck } from 'lucide-react'
+import { useApi } from '@ploykit/hooks'
+import { isApiError } from '@ploykit/client'
+import {
+  Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter,
+} from './ui/dialog'
+import { Button } from './ui/button'
+import { Input } from './ui/input'
+import { toast } from './toast'
+
+/**
+ * Step-up（sudo mode）两段式协议的第二段（ADR 0011）：敏感操作被
+ * 403 E_REAUTH_REQUIRED 拒绝后，弹本对话框验证密码（POST
+ * /auth/confirm-password），成功后自动重试原请求。
+ *
+ * 用法：页面捕获 isApiError(err, 'E_REAUTH_REQUIRED') 时，把"重试动作"
+ * （通常是 mutation.mutateAsync 绑定原参数）交给 retry，打开对话框即可。
+ */
+export interface ReauthDialogProps {
+  open: boolean
+  /** 被挑战的原动作；确认成功后重新执行一次。为 null 时对话框只确认不重试。 */
+  retry: (() => Promise<unknown>) | null
+  onClose: () => void
+}
+
+export function ReauthDialog({ open, retry, onClose }: ReauthDialogProps) {
+  const api = useApi()
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  const confirm = async () => {
+    if (!password || busy) return
+    setBusy(true)
+    setError('')
+    try {
+      await api.post('/auth/confirm-password', { password })
+      if (retry) await retry()
+      toast.success('已验证，操作已重试')
+      setPassword('')
+      onClose()
+    } catch (err) {
+      if (isApiError(err, 'E_UNAUTHENTICATED')) {
+        setError('密码不正确，请重试')
+        return
+      }
+      toast.error('操作失败，请稍后重试')
+      onClose()
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={(o) => { if (!o && !busy) onClose() }}>
+      <DialogContent className="max-w-sm">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <ShieldCheck className="size-4" />
+            需要验证密码
+          </DialogTitle>
+          <DialogDescription>
+            这是敏感操作，需要确认密码后自动重试。密码确认在一段时间内有效。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          className="space-y-1"
+          onSubmit={(e) => { e.preventDefault(); void confirm() }}
+        >
+          <Input
+            type="password"
+            autoFocus
+            autoComplete="current-password"
+            aria-label="当前密码"
+            placeholder="当前密码"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            disabled={busy}
+          />
+          {error && <p className="text-sm text-destructive">{error}</p>}
+          <DialogFooter className="mt-4">
+            <Button type="button" variant="outline" onClick={onClose} disabled={busy}>
+              取消
+            </Button>
+            <Button type="submit" disabled={!password || busy}>
+              {busy ? '验证中…' : '验证并继续'}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/components/SecretModal.tsx

@@ -0,0 +1,147 @@
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import {
+  Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter,
+} from './ui/dialog'
+import { Button } from './ui/button'
+
+export function SecretModal({ open, onOpenChange, secretName, secretValue, title }: {
+  open: boolean
+  /** 关闭回调。契约：用户勾选"我已保存"之前，本组件不会把 false 传进来——ESC、遮罩点击、关闭按钮均被拦截，调用方无需自行兜底。 */
+  onOpenChange: (open: boolean) => void
+  /** 密钥名称，用于默认标题「{secretName} 创建成功」。 */
+  secretName: string
+  /** 仅显示一次的密钥明文。 */
+  secretValue: string
+  /** 可选标题，覆盖默认的「{secretName} 创建成功」——用于"重置/查看"等非创建成功场景。 */
+  title?: string
+}) {
+  const [copied, setCopied] = useState(false)
+  const [copyFailed, setCopyFailed] = useState(false)
+  const [confirmed, setConfirmed] = useState(false)
+  const copyTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  
+  
+  useEffect(() => {
+    setCopied(false)
+    setCopyFailed(false)
+    setConfirmed(false)
+    if (copyTimer.current) {
+      clearTimeout(copyTimer.current)
+      copyTimer.current = null
+    }
+  }, [open, secretValue])
+
+  
+  useEffect(() => () => {
+    if (copyTimer.current) clearTimeout(copyTimer.current)
+  }, [])
+
+  const copy = async () => {
+    
+    
+    try {
+      await navigator.clipboard.writeText(secretValue)
+      setCopied(true)
+      setCopyFailed(false)
+    } catch {
+      setCopied(false)
+      setCopyFailed(true)
+    }
+    if (copyTimer.current) clearTimeout(copyTimer.current)
+    copyTimer.current = setTimeout(() => {
+      setCopied(false)
+      setCopyFailed(false)
+    }, 2000)
+  }
+
+  return (
+    // 契约（见 props JSDoc）：确认勾选前 onOpenChange 不会收到 false——
+    // ESC/遮罩/关闭按钮在此被统一拦截，防止密钥未保存即被关掉。
+    <Dialog open={open} onOpenChange={(o) => confirmed && onOpenChange(o)}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{title ?? `${secretName} 创建成功`}</DialogTitle>
+          <DialogDescription>
+            此密钥只显示一次，关闭后无法再次查看。请立即保存到安全的地方。
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex items-center gap-2">
+          <code className="flex-1 px-3 py-2 bg-foreground/5 rounded font-mono text-sm break-all">
+            {secretValue}
+          </code>
+          <Button variant="outline" size="sm" onClick={copy}>
+            {copied ? '已复制' : copyFailed ? '复制失败，请手动复制' : '复制'}
+          </Button>
+        </div>
+        <label className="flex items-center gap-2 text-sm text-muted-foreground">
+          <input
+            type="checkbox"
+            checked={confirmed}
+            onChange={(e) => setConfirmed(e.target.checked)}
+            className="rounded border-input"
+          />
+          我已将密钥保存到安全的地方
+        </label>
+        <DialogFooter>
+          <Button onClick={() => onOpenChange(false)} disabled={!confirmed}>
+            {confirmed ? '我已保存' : '请先确认已保存'}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+export function ImpactConfirmation({ open, onConfirm, onOpenChange, title, impacts, confirmText, danger }: {
+  open: boolean
+  /** 点击确认按钮后回调；回调返回后组件会立即请求关闭。 */
+  onConfirm: () => void
+  onOpenChange: (open: boolean) => void
+  title: string
+  /** 影响项列表。支持任意 ReactNode（可含链接/加粗等富文本）；key 按下标生成，注意项内容需自行保证可读。 */
+  impacts: ReactNode[]
+  confirmText?: string
+  danger?: boolean
+}) {
+  const [checked, setChecked] = useState(false)
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>此操作将产生以下影响：</DialogDescription>
+        </DialogHeader>
+        {/* max-h + overflow：影响项过多时列表内部滚动，弹窗整体不被撑出视口 */}
+        <ul className="max-h-48 space-y-1.5 overflow-y-auto">
+          {impacts.map((impact, index) => (
+            <li key={index} className="flex items-start gap-2 text-sm text-foreground">
+              <span className="text-destructive mt-0.5">•</span> {impact}
+            </li>
+          ))}
+        </ul>
+        <label className="flex items-center gap-2 text-sm text-muted-foreground pt-2 border-t">
+          <input
+            type="checkbox"
+            checked={checked}
+            onChange={(e) => setChecked(e.target.checked)}
+            className="rounded border-input"
+          />
+          我理解并接受以上影响
+        </label>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>取消</Button>
+          <Button
+            variant={danger ? 'destructive' : 'default'}
+            disabled={!checked}
+            onClick={() => { onConfirm(); onOpenChange(false) }}
+          >
+            {confirmText ?? '确认执行'}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/components/SettingsCard.tsx

@@ -0,0 +1,39 @@
+
+import type { ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import {
+  Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent,
+} from './ui/card'
+
+export interface SettingsCardProps {
+  title: ReactNode
+  description?: ReactNode
+  
+  cta?: ReactNode
+  
+  danger?: boolean
+  
+  bodyClassName?: string
+  children: ReactNode
+}
+
+export function SettingsCard({
+  title, description, cta, danger, bodyClassName, children,
+}: SettingsCardProps) {
+  return (
+    <Card className="my-4 w-full max-w-4xl text-left" size="sm">
+      <CardHeader>
+        {/* G7.1：分块卡标题升 h2（PageHeader h1 之下的文档大纲层级），
+            经 card.tsx CardTitle 的 as 多态，样式/props 不变。 */}
+        <h2 data-slot="card-title" className={cn('flex items-center gap-2 font-semibold leading-none tracking-tight', danger && 'text-destructive')}>{title}</h2>
+        {description && (
+          <CardDescription className={cn(danger && 'text-destructive/80')}>
+            {description}
+          </CardDescription>
+        )}
+        {cta && <CardAction>{cta}</CardAction>}
+      </CardHeader>
+      <CardContent className={cn('text-left', bodyClassName)}>{children}</CardContent>
+    </Card>
+  )
+}

package/src/components/SiteBanner.tsx

@@ -0,0 +1,32 @@
+
+import { TriangleAlert } from 'lucide-react'
+import { cn } from '../lib/utils'
+
+export interface SiteBannerProps {
+  
+  text?: string
+  
+  kind?: 'info' | 'warn'
+  className?: string
+}
+
+export function SiteBanner({ text, kind = 'info', className }: SiteBannerProps) {
+  if (!text || !text.trim()) return null
+  const warn = kind === 'warn'
+  return (
+    <div
+      role="status"
+      data-slot="site-banner"
+      className={cn(
+        'flex w-full items-center justify-center gap-2 border-b px-4 py-2 text-sm',
+        warn
+          ? 'border-destructive/30 bg-destructive/10 text-destructive'
+          : 'border-primary/25 bg-primary/10 text-primary',
+        className,
+      )}
+    >
+      {warn && <TriangleAlert className="size-4 shrink-0" aria-hidden="true" />}
+      <span className="min-w-0 whitespace-pre-wrap text-balance">{text}</span>
+    </div>
+  )
+}

package/src/components/SiteBannerLayer.tsx

@@ -0,0 +1,29 @@
+
+import { SiteBanner } from './SiteBanner';
+import { useSiteConfig } from '@ploykit/hooks';
+
+export interface SiteBannerLayerProps {
+  
+  maintenanceText?: string;
+}
+
+export function SiteBannerLayer({
+  maintenanceText,
+}: SiteBannerLayerProps = {}) {
+  const { data } = useSiteConfig();
+  if (!data) return null;
+  return (
+    <>
+      {data.maintenance_mode === '1' && (
+        <SiteBanner
+          text={maintenanceText ?? '维护中：系统维护中，功能可能出现短暂不可用'}
+          kind="warn"
+        />
+      )}
+      <SiteBanner
+        text={data.banner_text}
+        kind={data.banner_kind === 'warn' ? 'warn' : 'info'}
+      />
+    </>
+  );
+}

package/src/components/StatusBadge.tsx

@@ -0,0 +1,12 @@
+import { cn, statusLabel, statusTone, STATUS_TONE_CLASS } from '../lib/utils'
+
+// 业务语义件（shadcn 无对应物，按"有则用 stock、无则留业务层"规则留守）：
+// 按订阅/订单/投递等业务状态映射色调与文案的徽章，从 stock 镜像 badge.tsx 迁出。
+export function StatusBadge({ status, className }: { status: string; className?: string }) {
+  return (
+    <span className={cn('inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium whitespace-nowrap',
+      STATUS_TONE_CLASS[statusTone(status)], className)}>
+      {statusLabel(status)}
+    </span>
+  )
+}

package/src/components/UserMenu.tsx

@@ -0,0 +1,103 @@
+
+import { useNavigate } from 'react-router'
+import type { ReactNode } from 'react'
+import { LogOut, Settings, ShieldCheck } from 'lucide-react'
+import { Avatar, AvatarFallback, AvatarImage } from './ui/avatar'
+import {
+  DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem,
+  DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger,
+} from './ui/dropdown-menu'
+import { useAuth } from '@ploykit/hooks'
+import { toast } from './toast'
+
+export interface UserMenuExtraItem {
+  label: string
+  onClick?: () => void
+  to?: string
+  icon?: ReactNode
+  destructive?: boolean
+}
+
+export interface UserMenuProps {
+  
+  items?: UserMenuExtraItem[]
+  
+  logoutRedirect?: string
+}
+
+function initialsOf(name: string, email: string): string {
+  const src = name.trim() || email.trim()
+  if (!src) return '?'
+  const parts = src.split(/[\s@._-]+/).filter(Boolean)
+  return parts.slice(0, 2).map((p) => p[0]?.toUpperCase() ?? '').join('') || src.slice(0, 2).toUpperCase()
+}
+
+export function UserMenu({ items = [], logoutRedirect = '/login' }: UserMenuProps) {
+  const { user, logout } = useAuth()
+  const navigate = useNavigate()
+
+  const name = user?.display_name || user?.email || ''
+  const email = user?.email ?? ''
+
+  const handleLogout = async () => {
+    try {
+      await logout()
+    } catch {
+      
+      
+      toast.error('退出登录失败，请稍后在登录页重试')
+    }
+    navigate(logoutRedirect)
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm text-muted-foreground
+                   transition-colors hover:bg-accent hover:text-accent-foreground
+                   aria-expanded:bg-accent"
+        aria-label="用户菜单"
+      >
+        <Avatar size="sm">
+          {user?.avatar_url ? <AvatarImage src={user.avatar_url} alt={name} /> : null}
+          <AvatarFallback>{initialsOf(user?.display_name ?? '', email)}</AvatarFallback>
+        </Avatar>
+        <span className="hidden max-w-40 truncate md:inline">{name || '未登录'}</span>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-56">
+        <DropdownMenuGroup>
+          <DropdownMenuLabel className="p-0 font-normal">
+            <div className="flex flex-col px-2 py-1.5">
+              <span className="truncate text-sm font-medium text-foreground">{name || '未登录'}</span>
+              <span className="truncate text-xs text-muted-foreground">{email}</span>
+            </div>
+          </DropdownMenuLabel>
+        </DropdownMenuGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onClick={() => navigate('/account/profile')}>
+          <Settings /> 账户设置
+        </DropdownMenuItem>
+        {user?.is_platform_admin && (
+          <DropdownMenuItem onClick={() => navigate('/admin')}>
+            <ShieldCheck /> 管理控制台
+          </DropdownMenuItem>
+        )}
+        {items.length > 0 && <DropdownMenuSeparator />}
+        {items.map((item) => (
+          <DropdownMenuItem
+            key={item.label}
+            variant={item.destructive ? 'destructive' : 'default'}
+            onClick={() => (item.to ? navigate(item.to) : item.onClick?.())}
+          >
+            {item.icon}
+            {item.label}
+          </DropdownMenuItem>
+        ))}
+        <DropdownMenuSeparator />
+        <DropdownMenuItem variant="destructive" onClick={handleLogout}>
+          <LogOut /> 退出登录
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}