@vtex/faststore 0.0.5 → 0.0.6

package/dist/matter/payment/use-payment-submit-gate.d.ts

@@ -0,0 +1,111 @@
+import { PaymentUserError } from "../../sdk/payment/operations.js";
+import "./use-payment-method-selection.js";
+//#region src/matter/payment/use-payment-submit-gate.d.ts
+/**
+ * The submit gate (specs/cardholder-document-submit-gate.md, T24 of the Credit Card epic;
+ * docs/features/credit-card/rfc.md § D3, D6). One pure resolver covering the two facts T11's own
+ * deferral asked to ship together: a required-but-missing-or-malformed cardholder document, and a
+ * declined "same as delivery" billing address with nothing persisted yet. `PlaceOrder` (T14) reads the
+ * verdict through `usePaymentSubmitGate()` below and forwards it into `usePlaceOrder`'s (T13)
+ * pre-flight, which refuses on it before `startTransaction` ever opens a transaction the client already
+ * knows it cannot complete.
+ *
+ * **Only the verdict crosses into `sdk/payment/`.** `usePlaceOrder` never learns *why* it refused —
+ * only this opaque `PaymentUserError` — because `sdk/payment/use-place-order.ts` may name no identifier
+ * matching `CARD_FIELD_PATTERN` (`sdk/payment/card-field-pattern.ts`), which includes `document`. Every
+ * fact the gate reads, and the four codes below, live here in `matter/payment/` instead.
+ */
+export declare const PAYMENT_MISSING_DOCUMENT_CODE = "MISSING_CARDHOLDER_DOCUMENT";
+export declare const PAYMENT_INVALID_DOCUMENT_CODE = "INVALID_CARDHOLDER_DOCUMENT";
+export declare const PAYMENT_UNSAVED_BILLING_ADDRESS_CODE = "UNSAVED_BILLING_ADDRESS";
+/**
+ * T192 (issue 948): a document refusal while `CardholderDocument` renders nothing —
+ * a method the card form cannot pay with, or a selection outside the section's `group` — so the
+ * shopper is told to change the method, never to fill a field that is not on screen. The code and its
+ * copy are provisional until Product answers T191's OQ-4; `PlaceOrder` authors the copy
+ * (`unavailableMethodMessage`).
+ */
+export declare const PAYMENT_UNAVAILABLE_METHOD_CODE = "UNAVAILABLE_PAYMENT_METHOD";
+export type PaymentSubmitGateInput = Readonly<{
+  /**
+   * The selected method's `validator.documentRequired`; `false` when no method is resolved yet.
+   * `usePaymentSubmitGate()` resolves the method by `selectedMethodId` against `allMethods` — the
+   * section's *unscoped* list — never the group-scoped `selectedMethod` (finding S1; see that hook's
+   * own doc comment).
+   */
+  documentRequired: boolean;
+  /**
+   * The selected method's `validator.documentDisplayable`, resolved the same unscoped way; `false` when
+   * no method is resolved yet. Gates *both* document checks below (fix pass, findings R1/S4/S5 — one
+   * root cause, three symptoms): `draft.document` is a single fact with a single writer,
+   * `CardholderDocument.onValueChange` (`cardholder-document.tsx:111`). When the selected method's
+   * validator says the document is not displayable, `CardholderDocument` renders nothing for it
+   * (`cardholder-document.tsx:93`) — but nothing clears `draft.document` when that happens: not
+   * `CardholderDocument` unmounting, and not `selectMethod` (`use-payment-method-selection.ts`), which
+   * writes only `path`/`bin` from its input. So `draft.document` can still hold whatever the shopper
+   * typed for a *previously* selected, displayable method. Without this flag, a stale malformed value
+   * would refuse forever with no field left to fix it (R1: a mid-typing, not-yet-valid value survives a
+   * network-detection re-dispatch to a method that never shows the field; S5: any method whose validator
+   * pairs `documentRequired: true` with `documentDisplayable: false` is unconditionally unsatisfiable),
+   * and a stale *valid* value would silently vouch for a document the current method never collected
+   * (S4). Both are the same mistake: treating `draft.document` as meaningful when there is no field on
+   * screen for the shopper to read it from or correct it in. Neither check may run in that state —
+   * matching US-1's fourth criterion ("the gate contributes nothing regardless of what `draft.document`
+   * holds") generalized to every `documentRequired` value, not only `false`. This does not weaken the
+   * spec's own settled "no `CardholderDocument` composed" deadlock (its Risk R1, US-4 — a different R1
+   * than this fix pass's own): that case has `documentDisplayable: true` on the validator (the method
+   * genuinely calls for a document) with the leaf simply missing from the schema, so FR-1 still fires and
+   * still refuses with a console diagnostic.
+   */
+  documentDisplayable: boolean;
+  /**
+   * Whether `CardholderDocument` renders for this selection: `isCardholderDocumentShown(...)` over the
+   * *scoped* `selectedMethod` and `cardPaymentCollapsed` (T192, Decision 3). Never a trigger: the two
+   * unscoped flags above still decide whether the document refuses (S1). It decides only what the
+   * refusal says — the document codes when the field is on screen, `UNAVAILABLE_PAYMENT_METHOD` when it
+   * is not, since a shopper cannot fill a field that is not there (issue 948).
+   */
+  documentFieldShown: boolean;
+  /** `draft.document` — the masked value `CardholderDocument` publishes on change. */
+  document: string | null;
+  /** `draft.billingAddressUnsaved`. */
+  billingAddressUnsaved: boolean | null;
+}>;
+/**
+ * The whole gate: at most one refusal, resolved in a fixed order (FR-7) — the document slot
+ * (document-missing, then document-invalid), then billing-unsaved. Pure — no hooks, no context, no DOM —
+ * so the truth table is unit-testable without rendering, mirroring `card-entry.tsx`'s own exported
+ * `isValidLuhn` / `isExpirationInFuture` convention.
+ *
+ * T192 (Decision 2): the document slot refuses in exactly the states it always did, and `documentFieldShown`
+ * changes only its code — `UNAVAILABLE_PAYMENT_METHOD` instead of a document code while `CardholderDocument`
+ * renders nothing (INV-1, INV-2). The billing check is unchanged.
+ */
+export declare function resolvePaymentSubmitGate({ documentRequired, documentDisplayable, documentFieldShown, document, billingAddressUnsaved }: PaymentSubmitGateInput): PaymentUserError | null;
+/**
+ * Reads `usePayment()` and resolves the gate, memoized on the primitives — never on the `draft` object
+ * itself (NFR-3): `draft`'s identity changes on every card-number keystroke (`setDraftBin`), and this
+ * must not re-run the CPF check-digit test on each one.
+ *
+ * Resolves the validator by looking `persistedMethodId` up against `allMethods` — the section's
+ * *unscoped* fact and *unscoped* method list — rather than the group-scoped `selectedMethod` /
+ * `selectedMethodId` `usePayment()` also exposes (T74, Decision 4/7: the ones `CardholderDocument`/
+ * `CardEntry` render from). Fix pass, finding S1, carried forward by T74's contract split:
+ * `usePlaceOrder`'s own pre-flight (`sdk/payment/use-place-order.ts`) resolves *its* `selectedMethod`
+ * the same unscoped way, off its own independent fragment slice (Decision 2 forbids either hook from
+ * reading the other's module). Resolving off the scoped `selectedMethodId` here would silently degrade
+ * `documentRequired` to `false` whenever the persisted selection's `groupName` sits outside this root's
+ * configured `group` set — no attacker needed, just a store whose real credit- or debit-card group name
+ * differs from the hardcoded defaults (`payment.tsx`'s `DEFAULT_METHOD_GROUP`, now two groups rather than
+ * one) — while `usePlaceOrder` still finds the method by id alone and opens a transaction. Matching
+ * `usePlaceOrder`'s own by-id lookup keeps the two
+ * in agreement for every method actually reachable through this root, which is the one thing
+ * `usePaymentSubmitGate` and `usePlaceOrder` can never be allowed to disagree about.
+ *
+ * T192 (issue 948): the scoped `selectedMethod` and `cardPaymentCollapsed` are read for one fact only,
+ * `documentFieldShown`, through the same `isCardholderDocumentShown` `CardholderDocument` renders by.
+ * It never decides whether the gate refuses — only whether a refusal may name the document.
+ */
+export declare function usePaymentSubmitGate(): PaymentUserError | null;
+//#endregion
+//# sourceMappingURL=use-payment-submit-gate.d.ts.map

