@repobit/dex-system-design 0.22.12 → 0.23.1

package/src/components/input/custom-form.stories.js

@@ -1,33 +1,173 @@
+// form-inputs.stories.js
 import { html } from 'lit';
+import '../Button/Button.js';
 import '../dropdown/dropdown.js';
 import './input-clipboard.js';
 import './input.js';
-
 export default {
-  title: 'Components/Form Inputs and Dropdown',
-  tags : ['autodocs']
-};
+  title     : 'Components/Form Inputs',
+  component : 'bd-custom-input',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**FormInputs** is a suite of Lit web components providing accessible, themeable form controls for Bitdefender interfaces.
+
+It includes:
+- A text / email / password / number / tel **Input** field with validation states
+- A **Dropdown** select with configurable options and sizing
+- An **InputClipboard** field with one-click copy/paste functionality
+
+### States
+| State | Description |
+|---|---|
+| \`default\` | Idle, no interaction |
+| \`focused\` | Active keyboard / pointer focus |
+| \`invalid\` | Failed validation — red border + helper text |
+| \`validated\` | Passed validation — green border + check icon |
+| \`disabled\` | Non-interactive, visually muted |
+
+### Sizes (\`kind\`)
+| Value | Use case |
+|---|---|
+| \`sm\` | Compact forms, sidebars, modals |
+| \`md\` | Default forms |
+| \`lg\` | Hero / marketing sign-up areas |
+
+### Input Types
+Supports all native HTML input types: \`text\`, \`email\`, \`password\`, \`number\`, \`tel\`.
+        `
+      }
+    }
+  },
+  argTypes: {
+    // ── Input props ──────────────────────────────────────────────────────────
+    label: {
+      control    : 'text',
+      description: 'Visible label rendered above the field',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'Nume complet' },
+        category    : 'Input'
+      }
+    },
+    type: {
+      control    : { type: 'select' },
+      options    : ['text', 'email', 'password', 'number', 'tel'],
+      description: 'Native HTML input type',
+      table      : {
+        type        : { summary: "'text' | 'email' | 'password' | 'number' | 'tel'" },
+        defaultValue: { summary: 'text' },
+        category    : 'Input'
+      }
+    },
+    placeholder: {
+      control    : 'text',
+      description: 'Placeholder text shown when the field is empty',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'Introdu numele tău' },
+        category    : 'Input'
+      }
+    },
+    kind: {
+      control    : { type: 'select' },
+      options    : ['sm', 'md', 'lg'],
+      description: 'Size variant — controls height, font-size, and padding',
+      table      : {
+        type        : { summary: "'sm' | 'md' | 'lg'" },
+        defaultValue: { summary: 'sm' },
+        category    : 'Layout'
+      }
+    },
+    required: {
+      control    : 'boolean',
+      description: 'Marks the field as required and appends an asterisk to the label',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: false },
+        category    : 'State'
+      }
+    },
+    focused: {
+      control    : 'boolean',
+      description: 'Forces the focus ring on; useful for design review in Storybook',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: false },
+        category    : 'State'
+      }
+    },
+    invalid: {
+      control    : 'boolean',
+      description: 'Applies the error / invalid styling — red border, warning icon, helper text',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: false },
+        category    : 'State'
+      }
+    },
+    validated: {
+      control    : 'boolean',
+      description: 'Applies the success / validated styling — green border and check icon',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: false },
+        category    : 'State'
+      }
+    },
+    disabled: {
+      control    : 'boolean',
+      description: 'Disables the field — prevents interaction and applies muted styles',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: false },
+        category    : 'State'
+      }
+    },
+    tooltip: {
+      control    : 'text',
+      description: 'Optional tooltip text shown via an info icon adjacent to the label',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '' },
+        category    : 'Input'
+      }
+    },
+
+    // ── Dropdown props ───────────────────────────────────────────────────────
+    options: {
+      control    : 'object',
+      description: `
+Array of option strings rendered inside the dropdown list.
+
+\`\`\`js
+options: ['Small', 'Medium', 'Large']
+\`\`\`
+      `,
+      table: {
+        type    : { summary: 'string[]' },
+        category: 'Dropdown'
+      }
+    },
 
