@vtex/faststore 0.0.7 → 0.0.8

package/dist/matter/account-address-book/account-address-country.js

@@ -0,0 +1,151 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { useStorefrontContext } from "../../sdk/context/storefront-context.js";
+import { useStorefrontFormatters } from "../../sdk/format/client.js";
+import { useIntl } from "../../sdk/i18n/client.js";
+import { useDataOverride } from "../../sdk/data/data-override-context.js";
+import { resolveAuthoredCopy } from "../../utils/resolve-authored-copy.js";
+import { countryDisplayName } from "../../sdk/address/country-display.js";
+import { AccountAddressBookSkeleton } from "./account-address-book.js";
+import { Select } from "../../particles/select/select.js";
+import { useAccountAddressForm } from "./account-address-form-context.js";
+import { useEffect, useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+const AddressCountryControlDefinition = defineComponent({
+	name: "AddressCountryControl",
+	importPath: "@vtex/faststore/components",
+	component: AddressCountryControl,
+	fragment: `
+  fragment AddressCountryControlData on Query {
+    shippingCountries {
+      countries
+      source
+    }
+  }
+`,
+	fetchStrategy: "reactive",
+	requiresContext: "account-address-form",
+	skeleton: AccountAddressBookSkeleton,
+	editor: {
+		label: "Address Country Control",
+		category: "input"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Field label"
+	} },
+	guideline: "The country of the address. A new address picks it from the countries the store ships to, in a list sorted by name, when there are two or more; with one it shows nothing, and the address takes that country. A saved address keeps its country, shown as text, and so does a new one when the list could not be read. Changing it keeps the fields the new country takes, and brings back what was typed for that country before. Compose it explicitly under AccountAddressFormRoot to offer the choice: in the root's default composition it gets no list and shows the root's defaultCountry as text. Place AccountAddressCountryNotice next to it. Must be inside AccountAddressFormRoot."
+});
+const AccountAddressCountryNoticeDefinition = defineComponent({
+	name: "AccountAddressCountryNotice",
+	importPath: "@vtex/faststore/components",
+	component: AccountAddressCountryNotice,
+	requiresContext: "account-address-form",
+	editor: {
+		label: "Account Address Country Notice",
+		category: "content"
+	},
+	schema: { message: {
+		type: "string",
+		label: "Notice message"
+	} },
+	guideline: "Says which fields a country change left behind, and that they come back on switching back. Announced politely, and empty until a change leaves something behind. The message takes count, country, previous and fields as ICU arguments. Place it right after AddressCountryControl. Must be inside AccountAddressFormRoot."
+});
+function AddressCountryControl({ $data: $dataProp, label, className }) {
+	const slice = useDataOverride($dataProp);
+	const { mode, country, pending, countryChoice: { offer, selected, change } } = useAccountAddressForm();
+	const { displayName } = useStorefrontFormatters();
+	const { locale } = useStorefrontContext();
+	const intl = useIntl();
+	const countries = slice?.countries ?? null;
+	const reported = countries?.join(",") ?? null;
+	useEffect(() => offer(reported === null ? null : reported.split(",").filter(Boolean)), [offer, reported]);
+	const options = useMemo(() => {
+		const collator = new Intl.Collator(locale);
+		return (countries ?? []).map((code) => ({
+			value: code,
+			label: countryDisplayName(code, displayName) ?? code
+		})).sort((a, b) => collator.compare(a.label, b.label));
+	}, [
+		countries,
+		locale,
+		displayName
+	]);
+	const wrapper = {
+		className,
+		"data-fs-address-country-control": "",
+		...selected !== country ? { "data-fs-address-country-control-pending": "" } : {}
+	};
+	if (mode === "add" && countries?.length === 1) return null;
+	if (mode === "add" && countries && countries.length > 1) return /* @__PURE__ */ jsx("div", {
+		...wrapper,
+		"data-fs-address-country-control-mode": "select",
+		children: /* @__PURE__ */ jsxs(Select.Root, {
+			value: selected,
+			disabled: pending,
+			onValueChange: (value) => value && change(value),
+			children: [
+				/* @__PURE__ */ jsx(Select.Label, { children: resolveAuthoredCopy(label, intl.formatMessage({ id: "fs/address-form.country" })) }),
+				/* @__PURE__ */ jsxs(Select.Trigger, {
+					"data-fs-account-address-form-control": "",
+					disabled: pending,
+					children: [/* @__PURE__ */ jsx(Select.Value, { children: (value) => options.find((option) => option.value === value)?.label ?? countryDisplayName(value, displayName) ?? value }), /* @__PURE__ */ jsx(Select.Icon, {})]
+				}),
+				/* @__PURE__ */ jsx(Select.Portal, { children: /* @__PURE__ */ jsx(Select.Positioner, { children: /* @__PURE__ */ jsx(Select.Popup, { children: /* @__PURE__ */ jsx(Select.List, { children: options.map((option) => /* @__PURE__ */ jsx(Select.Item, {
+					value: option.value,
+					label: option.label,
+					children: /* @__PURE__ */ jsx(Select.ItemText, { children: option.label })
+				}, option.value)) }) }) }) })
+			]
+		})
+	});
+	const name = countryDisplayName(country, displayName);
+	if (!name) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...wrapper,
+		"data-fs-address-country-control-mode": "text",
+		children: /* @__PURE__ */ jsx("p", {
+			"data-fs-address-country-control-text": "",
+			children: name
+		})
+	});
+}
+function describeChange({ change, message, intl, formatters }) {
+	if (!change || change.notCarried.length === 0) return "";
+	const { displayName, formatList } = formatters;
+	const values = {
+		count: change.notCarried.length,
+		country: countryDisplayName(change.to, displayName) ?? change.to,
+		previous: countryDisplayName(change.from, displayName) ?? change.from,
+		fields: formatList(change.notCarried.map(({ labelId }) => intl.formatMessage({ id: labelId })))
+	};
+	const fallback = intl.formatMessage({ id: "fs/address-form.country-notice" }, values);
+	const authored = resolveAuthoredCopy(message, "");
+	if (!authored) return fallback;
+	try {
+		return String(intl.formatters.getMessageFormat(authored, intl.locale).format(values));
+	} catch {
+		return fallback;
+	}
+}
+function AccountAddressCountryNotice({ message, className }) {
+	const { countryChoice: { lastChange } } = useAccountAddressForm();
+	const intl = useIntl();
+	const formatters = useStorefrontFormatters();
+	return /* @__PURE__ */ jsx("output", {
+		"aria-live": "polite",
+		className,
+		"data-fs-account-address-country-notice": "",
+		children: describeChange({
+			change: lastChange,
+			message,
+			intl,
+			formatters
+		})
+	});
+}
+//#endregion
+export { AccountAddressCountryNotice, AccountAddressCountryNoticeDefinition, AddressCountryControl, AddressCountryControlDefinition };
+
+//# sourceMappingURL=account-address-country.js.map

