@estiva-app/ui 0.50.4 → 0.51.0

package/dist/looks.d.ts

@@ -36,4 +36,11 @@ export declare const BARE_INPUT_CLASSES = "bg-transparent text-text-primary plac
 /** A sidebar row's shape and its words at rest, brightening under the pointer: NavItem, and SectionHeader's `row` (a folder among rows). */
 export declare const SIDEBAR_ROW_CLASSES = "rounded-md transition-colors";
 export declare const SIDEBAR_ROW_TEXT_CLASSES = "text-text-secondary hover:text-text-primary";
+/**
+ * A panel that slides open and shut on Base UI's Collapsible: Base UI measures
+ * it and writes its height to a variable, `auto` again once the slide ends, and
+ * the panel is 0 high on its opening and closing frames. None under
+ * prefers-reduced-motion. CollapsibleSection's rows, and the rows under a NavItem.
+ */
+export declare const COLLAPSIBLE_PANEL_CLASSES = "h-[var(--collapsible-panel-height)] overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none data-[starting-style]:h-0 data-[ending-style]:h-0";
 //# sourceMappingURL=looks.d.ts.map

package/dist/looks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAC5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA"}
+{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAC5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.50.4",
+  "version": "0.51.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.50.4",
-    "exports": 104,
-    "typeExports": 113,
+    "packageVersion": "0.51.0",
+    "exports": 105,
+    "typeExports": 116,
     "files": null
   },
   "storybook": {
@@ -1089,6 +1089,12 @@
           "required": false,
           "note": "`heading` (default): the title is a section heading."
         },
+        {
+          "name": "indent",
+          "takes": "true/false",
+          "required": false,
+          "note": "With the `heading` look: the rows start under the title, past the chevron — a folder in a sidebar, its files lightly indented under its name (Katerina, 2 October)."
+        },
         {
           "name": "children",
           "takes": "anything",
@@ -3512,6 +3518,36 @@
           "required": false,
           "note": "The ⋮'s accessible name and tooltip. Default \"More options for {label}\"."
         },
+        {
+          "name": "hint",
+          "takes": "anything",
+          "required": false,
+          "note": "Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": false,
+          "note": "Rows under this one, folding under it: `NavItem`s."
+        },
+        {
+          "name": "defaultOpen",
+          "takes": "true/false",
+          "required": false,
+          "note": "With `children`: open unless told otherwise."
+        },
+        {
+          "name": "open",
+          "takes": "true/false",
+          "required": false,
+          "note": "With `children`: the caller owns the state."
+        },
+        {
+          "name": "onOpenChange",
+          "takes": "a handler",
+          "required": false,
+          "note": null
+        },
         {
           "name": "className",
           "takes": "text",
@@ -3520,7 +3556,12 @@
         }
       ],
       "variants": [],
-      "ownsBehaviours": [],
+      "ownsBehaviours": [
+        {
+          "id": "base-ui",
+          "behaviour": "Is built on Base UI"
+        }
+      ],
       "status": "stable",
       "migrationStage": null,
       "docsId": "frame-navitem--docs",
@@ -3531,9 +3572,66 @@
         "text-body-2 rounded-md transition-colors bg-bg-active text-text-primary",
         "text-body-2 rounded-md transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
         "text-center font-mono text-caption tabular-nums text-text-muted",
-        "text-center font-mono text-caption tabular-nums text-text-muted transition-opacity"
+        "text-center font-mono text-caption tabular-nums text-text-muted transition-opacity",
+        "overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none"
       ]
     },
