@estiva-app/ui 0.1.0 → 0.3.0

package/src/Menu.mdx

@@ -0,0 +1,111 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as MenuStories from './Menu.stories'
+
+<Meta of={MenuStories} />
+
+# Menu
+
+The shell every menu shares: an elevated container — hairline border, 8px
+radius, 8px padding, the large shadow — and the two exits every menu owes,
+**Escape and a click outside, owned here and never by the caller**. Rows are
+**MenuItem**, headings are **MenuSection**, a non-interactive line at row
+geometry is **MenuRow**, and **EnterHint** is the "↩ Enter" a picker row
+shows while highlighted.
+
+<Canvas of={MenuStories.Items} />
+
+## When
+
+- A click-opened list of actions: a `…` more-menu, an account menu, a
+  right-click's worth of verbs. Rows are the default `MenuItem` — 14px
+  label, optional `leading` icon, `shortcut` kbd chip, `destructive` in the
+  error colour.
+- A picker fed by typing: @-mentions, a people picker, a command list.
+  Those rows are `MenuItem size="tall"` — content height with a 40px floor,
+  room for a 32px face via `leading` and a `description` line — with an
+  `EnterHint` on the highlighted row.
+- Grouped choices where one is current: `MenuSection` over rows, `selected`
+  on the chosen one.
+
+<Canvas of={MenuStories.Sections} />
+
+## When not
+
+- Picking one value for a form field → **Select**. It is the same shell
+  behaviour plus a trigger that shows the value.
+- Rows that toggle checkboxes and stay open → that is a **listbox**, not a
+  menu; a Checkbox inside a `menuitem` button is invalid HTML. Build it as
+  a list in a DialogShell.
+- A strip of icon actions (reactions, formatting) → a toolbar of
+  **IconButton**s.
+- Anything with a title and a footer → **DialogShell**.
+- Who-you-are and where-you-are (the avatar in the top bar) →
+  **IdentityMenu**, already built on this shell.
+
+## How
+
+Menus are controlled: the caller keeps `open` state, renders the menu only
+while true, and hands it `onClose`. Escape and outside-click then work
+without the caller writing either.
+
+```tsx
+import { Menu, MenuItem } from '@estiva-app/ui'
+
+{open && (
+  <Menu onClose={() => setOpen(false)}>
+    <MenuItem label="Rename" onClick={rename} />
+    <MenuItem label="Delete" destructive onClick={confirmDelete} />
+  </Menu>
+)}
+```
+
+Two anchorings:
+
+- **Default** — the menu hangs below its trigger, right-aligned; the
+  wrapper around trigger and menu must be `relative`.
+- **`position={{ top, left }}` or `{ top, right }`** — the menu portals to
+  the body at fixed viewport coordinates, for triggers inside containers
+  that scroll or clip.
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Escape | closes — the shell's listener, not the caller's |
+| `mousedown` outside | closes; the trigger swallows its own (see below) |
+| click inside the menu | stays open — the shell stops propagation |
+| Tab / Shift-Tab | moves focus through the rows (native buttons) |
+| Enter / Space on a focused row | activates it |
+| Arrow keys | nothing — a typeahead picker owns its own highlight |
+
+### The trigger trap
+
+The outside-click exit listens on `mousedown`. A trigger that toggles on
+`click` will therefore see its own press close the menu and the click
+reopen it — a flicker that reads as "the menu ignores me". The trigger
+swallows the mousedown, exactly as IdentityMenu's does:
+
+```tsx
+<button
+  onMouseDown={(event) => event.stopPropagation()}
+  onClick={() => setOpen((value) => !value)}
+/>
+```
+
+### What stays the caller's
+
+Hover-opening, and submenus. A hover-opened menu owes the five popover
+rules (see the README — stay open over the menu, close on leave, guard the
+parent's hover); the shell gives only the two click-opened exits, so the
+hover choreography is the caller's. Submenus likewise stay caller-owned —
+if a second menu needs one, the shell learns it then.
+
+### Alignment
+
+A menu whose rows are `px-3` (tall picker rows) aligns its headings by
+passing `className="px-3"` to `MenuSection` — the heading row is `px-2` by
+default, matching the default rows.
+
+## Props
+
+<Controls of={MenuStories.Items} />

package/src/Menu.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconCopy, IconPencil, IconTrash } from '@tabler/icons-react'
+import { Divider } from './Divider'
+import { Menu, MenuItem, MenuRow, MenuSection } from './Menu'
+import { SectionLabel } from './SectionLabel'
+
+/**
+ * The shell every menu shares — container, rows, headings, and the two exits
+ * (Escape and a click outside) owned here, never by the caller. In an app
+ * the menu hangs from its trigger or a portal position; stories pin it open
+ * in-flow (`className="static"` wins over the anchoring) and centre it, so
+ * the docs page shows each one inside its own frame.
+ */
+const meta = {
+  title: 'Overlays/Menu',
+  component: Menu,
+  decorators: [(Story) => <div className="flex min-h-[240px] w-full items-center justify-center"><Story /></div>],
+  args: { onClose: () => {}, children: null, className: 'static' },
+  argTypes: { position: { control: false }, onClose: { control: false }, children: { control: false } },
+} satisfies Meta<typeof Menu>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Rows with a leading icon, a shortcut, and the destructive colour for the one that deletes. */
+export const Items: Story = {
+  render: (args) => (
+    <Menu {...args}>
+      <MenuItem label="Rename" leading={<IconPencil size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
+      <MenuItem label="Copy link" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="⌘ C" onClick={() => {}} />
+      <Divider className="my-1" />
+      <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
+    </Menu>
+  ),
+}
+
+/** Groups under SectionLabel headings, with a Divider between them; `selected` marks the chosen value. */
+export const Sections: Story = {
+  render: (args) => (
+    <Menu {...args}>
+      <MenuSection label="Sort by">
+        <MenuItem label="Newest first" selected onClick={() => {}} />
+        <MenuItem label="Oldest first" onClick={() => {}} />
+      </MenuSection>
+      <Divider className="my-1" />
+      <MenuSection label="Show">
+        <MenuItem label="Everything" onClick={() => {}} />
+        <MenuItem label="Unread only" onClick={() => {}} />
+      </MenuSection>
+    </Menu>
+  ),
+}
+
+/** A non-interactive row at the item's geometry — identity lines, hints. */
+export const WithARow: Story = {
+  render: (args) => (
+    <Menu {...args} className="static w-64">
+      <MenuRow>
+        <span className="min-w-0 flex-1 truncate text-[14px] leading-[140%] text-text-primary">Ana Duarte</span>
+        <SectionLabel className="text-text-secondary">Owner</SectionLabel>
+      </MenuRow>
+      <Divider className="my-1" />
+      <MenuItem label="Sign out" onClick={() => {}} />
+    </Menu>
+  ),
+}

package/src/Menu.tsx

@@ -0,0 +1,172 @@
+import { useEffect, useRef, type ComponentPropsWithRef, type CSSProperties, type ReactNode } from 'react'
+import { IconChevronRight } from '@tabler/icons-react'
+import { createPortal } from 'react-dom'
+import { cn } from './cn'
+import { SectionLabel } from './SectionLabel'
+
+/**
+ * THE menu shell (2026-09-01) — extracted once, for every menu in every app.
+ *
+ * Peek has no single Menu file; its topic menu, conversation menus, files
+ * menu and the top bar's account menu each hand-roll the same thing, and
+ * they disagree: some close on Escape, most do not, and row heights and
+ * minimum widths drift copy by copy. Ship extracted the shape so it would
+ * not become the next copy; the package exists so nobody becomes the one
+ * after that.
+ *
+ * What every menu shares, kept exactly: an elevated container with a
+ * hairline border, 8px radius, 8px padding and the large shadow; items that
+ * are 8px-radius rows, `px-2 py-1.5`, hover fill, 14px text, destructive
+ * ones in the error colour; section headings as a SectionLabel in a 32px
+ * row; and the two exits every menu has — Escape and a click outside —
+ * owned by the menu, never copied into a caller.
+ *
+ * Two anchorings: `position` portals it to the body at fixed viewport
+ * coordinates (for menus opened inside scrolling containers that clip);
+ * without it the menu hangs below its trigger, right-aligned, and the
+ * caller's wrapper is `relative`.
+ */
+export interface MenuProps {
+  onClose: () => void
+  /** Viewport coordinates; the menu is portalled, hung from `top`, and aligned to whichever edge is given. */
+  position?: { top: number; right: number } | { top: number; left: number }
+  children: ReactNode
+  className?: string
+}
+
+export function Menu({ onClose, position, children, className }: MenuProps) {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onDown = (event: MouseEvent) => {
+      if (!ref.current?.contains(event.target as Node)) onClose()
+    }
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onClose()
+    }
+    document.addEventListener('mousedown', onDown)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', onDown)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [onClose])
+
+  const style: CSSProperties | undefined = position ? { top: position.top, ...('left' in position ? { left: position.left } : { right: position.right }) } : undefined
+  const node = (
+    <div
+      ref={ref}
+      role="menu"
+      data-interactive
+      className={cn(
+        'z-50 flex min-w-[180px] flex-col rounded-lg border border-border-default bg-bg-elevated p-2 shadow-lg',
+        position ? 'fixed' : 'absolute right-0 top-full mt-1',
+        className,
+      )}
+      style={style}
+      onClick={(event) => event.stopPropagation()}
+    >
+      {children}
+    </div>
+  )
+  return position ? createPortal(node, document.body) : node
+}
+
+export interface MenuItemProps extends Omit<ComponentPropsWithRef<'button'>, 'children'> {
+  label?: string
+  /** Replaces the label/description block — for rows whose middle is richer
+   *  than text (the launcher's form rows). Leading/trailing still apply. */
+  children?: ReactNode
+  /** `tall` is the picker row — content height with a 40px floor, px-3,
+   *  gap-3, room for a 32px face or icon tile and the description line.
+   *  `default` is the command row. */
+  size?: 'default' | 'tall'
+  /** A second line under the label — a role, an address — 12px, secondary, truncating. */
+  description?: string
+  /** Before the label: a 16px icon (stroke 1.5, secondary), or an Avatar, for rows led by a face. */
+  leading?: ReactNode
+  /** At the right edge: a hint, a value — anything. Wins over `shortcut` and `submenu`. */
+  trailing?: ReactNode
+  /** A keyboard hint, drawn as the kbd chip. */
+  shortcut?: string
+  /** The row opens another menu: draws the chevron at the right edge. */
+  submenu?: boolean
+  destructive?: boolean
+  /** The row the menu currently points at (a submenu's chosen value). */
+  selected?: boolean
+}
+
+export function MenuItem({ label, children, size = 'default', description, leading, trailing, shortcut, submenu, destructive, selected, className, ...props }: MenuItemProps) {
+  const edge =
+    trailing ??
+    (shortcut ? (
+      <kbd className="inline-flex shrink-0 items-center justify-center rounded-sm border border-border-strong bg-bg-inset px-1 py-px text-caption text-text-secondary">
+        {shortcut}
+      </kbd>
+    ) : submenu ? (
+      <IconChevronRight size={16} stroke={1.5} className="shrink-0 text-text-muted" />
+    ) : null)
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      className={cn(
+        'flex w-full cursor-pointer items-center rounded-lg text-left hover:bg-bg-hover transition-colors',
+        // tall: as tall as its content, never shorter than 40px (Katerina,
+        // 2026-09-01) — a single-line picker row sits at 40, a row with a
+        // 32px face and a role line comes out at its natural 48. One rule,
+        // not a hand-picked height per file.
+        size === 'tall' ? 'min-h-10 gap-3 px-3 py-1.5' : 'gap-2 px-2 py-1.5',
+        selected && 'bg-bg-hover',
+        className,
+      )}
+      {...props}
+    >
+      {leading && <span className="flex shrink-0 items-center">{leading}</span>}
+      {/* Sizes are arbitrary values (the body-2 and caption tokens): these
+          lists merge with a colour, and tw-merge drops a token size beside a
+          colour. Ship's copy said `text-sm`, which was never the ramp. */}
+      {children ?? (
+        <span className={cn('flex min-w-0 flex-1 flex-col', size === 'tall' && 'gap-[2px]')}>
+          <span className={cn('truncate text-[14px] leading-[140%]', destructive ? 'text-error-default' : 'text-text-primary')}>
+            {label}
+          </span>
+          {description && <span className="truncate text-[12px] leading-[120%] text-text-secondary">{description}</span>}
+        </span>
+      )}
+      {edge && <span className="flex shrink-0 items-center">{edge}</span>}
+    </button>
+  )
+}
+
+/**
+ * The keyboard hint a picker row shows while highlighted — "↩ Enter",
+ * "↩ #topic" — hand-rolled in five files before this (2026-09-01).
+ */
+export function EnterHint({ label = 'Enter' }: { label?: string }) {
+  return (
+    <span className="flex shrink-0 items-center gap-2 text-text-muted">
+      <span className="text-[12px] leading-[120%]">↩</span>
+      <span className="text-[9px] font-medium leading-[115%] signal:font-mono signal:text-[9.5px] signal:tracking-[0.04em]">{label}</span>
+    </span>
+  )
+}
+
+/** A section heading inside a menu: the 32px row with a SectionLabel, read
+ *  secondary — a heading inside a menu labels the rows, it is not one of
+ *  them (Katerina, 2026-09-01). */
+export function MenuSection({ label, children, className }: { label: string; children: ReactNode; /** On the heading row — a surface whose rows are px-3 aligns its heading with px-3. */ className?: string }) {
+  return (
+    <div className="flex flex-col">
+      <div className={cn('flex h-8 items-center px-2', className)}>
+        <SectionLabel className="text-text-secondary">{label}</SectionLabel>
+      </div>
+      {children}
+    </div>
+  )
+}
+
+/** A non-interactive row inside a menu, at the item's own geometry. */
+export function MenuRow({ children, className }: { children: ReactNode; className?: string }) {
+  return <div className={cn('flex items-center gap-2 px-2 py-1.5', className)}>{children}</div>
+}

