3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 06:05:43 +01:00

Answer product-owner round 1: 0 🔴, 2 🟡 (0 misread); refuse a stray data-indent-level and a stray open, name open in the README

This commit is contained in:
2026-11-15 12:09:39 +01:00
committed by Lillem4n
parent 0b88649dd8
commit c7766a2d2c
10 changed files with 36 additions and 27 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, and an opened `<details>` as the same expand
- `htmlToAdf` also reads the dialect as a browser serializes it
- No runtime dependencies
- Standards ship as data
- fast-check
+2 -2
View File
@@ -11,8 +11,8 @@
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.
- `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.
element, and `htmlToAdf` reads it back. The carry element `0.3.1` wrote for it still reads.
- `htmlToAdf` reads an expand's `<details class="adf-expand" open="">`, as a browser writes one 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 -3
View File
@@ -259,7 +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.
10. **Maintain:** HTML output holds no style: elements, classes, ids and `data-*` attributes name what a node is. Styling is the consumer's, in a stylesheet of their own.
## Audience
@@ -556,7 +556,7 @@ saving what this pair read replaces mentions, attachments and macros with text.
## HTML
Serves [Goals](#goals) 1, 6 and 7. `adfToHtml` writes the nodes and marks the table lists as their
Serves [Goals](#goals) 1, 6, 7 and 10. `adfToHtml` writes the nodes and marks the table lists as their
HTML elements, and keeps every other node whole: an element of class `adf-carry` holds the node's JSON in
`data-adf` and shows the node's content, its links included, so a reader of the page loses no
content. No stylesheet ships. The complete dialect:
@@ -602,7 +602,7 @@ content. No stylesheet ships. The complete dialect:
`htmlToAdf` reads that HTML back. It reads a carry element's node from its `data-adf`, and what the
element shows must be what `adfToHtml` shows for that node: an edit there would be lost, so it is
refused. It reads the HTML as a browser's `innerHTML` writes it too, and as a form post sends it: a raw `"` in text, `&nbsp;` for a no-break space, a raw `<` or `>` in an attribute value,
and `\r\n` for a line feed. Other HTML is refused as `unmappable-html`: another element, attribute or
`\r\n` for a line feed, and `open=""` on an expand's `<details>`, which reads as the same expand. Other HTML is refused as `unmappable-html`: another element, attribute or
escape, such as `<b>`, `<br/>` or `&#39;`, a lone `\r`, and HTML missing its final line feed.
A few causes, such as a `data-*` attribute its element does not take, are `unsupported-node-shape`
instead, and nesting past 500 levels is `unsupported-nesting-depth`. [Either
+10 -6
View File
@@ -512,8 +512,9 @@ An eighth panel (2026-11-14, three readers in the same roles; seven for indentat
For an `indentation` mark, five of seven picked `data-indent-level`; whether a `margin-left` style
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.
holding no other mark. The `style` attributes above work against that goal: a text colour, a
background colour, an alignment and a cell's `background`. They stand until `todo.md` item 188 spells
each without one.
## `htmlToAdf` also reads the dialect as a browser serializes it
@@ -527,10 +528,13 @@ 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. 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.
every element the dialect writes, later ones included.
One more difference is DOM state, not the algorithm's: a `<details>` its user opened carries `open=""`
after its other attributes. `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 -4
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>`; the `alignment` and `indentation` marks as on a paragraph |
| `heading`, `level` 1 to 6 | `<h1>…</h1>` to `<h6>…</h6>`, its `alignment` and `indentation` marks as a paragraph's |
| `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`, `<p data-indent-level="2">` for an `indentation` mark of `level` 2, 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 |
| `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 or one indentation of `level` 1 to 6;
- a paragraph or heading holding two marks, or a mark besides a `center` or `end` alignment and an 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,7 +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 |
| an expand's or nested expand's `<details>` | the same with `open=""` after its other attributes, which a browser writes for one its user opened; it reads as the same expand, the open state 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
+5 -1
View File
@@ -705,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="x">\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 open="" once, after its other attributes'],
['<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"'],
@@ -741,6 +741,10 @@ const pinnedRefusals: readonly (readonly [string, string])[] = [
['<h1 style="text-align:left">a</h1>\n', 'unmappable-html at /content/0: style on <h1> holds text-align:center or text-align:right'],
['<p data-indent-level="7">a</p>\n', 'unmappable-html at /content/0: data-indent-level on <p> holds a whole number from 1 to 6'],
['<h3 data-indent-level="">a</h3>\n', 'unmappable-html at /content/0: data-indent-level on <h3> holds a whole number from 1 to 6'],
['<p data-local-id="p1" data-indent-level="2">a</p>\n', 'unmappable-html at /content/0: <p> takes data-indent-level once, first, before its data-* attributes'],
['<p data-indent-level="2" data-indent-level="2">a</p>\n', 'unmappable-html at /content/0: <p> takes data-indent-level once, first, before its data-* attributes'],
['<p style="text-align:center" data-indent-level="2">a</p>\n', 'unmappable-html at /content/0: <p> takes data-indent-level once, first, before its data-* attributes'],
['<details class="adf-expand" open="" open="">\n<p>a</p>\n</details>\n', 'unmappable-html at /content/0: <details> takes open="" once, after its other attributes'],
['<p>a <span title="color:red">b</span></p>\n', 'unmappable-html at /content/0/content/1: a <span> of the dialect is a carry element, holding class="adf-carry" and then data-adf alone, or opens with class="adf-emoji", "adf-mention" or "adf-status": found "<span title=\\"color:red\\">"…'],
['<blockquote><p>a</p></blockquote>\n', 'unmappable-html at /content/0: <blockquote> holds </blockquote> straight after it, or a line feed and its first block: found "<p>a</p></blockquote>\\n"'],
['<ul><li>a</li></ul>\n', 'unmappable-html at /content/0: <ul> holds </ul> straight after it, or a line feed and its first item: found "<li>a</li></ul>\\n"'],
+3 -1
View File
@@ -244,7 +244,9 @@ function readDetails(html: string, tag: StartTag, place: Place, open: Open): Res
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 last = pairs.at(-1)
const opened = last?.[0] === 'open' && last[1] === ''
const data = readDataAttributes(opened ? pairs.slice(0, -1) : pairs, tag.name, blockNodes[type].attributes, ['title'])
const rest = opened ? pairs.slice(0, -1) : pairs
if (rest.some(([name]) => name === 'open')) return refused('unmappable-html', '<details> takes open="" once, after its other attributes', html, tag.start, place)
const data = readDataAttributes(rest, 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 -3
View File
@@ -10,9 +10,8 @@ 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 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)
const marked = type === 'paragraph' || type === 'heading'
const held = marked ? 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)
const inline = readInline(html, tag.end, place)
if (!inline.ok) return inline
+4 -2
View File
@@ -15,7 +15,7 @@ function alignments(): ReadonlyMap<string, string> {
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.
// 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 second mark, or a mark that no such attribute 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)
@@ -40,7 +40,9 @@ export function readTextBlockAttributes(pairs: readonly (readonly [string, strin
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)
const rest = mark === undefined ? pairs : pairs.slice(1)
if (rest.some(([name]) => name === indentAttribute)) return { fault: { code: 'unmappable-html', message: `<${element}> takes ${indentAttribute} once, first, before its data-* attributes` } }
const data = readDataAttributes(rest, element, vocabulary, written)
if (data.fault !== undefined) return data
return { value: { attrs: data.value, marks: mark === undefined ? [] : [mark.value] } }
}
+2 -4
View File
@@ -50,11 +50,9 @@
### 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`.
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:…"`.
The unreleased dialect writes four `style` attributes, which README goal 10 rules out: `style="text-align:center|right"` on a paragraph or heading, `<span style="color:…">`, `<mark style="background-color:…">` and a cell's `style="background-color:…"`.
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.
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.
A colour is any run of letters and digits after an optional `#`, so a class per colour cannot spell it. The likely spelling is a `data-*` attribute holding the value beside a class naming the element, and for 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, the `CHANGELOG.md` bullets that name the `style` spellings and `docs/decisions.md` §The HTML dialect, whose style lines this item replaces. The carry element `0.3.1` wrote still reads; the style spellings were never released, so `htmlToAdf` stops reading them.
### 46. Publish the bundle size in the README, failing the release pipeline when it drifts.