@estiva-app/ui 0.74.0 → 0.75.0

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

package/src/linked.ts

@@ -0,0 +1,217 @@
+/**
+ * What a link stands for, as the link widgets draw it (LinkChip, LinkRow,
+ * LinkCard, LinkPreview, CardUnder). The app builds it from its own lookup —
+ * every Estiva app from `@estiva-app/interop`'s projection — and hands it in
+ * whole: the words, the addresses, and the changes the reader may make. The
+ * widgets look nothing up, and keep nothing but what a reader does to them.
+ *
+ * The shape follows the prototype Miky approved (Widgets 2, 15 Oct; why:
+ * https://github.com/estiva-app/estiva-docs/blob/main/decisions/where-a-link-sits-and-which-file-gets-the-card.md).
+ */
+import type { ThingKind } from './KindIcon'
+
+/** What a link stands for, by its icon. `page` draws a page of text. */
+export type LinkedKind = ThingKind | 'page'
+
+/** The colours a status draws in, as an app's manifest names them. */
+export type StatusColour = 'neutral' | 'blue' | 'green' | 'muted'
+
+/** One value of a status, as the reader sees it. */
+export interface LinkedStatus {
+  label: string
+  colour: StatusColour
+}
+
+/** A person, by the name the app shows and, when it has one, their picture. */
+export interface LinkedPerson {
+  name: string
+  picture?: string
+}
+
+/** One choice a picker offers. */
+export interface PickerOption {
+  value: string
+  label: string
+  /** A status's colour: the option draws its shape. */
+  colour?: StatusColour
+  /** A person's picture: the option draws their face. */
+  picture?: string
+}
+
+/**
+ * A value the reader may be able to change from the card: a status, or who
+ * owns it. With `onChange` it is a picker; without it, the reader may not
+ * change it, and it reads as words in the same place.
+ */
+export interface LinkedPicker {
+  /** The chosen option's `value`; `undefined` is nobody, for an owner. */
+  value: string | undefined
+  options: PickerOption[]
+  onChange?: (value: string) => void
+}
+
+/** The count of what was said about it, and where that is read. */
+export interface LinkedConversation {
+  count: number
+  /** Opens the conversation, at the first unread when there is one. */
+  href: string
+  /**
+   * The reader has something unread there. Only a member of it has unread
+   * (SPEC §11.8; why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/membership-replaces-following.md),
+   * so the app passes `true` only for one.
+   */
+  unread?: boolean
+}
+
+/** One item listed inside a card, such as a group's members, each opening on its own. */
+export interface LinkedChild {
+  id: string
+  title: string
+  href: string
+  key?: string
+  status: LinkedStatus
+  owner?: LinkedPerson
+}
+
+/** Everything a link's widgets may draw about what it stands for. Only `id`, `kind`, `title` and `href` are always there. */
+export interface Linked {
+  /** Its address. Two `Linked` with the same `id` are the same thing (identity by value, not by object). */
+  id: string
+  kind: LinkedKind
+  title: string
+  /** Opens it. An address in this app goes through `AppProvider`'s `navigate`. */
+  href: string
+  /** What the reader calls it, quietly before the title: "ABC-2". */
+  key?: string
+  /** The line under a card's title: what it is in. Drawn after the key. */
+  subtitle?: string
+  /** Its short summary, a sentence or two. Without one a card shows the title alone. */
+  summary?: string
+  /** Its status: each option carries its `colour`. */
+  status?: LinkedPicker
+  /** Who owns it, by the word the app uses (`ownerLabel`: "Assignee", "Lead"). */
+  owner?: LinkedPicker
+  ownerLabel?: string
+  /** What was said about it. `noun` names it for a screen reader: "comments" by default. */
+  conversation?: LinkedConversation & { noun?: string }
+  /** Items inside it, drawn as rows in its card. */
+  children?: LinkedChild[]
+  /** How far along it is, drawn as a ring. */
+  done?: { done: number; total: number }
+  /** Who is in it, as faces. */
+  members?: LinkedPerson[]
+  /** Who wrote it, as faces. */
+  authors?: LinkedPerson[]
+  /** When it last changed, in the app's words: "2h ago". */
+  updated?: string
+  /** The newest thing said in it, drawn only when the reader may read it. */
+  latest?: { author: LinkedPerson; body: string; at: string }
+  /** Words a person wrote, linked as themselves: drawn with `author`'s face, not an icon. */
+  body?: string
+  author?: LinkedPerson
+}
+
+/** What a card's last line holds: pickers, faces, a line of words, or nothing. */
+export type LoadingFooter = 'pickers' | 'people' | 'line' | 'none'
+
+/** The parts of a card known before it loads, so its placeholder takes the card's height. */
+export interface LoadingShape {
+  subtitle?: boolean
+  summary?: boolean
+  rows?: number
+  latest?: boolean
+  ring?: boolean
+  footer?: LoadingFooter
+}
+
+/**
+ * Where a link's lookup stands. `loading` knows the kind from the address, and
+ * a shape when the app remembers one; `unavailable` is deleted or not the
+ * reader's to see, which read the same (Miky, 15 Oct).
+ */
+export type LinkState =
+  | { state: 'loading'; kind: LinkedKind; shape?: LoadingShape }
+  | {
+      state: 'unavailable'
+      kind: LinkedKind
+      /** What it is, in a word: "Item". */
+      noun: string
+      /** Where it may still open for someone who can: the app that owns it, and its address. */
+      openIn?: { app: string; href: string }
+    }
+  | { state: 'ready'; linked: Linked }
+
+/** A picker's chosen option, or none. */
+export function chosenOf(picker: LinkedPicker | undefined): PickerOption | undefined {
+  return picker?.value === undefined ? undefined : picker.options.find((option) => option.value === picker.value)
+}
+
+/** The shape `linked`'s card takes, for its placeholder the next time it loads. */
+export function loadingShapeOf(linked: Linked): LoadingShape {
+  return {
+    subtitle: !!(linked.subtitle || linked.key),
+    summary: !!linked.summary,
+    rows: linked.children?.length ?? 0,
+    latest: !!linked.latest,
+    ring: !!linked.done,
+    footer: linked.status || linked.owner ? 'pickers' : linked.authors ? 'people' : 'line',
+  }
+}
+
+/**
+ * What this device last found it could not show, kept so the next open draws
+ * "not available." from the first paint instead of a card's height that then
+ * closes (Peek's OPT-10; Miky, 15 Oct). One per app, under its own key, in
+ * localStorage because the first paint reads it synchronously. The app clears
+ * it with the rest of the device's copy at sign-out.
+ */
+export interface UnavailableMemory {
+  /** Whether this device last found `id` not available. */
+  has: (id: string) => boolean
+  /** The lookup's answer: remembered when not available, forgotten when it is. */
+  note: (id: string, available: boolean) => void
+  /** Sign-out. */
+  clear: () => void
+}
+
+/** The device's memory of links it could not show, under the app's own `storageKey`, keeping the newest `limit`. */
+export function unavailableMemory(storageKey: string, limit = 300): UnavailableMemory {
+  // Read once per page: a screen of cards asks many times.
+  let held: Set<string> | undefined
+  const list = () => {
+    if (held) return held
+    try {
+      const stored: unknown = JSON.parse(localStorage.getItem(storageKey) ?? '[]')
+      held = new Set(Array.isArray(stored) ? stored.filter((item): item is string => typeof item === 'string') : [])
+    } catch {
+      held = new Set()
+    }
+    return held
+  }
+  return {
+    has: (id) => list().has(id),
+    note: (id, available) => {
+      // Re-read before writing: another memory on this key, or another tab's sign-out, may have changed it since.
+      held = undefined
+      const current = list()
+      if (available !== current.has(id)) return
+      const next = new Set(current)
+      if (available) next.delete(id)
+      else next.add(id)
+      held = new Set([...next].slice(-limit))
+      try {
+        localStorage.setItem(storageKey, JSON.stringify([...held]))
+      } catch {
+        // Full or blocked storage: the next page draws the card as if never seen, which is only the first-open jump.
+      }
+    },
+    clear: () => {
+      held = undefined
+      try {
+        localStorage.removeItem(storageKey)
+      } catch {
+        // Nothing to clear where storage is blocked.
+      }
+    },
+  }
+}

