@yuku123/z-frontend-common 0.2.9 → 1.1.0

package/src/components/ui/LoadingState.jsx

@@ -0,0 +1,116 @@
+import {Skeleton} from 'antd'
+import {radius} from './tokens'
+
+/**
+ * LoadingState - 统一骨架屏 - 借鉴 ui-ux-pro-max P3: Reserve space (CLS < 0.1).
+ *
+ * 原则:
+ *   - 提前占位避免内容跳动 (CLS)
+ *   - 不用 spinner (除全屏初次加载), 用骨架屏更专业
+ *   - 提供常见布局预设
+ *
+ * @param {Object} props
+ * @param {'cards'|'table'|'list'|'detail'} [props.variant] - 预设布局
+ * @param {number} [props.rows] - 行数
+ * @param {boolean} [props.active] - 是否显示流光效果
+ * @param {Object} [props.style]
+ */
+export default function LoadingState({
+                                         variant = 'cards',
+                                         rows = 4,
+                                         active = true,
+                                         style,
+                                     }) {
+    if (variant === 'cards') {
+        return (
+            <div
+                role="status"
+                aria-busy="true"
+                aria-label="加载中"
+                style={{
+                    display: 'grid',
+                    gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))',
+                    gap: 16,
+                    ...style,
+                }}
+            >
+                {Array.from({length: rows}).map((_, i) => (
+                    <div
+                        key={i}
+                        style={{
+                            background: '#ffffff',
+                            borderRadius: radius.lg,
+                            overflow: 'hidden',
+                            border: '1px solid #f1f5f9',
+                        }}
+                    >
+                        <Skeleton.Image
+                            active={active}
+                            style={{width: '100%', height: 140, borderRadius: 0}}
+                        />
+                        <div style={{padding: 16}}>
+                            <Skeleton active={active} paragraph={{rows: 2}} title={{width: '60%'}}/>
+                        </div>
+                    </div>
+                ))}
+            </div>
+        )
+    }
+
+    if (variant === 'table') {
+        return (
+            <div
+                role="status"
+                aria-busy="true"
+                aria-label="加载中"
+                style={{
+                    background: '#ffffff',
+                    padding: 24,
+                    borderRadius: radius.md,
+                    ...style,
+                }}
+            >
+                <Skeleton active={active} paragraph={{rows}}/>
+            </div>
+        )
+    }
+
+    if (variant === 'list') {
+        return (
+            <div role="status" aria-busy="true" aria-label="加载中" style={style}>
+                {Array.from({length: rows}).map((_, i) => (
+                    <div
+                        key={i}
+                        style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 12,
+                            padding: '12px 0',
+                            borderBottom: i < rows - 1 ? '1px solid #f1f5f9' : 'none',
+                        }}
+                    >
+                        <Skeleton.Avatar active={active} size="default"/>
+                        <Skeleton active={active} paragraph={{rows: 1}} title={{width: 120}} style={{flex: 1}}/>
+                    </div>
+                ))}
+            </div>
+        )
+    }
+
+    // detail: 用于详情页
+    return (
+        <div
+            role="status"
+            aria-busy="true"
+            aria-label="加载中"
+            style={{
+                background: '#ffffff',
+                padding: 32,
+                borderRadius: radius.md,
+                ...style,
+            }}
+        >
+            <Skeleton active={active} title={{width: '40%'}} paragraph={{rows}}/>
+        </div>
+    )
+}

package/src/components/ui/PageHeader.jsx

