19 数据契约与示例集（核心组件的完整使用契约）

import { Button } from '@xiaoye-react/ui';

<Button
    component="a"
    href="/console/list"
    variant="gradient"
    gradient={{ from: 'blue', to: 'cyan', deg: 45 }}
    size="md"
    radius="md"
    color="blue"
    justify="space-between"
    leftSection={<IconArrowLeft />}
    rightSection={<IconChevronRight />}
    fullWidth
    loading={submitting}
    loaderProps={{ color: 'currentColor' }}
    autoContrast
    classNames={{ root: 'btn-root', label: 'btn-label' }}
    styles={{ root: { boxShadow: '0 2px 8px rgba(0,0,0,.12)' } }}
    vars={{ root: { '--button-height': '52px' } }}
    attributes={{ 'data-testid': 'submit-btn' }}
    onClick={handleClick}
>
    保存并返回列表
</Button>

// withProps：固定 props 的变体组件（静态件 classes/varsResolver/extend 全部透传）
const DestructiveButton = Button.withProps({ variant: 'filled', color: 'red' });

// 按选择器取内部类名做 CSS 探测
console.log(Button.classes.root);

// 主题级：主题上下文里对 Button 做全局定制
// theme={{ components: { Button: { defaultProps: { variant: 'light' }, classNames: { label: 'global-label' } } } }}

import { TextInput } from '@xiaoye-react/ui';

const [name, setName] = useState('');

<TextInput
    label="项目名称"
    description="2-32 个字符，创建后不可修改"
    placeholder="例如：运维巡检平台"
    error={nameError ?? undefined}
    required
    withAsterisk
    size="md"
    variant="default"
    radius="sm"
    disabled={readonly}
    leftSection={<IconForms size={16} />}
    rightSection={<CharCount value={name} />}
    maxLength={32}
    value={name}
    onChange={e => setName(e.currentTarget.value)}
    onBlur={validateName}
    classNames={{ input: 'ti-input' }}
    styles={{ label: { fontWeight: 600 } }}
    vars={{ root: { '--input-height': '44px' } } as any}
    data-autofocus
/>

const ref = useRef<HTMLInputElement>(null);
<TextInput
    defaultValue="默认项目名"
    key={formKey}
    ref={ref}
    onChange={e => draftRef.current = e.currentTarget.value}
/>

import { Select } from '@xiaoye-react/ui';

const [dept, setDept] = useState<string | null>(null);

<Select
    label="所属部门"
    placeholder="选择部门"
    data={[
        { value: 'rd', label: '研发部', group: '技术线' },
        { value: 'qa', label: '测试部', group: '技术线' },
        { value: 'hr', label: '人事部', group: '职能线' },
        '外包',                                  // 字符串条目也合法
    ]}
    value={dept}
    onChange={setDept}
    searchable
    clearable
    maxDropdownHeight={280}
    position="bottom-start"
    checkIconPosition="right"
    renderOption={({ option, checked }) => (
        <span style={{ fontWeight: checked ? 700 : 400 }}>{option.label}</span>
    )}
    nothingFoundMessage="没有匹配的部门"
    classNames={{ option: 'sel-option' }}
    styles={{ dropdown: { borderRadius: 12 } }}
/>

<Select
    defaultValue="rd"
    onChange={v => console.log('选中', v)}   // 清除时收到 null
    data={DEPT_DATA}
/>

import { Tabs } from '@xiaoye-react/ui';

<Tabs
    defaultValue="posts"
    variant="pills"
    color="teal"
    radius="md"
    orientation="horizontal"
    keepMounted={false}
    classNames={{ tab: 'my-tab' }}
    vars={{ root: { '--tabs-radius': '10px' } }}
>
    <Tabs.List>
        <Tabs.Tab value="posts">文章</Tabs.Tab>
        <Tabs.Tab value="comments">评论</Tabs.Tab>
        <Tabs.Tab value="about">关于</Tabs.Tab>
    </Tabs.List>
    <Tabs.Panel value="posts">文章列表…</Tabs.Panel>
    <Tabs.Panel value="comments" keepMounted>评论（隐藏时保留 DOM）…</Tabs.Panel>
    <Tabs.Panel value="about">关于…</Tabs.Panel>
</Tabs>

const [active, setActive] = useState('posts');
<Tabs value={active} onChange={setActive}>
    {/* 子件不变 —— 受控/非受控切换不改子件代码 */}
</Tabs>

import { Modal, Button } from '@xiaoye-react/ui';

const [opened, { open, close }] = useDisclosure(false);

