@estiva-app/ui 0.74.1 → 0.75.0

package/src/LinkChip.mdx

@@ -0,0 +1,51 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkChipStories from './LinkChip.stories'
+
+<Meta of={LinkChipStories} />
+
+# LinkChip
+
+A link in a sentence: its icon, its key, its title cut short, and its status as a shape.
+
+<Canvas of={LinkChipStories.InASentence} />
+
+## When
+
+- **ready** — a link the app has looked up. Hovering it shows its card (**LinkPreview**); a tap or a click opens it.
+- **loading** — still being looked up: the icon, which the address already says, and a bar.
+- **unavailable** — deleted, or not the reader's to see. Both say "Item, not available" in the app's word for it.
+- `preview={false}` — no card on hover, where a card would cover what the reader is choosing from.
+
+<Canvas of={LinkChipStories.EachKind} />
+
+## When not
+
+- A link alone on its line → **LinkRow**.
+- The one card under a piece of text → **CardUnder**.
+- A person, a place or a label with no lookup behind it → **InlineChip**.
+
+## How
+
+```tsx
+import { LinkChip, type LinkState } from '@estiva-app/ui'
+
+// The app looks the link up and hands in where that stands.
+const link: LinkState = found ? { state: 'ready', linked: found } : gone ? { state: 'unavailable', kind: 'issue', noun: 'Item' } : { state: 'loading', kind: 'issue' }
+<LinkChip link={link} />
+```
+
+- **The app looks it up; the chip draws.** `linked` (`Linked`, from `@estiva-app/ui`) carries the words, the `href`, the status and the owner as the app's lookup found them. The chip fetches nothing.
+- `linked.href` opens it. An address in this app goes through `AppProvider`'s `navigate`, so the page does not reload.
+- Words a person wrote (`kind: 'message'` with an `author`) lead with their face and read "Name: words".
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Shows the card on hover, and none on a screen that cannot hover | a hover card of your own, a touch check |
+| Cuts a long title short | a truncation of your own |
+| Says "not available" in words, quieter than a link | a missing-reference chip of your own |
+
+## Props
+
+<Controls of={LinkChipStories.InASentence} />

package/src/LinkChip.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { LinkChip } from './LinkChip'
+import { GROUP, ITEM, LOADING, PAGE, PLACE, ready, SAID, UNAVAILABLE } from './linked.examples'
+
+const meta = {
+  title: 'Components/LinkChip',
+  component: LinkChip,
+  parameters: { layout: 'padded' },
+  args: { link: ready(ITEM) },
+} satisfies Meta<typeof LinkChip>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** In a sentence. Hover it for its card. */
+export const InASentence: Story = {
+  render: (args) => (
+    <p className="max-w-[560px] text-body-2 text-text-primary">
+      A sentence that links <LinkChip {...args} /> in the middle of its words, and goes on after it.
+    </p>
+  ),
+}
+
+/** Every kind, by its icon; words a person wrote lead with their face. */
+export const EachKind: Story = {
+  render: () => (
+    <p className="max-w-[560px] text-body-2 leading-7 text-text-primary">
+      <LinkChip link={ready(ITEM)} /> <LinkChip link={ready(GROUP)} /> <LinkChip link={ready(PLACE)} /> <LinkChip link={ready(PAGE)} /> <LinkChip link={ready(SAID)} />
+    </p>
+  ),
+}
+
+/** Still being looked up: the icon, known from the address, and a bar. */
+export const Loading: Story = { args: { link: LOADING } }
+
+/** Deleted, or not this reader's to see: said in words. */
+export const NotAvailable: Story = { args: { link: UNAVAILABLE } }
+
+/** No card on hover: where a card would cover what the reader is choosing from. */
+export const WithoutPreview: Story = { args: { preview: false } }

