@conduction/docusaurus-preset 3.32.0 → 3.34.0

package/src/components/MockScene/MockScene.jsx

@@ -44,6 +44,12 @@
  *   - items:     Array of item descriptors (see above)
  *   - width:     scene width in px (default 960)
  *   - height:    scene height in px (default 420)
+ *   - running:   boolean (default true) — the scene assembles: items
+ *     land one by one on a 220ms stagger (opacity + translateY only,
+ *     so the inline left/top positioning is never fought), hold, and
+ *     fade for the loop reset. The loop period derives from the item
+ *     count (--ms-dur, set inline). `running={false}` and
+ *     prefers-reduced-motion show the assembled scene.
  *   - className: string
  */
 
@@ -64,16 +70,24 @@ function renderItem(item) {
   return item.node || null;
 }
 
-export default function MockScene({ items = [], width = 960, height = 420, className }) {
+export default function MockScene({ items = [], width = 960, height = 420, running = true, className }) {
+  /* Landing timing: item i arrives at i × 220ms; ~5s hold after the
+     last landing, then a fade window before the loop restarts. */
+  const STEP = 220;
+  const duration = items.length * STEP + 5600;
   return (
     <div className={[amStyles.am, styles.scene, className].filter(Boolean).join(' ')}>
-      <div className={styles.sceneFrame} style={{ width, height }}>
+      <div
+        className={[styles.sceneFrame, !running && styles.static].filter(Boolean).join(' ')}
+        style={{ width, height, '--ms-dur': `${duration}ms` }}
+      >
         {items.map((item, i) => {
           const wrapperStyle = {
             ...(item.style || {}),
             left: item.x || 0,
             top: item.y || 0,
             zIndex: item.z != null ? item.z : i,
+            animationDelay: `${i * STEP}ms`,
           };
           return (
             <div key={i} className={styles.sceneItem} style={wrapperStyle}>

package/src/components/MockScene/MockScene.module.css

@@ -21,8 +21,28 @@
 
 .am .sceneItem {
   position: absolute;
-  /* `left`, `top`, and optionally `z-index` are set inline by the
-     component from the item's x/y/z values. */
+  /* `left`, `top`, optionally `z-index`, and the landing
+     animation-delay (i × 220ms) are set inline by the component from
+     the item's x/y/z values and index. The landing is transform +
+     opacity only — the inline left/top positioning is never fought.
+     0% and 100% are both hidden, so the staggered delays stay
+     seamless in steady state; `both` keeps a delayed item on its
+     hidden first frame before the initial landing. */
+  animation: msLand var(--ms-dur, 8s) cubic-bezier(0.2, 0.7, 0.3, 1) infinite both;
+}
+
+@keyframes msLand {
+  0%        { opacity: 0; transform: translateY(16px); }
+  4%        { opacity: 1; transform: none; }
+  94%       { opacity: 1; transform: none; }
+  99%, 100% { opacity: 0; transform: none; }
+}
+
+/* Static scene (running={false} and reduced motion): assembled. */
+.am .static .sceneItem { animation: none; }
+
+@media (prefers-reduced-motion: reduce) {
+  .am .sceneItem { animation: none; }
 }
 
 /* Widgets inside a scene drop their LaunchPad-style cobalt-900 dashboard

package/src/components/MockScene/__tests__/MockScene.render.test.js

@@ -0,0 +1,101 @@
+/**
+ * MockScene.render.test.js — SSR-renders the real <MockScene> and
+ * asserts the landing-stagger wiring: inline left/top positioning is
+ * preserved untouched (the animation is transform-only), each item
+ * carries its 220ms-stagger animation-delay, the loop period --ms-dur
+ * derives from the item count, and running={false} puts the static
+ * class on the scene frame. Same esbuild harness as
+ * KanbanMock.render.test.js; CSS modules stubbed to identity.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const {before, after} = test;
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const {build} = require('esbuild');
+const React = require('react');
+const {renderToStaticMarkup} = require('react-dom/server');
+
+const COMPONENT = path.resolve(__dirname, '..', 'MockScene.jsx');
+const PRESET_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+const SCRATCH = path.join(PRESET_ROOT, '.tmp-mock-scene-test');
+
+const ITEMS = [
+  {type: 'widget', kind: 'nextcloud-mail', x: 0, y: 0, size: 'sm'},
+  {type: 'sidebar', kind: 'openregister-metadata', x: 220, y: 30, size: 'md'},
+  {type: 'widget', kind: 'openregister-activity', x: 540, y: 80, size: 'md'},
+];
+
+const cssModuleStub = {
+  name: 'css-module-stub',
+  setup(b) {
+    b.onResolve({filter: /\.module\.css$/}, (args) => ({path: args.path, namespace: 'css-stub'}));
+    b.onLoad({filter: /.*/, namespace: 'css-stub'}, () => ({
+      contents: 'export default new Proxy({}, {get: (_, p) => p});',
+      loader: 'js',
+    }));
+  },
+};
+
+let MockScene;
+
+before(async () => {
+  await fs.mkdir(SCRATCH, {recursive: true});
+  const tmpDir = await fs.mkdtemp(path.join(SCRATCH, 'run-'));
+  const outFile = path.join(tmpDir, 'bundle.cjs');
+  await build({
+    entryPoints: [COMPONENT],
+    outfile: outFile,
+    bundle: true,
+    format: 'cjs',
+    jsx: 'automatic',
+    jsxImportSource: 'react',
+    tsconfigRaw: {compilerOptions: {jsx: 'react-jsx', jsxImportSource: 'react'}},
+    platform: 'node',
+    external: ['react'],
+    plugins: [cssModuleStub],
+    logLevel: 'warning',
+  });
+  delete require.cache[require.resolve(outFile)];
+  MockScene = require(outFile).default;
+});
+
+after(async () => {
+  await fs.rm(SCRATCH, {recursive: true, force: true});
+});
+
+function render(props) {
+  return renderToStaticMarkup(React.createElement(MockScene, props));
+}
+
+test('SSR smoke: renders the scene frame with one wrapper per item', () => {
+  const html = render({items: ITEMS});
+  assert.match(html, /class="sceneFrame"/);
+  assert.equal((html.match(/class="sceneItem"/g) || []).length, ITEMS.length);
+});
+
+test('positioning: inline left/top from item x/y are preserved (animation is transform-only)', () => {
+  const html = render({items: ITEMS});
+  assert.match(html, /left:220px;top:30px/);
+  assert.match(html, /left:540px;top:80px/);
+});
+
+test('landing stagger: each item carries its 220ms-step animation-delay', () => {
+  const html = render({items: ITEMS});
+  for (let i = 0; i < ITEMS.length; i++) {
+    assert.match(html, new RegExp(`animation-delay:${i * 220}ms`), `item ${i}: missing delay`);
+  }
+});
+
+test('loop period: --ms-dur on the frame derives from the item count (+ hold)', () => {
+  const html = render({items: ITEMS});
+  assert.match(html, new RegExp(`--ms-dur:${ITEMS.length * 220 + 5600}ms`));
+});
+
+test('P0 plumbing: running={false} adds the static class to the scene frame; default omits it', () => {
+  assert.match(render({items: ITEMS, running: false}), /class="sceneFrame static"/);
+  assert.doesNotMatch(render({items: ITEMS}), /sceneFrame static/);
+});

package/src/components/WidgetShelf/WidgetShelf.jsx

@@ -37,14 +37,187 @@
  * viewport. Each card has the panel (preview) at the top, title +
  * description below.
  *
+ * Widgets without an explicit `panel` get an auto-generated mini
+ * panel: the title is hashed into one of four token-built archetypes
+ * (KPI tile, mini bar chart, list rows, donut gauge) with a
+ * deterministically chosen accent family, so long carousels look
+ * alive without hand-built mocks. An explicit `panel` always wins.
+ * Same abstraction level as <AppMock>: greeked bars, no real words.
+ *
+ * Controls: the carousel renders a pause/play toggle and prev/next
+ * buttons (cobalt ghost styling). Prev/next nudge the track by one
+ * card with a smooth ease; auto-scroll resumes afterwards unless
+ * paused. Server-side and before hydration the track runs on the
+ * pure-CSS marquee; after mount a rAF loop drives the same transform
+ * so the buttons can steer it. Under reduced motion the controls are
+ * hidden along with the marquee.
+ *
  * Props (beyond eyebrow/title/lede/widgets/columns/className):
  *   - carousel: boolean (default true) — false renders the static grid
- *   - speed:    number — seconds per full carousel loop (default 45)
+ *   - speed:    number — seconds per full carousel loop. Default is
+ *               derived from the widget count (6s per card, min 30s)
+ *               so the per-card reading pace stays constant no matter
+ *               how many widgets a page declares.
  */
 
-import React from 'react';
+import React, {useEffect, useRef, useState} from 'react';
 import styles from './WidgetShelf.module.css';
 
+/* Seconds each card takes to traverse its own width — the per-card
+   reading pace. A 15-widget shelf loops in 90s, a 30-widget one in
+   180s; both feel identical to the reader. */
+const SECONDS_PER_CARD = 6;
+const MIN_LOOP_SECONDS = 30;
+const NUDGE_MS = 450;
+
+/* Accent families available to auto-generated panels — exactly the
+   hex-family policy roster from tokens.css: lavender, mint, forest,
+   terracotta, plus workspaceblue. Coral (KNVB orange) and gold are
+   reserved (one orange per component — the shelf's eyebrow already
+   spends it; gold is the Certified mark only). */
+const AUTO_FAMILIES = ['mint', 'lavender', 'forest', 'terracotta', 'workspaceblue'];
+
+/* djb2-xor string hash with a murmur3-style finalizer — stable across
+   renders and platforms, so the same title always draws the same
+   panel. The finalizer avalanches the bits: without it, titles that
+   differ only in their last character ("Lead 1" / "Lead 2") land in
+   the same accent family because the family picker discards low bits. */
+function hashString(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = (Math.imul(h, 33) ^ str.charCodeAt(i)) >>> 0;
+  }
+  h ^= h >>> 16;
+  h = Math.imul(h, 0x85ebca6b) >>> 0;
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35) >>> 0;
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+
+/**
+ * Auto-generated mini panel for widgets without an explicit `panel`.
+ * Deterministic: archetype and accent family both derive from the
+ * hash of the seed (the widget title). Token-built, greeked, no
+ * words — the card below already shows the real title.
+ */
+function AutoPanel({seed}) {
+  const h = hashString(seed);
+  const family = AUTO_FAMILIES[(h >>> 4) % AUTO_FAMILIES.length];
+  const vars = {
+    '--wsa': `var(--c-${family}-500)`,
+    '--wsa-soft': `var(--c-${family}-300)`,
+  };
+  const kind = h % 4;
+
+  if (kind === 0) {
+    /* KPI number tile. */
+    const value = 12 + (h % 88);
+    const trendW = 32 + ((h >>> 8) % 40);
+    return (
+      <div className={[styles.auto, styles.autoKpi].join(' ')} style={vars} aria-hidden="true">
+        <span className={styles.autoHex} />
+        <span className={styles.autoKpiValue}>{value}</span>
+        <span className={styles.autoKpiBar} style={{width: `${trendW}%`}} />
+      </div>
+    );
+  }
+
+  if (kind === 1) {
+    /* Mini bar chart. */
+    const hi = (h >>> 8) % 6;
+    return (
+      <div className={[styles.auto, styles.autoBars].join(' ')} style={vars} aria-hidden="true">
+        {Array.from({length: 6}, (_, i) => {
+          const height = Math.round(30 + (((h >>> (i * 4)) & 15) / 15) * 65);
+          return (
+            <span
+              key={i}
+              className={[styles.autoBar, i === hi && styles.autoBarHi].filter(Boolean).join(' ')}
+              style={{height: `${height}%`}}
+            />
+          );
+        })}
+      </div>
+    );
+  }
+
+  if (kind === 2) {
+    /* List rows. */
+    const hot = (h >>> 8) % 3;
+    return (
+      <div className={[styles.auto, styles.autoList].join(' ')} style={vars} aria-hidden="true">
+        {Array.from({length: 3}, (_, i) => {
+          const w = Math.round(34 + (((h >>> (i * 5)) & 31) / 31) * 30);
+          return (
+            <span key={i} className={styles.autoRow}>
+              <span className={[styles.autoDot, i === hot && styles.autoDotHi].filter(Boolean).join(' ')} />
+              <span className={styles.autoRowBars}>
+                <span className={styles.autoRowBar} style={{width: `${w}%`}} />
+                <span className={styles.autoRowLine} />
+              </span>
+            </span>
+          );
+        })}
+      </div>
+    );
+  }
+
+  /* Donut gauge. Circumference of r=15.9155 is 100, so the dasharray
+     reads directly as a percentage. */
+  const pct = 34 + ((h >>> 6) % 52);
+  return (
+    <div className={[styles.auto, styles.autoDonut].join(' ')} style={vars} aria-hidden="true">
+      <svg viewBox="0 0 42 42" className={styles.autoRing} aria-hidden="true" focusable="false">
+        <circle cx="21" cy="21" r="15.9155" className={styles.autoRingTrack} />
+        <circle
+          cx="21"
+          cy="21"
+          r="15.9155"
+          className={styles.autoRingFill}
+          strokeDasharray={`${pct} ${100 - pct}`}
+          strokeDashoffset="25"
+        />
+      </svg>
+      <span className={styles.autoDonutBars}>
+        <span className={styles.autoRowBar} style={{width: '64%'}} />
+        <span className={styles.autoRowLine} />
+      </span>
+    </div>
+  );
+}
+
+function ControlIcon({kind}) {
+  if (kind === 'prev') {
+    return (
+      <svg viewBox="0 0 24 24" className={styles.chev} aria-hidden="true" focusable="false">
+        <path d="M15 4l-8 8 8 8" />
+      </svg>
+    );
+  }
+  if (kind === 'next') {
+    return (
+      <svg viewBox="0 0 24 24" className={styles.chev} aria-hidden="true" focusable="false">
+        <path d="M9 4l8 8-8 8" />
+      </svg>
+    );
+  }
+  if (kind === 'pause') {
+    return (
+      <svg viewBox="0 0 24 24" className={styles.glyph} aria-hidden="true" focusable="false">
+        <rect x="6" y="4" width="4" height="16" rx="1" />
+        <rect x="14" y="4" width="4" height="16" rx="1" />
+      </svg>
+    );
+  }
+  /* play */
+  return (
+    <svg viewBox="0 0 24 24" className={styles.glyph} aria-hidden="true" focusable="false">
+      <path d="M8 4.5l12 7.5-12 7.5z" />
+    </svg>
+  );
+}
+
 export default function WidgetShelf({
   eyebrow,
   title,
@@ -52,17 +225,114 @@ export default function WidgetShelf({
   widgets = [],
   columns,
   carousel = true,
-  speed = 45,
+  speed,
   className,
 }) {
   const cols = columns || (widgets.length >= 4 ? 3 : Math.min(widgets.length, 3));
-  const cards = widgets.map((w, i) => (
+  const loopSeconds = speed != null ? speed : Math.max(MIN_LOOP_SECONDS, widgets.length * SECONDS_PER_CARD);
+
+  const [paused, setPaused] = useState(false);
+  const pausedRef = useRef(false);
+  const viewportRef = useRef(null);
+  const trackRef = useRef(null);
+  const groupRef = useRef(null);
+  /* Marquee state lives in a ref: the rAF loop writes the transform
+     directly, so no React re-render per frame. */
+  const marquee = useRef({offset: 0, groupW: 0, step: 0, hover: false, nudge: null});
+
+  useEffect(() => {
+    pausedRef.current = paused;
+  }, [paused]);
+
+  useEffect(() => {
+    if (!carousel || widgets.length === 0) return undefined;
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return undefined;
+    /* Reduced motion: the CSS already collapses the carousel to the
+       static grid and hides the controls; nothing to drive. */
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return undefined;
+
+    const viewport = viewportRef.current;
+    const track = trackRef.current;
+    const group = groupRef.current;
+    if (!viewport || !track || !group) return undefined;
+
+    const m = marquee.current;
+    const measure = () => {
+      /* offsetWidth includes the trailing padding-right gap, so it is
+         exactly the seamless-loop period. */
+      m.groupW = group.offsetWidth;
+      const cards = group.children;
+      m.step = cards.length > 1 ? cards[1].offsetLeft - cards[0].offsetLeft : group.offsetWidth;
+    };
+    measure();
+
+    /* Take over from the pure-CSS marquee (which covers SSR/no-JS). */
+    track.classList.add(styles.jsDriven);
+
+    const onEnter = () => { m.hover = true; };
+    const onLeave = () => { m.hover = false; };
+    viewport.addEventListener('mouseenter', onEnter);
+    viewport.addEventListener('mouseleave', onLeave);
+    viewport.addEventListener('focusin', onEnter);
+    viewport.addEventListener('focusout', onLeave);
+
+    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(measure) : null;
+    if (ro) ro.observe(group);
+
+    let raf = 0;
+    let last = performance.now();
+    const frame = (now) => {
+      const dt = Math.min((now - last) / 1000, 0.1);
+      last = now;
+      if (m.nudge) {
+        const t = Math.min((now - m.nudge.start) / m.nudge.dur, 1);
+        /* ease-in-out cubic */
+        const e = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+        m.offset = m.nudge.from + (m.nudge.to - m.nudge.from) * e;
+        if (t >= 1) m.nudge = null;
+      } else if (!pausedRef.current && !m.hover) {
+        m.offset += (m.groupW / loopSeconds) * dt;
+      }
+      if (m.groupW > 0) {
+        /* Content repeats every groupW px, so wrapping is invisible. */
+        m.offset = ((m.offset % m.groupW) + m.groupW) % m.groupW;
+      }
+      track.style.transform = `translate3d(${-m.offset}px, 0, 0)`;
+      raf = window.requestAnimationFrame(frame);
+    };
+    raf = window.requestAnimationFrame(frame);
+
+    return () => {
+      window.cancelAnimationFrame(raf);
+      if (ro) ro.disconnect();
+      viewport.removeEventListener('mouseenter', onEnter);
+      viewport.removeEventListener('mouseleave', onLeave);
+      viewport.removeEventListener('focusin', onEnter);
+      viewport.removeEventListener('focusout', onLeave);
+      track.classList.remove(styles.jsDriven);
+      track.style.transform = '';
+      m.nudge = null;
+    };
+  }, [carousel, widgets.length, loopSeconds]);
+
+  const nudge = (dir) => {
+    const m = marquee.current;
+    if (!m.step) return;
+    /* Rapid clicks accumulate: continue from the pending target. */
+    const base = m.nudge ? m.nudge.to : m.offset;
+    m.nudge = {from: m.offset, to: base + dir * m.step, start: performance.now(), dur: NUDGE_MS};
+  };
+
+  const renderCard = (w, i) => (
     <article key={i} className={styles.card}>
-      <div className={styles.panel}>{w.panel}</div>
+      <div className={styles.panel}>
+        {w.panel || <AutoPanel seed={w.title ? String(w.title) : `widget-${i}`} />}
+      </div>
       {w.title && <h3 className={styles.cardTitle}>{w.title}</h3>}
       {w.desc && <p className={styles.cardDesc}>{w.desc}</p>}
     </article>
-  ));
+  );
+
   return (
     <section className={[styles.shelf, carousel && styles.carousel, className].filter(Boolean).join(' ')}>
       {(eyebrow || title || lede) && (
@@ -73,32 +343,55 @@ export default function WidgetShelf({
         </header>
       )}
       {carousel ? (
-        <div className={styles.viewport}>
-          <div
-            className={styles.track}
-            style={{'--ws-speed': `${speed}s`}}
-          >
-            <div className={[styles.group, styles[`cols-${cols}`]].join(' ')}>
-              {cards}
-            </div>
-            {/* Seamless-loop duplicate. Hidden from assistive tech so
-                each widget is announced once; under reduced motion the
-                CSS removes it entirely and the first group becomes the
-                static grid. */}
-            <div className={[styles.group, styles.dup].join(' ')} aria-hidden="true">
-              {widgets.map((w, i) => (
-                <article key={i} className={styles.card}>
-                  <div className={styles.panel}>{w.panel}</div>
-                  {w.title && <h3 className={styles.cardTitle}>{w.title}</h3>}
-                  {w.desc && <p className={styles.cardDesc}>{w.desc}</p>}
-                </article>
-              ))}
+        <>
+          <div className={styles.viewport} ref={viewportRef}>
+            <div
+              className={styles.track}
+              ref={trackRef}
+              style={{'--ws-speed': `${loopSeconds}s`}}
+            >
+              <div className={[styles.group, styles[`cols-${cols}`]].join(' ')} ref={groupRef}>
+                {widgets.map(renderCard)}
+              </div>
+              {/* Seamless-loop duplicate. Hidden from assistive tech so
+                  each widget is announced once; under reduced motion the
+                  CSS removes it entirely and the first group becomes the
+                  static grid. */}
+              <div className={[styles.group, styles.dup].join(' ')} aria-hidden="true">
+                {widgets.map(renderCard)}
+              </div>
             </div>
           </div>
-        </div>
+          <div className={styles.controls}>
+            <button
+              type="button"
+              className={styles.ctrl}
+              aria-label="Previous widgets"
+              onClick={() => nudge(-1)}
+            >
+              <ControlIcon kind="prev" />
+            </button>
+            <button
+              type="button"
+              className={styles.ctrl}
+              aria-label={paused ? 'Play' : 'Pause'}
+              onClick={() => setPaused((p) => !p)}
+            >
+              <ControlIcon kind={paused ? 'play' : 'pause'} />
+            </button>
+            <button
+              type="button"
+              className={styles.ctrl}
+              aria-label="Next widgets"
+              onClick={() => nudge(1)}
+            >
+              <ControlIcon kind="next" />
+            </button>
+          </div>
+        </>
       ) : (
         <div className={[styles.grid, styles[`cols-${cols}`]].join(' ')}>
-          {cards}
+          {widgets.map(renderCard)}
         </div>
       )}
     </section>