@fiscozen/input 0.1.17 → 1.0.0-next.0

package/src/FzCurrencyInput.vue

@@ -1,156 +1,796 @@
-<template>
-  <FzInput
-    ref="fzInputRef"
-    v-bind="props"
-    :modelValue="fzInputModel"
-    type="text"
-    @paste="onPaste"
-  >
-    <template #right-icon v-if="step">
-      <div class="flex flex-col justify-between items-center">
-        <FzIcon
-          name="angle-up"
-          size="xs"
-          class="fz__currencyinput__arrowup cursor-pointer"
-          @click="stepUpDown(step)"
-        ></FzIcon>
-        <FzIcon
-          name="angle-down"
-          size="xs"
-          class="fz__currencyinput__arrowdown cursor-pointer"
-          @click="stepUpDown(-step)"
-        ></FzIcon>
-      </div>
-    </template>
-    <template #label>
-      <slot name="label"></slot>
-    </template>
-  </FzInput>
-</template>
-
 <script setup lang="ts">
+/**
+ * FzCurrencyInput Component
+ *
+ * Specialized currency input built on FzInput with number formatting, validation,
+ * and step controls. Formats values using Intl.NumberFormat with locale-aware separators.
+ * Supports min/max constraints and step quantization
+ * that detects decimal/thousand separators automatically.
+ *
+ * @component
+ * @example
+ * <FzCurrencyInput label="Amount" v-model="value" :min="0" :max="1000" />
+ */
 import { computed, nextTick, onMounted, ref, watch } from "vue";
 import FzInput from "./FzInput.vue";
 import { FzCurrencyInputProps } from "./types";
-import { roundTo, useCurrency } from "@fiscozen/composables";
+import {
+  clamp,
+  format as formatValue,
+  parse,
+  roundTo,
+  truncateDecimals,
+} from "@fiscozen/composables";
 import { FzIcon } from "@fiscozen/icons";
 
 const fzInputRef = ref<InstanceType<typeof FzInput>>();
-const fzInputModel = ref();
+
+const fzInputModel = ref<string | undefined>();
+
 const containerRef = computed(() => fzInputRef.value?.containerRef);
+
 const inputRef = computed(() => fzInputRef.value?.inputRef);
+
+const isFocused = ref(false);
+
 const props = withDefaults(defineProps<FzCurrencyInputProps>(), {
+  min: -Infinity,
   minimumFractionDigits: 2,
+  max: Infinity,
   maximumFractionDigits: 2,
+  step: 1,
 });
