3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-19 14:45:44 +01:00

Answer principles round 1: 3 🔴, 8 🟡 (0 misread); attributes as data-*, carried content as paragraphs, links and notes, no character HTML cannot hold, mutants killed

This commit is contained in:
2026-10-23 19:19:14 +02:00
committed by Lillem4n
parent 1f46111fe4
commit 7a38db2563
27 changed files with 612 additions and 295 deletions
+33 -11
View File
@@ -21,7 +21,7 @@ products store as ADF.
drops the rest.
- **HTML out:** `adfToHtml` writes paragraphs, headings, lists, quotes, code blocks, images and
links as their HTML elements, and every other node as an element holding its JSON and showing its
text.
content.
- **No throws:** every call returns a result; a refusal carries a code from a closed list.
- **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers.
TypeScript types ship beside the JavaScript.
@@ -75,11 +75,30 @@ if (portable.ok) console.log(portable.value)
Full reference: [HTML](#html).
```ts
import { adfToHtml } from '@larvit/adf-codec'
import { adfToHtml, type AdfDocument } from '@larvit/adf-codec'
const html = adfToHtml(doc) // the panel above
const page: AdfDocument = {
content: [
{ attrs: { level: 2, localId: 'a1f3' }, content: [{ text: 'Release notes', type: 'text' }], type: 'heading' },
{
content: [
{ text: 'Read the ', type: 'text' },
{ marks: [{ attrs: { href: 'https://spec.commonmark.org/' }, type: 'link' }], text: 'spec', type: 'text' },
{ text: ', then ask ', type: 'text' },
{ attrs: { id: '5b10a2', text: '@Mikael' }, type: 'mention' },
],
type: 'paragraph',
},
],
type: 'doc',
version: 1,
}
// URLs are written as the ADF holds them, javascript: included: sanitize HTML from an author you do not trust before showing it.
const html = adfToHtml(page)
if (html.ok) console.log(html.value)
// <div class="adf-carry" data-adf="{&quot;attrs&quot;:{&quot;panelType&quot;:&quot;warning&quot;},…}">Check the collation before importing.</div>
// <h2 data-local-id="a1f3">Release notes</h2>
// <p>Read the <a href="https://spec.commonmark.org/">spec</a>, then 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>
```
### Markdown to ADF
@@ -447,9 +466,9 @@ saving what this pair read replaces mentions, attachments and macros with text.
## HTML
Serves [Goals](#goals) 1, 6 and 7. `adfToHtml` writes the HTML element for each node HTML has one
for, and keeps every other node whole: an element of class `adf-carry` holds the node's JSON in
`data-adf` and shows the node's text, so a reader of the page loses no content. No stylesheet
ships. The complete dialect:
for, an attribute HTML has none for as `data-*`, and keeps every other node whole: an element of
class `adf-carry` holds the node's JSON in `data-adf` and shows the node's content, its links
included, so a reader of the page loses no content. No stylesheet ships. The complete dialect:
[`spec/html.md`](https://github.com/larvit/adf-codec/blob/main/spec/html.md).
| ADF | HTML |
@@ -464,11 +483,14 @@ ships. The complete dialect:
| `paragraph` | `<p>` |
| `rule` | `<hr>` |
| `text` marked `code`, `em`, `strong` | `<code>`, `<em>`, `<strong>`, the first mark outermost |
| any other node, or a node holding what its element cannot | `<div class="adf-carry" data-adf="{…}">its text</div>`, a `<span>` inline |
| any other attribute the node's type holds | `data-*` named as HTML's `dataset` names it: `<p data-local-id="a1f3">` |
| any other node, or a node holding what its element cannot | `<div class="adf-carry" data-adf="{…}"><p>its content</p></div>`, a `<span>` inline |
- Text and attribute values are escaped: `&`, `<`, `>`, `"` and a carriage return.
- The carry element shows a mention, status or emoji by its text, a date as `2026-09-13` in UTC, a
card by its URL, an image by its `alt`, else its URL, and an expand by its title.
- Text and attribute values are escaped: `&`, `<`, `>` and `"`. A node holding what HTML cannot
hold, such as a carriage return or a control character, rides the carry element.
- The carry element shows each block's content as a `<p>`, 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, `<em>(image)</em>`.
- 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.