@conduction/docusaurus-preset 3.37.0 → 3.39.0

package/MISSING_COMPONENTS.md

@@ -65,6 +65,7 @@ Most consume one or more primitives.
 - **BuildMock** — `BuildMock/BuildMock.jsx`. Looping "make it yours" animation: the orange Buildiq edit FAB is pressed, a component palette opens, and a widget is dragged into the page layout where it snaps in (~8s loop). `prefers-reduced-motion` / `running={false}` renders the static end state (component placed).
 - **KanbanMock** — `KanbanMock/KanbanMock.jsx`. Looping kanban drag for the pipelinq hero: a cursor lifts the top lead card, drags it to the next column, drops it flush into the column's card slot, and at the drop the column counts nudge (3→2, 2→3) and the per-lane € KPI tiles above the board shift the moved deal's value (~7s loop, clean reset). `prefers-reduced-motion` / `running={false}` renders the static board with the initial counts and totals.
 - **MockScene** — `MockScene/MockScene.jsx`. Free-form positioning stage for overlap shots of WidgetMocks + SidebarMocks (caller supplies canvas size and per-item x/y/z). The scene assembles on a loop: items land on a 220ms stagger, transform-only so the inline left/top positioning is never fought; `running={false}` / `prefers-reduced-motion` show the assembled scene.
+- **ThemeSeamMock** — `ThemeSeamMock/ThemeSeamMock.jsx`. One AppMock frame rendered twice, the second inside a wrapper that redefines the palette and radius tokens. A stitched seam travels across the frame and the finish changes behind it (`--ts-dur`, 9s), then the loop hands the frame back. The themed layer is nothing but tokens, which is the claim Thematiq makes about a token set; the inner mocks run `running={false}` so their own loops do not compete with the seam. Themes: `lasuite`. `running={false}` / `prefers-reduced-motion` render the themed end state with the seam at rest.
 - **ExternalAppShelf** — `ExternalAppShelf/ExternalAppShelf.jsx`. Third-party-app shelf (Outlook-style, Mattermost, Keycloak, etc.) used on `/connext`. Specimen: `preview/components/external-app-shelf.html`.
 - **WidgetShelf** — `WidgetShelf/WidgetShelf.jsx`. Widget showcase with eyebrow + title + lede. Default is a slow single-row carousel (seamless duplicated track, pause on hover/focus, static wrapping grid under `prefers-reduced-motion`); loop duration derives from the widget count (6s per card, min 30s; `speed` overrides), with pause/play + prev/next controls (cobalt ghost, hidden under reduced motion). Widgets without an explicit `panel` get a deterministic auto-generated mini panel (KPI tile / bar chart / list rows / donut, hashed from the title). `carousel={false}` renders the N-column grid. Specimen: `preview/components/widget-shelf.html`.
 - **Showcase** — `Showcase/Showcase.jsx`. Multi-item collapsible showcase with screenshot + body. Used on `/commonground` for the "5-lagen model". Specimen: `preview/components/showcase.html`.

package/package.json

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

package/src/__tests__/no-icu-messages.test.js

@@ -0,0 +1,57 @@
+/**
+ * no-icu-messages.test.js — no translatable string may use ICU plural
+ * or select syntax.
+ *
+ * Docusaurus's `translate()` and `<Translate>` substitute
+ * `{placeholder}` and nothing else. An ICU message therefore does not
+ * fail, does not warn, and does not fall back: it renders to the
+ * reader verbatim, braces and keywords and all, in every locale. It
+ * shipped that way in the game-over modal and was reported from the
+ * live site.
+ *
+ * The fix is two messages chosen in JS. This test is the reason nobody
+ * has to remember that.
+ */
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const SRC = path.resolve(__dirname, '..');
+/* `{name, plural, ...}` / `{count, select, ...}`, the two ICU forms
+   that render raw. Deliberately loose: any argument name, any spacing. */
+const ICU = /\{\s*\w+\s*,\s*(plural|select|selectordinal)\s*,/;
+
+function sourceFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      out.push(...sourceFiles(full));
+    } else if (/\.(jsx?|tsx?)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+test('no component ships an ICU plural or select message', () => {
+  const offenders = [];
+  for (const file of sourceFiles(SRC)) {
+    const lines = fs.readFileSync(file, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      /* Skip the comment that explains the rule. */
+      if (/^\s*(\*|\/\/|\/\*)/.test(line)) return;
+      if (ICU.test(line)) offenders.push(`${path.relative(SRC, file)}:${i + 1}: ${line.trim()}`);
+    });
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    'ICU syntax renders verbatim to the reader; use two messages picked in JS:\n' + offenders.join('\n'),
+  );
+});

