3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-17 13:50:25 +01:00

Write emoji, status, date and URL card as HTML elements, not the carry

This commit is contained in:
2026-11-04 13:36:50 +01:00
committed by Lillem4n
parent 7ca6114f5d
commit 7c17447a87
14 changed files with 236 additions and 24 deletions
+5 -3
View File
@@ -8,14 +8,16 @@
to or from markdown, wrappers and forks aside; its second table lists other ecosystems'
libraries and Atlassian's own paths.
- `adfToHtml` writes ADF as HTML: paragraphs, headings, lists, quotes, code blocks, rules, hard
breaks, a centered, uncaptioned external image holding no attribute but its URL and alt, and `em`,
`strong`, `code` and links as their elements. A paragraph, heading, quote, list, list item, code block or
breaks, a centered, uncaptioned external image holding no attribute but its URL and alt, an
emoji, a status, a date and a card holding only a URL (`<span class="adf-emoji">`, `<span class="adf-status">`,
`<time class="adf-date">`, `<a class="adf-inline-card">`), and `em`, `strong`, `code` and links as
their elements. A paragraph, heading, quote, list, list item, code block or
rule writes its other attributes as `data-*` attributes, `localId` as `data-local-id`. Every other
node is an element of class `adf-carry` holding the node's JSON in `data-adf` and showing its
content, links included. Every URL is written as the ADF holds it,
`javascript:` included: sanitize HTML from an author you do not trust before showing it.
- `htmlToAdf` reads `adfToHtml`'s HTML back to the document it came from, a carry element from its
`data-adf`. It reads that HTML as a browser's `innerHTML` writes it too (a raw `"` in text,
`data-adf`, and those elements. It reads that HTML as a browser's `innerHTML` writes it too (a raw `"` in text,
`&nbsp;`, a raw `<` or `>` in an attribute value) and as a form post sends it (`\r\n` for each
line feed). It refuses any other HTML, including an edit to what a carry element shows, with the
codes README §The calls lists.
+2
View File
@@ -516,8 +516,10 @@ content. No stylesheet ships. The complete dialect:
| `blockquote` | `<blockquote>` |
| `bulletList`, `orderedList`, `listItem` | `<ul>`, `<ol>`, `<ol start="3">` for an `order` of 3, and `<li>`; an item's first paragraph stands bare, `<li>Bolt</li>`, or as `<li><p data-local-id="p1">Bolt</p></li>` where it holds an attribute |
| `codeBlock` | `<pre><code class="language-js">`, no `class` without a language |
| `date`, `emoji`, `status` | `<time class="adf-date" datetime="2025-08-25" data-timestamp="…">2025-08-25</time>`, `<span class="adf-emoji" data-id="1f389" data-short-name=":tada:">🎉</span>`, `<span class="adf-status" data-color="yellow">In review</span>` |
| `hardBreak` | `<br>` |
| `heading` | `<h1>` to `<h6>` |
| `inlineCard` holding a `url` | `<a class="adf-inline-card" href="…">…</a>` |
| `link` | `<a href="…" title="…">` |
| `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; an image holding such an attribute, as editor-written ones do, rides the carry element |
| `paragraph` | `<p>` |
+20 -2
View File
@@ -442,8 +442,26 @@ it joins the second panel's `<a>` to that portable spelling.
Inside a carry element, a card a link marks links to the link's target, and shows its own URL as its
text where it has one, so both stay. A card showing only its name keeps its URL in `data-adf` alone.
Atlassian's schema gives no card a link mark, so only a hand-built document meets this;
`todo.md` item 133 ends it for inline cards, in 0.3.0. Recorded 2026-10-24 without a panel of its
own: it puts the second panel's `<a>` around the text a card shows.
`todo.md` item 133 ends it for a card holding `data` or a link mark, in 0.3.0. Recorded 2026-10-24
without a panel of its own: it puts the second panel's `<a>` around the text a card shows.
A fifth panel (2026-11-04, three readers in the same roles, then four more for what the first three
split on) picked how an emoji, status, date and inline card are written, the nodes the carry held.
The first three picked each of these 3 of 3:
- an emoji as `<span class="adf-emoji" data-id="1f389" data-short-name=":tada:">🎉</span>`, its text
the content, over an `<img>`;
- a status as `<span class="adf-status" data-color="yellow">In review</span>`;
- a card holding a URL as `<a class="adf-inline-card" href="https://example.com/spec">https://example.com/spec</a>`,
over a `data-url` beside the `href`.
Seven readers picked a date as
`<time class="adf-date" datetime="2025-08-25" data-timestamp="1756080000000">2025-08-25</time>`,
5 of 7: the day for people, the exact timestamp for scripts. Two splits stay open and ride the carry,
`todo.md` item 133: a mention's `data-id`, `data-access-level` and `data-user-type` drew 4 of 7, over
`data-mention-id` 2 and `data-user-id` 1; a card holding `data` and no URL drew `<a … href data-data>`
3, `<a … data-card>` 2 and `<span … data-data>` 2. The link-marked card's spelling hangs on that
one. So a card holding `data` or a mark rides the carry too.
## `htmlToAdf` also reads the dialect as a browser serializes it
+13
View File
@@ -35,11 +35,21 @@ block's `data-*` attributes stand on its `<pre>`.
| ADF | HTML |
| --- | --- |
| `date` | `<time class="adf-date" datetime="2025-08-25" data-timestamp="1756080000000">2025-08-25</time>`, the day in UTC; its other attributes after the class, as below |
| `em`, `strong`, `code` | `<em>`, `<strong>`, `<code>` around the text |
| `emoji` | `<span class="adf-emoji" data-id="1f389" data-short-name=":tada:">🎉</span>`, its `text` the content |
| `hardBreak` | `<br>` |
| `inlineCard`, holding a `url` | `<a class="adf-inline-card" href="https://example.com/spec">https://example.com/spec</a>` |
| `link`, holding `href` and an optional `title` | `<a href="…" title="…">` around the text |
| `status` | `<span class="adf-status" data-color="yellow">In review</span>`, its `text` the content |
| `text` | its text, escaped |
A `date`, `emoji`, `inlineCard` or `status` writes each other attribute its type holds as a
`data-*` attribute, named and sorted as on a block, `data-local-id` among them. It rides the carry
where it holds a mark, `content`, a key or value its type does not hold, or an empty `attrs`; where
it has no text to show (an emoji or status with no `text`, a date whose `timestamp` names no day, a
card with no `url`); and where a card holds `data`. A `mention` rides the carry.
A text node's marks nest in the order its `marks` array lists them, the first outermost:
`<strong><em>manual</em></strong>`. Each text node writes its own elements, so two text nodes a link
marks are two `<a>` elements.
@@ -138,6 +148,9 @@ that node in either spelling: an edit there would be lost, so it is `unmappable-
- Any other HTML is `unmappable-html`: another element, attribute or escape, attributes in another
order, a block on the line of another, a carriage return not followed by a line feed, or
non-empty HTML not ending in a line feed.
- An emoji, status, date or card element reads back as its node only when it shows what `adfToHtml`
writes for it: the text is not empty, a date's `datetime` and text are the day its `data-timestamp`
names, and a card's `href` and text are one URL. Another shape is `unmappable-html`.
- A `data-*` attribute that its element does not take, such as `data-level` on `<h1>`, or that holds
a value outside its attribute's kind or not written as compact JSON, is `unsupported-node-shape`.
- A carry element's `data-adf` holding invalid JSON is `unmappable-html`. JSON that is no ADF node,
+36 -5
View File
@@ -140,6 +140,37 @@ test('carries every other node in an adf-carry element holding its JSON', () =>
assert.equal(html(adfToHtml(document(paragraph(text('Ask '), mention)))), '<p>Ask <span class="adf-carry" data-adf="{&quot;attrs&quot;:{&quot;id&quot;:&quot;5b10a2&quot;,&quot;text&quot;:&quot;@Mikael&quot;},&quot;type&quot;:&quot;mention&quot;}">@Mikael</span></p>\n')
})
test('writes an emoji, status, date and URL card as their elements, their attributes data-* sorted by name', () => {
const inline = (node: AdfNode): string => html(adfToHtml(document(paragraph(text('See '), node))))
assert.equal(inline({ attrs: { id: '1f389', localId: 'e1', shortName: ':tada:', text: '🎉' }, type: 'emoji' }), '<p>See <span class="adf-emoji" data-id="1f389" data-local-id="e1" data-short-name=":tada:">🎉</span></p>\n')
assert.equal(inline({ attrs: { text: '<3' }, type: 'emoji' }), '<p>See <span class="adf-emoji">&lt;3</span></p>\n')
assert.equal(inline({ attrs: { color: 'yellow', localId: 's1', style: 'bold', text: 'In review' }, type: 'status' }), '<p>See <span class="adf-status" data-color="yellow" data-local-id="s1" data-style="bold">In review</span></p>\n')
assert.equal(inline({ attrs: { localId: 'd1', timestamp: '1756080000000' }, type: 'date' }), '<p>See <time class="adf-date" datetime="2025-08-25" data-local-id="d1" data-timestamp="1756080000000">2025-08-25</time></p>\n')
assert.equal(inline({ attrs: { localId: 'c1', url: 'https://example.com/spec?a=1&b=2' }, type: 'inlineCard' }), '<p>See <a class="adf-inline-card" href="https://example.com/spec?a=1&amp;b=2" data-local-id="c1">https://example.com/spec?a=1&amp;b=2</a></p>\n')
})
test('carries an emoji, status, date or URL card the element cannot hold', () => {
const carried = (node: AdfNode): boolean => html(adfToHtml(document(paragraph(node)))).includes('adf-carry')
const comment: AdfMark = { attrs: { annotationType: 'inlineComment', id: 'c1' }, type: 'annotation' }
assert.equal(carried({ attrs: { text: '🎉' }, marks: [comment], type: 'emoji' }), true)
assert.equal(carried({ attrs: { shortName: ':tada:' }, type: 'emoji' }), true)
assert.equal(carried({ attrs: { text: '' }, type: 'emoji' }), true)
assert.equal(carried({ attrs: { text: 'a\u0001' }, type: 'emoji' }), true)
assert.equal(carried({ attrs: { size: 'big', text: '🎉' }, type: 'emoji' }), true)
assert.equal(carried({ attrs: { id: 5, text: '🎉' }, type: 'emoji' }), true)
assert.equal(carried({ attrs: { text: '🎉' }, content: [], type: 'emoji' }), true)
assert.equal(carried({ attrs: { color: 'red' }, type: 'status' }), true)
assert.equal(carried({ attrs: { timestamp: 'soon' }, type: 'date' }), true)
assert.equal(carried({ attrs: { timestamp: 1756080000000 }, type: 'date' }), true)
assert.equal(carried({ type: 'date' }), true)
assert.equal(carried({ attrs: { data: { name: 'Roadmap' } }, type: 'inlineCard' }), true)
assert.equal(carried({ attrs: { data: { name: 'Roadmap' }, url: 'https://example.com/' }, type: 'inlineCard' }), true)
assert.equal(carried({ attrs: { url: 'https://example.com/' }, marks: [{ attrs: { href: 'https://example.org/' }, type: 'link' }], type: 'inlineCard' }), true)
assert.equal(carried({ attrs: { url: '' }, type: 'inlineCard' }), true)
assert.equal(carried({ attrs: { url: 'https://example.com/\u0001' }, type: 'inlineCard' }), true)
assert.equal(carried({ attrs: { id: '5b10a2', text: '@Mikael' }, type: 'mention' }), true)
})
test('shows each block a carried node holds as a paragraph in a div', () => {
const panel: AdfNode = { attrs: { panelType: 'info' }, content: [paragraph(text('Check the collation.')), paragraph(text('Then import.'))], type: 'panel' }
assert.equal(shown(html(adfToHtml(document(panel)))), '<p>Check the collation.</p><p>Then import.</p>')
@@ -199,11 +230,11 @@ test('shows a code block in a span carry as text, its line feeds line breaks', (
test('shows the content a carried node holds in an attribute, and links a card or an external image to its URL', () => {
const inline = (node: AdfNode): string => shown(html(adfToHtml(document(paragraph(node)))))
assert.equal(inline({ attrs: { timestamp: '1700000000000' }, type: 'date' }), '2023-11-14')
assert.equal(inline({ attrs: { shortName: ':smile:', text: '😄' }, type: 'emoji' }), '😄')
assert.equal(inline({ attrs: { timestamp: '1700000000000' }, marks: [{ attrs: { annotationType: 'inlineComment', id: 'c1' }, type: 'annotation' }], type: 'date' }), '2023-11-14')
assert.equal(inline({ attrs: { shortName: ':smile:', text: '😄' }, marks: [{ attrs: { annotationType: 'inlineComment', id: 'c1' }, type: 'annotation' }], type: 'emoji' }), '😄')
assert.equal(inline({ attrs: { id: '5b10a2' }, type: 'mention' }), '@5b10a2')
assert.equal(inline({ attrs: { color: 'green', text: 'Done' }, type: 'status' }), 'Done')
assert.equal(inline({ attrs: { url: 'https://example.com/<card>' }, type: 'inlineCard' }), '<a href="https://example.com/&lt;card&gt;">https://example.com/&lt;card&gt;</a>')
assert.equal(inline({ attrs: { color: 'green', text: 'Done' }, marks: [{ attrs: { annotationType: 'inlineComment', id: 'c1' }, type: 'annotation' }], type: 'status' }), 'Done')
assert.equal(inline({ attrs: { url: 'https://example.com/<card>' }, marks: [{ attrs: { annotationType: 'inlineComment', id: 'c1' }, type: 'annotation' }], type: 'inlineCard' }), '<a href="https://example.com/&lt;card&gt;">https://example.com/&lt;card&gt;</a>')
assert.equal(inline({ attrs: { data: { name: 'Roadmap' } }, type: 'inlineCard' }), 'Roadmap')
assert.equal(inline(text('underlined', { type: 'underline' })), 'underlined')
const image = (media: AdfNode): string => shown(html(adfToHtml(document({ attrs: { layout: 'wide' }, content: [media], type: 'mediaSingle' }))))
@@ -296,7 +327,7 @@ test('writes every URL as the ADF holds it, escaped, whatever its scheme', () =>
assert.equal(linked('data:text/html,<b>x</b>'), '<p><a href="data:text/html,&lt;b&gt;x&lt;/b&gt;">x</a></p>\n')
const image: AdfNode = { attrs: { layout: 'center' }, content: [{ attrs: { type: 'external', url: 'vbscript:x' }, type: 'media' }], type: 'mediaSingle' }
assert.equal(html(adfToHtml(document(image))), '<p><img src="vbscript:x"></p>\n')
assert.equal(shown(html(adfToHtml(document(paragraph({ attrs: { url: 'javascript:alert(1)' }, type: 'inlineCard' }))))), '<a href="javascript:alert(1)">javascript:alert(1)</a>')
assert.equal(html(adfToHtml(document(paragraph({ attrs: { url: 'javascript:alert(1)' }, type: 'inlineCard' })))), '<p><a class="adf-inline-card" href="javascript:alert(1)">javascript:alert(1)</a></p>\n')
})
test('writes a container holding no content key as its element holding nothing', () => {
+3
View File
@@ -4,6 +4,7 @@ import { carriedInline } from './carry-element.ts'
import { elementOfMark } from '../mark-elements.ts'
import { holdsOnlyAttributes, isSpellableText, isUnmarkedSpellableText, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
import { linkAttrs } from '../../adf/mark-attributes.ts'
import { nodeElement } from './node-element.ts'
import { success, type ConvertErrorPath, type Result } from '../../result.ts'
import { writableValue } from '../escaping.ts'
@@ -25,6 +26,8 @@ export function inlineHtml(nodes: readonly AdfNode[], path: ConvertErrorPath): R
function tryInlineNode(node: AdfNode): string | undefined {
if (node.type === 'hardBreak') return holdsOnlyAttributes(node, []) && nodeContent(node).length === 0 ? '<br>' : undefined
const element = nodeElement(node)
if (element !== undefined) return element
const text = isSpellableText(node) ? writableText(node.text) : undefined
if (text === undefined) return undefined
const marks = nodeMarks(node)
+18
View File
@@ -0,0 +1,18 @@
import type { AdfNode } from '../../adf/document.ts'
import { dataAttributes } from '../data-attributes.ts'
import { elementOfNodeType } from '../node-element.ts'
import { nodeAttrs } from '../../adf/document.ts'
import { shownText } from '../../adf/shown-text.ts'
import { writableValue } from '../escaping.ts'
// `undefined` where the node is no emoji, status, date or URL card, or holds what its element cannot write: it rides the carry.
export function nodeElement(node: AdfNode): string | undefined {
const model = elementOfNodeType(node.type)
if (model === undefined || node.content !== undefined) return undefined
const data = dataAttributes(node, model.vocabulary, model.content === undefined ? [] : [model.content])
const held = model.content === undefined ? shownText(node) : nodeAttrs(node)[model.content]
const shown = typeof held === 'string' && held !== '' ? writableValue(held) : undefined
if (data === undefined || shown === undefined) return undefined
const leading = model.leading === undefined ? '' : ` ${model.leading}="${shown}"`
return `<${model.element} class="${model.class}"${leading}${data}>${shown}</${model.element}>`
}
+31
View File
@@ -0,0 +1,31 @@
import type { AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
import { inlineNodeModel } from '../adf/inline-nodes.ts'
// An inline node HTML writes as its own element instead of the carry (docs/decisions.md §The HTML dialect). `content` is the attribute its text is, none for a date, whose text is the day its `timestamp` falls on; `leading` is the attribute standing first after the class, holding that same text.
export type NodeElement = {
class: string
content: string | undefined
element: 'a' | 'span' | 'time'
leading: 'datetime' | 'href' | undefined
vocabulary: AttributeVocabulary
}
const nodeElements: Readonly<Record<string, NodeElement>> = {
date: { class: 'adf-date', content: undefined, element: 'time', leading: 'datetime', vocabulary: attributesOf('date') },
emoji: { class: 'adf-emoji', content: 'text', element: 'span', leading: undefined, vocabulary: attributesOf('emoji') },
// A card's `data` is not written yet, so a card holding it rides the carry.
inlineCard: { class: 'adf-inline-card', content: 'url', element: 'a', leading: 'href', vocabulary: { localId: 'string', url: 'string' } },
status: { class: 'adf-status', content: 'text', element: 'span', leading: undefined, vocabulary: attributesOf('status') },
}
function attributesOf(type: string): AttributeVocabulary {
return inlineNodeModel(type)?.attributes ?? {}
}
export function elementOfNodeType(type: string): NodeElement | undefined {
return Object.hasOwn(nodeElements, type) ? nodeElements[type] : undefined
}
export function nodeTypeOfElement(element: string, className: string): [string, NodeElement] | undefined {
return Object.entries(nodeElements).find(([, candidate]) => candidate.element === element && candidate.class === className)
}
+45
View File
@@ -191,6 +191,29 @@ test('reads a carry element holding a node HTML writes as its own element as tha
assert.deepEqual(read(htmlToAdf(`<ul>\n<li>\n${carry('div', paragraph(text('x')), '<p>x</p>')}\n</li>\n</ul>\n`)), document({ content: [item(paragraph(text('x')))], type: 'bulletList' }))
})
test('reads an emoji, status, date and URL card from their elements', () => {
const inline = (node: AdfNode): AdfDocument | string => read(htmlToAdf(adfToHtmlText(document(paragraph(text('See '), node)))))
const nodes: AdfNode[] = [
{ attrs: { id: '1f389', localId: 'e1', shortName: ':tada:', text: '🎉' }, type: 'emoji' },
{ attrs: { text: '<3 &' }, type: 'emoji' },
{ attrs: { color: 'yellow', localId: 's1', style: 'bold', text: 'In "review"' }, type: 'status' },
{ attrs: { localId: 'd1', timestamp: '1756080000000' }, type: 'date' },
{ attrs: { localId: 'c1', url: 'https://example.com/spec?a=1&b=2' }, type: 'inlineCard' },
]
for (const node of nodes) assert.deepEqual(inline(node), document(paragraph(text('See '), node)))
assert.deepEqual(read(htmlToAdf('<p><span class="adf-emoji">a&nbsp;&quot;b</span></p>\n')), document(paragraph({ attrs: { text: 'a\u00a0"b' }, type: 'emoji' })))
})
test('reads a carry element holding an emoji, status, date or URL card as that node', () => {
const emoji: AdfNode = { attrs: { text: '🎉' }, type: 'emoji' }
assert.deepEqual(read(htmlToAdf(`<p>${carry('span', emoji, '🎉')}</p>\n`)), document(paragraph(emoji)))
})
function adfToHtmlText(doc: AdfDocument): string {
const written = adfToHtml(doc)
return written.ok ? written.value : written.error.message
}
// Each group's cases, the HTML and its refusal.
const refusals: Readonly<Record<string, readonly (readonly [string, string])[]>> = {
'refuses block shapes adfToHtml would not write': [
@@ -240,6 +263,28 @@ const refusals: Readonly<Record<string, readonly (readonly [string, string])[]>>
[`<p>a</p>\n${carry('div', panel, '<p>Check the <b>collation</b>.</p>')}\n`, 'unmappable-html at /content/1 line 2 offset 9'],
[`<p>Ask ${carry('span', mention, '')}</p>\n`, 'unmappable-html at /content/0/content/1 line 1 offset 0'],
],
'refuses an emoji, status, date or URL card element that is not as adfToHtml writes it': [
['<p><span class="adf-emoji"></span></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji">a<b>b</b></span></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji">a</p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji">a&b</span></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji" data-short-name=":a:" data-id="1">a</span></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji" data-size="big">a</span></p>\n', 'unsupported-node-shape at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji" data-text="a">a</span></p>\n', 'unsupported-node-shape at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-emoji" id="x">a</span></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><span class="adf-status" class="adf-status">a</span></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><time class="adf-date" data-timestamp="1756080000000">2025-08-25</time></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><time class="adf-date" datetime="2025-08-26" data-timestamp="1756080000000">2025-08-26</time></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><time class="adf-date" datetime="2025-08-25" data-timestamp="1756080000000">Today</time></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><time class="adf-date" datetime="2025-08-25">2025-08-25</time></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><time class="adf-date" datetime="x" data-timestamp="x">x</time></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><time datetime="2025-08-25">2025-08-25</time></p>\n', 'unmappable-html at /content/0 line 1 offset 0'],
['<p><a class="adf-inline-card" href="https://example.com/">Spec</a></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><a class="adf-inline-card">https://example.com/</a></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><a class="adf-inline-card" href="">a</a></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><a class="adf-inline-card" href="https://example.com/" title="t">https://example.com/</a></p>\n', 'unmappable-html at /content/0/content/0 line 1 offset 0'],
['<p><a class="adf-inline-card" href="https://example.com/" data-data="{}">https://example.com/</a></p>\n', 'unsupported-node-shape at /content/0/content/0 line 1 offset 0'],
],
'refuses the document\'s carry anywhere but as the whole document, a line feed ending it': [
[documentCarry, 'unmappable-html at / line 1 offset 0'],
[`${documentCarry}\n\n`, `unmappable-html at / line 2 offset ${documentCarry.length + 1}`],
+2 -2
View File
@@ -7,10 +7,10 @@ import { carryContent } from '../carry-content.ts'
import { centeredImage, externalMedia } from '../../adf/plain-image.ts'
import { containerElements, headingElements, headingLevel, readListStart, type ContainerType } from '../block-elements.ts'
import { firstParagraphForm } from '../first-paragraph.ts'
import { foundAt, misread, positionIn, readStartTag, refused, startTagName, type Place, type ReadNode, type StartTag } from './source.ts'
import { foundAt, misread, misspelledText, positionIn, readStartTag, refused, startTagName, type Place, type ReadNode, type StartTag } from './source.ts'
import { largestNesting } from '../../nesting.ts'
import { misspelledAt, unescapedValue } from '../escaping.ts'
import { misspelledText, readInline } from './inline.ts'
import { readInline } from './inline.ts'
import { nodeAttrs } from '../../adf/document.ts'
import { notAString } from '../../not-a-string.ts'
import { positioned, success } from '../../result.ts'
+4 -5
View File
@@ -1,12 +1,13 @@
import type { AdfMark, AdfNode } from '../../adf/document.ts'
import type { ParseError, Result } from '../../result.ts'
import { foundAt, misread, readStartTag, refused, type Place, type ReadNode, type StartTag } from './source.ts'
import { foundAt, misread, misspelledText, readStartTag, refused, type Place, type ReadNode, type StartTag } from './source.ts'
import { largestNesting } from '../../nesting.ts'
import { linkMarkFrom } from '../../adf/mark-attributes.ts'
import { markOfElement } from '../mark-elements.ts'
import { misspelledAt, unescapedValue } from '../escaping.ts'
import { readAnchorAttributes } from '../anchor-element.ts'
import { readCarry } from './carry-element.ts'
import { readNodeElement } from './node-element.ts'
import { success } from '../../result.ts'
// The inline nodes from `index` up to the first tag opening none, which the caller reads.
@@ -28,6 +29,8 @@ export function readInline(html: string, index: number, place: Place): Result<{
function readTagged(html: string, index: number, place: Place): ReadNode | undefined {
const tag = readStartTag(html, index)
if (tag?.name === 'br' && tag.attributes.length === 0) return success({ end: tag.end, node: { type: 'hardBreak' } })
const element = tag === undefined ? undefined : readNodeElement(html, tag, place)
if (element !== undefined) return element
if (tag?.name === 'span') return readCarry(html, tag, 'span', largestNesting, place)
return tag !== undefined && markOf(tag) !== undefined ? readMarked(html, index, place) : undefined
}
@@ -69,10 +72,6 @@ function readText(html: string, index: number, marks: AdfMark[], place: Place):
return success({ end, node: marks.length === 0 ? { text, type: 'text' } : { marks, text, type: 'text' } })
}
export function misspelledText<T>(html: string, index: number, place: Place): Result<T, ParseError> {
return refused('unmappable-html', `text escapes & as &amp;, < as &lt; and > as &gt;, and holds no character HTML cannot hold: ${foundAt(html, index)}`, html, index, place)
}
function markOf(tag: StartTag): AdfMark | undefined {
if (tag.name === 'a') {
const link = readAnchorAttributes(tag.attributes)
+34
View File
@@ -0,0 +1,34 @@
import type { AdfAttributes, AdfNode } from '../../adf/document.ts'
import { foundAt, misspelledText, refused, type Place, type ReadNode, type StartTag } from './source.ts'
import { nodeTypeOfElement, type NodeElement } from '../node-element.ts'
import { readDataAttributes } from '../data-attributes.ts'
import { shownText } from '../../adf/shown-text.ts'
import { success } from '../../result.ts'
import { unescapedValue } from '../escaping.ts'
// `undefined` where the tag opens no emoji, status, date or URL card element; one that does reads as the node `nodeElement` wrote it from, or is refused.
export function readNodeElement(html: string, tag: StartTag, place: Place): ReadNode | undefined {
const [kind, ...rest] = tag.attributes
const found = kind?.[0] === 'class' ? nodeTypeOfElement(tag.name, kind[1]) : undefined
if (found === undefined) return undefined
const [type, model] = found
if (model.leading !== undefined && rest[0]?.[0] !== model.leading) return refused('unmappable-html', `<${tag.name} class="${model.class}"> holds ${model.leading} first, before its data-* attributes: ${foundAt(html, tag.start)}`, html, tag.start, place)
const data = readDataAttributes(rest, tag.name, model.vocabulary, model.content === undefined ? [] : [model.content], model.leading)
if (data.fault !== undefined) return refused(data.fault.code, data.fault.message, html, tag.start, place)
const closer = `</${tag.name}>`
const stop = html.indexOf('<', tag.end)
const end = stop < 0 ? html.length : stop
const shown = unescapedValue(html.slice(tag.end, end), 'text')
if (shown === undefined) return misspelledText(html, tag.end, place)
if (!html.startsWith(closer, end)) return refused('unmappable-html', `<${tag.name} class="${model.class}"> holds its text, then ${closer}: ${foundAt(html, end)}`, html, end, place)
const node = nodeOf(type, model, data.value, shown)
const expected = model.content === undefined ? shownText(node) : shown
if (expected === undefined || expected === '' || shown !== expected || (model.leading !== undefined && rest[0]?.[1] !== expected)) {
return refused('unmappable-html', `<${tag.name} class="${model.class}"> shows what adfToHtml writes for its node, ${model.leading === undefined ? '' : `${model.leading} the same, `}then ${closer}; to change the node, edit its data-* attributes: ${foundAt(html, tag.end)}`, html, tag.end, place)
}
return success({ end: end + closer.length, node })
}
function nodeOf(type: string, model: NodeElement, data: AdfAttributes, shown: string): AdfNode {
return { attrs: model.content === undefined ? data : { ...data, [model.content]: shown }, type }
}
+4
View File
@@ -45,6 +45,10 @@ export function foundAt(html: string, index: number): string {
return `found ${spelled}${index + found.length < html.length ? '…' : ''}`
}
export function misspelledText<T>(html: string, index: number, place: Place): Result<T, ParseError> {
return refused('unmappable-html', `text escapes & as &amp;, < as &lt; and > as &gt;, and holds no character HTML cannot hold: ${foundAt(html, index)}`, html, index, place)
}
// The position of the start of `line` in `html` as handed in, for a line counted after each `\r\n` became a line feed.
export function positionIn(html: string, { line }: SourcePosition): SourcePosition {
let offset = 0
+19 -7
View File
@@ -12,10 +12,10 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 133 | 0.3.0 | | question | **Write mentions, and inline cards holding `data` or a link mark, as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 3 | 3.0 |
| 163 | 0.3.0 | | | **Gather a corpus of real-world ADF documents from public Jira and Confluence sites, each recording where it came from and under what licence.** | 3 | 2 | 4 | 7 | 4 | 6 by 3 | 3.0 |
| 164 | 0.3.0 | 163 | | **Publish a feature table setting chosen corpus examples beside what each call writes for them, readable at a glance by people and parseable by LLMs, and kept current by the gate.** | 3 | 2 | 1 | 4 | 5 | 3 by 6, 6 by 4 | 6.2 |
| 165 | 0.3.0 | 164 | | **Have a reader panel seated from `## Audience` judge each feature-table row reasonable or not, and file an item for each row it rejects.** | 2 | 2 | 1 | 3 | 3 | 6 by 5 | 7.5 |
| 133 | 0.3.0 | | decision | **Write mentions, emoji, dates, statuses and inline cards as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 3 | 3.0 |
| 132 | 0.3.0 | | | **Write tables as `<table>` in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 5 | 6 by 4 | 2.4 |
| 73 | 0.3.0 | 132, 133, 163, 165 | | **Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions.** | 1 | 2 | 2 | 3 | 2 | 3 by 8 | 16.9 |
| 72 | 0.3.0 | 132, 133 | decision | **Re-create `gitea.larvit.se/larvit/adf-codec` as a read-only pull mirror of GitHub, its issues and Actions off and its description pointing at GitHub.** | 1 | 2 | 1 | 2 | 1 | 3 by 1 | 2.5 |
@@ -69,6 +69,24 @@
## Details
### 133. Write mentions, and inline cards holding `data` or a link mark, as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.
The fifth writer panel (`docs/decisions.md` §The HTML dialect) did not reach 5 of 7 on two
spellings, so mentions and cards holding `data` ride the carry until the maintainer settles them.
Class: the HTML dialect's spellings. Earlier entries: `data-*` named as HTML's `dataset` names it,
`data-local-id` over `data-adf-local-id`. Candidates, each following those entries:
- a mention as `<span class="adf-mention" data-access-level="CONTAINER" data-id="5b10a2" data-user-type="DEFAULT">@Mikael</span>` (4 of 7; `data-mention-id` drew 2);
- a card holding `data` and no URL as `<a class="adf-inline-card" href="https://example.com/plan" data-data="{…}">Release plan</a>`, `href` the URL its `data` holds (3 of 7; `data-card` drew 2, a `<span>` without `href` 2).
Where a link marks a card, both the link's target and the card's URL stay in sight, a card showing
only its name included.
Candidate entry for §The HTML dialect, if the leading spellings stand: "A mention is
`<span class="adf-mention" data-access-level data-id data-user-type>` showing its text. A card
holding `data` and no URL is `<a class="adf-inline-card" href data-data>`, `href` the URL its `data`
holds, showing its name." The instance it yields for the example above: `<a class="adf-inline-card" href="https://example.com/plan" data-data="{…}">Release plan</a>`.
### 163. Gather a corpus of real-world ADF documents from public Jira and Confluence sites, each recording where it came from and under what licence.
The maintainer asked for it on 2026-11-03: paragraphs such as bold around a code span or italics over a line break occur all the time, and the project holds no evidence of what real documents contain. Find public sites that serve ADF without an account, such as Jira Cloud issues on public projects through the REST v3 API, and fetch enough documents to cover the node and mark types the flavour spells.
@@ -86,12 +104,6 @@ The examples are picked by an explicit list of corpus ids, each with a one-line
The panel follows AGENTS.md §7's reader-panel rule: readers, one per persona the row serves, see only `## Audience` and the row, and say whether the output is what they expect. A rejected row becomes an item naming the expected output. The verdicts land in `docs/decisions.md`.
### 133. Write mentions, emoji, dates, statuses and inline cards as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.
A writer panel picks the elements, classes and `data-*` attributes. Where a link marks a card, both
the link's target and the card's URL stay in sight, a card showing only its name included
(`docs/decisions.md` §The HTML dialect).
### 132. Write tables as `<table>` in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.
Header cells as `<th>`; a cell's span, width and background in HTML attributes or `data-*`, as a