@conduction/docusaurus-preset 3.39.0 → 3.41.0

package/src/components/LockPick/engine.js

@@ -0,0 +1,172 @@
+/**
+ * Lock pick — the rules, with no DOM and no clock of its own.
+ *
+ * Keepiq's game, and the one everybody already knows how to play: set
+ * the pick, turn the cylinder, feel how far it gives. Close to the
+ * sweet spot it turns; far from it the pick strains and eventually
+ * snaps. Three picks and the lock wins.
+ *
+ * The feedback is graded rather than binary, which is what makes it a
+ * game of deduction instead of a lottery: every turn tells you how
+ * close you were, so the next one is a better guess. It also means the
+ * lock is pickable without seeing anything, which matters more here
+ * than the animation does.
+ *
+ * Nothing in here runs on a clock. A lock is a state machine, not a
+ * race, and that is the difference between this game and the other
+ * four.
+ */
+
+export const POSITIONS = 100;
+
+export const DEFAULTS = {
+  picks: 3,
+  /* How far off the sweet spot the pick may be and still open the
+     lock, as positions on the dial. Narrows each time a lock opens,
+     down to a floor that is still findable by halving the range. */
+  toleranceStart: 9,
+  toleranceFloor: 3,
+  toleranceStep: 1,
+  /* A pick survives a few bad turns near the spot and one wild one.
+     Strain is the square of how far off you were, so the punishment
+     for a guess a long way out is what ends a pick, not patience. */
+  durability: 100,
+  strainScale: 2.4,
+  /* No single turn may snap a fresh pick. Without this cap a guess at
+     the far end of the dial costs a whole pick, so a player who has
+     not found the spot yet loses all three before learning anything,
+     and the graded feedback the game is built on never gets read. Two
+     wild turns in a row still end a pick. */
+  maxStrain: 55,
+  pointsPerLock: 20,
+  /* What is left of the pick when the lock opens is worth points: it
+     rewards deduction over brute force, which is the whole game. */
+  durabilityBonusDivisor: 5,
+};
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function random() {
+    a |= 0; a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function newLock(state) {
+  const tolerance = Math.max(
+    state.cfg.toleranceFloor,
+    state.cfg.toleranceStart - state.opened * state.cfg.toleranceStep,
+  );
+  /* Keep the sweet spot off the very edges: a lock whose answer is 0
+     or 99 is opened by the two guesses everybody tries first. */
+  const margin = tolerance + 2;
+  const span = POSITIONS - 1 - margin * 2;
+  return {
+    sweet: margin + Math.floor(state.random() * (span + 1)),
+    tolerance,
+    attempts: 0,
+  };
+}
+
+export function createGame({seed = Date.now(), config = {}} = {}) {
+  const cfg = {...DEFAULTS, ...config};
+  const base = {
+    cfg,
+    random: mulberry32(seed),
+    position: Math.floor(POSITIONS / 2),
+    picks: cfg.picks,
+    durability: cfg.durability,
+    score: 0,
+    opened: 0,
+    snapped: 0,
+    turns: 0,
+    last: null,
+    over: false,
+  };
+  return {...base, lock: newLock(base)};
+}
+
+/** Move the pick. The dial does not wrap: both ends are ends. */
+export function setPosition(state, position) {
+  if (state.over) return state;
+  const clamped = Math.min(POSITIONS - 1, Math.max(0, Math.round(position)));
+  return clamped === state.position ? state : {...state, position: clamped};
+}
+
+export function nudge(state, delta) {
+  return setPosition(state, state.position + delta);
+}
+
+/**
+ * How far the cylinder turns at the current position, 0 to 1.
+ *
+ * Inside the tolerance it is 1: the lock opens. Outside, it falls away
+ * with distance, and that number is both the feedback the player reads
+ * and the inverse of the strain the pick takes.
+ */
+export function give(state) {
+  const distance = Math.abs(state.position - state.lock.sweet);
+  if (distance <= state.lock.tolerance) return 1;
+  const reach = POSITIONS / 2;
+  return Math.max(0, 1 - (distance - state.lock.tolerance) / reach);
+}
+
+/**
+ * Turn the cylinder.
+ *
+ * Opens the lock, or costs the pick some life. A pick that runs out
+ * snaps, and the next one starts fresh on the same lock: the lock is
+ * not re-dealt, because a player who has narrowed it down to two
+ * positions should not lose that work to a broken pick.
+ */
+export function turn(state) {
+  if (state.over) return state;
+
+  const turned = give(state);
+  const attempts = state.lock.attempts + 1;
+  const base = {...state, turns: state.turns + 1, lock: {...state.lock, attempts}};
+
+  if (turned >= 1) {
+    const bonus = Math.round(base.durability / base.cfg.durabilityBonusDivisor);
+    const opened = {
+      ...base,
+      score: base.score + base.cfg.pointsPerLock + bonus,
+      opened: base.opened + 1,
+      durability: base.cfg.durability,
+      last: {result: 'opened', points: base.cfg.pointsPerLock + bonus, attempts},
+    };
+    /* A fresh lock, and a fresh pick with it: the run ends on the
+       locks that beat you, not on wear from the ones you solved. */
+    return {...opened, lock: newLock(opened), position: Math.floor(POSITIONS / 2)};
+  }
+
+  const strain = Math.min(
+    base.cfg.maxStrain,
+    Math.round((1 - turned) ** 2 * 100 * base.cfg.strainScale / 2) + 4,
+  );
+  const durability = base.durability - strain;
+
+  if (durability > 0) {
+    return {...base, durability, last: {result: 'held', give: turned, attempts}};
+  }
+
+  const picks = base.picks - 1;
+  return {
+    ...base,
+    picks,
+    snapped: base.snapped + 1,
+    durability: base.cfg.durability,
+    last: {result: 'snapped', give: turned, attempts},
+    over: picks <= 0,
+  };
+}
+
+/** The line that goes on the game-over card and into the post. */
+export function summarise(state, locale = 'en') {
+  const n = (v) => Number(v || 0).toLocaleString(locale);
+  return locale === 'nl'
+    ? `${n(state.opened)} sloten open · ${n(state.turns)} pogingen`
+    : `${n(state.opened)} locks opened · ${n(state.turns)} turns`;
+}

package/src/components/PaintByTokens/PaintByTokens.jsx

@@ -0,0 +1,226 @@
+/**
+ * <PaintByTokens />
+ *
+ * Thematiq's mini-game. Paint by numbers, where the numbers are the
+ * tokens a theme is made of: surface, accent, ink, muted, line. Pick a
+ * token, fill the cells that ask for it, finish the picture before the
+ * clock runs out.
+ *
+ * The swatch is never the answer. Each cell says which token it wants,
+ * and what colour that token is depends on the theme the page is
+ * wearing, which is the habit the app exists to teach.
+ *
+ * The rules live in ./engine.js with no DOM and no clock.
+ *
+ * Usage on a product page:
+ *
+ *   <PaintByTokens />
+ *
+ * Fires the shared `connext:gameend` event on game over, and listens
+ * for `connext:gamereplay`.
+ *
+ * Accessibility: every cell is a button that says which token it wants
+ * and whether it is filled, and the palette is a radio-style row on the
+ * number keys. Nothing here needs colour to be played, which is a
+ * strange thing to say about a painting game and the reason it works.
+ */
+
+import React, {useCallback, useEffect, useRef, useState} from 'react';
+import {translate} from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {createGame, paint, select, step, timeLeft, remaining, summarise, TOKENS, COLS} from './engine';
+import styles from './PaintByTokens.module.css';
+
+const GAME_ID = 'paint-by-tokens';
+const TICK_MS = 100;
+
+function tokenLabel(token) {
+  switch (TOKENS[token]) {
+    case 'surface':
+      return translate({id: 'preset.paintByTokens.token.surface', message: 'surface', description: 'Name of the surface token in the paint-by-tokens game'});
+    case 'accent':
+      return translate({id: 'preset.paintByTokens.token.accent', message: 'accent', description: 'Name of the accent token in the paint-by-tokens game'});
+    case 'ink':
+      return translate({id: 'preset.paintByTokens.token.ink', message: 'ink', description: 'Name of the ink token in the paint-by-tokens game'});
+    case 'muted':
+      return translate({id: 'preset.paintByTokens.token.muted', message: 'muted', description: 'Name of the muted token in the paint-by-tokens game'});
+    default:
+      return translate({id: 'preset.paintByTokens.token.line', message: 'line', description: 'Name of the line token in the paint-by-tokens game'});
+  }
+}
+
+export default function PaintByTokens({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.paintByTokens.over.title', message: 'Time, and the theme is half painted.', description: 'Headline on the game-over dialog after a paint-by-tokens run'}),
+        subtitle: translate({id: 'preset.paintByTokens.over.subtitle', message: 'Every finished picture bought you time. Painting by eye spent it.', description: 'Subtitle on the game-over dialog after a paint-by-tokens 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 pick = useCallback((token) => {
+    if (!gameRef.current) return;
+    const next = select(gameRef.current, token);
+    gameRef.current = next;
+    setGame(next);
+  }, []);
+
+  const fill = useCallback((index) => {
+    if (!gameRef.current || gameRef.current.over) return;
+    const t = now();
+    const next = paint(gameRef.current, index, t);
+    gameRef.current = next;
+    setGame(next);
+    setSeconds(Math.ceil(timeLeft(next, t) / 1000));
+  }, []);
+
+  useEffect(() => {
+    if (!running || typeof window === 'undefined') return undefined;
+    const onKey = (e) => {
+      const n = Number(e.key);
+      if (Number.isInteger(n) && n >= 1 && n <= TOKENS.length) {
+        e.preventDefault();
+        pick(n - 1);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [running, pick]);
+
+  const cells = game ? game.cells : [];
+  const selected = game ? game.selected : 0;
+  const last = game ? game.last : null;
+
+  return (
+    <section className={[styles.pbt, className].filter(Boolean).join(' ')} aria-labelledby="paint-by-tokens-title">
+      <header className={styles.head}>
+        <div>
+          <p className={styles.eyebrow}>
+            {translate({id: 'preset.paintByTokens.eyebrow', message: 'Mini-game', description: 'Eyebrow above the paint-by-tokens game on a product page'})}
+          </p>
+          <h3 className={styles.title} id="paint-by-tokens-title">
+            {translate({id: 'preset.paintByTokens.title', message: 'Paint by tokens', description: 'Name of the Thematiq mini-game'})}
+          </h3>
+          <p className={styles.lede}>
+            {translate({id: 'preset.paintByTokens.lede', message: 'Paint by numbers, except the numbers are tokens. Every cell says which one it wants, and what colour that is depends on the theme, not on your eye.', description: 'One-line explanation of the paint-by-tokens rules'})}
+          </p>
+        </div>
+        <div className={styles.hud} role="status" aria-live="polite">
+          <span className={styles.hudPill}>
+            {translate({id: 'preset.paintByTokens.hud.score', message: 'Score {score}', description: 'Score readout on the paint-by-tokens 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.paintByTokens.hud.time', message: '{seconds}s left', description: 'Remaining-time readout on the paint-by-tokens HUD'}, {seconds: running ? seconds : 0})}
+          </span>
+          <span className={styles.hudPill}>
+            {translate({id: 'preset.paintByTokens.hud.left', message: '{left} cells to go', description: 'Remaining-cells readout on the paint-by-tokens HUD'}, {left: game ? remaining(game) : 0})}
+          </span>
+        </div>
+      </header>
+
+      <div className={styles.palette} role="group" aria-label={translate({id: 'preset.paintByTokens.paletteLabel', message: 'Tokens', description: 'Accessible name for the paint-by-tokens palette'})}>
+        {TOKENS.map((_, i) => (
+          <button
+            key={i}
+            type="button"
+            className={[styles.swatch, styles[`tone${i}`], i === selected && styles.swatchOn].filter(Boolean).join(' ')}
+            onClick={() => pick(i)}
+            disabled={!running}
+            aria-pressed={i === selected}>
+            <span className={styles.swatchKey} aria-hidden="true">{i + 1}</span>
+            <span className={styles.swatchName}>{tokenLabel(i)}</span>
+          </button>
+        ))}
+      </div>
+
+      <div className={styles.grid} style={{gridTemplateColumns: `repeat(${COLS}, minmax(0, 1fr))`}}>
+        {cells.map((cell, i) => (
+          <button
+            key={i}
+            type="button"
+            className={[
+              styles.cell,
+              cell.painted && styles.cellPainted,
+              cell.painted && styles[`tone${cell.token}`],
+            ].filter(Boolean).join(' ')}
+            onClick={() => fill(i)}
+            disabled={!running || cell.painted}
+            aria-label={cell.painted
+              ? translate({id: 'preset.paintByTokens.cell.done', message: 'Filled with {token}', description: 'Accessible label for a painted cell'}, {token: tokenLabel(cell.token)})
+              : translate({id: 'preset.paintByTokens.cell.open', message: 'Wants {token}', description: 'Accessible label for an unpainted cell'}, {token: tokenLabel(cell.token)})}>
+            <span aria-hidden="true">{cell.painted ? '' : cell.token + 1}</span>
+          </button>
+        ))}
+        {!game && (
+          <p className={styles.idle}>
+            {translate({id: 'preset.paintByTokens.idle', message: 'An empty theme, and five tokens to fill it with.', description: 'Placeholder before the paint-by-tokens game starts'})}
+          </p>
+        )}
+      </div>
+
+      <footer className={styles.foot}>
+        <button type="button" className={styles.start} onClick={begin}>
+          {game
+            ? translate({id: 'preset.paintByTokens.restart', message: 'Restart', description: 'Button that restarts the paint-by-tokens game'})
+            : translate({id: 'preset.paintByTokens.start', message: 'Open a theme', description: 'Button that starts the paint-by-tokens game'})}
+        </button>
+        <p className={styles.hint} role="status" aria-live="polite">
+          {last && last.result === 'finished' && translate({id: 'preset.paintByTokens.feedback.finished', message: 'Theme done. That bought you twenty seconds.', description: 'Feedback after finishing a picture'})}
+          {last && last.result === 'wrong' && translate(
+            {id: 'preset.paintByTokens.feedback.wrong', message: 'That cell wanted {wanted}, not {used}. Three seconds gone.', description: 'Feedback after filling a cell with the wrong token'},
+            {wanted: tokenLabel(last.wanted), used: tokenLabel(last.used)},
+          )}
+          {(!last || last.result === 'painted' || last.result === 'timeout') && translate({id: 'preset.paintByTokens.hint', message: 'Pick a token with the number keys, then fill every cell that asks for it.', description: 'Hint under the paint-by-tokens board'})}
+        </p>
+      </footer>
+    </section>
+  );
+}

package/src/components/PaintByTokens/PaintByTokens.module.css

@@ -0,0 +1,202 @@
+/**
+ * <PaintByTokens /> styles.
+ *
+ * The five tones are the five tokens, drawn from the theme rather than
+ * from a palette of their own: that is the point of the game, and it
+ * means a site that reskins the preset reskins the picture with it.
+ *
+ * Every cell also carries its token as a number, so the board is
+ * playable by someone who cannot tell the tones apart.
+ */
+
+.pbt {
+  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: 16px;
+}
+
+.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; }
+
+/* The five tokens. Nothing else in the file names a colour. */
+.tone0 { --pbt-tone: var(--c-cobalt-50); --pbt-ink: var(--c-cobalt-700); }
+.tone1 { --pbt-tone: var(--c-blue-cobalt); --pbt-ink: white; }
+.tone2 { --pbt-tone: var(--c-cobalt-900); --pbt-ink: white; }
+.tone3 { --pbt-tone: var(--c-cobalt-300); --pbt-ink: var(--c-cobalt-900); }
+.tone4 { --pbt-tone: var(--c-mint-500); --pbt-ink: var(--c-cobalt-900); }
+
+.palette {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.swatch {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 12px 7px 8px;
+  border: 1px solid var(--c-cobalt-200);
+  border-radius: var(--radius-pill);
+  background: white;
+  font-family: inherit;
+  font-size: 12px;
+  color: var(--c-cobalt-700);
+  cursor: pointer;
+  transition: border-color 120ms ease;
+}
+.swatch::before {
+  content: '';
+  width: 16px;
+  height: 16px;
+  border-radius: 4px;
+  background: var(--pbt-tone);
+  border: 1px solid var(--c-cobalt-200);
+}
+.swatch:hover:not(:disabled) { border-color: var(--c-blue-cobalt); }
+.swatch:disabled { opacity: 0.55; cursor: default; }
+.swatch:focus-visible { outline: 2px solid var(--c-blue-cobalt); outline-offset: 2px; }
+
+.swatchOn {
+  border-color: var(--c-blue-cobalt);
+  background: var(--c-cobalt-50);
+  font-weight: 600;
+  color: var(--c-cobalt-900);
+}
+
+.swatchKey {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 10px;
+  color: var(--c-cobalt-400);
+}
+
+.swatchName { white-space: nowrap; }
+
+.grid {
+  display: grid;
+  gap: 3px;
+  max-width: 460px;
+  padding: 10px;
+  border-radius: var(--radius-md);
+  background: var(--c-cobalt-50);
+  min-height: 120px;
+}
+
+.cell {
+  aspect-ratio: 1;
+  border: 1px solid var(--c-cobalt-200);
+  border-radius: var(--radius-sm);
+  background: white;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 10px;
+  color: var(--c-cobalt-400);
+  cursor: pointer;
+  padding: 0;
+  transition: background 120ms ease, border-color 120ms ease;
+}
+.cell:hover:not(:disabled) { border-color: var(--c-blue-cobalt); }
+.cell:disabled { cursor: default; }
+.cell:focus-visible { outline: 2px solid var(--c-blue-cobalt); outline-offset: 1px; }
+
+.cellPainted {
+  background: var(--pbt-tone);
+  border-color: var(--pbt-tone);
+  color: var(--pbt-ink);
+}
+
+.idle {
+  grid-column: 1 / -1;
+  margin: auto;
+  font-size: 14px;
+  color: var(--c-cobalt-400);
+  text-align: center;
+}
+
+.foot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-top: 14px;
+}
+
+.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) {
+  .cellPainted { animation: pbtFill 140ms ease-out; }
+  @keyframes pbtFill {
+    from { transform: scale(0.8); }
+    to   { transform: scale(1); }
+  }
+}