@spaethtech/svelte-ui 0.7.1-dev.38.b73de30 → 0.7.1-dev.40.3d22ac0

package/.claude/skills/svelte-ui/SKILL.md

@@ -154,7 +154,9 @@ examples):
 
 - **Form:** `Button` `ButtonDropdown` `Input` `Select` `List` `TextArea` `Checkbox` `Toggle` `Radio`
   `Rating` · **`FieldGroup`** (fieldset wrapper for radio/checkbox/toggle sets)
-- **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput`
+- **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput` (formatting +
+  `percent`/`stepper`/`clamp`/`liveFormat`) `PhoneInput` (stores E.164; dep-free, inject
+  `parse`/`format` for per-country)
 - **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`
 - **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
   (query-language parser/AST, `createGrid`, `DataGrid<T>`, `DataSet`).

package/dist/components/NumberInput.svelte

@@ -1,5 +1,10 @@
 <script lang="ts">
+  import { tick } from "svelte";
+  import type { Snippet } from "svelte";
   import Input from "./Input.svelte";
+  import Button from "./Button.svelte";
+  import Minus from "~icons/mdi/minus";
+  import Plus from "~icons/mdi/plus";
   import type { HTMLInputAttributes } from "svelte/elements";
   import type { Size } from "../types/sizes.js";
   import type { Responsive } from "../types/responsive.js";
@@ -25,11 +30,23 @@
     thousandsSeparator?: boolean;
     prefix?: string;
     suffix?: string;
-    currency?: string; // e.g., '$', '€', '£', '¥', etc.
-    decimalSeparator?: string; // Decimal separator (default: '.')
-    thousandsChar?: string; // Thousands separator character (default: ',')
-    roundingMode?: "round" | "floor" | "ceil" | "trunc"; // Rounding behavior for integers
-    negativeMode?: "minus" | "parentheses" | "both"; // How to display/accept negative numbers
+    currency?: string; // symbol, e.g. '$', '€' — a prefix (use `suffix` for trailing symbols)
+    decimalSeparator?: string;
+    thousandsChar?: string;
+    roundingMode?: "round" | "floor" | "ceil" | "trunc";
+    negativeMode?: "minus" | "parentheses" | "both";
+    /** Hard-block the minus key + strip negatives on parse. Default: derived from `min`
+     *  (`min >= 0` ⇒ `false`, otherwise `true`). */
+    allowNegative?: boolean;
+    /** On blur, coerce the value into `[min, max]` instead of only surfacing a validation error. */
+    clamp?: boolean;
+    /** Show ± stepper buttons. Arrow-Up/Down always step by `step` (this just adds the buttons). */
+    stepper?: boolean;
+    /** Percent mode: store the fraction, display ×100 with a `%` suffix (`0.5` ⇄ `50%`).
+     *  `value` / `min` / `max` / `step` are all in the fraction units. */
+    percent?: boolean;
+    /** Group digits AS YOU TYPE (caret preserved) rather than only reformatting on blur. */
+    liveFormat?: boolean;
   }
 
   let {
@@ -42,12 +59,6 @@
     max,
     step = 1,
     allowDecimals = true,
-    // Integer by default. Currency / accounting callers already
-    // pass `decimalPlaces={2}` explicitly (see the showcase), so
-    // this default only affects bare `<NumberInput bind:value=… />`
-    // which reads as an integer field 99% of the time (port numbers,
-    // intervals, counts). Prevents the `22 → 22.00` surprise where
-    // callers had to opt OUT of decimals to display a whole number.
     decimalPlaces = 0,
     thousandsSeparator: enableThousandsSeparator = false,
     prefix = "",
@@ -57,6 +68,11 @@
     thousandsChar = ",",
     roundingMode = "round",
     negativeMode = "minus",
+    allowNegative,
+    clamp = false,
+    stepper = false,
+    percent = false,
+    liveFormat = false,
     placeholder = "Enter a number...",
     ...restProps
   }: Props = $props();
@@ -64,204 +80,176 @@
   let displayValue = $state("");
   let focused = $state(false);
 
-  // Convert number to formatted display string
-  function formatNumber(num: number | null): string {
-    if (num === null || num === undefined || isNaN(num)) return "";
+  // Negatives default to disallowed when `min` fences them off (min >= 0). Percent uses "%" as the
+  // effective suffix and drops any prefix; otherwise currency/prefix + suffix apply as before.
+  const negativeAllowed = $derived(allowNegative ?? (min === undefined || min < 0));
+  const effPrefix = $derived(percent ? "" : currency || prefix);
+  const effSuffix = $derived(percent ? "%" : suffix);
+  const inputMode = $derived<"decimal" | "numeric">(allowDecimals || percent ? "decimal" : "numeric");
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+  function clampVal(n: number): number {
+    if (min !== undefined) n = Math.max(min, n);
+    if (max !== undefined) n = Math.min(max, n);
+    return n;
+  }
 
+  // number -> display string (full formatting: decimals/rounding, grouping, prefix/suffix, negatives)
+  function formatNumber(numRaw: number | null): string {
+    if (numRaw === null || numRaw === undefined || isNaN(numRaw)) return "";
+    const num = percent ? numRaw * 100 : numRaw;
     const isNegative = num < 0;
     const absoluteNum = Math.abs(num);
     let formatted = absoluteNum.toString();
 
-    // Handle decimal places and rounding
     if (allowDecimals && decimalPlaces > 0) {
       formatted = absoluteNum.toFixed(decimalPlaces);
     } else if (!allowDecimals) {
-      // Apply rounding mode for integers
       let rounded: number;
       switch (roundingMode) {
-        case "floor":
-          rounded = Math.floor(absoluteNum);
-          break;
-        case "ceil":
-          rounded = Math.ceil(absoluteNum);
-          break;
-        case "trunc":
-          rounded = Math.trunc(absoluteNum);
-          break;
-        default: // 'round'
-          rounded = Math.round(absoluteNum);
+        case "floor": rounded = Math.floor(absoluteNum); break;
+        case "ceil": rounded = Math.ceil(absoluteNum); break;
+        case "trunc": rounded = Math.trunc(absoluteNum); break;
+        default: rounded = Math.round(absoluteNum);
       }
       formatted = rounded.toString();
     }
 
-    // Add thousands separator and convert to custom format
     if (enableThousandsSeparator) {
       const parts = formatted.split(".");
       parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, thousandsChar);
       formatted = parts.join(decimalSeparator);
     } else if (decimalSeparator !== ".") {
-      // Even without thousands separator, we need to convert decimal separator
       formatted = formatted.replace(".", decimalSeparator);
     }
 
-    const finalPrefix = currency || prefix;
-
-    // Handle negative number display
     if (isNegative) {
-      if (negativeMode === "parentheses") {
-        // For parentheses, put everything (prefix, number, suffix) inside
-        return `(${finalPrefix}${formatted}${suffix})`;
-      } else {
-        // 'minus' or 'both' - put minus in front
-        return `-${finalPrefix}${formatted}${suffix}`;
-      }
+      if (negativeMode === "parentheses") return `(${effPrefix}${formatted}${effSuffix})`;
+      return `-${effPrefix}${formatted}${effSuffix}`;
     }
-
-    return `${finalPrefix}${formatted}${suffix}`;
+    return `${effPrefix}${formatted}${effSuffix}`;
   }
 
-  // Parse display string back to number
+  // display string -> number
   function parseNumber(str: string): number | null {
     if (!str || str.trim() === "") return null;
+    const isNegative =
+      negativeAllowed && ((str.includes("(") && str.includes(")")) || str.includes("-"));
 
-    // Check for negative indicators
-    const hasParentheses = str.includes("(") && str.includes(")");
-    const hasMinus = str.includes("-");
-    const isNegative = hasParentheses || hasMinus;
-
-    // Remove prefix, suffix, currency
-    const finalPrefix = currency || prefix;
     let cleaned = str;
-
-    if (finalPrefix) {
-      const escapedPrefix = finalPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      // Remove prefix from beginning, or after negative indicators
-      cleaned = cleaned.replace(new RegExp(`^${escapedPrefix}`), ""); // $123
-      cleaned = cleaned.replace(new RegExp(`^-${escapedPrefix}`), "-"); // -$123 -> -123
-      cleaned = cleaned.replace(new RegExp(`^\\(${escapedPrefix}`), "("); // ($123 -> (123
+    if (effPrefix) {
+      const e = esc(effPrefix);
+      cleaned = cleaned
+        .replace(new RegExp(`^${e}`), "")
+        .replace(new RegExp(`^-${e}`), "-")
+        .replace(new RegExp(`^\\(${e}`), "(");
     }
+    if (effSuffix) cleaned = cleaned.replace(new RegExp(`${esc(effSuffix)}\\)?$`), "");
 
-    if (suffix) {
-      const escapedSuffix = suffix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      cleaned = cleaned.replace(new RegExp(`${escapedSuffix}$`), "");
-    }
-
-    // Remove negative indicators
-    cleaned = cleaned.replace(/[()]/g, ""); // Remove parentheses
-    cleaned = cleaned.replace(/-/g, ""); // Remove minus signs
-
-    // Remove thousands separators (both , and . could be thousands separators)
-    cleaned = cleaned.replace(
-      new RegExp(`\\${thousandsChar.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
-      "",
-    );
-
-    // Convert decimal separator to standard decimal point
+    cleaned = cleaned.replace(/[()]/g, "").replace(/-/g, "");
+    cleaned = cleaned.replace(new RegExp(esc(thousandsChar), "g"), "");
     if (decimalSeparator !== ".") {
-      // Replace the decimal separator with standard decimal point
-      // But only the last occurrence to handle cases like "1.234,56"
-      const lastSeparatorIndex = cleaned.lastIndexOf(decimalSeparator);
-      if (lastSeparatorIndex !== -1) {
-        cleaned =
-          cleaned.substring(0, lastSeparatorIndex) +
-          "." +
-          cleaned.substring(lastSeparatorIndex + 1);
-      }
+      const last = cleaned.lastIndexOf(decimalSeparator);
+      if (last !== -1) cleaned = cleaned.substring(0, last) + "." + cleaned.substring(last + 1);
     }
 
     const parsed = parseFloat(cleaned);
     if (isNaN(parsed)) return null;
+    const signed = isNegative ? -parsed : parsed;
+    return percent ? signed / 100 : signed;
+  }
 
