@charcuterie/ui 3.23.0 → 3.25.0

package/src/Nav/navItems.test.ts

@@ -0,0 +1,163 @@
+import { expect, test } from "vitest"
+
+import type { NavItem } from "./navItems.ts"
+import {
+  getIsCurrentHref,
+  resolveActiveKey,
+} from "./navItems.ts"
+
+const isCurrent = (currentHref: string, href: string) =>
+  getIsCurrentHref({ currentHref, href })
+
+const toItems = (...hrefs: string[]): NavItem[] =>
+  hrefs.map((href) => ({ href, label: href }))
+
+test("a destination is current on its own path", () => {
+  expect(isCurrent("/backlog", "/backlog")).toBe(true)
+
+  expect(isCurrent("/backlog", "/board")).toBe(false)
+})
+
+test("a parent path is current for its children", () => {
+  expect(isCurrent("/tasks/41", "/tasks")).toBe(true)
+
+  expect(isCurrent("/tasks/41/edit", "/tasks")).toBe(true)
+})
+
+test("a partial segment is not a match", () => {
+  // The separator is part of the rule. A bare `startsWith` lights
+  // two unrelated destinations here.
+  expect(isCurrent("/tasks", "/task")).toBe(false)
+
+  expect(isCurrent("/backlogged", "/backlog")).toBe(false)
+
+  expect(isCurrent("/boardgames", "/board")).toBe(false)
+})
+
+test("the root is exact", () => {
+  expect(isCurrent("/", "/")).toBe(true)
+
+  // `/` prefixes every path in the app, so a permissive root would
+  // mark Home current on every screen.
+  expect(isCurrent("/backlog", "/")).toBe(false)
+})
+
+test("the query string and the fragment are not part of the answer", () => {
+  expect(
+    isCurrent("/backlog?focus=search", "/backlog"),
+  ).toBe(true)
+
+  expect(isCurrent("/backlog#top", "/backlog")).toBe(true)
+
+  expect(
+    isCurrent("/backlog", "/backlog?focus=search"),
+  ).toBe(true)
+})
+
+test("a trailing slash is the same place", () => {
+  expect(isCurrent("/backlog/", "/backlog")).toBe(true)
+
+  expect(isCurrent("/backlog", "/backlog/")).toBe(true)
+})
+
+test("no current path marks nothing", () => {
+  expect(
+    getIsCurrentHref({ currentHref: undefined, href: "/" }),
+  ).toBe(false)
+})
+
+test("resolveActiveKey answers the key, and defaults it to the href", () => {
+  expect(
+    resolveActiveKey(toItems("/", "/board"), "/board"),
+  ).toBe("/board")
+
+  expect(
+    resolveActiveKey(
+      [{ href: "/board", key: "board", label: "Board" }],
+      "/board",
+    ),
+  ).toBe("board")
+})
+
+test("no address means nothing is current", () => {
+  expect(resolveActiveKey(toItems("/", "/board"))).toBe(
+    null,
+  )
+})
+
+test("an address no destination owns marks nothing", () => {
+  expect(
+    resolveActiveKey(toItems("/", "/board"), "/nowhere"),
+  ).toBe(null)
+})
+
+/**
+ * The defect this function exists for. `getIsCurrentHref` is asked
+ * once per item and says `true` for both of these, which is two
+ * `aria-current="page"` in one nav — a nav that has stopped saying
+ * anything.
+ */
+test("the deepest match wins, so exactly one item is current", () => {
+  expect(isCurrent("/settings/labels", "/settings")).toBe(
+    true,
+  )
+
+  expect(
+    resolveActiveKey(
+      toItems("/settings", "/settings/labels"),
+      "/settings/labels",
+    ),
+  ).toBe("/settings/labels")
+})
+
+test("the deepest match wins regardless of array order", () => {
+  // Longest by path, not by position: an app lists its destinations
+  // in the order the product reads, and that order must not decide
+  // which one lights up.
+  expect(
+    resolveActiveKey(
+      toItems("/settings/labels", "/settings"),
+      "/settings/labels",
+    ),
+  ).toBe("/settings/labels")
+})
+
+test("a parent is still current for a child it alone owns", () => {
+  expect(
+    resolveActiveKey(
+      toItems("/settings", "/settings/labels"),
+      "/settings/schemes",
+    ),
+  ).toBe("/settings")
+})
+
+test("an external destination is never current", () => {
+  // Without this, an external item pointing at another product's
+  // `/board` matches this app's own `/board`.
+  expect(
+    resolveActiveKey(
+      [
+        {
+          href: "https://example.com/board",
+          isExternal: true,
+          label: "Elsewhere",
+        },
+        { href: "/board", label: "Board" },
+      ],
+      "/board",
+    ),
+  ).toBe("/board")
+
+  expect(
+    resolveActiveKey(
+      [
+        {
+          href: "/board",
+          isExternal: true,
+          label: "Elsewhere",
+        },
+      ],
+      "/board",
+    ),
+  ).toBe(null)
+})

