create-wervt 0.2.14 → 0.2.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/index.js +2 -0
  2. package/package.json +2 -2
  3. package/template/.claude/skills/nuxt-ui/SKILL.md +85 -243
  4. package/template/.claude/skills/nuxt-ui/references/components.md +184 -313
  5. package/template/.claude/skills/nuxt-ui/references/guidelines/component-selection.md +124 -0
  6. package/template/.claude/skills/nuxt-ui/references/guidelines/conventions.md +372 -0
  7. package/template/.claude/skills/nuxt-ui/references/guidelines/design-system.md +378 -0
  8. package/template/.claude/skills/nuxt-ui/references/guidelines/forms.md +235 -0
  9. package/template/.claude/skills/nuxt-ui/references/layouts/chat.md +140 -77
  10. package/template/.claude/skills/nuxt-ui/references/layouts/dashboard.md +33 -19
  11. package/template/.claude/skills/nuxt-ui/references/layouts/docs.md +23 -12
  12. package/template/.claude/skills/nuxt-ui/references/layouts/editor.md +49 -63
  13. package/template/.claude/skills/nuxt-ui/references/layouts/{page.md → landing.md} +43 -118
  14. package/template/.claude/skills/nuxt-ui/references/recipes/auth.md +162 -0
  15. package/template/.claude/skills/nuxt-ui/references/recipes/data-tables.md +249 -0
  16. package/template/.claude/skills/nuxt-ui/references/recipes/navigation.md +90 -0
  17. package/template/.claude/skills/nuxt-ui/references/recipes/overlays.md +177 -0
  18. package/template/.claude/skills/nuxt-ui-mobile/SKILL.md +38 -10
  19. package/template/.claude/skills/nuxt-ui-mobile/references/identity.md +127 -0
  20. package/template/.claude/skills/nuxt-ui-mobile/references/patterns.md +1 -0
  21. package/template/.claude/skills/nuxt-ui-mobile/references/review-checklist.md +14 -6
  22. package/template/.claude/skills/nuxt-ui-mobile/references/tokens.md +1 -1
  23. package/template/.claude/skills/nuxt-ui-mobile/template/app/assets/css/main.css +9 -9
  24. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ListSection.vue +7 -3
  25. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/NavBar.vue +13 -4
  26. package/template/.claude/skills/nuxt-ui-mobile/template/nuxt.config.ts +2 -1
  27. package/template/AGENTS.md +175 -9
  28. package/template/drizzle/20261005212059_sudden_titania/snapshot.json +46 -25
  29. package/template/golar.config.ts +5 -0
  30. package/template/nuxt.config.ts +7 -0
  31. package/template/package.json +9 -6
  32. package/template/pnpm-workspace.yaml +2 -0
  33. package/template/server/api/example-secret.get.ts +8 -0
  34. package/template/.claude/skills/nuxt-ui/references/composables.md +0 -127
  35. package/template/.claude/skills/nuxt-ui/references/theming.md +0 -427
@@ -1,65 +1,137 @@
1
1
  # Chat Layout
2
2
 
3
- Build AI chat interfaces with message streams, prompts, and Vercel AI SDK integration.
3
+ Build AI chat interfaces with message streams, reasoning, tool calling, and Vercel AI SDK integration.
4
4
 
5
- ## Component tree
5
+ ## When to use
6
6
 
7
- ```
8
- UApp
9
- └── NuxtLayout (dashboard)
10
- └── UDashboardGroup
11
- ├── UDashboardSidebar (conversations)
12
- └── NuxtPage
13
- └── UDashboardPanel
14
- ├── #header → UDashboardNavbar
15
- ├── #body → UContainer → UChatMessages
16
- └── #footer → UContainer → UChatPrompt
17
- └── UChatPromptSubmit
18
- ```
7
+ - AI chatbot interfaces
8
+ - Customer support chat
9
+ - Any conversational UI with streaming responses
19
10
 
20
11
  ## Setup
21
12
 
22
- ### Install AI SDK
13
+ ### Install dependencies
14
+
15
+ **Nuxt:**
23
16
 
