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

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"}

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

@@ -0,0 +1,144 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 { useCallback, useMemo, useRef, useState } from 'react';
+import { ButtonSize, FormFieldAddressLookupLabel, FrontendComponentType } from '@wildo-ai/presets-components-models';
+import { CoreResourceType, UserPrivacySchema } from '@wildo-ai/saas-models';
+import { BUILTIN_PROVIDER_CAPABILITY } from '@wildo-ai/saas-models/public-runtime';
+import { getZodObjectShape } from '@wildo-ai/zod-decorators';
+import { ProviderComponentStatus } from '@wildo-ai/external-connectors-public/app';
+import { useApplication } from '../../core/runtime/useApplication.js';
+import { useI18n } from '../../core/i18n/useI18n.js';
+import { useGrantedConsentPurposes } from '../../core/security/useGrantedConsentPurposes.js';
+import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
+import { useProviderComponent, useProviderComponentChoices, } from '../../core/components-registry/useProviderComponent.frontend.hooks.js';
+import { Button, ButtonVariants_Variant } from '../../components/actions/button.js';
+import { FieldLabel } from '../../components/form/chromes/field.js';
+import { receiveProviderAddressLookupSelection } from './provider-address-lookup-selection.frontend.utils.js';
+import { ProviderAddressLookupPlaceWithoutAddressError } from './ProviderAddressLookupCombobox.js';
+const ADDRESS_LOOKUP_CAPABILITY = BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ADDRESS_LOOKUP;
+/** Consent purposes are worded through the field that stores a person's grant (#966), as the file field does. */
+const CONSENTED_PURPOSES_FIELD_SCHEMA = getZodObjectShape(UserPrivacySchema).consentedPurposes;
+/** Why the lookup is showing a status line instead of (or beside) its search. */
+export var ProviderAddressLookupNotice;
+(function (ProviderAddressLookupNotice) {
+    /** The lookup could not run; the parts work by hand. */
+    ProviderAddressLookupNotice["UNAVAILABLE"] = "UNAVAILABLE";
+    /** The chosen place could not fill this field. */
+    ProviderAddressLookupNotice["ADDRESS_REFUSED"] = "ADDRESS_REFUSED";
+})(ProviderAddressLookupNotice || (ProviderAddressLookupNotice = {}));
+/** A fresh vendor session token: a version 4 UUID, as Google recommends for Places session tokens. */
+function newSessionToken() {
+    return globalThis.crypto.randomUUID();
+}
+export function ProviderAddressLookupHost({ host, addressSchema, fieldName }) {
+    const { providerComponentRegistry, frontendProviderRegistry } = useApplication();
+    const { t, tComponent, tResourceFieldEnumValue, currentLanguage } = useI18n({ component: [FrontendComponentType.LOW_LEVEL_FORM_FIELD_ADDRESS] });
+    const label = (key, params) => tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_ADDRESS, key, params);
+    const allChoices = useProviderComponentChoices(ADDRESS_LOOKUP_CAPABILITY);
+    // Offered only when the component declares how it reaches its vendor: without declared operations there is no
+    // call this host could make on its behalf, and a component making its own would bypass the door.
+    const choices = useMemo(() => allChoices.filter((choice) => providerComponentRegistry?.describe(ADDRESS_LOOKUP_CAPABILITY, choice.providerRef)?.addressLookup !== undefined), [allChoices, providerComponentRegistry]);
+    const [pickedRef, setPickedRef] = useState(undefined);
+    // A single provider needs no chooser; several are a genuine choice the person makes, never this host.
+    const chosen = pickedRef ?? (choices.length === 1 ? choices[0]?.providerRef : undefined);
+    const { status, Component, missingConsentPurposes } = useProviderComponent(ADDRESS_LOOKUP_CAPABILITY, chosen);
+    const { grant: grantConsent } = useGrantedConsentPurposes();
+    const [notice, setNotice] = useState(undefined);
+    const descriptor = chosen === undefined ? undefined : providerComponentRegistry?.describe(ADDRESS_LOOKUP_CAPABILITY, chosen);
+    const declaration = descriptor?.addressLookup;
+    /** The current vendor session; `undefined` until the first call of a session needs one. */
+    const sessionTokenRef = useRef(undefined);
+    const endSession = useCallback(() => {
+        sessionTokenRef.current = undefined;
+    }, []);
+    const run = useCallback(async (operationId, input) => {
+        if (chosen === undefined)
+            throw new Error('No address lookup provider is chosen.');
+        const tokenInput = declaration?.sessionTokenInput;
+        let sent = { ...input };
+        if (tokenInput !== undefined) {
+            sessionTokenRef.current ??= newSessionToken();
+            // Written by the host AFTER the component's input, so a component cannot send its own token instead.
+            sent = { ...sent, [tokenInput]: sessionTokenRef.current };
+        }
+        const answer = await getManualCallsHttpClient().executeProviderOperation(chosen, operationId, { input: sent });
+        return answer.output;
+    }, [chosen, declaration?.sessionTokenInput]);
+    const suggest = useCallback((input) => {
+        if (declaration === undefined)
+            return Promise.reject(new Error('The address lookup declares no operations.'));
+        return run(declaration.suggestOperationId, input);
+    }, [declaration, run]);
+    const retrieve = useCallback((input) => {
+        if (declaration === undefined)
+            return Promise.reject(new Error('The address lookup declares no operations.'));
+        // The retrieval ends the vendor session whatever it answers: the next search is a new session.
+        return run(declaration.retrieveOperationId, input).finally(endSession);
+    }, [declaration, endSession, run]);
+    const handleSelect = useCallback((selection) => {
+        if (chosen === undefined)
+            return;
+        endSession();
+        const outcome = receiveProviderAddressLookupSelection({ providerRef: chosen, descriptor, selection, addressSchema });
+        if (outcome.accepted === undefined) {
+            setNotice(ProviderAddressLookupNotice.ADDRESS_REFUSED);
+            return;
+        }
+        setNotice(undefined);
+        host.applyAddress(outcome.accepted.address);
+    }, [addressSchema, chosen, descriptor, endSession, host]);
+    const handleCancel = useCallback(() => endSession(), [endSession]);
+    const handleError = useCallback((error) => {
+        endSession();
+        // A place with no holdable address is the lookup WORKING and the place being unusable — said as such.
+        setNotice(error instanceof ProviderAddressLookupPlaceWithoutAddressError ? ProviderAddressLookupNotice.ADDRESS_REFUSED : ProviderAddressLookupNotice.UNAVAILABLE);
+    }, [endSession]);
+    if (choices.length === 0)
+        return null;
+    const chosenChoice = choices.find((choice) => choice.providerRef === chosen);
+    const providerName = (choice) => t(choice.displayNameLabelKey) ?? choice.displayName ?? choice.providerRef;
+    const lookupName = `${fieldName}.lookup`;
+    const Lookup = Component;
+    const failedToLoad = status === ProviderComponentStatus.UNAVAILABLE;
+    const shownNotice = failedToLoad ? ProviderAddressLookupNotice.UNAVAILABLE : notice;
+    return (_jsxs("div", { className: "flex flex-col gap-1", "data-address-lookup": chosen ?? '', children: [_jsx(FieldLabel, { htmlFor: `field-${lookupName}`, className: "text-sm text-muted-foreground", children: label(FormFieldAddressLookupLabel.LOOKUP_LABEL) }), choices.length > 1 ? (_jsx("div", { role: "group", className: "flex flex-wrap gap-item-xs", children: choices.map((choice) => (_jsx(Button, { type: "button", size: ButtonSize.SM, variant: choice.providerRef === chosen ? ButtonVariants_Variant.DEFAULT : ButtonVariants_Variant.OUTLINE, "aria-pressed": choice.providerRef === chosen, onClick: () => { setNotice(undefined); endSession(); setPickedRef(choice.providerRef); }, children: providerName(choice) }, choice.providerRef))) })) : null, status === ProviderComponentStatus.CONSENT_REQUIRED && chosenChoice !== undefined ? (_jsx("div", { role: "status", className: "flex flex-wrap items-center gap-item-xs text-sm text-muted-foreground", children: (() => {
+                    const purposes = missingConsentPurposes
+                        .map((purpose) => tResourceFieldEnumValue(CoreResourceType.USER_SELF_PREFERENCES, 'privacy.consentedPurposes', purpose, CONSENTED_PURPOSES_FIELD_SCHEMA))
+                        .join(', ');
+                    return (_jsxs(_Fragment, { children: [_jsx("span", { children: label(FormFieldAddressLookupLabel.LOOKUP_CONSENT_REQUIRED, { provider: providerName(chosenChoice), purposes }) }), grantConsent === undefined ? null : (_jsx(Button, { type: "button", size: ButtonSize.SM, variant: ButtonVariants_Variant.OUTLINE, onClick: () => void grantConsent(missingConsentPurposes), children: label(FormFieldAddressLookupLabel.LOOKUP_CONSENT_GRANT, { purposes }) }))] }));
+                })() })) : null, status === ProviderComponentStatus.READY && Lookup !== null && chosen !== undefined && declaration !== undefined ? (_jsx(_Fragment, { children: _jsx(Lookup, { providerRef: chosen, publicConfig: frontendProviderRegistry?.getProviderByRef(chosen)?.publicConfig ?? {}, ...(host.countriesAllowed !== undefined ? { countriesAllowed: host.countriesAllowed } : {}), ...(host.defaultCountry !== undefined ? { defaultCountry: host.defaultCountry } : {}), languageCode: currentLanguage, disabled: host.disabled, name: lookupName, ...(declaration.attributionMark !== undefined
+                        ? { attribution: { mark: declaration.attributionMark, accessibleLabel: label(FormFieldAddressLookupLabel.LOOKUP_ATTRIBUTION, { mark: declaration.attributionMark }) } }
+                        : {}), suggest: suggest, retrieve: retrieve, onSelect: handleSelect, onCancel: handleCancel, onError: handleError }) })) : null, shownNotice !== undefined ? (_jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: label(shownNotice === ProviderAddressLookupNotice.UNAVAILABLE ? FormFieldAddressLookupLabel.LOOKUP_UNAVAILABLE : FormFieldAddressLookupLabel.LOOKUP_ADDRESS_REFUSED) })) : null] }));
+}
+//# sourceMappingURL=ProviderAddressLookupHost.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderAddressLookupHost.js","sourceRoot":"","sources":["../../../../../src/core/external-providers/ProviderAddressLookupHost.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * The framework side of an address lookup (#561): offer the live `FRONTEND_ADDRESS_LOOKUP` providers, load the\n * chosen one's component, run its vendor calls through the application backend, hold what it returns to the\n * field's own rules, and keep the field usable by hand whatever happens.\n *\n * `FormField` renders it in every `z_address()` field's `renderLookup` slot. With no live lookup provider — every\n * application that declared none — it renders NOTHING, and the field is the plain multi-part control.\n *\n * ## What the host ENFORCES, because a component could forget (#561 D2, D4)\n *\n * - **The vendor is reached only through the provider-operation door.** The component receives `suggest` and\n *   `retrieve`, bound to the two operations its descriptor declares and run through\n *   `POST /provider-operations/:providerRef/:operationId` on the application's own account. The page holds no\n *   vendor key; the backend admits each operation by `providers.browserOperations`, counts it against the person,\n *   and records it. A provider whose component declares no `addressLookup` operations is not offered at all.\n * - **One vendor session per lookup.** The host writes a UUIDv4 into the declared `sessionTokenInput` of every\n *   suggestion and of the retrieval, and starts a new one after a retrieval or when the lookup is abandoned — so a\n *   vendor that bills by session is never billed per keystroke by a component that forgot the token.\n * - **The vendor's attribution is handed to the component** from the descriptor's `attributionMark` — the mark\n *   verbatim and a sentence from the application's labels naming it — for the component to show inside its\n *   suggestion popup, the container the vendor's terms require (the framework combobox does, with\n *   `ProviderAddressLookupAttribution`).\n * - **The field decides.** A chosen address passes `receiveProviderAddressLookupSelection` against the field's own\n *   schema (countries, required parts) and the component's declared place-id retention before `applyAddress`; a\n *   refused one fills nothing and says so.\n *\n * ## Manual entry always works (#561 D5)\n *\n * A refusal, a throttle, a vendor timeout, a component that fails to load: each leaves the parts exactly as they\n * were, editable, and shows one status line telling the person to enter the address below. Nothing blocks the\n * form's submission.\n */\n\nimport React, { useCallback, useMemo, useRef, useState } from 'react';\nimport type { z } from 'zod';\nimport { ButtonSize, FormFieldAddressLookupLabel, FrontendComponentType } from '@wildo-ai/presets-components-models';\nimport type { ProviderAddressLookupProps, ProviderAddressLookupSelection, ProviderCapability } from '@wildo-ai/saas-models';\nimport { CoreResourceType, UserPrivacySchema } from '@wildo-ai/saas-models';\nimport { BUILTIN_PROVIDER_CAPABILITY, type ProviderAddressLookupDeclaration } from '@wildo-ai/saas-models/public-runtime';\nimport { getZodObjectShape } from '@wildo-ai/zod-decorators';\nimport { ProviderComponentStatus } from '@wildo-ai/external-connectors-public/app';\n\nimport { useApplication } from '~wildo-frontend-lib/core/runtime/useApplication';\nimport { useI18n } from '~wildo-frontend-lib/core/i18n/useI18n';\nimport { useGrantedConsentPurposes } from '~wildo-frontend-lib/core/security/useGrantedConsentPurposes';\nimport { getManualCallsHttpClient } from '~wildo-frontend-lib/core/requests/wildo-http-client-manual-calls.frontend.service';\nimport {\n  useProviderComponent,\n  useProviderComponentChoices,\n} from '~wildo-frontend-lib/core/components-registry/useProviderComponent.frontend.hooks';\nimport { Button, ButtonVariants_Variant } from '~wildo-frontend-lib/components/actions/button';\nimport { FieldLabel } from '~wildo-frontend-lib/components/form/chromes/field';\nimport type { AddressFieldLookupHost } from '~wildo-frontend-lib/components/form/fields/form-field-address';\nimport { receiveProviderAddressLookupSelection } from './provider-address-lookup-selection.frontend.utils';\nimport { ProviderAddressLookupPlaceWithoutAddressError } from './ProviderAddressLookupCombobox';\n\nconst ADDRESS_LOOKUP_CAPABILITY = BUILTIN_PROVIDER_CAPABILITY.FRONTEND_ADDRESS_LOOKUP as ProviderCapability;\n\n/** Consent purposes are worded through the field that stores a person's grant (#966), as the file field does. */\nconst CONSENTED_PURPOSES_FIELD_SCHEMA = getZodObjectShape(UserPrivacySchema).consentedPurposes;\n\n/** Why the lookup is showing a status line instead of (or beside) its search. */\nexport enum ProviderAddressLookupNotice {\n  /** The lookup could not run; the parts work by hand. */\n  UNAVAILABLE = 'UNAVAILABLE',\n  /** The chosen place could not fill this field. */\n  ADDRESS_REFUSED = 'ADDRESS_REFUSED',\n}\n\nexport interface ProviderAddressLookupHostProps {\n  /** What the field hands its `renderLookup` slot. */\n  readonly host: AddressFieldLookupHost;\n  /** The field's own `z_address()` schema: a chosen address it refuses is refused here, before it fills anything. */\n  readonly addressSchema: z.ZodType;\n  /** The field's form name; the lookup control is named `<name>.lookup`. */\n  readonly fieldName: string;\n}\n\n/** A fresh vendor session token: a version 4 UUID, as Google recommends for Places session tokens. */\nfunction newSessionToken(): string {\n  return globalThis.crypto.randomUUID();\n}\n\nexport function ProviderAddressLookupHost({ host, addressSchema, fieldName }: ProviderAddressLookupHostProps): React.ReactElement | null {\n  const { providerComponentRegistry, frontendProviderRegistry } = useApplication();\n  const { t, tComponent, tResourceFieldEnumValue, currentLanguage } = 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 allChoices = useProviderComponentChoices(ADDRESS_LOOKUP_CAPABILITY);\n  // Offered only when the component declares how it reaches its vendor: without declared operations there is no\n  // call this host could make on its behalf, and a component making its own would bypass the door.\n  const choices = useMemo(\n    () => allChoices.filter((choice) => providerComponentRegistry?.describe(ADDRESS_LOOKUP_CAPABILITY, choice.providerRef)?.addressLookup !== undefined),\n    [allChoices, providerComponentRegistry],\n  );\n  const [pickedRef, setPickedRef] = useState<string | undefined>(undefined);\n  // A single provider needs no chooser; several are a genuine choice the person makes, never this host.\n  const chosen = pickedRef ?? (choices.length === 1 ? choices[0]?.providerRef : undefined);\n  const { status, Component, missingConsentPurposes } = useProviderComponent(ADDRESS_LOOKUP_CAPABILITY, chosen);\n  const { grant: grantConsent } = useGrantedConsentPurposes();\n  const [notice, setNotice] = useState<ProviderAddressLookupNotice | undefined>(undefined);\n\n  const descriptor = chosen === undefined ? undefined : providerComponentRegistry?.describe(ADDRESS_LOOKUP_CAPABILITY, chosen);\n  const declaration: ProviderAddressLookupDeclaration | undefined = descriptor?.addressLookup;\n\n  /** The current vendor session; `undefined` until the first call of a session needs one. */\n  const sessionTokenRef = useRef<string | undefined>(undefined);\n  const endSession = useCallback(() => {\n    sessionTokenRef.current = undefined;\n  }, []);\n\n  const run = useCallback(\n    async (operationId: string, input: Readonly<Record<string, unknown>>): Promise<unknown> => {\n      if (chosen === undefined) throw new Error('No address lookup provider is chosen.');\n      const tokenInput = declaration?.sessionTokenInput;\n      let sent: Record<string, unknown> = { ...input };\n      if (tokenInput !== undefined) {\n        sessionTokenRef.current ??= newSessionToken();\n        // Written by the host AFTER the component's input, so a component cannot send its own token instead.\n        sent = { ...sent, [tokenInput]: sessionTokenRef.current };\n      }\n      const answer = await getManualCallsHttpClient().executeProviderOperation(chosen, operationId, { input: sent });\n      return answer.output;\n    },\n    [chosen, declaration?.sessionTokenInput],\n  );\n\n  const suggest = useCallback(\n    (input: Readonly<Record<string, unknown>>) => {\n      if (declaration === undefined) return Promise.reject(new Error('The address lookup declares no operations.'));\n      return run(declaration.suggestOperationId, input);\n    },\n    [declaration, run],\n  );\n\n  const retrieve = useCallback(\n    (input: Readonly<Record<string, unknown>>) => {\n      if (declaration === undefined) return Promise.reject(new Error('The address lookup declares no operations.'));\n      // The retrieval ends the vendor session whatever it answers: the next search is a new session.\n      return run(declaration.retrieveOperationId, input).finally(endSession);\n    },\n    [declaration, endSession, run],\n  );\n\n  const handleSelect = useCallback(\n    (selection: ProviderAddressLookupSelection) => {\n      if (chosen === undefined) return;\n      endSession();\n      const outcome = receiveProviderAddressLookupSelection({ providerRef: chosen, descriptor, selection, addressSchema });\n      if (outcome.accepted === undefined) {\n        setNotice(ProviderAddressLookupNotice.ADDRESS_REFUSED);\n        return;\n      }\n      setNotice(undefined);\n      host.applyAddress(outcome.accepted.address);\n    },\n    [addressSchema, chosen, descriptor, endSession, host],\n  );\n\n  const handleCancel = useCallback(() => endSession(), [endSession]);\n\n  const handleError = useCallback((error: Error) => {\n    endSession();\n    // A place with no holdable address is the lookup WORKING and the place being unusable — said as such.\n    setNotice(error instanceof ProviderAddressLookupPlaceWithoutAddressError ? ProviderAddressLookupNotice.ADDRESS_REFUSED : ProviderAddressLookupNotice.UNAVAILABLE);\n  }, [endSession]);\n\n  if (choices.length === 0) return null;\n\n  const chosenChoice = choices.find((choice) => choice.providerRef === chosen);\n  const providerName = (choice: (typeof choices)[number]): string => t(choice.displayNameLabelKey) ?? choice.displayName ?? choice.providerRef;\n  const lookupName = `${fieldName}.lookup`;\n  const Lookup = Component as React.ComponentType<ProviderAddressLookupProps> | null;\n  const failedToLoad = status === ProviderComponentStatus.UNAVAILABLE;\n  const shownNotice = failedToLoad ? ProviderAddressLookupNotice.UNAVAILABLE : notice;\n\n  return (\n    <div className=\"flex flex-col gap-1\" data-address-lookup={chosen ?? ''}>\n      <FieldLabel htmlFor={`field-${lookupName}`} className=\"text-sm text-muted-foreground\">\n        {label(FormFieldAddressLookupLabel.LOOKUP_LABEL)}\n      </FieldLabel>\n      {choices.length > 1 ? (\n        <div role=\"group\" className=\"flex flex-wrap gap-item-xs\">\n          {choices.map((choice) => (\n            <Button\n              key={choice.providerRef}\n              type=\"button\"\n              size={ButtonSize.SM}\n              variant={choice.providerRef === chosen ? ButtonVariants_Variant.DEFAULT : ButtonVariants_Variant.OUTLINE}\n              aria-pressed={choice.providerRef === chosen}\n              onClick={() => { setNotice(undefined); endSession(); setPickedRef(choice.providerRef); }}\n            >\n              {providerName(choice)}\n            </Button>\n          ))}\n        </div>\n      ) : null}\n      {status === ProviderComponentStatus.CONSENT_REQUIRED && chosenChoice !== undefined ? (\n        <div role=\"status\" className=\"flex flex-wrap items-center gap-item-xs text-sm text-muted-foreground\">\n          {(() => {\n            const purposes = missingConsentPurposes\n              .map((purpose) => tResourceFieldEnumValue(CoreResourceType.USER_SELF_PREFERENCES, 'privacy.consentedPurposes', purpose, CONSENTED_PURPOSES_FIELD_SCHEMA))\n              .join(', ');\n            return (\n              <>\n                <span>{label(FormFieldAddressLookupLabel.LOOKUP_CONSENT_REQUIRED, { provider: providerName(chosenChoice), purposes })}</span>\n                {grantConsent === undefined ? null : (\n                  <Button type=\"button\" size={ButtonSize.SM} variant={ButtonVariants_Variant.OUTLINE} onClick={() => void grantConsent(missingConsentPurposes)}>\n                    {label(FormFieldAddressLookupLabel.LOOKUP_CONSENT_GRANT, { purposes })}\n                  </Button>\n                )}\n              </>\n            );\n          })()}\n        </div>\n      ) : null}\n      {status === ProviderComponentStatus.READY && Lookup !== null && chosen !== undefined && declaration !== undefined ? (\n        <>\n          <Lookup\n            providerRef={chosen}\n            publicConfig={frontendProviderRegistry?.getProviderByRef(chosen as never)?.publicConfig ?? {}}\n            {...(host.countriesAllowed !== undefined ? { countriesAllowed: host.countriesAllowed } : {})}\n            {...(host.defaultCountry !== undefined ? { defaultCountry: host.defaultCountry } : {})}\n            languageCode={currentLanguage}\n            disabled={host.disabled}\n            name={lookupName}\n            {...(declaration.attributionMark !== undefined\n              ? { attribution: { mark: declaration.attributionMark, accessibleLabel: label(FormFieldAddressLookupLabel.LOOKUP_ATTRIBUTION, { mark: declaration.attributionMark }) } }\n              : {})}\n            suggest={suggest}\n            retrieve={retrieve}\n            onSelect={handleSelect}\n            onCancel={handleCancel}\n            onError={handleError}\n          />\n        </>\n      ) : null}\n      {shownNotice !== undefined ? (\n        <p role=\"status\" className=\"text-sm text-muted-foreground\">\n          {label(shownNotice === ProviderAddressLookupNotice.UNAVAILABLE ? FormFieldAddressLookupLabel.LOOKUP_UNAVAILABLE : FormFieldAddressLookupLabel.LOOKUP_ADDRESS_REFUSED)}\n        </p>\n      ) : null}\n    </div>\n  );\n}\n"]}

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

