srcdev-nuxt-components 9.6.7 → 9.6.9

package/app/components/05.forms/input-text/tests/InputTextAsNumberField.spec.ts

@@ -0,0 +1,135 @@
+// https://nuxt.com/docs/getting-started/testing#unit-testing
+import { nextTick } from "vue";
+import type { VueWrapper } from "@vue/test-utils";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentUnderTest from "../InputTextAsNumberField.vue";
+
+const initialPropsData = {
+  name: "quantity",
+  label: "Quantity",
+  errorMessage: "",
+  min: 0,
+  max: 10,
+};
+
+let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+const wrapperFactory = (propsData = {}) => {
+  const mockPropsData = { ...initialPropsData, ...propsData };
+
+  return mountSuspended(ComponentUnderTest, {
+    attachTo: document.body,
+    props: mockPropsData,
+    slots: {
+      left: () => "−",
+      right: () => "+",
+    },
+  });
+};
+
+const stepButtons = () => {
+  const [stepDown, stepUp] = wrapper.findAll("button");
+  return { stepDown: stepDown!, stepUp: stepUp! };
+};
+
+const lastEmitted = () => wrapper.emitted("update:modelValue")?.at(-1);
+
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks();
+});
+
+describe("InputTextAsNumberField", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders .input-text-as-number-field as the root", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.classes()).toContain("input-text-as-number-field");
+  });
+
+  it("uses the default step button text", async () => {
+    wrapper = await wrapperFactory();
+
+    expect(stepButtons().stepDown.text()).toContain("Step down");
+    expect(stepButtons().stepUp.text()).toContain("Step up");
+  });
+
+  it("uses custom stepDownText/stepUpText when provided", async () => {
+    wrapper = await wrapperFactory({ stepDownText: "Diminuer", stepUpText: "Augmenter" });
+
+    expect(stepButtons().stepDown.text()).toContain("Diminuer");
+    expect(stepButtons().stepUp.text()).toContain("Augmenter");
+  });
+
+  it("increments the value when the step-up button is clicked", async () => {
+    wrapper = await wrapperFactory({ modelValue: 5 });
+    await stepButtons().stepUp.trigger("click");
+    expect(lastEmitted()).toEqual([6]);
+  });
+
+  it("rounds fractional steps instead of drifting", async () => {
+    wrapper = await wrapperFactory({ modelValue: 0.2, max: 1, step: 0.1 });
+    await stepButtons().stepUp.trigger("click");
+    expect(lastEmitted()).toEqual([0.3]);
+  });
+
+  it("clamps to max instead of overshooting", async () => {
+    wrapper = await wrapperFactory({ modelValue: 8, step: 5 });
+    await stepButtons().stepUp.trigger("click");
+    expect(lastEmitted()).toEqual([10]);
+  });
+
+  it("pulls a typed out-of-range value back into range", async () => {
+    wrapper = await wrapperFactory({ modelValue: 50 });
+    await stepButtons().stepDown.trigger("click");
+    expect(lastEmitted()).toEqual([10]);
+  });
+
+  it("starts from 0, clamped, when the field is empty", async () => {
+    wrapper = await wrapperFactory({ modelValue: undefined, min: 3 });
+    await stepButtons().stepUp.trigger("click");
+    expect(lastEmitted()).toEqual([3]);
+  });
+
+  it("makes the step buttons read-only at and beyond the limits", async () => {
+    wrapper = await wrapperFactory({ modelValue: 12 });
+    expect(stepButtons().stepUp.attributes("readonly")).toBeDefined();
+
+    await wrapper.setProps({ modelValue: 0 });
+    expect(stepButtons().stepDown.attributes("readonly")).toBeDefined();
+  });
+
+  it("parses typed text into a number and empties to undefined", async () => {
+    wrapper = await wrapperFactory({ modelValue: 1 });
+    const input = wrapper.find("input");
+
+    await input.setValue("7");
+    expect(lastEmitted()).toEqual([7]);
+
+    await input.setValue("");
+    expect(lastEmitted()).toEqual([undefined]);
+  });
+
+  it("picks inputmode from min and step", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("input").attributes("inputmode")).toBe("numeric");
+
+    await wrapper.setProps({ step: 0.5 });
+    expect(wrapper.find("input").attributes("inputmode")).toBe("decimal");
+
+    await wrapper.setProps({ min: -5 });
+    expect(wrapper.find("input").attributes("inputmode")).toBe("text");
+  });
+
+  it("applies styleClassPassthrough to its root only and reacts to changes", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: ["custom-number-class"] });
+    expect(wrapper.classes()).toContain("custom-number-class");
+    expect(wrapper.find("input").classes()).not.toContain("custom-number-class");
+
+    await wrapper.setProps({ styleClassPassthrough: ["other-class"] });
+    await nextTick();
+    expect(wrapper.classes()).toContain("other-class");
+  });
+});

