From 0507a49579b19dc18f8c6f32b4369463941e2470 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 14 Nov 2026 21:30:11 +0100 Subject: [PATCH] Write tables, images, cards, extensions and expand titles in adfToPlainText --- CHANGELOG.md | 6 +- README.md | 2 +- docs/decisions.md | 20 +++- docs/reading-cost.md | 17 ++++ src/plain-text/adf-to-plain-text.test.ts | 116 ++++++++++++++++++++++- src/plain-text/adf-to-plain-text.ts | 79 ++++++++++++--- todo.md | 21 ---- 7 files changed, 220 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f6cefd2..4f880eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,8 +5,10 @@ - `adfToPlainText` writes a document as text with no markup, for a search index, a notification or an email: blocks a blank line apart; `• ` and `1.` list markers, `☑ ` and `☐ ` for a done and an open task, nesting indented; a link's address and title in parentheses after its text; a hard break as a - line feed; and a mention, emoji, date or status as the text it shows. It refuses what `adfToHtml` - refuses. A table is written as its cells, as blocks, for now. + line feed; a mention, emoji, date or status as the text it shows; a table as a line per row, its + cells apart by ` | `; an image as its alt text and address, `[image]` with neither; a card as its + address; an extension's text; and an expand's title above its body. It refuses what `adfToHtml` + refuses. - `readAdfDocument` and the four writers name the node `not-an-adf-document` refuses: `path` leads to a node that is not an ADF node, and the message says what is wrong with it, such as which attribute holds a value that is not JSON. A getter, an object holding itself, a throwing Proxy diff --git a/README.md b/README.md index 9500787..935fd2e 100644 --- a/README.md +++ b/README.md @@ -369,7 +369,7 @@ Each call's name says which format it reads or writes: | --- | --- | --- | | `adfToHtml` | writes HTML: the elements [HTML](#html) lists, and an `adf-carry` element holding everything else | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `adfToLosslessMarkdown` | writes the lossless flavour: CommonMark plus GFM's pipe tables and `~~`, with `!adf:` directives and `adf:` fences for everything else | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | -| `adfToPlainText` | writes text with no markup: blocks a blank line apart; list items under `• ` or `1.`, a task item under `☑ ` or `☐ `, nesting indented; a link's address and title in parentheses after its text; a hard break a line feed; a mention, emoji, date and status as the text they show; a table as its cells written as blocks | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | +| `adfToPlainText` | writes text with no markup: blocks a blank line apart; list items under `• ` or `1.`, a task item under `☑ ` or `☐ `, nesting indented; a link's address and title in parentheses after its text; a hard break a line feed; a mention, emoji, date and status as the text they show; a table as a line per row, cells apart by ` \| `; an image as its alt text, then its address in parentheses; a card as its address; an extension's text; an expand's title above its body | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `adfToPortableMarkdown` | writes markdown GitHub, GitLab and Obsidian render; drops what they cannot show, and writes no directive | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `commonMarkToAdf` | reads strict CommonMark as its spec says: a directive, a pipe table, `~~`, `==` and an `adf:` fence read as text and code | `engine-limit`, `not-a-string`, `unmappable-html`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `htmlToAdf` | reads the HTML `adfToHtml` writes, also as a browser's `innerHTML` or a form post spells it, a carry element from its `data-adf`; refuses any other HTML, an edit to what a carry element shows included | `engine-limit`, `not-a-string`, `unmappable-html`, `unsupported-nesting-depth`, `unsupported-node-shape` | diff --git a/docs/decisions.md b/docs/decisions.md index abbe383..f8ca144 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1316,6 +1316,16 @@ candidates for the links and four for task state. All three picked a link's addr after its text, with the title after the address, and `☑` and `☐` in place of the bullet. All three had expected no title, and goal 7 counts a title as content, so every candidate kept it. +A third panel, of 3 then 7 (export/indexing, support agent and product manager first; then LLM/agent, +engineer, viewer/editor and bot), wrote the text they expected, then picked among shuffled candidates +for a table, an image, a card, an extension and an expand. All three agreed on one line per row with +` | ` between cells, a header row like any other, a merged cell written once with no place for the +cells it covers, a card as its address, an extension as its text, and an expand as its title, a blank +line, then its body. Five of seven picked `[image]` for an image with nothing to show. Three splits +went to the maintainer: a block in a cell (five of seven expected the blocks joined by a space, so +that is the rule), and an image with an address (alt text then ` (address)`, as links do, since +goal 7 counts the address as content; with no alt text the address alone). + `adfToPlainText` writes: - Blocks a blank line apart; an item's blocks and a list's items one line feed apart. @@ -1330,4 +1340,12 @@ had expected no title, and goal 7 counts a title as content, so every candidate the link; nothing after a link whose text is its address and that holds no title. - Any other mark as the text it marks. - A block holding no text as nothing, with no extra blank line. -- A table as its cells written as blocks, until item 180 gives it a spelling. +- A table as a line per row, a line feed apart, its cells apart by ` | ` and an empty cell empty, a + header row like any other; a merged cell once, the cells it covers writing no place; a cell's + blocks, hard breaks and code lines on its line a space apart, a list item behind its marker. +- An image as its alt text, else its address, else `[image]`; then ` (address)` for the link around + it, titled as a link is, then ` (address)` for its own address where the alt text stood in for it. +- A card as its address, or its name then ` (address)`; an extension as its `text`, and as nothing + with none; no other note is written, so a card, an extension or a synced block holding nothing + writes nothing. +- An expand's title on a line, a blank line above its body. diff --git a/docs/reading-cost.md b/docs/reading-cost.md index de15170..916a8db 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -1076,3 +1076,20 @@ Read most (opens and searches): - `docs/score-anchors.md` 1 - `src/adf/inline-nodes.ts` 1 - `src/html/emit/adf-to-html.ts` 1 + +## Reading cost, chunk 1529af18f07f, finished 2026-11-14T20:19:06Z + +535229 new input tokens before the first commit. + +Read most (opens and searches): + +- `README.md` 27 +- `docs/decisions.md` 10 +- `src/html/emit/adf-to-html.test.ts` 6 +- `ci.sh` 5 +- `src/adf/document.ts` 4 +- `todo.md` 4 +- `src/adf/block-nodes.ts` 3 +- `src/html/emit/adf-to-html.ts` 3 +- `src/index.ts` 3 +- `CHANGELOG.md` 2 diff --git a/src/plain-text/adf-to-plain-text.test.ts b/src/plain-text/adf-to-plain-text.test.ts index 05a47c7..2fbb5ff 100644 --- a/src/plain-text/adf-to-plain-text.test.ts +++ b/src/plain-text/adf-to-plain-text.test.ts @@ -229,10 +229,118 @@ test('writes a mention, an emoji, a date and a status as the text they show', () assert.equal(plain(adfToPlainText(document(paragraph(...nodes.flatMap((node) => [node, text(' ')]))))), '@557058:ann 😄 2025-08-25 Done ') }) -test('writes a table\'s cells as blocks, until a table has its own spelling', () => { - const cell = (value: string): AdfNode => ({ content: [line(value)], type: 'tableCell' }) - const table: AdfNode = { content: [{ content: [cell('a'), cell('b')], type: 'tableRow' }, { content: [cell('c'), cell('d')], type: 'tableRow' }], type: 'table' } - assert.equal(plain(adfToPlainText(document(table))), 'a\n\nb\n\nc\n\nd') +function cell(...content: AdfNode[]): AdfNode { + return { content: content.length === 0 ? [paragraph()] : content, type: 'tableCell' } +} + +function row(...cells: AdfNode[]): AdfNode { + return { content: cells, type: 'tableRow' } +} + +function table(...rows: AdfNode[]): AdfNode { + return { content: rows, type: 'table' } +} + +function cells(...values: string[]): AdfNode { + return row(...values.map((value) => cell(line(value)))) +} + +test('writes a table as one line per row, its cells apart by a bar, a header row like any other', () => { + const header = row(...['Name', 'Role'].map((value) => ({ content: [line(value)], type: 'tableHeader' }))) + assert.equal(plain(adfToPlainText(document(table(header, cells('Ada', 'Engineer'), cells('Grace', 'Admiral'))))), 'Name | Role\nAda | Engineer\nGrace | Admiral') +}) + +test('writes a table a blank line from the blocks around it', () => { + assert.equal(plain(adfToPlainText(document(line('Team'), table(cells('a', 'b'), cells('c', 'd')), line('End')))), 'Team\n\na | b\nc | d\n\nEnd') +}) + +test('writes a merged cell once, with no place for the cells it covers', () => { + const wide: AdfNode = { attrs: { colspan: 2 }, content: [line('Wide')], type: 'tableCell' } + const tall: AdfNode = { attrs: { rowspan: 2 }, content: [line('Tall')], type: 'tableCell' } + assert.equal(plain(adfToPlainText(document(table(row(wide, tall), cells('x', 'y'))))), 'Wide | Tall\nx | y') +}) + +test('writes an empty cell as an empty place between the bars, in any column', () => { + assert.equal(plain(adfToPlainText(document(table(row(cell(line('a')), cell(), cell(line('c'))), row(cell(), cell(line('e'))))))), 'a | | c\n | e') +}) + +test('writes the blocks of a cell on its line, a space apart, a list item behind its marker', () => { + const nested = row(cell(line('Line one'), line('Line two')), cell(bullets(item(line('p')), item(line('q'))))) + assert.equal(plain(adfToPlainText(document(table(nested, cells('x', 'y'))))), 'Line one Line two | • p • q\nx | y') +}) + +test('writes a hard break and the lines of a code block in a cell as spaces, so the row stays one line', () => { + const broken = row(cell(paragraph(text('a'), { type: 'hardBreak' }, text('b'))), cell({ content: [text('c\nd\n')], type: 'codeBlock' }), cell(line('e'))) + assert.equal(plain(adfToPlainText(document(table(broken)))), 'a b | c d | e') +}) + +test('writes a table inside a list item under the item\'s indent', () => { + assert.equal(plain(adfToPlainText(document(bullets(item(line('t'), table(cells('a', 'b'), cells('c', 'd'))))))), '• t\n a | b\n c | d') +}) + +const external: AdfNode = { attrs: { alt: 'Team photo', type: 'external', url: 'https://example.com/team.png' }, type: 'media' } +const uploaded: AdfNode = { attrs: { alt: 'Quarterly chart', id: 'f', type: 'file' }, type: 'media' } + +function shown(...nodes: AdfNode[]): string { + return plain(adfToPlainText(document(paragraph(text('Before')), ...nodes, paragraph(text('After'))))) +} + +function withLink(media: AdfNode, href: string): AdfNode { + return { ...media, marks: [{ attrs: { href }, type: 'link' }] } +} + +test('writes an external image as its alt text then its address, the address alone with no alt text', () => { + assert.equal(shown({ content: [external], type: 'mediaSingle' }), 'Before\n\nTeam photo (https://example.com/team.png)\n\nAfter') + assert.equal(shown({ content: [{ attrs: { type: 'external', url: 'https://example.com/team.png' }, type: 'media' }], type: 'mediaSingle' }), 'Before\n\nhttps://example.com/team.png\n\nAfter') +}) + +test('writes an uploaded image as its alt text, or as [image] with none', () => { + assert.equal(shown({ content: [uploaded], type: 'mediaSingle' }), 'Before\n\nQuarterly chart\n\nAfter') + assert.equal(shown({ content: [{ attrs: { id: 'f', type: 'file' }, type: 'media' }], type: 'mediaSingle' }), 'Before\n\n[image]\n\nAfter') + assert.equal(shown({ content: [{ attrs: { alt: ' ', id: 'f', type: 'file' }, type: 'media' }], type: 'mediaSingle' }), 'Before\n\n[image]\n\nAfter') +}) + +test('writes the target of a link around an image, after its alt text and before the image\'s own address', () => { + assert.equal(shown({ content: [withLink(external, 'https://example.com/go')], type: 'mediaSingle' }), 'Before\n\nTeam photo (https://example.com/go) (https://example.com/team.png)\n\nAfter') + assert.equal(shown({ content: [withLink(external, 'https://example.com/team.png')], type: 'mediaSingle' }), 'Before\n\nTeam photo (https://example.com/team.png)\n\nAfter') + assert.equal(shown({ content: [withLink(uploaded, 'https://example.com/go')], type: 'mediaSingle' }), 'Before\n\nQuarterly chart (https://example.com/go)\n\nAfter') + assert.equal(shown({ content: [withLink({ attrs: { id: 'f', type: 'file' }, type: 'media' }, 'https://example.com/go')], type: 'mediaSingle' }), 'Before\n\n[image] (https://example.com/go)\n\nAfter') + assert.equal(shown({ content: [withLink({ attrs: { type: 'external', url: 'https://example.com/team.png' }, type: 'media' }, 'https://example.com/go')], type: 'mediaSingle' }), 'Before\n\nhttps://example.com/team.png (https://example.com/go)\n\nAfter') +}) + +test('writes a link\'s title around an image behind its target', () => { + const titled: AdfNode = { ...uploaded, marks: [{ attrs: { href: 'https://example.com/go', title: 'Go' }, type: 'link' }] } + assert.equal(shown({ content: [titled], type: 'mediaSingle' }), 'Before\n\nQuarterly chart (https://example.com/go, "Go")\n\nAfter') +}) + +test('writes the images of a group and an inline image on the line they stand in', () => { + assert.equal(shown({ content: [external, uploaded], type: 'mediaGroup' }), 'Before\n\nTeam photo (https://example.com/team.png)\n\nQuarterly chart\n\nAfter') + assert.equal(plain(adfToPlainText(document(paragraph(text('See '), { attrs: { alt: 'logo', type: 'file' }, type: 'mediaInline' }, text(' here'))))), 'See logo here') +}) + +test('writes a card as its address, or as its name then its address', () => { + const card = (attrs: Record): AdfNode => ({ attrs, type: 'blockCard' }) + assert.equal(shown(card({ url: 'https://example.com/spec' })), 'Before\n\nhttps://example.com/spec\n\nAfter') + assert.equal(shown(card({ data: { name: 'Design spec' }, url: 'https://example.com/spec' })), 'Before\n\nhttps://example.com/spec\n\nAfter') + assert.equal(shown(card({ data: { name: 'Design spec' } })), 'Before\n\nDesign spec\n\nAfter') + assert.equal(shown(card({ data: { name: 'Design spec', url: 'https://example.com/spec' } })), 'Before\n\nDesign spec (https://example.com/spec)\n\nAfter') + assert.equal(shown(card({ data: { url: 'https://example.com/spec' } })), 'Before\n\nhttps://example.com/spec\n\nAfter') + assert.equal(shown(card({})), 'Before\n\nAfter') + assert.equal(shown({ attrs: { url: 'https://example.com/embed' }, type: 'embedCard' }), 'Before\n\nhttps://example.com/embed\n\nAfter') + assert.equal(plain(adfToPlainText(document(paragraph(text('See '), { attrs: { data: { name: 'Spec', url: 'https://example.com/spec' } }, type: 'inlineCard' }, text('.'))))), 'See Spec (https://example.com/spec).') +}) + +test('writes an extension as the text it carries, and as nothing with none', () => { + assert.equal(shown({ attrs: { extensionKey: 'chart', extensionType: 'com.example', text: 'Roadmap macro output' }, type: 'extension' }), 'Before\n\nRoadmap macro output\n\nAfter') + assert.equal(shown({ attrs: { extensionKey: 'chart', extensionType: 'com.example' }, type: 'extension' }), 'Before\n\nAfter') + assert.equal(plain(adfToPlainText(document(paragraph(text('a '), { attrs: { extensionKey: 'k', extensionType: 't', text: 'x' }, type: 'inlineExtension' }, text(' b'))))), 'a x b') +}) + +test('writes an expand\'s title on a line, a blank line above its body', () => { + assert.equal(shown({ attrs: { title: 'Details' }, content: [line('Hidden body')], type: 'expand' }), 'Before\n\nDetails\n\nHidden body\n\nAfter') + assert.equal(shown({ attrs: { title: 'Details' }, content: [line('Hidden body')], type: 'nestedExpand' }), 'Before\n\nDetails\n\nHidden body\n\nAfter') + assert.equal(shown({ content: [line('Hidden body')], type: 'expand' }), 'Before\n\nHidden body\n\nAfter') + assert.equal(shown({ attrs: { title: 'Details' }, content: [paragraph()], type: 'expand' }), 'Before\n\nDetails\n\nAfter') }) test('writes a node of an unknown type as the text it holds, its children a blank line apart', () => { diff --git a/src/plain-text/adf-to-plain-text.ts b/src/plain-text/adf-to-plain-text.ts index 9bab89e..97f2b3b 100644 --- a/src/plain-text/adf-to-plain-text.ts +++ b/src/plain-text/adf-to-plain-text.ts @@ -6,22 +6,31 @@ import { linkAttrs, type LinkAttrs } from '../adf/mark-attributes.ts' import { largestNesting } from '../nesting.ts' import { longestOutput, tooLong, withinEngineLimits } from '../length-bound.ts' import { nodeAttrs, nodeContent, nodeMarks, readAdfDocument, writableContent } from '../adf/document.ts' -import { shownText } from '../adf/shown-text.ts' +import { shownLink, shownText, shownUrl, visibleText } from '../adf/shown-text.ts' -// `gap`: the line feeds the next text needs before it at least; `leave`: the state to restore after a list item, and its `length` at the start, which shows whether it wrote anything; `marker`: the marker this node has in its list; `suffix`: text written right after this node; `depth`: the nesting level as `largestNesting` counts it; `parent`: the node holding this one, from which a refusal's path is built. +// `gap`: the line feeds the next text needs before it at least; `leave`: the state to restore after a list item, and its `length` at the start, which shows whether it wrote anything; `leaveCell`: the cell, `gap` and `literal` to restore after a table cell; `separator`: the bar between two cells of a row; `marker`: the marker this node has in its list; `suffix`: text written right after this node; `depth`: the nesting level as `largestNesting` counts it; `parent`: the node holding this one, from which a refusal's path is built. type Place = { index: number; parent: Place | undefined } type Step = | { kind: 'gap'; lines: number } + | { kind: 'leaveCell'; cell: Cell | undefined; gap: number; literal: number } | { kind: 'leave'; indent: string; lead: string | undefined; length: number } + | { kind: 'separator' } | { depth: number; kind: 'node'; marker: string | undefined; node: AdfNode; place: Place | undefined; suffix: string | undefined } -// `lines`: the line feeds between a node's children; `level`: how much deeper they nest. -type Layout = { level: number; lines: number } +// A table cell being written: its text goes on the row's line, so `base`, the margin of the row, is not repeated; `start` is the `length` where the cell began. +type Cell = { base: string; start: number } + +// `lines`: the line feeds between a node's children; `level`: how much deeper they nest; `cells`: they are bar-separated cells on one line. +type Layout = { cells?: true; level: number; lines: number } const bulletLists = ['bulletList', 'decisionList', 'taskList'] const itemTypes = ['blockTaskItem', 'listItem'] const markedItems = ['blockTaskItem', 'decisionItem', 'listItem', 'taskItem'] -const shownTextTypes = ['date', 'emoji', 'mention', 'status'] +const cardTypes = ['blockCard', 'embedCard', 'inlineCard'] +const cellTypes = ['tableCell', 'tableHeader'] +const expandTypes = ['expand', 'nestedExpand'] +const imageTypes = ['media', 'mediaInline'] +const shownTextTypes = ['date', 'emoji', 'extension', 'inlineExtension', 'mention', 'status'] export function adfToPlainText(document: AdfDocument): Result { return withinEngineLimits(() => { @@ -40,19 +49,25 @@ function writeText(content: readonly AdfNode[]): Result { let indent = '' let lead: string | undefined let literal = 0 + let cell: Cell | undefined + // Past its first text, a cell goes on the row's line: a line feed owed becomes a space, and a marker keeps its place without the row's margin. function emit(text: string): void { const end = endBeforeLineFeeds(text) if (end > 0) { const owed = Math.max(gap, literal) - const head = length === 0 || owed > 0 ? `${length === 0 ? '' : '\n'.repeat(owed)}${lead ?? indent}` : '' - const body = text.slice(0, end).replaceAll(/\n(?=[^\n])/g, `\n${indent}`) + const open = cell + let head = '' + if (open !== undefined && length > open.start) head = owed > 0 ? ` ${lead === undefined ? '' : lead.slice(open.base.length)}` : '' + else if (length === 0 || owed > 0 || lead !== undefined) head = `${length === 0 ? '' : '\n'.repeat(owed)}${lead ?? indent}` + const kept = text.slice(0, end) + const body = open === undefined ? kept.replaceAll(/\n(?=[^\n])/g, `\n${indent}`) : kept.replaceAll(/\n+/g, ' ') pieces.push(head, body) length += head.length + body.length gap = 0 lead = undefined } - literal = (end > 0 ? 0 : literal) + text.length - end + literal = (end > 0 ? 0 : literal) + (cell === undefined ? text.length - end : 0) } const pending: Step[] = childSteps(content, { level: 1, lines: 2 }, 0, undefined, () => undefined).reverse() @@ -61,6 +76,17 @@ function writeText(content: readonly AdfNode[]): Result { gap = Math.max(gap, step.lines) continue } + if (step.kind === 'leaveCell') { + const written = cell !== undefined && length > cell.start + gap = written ? 0 : step.gap + literal = written ? 0 : step.literal + cell = step.cell + continue + } + if (step.kind === 'separator') { + emit(' | ') + continue + } if (step.kind === 'leave') { indent = step.indent lead = step.length === length ? step.lead : undefined @@ -68,6 +94,10 @@ function writeText(content: readonly AdfNode[]): Result { } const { depth, marker, node, place, suffix } = step if (depth > largestNesting) return failure('unsupported-nesting-depth', `the document nests deeper than the ${largestNesting} levels the writer carries`, pathTo(place)) + if (cellTypes.includes(node.type)) { + pending.push({ cell, gap, kind: 'leaveCell', literal }) + cell = { base: indent, start: length } + } if (marker !== undefined) { pending.push({ indent, kind: 'leave', lead, length }) lead = lead === undefined ? `${indent}${marker}` : `${lead}${marker}` @@ -75,9 +105,14 @@ function writeText(content: readonly AdfNode[]): Result { } if (node.type === 'hardBreak') gap += 1 else if (shownTextTypes.includes(node.type)) emit(shownText(node) ?? '') + else if (cardTypes.includes(node.type)) emit(cardText(node)) + else if (imageTypes.includes(node.type)) emit(imageText(node)) else { - emit(`${node.text ?? ''}${suffix ?? ''}`) - for (const child of stepsWithin(node, depth, place).reverse()) pending.push(child) + const title = expandTypes.includes(node.type) ? shownText(node) : undefined + emit(`${node.text ?? title ?? ''}${suffix ?? ''}`) + const inner = stepsWithin(node, depth, place) + if (title !== undefined) inner.unshift({ kind: 'gap', lines: 2 }) + for (const child of inner.reverse()) pending.push(child) } if (length > longestOutput) return tooLong() } @@ -101,7 +136,7 @@ function childSteps(nodes: readonly AdfNode[], layout: Layout, depth: number, pa const links = nodes.map(linkOf) let run = '' for (const [index, node] of nodes.entries()) { - if (index > 0) steps.push({ kind: 'gap', lines: layout.lines }) + if (index > 0) steps.push(layout.cells === true ? { kind: 'separator' } : { kind: 'gap', lines: layout.lines }) const link = links[index] const before = links[index - 1] run = link !== undefined && before !== undefined && sameLink(link, before) ? `${run}${node.text ?? ''}` : node.text ?? '' @@ -112,6 +147,24 @@ function childSteps(nodes: readonly AdfNode[], layout: Layout, depth: number, pa return steps } +// A card shows its address, or its name and then its address. +function cardText(card: AdfNode): string { + const text = shownText(card) + const url = shownUrl(card) + return text === undefined || url === undefined || url === text ? text ?? '' : `${text} (${url})` +} + +// An image shows its alt text, else its address, else `[image]`; then the target of the link around it, then its own address where the alt text stood in for it. +function imageText(media: AdfNode): string { + const alt = visibleText(nodeAttrs(media)['alt']) + const link = shownLink(media) + const url = shownUrl(media) + const shown = alt ?? url ?? '[image]' + const target = link === undefined ? undefined : linkSuffix(link, shown) + const own = alt !== undefined && url !== undefined && url !== link?.href ? ` (${url})` : '' + return `${shown}${target ?? ''}${own}` +} + function linkOf(node: AdfNode): LinkAttrs | undefined { const mark = nodeMarks(node).find((held) => held.type === 'link') return node.type === 'text' && mark !== undefined ? linkAttrs(nodeAttrs(mark)) : undefined @@ -130,7 +183,9 @@ function linkSuffix(link: LinkAttrs, text: string): string | undefined { function layoutOf(node: AdfNode): Layout { if (bulletLists.includes(node.type) || node.type === 'orderedList') return { level: 1, lines: 1 } if (itemTypes.includes(node.type)) return { level: 0, lines: 1 } - if (node.type === 'tableCell' || node.type === 'tableHeader') return { level: 0, lines: 2 } + if (node.type === 'table') return { level: 1, lines: 1 } + if (node.type === 'tableRow') return { cells: true, level: 1, lines: 0 } + if (cellTypes.includes(node.type)) return { level: 0, lines: 2 } const model = blockNodeModel(node.type) if (model !== undefined) return model.contentModel === 'block' ? { level: 1, lines: 2 } : { level: 0, lines: 0 } return nodeContent(node).every((child) => child.type === 'text' || inlineNodeModel(child.type) !== undefined) ? { level: 0, lines: 0 } : { level: 1, lines: 2 } diff --git a/todo.md b/todo.md index 9dddc09..174e699 100644 --- a/todo.md +++ b/todo.md @@ -12,8 +12,6 @@ | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| -| 180 | 0.4.0 | | | **Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells.** | 2 | 2 | 2 | 4 | 3 | 3 by 1, 6.2 by 3 | 4.8 | -| 181 | 0.4.0 | | | **Write media, link cards, extensions and expand titles in `adfToPlainText` as the text each shows, and answer developer-community topic 41858.** | 2 | 2 | 2 | 4 | 4 | 3 by 2, 6.2 by 2 | 3.3 | | 141 | 0.4.0 | | decision | **Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element.** | 1 | 1 | 1 | 1 | 2 | 6 by 2 | 3.2 | | 135 | 0.4.0 | | | **Write media, media groups and captions as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 1.6 | | 136 | 0.4.0 | | | **Write underline, text and background colours, subscript, superscript, alignment and indentation as HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 1.6 | @@ -50,25 +48,6 @@ ## Details -### 180. Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells. - -A reader panel picks the cell separator, and what a header row, a merged cell and a block nested in -a cell read as. The verdict lands in `docs/decisions.md`. Until this item ships, -`adfToPlainText` writes a table's cells as blocks. - -### 181. Write media, link cards, extensions and expand titles in `adfToPlainText` as the text each shows, and answer developer-community topic 41858. - -`src/adf/shown-text.ts` already holds what each of these shows in portable markdown and HTML: an -image's alt text or URL, a card's URL or `data.name`, an extension's `text` and an expand's title. -For a node that shows no text, its `shownNote` names the node instead, such as `image` or an -extension's key. A reader panel picks which texts plain text keeps, and whether it writes those -notes. The verdict lands in `docs/decisions.md`. - -This item doesn't read item 180's table spelling, so the two land in either order. Both change -`adfToPlainText`, so the second to merge may meet a conflict; neither waits for the other. - -Topic 41858 asks for ADF as plain text. Answer it once item 181 ships (the maintainer, 2026-10-28). - ### 141. Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element. GFM spells `strike`, and no other HTML item writes it: `adfToHtml` writes only the marks CommonMark