npm - @terpjs/react-core - Versions diffs - 0.9.0 → 0.11.0 - Mend

@terpjs/react-core 0.9.0 → 0.11.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 (101) hide show

package/README.md +57 -21
package/package.json +6 -5
package/src/AppShell.test.tsx +323 -4
package/src/AppShell.tsx +401 -66
package/src/EmptyState.test.tsx +30 -0
package/src/EmptyState.tsx +23 -3
package/src/Field.test.tsx +30 -0
package/src/Field.tsx +36 -8
package/src/FormPage.tsx +54 -0
package/src/LoginView.test.tsx +34 -2
package/src/LoginView.tsx +43 -18
package/src/ModuleNav.test.tsx +17 -10
package/src/ModuleNav.tsx +35 -3
package/src/Page.tsx +23 -1
package/src/ProfileView.test.tsx +1 -1
package/src/ProfileView.tsx +2 -4
package/src/SettingsPage.tsx +50 -0
package/src/SplitPage.tsx +150 -0
package/src/UserMenu.test.tsx +28 -5
package/src/UserMenu.tsx +15 -9
package/src/admin/AuditLogAdmin.tsx +21 -7
package/src/admin/GroupCreate.tsx +17 -3
package/src/admin/GroupDetail.tsx +48 -13
package/src/admin/GroupsAdmin.tsx +13 -5
package/src/admin/UserCreate.tsx +40 -11
package/src/admin/UserDetail.tsx +4 -1
package/src/admin/UsersAdmin.tsx +14 -6
package/src/admin/admin.test.tsx +212 -8
package/src/admin/fieldErrors.ts +45 -0
package/src/bootstrap.test.tsx +208 -0
package/src/bootstrap.tsx +121 -5
package/src/breakpoints.ts +41 -0
package/src/dataview/DataView.tsx +12 -5
package/src/dataview/DataViewCardList.tsx +8 -7
package/src/dataview/DataViewPagination.tsx +15 -8
package/src/dataview/DataViewTable.tsx +32 -21
package/src/dataview/README.md +13 -2
package/src/dataview/index.ts +1 -0
package/src/dataview/internal.tsx +31 -1
package/src/dataview/types.ts +26 -3
package/src/format.test.tsx +213 -0
package/src/format.ts +150 -0
package/src/icons.tsx +67 -5
package/src/index.ts +56 -6
package/src/layout.manifest.json +118 -0
package/src/layout.manifest.test.ts +205 -0
package/src/layout.test.tsx +198 -1
package/src/layout.tsx +208 -11
package/src/layoutContract.test.tsx +311 -2
package/src/layoutContract.ts +44 -3
package/src/layoutDeclaration.test.ts +435 -0
package/src/layoutDeclaration.ts +531 -0
package/src/locale.tsx +12 -0
package/src/markers.test.ts +27 -5
package/src/nav.test.ts +234 -4
package/src/nav.ts +180 -6
package/src/navActive.test.ts +115 -0
package/src/navActive.ts +119 -0
package/src/navLink.tsx +20 -2
package/src/previewBridge.test.ts +327 -0
package/src/previewBridge.ts +278 -0
package/src/raw.d.ts +14 -2
package/src/review.test.tsx +272 -0
package/src/router.test.tsx +575 -2
package/src/router.tsx +212 -19
package/src/styles.test.ts +535 -58
package/src/styles.ts +1130 -111
package/src/theme.test.tsx +29 -0
package/src/theme.themes.test.ts +13 -7
package/src/theme.tsx +30 -33
package/src/themes.ts +54 -0
package/src/toast.tsx +2 -1
package/src/tokens.guard.test.ts +239 -0
package/src/typography.test.tsx +213 -0
package/src/typography.tsx +255 -0
package/src/ui/Avatar.test.tsx +63 -0
package/src/ui/Avatar.tsx +65 -0
package/src/ui/Button.test.tsx +69 -3
package/src/ui/Button.tsx +57 -4
package/src/ui/Card.test.tsx +13 -0
package/src/ui/Card.tsx +28 -1
package/src/ui/Checkbox.tsx +10 -2
package/src/ui/Combobox.test.tsx +139 -0
package/src/ui/Combobox.tsx +255 -43
package/src/ui/DatePicker.tsx +44 -12
package/src/ui/Input.test.tsx +123 -0
package/src/ui/Input.tsx +65 -2
package/src/ui/Menu.tsx +16 -5
package/src/ui/Popover.tsx +13 -0
package/src/ui/Radio.tsx +10 -5
package/src/ui/Select.test.tsx +232 -0
package/src/ui/Select.tsx +177 -8
package/src/ui/Switch.tsx +10 -2
package/src/ui/Tabs.test.tsx +28 -0
package/src/ui/Tabs.tsx +30 -6
package/src/ui/Tooltip.test.tsx +56 -1
package/src/ui/Tooltip.tsx +69 -6
package/src/uiText.literals.test.ts +199 -0
package/src/uiText.tsx +36 -0
package/src/unwrap.test.ts +132 -0
package/src/unwrap.ts +118 -32