@@ -29,7 +29,7 @@
  * translation becomes invisible.
  */
 import React from 'react';
-import type { FileStorageAccepted } from '@wildo-ai/saas-models/public-runtime';
+import type { ConsentPurpose, FileStorageAccepted } from '@wildo-ai/saas-models/public-runtime';
 import type { ProviderFilePickerConstraints, ProviderFileSelection } from '@wildo-ai/saas-models/public-runtime';
 import { type ProviderComponentChoice } from '../../core/components-registry/useProviderComponent.frontend.hooks';
 import { type ProviderFileSelectionRejection } from './provider-file-selection.frontend.utils';
@@ -84,6 +84,27 @@ export interface ProviderFilePickerHostProps {
         readonly chosen: string | undefined;
         choose(providerRef: string): void;
     }): React.ReactNode;
+    /**
+     * Renders the state shown when the chosen provider rests on consent the person has not granted (#1702):
+     * nothing of the provider has been downloaded, and the surface owes the person the reason and the way to
+     * change it. Supplied by the caller for the same reason as `renderChooser` — it is chrome, and its words
+     * are the caller's i18n. The default below names the purposes by their raw values: a missing label that
+     * LOOKS missing, never invented text.
+     */
+    renderConsentRequired?(input: ProviderFilePickerConsentRequiredInput): React.ReactNode;
+}
+/** What a consent-required state needs to say and to offer. */
+export interface ProviderFilePickerConsentRequiredInput {
+    /** The chosen provider, as a choice — its display-name label KEY included. */
+    readonly choice: ProviderComponentChoice;
+    /** The purposes the person would have to grant, in vocabulary order. Never empty. */
+    readonly missingPurposes: readonly ConsentPurpose[];
+    /**
+     * Records a grant of exactly `missingPurposes` through the person's audited preference write; the picker
+     * then loads without a re-mount. `undefined` when there is no signed-in person to record it for — the
+     * state must then say what is missing without offering an action it cannot perform.
+     */
+    readonly grant: (() => Promise<void>) | undefined;
 }
 export declare function ProviderFilePickerHost(props: ProviderFilePickerHostProps): React.ReactElement | null;
 //# sourceMappingURL=ProviderFilePickerHost.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ProviderFilePickerHost.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/ProviderFilePickerHost.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAGjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,KAAK,EACV,6BAA6B,EAE7B,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,kFAAkF,CAAC;AAC1F,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,0CAA0C,CAAC;AAIlD,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,6BAA6B,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,qBAAqB,EAAE,GAAG,IAAI,CAAC;IAClF,QAAQ,CAAC,IAAI,IAAI,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,8BAA8B,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7J;;;;OAIG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;QACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;QACpC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC,GAAG,KAAK,CAAC,SAAS,CAAC;CACrB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA4IpG"}
