@estiva-app/ui 0.50.4 → 0.51.0

package/src/NavTree.mdx

@@ -0,0 +1,83 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as NavTreeStories from './NavTree.stories'
+
+<Meta of={NavTreeStories} />
+
+# NavTree
+
+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.
+
+<Canvas of={NavTreeStories.Default} />
+
+## When
+
+- Places that nest, in a **Sidebar**: groups, rows in them, rows under
+  those rows. Hand it the whole list; it draws every level.
+- `selected` is the current row: it is `active`, and only its group starts
+  open. Rows with rows under them start open.
+
+<Canvas of={NavTreeStories.CurrentDeep} />
+
+- A row's `hint` (a neutral **Chip**), `count` and `menu` are **NavItem**'s,
+  passed through.
+- `groups={null}` while the first read is on its way draws a skeleton;
+  `[]` draws `emptyMessage`, level with the rows.
+
+<Canvas of={NavTreeStories.Loading} />
+
+## When not
+
+- A flat list of places → **NavItem** rows in the **Sidebar**.
+- One group that folds, written by hand → **CollapsibleSection**.
+- A list beside the thing that is open → **ListColumn**.
+
+## How
+
+```tsx
+import { NavTree, Sidebar } from '@estiva-app/ui'
+
+<Sidebar>
+  <NavTree
+    title="Groups"
+    groups={groups}
+    selected={currentId}
+    onSelect={(node, event) => {
+      event.preventDefault()
+      navigate(node.href)
+    }}
+    emptyMessage="Nothing here yet."
+    storageKey="app.sidebar.groups"
+  />
+</Sidebar>
+```
+
+- Each row is a **NavItem**, so a row is a link: a router app prevents the
+  default in `onSelect` and navigates.
+- `storageKey` remembers each group open or closed in this browser, under
+  the key and the group's id. The rows under a row are not remembered yet.
+- The words in `emptyMessage` are the caller's.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Draws every level from one list, rows under rows | a recursive render of **NavItem**s and **CollapsibleSection**s |  |
+| Opens the group that holds the current row | a search through the list for the current row |  |
+| Says it is loading, or empty, in the rows' place | a skeleton or an **EmptyState** placed by hand |  |
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Tab | each group's title, then its rows: each row's link, then its arrow |
+| Enter, Space | on a group's title or a row's arrow: folds or unfolds |
+
+It is not an ARIA tree yet: there are no arrow keys between rows.
+
+## Props
+
+<Controls of={NavTreeStories.Default} />

