@estiva-app/protocol 0.40.0 → 0.42.0

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.
package/src/editor.ts CHANGED
@@ -8,7 +8,7 @@ import {
8
8
  type BlockDocument,
9
9
  } from './blocks.js'
10
10
  import { markerTextToBlockDocument } from './bridge-content.js'
11
- import { targetMark, type InlineMarkNode, type InlineTextNode } from './content.js'
11
+ import { isAllowedHref, targetMark, type InlineMarkNode, type InlineTextNode } from './content.js'
12
12
  import { BLOCK_DOCUMENT_FORMAT, type ContentFormat } from './render.js'
13
13
 
14
14
  /**
@@ -173,7 +173,20 @@ function cardAndExtra(embed: unknown, rest: Record<string, unknown>): { card: {
173
173
  return { card: {}, extra: embed === undefined ? rest : { ...rest, embed } }
174
174
  }
175
175
 
176
- function inlineToEditor(runs: readonly InlineTextNode[]): EditorNode[] {
176
+ /** How a document opens in an editor ({@link toEditorDocument}). */
177
+ export interface EditorOptions {
178
+ /**
179
+ * Keep a link on words as a `link` mark on its words (§13.3, C23): its
180
+ * `href`, and every other key it carries in `extra`, which a save writes
181
+ * back. For an editor whose schema has a `link` mark with `href` and `extra`
182
+ * attributes. Off, the words stay and the link does not: TipTap loads a
183
+ * document holding a mark its schema lacks as empty, and a save would
184
+ * then wipe it.
185
+ */
186
+ links?: boolean
187
+ }
188
+
189
+ function inlineToEditor(runs: readonly InlineTextNode[], options: EditorOptions): EditorNode[] {
177
190
  return runs.flatMap((run) => {
178
191
  const marks = run.marks ?? []
179
192
  // The marks a run keeps as marks; `reference` and `link` become the chip, or nothing when malformed.
@@ -227,12 +240,21 @@ function inlineToEditor(runs: readonly InlineTextNode[]): EditorNode[] {
227
240
  },
228
241
  ]
229
242
  }
230
- // A link on other words is not one these editors write or draw: its words stay, the link does not.
243
+ if (link && options.links) {
244
+ // A link on words: its words, linked, in the order the run's marks came.
245
+ const { href, ...extra } = link
246
+ const first = marks.findIndex((m) => m.type === 'link')
247
+ const linked = marks.flatMap((m, i): NonNullable<EditorNode['marks']> =>
248
+ i === first ? [{ type: 'link', attrs: { href, ...(Object.keys(extra).length ? { extra } : {}) } }] : m.type === 'link' ? [] : [{ type: m.type }],
249
+ )
250
+ return textNodes(run.text, linked)
251
+ }
252
+ // Without `links`, a link on other words is not one the editor can hold: its words stay, the link does not.
231
253
  return textNodes(run.text, carried.map((type) => ({ type })))
232
254
  })
233
255
  }
234
256
 