package/app/components/05.forms/input-text/tests/InputTextField.spec.ts

@@ -0,0 +1,130 @@
+// https://nuxt.com/docs/getting-started/testing#unit-testing
+import { defineComponent, nextTick, ref } from "vue";
+import type { VueWrapper } from "@vue/test-utils";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentUnderTest from "../InputTextField.vue";
+
+const initialPropsData = {
+  type: "text" as const,
+  name: "testName",
+  label: "Test label",
+  errorMessage: "",
+  modelValue: "",
+};
+
+let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+const wrapperFactory = (propsData = {}, slots = {}) => {
+  const mockPropsData = { ...initialPropsData, ...propsData };
+
+  return mountSuspended(ComponentUnderTest, {
+    attachTo: document.body,
+    props: mockPropsData,
+    slots,
+  });
+};
+
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks();
+});
+
+describe("InputTextField", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders .input-text-field as the root", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.classes()).toContain("input-text-field");
+  });
+
+  it("renders the label text, linked to the input", async () => {
+    wrapper = await wrapperFactory({ label: "Email address" });
+    const label = wrapper.find("label");
+
+    expect(label.text()).toContain("Email address");
+    expect(label.attributes("for")).toBe(wrapper.find("input").attributes("id"));
+  });
+
+  it("does not leak label or error-message onto the control as attributes", async () => {
+    wrapper = await wrapperFactory({ errorMessage: "Oops" });
+    const control = wrapper.find(".input-text-wrapper");
+
+    expect(control.attributes("label")).toBeUndefined();
+    expect(control.attributes("error-message")).toBeUndefined();
+  });
+
+  it("forwards min/max through to the input (e.g. for type=date)", async () => {
+    wrapper = await wrapperFactory({ type: "date", min: "2026-01-01", max: "2026-12-31" });
+    const input = wrapper.find("input");
+
+    expect(input.attributes("type")).toBe("date");
+    expect(input.attributes("min")).toBe("2026-01-01");
+    expect(input.attributes("max")).toBe("2026-12-31");
+  });
+
+  it("forwards readonly and autocomplete to the input", async () => {
+    wrapper = await wrapperFactory({ readonly: true, autocomplete: "email" });
+    expect(wrapper.find("input").attributes("readonly")).toBeDefined();
+    expect(wrapper.find("input").attributes("autocomplete")).toBe("email");
+  });
+
+  it("sets data-invalid on the root and links the error via aria-describedby", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "Please enter an email" });
+
+    expect(wrapper.attributes("data-invalid")).toBe("");
+    expect(wrapper.text()).toContain("Please enter an email");
+    expect(wrapper.find("input").attributes("aria-describedby")).toMatch(/-error-message$/);
+  });
+
+  it("marks the field dirty once it has a value", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.attributes("data-dirty")).toBeUndefined();
+
+    await wrapper.setProps({ modelValue: "x" });
+    await nextTick();
+    expect(wrapper.attributes("data-dirty")).toBe("");
+  });
+
+  it("renders the description after the input for the outlined variant", async () => {
+    wrapper = await wrapperFactory({ inputVariant: "outlined" }, { descriptionText: () => "Hint text" });
+    const html = wrapper.html();
+    expect(html.indexOf("Hint text")).toBeGreaterThan(html.indexOf("<input"));
+  });
+
+  it("applies styleClassPassthrough to its root only and reacts to changes", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: "first-class" });
+    expect(wrapper.classes()).toContain("first-class");
+    expect(wrapper.find("input").classes()).not.toContain("first-class");
+
+    await wrapper.setProps({ styleClassPassthrough: "second-class" });
+    await nextTick();
+    expect(wrapper.classes()).toContain("second-class");
+    expect(wrapper.classes()).not.toContain("first-class");
+  });
+
+  it("points aria-describedby at the description once it appears after mount", async () => {
+    const Host = defineComponent({
+      components: { ComponentUnderTest },
+      setup() {
+        return { modelValue: ref(""), showDescription: ref(false) };
+      },
+      template: `
+        <ComponentUnderTest v-model="modelValue" type="text" name="email" label="Email" error-message="">
+          <template v-if="showDescription" #descriptionText>We never share it.</template>
+        </ComponentUnderTest>
+      `,
+    });
+    const host = await mountSuspended(Host);
+    const input = () => host.find("input");
+    expect(input().attributes("aria-describedby")).toBeFalsy();
+    (host.vm as unknown as { showDescription: boolean }).showDescription = true;
+    await nextTick();
+    expect(input().attributes("aria-describedby")).toMatch(/-description$/);
+    (host.vm as unknown as { showDescription: boolean }).showDescription = false;
+    await nextTick();
+    expect(input().attributes("aria-describedby")).toBeFalsy();
+    host.unmount();
+  });
+});

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

