@vtex/faststore 0.0.4 → 0.0.6

package/dist/matter/client-profile/client-profile.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-profile.js","names":[],"sources":["../../../src/matter/client-profile/client-profile.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useContext, useMemo, useRef, useState } from 'react';\nimport type { PhoneCountry } from '../../particles/phone-field/phone-field.js';\nimport { PhoneField, toE164, validatePhoneNumber } from '../../particles/phone-field/phone-field.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * The `client-profile` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP, not\n * per field). The shopper-profile fields recorded on the cart's `clientProfileData` live on the User\n * Identity `ClientProfile` entity — a SIBLING of `Cart`, not nested under it. They are read through\n * `Query.clientProfile` and written through the shared `$actions.identity.clientProfileUpdate`\n * action, which performs a partial write that leaves the fields it is not given untouched.\n *\n * This matter wires only `phone`: a `ClientProfilePhoneControl` that composes the reusable,\n * business-agnostic `PhoneField` particle (reused later in MyAccount / extensions; the binding here\n * owns the data source and persistence). Room is kept for future profile Controls on the same Root.\n * Reads follow the colocated-fragment Root pattern (ADR-0006, fetchStrategy 'reactive'), mirroring\n * `EmailIdentificationControl`; writes flow through `$actions.identity` (ADR-0010). The write is\n * pessimistic (awaits the mutation) and is dispatched on blur — form-bound saving via the profile-form\n * CTA is a follow-up, not implemented here.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the ClientProfile sibling entity (ADR-0011)\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientProfilePhoneData on Query {\n    clientProfile {\n      __typename\n      id\n      phone\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Raw data shape of the section fragment\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the `ClientProfile` sibling entity. */\nexport type ClientProfileData = {\n  clientProfile?: {\n    phone?: string | null;\n  } | null;\n} | null;\n\n// ---------------------------------------------------------------------------\n// Context — the Root publishes the seeded profile values to its Controls\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileContextValue = Readonly<{\n  /** Current value of each profile field, seeded from the ClientProfile entity (null → empty). */\n  phone: string;\n}>;\n\nconst CLIENT_PROFILE_UNSET = Symbol('ClientProfileContextUnset');\n\nconst ClientProfileContext = createContext<ClientProfileContextValue | typeof CLIENT_PROFILE_UNSET>(\n  CLIENT_PROFILE_UNSET,\n);\n\nfunction useClientProfileContext(): ClientProfileContextValue {\n  const ctx = useContext(ClientProfileContext);\n  if (ctx === CLIENT_PROFILE_UNSET) {\n    throw new Error('A client-profile Control must be used inside a ClientProfileRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Root\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileRootProps = {\n  /** ClientProfile entity slice forwarded by the reactive runtime (value of the section fragment). */\n  $data?: ClientProfileData;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport const ClientProfileRootDefinition = defineComponent<ClientProfileRootProps>({\n  name: 'ClientProfileRoot',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  providesContext: 'client-profile',\n  requiresContext: 'session',\n  editor: { label: 'Client Profile Root', category: 'identity' },\n  schema: {},\n  guideline:\n    'Binding provider for the shopper-profile section; reads the profile fields (today: phone) from the ClientProfile entity (Query.clientProfile) and exposes them to its Controls. Writes flow through $actions.identity.clientProfileUpdate. Must be inside SessionRoot. Wrap a ClientProfilePhoneControl.',\n});\n\n/**\n * Renders the client-profile section Root: reads `$data` (the `ClientProfile` sibling entity), seeds\n * the profile values from the colocated fragment, and publishes a section context. It also reads\n * `useSession()` — which enforces the `SessionRoot` ancestor. Writes are owned by the Control's\n * `$actions.identity` (ADR-0010); the Root only supplies the pre-fill.\n */\nexport function ClientProfileRoot({ $data: $dataProp, className, children }: ClientProfileRootProps) {\n  const $data = useDataOverride($dataProp);\n  // Reads identification state and, as a side effect, throws when rendered outside <SessionRoot>.\n  useSession();\n\n  const phone = $data?.clientProfile?.phone ?? '';\n\n  const contextValue = useMemo<ClientProfileContextValue>(() => ({ phone }), [phone]);\n\n  return (\n    <ClientProfileContext value={contextValue}>\n      <div className={className} data-fs-client-profile-root=\"\">\n        {children}\n      </div>\n    </ClientProfileContext>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Phone Control\n// ---------------------------------------------------------------------------\n\ntype PhoneFieldRequirement = 'mandatory' | 'optional' | 'hidden';\n\nexport type ClientProfilePhoneControlProps = {\n  /** Visible field label. */\n  label?: string;\n  /** Selects the phone mask and validation rule. */\n  country?: PhoneCountry;\n  /** Controls field visibility and required validation. */\n  requirement?: PhoneFieldRequirement;\n  /** Error string shown when the input format is invalid. */\n  errorInvalid?: string;\n  /** Error string shown when the mandatory field is left empty. */\n  errorRequired?: string;\n  className?: string;\n  /** Injected by the compiler from `actions: { identity: ['clientProfileUpdate'] }`; the write surface. */\n  $actions?: ComponentActions;\n};\n\nexport const ClientProfilePhoneControlDefinition = defineComponent<ClientProfilePhoneControlProps>({\n  name: 'ClientProfilePhoneControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfilePhoneControl,\n  requiresContext: 'client-profile',\n  actions: { identity: ['clientProfileUpdate'] },\n  editor: { label: 'Client Profile Phone Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', default: 'Phone', label: 'Label' },\n    country: { type: 'string', default: 'US', label: 'Country (US or BR)' },\n    requirement: { type: 'string', default: 'mandatory', label: 'Requirement' },\n    errorInvalid: { type: 'string', default: 'Invalid phone number', label: 'Invalid error message' },\n    errorRequired: { type: 'string', default: 'Phone number is required', label: 'Required error message' },\n  },\n  guideline:\n    'The bound phone field; must be a descendant of ClientProfileRoot. Reads the saved phone from the ClientProfile entity and persists it on blur via $actions.identity.clientProfileUpdate({ phone }). Composes the reusable PhoneField particle.',\n});\n\n/**\n * Renders the bound phone field by composing the reusable `PhoneField` particle. Reads the saved\n * phone from the section context, and on a **changed** value persists only `phone` — normalized to\n * E.164 — through `$actions.identity.clientProfileUpdate({ phone })` on blur (pessimistic,\n * mirroring `EmailIdentificationControl`). While the write is in flight the field is disabled and\n * `data-fs-client-profile-phone-pending` is present so a checkout-CTA guard can block. When the\n * session reports `canEditData: false` the field renders disabled with\n * `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline.\n */\nexport function ClientProfilePhoneControl({\n  label = 'Phone',\n  country = 'US',\n  requirement = 'mandatory',\n  errorInvalid = 'Invalid phone number',\n  errorRequired = 'Phone number is required',\n  className,\n  $actions: $actionsProp,\n}: Readonly<ClientProfilePhoneControlProps>) {\n  const $actions = useActionsOverride($actionsProp);\n  const { phone: savedPhone } = useClientProfileContext();\n  // VTEX refuses profile edits for an identified-but-unauthenticated claimed profile; render the\n  // field read-only instead of accepting a write that is doomed server-side (mirrors\n  // EmailIdentificationControl).\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n  const [draft, setDraft] = useState(savedPhone);\n  const [pending, setPending] = useState(false);\n  const [serverError, setServerError] = useState<string | null>(null);\n\n  // Re-seed the local draft when the saved value changes (e.g. cache update after a write, or a\n  // logged-in shopper's profile resolving). Like the email control's pre-fill sync, this overwrites\n  // any in-progress draft — the profile is the source of truth when it changes.\n  const prevSavedRef = useRef(savedPhone);\n  if (prevSavedRef.current !== savedPhone) {\n    // react-doctor-disable-next-line no-ref-current-in-render -- paired with the setDraft call right below, both replay together\n    prevSavedRef.current = savedPhone;\n    setDraft(savedPhone);\n  }\n\n  function handleValueChange(next: string) {\n    setDraft(next);\n    if (serverError) setServerError(null);\n  }\n\n  async function handleBlur() {\n    const clientProfileUpdate = $actions?.identity?.clientProfileUpdate;\n    if (!clientProfileUpdate) return;\n    // Untouched → nothing to persist.\n    if (draft === savedPhone) return;\n    // Client-side invalid → skip the write and let the PhoneField's inline error stand; don't\n    // rely on server userErrors for a value the mask/validator already rejects. Mirrors the\n    // validity the PhoneField particle computes on blur (mandatory-empty or bad format).\n    const isEmpty = !draft.trim();\n    if (requirement === 'mandatory' && isEmpty) return;\n    if (!isEmpty && !validatePhoneNumber(draft, country)) return;\n    const phone = isEmpty ? '' : toE164(draft, country);\n    // Unchanged after normalization (e.g. the saved \"+12015551234\" re-typed as \"2015551234\") →\n    // nothing to persist either.\n    if (phone === savedPhone) return;\n\n    setPending(true);\n    setServerError(null);\n    try {\n      const errors = (await clientProfileUpdate({ phone })) ?? [];\n      if (errors.length > 0) setServerError(errors[0]?.message ?? null);\n    } finally {\n      setPending(false);\n    }\n  }\n\n  return (\n    <div\n      className={className}\n      data-fs-client-profile-phone-control=\"\"\n      {...(pending ? { 'data-fs-client-profile-phone-pending': '' } : {})}\n      {...(readOnly ? { 'data-fs-client-profile-phone-readonly': '' } : {})}\n    >\n      <PhoneField\n        label={label}\n        country={country}\n        requirement={requirement}\n        errorInvalid={errorInvalid}\n        errorRequired={errorRequired}\n        value={draft}\n        onValueChange={handleValueChange}\n        onBlur={handleBlur}\n        isDisabled={pending || readOnly}\n        invalid={serverError != null || undefined}\n        error={serverError ?? undefined}\n      />\n    </div>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const ClientProfile = {\n  Root: ClientProfileRoot,\n  PhoneControl: ClientProfilePhoneControl,\n};\n"],"mappings":"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"}
+{"version":3,"file":"client-profile.js","names":[],"sources":["../../../src/matter/client-profile/client-profile.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useContext, useMemo, useRef, useState } from 'react';\nimport type { PhoneCountry } from '../../particles/phone-field/phone-field.js';\nimport { PhoneField, toE164, validatePhoneNumber } from '../../particles/phone-field/phone-field.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * The `client-profile` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP, not\n * per field). The shopper-profile fields recorded on the cart's `clientProfileData` live on the User\n * Identity `ClientProfile` entity — a SIBLING of `Cart`, not nested under it. They are read through\n * `Query.clientProfile` and written through the shared `$actions.identity.clientProfileUpdate`\n * action, which performs a partial write that leaves the fields it is not given untouched.\n *\n * This matter wires only `phone`: a `ClientProfilePhoneControl` that composes the reusable,\n * business-agnostic `PhoneField` particle (reused later in MyAccount / extensions; the binding here\n * owns the data source and persistence). Room is kept for future profile Controls on the same Root.\n * Reads follow the colocated-fragment Root pattern (ADR-0006, fetchStrategy 'reactive'), mirroring\n * `EmailIdentificationControl`; writes flow through `$actions.identity` (ADR-0010). The write is\n * pessimistic (awaits the mutation) and is dispatched on blur — form-bound saving via the profile-form\n * CTA is a follow-up, not implemented here.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the ClientProfile sibling entity (ADR-0011)\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientProfilePhoneData on Query {\n    clientProfile {\n      __typename\n      id\n      phone\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Raw data shape of the section fragment\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the `ClientProfile` sibling entity, unwrapped. */\nexport type ClientProfileData = {\n  phone?: string | null;\n} | null;\n\n// ---------------------------------------------------------------------------\n// Context — the Root publishes the seeded profile values to its Controls\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileContextValue = Readonly<{\n  /** Current value of each profile field, seeded from the ClientProfile entity (null → empty). */\n  phone: string;\n}>;\n\nconst CLIENT_PROFILE_UNSET = Symbol('ClientProfileContextUnset');\n\nconst ClientProfileContext = createContext<ClientProfileContextValue | typeof CLIENT_PROFILE_UNSET>(\n  CLIENT_PROFILE_UNSET,\n);\n\nfunction useClientProfileContext(): ClientProfileContextValue {\n  const ctx = useContext(ClientProfileContext);\n  if (ctx === CLIENT_PROFILE_UNSET) {\n    throw new Error('A client-profile Control must be used inside a ClientProfileRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Root\n// ---------------------------------------------------------------------------\n\nexport type ClientProfileRootProps = {\n  /** ClientProfile entity slice forwarded by the reactive runtime (value of the section fragment). */\n  $data?: ClientProfileData;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport const ClientProfileRootDefinition = defineComponent<ClientProfileRootProps>({\n  name: 'ClientProfileRoot',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfileRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  providesContext: 'client-profile',\n  requiresContext: 'session',\n  editor: { label: 'Client Profile Root', category: 'identity' },\n  schema: {},\n  guideline:\n    'Binding provider for the shopper-profile section; reads the profile fields (today: phone) from the ClientProfile entity (Query.clientProfile) and exposes them to its Controls. Writes flow through $actions.identity.clientProfileUpdate. Must be inside SessionRoot. Wrap a ClientProfilePhoneControl.',\n});\n\n/**\n * Renders the client-profile section Root: reads `$data` (the `ClientProfile` sibling entity), seeds\n * the profile values from the colocated fragment, and publishes a section context. It also reads\n * `useSession()` — which enforces the `SessionRoot` ancestor. Writes are owned by the Control's\n * `$actions.identity` (ADR-0010); the Root only supplies the pre-fill.\n */\nexport function ClientProfileRoot({ $data: $dataProp, className, children }: ClientProfileRootProps) {\n  const $data = useDataOverride($dataProp);\n  // Reads identification state and, as a side effect, throws when rendered outside <SessionRoot>.\n  useSession();\n\n  const phone = $data?.phone ?? '';\n\n  const contextValue = useMemo<ClientProfileContextValue>(() => ({ phone }), [phone]);\n\n  return (\n    <ClientProfileContext value={contextValue}>\n      <div className={className} data-fs-client-profile-root=\"\">\n        {children}\n      </div>\n    </ClientProfileContext>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Phone Control\n// ---------------------------------------------------------------------------\n\ntype PhoneFieldRequirement = 'mandatory' | 'optional';\n\nexport type ClientProfilePhoneControlProps = {\n  /** Visible field label. */\n  label?: string;\n  /** Selects the phone mask and validation rule. */\n  country?: PhoneCountry;\n  /** Controls required validation. */\n  requirement?: PhoneFieldRequirement;\n  /** Error string shown when the input format is invalid. */\n  errorInvalid?: string;\n  /** Error string shown when the mandatory field is left empty. */\n  errorRequired?: string;\n  className?: string;\n  /** Injected by the compiler from `actions: { identity: ['clientProfileUpdate'] }`; the write surface. */\n  $actions?: ComponentActions;\n};\n\nexport const ClientProfilePhoneControlDefinition = defineComponent<ClientProfilePhoneControlProps>({\n  name: 'ClientProfilePhoneControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientProfilePhoneControl,\n  requiresContext: 'client-profile',\n  actions: { identity: ['clientProfileUpdate'] },\n  editor: { label: 'Client Profile Phone Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', default: 'Phone', label: 'Label' },\n    country: { type: 'string', default: 'US', label: 'Country (US or BR)' },\n    requirement: { type: ['mandatory', 'optional'] as const, default: 'mandatory', label: 'Requirement' },\n    errorInvalid: { type: 'string', default: 'Invalid phone number', label: 'Invalid error message' },\n    errorRequired: { type: 'string', default: 'Phone number is required', label: 'Required error message' },\n  },\n  guideline:\n    'The bound phone field; must be a descendant of ClientProfileRoot. Reads the saved phone from the ClientProfile entity and persists it on blur via $actions.identity.clientProfileUpdate({ phone }). Composes the reusable PhoneField particle.',\n});\n\n/**\n * Renders the bound phone field by composing the reusable `PhoneField` particle. Reads the saved\n * phone from the section context, and on a **changed** value persists only `phone` — normalized to\n * E.164 — through `$actions.identity.clientProfileUpdate({ phone })` on blur (pessimistic,\n * mirroring `EmailIdentificationControl`). While the write is in flight the field is disabled and\n * `data-fs-client-profile-phone-pending` is present so a checkout-CTA guard can block. When the\n * session reports `canEditData: false` the field renders disabled with\n * `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline.\n */\nexport function ClientProfilePhoneControl({\n  label = 'Phone',\n  country = 'US',\n  requirement = 'mandatory',\n  errorInvalid = 'Invalid phone number',\n  errorRequired = 'Phone number is required',\n  className,\n  $actions: $actionsProp,\n}: Readonly<ClientProfilePhoneControlProps>) {\n  const $actions = useActionsOverride($actionsProp);\n  const { phone: savedPhone } = useClientProfileContext();\n  // VTEX refuses profile edits for an identified-but-unauthenticated claimed profile; render the\n  // field read-only instead of accepting a write that is doomed server-side (mirrors\n  // EmailIdentificationControl).\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n  const [draft, setDraft] = useState(savedPhone);\n  // A plain ref, not state: set only from handlers (never during render), and read only inside the\n  // render-body re-seed comparison below — nothing here needs its own re-render, since every call\n  // site that sets it already triggers one via a sibling state setter in the same tick.\n  const dirtyRef = useRef(false);\n  const [pending, setPending] = useState(false);\n  const [serverError, setServerError] = useState<string | null>(null);\n\n  // Re-seed the local draft when the saved value changes (e.g. cache update after a write, or a\n  // logged-in shopper's profile resolving) — but never while an edit is in progress. A render-phase\n  // compare-and-set, not a ref: the comparison baseline lives in state, and the compare-and-set runs\n  // during render, so a render React abandons without committing — a suspended transition, a\n  // Suspense retry — never leaves a stale baseline behind the way a ref write would, and a reactive\n  // fetch landing mid-keystroke still can't silently replace what the shopper just typed.\n  const [prevSaved, setPrevSaved] = useState(savedPhone);\n  if (prevSaved !== savedPhone) {\n    setPrevSaved(savedPhone);\n    if (!dirtyRef.current) setDraft(savedPhone);\n  }\n\n  function handleValueChange(next: string) {\n    setDraft(next);\n    dirtyRef.current = true;\n    if (serverError) setServerError(null);\n  }\n\n  async function handleBlur() {\n    const clientProfileUpdate = $actions?.identity?.clientProfileUpdate;\n    if (!clientProfileUpdate) return;\n    // Untouched → nothing to persist.\n    if (draft === savedPhone) return;\n    // Client-side invalid → skip the write and let the PhoneField's inline error stand; don't\n    // rely on server userErrors for a value the mask/validator already rejects. Mirrors the\n    // validity the PhoneField particle computes on blur (mandatory-empty or bad format).\n    const isEmpty = !draft.trim();\n    if (requirement === 'mandatory' && isEmpty) return;\n    if (!isEmpty && !validatePhoneNumber(draft, country)) return;\n    const phone = isEmpty ? '' : toE164(draft, country);\n    // Unchanged after normalization (e.g. the saved \"+12015551234\" re-typed as \"2015551234\") →\n    // nothing to persist either.\n    if (phone === savedPhone) return;\n\n    setPending(true);\n    setServerError(null);\n    try {\n      const errors = (await clientProfileUpdate({ phone })) ?? [];\n      if (errors.length > 0) {\n        setServerError(errors[0]?.message ?? null);\n      } else {\n        // The edit is now committed — clear the guard so a later external change (another tab,\n        // a cache refresh) can re-seed the draft again.\n        dirtyRef.current = false;\n      }\n    } finally {\n      setPending(false);\n    }\n  }\n\n  return (\n    <div\n      className={className}\n      data-fs-client-profile-phone-control=\"\"\n      {...(pending ? { 'data-fs-client-profile-phone-pending': '' } : {})}\n      {...(readOnly ? { 'data-fs-client-profile-phone-readonly': '' } : {})}\n    >\n      <PhoneField\n        label={label}\n        country={country}\n        requirement={requirement}\n        errorInvalid={errorInvalid}\n        errorRequired={errorRequired}\n        value={draft}\n        onValueChange={handleValueChange}\n        onBlur={handleBlur}\n        isDisabled={pending || readOnly}\n        invalid={serverError != null || undefined}\n        error={serverError ?? undefined}\n      />\n    </div>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const ClientProfile = {\n  Root: ClientProfileRoot,\n  PhoneControl: ClientProfilePhoneControl,\n};\n"],"mappings":"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"}

package/dist/matter/client-profile-form/client-profile-fieldset.d.ts

@@ -0,0 +1,119 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { PhoneCountry } from "../../particles/phone-field/phone-field.js";
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/matter/client-profile-form/client-profile-fieldset.d.ts
+/** The `$data` slice forwarded by the reactive runtime — the ClientProfile sibling entity, unwrapped. */
+export type ClientProfileFieldsetData = {
+  firstName?: string | null;
+  lastName?: string | null;
+  phone?: string | null;
+  document?: string | null;
+} | null;
+export type ClientProfileFieldsetProps = {
+  /** Phone mask/validation country, provided to the phone control via context. */
+  country?: PhoneCountry;
+  /** Locale document type; the document control renders only when supported. */
+  documentType?: string;
+  /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */
+  skeletonCount?: number;
+  /** Announced politely while the profile resolves. Blank means no announcement. */
+  loadingLabel?: string;
+  /** Announced politely once the controls mount. Blank means no announcement. */
+  loadedLabel?: string;
+  /** Accessible name of the `<fieldset>` group. Blank means no name is exposed. */
+  groupLabel?: string;
+  className?: string;
+  children?: ReactNode;
+  /** `ClientProfileFieldsetData` slice forwarded by the reactive runtime. */
+  $data?: ClientProfileFieldsetData;
+  /** Compiler-injected; carries `identity.clientProfileUpdate`. */
+  $actions?: ComponentActions;
+};
+type ProfileTextControlProps = {
+  label?: string;
+  placeholder?: string;
+  className?: string;
+  children?: ReactNode;
+};
+export type ClientProfileFirstNameControlProps = ProfileTextControlProps;
+export type ClientProfileLastNameControlProps = ProfileTextControlProps;
+export type ClientProfileFieldsetPhoneControlProps = {
+  label?: string;
+  placeholder?: string;
+  /**
+   * Raises the field to required. The composite owns it; the contract carries no rule (Decision 6),
+   * so here the raise is the whole of the resolution. Unset is no opinion, which leaves the phone
+   * optional.
+   */
+  requirement?: 'mandatory' | 'optional';
+  errorInvalid?: string;
+  errorRequired?: string;
+  className?: string;
+  /** Given, replaces PhoneField's default Field.Label + PhoneFieldInput + Field.Error anatomy. */
+  children?: ReactNode;
+};
+export type ClientProfileDocumentControlProps = {
+  label?: string;
+  placeholder?: string;
+  errorMessage?: string;
+  className?: string;
+  /** Given, replaces DocumentField's default Field.Label + DocumentFieldInput + Field.Error anatomy. */
+  children?: ReactNode;
+};
+export declare const ClientProfileFieldsetDefinition: ComponentDefinition<ClientProfileFieldsetProps>;
+export declare const ClientProfileFirstNameControlDefinition: ComponentDefinition<ProfileTextControlProps>;
+export declare const ClientProfileLastNameControlDefinition: ComponentDefinition<ProfileTextControlProps>;
+export declare const ClientProfileFieldsetPhoneControlDefinition: ComponentDefinition<ClientProfileFieldsetPhoneControlProps>;
+export declare const ClientProfileDocumentControlDefinition: ComponentDefinition<ClientProfileDocumentControlProps>;
+/**
+ * Registers a batched write of the `ClientProfile` entity with the enclosing `FormRoot`
+ * (`registerFieldset`, namespace `clientProfile`) on mount, unconditionally — so this fieldset keeps its
+ * original dispatch slot even while its own query is still resolving. Its children — the seed values and
+ * the field-name registry its controls need — render only once the entity has resolved; until then the
+ * `Fieldset.Root` carries `-pending` and renders `ClientProfileFieldsetSkeleton` (Decision 5).
+ * `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions`/`country`/`documentType`
+ * through a ref, so the registration effect runs exactly once per mount regardless of how often the
+ * parent re-renders.
+ *
+ * "Resolved" is two conditions, because `$data` alone cannot answer it. Under the reactive runtime the
+ * slice is defined from the first render — `useReactiveEntity` hands down `fallbackData` while the cache
+ * read is incomplete — so an empty server answer looks exactly like a resolved one, and the controls
+ * would mount and seed `''` before the shopper's real profile arrives. `useSeedAdoption` re-seeds a
+ * clean field with `defaultValue` on every render, but once the field turns dirty no later seed
+ * ever reaches it again: a shopper who starts typing before the real profile arrives locks that
+ * empty seed in for good, and even a shopper who does not type sees the field flash from `''` to
+ * the real data. `useReactiveDataSettled` supplies the missing half: the page query's own
+ * in-flight state, latched so it only ever goes pending → settled. The `$data === undefined` half still
+ * carries trees with no reactive root above them, where the slice arrives as a plain prop.
+ *
+ * Both ends of that wait are spoken: the fieldset carries `aria-busy` while it lasts and holds a polite
+ * live region that announces `loadingLabel` and then `loadedLabel`. Style the region `sr-only` — it is
+ * text meant for a screen reader, not for the page.
+ */
+export declare function ClientProfileFieldset({ country, documentType, skeletonCount, loadingLabel, loadedLabel, groupLabel, className, children, $data: $dataProp, $actions: $actionsProp }: ClientProfileFieldsetProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ClientProfileFieldset {
+  var Skeleton: typeof ClientProfileFieldsetSkeleton;
+}
+/**
+ * The loading state of the fieldset, rendered in place of the controls until the entity resolves and
+ * declared as the definition's `skeleton`. Purely visual: the wait is spoken by the fieldset's own live
+ * region, so this is hidden from assistive technology rather than announced twice.
+ */
+export declare function ClientProfileFieldsetSkeleton({ count, className, ...props }: ComponentPropsWithRef<'div'> & {
+  count?: number;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileFirstNameControl({ label, placeholder, className, children }: ClientProfileFirstNameControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileLastNameControl({ label, placeholder, className, children }: ClientProfileLastNameControlProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Composes `PhoneField` inside a `FieldBinding`, wrapped in a `data-fs-client-profile-fieldset-field="phone"`
+ * node — the same styling hook attribute the text controls carry on their own `Field.Root`.
+ * `useFieldsetField` runs unconditionally, before `requirement` is even read — there is no suppressed
+ * state for this control to second-guess; `requirement` only ever raises the field to required,
+ * and left unset it raises nothing.
+ */
+export declare function ClientProfileFieldsetPhoneControl({ label, placeholder, requirement, errorInvalid, errorRequired, className, children }: ClientProfileFieldsetPhoneControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfileDocumentControl({ label, placeholder, errorMessage, className, children }: ClientProfileDocumentControlProps): import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+//# sourceMappingURL=client-profile-fieldset.d.ts.map