@marianmeres/stuic 3.121.0 → 3.123.0

package/API.md

@@ -308,6 +308,26 @@ Text input field with label, error, and hint support.
 <FieldInput bind:value={name} label="Name" required />
 ```
 
+#### `FieldMoney`
+
+Money input whose canonical bindable `value` is an **integer in minor units** (e.g. cents); the visible input shows/accepts a major-unit decimal (e.g. `"19.99"`). Wraps `FieldInput`. The `name` is applied to a hidden input carrying the integer minor units (the visible input stays name-less so a form never serializes the display string). A built-in numeric guard rejects non-numeric input and enforces the optional major-unit `min` / `max`.
+
+| Prop       | Type                         | Default | Description                                           |
+| ---------- | ---------------------------- | ------- | ----------------------------------------------------- |
+| `value`    | `number \| string \| null`   | —       | Bindable amount in integer minor units (e.g. `1999`)  |
+| `scale`    | `number`                     | `100`   | Minor units per major unit (cents per dollar/euro)    |
+| `decimals` | `number`                     | `2`     | Fraction digits shown in the visible input            |
+| `name`     | `string`                     | —       | Hidden input name for form submission (integer minor) |
+| `min`      | `number`                     | —       | Optional minimum, in major units                      |
+| `max`      | `number`                     | —       | Optional maximum, in major units                      |
+| `validate` | `boolean \| ValidateOptions` | —       | `false` disables the built-in guard; object merges it |
+
+```svelte
+<FieldMoney bind:value={priceCents} label="Price" name="price" min={0} />
+```
+
+The `formatMinorUnits`, `parseToMinorUnits`, and `money` helpers are exported for display elsewhere.
+
 #### `FieldTextarea`
 
 Multi-line text input.

package/README.md

@@ -148,7 +148,7 @@ AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, Header,
 
 ### Forms & Inputs
 
-FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, FieldCountry, CronInput, Fieldset, LoginForm, LoginFormModal, RegisterForm, RegisterFormModal, LoginOrRegisterForm, LoginOrRegisterFormModal, EmailVerifyForm, OtpInput
+FieldInput, FieldMoney, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, FieldCountry, CronInput, Fieldset, LoginForm, LoginFormModal, RegisterForm, RegisterFormModal, LoginOrRegisterForm, LoginOrRegisterFormModal, EmailVerifyForm, OtpInput
 
 ### Buttons & Controls
 

package/dist/components/ButtonGroupRadio/ButtonGroupRadio.svelte

@@ -95,7 +95,23 @@
 
 	let els = $state<Record<number, HTMLButtonElement>>({});
 
+	// An option is non-interactive if the whole group is disabled or the option
+	// itself is flagged `disabled`.
+	function is_disabled(index: number): boolean {
+		return !!disabled || !!coll.items[index]?.option.disabled;
+	}
+
+	// Find the next enabled index in `dir` (+1/-1), skipping disabled options.
+	// Does not wrap and clamps at the edges (returns `from` if none found).
+	function next_enabled_index(from: number, dir: 1 | -1): number {
+		for (let i = from + dir; i >= 0 && i < coll.size; i += dir) {
+			if (!is_disabled(i)) return i;
+		}
+		return from;
+	}
+
 	async function maybe_activate(index: number, coll: ItemColl) {
+		if (is_disabled(index)) return;
 		if ((await onButtonClick?.(index, coll)) !== false) {
 			coll.setActiveIndex(index);
 			els[index].focus();
@@ -121,7 +137,7 @@
 					classButton,
 					$coll.activeIndex === i && classButtonActive
 				)}
-				{disabled}
+				disabled={disabled || item.option.disabled}
 				type="button"
 				role="radio"
 				aria-checked={$coll.activeIndex === i}
@@ -131,10 +147,10 @@
 				bind:el={els[i]}
 				onkeydown={async (e) => {
 					if (["ArrowRight", "ArrowDown"].includes(e.key)) {
-						await maybe_activate(Math.min(i + 1, coll.size - 1), coll);
+						await maybe_activate(next_enabled_index(i, 1), coll);
 					}
 					if (["ArrowLeft", "ArrowUp"].includes(e.key)) {
-						await maybe_activate(Math.max(0, i - 1), coll);
+						await maybe_activate(next_enabled_index(i, -1), coll);
 					}
 				}}
 				id={item.id}

package/dist/components/ButtonGroupRadio/README.md

@@ -29,10 +29,28 @@ A radio button group styled as a segmented button toggle. Supports keyboard navi
 // Or object
 {
   label: 'Option A',
-  value: 'a'  // optional, defaults to label
+  value: 'a',       // optional, defaults to label
+  disabled: true    // optional, disables just this option
 }
 ```
 
