@terpjs/react-core 0.1.0

package/src/locale.tsx

@@ -0,0 +1,246 @@
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+
+import { Icon } from "./icons";
+import { Menu, MenuItem } from "./ui/Menu";
+import { UiTextProvider, useStrings } from "./uiText";
+import type { TerpStrings } from "./uiText";
+
+/**
+ * One locale's catalog: per-key overrides of the framework strings (missing keys fall
+ * back to the bundled English defaults) plus an optional native display name for
+ * language pickers. `{}` is a valid catalog — English needs no overrides.
+ */
+export interface LocaleCatalog {
+  /** Native display name shown by {@link LanguageSwitcher} (default: the locale code). */
+  label?: string;
+  /** Framework-string overrides for this locale. */
+  strings?: Partial<TerpStrings>;
+}
+
+/** The built-in English catalog — the bundled defaults, no overrides needed. */
+export const LOCALE_EN: LocaleCatalog = { label: "English" };
+
+/**
+ * The built-in Dutch catalog: a complete translation of every framework string,
+ * so `locales: { en: LOCALE_EN, nl: LOCALE_NL }` localises the whole chrome out
+ * of the box (a completeness test pins it to the `TerpStrings` key set).
+ */
+export const LOCALE_NL: LocaleCatalog = {
+  label: "Nederlands",
+  strings: {
+    loading: "Laden...",
+    emptyList: "Nog niets te zien.",
+    add: "Toevoegen",
+    signOut: "Uitloggen",
+    signIn: "Inloggen",
+    signingIn: "Bezig met inloggen…",
+    email: "E-mailadres",
+    password: "Wachtwoord",
+    signInFailed: "Inloggen mislukt. Controleer je gegevens.",
+    fillDevCredentials: "Vul dev-inloggegevens in",
+    continueWith: "Doorgaan met",
+    orSeparator: "of",
+    ssoFailed: "Single sign-on mislukt. Probeer het opnieuw.",
+    uploadFile: "Bestand uploaden",
+    uploading: "Uploaden…",
+    unauthorized: "Je hebt geen toegang tot deze pagina.",
+    breadcrumbsLabel: "Kruimelpad",
+    moduleNavigationLabel: "Modulenavigatie",
+    moreActions: "Meer acties",
+    errorTitle: "Er is iets misgegaan.",
+    confirm: "Bevestigen",
+    cancel: "Annuleren",
+    successTitle: "Gelukt",
+    warningTitle: "Let op",
+    dismiss: "Sluiten",
+    accountMenu: "Accountmenu",
+    settings: "Instellingen",
+    profile: "Profiel",
+    role: "Rol",
+    home: "Start",
+    primaryNavigationLabel: "Hoofdnavigatie",
+    collapseSidebar: "Zijbalk inklappen",
+    expandSidebar: "Zijbalk uitklappen",
+    openNavigation: "Navigatie openen",
+    closeNavigation: "Navigatie sluiten",
+    theme: "Thema",
+    themeLight: "Licht",
+    themeDark: "Donker",
+    themeSystem: "Systeem",
+    language: "Taal",
+    admin: "Beheer",
+    adminUsers: "Gebruikers",
+    adminUsersDescription: "Accounts aanmaken, rollen wijzigen, wachtwoorden resetten",
+    adminGroups: "Groepen",
+    adminGroupsDescription: "Bundel permissies; lidmaatschap past ze toe",
+    adminAudit: "Auditlog",
+    adminAuditDescription: "Elke wijziging: wat, wie, wanneer",
+    statusColumn: "Status",
+    createdColumn: "Aangemaakt",
+    statusActive: "Actief",
+    statusDeactivated: "Gedeactiveerd",
+    provisionUser: "Gebruiker aanmaken",
+    roleViewer: "Lezer",
+    roleEditor: "Redacteur",
+    roleAdmin: "Beheerder",
+    working: "Bezig…",
+    makeRole: "Maak {role}",
+    resetPassword: "Wachtwoord resetten",
+    newPassword: "Nieuw wachtwoord",
+    deactivate: "Deactiveren",
+    reactivate: "Heractiveren",
+    changeRoleConfirm: "De rol van deze gebruiker wijzigen naar {role}?",
+    deactivateUserConfirm: "Dit account deactiveren? Actieve sessies worden ingetrokken.",
+    reactivateUserConfirm: "Dit account heractiveren?",
+    groupName: "Naam",
+    description: "Omschrijving",
+    members: "Leden",
+    createGroup: "Groep aanmaken",
+    deleteGroup: "Groep verwijderen",
+    deleteGroupConfirm: "Deze groep verwijderen? Lidmaatschappen en permissies gaan mee.",
+    addMember: "Lid toevoegen",
+    removeMember: "Verwijderen",
+    removeMemberConfirm: "Dit lid uit de groep verwijderen?",
+    userField: "Gebruiker",
+    userNotFound: "Geen account gevonden met dat e-mailadres.",
+    permissions: "Permissies",
+    grantPermission: "Permissie toekennen",
+    permission: "Permissie",
+    revoke: "Intrekken",
+    revokeConfirm: "Deze permissie van de groep intrekken?",
+    actionColumn: "Actie",
+    actorColumn: "Uitvoerder",
+    targetColumn: "Doel",
+    whenColumn: "Wanneer",
+    details: "Details",
+    saved: "Opgeslagen",
+    requestFailed: "Het verzoek is mislukt. Probeer opnieuw.",
+  },
+};
+
+/** The `localStorage` key {@link LocaleProvider} persists the choice under. */
+export const LOCALE_STORAGE_KEY = "terp.locale";
+
+interface LocaleContextValue {
+  locale: string;
+  locales: readonly string[];
+  labelOf: (locale: string) => string;
+  setLocale: (locale: string) => void;
+}
+
+const LocaleContext = createContext<LocaleContextValue | null>(null);
+
+export interface LocaleProviderProps {
+  /** The app's locales, keyed by BCP-47 code (e.g. `{ en: LOCALE_EN, nl: {...} }`). */
+  locales: Record<string, LocaleCatalog>;
+  /** Starting locale when the user has not chosen one; default: the first key. */
+  defaultLocale?: string;
+  children: ReactNode;
+}
+
+/**
+ * The language seam over {@link UiTextProvider}: owns which locale is active, persists
+ * the choice in `localStorage`, and feeds the active catalog's string overrides to the
+ * `UiText` context — so every react-core component (and every `UiText` prop) follows the
+ * switch with no per-component wiring. Adding a language to an app is one catalog entry.
+ */
+export function LocaleProvider({ locales, defaultLocale, children }: LocaleProviderProps) {
+  const codes = Object.keys(locales);
+  const fallback = defaultLocale !== undefined && codes.includes(defaultLocale)
+    ? defaultLocale
+    : codes[0];
+  const [locale, setLocaleState] = useState<string>(() => {
+    try {
+      const stored = window.localStorage.getItem(LOCALE_STORAGE_KEY);
+      return stored !== null && codes.includes(stored) ? stored : (fallback ?? "en");
+    } catch {
+      return fallback ?? "en";
+    }
+  });
+
+  const setLocale = useCallback(
+    (next: string) => {
+      if (!codes.includes(next)) {
+        return;
+      }
+      setLocaleState(next);
+      try {
+        window.localStorage.setItem(LOCALE_STORAGE_KEY, next);
+      } catch {
+        // Private mode / quota: the choice still applies for this session.
+      }
+    },
+    [codes.join("\u0000")],
+  );
+
+  const value = useMemo<LocaleContextValue>(
+    () => ({
+      locale,
+      locales: codes,
+      labelOf: (code) => locales[code]?.label ?? code,
+      setLocale,
+    }),
+    [locale, codes.join("\u0000"), setLocale, locales],
+  );
+
+  return (
+    <LocaleContext.Provider value={value}>
+      <UiTextProvider strings={locales[locale]?.strings}>{children}</UiTextProvider>
+    </LocaleContext.Provider>
+  );
+}
+
+/** The active locale + the catalog codes + setter, or `null` outside a {@link LocaleProvider}. */
+export function useLocale(): LocaleContextValue | null {
+  return useContext(LocaleContext);
+}
+
+export interface LanguageSwitcherProps {
+  /**
+   * `"stacked"` (default) renders a labelled icon menu for settings panels;
+   * `"inline"` renders only the compact icon trigger used by the shell header.
+   */
+  variant?: "stacked" | "inline";
+}
+
+/**
+ * The standard language control: a token-themed menu over the app's locale catalogs.
+ * Renders nothing outside a {@link LocaleProvider} or when only one locale is declared,
+ * so shared chrome (the shell header) can include it unconditionally.
+ */
+export function LanguageSwitcher({ variant = "stacked" }: LanguageSwitcherProps) {
+  const context = useLocale();
+  const strings = useStrings();
+  if (context === null || context.locales.length < 2) {
+    return null;
+  }
+  const menu = (
+    <Menu trigger={<Icon name="globe" size="1.15rem" />} triggerLabel={strings.language}>
+      {({ close }) => (
+        <>
+          {context.locales.map((code) => (
+            <MenuItem
+              key={code}
+              label={context.labelOf(code)}
+              selected={code === context.locale}
+              onSelect={() => {
+                context.setLocale(code);
+                close(true);
+              }}
+            />
+          ))}
+        </>
+      )}
+    </Menu>
+  );
+  if (variant === "inline") {
+    return menu;
+  }
+  return (
+    <div style={{ display: "grid", justifyItems: "start", gap: "var(--space-1)", fontSize: "var(--font-size-sm)" }}>
+      <span style={{ color: "var(--color-neutral-600)" }}>{strings.language}</span>
+      {menu}
+    </div>
+  );
+}

