@poveste/plugin-quasar 0.8.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Guillaume Chau (original "histoire" project)
+Copyright (c) 2026 Sorin Gitlan (poveste fork)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @poveste/plugin-quasar
+
+Builds a Poveste book inside a Quasar project.
+
+```ts
+import { HstQuasar } from '@poveste/plugin-quasar'
+import { HstVue } from '@poveste/plugin-vue'
+
+export default defineConfig({
+  plugins: [
+    HstVue(),
+    HstQuasar(),
+  ],
+})
+```
+
+Quasar builds its Vite config asynchronously and exposes it through an
+entrypoint whose own header says it is for tooling. This plugin fetches it and
+makes the two adjustments a book needs — both of which are easy to get wrong and
+fail in ways that do not point back at them.
+
+Quasar's plugins are passed through whole. Nothing needs removing, which is
+unusual: `@poveste/plugin-nuxt` drops six. Removing Quasar's Vue plugin as a
+duplicate is the tempting mistake, and `@quasar/vite-plugin` refuses outright
+because it asserts a Vue plugin is registered before it.
+
+Quasar is also kept transformed rather than externalised during story
+collection. Its plugin writes `__QUASAR_VERSION__` while transforming its own
+source, so a source loaded through Node instead has nothing to read.
+
+## Boot files
+
+Poveste renders your components in its own app, so Quasar's boot files never run
+on their own — and an app extension registers its components through a boot file
+it contributes, so an extension's components are missing too. Both fail quietly:
+the build succeeds and the component is simply absent.
+
+Pass them to `setupQuasar` in your setup file:
+
+```ts
+import { setupQuasar } from '@poveste/plugin-quasar/setup'
+import { defineSetupVue3 } from '@poveste/plugin-vue'
+import greeting from './boot/greeting'
+
+export const setupVue3 = defineSetupVue3(setupQuasar({
+  boot: [greeting],
+}))
+```
+
+Only `app` is passed to a boot file: a story has no router, no store and no SSR
+context, so one that needs those has to be split or guarded.
+
+Needs `@quasar/app-vite@^3.8.0` and `quasar@^2.24.0`. Quasar's SPA config is what
+the entrypoint returns, so that is what a book is built with.
+
+The setup helper imports Quasar's stylesheet, which is Sass, so the project needs
+a Sass compiler for Vite to use — `sass` or `sass-embedded`. Quasar projects have
+one already; a project that reaches Quasar another way may not, and Vite says so
+with `Preprocessor dependency "sass" not found`.
+
+Quasar reports a project it will not build by exiting the process rather than
+raising an error. That is caught while its config is being read, so a missing
+`index.html` or a rejected `quasar.config` fails as a Poveste error naming this
+plugin instead of taking the CLI down with no explanation.
+
+[Configuration](https://poveste.dev/reference/config.html) ·
+[Quasar recipe](https://poveste.dev/guide/config.html)

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import type { Plugin } from '@poveste/shared';
+/**
+ * Quasar builds its Vite config asynchronously and hands it over through one
+ * entrypoint, whose own header says it is "used exclusively by @quasar/testing
+ * AEs". That is the same footing as Tailwind's `__unstable__loadDesignSystem`:
+ * usable, and not something to ask every user to import from their own config.
+ */
+export declare const QUASAR_PROJECT_REQUIRED: string;
+export declare const QUASAR_EXITED: string;
+export declare const QUASAR_APP_VITE_REQUIRED: string;
+/** What `getTestingConfig` hands back — a Vite config, loosely typed at this boundary. */
+export interface QuasarViteConfig {
+    define?: Record<string, unknown>;
+    resolve?: {
+        alias?: unknown;
+        extensions?: unknown;
+        dedupe?: unknown;
+    };
+    plugins?: unknown[];
+}
+export interface HstQuasarOptions {
+    /**
+     * Passed through to `getTestingConfig`. It resolves the SPA config whatever is
+     * asked of it today, so this exists for when that stops being true.
+     */
+    ctx?: Record<string, unknown>;
+}
+type GetTestingConfig = (ctx?: Record<string, unknown>) => Promise<QuasarViteConfig>;
+export declare function isPackageAbsent(error: unknown): boolean;
+export declare function resolveTestingConfig(importTesting?: () => Promise<unknown>): Promise<GetTestingConfig>;
+/** The directory holding the nearest quasar.config, searching upwards from `from`. */
+export declare function findQuasarProject(from: string, exists?: (path: string) => boolean): string | undefined;
+/**
+ * Quasar validates the project while building its config, and reports a failure by
+ * calling its own `fatal()` — which ends in `process.exit(1)`. From inside a plugin
+ * hook that takes the whole CLI down with it: no poveste error, no plugin named,
+ * and `poveste dev` gone with it.
+ *
+ * Nothing here can stop a dependency exiting, so the exit is turned into a throw for
+ * as long as the call lasts. The real `process.exit` goes back either way.
+ */
+export declare function withoutProcessExit<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Quasar's plugins are passed through whole. Nothing needs removing — unusually,
+ * since the Nuxt plugin drops six — and removing its Vue plugin in particular
+ * fails config resolution, because @quasar/vite-plugin asserts one precedes it.
+ *
+ * `ssr.noExternal` is the part users should not have to know: Quasar's plugin
+ * writes `__QUASAR_VERSION__` while transforming its own source, so that source
+ * has to be transformed rather than externalised during story collection.
+ */
+export declare function quasarViteConfig(viteConfig: QuasarViteConfig): {
+    ssr: {
+        noExternal: RegExp[];
+    };
+    define: {
+        [x: string]: unknown;
+    };
+    resolve: {
+        alias: unknown;
+        extensions: unknown;
+        dedupe: unknown;
+    };
+    plugins: unknown[];
+};
+export declare function HstQuasar(options?: HstQuasarOptions): Plugin;
+export {};

package/dist/index.js

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import process from 'node:process';
+import { dirname, join, parse } from 'pathe';
+/**
+ * Quasar builds its Vite config asynchronously and hands it over through one
+ * entrypoint, whose own header says it is "used exclusively by @quasar/testing
+ * AEs". That is the same footing as Tailwind's `__unstable__loadDesignSystem`:
+ * usable, and not something to ask every user to import from their own config.
+ */
+export const QUASAR_PROJECT_REQUIRED = '@poveste/plugin-quasar found no quasar.config file above the current directory. '
+    + 'It reads the Vite config Quasar builds for the project, so it needs a Quasar project to read.';
+export const QUASAR_EXITED = '@poveste/plugin-quasar: Quasar ended the process while resolving its config. Its own output is above; '
+    + 'a missing index.html or a quasar.config it refuses are the usual causes.';
+export const QUASAR_APP_VITE_REQUIRED = '@poveste/plugin-quasar needs @quasar/app-vite: the installed copy does not export '
+    + '`getTestingConfig` from `@quasar/app-vite/testing`. Install @quasar/app-vite@^3.8.0.';
+function hasGetTestingConfig(mod) {
+    return typeof mod?.getTestingConfig === 'function';
+}
+/** Only these mean the package or its entrypoint is absent. Anything else is its own problem. */
+const ABSENT = new Set(['ERR_MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED']);
+export function isPackageAbsent(error) {
+    return ABSENT.has(error?.code ?? '');
+}
+export async function resolveTestingConfig(importTesting = () => import('@quasar/app-vite/testing')) {
+    let mod;
+    try {
+        mod = await importTesting();
+    }
+    catch (error) {
+        // A broken transitive dependency, or a file the installed Node will not parse,
+        // is not a missing package — saying so sends the reader to reinstall something
+        // that was never the problem, and loses the error that was.
+        if (!isPackageAbsent(error)) {
+            throw error;
+        }
+        throw new Error(QUASAR_APP_VITE_REQUIRED, { cause: error });
+    }
+    if (!hasGetTestingConfig(mod)) {
+        throw new Error(QUASAR_APP_VITE_REQUIRED);
+    }
+    return mod.getTestingConfig;
+}
+/** The directory holding the nearest quasar.config, searching upwards from `from`. */
+export function findQuasarProject(from, exists = existsSync) {
+    const names = ['quasar.config.js', 'quasar.config.mjs', 'quasar.config.cjs', 'quasar.config.ts'];
+    let dir = from;
+    let { root } = parse(from);
+    // On Windows this is `C:` and needs the trailing slash to terminate the walk.
+    if (root[1] === ':' && root[2] === undefined) {
+        root += '/';
+    }
+    while (true) {
+        if (names.some(name => exists(join(dir, name)))) {
+            return dir;
+        }
+        if (dir === root) {
+            return undefined;
+        }
+        dir = dirname(dir);
+    }
+}
+/**
+ * Quasar validates the project while building its config, and reports a failure by
+ * calling its own `fatal()` — which ends in `process.exit(1)`. From inside a plugin
+ * hook that takes the whole CLI down with it: no poveste error, no plugin named,
+ * and `poveste dev` gone with it.
+ *
+ * Nothing here can stop a dependency exiting, so the exit is turned into a throw for
+ * as long as the call lasts. The real `process.exit` goes back either way.
+ */
+export async function withoutProcessExit(fn) {
+    const realExit = process.exit;
+    process.exit = ((code) => {
+        throw new Error(`${QUASAR_EXITED} (exit code ${code ?? 0})`);
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        process.exit = realExit;
+    }
+}
+/**
+ * Quasar's plugins are passed through whole. Nothing needs removing — unusually,
+ * since the Nuxt plugin drops six — and removing its Vue plugin in particular
+ * fails config resolution, because @quasar/vite-plugin asserts one precedes it.
+ *
+ * `ssr.noExternal` is the part users should not have to know: Quasar's plugin
+ * writes `__QUASAR_VERSION__` while transforming its own source, so that source
+ * has to be transformed rather than externalised during story collection.
+ */
+export function quasarViteConfig(viteConfig) {
+    return {
+        ssr: { noExternal: [/quasar/] },
+        define: { ...viteConfig.define },
+        resolve: {
+            alias: viteConfig.resolve?.alias,
+            extensions: viteConfig.resolve?.extensions,
+            dedupe: viteConfig.resolve?.dedupe,
+        },
+        plugins: viteConfig.plugins,
+    };
+}
+export function HstQuasar(options = {}) {
+    return {
+        name: '@poveste/plugin-quasar',
+        async defaultConfig() {
+            if (!findQuasarProject(process.cwd())) {
+                throw new Error(QUASAR_PROJECT_REQUIRED);
+            }
+            const getTestingConfig = await resolveTestingConfig();
+            const viteConfig = await withoutProcessExit(() => getTestingConfig(options.ctx ?? {}));
+            return { vite: quasarViteConfig(viteConfig) };
+        },
+    };
+}

package/dist/setup.d.ts

@@ -0,0 +1,24 @@
+import type { App } from 'vue';
+import 'quasar/src/css/index.sass';
+/**
+ * A Quasar boot file. Quasar hands these the router, the store and the SSR
+ * context as well; a story has none of those, so only `app` is passed and a boot
+ * file needing more has to be split or guarded.
+ */
+export type BootFile = (params: {
+    app: App;
+}) => unknown;
+export interface SetupQuasarOptions {
+    /** Passed to `app.use(Quasar, …)` — Quasar's own plugin options. */
+    quasar?: Record<string, unknown>;
+    /**
+     * Boot files to run. Poveste renders stories in its own app, so the ones
+     * `quasar.config.js` lists never run on their own; nor do the ones app
+     * extensions contribute, which is why an extension's components are otherwise
+     * missing with no error. Import them and pass them here.
+     */
+    boot?: BootFile[];
+}
+export declare function setupQuasar(options?: SetupQuasarOptions): ({ app }: {
+    app: App;
+}) => void;

package/dist/setup.js

@@ -0,0 +1,10 @@
+import { Quasar } from 'quasar';
+import 'quasar/src/css/index.sass';
+export function setupQuasar(options = {}) {
+    return ({ app }) => {
+        app.use(Quasar, options.quasar ?? {});
+        for (const boot of options.boot ?? []) {
+            boot({ app });
+        }
+    };
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@poveste/plugin-quasar",
+  "type": "module",
+  "version": "0.8.2",
+  "description": "Poveste plugin that builds a book inside a Quasar project",
+  "author": {
+    "name": "Sorin Gitlan"
+  },
+  "license": "MIT",
+  "homepage": "https://poveste.dev",
+  "repository": {
+    "url": "https://github.com/poveste-dev/poveste.git",
+    "type": "git",
+    "directory": "packages/poveste-plugin-quasar"
+  },
+  "bugs": "https://github.com/poveste-dev/poveste/issues",
+  "keywords": [
+    "poveste",
+    "histoire",
+    "storybook",
+    "component-playground",
+    "component-explorer",
+    "stories",
+    "styleguide",
+    "vite",
+    "vue",
+    "quasar",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./setup": {
+      "types": "./setup.d.ts",
+      "default": "./setup.js"
+    },
+    "./*": "./*"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "setup.d.ts",
+    "setup.js"
+  ],
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+  },
+  "peerDependencies": {
+    "@quasar/app-vite": "^3.8.0",
+    "quasar": "^2.24.0",
+    "vue": "^3.5.26",
+    "poveste": "^0.8.2"
+  },
+  "dependencies": {
+    "pathe": "^1.1.2",
+    "@poveste/shared": "0.8.2"
+  },
+  "devDependencies": {
+    "@quasar/app-vite": "^3.8.1",
+    "@types/node": "^22.10.1",
+    "quasar": "^2.27.0",
+    "typescript": "5.6.3",
+    "vite": "^8.2.0",
+    "vitest": "^4.1.10",
+    "vue": "^3.5.26",
+    "poveste": "0.8.2"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -d",
+    "watch": "tsc -d -w --sourceMap",
+    "test": "vitest run",
+    "test:dev": "vitest"
+  }
+}

package/setup.d.ts

@@ -0,0 +1 @@
+export * from './dist/setup.js'

package/setup.js

@@ -0,0 +1 @@
+export * from './dist/setup.js'