-// ---------- INPUT COMPONENT ----------
-const InputTemplate = (args) => {
-  return html`
-    <bd-custom-input
-      label="${args.label}"
-      type="${args.type}"
-      placeholder="${args.placeholder}"
-      kind="${args.kind}"
-      ?required="${args.required}"
-      ?focused="${args.focused}"
-      ?invalid="${args.invalid}"
-      ?validated="${args.validated}"
-      ?disabled="${args.disabled}"
-      tooltip="${args.tooltip}"
-    ></bd-custom-input>
-  `;
+    // ── InputClipboard props ─────────────────────────────────────────────────
+    value: {
+      control    : 'text',
+      description: 'Pre-filled value for the clipboard input',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '' },
+        category    : 'InputClipboard'
+      }
+    }
+  }
 };
 
-export const Input = InputTemplate.bind({});
-Input.args = {
+// ─── Default args shared across stories ─────────────────────────────────────
+
+const defaultInputArgs = {
   label      : 'Nume complet',
   type       : 'text',
   placeholder: 'Introdu numele tău',
@@ -40,246 +180,643 @@ Input.args = {
   tooltip    : ''
 };
 
-Input.argTypes = {
-  label: { control: 'text' },
-  type : {
-    control: { type: 'select' },
-    options: ['text', 'email', 'password', 'number', 'tel']
-  },
-  placeholder: { control: 'text' },
-  kind       : {
-    control: { type: 'select' },
-    options: ['sm', 'md', 'lg']
-  },
-  required : { control: 'boolean' },
-  focused  : { control: 'boolean' },
-  invalid  : { control: 'boolean' },
-  validated: { control: 'boolean' },
-  disabled : { control: 'boolean' },
-  tooltip  : { control: 'text' }
+const defaultDropdownArgs = {
+  label  : 'Select size',
+  kind   : 'md',
+  options: ['Small', 'Medium', 'Large'],
+  tooltip: 'Choose an option'
 };
 
-Input.parameters = {
-  docs: {
-    description: {
-      component: 'Custom input component with various states and sizes.'
+const defaultClipboardArgs = {
+  label      : 'Token',
+  kind       : 'sm',
+  placeholder: 'Paste token here',
+  value      : '',
+  disabled   : false,
+  tooltip    : ''
+};
+
+// ─── Render helpers ──────────────────────────────────────────────────────────
+
+const renderInput = (args) => html`
+  <bd-custom-input
+    label="${args.label}"
+    type="${args.type}"
+    placeholder="${args.placeholder}"
+    kind="${args.kind}"
+    ?required="${args.required}"
+    ?focused="${args.focused}"
+    ?invalid="${args.invalid}"
+    ?validated="${args.validated}"
+    ?disabled="${args.disabled}"
+    tooltip="${args.tooltip}"
+  ></bd-custom-input>
+`;
+
+const renderDropdown = (args) => html`
+  <bd-custom-dropdown
+    label="${args.label}"
+    kind="${args.kind}"
+    options='${JSON.stringify(args.options)}'
+    tooltip="${args.tooltip}"
+  ></bd-custom-dropdown>
+`;
+
+const renderClipboard = (args) => html`
+  <bd-custom-input-clipboard
+    label="${args.label}"
+    kind="${args.kind}"
+    placeholder="${args.placeholder}"
+    value="${args.value}"
+    ?disabled="${args.disabled}"
+    tooltip="${args.tooltip}"
+  ></bd-custom-input-clipboard>
+`;
+
+// ─── Stories ─────────────────────────────────────────────────────────────────
+
+/**
+ * Default idle state of the Input component — no validation, no focus.
+ */
+export const InputDefault = {
+  name      : 'Input — Default',
+  args      : { ...defaultInputArgs },
+  render    : renderInput,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The base input in its idle state. No validation, no focus ring. Use the Controls panel to toggle `required`, `focused`, `invalid`, `validated`, and `disabled` states, or switch `type` and `kind`.'
+      }
     }
   }
 };
 
-// ---------- DROPDOWN COMPONENT ----------
-const DropdownTemplate = (args) => {
-  return html`
-    <bd-custom-dropdown
-      label="${args.label}"
-      kind="${args.kind}"
-      options='${JSON.stringify(args.options)}'
-      tooltip="${args.tooltip}"
-    ></bd-custom-dropdown>
-  `;
+/**
+ * Input with the focused ring forced on — useful for design review without interaction.
+ */
+export const InputFocused = {
+  name      : 'Input — Focused',
+  args      : { ...defaultInputArgs, focused: true, label: 'Adresă de email', type: 'email', placeholder: 'you@example.com', kind: 'md' },
+  render    : renderInput,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Focus ring applied via the `focused` boolean prop. Demonstrates the active ring style without requiring pointer or keyboard interaction inside the story frame.'
+      }
+    }
+  }
 };
 
-export const Dropdown = DropdownTemplate.bind({});
-Dropdown.args = {
-  label  : 'Select size',
-  kind   : 'md',
-  options: ['Small', 'Medium', 'Large'],
-  tooltip: 'Choose an option'
+/**
+ * Input in the invalid / error state — red border, warning icon, helper text.
+ */
+export const InputInvalid = {
+  name      : 'Input — Invalid',
+  args      : { ...defaultInputArgs, invalid: true, label: 'Email', type: 'email', placeholder: 'Enter your email', required: true, tooltip: 'Please enter a valid email address' },
+  render    : renderInput,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The `invalid` prop activates the error state: red/danger border color, warning icon, and any associated helper or error message text. Combine with `required` for a realistic validation flow.'
+      }
+    }
+  }
 };
 
