@estiva-app/ui 0.74.1 → 0.75.0

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()
+  })
+})

package/src/PartCard.tsx

@@ -0,0 +1,59 @@
+/**
+ * A part of something longer, shared live: its blocks as they are now, under
+ * the header of what it is part of (why:
+ * https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-shared-part-of-a-page-is-a-selected-run-of-blocks.md).
+ * There is no row or card choice for a part: it draws itself. The app draws
+ * the blocks and passes them as `children`.
+ */
+import type { ReactNode } from 'react'
+import { Card } from './Card'
+import { Link } from './Link'
+import { LinkCardLoading } from './LinkCard'
+import type { LinkedKind } from './linked'
+import { LinkedIcon, LinkKey } from './LinkParts'
+import { LinkUnavailable } from './LinkRow'
+
+export interface PartCardProps {
+  /** Where its lookup stands. Default `ready`. */
+  state?: 'ready' | 'loading' | 'unavailable'
+  /** What it is part of, by its icon. */
+  kind: LinkedKind
+  /** The title of what it is part of. */
+  heading?: string
+  /** Opens what it is part of, at the part. */
+  href?: string
+  /** The key of what it is part of: "ABC-2". */
+  partKey?: string
+  /** What it is part of, in a word, for "A part of this item — not available.". */
+  noun?: string
+  /** Where it may still open, for someone who can, when it is not available. */
+  openIn?: { app: string; href: string }
+  /** The part's blocks, drawn by the app. */
+  children?: ReactNode
+}
+
+export function PartCard({ state = 'ready', kind, heading, href, partKey, noun = 'Item', openIn, children }: PartCardProps) {
+  if (state === 'loading') return <LinkCardLoading kind={kind} shape={{ summary: true, rows: 0, footer: 'none' }} />
+  if (state === 'unavailable') return <LinkUnavailable kind={kind} noun={`A part of this ${noun.toLowerCase()}`} openIn={openIn} />
+  const header = (
+    <>
+      <LinkedIcon kind={kind} />
+      {partKey && <LinkKey>{partKey}</LinkKey>}
+      <span className="truncate">{heading}</span>
+    </>
+  )
+  return (
+    <Card fill="inset" className="flex flex-col gap-2 p-3">
+      <span className="flex min-w-0 items-center gap-2 text-body-2-strong text-text-primary">
+        {href ? (
+          <Link href={href} variant="quiet" className="flex min-w-0 items-center gap-2">
+            {header}
+          </Link>
+        ) : (
+          header
+        )}
+      </span>
+      <div className="border-l-2 border-border-default pl-3">{children}</div>
+    </Card>
+  )
+}

package/src/Skeleton.tsx

@@ -10,10 +10,14 @@ import { cn } from './cn'
  * A list reveals after 150ms (`animate-skeleton-in`, in the preset) so a
  * fast load never flashes a skeleton — Peek's rule.
  */
