@poveste/plugin-vue 0.20.0 → 0.21.0

package/dist/util/project-vue.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+export function projectVueVersion(root) {
+    try {
+        const manifest = createRequire(join(root, 'package.json')).resolve('vue/package.json');
+        return JSON.parse(readFileSync(manifest, 'utf8')).version;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@poveste/plugin-vue",
   "type": "module",
-  "version": "0.20.0",
-  "description": "Poveste plugin for Vue.js support",
+  "version": "0.21.0",
+  "description": "Poveste plugin for Vue 3: stories as .vue files, controls, and a props, slots and events table read from your components' types",
   "author": {
     "name": "Sorin Gitlan",
     "url": "https://x.com/50rayn"
@@ -41,6 +41,10 @@
       "types": "./dist/client/server.d.ts",
       "default": "./dist/bundled/client/server.js"
     },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/bundled/testing/index.js"
+    },
     "./components": {
       "types": "./components.d.ts"
     },
@@ -66,19 +70,26 @@
     "collect.d.ts",
     "components.d.ts",
     "dist",
-    "src"
+    "src",
+    "testing.d.ts"
   ],
   "engines": {
     "node": ">=22.22.2"
   },
   "peerDependencies": {
-    "poveste": "^0.20.0",
+    "poveste": "^0.21.0",
+    "vitest": "^5.0.0",
     "vue": "^3.5.43"
   },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "dependencies": {
-    "@poveste/controls": "^0.20.0",
-    "@poveste/shared": "^0.20.0",
-    "@poveste/vendors": "^0.20.0",
+    "@poveste/controls": "^0.21.0",
+    "@poveste/shared": "^0.21.0",
+    "@poveste/vendors": "^0.21.0",
     "change-case": "^5.4.4",
     "ignore": "^7.0.10",
     "launch-editor": "^2.14.2",
@@ -87,12 +98,17 @@
     "vue-component-meta": "^3.3.13"
   },
   "devDependencies": {
+    "@fontsource/fira-mono": "^5.3.0",
+    "@tailwindcss/oxide": "^4.3.3",
     "@types/node": "^26.6.5",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "@vitest/browser-playwright": "5.0.5",
     "concurrently": "^10.0.6",
-    "poveste": "0.20.0",
+    "jsdom": "^30.1.3",
+    "poveste": "0.21.0",
     "typescript": "6.0.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.4",
+    "vitest": "^5.0.5",
     "vue": "^3.5.44",
     "vue-vapor-rc": "npm:vue@3.6.0-rc.10"
   },
@@ -101,6 +117,7 @@
     "build:types": "tsc --declaration --emitDeclarationOnly",
     "watch": "concurrently \"vite build --watch\" \"tsc -d -P tsconfig.build.json --watch\" \"pnpm run build:types --watch\"",
     "test": "vitest run",
+    "test:story-tests": "vitest run --config vitest.story-tests.config.ts",
     "test:dev": "vitest"
   }
 }

package/src/client/app/Story.ts

@@ -1,11 +1,11 @@
 import type { Story } from '@poveste/shared'
-import type { PropType, VNode } from 'vue'
+import type { Component, PropType, VNode } from 'vue'
 import type { PreviewRenderContext } from './render-context.js'
 import { omitInheritStoryProps } from '@poveste/shared'
 import { cloneVNode, computed, defineComponent, h, isRef, reactive, useAttrs } from 'vue'
 import { implicitStateContext, storyContext } from './context.js'
 import { useRenderContext } from './render-context.js'