package/dist/matter/account-address-book/account-address-country.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-address-country.js","names":[],"sources":["../../../src/matter/account-address-book/account-address-country.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { useEffect, useMemo } from 'react';\nimport { Select } from '../../particles/select/select.js';\nimport { countryDisplayName } from '../../sdk/address/country-display.js';\nimport { useStorefrontContext } from '../../sdk/context/storefront-context.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useStorefrontFormatters } from '../../sdk/format/client.js';\nimport { useIntl } from '../../sdk/i18n/client.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { AccountAddressBookSkeleton } from './account-address-book.js';\nimport { type AccountAddressCountryChange, useAccountAddressForm } from './account-address-form-context.js';\n\n/**\n * The country of a new address, chosen from where the store ships, and the notice that says what a switch\n * left behind. The control reads `shippingCountries` through its own fragment and reports the list to the\n * form, which owns the country, the switch and the values set aside. Neither part touches the draft.\n */\n\nconst fragment = /* GraphQL */ `\n  fragment AddressCountryControlData on Query {\n    shippingCountries {\n      countries\n      source\n    }\n  }\n`;\n\n/** The shipping countries the control reads. `countries` is ISO 3166-1 alpha-3, in the platform's order. */\nexport type AddressCountryControlSlice = Readonly<{\n  countries: readonly string[];\n  source: 'PLATFORM' | 'SALES_CHANNEL_FALLBACK';\n}>;\n\nexport type AddressCountryControlProps = Readonly<{\n  /** Unwrapped `shippingCountries` from the reactive runtime: `null` when the read failed, absent outside the page query. */\n  $data?: AddressCountryControlSlice | null;\n  /** The select's label. A blank value falls back to the catalog copy. */\n  label?: string;\n  className?: string;\n}>;\n\nexport type AccountAddressCountryNoticeProps = Readonly<{\n  /** Replaces the whole sentence, with the same ICU arguments. A blank value falls back to the catalog copy. */\n  message?: string;\n  className?: string;\n}>;\n\nexport const AddressCountryControlDefinition = defineComponent<AddressCountryControlProps>({\n  name: 'AddressCountryControl',\n  importPath: '@vtex/faststore/components',\n  component: AddressCountryControl,\n  fragment,\n  fetchStrategy: 'reactive',\n  requiresContext: 'account-address-form',\n  skeleton: AccountAddressBookSkeleton,\n  editor: { label: 'Address Country Control', category: 'input' },\n  schema: {\n    label: { type: 'string', label: 'Field label' },\n  },\n  guideline:\n    \"The country of the address. A new address picks it from the countries the store ships to, in a list sorted by name, when there are two or more; with one it shows nothing, and the address takes that country. A saved address keeps its country, shown as text, and so does a new one when the list could not be read. Changing it keeps the fields the new country takes, and brings back what was typed for that country before. Compose it explicitly under AccountAddressFormRoot to offer the choice: in the root's default composition it gets no list and shows the root's defaultCountry as text. Place AccountAddressCountryNotice next to it. Must be inside AccountAddressFormRoot.\",\n});\n\nexport const AccountAddressCountryNoticeDefinition = defineComponent<AccountAddressCountryNoticeProps>({\n  name: 'AccountAddressCountryNotice',\n  importPath: '@vtex/faststore/components',\n  component: AccountAddressCountryNotice,\n  requiresContext: 'account-address-form',\n  editor: { label: 'Account Address Country Notice', category: 'content' },\n  schema: {\n    message: { type: 'string', label: 'Notice message' },\n  },\n  guideline:\n    'Says which fields a country change left behind, and that they come back on switching back. Announced politely, and empty until a change leaves something behind. The message takes count, country, previous and fields as ICU arguments. Place it right after AddressCountryControl. Must be inside AccountAddressFormRoot.',\n});\n\ntype CountryOption = Readonly<{ value: string; label: string }>;\n\nexport function AddressCountryControl({ $data: $dataProp, label, className }: AddressCountryControlProps) {\n  const slice = useDataOverride<AddressCountryControlSlice | null | undefined>($dataProp);\n  const {\n    mode,\n    country,\n    pending,\n    countryChoice: { offer, selected, change },\n  } = useAccountAddressForm();\n  const { displayName } = useStorefrontFormatters();\n  const { locale } = useStorefrontContext();\n  const intl = useIntl();\n\n  // A slice from another ancestor's provider has no `countries`: the list is unknown then.\n  const countries = slice?.countries ?? null;\n  const reported = countries?.join(',') ?? null;\n\n  useEffect(() => offer(reported === null ? null : reported.split(',').filter(Boolean)), [offer, reported]);\n\n  const options = useMemo<readonly CountryOption[]>(() => {\n    const collator = new Intl.Collator(locale);\n    return (countries ?? [])\n      .map((code) => ({ value: code, label: countryDisplayName(code, displayName) ?? code }))\n      .sort((a, b) => collator.compare(a.label, b.label));\n  }, [countries, locale, displayName]);\n\n  const switching = selected !== country;\n  const wrapper = {\n    className,\n    'data-fs-address-country-control': '',\n    ...(switching ? { 'data-fs-address-country-control-pending': '' } : {}),\n  };\n\n  if (mode === 'add' && countries?.length === 1) return null;\n\n  if (mode === 'add' && countries && countries.length > 1) {\n    return (\n      <div {...wrapper} data-fs-address-country-control-mode=\"select\">\n        <Select.Root value={selected} disabled={pending} onValueChange={(value) => value && change(value)}>\n          <Select.Label>\n            {resolveAuthoredCopy(label, intl.formatMessage({ id: 'fs/address-form.country' }))}\n          </Select.Label>\n          <Select.Trigger data-fs-account-address-form-control=\"\" disabled={pending}>\n            <Select.Value>\n              {(value) =>\n                options.find((option) => option.value === value)?.label ??\n                countryDisplayName(value, displayName) ??\n                value\n              }\n            </Select.Value>\n            <Select.Icon />\n          </Select.Trigger>\n          <Select.Portal>\n            <Select.Positioner>\n              <Select.Popup>\n                <Select.List>\n                  {options.map((option) => (\n                    <Select.Item key={option.value} value={option.value} label={option.label}>\n                      <Select.ItemText>{option.label}</Select.ItemText>\n                    </Select.Item>\n                  ))}\n                </Select.List>\n              </Select.Popup>\n            </Select.Positioner>\n          </Select.Portal>\n        </Select.Root>\n      </div>\n    );\n  }\n\n  const name = countryDisplayName(country, displayName);\n  if (!name) return null;\n\n  return (\n    <div {...wrapper} data-fs-address-country-control-mode=\"text\">\n      <p data-fs-address-country-control-text=\"\">{name}</p>\n    </div>\n  );\n}\n\ntype DescribeChangeInput = Readonly<{\n  change: AccountAddressCountryChange | null;\n  message: string | undefined;\n  intl: ReturnType<typeof useIntl>;\n  formatters: ReturnType<typeof useStorefrontFormatters>;\n}>;\n\nfunction describeChange({ change, message, intl, formatters }: DescribeChangeInput): string {\n  if (!change || change.notCarried.length === 0) return '';\n  const { displayName, formatList } = formatters;\n  const values = {\n    count: change.notCarried.length,\n    country: countryDisplayName(change.to, displayName) ?? change.to,\n    previous: countryDisplayName(change.from, displayName) ?? change.from,\n    fields: formatList(change.notCarried.map(({ labelId }) => intl.formatMessage({ id: labelId }))),\n  };\n  const fallback = intl.formatMessage({ id: 'fs/address-form.country-notice' }, values);\n  const authored = resolveAuthoredCopy(message, '');\n  if (!authored) return fallback;\n  try {\n    return String(intl.formatters.getMessageFormat(authored, intl.locale).format(values));\n  } catch {\n    // An authored message is free text: a malformed ICU pattern falls back to the catalog copy.\n    return fallback;\n  }\n}\n\nexport function AccountAddressCountryNotice({ message, className }: AccountAddressCountryNoticeProps) {\n  const {\n    countryChoice: { lastChange },\n  } = useAccountAddressForm();\n  const intl = useIntl();\n  const formatters = useStorefrontFormatters();\n\n  return (\n    <output aria-live=\"polite\" className={className} data-fs-account-address-country-notice=\"\">\n      {describeChange({ change: lastChange, message, intl, formatters })}\n    </output>\n  );\n}\n"],"mappings":"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"}

