@sparqjs/site-ui 0.2.2

package/README.md

@@ -0,0 +1,46 @@
+# Sparq Site UI
+
+`@sparqjs/site-ui` 为 Sparq Website 主题和普通服务端 HTML 页面提供框架无关的公共样式与交互。它不依赖 Vue、Element Plus 或 Admin Shell，也不包含市场卡片、账户工作台等业务页面组件。
+
+组件规范见 [COMPONENT-SPEC.md](./COMPONENT-SPEC.md)，Demo 按场景运行：`pnpm run demo:dev`。
+
+```ts
+import { sparqUI as squi } from '@sparqjs/site-ui'
+import '@sparqjs/site-ui/style.css'
+
+const accepted = await squi.confirm({
+    title: '删除发票抬头',
+    message: '删除后不能恢复，已有发票不会受影响。',
+    confirmLabel: '确认删除',
+    tone: 'danger',
+})
+
+squi.success('主题资源已经同步。')
+squi.error('无法连接到部署服务。', { duration: 6000 })
+```
+
+公开命名统一使用 `.sparq-*`、`--sparq-*` 和 `data-sparq-*`。主题通过覆盖语义变量调整品牌外观，不应复制组件内部状态样式。
+
+默认视觉参考 Tabler 的产品界面语言：中性页面表面、清晰细边框、紧凑控件和克制阴影。该参考只影响默认 token 与组件质感，公开 API 不依赖 Tabler 的类名或运行时代码。
+
+## 公共 API
+
+- 按钮：`.sparq-button`，以及 `--secondary`、`--danger`、`--ghost`、`--sm`、`--lg`、`--block`、`--icon` 修饰类。
+- 表单：`.sparq-form`、`.sparq-field`、`.sparq-label`、`.sparq-control`、`.sparq-select`、`.sparq-textarea` 和字段帮助、错误状态。
+- 选择控件：`.sparq-check`、`.sparq-radio`、`.sparq-switch`、`.sparq-choice-input`、`.sparq-switch-input`。
+- 组合控件：`.sparq-input-group`、`.sparq-input-icon`、`.sparq-form-actions`。
+- 表单补充：`.sparq-form-row`、`.sparq-form-row--columns-1` 至 `.sparq-form-row--columns-6`、`.sparq-form-row--one`、`.sparq-form-row--two`、`.sparq-field--horizontal`、`.sparq-fieldset`、`.sparq-input-addon`、`.sparq-range`、`.sparq-file`、`.sparq-required` 和 `.sparq-error-summary`。
+
+表单行默认使用 Flex 自适应换行；需要明确列数时，在行上使用 `sparq-form-row--columns-3` 或 `sparq-form-row--columns-5`。左标签布局使用 `sparq-field--horizontal`，可通过 `--sparq-form-label-width: 7rem` 和 `--sparq-form-label-align: end` 调整标签宽度与对齐方式。`--sparq-form-row-gap` 可调整字段列间距。
+- 前台展示：`.sparq-card`、`.sparq-badge` 和 `.sparq-avatar`。
+- 导航：`.sparq-breadcrumb`、`.sparq-tabs`、`.sparq-pagination`、`.sparq-button-group` 和 `.sparq-toolbar`。
+- 反馈与加载：`.sparq-alert`、`.sparq-empty`、`.sparq-progress`、`.sparq-spinner` 和 `.sparq-skeleton`。
+- 布局：`.sparq-container`、`.sparq-stack`、`.sparq-cluster`、`.sparq-grid`、`.sparq-sidebar-layout`。
+- 弹层：`.sparq-dialog`、`data-sparq-dialog-open`、`data-sparq-dialog-close` 和 `squi.open()`、`squi.close()`、`squi.confirm()`。
+- 菜单：`.sparq-dropdown`、`.sparq-dropdown__menu`、`.sparq-dropdown__item`、`data-sparq-dropdown-toggle`，以及 `squi.dropdown.open()`、`squi.dropdown.close()`。
+- Toast：`.sparq-toast-region`、`.sparq-toast` 和 `squi.toast()`；完整调用使用对象参数，也提供 `squi.info()`、`squi.success()`、`squi.warning()` 和 `squi.error()` 快捷方法。默认 4 秒关闭，顶部进度条显示剩余时间，悬停或聚焦时暂停并从剩余时间继续，`duration: 0` 可保持显示且不渲染倒计时条。
+- UI 实例：`createSparqUI()` 创建隔离实例，`sparqUI` 提供默认懒加载实例；实例支持 `mount()`、`use()` 插件、Toast、Dialog/Confirm 操作和 `destroy()` 生命周期。
+
+Dropdown 触发器必须提供 `aria-controls` 并指向同一 `.sparq-dropdown` 内的菜单。`mount()` 会统一处理点击、外部点击、方向键、Home、End、Tab、Escape 和焦点恢复。
+
+业务主题可以用 `.sqw-*` 定义页面布局和内容表达，但不能重新实现以上组件的基础边框、焦点、禁用、加载或危险状态。