package/src/MenuItem.mdx

@@ -0,0 +1,55 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as MenuItemStories from './MenuItem.stories'
+
+<Meta of={MenuItemStories} />
+
+# MenuItem
+
+The row of a menu: label, and around it everything a row can carry — a
+`leading` icon or face, a `description` second line, a `shortcut` kbd
+chip, a `submenu` chevron, a `trailing` anything (which wins over the
+other two), `destructive` in the error colour, `selected` as the fill.
+
+<Canvas of={MenuItemStories.AllVariants} />
+
+## When
+
+- Every actionable row inside a **Menu**.
+- **`size="tall"`** is the picker row: content height with a 40px floor,
+  `px-3`, room for a 32px face and the description line — one rule, not a
+  hand-picked height per surface. ChipInput's suggestions are these.
+- `children` replaces the label/description block for rows whose middle
+  is richer than text; `leading` and `trailing` still apply.
+
+<Canvas of={MenuItemStories.Tall} />
+
+## When not
+
+- Outside a menu — it renders `role="menuitem"` and belongs inside a
+  `role="menu"` container.
+- Picking a form value → **Select**'s own options.
+- A row that toggles a checkbox → not a menu at all; see the Menu page.
+
+## How
+
+```tsx
+import { Menu, MenuItem } from '@estiva-app/ui'
+import { IconPencil } from '@tabler/icons-react'
+
+<MenuItem
+  label="Rename"
+  leading={<IconPencil size={16} stroke={1.5} className="text-text-secondary" />}
+  shortcut="⌘ R"
+  onClick={rename}
+/>
+```
+
+- It is a native button underneath — every prop passes through, ref
+  included, so a typeahead can drive the highlight with `selected` +
+  `onMouseEnter` and add on `onMouseDown`.
+- A destructive row's `leading` icon takes the error colour itself
+  (`text-error-default`) — the row colours only its label.
+
+## Props
+
+<Controls of={MenuItemStories.Default} />

