@charcuterie/ui 3.20.0 → 3.22.0

package/src/NavBar/NavBar.tsx

@@ -0,0 +1,271 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { Placement } from "@floating-ui/react"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { IconButton } from "../IconButton/IconButton.tsx"
+import { usePanelItemSize } from "../Overlay/usePanelItemSize.ts"
+import { Popover } from "../Popover/Popover.tsx"
+import { useToolbarOverflow } from "../Toolbar/useToolbarOverflow.ts"
+import { toClassName } from "../toClassName.ts"
+import { NavBarLink } from "./NavBarLink.tsx"
+import { getIsCurrentHref } from "./navBarCurrent.ts"
+
+export type NavBarItem = {
+  /**
+   * 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
+  /** Defaults to `href`, which is already unique in a nav. */
+  key?: string
+  /** The visible text, and the accessible name. */
+  label: string
+}
+
+export type NavBarProps = {
+  className?: string
+  /**
+   * Where the reader is — `useLocation().pathname` in a
+   * react-router app. `aria-current="page"` is derived from it by
+   * `getIsCurrentHref`, which matches a parent path for its
+   * children and treats `/` as exact.
+   *
+   * Omitted means nothing is current, which is the honest answer on
+   * a route no destination owns.
+   */
+  currentHref?: string
+  /**
+   * **Initial** only, and the bar owns it from then on — the same
+   * uncontrolled contract every other component here has. It exists
+   * so a story (and a screenshot) can show the menu open; an app
+   * almost never passes it.
+   */
+  isMenuVisible?: boolean
+  items: readonly NavBarItem[]
+  /**
+   * Required, and it becomes the `<nav>`'s `aria-label`. Two unnamed
+   * navigation landmarks in one page is axe's `landmark-unique`, and
+   * more to the point it is a screen reader announcing "navigation"
+   * twice with no way to tell which is the main one.
+   */
+  label: string
+  /**
+   * Where the trigger sits in the bar's track once the row has
+   * folded. `"end"` when the header puts its own actions at the
+   * far edge, so the fold control joins them instead of hugging
+   * the wordmark with the whole track empty after it.
+   *
+   * It reaches **only** the folded row, which holds exactly one
+   * item — so it cannot disturb where the links sit when the bar
+   * is whole, and there is deliberately no prop that can.
+   */
+  menuAlign?: "end" | "start"
+  /**
+   * The collapsed trigger's glyph. **No default** — the library
+   * ships no icons, and `☰` renders as nothing where the font lacks
+   * it. With no icon the trigger is a text button reading
+   * `menuLabel`, which works everywhere.
+   */
+  menuIcon?: ReactNode
+  /**
+   * Names the trigger and, through it, the panel it opens. A
+   * `role="dialog"` takes no accessible name from its content.
+   */
+  menuLabel?: string
+  menuPlacement?: Placement
+  size?: ControlSize
+}
+
+/**
+ * The app's destinations as real links, in one line — folding into a
+ * single menu button, whole, when that line does not fit.
+ *
+ * ## Why this is not `Toolbar`
+ *
+ * `Toolbar` already solves collapse-into-an-overflow, and this
+ * component **reuses its measurement** (`useToolbarOverflow`) rather
+ * than growing a second one. What it cannot reuse is the rendering:
+ * a `ToolbarAction` is `{ label, onSelect }` and a collapsed one
+ * becomes a `MenuItem`, so a nav folded into a `Toolbar` is a row of
+ * `<button>`s. Navigation is an `<a href>` — see `NavBarLink`.
+ *
+ * The overflow is a `Popover` (`role="dialog"`) rather than a `Menu`
+ * for the same reason: `role="menu"` permits only the `menuitem`
+ * family, and a `menuitem` is something you *do*, not somewhere you
+ * *go*.
+ *
+ * ## It folds WHOLE, and that is the decision
+ *
+ * `Toolbar` collapses **progressively** — items drop off the end one
+ * at a time — because its items are ranked: the two things you do to
+ * a running job matter more than the two you do to the deck. A nav
+ * is not ranked. Its order is the shape of the product (Docket's
+ * reads as the pipeline: Triage → Backlog → Phases → Board →
+ * Archives), and a half-collapsed one splits that shape across two
+ * places with no rule the reader can learn — "some of the app is up
+ * here and the rest is behind a button" is worse than either whole
+ * answer. So the bar shows **every** destination or **none**, and
+ * the menu, when it opens, is the complete list in the product's own
+ * order.
+ *
+ * ## Measured, not breakpointed
+ *
+ * There is no `collapseAt` prop and no media query. The bar reads
+ * the width its links actually have and folds when their sum stops
+ * fitting, so a longer label, a tenth destination, a
+ * `data-density="kiosk"` or a reader at 175% browser zoom each move
+ * the fold on their own. A hardcoded pixel number is wrong the first
+ * time any of those changes — mux-magic collapses at `480px` and
+ * plex-channels at `760px`, and neither number has a reason.
+ *
+ * ⚠️ **The bar must not be sized by its own contents.** It measures
+ * its own box to decide what to draw in it, so a container that
+ * shrink-wraps makes the answer its own input: put it in a
+ * `minmax(0, 1fr)` grid track or a `flex-1 min-w-0` row. The root
+ * carries `min-w-0 flex-1` for the flex case; a grid track is the
+ * caller's to declare. Same trap `useAdaptiveColumns` documents from
+ * the other end.
+ *
+ * ## Mounted exactly once
+ *
+ * A destination is in the bar or in the panel, never both. The
+ * fleet's habit is to render the whole nav twice and hide one copy
+ * with `hidden md:flex` — mux-magic's `PageHeader` across two
+ * ~55-line blocks, mail-sifter's `TriageQueue` again — which puts
+ * every link in the DOM at every width, so an agent driving the page
+ * finds two of each and cannot tell which one a human can see.
+ */
+export const NavBar = ({
+  className,
+  currentHref,
+  isMenuVisible = false,
+  items,
+  label,
+  menuAlign = "start",
+  menuIcon,
+  menuLabel = "Menu",
+  menuPlacement = "bottom-start",
+  size = "sm",
+}: NavBarProps): ReactNode => {
+  const itemKeys = items.map(
+    (item) => item.key ?? item.href,
+  )
+
+  const { containerRef, trackItem, visibleCount } =
+    useToolbarOverflow({ itemKeys })
+
+  /**
+   * All or nothing. `visibleCount` is the progressive answer and
+   * this is the only thing read off it: the moment one link stops
+   * fitting, every link goes into the menu together.
+   *
+   * The hook's `trackTrigger` is deliberately not wired up, and the
+   * missing measurement costs nothing here. It exists so a
+   * progressive bar can ask "how many fit **beside a trigger**",
+   * which is a question this bar never asks: either every link fits
+   * with no trigger at all, or the row is one trigger and nothing
+   * else. `chooseVisibleCount` tests the whole-row case first and
+   * with the trigger costed at zero, so that branch is exact.
+   */
+  const isCollapsed = visibleCount < items.length
+
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isMenuVisible,
+  })
+
+  const panelItemSize = usePanelItemSize("lg")
+
+  const renderLink = (
+    item: NavBarItem,
+    placement: "bar" | "panel",
+  ) => (
+    <NavBarLink
+      isCurrent={getIsCurrentHref({
+        currentHref,
+        href: item.href,
+      })}
+      item={item}
+      key={item.key ?? item.href}
+      onNavigate={placement === "panel" ? hide : undefined}
+      placement={placement}
+      size={placement === "bar" ? size : panelItemSize}
+      trackElement={
+        placement === "bar" ? trackItem : undefined
+      }
+    />
+  )
+
+  const trigger =
+    menuIcon === undefined ? (
+      <Button
+        appearance="ghost"
+        intent="neutral"
+        onClick={toggle}
+        size={size}
+      >
+        {menuLabel}
+      </Button>
+    ) : (
+      <IconButton
+        appearance="ghost"
+        intent="neutral"
+        label={menuLabel}
+        onClick={toggle}
+        size={size}
+      >
+        {menuIcon}
+      </IconButton>
+    )
+
+  return (
+    <nav
+      aria-label={label}
+      className={toClassName(
+        "flex min-w-0 flex-1 items-center gap-1",
+        // Two written-out entries rather than one interpolated
+        // string: Tailwind's scanner cannot see a class that
+        // exists only at runtime.
+        isCollapsed && menuAlign === "end"
+          ? "justify-end"
+          : "justify-start",
+        className,
+      )}
+      ref={containerRef}
+    >
+      {isCollapsed ? (
+        <Popover
+          // The default panel is `max-w-xs p-3` — sized for a
+          // paragraph of prose. This one holds full-bleed rows that
+          // bring their own inset, so the padding shrinks to the
+          // gutter around them and the width is left to the list.
+          className="max-w-none p-1"
+          heading={menuLabel}
+          isVisible={isVisible}
+          onDismiss={hide}
+          placement={menuPlacement}
+          trigger={trigger}
+        >
+          {/*
+            A list, so a screen reader says how many destinations
+            there are before the reader starts down them — the one
+            thing the bar's own row communicates by simply being
+            visible all at once.
+          */}
+          <ul className="flex min-w-48 list-none flex-col gap-0.5">
+            {items.map((item) => (
+              <li key={item.key ?? item.href}>
+                {renderLink(item, "panel")}
+              </li>
+            ))}
+          </ul>
+        </Popover>
+      ) : (
+        items.map((item) => renderLink(item, "bar"))
+      )}
+    </nav>
+  )
+}

