@aquera/mcp-ui-render 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,437 @@
+# Changelog — pre-npm development history (Verdaccio)
+
+> **This file is history, not the release record.** Everything below documents the package's
+> development against the **private Verdaccio registry**, where it reached `0.5.4` published and
+> `0.6.0` in-repo. None of these versions exist on public npm.
+>
+> **For published releases, see [`RELEASE-NOTES.md`](./RELEASE-NOTES.md)** — the public npm line
+> starts at `0.0.1`, which is the same code as the internal `0.6.0` build.
+>
+> It is kept rather than deleted because the reasoning in these entries — why a control behaves
+> the way it does, what an interim version got wrong — is the only record of those decisions, and
+> that context outlives the registry it was written against.
+
+All notable changes to `@aquera/mcp-ui-render` are documented here.
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/); this package
+follows semver (MAJOR.MINOR.PATCH) once past 0.x.
+
+## [0.6.0] - 2026-08-26
+
+### Added
+
+- **`sectionsLayout: 'accordion'` — a third section arrangement.** Alongside `'stacked'` (a card
+  per section) and `'tabs'`, sections can now render as a single-open stack of `nile-accordion`
+  cards. The point is the *collapsed* state: a section that isn't open still reports what's inside
+  it, so a multi-section form is scannable without opening every card.
+  - **Header.** An icon tile, the section label with a describing line under it, and a completion
+    status beside the chevron — **✓ Complete** or **N required left** — so a collapsed section says
+    both what it is and whether it still needs work. Status is plain text with a mark rather than a
+    filled pill: it is a readout, not a control, and colour is never the only signal.
+  - **The header writes no connector-describing text of its own.** `section.label` and
+    `section.authType` are rendered verbatim — the label as the title, the authType as the same
+    `nile-badge` the stacked and tabs layouts already use. Nothing is composed around them and
+    nothing is inferred from a key being absent. An interim version rendered
+    "Basic authentication · saved by the platform" under the title, which read as the connector
+    describing itself but wasn't: only "Basic" came from the descriptor, and "saved by the
+    platform" was the renderer turning a MISSING `submitTool` into a sentence. The `bootstrap`
+    format carries no prose field and its shape is fixed, so rather than add a key or invent copy,
+    the header now shows only values the descriptor supplied.
+  - **`sectionIcons`** (a host map keyed by section key) sets the header tile, over a built-in
+    default for the contract's own `authorization` and `tenantAttributes` keys and a generic
+    fallback. The override is host-side because the format carries no icon field — and because
+    iconography is the application's decision, not the connector's.
+  - **Dense field layout.** The open card's body is a grid of label-**above**-control cells rather
+    than the label-left/control-right rows the other layouts use, with each field's `help` as hint
+    text beneath the control — the same `renderHelp()` (and the same "View more/less" truncation)
+    every other layout uses, only repositioned, so one description reads identically everywhere.
+    An empty field shows "Not set" as its placeholder, and a boolean renders as a labelled toggle
+    pill. Booleans keep their declared `order` — styled differently, not reordered.
+  - **Field zoning.** The open card splits into three: fields with no `defaultValue` (what you must
+    actually decide) full width; fields that already carry a working default grouped two-up under a
+    "defaults you can tune" rule; and booleans last, as full-width rows carrying their own
+    description. This DOES reorder relative to the descriptor — the only layout that does — because
+    an "everything you must set" block reads better than defaults interleaved with required fields.
+    Order is preserved within each zone.
+  - **The required marker is now conditional.** `Needs a value` shows only while a required field is
+    still empty, instead of an asterisk on every required field forever. A permanent mark on
+    finished fields is noise that hides the ones that still mean something; this makes the marker a
+    to-do list, matching what the header's "N required left" counts.
+  - **A stored `writeOnce` secret reads as a state**, not a masked value: a lock and "Saved and
+    encrypted" rather than a row of dots, since the host holds the real secret and this element
+    never sees it (§7) — dots imply there is something here to reveal.
+  - **Dense help is never truncated.** The `View more` threshold is tuned for the stacked layout's
+    narrow label column; as a full-width hint line the same text already fits.
+  - **`accordionColumns`** (`1 | 2`, default `2`) sets how many columns the defaults group uses. It is a
+    ceiling, not a fixed count: at `2` the grid still collapses to one column when its CONTAINER
+    is too narrow (not the viewport — the same form is 1180px wide on its own page and ~400px
+    beside a docked panel at an identical viewport), so `1` means "never two".
+  - **`accordionOpenSection`** (default `null`) picks the initially-expanded section: unset, the
+    library opens the first section still missing a required value, else the first visible one — so
+    the form opens on the part that needs work. A section `key` pins it; `''` starts all collapsed.
+    Only re-evaluated on a descriptor change, never on a value edit, so the card being typed in
+    never slams shut.
+  - **`accordionShowFooters`** (default **`false`**, unlike the other layouts) — an accordion is a
+    whole-form overview, and the host normally drives one submit via `validateAll()`. Set it true
+    for per-section "Save `<label>`" buttons here too; `showSectionFooters: false` still wins.
+  - An unrecognised `sectionsLayout` value now falls back to `'stacked'` rather than rendering an
+    empty form.
+
+- **`sectionStatus()`** (`engine/status.ts`, exported) — the pure function behind that attention
+  state, usable standalone by a host that wants the same "is this section done" summary elsewhere. It counts applicable, non-hidden, value-bearing fields
+  (§12/§7; `datatype: "none"` excluded — buttons and reports hold no value the user supplies) and
+  treats a stored write-once secret (§7) as set.
+
+  It is deliberately **not** the same question as the existing per-tab error dot: a required field
+  the user simply hasn't reached yet is *incomplete*, not *invalid*. `sectionStatus` reports
+  completeness; the error machinery keeps reporting validity, and neither replaces the other.
+
+- **`isEmpty()`** is now exported from `engine/validate.js`. It was already the private rule behind
+  `isRequired`; exporting it is what lets `sectionStatus` mean exactly the same thing by "empty" —
+  two independent emptiness notions would let a section read "Complete" while a field inside it
+  still failed validation.
+
+- **`ControlContext.dense`** — an optional, purely advisory flag telling a control its row is being
+  laid out label-above-control in a narrow grid cell. Every built-in renders correctly either way
+  and a custom control that ignores it is not broken; the built-ins use it for one thing, showing
+  "Not set" as the placeholder of an empty field that has no `defaultValue` to advertise instead.
+
+### Fixed
+
+- **A field's help tooltip no longer collapses the section it lives in.** `nile-tooltip` emits
+  `nile-show`/`nile-hide` — the same event names `nile-accordion` uses — and every Nile component
+  emits `bubbles: true, composed: true` (`internal/nile-element.ts`). The accordion's own handlers
+  therefore saw a tooltip opening as "open this section" and its dismissal as "close it", so the
+  card slammed shut under the user's cursor. The handlers now ignore any disclosure event whose
+  target isn't the accordion itself, which also covers any future nested Nile component reusing
+  those names.
+
+### Notes
+
+- `nile-accordion` is registered by `@aquera/nile-elements`' root bundle (what a host imports), but
+  the package ships no per-element export subpath for it — the same gap the browser suite already
+  documents for `nile-file-upload`. Hosts importing the whole package are unaffected.
+- No change to `types.ts`: layout stays a host-side element property and never enters the
+  `bootstrap` descriptor, same as `'tabs'`.
+
+## [0.5.5] - 2026-08-08
+
+### Added
+
+- **`datatype: "object"` now has a real editable control** — `validateField` has always had
+  proper object validation (`requiredKeys`, per-value regex, §8), but no `ui-component` actually
+  rendered an object usably: `input`/`textarea` both did `String(value)`, which for a real object
+  produces the literal text `"[object Object]"` — not editable, not even legible. `input` and
+  `textarea` now display an object value as pretty-printed JSON, and parse the typed text back
+  into a real object on input; while the JSON is mid-typing and not yet valid/complete (the
+  normal state for anything beyond a bare `{}`), the raw text is kept as an interim value instead
+  of being dropped or corrupted — `validateField`'s object branch already treats a non-object
+  value as an empty object rather than crashing, so this degrades to an ordinary "missing
+  required key(s)" validation message, never a throw, until the JSON is valid again.
+  `DATATYPE_DEFAULT['object']` changed from `input` to `textarea` (a single line is a poor fit
+  for JSON; `textarea` is also what real descriptors already pair `object` with, e.g.
+  `flatfile-mcp-server`'s `tenantAttributes.schemas`). Found — like the `0.5.4` defaults fix —
+  while validating a real `flatfile-mcp-server` bootstrap descriptor end to end; not currently
+  exercised by any hidden field in that descriptor, but a real gap for any connector that ever
+  ships a non-hidden `object` field.
+
+## [0.5.4] - 2026-08-08
+
+### Fixed
+
+- **A dependent field's own `defaultValue` was never seeded when it became newly applicable
+  mid-session — only at initial descriptor load.** `<aq-mcp-config>`'s `willUpdate` only called
+  `seedDefaults()` when the `descriptor` property itself changed. A field gated behind
+  `dependencyAttribute`/`dependencyValue` (or `dependsOn`) that's inapplicable at first render —
+  e.g. a "Storage Type" radio that only applies once "Source Connection Type" is set to "Flat
+  File" — becomes applicable via a `values` change (the user picking something elsewhere), not a
+  `descriptor` change, so its `defaultValue` was silently never seeded: the field rendered with
+  nothing selected despite the descriptor declaring a default, and — worse, for a non-required
+  field — that default would never be submitted at all, since `collectSubmit` only submits keys
+  already present in `values`. Found while validating a real `flatfile-mcp-server` bootstrap
+  descriptor end to end. Fixed by re-running `seedDefaults` on a `values` change too, guarded by a
+  key-count comparison (`seedDefaults` only ever fills in a currently-`undefined` attribute, so a
+  key-count mismatch is a cheap, correct signal that seeding actually added something) —
+  reassigning `this.values` only when seeding truly changed it avoids re-triggering `willUpdate`
+  forever.
+
+## [0.5.3] - 2026-08-08
+
+### Fixed
+
+- **`.aq-mcp-section`, `.aq-mcp-tabs`, and the selected permissions-report filter chip kept a
+  white background under the dark theme.** All three used `--ng-color-base-white`, a raw Nile
+  palette token that's `#FFFFFF` unconditionally in both light AND dark (it never flips) —
+  the theme-aware surface token is `--ng-colors-bg-primary`, which resolves to
+  `--ng-color-base-white` in light and `--ng-color-graydarkmode-950` in dark. Every text token in
+  the sheet was already correct (`--ng-colors-text-primary-900`/`-secondary-700`/`-tertiary-600`
+  all flip), so under dark mode section headings and help text turned near-white against a card
+  that stayed white — headings effectively invisible, `nile-input` controls rendering as black
+  boxes on a white card. `.aq-mcp-section__footer` uses `--ng-colors-bg-secondary` and DOES flip,
+  so the footer strip went dark inside a still-white card. Fixed by swapping all three to
+  `--ng-colors-bg-primary` (light mode unaffected — it resolves to the same white there).
+- **The selected permissions-report filter chip's text color was never theme-aware at all.**
+  `--ng-colors-brand-600` isn't a real Nile token (checked every `nxtgen-*.css` shipped) — it
+  silently fell back to the hardcoded `#155eef` in both themes, every time. Swapped for
+  `--ng-componentcolors-utility-brand-600`, the real semantic token, which resolves to the exact
+  same `#155EEF` in light mode (zero visual change there) and to a lighter `#528BFF` in dark mode
+  — the old `#155eef`-on-`--ng-colors-bg-primary` combination in dark mode measured ~3.6:1
+  contrast, borderline-failing for text; the fixed token measures noticeably better.
+  **Known, left as-is:** `.aq-mcp-field__help-toggle`'s "View more"/"View less" link has the same
+  nonexistent `--ng-colors-brand-600` token, falling back to `#7f56d9` — Aquera's actual brand
+  purple, not Nile's blue. No theme-flipping purple token exists in Nile (every "brand" text
+  token there resolves to the blue `bluedark` family), and the literal purple already reads
+  ~3.9:1 against the new dark surface, so swapping it would trade a working purple for an
+  unintended blue rather than fix anything — left alone.
+
+## [0.5.2] - 2026-08-07
+
+### Fixed
+
+- **`validateFile` crashed on any non-`File` value, not just the `WRITE_ONCE_UNCHANGED`
+  sentinel fixed in `0.5.1`.** That fix stopped the sentinel specifically from reaching
+  `validateFile`, but `validateFile`/`acceptMatches` still unconditionally assumed
+  `value` was a real `File` — any OTHER non-`File` value (stale data left over from
+  before a field became a `file`-upload type, or any other malformed value a host
+  hands back) still crashed the same way: `file.name.toLowerCase()` on a value with no
+  `.name`. Fixed by guarding `validateFile` itself with an `instanceof File` check —
+  fails safe (returns the field's validation message, i.e. "invalid") instead of
+  throwing, for ANY non-`File` value, not just the one sentinel string. This is the
+  correct chokepoint: every `file`-datatype value flows through `validateFile`
+  regardless of how it got there, so this closes the crash for good rather than
+  special-casing another known-bad value.
+
+## [0.5.1] - 2026-08-07
+
+### Fixed
+
+- **`validateField` crashed on a stored `writeOnce` value for `file` fields, silently killing the whole submit.**
+  A `writeOnce` field's stored value is the `WRITE_ONCE_UNCHANGED` sentinel string (§7), never the real
+  value — `validateField` never checked for it before running datatype-specific checks. For a `string`
+  field this "worked" by accident (`String(sentinel)` against the field's own regex is harmless, if
+  meaningless). For a `file` field it crashed for real: the `file`-control branch reads `value.name`/
+  `value.size` off what it assumes is a real `File`, and a plain string has neither — `TypeError` thrown
+  mid-`computeErrors()`, which both `validateSection` (section Save) and `AqMcpConfig.validateAll()` call
+  over *every* field in the section, not just the one being edited. Net effect: any connector with a
+  stored file-type credential field (e.g. ADP's client certificate) was unsaveable — editing ANY other
+  field in that section threw before ever emitting `aq-mcp-submit`, no request ever sent, Save stuck
+  indefinitely. Fixed by short-circuiting `validateField` to `null` the moment `value === WRITE_ONCE_UNCHANGED`,
+  before any datatype-specific check runs — the same "sentinel means stored, don't touch" rule
+  `<aq-mcp-field>`'s own `isSetWriteOnce()` already applies on the display side.
+
+## [0.5.0] - 2026-08-06
+
+### Added
+
+- **`radio` control** — a new built-in `ui-component`, mapped to `nile-radio-group`/
+  `nile-radio` (previously an unregistered `ui-component` silently fell back to the
+  datatype default, e.g. `input` for `string` — no radio buttons, no options shown,
+  no warning). Needs `options` like `select` does; an empty list logs the same
+  "descriptor defect (§15)" warning and renders disabled. Gets the same accessible-name
+  wiring as `input`/`textarea`/`password`/`select`: the field's label is passed into
+  Nile's own `label` property (real `aria-labelledby` association on the group's
+  `<fieldset>`), then visually hidden via `::part(form-control-label)` since this
+  library already shows the label in `<aq-mcp-field>`'s own left column.
+- **`select`/`radio` accept `{ value, label }` options**, alongside the original plain
+  primitive form (`value === display text`) — e.g. `{ value: 'sftpStorage', label: 'SFTP
+  Storage' }` shows "SFTP Storage" to the user while still emitting/submitting the raw
+  code `sftpStorage`. Fully backward compatible: a plain string/number option renders
+  exactly as before.
+- **`dynamicOptions` property + `aq-mcp-options-request` event (§9.6)** — a way to feed a
+  `select`/`radio` field's `options` from a host-executed tool call (e.g. `listFtpServers`),
+  since this library still performs no network I/O itself (D-4). A field with `tool` set and
+  no options yet emits `aq-mcp-options-request` (`{ attribute, tool, args }`) once it's
+  actually applicable (respects `dependencyAttribute`) and at most once per attribute ever;
+  the host calls the tool and sets the result into `<aq-mcp-config>.dynamicOptions` (keyed by
+  attribute), which takes priority over the field's own static `options`. A field pending a
+  fetch renders disabled WITHOUT the §15 "descriptor defect" warning — that warning is now
+  reserved for a field with no options and no `tool` either, i.e. genuinely no way to ever get
+  any.
+- **`properties-table` control** — a new built-in `ui-component`, `datatype: "none"` (never
+  validated/submitted, same contract as `test-connection-report`). Renders a read-only
+  Property/Value `<table>` from a `PropertiesTableRow[]` list — for surfacing a handful of
+  attributes' values (typically read-only/hidden tenant attributes worth seeing but not worth
+  exposing as disabled form fields) without duplicating them into the editable form. Two ways
+  to supply the rows, same priority `select`/`radio` already have between `options` and
+  `dynamicOptions`: **static**, declared directly on the field as `field.rows` (for data the
+  connector already knows when it builds the `bootstrap` response — no host computation
+  needed), or **dynamic**, host-supplied via `values[attribute]` (wins over `field.rows` when
+  both are present). Formats `null`/`undefined` as an em dash, an array by joining with commas,
+  and truncates a long value with an ellipsis (the full value stays available via the cell's
+  `title`). Not mapped to a Nile element — Nile has no read-only data-table primitive this
+  simple case needs. A plain (non-array) object value is `JSON.stringify`'d rather than
+  `String()`'d (so it never renders the literal `[object Object]`), and property names over 24
+  characters truncate with an ellipsis + hover `title`, same treatment as values.
+- **`Field.dependsOn?: { attribute: string; value: string | string[] }[]`** — a compound,
+  multi-attribute OR dependency, alongside the existing single-attribute
+  `dependencyAttribute`/`dependencyValue`. A field applies if `dependencyAttribute` matches OR
+  any `dependsOn` entry matches (all OR'd together, never AND'd) — for a field relevant when
+  either of two DIFFERENT attributes hits a value, which the single-attribute form can't
+  express. Fully backward compatible: a field using only `dependencyAttribute` behaves exactly
+  as before.
+- **Collapsible "View more"/"View less" help text** (`<aq-mcp-field>`) — `field.help` over 100
+  characters now renders truncated with a toggle instead of always showing in full; help at or
+  under the threshold is unaffected. Purely a display convenience with local component state,
+  no `Field`/`Values` model change.
+- **`Field.actions` — a multi-action toolbar for a control, alongside the existing single-action
+  `button` control.** `properties-table` now renders its own card header (title from
+  `field.label`, subtitle from `field.help`, and a right-aligned toolbar built from
+  `field.actions`) instead of relying on `<aq-mcp-field>`'s usual label-left/control-right split
+  — matching the live reference's "Generated Configuration" card exactly (a download icon
+  button + an "Edit Configuration" button, each independently wired to its own tool). An
+  `actions` entry with `icon` set renders as an icon-only `nile-icon-button`; without `icon`, a
+  labeled `nile-button`. Clicking one calls the control's `onAction` with that specific
+  `FieldAction`, and `aq-mcp-action`'s event detail now includes `action` (undefined for the
+  classic single-`button` case) so a host can tell which of several actions fired. Each action
+  carries its own `tool`/`args`/`confirm`, independent of the field's own (still supported)
+  top-level `tool`/`args`/`confirm`.
+- **`properties-table` is now a `FULL_WIDTH_CONTROLS` entry** (`<aq-mcp-field>`) — it spans the
+  whole field row instead of sitting in the standard two-column label-left/control-right split,
+  since it now renders its own title/subtitle/toolbar. Purely a layout change; `field.rows` /
+  `values[attribute]` / empty-value behavior is unchanged, and the field's label still always
+  renders somewhere (now in the control's own header) even when there are no rows yet.
+- **`permissions-report` control** — a new `datatype: "none"` read-only control, distinct from
+  `test-connection-report`: that one models a list of PASS/FAIL endpoint probes, this one models
+  a scope/permission GRANT table (a validation banner + a running "N Granted" count + an
+  All/Success filter + a Resource Type/Permission Type/Access table) — matching the live
+  reference's own "Credentials" tab Test Connection result exactly. The granted count is always
+  derived from the current `grants` array (never a separately-suppliable, possibly-inconsistent
+  number). The All/Success filter is pure CSS (native radio inputs + a general-sibling rule in
+  `mcp-ui-render.css`) — no Lit reactive state, same precedent `test-connection-report`'s
+  mitigation `<details>` already set. New types: `PermissionGrant`, `PermissionsValidationReport`.
+
+### Fixed
+
+- **A `test-connection-report`/`permissions-report` field with no value yet still rendered its
+  own `<aq-mcp-field>` row** — the control itself correctly rendered nothing, but the field's
+  label (e.g. "Validation Report") still showed in the left column next to a blank right column,
+  since `<aq-mcp-section>`'s applicability filter only checked `hidden`/`dependencyAttribute`, not
+  whether the control had anything to show. Fixed by skipping the field entirely (no
+  `<aq-mcp-field>` element at all, not just an empty control body) when one of these two controls
+  has a `null`/`undefined` value — `properties-table` is unaffected (it always shows its own
+  header/toolbar by design, even with zero rows).
+- **`file` fields always showed `nile-file-upload`'s hardcoded image-upload hint**
+  ("PNG, JPG or SVG (upto 1MB) | 1:1 ratio") regardless of the field's own `accept`/`maxSizeKB` —
+  those props only fed the control's drop/pick VALIDATION, never its displayed `subtitle` text,
+  so a non-image field (a PEM certificate, say) still told the user to drop a PNG. Fixed by
+  deriving the hint from `field.accept` (extension-like entries only, e.g. `.pem`/`.crt`; bare
+  MIME types are skipped) and `field.maxSizeKB`, e.g. `"PEM, CRT or CER (up to 64KB)"`.
+
+## [0.4.1] - 2026-08-05
+
+### Fixed
+
+- **Rendered form controls had no accessible name at all for assistive technology.**
+  `<aq-mcp-field>` shows the field's label VISIBLY in its own left-column `<div>` (§12
+  two-column layout), but that div was never programmatically associated with the
+  control next to it (no `for`/`aria-labelledby`/`aria-label`) — and the `input`/
+  `textarea`/`password`/`select` controls never populated Nile's own `label` property
+  either, which is what actually drives each control's real accessible-name wiring
+  (`for="input"` on `nile-input`/`nile-textarea`, `aria-labelledby="label"` on
+  `nile-select`; each is `aria-hidden` when `label` is empty). Net effect: every
+  rendered field had zero accessible name for a screen reader. Fixed by passing the
+  field's label into Nile's `.label` property on those four controls, then visually
+  hiding Nile's own internal label element (`::part(form-control-label)`, the
+  standard clip-rect "hidden but announced" pattern — not `display:none`, which would
+  also drop it from the accessibility tree) so nothing appears twice on screen.
+  Confirmed directly against the live accessibility tree (`aria-hidden="false"`, label
+  text matches, zero visual footprint) — not just asserted from source reading.
+- **Known, separate gap — not fixed here:** `checkbox` (`nile-slide-toggle`) has no
+  equivalent wiring in Nile itself; its internal `<input type="checkbox">` has no
+  `for`/`aria-label`/`aria-labelledby` connecting it to its own `label`/`sublabel`
+  properties at all (confirmed by reading its full render template). This is a gap in
+  Nile's own component, not something fixable from this library's side — flagged for
+  the Nile team, not silently worked around.
+
+## [0.4.0] - 2026-08-04
+
+### Added
+
+- **`sectionsLayout: 'stacked' | 'tabs'`** (`<aq-mcp-config>`, default `'stacked'`) — an
+  alternative to the default one-card-per-section layout. `'tabs'` renders one
+  [`nile-nav-tab`](https://nile.aqueralabs.com/2.0.1/nav-tab) per section, with the
+  section's own card as that tab's panel (rendered `compact`: no border/title, since the
+  tab label already shows it). Validation, submit, and footers behave identically in
+  either layout — only the arrangement changes.
+- **`tabsPlacement: 'top' | 'bottom' | 'start' | 'end'`** (`<aq-mcp-config>`, default
+  `'top'`) — tab orientation, only meaningful in `sectionsLayout: 'tabs'`. `'start'`/`'end'`
+  give a fixed-width vertical tab list (label truncates with an ellipsis + native `title`
+  tooltip past 170px, using `nile-nav-tab-group`'s own `width` attribute to prevent layout
+  shift between tabs, per its documented purpose).
+- **`tabsShowErrorIndicator`** (`<aq-mcp-config>`, default `true`) — a small red dot next to
+  a tab's label once that section has an actual recorded validation error (present in the
+  form's live `errors` state) — never on a pristine, untouched required field. Rendered via
+  `nile-nav-tab`'s documented `suffix` slot (not the default label slot, which gets
+  squeezed to zero width in vertical placement). Set `false` to opt out.
+- **`compact`** (`<aq-mcp-section>`, default `false`) — drops a section's own card
+  border/title when it's already framed by something else (set automatically by
+  `<aq-mcp-config>` in tabs mode; available for a host embedding `<aq-mcp-section>`
+  standalone inside its own tabbed/framed UI).
+- New `mcp-render-demo` example: a "Sections: Stacked / Tabs (horizontal) / Tabs
+  (vertical)" cycling control wired to `sectionsLayout`/`tabsPlacement`.
+- **`CONFIGURATION.md`** — a dedicated reference documenting every property, method, and
+  event on `<aq-mcp-config>` / `<aq-mcp-section>` / `<aq-mcp-field>`, plus the
+  `registerControl`/`registerSectionFooter` extensibility registries, linked from
+  `README.md`.
+
+## [0.3.1] - 2026-08-04
+
+### Fixed
+
+- **`writeOnce` password fields (e.g. `datatype: "password"` with `writeOnce: true`) discarded
+  keystrokes and flipped back to the masked "••••••• Replace" view after the very first
+  character typed into a blank field.** Two compounding bugs:
+  - The `password` control (`controls.ts`) hardcoded `<nile-input>`'s `.value` to `''` on
+    every render instead of binding the actual current `value` — so every re-render
+    (triggered by each keystroke) forcibly reset the input back to empty.
+  - `AqMcpField.isSetWriteOnce()` treated **any non-empty string** as "a value is already
+    stored" (`typeof this.value === 'string' && this.value !== ''`), rather than checking
+    specifically for the `WRITE_ONCE_UNCHANGED` sentinel. So the moment a user typed even one
+    character into a genuinely blank field, that keystroke itself satisfied "non-empty
+    string" and flipped the field to the masked/Replace view mid-type, discarding everything
+    typed after the first character.
+  - Both fixed: the control now binds `.value` like every other control, and
+    `isSetWriteOnce()` now checks `this.value === WRITE_ONCE_UNCHANGED` specifically. The
+    genuine "already-stored value → click Replace → type a new one" flow is unaffected and
+    still masks correctly.
+
+## [0.3.0] - 2026-08-04
+
+### Added
+
+- **`showFooter` / `showSectionFooters`** boolean properties (`<aq-mcp-section>` /
+  `<aq-mcp-config>`, default `true`) — a master switch that hides a section's footer
+  entirely, whether it's the library's default "Save `<label>`" button **or** a
+  `registerSectionFooter` override. Lets a host that drives submission itself (its own
+  external button) turn footers off with one property instead of registering an empty
+  footer for every section key.
+- **`AqMcpConfig.validateAll(): { valid: boolean; values: Values }`** — a public method a
+  host can call imperatively (e.g. via an Angular template ref) to validate every
+  section's applicable fields at once and get the full form state back. Pushes results
+  into the element's own `errors` state — the same mechanism a section's own Save button
+  uses via `validateSection` — so a host-driven "submit everything" button gets real
+  validation and inline field-error display, not just raw `values`.
+- **Live on-change validation** — editing a field now re-validates its actual new value
+  immediately (`onFieldInput`), instead of just optimistically clearing its error and
+  waiting for the next submit. An error appears the instant a field goes invalid and
+  clears the instant it's genuinely fixed.
+
+### Changed
+
+- Internally refactored the per-field validation loop into a shared `computeErrors()`
+  helper, used by both `validateSection` (one section) and `validateAll` (every section),
+  so both paths compute errors identically.
+
+## [0.2.0] - 2026-07-31
+
+Published externally with no corresponding source changes in this repo — identical
+content to 0.1.0. Recorded here only so the version history has no unexplained gap; see
+0.1.0 below for what it actually contains.
+
+## [0.1.0] - 2026-07-29
+
+### Added
+
+- Initial scaffold: framework-agnostic Lit 3 web components (`<aq-mcp-config>`,
+  `<aq-mcp-section>`, `<aq-mcp-field>`) rendering a `bootstrap` tenant-configuration
+  descriptor via Nile, with the `aq-mcp-change` / `aq-mcp-submit` / `aq-mcp-action` event
+  contract and the `registerControl` / `registerSectionFooter` extensibility registry.