package/src/LinkChip.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+/**
+ * What the LinkChip and LinkPreview pages claim, pinned: what each state says,
+ * where the chip leads, and that a screen that cannot hover gets no preview.
+ */
+import { act, cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { LinkChip } from './LinkChip'
+import { ITEM, LOADING, ready, SAID, UNAVAILABLE } from './linked.examples'
+
+/** A screen that can hover, or one that cannot (a phone, a tablet). */
+function screenThatCanHover(canHover: boolean) {
+  vi.stubGlobal('matchMedia', (query: string) => ({
+    matches: query === '(hover: hover)' ? canHover : false,
+    media: query,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  }))
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+/** Rest the pointer on the chip past the preview's delay. */
+async function hoverChip(name: RegExp) {
+  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+  await user.hover(screen.getByRole('link', { name }))
+  await act(async () => {
+    vi.advanceTimersByTime(1000)
+  })
+}
+
+describe('LinkChip', () => {
+  it('leads to what it links, with its key and title', () => {
+    render(<LinkChip link={ready(ITEM)} preview={false} />)
+    const link = screen.getByRole('link', { name: /ABC-2/ })
+    expect(link.getAttribute('href')).toBe('#item')
+    expect(link.textContent).toContain(ITEM.title)
+  })
+
+  it('says a person’s words after their name', () => {
+    render(<LinkChip link={ready(SAID)} preview={false} />)
+    expect(screen.getByRole('link').textContent).toContain(`Person one: ${SAID.body}`)
+  })
+
+  it('while it loads, is busy and leads nowhere yet', () => {
+    const { container } = render(<LinkChip link={LOADING} />)
+    expect(container.querySelector('[aria-busy="true"]')).not.toBeNull()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('says “not available” in words, and leads nowhere', () => {
+    render(<LinkChip link={UNAVAILABLE} />)
+    expect(screen.getByText('Item, not available')).toBeTruthy()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('shows its card, read only, when the pointer rests on it', async () => {
+    screenThatCanHover(true)
+    render(<LinkChip link={ready(ITEM)} />)
+    await hoverChip(/ABC-2/)
+    expect(screen.getByText(ITEM.summary!)).toBeTruthy()
+    // Read only: the values are words, never pickers, though this reader may change them.
+    expect(screen.queryByRole('combobox')).toBeNull()
+    expect(screen.getByText('Person one')).toBeTruthy()
+  })
+
+  it('shows no card on a screen that cannot hover, where a tap opens it', async () => {
+    screenThatCanHover(false)
+    render(<LinkChip link={ready(ITEM)} />)
+    await hoverChip(/ABC-2/)
+    expect(screen.queryByText(ITEM.summary!)).toBeNull()
+    expect(screen.getByRole('link', { name: /ABC-2/ }).getAttribute('href')).toBe('#item')
+  })
+})

package/src/LinkChip.tsx

@@ -0,0 +1,51 @@
+/**
+ * A link in running text: the icon (or the author's face, for words a person
+ * wrote), the key, the title cut short, the status as its shape. Loading
+ * keeps the icon, since the kind is known from the address; not available says
+ * so in words. Hovering it shows its card; a tap opens it.
+ */
+import { Avatar } from './Avatar'
+import { InlineChip } from './InlineChip'
+import type { LinkState } from './linked'
+import { chosenOf } from './linked'
+import { LinkedIcon, LinkKey, StatusMark } from './LinkParts'
+import { LinkPreview } from './LinkPreview'
+import { SkeletonBar } from './Skeleton'
+
+export interface LinkChipProps {
+  link: LinkState
+  /** Hovering shows its card. Off where a card would cover what the reader is choosing from. */
+  preview?: boolean
+}
+
+export function LinkChip({ link, preview = true }: LinkChipProps) {
+  if (link.state === 'loading') {
+    return (
+      <InlineChip icon={<LinkedIcon kind={link.kind} size={14} tone="inherit" />} aria-busy>
+        <SkeletonBar className="h-2.5 w-16" />
+      </InlineChip>
+    )
+  }
+  if (link.state === 'unavailable') {
+    return (
+      <InlineChip tone="muted" icon={<LinkedIcon kind={link.kind} size={14} tone="inherit" />}>
+        {link.noun}, not available
+      </InlineChip>
+    )
+  }
+  const { linked } = link
+  const status = chosenOf(linked.status)
+  const said = linked.kind === 'message' && linked.author
+  const chip = (
+    <InlineChip
+      icon={said ? <Avatar name={said.name} src={said.picture} size={16} /> : <LinkedIcon kind={linked.kind} size={14} tone="inherit" />}
+      href={linked.href}
+      className="max-w-[28ch]"
+    >
+      {linked.key && <LinkKey>{linked.key}</LinkKey>}
+      <span className="truncate">{said ? `${said.name}: ${linked.body ?? linked.title}` : linked.title}</span>
+      {status?.colour && <StatusMark status={{ label: status.label, colour: status.colour }} />}
+    </InlineChip>
+  )
+  return preview ? <LinkPreview linked={linked}>{chip}</LinkPreview> : chip
+}

package/src/LinkParts.mdx

@@ -0,0 +1,49 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkPartsStories from './LinkParts.stories'
+
+<Meta of={LinkPartsStories} />
+
+# LinkParts
+
+The small parts the link widgets are built from: the pickers, the conversation count, a status's shape and a progress ring.
+
+<Canvas of={LinkPartsStories.Pickers} />
+
+## When
+
+- **LinkPickers** — a status and an owner, changed in place. A picker with no `onChange`, or `readOnly`, reads as words in the same place.
+- **CommentCount** — how much was said, as a link to where it is read; brighter, with a dot, when there is something unread for a member.
+- **StatusMark** — a status as its shape, which reads without colour; its words on hover.
+- **ProgressRing** — how far along, as a ring and a count.
+- **LinkedIcon**, **LinkKey** — the icon for what a link stands for, and its key.
+
+<Canvas of={LinkPartsStories.PickersReadOnly} />
+<Canvas of={LinkPartsStories.Conversation} />
+<Canvas of={LinkPartsStories.Marks} />
+
+## When not
+
+- A whole link → **LinkChip**, **LinkRow**, **LinkCard**.
+- A choice in a form → **Select**.
+
+## How
+
+```tsx
+import { LinkPickers, CommentCount } from '@estiva-app/ui'
+
+<LinkPickers status={{ value: statusKey, options: statuses, onChange: setStatus }} owner={{ value: ownerKey, options: people }} ownerLabel="Owner" />
+<CommentCount conversation={{ count: 4, href: conversationHref, unread: isMemberWithUnread }} />
+```
+
+- `unread` only for a member of the conversation: anyone else sees the count alone.
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Draws a value as words where it may not be changed | a disabled select |
+| Says the count and whether it is unread to a screen reader | an `aria-label` of your own |
+
+## Props
+
+<Controls of={LinkPartsStories.PickersReadOnly} />

package/src/LinkParts.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+import { PEOPLE, STATUS_OPTIONS } from './linked.examples'
+import { CommentCount, LinkPickers, ProgressRing, StatusMark } from './LinkParts'
+
+const meta = {
+  title: 'Components/LinkParts',
+  component: LinkPickers,
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof LinkPickers>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A status and an owner, changed from the card. */
+export const Pickers: Story = {
+  render: () => {
+    const [status, setStatus] = useState('todo')
+    const [owner, setOwner] = useState<string | undefined>(undefined)
+    return (
+      <LinkPickers
+        status={{ value: status, options: STATUS_OPTIONS, onChange: setStatus }}
+        owner={{ value: owner, options: PEOPLE, onChange: setOwner }}
+        ownerLabel="Owner"
+      />
+    )
+  },
+}
+
+/** To a reader who may not change them, and in the hover preview: the same values, as words. */
+export const PickersReadOnly: Story = {
+  args: { status: { value: 'doing', options: STATUS_OPTIONS }, owner: { value: 'b', options: PEOPLE } },
+}
+
+/** Nobody owns it yet, read only. */
+export const NoOwner: Story = {
+  args: { status: { value: 'todo', options: STATUS_OPTIONS }, owner: { value: undefined, options: PEOPLE } },
+}
+
+/** The count of what was said, opening where it is read. With something unread, to a member: brighter, with a dot. */
+export const Conversation: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <CommentCount conversation={{ count: 4, href: '#conversation' }} />
+      <CommentCount conversation={{ count: 5, href: '#conversation', unread: true }} />
+    </div>
+  ),
+}
+
+/** A status as its shape, and progress as a ring. */
+export const Marks: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      {STATUS_OPTIONS.map((option) => (
+        <StatusMark key={option.value} status={{ label: option.label, colour: option.colour! }} />
+      ))}
+      <ProgressRing done={2} total={5} />
+      <ProgressRing done={5} total={5} />
+    </div>
+  ),
+}

package/src/LinkParts.tsx

@@ -0,0 +1,147 @@
+/**
+ * The small parts every link widget is built from: the icon for what a link
+ * stands for, a status as its shape, progress as a ring, the conversation
+ * count with its unread dot, and the pickers. LinkChip, LinkRow and LinkCard
+ * place them; an app may place them too.
+ */
+import { IconCircle, IconCircleCheck, IconCircleDashed, IconCircleHalf2, IconCircleX, IconFileText, IconMessage2 } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { cn } from './cn'
+import { KindIcon } from './KindIcon'
+import { Link } from './Link'
+import { chosenOf, type LinkedConversation, type LinkedKind, type LinkedPicker, type LinkedStatus, type StatusColour } from './linked'
+import { Select } from './Select'
+import { WithTooltip } from './Tooltip'
+import { UnreadDot } from './UnreadDot'
+
+const STATUS_ICON: Record<StatusColour, { Icon: typeof IconCircle; tone: string }> = {
+  neutral: { Icon: IconCircleDashed, tone: 'text-text-secondary' },
+  blue: { Icon: IconCircleHalf2, tone: 'text-info-default' },
+  green: { Icon: IconCircleCheck, tone: 'text-success-default' },
+  muted: { Icon: IconCircleX, tone: 'text-text-muted' },
+}
+
+/** A status's shape alone, beside words that already name it. */
+function StatusIcon({ colour }: { colour: StatusColour }) {
+  const { Icon, tone } = STATUS_ICON[colour]
+  return <Icon size={14} stroke={1.5} className={cn('shrink-0', tone)} aria-hidden />
+}
+
+/** A status as its shape, which reads without colour; its words on hover and to a screen reader. */
+export function StatusMark({ status }: { status: LinkedStatus }) {
+  return (
+    <WithTooltip label={status.label} inline wrapperClassName="inline-flex shrink-0 items-center">
+      <StatusIcon colour={status.colour} />
+      <span className="sr-only">{status.label}</span>
+    </WithTooltip>
+  )
+}
+
+/** The icon for what a link stands for. A page of text has its own. */
+export function LinkedIcon({ kind, size = 16, tone = 'secondary' }: { kind: LinkedKind; size?: 14 | 16; tone?: 'secondary' | 'inherit' }) {
+  if (kind === 'page') return <IconFileText size={size} stroke={1.5} className={cn('shrink-0', tone === 'secondary' && 'text-text-secondary')} aria-hidden />
+  return <KindIcon kind={kind} size={size} tone={tone} />
+}
+
+/** A key, the way people say it ("ABC-2"): before the title, quieter than it. */
+export function LinkKey({ children }: { children: string }) {
+  return <span className="shrink-0 text-caption tabular-nums text-text-muted">{children}</span>
+}
+
+/** Progress as a small ring, with the count beside it. */
+export function ProgressRing({ done, total }: { done: number; total: number }) {
+  const size = 16
+  const stroke = 2
+  const r = (size - stroke) / 2
+  const c = 2 * Math.PI * r
+  const share = total > 0 ? Math.min(done, total) / total : 0
+  return (
+    <WithTooltip label={`${done} of ${total} done`} inline wrapperClassName="inline-flex shrink-0">
+      <span className="inline-flex shrink-0 items-center gap-1 text-caption tabular-nums text-text-secondary">
+        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} className="shrink-0 -rotate-90" aria-hidden>
+          <circle cx={size / 2} cy={size / 2} r={r} fill="none" strokeWidth={stroke} className="stroke-border-default" />
+          <circle cx={size / 2} cy={size / 2} r={r} fill="none" strokeWidth={stroke} strokeLinecap="round" strokeDasharray={`${c * share} ${c}`} className="stroke-success-default" />
+        </svg>
+        {done}/{total}
+      </span>
+    </WithTooltip>
+  )
+}
+
+/**
+ * The count of what was said, a link to where it is read. With something
+ * unread there the words are brighter and a dot follows. It sits above a
+ * row's covering link, so the row opens the thing and the count its
+ * conversation.
+ */
+export function CommentCount({ conversation, noun = 'comments' }: { conversation: LinkedConversation; noun?: string }) {
+  const { count, href, unread = false } = conversation
+  return (
+    <span className={cn('relative z-10 -mx-1 inline-flex shrink-0 rounded-sm px-1 text-caption tabular-nums hover:bg-bg-active', unread ? 'font-medium text-text-primary' : 'text-text-secondary')}>
+      <Link href={href} variant="plain" className="inline-flex items-center gap-1">
+        <IconMessage2 size={14} stroke={1.5} aria-hidden />
+        {count}
+        <span className="sr-only">{unread ? `${noun}, unread — open the conversation` : `${noun} — open the conversation`}</span>
+        {unread && <UnreadDot className="h-auto w-auto" />}
+      </Link>
+    </span>
+  )
+}
+
+export interface LinkPickersProps {
+  status?: LinkedPicker
+  owner?: LinkedPicker
+  /** The owner's word: "Assignee", "Lead". */
+  ownerLabel?: string
+  /** Draws the values as words even where they could be changed: the hover preview. */
+  readOnly?: boolean
+}
+
+/**
+ * A status and an owner, where the reader can change them from the card. A
+ * picker whose app passed no `onChange` reads as words in the same place: the
+ * reader may not change it. The hover preview is always words.
+ */
+export function LinkPickers({ status, owner, ownerLabel = 'Owner', readOnly = false }: LinkPickersProps) {
+  const statusNow = chosenOf(status)
+  const ownerNow = chosenOf(owner)
+  const statusWords = status && (readOnly || !status.onChange)
+  const ownerWords = owner && (readOnly || !owner.onChange)
+  return (
+    <span className="flex h-6 min-w-0 items-center gap-2 text-caption text-text-secondary">
+      {status &&
+        (statusWords ? (
+          <span className="inline-flex shrink-0 items-center gap-1">
+            {statusNow?.colour && <StatusIcon colour={statusNow.colour} />}
+            {statusNow?.label ?? 'No status'}
+          </span>
+        ) : (
+          <Select
+            size="small"
+            className="w-auto"
+            value={status.value ?? ''}
+            onChange={(value) => status.onChange?.(value)}
+            ariaLabel="Status"
+            options={status.options.map((option) => ({ value: option.value, label: option.label, leading: option.colour && <StatusIcon colour={option.colour} /> }))}
+          />
+        ))}
+      {owner &&
+        (ownerWords ? (
+          <span className="inline-flex min-w-0 items-center gap-1">
+            <Avatar name={ownerNow?.label} src={ownerNow?.picture} size={16} />
+            <span className="truncate">{ownerNow?.label ?? 'Unassigned'}</span>
+          </span>
+        ) : (
+          <Select
+            size="small"
+            className="w-auto"
+            value={owner.value ?? ''}
+            placeholder="Unassigned"
+            onChange={(value) => owner.onChange?.(value)}
+            ariaLabel={ownerLabel}
+            options={owner.options.map((option) => ({ value: option.value, label: option.label, leading: <Avatar name={option.label} src={option.picture} size={16} /> }))}
+          />
+        ))}
+    </span>
+  )
+}

package/src/LinkPreview.mdx

@@ -0,0 +1,47 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkPreviewStories from './LinkPreview.stories'
+
+<Meta of={LinkPreviewStories} />
+
+# LinkPreview
+
+A link's card on hover over its chip or its row, read only, in the package's one elevated box.
+
+<Canvas of={LinkPreviewStories.OnHover} />
+
+## When
+
+- **on hover** — **LinkChip** and **LinkRow** wrap themselves in it; an app wraps its own trigger only when it draws a link some other way.
+- **open** — `LinkPreviewOpen`, the same box drawn open, for a still picture.
+- **on a screen that cannot hover** — nothing: the trigger alone, and a tap opens the link. `useCanHover()` says which.
+
+<Canvas of={LinkPreviewStories.Open} />
+
+## When not
+
+- A card that stays → **LinkCard**, or **CardUnder** under a piece of text.
+- A preview of something that is not a link → **PreviewCard**.
+
+## How
+
+```tsx
+import { LinkPreview } from '@estiva-app/ui'
+
+<LinkPreview linked={linked} block>
+  {yourRow}
+</LinkPreview>
+```
+
+- `block` for a trigger that fills its column; a chip is inline.
+- Nothing in it can be changed: the values are words.
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Waits before it opens, and closes when the pointer leaves | a hover timer |
+| Draws no preview on a screen that cannot hover | a `matchMedia` check |
+
+## Props
+
+<Controls of={LinkPreviewStories.OnHover} />

package/src/LinkPreview.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { LinkChip } from './LinkChip'
+import { GROUP, ITEM, PLACE, ready } from './linked.examples'
+import { LinkPreview, LinkPreviewOpen } from './LinkPreview'
+import { LinkRow } from './LinkRow'
+
+const meta = {
+  title: 'Components/LinkPreview',
+  component: LinkPreview,
+  parameters: { layout: 'padded' },
+  args: { linked: ITEM, children: null },
+} satisfies Meta<typeof LinkPreview>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Hover the chip or the row: the card shows, read only. On a screen that cannot hover there is none, and a tap opens the link. */
+export const OnHover: Story = {
+  render: () => (
+    <div className="flex max-w-[480px] flex-col gap-3">
+      <p className="text-body-2 text-text-primary">
+        Hover <LinkChip link={ready(ITEM)} /> for its card.
+      </p>
+      <LinkRow link={ready(GROUP)} />
+    </div>
+  ),
+}
+
+/** Drawn open, for a still picture: the values are words, never pickers. */
+export const Open: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-start gap-4">
+      <LinkPreviewOpen linked={ITEM} />
+      <LinkPreviewOpen linked={GROUP} />
+      <LinkPreviewOpen linked={PLACE} />
+    </div>
+  ),
+}

