srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/05.forms/form-errors/InputError.vue

@@ -3,20 +3,25 @@
     :id
     class="input-error-message"
     data-theme="error"
-    :class="[inputVariant, elementClasses, { show: showError }, { detached: isDetached }]"
+    :class="elementClasses"
     :data-testid
-    :aria-hidden="!showError"
+    :data-input-variant="inputVariant"
+    :data-visible="showError ? '' : undefined"
+    :data-detached="isDetached ? '' : undefined"
+    :aria-hidden="showError ? undefined : 'true'"
   >
-    <div class="inner" :class="[{ show: showError }]">
-      <div class="inner-content">
-        <div class="inner-icon">
-          <Icon name="radix-icons:circle-backslash" class="icon" />
+    <div class="input-error-message-inner">
+      <div class="input-error-message-content">
+        <div class="input-error-message-icon-wrapper">
+          <Icon :name="icon" class="input-error-message-icon" aria-hidden="true" />
         </div>
-        <div class="message">
-          <ul v-if="isArray" class="message-list">
-            <li v-for="(message, index) in errorMessage" :key="index" class="message-list-item">{{ message }}</li>
+        <div class="input-error-message-text">
+          <ul v-if="isArray" class="input-error-message-list">
+            <li v-for="(message, index) in errorMessage" :key="index" class="input-error-message-list-item">
+              {{ message }}
+            </li>
           </ul>
-          <span v-else class="message-single">
+          <span v-else class="input-error-message-single">
             {{ errorMessage }}
           </span>
         </div>
@@ -34,41 +39,52 @@ interface Props {
   showError: boolean;
   id: string;
   styleClassPassthrough?: string | string[];
-  compact?: boolean;
   isDetached: boolean;
   inputVariant?: InputUiVariant;
+  icon?: string;
 }
 
 const props = withDefaults(defineProps<Props>(), {
   dataTestid: "inputError",
   styleClassPassthrough: () => [],
-  compact: false,
   inputVariant: "normal",
+  icon: "radix-icons:circle-backslash",
 });
 
