@terpjs/react-core 0.8.0 → 0.10.0

package/src/nav.ts

@@ -1,13 +1,187 @@
-import type { ModuleManifest, NavItem } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup, 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).
+ * What a manifest's declared visibility is resolved against.
+ *
+ * Built from what `/me` actually returns, which is the whole reason this type is two fields and
+ * not four. ADR 0097 §5 specified a context of module grants, per-module role ranks, superuser
+ * and internal-versus-external; `CurrentUser` carries none of them. It carries `role_rank`,
+ * `role_name` and `permissions`, and the last of those is the general mechanism the decision
+ * never named. A context built from what is real is honest; one built from that list would be
+ * vocabulary with no source behind it.
+ */
+export interface NavVisibilityContext {
+  /** Whether the caller clears a named role's floor — the existing `role` gate, unchanged. */
+  canSeeRole: (role: string | undefined) => boolean;
+  /**
+   * The caller's named grants, from `CurrentUser.permissions`.
+   *
+   * Empty when signed out and empty for an app that mounts no grant capability, which is what
+   * makes the gate fail closed in both cases rather than failing open in the second.
+   */
+  permissions: readonly string[];
+}
+
+/**
+ * Whether one declared item is visible to the caller.
+ *
+ * `role` and `permission` are **ANDed**, which is deliberately what the server does: a `Policy`
+ * carrying a `Permission` enforces the permission's role floor *and* the grant, so a client that
+ * checked either alone would disagree with the endpoint in one direction or the other. It is the
+ * same composition `Authorized` already ships, and reusing it means the navigation gains the gate
+ * the buttons already have rather than a second vocabulary for the same idea.
+ *
+ * Exported because routes need it too. A nav-only gate would hide the link and leave the route
+ * reachable by URL — `role` has never had that asymmetry, since it is declared on both
+ * `NavItem` and `ModuleRoute`, and `permission` must not introduce one.
+ */
+export function isDeclarationVisible(
+  declaration: { role?: string; permission?: string },
+  context: NavVisibilityContext,
+): boolean {
+  if (!context.canSeeRole(declaration.role)) {
+    return false;
+  }
+  return (
+    declaration.permission === undefined ||
+    context.permissions.includes(declaration.permission)
+  );
+}
+
+/**
+ * Flatten the nav of every module manifest into one ordered sidebar list, keeping only the items
+ * the current user may see.
+ *
+ * The context is a **required** argument, and that is a breaking change taken on purpose. Making
+ * it optional would have been source-compatible and silently wrong: an existing two-argument
+ * caller would fail closed on every item that gained a `permission`, removing links from a
+ * sidebar with no error anywhere. A required parameter turns that into a typecheck error at the
+ * one call site each app has.
  */
 export function visibleNav(
   manifests: readonly ModuleManifest[],
-  canSeeRole: (role: string | undefined) => boolean,
+  context: NavVisibilityContext,
 ): NavItem[] {
-  return manifests.flatMap((manifest) => manifest.nav ?? []).filter((item) => canSeeRole(item.role));
+  return manifests
+    .flatMap((manifest) => manifest.nav ?? [])
+    .filter((item) => isDeclarationVisible(item, context));
+}
+
+/**
+ * One rendered section of the primary navigation: a declared {@link NavGroup} with the items that
+ * named it, or the default headerless group with everything that named nothing.
+ *
+ * The group is flattened into `id` and `label` rather than carried whole, and that is what lets
+ * one shape describe both cases. The default group has no declaration to carry — it is not a
+ * `NavGroup` an app wrote, it is the absence of one — so a section holding an optional `NavGroup`
+ * would force every reader through `section.group?.label` to ask a question that has the same
+ * answer either way: what, if anything, do I render above this list.
+ */
+export interface NavSection {
+  /** The declared group's id, or `null` for the default headerless group. */
+  id: string | null;
+  /** The label to render above the list, or `null` when the section renders none. */
+  label: string | null;
+  items: NavItem[];
+}
+
+/** Stable ascending sort on `order ?? 0` — see {@link groupNav} for why absent is 0. */
+function byOrder<T extends { order?: number }>(values: T[]): T[] {
+  return values.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+}
+
+/**
+ * Arrange visible nav items into the app's declared groups.
+ *
+ * Groups fix the defect ADR 0097 names in its own Context: sidebar order is "an accident of
+ * `import.meta.glob` key order", because the sidebar is one flat list flattened out of whatever
+ * sequence the module manifests happened to arrive in. A group spans modules, so no module can
+ * own one — the app declares them, modules reference them by id, and this function is where the
+ * two halves meet.
+ *
+ * **Additive by construction.** An app that declares no groups gets exactly one section holding
+ * exactly the items it passed in, in the order it passed them: `groups` defaults to empty, every
+ * item falls into the default bucket, and a stable sort over keys that are all 0 is the identity.
+ * That is not an argument that it *should* be additive — it is the code path, and the shell
+ * renders the same list it renders today.
+ *
+ * Four rules, and each one is a decision:
+ *
+ * **An unknown group id falls into the default bucket rather than dropping the item.** A group is
+ * declared by the app; the item is declared by a module that ships on its own schedule. An id
+ * with no declaration yet is therefore the ordinary state of a module the app has not finished
+ * adopting, not a corruption — and the two ways to be wrong are not symmetric. An ungrouped link
+ * is in the wrong place and works; a dropped link is a screen the user cannot reach, with nothing
+ * anywhere saying why. Nothing warns about it either: this is a state the design calls normal,
+ * and a diagnostic for a normal state is noise that teaches people to ignore diagnostics.
+ *
+ * **A section with no items is not emitted.** Reachable on the first render of any app that
+ * groups the packaged admin entry's neighbours: `/admin` declares `role: "admin"`, so
+ * {@link visibleNav} removes it for everyone else and a group holding only it is left empty. A
+ * label over a void is worse than no label, because it names a place the user is being refused
+ * and cannot see.
+ *
+ * **The default bucket is emitted LAST, and it is not part of the group sort.** This is the rule
+ * that changed under review, and the case that decided it is the one case every app has. The
+ * packaged admin area is appended after the app's own manifests, so its nav entry renders last
+ * today. Emit the default bucket first and that entry — which no app authors and therefore no app
+ * can annotate with a `group` — jumps to the top of the sidebar the moment the app declares its
+ * first group. Emitting last leaves it exactly where it already is. It also puts an item naming
+ * an undeclared group at the bottom rather than above the app's own structure, which is the
+ * better place for a fail-open result to surface.
+ *
+ * The trade is real and is worth stating: an app that groups a *minority* of its items sees the
+ * ungrouped majority sink below them. That is app-authored, visible on the first render, and
+ * fixed in one line by declaring `{ id: "main", label: null, order: -1 }` and pointing those
+ * items at it — a group with a `null` label renders no heading, so it is pure positioning. The
+ * admin case has no such fix, which is what makes it decisive rather than merely also true.
+ *
+ * **Absent `order` is 0, everywhere, and the sort is stable.** Not `Infinity`: a single numbered
+ * item would then leap above an entire unnumbered list, which breaks the additivity the rest of
+ * this function is built on. Absent-is-0 is CSS `order` semantics exactly — positive sorts below
+ * its unordered siblings, negative above — which is the vocabulary a framework styled in tokens
+ * already speaks, and it means a manifest that numbers nothing is untouched.
+ *
+ * A duplicate group id is not an error here: the first declaration wins and the second is
+ * inert, so this function stays total and a render can never throw. `buildAppRouter` refuses the
+ * duplicate at composition time instead, where an authoring error belongs and where it can be
+ * reported once rather than on every frame.
+ */
+export function groupNav(
+  items: readonly NavItem[],
+  groups: readonly NavGroup[] = [],
+): NavSection[] {
+  // First declaration wins. A Map also gives the declared ids an O(1) membership test, which is
+  // what separates "this item names a real group" from "this item falls open".
+  const declared = new Map<string, NavGroup>();
+  for (const group of groups) {
+    if (!declared.has(group.id)) {
+      declared.set(group.id, group);
+    }
+  }
+
+  // `null` keys the default bucket. It cannot collide with a declared id: an id is a string, and
+  // the empty string — which is a legal id and would collide with any falsy sentinel — is a
+  // distinct Map key from null.
+  const buckets = new Map<string | null, NavItem[]>([[null, []]]);
+  for (const id of declared.keys()) {
+    buckets.set(id, []);
+  }
+  for (const item of items) {
+    const key = item.group !== undefined && declared.has(item.group) ? item.group : null;
+    buckets.get(key)!.push(item);
+  }
+
+  const sections: NavSection[] = [];
+  for (const group of byOrder([...declared.values()])) {
+    const bucket = buckets.get(group.id)!;
+    if (bucket.length > 0) {
+      sections.push({ id: group.id, label: group.label, items: byOrder(bucket) });
+    }
+  }
+  const ungrouped = buckets.get(null)!;
+  if (ungrouped.length > 0) {
+    sections.push({ id: null, label: null, items: byOrder(ungrouped) });
+  }
+  return sections;
 }

