@estiva-app/ui 0.74.0 → 0.75.0

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} />

package/src/LinkRow.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { GROUP, ITEM, ITEM_UNREAD, LOADING, PAGE, PLACE, ready, SAID, UNAVAILABLE } from './linked.examples'
+import { LinkRow, LinkUnavailable } from './LinkRow'
+
+const meta = {
+  title: 'Components/LinkRow',
+  component: LinkRow,
+  parameters: { layout: 'padded' },
+  args: { link: ready(ITEM) },
+  decorators: [(Story) => <div className="max-w-[480px]">{Story()}</div>],
+} satisfies Meta<typeof LinkRow>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A link alone on its line. Hover it for its card. */
+export const Default: Story = {}
+
+/** Every kind: the corner says what each one has. */
+export const EachKind: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <LinkRow link={ready(ITEM)} />
+      <LinkRow link={ready(GROUP)} />
+      <LinkRow link={ready(PLACE)} />
+      <LinkRow link={ready(PAGE)} />
+      <LinkRow link={ready(SAID)} />
+    </div>
+  ),
+}
+
+/** Something unread in its conversation, to a member: the count shows, with its dot. */
+export const Unread: Story = { args: { link: ready(ITEM_UNREAD) } }
+
+/** Still being looked up: the row in bars, at the row's height. */
+export const Loading: Story = { args: { link: LOADING } }
+
+/** Deleted, or not this reader's to see: one line, and where it may still open. */
+export const NotAvailable: Story = { args: { link: UNAVAILABLE } }
+
+/** The not-available line on its own, as a card or a part draws it too; without `openIn`, no way out. */
+export const NotAvailableLine: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <LinkUnavailable kind="issue" noun="Item" openIn={{ app: 'App one', href: '#elsewhere' }} />
+      <LinkUnavailable kind="page" noun="Page" />
+    </div>
+  ),
+}

package/src/LinkRow.test.tsx