package/src/LinkPreview.tsx

@@ -0,0 +1,55 @@
+/**
+ * A link's card, shown on hover over its chip or its row: read only, in the
+ * package's one elevated box. A screen that cannot hover draws no preview, and
+ * a tap opens the link (Miky, WID-2: "there's no hover on touch").
+ */
+import { useSyncExternalStore, type ReactNode } from 'react'
+import { LinkCard } from './LinkCard'
+import type { Linked } from './linked'
+import { MenuPanel } from './Menu'
+import { PreviewCard } from './PreviewCard'
+
+const HOVER = '(hover: hover)'
+
+function subscribe(onChange: () => void) {
+  if (typeof window === 'undefined' || !window.matchMedia) return () => {}
+  const query = window.matchMedia(HOVER)
+  query.addEventListener('change', onChange)
+  return () => query.removeEventListener('change', onChange)
+}
+
+/** Whether this screen can hover. Without `matchMedia` (a test, a server) it is taken to. */
+export function useCanHover(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => (typeof window === 'undefined' || !window.matchMedia ? true : window.matchMedia(HOVER).matches),
+    () => true,
+  )
+}
+
+export interface LinkPreviewProps {
+  linked: Linked
+  /** The trigger fills its column, as a row does; a chip is inline. */
+  block?: boolean
+  children: ReactNode
+}
+
+export function LinkPreview({ linked, block = false, children }: LinkPreviewProps) {
+  const canHover = useCanHover()
+  if (!canHover) return <>{children}</>
+  // A row fills its column; PreviewCard's own trigger is inline and would shrink it to its words.
+  return (
+    <PreviewCard side="bottom" content={<LinkCard link={{ state: 'ready', linked }} bare readOnly />} wrapperClassName={block ? 'grid w-full min-w-0 grid-cols-[minmax(0,1fr)]' : 'max-w-full'}>
+      {children}
+    </PreviewCard>
+  )
+}
+
+/** The preview drawn open, for a still picture of it: the same box PreviewCard draws. */
+export function LinkPreviewOpen({ linked }: { linked: Linked }) {
+  return (
+    <MenuPanel className="w-[360px] p-0">
+      <LinkCard link={{ state: 'ready', linked }} bare readOnly />
+    </MenuPanel>
+  )
+}

