blatui

🧩 这是 BlatUI 单体仓库。 Composer 包位于仓库根目录（src/ + stubs/） — Packagist 会直接读取该目录，因此 composer require anousss007/blatui 保持不变， 且 apps/ 会从 dist 压缩包中剔除。组件在 apps/demo/ 中编写，然后生成到 stubs/。编辑组件前，请参阅贡献指南。

---

为什么选择 BlatUI

• 默认支持无障碍。 提供 WAI-ARIA 角色、完整的键盘导航与焦点管理，以及符合 WCAG AA 的颜色对比度——以 shadcn/ui 的 Base UI 行为为蓝本，经真实浏览器验证并使用 axe-core 审核。无障碍不是附加功能，而是每个组件都内置的能力。
• 代码归你所有。 组件会复制到你的项目中，而不是藏在 vendor/ 里。你可以随意编辑；更新此包永远不会覆盖你的修改。
• BLAT 技术栈。 纯 Blade 组件，搭配少量 Alpine.js 实现交互，并使用 Tailwind CSS v4 进行样式设计。无需 React，也不会被构建步骤绑定。
• 支持 Livewire。 wire:model 可用于所有表单控件——输入框、选择框、复选框、开关、滑块、日期/时间选择器、文件上传等——并提供完整的双向绑定。这是 Flux Pro 的免费替代方案，代码归你所有。查看 Livewire 指南 →
• 忠于 shadcn/ui。 保留相同的设计语言、组件 API 和区块，并以 Laravel 的方式移植。
• 主题化能力深入核心。 每个设计令牌都是 CSS 变量。

要求

• PHP 8.2+ · Laravel 11、12 或 13
• Tailwind CSS v4 · Alpine.js 3 · Node 18+

安装

# 1. Install the CLI
composer require anousss007/blatui

# 2. Peer packages used by the components
composer require gehrisandro/tailwind-merge-laravel mallardduck/blade-lucide-icons
npm install -D alpinejs @alpinejs/anchor @floating-ui/dom @alpinejs/collapse @alpinejs/focus

# 3. Publish the foundations (theme tokens + Alpine/chart/calendar engine)
php artisan vendor:publish --tag=blatui-foundations
#   → resources/css/blatui.css      (oklch design tokens, presets, light/dark)
#   → resources/js/blatui.js        (greenfield bootstrap — boots Alpine for you)
#   → resources/js/blatui-core.js   (engine: registerBlatUI, for apps already running Alpine)

# 4. Verify your setup
php artisan blatui:init

将两个 Vite 入口文件指向已发布的基础文件——替换每个文件的内容：

/* resources/css/app.css */
@import "./blatui.css";

// resources/js/app.js
import "./blatui.js";

blatui.css 包含 Tailwind、设计令牌和 @theme 映射；blatui.js 会启动 Alpine 及其插件，并按需加载 ApexCharts。运行 blatui:init，确认所有内容（软件包、令牌、导入）都已正确配置。

基础文件发布一次后就归你所有——可以调整令牌，不需要图表时也可以移除 图表引擎，等等。blatui:init 会提示你还有哪些内容未配置。

安装到现有项目

所有改动都具有叠加性——无需替换现有文件。

• 需要 Tailwind v4。 BlatUI 使用仅 v4 支持的功能（@theme inline、oklch）。如果使用 Tailwind v3，请先使用 npx @tailwindcss/upgrade 迁移；blatui:init 会检测版本。
• **CSS：**在现有的 app.css 中添加 @import "./blatui.css";，放在 @import "tailwindcss"; 之后。
• **JS — 已经在运行 Alpine？**不要导入 blatui.js（否则会启动第二个 Alpine）。 请改为将 BlatUI 注册到你自己的实例中，并在启动它之前完成注册：

import Alpine from 'alpinejs'
import { registerBlatUI } from './blatui-core.js'

registerBlatUI(Alpine)   // plugins + theme store + chart/calendar engines
window.Alpine = Alpine
Alpine.start()

• **JS — 正在使用 Livewire 或 Flux？**Livewire 会为你打包并启动 Alpine，因此不要 npm install alpinejs（这会导致 Alpine 重复），也不要导入 blatui.js。 只安装插件——npm install -D @alpinejs/anchor @floating-ui/dom @alpinejs/collapse @alpinejs/focus （仅在使用图表时才添加 apexcharts）——然后通过 alpine:init 钩子将 BlatUI 注册到 Livewire 的 Alpine：

import { registerBlatUI } from './blatui-core.js'

document.addEventListener('alpine:init', () => {
    registerBlatUI(window.Alpine)
})

