do11y 0.4.3 → 0.5.1

package/README.md

@@ -9,19 +9,19 @@ A bare-bones tool to document Vue components.
 
 ### Markdown components with [@mdit-vue](https://github.com/mdit-vue/mdit-vue).
 
-Markdown files are treated as single file Vue components with the help of [@mdit-vue](https://github.com/mdit-vue/mdit-vue).
+> Customizable through the options `markdownSetup` and `markdownCodeBlock`.
 
-You can customize the markdown-it instance through the `markdownSetup` option.
+Markdown files are treated as single file Vue components with the help of [@mdit-vue](https://github.com/mdit-vue/mdit-vue).
 
-### Import markdown route files and pages as routes through `do11y:routes`
+### Markdown routes available through `do11y:routes`
 
-To include a markdown file as a route it needs to have a `title` and a `slug` (e.g. `/button`) in it's frontmatter. Or add it inside the `docs/do11y/pages` folder.
+To include a markdown file as a route it needs to have a `title` and a `slug` (e.g. `/button`) in it's frontmatter, or it needs to be placed inside `docs/do11y/pages`.
 
 ### [Shiki](https://shiki.style) code highlighting
 
-Code blocks are automatically highlighted with [Shiki](https://shiki.style).
+> Customizable through the `highlighter` option.
 
-You can customize the Shiki instance through the `highlighter` options.
+Code blocks are automatically highlighted with [Shiki](https://shiki.style).
 
 ### Highlight imports
 
@@ -30,28 +30,50 @@ You can import Vue files as highlighted code blocks through `.vue?highlight`, or
 These imports return HTML strings meaning you have to render the code block using `v-html`.
 
 > [!WARNING]
-> Imports of type `.vue?highlight&lang=css` only work on built sites. During development it will return the same result as `.vue?highlight`.
+> Imports of type `.vue?highlight&lang=css` only work on _built_ sites. During development it will return the same result as `.vue?highlight`.
 
 ### Sandboxes
 
-Create sandbox components - e.g. `Button.sandbox.vue` will be available under the url `/sandbox?id=button`, and if importing the component it will be wrapped inside an iframe component that has access to the components `?highlight` imports.
+> To customize the Sandbox app add a custom `docs/do11y/pages/Sandbox.vue` wrapper component and/or use the `setupSandbox` option.
 
-To customize the sandbox app, use the `Sandbox` option - and to cutomize the iframe component used for import, use the `SandboxIframe` option.
+Turn a component into a sandbox by adding a `.sandbox` prefix to the component name, e.g. `Button.sandbox.vue` will be available under the url `/sandbox?id=button`, and when importing the component it will be wrapped inside an iframe.
 
 > [!NOTE]
-> The id is based on the filename - not the path to the file - this means if you have two sandbox files of the same name in different locations - they won't both work.
+> The id of a sandbox component is based on the filename - not the path - this means every sandbox component must have a unique name.
+
+#### Sandbox Iframe
+
+> To customize the Sandbox app add a custom `docs/do11y/layout/SandboxIframe.vue` wrapper component.
+
+The sandbox iframe component has some props automatically passed to it - you can use the `SandboxIframeProps` type to declare these.
+
+```vue
+<template>
+  <iframe ref="iframe" :title="`Sandbox for ${title || id}`" :src="url" />
+</template>
+
+<script lang="ts" setup>
+import type { SandboxIframeProps } from "do11y";
+
+defineProps<SandboxIframeProps & { title?: string }>();
+</script>
+```
 
 ### Document components with [vue-component-meta](https://www.npmjs.com/package/vue-component-meta)
 
-Document components through meta imports (`Button.vue?meta`) which give a simplified version of a result from [vue-component-meta](https://www.npmjs.com/package/vue-component-meta).
+Document components through meta imports (`Button.vue?meta`) which give a simplified version of the result from [vue-component-meta](https://www.npmjs.com/package/vue-component-meta).
 
 ## Options
 
-Expected as the default export in `docs/do11y/do11y.ts`.
+> Options should be the default export of `docs/do11y/do11y.ts`.
 
-You can specify a layout for each page by adding a `docs/do11y/layout/Page.vue` file with a `<RouterView />` in it.
+You can set the home page by adding a `docs/do11y/pages/Home.vue` file, and you can add a layout for each page in `docs/do11y/layout/Page.vue` using `<RouterView />`.
 
-And you can set the home page by adding `docs/do11y/pages/Home.vue`.
+```ts
+import type { Options } from "do11y";
+
+export default {} satisfies Options;
+```
 
 ```ts
 interface Options {
@@ -60,21 +82,11 @@ interface Options {
    */
   setup?(app: App, router: Router): void | Promise<void>;
 
-  /**
-   * The wrapper component for sandboxes.
-   */
-  Sandbox?: () => Promise<Component>;
-
   /**
    * Additional setup for the sandbox app.
    */
   setupSandbox?(app: App): void | Promise<void>;
 
-  /**
-   * Custom wrapper component for `.vue.sandbox` imports.
-   */
-  SandboxIframe?: () => Promise<Component>;
-
   /**
    * The code highlighter.
    *   - Markdown code blocks

package/dist/docs/plugins/options.d.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from "vite";
-import type { App, Component } from "vue";
+import type { App } from "vue";
 import type { Router } from "vue-router";
 import type { BundledTheme, ShikiTransformer, StringLiteralUnion, ThemeInput } from "shiki";
 import type { MarkdownPluginOptions } from "./markdown.js";
@@ -8,18 +8,10 @@ export interface Options extends MarkdownPluginOptions {
      * Additional setup for the app.
      */
     setup?(app: App, router: Router): void | Promise<void>;
-    /**
-     * The wrapper component for sandboxes.
-     */
-    Sandbox?: () => Promise<Component>;
     /**
      * Additional setup for the sandbox app.
      */
     setupSandbox?(app: App): void | Promise<void>;
-    /**
-     * Custom wrapper component for `.vue.sandbox` imports.
-     */
-    SandboxIframe?: () => Promise<Component>;
     /**
      * The code highlighter.
      *   - Markdown code blocks
@@ -76,9 +68,15 @@ export interface ResolvedOptions extends Omit<Options, "highlighter"> {
     };
 }
 /**
- * Add ability to access options (`docs/do11y/do11y.ts`)
- * through `do11y:options`, the home component through `do11y:home`,
- * and the layout component through `do11y:page-layout`.
+ * Adds the ability to import options and setup files.
+ *
+ * `do11y:options` → `docs/do11y/do11y.ts`
+ *
+ * `do11y:home` → `docs/do11y/pages/Home.vue`
+ * `do11y:page-layout` → `docs/do11y/layout/Page.vue`
+ *
+ * `do11y:sandbox` → `docs/do11y/pages/Sandbox.vue`
+ * `do11y:sandbox-iframe` → `docs/do11y/layout/SandboxIframe.vue`
  */
 declare const _default: () => Plugin;
 export default _default;

package/dist/docs/plugins/options.js

@@ -2,37 +2,41 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { do11y } from "../files.js";
 /**
- * Add ability to access options (`docs/do11y/do11y.ts`)
- * through `do11y:options`, the home component through `do11y:home`,
- * and the layout component through `do11y:page-layout`.
+ * Adds the ability to import options and setup files.
+ *
+ * `do11y:options` → `docs/do11y/do11y.ts`
+ *
+ * `do11y:home` → `docs/do11y/pages/Home.vue`
+ * `do11y:page-layout` → `docs/do11y/layout/Page.vue`
+ *
+ * `do11y:sandbox` → `docs/do11y/pages/Sandbox.vue`
+ * `do11y:sandbox-iframe` → `docs/do11y/layout/SandboxIframe.vue`
  */
-export default () => ({
-    name: "do11y:options",
-    async resolveId(id, importer) {
-        if (id === "do11y:options") {
-            return this.resolve(join(do11y, "do11y.js"), importer);
-        }
-        if (id === "do11y:home") {
-            const homeFile = join(do11y, "pages", "Home.vue");
-            /* prettier-ignore */
-            return existsSync(homeFile)
-                ? this.resolve(homeFile, importer)
-                : `\0do11y:home`;
-        }
-        if (id === "do11y:page-layout") {
-            const pageLayoutFile = join(do11y, "layout", "Page.vue");
-            /* prettier-ignore */
-            return existsSync(pageLayoutFile)
-                ? this.resolve(pageLayoutFile, importer)
-                : `\0do11y:page-layout`;
-        }
-    },
-    async load(id) {
-        if (id === `\0do11y:home` || id === `\0do11y:page-layout`) {
-            return {
-                code: "export default undefined",
-                moduleType: "js",
-            };
-        }
-    },
-});
+export default () => {
+    const setupFiles = {
+        "do11y:options": join(do11y, "do11y.js"),
+        "do11y:home": join(do11y, "pages", "Home.vue"),
+        "do11y:page-layout": join(do11y, "layout", "Page.vue"),
+        "do11y:sandbox": join(do11y, "pages", "Sandbox.vue"),
+        "do11y:sandbox-iframe": join(do11y, "layout", "SandboxIframe.vue"),
+    };
+    return {
+        name: "do11y:options",
+        async resolveId(id, importer) {
+            if (Object.keys(setupFiles).includes(id)) {
+                /* prettier-ignore */
+                return existsSync(setupFiles[id])
+                    ? this.resolve(setupFiles[id], importer)
+                    : `\0${id}`;
+            }
+        },
+        async load(id) {
+            if (id.startsWith("\0") && Object.keys(setupFiles).includes(id.replace("\0", ""))) {
+                return {
+                    code: "export default undefined",
+                    moduleType: "js",
+                };
+            }
+        },
+    };
+};

package/dist/docs/plugins/routes.js

@@ -2,8 +2,8 @@ import { join, parse } from "node:path";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { globSync } from "tinyglobby";
 import { root, do11y } from "../files.js";
-import fm from "front-matter";
 import { toParamId } from "./sandbox.js";
+import fm from "front-matter";
 /**
  * Adds the ability to import routes through `do11y:routes`.
  *
@@ -24,9 +24,10 @@ export default () => {
         .map((path) => ({ path, frontmatter: fm(readFileSync(path, "utf-8")).attributes }))
         .filter((file) => typeof file.frontmatter.title === "string" && typeof file.frontmatter.slug === "string");
     /* prettier-ignore */
-    const pages = existsSync(join(do11y, "pages"))
+    let pages = existsSync(join(do11y, "pages"))
         ? readdirSync(join(do11y, "pages")).filter((page) => page !== "Home.vue" && (page.endsWith(".md") || page.endsWith(".vue")))
         : [];
+    pages = pages.filter((page) => page !== "Sandbox.vue");
     return {
         name: "do11y:routes",
         resolveId(id) {
@@ -60,8 +61,6 @@ export default () => {
           import Home from 'do11y:home';
           import options from 'do11y:options';
 
-          import { RouterView } from 'vue-router';
-
           const homeRoute = {
             path: "/",
             component: Home,
@@ -72,7 +71,7 @@ export default () => {
             }
           };
 
-          const customRoutes = (options.routes ?? []).map(page => ({
+          const customRoutes = (options?.routes ?? []).map(page => ({
             ...page,
 
             meta: {

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

@@ -2,7 +2,7 @@ import type { Plugin } from "vite";
 export declare const toParamId: (path: string) => string;
 /**
  * Creates a seprate sandbox app, and
- * adds access to sandbox components through `do11y:sandbox`.
+ * adds access to sandbox components through `do11y:sandboxes`.
  */
 declare const _default: () => Plugin;
 export default _default;

package/dist/docs/plugins/sandbox.js

@@ -5,10 +5,10 @@ import { indexHtml } from "../html/plugin.js";
 export const toParamId = (path) => parse(path).name.toLowerCase().replace(".sandbox", "").replace(".vue", "");
 /**
  * Creates a seprate sandbox app, and
- * adds access to sandbox components through `do11y:sandbox`.
+ * adds access to sandbox components through `do11y:sandboxes`.
  */
 export default () => {
-    const moduleId = "do11y:sandbox";
+    const moduleId = "do11y:sandboxes";
     const resolvedModuleId = "\0" + moduleId;
     const sandboxFiles = globSync(["(docs|src|packages)/**/*.sandbox.vue"], {
         ignore: ["**/node_modules/**", "**/dist/**"],
@@ -17,7 +17,7 @@ export default () => {
         cwd: root,
     });
     return {
-        name: "do11y:sandbox",
+        name: "do11y:sandboxes",
         ...indexHtml(ui, "sandbox"),
         resolveId(id) {
             if (id === moduleId) {

package/dist/ui/index.js

@@ -1 +1 @@
-import{createApp as e,createBlock as t,defineComponent as n,onBeforeMount as r,openBlock as i,resolveComponent as a,unref as o}from"vue";import s from"do11y:options";import{createRouter as c,createWebHistory as l}from"vue-router";import u from"do11y:routes";import d from"do11y:page-layout";import f from"do11y:css";var p=n({__name:`Page`,setup(e){return r(async()=>{let e=document.createElement(`style`);e.innerHTML=f,document.head.appendChild(e)}),(e,n)=>{let r=a(`RouterView`);return o(d)?(i(),t(o(d),{key:0})):(i(),t(r,{key:1}))}}});(async()=>{let t=c({history:l(`/`),routes:u,scrollBehavior(e,t,n){if(!e.hash)return;let r=document.querySelector(e.hash);if(!r)return;let i=parseFloat(getComputedStyle(r).scrollMarginTop);return{el:e.hash,top:isNaN(i)?n?.top??0:i}}}),n=e(p);await s.setup?.(n,t),n.use(t),n.mount(`#app`)})();
+import{createApp as e,createBlock as t,defineComponent as n,onBeforeMount as r,openBlock as i,resolveComponent as a,unref as o}from"vue";import{createRouter as s,createWebHistory as c}from"vue-router";import l from"do11y:routes";import u from"do11y:options";import d from"do11y:page-layout";import f from"do11y:css";var p=n({__name:`Page`,setup(e){return r(async()=>{let e=document.createElement(`style`);e.innerHTML=f,document.head.appendChild(e)}),(e,n)=>{let r=a(`RouterView`);return o(d)?(i(),t(o(d),{key:0})):(i(),t(r,{key:1}))}}});(async()=>{let t=s({history:c(`/`),routes:l,scrollBehavior(e,t,n){if(!e.hash)return;let r=document.querySelector(e.hash);if(!r)return;let i=parseFloat(getComputedStyle(r).scrollMarginTop);return{el:e.hash,top:isNaN(i)?n?.top??0:i}}}),n=e(p);await u?.setup?.(n,t),n.use(t),n.mount(`#app`)})();

package/dist/ui/sandbox-iframe.js

@@ -1 +1 @@
-import{computed as e,createBlock as t,createElementBlock as n,defineComponent as r,mergeProps as i,onBeforeMount as a,openBlock as o,shallowRef as s,unref as c}from"vue";import l from"do11y:options";var u=[`title`,`src`],d=r({__name:`SandboxIframe`,props:{title:{},id:{},url:{},highlightedSource:{},highlightedStylelessSource:{},highlightedCssSource:{},passedProps:{}},setup(r){let d=r,f=e(()=>`/sandbox?id=${d.id}`),p=s();return a(async()=>{p.value=(await l.SandboxIframe?.())?.default}),(e,a)=>p.value?(o(),t(c(p),i({key:0,title:r.title,id:r.id,url:f.value,"highlighted-source":r.highlightedSource,"highlighted-css-source":r.highlightedCssSource,"highlighted-styleless-source":r.highlightedStylelessSource},r.passedProps),null,16,[`title`,`id`,`url`,`highlighted-source`,`highlighted-css-source`,`highlighted-styleless-source`])):(o(),n(`iframe`,{key:1,title:r.title,src:f.value},null,8,u))}});export{d as default};
+import{computed as e,createBlock as t,createElementBlock as n,defineComponent as r,mergeProps as i,openBlock as a,unref as o}from"vue";import s from"do11y:sandbox-iframe";var c=[`title`,`src`],l=r({__name:`SandboxIframe`,props:{title:{},id:{},url:{},highlightedSource:{},highlightedStylelessSource:{},highlightedCssSource:{},passedProps:{}},setup(r){let l=r,u=e(()=>`/sandbox?id=${l.id}`);return(e,l)=>o(s)?(a(),t(o(s),i({key:0,title:r.title,id:r.id,url:u.value,"highlighted-source":r.highlightedSource,"highlighted-css-source":r.highlightedCssSource,"highlighted-styleless-source":r.highlightedStylelessSource},r.passedProps),null,16,[`title`,`id`,`url`,`highlighted-source`,`highlighted-css-source`,`highlighted-styleless-source`])):(a(),n(`iframe`,{key:1,title:r.title,src:u.value},null,8,c))}});export{l as default};

package/dist/ui/sandbox.js

@@ -1 +1 @@
-import{createApp as e,createBlock as t,createCommentVNode as n,defineComponent as r,onBeforeMount as i,openBlock as a,shallowRef as o,unref as s,withCtx as c}from"vue";import l from"do11y:options";import{parseQuery as u}from"vue-router";import d from"do11y:sandbox";e(r({__name:`Sandbox`,setup(e){let r=u(window.location.search),f=o(),p=o();return i(async()=>{let{component:e}=d.find(({url:e})=>e===r.id)??{};f.value=(await l.Sandbox?.())?.default,p.value=await e?.()}),(e,r)=>f.value?(a(),t(s(f),{key:0},{default:c(()=>[p.value?(a(),t(s(p),{key:0})):n(``,!0)]),_:1})):n(``,!0)}})).mount(`#app`);
+import{createApp as e,createBlock as t,createCommentVNode as n,defineComponent as r,onBeforeMount as i,openBlock as a,shallowRef as o,unref as s,withCtx as c}from"vue";import{parseQuery as l}from"vue-router";import u from"do11y:sandboxes";import d from"do11y:sandbox";e(r({__name:`Sandbox`,setup(e){let r=l(window.location.search),f=o();return i(async()=>{let{component:e}=u.find(({url:e})=>e===r.id)??{};f.value=await e?.()}),(e,r)=>s(d)?(a(),t(s(d),{key:0},{default:c(()=>[f.value?(a(),t(s(f),{key:0})):n(``,!0)]),_:1})):n(``,!0)}})).mount(`#app`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "do11y",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "A bare-bones tool to document Vue components.",
   "keywords": [
     "docs-generator",

package/src/types.d.ts

@@ -16,11 +16,13 @@ declare module "do11y:routes" {
 declare module "do11y:options" {
   import type { Options } from "do11y";
 
-  const options: Omit<Options, "Layout" | "Sandbox" | "SandboxIframe"> & {
-    Layout: () => Promise<{ default: Component }>;
-    Sandbox?: () => Promise<{ default: Component }>;
-    SandboxIframe?: () => Promise<{ default: Component }>;
-  };
+  const options:
+    | (Omit<Options, "Layout" | "Sandbox" | "SandboxIframe"> & {
+        Layout: () => Promise<{ default: Component }>;
+        Sandbox?: () => Promise<{ default: Component }>;
+        SandboxIframe?: () => Promise<{ default: Component }>;
+      })
+    | undefined;
 
   export default options;
 }
@@ -37,12 +39,24 @@ declare module "do11y:page-layout" {
   export default layout;
 }
 
+declare module "do11y:sandbox" {
+  import type { Component } from "vue";
+  const sandbox: Component | undefined;
+  export default sandbox;
+}
+
+declare module "do11y:sandbox-iframe" {
+  import type { Component } from "vue";
+  const iframe: Component | undefined;
+  export default iframe;
+}
+
 declare module "do11y:css" {
   const css: string;
   export default string;
 }
 
-declare module "do11y:sandbox" {
+declare module "do11y:sandboxes" {
   import type { Component } from "vue";
 
   const sandboxes: {