package/src/MenuItem.stories.tsx

@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconCopy, IconPin, IconTrash } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { EnterHint, Menu, MenuItem } from './Menu'
+
+/**
+ * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
+ * with an optional `description` line · one thing at the right edge —
+ * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
+ * chevron. Stories sit inside a pinned-open Menu so the row is seen on the
+ * surface it lives on.
+ */
+const meta = {
+  title: 'Overlays/MenuItem',
+  component: MenuItem,
+  decorators: [
+    (Story) => (
+      <div className="flex min-h-[120px] w-full items-center justify-center">
+        <Menu onClose={() => {}} className="static w-72">
+          <Story />
+        </Menu>
+      </div>
+    ),
+  ],
+  args: { label: 'Rename', onClick: () => {} },
+  argTypes: {
+    onClick: { control: false },
+    leading: { control: false },
+    trailing: { control: false },
+  },
+} satisfies Meta<typeof MenuItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const WithAnIcon: Story = {
+  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
+}
+
+export const WithAShortcut: Story = {
+  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: '⌘ C' },
+}
+
+/** The row opens another menu. */
+export const Submenu: Story = {
+  args: { label: 'Move to…', submenu: true },
+}
+
+/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
+export const APerson: Story = {
+  args: {
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    trailing: <span className="text-[12px] leading-[120%] text-text-muted">↩</span>,
+  },
+}
+
+/** The submenu's chosen value. */
+export const Selected: Story = {
+  args: { label: 'Newest first', selected: true },
+}
+
+export const Destructive: Story = {
+  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
+}
+
+/** Every shape on one canvas. */
+export const AllVariants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <>
+      <MenuItem label="Bare" onClick={() => {}} />
+      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
+      <MenuItem label="With a shortcut" shortcut="⌘ K" onClick={() => {}} />
+      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="⌘ C" onClick={() => {}} />
+      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
+      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<span className="text-[12px] leading-[120%] text-text-muted">↩</span>} onClick={() => {}} />
+      <MenuItem label="The chosen value" selected onClick={() => {}} />
+      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
+      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
+    </>
+  ),
+}
+
+/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
+export const Tall: Story = {
+  args: {
+    size: 'tall',
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    selected: true,
+    trailing: <EnterHint />,
+  },
+}