package/src/NavTree.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { useState } from 'react'
+import { Chip } from './Chip'
+import { NavItem } from './NavItem'
+import { NavTree, type NavTreeGroup } from './NavTree'
+import { Sidebar } from './Sidebar'
+
+const placeholder = <IconSquareRounded size={16} stroke={1.5} />
+const hint = <Chip type="neutral" label="Label" />
+
+/** Three groups; the open one holds rows under rows, hints and counts, and long labels to see what fits. */
+const GROUPS: NavTreeGroup[] = [
+  { id: 'g1', title: 'Group one', nodes: [{ id: 'a', label: 'Item two', href: '#', icon: placeholder }] },
+  {
+    id: 'g2',
+    title: 'A group with a longer name',
+    nodes: [
+      { id: 'b', label: 'Item three', href: '#', icon: placeholder, count: 1, countLabel: '1 open' },
+      {
+        id: 'c',
+        label: 'An item whose label runs longer than the column',
+        href: '#',
+        icon: placeholder,
+        children: [
+          { id: 'c1', label: 'An item one level in, also long', href: '#', icon: placeholder, count: 2, countLabel: '2 open' },
+          { id: 'c2', label: 'Item four', href: '#', icon: placeholder, children: [{ id: 'c21', label: 'An item two levels in, long too', href: '#', icon: placeholder }] },
+        ],
+      },
+      { id: 'd', label: 'An item with a hint and a long label', href: '#', icon: placeholder, hint, count: 3, countLabel: '3 open' },
+      { id: 'e', label: 'Item five', href: '#', icon: placeholder, hint },
+      { id: 'f', label: 'An item with a hint and a count', href: '#', icon: placeholder, hint, count: 12, countLabel: '12 open' },
+    ],
+  },
+  { id: 'g3', title: 'Group three', nodes: [{ id: 'g', label: 'Item six', href: '#', icon: placeholder }] },
+]
+
+const meta = {
+  title: 'Frame/NavTree',
+  component: NavTree,
+  parameters: { layout: 'fullscreen' },
+  args: { title: 'Groups', groups: GROUPS, selected: 'b', emptyMessage: 'Nothing here yet.' },
+  argTypes: { groups: { control: false } },
+  // In the Sidebar, under a first row, as it sits in an app; a click marks the row it was on.
+  render: function Render(args) {
+    const [selected, setSelected] = useState(args.selected)
+    return (
+      <div className="flex h-screen bg-bg-base">
+        <Sidebar>
+          <NavItem href="#" label="Item one" icon={placeholder} />
+          <NavTree
+            {...args}
+            selected={selected}
+            onSelect={(node, event) => {
+              event.preventDefault()
+              setSelected(node.id)
+            }}
+          />
+        </Sidebar>
+      </div>
+    )
+  },
+} satisfies Meta<typeof NavTree>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Only the group holding the current row starts open. Point at a row with rows under it: its icon becomes the arrow. Point at a row with a hint: the chip shows. */
+export const Default: Story = {}
+
+/** The current row is two levels in: its group opens, and the rows above it are open too. */
+export const CurrentDeep: Story = { args: { selected: 'c21' } }
+
+/** No quiet label over the groups. */
+export const NoTitle: Story = { args: { title: undefined } }
+
+/** The first read is on its way. */
+export const Loading: Story = { args: { groups: null } }
+
+/** No groups: the caller's words, level with the rows. */
+export const Empty: Story = { args: { groups: [] } }
+
+/** Close a group and reload the page: still closed. This browser remembers each group, under the key. */
+export const Remembered: Story = { args: { storageKey: 'estiva-ui.stories.nav-tree' } }