+{"version":3,"file":"ProviderFilePickerHost.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/ProviderFilePickerHost.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAA4D,MAAM,OAAO,CAAC;AAGjF,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EACV,6BAA6B,EAE7B,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAK9C,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,kFAAkF,CAAC;AAC1F,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,0CAA0C,CAAC;AAIlD,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,6BAA6B,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,qBAAqB,EAAE,GAAG,IAAI,CAAC;IAClF,QAAQ,CAAC,IAAI,IAAI,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,8BAA8B,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7J;;;;OAIG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;QACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;QACpC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC,GAAG,KAAK,CAAC,SAAS,CAAC;IACpB;;;;;;OAMG;IACH,qBAAqB,CAAC,CAAC,KAAK,EAAE,sCAAsC,GAAG,KAAK,CAAC,SAAS,CAAC;CACxF;AAED,+DAA+D;AAC/D,MAAM,WAAW,sCAAsC;IACrD,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,qFAAqF;IACrF,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CACnD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAuJpG"}

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

@@ -32,8 +32,10 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { BUILTIN_PROVIDER_CAPABILITY, layerProviderFilePickerConstraints } from '@wildo-ai/saas-models/public-runtime';
 import { useApplication } from '../../core/runtime/useApplication.js';
+import { useGrantedConsentPurposes } from '../../core/security/useGrantedConsentPurposes.js';
 import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