package/src/NavItem.mdx

@@ -0,0 +1,53 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as NavItemStories from './NavItem.stories'
+
+<Meta of={NavItemStories} />
+
+# NavItem
+
+One row of a sidebar: an optional 16px icon, a label, and an optional
+count — a muted mono number whose tooltip says what it counts.
+
+<Canvas of={NavItemStories.WithIconAndCount} />
+
+## When
+
+- The entries of a **Sidebar** — top-level places, and the rows of a
+  labelled group.
+- `active` marks where the route is: the selected tab's neutral fill, and
+  `aria-current="page"` for assistive tech.
+- A count is a number of **one** thing, and `countLabel` says which ("18
+  open", "5 active"). A `0` or an absent count draws nothing — that is
+  this row's rule; a *tab* draws its zero, and both rulings stand.
+
+<Canvas of={NavItemStories.ZeroDrawsNothing} />
+
+## When not
+
+- An icon rail's tile → **RailItem**.
+- Switching views inside a page → **Tabs**.
+- A row in a popover → **MenuItem**.
+
+## How
+
+```tsx
+import { NavItem } from '@estiva-app/ui'
+
+<NavItem
+  href="#/documents"
+  label="Documents"
+  icon={<IconListDetails size={16} stroke={1.5} />}
+  count={openCount}
+  countLabel={`${openCount} open`}
+  active={current === 'documents'}
+/>
+```
+
+- It renders a plain anchor. A router app keeps a thin wrapper: compute
+  `active` from the location, intercept the click, navigate — every
+  anchor prop passes through.
+- The label truncates; the count never gives up its width.
+
+## Props
+
+<Controls of={NavItemStories.Default} />

package/src/NavItem.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { NavItem } from './NavItem'
+
+const placeholder = <IconSquareRounded size={16} stroke={1.5} />
+
+const meta = {
+  title: 'Frame/NavItem',
+  component: NavItem,
+  args: { label: 'Item', href: '#', active: false },
+  argTypes: { icon: { control: false } },
+  decorators: [(Story) => <div className="flex w-60 flex-col gap-px">{Story()}</div>],
+} satisfies Meta<typeof NavItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/** Active is the selected tab's fill — neutral, text primary. */
+export const Active: Story = { args: { active: true } }
+
+/** The count is a muted mono number, and its tooltip says what it counts. */
+export const WithIconAndCount: Story = {
+  args: { icon: placeholder, count: 18, countLabel: '18 open' },
+}
+
+/** A zero is not drawn at all — this row's rule (a tab draws its zero; both are deliberate). */
+export const ZeroDrawsNothing: Story = {
+  args: { icon: placeholder, count: 0, countLabel: '0 open' },
+}
+
+/** The label gives way; the count never does. */
+export const LongLabelTruncates: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', count: 7, countLabel: '7 open' },
+}

