@conduction/docusaurus-preset 3.38.0 → 3.39.0

package/src/components/FeaturedCard/__tests__/FeaturedCard.visual.test.js

@@ -0,0 +1,110 @@
+/**
+ * FeaturedCard.visual.test.js — the `visual` prop puts a node in the
+ * card's right-hand column instead of the hex thumbnail.
+ *
+ * The regression half matters more than the feature half: every
+ * academy card and every featured post renders through this
+ * component, so a card that passes no `visual` has to render exactly
+ * what it rendered before, satellites and all.
+ *
+ * Same esbuild-bundle-then-renderToStaticMarkup technique as the
+ * other render tests; CSS modules are stubbed with an identity proxy.
+ */
+
+'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, '..', 'FeaturedCard.jsx');
+const PRESET_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+const SCRATCH = path.join(PRESET_ROOT, '.tmp-featured-card-test');
+
+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',
+    }));
+  },
+};
+
+const docusaurusStub = {
+  name: 'docusaurus-stub',
+  setup(b) {
+    b.onResolve({filter: /^@docusaurus\/Translate$/}, () => ({path: 'docusaurus-translate', namespace: 'docusaurus-stub'}));
+    b.onLoad({filter: /^docusaurus-translate$/, namespace: 'docusaurus-stub'}, () => ({
+      contents: `import React from 'react';
+        export function translate(o, v) {
+          return String(o.message).replace(/\\{(\\w+)\\}/g, (_, k) => (v && v[k] !== undefined ? v[k] : ''));
+        }
+        export default function Translate({children}) { return React.createElement(React.Fragment, null, children); }`,
+      loader: 'jsx',
+    }));
+  },
+};
+
+let FeaturedCard;
+
+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, docusaurusStub],
+    logLevel: 'warning',
+  });
+  delete require.cache[require.resolve(outFile)];
+  FeaturedCard = require(outFile).default;
+});
+
+after(async () => {
+  await fs.rm(SCRATCH, {recursive: true, force: true});
+});
+
+const BASE = {title: 'La Frankendesk', lede: 'One finish, mixed parts.', href: '/academy/x'};
+
+function render(props) {
+  return renderToStaticMarkup(React.createElement(FeaturedCard, {...BASE, ...props}));
+}
+
+const marker = React.createElement('div', {'data-visual': 'seam'}, 'scene');
+
+test('without a visual the card renders the hex thumbnail and its satellites, as before', () => {
+  const html = render({thumbnail: {icon: React.createElement('svg', null), tone: 'cobalt'}});
+  assert.match(html, /thumb/, 'no hex thumbnail rendered');
+  assert.equal((html.match(/satellite/g) || []).length > 0, true, 'satellites missing');
+  assert.doesNotMatch(html, /visualNode/);
+});
+
+test('a visual takes the column and stands the satellites down', () => {
+  const html = render({visual: marker});
+  assert.match(html, /data-visual="seam"/, 'the passed node did not render');
+  assert.match(html, /visualNode/);
+  assert.doesNotMatch(html, /satellite/, 'satellites still frame a node that is not a hex');
+  assert.doesNotMatch(html, /thumb/, 'the hex thumbnail rendered alongside the visual');
+});
+
+test('the copy column is untouched by the visual', () => {
+  const html = render({visual: marker, eyebrow: 'blog', durationMinutes: 20});
+  assert.match(html, /La Frankendesk/);
+  assert.match(html, /One finish, mixed parts\./);
+  assert.match(html, /20 min read/);
+});

package/src/components/GameModal/GameModal.jsx

@@ -42,60 +42,66 @@
 
 import React, {useEffect, useState, useCallback, useMemo} from 'react';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Translate, {translate} from '@docusaurus/Translate';
+import {
+  readScores, writeScores, recordResult, bestFor, foundCount as countFound,
+  totalScore, formatScore,
+} from './scores';
+import {buildShareText, scoreLines, mastodonShareUrl, linkedInShareUrl, normaliseInstance} from './share';
 import styles from './GameModal.module.css';
 
