@nxgt/material 3.75.0 → 3.76.0

package/dist/lib/components/ui/widgets/calculator/calculator-announce.d.ts

@@ -0,0 +1,27 @@
+import { AngleMode, CalcErrorCode, CalcKey, CalcSession } from '@nxgt/material-core/calculator';
+import { MaterialLocaleKey } from '../../../../i18n/types.js';
+import { ResultNotation } from './engine.js';
+import { ProgrammerState } from './variants/programmer/programmer-word.js';
+/** What the live region says: a `material.*` key, its English text and values. */
+export type Announcement = {
+    readonly key: MaterialLocaleKey;
+    readonly fallback: string;
+    readonly values?: Readonly<Record<string, string | number>>;
+};
+/** The engine's error codes as the `material.calculator.error.*` leaves. */
+export declare const ERROR_KEYS: Readonly<Record<CalcErrorCode, MaterialLocaleKey>>;
+/** The memory, as a number in `locale`. */
+export declare function memoryText(memory: string, locale?: string): string;
+/**
+ * What the live region says after `key`: the result after `=`, an error when
+ * one appears, and the memory keys. Nothing for the others (typing is not
+ * announced).
+ */
+export declare function announceKey(key: CalcKey, prev: CalcSession, next: CalcSession, locale?: string, programmer?: ProgrammerState): Announcement | null;
+export declare const message: (name: "copied" | "pasted") => Announcement;
+/** The live region's words when the angle unit changes. */
+export declare const angleMessage: (mode: AngleMode) => Announcement;
+/** The live region's words when the result notation changes. */
+export declare const notationMessage: (notation: ResultNotation) => Announcement;
+/** The live region's words when 2nd turns the second functions on or off. */
+export declare const secondMessage: (on: boolean) => Announcement;

package/dist/lib/components/ui/widgets/calculator/calculator-clipboard.d.ts

@@ -0,0 +1,19 @@
+import { Announcement } from './calculator-announce.js';
+import { ProgrammerState } from './variants/programmer/programmer-word.js';
+export type CopyDeps = {
+    /** Writes text to the clipboard; rejects when it cannot. */
+    write: (text: string) => Promise<void>;
+    announce: (m: Announcement) => void;
+};
+/**
+ * Copies the exact value shown (canonical `value`) in the locale's decimal,
+ * without grouping; the Programmer variant copies it in the base shown, which
+ * a paste reads back. A refusal (no clipboard, denied) copies nothing and says
+ * nothing; the result is whether the text was written.
+ */
+export declare function copyResult(value: string, locale: string | undefined, deps: CopyDeps, programmer?: ProgrammerState): Promise<boolean>;
+/**
+ * The text of the clipboard for the Paste button, or `''` when it is empty,
+ * missing or denied. A keyboard paste uses the paste event's own data.
+ */
+export declare function readClipboardText(read: (() => Promise<string>) | undefined): Promise<string>;

package/dist/lib/components/ui/widgets/calculator/calculator-context.d.ts

