docs: AFCL reference is split into Buttons and Inputs, Layout and Overlays, Data Display and Loading and Charts pages, every example imports its components from @/afcl, previews load only these components and preload the font AdminForth/2005

Author: ivictbor

adminforth/design/system-concepts.md

@@ -22,7 +22,7 @@ Apps restyle and test AdminForth by `af-*` and `afcl-*` classes. A restyle never
 
 - Build UI in core and plugins from AFCL components (`@/afcl`). A plugin may adjust a few classes of a component via `class` or props like `contentClass`.
 - When the same piece of UI shows up in several places, or a piece clearly is a component, add it to AFCL instead of copying markup. Follow AFCL conventions: typed props with `withDefaults`, slots for content, `v-model` for state, `defineExpose` for an imperative API, `mergeClasses` for class overrides, tokens for colors, an `afcl-*` root class.
-- A new AFCL component gets a section in the AFCL docs (`documentation/docs/tutorial/03-Customization/15-afcl.md`) and its states and variants in [system.html](./system.html). Docs examples are live, not screenshots: wrap the code blocks of an example into `<AfclPreview id="...">` and the docs build renders them with real AFCL (see `documentation/afcl-preview/vite.config.ts`).
+- A new AFCL component gets a section on the page of its category in the AFCL docs (`documentation/docs/tutorial/03-Customization/15-afcl/`, a link in its `index.md` as well) and its states and variants in [system.html](./system.html). Docs examples are live, not screenshots: wrap the code blocks of an example into `<AfclPreview id="...">` and the docs build renders them with real AFCL (see `documentation/afcl-preview/vite.config.ts`). Nothing is registered globally, an example imports every AFCL component it uses from `@/afcl`, otherwise the build fails.
 - Example: `DropdownMenu` and `DropdownMenuItem` replaced the hand-made menus of the list (⋯ in the header and in rows), the user menu and the import-export plugin.
 
 ## Disabled state

documentation/afcl-preview/index.html

@@ -4,6 +4,8 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>AFCL preview</title>
+    <!-- otherwise the font is found only when the example renders its text, and the first paint waits for it -->
+    <link rel="preload" href="./node_modules/@fontsource-variable/geist/files/geist-latin-wght-normal.woff2" as="font" type="font/woff2" crossorigin />
   </head>
   <body class="bg-lightHtml text-lightListTableText dark:bg-darkHtml dark:text-darkListTableText">
     <div id="app" class="p-4 sm:p-6"></div>

documentation/afcl-preview/main.ts

@@ -1,6 +1,5 @@
 import { createApp, defineAsyncComponent } from 'vue';
 import { createRouter, createMemoryHistory } from 'vue-router';
-import * as afcl from '@/afcl';
 import { initI18n } from '@/i18n';
 import { coreStore } from './stubs';
 import '@fontsource-variable/geist';
@@ -24,14 +23,14 @@ syncTheme();
 new MutationObserver(syncTheme).observe(docsRoot, { attributeFilter: ['data-theme'] });
 
 const app = createApp(defineAsyncComponent(loadExample));
-Object.entries(afcl).forEach(([name, component]) => typeof component === 'object' && app.component(name, component));
 app.use(createRouter({ history: createMemoryHistory(), routes: [{ path: '/:path(.*)*', component: { render: () => null } }] }));
 initI18n(app);
 app.mount('#app');
 
 // the docs page sizes the iframe to the example, and asks for the height again once it listens
+// offsetHeight rounds a fractional height down as well, the frame then is a bit short and shows a scrollbar
 function postHeight() {
-  window.parent.postMessage({ afclPreview: id, height: document.body.offsetHeight }, '*');
+  window.parent.postMessage({ afclPreview: id, height: Math.ceil(document.body.getBoundingClientRect().height) }, '*');
 }
 new ResizeObserver(postHeight).observe(document.body);
 window.addEventListener('message', (e) => e.data === 'afclPreviewHeight' && postHeight());

documentation/afcl-preview/vite.config.ts

@@ -15,11 +15,14 @@ const docsDir = path.join(previewDir, '../docs');
 const examplesDir = path.join(previewDir, 'examples');
 const spaDir = path.join(previewDir, '../../adminforth/spa');
 const spaSrc = path.join(spaDir, 'src');
+const afclDir = path.join(spaSrc, 'afcl');
 const stubs = path.join(previewDir, 'stubs.ts');
 
 const PREVIEW_RE = /<AfclPreview id="([^"]+)"[^>]*>([\s\S]*?)<\/AfclPreview>/g;
 const CODE_BLOCK_RE = /```(\w+)[^\n]*\n([\s\S]*?)```/g;
 const DIFF_MARKER_RE = /^\s*\/\/\s*diff-(add|remove)\s*$/;
+const AFCL_IMPORT_RE = /^import \{([^}]+)\} from '@\/afcl';?$/gm;
+const COMPONENT_TAG_RE = /<([A-Z]\w*)/g;
 
 // code blocks may show a change with //diff-add and //diff-remove lines, the example renders the result
 function applyDiff(code: string) {
@@ -39,19 +42,33 @@ function applyDiff(code: string) {
 }
 
 // every <AfclPreview> of the docs becomes an SFC: its html code blocks form the template, other blocks the script
+// nothing is registered globally, an example imports its components from '@/afcl' like an app does. The SFC takes
+// each of them from its own file, so an iframe loads only these components and not all of AFCL
 function docsExamples(): Plugin {
   return {
     name: 'afcl-docs-examples',
     buildStart() {
       fs.rmSync(examplesDir, { recursive: true, force: true });
       fs.mkdirSync(examplesDir);
+      const afclComponents = new Set(fs.readdirSync(afclDir).filter((file) => file.endsWith('.vue')).map((file) => path.basename(file, '.vue')));
       const mdFiles = fs.readdirSync(docsDir, { recursive: true, encoding: 'utf-8' }).filter((file) => file.endsWith('.md'));
       for (const file of mdFiles) {
         for (const [, id, body] of fs.readFileSync(path.join(docsDir, file), 'utf-8').matchAll(PREVIEW_RE)) {
           const blocks = [...body.matchAll(CODE_BLOCK_RE)];
           const code = (html: boolean) => blocks.filter(([, lang]) => (lang === 'html') === html).map(([, , src]) => applyDiff(src)).join('\n');
+          const template = code(true);
+          const imported: string[] = [];
+          const script = code(false).replace(AFCL_IMPORT_RE, (_, names: string) => {
+            imported.push(...names.split(',').map((name) => name.trim()));
+            return '';
+          });
+          const notImported = [...template.matchAll(COMPONENT_TAG_RE)].map(([, name]) => name).find((name) => afclComponents.has(name) && !imported.includes(name));
+          if (notImported) {
+            this.error(`AFCL example "${id}" in ${file} uses <${notImported}> but does not import it from '@/afcl'`);
+          }
+          const imports = imported.map((name) => `import ${name} from '@/afcl/${name}.vue';\n`).join('');
           // 'wx' fails on a second example with the same id
-          fs.writeFileSync(path.join(examplesDir, `${id}.vue`), `<script setup lang="ts">\n${code(false)}</script>\n\n<template>\n${code(true)}</template>\n`, { flag: 'wx' });
+          fs.writeFileSync(path.join(examplesDir, `${id}.vue`), `<script setup lang="ts">\n${imports}${script}</script>\n\n<template>\n${template}</template>\n`, { flag: 'wx' });
         }
       }
     },