@estiva-app/ui 0.59.0 → 0.60.0

package/src/AppProvider.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+/**
+ * What AppProvider promises, pinned: a face handed no picture asks the app for
+ * one, and a picture handed in still wins; a plain click on a link to the
+ * app's own address changes page through the app instead of loading it, and
+ * every other click is left to the browser; without a provider, nothing changes.
+ */
+import { type ReactNode } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { AppProvider } from './AppProvider'
+import { Avatar } from './Avatar'
+import { Chip } from './Chip'
+import { IconButton } from './IconButton'
+import { InlineChip } from './InlineChip'
+import { Link } from './Link'
+import { NavItem } from './NavItem'
+import { Person } from './Person'
+import { RailItem } from './RailItem'
+
+afterEach(cleanup)
+
+const imgOf = (container: HTMLElement) => container.querySelector('img')
+
+describe('pictures', () => {
+  const pictureFor = (name: string) => (name === 'Ana Duarte' ? 'https://pictures.test/ana.png' : null)
+
+  it("asks the app for a face's picture when none is handed in", () => {
+    const { container } = render(
+      <AppProvider pictureFor={pictureFor}>
+        <Avatar name="Ana Duarte" />
+      </AppProvider>,
+    )
+    expect(imgOf(container)?.getAttribute('src')).toBe('https://pictures.test/ana.png')
+  })
+
+  it('keeps a picture that is handed in', () => {
+    const { container } = render(
+      <AppProvider pictureFor={pictureFor}>
+        <Avatar name="Ana Duarte" src="https://pictures.test/own.png" />
+      </AppProvider>,
+    )
+    expect(imgOf(container)?.getAttribute('src')).toBe('https://pictures.test/own.png')
+  })
+
+  it('draws the initials when the app has no picture either', () => {
+    const { container } = render(
+      <AppProvider pictureFor={pictureFor}>
+        <Avatar name="Ravi Mehta" />
+      </AppProvider>,
+    )
+    expect(imgOf(container)).toBeNull()
+    expect(container.textContent).toBe('RM')
+  })
+
+  it('reaches a face drawn through another part', () => {
+    const { container } = render(
+      <AppProvider pictureFor={pictureFor}>
+        <Person name="Ana Duarte" />
+      </AppProvider>,
+    )
+    expect(imgOf(container)?.getAttribute('src')).toBe('https://pictures.test/ana.png')
+  })
+
+  it('asks nothing without a provider', () => {
+    const { container } = render(<Avatar name="Ana Duarte" />)
+    expect(imgOf(container)).toBeNull()
+  })
+})
+
+describe('changing page', () => {
+  const inApp = (navigate: (href: string) => void, children: ReactNode) => render(<AppProvider navigate={navigate}>{children}</AppProvider>)
+
+  it.each([
+    ['Link', <Link href="/topics">Topics</Link>],
+    ['NavItem', <NavItem href="/topics" label="Topics" />],
+    ['RailItem', <RailItem href="/topics" icon={<i />} label="Topics" />],
+    ['Chip', <Chip href="/topics" label="Topics" />],
+    ['InlineChip', <InlineChip href="/topics">Topics</InlineChip>],
+    ['IconButton', <IconButton href="/topics" aria-label="Topics" tooltip="Topics"><i /></IconButton>],
+  ])('%s: a plain click goes through the app', async (_name, part) => {
+    const navigate = vi.fn()
+    inApp(navigate, part)
+    await userEvent.click(screen.getByRole('link'))
+    expect(navigate).toHaveBeenCalledWith('/topics')
+  })
+
+  it("runs the caller's own onClick first", async () => {
+    const order: string[] = []
+    inApp(() => order.push('navigate'), <Link href="/topics" onClick={() => order.push('caller')}>Topics</Link>)
+    await userEvent.click(screen.getByRole('link'))
+    expect(order).toEqual(['caller', 'navigate'])
+  })
+
+  it('leaves a click the caller already handled', async () => {
+    const navigate = vi.fn()
+    inApp(navigate, <Link href="/topics" onClick={(event) => event.preventDefault()}>Topics</Link>)
+    await userEvent.click(screen.getByRole('link'))
+    expect(navigate).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    ['Ctrl', { ctrlKey: true }],
+    ['Cmd', { metaKey: true }],
+    ['Shift', { shiftKey: true }],
+    ['Alt', { altKey: true }],
+    ['the middle button', { button: 1 }],
+  ])('leaves a click with %s to the browser', (_name, init) => {
+    const navigate = vi.fn()
+    inApp(navigate, <Link href="/topics">Topics</Link>)
+    const link = screen.getByRole('link')
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true, ...init })
+    link.dispatchEvent(event)
+    expect(navigate).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it.each([
+    ['another site', <Link href="https://elsewhere.test/topics">Topics</Link>],
+    ['another scheme', <Link href="folder:1234">Topics</Link>],
+    ['a new tab', <Link href="/topics" external>Topics</Link>],
+    ['a download', <Link href="/file.pdf" download>File</Link>],
+  ])('leaves a link to %s to the browser', (_name, part) => {
+    const navigate = vi.fn()
+    inApp(navigate, part)
+    const link = screen.getByRole('link')
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true })
+    link.dispatchEvent(event)
+    expect(navigate).not.toHaveBeenCalled()
+  })
+
+  it('stops the page load it replaces', () => {
+    inApp(() => {}, <Link href="/topics">Topics</Link>)
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true })
+    screen.getByRole('link').dispatchEvent(event)
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('changes nothing without a provider', () => {
+    render(<Link href="/topics">Topics</Link>)
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true })
+    screen.getByRole('link').dispatchEvent(event)
+    expect(event.defaultPrevented).toBe(false)
+  })
+
+  it('keeps the address on the link, for a new tab', () => {
+    inApp(() => {}, <NavItem href="/topics" label="Topics" />)
+    expect(screen.getByRole('link').getAttribute('href')).toBe('/topics')
+  })
+
+})