package/CONFIGURATION.md

@@ -0,0 +1,178 @@
+# Configuration Reference
+
+Every property, method, event, and extensibility hook the three custom elements
+(`<aq-mcp-config>`, `<aq-mcp-section>`, `<aq-mcp-field>`) expose. See [`USAGE.md`](./USAGE.md)
+for framework integration examples and [`README.md`](./README.md) for the public API export
+table (`index.ts`).
+
+All properties are plain Lit reactive properties set via JS (`el.propName = value`) or, in
+Angular/JSX, via property binding (`[propName]="value"`) — not HTML attributes, except where
+noted (`sectionsLayout`, `tabsPlacement`, `showSectionFooters`, `tabsShowErrorIndicator`,
+`showFooter`, `compact` reflect as attributes too since they're primitives).
+
+## `<aq-mcp-config>` — the root element
+
+This is the element a host actually mounts. It owns the descriptor + values + validation state,
+renders every section, and is the only element that emits the public event contract.
+
+### Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `descriptor` | `Descriptor \| null` | `null` | The `bootstrap` tool's response — required to render anything. |
+| `values` | `Values` (`Record<string, unknown>`) | `{}` | Current form state, keyed by `attribute`. One-way in: the host passes it down; edits flow back out via the `aq-mcp-change` event's `detail.values`, not by mutating this property in place. |
+| `showSectionFooters` | `boolean` | `true` | Master switch for every section's footer — the default "Save `<label>`" button, **and** any `registerSectionFooter` override. `false` hides every footer at once, e.g. when the host drives submission itself via its own button(s). |
+| `sectionsLayout` | `'stacked' \| 'tabs' \| 'accordion'` | `'stacked'` | How sections are arranged. `'stacked'` is every section as its own card, one after another (unchanged legacy behavior). `'tabs'` renders one `nile-nav-tab` per section, with the section's own card as that tab's panel. `'accordion'` renders one `nile-accordion` per section — single-open, with a label-above-control body laid out in one or two columns (`accordionColumns`) and each field's `help` shown as hint text beneath it; a card whose section still has a required field empty tints its edge, so a collapsed section that needs work is findable. Validation and submit behave identically in every layout; footers default to hidden in `'accordion'` (see `accordionShowFooters`). An unrecognised value falls back to `'stacked'`. |
+| `tabsPlacement` | `'top' \| 'bottom' \| 'start' \| 'end'` | `'top'` | Tab orientation, only meaningful when `sectionsLayout === 'tabs'`. Passed straight through to `nile-nav-tab-group`'s own `placement`. `'start'` gives a left-hand vertical tab list; `'end'` a right-hand one. |
+| `tabsShowErrorIndicator` | `boolean` | `true` | Tabs mode only. Shows a small red dot next to a tab's label once that section has an **actual recorded** validation error (i.e. present in the internal `errors` state) — not merely a required field the user hasn't reached yet. An error lands there only after a live edit is validated or the section/whole form has been submitted at least once. `false` opts out entirely. |
+| `accordionOpenSection` | `string \| null` | `null` | Accordion mode only. Which section starts expanded. Left `null`, the library picks the first section with a required-but-empty field, else the first visible section — so the form opens on the part that still needs work. A section `key` pins that section; `''` starts every section collapsed. Only re-evaluated when the descriptor (or this property) changes, never on a value edit — otherwise the card being typed in would slam shut. |
+| `accordionShowFooters` | `boolean` | `false` | Accordion mode only. Shows the open section's "Save `<label>`" footer. Defaults to **false**, unlike the other layouts: an accordion is a whole-form overview, and the host normally drives one submit for all of it via `validateAll()`. `showSectionFooters: false` still overrides this to off. |
+| `sectionIcons` | `Record<string, string>` | `{}` | Accordion mode only. Header icon per `section.key` → `nile-glyph` name. Host map first, then a built-in default for `authorization`/`tenantAttributes`, then a generic glyph. Host-side only — the `bootstrap` format carries no icon field. |
+| `accordionColumns` | `1 \| 2` | `2` | Accordion mode only. How many columns the "defaults you can tune" group uses. A **ceiling, not a fixed count**: at `2` the grid still collapses to one column when the container is too narrow to give each cell a usable width, so `1` means "never two", not "always exactly one". |
+| `dynamicOptions` | `Record<string, unknown[]>` | `{}` | Host-fed options for `select`/`radio` fields resolved dynamically (§9.6) — keyed by `field.attribute`, takes priority over that field's own static `options` when both are present. The library asks for a list via `aq-mcp-options-request`; the host calls the named tool and sets the result back in here (a NEW object each time — `{ ...cfg.dynamicOptions, [attr]: list }` — not a mutated one, so the property-changed check fires). See "Common recipes" below for the full round-trip. |
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `validateAll()` | `(): { valid: boolean; values: Values }` | Validates every section's applicable fields at once and pushes the results into the element's own internal `errors` state — the same mechanism a section's own Save button uses (`validateSection`), just across every section. Call it imperatively on the element (e.g. an Angular template ref: `<aq-mcp-config #cfg>` then `cfg.validateAll()`) when the host drives its own "submit everything" button instead of using per-section footers — this is what makes that external button still get real validation + inline field-error display, not just the raw `values`. There is no event for this: the host decides what "submit everything" even means for its own data shape, so it must call the method directly. |
+
+### Events
+
+All three bubble and are composed (`bubbles: true, composed: true`), so a host listening on any
+ancestor element (or via `addEventListener` on `document`) still receives them.
+
+| Event | `detail` shape | Fires when |
+|---|---|---|
+| `aq-mcp-change` | `{ attribute: string; value: unknown; values: Values }` | Any field is edited. `values` is the **entire current form state** across every section (not scoped to the edited field's section) — this is the only way the host's own copy of `values` stays in sync, since `[values]` is a one-way-in property; write `detail.values` back into whatever the host passed in as `values` if it needs to read the form state later (e.g. from a host-driven submit button). |
+| `aq-mcp-submit` | `{ sectionKey: string; submitTool: string \| null; values: Values }` (`SubmitPayload`) | A section's Save action succeeds validation. `values` here is scoped to **that one section only**, and pre-processed: hidden/`datatype:"none"` fields dropped, inapplicable fields (failed a `dependencyAttribute`/`dependsOn` check, §9.7) dropped, numbers coerced, and a blank/unchanged `writeOnce`/secret field omitted entirely (so "keep current value" doesn't overwrite anything). `submitTool` is the connector tool to call, or `null` meaning the platform default (`applications_update`). Never fires if validation fails — nothing is emitted, the section's fields just show inline errors. |
+| `aq-mcp-action` | `{ tool: string; args: Record<string, unknown>; confirm?: string; field: Field; action?: FieldAction }` | A `datatype: "none"` button field is invoked, OR one entry in a control's own `field.actions` toolbar is clicked (§5, e.g. `properties-table`'s "Download"/"Edit Configuration") — after the user confirms, if a `confirm` message is declared (on the action itself, or on the field, checked in that order). `tool`/`args`/`confirm` resolve from the clicked `action` when present, else from the field's own top-level `tool`/`args`/`confirm`. `action` is the specific `FieldAction` clicked, undefined for the classic single-`button` case. No `values` on this event at all. |
+| `aq-mcp-options-request` | `{ attribute: string; tool: string; args: Record<string, unknown> }` | A `select`/`radio` field declares `tool` and currently has no options (§9.6) — neither a static `field.options` nor an existing `dynamicOptions` entry — AND currently applies (passes its `dependencyAttribute`/`dependsOn` check, if any, §9.7; a field gated behind another field's value is never requested before that value makes it applicable). Fires **at most once per `attribute`** for this element's lifetime; feed the result back via the `dynamicOptions` property. |
+
+The library performs no network I/O and holds no secrets: it renders, validates, and emits
+intent; the host is responsible for actually calling the connector/platform tool.
+
+## `<aq-mcp-section>` — one section's card
+
+Normally only used internally by `<aq-mcp-config>` (one instance per section), but it's a
+public, independently-usable custom element if a host ever wants to render a single section on
+its own outside the full form.
+
+### Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `section` | `Section` | *(required)* | The section to render — one entry from `descriptor.sections`. |
+| `values` | `Values` | `{}` | Current form state (the whole form's, not just this section's — fields reference other sections' values via `dependencyAttribute`). |
+| `errors` | `Record<string, string \| null>` | `{}` | Per-field validation messages, keyed by `attribute`. |
+| `showFooter` | `boolean` | `true` | Master switch for **this** section's footer — the default "Save `<label>`" button, AND any `registerSectionFooter` override for this section's key. `false` hides the footer entirely regardless of what's registered. |
+| `compact` | `boolean` | `false` | Set automatically by `<aq-mcp-config>` when this section is rendered as a tab panel (`sectionsLayout: 'tabs'`) — drops the card's own border and title line (the tab nav already shows the label), but keeps the `authType` badge and save-target caption. Set it yourself only if embedding `<aq-mcp-section>` standalone inside some other tabbed/framed UI. |
+| `dynamicOptions` | `Record<string, unknown[]>` | `{}` | Passed straight through to every `<aq-mcp-field>` this section renders — see `<aq-mcp-config>`'s own `dynamicOptions` for the full contract. **Note:** `aq-mcp-options-request` is only ever emitted by `<aq-mcp-config>` (it owns the "which field needs options" scan); `<aq-mcp-section>` used standalone never fires it, so a host embedding it without `<aq-mcp-config>` must resolve any `tool`-backed field's options itself before setting this property — same "more on the host" trade-off already true for standalone validation/submit below. |
+
+Emits the internal `section-submit` event (`{ detail: { sectionKey } }`) when its footer's Save
+button is clicked — this is consumed by `<aq-mcp-config>`, not part of the public host contract;
+a host embedding `<aq-mcp-section>` standalone needs to listen for it directly and call its own
+validation/submit logic (there's no `<aq-mcp-config>` there to do it automatically).
+
+## `<aq-mcp-field>` — one field's row
+
+Independent of `<aq-mcp-config>`/`<aq-mcp-section>` entirely — the simplest way to render a
+single control (e.g. dropping a `test-connection-report` result into an arbitrary div; see
+`README.md`'s "Rendering a single `ui-component`" section for a worked example).
+
+### Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `field` | `Field` | *(required)* | The field definition to render (`attribute`, `datatype`, `ui-component`, `isRequired`, `validation`, etc. — see the descriptor contract). |
+| `value` | `unknown` | `undefined` | The field's current value. |
+| `error` | `string \| null` | `null` | Validation message to show, or `null` when valid. |
+| `dynamicOptions` | `Record<string, unknown[]>` | `{}` | Forwarded to the `select`/`radio` control renderer as `ControlContext.dynamicOptions` (§9.6) — see `<aq-mcp-config>`'s own `dynamicOptions` for the full contract. `<aq-mcp-field>` never emits `aq-mcp-options-request` itself (that scan lives in `<aq-mcp-config>`); a standalone `<aq-mcp-field>` for a `tool`-backed field needs this set directly by the host up front. |
+
+A `writeOnce` field (e.g. a password) whose `value` is exactly the `WRITE_ONCE_UNCHANGED`
+sentinel (exported from `index.ts`) renders masked + a "Replace" link instead of an input, until
+Replace is clicked — this is a stored-value indicator, not a truthy-string check, so typing into
+an otherwise-empty `writeOnce` field never gets misread as "already set."
+
+A `file` field's `accept`/`maxSizeKB` validation is **client-side only, advisory** — this library
+has no network I/O (D-4), so it can't be the real gate. A connector must still enforce file
+type/size server-side; treat the in-browser check as a fast first pass for the user, not a
+security boundary.
+
+Emits the internal `field-input` (`{ detail: { attribute, value } }`) and `field-action`
+(`{ detail: { field } }`) events — again consumed by `<aq-mcp-config>`/`<aq-mcp-section>`, not
+part of the public contract for a standalone embed.
+
+## Extensibility registries (`index.ts` exports)
+
+Two global, side-effecting registries — call these once at app bootstrap, before the relevant
+`<aq-mcp-*>` element first renders.
+
+| Function | Signature | Description |
+|---|---|---|
+| `registerControl` | `(name: string, renderer: ControlRenderer) => void` | Register or override the Lit renderer for a `ui-component` string. An unknown `ui-component` always falls back to the field's datatype default (`registry.ts`'s `defaultControlFor`) — a field is never silently dropped. |
+| `resolveControl` | `(uiComponent: string) => ControlRenderer \| undefined` | Look up a registered control renderer directly (used internally by `<aq-mcp-field>`; also usable by a host bypassing `<aq-mcp-field>` entirely — see README). |
+| `registerSectionFooter` | `(key: string, renderer: SectionFooterRenderer) => void` | Register or override the footer for a section, keyed by `section.key`. Replaces the library's default "Save `<label>`" button entirely for that key — the renderer owns the markup and must call `ctx.onSubmit()` itself to actually trigger validation + `aq-mcp-submit`. This override always takes precedence over `showSectionFooters`/`showFooter` being `true`, but **not** over them being `false` — the boolean is a master kill-switch checked first (see `AqMcpSection.renderFooter`). |
+| `resolveSectionFooter` | `(key: string) => SectionFooterRenderer \| undefined` | Look up a registered footer renderer directly. |
+
+`ControlContext` (what a control renderer receives): `{ field, value, error, onInput, onAction?, dynamicOptions? }`.
+`SectionFooterContext` (what a footer renderer receives): `{ section, values, onSubmit }`.
+
+## Common recipes
+
+**Hide every section's default footer, drive submission from the host's own button:**
+```ts
+cfg.showSectionFooters = false;
+// ...
+const { valid, values } = cfg.validateAll(); // real validation, not just raw values
+```
+
+**Tabs, vertical, with the error dot:**
+```html
+<aq-mcp-config
+  [descriptor]="descriptor" [values]="values"
+  sectionsLayout="tabs" tabsPlacement="start"
+></aq-mcp-config>
+```
+
+**Feed a `select`/`radio` field's options from a tool call (§9.6):**
+```ts
+cfg.addEventListener('aq-mcp-options-request', async (e) => {
+  const { attribute, tool, args } = e.detail; // e.g. tool: 'listFtpServers'
+  const options = await host.callTool(tool, args); // string[] or {value,label}[]
+  cfg.dynamicOptions = { ...cfg.dynamicOptions, [attribute]: options };
+});
+```
+
+**Replace one section's footer, keep the rest default:**
+```ts
+import { registerSectionFooter } from '@aquera/mcp-ui-render';
+import { html } from 'lit';
+
+registerSectionFooter('authorization', ({ onSubmit }) => html`
+  <div class="aq-mcp-section__footer">
+    <nile-button variant="primary" @click=${onSubmit}>Save & encrypt credentials</nile-button>
+  </div>
+`);
+```
+
+**Customize `properties-table`'s action toolbar (`Field.actions`) beyond the built-in
+icon/labeled-button default** — there's no separate action-renderer hook; `registerControl`
+overrides the whole control, toolbar included, same as customizing any other built-in:
+```ts
+import { registerControl } from '@aquera/mcp-ui-render';
+import { html } from 'lit';
+
+registerControl('properties-table', ({ field, value, onAction }) => {
+  const rows = value ?? field.rows ?? [];
+  return html`
+    <div class="my-config-card">
+      <h3>${field.label}</h3>
+      <nile-dropdown>
+        ${(field.actions ?? []).map((a) => html`<nile-menu-item @click=${() => onAction?.(a)}>${a.label}</nile-menu-item>`)}
+      </nile-dropdown>
+      <!-- ... your own row rendering ... -->
+    </div>
+  `;
+});
+```