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:
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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 `<` or `>` (a browser from before the algorithm escaped th
|
||||
in both, ` ` 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
@@ -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 | ` ` |
|
||||
| `<` and `>` 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
|
||||
|
||||
@@ -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' }] } }
|
||||
}
|
||||
@@ -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', () => {
|
||||
|
||||
@@ -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,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'
|
||||
|
||||
@@ -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 & 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')
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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,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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user