<>
    <Button onClick={open}>编辑用户</Button>
    <Modal
        opened={opened}
        onClose={close}
        title="编辑用户"
        size="lg"
        radius="md"
        centered
        withOverlay
        overlayProps={{ backgroundOpacity: 0.55, blur: 3 }}
        withCloseButton
        closeOnEscape
        closeOnClickOutside={false}
        trapFocus
        returnFocus
        lockScroll
        withinPortal
        zIndex={200}
        transitionProps={{ duration: 200 }}
        classNames={{ header: 'm-header', body: 'm-body' }}
        vars={{ root: { '--modal-radius': '16px' } }}
    >
        <Modal.Body>…表单…</Modal.Body>
    </Modal>
</>

import { DataTable } from '@xiaoye-react/ui';

const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(10);
const [total, setTotal] = useState(0);
const [records, setRecords] = useState<User[]>([]);
const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
const [sortStatus, setSortStatus] = useState<DataTableSortStatus<User> | null>(null);

<DataTable<User>
    columns={[
        { accessor: 'name', title: '姓名', sortable: true, width: 160 },
        { accessor: 'email', title: '邮箱', ellipsis: true },
        { accessor: 'role', title: '角色', render: u => ROLE_LABELS[u.role] },
        { accessor: 'actions', title: '操作', width: 80, sticky: 'right',
          render: u => <Button size="xs" variant="light">编辑</Button> },
    ]}
    records={records}
    rowKey={u => u.id}
    total={total} page={page} pageSize={pageSize}
    onPageChange={setPage} onPageSizeChange={setPageSize}
    sortStatus={sortStatus} onSortStatusChange={setSortStatus}
    selectionMode="checkbox"
    selectedKeys={selectedKeys} onSelectedKeysChange={setSelectedKeys}
    withColumnSettings
    loading={loading}
    empty={<EmptyState title="暂无数据" />}
    striped highlightOnHover
    minHeight={360} maxHeight={560}
    verticalSpacing="sm"
    onRowClick={u => openDetail(u.id)}
    styles={{ td: { cursor: 'pointer' } }}
/>

<DataTable columns={columns} records={localUsers} rowKey={u => u.id} />
// 排序在本地 sortRecords 稳定排序；不传 total/page 即不渲染分页底栏

import { Notifications, notifications } from '@xiaoye-react/ui';

// 应用根：渲染一次宿主
<UIProvider>
    <Notifications position="top-right" limit={5} />
    <App />
</UIProvider>

// 任意模块（组件、请求拦截器、工具函数）内：
notifications.show({ title: '保存成功', message: '配置已更新', color: 'teal', autoClose: 3000 });
notifications.show({ title: '请求失败', message: err.message, color: 'red', autoClose: false });
notifications.update(id, { message: '已重试成功' });
notifications.hide(id);
notifications.clean();       // 清空全部
notifications.cleanQueue();  // 清空排队中的

import { UIProvider, createTheme, Button } from '@xiaoye-react/ui';

// 第一级：主题对象（JS 侧声明，类型收窄走 createTheme 恒等函数）
const theme = createTheme({
    primaryColor: 'teal',
    primaryShade: 7,
    defaultRadius: 'md',
    fontFamily: '"PingFang SC", "Microsoft YaHei", sans-serif',
    colors: {
        // virtual color：亮暗两套分别取值
        brand: [
            '#e6f7f4', '#c2ece4', '#8fd9cb', '#5cc6b1', '#2fb397',
            '#1a9c82', '#0f7d67', '#0c6453', '#094b3f', '#07332b',
        ],
    },
    // 主题级组件定制（全局 StylesApi）
    components: {
        Button: { defaultProps: { radius: 'md' }, classNames: { label: 'app-btn-label' } },
    },
});

export default function App() {
    return (
        <UIProvider
            theme={theme}
            colorScheme="auto"                 // 受控传 'light'|'dark'；auto 跟随系统
            classNamesPrefix="ui"
            localStorageKey="ui-color-scheme-value"
        >
            {/* 第二级：CSS 变量级联——组件消费 --ui-* 与 --brand-* */}
            <Button color="brand" variant="filled">主题色按钮（随明暗切换自动取 shade）</Button>

            {/* 第三级：实例级 vars 覆盖组件白名单变量 */}
            <Button vars={{ root: { '--button-height': '52px' } }}>加高按钮</Button>

            {/* 第四级：classNames/styles 按选择器注入 */}
            <Button classNames={{ root: 'hero-btn' }} styles={{ label: { letterSpacing: 2 } }}>
                定制按钮
            </Button>
        </UIProvider>
    );
}

:root {
    --ui-radius-default: 10px;
    --ui-color-body: #fafafa;
}
[data-ui-color-scheme="dark"] {
    --ui-color-body: #121212;
}