@@ -0,0 +1,49 @@
+import { AngleMode, CalcKey, HistoryEntry, RoundingMode } from '@nxgt/material-core/calculator';
+import { RefObject } from 'react';
+import { DisplayModel } from './calculator.selectors.js';
+import { CalculatorState } from './calculator.slice.js';
+import { ResultNotation } from './engine.js';
+import { CalculatorRatesSource, CalculatorVariant } from './types.js';
+import { PosModel } from './use-calculator-pos.js';
+import { ProgrammerAction } from './variants/programmer/programmer-reduce.js';
+import { VariantDefinition } from './variants/registry.js';
+export type CalculatorContextValue = {
+    state: CalculatorState;
+    variant: CalculatorVariant;
+    definition: VariantDefinition;
+    variants: readonly CalculatorVariant[];
+    locale: string | undefined;
+    /** What the conversion variant needs: the rates and how to round. */
+    conversion: {
+        readonly currencyRates: CalculatorRatesSource | undefined;
+        readonly precision: number | undefined;
+        readonly rounding: RoundingMode | undefined;
+    };
+    /** ISO 4217 code of the amounts of the variants that show money. */
+    currency: string | undefined;
+    display: DisplayModel;
+    hasMemory: boolean;
+    press: (key: CalcKey) => void;
+    setVariant: (variant: CalculatorVariant) => void;
+    /** Scientific chrome. */
+    setAngle: (angle: AngleMode) => void;
+    setNotation: (notation: ResultNotation) => void;
+    toggleSecond: (on?: boolean) => void;
+    /** Programmer chrome: the base, the word, a bit. */
+    setProgrammer: (action: ProgrammerAction) => void;
+    replay: (entry: HistoryEntry) => void;
+    reuse: (entry: HistoryEntry) => void;
+    clearTape: () => void;
+    toggleTape: () => void;
+    copy: () => void;
+    paste: () => void;
+    /** A keyboard paste: the text of the paste event. */
+    pasteText: (text: string) => void;
+    /** The point-of-sale panel: its options, its ticket's view and its actions. */
+    pos: PosModel;
+    /** The history toggle and the tape: focus goes to the tape on open. */
+    toggleRef: RefObject<HTMLButtonElement | null>;
+    tapeRef: RefObject<HTMLDivElement | null>;
+};
+export declare const CalculatorProvider: import('react').Provider<CalculatorContextValue | null>;
+export declare function useCalculatorContext(): CalculatorContextValue;

package/dist/lib/components/ui/widgets/calculator/calculator-feedback.d.ts

@@ -0,0 +1,18 @@
+import { CalculatorFeedback } from './types.js';
+/** The browser pieces feedback uses; tests pass stubs. */
+export type FeedbackEnv = {
+    vibrate?: (ms: number) => boolean;
+    reducedMotion: () => boolean;
+    audio?: () => {
+        tick: () => void;
+    } | undefined;
+};
+export declare const HAPTIC_MS = 8;
+/** Fires the enabled kinds for one key press. Never throws; off by default. */
+export declare function fireFeedback(feedback: CalculatorFeedback | undefined, env: FeedbackEnv): void;
+/** A tick made on demand by one shared oscillator-per-press, created on the first one. */
+export declare function createTick(): () => {
+    tick: () => void;
+} | undefined;
+/** The real browser's pieces. */
+export declare function browserFeedbackEnv(audio: FeedbackEnv['audio']): FeedbackEnv;

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

@@ -0,0 +1,30 @@
+import { CalcKey, KeyAction, KeyEventLike } from '@nxgt/material-core/calculator';
+/** The slice of an event target the rules read; a DOM `Element` fits. */
+export type KeyTargetLike = {
+    readonly tagName?: string;
+    readonly isContentEditable?: boolean;
+    closest?: (selector: string) => unknown;
+};
+export type CalculatorKeyEvent = KeyEventLike & {
+    readonly target?: KeyTargetLike | EventTarget | null;
+    readonly defaultPrevented?: boolean;
+    readonly repeat?: boolean;
+};
+export type KeyboardContext = {
+    readonly locale?: string;
+    /** Whether the variant takes a key; others are left to the page. */
+    readonly accepts: (key: CalcKey) => boolean;
+    /** The window listener: leaves fields alone and events already handled. */
+    readonly global?: boolean;
+    /** The Programmer variant: `a` to `f` are digits. */
+    readonly programmer?: boolean;
+    /** True when the user has text selected: a copy is then the browser's. */
+    readonly hasSelection?: () => boolean;
+};
+export declare function isEditableTarget(target: KeyTargetLike | null | undefined): boolean;
+/**
+ * The action a key event stands for in this calculator, or `null` to leave it
+ * to the browser. Enter on a focused button is that button's click, never
+ * `=`, so a keyboard user is not made to calculate by activating a key.
+ */
+export declare function actionForKeyEvent(ev: CalculatorKeyEvent, ctx: KeyboardContext): KeyAction | null;

