feat(doc): live demos for all demos/*

.github/workflows/deploy-docs.yml

@@ -30,8 +30,14 @@ jobs:
         cache: "yarn"
     - name: Install dependencies
       run: yarn install
+    - name: Build demos
+      run: yarn workspace @ribajs/doc run build:demos
     - name: Build documentation
       run: yarn workspace @ribajs/doc run build
+    - name: Install Playwright Chromium
+      run: yarn playwright install --with-deps chromium
+    - name: Smoke-test demos
+      run: yarn workspace @ribajs/doc run smoke:demos
     - name: Setup Pages
       uses: actions/configure-pages@v5
     - name: Upload artifact

.gitignore

@@ -4,6 +4,8 @@
 /infra/*/dist/
 !infra/webpack-serve/dist/
 /packages/*/dist/
+/infra/doc/_demos/
+/infra/doc/_smoke/
 /demos/*/dist
 /demos/*/public/iconset
 node_modules/

demos/bs5-tagged-image/src/ts/components/bs5-taggedimage-example/bs5-taggedimage-example.component.html

@@ -168,7 +168,7 @@ <h2 class="font-weight-bold m-0 text-shadow">
   <div class="row">
     <section class="col-12 my-5">
       <h3 class="text-center">Bs5-Slideshow</h3>
-      <bs5-slideshow autoplay="true" autoplay-interval="4000" control-prev-icon-src="arrow_carrot.svg" indicator-inactive-icon-src="icon_circle-empty.svg" indicator-active-icon-src="icon_circle-selected.svg" control-next-icon-src="arrow_carrot.svg">
+      <bs5-slideshow autoplay="true" autoplay-interval="4000" control-prev-icon-src="/iconset/svg/arrow_carrot.svg" indicator-inactive-icon-src="/iconset/svg/icon_circle-empty.svg" indicator-active-icon-src="/iconset/svg/icon_circle-selected.svg" control-next-icon-src="/iconset/svg/arrow_carrot.svg">
         <div class="row slideshow-row">
           <div class="slide-placeholder col-4">&nbsp;</div>
           <div class="slide col-4">

demos/bs5-tagged-image/src/ts/components/bs5-taggedimage-example/bs5-taggedimage-example.component.ts

@@ -39,12 +39,9 @@ export class Bs5TaggedImageExampleComponent extends Component {
 
   protected getFadeshowImageTags() {
     return [1, 2, 3, 4, 5].map((n) => ({
-      src: `../../../images/shotokan-karate-cuxhaven-${n}.jpg`,
+      src: `/images/shotokan-karate-cuxhaven-${n}.jpg`,
       srcset: [800, 1000, 1200, 1400, 1600, 1920]
-        .map(
-          (w) =>
-            `../../../images/shotokan-karate-cuxhaven-${n}-${w}.jpg ${w}w,`,
-        )
+        .map((w) => `/images/shotokan-karate-cuxhaven-${n}-${w}.jpg ${w}w,`)
         .join("\n"),
       title: `Image ${n}`,
       tags: [1, 2, 3, 4, 5, 6, 7].map((n) => ({

demos/content-slider/src/index.html

@@ -1,6 +1,7 @@
 <!DOCTYPE html>
 <html>
   <head>
+    <meta name="referrer" content="no-referrer">
     <title>Content Slider Example</title>
     <link rel="stylesheet" href="./scss/main.scss">
   </head>

demos/iconset/src/ts/main.ts

@@ -4,7 +4,7 @@ import { bs5Module } from "@ribajs/bs5";
 import { coreModule, Riba } from "@ribajs/core";
 import { IconsetModule } from "./iconset.module.js";
 
-const iconsetModules = import.meta.glob("@ribajs/iconset/svg/*.svg");
+const iconsetModules = import.meta.glob("../../../../packages/iconset/src/svg/*.svg");
 const ICONSET = Object.keys(iconsetModules)
   .map((modulePath) => modulePath.split("/").pop()?.replace(".svg", ""))
   .filter((iconName): iconName is string => Boolean(iconName));

demos/podcast-fixed-player/src/ts/data/show.ts

@@ -5,6 +5,6 @@ export const show: PodloveWebPlayerShow = {
   subtitle: "Der Podlove Entwickler:innen Podcast",
   summary:
     "Podlove ist eine Initiative zur Verbesserung der Open Source Infrastruktur zum Podcasting. Podlove ist gleichzeitig auch ein Netzwerk an Entwickler:innen zur Diskussion von Features und Standardisierung.",
-  poster: "/assets/web-player/show.png",
+  poster: "/assets/show.png",
   link: "https://podlovers.org",
 };

demos/podcast/src/ts/data/show.ts

@@ -5,6 +5,6 @@ export const show: PodloveWebPlayerShow = {
   subtitle: "Der Podlove Entwickler:innen Podcast",
   summary:
     "Podlove ist eine Initiative zur Verbesserung der Open Source Infrastruktur zum Podcasting. Podlove ist gleichzeitig auch ein Netzwerk an Entwickler:innen zur Diskussion von Features und Standardisierung.",
-  poster: "/assets/web-player/show.png",
+  poster: "/assets/show.png",
   link: "https://podlovers.org",
 };

demos/router-view/src/ts/components/nav/nav.component.html

@@ -3,9 +3,9 @@
       <div class="row">
           <div class="col-auto d-flex align-items-center">
               <ul class="nav d-none d-lg-flex">
-                  <li class="nav d-flex"><a class="nav-link text-light" href="/index.html">Home</a></li>
-                  <li class="nav d-flex"><a class="nav-link text-light" href="/page-1.html">Page 1</a></li>
-                  <li class="nav d-flex"><a class="nav-link text-light" href="/page-2.html">Page 2</a></li>
+                  <li class="nav d-flex"><a class="nav-link text-light" href="./index.html">Home</a></li>
+                  <li class="nav d-flex"><a class="nav-link text-light" href="./page-1.html">Page 1</a></li>
+                  <li class="nav d-flex"><a class="nav-link text-light" href="./page-2.html">Page 2</a></li>
               </ul>
           </div>
       </div>

e2e/router-basic/navigation.spec.ts

@@ -17,7 +17,7 @@ test.describe("Router basic navigation (no transitions)", () => {
     await routerView.evaluate((el) =>
       el.classList.remove("transition-complete"),
     );
-    await page.locator('a.nav-link[href="/page-1.html"]').click();
+    await page.locator('a.nav-link[href="./page-1.html"]').click();
     await expect(routerView).toHaveClass(/transition-complete/, {
       timeout: 10_000,
     });
@@ -38,7 +38,7 @@ test.describe("Router basic navigation (no transitions)", () => {
     await routerView.evaluate((el) =>
       el.classList.remove("transition-complete"),
     );
-    await page.locator('a.nav-link[href="/page-2.html"]').click();
+    await page.locator('a.nav-link[href="./page-2.html"]').click();
     await expect(routerView).toHaveClass(/transition-complete/, {
       timeout: 10_000,
     });
@@ -48,7 +48,7 @@ test.describe("Router basic navigation (no transitions)", () => {
     await routerView.evaluate((el) =>
       el.classList.remove("transition-complete"),
     );
-    await page.locator('a.nav-link[href="/index.html"]').click();
+    await page.locator('a.nav-link[href="./index.html"]').click();
     await expect(routerView).toHaveClass(/transition-complete/, {
       timeout: 10_000,
     });
@@ -67,7 +67,7 @@ test.describe("Router basic navigation (no transitions)", () => {
     await routerView.evaluate((el) =>
       el.classList.remove("transition-complete"),
     );
-    await page.locator('a.nav-link[href="/page-1.html"]').click();
+    await page.locator('a.nav-link[href="./page-1.html"]').click();
     await expect(routerView).toHaveClass(/transition-complete/, {
       timeout: 10_000,
     });
@@ -93,7 +93,7 @@ test.describe("Router basic navigation (no transitions)", () => {
     await routerView.evaluate((el) =>
       el.classList.remove("transition-complete"),
     );
-    await page.locator('a.nav-link[href="/page-1.html"]').click();
+    await page.locator('a.nav-link[href="./page-1.html"]').click();
     await expect(routerView).toHaveClass(/transition-complete/, {
       timeout: 10_000,
     });

infra/doc/README.md

@@ -0,0 +1,34 @@
+# Riba docs site (`@ribajs/doc`)
+
+Static site built with Vite + Pug, deployed to GitHub Pages (`.github/workflows/deploy-docs.yml`).
+
+## Live demos
+
+Every `demos/*` package with a `package.json` is built into `_demos/<id>/` and copied to
+`_site/demos/<id>/`; `demos.html` is the gallery, `demo.html?id=<id>` embeds a demo in an iframe
+(`rv-demo-viewer`).
+
+| Command | Purpose |
+|---|---|
+| `yarn workspace @ribajs/doc build:demos` | Build all demos (4 in parallel, per-demo timeout, one retry) and write `_demos/manifest.json` |
+| `yarn workspace @ribajs/doc build` | Build the site; copies `_demos` to `_site/demos` |
+| `yarn workspace @ribajs/doc smoke:demos` | Load every demo in headless Chromium; writes `_smoke/report.json` + screenshots, exits 1 on any unexplained finding |
+| `yarn workspace @ribajs/doc start:live` | Site + demo watcher + preview on `http://127.0.0.1:4173` |
+
+Hotlinking demos that load imgur images must send no referrer (`<meta name="referrer" content="no-referrer">`): imgur answers 403 when the `Referer` is an IP literal such as `127.0.0.1`.
+
+### Authoring rules for demos
+
+- Reference assets from `public/` root-absolute (`/images/a.jpg`, `/iconset/svg/x.svg`). The
+  `basePathPlugin` in `infra/vite-config` prefixes them with the Vite `base`, so the demo works at `/`
+  and under `/demos/<id>/`. Do not climb with `../../../images/…` and do not use bare names of files
+  that Vite never emits.
+- Page links in router demos must be relative (`./page-1.html`).
+- A demo that cannot run is not hidden: declare it in the demo's `package.json`:
+
+  ```json
+  { "riba": { "demo": { "knownIssues": [{ "issue": 1234, "title": "Needs a backend" }] } } }
+  ```
+
+  The viewer shows a banner with the link, and the smoke gate reports its findings as `known`
+  instead of failing. `skip: true` leaves a demo out of the build entirely.

infra/doc/package.json

@@ -8,8 +8,12 @@
   "scripts": {
     "build": "vite build --mode production",
     "build:dev": "vite build --mode development",
+    "build:demos": "node scripts/build-demos.js",
+    "smoke:demos": "node scripts/smoke-demos.mjs",
     "watch": "node scripts/watch.js",
+    "watch:demos": "node scripts/watch-demos.js",
     "start": "concurrently 'yarn:watch' 'yarn:preview'",
+    "start:live": "concurrently 'yarn:watch' 'yarn:watch:demos' 'vite preview --host 127.0.0.1 --port 4173 --strictPort'",
     "hmr": "vite serve",
     "preview": "vite preview",
     "clear": "rm -rf ./_site",