-Dropdown.argTypes = {
-  label: { control: 'text' },
-  kind : {
-    control: { type: 'select' },
-    options: ['sm', 'md', 'lg']
+/**
+ * Input in the validated / success state — green border and check icon.
+ */
+export const InputValidated = {
+  name      : 'Input — Validated',
+  args      : { ...defaultInputArgs, validated: true, label: 'Email', placeholder: 'Enter email', tooltip: 'Looks good!' },
+  render    : renderInput,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The `validated` prop activates the success state: green border and a check icon confirming the value passed validation. Typically toggled after a successful async check or on `blur`.'
+      }
+    }
+  }
+};
+
+/**
+ * Input in the disabled state — non-interactive and visually muted.
+ */
+export const InputDisabled = {
+  name      : 'Input — Disabled',
+  args      : { ...defaultInputArgs, disabled: true, label: 'Disabled Input', placeholder: "Can't type here", tooltip: 'This field is disabled' },
+  render    : renderInput,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The `disabled` prop prevents all user interaction. The field is rendered with reduced opacity and a `not-allowed` cursor. The native `<input>` element's disabled attribute is also set."
+      }
+    }
+  }
+};
+
+/**
+ * All three size variants of the Input rendered for side-by-side comparison.
+ */
+export const InputSizes = {
+  name  : 'Input — All Sizes',
+  render: () => html`
+    <div style="display: grid; gap: 1.5rem; max-width: 420px; margin: 2rem auto;">
+      <bd-custom-input label="Small (sm)" placeholder="sm variant" kind="sm"></bd-custom-input>
+      <bd-custom-input label="Medium (md)" placeholder="md variant" kind="md"></bd-custom-input>
+      <bd-custom-input label="Large (lg)" placeholder="lg variant" kind="lg"></bd-custom-input>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Side-by-side comparison of all three `kind` values: `sm`, `md`, and `lg`. Height, font-size, and internal padding scale proportionally.'
+      }
+    }
+  }
+};
+
+/**
+ * All five input types rendered together.
+ */
+export const InputTypes = {
+  name  : 'Input — All Types',
+  render: () => html`
+    <div style="display: grid; gap: 1.5rem; max-width: 420px; margin: 2rem auto;">
+      <bd-custom-input label="Text"     type="text"     placeholder="Plain text"        kind="sm"></bd-custom-input>
+      <bd-custom-input label="Email"    type="email"    placeholder="you@example.com"   kind="sm"></bd-custom-input>
+      <bd-custom-input label="Password" type="password" placeholder="••••••••"          kind="sm"></bd-custom-input>
+      <bd-custom-input label="Number"   type="number"   placeholder="0"                 kind="sm"></bd-custom-input>
+      <bd-custom-input label="Tel"      type="tel"      placeholder="+40 700 000 000"   kind="sm"></bd-custom-input>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'One input per supported `type`: `text`, `email`, `password`, `number`, `tel`. Verifies that each type renders without layout regressions and that browser-native affordances (toggle eye, number stepper) are preserved.'
+      }
+    }
+  }
+};
+
+// ─── Dropdown Stories ─────────────────────────────────────────────────────────
+
+/**
+ * Default Dropdown with three size options.
+ */
+export const DropdownDefault = {
+  name      : 'Dropdown — Default',
+  args      : { ...defaultDropdownArgs },
+  render    : renderDropdown,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Base dropdown in its idle state. The `options` array is serialised to JSON and passed as an attribute. Use the Controls panel to add, remove, or reorder options live.'
+      }
+    }
+  }
+};
+
+/**
+ * Dropdown with a long options list — verifies scroll behavior.
+ */
+export const DropdownLongList = {
+  name: 'Dropdown — Long Options List',
+  args: {
+    ...defaultDropdownArgs,
+    label  : 'Select country',
+    kind   : 'sm',
+    options: ['Romania', 'Germany', 'Canada', 'Japan', 'Brazil', 'France', 'Spain', 'Italy', 'United States', 'United Kingdom', 'Australia', 'Netherlands'],
+    tooltip: 'Choose your country'
   },
-  options: { control: 'object' },
-  tooltip: { control: 'text' }
+  render    : renderDropdown,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Twelve options provided — verifies that the dropdown list scrolls or truncates gracefully when the viewport height is limited. The max-height and overflow-y behaviour should activate.'
+      }
+    }
+  }
 };
 
