@arbor-education/design-system.components 0.25.8 → 1.0.0

package/src/components/pill/Pill.stories.tsx

@@ -50,10 +50,10 @@ const USAGE_GUIDANCE = [
   '',
   '```tsx',
   '// BAD — Pill is a filter control, not an action trigger',
-  '<Pill text="Save student" onclick={handleSave} />',
+  '<Pill text="Save student" onChange={handleSave} />',
   '',
   '// GOOD — Pill used as an auto-apply filter',
-  '<Pill text="Year 7" onclick={checked => onFilterChange("year7", checked)} />',
+  '<Pill text="Year 7" onChange={checked => onFilterChange("year7", checked)} />',
   '```',
   '',
   '---',
@@ -71,40 +71,37 @@ const USAGE_GUIDANCE = [
 ].join('\n');
 
 const DEVELOPER_NOTES = [
-  '### Quirks to know before shipping',
+  '### Controlled vs uncontrolled',
   '',
-  '**`onclick` fires on mount, not only on user interaction.** The implementation uses',
-  '`useEffect(() => { if (onclick) onclick(checked); }, [checked, onclick])`, which means React',
-  'runs it after the first render. Your handler will receive the initial `initialValue` (default',
-  '`false`) the moment the component mounts — before the user has clicked anything.',
-  '',
-  'To suppress the mount-time call, guard with a ref:',
+  '**Uncontrolled** (default) — pass `initialValue` to set the starting state and let the pill',
+  'own its checked state from there. Use `onChange` to be notified of changes without taking',
+  'ownership of the state.',
   '',
   '```tsx',
-  'const hasMounted = useRef(false);',
-  '',
-  '<Pill',
-  '  text="Autumn term"',
-  '  onclick={(checked) => {',
-  '    if (!hasMounted.current) { hasMounted.current = true; return; }',
-  '    handleFilter(checked);',
-  '  }}',
-  '/>',
+  '<Pill text="Autumn term" initialValue={false} onChange={checked => console.log(checked)} />',
   '```',
   '',
-  '**Pill is uncontrolled — there is no `value` prop.** Once mounted, its state is private.',
-  'To reset a pill from outside (e.g. a "Clear all filters" button), change its `key` prop to',
-  'force React to remount it. Note that remounting also triggers the mount-time `onclick` firing.',
+  '**Controlled** — pass `checked` to make the parent own the state. Every time `checked` changes,',
+  'the pill syncs to match. Wire `onChange` back to your state setter so clicks are reflected.',
   '',
   '```tsx',
-  'const [resetKey, setResetKey] = useState(0);',
+  'const [active, setActive] = useState(false);',
   '',
-  '<Pill key={resetKey} text="Autumn term" onclick={handleToggle} />',
-  '<Button type="button" onClick={() => setResetKey(k => k + 1)}>Clear filters</Button>',
+  '<Pill text="Autumn term" checked={active} onChange={setActive} />',
+  '<button onClick={() => setActive(false)}>Clear</button>',
   '```',
   '',
   '---',
   '',
+  '### When `onChange` fires',
+  '',
+  '`onChange` fires only in response to user interaction — a click on the pill (or its embedded',
+  'checkbox). It receives the new checked value. It does **not** fire on mount, and it does **not**',
+  'fire when the controlled `checked` prop is updated by the parent, so driving the pill externally',
+  '(e.g. a "Clear all filters" button) never re-triggers your handler.',
+  '',
+  '---',
+  '',
   '### Accessibility',
   '',
   '**Known limitation:** `Pill` renders as a `<span>` with an `onClick` handler. It is not natively',
@@ -125,7 +122,7 @@ const DEVELOPER_NOTES = [
   "    if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); handleToggle(); }",
   '  }}',
   '>',
-  '  <Pill text="Year 7" onclick={handleToggle} />',
+  '  <Pill text="Year 7" onChange={handleToggle} />',
   '</span>',
   '```',
 ].join('\n');
@@ -203,21 +200,35 @@ const meta = {
         'Sets the initial checked/active state on first mount. Defaults to `false` (inactive).',
         'Use `initialValue={true}` to pre-select a pill — for example, pre-activating an "All"',
         'pill when a filter row first loads.',
-        '**Note:** when `initialValue={true}`, the `onclick` callback fires on mount with `true`.',
+        'Only applies in uncontrolled mode; when `checked` is provided, the parent owns the state.',
       ].join(' '),
       table: {
         type: { summary: 'boolean' },
         defaultValue: { summary: 'false' },
       },
     },
-    onclick: {
+    checked: {
+      control: 'boolean',
+      description: [
+        'Makes the pill **controlled** — the parent owns the checked state.',
+        'When provided, the pill syncs to this value whenever it changes.',
+        'Pair with `onChange` so that user clicks are reflected back into your state.',
+        'Omit to use **uncontrolled** mode where `initialValue` sets the starting state',
+        'and the pill manages itself from there.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    onChange: {
       control: false,
       description: [
-        'Callback fired each time the pill\'s checked state changes.',
+        'Callback fired each time the user toggles the pill (a click on the pill or its checkbox).',
         'Receives `true` when the pill becomes active/checked, `false` when it becomes inactive.',
-        'Example: `onclick={checked => onFilterChange("year7", checked)}`.',
-        '**Quirk:** also fires on mount with the current `initialValue`. Guard with a `useRef`',
-        'if you need to suppress the mount-time call. See the component description for the pattern.',
+        'Example: `onChange={checked => onFilterChange("year7", checked)}`.',
+        'Fires only on user interaction — never on mount, and never when a controlled `checked`',
+        'prop is updated by the parent.',
       ].join(' '),
       table: {
         type: { summary: '(checked: boolean) => void' },
@@ -270,7 +281,7 @@ const FilterGroupTemplate = () => {
             key={year}
             text={year}
             initialValue={active === year}
-            onclick={checked => setActive(checked ? year : null)}
+            onChange={checked => setActive(checked ? year : null)}
           />
         ))}
       </div>
@@ -307,7 +318,7 @@ const MultiSelectFilterGroupTemplate = () => {
             key={status}
             text={status}
             checkbox
-            onclick={checked => toggle(status, checked)}
+            onChange={checked => toggle(status, checked)}
           />
         ))}
       </div>
@@ -359,14 +370,14 @@ const WithAllOptionTemplate = () => {
         <Pill
           text="All"
           initialValue={allActive}
-          onclick={handleAllClick}
+          onChange={handleAllClick}
         />
         {subjects.map(subject => (
           <Pill
             key={subject}
             text={subject}
             initialValue={activeFilters.has(subject)}
-            onclick={checked => handleSubjectClick(subject, checked)}
+            onChange={checked => handleSubjectClick(subject, checked)}
           />
         ))}
       </div>
@@ -374,6 +385,77 @@ const WithAllOptionTemplate = () => {
   );
 };
 
+const UncontrolledTemplate = () => {
+  const [lastValue, setLastValue] = useState<boolean | null>(null);
+
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Pill owns its own state — parent only observes via
+        {' '}
+        <code>onChange</code>
+        .
+      </p>
+      <Pill text="Autumn term" initialValue={false} onChange={v => setLastValue(v)} />
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        Last
+        {' '}
+        <code>onChange</code>
+        {': '}
+        <code>{lastValue === null ? '(not fired yet)' : String(lastValue)}</code>
+      </p>
+    </div>
+  );
+};
+
+const ControlledTemplate = () => {
+  const [isChecked, setIsChecked] = useState(false);
+
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Parent owns the state — click the pill or the external button to observe they stay in sync.
+      </p>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)', alignItems: 'center' }}>
+        <Pill text="Autumn term" checked={isChecked} onChange={setIsChecked} />
+        <button
+          type="button"
+          style={{
+            padding: 'var(--spacing-xsmall) var(--spacing-medium)',
+            border: 'var(--border-weight) solid var(--color-grey-300)',
+            borderRadius: 'var(--border-radius-small)',
+            background: 'var(--color-white)',
+            cursor: 'pointer',
+            fontSize: 'var(--font-size-1-13)',
+          }}
+          onClick={() => setIsChecked(v => !v)}
+        >
+          Toggle from outside
+        </button>
+        <button
+          type="button"
+          style={{
+            padding: 'var(--spacing-xsmall) var(--spacing-medium)',
+            border: 'var(--border-weight) solid var(--color-grey-300)',
+            borderRadius: 'var(--border-radius-small)',
+            background: 'var(--color-white)',
+            cursor: 'pointer',
+            fontSize: 'var(--font-size-1-13)',
+          }}
+          onClick={() => setIsChecked(false)}
+        >
+          Reset
+        </button>
+      </div>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        External state:
+        {' '}
+        <code>{String(isChecked)}</code>
+      </p>
+    </div>
+  );
+};
+
 const AllVariantsTemplate = () => (
   <div
     style={{
@@ -539,6 +621,133 @@ const AccessibilityNoteTemplate = () => (
   </div>
 );
 
+const OnChangeBehaviourTemplate = () => {
+  const [log, setLog] = useState<boolean[]>([]);
+
+  const handleChange = (value: boolean) => {
+    setLog(prev => [value, ...prev]);
+  };
+
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Click the pill. Each click fires `onChange` with the new value — nothing is logged until
+        you interact.
+      </p>
+      <Pill text="Autumn term" onChange={handleChange} />
+      <div
+        style={{
+          border: '1px solid var(--color-grey-300)',
+          borderRadius: 'var(--border-radius-small)',
+          padding: 'var(--spacing-small)',
+          minHeight: '4rem',
+          maxHeight: '12rem',
+          overflowY: 'auto',
+          background: 'var(--color-grey-050)',
+        }}
+      >
+        {log.length === 0
+          ? (
+              <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+                Waiting for events...
+              </p>
+            )
+          : (
+              log.map((value, i) => (
+                <p
+                  key={i}
+                  className="ds-text"
+                  style={{ margin: '0 0 var(--spacing-xsmall)' }}
+                >
+                  {`onChange(${String(value)})`}
+                </p>
+              ))
+            )}
+      </div>
+    </div>
+  );
+};
+
+const SUBJECTS = ['Maths', 'English', 'Science', 'History', 'Art', 'French', 'PE'];
+
+const ControlledCheckboxModeTemplate = () => {
+  const [selected, setSelected] = useState<string[]>(['Maths', 'Science']);
+
+  const toggle = (subject: string) => {
+    setSelected(prev =>
+      prev.includes(subject)
+        ? prev.filter(s => s !== subject)
+        : [...prev, subject],
+    );
+  };
+
+  return (
+    <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Parent owns a string[] of selected subjects and passes
+        {' '}
+        <code>
+          checked=
+          {'{selected.includes(subject)}'}
+        </code>
+        {' '}
+        to each pill.
+      </p>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+        {SUBJECTS.map(subject => (
+          <Pill
+            key={subject}
+            text={subject}
+            checkbox
+            checked={selected.includes(subject)}
+            onChange={() => toggle(subject)}
+          />
+        ))}
+      </div>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }}>
+        {selected.length === 0 ? 'No subjects selected' : `Subjects: ${selected.join(', ')}`}
+      </p>
+    </div>
+  );
+};
+
+const ALL_PILLS = [
+  'Year 7', 'Year 8', 'Year 9', 'Year 10', 'Year 11', 'Year 12', 'Year 13',
+  'Maths', 'English', 'Science', 'History', 'Art', 'French', 'PE', 'PE', 'Drama',
+];
+
+const PillGroupWrappingTemplate = () => (
+  <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+    <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+      16 pills in a 380px container — the consumer&apos;s flex wrapper is what makes them wrap.
+      Pills themselves are
+      {' '}
+      <code>width: fit-content</code>
+      {' '}
+      and will overflow without
+      {' '}
+      <code>flex-wrap: wrap</code>
+      {' '}
+      on the parent.
+    </p>
+    <div
+      style={{
+        maxWidth: '380px',
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: 'var(--spacing-small)',
+        padding: 'var(--spacing-small)',
+        border: '1px dashed var(--color-grey-300)',
+        borderRadius: 'var(--border-radius-small)',
+      }}
+    >
+      {ALL_PILLS.map((label, i) => (
+        <Pill key={`${label}-${i}`} text={label} />
+      ))}
+    </div>
+  </div>
+);
+
 // ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
