npm - @terpjs/react-core - Versions diffs - 0.10.0 → 0.12.0 - Mend

@terpjs/react-core 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/README.md +7 -6
package/package.json +2 -2
package/src/AppShell.test.tsx +52 -4
package/src/AppShell.tsx +35 -17
package/src/ConfirmDialog.tsx +4 -4
package/src/EmptyState.test.tsx +30 -0
package/src/EmptyState.tsx +31 -8
package/src/ErrorState.tsx +8 -4
package/src/Field.test.tsx +20 -0
package/src/Field.tsx +2 -2
package/src/LoginView.test.tsx +34 -2
package/src/LoginView.tsx +33 -20
package/src/UserMenu.test.tsx +2 -2
package/src/bootstrap.tsx +5 -2
package/src/format.test.tsx +3 -3
package/src/index.ts +24 -3
package/src/locale.test.tsx +195 -3
package/src/locale.tsx +196 -11
package/src/markers.test.ts +2 -0
package/src/nav.ts +2 -2
package/src/router.tsx +13 -3
package/src/sso.ts +2 -2
package/src/styles.test.ts +84 -34
package/src/styles.ts +233 -31
package/src/tokens.guard.test.ts +49 -2
package/src/ui/Combobox.test.tsx +90 -0
package/src/ui/Combobox.tsx +247 -41
package/src/ui/DatePicker.tsx +16 -7
package/src/ui/Tabs.test.tsx +28 -0
package/src/ui/Tabs.tsx +14 -0
package/src/uiText.literals.test.ts +199 -0
package/src/uiText.test.tsx +15 -1
package/src/uiText.tsx +71 -2

package/README.md CHANGED Viewed

@@ -31,9 +31,10 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
   focus ring, a checkbox's `accent-color`. One token cannot do both: in a dark theme the
   surface use needs a value dark enough to hold a white label and the ink use needs one light
   enough to read on a dark canvas, and there is no value satisfying both.
-- **User-facing text is `UiText`** — every text prop accepts a plain string or an
-  `{id, message}` descriptor, so apps can localize via `UiTextProvider` without
-  react-core taking an i18n dependency.
+- **Static user-facing text is cataloged** — use an `{id, message}` `UiText`
+  descriptor for text props and `<Trans id message />` for JSX bodies. Plain strings are
+  reserved for dynamic business data, identifiers and product names. The boundary lint
+  refuses bare static copy and checks every id against every target in `frontend/i18n.json`.
 - **Dependency-free UI** — react-core ships no icon/toast/i18n libraries. Glyphs are
   inline SVG; transient feedback goes through `ToastProvider` / `useToast`.
 - **Security defaults** — `dangerouslySetInnerHTML` and the DOM HTML-injection sinks
@@ -54,7 +55,7 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
 | `useSso`, `parseSsoCallback`, `fetchSsoAuthorizationUrl`, `completeSsoCallback` | The SSO login seam (ADR 0058): `useSso().begin(provider)` opens an OIDC flow; `TerpProvider` completes the `/auth/callback/{provider}` redirect landing into a normal session on boot. `renderTerpApp({ ssoProviders })` wires the buttons in one line. |
 | `RequireAuth` | Renders children only with a session; pairs with the router so the app mounts only when signed in. |
 | `ThemeProvider`, `ThemeToggle`, `useTheme` | Theming over the shipped palettes — `light`, `dark`, `midnight`, `twilight`, `contrast` — plus `system` to follow the OS preference. Applies `data-theme` on `<html>` (the token stylesheet carries every palette) and persists the choice. `defaultTheme` is how an app ships on a named theme — declare it in `layout-contract.json` so a tool can read and rewrite it, or pass the bootstrap option; both is refused. `renderTerpApp` mounts it for every app; the shell header uses an icon-only, token-themed `variant="inline"` menu. |
