@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/input.cjs

@@ -0,0 +1,163 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_money = require("./money-B3wH_Z4S.cjs");
+const require_number_text = require("./number-text-BWu67jUq.cjs");
+const require_rate = require("./rate-CVeMii4a.cjs");
+const require_amount = require("./amount-BV0O-aN8.cjs");
+//#region src/input/import.ts
+/**
+* Amount text from a file or a third party to canonical DecimalText (major units, exactly as
+* written: `'1.299,00'` gives `'1299'`), or null when it is not an amount (empty, exponent,
+* hex, garbage, negative without `allowNegative`). Never 0 for bad input.
+*/
+function parseImportAmount(text, options = {}) {
+	const read = require_number_text.readNumberText(text, {
+		decimalSeparator: options.decimalSeparator ?? "auto",
+		currency: options.currency,
+		allowTrailingText: options.allowTrailingText
+	});
+	if ("reason" in read || read.sign < 0 && !options.allowNegative) return null;
+	return require_money.toDecimalText(require_amount.decimalOfText(read));
+}
+/**
+* Strict decimal entry: `.` decimal, no grouping, at most `maxDecimals` fraction digits (cost
+* entry at 4, metafields). `'4.5'` gives `'4.5'`, `'.5'` gives `'0.5'`; `'1,000'` is `'unparseable'`.
+*/
+function parseDecimalInput(text, options) {
+	const read = require_number_text.readNumberText(text, {
+		decimalSeparator: ".",
+		groupSeparator: null
+	});
+	if ("reason" in read) return {
+		ok: false,
+		reason: read.reason
+	};
+	const value = require_amount.decimalOfText(read);
+	if (require_money.fractionDigitsOf(value) > options.maxDecimals) return {
+		ok: false,
+		reason: "too_many_decimals"
+	};
+	if (value.units < 0n && !options.allowNegative) return {
+		ok: false,
+		reason: "negative"
+	};
+	if (options.min !== void 0 && require_money.compareDecimal(value, require_money.decimalOf(options.min)) < 0) return {
+		ok: false,
+		reason: "below_min"
+	};
+	if (options.max !== void 0 && require_money.compareDecimal(value, require_money.decimalOf(options.max)) > 0) return {
+		ok: false,
+		reason: "above_max"
+	};
+	return {
+		ok: true,
+		value: require_money.toDecimalText(value)
+	};
+}
+//#endregion
+//#region src/input/percent-rate.ts
+/**
+* A typed percent (`'20'`, `'12.5'`, `'12,5 %'` in de-DE) as DecimalText. A `%` before or after
+* the number is allowed. Default range 0..100 with 2 decimals; below 0 (with a non-negative
+* `min`) is `'negative'`.
+*/
+function parsePercentInput(text, options = {}) {
+	const bare = typeof text === "string" ? text.trim().replace(/^%\s*|\s*%$/g, "") : text;
+	const read = require_number_text.readNumberText(bare, require_amount.localeSeparators(options.locale));
+	if ("reason" in read) return {
+		ok: false,
+		reason: read.reason
+	};
+	const value = require_amount.decimalOfText(read);
+	const min = require_money.decimalOf(options.min ?? 0, true, "min");
+	const max = require_money.decimalOf(options.max ?? 100, true, "max");
+	if (require_money.fractionDigitsOf(value) > (options.maxDecimals ?? 2)) return {
+		ok: false,
+		reason: "too_many_decimals"
+	};
+	if (require_money.compareDecimal(value, min) < 0) return {
+		ok: false,
+		reason: value.units < 0n && min.units >= 0n ? "negative" : "below_min"
+	};
+	if (require_money.compareDecimal(value, max) > 0) return {
+		ok: false,
+		reason: "above_max"
+	};
+	return {
+		ok: true,
+		value: require_money.toDecimalText(value)
+	};
+}
+/**
+* A typed exchange rate ("1 store-currency unit equals this many units") as a precise Rate
+* (`fx.rateFromDecimal(value, { encoding: 'precise' })`), or null when the text is not a
+* positive number or the rate is outside `RATE_BOUNDS` (0.0000001 to 1000000000).
+*/
+function parseRateInput(text, options = {}) {
+	const read = require_number_text.readNumberText(text, require_amount.localeSeparators(options.locale));
+	if ("reason" in read || read.sign < 0 || read.units === 0n) return null;
+	try {
+		const precise = require_rate.rateFromDecimal(require_money.formatDecimal(require_amount.decimalOfText(read)), { encoding: "precise" });
+		return require_rate.rate(precise.numerator, precise.denominator);
+	} catch (error) {
+		if (error instanceof require_money.MoneyError && error.code === "rate_invalid") return null;
+		throw error;
+	}
+}
+//#endregion
+//#region src/input/template.ts
+const DEFAULT_TEMPLATE = Object.freeze({
+	prefix: "",
+	suffix: "",
+	fractionDigits: 2,
+	decimalSeparator: ".",
+	groupSeparator: ","
+});
+const NUMBER_RUN = /\d[\d.,'’\s]*\d|\d/u;
+const counterpart = (separator) => separator === "," ? "." : ",";
+/**
+* The print template of one captured literal (cloner `analyzeMoneyFormat`): prefix and suffix
+* around the number, the decimal separator and digit count of its fraction (1 or 2 digits
+* read as 2, 3 as 3, none as 0), the separator it groups thousands with (else the decimal's
+* counterpart), all as the separator engine's `'auto'` rule reads them. A
+* sample with no number gives `{ prefix: '', suffix: '', fractionDigits: 2, '.', ',' }`.
+*/
+function moneyTemplateOf(sample) {
+	const text = typeof sample === "string" ? sample : "";
+	const run = NUMBER_RUN.exec(text);
+	if (!run) return DEFAULT_TEMPLATE;
+	const read = require_number_text.readNumberText(run[0], { decimalSeparator: "auto" });
+	if ("reason" in read) return DEFAULT_TEMPLATE;
+	const decimalSeparator = read.decimalMark ?? counterpart(read.groupMark ?? ",");
+	return Object.freeze({
+		prefix: text.slice(0, run.index),
+		suffix: text.slice(run.index + run[0].length),
+		fractionDigits: read.scale === 0 ? 0 : read.scale === 3 ? 3 : 2,
+		decimalSeparator,
+		groupSeparator: read.groupMark ?? counterpart(decimalSeparator)
+	});
+}
+/**
+* Money printed with a captured template: the exact major amount (stored / storageScale)
+* rounded half-up to the template's digits, grouped, the sign after the prefix
+* (`moneyTemplateOf('Rp 199.000')` prints IDR 2500050 as `'Rp 25.001'`).
+*/
+function formatWithTemplate(m, template) {
+	const { value } = require_money.storedDecimal(m);
+	const rounded = require_money.formatDecimal(require_money.roundToScale(value, template.fractionDigits, "half-up"));
+	const negative = rounded.startsWith("-");
+	const [whole, fraction] = (negative ? rounded.slice(1) : rounded).split(".");
+	const grouped = require_amount.groupDigits(whole, template.groupSeparator);
+	const tail = fraction === void 0 ? "" : `${template.decimalSeparator}${fraction}`;
+	return `${template.prefix}${negative ? "-" : ""}${grouped}${tail}${template.suffix}`;
+}
+//#endregion
+exports.formatAmountInput = require_amount.formatAmountInput;
+exports.formatWithTemplate = formatWithTemplate;
+exports.inputPlaceholder = require_amount.inputPlaceholder;
+exports.inputStep = require_amount.inputStep;
+exports.moneyTemplateOf = moneyTemplateOf;
+exports.parseAmountInput = require_amount.parseAmountInput;
+exports.parseDecimalInput = parseDecimalInput;
+exports.parseImportAmount = parseImportAmount;
+exports.parsePercentInput = parsePercentInput;
+exports.parseRateInput = parseRateInput;

package/dist/input.d.cts

@@ -0,0 +1,203 @@
+import { R as DecimalText, b as FractionDigits, i as Money } from "./money-B-3aFjNJ.cjs";
+import { r as Rate } from "./rate-tqK8ijG0.cjs";
+//#region src/input/amount.d.ts
+/** Why typed text is not an acceptable amount. */
+type ParseFailureReason = 'empty' | 'unparseable' | 'too_many_decimals' | 'negative' | 'zero' | 'below_min' | 'above_max';
+interface ParseAmountInputOptions {
+  /**
+   * Decides the decimal and group separators (unsupported tags fall back to `'en-US'`). Absent
+   * (default): the 'auto' rule of `parseImportAmount`, today's admin price-entry rule except the
+   * listed behaviour changes: the text and the currency decide (`'29,99'` EUR is 29.99,
+   * `'1.299,00'` is 1299, KWD `'1,5'` is 1.5), and a currency storing 0 digits rounds a
+   * fraction half-up to a whole unit (`'1200.5'` JPY is 1201).
+   */
+  locale?: string;
+  /**
+   * `'.'`: machine decimal text, the value of an `<input type="number">` (browsers always
+   * serialise it with a `.` decimal and no grouping). `.` is the decimal (`'.5'` is 0.5), `,`
+   * and any grouping are `'unparseable'`, and a currency storing 0 digits rounds a fraction
+   * half-up to a whole unit, as admin `numericEntryToMinorUnits` does (`'1200.5'` JPY is
+   * 1201, `'1.500'` JPY is 2). TND and IQD `'1.500'` are 1.5. Extra fraction digits in a
+   * currency with decimals are `'too_many_decimals'`, never rounded. Every number input must
+   * use it; not with `locale`.
+   */
+  decimalSeparator?: '.';
+  /** Default false: a leading `-` gives `'negative'`. */
+  allowNegative?: boolean;
+  /** Default true; false gives `'zero'` for a zero amount. */
+  allowZero?: boolean;
+  /** Inclusive lower bound, in the same currency. */
+  min?: Money;
+  /** Inclusive upper bound, in the same currency. */
+  max?: Money;
+  /**
+   * The stored amount the field was prefilled with (`formatAmountInput(original)`). Text whose
+   * value equals it returns `original` unchanged, even when it has more fraction digits than
+   * the currency stores (JPY 120050 shows `'1200.50'`), so saving an untouched field never
+   * rewrites the amount. Any other text is held to the normal rule. Must be in `currency`.
+   */
+  original?: Money;
+}
+/**
+ * `text` is the canonical machine text on success (`'1250.00'`, `'1200'`, `'1.500'`: the major
+ * amount at the currency's storage digits) and the trimmed input on failure.
+ */
+type ParseAmountResult = {
+  readonly ok: true;
+  readonly money: Money;
+  readonly text: string;
+} | {
+  readonly ok: false;
+  readonly reason: ParseFailureReason;
+  readonly text: string;
+};
+/**
+ * Typed text to Money, one rule for every money field: the currency's symbols and code and all
+ * whitespace are stripped; a leading `-` or U+2212 is the sign.
+ * - Without `locale` (the chat wizard, any field with no locale): the 'auto' rule decides `.`
+ *   against `,` (see `parseImportAmount`): `'29,99'` EUR is 29.99, `'1.299,00'` and `'1,299'`
+ *   are 1299, KWD `'1,5'` is 1.5; a currency storing 0 digits rounds a fraction half-up to a
+ *   whole unit (`'1200.5'` JPY is 1201).
+ * - With `locale`: its decimal separator is the decimal and its group separator is valid only in
+ *   3-digit (or Indian lakh) groups; in a currency that stores no fraction (JPY, VND) a separator
+ *   before exactly three digits in grouping position is grouping (`'1.500'` JPY is 1500).
+ *   en-US `'29,99'` USD is `'unparseable'`; de-DE `'29,99'` EUR is 29.99; en-US `'1200.5'` JPY
+ *   is `'too_many_decimals'`.
+ * - With `decimalSeparator: '.'` (every `<input type="number">`): `.` is the decimal, nothing
+ *   groups (`'1,299'` is `'unparseable'`), TND and IQD `'1.500'` are 1.5, and a currency storing
+ *   0 digits rounds a fraction half-up to a whole unit (`'1.5'` JPY is 2).
+ * Otherwise more fraction digits than the currency stores is `'too_many_decimals'`, never rounded
+ * (`'1,2345'` USD). Text equal to `original` returns it unchanged (JPY 120050 shown as
+ * `'1200.50'`). An unknown currency, or an `original` in another currency, throws.
+ */
+export declare function parseAmountInput(text: string, currency: string, options?: ParseAmountInputOptions): ParseAmountResult;
+/**
+ * The text a money field shows for a stored amount, no symbol, exact: a stored amount finer than
+ * the storage digits keeps its digits (JPY 120050 is never rounded on display).
+ * - Without `locale`: the spelling `parseAmountInput` reads back without a locale. Trailing
+ *   fraction zeros are dropped (`'12.5'`, `'1200'`, KWD 1500 is `'1.5'`, JPY 120050 is
+ *   `'1200.5'`), a currency written with a decimal comma (TND, `commaDecimal`) uses `,` and
+ *   groups with `.` (`'1,125'`, `'1.234,5'`), every other currency `.` and `,`. Two amounts have no
+ *   such spelling: IQD with a three-digit fraction (`'1.125'` reads as 1125, IQD displays no
+ *   decimals) and a sub-unit amount of a currency storing 0 digits (`'1200.5'` JPY reads as a
+ *   whole 1201); pass `{ original: m }` so the untouched text returns `m` itself.
+ * - With `locale`: its decimal and group separators and the storage digits (`'12,50'` de-DE).
+ * - With `decimalSeparator: '.'` (the value of an `<input type="number">`): `.` decimal, never
+ *   grouped, trailing zeros dropped (TND 1500 is `'1.5'`, JPY 120050 `'1200.5'`), read back
+ *   exactly by `parseAmountInput(text, currency, { decimalSeparator: '.' })` (JPY sub-unit
+ *   amounts through `original`).
+ * `grouped` adds group separators (not in `'.'` mode); `digits` overrides the zeros
+ * (`'storage'` keeps them, `'trim-zero'` drops them).
+ */
+export declare function formatAmountInput(m: Money, options?: {
+  locale?: string;
+  decimalSeparator?: '.';
+  grouped?: boolean;
+  digits?: 'storage' | 'trim-zero';
+}): string;
+/** The `step` of a money number input: `'1'` (JPY), `'0.01'` (USD), `'0.001'` (KWD), from the storage digits. */
+export declare function inputStep(currency: string): '1' | '0.01' | '0.001';
+/** The placeholder of a money input: `'0'`, `'0.00'` or `'0.000'`, from the storage digits. */
+export declare function inputPlaceholder(currency: string): '0' | '0.00' | '0.000';
+//#endregion
+//#region src/input/import.d.ts
+interface ImportAmountOptions {
+  /**
+   * `'auto'` (default): spaces, NBSP, thin spaces and apostrophes are grouping, and the
+   * separator engine's 'auto' rule decides `.` against `,` (`'1.299,00'`, `'1.299'` and
+   * `'1,299'` are 1299, `'29,99'` is 29.99, `'0,500'` is 0.5, KWD `'1.500'` is 1.5; a `currency`
+   * storing 0 digits rounds to a whole unit). An explicit separator validates 3-digit groups of the other.
+   */
+  decimalSeparator?: '.' | ',' | 'auto';
+  /** Strips this currency's symbols and code, and decides the 3-digit rule above. */
+  currency?: string;
+  /** Default false: a negative amount gives null. */
+  allowNegative?: boolean;
+  /** Read the first numeric run and ignore the rest (`'22.67 + KDV'`, `'$1,299.00 incl. VAT'`). Default false. */
+  allowTrailingText?: boolean;
+}
+/**
+ * Amount text from a file or a third party to canonical DecimalText (major units, exactly as
+ * written: `'1.299,00'` gives `'1299'`), or null when it is not an amount (empty, exponent,
+ * hex, garbage, negative without `allowNegative`). Never 0 for bad input.
+ */
+export declare function parseImportAmount(text: string, options?: ImportAmountOptions): DecimalText | null;
+interface DecimalInputOptions {
+  /** Most fraction digits allowed (trailing zeros do not count). */
+  maxDecimals: number;
+  /** Inclusive bounds, decimal text. */
+  min?: DecimalText | string;
+  max?: DecimalText | string;
+  /** Default false. */
+  allowNegative?: boolean;
+}
+/**
+ * Strict decimal entry: `.` decimal, no grouping, at most `maxDecimals` fraction digits (cost
+ * entry at 4, metafields). `'4.5'` gives `'4.5'`, `'.5'` gives `'0.5'`; `'1,000'` is `'unparseable'`.
+ */
+export declare function parseDecimalInput(text: string, options: DecimalInputOptions): {
+  ok: true;
+  value: DecimalText;
+} | {
+  ok: false;
+  reason: ParseFailureReason;
+};
+//#endregion
+//#region src/input/percent-rate.d.ts
+interface PercentInputOptions {
+  /** Inclusive, default 0. */
+  min?: number;
+  /** Inclusive, default 100. */
+  max?: number;
+  /** Default 2. */
+  maxDecimals?: number;
+  /** Decides the separators; default `'en-US'`. */
+  locale?: string;
+}
+/**
+ * A typed percent (`'20'`, `'12.5'`, `'12,5 %'` in de-DE) as DecimalText. A `%` before or after
+ * the number is allowed. Default range 0..100 with 2 decimals; below 0 (with a non-negative
+ * `min`) is `'negative'`.
+ */
+export declare function parsePercentInput(text: string, options?: PercentInputOptions): {
+  ok: true;
+  value: DecimalText;
+} | {
+  ok: false;
+  reason: ParseFailureReason;
+};
+/**
+ * A typed exchange rate ("1 store-currency unit equals this many units") as a precise Rate
+ * (`fx.rateFromDecimal(value, { encoding: 'precise' })`), or null when the text is not a
+ * positive number or the rate is outside `RATE_BOUNDS` (0.0000001 to 1000000000).
+ */
+export declare function parseRateInput(text: string, options?: {
+  locale?: string;
+}): Rate | null;
+//#endregion
+//#region src/input/template.d.ts
+interface MoneyTemplate {
+  /** Text before the number (`'Rp '`, `'€'`), the sign goes after it. */
+  readonly prefix: string;
+  /** Text after the number (`' CHF'`, `' ₫'`). */
+  readonly suffix: string;
+  readonly fractionDigits: FractionDigits;
+  readonly decimalSeparator: string;
+  readonly groupSeparator: string;
+}
+/**
+ * The print template of one captured literal (cloner `analyzeMoneyFormat`): prefix and suffix
+ * around the number, the decimal separator and digit count of its fraction (1 or 2 digits
+ * read as 2, 3 as 3, none as 0), the separator it groups thousands with (else the decimal's
+ * counterpart), all as the separator engine's `'auto'` rule reads them. A
+ * sample with no number gives `{ prefix: '', suffix: '', fractionDigits: 2, '.', ',' }`.
+ */
+export declare function moneyTemplateOf(sample: string): MoneyTemplate;
+/**
+ * Money printed with a captured template: the exact major amount (stored / storageScale)
+ * rounded half-up to the template's digits, grouped, the sign after the prefix
+ * (`moneyTemplateOf('Rp 199.000')` prints IDR 2500050 as `'Rp 25.001'`).
+ */
+export declare function formatWithTemplate(m: Money, template: MoneyTemplate): string;
+//#endregion
+export type { DecimalInputOptions, ImportAmountOptions, MoneyTemplate, ParseAmountInputOptions, ParseAmountResult, ParseFailureReason, PercentInputOptions };

package/dist/input.d.ts

@@ -0,0 +1,203 @@
+import { R as DecimalText, b as FractionDigits, i as Money } from "./money-B-3aFjNJ.js";
+import { r as Rate } from "./rate-DBPiYgT1.js";
+//#region src/input/amount.d.ts
+/** Why typed text is not an acceptable amount. */
+type ParseFailureReason = 'empty' | 'unparseable' | 'too_many_decimals' | 'negative' | 'zero' | 'below_min' | 'above_max';
+interface ParseAmountInputOptions {
+  /**
+   * Decides the decimal and group separators (unsupported tags fall back to `'en-US'`). Absent
+   * (default): the 'auto' rule of `parseImportAmount`, today's admin price-entry rule except the
+   * listed behaviour changes: the text and the currency decide (`'29,99'` EUR is 29.99,
+   * `'1.299,00'` is 1299, KWD `'1,5'` is 1.5), and a currency storing 0 digits rounds a
+   * fraction half-up to a whole unit (`'1200.5'` JPY is 1201).
+   */
+  locale?: string;
+  /**
+   * `'.'`: machine decimal text, the value of an `<input type="number">` (browsers always
+   * serialise it with a `.` decimal and no grouping). `.` is the decimal (`'.5'` is 0.5), `,`
+   * and any grouping are `'unparseable'`, and a currency storing 0 digits rounds a fraction
+   * half-up to a whole unit, as admin `numericEntryToMinorUnits` does (`'1200.5'` JPY is
+   * 1201, `'1.500'` JPY is 2). TND and IQD `'1.500'` are 1.5. Extra fraction digits in a
+   * currency with decimals are `'too_many_decimals'`, never rounded. Every number input must
+   * use it; not with `locale`.
+   */
+  decimalSeparator?: '.';
+  /** Default false: a leading `-` gives `'negative'`. */
+  allowNegative?: boolean;
+  /** Default true; false gives `'zero'` for a zero amount. */
+  allowZero?: boolean;
+  /** Inclusive lower bound, in the same currency. */
+  min?: Money;
+  /** Inclusive upper bound, in the same currency. */
+  max?: Money;
+  /**
+   * The stored amount the field was prefilled with (`formatAmountInput(original)`). Text whose
+   * value equals it returns `original` unchanged, even when it has more fraction digits than
+   * the currency stores (JPY 120050 shows `'1200.50'`), so saving an untouched field never
+   * rewrites the amount. Any other text is held to the normal rule. Must be in `currency`.
+   */
+  original?: Money;
+}
+/**
+ * `text` is the canonical machine text on success (`'1250.00'`, `'1200'`, `'1.500'`: the major
+ * amount at the currency's storage digits) and the trimmed input on failure.
+ */
+type ParseAmountResult = {
+  readonly ok: true;
+  readonly money: Money;
+  readonly text: string;
+} | {
+  readonly ok: false;
+  readonly reason: ParseFailureReason;
+  readonly text: string;
+};
+/**
+ * Typed text to Money, one rule for every money field: the currency's symbols and code and all
+ * whitespace are stripped; a leading `-` or U+2212 is the sign.
+ * - Without `locale` (the chat wizard, any field with no locale): the 'auto' rule decides `.`
+ *   against `,` (see `parseImportAmount`): `'29,99'` EUR is 29.99, `'1.299,00'` and `'1,299'`
+ *   are 1299, KWD `'1,5'` is 1.5; a currency storing 0 digits rounds a fraction half-up to a
+ *   whole unit (`'1200.5'` JPY is 1201).
+ * - With `locale`: its decimal separator is the decimal and its group separator is valid only in
+ *   3-digit (or Indian lakh) groups; in a currency that stores no fraction (JPY, VND) a separator
+ *   before exactly three digits in grouping position is grouping (`'1.500'` JPY is 1500).
+ *   en-US `'29,99'` USD is `'unparseable'`; de-DE `'29,99'` EUR is 29.99; en-US `'1200.5'` JPY
+ *   is `'too_many_decimals'`.
+ * - With `decimalSeparator: '.'` (every `<input type="number">`): `.` is the decimal, nothing
+ *   groups (`'1,299'` is `'unparseable'`), TND and IQD `'1.500'` are 1.5, and a currency storing
+ *   0 digits rounds a fraction half-up to a whole unit (`'1.5'` JPY is 2).
+ * Otherwise more fraction digits than the currency stores is `'too_many_decimals'`, never rounded
+ * (`'1,2345'` USD). Text equal to `original` returns it unchanged (JPY 120050 shown as
+ * `'1200.50'`). An unknown currency, or an `original` in another currency, throws.
+ */
+export declare function parseAmountInput(text: string, currency: string, options?: ParseAmountInputOptions): ParseAmountResult;
+/**
+ * The text a money field shows for a stored amount, no symbol, exact: a stored amount finer than
+ * the storage digits keeps its digits (JPY 120050 is never rounded on display).
+ * - Without `locale`: the spelling `parseAmountInput` reads back without a locale. Trailing
+ *   fraction zeros are dropped (`'12.5'`, `'1200'`, KWD 1500 is `'1.5'`, JPY 120050 is
+ *   `'1200.5'`), a currency written with a decimal comma (TND, `commaDecimal`) uses `,` and
+ *   groups with `.` (`'1,125'`, `'1.234,5'`), every other currency `.` and `,`. Two amounts have no
+ *   such spelling: IQD with a three-digit fraction (`'1.125'` reads as 1125, IQD displays no
+ *   decimals) and a sub-unit amount of a currency storing 0 digits (`'1200.5'` JPY reads as a
+ *   whole 1201); pass `{ original: m }` so the untouched text returns `m` itself.
+ * - With `locale`: its decimal and group separators and the storage digits (`'12,50'` de-DE).
+ * - With `decimalSeparator: '.'` (the value of an `<input type="number">`): `.` decimal, never
+ *   grouped, trailing zeros dropped (TND 1500 is `'1.5'`, JPY 120050 `'1200.5'`), read back
+ *   exactly by `parseAmountInput(text, currency, { decimalSeparator: '.' })` (JPY sub-unit
+ *   amounts through `original`).
+ * `grouped` adds group separators (not in `'.'` mode); `digits` overrides the zeros
+ * (`'storage'` keeps them, `'trim-zero'` drops them).
+ */
+export declare function formatAmountInput(m: Money, options?: {
+  locale?: string;
+  decimalSeparator?: '.';
+  grouped?: boolean;
+  digits?: 'storage' | 'trim-zero';
+}): string;
+/** The `step` of a money number input: `'1'` (JPY), `'0.01'` (USD), `'0.001'` (KWD), from the storage digits. */
+export declare function inputStep(currency: string): '1' | '0.01' | '0.001';
+/** The placeholder of a money input: `'0'`, `'0.00'` or `'0.000'`, from the storage digits. */
+export declare function inputPlaceholder(currency: string): '0' | '0.00' | '0.000';
+//#endregion
+//#region src/input/import.d.ts
+interface ImportAmountOptions {
+  /**
+   * `'auto'` (default): spaces, NBSP, thin spaces and apostrophes are grouping, and the
+   * separator engine's 'auto' rule decides `.` against `,` (`'1.299,00'`, `'1.299'` and
+   * `'1,299'` are 1299, `'29,99'` is 29.99, `'0,500'` is 0.5, KWD `'1.500'` is 1.5; a `currency`
+   * storing 0 digits rounds to a whole unit). An explicit separator validates 3-digit groups of the other.
+   */
+  decimalSeparator?: '.' | ',' | 'auto';
+  /** Strips this currency's symbols and code, and decides the 3-digit rule above. */
+  currency?: string;
+  /** Default false: a negative amount gives null. */
+  allowNegative?: boolean;
+  /** Read the first numeric run and ignore the rest (`'22.67 + KDV'`, `'$1,299.00 incl. VAT'`). Default false. */
+  allowTrailingText?: boolean;
+}
+/**
+ * Amount text from a file or a third party to canonical DecimalText (major units, exactly as
+ * written: `'1.299,00'` gives `'1299'`), or null when it is not an amount (empty, exponent,
+ * hex, garbage, negative without `allowNegative`). Never 0 for bad input.
+ */
+export declare function parseImportAmount(text: string, options?: ImportAmountOptions): DecimalText | null;
+interface DecimalInputOptions {
+  /** Most fraction digits allowed (trailing zeros do not count). */
+  maxDecimals: number;
+  /** Inclusive bounds, decimal text. */
+  min?: DecimalText | string;
+  max?: DecimalText | string;
+  /** Default false. */
+  allowNegative?: boolean;
+}
+/**
+ * Strict decimal entry: `.` decimal, no grouping, at most `maxDecimals` fraction digits (cost
+ * entry at 4, metafields). `'4.5'` gives `'4.5'`, `'.5'` gives `'0.5'`; `'1,000'` is `'unparseable'`.
+ */
+export declare function parseDecimalInput(text: string, options: DecimalInputOptions): {
+  ok: true;
+  value: DecimalText;
+} | {
+  ok: false;
+  reason: ParseFailureReason;
+};
+//#endregion
+//#region src/input/percent-rate.d.ts
+interface PercentInputOptions {
+  /** Inclusive, default 0. */
+  min?: number;
+  /** Inclusive, default 100. */
+  max?: number;
+  /** Default 2. */
+  maxDecimals?: number;
+  /** Decides the separators; default `'en-US'`. */
+  locale?: string;
+}
+/**
+ * A typed percent (`'20'`, `'12.5'`, `'12,5 %'` in de-DE) as DecimalText. A `%` before or after
+ * the number is allowed. Default range 0..100 with 2 decimals; below 0 (with a non-negative
+ * `min`) is `'negative'`.
+ */
+export declare function parsePercentInput(text: string, options?: PercentInputOptions): {
+  ok: true;
+  value: DecimalText;
+} | {
+  ok: false;
+  reason: ParseFailureReason;
+};
+/**
+ * A typed exchange rate ("1 store-currency unit equals this many units") as a precise Rate
+ * (`fx.rateFromDecimal(value, { encoding: 'precise' })`), or null when the text is not a
+ * positive number or the rate is outside `RATE_BOUNDS` (0.0000001 to 1000000000).
+ */
+export declare function parseRateInput(text: string, options?: {
+  locale?: string;
+}): Rate | null;
+//#endregion
+//#region src/input/template.d.ts
+interface MoneyTemplate {
+  /** Text before the number (`'Rp '`, `'€'`), the sign goes after it. */
+  readonly prefix: string;
+  /** Text after the number (`' CHF'`, `' ₫'`). */
+  readonly suffix: string;
+  readonly fractionDigits: FractionDigits;
+  readonly decimalSeparator: string;
+  readonly groupSeparator: string;
+}
+/**
+ * The print template of one captured literal (cloner `analyzeMoneyFormat`): prefix and suffix
+ * around the number, the decimal separator and digit count of its fraction (1 or 2 digits
+ * read as 2, 3 as 3, none as 0), the separator it groups thousands with (else the decimal's
+ * counterpart), all as the separator engine's `'auto'` rule reads them. A
+ * sample with no number gives `{ prefix: '', suffix: '', fractionDigits: 2, '.', ',' }`.
+ */
+export declare function moneyTemplateOf(sample: string): MoneyTemplate;
+/**
+ * Money printed with a captured template: the exact major amount (stored / storageScale)
+ * rounded half-up to the template's digits, grouped, the sign after the prefix
+ * (`moneyTemplateOf('Rp 199.000')` prints IDR 2500050 as `'Rp 25.001'`).
+ */
+export declare function formatWithTemplate(m: Money, template: MoneyTemplate): string;
+//#endregion
+export type { DecimalInputOptions, ImportAmountOptions, MoneyTemplate, ParseAmountInputOptions, ParseAmountResult, ParseFailureReason, PercentInputOptions };