srcdev-nuxt-components 9.6.8 → 9.6.9

package/app/components/05.forms/toggle-switch/stories/ToggleSwitchField.stories.ts

@@ -0,0 +1,176 @@
+import { computed, ref } from "vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import ToggleSwitchField from "../ToggleSwitchField.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
+import type { FormUiTheme, LabelWeight } from "~/types/forms/types.forms.d";
+import type { MediaCanvas } from "~/types/components";
+
+interface StoryArgs {
+  modelValue: string | number | boolean;
+  name: string;
+  label: string;
+  layout: "stacked" | "inline";
+  labelWeight: LabelWeight | undefined;
+  required: boolean;
+  errorMessage: string;
+  fieldHasError: boolean;
+  trueValue: string | number | boolean;
+  falseValue: string | number | boolean;
+  theme: FormUiTheme;
+  round: boolean;
+  styleClassPassthrough: string[];
+  descriptionText: string;
+  useCustomIcons: boolean;
+}
+
+const meta: Meta<StoryArgs> = {
+  title: "Components/Forms/Toggle Switch/ToggleSwitchField",
+  component: ToggleSwitchField,
+  argTypes: {
+    modelValue: { control: "boolean", table: { category: "Model" } },
+    name: { control: "text", table: { category: "Basic" } },
+    label: { control: "text", table: { category: "Basic" } },
+    layout: { control: { type: "select" }, options: ["stacked", "inline"], table: { category: "Layout" } },
+    labelWeight: {
+      control: { type: "select" },
+      options: [undefined, "normal", "semi-bold", "bold"],
+      description: "Defaults to bold when stacked, normal when inline",
+      table: { category: "Layout" },
+    },
+    required: { control: "boolean", table: { category: "Validation" } },
+    errorMessage: { control: "text", table: { category: "Validation" } },
+    fieldHasError: { control: "boolean", table: { category: "Validation" } },
+    trueValue: { control: "text", table: { category: "Values" } },
+    falseValue: { control: "text", table: { category: "Values" } },
+    theme: {
+      control: { type: "select" },
+      options: ["default", "success", "error", "warning"],
+      table: { category: "Styling" },
+    },
+    round: { control: "boolean", table: { category: "Styling" } },
+    styleClassPassthrough: { control: "object", table: { category: "Styling" } },
+    descriptionText: { control: "text", description: "Story-only: fills the descriptionText slot", table: { category: "Slots" } },
+    useCustomIcons: {
+      control: "boolean",
+      description: "Story-only: fills the iconOn/iconOff slots",
+      table: { category: "Slots" },
+    },
+  },
+  args: {
+    modelValue: false,
+    name: "notifications",
+    label: "Email notifications",
+    layout: "stacked",
+    labelWeight: undefined,
+    required: false,
+    errorMessage: "",
+    fieldHasError: false,
+    trueValue: true,
+    falseValue: false,
+    theme: "default",
+    round: true,
+    styleClassPassthrough: [],
+    descriptionText: "",
+    useCustomIcons: false,
+  },
+  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 switch: `InputLabel`, an optional description, `ToggleSwitch` and an error strip, linked through `aria-describedby`. `layout=\"stacked\"` (default) puts the label above the switch; `layout=\"inline\"` puts them on one row with the description and error below. `labelWeight` defaults to bold when stacked and normal when inline. `style-class-passthrough` lands on the `.toggle-switch-field` root only.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StoryArgs>;
+
+const render = (args: StoryArgs) => ({
+  components: { ToggleSwitchField },
+  setup() {
+    const componentArgs = computed(() => {
+      const { modelValue: _modelValue, descriptionText: _descriptionText, useCustomIcons: _useCustomIcons, ...rest } = args;
+      return rest;
+    });
+    return { args, componentArgs };
+  },
+  template: `
+    <ToggleSwitchField v-model="args.modelValue" v-bind="componentArgs">
+      <template v-if="args.descriptionText" #descriptionText>{{ args.descriptionText }}</template>
+      <template v-if="args.useCustomIcons" #iconOn><Icon name="mdi:check" /></template>
+      <template v-if="args.useCustomIcons" #iconOff><Icon name="mdi:close" /></template>
+    </ToggleSwitchField>
+  `,
+});
+
+export const Default: Story = { render };
+
+export const WithDescription: Story = { args: { descriptionText: "At most one email a week." }, render };
+
+export const Inline: Story = {
+  args: { layout: "inline", label: "Email me appointment reminders", descriptionText: "Sent the day before." },
+  render,
+  parameters: {
+    docs: {
+      description: {
+        story: "`layout=\"inline\"`: label and switch on one row, description and error below. Replaces `ToggleSwitchWithLabelInline`.",
+      },
+    },
+  },
+};
+
+export const WithCustomIcons: Story = { args: { useCustomIcons: true }, render };
+
+export const ErrorState: Story = {
+  args: { fieldHasError: true, errorMessage: "Please accept to continue", required: true },
+  render,
+};
+
+export const InlineError: Story = {
+  args: { layout: "inline", fieldHasError: true, errorMessage: "Please accept to continue" },
+  render,
+};
+
+export const StringValues: Story = { args: { modelValue: "off", trueValue: "on", falseValue: "off" }, render };
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    layout: "inline",
+    label:
+      "🔔 Benachrichtigungenüberterminänderungenundsonderangeboteperemailerhalten https://example.com/a/very/long/unbroken/url <b>not bold</b> إشعارات",
+    descriptionText: "يرجى تفعيل الإشعارات Sie erhalten höchstens eine Nachricht pro Woche, jederzeit abbestellbar.",
+    errorMessage: "BittebestätigenSiedieEinstellungbevorSiefortfahren",
+    fieldHasError: true,
+    useCustomIcons: true,
+  },
+  render,
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      description: {
+        story:
+          "The inline layout with long unbroken German, URL, emoji, HTML-like and right-to-left copy in the label, description and error. Check at every canvas width: the label wraps beside the switch without pushing it out of the dashed outline, the switch keeps its size, and markup renders as text. Switch `layout` to stacked to check that too.",
+      },
+    },
+  },
+};