package/src/components/AiDisclosure/AiDisclosure.jsx

@@ -32,28 +32,39 @@
  */
 
 import React from 'react';
-import {useColorMode} from '@docusaurus/theme-common';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import styles from './AiDisclosure.module.css';
-import {isValidKind, getCopy, getViewBox, getIconPath, AI_KINDS} from './disclosure';
+import {isValidKind, getCopy, getLinkText, resolveLinkHref, LINK_HREF, AI_KINDS} from './disclosure';
+
+// The Commission's own AI letterforms, lifted verbatim from the
+// vendored Basic mark (static/img/ai-disclosure/ai-black.svg, paths 2
+// and 3) so the glyph a reader recognises is unchanged. What is
+// replaced is only the container: the Commission's black disc becomes
+// Conduction's hexagon in neutral grey, matching the hex used for app
+// glyphs across the design system.
+//
+// Both live in the mark's original 566.93 viewBox, so the letterforms
+// keep their exact position and proportion inside the new container.
+// The hexagon is regular, centred on the disc's own centre
+// (272.03, 283.46) with a circumradius of 200 - larger than the disc's
+// 182.74 because a hexagon's inradius is only 0.866 of its
+// circumradius, and the letters need the vertical room.
+const HEX_PATH =
+  'M472.03,283.46 L372.03,456.67 L172.03,456.67 L72.03,283.46 L172.03,110.25 L372.03,110.25 Z';
+const AI_LETTER_A =
+  'M170.79,353.74c-1.08,0-2.05-.43-2.92-1.31-.88-.87-1.31-1.84-1.31-2.92,0-.67.07-1.27.2-1.81l47.34-129.32c.4-1.48,1.24-2.79,2.52-3.93,1.27-1.14,3.05-1.71,5.34-1.71h29.81c2.28,0,4.06.57,5.34,1.71,1.27,1.14,2.11,2.45,2.52,3.93l47.14,129.32c.27.54.4,1.14.4,1.81,0,1.08-.44,2.05-1.31,2.92s-1.91,1.31-3.12,1.31h-24.78c-2.01,0-3.52-.5-4.53-1.51-1.01-1.01-1.65-1.91-1.91-2.72l-7.86-20.55h-53.78l-7.65,20.55c-.27.81-.88,1.71-1.81,2.72-.94,1.01-2.55,1.51-4.83,1.51h-24.78ZM218.13,299.96h37.47l-18.93-53.18-18.53,53.18Z';
+const AI_LETTER_I =
+  'M328.11,353.74c-1.48,0-2.69-.47-3.63-1.41-.94-.94-1.41-2.15-1.41-3.63v-130.93c0-1.48.47-2.68,1.41-3.63s2.15-1.41,3.63-1.41h26.99c1.48,0,2.68.47,3.63,1.41.94.94,1.41,2.15,1.41,3.63v130.93c0,1.48-.47,2.69-1.41,3.63-.94.94-2.15,1.41-3.63,1.41h-26.99Z';
 
 export default function AiDisclosure({kind, className}) {
-  const {colorMode} = useColorMode();
-  const {i18n} = useDocusaurusContext();
+  const {i18n, siteConfig} = useDocusaurusContext();
   const locale = (i18n && i18n.currentLocale) || 'en';
 
   const isKindValid = isValidKind(kind);
-  // Dark-ink mark on light surfaces, light-ink mark on dark surfaces -
-  // the opaque treatments (not the transparent ones) so the mark
-  // reads correctly regardless of what sits behind the banner panel.
-  const treatment = colorMode === 'dark' ? 'white' : 'black';
-  // Served as a plain static file (static/img/ai-disclosure/), not a
-  // webpack `.svg` import - see disclosure.js's ICONS_BASE_PATH
-  // comment for why. useBaseUrl() must run unconditionally (React
-  // hooks rule), so it's called even when kind is invalid; the result
-  // is simply unused in that branch.
-  const iconPath = useBaseUrl(getIconPath(isKindValid ? kind : 'assisted', treatment));
+  // useBaseUrl() must run unconditionally (React hooks rule), so it is
+  // called even when kind is invalid; the result is unused in that branch.
+  const href = resolveLinkHref(siteConfig && siteConfig.url, useBaseUrl(LINK_HREF));
 
   if (!isKindValid) {
     if (typeof console !== 'undefined') {
@@ -65,18 +76,31 @@ export default function AiDisclosure({kind, className}) {
     return null;
   }
 
-  const {width, height} = getViewBox(kind);
   const copy = getCopy(kind, locale);
+  const linkText = getLinkText(locale);
 
   return (
     <div className={[styles.disclosure, className].filter(Boolean).join(' ')} role="note">
-      <img
-        src={iconPath}
-        alt=""
+      {/* One mark for all three kinds and both colour modes: the kind is
+          stated in the copy, and grey-on-white reads the same as
+          grey-on-dark, so there is no treatment to switch. */}
+      <svg
         className={styles.mark}
-        style={{aspectRatio: `${width} / ${height}`}}
-      />
-      <p className={styles.copy}>{copy}</p>
+        viewBox="0 0 566.93 566.93"
+        role="img"
+        aria-label="AI"
+        focusable="false"
+        xmlns="http://www.w3.org/2000/svg">
+        <path className={styles.markHex} d={HEX_PATH} />
+        <path className={styles.markGlyph} fillRule="evenodd" d={AI_LETTER_A} />
+        <path className={styles.markGlyph} d={AI_LETTER_I} />
+      </svg>
+      <p className={styles.copy}>
+        {copy}{' '}
+        <a className={styles.link} href={href}>
+          {linkText}
+        </a>
+      </p>
     </div>
   );
 }

package/src/components/AiDisclosure/AiDisclosure.module.css

@@ -19,17 +19,52 @@
   border-radius: var(--radius-md);
 }
 
+/**
+ * The mark is a single square hexagon glyph now, not the three
+ * differently-proportioned Commission word-marks, so it gets a fixed
+ * square box rather than a per-kind aspect-ratio.
+ */
 .mark {
   display: block;
-  width: 96px;
-  max-width: 30%;
-  height: auto;
+  width: 40px;
+  height: 40px;
   flex-shrink: 0;
 }
 
+/**
+ * Neutral grey, and deliberately not brand orange: this is a factual
+ * disclosure, not a call to action. Grey reads correctly on both the
+ * light and the dark banner surface, which is why the mark needs no
+ * light/dark treatment switch at all.
+ */
+.markHex {
+  fill: var(--ai-mark-hex, #6b7280);
+}
+
+.markGlyph {
+  fill: var(--ai-mark-glyph, #ffffff);
+}
+
+[data-theme='dark'] .markHex {
+  fill: var(--ai-mark-hex-dark, #9ca3af);
+}
+
+[data-theme='dark'] .markGlyph {
+  fill: var(--ai-mark-glyph-dark, #1f2937);
+}
+
 .copy {
   margin: 0;
   font-size: 14px;
   line-height: 1.5;
   color: var(--c-cobalt-700);
 }
+
+.link {
+  color: inherit;
+  text-decoration: underline;
+}
+
+.link:hover {
+  text-decoration: none;
+}

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

@@ -11,9 +11,9 @@
  * `@docusaurus/useBaseUrl`) are stubbed via esbuild plugins since this
  * test runs outside an actual Docusaurus build; the useBaseUrl stub
  * prefixes a fake `/base/` the same way the real hook prefixes a
- * site's configured baseUrl, so the assertion is "the resolved icon
- * path for this kind/treatment was passed through base-url
- * resolution", not a snapshot of a real deployed URL.
+ * site's configured baseUrl, so the assertion is "the policy link was
+ * passed through base-url resolution", not a snapshot of a real
+ * deployed URL.
  *
  * @spec openspec/changes/ai-content-disclosure/tasks.md#task-5.2
  */
@@ -42,7 +42,7 @@ const cssModuleStub = {
   },
 };
 
-function docusaurusStub({colorMode, locale}) {
+function docusaurusStub({colorMode, locale, siteUrl}) {
   return {
     name: 'docusaurus-stub',
     setup(b) {
@@ -54,7 +54,7 @@ function docusaurusStub({colorMode, locale}) {
         loader: 'js',
       }));
       b.onLoad({filter: /^docusaurus-context$/, namespace: 'docusaurus-stub'}, () => ({
-        contents: `export default function useDocusaurusContext() { return {i18n: {currentLocale: ${JSON.stringify(locale)}}}; }`,
+        contents: `export default function useDocusaurusContext() { return {i18n: {currentLocale: ${JSON.stringify(locale)}}, siteConfig: {url: ${JSON.stringify(siteUrl)}}}; }`,
         loader: 'js',
       }));
       // Mirrors the real hook's job: prefix the site's baseUrl onto a
@@ -73,7 +73,7 @@ function docusaurusStub({colorMode, locale}) {
 // inside the package instead, mirroring build-kit.mjs's `.tmp-build-kit`.
 const PRESET_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
 
-async function renderAiDisclosure(props, {colorMode = 'light', locale = 'en'} = {}) {
+async function renderAiDisclosure(props, {colorMode = 'light', locale = 'en', siteUrl = 'https://conduction.nl'} = {}) {
   const scratchRoot = path.join(PRESET_ROOT, '.tmp-ai-disclosure-test');
   await fs.mkdir(scratchRoot, {recursive: true});
   const tmpDir = await fs.mkdtemp(path.join(scratchRoot, 'run-'));
@@ -89,7 +89,7 @@ async function renderAiDisclosure(props, {colorMode = 'light', locale = 'en'} =
       tsconfigRaw: {compilerOptions: {jsx: 'react-jsx', jsxImportSource: 'react'}},
       platform: 'node',
       external: ['react'],
-      plugins: [cssModuleStub, docusaurusStub({colorMode, locale})],
+      plugins: [cssModuleStub, docusaurusStub({colorMode, locale, siteUrl})],
       logLevel: 'warning',
     });
     delete require.cache[require.resolve(outFile)];
@@ -101,20 +101,32 @@ async function renderAiDisclosure(props, {colorMode = 'light', locale = 'en'} =
   }
 }
 
-test('renders the generated mark + English copy in light mode', async () => {
+test('renders the hexagon mark, English copy and the base-url policy link', async () => {
   const html = await renderAiDisclosure({kind: 'generated'}, {colorMode: 'light', locale: 'en'});
-  assert.match(html, /\/base\/img\/ai-disclosure\/ai-generated-black\.svg/);
+  assert.match(html, /<svg[^>]*aria-label="AI"/);
   assert.match(html, /This page was generated with AI\./);
+  assert.match(html, /href="\/base\/\/ai"/);
+  assert.match(html, /how Conduction uses AI\./);
 });
 
-test('renders the white (light-ink-on-dark) treatment in dark mode', async () => {
-  const html = await renderAiDisclosure({kind: 'modified'}, {colorMode: 'dark', locale: 'en'});
-  assert.match(html, /\/base\/img\/ai-disclosure\/ai-modified-white\.svg/);
+test('renders the same mark in dark mode, with no treatment switch', async () => {
+  const light = await renderAiDisclosure({kind: 'modified'}, {colorMode: 'light', locale: 'en'});
+  const dark = await renderAiDisclosure({kind: 'modified'}, {colorMode: 'dark', locale: 'en'});
+  assert.equal(dark, light);
+  assert.doesNotMatch(dark, /<img/);
 });
 
 test('renders Dutch copy when the active locale is nl', async () => {
   const html = await renderAiDisclosure({kind: 'assisted'}, {colorMode: 'light', locale: 'nl'});
-  assert.match(html, /Deze pagina is geschreven met hulp van AI\./);
+  assert.match(html, /Deze pagina is geschreven met hulp van AI, bijvoorbeeld voor spelling en onderzoek\./);
+});
+
+test('points at the policy page on conduction.nl from a product docs site', async () => {
+  const html = await renderAiDisclosure(
+    {kind: 'assisted'},
+    {colorMode: 'light', locale: 'en', siteUrl: 'https://dossiq.conduction.nl'},
+  );
+  assert.match(html, /href="https:\/\/conduction\.nl\/ai"/);
 });
 
 test('renders nothing for an unrecognised kind', async () => {

package/src/components/AiDisclosure/__tests__/disclosure.test.js

@@ -32,6 +32,11 @@ const {
   getIconPath,
   getViewBox,
   getCopy,
+  getLinkText,
+  LINK_TEXT,
+  LINK_HREF,
+  POLICY_URL,
+  resolveLinkHref,
 } = require('../disclosure');
 
 // Icons are vendored as plain static files (not a webpack `.svg`
@@ -216,3 +221,58 @@ test('isValidKind rejects anything outside the three permitted values', () => {
   assert.equal(isValidKind(undefined), false);
   assert.equal(isValidKind(null), false);
 });
+
+// -- "read more" pointer to the AI policy page --------------------------------
+//
+// The link is navigation, not a statement about the page, which is why
+// it lives outside COPY and is asserted separately here.
+
+test('link text covers every locale COPY covers', () => {
+  for (const locale of LOCALES) {
+    assert.equal(
+      typeof LINK_TEXT[locale],
+      'string',
+      `LINK_TEXT is missing locale "${locale}" that COPY defines`,
+    );
+    assert.ok(LINK_TEXT[locale].length > 0, `LINK_TEXT["${locale}"] is empty`);
+  }
+});
+
+test('getLinkText falls back to English for an unknown locale', () => {
+  assert.equal(getLinkText('en'), LINK_TEXT.en);
+  assert.equal(getLinkText('nl'), LINK_TEXT.nl);
+  assert.equal(getLinkText('xx'), LINK_TEXT.en);
+  assert.equal(getLinkText(undefined), LINK_TEXT.en);
+});
+
+test('the link points at the AI policy page, site-relative', () => {
+  // Site-relative so useBaseUrl() can prefix a deployment baseUrl.
+  assert.equal(LINK_HREF, '/ai');
+});
+
+test('link text makes no compliance claim either', () => {
+  // Same denylist discipline as COPY: the pointer must not smuggle in a
+  // claim the copy is forbidden from making.
+  const denied = [/compliant/i, /compliance/i, /code of practice/i, /conform/i, /certified/i];
+  for (const locale of LOCALES) {
+    for (const pattern of denied) {
+      assert.ok(
+        !pattern.test(LINK_TEXT[locale]),
+        `LINK_TEXT["${locale}"] matches forbidden pattern ${pattern}`,
+      );
+    }
+  }
+});
+
+test('the link stays site-relative on conduction.nl itself', () => {
+  assert.equal(resolveLinkHref('https://conduction.nl', '/en/ai'), '/en/ai');
+  assert.equal(resolveLinkHref('https://www.conduction.nl/', '/ai'), '/ai');
+});
+
+test('off conduction.nl the link goes to the policy page there, not a local 404', () => {
+  assert.equal(POLICY_URL, 'https://conduction.nl/ai');
+  assert.equal(resolveLinkHref('https://dossiq.conduction.nl', '/ai'), POLICY_URL);
+  assert.equal(resolveLinkHref('https://docs.example.org', '/docs/ai'), POLICY_URL);
+  assert.equal(resolveLinkHref(undefined, '/ai'), POLICY_URL);
+  assert.equal(resolveLinkHref('not a url', '/ai'), POLICY_URL);
+});

package/src/components/AiDisclosure/disclosure.js

@@ -49,27 +49,78 @@ const COPY = {
   nl: {
     generated: 'Deze pagina is gegenereerd met AI.',
     modified: 'Deze pagina is gedeeltelijk aangepast met AI.',
-    assisted: 'Deze pagina is geschreven met hulp van AI.',
+    assisted: 'Deze pagina is geschreven met hulp van AI, bijvoorbeeld voor spelling en onderzoek.',
   },
   en: {
     generated: 'This page was generated with AI.',
     modified: 'This page was partially modified with AI.',
-    assisted: 'This page was written with AI assistance.',
+    assisted: 'This page was written using AI assistance, for example for spelling and research.',
   },
   de: {
     generated: 'Diese Seite wurde mit KI erstellt.',
     modified: 'Diese Seite wurde teilweise mit KI bearbeitet.',
-    assisted: 'Diese Seite wurde mit KI-Unterstützung geschrieben.',
+    assisted:
+      'Diese Seite wurde mit KI-Unterstützung geschrieben, zum Beispiel für Rechtschreibung und Recherche.',
   },
   fr: {
     generated: "Cette page a été générée avec l'IA.",
     modified: "Cette page a été partiellement modifiée avec l'IA.",
-    assisted: "Cette page a été rédigée avec l'aide de l'IA.",
+    assisted:
+      "Cette page a été rédigée avec l'aide de l'IA, par exemple pour l'orthographe et la recherche.",
   },
 };
 
 const LOCALES = Object.keys(COPY);
 
+// The "what does that mean" pointer. Kept OUT of the COPY table on
+// purpose: COPY holds only statements of fact about the page (the
+// denylist test asserts every value makes no compliance claim), while
+// this is navigation. One link text per locale, identical across all
+// three kinds - what the reader wants to know ("how does Conduction
+// use AI?") does not change with the kind.
+const LINK_TEXT = {
+  nl: 'Lees wat dat betekent en hoe Conduction AI gebruikt.',
+  en: 'Read what that means and how Conduction uses AI.',
+  de: 'Lesen Sie, was das bedeutet und wie Conduction KI einsetzt.',
+  fr: "Découvrez ce que cela signifie et comment Conduction utilise l'IA.",
+};
+
+// Site-relative. The page exists at src/pages/ai.mdx ("How we use AI")
+// on conduction.nl only. Every product docs site uses this preset too,
+// and none of them carries an /ai page, so off conduction.nl the link
+// goes to the policy page on conduction.nl instead of a 404.
+const LINK_HREF = '/ai';
+const POLICY_SITE_HOSTS = ['conduction.nl', 'www.conduction.nl'];
+const POLICY_URL = 'https://conduction.nl/ai';
+
+/**
+ * Where the "read more" link points on a given site.
+ *
+ * @param {string} siteUrl   the site's configured `url` (siteConfig.url)
+ * @param {string} localHref LINK_HREF already passed through useBaseUrl()
+ * @returns {string}
+ */
+function resolveLinkHref(siteUrl, localHref) {
+  let host = '';
+  try {
+    host = new URL(siteUrl).hostname;
+  } catch (e) {
+    host = '';
+  }
+  return POLICY_SITE_HOSTS.indexOf(host) !== -1 ? localHref : POLICY_URL;
+}
+
+/**
+ * Localised "read more" text for the disclosure banner.
+ * Falls back to English for an unknown locale, same as getCopy().
+ *
+ * @param {string} locale
+ * @returns {string}
+ */
+function getLinkText(locale) {
+  return LINK_TEXT[locale] || LINK_TEXT.en;
+}
+
 function isValidKind(value) {
   return AI_KINDS.indexOf(value) !== -1;
 }
@@ -159,6 +210,9 @@ module.exports = {
   KIND_TO_FILE_PREFIX,
   VIEWBOX,
   COPY,
+  LINK_TEXT,
+  LINK_HREF,
+  POLICY_URL,
   ICONS_BASE_PATH,
   isValidKind,
   resolveAiFrontmatter,
@@ -166,4 +220,6 @@ module.exports = {
   getIconPath,
   getViewBox,
   getCopy,
+  getLinkText,
+  resolveLinkHref,
 };