+    {
+      "name": "NavTree",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/NavTree.tsx",
+      "purpose": "A sidebar's tree from one nested list: a quiet label, groups that fold under the standard heading with their rows lightly indented, and rows under rows to any depth.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "title",
+          "takes": "text",
+          "required": false,
+          "note": "The quiet label over the groups. Absent, none is drawn."
+        },
+        {
+          "name": "groups",
+          "takes": "NavTreeGroup[] | null",
+          "required": true,
+          "note": "`null` while the first read is on its way: a skeleton in the rows' place."
+        },
+        {
+          "name": "selected",
+          "takes": "text",
+          "required": false,
+          "note": "The row that is current: `active`, and its group starts open."
+        },
+        {
+          "name": "onSelect",
+          "takes": "a handler",
+          "required": false,
+          "note": "A row was clicked. A router app prevents the default and navigates."
+        },
+        {
+          "name": "emptyMessage",
+          "takes": "text",
+          "required": true,
+          "note": "What to say when there are no groups. The words are the caller's."
+        },
+        {
+          "name": "storageKey",
+          "takes": "text",
+          "required": false,
+          "note": "Remember each group open or closed in this browser, under this key and the group's id."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "frame-navtree--docs",
+      "storyId": "frame-navtree--default",
+      "docPage": "src/NavTree.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "normalizeHref",
       "repo": "estiva-ui",
@@ -4686,6 +4784,12 @@
           "required": false,
           "note": "Cut a long label short with an ellipsis instead of letting it wrap or spill."
         },
