@aquera/mcp-ui-render 0.0.1

package/src/elements/aq-mcp-config.d.ts

@@ -0,0 +1,289 @@
+/**
+ * `<aq-mcp-config>` — root element. Owns the descriptor + values + validation
+ * state, renders ordered sections (§12), and emits intent for the host:
+ *   - `aq-mcp-change` — on any field edit `{ attribute, value, values }`
+ *   - `aq-mcp-submit` — per-section save `{ sectionKey, submitTool, values }` (§13/§14)
+ *   - `aq-mcp-action` — button/action `{ tool, args, confirm, field, action }` (§5).
+ *     `action` is the specific `FieldAction` clicked for a multi-action control's
+ *     own toolbar (e.g. `properties-table`'s "Download"/"Edit Configuration"),
+ *     undefined for the classic single-action `button` control.
+ *   - `aq-mcp-options-request` — a `select`/`radio` field with `tool` set has no
+ *     options yet `{ attribute, tool, args }` (§9.6); host resolves + feeds them
+ *     back via the `dynamicOptions` property (see below), one request per attribute.
+ * It performs NO network I/O and holds no secrets (D-4): it renders, validates,
+ * and emits; the host executes tools. A host driving its OWN "submit
+ * everything" button (bypassing per-section footers) can call the public
+ * `validateAll()` method directly on the element to get the library's real
+ * validation + inline field-error display instead of just the raw `values`.
+ * Every field is also validated live on its own edits (`onFieldInput`), not
+ * just on submit — its error updates the instant its value changes.
+ * `sectionsLayout` ('stacked' default, or 'tabs' with `tabsPlacement` for
+ * orientation) controls how sections are arranged — everything else
+ * (validation, submit, footers) behaves identically in either layout.
+ * `tabsShowErrorIndicator` (default true, tabs mode only) puts a red dot on a
+ * tab whose section has a required-but-empty or invalid field, computed live
+ * — not just after a failed submit.
+ *
+ * Renders into LIGHT DOM (`createRenderRoot()` returns `this`, no shadow
+ * root) on all three elements in this package, deliberately: it lets Nile's
+ * CSS custom-property tokens (`--ng-*`/`--nile-*`) and `mcp-ui-render.css`
+ * cascade in from the host's own stylesheet the same way any other page
+ * content does, with no per-shadow-root style injection needed. The
+ * trade-off is zero style encapsulation — a host's global CSS can affect
+ * `.aq-mcp-*` classes and vice versa — and it means `mcp-ui-render.css` MUST
+ * be loaded globally by the host; without it these elements render
+ * structurally correct but entirely unstyled, with no error or warning
+ * (see USAGE.md "Styling & light DOM").
+ */
+import { LitElement, type PropertyValues, type TemplateResult } from 'lit';
+import type { Descriptor, Values } from '../types.js';
+import './aq-mcp-section.js';
+export declare class AqMcpConfig extends LitElement {
+    /** The `bootstrap` response to render. */
+    descriptor: Descriptor | null;
+    /** Current values keyed by `attribute`. */
+    values: Values;
+    /**
+     * Host-fed options for `select`/`radio` fields whose list is resolved dynamically
+     * (`field.tool` set, e.g. `listFtpServers`) rather than declared statically as
+     * `field.options` (§9.6) — keyed by `field.attribute`. This library performs no
+     * network I/O itself (D-4): it only ASKS, via `aq-mcp-options-request`; the host
+     * calls the tool and sets the result back in here (immutably — a new object, not
+     * a mutated one, so Lit's property-changed check fires):
+     *
+     *   el.addEventListener('aq-mcp-options-request', async (e) => {
+     *     const { attribute, tool, args } = e.detail;
+     *     const options = await host.callTool(tool, args); // e.g. FTP server list
+     *     el.dynamicOptions = { ...el.dynamicOptions, [attribute]: options };
+     *   });
+     *
+     * Takes priority over `field.options` when both are present for the same
+     * attribute. A field is requested at most once per attribute for this
+     * element's lifetime — a host that needs to force a refresh re-triggers it
+     * itself (out of scope here, same "host decides" split as `validateAll()`).
+     */
+    dynamicOptions: Record<string, unknown[]>;
+    /** Master switch for every section's footer (§13/§14) — the default "Save
+     *  <label>" button, AND any `registerSectionFooter` override. Default true;
+     *  set false to hide every section's footer at once, e.g. when the host
+     *  drives submission itself via its own button(s). */
+    showSectionFooters: boolean;
+    /** How sections are laid out. `'stacked'` (default) is today's behavior —
+     *  every section as its own card, one after another. `'tabs'` renders one
+     *  `nile-nav-tab` per section (nav) with the section's own card as that
+     *  tab's panel — orientation controlled by `tabsPlacement`. `'accordion'`
+     *  renders one `nile-accordion` per section, single-open, with a completion
+     *  summary in each collapsed header (field count + status chip) and a
+     *  two-column, label-above-control body — see `renderAccordion`. */
+    sectionsLayout: 'stacked' | 'tabs' | 'accordion';
+    /** Tab orientation when `sectionsLayout === 'tabs'` — passed straight
+     *  through to `nile-nav-tab-group`'s own `placement`. Ignored in
+     *  `'stacked'` mode. `'start'` gives a left-hand vertical tab list. */
+    tabsPlacement: 'top' | 'bottom' | 'start' | 'end';
+    /** In `'tabs'` mode, show a small red dot next to a tab's label when that
+     *  section has a required-but-empty field or a live validation error — lets
+     *  the user spot which tab needs attention without opening it. Default
+     *  true (this is a pure addition with no prior equivalent, so there's
+     *  nothing to stay backward-compatible with); set false to opt out.
+     *  Ignored in `'stacked'` mode, where inline field errors are already
+     *  visible without needing a tab-level summary. */
+    tabsShowErrorIndicator: boolean;
+    /** Which section starts expanded in `'accordion'` mode. Left unset
+     *  (`null`), the library picks: the first section with a required-but-empty
+     *  field, else the first visible section — so a form always opens on the
+     *  part that still needs work. A section `key` pins that section instead;
+     *  the empty string starts every section collapsed. Only consulted when the
+     *  descriptor (or this property) changes — never re-evaluated on a value
+     *  edit, which would slam the card the user is typing in shut. Ignored in
+     *  the other layouts. */
+    accordionOpenSection: string | null;
+    /** Show the open section's save footer in `'accordion'` mode. Default
+     *  FALSE, unlike the other two layouts: an accordion is a whole-form
+     *  overview, and the host normally drives one submit for all of it via
+     *  `validateAll()`. Set true to get the per-section "Save <label>" button
+     *  here too; `showSectionFooters` still overrides both to off. Ignored in
+     *  the other layouts. */
+    accordionShowFooters: boolean;
+    /** How many columns the open section's field grid uses in `'accordion'`
+     *  mode. `2` (default) is the side-by-side layout; `1` stacks every field
+     *  full width, which suits a narrow container, a long-label descriptor, or
+     *  simply a host that prefers a single reading column.
+     *
+     *  This is 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 (see `.aq-mcp-section__body--dense`), so `1` means "never two",
+     *  not "always exactly one regardless of space". Ignored in the other
+     *  layouts, whose rows are single-column by construction. */
+    accordionColumns: 1 | 2;
+    /** Host override for section header icons in `'accordion'` mode, keyed by
+     *  `section.key` → `nile-glyph` name. Highest priority in a three-step
+     *  fallback: this map, then the descriptor's own `section.icon`, then
+     *  `DEFAULT_SECTION_ICONS` below. The host wins because it knows the
+     *  product's iconography; the descriptor only knows the connector. */
+    sectionIcons: Record<string, string>;
+    private errors;
+    /** The single expanded section's `key` in `'accordion'` mode, or null when
+     *  all are collapsed. Holding ONE key is what makes the accordion
+     *  single-open: setting it re-renders every sibling with `open=false`. */
+    private openKey;
+    private pendingAction;
+    /** Attributes already asked about via `aq-mcp-options-request` — a plain dedupe
+     *  guard, not rendered state, so mutated in place rather than reassigned (no
+     *  need to trigger a Lit update for it). */
+    private requestedOptions;
+    protected createRenderRoot(): HTMLElement;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** The section to expand first: an explicit `accordionOpenSection` wins
+     *  (including `''` for "all collapsed"), else the first section still
+     *  missing a required value, else the first visible one. */
+    private resolveOpenKey;
+    /** Sections in render order (§12) — `order` ascending, missing treated as 0. */
+    private sortedSections;
+    protected updated(changed: PropertyValues<this>): void;
+    /** Emits `aq-mcp-options-request` for every currently-applicable `select`/`radio`
+     *  field that declares `tool` but has no options yet — neither a static
+     *  `field.options` nor an already-fed `dynamicOptions` entry — and hasn't been
+     *  asked about before. Skipped for a field that's statically hidden or whose
+     *  `dependencyAttribute` condition isn't currently met (§12) — no point asking
+     *  for FTP servers before the user has even chosen SFTP storage. */
+    private requestPendingOptions;
+    /** Look up a field's own schema by `attribute` — needed to re-validate it
+     *  live on every edit (`onFieldInput`), since the event only carries the
+     *  new value, not the field definition itself. */
+    private fieldByAttribute;
+    /** Whether a field is currently in play for validation — skips
+     *  `datatype: "none"` (buttons/reports never hold a value), statically
+     *  hidden fields, and fields whose `dependencyAttribute` condition isn't
+     *  currently met. Shared by `computeErrors`, live on-change validation, and
+     *  the tab error-indicator, so all three agree on what "applicable" means. */
+    private fieldNeedsValidation;
+    private onFieldInput;
+    private onFieldAction;
+    private onSectionSubmit;
+    private emitAction;
+    /** Validate one batch of fields against the current `values` — shared by
+     *  `validateSection` (one section) and the public `validateAll` (every
+     *  section), so both paths compute errors identically. */
+    private computeErrors;
+    /** Does this section have an actual, currently-recorded validation error —
+     *  i.e. a field present in `this.errors` with a message. Deliberately reads
+     *  `this.errors`, NOT a fresh re-validation of every field: a required field
+     *  the user simply hasn't reached yet is incomplete, not invalid, and
+     *  shouldn't flag its tab before the user has done anything. An error only
+     *  lands in `this.errors` once a field has actually been edited (live
+     *  validation) or the section/form has been submitted at least once —
+     *  exactly the same "has this field's error actually surfaced" signal the
+     *  inline per-field error display already uses. */
+    private sectionHasError;
+    private validateSection;
+    private submitSection;
+    /** Validate every section's applicable fields at once and return the full
+     *  form state. Pushes results into this element's own `errors` state — the
+     *  same thing a section's Save button does via `validateSection`, just
+     *  across ALL sections at once — so a host-driven "submit everything"
+     *  button (bypassing per-section footers entirely) still gets the
+     *  library's real validation and inline field-error display, not just the
+     *  raw `values`. Call it imperatively on the element (e.g. an Angular
+     *  template ref: `<aq-mcp-config #cfg>` then `cfg.validateAll()`) — there's
+     *  no natural event to hang this off, since the host decides what "submit
+     *  everything" even means for its own data shape. */
+    validateAll(): {
+        valid: boolean;
+        values: Values;
+    };
+    render(): TemplateResult;
+    /** Dispatch to the layout the host asked for. `'stacked'` — today's
+     *  default — is the fallback for any unrecognised value, so a typo'd
+     *  attribute renders a usable form rather than nothing. */
+    private renderSections;
+    /** A section whose every field is statically hidden has nothing to show
+     *  (§7, §12) — in 'stacked' mode `renderSection` just renders nothing for
+     *  it; in 'tabs' mode it must not get a tab at all (an empty tab is worse
+     *  than no tab), so this filters the nav list up front. */
+    private visibleSections;
+    private renderTabs;
+    /**
+     * Is this `nile-show`/`nile-hide` the ACCORDION's own, or one that bubbled up
+     * from a descendant?
+     *
+     * Every Nile component emits with `bubbles: true, composed: true`
+     * (`internal/nile-element.ts`), and `nile-tooltip` emits the same
+     * `nile-show`/`nile-hide` names an accordion does. A field's help tooltip
+     * lives inside the open card, so without this guard simply hovering an info
+     * icon opened the section and dismissing the tooltip COLLAPSED it — the
+     * card slamming shut under the user's cursor.
+     *
+     * `currentTarget` is the `nile-accordion` the listener sits on;
+     * `target` is whatever emitted. Comparing them keeps a descendant's
+     * identically-named event from driving this element's open state, and stays
+     * correct for any future nested Nile component that reuses these names.
+     */
+    private static isOwnDisclosure;
+    /**
+     * `sectionsLayout: 'accordion'` — one `nile-accordion` per visible section,
+     * single-open, in §12 order.
+     *
+     * Single-open falls out of holding ONE key: `nile-accordion` owns its own
+     * `open` flag, so both directions are wired — `?open` down from `openKey`,
+     * `nile-show`/`nile-hide` back up. Setting `openKey` on a show re-renders
+     * every sibling with `open=false`, which closes them; there's no need to
+     * imperatively call `hide()` on the others.
+     */
+    /** Host map first, then the built-in map for the contract's own section
+     *  keys, then a generic glyph. The descriptor has no icon field and its
+     *  shape is fixed, so the host is the only place a product can override
+     *  this — which is the right place anyway: iconography is the app's
+     *  decision, not the connector's. */
+    private iconFor;
+    /**
+     * The header's completion readout, for a section the user may never open.
+     *
+     * A mark and a NUMBER, no sentence. The count is descriptor-derived (how
+     * many `isRequired` fields still hold no value); the check and the dot are
+     * symbols. An earlier version read "Complete" and "N required left", which
+     * is the renderer narrating state in words the descriptor never supplied.
+     *
+     * The trade-off is real and worth naming: a bare dot-and-count is terser
+     * than "2 required left", and leans on the reader connecting it to the `*`
+     * marks inside the card. `title` carries the count on hover and to assistive
+     * tech using the descriptor's own key name rather than invented prose.
+     */
+    private renderSectionStatus;
+    /**
+     * `sectionsLayout: 'accordion'` — one `nile-accordion` per visible section,
+     * single-open, in §12 order. Each header is an icon tile, the section
+     * `label`, its `authType` badge, and a completion status beside the chevron,
+     * so a collapsed section says what it is and whether it still needs work
+     * without being opened.
+     *
+     * Every word of connector-describing text here is a descriptor VALUE
+     * rendered verbatim — `section.label` and `section.authType`. An earlier
+     * version composed a sentence around them ("Basic authentication · saved by
+     * the platform"), which read as the connector's own description of itself
+     * but was the renderer putting words in its mouth: only "Basic" came from
+     * the descriptor, and "saved by the platform" was inferred from a key being
+     * ABSENT. The `bootstrap` format carries no prose field, so rather than
+     * invent one, nothing is written here that the descriptor did not supply.
+     *
+     * Single-open falls out of holding ONE key: `nile-accordion` owns its own
+     * `open` flag, so both directions are wired — `?open` down from `openKey`,
+     * `nile-show`/`nile-hide` back up. Setting `openKey` on a show re-renders
+     * every sibling with `open=false`, which closes them; there's no need to
+     * imperatively call `hide()` on the others.
+     */
+    private renderAccordion;
+    /** `compact` drops the per-section card's own border + title (the tab nav
+     *  already shows the label) when nested inside a tab panel — the authType
+     *  badge and save-target caption still show either way. `dense` is the
+     *  accordion equivalent: the card AND the header go (the accordion's own
+     *  summary carries all of it), and the body switches to the two-column,
+     *  label-above-control grid. They're separate flags, not one enum, because
+     *  each drops a different amount of chrome. */
+    private renderSection;
+    private renderConfirm;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'aq-mcp-config': AqMcpConfig;
+    }
+}