package/dist/matter/account-address-book/account-address-first-line.js

@@ -0,0 +1,11 @@
+import { formatAddress } from "../../sdk/address/format-address.js";
+//#region src/matter/account-address-book/account-address-first-line.ts
+/** The text of the address's first printed line, so a button says which address it acts on. */
+function firstLine(address) {
+	const [line] = formatAddress(address, address.country ?? "");
+	return (line ?? []).map(({ field, separator }) => `${separator ?? ""}${address[field] ?? ""}`).join("");
+}
+//#endregion
+export { firstLine };
+
+//# sourceMappingURL=account-address-first-line.js.map

package/dist/matter/account-address-book/account-address-first-line.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-address-first-line.js","names":[],"sources":["../../../src/matter/account-address-book/account-address-first-line.ts"],"sourcesContent":["import { formatAddress } from '../../sdk/address/format-address.js';\nimport type { AccountAddressBookItemSlice } from './account-address-book.js';\n\n/** The text of the address's first printed line, so a button says which address it acts on. */\nexport function firstLine(address: AccountAddressBookItemSlice): string {\n  const [line] = formatAddress(address, address.country ?? '');\n  return (line ?? []).map(({ field, separator }) => `${separator ?? ''}${address[field] ?? ''}`).join('');\n}\n"],"mappings":";;;AAIA,SAAgB,UAAU,SAA8C;CACtE,MAAM,CAAC,QAAQ,cAAc,SAAS,QAAQ,WAAW,EAAE;CAC3D,QAAQ,QAAQ,CAAC,EAAA,CAAG,KAAK,EAAE,OAAO,gBAAgB,GAAG,aAAa,KAAK,QAAQ,UAAU,IAAI,CAAC,CAAC,KAAK,EAAE;AACxG"}