-Dropdown.parameters = {
-  docs: {
-    description: {
-      component: 'Custom dropdown component with configurable options.'
+/**
+ * All three size variants of the Dropdown.
+ */
+export const DropdownSizes = {
+  name  : 'Dropdown — All Sizes',
+  render: () => html`
+    <div style="display: grid; gap: 1.5rem; max-width: 420px; margin: 2rem auto;">
+      <bd-custom-dropdown label="Small (sm)" kind="sm" options='["Option A","Option B","Option C"]'></bd-custom-dropdown>
+      <bd-custom-dropdown label="Medium (md)" kind="md" options='["Option A","Option B","Option C"]'></bd-custom-dropdown>
+      <bd-custom-dropdown label="Large (lg)" kind="lg" options='["Option A","Option B","Option C"]'></bd-custom-dropdown>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Side-by-side comparison of `sm`, `md`, and `lg` dropdown variants, matching the Input size spec so they can be used interchangeably within the same form row.'
+      }
     }
   }
 };
 
-// ---------- INPUT CLIPBOARD COMPONENT ----------
-const InputClipboardTemplate = (args) => {
-  return html`
-    <bd-custom-input-clipboard
-      label="${args.label}"
-      kind="${args.kind}"
-      placeholder="${args.placeholder}"
-      value="${args.value}"
-      ?disabled="${args.disabled}"
-      tooltip="${args.tooltip}"
-    ></bd-custom-input-clipboard>
-  `;
+// ─── InputClipboard Stories ───────────────────────────────────────────────────
+
+/**
+ * Default InputClipboard with no pre-filled value.
+ */
+export const ClipboardDefault = {
+  name      : 'InputClipboard — Default',
+  args      : { ...defaultClipboardArgs },
+  render    : renderClipboard,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Base clipboard input with an empty value. Clicking the copy icon while the field is empty should be a no-op or show a subtle "nothing to copy" signal.'
+      }
+    }
+  }
 };
 
-export const InputClipboard = InputClipboardTemplate.bind({});
-InputClipboard.args = {
-  label      : 'Token',
-  kind       : 'sm',
-  placeholder: 'Paste token here',
-  value      : '',
-  disabled   : false,
-  tooltip    : ''
+/**
+ * InputClipboard pre-filled with an API token string.
+ */
+export const ClipboardWithValue = {
+  name: 'InputClipboard — Pre-filled Value',
+  args: {
+    ...defaultClipboardArgs,
+    label  : 'API Token',
+    value  : 'sk-bd-live-4f8a2c1e9b3d7f6a0e5c8b2d4f1a9e7c',
+    tooltip: 'Copy your API token to the clipboard'
+  },
+  render    : renderClipboard,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The `value` prop pre-populates the field with an API token. Clicking the clipboard icon copies the value to the OS clipboard and should toggle a brief success indicator.'
+      }
+    }
+  }
 };
 
-InputClipboard.argTypes = {
-  label: { control: 'text' },
-  kind : {
-    control: { type: 'select' },
-    options: ['sm', 'md', 'lg']
+/**
+ * InputClipboard in the disabled state.
+ */
+export const ClipboardDisabled = {
+  name: 'InputClipboard — Disabled',
+  args: {
+    ...defaultClipboardArgs,
+    label   : 'Revoked Token',
+    value   : 'sk-bd-revoked-0000000000000000',
+    disabled: true,
+    tooltip : 'This token has been revoked'
   },
-  placeholder: { control: 'text' },
-  value      : { control: 'text' },
-  disabled   : { control: 'boolean' },
-  tooltip    : { control: 'text' }
+  render    : renderClipboard,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Both the text field and the copy button are non-interactive when `disabled` is set. The copy icon should also appear muted to communicate its unavailability.'
+      }
+    }
+  }
 };
 
-InputClipboard.parameters = {
-  docs: {
-    description: {
-      component: 'Input field with clipboard functionality for easy copy/paste.'
+/**
+ * All three size variants of InputClipboard.
+ */
+export const ClipboardSizes = {
+  name  : 'InputClipboard — All Sizes',
+  render: () => html`
+    <div style="display: grid; gap: 1.5rem; max-width: 420px; margin: 2rem auto;">
+      <bd-custom-input-clipboard label="Small (sm)" kind="sm" value="token-sm-example-value"></bd-custom-input-clipboard>
+      <bd-custom-input-clipboard label="Medium (md)" kind="md" value="token-md-example-value"></bd-custom-input-clipboard>
+      <bd-custom-input-clipboard label="Large (lg)" kind="lg" value="token-lg-example-value"></bd-custom-input-clipboard>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Size comparison for all three `kind` values of InputClipboard. Ensures the clipboard icon scales proportionally alongside the field height.'
+      }
     }
   }
 };
 
