@estiva-app/ui 0.53.1 → 0.54.0

package/dist/looks.d.ts

@@ -34,7 +34,7 @@ export declare const CHIP_TEXT_CLASSES = "text-chip signal:font-mono signal:text
 /** Words typed straight into an input with no box of its own: SearchInput and ChipInput. */
 export declare const BARE_INPUT_CLASSES = "bg-transparent text-text-primary placeholder:text-text-muted outline-none";
 /** 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_CLASSES = "rounded-lg 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

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;AAErF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,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;AAE5I,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.53.1",
+  "version": "0.54.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.53.1",
-    "exports": 120,
-    "typeExports": 128,
+    "packageVersion": "0.54.0",
+    "exports": 122,
+    "typeExports": 129,
     "files": null
   },
   "storybook": {
@@ -3657,6 +3657,18 @@
           "required": false,
           "note": "Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically."
         },
+        {
+          "name": "unread",
+          "takes": "true/false",
+          "required": false,
+          "note": "Something new here: brighter words, the label in medium, and the `UnreadDot` at the right."
+        },
+        {
+          "name": "urgent",
+          "takes": "true/false",
+          "required": false,
+          "note": "With `unread`: the warning badge in the dot's place."
+        },
         {
           "name": "children",
           "takes": "anything",
@@ -3702,8 +3714,9 @@
       "docPage": "src/NavItem.mdx",
       "app": null,
       "looks": [
-        "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-body-2 rounded-lg transition-colors bg-bg-nav-active text-text-primary",
+        "text-body-2 rounded-lg transition-colors text-text-primary hover:bg-bg-hover",
+        "text-body-2 rounded-lg 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",
         "overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none"
@@ -3724,11 +3737,23 @@
           "required": false,
           "note": "The quiet label over the groups. Absent, none is drawn."
         },
+        {
+          "name": "titleActions",
+          "takes": "SectionAction[]",
+          "required": false,
+          "note": "Beside the label, always shown: \"New\", typically."
+        },
         {
           "name": "groups",
           "takes": "NavTreeGroup[] | null",
-          "required": true,
-          "note": "`null` while the first read is on its way: a skeleton in the rows' place."
+          "required": false,
+          "note": "`null` while the first read is on its way: a skeleton in the groups' place."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": false,
+          "note": "The groups, drawn by the app: `NavTreeSection`s with `NavItem` rows — for an app whose groups and rows each read their own data."
         },
         {
           "name": "selected",
@@ -3745,8 +3770,8 @@
         {
           "name": "emptyMessage",
           "takes": "text",
-          "required": true,
-          "note": "What to say when there are no groups. The words are the caller's."
+          "required": false,
+          "note": "What to say when `groups` is empty. The words are the caller's; absent, nothing is said."
         },
         {
           "name": "storageKey",
@@ -3765,6 +3790,98 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "NavTreeSection",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/NavTree.tsx",
+      "purpose": "One group of a `NavTree`, for an app that draws its own: the standard heading folding its rows, lightly indented under its title, with the group's line, skeleton, actions and `onIntent`.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "title",
+          "takes": "text",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "id",
+          "takes": "text",
+          "required": false,
+          "note": "Marks the group's box as `data-nav-group`, for tests and photo runs to find it."
+        },
+        {
+          "name": "message",
+          "takes": "text",
+          "required": false,
+          "note": "Said in the rows' place, level with them."
+        },
+        {
+          "name": "trailing",
+          "takes": "anything",
+          "required": false,
+          "note": "Beside the title, always shown: an `UnreadDot`, typically."
+        },
+        {
+          "name": "actions",
+          "takes": "SectionAction[]",
+          "required": false,
+          "note": "Beside the title, shown on hover or focus: \"Open\", typically."
+        },
+        {
+          "name": "defaultOpen",
+          "takes": "true/false",
+          "required": false,
+          "note": "Open unless told otherwise."
+        },
+        {
+          "name": "open",
+          "takes": "true/false",
+          "required": false,
+          "note": "The caller owns whether the group is open."
+        },
+        {
+          "name": "onOpenChange",
+          "takes": "a handler",
+          "required": false,
+          "note": null
+        },
+        {
+          "name": "onIntent",
+          "takes": "a handler",
+          "required": false,
+          "note": "The pointer rests on the group, or the keyboard reaches it: read its rows now."
+        },
+        {
+          "name": "loading",
+          "takes": "true/false",
+          "required": false,
+          "note": "Its rows are being read: a skeleton in their place."
+        },
+        {
+          "name": "storageKey",
+          "takes": "text",
+          "required": false,
+          "note": "Remember it open or closed in this browser, under this key."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": false,
+          "note": "The rows: `NavItem`s."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "frame-navtree--docs",
+      "storyId": "frame-navtree--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "normalizeHref",
       "repo": "estiva-ui",
@@ -4979,8 +5096,8 @@
       "app": null,
       "looks": [
         "transition-transform duration-150 text-text-secondary rotate-90",
-        "rounded-md transition-colors text-text-secondary hover:text-text-primary",
-        "rounded-md transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
+        "rounded-lg transition-colors text-text-secondary hover:text-text-primary",
+        "rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
         "-mr-1 opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100",
         "opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100"
       ]
@@ -6472,6 +6589,32 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "UnreadDot",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/UnreadDot.tsx",
+      "purpose": "The accent dot that says \"something new here\": a 6px disc centred in a 24px slot, so it sits exactly where a control would and the row does not shift when one replaces the other.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-unreaddot--docs",
+      "storyId": "primitives-unreaddot--default",
+      "docPage": "src/UnreadDot.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "UrgentPersonMention",
       "repo": "estiva-ui",

package/src/NavItem.mdx

@@ -41,6 +41,13 @@ count — a muted mono number whose tooltip says what it counts.
 
 <Canvas of={NavItemStories.WithHintLongLabel} />
 
+- Something new on the row is `unread`: its words and icon brighten, the
+  label is set in medium, and the **UnreadDot** sits at the right.
+  `urgent` with it draws the warning badge in the dot's place. Say "unread"
+  in the row's own accessible name too: a dot reads as nothing.
+
+<Canvas of={NavItemStories.Unread} />
+
 ## When not
 
 - An icon rail's tile → **RailItem**.
@@ -73,9 +80,14 @@ import { NavItem } from '@estiva-app/ui'
   `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.
+- The ⋮ lands on what is at the right: the count, or the dot. With nothing
+  there it keeps no room at rest, so the label has the row's whole width,
+  and takes its 24px slot only while it shows.
+- `active` is `bg-nav-active`, the current row in a sidebar, which each theme
+  sets for itself.
 
 - A row is 32px tall, 8px in on each side, 8px between the icon and the label,
-  the label 14px regular, 6px corners.
+  the label 14px regular (medium when unread), 8px corners as a **MenuItem**'s.
 
 ## What it owns
 
@@ -89,6 +101,7 @@ It does these by itself. Write none of them around it.
 | 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 |  |
+| Draws the dot or the badge for `unread` and `urgent`, and brightens the row | an **UnreadDot** placed by hand, a weight or colour passed in |  |
 
 ## Keys
 

package/src/NavItem.stories.tsx

@@ -94,3 +94,18 @@ export const WithRowsUnderClosed: Story = {
     </NavItem>
   ),
 }
+
+/** Something new: the words brighten, the label is medium, and the dot sits at the right. */
+export const Unread: Story = {
+  args: { icon: placeholder, unread: true },
+}
+
+/** Urgent and unread: the warning badge in the dot's place. */
+export const UnreadUrgent: Story = {
+  args: { icon: placeholder, unread: true, urgent: true },
+}
+
+/** Unread, with a menu: point at it and the ⋮ lands on the dot. */
+export const UnreadWithMenu: Story = {
+  args: { icon: placeholder, unread: true, menu: MENU },
+}