@@ -0,0 +1,143 @@
+import {Breadcrumb} from 'antd'
+import {useNavigate} from 'react-router-dom'
+
+/**
+ * PageHeader - 通用页面标题（紧凑单行版）.
+ *
+ * 解决 z-opc 后台每个页面都重复写 Title + Description + 返回按钮的问题.
+ *
+ * 原则 (来自 anthropics/frontend-design):
+ *   - Structure is information. 面包屑末级即当前页名, 与操作按钮同行, 信息密度优先.
+ *   - 不用 emoji/装饰元素, 用 typography 表达层级.
+ *
+ * @param {Object} props
+ * @param {string} props.title - 主标题（有 breadcrumb 时以面包屑末级为准, 不再单独渲染）
+ * @param {string} [props.subtitle] - 副标题/描述（同行小灰字, 超长截断, hover 可见全文）
+ * @param {Array<{label: string, href?: string}>} [props.breadcrumb] - 面包屑
+ * @param {ReactNode} [props.extra] - 右上角操作按钮区
+ * @param {ReactNode} [props.back] - 是否显示返回按钮 + onBack 回调
+ * @param {Function} [props.onBack] - 返回回调
+ */
+export default function PageHeader({
+                                       title,
+                                       subtitle,
+                                       breadcrumb,
+                                       extra,
+                                       back,
+                                       onBack,
+                                   }) {
+    const navigate = useNavigate()
+    const handleBack = () => {
+        if (onBack) onBack()
+        else navigate(-1)
+    }
+
+    return (
+        <div style={{
+            marginBottom: 12,
+            paddingBottom: 10,
+            borderBottom: '1px solid #f1f5f9',
+        }}>
+            {/* 单行: 面包屑/标题 + 副标题 | 操作区 */}
+            <div style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                gap: 12,
+                flexWrap: 'wrap',
+            }}>
+                <div style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 10,
+                    minWidth: 0,
+                    flexWrap: 'wrap',
+                }}>
+                    {back && (
+                        <button
+                            onClick={handleBack}
+                            aria-label="返回上一页"
+                            style={{
+                                width: 28, height: 28,
+                                borderRadius: 6,
+                                border: '1px solid #e5e7eb',
+                                background: '#ffffff',
+                                color: '#6b7280',
+                                cursor: 'pointer',
+                                display: 'inline-flex',
+                                alignItems: 'center',
+                                justifyContent: 'center',
+                                fontSize: 13,
+                                transition: 'all 150ms ease',
+                                flexShrink: 0,
+                            }}
+                            onMouseEnter={(e) => {
+                                e.currentTarget.style.background = '#f8fafc'
+                                e.currentTarget.style.color = '#111827'
+                                e.currentTarget.style.borderColor = '#7c3aed'
+                            }}
+                            onMouseLeave={(e) => {
+                                e.currentTarget.style.background = '#ffffff'
+                                e.currentTarget.style.color = '#6b7280'
+                                e.currentTarget.style.borderColor = '#e5e7eb'
+                            }}
+                        >
+                            ←
+                        </button>
+                    )}
+                    {breadcrumb && breadcrumb.length > 0 ? (
+                        <Breadcrumb
+                            items={breadcrumb.map((b, i) => {
+                                const last = i === breadcrumb.length - 1
+                                return {
+                                    title: b.href && !last
+                                        ? <a onClick={(e) => {
+                                            e.preventDefault();
+                                            navigate(b.href)
+                                        }}>{b.label}</a>
+                                        : <span style={last ? {
+                                            fontWeight: 600,
+                                            color: '#111827'
+                                        } : undefined}>{b.label}</span>,
+                                }
+                            })}
+                        />
+                    ) : (
+                        title && (
+                            <span role="heading" aria-level={1} style={{
+                                fontSize: 15,
+                                fontWeight: 600,
+                                color: '#111827',
+                                lineHeight: 1.4,
+                            }}>
+                                {title}
+                            </span>
+                        )
+                    )}
+                    {subtitle && (
+                        <span title={subtitle} style={{
+                            fontSize: 12,
+                            color: '#94a3b8',
+                            lineHeight: 1.4,
+                            whiteSpace: 'nowrap',
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            maxWidth: 360,
+                        }}>
+                            {subtitle}
+                        </span>
+                    )}
+                </div>
+                {extra && (
+                    <div style={{
+                        display: 'flex',
+                        gap: 8,
+                        flexShrink: 0,
+                    }}>
+                        {extra}
+                    </div>
+                )}
+            </div>
+        </div>
+    )
+}

package/src/components/ui/PagedTable.jsx

