srcdev-nuxt-components 9.6.8 → 9.6.9

package/app/components/05.forms/input-select/stories/InputSelectField.stories.ts

@@ -0,0 +1,187 @@
+import { computed, ref } from "vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import InputSelectField from "../InputSelectField.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
+import type { FormUiTheme, InputUiVariant, IFormMultipleOptions, IOptionsConfig } from "~/types/forms/types.forms.d";
+import type { MediaCanvas } from "~/types/components";
+
+interface StoryArgs {
+  modelValue: string | number;
+  name: string;
+  label: string;
+  placeholder: string;
+  title: string;
+  errorMessage: string;
+  fieldHasError: boolean;
+  required: boolean;
+  theme: FormUiTheme;
+  inputVariant: InputUiVariant;
+  styleClassPassthrough: string[];
+  descriptionText: string;
+  options: IOptionsConfig[];
+}
+
+const colourOptions: IOptionsConfig[] = [
+  { id: "1", name: "red", value: "red", label: "Red" },
+  { id: "2", name: "blue", value: "blue", label: "Blue" },
+  { id: "3", name: "green", value: "green", label: "Green" },
+];
+
+const meta: Meta<StoryArgs> = {
+  title: "Components/Forms/Input Select/InputSelectField",
+  component: InputSelectField,
+  argTypes: {
+    modelValue: { control: "text", table: { category: "Model" } },
+    name: { control: "text", table: { category: "Basic" } },
+    label: { control: "text", table: { category: "Basic" } },
+    placeholder: { control: "text", table: { category: "Basic" } },
+    title: { control: "text", description: "Native tooltip; pass translated copy", table: { category: "Accessibility" } },
+    errorMessage: { control: "text", table: { category: "Validation" } },
+    fieldHasError: { control: "boolean", table: { category: "Validation" } },
+    required: { control: "boolean", table: { category: "Validation" } },
+    theme: {
+      control: { type: "select" },
+      options: ["default", "success", "error", "warning"],
+      table: { category: "Styling" },
+    },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      table: { category: "Styling" },
+    },
+    styleClassPassthrough: { control: "object", table: { category: "Styling" } },
+    descriptionText: {
+      control: "text",
+      description: "Story-only: fills the descriptionText slot",
+      table: { category: "Slots" },
+    },
+    options: {
+      control: "object",
+      description: "Story-only: the `data` array of `v-model:field-data`",
+      table: { category: "Model" },
+    },
+  },
+  args: {
+    modelValue: "",
+    name: "colour",
+    label: "Favourite colour",
+    placeholder: "Choose a colour",
+    title: "Please select an option",
+    errorMessage: "",
+    fieldHasError: false,
+    required: false,
+    theme: "default",
+    inputVariant: "normal",
+    styleClassPassthrough: [],
+    descriptionText: "",
+    options: colourOptions,
+  },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; padding: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Labelled select field: `InputLabel`, an optional description (`descriptionText`/`descriptionHtml` slots, moved after the control for the `outlined` variant), `InputSelect` and an error strip linked through `aria-describedby`. `field-has-error` switches the control to the `error` theme. `style-class-passthrough` lands on the `.input-select-field` root only.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StoryArgs>;
+
+const render = (args: StoryArgs) => ({
+  components: { InputSelectField },
+  setup() {
+    const fieldData = computed<IFormMultipleOptions>(() => ({
+      data: args.options,
+      total: args.options.length,
+      skip: 0,
+      limit: args.options.length,
+    }));
+    const componentArgs = computed(() => {
+      const { modelValue: _modelValue, descriptionText: _descriptionText, options: _options, ...rest } = args;
+      return rest;
+    });
+    return { args, componentArgs, fieldData };
+  },
+  template: `
+    <InputSelectField v-model="args.modelValue" :field-data="fieldData" v-bind="componentArgs">
+      <template v-if="args.descriptionText" #descriptionText>{{ args.descriptionText }}</template>
+    </InputSelectField>
+    <p style="margin-block-start: 1.6rem; font-family: monospace;">modelValue: {{ JSON.stringify(args.modelValue) }}</p>
+  `,
+});
+
+export const Default: Story = { render };
+
+export const WithError: Story = {
+  args: { fieldHasError: true, errorMessage: "Please choose a colour" },
+  render,
+};
+
+export const Required: Story = { args: { required: true }, render };
+
+export const WithDescription: Story = { args: { descriptionText: "Pick the colour you like best" }, render };
+
+export const Underlined: Story = { args: { inputVariant: "underlined" }, render };
+
+export const Outlined: Story = {
+  args: { inputVariant: "outlined", descriptionText: "Pick the colour you like best" },
+  render,
+  parameters: { docs: { description: { story: "The `outlined` variant renders the description after the control and error." } } },
+};
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    modelValue: "long",
+    label:
+      "🎨 Bevorzugtefarbefürdiegesamtegestaltungderbenutzeroberfläche https://example.com/a/very/long/unbroken/url <b>not bold</b> اللون",
+    descriptionText: "يرجى اختيار لون Wählen Sie bitte die Farbe, die Ihnen für die Oberfläche am besten gefällt.",
+    placeholder: "Bitte wählen Sie eine Farbe aus der folgenden sehr langen Liste aus",
+    errorMessage: "DieausgewähltefarbeistleidernichtverfügbarbitteversuchenSieeserneut",
+    fieldHasError: true,
+    required: true,
+    options: [
+      { id: "0", name: "zero", value: "0", label: "0" },
+      { id: "1", name: "long", value: "long", label: "Dunkelblaugrüngrauschimmerndemitternachtsfarbemitmetallischemglanz" },
+      { id: "2", name: "html", value: "html", label: "<i>italic?</i>" },
+      { id: "3", name: "rtl", value: "rtl", label: "أزرق" },
+      ...Array.from({ length: 20 }, (_, index) => ({
+        id: `n${index}`,
+        name: `n${index}`,
+        value: `n${index}`,
+        label: `Colour ${index + 1}`,
+      })),
+    ],
+  },
+  render,
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      story: { inline: false, height: "520px" },
+      description: {
+        story:
+          "Long unbroken German, URL, emoji, HTML-like and right-to-left copy in the label, description, placeholder, error and options, with a long unbroken label selected. Check at every canvas width: the label, description and error wrap inside the dashed outline, the select never pushes past it, and markup renders as text.",
+      },
+    },
+  },
+};

