@aquera/mcp-ui-render 0.0.1

package/src/registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Component registry (§9.1 extensibility): `ui-component` string → a Lit control
+ * renderer. New components register into the map without touching the engine;
+ * an unknown `ui-component` falls back to the datatype's default control, so a
+ * field is never dropped.
+ */
+import type { TemplateResult } from 'lit';
+import type { Datatype, Field, FieldAction, Section, Values } from './types.js';
+/** What a control renderer receives from the field engine. */
+export interface ControlContext {
+    field: Field;
+    value: unknown;
+    /** Validation message to show, or null when valid. */
+    error: string | null;
+    /** Emit a new value for this field's `attribute` (§14). */
+    onInput: (value: unknown) => void;
+    /** Invoke a `button`/action field (§5), or one entry from `field.actions` for a
+     *  control with more than one independent action — omit the argument for the
+     *  single-action `button` case (uses the field's own `tool`/`args`/`confirm`),
+     *  pass the specific `FieldAction` for a multi-action toolbar. No-op for plain
+     *  value controls that never call it at all. */
+    onAction?: (action?: FieldAction) => void;
+    /** Host-fed options for `select`/`radio` fields whose list is resolved
+     *  dynamically via `field.tool` rather than declared statically in the
+     *  descriptor (§9.6) — keyed by `field.attribute`. Only consulted when
+     *  `field.options` is absent/empty; see `<aq-mcp-config>`'s `dynamicOptions`
+     *  property and the `aq-mcp-options-request` event. */
+    dynamicOptions?: Record<string, unknown[]>;
+    /**
+     * The field's row is being laid out label-ABOVE-control in a narrow grid
+     * cell (`sectionsLayout: 'accordion'`), rather than in the roomy
+     * label-left/control-right row the other two layouts use. Purely advisory:
+     * every built-in control renders correctly either way, and a custom control
+     * that ignores this 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, which is only legible in the dense
+     * grid where an empty box would otherwise say nothing at all.
+     */
+    dense?: boolean;
+}
+export type ControlRenderer = (ctx: ControlContext) => TemplateResult;
+/** Register (or override) the renderer for a `ui-component`. */
+export declare function registerControl(name: string, renderer: ControlRenderer): void;
+/** Resolve a renderer by `ui-component`, or undefined if none is registered. */
+export declare function resolveControl(uiComponent: string): ControlRenderer | undefined;
+/** What a section-footer renderer receives in place of the library's default save button. */
+export interface SectionFooterContext {
+    section: Section;
+    values: Values;
+    /** Validate + emit `aq-mcp-submit` for this section (§13/§14), same as the default button. */
+    onSubmit: () => void;
+}
+export type SectionFooterRenderer = (ctx: SectionFooterContext) => TemplateResult;
+/**
+ * Register (or override) a custom footer for a section, keyed by `section.key`
+ * (e.g. `"authorization"`). Replaces the library's default "Save <label>" button
+ * entirely — the renderer owns the markup and must call `onSubmit` itself.
+ */
+export declare function registerSectionFooter(key: string, renderer: SectionFooterRenderer): void;
+/** Resolve a custom footer renderer by section key, or undefined for the library default. */
+export declare function resolveSectionFooter(key: string): SectionFooterRenderer | undefined;
+/** The fallback control name for a datatype when `ui-component` is unknown (§9.1). */
+export declare function defaultControlFor(datatype: Datatype): string;

package/src/registry.js

