docs(storybook): align live component stories

Author: diogo-filipe-costa

packages/react-components/src/components/Autocomplete/Autocomplete.stories.tsx

@@ -1,9 +1,91 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Autocomplete } from './Autocomplete';
+import { Autocomplete, type AutocompleteProps } from './Autocomplete';
 
-const options = ['England', 'Scotland', 'Wales', 'Northern Ireland'];
+type AutocompleteOptionSet = 'countries' | 'cities' | 'empty';
 
-const meta: Meta<typeof Autocomplete> = {
+type AutocompleteStoryArgs = AutocompleteProps & {
+  optionSet?: AutocompleteOptionSet;
+};
+
+const countriesOptions = ['England', 'Scotland', 'Wales', 'Northern Ireland'];
+
+const citiesOptions = [
+  'London',
+  'Manchester',
+  'Birmingham',
+  'Leeds',
+  'Liverpool',
+];
+
+const optionSets: Record<AutocompleteOptionSet, string[]> = {
+  countries: countriesOptions,
+  cities: citiesOptions,
+  empty: [],
+};
+
+const defaultStoryCode = `import { Autocomplete } from '@ourfuturehealth/react-components';
+
+const countriesOptions = ['England', 'Scotland', 'Wales', 'Northern Ireland'];
+
+<Autocomplete
+  hint="Start typing to filter the list."
+  label="Country"
+  name="country"
+  options={countriesOptions}
+/>;
+`;
+
+const withErrorStoryCode = `import { Autocomplete } from '@ourfuturehealth/react-components';
+
+const countriesOptions = ['England', 'Scotland', 'Wales', 'Northern Ireland'];
+
+<Autocomplete
+  errorMessage="Select a country from the list or enter a new one."
+  hint="Start typing to filter the list."
+  label="Country"
+  name="country"
+  options={countriesOptions}
+/>;
+`;
+
+const fixedWidthStoryCode = `import { Autocomplete } from '@ourfuturehealth/react-components';
+
+const countriesOptions = ['England', 'Scotland', 'Wales', 'Northern Ireland'];
+
+<Autocomplete
+  hint="Start typing to filter the list."
+  inputWidth={20}
+  label="Country"
+  name="country"
+  options={countriesOptions}
+/>;
+`;
+
+const customNoResultsStoryCode = `import { Autocomplete } from '@ourfuturehealth/react-components';
+
+const countriesOptions = ['England', 'Scotland', 'Wales', 'Northern Ireland'];
+
+<Autocomplete
+  hint="Start typing to filter the list."
+  label="Country"
+  name="country"
+  noResultsText="No matching countries. Enter a new country instead."
+  options={countriesOptions}
+/>;
+`;
+
+const renderAutocompleteStory = ({
+  optionSet,
+  options = countriesOptions,
+  ...args
+}: AutocompleteStoryArgs) => {
+  const resolvedOptions =
+    optionSet === undefined ? options : optionSets[optionSet];
+
+  return <Autocomplete {...args} options={resolvedOptions} />;
+};
+
+const meta: Meta<AutocompleteStoryArgs> = {
   title: 'Components/Input/Autocomplete',
   component: Autocomplete,
   parameters: {
@@ -12,15 +94,15 @@ const meta: Meta<typeof Autocomplete> = {
     docs: {
       description: {
         component:
-          'An input with inline suggestions that reuses the toolkit autocomplete classes, shared input-family label treatment, and suggestions list styling. The component manages the suggestion menu internally and supports both controlled and uncontrolled input values.',
+          'Use Autocomplete for a text field that suggests matches while the user types. The React API stays small: pass a label, an array of suggestion strings, and the usual form-field props such as hint, error message, width, and `defaultValue` or `value` when you need them. Use the `Builder` story to explore the component with friendly preset controls, and use the other stories as fixed examples.',
       },
     },
   },
   tags: ['autodocs'],
   args: {
     label: 'Country',
     name: 'country',
-    options,
+    options: countriesOptions,
   },
   argTypes: {
     label: {
@@ -29,28 +111,41 @@ const meta: Meta<typeof Autocomplete> = {
     },
     hint: {
       control: 'text',
-      description: 'Optional supporting text shown below the label and above any error message.',
+      description:
+        'Optional supporting text shown below the label and above any error message.',
     },
     errorMessage: {
       control: 'text',
-      description: 'Validation message shown above the input. When present, the input is marked invalid and linked with `aria-describedby`.',
+      description:
+        'Validation message shown above the input. When present, the input is marked invalid and linked with `aria-describedby`.',
     },
     name: {
       control: 'text',
       description: 'HTML name submitted with the form.',
     },
     options: {
-      control: 'object',
-      description: 'Plain-text options used to build the suggestions list. Edit this as a simple array of strings.',
+      control: false,
+      description:
+        'Suggestion strings used to build the autocomplete menu. Pass a plain array of labels, for example country names or common answers.',
       table: {
         type: {
           summary: 'string[]',
         },
       },
     },
+    optionSet: {
+      control: 'select',
+      options: ['countries', 'cities', 'empty'],
+      description:
+        'Storybook-only helper for the Builder story. Switches between preset suggestion lists without editing the real `options` array.',
+      table: {
+        disable: true,
+      },
+    },
     noResultsText: {
       control: 'text',
-      description: 'Override for the no-results message shown when the query matches no suggestions.',
+      description:
+        'Override for the no-results message shown when the query matches no suggestions.',
     },
     width: {
       control: 'select',
@@ -62,16 +157,24 @@ const meta: Meta<typeof Autocomplete> = {
         'one-third',
         'one-quarter',
       ],
-      description: 'Responsive width utility for the autocomplete field, including its suggestions dropdown.',
+      description:
+        'Responsive width utility for the autocomplete field, including its suggestions dropdown.',
     },
     inputWidth: {
       control: 'select',
       options: [2, 3, 4, 5, 10, 20, 30],
-      description: 'Fixed character-width modifier that helps signal the expected answer length and also constrains the suggestions dropdown width.',
+      description:
+        'Fixed character-width modifier that helps signal the expected answer length and also constrains the suggestions dropdown width.',
     },
     describedBy: {
       control: 'text',
-      description: 'Additional element IDs to append to the component-generated `aria-describedby` value.',
+      description:
+        'Additional element IDs to append to the component-generated `aria-describedby` value.',
+    },
+    isPageHeading: {
+      control: 'boolean',
+      description:
+        'Wrap the label in an `h1` when this question is also the page heading.',
     },
     onOptionSelect: {
       control: false,
@@ -133,25 +236,114 @@ export const Default: Story = {
   args: {
     hint: 'Start typing to filter the list.',
   },
+  parameters: {
+    controls: {
+      disable: true,
+    },
+    docs: {
+      description: {
+        story:
+          'A realistic autocomplete example with a small set of country suggestions.',
+      },
+      source: {
+        code: defaultStoryCode,
+      },
+    },
+  },
+};
+
+export const Builder: Story = {
+  args: {
+    hint: 'Start typing to filter the list.',
+    label: 'Country',
+    name: 'country',
+    optionSet: 'countries',
+    options: countriesOptions,
+  },
+  render: renderAutocompleteStory,
+  parameters: {
+    controls: {
+      include: [
+        'label',
+        'hint',
+        'errorMessage',
+        'name',
+        'optionSet',
+        'noResultsText',
+        'width',
+        'inputWidth',
+        'describedBy',
+        'isPageHeading',
+      ],
+    },
+    docs: {
+      description: {
+        story:
+          'Use the friendly controls here to explore the component with preset suggestion lists and the most useful visible props.',
+      },
+    },
+  },
 };
 
 export const WithError: Story = {
   args: {
     errorMessage: 'Select a country from the list or enter a new one.',
     hint: 'Start typing to filter the list.',
   },
+  parameters: {
+    controls: {
+      disable: true,
+    },
+    docs: {
+      description: {
+        story:
+          'Shows how the component presents a validation message above the input.',
+      },
+      source: {
+        code: withErrorStoryCode,
+      },
+    },
+  },
 };
 
 export const FixedWidth: Story = {
   args: {
     hint: 'Start typing to filter the list.',
     inputWidth: 20,
   },
+  parameters: {
+    controls: {
+      disable: true,
+    },
+    docs: {
+      description: {
+        story:
+          'Shows the fixed character-width modifier that signals the expected answer length.',
+      },
+      source: {
+        code: fixedWidthStoryCode,
+      },
+    },
+  },
 };
 
 export const CustomNoResultsText: Story = {
   args: {
     hint: 'Start typing to filter the list.',
     noResultsText: 'No matching countries. Enter a new country instead.',
   },
+  parameters: {
+    controls: {
+      disable: true,
+    },
+    docs: {
+      description: {
+        story:
+          'Shows how to override the empty-results message when you need service-specific wording.',
+      },
+      source: {
+        code: customNoResultsStoryCode,
+      },
+    },
+  },
 };