package/app/components/05.forms/input-select/tests/{InputSelectCore.spec.ts → InputSelect.spec.ts}

@@ -1,7 +1,8 @@
 // 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 "../InputSelectCore.vue";
+import ComponentUnderTest from "../InputSelect.vue";
 
 const initialFieldData = {
   data: [
@@ -30,35 +31,63 @@ const wrapperFactory = (propsData = {}) => {
   });
 };
 
-describe("InputSelectCore", () => {
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks();
+});
+
+describe("InputSelect", () => {
   it("mounts without error", async () => {
     wrapper = await wrapperFactory();
     expect(wrapper.vm).toBeTruthy();
   });
 
+  it("renders the native select with the .input-select class", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("select.input-select").exists()).toBe(true);
+  });
+
   it("renders an option per fieldData item", async () => {
     wrapper = await wrapperFactory();
-    const options = wrapper.findAll("option");
+    const options = wrapper.findAll("option.input-select-option");
     expect(options.map((o) => o.text())).toEqual(["Red", "Blue"]);
   });
 
   it("binds v-model to the select value", async () => {
     wrapper = await wrapperFactory({ modelValue: "blue" });
-    expect(wrapper.find("select").element.value).toBe("blue");
+    expect((wrapper.find("select").element as HTMLSelectElement).value).toBe("blue");
+  });
+
+  it("selects an option whose value is 0", async () => {
+    wrapper = await wrapperFactory({
+      placeholder: "Pick a number",
+      modelValue: 0,
+      fieldData: { ...initialFieldData, data: [{ id: "0", name: "zero", value: 0, label: "Zero" }] },
+    });
+    expect((wrapper.find("select").element as HTMLSelectElement).selectedOptions[0]?.textContent?.trim()).toBe("Zero");
   });
 
   it("renders a disabled placeholder option when placeholder is set", async () => {
     wrapper = await wrapperFactory({ placeholder: "Choose a colour", modelValue: "" });
-    const placeholderOption = wrapper.find("option.placeholder");
+    const placeholderOption = wrapper.find("option.input-select-option-placeholder");
 
     expect(placeholderOption.exists()).toBe(true);
     expect(placeholderOption.text()).toBe("Choose a colour");
     expect(placeholderOption.attributes("disabled")).toBeDefined();
+    expect((placeholderOption.element as HTMLOptionElement).selected).toBe(true);
   });
 
   it("does not render a placeholder option when placeholder is unset", async () => {
     wrapper = await wrapperFactory();
-    expect(wrapper.find("option.placeholder").exists()).toBe(false);
+    expect(wrapper.find("option.input-select-option-placeholder").exists()).toBe(false);
+  });
+
+  it("renders option labels as text, not markup", async () => {
+    wrapper = await wrapperFactory({
+      fieldData: { ...initialFieldData, data: [{ id: "1", name: "x", value: "x", label: "<b>bold</b>" }] },
+    });
+    expect(wrapper.find("option b").exists()).toBe(false);
+    expect(wrapper.find("option").text()).toBe("<b>bold</b>");
   });
 
   it("sets required attribute when required is true", async () => {
@@ -71,6 +100,22 @@ describe("InputSelectCore", () => {
     expect(wrapper.find("select").attributes("required")).toBeUndefined();
   });
 
+  it("forwards title, defaulting to the English copy", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("select").attributes("title")).toBe("Please select an option");
+
+    await wrapper.setProps({ title: "Veuillez choisir" });
+    expect(wrapper.find("select").attributes("title")).toBe("Veuillez choisir");
+  });
+
+  it("omits aria-describedby when empty and forwards it when set", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("select").attributes("aria-describedby")).toBeUndefined();
+
+    await wrapper.setProps({ ariaDescribedby: "hint-id" });
+    expect(wrapper.find("select").attributes("aria-describedby")).toBe("hint-id");
+  });
+
   it("sets data-theme from the theme prop", async () => {
     wrapper = await wrapperFactory({ theme: "error" });
     expect(wrapper.find(".input-select-wrapper").attributes("data-theme")).toBe("error");
@@ -82,19 +127,30 @@ describe("InputSelectCore", () => {
     expect(wrapper.find("select").attributes("aria-invalid")).toBe("true");
   });
 
-  it("defaults inputVariant to normal", async () => {
+  it("omits data-invalid and aria-invalid by default", async () => {
     wrapper = await wrapperFactory();
-    expect(wrapper.find(".input-select-wrapper").classes()).toContain("normal");
+    expect(wrapper.find(".input-select-wrapper").attributes("data-invalid")).toBeUndefined();
+    expect(wrapper.find("select").attributes("aria-invalid")).toBeUndefined();
   });
 
-  it("applies inputVariant as a class on the wrapper", async () => {
+  it("defaults data-input-variant to normal", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".input-select-wrapper").attributes("data-input-variant")).toBe("normal");
+  });
+
+  it("sets data-input-variant from inputVariant", async () => {
     wrapper = await wrapperFactory({ inputVariant: "underlined" });
-    expect(wrapper.find(".input-select-wrapper").classes()).toContain("underlined");
+    expect(wrapper.find(".input-select-wrapper").attributes("data-input-variant")).toBe("underlined");
   });
 
-  it("applies styleClassPassthrough to the select", async () => {
+  it("applies styleClassPassthrough to the select and reacts to changes", async () => {
     wrapper = await wrapperFactory({ styleClassPassthrough: ["custom-select-class"] });
     expect(wrapper.find("select").classes()).toContain("custom-select-class");
+
+    await wrapper.setProps({ styleClassPassthrough: ["other-class"] });
+    await nextTick();
+    expect(wrapper.find("select").classes()).toContain("other-class");
+    expect(wrapper.find("select").classes()).not.toContain("custom-select-class");
   });
 
   it("sets isActive true on focus and false on blur", async () => {
@@ -114,6 +170,13 @@ describe("InputSelectCore", () => {
     expect(wrapper.emitted("update:isDirty")?.at(-1)).toEqual([true]);
   });
 
+  it("reflects isDirty and isActive as data attributes", async () => {
+    wrapper = await wrapperFactory({ isDirty: true, isActive: true });
+    const root = wrapper.find(".input-select-wrapper");
+    expect(root.attributes("data-dirty")).toBe("");
+    expect(root.attributes("data-active")).toBe("");
+  });
+
   it("renders an icon for an option that has one, hidden from assistive tech", async () => {
     wrapper = await wrapperFactory({
       fieldData: {
@@ -122,7 +185,7 @@ describe("InputSelectCore", () => {
       },
     });
 
-    const icon = wrapper.find(".input-select-core-option-decorator-icon");
+    const icon = wrapper.find(".input-select-option-icon");
     expect(icon.exists()).toBe(true);
     expect(icon.attributes("aria-hidden")).toBe("true");
   });

package/app/components/05.forms/input-select/tests/InputSelectField.spec.ts

@@ -0,0 +1,121 @@
+// 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 "../InputSelectField.vue";
+
+const initialFieldData = {
+  data: [
+    { id: "1", name: "red", value: "red", label: "Red" },
+    { id: "2", name: "blue", value: "blue", label: "Blue" },
+  ],
+  total: 2,
+  skip: 0,
+  limit: 10,
+};
+
+const initialPropsData = {
+  name: "colour",
+  label: "Colour",
+  errorMessage: "",
+  modelValue: "red",
+  fieldData: initialFieldData,
+};
+
+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("InputSelectField", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders .input-select-field as the root", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.classes()).toContain("input-select-field");
+  });
+
+  it("renders the label text, linked to the select", async () => {
+    wrapper = await wrapperFactory({ label: "Favourite colour" });
+    const label = wrapper.find("label");
+    expect(label.text()).toContain("Favourite colour");
+    expect(label.attributes("for")).toBe(wrapper.find("select").attributes("id"));
+  });
+
+  it("renders a native select with an option per fieldData item", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("select").exists()).toBe(true);
+    expect(wrapper.findAll("option").map((o) => o.text())).toEqual(["Red", "Blue"]);
+  });
+
+  it("sets data-invalid on the root when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true });
+    expect(wrapper.attributes("data-invalid")).toBe("");
+  });
+
+  it("renders the error message and links it via aria-describedby", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "Please choose a colour" });
+    expect(wrapper.text()).toContain("Please choose a colour");
+    const describedBy = wrapper.find("select").attributes("aria-describedby") ?? "";
+    expect(describedBy.length).toBeGreaterThan(0);
+  });
+
+  it("renders the descriptionText slot before the select by default", async () => {
+    wrapper = await wrapperFactory({}, { descriptionText: () => "Pick your favourite" });
+    const html = wrapper.html();
+    expect(wrapper.text()).toContain("Pick your favourite");
+    expect(html.indexOf("Pick your favourite")).toBeLessThan(html.indexOf("<select"));
+  });
+
+  it("renders the description after the select for the outlined variant", async () => {
+    wrapper = await wrapperFactory({ inputVariant: "outlined" }, { descriptionText: () => "Pick your favourite" });
+    const html = wrapper.html();
+    expect(html.indexOf("Pick your favourite")).toBeGreaterThan(html.indexOf("<select"));
+  });
+
+  it("sets data-input-variant on the root", async () => {
+    wrapper = await wrapperFactory({ inputVariant: "underlined" });
+    expect(wrapper.attributes("data-input-variant")).toBe("underlined");
+  });
+
+  it("applies styleClassPassthrough to its root only and reacts to changes", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: "custom-select" });
+    expect(wrapper.classes()).toContain("custom-select");
+    expect(wrapper.find("select").classes()).not.toContain("custom-select");
+
+    await wrapper.setProps({ styleClassPassthrough: "other-select" });
+    await nextTick();
+    expect(wrapper.classes()).toContain("other-select");
+    expect(wrapper.classes()).not.toContain("custom-select");
+  });
+
+  it("forwards required and title to the native select", async () => {
+    wrapper = await wrapperFactory({ required: true, title: "Choisissez" });
+    expect(wrapper.find("select").attributes("required")).toBeDefined();
+    expect(wrapper.find("select").attributes("title")).toBe("Choisissez");
+  });
+
+  it("applies the error theme to InputSelect when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, theme: "default" });
+    expect(wrapper.find(".input-select-wrapper").attributes("data-theme")).toBe("error");
+  });
+
+  it("defaults data-testid to input-select-field", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.attributes("data-testid")).toBe("input-select-field");
+  });
+});

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

