@terpjs/react-core 0.10.0 → 0.12.0

package/src/uiText.literals.test.ts

@@ -0,0 +1,199 @@
+// The hole the completeness guard cannot see.
+//
+// `locale.test.tsx` already asserts that every framework string is translated in every
+// shipped locale, and it passes at 100%. It is only as wide as the string TABLE: a
+// hardcoded `aria-label="Clear selection"` never becomes a `TerpStrings` key, so it is
+// invisible to a check that walks keys — and "every framework string is translated" and
+// "this control cannot be translated at all" were both true at the same time.
+//
+// This walks the SOURCE instead, so the two guards together cover the round trip: a
+// user-facing string has to reach the table, and everything in the table has to be
+// translated. Reported as "translations are not always present", which is exactly how it
+// looks from an app — most of the chrome localises, a few controls stubbornly do not, and
+// no gate anywhere goes red.
+//
+// Uses Vite's raw glob rather than an fs walk, the way the other scanning tests here do:
+// this package's tsconfig declares no Node types on purpose.
+
+import { describe, expect, it } from "vitest";
+
+const sources = import.meta.glob("./**/*.{ts,tsx}", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+}) as Record<string, string>;
+
+/** Attributes whose value a user reads or hears. */
+const USER_FACING_ATTRIBUTES = ["aria-label", "placeholder", "title", "alt", "aria-description"];
+
+/**
+ * Files where a bare literal is not a translation defect.
+ *
+ * Deliberately tiny, and each entry says why it is not one. This is NOT a migration
+ * baseline: the framework's chrome is already routed through `TerpStrings`, so there is no
+ * debt to ratchet down, and a growing list here would mean the opposite of what this test
+ * is for.
+ */
+const ALLOWED: Record<string, string> = {
+  "./uiText.tsx": "the string table itself — these ARE the source-language defaults",
+  "./locale.tsx": "the shipped catalogues — every value here is a translation",
+  "./styles.ts":
+    "CSS in a template literal, so a match is an attribute SELECTOR " +
+    '(data-placeholder="true"), never a string a user reads',
+};
+
+/**
+ * A line that only *documents* code.
+ *
+ * These checks forbid a shape, and the clearest way to document a forbidden shape is to
+ * write it down — so the prose explaining the fix contains the defect verbatim. The first
+ * version of the widened default check duly reported DatePicker's own comment, which says
+ * `placeholder = "Select date"` while the code beside it does the right thing. Skipping
+ * comment-only lines is the fix; a literal inside a trailing comment on a line of real code
+ * is still matched, which is the rarer shape and the one worth a false positive.
+ */
+function isComment(line: string): boolean {
+  const trimmed = line.trimStart();
+  return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
+}
+
+function scannable(): [string, string][] {
+  return Object.entries(sources).filter(
+    ([file]) => !/\.(test|spec)\.tsx?$/.test(file) && ALLOWED[file] === undefined,
+  );
+}
+
+describe("user-facing strings", () => {
+  it("never hardcodes an attribute a user reads", () => {
+    const offenders: string[] = [];
+
+    for (const [file, source] of scannable()) {
+      source.split("\n").forEach((line, index) => {
+        if (line.includes("i18n-ok") || isComment(line)) {
+          return;
+        }
+        for (const attribute of USER_FACING_ATTRIBUTES) {
+          // A double-quoted value starting with a letter — a literal a human reads. A
+          // `{expression}` value is not matched, and that is the compliant shape: it
+          // resolves a `UiText` or reads a `TerpStrings` key.
+          const match = new RegExp(`${attribute}="([A-Za-z][^"]*)"`).exec(line);
+          if (match !== null) {
+            offenders.push(`${file}:${index + 1}  ${attribute}="${match[1]}"`);
+          }
+        }
+      });
+    }
+
+    expect(
+      offenders,
+      "these strings are rendered to a user and cannot be translated: they never enter " +
+        "TerpStrings, so locale.test.tsx's completeness guard passes over them and an app " +
+        "has no way to override them. Add a TerpStrings key (with its translations) and " +
+        "read it through useStrings() — or, for a caller-supplied string, take a UiText " +
+        "prop and resolve it with useUiText(). A genuinely non-linguistic value (a test id, " +
+        "a token name) takes an `i18n-ok` comment on the line.",
+    ).toEqual([]);
+  });
+
+  it("never hides a literal inside a braced attribute value", () => {
+    // The shape the check above is blind to by construction. Its comment claimed a
+    // `{expression}` value "is the compliant shape: it resolves a UiText or reads a
+    // TerpStrings key" — true of most, and not of a ternary, a `??` fallback or a default,
+    // any of which carries the untranslatable literal straight through the braces. Not
+    // hypothetical: `aria-label={multiple ? "Clear all selections" : "Clear selection"}`
+    // shipped while this very file was being written to forbid it, and the two met in a
+    // merge. Treating braces as proof of compliance makes the fix for one control the
+    // loophole for the next.
+    //
+    // Same line only, which is a stated limit rather than a claim: the shapes that carry a
+    // literal (ternary, fallback, default) fit on one line under this repo's formatting.
+    const offenders: string[] = [];
+
+    for (const [file, source] of scannable()) {
+      source.split("\n").forEach((line, index) => {
+        if (line.includes("i18n-ok") || isComment(line)) {
+          return;
+        }
+        for (const attribute of USER_FACING_ATTRIBUTES) {
+          // The name must stand alone: `data-placeholder={…}` is not `placeholder`, and
+          // matching it as a substring reported a data attribute's `"true"` as prose.
+          const opener = new RegExp(`(?<![\w-])${attribute}=\{`, "g");
+          for (const opened of line.matchAll(opener)) {
+            // Read to the MATCHING brace. Reading to end-of-line swept up whatever attribute
+            // came next — `data-terp="breadcrumbs"` on the same element was reported as a
+            // user-facing literal.
+            const start = opened.index + opened[0].length;
+            let cursor = start;
+            let depth = 1;
+            while (cursor < line.length && depth > 0) {
+              if (line[cursor] === "{") depth += 1;
+              else if (line[cursor] === "}") depth -= 1;
+              if (depth === 0) break;
+              cursor += 1;
+            }
+            for (const [literal, inner] of line.slice(start, cursor).matchAll(/"([A-Za-z][^"]*)"/g)) {
+              // Inside an expression most literals are not prose: a discriminant
+              // (`kind === "role"`), a placeholder token, a data value. Unlike the direct
+              // `attribute="…"` position — where a literal is user-facing almost by
+              // definition — this one asks whether the string LOOKS like a label.
+              //
+              // A heuristic, stated as one: a lowercase single-word label
+              // (`aria-label={open ? "close" : "open"}`) slips through. Every user-facing
+              // string this framework ships is a capitalised phrase, so that shape does not
+              // exist here; if one lands, it wants the direct check's discipline rather than
+              // a wider net here, which would flag every discriminant in the package.
+              if (/^[A-Z]/.test(inner!) || inner!.includes(" ")) {
+                offenders.push(`${file}:${index + 1}  ${attribute}={… ${literal} …}`);
+              }
+            }
+          }
+        }
+      });
+    }
+
+    expect(
+      offenders,
+      "a user-facing attribute resolves an expression, and the expression still contains a " +
+        "hardcoded English string — most often a ternary picking between two literals, or a " +
+        "`??` fallback behind a translatable prop. Braces are not evidence of anything: move " +
+        "every branch to a TerpStrings key and read them through useStrings().",
+    ).toEqual([]);
+  });
+
+  it("never defaults a UiText prop to a bare string", () => {
+    // The subtler half, and the one that looks fine in review. A `UiText` prop defaulted to
+    // `"Select date"` IS overridable — and still untranslatable: a plain string resolves
+    // as-is, so an app that does not pass the prop shows English in every locale. The fix is
+    // not a descriptor default either; it is to fall back to a TerpStrings key at the use
+    // site, so the app's own catalogue answers when the caller says nothing.
+    const offenders: string[] = [];
+
+    for (const [file, source] of scannable()) {
+      const uiTextProps = new Set(
+        [...source.matchAll(/^\s*(\w+)\??:\s*UiText[;\s|]/gm)].map((match) => match[1]!),
+      );
+      source.split("\n").forEach((line, index) => {
+        if (line.includes("i18n-ok") || isComment(line)) {
+          return;
+        }
+        // Anywhere on the line, NOT anchored to own it. Anchoring made this depend on
+        // formatting: `removeLabel = "Remove"` inside a one-line destructuring
+        // (`const { value, onChange, removeLabel = "Remove", ...rest } = props`) was
+        // invisible, and became visible only when the line was split for unrelated reasons.
+        // A check that a reformat can switch on and off is not a check.
+        for (const assignment of line.matchAll(/(\w+)\s*=\s*"([A-Za-z][^"]*)"/g)) {
+          if (uiTextProps.has(assignment[1]!)) {
+            offenders.push(`${file}:${index + 1}  ${assignment[1]} = "${assignment[2]}"`);
+          }
+        }
+      });
+    }
+
+    expect(
+      offenders,
+      "a UiText prop defaulted to a plain string renders that string in every locale for any " +
+        "app that does not override it — the prop is translatable and its default is not. " +
+        "Leave the default `undefined` and fall back to a TerpStrings key at the use site.",
+    ).toEqual([]);
+  });
+});