package/dist/lib/components/ui/widgets/calculator/calculator-storage.d.ts

@@ -0,0 +1,17 @@
+import { HistoryEntry } from '@nxgt/material-core/calculator';
+/** The part of `Storage` the calculator uses; tests pass a map. */
+export type CalculatorStorage = Pick<Storage, 'getItem' | 'setItem'>;
+export type StoredCalculator = {
+    history: HistoryEntry[];
+    memory: string;
+};
+/** `localStorage`, or `undefined` where it is missing or blocked. */
+export declare function browserStorage(): CalculatorStorage | undefined;
+/** The slot name from the `persist` prop; `undefined` when persistence is off. */
+export declare function storageSlot(persist: boolean | {
+    key: string;
+} | undefined): string | undefined;
+/** What the slot holds; anything unreadable gives an empty tape and memory `0`. Never throws. */
+export declare function readStored(storage: CalculatorStorage | undefined, slot: string): StoredCalculator;
+/** Writes the slot; a full or blocked storage is ignored. */
+export declare function writeStored(storage: CalculatorStorage | undefined, slot: string, value: StoredCalculator): void;

package/dist/lib/components/ui/widgets/calculator/calculator-variant-steps.d.ts

@@ -0,0 +1,16 @@
+import { CalculatorState } from './calculator.slice.js';
+import { PosFormat } from './variants/pos/pos-announce.js';
+import { PosAction, PosEnv } from './variants/pos/pos-types.js';
+import { ProgrammerAction } from './variants/programmer/programmer-reduce.js';
+/**
+ * One point-of-sale action on the state: the ticket's maths come with the
+ * point-of-sale chunk, and its actions only come from that variant's panels,
+ * so it is loaded by then (nothing happens otherwise).
+ */
+export declare function stepPos(state: CalculatorState, p: {
+    action: PosAction;
+    env: PosEnv;
+    format: PosFormat;
+}): void;
+/** One Programmer action on the state, once the Programmer chunk is loaded. */
+export declare function stepProgrammer(state: CalculatorState, action: ProgrammerAction): void;

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

@@ -0,0 +1,11 @@
+import { CalculatorProps } from './types.js';
+/**
+ * A calculator with exact decimal arithmetic and the usual precedence
+ * (`2 + 3 × 4` is 14): a display with the expression above the result, a
+ * keypad, a tape of past results, a memory, the physical keyboard, copy and
+ * paste, and a variant switcher. The engine is `@nxgt/material-core/calculator`;
+ * nothing is evaluated as code.
+ *
+ * Own entry, `@nxgt/material/calculator`: not exported from `./components`.
+ */
+export declare function Calculator({ className, 'aria-label': ariaLabel, ...props }: CalculatorProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/calculator/calculator.selectors.d.ts

@@ -0,0 +1,23 @@
+import { CalcErrorCode } from '@nxgt/material-core/calculator';
+import { CalculatorState } from './calculator.slice.js';
+import { EngineSettings } from './engine.js';
+export type DisplayModel = {
+    /** The expression, shown in the locale. */
+    expression: string;
+    /** The big line: the result, a live preview, or `0`. */
+    result: string;
+    kind: 'empty' | 'preview' | 'result' | 'error';
+    /** The exact value to copy (canonical text), or `''`. */
+    value: string;
+    error: CalcErrorCode | '';
+};
+/** The expression without the operator the user is about to follow with a number. */
+export declare const withoutTrailingOperator: (expression: string) => string;
+export declare function selectDisplay(state: CalculatorState, settings: EngineSettings): DisplayModel;
+export declare const selectHasMemory: (state: CalculatorState) => boolean;
+export declare const selectCanClearTape: (state: CalculatorState) => boolean;
+export declare const calculatorSelectors: {
+    selectDisplay: typeof selectDisplay;
+    selectHasMemory: (state: CalculatorState) => boolean;
+    selectCanClearTape: (state: CalculatorState) => boolean;
+};