docs: support per-example playground import maps

Parse @import lines in ::: example blocks to declare extra
dependencies for the @vue/repl playground. Auto-resolves to
esm.sh or accepts explicit URL overrides.

Author: johnleider

apps/docs/build/markdown.ts

@@ -82,6 +82,7 @@ export default async function MarkdownPlugin () {
             env._inExample = true
             env._exampleFilePaths = [] as string[]
             env._exampleFileOrders = [] as (number | undefined)[]
+            env._exampleImports = {} as Record<string, string>
             env._exampleCollapse = isCollapse
             return '' // Defer opening tag until we know the file path(s)
           }
@@ -92,15 +93,20 @@ export default async function MarkdownPlugin () {
           const orders = env._exampleFileOrders as (number | undefined)[]
           const hasOrders = orders?.some(o => o !== undefined)
           const collapse = env._exampleCollapse
+          const imports = env._exampleImports as Record<string, string>
 
           delete env._inExample
           delete env._exampleFilePaths
           delete env._exampleFileOrders
+          delete env._exampleImports
           delete env._exampleOpened
           delete env._examplePathPara
           delete env._exampleCollapse
 
           const collapseAttr = collapse ? ' collapse' : ''
+          const importsAttr = Object.keys(imports).length > 0
+            ? ` :imports="${JSON.stringify(imports).replace(/"/g, '\'')}"`
+            : ''
 
           // If opened with description, close the description template
           if (wasOpened) {
@@ -109,11 +115,11 @@ export default async function MarkdownPlugin () {
 
           // If we have paths but no description content, emit simple peek version
           if (paths?.length === 1) {
-            return `<DocsExample file-path="${paths[0]}"${collapse ? collapseAttr : ' peek'} />\n`
+            return `<DocsExample file-path="${paths[0]}"${collapse ? collapseAttr : ' peek'}${importsAttr} />\n`
           } else if (paths?.length > 1) {
             const pathsJson = JSON.stringify(paths).replace(/"/g, '\'')
             const ordersAttr = hasOrders ? ` :file-orders="${JSON.stringify(orders)}"` : ''
-            return `<DocsExample :file-paths="${pathsJson}"${ordersAttr}${collapseAttr} />\n`
+            return `<DocsExample :file-paths="${pathsJson}"${ordersAttr}${collapseAttr}${importsAttr} />\n`
           }
 
           return ''
@@ -148,16 +154,20 @@ export default async function MarkdownPlugin () {
           const hasOrders = orders?.some(o => o !== undefined)
           const collapse = env._exampleCollapse
           const collapseAttr = collapse ? ' collapse' : ''
+          const imports = env._exampleImports as Record<string, string>
+          const importsAttr = Object.keys(imports).length > 0
+            ? ` :imports="${JSON.stringify(imports).replace(/"/g, '\'')}"`
+            : ''
           const defaultRender = defaultHeadingOpen
             ? defaultHeadingOpen(tokens, index, options, env, self)
             : self.renderToken(tokens, index, options)
 
           if (paths.length === 1) {
-            return `<DocsExample file-path="${paths[0]}"${collapseAttr}>\n<template #description>\n${defaultRender}`
+            return `<DocsExample file-path="${paths[0]}"${collapseAttr}${importsAttr}>\n<template #description>\n${defaultRender}`
           } else {
             const pathsJson = JSON.stringify(paths).replace(/"/g, '\'')
             const ordersAttr = hasOrders ? ` :file-orders="${JSON.stringify(orders)}"` : ''
-            return `<DocsExample :file-paths="${pathsJson}"${ordersAttr}${collapseAttr}>\n<template #description>\n${defaultRender}`
+            return `<DocsExample :file-paths="${pathsJson}"${ordersAttr}${collapseAttr}${importsAttr}>\n<template #description>\n${defaultRender}`
           }
         }
 
@@ -175,8 +185,9 @@ export default async function MarkdownPlugin () {
 
         // Handle example container: lines starting with / are file paths
         // Multiple paths may be in one paragraph separated by newlines
-        if (env._inExample && inlineToken?.type === 'inline' && inlineToken.content?.startsWith('/')) {
-          const lines = inlineToken.content.split('\n')
+        const content = inlineToken?.content?.trim() ?? ''
+        if (env._inExample && inlineToken?.type === 'inline' && (content.startsWith('/') || content.startsWith('@import'))) {
+          const lines = inlineToken.content!.split('\n')
           for (const line of lines) {
             const trimmed = line.trim()
             if (trimmed.startsWith('/') && trimmed.length > 1) {
@@ -189,6 +200,14 @@ export default async function MarkdownPlugin () {
                 ;(env._exampleFilePaths as string[]).push(trimmed.slice(1))
                 ;(env._exampleFileOrders as (number | undefined)[]).push(undefined)
               }
+            } else if (trimmed.startsWith('@import ')) {
+              const rest = trimmed.slice(8).trim()
+              const space = rest.indexOf(' ')
+              if (space > 0) {
+                ;(env._exampleImports as Record<string, string>)[rest.slice(0, space)] = rest.slice(space + 1).trim()
+              } else if (rest) {
+                ;(env._exampleImports as Record<string, string>)[rest] = `https://esm.sh/${rest}`
+              }
             }
           }
           env._examplePathPara = true
@@ -205,12 +224,16 @@ export default async function MarkdownPlugin () {
           const hasOrders = orders?.some(o => o !== undefined)
           const collapse = env._exampleCollapse
           const collapseAttr = collapse ? ' collapse' : ''
+          const imports = env._exampleImports as Record<string, string>
+          const importsAttr = Object.keys(imports).length > 0
+            ? ` :imports="${JSON.stringify(imports).replace(/"/g, '\'')}"`
+            : ''
           if (paths.length === 1) {
-            return `<DocsExample file-path="${paths[0]}"${collapseAttr}>\n<template #description>\n` + (defaultParagraphOpen ? defaultParagraphOpen(tokens, index, options, env, self) : '<p>')
+            return `<DocsExample file-path="${paths[0]}"${collapseAttr}${importsAttr}>\n<template #description>\n` + (defaultParagraphOpen ? defaultParagraphOpen(tokens, index, options, env, self) : '<p>')
           } else {
             const pathsJson = JSON.stringify(paths).replace(/"/g, '\'')
             const ordersAttr = hasOrders ? ` :file-orders="${JSON.stringify(orders)}"` : ''
-            return `<DocsExample :file-paths="${pathsJson}"${ordersAttr}${collapseAttr}>\n<template #description>\n` + (defaultParagraphOpen ? defaultParagraphOpen(tokens, index, options, env, self) : '<p>')
+            return `<DocsExample :file-paths="${pathsJson}"${ordersAttr}${collapseAttr}${importsAttr}>\n<template #description>\n` + (defaultParagraphOpen ? defaultParagraphOpen(tokens, index, options, env, self) : '<p>')
           }
         }
 

apps/docs/src/components/docs/DocsExample.vue

@@ -34,6 +34,7 @@
     code?: string
     collapse?: boolean
     files?: ExampleFile[]
+    imports?: Record<string, string>
     peek?: boolean
     peekLines?: number
   }>(), {
@@ -156,7 +157,7 @@
   async function openAllInPlayground () {
     if (!displayFiles.value?.length) return
     const files = displayFiles.value.map(f => ({ name: f.name, code: f.code }))
-    const url = await usePlayground(files)
+    const url = await usePlayground(files, undefined, props.imports)
     window.open(url, '_blank')
   }
 

apps/docs/src/composables/usePlayground.ts

@@ -101,9 +101,15 @@ function buildPlaygroundFiles (inputFiles: PlaygroundFile[], dir?: string): Reco
  * Get editor URL for multiple files.
  * When dir is provided, files are nested under src/{dir}/.
  */
-export async function usePlayground (inputFiles: PlaygroundFile[], dir?: string): Promise<string> {
+export async function usePlayground (
+  inputFiles: PlaygroundFile[],
+  dir?: string,
+  imports?: Record<string, string>,
+): Promise<string> {
   const files = buildPlaygroundFiles(inputFiles, dir)
-  const hash = await utoa(JSON.stringify(files))
+  const data: PlaygroundHashData = { files }
+  if (imports && Object.keys(imports).length > 0) data.imports = imports
+  const hash = await encodePlaygroundHash(data)
   return `/playground#${hash}`
 }
 
@@ -114,6 +120,7 @@ function isFileRecord (v: unknown): v is Record<string, string> {
 export interface PlaygroundHashData {
   files: Record<string, string>
   active?: string
+  imports?: Record<string, string>
 }
 
 /**
@@ -139,8 +146,12 @@ export async function decodePlaygroundHash (hash: string): Promise<PlaygroundHas
       && 'files' in parsed
       && isFileRecord((parsed as { files: unknown }).files)
     ) {
-      const { files, active } = parsed as { files: Record<string, string>, active?: unknown }
-      return { files, active: isString(active) ? active : undefined }
+      const { files, active, imports } = parsed as { files: Record<string, string>, active?: unknown, imports?: unknown }
+      return {
+        files,
+        active: isString(active) ? active : undefined,
+        imports: isFileRecord(imports) ? imports : undefined,
+      }
     }
     return null
   } catch {

apps/docs/src/composables/usePlaygroundFiles.ts

@@ -36,13 +36,18 @@ export function usePlaygroundFiles () {
   const isReady = shallowRef(false)
 
   const aliasMap = shallowRef(new Map<string, string>())
+  const extraImports = shallowRef<Record<string, string>>()
 
   onMounted(async () => {
     const hash = window.location.hash.slice(1)
     const decoded = hash ? await decodePlaygroundHash(hash) : null
 
     if (decoded) {
       await loadExample(decoded.files, decoded.active)
+      if (decoded.imports && Object.keys(decoded.imports).length > 0) {
+        extraImports.value = decoded.imports
+        store.setImportMap({ imports: decoded.imports }, true)
+      }
     } else {
       const theme_ = theme.isDark.value ? 'dark' : 'light'
       await store.setFiles(
@@ -113,7 +118,7 @@ export function usePlaygroundFiles () {
 
   const updateHash = debounce(async (files: Record<string, string>, active: string | undefined) => {
     if (Object.keys(files).length === 0) return
-    const hash = await encodePlaygroundHash({ files, active })
+    const hash = await encodePlaygroundHash({ files, active, imports: extraImports.value })
     history.replaceState(null, '', `#${hash}`)
   }, 500)
 

apps/docs/src/pages/composables/selection/create-selection.md

@@ -72,7 +72,52 @@ Selection state is **always reactive**. Collection methods follow the base `crea
 ## Examples
 
 ::: example
-/composables/create-selection/file-picker
+/composables/create-selection/context.ts
+/composables/create-selection/BookmarkProvider.vue
+/composables/create-selection/BookmarkConsumer.vue
+/composables/create-selection/bookmark-manager.vue
+@import @mdi/js
+
+### Bookmark Manager
+
+A multi-select bookmark manager demonstrating `createSelection` with `createContext` for provider/consumer separation. The provider owns the registry and exposes domain methods; the consumer handles UI and filtering.
+
+```mermaid "Data Flow"
+sequenceDiagram
+  participant C as BookmarkConsumer
+  participant P as BookmarkProvider
+  participant S as createSelection
+
+  C->>P: add(title, url, tags)
+  P->>S: register(ticket)
+  S-->>P: selectedIds updated
+  P-->>C: stats / pinned computed
+  C->>S: toggle(id)
+  S-->>C: isSelected ref updated
+```
+
+**File breakdown:**
+
+| File | Role |
+|------|------|
+| `context.ts` | Defines `BookmarkInput` (extending `SelectionTicketInput`) and `BookmarkContext`, then creates the `[useBookmarks, provideBookmarks]` tuple |
+| `BookmarkProvider.vue` | Creates the selection with `events: true`, wraps it with `useProxyRegistry` for reactive collection access, manages a separate `pinnedIds` Set, seeds initial bookmarks via `onboard`, and exposes mutation methods through context |
+| `BookmarkConsumer.vue` | Calls `useBookmarks()` for data and methods; wraps the context with `useProxyRegistry` for reactive `values`; owns local UI state (filters, inputs) and derives `filtered` and `allTags` as computed |
+| `bookmark-manager.vue` | Entry point—composes `BookmarkProvider` around `BookmarkConsumer` |
+
+**Key patterns:**
+
+- `events: true` + `useProxyRegistry` — enables reactive `proxy.values` so computeds like `filtered` and `allTags` update when bookmarks are added
+- `pinnedIds` — a separate `shallowReactive(Set)` for pin state, following the same pattern as `selectedIds`
+- `onboard()` — bulk-loads the initial bookmark set in a single batch
+- `selection.register()` — adds a bookmark with custom fields (`url`, `tags`)
+- `selection.toggle()` / `ticket.toggle()` — toggles selection from either the registry or the ticket
+- `disabled: true` — prevents selecting deprecated bookmarks
+- Tag-based filtering with `Select all` / `Clear` bulk actions
+- `Checkbox.Root` + `Checkbox.Indicator` — headless checkbox from `@vuetify/v0`
+
+Add bookmarks, filter by tag, toggle selection with checkboxes, and pin favorites. Hover over a row to see the pin action.
+
 :::
 
 <DocsApi />