package/src/nav.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import type { ModuleManifest } from "@terpjs/contract";
+
+import { visibleNav } from "./nav";
+
+const manifests: ModuleManifest[] = [
+  { name: "notes", routes: [], nav: [{ label: "Notes", to: "/notes" }] },
+  { name: "admin", routes: [], nav: [{ label: "Users", to: "/users", role: "admin" }] },
+  { name: "noNav", routes: [] },
+];
+
+describe("visibleNav", () => {
+  it("flattens nav across manifests when everything is visible", () => {
+    expect(visibleNav(manifests, () => true).map((i) => i.to)).toEqual(["/notes", "/users"]);
+  });
+
+  it("filters items by their required role", () => {
+    const onlyPublic = visibleNav(manifests, (role) => role === undefined);
+    expect(onlyPublic.map((i) => i.to)).toEqual(["/notes"]);
+  });
+});

package/src/nav.ts

@@ -0,0 +1,13 @@
+import type { ModuleManifest, NavItem } from "@terpjs/contract";
+
+/**
+ * Flatten the nav of every module manifest into one ordered sidebar list, keeping only
+ * the items the current user may see. `canSeeRole(role)` decides visibility for an item's
+ * required role (an item with no `role` is visible to any authenticated user).
+ */
+export function visibleNav(
+  manifests: readonly ModuleManifest[],
+  canSeeRole: (role: string | undefined) => boolean,
+): NavItem[] {
+  return manifests.flatMap((manifest) => manifest.nav ?? []).filter((item) => canSeeRole(item.role));
+}

