From b362ae25f51afbde946d3532034d1f5f2571f16c Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 14 Nov 2026 21:57:04 +0100 Subject: [PATCH] =?UTF-8?q?Answer=20stability=20round=201:=201=20?= =?UTF-8?q?=F0=9F=94=B4,=204=20=F0=9F=9F=A1=20(0=20misread);=20keep=20a=20?= =?UTF-8?q?row=20on=20its=20line=20when=20a=20cell=20starts=20empty,=20dro?= =?UTF-8?q?p=20the=20margin=20of=20a=20cell's=20list,=20soften=20a=20test?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 5 ++-- README.md | 2 +- docs/decisions.md | 27 +++++++++++---------- src/plain-text/adf-to-plain-text.test.ts | 30 +++++++++++++++++------ src/plain-text/adf-to-plain-text.ts | 31 ++++++++++++------------ todo.md | 7 +++++- 6 files changed, 63 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f880eb..10161f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,9 @@ 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; 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` + cells apart by ` | `; an image as its alt text and address, the address alone with no alt text, `[image]` + with neither; a card as its address, or its name then its address; an extension as its 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 diff --git a/README.md b/README.md index 935fd2e..f1606f9 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 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` | +| `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, the address alone with no alt text, and `[image]` with neither; a card as its address, or its name then its address in parentheses; an extension as its 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 f8ca144..da343d3 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1319,12 +1319,13 @@ had expected no title, and goal 7 counts a title as content, so every candidate 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). +` | ` between cells, a header row like any other, a merged cell written once with its covered cells +left out, 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. The picks +split on a block in a cell, where five of seven had expected the blocks joined by a space, so that is +the rule. They split on an image with an address too; the maintainer chose alt text then +` (address)`, as links do, since goal 7 counts the address as content, and the address alone with no +alt text. `adfToPlainText` writes: @@ -1340,12 +1341,12 @@ goal 7 counts the address as content; with no alt text the address alone). 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 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. +- A table as one line per row, its cells apart by ` | ` and an empty cell between the bars, a + header row like any other; a merged cell once, its covered cells left out; a cell's blocks, hard + breaks and code lines on the row's 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. + it, titled as a link is, then ` (address)` for its own address where the alt text stood in for it, + unless that is the link's address. +- A card as its address, or its name then ` (address)`, and an extension as its `text`. A card, an + extension or a synced block holding no text adds no note in its place. - An expand's title on a line, a blank line above its body. diff --git a/src/plain-text/adf-to-plain-text.test.ts b/src/plain-text/adf-to-plain-text.test.ts index 1b21729..bd62762 100644 --- a/src/plain-text/adf-to-plain-text.test.ts +++ b/src/plain-text/adf-to-plain-text.test.ts @@ -254,13 +254,13 @@ 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', () => { +test('writes a merged cell once, with its covered cells left out', () => { 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', () => { +test('writes an empty cell as nothing 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') }) @@ -278,11 +278,27 @@ 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') }) -test('writes the text nodes of a cell without a space between them, and a list in a nested table behind its own marker', () => { +test('writes the text nodes of a cell without a space between them', () => { const marked: AdfNode = { marks: [{ type: 'strong' }], text: 'b', type: 'text' } assert.equal(plain(adfToPlainText(document(table(row(cell(paragraph(text('a'), marked)), cell(line('c'))))))), 'ab | c') +}) + +test('writes a list in any cell of a table inside a list item behind its own marker, without the item\'s indent', () => { const listed = row(cell(bullets(item(line('p')), item(line('q')))), cell(line('y'))) assert.equal(plain(adfToPlainText(document(bullets(item(line('t'), table(listed)))))), '• t\n • p • q | y') + const later = row(cell(line('y')), cell(bullets(item(line('p')), item(line('q'))))) + assert.equal(plain(adfToPlainText(document(bullets(item(line('t'), table(later)))))), '• t\n y | • p • q') +}) + +test('writes the items of a list nested in a list in a cell a space apart, without the nesting margin', () => { + const nested = bullets(item(line('p'), bullets(item(line('q'))))) + assert.equal(plain(adfToPlainText(document(table(row(cell(nested), cell(line('y'))))))), '• p • q | y') +}) + +test('keeps a row on its line when the first block of a cell holds no text', () => { + const code = (value: string): AdfNode => ({ content: [text(value)], type: 'codeBlock' }) + const leading: AdfNode[] = [paragraph(), paragraph({ type: 'hardBreak' }), { type: 'rule' }, code('\n')] + for (const first of leading) assert.equal(plain(adfToPlainText(document(table(row(cell(line('a')), cell(first, line('b'))), row(cell(first, line('c')), cell(line('d'))))))), 'a | b\nc | d') }) test('writes a blank line and a line feed ending a code fragment in a cell as one space each', () => { @@ -320,12 +336,12 @@ test('writes the target of a link around an image, after its alt text and before 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', () => { +test('writes a link\'s title behind its target after an image', () => { 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', () => { +test('writes the images of a group a blank line apart, and an inline image on the line it stands 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') }) @@ -342,7 +358,7 @@ test('writes a card as its address, or as its name then its address', () => { 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', () => { +test('writes an extension as the text it carries, and as no text 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') @@ -385,7 +401,7 @@ const refusedDocuments: Record = { 'a card with a link mark': document(paragraph(text('See '), { attrs: { url: 'https://example.com/' }, marks: [{ attrs: { href: 'https://example.com/' }, type: 'link' }], type: 'inlineCard' })), } -test('names the limit it refuses a document for', () => { +test('gives the limit in the message of a document nested too deep', () => { assert.equal(plain(adfToPlainText(document(deepQuote(largestNesting + 1)))), `unsupported-nesting-depth: the document nests deeper than the ${largestNesting} levels the writer carries`) }) diff --git a/src/plain-text/adf-to-plain-text.ts b/src/plain-text/adf-to-plain-text.ts index 23528d0..c7cdb21 100644 --- a/src/plain-text/adf-to-plain-text.ts +++ b/src/plain-text/adf-to-plain-text.ts @@ -8,31 +8,31 @@ import { longestOutput, tooLong, withinEngineLimits } from '../length-bound.ts' import { nodeAttrs, nodeContent, nodeMarks, readAdfDocument, writableContent } from '../adf/document.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; `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. +// `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 to restore after a table cell, with the `gap` and `literal` to restore too where the cell wrote no text; `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' } + | { kind: 'leaveCell'; cell: Cell | undefined; gap: number; literal: number } | { depth: number; kind: 'node'; marker: string | undefined; node: AdfNode; place: Place | undefined; suffix: string | undefined } + | { kind: 'separator' } // The text written so far. `pieces`: its heads and bodies, `length` their total; `gap`: the line feeds the layout owes before the next text at least, and `literal` those the text before ended in, of which the larger is written; `lead`: the marker of the item the next text opens; `indent`: the margin of every line after that; `cell`: the table cell being written. type Writing = { cell: Cell | undefined; gap: number; indent: string; lead: string | undefined; length: number; literal: number; pieces: string[] } -// 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 } +// A table cell being written: its text goes on the row's line, without the row's margin; `start` is the `length` where the cell began, and `owed` the line feeds owed there, the only ones its first text may write. +type Cell = { owed: number; 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 cardTypes = ['blockCard', 'embedCard', 'inlineCard'] const cellTypes = ['tableCell', 'tableHeader'] const expandTypes = ['expand', 'nestedExpand'] const imageTypes = ['media', 'mediaInline'] +const itemTypes = ['blockTaskItem', 'listItem'] +const markedItems = ['blockTaskItem', 'decisionItem', 'listItem', 'taskItem'] const shownTextTypes = ['date', 'emoji', 'extension', 'inlineExtension', 'mention', 'status'] export function adfToPlainText(document: AdfDocument): Result { @@ -58,7 +58,6 @@ function writeText(content: readonly AdfNode[]): Result { return success(writing.pieces.join('')) } -// What a step that is no node does to the state. function applyStep(writing: Writing, step: Exclude): void { if (step.kind === 'gap') writing.gap = Math.max(writing.gap, step.lines) else if (step.kind === 'separator') emit(writing, ' | ') @@ -79,7 +78,7 @@ function openNode(writing: Writing, step: Extract, pendi 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: writing.cell, gap: writing.gap, kind: 'leaveCell', literal: writing.literal }) - writing.cell = { base: writing.indent, start: writing.length } + writing.cell = { owed: Math.max(writing.gap, writing.literal), start: writing.length } } if (marker !== undefined) { pending.push({ indent: writing.indent, kind: 'leave', lead: writing.lead, length: writing.length }) @@ -100,14 +99,16 @@ function openNode(writing: Writing, step: Extract, pendi return 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. +// In a cell, the text goes on the row's line: before its first text only the line feeds owed at the cell's start are written, after it a line feed owed or in the text becomes a space, and a list marker keeps its place without any margin. function emit(writing: Writing, text: string): void { const end = endBeforeLineFeeds(text) if (end > 0) { - const owed = Math.max(writing.gap, writing.literal) const { cell, indent, lead, length } = writing + const started = cell !== undefined && length > cell.start + const owed = cell !== undefined && !started ? cell.owed : Math.max(writing.gap, writing.literal) + const marker = lead?.trimStart() ?? '' let head = '' - if (cell !== undefined && length > cell.start) head = owed > 0 ? ` ${lead === undefined ? '' : lead.slice(cell.base.length)}` : '' + if (cell !== undefined && (started || (owed === 0 && length > 0))) head = started ? (owed > 0 ? ` ${marker}` : '') : marker else if (length === 0 || owed > 0 || lead !== undefined) head = `${length === 0 ? '' : '\n'.repeat(owed)}${lead ?? indent}` const kept = text.slice(0, end) const body = cell === undefined ? kept.replaceAll(/\n(?=[^\n])/g, `\n${indent}`) : kept.replaceAll(/\n+/g, ' ') @@ -130,7 +131,7 @@ function stepsWithin(node: AdfNode, depth: number, place: Place | undefined): St return childSteps(nodeContent(node), layout, depth + layout.level, place, markerFor(node)) } -// The steps for `nodes` in document order, `layout.lines` line feeds apart. +// The steps for `nodes` in document order, `layout.lines` line feeds apart, or bar-separated where the layout holds cells. function childSteps(nodes: readonly AdfNode[], layout: Layout, depth: number, parent: Place | undefined, markerFor: (index: number, node: AdfNode) => string | undefined): Step[] { const steps: Step[] = [] const links = nodes.map(linkOf) @@ -154,7 +155,7 @@ function cardText(card: AdfNode): string { return 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. +// An image shows its alt text, else its address, else `[image]`; then the target of the link around it, then its own address, unless that is the link's target or the image showed it already. function imageText(media: AdfNode): string { const alt = visibleText(nodeAttrs(media)['alt']) const link = shownLink(media) @@ -179,7 +180,7 @@ function linkSuffix(link: LinkAttrs, text: string): string | undefined { return ` (${link.href}, "${link.title}")` } -// Children stand on one line where they are inline, a line feed apart in a list and an item, a blank line apart between blocks. A list's items nest one level below it, an item's blocks at its own. +// Children stand on one line where they are inline, a line feed apart in a list, an item and a table, a blank line apart between other blocks. A list's items nest one level below it, an item's blocks at its own. 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 } diff --git a/todo.md b/todo.md index 174e699..2c09bdb 100644 --- a/todo.md +++ b/todo.md @@ -6,12 +6,13 @@ `Bar = 0.1` -`Next ID = 183` +`Next ID = 184` ## Items | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| +| 183 | 0.4.0 | | | **Answer developer-community topic 41858 once 0.4.0 is published.** | 1 | 1 | 1 | 1 | 1 | 3 by 2, 6.2 by 2 | 7.9 | | 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 | @@ -48,6 +49,10 @@ ## Details +### 183. Answer developer-community topic 41858 once 0.4.0 is published. + +Topic 41858 asks for ADF as plain text. `adfToPlainText` now writes tables, images, cards, extensions and expand titles, so the answer names what it writes. Post it only after 0.4.0 publishes (§Posts announcing a release wait for its publish). The post is the maintainer's (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