srcdev-nuxt-components 9.4.9 → 9.4.11

package/app/components/05.forms/patterns/stories/MigratedFieldsForm.stories.ts

@@ -0,0 +1,220 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { reactive } from "vue";
+import InputTextWithLabel from "../../input-text/variants/InputTextWithLabel.vue";
+import InputRangeDefault from "../../input-range/variants/InputRangeDefault.vue";
+import InputNumberDefault from "../../input-number/variants/InputNumberDefault.vue";
+import InputTextareaWithLabel from "../../input-textarea/variants/InputTextareaWithLabel.vue";
+import InputSelectWithLabel from "../../input-select/variants/InputSelectWithLabel.vue";
+import ToggleSwitchWithLabel from "../../toggle-switch/variants/ToggleSwitchWithLabel.vue";
+import InputButtonCore from "../../input-button/InputButtonCore.vue";
+import FormField from "../../form-field/FormField.vue";
+import HeroText from "../../../01.atoms/text-blocks/hero-text/HeroText.vue";
+import type { InputUiVariant, IFormMultipleOptions } from "~/types/forms/types.forms.d";
+
+interface MigratedFieldsFormStoryArgs {
+  inputVariant: InputUiVariant;
+}
+
+// Living reference, not a component of its own — one field per 05.forms component group that
+// currently scores 5/5 in the Component Ledger (.claude/component-ledger/audit.json: tier folder,
+// tests, story, skill doc, CONSUMER-STYLING.md, VS Code snippet). As of 2026-09-23 that's
+// InputTextCore (via InputTextWithLabel), InputRangeCore (via InputRangeDefault), InputNumberCore
+// (via InputNumberDefault), InputTextareaCore (via InputTextareaWithLabel), InputSelectCore
+// (via InputSelectWithLabel), and ToggleSwitchCore (via ToggleSwitchWithLabel) — every other
+// 05.forms component (checkbox, radio, ...) is still mid-migration.
+// Add a field here each time /migrate-component brings another 05.forms component up to 5/5, so
+// this story doubles as a visible migration-progress tracker rather than living only in the
+// ledger's HTML output. No validation wiring (useZodValidation/zod) here — that's the consuming
+// app's concern, this is a visual/composition reference only.
+export default {
+  title: "Patterns/Migrated Fields Form",
+  argTypes: {
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      description: "Applied to every text-like field in the form at once",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    inputVariant: "normal",
+  },
+} as Meta<MigratedFieldsFormStoryArgs>;
+
+const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
+  components: {
+    InputTextWithLabel,
+    InputRangeDefault,
+    InputNumberDefault,
+    InputTextareaWithLabel,
+    InputSelectWithLabel,
+    ToggleSwitchWithLabel,
+    InputButtonCore,
+    FormField,
+    HeroText,
+  },
+  setup() {
+    const state = reactive({
+      fullName: "",
+      budget: 50,
+      quantity: 1,
+      notes: "",
+      colour: "",
+      subscribe: false,
+    });
+
+    const colourOptions = reactive<IFormMultipleOptions>({
+      data: [
+        { id: "1", name: "red", value: "red", label: "Red" },
+        { id: "2", name: "blue", value: "blue", label: "Blue" },
+        { id: "3", name: "green", value: "green", label: "Green" },
+      ],
+      total: 3,
+      skip: 0,
+      limit: 10,
+    });
+
+    // Demo-only "validation" — a real consuming app would wire this through something like
+    // useZodValidation instead (see this file's top comment). Kept deliberately simple so the
+    // Continue button has an obvious, reliable way to trigger each field's error state for
+    // exercising InputTextWithLabel/InputRangeDefault/InputNumberDefault/InputTextareaWithLabel/
+    // InputSelectWithLabel's error UI in Storybook.
+    const errors = reactive({
+      fullName: "",
+      budget: "",
+      quantity: "",
+      notes: "",
+      colour: "",
+    });
+
+    const validate = () => {
+      errors.fullName = state.fullName.trim() ? "" : "Full name is required";
+      errors.budget = state.budget >= 100 ? "" : "Budget must be at least £100";
+      errors.quantity = state.quantity >= 1 ? "" : "Quantity must be at least 1";
+      errors.notes = state.notes.trim() ? "" : "Notes are required";
+      errors.colour = state.colour ? "" : "Please choose a colour";
+    };
+
+    const clearErrors = () => {
+      errors.fullName = "";
+      errors.budget = "";
+      errors.quantity = "";
+      errors.notes = "";
+      errors.colour = "";
+    };
+
+    return { args, state, errors, validate, clearErrors, colourOptions };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 480px;">
+      <HeroText
+        tag="h2"
+        font-size="heading"
+        :text-content="[{ text: 'Migrated fields', styleClass: 'normal' }]"
+        :style-class-passthrough="['mbe-20']"
+      />
+      <p style="margin: 0 0 2rem 0; color: #475569; font-size: 1.4rem;">
+        One field per 05.forms component that's fully migrated (5/5 on the Component Ledger).
+        Click Continue with an empty name, a budget under £100, a quantity under 1, empty notes,
+        or no colour chosen to see the error states.
+      </p>
+
+      <form novalidate @submit.prevent="validate">
+        <FormField width="wide" :has-gutter="false">
+          <InputTextWithLabel
+            v-model="state.fullName"
+            type="text"
+            name="fullName"
+            label="Full name"
+            placeholder="eg. Jane Smith"
+            :error-message="errors.fullName"
+            :field-has-error="!!errors.fullName"
+            :required="true"
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputRangeDefault
+            v-model="state.budget"
+            name="budget"
+            label="Budget (£)"
+            :min="0"
+            :max="500"
+            :step="10"
+            :error-message="errors.budget"
+            :field-has-error="!!errors.budget"
+          >
+            <template #left><span aria-hidden="true">−</span></template>
+            <template #right><span aria-hidden="true">+</span></template>
+          </InputRangeDefault>
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputNumberDefault
+            v-model="state.quantity"
+            name="quantity"
+            label="Quantity"
+            :min="1"
+            :max="10"
+            :error-message="errors.quantity"
+            :field-has-error="!!errors.quantity"
+            :input-variant="args.inputVariant"
+          >
+            <template #left><span aria-hidden="true">−</span></template>
+            <template #right><span aria-hidden="true">+</span></template>
+          </InputNumberDefault>
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputTextareaWithLabel
+            v-model="state.notes"
+            name="notes"
+            label="Notes"
+            placeholder="Anything else we should know?"
+            :error-message="errors.notes"
+            :field-has-error="!!errors.notes"
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputSelectWithLabel
+            v-model="state.colour"
+            v-model:field-data="colourOptions"
+            name="colour"
+            label="Favourite colour"
+            placeholder="Choose a colour"
+            :error-message="errors.colour"
+            :field-has-error="!!errors.colour"
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <ToggleSwitchWithLabel v-model="state.subscribe" name="subscribe" label="Subscribe to updates" />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <div style="display: flex; gap: 1.2rem;">
+            <InputButtonCore type="submit" variant="primary" button-text="Continue" />
+            <InputButtonCore type="button" variant="tertiary" button-text="Clear errors" @click="clearErrors" />
+          </div>
+        </FormField>
+      </form>
+
+      <div
+        style="margin-top: 2rem; padding: 1.6rem; border-radius: 0.8rem; background: #f8fafc; font-family: monospace; font-size: 1.3rem;"
+      >
+        <div>fullName: {{ state.fullName || '""' }}</div>
+        <div>budget: £{{ state.budget }}</div>
+        <div>quantity: {{ state.quantity }}</div>
+        <div>notes: {{ state.notes || '""' }}</div>
+        <div>colour: {{ state.colour || '""' }}</div>
+        <div>subscribe: {{ state.subscribe }}</div>
+      </div>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});

