@estiva-app/ui 0.85.0 → 0.86.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,286 @@
1
+ /**
2
+ * What a link stands for, built from `@estiva-app/interop`'s projection of the
3
+ * file — the one builder Peek, Ship and Leaf share, so one file draws as one
4
+ * card in every app (5ebf2756; why:
5
+ * https://github.com/estiva-app/estiva-docs/blob/main/decisions/every-app-edits-a-document-with-one-shared-editor.md).
6
+ *
7
+ * The package depends on neither interop nor protocol: {@link LinkedSource} is
8
+ * the part of interop's `ForeignObject` this reads, so any interop version's
9
+ * object fits, and what needs the protocol (where a link opens, a message's
10
+ * words, what an address is before it is read) is the app's, passed in.
11
+ */
12
+ import { thingKindOf } from './KindIcon'
13
+ import type { LinkState, Linked, LinkedChild, LinkedConversation, LinkedKind, LinkedPicker, StatusColour } from './linked'
14
+
15
+ /** A person as interop names them: a profile, possibly empty. */
16
+ export interface LinkedProfile {
17
+ displayName?: string
18
+ picture?: string
19
+ }
20
+
21
+ /** One of interop's resolved slots. */
22
+ export interface LinkedSlot {
23
+ value: string
24
+ label?: string
25
+ colour?: string
26
+ isPubkey?: boolean
27
+ field?: string
28
+ }
29
+
30
+ /** One of interop's resolved actions: what the file's own app lets a reader change. */
31
+ export interface LinkedAction {
32
+ id: string
33
+ label: string
34
+ control: string
35
+ field?: string
36
+ current?: string
37
+ options?: { value: string; label: string; colour?: string }[]
38
+ }
39
+
40
+ /** The part of interop's `ForeignObject` a link is built from. */
41
+ export interface LinkedSource {
42
+ ref: string
43
+ address?: string
44
+ eventId?: string
45
+ kind: number
46
+ widget: string | string[]
47
+ noun?: string
48
+ appName?: string
49
+ slots: Record<string, LinkedSlot | undefined>
50
+ meta: LinkedSlot[]
51
+ children?: LinkedSource[]
52
+ people?: Record<string, LinkedProfile>
53
+ actions: LinkedAction[]
54
+ parentField?: string
55
+ openUrl?: string
56
+ unreachable?: boolean
57
+ archived?: unknown
58
+ /** When it last changed, in seconds (interop 0.64). */
59
+ changedAt?: number
60
+ }
61
+
62
+ /** `T` is the app's own object type (interop's `ForeignObject`), so `hrefOf` takes it as it is. */
63
+ export interface LinkedFromOptions<T extends LinkedSource = LinkedSource> {
64
+ /**
65
+ * Where a file opens in this app: the linked file itself (`top`), or one of
66
+ * the rows on its card. Another app's address comes from a manifest anyone
67
+ * may publish, so the app keeps it to https.
68
+ */
69
+ hrefOf: (object: T, top: boolean) => string
70
+ /** A message's words for a one-line preview: marks stripped, references read as words. */
71
+ previewText: (body: string, people: Record<string, LinkedProfile> | undefined) => string
72
+ /** The workspace's people, for the owner picker's options. */
73
+ directory?: Record<string, LinkedProfile>
74
+ /**
75
+ * Changes the file from its card. Without it the values read as words
76
+ * (Decided 16 Oct: any reader may change a file from its card; words only in
77
+ * a preview and for a file that cannot be read). An archived file's read as
78
+ * words whatever is passed: its page is read-only.
79
+ */
80
+ onAct?: (actionId: string, value: string) => void
81
+ /** What was said about it, when the app has read that. */
82
+ conversation?: LinkedConversation
83
+ }
84
+
85
+ /** How many of a file's items its card lists: the most recently changed (Miky, 21 Oct). */
86
+ const CARD_ROWS = 7
87
+
88
+ const KIND_PAGE = 30842
89
+ const KIND_CHANNEL = 39000
90
+
91
+ const COLOURS: readonly StatusColour[] = ['neutral', 'blue', 'green', 'muted']
92
+
93
+ function colourOf(colour: string | undefined): StatusColour | undefined {
94
+ return COLOURS.find((known) => known === colour)
95
+ }
96
+
97
+ /** The icon a file draws by its event kind; a document draws a page. */
98
+ function linkedKindOfKind(kind: number): LinkedKind {
99
+ return kind === KIND_PAGE ? 'page' : thingKindOf(kind)
100
+ }
101
+
102
+ /** The manifest's `message` widget, wherever it sits in the fallback chain (§13.3). */
103
+ function isMessage(object: LinkedSource): boolean {
104
+ return (Array.isArray(object.widget) ? object.widget : [object.widget]).includes('message')
105
+ }
106
+
107
+ /** What a file is called, by its noun or its app: "Topic", "Estiva Ship". */
108
+ function nounOf(object: { noun?: string; appName?: string }): string | undefined {
109
+ if (object.noun) return object.noun.charAt(0).toUpperCase() + object.noun.slice(1)
110
+ return object.appName
111
+ }
112
+
113
+ function titleOf(object: LinkedSource): string {
114
+ const title = object.slots.title
115
+ if (title?.isPubkey) return object.people?.[title.value]?.displayName ?? '—'
116
+ return title?.value || nounOf(object) || 'Untitled'
117
+ }
118
+
119
+ function idOf(object: LinkedSource): string {
120
+ return object.address ?? object.eventId ?? object.ref
121
+ }
122
+
123
+ /** What the reader calls it, quietly before the title: an issue's ref ("WBD-5"), a project's key ("WBD"). */
124
+ function keyOf(object: LinkedSource): string | undefined {
125
+ return object.meta.find((slot) => (slot.field === 'ref' || slot.field === 'key') && !slot.isPubkey && slot.value)?.value
126
+ }
127
+
128
+ /** The person a file names in its owner's place (its assignee, its lead). */
129
+ function ownerSlotOf(object: LinkedSource): LinkedSlot | undefined {
130
+ return object.meta.find((slot) => slot.isPubkey && slot.value && slot.field !== object.slots.title?.field)
131
+ }
132
+
133
+ /**
134
+ * The items its card lists. A project's are its 7 most recently changed
135
+ * issues, newest first and the same 7 in every app (a tie goes to the
136
+ * address); a Folder's are its files in the Folder's own order (Miky, 16 Oct,
137
+ * ship#310). Interop has already left out what is archived.
138
+ */
139
+ function listedOf(object: LinkedSource): LinkedSource[] {
140
+ const children = object.children ?? []
141
+ if (object.kind === KIND_CHANNEL) return children
142
+ // An interop before 0.64 says nothing of when an item changed: its own order, rather than the addresses'.
143
+ if (children.some((child) => child.changedAt === undefined)) return children.slice(0, CARD_ROWS)
144
+ return [...children]
145
+ .sort((a, b) => (b.changedAt ?? 0) - (a.changedAt ?? 0) || (idOf(a) < idOf(b) ? -1 : idOf(a) > idOf(b) ? 1 : 0))
146
+ .slice(0, CARD_ROWS)
147
+ }
148
+
149
+ function childrenOf<T extends LinkedSource>(object: T, options: LinkedFromOptions<T>): LinkedChild[] | undefined {
150
+ // An object's children are objects of its own type: interop's are `ForeignObject`s.
151
+ const listed = listedOf(object) as T[]
152
+ if (!listed.length) return undefined
153
+ return listed.map((child) => {
154
+ const status = child.slots.status
155
+ const owner = ownerSlotOf(child)
156
+ const person = owner ? child.people?.[owner.value] : undefined
157
+ const key = keyOf(child)
158
+ return {
159
+ id: idOf(child),
160
+ title: titleOf(child),
161
+ href: options.hrefOf(child, false),
162
+ ...(key ? { key } : {}),
163
+ status: { label: status?.value ?? nounOf(child) ?? 'File', colour: colourOf(status?.colour) ?? 'muted' },
164
+ ...(person?.displayName ? { owner: { name: person.displayName, ...(person.picture ? { picture: person.picture } : {}) } } : {}),
165
+ }
166
+ })
167
+ }
168
+
169
+ /**
170
+ * How far along it is, when every item has a status: the green ones over all
171
+ * of them, listed or not. A cancelled issue is muted, so it counts in the total
172
+ * and not as done (Miky, 21 Oct).
173
+ */
174
+ function doneOf(object: LinkedSource): { done: number; total: number } | undefined {
175
+ const children = object.children
176
+ if (!children?.length || children.some((child) => !child.slots.status)) return undefined
177
+ return { done: children.filter((child) => child.slots.status?.colour === 'green').length, total: children.length }
178
+ }
179
+
180
+ function statusOf(object: LinkedSource, onAct: LinkedFromOptions['onAct']): LinkedPicker | undefined {
181
+ const { slots } = object
182
+ const action = object.actions.find((one) => one.control === 'select' && one.field && one.field === slots.status?.field)
183
+ if (action) {
184
+ return {
185
+ value: action.current,
186
+ options: (action.options ?? []).map((option) => ({ value: option.value, label: option.label, colour: colourOf(option.colour) })),
187
+ ...(onAct ? { onChange: (value: string) => onAct(action.id, value) } : {}),
188
+ }
189
+ }
190
+ if (!slots.status) return undefined
191
+ return { value: slots.status.value, options: [{ value: slots.status.value, label: slots.status.value, colour: colourOf(slots.status.colour) }] }
192
+ }
193
+
194
+ function ownerOf(object: LinkedSource, options: Pick<LinkedFromOptions, 'directory'>, onAct: LinkedFromOptions['onAct']): { owner: LinkedPicker; ownerLabel?: string } | undefined {
195
+ const { slots, people } = object
196
+ // Who owns it: the manifest's person control that is neither the title nor the move (FOL-4).
197
+ const action = object.actions.find(
198
+ (one) => one.control === 'pubkey' && one.field && one.field !== slots.title?.field && one.field !== object.parentField,
199
+ )
200
+ if (action) {
201
+ const known = { ...options.directory }
202
+ // The holder stays pickable while the directory loads, or once they have left it: the object names them.
203
+ if (action.current && !known[action.current]) known[action.current] = people?.[action.current] ?? {}
204
+ return {
205
+ owner: {
206
+ value: action.current || undefined,
207
+ options: [
208
+ { value: '', label: 'Unassigned' },
209
+ ...Object.entries(known)
210
+ // The em dash for an unnameable person, never the key (FEE-1).
211
+ .map(([pubkey, profile]) => ({ value: pubkey, label: profile.displayName ?? '—', picture: profile.picture }))
212
+ .sort((a, b) => a.label.localeCompare(b.label)),
213
+ ],
214
+ ...(onAct ? { onChange: (value: string) => onAct(action.id, value) } : {}),
215
+ },
216
+ ownerLabel: object.meta.find((slot) => slot.field === action.field)?.label ?? action.label,
217
+ }
218
+ }
219
+ // No owner the reader's app may change: the one the file names, as words.
220
+ const slot = ownerSlotOf(object)
221
+ if (!slot) return undefined
222
+ const person = people?.[slot.value]
223
+ return {
224
+ owner: { value: slot.value, options: [{ value: slot.value, label: person?.displayName ?? '—', ...(person?.picture ? { picture: person.picture } : {}) }] },
225
+ ...(slot.label ? { ownerLabel: slot.label } : {}),
226
+ }
227
+ }
228
+
229
+ /** The file a reference names, as the kit's chip, row and card draw it. */
230
+ export function linkedFrom<T extends LinkedSource>(object: T, options: LinkedFromOptions<T>): Linked {
231
+ const { slots, people } = object
232
+ const id = idOf(object)
233
+ const href = options.hrefOf(object, true)
234
+ if (isMessage(object) && slots.title?.isPubkey) {
235
+ // A message is titled by its author (RIC-11): drawn with their face, then its opening words.
236
+ const person = people?.[slots.title.value]
237
+ const name = person?.displayName ?? '—'
238
+ const body = slots.body?.value ? options.previewText(slots.body.value, people) : ''
239
+ return { id, kind: 'message', title: name, href, author: { name, ...(person?.picture ? { picture: person.picture } : {}) }, ...(body ? { body } : {}) }
240
+ }
241
+ const onAct = object.archived ? undefined : options.onAct
242
+ const key = keyOf(object)
243
+ const status = statusOf(object, onAct)
244
+ const owner = ownerOf(object, options, onAct)
245
+ const children = childrenOf(object, options)
246
+ const done = doneOf(object)
247
+ return {
248
+ id,
249
+ kind: linkedKindOfKind(object.kind),
250
+ title: titleOf(object),
251
+ href,
252
+ ...(key ? { key } : {}),
253
+ // Interop reads every file kind's summary into its subtitle (SPEC §6.12).
254
+ ...(slots.subtitle?.value ? { summary: slots.subtitle.value } : {}),
255
+ ...(status ? { status } : {}),
256
+ ...(owner ?? {}),
257
+ ...(options.conversation ? { conversation: options.conversation } : {}),
258
+ ...(children ? { children } : {}),
259
+ ...(done ? { done } : {}),
260
+ }
261
+ }
262
+
263
+ /**
264
+ * Where a reference's read stands, for the kit: `undefined` is still read,
265
+ * `null` an answer of nothing. `unread` is what the app knows from the address
266
+ * alone, for those two. Nothing, and a file the reader may not read, draw
267
+ * alike: "not available." (Miky, 15 Oct).
268
+ */
269
+ export function linkStateFrom<T extends LinkedSource>(
270
+ object: T | null | undefined,
271
+ unread: { kind: LinkedKind; noun: string },
272
+ options: LinkedFromOptions<T>,
273
+ ): LinkState {
274
+ if (object === undefined) return { state: 'loading', kind: unread.kind }
275
+ if (object === null) return { state: 'unavailable', kind: unread.kind, noun: unread.noun }
276
+ if (object.unreachable) {
277
+ const href = object.openUrl && /^https:\/\//i.test(object.openUrl) ? object.openUrl : undefined
278
+ return {
279
+ state: 'unavailable',
280
+ kind: linkedKindOfKind(object.kind),
281
+ noun: (object.noun && nounOf(object)) || unread.noun,
282
+ ...(href ? { openIn: { app: object.appName ?? 'its app', href } } : {}),
283
+ }
284
+ }
285
+ return { state: 'ready', linked: linkedFrom(object, options) }
286
+ }
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
48
48
  expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
