@cfasim-ui/docs 0.3.16 → 0.3.18

package/components/NumberInput/NumberInput.md

@@ -12,6 +12,16 @@ const days = ref(10)
 const population = ref(100000)
 const coverage = ref(0.5)
 const r0 = ref(3.5)
+const ageRange = ref([18, 65])
+const coverageRange = ref([0.2, 0.8])
+const minAge = ref(18)
+const maxAge = ref(65)
+const dayMs = 24 * 60 * 60 * 1000
+const dateStart = Date.UTC(2024, 0, 1)
+const dateEnd = Date.UTC(2024, 11, 31)
+const dateRange = ref([Date.UTC(2024, 2, 1), Date.UTC(2024, 8, 30)])
+const formatDate = (ms) =>
+  new Date(ms).toLocaleDateString("en-US", { month: "short", day: "numeric" })
 </script>
 
 <ComponentDemo>
@@ -116,6 +126,157 @@ const days = ref(10);
   </template>
 </ComponentDemo>
 
+### Range slider
+
+Bind `v-model:range` with a `[low, high]` tuple to render a two-handle
+slider. Range mode is enabled automatically by the binding — there's no
+explicit toggle prop.
+
+<ComponentDemo>
+  <div style="width: 300px">
+    <NumberInput
+      v-model:range="ageRange"
+      label="Age range"
+      :min="0"
+      :max="100"
+      number-type="integer"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const ageRange = ref([18, 65]);
+</script>
+
+<NumberInput
+  v-model:range="ageRange"
+  label="Age range"
+  :min="0"
+  :max="100"
+  number-type="integer"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Range slider with split bindings
+
+When your state stores the bounds in separate refs (rather than as a tuple),
+bind them directly with `v-model:lower` and `v-model:upper`. You can bind
+either pair or combine them with `v-model:range` — writes from the component
+go to every bound sink.
+
+<ComponentDemo>
+  <div style="width: 300px">
+    <NumberInput
+      v-model:lower="minAge"
+      v-model:upper="maxAge"
+      label="Age range (split)"
+      :min="0"
+      :max="100"
+      number-type="integer"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const minAge = ref(18);
+const maxAge = ref(65);
+</script>
+
+<NumberInput
+  v-model:lower="minAge"
+  v-model:upper="maxAge"
+  label="Age range"
+  :min="0"
+  :max="100"
+  number-type="integer"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Range mode works with `percent` and `live` as well:
+
+<ComponentDemo>
+  <div style="width: 300px">
+    <NumberInput
+      v-model:range="coverageRange"
+      label="Coverage range"
+      percent
+      live
+      :max="1"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<NumberInput
+  v-model:range="coverageRange"
+  label="Coverage range"
+  percent
+  live
+  :max="1"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Custom slider display
+
+Pass `slider-display` (a `(value: number) => string` function) to format the
+thumb labels and the min/max labels however you like. The internal model is
+still a number — only the displayed text changes. This applies to single
+sliders and ranges; the regular text input is unaffected.
+
+<ComponentDemo>
+  <div style="width: 300px">
+    <NumberInput
+      v-model:range="dateRange"
+      label="Date range"
+      :min="dateStart"
+      :max="dateEnd"
+      :step="dayMs"
+      :slider-display="formatDate"
+    />
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref } from "vue";
+const dayMs = 24 * 60 * 60 * 1000;
+const dateStart = Date.UTC(2024, 0, 1);
+const dateEnd = Date.UTC(2024, 11, 31);
+const dateRange = ref([Date.UTC(2024, 2, 1), Date.UTC(2024, 8, 30)]);
+const formatDate = (ms) =>
+  new Date(ms).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+</script>
+
+<NumberInput
+  v-model:range="dateRange"
+  label="Date range"
+  :min="dateStart"
+  :max="dateEnd"
+  :step="dayMs"
+  :slider-display="formatDate"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Live slider
 
 With `live`, the model updates while dragging the slider thumb rather than only on release.
@@ -284,6 +445,9 @@ the input visually.
 | Name | Type |
 |------|------|
 | `v-model` | `number` |