-const STORAGE_KEY = 'conduction:minigames';
-
-const DEFAULT_GAMES = [
-  {id: 'hexrain',      label: 'Twelve apps · hex rain'},
-  {id: 'boats',        label: 'Sink the boats · footer canal'},
-  {id: 'invaders',     label: 'Hex-vaders · cookie CLI'},
-  {id: 'logo-memory',  label: 'Logo memory · clients marquee'},
-  {id: 'kade-cyclist', label: 'Kade cyclist · footer kade'},
-];
-
-function readFound() {
-  if (typeof window === 'undefined') return {};
-  try {
-    const raw = window.localStorage.getItem(STORAGE_KEY);
-    return raw ? JSON.parse(raw) : {};
-  } catch (e) { return {}; }
-}
+/* The player's Mastodon instance, remembered so the second share does
+   not ask again. Per-viewer convenience only; nothing else reads it. */
+const INSTANCE_KEY = 'conduction:mastodon-instance';
 
-function writeFound(found) {
-  if (typeof window === 'undefined') return;
-  try {
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(found));
-  } catch (e) {/* fail open */}
+/* The labels are read by every player, so they are translated like any
+   other user-facing string. Each one is "the game · where it hides";
+   the share text keeps only the part before the separator. Built in a
+   function rather than at module scope, because translate() must run
+   inside the render for the active locale to apply. */
+function defaultGames() {
+  return [
+    {id: 'hexrain', label: translate({id: 'preset.gameModal.game.hexrain', message: 'Twelve apps · hex rain', description: 'Name of the hex-rain mini-game and where it hides'})},
+    {id: 'boats', label: translate({id: 'preset.gameModal.game.boats', message: 'Sink the boats · footer canal', description: 'Name of the boat-sinking mini-game and where it hides'})},
+    {id: 'invaders', label: translate({id: 'preset.gameModal.game.invaders', message: 'Hex-vaders · cookie CLI', description: 'Name of the invaders mini-game and where it hides'})},
+    {id: 'logo-memory', label: translate({id: 'preset.gameModal.game.logoMemory', message: 'Logo memory · clients marquee', description: 'Name of the logo-memory mini-game and where it hides'})},
+    {id: 'kade-cyclist', label: translate({id: 'preset.gameModal.game.kadeCyclist', message: 'Kade cyclist · footer kade', description: 'Name of the kade-cyclist mini-game and where it hides'})},
+  ];
 }
 