-// ---------- SHOWCASE STORIES ----------
-export const InputsShowcase = () => html`
-  <div style="display: grid; gap: 1rem; max-width: 400px; margin: 2rem auto;">
-    <h3>Input Variants</h3>
-    
-    <bd-custom-input 
-      label="Nume complet" 
-      placeholder="Introdu numele tău" 
-      kind="sm" 
-      required
-      tooltip="Choose a unique username">
-    </bd-custom-input>
-
-    <bd-custom-input 
-      label="Adresă de email" 
-      type="email" 
-      placeholder="you@example.com" 
-      kind="md" 
-      focused
-      tooltip="Click to see focus state">
-    </bd-custom-input>
-
-    <bd-custom-input 
-      label="Email" 
-      type="email" 
-      kind="sm" 
-      placeholder="Enter your email" 
-      required 
-      invalid
-      tooltip="Please enter a valid email address">
-    </bd-custom-input>
-
-    <bd-custom-input 
-      label="Email" 
-      kind="sm" 
-      placeholder="Enter email" 
-      tooltip="Looks good!"
-      validated>
-    </bd-custom-input>
-
-    <bd-custom-input 
-      label="Disabled Input" 
-      placeholder="Can't type here" 
-      tooltip="This field is disabled" 
-      kind="sm"
-      disabled>
-    </bd-custom-input>
-  </div>
-`;
+// ─── Showcase / Combined Stories ─────────────────────────────────────────────
 
