@do11y/docs 0.0.16 → 0.1.0

package/README.md

@@ -4,7 +4,8 @@ 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`.
+- Sandbox components - e.g. `Button.sandbox.vue` will be available on the url `/sandbox?id=button`.
+- Import components isolated inside an iframe - e.g. `import 'Button.sandbox.vue?iframe'` or `import 'Button.vue?iframe'`.
 - Easily document components with [vue-component-meta](https://www.npmjs.com/package/vue-component-meta) using meta imports - e.g. `Button.vue?meta`.
 
 ## Setup
@@ -59,42 +60,35 @@ npm docs:dev
 
 ### `site/index.ts`
 
-This file will be used to configure the site.
+This file is used for configuration.
 
 > [!WARNING]
 > 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';
+import type { Options } from '@do11y/docs';
 
 export default {
-  // The main component for the site.
   Site: () => import('./Site.vue'),
 
+  Sandbox: () => import('./Sandbox.vue'),
+
+  SandboxIframe: () => import('./SandboxIframe.vue'),
+
   async setup(app, router) {
-    // Additional setup for the app.
+    /** Setup app */
   },
 
   async setupSandbox(app) {
-    // Additional setup for the sandbox app.
+    /** Setup sandbox app */
   },
-} satisfies Site;
-```
-
-### `site/plugins.ts`
 
-This file will be used to configure the different plugins available.
-
-```ts
-import type { PluginOptions } from '@do11y/docs';
-
-export default {
-  setup(md) {
+  markdownSetup(md) {
     // Additional markdown-it setup.
   }
 
-  highlight(md, code, lang, attrs) {
+  markdownHighlight(md, code, lang, attrs) {
     // The highlight option for `markdown-it`.
   }
-} satisfies PluginOptions;
+} satisfies Options;
 ```

package/dist/files.d.ts

@@ -1,4 +1,4 @@
 export declare const ui: string;
 export declare const root: string;
 export declare const docs: string;
-export declare const plugins: string;
+export declare const site: string;

package/dist/files.js

@@ -2,8 +2,8 @@ import { join, dirname } from 'node:path';
 import { createRequire } from 'node:module';
 import { searchForWorkspaceRoot } from 'vite';
 const require = createRequire(import.meta.url);
-export const ui = join(dirname(require.resolve('@do11y/ui/package.json')));
+export const ui = dirname(require.resolve('@do11y/ui/package.json'));
 export const root = searchForWorkspaceRoot(process.cwd());
 // export const root = join(searchForWorkspaceRoot(process.cwd()), 'example');
 export const docs = join(root, 'docs');
-export const plugins = join(docs, 'site', 'plugins.ts');
+export const site = join(docs, 'site', 'index.ts');

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/options.d.ts

@@ -0,0 +1,5 @@
+import type { Options } from './plugins/options/options.js';
+/**
+ * Access plugin options (`docs/site/index.ts`).
+ */
+export declare const options: Options;

package/dist/options.js

@@ -0,0 +1,5 @@
+import { site } from './files.js';
+/**
+ * Access plugin options (`docs/site/index.ts`).
+ */
+export const options = (await import(site)).default;

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