+const SKELETON_SHAPE = { bar: 'rounded-sm', round: 'rounded-full', control: 'rounded-md' } as const
+
 /** One pulsing bar at the inset colour: the piece every placeholder here is
- *  built from. It draws nothing of its own — give it a width and a height. */
-export function SkeletonBar({ className, style }: { className?: string; style?: CSSProperties }) {
-  return <div className={cn('bg-bg-inset rounded-sm animate-pulse', className)} style={style} />
+ *  built from. It draws nothing of its own — give it a width and a height.
+ *  `on="inset"` on an inset card, where the inset colour would vanish;
+ *  `shape` for a line of words, a face or a ring, or a control. */
+export function SkeletonBar({ className, style, on = 'surface', shape = 'bar' }: { className?: string; style?: CSSProperties; on?: 'surface' | 'inset'; shape?: keyof typeof SKELETON_SHAPE }) {
+  return <div className={cn('animate-pulse', SKELETON_SHAPE[shape], on === 'inset' ? 'bg-bg-active' : 'bg-bg-inset', className)} style={style} />
 }
 
 const ROW_BAR_WIDTHS = [150, 100, 170, 120, 90, 140, 110, 160]

package/src/eslint/no-native-title.test.ts

@@ -60,8 +60,9 @@ tester.run('no-native-title', noNativeTitle, {
 
 describe('PARTS_WITH_A_TITLE', () => {
   it('is every part the catalogue says takes a title of its own, and no other', () => {
-    const registry = JSON.parse(readFileSync(new URL('../../registry.json', import.meta.url), 'utf8')) as { entries: { name: string; props?: { name: string }[] | null }[] }
-    const declared = registry.entries.filter((entry) => entry.props?.some((prop) => prop.name === 'title')).map((entry) => entry.name).sort()
+    const registry = JSON.parse(readFileSync(new URL('../../registry.json', import.meta.url), 'utf8')) as { entries: { name: string; kind: string; props?: { name: string }[] | null }[] }
+    // A part is a component: a helper whose argument has a `title` field (`loadingShapeOf`) is not drawn with one.
+    const declared = registry.entries.filter((entry) => entry.kind === 'component' && entry.props?.some((prop) => prop.name === 'title')).map((entry) => entry.name).sort()
     expect([...PARTS_WITH_A_TITLE].sort()).toEqual(declared)
   })
 })

package/src/eslint/no-restyled-part.ts

@@ -132,6 +132,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   Checkbox: ['row'],
   Chip: ['type'],
   KindIcon: ['tone'],
+  LinkedIcon: ['tone'],
   CollapsibleSection: ['look'],
   Divider: ['tone', 'orientation'],
   EmptyState: ['scope'],

package/src/index.ts

@@ -84,6 +84,31 @@ export { ShowMore, type ShowMoreProps } from './ShowMore'
 export { ReactionPicker, type ReactionOption, type ReactionPickerProps } from './ReactionPicker'
 export { Toolbar, ToolbarButton, ToolbarInput, ToolbarLink, ToolbarSeparator, type ToolbarProps, type ToolbarButtonProps, type ToolbarInputProps, type ToolbarLinkProps } from './Toolbar'
 export { PreviewCard, type PreviewCardProps } from './PreviewCard'
+// How a link draws, wherever it sits: one kit for every app (Widgets 2).
+export {
+  chosenOf,
+  loadingShapeOf,
+  unavailableMemory,
+  type Linked,
+  type LinkedChild,
+  type LinkedConversation,
+  type LinkedKind,
+  type LinkedPerson,
+  type LinkedPicker,
+  type LinkedStatus,
+  type LinkState,
+  type LoadingShape,
+  type PickerOption,
+  type StatusColour,
+  type UnavailableMemory,
+} from './linked'
+export { CommentCount, LinkedIcon, LinkKey, LinkPickers, ProgressRing, StatusMark, type LinkPickersProps } from './LinkParts'
+export { LinkChip, type LinkChipProps } from './LinkChip'
+export { LinkRow, LinkUnavailable, type LinkRowProps, type LinkUnavailableProps } from './LinkRow'
+export { LinkCard, LinkCardLoading, type LinkCardProps, type LinkCardLoadingProps } from './LinkCard'
+export { LinkPreview, LinkPreviewOpen, useCanHover, type LinkPreviewProps } from './LinkPreview'
+export { CardUnder, type CardUnderProps } from './CardUnder'
+export { PartCard, type PartCardProps } from './PartCard'
 export { Person, type PersonProps } from './Person'
 export { Rail, type RailProps } from './Rail'
 export { RailItem, type RailItemProps } from './RailItem'

package/src/linked.examples.ts

@@ -0,0 +1,107 @@
+/**
+ * Placeholder links for the link widgets' stories and tests: neutral words,
+ * every field one of the widgets draws. Not exported from the package.
+ */
+import type { Linked, LinkedPicker, LinkState, PickerOption } from './linked'
+
+const noop = () => {}
+
+export const STATUS_OPTIONS: PickerOption[] = [
+  { value: 'todo', label: 'Todo', colour: 'neutral' },
+  { value: 'doing', label: 'In progress', colour: 'blue' },
+  { value: 'done', label: 'Done', colour: 'green' },
+  { value: 'dropped', label: 'Cancelled', colour: 'muted' },
+]
+
+export const PEOPLE: PickerOption[] = [
+  { value: 'a', label: 'Person one' },
+  { value: 'b', label: 'Person two' },
+  { value: 'c', label: 'Person three' },
+]
+
+const picker = (value: string | undefined, options: PickerOption[], mayChange = true): LinkedPicker => ({ value, options, onChange: mayChange ? noop : undefined })
+
+const SUMMARY = 'A one-sentence summary of what this is for.'
+
+/** A tracked item: a key, a status and an owner the reader may change, and a conversation. */
+export const ITEM: Linked = {
+  id: 'example:item',
+  kind: 'issue',
+  title: 'Item one, with a title long enough to be cut short',
+  href: '#item',
+  key: 'ABC-2',
+  subtitle: 'Group one',
+  summary: SUMMARY,
+  status: picker('doing', STATUS_OPTIONS),
+  owner: picker('a', PEOPLE),
+  ownerLabel: 'Owner',
+  conversation: { count: 4, href: '#item-conversation' },
+}
+
+/** The same item, to a reader who may not change it. */
+export const ITEM_READ_ONLY: Linked = { ...ITEM, status: picker('doing', STATUS_OPTIONS, false), owner: picker('a', PEOPLE, false) }
+
+/** The same item with something unread in its conversation, as a member sees it. */
+export const ITEM_UNREAD: Linked = { ...ITEM, conversation: { count: 5, href: '#item-conversation', unread: true } }
+
+/** An item with no summary: its card shows the title alone. */
+export const ITEM_NO_SUMMARY: Linked = { ...ITEM, id: 'example:item-2', title: 'Item two', key: 'ABC-3', summary: undefined, owner: picker(undefined, PEOPLE) }
+
+/** A group of items: its progress, its owner, and the items inside it. */
+export const GROUP: Linked = {
+  id: 'example:group',
+  kind: 'project',
+  title: 'Group one',
+  href: '#group',
+  summary: SUMMARY,
+  status: picker('doing', STATUS_OPTIONS),
+  owner: picker('b', PEOPLE),
+  ownerLabel: 'Lead',
+  done: { done: 2, total: 5 },
+  conversation: { count: 2, href: '#group-conversation' },
+  children: [
+    { id: 'example:c1', title: 'Item one', href: '#c1', key: 'ABC-1', status: { label: 'Done', colour: 'green' }, owner: { name: 'Person one' } },
+    { id: 'example:c2', title: 'Item two', href: '#c2', key: 'ABC-2', status: { label: 'In progress', colour: 'blue' }, owner: { name: 'Person two' } },
+    { id: 'example:c3', title: 'Item three', href: '#c3', key: 'ABC-3', status: { label: 'Todo', colour: 'neutral' } },
+  ],
+}
+
+/** A place people talk: its members, when it last moved, and its newest conversation. */
+export const PLACE: Linked = {
+  id: 'example:place',
+  kind: 'topic',
+  title: 'Place one',
+  href: '#place',
+  summary: SUMMARY,
+  members: [{ name: 'Person one' }, { name: 'Person two' }, { name: 'Person three' }],
+  updated: '2h ago',
+  conversation: { count: 12, href: '#place-conversations', noun: 'conversations' },
+  latest: { author: { name: 'Person two' }, body: 'A few words someone wrote, long enough to need a second line before the card cuts them short.', at: '2h ago' },
+}
+
+/** A page of text: who wrote it, and when it last changed. */
+export const PAGE: Linked = {
+  id: 'example:page',
+  kind: 'page',
+  title: 'Page one',
+  href: '#page',
+  subtitle: 'Shelf one',
+  summary: SUMMARY,
+  authors: [{ name: 'Person one' }, { name: 'Person three' }],
+  updated: 'Yesterday',
+}
+
+/** Words a person wrote, linked as themselves. */
+export const SAID: Linked = {
+  id: 'example:said',
+  kind: 'message',
+  title: 'A few words someone wrote',
+  href: '#said',
+  author: { name: 'Person one' },
+  body: 'A few words someone wrote, linked from somewhere else. Long enough to wrap onto a second line.',
+  updated: '10:42',
+}
+
+export const ready = (linked: Linked): LinkState => ({ state: 'ready', linked })
+export const LOADING: LinkState = { state: 'loading', kind: 'issue' }
+export const UNAVAILABLE: LinkState = { state: 'unavailable', kind: 'issue', noun: 'Item', openIn: { app: 'App one', href: '#elsewhere' } }

package/src/linked.test.ts

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+/**
+ * The device's memory of links it could not show: kept across a reload, so
+ * the next open draws "not available." from the first paint, and forgotten
+ * when the link can be read again or at sign-out.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { unavailableMemory } from './linked'
+
+afterEach(() => localStorage.clear())
+
+describe('unavailableMemory', () => {
+  it('remembers a link it could not show across a reload', () => {
+    unavailableMemory('test.unavailable').note('a', false)
+    // A new page: a fresh memory reads what the last one wrote.
+    expect(unavailableMemory('test.unavailable').has('a')).toBe(true)
+    expect(unavailableMemory('test.unavailable').has('b')).toBe(false)
+  })
+
+  it('forgets it once it can be read again', () => {
+    const memory = unavailableMemory('test.unavailable')
+    memory.note('a', false)
+    memory.note('a', true)
+    expect(unavailableMemory('test.unavailable').has('a')).toBe(false)
+  })
+
+  it('keeps what another memory on the same key wrote since it was read', () => {
+    const one = unavailableMemory('test.unavailable')
+    const two = unavailableMemory('test.unavailable')
+    expect(two.has('a')).toBe(false)
+    one.note('a', false)
+    two.note('b', false)
+    const next = unavailableMemory('test.unavailable')
+    expect([next.has('a'), next.has('b')]).toEqual([true, true])
+  })
+
+  it('keeps each app’s memory apart', () => {
+    unavailableMemory('one.unavailable').note('a', false)
+    expect(unavailableMemory('two.unavailable').has('a')).toBe(false)
+  })
+
+  it('forgets everything at sign-out', () => {
+    const memory = unavailableMemory('test.unavailable')
+    memory.note('a', false)
+    memory.clear()
+    expect(memory.has('a')).toBe(false)
+    expect(unavailableMemory('test.unavailable').has('a')).toBe(false)
+  })
+
+  it('keeps only the newest, up to its limit', () => {
+    const memory = unavailableMemory('test.unavailable', 2)
+    memory.note('a', false)
+    memory.note('b', false)
+    memory.note('c', false)
+    const next = unavailableMemory('test.unavailable', 2)
+    expect([next.has('a'), next.has('b'), next.has('c')]).toEqual([false, true, true])
+  })
+})