@@ -0,0 +1,39 @@
+const registry = new Map();
+/** Register (or override) the renderer for a `ui-component`. */
+export function registerControl(name, renderer) {
+    registry.set(name, renderer);
+}
+/** Resolve a renderer by `ui-component`, or undefined if none is registered. */
+export function resolveControl(uiComponent) {
+    return registry.get(uiComponent);
+}
+const footerRegistry = new Map();
+/**
+ * Register (or override) a custom footer for a section, keyed by `section.key`
+ * (e.g. `"authorization"`). Replaces the library's default "Save <label>" button
+ * entirely — the renderer owns the markup and must call `onSubmit` itself.
+ */
+export function registerSectionFooter(key, renderer) {
+    footerRegistry.set(key, renderer);
+}
+/** Resolve a custom footer renderer by section key, or undefined for the library default. */
+export function resolveSectionFooter(key) {
+    return footerRegistry.get(key);
+}
+/** The default `ui-component` for each datatype (§4). `object` defaults to `textarea`, not
+ *  `input` — a single line is a poor fit for JSON, and `textarea` is what `controls.ts`'s
+ *  object-aware JSON display/parsing is built around. */
+const DATATYPE_DEFAULT = {
+    string: 'input',
+    number: 'input',
+    boolean: 'checkbox',
+    array: 'select',
+    object: 'textarea',
+    file: 'file',
+    none: 'button',
+};
+/** The fallback control name for a datatype when `ui-component` is unknown (§9.1). */
+export function defaultControlFor(datatype) {
+    return DATATYPE_DEFAULT[datatype] ?? 'input';
+}
+//# sourceMappingURL=registry.js.map

package/src/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../apps/mcp-ui-render/src/registry.ts"],"names":[],"mappings":"AA4CA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;AAEpD,gEAAgE;AAChE,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,QAAyB;IACrE,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,OAAO,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AACnC,CAAC;AAYD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAiC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,QAA+B;IAChF,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;yDAEyD;AACzD,MAAM,gBAAgB,GAA6B;IACjD,MAAM,EAAE,OAAO;IACf,MAAM,EAAE,OAAO;IACf,OAAO,EAAE,UAAU;IACnB,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,UAAU;IAClB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,QAAQ;CACf,CAAC;AAEF,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,QAAkB;IAClD,OAAO,gBAAgB,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC;AAC/C,CAAC"}

