@ethisyscore/plugin-ui 1.92.1 → 1.94.1

package/dist/components/connectors/index.d.cts

@@ -1,374 +1,166 @@
+import { C as ConnectorCanonicalField } from '../../mappingQueryKeys-BcbA0TGy.cjs';
+export { a as CONNECTOR_CONTROL_LABEL, b as ConnectorCanonicalFieldKind, c as ConnectorMappingSuggestionResult, d as ConnectorMappingTranslationEditorProps, e as ConnectorMappingTranslationEditorView, M as MappingCompletenessBanner, f as MappingCompletenessBannerProps, g as MappingCompletenessItem, h as MappingCompletenessResult, i as MappingReadiness, P as PLUGIN_PROVIDER_CONTROL_LABEL, j as PROVIDER_CONTROL_LABEL, k as PROVIDER_OPTION_LABEL, T as TestToolMappingExtractedField, l as TestToolMappingRequest, m as TestToolMappingResult, n as connectorMappingCompletenessQueryKey, o as connectorMappingsQueryKey, p as connectorMappingsRootQueryKey, q as pluginTargetMappingsQueryKey, s as selectIncompleteOperations, r as selectMappingReadiness, t as selectOptionalIncompleteOperations, u as selectRequiredIncompleteOperations } from '../../mappingQueryKeys-BcbA0TGy.cjs';
 import * as react from 'react';
+import { ReactNode } from 'react';
 