24
17
  ```bash
25
- pnpm add ai @ai-sdk/gateway @ai-sdk/vue
18
+ pnpm add ai @ai-sdk/vue @comark/nuxt
19
+ ```
20
+
21
+ **Vue (Vite):**
22
+
23
+ ```bash
24
+ pnpm add ai @ai-sdk/vue @comark/vue
25
+ ```
26
+
27
+ ### Register Comark module
28
+
29
+ **Nuxt:**
30
+
31
+ ```ts [nuxt.config.ts]
32
+ export default defineNuxtConfig({
33
+ modules: [
34
+ '@nuxt/ui',
35
+ '@comark/nuxt'
36
+ ]
37
+ })
38
+ ```
39
+
40
+ **Vue (Vite):** No module registration needed, import directly from `@comark/vue`.
41
+
42
+ > `@comark/nuxt` (or `@comark/vue` for Vue projects) provides the `Comark` component used to render AI responses as streaming Markdown, it incrementally renders tokens as they arrive and automatically enables Nuxt UI's prose components.
43
+
44
+ ### Dark mode for syntax highlighting
45
+
46
+ When using the `highlight` plugin, add the following CSS to your stylesheet:
47
+
48
+ ```css [main.css]
49
+ html.dark .shiki span {
50
+ color: var(--shiki-dark) !important;
51
+ background-color: var(--shiki-dark-bg) !important;
52
+ font-style: var(--shiki-dark-font-style) !important;
53
+ font-weight: var(--shiki-dark-font-weight) !important;
54
+ text-decoration: var(--shiki-dark-text-decoration) !important;
55
+ }
26
56
  ```
27
57
 
28
58
  ### Server endpoint
29
59
 