package/dist/matter/account-address-book/account-address-form-context.d.ts

@@ -0,0 +1,55 @@
+import { MessageId } from "../../sdk/i18n/locales.js";
+import "../../sdk/i18n/client.js";
+import { AddressFieldError, AddressFieldName, CountryRules } from "../../sdk/address/types.js";
+//#region src/matter/account-address-book/account-address-form-context.d.ts
+export type EditableField = Exclude<AddressFieldName, 'name'>;
+/** The draft: the address fields the form edits. `name` is not edited, as `CustomerAddress` has none. */
+export type AccountAddressFormDraft = Readonly<Partial<Record<EditableField, string>>>;
+export type AccountAddressFormFieldErrors = Readonly<Partial<Record<AddressFieldName, AddressFieldError>>>;
+/** What a refusal that names no field on screen says. */
+export type AccountAddressFormErrorKind = 'unrenderedField' | 'notFound' | 'unauthorized' | 'saveFailed' | 'rulesFailed' | 'countrySwitchFailed' | 'unsupportedCountry';
+/** What the last applied switch did not carry, for AccountAddressCountryNotice. */
+export type AccountAddressCountryChange = Readonly<{
+  /** ISO 3166-1 alpha-3. */
+  from: string;
+  to: string;
+  /** In the old country's field order; empty when everything was carried. */
+  notCarried: readonly Readonly<{
+    field: AddressFieldName;
+    labelId: MessageId;
+  }>[];
+}>;
+/**
+ * The country choice, the only part of the form the country control and the notice touch. The
+ * values set aside on a switch stay with the draft's owner, behind `change`.
+ */
+export type AccountAddressFormCountryChoice = Readonly<{
+  /** AddressCountryControl reports its shipping countries; `null` means unknown. Returns the withdrawal. */
+  offer: (countries: readonly string[] | null) => () => void;
+  /** The country the control shows as chosen: a switch in flight, else `country`. */
+  selected: string;
+  /** Starts a switch in add mode. Ignored in edit mode. `change(country)` cancels a switch in flight. */
+  change: (to: string) => void;
+  /** `null` until a switch applies, and always in edit mode. */
+  lastChange: AccountAddressCountryChange | null;
+}>;
+export type AccountAddressFormContextValue = Readonly<{
+  mode: 'add' | 'edit';
+  /** ISO 3166-1 alpha-3, upper case. Empty while a new address's country is not resolved yet. */
+  country: string;
+  /** `null` until the country's rules loaded. */
+  rules: CountryRules | null;
+  draft: AccountAddressFormDraft;
+  fieldErrors: AccountAddressFormFieldErrors;
+  formError: AccountAddressFormErrorKind | null;
+  pending: boolean;
+  setField: (name: EditableField, value: string) => void;
+  /** A field part calls this while it is on screen, so a refusal on a field with no control is told apart. */
+  registerField: (name: AddressFieldName) => () => void;
+  close: () => void;
+  countryChoice: AccountAddressFormCountryChoice;
+}>;
+/** The form's draft, errors and state, for any part composed under `AccountAddressFormRoot`. */
+export declare function useAccountAddressForm(): AccountAddressFormContextValue;
+//#endregion
+//# sourceMappingURL=account-address-form-context.d.ts.map