package/src/router.tsx CHANGED Viewed

@@ -7,13 +7,14 @@ import {
   useNavigate,
   useParams,
   useRouter,
+  useRouterState,
   useSearch,
   type AnyRoute,
   type RouterHistory,
 } from "@tanstack/react-router";
 import type { ComponentType, ReactNode } from "react";
-import { useEffect, useRef, useState } from "react";
-import type { ModuleManifest } from "@terpjs/contract";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ModuleManifest, NavGroup } from "@terpjs/contract";
 import { AppShell } from "./AppShell";
 import { ProfileView } from "./ProfileView";
@@ -25,8 +26,14 @@ import type {
   TerpRouteSearch,
 } from "./routeTypes";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
-import { visibleNav } from "./nav";
+import {
+  BRAND_FIELDS,
+  resolveLayoutDeclaration,
+  type LayoutDeclaration,
+} from "./layoutDeclaration";
+import { isDeclarationVisible, visibleNav } from "./nav";
 import { NavLinkContext } from "./navLink";
+import type { NavLinkRenderer } from "./navLink";
 import { PageMarkerContext } from "./pageMarker";
 import {
   RouteSearchContext,
@@ -234,8 +241,51 @@ export interface BuildAppRouterOptions {
   title: string;
   /** Brand mark in the sidebar (any rendered node); default: the placeholder TerpMark. */
   logo?: ReactNode;
+  /**
+   * The dark-theme brand mark ({@link AppShell.logoDark}); the stylesheet picks per appearance.
+   *
+   * Forwarded because it was not, which made it the third slot to exist on the shell and be
+   * unreachable from the entry points every app uses — after `headerActions`, which this ADR's
+   * own Context complains about. This one was worse than unreachable: the project template
+   * instructs every new app to pass `logoDark` to `renderTerpApp`, so the documented example
+   * did not typecheck.
+   */
+  logoDark?: ReactNode;
+  /** Extra header content, rendered before the theme / language controls. */
+  headerActions?: ReactNode;
   /** Footer line under the content; default: a muted line with the app title. */
   footer?: ReactNode;
+  /**
+   * Cap routed content at the published measure, with each page's header on the full track
+   * ({@link AppShell.contentWidth}); default `"full"`, which changes nothing.
+   */
+  contentWidth?: "full" | "measured";
+  /**
+   * App-wide density ({@link AppShell.density}). **No default** — omitting it stamps nothing, so
+   * an app's own `data-density` on `<html>` still reaches the tree.
+   */
+  density?: "comfortable" | "compact";
+  /**
+   * Where the primary navigation lives on desktop ({@link AppShell.navPlacement}): the
+   * full-height `"sidebar"` (default, and what every shell renders today) or `"header"`, a
+   * horizontal row in the header with no sidebar at all. Below the mobile breakpoint both are
+   * the drawer.
+   */
+  navPlacement?: "sidebar" | "header";
+  /**
+   * The app's navigation groups ({@link AppShell.navGroups}), which manifest items reference by
+   * `NavItem.group`. Omit for the flat, unlabelled sidebar every app renders today.
+   *
+   * Prefer {@link BuildAppRouterOptions.layout}: `shell.navGroups` in the app's own
+   * `frontend/layout-contract.json` says the same thing in the one document a tool can read and
+   * rewrite. Declaring the groups in both places is refused rather than silently resolved.
+   *
+   * A duplicate id is refused here rather than tolerated: it is an authoring error with no
+   * legitimate transient form, and composition time is where it can be reported once instead of
+   * on every render. An item naming an *undeclared* group is the opposite case and is not an
+   * error at all — modules ship independently of the app, so `groupNav` lets it fall open.
+   */
+  navGroups?: readonly NavGroup[];
   /** Role-name -> minimum rank; an unknown role is denied (fail closed). */
   roleRanks?: Record<string, number>;
   /** Rendered when the current user may not access a route (default: a simple message). */
@@ -244,10 +294,32 @@ export interface BuildAppRouterOptions {
    * Opt into a slot-typed layout contract (ADR 0079), e.g. `"standard"`: every routed
    * archetype's body slot then accepts only the components the contract allows there,
    * verified at runtime (fail closed) with the same directive message the
-   * `terp/layout-contract` lint rule phrases. Keep it in sync with the app's checked-in
-   * `layout-contract.json` (the lint half). Omit for today's archetype-only behavior.
+   * `terp/layout-contract` lint rule phrases.
+   *
+   * Prefer {@link BuildAppRouterOptions.layout}. This option used to carry the instruction
+   * "keep it in sync with the app's checked-in `layout-contract.json`", which is a defect
+   * written as advice and, since this function began reading that file, worse than stale:
+   * doing what the sentence said is now refused as one fact declared twice, even when the two
+   * agree. Omit both for today's archetype-only behavior.
    */
   layoutContract?: string;
+  /**
+   * The app's checked-in layout declaration (`frontend/layout-contract.json`, imported).
+   *
+   * The file the `terp/layout-contract` lint rule already reads, now read by the runtime half
+   * too, so `contract` is declared once instead of once per half. It also carries the palette
+   * the app opens on and the shell's own shape — `density`, `navPlacement`, `contentWidth` and
+   * the `navGroups` a module's `NavItem.group` names by id — all of which shipped as options
+   * here and were therefore out of reach of anything that edits files rather than code.
+   *
+   * The authoritative list is `TOP_LEVEL_KEYS` and `SHELL_KEYS` in
+   * {@link ./layoutDeclaration}, and the published `layout.manifest.json` beside them. This
+   * sentence is a restatement and has already drifted once.
+   *
+   * Declaring a key here AND passing the matching option is refused — see
+   * {@link resolveLayoutDeclaration}.
+   */
+  layout?: LayoutDeclaration;
   /** Router history (e.g. `createMemoryHistory`); omit for the browser history. */
   history?: RouterHistory;
 }
@@ -281,13 +353,33 @@ function DefaultUnauthorized() {
  * built-in {@link ProfileView} mounts at {@link PROFILE_PATH} unless a manifest claims that
  * path. Wrap the returned router in `<TerpProvider><RouterProvider router={router}/></TerpProvider>`.
  */
+/**
+ * A declared path as the element the shell's slot takes.
+ *
+ * `alt=""` because the mark is decorative here: the shell renders the app's title beside it,
+ * so a name on the image would have a screen reader announce the app twice. That is also what
+ * the template's own commented example does, and what an app hand-writing the option should do.
+ */
+function brandMark(path: string | undefined) {
+  return path === undefined ? undefined : <img src={path} alt="" />;
+}
 export function buildAppRouter(
   manifests: readonly ModuleManifest[],
   options: BuildAppRouterOptions,
 ) {
   const roleRanks = options.roleRanks ?? DEFAULT_ROLE_RANKS;
   const Unauthorized = options.unauthorized ?? DefaultUnauthorized;
-  const layoutContract = options.layoutContract ?? null;
+  // The declaration and the options collapse into one set before anything reads them, so
+  // every consumer below sees a single answer per key and cannot pick a different precedence.
+  const layout = resolveLayoutDeclaration(options.layout, {
+    contract: options.layoutContract,
+    density: options.density,
+    navPlacement: options.navPlacement,
+    contentWidth: options.contentWidth,
+    navGroups: options.navGroups,
+  });
+  const layoutContract = layout.contract ?? null;
   if (layoutContract !== null && LAYOUT_CONTRACTS[layoutContract] === undefined) {
     throw new Error(
       `Unknown layout contract "${layoutContract}"; known contracts: ` +
@@ -295,6 +387,40 @@ export function buildAppRouter(
         ".",
     );
   }
+  // An authoring error with no legitimate transient form, so it is refused here rather than
+  // absorbed. `groupNav` itself stays total — first declaration wins — because it runs on every
+  // render and a render must not be able to throw; this runs once, when the app is composed.
+  // Deliberately NOT symmetrical with an item naming an undeclared group, which is not an error
+  // at all: a module ships on its own schedule, so that is the normal state of an app mid-adoption
+  // and it falls open.
+  // Over the RESOLVED list, so one refusal covers a group declared in the file and a group
+  // passed as an option alike — which is also why `resolveLayoutDeclaration` does not restate it.
+  // The brand's two slots, each declarable as a checked-in PATH or passed as a rendered
+  // element. Refused together for the reason every other doubly-declared key is, and refused
+  // HERE rather than in the resolver because a path and an element are not comparable values:
+  // the resolver's message names both, and there is nothing to name on the code side but the
+  // fact that something was passed.
+  const brandConflicts = BRAND_FIELDS.filter(
+    (slot) => layout.brand?.[slot] !== undefined && options[slot] !== undefined,
+  );
+  if (brandConflicts.length > 0) {
+    throw new Error(
+      `frontend/layout-contract.json declares shell.brand.${brandConflicts.join(" and shell.brand.")}` +
+        ` and the bootstrap options pass ${brandConflicts.join(" and ")}. Declare each mark in ` +
+        "one place: the file is what a tool can read and rewrite, so prefer it and drop the option.",
+    );
+  }
+  const duplicateGroups = (layout.navGroups ?? [])
+    .map((group) => group.id)
+    .filter((id, index, ids) => ids.indexOf(id) !== index);
+  if (duplicateGroups.length > 0) {
+    throw new Error(
+      "Terp navGroups declare duplicate id(s): " +
+        [...new Set(duplicateGroups)].join(", ") +
+        ". Each group id is referenced by NavItem.group and must be declared once.",
+    );
+  }
   const missingViews = manifests.flatMap((manifest) =>
     manifest.routes
       .filter((route) => options.views[route.view] === undefined)
@@ -317,27 +443,85 @@ export function buildAppRouter(
   function Shell() {
     const router = useRouter();
-    const rank = useAuth().currentUser()?.role_rank ?? null;
-    const nav = visibleNav(manifests, (role) => allows(roleRanks, rank, role));
+    const user = useAuth().currentUser();
+    const rank = user?.role_rank ?? null;
+    const nav = visibleNav(manifests, {
+      canSeeRole: (role) => allows(roleRanks, rank, role),
+      permissions: user?.permissions ?? [],
+    });
+    // The shell decides which nav item is current and needs the path to do it. Selected, so the
+    // subscription re-renders only when the pathname itself changes — the same mechanism
+    // ModuleNav already uses.
+    const pathname = useRouterState({ select: (state) => state.location.pathname });
+    // Memoised, and this is a fix for a regression the line above introduces rather than
+    // tidying. `Shell` used to re-render only when `useAuth()` changed; it now re-renders on
+    // every navigation. `Outlet` is memoised with no props, so a re-render alone bails out at
+    // that boundary and the routed subtree is untouched — but a CONTEXT VALUE punches straight
+    // through a memo bailout, and this value is used as a component (Breadcrumbs and HubCard
+    // render it through useNavLink), so an unstable identity is worse than a re-render: it
+    // remounts every in-app link in the tree on each navigation.
+    const renderNavLink = useCallback<NavLinkRenderer>(
+      // `activeOptions={{ exact: true }}` for the same reason the shell's `renderLink`
+      // below carries it, and it matters MORE here: this renderer is what `Breadcrumbs`
+      // and `HubCard` use, so its job is rendering ANCESTORS. Under the router's default
+      // prefix matching every ancestor link matched the URL and was marked active, which
+      // on any detail route emitted a second `aria-current="page"` — one on the crumb for
+      // `/definitions` and one on the current crumb — plus a stray `.active` class and
+      // `data-status="active"` that made an ancestor look like the current page. The fix
+      // was applied to the nav and missed on the component whose whole purpose is the
+      // trail; exact matching means a crumb is only ever current when it IS the URL, and
+      // the current crumb is a span rather than a link.
+      ({ to, children, attributes }) => (
+        <Link to={to} activeOptions={{ exact: true }} {...attributes}>
+          {children}
+        </Link>
+      ),
+      [],
+    );
     return (
       // Publish the router's Link so every layout component that renders an in-app link
       // (Breadcrumbs, HubCard) navigates client-side by default. Forgetting `renderLink`
       // used to degrade the app silently: a raw anchor, a full page reload, no error.
-      <NavLinkContext.Provider value={({ to, children }) => <Link to={to}>{children}</Link>}>
+      <NavLinkContext.Provider value={renderNavLink}>
       <AppShell
         title={options.title}
-        logo={options.logo}
+        logo={brandMark(layout.brand?.logo) ?? options.logo}
+        logoDark={brandMark(layout.brand?.logoDark) ?? options.logoDark}
+        headerActions={options.headerActions}
         footer={options.footer}
+        contentWidth={layout.contentWidth}
+        density={layout.density}
+        navPlacement={layout.navPlacement}
+        activePath={pathname}
         nav={nav}
+        navGroups={layout.navGroups}
         renderBrandLink={({ to, children }) => (
           <Link to={to} data-terp="appshell-brand">
             {children}
           </Link>
         )}
-        // No style objects and no activeProps: the shell's stylesheet owns the link
-        // geometry and keys the active route on aria-current="page", which Link sets.
-        renderLink={(item, children) => (
-          <Link to={item.to} activeOptions={{ exact: item.to === "/" }}>
+        // No style objects and no activeProps: the shell's stylesheet owns the link geometry
+        // and keys the active route on aria-current="page".
+        //
+        // The shell supplies that attribute now, and `exact: true` is what makes the router
+        // agree instead of arguing. Two facts combine. `aria-current` is not among the props
+        // useLinkProps destructures, so a value passed here survives into the rendered anchor;
+        // and the router's own active props are spread LAST, but only when it considers the link
+        // active. With exact matching, "the router considers it active" implies the link's path
+        // equals the URL — which is the longest possible match, so it is always the same item
+        // the shell picked. The router can therefore only ever agree, never add a second
+        // current item.
+        //
+        // Prefix matching is what broke that: it marked every ancestor active, so `/settings`
+        // and `/settings/users` were both current at `/settings/users`. The old
+        // `exact: item.to === "/"` was a workaround for the same thing at the root, and it is
+        // gone because the shell's predicate matches on segments and `/` claims nothing else.
+        renderLink={(item, children, { active }) => (
+          <Link
+            to={item.to}
+            activeOptions={{ exact: true }}
+            aria-current={active ? "page" : undefined}
+          >
             {children}
           </Link>
         )}
@@ -359,12 +543,21 @@ export function buildAppRouter(
   function guardedRoute(
     path: string,
     View: ComponentType,
-    role: string | undefined,
+    declaration: { role?: string; permission?: string },
     viewName: string,
   ): AnyRoute {
     function RouteComponent() {
-      const rank = useAuth().currentUser()?.role_rank ?? null;
-      const allowed = allows(roleRanks, rank, role);
+      const user = useAuth().currentUser();
+      const rank = user?.role_rank ?? null;
+      // The same resolution the sidebar uses, and using it here is what stops `permission` from
+      // becoming a cosmetic gate: hiding a link while leaving its route reachable by URL is not
+      // a weaker version of authorization, it is the appearance of it. `role` has never had that
+      // asymmetry — it is declared on both NavItem and ModuleRoute — so `permission` does not
+      // get to introduce one.
+      const allowed = isDeclarationVisible(declaration, {
+        canSeeRole: (role) => allows(roleRanks, rank, role),
+        permissions: user?.permissions ?? [],
+      });
       // The runtime half of the "every routed view is a page archetype" control: Page
       // (composed by OverviewPage / DetailPage / HubPage) marks the render; a routed view
       // that mounted without any archetype in its tree is refused, fail closed. The check
@@ -416,14 +609,14 @@ export function buildAppRouter(
   const childRoutes: AnyRoute[] = manifests.flatMap((manifest) =>
     manifest.routes.map((route) =>
-      guardedRoute(route.path, options.views[route.view]!, route.role, route.view),
+      guardedRoute(route.path, options.views[route.view]!, route, route.view),
     ),
   );
   const profileClaimed = manifests.some((manifest) =>
     manifest.routes.some((route) => route.path === PROFILE_PATH),
   );
   if (!profileClaimed) {
-    childRoutes.push(guardedRoute(PROFILE_PATH, ProfileView, undefined, "profile"));
+    childRoutes.push(guardedRoute(PROFILE_PATH, ProfileView, {}, "profile"));
   }
   const routeTree = rootRoute.addChildren(childRoutes);