-const isArray = computed(() => {
-  return Array.isArray(props.errorMessage);
-});
+const isArray = computed(() => Array.isArray(props.errorMessage));
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
 </script>
 
 <style lang="css">
 @layer components {
   .input-error-message {
+    --_text-color: var(--input-error-text-color, var(--input-error-color));
+    --_border-radius: var(--input-error-border-radius, var(--form-input-border-radius));
+    --_padding-inline: var(--input-error-padding-inline, 1.2rem);
+    --_padding-block-start: 1rem;
+    --_transition-duration: var(--input-error-transition-duration, var(--theme-form-transition-duration));
+
     grid-row: 2;
     grid-column: 1;
     display: grid;
     grid-template-rows: 0fr;
 
-    color: var(--input-error-color);
-    background-color: var(--theme-error-surface);
+    color: var(--_text-color);
+    background-color: var(--input-error-background-color, var(--theme-error-surface));
     opacity: 0;
 
     transition:
-      grid-template-rows var(--theme-form-transition-duration) linear,
-      opacity var(--theme-form-transition-duration) linear,
-      margin-block-start var(--theme-form-transition-duration) linear;
+      grid-template-rows var(--_transition-duration) linear,
+      opacity var(--_transition-duration) linear,
+      margin-block-start var(--_transition-duration) linear;
 
     transition-behavior: allow-discrete;
 
@@ -78,132 +94,95 @@ const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
 
     background-clip: padding-box;
 
-    translate: 0 calc(-1 * calc(var(--form-element-border-width) + var(--form-input-border-radius)));
+    translate: 0 calc(-1 * (var(--form-element-border-width) + var(--form-input-border-radius)));
 
     margin-block-start: var(--input-error-margin-block-start);
 
-    &.underlined {
-      outline-color: transparent;
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
     }
 
-    &.detached {
-      margin-block-start: 0rem;
-
-      border-top: var(--form-element-border-width) solid var(--theme-error-surface);
-      border-right: var(--form-element-border-width) solid var(--theme-error-surface);
-      border-bottom: var(--form-element-border-width) solid var(--red-08);
-      border-left: var(--form-element-border-width) solid var(--theme-error-surface);
+    &[data-input-variant="normal"] {
+      --_padding-block-start: 1.2rem;
+    }
 
-      border-radius: var(--form-input-border-radius);
+    &[data-detached] {
+      margin-block-start: 0rem;
+      border-radius: var(--_border-radius);
 
-      &.underlined {
+      &[data-input-variant="underlined"] {
         border-radius: 0;
       }
     }
 
-    &.show {
+    &[data-visible] {
       grid-template-rows: 1fr;
-      display: grid;
       opacity: 1;
 
-      border: var(--form-element-border-width) solid var(--theme-error-border);
-      outline: var(--form-element-outline-width) solid var(--theme-error-outline);
+      border: var(--form-element-border-width) solid var(--input-error-border-color, var(--theme-error-border));
+      outline: var(--form-element-outline-width) solid var(--input-error-outline-color, var(--theme-error-outline));
 
-      &:not(.underlined) {
-        border-bottom-left-radius: var(--form-input-border-radius);
-        border-bottom-right-radius: var(--form-input-border-radius);
+      &:not([data-input-variant="underlined"]) {
+        border-bottom-left-radius: var(--_border-radius);
+        border-bottom-right-radius: var(--_border-radius);
       }
 
-      &.detached {
-        margin-block-start: 2rem;
+      &[data-detached] {
+        margin-block-start: var(--input-error-detached-offset, 2rem);
       }
     }
 
-    .inner {
-      align-items: center;
-      overflow: hidden;
-
-      .inner-content {
-        display: flex;
-        align-items: center;
-
-        .inner-icon {
-          display: inline-block;
-          padding-left: 1.2rem;
-
-          .icon {
-            color: white;
-            transform: translateY(3px);
-          }
-        }
-
-        .message {
-          display: inline-block;
-          flex-grow: 1;
-          font-family: var(--font-family);
-          font-size: 1.6rem;
-          font-weight: 500;
-          padding-block: 1rem 1rem;
-          padding-inline: 1.2rem;
-
-          .message-single {
-            color: var(--input-error-color);
-          }
-
-          .message-list {
-            list-style-type: none;
-            padding-inline-start: 0;
-            margin-block-start: 0;
-            margin-block-end: 0;
-
-            .message-list-item {
-              color: white;
-            }
-
-            .message-list-item + .message-list-item {
-              margin-block-start: 0.6rem;
-            }
-          }
-        }
+    &:not([data-detached]) {
+      &[data-input-variant="normal"] .input-error-message-inner {
+        padding-block-start: var(--form-input-border-radius);
       }
-    }
 
-    /* Modifiers for input variants: */
-    &:is(.detached) {
-      &.normal {
-        .inner {
-          .inner-content {
-            .message {
-              padding-block: 1.2rem 1rem;
-            }
-          }
-        }
-      }
-    }
-
-    &:not(.detached) {
-      &.normal {
-        .inner {
-          padding-block-start: var(--form-input-border-radius);
-
-          .inner-content {
-            .message {
-              padding-block: 1.2rem 1rem;
-            }
-          }
-        }
-      }
-      &.underlined {
+      &[data-input-variant="underlined"] {
         outline-color: transparent;
-        .inner {
-          .inner-content {
-            .message {
-              padding-block: 1rem 1rem;
-            }
-          }
-        }
       }
     }
   }
+
+  .input-error-message-inner {
+    align-items: center;
+    overflow: hidden;
+  }
+
+  .input-error-message-content {
+    display: flex;
+    align-items: center;
+  }
+
+  .input-error-message-icon-wrapper {
+    display: inline-block;
+    padding-inline-start: var(--_padding-inline);
+  }
+
+  .input-error-message-icon {
+    color: var(--input-error-icon-color, var(--_text-color));
+    font-size: var(--input-error-icon-size, 1em);
+    transform: translateY(3px);
+  }
+
+  .input-error-message-text {
+    display: inline-block;
+    flex-grow: 1;
+    font-family: var(--input-error-font-family, var(--font-family));
+    font-size: var(--input-error-font-size, 1.6rem);
+    font-weight: var(--input-error-font-weight, 500);
+    padding-block: var(--input-error-padding-block-start, var(--_padding-block-start))
+      var(--input-error-padding-block-end, 1rem);
+    padding-inline: var(--_padding-inline);
+  }
+
+  .input-error-message-list {
+    list-style-type: none;
+    padding-inline-start: 0;
+    margin-block: 0;
+  }
+
+  .input-error-message-list-item + .input-error-message-list-item {
+    margin-block-start: var(--input-error-list-gap, 0.6rem);
+  }
 }
 </style>

package/app/components/05.forms/form-errors/stories/InputError.stories.ts

@@ -0,0 +1,125 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import StorybookComponent from "../InputError.vue";
+
+interface InputErrorStoryArgs {
+  id: string;
+  errorMessage: string | string[];
+  showError: boolean;
+  isDetached: boolean;
+  inputVariant: "normal" | "outlined" | "underlined";
+  icon: string;
+  styleClassPassthrough: string;
+}
+
+export default {
+  title: "Components/Forms/Form Errors/InputError",
+  component: StorybookComponent,
+  argTypes: {
+    id: { control: "text", table: { category: "Basic" } },
+    errorMessage: {
+      control: "object",
+      description: "A string, or an array of strings rendered as a list",
+      table: { category: "Basic" },
+    },
+    showError: { control: "boolean", table: { category: "State" } },
+    isDetached: {
+      control: "boolean",
+      description: "Detached: sits below the control with a gap. Attached: tucked under the control's bottom edge",
+      table: { category: "Layout" },
+    },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      table: { category: "Layout" },
+    },
+    icon: { control: "text", table: { category: "Content" } },
+    styleClassPassthrough: { control: "text", table: { category: "Styling" } },
+  },
+  args: {
+    id: "story-field-error-message",
+    errorMessage: "Please enter a valid email address",
+    showError: true,
+    isDetached: false,
+    inputVariant: "normal",
+    icon: "radix-icons:circle-backslash",
+    styleClassPassthrough: "",
+  },
+} as Meta<InputErrorStoryArgs>;
+
+const demoStyles = `
+  <component is="style">
+    .input-error-story-field {
+      display: grid;
+      grid-template-rows: auto auto;
+      max-width: 48rem;
+      margin: 3.6rem;
+    }
+    .input-error-story-control {
+      grid-row: 1;
+      grid-column: 1;
+      position: relative;
+      z-index: 1;
+      padding: 1.2rem;
+      font-size: 1.6rem;
+      background-color: var(--theme-input-surface);
+      color: var(--theme-text);
+      border: var(--form-element-border-width) solid var(--theme-border);
+      border-radius: var(--form-input-border-radius);
+    }
+    .input-error-story-field[data-invalid] .input-error-story-control {
+      border-color: var(--theme-error-border);
+    }
+    .input-error-story-field[data-variant="underlined"] .input-error-story-control {
+      border-radius: 0;
+      border-width: 0 0 var(--form-element-border-width);
+    }
+  </component>
+`;
+
+const Template: StoryFn<InputErrorStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    return { args };
+  },
+  template: `
+    <div>
+      ${demoStyles}
+      <div
+        class="input-error-story-field"
+        :data-invalid="args.showError ? '' : undefined"
+        :data-variant="args.inputVariant"
+      >
+        <div class="input-error-story-control">Stand-in form control</div>
+        <StorybookComponent
+          :id="args.id"
+          :error-message="args.errorMessage"
+          :show-error="args.showError"
+          :is-detached="args.isDetached"
+          :input-variant="args.inputVariant"
+          :icon="args.icon"
+          :style-class-passthrough="args.styleClassPassthrough"
+        ></StorybookComponent>
+      </div>
+    </div>
+  `,
+});
+
+export const Attached = Template.bind({});
+
+export const Detached = Template.bind({});
+Detached.args = { isDetached: true };
+
+export const MultipleMessages = Template.bind({});
+MultipleMessages.args = {
+  isDetached: true,
+  errorMessage: ["Password must be at least 12 characters", "Password must contain a number"],
+};
+
+export const Underlined = Template.bind({});
+Underlined.args = { inputVariant: "underlined" };
+
+export const Hidden = Template.bind({});
+Hidden.args = { showError: false };
+Hidden.parameters = {
+  docs: { description: { story: "Toggle `showError` to see the open/close animation." } },
+};

package/app/components/05.forms/form-errors/tests/InputError.spec.ts

@@ -1,15 +1,14 @@
-// https://nuxt.com/docs/getting-started/testing#unit-testing
+import { describe, it, expect } from "vitest";
 import type { VueWrapper } from "@vue/test-utils";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
 import ComponentUnderTest from "../InputError.vue";
 
 const initialPropsData = {
-  dataTestid: "inputError",
   errorMessage: "Hello World",
   showError: true,
   id: "testId",
   styleClassPassthrough: ["testClass"],
-  compact: false,
   isDetached: true,
 };
 
@@ -22,45 +21,97 @@ const wrapperFactory = (propsData = {}) => {
   });
 };
 
-describe("InputError Component", () => {
-  it("renders properly", async () => {
+describe("InputError", () => {
+  it("renders the root with id, testid, error theme and passthrough classes", async () => {
     wrapper = await wrapperFactory();
+    const root = wrapper.find(".input-error-message");
 
-    // Check the value of the data-testid attribute
-    const dataTestIdValue = wrapper.attributes("data-testid");
-    expect(dataTestIdValue).toBe("inputError");
+    expect(root.attributes("id")).toBe("testId");
+    expect(root.attributes("data-testid")).toBe("inputError");
+    expect(root.attributes("data-theme")).toBe("error");
+    expect(root.classes()).toContain("testClass");
+  });
+
+  it("marks itself visible and exposed to assistive tech when showError is true", async () => {
+    wrapper = await wrapperFactory();
+    const root = wrapper.find(".input-error-message");
+
+    expect(root.attributes("data-visible")).toBe("");
+    expect(root.attributes("aria-hidden")).toBeUndefined();
+  });
+
+  it("is hidden and aria-hidden when showError is false", async () => {
+    wrapper = await wrapperFactory({ showError: false });
+    const root = wrapper.find(".input-error-message");
+
+    expect(root.attributes("data-visible")).toBeUndefined();
+    expect(root.attributes("aria-hidden")).toBe("true");
+  });
+
+  it("reflects isDetached as data-detached", async () => {
+    wrapper = await wrapperFactory({ isDetached: true });
+    expect(wrapper.find(".input-error-message").attributes("data-detached")).toBe("");
+
+    await wrapper.setProps({ isDetached: false });
+    expect(wrapper.find(".input-error-message").attributes("data-detached")).toBeUndefined();
+  });
+
+  it("reflects inputVariant as data-input-variant, defaulting to normal", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".input-error-message").attributes("data-input-variant")).toBe("normal");
+
+    await wrapper.setProps({ inputVariant: "underlined" });
+    expect(wrapper.find(".input-error-message").attributes("data-input-variant")).toBe("underlined");
+  });
+
+  it("does not use collision-prone bare modifier classes", async () => {
+    wrapper = await wrapperFactory({ inputVariant: "underlined" });
+    const classes = wrapper.find(".input-error-message").classes();
+
+    expect(classes).not.toContain("show");
+    expect(classes).not.toContain("detached");
+    expect(classes).not.toContain("underlined");
+    expect(wrapper.find(".inner").exists()).toBe(false);
+    expect(wrapper.find(".message").exists()).toBe(false);
+  });
 
-    expect(wrapper.find("[data-testid]").classes()).toContain("testClass");
-    expect(wrapper.find("[data-testid]").classes()).toContain("show");
+  it("displays a single error message", async () => {
+    wrapper = await wrapperFactory();
+
+    expect(wrapper.find(".input-error-message-list").exists()).toBe(false);
+    expect(wrapper.find(".input-error-message-single").text()).toBe("Hello World");
   });
 
-  it("is not displayed by default", async () => {
-    const propData = {
-      showError: false,
-    };
-    wrapper = await wrapperFactory(propData);
+  it("displays an array of error messages as a list", async () => {
+    wrapper = await wrapperFactory({ errorMessage: ["Hello World", "Hello World 2"] });
+    const items = wrapper.findAll(".input-error-message-list-item");
 
-    expect(wrapper.find("[data-testid]").classes()).not.toContain("show");
+    expect(wrapper.find(".input-error-message-single").exists()).toBe(false);
+    expect(items).toHaveLength(2);
+    expect(items[0]!.text()).toBe("Hello World");
+    expect(items[1]!.text()).toBe("Hello World 2");
   });
 
-  it("is displays a single error message", async () => {
-    const propData = {
-      showError: true,
-    };
-    wrapper = await wrapperFactory(propData);
+  it("renders a decorative icon that can be overridden", async () => {
+    wrapper = await wrapperFactory();
+    const icon = wrapper.find(".input-error-message-icon");
+
+    expect(icon.exists()).toBe(true);
+    expect(icon.attributes("aria-hidden")).toBe("true");
+    expect(icon.html()).toContain("circle-backslash");
 
-    expect(wrapper.find(".message-list").exists()).toBe(false);
-    expect(wrapper.find(".message-single").text()).toContain("Hello World");
+    await wrapper.setProps({ icon: "radix-icons:exclamation-triangle" });
+    expect(wrapper.find(".input-error-message-icon").html()).toContain("exclamation-triangle");
   });
 
-  it("is displays a single error message", async () => {
-    const propData = {
-      errorMessage: ["Hello World", "Hello World 2"],
-    };
-    wrapper = await wrapperFactory(propData);
+  it("updates passthrough classes when the prop changes", async () => {
+    wrapper = await wrapperFactory();
+
+    await wrapper.setProps({ styleClassPassthrough: ["otherClass"] });
+    await nextTick();
 
-    expect(wrapper.find(".message-single").exists()).toBe(false);
-    expect(wrapper.find(".message-list .message-list-item:first-child").text()).toEqual("Hello World");
-    expect(wrapper.find(".message-list .message-list-item:last-child").text()).toEqual("Hello World 2");
+    const classes = wrapper.find(".input-error-message").classes();
+    expect(classes).toContain("otherClass");
+    expect(classes).not.toContain("testClass");
   });
 });

package/app/components/05.forms/form-field/CONSUMER-STYLING.md

@@ -0,0 +1,91 @@
+# FormField — Consumer Styling Guide
+
+`FormField` is a layout wrapper for one form control (typically an `*Field` component such as
+`InputTextWithLabel` or `InputNumberField`). It caps the field's width, centres it, optionally
+insets it from its container's edges with a gutter, and applies vertical spacing between fields.
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--form-field-max-width-narrow` | `400px` | Max width when `width="narrow"` (the default) |
+| `--form-field-max-width-medium` | `800px` | Max width when `width="medium"` |
+| `--form-field-max-width-wide` | `1200px` | Max width when `width="wide"` |
+| `--form-field-gutter-width` | `1.6rem` | Inline inset on each side when `has-gutter` is on (the default) |
+| `--form-field-margin-block` | `var(--field-margin-block)` (`0 1.6rem`) | Vertical spacing around the field |
+| `--form-field-background-color` | `transparent` | Wrapper background |
+| `--form-field-border-radius` | `0.4rem` | Wrapper corner radius (only visible once a background is set) |
+
+`--field-margin-block` is the shared form-layout token from
+`assets/styles/setup/04.elements/forms/01.field-layout-container-level.css`; overriding it
+changes the spacing of every `FormField` at once, `--form-field-margin-block` changes only the
+ones in scope.
+
+Private tokens (not public API): `--_max-width` (swapped by the `width` prop) and
+`--_gutter-width` (swapped by `has-gutter`).
+
+---
+
+## State hooks
+
+The root `.form-field` element carries these attributes, which are safe to target in consumer CSS:
+
+| Attribute | When |
+|---|---|
+| `data-width="narrow" \| "medium" \| "wide"` | Always, mirrors the `width` prop |
+| `data-has-gutter` | `has-gutter` is `true` |
+| `data-invalid` | `field-has-error` is `true`. Also switches every descendant to the red error theme, via the global `:where([data-invalid])` theming rules |
+
+> **Changed 2026-09-26**: width/gutter used to be bare classes (`.narrow`, `.medium`, `.wide`,
+> `.has-gutter`) and `data-invalid` rendered as `"true"`. Update any `.form-field.wide` selector to
+> `.form-field[data-width="wide"]`; `[data-invalid]` selectors keep working.
+
+---
+
+## Global theming
+
+```css
+:where(html) {
+  --form-field-max-width-narrow: 48rem;
+  --form-field-gutter-width: 2.4rem;
+}
+```
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<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`.
+
+### One instance
+
+```vue
+<FormField width="wide" style="--form-field-background-color: var(--slate-01);">
+  <InputTextWithLabel ... />
+</FormField>
+```
+
+Or scoped by a page/section wrapper class:
+
+```css
+.contact-page {
+  .form-field {
+    --form-field-margin-block: 0 2.4rem;
+  }
+
+  .form-field[data-invalid] {
+    --form-field-background-color: var(--red-01);
+  }
+}
+```
+
+---
+
+## Class passthrough
+
+`:style-class-passthrough` (string or string array) adds classes to the root `.form-field` element.
+