actual-css 0.9.2 → 0.11.0

package/docs/pages/enhancements/tooltip.md

@@ -8,6 +8,8 @@ and arrow position are written by JavaScript; the element is shown and hidden
 by promoting it to the top layer with `popover="manual"`.
 
 - Use `data-tooltip` on the trigger. With text (`data-tooltip="Help"`), the tooltip element is generated. Empty (`data-tooltip`) marks an explicit tooltip connected via `aria-describedby`.
+- Generated text is a snapshot at show time: changing `data-tooltip` never rewrites a tooltip that is already shown, and an always-visible generated tooltip keeps its initial text. For content that must update dynamically, use an explicit tooltip. See the [tooltips bench](../examples/overview.md) (`demo/templates/tooltips.html`) for all six cases side by side.
+- Generated text is always plain text (`textContent` only), so a shorthand value is safe for untrusted strings once they are in the DOM. An explicit tooltip is author-owned DOM: its sanitization belongs to whoever produces it. Escape the attribute server-side — a DOM already compromised at render cannot be repaired at read time. There is no `data-tooltip-html`, by design.
 - Tooltips are supplemental. Do not put required information or interactive controls inside them.
 - Show on hover and focus. Hide on Escape, blur, or pointer leave.
 - A trigger scrolled out of view takes its tooltip down and brings it back when it returns; only a dismissal ends the tooltip.
@@ -35,7 +37,7 @@ runtime when Actual should own showing and hiding.
 
 **Where the element lives is part of the contract.** An explicit tooltip stays
 exactly where you wrote it, so it keeps every scope that reaches it by
-inheritance — a theme island, a density scope, `.inverted`, your own scoped
+inheritance — a theme island, a density scope, your own scoped
 custom properties. It also means placement is yours to get right: a tooltip
 used from inside a modal dialog must be authored inside that dialog, because
 the top layer does not lift an element out of a modal's inertness.

package/docs/pages/examples/overview.md

@@ -47,12 +47,13 @@ One mechanism at a time, with its contract and its pitfalls.
 Contracts you cannot read off a static screenshot: state, motion, focus, and
 extension points.
 
-- [Surface contracts](../../demo/templates/surfaces.html) - `.inverted`, cascade precedence, and the intent boundary
+- [Contrast contexts](../../demo/templates/contrast-contexts.html) - the page, `data-theme` islands, a card island, a named theme and an application-painted band side by side, with every intent variant, a full form (combobox and date picker included) and focus line measured live, plus joined fields that need no focus adaptation
 - [Presence motion](../../demo/templates/motion.html) - status bar, tooltip, flyout, modal and drawer replayed side by side, with easing swaps and a reduced-motion simulation
 - [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
 - [Adaptive filter surface](../../demo/templates/adaptive-surface.html) - app-level flyout/drawer composition with one synchronized filter state
 - [Select intents](../../demo/templates/select-intents.html) - extending the enhancer with a project's own `data-enhance` behavior, injected markup included, with no framework change
 - [Popover transport probe](../../demo/templates/popover-transport.html) - self-scoring bench for the native popover transport go/no-go
+- [Tooltips](../../demo/templates/tooltips.html) - generated text is a snapshot at show time: what updates, what stays, and the explicit-tip way for dynamic content
 
 ### Third-party components on Actual tokens
 

package/docs/pages/forms/choice-cards.md

@@ -7,12 +7,35 @@
 | Class                     | Kind      | Description                                   |
 | ------------------------- | --------- | --------------------------------------------- |
 | `.choice-card`            | Component | Card-style `<label>` around a native control. |
+| `.chip`                   | Modifier  | Compact pill form: filter chips, tags.        |
 | `.primary` / `.secondary` | Intent    | Accent for the selected state.                |
 
 - Use `.choice-card` on a `<label>` wrapping a native `<input type="radio">` or `<input type="checkbox">`. The input is visually hidden; in browsers without `:has()` it stays visible so selection state never disappears.
-- Selected items show a primary border, subtle background tint, and a checkmark badge at the top-right corner — round for radio, rounded square for checkbox.
-- Pair with grid or flex utilities for group layout. The badge overhangs the top-right corner, so avoid `overflow: hidden` on the direct container.
-- Supports disabled, checked, focus-visible, and invalid states.
+- The control shows before any choice: a ring (radio) or a rounded box (checkbox) on the leading edge, level with the first line. Checked, it fills with a check, and the card takes a primary border and a subtle tint.
+- Each child element of the label sits on its own row beside the indicator — a title and a `.muted` detail need no wrapper. Wrap loose text in an element.
+- Stack cards for a list of options (a person, an address, a delivery method), or pair them with grid utilities for options compared side by side.
+- Supports disabled, checked, focus-visible, and invalid states; the resting ring turns danger with the border.
+
+```html demo
+<fieldset class="field-group stack">
+  <legend class="field-label">Deliver to</legend>
+  <label class="choice-card">
+    <input type="radio" name="address" value="home" checked />
+    <strong>Home</strong>
+    <span class="muted">12 Rue des Tanneurs, 1000 Brussels</span>
+  </label>
+  <label class="choice-card">
+    <input type="radio" name="address" value="work" />
+    <strong>Work</strong>
+    <span class="muted">Avenue Louise 54, 1050 Ixelles</span>
+  </label>
+  <label class="choice-card">
+    <input type="radio" name="address" value="pickup" />
+    <strong>Pickup point</strong>
+    <span class="muted">Collect within 7 days</span>
+  </label>
+</fieldset>
+```
 
 ```html demo
 <div class="grid-3">
@@ -93,11 +116,100 @@ follows through its `em` sizing. Padding is density, so use a `.compact` or
 `.spacious` context to change it. Intent classes (`.primary`, `.secondary`) are
 supported on the `.choice-card` element.
 
+## Corner badge
+
+A tile whose content is the choice itself — a product image, a centred plan
+name — may want no indicator column, and a check badge over its corner once
+selected (radio/checkbox tile, selected tick, check in the corner). That is a
+recipe on the card's own `::before` (disc) and `::after` (check) layers,
+written in application CSS after the framework:
+
+```css
+.choice-tile {
+  --choice-card-check-size: 1.5em;
+
+  display: block;
+}
+
+.choice-tile::before,
+.choice-tile::after {
+  position: absolute;
+  inset-inline-end: -0.375em;
+  inset-block-start: -0.375em;
+  margin: 0;
+}
+
+.choice-tile::before {
+  border: 0;
+  box-shadow: 0 0 0 2px var(--surface-opaque);
+  transform: scale(0);
+}
+
+.choice-tile:has(:checked)::before {
+  transform: scale(1);
+}
+```
+
+```html
+<label class="choice-card choice-tile">
+  <input type="radio" name="cpu" value="1" checked />
+  <strong>8-core CPU</strong><br />
+  <span class="muted">32 GB RAM</span>
+</label>
+```
+
+The badge overhangs the corner, so no ancestor up to the grid may clip with
+`overflow: hidden`. The [Neon Ramen item page](../../demo/sites/neon-ramen/item.html)
+uses it for its sizes and toppings.
+
+## Chips
+
+Add `.chip` for the compact pill form: filter chips, selectable tags, toggle
+pills, multi-select facets. A radio group gives single-choice chips. A leading
+dot turns into the check in a fixed slot, so checking never moves the label.
+Use `.cluster` for a wrapping row. A chip is sized like a control: `.btn` and
+`.input` height, `--control-pad-x` inline padding, `.sm` / `.lg` scale.
+A chip is a `<label>` around its checkbox/radio — never nest a `.close` or any
+other button inside it. A removable value (combobox tag) belongs to the widget
+that produced it, or to a sibling `.badge` + `.close`, not to the chip label.
+
+```html demo
+<fieldset class="field-group">
+  <legend class="field-label">Fruit</legend>
+  <div class="cluster">
+    <label class="choice-card chip">
+      <input type="checkbox" name="fruit" value="pear" checked />
+      Pear
+    </label>
+    <label class="choice-card chip">
+      <input type="checkbox" name="fruit" value="apple" />
+      Apple
+    </label>
+    <label class="choice-card chip">
+      <input type="checkbox" name="fruit" value="plum" disabled />
+      Plum
+    </label>
+  </div>
+</fieldset>
+```
+
+The dot is `::before`: a full-chip layer clipped to a `circle()` centred on
+the check slot (`--choice-chip-dot`). A theme can grow it into a selected fill
+by widening the clip, as the `material` theme does.
+
 ## CSS hooks
 
 - `--choice-card-pad` — inner padding.
+- `--choice-card-gap` — space between the indicator column and the label.
 - `--choice-card-radius` — corner radius.
-- `--choice-card-check-size` — size of the check indicator.
+- `--choice-card-check-size` — size of the indicator, and the width of its
+  column.
+- `--choice-card-border` / `--choice-card-bg` — resting border and background;
+  the checked state and hover rebind them, so a checked override needs
+  `:has(:checked)`.
+- `--choice-chip-dot` — read-only: the chip's check-slot centre as a `circle()`
+  position. It is declared on the chip's `::before`, so read it in a
+  `.choice-card.chip…::before` rule.
 
 Plain `.check` / `.radio` controls expose two hooks:
 

package/docs/pages/forms/combobox.md

@@ -10,7 +10,7 @@ real product needs a JavaScript combobox (searchable select, removable tags,
 autocomplete suggestions), load a dedicated component and bridge its custom
 properties onto Actual's tokens.
 
-**Related terms:** combo box, combobox, autocomplete, datalist, searchable select, enhanced select, multiple select, tags, chips, tag input, pill input.
+**Related terms:** combo box, combobox, autocomplete, datalist, select, custom select, native select, searchable select, enhanced select, multiple select, dropdown, form controls, tags, chips, tag input, pill input.
 
 ## Theme bridge
 
@@ -36,6 +36,21 @@ mix tokens.
 
 The card in the template documents the full token map of this recipe.
 
+## Bridge contract
+
+Actual owns the visual language; the widget owns the behavior. Actual provides
+surface, border, radius, inset focus outline, danger state, `.join` corners,
+and the contrast contracts those tokens carry. The widget provides search,
+keyboard navigation, multi-value state, removable tags, and option rendering.
+The bridge CSS stays in docs/demo — it is a recipe, not package API, so no
+`actual-combobox.css` ships with the framework and no widget version is pinned
+by it.
+
+Multi-value and i18n (for example a "n selected" summary string) are widget
+configuration: pass locale strings and tag rendering through the widget's own
+options, and keep skinning on the `--cb-*` tokens so light/dark mode and preset
+themes keep applying for free.
+
 ## Lightweight pass-through
 
 Most of the skin is three one-line token bridges. The visible vocabulary —
@@ -47,7 +62,7 @@ contrast contracts apply to the combobox for free:
 .actual-combobox {
   --cb-bg: var(--surface);
   --cb-color: var(--text);
-  --cb-border-color: var(--border);
+  --cb-border-color: var(--form-invalid-border, var(--border));
   --cb-border-radius: var(--radius);
   --cb-focus-color: var(--focus);
   --cb-muted-color: var(--text-muted);
@@ -57,15 +72,23 @@ contrast contracts apply to the combobox for free:
   --cb-option-min-height: var(--control-size);
 }
 
-.actual-combobox .cb-control:focus-within,
-.actual-combobox .cb-text-control:focus {
-  outline: 2px solid transparent;
-  box-shadow: var(--focus-ring-shadow);
+.actual-combobox :is(.cb-text-control:focus-visible, .cb-control:has(.cb-input:focus-visible)) {
+  border-color: var(--form-invalid-border, var(--cb-border-color));
+  outline: var(--focus-ring-width) solid var(--form-invalid-border, var(--focus));
+  outline-offset: calc(var(--focus-ring-width) * -1);
+  box-shadow: none;
+}
+
+.actual-combobox :is(.cb-text-control[aria-invalid="true"], .cb-control:has([aria-invalid="true"])) {
+  --form-invalid-border: var(--danger);
+}
+
+:where(.actual-combobox) combo-box {
+  border-radius: var(--cb-border-radius);
 }
 
-.actual-combobox .cb-chip-remove:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: 0 0 0 2px var(--focus-ring);
+.actual-combobox :is(.cb-control, .cb-text-control) {
+  border-radius: inherit;
 }
 
 .actual-combobox .cb-chip {
@@ -79,9 +102,13 @@ contrast contracts apply to the combobox for free:
 }
 ```
 
-The composite focus ring follows any internal focus, not just the search
-input: focus a chip or its remove × and the control shows the same field ring,
-with the local `:focus-visible` indicator on the chip or its × on top.
+While the search input is focused, the control takes the same inset outline as
+`.input` in place of the library's accent border and outer halo; a focused chip
+or remove × keeps the library's own inner ring. Being inset, the outline needs
+no adaptation inside `.join`: `combo-box` owns the radius at zero specificity,
+so the join gives it the group corners and the visible control inherits them. The invalid rule sets `--form-invalid-border`,
+the hook `.field.danger` and `aria-invalid` already use, so border and outline
+turn danger together.
 
 The same approach works for any widget that exposes a custom-property skin —
 keep the widget's behavior, restyle its tokens through the shared vocabulary.

package/docs/pages/forms/joined-controls.md

@@ -29,11 +29,8 @@ When composing source files manually, import `components/join.css` after the con
 </div>
 ```
 
-`.join` handles border-radius and border collapsing between adjacent children. It works with any direct child — `.input`, `.btn`, `.select`, or `.join-addon`.
-When an `.input`, `.textarea`, or `.select` receives keyboard-relevant focus,
-the focus ring surrounds the complete joined field. Attached buttons keep their
-own focus indicator when reached directly, so the actionable segment remains
-identifiable.
+`.join` handles border-radius and border collapsing between adjacent children. It works with any direct child — `.input`, `.btn`, `.select`, or `.join-addon` — plus one wrapper level (e.g. a combobox element around the native control): the wrapper receives the group corners and the inner control inherits them via `border-radius: inherit`.
+When an `.input`, `.textarea`, or `.select` receives keyboard focus, it keeps its own inset focus outline; the group never moves the ring onto itself, so the focused segment remains identifiable.
 
 ## Linting `role="group"`
 

package/docs/pages/forms/overview.md

@@ -10,6 +10,9 @@
 - `.field-group` and `.choice` provide layout without depending on parent scope.
 - Customizable select is progressive enhancement only — the native select remains the baseline.
 - Searchable selects, tags and autocomplete are a JavaScript widget concern; theme an external combobox with Actual tokens — see the [combobox template](../../demo/templates/combobox.html).
+- Formatted text (bold, lists, links) is a hosted-editor concern; the native textarea stays the baseline and an external engine is themed the same way — see the [rich-text template](../../demo/templates/rich-text.html) and the [composer template](../../demo/templates/composer.html) for the plain-text case.
+
+**Related terms:** form controls, select, custom select, dropdown, input, textarea, checkbox, radio.
 
 ## Class reference
 
@@ -165,6 +168,12 @@ A full form using the control classes, field wrappers, and form actions:
 </form>
 ```
 
+## Hooks
+
+Set `--control-hover-border` to tune the hover border of `.input` and `.textarea`.
+Set `--control-hover-bg` to keep a `.select` background steady on hover, or give
+it a stronger fill.
+
 ## Notes
 
 - `required` is enough on native inputs. `aria-required="true"` is redundant and not used in these examples.
@@ -175,7 +184,7 @@ A full form using the control classes, field wrappers, and form actions:
 - Use native `<optgroup>` and `disabled` options in `.select` controls when applicable; the customizable picker preserves both as a progressive enhancement.
 - `.choice` is the choice-label API. Use `.check` or `.radio` on the nested control. The control goes first, the label group second, so multi-line labels align the control with the first line.
 - For a switch, use `class="switch"` and `role="switch"`.
-- Core range controls stay native and are enhanced by `accent-color`. An optional richer range skin may come later if real projects need it.
+- `.range` skins the native range control (`appearance: none` track, thumb, and focus ring). Add `data-enhance="range"` for the fill share, named `datalist` values, and output sync.
 - `.form-actions` carries a default top margin. Override it with `--form-actions-margin-block-start`, `--form-actions-align`, or `--form-actions-justify`. It is class-only and may live inside or outside `<form>`. See Detached Actions below.
 - `.join` visually joins adjacent controls into a single unit. Use `.join-addon` for static prefix/suffix content. The container still carries `role="group"` for accessibility.
 

package/docs/pages/forms/range.md

@@ -12,14 +12,117 @@ rather than the CSS box.
 ```html demo
 <label class="field">
   <span class="field-label">Volume</span>
-  <input class="range" type="range" min="0" max="100" value="50" />
+  <input class="range" data-enhance="range" type="range" min="0" max="100" value="50" />
 </label>
 ```
 
-Actual deliberately does not emulate filled tracks, tick marks, value labels,
-or multi-thumb ranges. Those still require engine-specific pseudo-elements or a
-value duplicated out of the HTML into CSS. Prefer the platform as richer range
-styling becomes interoperable — see
+## Fill
+
+`data-enhance="range"` opts into the `actual-css/js/range` behavior. It writes
+`--range-progress`, the fill share the track gradient reads, and keeps it in
+sync on input and after a form reset, including inputs associated through
+`form="…"`. Without it the variable stays at its `0%` default and the track
+renders plain — the control stays fully usable without JavaScript. The fill
+follows the writing direction, and a bare `input[type="range"]` without the
+`.range` class can opt in the same way.
+
+## Named values
+
+A `datalist` is the source of truth for discrete named steps: positions plus
+names. Browsers render its ticks and labels inconsistently, so Actual never
+depends on their presentation — the enhancement only reads `option` values and
+their `label`. A matching label sets `aria-valuetext` on the input and mirrors
+into each `<output for="…">`. The output is the visible value, not the input's
+name — give the input its own accessible name, since `for` only declares the
+output's operands.
+
+```html demo
+<div class="field">
+  <output class="field-label" for="effort">High</output>
+  <input
+    class="range"
+    data-enhance="range"
+    id="effort"
+    type="range"
+    min="0"
+    max="3"
+    step="1"
+    value="2"
+    list="effort-levels"
+    aria-label="Effort"
+  />
+  <datalist id="effort-levels">
+    <option value="0" label="Minimal"></option>
+    <option value="1" label="Standard"></option>
+    <option value="2" label="High"></option>
+    <option value="3" label="Maximum"></option>
+  </datalist>
+</div>
+```
+
+`aria-valuetext` is the announced value when a number really means a text; keep
+it even if the visible `output` changes shape. An `output` is a live region,
+so verify with a screen reader that the two do not double-announce.
+
+## In a flyout
+
+The range stays an `input`, the flyout stays a flyout — together they read as
+a richer picker with no new component. `data-flyout-auto-close="outside"` keeps
+dragging the slider from closing the panel.
+
+```html demo
+<div class="flyout-trigger">
+  <button
+    class="btn outline"
+    type="button"
+    data-enhance="flyout"
+    aria-expanded="false"
+    aria-controls="effort-picker"
+  >
+    Reasoning effort
+  </button>
+
+  <div
+    class="flyout"
+    id="effort-picker"
+    data-flyout-auto-close="outside"
+    style="--flyout-inline-size: 16rem; --flyout-pad: var(--space-40)"
+    hidden
+  >
+    <div class="field">
+      <output class="field-label text-center" for="effort-flyout">High</output>
+
+      <input
+        class="range"
+        data-enhance="range"
+        id="effort-flyout"
+        type="range"
+        min="0"
+        max="3"
+        step="1"
+        value="2"
+        list="effort-flyout-levels"
+        aria-label="Reasoning effort"
+      >
+
+      <datalist id="effort-flyout-levels">
+        <option value="0" label="Minimal"></option>
+        <option value="1" label="Standard"></option>
+        <option value="2" label="High"></option>
+        <option value="3" label="Maximum"></option>
+      </datalist>
+    </div>
+
+    <div class="cluster" style="--cluster-justify: center">
+      <button class="btn primary sm" type="button" data-flyout-close>Done</button>
+    </div>
+  </div>
+</div>
+```
+
+Actual deliberately does not emulate tick marks or multi-thumb ranges. Ticks
+still need engine-specific pseudo-elements; the fill above is designed for
+deletion once `::slider-fill` is interoperable — see
 [Enhanced range controls](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/platform-alignment.md).
 
 ## CSS hooks
@@ -28,3 +131,5 @@ styling becomes interoperable — see
 - `--range-track-height` — track thickness.
 - `--range-thumb-bg` — thumb color. Defaults to the local intent, then `--primary`.
 - `--range-track-bg` — track color.
+- `--range-fill-bg` — filled portion color. Defaults to the local intent, then `--primary`.
+- `--range-progress` — fill share. Written by `actual-css/js/range`, never set by hand.

package/docs/pages/forms/rich-text.md

@@ -0,0 +1,110 @@
+# Rich text
+
+> A rich-text editor is not shipped by the framework — the native `<textarea>` stays the baseline. Enhance it with a dedicated engine, themed with Actual tokens.
+
+Use a `<textarea>` while editing text, and a hosted editing engine as soon as
+editing means a document (formatting, lists, links, mentions). The
+[rich-text template](../../demo/templates/rich-text.html) enhances a textarea
+with [@lekoala/rich-text](https://github.com/lekoala/rich-text) (Squire
+underneath): the package generates the toolbar with its roving tabindex,
+states, commands and lifecycle, while Actual maps its visual language onto the
+package's `--rt-*` tokens. No adapter, no compatibility layer.
+
+**Related terms:** rich text, richtext, WYSIWYG, HTML editor, formatted text, Squire, ProseMirror, Tiptap, text formatting, bold italic, mentions, slash commands.
+
+## Theme bridge
+
+The template loads the package JS and CSS from a CDN (`@0.2` caret range) and
+declares one editor per field — Actual never builds toolbar buttons or calls
+into the editing engine:
+
+```html
+<div class="field actual-rich-text">
+  <label class="field-label" for="note">Team note</label>
+  <rich-text id="note-editor">
+    <textarea class="textarea" id="note" name="note" required placeholder="Write a note…"></textarea>
+  </rich-text>
+  <span class="field-help">Bold, italic, lists, quotes and links.</span>
+</div>
+```
+
+```js
+editor.options = {
+  buttons, // Tabler icons as Nodes, never HTML strings
+  requestLink, // an Actual <dialog> replacing window.prompt()
+  suggestions, // static @people and /snippets providers
+};
+```
+
+The bridge maps tokens; it does not restyle the editor's internals:
+
+```css
+.actual-rich-text .rt-shell {
+  --rt-bg: var(--surface);
+  --rt-fg: var(--text);
+  --rt-border: var(--form-invalid-border, var(--control-border, var(--border)));
+  --rt-divider: var(--border);
+  --rt-focus: var(--form-invalid-border, var(--focus));
+  --rt-toolbar-bg: var(--surface-subtle);
+  --rt-button-pressed-bg: var(--state-selected);
+  --rt-link: var(--primary);
+  --rt-suggestion-bg: var(--surface-raised);
+  --rt-suggestion-shadow: var(--shadow-popout);
+}
+```
+
+The card in the template documents the full token map of this recipe. The
+suggestion popover is a child of `.rt-shell`, so it inherits the tokens like
+the rest of the editor. `--rt-border` paints only the field frame, so the
+invalid and hover hooks never reach the toolbar separators or the quote bar,
+which follow `--rt-divider`.
+
+## Bridge contract
+
+`@lekoala/rich-text` owns the editor UI semantics — progressive enhancement,
+sanitization, toolbar behaviour and keyboard, links, `@mentions`, `/`
+suggestions, form/reset/readonly/disabled integration, selection and undo
+lifecycle. Actual owns presentation and composer chrome — tokens, visual
+states, dialogs, attachments, send, `Ctrl/Cmd+Enter`.
+
+Formatting buttons stay local to the editor instance. The stateless `command`
+router never drives bold/italic: those depend on selection, schema and history,
+which only the engine knows. Reserve `command` for the chrome around the
+editor (attach, template, dictate, send).
+
+A rich composer reuses `.composer` and `.composer-actions` for the outer
+surface; the bridge only lifts the editor and toolbar into the composer grid
+with `display: contents` and grid areas. `composer.css` itself never knows
+about `.rt-*`. The plain-text [composer template](../../demo/templates/composer.html)
+stays the canonical pattern when editing means text, not a document.
+
+People lookup and templates are application concerns: the demo wires static
+arrays into the package's suggestion seam, and the composer buttons type
+`@`/`/` so the providers do the rest. Attachments stay composer-owned —
+logged, never serialized into the HTML.
+
+## Storage and sanitization
+
+The form submits limited HTML, not engine state: portable, readable,
+editor-independent, reversible. Sanitization is mandatory inside the package
+and not configurable; the client-side sanitizer is a UI boundary, not the
+persistence security boundary — sanitize again on the server before storing or
+rendering untrusted content. An editor holding only the empty block serializes
+to `""`, so native `required` keeps working.
+
+If the product later needs truly structural content (custom document nodes,
+annotations, collaboration), a schema-based engine becomes interesting — see
+the [rich-text design note](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/rich-text.md).
+
+## Baseline traps
+
+The textarea is the value owner and the no-JS fallback, holding raw HTML. Two
+details keep it honest:
+
+- Without the integration script the page remains a plain textarea — the link
+  dialog wiring and the suggestion providers only exist once the package
+  loads, and the composer falls back to plain-text send.
+- `required` cannot sit usefully on a hidden textarea: mirror validity with
+  `aria-invalid` on submit (the package emits `richtext:invalid` and focuses
+  the editor when it is the form's first invalid control), and let the bridge
+  re-own the danger hook from there.

package/docs/pages/forms/validation.md

@@ -55,7 +55,11 @@ Native validation first; the enhancer only adds state and focus behavior.
 
 Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the full runtime (`actual-css/js/full`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
 
-Opt in with the `.needs-validation` class. Importing the module registers the behavior; there is no init call.
+Opt in with `data-enhance="validation"` on the form; `.needs-validation` alone
+only enables the CSS feedback. Importing the module registers the behavior;
+there is no init call. To opt in forms you cannot mark up, call
+`applyEnhancement("validation", "form.needs-validation")` from
+`actual-css/js/enhance`.
 
 ```html demo
 <form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">