@@ -549,11 +758,73 @@ export const Default: Story = withDescription(
       text: 'Year 7',
       checkbox: false,
       initialValue: false,
-      onclick: fn(),
+      onChange: fn(),
     },
     render: args => <Pill {...args} />,
   },
-  'The interactive canvas. Every prop is wired to the Controls panel below — toggle `checkbox` to switch between single-select and multi-select modes, toggle `initialValue` to start in the active/checked state. The `onclick` callback fires into the Actions panel on every state change.',
+  'The interactive canvas. Every prop is wired to the Controls panel below — toggle `checkbox` to switch between single-select and multi-select modes, toggle `initialValue` to start in the active/checked state. The `onChange` callback fires into the Actions panel on every state change.',
+);
+
+export const Uncontrolled: Story = withDescription(
+  {
+    render: UncontrolledTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Pill } from '@arbor-education/design-system.components';
+
+function UncontrolledExample() {
+  const [lastValue, setLastValue] = useState<boolean | null>(null);
+
+  return (
+    <>
+      <Pill text="Autumn term" initialValue={false} onChange={v => setLastValue(v)} />
+      <p>Last onChange: {lastValue === null ? '(not fired yet)' : String(lastValue)}</p>
+    </>
+  );
+}
+export default UncontrolledExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The pill owns its own checked state — `initialValue` seeds it on first mount and the pill manages itself from there. The parent observes changes via `onChange` but does NOT hold the source of truth. Click the pill to toggle it; the last `onChange` value echoes below.',
+);
+
+export const Controlled: Story = withDescription(
+  {
+    render: ControlledTemplate,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Pill } from '@arbor-education/design-system.components';
+
+function ControlledExample() {
+  const [isChecked, setIsChecked] = useState(false);
+
+  return (
+    <>
+      <Pill text="Autumn term" checked={isChecked} onChange={setIsChecked} />
+      <button type="button" onClick={() => setIsChecked(v => !v)}>Toggle from outside</button>
+      <button type="button" onClick={() => setIsChecked(false)}>Reset</button>
+      <p>External state: {String(isChecked)}</p>
+    </>
+  );
+}
+export default ControlledExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The parent holds the source of truth via `checked` + `onChange`. Clicking the pill fires `onChange` → parent updates its state → `checked` prop changes → pill syncs. The external "Toggle from outside" button demonstrates that the parent can drive the pill\'s state independently of user clicks. Use this pattern when you need to reset or synchronise pills from elsewhere in your UI (e.g. a "Clear all filters" button).',
 );
 
 export const ToggleActive: Story = withDescription(
@@ -689,7 +960,7 @@ function YearGroupFilter() {
           key={year}
           text={year}
           initialValue={active === year}
-          onclick={checked => setActive(checked ? year : null)}
+          onChange={checked => setActive(checked ? year : null)}
         />
       ))}
     </div>