package/src/uiText.test.tsx

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { Page } from "./Page";
 import { ResourceList } from "./ResourceList";
 import { TerpProvider } from "./TerpProvider";
-import { resolveUiText, UiTextProvider } from "./uiText";
+import { resolveUiText, resolveUiTextNode, UiTextProvider } from "./uiText";
 
 afterEach(cleanup);
 
@@ -14,6 +14,20 @@ describe("resolveUiText", () => {
     expect(resolveUiText("Tasks")).toBe("Tasks");
     expect(resolveUiText({ id: "tasks.title", message: "Tasks" })).toBe("Tasks");
   });
+
+  it("resolves descriptors in prose slots and preserves rich React nodes", () => {
+    const resolve = (text: string | { readonly id: string; readonly message: string }) =>
+      typeof text === "string" ? text : `translated:${text.id}`;
+    expect(
+      resolveUiTextNode(
+        { id: "tasks.empty.description", message: "Create your first task." },
+        resolve,
+      ),
+    ).toBe("translated:tasks.empty.description");
+
+    const rich = <strong>Already rendered</strong>;
+    expect(resolveUiTextNode(rich, resolve)).toBe(rich);
+  });
 });
 
 describe("UiTextProvider", () => {

package/src/uiText.tsx

@@ -1,5 +1,8 @@
 import { createContext, useCallback, useContext, useMemo } from "react";
 import type { ReactNode } from "react";
+import type { UiText } from "@terpjs/contract";
+
+export type { UiText } from "@terpjs/contract";
 
 /**
  * A piece of user-facing text: either a plain string (used as-is) or a message
@@ -7,11 +10,38 @@ import type { ReactNode } from "react";
  * `message` used as the fallback. Components accept `UiText` so an app can go
  * from hardcoded strings to a full i18n runtime without changing call sites.
  */
-export type UiText = string | { id: string; message: string };
-
 /** Resolves a {@link UiText} to the display string for the active locale. */
 export type ResolveUiText = (text: UiText) => string;
 
+/** Textual copy or an already-rendered rich node, for prose-bearing component slots. */
+export type UiTextNode = UiText | ReactNode;
+
+/**
+ * Resolve a descriptor/string while leaving rich React content untouched. Components
+ * with prose slots use this instead of making callers choose between localization and
+ * inline emphasis/links.
+ */
+export function resolveUiTextNode(
+  value: UiTextNode,
+  resolve: ResolveUiText = resolveUiText,
+): ReactNode {
+  if (typeof value === "string") {
+    return resolve(value);
+  }
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "id" in value &&
+    "message" in value &&
+    typeof value.id === "string" &&
+    typeof value.message === "string"
+  ) {
+    return resolve(value);
+  }
+  return value as ReactNode;
+}
+
 /** The default resolver: plain strings as-is, descriptors via their fallback `message`. */
 export function resolveUiText(text: UiText): string {
   return typeof text === "string" ? text : text.message;
@@ -210,9 +240,36 @@ export interface TerpStrings {
   saved: string;
   /** Generic failure toast when a request did not go through. */
   requestFailed: string;
+  /** Combobox: clears the single selection. */
+  clearSelection: string;
+  /** Combobox: clears every selection in multiple mode. */
+  clearAllSelections: string;
+  /** Combobox: removes one chosen option in multiple mode, prefixed to its label. */
+  comboboxRemove: string;
+  /** Combobox: shown in the listbox while options are being fetched. */
+  comboboxLoading: string;
+  /** Combobox: shown in the listbox when the filter matches nothing. */
+  comboboxNoOptions: string;
+  /** DatePicker: steps the calendar back one month. */
+  previousMonth: string;
+  /** DatePicker: steps the calendar forward one month. */
+  nextMonth: string;
+  /** DatePicker: trigger text before a date is chosen. */
+  selectDate: string;
+  /** DateRangePicker: trigger text before a range is chosen. */
+  selectDateRange: string;
 }
 
 export const DEFAULT_STRINGS: TerpStrings = {
+  clearSelection: "Clear selection",
+  clearAllSelections: "Clear all selections",
+  comboboxRemove: "Remove",
+  comboboxLoading: "Loading…",
+  comboboxNoOptions: "No options",
+  previousMonth: "Previous month",
+  selectDate: "Select date",
+  selectDateRange: "Select date range",
+  nextMonth: "Next month",
   loading: "Loading...",
   emptyList: "Nothing here yet.",
   add: "Add",
@@ -358,3 +415,15 @@ export function useUiText(): ResolveUiText {
   const { resolveText } = useContext(UiTextContext);
   return useCallback((text: UiText) => resolveText(text), [resolveText]);
 }
+
+/** Props for {@link Trans}: one stable catalog id and its source-language fallback. */
+export interface TransProps {
+  id: string;
+  message: string;
+}
+
+/** Render authored copy through the active locale resolver, including plain JSX body text. */
+export function Trans({ id, message }: TransProps) {
+  const resolve = useUiText();
+  return <>{resolve({ id, message })}</>;
+}