# bolt-ui

A Nuxt 4 component library for the homepage and admin UI. Built on Vue 3.5 with TypeScript and SCSS.

## Auto-Registration

When used via the `bolt-ui/nuxt` module (already wired in `nuxt.config.ts`), components and composables under this package are auto-registered globally:

- Components at `components/<Name>/index.ts` are available as `<BoName>` (e.g. `components/Button/index.ts` → `<BoButton>`)
- Composables exporting `useXxx` functions under `hooks/`, `utils/`, or `locales/` are auto-imported (e.g. `hooks/useClickOutside/index.ts` exports `useClickOutside`)
- Theme styles are auto-injected on first use of each component

## Components

| Name | Description |
|------|-------------|
| `BoButton` | Standard button with type / size / loading / disabled variants |
| `BoConfigProvider` | Provides design tokens and locale to descendants |
| `BoContainer` | Centered max-width container with size variants |
| `BoDialog` | Modal dialog with Teleport + Mask + Transition |
| `BoDrawer` | Side-sliding panel (left/right) with mask, focus trap, and body scroll lock |
| `BoMask` | Full-screen mask overlay |

## Drawer 抽屉

从屏幕边缘滑出的面板，常用于移动端侧栏、设置面板、通知中心等场景。

### 基础用法

```vue
<BoDrawer v-model:open="open" side="left" width="80%">
  <div class="my-panel">面板内容</div>
</BoDrawer>
```

### Props

| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `open` | `boolean` | — | 是否打开，配合 `v-model:open` 双向绑定 |
| `side` | `'left' \| 'right'` | `'left'` | 滑出方向 |
| `width` | `string \| number` | `'80%'` | 面板宽度；数字视为 px |
| `closeOnMask` | `boolean` | `true` | 点击遮罩是否关闭 |
| `closeOnEsc` | `boolean` | `true` | 按 Esc 是否关闭 |
| `showMask` | `boolean` | `true` | 是否显示遮罩 |
| `zIndex` | `number` | `200` | 面板 z-index |
| `transitionDuration` | `number` | `280` | 过渡时长 (ms) |
| `teleportTo` | `string` | `'body'` | Teleport 目标选择器 |
| `ariaLabel` | `string` | `'抽屉'` | ARIA 标签 |

### Emits

| 事件 | 参数 | 说明 |
|------|------|------|
| `update:open` | `(value: boolean)` | 由 `v-model:open` 监听 |

### 行为

- 打开时锁定 `body` 滚动，关闭时恢复
- 自动焦点管理：打开时聚焦面板内第一个可聚焦元素，关闭时返回触发器
- 内置焦点陷阱（Tab / Shift+Tab 在面板内循环）
- Teleport 到 `body`，避免父级 `overflow: hidden` / `transform` 影响
- SSR 安全：服务端不渲染 Teleport，客户端 `onMounted` 后挂载

## Composables

### useMediaQuery

```ts
const isMobile = useMediaQuery('(max-width: 767.98px)')
```

响应式地跟踪媒体查询匹配状态。SSR 期间返回 `false`，客户端 mount 后由 `matchMedia` 真实驱动，自动清理监听。

### useClickOutside

```ts
useClickOutside(elementRef, (event) => {
  // triggered when click is outside elementRef
}, { ignore: [someOtherRef] })
```

监听元素外部的点击事件，可选地忽略某些元素。SSR 期间无操作，客户端 mount 后挂载。