npm package: @kovic_fan/realibox-ui-sdk
Description: 基于 Lit 3 + TypeScript + Vite 的企业级组件库脚手架，已集成：
Latest version: 0.1.2

# Enterprise Lit SDK Scaffold

基于 Lit 3 + TypeScript + Vite 的企业级组件库脚手架，已集成：

- 全局配置中心（`initSDK` + 单例 `ConfigManager`）
- 授权系统（拦截器、有效期检查、SessionStorage 缓存、防抖校验）
- 组件基类（`BaseElement`）与多个示例组件（`pro-data-chart`、`pro-info-card`、`pro-stat-card`）
- Tailwind CSS（默认优先使用 Tailwind 工具类）
- ESLint + Biome + PostCSS

## 1. 项目目录结构

```text
.
├── AGENTS.md
├── README.md
├── biome.json
├── eslint.config.mjs
├── index.html
├── package.json
├── postcss.config.cjs
├── tsconfig.json
├── vite.config.ts
└── src
    ├── auth
    │   ├── expiry.ts
    │   ├── interceptor.ts
    │   ├── storage.ts
    │   ├── types.ts
    │   └── validator.ts
    ├── components
    │   ├── base
    │   │   ├── base-element.ts
    │   │   └── index.ts
    │   ├── pro-data-chart
    │   │   ├── pro-data-chart.ts
    │   │   └── index.ts
    │   ├── pro-info-card
    │   │   ├── pro-info-card.ts
    │   │   └── index.ts
    │   ├── pro-stat-card
    │   │   ├── pro-stat-card.ts
    │   │   └── index.ts
    │   └── index.ts
    ├── core
    │   └── config.ts
    ├── styles
    │   └── tailwind.css
    ├── index.ts
    ├── main.ts
    └── vite-env.d.ts
```

## 2. 如何跑起来

```bash
npm install
npm run dev
```

启动后打开 Vite 提示的地址（默认 `http://localhost:5173`），即可看到多个组件联调页。

> 当前演示授权规则：必须先调用 `initSDK({ apiKey })`，且仅 `apiKey === "123"` 时组件可用。

## 3. 如何查看你新写的组件

1. 在 `src/components/<component-name>/` 新建组件目录。
2. 组件文件建议命名为 `<component-name>.ts`，并在该目录写 `index.ts` 导出。
3. 在 `src/components/index.ts` 和 `src/index.ts` 聚合导出。
4. 在根目录 `index.html` 直接写组件标签调试。
5. 保存后 Vite 会热更新，页面实时看到效果。

## 4. 如何新增一个组件（推荐流程）

```ts
// src/components/hello-card/hello-card.ts
import { html } from "lit";
import { BaseElement } from "../base";

export class HelloCard extends BaseElement {
  render() {
    if (this.authState === "checking" || this.authState === "idle") return this.renderAuthLoading();
    if (!this.isAuthorized) return this.renderAuthError();
    return html`<section class="rounded-xl border border-slate-200 bg-white p-4">Hello Card</section>`;
  }
}

if (!customElements.get("hello-card")) {
  customElements.define("hello-card", HelloCard);
}
```

```ts
// src/components/hello-card/index.ts
export { HelloCard } from "./hello-card";
```

```ts
// src/components/index.ts
import "./hello-card";
export { HelloCard } from "./hello-card";
```

```ts
// src/index.ts
import "./components";
export { HelloCard } from "./components";
```

## 5. 用户如何引入使用（必须先初始化）

### 5.1 打包 SDK

```bash
npm run build
```

会输出：

- `dist/enterprise-lit-sdk.es.js`
- `dist/enterprise-lit-sdk.umd.js`

### 5.2 在业务项目中使用（ESM）

```ts
import { initSDK } from "@kovic_fan/realibox-ui-sdk";

// 初始化是必须步骤；当前示例仅 key=123 为合法。
initSDK({ apiKey: "123" });
```

```html
<!-- 组件已自动注册，直接使用即可 -->
<pro-data-chart title="营收趋势" subtitle="单位：万元" series="12,23,35,46" variant="outline" size="lg"></pro-data-chart>
<pro-info-card title="企业版能力" desc="模块化架构能力说明" badge="PRO" variant="default" size="md"></pro-info-card>
<pro-stat-card title="新增客户" value="1,284" trend="+18.2%" variant="ghost" size="sm"></pro-stat-card>
```

### 5.4 TypeScript 类型（含 React JSX 按需类型）

```ts
import type { ProDataChartProps } from "@kovic_fan/realibox-ui-sdk";
```

### 5.3 在纯 HTML 中使用（UMD）

```html
<!-- 当前 npm 版本未暴露 UMD 文件；建议先走 ESM 接入。 -->
```

## 6. 质量与格式命令

```bash
npm run lint
npm run lint:fix
npm run format
npm run format:check
```

## 7. Tailwind 在 Lit 的说明

Tailwind 只在 SDK 构建阶段使用，样式会预编译并自动注入到库入口。  
客户侧无需安装 Tailwind，也无需手动引入 `style.css`。

## 8. 组件定制策略（已执行）

为保证 API 稳定和可维护性，组件定制统一采用以下三层能力：

1. `class`：控制组件外层布局（宽高、栅格、间距、响应式）。
2. `variant` / `size`：控制受控外观差异（不暴露内部结构细节）。
3. CSS 变量：控制主题（颜色、圆角、图表主色），避免依赖内部 DOM 层级。

### 8.1 统一可用属性

`pro-data-chart`、`pro-info-card`、`pro-stat-card` 现已统一支持：

- `variant`: `default | outline | ghost`
- `size`: `sm | md | lg`
- `class`: 外层 class（原生 HTML 属性）

### 8.2 CSS 变量清单

卡片通用变量：

- `--ri-card-bg`
- `--ri-card-border`
- `--ri-card-radius`
- `--ri-card-text`
- `--ri-card-title`
- `--ri-card-muted`

信息卡补充变量：

- `--ri-card-desc`
- `--ri-card-badge-bg`
- `--ri-card-badge-text`

统计卡补充变量：

- `--ri-card-value`
- `--ri-card-trend`

图表卡补充变量：

- `--ri-chart-grid`
- `--ri-chart-bar-from`
- `--ri-chart-bar-to`
- `--ri-chart-label`

### 8.3 用户侧定制示例

```html
<style>
  .enterprise-theme {
    --ri-card-bg: #f8fafc;
    --ri-card-border: #bfdbfe;
    --ri-card-radius: 1.25rem;
    --ri-card-title: #0f172a;
    --ri-card-muted: #334155;
    --ri-chart-bar-from: #38bdf8;
    --ri-chart-bar-to: #0369a1;
  }
</style>

<pro-data-chart
  class="enterprise-theme w-full"
  title="北区季度营收"
  subtitle="单位：万元"
  series="38,52,71,66,87,96"
  variant="outline"
  size="lg"
></pro-data-chart>
```

### 8.4 内部样式策略

不将“任意内部节点 class 覆盖”作为一等 API。  
组件内提供 `data-slot` 作为稳定语义标记（调试/高级覆盖可用），但主推荐路径仍为：

1. `class`
2. `variant` / `size`
3. CSS 变量