-export default function GameModal({games = DEFAULT_GAMES, className}) {
+export default function GameModal({games: gamesProp, share: shareConfig, className}) {
   const isBrowser = useIsBrowser();
+  const {siteConfig, i18n} = useDocusaurusContext();
   const [open, setOpen] = useState(false);
   const [event, setEvent] = useState(null);
-  const [found, setFound] = useState({});
+  const [scores, setScores] = useState(() => ({version: 2, games: {}}));
+  /* Share UI state: which network is mid-flow, the remembered Mastodon
+     instance, and the "copied" acknowledgement. */
+  const [instance, setInstance] = useState('');
+  const [askInstance, setAskInstance] = useState(false);
+  const [copied, setCopied] = useState(false);
 
-  /* On mount: read found-games table from localStorage and subscribe
-     to the `connext:gameend` event. Each event opens the modal with
-     the supplied copy and (if won) marks the game as found. */
+  /* On mount: read the score table from localStorage and subscribe to
+     the `connext:gameend` event. Each event opens the modal with the
+     supplied copy and folds the result into the table. */
   useEffect(() => {
     if (!isBrowser) return;
-    setFound(readFound());
+    setScores(readScores());
+    try {
+      setInstance(window.localStorage.getItem(INSTANCE_KEY) || '');
+    } catch (e) {/* blocked storage: the player types it again */}
 
     function onEnd(e) {
       const detail = e.detail || {};
       setEvent(detail);
       setOpen(true);
-      /* Discovery vs. victory: any game-end counts the game as "found"
-         because a few of the games (kade-cyclist, future endless
-         runners) never reach a clean win state. The scoreboard pill
-         still reflects the actual performance for that round. */
+      setCopied(false);
+      setAskInstance(false);
       if (detail.id) {
-        setFound((prev) => {
-          if (prev[detail.id]) return prev;
-          const next = {...prev, [detail.id]: true};
-          writeFound(next);
+        setScores((prev) => {
+          const next = recordResult(prev, detail);
+          writeScores(next);
           return next;
         });
       }
@@ -137,9 +143,88 @@ export default function GameModal({games = DEFAULT_GAMES, className}) {
     setOpen(false);
   }, [event]);
 
-  const foundCount = useMemo(() => Object.values(found).filter(Boolean).length, [found]);
+  const locale = (i18n && i18n.currentLocale) || 'en';
+
+  /* Copy that reaches this component from a site's themeConfig can be
+     either a string or a per-locale map, because Docusaurus does not
+     translate themeConfig at all. A string is used as-is. */
+  const pickLocale = useCallback((value) => {
+    if (!value || typeof value === 'string') return value;
+    return value[locale] || value.en || Object.values(value)[0];
+  }, [locale]);
+
+  /* The roster: which games this site actually ships. The preset's own
+     five are the default, and a site that hides more of them passes
+     its own list (with per-locale labels, same reason as above). A
+     roster that named a game the site does not ship would leave every
+     player permanently short of "all found". */
+  const games = useMemo(
+    () => (gamesProp || defaultGames()).map((g) => ({...g, label: pickLocale(g.label)})),
+    [gamesProp, pickLocale],
+  );
+  const rosterIds = useMemo(() => games.map((g) => g.id), [games]);
+  const foundCount = useMemo(() => countFound(scores, rosterIds), [scores, rosterIds]);
   const total = games.length;
   const percent = total > 0 ? Math.round((foundCount / total) * 100) : 0;
+  const grandTotal = useMemo(() => totalScore(scores, rosterIds), [scores, rosterIds]);
+  const lines = useMemo(
+    () => scoreLines(games, (id) => bestFor(scores, id), locale),
+    [games, scores, locale],
+  );
+
+  /* The post the player publishes. Built here so the copy button, the
+     Mastodon link and the LinkedIn link cannot drift apart. */
+  const shareText = useMemo(() => buildShareText({
+    total: grandTotal,
+    lines,
+    foundCount,
+    totalGames: total,
+    hashtag: (shareConfig && shareConfig.hashtag) || '#IReadTheKit',
+    url: (shareConfig && shareConfig.url) || (siteConfig && siteConfig.url) || undefined,
+    locale,
+  }), [grandTotal, lines, foundCount, total, shareConfig, siteConfig, locale]);
+
+  const copyShareText = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(shareText);
+      setCopied(true);
+      return true;
+    } catch (e) {
+      /* No clipboard permission (or no clipboard): fall back to a
+         hidden textarea, which works everywhere that still supports
+         execCommand, and give up quietly if that fails too. */
+      try {
+        const ta = document.createElement('textarea');
+        ta.value = shareText;
+        ta.setAttribute('readonly', '');
+        ta.style.position = 'fixed';
+        ta.style.opacity = '0';
+        document.body.appendChild(ta);
+        ta.select();
+        const ok = document.execCommand('copy');
+        document.body.removeChild(ta);
+        setCopied(ok);
+        return ok;
+      } catch (e2) { return false; }
+    }
+  }, [shareText]);
+
+  const shareOnMastodon = useCallback((raw) => {
+    const url = mastodonShareUrl(raw, shareText);
+    if (!url) { setAskInstance(true); return; }
+    const host = normaliseInstance(raw);
+    setInstance(host);
+    setAskInstance(false);
+    try { window.localStorage.setItem(INSTANCE_KEY, host); } catch (e) {/* fine */}
+    window.open(url, '_blank', 'noopener,noreferrer');
+  }, [shareText]);
+
+  const shareOnLinkedIn = useCallback(async () => {
+    /* LinkedIn stopped honouring prefilled text reliably, so the post
+       goes to the clipboard first and the composer opens for a paste. */
+    await copyShareText();
+    window.open(linkedInShareUrl(shareText), '_blank', 'noopener,noreferrer');
+  }, [copyShareText, shareText]);
 
   if (!isBrowser || !open || !event) return null;
 
@@ -188,27 +273,147 @@ export default function GameModal({games = DEFAULT_GAMES, className}) {
         </div>
 
         <ul className={styles.grid}>
-          {games.map((g) => (
-            <li key={g.id} className={found[g.id] ? styles.gridItemFound : styles.gridItem}>
-              <span className={styles.gridHex} aria-hidden="true" />
-              <span>{g.label}</span>
-            </li>
-          ))}
+          {games.map((g) => {
+            const best = bestFor(scores, g.id);
+            const isFound = Boolean(scores.games[g.id] && scores.games[g.id].found);
+            return (
+              <li key={g.id} className={isFound ? styles.gridItemFound : styles.gridItem}>
+                <span className={styles.gridHex} aria-hidden="true" />
+                <span className={styles.gridLabel}>{g.label}</span>
+                {best !== null && (
+                  <span className={styles.gridScore}>{formatScore(best, locale)}</span>
+                )}
+              </li>
+            );
+          })}
         </ul>
 
+        {grandTotal > 0 && (
+          <p className={styles.total}>
+            <Translate
+              id="preset.gameModal.totalScore"
+              description="Total score line under the games list. {score} is the sum of the player's best score in every game."
+              values={{score: <strong>{formatScore(grandTotal, locale)}</strong>}}>
+              {'Total score {score}'}
+            </Translate>
+          </p>
+        )}
+
         <p className={styles.cta}>
+          {/* Two messages picked here rather than one ICU plural.
+              Docusaurus's translate() only substitutes {placeholder};
+              it does not expand plurals, so an ICU string renders to
+              the reader verbatim, braces and all, in every locale. */}
           {foundCount < total
-            ? translate(
+            ? (total - foundCount === 1
+                ? translate({
+                    id: 'preset.gameModal.cta.remaining.one',
+                    message: 'One more game hidden somewhere. Keep clicking.',
+                    description: 'CTA on the game-over modal when exactly one mini-game is still hidden.',
+                  })
+                : translate(
+                    {
+                      id: 'preset.gameModal.cta.remaining.other',
+                      message: '{remaining} more games hidden somewhere. Keep clicking.',
+                      description: 'CTA on the game-over modal when several mini-games are still hidden. {remaining} is how many.',
+                    },
+                    {remaining: total - foundCount},
+                  ))
+            : translate(
                 {
-                  id: 'preset.gameModal.cta.remaining',
-                  message: '{remaining, plural, one {# more game hidden somewhere. Keep clicking.} other {# more games hidden somewhere. Keep clicking.}}',
-                  description: 'CTA text on the game-over modal when at least one game is still hidden. {remaining} is the count of games still hidden.',
+                  id: 'preset.gameModal.cta.allFound',
+                  message: 'All {total} found. You read the kit.',
+                  description: 'CTA on the game-over modal when every mini-game has been discovered. {total} is how many games there are.',
                 },
-                {remaining: total - foundCount},
-              )
-            : translate({id: 'preset.gameModal.cta.allFound', message: 'All five found. You read the kit.', description: 'CTA text on the game-over modal when the player has discovered every mini-game.'})}
+                {total},
+              )}
         </p>
 
+        {/* Posting a score is the whole competition: there is no
+            leaderboard to submit to, so the share block is where a run
+            turns into something other people can see. */}
+        <div className={styles.share}>
+          <p className={styles.shareHead}>
+            <Translate id="preset.gameModal.share.head" description="Heading above the share buttons on the game-over modal">
+              Post your score
+            </Translate>
+          </p>
+          <p className={styles.shareHint}>
+            <Translate id="preset.gameModal.share.hint" description="Line under the share heading telling the player to attach a screenshot of the modal">
+              Add a screenshot of this card, so people can see the run behind the number.
+            </Translate>
+          </p>
+
+          <div className={styles.shareButtons}>
+            <button
+              type="button"
+              className={styles.shareBtn}
+              onClick={() => (instance ? shareOnMastodon(instance) : setAskInstance(true))}>
+              <Translate id="preset.gameModal.share.mastodon" description="Share-on-Mastodon button label">Mastodon</Translate>
+            </button>
+            <button type="button" className={styles.shareBtn} onClick={shareOnLinkedIn}>
+              <Translate id="preset.gameModal.share.linkedin" description="Share-on-LinkedIn button label">LinkedIn</Translate>
+            </button>
+            <button type="button" className={styles.shareBtn} onClick={copyShareText}>
+              <Translate id="preset.gameModal.share.copy" description="Copy-the-post-text button label">Copy the post</Translate>
+            </button>
+            <span className={styles.shareStatus} role="status" aria-live="polite">
+              {copied && (
+                <Translate id="preset.gameModal.share.copied" description="Confirmation shown after the post text is copied to the clipboard">
+                  Copied. Paste it with your screenshot.
+                </Translate>
+              )}
+            </span>
+          </div>
+
+          {askInstance && (
+            /* Mastodon has no central share endpoint, so the post can
+               only be opened on the player's own instance. Asked once,
+               then remembered. */
+            <form
+              className={styles.instanceRow}
+              onSubmit={(e) => { e.preventDefault(); shareOnMastodon(e.target.elements.instance.value); }}>
+              <label className={styles.instanceLabel} htmlFor="gm-instance">
+                <Translate id="preset.gameModal.share.instanceLabel" description="Label for the input asking which Mastodon instance the player is on">
+                  Your Mastodon instance
+                </Translate>
+              </label>
+              <input
+                id="gm-instance"
+                name="instance"
+                className={styles.instanceInput}
+                defaultValue={instance}
+                placeholder="mastodon.nl"
+                autoComplete="off"
+              />
+              <button type="submit" className={styles.shareBtn}>
+                <Translate id="preset.gameModal.share.instanceGo" description="Submit button next to the Mastodon instance input">Open</Translate>
+              </button>
+            </form>
+          )}
+
+          {shareConfig && pickLocale(shareConfig.prize) && (
+            /* The prize sentence stays text and only the rules link is
+               a link: a whole underlined paragraph reads as one long
+               link and hides where it goes. */
+            <p className={styles.prize}>
+              {pickLocale(shareConfig.prize)}
+              {shareConfig.prizeHref && (
+                <>
+                  {' '}
+                  <a href={shareConfig.prizeHref}>
+                    {pickLocale(shareConfig.prizeLinkLabel) || translate({
+                      id: 'preset.gameModal.share.rules',
+                      message: 'Read the rules',
+                      description: 'Link to the giveaway rules, shown after the prize line in the share block',
+                    })}
+                  </a>
+                </>
+              )}
+            </p>
+          )}
+        </div>
+
         <div className={styles.actions}>
           <button type="button" className={styles.btnSecondary} onClick={close}>
             <Translate id="preset.gameModal.action.close" description="Close button label on the game-over modal">Close</Translate>

package/src/components/GameModal/GameModal.module.css

@@ -142,6 +142,109 @@
 }
 .gridItemFound .gridHex { background: var(--c-mint-500); }
 
+/* Per-game best, right-aligned against the game's label. */
+.gridLabel { flex: 1; }
+.gridScore {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 12px;
+  color: var(--c-cobalt-700);
+  font-variant-numeric: tabular-nums;
+}
+
+.total {
+  margin: 12px 0 0;
+  font-size: 15px;
+  color: var(--c-cobalt-700);
+}
+.total strong {
+  color: var(--c-cobalt-900);
+  font-family: var(--conduction-typography-font-family-code);
+  font-variant-numeric: tabular-nums;
+}
+
+/* ======================================================================
+   Share block
+   ====================================================================== */
+
+.share {
+  margin: 20px 0 0;
+  padding: 16px;
+  background: var(--c-cobalt-50);
+  border-radius: var(--radius-md);
+}
+
+.shareHead {
+  margin: 0 0 4px;
+  font-weight: 600;
+  font-size: 14px;
+  color: var(--c-cobalt-900);
+}
+
+.shareHint {
+  margin: 0 0 12px;
+  font-size: 13px;
+  color: var(--c-cobalt-400);
+}
+
+.shareButtons {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+
+.shareBtn {
+  background: white;
+  color: var(--c-cobalt-700);
+  border: 1px solid var(--c-cobalt-200);
+  padding: 8px 14px;
+  border-radius: var(--radius-pill);
+  font-weight: 500;
+  font-size: 13px;
+  cursor: pointer;
+  font-family: inherit;
+  transition: border-color 120ms ease, color 120ms ease;
+}
+.shareBtn:hover { border-color: var(--c-blue-cobalt); color: var(--c-blue-cobalt); }
+
+.shareStatus {
+  font-size: 12px;
+  color: var(--c-mint-500);
+  min-height: 1em;
+}
+
+.instanceRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-top: 12px;
+}
+.instanceLabel { font-size: 12px; color: var(--c-cobalt-700); }
+.instanceInput {
+  flex: 1;
+  min-width: 160px;
+  padding: 7px 10px;
+  border: 1px solid var(--c-cobalt-200);
+  border-radius: var(--radius-md);
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 13px;
+  color: var(--c-cobalt-900);
+  background: white;
+}
+.instanceInput:focus {
+  outline: 2px solid var(--c-blue-cobalt);
+  outline-offset: 1px;
+  border-color: var(--c-blue-cobalt);
+}
+
+.prize {
+  margin: 12px 0 0;
+  font-size: 13px;
+  color: var(--c-cobalt-700);
+}
+.prize a { color: var(--c-blue-cobalt); }
+
 .cta {
   font-size: 13px;
   color: var(--c-cobalt-400);