package/src/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * TypeScript model of the `bootstrap` tenant-configuration descriptor
+ * (bootstrap-tool-tenant-config.md §2–§3). `additionalProperties: true` at both
+ * the section and field level is honoured with index signatures so unknown keys
+ * survive a round-trip (§9.4).
+ */
+/** The closed set of value types (§4). */
+export type Datatype = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'file' | 'none';
+/** The one auth shape an application uses (§2 Section). Metadata — never submitted. */
+export type AuthType = 'Basic' | 'Bearer' | 'Header' | 'URL' | 'OAuth2' | 'OAuth2-client_credentials' | 'BasicNBearer';
+/** A single control descriptor (§3 $defs/field). */
+export interface Field {
+    attribute: string;
+    datatype: Datatype;
+    /** How it renders. Open set — an unknown value falls back to the datatype default (§9.1). */
+    'ui-component': string;
+    label?: string;
+    help?: string;
+    /**
+     * `select`/`radio` only. Each entry is either a plain primitive (its value IS its
+     * display text — the original contract) or `{ value, label }` when the submitted
+     * code and its human-readable display name differ, e.g.
+     * `{ value: 'sftpStorage', label: 'SFTP Storage' }`. `value` is always what's
+     * emitted/submitted; `label` (when present) is what's shown to the user.
+     */
+    options?: unknown[];
+    defaultValue?: unknown;
+    isRequired?: boolean;
+    hidden?: boolean;
+    readOnly?: boolean;
+    secret?: boolean;
+    writeOnce?: boolean;
+    /** ECMAScript regex sources, whole-value, AND-combined (§8). */
+    validation?: string[];
+    validationmessage?: string;
+    min?: number;
+    max?: number;
+    minItems?: number;
+    maxItems?: number;
+    /** `datatype: "file"` only — allowed MIME types/extensions (e.g. `["image/png", ".pdf"]`). */
+    accept?: string[];
+    /** `datatype: "file"` only — max size per file, in KB. */
+    maxSizeKB?: number;
+    requiredKeys?: string[];
+    dependencyAttribute?: string;
+    dependencyValue?: string | string[];
+    /**
+     * Compound dependency (§12 amendment, §9.7) — a field applies if `dependencyAttribute`
+     * matches OR any entry here matches, i.e. an OR across MULTIPLE fields' values, not just
+     * one. For a field gated on a single attribute, `dependencyAttribute`/`dependencyValue`
+     * alone is still enough — this exists for the case where two DIFFERENT fields can each
+     * independently make a field relevant (e.g. an FTP-server picker that applies when
+     * `sourceConnectionType === 'directConnection'` OR `storageType === 'sftpStorage'`, two
+     * unrelated fields, neither of which alone tells the whole story).
+     */
+    dependsOn?: {
+        attribute: string;
+        value: string | string[];
+    }[];
+    /** button/submitTool wiring. */
+    tool?: string;
+    args?: Record<string, unknown>;
+    confirm?: string;
+    /** e.g. "secretRef:entraid/client_secret" — a reference, never a live secret (§7). */
+    valueFrom?: string;
+    /**
+     * `properties-table` only — static rows declared directly in the descriptor, for
+     * data the connector already knows when it builds the `bootstrap` response (no
+     * host-side computation needed). Same "descriptor-declared default, host-supplied
+     * `values[attribute]` wins if present" priority `options`/`dynamicOptions` already
+     * have for `select`/`radio` (§9.6) — see `PropertiesTableRow`.
+     */
+    rows?: PropertiesTableRow[];
+    /**
+     * A toolbar of named actions rendered by the control itself (currently
+     * `properties-table` only), distinct from the single `tool`/`args`/`confirm` a
+     * whole `button`-datatype field already represents (§5) — for a control that
+     * needs MORE THAN ONE independent action (e.g. "Download"/"Edit Configuration").
+     * Each entry carries its own `tool`/`args`/`confirm`; `onAction` is called with
+     * the specific action clicked, so the host can tell which one fired. A field
+     * with no `actions` renders no toolbar at all — purely additive, no effect on
+     * the existing single-action `button` control.
+     *
+     * This shape only describes the DEFAULT rendering (icon-only `nile-icon-button`
+     * when `icon` is set, else a labeled `nile-button`). A host that wants different
+     * toolbar UI entirely — different button styling, a dropdown instead of inline
+     * buttons, extra chrome around the actions — doesn't need a new hook for that:
+     * `registerControl('properties-table', myRenderer)` (§9.1) already replaces the
+     * WHOLE control, toolbar included, the same escape hatch every other control in
+     * this library relies on for "the default doesn't fit, build your own."
+     */
+    actions?: FieldAction[];
+    /** Unknown keys preserved on round-trip (§9.4). */
+    [k: string]: unknown;
+}
+/**
+ * One entry in `Field.actions` — a named, independently-invokable action a
+ * control's own toolbar exposes (see `Field.actions`'s doc comment for why this
+ * exists alongside the single-action `button` control). `icon` (a `nile-glyph`
+ * name) selects an icon-only button; omit it for a labeled text button.
+ */
+export interface FieldAction {
+    key: string;
+    label: string;
+    tool: string;
+    args?: Record<string, unknown>;
+    confirm?: string;
+    icon?: string;
+}
+/** An ordered group of fields (§2 Section). */
+export interface Section {
+    key: string;
+    label: string;
+    order: number;
+    authType?: AuthType;
+    /** When set, the connector saves this section via this tool instead of the platform default (§13). */
+    submitTool?: string;
+    fields: Field[];
+    [k: string]: unknown;
+}
+/** The full response envelope (§2). */
+export interface Descriptor {
+    /** Contract version MAJOR.MINOR — consumers switch on MAJOR only (§9.5). */
+    version: string;
+    server: {
+        name: string;
+        version: string;
+        [k: string]: unknown;
+    };
+    sections: Section[];
+    [k: string]: unknown;
+}
+/** Collected values keyed by `attribute` (§14). */
+export type Values = Record<string, unknown>;
+/**
+ * One probe in a `test-connection-report` value (§5, `ui-component:
+ * "test-connection-report"`). `SKIPPED` covers a check the host never ran —
+ * e.g. because an earlier config-validation check already failed — and
+ * renders as neutral, not a failure.
+ */
+export interface TestConnectionCheck {
+    name: string;
+    /** `null`/omitted for a config-validation check that never called anything. */
+    endpoint?: string | null;
+    /** Open categorisation string, e.g. "auth" | "capability" | "probe" | "config". */
+    category?: string;
+    /** @deprecated superseded by `category`; still accepted for older payloads. */
+    type?: string;
+    /** For a config-validation check: the tenant-attribute name it validated. */
+    attribute?: string;
+    status: 'PASSED' | 'FAILED' | 'SKIPPED' | string;
+    /** For a config-validation check: was this attribute required/supplied/well-formed. */
+    required?: boolean;
+    provided?: boolean;
+    valid?: boolean;
+    httpStatus?: number;
+    message?: string;
+    errorCode?: string;
+    /** Shown collapsed under the check, in a "How to fix" accordion, when `status` is FAILED. */
+    mitigation?: string;
+}
+/**
+ * The value shape for `ui-component: "test-connection-report"` (`datatype: "none"` —
+ * read-only, never submitted). The host sets this into `values[attribute]` after
+ * running its own connection-test tool; the library only renders it.
+ */
+export interface TestConnectionReport {
+    success: boolean;
+    connectionStatus: 'SUCCESS' | 'PARTIAL' | 'FAILED' | 'CONFIG_INVALID' | string;
+    /** ISO 8601 timestamp. */
+    testedAt: string;
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped?: number;
+    };
+    checks: TestConnectionCheck[];
+    /** A hard failure to even run the test (distinct from an individual check failing). */
+    error?: string | null;
+    /**
+     * Optional business-impact sentence for the banner's second line (e.g. "Payroll
+     * data will not be pulled until the failed check is resolved") — supplied by the
+     * host, which knows what the connector's checks mean; the library never invents it.
+     */
+    impact?: string;
+}
+/**
+ * One row for `ui-component: "permissions-report"` (`datatype: "none"` — read-only,
+ * never submitted) — a single scope/permission the connector's credentials were
+ * checked against. `access` is free-form (matching the live reference's own
+ * "Granted" badge text) rather than a closed enum, same "open categorisation
+ * string" choice `TestConnectionCheck.category` already made.
+ */
+export interface PermissionGrant {
+    resourceType: string;
+    permissionType: string;
+    access: 'Granted' | 'Denied' | string;
+}
+/**
+ * The value shape for `ui-component: "permissions-report"` (`datatype: "none"` —
+ * read-only, never submitted, same contract as `test-connection-report`). Distinct
+ * from `TestConnectionReport`: that shape models a list of PASS/FAIL endpoint
+ * probes, this one models a scope/permission GRANT table with a running count and
+ * an All/Success filter — the live reference's own "Credentials" tab Test
+ * Connection result renders exactly this shape (a "Validation Report" of
+ * `resourceType`/`permissionType`/`access` rows), not the endpoint-checklist shape.
+ * The host sets this into `values[attribute]` after running its own
+ * credential-validation tool; the library only renders it.
+ */
+export interface PermissionsValidationReport {
+    valid: boolean;
+    /** e.g. "The provided credentials are valid. All permissions granted." */
+    message: string;
+    /** ISO 8601 timestamp. */
+    testedAt: string;
+    grants: PermissionGrant[];
+}
+/**
+ * One row for `ui-component: "properties-table"` (`datatype: "none"` — read-only,
+ * never submitted). Two ways to supply `PropertiesTableRow[]`, same priority
+ * `select`/`radio` already have between `options` and `dynamicOptions` (§9.6):
+ *  - **Static, in the descriptor itself** — `field.rows`, for data the connector
+ *    already knows when it builds the `bootstrap` response (no host computation
+ *    needed at all).
+ *  - **Dynamic, host-supplied** — `values[attribute]`, for data the host computes
+ *    at render time (typically summarizing a handful of OTHER attributes' current
+ *    values) — same "host computes, library only displays" split
+ *    `test-connection-report` already established. Wins over `field.rows` when
+ *    both are present, for the same reason a host-fed `dynamicOptions` entry wins
+ *    over a field's static `options`: the host's data is necessarily more current.
+ */
+export interface PropertiesTableRow {
+    property: string;
+    /** Rendered as-is for most types; booleans/arrays/long strings get light
+     *  formatting (see `controls.ts`'s `formatTableValue`) — never re-interpreted
+     *  or validated, since this is a display-only control. */
+    value: unknown;
+}

package/src/types.js

@@ -0,0 +1,8 @@
+/**
+ * TypeScript model of the `bootstrap` tenant-configuration descriptor
+ * (bootstrap-tool-tenant-config.md §2–§3). `additionalProperties: true` at both
+ * the section and field level is honoured with index signatures so unknown keys
+ * survive a round-trip (§9.4).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../apps/mcp-ui-render/src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}