-    return isNegative ? -parsed : parsed;
+  // Live grouping only (thousands) — no toFixed/parentheses while typing, and a trailing decimal
+  // separator ("12.") is preserved so decimals can still be entered.
+  function liveGroup(raw: string): string {
+    const neg = negativeAllowed && raw.includes("-");
+    const sep = esc(decimalSeparator);
+    const cleaned = raw.replace(new RegExp(`[^0-9${sep}]`, "g"), "");
+    const firstSep = cleaned.indexOf(decimalSeparator);
+    const intPart = firstSep >= 0 ? cleaned.slice(0, firstSep) : cleaned;
+    const decPart =
+      firstSep >= 0 ? cleaned.slice(firstSep + 1).replace(new RegExp(sep, "g"), "") : null;
+    const grouped = enableThousandsSeparator
+      ? intPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousandsChar)
+      : intPart;
+    const body = grouped + (decPart !== null ? decimalSeparator + decPart : "");
+    if (body === "") return neg ? "-" : "";
+    return `${neg ? "-" : ""}${effPrefix}${body}${effSuffix}`;
   }
 
-  // Update display value when value changes
+  // Reflect external value changes into the field when the user isn't editing.
   $effect(() => {
-    if (!focused) {
-      displayValue = formatNumber(value);
-    }
+    if (!focused) displayValue = formatNumber(value);
   });
 