+### Disabling individual options
+
+Set `disabled: true` on any option to make it non-interactive. Disabled options
+can't be clicked or activated and are skipped by keyboard arrow navigation. To
+disable the whole group instead, use the top-level `disabled` prop.
+
+```svelte
+<ButtonGroupRadio
+	options={[
+		{ label: "Free", value: "free" },
+		{ label: "Pro", value: "pro" },
+		{ label: "Enterprise", value: "enterprise", disabled: true },
+	]}
+	bind:value={plan}
+/>
+```
+
 ## Usage
 
 ### Basic

package/dist/components/Float/index.css

@@ -25,8 +25,10 @@
 		--stuic-color-surface-foreground,
 		var(--stuic-color-foreground)
 	);
-	--stuic-float-header-padding-x: 0.5rem;
-	--stuic-float-header-padding-y: 0.25rem;
+	--stuic-float-header-padding-t: 0.25rem;
+	--stuic-float-header-padding-r: 0.25rem;
+	--stuic-float-header-padding-b: 0.25rem;
+	--stuic-float-header-padding-l: 0.5rem;
 	--stuic-float-header-gap: 0.5rem;
 	--stuic-float-header-font-weight: var(--font-weight-medium);
 
@@ -75,7 +77,8 @@
 		display: flex;
 		align-items: center;
 		gap: var(--stuic-float-header-gap);
-		padding: var(--stuic-float-header-padding-y) var(--stuic-float-header-padding-x);
+		padding: var(--stuic-float-header-padding-t) var(--stuic-float-header-padding-r)
+			var(--stuic-float-header-padding-b) var(--stuic-float-header-padding-l);
 		background: var(--stuic-float-header-bg);
 		color: var(--stuic-float-header-text);
 		border-bottom: var(--stuic-float-border-width, var(--stuic-border-width)) solid

package/dist/components/Input/FieldMoney.svelte