package/src/registry/registry.test.ts

@@ -48,20 +48,20 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 178 names over 84 files: 119 components, 57 helpers and 2 hooks (InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
+  it('counts 197 names over 92 files: 134 components, 60 helpers and 3 hooks (the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 119, helper: 57, hook: 2 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(84)
+    expect(kinds).toEqual({ component: 134, helper: 60, hook: 3 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(92)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(80)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(98)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(86)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(111)
   })
 
   it('takes a name with a page of its own from the page, and a name without one from the code', () => {
@@ -262,8 +262,8 @@ describe('the ids point at something', () => {
 
   it('gives every component a page and a story, and only a helper none', () => {
     const without = registry.entries.filter((one) => one.docsId === null || one.storyId === null)
-    // The helpers in a file with no page: cn, the shortcut names, and the editor's suggestion wiring (documented on SuggestionMenu's page).
-    expect(without.map((one) => one.name).sort()).toEqual(['cn', 'isApplePlatform', 'isSuggestionActive', 'isSuggestionOpen', 'shortcutLabel', 'suggestionPopup'])
+    // The helpers in a file with no page: cn, the shortcut names, the editor's suggestion wiring (documented on SuggestionMenu's page), and the link widgets' data helpers (documented on LinkCard's and LinkChip's pages).
+    expect(without.map((one) => one.name).sort()).toEqual(['chosenOf', 'cn', 'isApplePlatform', 'isSuggestionActive', 'isSuggestionOpen', 'loadingShapeOf', 'shortcutLabel', 'suggestionPopup', 'unavailableMemory'])
     expect(without.every((one) => one.kind !== 'component')).toBe(true)
   })
 
@@ -299,7 +299,7 @@ describe('the ids point at something', () => {
 describe('a second parser agrees', async () => {
   const docgen = await import('react-docgen').catch(() => null)
 
-  it.skipIf(!docgen)('finds the same props on all 80 components', async () => {
+  it.skipIf(!docgen)('finds the same props on all 86 components', async () => {
     if (!docgen) return
     const resolver = new docgen.builtinResolvers.FindExportedDefinitionsResolver({ limit: 0 })
     const byName = new Map(registry.entries.map((one) => [one.name, one]))

package/stories/Choosing.mdx

@@ -106,6 +106,13 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A URL in a document that reads as the chip of what it points at | **LinkChips** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app says what each URL names |
 | Open a chip in a document, or choose its card, while writing | **ReferenceMenu** — from `@estiva-app/ui/editor`, beside `ReferenceCards`; a click on the chip, or putting one in, opens it |
 | A code block in an editor, coloured by its language as you type | **CodeBlockColours** — from `@estiva-app/ui/editor`, in place of the starter kit's code block |
+| A link to something an app looked up, in a sentence | **LinkChip** — hover shows its card; loading and "not available" drawn for you. **LinkChips** (editor) turns a URL in a document into one |
+| A link alone on its line | **LinkRow** — one 36px line for every kind; **LinkUnavailable** when it cannot be read |
+| A link's card: what a row cannot hold, with the pickers the reader may use | **LinkCard** — `onChange` on a picker only for a reader who may change it; **LinkCardLoading** at its height |
+| The one card under a piece of text, with the ✕ that removes it | **CardUnder** — `revealOnHover` once it is sent |
+| A link's card on hover, read only | **LinkPreview** — LinkChip and LinkRow already wrap themselves in it |
+| A part of something longer, shared live | **PartCard** — the app draws the blocks |
+| A status and an owner changed in place, a conversation count with its unread dot, a ring | **LinkParts** — `LinkPickers`, `CommentCount`, `StatusMark`, `ProgressRing` |
 | A person or a thing named inside a sentence | **InlineChip** — one line high, level with the words; `href` makes it a link |
 | What kind of thing a name stands for — a topic, a project, an issue, a file, a message | **KindIcon** — before the name in a row, or inside an **InlineChip**; `thingKindOf` turns an event kind into one |
 | Formatted text: headings, lists, a quote, code, a table, links | **RichText** — pass the parsed tree; `small` inside a card |