+        {
+          "name": "folds",
+          "takes": "true/false",
+          "required": false,
+          "note": "The title of a group that opens and closes."
+        },
         {
           "name": "className",
           "takes": "text",
@@ -4711,6 +4815,12 @@
       "docPage": "src/SectionLabel.mdx",
       "app": null,
       "looks": [
+        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-secondary",
+        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-secondary truncate",
+        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-muted",
+        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-muted truncate",
+        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-primary",
+        "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-primary truncate",
         "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-secondary",
         "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-secondary truncate",
         "text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest text-text-muted",

package/src/CollapsibleSection.mdx

@@ -28,6 +28,12 @@ toggle, and the rows under it, sliding shut and open.
 
 <Canvas of={CollapsibleSectionStories.AsARow} />
 
+- `indent` with the standard heading: its rows start under its title, past
+  the chevron — a group in a sidebar whose rows read as inside it. **NavTree**
+  draws its groups this way.
+
+<Canvas of={CollapsibleSectionStories.Indented} />
+
 In a sidebar — the Sidebar's own Composed canvas, which is where that
 composition lives:
 

package/src/CollapsibleSection.stories.tsx

@@ -47,3 +47,8 @@ export const Remembered: Story = { args: { storageKey: 'estiva-ui.stories.collap
 export const AsARow: Story = {
   args: { title: 'Folder', look: 'row' },
 }
+
+/** `indent`: the heading look, its rows starting under its title, past the chevron — a folder in a sidebar. */
+export const Indented: Story = {
+  args: { title: 'Group', indent: true },
+}

package/src/CollapsibleSection.tsx

@@ -2,6 +2,7 @@ import { useState, type ReactNode } from 'react'
 import { Collapsible } from '@base-ui/react/collapsible'
 import { cn } from './cn'
 import { SectionHeader, type SectionAction } from './SectionHeader'
+import { COLLAPSIBLE_PANEL_CLASSES } from './looks'
 
 /**
  * A section that opens and closes: a `SectionHeader` whose title is the
@@ -42,6 +43,12 @@ export interface CollapsibleSectionProps {
    * its title, past the chevron (`SectionHeader`'s `look`).
    */
   look?: 'heading' | 'row'
+  /**
+   * With the `heading` look: the rows start under the title, past the
+   * chevron — a folder in a sidebar, its files lightly indented under its
+   * name (Katerina, 2 October). The `row` look always indents.
+   */
+  indent?: boolean
   /** The rows. */
   children: ReactNode
   /** On the section's box: `mt-2` between groups, `shrink-0` in a scrolling column. */
@@ -72,7 +79,7 @@ function writeStored(key: string | undefined, open: boolean) {
   }
 }
 
-export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, storageKey, trailing, actions, showActions, look = 'heading', children, className, contentClassName }: CollapsibleSectionProps) {
+export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, storageKey, trailing, actions, showActions, look = 'heading', indent = false, children, className, contentClassName }: CollapsibleSectionProps) {
   const [openState, setOpenState] = useState(() => readStored(storageKey) ?? defaultOpen)
   const open = openProp ?? openState
   const setOpen = (next: boolean) => {
@@ -91,10 +98,11 @@ export function CollapsibleSection({ title, defaultOpen = true, open: openProp,
           prefers-reduced-motion. */}
       <Collapsible.Panel
         hiddenUntilFound
-        className="h-[var(--collapsible-panel-height)] overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none data-[starting-style]:h-0 data-[ending-style]:h-0"
+        className={COLLAPSIBLE_PANEL_CLASSES}
       >
-        {/* A row's rows start under its title: the 16px chevron and its 8px gap (pl-6). */}
-        <div className={cn('flex flex-col', look === 'row' && 'pl-6', contentClassName)}>{children}</div>
+        {/* A row's rows start under its title: the 16px chevron and its 8px gap
+            (pl-6). An indented heading's: its 12px chevron and 4px gap (pl-4). */}
+        <div className={cn('flex flex-col', look === 'row' ? 'pl-6' : indent && 'pl-4', contentClassName)}>{children}</div>
       </Collapsible.Panel>
     </Collapsible.Root>
   )

package/src/NavItem.mdx

@@ -28,6 +28,19 @@ count — a muted mono number whose tooltip says what it counts.
 
 <Canvas of={NavItemStories.WithMenu} />
 
+- A row with rows under it takes them as `children`: more `NavItem`s. The
+  row stays a link; while it is pointed at or focused, its icon becomes the
+  arrow that folds them, in the icon's own place, and they slide shut. For a
+  whole tree from one list, use **NavTree**.
+
+<Canvas of={NavItemStories.WithRowsUnder} />
+
+- A word that helps only while the row is pointed at — where the item comes
+  from — is `hint`: pass a neutral **Chip**. It shows left of the count, and
+  the label ends with "…" before it instead of running under it.
+
+<Canvas of={NavItemStories.WithHintLongLabel} />
+
 ## When not
 
 - An icon rail's tile → **RailItem**.
@@ -55,6 +68,11 @@ import { NavItem } from '@estiva-app/ui'
 - The label truncates; the count never gives up its width.
 - `menu` is the items only: `menu={<MenuItem label="Move to Folder…" onClick={move} />}`.
   The ⋮'s name is `More options for {label}` unless `menuLabel` says otherwise.
+- `children` start open; `defaultOpen={false}` starts them folded, and
+  `open` with `onOpenChange` hands the state to the app. The arrow's name is
+  `Hide what is under {label}` or `Show what is under {label}`.
+- `hint` takes room only while it shows, so a label at rest keeps its full
+  width.
 
 - A row is 32px tall, 8px in on each side, 8px between the icon and the label,
   the label 14px regular, 6px corners.
@@ -68,6 +86,18 @@ It does these by itself. Write none of them around it.
 | Marks the current place for assistive technology when `active` | `aria-current` |  |
 | Keeps its 32px in a scrolling column | `shrink-0` |  |
 | Shows a ⋮ over the count while pointed at, focused or open, and keeps the row's hover look under it | a positioned `IconButton` + `Menu` over the row, `group-hover` reveals |  |
+| Turns its icon into the arrow that folds `children` while pointed at or focused, and slides them | a positioned `IconButton` over the icon, open state, `group-hover` reveals, an indented box |  |
+| Tells assistive technology whether its rows are open | `aria-expanded`, `aria-controls` |  |
+| Shows `hint` only while pointed at or focused, and makes the label give way | a positioned chip over the row, `group-hover` reveals |  |
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Tab | the link, then its arrow (with `children`), then its ⋮ (with `menu`) |
+| Enter, Space | on the arrow: folds or unfolds the rows under it |
+
+The rows are not an ARIA tree: there are no arrow keys between rows yet.
 
 ## Props
 

package/src/NavItem.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconSquareRounded } from '@tabler/icons-react'
+import { Chip } from './Chip'
 import { MenuItem } from './Menu'
 import { NavItem } from './NavItem'
 
@@ -60,3 +61,36 @@ export const WithMenuActive: Story = {
 export const WithMenuNoCount: Story = {
   args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, menu: MENU },
 }
+
+/** A hint shows only while the row is pointed at or focused, left of the count: here a neutral Chip. */
+export const WithHint: Story = {
+  args: { icon: placeholder, count: 3, countLabel: '3 open', hint: <Chip type="neutral" label="Label" /> },
+}
+
+/** A long label gives way to the hint while it shows: it ends with "…" before the chip instead of running under it. */
+export const WithHintLongLabel: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, count: 12, countLabel: '12 open', hint: <Chip type="neutral" label="Label" /> },
+}
+
+/** Rows under a row: point at it and its icon becomes the arrow that folds them. The row itself stays a link. */
+export const WithRowsUnder: Story = {
+  args: { icon: placeholder },
+  render: (args) => (
+    <NavItem {...args}>
+      <NavItem href="#" label="Item two" icon={placeholder} />
+      <NavItem href="#" label="Item three" icon={placeholder}>
+        <NavItem href="#" label="Item four" icon={placeholder} />
+      </NavItem>
+    </NavItem>
+  ),
+}
+
+/** Starts folded: point at it, or Tab to its arrow, to open it. */
+export const WithRowsUnderClosed: Story = {
+  args: { icon: placeholder, defaultOpen: false },
+  render: (args) => (
+    <NavItem {...args}>
+      <NavItem href="#" label="Item two" icon={placeholder} />
+    </NavItem>
+  ),
+}