@@ -0,0 +1,193 @@
+<!--
+	FieldMoney — edit a money amount stored as INTEGER minor units.
+
+	The bound `value` is the amount in minor units (e.g. cents); the visible input
+	shows/accepts a major-unit decimal (e.g. "1.00"). Conversion uses `scale` /
+	`decimals` (e.g. scale=100, decimals=2 for dollars/cents). Wraps FieldInput so
+	you get the full label / description / validation / layout system for free.
+
+	WHY a hidden input carries `name` (and the visible input stays name-less):
+	a <form> serializes the live DOM. If the *visible* input held `name`, the form
+	would submit the major-unit display string ("12.34") instead of the integer
+	minor units the server expects, and whole values like "20.00" would parse to 20
+	(minor units) — storing $0.20 for $20. So the visible input is kept name-less
+	and a hidden input carries `name` + the already-converted INTEGER minor units.
+	This mirrors FieldPhoneNumber, whose hidden input carries the composed E.164.
+-->
+<script lang="ts" module>
+	import type { ValidateOptions } from "../../actions/validate.svelte.js";
+	import type { Props as FieldInputProps } from "./FieldInput.svelte";
+
+	export interface Props extends Omit<
+		FieldInputProps,
+		"value" | "type" | "inputmode" | "min" | "max"
+	> {
+		/**
+		 * Bound value in INTEGER minor units (e.g. cents). `null` / `undefined` /
+		 * `""` mean empty. The visible input shows/accepts a major-unit decimal
+		 * string (e.g. "1.00"); conversion uses `scale` / `decimals`.
+		 */
+		value?: number | string | null;
+		/** Minor units per major unit. Default: 100 (cents per dollar/euro). */
+		scale?: number;
+		/** Fraction digits shown in the visible input. Default: 2. */
+		decimals?: number;
+		/**
+		 * Form field name — applied to the hidden submit input carrying the integer
+		 * minor units, NOT to the visible input. See the file header for why.
+		 */
+		name?: string;
+		/** Optional minimum, in MAJOR units (e.g. `0` to forbid negatives). */
+		min?: number;
+		/** Optional maximum, in MAJOR units. */
+		max?: number;
+		/**
+		 * Validation. `false` disables the built-in numeric guard; an options object
+		 * is merged with it (your `customValidator` runs after the numeric/min/max
+		 * checks pass). Defaults to the built-in guard.
+		 */
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+	}
+</script>
+
+<script lang="ts">
+	import { untrack } from "svelte";
+	import type { ValidationResult } from "../../actions/validate.svelte.js";
+	import { formatMinorUnits, parseToMinorUnits } from "../../utils/money-units.js";
+	import FieldInput from "./FieldInput.svelte";
+
+	let {
+		input = $bindable(),
+		value = $bindable(),
+		scale = 100,
+		decimals = 2,
+		name,
+		min,
+		max,
+		validate: validateProp,
+		...rest
+	}: Props = $props();
+
+	// Inner FieldInput instance — forwards the imperative ValidatableField API.
+	let field: ReturnType<typeof FieldInput> | undefined = $state();
+
+	const cfg = $derived({ scale, decimals });
+
+	// Single source of truth for "is this a valid amount, and what number is it?".
+	// A clean decimal is an optional leading "-", then digits with an optional
+	// single dot ("12", "12.34", "12.", ".5", "-3.2"). Everything else is rejected
+	// → null: hex ("0x10"), trailing garbage ("12.34abc"), thousands separators
+	// ("1,234.56"), scientific ("1e3"). Both the value-sync path (toMinor) and the
+	// validator below derive from THIS one helper, so what the validator accepts
+	// and what the hidden input submits can never disagree (parseFloat alone would:
+	// it reads "1,234.56" as 1 and "0x10" as 0, silently storing a wrong amount).
+	const DECIMAL_RE = /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
+	const parseDecimal = (s: string): number | null => {
+		const str = `${s}`.trim();
+		return DECIMAL_RE.test(str) ? parseFloat(str) : null;
+	};
+
+	// Major-unit display string → integer minor units. Empty or non-numeric → null
+	// (so a half-typed/garbage value is treated as "no amount", not silently 0).
+	const toMinor = (s: string): number | null => {
+		const n = parseDecimal(s);
+		return n === null ? null : parseToMinorUnits(n, cfg);
+	};
+
+	// Integer minor units → major-unit display string ("" when empty).
+	const fromValue = (v: number | string | null | undefined): string =>
+		v === null || v === undefined || v === "" ? "" : formatMinorUnits(v, cfg);
+
+	// Input-facing major-unit string (e.g. "1.00").
+	let display = $state(fromValue(value));
+
+	// Typing updates the bound minor-unit value.
+	$effect(() => {
+		const next = toMinor(display);
+		untrack(() => {
+			if (next !== (value ?? null)) value = next;
+		});
+	});
+
+	// External value changes (model load/switch) resync the display — but only
+	// when they don't already match what's typed, so we never clobber user input.
+	$effect(() => {
+		const incoming = value;
+		untrack(() => {
+			const incomingMinor =
+				incoming === null || incoming === undefined || incoming === ""
+					? null
+					: Math.round(Number(incoming));
+			if (toMinor(display) !== incomingMinor) display = fromValue(incoming);
+		});
+	});
+
+	// What the form submits: INTEGER minor units derived straight from the visible
+	// display string (empty/invalid → ""). Derived from `display` (not the bound
+	// `value`) so it's correct synchronously at submit time, without depending on
+	// the value-sync effect above having flushed first.
+	const submitValue = $derived(toMinor(display) ?? "");
+
+	// Built-in light numeric guard: reject a non-empty-but-non-numeric amount and
+	// enforce optional major-unit min/max. `required`-empty is handled natively by
+	// the visible input (FieldInput forwards `required`). Consumer opts are honored:
+	// `false` disables; an options object is merged (its customValidator runs after
+	// the numeric guard passes).
+	const validateOpts = $derived.by<
+		boolean | Omit<ValidateOptions, "setValidationResult">
+	>(() => {
+		if (validateProp === false) return false;
+		const custom = validateProp && typeof validateProp === "object" ? validateProp : {};
+		return {
+			...custom,
+			customValidator: (val, ctx, el) => {
+				const str = `${val ?? ""}`.trim();
+				if (str !== "") {
+					const n = parseDecimal(str);
+					if (n === null) return "Please enter a valid amount.";
+					if (min != null && n < min) return `Amount must be at least ${min}.`;
+					if (max != null && n > max) return `Amount must be at most ${max}.`;
+				}
+				return custom.customValidator?.(val, ctx, el) || "";
+			},
+		};
+	});
+
+	// ---- Imperative API (satisfies ValidatableField), forwarded to FieldInput ----
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		return field?.validate();
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		field?.clearValidation();
+	}
+
+	/** Current validation state, or undefined if the validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return field?.getValidation();
+	}
+
+	/** Focus the visible input. */
+	export function focus(): void {
+		field?.focus();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		field?.scrollIntoView(opts);
+	}
+</script>
+
+<FieldInput
+	bind:this={field}
+	bind:input
+	type="text"
+	inputmode="decimal"
+	bind:value={display}
+	validate={validateOpts}
+	{...rest}
+/>
+<input type="hidden" {name} value={submitValue} />

