@conduction/docusaurus-preset 3.41.1 → 3.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.41.1",
+  "version": "3.42.0",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js",
     "test": "node --test"

package/src/components/DetailHero/DetailHero.jsx

@@ -323,9 +323,15 @@ export default function DetailHero({
           {title && (
             <h1 className={styles.title}>
               {resolvedIcon && (
+                /* The glyph doubles as a hiding place. <HiddenGame>
+                   attaches its click and hold unlocks to whatever
+                   carries this marker, so a page can hide a game
+                   behind its own logo without the hero knowing which
+                   game, or that there is one. */
                 <span
                   className={styles.titleIcon}
                   style={{background: resolvedIconColor}}
+                  data-hidden-target="app-glyph"
                   aria-hidden="true"
                 >
                   {resolvedIcon}

package/src/components/HiddenGame/HiddenGame.jsx

@@ -0,0 +1,190 @@
+/**
+ * <HiddenGame />
+ *
+ * Wraps a mini-game and keeps it off the page until somebody finds it.
+ * Every game on the site is hidden behind a different way in, because
+ * the hunt is the game around the games: one wants three clicks on the
+ * app's logo, another the Konami code, another a word typed on the
+ * page, another a paragraph selected as if you were about to redact
+ * it.
+ *
+ * The matching lives in ./matchers.js, with no DOM and no clock, so
+ * "does this open it" and "does this open by accident" are tested
+ * rather than tried.
+ *
+ * Usage:
+ *
+ *   <HiddenGame id="stamp-rush" unlock={{kind: 'clicks', target: 'app-glyph'}}>
+ *     <StampRush />
+ *   </HiddenGame>
+ *
+ * Unlock kinds:
+ *   clicks    {target, count = 3, windowMs}  clicks on an element carrying
+ *                                            data-hidden-target="<target>"
+ *   hold      {target, holdMs}               press and hold that element
+ *   type      {word}                         type a word anywhere on the page
+ *   konami    {}                             the Konami code
+ *   select    {minLength, settleMs}          select a run of text and pause
+ *   link      {}                             renders its own quiet opener
+ *
+ * Every kind also answers to `#play-<id>` in the URL, which is how a
+ * page links straight to its own game (the arcade page does) and how
+ * the e2e suite gets in without re-testing the matchers through a
+ * browser.
+ *
+ * Once found, a game stays found for that browser: reopening the page
+ * shows it straight away, because hiding it again would punish the
+ * person who solved it.
+ */
+
+import React, {useCallback, useEffect, useRef, useState} from 'react';
+import {translate} from '@docusaurus/Translate';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {
+  createSequenceMatcher, createWordMatcher, createClickCounter,
+  createHoldTimer, createSelectionWatcher, KONAMI,
+} from './matchers';
+import styles from './HiddenGame.module.css';
+
+const FOUND_KEY = 'conduction:minigames-found';
+
+function readFound(id) {
+  if (typeof window === 'undefined') return false;
+  try {
+    const raw = window.localStorage.getItem(FOUND_KEY);
+    return Boolean(raw && JSON.parse(raw)[id]);
+  } catch (e) { return false; }
+}
+
+function writeFound(id) {
+  if (typeof window === 'undefined') return;
+  try {
+    const raw = window.localStorage.getItem(FOUND_KEY);
+    const found = raw ? JSON.parse(raw) : {};
+    found[id] = true;
+    window.localStorage.setItem(FOUND_KEY, JSON.stringify(found));
+  } catch (e) {/* fail open: the game still opened, it just won't be remembered */}
+}
+
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+export default function HiddenGame({id, unlock = {}, children, className}) {
+  const isBrowser = useIsBrowser();
+  const [open, setOpen] = useState(false);
+  const holder = useRef(null);
+  const openedRef = useRef(false);
+
+  const reveal = useCallback(() => {
+    if (openedRef.current) return;
+    openedRef.current = true;
+    setOpen(true);
+    writeFound(id);
+    /* Bring it into view: a game that opens below the fold looks like
+       nothing happened, and the player goes back to poking the logo. */
+    window.requestAnimationFrame(() => {
+      if (holder.current) holder.current.scrollIntoView({behavior: 'smooth', block: 'center'});
+    });
+  }, [id]);
+
+  /* Already found here before, or linked to directly. */
+  useEffect(() => {
+    if (!isBrowser) return;
+    if (readFound(id) || window.location.hash === `#play-${id}`) {
+      openedRef.current = true;
+      setOpen(true);
+    }
+  }, [isBrowser, id]);
+
+  /* Typed words and the Konami code both listen on the document. */
+  useEffect(() => {
+    if (!isBrowser || open) return undefined;
+    if (unlock.kind !== 'type' && unlock.kind !== 'konami') return undefined;
+
+    const matcher = unlock.kind === 'konami'
+      ? createSequenceMatcher(KONAMI)
+      : createWordMatcher(unlock.word || '');
+
+    const onKey = (e) => {
+      /* Never steal from a field somebody is typing in. */
+      const el = e.target;
+      if (el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable)) return;
+      if (matcher.push(e.key)) reveal();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [isBrowser, open, unlock.kind, unlock.word, reveal]);
+
+  /* Clicks and holds attach to whatever carries the target marker. */
+  useEffect(() => {
+    if (!isBrowser || open) return undefined;
+    if (unlock.kind !== 'clicks' && unlock.kind !== 'hold') return undefined;
+
+    const target = document.querySelector(`[data-hidden-target="${unlock.target}"]`);
+    if (!target) return undefined;
+
+    if (unlock.kind === 'clicks') {
+      const counter = createClickCounter({count: unlock.count || 3, windowMs: unlock.windowMs || 1500});
+      const onClick = () => { if (counter.push(now())) reveal(); };
+      target.addEventListener('click', onClick);
+      return () => target.removeEventListener('click', onClick);
+    }
+
+    const timer = createHoldTimer({holdMs: unlock.holdMs || 1200});
+    let poll = null;
+    const start = () => {
+      timer.start(now());
+      poll = setInterval(() => { if (timer.check(now())) { clearInterval(poll); reveal(); } }, 100);
+    };
+    const stop = () => { timer.cancel(); if (poll) clearInterval(poll); };
+    target.addEventListener('pointerdown', start);
+    target.addEventListener('pointerup', stop);
+    target.addEventListener('pointerleave', stop);
+    return () => {
+      stop();
+      target.removeEventListener('pointerdown', start);
+      target.removeEventListener('pointerup', stop);
+      target.removeEventListener('pointerleave', stop);
+    };
+  }, [isBrowser, open, unlock.kind, unlock.target, unlock.count, unlock.windowMs, unlock.holdMs, reveal]);
+
+  /* Selecting text, for the game about selecting text. */
+  useEffect(() => {
+    if (!isBrowser || open || unlock.kind !== 'select') return undefined;
+
+    const watcher = createSelectionWatcher({
+      minLength: unlock.minLength || 12,
+      settleMs: unlock.settleMs || 900,
+    });
+    const tick = setInterval(() => {
+      const text = window.getSelection ? String(window.getSelection()) : '';
+      if (watcher.push(text, now())) reveal();
+    }, 200);
+    return () => clearInterval(tick);
+  }, [isBrowser, open, unlock.kind, unlock.minLength, unlock.settleMs, reveal]);
+
+  if (!isBrowser) return null;
+
+  if (!open) {
+    /* The `link` kind is the one hiding place that shows itself, for a
+       page with nothing else to poke at. Everything else renders
+       nothing at all: an empty wrapper is the point. */
+    if (unlock.kind !== 'link') return null;
+    return (
+      <p className={[styles.opener, className].filter(Boolean).join(' ')}>
+        <button type="button" className={styles.openerButton} onClick={reveal}>
+          {unlock.label || translate({
+            id: 'preset.hiddenGame.opener',
+            message: 'Take a break',
+            description: 'Quiet link that opens a hidden mini-game on a page',
+          })}
+        </button>
+      </p>
+    );
+  }
+
+  return (
+    <div className={[styles.found, className].filter(Boolean).join(' ')} ref={holder}>
+      {children}
+    </div>
+  );
+}

package/src/components/HiddenGame/HiddenGame.module.css

@@ -0,0 +1,42 @@
+/**
+ * <HiddenGame /> styles.
+ *
+ * Almost nothing, on purpose: a hidden game renders nothing until it
+ * is found, and once found it is the game's own styles that matter.
+ * Only two things live here, the quiet opener for the `link` kind and
+ * the arrival of the game itself.
+ */
+
+.opener {
+  margin: 0;
+  text-align: center;
+}
+
+/* Deliberately understated. It is meant to be found by someone
+   reading the page, not to advertise itself from across the screen. */
+.openerButton {
+  border: 0;
+  background: none;
+  padding: 4px 6px;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--c-cobalt-300);
+  cursor: pointer;
+  transition: color 140ms ease;
+}
+.openerButton:hover { color: var(--c-blue-cobalt); }
+.openerButton:focus-visible {
+  outline: 2px solid var(--c-blue-cobalt);
+  outline-offset: 2px;
+  color: var(--c-blue-cobalt);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .found { animation: hgArrive 260ms ease-out both; }
+  @keyframes hgArrive {
+    from { opacity: 0; transform: translateY(8px); }
+    to   { opacity: 1; transform: none; }
+  }
+}

package/src/components/HiddenGame/__tests__/matchers.test.js

@@ -0,0 +1,117 @@
+/**
+ * matchers.test.js — how a hidden game gets found.
+ *
+ * These are the only thing standing between a game nobody can reach
+ * and a game that opens by accident, so both halves are pinned: the
+ * intended input opens it, and the near misses do not.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  createSequenceMatcher, createWordMatcher, createClickCounter,
+  createHoldTimer, createSelectionWatcher, KONAMI,
+} = require('../matchers.js');
+
+/** Feed a list of keys, returning how many times it fired. */
+function feed(matcher, keys) {
+  return keys.reduce((hits, k) => hits + (matcher.push(k) ? 1 : 0), 0);
+}
+
+test('the Konami code opens it, once', () => {
+  const m = createSequenceMatcher(KONAMI);
+  assert.equal(feed(m, KONAMI), 1);
+  assert.equal(m.progress, 0, 'the sequence did not reset after firing');
+});
+
+test('a wrong key resets the sequence, but a repeat of the first key restarts it', () => {
+  const m = createSequenceMatcher(['ArrowUp', 'ArrowDown', 'b']);
+  assert.equal(feed(m, ['ArrowUp', 'x', 'ArrowDown', 'b']), 0, 'a wrong key did not break the run');
+
+  /* "up up down b" has to work: the second up is a fresh start, not a
+     failure, or nobody ever lands a sequence that repeats a key. */
+  m.reset();
+  assert.equal(feed(m, ['ArrowUp', 'ArrowUp', 'ArrowDown', 'b']), 1);
+});
+
+test('the sequence ignores case, the way the Konami b and a are typed', () => {
+  const m = createSequenceMatcher(KONAMI);
+  const shouted = KONAMI.map((k) => (k.length === 1 ? k.toUpperCase() : k));
+  assert.equal(feed(m, shouted), 1);
+});
+
+test('a typed word opens it, even when the typing was messy before it', () => {
+  const m = createWordMatcher('build');
+  assert.equal(feed(m, 'buil'.split('')), 0);
+  assert.equal(feed(m, 'd'.split('')), 1);
+
+  m.reset();
+  assert.equal(feed(m, 'bbuild'.split('')), 1, 'a stutter before the word broke it');
+  m.reset();
+  assert.equal(feed(m, 'xxbuild'.split('')), 1, 'typing near it first broke it');
+});
+
+test('a typed word ignores keys that are not characters', () => {
+  const m = createWordMatcher('d20');
+  assert.equal(feed(m, ['d', 'Shift', '2', 'ArrowLeft', '0']), 1);
+});
+
+test('a word that is only half typed stays shut', () => {
+  const m = createWordMatcher('hunter2');
+  assert.equal(feed(m, 'hunter'.split('')), 0);
+  assert.equal(m.buffer, 'hunter');
+});
+
+test('three clicks in a row open it; three clicks spread out do not', () => {
+  const quick = createClickCounter({count: 3, windowMs: 1500});
+  assert.equal(quick.push(0), false);
+  assert.equal(quick.push(300), false);
+  assert.equal(quick.push(600), true);
+
+  const slow = createClickCounter({count: 3, windowMs: 1500});
+  assert.equal(slow.push(0), false);
+  assert.equal(slow.push(5000), false);
+  assert.equal(slow.push(10000), false, 'clicks a whole visit apart were counted together');
+});
+
+test('the click window slides rather than resetting, so a fourth click still lands', () => {
+  const c = createClickCounter({count: 3, windowMs: 1000});
+  assert.equal(c.push(0), false);
+  assert.equal(c.push(1800), false, 'the first click should have aged out');
+  assert.equal(c.push(2000), false);
+  assert.equal(c.push(2400), true);
+});
+
+test('a hold has to last, and a cancelled hold counts for nothing', () => {
+  const h = createHoldTimer({holdMs: 1200});
+  h.start(0);
+  assert.equal(h.check(900), false);
+  assert.equal(h.check(1300), true);
+
+  h.start(2000);
+  h.cancel();
+  assert.equal(h.check(9000), false, 'a hold that left the element still opened it');
+  assert.equal(h.holding, false);
+});
+
+test('a selection has to settle before it counts', () => {
+  const s = createSelectionWatcher({minLength: 10, settleMs: 900});
+  assert.equal(s.push('a permit application', 0), false, 'fired on the first frame of a drag');
+  assert.equal(s.push('a permit application', 500), false);
+  assert.equal(s.push('a permit application', 1000), true);
+});
+
+test('a growing selection keeps restarting the clock, and a short one never starts it', () => {
+  const s = createSelectionWatcher({minLength: 10, settleMs: 900});
+  s.push('a permit app', 0);
+  s.push('a permit application', 800);
+  assert.equal(s.push('a permit application', 1200), false, 'the clock did not restart when the drag grew');
+  assert.equal(s.push('a permit application', 1800), true);
+
+  s.reset();
+  assert.equal(s.push('short', 0), false);
+  assert.equal(s.push('short', 5000), false, 'a tiny selection opened it');
+});

package/src/components/HiddenGame/matchers.js

@@ -0,0 +1,168 @@
+/**
+ * Unlock matchers — how a hidden game gets found.
+ *
+ * Every mini-game on a Conduction page is hidden, and every one is
+ * hidden differently: finding them is the game around the games. These
+ * are the little state machines behind that, kept pure so each one can
+ * be tested without a page, a keyboard or a clock of its own.
+ *
+ * Each matcher takes events and answers the same question: has this
+ * been done yet? They never touch the DOM; the component feeds them.
+ */
+
+/**
+ * A fixed key sequence, the Konami shape.
+ *
+ * Partial progress survives a wrong key only when that key could start
+ * the sequence again, which is what makes "up up down…" forgiving
+ * enough to actually land: the second `up` is not a reset, it is a
+ * fresh first step.
+ */
+export function createSequenceMatcher(sequence) {
+  const wanted = sequence.map((k) => String(k).toLowerCase());
+  let index = 0;
+
+  return {
+    get progress() { return index; },
+    get length() { return wanted.length; },
+    reset() { index = 0; },
+    push(key) {
+      const k = String(key || '').toLowerCase();
+      if (k === wanted[index]) {
+        index += 1;
+      } else if (k === wanted[0]) {
+        index = 1;
+      } else {
+        index = 0;
+      }
+      if (index === wanted.length) {
+        index = 0;
+        return true;
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * A word typed anywhere on the page.
+ *
+ * Keeps a rolling buffer the length of the word rather than resetting
+ * on every mistake, so typing "hunthunter2" still opens it. Anything
+ * that is not a single printable character is ignored, so shift,
+ * arrows and tabbing about are harmless.
+ */
+export function createWordMatcher(word) {
+  const wanted = String(word).toLowerCase();
+  let buffer = '';
+
+  return {
+    get buffer() { return buffer; },
+    reset() { buffer = ''; },
+    push(key) {
+      const k = String(key || '');
+      if (k.length !== 1) return false;
+      buffer = (buffer + k.toLowerCase()).slice(-wanted.length);
+      if (buffer === wanted) {
+        buffer = '';
+        return true;
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * N clicks on one thing, inside a window.
+ *
+ * The window is what keeps an accidental unlock from being assembled
+ * over a whole visit: three clicks a minute apart are three people
+ * reading, not somebody poking at the logo.
+ */
+export function createClickCounter({count = 3, windowMs = 1500} = {}) {
+  let times = [];
+
+  return {
+    get progress() { return times.length; },
+    reset() { times = []; },
+    push(now) {
+      const t = Number(now) || 0;
+      times = times.filter((prev) => t - prev <= windowMs);
+      times.push(t);
+      if (times.length >= count) {
+        times = [];
+        return true;
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * Something held down, or hovered, for long enough.
+ *
+ * Start and end are separate calls because a press that leaves the
+ * element never ends: the component cancels it instead, and a
+ * cancelled hold must not count.
+ */
+export function createHoldTimer({holdMs = 1200} = {}) {
+  let startedAt = null;
+
+  return {
+    get holding() { return startedAt !== null; },
+    start(now) { startedAt = Number(now) || 0; },
+    cancel() { startedAt = null; },
+    check(now) {
+      if (startedAt === null) return false;
+      if ((Number(now) || 0) - startedAt >= holdMs) {
+        startedAt = null;
+        return true;
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * A run of text selected on the page, held for a moment.
+ *
+ * The moment matters: a selection appears halfway through every drag,
+ * so unlocking on the first one would fire while somebody is still
+ * choosing what to copy.
+ */
+export function createSelectionWatcher({minLength = 12, settleMs = 900} = {}) {
+  let since = null;
+  let last = '';
+
+  return {
+    reset() { since = null; last = ''; },
+    /** Feed the current selection text and the time; returns true once. */
+    push(text, now) {
+      const value = String(text || '').trim();
+      const t = Number(now) || 0;
+      if (value.length < minLength) {
+        since = null;
+        last = '';
+        return false;
+      }
+      if (value !== last) {
+        last = value;
+        since = t;
+        return false;
+      }
+      if (since !== null && t - since >= settleMs) {
+        since = null;
+        last = '';
+        return true;
+      }
+      return false;
+    },
+  };
+}
+
+/** The Konami code, spelled the way KeyboardEvent.key spells it. */
+export const KONAMI = [
+  'ArrowUp', 'ArrowUp', 'ArrowDown', 'ArrowDown',
+  'ArrowLeft', 'ArrowRight', 'ArrowLeft', 'ArrowRight',
+  'b', 'a',
+];

package/src/components/index.js

@@ -64,6 +64,7 @@ export {default as StampRush} from './StampRush/StampRush.jsx';
 export {default as DeadlineDefender} from './DeadlineDefender/DeadlineDefender.jsx';
 export {default as BlueprintRush} from './BlueprintRush/BlueprintRush.jsx';
 export {default as RecordRun} from './RecordRun/RecordRun.jsx';
+export {default as HiddenGame} from './HiddenGame/HiddenGame.jsx';
 export {default as LockPick} from './LockPick/LockPick.jsx';
 export {default as PaintByTokens} from './PaintByTokens/PaintByTokens.jsx';
 export {default as Redaction} from './Redaction/Redaction.jsx';