@do11y/docs 0.0.11 → 0.0.13

package/README.md

@@ -5,6 +5,7 @@ A very bare-bones tool to help document Vue components.
 - Write documentation in Markdown files that get treated as Vue components.
 - Import markdown files as routes.
 - Add sandbox components - e.g. `Button.sandbox.vue` will be available on the url `/sandbox?id=button`.
+- Easily document components with [vue-component-meta](https://www.npmjs.com/package/vue-component-meta) using meta imports - e.g. `Button.vue?meta`.
 
 ## Setup
 
@@ -14,18 +15,12 @@ A very bare-bones tool to help document Vue components.
 import { fileURLToPath, URL } from 'node:url';
 
 import { defineConfig } from 'vite';
+import { vueOptions } from '@do11y/docs';
 
 import vue from '@vitejs/plugin-vue';
-import vueDevTools from 'vite-plugin-vue-devtools';
 
 export default defineConfig({
-  plugins: [vue({ include: [/\.vue$/, /\.md$/] }), vueDevTools()],
-
-  resolve: {
-    alias: {
-      '@': fileURLToPath(new URL('./src', import.meta.url)),
-    },
-  },
+  plugins: [vue(vueOptions)],
 });
 ```
 
@@ -64,19 +59,24 @@ npm docs:dev
 
 ### `site/index.ts`
 
-This file will be used to configure the documentation site.
+This file will be used to configure the site.
 
 > [!WARNING]
-> Both the documentation site and the sandbox uses the same `setup` function. This means importing styles or components directly in this file will also import them to the sandbox.
+> Both the documentation site and the sandbox import this file - this is why it is recommended to import necessary files/components _inside_ the functions.
 
 ```ts
 import type { Site } from '@do11y/docs';
 
 export default {
+  // The main component for the site.
   Site: () => import('./Site.vue'),
 
-  setup(app) {
-    // App setup
+  async setup(app, router) {
+    // Additional setup for the app.
+  },
+
+  async setupSandbox(app) {
+    // Additional setup for the sandbox app.
   },
 } satisfies Site;
 ```
@@ -89,11 +89,12 @@ This file will be used to configure the different plugins available.
 import type { PluginOptions } from '@do11y/docs';
 
 export default {
-  metaRenderer(meta, title) {
-    return `
-      <h3>${title}</h3>
-      <pre><code>${JSON.stringify(meta, null, 2)}</code></pre>
-    `;
-  },
+  setup(md) {
+    // Additional markdown-it setup.
+  }
+
+  highlight(md, code, lang, attrs) {
+    // The highlight option for `markdown-it`.
+  }
 } satisfies PluginOptions;
 ```

package/dist/index.d.ts

@@ -1,3 +1,7 @@
 import type { PluginOptions } from './plugin-options.js';
 import type { Site } from './plugins/site/site.js';
 export type { Site, PluginOptions };
+export declare const vueOptions: {
+    include: RegExp[];
+    exclude: RegExp[];
+};

package/dist/index.js

@@ -1 +1,4 @@
-export {};
+export const vueOptions = {
+    include: [/\.vue$/, /\.md$/],
+    exclude: [/\.vue\?meta$/],
+};

package/dist/plugins/markdown/markdown.d.ts

@@ -1,5 +1,4 @@
 import { type MarkdownSfcBlocks } from '@mdit-vue/plugin-sfc';
-import type { PluginOptions, MarkdownItEnv as Env } from 'markdown-it-vue-meta';
 import type { PluginSimple } from 'markdown-it';
 import type { Plugin } from 'vite';
 import type MarkdownIt from 'markdown-it';
@@ -12,12 +11,8 @@ export interface MarkdownPluginOptions {
      * The highlight option for `markdown-it`.
      */
     highlight?: (md: MarkdownIt, code: string, lang: string, attrs: string) => string;
-    /**
-     * The renderer option for `markdown-it-vue-meta`.
-     */
-    metaRenderer?: PluginOptions['renderer'];
 }
-export interface MarkdownItEnv extends Env {
+export interface MarkdownItEnv {
     /**
      * Blocks extracted by `@mdit-vue/plugin-sfc`.
      */

package/dist/plugins/markdown/markdown.js

@@ -1,12 +1,8 @@
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
 import { componentPlugin } from '@mdit-vue/plugin-component';
 import { sfcPlugin } from '@mdit-vue/plugin-sfc';
 import { frontmatterPlugin } from '@mdit-vue/plugin-frontmatter';
 import attrsPlugin from 'markdown-it-attrs';
-import metaPlugin from 'markdown-it-vue-meta';
 import markdown from 'markdown-it';
-import { root } from '../../files.js';
 /**
  * Processes blocks with the lang set to `md` into HTML,
  * and turns `.md` files into single file vue components
@@ -23,16 +19,6 @@ export default (options) => {
     md.use(sfcPlugin);
     md.use(componentPlugin);
     md.use(attrsPlugin);
-    if (options?.metaRenderer) {
-        let tsconfig = join(root, 'tsconfig.app.json');
-        if (!existsSync(tsconfig)) {
-            tsconfig = join(root, 'tsconfig.json');
-        }
-        md.use(metaPlugin, {
-            renderer: options.metaRenderer,
-            tsconfig,
-        });
-    }
     if (options?.setup) {
         md.use(options.setup);
     }
@@ -41,9 +27,7 @@ export default (options) => {
         enforce: 'pre',
         transform(code, id) {
             if (id.endsWith('.md')) {
-                const env = {
-                    path: id.replace(/[?#].*$/, ''),
-                };
+                const env = {};
                 const html = md.render(code, env);
                 /**
                  * If it's a markdown block, return the

package/dist/plugins/meta/meta-mapper.d.ts

@@ -0,0 +1,42 @@
+import type { ComponentMeta } from 'vue-component-meta';
+export declare const mapMeta: (meta: ComponentMeta, render: (input: string) => string) => {
+    modelValues: {
+        default: string | undefined;
+        required: boolean;
+        name: string;
+        type: string;
+        description: string;
+        deprecated: string | boolean;
+        tags: {
+            name: string;
+            text: string | undefined;
+        }[];
+    }[];
+    props: {
+        default: string | undefined;
+        required: boolean;
+        name: string;
+        type: string;
+        description: string;
+        deprecated: string | boolean;
+        tags: {
+            name: string;
+            text: string | undefined;
+        }[];
+    }[];
+    events: {
+        name: string;
+        type: string;
+        description: string;
+        deprecated: string | boolean;
+        tags: {
+            name: string;
+            text: string | undefined;
+        }[];
+    }[];
+    slots: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+};

package/dist/plugins/meta/meta-mapper.js

@@ -0,0 +1,50 @@
+export const mapMeta = (meta, render) => {
+    const nonGlobalProps = meta.props.filter((prop) => !prop.global);
+    const hasAssociatedEvent = (prop) => {
+        return meta.events.some((event) => event.name === `update:${prop.name}`);
+    };
+    const hasAssociatedProp = (event) => {
+        return meta.props.some((prop) => `update:${prop.name}` === event.name);
+    };
+    const getDeprecated = (tags) => {
+        const deprecated = getTag(tags, 'deprecated');
+        return deprecated ? deprecated.text || true : false;
+    };
+    const getFilteredTags = (tags) => {
+        const filteredTags = tags.filter((t) => !['default', 'deprecated'].includes(t.name));
+        return filteredTags.map((tag) => ({
+            name: tag.name,
+            text: tag.text ? render(tag.text) : undefined,
+        }));
+    };
+    const mapPropertyAndEvent = (prop) => ({
+        name: prop.name,
+        type: prop.type,
+        description: render(prop.description),
+        deprecated: getDeprecated(prop.tags),
+        tags: getFilteredTags(prop.tags),
+    });
+    const mapSlotAndExposed = (m) => ({
+        name: m.name,
+        type: m.type,
+        description: render(m.description),
+    });
+    const mapProperty = (prop) => ({
+        ...mapPropertyAndEvent(prop),
+        default: prop.default || getTag(prop.tags, 'default')?.text,
+        required: prop.required,
+    });
+    return {
+        modelValues: nonGlobalProps
+            .filter((prop) => hasAssociatedEvent(prop))
+            .map((modelValue) => mapProperty(modelValue)),
+        props: nonGlobalProps
+            .filter((prop) => !hasAssociatedEvent(prop))
+            .map((prop) => mapProperty(prop)),
+        events: meta.events
+            .filter((event) => !hasAssociatedProp(event))
+            .map((event) => mapPropertyAndEvent(event)),
+        slots: meta.slots.map((slot) => mapSlotAndExposed(slot)),
+    };
+};
+const getTag = (tags, tag) => tags.find(({ name }) => name === tag);

package/dist/plugins/meta/meta.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'vite';
+/**
+ * Adds `.vue?meta` imports which returns the results of
+ * running the component through `vue-component-meta`.
+ */
+declare const _default: () => Plugin;
+export default _default;

package/dist/plugins/meta/meta.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createChecker } from 'vue-component-meta';
+import markdown from 'markdown-it';
+import { root } from '../../files.js';
+import { mapMeta } from './meta-mapper.js';
+/**
+ * Adds `.vue?meta` imports which returns the results of
+ * running the component through `vue-component-meta`.
+ */
+export default () => {
+    let tsconfig = join(root, 'tsconfig.app.json');
+    if (!existsSync(tsconfig)) {
+        tsconfig = join(root, 'tsconfig.json');
+    }
+    const checker = createChecker(tsconfig, {
+        noDeclarations: true,
+    });
+    const md = markdown();
+    return {
+        name: 'do11y:meta',
+        transform(_, id) {
+            if (id.endsWith('.vue?meta')) {
+                const file = id.replace('?meta', '');
+                const meta = checker.getComponentMeta(file);
+                const code = `export default ${JSON.stringify(mapMeta(meta, (content) => md.render(content)))}`;
+                return {
+                    code,
+                    map: { mappings: '' },
+                    moduleType: 'js',
+                };
+            }
+        },
+    };
+};

package/dist/plugins/plugins.js

@@ -1,4 +1,5 @@
 import markdownPlugin from './markdown/markdown.js';
+import metaPlugin from './meta/meta.js';
 import customBlockPlugin from 'v-custom-block';
 import sitePlugin from './site/site.js';
 import routesPlugin from './routes/routes.js';
@@ -8,6 +9,7 @@ import { pluginOptions } from '../plugin-options.js';
 export const plugins = () => [
     uiPlugin(),
     sandboxPlugin(),
+    metaPlugin(),
     markdownPlugin(pluginOptions),
     customBlockPlugin('docs'),
     sitePlugin(),

package/dist/plugins/site/site.d.ts

@@ -10,6 +10,10 @@ export interface Site {
      * Additional setup for the app.
      */
     setup?(app: App, router: Router): void | Promise<void>;
+    /**
+     * Additional setup for the sandbox app.
+     */
+    setupSandbox?(app: App): void | Promise<void>;
 }
 /**
  * Add ability to access the site options (`docs/site/index.ts`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@do11y/docs",
   "description": "A very bare-bones tool to help document Vue components.",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,9 +38,9 @@
     "front-matter": "^4.0.2",
     "markdown-it": "^14.1.0",
     "markdown-it-attrs": "^4.3.1",
-    "markdown-it-vue-meta": "^0.0.2",
     "v-custom-block": "^1.0.67",
-    "@do11y/ui": "0.0.5"
+    "vue-component-meta": "^3.1.8",
+    "@do11y/ui": "0.0.6"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/template/site/{SandboxPlayground.vue → SandboxIframe.vue}

@@ -1,8 +1,5 @@
 <template>
-  <div class="iframe-wrapper">
-    <iframe ref="iframe" :title="`Sandbox for ${title}`" :src="url" />
-  </div>
-
+  <iframe ref="iframe" :title="`Sandbox for ${title}`" :src="url" />
   <a :href="url" target="_blank" rel="noopener noreferrer">Open in a new tab</a>
 </template>
 
@@ -10,7 +7,15 @@
   import { computed, ref } from 'vue';
 
   const props = defineProps<{
+    /**
+     * The iframe title.
+     */
     title: string;
+
+    /**
+     * The `id` of the sandbox - which is the filename
+     * without the extension `.sandbox.vue`.
+     */
     id: string;
   }>();
 
@@ -19,7 +24,7 @@
   const url = computed(() => `${window.location.origin}/sandbox?id=${props.id}`);
 </script>
 
-<style scoped>
+<style>
   iframe {
     border: none;
     width: 100%;

package/template/site/Site.vue

@@ -1,26 +1,20 @@
 <template>
   <nav>
     <ul>
-      <template v-for="route of routes" :key="route.path">
-        <li>
-          <router-link :to="route.path">
-            {{ route.meta.title }}
-          </router-link>
-        </li>
-      </template>
+      <li v-for="route of routes" :key="route.path">
+        <router-link :to="route.path">
+          {{ route.meta.title }}
+        </router-link>
+      </li>
     </ul>
   </nav>
 
-  <RouterView />
+  <main>
+    <RouterView />
+  </main>
 </template>
 
 <script lang="ts" setup>
   import routes from 'do11y:routes';
   import './style.css';
 </script>
-
-<style>
-  button {
-    width: max-content;
-  }
-</style>

package/template/site/index.ts

@@ -4,7 +4,11 @@ export default {
   Site: () => import('./Site.vue'),
 
   async setup(app) {
-    const SandboxPlaygroundComponent = (await import('./SandboxPlayground.vue')).default;
-    app.component('SandboxPlayground', SandboxPlaygroundComponent);
+    const SandboxIframe = (await import('./SandboxIframe.vue')).default;
+    app.component('SandboxIframe', SandboxIframe);
+  },
+
+  async setupSandbox(app) {
+    /** Setup sandbox app */
   },
 } satisfies Site;

package/template/site/plugins.ts

@@ -1,10 +1,3 @@
 import type { PluginOptions } from '@do11y/docs';
 
-export default {
-  metaRenderer(meta, title) {
-    return `
-      <h3>${title}</h3>
-      <pre><code>${JSON.stringify(meta, null, 2)}</code></pre>
-    `;
-  },
-} satisfies PluginOptions;
+export default {} satisfies PluginOptions;

package/template/site/style.css

@@ -15,6 +15,7 @@ html {
   margin: 0;
 }
 
+[id],
 :target {
   scroll-margin-block: 2em;
 }
@@ -24,54 +25,17 @@ button {
   cursor: pointer;
 }
 
-button {
-  color: inherit;
-}
-
 button:disabled,
 button[aria-disabled='true'] {
   cursor: default;
 }
 
-button,
-input,
-textarea,
-select {
-  font: inherit;
-  letter-spacing: inherit;
-  word-spacing: inherit;
-}
-
-textarea {
-  field-sizing: content;
-}
-
-a {
-  text-underline-position: from-font;
-}
-
 pre {
   white-space: pre-wrap;
+  inline-size: 100%;
 }
 
-code {
-  word-break: break-all;
-}
-
-pre,
-table,
-img,
-svg,
-picture,
-video,
-canvas,
-iframe {
-  max-inline-size: 100%;
-  min-inline-size: 0;
-
-  display: block;
-}
-
-[id] {
-  scroll-margin-top: 2rem;
+body {
+  margin-inline: auto;
+  inline-size: min(90dvw, 50rem);
 }