package/src/navActive.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import { activeNavPath, isNavItemActive } from "./navActive";
+
+// The predicate the sidebar and ModuleNav share (ADR 0097 §6, amended in 4e).
+//
+// Every case here is a URL shape where something in the framework got it wrong, or would have.
+// The set-level ones are the point of the file: `activeNavPath` exists because "at most one item
+// is current" cannot be decided one link at a time, and three of the four cases below are
+// invisible to a per-item test.
+
+describe("isNavItemActive", () => {
+  it("matches a segment-aligned prefix, not a string prefix", () => {
+    expect(isNavItemActive("/settings/users", "/settings")).toBe(true);
+    // The guard that matters: /settings-users starts with /settings as a STRING.
+    expect(isNavItemActive("/settings-users", "/settings")).toBe(false);
+  });
+
+  it("normalises a trailing slash on both operands, in both branches", () => {
+    // The exact branch had this from the start; the prefix branch did not, and an earlier draft
+    // of the rule attached the normalisation to `exact` alone.
+    expect(isNavItemActive("/settings/", "/settings")).toBe(true);
+    expect(isNavItemActive("/settings", "/settings/")).toBe(true);
+    expect(isNavItemActive("/settings/", "/settings", true)).toBe(true);
+    expect(isNavItemActive("/settings", "/settings/", true)).toBe(true);
+    // ...and the root is not normalised away to the empty string.
+    expect(isNavItemActive("/", "/")).toBe(true);
+  });
+
+  it("ignores the query string and the hash", () => {
+    // A nav tab's identity is its path. Filtering a list must not unhighlight the tab the user
+    // is standing on, which is what the router does on an exact link with includeSearch left at
+    // its default.
+    expect(isNavItemActive("/records", "/records")).toBe(true);
+    expect(isNavItemActive("/records", "/records", true)).toBe(true);
+  });
+
+  it("treats a `to` that is not an absolute path as inactive", () => {
+    // Not tidiness. The router resolves a relative or empty `to` against the CURRENT location,
+    // so `to: ""` is a link to wherever you already are — and a raw prefix test would light
+    // every item at once, because every path starts with the empty string.
+    expect(isNavItemActive("/records", "")).toBe(false);
+    expect(isNavItemActive("/records", "records")).toBe(false);
+    expect(isNavItemActive("/records", "./records")).toBe(false);
+  });
+
+  it("exact refuses the children a prefix would take", () => {
+    expect(isNavItemActive("/settings/users", "/settings", true)).toBe(false);
+    expect(isNavItemActive("/settings", "/settings", true)).toBe(true);
+  });
+
+  it("lets the root claim nothing but itself, with no rule of its own", () => {
+    // `/` prefixes every path as a STRING, which is why the router adapter carried a
+    // hand-written `exact: item.to === "/"`. Matching on SEGMENTS makes that unnecessary:
+    // `/profile`'s second character is not a slash.
+    expect(isNavItemActive("/profile", "/")).toBe(false);
+    expect(isNavItemActive("/", "/")).toBe(true);
+  });
+
+  it("collapses repeated slashes, which is the one shape the segment test would let through", () => {
+    // The gate for the normalisation, and it is the only input that distinguishes it: `/` has
+    // length 1, so the boundary test asks whether current[1] is a slash — true for exactly
+    // `//foo`. The router never emits that (it collapses on the way in), but `activePath` is a
+    // plain string and window.location.pathname is not normalised by anyone.
+    expect(isNavItemActive("//foo", "/")).toBe(false);
+    expect(activeNavPath("//foo", [{ to: "/" }])).toBeUndefined();
+    // ...and a doubled slash deeper in the path resolves to the same item either way.
+    expect(isNavItemActive("/settings//users", "/settings")).toBe(true);
+  });
+});
+
+describe("activeNavPath", () => {
+  const NAV = [{ to: "/" }, { to: "/settings" }, { to: "/settings/users" }];
+
+  it("returns exactly one item where a per-link predicate returns two", () => {
+    // The defect this whole file exists for. Both /settings and /settings/users match
+    // /settings/users on their own, so a router — which decides per link — marks both current,
+    // paints both, and announces "current page" twice.
+    expect(NAV.filter((item) => isNavItemActive("/settings/users", item.to))).toHaveLength(2);
+    expect(activeNavPath("/settings/users", NAV)).toBe("/settings/users");
+  });
+
+  it("keeps the parent lit on a URL that is not itself a nav item", () => {
+    // The other half, and the reason per-item `exact` is not the fix: turn exact on to stop the
+    // case above and this one goes dark, leaving a page with nothing current at all.
+    expect(activeNavPath("/settings/appearance", NAV)).toBe("/settings");
+  });
+
+  it("does not let the root item claim an unrelated page", () => {
+    // The example app ships `{ label: "Notes", to: "/" }`, and PROFILE_PATH is mounted by
+    // buildAppRouter and is in no manifest's nav. A STRING-prefix longest-match would light
+    // "Notes" while the user is on their profile; a segment-aligned one does not.
+    expect(activeNavPath("/profile", NAV)).toBeUndefined();
+    expect(activeNavPath("/", NAV)).toBe("/");
+  });
+
+  it("returns undefined when nothing matches", () => {
+    expect(activeNavPath("/explorer", [{ to: "/settings" }])).toBeUndefined();
+  });
+
+  it("honours an item's own exact flag", () => {
+    const nav = [{ to: "/settings", exact: true }, { to: "/records" }];
+    expect(activeNavPath("/settings/users", nav)).toBeUndefined();
+    expect(activeNavPath("/settings", nav)).toBe("/settings");
+  });
+
+  it("is not fooled by declaration order", () => {
+    // Longest wins, not first — otherwise the answer depends on `import.meta.glob` key order,
+    // which is the same accident 0097 names as the reason nav needs explicit ordering at all.
+    const shallowFirst = [{ to: "/settings" }, { to: "/settings/users" }];
+    const deepFirst = [{ to: "/settings/users" }, { to: "/settings" }];
+    expect(activeNavPath("/settings/users", shallowFirst)).toBe("/settings/users");
+    expect(activeNavPath("/settings/users", deepFirst)).toBe("/settings/users");
+  });
+});