package/app/components/05.forms/toggle-switch/tests/ToggleSwitch.spec.ts

@@ -0,0 +1,145 @@
+// 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 "../ToggleSwitch.vue";
+
+const initialPropsData = {
+  id: "test-toggle",
+  name: "testName",
+  modelValue: false,
+};
+
+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("ToggleSwitch", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders a checkbox input with the switch role", async () => {
+    wrapper = await wrapperFactory();
+    const input = wrapper.find("input.toggle-switch-input");
+
+    expect(input.attributes("type")).toBe("checkbox");
+    expect(input.attributes("role")).toBe("switch");
+    expect(input.attributes("id")).toBe("toggle-switch-test-toggle");
+  });
+
+  it("binds v-model to the checkbox checked state and data-checked", async () => {
+    wrapper = await wrapperFactory({ modelValue: true });
+
+    expect(wrapper.find<HTMLInputElement>("input").element.checked).toBe(true);
+    expect(wrapper.attributes("data-checked")).toBe("");
+
+    await wrapper.setProps({ modelValue: false });
+    expect(wrapper.attributes("data-checked")).toBeUndefined();
+  });
+
+  it("toggles modelValue when the track is clicked", async () => {
+    wrapper = await wrapperFactory({ modelValue: false });
+    await wrapper.find(".toggle-switch-track").trigger("click");
+    expect(wrapper.emitted("update:modelValue")?.at(-1)).toEqual([true]);
+  });
+
+  it("toggles once, through v-model, when the input itself is clicked", async () => {
+    wrapper = await wrapperFactory({ modelValue: false });
+    await wrapper.find("input").trigger("click");
+
+    expect(wrapper.emitted("update:modelValue")).toEqual([[true]]);
+  });
+
+  it("toggles between custom trueValue/falseValue", async () => {
+    wrapper = await wrapperFactory({ modelValue: "no", trueValue: "yes", falseValue: "no" });
+    await wrapper.find(".toggle-switch-track").trigger("click");
+    expect(wrapper.emitted("update:modelValue")?.at(-1)).toEqual(["yes"]);
+  });
+
+  it("sets required attribute when required is true", async () => {
+    wrapper = await wrapperFactory({ required: true });
+    expect(wrapper.find("input").attributes("required")).toBeDefined();
+  });
+
+  it("does not set required attribute by default", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("input").attributes("required")).toBeUndefined();
+  });
+
+  it("sets data-theme from the theme prop", async () => {
+    wrapper = await wrapperFactory({ theme: "success" });
+    expect(wrapper.attributes("data-theme")).toBe("success");
+  });
+
+  it("switches to the error theme and sets data-invalid and aria-invalid when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, theme: "success" });
+
+    expect(wrapper.attributes("data-theme")).toBe("error");
+    expect(wrapper.attributes("data-invalid")).toBe("");
+    expect(wrapper.find("input").attributes("aria-invalid")).toBe("true");
+  });
+
+  it("omits aria-invalid and aria-describedby by default", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("input").attributes("aria-invalid")).toBeUndefined();
+    expect(wrapper.find("input").attributes("aria-describedby")).toBeUndefined();
+  });
+
+  it("hides the decorative track from assistive tech", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".toggle-switch-track").attributes("aria-hidden")).toBe("true");
+  });
+
+  it("applies styleClassPassthrough to the root element and reacts to changes", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: ["custom-toggle"] });
+    expect(wrapper.classes()).toContain("custom-toggle");
+
+    await wrapper.setProps({ styleClassPassthrough: ["other-toggle"] });
+    await nextTick();
+    expect(wrapper.classes()).toContain("other-toggle");
+    expect(wrapper.classes()).not.toContain("custom-toggle");
+  });
+
+  it("renders default icons when no icon slots are provided", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.findAll(".toggle-switch-icon")).toHaveLength(2);
+  });
+
+  it("renders custom icon slot content instead of the default icon", async () => {
+    wrapper = await wrapperFactory(
+      {},
+      {
+        iconOn: '<span data-testid="custom-on">on</span>',
+        iconOff: '<span data-testid="custom-off">off</span>',
+      }
+    );
+
+    expect(wrapper.find(".toggle-switch-icon-on [data-testid='custom-on']").exists()).toBe(true);
+    expect(wrapper.find(".toggle-switch-icon-off [data-testid='custom-off']").exists()).toBe(true);
+  });
+
+  it("consumes round as a declared prop instead of leaking it as a DOM attribute", async () => {
+    wrapper = await wrapperFactory({ round: false });
+    expect(wrapper.props("round")).toBe(false);
+    expect(wrapper.attributes("round")).toBeUndefined();
+  });
+
+  it("defaults round to true", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.props("round")).toBe(true);
+  });
+});

