@nxgt/material 3.101.0 → 3.103.0

package/dist/lib/components/ui/widgets/{calculator/partials/calculator-key.d.ts → keypad/keypad-key.d.ts}

@@ -1,6 +1,6 @@
 import { Ref } from 'react';
-import { KeyDef } from '../variants/key-layout.js';
-export type CalculatorKeyProps = {
+import { KeyDef } from './key-layout.js';
+export type KeypadKeyProps = {
     def: KeyDef;
     row: number;
     index: number;
@@ -12,6 +12,9 @@ export type CalculatorKeyProps = {
     onPress: (def: KeyDef) => void;
     onFocus: (row: number, index: number) => void;
     buttonRef: Ref<HTMLButtonElement>;
+    /** The button's `data-slot` and class (the calculator's by default). */
+    slot?: string;
+    className?: string;
 };
 /** One native button. Its glyph is decoration; the spoken name is the label. */
-export declare function CalculatorKey({ def, row, index, tabIndex, decimal, unavailable, onPress, onFocus, buttonRef, }: CalculatorKeyProps): import("react").JSX.Element;
+export declare function KeypadKey({ def, row, index, tabIndex, decimal, unavailable, onPress, onFocus, buttonRef, slot, className, }: KeypadKeyProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/keypad/keypad-layout.d.ts

@@ -0,0 +1,19 @@
+import { KeyLayout } from './key-layout.js';
+import { KeypadOperation } from './keypad.types.js';
+export type KeypadLayoutOptions = {
+    operations: readonly KeypadOperation[];
+    /** The decimal key; off at no decimals, and when digits go in as minor units. */
+    decimal: boolean;
+    /** The commit key's text and name, when the app names it. */
+    commitLabel?: string;
+    /** True while a calculation waits: the commit key then reads "=". */
+    pending: boolean;
+    /** The cash variant: the commit key tenders. */
+    cash?: boolean;
+};
+/**
+ * Twelve grid units: 7 8 9 C / 4 5 6 ⌫ / 1 2 3 00 / 0 . and the commit key,
+ * with a row of the offered operations above. `wide` makes four keys of three
+ * units; the last row's `0` takes six.
+ */
+export declare function keypadLayout(o: KeypadLayoutOptions): KeyLayout;

package/dist/lib/components/ui/widgets/{calculator/partials → keypad}/keypad-navigation.d.ts

@@ -1,4 +1,4 @@
-import { KeyLayout } from '../variants/key-layout.js';
+import { KeyLayout } from './key-layout.js';
 export type Cell = {
     readonly row: number;
     readonly index: number;

package/dist/lib/components/ui/widgets/keypad/keypad.d.ts

@@ -0,0 +1,9 @@
+import { KeypadProps } from './keypad.types.js';
+/**
+ * `Keypad`: touch and keyboard numeric entry outside the Calculator widget,
+ * for a quantity, a price, a percentage. The digits go in as typed
+ * (`entry="decimal"`) or like a till (`entry="minor"`); `operations` adds
+ * calculation keys. The value is a canonical decimal string. Styled by
+ * `calculator.css`.
+ */
+export declare function Keypad(raw: KeypadProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/keypad/keypad.types.d.ts

@@ -0,0 +1,91 @@
+/** A calculation key the keypad can offer next to the digits. */
+export type KeypadOperation = 'add' | 'subtract' | 'multiply' | 'divide';
+/** What the keypad is for: plain `standard` entry, or a `cash` tender against a `total`. */
+export type KeypadVariant = 'standard' | 'cash';
+/**
+ * The outcome of a cash tender, amounts as canonical decimal text: the
+ * customer gave enough (`change` may be `'0'`), or still owes `due`.
+ */
+export type KeypadSettlement = {
+    readonly status: 'paid';
+    readonly change: string;
+} | {
+    readonly status: 'short';
+    readonly due: string;
+};
+/** How the digits go in: `decimal` as typed (`1`, `2`, `.`, `5` is 12.5), or `minor` like a till (`1`, `2`, `5` is 1.25). */
+export type KeypadEntry = 'decimal' | 'minor';
+/**
+ * A field's number as the keypad reads and writes it (from `useKeypadNumber`
+ * or `useKeypadQuantity`). Pass it whole as the `binding` prop. The field keeps its number while a calculation is typed; `onValueChange` is called with the result at `=`.
+ */
+export type KeypadBinding = {
+    /** The field's number as canonical decimal text (`''` when empty). */
+    value: string;
+    onValueChange: (value: string) => void;
+    /** The decimals the field keeps. */
+    fractionDigits?: number;
+    min?: number;
+    max?: number;
+};
+export type KeypadProps = {
+    /** The value as canonical decimal text (`'12.5'`, `''` when empty). Controlled with `onValueChange`. */
+    value?: string;
+    /** The value of an uncontrolled keypad. */
+    defaultValue?: string;
+    /** Called with the new value text whenever it changes (`''` when emptied); not while a calculation waits for `=`. */
+    onValueChange?: (value: string) => void;
+    /**
+     * The commit key (or Enter): the value, within `min` and `max`, and the
+     * expression that gave it (`'2+3'`; the value itself without operations).
+     * With operations, the key first evaluates a pending calculation.
+     */
+    onCommit?: (value: string, expression: string) => void;
+    /** Calculation keys: `true` offers all four, a list picks some. Off by default; `minor` entry and the `cash` variant take none. */
+    operations?: boolean | readonly KeypadOperation[];
+    /** The locale of the decimal separator, grouping and spoken results; the page's by default. */
+    locale?: string;
+    /** Decimals kept: further digits are refused, a calculation is rounded half-up to them. The currency's by default. */
+    fractionDigits?: number;
+    /** An ISO 4217 code: the amount shows its symbol and takes the currency's decimals. */
+    currency?: string;
+    /** The commit key clamps the value to this floor and ceiling; typing past `max` is refused. */
+    min?: number;
+    max?: number;
+    /**
+     * Where the physical keyboard works: `'focus'` (default) when focus is in
+     * the keypad, `'global'` anywhere on the page outside fields, `false` never.
+     */
+    keyboard?: 'focus' | 'global' | false;
+    /** Key height: `comfortable` (default) or `large` for a till. */
+    size?: 'comfortable' | 'large';
+    /** The commit key's name and text; the translated "Enter" by default. */
+    commitLabel?: string;
+    /** Keys do nothing and say so. */
+    disabled?: boolean;
+    /** `'standard'` (default) or `'cash'`: tender against `total`, with change, bill shortcuts and `onTender`. */
+    variant?: KeypadVariant;
+    /** `cash`: the amount due, as a number or exact decimal text. */
+    total?: number | string;
+    /** `cash`: the bills and coins (`[5, 10, 20, 50]`) whose next round amount at or above `total` is offered as an amount button after the exact total (four buttons at most, none above `max`). A button fills the amount; the commit key tenders. */
+    denominations?: readonly number[];
+    /**
+     * `cash`: the commit key (or Enter) with the amount tendered and the
+     * settlement, once a valid `total` is set and an amount is entered (a missing
+     * or negative `total` does nothing). `onCommit` is not called in this variant. The app owns the charge; the keypad only reports it. A
+     * short payment is a settlement too, not an error.
+     */
+    onTender?: (tendered: string, settlement: KeypadSettlement) => void;
+    /** `'decimal'` (default) or `'minor'`. */
+    entry?: KeypadEntry;
+    /**
+     * A field the keypad types into (`useKeypadNumber`, `useKeypadQuantity`).
+     * Its value, decimals, `min` and `max` apply unless the same prop is given.
+     */
+    binding?: KeypadBinding;
+    /** Shows the amount above the keys: by default when no `binding` is given or `operations` are offered (the field shows the number, not the calculation). */
+    display?: boolean;
+    /** The keypad's accessible name; "Keypad" by default. */
+    label?: string;
+    className?: string;
+};

package/dist/lib/components/ui/widgets/keypad/use-keypad-cash.d.ts

@@ -0,0 +1,14 @@
+import { KeypadProps } from './keypad.types.js';
+import { useKeypad } from './use-keypad.js';
+/**
+ * What the cash variant adds to the keypad: the settlement of what is
+ * tendered so far, the bill shortcuts, and the sentence the live region says
+ * ("Change 2.65", "Still due 1.00"). Nothing for the standard variant.
+ */
+export declare function useKeypadCash(p: Pick<KeypadProps, 'variant' | 'total' | 'denominations' | 'locale' | 'currency' | 'max'>, k: ReturnType<typeof useKeypad>): {
+    cash: boolean;
+    total: string | undefined;
+    settlement: import('./keypad.types.js').KeypadSettlement | undefined;
+    shortcuts: string[];
+    said: string | undefined;
+};

package/dist/lib/components/ui/widgets/keypad/use-keypad-keyboard.d.ts

@@ -0,0 +1,7 @@
+import { useKeypad } from './use-keypad.js';
+/**
+ * The physical keyboard: `onKeyDown` for the keypad's root (the `'focus'`
+ * mode), and with `global` a window listener too. Enter commits, the other
+ * keys press; a key the keypad does not offer is left to the page.
+ */
+export declare function useKeypadKeyboard(k: ReturnType<typeof useKeypad>, locale: string | undefined, global: boolean): (ev: import('react').KeyboardEvent<HTMLElement>) => void;

package/dist/lib/components/ui/widgets/keypad/use-keypad-number.d.ts

@@ -0,0 +1,10 @@
+import { KeypadBinding } from './keypad.types.js';
+import { UseKeypadNumberOptions } from './keypad-binding.js';
+/**
+ * Binds a Keypad to a number field's value (`NumberField`, `PercentField`,
+ * `CurrencyField`, including its `minorUnits`): pass the result as the
+ * keypad's `binding`. The keypad reads the field's number, writes each change
+ * back, holds `min` / `max` and the decimals, and hides its own display unless
+ * `operations` are offered.
+ */
+export declare function useKeypadNumber(options: UseKeypadNumberOptions): KeypadBinding;

package/dist/lib/components/ui/widgets/keypad/use-keypad-quantity.d.ts

@@ -0,0 +1,16 @@
+import { QuantityValue } from '../../fields/quantity-field/types.js';
+import { KeypadBinding } from './keypad.types.js';
+export type UseKeypadQuantityOptions = {
+    /** The QuantityField's value: the amount and its unit. */
+    value: QuantityValue | undefined;
+    /** Called on each change; `value` is `null` when the keypad is emptied. */
+    onChange?: (value: QuantityValue) => void;
+    min?: number;
+    max?: number;
+    fractionDigits?: number;
+};
+/**
+ * Binds a Keypad to a `QuantityField`'s amount: the keypad types the number,
+ * the unit stays as the field holds it.
+ */
+export declare function useKeypadQuantity(options: UseKeypadQuantityOptions): KeypadBinding;

package/dist/lib/components/ui/widgets/keypad/use-keypad-value.d.ts

@@ -0,0 +1,17 @@
+import { CalcSession } from '@nxgt/material-core/calculator';
+import { RefObject } from 'react';
+import { KeypadProps } from './keypad.types.js';
+type ValueOptions = Pick<KeypadProps, 'value' | 'defaultValue' | 'onValueChange'>;
+/**
+ * The keypad's session and its link to the app's value. A controlled `value`
+ * is the truth on every render: when it differs from the value the keypad
+ * last held or reported, the session is replaced by it (the app cleared, set
+ * or refused a change), even while a calculation waits. `report` tells the
+ * app the value, except while a calculation waits for `=`.
+ */
+export declare function useKeypadValue(o: ValueOptions, onValueChange: RefObject<ValueOptions['onValueChange']>): {
+    session: CalcSession;
+    setInner: import('react').Dispatch<import('react').SetStateAction<CalcSession>>;
+    report: (next: CalcSession) => void;
+};
+export {};

package/dist/lib/components/ui/widgets/keypad/use-keypad.d.ts

@@ -0,0 +1,23 @@
+import { CalcKey } from '@nxgt/material-core/calculator';
+import { KeypadProps } from './keypad.types.js';
+type Options = Pick<KeypadProps, 'value' | 'defaultValue' | 'onValueChange' | 'onCommit' | 'variant' | 'total' | 'onTender' | 'operations' | 'fractionDigits' | 'currency' | 'min' | 'max' | 'entry' | 'disabled'>;
+/**
+ * The keypad's state: a calculator session, held as typed. A controlled
+ * `value` is the truth on every render: when it differs from the value the
+ * keypad last held or reported, it replaces the session (the app cleared, set
+ * or refused a change), even while a calculation waits; `onValueChange` fires when a key changes the
+ * value text, not on every key (a `.` or an operator does not) and never
+ * while a calculation waits for `=`.
+ */
+export declare function useKeypad(o: Options): {
+    session: import('@nxgt/material-core/calculator').CalcSession;
+    value: string;
+    pending: boolean;
+    digits: number | undefined;
+    entry: import('./keypad.types.js').KeypadEntry;
+    operations: readonly import('./keypad.types.js').KeypadOperation[];
+    press: (key: CalcKey) => void;
+    commit: () => void;
+    set: (value: string) => void;
+};
+export {};

package/dist/lib/hooks/index.d.ts

@@ -1,6 +1,7 @@
 export * from './resolve-theme.js';
 export * from './unsaved-guard-rules.js';
 export * from './use-allowed-transitions.js';
+export * from './use-barcode-scanner.js';
 export * from './use-countdown.js';
 export { useCspNonce } from './use-csp-nonce.js';
 export * from './use-drafts.js';

package/dist/lib/hooks/use-barcode-scanner.d.ts

@@ -0,0 +1,39 @@
+import { ScannerOptions, ScannerResult } from '@nxgt/material-core/barcode-scanner';
+export { createScanner, DEFAULT_SCANNER_MAX_GAP, DEFAULT_SCANNER_MIN_LENGTH, type Scanner, type ScannerOptions, type ScannerResult, } from '@nxgt/material-core/barcode-scanner';
+export type UseBarcodeScannerOptions = ScannerOptions & {
+    /** Called with the code when a scan ends. The Enter that closed it is swallowed. */
+    onScan: (code: string) => void;
+    /** Off while false: nothing is listened to and nothing is swallowed. Default `true`. */
+    enabled?: boolean;
+    /**
+     * A CSS selector of the form fields a scan is also accepted in (a search
+     * field). A scan is always accepted outside form fields; every other
+     * `input`, `textarea`, `select` and editable element is typed in.
+     */
+    acceptIn?: string;
+    /**
+     * Called for each key the scanner looked at, after it did, with what it
+     * made of the key and the characters buffered so far. A screen with its own
+     * shortcuts skips them while `pending.length > 1`: those keys are a scan's.
+     */
+    onKey?: (event: KeyboardEvent, state: {
+        result: ScannerResult;
+        pending: string;
+    }) => void;
+};
+type KeyTarget = Pick<Document, 'addEventListener' | 'removeEventListener'>;
+/**
+ * The framework-free binding behind `useBarcodeScanner`: one capture-phase
+ * `keydown` listener on `target`. Returns what removes it.
+ */
+export declare function attachBarcodeScanner(target: KeyTarget, { onScan, acceptIn, onKey, maxGap, minLength, }: Omit<UseBarcodeScannerOptions, 'enabled'>): () => void;
+/**
+ * Hears a keyboard-wedge barcode reader anywhere on the page: a run of keys
+ * each within `maxGap` ms (50) of the last, at least `minLength` (4) long,
+ * closed by Enter, reaches `onScan(code)`. Slower or shorter runs are typing
+ * and are left alone, as are Ctrl, Meta and Alt chords and key repeat. Scans
+ * are accepted outside form fields, and in the fields `acceptIn` names. The
+ * callbacks are read from a ref: a new function each render never re-binds
+ * the listener. Does nothing on the server.
+ */
+export declare function useBarcodeScanner(options: UseBarcodeScannerOptions): void;

package/dist/lib/i18n/resources/en/en.d.ts

@@ -70,6 +70,7 @@ export declare const en: {
             processing: string;
             failed: string;
             "form-failed": string;
+            "type-phrase": string;
         };
         "scroll-progress": string;
         "skip-link": string;
@@ -1460,6 +1461,19 @@ export declare const en: {
             invalid: string;
             open: string;
         };
+        "status-menu": {
+            trigger: string;
+            current: string;
+            confirms: string;
+            "confirm-default": string;
+            locked: string;
+            unavailable: string;
+            saving: string;
+            changed: string;
+            failed: string;
+            close: string;
+            choose: string;
+        };
         stepper: {
             step: string;
             completed: string;
@@ -3535,6 +3549,17 @@ export declare const en: {
                 cancel: string;
             };
         };
+        keypad: {
+            commit: string;
+            tender: string;
+            total: string;
+            change: string;
+            due: string;
+            shortcuts: string;
+            "change-label": string;
+            "due-label": string;
+            amount: string;
+        };
         "record-actions": {
             archive: string;
             restore: string;

package/dist/lib/i18n/resources/en/material.json.d.ts

@@ -59,7 +59,8 @@ declare const _default: {
 		"cancel": "Cancel",
 		"processing": "Processing...",
 		"failed": "The action failed.",
-		"form-failed": "The form could not be loaded."
+		"form-failed": "The form could not be loaded.",
+		"type-phrase": "Type {phrase} to confirm"
 	},
 	"scroll-progress": "Scroll progress",
 	"skip-link": "Skip to content",
@@ -1450,6 +1451,19 @@ declare const _default: {
 		"invalid": "Enter a valid URL",
 		"open": "Open URL"
 	},
+	"status-menu": {
+		"trigger": "Status of {label}: {status}",
+		"current": "Current status",
+		"confirms": "Asks first",
+		"confirm-default": "Change the status to {label}?",
+		"locked": "Locked",
+		"unavailable": "Not available from {status}",
+		"saving": "Saving the status of {label}",
+		"changed": "Status of {label} changed to {status}",
+		"failed": "The status of {label} could not be changed",
+		"close": "Close",
+		"choose": "Choose a status"
+	},
 	"stepper": {
 		"step": "Step {step}",
 		"completed": "Completed",
@@ -3525,6 +3539,17 @@ declare const _default: {
 			"cancel": "Cancel"
 		}
 	},
+	"keypad": {
+		"commit": "Enter",
+		"tender": "Tender",
+		"total": "Total",
+		"change": "Change {amount}",
+		"due": "Still due {amount}",
+		"shortcuts": "Quick amounts",
+		"change-label": "Change",
+		"due-label": "Still due",
+		"amount": "Amount {amount}"
+	},
 	"record-actions": {
 		"archive": "Archive",
 		"restore": "Restore",

package/dist/lib/i18n/resources/fr/fr.d.ts

@@ -70,6 +70,7 @@ export declare const fr: {
             processing: string;
             failed: string;
             "form-failed": string;
+            "type-phrase": string;
         };
         "scroll-progress": string;
         "skip-link": string;
@@ -1460,6 +1461,19 @@ export declare const fr: {
             invalid: string;
             open: string;
         };
+        "status-menu": {
+            trigger: string;
+            current: string;
+            confirms: string;
+            "confirm-default": string;
+            locked: string;
+            unavailable: string;
+            saving: string;
+            changed: string;
+            failed: string;
+            close: string;
+            choose: string;
+        };
         stepper: {
             step: string;
             completed: string;
@@ -3535,6 +3549,17 @@ export declare const fr: {
                 cancel: string;
             };
         };
+        keypad: {
+            commit: string;
+            tender: string;
+            total: string;
+            change: string;
+            due: string;
+            shortcuts: string;
+            "change-label": string;
+            "due-label": string;
+            amount: string;
+        };
         "record-actions": {
             archive: string;
             restore: string;

package/dist/lib/i18n/resources/fr/material.json.d.ts

@@ -59,7 +59,8 @@ declare const _default: {
 		"cancel": "Annuler",
 		"processing": "Traitement en cours…",
 		"failed": "L’action a échoué.",
-		"form-failed": "Le formulaire n’a pas pu être chargé."
+		"form-failed": "Le formulaire n’a pas pu être chargé.",
+		"type-phrase": "Saisissez {phrase} pour confirmer"
 	},
 	"scroll-progress": "Progression du défilement",
 	"skip-link": "Aller au contenu",
@@ -1450,6 +1451,19 @@ declare const _default: {
 		"invalid": "Saisissez une URL valide",
 		"open": "Ouvrir l’URL"
 	},
+	"status-menu": {
+		"trigger": "Statut de {label} : {status}",
+		"current": "Statut actuel",
+		"confirms": "Demande confirmation",
+		"confirm-default": "Changer le statut en {label} ?",
+		"locked": "Verrouillé",
+		"unavailable": "Indisponible depuis {status}",
+		"saving": "Enregistrement du statut de {label}",
+		"changed": "Statut de {label} changé en {status}",
+		"failed": "Le statut de {label} n'a pas pu être changé",
+		"close": "Fermer",
+		"choose": "Choisir un statut"
+	},
 	"stepper": {
 		"step": "Étape {step}",
 		"completed": "Terminée",
@@ -3525,6 +3539,17 @@ declare const _default: {
 			"cancel": "Annuler"
 		}
 	},
+	"keypad": {
+		"commit": "Valider",
+		"tender": "Encaisser",
+		"total": "Total",
+		"change": "Monnaie à rendre {amount}",
+		"due": "Reste à payer {amount}",
+		"shortcuts": "Montants rapides",
+		"change-label": "Monnaie",
+		"due-label": "Reste à payer",
+		"amount": "Montant {amount}"
+	},
 	"record-actions": {
 		"archive": "Archiver",
 		"restore": "Restaurer",

package/dist/lib/i18n/resources/resources.d.ts

@@ -68,6 +68,7 @@ export declare const resources: {
                 processing: string;
                 failed: string;
                 "form-failed": string;
+                "type-phrase": string;
             };
             "scroll-progress": string;
             "skip-link": string;
@@ -1458,6 +1459,19 @@ export declare const resources: {
                 invalid: string;
                 open: string;
             };
+            "status-menu": {
+                trigger: string;
+                current: string;
+                confirms: string;
+                "confirm-default": string;
+                locked: string;
+                unavailable: string;
+                saving: string;
+                changed: string;
+                failed: string;
+                close: string;
+                choose: string;
+            };
             stepper: {
                 step: string;
                 completed: string;
@@ -3533,6 +3547,17 @@ export declare const resources: {
                     cancel: string;
                 };
             };
+            keypad: {
+                commit: string;
+                tender: string;
+                total: string;
+                change: string;
+                due: string;
+                shortcuts: string;
+                "change-label": string;
+                "due-label": string;
+                amount: string;
+            };
             "record-actions": {
                 archive: string;
                 restore: string;
@@ -3668,6 +3693,7 @@ export declare const resources: {
                 processing: string;
                 failed: string;
                 "form-failed": string;
+                "type-phrase": string;
             };
             "scroll-progress": string;
             "skip-link": string;
@@ -5058,6 +5084,19 @@ export declare const resources: {
                 invalid: string;
                 open: string;
             };
+            "status-menu": {
+                trigger: string;
+                current: string;
+                confirms: string;
+                "confirm-default": string;
+                locked: string;
+                unavailable: string;
+                saving: string;
+                changed: string;
+                failed: string;
+                close: string;
+                choose: string;
+            };
             stepper: {
                 step: string;
                 completed: string;
@@ -7133,6 +7172,17 @@ export declare const resources: {
                     cancel: string;
                 };
             };
+            keypad: {
+                commit: string;
+                tender: string;
+                total: string;
+                change: string;
+                due: string;
+                shortcuts: string;
+                "change-label": string;
+                "due-label": string;
+                amount: string;
+            };
             "record-actions": {
                 archive: string;
                 restore: string;