npm package: @hybridh5/c-ui-react
Description: React + Vite migration package for c-ui
Latest version: 0.1.1

# @hybridh5/c-ui-react

c-ui 的 React 组件包，基于 React + TypeScript + Vite 构建。

## 安装

```bash
npm i @hybridh5/c-ui-react react react-dom
```

说明：

- `dayjs` 是 `CDatePicker` 的可选 peer 依赖；使用日期组件时建议安装。

```bash
npm i dayjs
```

## 快速开始

```tsx
import {
  CConfigProvider,
  CButton,
  CInput,
  CNumberInput,
  CSelect,
  CDatePicker,
  type CSelectOption
} from '@hybridh5/c-ui-react'
import '@hybridh5/c-ui-react/dist/c-ui-react.css'

const options: CSelectOption[] = [
  { label: '全部', value: 'all' },
  { label: '进行中', value: 'doing' },
  { label: '已完成', value: 'done' }
]

export default function Demo() {
  return (
    <CConfigProvider theme="light" size="md">
      <CButton variant="primary">提交</CButton>
      <CInput placeholder="请输入关键词" clearable />
      <CNumberInput min={0} max={100} defaultValue={10} />
      <CSelect options={options} defaultValue="all" />
      <CDatePicker format="YYYY-MM-DD" clearable />
    </CConfigProvider>
  )
}
```

说明：

- 即使按需引入组件，也需要引入一次 `@hybridh5/c-ui-react/dist/c-ui-react.css`。

## 受控与事件约定

输入类组件（如 `CInput`、`CNumberInput`、`CSelect`、`CCheckbox`、`CPagination`）支持受控与非受控：

- 受控：`value` + `onValueChange`
- 非受控：`defaultValue`

`onChange` 与 `onValueChange` 在多个组件中都会触发值变化回调，推荐在业务中统一使用 `onValueChange`。

## 配置提供器

包里有两个配置容器：

- `CConfigProvider`：推荐在业务里直接使用，会渲染 `.c-config-provider` 容器并向下提供 `theme`、`size`。
- `CUIConfigProvider`：更底层，仅提供上下文，不额外渲染容器。

```tsx
import { CConfigProvider, CUIConfigProvider, useCUIConfig } from '@hybridh5/c-ui-react'

function Toolbar() {
  const config = useCUIConfig()
  return <span>{config.theme ?? 'light'} / {config.size ?? 'md'}</span>
}

export default function App() {
  return (
    <CConfigProvider theme="dark" size="lg">
      <Toolbar />
    </CConfigProvider>
  )
}
```

## 常用 API 速览

以下只列最常用属性，完整类型以导出的 `*Props` 为准。

### 表单与输入

- `CInput`：`value`、`defaultValue`、`placeholder`、`clearable`、`prefix`、`suffix`、`onValueChange`
- `CNumberInput`：`value`、`defaultValue`、`min`、`max`、`step`、`clearable`、`onValueChange`
- `CCheckbox`：`checked`、`defaultChecked`、`indeterminate`、`disabled`、`onValueChange`
- `CSelect`：`value`、`defaultValue`、`options`、`placeholder`、`filterable`、`clearable`、`onValueChange`
- `CDatePicker`：`value`、`format`、`placeholder`、`clearable`、`trigger`、`onChange`

### 数据展示

- `CTable`：`columns`、`rows`、`rowKey`、`selectable`、`selected`、`onSelectionChange`、`onSort`
- `CPagination`：`total`、`currentPage`、`defaultCurrentPage`、`pagerCount`、`showTotal`、`onCurrentPageChange`
- `CBadge`：`count`、`dot`、`max`、`showZero`
- `CTag`：`color`、`size`、`closable`、`onClose`
- `CTooltip`：`content`、`placement`、`trigger`
- `CEmpty`：`text`、`icon`、`height`

### 基础组件

- `CButton`：`type`、`variant`、`size`、`loading`、`block`、`prefix`、`suffix`

## 组件与类型导出

```ts
import {
  CButton,
  CInput,
  CNumberInput,
  CBadge,
  CCheckbox,
  CTag,
  CEmpty,
  CTooltip,
  CConfigProvider,
  CPagination,
  CDatePicker,
  CSelect,
  CTable,
  CUIConfigProvider,
  useCUIConfig,
  type CButtonProps,
  type CInputProps,
  type CNumberInputProps,
  type CBadgeProps,
  type CCheckboxProps,
  type CTagProps,
  type CEmptyProps,
  type CTooltipProps,
  type CConfigProviderProps,
  type CPaginationProps,
  type CDatePickerProps,
  type CSelectProps,
  type CSelectOption,
  type CTableProps,
  type CTableColumn,
  type CTableAction,
  type CTableRow,
  type CUIConfigProviderProps,
  type CUIComponentSize,
  type CUIConfig,
  type CUITheme
} from '@hybridh5/c-ui-react'
```

## 常用示例

### 表格

```tsx
import { CTable, type CTableColumn, type CTableRow } from '@hybridh5/c-ui-react'

const columns: CTableColumn[] = [
  { key: 'name', label: '姓名' },
  { key: 'age', label: '年龄', sortable: true }
]

const rows: CTableRow[] = [
  { id: 1, name: 'Alice', age: 28 },
  { id: 2, name: 'Bob', age: 32 }
]

export default function TableDemo() {
  return (
    <CTable
      rowKey="id"
      columns={columns}
      rows={rows}
      selectable
      onSelectionChange={(keys) => {
        console.log('selected keys', keys)
      }}
      onSort={(key, order) => {
        console.log('sort', key, order)
      }}
    />
  )
}
```

### 分页

```tsx
import { CPagination } from '@hybridh5/c-ui-react'

export default function Pager() {
  return (
    <CPagination
      total={125}
      defaultCurrentPage={1}
      pagerCount={7}
      showTotal
      onCurrentPageChange={(page) => {
        console.log('page', page)
      }}
    />
  )
}
```

## 本地开发

在 monorepo 根目录执行：

```bash
npm run build -w @hybridh5/c-ui-react
```

如需全仓验证：

```bash
npm run build
```