-import { ProviderComponentStatus, useProviderComponent, useProviderComponentChoices, } from '../../core/components-registry/useProviderComponent.frontend.hooks.js';
+import { ProviderComponentStatus } from '@wildo-ai/external-connectors-public/app';
+import { useProviderComponent, useProviderComponentChoices, } from '../../core/components-registry/useProviderComponent.frontend.hooks.js';
 import { receiveProviderFileSelections, } from './provider-file-selection.frontend.utils.js';
 const FILE_PICKER_CAPABILITY = BUILTIN_PROVIDER_CAPABILITY.FRONTEND_FILE_PICKER;
 export function ProviderFilePickerHost(props) {
@@ -57,7 +59,8 @@ export function ProviderFilePickerHost(props) {
         if (soleProviderRef !== undefined && chosen === undefined)
             setChosen(soleProviderRef);
     }, [soleProviderRef, chosen]);
-    const { status, Component } = useProviderComponent(FILE_PICKER_CAPABILITY, chosen);
+    const { status, Component, missingConsentPurposes } = useProviderComponent(FILE_PICKER_CAPABILITY, chosen);
+    const { grant: grantConsent } = useGrantedConsentPurposes();
     const publicConfig = useMemo(() => {
         if (chosen === undefined)
             return {};
@@ -132,13 +135,30 @@ export function ProviderFilePickerHost(props) {
         return null;
     const chooser = props.renderChooser?.({ choices, chosen, choose: setChosen })
         ?? defaultChooser({ choices, chosen, choose: setChosen });
+    const chosenChoice = choices.find((choice) => choice.providerRef === chosen);
+    const consentRequired = status === ProviderComponentStatus.CONSENT_REQUIRED && chosenChoice !== undefined
+        ? (props.renderConsentRequired ?? defaultConsentRequired)({
+            choice: chosenChoice,
+            missingPurposes: missingConsentPurposes,
+            grant: grantConsent === undefined ? undefined : () => grantConsent(missingConsentPurposes),
+        })
+        : null;
     // `Component` is typed as the registry's opaque component: this package must
     // not make the registry know any capability's props. The narrowing happens
     // HERE, where the capability is known, and it is the only cast in the path.
     const Picker = Component;
-    return (_jsxs(_Fragment, { children: [choices.length > 1 ? chooser : null, status === ProviderComponentStatus.READY && Picker !== null && chosen !== undefined ? (_jsx(Picker, { providerRef: chosen, publicConfig: publicConfig, constraints: constraints, getAccessToken: getAccessToken, onSelect: handleSelect, onCancel: handleCancel, onError: handleError })) : null] }));
+    return (_jsxs(_Fragment, { children: [choices.length > 1 ? chooser : null, consentRequired, status === ProviderComponentStatus.READY && Picker !== null && chosen !== undefined ? (_jsx(Picker, { providerRef: chosen, publicConfig: publicConfig, constraints: constraints, getAccessToken: getAccessToken, onSelect: handleSelect, onCancel: handleCancel, onError: handleError })) : null] }));
 }
 function defaultChooser(input) {
     return (_jsx("div", { role: "group", children: input.choices.map((choice) => (_jsx("button", { type: "button", "aria-pressed": choice.providerRef === input.chosen, onClick: () => input.choose(choice.providerRef), children: choice.displayName ?? choice.providerRef }, choice.providerRef))) }));
 }
+/**
+ * The fallback consent-required state: announced (`role="status"`), with a real, keyboard-reachable
+ * button when a grant can be recorded. It names purposes by their RAW values on purpose — a surface with an
+ * i18n service passes `renderConsentRequired` and words them; this default must not invent the words.
+ */
+function defaultConsentRequired(input) {
+    const purposes = input.missingPurposes.join(', ');
+    return (_jsxs("div", { role: "status", "data-provider-consent-required": input.choice.providerRef, children: [_jsx("span", { children: purposes }), input.grant === undefined ? null : (_jsx("button", { type: "button", onClick: () => void input.grant?.(), children: purposes }))] }));
+}
 //# sourceMappingURL=ProviderFilePickerHost.js.map