package/dist/matter/payment/use-payment-submit-gate.js

@@ -0,0 +1,144 @@
+"use client";
+import { usePayment } from "./payment.js";
+import { isValidDocument } from "../../particles/document-field/document-field.js";
+import { useMemo } from "react";
+//#region src/matter/payment/use-payment-submit-gate.ts
+/**
+* The submit gate (specs/cardholder-document-submit-gate.md, T24 of the Credit Card epic;
+* docs/features/credit-card/rfc.md § D3, D6). One pure resolver covering the two facts T11's own
+* deferral asked to ship together: a required-but-missing-or-malformed cardholder document, and a
+* declined "same as delivery" billing address with nothing persisted yet. `PlaceOrder` (T14) reads the
+* verdict through `usePaymentSubmitGate()` below and forwards it into `usePlaceOrder`'s (T13)
+* pre-flight, which refuses on it before `startTransaction` ever opens a transaction the client already
+* knows it cannot complete.
+*
+* **Only the verdict crosses into `sdk/payment/`.** `usePlaceOrder` never learns *why* it refused —
+* only this opaque `PaymentUserError` — because `sdk/payment/use-place-order.ts` may name no identifier
+* matching `CARD_FIELD_PATTERN` (`sdk/payment/card-field-pattern.ts`), which includes `document`. Every
+* fact the gate reads, and the four codes below, live here in `matter/payment/` instead.
+*/
+const PAYMENT_MISSING_DOCUMENT_CODE = "MISSING_CARDHOLDER_DOCUMENT";
+const PAYMENT_INVALID_DOCUMENT_CODE = "INVALID_CARDHOLDER_DOCUMENT";
+const PAYMENT_UNSAVED_BILLING_ADDRESS_CODE = "UNSAVED_BILLING_ADDRESS";
+/**
+* T192 (issue 948): a document refusal while `CardholderDocument` renders nothing —
+* a method the card form cannot pay with, or a selection outside the section's `group` — so the
+* shopper is told to change the method, never to fill a field that is not on screen. The code and its
+* copy are provisional until Product answers T191's OQ-4; `PlaceOrder` authors the copy
+* (`unavailableMethodMessage`).
+*/
+const PAYMENT_UNAVAILABLE_METHOD_CODE = "UNAVAILABLE_PAYMENT_METHOD";
+const MISSING_DOCUMENT_ERROR = {
+	code: PAYMENT_MISSING_DOCUMENT_CODE,
+	message: "Enter your document before placing the order."
+};
+const INVALID_DOCUMENT_ERROR = {
+	code: PAYMENT_INVALID_DOCUMENT_CODE,
+	message: "Enter a valid document before placing the order."
+};
+const UNSAVED_BILLING_ADDRESS_ERROR = {
+	code: PAYMENT_UNSAVED_BILLING_ADDRESS_CODE,
+	message: "Save your billing address before placing the order."
+};
+const UNAVAILABLE_METHOD_ERROR = {
+	code: PAYMENT_UNAVAILABLE_METHOD_CODE,
+	message: "Choose another payment method before placing the order."
+};
+/**
+* Whether `CardholderDocument` renders for this selection (T192, Decision 3): the one definition, so
+* the field and the gate can never disagree about it. `selectedMethod` is the *scoped* one
+* `usePayment()` serves, so a selection outside `group` shows no field. Nothing shows while the card
+* payment is collapsed either (T191, FR-7), whatever the method's validator says.
+*/
+function isCardholderDocumentShown({ cardPaymentCollapsed, selectedMethod }) {
+	return !cardPaymentCollapsed && (selectedMethod?.validator.documentDisplayable ?? false);
+}
+/**
+* The document half of the gate: document-missing, then document-invalid, or `null`.
+*
+* FR-1/FR-3: emptiness is its own explicit check, never expressed through `isValidDocument` alone —
+* `isValidDocument('')` returns `true` by design (the document is optional in the general case), which
+* would otherwise silently let a required-but-blank document through. FR-2/Decision 6: validity is
+* checked whenever a value is present, independent of `documentRequired` — a malformed *optional*
+* document blocks too, matching the legacy's own unconditional `pattern`/`validate` rule. Decision 6's
+* own premise is a *displayable* field (a shopper who can see and fix what they typed); `documentDisplayable`
+* therefore gates FR-1 and FR-2 alike (findings R1/S4/S5).
+*/
+function resolveDocumentRefusal({ documentRequired, documentDisplayable, document }) {
+	if (!documentDisplayable) return null;
+	if (documentRequired && (document?.trim() ?? "") === "") return MISSING_DOCUMENT_ERROR;
+	if (!isValidDocument(document ?? "", "CPF")) return INVALID_DOCUMENT_ERROR;
+	return null;
+}
+/**
+* The whole gate: at most one refusal, resolved in a fixed order (FR-7) — the document slot
+* (document-missing, then document-invalid), then billing-unsaved. Pure — no hooks, no context, no DOM —
+* so the truth table is unit-testable without rendering, mirroring `card-entry.tsx`'s own exported
+* `isValidLuhn` / `isExpirationInFuture` convention.
+*
+* T192 (Decision 2): the document slot refuses in exactly the states it always did, and `documentFieldShown`
+* changes only its code — `UNAVAILABLE_PAYMENT_METHOD` instead of a document code while `CardholderDocument`
+* renders nothing (INV-1, INV-2). The billing check is unchanged.
+*/
+function resolvePaymentSubmitGate({ documentRequired, documentDisplayable, documentFieldShown, document, billingAddressUnsaved }) {
+	const documentRefusal = resolveDocumentRefusal({
+		documentRequired,
+		documentDisplayable,
+		document
+	});
+	if (documentRefusal) return documentFieldShown ? documentRefusal : UNAVAILABLE_METHOD_ERROR;
+	if (billingAddressUnsaved) return UNSAVED_BILLING_ADDRESS_ERROR;
+	return null;
+}
+/**
+* Reads `usePayment()` and resolves the gate, memoized on the primitives — never on the `draft` object
+* itself (NFR-3): `draft`'s identity changes on every card-number keystroke (`setDraftBin`), and this
+* must not re-run the CPF check-digit test on each one.
+*
+* Resolves the validator by looking `persistedMethodId` up against `allMethods` — the section's
+* *unscoped* fact and *unscoped* method list — rather than the group-scoped `selectedMethod` /
+* `selectedMethodId` `usePayment()` also exposes (T74, Decision 4/7: the ones `CardholderDocument`/
+* `CardEntry` render from). Fix pass, finding S1, carried forward by T74's contract split:
+* `usePlaceOrder`'s own pre-flight (`sdk/payment/use-place-order.ts`) resolves *its* `selectedMethod`
+* the same unscoped way, off its own independent fragment slice (Decision 2 forbids either hook from
+* reading the other's module). Resolving off the scoped `selectedMethodId` here would silently degrade
+* `documentRequired` to `false` whenever the persisted selection's `groupName` sits outside this root's
+* configured `group` set — no attacker needed, just a store whose real credit- or debit-card group name
+* differs from the hardcoded defaults (`payment.tsx`'s `DEFAULT_METHOD_GROUP`, now two groups rather than
+* one) — while `usePlaceOrder` still finds the method by id alone and opens a transaction. Matching
+* `usePlaceOrder`'s own by-id lookup keeps the two
+* in agreement for every method actually reachable through this root, which is the one thing
+* `usePaymentSubmitGate` and `usePlaceOrder` can never be allowed to disagree about.
+*
+* T192 (issue 948): the scoped `selectedMethod` and `cardPaymentCollapsed` are read for one fact only,
+* `documentFieldShown`, through the same `isCardholderDocumentShown` `CardholderDocument` renders by.
+* It never decides whether the gate refuses — only whether a refusal may name the document.
+*/
+function usePaymentSubmitGate() {
+	const { persistedMethodId, allMethods, selectedMethod, cardPaymentCollapsed, draft } = usePayment();
+	const resolvedMethod = useMemo(() => allMethods.find((method) => method.id === persistedMethodId) ?? null, [allMethods, persistedMethodId]);
+	const documentRequired = resolvedMethod?.validator.documentRequired ?? false;
+	const documentDisplayable = resolvedMethod?.validator.documentDisplayable ?? false;
+	const documentFieldShown = isCardholderDocumentShown({
+		cardPaymentCollapsed,
+		selectedMethod
+	});
+	const { document, billingAddressUnsaved } = draft;
+	return useMemo(() => resolvePaymentSubmitGate({
+		documentRequired,
+		documentDisplayable,
+		documentFieldShown,
+		document,
+		billingAddressUnsaved
+	}), [
+		documentRequired,
+		documentDisplayable,
+		documentFieldShown,
+		document,
+		billingAddressUnsaved
+	]);
+}
+//#endregion
+export { PAYMENT_INVALID_DOCUMENT_CODE, PAYMENT_MISSING_DOCUMENT_CODE, PAYMENT_UNAVAILABLE_METHOD_CODE, PAYMENT_UNSAVED_BILLING_ADDRESS_CODE, isCardholderDocumentShown, resolvePaymentSubmitGate, usePaymentSubmitGate };
+
+//# sourceMappingURL=use-payment-submit-gate.js.map

