srcdev-nuxt-components 9.6.7 → 9.6.9

package/app/components/05.forms/input-range/tests/{InputRangeDefault.spec.ts → InputRangeField.spec.ts}

@@ -1,7 +1,7 @@
 // https://nuxt.com/docs/getting-started/testing#unit-testing
 import type { VueWrapper } from "@vue/test-utils";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
-import ComponentUnderTest from "../InputRangeDefault.vue";
+import ComponentUnderTest from "../InputRangeField.vue";
 
 const initialPropsData = {
   name: "testName",
@@ -13,6 +13,11 @@ const initialPropsData = {
 };
 
 let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks();
+});
 const wrapperFactory = (propsData = {}, slots = {}) => {
   const mockPropsData = { ...initialPropsData, ...propsData };
 
@@ -23,7 +28,7 @@ const wrapperFactory = (propsData = {}, slots = {}) => {
   });
 };
 
-describe("InputRangeDefault", () => {
+describe("InputRangeField", () => {
   it("mounts without error", async () => {
     wrapper = await wrapperFactory();
     expect(wrapper.vm).toBeTruthy();
@@ -39,10 +44,10 @@ describe("InputRangeDefault", () => {
     expect(wrapper.find('input[type="range"]').exists()).toBe(true);
   });
 
-  it("sets data-invalid and the error class when fieldHasError is true", async () => {
+  it("sets data-invalid, not a bare error class, when fieldHasError is true", async () => {
     wrapper = await wrapperFactory({ fieldHasError: true });
-    expect(wrapper.find(".input-range-with-label").attributes("data-invalid")).toBe("");
-    expect(wrapper.find(".input-range-with-label").classes()).toContain("error");
+    expect(wrapper.find(".input-range-field").attributes("data-invalid")).toBe("");
+    expect(wrapper.find(".input-range-field").classes()).not.toContain("error");
   });
 
   it("does not render step buttons when the left/right slots are not used", async () => {
@@ -133,8 +138,67 @@ describe("InputRangeDefault", () => {
     expect(wrapper.text()).toContain("This field is required");
   });
 
-  it("applies styleClassPassthrough", async () => {
+  it("applies styleClassPassthrough to the root only, not the inner input", async () => {
     wrapper = await wrapperFactory({ styleClassPassthrough: "custom-range" });
-    expect(wrapper.find(".input-range-with-label").classes()).toContain("custom-range");
+    expect(wrapper.find(".input-range-field").classes()).toContain("custom-range");
+    expect(wrapper.find("input").classes()).not.toContain("custom-range");
+  });
+
+  it("uses its own label class, not the number field's", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".input-range-label").exists()).toBe(true);
+    expect(wrapper.find(".input-number-label").exists()).toBe(false);
+  });
+
+  it("forwards the markers slot", async () => {
+    wrapper = await wrapperFactory({}, { markers: '<div class="input-range-markers" data-testid="markers"></div>' });
+    expect(wrapper.find('[data-testid="markers"]').exists()).toBe(true);
+    expect(wrapper.find(".input-range-wrapper").attributes("data-has-markers")).toBe("");
+  });
+
+  it("forwards the datalist slot with its generated id", async () => {
+    wrapper = await wrapperFactory(
+      {},
+      { datalist: `<template #datalist="{ datalistId }"><datalist :id="datalistId"></datalist></template>` }
+    );
+    const list = wrapper.find("input").attributes("list");
+
+    expect(list).toBeTruthy();
+    expect(wrapper.find("datalist").attributes("id")).toBe(list);
+  });
+
+  describe("step buttons", () => {
+    const stepSlots = { left: "<span>-</span>", right: "<span>+</span>" };
+    const stepDown = () => wrapper.findAll("button").find((button) => button.text().includes("-"))!;
+    const stepUp = () => wrapper.findAll("button").find((button) => button.text().includes("+"))!;
+
+    it("rounds away floating-point drift on fractional steps", async () => {
+      wrapper = await wrapperFactory({ modelValue: 0.2, min: 0, max: 1, step: 0.1 }, stepSlots);
+      await stepUp().trigger("click");
+      expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([0.3]);
+    });
+
+    it("clamps to max when a step would overshoot it", async () => {
+      wrapper = await wrapperFactory({ modelValue: 98, min: 0, max: 100, step: 5 }, stepSlots);
+      await stepUp().trigger("click");
+      expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([100]);
+    });
+
+    it("clamps to min when a step would undershoot it", async () => {
+      wrapper = await wrapperFactory({ modelValue: 2, min: 0, max: 100, step: 5 }, stepSlots);
+      await stepDown().trigger("click");
+      expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([0]);
+    });
+
+    it("treats a negative or zero step as its size, or 1", async () => {
+      wrapper = await wrapperFactory({ modelValue: 50, step: -5 }, stepSlots);
+      await stepUp().trigger("click");
+      expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([55]);
+
+      wrapper.unmount();
+      wrapper = await wrapperFactory({ modelValue: 50, step: 0 }, stepSlots);
+      await stepUp().trigger("click");
+      expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([51]);
+    });
   });
 });

package/app/components/05.forms/input-select/CONSUMER-STYLING.md

@@ -1,4 +1,7 @@
-# InputSelectCore — Consumer Styling Guide
+# InputSelect — Consumer Styling Guide
+
+> **Renamed 2026-10-16**: `InputSelectCore` → `InputSelect`, `InputSelectWithLabel` →
+> `InputSelectField`. Class changes are listed under "State hooks" below.
 
 ## Public token API
 
@@ -7,23 +10,73 @@ to override just this component; leave it unset and it inherits the shared `--th
 `--theme-*` token every other themed component also falls back to. See
 `theming-component-token-pattern.md` for why this two-tier shape exists.
 
-(Before 2026-08-25 this component used a private `--_input-select-*` naming scheme presented as a
-"local override path" — that's gone. A private, underscore-prefixed custom property was never a
-real override point; renaming it public with a real fallback is the actual fix, not a second
-documented path to reach for.)
+### Control
 
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
 | `--input-select-surface` | `var(--theme-input-surface)` | Wrapper/select background |
-| `--input-select-surface-hover` | `var(--theme-input-surface-hover)` | Option row background on hover |
-| `--input-select-border` | `var(--theme-border)` | Border colour (`.normal`/`.underlined`/open picker, resting) |
+| `--input-select-text-color` | `var(--theme-input-text-color-normal)` | Select text colour (added 2026-10-16; it inherited the page colour before) |
+| `--input-select-border` | `var(--theme-border)` | Border colour (`normal`/`underlined` variants and the open picker, resting) |
 | `--input-select-border-hover` | `var(--theme-border-focus)` | Outline colour on hover (mouse) |
-| `--input-select-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (keyboard/assistive) |
+| `--input-select-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (keyboard/assistive), and the open picker's outline |
+
+### Options
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-select-surface-hover` | `var(--theme-input-surface-hover)` | Option row background on hover |
+| `--input-select-option-gap` | `1.5rem` | Gap between an option's icon and its label |
+| `--input-select-option-icon-size` | `1.5rem` | Option icon width and height |
 
 Geometry (`--input-padding-*`, `--input-min-height`, `--input-select-option-min-height`,
 `--form-element-*`, etc.) is shared across every `05.forms` component and untouched by this — see
 `theming-form-geometry-tokens.md`.
 
+Private (not public API): `--_border` and `--_border-focus`, each resolved once and read in several
+places.
+
+Option rows (`--input-select-surface-hover`, the gap and the icon) and the open picker's border are
+only styled where the browser supports `appearance: base-select`. Elsewhere the native dropdown
+shows and ignores them.
+
+---
+
+## State hooks
+
+| Attribute | On | When |
+|---|---|---|
+| `data-input-variant="normal" \| "outlined" \| "underlined"` | `.input-select-wrapper`, `.input-select-field` | Always, mirrors `input-variant` |
+| `data-theme` | `.input-select-wrapper`, `.input-select-field` | Always. The Field's own is the `theme` prop; the inner wrapper's switches to `error` while `field-has-error` is set |
+| `data-invalid` | `.input-select-wrapper`, `.input-select-field` | `field-has-error` |
+| `data-dirty` | `.input-select-wrapper` | The value has changed (the `is-dirty` model) |
+| `data-active` | `.input-select-wrapper` | The select has focus (the `is-active` model) |
+
+Inner elements: `.input-select` (the native select), `.input-select-option` (each option),
+`.input-select-option-placeholder` (the placeholder option), `.input-select-option-icon`,
+`.input-select-label` (the Field's `InputLabel`), `.input-text-description` (the Field's
+`InputDescription`, shared with the other Field components).
+
+`outlined` has no CSS of its own: the control renders with no border or outline. In the Field it
+moves the description after the control and error.
+
+> **Changed 2026-10-16**: state used to be bare classes, which collide with common consumer CSS
+> (an unlayered `.error` or `.normal` rule would restyle the field). Select on the attributes
+> above instead:
+>
+> - `.input-select-wrapper.normal` / `.underlined` / `.outlined` → `[data-input-variant="…"]`
+> - `.input-select-wrapper.dirty` / `.active` / `.error` → `[data-dirty]` / `[data-active]` /
+>   `[data-invalid]`
+> - `.input-select-core` → `.input-select`; `.input-select-core-option` → `.input-select-option`;
+>   `option.placeholder` → `.input-select-option-placeholder`;
+>   `.input-select-core-option-decorator-icon` → `.input-select-option-icon`
+> - `.input-select-with-label` → `.input-select-field`, which is now the root (it used to sit
+>   inside an unclassed `<div>`); its `.error`, variant, `dirty` and `active` classes are gone, use
+>   `[data-invalid]` / `[data-input-variant]`, or the inner wrapper's attributes
+> - the Field's default `data-testid` is `input-select-field` (was `input-select-with-label`)
+>
+> Also: long label, description and error copy now wraps (`overflow-wrap: anywhere` on
+> `.input-select-field`), and long option labels wrap in the open picker.
+
 ---
 
 ## Global theming
@@ -52,6 +105,23 @@ Set the tokens above on an element you own (a page or section class, or a class
 ### One instance
 
 ```vue
-<InputSelectCore id="country" name="country" style="--input-select-border-focus: var(--gold-04);" />
+<InputSelectField
+  v-model="country"
+  v-model:field-data="countries"
+  name="country"
+  label="Country"
+  :error-message="errors.country"
+  style="--input-select-border-focus: var(--gold-04);"
+/>
 ```
 
+---
+
+## Class passthrough
+
+`InputSelect`'s `:style-class-passthrough` lands on the native `<select class="input-select">`.
+`InputSelectField`'s lands on its root `.input-select-field` only.
+
+> **Changed 2026-10-16**: `InputSelectWithLabel` forwarded its passthrough classes to the inner
+> select instead of its own root. If you styled the select through the Field's passthrough, select
+> `.your-class .input-select` instead.

package/app/components/05.forms/input-select/InputSelect.vue

@@ -0,0 +1,198 @@
+<template>
+  <div
+    class="input-select-wrapper"
+    :data-theme="theme"
+    :data-input-variant="inputVariant"
+    :data-invalid="fieldHasError ? '' : null"
+    :data-dirty="isDirty ? '' : null"
+    :data-active="isActive ? '' : null"
+  >
+    <select
+      :id
+      v-model="modelValue"
+      :aria-invalid="fieldHasError ? 'true' : undefined"
+      :class="['input-select', elementClasses]"
+      :name
+      :title
+      :required
+      :aria-describedby="ariaDescribedby || undefined"
+      @focusin="isActive = true"
+      @focusout="isActive = false"
+      @change="isDirty = true"
+    >
+      <option
+        v-if="placeholder"
+        value=""
+        disabled
+        :selected="isEmpty"
+        class="input-select-option input-select-option-placeholder"
+      >
+        {{ placeholder }}
+      </option>
+      <option
+        v-for="item in fieldData.data"
+        :key="item.id"
+        :value="item.value"
+        :selected="String(item.value) === String(modelValue)"
+        class="input-select-option"
+      >
+        <Icon
+          v-if="item.icon"
+          :name="item.icon"
+          class="input-select-option-icon"
+          aria-hidden="true"
+          focusable="false"
+        />
+        {{ item.label }}
+      </option>
+    </select>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { IFormMultipleOptions, FormUiTheme, InputUiVariant } from "~/types/forms/types.forms";
+
+interface Props {
+  id: string;
+  name: string;
+  placeholder?: string;
+  title?: string;
+  required?: boolean;
+  fieldHasError?: boolean;
+  styleClassPassthrough?: string | string[];
+  theme?: FormUiTheme;
+  inputVariant?: InputUiVariant;
+  ariaDescribedby?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  placeholder: "",
+  title: "Please select an option",
+  required: false,
+  fieldHasError: false,
+  styleClassPassthrough: () => [],
+  theme: "default",
+  inputVariant: "normal",
+  ariaDescribedby: "",
+});
+
+const modelValue = defineModel<string | number | readonly number[]>({ required: true });
+const isDirty = defineModel<boolean>("isDirty");
+const isActive = defineModel<boolean>("isActive");
+const fieldData = defineModel<IFormMultipleOptions>("fieldData", { required: true });
+
+const isEmpty = computed(() => modelValue.value === "" || modelValue.value == null);
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .input-select-wrapper {
+    --_border: var(--input-select-border, var(--theme-border));
+    --_border-focus: var(--input-select-border-focus, var(--theme-border-focus));
+
+    min-inline-size: 0;
+    max-inline-size: 100%;
+    background-color: var(--input-select-surface, var(--theme-input-surface));
+    overflow: hidden;
+
+    z-index: 2;
+    position: relative;
+    transition: all var(--theme-form-transition-duration) ease-in-out;
+
+    &[data-input-variant="normal"] {
+      border: var(--form-element-border-width) solid var(--_border);
+      border-radius: var(--form-input-border-radius);
+      outline: var(--form-element-outline-width) solid transparent;
+    }
+
+    &[data-input-variant="underlined"] {
+      border-bottom: var(--form-element-border-bottom-width-underlined) solid var(--_border);
+    }
+
+    &:has(:hover) {
+      outline: var(--form-element-outline-width-focus) solid
+        var(--input-select-border-hover, var(--theme-border-focus));
+      outline-offset: var(--form-element-outline-offset-focus);
+    }
+
+    &:has(select:focus-visible) {
+      outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
+      outline-offset: var(--form-element-outline-offset-focus);
+    }
+
+    .input-select {
+      appearance: none;
+      background-color: transparent;
+      color: var(--input-select-text-color, var(--theme-input-text-color-normal));
+      display: flex;
+      align-items: center;
+
+      &,
+      &::picker(select) {
+        appearance: base-select;
+      }
+
+      &::picker(select) {
+        transition:
+          display allow-discrete var(--theme-form-transition-duration),
+          opacity var(--theme-form-transition-duration),
+          overlay var(--theme-form-transition-duration) allow-discrete;
+      }
+
+      &:not(:open)::picker(select) {
+        opacity: 0;
+      }
+
+      &:open::picker(select) {
+        opacity: 1;
+        border: var(--form-element-border-width) solid var(--_border);
+        outline: var(--form-element-outline-width) solid var(--_border-focus);
+
+        @starting-style {
+          opacity: 0;
+        }
+      }
+
+      border: none;
+      outline: none;
+      border-radius: 0;
+      width: 100%;
+      min-inline-size: 0;
+
+      font-family: var(--font-family);
+      font-size: var(--input-font-size);
+      padding-block: var(--input-padding-block);
+      padding-inline: var(--input-padding-inline);
+      min-height: var(--input-min-height);
+
+      .input-select-option {
+        min-height: var(--input-select-option-min-height);
+        gap: var(--input-select-option-gap, 1.5rem);
+        overflow-wrap: anywhere;
+        white-space: normal;
+        transition: all var(--theme-form-transition-duration) ease-in-out;
+
+        &:hover {
+          background-color: var(--input-select-surface-hover, var(--theme-input-surface-hover));
+        }
+
+        .input-select-option-icon {
+          display: inline-block;
+          flex-shrink: 0;
+          width: var(--input-select-option-icon-size, 1.5rem);
+          height: var(--input-select-option-icon-size, 1.5rem);
+        }
+      }
+    }
+  }
+}
+</style>

package/app/components/05.forms/input-select/InputSelectField.vue

@@ -0,0 +1,130 @@
+<template>
+  <div
+    class="input-select-field"
+    :class="elementClasses"
+    :data-testid
+    :data-theme="theme"
+    :data-input-variant="inputVariant"
+    :data-invalid="fieldHasError ? '' : null"
+  >
+    <InputLabel
+      :id
+      :required
+      :input-variant
+      :field-has-error
+      :style-class-passthrough="['input-select-label']"
+    >
+      <template #textLabel>{{ label }}</template>
+    </InputLabel>
+
+    <InputDescription
+      v-if="inputVariant !== 'outlined'"
+      :description-id
+      :input-variant
+      :field-has-error="fieldHasError"
+      :style-class-passthrough="['input-text-description']"
+    >
+      <template v-if="slots.descriptionHtml" #descriptionHtml>
+        <slot name="descriptionHtml"></slot>
+      </template>
+      <template v-if="slots.descriptionText" #descriptionText>
+        <slot name="descriptionText"></slot>
+      </template>
+    </InputDescription>
+
+    <InputSelect
+      :id
+      v-model="modelValue"
+      v-model:field-data="fieldData"
+      v-model:is-dirty="isDirty"
+      v-model:is-active="isActive"
+      :name
+      :placeholder
+      :title
+      :field-has-error
+      :required
+      :theme="selectTheme"
+      :aria-describedby="ariaDescribedby()"
+      :input-variant
+    />
+
+    <InputError :id="errorId" :error-message :show-error="fieldHasError" :is-detached="false" :input-variant />
+
+    <InputDescription
+      v-if="inputVariant === 'outlined'"
+      :description-id
+      :input-variant
+      :field-has-error="fieldHasError"
+      :style-class-passthrough="['input-text-description']"
+    >
+      <template v-if="slots.descriptionHtml" #descriptionHtml>
+        <slot name="descriptionHtml"></slot>
+      </template>
+      <template v-if="slots.descriptionText" #descriptionText>
+        <slot name="descriptionText"></slot>
+      </template>
+    </InputDescription>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { FormUiTheme, InputUiVariant, IFormMultipleOptions } from "~/types/forms/types.forms";
+
+interface Props {
+  dataTestid?: string;
+  name: string;
+  label: string;
+  placeholder?: string;
+  title?: string;
+  errorMessage: object | string;
+  required?: boolean;
+  fieldHasError?: boolean;
+  styleClassPassthrough?: string | string[];
+  theme?: FormUiTheme;
+  inputVariant?: InputUiVariant;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  dataTestid: "input-select-field",
+  placeholder: "",
+  title: "Please select an option",
+  required: false,
+  fieldHasError: false,
+  styleClassPassthrough: () => [],
+  theme: "default",
+  inputVariant: "normal",
+});
+
+const slots = useSlots();
+
+const selectTheme = computed(() => (props.fieldHasError ? "error" : props.theme));
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+
+const { id, errorId, descriptionId, ariaDescribedby } = useAriaDescribedById(
+  props.name,
+  toRef(props, "fieldHasError"),
+  slots
+);
+
+const modelValue = defineModel<string | number | readonly number[]>({ required: true });
+const isDirty = defineModel<boolean>("isDirty");
+const isActive = defineModel<boolean>("isActive");
+const fieldData = defineModel<IFormMultipleOptions>("fieldData", { required: true });
+</script>
+
+<style lang="css">
+@layer components {
+  .input-select-field {
+    min-inline-size: 0;
+    overflow-wrap: anywhere;
+  }
+}
+</style>