package/src/NavItem.test.tsx

@@ -80,3 +80,34 @@ describe('NavItem with a hint', () => {
     expect(container.firstElementChild?.tagName).toBe('A')
   })
 })
+
+describe('NavItem unread', () => {
+  it('draws the dot, and sets the label in medium', () => {
+    const { container } = render(<NavItem href="#" label="Item one" unread />)
+    expect(container.querySelector('[data-unread]')).not.toBeNull()
+    expect(screen.getByText('Item one').className).toContain('font-medium')
+  })
+
+  it('urgent draws the badge in the dot’s place', () => {
+    const { container } = render(<NavItem href="#" label="Item one" unread urgent />)
+    expect(container.querySelector('[data-urgent]')).not.toBeNull()
+    expect(container.querySelector('[data-unread]')).toBeNull()
+  })
+
+  it('urgent without unread draws nothing', () => {
+    const { container } = render(<NavItem href="#" label="Item one" urgent />)
+    expect(container.querySelector('[data-urgent], [data-unread]')).toBeNull()
+  })
+
+  it('with a menu, the ⋮ sits in the 24px slot over the dot', () => {
+    render(<NavItem href="#" label="Item one" unread menu={<span>Action</span>} />)
+    const menu = screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')
+    expect(menu?.className).toContain('right-2')
+  })
+
+  it('with a count and a menu, the ⋮ lands on the count', () => {
+    render(<NavItem href="#" label="Item one" count={3} menu={<span>Action</span>} />)
+    const menu = screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')
+    expect(menu?.className).toContain('right-1')
+  })
+})