-const {
-  inputRef: currencyInputRef,
-  setValue,
-  emitAmount,
-  parse,
-  format,
-} = useCurrency({
-  minimumFractionDigits: props.minimumFractionDigits,
-  maximumFractionDigits: props.maximumFractionDigits,
-  min: props.min,
-  max: props.max,
-  step: props.step,
+
+const model = defineModel<FzCurrencyInputProps["modelValue"]>();
+
+let isInternalUpdate = false;
+
+/**
+ * Determines the value to emit when input is empty based on nullOnEmpty and zeroOnEmpty props
+ *
+ * Priority: nullOnEmpty > zeroOnEmpty > undefined
+ *
+ * @returns null if nullOnEmpty is true, 0 if zeroOnEmpty is true, undefined otherwise
+ */
+const getEmptyValue = (): number | null | undefined => {
+  if (props.nullOnEmpty) {
+    return null;
+  }
+  if (props.zeroOnEmpty) {
+    return 0;
+  }
+  return undefined;
+};
+
+/**
+ * Determines the display value when input is empty
+ *
+ * When zeroOnEmpty is true and the empty value is 0:
+ * - During typing (focused): returns empty string (formatting happens on blur)
+ * - On blur (not focused): returns formatted "0,00"
+ *
+ * Otherwise returns empty string.
+ *
+ * @param isEmptyValueZero - Whether the empty value is 0 (from getEmptyValue())
+ *   If true, implies props.zeroOnEmpty is also true
+ * @param isCurrentlyFocused - Whether the input is currently focused
+ * @returns Display string to show in the input field
+ */
+const getEmptyDisplayValue = (
+  isEmptyValueZero: boolean,
+  isCurrentlyFocused: boolean
+): string => {
+  if (isEmptyValueZero) {
+    // During typing, show empty string. Formatting happens on blur
+    if (isCurrentlyFocused) {
+      return "";
+    }
+    // On blur or when not focused, show formatted zero
+    return formatValue(0, {
+      minimumFractionDigits: props.minimumFractionDigits,
+      maximumFractionDigits: props.maximumFractionDigits,
+      roundDecimals: false,
+      useGrouping: true,
+    });
+  }
+  return "";
+};
+
+/**
+ * Computed aria-label for step up button
+ *
+ * Uses custom stepUpAriaLabel if provided, otherwise generates default label based on step value.
+ */
+const stepUpAriaLabel = computed(() => {
+  if (props.stepUpAriaLabel) {
+    return props.stepUpAriaLabel;
+  }
+  return `Incrementa di ${props.step}`;
+});
+
+/**
+ * Computed aria-label for step down button
+ *
+ * Uses custom stepDownAriaLabel if provided, otherwise generates default label based on step value.
+ */
+const stepDownAriaLabel = computed(() => {
+  if (props.stepDownAriaLabel) {
+    return props.stepDownAriaLabel;
+  }
+  return `Decrementa di ${props.step}`;
+});
+
+/**
+ * Computed disabled state for step controls
+ *
+ * Step controls are disabled when input is readonly or disabled.
+ */
+const isStepDisabled = computed(() => {
+  return props.readonly || props.disabled;
 });
 
-defineEmits(["update:amount"]);
+/**
+ * Validates and normalizes user input
+ *
+ * Allows only digits, "." and ",". Converts "." to ",".
+ * Allows minus sign only at the beginning for negative values.
+ * Handles double comma case: "123,45" -> "12,3,45" -> "12,34"
+ * (keeps only the first comma, everything after becomes decimal part)
+ *
+ * @param inputValue - Raw input value from user
+ * @returns Normalized value with only one comma and optional leading minus sign
+ */
+const normalizeInput = (inputValue: string): string => {
+  // Allow only digits, "." "," and "-"
+  let filtered = inputValue.replace(/[^0-9.,-]/g, "");
+
+  // Check if minus sign is at the beginning (after removing invalid chars)
+  const hasLeadingMinus = filtered.startsWith("-");
+
+  // Remove all minus signs (we'll reattach only one at the beginning if needed)
+  filtered = filtered.replace(/-/g, "");
+
+  // Convert "." to ","
+  filtered = filtered.replace(/\./g, ",");
+
+  // Handle multiple commas: keep only the first one
+  const firstCommaIndex = filtered.indexOf(",");
+  if (firstCommaIndex !== -1) {
+    // Keep everything before first comma + first comma + everything after first comma (remove other commas)
+    const beforeComma = filtered.substring(0, firstCommaIndex);
+    const afterComma = filtered
+      .substring(firstCommaIndex + 1)
+      .replace(/,/g, "");
+    filtered = beforeComma + "," + afterComma;
+  }
+
+  // Reattach minus sign at the beginning if it was present at the start
+  return hasLeadingMinus ? "-" + filtered : filtered;
+};
+
+/**
+ * Prevents invalid characters from being typed
+ *
+ * Allows only digits, "." and ",". Allows minus sign only at the beginning.
+ * Blocks all other characters.
+ * Also allows control keys (Backspace, Delete, Arrow keys, Tab, etc.)
+ * Multiple commas are handled by normalizeInput.
+ *
+ * @param e - Keyboard event
+ */
+const handleKeydown = (e: KeyboardEvent) => {
+  // Allow control keys (Backspace, Delete, Arrow keys, Tab, etc.)
+  if (
+    e.ctrlKey ||
+    e.metaKey ||
+    e.altKey ||
+    [
+      "Backspace",
+      "Delete",
+      "ArrowLeft",
+      "ArrowRight",
+      "ArrowUp",
+      "ArrowDown",
+      "Tab",
+      "Enter",
+      "Home",
+      "End",
+    ].includes(e.key)
+  ) {
+    return;
+  }
+
+  // Allow minus sign only at the beginning (position 0) or when entire value is selected
+  if (e.key === "-") {
+    const target = e.target as HTMLInputElement;
+    const cursorPosition = target.selectionStart ?? 0;
+    const selectionLength = (target.selectionEnd ?? 0) - cursorPosition;
+    const valueLength = target.value.length;
+
+    // Allow minus if:
+    // 1. Cursor is at position 0 (beginning)
+    // 2. Entire value is selected (user can replace with negative)
+    if (cursorPosition !== 0 && selectionLength !== valueLength) {
+      e.preventDefault();
+    }
+    return;
+  }
+
+  // Allow only digits, "." and ","
+  if (!/^[0-9.,]$/.test(e.key)) {
+    e.preventDefault();
+  }
+};
+
+/**
+ * Handles paste event to replace entire input value
+ *
+ * Prevents default paste behavior and replaces the entire input value with the pasted content.
+ * Uses parse() to handle Italian format (e.g., "1.234,56"). If the pasted text is not a valid number,
+ * the paste is ignored.
+ */
+const handlePaste = (e: ClipboardEvent) => {
+  if (props.readonly || props.disabled) {
+    return;
+  }
 
-const onPaste = (e: ClipboardEvent) => {
   e.preventDefault();
 
-  if (props.readonly) {
+  const pastedText = e.clipboardData?.getData("text") || "";
+  if (!pastedText) {
     return;
   }
 
-  let rawPastedText;
-  if (e.clipboardData && e.clipboardData.getData) {
-    rawPastedText = e.clipboardData.getData("text/plain");
-  } else {
-    throw "invalid paste value";
+  // Use parse() to convert Italian format to number
+  const parsed = parse(pastedText);
+
+  if (!isNaN(parsed) && isFinite(parsed)) {
+    // Truncate decimals to maximumFractionDigits
+    const processed = truncateDecimals(parsed, props.maximumFractionDigits);
+
+    // Update v-model
+    isInternalUpdate = true;
+    model.value = processed;
+    isInternalUpdate = false;
+
+    // Convert number to normalized string format for display (e.g., 1234.56 -> "1234,56")
+    const numberString = String(processed);
+    const normalized = normalizeInput(numberString);
+    fzInputModel.value = normalized;
   }
+  // If invalid, ignore paste (do nothing)
+};
 
-  // Fix for firefox paste handling on `contenteditable` elements where `e.target` is the text node, not the element
-  let eventTarget;
-  if ((!e.target as any)?.tagName) {
-    eventTarget = (e as any).explicitOriginalTarget;
-  } else {
-    eventTarget = e.target;
+/**
+ * Handles input updates from FzInput
+ *
+ * Validates and normalizes input, updates v-model with parsed number.
+ * Does NOT format the display value - shows raw input (e.g., "123" stays "123", not "123,00").
+ * Does NOT apply step quantization - quantization happens only on blur.
+ * Formatting and quantization happen only on blur.
+ */
+const handleInputUpdate = (newValue: string | undefined) => {
+  if (!newValue) {
+    const emptyValue = getEmptyValue();
+    isInternalUpdate = true;
+    model.value = emptyValue;
+    isInternalUpdate = false;
+
+    // During typing, always show empty string. Formatting to "0,00" happens only on blur
+    fzInputModel.value = "";
+    return;
   }
 
-  let isNegative = rawPastedText.slice(0, 1) === "-";
-  const separatorRegex = /[,.]/g;
-  const separators: string[] = [...rawPastedText.matchAll(separatorRegex)].map(
-    (regexRes) => regexRes[0],
-  );
+  const normalized = normalizeInput(newValue);
+  fzInputModel.value = normalized;
 
-  const uniqueSeparators = new Set(separators);
-  let decimalSeparator = ".";
-  let thousandSeparator = "";
-  let unknownSeparator;
+  // Parse to number and update v-model (but don't format display - keep raw)
+  const parsed = parse(normalized);
+  if (!isNaN(parsed) && isFinite(parsed)) {
+    // Truncate decimals to maximumFractionDigits before updating v-model
+    const processed = truncateDecimals(parsed, props.maximumFractionDigits);
 
-  // case 1: there are 2 different separators pasted, therefore we can assume the rightmost is the decimal separator
-  if (uniqueSeparators.size > 1) {
-    decimalSeparator = separators[separators.length - 1];
-    thousandSeparator = separators[0];
+    isInternalUpdate = true;
+    model.value = processed;
+    isInternalUpdate = false;
+  } else {
+    // If invalid, keep the normalized string but don't update v-model
+    isInternalUpdate = true;
+    model.value = getEmptyValue();
+    isInternalUpdate = false;
   }
+};
 
-  // case 2: there are multiple instances of the same separator, therefore it must be the thousand separator
-  if (uniqueSeparators.size === 1) {
-    if (separators.length > 1) {
-      thousandSeparator = separators[0];
-    }
+/**
+ * Handles blur event to format the value
+ *
+ * Formats the value to Italian format (e.g., "123" -> "123,00", "123,4" -> "123,40").
+ * Applies step quantization if forceStep is enabled (quantization happens only on blur, not during typing).
+ */
+const handleBlur = () => {
+  if (props.readonly || props.disabled) {
+    return;
+  }
 
-    // case 3: there is only one instance of a separator  with < 3 digits afterwards (must be decimal separator)
-    unknownSeparator = separators[0];
-    const splitted = rawPastedText.split(unknownSeparator);
+  isFocused.value = false;
 
-    if (splitted[1].length !== 3) {
-      decimalSeparator = unknownSeparator;
+  const currentValue = normalizeModelValue(model.value);
+  if (currentValue === undefined || currentValue === null) {
+    // Ensure v-model matches the expected empty value based on nullOnEmpty/zeroOnEmpty
+    const expectedEmptyValue = getEmptyValue();
+    if (model.value !== expectedEmptyValue) {
+      isInternalUpdate = true;
+      model.value = expectedEmptyValue;
+      isInternalUpdate = false;
     }
+
+    // Display empty value (formatted zero if zeroOnEmpty is true, empty string otherwise)
+    fzInputModel.value = getEmptyDisplayValue(
+      expectedEmptyValue === 0,
+      false // Not focused during blur
+    );
+    return;
+  }
+
+  // Apply step quantization if forceStep is enabled
+  let processed = currentValue;
+  if (props.forceStep) {
+    processed = roundTo(props.step, processed);
   }
 
-  // case 3: there is only one instance of a separator with 3 digits afterwards. Here we cannot make assumptions
-  //         we will format based on settings
-  //@ts-ignore
-  let safeText = rawPastedText.replaceAll(thousandSeparator, "").trim();
-  safeText = safeText.replaceAll(decimalSeparator, ".").trim();
+  // Apply min/max constraints
+  processed = clamp(props.min, processed, props.max);
+
+  // Update v-model if processed value differs
+  if (processed !== currentValue) {
+    isInternalUpdate = true;
+    model.value = processed;
+    isInternalUpdate = false;
+  }
 
-  const safeNum = parse(safeText);
-  safeText = format(safeNum);
-  setValue(safeText);
-  emitAmount(safeNum);
+  // Format the value for display
+  const formatted = formatValue(processed, {
+    minimumFractionDigits: props.minimumFractionDigits,
+    maximumFractionDigits: props.maximumFractionDigits,
+    roundDecimals: false,
+    useGrouping: true,
+  });
+  fzInputModel.value = formatted;
 };
 
-onMounted(() => {
-  currencyInputRef.value = inputRef.value;
-  nextTick(() => {
-    fzInputModel.value = inputRef.value?.value;
+/**
+ * Handles focus event
+ *
+ * When input gains focus, shows raw value (without formatting)
+ */
+const handleFocus = () => {
+  if (props.readonly || props.disabled) {
+    return;
+  }
+
+  isFocused.value = true;
+
+  // Convert formatted value back to raw for editing
+  const currentValue = normalizeModelValue(model.value);
+  if (currentValue !== undefined) {
+    // Get raw value from formatted: remove thousand separators, keep decimal separator
+    const formatted = formatValue(currentValue, {
+      minimumFractionDigits: props.minimumFractionDigits,
+      maximumFractionDigits: props.maximumFractionDigits,
+      roundDecimals: false,
+      useGrouping: true,
+    });
+    const rawValue = formatted.replace(/\./g, ""); // Remove thousand separators
+    fzInputModel.value = rawValue;
+  }
+};
+
+/**
+ * Normalizes model value to number | undefined | null
+ *
+ * Converts string values to numbers (with deprecation warning) and handles
+ * null/undefined/empty string cases.
+ *
+ * @param value - Input value (number, string, undefined, or null)
+ * @returns Normalized number value, undefined, or null
+ */
+const normalizeModelValue = (
+  value: number | string | undefined | null
+): number | undefined | null => {
+  if (value === undefined || value === null || value === "") {
+    return value === null ? null : undefined;
+  }
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    console.warn(
+      "[FzCurrencyInput] String values in v-model are deprecated. Please use number instead. " +
+        `Received: "${value}". This will be parsed to a number for retrocompatibility, but string support may be removed in a future version.`
+    );
+    const parsed = parse(value);
+    return isNaN(parsed) ? undefined : parsed;
+  }
+  return undefined;
+};
+
+/**
+ * Handles step up button click
+ *
+ * Increments the current value by step amount, applying truncation and clamping.
+ */
+const handleStepUp = () => {
+  if (props.readonly || props.disabled) {
+    return;
+  }
+
+  const currentValue = normalizeModelValue(model.value);
+  // If value is undefined/null, start from 0 or empty value based on props
+  const baseValue =
+    currentValue === undefined || currentValue === null ? 0 : currentValue;
+
+  // Add step
+  const newValue = baseValue + props.step;
+
+  // Truncate decimals
+  const truncated = truncateDecimals(newValue, props.maximumFractionDigits);
+
+  // Apply min/max constraints
+  const clamped = clamp(props.min, truncated, props.max);
+
+  // Update v-model
+  isInternalUpdate = true;
+  model.value = clamped;
+  isInternalUpdate = false;
+
+  // Format and update display
+  const formatted = formatValue(clamped, {
+    minimumFractionDigits: props.minimumFractionDigits,
+    maximumFractionDigits: props.maximumFractionDigits,
+    roundDecimals: false,
+    useGrouping: true,
   });
-});
-const model = defineModel<number>("amount");
+  fzInputModel.value = formatted;
+};
 
-const stepUpDown = (amount: number) => {
-  if (!props.step) {
+/**
+ * Handles step down button click
+ *
+ * Decrements the current value by step amount, applying truncation and clamping.
+ */
+const handleStepDown = () => {
+  if (props.readonly || props.disabled) {
     return;
   }
-  const value = model.value || 0;
-  let stepVal = props.forceStep ? roundTo(props.step, value) : value;
-  stepVal += amount;
-  const safeText = format(stepVal);
-  setValue(safeText);
-  emitAmount(stepVal);
+
+  const currentValue = normalizeModelValue(model.value);
+  // If value is undefined/null, start from 0 or empty value based on props
+  const baseValue =
+    currentValue === undefined || currentValue === null ? 0 : currentValue;
+
+  // Subtract step
+  const newValue = baseValue - props.step;
+
+  // Truncate decimals
+  const truncated = truncateDecimals(newValue, props.maximumFractionDigits);
+
+  // Apply min/max constraints
+  const clamped = clamp(props.min, truncated, props.max);
+
+  // Update v-model
+  isInternalUpdate = true;
+  model.value = clamped;
+  isInternalUpdate = false;
+
+  // Format and update display
+  const formatted = formatValue(clamped, {
+    minimumFractionDigits: props.minimumFractionDigits,
+    maximumFractionDigits: props.maximumFractionDigits,
+    roundDecimals: false,
+    useGrouping: true,
+  });
+  fzInputModel.value = formatted;
 };
 
-watch(model, (newVal) => {
-  fzInputModel.value = newVal;
+/**
+ * Initializes fzInputModel with the value from v-model on mount
+ *
+ * Formats the value only if not focused (formatted display).
+ */
+onMounted(() => {
+  const initialValue = model.value;
+
+  if (initialValue === undefined || initialValue === null) {
+    // Ensure v-model matches the expected empty value based on nullOnEmpty/zeroOnEmpty
+    const expectedEmptyValue = getEmptyValue();
+    if (initialValue !== expectedEmptyValue) {
+      isInternalUpdate = true;
+      model.value = expectedEmptyValue;
+      isInternalUpdate = false;
+    }
+
+    // Display empty value (formatted zero if zeroOnEmpty is true, empty string otherwise)
+    fzInputModel.value = getEmptyDisplayValue(
+      expectedEmptyValue === 0,
+      false // Not focused during mount
+    );
+    return;
+  }
+
+  if (typeof initialValue === "number") {
+    // Truncate decimals to maximumFractionDigits before updating v-model
+    let processed = truncateDecimals(initialValue, props.maximumFractionDigits);
+
+    // Apply step quantization if forceStep is enabled
+    if (props.forceStep) {
+      processed = roundTo(props.step, processed);
+    }
+
+    // Apply min/max constraints
+    processed = clamp(props.min, processed, props.max);
+
+    // Update v-model if processed value differs (to ensure v-model always respects max decimals and step quantization)
+    if (processed !== initialValue) {
+      isInternalUpdate = true;
+      model.value = processed;
+      isInternalUpdate = false;
+    }
+
+    // Format number to Italian format (comma as decimal separator)
+    const formatted = formatValue(processed, {
+      minimumFractionDigits: props.minimumFractionDigits,
+      maximumFractionDigits: props.maximumFractionDigits,
+      roundDecimals: false,
+      useGrouping: true,
+    });
+    fzInputModel.value = formatted;
+    return;
+  }
+
+  if (typeof initialValue === "string") {
+    // Normalize string value (handles Italian format: "1.234,56" and shows deprecation warning)
+    const normalized = normalizeModelValue(initialValue);
+    if (normalized !== undefined && normalized !== null) {
+      const parsed = normalized;
+      // Truncate decimals to maximumFractionDigits before updating v-model
+      let processed = truncateDecimals(parsed, props.maximumFractionDigits);
+
+      // Apply step quantization if forceStep is enabled
+      if (props.forceStep) {
+        processed = roundTo(props.step, processed);
+      }
+
+      // Apply min/max constraints
+      processed = clamp(props.min, processed, props.max);
+
+      // Update v-model to number (this will trigger watch, but will be handled as number)
+      isInternalUpdate = true;
+      model.value = processed;
+      isInternalUpdate = false;
+      // Format and display
+      const formatted = formatValue(processed, {
+        minimumFractionDigits: props.minimumFractionDigits,
+        maximumFractionDigits: props.maximumFractionDigits,
+        roundDecimals: false,
+        useGrouping: true,
+      });
+      fzInputModel.value = formatted;
+    } else {
+      // Invalid string, clear input
+      const emptyValue = getEmptyValue();
+      isInternalUpdate = true;
+      model.value = emptyValue;
+      isInternalUpdate = false;
+
+      // Display empty value (formatted zero if zeroOnEmpty is true, empty string otherwise)
+      fzInputModel.value = getEmptyDisplayValue(
+        emptyValue === 0,
+        false // Not focused during mount
+      );
+    }
+    return;
+  }
 });
 
+/**
+ * Syncs external v-model changes to fzInputModel
+ *
+ * Point 1: v-model undefined -> fzInputModel = "" (empty string), v-model stays undefined
+ * Point 2: v-model number 1234.56 -> fzInputModel = "1234,56" (formatted), v-model stays 1234.56
+ * Point 3: v-model string "1.234,56" -> fzInputModel = "1234,56" (formatted), v-model will be 1234.56
+ *
+ * Formats only when not focused (when focused, shows raw value for editing).
+ */
+watch(
+  () => model.value,
+  (newVal) => {
+    // Skip if this is an internal update (from handleInputUpdate)
+    if (isInternalUpdate) {
+      return;
+    }
+
+    if (newVal === undefined || newVal === null) {
+      // Ensure v-model matches the expected empty value based on nullOnEmpty/zeroOnEmpty
+      const expectedEmptyValue = getEmptyValue();
+      if (newVal !== expectedEmptyValue) {
+        isInternalUpdate = true;
+        model.value = expectedEmptyValue;
+        isInternalUpdate = false;
+      }
+
+      // Display empty value (formatted zero if zeroOnEmpty is true, empty string otherwise)
+      fzInputModel.value = getEmptyDisplayValue(
+        expectedEmptyValue === 0,
+        isFocused.value
+      );
+      return;
+    }
+
+    if (typeof newVal === "number") {
+      // Truncate decimals to maximumFractionDigits before updating v-model
+      let processed = truncateDecimals(newVal, props.maximumFractionDigits);
+
+      // Apply step quantization if forceStep is enabled
+      if (props.forceStep) {
+        processed = roundTo(props.step, processed);
+      }
+
+      // Apply min/max constraints only when input is not focused
+      // When focused, allow values outside range temporarily (clamping happens on blur)
+      if (!isFocused.value) {
+        processed = clamp(props.min, processed, props.max);
+      }
+
+      // Update v-model if processed value differs (to ensure v-model always respects max decimals and step quantization)
+      if (processed !== newVal) {
+        isInternalUpdate = true;
+        model.value = processed;
+        isInternalUpdate = false;
+      }
+
+      // Format number to Italian format (comma as decimal separator)
+      // But only if not focused (when focused, show raw value)
+      if (!isFocused.value) {
+        const formatted = formatValue(processed, {
+          minimumFractionDigits: props.minimumFractionDigits,
+          maximumFractionDigits: props.maximumFractionDigits,
+          roundDecimals: false,
+          useGrouping: true,
+        });
+        fzInputModel.value = formatted;
+      }
+      return;
+    }
+
+    if (typeof newVal === "string") {
+      // Normalize string value (handles Italian format: "1.234,56" and shows deprecation warning)
+      const normalized = normalizeModelValue(newVal);
+      if (normalized !== undefined && normalized !== null) {
+        const parsed = normalized;
+        // Truncate decimals to maximumFractionDigits before updating v-model
+        let processed = truncateDecimals(parsed, props.maximumFractionDigits);
+
+        // Apply step quantization if forceStep is enabled
+        if (props.forceStep) {
+          processed = roundTo(props.step, processed);
+        }
+
+        // Apply min/max constraints only when input is not focused
+        // When focused, allow values outside range temporarily (clamping happens on blur)
+        if (!isFocused.value) {
+          processed = clamp(props.min, processed, props.max);
+        }
+
+        // Update v-model to number (this will trigger watch again, but will be handled as number)
+        isInternalUpdate = true;
+        model.value = processed;
+        isInternalUpdate = false;
+        // Format and display (only if not focused)
+        if (!isFocused.value) {
+          const formatted = formatValue(processed, {
+            minimumFractionDigits: props.minimumFractionDigits,
+            maximumFractionDigits: props.maximumFractionDigits,
+            roundDecimals: false,
+            useGrouping: true,
+          });
+          fzInputModel.value = formatted;
+        }
+      } else {
+        // Invalid string, clear input
+        const emptyValue = getEmptyValue();
+        isInternalUpdate = true;
+        model.value = emptyValue;
+        isInternalUpdate = false;
+
+        // Display empty value (formatted zero if zeroOnEmpty is true, empty string otherwise)
+        fzInputModel.value = getEmptyDisplayValue(
+          emptyValue === 0,
+          isFocused.value
+        );
+      }
+      return;
+    }
+  }
+);
+
 defineExpose({
   inputRef,
   containerRef,
 });
 </script>
+
+<template>
+  <FzInput
+    ref="fzInputRef"
+    v-bind="props"
+    :modelValue="fzInputModel"
+    type="text"
+    @update:modelValue="handleInputUpdate"
+    @keydown="handleKeydown"
+    @focus="handleFocus"
+    @blur="handleBlur"
+    @paste="handlePaste"
+  >
+    <template #label>
+      <slot name="label"></slot>
+    </template>
+    <template #left-icon>
+      <slot name="left-icon"></slot>
+    </template>
+    <template #right-icon>
+      <div class="flex items-center gap-4">
+        <FzIcon
+          v-if="props.valid"
+          name="check"
+          size="md"
+          class="text-semantic-success"
+          aria-hidden="true"
+        />
+        <div class="flex flex-col justify-between items-center">
+          <FzIcon
+            name="angle-up"
+            size="xs"
+            role="button"
+            :aria-label="stepUpAriaLabel"
+            :aria-disabled="isStepDisabled ? 'true' : undefined"
+            :tabindex="isStepDisabled ? undefined : '0'"
+            class="fz__currencyinput__arrowup cursor-pointer"
+            @click="handleStepUp"
+            @keydown="
+              (e: KeyboardEvent) => {
+                if ((e.key === 'Enter' || e.key === ' ') && !isStepDisabled) {
+                  e.preventDefault();
+                  handleStepUp();
+                }
+              }
+            "
+          ></FzIcon>
+          <FzIcon
+            name="angle-down"
+            size="xs"
+            role="button"
+            :aria-label="stepDownAriaLabel"
+            :aria-disabled="isStepDisabled ? 'true' : undefined"
+            :tabindex="isStepDisabled ? undefined : '0'"
+            class="fz__currencyinput__arrowdown cursor-pointer"
+            @click="handleStepDown"
+            @keydown="
+              (e: KeyboardEvent) => {
+                if ((e.key === 'Enter' || e.key === ' ') && !isStepDisabled) {
+                  e.preventDefault();
+                  handleStepDown();
+                }
+              }
+            "
+          ></FzIcon>
+        </div>
+      </div>
+    </template>
+    <template #helpText>
+      <slot name="helpText"></slot>
+    </template>
+    <template #errorMessage>
+      <slot name="errorMessage"></slot>
+    </template>
+  </FzInput>
+</template>