-| `LocaleProvider`, `LanguageSwitcher`, `useLocale`, `LOCALE_EN`, `LOCALE_NL` | The language seam over `UiTextProvider`: per-locale string catalogs, a persisted active locale, and an icon-only, token-themed menu in the shell header once an app declares a second locale. English and Dutch catalogs ship complete; `renderTerpApp({ locales })` wires them. |
+| `LocaleProvider`, `defineAppLocales`, `LanguageSwitcher`, `useLocale`, `LOCALE_EN`, `LOCALE_NL` | The language seam over `UiTextProvider`: `defineAppLocales(i18n, frameworkCatalogs)` validates and merges checked-in app messages with framework chrome, the active locale persists, and the shell offers a picker. Pass `sourceLocale` with `locales`; missing/empty target messages, undocumented source copies, invalid locale selection and a non-English locale without a complete framework-string catalog throw rather than silently falling back. |
 | `UserMenu`, `userInitials` | The signed-in user's menu, pinned by `buildAppRouter` to the bottom of the sidebar: an initials avatar trigger opening the identity block, **Settings** (the built-in profile page) and sign-out. Collapses to the avatar in the icon rail. |
 | `ProfileView` | The built-in profile / settings page (`/profile`): the server-validated identity, theme + language preferences, and sign-out. |
@@ -70,7 +71,7 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
 ## Page archetypes (the three-level screen pattern)
 Every routed view **must** render one of the archetypes (`Page`, or `OverviewPage` /
-`DetailPage` / `HubPage`, which compose it) — `buildAppRouter` refuses an unframed view at
+`DetailPage` / `HubPage` / `FormPage` / `SettingsPage` / `SplitPage`, which compose it) — `buildAppRouter` refuses an unframed view at
 runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/error frame.
 | Export | Use |
@@ -266,7 +267,7 @@ single screen by claiming its path from an app module.
 | Export | Use |
 |---|---|