package/src/pageMarker.ts

@@ -0,0 +1,15 @@
+import { createContext, useContext } from "react";
+
+/**
+ * The runtime half of the "every routed view is a page archetype" control. The router's route
+ * wrapper provides a marker callback; {@link Page} (which `OverviewPage` / `DetailPage` /
+ * `HubPage` all compose) invokes it during render. After mount the wrapper checks the mark and
+ * fails closed on a routed view that skipped the archetypes — so every screen keeps the frame
+ * (breadcrumbs, one `h1`, the loading/error slots) even if a lint were bypassed.
+ */
+export const PageMarkerContext = createContext<(() => void) | null>(null);
+
+/** The marker callback for the current routed view, or null outside a routed view. */
+export function usePageMarker(): (() => void) | null {
+  return useContext(PageMarkerContext);
+}

package/src/raw.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal Node file access for the token guard test only — the package keeps
+ * `"types": []` so component source never sees ambient Node globals.
+ */
+declare module "node:fs" {
+  export function readFileSync(path: URL | string, encoding: "utf-8"): string;
+}

package/src/realtime-hook.test.tsx

@@ -0,0 +1,226 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  post: vi.fn(),
+  client: null as unknown as { POST: ReturnType<typeof vi.fn> },
+}));
+mocks.client = { POST: mocks.post };
+
+vi.mock("./TerpProvider", () => ({
+  useTerpBaseUrl: () => "https://api.example.test",
+  useTerpClient: () => mocks.client,
+}));
+
+import { useRealtimeChannel } from "./realtime";
+
+interface Notice {
+  sequence: number;
+  text: string;
+}
+
+const isNotice = (value: unknown): value is Notice => {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record.sequence === "number" && typeof record.text === "string";
+};
+
+class EventSourceDouble {
+  static instances: EventSourceDouble[] = [];
+
+  readonly url: string;
+  closed = false;
+  onopen: ((event: Event) => void) | null = null;
+  onmessage: ((event: MessageEvent<string>) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+
+  constructor(url: string | URL) {
+    this.url = String(url);
+    EventSourceDouble.instances.push(this);
+  }
+
+  close() {
+    this.closed = true;
+  }
+}
+
+class WebSocketDouble {
+  static readonly OPEN = 1;
+  static instances: WebSocketDouble[] = [];
+
+  readonly url: string;
+  readyState = WebSocketDouble.OPEN;
+  onopen: ((event: Event) => void) | null = null;
+  onmessage: ((event: MessageEvent<string>) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+  onclose: ((event: CloseEvent) => void) | null = null;
+
+  constructor(url: string | URL) {
+    this.url = String(url);
+    WebSocketDouble.instances.push(this);
+  }
+
+  send() {}
+
+  close() {
+    this.readyState = 3;
+  }
+}
+
+afterEach(() => {
+  cleanup();
+  mocks.post.mockReset();
+  EventSourceDouble.instances = [];
+  WebSocketDouble.instances = [];
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("useRealtimeChannel lifecycle", () => {
+  it("does not open a transport when closed while ticket mint is pending", async () => {
+    let resolveTicket: ((value: unknown) => void) | undefined;
+    mocks.post.mockReturnValue(
+      new Promise((resolve) => {
+        resolveTicket = resolve;
+      }),
+    );
+    vi.stubGlobal("EventSource", EventSourceDouble);
+
+    const { result } = renderHook(() =>
+      useRealtimeChannel({ channel: "system.notices", validate: isNotice }),
+    );
+    await waitFor(() => expect(mocks.post).toHaveBeenCalledTimes(1));
+
+    act(() => result.current.close());
+    expect(result.current.status).toBe("closed");
+
+    await act(async () => {
+      resolveTicket?.({
+        data: {
+          ticket: "late-ticket",
+          expires_in: 30,
+          channel: "system.notices",
+          transport: "sse",
+        },
+      });
+      await Promise.resolve();
+    });
+
+    expect(EventSourceDouble.instances).toHaveLength(0);
+    expect(result.current.status).toBe("closed");
+  });
+
+  it("closes a failed SSE source and remints its one-use ticket", async () => {
+    vi.useFakeTimers();
+    mocks.post
+      .mockResolvedValueOnce({
+        data: {
+          ticket: "ticket-one",
+          expires_in: 30,
+          channel: "system.notices",
+          transport: "sse",
+        },
+      })
+      .mockResolvedValueOnce({
+        data: {
+          ticket: "ticket-two",
+          expires_in: 30,
+          channel: "system.notices",
+          transport: "sse",
+        },
+      });
+    vi.stubGlobal("EventSource", EventSourceDouble);
+
+    const { result } = renderHook(() =>
+      useRealtimeChannel({ channel: "system.notices", validate: isNotice }),
+    );
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(EventSourceDouble.instances).toHaveLength(1);
+    expect(EventSourceDouble.instances[0].url).toContain("ticket=ticket-one");
+
+    act(() => EventSourceDouble.instances[0].onerror?.(new Event("error")));
+    expect(EventSourceDouble.instances[0].closed).toBe(true);
+    expect(result.current.status).toBe("error");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+
+    expect(mocks.post).toHaveBeenCalledTimes(2);
+    expect(EventSourceDouble.instances).toHaveLength(2);
+    expect(EventSourceDouble.instances[1].url).toContain("ticket=ticket-two");
+
+    act(() =>
+      EventSourceDouble.instances[0].onmessage?.(
+        new MessageEvent("message", {
+          data: '{"sequence":1,"text":"stale"}',
+        }),
+      ),
+    );
+    expect(result.current.lastMessage).toBeNull();
+
+    act(() =>
+      EventSourceDouble.instances[1].onmessage?.(
+        new MessageEvent("message", {
+          data: '{"sequence":2,"text":"fresh"}',
+        }),
+      ),
+    );
+    expect(result.current.lastMessage).toEqual({ sequence: 2, text: "fresh" });
+  });
+
+  it("remints after a remote WebSocket close until the caller closes", async () => {
+    vi.useFakeTimers();
+    mocks.post
+      .mockResolvedValueOnce({
+        data: {
+          ticket: "socket-one",
+          expires_in: 30,
+          channel: "personal.updates",
+          transport: "websocket",
+        },
+      })
+      .mockResolvedValueOnce({
+        data: {
+          ticket: "socket-two",
+          expires_in: 30,
+          channel: "personal.updates",
+          transport: "websocket",
+        },
+      });
+    vi.stubGlobal("WebSocket", WebSocketDouble);
+
+    const { result } = renderHook(() =>
+      useRealtimeChannel({
+        channel: "personal.updates",
+        transport: "websocket",
+        validate: isNotice,
+      }),
+    );
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(WebSocketDouble.instances).toHaveLength(1);
+
+    act(() =>
+      WebSocketDouble.instances[0].onclose?.(
+        new CloseEvent("close", { code: 1000 }),
+      ),
+    );
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+    expect(mocks.post).toHaveBeenCalledTimes(2);
+    expect(WebSocketDouble.instances).toHaveLength(2);
+
+    act(() => result.current.close());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(30_000);
+    });
+    expect(result.current.status).toBe("closed");
+    expect(mocks.post).toHaveBeenCalledTimes(2);
+  });
+});

package/src/realtime.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import { parseMessage, transportUrl, useRealtimeChannel } from "./realtime";
+
+interface Notice {
+  sequence: number;
+  text: string;
+}
+
+const isNotice = (value: unknown): value is Notice => {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record.sequence === "number" && typeof record.text === "string";
+};
+
+describe("realtime transport contract", () => {
+  it("derives SSE and WebSocket URLs from the provider base URL with an opaque ticket", () => {
+    expect(
+      transportUrl("https://api.example.test/base", "sse", "notes.changed", "ticket value"),
+    ).toBe(
+      "https://api.example.test/api/v1/realtime/sse/notes.changed?ticket=ticket+value",
+    );
+    expect(
+      transportUrl("https://api.example.test", "websocket", "notes/live", "opaque"),
+    ).toBe(
+      "wss://api.example.test/api/v1/realtime/ws/notes%2Flive?ticket=opaque",
+    );
+  });
+
+  it("parses only JSON that passes the channel's runtime type guard", () => {
+    expect(parseMessage('{"sequence":1,"text":"hello"}', isNotice)).toEqual({
+      sequence: 1,
+      text: "hello",
+    });
+    expect(() => parseMessage("not json", isNotice)).toThrow(/invalid JSON/);
+    expect(() => parseMessage('{"sequence":"one"}', isNotice)).toThrow(
+      /outside its declared type/,
+    );
+  });
+
+  it("exports the sanctioned hook", () => {
+    expect(typeof useRealtimeChannel).toBe("function");
+  });
+});