larvit/adf-codec
3
0
Fork 0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-12 11:48:29 +01:00
Code Activity

Answer product-owner round 1: 0 🔴, 4 🟡 (0 misread); list the breaking change on its own, name what to build, and cover the readers

Browse Source
This commit is contained in:
Lilleman auf Larv
2026-11-04 20:30:08 +01:00
committed by Lillem4n
parent deae360969
commit 9460f18f6f
3 changed files with 22 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+7 -4
View File
@@ -17,9 +17,7 @@
`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. **Breaking:** `adfToHtml`, `adfToLosslessMarkdown` and `adfToPortableMarkdown` refuse an
inline card a link marks, wherever it stands, as `unsupported-node-shape` at the card's path, before
they write: Atlassian's schema gives a card no link mark.
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,
`&nbsp;`, a raw `<` or `>` in an attribute value) and as a form post sends it (`\r\n` for each
@@ -31,7 +29,12 @@
reads as a plain mention. A link or directive mark around only nodes that cannot take it is
`unsupported-node-shape`, even in markdown `adfToLosslessMarkdown` wrote. A link around hard
breaks alone still reads as before. `adfToLosslessMarkdown` writes a node holding a mark its type
cannot take as `!adf:carry{json="…"}`. `MIGRATION.md` says how to convert stored markdown.
cannot take as `!adf:carry{json="…"}`, except an inline card a link marks, which it refuses.
`MIGRATION.md` says how to convert stored markdown.
- **Breaking:** `adfToLosslessMarkdown` and `adfToPortableMarkdown` refuse an inline card a link marks
as `unsupported-node-shape` at the card's path, and `losslessMarkdownToAdf` refuses a carry
holding one, since Atlassian's schema gives a card no link mark. `adfToHtml` and `htmlToAdf` do
the same. `MIGRATION.md` says what to do.
- **Breaking:** every reader gives code text no mark but `link` and `annotation`, as Atlassian's
schema requires: ``**`npm ci`**`` now reads as plain code, and a directive mark other than a link
around only code spans is `unsupported-node-shape`. `adfToLosslessMarkdown` writes code text
MIGRATION.md
+8 -8
View File
@@ -12,14 +12,9 @@ also skips every other node Atlassian's schema withholds the mark from:
| a code span inside any mark's spelling but a link's (``**`npm ci`**``) | the code text holds the mark | the code text holds only `code`, and a link where one wraps it |
| text inside `!adf:border[…]` (`!adf:border[x]{color="#091e42" size=2}`) | the text holds `border` | the text holds none, and where nothing the spelling wraps takes `border`, `unsupported-node-shape`: delete the spelling and keep its text. Only a `mediaInline` takes `border` |
`adfToLosslessMarkdown` and `adfToPortableMarkdown` no longer write an `inlineCard` a link marks:
`0.3.0` refuses it as `unsupported-node-shape` at the card's path, as does `adfToHtml`, since
Atlassian's schema gives a card no link mark. Remove the link mark from the card, or wrap the card's
text in the link yourself.
`0.3.0`'s `adfToLosslessMarkdown` writes a node holding a withheld mark as `!adf:carry{json="…"}`,
where `0.2.0` wrote these spellings. `0.3.0` reads markdown stored from such a document without the
mark, and refuses it where the mark wrapped only those nodes. Keep the mark only in markdown
`0.3.0`'s `adfToLosslessMarkdown` writes a node holding a withheld mark as `!adf:carry{json="…"}`
(an `inlineCard`'s link excepted, below), where `0.2.0` wrote these spellings. `0.3.0` reads
markdown stored from such a document without the mark, and refuses it where the mark wrapped only those nodes. Keep the mark only in markdown
written from ADF that held it: Atlassian's schema withholds it, so a site may refuse the document.
To keep it, read the markdown with `0.2.0` and write it with `0.3.0`, installed side by side:
@@ -27,6 +22,11 @@ To keep it, read the markdown with `0.2.0` and write it with `0.3.0`, installed
npm install @larvit/adf-codec@0.3.0 adf-codec-0.2@npm:@larvit/adf-codec@0.2.0
```
That recipe cannot keep a link on an `inlineCard`: `0.3.0` refuses it as `unsupported-node-shape`,
the error's `path` naming the card, since Atlassian's schema gives a card no link mark. Remove the
`link` mark from that card before you write it with `0.3.0`; to keep the link's target, put the
link on a `text` node beside the card.
## From `0.1.0` to `0.2.0`
Each call names the markdown it reads or writes:
README.md
+7 -5
View File
@@ -526,7 +526,7 @@ content. No stylesheet ships. The complete dialect:
| `rule` | `<hr>` |
| `text` marked `code`, `em`, `strong` | `<code>`, `<em>`, `<strong>`, the first mark outermost |
| an attribute its type holds that its element does not write, such as `localId`, on a paragraph, heading, quote, list, list item, code block, rule, emoji, mention, status, date or card | `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 |
| any other node, or a node holding what its element cannot, except an inline card a link marks, which is refused ([The errors](#the-errors)) | `<div class="adf-carry" data-adf="{…}"><p>its content</p></div>`, a `<span>` inline |
- Every URL is written as the ADF holds it, `javascript:` included: a link's, an image's, a
card's, and a carried link's in the carry element. Sanitize the HTML before showing a document from
@@ -631,7 +631,8 @@ Every call can raise these:
such as `[!adf:status[Done]{color=green}](/u)`: write the link around text beside them;
- writes as a directive a node or mark the lossless flavour spells as CommonMark;
- puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole
document.
document;
- carries an inline card a link marks, as the writers' cause below says.
- **Reading, in `htmlToAdf`.** Fix what the message names;
[`spec/html.md`](https://github.com/larvit/adf-codec/blob/main/spec/html.md) lists each element's
attributes. The HTML:
@@ -640,15 +641,16 @@ Every call can raise these:
`data-wrap="yes"`;
- holds a carry element whose `data-adf` holds JSON that is no ADF node, is not written compact
with its keys sorted, or holds a number JSON cannot spell;
- holds a carry element carrying an inline card a link marks, as the writers' cause below says;
- holds the document's own carry element beside another block.
- **Writing, in `adfToLosslessMarkdown`**: a node not riding the carry that carries one mark type
twice, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node
holding `content`. Keep the ADF and show the document read-only; where you built the ADF, fix
what the message names.
- **Writing, in `adfToHtml`, `adfToLosslessMarkdown` and `adfToPortableMarkdown`**: an inline card
marked by a link, wherever it stands: Atlassian's schema gives a card no link mark. Keep the ADF
and show the document read-only; where you built the ADF, remove the link mark from the card the
error's `path` names.
marked by a link, even inside a node that rides the carry: Atlassian's schema gives a card no link
mark. Keep the ADF and pass the document over or show it read-only; where you built the ADF,
remove the link mark from the card the error's `path` names.
- **Writing, in `adfToPortableMarkdown`**: a line or task list the portable writer cannot spell.
This is a bug in this library: report it.
- **Past the engine's longest string**: