@vanelsas/baredom 4.0.0-alpha.0 → 4.0.0

package/CHANGELOG.md

@@ -2,15 +2,351 @@
 
 All notable changes to BareDOM will be documented in this file.
 
-## [4.0.0-alpha.0] - 2026-06-03
+## [4.0.0] - 2026-10-08
+
+BareDOM 4 makes every component follow the theme, gives every attribute a typed property, and
+brings BareMirror as an alpha. A page looks different after this upgrade, with and without
+`x-theme`, which is why it is a major version.
+
+All five adapters are released with it: `-react` 3.0.0, `-angular` 3.0.0, `-vue` 0.6.0, `-svelte`
+0.6.0 and `-solid` 0.6.0. Each now requires `@vanelsas/baredom` 4.0.0 or later.
+
+### Breaking
+
+- **The look under `x-theme`.** Ten families of values follow the theme where they were fixed
+  before. See "Changed" below for what moves.
+- **The font, also without a theme.** Buttons, inputs, selects and text areas inside components
+  take the font of the page. `x-typography` and `x-kinetic-typography` show the page font, where
+  they showed the system font.
+- **`hidden` hides a component.** 101 components ignored the attribute. A page that set `hidden`
+  on one of them and relied on it showing must remove the attribute.
+- **Seven properties lost their dashed names.** `x-pagination` (`totalPages`, `siblingCount`,
+  `boundaryCount`) and `x-breadcrumbs` (`maxItems`, `itemsBefore`, `itemsAfter`,
+  `preserveAriaCurrent`) installed these under the names of their attributes, such as
+  `el["total-pages"]`. They are now installed under the camel-case names that the docs and the
+  types always gave. The attributes are unchanged.
+- **`x-form-field` in the adapters: `readonly` is `readOnly`.** The adapters now use the name
+  the element installs.
+- **A boolean property that is on by default reads the text `"false"` as false.** A framework
+  that writes `dismissible="false"` to `x-alert` through the property now turns it off.
+- **The `code` property of `x-code` writes the attribute.** The component no longer keeps the
+  value in a field of its own, so an attribute written later wins.
+- **`--x-z-toast` is 9000, was 1200.** Under a theme, dialogs are at 1100 (were 1000),
+  `x-command-palette` at 1100 (was 800), the tooltip of `x-copy` at 1000 (was 100) and
+  `x-notification-center` at 9000 (was 9999).
+- **The supported browsers are the current ones.** BareDOM is tested in Chrome and Edge 154,
+  Firefox 157 and Safari 26.5. The floor of Chrome 67, Firefox 63 and Safari 14 is dropped.
+- **Four `data-*` attributes of `x-timeline-item` left the manifest.** The parent writes them,
+  and they are not public API.
 