package/dist/matter/payment/use-payment-submit-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-payment-submit-gate.js","names":[],"sources":["../../../src/matter/payment/use-payment-submit-gate.ts"],"sourcesContent":["'use client';\n\nimport { useMemo } from 'react';\nimport { isValidDocument } from '../../particles/document-field/document-field.js';\nimport type { PaymentUserError } from '../../sdk/payment/operations.js';\nimport { usePayment } from './payment.js';\nimport type { PaymentSectionMethod } from './use-payment-method-selection.js';\n\n/**\n * The submit gate (specs/cardholder-document-submit-gate.md, T24 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D3, D6). One pure resolver covering the two facts T11's own\n * deferral asked to ship together: a required-but-missing-or-malformed cardholder document, and a\n * declined \"same as delivery\" billing address with nothing persisted yet. `PlaceOrder` (T14) reads the\n * verdict through `usePaymentSubmitGate()` below and forwards it into `usePlaceOrder`'s (T13)\n * pre-flight, which refuses on it before `startTransaction` ever opens a transaction the client already\n * knows it cannot complete.\n *\n * **Only the verdict crosses into `sdk/payment/`.** `usePlaceOrder` never learns *why* it refused —\n * only this opaque `PaymentUserError` — because `sdk/payment/use-place-order.ts` may name no identifier\n * matching `CARD_FIELD_PATTERN` (`sdk/payment/card-field-pattern.ts`), which includes `document`. Every\n * fact the gate reads, and the four codes below, live here in `matter/payment/` instead.\n */\n\n// ---------------------------------------------------------------------------\n// Client-synthesized codes. Distinct from T13's own three (`use-place-order.ts`) and from the\n// gateway's (`gateway.ts`) — these mean \"the client already knows this submission would be refused,\"\n// resolved before any request leaves the browser.\n// ---------------------------------------------------------------------------\n\nexport const PAYMENT_MISSING_DOCUMENT_CODE = 'MISSING_CARDHOLDER_DOCUMENT';\nexport const PAYMENT_INVALID_DOCUMENT_CODE = 'INVALID_CARDHOLDER_DOCUMENT';\nexport const PAYMENT_UNSAVED_BILLING_ADDRESS_CODE = 'UNSAVED_BILLING_ADDRESS';\n/**\n * T192 (issue 948): a document refusal while `CardholderDocument` renders nothing —\n * a method the card form cannot pay with, or a selection outside the section's `group` — so the\n * shopper is told to change the method, never to fill a field that is not on screen. The code and its\n * copy are provisional until Product answers T191's OQ-4; `PlaceOrder` authors the copy\n * (`unavailableMethodMessage`).\n */\nexport const PAYMENT_UNAVAILABLE_METHOD_CODE = 'UNAVAILABLE_PAYMENT_METHOD';\n\nconst MISSING_DOCUMENT_ERROR: PaymentUserError = {\n  code: PAYMENT_MISSING_DOCUMENT_CODE,\n  message: 'Enter your document before placing the order.',\n};\n\nconst INVALID_DOCUMENT_ERROR: PaymentUserError = {\n  code: PAYMENT_INVALID_DOCUMENT_CODE,\n  message: 'Enter a valid document before placing the order.',\n};\n\nconst UNSAVED_BILLING_ADDRESS_ERROR: PaymentUserError = {\n  code: PAYMENT_UNSAVED_BILLING_ADDRESS_CODE,\n  message: 'Save your billing address before placing the order.',\n};\n\nconst UNAVAILABLE_METHOD_ERROR: PaymentUserError = {\n  code: PAYMENT_UNAVAILABLE_METHOD_CODE,\n  message: 'Choose another payment method before placing the order.',\n};\n\n/**\n * Whether `CardholderDocument` renders for this selection (T192, Decision 3): the one definition, so\n * the field and the gate can never disagree about it. `selectedMethod` is the *scoped* one\n * `usePayment()` serves, so a selection outside `group` shows no field. Nothing shows while the card\n * payment is collapsed either (T191, FR-7), whatever the method's validator says.\n */\nexport function isCardholderDocumentShown({\n  cardPaymentCollapsed,\n  selectedMethod,\n}: Readonly<{ cardPaymentCollapsed: boolean; selectedMethod: PaymentSectionMethod | null }>): boolean {\n  return !cardPaymentCollapsed && (selectedMethod?.validator.documentDisplayable ?? false);\n}\n\n// ---------------------------------------------------------------------------\n// The resolver\n// ---------------------------------------------------------------------------\n\nexport type PaymentSubmitGateInput = Readonly<{\n  /**\n   * The selected method's `validator.documentRequired`; `false` when no method is resolved yet.\n   * `usePaymentSubmitGate()` resolves the method by `selectedMethodId` against `allMethods` — the\n   * section's *unscoped* list — never the group-scoped `selectedMethod` (finding S1; see that hook's\n   * own doc comment).\n   */\n  documentRequired: boolean;\n  /**\n   * The selected method's `validator.documentDisplayable`, resolved the same unscoped way; `false` when\n   * no method is resolved yet. Gates *both* document checks below (fix pass, findings R1/S4/S5 — one\n   * root cause, three symptoms): `draft.document` is a single fact with a single writer,\n   * `CardholderDocument.onValueChange` (`cardholder-document.tsx:111`). When the selected method's\n   * validator says the document is not displayable, `CardholderDocument` renders nothing for it\n   * (`cardholder-document.tsx:93`) — but nothing clears `draft.document` when that happens: not\n   * `CardholderDocument` unmounting, and not `selectMethod` (`use-payment-method-selection.ts`), which\n   * writes only `path`/`bin` from its input. So `draft.document` can still hold whatever the shopper\n   * typed for a *previously* selected, displayable method. Without this flag, a stale malformed value\n   * would refuse forever with no field left to fix it (R1: a mid-typing, not-yet-valid value survives a\n   * network-detection re-dispatch to a method that never shows the field; S5: any method whose validator\n   * pairs `documentRequired: true` with `documentDisplayable: false` is unconditionally unsatisfiable),\n   * and a stale *valid* value would silently vouch for a document the current method never collected\n   * (S4). Both are the same mistake: treating `draft.document` as meaningful when there is no field on\n   * screen for the shopper to read it from or correct it in. Neither check may run in that state —\n   * matching US-1's fourth criterion (\"the gate contributes nothing regardless of what `draft.document`\n   * holds\") generalized to every `documentRequired` value, not only `false`. This does not weaken the\n   * spec's own settled \"no `CardholderDocument` composed\" deadlock (its Risk R1, US-4 — a different R1\n   * than this fix pass's own): that case has `documentDisplayable: true` on the validator (the method\n   * genuinely calls for a document) with the leaf simply missing from the schema, so FR-1 still fires and\n   * still refuses with a console diagnostic.\n   */\n  documentDisplayable: boolean;\n  /**\n   * Whether `CardholderDocument` renders for this selection: `isCardholderDocumentShown(...)` over the\n   * *scoped* `selectedMethod` and `cardPaymentCollapsed` (T192, Decision 3). Never a trigger: the two\n   * unscoped flags above still decide whether the document refuses (S1). It decides only what the\n   * refusal says — the document codes when the field is on screen, `UNAVAILABLE_PAYMENT_METHOD` when it\n   * is not, since a shopper cannot fill a field that is not there (issue 948).\n   */\n  documentFieldShown: boolean;\n  /** `draft.document` — the masked value `CardholderDocument` publishes on change. */\n  document: string | null;\n  /** `draft.billingAddressUnsaved`. */\n  billingAddressUnsaved: boolean | null;\n}>;\n\n/**\n * The document half of the gate: document-missing, then document-invalid, or `null`.\n *\n * FR-1/FR-3: emptiness is its own explicit check, never expressed through `isValidDocument` alone —\n * `isValidDocument('')` returns `true` by design (the document is optional in the general case), which\n * would otherwise silently let a required-but-blank document through. FR-2/Decision 6: validity is\n * checked whenever a value is present, independent of `documentRequired` — a malformed *optional*\n * document blocks too, matching the legacy's own unconditional `pattern`/`validate` rule. Decision 6's\n * own premise is a *displayable* field (a shopper who can see and fix what they typed); `documentDisplayable`\n * therefore gates FR-1 and FR-2 alike (findings R1/S4/S5).\n */\nfunction resolveDocumentRefusal({\n  documentRequired,\n  documentDisplayable,\n  document,\n}: Pick<PaymentSubmitGateInput, 'documentRequired' | 'documentDisplayable' | 'document'>): PaymentUserError | null {\n  if (!documentDisplayable) return null;\n  if (documentRequired && (document?.trim() ?? '') === '') return MISSING_DOCUMENT_ERROR;\n  if (!isValidDocument(document ?? '', 'CPF')) return INVALID_DOCUMENT_ERROR;\n  return null;\n}\n\n/**\n * The whole gate: at most one refusal, resolved in a fixed order (FR-7) — the document slot\n * (document-missing, then document-invalid), then billing-unsaved. Pure — no hooks, no context, no DOM —\n * so the truth table is unit-testable without rendering, mirroring `card-entry.tsx`'s own exported\n * `isValidLuhn` / `isExpirationInFuture` convention.\n *\n * T192 (Decision 2): the document slot refuses in exactly the states it always did, and `documentFieldShown`\n * changes only its code — `UNAVAILABLE_PAYMENT_METHOD` instead of a document code while `CardholderDocument`\n * renders nothing (INV-1, INV-2). The billing check is unchanged.\n */\nexport function resolvePaymentSubmitGate({\n  documentRequired,\n  documentDisplayable,\n  documentFieldShown,\n  document,\n  billingAddressUnsaved,\n}: PaymentSubmitGateInput): PaymentUserError | null {\n  const documentRefusal = resolveDocumentRefusal({ documentRequired, documentDisplayable, document });\n  if (documentRefusal) {\n    return documentFieldShown ? documentRefusal : UNAVAILABLE_METHOD_ERROR;\n  }\n\n  if (billingAddressUnsaved) {\n    return UNSAVED_BILLING_ADDRESS_ERROR;\n  }\n\n  return null;\n}\n\n/**\n * Reads `usePayment()` and resolves the gate, memoized on the primitives — never on the `draft` object\n * itself (NFR-3): `draft`'s identity changes on every card-number keystroke (`setDraftBin`), and this\n * must not re-run the CPF check-digit test on each one.\n *\n * Resolves the validator by looking `persistedMethodId` up against `allMethods` — the section's\n * *unscoped* fact and *unscoped* method list — rather than the group-scoped `selectedMethod` /\n * `selectedMethodId` `usePayment()` also exposes (T74, Decision 4/7: the ones `CardholderDocument`/\n * `CardEntry` render from). Fix pass, finding S1, carried forward by T74's contract split:\n * `usePlaceOrder`'s own pre-flight (`sdk/payment/use-place-order.ts`) resolves *its* `selectedMethod`\n * the same unscoped way, off its own independent fragment slice (Decision 2 forbids either hook from\n * reading the other's module). Resolving off the scoped `selectedMethodId` here would silently degrade\n * `documentRequired` to `false` whenever the persisted selection's `groupName` sits outside this root's\n * configured `group` set — no attacker needed, just a store whose real credit- or debit-card group name\n * differs from the hardcoded defaults (`payment.tsx`'s `DEFAULT_METHOD_GROUP`, now two groups rather than\n * one) — while `usePlaceOrder` still finds the method by id alone and opens a transaction. Matching\n * `usePlaceOrder`'s own by-id lookup keeps the two\n * in agreement for every method actually reachable through this root, which is the one thing\n * `usePaymentSubmitGate` and `usePlaceOrder` can never be allowed to disagree about.\n *\n * T192 (issue 948): the scoped `selectedMethod` and `cardPaymentCollapsed` are read for one fact only,\n * `documentFieldShown`, through the same `isCardholderDocumentShown` `CardholderDocument` renders by.\n * It never decides whether the gate refuses — only whether a refusal may name the document.\n */\nexport function usePaymentSubmitGate(): PaymentUserError | null {\n  const { persistedMethodId, allMethods, selectedMethod, cardPaymentCollapsed, draft } = usePayment();\n  const resolvedMethod = useMemo(\n    () => allMethods.find((method) => method.id === persistedMethodId) ?? null,\n    [allMethods, persistedMethodId],\n  );\n  const documentRequired = resolvedMethod?.validator.documentRequired ?? false;\n  const documentDisplayable = resolvedMethod?.validator.documentDisplayable ?? false;\n  const documentFieldShown = isCardholderDocumentShown({ cardPaymentCollapsed, selectedMethod });\n  const { document, billingAddressUnsaved } = draft;\n\n  return useMemo(\n    () =>\n      resolvePaymentSubmitGate({\n        documentRequired,\n        documentDisplayable,\n        documentFieldShown,\n        document,\n        billingAddressUnsaved,\n      }),\n    [documentRequired, documentDisplayable, documentFieldShown, document, billingAddressUnsaved],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6BA,MAAa,gCAAgC;AAC7C,MAAa,gCAAgC;AAC7C,MAAa,uCAAuC;;;;;;;;AAQpD,MAAa,kCAAkC;AAE/C,MAAM,yBAA2C;CAC/C,MAAM;CACN,SAAS;AACX;AAEA,MAAM,yBAA2C;CAC/C,MAAM;CACN,SAAS;AACX;AAEA,MAAM,gCAAkD;CACtD,MAAM;CACN,SAAS;AACX;AAEA,MAAM,2BAA6C;CACjD,MAAM;CACN,SAAS;AACX;;;;;;;AAQA,SAAgB,0BAA0B,EACxC,sBACA,kBACoG;CACpG,OAAO,CAAC,yBAAyB,gBAAgB,UAAU,uBAAuB;AACpF;;;;;;;;;;;;AA+DA,SAAS,uBAAuB,EAC9B,kBACA,qBACA,YACiH;CACjH,IAAI,CAAC,qBAAqB,OAAO;CACjC,IAAI,qBAAqB,UAAU,KAAK,KAAK,QAAQ,IAAI,OAAO;CAChE,IAAI,CAAC,gBAAgB,YAAY,IAAI,KAAK,GAAG,OAAO;CACpD,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,yBAAyB,EACvC,kBACA,qBACA,oBACA,UACA,yBACkD;CAClD,MAAM,kBAAkB,uBAAuB;EAAE;EAAkB;EAAqB;CAAS,CAAC;CAClG,IAAI,iBACF,OAAO,qBAAqB,kBAAkB;CAGhD,IAAI,uBACF,OAAO;CAGT,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,uBAAgD;CAC9D,MAAM,EAAE,mBAAmB,YAAY,gBAAgB,sBAAsB,UAAU,WAAW;CAClG,MAAM,iBAAiB,cACf,WAAW,MAAM,WAAW,OAAO,OAAO,iBAAiB,KAAK,MACtE,CAAC,YAAY,iBAAiB,CAChC;CACA,MAAM,mBAAmB,gBAAgB,UAAU,oBAAoB;CACvE,MAAM,sBAAsB,gBAAgB,UAAU,uBAAuB;CAC7E,MAAM,qBAAqB,0BAA0B;EAAE;EAAsB;CAAe,CAAC;CAC7F,MAAM,EAAE,UAAU,0BAA0B;CAE5C,OAAO,cAEH,yBAAyB;EACvB;EACA;EACA;EACA;EACA;CACF,CAAC,GACH;EAAC;EAAkB;EAAqB;EAAoB;EAAU;CAAqB,CAC7F;AACF"}

