@vtex/faststore 0.0.1

package/dist/matter/region/region.d.ts

@@ -0,0 +1,211 @@
+import { ContentValue } from "../../core/dist/define-content-type.js";
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { RegionEntity } from "../../sdk/region/operations.js";
+import { RegionUserError } from "../../sdk/region/region-operations.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/matter/region/region.d.ts
+export declare const RegionTriggerContent: {
+  readonly id: "region-trigger";
+  readonly title: "Region Trigger";
+  readonly description: "Copy for the control that opens the region modal.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly unsetLabel: {
+        readonly type: "string";
+        readonly title: "Label when no region is set";
+      };
+      readonly ariaLabel: {
+        readonly type: "string";
+        readonly title: "Accessible label";
+      };
+    };
+  };
+};
+export declare const RegionSubmitContent: {
+  readonly id: "region-submit";
+  readonly title: "Region Submit";
+  readonly description: "Copy for the region submit control.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Button label";
+      };
+      readonly pendingLabel: {
+        readonly type: "string";
+        readonly title: "Pending label";
+      };
+    };
+  };
+};
+export declare const RegionUnknownLinkContent: {
+  readonly id: "region-unknown-link";
+  readonly title: "Region \"I don't know my postal code\" Link";
+  readonly description: "Copy and destination for the postal-code lookup link. Absent href omits the link.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly text: {
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly title: "Link text";
+      };
+      readonly href: {
+        readonly type: "string";
+        readonly title: "Destination";
+        readonly format: "uri-reference";
+        readonly pattern: "^(?:https?://.*|mailto:.+|tel:.+|/(?:[^/].*)?)$";
+      };
+    };
+  };
+};
+export declare const RegionErrorContent: {
+  readonly id: "region-error";
+  readonly title: "Region Error";
+  readonly description: "Fallback message shown when a write fails without a server message.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly genericMessage: {
+        readonly type: "string";
+        readonly title: "Generic failure message";
+      };
+    };
+  };
+};
+export type RegionContextValue = Readonly<{
+  /** Persisted postal code, formatted; null until a region is set. */
+  postalCode: string | null;
+  /** Persisted city; null when the contract does not resolve one. */
+  city: string | null;
+  /** The reactive read has not resolved and no cached value is available. */
+  loading: boolean;
+  /** The modal's draft value, masked as the shopper typed it. */
+  draft: string;
+  setDraft: (value: string) => void;
+  /** A write is in flight. */
+  pending: boolean;
+  /** Errors from the latest write; empty when there are none. */
+  errors: readonly RegionUserError[];
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  /** Dispatches setPostalCode with the current draft. No-op while pending. */
+  submit: () => void;
+}>;
+export declare const RegionContext: React.Context<RegionContextValue>;
+/**
+ * Read the active region and the modal's write state from the nearest `RegionRoot`. Throws when
+ * called outside a `RegionRoot` subtree, mirroring `useSession()` and `useCart()`: a misplaced part
+ * is a composition bug the author should see immediately, not a silent degrade to "no region". The
+ * compiler catches the same mistake earlier through `requiresContext: 'region'` (ADR-0009).
+ */
+export declare function useRegion(): RegionContextValue;
+export type RegionRootProps = ComponentPropsWithRef<'div'> & {
+  /**
+   * Region entity slice forwarded by the reactive runtime (`ReactiveDataProvider`) — the value of the
+   * `region` top-level field on `RegionData on Query`, not the wrapping `{ region: … }` shape.
+   * Receives `null` while the entity has not resolved and when no region is set.
+   */
+  $data?: RegionEntity | null;
+  /** Injected by the compiler from `actions: { region: ['setPostalCode'] }`; the region write surface. */
+  $actions?: ComponentActions;
+  children?: ReactNode;
+};
+export type RegionTriggerProps = ComponentPropsWithRef<'button'> & {
+  /** Shown when no region is set. */
+  unsetLabel?: string;
+  /** Merchant-authored copy; wins over the props when present. */
+  $content?: ContentValue<typeof RegionTriggerContent>;
+};
+/** Children are omitted: what this renders is the resolved region, never authored content. */
+export type RegionValueProps = Omit<ComponentPropsWithRef<'span'>, 'children'>;
+export type RegionLoadingProps = ComponentPropsWithRef<'div'>;
+export type RegionModalControllerProps = {
+  children?: ReactNode;
+};
+export type RegionFormProps = ComponentPropsWithRef<'form'>;
+export type RegionPostalCodeControlProps = {
+  className?: string;
+  /** Mask template forwarded to `PostalCodeField`; defaults to that particle's BR CEP mask. */
+  mask?: string;
+  label?: string;
+  placeholder?: string;
+  /** The field's own incomplete-value message. Server rejections surface through `RegionError`. */
+  errorMessage?: string;
+};
+export type RegionSubmitProps = ComponentPropsWithRef<'button'> & {
+  label?: string;
+  pendingLabel?: string;
+  /** Merchant-authored copy; wins over the props when present. */
+  $content?: ContentValue<typeof RegionSubmitContent>;
+};
+/** Children are omitted: what this renders is the write's own error, never authored content. */
+export type RegionErrorProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** Merchant-authored fallback copy; wins over the prop when present. */
+  $content?: ContentValue<typeof RegionErrorContent>;
+};
+export type RegionUnknownLinkProps = ComponentPropsWithRef<'a'> & {
+  /** Merchant-authored text and destination; each wins over its prop when present. */
+  $content?: ContentValue<typeof RegionUnknownLinkContent>;
+};
+export declare const RegionRootDefinition: ComponentDefinition<RegionRootProps>;
+export declare const RegionTriggerDefinition: ComponentDefinition<RegionTriggerProps>;
+export declare const RegionValueDefinition: ComponentDefinition<RegionValueProps>;
+export declare const RegionLoadingDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>;
+export declare const RegionModalControllerDefinition: ComponentDefinition<RegionModalControllerProps>;
+export declare const RegionFormDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>>;
+export declare const RegionPostalCodeControlDefinition: ComponentDefinition<RegionPostalCodeControlProps>;
+export declare const RegionSubmitDefinition: ComponentDefinition<RegionSubmitProps>;
+export declare const RegionErrorDefinition: ComponentDefinition<RegionErrorProps>;
+export declare const RegionUnknownLinkDefinition: ComponentDefinition<RegionUnknownLinkProps>;
+/**
+ * Reads the active region reactively and publishes it, the modal's draft, and the write state as
+ * `region` context.
+ *
+ * The resolved value is never copied into state: `RegionValue` renders only what the fragment
+ * resolves, and a successful write updates the display solely by the mutation payload normalizing
+ * into the Apollo cache (Decision 5). That is why a rejected write needs no rollback and cannot
+ * leave the header showing a postal code the server refused.
+ */
+export declare function RegionRoot({ $data: $dataProp, $actions, className, children, ...props }: RegionRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function RegionTrigger({ unsetLabel, $content, className, children, ...props }: RegionTriggerProps): import("react/jsx-runtime").JSX.Element;
+export declare function RegionValue({ className, ...props }: RegionValueProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function RegionLoading({ className, children, ...props }: RegionLoadingProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Makes the wrapped `DialogRoot` controlled by the region state. Mirrors
+ * `ShippingAddressSavedAddressDrawerController`'s `cloneElement` mechanism; expects a single
+ * `DialogRoot` child. Dismissal is never blocked — the Phase 1 modal is always dismissible.
+ */
+export declare function RegionModalController({ children }: RegionModalControllerProps): ReactNode;
+/**
+ * Gives the field and the submit a form owner, so Enter in the postal code submits the way it does
+ * in every other short form in the repo. Mirrors `ShippingSimulatorForm`: the form's only job is to
+ * route native submission to the context's `submit()`.
+ */
+export declare function RegionForm({ className, children, ...props }: RegionFormProps): import("react/jsx-runtime").JSX.Element;
+export declare function RegionPostalCodeControl({ className, mask, label, placeholder, errorMessage }: RegionPostalCodeControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function RegionSubmit({ label, pendingLabel, $content, className, children, ...props }: RegionSubmitProps): import("react/jsx-runtime").JSX.Element;
+export declare function RegionError({ $content, className, ...props }: RegionErrorProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function RegionUnknownLink({ $content, className, children, href, rel, ...props }: RegionUnknownLinkProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const Region: {
+  Root: typeof RegionRoot;
+  Trigger: typeof RegionTrigger;
+  Value: typeof RegionValue;
+  Loading: typeof RegionLoading;
+  ModalController: typeof RegionModalController;
+  Form: typeof RegionForm;
+  PostalCodeControl: typeof RegionPostalCodeControl;
+  Submit: typeof RegionSubmit;
+  Error: typeof RegionError;
+  UnknownLink: typeof RegionUnknownLink;
+};
+//#endregion
+//# sourceMappingURL=region.d.ts.map