frappe-ui 1.0.0-beta.2 → 1.0.0-beta.21

package/vitepress/index.d.ts

@@ -0,0 +1,23 @@
+// Combined type surface for `frappe-ui/vitepress`.
+//
+// At runtime the package resolves to two different files by export condition:
+// `index.node.ts` (the Node config builder) for VitePress' config loader, and
+// `index.ts` (the browser barrel: theme + components) for Vue code. TypeScript,
+// however, doesn't apply the `node` condition — it would otherwise only ever
+// see the browser half and flag `defineDocsConfig` as missing in config files.
+//
+// This declaration (wired as the `types` condition) merges both surfaces so
+// editors resolve the full API regardless of context. The node-only names are
+// disjoint from the browser names, so there are no `export *` collisions.
+export * from './index'
+export {
+  defineDocsConfig,
+  syncColocatedComponentDocs,
+  colocatedComponentDocs,
+  componentTransformer,
+  createComponentTransformer,
+} from './index.node'
+export type {
+  DefineDocsConfigOptions,
+  DocsThemeConfig,
+} from './index.node'

package/vitepress/index.node.ts

@@ -0,0 +1,175 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { defineConfig, type DefaultTheme, type UserConfig } from 'vitepress'
+import { transformerStyleToClass } from '@shikijs/transformers'
+// @ts-ignore — JS package without bundled types
+import { lucideIcons } from 'frappe-ui/vite'
+
+import { createComponentTransformer } from './plugins/componentTransformer.ts'
+import colocatedComponentDocs from './plugins/colocatedComponentDocs.ts'
+import type { SidebarSection } from './components/Docs/sidebarList.ts'
+
+// frappe-ui package root — this file lives at <root>/vitepress/index.node.ts.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+type HeadConfig = NonNullable<UserConfig['head']>[number]
+
+// Extends the default theme with the extra fields the shared Sidebar reads.
+export interface DocsThemeConfig extends DefaultTheme.Config {
+  name?: string
+  version?: string
+  githubUrl?: string
+  sections?: SidebarSection[]
+}
+
+export interface DefineDocsConfigOptions {
+  // Consumer project root (the docs dir). Drives every absolute path:
+  // vite resolve.alias, plugin sourceRoots, shiki cache.
+  rootDir: string
+  name: string
+  description: string
+  base?: string
+  githubUrl?: string
+  logo?: string
+  version?: string
+  // Data-driven IA tree rendered by the shared Sidebar.
+  sidebar: SidebarSection[]
+  // Merged with generated OG/Twitter defaults.
+  head?: HeadConfig[]
+  // Absolute source roots for component story/types snippet resolution.
+  sourceRoots?: string[]
+  // Opt-in: generate @include proxy pages for colocated component docs.
+  // `true` uses rootDir defaults; pass options to customize. Off by default
+  // since most consumers don't have the frappe-ui component/frappe layout.
+  colocatedDocs?: Parameters<typeof colocatedComponentDocs>[0] | boolean
+  // Extra resolve.alias entries (merged over rootDir-relative defaults).
+  alias?: Record<string, string>
+  // Hook for extra markdown-it plugins.
+  markdownConfig?: (md: any) => void
+}
+
+function generatedHead(name: string, description: string): HeadConfig[] {
+  return [
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:site_name', content: name }],
+    ['meta', { property: 'og:title', content: name }],
+    ['meta', { property: 'og:description', content: description }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:title', content: name }],
+    ['meta', { name: 'twitter:description', content: description }],
+  ]
+}
+
+export function defineDocsConfig(
+  options: DefineDocsConfigOptions,
+): UserConfig<DocsThemeConfig> {
+  const {
+    rootDir,
+    name,
+    description,
+    base = '/',
+    githubUrl,
+    logo,
+    version,
+    sidebar,
+    head = [],
+    sourceRoots = [],
+    colocatedDocs = false,
+    alias = {},
+    markdownConfig,
+  } = options
+
+  const isDev = process.env.NODE_ENV !== 'production'
+
+  // transformerStyleToClass turns shiki inline styles into classes; its CSS
+  // is collected and injected via transformHead below.
+  const toClass = transformerStyleToClass({ classPrefix: 's_' })
+
+  return defineConfig<DocsThemeConfig>({
+    base,
+    srcDir: 'content',
+    cleanUrls: true,
+    lastUpdated: true,
+    title: name,
+    description,
+    head: [...generatedHead(name, description), ...head],
+    markdown: {
+      theme: { dark: 'tokyo-night', light: 'github-light' },
+      // In dev, transformerStyleToClass flushes only at buildEnd, so let
+      // shiki emit inline --shiki-light/dark vars instead.
+      codeTransformers: isDev ? [] : [toClass],
+      config(md) {
+        md.use(createComponentTransformer({ sourceRoots }))
+        markdownConfig?.(md)
+      },
+    },
+    themeConfig: {
+      // Consumed by the shared Sidebar/Navbar (SSR-safe; no package.json read).
+      name,
+      logo,
+      version,
+      githubUrl,
+      sidebar,
+      sections: sidebar,
+      // Enables VitePress' local search index, rendered by the shared Search.
+      search: { provider: 'local' },
+    },
+    vite: {
+      plugins: [
+        lucideIcons(),
+        ...(colocatedDocs
+          ? [
+              colocatedComponentDocs(
+                colocatedDocs === true ? { rootDir } : colocatedDocs,
+              ),
+            ]
+          : []),
+      ],
+      resolve: {
+        alias: {
+          '@/components': path.resolve(rootDir, 'components'),
+          // Force Vite (client + SSR) to resolve the bare `frappe-ui/vitepress`
+          // specifier to the browser barrel — never the Node config entry this
+          // file lives in. This sidesteps SSR export-condition ambiguity: the
+          // `node` condition only ever serves VitePress' Node config loader.
+          'frappe-ui/vitepress': path.resolve(packageRoot, 'vitepress/index.ts'),
+          ...alias,
+        },
+      },
+      // frappe-ui is often a symlink resolving outside the project root (e.g.
+      // bundled fonts/assets); allow the dev server to serve from its real dir.
+      server: {
+        fs: {
+          allow: [rootDir, fs.realpathSync(packageRoot)],
+        },
+      },
+      // The shared theme renders frappe-ui during SSR. Bundle frappe-ui and
+      // its ESM-only deps (which use extensionless imports Node can't resolve
+      // when externalized) into the server build.
+      ssr: {
+        noExternal: ['frappe-ui', 'dayjs'],
+      },
+    },
+    // Inject shiki's collected CSS into each page's <head>; the production
+    // CSS bundle is finalized before markdown runs, so this side-steps timing.
+    transformHead: () => {
+      const css = toClass.getCSS()
+      if (!css) return []
+      return [['style', { 'data-shiki': '' }, css]]
+    },
+  })
+}
+
+export type {
+  SidebarSection,
+  SidebarItem,
+} from './components/Docs/sidebarList.ts'
+export { isActiveLink, getSidebarList } from './components/Docs/sidebarList.ts'
+
+// Re-exports for convenience. Explicit .ts extensions keep this entry
+// loadable when externalized by VitePress' Node-based config loader.
+// Vue SFCs are intentionally omitted here — Node can't evaluate them. The
+// browser barrel (index.ts, the `default` export condition) re-exports the
+// components/theme for Vue code.
+export * from './plugins/index.ts'

package/vitepress/index.ts

@@ -0,0 +1,17 @@
+// Browser / SSR barrel for the reusable VitePress docs theme — the
+// `frappe-ui/vitepress` entry as seen by Vue code (theme, components,
+// composables). It pulls in Vue SFCs, so it can only be evaluated by Vite,
+// never by Node's config loader.
+//
+// The config builder (`defineDocsConfig`) lives in the sibling
+// `index.node.ts`, exposed through the package's `node` export condition.
+// Named exports only. Importing `theme` also loads the stylesheet as a side
+// effect (via ./theme), so consumers don't need a separate style.css import.
+export { theme } from './theme'
+
+// Shared components (Layout, CommandPalette, Search, Sidebar, …) plus the
+// `isActiveLink` / `getSidebarList` helpers and Sidebar* types.
+export * from './components'
+// Theme composables (useTheme / setTheme).
+export * from './composables'
+export { state } from './state'

package/vitepress/plugins/colocatedComponentDocs.ts

@@ -0,0 +1,164 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { Plugin, ViteDevServer } from 'vite'
+
+// Author-facing layout: each component owns its docs:
+//   src/components/Button/Button.md      (hand-written)
+//   src/components/Button/Button.api.md  (auto-generated by propsgen)
+//   frappe/Link/Link.md                  (Frappe-integrated controls)
+//
+// VitePress wants every page under its srcDir (`docs/content`). Instead of
+// reshaping srcDir or rewrites, this plugin keeps a thin proxy file at
+//   docs/content/docs/components/<name>.md
+//   docs/content/docs/frappe/<name>.md
+// that simply `@include`s the colocated source. The proxy is auto-managed
+// — never edit it by hand.
+
+export interface SourceRootMap {
+  // Absolute dir holding `<Component>/<Component>.md` source files.
+  sourceDir: string
+  // Absolute dir where proxy `<name>.md` files are written.
+  proxyDir: string
+}
+
+export interface ColocatedComponentDocsOptions {
+  // Pairs of source/proxy dirs. Takes precedence over `rootDir` defaults.
+  sourceRoots?: SourceRootMap[]
+  // Consumer project root. Defaults the proxy dirs to
+  // `<rootDir>/content/docs/{components,frappe}` and source dirs to
+  // `<rootDir>/../src/components` and `<rootDir>/../frappe`.
+  rootDir?: string
+}
+
+function rootDirRoots(rootDir: string): SourceRootMap[] {
+  return [
+    {
+      sourceDir: path.resolve(rootDir, '../src/components'),
+      proxyDir: path.resolve(rootDir, 'content/docs/components'),
+    },
+    {
+      sourceDir: path.resolve(rootDir, '../frappe'),
+      proxyDir: path.resolve(rootDir, 'content/docs/frappe'),
+    },
+  ]
+}
+
+function resolveRoots(options: ColocatedComponentDocsOptions): SourceRootMap[] {
+  if (options.sourceRoots && options.sourceRoots.length) return options.sourceRoots
+  if (options.rootDir) return rootDirRoots(options.rootDir)
+  // No legacy in-repo fallback: warn rather than resolve into nonexistent paths.
+  console.warn(
+    '[colocatedComponentDocs] no sourceRoots or rootDir provided — skipping proxy generation.',
+  )
+  return []
+}
+
+const PROXY_HEADER =
+  '<!-- AUTO-GENERATED by colocatedComponentDocs — do not edit. Source: '
+
+interface Entry {
+  name: string // 'Button'
+  source: string // absolute path to src/components/Button/Button.md
+  proxy: string // absolute path to docs/content/docs/components/button.md
+  proxyDir: string // absolute path to the proxy root that owns this entry
+}
+
+function discover(sourceDir: string, proxyDir: string): Entry[] {
+  if (!fs.existsSync(sourceDir)) return []
+  const entries: Entry[] = []
+  for (const name of fs.readdirSync(sourceDir)) {
+    const source = path.join(sourceDir, name, `${name}.md`)
+    if (!fs.existsSync(source)) continue
+    entries.push({
+      name,
+      source,
+      proxy: path.join(proxyDir, `${name.toLowerCase()}.md`),
+      proxyDir,
+    })
+  }
+  return entries
+}
+
+function proxyContent(entry: Entry) {
+  const includePath = path
+    .relative(path.dirname(entry.proxy), entry.source)
+    .split(path.sep)
+    .join('/')
+  const sourceRel = path
+    .relative(entry.proxyDir, entry.source)
+    .split(path.sep)
+    .join('/')
+  return `${PROXY_HEADER}${sourceRel} -->\n<!-- @include: ${includePath} -->\n`
+}
+
+function isManagedProxy(filePath: string) {
+  if (!fs.existsSync(filePath)) return false
+  const first = fs.readFileSync(filePath, 'utf-8').split('\n', 1)[0] ?? ''
+  return first.startsWith(PROXY_HEADER)
+}
+
+function writeIfChanged(filePath: string, content: string) {
+  if (fs.existsSync(filePath)) {
+    const current = fs.readFileSync(filePath, 'utf-8')
+    if (current === content) return false
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content, 'utf-8')
+  return true
+}
+
+export function syncColocatedComponentDocs(
+  options: ColocatedComponentDocsOptions = {},
+) {
+  const roots = resolveRoots(options)
+  const allEntries: Entry[] = []
+
+  for (const { sourceDir, proxyDir } of roots) {
+    const entries = discover(sourceDir, proxyDir)
+    allEntries.push(...entries)
+    const expected = new Set(entries.map((e) => e.proxy))
+
+    for (const entry of entries) {
+      writeIfChanged(entry.proxy, proxyContent(entry))
+    }
+
+    // Remove orphan proxies — only those we created (header check), so
+    // hand-written legacy pages like badge.md, legacy.md stay untouched.
+    if (fs.existsSync(proxyDir)) {
+      for (const name of fs.readdirSync(proxyDir)) {
+        const filePath = path.join(proxyDir, name)
+        if (expected.has(filePath)) continue
+        if (isManagedProxy(filePath)) fs.unlinkSync(filePath)
+      }
+    }
+  }
+
+  return allEntries
+}
+
+export default function colocatedComponentDocs(
+  options: ColocatedComponentDocsOptions = {},
+): Plugin {
+  const roots = resolveRoots(options)
+  const syncAll = () => syncColocatedComponentDocs(options)
+  return {
+    name: 'colocated-component-docs',
+    enforce: 'pre',
+    buildStart() {
+      syncAll()
+    },
+    configureServer(server: ViteDevServer) {
+      syncAll()
+      const onChange = (file: string) => {
+        const matchesRoot = roots.some(({ sourceDir }) =>
+          file.startsWith(sourceDir),
+        )
+        if (!matchesRoot) return
+        if (!file.endsWith('.md')) return
+        syncAll()
+      }
+      server.watcher.on('add', onChange)
+      server.watcher.on('unlink', onChange)
+    },
+  }
+}

package/vitepress/plugins/componentTransformer.ts

@@ -0,0 +1,286 @@
+import type { MarkdownEnv, MarkdownRenderer } from 'vitepress'
+import type StateCore from 'markdown-it/lib/rules_core/state_core'
+import { existsSync } from 'node:fs'
+import { dirname, isAbsolute, resolve } from 'node:path'
+import {
+  baseParse,
+  NodeTypes,
+  type AttributeNode,
+  type DirectiveNode,
+  type ElementNode,
+  type SimpleExpressionNode,
+  type TextNode,
+} from '@vue/compiler-dom'
+
+export interface ComponentTransformerOptions {
+  // Absolute source root dirs, each holding `<Component>/stories/*.vue` and
+  // `<Component>/types.ts`. When omitted, defaults resolve relative to each
+  // markdown file (backward compatible with the in-repo docs layout).
+  sourceRoots?: string[]
+}
+
+// Resolve configured source roots; empty when no sourceRoots are provided
+// (callers warn rather than silently resolve into nonexistent legacy paths).
+function getRoots(mdDir: string, sourceRoots?: string[]): string[] {
+  if (sourceRoots && sourceRoots.length) {
+    return sourceRoots.map((r) => (isAbsolute(r) ? r : resolve(mdDir, r)))
+  }
+  return []
+}
+
+function warnMissingRoots(tag: string, mdPath: string) {
+  console.warn(
+    `[componentTransformer] <${tag}> in ${mdPath} but no sourceRoots configured — skipping. Pass sourceRoots to defineDocsConfig.`,
+  )
+}
+
+function resolveSourcePath(roots: string[], relativePath: string): string {
+  for (const root of roots) {
+    const candidate = resolve(root, relativePath)
+    if (existsSync(candidate)) return candidate
+  }
+  return resolve(roots[0], relativePath)
+}
+
+interface ParsedTag {
+  /** Static attributes: `foo="bar"` */
+  attrs: Record<string, string>
+  /** Bound attributes: `:foo="expr"` — value is the expression text */
+  binds: Record<string, string>
+}
+
+function parseSingleTag(source: string, tagName: string): ParsedTag | null {
+  let ast
+  try {
+    ast = baseParse(source)
+  } catch {
+    return null
+  }
+  for (const child of ast.children) {
+    if (child.type !== NodeTypes.ELEMENT) continue
+    const element = child as ElementNode
+    if (element.tag !== tagName) continue
+
+    const attrs: Record<string, string> = {}
+    const binds: Record<string, string> = {}
+    for (const prop of element.props) {
+      if (prop.type === NodeTypes.ATTRIBUTE) {
+        const attr = prop as AttributeNode
+        attrs[attr.name] = (attr.value as TextNode | undefined)?.content ?? ''
+      } else if (prop.type === NodeTypes.DIRECTIVE) {
+        const dir = prop as DirectiveNode
+        if (
+          dir.name === 'bind' &&
+          dir.arg?.type === NodeTypes.SIMPLE_EXPRESSION
+        ) {
+          const argName = (dir.arg as SimpleExpressionNode).content
+          const expr = (dir.exp as SimpleExpressionNode | undefined)?.content
+          binds[argName] = expr ?? ''
+        }
+      }
+    }
+    return { attrs, binds }
+  }
+  return null
+}
+
+function getPreviewParts(name: string) {
+  const separatorIndex = name.indexOf('-')
+  if (separatorIndex === -1) {
+    return { componentName: name, storyFileName: name }
+  }
+  return {
+    componentName: name.slice(0, separatorIndex),
+    storyFileName: name.slice(separatorIndex + 1),
+  }
+}
+
+function getStoryImportName(storyFileName: string) {
+  const normalized = storyFileName.replace(/[^a-zA-Z0-9_$]+/g, ' ')
+  const pascal = normalized
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+  return /^[A-Za-z_$]/.test(pascal) ? pascal : `Story${pascal}`
+}
+
+function applyImports(state: StateCore, imports: string[]) {
+  if (imports.length === 0) return
+  const combined = imports.join('\n')
+  const scriptIdx = state.tokens.findIndex(
+    (t) => t.type === 'html_block' && /<script\s+setup>/.test(t.content),
+  )
+  if (scriptIdx === -1) {
+    const token = new state.Token('html_block', '', 0)
+    token.content = `<script setup>\n${combined}\n</script>\n`
+    // Unshifting earlier would shift every other token's index — do it
+    // after the main transform loop so its `tokenIdx` values stay valid.
+    state.tokens.unshift(token)
+  } else {
+    state.tokens[scriptIdx].content = state.tokens[scriptIdx].content.replace(
+      '</script>',
+      `${combined}\n</script>`,
+    )
+  }
+}
+
+function getStoryPath(
+  roots: string[],
+  componentName: string,
+  storyFileName: string,
+) {
+  const moleculeName =
+    componentName.charAt(0).toLowerCase() + componentName.slice(1)
+  const candidates: string[] = []
+  for (const root of roots) {
+    candidates.push(
+      resolve(root, componentName, 'stories', `${storyFileName}.vue`),
+    )
+    candidates.push(
+      resolve(root, moleculeName, 'stories', `${storyFileName}.vue`),
+    )
+  }
+  return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0]
+}
+
+function transformPreview(
+  state: StateCore,
+  tokenIdx: number,
+  tag: ParsedTag,
+  roots: string[],
+): string | null {
+  const name = tag.attrs.name
+  if (!name) return null
+
+  const csr = tag.attrs.csr === 'true'
+  const { componentName, storyFileName } = getPreviewParts(name)
+  const storyImportName = getStoryImportName(storyFileName)
+  const componentPath = getStoryPath(roots, componentName, storyFileName)
+
+  // Forward every static attr except `csr`, which this plugin consumes
+  // itself (it's not a Vue prop). `name` is still a prop on the Demo
+  // component so it gets forwarded along with the rest.
+  const forwardedStatic = Object.entries(tag.attrs)
+    .filter(([key]) => key !== 'csr')
+    .map(([key, value]) => ` ${key}="${value}"`)
+    .join('')
+  const forwardedBinds = Object.entries(tag.binds)
+    .map(([key, expr]) => ` :${key}="${expr}"`)
+    .join('')
+
+  const openWrap = csr ? '<ClientOnly>' : ''
+  const closeWrap = csr ? '</ClientOnly>' : ''
+
+  state.tokens[tokenIdx].content =
+    `${openWrap}<ComponentPreview${forwardedStatic}${forwardedBinds}><${storyImportName} /><template #code>`
+
+  const code = new state.Token('fence', 'code', 0)
+  code.info = 'vue'
+  code.content = `<<< ${componentPath}`
+  // @ts-ignore snippets plugin reads `src` for the absolute path (Token lacks the field in types)
+  code.src = [componentPath]
+
+  const close = new state.Token('html_inline', '', 0)
+  close.content = `</template></ComponentPreview>${closeWrap}`
+
+  state.tokens.splice(tokenIdx + 1, 0, code, close)
+
+  return `import ${storyImportName} from '${componentPath}'`
+}
+
+function transformPropsTable(
+  state: StateCore,
+  tokenIdx: number,
+  tag: ParsedTag,
+  roots: string[],
+) {
+  const name = tag.attrs.name
+  const dataExpr = tag.binds.data
+  if (!name || !dataExpr) return
+
+  // The optional `folder` attribute lets a sub-component (e.g.
+  // DateTimePicker, which lives inside the DatePicker folder) point at
+  // the correct `types.ts`. When omitted, the folder matches `name`.
+  const componentFolder = tag.attrs.folder || name
+  const typesPath = resolveSourcePath(roots, `${componentFolder}/types.ts`)
+
+  state.tokens[tokenIdx].content =
+    `<PropsTable name="${name}" :data="${dataExpr}"><template #code>`
+
+  const code = new state.Token('fence', 'code', 0)
+  code.info = 'typescript'
+  code.content = `<<< ${typesPath}`
+  // @ts-ignore snippets plugin reads `src` for the absolute path (Token lacks the field in types)
+  code.src = [typesPath]
+
+  const close = new state.Token('html_inline', '', 0)
+  close.content = `</template></PropsTable>`
+
+  state.tokens.splice(tokenIdx + 1, 0, code, close)
+}
+
+function install(md: MarkdownRenderer, options: ComponentTransformerOptions) {
+  md.core.ruler.after('inline', 'component-preview', (state) => {
+    const env = state.env as MarkdownEnv
+    // VitePress calls parseInline with an empty env (e.g. title inference);
+    // there's nothing to transform without a source path.
+    const mdPath = env.realPath ?? env.path
+    if (!mdPath) return
+    const mdDir = dirname(mdPath)
+    const roots = getRoots(mdDir, options.sourceRoots)
+    const imports: string[] = []
+
+    // Walk in reverse so splicing in new tokens doesn't shift indices
+    // we haven't visited yet.
+    for (let i = state.tokens.length - 1; i >= 0; i--) {
+      const token = state.tokens[i]
+      if (token.type !== 'html_block' && token.type !== 'html_inline') continue
+
+      // Cheap text prefilter — Vue's parser is fast but no point invoking
+      // it on tokens that clearly don't contain our tags.
+      if (token.content.includes('<ComponentPreview')) {
+        const tag = parseSingleTag(token.content, 'ComponentPreview')
+        if (tag) {
+          if (!roots.length) {
+            warnMissingRoots('ComponentPreview', mdPath)
+            continue
+          }
+          const importStmt = transformPreview(state, i, tag, roots)
+          if (importStmt) imports.push(importStmt)
+        }
+      } else if (token.content.includes('<PropsTable')) {
+        const tag = parseSingleTag(token.content, 'PropsTable')
+        if (tag) {
+          if (!roots.length) {
+            warnMissingRoots('PropsTable', mdPath)
+            continue
+          }
+          transformPropsTable(state, i, tag, roots)
+        }
+      }
+    }
+
+    applyImports(state, imports)
+  })
+}
+
+// Factory: returns a markdown-it plugin bound to the given source roots.
+export function createComponentTransformer(
+  options: ComponentTransformerOptions = {},
+) {
+  return (md: MarkdownRenderer) => install(md, options)
+}
+
+// Backward compatible: usable directly as `md.use(componentTransformer)`
+// (first arg is the renderer) or as a factory `componentTransformer(opts)`.
+export default function componentTransformer(
+  mdOrOptions?: MarkdownRenderer | ComponentTransformerOptions,
+) {
+  if (mdOrOptions && 'core' in (mdOrOptions as MarkdownRenderer)) {
+    return install(mdOrOptions as MarkdownRenderer, {})
+  }
+  return createComponentTransformer(
+    (mdOrOptions as ComponentTransformerOptions) ?? {},
+  )
+}

package/vitepress/plugins/index.ts

@@ -0,0 +1,12 @@
+export {
+  default as componentTransformer,
+  createComponentTransformer,
+  type ComponentTransformerOptions,
+} from './componentTransformer.ts'
+
+export {
+  default as colocatedComponentDocs,
+  syncColocatedComponentDocs,
+  type ColocatedComponentDocsOptions,
+  type SourceRootMap,
+} from './colocatedComponentDocs.ts'

package/vitepress/state.ts

@@ -0,0 +1,10 @@
+import { reactive } from 'vue'
+import type { SidebarSection } from './components/Docs/sidebarList'
+
+// Shared cross-component UI state for the docs layout.
+export const state = reactive({
+  mobsidebar: false,
+  mobnavbar: false,
+  searchDialog: false,
+  sidebarList: [] as SidebarSection[],
+})