@@ -1,4 +1,9 @@
-# InputTextCore — Consumer Styling Guide
+# InputText — Consumer Styling Guide
+
+> **Renamed 2026-10-16**: `InputTextCore` → `InputText`, `InputTextWithLabel` →
+> `InputTextField`, `InputPasswordWithLabel` → `InputPasswordField`,
+> `InputTextAsNumberWithLabel` → `InputTextAsNumberField`. Class changes are listed under "State
+> hooks" below.
 
 ## Public token API
 
@@ -7,25 +12,69 @@ override just this component; leave it unset and it inherits the shared `--theme
 `--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-text-*` 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.)
-
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
-| `--input-text-surface` | `var(--theme-input-surface)` | Wrapper background |
-| `--input-text-surface-hover` | `var(--theme-input-surface-hover)` | Background of an embedded `InputButton` slot on hover |
-| `--input-text-border` | `var(--theme-border)` | Border colour (`.normal`/`.underlined`, resting) |
-| `--input-text-border-hover` | `var(--theme-border-focus)` | Outline colour on hover (mouse) |
-| `--input-text-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (keyboard/assistive) |
-| `--input-text-color` | `var(--theme-input-text-color-normal)` | Input text colour |
+| `--input-text-surface` | `var(--theme-input-surface)` | Wrapper background, and slot `InputButton` background |
+| `--input-text-surface-hover` | `var(--theme-input-surface-hover)` | Slot `InputButton` background on hover |
+| `--input-text-border` | `var(--theme-border)` | Border colour (`normal`/`underlined`, resting), and the stepper's button dividers |
+| `--input-text-border-hover` | `var(--theme-border-focus)` | Outline colour on hover (`normal` only) |
+| `--input-text-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (`normal` only), and a slot button's own focus outline |
+| `--input-text-color` | `var(--theme-input-text-color-normal)` | Input text and slot button colour, and autofilled text (global rule) |
 | `--input-text-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |
 