@@ -1,4 +1,7 @@
-# InputTextareaCore — Consumer Styling Guide
+# InputTextarea — Consumer Styling Guide
+
+> **Renamed 2026-10-16**: `InputTextareaCore` → `InputTextarea`, `InputTextareaWithLabel` →
+> `InputTextareaField`. Class changes are listed under "State hooks" below.
 
 ## Public token API
 
@@ -7,30 +10,73 @@ name to override just this component; leave it unset and it inherits the shared
 `--theme-*` token every other themed component also falls back to. See
 `theming-component-token-pattern.md` for why this two-tier shape exists.
 
-This shape mirrors `InputTextCore`'s token set (see its own CONSUMER-STYLING.md).
+This shape mirrors `InputText`'s token set (see its own CONSUMER-STYLING.md).
+
+### Colour
 
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
 | `--input-textarea-surface` | `var(--theme-input-surface)` | Wrapper background |
 | `--input-textarea-border` | `var(--theme-border)` | Border colour (`normal`/`underlined` variant border) |
-| `--input-textarea-border-hover` | `var(--theme-border-focus)` | Wrapper outline colour on mouse hover (`normal` variant only) |
-| `--input-textarea-border-focus` | `var(--theme-border-focus)` | Wrapper outline colour on `:focus-visible` (`normal` variant only) |
+| `--input-textarea-border-hover` | `var(--theme-border-focus)` | Wrapper outline colour on mouse hover (`normal` only) |
+| `--input-textarea-border-focus` | `var(--theme-border-focus)` | Wrapper outline colour on `:focus-visible` (`normal` only) |
 | `--input-textarea-text-color` | `var(--theme-input-text-color-normal)` | Textarea text colour |
 | `--input-textarea-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |
 
+### Size
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-textarea-min-height` | `6lh` | Minimum height (six lines) |
+| `--input-textarea-max-height` | `none` | Maximum height before the textarea scrolls. It grows with its content up to here where `field-sizing: content` is supported |
+| `--input-textarea-slot-gap` | `1.2rem` | Gap between the left/right slots and the textarea |
+| `--input-textarea-slot-align` | `center` | Vertical position of the left/right slots against the textarea (`align-self`: `start`, `center`, `end`) |
+| `--input-textarea-slot-padding-block` | `0` | Space above and below each slot, so a `start`- or `end`-aligned slot doesn't sit against the field's edge |
+
 Geometry (`--form-textarea-padding-block`, `--form-textarea-padding-inline`, `--input-font-size`,
 `--input-textarea-line-height`, `--input-padding-inline`, etc.) is shared across every `05.forms`
 component and untouched by this — see `theming-form-geometry-tokens.md`.
 
+Private (not public API): `--_border`, resolved once and read by both border variants.
+
 ---
 
-## Input variant
+## State hooks
 