235
- function blockToEditor(block: Block): EditorNode {
257
+ function blockToEditor(block: Block, options: EditorOptions): EditorNode {
236
258
  if (!EDITOR_BLOCK_TYPES.has(block.type)) {
237
259
  // `text` is §13.3's inline text, worked out here so the node view that
238
260
  // shows it needs nothing from this package.
@@ -253,7 +275,7 @@ function blockToEditor(block: Block): EditorNode {
253
275
  the quote's text was read as no text at all — typed into a description or
254
276
  a message, a quote saved empty (found 30 September).
255
277
  */
256
- const inline = isInlineRun(block.content) ? inlineToEditor(block.content) : []
278
+ const inline = isInlineRun(block.content) ? inlineToEditor(block.content, options) : []
257
279
  return { type: 'blockquote', attrs, content: [{ type: 'paragraph', content: inline }] }
258
280
  }
259
281
 
@@ -270,16 +292,16 @@ function blockToEditor(block: Block): EditorNode {
270
292
  save hands it back unchanged rather than erasing what another app wrote.
271
293
  */
272
294
  const { indent: _depth, ...itemAttrs } = attrs
273
- const inline = isInlineRun(block.content) ? inlineToEditor(block.content) : []
295
+ const inline = isInlineRun(block.content) ? inlineToEditor(block.content, options) : []
274
296
  return { type: 'listItem', attrs: itemAttrs, content: [{ type: 'paragraph', content: inline }] }
275
297
  }
276
298
 
277
- if (LISTS.has(block.type)) return listToEditor(block, attrs)
299
+ if (LISTS.has(block.type)) return listToEditor(block, attrs, options)
278
300
 
279
301
  if (block.content === undefined) return { type: block.type, attrs }
280
302
  const content = isInlineRun(block.content)
281
- ? inlineToEditor(block.content)
282
- : (block.content as Block[]).map(blockToEditor)
303
+ ? inlineToEditor(block.content, options)
304
+ : (block.content as Block[]).map((child) => blockToEditor(child, options))
283
305
  return { type: block.type, attrs, ...(content.length ? { content } : {}) }
284
306
  }
285
307
 
@@ -292,7 +314,7 @@ function blockToEditor(block: Block): EditorNode {
292
314
  * editor's alone: they have no id because the wire has no such block, and
293
315
  * each takes the type of the list it sits in (Miky, 2026-10-12).
294
316
  */
295
- function listToEditor(block: Block, attrs: Record<string, unknown>): EditorNode {
317
+ function listToEditor(block: Block, attrs: Record<string, unknown>, options: EditorOptions): EditorNode {
296
318
  const items = Array.isArray(block.content) && !isInlineRun(block.content) ? (block.content as Block[]) : []
297
319
  const depths = listItemDepths(items)
298
320
  const root: EditorNode = { type: block.type, attrs, content: [] }
@@ -316,7 +338,7 @@ function listToEditor(block: Block, attrs: Record<string, unknown>): EditorNode
316
338
  depth -= 1
317
339
  }
318
340
  }
319
- open[depth].content!.push(blockToEditor(item))
341
+ open[depth].content!.push(blockToEditor(item, options))
320
342
  })
321
343
  if (root.content!.length === 0) delete root.content
322
344
  return root
@@ -343,8 +365,8 @@ export function documentForEditing(value: string, format: ContentFormat): BlockD
343
365
  }
344
366
  }
345
367
 
