srcdev-nuxt-components 9.4.11 → 9.5.0

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

@@ -0,0 +1,177 @@
+# InputDescription — Consumer Styling Guide
+
+`InputDescription` is the help text rendered between the label and the control by every `*Field`
+wrapper (`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`,
+`InputTextareaWithLabel`, `InputRangeDefault`, `InputTextAsNumberWithLabel`, `SingleCheckbox`,
+`MultipleCheckboxes`, `MultipleRadiobuttons`) when you pass it a `descriptionText` or
+`descriptionHtml` slot. With neither slot it renders nothing.
+
+## Public token API
+
+Every token is consumed as `var(--input-description-*, {default})` and none is declared on the
+element itself, so set them on any ancestor (or `:root`) and they inherit down.
+
+### Panel (root `.input-description`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-description-color` | `inherit` | Text colour of both slots |
+| `--input-description-background-color` | `transparent` | Background |
+| `--input-description-margin-block` | `0` | Block margin (space from the label and control) |
+| `--input-description-margin-inline` | `0` | Inline margin |
+| `--input-description-padding-block` | `0` | Block padding |
+| `--input-description-padding-inline` | `0` | Inline padding |
+| `--input-description-border` | `0` | Border shorthand, e.g. `0.1rem solid var(--theme-border)` |
+| `--input-description-border-radius` | `0` | Corner radius |
+| `--input-description-outline` | `0` | Outline shorthand |
+| `--input-description-outline-offset` | `0` | Outline offset |
+
+These match `FormFieldset`'s `--form-fieldset-*` panel tokens.
+
+### Slots (`.input-description-html` and `.input-description-text`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--input-description-slot-margin-block-start` | `0.4rem` | Space above each slot's wrapper |
+| `--input-description-slot-margin-block-end` | `0.8rem` | Space below each slot's wrapper |
+| `--input-description-slot-margin-inline` | `0` | Inline margin of each slot's wrapper |
+| `--input-description-font-size` | `var(--step-4)` | Font size of the `descriptionText` paragraph |
+| `--input-description-line-height` | `var(--step-4)` | Line height of the `descriptionText` paragraph. The default equals the font size, which is tight for wrapping text, so `1.5` is a good override for long descriptions |
+
+With default (unpadded) panel tokens, the slot margins collapse through the root, so they are what
+spaces the description from the label and control. Beyond these the `descriptionHtml` wrapper
+sets nothing: style your own markup inside it directly.
+
+No private tokens.
+
+> **Changed 2026-09-26**: the text colour used to read `--form-description-color`, which nothing
+> ever declared, so it always inherited. Use `--input-description-color` instead.
+
+---
+
+## State hooks
+
+| Attribute on `.input-description` | When |
+|---|---|
+| `data-input-variant="normal" \| "outlined" \| "underlined"` | Always, mirrors the field's `input-variant` (not passed by `InputRangeDefault`, which has no variants, so it stays `normal` there) |
+| `data-invalid` | The field has an error |
+
+Inner elements: `.input-description-html` (div), `.input-description-text` (p).
+
+---
+
+## Global theming
+
+Every field's description at once, from an app-level stylesheet (e.g. `app/assets/styles/main.css`):
+
+```css
+:where(html) {
+  --input-description-color: var(--theme-input-placeholder);
+  --input-description-line-height: 1.5;
+}
+```
+
+---
+
+## Local overrides
+
+Set the tokens on an element you own that wraps the field(s): they inherit down into the
+description. Keep these blocks **unlayered** (no `@layer ...` wrapper) so they beat the library's
+`@layer components` styles. Full background in `.claude/skills/component-local-style-override.md`.
+
+### Page or section
+
+```vue
+<template>
+  <div class="contact-page-content">
+    <InputTextWithLabel v-model="email" name="email" label="Email">
+      <template #descriptionText>We'll only use this for your booking confirmation</template>
+    </InputTextWithLabel>
+  </div>
+</template>
+
+<style>
+.contact-page-content {
+  --input-description-font-size: 1.4rem;
+  --input-description-slot-margin-block-end: 1.2rem;
+
+  .input-description[data-invalid] {
+    --input-description-color: var(--theme-error-border);
+  }
+}
+</style>
+```
+
+### One field
+
+The wrappers don't forward `style-class-passthrough` to the description, but a plain `class` on
+the wrapper itself lands on its root element, which is an ancestor of the description:
+
+```vue
+<InputTextWithLabel class="email-field" v-model="email" name="email" label="Email">
+  <template #descriptionText>We'll only use this for your booking confirmation</template>
+</InputTextWithLabel>
+
+<style>
+.email-field {
+  --input-description-color: var(--theme-accent);
+}
+</style>
+```
+
+### If your page or component uses `<style scoped>`
+
+This library's components use plain (unscoped) styles, so this only matters when the overriding
+file in **your** app is scoped. Vue then adds your file's scope attribute to every selector, and
+the description's elements don't carry it.
+
+Tokens set on your own element still work, because your element carries the attribute and custom
+properties inherit down. Selectors that reach **into** the description
+(`.input-description[data-invalid]`, `.input-description-text`) won't match. Wrap them in
+`:deep()`, or use an unscoped `<style>` block as in the examples above:
+
+```vue
+<style scoped>
+.contact-page-content {
+  --input-description-font-size: 1.4rem; /* works as-is */
+
+  :deep(.input-description[data-invalid]) {
+    --input-description-color: var(--theme-error-border);
+  }
+}
+</style>
+```
+
+---
+
+## Recipe: panel / callout
+
+Once the root has padding or a border, the slot margins no longer collapse through it and would
+show as uneven space inside the panel. Zero them and space the panel with the root margins:
+
+```css
+.booking-form {
+  --input-description-background-color: var(--theme-surface-subtle);
+  --input-description-border: 0.1rem solid var(--theme-border);
+  --input-description-border-radius: 0.6rem;
+  --input-description-margin-block: 0.4rem 0.8rem;
+  --input-description-padding-block: 0.8rem;
+  --input-description-padding-inline: 1.2rem;
+  --input-description-slot-margin-block-start: 0;
+  --input-description-slot-margin-block-end: 0;
+
+  /* only needed when a field uses both slots */
+  .input-description-html + .input-description-text {
+    margin-block-start: 0.4rem;
+  }
+}
+```
+
+---
+
+## Class passthrough
+
+`:style-class-passthrough` (string or string array) adds classes to the root
+`.input-description` element. It's only reachable when you render `InputDescription` directly in
+a custom field wrapper: the library's own wrappers pass `input-text-description` (no styles
+attached) and don't forward yours. Use a `class` on the wrapper instead (see **One field** above).