-`:input-variant="'normal' | 'outlined' | 'underlined'"` (default `"normal"`) — same prop as
-`InputTextCore`. Only `normal` (bordered box, with hover/focus outline) and `underlined`
-(bottom-border only) have CSS today; `outlined` has no styling in `InputTextCore` either (no
-`&.outlined` rule exists there), so passing it renders with no border/outline at all — a
-pre-existing gap in the type, not specific to `InputTextareaCore`.
+| Attribute | On | When |
+|---|---|---|
+| `data-input-variant="normal" \| "outlined" \| "underlined"` | `.input-textarea-wrapper`, `.input-textarea-field` | Always, mirrors `input-variant` |
+| `data-theme` | `.input-textarea-wrapper`, `.input-textarea-field` | Always, mirrors `theme` |
+| `data-invalid` | `.input-textarea-wrapper`, `.input-textarea-field` | `field-has-error` |
+| `data-dirty` | `.input-textarea-wrapper`, `.input-textarea-field` | The Field has seen a non-empty value |
+| `data-active` | `.input-textarea-wrapper`, `.input-textarea-field` | The textarea has focus |
+| `data-has-left-slot` / `data-has-right-slot` | `.input-textarea-wrapper` | The `left` / `right` slot is filled |
+
+Inner elements: `.input-textarea` (the native textarea), `.input-textarea-slot` (both slot
+holders), `.input-textarea-slot-left`, `.input-textarea-slot-right`, `.input-textarea-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-textarea-wrapper.normal` / `.underlined` / `.outlined` → `[data-input-variant="…"]`
+> - `.input-textarea-wrapper.dirty` / `.active` / `.error` → `[data-dirty]` / `[data-active]` /
+>   `[data-invalid]`; `.has-left-slot` / `.has-right-slot` → `[data-has-left-slot]` /
+>   `[data-has-right-slot]`
+> - `.slot.left-slot` / `.slot.right-slot` → `.input-textarea-slot-left` /
+>   `.input-textarea-slot-right`
+> - `.input-textarea-core` → `.input-textarea` (no longer carries `dirty`/`active` classes)
+> - `.input-textarea-with-label` → `.input-textarea-field`, now the Field's root (it used to sit
+>   inside an unclassed `<div>`); its variant/`dirty`/`active` classes → the attributes above
+>
+> Also: the textarea keeps typed line breaks and wraps long unbroken strings (`white-space:
+> pre-wrap`, `overflow-wrap: anywhere`), and the Field wraps long label, description and error
+> copy.
 
 ---
 
@@ -40,6 +86,7 @@ pre-existing gap in the type, not specific to `InputTextareaCore`.
 :where(html) {
   --input-textarea-surface: var(--rose-09);
   --input-textarea-border: var(--rose-05);
+  --input-textarea-max-height: 20lh;
 }
 ```
 
@@ -48,6 +95,20 @@ Only declare the tokens you want to change — everything else keeps inheriting
 
 ---
 
+## Recipe: slot icon on the first line
+
+Top-align the slots and pad them by the textarea's own block padding, so an icon lines up with the
+first line of text instead of the middle of a tall field:
+
+```css
+.contact-form {
+  --input-textarea-slot-align: start;
+  --input-textarea-slot-padding-block: var(--form-textarea-padding-block);
+}
+```
+
+---
+
 ## Local overrides
 
 Set the tokens above on an element you own (a page or section class, or a class added with
@@ -56,9 +117,30 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
 `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
 
+**Caveat**: `InputTextarea`'s own passthrough lands on the `<textarea>`, which has no descendants,
+so tokens set through it only reach the textarea itself (text, placeholder colour and the height
+tokens). Set the others on the Field root or an ancestor.
+
 ### One instance
 
 ```vue
-<InputTextareaCore id="message" name="message" style="--input-textarea-border: var(--gold-04);" />
+<InputTextareaField
+  v-model="message"
+  name="message"
+  label="Message"
+  error-message=""
+  style="--input-textarea-border: var(--gold-04);"
+/>
 ```
 
+---
+
+## Class passthrough
+
+`InputTextarea`'s `:style-class-passthrough` lands on the native
+`<textarea class="input-textarea">`. `InputTextareaField`'s lands on its root
+`.input-textarea-field` only.
+
+> **Changed 2026-10-16**: `InputTextareaWithLabel` applied its passthrough classes to both its
+> root and the inner textarea. If you styled the textarea that way, select
+> `.your-class .input-textarea` instead.

package/app/components/05.forms/input-textarea/InputTextarea.vue