package/src/LinkRow.mdx

@@ -0,0 +1,47 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkRowStories from './LinkRow.stories'
+
+<Meta of={LinkRowStories} />
+
+# LinkRow
+
+A link alone on its line: one 36px row for every kind, with what it has in its corner.
+
+<Canvas of={LinkRowStories.EachKind} />
+
+## When
+
+- **ready** — the icon, the key, the title as the link, and in the corner its status, ring, owner, members or authors, and when it changed. Hovering it shows its card; a tap opens it.
+- **unread** — with something unread in its conversation the count shows, with its dot. A row otherwise keeps to one line and leaves the count to the card, except where conversations are what it holds.
+- **loading** — the row in bars, at the row's height.
+- **unavailable** — one line, "Item — not available.", with where it may still open (`openIn`). This is also what a card draws when it is not available: **LinkUnavailable**, from this file.
+
+<Canvas of={LinkRowStories.NotAvailable} />
+
+## When not
+
+- A link in a sentence → **LinkChip**.
+- The one card under a piece of text → **CardUnder**.
+
+## How
+
+```tsx
+import { LinkRow } from '@estiva-app/ui'
+
+<LinkRow link={{ state: 'ready', linked }} />
+```
+
+- The whole row opens `linked.href`; the conversation count opens `linked.conversation.href` on its own.
+- `linked.conversation.unread` is the app's to say, and only for a member of it.
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Covers the row with its link, with the count above it | a click handler on the row |
+| Shows the card on hover, and none on a screen that cannot hover | a hover card of your own |
+| Holds the row's height while it loads and when it is not available | a placeholder height of your own |
+
+## Props
+
+<Controls of={LinkRowStories.Default} />