package/src/NavItem.test.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+/**
+ * What the page claims for the rows under a row and the hint: the arrow folds
+ * the rows and says so, the rows are hidden rather than gone, the row itself
+ * stays a link a click does not fold, and the hint is there to be revealed.
+ * The reveal on hover and the slide are Chrome's to show.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { NavItem } from './NavItem'
+
+afterEach(cleanup)
+
+const arrow = (name: RegExp) => screen.getByRole('button', { name })
+
+describe('NavItem with rows under it', () => {
+  const tree = (props: Partial<Parameters<typeof NavItem>[0]> = {}) => (
+    <NavItem href="#one" label="Item one" {...props}>
+      <NavItem href="#two" label="Item two" />
+    </NavItem>
+  )
+
+  it('starts open: the arrow says so and names what it folds, and the rows are there', () => {
+    render(tree())
+    const button = arrow(/Hide what is under Item one/)
+    expect(button.getAttribute('aria-expanded')).toBe('true')
+    expect(document.getElementById(button.getAttribute('aria-controls') ?? '')).not.toBeNull()
+    expect(screen.getByText('Item two').closest('[hidden]')).toBeNull()
+  })
+
+  it('the arrow folds the rows, hidden rather than gone, and unfolds them', async () => {
+    render(tree())
+    await userEvent.click(arrow(/Hide what is under Item one/))
+    expect(arrow(/Show what is under Item one/).getAttribute('aria-expanded')).toBe('false')
+    expect(screen.getByText('Item two').closest('[hidden]')).not.toBeNull()
+    await userEvent.click(arrow(/Show what is under Item one/))
+    expect(screen.getByText('Item two').closest('[hidden]')).toBeNull()
+  })
+
+  it('a click on the row is the link’s, and does not fold it', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(tree({ onClick }))
+    await userEvent.click(screen.getByRole('link', { name: 'Item one' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(arrow(/Hide what is under Item one/).getAttribute('aria-expanded')).toBe('true')
+  })
+
+  it('starts folded with defaultOpen false, and reports a change through onOpenChange', async () => {
+    const onOpenChange = vi.fn()
+    render(tree({ defaultOpen: false, onOpenChange }))
+    expect(screen.getByText('Item two').closest('[hidden]')).not.toBeNull()
+    await userEvent.click(arrow(/Show what is under Item one/))
+    expect(onOpenChange).toHaveBeenCalledWith(true)
+  })
+
+  it('Enter on the arrow folds the rows', async () => {
+    render(tree())
+    arrow(/Hide what is under Item one/).focus()
+    await userEvent.keyboard('{Enter}')
+    expect(arrow(/Show what is under Item one/).getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('a row with a menu and rows under it: the open rows do not hold the ⋮ open', () => {
+    render(tree({ menu: <span>Action</span> }))
+    const menu = screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')
+    expect(menu).not.toBeNull()
+    expect(menu?.querySelector('[aria-expanded=true]')).toBeNull()
+  })
+})
+
+describe('NavItem with a hint', () => {
+  it('draws the hint inside the row, beside the label', () => {
+    render(<NavItem href="#" label="Item one" hint={<span>Label</span>} />)
+    expect(screen.getByRole('link', { name: /Item one/ }).textContent).toContain('Label')
+  })
+
+  it('without children, a menu or a hint, the row is the bare link', () => {
+    const { container } = render(<NavItem href="#" label="Item one" />)
+    expect(container.firstElementChild?.tagName).toBe('A')
+  })
+})

package/src/NavItem.tsx

@@ -1,7 +1,8 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react'
-import { IconDotsVertical } from '@tabler/icons-react'
+import { useId, useState, type ComponentPropsWithoutRef, type ReactNode } from 'react'
+import { Collapsible } from '@base-ui/react/collapsible'
+import { IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
 import { cn } from './cn'
-import { SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
+import { COLLAPSIBLE_PANEL_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { Menu } from './Menu'
 import { WithTooltip } from './Tooltip'
@@ -22,8 +23,19 @@ import { WithTooltip } from './Tooltip'
  * menu is open, in the count's place — the count steps aside rather than
  * sitting under it. The ⋮ is beside the link, not inside it (a button inside
  * an anchor is not a button), and follows it in the Tab order.
+ *
+ * `children` are rows under this one (Katerina, 2 October: Leaf's folder
+ * tree). The row stays a link; while it is pointed at or focused its icon
+ * gives way to an arrow that folds the rows, in the icon's own place — so a
+ * row with rows under it is as wide as one without. The arrow is beside the
+ * link, like the ⋮. The rows slide as `CollapsibleSection`'s do, indented
+ * past the icon so their icons start under this row's label.
+ *
+ * `hint` is shown only while the row is pointed at or focused, left of the
+ * count — a neutral `Chip`, typically. It takes its own room while it shows,
+ * so the label ends with "…" before it instead of running under it.
  */