@@ -0,0 +1,83 @@
+import {useCallback, useEffect, useState} from 'react'
+import {Button, Card, Table} from 'antd'
+import {ReloadOutlined} from '@ant-design/icons'
+import {EmptyState, ErrorState, PageHeader} from './index'
+
+/**
+ * 中间件管理台共用的分页表格（z-opc 内孵化的 Tier A 页面用）。
+ *
+ * load(current, size) 既可以返回 MyBatis-Plus 的 {records,total,...}，也可以返回裸数组。
+ * 后端 z-meta 的分页 count 有缺陷（records 有值但 total 返回 "0"），这里不把 0 当"共 0 条"显示，
+ * 而是显式标出接口给的总数，避免页面上出现"有数据却说没有数据"的假象。
+ */
+export default function PagedTable({title, description, load, columns, rowKey = 'id', extra, expandable}) {
+    const [rows, setRows] = useState([])
+    const [page, setPage] = useState({current: 1, size: 10, total: null})
+    const [loading, setLoading] = useState(false)
+    const [error, setError] = useState(null)
+
+    const fetch = useCallback(async (current = page.current, size = page.size) => {
+        setLoading(true)
+        setError(null)
+        try {
+            const res = await load(current, size)
+            if (Array.isArray(res)) {
+                setRows(res || [])
+                setPage({current, size, total: res.length})
+            } else {
+                const records = res?.records || []
+                setRows(records)
+                setPage({current, size, total: res?.total == null ? null : Number(res.total)})
+            }
+        } catch (e) {
+            setRows([])
+            setError(e)
+        } finally {
+            setLoading(false)
+        }
+    }, [load, page.current, page.size])
+
+    useEffect(() => {
+        fetch(1)
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    const totalKnown = page.total != null && page.total > 0
+    return (
+        <div>
+            <PageHeader title={title} subtitle={description}/>
+            <Card
+                extra={
+                    <Button icon={<ReloadOutlined/>} loading={loading}
+                            onClick={() => fetch(page.current, page.size)}>刷新</Button>
+                }
+            >
+                {extra}
+                {error ? (
+                    <ErrorState error={error} onRetry={() => fetch(page.current, page.size)} type="inline"/>
+                ) : (
+                    <Table
+                        size="small"
+                        columns={columns}
+                        dataSource={rows}
+                        loading={loading}
+                        rowKey={(r) => r?.[rowKey] ?? r?.key ?? JSON.stringify(r).slice(0, 32)}
+                        pagination={{
+                            current: page.current,
+                            pageSize: page.size,
+                            total: totalKnown ? page.total : rows.length,
+                            showSizeChanger: true,
+                            showTotal: () =>
+                                totalKnown
+                                    ? `共 ${page.total} 条`
+                                    : `本页 ${rows.length} 条（接口 total 未返回有效值）`,
+                        }}
+                        onChange={(p) => fetch(p.current, p.pageSize)}
+                        expandable={expandable}
+                        locale={{emptyText: <EmptyState title="暂无数据" description="接口返回空列表"/>}}
+                    />
+                )}
+            </Card>
+        </div>
+    )
+}

package/src/components/ui/SearchInput.jsx

@@ -0,0 +1,111 @@
+import {useEffect, useRef, useState} from 'react'
+import {Input} from 'antd'
+import {SearchOutlined} from '@ant-design/icons'
+import {radius} from './tokens'
+
+/**
+ * Debounced SearchInput - 修复 z-opc 后台"搜索必须点按钮"的交互不合理.
+ *
+ * 原则 (来自 ui-ux-pro-max P8 / frontend-ui-engineering Forms):
+ *   - 输入即时反馈, 不要让用户多一次点击
+ *   - debounce 300ms 防止每个键击都发请求
+ *   - 受控 value + onChange, 避免组件内部状态混乱
+ *   - Enter 立即触发 (不等待 debounce)
+ *   - Escape 清空
+ *
+ * @param {Object} props
+ * @param {string} [props.value] - 受控值
+ * @param {Function} props.onChange - 输入变化回调 (debounced)
+ * @param {Function} [props.onSearch] - 显式搜索回调 (Enter / 点按钮)
+ * @param {string} [props.placeholder]
+ * @param {number} [props.debounceMs] - 防抖延迟 (默认 300)
+ * @param {number} [props.width] - 宽度 (默认 280)
+ */
+export default function SearchInput({
+                                        value: controlledValue,
+                                        onChange,
+                                        onSearch,
+                                        placeholder = '搜索...',
+                                        debounceMs = 300,
+                                        width = 280,
+                                        allowClear = true,
+                                        // antd v6: enterButton 已被废弃,SearchInput 已通过 onKeyDown 自行处理 Enter 键,
+                                        // 所以从 rest 里过滤掉,避免透传到原生 <input> 报 React 警告。
+                                        enterButton: _ignored,
+                                        ...rest
+                                    }) {
+    const [inner, setInner] = useState(controlledValue || '')
+    const timerRef = useRef(null)
+    const lastEmittedRef = useRef(controlledValue || '')
+
+    // 受控/非受控兼容
+    useEffect(() => {
+        if (controlledValue !== undefined && controlledValue !== inner) {
+            setInner(controlledValue || '')
+            lastEmittedRef.current = controlledValue || ''
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [controlledValue])
+
+    useEffect(() => {
+        return () => {
+            if (timerRef.current) clearTimeout(timerRef.current)
+        }
+    }, [])
+
+    const emit = (v) => {
+        lastEmittedRef.current = v
+        if (onChange) onChange(v)
+    }
+
+    const handleChange = (e) => {
+        const v = e.target.value
+        setInner(v)
+        if (timerRef.current) clearTimeout(timerRef.current)
+        // 清空时立即触发 (用户期望立即看到结果)
+        if (v === '') {
+            emit('')
+            return
+        }
+        timerRef.current = setTimeout(() => emit(v), debounceMs)
+    }
+
+    const handleSearch = (v) => {
+        if (timerRef.current) clearTimeout(timerRef.current)
+        emit(v)
+        if (onSearch) onSearch(v)
+    }
+
+    const handleKeyDown = (e) => {
+        if (e.key === 'Enter') {
+            e.preventDefault()
+            handleSearch(inner)
+        } else if (e.key === 'Escape') {
+            setInner('')
+            handleSearch('')
+        }
+    }
+
+    const handleClear = () => {
+        setInner('')
+        handleSearch('')
+    }
+
+    return (
+        <Input
+            {...rest}
+            value={inner}
+            onChange={handleChange}
+            onPressEnter={handleSearch}
+            onKeyDown={handleKeyDown}
+            placeholder={placeholder}
+            allowClear={allowClear ? {clearIcon: <span onClick={handleClear}>×</span>} : false}
+            prefix={<SearchOutlined style={{color: '#9ca3af'}}/>}
+            style={{
+                width,
+                borderRadius: radius.md,
+                ...(rest.style || {}),
+            }}
+        />
+    )
+}

package/src/components/ui/SectionHeader.jsx

@@ -0,0 +1,76 @@
+import CategoryDot from './CategoryDot'
+
+/**
+ * 段落标题 - 借鉴 wenming7/marketplace 分类段头
+ *
+ * 视觉:
+ *   � 热门爆款                          全部 >
+ *   圆点 + 标题                          右侧跳转链接
+ *
+ * @param {Object} props
+ * @param {string} props.color - 圆点配色
+ * @param {string} props.title - 标题
+ * @param {string} [props.subtitle] - 副标题
+ * @param {string} [props.moreText] - "全部 >" 文案
+ * @param {string} [props.moreHref] - 跳转路径
+ */
+export default function SectionHeader({
+                                          color = 'blue',
+                                          title,
+                                          subtitle,
+                                          moreText = '全部',
+                                          moreHref,
+                                          onMore,
+                                      }) {
+    return (
+        <div style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            marginBottom: 16,
+        }}>
+            <div style={{display: 'flex', alignItems: 'baseline', gap: 12}}>
+                <CategoryDot color={color} label={title} size={10}/>
+                {subtitle && (
+                    <span style={{
+                        fontSize: 13,
+                        color: '#6b7280',
+                        fontWeight: 400,
+                    }}>
+                        {subtitle}
+                    </span>
+                )}
+            </div>
+            {(moreHref || onMore) && (
+                <a
+                    href={moreHref}
+                    onClick={(e) => {
+                        if (onMore) {
+                            e.preventDefault()
+                            onMore()
+                        }
+                    }}
+                    style={{
+                        fontSize: 13,
+                        color: '#6b7280',
+                        textDecoration: 'none',
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        gap: 4,
+                        cursor: 'pointer',
+                        transition: 'color 150ms ease',
+                    }}
+                    onMouseEnter={(e) => {
+                        e.currentTarget.style.color = '#7c3aed'
+                    }}
+                    onMouseLeave={(e) => {
+                        e.currentTarget.style.color = '#6b7280'
+                    }}
+                >
+                    {moreText}
+                    <span style={{fontSize: 12}}>›</span>
+                </a>
+            )}
+        </div>
+    )
+}

package/src/components/ui/StatusBadge.jsx

@@ -0,0 +1,66 @@
+import {Tag} from 'antd'
+
+/**
+ * 通用状态 Badge — 替代散落在各页面的 Tag 颜色定义
+ *
+ * 用法:
+ *   <StatusBadge status={1} type="status"/>     // 任务状态
+ *   <StatusBadge status="ACTIVE" type="model"/> // 模型状态
+ *   <StatusBadge level="high" type="priority"/> // 优先级
+ */
+
+const TASK_STATUS = {
+    0: {label: '待办', color: 'default'},
+    1: {label: '进行中', color: 'blue'},
+    2: {label: '已完成', color: 'green'},
+}
+
+const MODEL_STATUS = {
+    ACTIVE: {label: '正常', color: 'green'},
+    INACTIVE: {label: '禁用', color: 'red'},
+    ENABLED: {label: '启用', color: 'green'},
+    DISABLED: {label: '禁用', color: 'red'},
+}
+
+const PRIORITY = {
+    low: {label: '低', color: 'default'},
+    medium: {label: '中', color: 'orange'},
+    high: {label: '高', color: 'red'},
+    1: {label: '低', color: 'default'},
+    2: {label: '中', color: 'orange'},
+    3: {label: '高', color: 'red'},
+}
+
+const APPROVAL = {
+    PENDING: {label: '待审批', color: 'orange'},
+    APPROVED: {label: '已通过', color: 'green'},
+    REJECTED: {label: '已拒绝', color: 'red'},
+    CANCELLED: {label: '已撤回', color: 'default'},
+}
+
+const SCHEDULE = {
+    RUNNING: {label: '运行中', color: 'green'},
+    PAUSED: {label: '已暂停', color: 'orange'},
+    STOPPED: {label: '已停止', color: 'default'},
+    FAILED: {label: '失败', color: 'red'},
+    SUCCESS: {label: '成功', color: 'green'},
+}
+
+const MAP = {
+    task: TASK_STATUS,
+    model: MODEL_STATUS,
+    priority: PRIORITY,
+    approval: APPROVAL,
+    schedule: SCHEDULE,
+}
+
+export default function StatusBadge({status, type = 'task', mapping, ...rest}) {
+    const m = mapping || MAP[type] || {}
+    const cfg = m[status]
+    if (!cfg) return <Tag {...rest}>{String(status)}</Tag>
+    return (
+        <Tag color={cfg.color} {...rest}>
+            {cfg.label}
+        </Tag>
+    )
+}

package/src/components/ui/TableToolbar.jsx

@@ -0,0 +1,58 @@
+import {Button, Space} from 'antd'
+import {ReloadOutlined} from '@ant-design/icons'
+
+/**
+ * 表格上方工具栏 — 统一搜索 + 过滤 + 操作按钮布局
+ *
+ * Props:
+ *   - left:    ReactNode   左侧过滤区 (Select, Radio, Checkbox 等)
+ *   - right:   ReactNode   右侧操作区 (按钮组)
+ *   - extra:   ReactNode   最右侧插入
+ *
+ * 用法:
+ * <TableToolbar
+ *   left={
+ *     <>
+ *       <SearchInput placeholder="搜索..."/>
+ *       <Select placeholder="状态"/>
+ *     </>
+ *   }
+ *   right={
+ *     <>
+ *       <Button icon={<ReloadOutlined/>}>刷新</Button>
+ *       <Button type="primary" icon={<PlusOutlined/>}>新建</Button>
+ *     </>
+ *   }
+ * />
+ */
+export default function TableToolbar({left, right, extra}) {
+    return (
+        <div
+            style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                gap: 12,
+                marginBottom: 12,
+                flexWrap: 'wrap',
+            }}
+        >
+            <Space size={8} wrap>{left}</Space>
+            <Space size={8} wrap>
+                {right}
+                {extra}
+            </Space>
+        </div>
+    )
+}
+
+/**
+ * 紧凑版刷新按钮 — 表格内常用
+ */
+export function RefreshButton({onClick, loading, title = '刷新'}) {
+    return (
+        <Button icon={<ReloadOutlined/>} onClick={onClick} loading={loading} title={title}>
+            {title}
+        </Button>
+    )
+}