package/src/NavItem.tsx

@@ -1,10 +1,11 @@
 import { useId, useState, type ComponentPropsWithoutRef, type ReactNode } from 'react'
 import { Collapsible } from '@base-ui/react/collapsible'
-import { IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
+import { IconAlertSquareRounded, IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
 import { cn } from './cn'
 import { COLLAPSIBLE_PANEL_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { Menu } from './Menu'
+import { UnreadDot } from './UnreadDot'
 import { WithTooltip } from './Tooltip'
 
 /**
@@ -34,6 +35,15 @@ import { WithTooltip } from './Tooltip'
  * `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.
+ *
+ * `unread` brightens the row's words and icon, sets the label in medium, and
+ * draws the `UnreadDot` at the right; `urgent` with it draws the warning badge
+ * in the dot's place (Katerina, 2 October: Peek's row, moved in). The ⋮ lands
+ * on whatever is in that place, and with nothing there it takes no room until
+ * the row is pointed at, so a label at rest keeps the row's whole width.
+ *
+ * Active is `bg-nav-active`, the current row in a sidebar, which each theme
+ * sets: the selected tab's neutral fill in most, Signal's blue in Signal.
  */
 export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'children'> {
   label: string
@@ -51,6 +61,10 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
   menuLabel?: string
   /** Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically. */
   hint?: ReactNode
+  /** Something new here: brighter words, the label in medium, and the `UnreadDot` at the right. Say so in the row's own words for assistive tech too. */
+  unread?: boolean
+  /** With `unread`: the warning badge in the dot's place. */
+  urgent?: boolean
   /** 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. */
@@ -71,6 +85,8 @@ export function NavItem({
   menu,
   menuLabel,
   hint,
+  unread = false,
+  urgent = false,
   children,
   defaultOpen = true,
   open: openProp,
@@ -89,6 +105,10 @@ export function NavItem({
   // 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
+  // What sits at the right at rest, after the count: the dot, or the badge.
+  const mark = unread ? (urgent ? <UrgentMark /> : <UnreadDot />) : null
+  // Under the ⋮ while it shows: the count and the mark step aside for it.
+  const stepsAside = 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'
 
   const row = (
     <a
@@ -100,7 +120,7 @@ export function NavItem({
         // shrink-0 family; Katerina, 2026-09-02).
         'flex h-8 min-w-0 shrink-0 items-center gap-2 px-2 text-body-2',
         SIDEBAR_ROW_CLASSES,
-        active ? 'bg-bg-active text-text-primary' : cn(SIDEBAR_ROW_TEXT_CLASSES, 'hover:bg-bg-hover'),
+        active ? 'bg-bg-nav-active text-text-primary' : cn(unread ? 'text-text-primary' : 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. The same
         // for the arrow.
@@ -121,7 +141,7 @@ export function NavItem({
           {icon}
         </span>
       )}
-      <span className="flex-1 truncate">{label}</span>
+      <span className={cn('flex-1 truncate', unread && 'font-medium')}>{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>
@@ -135,17 +155,21 @@ export function NavItem({
           <span
             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-[[data-nav-menu]_[aria-expanded=true]]/nav:opacity-0',
+              // With a menu and no mark after it, the ⋮ takes this place while it shows.
+              !mark && stepsAside,
             )}
           >
             {count}
           </span>
         </WithTooltip>
-      ) : menu != null ? (
-        // No count, but a menu: the count's place is kept free, so a long
-        // label truncates before the ⋮ instead of running under it.
-        <span aria-hidden="true" className="min-w-4 shrink-0" />
+      ) : null}
+      {mark ? (
+        <span className={cn('flex shrink-0', stepsAside)}>{mark}</span>
+      ) : menu != null && !count ? (
+        // Nothing at the right, but a menu: no room is kept at rest, so the
+        // label has the row's whole width; while the ⋮ shows, its 24px slot
+        // is kept, so a long label ends before it instead of running under it.
+        <span aria-hidden="true" className="hidden w-6 shrink-0 group-hover/nav:block group-focus-within/nav:block group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:block" />
       ) : null}
     </a>
   )
@@ -170,9 +194,11 @@ export function NavItem({
         </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">
+        // On a count, `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. On the mark or the empty slot, `right-2`: the button
+        // sits in the 24px slot itself.
+        <div data-nav-menu className={cn('absolute inset-y-0 flex items-center', count && !mark ? 'right-1' : 'right-2', 'opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100')}>
           <Menu
             align="right"
             trigger={
@@ -204,3 +230,14 @@ export function NavItem({
     </Collapsible.Root>
   )
 }
+
+/** Urgent and unread: a 12px warning mark on its tint, in the dot's 24px slot. */
+function UrgentMark() {
+  return (
+    <div className="flex h-6 w-6 shrink-0 items-center justify-center" data-urgent>
+      <div className="flex items-center rounded-full bg-warning-muted p-0.5 signal:shadow-glow-warning">
+        <IconAlertSquareRounded size={12} stroke={2.5} className="text-warning-default" />
+      </div>
+    </div>
+  )
+}

package/src/NavTree.mdx

@@ -27,6 +27,30 @@ rows to any depth.
 
 <Canvas of={NavTreeStories.Loading} />
 
+- `titleActions` sit beside the label, always shown ("New"); a group's
+  `actions` beside its title on hover ("Open"), its `trailing` always (an
+  **UnreadDot**). A row's `unread` and `urgent` are **NavItem**'s.
+
+<Canvas of={NavTreeStories.WithActionsAndUnread} />
+
+- Rows can be read as they open. A group's `nodes={null}` is a skeleton in
+  its rows' place, and its `message` a line in their place ("Nothing in this
+  yet."). A row with `hasChildren` and no `children` has its arrow, a
+  skeleton under it once open, and `onOpenChange` says when to read them;
+  `childrenMessage` is the line under it. `onIntent` on a group says the
+  pointer rests on it or the keyboard reached it: read it then, so opening
+  it draws rows.
+
+<Canvas of={NavTreeStories.ReadAsItOpens} />
+
+- An app whose groups and rows each read their own data draws the groups
+  itself: leave out `groups` and pass **NavTreeSection**s as children, each
+  with **NavItem** rows. A `NavTreeSection` is one group exactly as `groups`
+  draws it — the heading, the light indent, `message`, `loading`, `trailing`,
+  `actions`, `onIntent`.
+
+<Canvas of={NavTreeStories.AppDrawnGroups} />
+
 ## When not
 
 - A flat list of places → **NavItem** rows in the **Sidebar**.
@@ -68,6 +92,7 @@ It does these by itself. Write none of them around it.
 | 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 |  |
+| Says when the pointer rests on a group, 150ms, and not while it sweeps past | a timer on pointer enter and leave |  |
 
 ## Keys
 

package/src/NavTree.stories.tsx

@@ -1,9 +1,11 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconSquareRounded } from '@tabler/icons-react'
 import { useState } from 'react'
+import { IconArrowUpRight, IconPlus } from '@tabler/icons-react'
 import { Chip } from './Chip'
+import { UnreadDot } from './UnreadDot'
 import { NavItem } from './NavItem'
-import { NavTree, type NavTreeGroup } from './NavTree'
+import { NavTree, NavTreeSection, type NavTreeGroup } from './NavTree'
 import { Sidebar } from './Sidebar'
 
 const placeholder = <IconSquareRounded size={16} stroke={1.5} />
@@ -82,3 +84,57 @@ 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' } }
+
+/** Actions beside the label and on each group, a group's dot, and unread rows — one urgent. */
+export const WithActionsAndUnread: Story = {
+  args: {
+    titleActions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'New', onClick: () => {} }],
+    groups: [
+      { id: 'u1', title: 'Group one', trailing: <UnreadDot />, actions: [{ icon: <IconArrowUpRight size={16} stroke={1.5} />, tooltip: 'Open', onClick: () => {} }], defaultOpen: true, nodes: [
+        { id: 'u1a', label: 'Item two', href: '#', icon: placeholder, unread: true },
+        { id: 'u1b', label: 'Item three', href: '#', icon: placeholder, unread: true, urgent: true },
+        { id: 'u1c', label: 'Item four', href: '#', icon: placeholder },
+      ] },
+      { id: 'u2', title: 'Group two', actions: [{ icon: <IconArrowUpRight size={16} stroke={1.5} />, tooltip: 'Open', onClick: () => {} }], nodes: [{ id: 'u2a', label: 'Item five', href: '#', icon: placeholder }] },
+    ],
+    selected: 'u1c',
+  },
+}
+
+/** Read as it opens: a group still being read, a group with nothing in it, a row whose rows are read when it opens, and one that could not be read. */
+export const ReadAsItOpens: Story = {
+  args: {
+    groups: [
+      { id: 'l1', title: 'Being read', defaultOpen: true, nodes: null },
+      { id: 'l2', title: 'Empty', defaultOpen: true, nodes: [], message: 'Nothing in this yet.' },
+      { id: 'l3', title: 'Rows read on open', defaultOpen: true, nodes: [
+        { id: 'l3a', label: 'Item with rows not read yet', href: '#', icon: placeholder, hasChildren: true, defaultOpen: false },
+        { id: 'l3b', label: 'Item whose rows failed', href: '#', icon: placeholder, hasChildren: true, childrenMessage: 'This could not be read.' },
+      ] },
+    ],
+    selected: undefined,
+  },
+}
+
+/** Groups the app draws itself, as `NavTree`'s children: each a `NavTreeSection` with `NavItem` rows — for groups and rows that each read their own data. */
+export const AppDrawnGroups: Story = {
+  args: { groups: undefined },
+  render: function Render(args) {
+    return (
+      <div className="flex h-screen bg-bg-base">
+        <Sidebar>
+          <NavTree title={args.title}>
+            <NavTreeSection title="Group one" trailing={<UnreadDot />}>
+              <NavItem href="#" label="Item one" icon={placeholder} unread />
+              <NavItem href="#" label="Item two" icon={placeholder} active>
+                <NavItem href="#" label="Item three" icon={placeholder} />
+              </NavItem>
+            </NavTreeSection>
+            <NavTreeSection title="Group two" loading />
+            <NavTreeSection title="Group three" message="Nothing in this yet." />
+          </NavTree>
+        </Sidebar>
+      </div>
+    )
+  },
+}