@conduction/docusaurus-preset 3.37.0 → 3.39.0

package/src/components/BlueprintRush/BlueprintRush.jsx

@@ -0,0 +1,238 @@
+/**
+ * <BlueprintRush />
+ *
+ * Buildiq's mini-game. A blueprint asks for the parts an app needs,
+ * in the reader's words rather than ours: where the records live, what
+ * one looks like, how people fill it in, who may see it. The tray
+ * offers those parts plus a few that belong to some other app. Fit the
+ * blueprint before the clock runs out; every finished app buys time.
+ *
+ * A puzzle rather than a reaction test, on purpose: the other two
+ * games are about speed, and a third one of those would be the same
+ * game a third time. Here the clock is the only pressure and the work
+ * is reading.
+ *
+ * The rules live in ./engine.js with no DOM and no clock.
+ *
+ * Usage on a product page:
+ *
+ *   <BlueprintRush />
+ *
+ * Fires the shared `connext:gameend` event on game over, and listens
+ * for `connext:gamereplay`, like every other mini-game.
+ *
+ * Accessibility: the tray is a row of buttons, each labelled with the
+ * part it places, and the slots are a list that says what is still
+ * missing. Nothing depends on position or colour.
+ */
+
+import React, {useCallback, useEffect, useRef, useState} from 'react';
+import {translate} from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {createGame, step, place, timeLeft, summarise} from './engine';
+import styles from './BlueprintRush.module.css';
+
+const GAME_ID = 'blueprint-rush';
+const TICK_MS = 100;
+
+/* What the blueprint asks for, and what the tray offers, in the words
+   a business owner would use. The part key is never shown. */
+function partCopy(part) {
+  switch (part) {
+    case 'register':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.register', message: 'Somewhere to keep the records', description: 'Blueprint slot asking for a register'}),
+        tray: translate({id: 'preset.blueprintRush.tray.register', message: 'A register', description: 'Tray part: a register'}),
+      };
+    case 'schema':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.schema', message: 'What one record looks like', description: 'Blueprint slot asking for a schema'}),
+        tray: translate({id: 'preset.blueprintRush.tray.schema', message: 'A set of fields', description: 'Tray part: a schema'}),
+      };
+    case 'form':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.form', message: 'How people fill one in', description: 'Blueprint slot asking for a form'}),
+        tray: translate({id: 'preset.blueprintRush.tray.form', message: 'A form', description: 'Tray part: a form'}),
+      };
+    case 'view':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.view', message: 'How people find one back', description: 'Blueprint slot asking for a list view'}),
+        tray: translate({id: 'preset.blueprintRush.tray.view', message: 'A list with search', description: 'Tray part: a list view'}),
+      };
+    case 'flow':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.flow', message: 'What happens after someone saves', description: 'Blueprint slot asking for a flow'}),
+        tray: translate({id: 'preset.blueprintRush.tray.flow', message: 'A flow', description: 'Tray part: a flow'}),
+      };
+    case 'permission':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.permission', message: 'Who is allowed to see it', description: 'Blueprint slot asking for permissions'}),
+        tray: translate({id: 'preset.blueprintRush.tray.permission', message: 'A group and its rights', description: 'Tray part: permissions'}),
+      };
+    case 'widget':
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.widget', message: 'What the manager sees on Monday', description: 'Blueprint slot asking for a dashboard widget'}),
+        tray: translate({id: 'preset.blueprintRush.tray.widget', message: 'A dashboard widget', description: 'Tray part: a dashboard widget'}),
+      };
+    default:
+      return {
+        slot: translate({id: 'preset.blueprintRush.slot.notification', message: 'Who hears about it', description: 'Blueprint slot asking for a notification'}),
+        tray: translate({id: 'preset.blueprintRush.tray.notification', message: 'A notification', description: 'Tray part: a notification'}),
+      };
+  }
+}
+
+export default function BlueprintRush({className}) {
+  const {i18n} = useDocusaurusContext();
+  const locale = (i18n && i18n.currentLocale) || 'en';
+
+  const [game, setGame] = useState(null);
+  const [seconds, setSeconds] = useState(0);
+  const gameRef = useRef(null);
+  const startedAtRef = useRef(0);
+  const endedRef = useRef(false);
+
+  const running = Boolean(game) && !game.over;
+
+  const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAtRef.current;
+
+  const begin = useCallback(() => {
+    endedRef.current = false;
+    startedAtRef.current = (typeof performance !== 'undefined' ? performance.now() : Date.now());
+    const fresh = createGame({seed: Math.floor(Math.random() * 2 ** 31), now: 0});
+    gameRef.current = fresh;
+    setGame(fresh);
+    setSeconds(Math.ceil(timeLeft(fresh, 0) / 1000));
+  }, []);
+
+  useEffect(() => {
+    if (!running) return undefined;
+    const id = setInterval(() => {
+      const t = now();
+      const next = step(gameRef.current, t);
+      gameRef.current = next;
+      setGame(next);
+      setSeconds(Math.ceil(timeLeft(next, t) / 1000));
+    }, TICK_MS);
+    return () => clearInterval(id);
+  }, [running]);
+
+  useEffect(() => {
+    if (!game || !game.over || endedRef.current) return;
+    endedRef.current = true;
+    if (typeof window === 'undefined') return;
+    window.dispatchEvent(new CustomEvent('connext:gameend', {
+      detail: {
+        id: GAME_ID,
+        won: false,
+        score: game.score,
+        summary: summarise(game, locale),
+        title: translate({id: 'preset.blueprintRush.over.title', message: 'Time, and the blueprint is still open.', description: 'Headline on the game-over dialog after a blueprint-rush run'}),
+        subtitle: translate({id: 'preset.blueprintRush.over.subtitle', message: 'Every finished app bought you seconds. The wrong parts spent them.', description: 'Subtitle on the game-over dialog after a blueprint-rush run'}),
+      },
+    }));
+  }, [game, locale]);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+    const onReplay = (e) => { if (e.detail && e.detail.id === GAME_ID) begin(); };
+    window.addEventListener('connext:gamereplay', onReplay);
+    return () => window.removeEventListener('connext:gamereplay', onReplay);
+  }, [begin]);
+
+  const put = useCallback((part) => {
+    if (!gameRef.current || gameRef.current.over) return;
+    const t = now();
+    const next = place(gameRef.current, part, t);
+    gameRef.current = next;
+    setGame(next);
+    setSeconds(Math.ceil(timeLeft(next, t) / 1000));
+  }, []);
+
+  const blueprint = game ? game.blueprint : null;
+  const filled = blueprint ? blueprint.filled : [];
+  const last = game && game.last ? game.last : null;
+
+  return (
+    <section className={[styles.br, className].filter(Boolean).join(' ')} aria-labelledby="blueprint-rush-title">
+      <header className={styles.head}>
+        <div>
+          <p className={styles.eyebrow}>
+            {translate({id: 'preset.blueprintRush.eyebrow', message: 'Mini-game', description: 'Eyebrow above the blueprint-rush game on a product page'})}
+          </p>
+          <h3 className={styles.title} id="blueprint-rush-title">
+            {translate({id: 'preset.blueprintRush.title', message: 'Blueprint rush', description: 'Name of the Buildiq mini-game'})}
+          </h3>
+          <p className={styles.lede}>
+            {translate({id: 'preset.blueprintRush.lede', message: 'Every app needs the same few parts. Pick them off the shelf before the clock runs out, and skip the ones that belong to somebody else’s app.', description: 'One-line explanation of the blueprint-rush rules'})}
+          </p>
+        </div>
+        <div className={styles.hud} role="status" aria-live="polite">
+          <span className={styles.hudPill}>
+            {translate({id: 'preset.blueprintRush.hud.score', message: 'Score {score}', description: 'Score readout on the blueprint-rush HUD'}, {score: Number(game ? game.score : 0).toLocaleString(locale)})}
+          </span>
+          <span className={[styles.hudPill, running && seconds <= 5 && styles.hudLow].filter(Boolean).join(' ')}>
+            {translate({id: 'preset.blueprintRush.hud.time', message: '{seconds}s left', description: 'Remaining-time readout on the blueprint-rush HUD'}, {seconds: running ? seconds : 0})}
+          </span>
+        </div>
+      </header>
+
+      <div className={styles.board}>
+        <ol className={styles.slots}>
+          {(blueprint ? blueprint.needed : []).map((part) => {
+            const done = filled.includes(part);
+            const copy = partCopy(part);
+            return (
+              <li key={part} className={[styles.slot, done && styles.slotDone].filter(Boolean).join(' ')}>
+                <span className={styles.slotMark} aria-hidden="true" />
+                <span className={styles.slotText}>{copy.slot}</span>
+                <span className={styles.slotState}>
+                  {done
+                    ? translate({id: 'preset.blueprintRush.slot.done', message: 'in place', description: 'State of a blueprint slot that has been filled'})
+                    : translate({id: 'preset.blueprintRush.slot.open', message: 'open', description: 'State of a blueprint slot that is still empty'})}
+                </span>
+              </li>
+            );
+          })}
+          {!blueprint && (
+            <li className={styles.slot}>
+              <span className={styles.slotText}>
+                {translate({id: 'preset.blueprintRush.idle', message: 'An empty blueprint, and a shelf full of parts.', description: 'Placeholder on the blueprint before the game starts'})}
+              </span>
+            </li>
+          )}
+        </ol>
+
+        <div className={styles.tray}>
+          {(blueprint ? blueprint.tray : []).map((part) => {
+            const done = filled.includes(part);
+            return (
+              <button
+                key={part}
+                type="button"
+                className={[styles.part, done && styles.partUsed].filter(Boolean).join(' ')}
+                onClick={() => put(part)}
+                disabled={!running || done}>
+                {partCopy(part).tray}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+
+      <footer className={styles.foot}>
+        <button type="button" className={styles.start} onClick={begin}>
+          {game
+            ? translate({id: 'preset.blueprintRush.restart', message: 'Restart', description: 'Button that restarts the blueprint-rush game'})
+            : translate({id: 'preset.blueprintRush.start', message: 'Open a blueprint', description: 'Button that starts the blueprint-rush game'})}
+        </button>
+        <p className={styles.hint} role="status" aria-live="polite">
+          {last && last.result === 'built' && translate({id: 'preset.blueprintRush.feedback.built', message: 'App built. That bought you seven seconds.', description: 'Feedback after completing a blueprint'})}
+          {last && last.result === 'wrong' && translate({id: 'preset.blueprintRush.feedback.wrong', message: 'That part belongs to another app. Two and a half seconds gone.', description: 'Feedback after picking a part the blueprint does not need'})}
+          {last && last.result === 'duplicate' && translate({id: 'preset.blueprintRush.feedback.duplicate', message: 'That one is already in place.', description: 'Feedback after picking a part that is already on the blueprint'})}
+          {(!last || last.result === 'placed' || last.result === 'timeout') && translate({id: 'preset.blueprintRush.hint', message: 'Read the blueprint, then take what it asks for. Each app in a row is worth more than the last.', description: 'Hint under the blueprint-rush board'})}
+        </p>
+      </footer>
+    </section>
+  );
+}

package/src/components/BlueprintRush/BlueprintRush.module.css

@@ -0,0 +1,186 @@
+/**
+ * <BlueprintRush /> styles.
+ *
+ * Tokens only. One accent: the clock in its last five seconds. The
+ * blueprint reads as a checklist because that is what it is, and the
+ * state of every slot is a word, not a colour.
+ */
+
+.br {
+  border: 1px solid var(--c-cobalt-100);
+  border-radius: var(--radius-lg);
+  background: white;
+  padding: clamp(16px, 3vw, 28px);
+  font-family: var(--conduction-typography-font-family-body);
+}
+
+.head {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  align-items: flex-start;
+  justify-content: space-between;
+  margin-bottom: 18px;
+}
+
+.eyebrow {
+  margin: 0 0 4px;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--c-orange-knvb);
+}
+
+.title {
+  margin: 0 0 6px;
+  font-size: 20px;
+  font-weight: 700;
+  color: var(--c-cobalt-900);
+}
+
+.lede {
+  margin: 0;
+  max-width: 58ch;
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--c-cobalt-700);
+}
+
+.hud {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+.hudPill {
+  padding: 6px 10px;
+  border-radius: var(--radius-pill);
+  background: var(--c-cobalt-50);
+  color: var(--c-cobalt-900);
+  white-space: nowrap;
+}
+.hudLow {
+  background: var(--c-orange-knvb);
+  color: white;
+}
+
+.board {
+  display: grid;
+  grid-template-columns: minmax(0, 1.1fr) minmax(0, 1fr);
+  gap: 20px;
+  align-items: start;
+  max-width: 760px;
+}
+@media (max-width: 720px) {
+  .board { grid-template-columns: 1fr; }
+}
+
+.slots {
+  list-style: none;
+  margin: 0;
+  padding: 14px;
+  border: 1px dashed var(--c-cobalt-200);
+  border-radius: var(--radius-md);
+  background: var(--c-cobalt-50);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.slot {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 14px;
+  color: var(--c-cobalt-700);
+  line-height: 1.35;
+}
+
+.slotMark {
+  width: 10px;
+  height: 12px;
+  flex-shrink: 0;
+  clip-path: var(--hex-pointy-top);
+  background: var(--c-cobalt-300);
+}
+.slotDone .slotMark { background: var(--c-mint-500); }
+
+.slotText { flex: 1; }
+.slotDone .slotText { color: var(--c-cobalt-900); }
+
+.slotState {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  color: var(--c-cobalt-400);
+  white-space: nowrap;
+}
+.slotDone .slotState { color: var(--c-mint-500); }
+
+.tray {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-content: flex-start;
+}
+
+.part {
+  padding: 10px 14px;
+  border: 1px solid var(--c-cobalt-200);
+  border-radius: var(--radius-pill);
+  background: white;
+  font-family: inherit;
+  font-size: 13px;
+  color: var(--c-cobalt-900);
+  cursor: pointer;
+  transition: border-color 120ms ease, background 120ms ease;
+}
+.part:hover:not(:disabled) { border-color: var(--c-blue-cobalt); background: var(--c-cobalt-50); }
+.part:disabled { cursor: default; }
+.part:focus-visible { outline: 2px solid var(--c-blue-cobalt); outline-offset: 2px; }
+
+.partUsed {
+  opacity: 0.45;
+  text-decoration: line-through;
+}
+
+.foot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-top: 16px;
+}
+
+.start {
+  background: var(--c-blue-cobalt);
+  color: white;
+  border: 1px solid var(--c-blue-cobalt);
+  padding: 10px 18px;
+  border-radius: var(--radius-md);
+  font-family: inherit;
+  font-weight: 500;
+  font-size: 14px;
+  cursor: pointer;
+  transition: background 120ms ease;
+}
+.start:hover { background: var(--c-cobalt-700); border-color: var(--c-cobalt-700); }
+.start:focus-visible { outline: 2px solid var(--c-cobalt-900); outline-offset: 2px; }
+
+.hint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--c-cobalt-400);
+  max-width: 52ch;
+  min-height: 1.5em;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .slotDone .slotMark { animation: brSet 200ms ease-out; }
+  @keyframes brSet {
+    from { transform: scale(0.4); }
+    to   { transform: scale(1); }
+  }
+}

