@xyhp915/slack-base-ui 0.0.1 → 0.0.3

package/README.md

@@ -125,6 +125,7 @@ npm run preview
 - 带有遮罩层和优雅的进入/退出动画
 - 支持子组件：`DialogBody`、`DialogFooter`、`DialogClose`
 - 完整的键盘导航和焦点管理
+- **命令式调用**：`DialogProvider` + `useDialog()` hook，支持 `show` / `confirm` / `alert` 三种模式
 
 ### AlertDialog - 警告对话框
 - 基于 Base UI 的 `Dialog` 组件
@@ -158,6 +159,7 @@ npm run preview
 - 支持四个方向和对齐方式配置
 - 提供便捷组件：`PopoverHeader`、`PopoverBody`、`PopoverFooter`
 - 支持受控和非受控模式
+- **命令式调用**：`ImperativePopoverProvider` + `useImperativePopover()` hook，可将 Popover 锚定到任意元素
 - [详细文档](./docs/POPOVER_MENU_CONTEXTMENU.md#popover-组件)
 
 ### Menu - 下拉菜单
@@ -291,14 +293,228 @@ function ConfirmDialog() {
 }
 ```
 
+## 🚀 命令式 API
+
+Dialog 和 Popover 均支持不依赖声明式 JSX、直接用代码调用的**命令式 API**，使用方式与 `useToast()` 完全一致。
+
+### 1. 注册 Provider
+
+在应用根节点（`main.tsx`）包裹对应的 Provider：
+
+```tsx
+// main.tsx
+import { DialogProvider } from './components/Dialog'
+import { ImperativePopoverProvider } from './components/Popover'
+
+createRoot(document.getElementById('root')!).render(
+  <ThemeProvider>
+    <ToastProvider>
+      <DialogProvider>
+        <ImperativePopoverProvider>
+          <App />
+        </ImperativePopoverProvider>
+      </DialogProvider>
+    </ToastProvider>
+  </ThemeProvider>
+)
+```
+
+---
+
+### 2. useDialog — 命令式对话框
+
+在任意子组件中调用 `useDialog()`，获得三个返回 Promise 的方法：
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `show(options)` | `Promise<void>` | 通用弹窗，关闭后 resolve |
+| `confirm(options)` | `Promise<boolean>` | 确认弹窗，确认 → `true`，取消/关闭 → `false` |
+| `alert(options)` | `Promise<void>` | 仅有 OK 按钮的提示弹窗，点击后 resolve |
+
+#### 通用弹窗 `show`
+
+```tsx
+import { useDialog } from './components/Dialog'
+
+function MyComponent() {
+  const { show } = useDialog()
+
+  const handleOpen = async () => {
+    await show({
+      title: '快捷设置',
+      content: <SettingsForm />,
+      size: 'md',
+    })
+    console.log('弹窗已关闭')
+  }
+
+  return <Button onClick={handleOpen}>打开设置</Button>
+}
+```
+
+#### 确认弹窗 `confirm`
+
+```tsx
+import { useDialog } from './components/Dialog'
+
+function DeleteButton({ onDelete }: { onDelete: () => void }) {
+  const { confirm } = useDialog()
+
+  const handleClick = async () => {
+    const ok = await confirm({
+      title: '确认删除频道？',
+      description: '此操作不可撤销，频道内所有消息将永久删除。',
+      confirmLabel: '删除',
+      cancelLabel: '取消',
+      confirmVariant: 'danger',
+    })
+    if (ok) onDelete()
+  }
+
+  return <Button variant="danger" onClick={handleClick}>删除频道</Button>
+}
+```
+
+#### 提示弹窗 `alert`
+
+```tsx
+import { useDialog } from './components/Dialog'
+
+function SubmitForm() {
+  const { alert } = useDialog()
+
+  const handleSubmit = async () => {
+    try {
+      await submitData()
+    } catch {
+      await alert({
+        title: '提交失败',
+        description: '服务器出现错误，请稍后再试。',
+      })
+    }
+  }
+
+  return <Button onClick={handleSubmit}>提交</Button>
+}
+```
+
+#### `show` 完整选项
+
+```ts
+interface ShowDialogOptions {
+  title?: string           // 对话框标题
+  description?: string     // 标题下方的副文本
+  content?: React.ReactNode // 自定义正文内容
+  size?: 'sm' | 'md' | 'lg' | 'xl'
+  showCloseButton?: boolean // 是否显示右上角关闭按钮，默认 true
+  className?: string
+}
+```
+
+#### `confirm` 完整选项
+
+```ts
+interface ConfirmDialogOptions {
+  title?: string
+  description?: string
+  content?: React.ReactNode
+  size?: 'sm' | 'md' | 'lg' | 'xl'
+  confirmLabel?: string                          // 默认 'Confirm'
+  cancelLabel?: string                           // 默认 'Cancel'
+  confirmVariant?: 'primary' | 'danger' | 'secondary'  // 默认 'primary'
+}
+```
+
+#### `alert` 完整选项
+
+```ts
+interface AlertDialogOptions {
+  title?: string
+  description?: string
+  content?: React.ReactNode
+  size?: 'sm' | 'md' | 'lg' | 'xl'
+  confirmLabel?: string  // 默认 'OK'
+}
+```
+
+---
+
+### 3. useImperativePopover — 命令式浮层
+
+在任意子组件中调用 `useImperativePopover()`，可以将 Popover 锚定到任意 DOM 元素上弹出，无需在 JSX 中手动组合 `<Popover>` + `<PopoverTrigger>`。
+
+全局单例模式：同一时刻只显示一个命令式 Popover。
+
+| 方法 / 属性 | 说明 |
+|-------------|------|
+| `show(anchor, options)` | 在指定元素旁弹出 Popover |
+| `hide()` | 关闭当前 Popover |
+| `toggle(anchor, options)` | 同一锚点再次调用时关闭，否则打开 |
+| `isOpen` | 当前是否处于打开状态 |
+
+#### 基础用法
+
+```tsx
+import { useImperativePopover } from './components/Popover'
+
+function UserCard({ user }: { user: User }) {
+  const popover = useImperativePopover()
+
   return (
-    <Tooltip content="Click to send message">
-      <Button variant="primary">Send</Button>
-    </Tooltip>
-  );
+    <button
+      onClick={e =>
+        popover.show(e.currentTarget, {
+          content: <ProfilePanel user={user} />,
+          side: 'bottom',
+          align: 'start',
+        })
+      }
+    >
+      {user.name}
+    </button>
+  )
+}
+```
+
+#### Toggle 用法（点击再次关闭）
+
+```tsx
+function SettingsButton() {
+  const popover = useImperativePopover()
+
+  return (
+    <IconButton
+      onClick={e =>
+        popover.toggle(e.currentTarget, {
+          content: <SettingsPanel onClose={popover.hide} />,
+          side: 'bottom',
+          align: 'end',
+          sideOffset: 4,
+        })
+      }
+      active={popover.isOpen}
+    >
+      <Settings size={16} />
+    </IconButton>
+  )
+}
+```
+
+#### `show` / `toggle` 完整选项
+
+```ts
+interface ImperativePopoverOptions {
+  content: React.ReactNode    // 弹出内容（必填）
+  side?: 'top' | 'right' | 'bottom' | 'left'  // 默认 'bottom'
+  align?: 'start' | 'center' | 'end'          // 默认 'center'
+  sideOffset?: number    // 与锚点的间距，默认 8
+  alignOffset?: number   // 对齐方向偏移，默认 0
+  className?: string     // 自定义弹出层样式
 }
 ```
 
+---
+
 ## 🎬 演示页面
 
 项目包含三个主要页面：

package/agents/slack-base-ui/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: slack-base-ui
+description: Use this skill whenever a React/Vite project is building with, migrating to, reviewing, or styling around the package @xyhp915/slack-base-ui. It enforces package-level Slack visual consistency, root theme tokens, and component-first adoption rules.
+---
+
+# `@xyhp915/slack-base-ui`
+
+This skill is the authoritative guide for AI work involving the UI library `@xyhp915/slack-base-ui`.
+
+## When to use this skill
+
+Use this skill whenever the task involves any of the following:
+
+- adding `@xyhp915/slack-base-ui` to a project
+- generating pages or components that import from `@xyhp915/slack-base-ui`
+- refactoring an existing UI to adopt this library
+- reviewing a project that already depends on `@xyhp915/slack-base-ui`
+- fixing visual drift in a project that should look like Slack
+
+## Non-negotiable rules
+
+1. **Use the package name exactly as published:** `@xyhp915/slack-base-ui`.
+2. **Any project that uses this library must keep a unified Slack-style visual language.** Do not mix in Material, shadcn, Ant Design, iOS-glass, neon cyberpunk, or unrelated brand aesthetics.
+3. **Set the root theme color to Slack** by applying `data-theme-color="slack"` on `document.documentElement`.
+4. **Dark mode uses the root `.dark` class** on `document.documentElement`.
+5. **Prefer library components first** (`Button`, `Input`, `Dialog`, `Menu`, `Popover`, `Tabs`, `Toast`, etc.) before creating parallel bespoke UI primitives.
+6. **Style through Slack-aligned CSS variables** instead of hard-coded one-off colors.
+7. **Do not switch to `blue`, `green`, or `aubergine` theme-color modes** in consuming apps unless the user explicitly asks to break the unified Slack style rule.
+
+## Verified library facts from the source project
+
+- Package identity is declared in `package.json` as `@xyhp915/slack-base-ui`.
+- The library build entry currently points to `src/components/index.ts` via `vite.libs.config.ts`.
+- The public component surface includes foundational components like `Button`, `Avatar`, `Badge`, `Input`, `IconButton`, `Tooltip`, `Dialog`, `AlertDialog`, `Form`, `Select`, `Checkbox`, `Radio`, `Switch`, `Tabs`, `Progress`, `Toast`, `Loading`, `AutoComplete`, `Popover`, `Menu`, and `ContextMenu`.
+- Slack design tokens live in the source project's `src/index.css`.
+- The source app's internal `ThemeProvider` writes both the root `.dark` class and the `data-theme-color` attribute.
+- The current library output is component-focused; do **not** assume the published package automatically injects global Slack theme CSS for consumers.
+
+## Default AI workflow
+
+### 1. Detect adoption state
+
+Check whether the target app already:
+
+- lists `@xyhp915/slack-base-ui` in dependencies
+- has global CSS tokens for Slack colors and surfaces
+- sets `document.documentElement.dataset.themeColor = 'slack'`
+- uses the root `.dark` class for dark mode
+
+### 2. Establish the Slack theme foundation first
+
+Before adding pages or components, make sure the consuming app has:
+
+- a global Slack token file
+- root theme initialization
+- Slack-like typography, radius, borders, backgrounds, and focus ring
+
+If missing, use the reference template in `templates/slack-theme.css` and the integration guide in `templates/consumer-setup.md`.
+
+### 3. Build with package primitives
+
+Prefer imports such as:
+
+```tsx
+import { Button, Input, Dialog, Avatar, Menu, Tabs } from '@xyhp915/slack-base-ui'
+```
+
+When composing new UI:
+
+- keep layout dense and productivity-oriented
+- use subdued surfaces and clear borders
+- use Slack aubergine/sidebar accents sparingly and intentionally
+- use green action emphasis and blue selection/focus emphasis
+
+### 4. Prevent visual drift
+
+Reject or replace:
+
+- oversized rounded "pill everywhere" styling
+- glassmorphism and heavy backdrop blur as a default language
+- pastel gradients as primary surfaces
+- over-animated interaction patterns
+- random per-page color systems unrelated to Slack tokens
+
+### 5. Review before finishing
+
+Run the checklist in `checklists/style-review.md` before concluding work.
+
+## Required styling contract for consumer apps
+
+Any consumer app using `@xyhp915/slack-base-ui` should satisfy all of these:
+
+- root has `data-theme-color="slack"`
+- dark mode toggles `.dark` on `<html>`
+- app-level global CSS defines the Slack token set used by the library
+- custom components continue using the same token family (`--bg-primary`, `--text-primary`, `--accent`, `--accent-action`, `--sidebar-bg`, etc.)
+- app shells, sidebars, lists, dialogs, menus, and inputs visually match the Slack system
+
+## Minimal integration pattern
+
+```tsx
+import { useEffect } from 'react'
+
+export function SlackThemeBootstrap() {
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme-color', 'slack')
+  }, [])
+
+  return null
+}
+```
+
+For full guidance, use `templates/consumer-setup.md`.
+
+## Decision rules for AI
+
+- If the user asks for a new screen in a consumer app, implement it with `@xyhp915/slack-base-ui` components first.
+- If the app already has a conflicting design system, migrate or wrap it toward Slack consistency rather than mixing systems.
+- If custom CSS is required, write it with the Slack token names from this skill.
+- If the user asks for branding changes that would break Slack consistency, call that out explicitly and only proceed if the user wants to override the library standard.
+
+## References inside this skill
+
+- `templates/slack-theme.css`
+- `templates/consumer-setup.md`
+- `checklists/style-review.md`
+
+## Output expectation
+
+When you finish a task involving this package, the result should:
+
+1. import from `@xyhp915/slack-base-ui`
+2. keep a consistent Slack-style UI across the project
+3. preserve the root theme contract (`data-theme-color="slack"`, optional `.dark`)
+4. avoid aesthetic drift from the library's design system
+
+

package/agents/slack-base-ui/checklists/style-review.md

@@ -0,0 +1,56 @@
+# Slack Base UI style review checklist
+
+Use this checklist before finishing any task in a project that depends on `@xyhp915/slack-base-ui`.
+
+## Package and component usage
+
+- [ ] Imports come from `@xyhp915/slack-base-ui` where equivalent primitives already exist.
+- [ ] No parallel button/input/dialog/menu primitives were added without a clear reason.
+- [ ] New UI uses the library's public component surface before inventing custom controls.
+
+## Theme contract
+
+- [ ] `document.documentElement` uses `data-theme-color="slack"`.
+- [ ] Dark mode, if supported, uses the root `.dark` class.
+- [ ] Global CSS includes Slack-compatible tokens required by the library.
+- [ ] Custom styles still read from CSS variables rather than hard-coded palette values.
+
+## Visual consistency
+
+- [ ] Sidebars, headers, lists, forms, dialogs, menus, and buttons feel like one Slack-style system.
+- [ ] Primary actions use Slack-style action emphasis instead of arbitrary gradients.
+- [ ] Focus states are visible and token-driven.
+- [ ] Border radius, spacing density, and typography remain productivity-oriented rather than overly playful.
+- [ ] No off-brand aesthetics were introduced: glassmorphism, random gradients, neon effects, or unrelated component-library styling.
+
+## Root tokens to verify
+
+At minimum, confirm the host app defines these tokens:
+
+- `--accent`
+- `--accent-hover`
+- `--accent-action`
+- `--accent-action-hover`
+- `--accent-contrast`
+- `--bg-primary`
+- `--bg-secondary`
+- `--bg-hover`
+- `--bg-muted`
+- `--text-primary`
+- `--text-secondary`
+- `--text-muted`
+- `--border-light`
+- `--border-active`
+- `--border-subtle`
+- `--sidebar-bg`
+- `--sidebar-text`
+- `--sidebar-text-active`
+- `--sidebar-item-hover`
+- `--sidebar-item-active`
+- `--focus-ring`
+- `--danger`
+- `--danger-hover`
+
+## Final acceptance rule
+
+If the package `@xyhp915/slack-base-ui` is present, the finished UI should read as a Slack-style product by default.

package/agents/slack-base-ui/templates/consumer-setup.md

@@ -0,0 +1,109 @@
+# Consumer app setup for `@xyhp915/slack-base-ui`
+
+Use this template when adding the library to a React/Vite app.
+
+## 1. Install the package
+
+```bash
+npm install @xyhp915/slack-base-ui
+```
+
+## 2. Add a global Slack theme stylesheet
+
+Create or update your app-level global CSS and base it on `templates/slack-theme.css` from this skill.
+
+Note: Here is the correct way to load tailwind external contents.
+
+```css
+@source "../node_modules/@xyhp915/slack-base-ui/libs/*.{js,jsx,ts,tsx}";
+```
+
+Example import from your app entry:
+
+```tsx
+import './slack-theme.css'
+import './index.css'
+```
+
+## 3. Bootstrap the root theme contract
+
+Add a tiny initializer so the host app always uses the Slack theme mode expected by the library:
+
+```tsx
+import { useEffect } from 'react'
+
+export function SlackThemeBootstrap () {
+  useEffect(() => {
+    const root = document.documentElement
+    root.setAttribute('data-theme-color', 'slack')
+
+    if (!root.classList.contains('light') && !root.classList.contains('dark')) {
+      root.classList.add('light')
+    }
+  }, [])
+
+  return null
+}
+```
+
+Mount it near the top of the app:
+
+```tsx
+import { SlackThemeBootstrap } from './SlackThemeBootstrap'
+
+export function AppShell () {
+  return (
+      <>
+        <SlackThemeBootstrap/>
+        <App/>
+      </>
+  )
+}
+```
+
+## 4. Use library components before custom primitives
+
+```tsx
+import { Avatar, Button, Dialog, Input, Tabs } from '@xyhp915/slack-base-ui'
+
+export function ChannelInviteDialog () {
+  return (
+      <div className="flex flex-col gap-4 bg-(--bg-primary) text-(--text-primary)">
+        <div className="flex items-center gap-3">
+          <Avatar fallback="CD" status="online"/>
+          <div>
+            <div className="font-bold">Charlie Day</div>
+            <div className="text-sm text-(--text-secondary)">Design Systems</div>
+          </div>
+        </div>
+
+        <Input label="Invite by email" placeholder="teammate@example.com" fullWidth/>
+
+        <div className="flex justify-end gap-2">
+          <Button variant="secondary">Cancel</Button>
+          <Button variant="primary">Send invite</Button>
+        </div>
+      </div>
+  )
+}
+```
+
+## 5. Dark mode rule
+
+If you support dark mode, toggle `.dark` on `document.documentElement`.
+Do not switch `data-theme-color` away from `slack` unless the user explicitly asks to override the design system.
+
+## 6. What to avoid
+
+Avoid these patterns in a consumer app that uses `@xyhp915/slack-base-ui`:
+
+- mixing in unrelated component libraries for core primitives
+- introducing non-Slack palettes as the default theme
+- replacing token-driven colors with hard-coded brand colors per page
+- using decorative gradients, glass effects, or oversized playful spacing as the baseline UI language
+
+## 7. Important implementation note
+
+Based on the current source project, the library build is centered on component exports. Do not assume the package will
+automatically provide the host app with global Slack CSS; make sure the consuming project owns that global theme layer
+explicitly.

package/agents/slack-base-ui/templates/slack-theme.css

@@ -0,0 +1,152 @@
+/* Host-app Slack theme template for @xyhp915/slack-base-ui */
+/* Keep this file global. The consuming app should not swap to a non-Slack baseline unless explicitly requested. */
+
+:root {
+  --slack-aubergine: #3f0e40;
+  --slack-aubergine-dark: #350d36;
+  --slack-blue: #1164a3;
+  --slack-green: #007a5a;
+  --slack-green-hover: #148567;
+  --slack-red: #e01e5a;
+
+  --accent: var(--slack-blue);
+  --accent-hover: #0b4c7a;
+  --accent-contrast: #ffffff;
+  --accent-action: var(--slack-green);
+  --accent-action-hover: var(--slack-green-hover);
+  --focus-ring: var(--accent);
+  --danger: var(--slack-red);
+  --danger-hover: #bd1546;
+  --badge-neutral: #616061;
+
+  --bg-primary: #ffffff;
+  --bg-secondary: #f8f8f8;
+  --bg-hover: #f2f2f2;
+  --bg-muted: #f6f6f6;
+
+  --text-primary: #1d1c1d;
+  --text-secondary: #616061;
+  --text-muted: #868686;
+
+  --border-light: #dddddd;
+  --border-gray: #767676;
+  --border-active: #dddddd;
+  --border-subtle: #e6e6e6;
+
+  --sidebar-bg: var(--slack-aubergine);
+  --sidebar-text: #cfc3cf;
+  --sidebar-text-active: #ffffff;
+  --sidebar-item-hover: #350d36;
+  --sidebar-item-active: #1164a3;
+
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+
+  --font-family: 'Lato', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+  --font-size-sm: 13px;
+  --font-size-md: 15px;
+  --font-size-lg: 18px;
+
+  --radius-sm: 3px;
+  --radius: 6px;
+  --radius-md: 8px;
+  --radius-lg: 10px;
+  --radius-xl: 14px;
+  --radius-2xl: 16px;
+  --radius-full: 9999px;
+}
+
+:root[data-theme-color='slack'] {
+  --accent: var(--slack-blue);
+  --accent-hover: #0b4c7a;
+  --accent-action: var(--slack-green);
+  --accent-action-hover: var(--slack-green-hover);
+}
+
+:root.dark {
+  --slack-aubergine: #19171d;
+  --slack-aubergine-dark: #121016;
+
+  --bg-primary: #1a1d21;
+  --bg-secondary: #222529;
+  --bg-hover: #2c3036;
+  --bg-muted: #16191d;
+
+  --text-primary: #d1d2d3;
+  --text-secondary: #abacae;
+  --text-muted: #858688;
+
+  --border-light: #363a3e;
+  --border-active: transparent;
+  --border-subtle: #454545;
+  --border-gray: #404040;
+
+  --sidebar-bg: #19171d;
+  --sidebar-text: #abacae;
+  --sidebar-text-active: #ffffff;
+  --sidebar-item-hover: #27242c;
+  --sidebar-item-active: #1164a3;
+}
+
+html {
+  color-scheme: light;
+}
+
+html.dark {
+  color-scheme: dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  padding: 0;
+  font-family: var(--font-family), serif;
+  color: var(--text-primary);
+  background-color: var(--bg-primary);
+  -webkit-font-smoothing: subpixel-antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+input:focus-visible,
+textarea:focus-visible,
+button:focus-visible,
+[role='button']:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--focus-ring) 35%, transparent);
+  outline-offset: 1px;
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--focus-ring) 40%, transparent);
+}
+
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.1);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.2);
+}
+
+:root.dark ::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+:root.dark ::-webkit-scrollbar-thumb:hover {
+  background: rgba(255, 255, 255, 0.2);
+}
+