package/app/components/05.forms/input-description/InputDescription.vue

@@ -1,55 +1,76 @@
 <template>
-  <div v-if="showDescription" :id="descriptionId" class="input-description" :class="[elementClasses]">
-    <div v-if="hasDescriptionHtml" class="input-description-html">
+  <div
+    v-if="showDescription()"
+    :id="descriptionId || undefined"
+    class="input-description"
+    :class="elementClasses"
+    :data-input-variant="inputVariant"
+    :data-invalid="fieldHasError ? '' : undefined"
+  >
+    <div v-if="slots.descriptionHtml" class="input-description-html">
       <slot name="descriptionHtml"></slot>
     </div>
-    <p v-if="hasDescriptionText" class="input-description-text">
+    <p v-if="slots.descriptionText" class="input-description-text">
       <slot name="descriptionText"></slot>
     </p>
   </div>
 </template>
 
 <script setup lang="ts">
-import type { FormUiTheme, InputUiVariant } from "~/types/forms/types.forms";
+import type { InputUiVariant } from "~/types/forms/types.forms";
 
 interface Props {
-  id: string;
   descriptionId?: string;
   fieldHasError?: boolean;
-  styleClassPassthrough?: string | string[];
-  theme?: FormUiTheme;
   inputVariant?: InputUiVariant;
+  styleClassPassthrough?: string | string[];
 }
 
 const props = withDefaults(defineProps<Props>(), {
   descriptionId: "",
   fieldHasError: false,
-  styleClassPassthrough: () => [],
-  theme: "default",
   inputVariant: "normal",
+  styleClassPassthrough: () => [],
 });
 
 const slots = useSlots();