package/dist/matter/place-order/place-order.d.ts

@@ -0,0 +1,74 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import "../../sdk/payment/operations.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { PlaceOrderData } from "../../sdk/payment/use-place-order.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/matter/place-order/place-order.d.ts
+export type PlaceOrderProps = ComponentPropsWithRef<'div'> & {
+  /** CTA label while idle. */
+  label?: string;
+  /** CTA label while the three-call sequence is in flight. */
+  placingLabel?: string;
+  /**
+   * CTA label while a surviving attempt (T29) offers a resume — the card already left the browser
+   * (`sent`) or its fate is unknown (`unresolved`), and the next click finalizes it rather than running
+   * the full sequence again. Shown instead of `label`, never alongside `placingLabel` (mutually
+   * exclusive — `placing` takes priority whenever both could apply).
+   */
+  resumeLabel?: string;
+  /** Inline message shown once the sequence has settled with no `userErrors`. */
+  successMessage?: string;
+  /** Shown when `placeOrder()` is invoked with no registered submission for the current path. */
+  missingSubmissionMessage?: string;
+  /** Shown when no payment method is selected yet. */
+  missingMethodMessage?: string;
+  /** Shown when `startTransaction` resolves incomplete transaction data. */
+  invalidTransactionMessage?: string;
+  /** Shown for an infrastructure-level failure reaching the payment gateway action. */
+  networkErrorMessage?: string;
+  /** Shown when the selected method requires a cardholder document and none is set. */
+  missingDocumentMessage?: string;
+  /** Shown when the typed cardholder document fails validation. */
+  invalidDocumentMessage?: string;
+  /**
+   * Shown instead of the two document messages above when the selected method calls for a cardholder
+   * document the page is not showing — a method the card form cannot pay with, or one outside the
+   * section's `group` — so the shopper has to choose another payment method (T192).
+   */
+  unavailableMethodMessage?: string;
+  /** Shown when the shopper declined "same as delivery" but never saved a billing address. */
+  unsavedBillingAddressMessage?: string;
+  /** Shown when the new-card draft itself fails validation before ever reaching the gateway. */
+  invalidCardDataMessage?: string;
+  /** Shown when a saved-card submission is refused for a missing or invalid CVV. */
+  invalidSecurityCodeMessage?: string;
+  /** Shown when the payment gateway itself refuses the submitted card. */
+  gatewayErrorMessage?: string;
+  /**
+   * Shown when a click lands on an order-placement attempt whose own sequence is still running — a
+   * transaction this instance did not open, and which nothing here may finalize or re-run (T170).
+   */
+  inFlightMessage?: string;
+  /**
+   * Shown when the payment was handed to the gateway but the order could not be confirmed, so it may still be
+   * processing (T176). Rendered as a status, never as the error alert.
+   */
+  unconfirmedMessage?: string;
+  /**
+   * Route template navigated to after a successful placement. The literal `{orderGroup}` is
+   * replaced by the placed order's group, percent-encoded. Absent ⇒ no navigation. Must resolve to
+   * the current page's origin — an absolute, protocol-relative, or non-http(s) template is refused
+   * rather than navigated to (fail closed, dev-only warn; fix pass, finding S1).
+   * e.g. "/reserva/checkout/order-placed/{orderGroup}"
+   */
+  successHref?: string;
+  /** `Payment` slice forwarded by the reactive runtime (arity-1, ADR-0015) — `null` until it resolves. */
+  $data?: PlaceOrderData;
+  /** Compiler-injected action surface; carries `payment.startTransaction`, `payment.gatewayCallback`, `analytics.track`. */
+  $actions?: ComponentActions;
+};
+export declare const PlaceOrderDefinition: ComponentDefinition<PlaceOrderProps>;
+export declare function PlaceOrder({ label, placingLabel, resumeLabel, successMessage, missingSubmissionMessage, missingMethodMessage, invalidTransactionMessage, networkErrorMessage, missingDocumentMessage, invalidDocumentMessage, unavailableMethodMessage, unsavedBillingAddressMessage, invalidCardDataMessage, invalidSecurityCodeMessage, gatewayErrorMessage, inFlightMessage, unconfirmedMessage, successHref, $data: $dataProp, $actions: $actionsProp, className, ...props }: PlaceOrderProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=place-order.d.ts.map