@estiva-app/protocol 0.40.0 → 0.41.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/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
  /**
@@ -352,8 +354,7 @@ export function renderTreeText(blocks: readonly RenderBlock[]): string {
352
354
  * @deprecated A whole paragraph is not the unit: since 0.38.0 a message's line
353
355
  * that is only a reference draws its row (§13.2, §13.6.2), which
354
356
  * `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.
357
+ * block document draws by the same line rule (§13.3): `documentLineDrawOf`.
357
358
  */
358
359
  export function standaloneReference(block: RenderBlock): string | undefined {
359
360
  if (block.type !== 'paragraph' || block.children?.length) return undefined
@@ -370,6 +371,9 @@ export function standaloneReference(block: RenderBlock): string | undefined {
370
371
  * no card. A string this reader does not know is `compact` — the writer asked
371
372
  * for a card, and the smallest is the safe reading, as for a message's `embed`
372
373
  * tag (§13.6.2). `none`, a non-string and absence are all no card.
374
+ *
375
+ * In a block document only `detailed` draws a card, in its lone link's row's
376
+ * place; everything else draws the row (§13.3, `documentLineDrawOf`).
373
377
  */
374
378
  export function cardLayout(raw: unknown): 'compact' | 'detailed' | undefined {
375
379
  // An empty string names no layout: no card, as an editor saves it.
@@ -400,6 +404,11 @@ export interface BlockCard {
400
404
  *
401
405
  * Inside a card's body or a part a reader asks nothing: there every reference
402
406
  * is its chip (§13.3), or two objects that card each other nest forever.
407
+ *
408
+ * @deprecated Since 0.41.0 a document's card is drawn in its lone link's row's
409
+ * place, never after the block, and only for `detailed` (§13.3, C22): a link
410
+ * in a sentence draws its chip, and a link on words draws its words. Draw each
411
+ * line by {@link documentLineDrawOf}. Kept until Ship's and Peek's readers move.
403
412
  */
404
413
  export function blockCards(block: RenderBlock, resolveLink?: LinkResolver): BlockCard[] {
405
414
  const out: BlockCard[] = []