@umbra.ui/core 0.1.0

package/src/components/inputs/InputNumber/README.md

@@ -0,0 +1,749 @@
+# InputNumber
+
+A specialized numeric input component built with Vue 3 Composition API and TypeScript. The InputNumber component provides numeric input validation, range constraints, unit labels, and visual feedback with smooth animations and accessibility features.
+
+## Installation/Import
+
+```typescript
+import { InputNumber } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for ripple animation and lock icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const number = ref(0);
+
+const handleNumberUpdate = (value: number) => {
+  console.log("Number:", value);
+  number.value = value;
+};
+</script>
+
+<template>
+  <div>
+    <InputNumber
+      v-model:value="number"
+      placeholder="Enter a number"
+      :min="0"
+      :max="100"
+      label="items"
+      @update:value="handleNumberUpdate"
+    />
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name     | Type                                                          | Required | Default     | Description                            |
+| ------------- | ------------------------------------------------------------- | -------- | ----------- | -------------------------------------- |
+| `value`       | `number`                                                      | No       | `undefined` | The numeric value                      |
+| `placeholder` | `string`                                                      | No       | `"0"`       | Placeholder text displayed when empty  |
+| `min`         | `number`                                                      | No       | `undefined` | Minimum allowed value                  |
+| `max`         | `number`                                                      | No       | `undefined` | Maximum allowed value                  |
+| `label`       | `string`                                                      | No       | `undefined` | Unit label displayed next to the input |
+| `state`       | `"normal" \| "active" \| "disabled" \| "readonly" \| "error"` | No       | `"normal"`  | Current state of the input field       |
+
+## Events
+
+| Event Name     | Payload Type | Description                            |
+| -------------- | ------------ | -------------------------------------- |
+| `update:value` | `number`     | Emitted when the numeric value changes |
+
+## Slots
+
+This component does not use slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## Features
+
+### Range Validation
+
+- **Min/Max Constraints**: Enforces minimum and maximum value limits
+- **Real-time Validation**: Validates range constraints as the user types
+- **Error Messages**: Displays specific error messages for out-of-range values
+- **Visual Feedback**: Changes input state to error when values are out of range
+
+### Unit Labels
+
+- **Custom Labels**: Display unit labels (e.g., "kg", "items", "years") next to the input
+- **Dynamic Styling**: Unit labels adapt their appearance based on input state
+- **Responsive Design**: Unit labels maintain proper spacing and alignment
+
+### Input States
+
+- **Normal**: Standard input state
+- **Active**: Shows animated ripple icon for active state
+- **Disabled**: Prevents user interaction with lock icon
+- **Readonly**: Shows lock icon and prevents editing
+- **Error**: Automatically triggered when value is out of range
+
+## CSS Customization
+
+The InputNumber component uses CSS custom properties for theming. It inherits from the general input theme:
+
+```css
+/* Input colors */
+--input-background-normal: #ffffff;
+--input-background-filled: #f8f9fa;
+--input-text-empty: #6c757d;
+--input-text-filled: #212529;
+--input-border: #ced4da;
+--input-border-filled: #80bdff;
+--input-focus-border: #007bff;
+--input-placeholder: #6c757d;
+--input-placeholder-filled: #adb5bd;
+
+/* State-specific colors */
+--input-disabled-bg: #e9ecef;
+--input-disabled-text: #6c757d;
+--input-disabled-border: #ced4da;
+--input-disabled-placeholder: #adb5bd;
+
+--input-readonly-bg: #f8f9fa;
+--input-readonly-text: #495057;
+--input-readonly-border: #ced4da;
+--input-readonly-placeholder: #6c757d;
+
+--input-error-bg: #f8d7da;
+--input-error-text: #721c24;
+--input-error-border: #dc3545;
+--input-text-error: #dc3545;
+```
+
+## Examples
+
+### Basic Number Input
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const quantity = ref(0);
+</script>
+
+<template>
+  <div class="number-form">
+    <h3>Product Configuration</h3>
+
+    <div class="form-group">
+      <label>Quantity</label>
+      <InputNumber
+        v-model:value="quantity"
+        placeholder="Enter quantity"
+        :min="1"
+        :max="1000"
+        label="items"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.number-form {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Range Validation
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const age = ref(0);
+const temperature = ref(0);
+const percentage = ref(0);
+</script>
+
+<template>
+  <div class="range-examples">
+    <h3>Range Validation Examples</h3>
+
+    <div class="form-group">
+      <label>Age (18-65)</label>
+      <InputNumber
+        v-model:value="age"
+        placeholder="Enter your age"
+        :min="18"
+        :max="65"
+        label="years"
+      />
+    </div>
+
+    <div class="form-group">
+      <label>Temperature (-50 to 50)</label>
+      <InputNumber
+        v-model:value="temperature"
+        placeholder="Enter temperature"
+        :min="-50"
+        :max="50"
+        label="°C"
+      />
+    </div>
+
+    <div class="form-group">
+      <label>Progress (0-100)</label>
+      <InputNumber
+        v-model:value="percentage"
+        placeholder="Enter percentage"
+        :min="0"
+        :max="100"
+        label="%"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.range-examples {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1.5rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Different States
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const normalNumber = ref(0);
+const disabledNumber = ref(42);
+const readonlyNumber = ref(100);
+const errorNumber = ref(150); // Will trigger error if max is 100
+</script>
+
+<template>
+  <div class="states-example">
+    <h3>Input States</h3>
+
+    <div class="state-group">
+      <label>Normal State</label>
+      <InputNumber
+        v-model:value="normalNumber"
+        placeholder="Enter a number"
+        state="normal"
+        label="units"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Disabled State</label>
+      <InputNumber
+        v-model:value="disabledNumber"
+        state="disabled"
+        label="items"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Readonly State</label>
+      <InputNumber
+        v-model:value="readonlyNumber"
+        state="readonly"
+        label="count"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Error State (Out of Range)</label>
+      <InputNumber
+        v-model:value="errorNumber"
+        :max="100"
+        state="normal"
+        label="items"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.states-example {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.state-group {
+  margin-bottom: 1.5rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Calculator Form
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const calculatorData = ref({
+  firstNumber: 0,
+  secondNumber: 0,
+  operation: "add",
+});
+
+const result = computed(() => {
+  const { firstNumber, secondNumber, operation } = calculatorData.value;
+
+  switch (operation) {
+    case "add":
+      return firstNumber + secondNumber;
+    case "subtract":
+      return firstNumber - secondNumber;
+    case "multiply":
+      return firstNumber * secondNumber;
+    case "divide":
+      return secondNumber !== 0 ? firstNumber / secondNumber : 0;
+    default:
+      return 0;
+  }
+});
+</script>
+
+<template>
+  <div class="calculator-form">
+    <h3>Simple Calculator</h3>
+
+    <div class="calculator-inputs">
+      <div class="form-group">
+        <label>First Number</label>
+        <InputNumber
+          v-model:value="calculatorData.firstNumber"
+          placeholder="0"
+          label=""
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Operation</label>
+        <select v-model="calculatorData.operation">
+          <option value="add">+ (Add)</option>
+          <option value="subtract">- (Subtract)</option>
+          <option value="multiply">× (Multiply)</option>
+          <option value="divide">÷ (Divide)</option>
+        </select>
+      </div>
+
+      <div class="form-group">
+        <label>Second Number</label>
+        <InputNumber
+          v-model:value="calculatorData.secondNumber"
+          placeholder="0"
+          label=""
+        />
+      </div>
+    </div>
+
+    <div class="result">
+      <h4>Result: {{ result }}</h4>
+    </div>
+  </div>
+</template>
+
+<style module>
+.calculator-form {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.calculator-inputs {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  gap: 1rem;
+  align-items: end;
+  margin-bottom: 1.5rem;
+}
+
+.form-group {
+  display: flex;
+  flex-direction: column;
+}
+
+label {
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+select {
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+}
+
+.result {
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 4px;
+  text-align: center;
+}
+
+.result h4 {
+  margin: 0;
+  color: #333;
+}
+</style>
+```
+
+### Settings Panel
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const settings = ref({
+  maxConnections: 10,
+  timeoutSeconds: 30,
+  retryAttempts: 3,
+  cacheSize: 100,
+  refreshInterval: 60,
+});
+
+const handleSaveSettings = () => {
+  console.log("Saving settings:", settings.value);
+  // Save settings logic here
+};
+</script>
+
+<template>
+  <div class="settings-panel">
+    <h3>Application Settings</h3>
+
+    <form @submit.prevent="handleSaveSettings">
+      <div class="settings-grid">
+        <div class="setting-group">
+          <label>Max Connections</label>
+          <InputNumber
+            v-model:value="settings.maxConnections"
+            :min="1"
+            :max="100"
+            label="connections"
+          />
+        </div>
+
+        <div class="setting-group">
+          <label>Timeout</label>
+          <InputNumber
+            v-model:value="settings.timeoutSeconds"
+            :min="5"
+            :max="300"
+            label="seconds"
+          />
+        </div>
+
+        <div class="setting-group">
+          <label>Retry Attempts</label>
+          <InputNumber
+            v-model:value="settings.retryAttempts"
+            :min="0"
+            :max="10"
+            label="attempts"
+          />
+        </div>
+
+        <div class="setting-group">
+          <label>Cache Size</label>
+          <InputNumber
+            v-model:value="settings.cacheSize"
+            :min="10"
+            :max="1000"
+            label="MB"
+          />
+        </div>
+
+        <div class="setting-group">
+          <label>Refresh Interval</label>
+          <InputNumber
+            v-model:value="settings.refreshInterval"
+            :min="10"
+            :max="3600"
+            label="seconds"
+          />
+        </div>
+      </div>
+
+      <button type="submit">Save Settings</button>
+    </form>
+  </div>
+</template>
+
+<style module>
+.settings-panel {
+  max-width: 600px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.settings-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.setting-group {
+  display: flex;
+  flex-direction: column;
+}
+
+label {
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+  font-size: 0.9rem;
+}
+
+button {
+  width: 100%;
+  padding: 0.75rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 1rem;
+}
+
+button:hover {
+  background-color: #0056b3;
+}
+</style>
+```
+
+### Measurement Converter
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputNumber } from "@umbra-ui/core";
+
+const measurement = ref({
+  value: 0,
+  unit: "meters",
+});
+
+const convertedValue = computed(() => {
+  const { value, unit } = measurement.value;
+
+  switch (unit) {
+    case "meters":
+      return {
+        feet: value * 3.28084,
+        inches: value * 39.3701,
+        yards: value * 1.09361,
+      };
+    case "feet":
+      return {
+        meters: value * 0.3048,
+        inches: value * 12,
+        yards: value * 0.333333,
+      };
+    case "inches":
+      return {
+        meters: value * 0.0254,
+        feet: value * 0.0833333,
+        yards: value * 0.0277778,
+      };
+    case "yards":
+      return {
+        meters: value * 0.9144,
+        feet: value * 3,
+        inches: value * 36,
+      };
+    default:
+      return { meters: 0, feet: 0, inches: 0, yards: 0 };
+  }
+});
+</script>
+
+<template>
+  <div class="converter">
+    <h3>Length Converter</h3>
+
+    <div class="converter-input">
+      <div class="form-group">
+        <label>Enter Length</label>
+        <div class="input-with-select">
+          <InputNumber
+            v-model:value="measurement.value"
+            placeholder="0"
+            :min="0"
+            label=""
+          />
+          <select v-model="measurement.unit">
+            <option value="meters">Meters</option>
+            <option value="feet">Feet</option>
+            <option value="inches">Inches</option>
+            <option value="yards">Yards</option>
+          </select>
+        </div>
+      </div>
+    </div>
+
+    <div class="conversion-results">
+      <h4>Converted Values</h4>
+      <div class="results-grid">
+        <div class="result-item">
+          <span class="value">{{ convertedValue.meters.toFixed(2) }}</span>
+          <span class="unit">Meters</span>
+        </div>
+        <div class="result-item">
+          <span class="value">{{ convertedValue.feet.toFixed(2) }}</span>
+          <span class="unit">Feet</span>
+        </div>
+        <div class="result-item">
+          <span class="value">{{ convertedValue.inches.toFixed(2) }}</span>
+          <span class="unit">Inches</span>
+        </div>
+        <div class="result-item">
+          <span class="value">{{ convertedValue.yards.toFixed(2) }}</span>
+          <span class="unit">Yards</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.converter {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1.5rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.input-with-select {
+  display: flex;
+  gap: 0.5rem;
+  align-items: end;
+}
+
+.input-with-select select {
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+  min-width: 120px;
+}
+
+.conversion-results {
+  margin-top: 1.5rem;
+}
+
+.conversion-results h4 {
+  margin-bottom: 1rem;
+  color: #333;
+}
+
+.results-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
+  gap: 1rem;
+}
+
+.result-item {
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 4px;
+  text-align: center;
+}
+
+.result-item .value {
+  display: block;
+  font-size: 1.5rem;
+  font-weight: bold;
+  color: #007bff;
+}
+
+.result-item .unit {
+  display: block;
+  font-size: 0.9rem;
+  color: #666;
+  margin-top: 0.25rem;
+}
+</style>
+```
+
+## Notes
+
+- The component automatically validates numeric input and enforces min/max constraints
+- Range validation triggers error state with specific error messages
+- Unit labels are displayed in a styled container that adapts to input state
+- The component hides browser default number input spinners for a cleaner appearance
+- Input is optimized for mobile devices with proper font sizes to prevent zoom
+- The component supports both positive and negative numbers within specified ranges
+- Empty values are treated as valid (undefined) and don't trigger range errors
+- Visual feedback includes animated icons for different states (active, readonly, disabled)
+- The component is fully accessible with proper ARIA attributes and keyboard navigation
+- Range validation messages are automatically generated based on min/max constraints
+- Unit labels maintain consistent styling across different input states and themes