package/app/components/05.forms/toggle-switch/CONSUMER-STYLING.md

@@ -23,6 +23,13 @@ token-rename pass, not a redesign.
 Geometry (`--input-toggle-*`, `--form-element-*`) is shared across every `05.forms` component and
 untouched by this — see `theming-form-geometry-tokens.md`.
 
+### Shape (`round` prop)
+
+`--toggle-switch-border-radius` controls the track and thumb's shared `border-radius`. Left unset,
+it defaults to `100vw` (pill shape) when the `round` prop is `true` (the default), or `0.4rem`
+(a rounded-square shape) when `round` is `false` — see the `SquareShape` story. Set the token
+directly to override with an exact value the two-state default doesn't produce.
+
 ### Track width
 
 `--toggle-switch-track-width` overrides the track's width directly. Left unset, the track derives
@@ -64,3 +71,25 @@ fixed width independent of symbol size).
 ```vue
 <ToggleSwitchCore id="notifications" name="notifications" style="--toggle-switch-symbol-surface-on: var(--gold-06);" />
 ```
+
+---
+
+## Migration notes (2026-09-23)
+
+- **`round` prop was previously dead** — `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline`
+  both accepted and forwarded it, but `ToggleSwitchCore` never declared the prop or read it, so
+  the Storybook `SquareShape` story rendered identically to `Default`. Fixed by adding `round` to
+  `ToggleSwitchCore` and wiring it to the new `--toggle-switch-border-radius` token (see Shape
+  above).
+- **`fieldHasError` didn't visually theme the component** — `ToggleSwitchCore` and
+  `ToggleSwitchWithLabel` both computed an error-aware theme value but bound `data-theme` to the
+  raw `theme` prop instead, so setting `fieldHasError` never applied this library's
+  `[data-theme="error"]` theme-token overrides (`_error.css`). Fixed by binding `data-theme` to the
+  computed value.
+- Custom `iconOn`/`iconOff` slot content could render as a non-square box (e.g. a 16×16 SVG
+  rendering as ~16×20), throwing off centering inside the thumb — fixed by adding
+  `line-height: 0` to `.symbol-icon`, which collapses inline leading for any slotted content.
+- Two dead, unread `--_transition-duration` private locals were removed from
+  `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` — nothing in either file's CSS or
+  `ToggleSwitchCore`'s ever read them (the actual transition durations are hardcoded `0.4s`
+  literals in `ToggleSwitchCore`).