-export const DropdownsShowcase = () => html`
-  <div style="display: grid; gap: 1rem; max-width: 400px; margin: 2rem auto;">
-    <h3>Dropdown Variants</h3>
-    
-    <bd-custom-dropdown 
-      label="Select size" 
-      kind="md" 
-      options='["Small", "Medium", "Large"]'
-      tooltip="Choose an option">
-    </bd-custom-dropdown>
-
-    <bd-custom-dropdown 
-      label="Select country" 
-      kind="sm" 
-      options='["Romania", "Germany", "Canada", "Japan", "Brazil"]'
-      tooltip="Choose an option">
-    </bd-custom-dropdown>
-  </div>
-`;
+/**
+ * All Input states in a single grid — quick visual regression reference.
+ */
+export const InputsShowcase = {
+  name  : 'Showcase — Input States',
+  render: () => html`
+    <div style="display: grid; gap: 1rem; max-width: 400px; margin: 2rem auto;">
+      <h3 style="margin: 0 0 .5rem;">Input Variants</h3>
 
-export const InputClipboardShowcase = () => html`
-  <div style="display: grid; gap: 1rem; max-width: 400px; margin: 2rem auto;">
-    <h3>Input Clipboard</h3>
-    
-    <bd-custom-input-clipboard 
-      label="Token" 
-      kind="sm" 
-      placeholder="Paste token here">
-    </bd-custom-input-clipboard>
-  </div>
-`;
+      <bd-custom-input
+        label="Nume complet"
+        placeholder="Introdu numele tău"
+        kind="sm"
+        required
+        tooltip="Choose a unique username">
+      </bd-custom-input>
 
-// ---------- COMBINED FORM EXAMPLE ----------
-export const FormExample = () => html`
-  <div style="max-width: 500px; margin: 2rem auto; padding: 2rem; border: 1px solid #e0e0e0; border-radius: 8px;">
-    <h3 style="margin-top: 0;">Complete Form Example</h3>
-    
-    <div style="display: grid; gap: 1.5rem;">
-      <bd-custom-input 
-        label="Full Name" 
-        placeholder="John Doe" 
-        kind="md" 
-        required>
+      <bd-custom-input
+        label="Adresă de email"
+        type="email"
+        placeholder="you@example.com"
+        kind="md"
+        focused
+        tooltip="Click to see focus state">
       </bd-custom-input>
 
-      <bd-custom-input 
-        label="Email Address" 
-        type="email" 
-        placeholder="john@example.com" 
-        kind="md" 
-        required>
+      <bd-custom-input
+        label="Email"
+        type="email"
+        kind="sm"
+        placeholder="Enter your email"
+        required
+        invalid
+        tooltip="Please enter a valid email address">
       </bd-custom-input>
 
-      <bd-custom-dropdown 
-        label="Country" 
-        kind="md" 
-        options='["Select a country", "United States", "Canada", "United Kingdom", "Germany", "France"]'
-        required>
+      <bd-custom-input
+        label="Email"
+        kind="sm"
+        placeholder="Enter email"
+        tooltip="Looks good!"
+        validated>
+      </bd-custom-input>
+
+      <bd-custom-input
+        label="Disabled Input"
+        placeholder="Can't type here"
+        tooltip="This field is disabled"
+        kind="sm"
+        disabled>
+      </bd-custom-input>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All five input states — default, focused, invalid, validated, and disabled — rendered in a single column for quick visual regression testing.'
+      }
+    }
+  }
+};
+
+/**
+ * All Dropdown variants in a single column.
+ */
+export const DropdownsShowcase = {
+  name  : 'Showcase — Dropdowns',
+  render: () => html`
+    <div style="display: grid; gap: 1rem; max-width: 400px; margin: 2rem auto;">
+      <h3 style="margin: 0 0 .5rem;">Dropdown Variants</h3>
+
+      <bd-custom-dropdown
+        label="Select size"
+        kind="md"
+        options='["Small", "Medium", "Large"]'
+        tooltip="Choose an option">
+      </bd-custom-dropdown>
+
+      <bd-custom-dropdown
+        label="Select country"
+        kind="sm"
+        options='["Romania", "Germany", "Canada", "Japan", "Brazil"]'
+        tooltip="Choose an option">
       </bd-custom-dropdown>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Two dropdown instances with different `kind` and `options` props. Useful for verifying that option rendering and sizing are consistent across configurations.'
+      }
+    }
+  }
+};
 
-      <bd-custom-input-clipboard 
-        label="API Token" 
-        kind="md" 
-        placeholder="Click to paste your token"
-        tooltip="Copy your API token from your account settings">
+/**
+ * All InputClipboard variants in a single column.
+ */
+export const InputClipboardShowcase = {
+  name  : 'Showcase — InputClipboard',
+  render: () => html`
+    <div style="display: grid; gap: 1rem; max-width: 400px; margin: 2rem auto;">
+      <h3 style="margin: 0 0 .5rem;">Input Clipboard</h3>
+
+      <bd-custom-input-clipboard
+        label="Token"
+        kind="sm"
+        placeholder="Paste token here">
       </bd-custom-input-clipboard>
 
-      <div style="display: flex; gap: 1rem; margin-top: 1rem;">
-        <bd-button 
-          label="Submit" 
-          size="md" 
-          kind="primary"
-          strong>
-        </bd-button>
-        
-        <bd-button 
-          label="Cancel" 
-          size="md" 
-          kind="outline">
-        </bd-button>
+      <bd-custom-input-clipboard
+        label="API Token"
+        kind="md"
+        value="sk-bd-live-4f8a2c1e9b3d7f6a0e5c8b2d4f1a9e7c"
+        tooltip="Click the icon to copy">
+      </bd-custom-input-clipboard>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Two clipboard inputs — one empty and one pre-filled — shown together for a quick comparison of empty vs populated states.'
+      }
+    }
+  }
+};
+
+/**
+ * A complete, realistic sign-up form combining all three components.
+ */
+export const FormExample = {
+  name  : 'Complete Form Example',
+  render: () => html`
+    <div style="max-width: 500px; margin: 2rem auto; padding: 2rem; border: 1px solid #e0e0e0; border-radius: 8px;">
+      <h3 style="margin-top: 0;">Complete Form Example</h3>
+
+      <div style="display: grid; gap: 1.5rem;">
+        <bd-custom-input
+          label="Full Name"
+          placeholder="John Doe"
+          kind="md"
+          required>
+        </bd-custom-input>
+
+        <bd-custom-input
+          label="Email Address"
+          type="email"
+          placeholder="john@example.com"
+          kind="md"
+          required>
+        </bd-custom-input>
+
+        <bd-custom-input
+          label="Password"
+          type="password"
+          placeholder="Min. 8 characters"
+          kind="md"
+          required
+          tooltip="Must contain uppercase, lowercase, number and symbol">
+        </bd-custom-input>
+
+        <bd-custom-dropdown
+          label="Country"
+          kind="md"
+          options='["Select a country", "United States", "Canada", "United Kingdom", "Germany", "France", "Romania"]'>
+        </bd-custom-dropdown>
+
+        <bd-custom-input-clipboard
+          label="API Token"
+          kind="md"
+          placeholder="Click to paste your token"
+          tooltip="Copy your API token from your account settings">
+        </bd-custom-input-clipboard>
+
+        <div style="display: flex; gap: 1rem; margin-top: 1rem;">
+          <bd-button size="md" kind="primary" strong>Submit</bd-button>
+          <bd-button size="md" kind="outline">Cancel</bd-button>
+        </div>
       </div>
     </div>
-  </div>
-`;
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A realistic sign-up form that combines all three components — Input (text, email, password), Dropdown, and InputClipboard — along with primary and outline action buttons. Demonstrates how the components compose together in a real-world layout.'
+      }
+    }
+  }
+};
+
+/**
+ * Mobile viewport (375px) — verifies all components render correctly at narrow width.
+ */
+export const MobileForm = {
+  name  : 'Mobile (375px)',
+  render: () => html`
+    <div style="padding: 1rem;">
+      <bd-custom-input
+        label="Full Name"
+        placeholder="John Doe"
+        kind="sm"
+        required>
+      </bd-custom-input>
+
+      <div style="margin-top: 1rem;">
+        <bd-custom-input
+          label="Email Address"
+          type="email"
+          placeholder="john@example.com"
+          kind="sm"
+          required>
+        </bd-custom-input>
+      </div>
+
+      <div style="margin-top: 1rem;">
+        <bd-custom-dropdown
+          label="Country"
+          kind="sm"
+          options='["Select a country", "United States", "Canada", "Romania"]'>
+        </bd-custom-dropdown>
+      </div>
+
+      <div style="margin-top: 1rem;">
+        <bd-custom-input-clipboard
+          label="API Token"
+          kind="sm"
+          placeholder="Paste your token">
+        </bd-custom-input-clipboard>
+      </div>
+    </div>
+  `,
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+    docs    : {
+      description: {
+        story:
+          'All three components rendered inside a 375px mobile viewport. Verifies that labels, icons, and interactive areas remain touch-friendly and do not overflow at narrow widths.'
+      }
+    }
+  }
+};
+
+/**
+ * Custom field labels, placeholders and options — demonstrates full content flexibility.
+ */
+export const CustomContent = {
+  name  : 'Custom Content',
+  render: () => html`
+    <div style="display: grid; gap: 1.5rem; max-width: 420px; margin: 2rem auto;">
+      <bd-custom-input
+        label="Company Registration Number"
+        placeholder="e.g. J40/12345/2024"
+        kind="md"
+        tooltip="As it appears on your trade registry certificate"
+        required>
+      </bd-custom-input>
+
+      <bd-custom-dropdown
+        label="Subscription Plan"
+        kind="md"
+        options='["Starter – Free", "Professional – €9 / mo", "Enterprise – Contact us"]'
+        tooltip="You can upgrade or downgrade at any time">
+      </bd-custom-dropdown>
+
+      <bd-custom-input-clipboard
+        label="Webhook Secret"
+        kind="md"
+        value="whsec_live_8d2f4b6a0c3e5f7d9b1a4c6e8f2d0b4a"
+        tooltip="Used to verify incoming webhook payloads">
+      </bd-custom-input-clipboard>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All three components configured with domain-specific content. Demonstrates that labels, placeholders, option text, and tooltip copy can be freely customised without affecting layout or behaviour.'
+      }
+    }
+  }
+};
+
+/**
+ * Playground — all controls fully exposed for interactive exploration.
+ */
+export const Playground = {
+  name      : '🛝 Playground',
+  args      : { ...defaultInputArgs },
+  render    : renderInput,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Fully interactive story wired to the `bd-custom-input` component. Use the **Controls** panel below to modify every prop in real time: label, type, placeholder, kind, required, focused, invalid, validated, disabled, and tooltip.'
+      }
+    }
+  }
+};