package/src/NavTree.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+/**
+ * What the page claims: every level is drawn from the one list; only the
+ * group holding the current row starts open, and the current row is active;
+ * a click reaches onSelect with its node; loading and empty say so.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { NavTree, type NavTreeGroup } from './NavTree'
+
+afterEach(cleanup)
+
+const GROUPS: NavTreeGroup[] = [
+  { id: 'g1', title: 'Group one', nodes: [{ id: 'a', label: 'Item a', href: '#a' }] },
+  {
+    id: 'g2',
+    title: 'Group two',
+    nodes: [{ id: 'b', label: 'Item b', href: '#b', children: [{ id: 'c', label: 'Item c', href: '#c', children: [{ id: 'd', label: 'Item d', href: '#d' }] }] }],
+  },
+]
+
+const hidden = (text: string) => screen.getByText(text).closest('[hidden]') !== null
+
+describe('NavTree', () => {
+  it('draws every level, and opens only the group holding the current row', () => {
+    render(<NavTree groups={GROUPS} selected="d" emptyMessage="Nothing here yet." />)
+    expect(hidden('Item a')).toBe(true)
+    expect(hidden('Item d')).toBe(false)
+    expect(screen.getByRole('link', { name: 'Item d' }).getAttribute('aria-current')).toBe('page')
+  })
+
+  it('a click reaches onSelect with the node it was on', async () => {
+    const onSelect = vi.fn((_node, event: { preventDefault: () => void }) => event.preventDefault())
+    render(<NavTree groups={GROUPS} selected="b" onSelect={onSelect} emptyMessage="Nothing here yet." />)
+    await userEvent.click(screen.getByRole('link', { name: 'Item c' }))
+    expect(onSelect.mock.calls[0][0].id).toBe('c')
+  })
+
+  it('draws the quiet label when given one', () => {
+    render(<NavTree title="Groups" groups={GROUPS} emptyMessage="Nothing here yet." />)
+    expect(screen.getByText('Groups')).not.toBeNull()
+  })
+
+  it('says it is empty in the caller’s words', () => {
+    render(<NavTree groups={[]} emptyMessage="Nothing here yet." />)
+    expect(screen.getByText('Nothing here yet.')).not.toBeNull()
+  })
+
+  it('draws no rows while loading', () => {
+    render(<NavTree groups={null} emptyMessage="Nothing here yet." />)
+    expect(screen.queryAllByRole('link')).toHaveLength(0)
+  })
+})

package/src/NavTree.tsx

@@ -0,0 +1,112 @@
+import type { MouseEvent, ReactNode } from 'react'
+import { CollapsibleSection } from './CollapsibleSection'
+import { EmptyState } from './EmptyState'
+import { NavItem } from './NavItem'
+import { SectionHeader } from './SectionHeader'
+import { SkeletonList } from './Skeleton'
+
+/** One row of the tree, and the rows under it. */
+export interface NavTreeNode {
+  id: string
+  label: string
+  href: string
+  /** 16px, stroke 1.5. */
+  icon?: ReactNode
+  /** `0` or absent renders no counter. */
+  count?: number
+  /** What the count counts, for the tooltip. */
+  countLabel?: string
+  /** Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically. */
+  hint?: ReactNode
+  /** The row's "More options" menu: `MenuItem`s. */
+  menu?: ReactNode
+  /** Rows under this one. Their row folds them; open unless `defaultOpen` says otherwise. */
+  children?: NavTreeNode[]
+  defaultOpen?: boolean
+}
+
+/** A group heading over its rows: the top of the tree. */
+export interface NavTreeGroup {
+  id: string
+  title: string
+  nodes: NavTreeNode[]
+}
+
+export interface NavTreeProps {
+  /** The quiet label over the groups. Absent, none is drawn. */
+  title?: string
+  /** `null` while the first read is on its way: a skeleton in the rows' place. */
+  groups: NavTreeGroup[] | null
+  /** The row that is current: `active`, and its group starts open. */
+  selected?: string
+  /** A row was clicked. A router app prevents the default and navigates. */
+  onSelect?: (node: NavTreeNode, event: MouseEvent<HTMLAnchorElement>) => void
+  /** What to say when there are no groups. The words are the caller's. */
+  emptyMessage: string
+  /** Remember each group open or closed in this browser, under this key and the group's id. The app prefixes it. */
+  storageKey?: string
+}
+
+function holds(nodes: NavTreeNode[], id: string | undefined): boolean {
+  return id !== undefined && nodes.some((node) => node.id === id || holds(node.children ?? [], id))
+}
+
+function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeProps, 'selected' | 'onSelect'>) {
+  return (
+    <NavItem
+      href={node.href}
+      label={node.label}
+      icon={node.icon}
+      count={node.count}
+      countLabel={node.countLabel}
+      hint={node.hint}
+      menu={node.menu}
+      active={node.id === selected}
+      defaultOpen={node.defaultOpen ?? true}
+      onClick={onSelect ? (event) => onSelect(node, event) : undefined}
+    >
+      {node.children?.length
+        ? node.children.map((child) => <Row key={child.id} node={child} selected={selected} onSelect={onSelect} />)
+        : undefined}
+    </NavItem>
+  )
+}
+
+/**
+ * A sidebar's tree, from one nested list (Katerina, 2 October: Leaf's folder
+ * tree): a quiet label, then each group as the standard heading folding its
+ * rows, lightly indented under its title; rows under rows to any depth, each
+ * row a link whose icon becomes the arrow that folds what is under it. Only
+ * the group that holds the current row starts open.
+ */
+export function NavTree({ title, groups, selected, onSelect, emptyMessage, storageKey }: NavTreeProps) {
+  return (
+    <>
+      {title && <SectionHeader title={title} look="quiet" className="mt-4 shrink-0" />}
+      {groups === null ? (
+        <SkeletonList rows={5} />
+      ) : groups.length === 0 ? (
+        // Level with the rows: a row pads itself, so the line takes a row's inset (Katerina, 14 September).
+        <div className="px-2 py-1">
+          <EmptyState scope="section" message={emptyMessage} />
+        </div>
+      ) : (
+        groups.map((group) => (
+          <CollapsibleSection
+            key={group.id}
+            title={group.title}
+            indent
+            defaultOpen={holds(group.nodes, selected)}
+            storageKey={storageKey ? `${storageKey}.${group.id}` : undefined}
+            className="mt-2 shrink-0"
+            contentClassName="gap-px"
+          >
+            {group.nodes.map((node) => (
+              <Row key={node.id} node={node} selected={selected} onSelect={onSelect} />
+            ))}
+          </CollapsibleSection>
+        ))
+      )}
+    </>
+  )
+}