package/app/components/05.forms/toggle-switch/tests/ToggleSwitchField.spec.ts

@@ -0,0 +1,155 @@
+// 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 "../ToggleSwitchField.vue";
+
+const initialPropsData = {
+  name: "notifications",
+  label: "Enable notifications",
+  modelValue: false,
+};
+
+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("ToggleSwitchField", () => {
+  it("mounts without error", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders .toggle-switch-field as the root with the stacked layout by default", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.classes()).toContain("toggle-switch-field");
+    expect(wrapper.attributes("data-layout")).toBe("stacked");
+  });
+
+  it("renders the label text, linked to the switch", async () => {
+    wrapper = await wrapperFactory();
+    const label = wrapper.find("label");
+
+    expect(label.text()).toContain("Enable notifications");
+    expect(label.classes()).toContain("toggle-switch-label");
+    expect(label.attributes("for")).toBe(wrapper.find("input[type='checkbox']").attributes("id"));
+  });
+
+  it("uses a bold label when stacked and a normal one when inline, unless labelWeight is set", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("label").classes()).toContain("body-normal-bold");
+
+    await wrapper.setProps({ layout: "inline" });
+    expect(wrapper.attributes("data-layout")).toBe("inline");
+    expect(wrapper.find("label").classes()).toContain("body-normal");
+
+    await wrapper.setProps({ labelWeight: "semi-bold" });
+    expect(wrapper.find("label").classes()).toContain("body-normal-semibold");
+  });
+
+  it("keeps the label, description, switch, error DOM order in both layouts", async () => {
+    for (const layout of ["stacked", "inline"]) {
+      wrapper = await wrapperFactory(
+        { layout, fieldHasError: true, errorMessage: "Required" },
+        { descriptionText: () => "Sends at most one email a week." }
+      );
+      const html = wrapper.html();
+      const order = ["<label", "Sends at most one email", "<input", "Required"].map((marker) => html.indexOf(marker));
+
+      expect(order).toEqual([...order].sort((a, b) => a - b));
+      wrapper.unmount();
+    }
+  });
+
+  it("renders the error message and sets data-invalid when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "Please choose" });
+
+    expect(wrapper.text()).toContain("Please choose");
+    expect(wrapper.attributes("data-invalid")).toBe("");
+    expect(wrapper.attributes("data-theme")).toBe("error");
+    expect(wrapper.find(".toggle-switch").attributes("data-theme")).toBe("error");
+  });
+
+  it("renders descriptionText and descriptionHtml through InputDescription", async () => {
+    wrapper = await wrapperFactory({}, { descriptionText: () => "Plain hint" });
+    expect(wrapper.find(".toggle-switch-description").text()).toContain("Plain hint");
+    wrapper.unmount();
+
+    wrapper = await wrapperFactory({}, { descriptionHtml: () => "Rich hint" });
+    expect(wrapper.find(".toggle-switch-description").text()).toContain("Rich hint");
+  });
+
+  it("renders no description element without a description slot", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".toggle-switch-description").exists()).toBe(false);
+  });
+
+  it("forwards required to the underlying input", async () => {
+    wrapper = await wrapperFactory({ required: true });
+    expect(wrapper.find("input").attributes("required")).toBeDefined();
+  });
+
+  it("applies styleClassPassthrough to its root only and reacts to changes", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: ["custom-toggle"] });
+    expect(wrapper.classes()).toContain("custom-toggle");
+    expect(wrapper.find(".toggle-switch").classes()).not.toContain("custom-toggle");
+
+    await wrapper.setProps({ styleClassPassthrough: ["other-toggle"] });
+    await nextTick();
+    expect(wrapper.classes()).toContain("other-toggle");
+  });
+
+  it("forwards round to ToggleSwitch without leaking it as a DOM attribute", async () => {
+    wrapper = await wrapperFactory({ round: false });
+    const toggle = wrapper.findComponent({ name: "ToggleSwitch" });
+
+    expect(toggle.props("round")).toBe(false);
+    expect(wrapper.find(".toggle-switch").attributes("round")).toBeUndefined();
+  });
+
+  it("points aria-describedby at the description once it appears after mount", async () => {
+    const Host = defineComponent({
+      components: { ComponentUnderTest },
+      setup() {
+        return { modelValue: ref(false), showDescription: ref(false) };
+      },
+      template: `
+        <ComponentUnderTest v-model="modelValue" name="notifications" label="Enable notifications">
+          <template v-if="showDescription" #descriptionText>Sends at most one email a week.</template>
+        </ComponentUnderTest>
+      `,
+    });
+    const host = await mountSuspended(Host);
+    const input = () => host.find("input[type='checkbox']");
+    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.unmount();
+  });
+
+  it("points aria-describedby at both the description and the error when both are present", async () => {
+    wrapper = await wrapperFactory(
+      { fieldHasError: true, errorMessage: "Required" },
+      { descriptionText: () => "Sends at most one email a week." }
+    );
+    const ids = (wrapper.find("input[type='checkbox']").attributes("aria-describedby") ?? "").split(" ");
+
+    expect(ids).toHaveLength(2);
+    expect(ids[0]).toMatch(/-description$/);
+    expect(ids[1]).toMatch(/-error-message$/);
+    expect(wrapper.find(`[id="${ids[0]}"]`).exists()).toBe(true);
+  });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.6.8",
+  "version": "9.6.9",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",