-  // Default validation
   const defaultValidator = (val: number | null) => {
-    if (val === null) return true; // Allow null/empty values
-
+    if (val === null) return true;
     if (min !== undefined && val < min) return `Value must be at least ${min}`;
     if (max !== undefined && val > max) return `Value must be at most ${max}`;
-
     if (!allowDecimals && val % 1 !== 0) return "Decimal values are not allowed";
-
     return true;
   };
+  const numberValidator = $derived(validate ?? defaultValidator);
+
+  function stepBy(dir: 1 | -1) {
+    const base = value ?? min ?? 0;
+    let next = Number((base + dir * step).toFixed(12));
+    if (!allowDecimals) next = Math.round(next);
+    next = clampVal(next);
+    value = next;
+    displayValue = formatNumber(next);
+    touched = true;
+  }
 
-  // Use custom validator if provided, otherwise use default
-  const numberValidator = validate || defaultValidator;
-
-  function handleInput(inputValue: string) {
-    displayValue = inputValue;
-
-    // Only skip parsing for truly incomplete inputs that have no numeric content
-    const finalPrefix = currency || prefix;
-
-    // Check if input is incomplete (has negative indicators but no actual numbers)
-    const incompletePatterns = [
-      "-", // Just minus
-      "(", // Just opening paren
-      "()", // Empty parens
-    ];
-
-    // Add prefix-related incomplete patterns
-    if (finalPrefix) {
-      incompletePatterns.push(
-        `-${finalPrefix}`, // -$, -€, etc.
-        `(${finalPrefix}`, // ($, (€, etc.
-        `(${finalPrefix})`, // ($), (€), etc.
-      );
-    }
-
-    // Add suffix-related incomplete patterns
-    if (suffix) {
-      incompletePatterns.push(
-        `-${suffix}`, // -%, etc.
-        `(${suffix}`, // (%, etc.
-        `(${suffix})`, // (%), etc.
-      );
-
-      // Combined prefix and suffix patterns
-      if (finalPrefix) {
-        incompletePatterns.push(
-          `-${finalPrefix}${suffix}`, // -$%, etc.
-          `(${finalPrefix}${suffix}`, // ($%, etc.
-          `(${finalPrefix}${suffix})`, // ($%), etc.
-        );
+  async function handleInput(raw: string) {
+    if (liveFormat) {
+      const el = element;
+      const caret = el?.selectionStart ?? raw.length;
+      const digitsLeft = raw.slice(0, caret).replace(/\D/g, "").length;
+      value = parseNumber(raw);
+      const disp = liveGroup(raw);
+      displayValue = disp;
+      await tick();
+      if (el) {
+        let pos = 0;
+        let count = 0;
+        while (pos < disp.length && count < digitsLeft) {
+          if (/\d/.test(disp[pos])) count++;
+          pos++;
+        }
+        el.setSelectionRange(pos, pos);
       }
-    }
-
-    if (incompletePatterns.includes(inputValue)) {
-      // Keep the current value but update display for incomplete inputs
       return;
     }
-
-    const parsed = parseNumber(inputValue);
-    value = parsed;
+    displayValue = raw;
+    // Incomplete inputs (just a sign / open paren) keep the current value until a digit arrives.
+    if (["-", "(", "()"].includes(raw)) return;
+    value = parseNumber(raw);
   }
 
   function handleFocus() {
     focused = true;
-    // Show the full formatted value including prefix/suffix for consistency
-    if (value !== null && !isNaN(value)) {
-      displayValue = formatNumber(value);
-    }
+    if (value !== null && !isNaN(value)) displayValue = formatNumber(value);
   }
 
   function handleBlur() {
     focused = false;
-    // Format the number when focus is lost
+    if (clamp && value !== null && !isNaN(value)) value = clampVal(value);
     displayValue = formatNumber(value);
   }
 
   function handleKeyDown(event: KeyboardEvent) {
-    // Allow control keys (backspace, delete, arrow keys, tab, etc.)
+    // Arrow-Up/Down step the value (spinbutton behavior), regardless of the visible stepper buttons.
+    if (event.key === "ArrowUp") {
+      event.preventDefault();
+      stepBy(1);
+      return;
+    }
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      stepBy(-1);
+      return;
+    }
     if (
       event.key === "Backspace" ||
       event.key === "Delete" ||
@@ -272,119 +260,99 @@
       event.key === "Home" ||
       event.key === "End" ||
       event.ctrlKey ||
-      event.metaKey // Allow Ctrl/Cmd shortcuts
+      event.metaKey
     ) {
       return;
     }
 
     const currentValue = displayValue;
-    const finalPrefix = currency || prefix;
     const input = event.target as HTMLInputElement;
     const cursorPosition = input.selectionStart || 0;
-
-    // Basic allowed characters
     const allowedChars = new Set(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]);
-
-    // Always allow both comma and period for international input flexibility
     allowedChars.add(",");
     allowedChars.add(".");
 
-    // Add currency characters (but validate position)
-    if (finalPrefix && event.key === finalPrefix) {
-      // Only allow currency at the beginning (after minus if present)
+    if (effPrefix && event.key === effPrefix) {
       const hasMinusAtStart = currentValue.startsWith("-");
       const expectedPosition = hasMinusAtStart ? 1 : 0;
-      if (cursorPosition === expectedPosition && !currentValue.includes(finalPrefix)) {
-        allowedChars.add(finalPrefix);
-      } else {
-        event.preventDefault();
-        return;
-      }
+      if (cursorPosition === expectedPosition && !currentValue.includes(effPrefix))
+        allowedChars.add(effPrefix);
+      else return void event.preventDefault();
     }
-
-    // Add suffix characters (but validate position and prevent duplicates)
-    if (suffix && event.key === suffix) {
-      // Only allow suffix at the end and if not already present
-      if (cursorPosition === currentValue.length && !currentValue.includes(suffix)) {
-        allowedChars.add(suffix);
-      } else {
-        event.preventDefault();
-        return;
-      }
+    if (effSuffix && event.key === effSuffix) {
+      if (cursorPosition === currentValue.length && !currentValue.includes(effSuffix))
+        allowedChars.add(effSuffix);
+      else return void event.preventDefault();
     }
-
-    // Always allow both minus and parentheses for input (negativeMode only affects display formatting)
     if (event.key === "-") {
-      // Only allow minus at the very beginning and if not already present
-      if (cursorPosition === 0 && !currentValue.includes("-")) {
+      if (negativeAllowed && cursorPosition === 0 && !currentValue.includes("-"))
         allowedChars.add("-");
-      } else {
-        event.preventDefault();
-        return;
-      }
+      else return void event.preventDefault();
     }
-
     if (event.key === "(") {
-      // Only allow opening parenthesis at the beginning and if not already present
-      if (cursorPosition === 0 && !currentValue.includes("(")) {
+      if (negativeAllowed && cursorPosition === 0 && !currentValue.includes("("))
         allowedChars.add("(");
-      } else {
-        event.preventDefault();
-        return;
-      }
+      else return void event.preventDefault();
     }
     if (event.key === ")") {
-      // Only allow closing parenthesis at the end, if opening exists, and no closing yet
       if (
         cursorPosition === currentValue.length &&
         currentValue.includes("(") &&
         !currentValue.includes(")")
-      ) {
+      )
         allowedChars.add(")");
-      } else {
-        event.preventDefault();
-        return;
-      }
+      else return void event.preventDefault();
     }
 
-    // Prevent typing if character is not allowed
-    if (!allowedChars.has(event.key)) {
-      event.preventDefault();
-    }
+    if (!allowedChars.has(event.key)) event.preventDefault();
   }
 
-  // Convert our number value to string for the Input component
   let stringValue = $derived(displayValue);
-
-  // Use native <input type="number"> when the caller isn't using any
-  // of the custom-formatting features (prefix / suffix / currency /
-  // thousands / non-`.` decimal / paren-negative). That gives them
-  // the browser spinner + arrow-key increment + guaranteed mobile
-  // numeric keypad. When formatting IS used, stay on type="text" so
-  // the browser doesn't strip `$`, `%`, `,`, `(`, etc.
-  const inputType = $derived(
-    prefix ||
-      suffix ||
-      currency ||
-      enableThousandsSeparator ||
-      decimalSeparator !== "." ||
-      negativeMode === "parentheses"
-      ? "text"
-      : "number",
-  );
+  const atMin = $derived(value !== null && min !== undefined && value <= min);
+  const atMax = $derived(value !== null && max !== undefined && value >= max);
 </script>
 
+<!-- Stepper ±. Defined at top level so it can be passed as the `actions` prop CONDITIONALLY (a
+     `{#snippet}` wrapped in `{#if}` is not forwarded as a prop). -->
+{#snippet stepperActions()}
+  <Button
+    variant="ghost"
+    size="sm"
+    tabindex={-1}
+    disabled={atMin}
+    onclick={() => stepBy(-1)}
+    aria-label="Decrease"
+    title="Decrease"
+  >
+    {#snippet icon()}<Minus />{/snippet}
+  </Button>
+  <Button
+    variant="ghost"
+    size="sm"
+    tabindex={-1}
+    disabled={atMax}
+    onclick={() => stepBy(1)}
+    aria-label="Increase"
+    title="Increase"
+  >
+    {#snippet icon()}<Plus />{/snippet}
+  </Button>
+{/snippet}
+
 <Input
   bind:value={stringValue}
   bind:valid
   bind:touched
   bind:element
-  type={inputType}
-  inputmode="numeric"
-  validate={(val) => {
-    const parsed = parseNumber(val);
-    return numberValidator(parsed);
-  }}
+  type="text"
+  inputmode={inputMode}
+  role="spinbutton"
+  aria-valuenow={value ?? undefined}
+  aria-valuemin={min}
+  aria-valuemax={max}
+  aria-valuetext={displayValue || undefined}
+  actions={stepper ? stepperActions : undefined}
+  validate={(val) => numberValidator(parseNumber(val))}
   oninput={(e) => handleInput((e.target as HTMLInputElement).value)}
   onfocus={handleFocus}
   onblur={handleBlur}

package/dist/components/NumberInput.svelte.d.ts

@@ -27,6 +27,18 @@ interface Props extends Omit<HTMLInputAttributes, "type" | "value" | "size"> {
     thousandsChar?: string;
     roundingMode?: "round" | "floor" | "ceil" | "trunc";
     negativeMode?: "minus" | "parentheses" | "both";
+    /** Hard-block the minus key + strip negatives on parse. Default: derived from `min`
+     *  (`min >= 0` ⇒ `false`, otherwise `true`). */
+    allowNegative?: boolean;
+    /** On blur, coerce the value into `[min, max]` instead of only surfacing a validation error. */
+    clamp?: boolean;
+    /** Show ± stepper buttons. Arrow-Up/Down always step by `step` (this just adds the buttons). */
+    stepper?: boolean;
+    /** Percent mode: store the fraction, display ×100 with a `%` suffix (`0.5` ⇄ `50%`).
+     *  `value` / `min` / `max` / `step` are all in the fraction units. */
+    percent?: boolean;
+    /** Group digits AS YOU TYPE (caret preserved) rather than only reformatting on blur. */
+    liveFormat?: boolean;
 }
 declare const NumberInput: import("svelte").Component<Props, {}, "element" | "value" | "valid" | "touched">;
 type NumberInput = ReturnType<typeof NumberInput>;

package/dist/components/PhoneInput.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+  import Input from "./Input.svelte";
+  import Phone from "~icons/mdi/phone-outline";
+  import type { HTMLInputAttributes } from "svelte/elements";
+  import type { Size } from "../types/sizes.js";
+  import type { Responsive } from "../types/responsive.js";
+  import type { Variant } from "../types/variants.js";
+
+  /**
+   * PhoneInput — type a phone number in ANY format; the bound `value` is stored in **E.164**
+   * (`+15551234567`): a leading `+`, country calling code, then the national number, digits only.
+   * The field shows what you type while editing and snaps to canonical E.164 on blur.
+   *
+   * **Dependency-free** by design — it normalises the E.164 *shape* only and does NOT do per-country
+   * formatting/validation (that needs a phone library + country data, which we don't bundle). To add
+   * that, inject `parse` / `format` / `validate` (e.g. backed by `libphonenumber-js`) — the component
+   * stays dep-free; you choose the library.
+   */
+  interface Props extends Omit<HTMLInputAttributes, "type" | "value" | "size"> {
+    /** Bound value in E.164 (`+15551234567`), normalised from whatever the user types. */
+    value: string;
+    class?: string;
+    inputClass?: string;
+    /** Validates the normalised E.164 value. Overrides the built-in E.164-shape check. */
+    validate?: (value: string) => boolean | string;
+    valid?: boolean;
+    touched?: boolean;
+    element?: HTMLInputElement;
+    size?: Responsive<Size>;
+    /** Shared axes — forwarded to the underlying Input. */
+    variant?: Variant;
+    borderless?: boolean;
+    required?: boolean;
+    /** Calling code (digits, no `+`) prepended when the typed number has no leading `+`. Default `"1"`
+     *  (North America). Set to the calling code of the numbers your users enter without a `+`. */
+    defaultCallingCode?: string;
+    /** Normalise typed text → stored E.164. Override to plug a library (e.g. libphonenumber-js). */
+    parse?: (input: string, defaultCallingCode: string) => string;
+    /** Format the stored E.164 → field display (default: shown as-is). Override for a national /
+     *  pretty format from your phone library. */
+    format?: (value: string) => string;
+  }
+
+  let {
+    value = $bindable(""),
+    valid = $bindable(true),
+    touched = $bindable(false),
+    element = $bindable(),
+    validate,
+    required = false,
+    defaultCallingCode = "1",
+    parse,
+    format,
+    placeholder = "(555) 123-4567",
+    ...restProps
+  }: Props = $props();
+
+  let displayValue = $state("");
+  let focused = $state(false);
+
+  // Default normalisation: an explicit international `+…` is kept (digits only after the `+`);
+  // otherwise the default calling code is prepended. SHAPE only — no per-country length check.
+  function defaultParse(raw: string, dcc: string): string {
+    const trimmed = (raw ?? "").trim();
+    if (!trimmed) return "";
+    const digits = trimmed.replace(/\D/g, "");
+    if (!digits) return "";
+    return trimmed.includes("+") ? `+${digits}` : `+${dcc}${digits}`;
+  }
+
+  const toE164 = (raw: string) => (parse ?? defaultParse)(raw, defaultCallingCode);
+  const toDisplay = (v: string) => (v ? (format ? format(v) : v) : "");
+
+  // Reflect external value changes into the field while the user isn't editing.
+  $effect(() => {
+    if (!focused) displayValue = toDisplay(value);
+  });
+
+  const defaultValidator = (v: string) => {
+    if (!v) return required ? "Phone number is required" : true;
+    // E.164 shape: `+`, a non-zero country digit, then 6–14 more digits (7–15 total).
+    if (!/^\+[1-9]\d{6,14}$/.test(v)) return "Enter a valid phone number";
+    return true;
+  };
+  const phoneValidator = $derived(validate ?? defaultValidator);
+
+  function handleInput(raw: string) {
+    displayValue = raw;
+    value = toE164(raw);
+  }
+  function handleFocus() {
+    focused = true;
+    displayValue = toDisplay(value);
+  }
+  function handleBlur() {
+    focused = false;
+    displayValue = toDisplay(value); // snap the field to the canonical (or your `format`) form
+  }
+
+  let stringValue = $derived(displayValue);
+</script>
+
+<Input
+  bind:value={stringValue}
+  bind:valid
+  bind:touched
+  bind:element
+  type="tel"
+  inputmode="tel"
+  autocomplete="tel"
+  {required}
+  validate={(val) => phoneValidator(toE164(val))}
+  oninput={(e) => handleInput((e.target as HTMLInputElement).value)}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+  {placeholder}
+  {...restProps}
+>
+  {#snippet icon()}<Phone />{/snippet}
+</Input>

package/dist/components/PhoneInput.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { Size } from "../types/sizes.js";
+import type { Responsive } from "../types/responsive.js";
+import type { Variant } from "../types/variants.js";
+/**
+ * PhoneInput — type a phone number in ANY format; the bound `value` is stored in **E.164**
+ * (`+15551234567`): a leading `+`, country calling code, then the national number, digits only.
+ * The field shows what you type while editing and snaps to canonical E.164 on blur.
+ *
+ * **Dependency-free** by design — it normalises the E.164 *shape* only and does NOT do per-country
+ * formatting/validation (that needs a phone library + country data, which we don't bundle). To add
+ * that, inject `parse` / `format` / `validate` (e.g. backed by `libphonenumber-js`) — the component
+ * stays dep-free; you choose the library.
+ */
+interface Props extends Omit<HTMLInputAttributes, "type" | "value" | "size"> {
+    /** Bound value in E.164 (`+15551234567`), normalised from whatever the user types. */
+    value: string;
+    class?: string;
+    inputClass?: string;
+    /** Validates the normalised E.164 value. Overrides the built-in E.164-shape check. */
+    validate?: (value: string) => boolean | string;
+    valid?: boolean;
+    touched?: boolean;
+    element?: HTMLInputElement;
+    size?: Responsive<Size>;
+    /** Shared axes — forwarded to the underlying Input. */
+    variant?: Variant;
+    borderless?: boolean;
+    required?: boolean;
+    /** Calling code (digits, no `+`) prepended when the typed number has no leading `+`. Default `"1"`
+     *  (North America). Set to the calling code of the numbers your users enter without a `+`. */
+    defaultCallingCode?: string;
+    /** Normalise typed text → stored E.164. Override to plug a library (e.g. libphonenumber-js). */
+    parse?: (input: string, defaultCallingCode: string) => string;
+    /** Format the stored E.164 → field display (default: shown as-is). Override for a national /
+     *  pretty format from your phone library. */
+    format?: (value: string) => string;
+}
+declare const PhoneInput: import("svelte").Component<Props, {}, "element" | "value" | "valid" | "touched">;
+type PhoneInput = ReturnType<typeof PhoneInput>;
+export default PhoneInput;

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { default as PasswordInput } from "./components/PasswordInput.svelte";
 export { default as EmailInput } from "./components/EmailInput.svelte";
 export { default as SearchInput } from "./components/SearchInput.svelte";
 export { default as NumberInput } from "./components/NumberInput.svelte";
+export { default as PhoneInput } from "./components/PhoneInput.svelte";
 export { default as DateTimeInput } from "./components/DateTimeInput.svelte";
 export { default as Calendar } from "./components/Calendar.svelte";
 export { default as DatePicker } from "./components/DatePicker.svelte";

package/dist/index.js

@@ -24,6 +24,7 @@ export { default as PasswordInput } from "./components/PasswordInput.svelte";
 export { default as EmailInput } from "./components/EmailInput.svelte";
 export { default as SearchInput } from "./components/SearchInput.svelte";
 export { default as NumberInput } from "./components/NumberInput.svelte";
+export { default as PhoneInput } from "./components/PhoneInput.svelte";
 export { default as DateTimeInput } from "./components/DateTimeInput.svelte";
 export { default as Calendar } from "./components/Calendar.svelte";
 export { default as DatePicker } from "./components/DatePicker.svelte";

package/docs/components.md

@@ -194,8 +194,32 @@ Thin wrappers over `Input`, each preconfigured with an MDI icon (rendered into I
 
 ### NumberInput
 
+Formatted numeric field (value-vs-display split; always `type="text"`, so validation is deferred to
+blur/submit).
+
 - **Location**: `src/lib/components/NumberInput.svelte`
-- **Features**: number formatting and validation
+- **Value**: `number | null` (bindable)
+- **Formatting**: `decimalPlaces`, `allowDecimals`, `roundingMode`, `thousandsSeparator`/`thousandsChar`,
+  `decimalSeparator`, `prefix`/`suffix`/`currency` (symbol), `negativeMode` (`minus`/`parentheses`/`both`),
+  and **`liveFormat`** (group as you type, caret-preserved).
+- **Numeric**: `min`, `max`, `step`, **`clamp`** (coerce into range on blur), **`allowNegative`**
+  (default off when `min >= 0`), **`stepper`** (± buttons + Arrow-Up/Down, `role="spinbutton"`),
+  and **`percent`** (display ×100 `%`, store the fraction; `min`/`max`/`step` in fraction units).
+- Dep-free by design — for locale/`Intl` or currency codes, format upstream or via `validate`.
+
+### PhoneInput
+
+Type any format; stores the bound value as **E.164** (`+15551234567`). Field shows what you type,
+snaps to canonical on blur.
+
+- **Location**: `src/lib/components/PhoneInput.svelte`
+- **Value**: `string` (E.164)
+- **Props**: `defaultCallingCode` (digits, default `"1"` — prepended when input has no `+`), `required`,
+  `validate` (validates the E.164), and the injection hooks **`parse`** (typed → E.164) / **`format`**
+  (E.164 → display).
+- **Dep-free** — normalises the E.164 *shape* only (no per-country validation/formatting). For that,
+  inject `parse`/`format`/`validate` backed by a phone library (e.g. `libphonenumber-js`); the
+  component bundles none.
 
 ## Navigation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.7.1-dev.38.b73de30",
+  "version": "0.7.1-dev.40.3d22ac0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"