` | +| any other node, or a node holding what its element cannot | `
its content
`, text a link marks as a link, a mention,
+ status or emoji by its text, a date as `2026-09-13` in UTC, a card as a link to its URL, an image as
+ a link to it, and an expand by its title. What it cannot show leaves a note, `(image)`.
- A link's or image's URL is written as the ADF holds it, `javascript:` included: sanitize the
HTML before showing a document from an author you do not trust.
diff --git a/browser-tests/convert-corpus.js b/browser-tests/convert-corpus.js
index c9274c2..ffc5493 100644
--- a/browser-tests/convert-corpus.js
+++ b/browser-tests/convert-corpus.js
@@ -1,5 +1,5 @@
try {
- const { adfToLosslessMarkdown, isAdfDocument, losslessMarkdownToAdf } = await import('/dist/index.js')
+ const { adfToHtml, adfToLosslessMarkdown, isAdfDocument, losslessMarkdownToAdf } = await import('/dist/index.js')
// WebDriver's JSON reads -0 back as 0, so a document crosses as JSON text with -0 tagged; run.js revives it.
const spelled = (result) => (result.ok ? { ok: true, value: JSON.stringify(result.value, (_, value) => (Object.is(value, -0) ? '\u0000-0' : value)) } : result)
window.convertCorpus = (corpus) => ({
@@ -8,7 +8,7 @@ try {
realPayloads: corpus.realPayloads.map(({ json, name }) => {
const adf = JSON.parse(json)
const emitted = adfToLosslessMarkdown(adf)
- return { emitted, isDocument: isAdfDocument(adf), name, parsed: emitted.ok ? spelled(losslessMarkdownToAdf(emitted.value)) : undefined }
+ return { emitted, html: adfToHtml(adf), isDocument: isAdfDocument(adf), name, parsed: emitted.ok ? spelled(losslessMarkdownToAdf(emitted.value)) : undefined }
}),
roundTrip: corpus.roundTrip.map(({ json, markdown, name }) => {
const adf = JSON.parse(json)
diff --git a/browser-tests/run.js b/browser-tests/run.js
index b0652df..ac9d6f1 100644
--- a/browser-tests/run.js
+++ b/browser-tests/run.js
@@ -3,6 +3,8 @@ import { createServer } from 'node:http'
import { extname, join } from 'node:path'
import { readFileSync, readdirSync } from 'node:fs'
+import { adfToHtml } from '../dist/index.js'
+
const contentTypes = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript' }
const driver = 'http://127.0.0.1:4444'
const repoRoot = join(import.meta.dirname, '..')
@@ -130,6 +132,7 @@ for (const [index, { json, name }] of corpus.realPayloads.entries()) {
assert.ok(result.emitted.ok, `it did not emit — ${refusal(result.emitted)}`)
assert.ok(result.parsed.ok, `it did not parse back — ${refusal(result.parsed)}`)
assert.deepEqual(revived(result.parsed.value), JSON.parse(json))
+ assert.deepEqual(result.html, adfToHtml(JSON.parse(json)), 'it wrote other HTML than Node wrote')
})
}
diff --git a/ci.sh b/ci.sh
index c18296f..7a16935 100755
--- a/ci.sh
+++ b/ci.sh
@@ -7,34 +7,38 @@ leg "install ($node_image)" in_image "$node_image" npm ci
leg "typecheck ($node_image)" in_image "$node_image" npm run typecheck
leg "lint ($node_image)" in_image "$node_image" npm run lint
-# The boundaries pass by finding nothing, so probe that each still fires: oxlint bumps automerge on green.
+# The boundaries pass by finding nothing, so probe that each still fires: oxlint bumps automerge on green. Each line is a probe and the import a boundary refuses it.
+boundary_probes="src/adf/boundary-probe.ts ../markdown/flavour.ts
+src/adf/boundary-probe-html.ts ../html/emit/adf-to-html.ts
+src/html/boundary-probe.ts ../markdown/flavour.ts
+src/markdown/boundary-probe-html.ts ../html/emit/adf-to-html.ts
+src/markdown/directive/boundary-probe.ts ../parse/blocks.ts
+src/markdown/directive/boundary-probe-emit.ts ../emit/image.ts
+src/markdown/directive/boundary-probe-html.ts ../../html/emit/adf-to-html.ts
+src/markdown/emit/boundary-probe.ts ../portable/conventions.ts
+src/markdown/emit/boundary-probe-html.ts ../../html/emit/adf-to-html.ts
+src/markdown/parse/boundary-probe.ts ../emit/adf-to-markdown.ts
+src/markdown/parse/boundary-probe-html.ts ../../html/emit/adf-to-html.ts
+src/markdown/parse/boundary-probe-portable.ts ../portable/conventions.ts"
+
boundaries_fire() {
- local adf=src/adf/boundary-probe.ts adf_html=src/adf/boundary-probe-html.ts allowed=src/markdown/parse/boundary-probe-allowed.ts directive=src/markdown/directive/boundary-probe.ts directive_emit=src/markdown/directive/boundary-probe-emit.ts directive_html=src/markdown/directive/boundary-probe-html.ts emit=src/markdown/emit/boundary-probe.ts emit_html=src/markdown/emit/boundary-probe-html.ts html=src/html/boundary-probe.ts lint_log markdown=src/markdown/boundary-probe-html.ts parse=src/markdown/parse/boundary-probe.ts parse_html=src/markdown/parse/boundary-probe-html.ts parse_portable=src/markdown/parse/boundary-probe-portable.ts
- local probes="$adf $adf_html $allowed $directive $directive_emit $directive_html $emit $emit_html $html $markdown $parse $parse_html $parse_portable"
+ local allowed=src/markdown/parse/boundary-probe-allowed.ts lint_log probe probes target
+ probes=$(cut -d ' ' -f 1 <<< "$boundary_probes" | tr '\n' ' ') &&
lint_log=$(mktemp) &&
# The paths are baked in: the trap fires after this function's locals are gone.
- trap "rm -f $probes $lint_log" EXIT &&
+ trap "rm -f $allowed $probes $lint_log" EXIT &&
trap 'exit 130' INT &&
trap 'exit 143' TERM &&
echo "import '../emit/spelling-questions.ts';" > "$allowed" &&
in_image "$node_image" npm run lint &&
- echo "import '../markdown/flavour.ts';" > "$adf" &&
- echo "import '../html/emit/adf-to-html.ts';" > "$adf_html" &&
- echo "import '../parse/blocks.ts';" > "$directive" &&
- echo "import '../emit/image.ts';" > "$directive_emit" &&
- echo "import '../../html/emit/adf-to-html.ts';" > "$directive_html" &&
- echo "import '../portable/conventions.ts';" > "$emit" &&
- echo "import '../../html/emit/adf-to-html.ts';" > "$emit_html" &&
- echo "import '../markdown/flavour.ts';" > "$html" &&
- echo "import '../html/emit/adf-to-html.ts';" > "$markdown" &&
- echo "import '../emit/adf-to-markdown.ts';" > "$parse" &&
- echo "import '../../html/emit/adf-to-html.ts';" > "$parse_html" &&
- echo "import '../portable/conventions.ts';" > "$parse_portable" &&
+ while read -r probe target; do
+ echo "import '$target';" > "$probe" || return 1
+ done <<< "$boundary_probes" &&
! in_image "$node_image" npm run lint -- --format unix 2>&1 | tee "$lint_log" &&
for probe in $probes; do
- [ "$probe" = "$allowed" ] || grep -q "^$probe:.*eslint(no-restricted-imports)" "$lint_log" || return 1
+ grep -q "^$probe:.*eslint(no-restricted-imports)" "$lint_log" || return 1
done &&
- rm -f $probes "$lint_log"
+ rm -f "$allowed" $probes "$lint_log"
}
leg "import boundaries fire ($node_image)" boundaries_fire
diff --git a/docs/decisions.md b/docs/decisions.md
index 8df444e..00a73b7 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -405,6 +405,13 @@ bare ``, a list item's first paragraph bare, `
picked `data-adf` 6 of 7 over `data-adf-node`. Four of them wanted the class `adf-carry` and three
no class; this entry's stable `adf-*` classes settle it.
+A second panel of the same three roles picked, 3 of 3: an attribute the element cannot express as
+`data-local-id` over `data-adf-local-id` and `id`, since Atlassian's editor puts a `localId` on every
+block and a block carried for it would show no element at all; inside a carry element a link as
+`` over `text (url)` and over its text alone, a carried node's blocks as ` ` over ` Read the CommonMark spec first. Then import. Ask @Mikael `; in a ``, ` Read the manual. Line one a < b && c > "d" \'e\'
\nf a < b && c > "d" \'e\'\tf\ng\fh b b Bolt x x Bolt Quoted Check the collation. Ask @Mikael Read the CommonMark spec first. Then Details Inside a (synced block) ${anchor}${element} ${shown}
` and a
+line feed, and media it cannot show as `(image)` over `(image not shown)` and
+nothing.
+
## No runtime dependencies
2026-08-23, the maintainer. Goal 8. Valid while ~20 lines of own code, or a vendored table, do each
@@ -970,6 +977,7 @@ is the only import `parse/` takes from `emit/`, through `emit/spelling-questions
`.oxlintrc.json` enforces that limit for `markdown/parse/`, keeps `parse/` and `emit/` from
importing `markdown/portable/`, keeps `markdown/directive/` from importing `emit/` or `parse/`,
keeps `markdown/` and `html/` from importing each other, and keeps `adf/` from importing either, as
-`no-restricted-imports` overrides. They are lint rules because the technical principles refuse a
+`no-restricted-imports` overrides. A later override replaces an earlier one's rule, so each
+`markdown/` subdirectory's override repeats the ban on `html/`, and `ci.sh` probes every override. They are lint rules because the technical principles refuse a
test that scans the source, and a lint rule reads every import spelling: `from`, a bare `import`,
double quotes and a dynamic `import()`.
diff --git a/spec/html.md b/spec/html.md
index ab89c44..26cc4f2 100644
--- a/spec/html.md
+++ b/spec/html.md
@@ -15,8 +15,8 @@ document whose `content` is an empty array is the empty string.
| `heading`, `level` 1 to 6 | `…
` to `…
` |
| `blockquote` | ``, a line feed, its blocks, a line feed, `
` |
| `bulletList` | ``, a line feed, its items a line each, a line feed, `
` |
-| `orderedList` | as `bulletList` with ``; `
` for an `order` of 3, a safe integer; no `start` where the list holds no `order` |
-| `listItem` | `
`; `
` for an `order` of 3, a safe integer other than `-0`; no `start` where the list holds no `order` |
+| `listItem` | `
`, the language one token holding no whitespace; no `class` where it holds no `language` |
| `rule` | `…
` |
| `mediaSingle`, centered, holding one external `media` | ``, ``; so is a paragraph or heading, ``.
+Every other attribute its type holds (`spec/flavour.md` §Block nodes) is a `data-*` attribute on the
+element, named as HTML's `dataset` names it, `localId` as `data-local-id`, after the element's own
+attributes and sorted by name. A string is its value; any other value is its JSON, compact:
+`
`, `
`. A code block's
+`data-*` attributes stand on its ``.
+
## Inline
| ADF | HTML |
@@ -39,43 +45,58 @@ marks are two `` elements.
## Escaping
-Text and attribute values escape `&`, `<`, `>` and `"` as `&`, `<`, `>` and `"`,
-and a carriage return as `
`, which an HTML parser would otherwise read as a line feed.
+Text and attribute values escape `&`, `<`, `>` and `"` as `&`, `<`, `>` and `"`.
Attribute values are double-quoted. A link's `href` and an image's `src` are the URL as the ADF
holds it, whatever its scheme (`docs/decisions.md` §HTML writes a URL as the ADF holds it, whatever
its scheme).
+HTML text and attribute values cannot hold a carriage return, which a parser reads as a line feed,
+a control other than a tab, line feed or form feed, a noncharacter, or a lone surrogate, which
+UTF-8 cannot encode (WHATWG HTML §13.1.3). A node holding one in a value its element writes rides
+the carry.
+
## The carry element
A node the sections above cannot write where it stands is the carry element: `
` parts two blocks'.
+ - A hard break and a line feed in text are `
`.
+ - Text a link marks is `` around it, and a card or an external image is a
+ link to its URL.
+ - A node referencing what it cannot show is a note naming it, `(image)`: `image` for
+ media with no `alt` or URL, `link card` for a card with neither URL nor name, an extension's
+ key, else `extension`, for an extension with no text, and `synced block` for a `syncBlock`.
+ - Characters HTML cannot hold are dropped.
+- A node rides the carry where it holds a mark or a key its element does not write, an attribute
+ its type does not hold as that kind, an empty `attrs`, `content` or `marks`, or a value its
+ element cannot hold:
+ - text holding no character, or a character HTML cannot hold; text holding a mark twice, or a
+ mark with attributes besides a link's `href` and `title`;
- an unmarked text node straight after another, which would read back as one;
- - a link whose `href` or `title` holds a null character, and an image whose `url` or `alt` holds
- one or whose link's `href` or `title` does;
- - a code block holding more than one text node, a marked one, or a language holding whitespace
- or a null character;
- - a list holding a node that is no `listItem`, or an item holding attributes or marks: the whole
- list rides the carry;
+ - a link whose `href` or `title` holds a character HTML cannot hold, and an image whose `url` or
+ `alt` holds one or whose link's `href` or `title` does;
+ - a heading whose `level` is not 1 to 6, and an ordered list whose `order` is not a safe integer
+ or is `-0`;
+ - a code block holding more than one text node, a marked one, or a language holding whitespace;
+ - a rule or hard break holding `content`;
+ - a list holding a node that is no `listItem`, or an item holding a mark, text, an empty key or
+ an attribute its type does not hold: the whole list rides the carry;
- a `listItem` outside a list, an inline node in block position and a block node inline.
- A block carry's JSON nests at most 500 levels less the depth it stands at, an inline carry's at
most 500, as in markdown.
diff --git a/src/adf/document.test.ts b/src/adf/document.test.ts
index 9e986f8..f262684 100644
--- a/src/adf/document.test.ts
+++ b/src/adf/document.test.ts
@@ -2,8 +2,9 @@ import assert from 'node:assert/strict'
import test from 'node:test'
import vm from 'node:vm'
+import type { AdfDocument } from './document.ts'
import type { JsonValue } from '../json-value.ts'
-import { adfDocumentFault, isAdfDocument } from './document.ts'
+import { adfDocumentFault, isAdfDocument, writableContent } from './document.ts'
import { largestNesting } from '../nesting.ts'
function fault(value: unknown): string {
@@ -114,3 +115,17 @@ test('refuses an object holding itself, and accepts one shared', () => {
const values = { b: 1 }
assert.equal(fault({ content: [shared, shared, { attrs: { a: [values, values] }, type: 'paragraph' }], type: 'doc', version: 1 }), 'accepted')
})
+
+test('opens every writer with the same checks: a document, version 1, and no more text than the longest output holds', () => {
+ const checked = (document: AdfDocument): string => {
+ const result = writableContent(document)
+ return result.ok ? JSON.stringify(result.value) ?? 'no content key' : result.error.code
+ }
+ assert.equal(checked({ type: 'doc', version: Number.NaN }), 'not-an-adf-document')
+ assert.equal(checked({ type: 'doc', version: 2 }), 'unsupported-document-version')
+ assert.equal(checked({ type: 'doc', version: 1 }), 'no content key')
+ assert.equal(checked({ content: [{ type: 'rule' }], type: 'doc', version: 1 }), '[{"type":"rule"}]')
+ const long = 'a'.repeat(2 ** 28)
+ const text = { content: [{ text: long, type: 'text' }, { text: long, type: 'text' }, { text: long, type: 'text' }], type: 'paragraph' }
+ assert.equal(checked({ content: [text], type: 'doc', version: 1 }), 'unsupported-node-shape')
+})
diff --git a/src/adf/shown-text.ts b/src/adf/shown-text.ts
index 143f3f6..4ea0340 100644
--- a/src/adf/shown-text.ts
+++ b/src/adf/shown-text.ts
@@ -1,7 +1,43 @@
import type { AdfNode } from './document.ts'
import type { JsonValue } from '../json-value.ts'
+import { blockNodeModel } from './block-nodes.ts'
import { nodeAttrs } from './document.ts'
+export function isBlockNodeType(type: string): boolean {
+ return blockNodeModel(type) !== undefined || type === 'blockCard' || type === 'embedCard'
+}
+
+// Whether the text a node shows stands apart from the text beside it; media shows inline, as an image in a line does.
+export function partsShownText(type: string): boolean {
+ return isBlockNodeType(type) && type !== 'media'
+}
+
+export function oneLine(text: string): string {
+ return text.replace(/[\r\u0000]/g, '').replace(/\n/g, ' ')
+}
+
+// The name of what a node references where it shows no text of its own, for a note standing in its place.
+export function referenceName(node: AdfNode): string | undefined {
+ switch (node.type) {
+ case 'blockCard':
+ case 'embedCard':
+ case 'inlineCard':
+ return 'link card'
+ case 'extension':
+ case 'inlineExtension': {
+ const key = visibleText(nodeAttrs(node)['extensionKey'])
+ return key === undefined ? 'extension' : oneLine(key).trim()
+ }
+ case 'media':
+ case 'mediaInline':
+ return 'image'
+ case 'syncBlock':
+ return 'synced block'
+ default:
+ return undefined
+ }
+}
+
// The text a node shows in place of itself, read from the attribute holding its content; `undefined` where it holds none.
export function shownText(node: AdfNode): string | undefined {
const attrs = nodeAttrs(node)
@@ -9,32 +45,45 @@ export function shownText(node: AdfNode): string | undefined {
case 'blockCard':
case 'embedCard':
case 'inlineCard':
- return visibleText(attrs['url']) ?? visibleText(cardData(node)['name']) ?? cardUrl(node)
+ return visibleText(attrs['url']) ?? visibleText(cardData(node)['name']) ?? shownUrl(node)
case 'date':
return isoDate(attrs['timestamp'])
case 'emoji':
return visibleText(attrs['text']) ?? stringValue(attrs['shortName'])
case 'expand':
case 'nestedExpand':
- case 'status':
- return stringValue(node.type === 'status' ? attrs['text'] : attrs['title'])
+ return stringValue(attrs['title'])
case 'extension':
case 'inlineExtension':
return visibleText(attrs['text'])
case 'media':
case 'mediaInline':
- return visibleText(attrs['alt']) ?? (attrs['type'] === 'external' ? visibleText(attrs['url']) : undefined)
+ return visibleText(attrs['alt']) ?? shownUrl(node)
case 'mention': {
const id = attrs['id']
return visibleText(attrs['text']) ?? (typeof id === 'string' && id !== '' ? `@${id}` : undefined)
}
+ case 'status':
+ return stringValue(attrs['text'])
default:
return undefined
}
}
-export function cardUrl(card: AdfNode): string | undefined {
- return visibleText(nodeAttrs(card)['url']) ?? visibleText(cardData(card)['url'])
+// The URL a card or an external image links a reader to; `undefined` for every other node.
+export function shownUrl(node: AdfNode): string | undefined {
+ const attrs = nodeAttrs(node)
+ switch (node.type) {
+ case 'blockCard':
+ case 'embedCard':
+ case 'inlineCard':
+ return visibleText(attrs['url']) ?? visibleText(cardData(node)['url'])
+ case 'media':
+ case 'mediaInline':
+ return attrs['type'] === 'external' ? visibleText(attrs['url']) : undefined
+ default:
+ return undefined
+ }
}
// `undefined` where the value is no string or holds only whitespace and null characters.
diff --git a/src/conformance/adf-property.test.ts b/src/conformance/adf-property.test.ts
index bb2ff01..82954f2 100644
--- a/src/conformance/adf-property.test.ts
+++ b/src/conformance/adf-property.test.ts
@@ -12,6 +12,19 @@ import { portableMarkdownToAdf } from '../markdown/portable/portable-markdown-to
import { toEditorNormal } from '../markdown/portable/editor-normal.ts'
const gateRuns = 1600
+// What HTML text cannot hold (WHATWG HTML §13.1.3), and the line feed a carry element shows as a line break.
+const unshown = /\n|(?![\t\f ])[\p{Cc}\p{Cs}\p{Noncharacter_Code_Point}]/gu
+
+// Every text node's text in document order.
+function documentTexts(nodes: readonly AdfNode[]): string[] {
+ const texts: string[] = []
+ const pending = [...nodes].reverse()
+ for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+ if (node.text !== undefined) texts.push(node.text)
+ for (const child of [...(node.content ?? [])].reverse()) pending.push(child)
+ }
+ return texts
+}
// Each block's text, an expand's title and an image's alt and url, in document order: what the portable pair keeps.
function shownText(nodes: readonly AdfNode[]): string[] {
@@ -56,12 +69,20 @@ test('a generated document writes portable markdown refusing only what the guard
)
})
-test('a generated document writes HTML holding no null character', { timeout: propertyTimeout }, () => {
+test('a generated document writes HTML holding no character HTML cannot hold, and showing every text node\'s text in document order', { timeout: propertyTimeout }, () => {
fc.assert(
fc.property(adfDocument, (document) => {
const written = adfToHtml(document)
assert.ok(written.ok, written.ok ? '' : `${written.error.code}: ${written.error.message}`)
- assert.ok(!written.value.includes('\0'), `writing ${JSON.stringify(document)}`)
+ assert.ok(!/(?![\t\n\f ])[\p{Cc}\p{Cs}\p{Noncharacter_Code_Point}]/u.test(written.value), `writing ${JSON.stringify(document)}`)
+ const page = written.value.replace(/<[^>]*>/g, '').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"').replaceAll('&', '&').replace(unshown, '')
+ let from = 0
+ for (const text of documentTexts(document.content ?? [])) {
+ const shown = text.replace(unshown, '')
+ const at = page.indexOf(shown, from)
+ assert.ok(at >= 0, `writing ${JSON.stringify(document)}: ${JSON.stringify(shown)} is not shown after ${from}`)
+ from = at + shown.length
+ }
}),
propertyRuns(gateRuns),
)
diff --git a/src/conformance/corpus.test.ts b/src/conformance/corpus.test.ts
index 0067e8e..ce0d033 100644
--- a/src/conformance/corpus.test.ts
+++ b/src/conformance/corpus.test.ts
@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
import { readFileSync, readdirSync } from 'node:fs'
import test from 'node:test'
+import { adfToHtml } from '../html/emit/adf-to-html.ts'
import { adfToLosslessMarkdown } from '../markdown/emit/adf-to-markdown.ts'
import { isAdfDocument } from '../adf/document.ts'
import { isJsonValue } from '../json-value.ts'
@@ -149,6 +150,23 @@ for (const name of names(realPayloadsRoot, '.json')) {
})
}
+// The element each block an editor writes with no attribute but `localId`, and `level` or `order`, opens with; every other block is carried.
+const blockElements: ReadonlyLevel 1
\n
\nLevel 6
\n')
@@ -42,18 +72,44 @@ test('writes the marks CommonMark spells, the first mark outermost', () => {
assert.equal(html(adfToHtml(document(paragraph(text('Line one'), { type: 'hardBreak' }, text('Line two'))))), '
Line two\n
\n')
- const nested: AdfNode = { attrs: { order: 3 }, content: [item(paragraph(text('Bolt')), { content: [item(paragraph(text('M8')))], type: 'bulletList' }), item(paragraph(text('a')), paragraph(text('b')))], type: 'orderedList' }
- assert.equal(html(adfToHtml(document(nested))), '\n
\n')
+ const listed: AdfNode = { attrs: { order: 3 }, content: [item(paragraph(text('Bolt')), { content: [item(paragraph(text('M8')))], type: 'bulletList' }), item(paragraph(text('a')), paragraph(text('b')))], type: 'orderedList' }
+ assert.equal(html(adfToHtml(document(listed))), '\n
\n\n
\n')
assert.equal(html(adfToHtml(document({ content: [item({ type: 'rule' }), { type: 'listItem' }], type: 'orderedList' }))), '\n
\n\n
\n')
assert.equal(html(adfToHtml(document({ content: [item(paragraph())], type: 'bulletList' }))), '
\n\n
\n')
})
+test('writes an item\'s first paragraph as its element where it holds an attribute, and as its carry where it holds a mark', () => {
+ const first = (node: AdfNode): string => html(adfToHtml(document({ content: [item(node)], type: 'bulletList' })))
+ assert.equal(first({ attrs: { localId: ids.paragraph }, content: [text('Bolt')], type: 'paragraph' }), `\n
\n`)
+ assert.equal(first({ content: [text('Bolt')], marks: [{ attrs: { align: 'center' }, type: 'alignment' }], type: 'paragraph' }).startsWith('\n
x
\n`)
+ assert.equal(html(adfToHtml(document({ attrs: { localId: ids.quote }, content: [paragraph(text('x'))], type: 'blockquote' }))), `\n
\n`)
+ const listed: AdfNode = { attrs: { localId: ids.list, order: 3 }, content: [{ attrs: { localId: ids.item }, content: [{ attrs: localId, content: [text('Bolt')], type: 'paragraph' }], type: 'listItem' }], type: 'orderedList' }
+ assert.equal(html(adfToHtml(document(listed))), `\n
\n`)
+ const code: AdfNode = { attrs: { wrap: true, language: 'js', hideLineNumbers: false, ...localId }, content: [text('x')], type: 'codeBlock' }
+ assert.equal(html(adfToHtml(document(code))), `
\n`)
+ assert.equal(html(adfToHtml(document({ attrs: { weight: -0, color: '#ccc', style: 'a"b' }, type: 'rule' }))), 'x
\n')
+})
+
test('writes quotes and code blocks, the language a class', () => {
assert.equal(html(adfToHtml(document({ content: [paragraph(text('Quoted'))], type: 'blockquote' }))), '\n
\n')
assert.equal(html(adfToHtml(document({ attrs: { language: 'javascript' }, content: [text('if (a < b)\n run()')], type: 'codeBlock' }))), '
\n')
@@ -67,61 +123,85 @@ test('writes an external image standing alone in a paragraph, a link around it w
assert.equal(html(adfToHtml(document(linked))), 'if (a < b)\n run()
import.
bc
b')
+ assert.equal(shown(html(adfToHtml(document(paragraph(text('a\u0001b\r', { type: 'underline' }, { attrs: { href: 'https://example.com/\u0001' }, type: 'link' })))))), 'ab')
+})
+
+test('shows the content a carried node holds in an attribute, a link to what it links to', () => {
+ 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: { id: '5b10a2' }, type: 'mention' }), '@5b10a2')
+ assert.equal(inline({ attrs: { color: 'green', text: 'Done' }, type: 'status' }), 'Done')
+ assert.equal(inline({ attrs: { url: 'https://example.com/
' : undefined)
+ const html = tryCodeBlock(node) ?? tryImage(node) ?? tryRule(node)
return html === undefined ? undefined : success(html)
}
-function inlineElement(tag: string, nodes: readonly AdfNode[], path: ConvertErrorPath): Result
`
+ if (node.content === undefined) return `
`
+ return code === undefined ? undefined : ``
@@ -128,3 +166,8 @@ function tryImage(node: AdfNode): string | undefined {
const anchor = anchorOpener(image.link)
return anchor === undefined ? undefined : `
')
+}
+
+// The node's own part of what its carry element shows: its text or what it shows in its place, linked where it links; a note where it references what it cannot show.
+function shownPiece(node: AdfNode): string {
+ if (node.type === 'hardBreak') return '
'
+ const text = node.text ?? shownText(node)
+ if (text === undefined) {
+ const name = referenceName(node)
+ return name === undefined ? '' : `(${shownValue(name)})`
+ }
+ const link = shownLink(node)
+ const anchor = link === undefined ? undefined : anchorOpener(link)
+ return anchor === undefined ? shownValue(text) : `${anchor}${shownValue(text)}`
+}
+
+// What a reader of the carry element follows from the node: its link mark's target, or the URL a card or an image links to.
+function shownLink(node: AdfNode): LinkAttrs | undefined {
+ const mark = nodeMarks(node).find((held) => held.type === 'link')
+ if (mark !== undefined) return linkAttrs(nodeAttrs(mark))
+ const href = shownUrl(node)
+ return href === undefined ? undefined : { href }
}
diff --git a/src/html/emit/escaping.ts b/src/html/emit/escaping.ts
index 73c223e..f462266 100644
--- a/src/html/emit/escaping.ts
+++ b/src/html/emit/escaping.ts
@@ -1,23 +1,44 @@
-// An HTML parser reads a null character as U+FFFD, so each function here refuses or drops one, and the writer escapes through nothing else.
+import type { LinkAttrs } from '../../adf/mark-attributes.ts'
-// `undefined` where the value holds a null character, so its node rides the carry element.
-export function htmlValue(value: string): string | undefined {
- return value.includes('\0') ? undefined : escapeHtml(value)
+// What HTML text and attribute values cannot hold (WHATWG HTML §13.1.3): a control other than ASCII whitespace or a carriage return, which a parser reads as a line feed; a noncharacter; and a lone surrogate, which UTF-8 cannot encode.
+const unwritable = /(?![\t\n\f ])[\p{Cc}\p{Cs}\p{Noncharacter_Code_Point}]/u
+const unwritables = new RegExp(unwritable.source, 'gu')
+
+export function anchorOpener({ href, title }: LinkAttrs): string | undefined {
+ const url = writableValue(href)
+ const titled = optionalAttribute('title', title)
+ return url === undefined || titled === undefined ? undefined : ``
}
-// ` name="value"`, `''` where the value is undefined, `undefined` where it holds a null character.
+// The carry's JSON, which spells each character HTML cannot hold as a JSON escape reading back to the same string.
+export function jsonValue(json: string): string {
+ return escapeHtml(json.replace(unwritables, (character) => jsonEscape(character)))
+}
+
+// ` name="value"`, `''` where the value is undefined, `undefined` where HTML cannot hold it.
export function optionalAttribute(name: string, value: string | undefined): string | undefined {
if (value === undefined) return ''
- const escaped = htmlValue(value)
+ const escaped = writableValue(value)
return escaped === undefined ? undefined : ` ${name}="${escaped}"`
}
-// What the carry element holds: its JSON spells a null character `\u0000`, and the text it shows drops one.
-export function carriedValue(value: string): string {
- return escapeHtml(value.replaceAll('\0', ''))
+// The text a carry element shows, dropping what HTML cannot hold, each line feed a line break.
+export function shownValue(value: string): string {
+ return escapeHtml(value.replace(unwritables, '')).replaceAll('\n', '
')
}
-// A carriage return is a character reference, since an HTML parser reads a raw one as a line feed.
-function escapeHtml(text: string): string {
- return text.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"').replaceAll('\r', '
')
+// `undefined` where HTML cannot hold the value, so its node rides the carry element.
+export function writableValue(value: string): string | undefined {
+ return unwritable.test(value) ? undefined : escapeHtml(value)
+}
+
+function escapeHtml(text: string): string {
+ return text.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"')
+}
+
+// An astral noncharacter spells as its two surrogates' escapes.
+function jsonEscape(character: string): string {
+ let escaped = ''
+ for (let index = 0; index < character.length; index += 1) escaped += `\\u${character.charCodeAt(index).toString(16).padStart(4, '0')}`
+ return escaped
}
diff --git a/src/html/emit/inline.ts b/src/html/emit/inline.ts
index 12fcfaa..7d253af 100644
--- a/src/html/emit/inline.ts
+++ b/src/html/emit/inline.ts
@@ -1,12 +1,15 @@
import type { AdfMark, AdfNode } from '../../adf/document.ts'
+import { anchorOpener, writableValue } from './escaping.ts'
import { carriedInline } from './carry-element.ts'
import { holdsOnlyAttributes, isSpellableText, isUnmarkedSpellableText, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
-import { htmlValue, optionalAttribute } from './escaping.ts'
-import { linkAttrs, type LinkAttrs } from '../../adf/mark-attributes.ts'
+import { linkAttrs } from '../../adf/mark-attributes.ts'
import { success, type ConvertErrorPath, type Result } from '../../result.ts'
-// Each names its element.
-const elementMarks: readonly string[] = ['code', 'em', 'strong']
+const markElements: ReadonlyMap