-| `UiTextProvider`, `useUiText`, `useStrings`, `resolveUiText`, `DEFAULT_STRINGS` | The `UiText` seam: override built-in strings and plug in a resolver (e.g. an i18n library) at the app root. `LocaleProvider` (above) is the batteries-included layer over it: per-locale catalogs + a persisted switcher. |
+| `UiTextProvider`, `Trans`, `useUiText`, `useStrings`, `resolveUiText`, `DEFAULT_STRINGS` | The `UiText` seam: descriptors for props, `Trans` for body copy, and framework strings through one resolver. `LocaleProvider` is the batteries-included catalog layer and refuses missing target-locale entries. |
 ## Testing components

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Terp React stack core — typed @terpjs/contract client provider, auth session, capability gates, TanStack Router adapter, app shell, page archetypes, DataView and token-styled UI primitives. First frontend stack; see README.md for the component catalog.",
   "exports": {
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.10.0"
+    "@terpjs/contract": "^0.12.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/AppShell.test.tsx CHANGED Viewed

@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { NavItem } from "@terpjs/contract";
 import { AppShell, SIDEBAR_STORAGE_KEY } from "./AppShell";
+import { LOCALE_NL, LocaleProvider } from "./locale";
 afterEach(() => {
   cleanup();
@@ -43,15 +44,20 @@ function stubMobileViewport() {
 }
 describe("AppShell", () => {
-  it("renders the landmarks, brand, footer, and the nav via renderLink", () => {
+  it("renders the landmarks, brand, and the nav via renderLink — and NO footer", () => {
     renderShell();
     expect(screen.getByRole("banner")).toBeInTheDocument();
     expect(screen.getByRole("navigation", { name: "Primary" })).toBeInTheDocument();
     expect(screen.getByRole("main")).toBeInTheDocument();
-    expect(screen.getByRole("contentinfo")).toBeInTheDocument();
-    // The brand is the standard home affordance; the default footer echoes the title.
-    expect(screen.getAllByText("Terp").length).toBeGreaterThanOrEqual(2);
+    // No `contentinfo` unless the app asks for one. The default used to be a strip
+    // restating the app title already in the header and the browser tab — on every screen
+    // of every app, costing vertical space on exactly the viewports with least of it. An
+    // empty landmark is worse than none: it is somewhere a screen-reader user can navigate
+    // to and find nothing.
+    expect(screen.queryByRole("contentinfo")).toBeNull();
+    // The brand is the standard home affordance.
+    expect(screen.getAllByText("Terp").length).toBeGreaterThanOrEqual(1);
     expect(screen.getByRole("link", { name: "Terp" })).toHaveAttribute("href", "/");
     expect(screen.getByRole("link", { name: "Notes" })).toHaveAttribute("href", "/notes");
     expect(screen.getByText("page content")).toBeInTheDocument();
@@ -355,6 +361,48 @@ describe("AppShell navigation groups", () => {
     { label: "Loose", to: "/loose" },
   ];
+  it("resolves localized item and group descriptors before rendering navigation", () => {
+    render(
+      <LocaleProvider
+        locales={{
+          en: {},
+          nl: {
+            ...LOCALE_NL,
+            messages: {
+              "nav.work": "Werkruimte",
+              "nav.notes": "Notities",
+            },
+          },
+        }}
+        defaultLocale="nl"
+        sourceLocale="en"
+      >
+        <AppShell
+          title="Terp"
+          nav={[
+            {
+              label: { id: "nav.notes", message: "Notes" },
+              to: "/notes",
+              group: "work",
+            },
+          ]}
+          navGroups={[
+            {
+              id: "work",
+              label: { id: "nav.work", message: "Workspace" },
+            },
+          ]}
+          renderLink={(item, children) => <a href={item.to}>{children}</a>}
+        >
+          <p>page content</p>
+        </AppShell>
+      </LocaleProvider>,
+    );
+    expect(screen.getByRole("list", { name: "Werkruimte" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Notities" })).toHaveAttribute("href", "/notes");
+  });
   it("labels each group's list with its own visible label", () => {
     render(
       <AppShell

package/src/AppShell.tsx CHANGED Viewed

@@ -125,7 +125,11 @@ interface AppShellBaseProps {
   density?: "comfortable" | "compact";
   /** Pinned to the bottom of the sidebar (the {@link UserMenu}); may read the rail state. */
   navFooter?: ReactNode | ((context: AppShellSlotContext) => ReactNode);
-  /** Footer line under the content; default: a muted line with the app title. */
+  /**
+   * Footer content under the routed view. **Omit it and no footer renders** — there is no
+   * default, because the default was a strip restating the app title already in the header
+   * and the browser tab, on every screen of every app, and nobody chose it.
+   */
   footer?: ReactNode;
   /**
    * The current URL path, so the shell can decide which nav item is current.
@@ -298,7 +302,7 @@ function PanelIcon() {
  *   nav and the same user menu render in the header, and the drawer still handles mobile;
  * - a **sticky** header over the content: the sidebar toggle on the left, then
  *   `headerActions` and the standard theme + language controls on the right;
- * - the routed `children` in a `main` landmark, with a slim `footer` underneath.
+ * - the routed `children` in a `main` landmark, with an optional `footer` underneath.
  *
  * Router-agnostic: `renderLink` wraps the shell-styled icon + label in the active
  * stack's link. Landmarks (`header` / `nav` / `main` / `footer`) keep it accessible.
@@ -473,11 +477,12 @@ export function AppShell({
       onClick={isMobile ? closeDrawer : undefined}
     >
       {groupNav(nav, navGroups).map((section, index) => {
+        const groupLabel = section.label === null ? null : resolve(section.label);
         // Only a labelled section needs an id, and only a DECLARED section can be labelled — the
         // default one has no declaration to carry a label. Keyed on the index rather than on
         // `section.id`: a group id is an app-supplied string, and whitespace in one would
         // silently break the IDREF rather than fail anywhere.
-        const labelId = section.label === null ? undefined : `${navGroupId}-${index}`;
+        const labelId = groupLabel === null ? undefined : `${navGroupId}-${index}`;
         return (
           // No heading element, and this is the decision rather than an oversight. `Heading`
           // refuses level 1 to reserve it for the routed view's title (see typography.tsx), and
@@ -500,22 +505,25 @@ export function AppShell({
           <div key={index} data-terp="appshell-nav-group">
             {labelId !== undefined && (
               <span id={labelId} data-terp="appshell-nav-group-label">
-                {section.label}
+                {groupLabel}
               </span>
             )}
             <ul data-terp="appshell-nav-list" aria-labelledby={labelId}>
-              {section.items.map((item) => (
-                <li key={item.to} title={railCollapsed ? item.label : undefined}>
-                  {renderLink(
-                    item,
-                    <>
-                      <NavIcon name={item.icon} label={item.label} />
-                      <span data-terp="appshell-nav-label">{item.label}</span>
-                    </>,
-                    { collapsed: railCollapsed, active: item.to === currentTo },
-                  )}
-                </li>
-              ))}
+              {section.items.map((item) => {
+                const label = resolve(item.label);
+                return (
+                  <li key={item.to} title={railCollapsed ? label : undefined}>
+                    {renderLink(
+                      item,
+                      <>
+                        <NavIcon name={item.icon} label={label} />
+                        <span data-terp="appshell-nav-label">{label}</span>
+                      </>,
+                      { collapsed: railCollapsed, active: item.to === currentTo },
+                    )}
+                  </li>
+                );
+              })}
             </ul>
           </div>
         );
@@ -688,7 +696,17 @@ export function AppShell({
         <main id={mainId} data-terp="appshell-main" tabIndex={-1}>
           {children}
         </main>
-        <footer data-terp="appshell-footer">{footer ?? <small>{resolvedTitle}</small>}</footer>
+        {/* Rendered only when the app asks for one. It used to default to the app's own
+            title, which meant every screen in every app carried a footer restating the
+            name already in the header and the browser tab — a permanent strip of chrome
+            nobody chose, costing vertical space on exactly the small viewports that have
+            least of it. `footer` is now the switch: pass content to get a footer, pass
+            nothing to get none. The landmark goes with it, which is correct — an empty
+            `contentinfo` is a landmark a screen-reader user can navigate to and find
+            nothing in. */}
+        {footer !== undefined && (
+          <footer data-terp="appshell-footer">{footer}</footer>
+        )}
       </div>
     </div>
   );

package/src/ConfirmDialog.tsx CHANGED Viewed

@@ -3,8 +3,8 @@ import type { ReactNode } from "react";
 import { Button } from "./ui/Button";
 import { injectTerpStyles } from "./styles";
-import { useStrings, useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useStrings, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 injectTerpStyles();
@@ -18,7 +18,7 @@ export interface ConfirmDialogProps {
   /** Short question — what is about to happen. */
   title: UiText;
   /** Optional consequence explanation. */
-  description?: ReactNode;
+  description?: UiTextNode;
   /** Confirm-button label; defaults to the `confirm` string. */
   confirmLabel?: UiText;
   /** Cancel-button label; defaults to the `cancel` string. */
@@ -118,7 +118,7 @@ export function ConfirmDialog({
         </h2>
         {description !== undefined && (
           <div id={descriptionId} data-terp="dialog-description">
-            {description}
+            {resolveUiTextNode(description, resolve)}
           </div>
         )}
         <div data-terp="dialog-actions">

package/src/EmptyState.test.tsx ADDED Viewed

@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { EmptyState } from "./EmptyState";
+afterEach(cleanup);
+describe("EmptyState size", () => {
+  it("stamps no attribute at the default size", () => {
+    // The full-page block's geometry IS the base rule, so the default matches no
+    // attribute selector — the same shape Button's sizes and the shell's density take.
+    render(<EmptyState title="Nothing yet" />);
+    expect(screen.getByText("Nothing yet").closest("[data-terp='empty-state']")).not.toHaveAttribute(
+      "data-size",
+    );
+  });
+  it("stamps compact, and keeps the frame and the wording", () => {
+    // Two default blocks stacked on one screen were 480px of chrome repeating a sentence:
+    // the emptiness of one section is not the page's headline. Compact takes the space back
+    // without changing what the block says or that it is recognisably an empty state.
+    render(
+      <EmptyState size="compact" title="No connections" description="Add one to begin." />,
+    );
+    const block = screen.getByText("No connections").closest("[data-terp='empty-state']");
+    expect(block).toHaveAttribute("data-size", "compact");
+    expect(screen.getByText("Add one to begin.")).toBeInTheDocument();
+  });
+});

package/src/EmptyState.tsx CHANGED Viewed

@@ -2,8 +2,8 @@ import type { ReactNode } from "react";
 import { Icon } from "./icons";
 import { injectTerpStyles } from "./styles";
-import { useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 injectTerpStyles();
@@ -16,9 +16,20 @@ export interface EmptyStateProps {
   /** Short title — what is missing. */
   title: UiText;
   /** Optional explanation — why it's missing, or what to do next. */
-  description?: ReactNode;
+  description?: UiTextNode;
   /** Optional call to action (typically a `Button`). */
   action?: ReactNode;
+  /**
+   * `"compact"` for an empty block that is not the whole screen.
+   *
+   * The default is sized to be the only thing on a page — generous padding, a 2rem
+   * glyph, centred. That is right for an empty list and wrong the moment a screen has two
+   * of them: stacked, they were 480px of chrome repeating a sentence, and the emptiness of
+   * one section is not the page's headline. Compact keeps the frame and the wording and
+   * takes back the space — tighter padding, a smaller glyph, left-aligned, because a
+   * block that is one item among several reads as a row rather than a poster.
+   */
+  size?: "default" | "compact";
 }
 /**
@@ -27,20 +38,32 @@ export interface EmptyStateProps {
  * UX platform-wide tells the user "this is not an error — there is just nothing to show",
  * and the `action` slot turns the dead end into the obvious next step.
  */
-export function EmptyState({ icon, title, description, action }: EmptyStateProps) {
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  size = "default",
+}: EmptyStateProps) {
   const resolve = useUiText();
+  const compact = size === "compact";
   const leading = icon ?? (
     <span data-terp="empty-state-icon">
-      <Icon name="inbox" size="2rem" />
+      <Icon name="inbox" size={compact ? "1.25rem" : "2rem"} />
     </span>
   );
+  // Stamped only for `compact`: the full-page block's geometry IS the base rule, the same
+  // shape `Button`'s sizes and the shell's density take.
   return (
-    <div data-terp="empty-state">
+    <div data-terp="empty-state" data-size={compact ? "compact" : undefined}>
       {leading}
       <p data-terp="empty-state-title">{resolve(title)}</p>
-      {description !== undefined && <div data-terp="empty-state-description">{description}</div>}
+      {description !== undefined && (
+        <div data-terp="empty-state-description">
+          {resolveUiTextNode(description, resolve)}
+        </div>
+      )}
       {action}
     </div>
   );
 }

package/src/ErrorState.tsx CHANGED Viewed

@@ -3,8 +3,8 @@ import type { ReactNode } from "react";
 import { useErrorMessage } from "./errorMessages";
 import { Icon } from "./icons";
 import { injectTerpStyles } from "./styles";
-import { useStrings, useUiText } from "./uiText";
-import type { UiText } from "./uiText";
+import { resolveUiTextNode, useStrings, useUiText } from "./uiText";
+import type { UiText, UiTextNode } from "./uiText";
 injectTerpStyles();
@@ -43,7 +43,7 @@ export interface ErrorStateProps {
    * copy for the error's stable `code` (see `useErrorMessage`), falling back to
    * {@link describeError}, so the platform error envelope surfaces consistently.
    */
-  description?: ReactNode;
+  description?: UiTextNode;
   /** The caught failure — used to derive `description` when none is given. */
   error?: unknown;
   /** Optional call to action (typically a retry `Button`). */
@@ -73,7 +73,11 @@ export function ErrorState({ icon, title, description, error, action }: ErrorSta
     <div role="alert" data-terp="error-state">
       {leading}
       <p data-terp="error-state-title">{resolve(title ?? strings.errorTitle)}</p>
-      {message !== null && message !== undefined && <div data-terp="error-state-description">{message}</div>}
+      {message !== null && message !== undefined && (
+        <div data-terp="error-state-description">
+          {resolveUiTextNode(message, resolve)}
+        </div>
+      )}
       {action}
     </div>
   );

package/src/Field.test.tsx CHANGED Viewed

@@ -3,6 +3,7 @@ import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 import { Field } from "./Field";
+import { UiTextProvider } from "./uiText";
 import { Input } from "./ui/Input";
 import { Select } from "./ui/Select";
 import { Textarea } from "./ui/Textarea";
@@ -10,6 +11,25 @@ import { Textarea } from "./ui/Textarea";
 afterEach(cleanup);
 describe("Field", () => {
+  it("resolves a descriptor used as helper text", () => {
+    render(
+      <UiTextProvider
+        resolveText={(text) =>
+          typeof text === "string" ? text : `translated:${text.id}`
+        }
+      >
+        <Field
+          label="Email"
+          hint={{ id: "account.email.hint", message: "We never share it" }}
+        >
+          <Input />
+        </Field>
+      </UiTextProvider>,
+    );
+    expect(screen.getByText("translated:account.email.hint")).toBeInTheDocument();
+  });
   it("labels its control (accessible association) and shows hint + error", () => {
     render(
       <Field label="Email" hint="we never share it" error="required">

package/src/Field.tsx CHANGED Viewed

@@ -15,7 +15,7 @@ export interface FieldProps {
   /** A field-level error (e.g. mapped from a 422), shown under the control. */
   error?: string | null;
   /** Optional helper text under the control. */
-  hint?: string;
+  hint?: UiText;
 }
 /**
@@ -90,7 +90,7 @@ export function Field({ label, children, error, hint }: FieldProps) {
       </label>
       {hint !== undefined && (
         <span id={hintId} data-terp="field-hint">
-          {hint}
+          {resolve(hint)}
         </span>
       )}
       {hasError && (

package/src/LoginView.test.tsx CHANGED Viewed

@@ -51,7 +51,39 @@ describe("LoginView dev credentials", () => {
       </TerpProvider>,
     );
     fireEvent.click(await screen.findByRole("button", { name: "Fill dev credentials" }));
-    expect(screen.getByPlaceholderText("Email")).toHaveValue("admin@example.test");
-    expect(screen.getByPlaceholderText("Password")).toHaveValue("correct horse battery staple");
+    // By label, not by placeholder. Reaching for a placeholder here was itself a symptom:
+    // it was the only handle these inputs had.
+    expect(screen.getByLabelText("Email")).toHaveValue("admin@example.test");
+    expect(screen.getByLabelText("Password")).toHaveValue("correct horse battery staple");
+  });
+});
+describe("LoginView accessible names", () => {
+  it("labels both credentials so they survive typing and can be addressed by name", async () => {
+    // The first screen of every Terp app, and it was labelled by placeholder alone. A
+    // placeholder is not an accessible name and it disappears the moment someone types, so
+    // the field a user is halfway through filling had nothing identifying it (WCAG 3.3.2)
+    // — and `getByLabel` could not find either input, which made the one screen every app
+    // ships the one screen its own tests could not address by name.
+    stubFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LoginView />
+      </TerpProvider>,
+    );
+    await screen.findByRole("heading", { name: "Sign in" });
+    const email = screen.getByLabelText("Email");
+    const password = screen.getByLabelText("Password");
+    expect(email).toHaveAttribute("type", "email");
+    expect(password).toHaveAttribute("type", "password");
+    // The name has to survive typing, which is the whole difference from a placeholder.
+    fireEvent.change(email, { target: { value: "someone@example.test" } });
+    expect(screen.getByLabelText("Email")).toHaveValue("someone@example.test");
+    // And the autocomplete tokens stay, so a password manager still offers to fill.
+    expect(email).toHaveAttribute("autocomplete", "username");
+    expect(password).toHaveAttribute("autocomplete", "current-password");
   });
 });

package/src/LoginView.tsx CHANGED Viewed

@@ -3,8 +3,9 @@ import type { FormEvent } from "react";
 import { TerpMark } from "./icons";
 import { useAuth, useSso } from "./TerpProvider";
-import { useStrings } from "./uiText";
+import { useStrings, useUiText } from "./uiText";
 import { Button } from "./ui/Button";
+import { Field } from "./Field";
 import { Input } from "./ui/Input";
 import type { SsoProvider } from "./sso";
@@ -52,6 +53,7 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
   const auth = useAuth();
   const sso = useSso();
   const strings = useStrings();
+  const resolve = useUiText();
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
   const [error, setError] = useState<string | null>(null);
@@ -92,24 +94,35 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
           <h1 data-terp="login-title">{strings.signIn}</h1>
         </div>
         <form data-terp="login-form" onSubmit={onSubmit}>
-          <Input
-            type="email"
-            // Neither field declared an autocomplete token, so no password manager offered to
-            // fill or save this form — the one place in the framework where that matters most.
-            autoComplete="username"
-            placeholder={strings.email}
-            value={email}
-            onChange={(event) => setEmail(event.target.value)}
-            required
-          />
-          <Input
-            type="password"
-            autoComplete="current-password"
-            placeholder={strings.password}
-            value={password}
-            onChange={(event) => setPassword(event.target.value)}
-            required
-          />
+          {/* Labelled through `Field`, not by placeholder. A placeholder is not an
+              accessible name and it disappears the moment someone types, so the field a
+              user is halfway through filling has nothing identifying it — WCAG 3.3.2 asks
+              for a label that survives typing. It also made these two inputs unreachable
+              by `getByLabel`, so every app's very first screen was the one place its own
+              tests could not address by name. The framework's own answer was already here:
+              `Field` wraps the control in a `<label>`, which is why it needs no id wiring.
+              The comment below is left because it dates the omission — an autocomplete
+              token was considered for these fields and a label was not. */}
+          <Field label={strings.email}>
+            <Input
+              type="email"
+              // Neither field declared an autocomplete token, so no password manager offered to
+              // fill or save this form — the one place in the framework where that matters most.
+              autoComplete="username"
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+              required
+            />
+          </Field>
+          <Field label={strings.password}>
+            <Input
+              type="password"
+              autoComplete="current-password"
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+              required
+            />
+          </Field>
           <Button type="submit" fullWidth loading={busy}>
             {busy ? strings.signingIn : strings.signIn}
           </Button>
@@ -146,7 +159,7 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
                   disabled={busy}
                   onClick={() => void onSso(provider)}
                 >
-                  {`${strings.continueWith} ${provider.label ?? provider.name}`}
+                  {`${strings.continueWith} ${resolve(provider.label ?? provider.name)}`}
                 </Button>
               ))}
             </div>

package/src/UserMenu.test.tsx CHANGED Viewed

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { TerpProvider, useAuth } from "./TerpProvider";
 import { UserMenu, userInitials } from "./UserMenu";
-import { LOCALE_EN, LocaleProvider } from "./locale";
+import { LOCALE_EN, LOCALE_NL, LocaleProvider } from "./locale";
 import { ThemeProvider } from "./theme";
 function jsonResponse(body: unknown): Response {
@@ -73,7 +73,7 @@ describe("UserMenu", () => {
     stubAuthFetch();
     render(
       <ThemeProvider>
-        <LocaleProvider locales={{ en: LOCALE_EN, nl: { label: "Nederlands" } }}>
+        <LocaleProvider locales={{ en: LOCALE_EN, nl: LOCALE_NL }}>
           <TerpProvider baseUrl="https://api.test">
             <LogInOnMount />
             <UserMenu />

package/src/bootstrap.tsx CHANGED Viewed

@@ -2,7 +2,7 @@ import { RouterProvider } from "@tanstack/react-router";
 import { StrictMode } from "react";
 import type { ComponentType, ReactNode } from "react";
 import { createRoot } from "react-dom/client";
-import type { ModuleManifest, NavGroup } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup, UiText } from "@terpjs/contract";
 import { LoginView } from "./LoginView";
 import type { DevCredentials } from "./LoginView";
@@ -95,7 +95,7 @@ export function collectModules(modules: Record<string, unknown>): {
 export interface RenderTerpAppOptions {
   /** App title shown in the shell's sidebar brand (and the default footer). */
-  title: string;
+  title: UiText;
   /** Discovered modules from an import.meta.glob over "./modules/<name>/module.tsx" (eager). */
   modules: Record<string, unknown>;
   /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
@@ -187,6 +187,8 @@ export interface RenderTerpAppOptions {
   locales?: Record<string, LocaleCatalog>;
   /** Starting locale when the user has not chosen one; default: the first `locales` key. */
   defaultLocale?: string;
+  /** Source locale for app-authored UiText descriptors; default: the first locale key. */
+  sourceLocale?: string;
   /**
    * Starting theme when the user has not chosen one; default `"system"` (OS preference).
    *
@@ -362,6 +364,7 @@ export function renderTerpApp(options: RenderTerpAppOptions): void {
         <LocaleProvider
           locales={options.locales ?? { en: {} }}
           defaultLocale={options.defaultLocale}
+          sourceLocale={options.sourceLocale}
         >
           <TerpProvider baseUrl={options.baseUrl ?? ""} ssoCallbackPath={options.ssoCallbackPath}>
             <ToastProvider>