package/src/AppProvider.tsx

@@ -0,0 +1,76 @@
+import { createContext, useContext, useMemo, type MouseEvent, type MouseEventHandler, type ReactNode } from 'react'
+
+export interface AppProviderProps {
+  /**
+   * Where this app keeps a person's picture. `Avatar` asks it, with the
+   * person's name, whenever it is handed no picture — and so does every part
+   * that draws a face through it: `Person`, `AvatarGroup`, `MembersPill`,
+   * `MembersDialog`, `PersonTrigger`, `IdentityMenu`.
+   */
+  pictureFor?: (name: string) => string | null | undefined
+  /**
+   * How this app changes page without reloading. A plain click on a link to
+   * this app's own address calls it with the link's `href` instead of loading
+   * the page again: `Link` (and so `Card` and `Breadcrumb`'s crumbs),
+   * `NavItem` (and so `NavTree`'s rows), `RailItem`, `Chip`, `InlineChip`, and
+   * `IconButton` (and so `ToolbarLink`).
+   */
+  navigate?: (href: string) => void
+  children: ReactNode
+}
+
+type AppSetup = Omit<AppProviderProps, 'children'>
+
+const Setup = createContext<AppSetup>({})
+
+/**
+ * What every part needs to know about the app it is in, said once at the top:
+ * where a person's picture comes from, and how to change page.
+ *
+ * Without it each app wrapped the parts that needed either: Peek's own
+ * `Avatar` and `Person` only looked a picture up, and Peek's and Ship's own
+ * `NavItem` only stopped a reload (Katerina, 8 October: "we would handle these
+ * in estiva-ui so we don't keep copies"). Both are optional, and a part
+ * without a provider above it draws exactly as it did.
+ */
+export function AppProvider({ pictureFor, navigate, children }: AppProviderProps) {
+  const value = useMemo(() => ({ pictureFor, navigate }), [pictureFor, navigate])
+  return <Setup.Provider value={value}>{children}</Setup.Provider>
+}
+
+/** The app's picture lookup, or nothing outside an `AppProvider`. */
+export function usePictureFor(): AppSetup['pictureFor'] {
+  return useContext(Setup).pictureFor
+}
+
+/**
+ * A link's click, kept inside the app: the caller's own `onClick` first, then,
+ * on a plain left click to this app's own address, the app's `navigate` in
+ * place of a page load.
+ *
+ * Left to the browser, as an `<a>` always is: a click the caller already
+ * handled (`preventDefault`), a click with a modifier or another button (a new
+ * tab), a link that opens elsewhere (`target`) or downloads, and an address on
+ * another site or in another scheme (`folder:`, `mailto:`). So an app that
+ * still passes its own router `onClick`, as Ship's `linkTo` does, is unchanged.
+ */
+export function useInAppClick<E extends HTMLElement>(href: string | undefined, onClick?: MouseEventHandler<E>): MouseEventHandler<E> | undefined {
+  const navigate = useContext(Setup).navigate
+  if (!navigate || href === undefined) return onClick
+  return (event: MouseEvent<E>) => {
+    onClick?.(event)
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+    const link = event.currentTarget
+    const target = link.getAttribute('target')
+    if ((target && target !== '_self') || link.hasAttribute('download')) return
+    let url: URL
+    try {
+      url = new URL(href, window.location.href)
+    } catch {
+      return
+    }
+    if (url.origin !== window.location.origin) return
+    event.preventDefault()
+    navigate(href)
+  }
+}