package/src/navActive.ts

@@ -0,0 +1,119 @@
+/**
+ * Which navigation item is current — one predicate, owned here (ADR 0097 §6, amended in 4e).
+ *
+ * The framework had two notions of "active" and they disagreed. `ModuleNav` compared
+ * `pathname === item.to` raw while the `Link` it rendered compared through the router, and the
+ * sheet's own comment beside the rule said so and deferred the fix to "the navigation model" —
+ * this file. The sidebar had no predicate at all: it took whatever the router put on the anchor.
+ *
+ * The part that decides the shape is not the comparison, it is **arity**. "At most one item is
+ * current" is a property of the SET, and a router computes `isActive` per link with no knowledge
+ * of siblings. So a nav listing `/settings` and `/settings/users` gets two links the router
+ * considers active at `/settings/users`, two `aria-current="page"` attributes and two painted
+ * tabs — a screen reader says "current page" twice and neither is wrong on its own terms. Per
+ * item `exact` cannot fix it either: turn it on and `/settings/appearance`, a real route that is
+ * not itself a nav item, lights nothing at all. Only something looking at every item at once can
+ * pick one, which is why {@link activeNavPath} exists and why the shell calls it rather than
+ * asking each link how it feels.
+ *
+ * The comparison itself deliberately mirrors the router's, so the two never disagree about a
+ * single item — see `node_modules/@tanstack/router-core/dist/esm/path.js` for
+ * `removeTrailingSlash` and `exactPathTest`, and the non-exact branch in
+ * `@tanstack/react-router/dist/esm/link.js`. Reimplemented rather than imported because
+ * `@terpjs/contract` and a future non-React adapter need the same rule, and neither can take a
+ * TanStack dependency to get it.
+ *
+ * Search and hash are ignored on purpose. A nav tab's identity is its path: filtering a list
+ * must not unhighlight the tab the user is standing on.
+ */
+
+/**
+ * The router's own normalisation: collapse repeated slashes, then drop one trailing slash
+ * (except from the root itself). `cleanPath` and `removeTrailingSlash` in router-core, in that
+ * order.
+ *
+ * The collapse is load-bearing rather than defensive tidying, and it is what removes a special
+ * case rather than adding one. `/` has length 1, so the segment-boundary test below asks whether
+ * `current[1]` is a slash — which is true for exactly one shape, `//foo`, and would let the root
+ * item claim it. The router never produces that (`router.js:210` collapses on the way in), but
+ * `activePath` is a plain string prop and the shell cannot assume its caller went through
+ * TanStack: `window.location.pathname` does not. Normalising both operands the way the router
+ * does makes the root behave exactly with no rule of its own — an earlier draft special-cased
+ * `target === "/"` and justified it with `/profile`, which the boundary test already rejects.
+ */
+function normalise(path: string): string {
+  const collapsed = path.replace(/\/{2,}/g, "/");
+  return collapsed.endsWith("/") && collapsed !== "/" ? collapsed.slice(0, -1) : collapsed;
+}
+
+/**
+ * Whether `to` matches `pathname` on its own — the per-item half of the predicate.
+ *
+ * `exact` compares normalised equality; otherwise it is a **segment-aligned** prefix, so
+ * `/settings` matches `/settings/users` but not `/settings-users`. Both operands are normalised
+ * in **both** branches, which the router also does and which an earlier draft of this rule
+ * attached to the exact branch only.
+ *
+ * The root needs no special case: `/` matches another path only when that path's second
+ * character is a slash, and {@link normalise} has already collapsed those away.
+ *
+ * A `to` that does not begin with `/` is never active, and that is a guard rather than
+ * tidiness: the router resolves a relative or empty `to` against the *current* location, so
+ * `to: ""` produces a link that always points at the current page — and a raw prefix test would
+ * light every item in the sidebar at once, since every path starts with the empty string.
+ */
+export function isNavItemActive(pathname: string, to: string, exact = false): boolean {
+  if (!to.startsWith("/")) {
+    return false;
+  }
+  const current = normalise(pathname);
+  const target = normalise(to);
+  if (exact) {
+    return current === target;
+  }
+  return (
+    current.startsWith(target) &&
+    (current.length === target.length || current[target.length] === "/")
+  );
+}
+
+/** The shape {@link activeNavPath} needs from an item: where it goes, and how it matches. */
+export interface NavActiveCandidate {
+  to: string;
+  exact?: boolean;
+}
+
+/**
+ * The `to` of the one item that is current, or `undefined` when none is.
+ *
+ * **Longest match wins**, and that single rule replaces two special cases. Two items where one
+ * path prefixes the other resolve to the deeper one, so exactly one is ever current. A URL below
+ * a nav item still lights its parent, so `/settings/appearance` keeps `/settings` lit rather
+ * than emptying the sidebar.
+ *
+ * It also retires the hand-written `exact: item.to === "/"` the router adapter used to carry.
+ * That flag was there because `/` prefixes every path — but only as a STRING, and
+ * {@link isNavItemActive} matches on segments, so `/` claims nothing but itself regardless.
+ * The adapter was working around a prefix test it did not have.
+ *
+ * Ties are impossible: two items can only both match at the same length if their normalised
+ * paths are equal, in which case the first wins and they were the same destination anyway.
+ */
+export function activeNavPath(
+  pathname: string,
+  items: readonly NavActiveCandidate[],
+): string | undefined {
+  let winner: string | undefined;
+  let longest = -1;
+  for (const item of items) {
+    if (!isNavItemActive(pathname, item.to, item.exact)) {
+      continue;
+    }
+    const length = normalise(item.to).length;
+    if (length > longest) {
+      longest = length;
+      winner = item.to;
+    }
+  }
+  return winner;
+}