package/app/components/05.forms/toggle-switch/ToggleSwitchCore.vue

@@ -1,6 +1,6 @@
 <template>
-  <div class="toggle-switch-core" :class="elementClasses" :data-theme="theme">
-    <div class="toggle-switch-wrapper" :class="wrapperClasses" :for="inputId" @click="toggleSwitchValue">
+  <div class="toggle-switch-core" :class="elementClasses" :data-theme="formUiTheme">
+    <div class="toggle-switch-wrapper" :class="wrapperClasses" @click="toggleSwitchValue">
       <input
         :id="inputId"
         v-model="modelValue"
@@ -44,6 +44,7 @@ interface Props {
   falseValue?: string | number | boolean;
   styleClassPassthrough?: string | string[];
   theme?: FormUiTheme;
+  round?: boolean;
   ariaDescribedby?: string;
 }
 
@@ -54,17 +55,20 @@ const props = withDefaults(defineProps<Props>(), {
   falseValue: false,
   styleClassPassthrough: () => [],
   theme: "default",
+  round: true,
   ariaDescribedby: "",
 });
 
 const slots = useSlots();
 const useDefaultIcons = computed(() => !slots.iconOn && !slots.iconOff);
 
-const FormUiTheme = computed(() => {
+const formUiTheme = computed(() => {
   return props.fieldHasError ? "error" : props.theme;
 });
 
-const modelValue = defineModel<string | number | boolean>();
+const roundedRadiusDefault = computed(() => (props.round ? "100vw" : "0.4rem"));
+
+const modelValue = defineModel<string | number | boolean>({ required: true });
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 const inputId = computed(() => `toggle-switch-${props.id}`);
@@ -90,156 +94,153 @@ const toggleSwitchValue = () => {
 
 <style lang="css">
 @layer components {
-.toggle-switch-core {
-  .toggle-switch-label {
-    display: block;
-  }
+  .toggle-switch-core {
+    .toggle-switch-label {
+      display: block;
+    }
 
-  .toggle-switch-wrapper {
-    /* --_icon-font-size, --_switch-padding, --_toggle-symbol-border-width are the only locals
+    .toggle-switch-wrapper {
+      /* --_icon-font-size, --_switch-padding, --_toggle-symbol-border-width are the only locals
        actually read anywhere below — --_icon-on-opacity, --_icon-off-opacity,
        --_symbol-background-color, --_symbol-margin-inline-start, --_symbol-checked-offset were
        declared here but never referenced by any property in this file; removed as dead code
        rather than migrated, since migrating an unread token would just create a new unread
        public one. */
-    --_icon-font-size: 2.4rem;
-    --_switch-padding: 0.2rem;
-    --_toggle-symbol-border-width: 0.1rem;
+      --_icon-font-size: 2.4rem;
+      --_switch-padding: 0.2rem;
+      --_toggle-symbol-border-width: 0.1rem;
 
-    /* Public --toggle-switch-* tokens, inline-fallback to the shared --theme-* tokens (see
+      /* Public --toggle-switch-* tokens, inline-fallback to the shared --theme-* tokens (see
        theming-component-token-pattern.md) — overriding one here doesn't touch every other
        themed input/control that also reads --theme-checkbox-symbol-surface/--theme-border. */
-    --_surface: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
-    --_surface-hover: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
-    --_border: var(--toggle-switch-border, var(--theme-border));
-    --_border-focus: var(--toggle-switch-border-focus, var(--theme-border-focus));
-
-    display: flex;
-    flex-direction: column;
-
-    input {
-      height: 0;
-      width: 0;
-      opacity: 0;
-
-      &:focus-visible {
-        + .symbol-wrapper {
-          outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
-          outline-offset: var(--form-element-outline-offset-focus);
+      --_surface: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
+      --_surface-hover: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
+      --_border: var(--toggle-switch-border, var(--theme-border));
+      --_border-focus: var(--toggle-switch-border-focus, var(--theme-border-focus));
+      --_border-radius: var(--toggle-switch-border-radius, v-bind(roundedRadiusDefault));
+
+      display: flex;
+      flex-direction: column;
+
+      input {
+        height: 0;
+        width: 0;
+        opacity: 0;
+
+        &:focus-visible {
+          + .symbol-wrapper {
+            outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
+            outline-offset: var(--form-element-outline-offset-focus);
+          }
         }
       }
-    }
 
-    .symbol-wrapper {
-      /* Geometry */
+      .symbol-wrapper {
+        /* Geometry */
 
-      /* Track width has no direct public token — it's derived from the same geometry tokens
+        /* Track width has no direct public token — it's derived from the same geometry tokens
          that size the thumb, so the track always scales with --input-toggle-symbol-size instead
          of clipping/floating it. Breakdown at the default 0.1rem tokens (= 72px total):
          2×symbol-size (6rem) + 2×form-element-border-width (0.2rem, wrapper border) +
          2×wrapper-padding (0.2rem) + 3×symbol-outline-width (0.3rem) +
          3×symbol-border-width (0.3rem) + 2×symbol-margin (0.2rem). Override
          --toggle-switch-track-width directly if you need a value the formula doesn't produce. */
-      --_track-width: var(
-        --toggle-switch-track-width,
-        calc(
-          (2 * var(--input-toggle-symbol-size)) + (2 * var(--form-element-border-width)) +
-            (2 * var(--input-toggle-wrapper-padding)) + (3 * var(--input-toggle-symbol-outline-width)) +
-            (3 * var(--input-toggle-symbol-border-width)) + (2 * var(--input-toggle-symbol-margin))
-        )
-      );
-
-      display: inline-flex;
-      align-items: center;
-      justify-content: start;
-      position: relative;
-      transition:
-        background-color var(--theme-form-transition-duration) linear,
-        border-color var(--theme-form-transition-duration) linear,
-        outline var(--theme-form-transition-duration) linear,
-        outline-offset var(--theme-form-transition-duration) linear,
-        outline var(--theme-form-transition-duration) linear;
-
-      /* UI */
-      background-color: var(--_surface);
-      border: var(--form-element-border-width) solid var(--_border);
-      outline: var(--form-element-outline-width) solid transparent;
-      border-radius: 100vw;
-      width: var(--_track-width);
-      padding: calc(var(--input-toggle-wrapper-padding) + var(--input-toggle-symbol-outline-width));
-
-      &:hover {
-        background-color: var(--_surface-hover);
-        cursor: pointer;
-      }
-
-      .symbol {
-        /* Geometry */
-
-        display: inline-grid;
-        grid-template-areas: "icon";
-        place-content: center;
-        /* position: absolute; */
-        overflow: hidden;
-        translate: 0 0;
-
-        aspect-ratio: 1/1;
+        --_track-width: var(
+          --toggle-switch-track-width,
+          calc(
+            (2 * var(--input-toggle-symbol-size)) + (2 * var(--form-element-border-width)) +
+              (2 * var(--input-toggle-wrapper-padding)) + (3 * var(--input-toggle-symbol-outline-width)) +
+              (3 * var(--input-toggle-symbol-border-width)) + (2 * var(--input-toggle-symbol-margin))
+          )
+        );
+
+        display: inline-flex;
+        align-items: center;
+        justify-content: start;
+        position: relative;
+        transition:
+          background-color var(--theme-form-transition-duration) linear,
+          border-color var(--theme-form-transition-duration) linear,
+          outline var(--theme-form-transition-duration) linear,
+          outline-offset var(--theme-form-transition-duration) linear,
+          outline var(--theme-form-transition-duration) linear;
 
         /* UI */
-        /* padding: calc(calc(var(--input-toggle-symbol-size) - var(--_icon-font-size)) / 2); */
-        border: var(--input-toggle-symbol-border-width) solid var(--toggle-switch-symbol-border, var(--theme-text));
-        outline: var(--input-toggle-symbol-outline-width) solid transparent;
-        border-radius: 100vw;
-        background-color: var(--toggle-switch-symbol-surface-off, var(--theme-on-surface));
-        transition:
-          translate 0.4s ease,
-          background-color 0.4s linear;
-
-        &.checked {
-          background-color: var(--toggle-switch-symbol-surface-on, var(--theme-surface));
-          /* left: calc(
-            100% - var(--input-toggle-symbol-size) - var(--_switch-padding) - (2 * var(--_toggle-symbol-border-width))
-          ); */
-          /* translate: calc(var(--input-toggle-symbol-size) / 2) 0; */
-          /* translate: 1.6rem 0; */
-          translate: calc(
-              var(--input-toggle-symbol-size) + var(--input-toggle-symbol-border-width) +
-                var(--input-toggle-symbol-outline-width)
-            )
-            0;
+        background-color: var(--_surface);
+        border: var(--form-element-border-width) solid var(--_border);
+        outline: var(--form-element-outline-width) solid transparent;
+        border-radius: var(--_border-radius);
+        width: var(--_track-width);
+        padding: calc(var(--input-toggle-wrapper-padding) + var(--input-toggle-symbol-outline-width));
+
+        &:hover {
+          background-color: var(--_surface-hover);
+          cursor: pointer;
         }
 
-        .symbol-icon {
+        .symbol {
           /* Geometry */
 
-          display: grid;
-          grid-area: icon;
+          display: inline-grid;
+          grid-template-areas: "icon";
           place-content: center;
-          opacity: 0;
+          overflow: hidden;
+          translate: 0 0;
+
+          aspect-ratio: 1/1;
 
           /* UI */
-          width: var(--input-toggle-symbol-size);
-          height: var(--input-toggle-symbol-size);
-          margin: var(--input-toggle-symbol-margin);
+          /* padding: calc(calc(var(--input-toggle-symbol-size) - var(--_icon-font-size)) / 2); */
+          border: var(--input-toggle-symbol-border-width) solid var(--toggle-switch-symbol-border, var(--theme-text));
+          outline: var(--input-toggle-symbol-outline-width) solid transparent;
+          border-radius: var(--_border-radius);
+          background-color: var(--toggle-switch-symbol-surface-off, var(--theme-on-surface));
           transition:
-            opacity var(--theme-form-transition-duration),
-            color var(--theme-form-transition-duration);
-
-          &.icon-on {
-            color: var(--toggle-switch-icon-on-color, var(--theme-on-surface));
-          }
-
-          &.icon-off {
-            color: var(--toggle-switch-icon-off-color, var(--theme-surface));
+            translate 0.4s ease,
+            background-color 0.4s linear;
+
+          &.checked {
+            background-color: var(--toggle-switch-symbol-surface-on, var(--theme-surface));
+            translate: calc(
+                var(--input-toggle-symbol-size) + var(--input-toggle-symbol-border-width) +
+                  var(--input-toggle-symbol-outline-width)
+              )
+              0;
           }
 
-          &.active {
-            opacity: 1;
+          .symbol-icon {
+            /* Geometry */
+
+            display: grid;
+            grid-area: icon;
+            place-content: center;
+            /* Removes line-box leading so slotted icon content sizes to its own intrinsic height. */
+            line-height: 0;
+            opacity: 0;
+
+            /* UI */
+            width: var(--input-toggle-symbol-size);
+            height: var(--input-toggle-symbol-size);
+            margin: var(--input-toggle-symbol-margin);
+            transition:
+              opacity var(--theme-form-transition-duration),
+              color var(--theme-form-transition-duration);
+
+            &.icon-on {
+              color: var(--toggle-switch-icon-on-color, var(--theme-on-surface));
+            }
+
+            &.icon-off {
+              color: var(--toggle-switch-icon-off-color, var(--theme-surface));
+            }
+
+            &.active {
+              opacity: 1;
+            }
           }
         }
       }
     }
   }
 }
-}
 </style>

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

@@ -75,7 +75,7 @@ export default {
     // Styling
     theme: {
       control: { type: "select" },
-      options: ["primary", "secondary", "tertiary", "ghost", "error", "success", "warning"],
+      options: ["default", "success", "error", "warning"],
       description: "Toggle switch theme",
       table: {
         category: "Styling",

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

@@ -83,7 +83,7 @@ export default {
     // Styling
     theme: {
       control: { type: "select" },
-      options: ["primary", "secondary", "tertiary", "ghost", "error", "success", "warning"],
+      options: ["default", "success", "error", "warning"],
       description: "Toggle switch theme",
       table: {
         category: "Styling",

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

@@ -64,7 +64,7 @@ export default {
     // Styling
     theme: {
       control: { type: "select" },
-      options: ["primary", "secondary", "tertiary", "ghost", "error", "success", "warning"],
+      options: ["default", "success", "error", "warning"],
       description: "Toggle switch theme",
       table: {
         category: "Styling",
@@ -243,7 +243,7 @@ export const InlineFormExample: StoryFn = () => ({
           name="darkMode"
           label="Dark mode"
           label-weight="normal"
-          theme="secondary"
+          theme="default"
         />
 
         <StorybookComponent