49
49
  })
50
50
 
51
- it('counts 206 names over 96 files: 139 components, 64 helpers and 3 hooks (ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; 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)', () => {
51
+ it('counts 209 names over 97 files: 139 components, 67 helpers and 3 hooks (keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; 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)', () => {
52
52
  // The reconciliation GATES.md §24 explains. If this changes, that changes.
53
53
  // The `EDITOR_EXTENSIONS` count as components by their names; they are
54
54
  // editor extensions, documented on SelectionToolbar's, BlockNodes' and
55
55
  // ComposerTriggers' pages.
56
56
  const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
57
- expect(kinds).toEqual({ component: 139, helper: 64, hook: 3 })
58
- expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(96)
57
+ expect(kinds).toEqual({ component: 139, helper: 67, hook: 3 })
58
+ expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(97)
59
59
  })
60
60
 
61
61
  it('gives every entry a purpose, from its own page or from the comment above it', () => {
62
62
  expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
63
63
  expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(90)
64
- expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(116)
64
+ expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(119)
65
65
  })
66
66
 
67
67
  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', () => {
262
262
 
263
263
  it('gives every component a page and a story, and only a helper none', () => {
264
264
  const without = registry.entries.filter((one) => one.docsId === null || one.storyId === null)
265
- // 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).
266
- expect(without.map((one) => one.name).sort()).toEqual(['chosenOf', 'cn', 'isApplePlatform', 'isSuggestionActive', 'isSuggestionOpen', 'loadingShapeOf', 'shortcutLabel', 'suggestionPopup', 'unavailableMemory'])
265
+ // 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; linkedFrom's on LinkCard's).
266
+ expect(without.map((one) => one.name).sort()).toEqual(['chosenOf', 'cn', 'isApplePlatform', 'isSuggestionActive', 'isSuggestionOpen', 'linkStateFrom', 'linkedFrom', 'loadingShapeOf', 'shortcutLabel', 'suggestionPopup', 'unavailableMemory'])
267
267
  expect(without.every((one) => one.kind !== 'component')).toBe(true)
268
268
  })
269
269