60
+ These examples target AI SDK v7 (`instructions`, `toUIMessageStream`).
61
+
62
+ Using [Vercel AI Gateway](https://vercel.com/ai-gateway) (recommended):
63
+
30
64
  ```ts [server/api/chat.post.ts]
31
- import { streamText, convertToModelMessages } from 'ai'
32
- import { gateway } from '@ai-sdk/gateway'
65
+ import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
33
66
 
34
67
  export default defineEventHandler(async (event) => {
35
68
  const { messages } = await readBody(event)
36
69
 
37
- return streamText({
38
- model: gateway('openai/gpt-4o-mini'),
39
- system: 'You are a helpful assistant.',
70
+ const result = streamText({
71
+ model: 'anthropic/claude-sonnet-5.5',
72
+ instructions: 'You are a helpful assistant.',
40
73
  messages: await convertToModelMessages(messages)
41
- }).toUIMessageStreamResponse()
74
+ })
75
+
76
+ const stream = toUIMessageStream({ stream: result.stream })
77
+ return createUIMessageStreamResponse({ stream })
42
78
  })
43
79
  ```
44
80
 
81
+ Or with a direct provider (e.g., `pnpm add @ai-sdk/openai`):
82
+
83
+ ```ts [server/api/chat.post.ts]
84
+ import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
85
+ import { openai } from '@ai-sdk/openai'
86
+
87
+ export default defineEventHandler(async (event) => {
88
+ const { messages } = await readBody(event)
89
+
90
+ const result = streamText({
91
+ model: openai('gpt-5-nano'),
92
+ instructions: 'You are a helpful assistant.',
93
+ messages: await convertToModelMessages(messages)
94
+ })
95
+
96
+ const stream = toUIMessageStream({ stream: result.stream })
97
+ return createUIMessageStreamResponse({ stream })
98
+ })
99
+ ```
100
+
101
+ ## Component tree
102
+
103
+ ```
104
+ UDashboardPanel
105
+ ├── #header → UDashboardNavbar
106
+ ├── #body → UContainer → UChatMessages
107
+ │ ├── #part → UChatReasoning, UChatTool, Comark
108
+ │ └── #indicator (loading)
109
+ └── #footer → UContainer → UChatPrompt
110
+ └── UChatPromptSubmit
111
+ ```
112
+
45
113
  ## Full page chat
46
114
 
47
115
  ```vue [pages/chat/[id].vue]
48
116
  <script setup lang="ts">
49
- import { Chat } from '@ai-sdk/vue'
117
+ import { isReasoningUIPart, isTextUIPart, isToolUIPart, getToolName } from 'ai'
118
+ import { useChat } from '@ai-sdk/vue'
119
+ import { isPartStreaming, isToolStreaming } from '@nuxt/ui/utils/ai'
120
+ import highlight from '@comark/nuxt/plugins/highlight'
50
121
 
51
122
  definePageMeta({ layout: 'dashboard' })
52
123
 
53
124
  const input = ref('')
54
125
 
55
- const chat = new Chat({
126
+ const { messages, status, error, sendMessage, stop, regenerate } = useChat({
56
127
  onError(error) {
57
128
  console.error(error)
58
129
  }
59
130
  })
60
131
 
61
132
  function onSubmit() {
62
- chat.sendMessage({ text: input.value })
133
+ if (!input.value.trim()) return
134
+ sendMessage({ text: input.value })
63
135
  input.value = ''
64
136
  }
65
137
  </script>
@@ -72,19 +144,35 @@ function onSubmit() {
72
144
 
73
145
  <template #body>
74
146
  <UContainer>
75
- <UChatMessages :messages="chat.messages" :status="chat.status">
76
- <template #content="{ message }">
77
- <template v-for="(part, index) in message.parts" :key="`${message.id}-${part.type}-${index}`">
78
- <MDC
79
- v-if="part.type === 'text' && message.role === 'assistant'"
80
- :value="part.text"
81
- :cache-key="`${message.id}-${index}`"
147
+ <UChatMessages :messages="messages" :status="status">
148
+ <template #part="{ part, message, streaming }">
149
+ <UChatReasoning
150
+ v-if="isReasoningUIPart(part)"
151
+ :text="part.text"
152
+ :streaming="isPartStreaming(part, streaming)"
153
+ >
154
+ <Comark
155
+ :markdown="part.text"
156
+ :streaming="isPartStreaming(part, streaming)"
157
+ :plugins="[highlight()]"
82
158
  class="*:first:mt-0 *:last:mb-0"
83
159
  />
84
- <p v-else-if="part.type === 'text' && message.role === 'user'" class="whitespace-pre-wrap">
85
- {{ part.text }}
86
- </p>
87
- </template>
160
+ </UChatReasoning>
161
+
162
+ <UChatTool
163
+ v-else-if="isToolUIPart(part)"
164
+ :text="getToolName(part)"
165
+ :streaming="isToolStreaming(part, streaming)"
166
+ :error="part.state === 'output-error'"
167
+ />
168
+
169
+ <Comark
170
+ v-else-if="isTextUIPart(part) && message.role === 'assistant'"
171
+ :markdown="part.text"
172
+ :streaming="isPartStreaming(part, streaming)"
173
+ :plugins="[highlight()]"
174
+ class="*:first:mt-0 *:last:mb-0"
175
+ />
88
176
  </template>
89
177
  </UChatMessages>
90
178
  </UContainer>
@@ -92,8 +180,8 @@ function onSubmit() {
92
180
 
93
181
  <template #footer>
94
182
  <UContainer class="pb-4 sm:pb-6">
95
- <UChatPrompt v-model="input" :error="chat.error" @submit="onSubmit">
96
- <UChatPromptSubmit :status="chat.status" @stop="chat.stop()" @reload="chat.regenerate()" />
183
+ <UChatPrompt v-model="input" :error="error" @submit="onSubmit">
184
+ <UChatPromptSubmit :status="status" @stop="stop()" @reload="regenerate()" />
97
185
  </UChatPrompt>
98
186
  </UContainer>
99
187
  </template>
@@ -103,36 +191,13 @@ function onSubmit() {
103
191
 
104
192
  ## Key components
105
193
 
106
- ### ChatMessages
107
-
108
- Scrollable message list with auto-scroll and loading indicator.
109
-
110
- | Prop | Description |
111
- |---|---|
112
- | `messages` | Array of AI SDK messages |
113
- | `status` | `'submitted'`, `'streaming'`, `'ready'`, `'error'` |
114
-
115
- Slots: `#content` (receives `{ message }`), `#actions` (per-message), `#indicator` (loading)
116
-
117
- ### ChatPrompt
118
-
119
- Enhanced textarea form for prompts. Accepts all Textarea props.
120
-
121
- | Prop | Description |
122
- |---|---|
123
- | `v-model` | Input text binding |
124
- | `error` | Error from chat instance |
125
- | `variant` | `'outline'` (default), `'subtle'`, `'soft'`, `'ghost'`, `'none'` |
126
-
127
- Slots: `#default` (submit button), `#footer` (below input, e.g. model selector)
128
-
129
- ### ChatPromptSubmit
130
-
131
- Submit button with automatic status handling (send/stop/reload).
132
-
133
- ### ChatPalette
134
-
135
- Layout wrapper for chat inside overlays (Modal, Slideover, Drawer).
194
+ - `UChatMessages` — scrollable message list with auto-scroll. Props: `messages`, `status`. Slots: `#part` (per part, unrendered parts fall back to the default output), `#content` (per message), `#actions`, `#indicator`.
195
+ - `UChatMessage` — individual bubble. Props: `message`, `side` (`'left'`/`'right'`).
196
+ - `UChatReasoning` — collapsible reasoning block. Auto-opens during streaming, auto-closes when done. Use `isPartStreaming(part, streaming)` from `@nuxt/ui/utils/ai`, with `streaming` from the `#part` slot.
197
+ - `UChatTool` — tool invocation status. Use `isToolStreaming(part, streaming)`. Variants: `'inline'` (default), `'card'`.
198
+ - `UChatPrompt` — enhanced textarea for chat. Its typed API exposes a selected subset of `UTextarea` props, forwards additional attributes to the underlying textarea, and adds chat-specific props such as `error` and `submitOnEnter`.
199
+ - `UChatPromptSubmit` — submit button with automatic status handling (send/stop/reload).
200
+ - `UChatPalette` — layout wrapper for chat inside overlays.
136
201
 
137
202
  ## Chat in a modal
138
203
 
@@ -140,11 +205,11 @@ Layout wrapper for chat inside overlays (Modal, Slideover, Drawer).
140
205
  <UModal v-model:open="isOpen">
141
206
  <template #content>
142
207
  <UChatPalette>
143
- <UChatMessages :messages="chat.messages" :status="chat.status" />
208
+ <UChatMessages :messages="messages" :status="status" />
144
209
 
145
210
  <template #prompt>
146
211
  <UChatPrompt v-model="input" @submit="onSubmit">
147
- <UChatPromptSubmit :status="chat.status" />
212
+ <UChatPromptSubmit :status="status" />
148
213
  </UChatPrompt>
149
214
  </template>
150
215
  </UChatPalette>
@@ -156,19 +221,15 @@ Layout wrapper for chat inside overlays (Modal, Slideover, Drawer).
156
221
 
157
222
  ```vue
158
223
  <UChatPrompt v-model="input" @submit="onSubmit">
159
- <UChatPromptSubmit :status="chat.status" />
224
+ <UChatPromptSubmit :status="status" />
160
225
 
161
226
  <template #footer>
162
227
  <USelect
163
228
  v-model="model"
229
+ :icon="models.find(m => m.value === model)?.icon"
164
230
  placeholder="Select a model"
165
231
  variant="ghost"
166
- icon="i-simple-icons-openai"
167
- :items="[
168
- { label: 'GPT-4o', value: 'gpt-4o' },
169
- { label: 'Claude 3.5 Sonnet', value: 'claude-3.5-sonnet' },
170
- { label: 'Gemini 2.5 Pro', value: 'gemini-2.5-pro' }
171
- ]"
232
+ :items="models"
172
233
  />
173
234
  </template>
174
235
  </UChatPrompt>
@@ -176,6 +237,8 @@ Layout wrapper for chat inside overlays (Modal, Slideover, Drawer).
176
237
 
177
238
  ## Conversation sidebar
178
239
 
240
+ Combine with dashboard layout for a ChatGPT-like interface:
241
+
179
242
  ```vue [layouts/dashboard.vue]
180
243
  <template>
181
244
  <UDashboardGroup>
@@ -2,6 +2,13 @@
2
2
 
3
3
  Build admin interfaces with resizable sidebars, multi-panel layouts, and toolbars.
4
4
 
5
+ ## When to use
6
+
7
+ - Admin panels, back-office UIs
8
+ - Email clients, project management tools
9
+ - Any app with a persistent sidebar and content panels
10
+ - Combine with chat or editor layouts for specialized dashboards
11
+
5
12
  ## Component tree
6
13
 
7
14
  ```
@@ -53,9 +60,9 @@ const items = computed<NavigationMenuItem[]>(() => [{
53
60
 
54
61
  <template #default="{ collapsed }">
55
62
  <UNavigationMenu
63
+ :collapsed="collapsed"
56
64
  :items="items"
57
65
  orientation="vertical"
58
- :ui="{ link: collapsed ? 'justify-center' : undefined }"
59
66
  />
60
67
  </template>
61
68
 
@@ -86,6 +93,9 @@ definePageMeta({ layout: 'dashboard' })
86
93
  <UDashboardPanel>
87
94
  <template #header>
88
95
  <UDashboardNavbar title="Home">
96
+ <template #leading>
97
+ <UDashboardSidebarCollapse />
98
+ </template>
89
99
  <template #right>
90
100
  <UButton icon="i-lucide-plus" label="New" />
91
101
  </template>
@@ -99,43 +109,49 @@ definePageMeta({ layout: 'dashboard' })
99
109
  </template>
100
110
  ```
101
111
 
112
+ ### Common mistakes
113
+
114
+ - Forgetting `definePageMeta({ layout: 'dashboard' })` — the page won't use the dashboard layout without it.
115
+ - Putting content directly in `UDashboardPanel` without using `#body` slot — content won't scroll properly.
116
+ - Not handling the `collapsed` slot prop — sidebar content should adapt when collapsed (hide labels, center icons).
117
+
102
118
  ## Key components
103
119
 
104
120
  ### DashboardGroup
105
121
 
106
- Root layout wrapper. Manages sidebar state and persistence.
122
+ Root wrapper. Manages sidebar state and persistence.
107
123
 
108
- | Prop | Default | Description |
124
+ | Prop | Default | Purpose |
109
125
  |---|---|---|
110
- | `storage` | `'cookie'` | State persistence: `'cookie'`, `'localStorage'`, `false` |
126
+ | `storage` | `'cookie'` | `'cookie'` or `'local'` |
127
+ | `persistent` | `true` | Set to `false` to stop saving sizes |
111
128
  | `storage-key` | `'dashboard'` | Storage key name |
112
- | `unit` | `'percentages'` | Size unit: `'percentages'` or `'pixels'` |
113
129
 
114
130
  ### DashboardSidebar
115
131
 
116
132
  Resizable, collapsible sidebar. Must be inside `DashboardGroup`.
117
133
 
118
- | Prop | Default | Description |
134
+ | Prop | Default | Purpose |
119
135
  |---|---|---|
120
- | `resizable` | `false` | Enable resize by dragging |
121
- | `collapsible` | `false` | Enable collapse when dragged to edge |
136
+ | `resizable` | `false` | Drag to resize |
137
+ | `collapsible` | `false` | Collapse when dragged to edge |
122
138
  | `side` | `'left'` | `'left'` or `'right'` |
123
- | `mode` | `'slideover'` | Mobile menu mode: `'modal'`, `'slideover'`, `'drawer'` |
139
+ | `mode` | `'slideover'` | Mobile: `'modal'`, `'slideover'`, `'drawer'` |
124
140
 
125
- Slots receive `{ collapsed }` prop. Control state: `v-model:collapsed`, `v-model:open` (mobile).
141
+ All slots receive `{ collapsed, collapse }` — `collapsed` is the boolean state, `collapse(value)` toggles it programmatically. Use `v-model:collapsed` and `v-model:open` (mobile) for state control.
126
142
 
127
143
  ### DashboardPanel
128
144
 
129
- Content panel with `#header`, `#body` (scrollable), `#footer`, and `#default` (raw) slots.
130
-
131
- | Prop | Default | Description |
132
- |---|---|---|
133
- | `id` | `—` | Unique ID (required for multi-panel) |
134
- | `resizable` | `false` | Enable resize by dragging |
145
+ Content panel with `#header`, `#body` (scrollable), `#footer`, and `#default` (raw, no scroll) slots.
135
146
 
136
147
  ### DashboardNavbar / DashboardToolbar
137
148
 
138
- Navbar has `#left`, `#default`, `#right` slots and a `title` prop. Toolbar has the same slots for filters/actions below the navbar.
149
+ Navbar: `#leading`, `#left`, `#default`, `#right` slots + `title` prop. Use `UDashboardSidebarCollapse` in `#leading` to collapse the sidebar on desktop. The navbar already renders a mobile toggle, customized with its `toggle` prop.
150
+ Toolbar: same slots, sits below navbar for filters/actions.
151
+
152
+ ### UNavigationMenu in sidebar
153
+
154
+ Always pass `:collapsed="collapsed"` to `UNavigationMenu` inside a collapsible sidebar — it auto-hides labels and centers icons. Use `NavigationMenuItem[][]` (array of arrays) for separate groups (main nav + footer links).
139
155
 
140
156
  ## Multi-panel (list-detail)
141
157
 
@@ -171,7 +187,6 @@ definePageMeta({ layout: 'dashboard' })
171
187
  <UDashboardPanel>
172
188
  <template #header>
173
189
  <UDashboardNavbar title="Users" />
174
-
175
190
  <UDashboardToolbar>
176
191
  <template #left>
177
192
  <UInput icon="i-lucide-search" placeholder="Search..." />
@@ -193,7 +208,6 @@ definePageMeta({ layout: 'dashboard' })
193
208
  <template #header>
194
209
  <UDashboardSearchButton />
195
210
  </template>
196
- <!-- ... -->
197
211
  </UDashboardSidebar>
198
212
 
199
213
  <slot />
@@ -2,7 +2,13 @@
2
2
 
3
3
  Build documentation sites with sidebar navigation, table of contents, and surround links.
4
4
 
5
- > Requires `@nuxt/content` module for navigation, search, and TOC.
5
+ ## When to use
6
+
7
+ - Technical documentation sites
8
+ - Knowledge bases, help centers
9
+ - Any content-heavy site with hierarchical navigation
10
+
11
+ > Requires `@nuxt/content` — see [conventions](../guidelines/conventions.md#content-module-integration) for setup (module order + `@source`).
6
12
 
7
13
  ## Component tree
8
14
 
@@ -125,17 +131,22 @@ const { data: surround } = await useAsyncData(`${route.path}-surround`, () => {
125
131
  </template>
126
132
  ```
127
133
 
128
- > The outer `UPage` in the layout handles the left sidebar. The inner `UPage` in the page handles the right sidebar. They nest correctly.
134
+ ### How nesting works
135
+
136
+ The outer `UPage` in the layout handles the **left sidebar**. The inner `UPage` in the page handles the **right sidebar**. They nest correctly — this is intentional.
137
+
138
+ ### Common mistakes
139
+
140
+ - Not providing navigation via `provide`/`inject` — the layout needs it from the app shell.
141
+ - Forgetting `UContentSearch` in app.vue — search won't work without it.
142
+ - Using `UContentSearchButton` without `UContentSearch` — the button opens search, but the search component must exist.
129
143
 
130
144
  ## Key components
131
145
 
132
- - `UPage` — Multi-column grid layout with `#left`, `#default`, `#right` slots
133
- - `UPageAside` — Sticky sidebar wrapper (visible from `lg` breakpoint)
134
- - `UPageHeader` — Page title and description
135
- - `UPageBody` — Main content area
136
- - `UContentNavigation` — Sidebar navigation tree
137
- - `UContentToc` — Table of contents
138
- - `UContentSurround` — Prev/next links
139
- - `UContentSearch` / `UContentSearchButton` — Search command palette
140
- - `UPageAnchors` — Simpler alternative to full TOC
141
- - `UPageLinks` — Related resource links
146
+ - `UPage` — multi-column grid with `#left`, `#default`, `#right` slots
147
+ - `UPageAside` — sticky sidebar wrapper (visible from `lg` breakpoint)
148
+ - `UContentNavigation` — sidebar navigation tree from Nuxt Content
149
+ - `UContentToc` — table of contents from page headings
150
+ - `UContentSurround` — prev/next links
151
+ - `UContentSearch` / `UContentSearchButton` — search command palette
152
+ - `UPageAnchors` — simpler alternative to full TOC
@@ -2,26 +2,26 @@
2
2
 
3
3
  Build a rich text editor with toolbars, slash commands, mentions, and drag-and-drop.
4
4
 
5
+ ## When to use
6
+
7
+ - Note-taking apps, CMS editors
8
+ - Collaborative editing interfaces
9
+ - Any rich text editing need (supports JSON, HTML, and Markdown)
10
+
5
11
  ## Component tree
6
12
 
7
13
  ```
8
- UApp
9
- ├── UHeader
10
- ├── UMain
11
- │ └── NuxtPage
12
- │ └── UContainer
13
- │ └── UEditor
14
- │ ├── UEditorToolbar (fixed / bubble / floating)
15
- │ ├── UEditorDragHandle
16
- │ ├── UEditorSuggestionMenu
17
- │ ├── UEditorMentionMenu
18
- │ └── UEditorEmojiMenu
19
- └── UFooter
14
+ UEditor
15
+ ├── UEditorToolbar (fixed / bubble / floating)
16
+ ├── UEditorDragHandle
17
+ ├── UEditorSuggestionMenu
18
+ ├── UEditorMentionMenu
19
+ └── UEditorEmojiMenu
20
20
  ```
21
21
 
22
- ## Page
22
+ ## Basic editor
23
23
 
24
- ```vue [pages/editor.vue]
24
+ ```vue
25
25
  <script setup lang="ts">
26
26
  const content = ref({
27
27
  type: 'doc',
@@ -40,28 +40,19 @@ const content = ref({
40
40
  </script>
41
41
 
42
42
  <template>
43
- <UPage>
44
- <UPageHeader title="Editor">
45
- <template #actions>
46
- <UButton label="Save" icon="i-lucide-save" />
47
- </template>
48
- </UPageHeader>
49
-
50
- <UPageBody>
51
- <UEditor v-model="content">
52
- <UEditorToolbar />
53
- <UEditorDragHandle />
54
- <UEditorSuggestionMenu />
55
- <UEditorMentionMenu
56
- :items="[
57
- { label: 'Benjamin', avatar: { src: 'https://github.com/benjamincanac.png' } },
58
- { label: 'Sébastien', avatar: { src: 'https://github.com/atinux.png' } }
59
- ]"
60
- />
61
- <UEditorEmojiMenu />
62
- </UEditor>
63
- </UPageBody>
64
- </UPage>
43
+ <UEditor v-slot="{ editor }" v-model="content">
44
+ <UEditorToolbar :editor="editor" />
45
+ <UEditorSuggestionMenu :editor="editor" />
46
+ <UEditorMentionMenu
47
+ :editor="editor"
48
+ :items="[
49
+ { label: 'Benjamin', avatar: { src: 'https://github.com/benjamincanac.png' } },
50
+ { label: 'Sébastien', avatar: { src: 'https://github.com/atinux.png' } }
51
+ ]"
52
+ />
53
+ <UEditorEmojiMenu :editor="editor" />
54
+ <UEditorDragHandle :editor="editor" />
55
+ </UEditor>
65
56
  </template>
66
57
  ```
67
58
 
@@ -69,30 +60,24 @@ const content = ref({
69
60
 
70
61
  ## Key components
71
62
 
72
- - `UEditor` — Rich text editor (`v-model` accepts JSON, HTML, or markdown via `content-type` prop)
73
- - `UEditorToolbar` — Toolbar with `layout`: `'fixed'` (default), `'bubble'` (on selection), `'floating'` (on empty lines)
74
- - `UEditorDragHandle` — Block drag-and-drop handle
75
- - `UEditorSuggestionMenu` — Slash command menu
76
- - `UEditorMentionMenu` — @ mention menu
77
- - `UEditorEmojiMenu` — Emoji picker
63
+ - `UEditor` — rich text editor. `v-model` accepts JSON (default), HTML, or Markdown via `content-type` prop. Default slot provides `{ editor, handlers }` — `editor` is the Tiptap instance, `handlers` contains action functions for toolbar/menus.
64
+ - `UEditorToolbar` — toolbar with `layout`: `'fixed'` (default), `'bubble'` (on selection), `'floating'` (on empty lines).
65
+ - `UEditorDragHandle` — block drag-and-drop handle.
66
+ - `UEditorSuggestionMenu` — slash command menu (type `/` to open).
67
+ - `UEditorMentionMenu` — `@` mention menu.
68
+ - `UEditorEmojiMenu` — emoji picker (type `:` to open).
78
69
 
79
70
  ## Toolbar modes
80
71
 
81
72
  ```vue
82
- <!-- Fixed (default) -->
83
- <UEditor v-model="content">
84
- <UEditorToolbar />
85
- </UEditor>
86
-
87
- <!-- Bubble (appears on text selection) -->
88
- <UEditor v-model="content">
89
- <UEditorToolbar layout="bubble" />
90
- </UEditor>
91
-
92
- <!-- Floating (appears on empty lines) -->
93
- <UEditor v-model="content">
94
- <UEditorToolbar layout="floating" />
95
- </UEditor>
73
+ <!-- Fixed (default) — always visible at top -->
74
+ <UEditorToolbar :editor="editor" />
75
+
76
+ <!-- Bubble — appears on text selection -->
77
+ <UEditorToolbar :editor="editor" layout="bubble" />
78
+
79
+ <!-- Floating — appears on empty lines -->
80
+ <UEditorToolbar :editor="editor" layout="floating" />
96
81
  ```
97
82
 
98
83
  ## Content types
@@ -110,7 +95,7 @@ const content = ref({
110
95
 
111
96
  ## With document sidebar
112
97
 
113
- Combine with Dashboard components for a multi-document editor with a sidebar.
98
+ Combine with Dashboard layout for a multi-document editor:
114
99
 
115
100
  ```vue [layouts/editor.vue]
116
101
  <template>
@@ -120,8 +105,9 @@ Combine with Dashboard components for a multi-document editor with a sidebar.
120
105
  <UButton icon="i-lucide-plus" label="New document" block />
121
106
  </template>
122
107
 
123
- <template #default>
108
+ <template #default="{ collapsed }">
124
109
  <UNavigationMenu
110
+ :collapsed="collapsed"
125
111
  :items="documents.map(doc => ({
126
112
  label: doc.title,
127
113
  to: `/editor/${doc.id}`,
@@ -155,11 +141,11 @@ const content = ref({ type: 'doc', content: [] })
155
141
  </template>
156
142
 
157
143
  <UContainer class="py-8">
158
- <UEditor v-model="content">
159
- <UEditorToolbar />
160
- <UEditorDragHandle />
161
- <UEditorSuggestionMenu />
162
- <UEditorEmojiMenu />
144
+ <UEditor v-slot="{ editor }" v-model="content">
145
+ <UEditorToolbar :editor="editor" />
146
+ <UEditorSuggestionMenu :editor="editor" />
147
+ <UEditorEmojiMenu :editor="editor" />
148
+ <UEditorDragHandle :editor="editor" />
163
149
  </UEditor>
164
150
  </UContainer>
165
151
  </UDashboardPanel>