# @tfdesign/dashboard

> Dashboard 规范的设计系统 npm 包：**内置**与 B 端完全一致的基础组件能力（Button/Input/Tag/FormTitle/Modal/Sheet/Tabs/Table 等，无需安装 `@tfdesign/b-end`），并新增 Dashboard 专属组件（图表、指标卡、筛选器、图表容器、图例、钻取、对比面板等）。

## 一键安装（推荐）

在你的业务项目根目录执行：

```bash
npx -y -p @tfdesign/dashboard@latest tfds-dashboard-setup
```

安装完成后，在 IDE 里使用 Skill：

- **Skill 名称**：`产品设计-体服平台数据看板-界面生成`

## 手动安装

```bash
npm i @tfdesign/dashboard
```

并确保入口 CSS（`src/index.css` 或 `app/globals.css` 等）在 `@import "tailwindcss"` 之后引入：

```css
@import "@tfdesign/dashboard/theme.css";
```

## 图表组件（Smart*Chart）

Dashboard 图表组件以 `spec` 驱动，统一遵循：

- **高度链路（硬规则）**：外层必须给明确高度（通常用 `spec.config.height`），图表内部使用 `ResponsiveContainer height="100%"`；禁止仅靠内容撑高。
- **配色**：序列颜色仅使用 `data-n` 槽位（`data-0`…`data-18`），由 `resolveColorToken()` 映射到主题色。
- **外壳一致**：网格线/坐标轴/Legend/Tooltip/Cursor 统一走图表基础封装（避免样式漂移）。

### 快速示例

```jsx
import {
  SmartLineChart,
  SmartBarChart,
  SmartAreaChart,
  SmartPieChart,
  SmartGaugeChart,
  SmartRadarChart,
  SmartScatterChart,
  SmartSankeyChart,
  SmartBulletChart,
  SmartComposedChart,
  SmartWordCloud,
} from '@tfdesign/dashboard';

export default function Demo() {
  const data = [
    { name: '05-22', v1: 3200, v2: 520 },
    { name: '05-23', v1: 3600, v2: 560 },
    { name: '05-24', v1: 4100, v2: 610 },
    { name: '05-25', v1: 4520, v2: 660 },
    { name: '05-26', v1: 4800, v2: 720 },
  ];

  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <SmartLineChart
        spec={{
          data,
          series: [
            { dataKey: 'v1', name: '原声反馈', colorToken: 'data-1' },
            { dataKey: 'v2', name: '风险线索', colorToken: 'data-5' },
          ],
          config: { height: 320, curveType: 'monotone', showDots: false },
        }}
      />

      <SmartBarChart
        spec={{
          data,
          series: [{ dataKey: 'v1', name: '有效内容', colorToken: 'data-0' }],
          config: { height: 320, layout: 'vertical', stack: false },
        }}
      />

      <SmartAreaChart
        spec={{
          data,
          series: [{ dataKey: 'v1', name: '趋势', colorToken: 'data-4' }],
          config: { height: 320, stack: false, curveType: 'monotone' },
        }}
      />

      <SmartPieChart
        spec={{
          data: [
            { name: 'A', value: 42, colorToken: 'data-1' },
            { name: 'B', value: 28, colorToken: 'data-5' },
            { name: 'C', value: 18, colorToken: 'data-7' },
          ],
          config: { height: 320, donut: true },
        }}
      />

      <SmartGaugeChart
        spec={{ value: 4.2, min: 3, max: 5, config: { title: '满意度', progressColorToken: 'data-1' } }}
      />

      <SmartRadarChart
        spec={{
          data: [
            { name: '维度一', series_0: 54, series_1: 64 },
            { name: '维度二', series_0: 58, series_1: 38 },
            { name: '维度三', series_0: 22, series_1: 24 },
            { name: '维度四', series_0: 62, series_1: 52 },
            { name: '维度五', series_0: 28, series_1: 78 },
          ],
          series: [
            { dataKey: 'series_0', name: '本周', colorToken: 'data-1' },
            { dataKey: 'series_1', name: '上周', colorToken: 'data-7' },
          ],
          config: { height: 320, maxValue: 80 },
        }}
      />

      <SmartScatterChart
        spec={{
          series: [
            { name: '样本A', colorToken: 'data-1', data: [{ x: 16, y: 74 }, { x: 52, y: 70 }] },
            { name: '样本B', colorToken: 'data-5', data: [{ x: 78, y: 60 }, { x: 86, y: 52 }] },
          ],
          config: { height: 320, legendPosition: 'bottom' },
        }}
      />

      <SmartBulletChart
        spec={{
          data: [{ title: '满意度', ranges: [100], measures: [80], targets: [85] }],
          config: { height: 320, variant: 'basic', legendPosition: 'top' },
        }}
      />

      <SmartSankeyChart
        spec={{
          nodes: [{ id: 'a', name: '入口' }, { id: 'b', name: '流向' }],
          links: [{ source: 'a', target: 'b', value: 120 }],
          config: { height: 360, dataColorToken: 'data-1', showDataTitle: true, title: '流向分析' },
        }}
      />

      <SmartComposedChart
        spec={{
          data,
          xAxisKey: 'name',
          series: [{ type: 'bar', dataKey: 'v1', name: '柱' }, { type: 'line', dataKey: 'v2', name: '线' }],
          config: { height: 320 },
        }}
      />

      <SmartWordCloud
        spec={{
          words: [
            { text: '成交金额', value: 100, category: 0 },
            { text: '电商数据', value: 80, category: 1 },
          ],
          config: { height: 320, categoryCount: 2, categoryLabels: ['分类1', '分类2'], categoryDataTokens: ['data-1', 'data-5'] },
        }}
      />
    </div>
  );
}
```

## 硬门禁：ESLint（`@tfdesign/dashboard/eslint`）

看板项目请使用 **dashboard preset**（spacing 来自 dashboard Token；锁定大屏模板 + 内嵌 b-end 范式模板）：

```bash
npm i -D eslint @eslint/js eslint-plugin-react eslint-plugin-react-hooks globals @tfdesign/dashboard
```

`eslint.config.js`：

```js
import tfds from '@tfdesign/dashboard/eslint';
export default [...tfds];
```

CI 建议：

```bash
npx eslint .
node node_modules/@tfdesign/dashboard/scripts/check-tfds-contract.mjs
```

| 工具 | 作用 |
|------|------|
| `@tfdesign/dashboard/eslint` | spacing 白名单、禁止样式漂移、锁定 `Monitor315Pattern` 等大屏模板 |
| `check-tfds-contract.mjs` | 禁直连 Recharts/ECharts、图表 hex 硬编码、b-end 基础件误用等 |

规则事实源：`scripts/eslint/`（随包 `eslint/` 子路径发布，与包版本对齐）。

