nuxt-app/packages/bolt-ui/README.md

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
BoChatBubble	Chat message bubble with user/assistant variants, simple Markdown rendering, and typing indicator

Drawer 抽屉

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

基础用法

<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

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

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

useClickOutside

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

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

ChatBubble 聊天气泡

通用聊天气泡组件，支持用户/助手两种角色，内置简易 Markdown 渲染和打字指示器。

基础用法

<BoChatBubble role="user" content="你好" />
<BoChatBubble role="assistant" content="**你好！** 有什么可以帮你的？" />
<BoChatBubble role="assistant" :loading="true" />

Props

名称	类型	默认值	说明
role	'user' | 'assistant'	—	消息角色，决定气泡方向和样式
content	string	''	消息文本内容，支持简易 Markdown（code、bold、换行）
loading	boolean	false	是否显示打字指示器（三点动画）

Slots

名称	说明
default	自定义消息内容，覆盖 content 渲染
avatar	自定义头像，覆盖默认图标