package/src/NavBar/NavBarLink.tsx

@@ -0,0 +1,139 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { MouseEvent, ReactNode } from "react"
+
+import {
+  CONTROL_SIZE_CLASS,
+  PANEL_ITEM_SIZE_CLASS,
+} from "../controlStyles.ts"
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { toClassName } from "../toClassName.ts"
+import type { NavBarItem } from "./NavBar.tsx"
+
+export type NavBarLinkProps = {
+  isCurrent: boolean
+  item: NavBarItem
+  /**
+   * Fires when the reader activates this link **in a way that keeps
+   * them on the page** — a plain left click, Enter, Space. It is
+   * what closes the collapsed panel behind them.
+   *
+   * A modified click (ctrl, meta, shift, alt) opens a new tab and
+   * leaves this document exactly where it was, so it deliberately
+   * does not fire: shutting the menu the reader is still working
+   * through is the behaviour that makes people stop ctrl-clicking.
+   */
+  onNavigate?: () => void
+  /** Where it is drawn. A bar row and a panel row paint differently. */
+  placement: "bar" | "panel"
+  size: ControlSize
+  /** Hands the bar row's box to the measuring hook. Bar only. */
+  trackElement?: (
+    key: string,
+    element: HTMLElement | null,
+  ) => void
+}
+
+/**
+ * One destination, drawn either in the bar or in the collapsed
+ * panel — and it is a real `<a href>` in both.
+ *
+ * That is the whole reason this component exists rather than the
+ * `Menu` a collapsed `Toolbar` opens: `MenuItem` is `{ label,
+ * onSelect }`, so a nav folded into one becomes a row of
+ * `<button>`s. It looks identical in a screenshot and it loses
+ * middle-click, ctrl-click, "open in a new tab", "copy link
+ * address", the status bar, and the browser's own visited styling.
+ * `BuildingAnApp.mdx` names `<button onClick={navigate}>` as the
+ * fleet's most common navigation defect; a collapse mechanism that
+ * introduced it at narrow widths would be that defect on a timer.
+ *
+ * The router seam is `ButtonLink`'s, unchanged: an external
+ * destination or a fragment falls back to a plain anchor rather than
+ * being pushed onto a history stack that has no route for it.
+ */
+export const NavBarLink = ({
+  isCurrent,
+  item,
+  onNavigate,
+  placement,
+  size,
+  trackElement,
+}: NavBarLinkProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  const LinkElement = getIsRoutedHref(item.href)
+    ? RouterLink
+    : "a"
+
+  const className =
+    placement === "bar"
+      ? toClassName(
+          "inline-flex shrink-0 items-center rounded-md border border-transparent whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard",
+          CONTROL_SIZE_CLASS[size],
+          // Two written-out entries rather than one interpolated
+          // string, the same rule `SegmentedOption` follows:
+          // Tailwind's scanner cannot see a class that exists only
+          // at runtime, and `tailwindCandidates.test.ts` rejects a
+          // template literal in a className outright.
+          isCurrent
+            ? "bg-intent-neutral-surface font-medium text-content-primary"
+            : "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+          FOCUS_RING_CLASS,
+        )
+      : toClassName(
+          "flex w-full items-center rounded-sm text-start transition-colors duration-(--duration-fast) ease-standard",
+          PANEL_ITEM_SIZE_CLASS[size],
+          // `-hover`, not the plain surface: the panel is drawn on
+          // `surface-overlay`, which every dark scheme paints
+          // *lighter* than the base tint, so the plain one reads as
+          // no change at all. Same correction `MenuAction` carries.
+          isCurrent
+            ? "bg-intent-neutral-surface-hover font-medium text-content-primary"
+            : "text-content-primary hover:bg-intent-neutral-surface-hover",
+          FOCUS_RING_CLASS,
+        )
+
+  return (
+    <LinkElement
+      // The platform's own "you are here", and the reason the paint
+      // above is never the only signal: a highlight is invisible to
+      // a screen reader and to anyone who cannot tell the two
+      // surfaces apart.
+      aria-current={isCurrent ? "page" : undefined}
+      className={className}
+      href={item.href}
+      onClick={(event: MouseEvent<HTMLAnchorElement>) => {
+        if (
+          event.defaultPrevented ||
+          event.button !== 0 ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.metaKey ||
+          event.shiftKey
+        ) {
+          return
+        }
+
+        onNavigate?.()
+      }}
+      ref={(element: HTMLAnchorElement | null) => {
+        trackElement?.(item.key ?? item.href, element)
+      }}
+    >
+      {item.icon === undefined ? null : (
+        // Decoration beside the item's own text. An icon that
+        // announces itself turns "Settings" into "gear Settings".
+        <span
+          aria-hidden="true"
+          className="shrink-0 text-content-secondary"
+        >
+          {item.icon}
+        </span>
+      )}
+
+      {item.label}
+    </LinkElement>
+  )
+}

