@poveste/plugin-vue 0.19.1 → 0.20.0

package/dist/bundled/client/app/MountStory.js

@@ -1,8 +1,9 @@
-import { createPreviewHost as e } from "./host.js";
-import { defineComponent as t, h as n, onMounted as r, onUnmounted as i, ref as a, watch as o } from "@poveste/vendors/vue";
-import { reactive as s } from "vue";
+import { warnIfForeignVue as e } from "./util.js";
+import { createPreviewHost as t } from "./host.js";
+import { defineComponent as n, h as r, onMounted as i, onUnmounted as a, ref as o, watch as s } from "@poveste/vendors/vue";
+import { reactive as c } from "vue";
 //#region src/client/app/MountStory.ts
-var c = t({
+var l = n({
 	name: "MountStory",
 	props: {
 		story: {
@@ -18,43 +19,44 @@ var c = t({
 			default: !0
 		}
 	},
-	setup(t) {
-		let n = a(), c = s({
+	setup(n) {
+		e("MountStory");
+		let r = o(), l = c({
 			mode: "mount",
 			slotName: "default",
 			currentVariant: null,
-			targetVariantId: t.targetVariantId,
-			syncState: t.syncState,
+			targetVariantId: n.targetVariantId,
+			syncState: n.syncState,
 			externalState: null,
 			nextVariantIndex: { value: 0 }
-		}), l = null;
-		async function u() {
-			n.value && (l = e({
+		}), u = null;
+		async function d() {
+			r.value && (u = t({
 				name: "MountStorySubApp",
-				el: n.value,
-				getStory: () => t.story,
+				el: r.value,
+				getStory: () => n.story,
 				getVariant: () => null,
-				renderContext: c
-			}), await l.mount());
+				renderContext: l
+			}), await u.mount());
 		}
-		function d() {
-			l?.unmount(), l = null;
+		function f() {
+			u?.unmount(), u = null;
 		}
-		return o(() => t.story.id, async () => {
-			d(), await u();
-		}), r(async () => {
-			await u();
-		}), o(() => t.story.variants, () => {
-			l?.forceUpdate();
-		}), o(() => t.targetVariantId, (e) => {
-			c.targetVariantId = e;
-		}), i(() => {
-			d();
-		}), { el: n };
+		return s(() => n.story.id, async () => {
+			f(), await d();
+		}), i(async () => {
+			await d();
+		}), s(() => n.story.variants, () => {
+			u?.forceUpdate();
+		}), s(() => n.targetVariantId, (e) => {
+			l.targetVariantId = e;
+		}), a(() => {
+			f();
+		}), { el: r };
 	},
 	render() {
-		return n("div", { ref: "el" });
+		return r("div", { ref: "el" });
 	}
 });
 //#endregion
-export { c as default };
+export { l as default };

package/dist/bundled/client/app/RenderStory.js

@@ -1,9 +1,9 @@
-import { syncStateBundledAndExternal as e } from "./util.js";
-import { createPreviewHost as t } from "./host.js";
-import { defineComponent as n, h as r, onBeforeUnmount as i, onMounted as a, ref as o, watch as s } from "@poveste/vendors/vue";
-import { reactive as c } from "vue";
+import { syncStateBundledAndExternal as e, warnIfForeignVue as t } from "./util.js";
+import { createPreviewHost as n } from "./host.js";
+import { defineComponent as r, h as i, onBeforeUnmount as a, onMounted as o, ref as s, watch as c } from "@poveste/vendors/vue";
+import { reactive as l } from "vue";
 //#region src/client/app/RenderStory.ts
-var l = n({
+var u = r({
 	name: "RenderStory",
 	props: {
 		variant: {
@@ -20,54 +20,49 @@ var l = n({
 		}
 	},
 	emits: { ready: () => !0 },
-	setup(n, { emit: r }) {
-		let l = o(), u = null, d = !1, f = c({}), p = e(n.variant.state, f), m = c({
+	setup(r, { emit: i }) {
+		t("RenderStory");
+		let u = s(), d = null, f = !1, p = l({}), m = e(r.variant.state, p), h = l({
 			mode: "render",
-			slotName: n.slotName,
-			currentVariant: n.variant,
-			externalState: f,
+			slotName: r.slotName,
+			currentVariant: r.variant,
+			externalState: p,
 			nextVariantIndex: { value: 0 }
 		});
-		function h() {
-			u?.unmount(), u = null;
-		}
 		function g() {
-			p?.stop(), p = e(n.variant.state, f);
+			d?.unmount(), d = null;
+		}
+		function _() {
+			m?.stop(), m = e(r.variant.state, p);
 		}
-		async function _() {
-			if (!d) {
-				if (d = !0, h(), m.currentVariant = n.variant, m.slotName = n.slotName, !l.value) {
-					d = !1;
-					return;
-				}
-				u = t({
-					name: "RenderStorySubApp",
-					el: l.value,
-					getStory: () => n.story,
-					getVariant: () => n.variant,
-					renderContext: m,
-					wrapInDiv: !0
-				}), await u.mount(), d = !1, r("ready");
-			}
+		async function v() {
+			f || (f = !0, g(), h.currentVariant = r.variant, h.slotName = r.slotName, u.value ? (d = n({
+				name: "RenderStorySubApp",
+				el: u.value,
+				getStory: () => r.story,
+				getVariant: () => r.variant,
+				renderContext: h,
+				wrapInDiv: !0
+			}), await d.mount(), f = !1, i("ready")) : f = !1);
 		}
-		return a(async () => {
-			n.variant.configReady && await _();
-		}), s(() => n.variant, () => {
-			m.currentVariant = n.variant, g();
-		}), s(() => [
-			n.story.id,
-			n.slotName,
-			n.variant.id,
-			n.variant.configReady
+		return o(async () => {
+			r.variant.configReady && await v();
+		}), c(() => r.variant, () => {
+			h.currentVariant = r.variant, _();
+		}), c(() => [
+			r.story.id,
+			r.slotName,
+			r.variant.id,
+			r.variant.configReady
 		], async ([, e]) => {
-			m.currentVariant = n.variant, m.slotName = e, n.variant.configReady && !d && (u ? u.forceUpdate() : await _());
-		}), i(() => {
-			p?.stop(), h();
-		}), { sandbox: l };
+			h.currentVariant = r.variant, h.slotName = e, r.variant.configReady && !f && (d ? d.forceUpdate() : await v());
+		}), a(() => {
+			m?.stop(), g();
+		}), { sandbox: u };
 	},
 	render() {
-		return r("div", { ref: "sandbox" });
+		return i("div", { ref: "sandbox" });
 	}
 });
 //#endregion
-export { l as default };
+export { u as default };

package/dist/bundled/client/app/Story.js

@@ -69,16 +69,12 @@ var m = c({
 		function x() {
 			let e = 0, t = m?.targetVariantId, n = t ? l.story.variants.findIndex((e) => e.id === t) : -1, r = (t) => {
 				let i = [];
-				for (let s of t) {
-					if (s.type?.__povesteType === "variant") {
-						let t = l.story.variants[e];
-						if (e++, !t || n !== -1 && e - 1 !== n) continue;
-						let r = { variant: t };
-						s.key ?? (r.key = t.id), !s.props?.initState && !s.props?.["init-state"] && (r.initState = a.initState), Object.assign(r, b(s)), i.push(o(s, r));
-						continue;
-					}
-					Array.isArray(s.children) && (s.children = r(s.children)), i.push(s);
-				}
+				for (let s of t) if (s.type?.__povesteType === "variant") {
+					let t = l.story.variants[e];
+					if (e++, !t || n !== -1 && e - 1 !== n) continue;
+					let r = { variant: t };
+					s.key ?? (r.key = t.id), !s.props?.initState && !s.props?.["init-state"] && (r.initState = a.initState), Object.assign(r, b(s)), i.push(o(s, r));
+				} else Array.isArray(s.children) && (s.children = r(s.children)), i.push(s);
 				return i;
 			};
 			return r(c.slots.default?.() ?? []);
@@ -98,13 +94,7 @@ var m = c({
 				if (t !== -1) {
 					let r = 0, i = !1, a = (e) => {
 						let n = [];
-						for (let s of e) {
-							if (s?.type?.__povesteType === "variant") {
-								r === t && (n.push(o(s, b(s))), i = !0), r++;
-								continue;
-							}
-							Array.isArray(s?.children) && s.children.length && (s.children = a(s.children)), n.push(s);
-						}
+						for (let s of e) s?.type?.__povesteType === "variant" ? (r === t && (n.push(o(s, b(s))), i = !0), r++) : (Array.isArray(s?.children) && s.children.length && (s.children = a(s.children)), n.push(s));
 						return n;
 					}, s = a(n);
 					if (i) return e.nextVariantIndex.value = t, s;

package/dist/bundled/client/app/util.js

@@ -1,66 +1,66 @@
-import { isRef as e, unref as t, watch as n } from "@poveste/vendors/vue";
-import { getCurrentInstance as r, isReadonly as i, isRef as a, markRaw as o, unref as s, watch as c } from "vue";
-import { applyState as l, createStateBaseline as u, isMarkedRaw as d, isPlainObject as f } from "@poveste/shared";
+import { getCurrentInstance as e, isRef as t, unref as n, watch as r } from "@poveste/vendors/vue";
+import { getCurrentInstance as i, isReadonly as a, isRef as o, markRaw as s, unref as c, watch as l } from "vue";
+import { applyState as u, createStateBaseline as d, isMarkedRaw as f, isPlainObject as p } from "@poveste/shared";
 //#region src/client/app/util.ts
-var p = (e) => typeof e == "object" && !!e;
-function m(e, t = /* @__PURE__ */ new WeakMap()) {
-	let n = a(e) ? s(e) : e;
+var m = (e) => typeof e == "object" && !!e;
+function h(e, t = /* @__PURE__ */ new WeakMap()) {
+	let n = o(e) ? c(e) : e;
 	if (typeof n == "symbol") return n.toString();
-	if (!p(n) || d(n)) return n;
+	if (!m(n) || f(n)) return n;
 	if (t.has(n)) return t.get(n);
-	if (!Array.isArray(n) && !f(n)) return o(n);
+	if (!Array.isArray(n) && !p(n)) return s(n);
 	if (Array.isArray(n)) {
 		let e = [];
-		return t.set(n, e), e.push(...n.map((e) => m(e, t))), e;
+		return t.set(n, e), e.push(...n.map((e) => h(e, t))), e;
 	}
 	{
 		let e = {};
-		return t.set(n, e), h(n, e, t), e;
+		return t.set(n, e), g(n, e, t), e;
 	}
 }
-function h(e, t, n = /* @__PURE__ */ new WeakMap()) {
+function g(e, t, n = /* @__PURE__ */ new WeakMap()) {
 	Object.keys(e).forEach((r) => {
-		t[r] = m(e[r], n);
+		t[r] = h(e[r], n);
 	});
 }
-function g(n, r = /* @__PURE__ */ new WeakMap()) {
-	let i = e(n) ? t(n) : n;
+function _(e, r = /* @__PURE__ */ new WeakMap()) {
+	let i = t(e) ? n(e) : e;
 	if (typeof i == "symbol") return i.toString();
-	if (!p(i) || d(i)) return i;
+	if (!m(i) || f(i)) return i;
 	if (r.has(i)) return r.get(i);
-	if (!Array.isArray(i) && !f(i)) return o(i);
+	if (!Array.isArray(i) && !p(i)) return s(i);
 	if (Array.isArray(i)) {
 		let e = [];
-		return r.set(i, e), e.push(...i.map((e) => g(e, r))), e;
+		return r.set(i, e), e.push(...i.map((e) => _(e, r))), e;
 	}
 	{
 		let e = {};
-		return r.set(i, e), _(i, e, r), e;
+		return r.set(i, e), v(i, e, r), e;
 	}
 }
-function _(e, t, n = /* @__PURE__ */ new WeakMap()) {
+function v(e, t, n = /* @__PURE__ */ new WeakMap()) {
 	Object.keys(e).forEach((r) => {
-		t[r] = g(e[r], n);
+		t[r] = _(e[r], n);
 	});
 }
-function v(e, t) {
+function y(e, t) {
 	if (!t.length) return e;
 	let n = { ...e };
 	for (let e of t) delete n[e];
 	return n;
 }
-function y(e, t, r = []) {
-	let i = u(), a = n(() => e, (e) => {
+function b(e, t, n = []) {
+	let i = d(), a = r(() => e, (e) => {
 		if (e == null) return;
-		let n = i.take(v(g(e), r));
-		n && l(t, n);
+		let r = i.take(y(_(e), n));
+		r && u(t, r);
 	}, {
 		deep: !0,
 		immediate: !0
-	}), o = c(() => t, (t) => {
+	}), o = l(() => t, (t) => {
 		if (t == null) return;
-		let n = i.take(v(m(t), r));
-		n && l(e, n);
+		let r = i.take(y(h(t), n));
+		r && u(e, r);
 	}, {
 		deep: !0,
 		immediate: !0
@@ -69,13 +69,17 @@ function y(e, t, r = []) {
 		a(), o();
 	} };
 }
-function b(e) {
-	return !(a(e) && i(e));
-}
 function x(e) {
-	let t = r();
+	return !(o(e) && a(e));
+}
+function S(e) {
+	let t = i();
 	if (!t) throw Error(`[poveste] <${e}> can only be set up inside a component`);
 	return t;
 }
+var C = !1;
+function w(t) {
+	C || e() || (C = !0, console.warn(`[poveste] ${t} was rendered by a copy of Vue other than \`@poveste/vendors/vue\`, so it renders nothing. Poveste's client components are built against that copy: create the app with \`createApp\` from \`@poveste/vendors/vue\`, not from \`vue\`.`));
+}
 //#endregion
-export { g as _toRawDeep, b as isWritableBinding, y as syncStateBundledAndExternal, m as toRawDeep, x as useInstance };
+export { _ as _toRawDeep, x as isWritableBinding, b as syncStateBundledAndExternal, h as toRawDeep, S as useInstance, w as warnIfForeignVue };

package/dist/bundled/client/server.js

@@ -1,2 +1 @@
-import { run as e } from "./server/run.js";
-export { e as run };
+export { run } from "./server/run.js";

package/dist/client/app/util.d.ts

@@ -50,3 +50,15 @@ export declare function syncStateBundledAndExternal(bundledState: Record<string,
  */
 export declare function isWritableBinding(value: unknown): boolean;
 export declare function useInstance(name: string): ComponentInternalInstance;
+/**
+ * Warns, once, when a component built against `@poveste/vendors/vue` is
+ * rendered by another copy of Vue.
+ *
+ * The other copy runs the component's `setup`, so the vendored one has no
+ * current instance and drops every hook: the story renders nothing, and no build
+ * of Vue says why. A test mounting `MountStory` with `createApp` from `vue` read
+ * it as a story with no variants (#940).
+ */
+export declare function warnIfForeignVue(component: string): void;
+/** For specs: lets the warning be seen again. */
+export declare function resetForeignVueWarning(): void;

package/dist/docgen/extractor.d.ts

@@ -0,0 +1,8 @@
+import type { DocgenExtractor, DocgenExtractorContext } from '@poveste/shared';
+export declare function findTsconfig(root: string): string | undefined;
+/**
+ * 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 declare function createExtractor(context: DocgenExtractorContext): Promise<DocgenExtractor>;

package/dist/docgen/extractor.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'pathe';
+import { toComponentDoc } from './meta.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) {
+    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) {
+    const { createChecker, createCheckerByJson } = await import('vue-component-meta');
+    const options = (context.options ?? {});
+    const checkerOptions = { forceUseTs: true, printer: { newLine: 1 } };
+    const tsconfig = findTsconfig(context.root);
+    const checker = tsconfig
+        ? createChecker(tsconfig, checkerOptions)
+        : createCheckerByJson(context.root, { include: ['**/*'], exclude: ['node_modules'] }, checkerOptions);
+    return {
+        extract: file => toComponentDoc(checker.getComponentMeta(file), options),
+        update(file) {
+            if (!SOURCE.test(file)) {
+                return;
+            }
+            if (existsSync(file)) {
+                checker.updateFile(file, readFileSync(file, 'utf8'));
+            }
+            else {
+                checker.deleteFile(file);
+            }
+        },
+        sources: () => checker.getProgram()?.getSourceFiles().map(sourceFile => sourceFile.fileName).filter(file => !file.includes('/node_modules/')) ?? [],
+        // The program is released with the checker; this drops what it cached.
+        dispose: () => checker.clearCache(),
+    };
+}

package/dist/docgen/meta.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentDoc } from '@poveste/shared';
+import type { ComponentMeta } from 'vue-component-meta';
+export interface VueDocgenOptions {
+    /** Packages whose props count although they are declared under `node_modules`. */
+    allow?: string[];
+}
+/** A default as written, without the quoting a tag or the printer added. */
+export declare function normalizeDefault(value: string): string;
+export declare function toComponentDoc(meta: ComponentMeta, options?: VueDocgenOptions): ComponentDoc;

package/dist/docgen/meta.js

@@ -0,0 +1,50 @@
+const HIDDEN_TAGS = ['internal', 'private'];
+// Aliases: bits-ui mixes them about 50/50, reka-ui and nuxt/ui write `@defaultValue`.
+const DEFAULT_TAGS = ['default', 'defaultValue'];
+function tagsOf(tags) {
+    return tags.map(({ name, text }) => text === undefined ? { name } : { name, text });
+}
+function isHidden(tags) {
+    return tags.some(tag => HIDDEN_TAGS.includes(tag.name));
+}
+/** Declared only in installed packages none of which is allowed: an inherited attribute. */
+function isInherited(prop, allow) {
+    const files = prop.getDeclarations().map(declaration => declaration.file.replaceAll('\\', '/'));
+    return files.length > 0 && files.every(file => file.includes('/node_modules/') && !allow.some(pkg => file.includes(`/node_modules/${pkg}/`)));
+}
+/** A default as written, without the quoting a tag or the printer added. */
+export function normalizeDefault(value) {
+    return value.trim().replace(/^`(.*)`$/s, '$1').replace(/^'(.*)'$/s, '"$1"');
+}
+function toProp(prop) {
+    const defaultTag = prop.tags.find(tag => DEFAULT_TAGS.includes(tag.name))?.text;
+    return {
+        name: prop.name,
+        ...prop.description ? { description: prop.description } : {},
+        type: prop.type,
+        required: prop.required,
+        ...prop.default !== undefined ? { default: prop.default } : {},
+        ...defaultTag !== undefined ? { defaultTag } : {},
+        // The code's default is what runs, so it is the one shown; the flag is for the reader.
+        ...prop.default !== undefined && defaultTag !== undefined && normalizeDefault(prop.default) !== normalizeDefault(defaultTag)
+            ? { defaultConflict: true }
+            : {},
+        tags: tagsOf(prop.tags),
+    };
+}
+function toMember(member) {
+    return {
+        name: member.name,
+        ...member.description ? { description: member.description } : {},
+        ...member.type ? { type: member.type } : {},
+        tags: tagsOf(member.tags),
+    };
+}
+export function toComponentDoc(meta, options = {}) {
+    const allow = options.allow ?? [];
+    return {
+        props: meta.props.filter(prop => !prop.global && !isHidden(prop.tags) && !isInherited(prop, allow)).map(toProp),
+        slots: meta.slots.filter(slot => !isHidden(slot.tags)).map(toMember),
+        events: meta.events.filter(event => !isHidden(event.tags)).map(toMember),
+    };
+}

package/dist/docgen/typescript.d.ts

@@ -0,0 +1,9 @@
+/** The version of the first `typescript` found in `dirs`, searched in order as Node searches `node_modules`. */
+export declare function typescriptVersionIn(dirs: string[]): string | undefined;
+/** Why auto-docs cannot read a Vue component's types with the TypeScript in `dirs`, or nothing when it can. */
+export declare function typescriptProblemIn(dirs: string[]): string | undefined;
+/**
+ * The same question for the TypeScript `vue-component-meta` will load: it requires
+ * `typescript` from where it is installed, an optional peer that npm does not add.
+ */
+export declare function typescriptProblem(): string | undefined;

package/dist/docgen/typescript.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'pathe';
+// `vue-component-meta` 3.3 calls `ts.readJsonConfigFile`, which TypeScript 7 no
+// longer has, and no release of it reads TypeScript 7 yet (#1382).
+const NEWEST_MAJOR = 6;
+const FIX = 'Install `typescript@6` in the book to turn it on, or set `autoDocs: false` to turn it off without this message.';
+/** The version of the first `typescript` found in `dirs`, searched in order as Node searches `node_modules`. */
+export function typescriptVersionIn(dirs) {
+    for (const dir of dirs) {
+        const manifest = join(dir, 'typescript', 'package.json');
+        if (existsSync(manifest)) {
+            return JSON.parse(readFileSync(manifest, 'utf8')).version;
+        }
+    }
+    return undefined;
+}
+/** Why auto-docs cannot read a Vue component's types with the TypeScript in `dirs`, or nothing when it can. */
+export function typescriptProblemIn(dirs) {
+    const version = typescriptVersionIn(dirs);
+    if (!version) {
+        return `Auto-docs is off: it reads component types with TypeScript, which this book does not have. ${FIX}`;
+    }
+    if (Number.parseInt(version, 10) > NEWEST_MAJOR) {
+        return `Auto-docs is off: it reads component types with TypeScript ${NEWEST_MAJOR} or earlier, and this book has TypeScript ${version}. ${FIX}`;
+    }
+    return undefined;
+}
+/**
+ * The same question for the TypeScript `vue-component-meta` will load: it requires
+ * `typescript` from where it is installed, an optional peer that npm does not add.
+ */
+export function typescriptProblem() {
+    const meta = createRequire(import.meta.url).resolve('vue-component-meta');
+    return typescriptProblemIn(createRequire(meta).resolve.paths('typescript') ?? []);
+}

package/dist/index.node.js

@@ -1,10 +1,13 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import generateStoryCommand from './commands/generate-story.server.js';
+import { typescriptProblem } from './docgen/typescript.js';
 import { VUE_SETUP_HOOK_NAMES } from './setup-hooks.js';
 import { listComponentFiles } from './util/list-components.js';
 import { VAPOR_INTEROP_ID, vaporInteropModule, withoutVaporPlugin } from './util/vapor.js';
+import { requireVuePlugin } from './util/vue-plugin.js';
 export function HstVue() {
     return {
         name: '@poveste/plugin-vue',
@@ -23,6 +26,7 @@ export function HstVue() {
             return {
                 vite: {
                     plugins: [
+                        requireVuePlugin(),
                         withoutVaporPlugin(),
                         (() => {
                             let root = process.cwd();
@@ -52,6 +56,12 @@ export function HstVue() {
                 },
             };
         },
+        // A story file documents nothing: it names the components that do.
+        docgen: {
+            match: file => file.endsWith('.vue') && !file.endsWith('.story.vue'),
+            module: fileURLToPath(new URL('./docgen/extractor.js', import.meta.url)),
+            unavailable: () => typescriptProblem(),
+        },
         supportPlugin: {
             id: 'vue3',
             moduleName: '@poveste/plugin-vue',

package/dist/util/vue-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin as VitePlugin } from 'vite';
+/**
+ * What to say when a book's Vite config has no Vue plugin. Without one, Vite
+ * answers the first `.vue` file with "Install @vitejs/plugin-vue", which sends a
+ * Quasar reader to install a package their project does not need: Quasar brings
+ * its own Vue plugin, and `HstQuasar()` is what hands it to Poveste (#1337).
+ */
+export declare function noVuePluginMessage(root: string, exists?: (path: string) => boolean): string;
+/** Reports, once per process, a resolved Vite config with no Vue plugin in it. */
+export declare function requireVuePlugin(): VitePlugin;

package/dist/util/vue-plugin.js

@@ -0,0 +1,28 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const QUASAR_CONFIGS = ['quasar.config.js', 'quasar.config.mjs', 'quasar.config.cjs', 'quasar.config.ts'];
+/**
+ * What to say when a book's Vite config has no Vue plugin. Without one, Vite
+ * answers the first `.vue` file with "Install @vitejs/plugin-vue", which sends a
+ * Quasar reader to install a package their project does not need: Quasar brings
+ * its own Vue plugin, and `HstQuasar()` is what hands it to Poveste (#1337).
+ */
+export function noVuePluginMessage(root, exists = existsSync) {
+    const fix = QUASAR_CONFIGS.some(name => exists(join(root, name)))
+        ? 'This is a Quasar project: add `HstQuasar()` from `@poveste/plugin-quasar` to the config\'s `plugins`, which brings Quasar\'s own Vue plugin.'
+        : 'Add `@vitejs/plugin-vue` to `vite.config`, or in a Nuxt project `HstNuxt()` from `@poveste/plugin-nuxt` to the config\'s `plugins`.';
+    return `[poveste] The Vite config has no Vue plugin, so no \`.vue\` story can be compiled. ${fix}`;
+}
+/** Reports, once per process, a resolved Vite config with no Vue plugin in it. */
+export function requireVuePlugin() {
+    let reported = false;
+    return {
+        name: 'poveste-plugin-vue:require-vue-plugin',
+        configResolved(config) {
+            if (!reported && !config.plugins.some(plugin => plugin.name === 'vite:vue')) {
+                reported = true;
+                console.error(noVuePluginMessage(config.root));
+            }
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/plugin-vue",
   "type": "module",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Poveste plugin for Vue.js support",
   "author": {
     "name": "Sorin Gitlan",
@@ -72,27 +72,28 @@
     "node": ">=22.22.2"
   },
   "peerDependencies": {
-    "poveste": "^0.19.1",
+    "poveste": "^0.20.0",
     "vue": "^3.5.43"
   },
   "dependencies": {
-    "@poveste/controls": "^0.19.1",
-    "@poveste/shared": "^0.19.1",
-    "@poveste/vendors": "^0.19.1",
+    "@poveste/controls": "^0.20.0",
+    "@poveste/shared": "^0.20.0",
+    "@poveste/vendors": "^0.20.0",
     "change-case": "^5.4.4",
     "ignore": "^7.0.10",
-    "launch-editor": "^2.9.1",
+    "launch-editor": "^2.14.2",
     "pathe": "^2.0.3",
-    "tinyglobby": "^0.2.17"
+    "tinyglobby": "^0.2.17",
+    "vue-component-meta": "^3.3.13"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
-    "concurrently": "^10.0.5",
-    "poveste": "0.19.1",
+    "@types/node": "^26.6.5",
+    "concurrently": "^10.0.6",
+    "poveste": "0.20.0",
     "typescript": "6.0.3",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2",
-    "vue": "^3.5.43",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4",
+    "vue": "^3.5.44",
     "vue-vapor-rc": "npm:vue@3.6.0-rc.10"
   },
   "scripts": {

package/src/client/app/MountStory.ts

@@ -12,6 +12,7 @@ import {
 } from '@poveste/vendors/vue'
 import { reactive } from 'vue'
 import { createPreviewHost } from './host.js'
+import { warnIfForeignVue } from './util.js'
 
 export default _defineComponent({
   name: 'MountStory',
@@ -34,6 +35,7 @@ export default _defineComponent({
   },
 
   setup(props) {
+    warnIfForeignVue('MountStory')
     const el = _ref<HTMLDivElement>()
     const renderContext = reactive({
       mode: 'mount' as const,

package/src/client/app/RenderStory.ts

@@ -12,7 +12,7 @@ import {
 } from '@poveste/vendors/vue'
 import { reactive } from 'vue'
 import { createPreviewHost } from './host.js'
-import { syncStateBundledAndExternal } from './util.js'
+import { syncStateBundledAndExternal, warnIfForeignVue } from './util.js'
 
 export default _defineComponent({
   name: 'RenderStory',
@@ -39,6 +39,7 @@ export default _defineComponent({
   },
 
   setup(props, { emit }) {
+    warnIfForeignVue('RenderStory')
     const sandbox = _ref<HTMLDivElement>()
     let host: ReturnType<typeof createPreviewHost> | null = null
     let mounting = false

package/src/client/app/util.ts

@@ -1,6 +1,7 @@
 import type { ComponentInternalInstance } from 'vue'
 import { applyState, createStateBaseline, isMarkedRaw, isPlainObject } from '@poveste/shared'
 import {
+  getCurrentInstance as _getCurrentInstance,
   isRef as _isRef,
   unref as _unref,
   watch as _watch,
@@ -241,3 +242,27 @@ export function useInstance(name: string): ComponentInternalInstance {
   }
   return vm
 }
+
+let warnedForeignVue = false
+
+/**
+ * Warns, once, when a component built against `@poveste/vendors/vue` is
+ * rendered by another copy of Vue.
+ *
+ * The other copy runs the component's `setup`, so the vendored one has no
+ * current instance and drops every hook: the story renders nothing, and no build
+ * of Vue says why. A test mounting `MountStory` with `createApp` from `vue` read
+ * it as a story with no variants (#940).
+ */
+export function warnIfForeignVue(component: string) {
+  if (warnedForeignVue || _getCurrentInstance()) {
+    return
+  }
+  warnedForeignVue = true
+  console.warn(`[poveste] ${component} was rendered by a copy of Vue other than \`@poveste/vendors/vue\`, so it renders nothing. Poveste's client components are built against that copy: create the app with \`createApp\` from \`@poveste/vendors/vue\`, not from \`vue\`.`)
+}
+
+/** For specs: lets the warning be seen again. */
+export function resetForeignVueWarning() {
+  warnedForeignVue = false
+}

package/src/docgen/extractor.ts

@@ -0,0 +1,47 @@
+import type { DocgenExtractor, DocgenExtractorContext } from '@poveste/shared'
+import type { VueDocgenOptions } from './meta.js'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'pathe'
+import { toComponentDoc } from './meta.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 options = (context.options ?? {}) as VueDocgenOptions
+  const checkerOptions = { forceUseTs: true, printer: { newLine: 1 } }
+  const tsconfig = findTsconfig(context.root)
+  const checker = tsconfig
+    ? createChecker(tsconfig, checkerOptions)
+    : createCheckerByJson(context.root, { include: ['**/*'], exclude: ['node_modules'] }, checkerOptions)
+
+  return {
+    extract: file => toComponentDoc(checker.getComponentMeta(file), options),
+    update(file) {
+      if (!SOURCE.test(file)) {
+        return
+      }
+      if (existsSync(file)) {
+        checker.updateFile(file, readFileSync(file, 'utf8'))
+      }
+      else {
+        checker.deleteFile(file)
+      }
+    },
+    sources: () => checker.getProgram()?.getSourceFiles().map(sourceFile => sourceFile.fileName).filter(file => !file.includes('/node_modules/')) ?? [],
+    // The program is released with the checker; this drops what it cached.
+    dispose: () => checker.clearCache(),
+  }
+}

package/src/docgen/meta.ts

@@ -0,0 +1,68 @@
+import type { ComponentDoc, DocEvent, DocProp, DocSlot, DocTag } from '@poveste/shared'
+import type { ComponentMeta, EventMeta, PropertyMeta, SlotMeta } from 'vue-component-meta'
+
+export interface VueDocgenOptions {
+  /** Packages whose props count although they are declared under `node_modules`. */
+  allow?: string[]
+}
+
+type Tags = { name: string, text?: string }[]
+
+const HIDDEN_TAGS = ['internal', 'private']
+// Aliases: bits-ui mixes them about 50/50, reka-ui and nuxt/ui write `@defaultValue`.
+const DEFAULT_TAGS = ['default', 'defaultValue']
+
+function tagsOf(tags: Tags): DocTag[] {
+  return tags.map(({ name, text }) => text === undefined ? { name } : { name, text })
+}
+
+function isHidden(tags: Tags) {
+  return tags.some(tag => HIDDEN_TAGS.includes(tag.name))
+}
+
+/** Declared only in installed packages none of which is allowed: an inherited attribute. */
+function isInherited(prop: PropertyMeta, allow: string[]) {
+  const files = prop.getDeclarations().map(declaration => declaration.file.replaceAll('\\', '/'))
+  return files.length > 0 && files.every(file =>
+    file.includes('/node_modules/') && !allow.some(pkg => file.includes(`/node_modules/${pkg}/`)))
+}
+
+/** A default as written, without the quoting a tag or the printer added. */
+export function normalizeDefault(value: string) {
+  return value.trim().replace(/^`(.*)`$/s, '$1').replace(/^'(.*)'$/s, '"$1"')
+}
+
+function toProp(prop: PropertyMeta): DocProp {
+  const defaultTag = prop.tags.find(tag => DEFAULT_TAGS.includes(tag.name))?.text
+  return {
+    name: prop.name,
+    ...prop.description ? { description: prop.description } : {},
+    type: prop.type,
+    required: prop.required,
+    ...prop.default !== undefined ? { default: prop.default } : {},
+    ...defaultTag !== undefined ? { defaultTag } : {},
+    // The code's default is what runs, so it is the one shown; the flag is for the reader.
+    ...prop.default !== undefined && defaultTag !== undefined && normalizeDefault(prop.default) !== normalizeDefault(defaultTag)
+      ? { defaultConflict: true }
+      : {},
+    tags: tagsOf(prop.tags),
+  }
+}
+
+function toMember(member: SlotMeta | EventMeta): DocSlot & DocEvent {
+  return {
+    name: member.name,
+    ...member.description ? { description: member.description } : {},
+    ...member.type ? { type: member.type } : {},
+    tags: tagsOf(member.tags),
+  }
+}
+
+export function toComponentDoc(meta: ComponentMeta, options: VueDocgenOptions = {}): ComponentDoc {
+  const allow = options.allow ?? []
+  return {
+    props: meta.props.filter(prop => !prop.global && !isHidden(prop.tags) && !isInherited(prop, allow)).map(toProp),
+    slots: meta.slots.filter(slot => !isHidden(slot.tags)).map(toMember),
+    events: meta.events.filter(event => !isHidden(event.tags)).map(toMember),
+  }
+}

package/src/docgen/typescript.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'pathe'
+
+// `vue-component-meta` 3.3 calls `ts.readJsonConfigFile`, which TypeScript 7 no
+// longer has, and no release of it reads TypeScript 7 yet (#1382).
+const NEWEST_MAJOR = 6
+
+const FIX = 'Install `typescript@6` in the book to turn it on, or set `autoDocs: false` to turn it off without this message.'
+
+/** The version of the first `typescript` found in `dirs`, searched in order as Node searches `node_modules`. */
+export function typescriptVersionIn(dirs: string[]): string | undefined {
+  for (const dir of dirs) {
+    const manifest = join(dir, 'typescript', 'package.json')
+    if (existsSync(manifest)) {
+      return JSON.parse(readFileSync(manifest, 'utf8')).version
+    }
+  }
+  return undefined
+}
+
+/** Why auto-docs cannot read a Vue component's types with the TypeScript in `dirs`, or nothing when it can. */
+export function typescriptProblemIn(dirs: string[]): string | undefined {
+  const version = typescriptVersionIn(dirs)
+  if (!version) {
+    return `Auto-docs is off: it reads component types with TypeScript, which this book does not have. ${FIX}`
+  }
+  if (Number.parseInt(version, 10) > NEWEST_MAJOR) {
+    return `Auto-docs is off: it reads component types with TypeScript ${NEWEST_MAJOR} or earlier, and this book has TypeScript ${version}. ${FIX}`
+  }
+  return undefined
+}
+
+/**
+ * The same question for the TypeScript `vue-component-meta` will load: it requires
+ * `typescript` from where it is installed, an optional peer that npm does not add.
+ */
+export function typescriptProblem(): string | undefined {
+  const meta = createRequire(import.meta.url).resolve('vue-component-meta')
+  return typescriptProblemIn(createRequire(meta).resolve.paths('typescript') ?? [])
+}

package/src/index.node.ts

@@ -3,11 +3,14 @@ import type { Plugin } from 'poveste'
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 import generateStoryCommand from './commands/generate-story.server.js'
+import { typescriptProblem } from './docgen/typescript.js'
 import { VUE_SETUP_HOOK_NAMES } from './setup-hooks.js'
 import { listComponentFiles } from './util/list-components.js'
 import { VAPOR_INTEROP_ID, vaporInteropModule, withoutVaporPlugin } from './util/vapor.js'
+import { requireVuePlugin } from './util/vue-plugin.js'
 
 export function HstVue(): Plugin {
   return {
@@ -29,6 +32,7 @@ export function HstVue(): Plugin {
       return {
         vite: {
           plugins: [
+            requireVuePlugin(),
             withoutVaporPlugin(),
             (() => {
               let root = process.cwd()
@@ -59,6 +63,13 @@ export function HstVue(): Plugin {
       }
     },
 
+    // A story file documents nothing: it names the components that do.
+    docgen: {
+      match: file => file.endsWith('.vue') && !file.endsWith('.story.vue'),
+      module: fileURLToPath(new URL('./docgen/extractor.js', import.meta.url)),
+      unavailable: () => typescriptProblem(),
+    },
+
     supportPlugin: {
       id: 'vue3',
       moduleName: '@poveste/plugin-vue',

package/src/util/vue-plugin.ts

@@ -0,0 +1,32 @@
+import type { Plugin as VitePlugin } from 'vite'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const QUASAR_CONFIGS = ['quasar.config.js', 'quasar.config.mjs', 'quasar.config.cjs', 'quasar.config.ts']
+
+/**
+ * What to say when a book's Vite config has no Vue plugin. Without one, Vite
+ * answers the first `.vue` file with "Install @vitejs/plugin-vue", which sends a
+ * Quasar reader to install a package their project does not need: Quasar brings
+ * its own Vue plugin, and `HstQuasar()` is what hands it to Poveste (#1337).
+ */
+export function noVuePluginMessage(root: string, exists: (path: string) => boolean = existsSync): string {
+  const fix = QUASAR_CONFIGS.some(name => exists(join(root, name)))
+    ? 'This is a Quasar project: add `HstQuasar()` from `@poveste/plugin-quasar` to the config\'s `plugins`, which brings Quasar\'s own Vue plugin.'
+    : 'Add `@vitejs/plugin-vue` to `vite.config`, or in a Nuxt project `HstNuxt()` from `@poveste/plugin-nuxt` to the config\'s `plugins`.'
+  return `[poveste] The Vite config has no Vue plugin, so no \`.vue\` story can be compiled. ${fix}`
+}
+
+/** Reports, once per process, a resolved Vite config with no Vue plugin in it. */
+export function requireVuePlugin(): VitePlugin {
+  let reported = false
+  return {
+    name: 'poveste-plugin-vue:require-vue-plugin',
+    configResolved(config) {
+      if (!reported && !config.plugins.some(plugin => plugin.name === 'vite:vue')) {
+        reported = true
+        console.error(noVuePluginMessage(config.root))
+      }
+    },
+  }
+}