LiquidUI React

iOS26 风格的液态玻璃 React 组件库，基于 React + TypeScript + Tailwind CSS + Radix UI 构建，内置完整的主题系统与类型定义，适合在 IDE、面板类应用中快速落地精致 UI。

✨ 特性

• 🌈 玻璃拟态 & 亮暗双主题，支持自定义 CSS 变量
• ⚛️ React + TypeScript，全量类型提示
• 🧱 收录 Button / Card / Input / Select / Cascader / Collapse / Dialog / ConfirmDialog / Spinner / Toast 等常用组件
• 🛡 基于 Radix UI primitives，A11y 友好
• 🎨 Tailwind 原子化样式，支持类名覆盖
• 📦 npm dist/ 同时包含 ESM、UMD 与 .d.ts

📦 安装

# npm
npm install liquid-ui-react

# pnpm
pnpm add liquid-ui-react

# bun
bun add liquid-ui-react

库将 React、ReactDOM 设为 peerDependencies，请确保主工程已安装。

🚀 快速上手

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "liquid-ui-react/dist/style.css"; // 或者手动引入 assets/index.css
import { Button, Card, CardContent, CardHeader, CardTitle } from "liquid-ui-react";

function App() {
  return (
    <main className="min-h-screen bg-linear-to-b from-slate-100 to-white glass p-8">
      <Card className="max-w-md">
        <CardHeader>
          <CardTitle>欢迎使用 LiquidUI</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <p>这是一个卡片组件示例。</p>
          <Button>点击我</Button>
        </CardContent>
      </Card>
    </main>
  );
}

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

如果希望使用自定义主题变量，可直接复制 src/assets/index.css 到宿主项目并按需调整。

📚 组件概览

| 组件 | 说明 | 核心 Props | | ---- | ---- | ---------- | | Button | 通用按钮，提供 variant/size/asChild | variant, size, asChild | | Input | 文本输入框，支持错误态 | 原生 input 属性 (aria-invalid 等) | | Select / SelectField | 自定义下拉选择 & 带 label 的 Field | options, value, onChange, size, error | | Cascader | 多级级联选择器，支持 hover 展开 | options, value, showFullPath, inline | | Card | 内容容器，含 CardHeader/CardContent/CardFooter/CardAction | slot 组织 | | Collapse / CollapsePanel / SimpleCollapse | 折叠面板 + 简化版 | accordion, activeKey, allowOverflow | | Dialog | 基于 Radix 的弹窗 | open, onOpenChange, blurOverlay, showCloseButton | | ConfirmDialog | 自定义确认弹窗 | open, onConfirm, variant | | Spinner | 加载器 | size, fullscreen, tip | | Toast / Toaster / useToast | 轻提示系统 | title, description, duration, action |

更多详尽用法，可查看 docs/UI_COMPONENTS.md 或运行项目本地的 demo 页面。

🧩 典型用例

1. SelectField + Input 组合

import { SelectField, Input } from "liquid-ui-react";

<SelectField
  label="Favorite Framework"
  helperText="选择你最常用的框架"
  options={[
    { value: "react", label: "React" },
    { value: "vue", label: "Vue" },
  ]}
  value={framework}
  onChange={setFramework}
/>
<Input aria-invalid={!projectName} placeholder="项目名称" />

2. Dialog & ConfirmDialog

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
} from "liquid-ui-react";
import ConfirmDialog from "liquid-ui-react/dist/components/ui/ConfirmDialog";

<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger asChild>
    <Button>新建工程</Button>
  </DialogTrigger>
  <DialogContent blurOverlay>
    <DialogHeader>
      <DialogTitle>创建新工程</DialogTitle>
      <DialogDescription>填写信息后点击创建。</DialogDescription>
    </DialogHeader>
    {/* ...content */}
    <DialogFooter>
      <Button variant="ghost">取消</Button>
      <Button>创建</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

<ConfirmDialog
  open={confirmOpen}
  onOpenChange={setConfirmOpen}
  title="危险操作"
  description="确认删除该工作区？"
  confirmText="确认删除"
  cancelText="再想想"
  variant="destructive"
  onConfirm={handleDelete}
/>

3. Toast 系统

import { Button } from "liquid-ui-react";
import { ToastAction, Toaster, useToast } from "liquid-ui-react";

function Example() {
  const { toast } = useToast();
  return (
    <>
      <Button
        onClick={() =>
          toast({
            title: "构建成功",
            description: "产物已上传，可点此回滚。",
            action: <ToastAction altText="Undo deploy">撤销</ToastAction>,
          })
        }
      >
        触发 Toast
      </Button>
      <Toaster />
    </>
  );
}

🛠 脚本

npm run dev        # 本地示例
npm run build      # IDE 应用打包
npm run build:lib  # 打包 npm 库 (ESM + UMD + d.ts)
npm run lint       # ESLint

🔧 发布指引

1. npm run build:lib
2. npm pack --dry-run 确认包内容
3. npm publish --access public

包名与版本已在 package.json 中配置，确保版本号递增即可。

📄 License

MIT © 2025 LiquidUI Team