-const hasDescriptionHtml = computed(() => slots.descriptionHtml);
-const hasDescriptionText = computed(() => slots.descriptionText);
-const showDescription = computed(() => hasDescriptionHtml.value || hasDescriptionText.value);
+const showDescription = () => Boolean(slots.descriptionHtml || slots.descriptionText);
 
-// const descriptionId = `${props.id}-description`;
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
 </script>
+
 <style lang="css">
 @layer components {
-.input-description {
-  .input-description-html {
-    margin-block: 0.4rem 0.8rem;
-  }
-  .input-description-text {
-    color: var(--form-description-color);
-    font-size: var(--step-4);
-    margin-block: 0.4rem 0.8rem;
-    line-height: var(--step-4);
+  .input-description {
+    color: var(--input-description-color, inherit);
+    background-color: var(--input-description-background-color, transparent);
+    margin-block: var(--input-description-margin-block, 0);
+    margin-inline: var(--input-description-margin-inline, 0);
+    padding-block: var(--input-description-padding-block, 0);
+    padding-inline: var(--input-description-padding-inline, 0);
+    border: var(--input-description-border, 0);
+    border-radius: var(--input-description-border-radius, 0);
+    outline: var(--input-description-outline, 0);
+    outline-offset: var(--input-description-outline-offset, 0);
+
+    .input-description-html,
+    .input-description-text {
+      margin-block: var(--input-description-slot-margin-block-start, 0.4rem)
+        var(--input-description-slot-margin-block-end, 0.8rem);
+      margin-inline: var(--input-description-slot-margin-inline, 0);
+    }
+
+    .input-description-text {
+      font-size: var(--input-description-font-size, var(--step-4));
+      line-height: var(--input-description-line-height, var(--step-4));
+    }
   }
 }
-}
 </style>

package/app/components/05.forms/input-description/stories/InputDescription.stories.ts

@@ -0,0 +1,160 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
+import StorybookComponent from "../InputDescription.vue";
+import type { InputUiVariant } from "~/types/forms/types.forms";
+
+interface InputDescriptionStoryArgs {
+  descriptionId: string;
+  fieldHasError: boolean;
+  inputVariant: InputUiVariant;
+  styleClassPassthrough: string;
+  descriptionText: string;
+  descriptionHtml: string;
+}
+
+export default {
+  title: "Components/Forms/Input Description/InputDescription",
+  component: StorybookComponent,
+  argTypes: {
+    descriptionId: {
+      control: "text",
+      description: "Rendered as the root id, the target of the control's aria-describedby",
+      table: { category: "Basic" },
+    },
+    descriptionText: {
+      control: "text",
+      description: "descriptionText slot: plain help text, rendered in a <p>",
+      table: { category: "Slots" },
+    },
+    descriptionHtml: {
+      control: "text",
+      description: "descriptionHtml slot: rich markup, rendered in a <div> above the text slot",
+      table: { category: "Slots" },
+    },
+    fieldHasError: {
+      control: "boolean",
+      description: "Rendered as data-invalid, a styling hook only",
+      table: { category: "State" },
+    },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      description: "Rendered as data-input-variant, a styling hook only",
+      table: { category: "Layout" },
+    },
+    styleClassPassthrough: { control: "text", table: { category: "Styling" } },
+  },
+  args: {
+    descriptionId: "story-field-description",
+    fieldHasError: false,
+    inputVariant: "normal",
+    styleClassPassthrough: "",
+    descriptionText: "We'll only use this to send your booking confirmation.",
+    descriptionHtml: "",
+  },
+} as Meta<InputDescriptionStoryArgs>;
+
+const Template: StoryFn<InputDescriptionStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const componentArgs = computed(() => {
+      const { descriptionText: _text, descriptionHtml: _html, ...rest } = args;
+      return rest;
+    });
+    return { args, componentArgs };
+  },
+  template: `
+    <div style="max-width: 48rem; margin: 3.6rem; font-size: 1.6rem;">
+      <label for="story-field" style="display: block; font-weight: 700;">Email address</label>
+      <StorybookComponent v-bind="componentArgs">
+        <template v-if="args.descriptionHtml" #descriptionHtml><span v-html="args.descriptionHtml"></span></template>
+        <template v-if="args.descriptionText" #descriptionText>{{ args.descriptionText }}</template>
+      </StorybookComponent>
+      <input
+        id="story-field"
+        type="email"
+        :aria-describedby="args.descriptionText || args.descriptionHtml ? args.descriptionId : undefined"
+        style="width: 100%; padding: 1.2rem; font-size: 1.6rem;"
+      />
+    </div>
+  `,
+});
+
+export const TextOnly = Template.bind({});
+
+export const HtmlOnly = Template.bind({});
+HtmlOnly.args = {
+  descriptionText: "",
+  descriptionHtml: "Password must contain:<ul><li>At least 12 characters</li><li>One number</li></ul>",
+};
+
+export const TextAndHtml = Template.bind({});
+TextAndHtml.args = {
+  descriptionHtml: "<strong>Tip:</strong> use your work address if you have one.",
+};
+
+export const Empty = Template.bind({});
+Empty.args = { descriptionText: "", descriptionHtml: "" };
+Empty.parameters = {
+  docs: { description: { story: "With neither slot provided nothing is rendered, so no empty element or id is left behind." } },
+};
+
+export const CustomTokens = Template.bind({});
+CustomTokens.args = { styleClassPassthrough: "input-description-story-tokens" };
+CustomTokens.decorators = [
+  () => ({
+    template: `
+      <div>
+        <component is="style">
+          .input-description-story-tokens {
+            --input-description-color: var(--theme-input-placeholder);
+            --input-description-font-size: 1.4rem;
+            --input-description-line-height: 1.5;
+            --input-description-slot-margin-block-start: 0.2rem;
+            --input-description-slot-margin-block-end: 1.2rem;
+          }
+        </component>
+        <story />
+      </div>
+    `,
+  }),
+];
+
+export const Panel = Template.bind({});
+Panel.args = {
+  styleClassPassthrough: "input-description-story-panel",
+  descriptionHtml: "<strong>Tip:</strong> use your work address if you have one.",
+};
+Panel.parameters = {
+  docs: {
+    description: {
+      story:
+        "Callout styling via the root tokens. The slot margins are zeroed so the panel's padding is even, and the root margins space the panel from the label and control instead.",
+    },
+  },
+};
+Panel.decorators = [
+  () => ({
+    template: `
+      <div>
+        <component is="style">
+          .input-description-story-panel {
+            --input-description-background-color: var(--theme-surface-subtle);
+            --input-description-border: 0.1rem solid var(--theme-border);
+            --input-description-border-radius: 0.6rem;
+            --input-description-margin-block: 0.4rem 0.8rem;
+            --input-description-padding-block: 0.8rem;
+            --input-description-padding-inline: 1.2rem;
+            --input-description-slot-margin-block-start: 0;
+            --input-description-slot-margin-block-end: 0;
+            --input-description-line-height: 1.5;
+          }
+          .input-description-story-panel .input-description-html + .input-description-text {
+            margin-block-start: 0.4rem;
+          }
+        </component>
+        <story />
+      </div>
+    `,
+  }),
+];