package/src/NavBar/navBarCurrent.test.ts

@@ -0,0 +1,81 @@
+import { expect, test } from "vitest"
+
+import { getIsCurrentHref } from "./navBarCurrent.ts"
+
+const isCurrent = (currentHref: string, href: string) =>
+  getIsCurrentHref({ currentHref, href })
+
+test("a destination is current on its own path", () => {
+  expect(isCurrent("/backlog", "/backlog")).toBe(true)
+
+  expect(isCurrent("/backlog", "/board")).toBe(false)
+})
+
+/**
+ * A nav item names a **section**, and a section does not stop being
+ * the one you are in when you open something inside it.
+ */
+test("a parent path is current for its children", () => {
+  expect(isCurrent("/tasks/41", "/tasks")).toBe(true)
+
+  expect(isCurrent("/tasks/41/edit", "/tasks")).toBe(true)
+})
+
+/**
+ * The match is on whole segments. A bare `startsWith` marks `/task`
+ * as current for `/tasks`, which is a highlight on the wrong item
+ * and nothing to see in a review.
+ */
+test("a partial segment is not a match", () => {
+  expect(isCurrent("/tasks", "/task")).toBe(false)
+
+  expect(isCurrent("/backlogged", "/backlog")).toBe(false)
+})
+
+/**
+ * react-router's `<NavLink to="/">` is active on every route unless
+ * the caller remembers `end` — the footgun behind every "why is Home
+ * always highlighted" bug. The root matches only itself here, and
+ * there is no prop to change it.
+ */
+test("the root is exact", () => {
+  expect(isCurrent("/", "/")).toBe(true)
+
+  expect(isCurrent("/backlog", "/")).toBe(false)
+})
+
+/**
+ * Sorting a list does not move the reader to a different
+ * destination.
+ */
+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)
+})
+
+/**
+ * `undefined` is what a caller passes when it does not know, and the
+ * honest reading of that is that nothing is current — not that
+ * everything is.
+ */
+test("no current path marks nothing", () => {
+  expect(
+    getIsCurrentHref({
+      currentHref: undefined,
+      href: "/backlog",
+    }),
+  ).toBe(false)
+})

