@estiva-app/ui 0.58.0 → 0.60.0

package/src/AppProvider.mdx

@@ -0,0 +1,69 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as AppProviderStories from './AppProvider.stories'
+
+<Meta of={AppProviderStories} />
+
+# AppProvider
+
+What the parts need to know about the app they are in, said once at its root:
+where a person's picture comes from, and how to change page without a reload.
+
+<Canvas of={AppProviderStories.Pictures} />
+
+## When
+
+- Every app, once, around everything it draws — beside `ToastProvider`.
+- `pictureFor`: the app keeps people's pictures somewhere the package cannot
+  know. Every face handed no picture asks it: **Avatar**, and so **Person**,
+  **AvatarGroup**, **MembersPill**, **MembersDialog**, **PersonTrigger** and
+  **IdentityMenu**.
+- `navigate`: the app changes page with a router. A plain click on a link to
+  the app's own address then goes through it: **Link**, **Card** and
+  **Breadcrumb**'s crumbs, **NavItem** and **NavTree**'s rows, **RailItem**,
+  **Chip**, **InlineChip**, **IconButton** and **ToolbarLink**.
+
+<Canvas of={AppProviderStories.ChangingPage} />
+
+## When not
+
+- A wrapper around a part that only looks a picture up, or only stops a
+  reload → this, once. Peek and Ship each kept their own Avatar, Person or
+  NavItem for one of these two jobs (Katerina, 8 October).
+- One face with a picture you already have → pass it to **Avatar**'s `src`
+  or **Person**'s `picture`. A picture handed in always wins.
+- One **Link** that does something other than change page → give it its own
+  `onClick` and `preventDefault()`; the provider leaves it alone.
+
+## How
+
+```tsx
+import { AppProvider } from '@estiva-app/ui'
+
+function Root({ children }) {
+  const pictureFor = usePictureLookup() // the app's own
+  const navigate = useNavigate() // the app's router
+  return (
+    <AppProvider pictureFor={pictureFor} navigate={navigate}>
+      {children}
+    </AppProvider>
+  )
+}
+```
+
+- Both are optional. A part with no provider above it draws as it always
+  did, which is also what a story or a test sees without one.
+- `pictureFor` gets the person's name and returns an address, or nothing for
+  the initials.
+- `navigate` gets the link's `href` exactly as written. The browser keeps
+  every other click: one already handled (`preventDefault`), one with Ctrl,
+  Cmd, Shift or Alt, the middle button, a link that opens a new tab or
+  downloads, and an address on another site or in another scheme
+  (`folder:`, `mailto:`).
+- A link's own `onClick` runs first, so an app that still passes its router
+  click per link keeps working while it moves over.
+- `active` is still the caller's: say which row is the current page where you
+  place it.
+
+## What it owns
+
+Nothing. It draws nothing; it holds two answers for the parts below it.

package/src/AppProvider.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { IconFolder, IconMessage } from '@tabler/icons-react'
+import { AppProvider } from './AppProvider'
+import { Link } from './Link'
+import { MembersPill } from './MembersPill'
+import { NavItem } from './NavItem'
+import { Person } from './Person'
+
+/** One picture the app "knows": Ana's. Inline, so the story needs nothing from anywhere. */
+const ANA = 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><rect width="10" height="10" fill="%2346c08a"/><circle cx="5" cy="4" r="2" fill="%23fff"/></svg>'
+const pictureFor = (name: string) => (name === 'Ana Duarte' ? ANA : undefined)
+
+const meta = {
+  title: 'Frame/AppProvider',
+  component: AppProvider,
+  args: { children: null },
+  argTypes: { children: { control: false }, pictureFor: { control: false }, navigate: { control: false } },
+} satisfies Meta<typeof AppProvider>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * The app knows Ana's picture and nobody else's. No part below is handed a
+ * picture: each face asks the app, and Ravi, whom it does not know, keeps
+ * his initials.
+ */
+export const Pictures: Story = {
+  render: () => (
+    <AppProvider pictureFor={pictureFor}>
+      <div className="flex flex-col items-start gap-3 text-body-2 text-text-primary">
+        <Person name="Ana Duarte" />
+        <Person name="Ravi Mehta" />
+        <MembersPill members={[{ name: 'Ana Duarte' }, { name: 'Ravi Mehta' }]} onClick={() => {}} />
+      </div>
+    </AppProvider>
+  ),
+}
+
+/**
+ * A click on a row or a link goes through the app's `navigate`, and the page
+ * is not loaded again. The line under them says where the last click went.
+ */
+export const ChangingPage: Story = {
+  render: function ChangingPage() {
+    const [at, setAt] = useState('/topics')
+    return (
+      <AppProvider navigate={setAt}>
+        <div className="flex w-60 flex-col gap-px">
+          <NavItem href="/topics" label="Topics" icon={<IconMessage size={16} stroke={1.5} />} active={at === '/topics'} />
+          <NavItem href="/folders" label="Folders" icon={<IconFolder size={16} stroke={1.5} />} active={at === '/folders'} />
+        </div>
+        <p className="mt-3 text-body-2 text-text-secondary">
+          <Link href="/people" variant="underlined">People</Link> · now at <span className="font-mono">{at}</span>
+        </p>
+      </AppProvider>
+    )
+  },
+}

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/CommandPalette.tsx

@@ -15,6 +15,7 @@ import { Autocomplete } from '@base-ui/react/autocomplete'
 import type { BaseUIEvent } from '@base-ui/react/types'
 import { IconLoader2, IconSearch } from '@tabler/icons-react'
 import { cn } from './cn'
+import { MONO_CAPTION_CLASSES } from './looks'
 import { Button } from './Button'
 import { Card } from './Card'
 import { InputChip } from './ChipInput'
@@ -176,7 +177,7 @@ type Key = [key: string, word: string]
 function Footer({ keys }: { keys: Key[] }) {
   const { where } = usePalette('The footer')
   return (
-    <div className="flex h-9 shrink-0 items-center gap-4 border-t border-border-subtle px-5 text-caption text-text-secondary signal:font-mono signal:text-small signal:text-text-muted leaf:font-mono leaf:text-small">
+    <div className={cn('flex h-9 shrink-0 items-center gap-4 border-t border-border-subtle px-5', MONO_CAPTION_CLASSES, 'signal:text-text-muted leaf:font-mono leaf:text-small')}>
       <span className="min-w-0 flex-1 truncate">{where}</span>
       {keys.map(([key, word]) => (
         <span key={key} className="flex shrink-0 items-center gap-1.5">

package/src/ComposerTriggers.mdx

@@ -92,6 +92,13 @@ const urgent = editor ? urgentPubkeys(editor) : undefined
   the same query; nothing waits for it. A row's `description` is its second
   line, which the chip does not wear. A row the person has arrowed to stays
   highlighted when the list is drawn again.
+- **Several kinds of thing in one `[` list:** a row's `icon` is drawn in
+  place of the list's, and the chip's `iconFor(uri)` picks the chip's from
+  what it points at, so the chip wears what its row wore. A row with no `icon`,
+  or a `uri` `iconFor` answers `undefined` for, keeps the one icon.
+
+<Canvas of={ComposerTriggersStories.ReferencesOfSeveralKinds} />
+
 - **An app's own node name:** `CaptionedReference.extend({ name: 'yourName' })`
   and `ReferenceTrigger.configure({ nodeName: 'yourName' })`. The chip's HTML
   attribute follows the name (`data-your-name`).