ThekNumeric

A headless, high-performance, and masked numeric input library for Vue 3.
Inspired by AutoNumeric, built for modern Vue applications with real-time masking, strict types, and native component ergonomics.

?? Features

• Real-time Masking: Instantly formats input with separators, decimals, and symbols as the user types.
• Zero-Jitter Cursor Positioning: Prevents cursor jumping during real-time formatting, even when adding grouping characters.
• v-model Support: Emits a clean raw number | null value, while displaying a formatted string in the textbox.
• Scientific Notation Recovery: Reliably handles very small/large numbers without breaking the display value.
• Interactive Configurator: Build and copy your configuration directly from the Showcase.
• Headless & Style-Agnostic: Designed to be easily styled within any design system.
• Strictly Typed: Built with TypeScript for reliable development.

?? Installation

npm install theknumeric

??? Usage

<script setup>
import { ref } from 'vue';
import { ThekNumeric } from 'theknumeric';

const amount = ref(1234.56);
</script>

<template>
  <ThekNumeric
    v-model="amount"
    :precision="2"
    separator=","
    decimal="."
    prefix="$ "
    suffix=" USD"
    :digit-group="true"
  />
</template>

?? Properties

| Property | Type | Default | Description | | :----------- | :--------------- | :------ | :----------------------------------------------- | | v-model | number \| null | null | The raw numeric value. | | separator | string | "," | Character used for thousands grouping. | | decimal | string | "." | Character used for the decimal point. | | precision | number | 2 | Number of decimal places (0 for integers). | | prefix | string | "" | String prepended to the numeric value. | | suffix | string | "" | String appended to the numeric value. | | digitGroup | boolean | true | Toggle thousands grouping (e.g., 1,000 vs 1000). |

?? Showcase & Examples

Run the interactive showcase to explore the component configurator:

npm run dev

The showcase includes samples for:

• Integers & Decimals
• High-precision (4+ decimal places)
• Negative numbers & Currency signs
• European formatting (comma as decimal)
• Safe integer limits

📚 Documentation

• Architecture - High-level design and data flow.
• Design Document - Design decisions and UX considerations.
• API Reference - Full list of props and events.
• Technical Spec - Details on the masking engine and cursor logic.
• Agent Instructions - Guidelines for AI-assisted development.

🛡️ Standards & Quality

• Linting: Verified with oxlint.
• Formatting: Verified with oxfmt.
• Tests: 100% logic coverage with Vitest.

?? License

MIT