@aleph-alpha/ui-library 1.16.1 → 1.17.0

package/src/components/UiField/UiField.stories.ts

@@ -12,6 +12,8 @@ import {
   UiFieldTitle,
 } from '.';
 import { UiCheckbox } from '../UiCheckbox';
+import { UiChip } from '../UiChip';
+import { UiIcon } from '../UiIcon';
 import { UiInput } from '../UiInput';
 import { UiRadioGroup, UiRadioGroupItem } from '../UiRadioGroup';
 import {
@@ -38,13 +40,24 @@ const meta: Meta<typeof UiField> = {
   argTypes: {
     orientation: {
       control: 'select',
-      options: ['vertical', 'horizontal', 'responsive'],
+      options: ['vertical', 'responsive'],
       description:
         'Layout orientation of the field. Use `responsive` to switch layout based on viewport size.',
     },
+    descriptionPlacement: {
+      control: 'select',
+      options: ['under-label', 'under-input'],
+      description: 'Where the description is placed relative to the field layout.',
+    },
+    descriptionCheckbox: {
+      control: 'boolean',
+      description: 'When true, the child UiFieldDescription renders with a checkbox.',
+    },
   },
   args: {
     orientation: 'vertical',
+    descriptionPlacement: 'under-input',
+    descriptionCheckbox: false,
   },
 };
 
@@ -97,11 +110,15 @@ export const Default: Story = {
       return { args, value, errors };
     },
     template: `
-      <UiField :orientation="args.orientation">
+      <UiField
+        :orientation="args.orientation"
+        :description-placement="args.descriptionPlacement"
+        :description-checkbox="args.descriptionCheckbox"
+      >
         <UiFieldLabel for="email">Email</UiFieldLabel>
+        <UiFieldDescription>We'll never share your email.</UiFieldDescription>
         <UiFieldContent>
           <UiInput id="email" v-model="value" name="email" placeholder="name@company.com" />
-          <UiFieldDescription>We'll never share your email.</UiFieldDescription>
           <UiFieldError :errors="errors" />
         </UiFieldContent>
       </UiField>
@@ -112,6 +129,127 @@ export const Default: Story = {
   },
 };
 
+const descriptionWithCheckboxTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiField,
+  UiFieldLabel,
+  UiFieldContent,
+  UiFieldDescription,
+  UiInput,
+} from '@aleph-alpha/ui-library'
+
+const value = ref('')
+const subscribe = ref(false)
+</script>
+
+<template>
+  <UiField>
+    <UiFieldLabel for="email">Email</UiFieldLabel>
+    <UiFieldContent>
+      <UiInput id="email" v-model="value" name="email" placeholder="name@company.com" />
+      <UiFieldDescription variant="input" v-model="subscribe" name="newsletter">
+        Subscribe to our newsletter
+      </UiFieldDescription>
+    </UiFieldContent>
+  </UiField>
+</template>`;
+
+/**
+ * Description with an inline checkbox (`variant="input"`).
+ * Useful for opt-in toggles tied to a field (e.g. newsletter subscription, terms agreement).
+ */
+export const DescriptionWithCheckbox: Story = {
+  render: () => ({
+    components: {
+      UiField,
+      UiFieldContent,
+      UiFieldDescription,
+      UiFieldLabel,
+      UiInput,
+    },
+    setup() {
+      const value = ref('');
+      const subscribe = ref(false);
+      return { value, subscribe };
+    },
+    template: `
+      <UiField>
+        <UiFieldLabel for="email">Email</UiFieldLabel>
+        <UiFieldContent>
+          <UiInput id="email" v-model="value" name="email" placeholder="name@company.com" />
+          <UiFieldDescription variant="input" v-model="subscribe" name="newsletter">
+            Subscribe to our newsletter
+          </UiFieldDescription>
+        </UiFieldContent>
+      </UiField>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: { source: { code: descriptionWithCheckboxTemplateSource } },
+  },
+};
+
+const withLabelInfoTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiField,
+  UiFieldLabel,
+  UiFieldContent,
+  UiFieldDescription,
+  UiInput,
+} from '@aleph-alpha/ui-library'
+
+const value = ref('')
+</script>
+
+<template>
+  <UiField>
+    <UiFieldLabel for="api-key" tooltip="Your unique API key for authentication.">
+      API Key
+    </UiFieldLabel>
+    <UiFieldContent>
+      <UiInput id="api-key" v-model="value" name="apiKey" placeholder="sk-..." />
+      <UiFieldDescription>Keep this secret and do not share it.</UiFieldDescription>
+    </UiFieldContent>
+  </UiField>
+</template>`;
+
+/**
+ * Label with an interactive info tooltip icon.
+ * Pass a `tooltip` prop to `UiFieldLabel` to render a ghost icon button with a tooltip.
+ */
+export const WithLabelInfo: Story = {
+  render: (args) => ({
+    components: {
+      UiField,
+      UiFieldContent,
+      UiFieldDescription,
+      UiFieldLabel,
+      UiInput,
+    },
+    setup() {
+      const value = ref('');
+      return { args, value };
+    },
+    template: `
+      <UiField :orientation="args.orientation">
+        <UiFieldLabel for="api-key" tooltip="Your unique API key for authentication.">
+          API Key
+        </UiFieldLabel>
+        <UiFieldContent>
+          <UiInput id="api-key" v-model="value" name="apiKey" placeholder="sk-..." />
+          <UiFieldDescription>Keep this secret and do not share it.</UiFieldDescription>
+        </UiFieldContent>
+      </UiField>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: withLabelInfoTemplateSource } },
+  },
+};
+
 const withErrorTemplateSource = `<script setup lang="ts">
 import { ref } from 'vue'
 import {
@@ -260,7 +398,157 @@ export const Group: Story = {
   },
 };
 
-const horizontalOrientationTemplateSource = `<script setup lang="ts">
+const chipGroupFieldTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  UiChip,
+  UiField,
+  UiFieldContent,
+  UiFieldDescription,
+  UiFieldLabel,
+  UiIcon,
+} from '@aleph-alpha/ui-library'
+
+const chips = ref([
+  'Data Analysis',
+  'Report Generation',
+  'Workflow Automation',
+  'Predictive Modeling',
+  'Sentiment Analysis',
+  'Risk Management',
+  'Fraud Detection',
+])
+
+const selectedAddChip = ref(false)
+
+const ChipIcon = {
+  components: { UiIcon },
+  template: '<UiIcon name="tag" :size="14" />',
+}
+
+const AddIcon = {
+  components: { UiIcon },
+  template: '<UiIcon name="plus" :size="14" />',
+}
+
+function removeChip(label: string) {
+  chips.value = chips.value.filter((chip) => chip !== label)
+}
+</script>
+
+<template>
+  <UiField>
+    <UiFieldLabel for="focus-areas">Focus Areas</UiFieldLabel>
+    <UiFieldContent>
+      <div id="focus-areas" class="flex flex-wrap items-center gap-2">
+        <UiChip
+          v-for="chip in chips"
+          :key="chip"
+          variant="removable"
+          :start-icon="ChipIcon"
+          @remove="removeChip(chip)"
+        >
+          {{ chip }}
+        </UiChip>
+
+        <UiChip
+          v-model="selectedAddChip"
+          variant="removable"
+          selectable
+          :start-icon="AddIcon"
+          remove-label="Remove add action"
+        >
+          Add
+        </UiChip>
+      </div>
+      <UiFieldDescription>
+        Chip group inside a field. Use Tab to navigate interactive chip actions in order.
+      </UiFieldDescription>
+    </UiFieldContent>
+  </UiField>
+</template>`;
+
+/**
+ * Field with a chip group value area (Figma chips-group style).
+ * Demonstrates removable chips and an interactive "Add" chip in a field context.
+ */
+export const ChipGroup: Story = {
+  render: () => ({
+    components: {
+      UiChip,
+      UiField,
+      UiFieldContent,
+      UiFieldDescription,
+      UiFieldLabel,
+      UiIcon,
+    },
+    setup() {
+      const chips = ref([
+        'Data Analysis',
+        'Report Generation',
+        'Workflow Automation',
+        'Predictive Modeling',
+        'Sentiment Analysis',
+        'Risk Management',
+        'Fraud Detection',
+      ]);
+      const selectedAddChip = ref(false);
+
+      const ChipIcon = {
+        components: { UiIcon },
+        template: '<UiIcon name="tag" :size="14" />',
+      };
+
+      const AddIcon = {
+        components: { UiIcon },
+        template: '<UiIcon name="plus" :size="14" />',
+      };
+
+      function removeChip(label: string) {
+        chips.value = chips.value.filter((chip) => chip !== label);
+      }
+
+      return { chips, selectedAddChip, ChipIcon, AddIcon, removeChip };
+    },
+    template: `
+      <UiField>
+        <UiFieldLabel for="focus-areas">Focus Areas</UiFieldLabel>
+        <UiFieldContent>
+          <div id="focus-areas" class="flex flex-wrap items-center gap-2">
+            <UiChip
+              v-for="chip in chips"
+              :key="chip"
+              variant="removable"
+              :start-icon="ChipIcon"
+              @remove="removeChip(chip)"
+            >
+              {{ chip }}
+            </UiChip>
+
+            <UiChip
+              v-model="selectedAddChip"
+              variant="removable"
+              selectable
+              :start-icon="AddIcon"
+              remove-label="Remove add action"
+            >
+              Add
+            </UiChip>
+          </div>
+          <UiFieldDescription>
+            Chip group inside a field. Use Tab to navigate interactive chip actions in order.
+          </UiFieldDescription>
+        </UiFieldContent>
+      </UiField>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: { source: { code: chipGroupFieldTemplateSource } },
+  },
+};
+
+const responsiveOrientationInlineTemplateSource = `<script setup lang="ts">
 import { ref } from 'vue'
 import {
   UiField,
@@ -274,7 +562,7 @@ const value = ref('')
 </script>
 
 <template>
-  <UiField orientation="horizontal">
+  <UiField orientation="responsive">
     <UiFieldLabel for="username">Username</UiFieldLabel>
     <UiFieldContent>
       <UiInput id="username" v-model="value" name="username" placeholder="shadcn" />
@@ -284,11 +572,11 @@ const value = ref('')
 </template>`;
 
 /**
- * Field with horizontal layout.
+ * Responsive layout: horizontal by default, collapses to vertical on small screens.
  * Useful when you want labels aligned on the left and controls on the right.
  */
-export const HorizontalOrientation: Story = {
-  args: { orientation: 'horizontal' },
+export const ResponsiveInline: Story = {
+  args: { orientation: 'responsive' },
   render: (args) => ({
     components: {
       UiField,
@@ -312,7 +600,7 @@ export const HorizontalOrientation: Story = {
     `,
   }),
   parameters: {
-    docs: { source: { code: horizontalOrientationTemplateSource } },
+    docs: { source: { code: responsiveOrientationInlineTemplateSource } },
   },
 };
 
@@ -652,7 +940,7 @@ const enabled = ref(true)
 </script>
 
 <template>
-  <UiField orientation="horizontal">
+  <UiField orientation="responsive">
     <UiCheckbox id="notifications" v-model="enabled" name="notifications" />
     <UiFieldContent>
       <UiFieldLabel for="notifications">Enable notifications</UiFieldLabel>
@@ -663,7 +951,7 @@ const enabled = ref(true)
 
 /**
  * Checkbox field layout (checkbox + text content).
- * The checkbox is a direct child of `UiField` so the horizontal styles can align it nicely.
+ * The checkbox is a direct child of `UiField` so the responsive styles can align it nicely.
  */
 export const Checkbox: Story = {
   render: () => ({
@@ -673,7 +961,7 @@ export const Checkbox: Story = {
       return { enabled };
     },
     template: `
-      <UiField orientation="horizontal">
+      <UiField orientation="responsive">
         <UiCheckbox id="notifications" v-model="enabled" name="notifications" />
         <UiFieldContent>
           <UiFieldLabel for="notifications">Enable notifications</UiFieldLabel>
@@ -702,7 +990,7 @@ const enabled = ref(false)
 </script>
 
 <template>
-  <UiField orientation="horizontal">
+  <UiField orientation="responsive">
     <UiSwitch id="airplane" v-model="enabled" name="airplane" />
     <UiFieldContent>
       <UiFieldLabel for="airplane">Airplane mode</UiFieldLabel>
@@ -722,7 +1010,7 @@ export const Switch: Story = {
       return { enabled };
     },
     template: `
-      <UiField orientation="horizontal">
+      <UiField orientation="responsive">
         <UiSwitch id="airplane" v-model="enabled" name="airplane" />
         <UiFieldContent>
           <UiFieldLabel for="airplane">Airplane mode</UiFieldLabel>
@@ -761,7 +1049,7 @@ const plan = ref('pro')
       <UiFieldLegend variant="label">Choose your plan</UiFieldLegend>
 
       <UiRadioGroup v-model="plan" name="plan">
-        <UiField orientation="horizontal">
+        <UiField orientation="responsive">
           <UiRadioGroupItem id="plan-free" value="free" />
           <UiFieldContent>
             <label for="plan-free" class="text-sm font-medium">Free</label>
@@ -769,7 +1057,7 @@ const plan = ref('pro')
           </UiFieldContent>
         </UiField>
 
-        <UiField orientation="horizontal">
+        <UiField orientation="responsive">
           <UiRadioGroupItem id="plan-pro" value="pro" />
           <UiFieldContent>
             <label for="plan-pro" class="text-sm font-medium">Pro</label>
@@ -777,7 +1065,7 @@ const plan = ref('pro')
           </UiFieldContent>
         </UiField>
 
-        <UiField orientation="horizontal" data-disabled="true">
+        <UiField orientation="responsive" data-disabled="true">
           <UiRadioGroupItem id="plan-enterprise" value="enterprise" disabled />
           <UiFieldContent>
             <label for="plan-enterprise" class="text-sm font-medium text-muted-foreground">Enterprise</label>
@@ -816,7 +1104,7 @@ export const RadioGroupInFieldSet: Story = {
           <UiFieldLegend variant="label">Choose your plan</UiFieldLegend>
 
           <UiRadioGroup v-model="plan" name="plan">
-            <UiField orientation="horizontal">
+            <UiField orientation="responsive">
               <UiRadioGroupItem id="plan-free" value="free" />
               <UiFieldContent>
                 <label for="plan-free" class="text-sm font-medium">Free</label>
@@ -824,7 +1112,7 @@ export const RadioGroupInFieldSet: Story = {
               </UiFieldContent>
             </UiField>
 
-            <UiField orientation="horizontal">
+            <UiField orientation="responsive">
               <UiRadioGroupItem id="plan-pro" value="pro" />
               <UiFieldContent>
                 <label for="plan-pro" class="text-sm font-medium">Pro</label>
@@ -832,7 +1120,7 @@ export const RadioGroupInFieldSet: Story = {
               </UiFieldContent>
             </UiField>
 
-            <UiField orientation="horizontal" data-disabled="true">
+            <UiField orientation="responsive" data-disabled="true">
               <UiRadioGroupItem id="plan-enterprise" value="enterprise" disabled />
               <UiFieldContent>
                 <label for="plan-enterprise" class="text-sm font-medium text-muted-foreground">Enterprise</label>
@@ -1006,14 +1294,14 @@ const email = ref(false)
       </UiFieldDescription>
 
       <UiFieldGroup data-slot="checkbox-group">
-        <UiField orientation="horizontal">
+        <UiField orientation="responsive">
           <UiCheckbox id="push-tasks" v-model="push" name="push-tasks" />
           <UiFieldLabel for="push-tasks" class="font-normal">
             Push notifications
           </UiFieldLabel>
         </UiField>
 
-        <UiField orientation="horizontal">
+        <UiField orientation="responsive">
           <UiCheckbox id="email-tasks" v-model="email" name="email-tasks" />
           <UiFieldLabel for="email-tasks" class="font-normal">
             Email notifications
@@ -1054,14 +1342,14 @@ export const CheckboxGroup: Story = {
           </UiFieldDescription>
 
           <UiFieldGroup data-slot="checkbox-group">
-            <UiField orientation="horizontal">
+            <UiField orientation="responsive">
               <UiCheckbox id="push-tasks" v-model="push" name="push-tasks" />
               <UiFieldLabel for="push-tasks" class="font-normal">
                 Push notifications
               </UiFieldLabel>
             </UiField>
 
-            <UiField orientation="horizontal">
+            <UiField orientation="responsive">
               <UiCheckbox id="email-tasks" v-model="email" name="email-tasks" />
               <UiFieldLabel for="email-tasks" class="font-normal">
                 Email notifications
@@ -1106,29 +1394,31 @@ const message = ref('')
         <UiFieldDescription>Fill in your profile information.</UiFieldDescription>
         <UiFieldSeparator />
         <UiFieldGroup>
-          <UiField orientation="responsive">
+          <UiField orientation="responsive" description-placement="under-label">
+            <UiFieldLabel for="profile-name" tooltip="Used on your public profile page.">
+              Name
+            </UiFieldLabel>
+            <UiFieldDescription>Provide your full name for identification</UiFieldDescription>
             <UiFieldContent>
-              <UiFieldLabel for="profile-name">Name</UiFieldLabel>
-              <UiFieldDescription>Provide your full name for identification</UiFieldDescription>
+              <UiInput id="profile-name" v-model="name" name="name" placeholder="Evil Rabbit" required />
             </UiFieldContent>
-            <UiInput id="profile-name" v-model="name" name="name" placeholder="Evil Rabbit" required />
           </UiField>
           <UiFieldSeparator />
-          <UiField orientation="responsive">
+          <UiField orientation="responsive" description-placement="under-label">
+            <UiFieldLabel for="profile-message">Message</UiFieldLabel>
+            <UiFieldDescription>
+              You can write your message here. Keep it short, preferably under 100 characters.
+            </UiFieldDescription>
             <UiFieldContent>
-              <UiFieldLabel for="profile-message">Message</UiFieldLabel>
-              <UiFieldDescription>
-                You can write your message here. Keep it short, preferably under 100 characters.
-              </UiFieldDescription>
+              <UiTextarea
+                id="profile-message"
+                v-model="message"
+                name="message"
+                placeholder="Hello, world!"
+                required
+                class="min-h-[100px] resize-none sm:min-w-[300px]"
+              />
             </UiFieldContent>
-            <UiTextarea
-              id="profile-message"
-              v-model="message"
-              name="message"
-              placeholder="Hello, world!"
-              required
-              class="min-h-[100px] resize-none sm:min-w-[300px]"
-            />
           </UiField>
           <UiFieldSeparator />
           <UiField orientation="responsive">
@@ -1143,7 +1433,8 @@ const message = ref('')
 
 /**
  * Full responsive form layout, mirroring the “Responsive Layout” example from shadcn-vue field docs.
- * Uses `UiFieldContent` as the label/description column and keeps controls aligned responsively.
+ * Uses `descriptionPlacement="under-label"` to group the label and description together,
+ * and `tooltip` prop on `UiFieldLabel` for inline help.
  */
 export const ResponsiveProfileForm: Story = {
   render: () => ({
@@ -1173,29 +1464,31 @@ export const ResponsiveProfileForm: Story = {
             <UiFieldDescription>Fill in your profile information.</UiFieldDescription>
             <UiFieldSeparator />
             <UiFieldGroup>
-              <UiField orientation="responsive">
+              <UiField orientation="responsive" description-placement="under-label">
+                <UiFieldLabel for="profile-name" tooltip="Used on your public profile page.">
+                  Name
+                </UiFieldLabel>
+                <UiFieldDescription>Provide your full name for identification</UiFieldDescription>
                 <UiFieldContent>
-                  <UiFieldLabel for="profile-name">Name</UiFieldLabel>
-                  <UiFieldDescription>Provide your full name for identification</UiFieldDescription>
+                  <UiInput id="profile-name" v-model="name" name="name" placeholder="Evil Rabbit" required />
                 </UiFieldContent>
-                <UiInput id="profile-name" v-model="name" name="name" placeholder="Evil Rabbit" required />
               </UiField>
               <UiFieldSeparator />
-              <UiField orientation="responsive">
+              <UiField orientation="responsive" description-placement="under-label">
+                <UiFieldLabel for="profile-message">Message</UiFieldLabel>
+                <UiFieldDescription>
+                  You can write your message here. Keep it short, preferably under 100 characters.
+                </UiFieldDescription>
                 <UiFieldContent>
-                  <UiFieldLabel for="profile-message">Message</UiFieldLabel>
-                  <UiFieldDescription>
-                    You can write your message here. Keep it short, preferably under 100 characters.
-                  </UiFieldDescription>
+                  <UiTextarea
+                    id="profile-message"
+                    v-model="message"
+                    name="message"
+                    placeholder="Hello, world!"
+                    required
+                    class="min-h-[100px] resize-none sm:min-w-[300px]"
+                  />
                 </UiFieldContent>
-                <UiTextarea
-                  id="profile-message"
-                  v-model="message"
-                  name="message"
-                  placeholder="Hello, world!"
-                  required
-                  class="min-h-[100px] resize-none sm:min-w-[300px]"
-                />
               </UiField>
               <UiFieldSeparator />
               <UiField orientation="responsive">
@@ -1214,146 +1507,11 @@ export const ResponsiveProfileForm: Story = {
   },
 };
 
-const checkoutPaymentFormTemplateSource = `<script setup lang="ts">
-import { ref } from 'vue'
-import {
-  UiButton,
-  UiCheckbox,
-  UiField,
-  UiFieldDescription,
-  UiFieldGroup,
-  UiFieldLabel,
-  UiFieldLegend,
-  UiFieldSeparator,
-  UiFieldSet,
-  UiInput,
-  UiSelect,
-  UiSelectContent,
-  UiSelectItem,
-  UiSelectTrigger,
-  UiSelectValue,
-  UiTextarea,
-} from '@aleph-alpha/ui-library'
-
-const cardName = ref('')
-const cardNumber = ref('')
-const cvv = ref('')
-const month = ref('')
-const year = ref('')
-const sameAsShipping = ref(true)
-const comments = ref('')
-</script>
-
-<template>
-  <div class="w-full max-w-md">
-    <form>
-      <UiFieldGroup>
-        <UiFieldSet>
-          <UiFieldLegend>Payment Method</UiFieldLegend>
-          <UiFieldDescription>All transactions are secure and encrypted</UiFieldDescription>
-
-          <UiFieldGroup>
-            <UiField>
-              <UiFieldLabel for="card-name">Name on Card</UiFieldLabel>
-              <UiInput id="card-name" v-model="cardName" name="cardName" placeholder="Evil Rabbit" required />
-            </UiField>
-
-            <UiField>
-              <UiFieldLabel for="card-number">Card Number</UiFieldLabel>
-              <UiInput id="card-number" v-model="cardNumber" name="cardNumber" placeholder="1234 5678 9012 3456" required />
-              <UiFieldDescription>Enter your 16-digit card number</UiFieldDescription>
-            </UiField>
-
-            <div class="grid grid-cols-3 gap-4">
-              <UiField>
-                <UiFieldLabel for="exp-month">Month</UiFieldLabel>
-                <UiSelect v-model="month">
-                  <UiSelectTrigger id="exp-month">
-                    <UiSelectValue placeholder="MM" />
-                  </UiSelectTrigger>
-                  <UiSelectContent>
-                    <UiSelectItem value="01">01</UiSelectItem>
-                    <UiSelectItem value="02">02</UiSelectItem>
-                    <UiSelectItem value="03">03</UiSelectItem>
-                    <UiSelectItem value="04">04</UiSelectItem>
-                    <UiSelectItem value="05">05</UiSelectItem>
-                    <UiSelectItem value="06">06</UiSelectItem>
-                    <UiSelectItem value="07">07</UiSelectItem>
-                    <UiSelectItem value="08">08</UiSelectItem>
-                    <UiSelectItem value="09">09</UiSelectItem>
-                    <UiSelectItem value="10">10</UiSelectItem>
-                    <UiSelectItem value="11">11</UiSelectItem>
-                    <UiSelectItem value="12">12</UiSelectItem>
-                  </UiSelectContent>
-                </UiSelect>
-              </UiField>
-
-              <UiField>
-                <UiFieldLabel for="exp-year">Year</UiFieldLabel>
-                <UiSelect v-model="year">
-                  <UiSelectTrigger id="exp-year">
-                    <UiSelectValue placeholder="YYYY" />
-                  </UiSelectTrigger>
-                  <UiSelectContent>
-                    <UiSelectItem value="2026">2026</UiSelectItem>
-                    <UiSelectItem value="2027">2027</UiSelectItem>
-                    <UiSelectItem value="2028">2028</UiSelectItem>
-                    <UiSelectItem value="2029">2029</UiSelectItem>
-                    <UiSelectItem value="2030">2030</UiSelectItem>
-                  </UiSelectContent>
-                </UiSelect>
-              </UiField>
-
-              <UiField>
-                <UiFieldLabel for="cvv">CVV</UiFieldLabel>
-                <UiInput id="cvv" v-model="cvv" name="cvv" placeholder="123" required />
-              </UiField>
-            </div>
-          </UiFieldGroup>
-        </UiFieldSet>
-
-        <UiFieldSeparator />
-
-        <UiFieldSet>
-          <UiFieldLegend>Billing Address</UiFieldLegend>
-          <UiFieldDescription>The billing address associated with your payment method</UiFieldDescription>
-          <UiFieldGroup>
-            <UiField orientation="horizontal">
-              <UiCheckbox id="same-as-shipping" v-model="sameAsShipping" name="same-as-shipping" />
-              <UiFieldLabel for="same-as-shipping" class="font-normal">Same as shipping address</UiFieldLabel>
-            </UiField>
-          </UiFieldGroup>
-        </UiFieldSet>
-
-        <UiFieldSet>
-          <UiFieldGroup>
-            <UiField>
-              <UiFieldLabel for="comments">Comments</UiFieldLabel>
-              <UiTextarea
-                id="comments"
-                v-model="comments"
-                name="comments"
-                placeholder="Add any additional comments"
-                class="resize-none"
-              />
-            </UiField>
-          </UiFieldGroup>
-        </UiFieldSet>
-
-        <UiField orientation="horizontal">
-          <UiButton type="submit">Submit</UiButton>
-          <UiButton variant="outline" type="button">Cancel</UiButton>
-        </UiField>
-      </UiFieldGroup>
-    </form>
-  </div>
-</template>`;
-
 /**
- * Full “checkout” composition (payment method + billing address + actions).
- * Based on the main example in shadcn-vue field docs.
+ * Payment form with card details, billing address, and comments.
+ * Demonstrates `tooltip` on labels, select inputs, checkbox, and textarea.
  */
-export const CheckoutPaymentForm: Story = {
+export const PaymentMethodForm: Story = {
   render: () => ({
     components: {
       UiButton,
@@ -1374,9 +1532,9 @@ export const CheckoutPaymentForm: Story = {
       UiTextarea,
     },
     setup() {
-      const cardName = ref('');
-      const cardNumber = ref('');
-      const cvv = ref('');
+      const cardName = ref('John Doe');
+      const cardNumber = ref('1234 5678 9012 3456');
+      const cvv = ref('123');
       const month = ref('');
       const year = ref('');
       const sameAsShipping = ref(true);
@@ -1384,67 +1542,45 @@ export const CheckoutPaymentForm: Story = {
       return { cardName, cardNumber, cvv, month, year, sameAsShipping, comments };
     },
     template: `
-      <div class="w-full max-w-md">
+      <div class="w-full max-w-sm">
         <form>
           <UiFieldGroup>
             <UiFieldSet>
               <UiFieldLegend>Payment Method</UiFieldLegend>
-              <UiFieldDescription>All transactions are secure and encrypted</UiFieldDescription>
+              <UiFieldDescription>All transactions are secure and encrypted.</UiFieldDescription>
 
               <UiFieldGroup>
                 <UiField>
-                  <UiFieldLabel for="card-name">Name on Card</UiFieldLabel>
-                  <UiInput id="card-name" v-model="cardName" name="cardName" placeholder="Evil Rabbit" required />
+                  <UiFieldLabel for="card-name" tooltip="The name printed on your card.">Name on card</UiFieldLabel>
+                  <UiInput id="card-name" v-model="cardName" name="cardName" placeholder="John Doe" required />
                 </UiField>
 
                 <UiField>
-                  <UiFieldLabel for="card-number">Card Number</UiFieldLabel>
+                  <UiFieldLabel for="card-number" tooltip="Your 16-digit card number.">Card number</UiFieldLabel>
                   <UiInput id="card-number" v-model="cardNumber" name="cardNumber" placeholder="1234 5678 9012 3456" required />
-                  <UiFieldDescription>Enter your 16-digit card number</UiFieldDescription>
                 </UiField>
 
                 <div class="grid grid-cols-3 gap-4">
                   <UiField>
-                    <UiFieldLabel for="exp-month">Month</UiFieldLabel>
+                    <UiFieldLabel for="exp-month" tooltip="Expiry month.">Month</UiFieldLabel>
                     <UiSelect v-model="month">
-                      <UiSelectTrigger id="exp-month">
-                        <UiSelectValue placeholder="MM" />
-                      </UiSelectTrigger>
+                      <UiSelectTrigger id="exp-month"><UiSelectValue placeholder="MM" /></UiSelectTrigger>
                       <UiSelectContent>
-                        <UiSelectItem value="01">01</UiSelectItem>
-                        <UiSelectItem value="02">02</UiSelectItem>
-                        <UiSelectItem value="03">03</UiSelectItem>
-                        <UiSelectItem value="04">04</UiSelectItem>
-                        <UiSelectItem value="05">05</UiSelectItem>
-                        <UiSelectItem value="06">06</UiSelectItem>
-                        <UiSelectItem value="07">07</UiSelectItem>
-                        <UiSelectItem value="08">08</UiSelectItem>
-                        <UiSelectItem value="09">09</UiSelectItem>
-                        <UiSelectItem value="10">10</UiSelectItem>
-                        <UiSelectItem value="11">11</UiSelectItem>
-                        <UiSelectItem value="12">12</UiSelectItem>
+                        <UiSelectItem v-for="m in ['01','02','03','04','05','06','07','08','09','10','11','12']" :key="m" :value="m">{{ m }}</UiSelectItem>
                       </UiSelectContent>
                     </UiSelect>
                   </UiField>
-
                   <UiField>
-                    <UiFieldLabel for="exp-year">Year</UiFieldLabel>
+                    <UiFieldLabel for="exp-year" tooltip="Expiry year.">Year</UiFieldLabel>
                     <UiSelect v-model="year">
-                      <UiSelectTrigger id="exp-year">
-                        <UiSelectValue placeholder="YYYY" />
-                      </UiSelectTrigger>
+                      <UiSelectTrigger id="exp-year"><UiSelectValue placeholder="YYYY" /></UiSelectTrigger>
                       <UiSelectContent>
-                        <UiSelectItem value="2026">2026</UiSelectItem>
-                        <UiSelectItem value="2027">2027</UiSelectItem>
-                        <UiSelectItem value="2028">2028</UiSelectItem>
-                        <UiSelectItem value="2029">2029</UiSelectItem>
-                        <UiSelectItem value="2030">2030</UiSelectItem>
+                        <UiSelectItem v-for="y in ['2026','2027','2028','2029','2030']" :key="y" :value="y">{{ y }}</UiSelectItem>
                       </UiSelectContent>
                     </UiSelect>
                   </UiField>
-
                   <UiField>
-                    <UiFieldLabel for="cvv">CVV</UiFieldLabel>
+                    <UiFieldLabel for="cvv" tooltip="3-digit security code on the back.">CVV</UiFieldLabel>
                     <UiInput id="cvv" v-model="cvv" name="cvv" placeholder="123" required />
                   </UiField>
                 </div>
@@ -1455,31 +1591,238 @@ export const CheckoutPaymentForm: Story = {
 
             <UiFieldSet>
               <UiFieldLegend>Billing Address</UiFieldLegend>
-              <UiFieldDescription>The billing address associated with your payment method</UiFieldDescription>
+              <UiFieldDescription>The billing address associated with your payment method.</UiFieldDescription>
               <UiFieldGroup>
-                <UiField orientation="horizontal">
+                <UiField orientation="responsive">
                   <UiCheckbox id="same-as-shipping" v-model="sameAsShipping" name="same-as-shipping" />
                   <UiFieldLabel for="same-as-shipping" class="font-normal">Same as shipping address</UiFieldLabel>
                 </UiField>
               </UiFieldGroup>
             </UiFieldSet>
 
+            <UiField>
+              <UiFieldLabel for="comments" tooltip="Any special delivery instructions.">Comments</UiFieldLabel>
+              <UiTextarea id="comments" v-model="comments" name="comments" placeholder="Add any additional comments" class="resize-none" />
+            </UiField>
+
+            <UiField orientation="responsive">
+              <UiButton type="submit">Submit</UiButton>
+              <UiButton variant="outline" type="button">Cancel</UiButton>
+            </UiField>
+          </UiFieldGroup>
+        </form>
+      </div>
+    `,
+  }),
+  parameters: { controls: { disable: true } },
+};
+
+/**
+ * Profile settings form with notification switches, privacy radio group,
+ * and a labeled separator. Demonstrates `descriptionPlacement`, `UiSwitch`,
+ * and `UiRadioGroup` inside fields.
+ */
+export const ProfileSettingsForm: Story = {
+  render: () => ({
+    components: {
+      UiButton,
+      UiField,
+      UiFieldContent,
+      UiFieldDescription,
+      UiFieldGroup,
+      UiFieldLabel,
+      UiFieldLegend,
+      UiFieldSeparator,
+      UiFieldSet,
+      UiInput,
+      UiRadioGroup,
+      UiRadioGroupItem,
+      UiSwitch,
+      UiTextarea,
+    },
+    setup() {
+      const firstName = ref('John');
+      const lastName = ref('Doe');
+      const email = ref('john@example.com');
+      const phone = ref('(555) 123-4567');
+      const bio = ref('');
+      const emailNotifications = ref(true);
+      const pushNotifications = ref(false);
+      const marketingEmails = ref(true);
+      const privacy = ref('everyone');
+      return {
+        firstName,
+        lastName,
+        email,
+        phone,
+        bio,
+        emailNotifications,
+        pushNotifications,
+        marketingEmails,
+        privacy,
+      };
+    },
+    template: `
+      <div class="w-full max-w-md">
+        <form>
+          <UiFieldGroup>
+            <UiFieldSet>
+              <UiFieldLegend>Profile Settings</UiFieldLegend>
+              <UiFieldDescription>Update your profile information and preferences.</UiFieldDescription>
+
+              <UiFieldGroup>
+                <div class="grid grid-cols-2 gap-4">
+                  <UiField>
+                    <UiFieldLabel for="profile-first" tooltip="Your given name.">First Name</UiFieldLabel>
+                    <UiInput id="profile-first" v-model="firstName" name="firstName" placeholder="John" />
+                  </UiField>
+                  <UiField>
+                    <UiFieldLabel for="profile-last" tooltip="Your family name.">Last Name</UiFieldLabel>
+                    <UiInput id="profile-last" v-model="lastName" name="lastName" placeholder="Doe" />
+                  </UiField>
+                </div>
+
+                <UiField>
+                  <UiFieldLabel for="profile-email" tooltip="Your primary contact email.">Email</UiFieldLabel>
+                  <UiInput id="profile-email" v-model="email" name="email" type="email" placeholder="john@example.com" />
+                </UiField>
+
+                <UiField>
+                  <UiFieldLabel for="profile-phone" tooltip="Include country code.">Phone Number</UiFieldLabel>
+                  <UiInput id="profile-phone" v-model="phone" name="phone" type="tel" placeholder="(555) 123-4567" />
+                </UiField>
+
+                <UiField>
+                  <UiFieldLabel for="profile-bio" tooltip="Keep it short and professional.">Bio</UiFieldLabel>
+                  <UiTextarea id="profile-bio" v-model="bio" name="bio" placeholder="Tell us a little about yourself" class="resize-none" />
+                </UiField>
+              </UiFieldGroup>
+            </UiFieldSet>
+
+            <UiFieldSet>
+              <UiFieldLegend>Notification Preferences</UiFieldLegend>
+              <UiFieldDescription>Manage your notification preferences.</UiFieldDescription>
+
+              <UiFieldGroup>
+                <UiField orientation="responsive" description-placement="under-label">
+                  <UiFieldLabel for="email-notif">Email notifications</UiFieldLabel>
+                  <UiFieldDescription>Receive emails about new products, features, and more. If you don't want to receive these emails, you can turn them off.</UiFieldDescription>
+                  <UiSwitch id="email-notif" v-model="emailNotifications" name="emailNotifications" />
+                </UiField>
+
+                <UiField orientation="responsive">
+                  <UiFieldLabel for="push-notif">Push notifications</UiFieldLabel>
+                  <UiSwitch id="push-notif" v-model="pushNotifications" name="pushNotifications" />
+                </UiField>
+
+                <UiField orientation="responsive">
+                  <UiFieldLabel for="marketing">Marketing emails</UiFieldLabel>
+                  <UiSwitch id="marketing" v-model="marketingEmails" name="marketingEmails" />
+                </UiField>
+              </UiFieldGroup>
+            </UiFieldSet>
+
+            <UiFieldSeparator>Privacy</UiFieldSeparator>
+
+            <UiFieldSet>
+              <UiFieldLegend>Privacy Settings</UiFieldLegend>
+              <UiFieldDescription>Choose who can see your profile and what they can see.</UiFieldDescription>
+
+              <UiRadioGroup v-model="privacy" name="privacy">
+                <UiField orientation="responsive">
+                  <UiRadioGroupItem id="privacy-everyone" value="everyone" />
+                  <UiFieldContent>
+                    <UiFieldLabel for="privacy-everyone" class="font-normal">Everyone</UiFieldLabel>
+                    <UiFieldDescription>Anyone can see your profile</UiFieldDescription>
+                  </UiFieldContent>
+                </UiField>
+                <UiField orientation="responsive">
+                  <UiRadioGroupItem id="privacy-followers" value="followers" />
+                  <UiFieldContent>
+                    <UiFieldLabel for="privacy-followers" class="font-normal">Followers</UiFieldLabel>
+                    <UiFieldDescription>Visible to your followers and connections</UiFieldDescription>
+                  </UiFieldContent>
+                </UiField>
+                <UiField orientation="responsive">
+                  <UiRadioGroupItem id="privacy-custom" value="custom" />
+                  <UiFieldContent>
+                    <UiFieldLabel for="privacy-custom" class="font-normal">Custom</UiFieldLabel>
+                    <UiFieldDescription>Choose who can see your profile</UiFieldDescription>
+                  </UiFieldContent>
+                </UiField>
+              </UiRadioGroup>
+            </UiFieldSet>
+
+            <UiField orientation="responsive">
+              <UiButton variant="outline" type="button">Cancel</UiButton>
+              <UiButton type="submit">Save Changes</UiButton>
+            </UiField>
+          </UiFieldGroup>
+        </form>
+      </div>
+    `,
+  }),
+  parameters: { controls: { disable: true } },
+};
+
+/**
+ * Personal information form with file upload and terms checkbox.
+ * Demonstrates `tooltip` labels, file input, and validation-style checkbox.
+ */
+export const PersonalInformationForm: Story = {
+  render: () => ({
+    components: {
+      UiButton,
+      UiCheckbox,
+      UiField,
+      UiFieldContent,
+      UiFieldDescription,
+      UiFieldGroup,
+      UiFieldLabel,
+      UiFieldLegend,
+      UiFieldSet,
+      UiInput,
+    },
+    setup() {
+      const pFirstName = ref('John');
+      const pLastName = ref('Doe');
+      const agreeTerms = ref(false);
+      return { pFirstName, pLastName, agreeTerms };
+    },
+    template: `
+      <div class="w-full max-w-sm">
+        <form>
+          <UiFieldGroup>
             <UiFieldSet>
+              <UiFieldLegend>Personal Information</UiFieldLegend>
+              <UiFieldDescription>Your basic contact information.</UiFieldDescription>
+
               <UiFieldGroup>
                 <UiField>
-                  <UiFieldLabel for="comments">Comments</UiFieldLabel>
-                  <UiTextarea
-                    id="comments"
-                    v-model="comments"
-                    name="comments"
-                    placeholder="Add any additional comments"
-                    class="resize-none"
-                  />
+                  <UiFieldLabel for="p-first" tooltip="As it appears on official documents.">First Name</UiFieldLabel>
+                  <UiInput id="p-first" v-model="pFirstName" name="pFirstName" placeholder="John" />
+                </UiField>
+
+                <UiField>
+                  <UiFieldLabel for="p-last" tooltip="As it appears on official documents.">Last Name</UiFieldLabel>
+                  <UiInput id="p-last" v-model="pLastName" name="pLastName" placeholder="Doe" />
+                </UiField>
+
+                <UiField>
+                  <UiFieldLabel for="p-resume" tooltip="PDF or DOCX, max 5 MB.">Upload Resume</UiFieldLabel>
+                  <UiInput id="p-resume" name="resume" type="file" />
                 </UiField>
               </UiFieldGroup>
             </UiFieldSet>
 
-            <UiField orientation="horizontal">
+            <UiField orientation="responsive" data-invalid="true">
+              <UiCheckbox id="agree-terms" v-model="agreeTerms" name="agreeTerms" />
+              <UiFieldContent>
+                <UiFieldLabel for="agree-terms" class="font-normal">I agree to the terms and conditions</UiFieldLabel>
+              </UiFieldContent>
+            </UiField>
+
+            <UiField orientation="responsive">
               <UiButton type="submit">Submit</UiButton>
               <UiButton variant="outline" type="button">Cancel</UiButton>
             </UiField>
@@ -1488,8 +1831,5 @@ export const CheckoutPaymentForm: Story = {
       </div>
     `,
   }),
-  parameters: {
-    controls: { disable: true },
-    docs: { source: { code: checkoutPaymentFormTemplateSource } },
-  },
+  parameters: { controls: { disable: true } },
 };