package/src/NavItem.tsx

@@ -0,0 +1,53 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react'
+import { cn } from './cn'
+import { WithTooltip } from './Tooltip'
+
+/**
+ * One row of a sidebar: a label, an optional count, an active state
+ * (Ship's NavItem, 2026-09-02, verbatim).
+ *
+ * A count is a number of ONE thing, and its tooltip says which ("18
+ * open", "5 active") — the caller passes the number and the words for it,
+ * and a zero is not drawn at all. That is this row's rule; a *tab's*
+ * count draws its zero (see Tabs) — both rulings stand, deliberately.
+ *
+ * Active is the same fill as a selected tab — `bg-active`, neutral.
+ */
+export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'> {
+  label: string
+  href: string
+  /** `0` or absent renders no counter. */
+  count?: number
+  /** What the count counts, for the tooltip — "18 open", "5 active". */
+  countLabel?: string
+  active?: boolean
+  /** 16px, stroke 1.5. */
+  icon?: ReactNode
+  className?: string
+}
+
+export function NavItem({ label, href, count, countLabel, active = false, icon, className, ...props }: NavItemProps) {
+  return (
+    <a
+      href={href}
+      aria-current={active ? 'page' : undefined}
+      className={cn(
+        // shrink-0: the row keeps its 32px inside an overflowing flex column
+        // — without it the list compresses instead of scrolling (the missing-
+        // shrink-0 family; Katerina, 2026-09-02).
+        'flex h-8 min-w-0 shrink-0 items-center gap-2 rounded-md px-2 text-body-2 transition-colors',
+        active ? 'bg-bg-active text-text-primary' : 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
+        className,
+      )}
+      {...props}
+    >
+      {icon && <span className="flex shrink-0 items-center">{icon}</span>}
+      <span className="flex-1 truncate">{label}</span>
+      {count ? (
+        <WithTooltip label={countLabel ?? `${count} open`}>
+          <span className="shrink-0 font-mono text-caption tabular-nums text-text-muted">{count}</span>
+        </WithTooltip>
+      ) : null}
+    </a>
+  )
+}