package/src/components/BlueprintRush/__tests__/engine.test.js

@@ -0,0 +1,154 @@
+/**
+ * engine.test.js — the blueprint-rush rules.
+ *
+ * The one that matters: the tray must always contain every part the
+ * blueprint asks for. A deal that is missing one is unwinnable, and an
+ * unwinnable board in a timed game reads to the player as the game
+ * being broken, which it would be.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {createGame, step, place, timeLeft, summarise, PARTS, DEFAULTS} = require('../engine.js');
+
+/** Complete the current blueprint correctly. */
+function build(state, now = 0) {
+  let s = state;
+  for (const part of [...s.blueprint.needed]) s = place(s, part, now);
+  return s;
+}
+
+test('a game opens with a blueprint, a tray and a clock', () => {
+  const s = createGame({seed: 1, now: 0});
+  assert.equal(s.blueprint.needed.length, DEFAULTS.slots);
+  assert.equal(s.blueprint.filled.length, 0);
+  assert.equal(timeLeft(s, 0), DEFAULTS.startMs);
+  assert.equal(s.over, false);
+});
+
+test('the tray always holds every part the blueprint asks for, plus the distractors', () => {
+  /* Twenty deals, because a shuffle bug shows up as one bad board in
+     a handful, not as every board. */
+  for (let seed = 1; seed <= 20; seed++) {
+    let s = createGame({seed, now: 0});
+    for (let round = 0; round < 3; round++) {
+      const {needed, tray} = s.blueprint;
+      for (const part of needed) {
+        assert.ok(tray.includes(part), `seed ${seed}: tray cannot complete the blueprint`);
+      }
+      assert.equal(tray.length, DEFAULTS.slots + DEFAULTS.distractors);
+      assert.equal(new Set(tray).size, tray.length, 'a part appears twice in the tray');
+      for (const part of tray) assert.ok(PARTS.includes(part), `unknown part ${part}`);
+      s = build(s, 100 * round);
+    }
+  }
+});
+
+test('placing a needed part fills its slot without scoring yet', () => {
+  let s = createGame({seed: 3, now: 0});
+  const first = s.blueprint.needed[0];
+  s = place(s, first, 10);
+  assert.deepEqual(s.blueprint.filled, [first]);
+  assert.equal(s.score, 0);
+  assert.equal(s.built, 0);
+});
+
+test('completing a blueprint scores, buys time and deals the next one', () => {
+  let s = createGame({seed: 4, now: 0});
+  const before = timeLeft(s, 0);
+  const firstNeeded = [...s.blueprint.needed];
+  s = build(s, 0);
+  assert.equal(s.built, 1);
+  assert.equal(s.score, DEFAULTS.pointsPerApp);
+  assert.equal(timeLeft(s, 0), before + DEFAULTS.bonusMs);
+  assert.equal(s.blueprint.filled.length, 0, 'the next blueprint started already filled');
+  assert.equal(s.blueprint.needed.length, DEFAULTS.slots);
+  assert.notDeepEqual(s.blueprint.needed, firstNeeded, 'the same blueprint was dealt twice in a row');
+});
+
+test('a streak of finished apps pays more each time', () => {
+  let s = createGame({seed: 5, now: 0});
+  s = build(s, 0);
+  const first = s.score;
+  s = build(s, 10);
+  assert.equal(s.score - first, DEFAULTS.pointsPerApp + DEFAULTS.comboBonus);
+  assert.equal(s.bestCombo, 2);
+});
+
+test('a part from some other app costs seconds, not a life', () => {
+  let s = createGame({seed: 6, now: 0});
+  const wrong = s.blueprint.tray.find((p) => !s.blueprint.needed.includes(p));
+  const before = timeLeft(s, 0);
+  s = place(s, wrong, 20);
+  assert.equal(timeLeft(s, 0), before - DEFAULTS.penaltyMs);
+  assert.equal(s.wrong, 1);
+  assert.equal(s.over, false, 'a wrong part ended the run');
+  assert.equal(s.blueprint.filled.length, 0);
+});
+
+test('placing the same part twice is a mistake, and the slot stays filled once', () => {
+  let s = createGame({seed: 7, now: 0});
+  const part = s.blueprint.needed[0];
+  s = place(s, part, 10);
+  /* Compare the deadline, not the time left: the clock moves between
+     the two reads and would hide or invent a penalty of its own. */
+  const deadlineBefore = s.endsAt;
+  s = place(s, part, 20);
+  assert.deepEqual(s.blueprint.filled, [part]);
+  assert.equal(s.endsAt, deadlineBefore - DEFAULTS.penaltyMs);
+  assert.equal(s.last.result, 'duplicate');
+});
+
+test('a wrong part breaks the streak', () => {
+  let s = createGame({seed: 8, now: 0});
+  s = build(s, 0);
+  assert.equal(s.combo, 1);
+  const wrong = s.blueprint.tray.find((p) => !s.blueprint.needed.includes(p));
+  s = place(s, wrong, 10);
+  assert.equal(s.combo, 0);
+  assert.equal(s.bestCombo, 1, 'the best streak was forgotten');
+});
+
+test('the clock ends the run, and nothing scores afterwards', () => {
+  let s = createGame({seed: 9, now: 0});
+  s = step(s, DEFAULTS.startMs + 1);
+  assert.equal(s.over, true);
+  assert.equal(timeLeft(s, DEFAULTS.startMs + 1), 0);
+
+  const frozen = place(s, s.blueprint.needed[0], DEFAULTS.startMs + 10);
+  assert.equal(frozen.score, s.score);
+  assert.equal(frozen.built, s.built);
+});
+
+test('a penalty that empties the clock ends the run there and then', () => {
+  let s = createGame({seed: 10, now: 0, config: {startMs: 2000}});
+  const wrong = s.blueprint.tray.find((p) => !s.blueprint.needed.includes(p));
+  s = place(s, wrong, 100);
+  assert.equal(s.over, true, 'the run kept going on an empty clock');
+  assert.equal(timeLeft(s, 100), 0);
+});
+
+test('the clock never reads negative', () => {
+  const s = createGame({seed: 11, now: 0});
+  assert.equal(timeLeft(s, DEFAULTS.startMs * 10), 0);
+});
+
+test('the same seed deals the same blueprints, a different one does not', () => {
+  const deals = (seed) => {
+    let s = createGame({seed, now: 0});
+    const out = [];
+    for (let i = 0; i < 4; i++) { out.push(s.blueprint.needed.join(',')); s = build(s, i); }
+    return out.join('|');
+  };
+  assert.equal(deals(42), deals(42));
+  assert.notEqual(deals(42), deals(43));
+});
+
+test('the summary reads as a sentence in both locales', () => {
+  const s = {built: 6, bestCombo: 3};
+  assert.match(summarise(s, 'en'), /6 apps built · streak 3/);
+  assert.match(summarise(s, 'nl'), /6 apps gebouwd · reeks 3/);
+});