@estiva-app/ui 0.74.1 → 0.75.0

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 |