346
- export function toEditorDocument(document: BlockDocument): EditorDocument {
347
- return { type: 'doc', content: document.content.map(blockToEditor) }
368
+ export function toEditorDocument(document: BlockDocument, options: EditorOptions = {}): EditorDocument {
369
+ return { type: 'doc', content: document.content.map((block) => blockToEditor(block, options)) }
348
370
  }
349
371
 
350
372
  // ── Editor → document ────────────────────────────────────────────────────────
@@ -473,7 +495,15 @@ function inlineFromEditor(nodes: readonly EditorNode[]): InlineTextNode[] {
473
495
  continue
474
496
  }
475
497
  if (node.type !== 'text' || node.text === undefined) continue
476
- const marks = (node.marks ?? []).map((m) => ({ type: m.type }) as InlineMarkNode)
498
+ const marks = (node.marks ?? []).flatMap((m): InlineMarkNode[] => {
499
+ if (m.type !== 'link') return [{ type: m.type } as InlineMarkNode]
500
+ // A link on words (`EditorOptions.links`): `href` first, as writers put it, then what it carried. One with no `href` is no link.
501
+ const href = m.attrs?.href
502
+ if (typeof href !== 'string' || !isAllowedHref(href)) return []
503
+ const extra = m.attrs?.extra
504
+ const { href: _ignored, ...kept } = extra && typeof extra === 'object' && !Array.isArray(extra) ? (extra as Record<string, unknown>) : {}
505
+ return [{ type: 'link', attrs: { href, ...kept } }]
506
+ })
477
507
  const last = out[out.length - 1]
478
508
  /*
479
509
  Merge runs that carry the same marks. ProseMirror splits a text node
package/src/embeds.ts CHANGED
@@ -116,6 +116,11 @@ function normalise(value: string): string | undefined {
116
116
  * holds that `d` — or undefined. Never a match on the link's trailing
117
117
  * identifier alone: that resolves any site's URL as somebody's object, and puts
118
118
  * a real issue's card under a link that does not open it (§7.7).
119
+ *
120
+ * A link to one block (`#block-<id>`, §13.6.1) resolves to the object the block
121
+ * is in: it reads as that file's chip, and its `part`, when the message carries
122
+ * one, draws the block and keeps the file's card off ({@link cardsIn},
123
+ * {@link defaultCardOf}, {@link lineDrawOf}).
119
124
  */
120
125
  export type LinkResolver = (url: string) => string | undefined
121
126
 
@@ -272,7 +277,9 @@ const PERSON = /^nostr:(npub1|nprofile1)/i
272
277
  *
273
278
  * Whitespace around it is trimmed. Anything else makes it a sentence: other
274
279
  * words or punctuation (trailing `.` included), a second reference, a marker
275
- * around it, a code span, or `[words](url)`. A person (`npub`, `nprofile`)
280
+ * around it, a code span, or a link on words (`[words](url)`, or a block
281
+ * document's `link` mark whose text is not its `href`). A `link` mark whose
282
+ * text is exactly its `href` is the bare URL (§13.3). A person (`npub`, `nprofile`)
276
283
  * alone on a line stays a chip, so it is not returned. A Folder stays a chip
277
284
  * too, but whether a URL names one is known only once it resolves: the reader
278
285
  * checks the value ({@link isFolderValue}). A URL returned here still has to
@@ -282,9 +289,11 @@ const PERSON = /^nostr:(npub1|nprofile1)/i
282
289
  export function isOnlyReferenceLine(line: readonly RenderInline[], block: Pick<RenderBlock, 'type'>): string | undefined {
283
290
  if (block.type !== 'paragraph' && block.type !== 'listItem') return undefined
284
291
  const runs = line.filter((run) => run.reference || run.text.trim() !== '')
285
- if (runs.length !== 1 || runs[0].marks.length > 0 || runs[0].href !== undefined) return undefined
292
+ if (runs.length !== 1 || runs[0].marks.length > 0) return undefined
286
293
  const [run] = runs
287
294
  if (run.reference) return PERSON.test(run.reference) ? undefined : run.reference
295
+ // A link mark bounds its URL, so nothing around it is trimmed off as punctuation.
296
+ if (run.href !== undefined) return run.text === run.href && LONE_URL.test(run.href) ? run.href : undefined
288
297
  const text = run.text.trim()
289
298
  return LONE_URL.test(text) && trimUrl(text) === text ? text : undefined
290
299
  }
@@ -338,6 +347,74 @@ export function lineDrawOf(
338
347
  return { draw: carded ? 'nothing' : 'row', value, ...(isReference ? {} : { url: only }) }
339
348
  }
340
349
 
350
+ /**
351
+ * What one line of a block document draws (§13.3, "A reference's card"): a
352
+ * message's {@link LineDraw} but `nothing` (a document has no card under it), or
353
+ * - `card` — the line is only a link to the file `value`, and its writer chose
354
+ * its card (`embed` `detailed` on the link's mark): the card, in the row's place.
355
+ */
356
+ export type DocumentLineDraw = Exclude<LineDraw, { draw: 'nothing' }> | { draw: 'card'; value: string; url?: string }
357
+
358
+ /**
359
+ * How a reader draws one line ({@link linesOf}) of a block document's `block`.
360
+ * The line rule is the message's ({@link lineDrawOf}), with no card under the
361
+ * document, so `nothing` never comes back. Only a paragraph's and a list item's
362
+ * lines can be a link alone, a checklist item's included (a list item on the
363
+ * wire); a heading, a quote, a callout (a quote with a tone) and a paragraph in
364
+ * a table cell are sentences. Where `block` sits is the caller's to say
365
+ * (`inTableCell`), because the tree holds a cell as a block this package does
366
+ * not name: {@link documentLineDraws} walks a whole document and says it.
367
+ *
368
+ * Anything else on the mark — no `embed`, `compact`, `none`, a value this
369
+ * reader does not know or one that is not a string — draws the row, and in a
370
+ * sentence every value draws the chip only. A link on
371
+ * words (a `link` mark whose text is not its `href`) is a sentence: its words,
372
+ * a link, and its `embed` draws nothing. Read the tree through
373
+ * {@link linksAsReferences} first, or pass `resolveLink`, so an app URL draws
374
+ * as what it names.
375
+ *
376
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-link-on-words-counts-toward-the-card.md
377
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-lone-links-chip-menu-offers-row-or-card.md
378
+ */
379
+ export function documentLineDrawOf(
380
+ line: readonly RenderInline[],
381
+ block: Pick<RenderBlock, 'type'> & { inTableCell?: boolean },
382
+ context: { resolveLink?: LinkResolver } = {},
383
+ ): DocumentLineDraw {
384
+ if (block.inTableCell) return { draw: 'sentence' }
385
+ const drawn = lineDrawOf(line, block, { resolveLink: context.resolveLink })
386
+ if (drawn.draw !== 'row' && drawn.draw !== 'nothing') return drawn
387
+ // The line is one run: the link, its `embed` read off its mark by `cardLayout`.
388
+ const only = line.find((run) => run.reference || run.text.trim() !== '')
389
+ return { ...drawn, draw: only?.embed === 'detailed' ? 'card' : 'row' }
390
+ }
391
+
392
+ /**
393
+ * Every line of a block document as a reader draws it ({@link documentLineDrawOf}),
394
+ * per block of `blocks`, keyed by the block object itself — pass the tree you
395
+ * draw, after {@link linksAsReferences} if you use it.
396
+ *
397
+ * Only a top-level paragraph and a list's items keep the line rule. Inside
398
+ * anything else — a table's cells, a quote or a block this reader does not
399
+ * know that holds blocks — every line is a sentence, so no reader has to
400
+ * remember where it is.
401
+ */
402
+ export function documentLineDraws(
403
+ blocks: readonly RenderBlock[],
404
+ context: { resolveLink?: LinkResolver } = {},
405
+ ): Map<RenderBlock, DocumentLineDraw[]> {
406
+ const out = new Map<RenderBlock, DocumentLineDraw[]>()
407
+ // `inside`: under a block that is not a list, where every line is a sentence.
408
+ const walk = (bs: readonly RenderBlock[], inside: boolean) => {
409
+ for (const block of bs) {
410
+ if (block.inline) out.set(block, linesOf(block).map((line) => documentLineDrawOf(line, { type: block.type, inTableCell: inside }, context)))
411
+ if (block.children) walk(block.children, inside || (block.type !== 'bulletList' && block.type !== 'orderedList'))
412
+ }
413
+ }
414
+ walk(blocks, false)
415
+ return out
416
+ }
417
+
341
418
  /**
342
419
  * The value a writer gives the default card, `["embed", V, "detailed"]`, as
343
420
  * it sends or edits a message (§13.6.2), or undefined.
package/src/index.ts CHANGED
@@ -47,7 +47,7 @@
47
47
  /** Bumped by hand with the version in package.json — `test/version.test.ts`
48
48
  * pins the two together. It exists so "the upgrade reached the app" can be
49
49
  * checked by grepping a built bundle rather than by trusting a lockfile. */
50
- export const PROTOCOL_VERSION = '0.40.0'
50
+ export const PROTOCOL_VERSION = '0.42.0'
51
51
 
52
52
  export {
53
53
  // types
@@ -285,6 +285,7 @@ export {
285
285
  selectionAnchorTags,
286
286
  } from './comment-anchor.js'
287
287
  export {
288
+ type DocumentLineDraw,
288
289
  type Embed,
289
290
  type EmbedLayout,
290
291
  type LineDraw,
@@ -292,6 +293,8 @@ export {
292
293
  EMBED_TAG,
293
294
  cardsIn,
294
295
  defaultCardOf,
296
+ documentLineDrawOf,
297
+ documentLineDraws,
295
298
  embedTag,
296
299
  embedTagsOf,
297
300
  embedsOf,
package/src/render.ts CHANGED
@@ -55,8 +55,10 @@ export interface RenderInline {
55
55
  reference?: string
56
56
  /**
57
57
  * The card its writer chose for this reference in a block document (§13.3,
58
- * "A reference's card"): absent for none. A message's cards are its `embed`
59
- * tags instead (§13.6.2), so a marker body never has one.
58
+ * "A reference's card"), as `cardLayout` reads it: absent for none. Only
59
+ * `detailed` draws one, and only alone on its line (`documentLineDrawOf`). A
60
+ * message's cards are its `embed` tags instead (§13.6.2), so a marker body
61
+ * never has one.
60
62
  */
61
63
  embed?: 'compact' | 'detailed'
62
64
  /**
@@ -193,20 +195,21 @@ const inlineFromMarkers = (text: string): RenderInline[] =>
193
195
  /** One inline run per line, joined by the `\n` the interface documents. */
194
196
  const inlineFromLines = (lines: string[]): RenderInline[] => inlineFromMarkers(lines.join('\n'))
195
197
 
198
+ /** A list's items, flat, each indented item carrying its depth as a block document's does. */
199
+ const itemsFromSegment = (items: string[], depths?: number[]): RenderBlock[] =>
200
+ items.map((item, i) => ({ type: 'listItem' as const, inline: inlineFromMarkers(item), ...(depths?.[i] ? { indent: depths[i] } : {}) }))
201
+
196
202
  function blockFromSegment(seg: BodySegment): RenderBlock {
197
203
  switch (seg.type) {
198
204
  case 'heading':
199
205
  return { type: 'heading', level: seg.level, inline: inlineFromMarkers(seg.text) }
200
206
  case 'bullet':
201
- return {
202
- type: 'bulletList',
203
- children: seg.items.map((item) => ({ type: 'listItem' as const, inline: inlineFromMarkers(item) })),
204
- }
207
+ return { type: 'bulletList', children: itemsFromSegment(seg.items, seg.depths) }
205
208
  case 'numbered':
206
209
  return {
207
210
  type: 'orderedList',
208
211
  ...(seg.start ? { start: seg.start } : {}),
209
- children: seg.items.map((item) => ({ type: 'listItem' as const, inline: inlineFromMarkers(item) })),
212
+ children: itemsFromSegment(seg.items, seg.depths),
210
213
  }
211
214
  case 'quote':
212
215
  return { type: 'blockquote', inline: inlineFromLines(seg.lines) }
@@ -311,7 +314,8 @@ export function toRenderTree(value: string, format: RenderFormat): RenderBlock[]
311
314
  }
312
315
  return doc.content.map(blockFromDocument)
313
316
  }
314
- return parseBodySegments(value).map(blockFromSegment)
317
+ // An indented item nests in a message (§13.2, Miky 2026-10-20).
318
+ return parseBodySegments(value, { indentedItems: true }).map(blockFromSegment)
315
319
  }
316
320
 
317
321
  function plainParagraph(value: string): RenderBlock[] {
@@ -352,8 +356,7 @@ export function renderTreeText(blocks: readonly RenderBlock[]): string {
352
356
  * @deprecated A whole paragraph is not the unit: since 0.38.0 a message's line
353
357
  * that is only a reference draws its row (§13.2, §13.6.2), which
354
358
  * `isOnlyReferenceLine` decides per line, list items and app URLs included. A
355
- * block document reads a reference as its chip (§13.3); use {@link blockCards}
356
- * for its cards.
359
+ * block document draws by the same line rule (§13.3): `documentLineDrawOf`.
357
360
  */
358
361
  export function standaloneReference(block: RenderBlock): string | undefined {
359
362
  if (block.type !== 'paragraph' || block.children?.length) return undefined
@@ -370,6 +373,9 @@ export function standaloneReference(block: RenderBlock): string | undefined {
370
373
  * no card. A string this reader does not know is `compact` — the writer asked
371
374
  * for a card, and the smallest is the safe reading, as for a message's `embed`
372
375
  * tag (§13.6.2). `none`, a non-string and absence are all no card.
376
+ *
377
+ * In a block document only `detailed` draws a card, in its lone link's row's
378
+ * place; everything else draws the row (§13.3, `documentLineDrawOf`).
373
379
  */
374
380
  export function cardLayout(raw: unknown): 'compact' | 'detailed' | undefined {
375
381
  // An empty string names no layout: no card, as an editor saves it.
@@ -400,6 +406,11 @@ export interface BlockCard {
400
406
  *
401
407
  * Inside a card's body or a part a reader asks nothing: there every reference
402
408
  * is its chip (§13.3), or two objects that card each other nest forever.
409
+ *
410
+ * @deprecated Since 0.41.0 a document's card is drawn in its lone link's row's
411
+ * place, never after the block, and only for `detailed` (§13.3, C22): a link
412
+ * in a sentence draws its chip, and a link on words draws its words. Draw each
413
+ * line by {@link documentLineDrawOf}. Kept until Ship's and Peek's readers move.
403
414
  */
404
415
  export function blockCards(block: RenderBlock, resolveLink?: LinkResolver): BlockCard[] {
405
416
  const out: BlockCard[] = []