-import { isWritableBinding, useInstance } from './util.js'
+import { holdsVueApp, isComponentBinding, isWritableBinding, useInstance } from './util.js'
 import Variant from './Variant.js'
 
 export default defineComponent({
@@ -25,6 +25,18 @@ export default defineComponent({
       type: Object as PropType<Story['meta']>,
       default: undefined,
     },
+
+    // Read at collection; declared so it is not passed on to the variants (#1398).
+    autoDocs: {
+      type: [Boolean, Array] as PropType<Story['autoDocs']>,
+      default: undefined,
+    },
+
+    // The components the Docs tab documents, read from the source by auto-docs (#1432).
+    component: {
+      type: [Object, Function, Array] as PropType<Component | Component[]>,
+      default: undefined,
+    },
   },
 
   setup(props) {
@@ -53,7 +65,7 @@ export default defineComponent({
     function addImplicitState(source: Record<string, any>, key: string) {
       const value = source[key]
 
-      if (typeof value === 'function' || (value?.__file) || typeof value?.render === 'function' || typeof value?.setup === 'function') {
+      if (isComponentBinding(value) || holdsVueApp(value)) {
         return
       }
 

package/src/client/app/global-components.ts

@@ -28,6 +28,10 @@ export function registerGlobalComponents(app: App) {
 
   app.component('Variant', Variant)
 
+  registerControlComponents(app)
+}
+
+export function registerControlComponents(app: App) {
   for (const [key, component] of Object.entries(components)) {
     app.component(key, wrapControlComponent(component))
   }

package/src/client/app/host.ts

@@ -27,6 +27,13 @@ interface PreviewHostOptions {
   getVariant: () => Variant | null
   renderContext: PreviewRenderContext
   wrapInDiv?: boolean
+  /** A story test's: what the app would only log, it fails on. */
+  onError?: (err: unknown) => void
+  onWarn?: (message: string, trace: string) => void
+  /** A story test's: when the render's async setups have settled. */
+  onResolve?: () => void
+  /** A story test's, run after the app's own registrations and setup hooks. */
+  configureApp?: (app: App) => void
 }
 
 const PreviewHostRoot = defineComponent({
@@ -86,7 +93,7 @@ export function createPreviewHost(options: PreviewHostOptions) {
           vnode = h('div', vnode)
         }
 
-        return h(Suspense, {}, vnode)
+        return h(Suspense, options.onResolve ? { onResolve: options.onResolve } : {}, vnode)
       },
     })
 
@@ -98,7 +105,17 @@ export function createPreviewHost(options: PreviewHostOptions) {
         storyId: options.getStory()?.id,
         variantId: options.getVariant()?.id,
       })
-      console.error(err)
+      if (options.onError) {
+        options.onError(err)
+      }
+      else {
+        console.error(err)
+      }
+    }
+
+    if (options.onWarn) {
+      const onWarn = options.onWarn
+      app.config.warnHandler = (message, _instance, trace) => onWarn(message, trace)
     }
 
     // From Vue 3.6, a Vapor component inside a VDOM tree mounts only through this
@@ -123,6 +140,8 @@ export function createPreviewHost(options: PreviewHostOptions) {
 
     await runSetupHooks(setupApi)
 
+    options.configureApp?.(app)
+
     app.mount(target)
   }
 

package/src/client/app/util.ts

@@ -235,6 +235,46 @@ export function isWritableBinding(value: unknown): boolean {
   return !(isRef(value) && isReadonly(value))
 }
 
+/**
+ * A component a story holds in its setup, which implicit state skips.
+ *
+ * Each key is asked with `in` before it is read. Nuxt's runtime config is, in
+ * dev, a proxy that warns on any key it does not carry, and reading `__file`,
+ * `render` and `setup` off it printed `NUXT_E1003` three times a mount (#1454).
+ */
+export function isComponentBinding(value: unknown): boolean {
+  if (typeof value === 'function') {
+    return true
+  }
+  if (!isObject(value)) {
+    return false
+  }
+  return ('__file' in value && !!value.__file)
+    || ('render' in value && typeof value.render === 'function')
+    || ('setup' in value && typeof value.setup === 'function')
+}
+
+function isVueApp(value: unknown): boolean {
+  return isObject(value) && '_context' in value && '_component' in value && 'mount' in value
+}
+
+/**
+ * A Vue app, or an object holding one in a data property of its own, as the
+ * Nuxt app `useNuxtApp()` returns does. Implicit state skips it: the state sync
+ * deep-watches what it holds, so it walked the whole app on every sync, as far
+ * as the dev-only `app.config.compilerOptions` getter that warns when read
+ * (#1457). Read through descriptors, so no getter runs to find out.
+ */
+export function holdsVueApp(value: unknown): boolean {
+  if (!isObject(value)) {
+    return false
+  }
+  if (isVueApp(value)) {
+    return true
+  }
+  return Object.values(Object.getOwnPropertyDescriptors(value)).some(descriptor => 'value' in descriptor && isVueApp(descriptor.value))
+}
+
 export function useInstance(name: string): ComponentInternalInstance {
   const vm = getCurrentInstance()
   if (!vm) {

package/src/client/server/Story.ts

@@ -1,5 +1,5 @@
-import type { ServerStory, ServerVariant } from '@poveste/shared'
-import type { PropType } from 'vue'
+import type { AutoDocsSection, ServerStory, ServerVariant } from '@poveste/shared'
+import type { Component, PropType } from 'vue'
 import { defineComponent, onMounted } from 'vue'
 import { addStoryContext, addVariantContext, serverStoryContext, storyFileContext } from './context.js'
 import { autoStubComponents } from './stub.js'
@@ -45,6 +45,18 @@ export default defineComponent({
       default: false,
     },
 
+    // A default, so an absent prop stays `undefined` rather than Vue's `false` for a Boolean.
+    autoDocs: {
+      type: [Boolean, Array] as PropType<boolean | AutoDocsSection[]>,
+      default: undefined,
+    },
+
+    // Read from the source by auto-docs, not at collection (#1432).
+    component: {
+      type: [Object, Function, Array] as PropType<Component | Component[]>,
+      default: undefined,
+    },
+
     meta: {
       type: Object as PropType<ServerStory['meta']>,
       default: undefined,
@@ -70,6 +82,7 @@ export default defineComponent({
       icon: props.icon,
       iconColor: props.iconColor,
       docsOnly: props.docsOnly,
+      ...props.autoDocs !== undefined ? { autoDocs: props.autoDocs } : {},
       meta: props.meta,
       variants: [],
     }

package/src/client/server/collect.ts

@@ -0,0 +1,83 @@
+import type { ServerRunPayload, ServerStory } from '@poveste/shared'
+import type { App, Component } from 'vue'
+import type { Vue3StorySetupApi, Vue3StorySetupHandler } from '../../helpers.js'
+import { getSetupHook } from '@poveste/shared'
+// @ts-expect-error virtual module id
+import * as generatedSetup from 'virtual:$poveste-generated-global-setup'
+// @ts-expect-error virtual module id
+import * as setup from 'virtual:$poveste-setup'
+import { createApp, h } from 'vue'
+import { VUE_SETUP_HOOK_NAMES } from '../../setup-hooks.js'
+import { addStoryContext, storyFileContext } from './context.js'
+import Story from './Story.js'
+import Variant from './Variant.js'
+
+/**
+ * Collects a story file's component that is already imported. Story tests get
+ * it from their own import, so no `moduleId` has to be a URL in the browser.
+ */
+export async function collectComponent(
+  Comp: Component & { doc?: string },
+  { file, storyData, el }: ServerRunPayload,
+  hooks: {
+    /** Before the setup hooks, so what they report is seen. */
+    beforeSetup?: (app: App) => void
+    /** After them, so what it adds fills gaps rather than replacing the app's own. */
+    afterSetup?: (app: App) => void
+  } = {},
+) {
+  const app = createApp({
+    // Provided from `setup` rather than the options object so the keys can be
+    // the symbols the components inject; the options form takes string keys.
+    setup() {
+      addStoryContext.provide((data: ServerStory) => {
+        storyData.push(data)
+      })
+      storyFileContext.provide(file)
+    },
+    render() {
+      return h(Comp)
+    },
+  })
+
+  app.component('Story', Story)
+
+  app.component('Variant', Variant)
+
+  hooks.beforeSetup?.(app)
+
+  // Call app setups to resolve global assets such as components
+
+  const setupApi: Vue3StorySetupApi = {
+    app,
+    // No story or variant exists while collecting.
+    story: undefined,
+    variant: undefined,
+    addWrapper: () => { /* noop */ },
+  }
+
+  const generatedSetupFn = getSetupHook<Vue3StorySetupHandler>(generatedSetup, VUE_SETUP_HOOK_NAMES)
+  if (generatedSetupFn) {
+    await generatedSetupFn(setupApi)
+  }
+
+  const setupFn = getSetupHook<Vue3StorySetupHandler>(setup, VUE_SETUP_HOOK_NAMES)
+  if (setupFn) {
+    await setupFn(setupApi)
+  }
+
+  hooks.afterSetup?.(app)
+
+  app.mount(el)
+
+  if (Comp.doc) {
+    const el = document.createElement('div')
+    el.innerHTML = Comp.doc
+    const text = el.textContent
+    storyData.forEach((s) => {
+      s.docsText = text
+    })
+  }
+
+  app.unmount()
+}

package/src/client/server/run.ts

@@ -1,67 +1,7 @@
-import type { ServerRunPayload, ServerStory } from '@poveste/shared'
-import type { Vue3StorySetupApi, Vue3StorySetupHandler } from '../../helpers.js'
-import { getSetupHook } from '@poveste/shared'
-// @ts-expect-error virtual module id
-import * as generatedSetup from 'virtual:$poveste-generated-global-setup'
-// @ts-expect-error virtual module id
-import * as setup from 'virtual:$poveste-setup'
-import { createApp, h } from 'vue'
-import { VUE_SETUP_HOOK_NAMES } from '../../setup-hooks.js'
-import { addStoryContext, storyFileContext } from './context.js'
-import Story from './Story.js'
-import Variant from './Variant.js'
+import type { ServerRunPayload } from '@poveste/shared'
+import { collectComponent } from './collect.js'
 
 export async function run({ file, storyData, el }: ServerRunPayload) {
   const { default: Comp } = await import(/* @vite-ignore */ file.moduleId)
-
-  const app = createApp({
-    // Provided from `setup` rather than the options object so the keys can be
-    // the symbols the components inject; the options form takes string keys.
-    setup() {
-      addStoryContext.provide((data: ServerStory) => {
-        storyData.push(data)
-      })
-      storyFileContext.provide(file)
-    },
-    render() {
-      return h(Comp)
-    },
-  })
-
-  app.component('Story', Story)
-
-  app.component('Variant', Variant)
-
-  // Call app setups to resolve global assets such as components
-
-  const setupApi: Vue3StorySetupApi = {
-    app,
-    // No story or variant exists while collecting.
-    story: undefined,
-    variant: undefined,
-    addWrapper: () => { /* noop */ },
-  }
-
-  const generatedSetupFn = getSetupHook<Vue3StorySetupHandler>(generatedSetup, VUE_SETUP_HOOK_NAMES)
-  if (generatedSetupFn) {
-    await generatedSetupFn(setupApi)
-  }
-
-  const setupFn = getSetupHook<Vue3StorySetupHandler>(setup, VUE_SETUP_HOOK_NAMES)
-  if (setupFn) {
-    await setupFn(setupApi)
-  }
-
-  app.mount(el)
-
-  if (Comp.doc) {
-    const el = document.createElement('div')
-    el.innerHTML = Comp.doc
-    const text = el.textContent
-    storyData.forEach((s) => {
-      s.docsText = text
-    })
-  }
-
-  app.unmount()
+  await collectComponent(Comp, { file, storyData, el })
 }

package/src/client-dependencies.ts

@@ -0,0 +1,2 @@
+/** What the client code imports from npm, for the optimizer to bundle up front. */
+export const CLIENT_DEPENDENCIES = ['change-case']

package/src/docgen/events.ts

@@ -0,0 +1,55 @@
+import type ts from 'typescript'
+
+export interface EventDoc {
+  description: string
+  tags: { name: string, text?: string }[]
+}
+
+/*
+ * vue-component-meta reads an event's JSDoc off the component's `$emit` signatures,
+ * and those are Vue's own `EmitFn` in `runtime-core.d.ts`, built from the declared
+ * type: the comment is never on them, so every event came back without a
+ * description or a tag (#1462). Volar keeps the `defineEmits` type argument, comments
+ * and all, as a `__VLS_Emit` alias in the generated code, and this reads it there,
+ * through the same program, so an emits type imported from another file resolves too.
+ */
+// Not only at the top: a `generic` setup, or a `<script>` block beside `<script setup>`,
+// puts the setup, and the alias with it, inside the component's initializer.
+function findEmitAlias(typescript: typeof ts, node: ts.Node): ts.TypeAliasDeclaration | undefined {
+  if (typescript.isTypeAliasDeclaration(node) && node.name.text === '__VLS_Emit') {
+    return node
+  }
+  return typescript.forEachChild(node, child => findEmitAlias(typescript, child))
+}
+
+export function readEventDocs(typescript: typeof ts, program: ts.Program | undefined, file: string): Map<string, EventDoc> {
+  const docs = new Map<string, EventDoc>()
+  const source = program?.getSourceFile(file)
+  const alias = source && findEmitAlias(typescript, source)
+  if (!program || !alias) {
+    return docs
+  }
+
+  const checker = program.getTypeChecker()
+  const type = checker.getTypeAtLocation(alias.name)
+  const tagsOf = (tags: ts.JSDocTagInfo[]) => tags.map(({ name, text }) => text?.length ? { name, text: typescript.displayPartsToString(text) } : { name })
+
+  // `change: [value: string]`
+  for (const property of type.getProperties()) {
+    docs.set(property.name, {
+      description: typescript.displayPartsToString(property.getDocumentationComment(checker)),
+      tags: tagsOf(property.getJsDocTags(checker)),
+    })
+  }
+  // `(event: 'change', value: string): void`
+  for (const signature of type.getCallSignatures()) {
+    const event = signature.parameters[0] && checker.getTypeOfSymbol(signature.parameters[0])
+    if (event?.isStringLiteral()) {
+      docs.set(event.value, {
+        description: typescript.displayPartsToString(signature.getDocumentationComment(checker)),
+        tags: tagsOf(signature.getJsDocTags()),
+      })
+    }
+  }
+  return docs
+}

package/src/docgen/extractor.ts

@@ -1,34 +1,54 @@
 import type { DocgenExtractor, DocgenExtractorContext } from '@poveste/shared'
+import type ts from 'typescript'
 import type { VueDocgenOptions } from './meta.js'
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'pathe'
+import { createRequire } from 'node:module'
+import { findTsconfig } from 'poveste/docgen'
+import { readEventDocs } from './events.js'
+import { readGeneric } from './generic.js'
 import { toComponentDoc } from './meta.js'
+import { readSlotProps } from './slots.js'
 
-// `tsconfig.app.json` first: Vite's Vue template splits the app's settings into it
-// and leaves `tsconfig.json` holding only references, which type nothing.
-const TSCONFIGS = ['tsconfig.app.json', 'tsconfig.json']
 const SOURCE = /\.(?:vue|[cm]?[jt]sx?)$/
 
-export function findTsconfig(root: string) {
-  return TSCONFIGS.map(name => join(root, name)).find(file => existsSync(file))
-}
-
 /**
  * Runs in the docgen worker. `vue-component-meta` is imported here rather than at
  * the top, so a book without TypeScript fails this one request, answered with its
  * error, and keeps its runtime props.
  */
 export async function createExtractor(context: DocgenExtractorContext): Promise<DocgenExtractor> {
-  const { createChecker, createCheckerByJson } = await import('vue-component-meta')
+  const { createChecker, createCheckerByJson, TypeMeta } = await import('vue-component-meta')
   const options = (context.options ?? {}) as VueDocgenOptions
   const checkerOptions = { forceUseTs: true, printer: { newLine: 1 } }
   const tsconfig = findTsconfig(context.root)
+  // The copy vue-component-meta loaded, so the syntax kinds match the program it builds.
+  const typescript: typeof ts = createRequire(createRequire(import.meta.url).resolve('vue-component-meta'))('typescript')
   const checker = tsconfig
     ? createChecker(tsconfig, checkerOptions)
     : createCheckerByJson(context.root, { include: ['**/*'], exclude: ['node_modules'] }, checkerOptions)
 
+  // A script file is offered for its default export, which is a component only when it is
+  // `defineComponent`'s: a function, a helper or a plain object throws or reads as Unknown.
+  function scriptComponent(file: string) {
+    try {
+      const meta = checker.getComponentMeta(file, 'default')
+      return meta.type === TypeMeta.Unknown ? undefined : meta
+    }
+    catch {
+      return undefined
+    }
+  }
+
   return {
-    extract: file => toComponentDoc(checker.getComponentMeta(file), options),
+    extract(file) {
+      const meta = file.endsWith('.vue') ? checker.getComponentMeta(file) : scriptComponent(file)
+      if (!meta) {
+        return undefined
+      }
+      const doc = toComponentDoc(meta, options, meta.events.length ? readEventDocs(typescript, checker.getProgram(), file) : undefined, slot => readSlotProps(typescript, checker.getProgram(), slot))
+      const generic = file.endsWith('.vue') ? readGeneric(readFileSync(file, 'utf8')) : undefined
+      return generic ? { ...doc, generic } : doc
+    },
     update(file) {
       if (!SOURCE.test(file)) {
         return

package/src/docgen/generic.ts

@@ -0,0 +1,20 @@
+// A tag's attributes may hold a `>`, as `generic="T extends Record<string, unknown>"` does,
+// so a quoted value is read whole rather than ending the tag.
+const SCRIPT_TAG = /<script\b((?:[^>"']|"[^"]*"|'[^']*')*)>/g
+const SETUP = /(?:^|\s)setup(?=[\s=]|$)/
+const GENERIC = /(?:^|\s)generic\s*=\s*(?:"([^"]*)"|'([^']*)')/
+
+/**
+ * The type parameters a `<script setup generic="…">` declares, constraints and defaults
+ * included, so a table that prints `T | T[]` can say what `T` may be (#1436).
+ */
+export function readGeneric(source: string): string | undefined {
+  for (const [, attributes] of source.matchAll(SCRIPT_TAG)) {
+    if (SETUP.test(attributes!)) {
+      const found = GENERIC.exec(attributes!)
+      const generic = (found?.[1] ?? found?.[2])?.replace(/\s+/g, ' ').trim()
+      return generic || undefined
+    }
+  }
+  return undefined
+}