@wildo-ai/saas-frontend-lib 1.1.4 → 1.1.6

package/dist/esm/core/external-providers/ConsentBasedProviderSdks.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The application's SECOND activation phase: providers that rest on a consent purpose (#1704).
+ *
+ * ## Why startup cannot do this
+ *
+ * `startApplication` activates provider SDKs before any person is known, so it passes no grant and starts
+ * only the providers that rest on no purpose (error monitoring, pickers). A provider that rests on
+ * `ConsentPurpose.ANALYTICS` could therefore never start on the application tier — the consent module had
+ * always said such a provider "must be activated by a consumer that holds the person's granted purposes",
+ * and no such consumer existed. This is it.
+ *
+ * ## Where the grant comes from, and what revokes it
+ *
+ * The signed-in person's `privacy.consentedPurposes`, published on `USER_PREFERENCES_CHANGED` — the same
+ * stream `AnalyticsContext` has always gated on, with the same rule: `privacy: null` (sign-out, or an
+ * identity with no preferences) REVOKES — sign-out publishes it, so a browser a person signed out of never
+ * keeps their consent running for whoever uses it next — and an empty set is a real withdrawal. Until
+ * preferences arrive nothing is granted, which is why pre-authentication pages start none.
+ *
+ * ## Start and stop
+ *
+ * The providers are (re)started when the granted subset of the purposes THEY rest on changes, so granting a
+ * purpose none of them uses restarts nothing; granting or withdrawing one they use restarts all of them.
+ * Every activation goes through `activateFrontendProviderSdks` — which refuses a consent-based provider that
+ * could not be stopped — and every withdrawal, sign-out or unmount calls `deactivateAll`, which is the only
+ * thing that stops a vendor already running in the page.
+ *
+ * Starts and stops are SERIALISED through `createFrontendProviderSdkActivationLane`, the one lane every consent-based
+ * consumer holds (the website's is the other): a new start waits until the previous one has fully stopped. A vendor SDK is
+ * usually a page-global singleton, so a stop that finished after the next start (a person who grants, withdraws
+ * and grants again while the vendor bundle is still downloading) would switch off the client that had just been
+ * published as running.
+ *
+ * ## No second audit trail
+ *
+ * The consent DECISION is the audited preference write (`consentedPurposes` on the person's preferences,
+ * read by the resource-operation audit emission). Starting or stopping an SDK here is a consequence of that
+ * decision, not a decision, so it records nothing of its own: a second trail would only be able to
+ * disagree with the first.
+ */
+import React from 'react';
+import { type ProviderFrontendSdkActivation } from '@wildo-ai/external-connectors-public/app';
+/** One running consent-based provider: its ref, the capabilities it serves, and its activation. */
+export interface ConsentBasedProviderActivation {
+    readonly providerRef: string;
+    readonly providerCapabilities: ReadonlyArray<string>;
+    readonly activation: ProviderFrontendSdkActivation;
+}
+/** @wildo_source:part:start saas.frontend.consent-based-provider-activation facet:layer:frontend facet:audience:app-developer */
+/**
+ * The consent-based providers currently RUNNING on the application, in registry order (#1704).
+ *
+ * Empty until the signed-in person grants the purposes a provider rests on, and emptied again on withdrawal or
+ * sign-out — immediately, before the providers' `deactivate` has finished. A consumer that dispatches to a
+ * provider (`AnalyticsContext` does, for `FRONTEND_PRODUCT_ANALYTICS`) reads this and never holds a handle past it.
+ */
+export declare function useConsentBasedProviderActivations(): ReadonlyArray<ConsentBasedProviderActivation>;
+/** @wildo_source:part:end saas.frontend.consent-based-provider-activation */
+export declare const ConsentBasedProviderActivationsContext: React.Context<readonly ConsentBasedProviderActivation[]>;
+export declare const ConsentBasedProviderSdksProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+//# sourceMappingURL=ConsentBasedProviderSdks.d.ts.map

package/dist/esm/core/external-providers/ConsentBasedProviderSdks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsentBasedProviderSdks.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/ConsentBasedProviderSdks.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAA0E,MAAM,OAAO,CAAC;AAC/F,OAAO,EAIL,KAAK,6BAA6B,EACnC,MAAM,0CAA0C,CAAC;AAOlD,mGAAmG;AACnG,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAC;CACpD;AAED,iIAAiI;AACjI;;;;;;GAMG;AACH,wBAAgB,kCAAkC,IAAI,aAAa,CAAC,8BAA8B,CAAC,CAElG;AACD,6EAA6E;AAE7E,eAAO,MAAM,sCAAsC,0DAAmE,CAAC;AAQvH,eAAO,MAAM,gCAAgC,EAAE,KAAK,CAAC,EAAE,CAAC;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,CA+EpF,CAAC"}

package/dist/esm/core/external-providers/ConsentBasedProviderSdks.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The application's SECOND activation phase: providers that rest on a consent purpose (#1704).
+ *
+ * ## Why startup cannot do this
+ *
+ * `startApplication` activates provider SDKs before any person is known, so it passes no grant and starts
+ * only the providers that rest on no purpose (error monitoring, pickers). A provider that rests on
+ * `ConsentPurpose.ANALYTICS` could therefore never start on the application tier — the consent module had
+ * always said such a provider "must be activated by a consumer that holds the person's granted purposes",
+ * and no such consumer existed. This is it.
+ *
+ * ## Where the grant comes from, and what revokes it
+ *
+ * The signed-in person's `privacy.consentedPurposes`, published on `USER_PREFERENCES_CHANGED` — the same
+ * stream `AnalyticsContext` has always gated on, with the same rule: `privacy: null` (sign-out, or an
+ * identity with no preferences) REVOKES — sign-out publishes it, so a browser a person signed out of never
+ * keeps their consent running for whoever uses it next — and an empty set is a real withdrawal. Until
+ * preferences arrive nothing is granted, which is why pre-authentication pages start none.
+ *
+ * ## Start and stop
+ *
+ * The providers are (re)started when the granted subset of the purposes THEY rest on changes, so granting a
+ * purpose none of them uses restarts nothing; granting or withdrawing one they use restarts all of them.
+ * Every activation goes through `activateFrontendProviderSdks` — which refuses a consent-based provider that
+ * could not be stopped — and every withdrawal, sign-out or unmount calls `deactivateAll`, which is the only
+ * thing that stops a vendor already running in the page.
+ *
+ * Starts and stops are SERIALISED through `createFrontendProviderSdkActivationLane`, the one lane every consent-based
+ * consumer holds (the website's is the other): a new start waits until the previous one has fully stopped. A vendor SDK is
+ * usually a page-global singleton, so a stop that finished after the next start (a person who grants, withdraws
+ * and grants again while the vendor bundle is still downloading) would switch off the client that had just been
+ * published as running.
+ *
+ * ## No second audit trail
+ *
+ * The consent DECISION is the audited preference write (`consentedPurposes` on the person's preferences,
+ * read by the resource-operation audit emission). Starting or stopping an SDK here is a consequence of that
+ * decision, not a decision, so it records nothing of its own: a second trail would only be able to
+ * disagree with the first.
+ */
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { activateFrontendProviderSdks, consentPurposesRequiredByProvider, createFrontendProviderSdkActivationLane, } from '@wildo-ai/external-connectors-public/app';
+import { AppFrontendType, BUILTIN_PROVIDER_CAPABILITY, normalizeConsentPurposes } from '@wildo-ai/saas-models/public-runtime';
+import { ApplicationContext } from '../../core/runtime/ApplicationContext.shared.js';
+import { useEventBus } from '../../core/events/useEventBus.js';
+import { FrontendEvents } from '../../core/events/events.frontend.schemas.js';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+/** @wildo_source:part:start saas.frontend.consent-based-provider-activation facet:layer:frontend facet:audience:app-developer */
+/**
+ * The consent-based providers currently RUNNING on the application, in registry order (#1704).
+ *
+ * Empty until the signed-in person grants the purposes a provider rests on, and emptied again on withdrawal or
+ * sign-out — immediately, before the providers' `deactivate` has finished. A consumer that dispatches to a
+ * provider (`AnalyticsContext` does, for `FRONTEND_PRODUCT_ANALYTICS`) reads this and never holds a handle past it.
+ */
+export function useConsentBasedProviderActivations() {
+    return useContext(ConsentBasedProviderActivationsContext);
+}
+/** @wildo_source:part:end saas.frontend.consent-based-provider-activation */
+export const ConsentBasedProviderActivationsContext = createContext([]);
+const logger = LoggerFrontendService.getLogger();
+function grantedKey(purposes) {
+    return [...purposes].sort().join(',');
+}
+export const ConsentBasedProviderSdksProvider = ({ children }) => {
+    const appContext = useContext(ApplicationContext);
+    const registry = appContext?.frontendProviderRegistry;
+    const { on } = useEventBus();
+    // `null` = nothing said yet; an empty array is a recorded withdrawal. Both start nothing.
+    const [grantedPurposes, setGrantedPurposes] = useState(null);
+    const [activations, setActivations] = useState([]);
+    // One lane for this consumer's lifetime: a start waits for the previous stop.
+    const lane = useRef(createFrontendProviderSdkActivationLane());
+    useEffect(() => on(FrontendEvents.USER_PREFERENCES_CHANGED, (payload) => {
+        if (payload.privacy === null) {
+            setGrantedPurposes([]);
+            return;
+        }
+        const purposes = payload.privacy?.consentedPurposes;
+        if (purposes !== undefined)
+            setGrantedPurposes(normalizeConsentPurposes(purposes));
+    }), [on]);
+    // `analytics.enabled` is the application's master switch for product analytics: with it off, a vendor analytics
+    // client is not even loaded on a grant — loading it would already send PostHog a flags request and write its ids,
+    // for events that would then never be dispatched to it.
+    const analyticsEnabled = appContext?.appConfig?.analytics?.enabled === true;
+    const consentBasedModules = useMemo(() => (registry?.listAll() ?? []).filter((module) => consentPurposesRequiredByProvider(module).length > 0
+        && (analyticsEnabled || !module.providerCapabilities.includes(BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS))), [registry, analyticsEnabled]);
+    // Only the purposes these providers rest on, so an unrelated grant does not restart a running client.
+    const relevantGranted = useMemo(() => {
+        const granted = grantedPurposes ?? [];
+        const required = new Set(consentBasedModules.flatMap((module) => consentPurposesRequiredByProvider(module)));
+        return granted.filter((purpose) => required.has(purpose));
+    }, [consentBasedModules, grantedPurposes]);
+    const key = grantedKey(relevantGranted);
+    useEffect(() => {
+        if (consentBasedModules.length === 0 || relevantGranted.length === 0) {
+            setActivations([]);
+            return;
+        }
+        // Serialised through the lane — see "Start and stop" above.
+        const stop = lane.current.start(() => activateFrontendProviderSdks({
+            surface: AppFrontendType.SAAS_APP,
+            modules: consentBasedModules,
+            grantedConsentPurposes: relevantGranted,
+            onDiagnostic: (diagnostic) => {
+                logger.warn('Consent-based frontend provider activation diagnostic', {
+                    kind: diagnostic.kind,
+                    providerRef: diagnostic.providerRef,
+                    message: diagnostic.message,
+                });
+            },
+        }), (result) => {
+            setActivations(consentBasedModules.flatMap((module) => {
+                const activation = result.activations.get(module.metadata.ref);
+                return activation === undefined
+                    ? []
+                    : [{ providerRef: module.metadata.ref, providerCapabilities: [...module.providerCapabilities], activation }];
+            }));
+        });
+        return () => {
+            // Withdrawn from consumers at once, so nothing dispatches to a client that is being stopped.
+            setActivations([]);
+            stop();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed by the granted SET, see grantedKey.
+    }, [consentBasedModules, key]);
+    return (_jsx(ConsentBasedProviderActivationsContext.Provider, { value: activations, children: children }));
+};
+//# sourceMappingURL=ConsentBasedProviderSdks.js.map

package/dist/esm/core/external-providers/ConsentBasedProviderSdks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsentBasedProviderSdks.js","sourceRoot":"","sources":["../../../../../src/core/external-providers/ConsentBasedProviderSdks.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * The application's SECOND activation phase: providers that rest on a consent purpose (#1704).\n *\n * ## Why startup cannot do this\n *\n * `startApplication` activates provider SDKs before any person is known, so it passes no grant and starts\n * only the providers that rest on no purpose (error monitoring, pickers). A provider that rests on\n * `ConsentPurpose.ANALYTICS` could therefore never start on the application tier — the consent module had\n * always said such a provider \"must be activated by a consumer that holds the person's granted purposes\",\n * and no such consumer existed. This is it.\n *\n * ## Where the grant comes from, and what revokes it\n *\n * The signed-in person's `privacy.consentedPurposes`, published on `USER_PREFERENCES_CHANGED` — the same\n * stream `AnalyticsContext` has always gated on, with the same rule: `privacy: null` (sign-out, or an\n * identity with no preferences) REVOKES — sign-out publishes it, so a browser a person signed out of never\n * keeps their consent running for whoever uses it next — and an empty set is a real withdrawal. Until\n * preferences arrive nothing is granted, which is why pre-authentication pages start none.\n *\n * ## Start and stop\n *\n * The providers are (re)started when the granted subset of the purposes THEY rest on changes, so granting a\n * purpose none of them uses restarts nothing; granting or withdrawing one they use restarts all of them.\n * Every activation goes through `activateFrontendProviderSdks` — which refuses a consent-based provider that\n * could not be stopped — and every withdrawal, sign-out or unmount calls `deactivateAll`, which is the only\n * thing that stops a vendor already running in the page.\n *\n * Starts and stops are SERIALISED through `createFrontendProviderSdkActivationLane`, the one lane every consent-based\n * consumer holds (the website's is the other): a new start waits until the previous one has fully stopped. A vendor SDK is\n * usually a page-global singleton, so a stop that finished after the next start (a person who grants, withdraws\n * and grants again while the vendor bundle is still downloading) would switch off the client that had just been\n * published as running.\n *\n * ## No second audit trail\n *\n * The consent DECISION is the audited preference write (`consentedPurposes` on the person's preferences,\n * read by the resource-operation audit emission). Starting or stopping an SDK here is a consequence of that\n * decision, not a decision, so it records nothing of its own: a second trail would only be able to\n * disagree with the first.\n */\n\nimport React, { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';\nimport {\n  activateFrontendProviderSdks,\n  consentPurposesRequiredByProvider,\n  createFrontendProviderSdkActivationLane,\n  type ProviderFrontendSdkActivation,\n} from '@wildo-ai/external-connectors-public/app';\nimport { AppFrontendType, BUILTIN_PROVIDER_CAPABILITY, normalizeConsentPurposes, type ConsentPurpose } from '@wildo-ai/saas-models/public-runtime';\nimport { ApplicationContext } from '~wildo-frontend-lib/core/runtime/ApplicationContext.shared';\nimport { useEventBus } from '~wildo-frontend-lib/core/events/useEventBus';\nimport { FrontendEvents } from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\n\n/** One running consent-based provider: its ref, the capabilities it serves, and its activation. */\nexport interface ConsentBasedProviderActivation {\n  readonly providerRef: string;\n  readonly providerCapabilities: ReadonlyArray<string>;\n  readonly activation: ProviderFrontendSdkActivation;\n}\n\n/** @wildo_source:part:start saas.frontend.consent-based-provider-activation facet:layer:frontend facet:audience:app-developer */\n/**\n * The consent-based providers currently RUNNING on the application, in registry order (#1704).\n *\n * Empty until the signed-in person grants the purposes a provider rests on, and emptied again on withdrawal or\n * sign-out — immediately, before the providers' `deactivate` has finished. A consumer that dispatches to a\n * provider (`AnalyticsContext` does, for `FRONTEND_PRODUCT_ANALYTICS`) reads this and never holds a handle past it.\n */\nexport function useConsentBasedProviderActivations(): ReadonlyArray<ConsentBasedProviderActivation> {\n  return useContext(ConsentBasedProviderActivationsContext);\n}\n/** @wildo_source:part:end saas.frontend.consent-based-provider-activation */\n\nexport const ConsentBasedProviderActivationsContext = createContext<ReadonlyArray<ConsentBasedProviderActivation>>([]);\n\nconst logger: LoggerFrontendService = LoggerFrontendService.getLogger();\n\nfunction grantedKey(purposes: readonly ConsentPurpose[]): string {\n  return [...purposes].sort().join(',');\n}\n\nexport const ConsentBasedProviderSdksProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {\n  const appContext = useContext(ApplicationContext);\n  const registry = appContext?.frontendProviderRegistry;\n  const { on } = useEventBus();\n\n  // `null` = nothing said yet; an empty array is a recorded withdrawal. Both start nothing.\n  const [grantedPurposes, setGrantedPurposes] = useState<readonly ConsentPurpose[] | null>(null);\n  const [activations, setActivations] = useState<ReadonlyArray<ConsentBasedProviderActivation>>([]);\n  // One lane for this consumer's lifetime: a start waits for the previous stop.\n  const lane = useRef(createFrontendProviderSdkActivationLane());\n\n  useEffect(() => on(FrontendEvents.USER_PREFERENCES_CHANGED, (payload) => {\n    if (payload.privacy === null) {\n      setGrantedPurposes([]);\n      return;\n    }\n    const purposes = payload.privacy?.consentedPurposes;\n    if (purposes !== undefined) setGrantedPurposes(normalizeConsentPurposes(purposes));\n  }), [on]);\n\n  // `analytics.enabled` is the application's master switch for product analytics: with it off, a vendor analytics\n  // client is not even loaded on a grant — loading it would already send PostHog a flags request and write its ids,\n  // for events that would then never be dispatched to it.\n  const analyticsEnabled = appContext?.appConfig?.analytics?.enabled === true;\n  const consentBasedModules = useMemo(\n    () => (registry?.listAll() ?? []).filter((module) => consentPurposesRequiredByProvider(module).length > 0\n      && (analyticsEnabled || !module.providerCapabilities.includes(BUILTIN_PROVIDER_CAPABILITY.FRONTEND_PRODUCT_ANALYTICS))),\n    [registry, analyticsEnabled],\n  );\n  // Only the purposes these providers rest on, so an unrelated grant does not restart a running client.\n  const relevantGranted = useMemo(() => {\n    const granted = grantedPurposes ?? [];\n    const required = new Set(consentBasedModules.flatMap((module) => consentPurposesRequiredByProvider(module)));\n    return granted.filter((purpose) => required.has(purpose));\n  }, [consentBasedModules, grantedPurposes]);\n  const key = grantedKey(relevantGranted);\n\n  useEffect(() => {\n    if (consentBasedModules.length === 0 || relevantGranted.length === 0) {\n      setActivations([]);\n      return;\n    }\n    // Serialised through the lane — see \"Start and stop\" above.\n    const stop = lane.current.start(\n      () => activateFrontendProviderSdks({\n        surface: AppFrontendType.SAAS_APP,\n        modules: consentBasedModules,\n        grantedConsentPurposes: relevantGranted,\n        onDiagnostic: (diagnostic) => {\n          logger.warn('Consent-based frontend provider activation diagnostic', {\n            kind: diagnostic.kind,\n            providerRef: diagnostic.providerRef,\n            message: diagnostic.message,\n          });\n        },\n      }),\n      (result) => {\n        setActivations(consentBasedModules.flatMap((module) => {\n          const activation = result.activations.get(module.metadata.ref);\n          return activation === undefined\n            ? []\n            : [{ providerRef: module.metadata.ref, providerCapabilities: [...module.providerCapabilities], activation }];\n        }));\n      },\n    );\n\n    return () => {\n      // Withdrawn from consumers at once, so nothing dispatches to a client that is being stopped.\n      setActivations([]);\n      stop();\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed by the granted SET, see grantedKey.\n  }, [consentBasedModules, key]);\n\n  return (\n    <ConsentBasedProviderActivationsContext.Provider value={activations}>\n      {children}\n    </ConsentBasedProviderActivationsContext.Provider>\n  );\n};\n"]}

package/dist/esm/core/external-providers/ProviderAddressLookupCombobox.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The framework's address-lookup COMPONENT, for any vendor that supplies a `ProviderAddressLookupAdapter` (#561).
+ *
+ * A vendor's lookup is four pure functions (build the suggest input, read the suggestions, build the retrieve
+ * input, read the address). Everything else a lookup must get right is the same for every vendor and is written
+ * once here:
+ *
+ * - **The keyboard and screen-reader pattern is the engine's `Combobox`**, not new markup: a trigger with
+ *   `role="combobox"` and `aria-expanded`, and inside it the command list whose text box is a WAI-ARIA combobox
+ *   over a `listbox` — arrow keys move the active option, which is announced through `aria-activedescendant`,
+ *   Enter chooses it and Escape closes the list. Server-side results, so the list is not filtered again locally.
+ * - **Suggestions start at {@link PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH} characters and are debounced**
+ *   by {@link PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS} (#561 D5): fewer characters match half a country, and a
+ *   request per keystroke spends the person's per-operation allowance at the door.
+ * - **A slower, older answer never replaces a newer one.** Each search carries a sequence number and only the
+ *   latest may write the list — the ordinary way a typeahead shows results for text the person already changed.
+ * - **Nothing vendor-owned is kept.** The suggestion's id lives only until the retrieval; the address that comes
+ *   back is handed to `onSelect` and the field takes it as typed text.
+ * - **Every failure is reported, never thrown** (`onError`), so the host can say the lookup is unavailable while
+ *   the address parts below keep working by hand.
+ *
+ * The session token and the choice of backend operations are NOT here: the host binds `suggest` / `retrieve` to the
+ * operations the provider declared and fills the token itself (#561 D4). The vendor attribution arrives from the host
+ * as data and is shown here, inside the suggestion popup beside the results, by {@link ProviderAddressLookupAttribution}.
+ */
+import React from 'react';
+import type { ProviderAddressLookupAdapter, ProviderAddressLookupAttributionText, ProviderAddressLookupProps } from '@wildo-ai/saas-models';
+/** Characters typed before a search runs (#561 D5). */
+export declare const PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH = 3;
+/** Quiet time after the last keystroke before a search runs, in milliseconds. */
+export declare const PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS = 300;
+export interface ProviderAddressLookupComboboxProps extends ProviderAddressLookupProps {
+    /** The vendor's four functions. */
+    readonly adapter: ProviderAddressLookupAdapter;
+}
+/**
+ * The vendor answered the retrieval, and the place it describes has no postal address the field can hold (no
+ * street line, no town or no country). Reported through `onError` like any failure, as its own class so the host
+ * can say "this place cannot be used" rather than "the lookup is unavailable" — the lookup worked.
+ */
+export declare class ProviderAddressLookupPlaceWithoutAddressError extends Error {
+    constructor();
+}
+/**
+ * A vendor's required attribution, rendered to the vendor's text rules (#561 D4).
+ *
+ * Google's rules for its "Google Maps" text, when its logo is not used: never translated (`translate="no"`), never
+ * wrapped onto two lines, weight 400, 12–16 px, normal letter spacing, and white, #1F1F1F or #5E5E5E with at least
+ * 4.5:1 contrast against its background. The mark is therefore set in #1F1F1F on its own white ground, which keeps
+ * that contrast on every theme the application ships — the one place a vendor's colours override the design
+ * system's tokens, as a logo would. The sentence around it, for assistive technology, comes from the application's
+ * labels; the mark itself is hidden from them so it is not read twice.
+ * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — "Font color: White, black
+ * (#1F1F1F), or gray (#5E5E5E)", "Don't wrap Google Maps onto multiple lines", "Prevent browsers from translating
+ * Google Maps by using the HTML attribute translate='no'". Fetched 2026-09-29.
+ */
+export declare function ProviderAddressLookupAttribution({ attribution }: {
+    readonly attribution: ProviderAddressLookupAttributionText;
+}): React.ReactElement;
+export declare function ProviderAddressLookupCombobox(props: ProviderAddressLookupComboboxProps): React.ReactElement;
+//# sourceMappingURL=ProviderAddressLookupCombobox.d.ts.map

package/dist/esm/core/external-providers/ProviderAddressLookupCombobox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderAddressLookupCombobox.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/ProviderAddressLookupCombobox.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAGjF,OAAO,KAAK,EACV,4BAA4B,EAC5B,oCAAoC,EACpC,0BAA0B,EAE3B,MAAM,uBAAuB,CAAC;AAM/B,uDAAuD;AACvD,eAAO,MAAM,4CAA4C,IAAI,CAAC;AAE9D,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAKvD,MAAM,WAAW,kCAAmC,SAAQ,0BAA0B;IACpF,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC;CAChD;AAED;;;;GAIG;AACH,qBAAa,6CAA8C,SAAQ,KAAK;;CAKvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAAC,EAAE,WAAW,EAAE,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,oCAAoC,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,CAcpJ;AAMD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,kCAAkC,GAAG,KAAK,CAAC,YAAY,CA8I3G"}

package/dist/esm/core/external-providers/ProviderAddressLookupCombobox.js

@@ -0,0 +1,178 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The framework's address-lookup COMPONENT, for any vendor that supplies a `ProviderAddressLookupAdapter` (#561).
+ *
+ * A vendor's lookup is four pure functions (build the suggest input, read the suggestions, build the retrieve
+ * input, read the address). Everything else a lookup must get right is the same for every vendor and is written
+ * once here:
+ *
+ * - **The keyboard and screen-reader pattern is the engine's `Combobox`**, not new markup: a trigger with
+ *   `role="combobox"` and `aria-expanded`, and inside it the command list whose text box is a WAI-ARIA combobox
+ *   over a `listbox` — arrow keys move the active option, which is announced through `aria-activedescendant`,
+ *   Enter chooses it and Escape closes the list. Server-side results, so the list is not filtered again locally.
+ * - **Suggestions start at {@link PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH} characters and are debounced**
+ *   by {@link PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS} (#561 D5): fewer characters match half a country, and a
+ *   request per keystroke spends the person's per-operation allowance at the door.
+ * - **A slower, older answer never replaces a newer one.** Each search carries a sequence number and only the
+ *   latest may write the list — the ordinary way a typeahead shows results for text the person already changed.
+ * - **Nothing vendor-owned is kept.** The suggestion's id lives only until the retrieval; the address that comes
+ *   back is handed to `onSelect` and the field takes it as typed text.
+ * - **Every failure is reported, never thrown** (`onError`), so the host can say the lookup is unavailable while
+ *   the address parts below keep working by hand.
+ *
+ * The session token and the choice of backend operations are NOT here: the host binds `suggest` / `retrieve` to the
+ * operations the provider declared and fills the token itself (#561 D4). The vendor attribution arrives from the host
+ * as data and is shown here, inside the suggestion popup beside the results, by {@link ProviderAddressLookupAttribution}.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { z } from 'zod';
+import { FormFieldAddressLookupLabel, FrontendComponentType } from '@wildo-ai/presets-components-models';
+import { useI18n } from '../../core/i18n/useI18n.js';
+import { Combobox } from '../../components/form/combobox.js';
+/** Characters typed before a search runs (#561 D5). */
+export const PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH = 3;
+/** Quiet time after the last keystroke before a search runs, in milliseconds. */
+export const PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS = 300;
+/** The search box holds text, never a stored value: the combobox is used for its interaction pattern only. */
+const LOOKUP_QUERY_SCHEMA = z.string();
+/**
+ * The vendor answered the retrieval, and the place it describes has no postal address the field can hold (no
+ * street line, no town or no country). Reported through `onError` like any failure, as its own class so the host
+ * can say "this place cannot be used" rather than "the lookup is unavailable" — the lookup worked.
+ */
+export class ProviderAddressLookupPlaceWithoutAddressError extends Error {
+    constructor() {
+        super('The chosen place has no postal address the field can hold.');
+        this.name = 'ProviderAddressLookupPlaceWithoutAddressError';
+    }
+}
+/**
+ * A vendor's required attribution, rendered to the vendor's text rules (#561 D4).
+ *
+ * Google's rules for its "Google Maps" text, when its logo is not used: never translated (`translate="no"`), never
+ * wrapped onto two lines, weight 400, 12–16 px, normal letter spacing, and white, #1F1F1F or #5E5E5E with at least
+ * 4.5:1 contrast against its background. The mark is therefore set in #1F1F1F on its own white ground, which keeps
+ * that contrast on every theme the application ships — the one place a vendor's colours override the design
+ * system's tokens, as a logo would. The sentence around it, for assistive technology, comes from the application's
+ * labels; the mark itself is hidden from them so it is not read twice.
+ * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — "Font color: White, black
+ * (#1F1F1F), or gray (#5E5E5E)", "Don't wrap Google Maps onto multiple lines", "Prevent browsers from translating
+ * Google Maps by using the HTML attribute translate='no'". Fetched 2026-09-29.
+ */
+export function ProviderAddressLookupAttribution({ attribution }) {
+    return (_jsxs("span", { "data-address-lookup-attribution": "", className: "inline-flex", children: [_jsx("span", { className: "sr-only", children: attribution.accessibleLabel }), _jsx("span", { "aria-hidden": "true", translate: "no", className: "whitespace-nowrap rounded-sm px-1 text-xs font-normal tracking-normal", style: { color: '#1F1F1F', backgroundColor: '#FFFFFF' }, children: attribution.mark })] }));
+}
+function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+export function ProviderAddressLookupCombobox(props) {
+    const { adapter, suggest, retrieve, onSelect, onCancel, onError, countriesAllowed, defaultCountry, languageCode, disabled, name, attribution } = props;
+    const { tComponent } = useI18n({ component: [FrontendComponentType.LOW_LEVEL_FORM_FIELD_ADDRESS] });
+    const label = (key, params) => tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_ADDRESS, key, params);
+    const [query, setQuery] = useState('');
+    const [suggestions, setSuggestions] = useState([]);
+    const [searching, setSearching] = useState(false);
+    /** Incremented by every search and every reset; an answer is written only while it is still the latest. */
+    const sequenceRef = useRef(0);
+    /** Set while a chosen suggestion is being retrieved, so the list closing on a choice is not read as a cancel. */
+    const choosingRef = useRef(false);
+    const trimmed = query.trim();
+    const searchable = trimmed.length >= PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH;
+    useEffect(() => {
+        const sequence = ++sequenceRef.current;
+        if (!searchable || disabled) {
+            setSuggestions([]);
+            setSearching(false);
+            return undefined;
+        }
+        setSearching(true);
+        const timer = setTimeout(() => {
+            let input;
+            try {
+                input = adapter.buildSuggestInput({ query: trimmed, countriesAllowed, defaultCountry, languageCode });
+            }
+            catch (error) {
+                setSearching(false);
+                onError(asError(error));
+                return;
+            }
+            suggest(input)
+                .then((output) => {
+                if (sequence !== sequenceRef.current)
+                    return;
+                setSuggestions(adapter.readSuggestions(output));
+            })
+                .catch((error) => {
+                if (sequence !== sequenceRef.current)
+                    return;
+                setSuggestions([]);
+                onError(asError(error));
+            })
+                .finally(() => {
+                if (sequence === sequenceRef.current)
+                    setSearching(false);
+            });
+        }, PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS);
+        return () => clearTimeout(timer);
+        // `countriesAllowed` is an array the field re-creates per render; its content is what matters.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [trimmed, searchable, disabled, adapter, suggest, onError, languageCode, defaultCountry, (countriesAllowed ?? []).join(',')]);
+    // The option VALUE is the suggestion's position, never the vendor's id: the command list may normalise an item
+    // value (trim it), and a vendor id is opaque text the framework must hand back exactly as it came.
+    const options = useMemo(() => suggestions.map((suggestion, index) => ({ value: `suggestion-${index}`, label: suggestion.primaryText, data: suggestion })), [suggestions]);
+    const reset = useCallback(() => {
+        sequenceRef.current += 1;
+        setQuery('');
+        setSuggestions([]);
+        setSearching(false);
+    }, []);
+    const handleChoose = useCallback((optionValue) => {
+        const suggestion = options.find((option) => option.value === optionValue)?.data;
+        if (suggestion === undefined)
+            return;
+        choosingRef.current = true;
+        let input;
+        try {
+            input = adapter.buildRetrieveInput({ suggestion, languageCode });
+        }
+        catch (error) {
+            choosingRef.current = false;
+            onError(asError(error));
+            return;
+        }
+        retrieve(input)
+            .then((output) => {
+            const address = adapter.readAddress(output);
+            if (address === undefined) {
+                onError(new ProviderAddressLookupPlaceWithoutAddressError());
+                return;
+            }
+            onSelect({ address });
+        })
+            .catch((error) => onError(asError(error)))
+            .finally(() => {
+            choosingRef.current = false;
+            reset();
+        });
+    }, [adapter, languageCode, onError, onSelect, options, reset, retrieve]);
+    const handleOpenChange = useCallback((open) => {
+        if (open || choosingRef.current)
+            return;
+        // Closed without a choice: the lookup session is abandoned, and the host starts a new one.
+        reset();
+        onCancel();
+    }, [onCancel, reset]);
+    const emptyMessage = !searchable
+        ? label(FormFieldAddressLookupLabel.LOOKUP_TYPE_MORE, { minimum: PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH })
+        : label(FormFieldAddressLookupLabel.LOOKUP_NO_RESULTS);
+    return (_jsx(Combobox, { schema: LOOKUP_QUERY_SCHEMA, name: name, 
+        // Always empty: the trigger keeps inviting a search, and a chosen place lands in the address parts.
+        value: "", options: options, onChange: handleChoose, onSearchChange: setQuery, onOpenChange: handleOpenChange, shouldFilter: false, isLoading: searching, disabled: disabled, placeholder: label(FormFieldAddressLookupLabel.LOOKUP_PLACEHOLDER), searchPlaceholder: label(FormFieldAddressLookupLabel.LOOKUP_SEARCH_PLACEHOLDER), emptyMessage: emptyMessage, 
+        // Inside the suggestion popup, below the results: the container the vendor's terms put the attribution in.
+        listFooter: attribution === undefined ? undefined : _jsx(ProviderAddressLookupAttribution, { attribution: attribution }), renderOption: (option) => {
+            // The combobox wrapper erases its option payload type; the payload is the suggestion set above.
+            const suggestion = option.data;
+            return (_jsxs("span", { className: "flex min-w-0 flex-col", children: [_jsx("span", { className: "truncate", children: suggestion?.primaryText ?? option.label }), suggestion?.secondaryText ? _jsx("span", { className: "truncate text-xs text-muted-foreground", children: suggestion.secondaryText }) : null] }));
+        } }));
+}
+//# sourceMappingURL=ProviderAddressLookupCombobox.js.map

package/dist/esm/core/external-providers/ProviderAddressLookupCombobox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderAddressLookupCombobox.js","sourceRoot":"","sources":["../../../../../src/core/external-providers/ProviderAddressLookupCombobox.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * The framework's address-lookup COMPONENT, for any vendor that supplies a `ProviderAddressLookupAdapter` (#561).\n *\n * A vendor's lookup is four pure functions (build the suggest input, read the suggestions, build the retrieve\n * input, read the address). Everything else a lookup must get right is the same for every vendor and is written\n * once here:\n *\n * - **The keyboard and screen-reader pattern is the engine's `Combobox`**, not new markup: a trigger with\n *   `role=\"combobox\"` and `aria-expanded`, and inside it the command list whose text box is a WAI-ARIA combobox\n *   over a `listbox` — arrow keys move the active option, which is announced through `aria-activedescendant`,\n *   Enter chooses it and Escape closes the list. Server-side results, so the list is not filtered again locally.\n * - **Suggestions start at {@link PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH} characters and are debounced**\n *   by {@link PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS} (#561 D5): fewer characters match half a country, and a\n *   request per keystroke spends the person's per-operation allowance at the door.\n * - **A slower, older answer never replaces a newer one.** Each search carries a sequence number and only the\n *   latest may write the list — the ordinary way a typeahead shows results for text the person already changed.\n * - **Nothing vendor-owned is kept.** The suggestion's id lives only until the retrieval; the address that comes\n *   back is handed to `onSelect` and the field takes it as typed text.\n * - **Every failure is reported, never thrown** (`onError`), so the host can say the lookup is unavailable while\n *   the address parts below keep working by hand.\n *\n * The session token and the choice of backend operations are NOT here: the host binds `suggest` / `retrieve` to the\n * operations the provider declared and fills the token itself (#561 D4). The vendor attribution arrives from the host\n * as data and is shown here, inside the suggestion popup beside the results, by {@link ProviderAddressLookupAttribution}.\n */\n\nimport React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { z } from 'zod';\nimport { FormFieldAddressLookupLabel, FrontendComponentType } from '@wildo-ai/presets-components-models';\nimport type {\n  ProviderAddressLookupAdapter,\n  ProviderAddressLookupAttributionText,\n  ProviderAddressLookupProps,\n  ProviderAddressLookupSuggestion,\n} from '@wildo-ai/saas-models';\n\nimport { useI18n } from '~wildo-frontend-lib/core/i18n/useI18n';\nimport { Combobox } from '~wildo-frontend-lib/components/form/combobox';\nimport type { FieldOption } from '~wildo-frontend-lib/components/form/form-field-types';\n\n/** Characters typed before a search runs (#561 D5). */\nexport const PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH = 3;\n\n/** Quiet time after the last keystroke before a search runs, in milliseconds. */\nexport const PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS = 300;\n\n/** The search box holds text, never a stored value: the combobox is used for its interaction pattern only. */\nconst LOOKUP_QUERY_SCHEMA = z.string();\n\nexport interface ProviderAddressLookupComboboxProps extends ProviderAddressLookupProps {\n  /** The vendor's four functions. */\n  readonly adapter: ProviderAddressLookupAdapter;\n}\n\n/**\n * The vendor answered the retrieval, and the place it describes has no postal address the field can hold (no\n * street line, no town or no country). Reported through `onError` like any failure, as its own class so the host\n * can say \"this place cannot be used\" rather than \"the lookup is unavailable\" — the lookup worked.\n */\nexport class ProviderAddressLookupPlaceWithoutAddressError extends Error {\n  constructor() {\n    super('The chosen place has no postal address the field can hold.');\n    this.name = 'ProviderAddressLookupPlaceWithoutAddressError';\n  }\n}\n\n/**\n * A vendor's required attribution, rendered to the vendor's text rules (#561 D4).\n *\n * Google's rules for its \"Google Maps\" text, when its logo is not used: never translated (`translate=\"no\"`), never\n * wrapped onto two lines, weight 400, 12–16 px, normal letter spacing, and white, #1F1F1F or #5E5E5E with at least\n * 4.5:1 contrast against its background. The mark is therefore set in #1F1F1F on its own white ground, which keeps\n * that contrast on every theme the application ships — the one place a vendor's colours override the design\n * system's tokens, as a logo would. The sentence around it, for assistive technology, comes from the application's\n * labels; the mark itself is hidden from them so it is not read twice.\n * spec-cite: https://developers.google.com/maps/documentation/places/web-service/policies — \"Font color: White, black\n * (#1F1F1F), or gray (#5E5E5E)\", \"Don't wrap Google Maps onto multiple lines\", \"Prevent browsers from translating\n * Google Maps by using the HTML attribute translate='no'\". Fetched 2026-09-29.\n */\nexport function ProviderAddressLookupAttribution({ attribution }: { readonly attribution: ProviderAddressLookupAttributionText }): React.ReactElement {\n  return (\n    <span data-address-lookup-attribution=\"\" className=\"inline-flex\">\n      <span className=\"sr-only\">{attribution.accessibleLabel}</span>\n      <span\n        aria-hidden=\"true\"\n        translate=\"no\"\n        className=\"whitespace-nowrap rounded-sm px-1 text-xs font-normal tracking-normal\"\n        style={{ color: '#1F1F1F', backgroundColor: '#FFFFFF' }}\n      >\n        {attribution.mark}\n      </span>\n    </span>\n  );\n}\n\nfunction asError(value: unknown): Error {\n  return value instanceof Error ? value : new Error(String(value));\n}\n\nexport function ProviderAddressLookupCombobox(props: ProviderAddressLookupComboboxProps): React.ReactElement {\n  const { adapter, suggest, retrieve, onSelect, onCancel, onError, countriesAllowed, defaultCountry, languageCode, disabled, name, attribution } = props;\n  const { tComponent } = useI18n({ component: [FrontendComponentType.LOW_LEVEL_FORM_FIELD_ADDRESS] });\n  const label = (key: FormFieldAddressLookupLabel, params?: Record<string, string | number>) =>\n    tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_ADDRESS, key, params);\n\n  const [query, setQuery] = useState('');\n  const [suggestions, setSuggestions] = useState<readonly ProviderAddressLookupSuggestion[]>([]);\n  const [searching, setSearching] = useState(false);\n  /** Incremented by every search and every reset; an answer is written only while it is still the latest. */\n  const sequenceRef = useRef(0);\n  /** Set while a chosen suggestion is being retrieved, so the list closing on a choice is not read as a cancel. */\n  const choosingRef = useRef(false);\n\n  const trimmed = query.trim();\n  const searchable = trimmed.length >= PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH;\n\n  useEffect(() => {\n    const sequence = ++sequenceRef.current;\n    if (!searchable || disabled) {\n      setSuggestions([]);\n      setSearching(false);\n      return undefined;\n    }\n    setSearching(true);\n    const timer = setTimeout(() => {\n      let input: Record<string, unknown>;\n      try {\n        input = adapter.buildSuggestInput({ query: trimmed, countriesAllowed, defaultCountry, languageCode });\n      } catch (error) {\n        setSearching(false);\n        onError(asError(error));\n        return;\n      }\n      suggest(input)\n        .then((output) => {\n          if (sequence !== sequenceRef.current) return;\n          setSuggestions(adapter.readSuggestions(output));\n        })\n        .catch((error: unknown) => {\n          if (sequence !== sequenceRef.current) return;\n          setSuggestions([]);\n          onError(asError(error));\n        })\n        .finally(() => {\n          if (sequence === sequenceRef.current) setSearching(false);\n        });\n    }, PROVIDER_ADDRESS_LOOKUP_DEBOUNCE_MS);\n    return () => clearTimeout(timer);\n    // `countriesAllowed` is an array the field re-creates per render; its content is what matters.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [trimmed, searchable, disabled, adapter, suggest, onError, languageCode, defaultCountry, (countriesAllowed ?? []).join(',')]);\n\n  // The option VALUE is the suggestion's position, never the vendor's id: the command list may normalise an item\n  // value (trim it), and a vendor id is opaque text the framework must hand back exactly as it came.\n  const options = useMemo<FieldOption<string, ProviderAddressLookupSuggestion>[]>(\n    () => suggestions.map((suggestion, index) => ({ value: `suggestion-${index}`, label: suggestion.primaryText, data: suggestion })),\n    [suggestions],\n  );\n\n  const reset = useCallback(() => {\n    sequenceRef.current += 1;\n    setQuery('');\n    setSuggestions([]);\n    setSearching(false);\n  }, []);\n\n  const handleChoose = useCallback(\n    (optionValue: string) => {\n      const suggestion = options.find((option) => option.value === optionValue)?.data;\n      if (suggestion === undefined) return;\n      choosingRef.current = true;\n      let input: Record<string, unknown>;\n      try {\n        input = adapter.buildRetrieveInput({ suggestion, languageCode });\n      } catch (error) {\n        choosingRef.current = false;\n        onError(asError(error));\n        return;\n      }\n      retrieve(input)\n        .then((output) => {\n          const address = adapter.readAddress(output);\n          if (address === undefined) {\n            onError(new ProviderAddressLookupPlaceWithoutAddressError());\n            return;\n          }\n          onSelect({ address });\n        })\n        .catch((error: unknown) => onError(asError(error)))\n        .finally(() => {\n          choosingRef.current = false;\n          reset();\n        });\n    },\n    [adapter, languageCode, onError, onSelect, options, reset, retrieve],\n  );\n\n  const handleOpenChange = useCallback(\n    (open: boolean) => {\n      if (open || choosingRef.current) return;\n      // Closed without a choice: the lookup session is abandoned, and the host starts a new one.\n      reset();\n      onCancel();\n    },\n    [onCancel, reset],\n  );\n\n  const emptyMessage = !searchable\n    ? label(FormFieldAddressLookupLabel.LOOKUP_TYPE_MORE, { minimum: PROVIDER_ADDRESS_LOOKUP_MINIMUM_QUERY_LENGTH })\n    : label(FormFieldAddressLookupLabel.LOOKUP_NO_RESULTS);\n\n  return (\n    <Combobox\n      schema={LOOKUP_QUERY_SCHEMA}\n      name={name}\n      // Always empty: the trigger keeps inviting a search, and a chosen place lands in the address parts.\n      value=\"\"\n      options={options}\n      onChange={handleChoose}\n      onSearchChange={setQuery}\n      onOpenChange={handleOpenChange}\n      shouldFilter={false}\n      isLoading={searching}\n      disabled={disabled}\n      placeholder={label(FormFieldAddressLookupLabel.LOOKUP_PLACEHOLDER)}\n      searchPlaceholder={label(FormFieldAddressLookupLabel.LOOKUP_SEARCH_PLACEHOLDER)}\n      emptyMessage={emptyMessage}\n      // Inside the suggestion popup, below the results: the container the vendor's terms put the attribution in.\n      listFooter={attribution === undefined ? undefined : <ProviderAddressLookupAttribution attribution={attribution} />}\n      renderOption={(option) => {\n        // The combobox wrapper erases its option payload type; the payload is the suggestion set above.\n        const suggestion = option.data as ProviderAddressLookupSuggestion | undefined;\n        return (\n          <span className=\"flex min-w-0 flex-col\">\n            <span className=\"truncate\">{suggestion?.primaryText ?? option.label}</span>\n            {suggestion?.secondaryText ? <span className=\"truncate text-xs text-muted-foreground\">{suggestion.secondaryText}</span> : null}\n          </span>\n        );\n      }}\n    />\n  );\n}\n"]}

package/dist/esm/core/external-providers/ProviderAddressLookupHost.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The framework side of an address lookup (#561): offer the live `FRONTEND_ADDRESS_LOOKUP` providers, load the
+ * chosen one's component, run its vendor calls through the application backend, hold what it returns to the
+ * field's own rules, and keep the field usable by hand whatever happens.
+ *
+ * `FormField` renders it in every `z_address()` field's `renderLookup` slot. With no live lookup provider — every
+ * application that declared none — it renders NOTHING, and the field is the plain multi-part control.
+ *
+ * ## What the host ENFORCES, because a component could forget (#561 D2, D4)
+ *
+ * - **The vendor is reached only through the provider-operation door.** The component receives `suggest` and
+ *   `retrieve`, bound to the two operations its descriptor declares and run through
+ *   `POST /provider-operations/:providerRef/:operationId` on the application's own account. The page holds no
+ *   vendor key; the backend admits each operation by `providers.browserOperations`, counts it against the person,
+ *   and records it. A provider whose component declares no `addressLookup` operations is not offered at all.
+ * - **One vendor session per lookup.** The host writes a UUIDv4 into the declared `sessionTokenInput` of every
+ *   suggestion and of the retrieval, and starts a new one after a retrieval or when the lookup is abandoned — so a
+ *   vendor that bills by session is never billed per keystroke by a component that forgot the token.
+ * - **The vendor's attribution is handed to the component** from the descriptor's `attributionMark` — the mark
+ *   verbatim and a sentence from the application's labels naming it — for the component to show inside its
+ *   suggestion popup, the container the vendor's terms require (the framework combobox does, with
+ *   `ProviderAddressLookupAttribution`).
+ * - **The field decides.** A chosen address passes `receiveProviderAddressLookupSelection` against the field's own
+ *   schema (countries, required parts) and the component's declared place-id retention before `applyAddress`; a
+ *   refused one fills nothing and says so.
+ *
+ * ## Manual entry always works (#561 D5)
+ *
+ * A refusal, a throttle, a vendor timeout, a component that fails to load: each leaves the parts exactly as they
+ * were, editable, and shows one status line telling the person to enter the address below. Nothing blocks the
+ * form's submission.
+ */
+import React from 'react';
+import type { z } from 'zod';
+import type { AddressFieldLookupHost } from '../../components/form/fields/form-field-address';
+/** Why the lookup is showing a status line instead of (or beside) its search. */
+export declare enum ProviderAddressLookupNotice {
+    /** The lookup could not run; the parts work by hand. */
+    UNAVAILABLE = "UNAVAILABLE",
+    /** The chosen place could not fill this field. */
+    ADDRESS_REFUSED = "ADDRESS_REFUSED"
+}
+export interface ProviderAddressLookupHostProps {
+    /** What the field hands its `renderLookup` slot. */
+    readonly host: AddressFieldLookupHost;
+    /** The field's own `z_address()` schema: a chosen address it refuses is refused here, before it fills anything. */
+    readonly addressSchema: z.ZodType;
+    /** The field's form name; the lookup control is named `<name>.lookup`. */
+    readonly fieldName: string;
+}
+export declare function ProviderAddressLookupHost({ host, addressSchema, fieldName }: ProviderAddressLookupHostProps): React.ReactElement | null;
+//# sourceMappingURL=ProviderAddressLookupHost.d.ts.map

package/dist/esm/core/external-providers/ProviderAddressLookupHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderAddressLookupHost.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/ProviderAddressLookupHost.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAiD,MAAM,OAAO,CAAC;AACtE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkB7B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+DAA+D,CAAC;AAS5G,iFAAiF;AACjF,oBAAY,2BAA2B;IACrC,wDAAwD;IACxD,WAAW,gBAAgB;IAC3B,kDAAkD;IAClD,eAAe,oBAAoB;CACpC;AAED,MAAM,WAAW,8BAA8B;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,mHAAmH;IACnH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAOD,wBAAgB,yBAAyB,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,EAAE,8BAA8B,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAkKvI"}