Click-to-edit has shipped and is in real use, but a consuming site has nothing
to read. The conventions are only discoverable by reading integration/index.js
and ui/dashboard.js, and two of them are traps rather than features — a site
author who guesses will get them wrong in a way that fails silently.
Deferred in two prior housekeeping passes; wiring up a real site's blocks
produced the concrete rules, so there is now something worth writing.
What the docs should say
data-aa-field (preview → editor). Its value must be the editor control's
actual form name. For a field inside a block that is index-qualified:
blocks[2].text, not text. Getting it wrong fails silently — the click posts
a message and focusEditorField finds no control and returns.
Never annotate a link. The click handler deliberately lets genuine links
navigate. An annotated <a> therefore posts the focus message and navigates
the preview away from the page being edited, which is worse than no annotation.
Where a link sits inside a repeated card, annotate the card's title and body
individually rather than the card or its list, so a click on the link finds no
annotated ancestor.
A component must forward unknown attributes. Any wrapper component that
destructures a fixed prop list drops data-aa-field on the floor: it compiles,
renders nothing, and fails no test. This bit two components on one site.
data-block-index (editor → preview). Without it findBlocks() falls back
to counting top-level <section> elements, so any block rendering something
else (a <figure> for an image band) shifts every index after it and the editor
highlights the wrong block. Nothing reports this.
Array and media controls do not take focus. A hidden input backing an image picker
or an array editor cannot be focused, so only the scroll-and-flash happens. That
is correct behaviour, not a bug — worth saying so, since it looks like one.
Where
docs/inline-editing.md exists and looks like the natural home.
Click-to-edit has shipped and is in real use, but a consuming site has nothing
to read. The conventions are only discoverable by reading
integration/index.jsand
ui/dashboard.js, and two of them are traps rather than features — a siteauthor who guesses will get them wrong in a way that fails silently.
Deferred in two prior housekeeping passes; wiring up a real site's blocks
produced the concrete rules, so there is now something worth writing.
What the docs should say
data-aa-field(preview → editor). Its value must be the editor control'sactual form name. For a field inside a block that is index-qualified:
blocks[2].text, nottext. Getting it wrong fails silently — the click postsa message and
focusEditorFieldfinds no control and returns.Never annotate a link. The click handler deliberately lets genuine links
navigate. An annotated
<a>therefore posts the focus message and navigatesthe preview away from the page being edited, which is worse than no annotation.
Where a link sits inside a repeated card, annotate the card's title and body
individually rather than the card or its list, so a click on the link finds no
annotated ancestor.
A component must forward unknown attributes. Any wrapper component that
destructures a fixed prop list drops
data-aa-fieldon the floor: it compiles,renders nothing, and fails no test. This bit two components on one site.
data-block-index(editor → preview). Without itfindBlocks()falls backto counting top-level
<section>elements, so any block rendering somethingelse (a
<figure>for an image band) shifts every index after it and the editorhighlights the wrong block. Nothing reports this.
Array and media controls do not take focus. A hidden input backing an image picker
or an array editor cannot be focused, so only the scroll-and-flash happens. That
is correct behaviour, not a bug — worth saying so, since it looks like one.
Where
docs/inline-editing.mdexists and looks like the natural home.