-**Pre-release — published on the npm `alpha` dist-tag (`npm install @vanelsas/baredom@alpha`). The stable `latest` line is unaffected, and `^3.x` ranges never resolve this version.** First preview of the BareBuild **write-side** coordination elements, designed-by-use from the Phase-4 demo port. These are **experimental — attribute shapes may change before 4.0.0** (the no-selectors / values-not-places spine will not). See `barebuild/docs/write-side-design-notes.md`.
+### Added
+
+- **BareMirror, as an alpha.** A small set of functions for an application on top of the
+  components. They place keyed nodes, write values into the parts of a template and turn events
+  into messages, with no comparing of old and new. `@vanelsas/baredom/baremirror-alpha` for
+  JavaScript, and the namespaces `baremirror.alpha.*` for ClojureScript. A name there may still
+  change. See [`docs/baremirror.md`](docs/baremirror.md).
+- **The requests map.** `@vanelsas/baredom/requests` and `baredom.requests` say, for each
+  cancelable request event, which attributes it asks to change. The manifest gives every event
+  its cancelable flag and every request its attributes.
+- **A typed property for every public attribute.** 79 new properties in 16 components, and
+  `counter` and `dots` on `x-welcome-tour`. The manifest types every attribute, and a number
+  property accepts numeric text, as a native one does.
+- **A change request on two text fields.** `x-form-field-change-request` and
+  `x-search-field-change-request` fire before a typed value takes effect. A cancelled request
+  puts the field back to its `value` attribute.
+- **Eight theme tokens.** `--x-radius-xl`, `--x-font-weight-bold`, and a `-hover` and an
+  `-active` shade for `--x-color-danger`, `--x-color-success` and `--x-color-warning`. The shades
+  are mixed from their colour, so a preset that names only the colour gets matching shades.
+- **A hold of the render.** Every element offers a way to hold its attribute changes and to
+  deliver them in order, for code that must write several attributes as one step.
+- **A script that prerenders a page**, `scripts/prerender.mjs`. See
+  [`docs/PRERENDER.md`](docs/PRERENDER.md).
+- **Two documents.** [`docs/styling.md`](docs/styling.md) says at which level to style and where
+  each value must be set to work. [`docs/TOKEN-COVERAGE.md`](docs/TOKEN-COVERAGE.md) counts, for
+  each component, how many values follow the theme.
+
+### Changed
+
+Under `x-theme`, these values now follow the theme:
+
+- **Colour.** A custom danger, success, warning or primary colour reaches alerts, badges,
+  toasts, selected tabs and rows. Hover fills and tints are mixed from the theme's colours. A
+  disabled `x-button` is a pale surface with muted text. The hover and pressed colour of a
+  danger, success or warning button shifts slightly.
+- **Corners.** 27 components take the theme's scale.
+- **Motion.** Every triggered transition takes the theme's duration and easing.
+- **Shadows.** They follow the theme, in dark mode too.
+- **Type.** The font family, the weights and the body line height follow the theme. Text of
+  13px and 15px is 14px, and the sizes of buttons and badges follow the scale.
+- **Borders.** Edges, inputs and divider lines follow `--x-border-width`.
+- **Layers.** Popups, dialogs and toasts sit on the three layers of the theme.
+
+Also changed:
+
+- A removed chip of `x-multi-combobox` fades out.
+- The default cells in the component docs are generated from the manifest.
+
+### Fixed
+
+- **Lists keep their nodes.** Ten lists no longer rebuild their items on every change, so a
+  node that stays keeps its focus: the pages of `x-pagination`, the chips and options of
+  `x-multi-combobox`, the options of `x-combobox`, the steps of `x-stepper`, the dots of
+  `x-scroll`, the day cells of `x-calendar` and `x-date-picker`, the items of
+  `x-command-palette` and the rows of `x-file-upload`.
+- **`x-table` honours a cancelled row select.** It changed the selection in every case.
+- **`x-form-field` and `x-search-field` keep typed text** on a write of the value they already
+  have.
+- **`x-progress` and `x-progress-circle` drop `aria-valuemax`** when they become indeterminate.
+- **`x-form`, `x-otp-input` and `x-search-field` set up on a prerendered page.** They took a
+  shadow root that was already there as a sign that they were set up.
+- **Three documents no longer show a component's own property set on `:root`**, where it has no
+  effect.
+
+This release contains the two fixes of 3.12.1.
+
+## [3.12.1] - 2026-10-08
+
+### Fixed
+
+- **`x-multi-combobox` reports no `NotFoundError` when a chip is removed with the pointer.** A
+  click on the remove button of a chip, while the panel was open, moved focus into that chip.
+  Removing the chip then closed the panel from inside the render, and the browser reported
+  `Failed to execute 'removeChild' on 'Node'`. The selection was correct, but an ordinary gesture
+  left an error in the console. Focus now moves to the input before the chip leaves, so the panel
+  stays open and focus stays in the control. (#376)
+
+- **`x-currency-field` keeps `value` current while the user types.** The `value` attribute was
+  written on change only, so the property was stale during an edit, and with it the values that
+  `x-form` collects on a submit with Enter. The attribute now follows each keystroke. (#264)
+
+  Three things follow from that:
+
+  - The inline message for a bad number or a value out of range waits while the user types, and
+    shows on change or blur. Validity itself follows each keystroke, as before.
+  - The display is formatted on every blur, also when the value did not change.
+  - On a change, `previousValue` of `x-currency-field-change-request` is the typed text. It was
+    the value before the edit.
+
+## [3.12.0] - 2026-09-15
+
+### Added
+
+- **`x-file-download` saves through the native save dialog.** A new `picker` attribute makes a
+  click open `showSaveFilePicker`, so the user chooses the folder and the name. The component
+  then fetches `href` and streams it into the chosen file, and reports the outcome as
+  `x-file-download-success`, `x-file-download-cancel` or `x-file-download-error` with the failing
+  phase. Browsers without the API, such as Firefox, Safari and Brave, keep the plain download, as
+  do cross-origin frames and a dialog that cannot open. `picker` is off by default, so existing
+  pages are unchanged.
+
+  All five adapters gain the `picker` prop and the three events: `-react` 2.5.0, `-angular`
+  2.11.0, `-vue` 0.5.0, `-svelte` 0.5.0, `-solid` 0.5.0.
+
+## [3.11.0] - 2026-08-28
+
+### Fixed
+
+- **Event detail keys are published as the component dispatches them.** `x-particle-button`
+  dispatches `#js {:press-x … :press-y …}`, so those are the keys on the event, but the generated
+  types camel-cased them and promised `pressX` and `pressY`. Every typed caller read a field that
+  is not there. The `.d.ts`, `custom-elements.json` and all five adapters now say `"press-x"`,
+  quoted because a hyphenated key is not a bare identifier in a TypeScript type.
+
+  This supersedes the detail half of the 3.3.0 fix "TypeScript declarations", which corrected the
+  same invalid identifiers by renaming them. That made the types compile and made them wrong.
+  Property names are unaffected and still camel-case, because a property reflects an attribute and
+  genuinely changes spelling.
+
+  Breaking for anyone writing `e.detail.pressX` — which never resolved to anything. Only
+  `x-particle-button` is affected; no other component has a kebab-case detail key. Every adapter
+  published the wrong key, so all five are released with it: `-react` 2.4.1, `-angular` 2.10.1,
+  `-vue` 0.4.2, `-svelte` 0.4.2, `-solid` 0.4.1.
+
+### Added
+
+- **`detail` on every event in `custom-elements.json`** — what an event carries, as data, beside
+  the TypeScript in `type.text`. A reader no longer parses a type expression to learn the shape.
+  Both come from one function, so they cannot disagree.
+
+### Changed
+
+- **`scripts/check_event_api.bb` also compares the manifest with the model.** It read the model on
+  both sides, so anything the generator did between them was invisible — which is how the
+  camel-casing above survived it. It now compares names and types over the union of both sides, so
+  a schema edited without regenerating is caught too.
+
+## [3.10.0] - 2026-08-28
+
+### Changed
+
+- **`x-date-picker` change details are one shape in both modes.** `x-date-picker-change` and
+  `x-date-picker-change-request` carried a different key set per mode — `value` in single mode,
+  `start` and `end` in range mode, and `date` on a range click — while `event-schema` declared only
+  the first. Every key is now always present and `null` where the mode has nothing to say, so the
+  declaration is true and a handler null-checks instead of testing for a key that was never there.
+
+  This widens the published types from `string` to `string | null` for `value`, `date`, `start` and
+  `end` on those two events, in `custom-elements.json`, the `.d.ts` files and all five framework
+  adapters. A consumer writing `const v: string = e.detail.value` will need a null check. Nothing
+  about when the events fire has changed.
+
+### Fixed
+
+- **The Svelte and Vue adapters no longer write `"null"` into a bound value.** Released as
+  `@vanelsas/baredom-svelte` 0.4.1 and `@vanelsas/baredom-vue` 0.4.1. Both coerced the
+  change detail unconditionally — `String(detail.value)`, `Number(detail.page)` — so a detail field
+  that did not apply arrived as the literal string `"null"` in `bind:value` / `v-model` and was
+  written back onto the element as an attribute. They now write only when the field is present.
+  `false`, `0` and `""` are values and still write; only `null` and `undefined` are skipped.
+  Affects the twelve form controls in each adapter. React, Solid and Angular do not write back and
+  were never affected.
+
+### Added
+
+- **`scripts/check_event_api.bb`** — a CI check that reads each component's dispatch calls and
+  asserts the manifest's event details agree with them. It reads forms rather than text, follows a
+  detail through a `let`, a helper, a namespace alias and `clj->js`, and reports what it could not
+  read rather than counting it as agreement. 198 of 201 events are compared; the three it cannot
+  resolve are named. It is what found the `x-date-picker` mismatch above.
+
+## [3.9.0] - 2026-08-26
+
+The manifest declares `schemaVersion 1.0.0` and omitted three fields the schema defines. It now
+publishes all three, so an editor reading `custom-elements.json` completes attributes and custom
+properties that it previously knew nothing about.
+
+### Added
+
+- **`attributes`** — every attribute a component observes. An attribute that a `property-api`
+  entry reflects also carries that property's type and field name. The rest carry a name alone,
+  because the component states no type for them. 809 attributes across 108 components, 480 of
+  them typed. `observed-attributes` names symbols rather than strings, so each one is resolved
+  through the model's own constants: a symbol that escaped resolution would publish `attr-columns`
+  as if it were an attribute name.
+
+- **`cssProperties` and `cssParts`** — the custom properties a component reads and the parts it
+  exposes, read from the implementation source that writes them rather than from a second
+  declaration. A property is owned by the longest tag that prefixes it, so `--x-table-cell-padding`
+  belongs to `x-table-cell` and not to `x-table`. 1351 properties and 489 parts.
+
+- **`scripts/check_css_api.bb` and `scripts/check_attribute_api.bb`** — CI checks that read each
+  component crudely and assert the manifest agrees. Each is written to avoid the assumption its
+  extractor makes, because a check that shares one agrees with the bug.
+
+### Notes
+
+- **`src/` is unchanged**, so the ESM bundles, the framework adapters and the compiled namespaces
+  in the jar are identical to 3.8.0. Only the manifest grew.
+
+## [3.8.0] - 2026-08-14
+
+### Added
+
+- **`baredom.dev.pick`** — a dev-only namespace for pointing at elements from a REPL, in both directions. `pick!` puts the page into click-to-select and answers with a stable `tag#n` id for whatever is clicked, `element-for` resolves that id back to an element, and `show!` outlines where it is. The id is minted here rather than reused from `x-trace-history`'s component id, which is an integer assigned inside the trace hook and only exists while the recorder is installed, because picking has to work with tracing off. Ids are numbered per tag in document order, so `x-table-cell#7` is the seventh cell on the page rather than the seventh one clicked, and an id survives a re-projection replacing the node.
+
+### Notes
+
+- **Nothing here is reachable from a component**, and no custom element is registered, so the ESM bundle and the framework adapters are unchanged. The namespace ships in the Clojars jar alongside the other `baredom.dev` namespaces and is not exported to npm.
+
+## [3.7.1] - 2026-08-12
+
+### Fixed
+
+- **`x-drop-zone`** no longer animates a panel in from the top-left corner. `animate-moves` measured panels with `getBoundingClientRect`, which returns `(0,0)` inside a `display: none` subtree, so a panel captured while hidden flew in from the viewport origin once shown. The FLIP decision is now a pure `flip-delta` that returns nil when either box was measured with zero size, and nil when the panel did not move.
+
+## [3.7.0] - 2026-07-30
+
+Two new components that work as a pair: a panel the user can pick up and a region that accepts it. Together they cover kanban boards, sortable lists, and any interface where something is moved from one place to another.
+
+### Added
+
+- **`x-drag-panel`** — a surface the user picks up with a pointer or the keyboard, with a grip handle over a body slot. Built on pointer events rather than the HTML5 drag-and-drop API, which never fires from touch input on iOS or Android, so it works from 320px up. `grab` chooses whether the whole card is a drag target or only the handle bar; in surface mode a touch drag arms after a short press and cancels if the finger travels first, so swiping over a card still scrolls the board. Dragging toward the edge of a scrollable ancestor auto-scrolls it, resolving the vertical and horizontal scrollers independently so a board that scrolls sideways with columns that scroll down works in both axes at once. Emits `x-drag-panel-drag-start` and `x-drag-panel-drag-cancel`.
+
+- **`x-drop-zone`** — a region that senses panels passing over it, renders an insertion caret where one would land, and reports the drop. Acceptance is declarative: `accepts` matches the panel's `kind` and `max` caps capacity, so a full or incompatible zone shows a reject cue during the hover rather than silently ignoring the drop. `animate-moves` animates children into place whenever the child list changes, which covers drop confirmations, another client's change arriving over a websocket, and filter toggles with one mechanism. Emits `x-drop-zone-enter`, `x-drop-zone-leave`, and `x-drop-zone-drop`.
+
+### Notes
+
+- **Neither component moves a node.** A drop is a request, not a fact — an app may validate it locally and refuse, queue it offline, or send it to a server that reorders differently. The components sense and report; the application owns the landing. `x-drop-zone-drop` carries `{ kind, value, from, to, index, panel }`, where `value` identifies the panel and `from` / `to` are the two zones' `value`s, so a server-backed handler works entirely in opaque strings and never holds an element across a round trip. `from` is `null` when the panel came from outside any zone, distinct from `""` for a zone with no `value`, and is typed `string | null` so the check is not optional.
+
+- **For moves that need confirming**, `zone.reserve(panel, index)` marks the in-flight window and `zone.release()` clears it. The panel renders an empty dashed footprint that keeps its box and the zone renders a reserved caret, so nothing in the layout moves until the answer arrives — every real reflow happens once, when the truth does. Nothing times out: a stalled move stays visible and keyboard-reachable rather than becoming a lost card. The underlying `pending` and `pending-index` attributes remain author-settable for apps that prefer to drive them directly.
+
+### Accessibility
+
+- The full interaction is keyboard-operable, which WCAG 2.2 SC 2.5.7 (Dragging Movements) requires of any drag: <kbd>Space</kbd> picks a panel up from its handle, arrows cycle the accepting zones in document order and scroll each into view, <kbd>Enter</kbd> drops, <kbd>Esc</kbd> cancels. Pointer and keyboard produce the same `x-drop-zone-drop` detail, so a consumer handles one path rather than two.
+
+- Focus moves to the destination zone on commit rather than riding the panel, because a confirmation re-render will often replace the panel element and focus would fall to `<body>`. Each component narrates the events it owns into a visually hidden live region; the panel's is created lazily at pickup so a fifty-card board carries no idle `aria-live` nodes. Whether a move succeeded is read back from the DOM rather than assumed, so a server that refused is announced honestly.
+
+- Auto-scroll is deliberately **not** disabled under `prefers-reduced-motion` — it is function rather than decoration, and a board deeper than the viewport would otherwise be unusable for the people relying on that setting. The lift transition, caret pulse, and `animate-moves` all are.
+
+- The framework adapters gain generated `x-drag-panel` and `x-drop-zone` wrappers. They version on their own cadence — see [`docs/RELEASING.md`](docs/RELEASING.md) — so releasing them is a separate step.
+
+## [3.6.0] - 2026-07-27
+
+One new component: a floating, draggable container for inspectors, tool palettes, mini-players, and any persistent surface the user should be able to move out of the way.
+
+### Added
+
+- **`x-floating-panel`** — a non-modal container that floats above page content at a viewport-fixed position and is repositioned by dragging its handle bar or, when the handle has focus, with the arrow keys. Position lives in the `x` / `y` attributes, so a panel renders where you declared it on first paint with no measure-then-place flash, and clamping keeps the handle reachable whenever the panel opens, connects, moves, or the viewport resizes — a panel parked off-screen is pulled back rather than stranded. Optional `closable` (close button plus `Escape`), `resizable` (native CSS resize grip on the body), `focus-on-open` (off by default, so an ambient panel never steals focus from what the user is typing in), and `step` for arrow-key distance. Emits `x-floating-panel-toggle`, a cancelable `x-floating-panel-dismiss-request`, and `x-floating-panel-move` on drag end and keyboard nudge — never per animation frame.
+
+### Accessibility
 
-### Added — write-side ALPHA
+- The handle bar is keyboard-operable, which WCAG 2.2 SC 2.5.7 (Dragging Movements) requires of any drag interaction. It is focusable and carries `aria-roledescription="Drag handle"` plus `aria-keyshortcuts`, because the handle is moved rather than activated and a bare `role="button"` would promise an activation that never happens. The panel is a non-modal `role="dialog"` with no focus trap, always accessibly named from the `header` slot or the `label` attribute.
+
+### Notes
+
+- Interactive content in the `header` slot can opt out of the drag surface with `data-no-drag`; the built-in close button is excluded automatically.
+- The framework adapters gain a generated `x-floating-panel` wrapper. They version on their own cadence — see [`docs/RELEASING.md`](docs/RELEASING.md) — so releasing them is a separate step.
+
+## [3.5.0] - 2026-07-24
+
+Form-associated components gain the instance-level validation API they were missing, and two form-control bugs are fixed: emptying an `x-date-picker` input now clears the committed date, and a form reset now clears validation errors.
+
+### Added
+
+- **The native validation API on all 17 form-associated components** — read-only `validity`, `validationMessage`, `willValidate`, `form` and `labels`, plus `checkValidity()` and `reportValidity()`. `ElementInternals` never mirrors these onto the host element, so only `x-search-field`, `x-currency-field`, `x-otp-input` and `x-file-upload` exposed any of it (the two methods), and every other control could be validated only by attempting a submit. `x-checkbox`, `x-color-picker`, `x-combobox`, `x-date-picker`, `x-form-field`, `x-multi-combobox`, `x-radio`, `x-range-slider`, `x-rating`, `x-select`, `x-slider`, `x-switch` and `x-text-area` now expose the full surface, and the four above are extended to match.
+
+### Fixed
+
+- **`x-date-picker` ignored a cleared input.** Deleting the text and committing it (blur, `Enter`, or `commit()`) left the previous date committed and repainted the old text — there was no way to clear the field from the keyboard. It now clears the value through the same cancelable `x-date-picker-change-request` path a normal commit uses, reports empty strings in the change detail (`{ value: "" }`, or `{ start: "", end: "" }` in range mode), and resets the range step so a half-picked range cannot complete against a start that no longer exists. Committing a blank input when nothing is committed stays a no-op.
+- **`form.reset()` left stale validation errors.** Reset cleared the value but not the `error` attribute, so the inline message, `data-invalid`, `aria-invalid` and the `customError` flag survived it on `x-date-picker`, `x-select`, `x-combobox`, `x-multi-combobox`, `x-form-field` and `x-text-area`. All six now drop the attribute on reset.
+
+### Changed — internal
+
+- **`forms/install-validity-api!`** (new, in `baredom.utils.forms`) is the single implementation of the validation surface; the four components that hand-rolled `checkValidity` / `reportValidity` are migrated onto it. The five read-only members are declared in each `property-api` as `:readonly true` — the framework adapters skip them and the generated declarations mark them `readonly` — and the two methods in `method-api`.
+- Twelve validity assertions across five test suites sat behind a `(when (.-validity el) …)` guard that was never true, and an input-commit regression test dispatched an event the component never listens for. All of them now genuinely run, alongside a new cross-component suite covering the surface on all 17 tags.
+
+### Notes
+
+- No adapter release accompanies this one: the new members are read-only, so the generated wrappers filter them out and the adapter packages are functionally unchanged.
+
+## [3.4.0] - 2026-07-22
+
+The four popup-selection form controls — `x-select`, `x-date-picker`, `x-combobox`, and `x-multi-combobox` — become **real form controls**: they display inline validation errors and participate in native `<form>` submission and constraint validation via `ElementInternals`. Two internal refactors extract the resulting form-control policy into one shared, unit-tested place.
+
+### Added
+
+- **Inline validation errors** on `x-select`, `x-date-picker`, `x-combobox`, `x-multi-combobox` — a new `error` attribute (and matching `error` property) renders a message in an `error` CSS part (an assertive `role="alert"` live region), marks the host `data-invalid`, and sets `aria-invalid` / `aria-describedby` on the control. Inside `x-form` this is driven for you by `form.setFieldError(name, message)`.
+- **Form association** for those four controls — they now attach `ElementInternals`, submit their value under `name` (appearing in `FormData` with no hidden input), honour `required`, expose the `error` attribute as a `customError`, and respond to `form.reset()` and a disabling `<fieldset>`.
+- **Framework adapter form bindings** for the newly form-associated controls: `x-date-picker` gains Vue `v-model` / Angular `ControlValueAccessor` / Svelte `bind:value` / React & Solid controlled `value`; `x-multi-combobox` gains the same with an array (`string[]`) value via new array-aware adapter codegen.
+
+### Changed — behavior changes (please read)
+
+These are bug fixes — the controls advertised `name` / `required` but did not honour them — but they change runtime behavior for anyone already using these four inside a `<form>`:
+
+- **Native form participation.** Placed in a plain `<form>`, these controls now submit their value under `name` and appear in `FormData`. Previously they did not (unless manually wired); a hidden-input workaround for the same `name` will now double-submit.
+- **`required` and `error` now block submission**, and `form.reset()` now clears these fields. Previously `required` was inert and reset skipped them — a form that used to submit with an empty required select/combobox/date-picker will now be gated by `reportValidity()`.
+
+No attributes, properties, or events were removed or renamed; this is otherwise additive.
+
+### Changed — internal
+
+- **`baredom.utils.forms`** (new) — the ElementInternals constraint-validation policy and the inline error-display recipe, previously hand-implemented in each form control, are extracted into one namespace. Both the validity decision and the `aria-describedby` projection are pure functions split from their effects, and are now unit-tested (coverage the effecting versions never had). All six form-associated components (the four above plus `x-form-field`, `x-text-area`) compose the shared validity policy; the four popup controls also compose the shared error display.
+- **`custom-elements.json`** — regenerated to pick up the `error` fields and `x-search-field`'s `debounce` field that had drifted out of the committed manifest.
+
+### Notes
 
-- **`<barebuild-action>`** — wraps a submit emitter by containment (a descendant dispatching the configured `submit-event`), JSON-POST/PUT/DELETEs the values, and publishes `.state` + a `barebuild-action-state {name, state}` event per phase transition. Optional `.valuesTransform` property for payload hygiene the action can't itself know (blank-stripping, numeric coercion).
-- **`<barebuild-invalidate-on>`** — placed as a child of a source; on a `when-phase`/`when-name` match it dispatches the document-level `barebuild-invalidate {src}` protocol.
-- **`<barebuild-data>`** now also listens at document for `barebuild-invalidate` and refetches when `detail.src` matches its own `src` by exact `URL.pathname` — the invalidation substrate (additive; the read-side contract is unchanged).
+- Adapter packages are versioned independently. This release ships alongside `react@2.2.0`, `angular@2.8.0`, `vue@0.2.0`, `svelte@0.2.0`, `solid@0.2.0` — each a minor bump carrying the new form bindings. See [`docs/RELEASING.md`](docs/RELEASING.md).
 
 ## [3.3.0] - 2026-05-26
 

package/README.md

@@ -18,6 +18,14 @@
 
 ---
 
+**Part of a set.** [BareDOM](https://github.com/avanelsas/baredom) is a comprehensive web component
+library. [BareBuild](https://github.com/avanelsas/barebuild) is a small runtime that drives web
+components from server state alone. [BareReplay](https://github.com/avanelsas/barereplay) is a
+powerful time-travel replay debugger for BareBuild-based apps.
+[BareProbe](https://github.com/avanelsas/bareprobe) reads the same log from a REPL.
+
+---
+
 ## What is BareDOM?
 
 BareDOM is a library of UI components built entirely on web standards — Custom Elements v1, Shadow DOM, and ES modules. There is no framework runtime, no virtual DOM, and no JavaScript framework peer dependency. Every component is a native HTML element that you register once and use anywhere.
@@ -46,7 +54,7 @@ All components can be explored in the [live demo](https://avanelsas.github.io/ba
 
 **Zero runtime, tree-shakeable.** Each component is a self-contained ES module compiled with Google Closure Advanced. The only JavaScript in your bundle is the components you import — no framework, no utility belt, no runtime library.
 
-**Predictable theming.** Every visual detail is exposed as a `--x-<component>-<property>` CSS custom property — override at any scope, or wrap in [`<x-theme>`](./docs/x-theme.md) for coordinated palettes with built-in presets. Light/dark mode adapts automatically via `prefers-color-scheme`.
+**Predictable theming.** Every visual detail is exposed as a `--x-<component>-<property>` CSS custom property. Set it on the component, or wrap the page in [`<x-theme>`](./docs/x-theme.md) for coordinated palettes with built-in presets. Light/dark mode adapts automatically via `prefers-color-scheme`.
 
 **Accessible & mobile-first.** ARIA roles, keyboard navigation, focus management, and `prefers-reduced-motion` support are part of every component. All components are tested on viewports from 320px up; touch targets meet the 44px minimum on coarse-pointer devices, and pointer events handle mouse + touch uniformly.
 
@@ -103,22 +111,21 @@ All adapters are auto-generated from the same Custom Elements Manifest, so addin
 
 ## Components
 
-**103 UI web components across 11 categories** — from foundational UI controls to morphing animations, organic effects, and scroll-driven storytelling — plus **5 [BareBuild](./barebuild/docs/read-side.md) orchestration elements** (read-side: router / route / data; write-side alpha: action / invalidate-on).
+**106 UI web components across 11 categories** — from foundational UI controls to morphing animations, organic effects, and scroll-driven storytelling.
 
 | Category | Count | Examples |
 |----------|------:|----------|
 | **Form**       | 23 | Button · Checkbox · Slider · Combobox · OTP Input · Color Picker |
 | **Feedback**   | 11 | Alert · Toast · Spinner · Progress · Skeleton · Notification Center |
 | **Navigation** | 8  | Navbar · Sidebar · Breadcrumbs · Tabs · Pagination · Menu |
-| **Layout**     | 10 | Card · Grid · Bento Grid · Split Pane · Container · Collapse |
+| **Layout**     | 12 | Card · Grid · Bento Grid · Split Pane · Drag Panel · Drop Zone |
 | **Data**       | 11 | Avatar · Table · Chart · Timeline · Calendar · Stat |
-| **Overlay**    | 9  | Modal · Drawer · Popover · Tooltip · Welcome Tour · Command Palette |
+| **Overlay**    | 10 | Modal · Drawer · Popover · Tooltip · Floating Panel · Command Palette |
 | **Display**    | 6  | Icon · Image · Typography · Code · Kbd · Spotlight Card |
 | **Animation**  | 6  | Kinetic Canvas · Kinetic Typography · Morph Stack · Soft Body · Splash |
 | **Effects**    | 12 | Liquid Glass · Confetti · Neural Glow · Metaball Cursor · Organic Shape |
 | **Scroll**     | 5  | Scroll · Scroll Parallax · Scroll Stack · Scroll Story · Scroll Timeline |
 | **Utility**    | 2  | i18n · i18n Provider |
-| **Orchestration** | 5 | BareBuild Router · Route · Data — read-side; Action · Invalidate-On — write-side (alpha); not adapter-wrapped |
 
 See [**docs/components.md**](./docs/components.md) for the full per-component catalogue with one-line descriptions and links to each component's API documentation.
 
@@ -141,7 +148,13 @@ See [`docs/x-trace-history.md`](./docs/x-trace-history.md) for the full guide
 
 Wrap any subtree in `<x-theme>` to apply a coordinated palette across every BareDOM component inside it. Eight presets ship in the box — `default`, `ocean`, `forest`, `sunset`, `neo-brutalist`, `aurora`, `mono-ai`, `warm-mineral` — each with light and dark variants that follow `prefers-color-scheme`.
 
-Register your own preset, override individual tokens via CSS, or nest themes for per-section palettes. See [`docs/x-theme.md`](./docs/x-theme.md) for the full API (presets, `registerPreset`, CSS overrides) and [`docs/THEMING.md`](./docs/THEMING.md) for the token catalogue.
+Register your own preset, override individual tokens via CSS, or nest themes for per-section palettes. See [`docs/x-theme.md`](./docs/x-theme.md) for the full API (presets, `registerPreset`, CSS overrides) and [`docs/THEMING.md`](./docs/THEMING.md) for the token catalogue. [`docs/styling.md`](./docs/styling.md) says where each value goes so that it works.
+
+---
+
+## BareMirror (alpha)
+
+A small set of functions for an application on top of the components: they place keyed nodes, write values into the parts of a template and turn events into messages, with no comparing of old and new. It ships inside this package as an alpha, for JavaScript and ClojureScript. See [`docs/baremirror.md`](./docs/baremirror.md).
 
 ---
 
@@ -179,13 +192,13 @@ Each component loads `base.js` once plus its own module. A typical page using 5-
 
 ## Browser Support
 
-BareDOM targets browsers that support Custom Elements v1 and Shadow DOM v1 natively:
+BareDOM is tested in the current versions of these browsers:
 
 | Browser | Minimum version |
 |---------|----------------|
-| Chrome / Edge | 67+ |
-| Firefox | 63+ |
-| Safari | 14+ |
+| Chrome / Edge | 154+ |
+| Firefox | 157+ |
+| Safari | 26.5+ |
 
 No polyfills are included or required for these targets.