@terpjs/react-core 0.9.0 → 0.11.0

package/src/ui/Tabs.test.tsx

@@ -27,3 +27,31 @@ describe("Tabs", () => {
     expect(onChange).toHaveBeenCalledWith("audit");
   });
 });
+
+describe("Tabs with a single tab", () => {
+  it("renders the content bare, with no tablist to choose from", () => {
+    // A tab set over one tab costs a row of the screen to offer nothing, and to a screen
+    // reader it is worse than decorative: it announces "tab 1 of 1" and the only
+    // affordance is already selected.
+    render(<Tabs label="Sections" tabs={[{ value: "only", label: "Only", content: "Body" }]} />);
+    expect(screen.queryByRole("tablist")).toBeNull();
+    expect(screen.queryByRole("tab")).toBeNull();
+    // The panel goes too: a tabpanel exists to be labelled by the tab that reveals it, and
+    // there is nothing left to reveal.
+    expect(screen.queryByRole("tabpanel")).toBeNull();
+    expect(screen.getByText("Body")).toBeInTheDocument();
+  });
+
+  it("keeps the chrome when that single tab is disabled", () => {
+    // Here the tab set carries real information — this section exists and is unavailable —
+    // and rendering its content bare would show what the caller marked unreachable.
+    render(
+      <Tabs
+        label="Sections"
+        tabs={[{ value: "only", label: "Only", content: "Body", disabled: true }]}
+      />,
+    );
+    expect(screen.getByRole("tablist")).toBeInTheDocument();
+    expect(screen.getByRole("tab", { name: "Only" })).toBeDisabled();
+  });
+});

package/src/ui/Tabs.tsx

@@ -31,6 +31,26 @@ export function Tabs({ tabs, value, defaultValue, onChange, label }: TabsProps)
   const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? firstValue);
   const selectedValue = value ?? uncontrolledValue;
   const selectedTab = tabs.find((tab) => tab.value === selectedValue) ?? enabledTabs[0] ?? tabs[0];