package/dist/components/Input/FieldMoney.svelte.d.ts

@@ -0,0 +1,39 @@
+import type { ValidateOptions } from "../../actions/validate.svelte.js";
+import type { Props as FieldInputProps } from "./FieldInput.svelte";
+export interface Props extends Omit<FieldInputProps, "value" | "type" | "inputmode" | "min" | "max"> {
+    /**
+     * Bound value in INTEGER minor units (e.g. cents). `null` / `undefined` /
+     * `""` mean empty. The visible input shows/accepts a major-unit decimal
+     * string (e.g. "1.00"); conversion uses `scale` / `decimals`.
+     */
+    value?: number | string | null;
+    /** Minor units per major unit. Default: 100 (cents per dollar/euro). */
+    scale?: number;
+    /** Fraction digits shown in the visible input. Default: 2. */
+    decimals?: number;
+    /**
+     * Form field name — applied to the hidden submit input carrying the integer
+     * minor units, NOT to the visible input. See the file header for why.
+     */
+    name?: string;
+    /** Optional minimum, in MAJOR units (e.g. `0` to forbid negatives). */
+    min?: number;
+    /** Optional maximum, in MAJOR units. */
+    max?: number;
+    /**
+     * Validation. `false` disables the built-in numeric guard; an options object
+     * is merged with it (your `customValidator` runs after the numeric/min/max
+     * checks pass). Defaults to the built-in guard.
+     */
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+}
+import type { ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldMoney: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "value" | "input">;
+type FieldMoney = ReturnType<typeof FieldMoney>;
+export default FieldMoney;

package/dist/components/Input/FieldRadios.svelte

@@ -115,7 +115,7 @@
 					value={o.value ?? o.label}
 					description={o.description}
 					{renderSize}
-					{disabled}
+					disabled={disabled || o.disabled}
 					{tabindex}
 					{required}
 					validate={validateProp}

package/dist/components/Input/README.md

@@ -7,6 +7,7 @@ A comprehensive form input system with multiple field components, validation sup
 | Component         | Description                                          |
 | ----------------- | ---------------------------------------------------- |
 | `FieldInput`      | Text, email, password, number, and other input types |
+| `FieldMoney`      | Money amount stored as integer minor units (cents)   |
 | `FieldTextarea`   | Multi-line text input with auto-grow                 |
 | `FieldSelect`     | Dropdown select with option groups                   |
 | `FieldCheckbox`   | Single checkbox with label                           |
@@ -158,6 +159,32 @@ Component-specific targets (e.g. `classInput` for the inner `<input>`/`<select>`
 </FieldInput>
 ```
 
+### Money Input
+
+`FieldMoney` edits a money amount whose canonical value is an **integer in minor
+units** (e.g. cents), while the user sees and types a major-unit decimal
+("12.34"). It wraps `FieldInput`, so all the common props (label, validation,
+sizing, class props, the imperative API) work as usual.
+
+```svelte
+<script lang="ts">
+	import { FieldMoney } from "stuic";
+
+	// bound value is the integer amount of minor units (e.g. 1999 = $19.99)
+	let priceCents = $state(1999);
+</script>
+
+<FieldMoney label="Price" name="price" bind:value={priceCents} min={0} />
+```
+
+The `name` is applied to a hidden input carrying the integer minor units — the
+visible input stays name-less so a `<form>` never serializes the display string.
+A built-in numeric guard rejects non-numeric input and enforces the optional
+major-unit `min` / `max`. Use `scale` / `decimals` for non-cents currencies
+(e.g. `scale={1000} decimals={3}`). The matching `formatMinorUnits`,
+`parseToMinorUnits`, and `money` helpers are exported from `@marianmeres/stuic`
+for display elsewhere.
+
 ### Left-aligned Label
 
 ```svelte

package/dist/components/Input/index.d.ts

@@ -3,6 +3,7 @@ export { default as FieldAssets, type Props as FieldAssetsProps, type FieldAsset
 export { default as FieldCheckbox, type Props as FieldCheckboxProps, } from "./FieldCheckbox.svelte";
 export { default as FieldFile, type Props as FieldFileProps } from "./FieldFile.svelte";
 export { default as FieldInput, type Props as FieldInputProps, } from "./FieldInput.svelte";
+export { default as FieldMoney, type Props as FieldMoneyProps, } from "./FieldMoney.svelte";
 export { default as FieldLikeButton, type Props as FieldLikeButtonProps, } from "./FieldLikeButton.svelte";
 export { default as FieldOptions, type Props as FieldOptionsProps, type Option as FieldOption, } from "./FieldOptions.svelte";
 export { default as FieldRadios, type Props as FieldRadiosProps, } from "./FieldRadios.svelte";

package/dist/components/Input/index.js

@@ -3,6 +3,7 @@ export { default as FieldAssets, } from "./FieldAssets.svelte";
 export { default as FieldCheckbox, } from "./FieldCheckbox.svelte";
 export { default as FieldFile } from "./FieldFile.svelte";
 export { default as FieldInput, } from "./FieldInput.svelte";
+export { default as FieldMoney, } from "./FieldMoney.svelte";
 export { default as FieldLikeButton, } from "./FieldLikeButton.svelte";
 export { default as FieldOptions, } from "./FieldOptions.svelte";
 export { default as FieldRadios, } from "./FieldRadios.svelte";

package/dist/components/Input/types.d.ts

@@ -8,6 +8,8 @@ export interface FieldRadiosOption {
     label: string;
     value?: string;
     description?: THC;
+    /** Disable this individual option (non-interactive, skipped by keyboard nav). */
+    disabled?: boolean;
 }
 /**
  * Class props forwarded to the shared `InputWrap` scaffolding used by every

package/dist/utils/index.d.ts

@@ -19,6 +19,7 @@ export * from "./is-mac.js";
 export * from "./is-nullish.js";
 export * from "./maybe-json-parse.js";
 export * from "./maybe-json-stringify.js";
+export * from "./money-units.js";
 export * from "./nl2br.js";
 export * from "./observe-exists.svelte.js";
 export * from "./omit-pick.js";
@@ -30,6 +31,7 @@ export * from "./preload-img.js";
 export * from "./qsa.js";
 export * from "./replace-map.js";
 export * from "./resolve-url.js";
+export * from "./round-to-decimals.js";
 export * from "./seconds.js";
 export * from "./sleep.js";
 export * from "./storage-abstraction.js";

package/dist/utils/index.js

@@ -19,6 +19,7 @@ export * from "./is-mac.js";
 export * from "./is-nullish.js";
 export * from "./maybe-json-parse.js";
 export * from "./maybe-json-stringify.js";
+export * from "./money-units.js";
 export * from "./nl2br.js";
 export * from "./observe-exists.svelte.js";
 export * from "./omit-pick.js";
@@ -30,6 +31,7 @@ export * from "./preload-img.js";
 export * from "./qsa.js";
 export * from "./replace-map.js";
 export * from "./resolve-url.js";
+export * from "./round-to-decimals.js";
 export * from "./seconds.js";
 export * from "./sleep.js";
 export * from "./storage-abstraction.js";

package/dist/utils/money-units.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Configuration for converting between an integer "minor units" amount (the
+ * smallest indivisible unit a currency is stored in, e.g. cents) and its
+ * human-facing "major units" decimal (e.g. dollars/euros).
+ *
+ * `scale` is how many minor units make one major unit (100 cents = 1 dollar);
+ * `decimals` is how many fraction digits the major-unit string shows.
+ */
+export interface MinorUnitsConfig {
+    /** Minor units per major unit. Default: 100. */
+    scale?: number;
+    /** Fraction digits in the major-unit string. Default: 2. */
+    decimals?: number;
+}
+/**
+ * Stored minor units (e.g. cents) → major-unit decimal string (e.g. `"1.00"`).
+ * No currency symbol or grouping separators — the result round-trips cleanly
+ * back through {@link parseToMinorUnits}, so it's safe for editable inputs.
+ *
+ * Non-numeric input is passed through stringified (so a half-typed value isn't
+ * silently zeroed); callers that need a guarantee should validate first.
+ *
+ * @example
+ * ```ts
+ * formatMinorUnits(100);                       // "1.00"
+ * formatMinorUnits(12345);                      // "123.45"
+ * formatMinorUnits(5, { scale: 1000, decimals: 3 }); // "0.005"
+ * ```
+ */
+export declare function formatMinorUnits(v: string | number | null | undefined, cfg?: MinorUnitsConfig): string;
+/**
+ * Major-unit decimal input (e.g. `"1.00"`) → integer minor units (e.g. `100`).
+ *
+ * NaN-safe: non-numeric input yields `0`. This is a low-level helper — UI that
+ * must distinguish "empty/invalid" from "zero" should guard for finiteness
+ * before calling (see how `FieldMoney` does it).
+ *
+ * @example
+ * ```ts
+ * parseToMinorUnits("1.00");                    // 100
+ * parseToMinorUnits("123.45");                   // 12345
+ * parseToMinorUnits("0.005", { scale: 1000, decimals: 3 }); // 5
+ * parseToMinorUnits("abc");                      // 0
+ * ```
+ */
+export declare function parseToMinorUnits(v: string | number | null | undefined, cfg?: MinorUnitsConfig): number;
+/**
+ * Format an integer amount of minor units (cents) as a localized currency
+ * string, e.g. `money(12345, "USD")` → `"$123.45"`.
+ *
+ * Uses `Intl.NumberFormat` with `currencyDisplay: "narrowSymbol"` so you get
+ * `"$"` / `"€"` rather than the locale-disambiguated `"US$"`. Falls back to a
+ * plain `"123.45 XXX"` for unknown/invalid currency codes.
+ *
+ * Unlike {@link formatMinorUnits} this is for DISPLAY only (it adds symbols and
+ * grouping) — do not feed its output back into an editable money input.
+ *
+ * @example
+ * ```ts
+ * money(12345, "USD"); // "$123.45"
+ * money(null, "EUR");  // "€0.00"
+ * ```
+ */
+export declare function money(cents: number | undefined | null, currency: string): string;

package/dist/utils/money-units.js

@@ -0,0 +1,75 @@
+import { roundToDecimals } from "./round-to-decimals.js";
+/**
+ * Stored minor units (e.g. cents) → major-unit decimal string (e.g. `"1.00"`).
+ * No currency symbol or grouping separators — the result round-trips cleanly
+ * back through {@link parseToMinorUnits}, so it's safe for editable inputs.
+ *
+ * Non-numeric input is passed through stringified (so a half-typed value isn't
+ * silently zeroed); callers that need a guarantee should validate first.
+ *
+ * @example
+ * ```ts
+ * formatMinorUnits(100);                       // "1.00"
+ * formatMinorUnits(12345);                      // "123.45"
+ * formatMinorUnits(5, { scale: 1000, decimals: 3 }); // "0.005"
+ * ```
+ */
+export function formatMinorUnits(v, cfg) {
+    const scale = cfg?.scale ?? 100;
+    const decimals = cfg?.decimals ?? 2;
+    const n = parseFloat(`${v}`);
+    if (!Number.isFinite(n))
+        return `${v ?? ""}`;
+    return roundToDecimals(n / scale, decimals).toFixed(decimals);
+}
+/**
+ * Major-unit decimal input (e.g. `"1.00"`) → integer minor units (e.g. `100`).
+ *
+ * NaN-safe: non-numeric input yields `0`. This is a low-level helper — UI that
+ * must distinguish "empty/invalid" from "zero" should guard for finiteness
+ * before calling (see how `FieldMoney` does it).
+ *
+ * @example
+ * ```ts
+ * parseToMinorUnits("1.00");                    // 100
+ * parseToMinorUnits("123.45");                   // 12345
+ * parseToMinorUnits("0.005", { scale: 1000, decimals: 3 }); // 5
+ * parseToMinorUnits("abc");                      // 0
+ * ```
+ */
+export function parseToMinorUnits(v, cfg) {
+    const scale = cfg?.scale ?? 100;
+    const n = parseFloat(`${v}`);
+    return Number.isFinite(n) ? Math.round(n * scale) : 0;
+}
+/**
+ * Format an integer amount of minor units (cents) as a localized currency
+ * string, e.g. `money(12345, "USD")` → `"$123.45"`.
+ *
+ * Uses `Intl.NumberFormat` with `currencyDisplay: "narrowSymbol"` so you get
+ * `"$"` / `"€"` rather than the locale-disambiguated `"US$"`. Falls back to a
+ * plain `"123.45 XXX"` for unknown/invalid currency codes.
+ *
+ * Unlike {@link formatMinorUnits} this is for DISPLAY only (it adds symbols and
+ * grouping) — do not feed its output back into an editable money input.
+ *
+ * @example
+ * ```ts
+ * money(12345, "USD"); // "$123.45"
+ * money(null, "EUR");  // "€0.00"
+ * ```
+ */
+export function money(cents, currency) {
+    const value = (cents ?? 0) / 100;
+    try {
+        return new Intl.NumberFormat(undefined, {
+            style: "currency",
+            currency,
+            currencyDisplay: "narrowSymbol",
+        }).format(value);
+    }
+    catch {
+        // Unknown/invalid currency code — degrade to a plain "12.00 XXX".
+        return `${value.toFixed(2)} ${currency}`;
+    }
+}

package/dist/utils/round-to-decimals.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Round a number to a fixed number of decimal places.
+ *
+ * Avoids the trailing float noise of naive `toFixed`-then-`parseFloat` by
+ * scaling to integers, rounding, then scaling back.
+ *
+ * @param value - The number to round
+ * @param decimals - Number of decimal places to keep (default: 5)
+ * @returns The rounded number
+ *
+ * @example
+ * ```ts
+ * roundToDecimals(1.005, 2);   // 1.01
+ * roundToDecimals(2.5 / 100, 2); // 0.03
+ * roundToDecimals(3.14159);    // 3.14159 (default 5 decimals)
+ * ```
+ */
+export declare function roundToDecimals(value: number, decimals?: number): number;

package/dist/utils/round-to-decimals.js

@@ -0,0 +1,21 @@
+/**
+ * Round a number to a fixed number of decimal places.
+ *
+ * Avoids the trailing float noise of naive `toFixed`-then-`parseFloat` by
+ * scaling to integers, rounding, then scaling back.
+ *
+ * @param value - The number to round
+ * @param decimals - Number of decimal places to keep (default: 5)
+ * @returns The rounded number
+ *
+ * @example
+ * ```ts
+ * roundToDecimals(1.005, 2);   // 1.01
+ * roundToDecimals(2.5 / 100, 2); // 0.03
+ * roundToDecimals(3.14159);    // 3.14159 (default 5 decimals)
+ * ```
+ */
+export function roundToDecimals(value, decimals = 5) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(value * factor) / factor;
+}

package/docs/domains/components.md

@@ -55,6 +55,7 @@
 | Component                                     | Purpose                                                                     |
 | --------------------------------------------- | --------------------------------------------------------------------------- |
 | Input (FieldInput, FieldSelect, etc.)         | Form fields                                                                 |
+| FieldMoney                                    | Money input storing integer minor units (e.g. cents)                        |
 | FieldPhoneNumber                              | International phone input with country picker                               |
 | FieldObject                                   | Dual-mode JSON object editor (pretty-print/raw)                             |
 | CronInput                                     | Cron expression editor with presets and validation                          |
@@ -146,8 +147,8 @@ Use `validate={false}` to bypass stuic's validation entirely.
 
 ### Per-field methods
 
-Available on `FieldInput`, `FieldTextarea`, `FieldCheckbox`, `FieldSelect`,
-`FieldFile`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
+Available on `FieldInput`, `FieldMoney`, `FieldTextarea`, `FieldCheckbox`,
+`FieldSelect`, `FieldFile`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
 `FieldKeyValues`, `FieldPhoneNumber`, `FieldCountry`, `FieldLikeButton`,
 `FieldRadios`, `FieldSwitch`, `FieldOptions`, and `Switch`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.121.0",
+	"version": "3.123.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -152,7 +152,7 @@
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
-		"playwright": "^1.60.0",
+		"playwright": "^1.61.0",
 		"prettier": "^3.8.4",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
@@ -161,7 +161,7 @@
 		"tailwindcss": "^4.3.1",
 		"tsx": "^4.22.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.61.0",
+		"typescript-eslint": "^8.61.1",
 		"vite": "^7.3.5",
 		"vitest": "^4.1.9",
 		"vitest-browser-svelte": "^2.1.1"