package/src/SectionHeader.tsx

@@ -106,7 +106,7 @@ export function SectionHeader({ title, chevron = false, isExpanded = true, onTog
             // A row's words: NavItem's size and colour, brightening under the pointer with the row.
             <span className="min-w-0 flex-1 truncate text-body-2">{title}</span>
           ) : (
-            <SectionLabel>{title}</SectionLabel>
+            <SectionLabel folds={chevron}>{title}</SectionLabel>
           )}
         </>
       ),

package/src/SectionLabel.mdx

@@ -40,7 +40,10 @@ It is a bare span: the caller owns the row it sits in and the spacing
 around it. Read it `tone="secondary"` where it labels rather than leads — menu
 headings and the command palette's groups do. `tone="muted"` where it marks a
 place in a list rather than heading it — a date between messages. `truncate`
-cuts a long label short with an ellipsis where its row has no room. A colour
+cuts a long label short with an ellipsis where its row has no room. `folds`
+is the title of a group that opens and closes: **SectionHeader** passes it
+whenever it draws the chevron, so in Leaf a folding group keeps Ship's type
+while every other label takes Signal's. A colour
 passed in `className` is refused by the lint.
 
 - Import it — never copy its classes. A copied class list drifts the first time

package/src/SectionLabel.stories.tsx

@@ -45,3 +45,6 @@ export const Truncated: Story = {
     </div>
   ),
 }
+
+/** The title of a group that folds: in Leaf it keeps Ship's type; in Signal and Ship it looks like any label. Switch the toolbar to Leaf to see the difference. */
+export const Folds: Story = { args: { folds: true, children: 'Group' } }

package/src/SectionLabel.tsx

@@ -18,6 +18,10 @@ import { cn } from './cn'
  * long label short with an ellipsis where its row has no room, as a date line in
  * a narrow panel must.
  *
+ * `folds` is the title of a group that opens and closes: in Leaf it keeps
+ * Ship's type rather than taking Signal's micro-label, so a folder reads as
+ * a name (Katerina, 2 October). Every other Leaf label keeps Signal's.
+ *
  * Deliberately NOT the same thing as Property's stacked field label (the
  * 9px `menu`-token one): they were merged for a day and unmerged by
  * Katerina's ruling (2026-09-01) — a section title and a field label are
