3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25:44 +01:00

Write indentation as data-indent-level in HTML and read an opened details as the same expand

This commit is contained in:
2026-11-15 11:28:38 +01:00
committed by Lillem4n
parent 03e219ed74
commit ed03d42d8b
14 changed files with 122 additions and 75 deletions
+1 -1
View File
@@ -40,7 +40,7 @@ In `docs/decisions.md`:
- The portable reader refuses what GFM's reading would drop
- The portable reader reads what GFM's reading keeps
- The HTML dialect
- `htmlToAdf` also reads the dialect as a browser serializes it
- `htmlToAdf` also reads the dialect as a browser serializes it, and an opened `<details>` as the same expand
- No runtime dependencies
- Standards ship as data
- fast-check
+4 -1
View File
@@ -9,7 +9,10 @@
- `adfToHtml` writes underline as `<u>`, subscript and superscript as `<sub>` and `<sup>`, a text colour as
`<span style="color:…">`, a background colour as `<mark style="background-color:…">` and a paragraph's or
heading's alignment as `style="text-align:…"`, where `0.3.1` wrote the carry element, and `htmlToAdf` reads them
back. The carry element `0.3.1` wrote for them still reads. Indentation still rides the carry element.
back. The carry element `0.3.1` wrote for them still reads.
- `adfToHtml` writes a paragraph's or heading's indentation as `data-indent-level="2"`, where `0.3.1` wrote the carry
element, and `htmlToAdf` reads it back. `htmlToAdf` also reads `<details open="">`, as a browser writes an expand its
user opened, as the same expand.
- `adfToHtml` writes a panel as `<div class="adf-panel">`, an expand and a nested expand as `<details>` with the
title in a `<summary>`, a task list as `<ul class="adf-task-list">` of items each a checkbox then its text, and a
decision list as `<ul class="adf-decision-list">`, where `0.3.1` wrote the carry element, and `htmlToAdf` reads
+3 -2
View File
@@ -259,6 +259,7 @@ whatever it costs; the Achieve goals are weighed against each other in the order
7. **Maintain:** Lossy conversion drops form, never content. A link's or an image's title counts as content.
8. **Maintain:** Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.
9. **Maintain:** Fast, and linear in the document's size as JSON.
10. **Maintain:** HTML output carries semantic names, classes, ids and `data-*` attributes, never a style. Styling is the consumer's, in a stylesheet of their own.
## Audience
@@ -570,14 +571,14 @@ content. No stylesheet ships. The complete dialect:
| `decisionList`, `decisionItem` | `<ul class="adf-decision-list">`, `<li class="adf-decision" data-state="DECIDED">` |
| `expand`, `nestedExpand` | `<details class="adf-expand">`, `<details class="adf-nested-expand">`, a `<summary>` holding the `title` |
| `hardBreak` | `<br>` |
| `heading` | `<h1>` to `<h6>`; `style="text-align:center"` for a centered one, `text-align:right` for one aligned to the end |
| `heading` | `<h1>` to `<h6>`; `style="text-align:center"` for a centered one, `text-align:right` for one aligned to the end, `data-indent-level="2"` for an indented one |
| `inlineCard` holding a `url`, or `data` and no `url` | `<a class="adf-inline-card" href="…">…</a>`; for `data`, `href` is the URL `data` holds, the text its name, else that URL, and `data-data` the whole `data` as JSON |
| `link` | `<a href="…" title="…">` |
| `mediaGroup` | `<div class="adf-media-group">` holding a `<span class="adf-file" data-id="…" data-type="file"></span>` for each `media` |
| `mediaSingle` holding an external `media`, centered, uncaptioned, holding no other attribute such as `width` or `localId` | `<p><img src="…" alt="…"></p>`, the image inside `<a>` where a link marks it |
| any other `mediaSingle` | `<figure class="adf-media-single" data-layout="wide">` holding the `<img>`, then the caption as `<figcaption>` |
| `panel` | `<div class="adf-panel" data-panel-type="info">` |
| `paragraph` | `<p>`; `style="text-align:center"` or `text-align:right`, as on a heading |
| `paragraph` | `<p>`; `style="text-align:center"`, `text-align:right` or `data-indent-level="2"`, as on a heading |
| `rule` | `<hr>` |
| `table`, `tableRow`, `tableCell`, `tableHeader` | `<table>`, `<thead>` for a first row of `tableHeader` cells alone, `<tbody>`, `<tr>`, `<td>` and `<th>`; a cell's first paragraph stands as an item's does, and `<td colspan="2" rowspan="2" style="background-color:#fffae6" data-colwidth="120,80">` writes its attributes |
| `taskList`, `taskItem` | `<ul class="adf-task-list">`, `<li class="adf-task" data-state="DONE"><input type="checkbox" checked="" disabled=""> text</li>` |
+9 -4
View File
@@ -413,7 +413,7 @@ its own.
## The HTML dialect
2026-08-23, the maintainer; Atlassian's HTML+ 2026-10-28, the maintainer. Goals 6 and 8. Valid
2026-08-23, the maintainer; Atlassian's HTML+ 2026-10-28, the maintainer. Goals 6, 8 and 10. Valid
while HTML output is read by consumers styling it themselves, and while Atlassian publishes no spec
for HTML+, its Rovo MCP server's HTML for agents; a published spec reopens the goals.
@@ -510,7 +510,10 @@ An eighth panel (2026-11-14, three readers in the same roles; seven for indentat
a value because the attribute grammar has no bare attribute.
For an `indentation` mark, five of seven picked `data-indent-level`; whether a `margin-left` style
goes with it split 4 to 3, so it rides the carry until `todo.md` item 184 is answered.
goes with it split 4 to 3. The maintainer answered on 2026-11-15 that the dialect holds no style at
all (README goal 10), so an indentation is `data-indent-level="2"` alone, on a paragraph or heading
holding no other mark. The `style` attributes above, a text and a background colour, an alignment and
a cell's `background`, work against that goal until `todo.md` item 188 spells each without one.
## `htmlToAdf` also reads the dialect as a browser serializes it
@@ -524,8 +527,10 @@ or `>` reads as `&lt;` or `&gt;` (a browser from before the algorithm escaped th
in both, `&nbsp;` reads as a no-break space; and `\r\n` reads as a line feed. All of it holds in what
a carry element shows too. These are every difference the algorithm leaves between a browser's HTML
and `adfToHtml`'s, checked against Firefox's own `innerHTML` in the browser leg, and they hold for
every element the dialect writes, later ones included. Other HTML stays refused, a lone `\r` among
it. A refusal's position counts the HTML as handed in.
every element the dialect writes, later ones included. One difference is DOM state, not the
algorithm's: a `<details>` its user opened carries `open=""` after its other attributes, and
`htmlToAdf` reads it as the same expand (the maintainer, 2026-11-15), since ADF's `expand` holds no
open state and the state is the viewer's. Other HTML stays refused, a lone `\r` among it. A refusal's position counts the HTML as handed in.
## No runtime dependencies
+4 -3
View File
@@ -16,14 +16,14 @@ Blocks are separated by a line feed, and a document holding any ends with one. A
| `codeBlock` | `<pre><code class="language-js">…</code></pre>`, the language one token holding no ASCII whitespace (a tab, line feed, form feed, carriage return or space); no `class` where it holds no `language` |
| `decisionList` | `<ul class="adf-decision-list">`, a line feed, its items a line each, a line feed, `</ul>`; each `decisionItem` is `<li class="adf-decision" data-state="DECIDED">` around its inline content |
| `expand`, `nestedExpand` | `<details class="adf-expand">`, `<details class="adf-nested-expand">`, a line feed, a `<summary>` holding the `title` where there is one, its blocks, each after a line feed, a line feed, `</details>` |
| `heading`, `level` 1 to 6 | `<h1>…</h1>` to `<h6>…</h6>` |
| `heading`, `level` 1 to 6 | `<h1>…</h1>` to `<h6>…</h6>`; the `alignment` and `indentation` marks as on a paragraph |
| `listItem` | its first paragraph straight after `<li>`: bare where it holds content and no attribute, `<li>Bolt</li>`, and as its `<p>` element where it holds an attribute, `<li><p data-local-id="p1">Bolt</p></li>`; where other blocks follow, each after a line feed, and a line feed before `</li>`. Where the first block is no paragraph, holds neither content nor an attribute, or rides the carry: `<li>`, a line feed, its blocks, a line feed, `</li>` |
| `mediaGroup` | `<div class="adf-media-group">` holding a `<span class="adf-file" data-id="…" data-type="file"></span>` for each `media`, none between |
| `mediaSingle`, centered, holding one external `media` | `<p><img src="…" alt="…"></p>`, no `alt` where the media holds none; `<p><a href="…"><img …></a></p>` where a link marks it |
| `mediaSingle`, any other | `<figure class="adf-media-single" data-layout="wide">`, its `media` as the `<img>` below, then its caption as `<figcaption>…</figcaption>`, on one line, `</figure>`; the `<img>` inside `<a href="…">` where a link marks the media |
| `orderedList` | as `bulletList` with `<ol>`; `<ol start="3">` for an `order` of 3, a safe integer other than `-0`; no `start` where the list holds no `order` |
| `panel` | `<div class="adf-panel" data-panel-type="info">`, a line feed, its blocks a line each, a line feed, `</div>` |
| `paragraph` | `<p>…</p>`; `<p style="text-align:center">` for an `alignment` mark of `center` and `text-align:right` for `end`, as on a heading |
| `paragraph` | `<p>…</p>`; `<p style="text-align:center">` for an `alignment` mark of `center` and `text-align:right` for `end`, `<p data-indent-level="2">` for an `indentation` mark of `level` 2, as on a heading |
| `rule` | `<hr>` |
| `table` | `<table>`, a line feed, its sections parted by a line feed, a line feed, `</table>`: a `<thead>` where its first row holds cells that are all `tableHeader`, and a `<tbody>` for the other rows where there are any. Each section is its tag, a line feed, its rows a line each, a line feed, its closing tag |
| `tableCell`, `tableHeader` | `<td>`, `<th>`, each holding its blocks as a `listItem` does: `<td>Bolt M8</td>`; attributes `colspan`, `rowspan`, `style="background-color:#fffae6"` for `background`, and `data-colwidth="120,80"` for `colwidth`, first and in that order |
@@ -161,7 +161,7 @@ later release writes it as its own element.
- a `mediaSingle` holding anything but one `media`, then at most one `caption`, or a `mediaGroup`
holding anything but `media`; a `media` holding more than one mark, a mark that is no link, or a
`height` or `width` that is not a positive safe integer;
- a paragraph or heading holding a mark besides one `center` or `end` alignment;
- a paragraph or heading holding a mark besides one `center` or `end` alignment or one indentation of `level` 1 to 6;
- a `textColor` or `backgroundColor` whose `color` is not letters and digits after an optional `#`;
- a `panel` or `expand` holding an attribute its type does not hold as that kind; a `taskItem`
whose `state` is not `DONE` or `TODO`, or a task or decision list holding a node that is no
@@ -195,6 +195,7 @@ what it shows too:
| a no-break space | `&nbsp;` |
| `&lt;` and `&gt;` in an attribute value | a raw `<` and `>`, as older browsers write them |
| a line feed | `\r\n` |
| an expand's `<details>` | the same with `open=""` after its other attributes, the state of a `<details>` its user opened, dropped |
A refusal's position counts the HTML as handed in. `htmlToAdf` reads a carry element's node from its
`data-adf`, and what the element shows, through its closing tag, must be what `adfToHtml` shows for
-36
View File
@@ -1,36 +0,0 @@
import type { AdfAttributes, AdfMark, AdfNode } from '../adf/document.ts'
import type { AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
import type { Read } from '../result.ts'
import { dataAttributes, readDataAttributes } from './data-attributes.ts'
import { nodeAttrs, nodeMarks } from '../adf/document.ts'
// The `text-align` value each alignment names.
function alignments(): ReadonlyMap<string, string> {
return new Map([
['center', 'center'],
['end', 'right'],
])
}
// A paragraph's or heading's attributes: its alignment mark as a `style` attribute, then the rest as `dataAttributes` writes them; `undefined` where it holds a mark besides one alignment the style spells.
export function textBlockAttributes(node: AdfNode, vocabulary: AttributeVocabulary, written: readonly string[]): string | undefined {
const [mark, ...others] = nodeMarks(node)
if (mark === undefined) return dataAttributes(node, vocabulary, written)
const attrs = nodeAttrs(mark)
const align = attrs['align']
const textAlign = others.length === 0 && mark.type === 'alignment' && Object.keys(attrs).length === 1 && typeof align === 'string' ? alignments().get(align) : undefined
const bare: AdfNode = { ...node }
delete bare.marks
const data = textAlign === undefined ? undefined : dataAttributes(bare, vocabulary, written)
return data === undefined ? undefined : ` style="text-align:${textAlign}"${data}`
}
// The attributes and marks a paragraph's or heading's start tag holds, as `textBlockAttributes` writes them.
export function readTextBlockAttributes(pairs: readonly (readonly [string, string])[], element: string, vocabulary: AttributeVocabulary, written: readonly string[]): Read<{ attrs: AdfAttributes; marks: AdfMark[] }> {
const [first] = pairs
const align = first?.[0] === 'style' ? [...alignments()].find(([, textAlign]) => first[1] === `text-align:${textAlign}`)?.[0] : undefined
if (first?.[0] === 'style' && align === undefined) return { fault: { code: 'unmappable-html', message: `style on <${element}> holds text-align:center or text-align:right` } }
const data = readDataAttributes(align === undefined ? pairs : pairs.slice(1), element, vocabulary, written)
if (data.fault !== undefined) return data
return { value: { attrs: data.value, marks: align === undefined ? [] : [{ attrs: { align }, type: 'alignment' }] } }
}
+17 -3
View File
@@ -106,7 +106,7 @@ test('writes an item\'s first paragraph as its element on the item\'s line where
assert.equal(listed(held), `<ul>\n<li><p data-local-id="${ids.paragraph}">Bolt</p></li>\n</ul>\n`)
assert.equal(listed(held, { content: [item(paragraph(text('M8')))], type: 'bulletList' }), `<ul>\n<li><p data-local-id="${ids.paragraph}">Bolt</p>\n<ul>\n<li>M8</li>\n</ul>\n</li>\n</ul>\n`)
assert.equal(listed({ attrs: { localId: ids.paragraph }, type: 'paragraph' }), `<ul>\n<li><p data-local-id="${ids.paragraph}"></p></li>\n</ul>\n`)
assert.equal(listed({ content: [text('Bolt')], marks: [{ attrs: { level: 1 }, type: 'indentation' }], type: 'paragraph' }).startsWith('<ul>\n<li>\n<div class="adf-carry"'), true)
assert.equal(listed({ content: [text('Bolt')], marks: [{ attrs: { level: 1 }, type: 'alignment' }], type: 'paragraph' }).startsWith('<ul>\n<li>\n<div class="adf-carry"'), true)
})
test('writes the attributes an element cannot express as data-* attributes on it, sorted, a value that is no string as JSON', () => {
@@ -234,10 +234,24 @@ test('carries a paragraph or heading holding an alignment HTML cannot spell, or
assert.equal(carriedBlockOf({ attrs: { align: 'start' }, type: 'alignment' }), true)
assert.equal(carriedBlockOf({ attrs: { align: 'center', x: 1 }, type: 'alignment' }), true)
assert.equal(carriedBlockOf({ type: 'alignment' }), true)
assert.equal(carriedBlockOf({ attrs: { level: 1 }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { level: 7 }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { level: 0 }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { level: 1.5 }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { level: '2' }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { level: 1, x: 1 }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { level: 1 }, type: 'indentation' }, { attrs: { level: 2 }, type: 'indentation' }), true)
assert.equal(carriedBlockOf({ attrs: { align: 'center' }, type: 'alignment' }, { attrs: { align: 'end' }, type: 'alignment' }), true)
assert.equal(carriedBlockOf({ attrs: { align: 'center' }, type: 'alignment' }, { attrs: { level: 1 }, type: 'indentation' }), true)
assert.equal(carriedBlock({ attrs: { level: 1 }, content: [text('x')], marks: [{ attrs: { level: 1 }, type: 'indentation' }], type: 'heading' }), true)
assert.equal(carriedBlock({ attrs: { level: 1 }, content: [text('x')], marks: [{ attrs: { level: 7 }, type: 'indentation' }], type: 'heading' }), true)
})
test('writes a paragraph or heading marked with an indentation of 1 to 6 as a data-indent-level attribute', () => {
const indented = (level: number, node: AdfNode = paragraph(text('x'))): string => html(adfToHtml(document({ ...node, marks: [{ attrs: { level }, type: 'indentation' }] })))
assert.equal(indented(2), '<p data-indent-level="2">x</p>\n')
assert.equal(indented(6, { attrs: { level: 2 }, content: [text('x')], type: 'heading' }), '<h2 data-indent-level="6">x</h2>\n')
assert.equal(indented(1, { attrs: { localId: ids.paragraph }, type: 'paragraph' }), `<p data-indent-level="1" data-local-id="${ids.paragraph}"></p>\n`)
assert.equal(html(adfToHtml(document({ content: [item({ content: [text('x')], marks: [{ attrs: { level: 3 }, type: 'indentation' }], type: 'paragraph' })], type: 'bulletList' }))), '<ul>\n<li><p data-indent-level="3">x</p></li>\n</ul>\n')
})
test('carries every other node in an adf-carry element holding its JSON', () => {
+1 -1
View File
@@ -19,7 +19,7 @@ import { longestOutput, tooLong, withinEngineLimits } from '../../length-bound.t
import { mediaImage } from '../media-element.ts'
import { plainImage } from '../../adf/plain-image.ts'
import { serializeCanonicalJson } from '../../canonical-json.ts'
import { textBlockAttributes } from '../alignment-element.ts'
import { textBlockAttributes } from '../text-block-attributes.ts'
// depth: the nesting level of the block list holding the node, as `largestNesting` counts it; `attributes`: the `<li>`'s, `<td>`'s or `<th>`'s, built when its list or table checked it; `lead`: what stands before the inline content of a task or decision item.
type Block = { depth: number; kind: 'block'; node: AdfNode; path: ConvertErrorPath }
+1 -1
View File
@@ -1,7 +1,7 @@
import type { AdfNode } from '../adf/document.ts'
import { blockNodes } from '../adf/block-nodes.ts'
import { nodeContent } from '../adf/document.ts'
import { textBlockAttributes } from './alignment-element.ts'
import { textBlockAttributes } from './text-block-attributes.ts'
// Where a list item's first paragraph stands: `bare` on the item's line, its `element` there, or a `block` on a line of its own.
export type FirstParagraphForm = 'bare' | 'block' | 'element'
+17 -2
View File
@@ -253,6 +253,17 @@ test('refuses a mark element the writer does not write', () => {
}
})
test('reads a paragraph or heading with a data-indent-level attribute as indented', () => {
const indentation = (level: number): AdfMark => ({ attrs: { level }, type: 'indentation' })
assert.deepEqual(read(htmlToAdf('<p data-indent-level="2">x</p>\n')), document({ content: [text('x')], marks: [indentation(2)], type: 'paragraph' }))
assert.deepEqual(read(htmlToAdf('<h2 data-indent-level="6">x</h2>\n')), document({ attrs: { level: 2 }, content: [text('x')], marks: [indentation(6)], type: 'heading' }))
assert.deepEqual(read(htmlToAdf(`<p data-indent-level="1" data-local-id="${ids.paragraph}"></p>\n`)), document({ attrs: { localId: ids.paragraph }, marks: [indentation(1)], type: 'paragraph' }))
assert.deepEqual(read(htmlToAdf('<ul>\n<li><p data-indent-level="3">x</p></li>\n</ul>\n')), document({ content: [item({ content: [text('x')], marks: [indentation(3)], type: 'paragraph' })], type: 'bulletList' }))
for (const html of ['<p data-indent-level="0">x</p>\n', '<p data-indent-level="7">x</p>\n', '<p data-indent-level="02">x</p>\n', '<p data-indent-level="1.5">x</p>\n', '<p data-indent-level="">x</p>\n', '<p data-indent-level="2" style="text-align:center">x</p>\n', '<p style="text-align:center" data-indent-level="2">x</p>\n', `<p data-local-id="${ids.paragraph}" data-indent-level="2">x</p>\n`, '<p data-indent-level="2" data-indent-level="2">x</p>\n', '<blockquote data-indent-level="2">\n<p>x</p>\n</blockquote>\n']) {
assert.notEqual(refusal(htmlToAdf(html)), 'read', html)
}
})
test('reads a paragraph or heading with a style attribute as aligned, right as end', () => {
const alignment = (align: string): AdfMark => ({ attrs: { align }, type: 'alignment' })
assert.deepEqual(read(htmlToAdf('<p style="text-align:center">x</p>\n')), document({ content: [text('x')], marks: [alignment('center')], type: 'paragraph' }))
@@ -694,7 +705,7 @@ const pinnedRefusals: readonly (readonly [string, string])[] = [
['<div class="adf-panel" data-panel-type="info">\n</div>\n', 'unmappable-html at /content/0/content/0: a block element of the dialect stands here: found "</div>\\n"'],
['<div class="adf-panel" data-panel-type="info"><p>a</p></div>\n', 'unmappable-html at /content/0: <div> holds </div> straight after it, or a line feed and its first block: found "<p>a</p></div>\\n"'],
['<div id="x" class="adf-panel">\n<p>a</p>\n</div>\n', 'unmappable-html at /content/0: a <div> of the dialect is a carry element, holding class="adf-carry" and then data-adf alone: found "<div id=\\"x\\" class=\\"adf-p"…'],
['<details class="adf-expand" open="">\n<p>a</p>\n</details>\n', 'unmappable-html at /content/0: <details> takes no open attribute'],
['<details class="adf-expand" open="x">\n<p>a</p>\n</details>\n', 'unmappable-html at /content/0: <details> takes no open attribute'],
['<details class="adf-expand" data-title="a">\n<p>a</p>\n</details>\n', 'unsupported-node-shape at /content/0: <details> takes no data-title attribute'],
['<details>\n<p>a</p>\n</details>\n', 'unmappable-html at /content/0: <details> starts with class="adf-expand" or class="adf-nested-expand": found "<details>\\n<p>a</p>\\n</det"…'],
['<details class="adf-expand">\n</details>\n', 'unmappable-html at /content/0/content/0: a block element of the dialect stands here: found "</details>\\n"'],
@@ -784,6 +795,8 @@ test('reads an expand and a nested expand back from their details, the title fro
assert.deepEqual(expand('<details class="adf-expand" data-local-id="x1">\n<summary>Details &amp; more</summary>\n<p>Inside</p>\n</details>\n'), document({ attrs: { localId: 'x1', title: 'Details & more' }, content: [paragraph(text('Inside'))], type: 'expand' }))
assert.deepEqual(expand('<details class="adf-nested-expand">\n<summary>T</summary>\n<p>Inside</p>\n</details>\n'), document({ attrs: { title: 'T' }, content: [paragraph(text('Inside'))], type: 'nestedExpand' }))
assert.deepEqual(expand('<details class="adf-expand">\n<p>Inside</p>\n</details>\n'), document({ content: [paragraph(text('Inside'))], type: 'expand' }))
assert.deepEqual(expand('<details class="adf-expand" data-local-id="x1" open="">\n<summary>T</summary>\n<p>Inside</p>\n</details>\n'), document({ attrs: { localId: 'x1', title: 'T' }, content: [paragraph(text('Inside'))], type: 'expand' }))
assert.deepEqual(expand('<details class="adf-nested-expand" open="">\n<p>Inside</p>\n</details>\n'), document({ content: [paragraph(text('Inside'))], type: 'nestedExpand' }))
assert.deepEqual(expand('<details class="adf-expand">\n<summary></summary>\n<p>Inside</p>\n</details>\n'), document({ attrs: { title: '' }, content: [paragraph(text('Inside'))], type: 'expand' }))
assert.deepEqual(expand('<details class="adf-expand">\n<summary>T</summary>\n</details>\n'), document({ attrs: { title: 'T' }, type: 'expand' }))
assert.deepEqual(expand('<details class="adf-expand"></details>\n'), document({ type: 'expand' }))
@@ -792,7 +805,9 @@ test('reads an expand and a nested expand back from their details, the title fro
test('refuses an expand the writer does not write', () => {
const refused = (source: string): string => refusal(htmlToAdf(source))
assert.equal(refused('<details class="adf-expand" open="">\n<p>a</p>\n</details>\n'), 'unmappable-html at /content/0 line 1 offset 0')
assert.equal(refused('<details class="adf-expand" open="x">\n<p>a</p>\n</details>\n'), 'unmappable-html at /content/0 line 1 offset 0')
assert.equal(refused('<details class="adf-expand" open="" data-local-id="x1">\n<p>a</p>\n</details>\n'), 'unmappable-html at /content/0 line 1 offset 0')
assert.equal(refused('<details class="adf-expand" open="" open="">\n<p>a</p>\n</details>\n'), 'unmappable-html at /content/0 line 1 offset 0')
assert.equal(refused('<details class="adf-expand" data-title="a">\n<p>a</p>\n</details>\n'), 'unsupported-node-shape at /content/0 line 1 offset 0')
assert.equal(refused('<details>\n<p>a</p>\n</details>\n'), 'unmappable-html at /content/0 line 1 offset 0')
assert.equal(refused('<details class="adf-expand">\n</details>\n'), 'unmappable-html at /content/0/content/0 line 2 offset 29')
+3 -2
View File
@@ -237,12 +237,13 @@ function readPanel(html: string, tag: StartTag, place: Place, open: Open): Resul
return readContents(html, tag, built('panel', data.value, []), place, open, 'blocks')
}
// An expand's title stands in a `<summary>` on the first line, its blocks a line each after it.
// An expand's title stands in a `<summary>` on the first line, its blocks a line each after it. A browser appends `open=""` to a `<details>` its user opened: the state is the viewer's, so it reads as the same expand.
function readDetails(html: string, tag: StartTag, place: Place, open: Open): Result<BlockStep, ParseError> {
const [first, ...pairs] = tag.attributes
const type = first?.[0] === 'class' ? expandOfClass(first[1]) : undefined
if (type === undefined) return refused('unmappable-html', `<details> starts with class="${expandClasses.expand}" or class="${expandClasses.nestedExpand}": ${foundAt(html, tag.start)}`, html, tag.start, place)
const data = readDataAttributes(pairs, tag.name, blockNodes[type].attributes, ['title'])
const opened = pairs.at(-1)?.[0] === 'open' && pairs.at(-1)?.[1] === ''
const data = readDataAttributes(opened ? pairs.slice(0, -1) : pairs, tag.name, blockNodes[type].attributes, ['title'])
if (data.fault !== undefined) return refused(data.fault.code, data.fault.message, html, tag.start, place)
const summary = html.startsWith('\n<summary>', tag.end) ? readSummary(html, tag.end + 1, place) : undefined
if (summary?.ok === false) return summary
+2 -2
View File
@@ -4,13 +4,13 @@ import type { Read } from '../../result.ts'
import { misread, refused, type Place, type ReadNode, type StartTag } from './source.ts'
import { readDataAttributes } from '../data-attributes.ts'
import { readInline } from './inline.ts'
import { readTextBlockAttributes } from '../alignment-element.ts'
import { readTextBlockAttributes } from '../text-block-attributes.ts'
import { success } from '../../result.ts'
// `own`: the attributes the element itself writes, such as a heading's level.
export function readInlineBlock(html: string, tag: StartTag, type: string, vocabulary: AttributeVocabulary, own: AdfAttributes, place: Place): ReadNode {
const written = Object.keys(own)
// Only a paragraph or heading takes an alignment, as a `style` attribute.
// Only a paragraph or heading takes an alignment or an indentation, as the attribute that spells it.
const aligned = type === 'paragraph' || type === 'heading'
const held = aligned ? readTextBlockAttributes(tag.attributes, tag.name, vocabulary, written) : readUnmarked(tag, vocabulary, written)
if (held.fault !== undefined) return refused(held.fault.code, held.fault.message, html, tag.start, place)
+54
View File
@@ -0,0 +1,54 @@
import type { AdfAttributes, AdfMark, AdfNode } from '../adf/document.ts'
import type { AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
import type { Read } from '../result.ts'
import { dataAttributes, readDataAttributes } from './data-attributes.ts'
import { nodeAttrs, nodeMarks } from '../adf/document.ts'
// The `text-align` value each alignment names.
function alignments(): ReadonlyMap<string, string> {
return new Map([
['center', 'center'],
['end', 'right'],
])
}
const indentAttribute = 'data-indent-level'
const indentLevels = ['1', '2', '3', '4', '5', '6']
// A paragraph's or heading's attributes: its one alignment or indentation mark as the attribute that spells it, then the rest as `dataAttributes` writes them; `undefined` where it holds a mark the attribute does not spell, or a second one.
export function textBlockAttributes(node: AdfNode, vocabulary: AttributeVocabulary, written: readonly string[]): string | undefined {
const [mark, ...others] = nodeMarks(node)
if (mark === undefined) return dataAttributes(node, vocabulary, written)
const spelled = others.length === 0 ? markAttribute(mark) : undefined
const bare: AdfNode = { ...node }
delete bare.marks
const data = spelled === undefined ? undefined : dataAttributes(bare, vocabulary, written)
return data === undefined ? undefined : `${spelled}${data}`
}
function markAttribute(mark: AdfMark): string | undefined {
const attrs = nodeAttrs(mark)
if (Object.keys(attrs).length !== 1) return undefined
const { align, level } = attrs
if (mark.type === 'alignment' && typeof align === 'string') return alignments().has(align) ? ` style="text-align:${alignments().get(align)}"` : undefined
return mark.type === 'indentation' && typeof level === 'number' && indentLevels.includes(String(level)) ? ` ${indentAttribute}="${level}"` : undefined
}
// The attributes and marks a paragraph's or heading's start tag holds, as `textBlockAttributes` writes them.
export function readTextBlockAttributes(pairs: readonly (readonly [string, string])[], element: string, vocabulary: AttributeVocabulary, written: readonly string[]): Read<{ attrs: AdfAttributes; marks: AdfMark[] }> {
const [first] = pairs
const mark = first === undefined ? undefined : readMark(first, element)
if (mark?.fault !== undefined) return mark
const data = readDataAttributes(mark === undefined ? pairs : pairs.slice(1), element, vocabulary, written)
if (data.fault !== undefined) return data
return { value: { attrs: data.value, marks: mark === undefined ? [] : [mark.value] } }
}
function readMark([name, spelled]: readonly [string, string], element: string): Read<AdfMark> | undefined {
if (name === indentAttribute) {
return indentLevels.includes(spelled) ? { value: { attrs: { level: Number(spelled) }, type: 'indentation' } } : { fault: { code: 'unmappable-html', message: `${indentAttribute} on <${element}> holds a whole number from 1 to 6` } }
}
if (name !== 'style') return undefined
const align = [...alignments()].find(([, textAlign]) => spelled === `text-align:${textAlign}`)?.[0]
return align === undefined ? { fault: { code: 'unmappable-html', message: `style on <${element}> holds text-align:center or text-align:right` } } : { value: { attrs: { align }, type: 'alignment' } }
}
+6 -17
View File
@@ -6,14 +6,13 @@
`Bar = 0.1`
`Next ID = 188`
`Next ID = 189`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 184 | 0.4.0 | | question | **Write indentation as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element, once the maintainer settles whether its element carries a `margin-left` style.** | 1 | 2 | 2 | 3 | 2 | 6 by 2 | 3.2 |
| 185 | 0.4.0 | | question | **Read `<details class="adf-expand" open="">` as the same expand, or keep refusing it, once the maintainer settles which.** | 1 | 1 | 2 | 2 | 2 | 6 by 1 | 1.6 |
| 188 | 0.4.0 | | defect | **Write no `style` attribute in `adfToHtml`: spell text and background colours, alignment and a cell's background with classes or `data-*` attributes, and read them back in `htmlToAdf`.** | 3 | 1 | 2 | 4 | 5 | 10 by 10 | 21.2 |
| 46 | 0.4.0 | | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 2 | 1 | 3 | 4 | 3 by 3 | 2.6 |
| 186 | 0.4.0 | | | **Name every spelling of the dialect's `<div>`, `<span>` and `<mark>` in the refusal of one that matches none.** | 1 | 1 | 1 | 1 | 1 | 6 by 1 | 1.9 |
| 174 | 0.4.0 | | defect | **Bound the passes `trimmedEdges` takes by a constant, so a line of alternating code and emphasized blanks trims in linear time.** | 3 | 1 | 2 | 4 | 7 | 9 by 3 | 1.9 |
@@ -49,23 +48,13 @@
## Details
### 184. Write indentation as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element, once the maintainer settles whether its element carries a `margin-left` style.
### 188. Write no `style` attribute in `adfToHtml`: spell text and background colours, alignment and a cell's background with classes or `data-*` attributes, and read them back in `htmlToAdf`.
Alignment, underline, colours, subscript and superscript are written as HTML, and indentation stays on the carry element, since the writer panel did not settle one spelling.
README goal 10 holds the dialect to semantic names, classes, ids and `data-*` attributes, never a style; styling is the consumer's, in a stylesheet of their own. The unreleased dialect writes four: `style="text-align:center|right"` on a paragraph or heading, `<span style="color:…">`, `<mark style="background-color:…">` and a cell's `style="background-color:…"`.
A writer panel of seven picked `data-indent-level` for the attribute name, 5 of 7. It split on whether a `margin-left` style stands beside it: 4 readers wanted the style as well, so a browser shows the indent, and 3 wanted the data attribute alone, as the alignment and colour styles are the only presentation the dialect writes.
Colours are arbitrary hex values, so a class per colour cannot spell them; a `data-*` attribute holding the value, beside a class naming the element, is the likely spelling, and an alignment a class such as `adf-align-center`. Each spelling is settled by a writer panel (AGENTS.md §7), then written in `spec/html.md`, the README table and `docs/decisions.md` §The HTML dialect, whose style-spelling lines this item replaces. The carry element `0.3.1` wrote still reads; the style spellings were never released, so `htmlToAdf` stops reading them.
Recommendation: the data attribute alone. The dialect writes no style the viewer needs to read the document, and a `margin-left` in some unit would be a second spelling of the level that has to agree with it. The level stays one value, `data-indent-level="2"`, and a block holding an indentation mark takes no other mark.
The gap to close in `docs/decisions.md`: the class is "which output the audience expects", settled by a panel, and this panel's split is less than five of seven, so it is a missing goal and the maintainer's to answer.
### 185. Read `<details class="adf-expand" open="">` as the same expand, or keep refusing it, once the maintainer settles which.
A browser serializes a `<details>` its user opened as `<details open="">`, so a document read from a browser's DOM refuses at the expand, naming the attribute.
The gap to close in `docs/decisions.md`: the difference is browser-set DOM state, which is not a difference of the innerHTML algorithm, so §`htmlToAdf` also reads the dialect as a browser serializes it, which lists every difference that algorithm leaves, does not decide it.
Recommendation: read `open=""` as the same expand and drop the state, since ADF's `expand` has no open state and the state is the viewer's, not the document's. The entry then names `open` as one more difference a browser leaves.
Release 0.4.0 holds this item, so it is not ready to cut before this lands; the release's contents are the maintainer's, and this item is filed under the goal they stated on 2026-11-15.
### 46. Publish the bundle size in the README, failing the release pipeline when it drifts.