@md-plugins/quasar-app-extension-q-press 0.1.0-beta.0 → 0.1.0-beta.10

package/README.md

@@ -4,7 +4,9 @@ The Ultimate Markdown Solution for the Quasar Framework.
 
 See the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpress/overview) for more information.
 
-> Q-Press currently targets Quasar Vite projects using `@quasar/app-vite` `^3.0.0-beta.12`. TypeScript processing is required.
+> Current beta release: `0.1.0-beta.10`.
+>
+> Q-Press currently targets Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.29`. TypeScript processing is required.
 
 ## Features
 
@@ -24,14 +26,12 @@ See the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpr
 - `quasar ext add @md-plugins/q-press`
 - Here is what gets installed on a **new** install:
   - `src/.q-press`
-  - `src/q-press.globals.d.ts`
   - `src/components`
   - `src/markdown`
   - `src/examples`
   - `src/siteConfig`
 - Here is what gets installed on an **update** install:
   - `src/.q-press`
-  - `src/q-press.globals.d.ts`
 
 2. Install `markdown-it` and `@types/markdown-it` in your project devDependencies
 
@@ -60,8 +60,6 @@ See the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpr
 
 - ```scss
   @import '../.q-press/css/app.scss';
-  @import '../.q-press/css/fonts.scss';
-  @import '../.q-press/css/prism-theme.scss';
   ```
 
 3. Modify your `quasar.config.ts`
@@ -220,7 +218,7 @@ If you don't have a `.prettierignore` file, create one and add the following:
 
 ## Updating
 
-When you update, only the `src/.q-press` folder will be updated as well as the file `src/q-press.globals.d.ts`. If you want to re-install everything, just remove the `src/siteConfig` folder.
+When you update, only the `src/.q-press` folder will be updated. If you want to re-install everything, just remove the `src/siteConfig` folder.
 
 To make it easier to update, you can use the following command:
 

package/dist/index.js

@@ -0,0 +1,97 @@
+/**
+ * Quasar App Extension index/runner script
+ * (runs on each dev/build)
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/index-api
+ */
+import { defineIndexScript } from '@quasar/app-vite';
+import { fileURLToPath } from 'node:url';
+const qPressGlobalsTsConfigPath = fileURLToPath(new URL('./q-press-globals.d.ts', import.meta.url)).replace(/\\/g, '/');
+function normalizeAlias(alias) {
+    if (Array.isArray(alias)) {
+        return [...alias];
+    }
+    return Object.entries(alias ?? {}).map(([find, replacement]) => ({
+        find,
+        replacement,
+    }));
+}
+function addQuasarSourceAlias(viteConf, appDir) {
+    const alias = normalizeAlias(viteConf.resolve?.alias);
+    viteConf.resolve ??= {};
+    viteConf.resolve.alias = [
+        ...alias,
+        {
+            find: /^quasar\/src\/(.*)$/,
+            replacement: `${appDir.replace(/\\/g, '/')}/node_modules/quasar/src/$1`,
+        },
+    ];
+}
+function addQPressGlobalsToTsConfig(tsConfig) {
+    tsConfig.files ??= [];
+    if (!tsConfig.files.includes(qPressGlobalsTsConfigPath)) {
+        tsConfig.files.push(qPressGlobalsTsConfigPath);
+    }
+}
+function extendTypeScriptConfig(typescriptConfig) {
+    const userExtendTsConfig = typescriptConfig.extendTsConfig;
+    typescriptConfig.extendTsConfig = (tsConfig) => {
+        userExtendTsConfig?.(tsConfig);
+        addQPressGlobalsToTsConfig(tsConfig);
+    };
+}
+export default defineIndexScript((api) => {
+    // verify this is a Vite project
+    if (!api.hasVite) {
+        throw new Error('This extension requires Vite');
+    }
+    api.compatibleWith('quasar', '^2.0.0');
+    api.compatibleWith('@quasar/app-vite', '>=3.0.0-beta.29');
+    // here we extend /quasar.config, so we can add some Vite/Vue stuff
+    api.extendQuasarConf(async (config) => {
+        config.build ??= {};
+        config.build.typescript ??= {};
+        config.build.viteVuePluginOptions ??= {};
+        config.framework ??= {};
+        extendTypeScriptConfig(config.build.typescript);
+        // make sure 'vueRouterMode' has 'history' mode
+        if (config.build.vueRouterMode !== 'history') {
+            console.warn('Changing vueRouterMode to "history" - required for hash links to work correctly');
+            config.build.vueRouterMode = 'history';
+        }
+        // let Vite know to transpile md files
+        const include = config.build.viteVuePluginOptions.include;
+        if (Array.isArray(include)) {
+            include.push(/\.(vue|md)$/);
+        }
+        else if (include !== void 0) {
+            config.build.viteVuePluginOptions.include = [include, /\.(vue|md)$/];
+        }
+        else {
+            config.build.viteVuePluginOptions.include = [/\.(vue|md)$/];
+        }
+        // let Vue know to auto import md files
+        const extensions = new Set(config.framework.autoImportVueExtensions || []);
+        extensions.add('md');
+        extensions.add('vue');
+        config.framework.autoImportVueExtensions = Array.from(extensions);
+        // add the appropriate plugins
+        const plugins = new Set(config.framework.plugins || []);
+        plugins.add('Cookies');
+        plugins.add('Dark');
+        plugins.add('Meta');
+        plugins.add('Notify');
+        config.framework.plugins = Array.from(plugins);
+        // const markdownPath = api.resolve.src('markdown')
+        // const path = api.resolve.src('siteConfig')
+        // if (fse.pathExistsSync(path) && fse.pathExistsSync(markdownPath)) {
+        //   const siteConfig = await import(path)
+        //   const { sidebar } = siteConfig.default || siteConfig
+        //   // add vite-md-plugin to quasar.config.js
+        //   config.vite.plugins.push(viteMdPlugin({ path: markdownPath, menu: sidebar }))
+        // }
+    });
+    api.extendViteConf((viteConf, _invoke, aeApi) => {
+        addQuasarSourceAlias(viteConf, aeApi.appDir);
+    });
+});

package/dist/install.js

@@ -0,0 +1,44 @@
+/**
+ * Quasar App Extension install script
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/install-api
+ */
+import { defineInstallScript } from '@quasar/app-vite';
+import { existsSync } from 'node:fs';
+export default defineInstallScript(async (api) => {
+    // verify this is a Vite project
+    if (!api.hasVite) {
+        throw new Error('This extension requires Vite');
+    }
+    api.compatibleWith('quasar', '^2.0.0');
+    api.compatibleWith('@quasar/app-vite', '>=3.0.0-beta.29');
+    // project must have pinia installed
+    if ((await api.getStorePackageName()) !== 'pinia') {
+        console.error('-----------------------------');
+        console.error('This extension requires pinia');
+        console.error('-----------------------------');
+        throw new Error('This extension requires pinia');
+    }
+    // project must be typescript
+    if ((await api.hasTypescript()) !== true) {
+        console.error('----------------------------------');
+        console.error('This extension requires TypeScript');
+        console.error('----------------------------------');
+        throw new Error('This extension requires TypeScript');
+    }
+    const path = api.resolve.src('siteConfig');
+    if (existsSync(path)) {
+        // this is an update scenario
+        console.warn('-------------------------------------');
+        console.warn("Update only for 'src/.q-press' folder");
+        console.warn('-------------------------------------');
+        api.render('./templates/update');
+    }
+    else {
+        // this is a project initial setup
+        console.warn('--------------------------------------------');
+        console.warn('Initial setup. Be sure to read the\ndocumentation on the manual set up required.');
+        console.warn('--------------------------------------------');
+        api.render('./templates/init');
+    }
+});

package/dist/q-press-globals.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="@quasar/app-vite/client" />
+
+declare module '*.md'
+
+declare global {
+  interface ImportMetaHot {
+    accept(callback?: (..._args: unknown[]) => unknown): void
+  }
+
+  interface ImportMeta {
+    readonly env: ImportMetaEnv
+    glob: <T = unknown>(pattern: string) => Record<string, () => Promise<T>>
+    hot?: ImportMetaHot
+  }
+
+  interface TocMenuItem {
+    id: string
+    level: number
+    title: string
+    link?: string
+    deep?: boolean
+    sub?: boolean
+    onClick?: () => void
+    children?: TocMenuItem[]
+  }
+
+  interface MarkdownModule {
+    title?: string
+    headers?: TocMenuItem[]
+    frontmatter?: Record<string, unknown>
+    filename?: string
+    render: (..._args: unknown[]) => unknown
+  }
+
+  interface MenuItem {
+    name: string
+    path?: string
+    icon?: string
+    iconColor?: string
+    rightIcon?: string
+    rightIconColor?: string
+    badge?: string
+    children?: MenuItem[] | undefined
+    external?: boolean
+    expanded?: boolean
+  }
+}
+
+export {}

package/dist/templates/init/src/_q-press/api/components/DarkModeToggle.json

@@ -0,0 +1,37 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/dark-mode-toggle"
+  },
+  "props": {
+    "darkIcon": {
+      "type": "String",
+      "desc": "Icon name for dark mode",
+      "examples": [
+        "mdiMoonWaningCrescent"
+      ],
+      "default": "mdiMoonWaningCrescent",
+      "category": "content"
+    },
+    "lightIcon": {
+      "type": "String",
+      "desc": "Icon name for light mode",
+      "examples": [
+        "mdiWhiteBalanceSunny"
+      ],
+      "default": "mdiWhiteBalanceSunny",
+      "category": "content"
+    }
+  },
+  "events": {
+    "update:mode": {
+      "desc": "Emitted when the mode is toggled",
+      "params": {
+        "mode": {
+          "type": "String",
+          "desc": "The current mode ('dark' or 'light')"
+        }
+      }
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownApi.json

@@ -0,0 +1,67 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-api"
+  },
+  "props": {
+    "nameBanner": {
+      "type": "String",
+      "desc": "Title to display in the banner",
+      "examples": [
+        "'API Documentation'",
+        "'Component API'"
+      ],
+      "category": "content"
+    },
+    "pageLink": {
+      "type": "String",
+      "desc": "URL for the page link",
+      "examples": [
+        "'https://github.com/user/repo/edit/main/docs/page.md'"
+      ],
+      "category": "navigation"
+    }
+  },
+  "events": {
+    "searchFieldClick": {
+      "desc": "Emitted when the search field is clicked",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    },
+    "filterClick": {
+      "desc": "Emitted when the filter button is clicked",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    }
+  },
+  "methods": {
+    "onSearchFieldClick": {
+      "desc": "Handler for the search field click event",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      },
+      "returns": null
+    },
+    "onFilterClick": {
+      "desc": "Handler for the filter button click event",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      },
+      "returns": null
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownApiEntry.json

@@ -0,0 +1,76 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-api-entry"
+  },
+  "functions": {
+    "getProp": {
+      "desc": "Function to get a property node for the API entry.",
+      "params": {
+        "openState": {
+          "type": "Object",
+          "desc": "The state object to manage open/close state of nodes."
+        },
+        "masterKey": {
+          "type": "String",
+          "desc": "The master key for the API entry."
+        },
+        "prop": {
+          "type": "Object",
+          "desc": "The property object to generate the node for."
+        },
+        "paramName": {
+          "type": "String",
+          "desc": "The name of the parameter."
+        },
+        "level": {
+          "type": "Number",
+          "desc": "The level of the property in the hierarchy."
+        }
+      },
+      "returns": {
+        "type": "Array<VNode>",
+        "desc": "An array of VNode elements representing the property."
+      }
+    },
+    "getDiv": {
+      "desc": "Function to create a div element for the API entry.",
+      "params": {
+        "cols": {
+          "type": "Number",
+          "desc": "The number of columns the div should span."
+        },
+        "label": {
+          "type": "String",
+          "desc": "The label for the div."
+        },
+        "key": {
+          "type": "String",
+          "desc": "The key for the div."
+        },
+        "children": {
+          "type": "Array<VNode>",
+          "desc": "The child nodes for the div."
+        }
+      },
+      "returns": {
+        "type": "VNode",
+        "desc": "A VNode element representing the div."
+      }
+    },
+    "getStringType": {
+      "desc": "Function to get the string representation of a type.",
+      "params": {
+        "type": {
+          "type": "Object",
+          "desc": "The type object to get the string representation for."
+        }
+      },
+      "returns": {
+        "type": "String",
+        "desc": "The string representation of the type."
+      }
+    }
+  },
+  "types": {}
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownCardLink.json

@@ -0,0 +1,28 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-card-link"
+  },
+  "props": {
+    "to": {
+      "type": "String",
+      "desc": "The target URL or path for the link",
+      "examples": [
+        "/home",
+        "https://example.com"
+      ],
+      "required": true,
+      "category": "navigation"
+    },
+    "external": {
+      "type": "Boolean",
+      "desc": "Flag to indicate if the link is external",
+      "category": "navigation"
+    }
+  },
+  "slots": {
+    "default": {
+      "desc": "Slot for custom content inside the link"
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownCardTitle.json

@@ -0,0 +1,48 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-card-title"
+  },
+  "props": {
+    "title": {
+      "type": "String",
+      "desc": "The title text to display",
+      "examples": [
+        "'Introduction'",
+        "'Chapter 1'"
+      ],
+      "category": "content"
+    },
+    "prefix": {
+      "type": "String",
+      "desc": "Prefix to add to the slugified title",
+      "examples": [
+        "'section-'"
+      ],
+      "category": "content"
+    }
+  },
+  "events": {
+    "click": {
+      "desc": "Emitted when the title is clicked",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    }
+  },
+  "methods": {
+    "onClick": {
+      "desc": "Handler for the click event on the title",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      },
+      "returns": null
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownCode.json

@@ -0,0 +1,37 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-code"
+  },
+  "props": {
+    "code": {
+      "type": "String",
+      "desc": "The code to display",
+      "examples": [
+        "'const a = 1;'",
+        "'<div>Hello World</div>'"
+      ],
+      "category": "content"
+    },
+    "maxHeight": {
+      "type": "String",
+      "desc": "Maximum height for the code block",
+      "examples": [
+        "'200px'",
+        "'50vh'"
+      ],
+      "category": "style"
+    },
+    "lang": {
+      "type": "String",
+      "desc": "Language of the code for syntax highlighting",
+      "default": "js",
+      "examples": [
+        "'js'",
+        "'html'",
+        "'css'"
+      ],
+      "category": "content"
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownCodePrism.json

@@ -0,0 +1,29 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-code-prism"
+  },
+  "props": {
+    "code": {
+      "type": "String",
+      "desc": "The code to display with syntax highlighting",
+      "examples": [
+        "'const a = 1;'",
+        "'<div>Hello World</div>'"
+      ],
+      "required": true,
+      "category": "content"
+    },
+    "lang": {
+      "type": "String",
+      "desc": "Language of the code for syntax highlighting",
+      "examples": [
+        "'js'",
+        "'html'",
+        "'css'"
+      ],
+      "required": true,
+      "category": "content"
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownCodepen.json

@@ -0,0 +1,18 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-codepen"
+  },
+  "props": {
+    "title": {
+      "type": "String",
+      "desc": "Title used for the generated CodePen",
+      "required": true,
+      "examples": [
+        "'Basic Example'",
+        "'Advanced Playground'"
+      ],
+      "category": "content"
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownCopyButton.json

@@ -0,0 +1,36 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-copy-button"
+  },
+  "props": {
+    "lang": {
+      "type": "String",
+      "desc": "Language of the code block to copy",
+      "examples": [
+        "'js'",
+        "'html'",
+        "'css'"
+      ],
+      "category": "content"
+    }
+  },
+  "events": {
+    "copy": {
+      "desc": "Emitted when the copy button is clicked",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    }
+  },
+  "methods": {
+    "copy": {
+      "desc": "Method to copy the code block to the clipboard",
+      "params": {},
+      "returns": null
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownDrawerSidebar.json

@@ -0,0 +1,17 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-drawer-toc"
+  },
+  "events": {
+    "toggleTocDrawer": {
+      "desc": "Emitted when the close button is clicked to toggle the Table of Contents drawer",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    }
+  }
+}

package/dist/templates/init/src/_q-press/api/components/MarkdownDrawerToc.json

@@ -0,0 +1,17 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-drawer-toc"
+  },
+  "events": {
+    "toggleTocDrawer": {
+      "desc": "Emitted when the close button is clicked to toggle the Table of Contents drawer",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    }
+  }
+}