@@ -27,20 +31,24 @@ export function SectionLabel({
   children,
   tone = 'primary',
   truncate = false,
+  folds = false,
   className,
 }: {
   children: ReactNode
   tone?: 'primary' | 'secondary' | 'muted'
   /** Cut a long label short with an ellipsis instead of letting it wrap or spill. */
   truncate?: boolean
+  /** The title of a group that opens and closes. In Leaf, Ship's type instead of the micro-label. */
+  folds?: boolean
   className?: string
 }) {
   return (
     <span
       className={cn(
         'text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest',
-        // Leaf's section labels are Signal's type (Katerina, 28 September).
-        'leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest',
+        // Leaf's section labels are Signal's type (Katerina, 28 September),
+        // but a group that folds keeps Ship's (Katerina, 2 October).
+        !folds && 'leaf:font-mono leaf:text-small leaf:uppercase leaf:tracking-widest',
         tone === 'secondary' ? 'text-text-secondary' : tone === 'muted' ? 'text-text-muted' : 'text-text-primary',
         truncate && 'min-w-0 truncate',
         className,

package/src/eslint/no-native-title.ts

@@ -8,7 +8,7 @@ import { bindingOfTag, partsOfFile, type Node, type Parser, type PartBinding } f
  * the browser shows it as its tooltip. `no-native-title.test.ts` holds this
  * list to the catalogue: a part that gains a `title` of its own joins it.
  */
-export const PARTS_WITH_A_TITLE = ['CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'DialogShell', 'ListColumn', 'Panel', 'SectionHeader'] as const
+export const PARTS_WITH_A_TITLE = ['CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'DialogShell', 'ListColumn', 'NavTree', 'Panel', 'SectionHeader'] as const
 
 const child = (node: Node, key: string) => node[key] as Node | null | undefined
 const nameOf = (node: Node | null | undefined): string | undefined =>

package/src/index.ts

@@ -70,6 +70,7 @@ export { SkeletonBar, SkeletonList, SkeletonRow } from './Skeleton'
 export { Breadcrumb, type BreadcrumbProps, type Crumb } from './Breadcrumb'
 export { EnterHint, Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSeparator, MenuSub, type MenuItemProps, type MenuPanelProps, type MenuProps, type MenuSubProps } from './Menu'
 export { NavItem, type NavItemProps } from './NavItem'
+export { NavTree, type NavTreeGroup, type NavTreeNode, type NavTreeProps } from './NavTree'
 export { Popover, type PopoverProps } from './Popover'
 export { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuProps, type SuggestionMenuRow, type SuggestionMenuSection } from './SuggestionMenu'
 export { ScrollArea, type ScrollAreaProps } from './ScrollArea'

package/src/looks.ts

@@ -46,3 +46,11 @@ export const BARE_INPUT_CLASSES = 'bg-transparent text-text-primary placeholder:
 /** A sidebar row's shape and its words at rest, brightening under the pointer: NavItem, and SectionHeader's `row` (a folder among rows). */
 export const SIDEBAR_ROW_CLASSES = 'rounded-md transition-colors'
 export 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 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'

package/src/registry/registry.test.ts

@@ -48,18 +48,18 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 104 names over 64 files: 90 components, 13 helpers and 1 hook (the block nodes joined on 30 September, MAN-9)', () => {
+  it('counts 105 names over 65 files: 91 components, 13 helpers and 1 hook (NavTree joined on 2 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The five `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's and BlockNodes' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 90, helper: 13, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(64)
+    expect(kinds).toEqual({ component: 91, helper: 13, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(65)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(61)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(62)
     expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(43)
   })
 

package/stories/Choosing.mdx

@@ -116,6 +116,7 @@ the **floating** TopBar goes with the **Rail** and the content card.
 | The floating frame: bar over the content, rail, rounded card | **AppShell** `floating` |
 | The 52px bar alone | **TopBar** — `solid` in flow, or `floating` over the content |
 | A 240px navigation column | **Sidebar**, filled with **NavItem** rows |
+| Groups of rows in that column, rows under rows, from one nested list | **NavTree**, inside the **Sidebar** |
 | A 64px icon strip | **Rail**, filled with **RailItem** tiles |
 | The menu button and the logo | the TopBar's `menu` and `logo` slots — collapsing stays yours |
 | The list beside the thing that is open | **ListColumn** — 290px, its name in a **ContainerHeader**, the list under it scrolling |