BlatUI 会注册一个用于深色模式的 theme store。如果 Flux 已经负责控制深色模式，请传入 registerBlatUI(window.Alpine, { darkMode: false })，避免两者同时切换 .dark。

添加组件

# Add one or more — dependencies are resolved automatically
php artisan blatui:add button card input

# See everything you can add — components, blocks & charts
php artisan blatui:list

# Details for a single component
php artisan blatui:list select

# Everything at once
php artisan blatui:add --all

组件会以 Blade 标签的形式放入 resources/views/components/ui/：

<x-ui.card class="max-w-sm">
    <x-ui.card-header>
        <x-ui.card-title>Welcome back</x-ui.card-title>
        <x-ui.card-description>Sign in to continue.</x-ui.card-description>
    </x-ui.card-header>
    <x-ui.card-content class="space-y-3">
        <x-ui.input type="email" placeholder="[email protected]" />
        <x-ui.button class="w-full">Sign in</x-ui.button>
    </x-ui.card-content>
</x-ui.card>

blatui:add 会显示组件所需的任何额外 composer/npm 包 （例如，图表会引入 apexcharts）。

保持组件为最新版本

复制的文件由你负责，因此升级不会自动进行——blatui:update 会显示更改内容，让你逐个文件决定：

# What would change across everything you have installed?
php artisan blatui:update --dry-run --diff

# Update, confirming each file that differs from the version we ship
php artisan blatui:update

# Just these families, no questions asked (your version is kept as .bak)
php artisan blatui:update button card --force

有差异的文件可能是你自定义的，也可能是过时的副本——磁盘上的信息无法区分两者，因此 BlatUI 绝不会在不展示差异并征求确认的情况下覆盖文件。--force 仍会在每个被替换文件旁写入一个 .bak（使用 --no-backup 可关闭此功能）。新版本中某个组件系列新增的文件会直接添加。

在 resources/views 上运行 Pint 或 Prettier？格式化工具会重写你复制的每个组件的 布局，因此它们都会被识别为已更改。此类文件会单独计为内容相同，仅重新格式化，而 --ignore-whitespace 会将其排除：

php artisan blatui:update --dry-run --ignore-whitespace

CSS/JS 基础文件是通过发布提供的，而非复制——使用 vendor:publish --tag=blatui-foundations --force 重新同步；当引擎版本落后时，blatui:init 会提示你。

区块和图表

区块（仪表盘、侧边栏、登录页面等）和 70 个图表都需要从演示网站复制粘贴——它们是完整页面组合，而非基础组件，因此你可以直接获取所需的确切源码，无需安装：

👉 在在线演示中浏览区块和图表

命令

命令	说明
blatui:init	诊断 — 检查软件包、Tailwind v4、主题令牌以及 Alpine/引擎接线
blatui:list [component]	列出所有组件系列，或查看其中一个系列的详情
blatui:add <components...>	将组件（及依赖项）复制到你的项目中
blatui:update [components...]	比较已安装组件与此版本的差异并更新（--dry-run、--diff、--force、--ignore-whitespace）
blatui:doctor [path]	扫描你的 Blade，查找已知隐患（表单中未指定类型的按钮、未闭合的标签）
blatui:mcp	运行 MCP 服务（stdio），以便 AI 编辑器搜索和安装组件
vendor:publish --tag=blatui-foundations	发布主题 CSS 和 JS 引擎

贡献

BlatUI 是一个单体仓库——一个仓库、一个 PR、一个 CI。Composer 软件包位于仓库根目录； 演示/文档网站和 starter kit 是与其并列的应用（通过 .gitattributes 从已发布的软件包中排除）。

composer.json  src/  stubs/   → the published package (this is what `composer require` gets)
apps/demo/                     → authors AND renders every component; the live docs site
apps/starter/                  → the Laravel starter kit
scripts/build-package.sh       → regenerates stubs/ from apps/demo (CI enforces it)

组件在 apps/demo/resources/views/components/ui/ 中编写（组件仅在此处渲染，因此这里是唯一事实来源）；stubs/ 是生成的——不要手动编辑。修改组件后，运行 bash scripts/build-package.sh 并同时提交两处更改。如果两处内容不一致，CI 会失败。 完整指南：CONTRIBUTING.md。

致谢

BlatUI 是 shadcn/ui 移植到 Laravel/Blade 生态系统的版本。感谢 shadcn 和所有贡献者。 图标由 Lucide 提供。图表由 ApexCharts 提供。

许可证

MIT — 可免费用于个人和商业用途。