-Geometry (`--input-padding-*`, `--input-min-height`, `--input-font-size`,
+Geometry (`--input-padding-*`, `--input-min-height`, `--input-font-size`, `--input-icon-slot-gap`,
 `--form-element-*`, etc.) is shared across every `05.forms` component and untouched by this —
 see `theming-form-geometry-tokens.md`.
 
+Private (not public API): `--_surface`, `--_border` and `--_border-focus`, each resolved once and
+read in several places.
+
+---
+
+## State hooks
+
+| Attribute | On | When |
+|---|---|---|
+| `data-input-variant="normal" \| "outlined" \| "underlined"` | `.input-text-wrapper`, each Field root | Always, mirrors `input-variant` |
+| `data-theme` | `.input-text-wrapper`, each Field root | Always, mirrors `theme` |
+| `data-invalid` | `.input-text-wrapper`, each Field root | `field-has-error` |
+| `data-dirty` | `.input-text-wrapper`, each Field root | The Field has seen a non-empty value |
+| `data-active` | `.input-text-wrapper`, each Field root | The input has focus |
+| `data-readonly` | `.input-text-wrapper` | `readonly` |
+| `data-inputmode` | `.input-text-wrapper` | Always, mirrors `inputmode` |
+| `data-has-left-slot` / `data-has-right-slot` | `.input-text-wrapper` | The `left` / `right` slot is filled |
+
+Field roots: `.input-text-field` (`InputTextField`, and `InputPasswordField`, which adds
+`.input-password-field`), `.input-text-as-number-field` (`InputTextAsNumberField`).
+
+Inner elements: `.input-text` (the native input), `.input-text-slot` (both slot holders),
+`.input-text-slot-left`, `.input-text-slot-right`, `.input-text-label` (the Fields' `InputLabel`),
+`.input-text-description` (the Fields' `InputDescription`), `.input-password-field-icon` (the
+password toggle's icon).
+
+`outlined` has no CSS of its own: the control renders with no border or outline. In
+`InputTextField` it moves the description after the input 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-text-wrapper.normal` / `.underlined` / `.outlined` → `[data-input-variant="…"]`
+> - `.input-text-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-text-slot-left` / `.input-text-slot-right`
+> - `.input-text-core` → `.input-text` (it also no longer carries `dirty`/`active` classes)
+> - `.input-text-with-label` → `.input-text-field`, now the Field's root (it used to sit inside
+>   an unclassed `<div>`); its variant/`dirty`/`active` classes → the attributes above
+> - `InputTextAsNumberField`'s root was `.input-text-with-label.input-text-as-number`; it's now
+>   `.input-text-as-number-field`, and the input no longer gets `.input-text-as-number`
+> - the password toggle icon's `.icon` → `.input-password-field-icon`
+>
+> Also: label, description and error copy wraps (`overflow-wrap: anywhere` on each Field root),
+> and the input can shrink below its intrinsic width (`min-inline-size: 0`), so a field no longer
+> overflows a narrow column.
+
 ---
 
 ## Global theming
@@ -51,9 +100,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**: `InputText`'s own passthrough lands on the `<input>`, which has no descendants, so
+tokens set through it only reach the input itself (text and placeholder colour). Set the others on
+a Field root or an ancestor.
+
 ### One instance
 
 ```vue
-<InputTextCore id="email" name="email" style="--input-text-border-focus: var(--gold-04);" />
+<InputTextField
+  v-model="email"
+  name="email"
+  type="email"
+  label="Email"
+  error-message=""
+  style="--input-text-border-focus: var(--gold-04);"
+/>
 ```
 
+---
+
+## Class passthrough
+
+`InputText`'s `:style-class-passthrough` lands on the native `<input class="input-text">`. Each
+Field's lands on its own root only.
+
+> **Changed 2026-10-16**: `InputTextField` and `InputTextAsNumberField` applied their passthrough
+> classes to both their root and the inner input. If you styled the input that way, select
+> `.your-class .input-text` instead.