+  // Element ids are built from the tab's INDEX, never from its `value`. A value is caller data
+  // and an id is an IDREF: a value containing whitespace turns `aria-labelledby` into a list of
+  // two tokens, neither of which resolves, and the tabpanel silently loses its accessible name.
+  // Nothing reports that — axe sees a well-formed reference to nothing. The same refusal to
+  // interpolate caller strings into ids is written out at AppShell's nav-group labels.
+  const selectedIndex = tabs.findIndex((tab) => tab.value === selectedTab?.value);
+
+  // One usable tab is not a choice, so it gets no chrome. A tablist over a single tab costs
+  // a row of the screen to offer nothing, and it is worse than decorative to a screen
+  // reader: the set announces "tab 1 of 1" and the only affordance is already selected.
+  // Rendering the content bare also drops the tabpanel, which is correct rather than
+  // convenient — a panel exists to be labelled by the tab that reveals it, and there is
+  // no revealing left to do.
+  //
+  // A single DISABLED tab keeps the chrome, deliberately: there the tab set is carrying
+  // real information (this section exists and is unavailable), and silently rendering its
+  // content would show what the caller marked unreachable.
+  if (tabs.length === 1 && !tabs[0]?.disabled) {
+    return <>{tabs[0]?.content}</>;
+  }
 
   function select(next: string) {
     if (value === undefined) {
@@ -62,24 +82,28 @@ export function Tabs({ tabs, value, defaultValue, onChange, label }: TabsProps)
     const next = enabledTabs[nextIndex];
     if (next) {
       select(next.value);
-      document.getElementById(`${baseId}-tab-${next.value}`)?.focus();
+      // Looked up by the tab's position in `tabs`, matching the id it was rendered with.
+      // `enabledTabs` is a filtered view, so its index is not the rendered one.
+      document
+        .getElementById(`${baseId}-tab-${tabs.findIndex((tab) => tab.value === next.value)}`)
+        ?.focus();
     }
   }
 
   return (
     <div data-terp="tabs">
       <div role="tablist" data-terp="tab-list" aria-label={label === undefined ? undefined : resolve(label)} onKeyDown={onKeyDown}>
-        {tabs.map((tab) => {
+        {tabs.map((tab, index) => {
           const selected = tab.value === selectedTab?.value;
           return (
             <button
               key={tab.value}
-              id={`${baseId}-tab-${tab.value}`}
+              id={`${baseId}-tab-${index}`}
               type="button"
               role="tab"
               data-terp="tab"
               aria-selected={selected}
-              aria-controls={`${baseId}-panel-${tab.value}`}
+              aria-controls={`${baseId}-panel-${index}`}
               tabIndex={selected ? 0 : -1}
               disabled={tab.disabled}
               onClick={() => select(tab.value)}
@@ -91,9 +115,9 @@ export function Tabs({ tabs, value, defaultValue, onChange, label }: TabsProps)
       </div>
       {selectedTab && (
         <div
-          id={`${baseId}-panel-${selectedTab.value}`}
+          id={`${baseId}-panel-${selectedIndex}`}
           role="tabpanel"
-          aria-labelledby={`${baseId}-tab-${selectedTab.value}`}
+          aria-labelledby={`${baseId}-tab-${selectedIndex}`}
           data-terp="tab-panel"
         >
           {selectedTab.content}

package/src/ui/Tooltip.test.tsx

@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
-import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { vi } from "vitest";
 import { afterEach, describe, expect, it } from "vitest";
 
 import { Button } from "./Button";
@@ -25,4 +26,58 @@ describe("Tooltip", () => {
     fireEvent.mouseEnter(trigger.parentElement!);
     expect(tooltip).toBeVisible();
   });
+
+  it("dismisses on Escape without moving the pointer or focus", () => {
+    // WCAG 1.4.13, Dismissible. There was no key handler of any kind, so a bubble covering the
+    // content under it could only be escaped by moving away from the control the user was
+    // reading about. Bound on the document, because the pointer-opened case has no focus
+    // anywhere near this component and a trigger-bound handler would never see the key.
+    // Mutation: delete the keydown effect.
+    render(
+      <Tooltip content="More information" defaultOpen>
+        <Button>Help</Button>
+      </Tooltip>,
+    );
+    const tooltip = screen.getByRole("tooltip");
+    expect(tooltip).toBeVisible();
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(tooltip).not.toBeVisible();
+  });
+
+  it("stays open while the pointer crosses to the bubble", () => {
+    // WCAG 1.4.13, Hoverable. The bubble used to declare pointer-events: none, which makes
+    // reaching it impossible by construction; that is gone, and the close is delayed so the
+    // visual gap between trigger and bubble can be crossed. Re-entering cancels the close.
+    // Mutation: close synchronously on mouseleave, and this fails.
+    vi.useFakeTimers();
+    try {
+      render(
+        <Tooltip content="More information" defaultOpen>
+          <Button>Help</Button>
+        </Tooltip>,
+      );
+      const tooltip = screen.getByRole("tooltip");
+      const anchor = tooltip.parentElement!;
+      fireEvent.mouseLeave(anchor);
+      // Still open partway through the grace period...
+      act(() => {
+        vi.advanceTimersByTime(60);
+      });
+      expect(tooltip).toBeVisible();
+      // ...and re-entering cancels the close entirely.
+      fireEvent.mouseEnter(anchor);
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(tooltip).toBeVisible();
+      // Leaving and staying away does close it.
+      fireEvent.mouseLeave(anchor);
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(tooltip).not.toBeVisible();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

package/src/ui/Tooltip.tsx

@@ -1,4 +1,4 @@
-import { cloneElement, isValidElement, useId, useState } from "react";
+import { cloneElement, isValidElement, useEffect, useId, useRef, useState } from "react";
 import type { FocusEvent, MouseEvent, ReactElement } from "react";
 
 import { injectTerpStyles } from "../styles";
@@ -10,6 +10,16 @@ injectTerpStyles();
 export interface TooltipProps {
   content: UiText;
   children: ReactElement;
+  /**
+   * Start with the bubble shown.
+   *
+   * The same dev/specimen affordance `AppShell.defaultCollapsed` and `defaultDrawerOpen` are,
+   * added for the same reason: the panel's whole style block — its surface, its ink, its shadow
+   * and its measure — was painted by nothing. The one Tooltip specimen renders the trigger with
+   * the bubble closed, and neither browser lane can hover or focus, so a change to any of those
+   * declarations moved no pixel that any gate reads. An app has no reason to pin a tooltip open.
+   */
+  defaultOpen?: boolean;
 }
 
 interface TriggerHandlers {
@@ -20,11 +30,60 @@ interface TriggerHandlers {
   "aria-describedby"?: string;
 }
 
-/** Accessible focus/hover tooltip. */
-export function Tooltip({ content, children }: TooltipProps) {
+/**
+ * Accessible focus/hover tooltip.
+ *
+ * Holds all three parts of WCAG 1.4.13 (Content on Hover or Focus, level AA), and two of them
+ * had to be added:
+ *
+ * - **Dismissible.** Escape closes the bubble without moving the pointer or focus. There was no
+ *   key handler of any kind before, so a tooltip covering the content beneath it could only be
+ *   escaped by moving away from the control the user was reading about.
+ * - **Hoverable.** The bubble is reachable with the pointer. It used to declare
+ *   `pointer-events: none`, which makes hovering it impossible by construction — so a tooltip
+ *   long enough to need reading could not be read by anyone tracking with a pointer or using
+ *   magnification. The bubble is a DOM child of the anchor, so moving onto it does not fire the
+ *   anchor's `mouseleave`; the close delay below covers the visual gap between the two, which
+ *   the pointer does cross.
+ * - **Persistent.** It stays until dismissed, focus leaves or the pointer leaves — it has never
+ *   had a timeout.
+ */
+export function Tooltip({ content, children, defaultOpen = false }: TooltipProps) {
   const id = useId();
   const resolve = useUiText();
-  const [open, setOpen] = useState(false);
+  const [open, setOpen] = useState(defaultOpen);
+  // Cleared on re-entry, which is what makes the gap between trigger and bubble crossable.
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  function cancelClose() {
+    if (closeTimer.current !== null) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  }
+
+  function scheduleClose() {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setOpen(false), 120);
+  }
+
+  useEffect(() => cancelClose, []);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    // On the document rather than the trigger: the pointer-opened case has no focus anywhere
+    // near this component, so a handler bound to the trigger would never see the key. The same
+    // placement Popover uses, for the same reason.
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") {
+        setOpen(false);
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open]);
 
   if (!isValidElement<TriggerHandlers>(children)) {
     return children;
@@ -33,13 +92,17 @@ export function Tooltip({ content, children }: TooltipProps) {
   return (
     <span
       data-terp="tooltip-anchor"
-      onMouseEnter={() => setOpen(true)}
-      onMouseLeave={() => setOpen(false)}
+      onMouseEnter={() => {
+        cancelClose();
+        setOpen(true);
+      }}
+      onMouseLeave={scheduleClose}
     >
       {cloneElement(children, {
         "aria-describedby": id,
         onFocus: (event: FocusEvent) => {
           children.props.onFocus?.(event);
+          cancelClose();
           setOpen(true);
         },
         onBlur: (event: FocusEvent) => {

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.tsx

@@ -40,6 +40,10 @@ export interface TerpStrings {
   email: string;
   /** Login password placeholder. */
   password: string;
+  /** Password reveal toggle, while the value is hidden. */
+  showPassword: string;
+  /** Password reveal toggle, while the value is visible. */
+  hidePassword: string;
   /** Login failure message. */
   signInFailed: string;
   /** Label of the dev-only button that fills the seeded development credentials. */
@@ -86,6 +90,8 @@ export interface TerpStrings {
   home: string;
   /** Accessible name of the sidebar `nav` landmark. */
   primaryNavigationLabel: string;
+  /** The shell's skip link — the first thing a keyboard reaches, jumping past the chrome. */
+  skipToContent: string;
   /** Accessible label of the header toggle when it collapses the expanded sidebar. */
   collapseSidebar: string;
   /** Accessible label of the header toggle when it expands the collapsed sidebar. */
@@ -204,9 +210,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",
@@ -215,6 +248,8 @@ export const DEFAULT_STRINGS: TerpStrings = {
   signingIn: "Signing in…",
   email: "Email",
   password: "Password",
+  showPassword: "Show password",
+  hidePassword: "Hide password",
   signInFailed: "Sign-in failed. Check your credentials.",
   fillDevCredentials: "Fill dev credentials",
   continueWith: "Continue with",
@@ -238,6 +273,7 @@ export const DEFAULT_STRINGS: TerpStrings = {
   role: "Role",
   home: "Home",
   primaryNavigationLabel: "Primary",
+  skipToContent: "Skip to content",
   collapseSidebar: "Collapse sidebar",
   expandSidebar: "Expand sidebar",
   openNavigation: "Open navigation",