-/**
- * Per-operation mapping completeness for one connector + module, as returned by the host's
- * `connectors:mappings:completeness` tool.
- *
- * Declared here rather than imported from a plugin's generated contracts because this package sits
- * BELOW the plugins: every plugin that shows a Tool Mappings page had its own copy of this shape,
- * and the copies are what let the surfaces drift apart.
- *
- * @remarks
- * The distinction that matters, and the one every copy of the banner got wrong at least once:
- * `isToolMapped` and `unmappedRequiredCanonicalFields` are INDEPENDENT. An operation can have a tool
- * mapped and still be incomplete, because the tool's schema does not accept a field the operation
- * requires. Copy that says "not mapped" when it means "fields not mapped" sends the operator to
- * auto-match, which maps tools and cannot close a field gap.
- */
-interface MappingCompletenessItem {
-    /** Canonical operation key, e.g. `list-commits`. */
-    operationKey: string;
-    /** Human label for the operation, as declared by the module's catalogue. */
-    label: string;
-    /**
-     * Whether the module declares this operation as required. Required gaps block the module from
-     * working; optional ones only leave an extra capability switched off.
-     */
-    isRequired: boolean;
-    /**
-     * Whether ANY tool is mapped to the operation. False means the operator has not chosen a tool
-     * yet; true says nothing about whether the mapping is complete.
-     */
-    isToolMapped: boolean;
-    /**
-     * Canonical request fields the operation requires that do not map onto a property the live tool
-     * actually accepts. Non-empty means incomplete, whether or not a tool is mapped.
-     */
-    unmappedRequiredCanonicalFields: string[];
-}
-/** Response envelope for the completeness read, post-unwrap. */
-interface MappingCompletenessResult {
-    operations: MappingCompletenessItem[];
+declare const SOURCE: {
+    readonly keyword: "keyword";
+    readonly ai: "ai";
+    readonly manual: "manual";
+};
+/** The vocabulary of `ToolMapping.Source` values the backend writes. Derived so the two cannot drift. */
+type MappingSourceValue = (typeof SOURCE)[keyof typeof SOURCE];
+/** A connector offered in the picker. */
+interface ConnectorMappingViewConnector {
+    id: string;
+    name: string;
 }
 /**
- * Type discriminator for a canonical field. Mirrors the backend `CanonicalFieldKind` enum.
- *
- * Wire format is the enum member name (e.g. `"String"`, `"StringArray"`); the editor renders the
- * value verbatim as the field-kind chip, so an unrecognised kind degrades to a label rather than
- * a blank.
+ * What serves the module, as this view spells it. Structurally identical to `MappingTargetKind` in
+ * the hooks module, declared here for the reason every shape in this file is: the two barrels share
+ * types across the boundary only as type-only imports, and this one is two literals.
  */
-type ConnectorCanonicalFieldKind = "String" | "Integer" | "Boolean" | "DateTime" | "Object" | "StringArray";
-/**
- * A single canonical field on an operation's request or response schema. Carried on the mapping row
- * so the editor can render an input per field without a separate schema fetch.
- */
-interface ConnectorCanonicalField {
+type ConnectorMappingViewProviderKind = "connector" | "plugin";
+/** An installed application offered in the provider picker. */
+interface ConnectorMappingViewPluginProvider {
+    extensionId: string;
     name: string;
-    kind: ConnectorCanonicalFieldKind;
-    isRequired: boolean;
 }
-/**
- * Arguments the editor hands to the consumer-supplied `onTestMapping` callback. The consumer builds
- * the full service request from these plus its own `connectorId` / `operationKey` / `toolName` — the
- * editor owns no network call.
- */
-interface TestToolMappingRequest {
-    /** Sample values the operator typed — one entry per canonical request field. */
-    sampleArgs: Record<string, unknown>;
-    /** Current unsaved request-field map (empty inputs stripped; `null` if all blank). */
+/** A tool offered in the per-row picker. */
+interface ConnectorMappingViewTool {
+    name: string;
+    description: string;
+}
+/** The operator-editable translation on one row, as handed to `onEditTranslation`. */
+interface ConnectorMappingViewTranslationState {
     requestFieldMap: Record<string, string> | null;
-    /** Current unsaved response-field paths (empty inputs stripped; `null` if all blank). */
     responseFieldPaths: Record<string, string> | null;
-    /**
-     * Current unsaved static request parameters (blank-key rows dropped; `null` if none). Optional and
-     * backward-compatible: it lets the dry-run exercise the DRAFT static params — a consolidated
-     * tool's `method` discriminator, say — that the operator typed but has not saved yet. A consumer
-     * whose test endpoint does not accept static fields simply ignores it.
-     */
-    staticRequestFields?: Record<string, string> | null;
-}
-/**
- * Result of extracting one canonical response field from the tool's raw response. Mirrors the
- * backend `ExtractedFieldResult` DTO.
- */
-interface TestToolMappingExtractedField {
-    canonicalField: string;
-    /** Extracted value, or `null` when the path matched nothing. */
-    value: string | null;
-    /** `true` when the JSON path resolved to a node in the response. */
-    present: boolean;
-    /**
-     * `true` when the extracted value looks like Base64 content (long string, charset
-     * `[A-Za-z0-9+/=]`, no whitespace). The editor shows a "prefix with base64:" hint so the operator
-     * adjusts the JSON path rather than concluding the mapping is broken.
-     */
-    looksBase64: boolean;
-}
-/** Result the consumer's `onTestMapping` callback resolves with, after the dry-run. */
-interface TestToolMappingResult {
-    success: boolean;
-    /** Error message when `success` is false. */
-    error: string | null;
-    /**
-     * Raw JSON string of the tool's response, shown in a collapsible so the operator can find the
-     * right JSON path.
-     */
-    rawResponseJson: string | null;
-    /** Per-field extraction result. */
-    extractedFields: TestToolMappingExtractedField[];
+    staticRequestFields: Record<string, string> | null;
 }
-/**
- * Result the consumer's `onSuggestTranslation` callback resolves with. When `success` is true, the
- * editor merges the two dictionaries over its current inputs so the operator can review the
- * AI proposal before saving.
- */
-interface ConnectorMappingSuggestionResult {
-    success: boolean;
-    /** Error message when `success` is false. `null` when `success` is true. */
-    error: string | null;
-    /**
-     * Proposed canonical-request → tool-field-name rewrite. Empty object `{}` when the model found no
-     * request-side rewrites to apply.
-     */
-    requestFieldMap: Record<string, string>;
-    /**
-     * Proposed canonical-response → JSON-path rewrite (e.g. `{ "content": "base64:$.content" }`).
-     * Empty object `{}` when the model found no response-side rewrites.
-     */
-    responseFieldPaths: Record<string, string>;
+/** One row of the mapping table. */
+interface ConnectorMappingViewRow {
+    operationKey: string;
+    label: string;
+    isRequired: boolean;
+    mappedToolName: string | null;
+    source: MappingSourceValue | null;
+    confidence: number | null;
+    /** `null` when no stored row exists yet; the view sends `""` up so the host upserts. */
+    rowVersion: string | null;
+    requiresReview?: boolean;
+    canonicalRequestFields?: ConnectorCanonicalField[] | null;
+    canonicalResponseFields?: ConnectorCanonicalField[] | null;
+    requestFieldMap?: Record<string, string> | null;
+    responseFieldPaths?: Record<string, string> | null;
+    staticRequestFields?: Record<string, string> | null;
 }
-
-interface MappingCompletenessBannerProps {
-    /**
-     * Per-operation completeness for the selected connector + module. The banner splits these into
-     * REQUIRED operations with gaps (a blocking warning) and OPTIONAL ones (an informational note);
-     * it renders nothing when neither group has gaps.
-     */
-    operations: MappingCompletenessItem[];
-    /**
-     * Opt-in AI assist. Invoked with the operation the operator chose to fix. The consumer wires this
-     * to the suggest-translation mutation and decides what to do with the result (open the editor
-     * seeded with the suggestion, apply it, and so on).
-     */
-    onSuggestWithAi: (operation: MappingCompletenessItem) => void;
-    /**
-     * Opens the manual mapping editor for an operation. The consumer owns the editor surface and
-     * routing; the banner only raises intent.
-     */
-    onOpenMappingEditor: (operation: MappingCompletenessItem) => void;
-    /**
-     * Operation key currently awaiting an AI suggestion, or `null`. Drives the per-row spinner and
-     * disabled state so a slow suggestion does not lock the whole banner.
-     */
-    suggestingOperationKey?: string | null;
-    /** Disables the AI assist affordance entirely, e.g. AI not configured for the organisation. */
-    disableSuggest?: boolean;
+/** Outcome of the most recent auto-match run, as the banner reads it. */
+interface ConnectorMappingViewBannerState {
+    aiAvailable: boolean;
+    unmatchedRequiredCount: number;
+    matchedByKeyword: number;
+    matchedByAi: number;
+    conflictReason: string | null;
 }
-/**
- * Connector-setup "mapping completeness" banner, shared by every plugin with a Tool Mappings page.
- *
- * Presentational and props-driven: the consumer fetches completeness and owns the editor, so the
- * same banner serves Repo Monitoring, Timesheets, Error Monitoring and anything added later.
- *
- * It separates two cases:
- *
- * - **Required** operations with unmapped required fields, a warning the operator must act on
- *   because the module cannot run them.
- * - **Optional** operations with unmapped required fields, a calm note. These power extra
- *   capabilities that stay off until their fields are mapped, and the connector may legitimately
- *   expose no suitable tool, so they must never read as a blocking error.
- *
- * Renders nothing when neither group has gaps.
- *
- * @remarks
- * **The wording is load-bearing, and was wrong in the copy this was promoted from.** Both groups are
- * selected on `unmappedRequiredCanonicalFields`, which is about FIELD mapping. The original optional
- * alert was titled "Optional operations not mapped" and said they "stay off until mapped", which
- * describes TOOL mapping. Auto-match maps tools and cannot close a field gap, so an operator who
- * pressed auto-match saw the count refuse to move and reported the banner as broken. It was
- * accurate; the text was not. Every string here therefore says "fields", and both alerts say plainly
- * that auto-match will not clear them.
- *
- * A row without the "No tool mapped" chip already HAS a tool and needs its fields mapped. That chip
- * is the only thing distinguishing the two states, which is why the prose points at it.
- */
-declare function MappingCompletenessBanner({ operations, onSuggestWithAi, onOpenMappingEditor, suggestingOperationKey, disableSuggest, }: MappingCompletenessBannerProps): react.JSX.Element | null;
-
-interface ConnectorMappingTranslationEditorProps {
-    open: boolean;
+interface ConnectorMappingViewProps {
+    isLoading: boolean;
+    /** Wire key of the mapping module, e.g. `repo-monitoring`. Not rendered; kept for parity. */
+    moduleKey: string;
+    /** Human-readable module label, used in the header and the empty state. */
+    moduleLabel: string;
     /**
-     * Human-readable operation label for the dialog title (e.g. "Get File").
-     *
-     * Optional because it is derived from a looked-up operation that may not be found: every caller
-     * passes `string | undefined`. The contract claimed required while reality was optional, so this
-     * states the truth rather than changing any runtime value.
+     * When `true` (the default), the view renders its own `<h1>` plus {@link breadcrumbs}. Set it to
+     * `false` on a page that already renders a `PageHeader`, or the title appears twice.
      */
-    operationLabel?: string;
+    withHeader?: boolean;
     /**
-     * Tool name the mapping currently points at — shown in the dialog header for context.
+     * Breadcrumb trail rendered under the built-in `<h1>`, and only when {@link withHeader} is true.
      *
-     * Optional and nullable because the editor opens for an operation that may not be mapped yet:
-     * every caller passes `string | null | undefined`.
+     * A node rather than an import. Breadcrumbs are plugin-specific — they need that plugin's route
+     * table and its menu context — and one of the three plugins this was promoted from had deleted
+     * the whole header block rather than lift `PageBreadcrumbs` plus its context and router shim for
+     * an import that could never execute. Injecting it means a consumer that wants the built-in
+     * header can have it without this package taking on a router dependency, and a consumer that
+     * does not simply omits both.
      */
-    toolName?: string | null;
+    breadcrumbs?: ReactNode;
     /**
-     * Canonical request fields the editor renders one input per.
+     * What to render while {@link isLoading}. Defaults to a plain skeleton block.
      *
-     * Optional and nullable: an operation may declare no canonical schema, and the editor already
-     * gates on their presence. See the coalescing note in the component body — this is not cosmetic.
-     */
-    canonicalRequestFields?: ConnectorCanonicalField[] | null;
-    /** Canonical response fields the editor renders one JSON-path input per. Same nullability. */
-    canonicalResponseFields?: ConnectorCanonicalField[] | null;
-    /** Currently-persisted request-field translation, or `null` if the operator hasn't supplied one. */
-    requestFieldMap: Record<string, string> | null;
-    /** Currently-persisted response-field translation, or `null` if the operator hasn't supplied one. */
-    responseFieldPaths: Record<string, string> | null;
-    /**
-     * Currently-persisted static request parameters (tool field name → constant literal value), or
-     * `null` if the operator hasn't supplied any. Seeds the "Static request parameters" rows.
-     */
-    staticRequestFields: Record<string, string> | null;
-    /**
-     * Called with the operator's translation dictionaries when they click Save. Empty inputs are
-     * stripped before this fires; if every input on a side was blank, that side is delivered as `null`
-     * rather than `{}` so the consumer can pass it straight through and the BE writes a NULL column
-     * (which the resolver treats as "no operator override" and falls back to the connector's
-     * vendor-default translation). A populated dictionary means "rewrite these fields explicitly"; the
-     * BE persists it verbatim and the resolver applies it on top of vendor defaults.
-     *
-     * `staticRequestFields` carries the constant tool-request parameters (e.g. `{ method: "get" }`);
-     * same null-vs-populated semantics — `null` when every static row was left blank.
-     */
-    onSave: (requestFieldMap: Record<string, string> | null, responseFieldPaths: Record<string, string> | null, staticRequestFields: Record<string, string> | null) => void;
-    onCancel: () => void;
-    /**
-     * Optional. When provided, the editor renders a Test section below the field tables and a "Test
-     * mapping" button inside it. The consumer supplies this callback so the editor never owns a
-     * network call. Invoked with the sample args and the current (unsaved) field maps — stripped to
-     * `null` when every input is blank, matching `onSave`.
+     * Injected for the same reason as {@link breadcrumbs}: each plugin has its own page skeleton, and
+     * a shared one that did not match would be a visible regression on adoption.
      */
-    onTestMapping?: (request: TestToolMappingRequest) => Promise<TestToolMappingResult>;
+    loadingFallback?: ReactNode;
+    connectors: ConnectorMappingViewConnector[];
+    selectedConnectorId: string;
+    onConnectorChange: (connectorId: string) => void;
     /**
-     * Optional. When provided, the editor renders an "Auto-configure" button in the Test section. The
-     * consumer invokes the AI suggestion endpoint with the sample inputs the Test section collects,
-     * then returns the suggested field maps so the editor can populate the request / response inputs.
-     * The operator reviews and clicks Save.
+     * What currently serves the module, or `undefined` when the operator has made no choice.
      *
-     * @param sampleArgs - Sample values the operator typed, one entry per canonical request field.
-     * @returns The suggestion result (success/error + proposed maps).
-     */
-    onSuggestTranslation?: (sampleArgs: Record<string, unknown>) => Promise<ConnectorMappingSuggestionResult>;
-}
-/**
- * Per-mapping translation editor — surfaced when the operator picks a tool whose schema doesn't
- * match the operation's canonical request/response field names. Renders two stacked tables
- * (request / response): left column shows the canonical field's name + kind chip + required
- * indicator; right column captures the operator-supplied tool field name (request side) or JSON
- * path (response side).
- *
- * <p><b>Identity semantics.</b> An empty input on a field means "identity — pass the canonical name
- * through unchanged". On Save the editor strips empty values; if every input on a side was blank,
- * that side is delivered to `onSave` as <code>null</code> (not <code>{}</code>) so the BE writes a
- * NULL column. The resolver then treats the NULL as "no operator override" and falls back to the
- * connector's vendor-default translation; a populated dictionary means "rewrite these fields
- * explicitly" and applies on top of the vendor default.</p>
- *
- * <p><b>State seeding.</b> The consumer page mounts/unmounts this dialog every time the editor opens
- * (the `open` prop is always `true` in practice — the parent gates rendering via conditional mount),
- * so local state initialises lazily from the props on each mount. This avoids the "setState in
- * useEffect" pattern the eslint react-hooks ruleset blocks, AND keeps the operator's in-flight edits
- * sovereign once the dialog is open — a concurrent refresh of the mapping row doesn't clobber what
- * they're typing.</p>
- *
- * <p><b>Promoted, not designed here.</b> This file existed FOUR times — the host's gogo-ui adapter
- * plus `self-healing`, `tech` and `timesheets` — and the copies had already drifted. Three
- * differences were adjudicated on the way in, and each is a reason the duplication was expensive:</p>
- *
- * <ol>
- *   <li><b>The Test button is gated on `onTestMapping`.</b> The enclosing block is gated on
- *       <code>(onTestMapping || onSuggestTranslation)</code>, so without the inner guard a consumer
- *       supplying only <code>onSuggestTranslation</code> rendered a "Test mapping" button whose
- *       handler returns immediately — a DEAD CONTROL. `self-healing` shipped that; `tech` and
- *       `timesheets` had fixed it. Nothing noticed, because there was no single source to notice
- *       it against.</li>
- *   <li><b>Backgrounds come from the theme (`action.hover`), never a hardcoded
- *       <code>rgba()</code>.</b> A literal <code>rgba(0,0,0,0.03)</code> is invisible in dark mode
- *       and is what `coreconnect/no-hardcoded-colors` exists to stop.</li>
- *   <li><b>No emoji in chip labels.</b> The chips already carry an icon and a semantic colour, so
- *       the emoji was a third, untranslatable, screen-reader-hostile encoding of the same state.</li>
- * </ol>
- *
- * <p>The null tolerance below came from the HOST copy, which was the most hardened of the four.
- * `coreconnect/no-local-mapping-editor` stops a fifth being written.</p>
- */
-declare function ConnectorMappingTranslationEditorView({ open, operationLabel, toolName, canonicalRequestFields: canonicalRequestFieldsProp, canonicalResponseFields: canonicalResponseFieldsProp, requestFieldMap, responseFieldPaths, staticRequestFields, onSave, onCancel, onTestMapping, onSuggestTranslation, }: ConnectorMappingTranslationEditorProps): react.JSX.Element;
-
-/**
- * Every operation with a gap, required or optional. Use it to decide whether to mount a banner at
- * all, without duplicating the predicate.
- */
-declare function selectIncompleteOperations(operations: MappingCompletenessItem[]): MappingCompletenessItem[];
-/**
- * REQUIRED operations with a gap. These genuinely block the module: the connector cannot run them.
- */
-declare function selectRequiredIncompleteOperations(operations: MappingCompletenessItem[]): MappingCompletenessItem[];
-/**
- * OPTIONAL operations with a gap. Informational only: the operation powers an extra capability that
- * stays off until its fields are mapped, and the connector may legitimately expose no suitable tool.
- *
- * @remarks
- * Treat these as a note, never a warning. A connector need not expose every operation a module can
- * use, so a correctly configured connector can sit here indefinitely — and a banner that never
- * clears is a banner operators learn to ignore, which costs you the required warnings too.
- */
-declare function selectOptionalIncompleteOperations(operations: MappingCompletenessItem[]): MappingCompletenessItem[];
-/** A module's readiness, counted over REQUIRED operations only. */
-interface MappingReadiness {
-    /** Required operations that are mapped AND have no field gaps. */
-    complete: number;
-    /** Total required operations declared by the module's catalogue. */
-    total: number;
-    /** True when every required operation is mapped and complete. */
-    isReady: boolean;
+     * `undefined` is a real state and is NOT rendered as "connector". An unconfigured module and a
+     * module pointed at a connector with nothing mapped yet look similar and need different actions,
+     * and defaulting here is how an operator ends up sent to the wrong control.
+     */
+    providerKind?: ConnectorMappingViewProviderKind;
+    /** Supplying this is what turns the provider picker on. See the block comment above. */
+    onProviderKindChange?: (kind: ConnectorMappingViewProviderKind) => void;
+    /** The installed applications on offer. Only read while {@link providerKind} is `"plugin"`. */
+    pluginProviders?: ConnectorMappingViewPluginProvider[];
+    /** The chosen application, or `""`. */
+    selectedPluginExtensionId?: string;
+    onPluginProviderChange?: (extensionId: string) => void;
+    mappings: ConnectorMappingViewRow[];
+    availableTools: ConnectorMappingViewTool[];
+    /**
+     * Called with `toolName === ""` when the operator clears a row's picker. The consumer routes that
+     * to the host's delete tool — see `useConnectorMappingMutations`, which does it — because the
+     * set validator rejects an empty tool name.
+     */
+    onUpdateMapping: (operationKey: string, toolName: string, rowVersion: string) => void;
+    onAutoMatch: () => void;
+    isUpdating: boolean;
+    isAutoMatching: boolean;
+    /** `null` when no outcome banner should render (nothing to say, or the operator dismissed it). */
+    bannerState: ConnectorMappingViewBannerState | null;
+    onDismissBanner: () => void;
+    /**
+     * Href of the host's AI-providers settings page. The view owns no routing; the consumer passes
+     * the href so the link stays correct across templates and route changes.
+     */
+    aiProvidersHref: string;
+    /** Href of the selected connector's settings page. Same routing-ownership rule. */
+    connectorSettingsHref: string;
+    /**
+     * Raised by the per-row "Configure field translation" button. Rows with no mapped tool, or with
+     * no declared canonical schema, never raise it — the view hides the button for those, because
+     * there is nothing operator-meaningful to translate.
+     */
+    onEditTranslation: (operationKey: string, current: ConnectorMappingViewTranslationState) => void;
 }
 /**
- * Readiness over REQUIRED operations only, for a progress indicator or a "ready" badge.
+ * The Tool Mappings table: a connector picker, one row per canonical operation with a tool picker
+ * and a source chip, the auto-match control, and the per-row translation affordance.
  *
- * @remarks
- * Optional operations are excluded on purpose. Counting them would leave a properly configured
- * connector permanently short of 100%, for operations the operator was never expected to map. This
- * rule came from `ethisyscore-plugin-timesheets`, which had it right while another plugin was
- * reporting optional field gaps in a standing banner.
- */
-declare function selectMappingReadiness(operations: MappingCompletenessItem[]): MappingReadiness;
-
-/**
- * React-query keys for a connector's tool mappings and the completeness read derived from them.
+ * ## Promoted, not designed here
  *
- * @remarks
- * The completeness key is built as a CHILD of the mappings key, and that nesting is the whole point
- * of shipping these from the SDK rather than letting each plugin declare its own.
+ * This file existed three times — `sales`, `tech` and `timesheets` — and two of the three were
+ * BYTE-IDENTICAL at 329 lines. The third was the same file with the header block deleted and one
+ * behaviour difference that was a live defect (see {@link renderBanner}). Nothing about it was
+ * plugin-specific except two imports, which are now props: the breadcrumbs and the loading
+ * skeleton.
  *
- * Completeness is derived state: it is the mappings joined against the live tool schemas. Every write
- * that changes a mapping can change it. When the two keys are siblings, a mutation has to remember to
- * invalidate both, and one plugin duly invalidated only the mappings key — so its "operations aren't
- * fully mapped" banner went stale after every save, clear and auto-match, and stayed stale until the
- * operator navigated away. Nesting means a single `invalidateQueries({ queryKey: mappings })` takes
- * the completeness read with it, and there is nothing left to forget.
+ * ## What it owns and what it does not
  *
- * @example
- * ```ts
- * const mappings = connectorMappingsQueryKey(connectorId, moduleKey);
+ * Presentational and fully props-driven. It fetches nothing, writes nothing and routes nowhere —
+ * `aiProvidersHref` and `connectorSettingsHref` arrive as strings, and clearing a row's picker
+ * emits `onUpdateMapping(key, "", rowVersion)` for the consumer to route. Pair it with
+ * `useConnectorToolMappings` from `@ethisyscore/plugin-ui/connector-mappings`, whose `view` bundle
+ * spreads straight onto these props.
  *
- * useQuery({ queryKey: mappings, queryFn: ... });
- * useQuery({ queryKey: connectorMappingCompletenessQueryKey(connectorId, moduleKey), queryFn: ... });
- *
- * // One call. Covers both, and any future query keyed beneath the mappings key.
- * queryClient.invalidateQueries({ queryKey: mappings });
- * ```
- */
-/**
- * Key for the mappings list of one connector + module.
- *
- * `connectorId` is accepted as possibly-undefined because the page renders before a connector is
- * chosen; pair it with `enabled: !!connectorId` rather than branching on the key.
- */
-declare function connectorMappingsQueryKey(connectorId: string | undefined, moduleKey: string): readonly ["connector-mappings", string | undefined, string];
-/**
- * Key for the completeness read, nested UNDER {@link connectorMappingsQueryKey} so invalidating the
- * mappings prefix always covers it. Do not flatten this into a sibling key.
+ * The translation affordance appears only when a row HAS a mapped tool AND declares both canonical
+ * schemas. A row with no schema has nothing to translate, and offering the button anyway opens an
+ * editor with no fields in it.
  */
-declare function connectorMappingCompletenessQueryKey(connectorId: string | undefined, moduleKey: string): readonly ["connector-mappings", string | undefined, string, "completeness"];
+declare function ConnectorMappingView({ isLoading, moduleLabel, breadcrumbs, loadingFallback, connectors, selectedConnectorId, onConnectorChange, providerKind, onProviderKindChange, pluginProviders, selectedPluginExtensionId, onPluginProviderChange, mappings, availableTools, onUpdateMapping, onAutoMatch, isUpdating, isAutoMatching, bannerState, onDismissBanner, onEditTranslation, withHeader, }: ConnectorMappingViewProps): react.JSX.Element;
 
-export { type ConnectorCanonicalField, type ConnectorCanonicalFieldKind, type ConnectorMappingSuggestionResult, type ConnectorMappingTranslationEditorProps, ConnectorMappingTranslationEditorView, MappingCompletenessBanner, type MappingCompletenessBannerProps, type MappingCompletenessItem, type MappingCompletenessResult, type MappingReadiness, type TestToolMappingExtractedField, type TestToolMappingRequest, type TestToolMappingResult, connectorMappingCompletenessQueryKey, connectorMappingsQueryKey, selectIncompleteOperations, selectMappingReadiness, selectOptionalIncompleteOperations, selectRequiredIncompleteOperations };
+export { ConnectorCanonicalField, ConnectorMappingView, type ConnectorMappingViewBannerState, type ConnectorMappingViewConnector, type ConnectorMappingViewPluginProvider, type ConnectorMappingViewProps, type ConnectorMappingViewProviderKind, type ConnectorMappingViewRow, type ConnectorMappingViewTool, type ConnectorMappingViewTranslationState };