@@ -0,0 +1,165 @@
+<template>
+  <div
+    class="input-textarea-wrapper"
+    :data-theme="theme"
+    :data-input-variant="inputVariant"
+    :data-invalid="fieldHasError ? '' : null"
+    :data-dirty="isDirty ? '' : null"
+    :data-active="isActive ? '' : null"
+    :data-has-left-slot="slots.left ? '' : null"
+    :data-has-right-slot="slots.right ? '' : null"
+  >
+    <span v-if="slots.left" class="input-textarea-slot input-textarea-slot-left">
+      <slot name="left"></slot>
+    </span>
+
+    <textarea
+      :id
+      v-model="modelValue"
+      :maxlength
+      :placeholder
+      :name
+      :required
+      :readonly
+      :autocomplete
+      :class="['input-textarea', elementClasses]"
+      :aria-invalid="fieldHasError ? 'true' : undefined"
+      :aria-describedby="ariaDescribedby || undefined"
+      @focusin="isActive = true"
+      @focusout="isActive = false"
+    ></textarea>
+
+    <span v-if="slots.right" class="input-textarea-slot input-textarea-slot-right">
+      <slot name="right"></slot>
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { FormUiTheme, InputUiVariant } from "~/types/forms/types.forms";
+
+interface Props {
+  maxlength?: number;
+  id: string;
+  name: string;
+  placeholder?: string;
+  ariaDescribedby?: string;
+  fieldHasError?: boolean;
+  required?: boolean;
+  readonly?: boolean;
+  autocomplete?: string;
+  styleClassPassthrough?: string | string[];
+  theme?: FormUiTheme;
+  inputVariant?: InputUiVariant;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  maxlength: 255,
+  placeholder: "",
+  ariaDescribedby: "",
+  fieldHasError: false,
+  required: false,
+  readonly: false,
+  autocomplete: undefined,
+  styleClassPassthrough: () => [],
+  theme: "default",
+  inputVariant: "normal",
+});
+
+const slots = useSlots();
+
+const modelValue = defineModel<string | number | readonly string[] | null | undefined>({
+  required: true,
+});
+const isDirty = defineModel<boolean>("isDirty");
+const isActive = defineModel<boolean>("isActive");
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .input-textarea-wrapper {
+    --_border: var(--input-textarea-border, var(--theme-border));
+
+    display: flex;
+    align-items: center;
+    gap: var(--input-textarea-slot-gap, 1.2rem);
+    min-inline-size: 0;
+    max-inline-size: 100%;
+    background-color: var(--input-textarea-surface, var(--theme-input-surface));
+    padding-inline: var(--input-padding-inline);
+    transition: all var(--theme-form-transition-duration) ease-in-out;
+
+    z-index: 2;
+    position: relative;
+
+    &[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;
+
+      &:has(textarea:is(:hover)) {
+        outline: var(--form-element-outline-width-focus) solid
+          var(--input-textarea-border-hover, var(--theme-border-focus));
+        outline-offset: var(--form-element-outline-offset-focus);
+      }
+
+      &:has(textarea:focus-visible) {
+        outline: var(--form-element-outline-width-focus) solid
+          var(--input-textarea-border-focus, var(--theme-border-focus));
+        outline-offset: var(--form-element-outline-offset-focus);
+      }
+    }
+
+    &[data-input-variant="underlined"] {
+      border-bottom: var(--form-element-border-bottom-width-underlined) solid var(--_border);
+    }
+
+    .input-textarea-slot {
+      display: flex;
+      flex-shrink: 0;
+      align-self: var(--input-textarea-slot-align, center);
+      padding-block: var(--input-textarea-slot-padding-block, 0);
+      place-items: center;
+      background-clip: padding-box;
+    }
+
+    .input-textarea {
+      all: unset;
+      touch-action: manipulation;
+      flex-grow: 1;
+      min-inline-size: 0;
+      field-sizing: content;
+      white-space: pre-wrap;
+      overflow-wrap: anywhere;
+      overflow-y: auto;
+
+      color: var(--input-textarea-text-color, var(--theme-input-text-color-normal));
+      font-family: var(--font-family);
+      font-size: var(--input-font-size);
+      line-height: var(--input-textarea-line-height);
+      padding-block: var(--form-textarea-padding-block);
+      padding-inline: var(--form-textarea-padding-inline);
+
+      min-height: var(--input-textarea-min-height, 6lh);
+      max-block-size: var(--input-textarea-max-height, none);
+
+      &::placeholder {
+        color: var(--input-textarea-placeholder-color, var(--theme-input-placeholder));
+        font-size: var(--theme-input-placeholder-font-size);
+        font-style: italic;
+        line-height: 1;
+        font-weight: normal;
+      }
+    }
+  }
+}
+</style>