@@ -6,11 +6,11 @@ export interface MarkdownPluginOptions {
     /**
      * Additional markdown-it setup.
      */
-    setup?: PluginSimple;
+    markdownSetup?: PluginSimple;
     /**
      * The highlight option for `markdown-it`.
      */
-    highlight?: (md: MarkdownIt, code: string, lang: string, attrs: string) => string;
+    markdownHighlight?: (md: MarkdownIt, code: string, lang: string, attrs: string) => string;
 }
 export interface MarkdownItEnv {
     /**

package/dist/plugins/markdown/markdown.js

@@ -12,15 +12,15 @@ export default (options) => {
     const md = markdown({
         html: true,
         highlight(code, lang, attrs) {
-            return options?.highlight?.(md, code, lang, attrs) ?? '';
+            return options?.markdownHighlight?.(md, code, lang, attrs) ?? '';
         },
     });
     md.use(frontmatterPlugin);
     md.use(sfcPlugin);
     md.use(componentPlugin);
     md.use(attrsPlugin);
-    if (options?.setup) {
-        md.use(options.setup);
+    if (options?.markdownSetup) {
+        md.use(options.markdownSetup);
     }
     return {
         name: 'do11y:markdown',

package/dist/plugins/meta/meta.js

@@ -26,7 +26,6 @@ export default () => {
                 const code = `export default ${JSON.stringify(mapMeta(meta, (content) => md.render(content)))}`;
                 return {
                     code,
-                    map: { mappings: '' },
                     moduleType: 'js',
                 };
             }

package/dist/plugins/{site/site.d.ts → options/options.d.ts}

@@ -1,7 +1,8 @@
 import type { Plugin } from 'vite';
 import type { App, Component } from 'vue';
 import type { Router } from 'vue-router';
-export interface Site {
+import type { MarkdownPluginOptions } from '../markdown/markdown.js';
+export interface Options extends MarkdownPluginOptions {
     /**
      * The wrapper component for the site.
      */
@@ -18,10 +19,14 @@ export interface Site {
      * Additional setup for the sandbox app.
      */
     setupSandbox?(app: App): void | Promise<void>;
+    /**
+     * Custom wrapper component for `?iframe` imports.
+     */
+    SandboxIframe?: () => Promise<Component>;
 }
 /**
- * Add ability to access the site options (`docs/site/index.ts`)
- * through `do11y:site`.
+ * Add ability to access options (`docs/site/index.ts`)
+ * through `do11y:options`.
  */
 declare const _default: () => Plugin;
 export default _default;

package/dist/plugins/{site/site.js → options/options.js}

@@ -1,13 +1,13 @@
 import { join } from 'node:path';
 import { docs } from '../../files.js';
 /**
- * Add ability to access the site options (`docs/site/index.ts`)
- * through `do11y:site`.
+ * Add ability to access options (`docs/site/index.ts`)
+ * through `do11y:options`.
  */
 export default () => ({
-    name: 'do11y:site',
+    name: 'do11y:options',
     async resolveId(id, importer) {
-        if (id === 'do11y:site') {
+        if (id === 'do11y:options') {
             return this.resolve(join(docs, 'site', 'index.js'), importer);
         }
     },

package/dist/plugins/plugins.js

@@ -1,17 +1,17 @@
 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 optionsPlugin from './options/options.js';
 import routesPlugin from './routes/routes.js';
 import uiPlugin from './ui/ui.js';
 import sandboxPlugin from './sandbox/sandbox.js';
-import { pluginOptions } from '../plugin-options.js';
+import { options } from '../options.js';
 export const plugins = () => [
     uiPlugin(),
     sandboxPlugin(),
     metaPlugin(),
-    markdownPlugin(pluginOptions),
+    markdownPlugin(options),
     customBlockPlugin('docs'),
-    sitePlugin(),
+    optionsPlugin(),
     routesPlugin(),
 ];

package/dist/plugins/sandbox/ok.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineSetupFnComponent<Record<string, any>, {}, {}, Record<string, any> & {}, import("vue").PublicProps>;
+export default _default;

package/dist/plugins/sandbox/ok.js

@@ -0,0 +1,5 @@
+import { defineComponent, h, useAttrs } from 'vue';
+export default defineComponent(() => {
+    const attrs = useAttrs();
+    return () => h('div', undefined, () => h('div', attrs));
+}, { inheritAttrs: false });

package/dist/plugins/sandbox/sandbox.js

@@ -1,8 +1,9 @@
 import { kebabCase } from 'change-case';
-import { parse } from 'node:path';
+import { join, parse } from 'node:path';
 import fg from 'fast-glob';
 import { root, ui } from '../../files.js';
 import { html } from '../../html/html.js';
+const toParamId = (path) => kebabCase(parse(path).name.replace('.sandbox', ''));
 /**
  * Creates a seprate sandbox app, and
  * adds the ability to declare sandbox components
@@ -27,12 +28,63 @@ export default () => {
             if (id === resolvedModuleId) {
                 const stringifiedStories = sandboxFiles.map((path) => {
                     return `{
-            url: "${kebabCase(parse(path).name.replace('.sandbox', ''))}",
+            url: "${toParamId(path)}",
             component: async () => (await import("${path}")).default
           }`;
                 });
                 return `export default [${stringifiedStories.map((sandbox) => sandbox.trim()).join(',\n')}]`;
             }
         },
+        transform: {
+            handler(source, id) {
+                if (!id.endsWith('.vue?iframe')) {
+                    return;
+                }
+                const file = id.replace('?iframe', '');
+                const components = join(ui, 'dist', 'bundled', 'components.js');
+                const sandboxId = toParamId(file);
+                if (id.endsWith('.sandbox.vue?iframe')) {
+                    const customCode = `
+            import { defineComponent, h } from 'vue';
+            
+            import { Do11ySandboxIframe } from '${components}';
+
+            import options from 'do11y:options';
+
+            const customIframe = options.SandboxIframe ? (await options.SandboxIframe()).default : undefined;
+
+            export default defineComponent((props) => {
+              return () => h(Do11ySandboxIframe, {
+                id: '${sandboxId}',
+                source: ${JSON.stringify(source)},
+                customIframe,
+                customIframeProps: props,
+              });
+            });
+          `;
+                    return {
+                        code: customCode,
+                        moduleType: 'js',
+                    };
+                }
+                const customCode = `
+          import { defineComponent, h, useAttrs } from 'vue';
+
+          import Component from '${file}';
+
+          import { Do11yIframe } from '${components}';
+
+          export default defineComponent(() => {
+            const attrs = useAttrs();
+
+            return () => h(Do11yIframe, undefined, () => h(Component, attrs));
+          });
+        `;
+                return {
+                    code: customCode,
+                    moduleType: 'js',
+                };
+            },
+        },
     };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@do11y/docs",
   "description": "A very bare-bones tool to help document Vue components.",
-  "version": "0.0.16",
+  "version": "0.1.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "markdown-it-attrs": "^4.3.1",
     "v-custom-block": "^1.0.67",
     "vue-component-meta": "^3.1.8",
-    "@do11y/ui": "0.0.9"
+    "@do11y/ui": "0.1.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/template/site/SandboxIframe.vue

@@ -1,27 +1,44 @@
 <template>
-  <iframe ref="iframe" :title="`Sandbox for ${title}`" :src="url" />
+  <iframe ref="iframe" :title="`Sandbox for ${title || id}`" :src="url" />
+
   <a :href="url" target="_blank" rel="noopener noreferrer">Open in a new tab</a>
+
+  <pre><code>{{ source }}</code></pre>
 </template>
 
 <script lang="ts" setup>
-  import { computed, ref } from 'vue';
+  import { ref } from 'vue';
 
-  const props = defineProps<{
+  defineProps<{
     /**
-     * The iframe title.
+     * The title of the iframe.
      */
-    title: string;
+    title?: string;
 
     /**
      * The `id` of the sandbox - which is the filename
      * without the extension `.sandbox.vue`.
+     *
+     * @do11y Automatically passed.
      */
     id: string;
+
+    /**
+     * The sandbox url.
+     *
+     *  @do11y Automatically passed.
+     */
+    url: string;
+
+    /**
+     * The source code.
+     *
+     *  @do11y Automatically passed.
+     */
+    source?: string;
   }>();
 
   const iframe = ref<HTMLIFrameElement>();
-
-  const url = computed(() => `${window.location.origin}/sandbox?id=${props.id}`);
 </script>
 
 <style scoped>
@@ -32,5 +49,6 @@
 
   a {
     float: right;
+    clear: both;
   }
 </style>

package/template/site/index.ts

@@ -1,15 +1,14 @@
-import type { Site } from '@do11y/docs';
+import type { Options } from '@do11y/docs';
 
 export default {
   Site: () => import('./Site.vue'),
+
   Sandbox: () => import('./Sandbox.vue'),
 
+  SandboxIframe: () => import('./SandboxIframe.vue'),
+
   async setup(app, router) {
     const SandboxIframe = (await import('./SandboxIframe.vue')).default;
     app.component('SandboxIframe', SandboxIframe);
   },
-
-  async setupSandbox(app) {
-    /** Setup sandbox app */
-  },
-} satisfies Site;
+} satisfies Options;

package/dist/plugin-options.d.ts

@@ -1,6 +0,0 @@
-import type { MarkdownPluginOptions } from './plugins/markdown/markdown.js';
-export type PluginOptions = MarkdownPluginOptions;
-/**
- * Access plugin options (`docs/site/plugins.ts`).
- */
-export declare const pluginOptions: PluginOptions | undefined;

package/dist/plugin-options.js

@@ -1,8 +0,0 @@
-import { existsSync } from 'node:fs';
-import { plugins } from './files.js';
-/**
- * Access plugin options (`docs/site/plugins.ts`).
- */
-export const pluginOptions = existsSync(plugins)
-    ? (await import(plugins)).default
-    : undefined;

package/dist/scaffold.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/scaffold.js

@@ -1,4 +0,0 @@
-import { cp } from 'node:fs/promises';
-import { join } from 'node:path';
-import { docs } from './files.js';
-await cp(join(import.meta.dirname, '../template'), docs, { recursive: true });