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. 项目目录结构

.
├── 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. 如何跑起来

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. 如何新增一个组件（推荐流程）

// 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);
}

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

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

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

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

5.1 打包 SDK

npm run build

会输出：

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

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

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

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

<!-- 组件已自动注册，直接使用即可 -->
<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 按需类型）

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

5.3 在纯 HTML 中使用（UMD）

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

6. 质量与格式命令

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 用户侧定制示例

<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 变量