@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/searchBar/SearchBar.stories.tsx

@@ -1,40 +1,228 @@
-import { useEffect, useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { useEffect, useState } from 'react';
 import { SearchBar } from './SearchBar';
 
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'SearchBar is a space-efficient search input that starts collapsed — showing only a search icon or a',
+  'short label — and expands into a full text input when clicked. It is designed for use in navigation',
+  'bars, table headers, and other space-constrained contexts where search is a secondary action.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Table headers** — filter a data table without dominating the header layout',
+  '- **Navigation bars** — compact global search that expands on demand',
+  '- **Space-constrained sidebars** — secondary search that should not distract from primary content',
+  '- **Any context where search is optional** — consumers can click to open or ignore it entirely',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Search is the primary action on the page | A full-width `TextInput` with a visible label — always-visible inputs reduce cognitive load when search is the main task |',
+  '| Search drives a list of suggested results | [`Combobox`](?path=/docs/components-combobox--docs) — it handles filtering + suggestions + keyboard selection |',
+  '| You need a labelled form field with validation | [`FormField`](?path=/docs/components-formfield--docs) — SearchBar has no label or error state |',
+  '| The input must always be visible | Set `alwaysOpen` to `true` — or use a plain `TextInput` if you also need a label |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`searchValue` and `setSearchValue` are a controlled pair.** Always pass both. Passing `searchValue`',
+  'without `setSearchValue` creates a frozen input — the user can see the value but typing has no effect.',
+  'Passing `setSearchValue` without `searchValue` will work but leaves state management up to an',
+  'anonymous internal variable, which makes reset and restore difficult.',
+  '',
+  '**`alwaysOpen` removes the clear button entirely.** When `alwaysOpen` is `true`, the component never',
+  'shows the collapsed state AND never renders the clear (×) button. There is no built-in way for the',
+  'user to clear the input. If you use `alwaysOpen`, add an external "Reset" button or clear link in your',
+  'UI and call `setSearchValue(\'\')` programmatically.',
+  '',
+  '**Non-empty `searchValue` forces the expanded state on mount.** If your page restores filter state',
+  'from a URL parameter or localStorage, passing a pre-filled `searchValue` will start the component',
+  'expanded — no flash of the collapsed button. This is intentional behaviour, not a side-effect.',
+  '',
+  '**`placeholderText` and `hoverText` label the COLLAPSED BUTTON, not the `<input>`.** They appear',
+  'only in the inactive state. The expanded `<input>` has no visible placeholder — it uses',
+  '`aria-label="Search input"` for accessibility.',
+  '',
+  '**`hoverText` swaps in on hover of the collapsed button.** When the user mouses away, the component',
+  'reverts to `placeholderText` (or an icon-only state if `placeholderText` is not set). This is a',
+  'hover-only affordance — there is no keyboard-equivalent of the hover swap.',
+  '',
+  '**Theming.** SearchBar is designed for brand-coloured and dark backgrounds. Its default background,',
+  'icon, and text colours use the `--search-global-*` token family. If you are placing it on a white or',
+  'light-grey background, override these tokens to ensure sufficient contrast:',
+  '',
+  '| Token | Controls |',
+  '|---|---|',
+  '| `--search-global-default-color-background` | Resting background |',
+  '| `--search-global-hover-color-background` | Hover background |',
+  '| `--search-global-focus-color-background` | Expanded/focused background |',
+  '| `--search-global-default-color-icon` | Search icon colour at rest |',
+  '| `--search-global-hover-color-icon` | Search icon colour on hover |',
+  '| `--search-global-focus-color-icon` | Search icon colour when active |',
+  '| `--search-global-default-color-text` | Placeholder and label text colour |',
+  '| `--search-global-radius` | Border radius of the component |',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The collapsed state renders a `<button>` — fully keyboard-operable and screen-reader-accessible',
+  '- The expanded `<input>` has `aria-label="Search input"` — do not add a visible `<label>` externally',
+  '- The clear button has `aria-label="Clear search"` and responds to `Enter` and `Space` in addition to click',
+  '- The search icon in the expanded state has `screenReaderText="Search icon"` rendered as a visually hidden span',
+  '- There is no `role="search"` landmark on the component — wrap in `<form role="search">` if you need a search landmark',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Combobox](?path=/docs/components-combobox--docs) · [Table](?path=/docs/components-table--docs) · [FormField](?path=/docs/components-formfield--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+function SearchBarDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
 const meta = {
   title: 'Components/SearchBar',
   component: SearchBar,
+  tags: ['autodocs'],
   parameters: {
     layout: 'padded',
+    docs: {
+      page: SearchBarDocsPage,
+    },
   },
-  tags: ['autodocs'],
   argTypes: {
     searchValue: {
       control: 'text',
-      description: 'The current search input value',
+      description: [
+        'The controlled value of the search input.',
+        'If non-empty on mount, the component starts in the expanded state.',
+        'Always pair with `setSearchValue`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     setSearchValue: {
-      action: 'search value changed',
-      description: 'Callback fired when the search input changes',
+      control: false,
+      action: 'setSearchValue',
+      description: [
+        'Callback fired when the search input changes and when the clear button is clicked.',
+        'Always pair with `searchValue`. Omitting this creates a frozen, non-interactive input.',
+      ].join(' '),
+      table: {
+        type: { summary: '(searchValue: string) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     placeholderText: {
       control: 'text',
-      description: 'Text displayed in the inactive/collapsed state',
+      description: [
+        'Label text displayed inside the collapsed (inactive) button beside the search icon.',
+        'This is NOT the HTML input placeholder — it labels the collapsed button state only.',
+        'When absent, the collapsed button shows an icon only.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     hoverText: {
       control: 'text',
-      description: 'Text displayed when hovering the inactive state',
+      description: [
+        'Text shown in the collapsed button when the user hovers over it.',
+        'Replaces `placeholderText` on hover and reverts on mouse-leave.',
+        'Only active in the collapsed (inactive) state — has no effect when expanded.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
     },
     alwaysOpen: {
       control: 'boolean',
-      description: 'Whether the search bar should be always open',
+      description: [
+        'When `true`, the component renders permanently expanded and the clear (×) button is hidden.',
+        'The collapsed button state is never shown. The consumer is responsible for clearing the',
+        'search value externally — there is no built-in clear affordance.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
   },
 } satisfies Meta<typeof SearchBar>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SearchBar>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components — all stories need local state because SearchBar is
+// a fully controlled component. Without useState the input is frozen.
+// ---------------------------------------------------------------------------
 
 const InteractiveSearchBar = (args: React.ComponentProps<typeof SearchBar>) => {
   const [value, setValue] = useState(args.searchValue ?? '');
@@ -44,43 +232,387 @@ const InteractiveSearchBar = (args: React.ComponentProps<typeof SearchBar>) => {
   return <SearchBar {...args} searchValue={value} setSearchValue={setValue} />;
 };
 
-export const Default: Story = {
-  render: args => <InteractiveSearchBar {...args} />,
+const WithPlaceholderTextTemplate = () => {
+  const [value, setValue] = useState('');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        placeholderText="Search pupils"
+      />
+    </div>
+  );
 };
 
-export const WithPlaceholder: Story = {
-  render: args => <InteractiveSearchBar {...args} />,
-  args: {
-    placeholderText: 'Search...',
-  },
+const WithHoverTextTemplate = () => {
+  const [value, setValue] = useState('');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        placeholderText="Search pupils"
+        hoverText="Search all pupils and staff"
+      />
+    </div>
+  );
 };
 
-export const WithHoverText: Story = {
-  render: args => <InteractiveSearchBar {...args} />,
-  args: {
-    placeholderText: 'Search...',
-    hoverText: 'Start searching',
-  },
+const WithHoverTextOnlyTemplate = () => {
+  const [value, setValue] = useState('');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        hoverText="Search pupils"
+      />
+    </div>
+  );
 };
 
-export const WithHoverTextNoPlaceholder: Story = {
-  render: args => <InteractiveSearchBar {...args} />,
-  args: {
-    hoverText: 'Start searching',
-  },
+const WithSearchValueTemplate = () => {
+  const [value, setValue] = useState('Emily Johnson');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        placeholderText="Search pupils"
+      />
+    </div>
+  );
 };
 
-export const WithSearchValue: Story = {
-  render: args => <InteractiveSearchBar {...args} />,
-  args: {
-    searchValue: 'Jacob Black',
-    placeholderText: 'Search...',
-  },
+const AlwaysOpenTemplate = () => {
+  const [value, setValue] = useState('');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        alwaysOpen
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-mono-white)', fontSize: '0.875rem' }}>
+        Note: no clear button — the × icon is absent when alwaysOpen is true.
+      </p>
+    </div>
+  );
 };
 
-export const AlwaysOpen: Story = {
-  render: args => <InteractiveSearchBar {...args} />,
-  args: {
-    alwaysOpen: true,
-  },
+const AlwaysOpenWithValueTemplate = () => {
+  const [value, setValue] = useState('Year 8');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        alwaysOpen
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-mono-white)', fontSize: '0.875rem' }}>
+        Pre-filled value with no clear button — the consumer must provide external clearing.
+      </p>
+    </div>
+  );
+};
+
+const ControlledByParentTemplate = () => {
+  const [value, setValue] = useState('');
+  return (
+    <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        placeholderText="Search reports"
+      />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-mono-white)', fontSize: '0.875rem' }}>
+        {value
+          ? `Active filter: "${value}" — ${value.length} character${value.length === 1 ? '' : 's'}`
+          : 'No active filter — click the search icon and start typing'}
+      </p>
+    </div>
+  );
 };
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      placeholderText: 'Search',
+      alwaysOpen: false,
+    },
+    render: args => (
+      <div style={{ background: 'var(--color-brand-600)', padding: 'var(--spacing-xlarge)' }}>
+        <InteractiveSearchBar {...args} />
+      </div>
+    ),
+  },
+  [
+    'The interactive canvas — every prop is wired to the Controls panel below.',
+    'Click the search icon to expand the input. The story background is brand-coloured to reflect the',
+    'real-world context (navigation bars, table headers) where SearchBar is designed to be used.',
+  ].join(' '),
+);
+
+export const WithPlaceholderText: Story = withDescription(
+  {
+    render: WithPlaceholderTextTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+function PupilSearchExample() {
+  const [value, setValue] = useState('');
+  return (
+    <SearchBar
+      searchValue={value}
+      setSearchValue={setValue}
+      placeholderText="Search pupils"
+    />
+  );
+}
+export default PupilSearchExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`placeholderText` adds a label beside the search icon in the collapsed state — making the affordance',
+    'explicit without taking up much space. Click the label to expand the full input.',
+    'Note: this is a label on the collapsed button, not the HTML `placeholder` attribute on the input.',
+  ].join(' '),
+);
+
+export const WithHoverText: Story = withDescription(
+  {
+    render: WithHoverTextTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+function PupilSearchWithHoverExample() {
+  const [value, setValue] = useState('');
+  return (
+    <SearchBar
+      searchValue={value}
+      setSearchValue={setValue}
+      placeholderText="Search pupils"
+      hoverText="Search all pupils and staff"
+    />
+  );
+}
+export default PupilSearchWithHoverExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'When both `placeholderText` and `hoverText` are set, the label swaps to `hoverText` on mouse-enter',
+    'and reverts to `placeholderText` on mouse-leave. Hover the icon to see the swap.',
+    'This is a hover-only affordance — keyboard users always see `placeholderText`.',
+  ].join(' '),
+);
+
+export const WithHoverTextOnly: Story = withDescription(
+  {
+    render: WithHoverTextOnlyTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+function IconOnlySearchExample() {
+  const [value, setValue] = useState('');
+  return (
+    <SearchBar
+      searchValue={value}
+      setSearchValue={setValue}
+      hoverText="Search pupils"
+    />
+  );
+}
+export default IconOnlySearchExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'When `placeholderText` is absent but `hoverText` is set, the button shows an icon only at rest.',
+    'Hovering reveals the label text. This pattern works well in very narrow navigation bars where',
+    'every pixel counts — the icon provides the affordance at rest and hover confirms the action.',
+  ].join(' '),
+);
+
+export const WithSearchValue: Story = withDescription(
+  {
+    render: WithSearchValueTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+// Restore a previously entered search value from URL params or session storage.
+// Passing a non-empty searchValue starts the component in the expanded state.
+function RestoredSearchExample() {
+  const [value, setValue] = useState('Emily Johnson');
+  return (
+    <SearchBar
+      searchValue={value}
+      setSearchValue={setValue}
+      placeholderText="Search pupils"
+    />
+  );
+}
+export default RestoredSearchExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Passing a non-empty `searchValue` starts the component expanded — no flash of the collapsed button.',
+    'This is the correct pattern for restoring filter state from URL parameters or local storage.',
+    'The clear (×) button is visible and clears both the value and collapses the input.',
+  ].join(' '),
+);
+
+export const AlwaysOpen: Story = withDescription(
+  {
+    render: AlwaysOpenTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+// alwaysOpen=true: permanently expanded, no clear button.
+// Wire up an external reset mechanism if users need to clear.
+function PersistentSearchExample() {
+  const [value, setValue] = useState('');
+  return (
+    <SearchBar
+      searchValue={value}
+      setSearchValue={setValue}
+      alwaysOpen
+    />
+  );
+}
+export default PersistentSearchExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`alwaysOpen` keeps the input permanently expanded and **removes the clear (×) button entirely**.',
+    'The collapsed button state is never shown. Use this in sidebars or fixed layouts where search is',
+    'always visible. Because there is no built-in clear affordance, add an external "Reset" button or',
+    'call `setSearchValue(\'\')` from your own UI when the user wants to clear.',
+  ].join(' '),
+);
+
+export const AlwaysOpenWithValue: Story = withDescription(
+  {
+    render: AlwaysOpenWithValueTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+// alwaysOpen + pre-filled value: expanded with no collapse or clear affordance.
+// The consumer is responsible for all value management.
+function PersistentFilteredSearchExample() {
+  const [value, setValue] = useState('Year 8');
+  return (
+    <SearchBar
+      searchValue={value}
+      setSearchValue={setValue}
+      alwaysOpen
+    />
+  );
+}
+export default PersistentFilteredSearchExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`alwaysOpen` combined with a pre-filled `searchValue` — the component starts expanded with a value',
+    'and no way for the user to clear it through the component itself.',
+    'This combination is appropriate when an external "Reset filters" action exists in the parent UI.',
+  ].join(' '),
+);
+
+export const ControlledByParent: Story = withDescription(
+  {
+    render: ControlledByParentTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { SearchBar } from '@arbor-education/design-system.components';
+
+// Always provide both searchValue and setSearchValue together.
+// The parent owns the state — SearchBar is a fully controlled component.
+function ReportSearchExample() {
+  const [value, setValue] = useState('');
+  return (
+    <div>
+      <SearchBar
+        searchValue={value}
+        setSearchValue={setValue}
+        placeholderText="Search reports"
+      />
+      {value && <p>Filtering by: "{value}"</p>}
+    </div>
+  );
+}
+export default ReportSearchExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The controlled pattern: the parent component owns `searchValue` state and passes both `searchValue`',
+    'and `setSearchValue` to SearchBar. The live value is displayed below — showing how a table filter,',
+    'URL parameter, or analytics event would respond to the search.',
+    'Click the search icon, type, and watch the status text update on every keystroke.',
+  ].join(' '),
+);