package/src/Nav/navItems.ts

@@ -0,0 +1,175 @@
+import type { ReactNode } from "react"
+
+export type NavItem = {
+  /**
+   * Where it goes. Routed through the injected `RouterLink` when it
+   * is this app's own path, and left to the platform when it is not.
+   */
+  href: string
+  /** Decoration beside the label. Never the accessible name. */
+  icon?: ReactNode
+  /**
+   * A destination outside this app. It renders a plain anchor with
+   * `target="_blank"` and `rel="noopener noreferrer"`, and it is
+   * never current — pushing `https://…` onto a router's history
+   * navigates the app to a route it does not have.
+   */
+  isExternal?: boolean
+  /** Defaults to `href`, which is already unique in a nav. */
+  key?: string
+  /** The visible text, and the accessible name. */
+  label: string
+}
+
+/**
+ * What the rail layouts take. `icon` stops being optional, because
+ * `railIcons` takes the **label** away: an item with no glyph is a
+ * blank square that still navigates, and there is no visual defect
+ * to notice because the row reads as padding.
+ *
+ * Optional would move that failure out of the type checker and into
+ * the first time somebody drags a window narrow. The library still
+ * ships no icons — a glyph in a default renders as nothing where the
+ * font lacks it, so the app brings its own.
+ */
+export type NavRailItem = NavItem & {
+  icon: ReactNode
+}
+
+export const getNavItemKey = (item: NavItem): string =>
+  item.key ?? item.href
+
+/**
+ * Which destination the reader is on — the rule behind
+ * `aria-current="page"`, kept pure so it can be checked in Node.
+ *
+ * The library is router-agnostic (see `RouterLinkProvider`), so it
+ * cannot ask a router which link is active. The app hands it one
+ * string — `useLocation().pathname`, `window.location.pathname`,
+ * whatever it has — and this decides the rest.
+ *
+ * ## A parent path is current for its children
+ *
+ * `/tasks` is current while the reader is on `/tasks/41`, because a
+ * nav item names a **section** and a section does not stop being the
+ * one you are in when you open something inside it. The match is on
+ * whole segments: `/task` is *not* current for `/tasks`, which a bare
+ * `startsWith` would get wrong.
+ *
+ * ## `/` is exact, and that is deliberately not react-router
+ *
+ * react-router's `<NavLink to="/">` is active on **every** route
+ * unless the caller remembers `end`, which is the footgun behind
+ * every "why is Home always highlighted" bug in the fleet. The root
+ * matches only itself here, and there is no prop to change it: a nav
+ * with two current items is a nav that has stopped saying anything.
+ *
+ * ## The query string and the fragment are not part of the answer
+ *
+ * `/backlog?focus=search` is still the Backlog. Sorting a list does
+ * not move the reader to a different destination.
+ *
+ * ⚠️ **This answers for ONE item, so it cannot keep the promise in
+ * the paragraph above by itself.** Given `/settings` and
+ * `/settings/labels`, it says `true` for both on the deeper path.
+ * `resolveActiveKey` is the whole-list answer, and it is what `Nav`
+ * uses; reach for this one only when there is a single link to test.
+ */
+const toComparablePath = (href: string): string => {
+  const path = href.split(/[#?]/u)[0] ?? ""
+
+  // A trailing slash is the same place, so it must not change the
+  // answer — but `/` itself has to survive being trimmed.
+  return path.length > 1 ? path.replace(/\/+$/u, "") : path
+}
+
+export const getIsCurrentHref = ({
+  currentHref,
+  href,
+}: {
+  /** Where the reader is. `undefined` means "nothing is current". */
+  currentHref: string | undefined
+  /** Where this destination goes. */
+  href: string
+}): boolean => {
+  if (currentHref === undefined) {
+    return false
+  }
+
+  const current = toComparablePath(currentHref)
+
+  const target = toComparablePath(href)
+
+  if (target === "" || target === "/") {
+    return current === target
+  }
+
+  return (
+    current === target || current.startsWith(`${target}/`)
+  )
+}
+
+/**
+ * The current destination's key, or `null` — the whole-list answer,
+ * and the one `Nav` marks with `aria-current="page"`.
+ *
+ * ## Exactly one, because the deepest match wins
+ *
+ * `getIsCurrentHref` is asked per item, so a nav holding both
+ * `/settings` and `/settings/labels` gets `true` twice while the
+ * reader is on the deeper one. Two current items is a nav that has
+ * stopped saying anything — the same thing react-router's `<NavLink
+ * to="/">` footgun produces — so the longest matching path wins and
+ * the shallower section stands down.
+ *
+ * Longest by **path**, not by array position: an app must be able to
+ * list its destinations in the order the product reads (Docket's is
+ * the pipeline) without that order deciding which one lights up.
+ *
+ * ## An external item is never current
+ *
+ * It is not a place inside this app, so no address the app is at can
+ * be it. Without this, an item pointing at `https://example.com/board`
+ * matches the app's own `/board` on a plain string compare.
+ */
+export const resolveActiveKey = (
+  items: readonly NavItem[],
+  activeHref?: string,
+): string | null => {
+  if (activeHref === undefined) {
+    return null
+  }
+
+  let matchedItem: NavItem | null = null
+
+  let matchedLength = -1
+
+  for (const item of items) {
+    if (item.isExternal === true) {
+      continue
+    }
+
+    if (
+      !getIsCurrentHref({
+        currentHref: activeHref,
+        href: item.href,
+      })
+    ) {
+      continue
+    }
+
+    const candidateLength = toComparablePath(
+      item.href,
+    ).length
+
+    if (candidateLength > matchedLength) {
+      matchedItem = item
+
+      matchedLength = candidateLength
+    }
+  }
+
+  return matchedItem === null
+    ? null
+    : getNavItemKey(matchedItem)
+}

package/src/Nav/useNavLayout.ts

@@ -0,0 +1,197 @@
+import { useMediaQuery } from "@charcuterie/logic"
+import { matchMediaMatcher } from "@charcuterie/logic/browser"
+import { useState } from "react"
+
+/**
+ * What the reader asked for, which is not the same as what they get.
+ *
+ * `auto` lets the width decide. The other two are a deliberate
+ * override and outrank the width — but only where a rail fits at
+ * all; see `useNavLayout`.
+ */
+export type NavLayoutMode =
+  | "auto"
+  | "collapsed"
+  | "expanded"
+
+/** The three forms a rail-shaped nav actually takes on screen. */
+export type ResolvedNavLayout =
+  | "menu"
+  | "rail"
+  | "railIcons"
+
+export type UseNavLayoutOptions = {
+  /**
+   * Below this width the rail drops its labels. Default `64rem`,
+   * which is `screen.lg`.
+   */
+  iconsBelow?: string
+  /**
+   * Below this width there is no rail at all. Default `48rem`, which
+   * is `screen.md` — and the same step `Rail` itself collapses at,
+   * so the two cannot disagree.
+   */
+  menuBelow?: string
+  /**
+   * Where the manual choice is remembered. Omit and the override
+   * lasts until the tab is closed.
+   *
+   * Name it for the app (`"queuepilot-nav"`), not for this library:
+   * two apps on the same origin share `localStorage`, and this
+   * fleet's dev servers all sit on `localhost`.
+   */
+  storageKey?: string
+}
+
+export type NavLayoutState = {
+  /** `true` in `railIcons`. The rail's own collapse control reads it. */
+  isCollapsed: boolean
+  /** What to pass to `Nav`'s `layout`. */
+  layout: ResolvedNavLayout
+  mode: NavLayoutMode
+  setMode: (mode: NavLayoutMode) => void
+  /**
+   * Expanded ⇄ collapsed. From `auto` it goes to whichever of the two
+   * is **not** on screen now, so the first press always visibly does
+   * something — which "toggle" has to mean or the control reads as
+   * broken.
+   */
+  toggle: () => void
+}
+
+const DEFAULT_ICONS_BELOW = "64rem"
+
+const DEFAULT_MENU_BELOW = "48rem"
+
+const isNavLayoutMode = (
+  value: string | null,
+): value is NavLayoutMode =>
+  value === "auto" ||
+  value === "collapsed" ||
+  value === "expanded"
+
+/**
+ * `localStorage`, wrapped both ways.
+ *
+ * It throws in a sandboxed iframe and in some privacy modes, and it
+ * does not exist at all while a page renders on a server — a rail
+ * that cannot remember its width should still have one.
+ *
+ * `@charcuterie/logic/browser`'s `localStoragePersistence` is the
+ * same shape and is deliberately **not** reused: it validates what
+ * it reads with `isColorSchemeMode`, so it answers `null` for every
+ * value this hook stores.
+ */
+const readStoredMode = (
+  key: string,
+): NavLayoutMode | null => {
+  try {
+    const stored = window.localStorage.getItem(key)
+
+    return isNavLayoutMode(stored) ? stored : null
+  } catch {
+    return null
+  }
+}
+
+const writeStoredMode = (
+  key: string,
+  mode: NavLayoutMode,
+) => {
+  try {
+    window.localStorage.setItem(key, mode)
+  } catch {
+    // A page that cannot persist still switches for this session.
+  }
+}
+
+/**
+ * The width rule for a rail-shaped navigation, written once.
+ *
+ * Three states, and the app chooses none of them:
+ *
+ * | Width | Layout | What the app renders |
+ * | --- | --- | --- |
+ * | `>= iconsBelow` | `rail` | a `Rail` holding a `Nav` |
+ * | `>= menuBelow` | `railIcons` | the same `Rail`, narrower |
+ * | below that | `menu` | a trigger in the `Header` |
+ *
+ * ### Why the app still places it
+ *
+ * Because the placement genuinely differs and the rule does not. The
+ * `menu` state puts a control in the header — a different corner of
+ * the page from a side rail — and no amount of restyling moves an
+ * element across `Shell`'s grid. So the library owns *which* state
+ * is right, at what width, with what override and where the override
+ * is remembered; the app owns two `if`s. That is the half that was
+ * being rewritten per app, and rewritten differently: Docket's nav
+ * wraps to three lines on a phone, mail-sifter collapses at `40rem`,
+ * and QueuePilot at `760px`, all of them arrived at alone.
+ *
+ * ### The override does not reach the narrow state
+ *
+ * `expanded` on a 390px screen would be a 212px rail beside 178px of
+ * content. The width wins there, and the remembered choice is *kept*
+ * rather than cleared — rotating a tablet back to landscape restores
+ * the rail the reader asked for, instead of silently forgetting it.
+ *
+ * ### It is a hook, not CSS
+ *
+ * The same reason `usePanelItemSize` is: a media query can restyle a
+ * rail, but it cannot move a control into the header, and it cannot
+ * tell the trigger whether to render at all. A resize re-renders;
+ * a scheme or density change still does not.
+ */
+export const useNavLayout = ({
+  iconsBelow = DEFAULT_ICONS_BELOW,
+  menuBelow = DEFAULT_MENU_BELOW,
+  storageKey,
+}: UseNavLayoutOptions = {}): NavLayoutState => {
+  // Read once, lazily — a `useState` initialiser, so the stored
+  // choice is in place for the first paint and the rail does not
+  // open wide and then snap shut.
+  const [mode, setStoredMode] = useState<NavLayoutMode>(
+    () =>
+      (storageKey === undefined
+        ? null
+        : readStoredMode(storageKey)) ?? "auto",
+  )
+
+  const { isMatching: isBelowMenu } = useMediaQuery({
+    matcher: matchMediaMatcher(`(width < ${menuBelow})`),
+  })
+
+  const { isMatching: isBelowIcons } = useMediaQuery({
+    matcher: matchMediaMatcher(`(width < ${iconsBelow})`),
+  })
+
+  const setMode = (nextMode: NavLayoutMode) => {
+    setStoredMode(nextMode)
+
+    if (storageKey !== undefined) {
+      writeStoredMode(storageKey, nextMode)
+    }
+  }
+
+  const autoLayout: ResolvedNavLayout = isBelowIcons
+    ? "railIcons"
+    : "rail"
+
+  const layout: ResolvedNavLayout = isBelowMenu
+    ? "menu"
+    : mode === "auto"
+      ? autoLayout
+      : mode === "collapsed"
+        ? "railIcons"
+        : "rail"
+
+  return {
+    isCollapsed: layout === "railIcons",
+    layout,
+    mode,
+    setMode,
+    toggle: () => {
+      setMode(layout === "rail" ? "collapsed" : "expanded")
+    },
+  }
+}

package/src/NavBar/NavBar.mdx

@@ -6,6 +6,32 @@ import * as NavBarStories from "./NavBar.stories";
 
 # NavBar
 
+> ## ⚠️ Deprecated — use [`Nav`](?path=/docs/components-layout-nav--docs)
+>
+> **Removed in the next major.** `NavBar` is now a thin adapter over `Nav` and keeps every
+> behaviour documented on this page, so nothing breaks today.
+>
+> ```tsx
+> // Before
+> <NavBar currentHref={pathname} items={DESTINATIONS} label="Main" />
+>
+> // After — `bar` is Nav's default layout
+> <Nav activeHref={pathname} items={DESTINATIONS} label="Main" />
+> ```
+>
+> `currentHref` is `activeHref`. Every other prop keeps its name.
+>
+> **Two items can no longer both be current.** This component asked the question once per
+> item, so a bar holding `/settings` and `/settings/labels` marked *both* while the reader was
+> on the deeper one — against the decision record below, which says a nav with two current
+> items has stopped saying anything. `Nav` takes the deepest match.
+>
+> **Why it went away:** it answered half the question. A horizontal row that folds is one
+> shape an app's destinations take; a labelled side rail, a collapsed icon rail and a
+> Narrow-View bottom strip are the others, and this component could not become any of them —
+> so an app that wanted a rail was back to hand-rolling, which is the state it was built to
+> end.
+
 The app's destinations as real links, in one line — folding into a single menu button,
 **whole**, when that line does not fit.