@carlonicora/nextjs-jsonapi 3.13.0 → 3.14.1

package/src/components/containers/MermaidDiagram.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import { useTheme } from "next-themes";
+import { useEffect, useId, useState } from "react";
+
+type MermaidDiagramProps = {
+  /** The body of a ```mermaid fence, verbatim. */
+  chart: string;
+};
+
+/**
+ * One Mermaid diagram, rendered in the browser.
+ *
+ * Four decisions worth keeping:
+ *
+ * 1. **`mermaid` is imported dynamically, inside the effect.** The library is
+ *    roughly half a megabyte gzipped. A static import at module scope would put
+ *    it in the bundle of every page that renders any markdown at all; this way
+ *    only a page that actually holds a diagram fetches it.
+ * 2. **The id comes from `useId`.** Mermaid keys its internal definitions by the
+ *    id it is handed, and two diagrams sharing one silently blank the second.
+ * 3. **A parse failure falls back to the source.** Mermaid throws on malformed
+ *    input and, worse, injects its own error graphic into the document when it
+ *    does — `suppressErrorRendering` turns that off, and the caller renders the
+ *    fenced block it would have shown anyway. A bad diagram must never cost the
+ *    reader the rest of the page.
+ * 4. **The theme is read, not assumed.** `resolvedTheme` resolves "system" to a
+ *    real value; re-running on a change is what keeps a diagram from staying
+ *    black-on-black after the mode flips. Mirrors `TokenUsageTimelineChart`.
+ */
+export function MermaidDiagram({ chart }: MermaidDiagramProps) {
+  const reactId = useId();
+  const { resolvedTheme } = useTheme();
+  const [svg, setSvg] = useState<string | undefined>(undefined);
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const draw = async () => {
+      try {
+        const mermaid = (await import("mermaid")).default;
+
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "strict",
+          suppressErrorRendering: true,
+          theme: resolvedTheme === "dark" ? "dark" : "default",
+
+          // `useMaxWidth: false` on every diagram type this documentation uses.
+          //
+          // By default Mermaid emits `width="100%"` with a viewBox, so the
+          // drawing scales to whatever box it lands in — inside a reading
+          // column that shrinks a seven-node graph until its labels are
+          // unreadable, and no CSS `max-width` can undo it because the scaling
+          // comes from the viewBox, not the width limit. With it off the SVG
+          // carries its intrinsic width and the wrapper scrolls to it, the same
+          // bargain a wide table makes.
+          flowchart: { useMaxWidth: false },
+          sequence: { useMaxWidth: false },
+          class: { useMaxWidth: false },
+          state: { useMaxWidth: false },
+          er: { useMaxWidth: false },
+          journey: { useMaxWidth: false },
+          gantt: { useMaxWidth: false },
+          pie: { useMaxWidth: false },
+        });
+
+        // Colons and other punctuation React puts in a useId are not legal in
+        // the DOM id Mermaid derives from this one.
+        const id = `mermaid-${reactId.replace(/[^a-zA-Z0-9-]/g, "")}`;
+        const result = await mermaid.render(id, chart);
+
+        if (cancelled) return;
+        setSvg(result.svg);
+        setFailed(false);
+      } catch {
+        if (cancelled) return;
+        setFailed(true);
+        setSvg(undefined);
+      }
+    };
+
+    void draw();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [chart, reactId, resolvedTheme]);
+
+  // Before the first render resolves, and after a failure, show the source. It
+  // is what the page displayed before diagrams were drawn at all, so the reader
+  // never ends up with less than they had.
+  if (failed || svg === undefined)
+    return (
+      // rtl-ok: deliberate LTR island (diagram source)
+      <pre dir="ltr" className="overflow-x-auto">
+        <code dir="ltr">{chart}</code>
+      </pre>
+    );
+
+  return (
+    <div
+      // Mermaid emits a complete <svg> document. It is generated from the
+      // repository's own documentation, and `securityLevel: "strict"` has
+      // already stripped script and foreign content from it.
+      // `!max-w-none`, not `max-w-full`. Mermaid writes an inline
+      // `max-width` on the SVG, and honouring it inside a reading column
+      // squeezes a wide graph until its labels are unreadable — the diagram is
+      // technically present and practically useless. An `!important` rule is
+      // what beats an inline style, so the graph keeps its natural size and the
+      // wrapper scrolls to it, exactly as a wide table does.
+      className="my-4 overflow-x-auto [&_svg]:mx-auto [&_svg]:h-auto [&_svg]:!max-w-none"
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

package/src/components/containers/ReactMarkdownContainer.tsx

@@ -8,6 +8,29 @@ import rehypeSlug from "rehype-slug";
 import remarkGfm from "remark-gfm";
 
 import { cn } from "../../utils/cn";
+import { MermaidDiagram } from "./MermaidDiagram";
+
+/**
+ * The source of a ```mermaid fence, or `undefined` for any other `pre`.
+ *
+ * Reads react-markdown's hast node rather than the rendered children: the
+ * language lives in the inner `code` element's `language-*` class, and the
+ * source is its raw text. Pulling it off the React children would mean
+ * unpicking elements that the `code` override has already transformed.
+ */
+function mermaidSourceOf(node: unknown): string | undefined {
+  const pre = node as { children?: { tagName?: string; properties?: { className?: unknown }; children?: unknown[] }[] };
+  const code = pre?.children?.[0];
+  if (code?.tagName !== "code") return undefined;
+
+  const classNames = Array.isArray(code.properties?.className) ? (code.properties.className as string[]) : [];
+  if (!classNames.includes("language-mermaid")) return undefined;
+
+  const text = code.children?.[0] as { type?: string; value?: string } | undefined;
+  if (text?.type !== "text" || typeof text.value !== "string") return undefined;
+
+  return text.value;
+}
 
 type ReactMarkdownContainerProps = {
   content: string;
@@ -100,15 +123,25 @@ export function ReactMarkdownContainer({
               // left-to-right in every locale, so both the fenced block and the
               // inline span are deliberate LTR islands. `node` is react-markdown's
               // hast node — it must not reach the DOM element.
-              // A fenced block scrolls on its own rather than widening the
-              // page: a long command line is unbreakable, and without this the
-              // whole layout is pushed sideways to accommodate it.
+              // A ```mermaid fence is a DIAGRAM, not code. It is caught here on
+              // the `pre` rather than on the `code` inside it, because the
+              // diagram replaces the whole block — catching it a level down
+              // would leave it wrapped in the `pre` chrome it is not.
+              //
+              // A fenced block otherwise scrolls on its own rather than
+              // widening the page: a long command line is unbreakable, and
+              // without this the whole layout is pushed sideways.
               // rtl-ok: deliberate LTR island (code)
-              pre: ({ children, node: _node, ...props }) => (
-                <pre dir="ltr" {...props} className="overflow-x-auto">
-                  {children}
-                </pre>
-              ),
+              pre: ({ children, node, ...props }) => {
+                const diagram = mermaidSourceOf(node);
+                if (diagram !== undefined) return <MermaidDiagram chart={diagram} />;
+
+                return (
+                  <pre dir="ltr" {...props} className="overflow-x-auto">
+                    {children}
+                  </pre>
+                );
+              },
               // No wrap rule HERE. The same component renders inline spans, the
               // contents of fenced blocks and the contents of table cells; the
               // last two live in their own scrollers, and breaking a path

package/src/components/containers/index.ts

@@ -1,5 +1,6 @@
 export * from "./PageContainer";
 export * from "./partitionTabs";
+export * from "./MermaidDiagram";
 export * from "./ReactMarkdownContainer";
 export * from "./RoundPageContainer";
 export * from "./RoundPageContainerTitle";

package/src/features/__tests__/i18n-keys.contract.spec.ts

@@ -0,0 +1,131 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Every `features/<feature>/i18n-keys.ts` declares the translation keys this
+ * package will ask a consuming app to define. Nothing imported those lists, so
+ * they were documentation that happened to compile: a component could add a
+ * `t("…")` call without touching the contract, and the omission only surfaced
+ * in whichever app rendered that branch first. `handbook.notFound` and the six
+ * `billing.tokens.*` keys reached several apps that way.
+ *
+ * These tests read the lists and the sources and compare them, in both
+ * directions, so the two cannot drift apart silently again.
+ */
+
+const FEATURES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+const SRC_DIR = join(FEATURES_DIR, "..");
+
+/**
+ * Keys a contract promises that no component in this package reads — the app
+ * owns the surface that renders them (administration landing cards, the help
+ * landing page, handbook screens an app builds itself). They are legitimate
+ * contract entries, so they are listed rather than deleted, but the list is
+ * closed: a NEW unread key fails the second test until someone either wires it
+ * up, deletes it, or justifies it here.
+ */
+const DECLARED_FOR_APP_RENDERED_SURFACES = new Set<string>([
+  "administration.billing.description",
+  "administration.companies.description",
+  "administration.group.platform",
+  "administration.rbac.description",
+  "administration.token_usage.description",
+  "administration.users.description",
+  "administration.ai_connections.description",
+  "handbook.chat.delete_confirm",
+  "handbook.chat.rename_placeholder",
+  "handbook.contents.title",
+  "handbook.notConfigured",
+  "handbook.subtitle",
+  "help.article.related",
+  "help.header.search",
+  "help.landing.browseByMode",
+  "help.landing.featuredTutorials",
+  "help.landing.heading",
+  "help.landing.subheading",
+  "help.modeIndex.empty",
+  "token_usage.series.other",
+  "token_usage.timeline.empty",
+]);
+
+/** `t("key")`, `t('key')`, `t(`key`)` and their `t.rich(…)` equivalents. */
+const STATIC_KEY = /\bt(?:\.rich)?\(\s*(?:"([^"${]+)"|'([^'${]+)'|`([^`${]+)`)/g;
+/** ``t(`prefix.${expr}`)`` — only the literal head is knowable. */
+const DYNAMIC_PREFIX = /\bt(?:\.rich)?\(\s*`([^`]*?)\$\{/g;
+
+function sourceFiles(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      if (entry !== "__tests__") sourceFiles(path, found);
+    } else if (/\.tsx?$/.test(entry) && !/\.(test|spec)\.tsx?$/.test(entry)) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/** Where each key is read, so a failure names the file instead of just the key. */
+const readKeys = new Map<string, string>();
+const dynamicPrefixes = new Set<string>();
+for (const file of sourceFiles(SRC_DIR)) {
+  const source = readFileSync(file, "utf8");
+  for (const match of source.matchAll(STATIC_KEY)) {
+    const key = (match[1] ?? match[2] ?? match[3])!;
+    if (!readKeys.has(key)) readKeys.set(key, relative(SRC_DIR, file));
+  }
+  for (const match of source.matchAll(DYNAMIC_PREFIX)) {
+    if (match[1]) dynamicPrefixes.add(match[1]);
+  }
+}
+
+const contracts = new Map<string, string[]>();
+for (const feature of readdirSync(FEATURES_DIR)) {
+  const path = join(FEATURES_DIR, feature, "i18n-keys.ts");
+  let source: string;
+  try {
+    source = readFileSync(path, "utf8");
+  } catch {
+    continue;
+  }
+  contracts.set(
+    feature,
+    [...source.matchAll(/"([^"]+)"/g)].map((match) => match[1]!),
+  );
+}
+
+/**
+ * Declared keys pooled across features: namespaces are shared (ai-connection
+ * reads `administration.*`), so ownership is per namespace, not per directory.
+ */
+const declared = new Set([...contracts.values()].flat());
+const declaredNamespaces = new Set([...declared].map((key) => key.split(".")[0]));
+
+describe("i18n key contracts", () => {
+  it("finds a contract to check", () => {
+    expect(contracts.size).toBeGreaterThan(0);
+    expect(readKeys.size).toBeGreaterThan(0);
+  });
+
+  it("declares every key the package reads in a contracted namespace", () => {
+    const undeclared = [...readKeys.entries()]
+      .filter(([key]) => declaredNamespaces.has(key.split(".")[0]!) && !declared.has(key))
+      .map(([key, file]) => `${key} (read in ${file})`)
+      .sort();
+
+    expect(undeclared).toEqual([]);
+  });
+
+  it.each([...contracts.keys()])("has no unread keys in the %s contract", (feature) => {
+    const isRead = (key: string) => readKeys.has(key) || [...dynamicPrefixes].some((prefix) => key.startsWith(prefix));
+
+    const unread = contracts
+      .get(feature)!
+      .filter((key) => !isRead(key) && !DECLARED_FOR_APP_RENDERED_SURFACES.has(key))
+      .sort();
+
+    expect(unread).toEqual([]);
+  });
+});

package/src/features/billing/i18n-keys.ts

@@ -93,3 +93,18 @@ export const BILLING_ADMIN_I18N_KEYS = [
   "billing.admin.prices.restore.description",
   "billing.admin.prices.restore.confirm",
 ] as const;
+
+/**
+ * The `billing.tokens.*` namespace, read by the token status indicator rather
+ * than by any administrative surface — which is why it is a second export
+ * instead of an addition to the list above, whose contract is scoped to the
+ * admin screens.
+ */
+export const BILLING_TOKENS_I18N_KEYS = [
+  "billing.tokens.status",
+  "billing.tokens.monthly",
+  "billing.tokens.available",
+  "billing.tokens.available_extra",
+  "billing.tokens.purchase_extra",
+  "billing.tokens.upgrade_plan",
+] as const;

package/src/features/handbook/components/details/HandbookPageDetails.tsx

@@ -22,6 +22,31 @@ type HandbookPageDetailsProps = {
  * to the English file. This is the detail read, which is the only read that
  * carries `displayContent` at all.
  */
+/**
+ * The reading column's type scale.
+ *
+ * `ReactMarkdownContainer`'s `size="normal"` puts NO size class on `p` or `li`,
+ * so they inherit — and the app's root is 14px while the browser default the
+ * container's own headings are sized against is 16px. The body therefore
+ * rendered a step larger than every other piece of body copy in the product,
+ * which role 7 of the typography system puts at `text-sm`.
+ *
+ * `text-sm` on the wrapper fixes the inherited elements by cascade. The heading
+ * ladder has explicit classes and cannot cascade, so it is restated one step
+ * down — a `text-3xl` H1 belongs to a page that has no header above it, and
+ * this one is already titled twice over by the reader's header and breadcrumb.
+ *
+ * Scoped HERE rather than in the shared container on purpose: 23 other surfaces
+ * render markdown through it — judgements, law articles, documents, legal
+ * research reports — and changing its default would restyle all of them
+ * silently. That alignment is worth making, but as its own change.
+ */
+const READING_SCALE = "text-sm [&_h1]:text-2xl [&_h2]:text-xl [&_h3]:text-base [&_h4]:text-sm [&_table]:text-sm";
+
 export function HandbookPageDetails({ handbookPage }: HandbookPageDetailsProps) {
-  return <ReactMarkdownContainer content={handbookPageContent(handbookPage)} />;
+  return (
+    <div className={READING_SCALE}>
+      <ReactMarkdownContainer content={handbookPageContent(handbookPage)} />
+    </div>
+  );
 }

package/src/features/handbook/i18n-keys.ts

@@ -17,6 +17,7 @@ export const handbookI18nKeys = [
   "handbook.syncFailed",
   "handbook.empty",
   "handbook.notConfigured",
+  "handbook.notFound",
   "handbook.chat.title",
   "handbook.chat.placeholder",
   "handbook.chat.ask",