package/dist/matter/account-address-book/account-address-form-context.js

@@ -0,0 +1,14 @@
+"use client";
+import { createContext, useContext } from "react";
+//#region src/matter/account-address-book/account-address-form-context.ts
+const AccountAddressFormContext = createContext(null);
+/** The form's draft, errors and state, for any part composed under `AccountAddressFormRoot`. */
+function useAccountAddressForm() {
+	const value = useContext(AccountAddressFormContext);
+	if (!value) throw new Error("Address form parts must be used inside an AccountAddressFormRoot.");
+	return value;
+}
+//#endregion
+export { AccountAddressFormContext, useAccountAddressForm };
+
+//# sourceMappingURL=account-address-form-context.js.map

package/dist/matter/account-address-book/account-address-form-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-address-form-context.js","names":[],"sources":["../../../src/matter/account-address-book/account-address-form-context.ts"],"sourcesContent":["'use client';\n\nimport { createContext, useContext } from 'react';\nimport type { AddressFieldError, AddressFieldName, CountryRules } from '../../sdk/address/types.js';\nimport type { MessageId } from '../../sdk/i18n/client.js';\n\nexport type EditableField = Exclude<AddressFieldName, 'name'>;\n\n/** The draft: the address fields the form edits. `name` is not edited, as `CustomerAddress` has none. */\nexport type AccountAddressFormDraft = Readonly<Partial<Record<EditableField, string>>>;\n\nexport type AccountAddressFormFieldErrors = Readonly<Partial<Record<AddressFieldName, AddressFieldError>>>;\n\n/** What a refusal that names no field on screen says. */\nexport type AccountAddressFormErrorKind =\n  | 'unrenderedField'\n  | 'notFound'\n  | 'unauthorized'\n  | 'saveFailed'\n  | 'rulesFailed'\n  | 'countrySwitchFailed'\n  | 'unsupportedCountry';\n\n/** What the last applied switch did not carry, for AccountAddressCountryNotice. */\nexport type AccountAddressCountryChange = Readonly<{\n  /** ISO 3166-1 alpha-3. */\n  from: string;\n  to: string;\n  /** In the old country's field order; empty when everything was carried. */\n  notCarried: readonly Readonly<{ field: AddressFieldName; labelId: MessageId }>[];\n}>;\n\n/**\n * The country choice, the only part of the form the country control and the notice touch. The\n * values set aside on a switch stay with the draft's owner, behind `change`.\n */\nexport type AccountAddressFormCountryChoice = Readonly<{\n  /** AddressCountryControl reports its shipping countries; `null` means unknown. Returns the withdrawal. */\n  offer: (countries: readonly string[] | null) => () => void;\n  /** The country the control shows as chosen: a switch in flight, else `country`. */\n  selected: string;\n  /** Starts a switch in add mode. Ignored in edit mode. `change(country)` cancels a switch in flight. */\n  change: (to: string) => void;\n  /** `null` until a switch applies, and always in edit mode. */\n  lastChange: AccountAddressCountryChange | null;\n}>;\n\nexport type AccountAddressFormContextValue = Readonly<{\n  mode: 'add' | 'edit';\n  /** ISO 3166-1 alpha-3, upper case. Empty while a new address's country is not resolved yet. */\n  country: string;\n  /** `null` until the country's rules loaded. */\n  rules: CountryRules | null;\n  draft: AccountAddressFormDraft;\n  fieldErrors: AccountAddressFormFieldErrors;\n  formError: AccountAddressFormErrorKind | null;\n  pending: boolean;\n  setField: (name: EditableField, value: string) => void;\n  /** A field part calls this while it is on screen, so a refusal on a field with no control is told apart. */\n  registerField: (name: AddressFieldName) => () => void;\n  close: () => void;\n  countryChoice: AccountAddressFormCountryChoice;\n}>;\n\nexport const AccountAddressFormContext = createContext<AccountAddressFormContextValue | null>(null);\n\n/** The form's draft, errors and state, for any part composed under `AccountAddressFormRoot`. */\nexport function useAccountAddressForm(): AccountAddressFormContextValue {\n  const value = useContext(AccountAddressFormContext);\n  if (!value) {\n    throw new Error('Address form parts must be used inside an AccountAddressFormRoot.');\n  }\n  return value;\n}\n"],"mappings":";;;AAgEA,MAAa,4BAA4B,cAAqD,IAAI;;AAGlG,SAAgB,wBAAwD;CACtE,MAAM,QAAQ,WAAW,yBAAyB;CAClD,IAAI,CAAC,OACH,MAAM,IAAI,MAAM,mEAAmE;CAErF,OAAO;AACT"}