+| `v-model:range` | `NumberRange` |
+| `v-model:lower` | `number` |
+| `v-model:upper` | `number` |
 
 ## Props
 
@@ -302,4 +466,5 @@ the input visually.
 | `numberType` | `"integer" \| "float"` | No | — |
 | `required` | `boolean` | No | — |
 | `decimals` | `number` | No | — |
+| `sliderDisplay` | `(value: number) =&gt; string` | No | — |
 

package/components/NumberInput/NumberInput.vue

@@ -1,9 +1,19 @@
 <script setup lang="ts">
-import { ref, watch, computed } from "vue";
+import { ref, watch, computed, onMounted, getCurrentInstance } from "vue";
 import { SliderRoot, SliderTrack, SliderRange, SliderThumb } from "reka-ui";
 import Hint from "../Hint/Hint.vue";
 
+export type NumberRange = [number, number];
+
+// The default `v-model` is always a scalar number. For range mode, bind
+// `v-model:range` (a tuple) and/or the split `v-model:lower`/`v-model:upper`.
+// Mode is auto-detected from which v-model bindings the parent provides;
+// no explicit toggle prop. Precedence on read: lower/upper > range >
+// slider defaults.
 const model = defineModel<number>();
+const range = defineModel<NumberRange>("range");
+const lower = defineModel<number>("lower");
+const upper = defineModel<number>("upper");
 
 const props = defineProps<{
   label?: string;
@@ -19,8 +29,43 @@ const props = defineProps<{
   numberType?: "integer" | "float";
   required?: boolean;
   decimals?: number;
+  // Custom formatter for slider thumb labels and min/max labels. Overrides
+  // the default percent/decimal formatting when provided. Only consulted in
+  // slider/range mode — the text input keeps its own number-shaped formatting.
+  sliderDisplay?: (value: number) => string;
 }>();
 
+function isRangeValue(v: unknown): v is NumberRange {
+  return Array.isArray(v) && v.length === 2;
+}
+
+// Auto-detect range mode from the parent's v-model bindings. We check both
+// the listener (which Vue attaches as `onUpdate:<name>` on the vnode) and
+// the initial value — that way one-way `:range="x"` bindings also work.
+// Determined once at setup; mode doesn't change for the component's life.
+const instance = getCurrentInstance();
+const vnodeProps = instance?.vnode.props;
+const isRange =
+  !!vnodeProps?.["onUpdate:range"] ||
+  !!vnodeProps?.["onUpdate:lower"] ||
+  !!vnodeProps?.["onUpdate:upper"] ||
+  range.value !== undefined ||
+  lower.value !== undefined ||
+  upper.value !== undefined;
+
+// Range implies slider — a two-handle range has no sensible text-input form.
+const isSlider = computed(() => !!props.slider || isRange);
+
+// Warn if the parent bound the default `v-model` in range mode — it will
+// never receive updates, which is almost always a bug.
+onMounted(() => {
+  if (isRange && !!vnodeProps?.["onUpdate:modelValue"]) {
+    console.warn(
+      "[NumberInput] In range mode, the default `v-model` is unused. Bind `v-model:range` or `v-model:lower`/`v-model:upper` instead.",
+    );
+  }
+});
+
 const sliderMin = computed(() => props.min ?? (props.percent ? 0 : 0));
 const sliderMax = computed(() => props.max ?? (props.percent ? 1 : 100));
 const sliderStep = computed(() => props.step ?? (props.percent ? 0.01 : 1));
@@ -68,6 +113,7 @@ function roundToDecimals(v: number, d: number): number {
 
 function formatSliderValue(v: number | undefined) {
   if (v == null) return "";
+  if (props.sliderDisplay) return props.sliderDisplay(v);
   const d = displayDecimals.value;
   if (props.percent) return (v * 100).toFixed(d) + "%";
   return v.toLocaleString("en-US", {
@@ -121,13 +167,50 @@ function stripCommas(s: string): string {
   return s.replace(/,/g, "");
 }
 
-const local = ref(formatForDisplay(toDisplay(model.value)));
-const sliderLocal = ref(model.value);
+// Resolve the current value across all bindings:
+// - In range mode: lower/upper take precedence; falls back per-side to
+//   `range`; finally to slider min/max. The default `v-model` is
+//   unused in this mode.
+// - In single mode: just the default `v-model`.
+function effectiveValue(): number | NumberRange | undefined {
+  if (isRange) {
+    const tuple = range.value;
+    const lo = lower.value ?? tuple?.[0];
+    const hi = upper.value ?? tuple?.[1];
+    if (lo !== undefined || hi !== undefined) {
+      return [lo ?? sliderMin.value, hi ?? sliderMax.value];
+    }
+    return undefined;
+  }
+  return model.value;
+}
+
+// Initial single-value display string. The text input isn't rendered in
+// range mode, so `local` is only consulted in single mode.
+const initialEffective = effectiveValue();
+const initialSingle =
+  typeof initialEffective === "number" ? initialEffective : undefined;
+const local = ref(formatForDisplay(toDisplay(initialSingle)));
+
+// Slider state is always an array, even in single mode (reka-ui's API).
+// In range mode it holds [low, high]; in single mode it holds [value].
+function modelToSliderArray(v: number | NumberRange | undefined): number[] {
+  if (isRange) {
+    if (isRangeValue(v)) return [v[0], v[1]];
+    return [sliderMin.value, sliderMax.value];
+  }
+  if (typeof v === "number") return [v];
+  return [sliderMin.value];
+}
+const sliderArrayLocal = ref<number[]>(modelToSliderArray(initialEffective));
 const validationError = ref<string>();
 
-watch(model, (v) => {
-  local.value = formatForDisplay(toDisplay(v));
-  sliderLocal.value = v;
+watch([model, range, lower, upper], () => {
+  const v = effectiveValue();
+  if (!isRange && !isRangeValue(v)) {
+    local.value = formatForDisplay(toDisplay(v as number | undefined));
+  }
+  sliderArrayLocal.value = modelToSliderArray(v);
   validationError.value = validate(v);
 });
 
@@ -179,21 +262,17 @@ function onBlur() {
 
 let liveTimeout: ReturnType<typeof setTimeout> | null = null;
 function onInputEvent() {
-  if (!props.live || props.slider) return;
+  if (!props.live || isSlider.value) return;
   if (liveTimeout) clearTimeout(liveTimeout);
   liveTimeout = setTimeout(commit, 300);
 }
 function onChangeEvent() {
-  if (!props.live || props.slider) return;
+  if (!props.live || isSlider.value) return;
   if (liveTimeout) clearTimeout(liveTimeout);
   commit();
 }
 
-// Validates a model value (or undefined for empty). Single source of truth
-// for required / min / max errors — used on commit, programmatic updates,
-// and arrow-key stepping.
-function validate(v: number | undefined): string | undefined {
-  if (v == null) return props.required ? "Required" : undefined;
+function validateScalar(v: number): string | undefined {
   const display = toDisplay(v) as number;
   if (inputMin.value != null && display < inputMin.value) {
     return `Min ${inputMin.value}${props.percent ? "%" : ""}`;
@@ -204,11 +283,28 @@ function validate(v: number | undefined): string | undefined {
   return undefined;
 }
 
+// Single source of truth for required / min / max errors — used on commit,
+// programmatic updates, and arrow-key stepping. In range mode, returns the
+// first failing handle's error, suffixed with "(lower)" or "(upper)".
+function validate(v: number | NumberRange | undefined): string | undefined {
+  if (v == null) return props.required ? "Required" : undefined;
+  if (isRangeValue(v)) {
+    const lo = validateScalar(v[0]);
+    if (lo) return `${lo} (lower)`;
+    const hi = validateScalar(v[1]);
+    if (hi) return `${hi} (upper)`;
+    return undefined;
+  }
+  return validateScalar(v);
+}
+
 function commit() {
-  // An empty field clears the model — distinct from garbage input.
+  // commit() is only reachable when !isSlider (only text-input events call
+  // it). Default `v-model` is scalar-only.
+  const current = model.value;
   if (local.value.trim() === "") {
     model.value = undefined;
-    sliderLocal.value = undefined;
+    sliderArrayLocal.value = modelToSliderArray(undefined);
     validationError.value = validate(undefined);
     return;
   }
@@ -219,8 +315,8 @@ function commit() {
   // turn pure garbage ("abc") into 0. Reset to the current model value so
   // invalid input doesn't linger in the field.
   if (!/\d/.test(cleaned)) {
-    local.value = formatForDisplay(toDisplay(model.value));
-    validationError.value = validate(model.value);
+    local.value = formatForDisplay(toDisplay(current));
+    validationError.value = validate(current);
     return;
   }
   if (cleaned !== local.value) {
@@ -240,22 +336,43 @@ function commit() {
   if (error) return;
 
   model.value = next;
-  sliderLocal.value = model.value;
+  sliderArrayLocal.value = [next];
+}
+
+function commitSliderArray(v: number[], asModel: boolean): void {
+  const coerced = v.map(coerceInteger);
+  sliderArrayLocal.value = coerced;
+  if (!isRange) {
+    local.value = formatForDisplay(toDisplay(coerced[0]));
+  }
+  if (asModel) {
+    if (isRange) {
+      // Emit to all range sinks; consumers without a matching v-model just
+      // ignore their `update:*` event. The default `v-model` is unused in
+      // range mode.
+      range.value = [coerced[0], coerced[1]] as NumberRange;
+      lower.value = coerced[0];
+      upper.value = coerced[1];
+    } else {
+      model.value = coerced[0];
+    }
+  }
+}
+
+function thumbAriaLabel(i: number): string | undefined {
+  if (!props.label) return undefined;
+  if (!isRange) return props.label;
+  return i === 0 ? `${props.label} (lower)` : `${props.label} (upper)`;
 }
 
 function onSliderUpdate(v: number[] | undefined) {
   if (!v) return;
-  const val = coerceInteger(v[0]);
-  sliderLocal.value = val;
-  local.value = formatForDisplay(toDisplay(val));
-  if (props.live) {
-    model.value = val;
-  }
+  commitSliderArray(v, !!props.live);
 }
 
 function onSliderCommit(v: number[] | undefined) {
   if (!v) return;
-  model.value = coerceInteger(v[0]);
+  commitSliderArray(v, true);
 }
 
 function onArrowStep(event: KeyboardEvent, direction: 1 | -1) {
@@ -268,71 +385,26 @@ function onArrowStep(event: KeyboardEvent, direction: 1 | -1) {
   if (inputMin.value != null) next = Math.max(next, inputMin.value);
   if (inputMax.value != null) next = Math.min(next, inputMax.value);
   local.value = formatForDisplay(next);
-  model.value = fromDisplay(next);
-  sliderLocal.value = model.value;
+  const nextModel = fromDisplay(next);
+  model.value = nextModel;
+  sliderArrayLocal.value = [nextModel];
 }
 </script>
 
 <template>
-  <label v-if="props.label" class="input-label">
+  <component
+    :is="props.label ? 'label' : 'div'"
+    :class="props.label ? 'input-label' : undefined"
+  >
     <span
+      v-if="props.label"
       class="input-label-row"
       :class="{ 'visually-hidden': props.hideLabel }"
     >
       {{ props.label }}
       <Hint v-if="props.hint && !props.hideLabel" :text="props.hint" />
     </span>
-    <span v-if="!props.slider" class="input-wrapper">
-      <input
-        type="text"
-        :inputmode="props.numberType === 'integer' ? 'numeric' : 'decimal'"
-        v-model="local"
-        :placeholder="props.placeholder"
-        :aria-invalid="!!validationError"
-        :aria-required="props.required || undefined"
-        :required="props.required"
-        @blur="onBlur"
-        @keydown.enter="commit"
-        @keydown.up="onArrowStep($event, 1)"
-        @keydown.down="onArrowStep($event, -1)"
-        @input="
-          reformatInput($event);
-          onInputEvent();
-        "
-        @change="onChangeEvent"
-      />
-      <span v-if="props.percent" class="input-suffix">%</span>
-    </span>
-    <span v-if="validationError" class="input-error" role="alert">
-      {{ validationError }}
-    </span>
-    <div v-if="props.slider" class="slider-container">
-      <SliderRoot
-        class="slider-root"
-        :model-value="sliderLocal != null ? [sliderLocal] : [sliderMin]"
-        :min="sliderMin"
-        :max="sliderMax"
-        :step="sliderStep"
-        @update:model-value="onSliderUpdate"
-        @value-commit="onSliderCommit"
-      >
-        <SliderTrack class="slider-track">
-          <SliderRange class="slider-range" />
-        </SliderTrack>
-        <SliderThumb class="slider-thumb" :aria-label="props.label">
-          <span class="slider-current">
-            {{ formatSliderValue(sliderLocal) }}
-          </span>
-        </SliderThumb>
-      </SliderRoot>
-      <div class="slider-labels">
-        <span>{{ formatSliderValue(sliderMin) }}</span>
-        <span>{{ formatSliderValue(sliderMax) }}</span>
-      </div>
-    </div>
-  </label>
-  <div v-else>
-    <span v-if="!props.slider" class="input-wrapper">
+    <span v-if="!isSlider" class="input-wrapper">
       <input
         type="text"
         :inputmode="props.numberType === 'integer' ? 'numeric' : 'decimal'"
@@ -356,10 +428,10 @@ function onArrowStep(event: KeyboardEvent, direction: 1 | -1) {
     <span v-if="validationError" class="input-error" role="alert">
       {{ validationError }}
     </span>
-    <div v-if="props.slider" class="slider-container">
+    <div v-if="isSlider" class="slider-container">
       <SliderRoot
         class="slider-root"
-        :model-value="sliderLocal != null ? [sliderLocal] : [sliderMin]"
+        :model-value="sliderArrayLocal"
         :min="sliderMin"
         :max="sliderMax"
         :step="sliderStep"
@@ -369,9 +441,14 @@ function onArrowStep(event: KeyboardEvent, direction: 1 | -1) {
         <SliderTrack class="slider-track">
           <SliderRange class="slider-range" />
         </SliderTrack>
-        <SliderThumb class="slider-thumb" :aria-label="props.label">
+        <SliderThumb
+          v-for="(v, i) in sliderArrayLocal"
+          :key="i"
+          class="slider-thumb"
+          :aria-label="thumbAriaLabel(i)"
+        >
           <span class="slider-current">
-            {{ formatSliderValue(sliderLocal) }}
+            {{ formatSliderValue(v) }}
           </span>
         </SliderThumb>
       </SliderRoot>
@@ -380,7 +457,7 @@ function onArrowStep(event: KeyboardEvent, direction: 1 | -1) {
         <span>{{ formatSliderValue(sliderMax) }}</span>
       </div>
     </div>
-  </div>
+  </component>
 </template>
 
 <style scoped>

package/components/index.ts

@@ -10,6 +10,7 @@ export { default as Hint } from "./Hint/Hint.vue";
 export { default as Icon } from "./Icon/Icon.vue";
 export { default as LightDarkToggle } from "./LightDarkToggle/LightDarkToggle.vue";
 export { default as NumberInput } from "./NumberInput/NumberInput.vue";
+export type { NumberRange } from "./NumberInput/NumberInput.vue";
 export { default as SelectBox } from "./SelectBox/SelectBox.vue";
 export type { SelectOption } from "./SelectBox/SelectBox.vue";
 export { default as SidebarLayout } from "./SidebarLayout/SidebarLayout.vue";

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.16",
+  "version": "0.3.18",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/docs",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {

package/theme/base.css

@@ -129,11 +129,6 @@ body {
   font-size: var(--font-size-md);
 }
 
-:root,
-body {
-  overflow: hidden;
-}
-
 h1,
 h2,
 h3,