package/src/navLink.tsx

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react";
-import type { ReactNode } from "react";
+import type { AnchorHTMLAttributes, ReactNode } from "react";
 
 /**
  * How the surrounding router renders an in-app link.
@@ -15,7 +15,25 @@ import type { ReactNode } from "react";
  * to it. The anchor remains only for a component rendered outside any Terp router (a
  * standalone story or unit test), where there is no router to navigate with.
  */
-export type NavLinkRenderer = (props: { to: string; children: ReactNode }) => ReactNode;
+export type NavLinkRenderer = (props: {
+  to: string;
+  children: ReactNode;
+  /**
+   * HTML attributes for the rendered anchor **itself**, rather than for a wrapper around it.
+   *
+   * Added because the alternative was a silent loss. A caller's `aria-label` or `id` has to
+   * land on the anchor to mean anything — an `aria-label` on a `<span>` wrapping a link is
+   * ignored, so the link keeps its content as its accessible name and the caller's intent
+   * disappears with no error. `Link` hit exactly that: it renders through this seam for an
+   * in-app path and as a plain anchor otherwise, so the same prop worked in one branch and
+   * was dropped in the other, decided by whether the destination happened to start with `/`.
+   *
+   * An implementation that destructures only `{ to, children }` stays source-compatible and
+   * simply forwards nothing — which is why the marker a component styles itself by is NOT
+   * passed this way. That stays on a wrapper the component owns, so a renderer cannot lose it.
+   */
+  attributes?: Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">;
+}) => ReactNode;
 
 export const NavLinkContext = createContext<NavLinkRenderer | null>(null);