package/src/NavBar/navBarCurrent.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+
+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}/`)
+  )
+}

package/src/icons.storyHelpers.tsx

@@ -192,6 +192,18 @@ export const MoreIcon = (): ReactNode => (
   </svg>
 )
 
+/**
+ * The three-line "open the nav" glyph, for `NavBar`'s collapsed
+ * trigger. U+2630 TRIGRAM FOR HEAVEN — the character a repo reaches
+ * for instead — measures blank in this sandbox's chromium, exactly
+ * like the three-dot glyph above.
+ */
+export const MenuIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M4 6h16M4 12h16M4 18h16" />
+  </svg>
+)
+
 /**
  * The markdown toolbar's nine, plus the bar's own overflow above.
  *

package/src/index.ts

@@ -190,6 +190,11 @@ export type {
   DialogSize,
 } from "./Dialog/Dialog.tsx"
 export { Dialog } from "./Dialog/Dialog.tsx"
+export type {
+  DropRailProps,
+  DropRailTarget,
+} from "./DropRail/DropRail.tsx"
+export { DropRail } from "./DropRail/DropRail.tsx"
 export type {
   EmptyStateProps,
   EmptyStateSize,
@@ -271,6 +276,12 @@ export type {
 export { Menu } from "./Menu/Menu.tsx"
 export type { ModalProps } from "./Modal/Modal.tsx"
 export { Modal } from "./Modal/Modal.tsx"
+export type {
+  NavBarItem,
+  NavBarProps,
+} from "./NavBar/NavBar.tsx"
+export { NavBar } from "./NavBar/NavBar.tsx"
+export { getIsCurrentHref } from "./NavBar/navBarCurrent.ts"
 export type {
   PickerOption,
   PickerProps,

package/src/sourceRules.test.ts

@@ -489,7 +489,30 @@ test("the barrel is the only place components are re-exported", async () => {
   // It is also why `safeUrls.ts` moved up out of
   // `markdownEditorCodeMirror/`: two surfaces taking a URL out of a
   // document and putting it in an `href` is one allowlist, not two.
-  expect(componentNames.length).toBe(56)
+  //
+  // `DropRail` — every move destination at once, as a listbox that a
+  // pointer, a tap or the arrow keys all drive — is +1 -> 57. It has
+  // no members, and it takes no drag-and-drop dependency: the
+  // hit test is `elementFromPoint` over its own chips, which is the
+  // only geometric question a rail has. `Board` keeps its `Menu`,
+  // which is the right control at three lanes; this is the one for a
+  // page with thirty-four groups on it.
+  //
+  // `NavBar` — the app's destinations as real links, folding whole
+  // into one menu button when the row stops fitting — is +1 -> 58.
+  // It **reuses** `Toolbar`'s `useToolbarOverflow` rather than
+  // forking the measurement, and exists as its own component for one
+  // reason the type system makes plain: a `ToolbarAction` is
+  // `{ label, onSelect }` and a collapsed one becomes a `MenuItem`,
+  // which is also `{ label, onSelect }` — so a nav folded into a
+  // `Toolbar` is a row of `<button>`s, which is the fleet's most
+  // common navigation defect and screenshots identically to the
+  // correct thing. `NavBarLink.tsx` is its member and stays out of
+  // this count by the `<Name>/<Name>.tsx` rule; `navBarCurrent.ts`
+  // is too, while still being exported from the barrel — an app that
+  // marks a destination current anywhere else must ask the same
+  // question the same way.
+  expect(componentNames.length).toBe(58)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)