@@ -0,0 +1,38 @@
+// @vitest-environment jsdom
+/** What the LinkRow page claims, pinned: where the row and its count lead, and when the count shows. */
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { ITEM, ITEM_UNREAD, LOADING, PLACE, ready, UNAVAILABLE } from './linked.examples'
+import { LinkRow } from './LinkRow'
+
+afterEach(cleanup)
+
+describe('LinkRow', () => {
+  it('opens what it links from the whole row', () => {
+    render(<LinkRow link={ready(ITEM)} preview={false} />)
+    expect(screen.getByRole('link', { name: ITEM.title }).getAttribute('href')).toBe('#item')
+  })
+
+  it('keeps to one line: the count shows only when something in it is unread', () => {
+    const { rerender } = render(<LinkRow link={ready(ITEM)} preview={false} />)
+    expect(screen.queryByRole('link', { name: /open the conversation/ })).toBeNull()
+    rerender(<LinkRow link={ready(ITEM_UNREAD)} preview={false} />)
+    expect(screen.getByRole('link', { name: /unread — open the conversation/ }).getAttribute('href')).toBe('#item-conversation')
+  })
+
+  it('always shows the count where conversations are what it holds', () => {
+    render(<LinkRow link={ready(PLACE)} preview={false} />)
+    expect(screen.getByRole('link', { name: /conversations — open the conversation/ })).toBeTruthy()
+  })
+
+  it('while it loads, is busy and leads nowhere yet', () => {
+    const { container } = render(<LinkRow link={LOADING} />)
+    expect(container.querySelector('[aria-busy="true"]')).not.toBeNull()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('says it is not available in one line', () => {
+    render(<LinkRow link={UNAVAILABLE} />)
+    expect(screen.getByText('Item — not available.')).toBeTruthy()
+  })
+})

package/src/LinkRow.tsx

@@ -0,0 +1,107 @@
+/**
+ * A link alone on its line: one 36px row for every kind. Hovering it shows its
+ * card; a tap opens it. Loading draws the row in bars; not available says so
+ * in one line of the same height.
+ */
+import { Avatar } from './Avatar'
+import { AvatarGroup } from './AvatarGroup'
+import { Card } from './Card'
+import { Link } from './Link'
+import { chosenOf, type LinkedKind, type LinkState } from './linked'
+import { CommentCount, LinkedIcon, LinkKey, ProgressRing, StatusMark } from './LinkParts'
+import { LinkPreview } from './LinkPreview'
+import { SkeletonBar } from './Skeleton'
+
+export interface LinkUnavailableProps {
+  kind: LinkedKind
+  /** What it is, in a word: "Item". Drawn as "Item — not available.". */
+  noun: string
+  /** Where it may still open, for someone who can: its app and address. */
+  openIn?: { app: string; href: string }
+}
+
+/**
+ * Not available: deleted, or not this reader's to see, which read the same.
+ * One line at a row's height, whether a row or a card was to draw. The way
+ * out stays, since the app it lives in may still open it for you.
+ */
+export function LinkUnavailable({ kind, noun, openIn }: LinkUnavailableProps) {
+  return (
+    <Card fill="none" unreadable className="flex h-9 items-center gap-2 px-3">
+      <LinkedIcon kind={kind} />
+      <span className="min-w-0 flex-1 truncate text-body-2 text-text-muted">{noun} — not available.</span>
+      {openIn && (
+        <span className="shrink-0 text-caption text-text-secondary">
+          <Link href={openIn.href} variant="quiet" external>
+            Open in {openIn.app} ↗
+          </Link>
+        </span>
+      )}
+    </Card>
+  )
+}
+
+export interface LinkRowProps {
+  link: LinkState
+  /** Hovering shows its card. */
+  preview?: boolean
+}
+
+export function LinkRow({ link, preview = true }: LinkRowProps) {
+  if (link.state === 'loading') {
+    return (
+      <div className="animate-skeleton-in" aria-busy>
+        <Card fill="inset" aria-hidden className="flex h-9 items-center gap-2 px-3">
+          <LinkedIcon kind={link.kind} />
+          <SkeletonBar on="inset" className="h-3 w-2/5" />
+          <SkeletonBar on="inset" shape="round" className="ml-auto size-4" />
+        </Card>
+      </div>
+    )
+  }
+  if (link.state === 'unavailable') return <LinkUnavailable kind={link.kind} noun={link.noun} openIn={link.openIn} />
+  const { linked } = link
+  const status = chosenOf(linked.status)
+  const owner = chosenOf(linked.owner)
+  const said = linked.kind === 'message' && linked.author
+  const row = (
+    <Card fill="inset" hover="hairline" className="relative flex h-9 items-center gap-2 px-3">
+      {said ? <Avatar name={said.name} src={said.picture} size={16} /> : <LinkedIcon kind={linked.kind} />}
+      {said ? (
+        <span className="flex min-w-0 flex-1 items-baseline gap-2 text-body-2">
+          <span className="shrink-0 text-body-2-strong text-text-primary">{said.name}</span>
+          <span className="contents text-text-secondary">
+            <Link href={linked.href} variant="quiet" cover truncate>
+              {linked.body ?? linked.title}
+            </Link>
+          </span>
+        </span>
+      ) : (
+        <>
+          {linked.key && <LinkKey>{linked.key}</LinkKey>}
+          <span className="contents text-body-2-strong text-text-primary">
+            <Link href={linked.href} variant="quiet" cover truncate className="min-w-0 flex-1">
+              {linked.title}
+            </Link>
+          </span>
+        </>
+      )}
+      {linked.updated && <span className="shrink-0 text-caption text-text-secondary">{linked.updated}</span>}
+      {/* A row keeps to one line: the count shows only when there is something unread in it, except where conversations are what it holds. */}
+      {linked.conversation && (linked.conversation.unread || linked.kind === 'topic') && <CommentCount conversation={linked.conversation} noun={linked.conversation.noun} />}
+      {/* A ring already says how far along it is. */}
+      {status?.colour && !linked.done && <StatusMark status={{ label: status.label, colour: status.colour }} />}
+      {linked.done && <ProgressRing done={linked.done.done} total={linked.done.total} />}
+      {owner && <Avatar name={owner.label} src={owner.picture} size={16} />}
+      {linked.members && <AvatarGroup members={linked.members} size={16} />}
+      {linked.authors && <AvatarGroup members={linked.authors} size={16} />}
+    </Card>
+  )
+  return preview ? (
+    <LinkPreview linked={linked} block>
+      {row}
+    </LinkPreview>
+  ) : (
+    row
+  )
+}

package/src/PartCard.mdx

@@ -0,0 +1,43 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PartCardStories from './PartCard.stories'
+
+<Meta of={PartCardStories} />
+
+# PartCard
+
+A part of something longer, shared live: its blocks as they are now, under the header of what it is part of.
+
+<Canvas of={PartCardStories.Default} />
+
+## When
+
+- **ready** — the icon, the key and the title of what it is part of, as the link, and the blocks the app draws as `children`.
+- **loading** — at a card's height.
+- **unavailable** — one line: "A part of this item — not available.".
+
+## When not
+
+- A link to the whole thing → **LinkCard** or **CardUnder**.
+
+## How
+
+```tsx
+import { PartCard } from '@estiva-app/ui'
+
+<PartCard state="ready" kind={kind} heading={title} partKey={key} href={hrefAtThePart}>
+  {blocksDrawnByTheApp}
+</PartCard>
+```
+
+- The blocks are the app's to draw, with its own renderer.
+- There is no ✕: to send without the part, the writer deletes the link.
+
+## What it owns
+
+| It does | So you never write |
+|---|---|
+| Marks the blocks as quoted from elsewhere | a border of your own |
+
+## Props
+
+<Controls of={PartCardStories.Default} />

package/src/PartCard.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { PartCard } from './PartCard'
+
+const meta = {
+  title: 'Components/PartCard',
+  component: PartCard,
+  parameters: { layout: 'padded' },
+  decorators: [(Story) => <div className="max-w-[480px]">{Story()}</div>],
+} satisfies Meta<typeof PartCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A part of something longer, under the header of what it is part of. */
+export const Default: Story = {
+  args: {
+    state: 'ready',
+    kind: 'issue',
+    heading: 'Item one',
+    partKey: 'ABC-2',
+    href: '#part',
+    children: (
+      <>
+        <p className="text-body-2-strong text-text-primary">A heading in the part</p>
+        <p className="text-body-2 text-text-secondary">The blocks of the part, as they are now. They change when the text they came from changes.</p>
+      </>
+    ),
+  },
+}
+
+/** Still being looked up. */
+export const Loading: Story = { args: { state: 'loading', kind: 'issue' } }
+
+/** The part, or what it is part of, is gone or not this reader's to see. */
+export const NotAvailable: Story = { args: { state: 'unavailable', kind: 'issue', noun: 'Item', openIn: { app: 'App one', href: '#elsewhere' } } }

package/src/PartCard.test.tsx

@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+/** What the PartCard page claims, pinned: the header opens what it is part of, the blocks draw, and the states say so. */
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { PartCard } from './PartCard'
+
+afterEach(cleanup)
+
+describe('PartCard', () => {
+  it('opens what it is part of from its header, and draws the blocks it is given', () => {
+    render(
+      <PartCard kind="issue" heading="Item one" partKey="ABC-2" href="#part">
+        <p>The blocks</p>
+      </PartCard>,
+    )
+    expect(screen.getByRole('link', { name: /ABC-2.*Item one/ }).getAttribute('href')).toBe('#part')
+    expect(screen.getByText('The blocks')).toBeTruthy()
+  })
+
+  it('says a part is not available in words', () => {
+    render(<PartCard state="unavailable" kind="issue" noun="Item" />)
+    expect(screen.getByText('A part of this item — not available.')).toBeTruthy()
+  })
+
+  it('while it loads, is busy and shows nothing of it', () => {
+    const { container } = render(<PartCard state="loading" kind="issue" />)
+    expect(container.querySelector('[aria-busy="true"]')).not.toBeNull()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+})