package/dist/matter/account-address-book/account-address-form.d.ts

@@ -0,0 +1,85 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { PageRef } from "../../sdk/navigation/types.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/matter/account-address-book/account-address-form.d.ts
+/**
+ * The form that adds an address and corrects a saved one (specs/sfs-3441-address-book-form.md, RFC
+ * REQ-02 and REQ-03). The Root renders `FormRoot` and registers one fieldset with it, under the
+ * `accountAddress` namespace: react-hook-form holds the draft and knows what is dirty, and the
+ * fieldset owns the field errors, the form-level error, the status message and the save. It holds no
+ * country rule: the fields come from `addressFields`, the verdict from `validateAddress`, and the
+ * writes go through `$actions.address`.
+ */
+export type AccountAddressFormRootProps = ComponentPropsWithRef<'form'> & {
+  /**
+   * ISO 3166-1 alpha-3 country a new address prefers: taken when the store ships there or its list
+   * is unknown. A blank value falls back to `BRA`.
+   */
+  defaultCountry?: string;
+  /** Toast after an address is added. A blank value falls back to the catalog copy. */
+  addedMessage?: string;
+  /** Toast after an address is saved. A blank value falls back to the catalog copy. */
+  savedMessage?: string;
+  /** Announced when a save is blocked. A blank value falls back to the catalog copy. */
+  blockedMessage?: string;
+  /** Where leaving the form goes when it stands on its own page. A page reference, or a site-relative string. A blank value falls back to the address page. */
+  returnHref?: PageRef | string;
+  /** Injected by the compiler from `actions: { address: [...] }`; the address write surface. */
+  $actions?: ComponentActions;
+};
+/** `className` goes on every field's wrapper. */
+export type AccountAddressFormFieldsProps = Readonly<{
+  className?: string;
+}>;
+export type AccountAddressFormLabelProps = Readonly<{
+  /** The field's label. A blank value falls back to the catalog copy. */
+  label?: string;
+  className?: string;
+}>;
+export type AccountAddressFormErrorProps = ComponentPropsWithRef<'div'> & {
+  /** Each message below falls back to the catalog copy when blank. */
+  unrenderedFieldMessage?: string;
+  notFoundMessage?: string;
+  unauthorizedMessage?: string;
+  saveFailedMessage?: string;
+  rulesFailedMessage?: string;
+  countrySwitchFailedMessage?: string;
+  unsupportedCountryMessage?: string;
+};
+export type AccountAddressFormButtonProps = Omit<ComponentPropsWithRef<'button'>, 'type'> & {
+  /** The button's text. A blank value falls back to the catalog copy. */
+  label?: string;
+};
+export declare function AccountAddressFormRoot({ defaultCountry, addedMessage, savedMessage, blockedMessage, returnHref, $actions, className, children, ...props }: AccountAddressFormRootProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AccountAddressFormRecipientName({ label, className }: AccountAddressFormLabelProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AccountAddressFormReference({ label, className }: AccountAddressFormLabelProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * One field per descriptor the country's rules give for the draft, in the order the country's form lists them.
+ * A complete postal code fills the empty state, city, neighborhood and street the shopper has not typed;
+ * the fill is announced once.
+ */
+export declare function AccountAddressFormFields({ className }: AccountAddressFormFieldsProps): import("react/jsx-runtime").JSX.Element[] | null;
+export declare function AccountAddressFormError({ unrenderedFieldMessage, notFoundMessage, unauthorizedMessage, saveFailedMessage, rulesFailedMessage, countrySwitchFailedMessage, unsupportedCountryMessage, className, ...props }: AccountAddressFormErrorProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AccountAddressFormSubmit({ label, className, children, ...props }: AccountAddressFormButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function AccountAddressFormCancel({ label, className, children, onClick, ...props }: AccountAddressFormButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare const AccountAddressFormRootDefinition: ComponentDefinition<AccountAddressFormRootProps>;
+export declare const AccountAddressFormRecipientNameDefinition: ComponentDefinition<Readonly<{
+  /** The field's label. A blank value falls back to the catalog copy. */
+  label?: string;
+  className?: string;
+}>>;
+export declare const AccountAddressFormFieldsDefinition: ComponentDefinition<Readonly<{
+  className?: string;
+}>>;
+export declare const AccountAddressFormReferenceDefinition: ComponentDefinition<Readonly<{
+  /** The field's label. A blank value falls back to the catalog copy. */
+  label?: string;
+  className?: string;
+}>>;
+export declare const AccountAddressFormErrorDefinition: ComponentDefinition<AccountAddressFormErrorProps>;
+export declare const AccountAddressFormSubmitDefinition: ComponentDefinition<AccountAddressFormButtonProps>;
+export declare const AccountAddressFormCancelDefinition: ComponentDefinition<AccountAddressFormButtonProps>;
+//#endregion
+//# sourceMappingURL=account-address-form.d.ts.map