@asteby/storefront-react 0.22.0 → 0.24.0

package/dist/fiscal.css

@@ -341,3 +341,106 @@
 [data-sf-invoice-actions] {
   align-items: center;
 }
+
+/* ---- Scan a tax document: entry buttons, bottom sheet and live viewfinder ---- */
+[data-sf-scan] {
+  display: grid;
+  gap: 0.75rem;
+}
+[data-sf-scan-open],
+[data-sf-scan-manual],
+[data-sf-reader-scan] button {
+  min-height: 44px;
+}
+[data-sf-reader-scan] {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+}
+[data-sf-scan-sheet] {
+  position: fixed;
+  inset: auto 0 0 0;
+  margin: 0;
+  width: 100%;
+  max-width: none;
+  max-height: 92dvh;
+  padding: 0;
+  border: 0;
+  border-radius: 1.25rem 1.25rem 0 0;
+  overflow: auto;
+  background: var(--sf-fiscal-sheet-bg, Canvas);
+  color: var(--sf-fiscal-sheet-fg, CanvasText);
+  box-shadow: 0 -8px 32px color-mix(in srgb, #000 22%, transparent);
+  animation: sf-scan-rise 180ms ease-out;
+}
+[data-sf-scan-sheet]::backdrop {
+  background: color-mix(in srgb, #000 45%, transparent);
+}
+@media (min-width: 40rem) {
+  [data-sf-scan-sheet] {
+    inset: 50% auto auto 50%;
+    transform: translate(-50%, -50%);
+    width: min(32rem, calc(100vw - 2rem));
+    border-radius: 1.25rem;
+    animation: none;
+  }
+}
+[data-sf-scan-panel] {
+  display: grid;
+  gap: 1rem;
+  padding: 1rem 1rem calc(1rem + env(safe-area-inset-bottom));
+}
+[data-sf-scan-header] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+[data-sf-scan-title] {
+  margin: 0;
+  font-size: 1.125rem;
+}
+[data-sf-scan-close] {
+  min-width: 44px;
+  min-height: 44px;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+[data-sf-reader-viewfinder] {
+  position: relative;
+  overflow: hidden;
+  border-radius: 1rem;
+  background: #000;
+  aspect-ratio: 4 / 3;
+}
+[data-sf-reader-video] {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+[data-sf-reader-frame] {
+  position: absolute;
+  inset: 18%;
+  border: 3px solid #fff;
+  border-radius: 0.75rem;
+  box-shadow: 0 0 0 9999px color-mix(in srgb, #000 35%, transparent);
+  pointer-events: none;
+}
+[data-sf-suggested] {
+  font-weight: 600;
+}
+@keyframes sf-scan-rise {
+  from {
+    transform: translateY(24px);
+    opacity: 0;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-sf-scan-sheet] {
+    animation: none;
+  }
+}

package/dist/fiscal.d.cts

@@ -1,9 +1,9 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, RefObject } from 'react';
 import { F as FieldErrors, a as CheckoutFieldClassNames } from './fields-vnMUi2HB.cjs';
 import { Region, RegionFiscalId, RegionFiscalEntry, InvoiceRequest, FiscalDocumentEvidence, IdentityDocumentSpec, InvoicingCapabilities, FiscalIdentity, InvoiceSummary } from '@asteby/storefront';
-import { f as FiscalReadError, d as FiscalFieldValues, c as FiscalFieldName, F as FiscalActionData, b as FiscalExtractionSummary } from './types-BnvSbV6t.cjs';
-export { a as FiscalErrorCode, e as FiscalIntent } from './types-BnvSbV6t.cjs';
+import { f as FiscalReadError, d as FiscalFieldValues, c as FiscalFieldName, F as FiscalActionData, g as FiscalReason, b as FiscalExtractionSummary } from './types-Cgx_65eM.cjs';
+export { a as FiscalErrorCode, e as FiscalIntent } from './types-Cgx_65eM.cjs';
 import { IdentityExtraction } from '@asteby/storefront/fiscal-document';
 
 /** Texts of the fiscal components. Spanish (es-MX) by default, English with `en*`, any locale with `messages`. */
@@ -30,6 +30,8 @@ type FiscalMessages = {
         useChoose: string;
         /** `{document}` = the document's name. */
         fromDocument: string;
+        /** Mark on an invoice use the region suggested (an editable preselection). */
+        suggested: string;
         errors: {
             required: string;
             taxIdFormat: string;
@@ -64,6 +66,26 @@ type FiscalMessages = {
             stale: string;
             regimeMissing: string;
             fieldsMissing: string;
+            qrPartial: string;
+        };
+        /** Reading a photo or the camera (the region's `image_mode`). `{document}` where noted. */
+        scan: {
+            title: string;
+            photo: string;
+            photoHint: string;
+            camera: string;
+            cameraTitle: string;
+            cameraGuide: string;
+            cameraStarting: string;
+            cameraRead: string;
+            cameraDenied: string;
+            cameraUnavailable: string;
+            closeCamera: string;
+            choosePhoto: string;
+            /** Button that opens the sheet; `{document}` is the document's label. */
+            open: string;
+            manual: string;
+            close: string;
         };
         errors: Record<FiscalReadError, string>;
         summaryTitleOne: string;
@@ -114,6 +136,17 @@ type FiscalMessages = {
         windowBody: string;
         unavailableTitle: string;
         unavailableBody: string;
+        /** The server says the store has no invoicing active (`capabilities.invoicing.available: false`). */
+        notEnabledTitle: string;
+        notEnabledBody: string;
+        /** The server does not say (older server) or could not be asked: never claims the store does not invoice. */
+        unknownTitle: string;
+        unknownBody: string;
+        unreachableBody: string;
+        /** Invoicing in test mode (sandbox): invoices have no fiscal validity. */
+        sandbox: string;
+        /** `{days}`: how long after the purchase an invoice can be requested. */
+        windowNote: string;
         cancelledTitle: string;
         cancelledBody: string;
         /** `reason_code` -> cause for the buyer. `default` when unknown. */
@@ -147,13 +180,26 @@ declare function postalCodeProblem(region: FiscalRegion, raw: string): 'required
  * are not narrowed by person type (the server still checks the combination).
  */
 declare function personTypeByLength(lengths: Record<string, number>): (taxId: string) => string | null;
+/**
+ * Tells a person type from a tax id with the region's own patterns (`fiscal_id.person_patterns`, DATA of the region
+ * pack). `null` when the region publishes none or none matches. A pattern that does not compile is ignored.
+ */
+declare function personTypeFromPatterns(fid: RegionFiscalId | undefined, taxId: string): string | null;
+/** The function to use for the person type: the store's override, else the region's patterns. */
+declare function personTypeResolver(fid: RegionFiscalId | undefined, override?: (taxId: string) => string | null): (taxId: string) => string | null;
+/**
+ * The invoice use to suggest for a regime, from region data only: the organization's `default_invoice_use` when the
+ * regime admits it, else the first use whose `suggested_for_regimes` lists the regime (and whose `allowed_regimes`
+ * admits it). `null` when the region suggests nothing: then nothing is preselected. A suggestion, never a rule.
+ */
+declare function suggestInvoiceUse(fid: RegionFiscalId | undefined, regime: string | null | undefined): string | null;
 /** Regimes that fit a person type (all when the type is unknown). */
 declare function regimesFor(fid: RegionFiscalId | undefined, personType: string | null): RegionFiscalEntry[];
 /** Invoice uses a regime admits (all when no regime is chosen yet). */
 declare function usesFor(fid: RegionFiscalId | undefined, regime: string | null | undefined): RegionFiscalEntry[];
 type FiscalProblem = 'required' | 'format' | 'unknown' | 'person_type' | 'use_not_allowed';
 /** Client-side check of the whole form against the region; the server stays the authority. */
-declare function validateFiscalValues(region: FiscalRegion, v: Partial<FiscalFieldValues>, personTypeOf?: (taxId: string) => string | null): Partial<Record<FiscalFieldName, FiscalProblem>>;
+declare function validateFiscalValues(region: FiscalRegion, v: Partial<FiscalFieldValues>, personTypeOverride?: (taxId: string) => string | null): Partial<Record<FiscalFieldName, FiscalProblem>>;
 /** Form values -> the API's `InvoiceRequest` (without `document`). */
 declare function toInvoiceRequest(v: Partial<FiscalFieldValues>, countryCode?: string): InvoiceRequest;
 /** `label_en` for English locales when the region has it. */
@@ -176,8 +222,13 @@ type FiscalIdentityFieldsProps = {
     namePrefix?: string;
     /** Prefix of the control ids (default: generated). */
     idPrefix?: string;
-    /** Tells a person type from a tax id, to narrow the regimes (`personTypeByLength`). */
+    /**
+     * Overrides how a person type is told from a tax id (to narrow the regimes). Default: the region's own patterns
+     * (`fiscal_id.person_patterns`); with neither, the regimes are not narrowed (the server still checks).
+     */
     personTypeOf?: (taxId: string) => string | null;
+    /** The invoice use in `values` came from the region's suggestion (a document was read): it gets the "Suggested" mark. */
+    suggestedUse?: string | null;
     disabled?: boolean;
     locale?: string;
     messages?: DeepPartial<FiscalMessages>;
@@ -185,7 +236,7 @@ type FiscalIdentityFieldsProps = {
     /** Hides the fieldset legend (when the caller already has a heading). */
     hideLegend?: boolean;
 };
-declare function FiscalIdentityFields({ region, values, onChange, fromDocument, documentName, regimeCandidates, errors, namePrefix, idPrefix, personTypeOf, disabled, locale: localeProp, messages, classNames: cx, hideLegend, }: FiscalIdentityFieldsProps): react.JSX.Element;
+declare function FiscalIdentityFields({ region, values, onChange, fromDocument, documentName, regimeCandidates, errors, namePrefix, idPrefix, personTypeOf: personTypeOverride, suggestedUse, disabled, locale: localeProp, messages, classNames: cx, hideLegend, }: FiscalIdentityFieldsProps): react.JSX.Element;
 
 type FiscalReaderResult = {
     values: FiscalFieldValues;
@@ -230,6 +281,50 @@ type IdentityDocumentReaderProps = {
 };
 declare function IdentityDocumentReader(props: IdentityDocumentReaderProps): react.JSX.Element | null;
 
+type ScanTaxDocumentClassNames = IdentityDocumentReaderProps['classNames'] & Partial<Record<'actions' | 'trigger' | 'manual' | 'sheet' | 'sheetPanel' | 'sheetHeader' | 'sheetTitle' | 'sheetClose', string>>;
+type ScanTaxDocumentProps = Omit<IdentityDocumentReaderProps, 'onConfirm' | 'onManual' | 'classNames' | 'confirmLabel'> & {
+    /** The buyer confirmed the reviewed data (the sheet is already closed). */
+    onConfirm: (result: FiscalReaderResult) => void;
+    /** The buyer chose to type their data (the sheet is already closed). */
+    onManual: () => void;
+    /** Label of the confirm button inside the sheet. */
+    confirmLabel?: ReactNode;
+    classNames?: ScanTaxDocumentClassNames;
+};
+declare function ScanTaxDocument(props: ScanTaxDocumentProps): react.JSX.Element | null;
+
+/**
+ * Live QR reading with the device camera. Nothing is recorded or stored: the frames are read in memory by
+ * `decodeImageQr` (loaded on demand, so a page that never opens the camera pays 0 bytes for it) and the stream is
+ * stopped when the scanner closes, when the component unmounts or when the page is hidden.
+ */
+
+type CameraQrStatus = 
+/** Not running. */
+'idle'
+/** Waiting for the permission or for the first frame. */
+ | 'starting' | 'scanning'
+/** The buyer (or the browser) refused the camera. */
+ | 'denied'
+/** No `getUserMedia` here (old browser, insecure page). */
+ | 'unsupported';
+type UseCameraQrOptions = {
+    /** Start (true) or stop (false) the camera. */
+    active: boolean;
+    /** The QR text read. Called once; the camera stops right after. */
+    onCode: (text: string) => void;
+    /** Milliseconds between two reading attempts (default 250). */
+    intervalMs?: number;
+};
+type UseCameraQr = {
+    videoRef: RefObject<HTMLVideoElement | null>;
+    status: CameraQrStatus;
+    /** Stops the stream now. */
+    stop: () => void;
+};
+declare function cameraSupported(): boolean;
+declare function useCameraQr({ active, onCode, intervalMs }: UseCameraQrOptions): UseCameraQr;
+
 type InvoiceToggleState = {
     requested: boolean;
     /** The data to send as `CheckoutInput.invoice` / `carts.setInvoice`; `null` when none is requested or it is not ready. */
@@ -273,14 +368,28 @@ type InvoiceToggleProps = {
 };
 declare function InvoiceToggle(props: InvoiceToggleProps): react.JSX.Element | null;
 
-type InvoiceCardState = 'not_requested' | 'awaiting_payment' | 'processing' | 'issued' | 'needs_data' | 'needs_review' | 'window_closed' | 'unavailable' | 'cancelled';
-/** Which of the card's states an invoice is in. `available: false` (the store does not invoice) wins over everything. */
-declare function invoiceCardState(invoice: InvoiceSummary | null | undefined, available?: boolean): InvoiceCardState;
+type InvoiceCardState = 'not_requested' | 'awaiting_payment' | 'processing' | 'issued' | 'needs_data' | 'needs_review' | 'window_closed' | 'unavailable' | 'not_enabled' | 'unknown' | 'unreachable' | 'cancelled';
+/**
+ * Which of the card's states an invoice is in.
+ *
+ * `available` / `reason` come from `loadFiscalContext`. Only a server that SAYS the store does not invoice
+ * (`reason` `off` / `no_region`) wins over the order: `not_enabled`. When the server says nothing (`unknown`, an older
+ * server), could not be asked (`unreachable`) or the caller gave no `reason`, the order's own summary still decides
+ * (an order that `can_request`, is being issued or already has its invoice is shown as such) and, with nothing to show,
+ * the card is neutral: it never claims that the store does not issue invoices.
+ */
+declare function invoiceCardState(invoice: InvoiceSummary | null | undefined, available?: boolean, reason?: FiscalReason): InvoiceCardState;
 type InvoiceStatusCardClassNames = Partial<Record<'root' | 'title' | 'body' | 'actions' | 'primary' | 'secondary' | 'link' | 'meta', string>>;
 type InvoiceStatusCardProps = {
     invoice?: InvoiceSummary | null;
-    /** `capabilities.invoicing.available`. `false`: "Invoice not available". */
+    /** `loadFiscalContext(...).available`. `false` alone is read as "unknown": see `availability`. */
     available?: boolean;
+    /** `loadFiscalContext(...).reason`: why it is (not) available. Lets the card say the true thing (not active / unknown / could not check). */
+    availability?: FiscalReason;
+    /** Invoicing is in test mode (sandbox): shows a badge saying invoices have no fiscal validity. */
+    testMode?: boolean;
+    /** `capabilities.invoicing.window_days`: shown next to the request button. */
+    windowDays?: number;
     /** The buyer taps "Request invoice". Shown when `invoice.can_request !== false`. Without it, `requestHref` is a link. */
     onRequest?: () => void;
     requestHref?: string;
@@ -310,4 +419,4 @@ declare function InvoiceStatusCard(props: InvoiceStatusCardProps): react.JSX.Ele
 /** `evidence` comes from `buildDocumentEvidence`. Only the conventional fields are kept: nothing else can leak. */
 declare function summarizeExtraction(x: IdentityExtraction, evidence: FiscalDocumentEvidence, validRegimes?: Iterable<string>): FiscalExtractionSummary;
 
-export { type DeepPartial, FiscalActionData, FiscalExtractionSummary, FiscalFieldName, FiscalFieldValues, FiscalIdentityFields, type FiscalIdentityFieldsClassNames, type FiscalIdentityFieldsProps, type FiscalMessages, type FiscalProblem, FiscalReadError, type FiscalReaderResult, type FiscalRegion, IdentityDocumentReader, type IdentityDocumentReaderClassNames, type IdentityDocumentReaderProps, type InvoiceCardState, InvoiceStatusCard, type InvoiceStatusCardClassNames, type InvoiceStatusCardProps, InvoiceToggle, type InvoiceToggleClassNames, type InvoiceToggleProps, type InvoiceToggleState, entryLabel, fiscalMessages, invoiceCardState, maskTaxId, normalizeTaxId, personTypeByLength, postalCodeProblem, regimesFor, summarizeExtraction, taxIdProblem, toInvoiceRequest, usesFor, validateFiscalValues };
+export { type CameraQrStatus, type DeepPartial, FiscalActionData, FiscalExtractionSummary, FiscalFieldName, FiscalFieldValues, FiscalIdentityFields, type FiscalIdentityFieldsClassNames, type FiscalIdentityFieldsProps, type FiscalMessages, type FiscalProblem, FiscalReadError, type FiscalReaderResult, type FiscalRegion, IdentityDocumentReader, type IdentityDocumentReaderClassNames, type IdentityDocumentReaderProps, type InvoiceCardState, InvoiceStatusCard, type InvoiceStatusCardClassNames, type InvoiceStatusCardProps, InvoiceToggle, type InvoiceToggleClassNames, type InvoiceToggleProps, type InvoiceToggleState, ScanTaxDocument, type ScanTaxDocumentClassNames, type ScanTaxDocumentProps, type UseCameraQr, type UseCameraQrOptions, cameraSupported, entryLabel, fiscalMessages, invoiceCardState, maskTaxId, normalizeTaxId, personTypeByLength, personTypeFromPatterns, personTypeResolver, postalCodeProblem, regimesFor, suggestInvoiceUse, summarizeExtraction, taxIdProblem, toInvoiceRequest, useCameraQr, usesFor, validateFiscalValues };

package/dist/fiscal.d.ts

@@ -1,9 +1,9 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, RefObject } from 'react';
 import { F as FieldErrors, a as CheckoutFieldClassNames } from './fields-vnMUi2HB.js';
 import { Region, RegionFiscalId, RegionFiscalEntry, InvoiceRequest, FiscalDocumentEvidence, IdentityDocumentSpec, InvoicingCapabilities, FiscalIdentity, InvoiceSummary } from '@asteby/storefront';
-import { f as FiscalReadError, d as FiscalFieldValues, c as FiscalFieldName, F as FiscalActionData, b as FiscalExtractionSummary } from './types-BnvSbV6t.js';
-export { a as FiscalErrorCode, e as FiscalIntent } from './types-BnvSbV6t.js';
+import { f as FiscalReadError, d as FiscalFieldValues, c as FiscalFieldName, F as FiscalActionData, g as FiscalReason, b as FiscalExtractionSummary } from './types-Cgx_65eM.js';
+export { a as FiscalErrorCode, e as FiscalIntent } from './types-Cgx_65eM.js';
 import { IdentityExtraction } from '@asteby/storefront/fiscal-document';
 
 /** Texts of the fiscal components. Spanish (es-MX) by default, English with `en*`, any locale with `messages`. */
@@ -30,6 +30,8 @@ type FiscalMessages = {
         useChoose: string;
         /** `{document}` = the document's name. */
         fromDocument: string;
+        /** Mark on an invoice use the region suggested (an editable preselection). */
+        suggested: string;
         errors: {
             required: string;
             taxIdFormat: string;
@@ -64,6 +66,26 @@ type FiscalMessages = {
             stale: string;
             regimeMissing: string;
             fieldsMissing: string;
+            qrPartial: string;
+        };
+        /** Reading a photo or the camera (the region's `image_mode`). `{document}` where noted. */
+        scan: {
+            title: string;
+            photo: string;
+            photoHint: string;
+            camera: string;
+            cameraTitle: string;
+            cameraGuide: string;
+            cameraStarting: string;
+            cameraRead: string;
+            cameraDenied: string;
+            cameraUnavailable: string;
+            closeCamera: string;
+            choosePhoto: string;
+            /** Button that opens the sheet; `{document}` is the document's label. */
+            open: string;
+            manual: string;
+            close: string;
         };
         errors: Record<FiscalReadError, string>;
         summaryTitleOne: string;
@@ -114,6 +136,17 @@ type FiscalMessages = {
         windowBody: string;
         unavailableTitle: string;
         unavailableBody: string;
+        /** The server says the store has no invoicing active (`capabilities.invoicing.available: false`). */
+        notEnabledTitle: string;
+        notEnabledBody: string;
+        /** The server does not say (older server) or could not be asked: never claims the store does not invoice. */
+        unknownTitle: string;
+        unknownBody: string;
+        unreachableBody: string;
+        /** Invoicing in test mode (sandbox): invoices have no fiscal validity. */
+        sandbox: string;
+        /** `{days}`: how long after the purchase an invoice can be requested. */
+        windowNote: string;
         cancelledTitle: string;
         cancelledBody: string;
         /** `reason_code` -> cause for the buyer. `default` when unknown. */
@@ -147,13 +180,26 @@ declare function postalCodeProblem(region: FiscalRegion, raw: string): 'required
  * are not narrowed by person type (the server still checks the combination).
  */
 declare function personTypeByLength(lengths: Record<string, number>): (taxId: string) => string | null;
+/**
+ * Tells a person type from a tax id with the region's own patterns (`fiscal_id.person_patterns`, DATA of the region
+ * pack). `null` when the region publishes none or none matches. A pattern that does not compile is ignored.
+ */
+declare function personTypeFromPatterns(fid: RegionFiscalId | undefined, taxId: string): string | null;
+/** The function to use for the person type: the store's override, else the region's patterns. */
+declare function personTypeResolver(fid: RegionFiscalId | undefined, override?: (taxId: string) => string | null): (taxId: string) => string | null;
+/**
+ * The invoice use to suggest for a regime, from region data only: the organization's `default_invoice_use` when the
+ * regime admits it, else the first use whose `suggested_for_regimes` lists the regime (and whose `allowed_regimes`
+ * admits it). `null` when the region suggests nothing: then nothing is preselected. A suggestion, never a rule.
+ */
+declare function suggestInvoiceUse(fid: RegionFiscalId | undefined, regime: string | null | undefined): string | null;
 /** Regimes that fit a person type (all when the type is unknown). */
 declare function regimesFor(fid: RegionFiscalId | undefined, personType: string | null): RegionFiscalEntry[];
 /** Invoice uses a regime admits (all when no regime is chosen yet). */
 declare function usesFor(fid: RegionFiscalId | undefined, regime: string | null | undefined): RegionFiscalEntry[];
 type FiscalProblem = 'required' | 'format' | 'unknown' | 'person_type' | 'use_not_allowed';
 /** Client-side check of the whole form against the region; the server stays the authority. */
-declare function validateFiscalValues(region: FiscalRegion, v: Partial<FiscalFieldValues>, personTypeOf?: (taxId: string) => string | null): Partial<Record<FiscalFieldName, FiscalProblem>>;
+declare function validateFiscalValues(region: FiscalRegion, v: Partial<FiscalFieldValues>, personTypeOverride?: (taxId: string) => string | null): Partial<Record<FiscalFieldName, FiscalProblem>>;
 /** Form values -> the API's `InvoiceRequest` (without `document`). */
 declare function toInvoiceRequest(v: Partial<FiscalFieldValues>, countryCode?: string): InvoiceRequest;
 /** `label_en` for English locales when the region has it. */
@@ -176,8 +222,13 @@ type FiscalIdentityFieldsProps = {
     namePrefix?: string;
     /** Prefix of the control ids (default: generated). */
     idPrefix?: string;
-    /** Tells a person type from a tax id, to narrow the regimes (`personTypeByLength`). */
+    /**
+     * Overrides how a person type is told from a tax id (to narrow the regimes). Default: the region's own patterns
+     * (`fiscal_id.person_patterns`); with neither, the regimes are not narrowed (the server still checks).
+     */
     personTypeOf?: (taxId: string) => string | null;
+    /** The invoice use in `values` came from the region's suggestion (a document was read): it gets the "Suggested" mark. */
+    suggestedUse?: string | null;
     disabled?: boolean;
     locale?: string;
     messages?: DeepPartial<FiscalMessages>;
@@ -185,7 +236,7 @@ type FiscalIdentityFieldsProps = {
     /** Hides the fieldset legend (when the caller already has a heading). */
     hideLegend?: boolean;
 };
-declare function FiscalIdentityFields({ region, values, onChange, fromDocument, documentName, regimeCandidates, errors, namePrefix, idPrefix, personTypeOf, disabled, locale: localeProp, messages, classNames: cx, hideLegend, }: FiscalIdentityFieldsProps): react.JSX.Element;
+declare function FiscalIdentityFields({ region, values, onChange, fromDocument, documentName, regimeCandidates, errors, namePrefix, idPrefix, personTypeOf: personTypeOverride, suggestedUse, disabled, locale: localeProp, messages, classNames: cx, hideLegend, }: FiscalIdentityFieldsProps): react.JSX.Element;
 
 type FiscalReaderResult = {
     values: FiscalFieldValues;
@@ -230,6 +281,50 @@ type IdentityDocumentReaderProps = {
 };
 declare function IdentityDocumentReader(props: IdentityDocumentReaderProps): react.JSX.Element | null;
 
+type ScanTaxDocumentClassNames = IdentityDocumentReaderProps['classNames'] & Partial<Record<'actions' | 'trigger' | 'manual' | 'sheet' | 'sheetPanel' | 'sheetHeader' | 'sheetTitle' | 'sheetClose', string>>;
+type ScanTaxDocumentProps = Omit<IdentityDocumentReaderProps, 'onConfirm' | 'onManual' | 'classNames' | 'confirmLabel'> & {
+    /** The buyer confirmed the reviewed data (the sheet is already closed). */
+    onConfirm: (result: FiscalReaderResult) => void;
+    /** The buyer chose to type their data (the sheet is already closed). */
+    onManual: () => void;
+    /** Label of the confirm button inside the sheet. */
+    confirmLabel?: ReactNode;
+    classNames?: ScanTaxDocumentClassNames;
+};
+declare function ScanTaxDocument(props: ScanTaxDocumentProps): react.JSX.Element | null;
+
+/**
+ * Live QR reading with the device camera. Nothing is recorded or stored: the frames are read in memory by
+ * `decodeImageQr` (loaded on demand, so a page that never opens the camera pays 0 bytes for it) and the stream is
+ * stopped when the scanner closes, when the component unmounts or when the page is hidden.
+ */
+
+type CameraQrStatus = 
+/** Not running. */
+'idle'
+/** Waiting for the permission or for the first frame. */
+ | 'starting' | 'scanning'
+/** The buyer (or the browser) refused the camera. */
+ | 'denied'
+/** No `getUserMedia` here (old browser, insecure page). */
+ | 'unsupported';
+type UseCameraQrOptions = {
+    /** Start (true) or stop (false) the camera. */
+    active: boolean;
+    /** The QR text read. Called once; the camera stops right after. */
+    onCode: (text: string) => void;
+    /** Milliseconds between two reading attempts (default 250). */
+    intervalMs?: number;
+};
+type UseCameraQr = {
+    videoRef: RefObject<HTMLVideoElement | null>;
+    status: CameraQrStatus;
+    /** Stops the stream now. */
+    stop: () => void;
+};
+declare function cameraSupported(): boolean;
+declare function useCameraQr({ active, onCode, intervalMs }: UseCameraQrOptions): UseCameraQr;
+
 type InvoiceToggleState = {
     requested: boolean;
     /** The data to send as `CheckoutInput.invoice` / `carts.setInvoice`; `null` when none is requested or it is not ready. */
@@ -273,14 +368,28 @@ type InvoiceToggleProps = {
 };
 declare function InvoiceToggle(props: InvoiceToggleProps): react.JSX.Element | null;
 
-type InvoiceCardState = 'not_requested' | 'awaiting_payment' | 'processing' | 'issued' | 'needs_data' | 'needs_review' | 'window_closed' | 'unavailable' | 'cancelled';
-/** Which of the card's states an invoice is in. `available: false` (the store does not invoice) wins over everything. */
-declare function invoiceCardState(invoice: InvoiceSummary | null | undefined, available?: boolean): InvoiceCardState;
+type InvoiceCardState = 'not_requested' | 'awaiting_payment' | 'processing' | 'issued' | 'needs_data' | 'needs_review' | 'window_closed' | 'unavailable' | 'not_enabled' | 'unknown' | 'unreachable' | 'cancelled';
+/**
+ * Which of the card's states an invoice is in.
+ *
+ * `available` / `reason` come from `loadFiscalContext`. Only a server that SAYS the store does not invoice
+ * (`reason` `off` / `no_region`) wins over the order: `not_enabled`. When the server says nothing (`unknown`, an older
+ * server), could not be asked (`unreachable`) or the caller gave no `reason`, the order's own summary still decides
+ * (an order that `can_request`, is being issued or already has its invoice is shown as such) and, with nothing to show,
+ * the card is neutral: it never claims that the store does not issue invoices.
+ */
+declare function invoiceCardState(invoice: InvoiceSummary | null | undefined, available?: boolean, reason?: FiscalReason): InvoiceCardState;
 type InvoiceStatusCardClassNames = Partial<Record<'root' | 'title' | 'body' | 'actions' | 'primary' | 'secondary' | 'link' | 'meta', string>>;
 type InvoiceStatusCardProps = {
     invoice?: InvoiceSummary | null;
-    /** `capabilities.invoicing.available`. `false`: "Invoice not available". */
+    /** `loadFiscalContext(...).available`. `false` alone is read as "unknown": see `availability`. */
     available?: boolean;
+    /** `loadFiscalContext(...).reason`: why it is (not) available. Lets the card say the true thing (not active / unknown / could not check). */
+    availability?: FiscalReason;
+    /** Invoicing is in test mode (sandbox): shows a badge saying invoices have no fiscal validity. */
+    testMode?: boolean;
+    /** `capabilities.invoicing.window_days`: shown next to the request button. */
+    windowDays?: number;
     /** The buyer taps "Request invoice". Shown when `invoice.can_request !== false`. Without it, `requestHref` is a link. */
     onRequest?: () => void;
     requestHref?: string;
@@ -310,4 +419,4 @@ declare function InvoiceStatusCard(props: InvoiceStatusCardProps): react.JSX.Ele
 /** `evidence` comes from `buildDocumentEvidence`. Only the conventional fields are kept: nothing else can leak. */
 declare function summarizeExtraction(x: IdentityExtraction, evidence: FiscalDocumentEvidence, validRegimes?: Iterable<string>): FiscalExtractionSummary;
 
-export { type DeepPartial, FiscalActionData, FiscalExtractionSummary, FiscalFieldName, FiscalFieldValues, FiscalIdentityFields, type FiscalIdentityFieldsClassNames, type FiscalIdentityFieldsProps, type FiscalMessages, type FiscalProblem, FiscalReadError, type FiscalReaderResult, type FiscalRegion, IdentityDocumentReader, type IdentityDocumentReaderClassNames, type IdentityDocumentReaderProps, type InvoiceCardState, InvoiceStatusCard, type InvoiceStatusCardClassNames, type InvoiceStatusCardProps, InvoiceToggle, type InvoiceToggleClassNames, type InvoiceToggleProps, type InvoiceToggleState, entryLabel, fiscalMessages, invoiceCardState, maskTaxId, normalizeTaxId, personTypeByLength, postalCodeProblem, regimesFor, summarizeExtraction, taxIdProblem, toInvoiceRequest, usesFor, validateFiscalValues };
+export { type CameraQrStatus, type DeepPartial, FiscalActionData, FiscalExtractionSummary, FiscalFieldName, FiscalFieldValues, FiscalIdentityFields, type FiscalIdentityFieldsClassNames, type FiscalIdentityFieldsProps, type FiscalMessages, type FiscalProblem, FiscalReadError, type FiscalReaderResult, type FiscalRegion, IdentityDocumentReader, type IdentityDocumentReaderClassNames, type IdentityDocumentReaderProps, type InvoiceCardState, InvoiceStatusCard, type InvoiceStatusCardClassNames, type InvoiceStatusCardProps, InvoiceToggle, type InvoiceToggleClassNames, type InvoiceToggleProps, type InvoiceToggleState, ScanTaxDocument, type ScanTaxDocumentClassNames, type ScanTaxDocumentProps, type UseCameraQr, type UseCameraQrOptions, cameraSupported, entryLabel, fiscalMessages, invoiceCardState, maskTaxId, normalizeTaxId, personTypeByLength, personTypeFromPatterns, personTypeResolver, postalCodeProblem, regimesFor, suggestInvoiceUse, summarizeExtraction, taxIdProblem, toInvoiceRequest, useCameraQr, usesFor, validateFiscalValues };