@@ -735,7 +1006,7 @@ function StatusFilter() {
           key={status}
           text={status}
           checkbox
-          onclick={checked => toggle(status, checked)}
+          onChange={checked => toggle(status, checked)}
         />
       ))}
     </div>
@@ -787,13 +1058,13 @@ function SubjectFilter() {
 
   return (
     <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
-      <Pill text="All" initialValue={allActive} onclick={handleAllClick} />
+      <Pill text="All" initialValue={allActive} onChange={handleAllClick} />
       {subjects.map(subject => (
         <Pill
           key={subject}
           text={subject}
           initialValue={activeFilters.has(subject)}
-          onclick={checked => handleSubjectClick(subject, checked)}
+          onChange={checked => handleSubjectClick(subject, checked)}
         />
       ))}
     </div>
@@ -875,3 +1146,123 @@ export default AccessibilityNoteExample;
   },
   '**Read before shipping to production.** Toggle-mode `Pill` is not keyboard-accessible — it renders as `<span onClick>` with no `tabIndex` or ARIA role. Checkbox mode IS accessible. This story documents the limitation and shows an accessible checkbox-mode example you can interact with via keyboard. See the component description for the toggle-mode wrapper workaround.',
 );
+
+export const OnChangeBehaviour: Story = withDescription(
+  {
+    render: OnChangeBehaviourTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Pill } from '@arbor-education/design-system.components';
+
+function PillOnChangeLog() {
+  const [log, setLog] = useState<boolean[]>([]);
+
+  return (
+    <>
+      <Pill
+        text="Autumn term"
+        onChange={checked => setLog(prev => [checked, ...prev])}
+      />
+      <ul>
+        {log.map((value, i) => <li key={i}>onChange({String(value)})</li>)}
+      </ul>
+    </>
+  );
+}
+export default PillOnChangeLog;
+`.trim(),
+        },
+      },
+    },
+  },
+  '`onChange` fires only on user interaction — once per click, with the new checked value. Nothing is logged until you click the pill: it does not fire on mount, and it does not fire when a controlled `checked` prop is updated by the parent. Wire it straight to a filter handler or state setter without needing a mount guard.',
+);
+
+export const ControlledCheckboxMode: Story = withDescription(
+  {
+    render: ControlledCheckboxModeTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Pill } from '@arbor-education/design-system.components';
+
+const SUBJECTS = ['Maths', 'English', 'Science', 'History', 'Art', 'French', 'PE'];
+
+function SubjectFilter() {
+  const [selected, setSelected] = useState<string[]>(['Maths', 'Science']);
+
+  const toggle = (subject: string) => {
+    setSelected(prev =>
+      prev.includes(subject)
+        ? prev.filter(s => s !== subject)
+        : [...prev, subject],
+    );
+  };
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+      {SUBJECTS.map(subject => (
+        <Pill
+          key={subject}
+          text={subject}
+          checkbox
+          checked={selected.includes(subject)}
+          onChange={() => toggle(subject)}
+        />
+      ))}
+    </div>
+  );
+}
+export default SubjectFilter;
+`.trim(),
+        },
+      },
+    },
+  },
+  'The canonical controlled multi-select pattern. The parent holds a `string[]` of selected subjects and passes `checked={selected.includes(subject)}` to each pill. `onChange` updates the array. Use this when filter state needs to live outside the component — e.g. in a URL param, a form, or a shared store. Two subjects are pre-selected to demonstrate the starting state.',
+);
+
+export const PillGroupWrapping: Story = withDescription(
+  {
+    render: PillGroupWrappingTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Pill } from '@arbor-education/design-system.components';
+
+function FilterPillGroup() {
+  const labels = [
+    'Year 7', 'Year 8', 'Year 9', 'Year 10', 'Year 11', 'Year 12', 'Year 13',
+    'Maths', 'English', 'Science', 'History', 'Art',
+  ];
+
+  // flex-wrap: wrap on the PARENT is what makes pills wrap.
+  // Pills themselves are width: fit-content and will overflow without it.
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }}>
+      {labels.map(label => (
+        <Pill key={label} text={label} />
+      ))}
+    </div>
+  );
+}
+export default FilterPillGroup;
+`.trim(),
+        },
+      },
+    },
+  },
+  'Pills must wrap — never scroll horizontally. The wrapper here is constrained to 380px so you can see the wrapping in action. In production the container width comes from the page layout. The key CSS is `display: flex; flex-wrap: wrap; gap: var(--spacing-small)` on the **parent** — Pill itself is `width: fit-content` and will overflow without it.',
+);