package/.claude/skills/components/input-select-core.md

@@ -1,151 +0,0 @@
-# InputSelectCore Component
-
-## Overview
-
-`InputSelectCore` is the low-level native `<select>` primitive for the `05.forms` select family.
-It renders a native select with a data-driven list of `<option>`s (each optionally decorated with
-an icon), an optional placeholder option, and adopts the modern CSS Customizable Select API
-(`appearance: base-select`) for a fully styleable open-picker state where supported, with a
-graceful CSS fallback (see "Browser support" below). It has no label, description, or
-error-message rendering of its own — that's composed by the `InputSelectWithLabel` variant below.
-
-Most consumers should reach for **InputSelectWithLabel** rather than `InputSelectCore` directly.
-
----
-
-## Props reference
-
-> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:field-has-error`, `:style-class-passthrough`, `:aria-describedby`.
-
-| Prop (template form) | Type | Default | Notes |
-|------|------|---------|-------|
-| `:id` | `string` | (required) | Applied to the native select. |
-| `:name` | `string` | (required) | Applied to the native select. |
-| `:placeholder` | `string` | `""` | Renders a disabled placeholder `<option>` (selected when `modelValue` is empty). No option rendered at all when unset. |
-| `:title` | `string` | `"Please select an option"` | Native `title` attribute (tooltip). |
-| `:required` | `boolean` | `false` | Native `required`. |
-| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
-| `:input-variant` | `InputUiVariant` | `"normal"` | Adds the variant name as a class on the wrapper — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputTextCore`. |
-| `:field-has-error` | `boolean` | `false` | Drives `data-invalid` on the wrapper and `aria-invalid` on the select. |
-| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the select element. |
-| `:aria-describedby` | `string` | `""` | Forwarded to the native select. |
-
-### v-models
-
-- `v-model` — `string | number | readonly number[]`, **required** (`defineModel({ required: true })`, satisfying `vue/require-default-prop` — see `project_ledger_eslint_issues_column` in memory).
-- `v-model:field-data` — `IFormMultipleOptions` (`{ data: IOptionsConfig[]; total; skip; limit }`), **required**. The `data` array drives the rendered `<option>`s. The template dereferences `fieldData.data` unconditionally, so a consumer that doesn't bind `v-model:field-data` will crash on render — `required: true` documents that constraint (it's a dev-time warning only, not a runtime guard).
-- `v-model:is-dirty` — `boolean`. Set to `true` on the native `change` event (never reset to `false` by this component).
-- `v-model:is-active` — `boolean`. Tracks native focus/blur (`focusin`/`focusout`), toggling `.active` on the wrapper.
-
----
-
-## CSS token API
-
-See [CONSUMER-STYLING.md](../../app/components/05.forms/input-select/CONSUMER-STYLING.md) for the
-full table with defaults.
-
-**Common tokens:**
-- `--input-select-surface` / `-surface-hover` — wrapper/select background and option-row hover background, fall back to `--theme-input-surface`/`-surface-hover`
-- `--input-select-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline (also the open-picker's own border/outline), fall back to `--theme-border`/`--theme-border-focus`
-
----
-
-## Browser support: `appearance: base-select`
-
-The open-picker styling (`&::picker(select)`, `:open`/`:not(:open)` states, the transition/opacity
-`@starting-style` reveal) relies on the CSS Customizable Select API
-(`appearance: base-select`/`::picker(select)`), a very new feature not yet supported everywhere.
-The component degrades gracefully in non-supporting browsers rather than breaking: `appearance:
-none` is set first (unconditionally), then overridden by `appearance: base-select` only where the
-browser recognizes that value — an unsupported value is simply ignored by the CSS parser, so the
-select falls back to the browser's native (unstyled) dropdown instead of losing functionality.
-Per pitfall #19's general lesson (checking WebKit support specifically for load-bearing use of a
-very new CSS feature, since Chrome's device-emulation mode can't catch a WebKit-only gap): this
-fallback is CSS-only degradation, not a functional break like `ExpandingPanel`'s `::details-content`
-case was, so it's lower risk — but the open-picker's custom border/outline/transition styling
-should still be spot-checked on a real Safari session before treating it as visually final.
-
----
-
-## Fixed 2026-09-22: dead functionality and prop-shape bugs
-
-`InputSelectCore` migrated to full compliance from a `variants:true`, `eslint_issues:true`,
-score-2/5 state (no tests, no skill doc, no snippet).
-
-- **`required` prop was declared but never bound to the native `<select>`** — native HTML
-  `required` validation was completely inert regardless of the prop's value. Fixed by adding
-  `:required` to the select.
-- **`styleClassPassthrough` prop was declared but never consumed** — no `useStyleClassPassthrough`
-  call existed anywhere in the script, and the select's `class` was a hardcoded static string.
-  The prop was entirely dead; a consumer passing it had no effect. Fixed by wiring up
-  `useStyleClassPassthrough` and binding `elementClasses` alongside the static class.
-- **`isDirty`/`isActive` models were declared and read in the wrapper's CSS class bindings
-  (`{ dirty: isDirty }`, `{ active: isActive }`), but nothing ever set them** — no `focusin`/
-  `focusout`/`change` handlers existed at all, unlike `InputTextareaCore`'s `updateFocus`
-  pattern. The `.dirty`/`.active` CSS states could never trigger. Fixed by adding
-  `@focusin`/`@focusout` (toggling `isActive`) and `@change` (setting `isDirty = true`) directly
-  on the select.
-- **The placeholder `<option>` used `readonly`**, which is not a valid/supported HTML attribute
-  on `<option>` — a silent no-op, leaving the placeholder fully selectable as a real answer
-  (defeating its purpose). Fixed by switching to `disabled`, the correct native pattern for a
-  non-selectable placeholder option.
-- **`theme`/`inputVariant` were typed as inline unions** (`"default" | "success" | "error" |
-  "warning"` / `"normal" | "outlined" | "underlined"`) instead of importing the shared
-  `FormUiTheme`/`InputUiVariant` types — aligned with the rest of `05.forms`.
-- **`fieldData`'s `defineModel` used an untyped `defineModel("fieldData") as Ref<T>` cast**
-  instead of the proper generic `defineModel<T>("fieldData")` call, and had no default — the
-  `as` cast also hid the prop from ESLint's `vue/require-default-prop` detection entirely (it
-  didn't fire on `InputSelectCore.vue`, only on `InputSelectWithLabel.vue`'s correctly-typed
-  equivalent). Fixed by using the proper generic form with `{ required: true }` on both files —
-  see the `v-model:field-data` note above for why `required` is the meaningful fix here (the
-  template would otherwise crash on `fieldData.data` with no data bound).
-- **Dead commented-out CSS** (~8 lines, a "legacy support - eg, Safari" `::after` arrow
-  fallback that was never active) and a **redundant duplicate declaration**
-  (`&.underlined { background-color: var(--_surface); }`, re-setting a value the unscoped base
-  rule already applied unconditionally) were removed.
-- **CSS token cleanup**: `--_surface`, `--_surface-hover`, `--_border-hover`, and
-  `--_outline-color` were each used at exactly one point with no composition or state-swap
-  behind them (`--_outline-color` was a bare alias for `--_border-focus`, per pitfall #20) — all
-  four inlined directly to their public `var(--input-select-*, {default})` form at their point of
-  use. `--_border` (reused across `.normal`/`.underlined`/open-picker) and `--_border-focus`
-  (used directly once, plus now the open-picker's outline too) correctly stayed private.
-
----
-
-## Variants
-
-### InputSelectWithLabel
-
-`InputSelectWithLabel` (`InputSelectWithLabel.vue`) composes `InputSelectCore` with
-`InputLabel`, `InputDescription` (positioned before or after the field depending on
-`inputVariant === "outlined"`, matching `InputTextWithLabel`'s exact placement rule), and
-`InputError`.
-
-**Additional props over InputSelectCore:**
-
-| Prop (template form) | Type | Default | Notes |
-|------|------|---------|-------|
-| `:data-testid` | `string` | `"input-select-with-label"` | Sets `data-testid` on the wrapper — used for the wrapper element specifically (`:data-testid` shorthand resolves to the camelCase `dataTestid` prop, same convention as `:aria-describedby`). |
-| `:label` | `string` | (required) | Rendered via `InputLabel`. |
-| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
-
-**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`).
-
-```vue
-<InputSelectWithLabel
-  name="colour"
-  label="Favourite colour"
-  v-model="colour"
-  v-model:field-data="colourOptions"
-  placeholder="Choose a colour"
-  :error-message="errors.colour"
-  :field-has-error="!!errors.colour"
->
-  <template #descriptionText>Pick the colour you like best</template>
-</InputSelectWithLabel>
-```
-
-`v-model` and `v-model:field-data` are both **required** — same as `InputSelectCore` above. Note
-this wrapper passes `:theme="FormUiTheme"` (a local `computed`, not the raw `theme` prop) down to
-`InputSelectCore`, so the theme automatically switches to `"error"` whenever `fieldHasError` is
-true, regardless of the `theme` prop's own value.