package/src/AppShell.mdx

@@ -69,6 +69,7 @@ import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
   variant="floating"
   menu={menuButton}
   logo="Estiva"
+  onSearch={openLauncher}
   identity={<IdentityMenu me={me} signedIn={signedIn} />}
   banner={notice && <Banner tone={notice.tone}>{notice.text}</Banner>}
   nav={<Rail>…</Rail>}
@@ -79,7 +80,9 @@ import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
 
 - Give it a height: it fills `h-full` and manages `min-h-0` internally so
   navigation and content scroll apart.
-- `menu`, `logo` and `search` pass through to the TopBar's slots.
+- `menu`, `logo`, `search`, `onSearch` and `searchPlaceholder` pass through to
+  the **TopBar**: with `onSearch` the bar draws the search field and answers
+  Ctrl+K.
 - In the floating manner the card owns `overflow-hidden` — your content
   manages its own scrolling inside it.
 - Desktop only for now — no narrow-screen behaviour is provided.

package/src/AppShell.stories.tsx

@@ -8,7 +8,6 @@ import { NavItem } from './NavItem'
 import { PersonTrigger } from './PersonTrigger'
 import { Rail } from './Rail'
 import { RailItem } from './RailItem'
-import { SearchInput } from './SearchInput'
 import { Sidebar } from './Sidebar'
 
 const meta = {
@@ -27,6 +26,7 @@ const meta = {
     menu: { control: false },
     logo: { control: false },
     search: { control: false },
+    onSearch: { control: false },
     identity: { control: false },
     banner: { control: false },
     nav: { control: false },
@@ -65,7 +65,7 @@ const rail = (
 /** The structured frame: solid bar, sidebar, content beside it. */
 export const Solid: Story = {
   render: (args) => (
-    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+    <AppShell {...args} logo="Estiva" onSearch={() => {}} identity={identity} nav={sidebar}>
       <EmptyState message="Nothing here yet." />
     </AppShell>
   ),
@@ -75,7 +75,7 @@ export const Solid: Story = {
 /** A page taller than the frame: it scrolls in the frame's own bar — the region every page passes through — never a native one. */
 export const SolidScrolls: Story = {
   render: (args) => (
-    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+    <AppShell {...args} logo="Estiva" onSearch={() => {}} identity={identity} nav={sidebar}>
       <div className="flex flex-col gap-px px-6 py-5">
         {Array.from({ length: 60 }, (_, i) => (
           <p key={i} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
@@ -99,7 +99,7 @@ export const SolidWithBanner: Story = {
 export const Inset: Story = {
   args: { variant: 'inset' },
   render: (args) => (
-    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+    <AppShell {...args} logo="Estiva" onSearch={() => {}} identity={identity} nav={sidebar}>
       <EmptyState message="Nothing here yet." />
     </AppShell>
   ),
@@ -122,7 +122,7 @@ export const Floating: Story = {
       variant="floating"
       menu={menuButton}
       logo="Estiva"
-      search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />}
+      onSearch={() => {}}
       identity={identity}
       nav={rail}
     >

package/src/AppShell.tsx

@@ -34,8 +34,12 @@ export interface AppShellProps {
   menu?: ReactNode
   /** The top bar's left: the app's logo mark, or its name as text. */
   logo?: ReactNode
-  /** The top bar's centre — a search field, when there is one. */
+  /** The top bar's centre: something of the caller's own. */
   search?: ReactNode
+  /** What searching opens: the top bar then draws its search field and answers Ctrl+K (`TopBar`'s `onSearch`). */
+  onSearch?: () => void
+  /** The words in the top bar's search field. */
+  searchPlaceholder?: string
   /** The top bar's right cluster — an `IdentityMenu`. */
   identity?: ReactNode
   /** A `Banner`, or nothing — drawn at the top of the content area. */
@@ -45,8 +49,8 @@ export interface AppShellProps {
   children: ReactNode
 }
 
-export function AppShell({ variant = 'solid', menu, logo, search, identity, banner, nav, children }: AppShellProps) {
-  const bar = <TopBar variant={variant} menu={menu} logo={logo} search={search} right={identity} />
+export function AppShell({ variant = 'solid', menu, logo, search, onSearch, searchPlaceholder, identity, banner, nav, children }: AppShellProps) {
+  const bar = <TopBar variant={variant} menu={menu} logo={logo} search={search} onSearch={onSearch} searchPlaceholder={searchPlaceholder} right={identity} />
   const inset = variant === 'inset'
 
   if (variant === 'floating') {

package/src/Avatar.tsx

@@ -1,5 +1,6 @@
 import { Avatar as BaseAvatar } from '@base-ui/react/avatar'
 import { IconUserFilled } from '@tabler/icons-react'
+import { usePictureFor } from './AppProvider'
 import { cn } from './cn'
 
 /**
@@ -51,7 +52,7 @@ export const initialsFor = (name: string) => {
 }
 
 export interface AvatarProps {
-  /** The picture URL, resolved by the caller. Until it arrives, and if it fails, the initials show. */
+  /** The picture URL, resolved by the caller — or, when none is given, by the app's `AppProvider`. Until it arrives, and if it fails, the initials show. */
   src?: string
   /** The person's name — where the initials and the colour come from. */
   name?: string
@@ -76,6 +77,9 @@ export interface AvatarProps {
 
 export function Avatar({ src, name, alt = '', size = 36, label: spoken, className }: AvatarProps) {
   const label = name || alt
+  // No picture handed in: the app's own, when it has said where pictures live (`AppProvider`).
+  const pictureFor = usePictureFor()
+  const picture = src ?? (label && pictureFor ? (pictureFor(label) ?? undefined) : undefined)
   return (
     <BaseAvatar.Root
       // A div, as it was drawn: Base UI's default is a span.
@@ -87,9 +91,9 @@ export function Avatar({ src, name, alt = '', size = 36, label: spoken, classNam
       className={cn('rounded-sm overflow-hidden shrink-0 bg-bg-inset', className)}
       style={{ width: size, height: size }}
     >
-      {src && (
+      {picture && (
         <BaseAvatar.Image
-          src={src}
+          src={picture}
           alt=""
           /*
             `keepMounted`: the <img> is in the tile from the first render, as it

package/src/Breadcrumb.mdx

@@ -48,8 +48,8 @@ import { Breadcrumb } from '@estiva-app/ui'
 />
 ```
 
-- A crumb is a plain anchor. In a router app pass `onClick` per crumb and
-  navigate in place there — NavItem's rule — and keep the `href` a real
+- A crumb is a **Link**, so it changes page as Link does: through
+  **AppProvider**'s `navigate`, or an `onClick` per crumb. The `href` stays a real
   address, so the link can still be copied or opened in a new tab.
 - Truncation is re-measured as the trail resizes; the tooltip appears and
   disappears with the room the trail actually has. Give the trail a

package/src/Card.mdx

@@ -62,7 +62,7 @@ import { Card } from '@estiva-app/ui'
 - It draws no padding and no layout of its own: put them in `className`, or let
   the content pad itself.
 - With `href` it renders `Link`'s anchor, with every anchor prop passed through,
-  so a router app takes the click and the address stays real.
+  so it changes page as **Link** does and the address stays real.
 - Without `href`, a card that responds to a click gets `cursor-pointer` from its
   `hover` and your `onClick` — the selected one too, since it can open again;
   the one being changed does not. Controls inside it should stop their own

package/src/Chip.mdx

@@ -38,8 +38,8 @@ import { Chip } from '@estiva-app/ui'
   it never rides the text baseline.
 - A count alone works too — `label="3"`, no icon.
 - `href` makes the chip a link to the thing it names: a real anchor with the
-  chip's round shape, so the keyboard ring is round too. A router app passes
-  `onClick`, as with **Link**. Inside a row whose **Link** has `cover`, it
+  chip's round shape, so the keyboard ring is round too. It changes page as
+  **Link** does. Inside a row whose **Link** has `cover`, it
   stays clickable on its own: the row opens one thing, the chip another.
 
 ```tsx

package/src/Chip.tsx

@@ -1,4 +1,5 @@
 import type { MouseEventHandler, ReactNode } from 'react'
+import { useInAppClick } from './AppProvider'
 import { cn } from './cn'
 import { CHIP_TEXT_CLASSES } from './looks'
 
@@ -41,6 +42,7 @@ const typeStyles: Record<ChipType, string> = {
 }
 
 export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, href, onClick, className }: ChipProps) {
+  const inApp = useInAppClick(href, onClick)
   const classes = cn('inline-flex min-w-0 items-center justify-center gap-1.5 rounded-full max-h-[20px] px-2 py-1', typeStyles[type], className)
   const inside = (
     <>
@@ -60,6 +62,6 @@ export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, href,
     </>
   )
   // `relative` lifts a linked chip above a covering link that comes before it.
-  if (href) return <a href={href} onClick={onClick} className={cn('relative', classes)}>{inside}</a>
+  if (href) return <a href={href} onClick={inApp} className={cn('relative', classes)}>{inside}</a>
   return <div className={classes}>{inside}</div>
 }

package/src/IconButton.mdx

@@ -55,8 +55,8 @@ import { IconPencil } from '@tabler/icons-react'
   and shows the reason in place of the tooltip — **on keyboard focus as
   well as on hover**.
 - **`href`** makes it a link that looks like the button: an anchor, so the
-  address stays real for a modified click or a new tab. A router app passes
-  `onClick`, prevents the default and navigates. While it cannot be used it
+  address stays real for a modified click or a new tab. It changes page as
+  **Link** does. While it cannot be used it
   is the button — a link cannot be disabled.
 - `tooltip` costs no wrapper: the button is the tooltip's trigger, so
   this component's root is the `<button>` whether it carries one or not,

package/src/IconButton.tsx

@@ -1,5 +1,6 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react'
 import { Button as BaseButton } from '@base-ui/react/button'
+import { useInAppClick } from './AppProvider'
 import { cn } from './cn'
 import { MUTED_CONTROL_CLASSES } from './looks'
 import { useFormBusy } from './formBusy'
@@ -67,6 +68,8 @@ export function IconButton({
 }: IconButtonProps) {
   // Inside a busy Form: switched off, and looking it (formBusy.ts).
   const formBusy = useFormBusy()
+  const anchor = props as unknown as ComponentPropsWithRef<'a'>
+  const inApp = useInAppClick(href, anchor.onClick)
   const unusable = disabled || !!disabledReason || formBusy
   const look = (off: boolean) =>
     cn(
@@ -104,7 +107,7 @@ export function IconButton({
     )
   const button =
     href && !unusable ? (
-      <a href={href} className={look(false)} {...(props as unknown as ComponentPropsWithRef<'a'>)}>
+      <a href={href} className={look(false)} {...anchor} onClick={inApp}>
         {children}
       </a>
     ) : (

package/src/InlineChip.mdx

@@ -42,9 +42,9 @@ import { InlineChip } from '@estiva-app/ui'
 - It belongs inside running text at the body size. `h-[1.4em]` is one line of
   that text, and `align-top` pins the chip to the line, so a line with a chip
   is the same height as a line without one.
-- It renders a plain anchor when it has an `href`. A router app passes
-  `onClick`, prevents the default and navigates; the `href` stays a real
-  address for a modified click or a new tab. Inside something that opens on
+- It renders a plain anchor when it has an `href`, and changes page as
+  **Link** does: through **AppProvider**'s `navigate`, or a router app's `onClick`.
+  The `href` stays a real address for a modified click or a new tab. Inside something that opens on
   click, stop the event there so the chip's click is not also the container's.
 - A long label: pass `className="max-w-[24ch]"` and wrap the text in
   `<span className="truncate">`.

package/src/InlineChip.tsx

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { useInAppClick } from './AppProvider'
 import { cn } from './cn'
 
 /**
@@ -67,6 +68,7 @@ export interface InlineChipProps extends Omit<ComponentPropsWithRef<'a'>, 'child
 }
 
 export function InlineChip({ tone = 'neutral', icon, href, className, children, ...props }: InlineChipProps) {
+  const inApp = useInAppClick(href, props.onClick)
   const body = (
     <>
       {icon && <span className="flex size-4 shrink-0 items-center justify-center text-text-secondary">{icon}</span>}
@@ -83,7 +85,7 @@ export function InlineChip({ tone = 'neutral', icon, href, className, children,
     )
   }
   return (
-    <a href={href} className={classes} {...props}>
+    <a href={href} className={classes} {...props} onClick={inApp}>
       {body}
     </a>
   )

package/src/Link.mdx

@@ -60,9 +60,11 @@ import { Link } from '@estiva-app/ui'
 </h3>
 ```
 
-- It renders a plain anchor and passes every anchor prop through. A router app
-  passes `onClick`, prevents the default and navigates; the `href` stays a real
-  address, so a modified click or a new tab still works.
+- It renders a plain anchor and passes every anchor prop through. Under
+  **AppProvider**'s `navigate`, a plain click on an address in the app changes page
+  without a reload; without it, a router app passes `onClick`, prevents the
+  default and navigates. The `href` stays a real address, so a modified click
+  or a new tab still works.
 - `quiet` and `underlined` set no size and no colour at rest: put them inside
   the text whose look they should take.
 - `plain` wraps a block: give the Link `className="block"` and let the child

package/src/Link.tsx

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { useInAppClick } from './AppProvider'
 import { cn } from './cn'
 
 /**
@@ -70,13 +71,15 @@ export interface LinkProps extends ComponentPropsWithRef<'a'> {
   children: ReactNode
 }
 
-export function Link({ href, variant = 'text', external = false, truncate = false, cover = false, className, children, ...props }: LinkProps) {
+export function Link({ href, variant = 'text', external = false, truncate = false, cover = false, className, children, onClick, ...props }: LinkProps) {
+  const inApp = useInAppClick(href, onClick)
   return (
     <a
       href={href}
       {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
       className={cn(VARIANT_CLASSES[variant], truncate && 'truncate', cover && COVER_CLASSES, className)}
       {...props}
+      onClick={inApp}
     >
       {children}
     </a>

package/src/NavItem.mdx

@@ -71,9 +71,9 @@ import { NavItem } from '@estiva-app/ui'
 />
 ```
 
-- 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.
+- It renders a plain anchor, and every anchor prop passes through. Under
+  **AppProvider**'s `navigate` a click changes page without a reload, so no
+  wrapper is needed: compute `active` from the location where you place it.
 - 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.

package/src/NavItem.tsx

@@ -1,6 +1,7 @@
 import { useId, useState, type ComponentPropsWithoutRef, type ReactNode } from 'react'
 import { Collapsible } from '@base-ui/react/collapsible'
 import { IconAlertSquareRounded, IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
+import { useInAppClick } from './AppProvider'
 import { cn } from './cn'
 import { COLLAPSIBLE_PANEL_CLASSES, COUNT_TEXT_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
@@ -92,8 +93,10 @@ export function NavItem({
   open: openProp,
   onOpenChange,
   className,
+  onClick,
   ...props
 }: NavItemProps) {
+  const inApp = useInAppClick(href, onClick)
   const [openState, setOpenState] = useState(defaultOpen)
   const panelId = useId()
   const hasRows = children != null && children !== false
@@ -135,6 +138,7 @@ export function NavItem({
         className,
       )}
       {...props}
+      onClick={inApp}
     >
       {(icon || hasRows) && (
         <span

package/src/NavTree.mdx

@@ -92,8 +92,9 @@ import { NavTree, Sidebar } from '@estiva-app/ui'
 </Sidebar>
 ```
 
-- Each row is a **NavItem**, so a row is a link: a router app prevents the
-  default in `onSelect` and navigates.
+- Each row is a **NavItem**, so a row is a link, and changes page as one
+  does: through **AppProvider**'s `navigate`, or `onSelect` preventing the
+  default and navigating.
 - `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.

package/src/RailItem.mdx

@@ -40,9 +40,9 @@ import { Rail, RailItem } from '@estiva-app/ui'
 </Rail>
 ```
 
-- Both render plain anchors and a `nav` region. A router app keeps a thin
-  wrapper per item: compute `active` from the location, intercept the
-  click, navigate.
+- Both render plain anchors and a `nav` region. Under **AppProvider**'s `navigate`
+  a click changes page without a reload; compute `active` from the location
+  where you place each item.
 - Icons are 16px at stroke 1.5.
 
 - A tile is 64px wide and 48px tall: the 16px icon in its 32px square, over its

package/src/RailItem.tsx

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react'
+import { useInAppClick } from './AppProvider'
 import { cn } from './cn'
 
 /**
@@ -22,13 +23,15 @@ export interface RailItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href
   className?: string
 }
 
-export function RailItem({ href, icon, label, active = false, className, ...props }: RailItemProps) {
+export function RailItem({ href, icon, label, active = false, className, onClick, ...props }: RailItemProps) {
+  const inApp = useInAppClick(href, onClick)
   return (
     <a
       href={href}
       aria-current={active ? 'page' : undefined}
       className={cn('group flex h-12 w-full shrink-0 flex-col items-center gap-0.5 px-2 py-0.5', className)}
       {...props}
+      onClick={inApp}
     >
       <div
         className={cn(

package/src/SearchInput.mdx

@@ -13,12 +13,11 @@ focus, and an optional keyboard hint at the right edge.
 ## When
 
 - Filtering a list, live, above the list it filters.
-- As a **launcher affordance**: keep the input `pointer-events-none` and
-  open your command surface from a click on the surround — the component
-  is the same either way, and `shortcut` shows the way in ("Ctrl+K").
 
 ## When not
 
+- The way into a launcher from the top bar → **TopBar**'s `onSearch`. The
+  bar draws this look as a button, 290px, and answers Ctrl+K itself.
 - General text entry → **TextInput**.
 - Picking entries from a directory → **ChipInput** or **Select**.
 
@@ -35,7 +34,7 @@ import { SearchInput } from '@estiva-app/ui'
   `Input` since stage 3; the border, the focus-within rule and the `Kbd`
   hint are this component's.
 - **Give it an `aria-label` ("Search")** — the placeholder is not a name,
-  and this usually stands alone in a top bar rather than in a `Field`.
+  and this usually stands alone above its list rather than in a `Field`.
   Inside one, the label names it and you add nothing.
 
 ## What it owns