-export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'> {
+export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'children'> {
   label: string
   href: string
   /** `0` or absent renders no counter. */
@@ -37,10 +49,47 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
   menu?: ReactNode
   /** The ⋮'s accessible name and tooltip. Default "More options for {label}". */
   menuLabel?: string
+  /** Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically. */
+  hint?: ReactNode
+  /** Rows under this one, folding under it: `NavItem`s. While the row is pointed at or focused, its icon becomes the arrow. */
+  children?: ReactNode
+  /** With `children`: open unless told otherwise. */
+  defaultOpen?: boolean
+  /** With `children`: the caller owns the state. */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
   className?: string
 }
 
-export function NavItem({ label, href, count, countLabel, active = false, icon, menu, menuLabel, className, ...props }: NavItemProps) {
+export function NavItem({
+  label,
+  href,
+  count,
+  countLabel,
+  active = false,
+  icon,
+  menu,
+  menuLabel,
+  hint,
+  children,
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange,
+  className,
+  ...props
+}: NavItemProps) {
+  const [openState, setOpenState] = useState(defaultOpen)
+  const panelId = useId()
+  const hasRows = children != null && children !== false
+  const open = openProp ?? openState
+  const setOpen = (next: boolean) => {
+    setOpenState(next)
+    onOpenChange?.(next)
+  }
+  // The row draws beside it — the ⋮, the arrow — so the pointer can leave the
+  // link for them while the row still reads as the one it is on.
+  const besides = menu != null || hasRows
+
   const row = (
     <a
       href={href}
@@ -53,14 +102,30 @@ export function NavItem({ label, href, count, countLabel, active = false, icon,
         SIDEBAR_ROW_CLASSES,
         active ? 'bg-bg-active text-text-primary' : cn(SIDEBAR_ROW_TEXT_CLASSES, 'hover:bg-bg-hover'),
         // With a menu the ⋮ sits beside the link, so the row keeps its hover
-        // look while the ⋮ is pointed at and while its menu is open.
-        menu != null && !active && 'group-hover/nav:bg-bg-hover group-hover/nav:text-text-primary group-has-[[aria-expanded=true]]/nav:bg-bg-hover group-has-[[aria-expanded=true]]/nav:text-text-primary',
+        // look while the ⋮ is pointed at and while its menu is open. The same
+        // for the arrow.
+        besides && !active && 'group-hover/nav:bg-bg-hover group-hover/nav:text-text-primary',
+        menu != null && !active && 'group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:bg-bg-hover group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:text-text-primary',
         className,
       )}
       {...props}
     >
-      {icon && <span className="flex shrink-0 items-center">{icon}</span>}
+      {(icon || hasRows) && (
+        <span
+          className={cn(
+            // With rows under it the slot is kept even with no icon: the arrow lands in it.
+            'flex min-w-4 shrink-0 items-center',
+            hasRows && 'transition-opacity group-hover/nav:opacity-0 group-focus-within/nav:opacity-0',
+          )}
+        >
+          {icon}
+        </span>
+      )}
       <span className="flex-1 truncate">{label}</span>
+      {hint != null && (
+        // Takes room only while it shows, so the label gives way to it.
+        <span className="hidden shrink-0 items-center group-hover/nav:flex group-focus-within/nav:flex">{hint}</span>
+      )}
       {count ? (
         <WithTooltip label={countLabel ?? `${count} open`}>
           {/* A 16px box, centred: the slot is an icon's width, so a number
@@ -71,7 +136,7 @@ export function NavItem({ label, href, count, countLabel, active = false, icon,
             className={cn(
               'min-w-4 shrink-0 text-center font-mono text-caption tabular-nums text-text-muted',
               // With a menu, the ⋮ takes this place while it shows.
-              menu != null && 'transition-opacity group-hover/nav:opacity-0 group-focus-within/nav:opacity-0 group-has-[[aria-expanded=true]]/nav:opacity-0',
+              menu != null && 'transition-opacity group-hover/nav:opacity-0 group-focus-within/nav:opacity-0 group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:opacity-0',
             )}
           >
             {count}
@@ -84,25 +149,58 @@ export function NavItem({ label, href, count, countLabel, active = false, icon,
       ) : null}
     </a>
   )
-  if (menu == null) return row
+  if (!besides && hint == null) return row
   const name = menuLabel ?? `More options for ${label}`
-  return (
+  const line = (
     <div className="group/nav relative shrink-0">
       {row}
-      {/* `right-1`: the 24px button's 16px icon then ends 8px from the row's
-          edge, where the count ends (px-2), so the ⋮ lands on the number. */}
-      <div className="absolute inset-y-0 right-1 flex items-center opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100">
-        <Menu
-          align="right"
-          trigger={
-            <IconButton tooltip="More options" aria-label={name}>
-              <IconDotsVertical size={16} stroke={1.5} />
-            </IconButton>
-          }
-        >
-          {menu}
-        </Menu>
-      </div>
+      {hasRows && (
+        // `left-1`: the 24px button's 16px arrow then sits where the icon
+        // sits (the row's px-2), so the icon turns into the arrow in place.
+        <div className="absolute inset-y-0 left-1 flex items-center opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100">
+          <IconButton
+            tooltip={open ? 'Collapse' : 'Expand'}
+            aria-label={open ? `Hide what is under ${label}` : `Show what is under ${label}`}
+            aria-expanded={open}
+            aria-controls={panelId}
+            onClick={() => setOpen(!open)}
+          >
+            <IconChevronRight size={16} stroke={1.5} className={cn('transition-transform duration-150', open && 'rotate-90')} />
+          </IconButton>
+        </div>
+      )}
+      {menu != null && (
+        // `right-1`: the 24px button's 16px icon then ends 8px from the row's
+        // edge, where the count ends (px-2), so the ⋮ lands on the number.
+        <div data-nav-menu className="absolute inset-y-0 right-1 flex items-center opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100">
+          <Menu
+            align="right"
+            trigger={
+              <IconButton tooltip="More options" aria-label={name}>
+                <IconDotsVertical size={16} stroke={1.5} />
+              </IconButton>
+            }
+          >
+            {menu}
+          </Menu>
+        </div>
+      )}
     </div>
   )
+  if (!hasRows) return line
+  return (
+    <Collapsible.Root open={open} onOpenChange={setOpen} className="flex shrink-0 flex-col">
+      {line}
+      {/* CollapsibleSection's slide, the same way: Base UI measures the panel
+          and the height transitions, none under prefers-reduced-motion. */}
+      <Collapsible.Panel
+        id={panelId}
+        hiddenUntilFound
+        className={COLLAPSIBLE_PANEL_CLASSES}
+      >
+        {/* `pl-6`: past the 16px icon and its 8px gap, so the rows' icons start under this row's label. */}
+        <div className="flex flex-col gap-px pl-6">{children}</div>
+      </Collapsible.Panel>
+    </Collapsible.Root>
+  )
 }