@arbor-education/design-system.components 0.25.9 → 1.0.1

package/dist/components/pill/Pill.js

@@ -2,20 +2,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import classNames from 'classnames';
 import { CheckboxInput } from '../formField/inputs/checkbox/CheckboxInput.js';
 import { useEffect, useState } from 'react';
-export const Pill = ({ text, checkbox, onclick, initialValue = false }) => {
-    const [checked, setChecked] = useState(initialValue);
+export const Pill = (props) => {
+    const { text, checkbox, onChange, initialValue = false, checked: controlledChecked, } = props;
+    const [checked, setChecked] = useState(controlledChecked ?? initialValue);
+    useEffect(() => {
+        if (typeof controlledChecked !== 'undefined') {
+            setChecked(!!controlledChecked);
+        }
+    }, [controlledChecked]);
+    const toggle = () => {
+        const next = !checked;
+        setChecked(next);
+        onChange?.(next);
+    };
     const handlePillClick = () => {
-        setChecked(prev => !prev);
+        toggle();
     };
     const handleCheckboxClick = (event) => {
         event.stopPropagation();
-        setChecked(prev => !prev);
+        toggle();
     };
-    useEffect(() => {
-        if (onclick) {
-            onclick(checked);
-        }
-    }, [checked, onclick]);
     return (_jsxs("span", { onClick: handlePillClick, className: classNames('ds-pill', checkbox ? { 'ds-pill__checked': checked, 'ds-pill__unchecked': !checked } : { 'ds-pill__active': checked, 'ds-pill__inactive': !checked }), children: [checkbox && (_jsx("span", { className: classNames('ds-pill__checkbox'), onClick: e => e.stopPropagation(), children: _jsx(CheckboxInput, { checked: checked, onChange: () => { }, onClick: handleCheckboxClick }) })), text] }));
 };
 //# sourceMappingURL=Pill.js.map

package/dist/components/pill/Pill.js.map

@@ -1 +1 @@
-{"version":3,"file":"Pill.js","sourceRoot":"","sources":["../../../src/components/pill/Pill.tsx"],"names":[],"mappings":";AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAS5C,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,GAAG,KAAK,EAAa,EAAE,EAAE;IACnF,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAErD,MAAM,eAAe,GAAG,GAAG,EAAE;QAC3B,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,MAAM,mBAAmB,GAAG,CAAC,KAAuB,EAAE,EAAE;QACtD,KAAK,CAAC,eAAe,EAAE,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,OAAO,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAEvB,OAAO,CACL,gBACE,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,UAAU,CACnB,SAAS,EACT,QAAQ,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAC3I,aAEA,QAAQ,IAAI,CACX,eAAM,SAAS,EAAE,UAAU,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,EAAE,YACjF,KAAC,aAAa,IACZ,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC,EAClB,OAAO,EAAE,mBAAmB,GAC5B,GACG,CACR,EACA,IAAI,IACA,CACR,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"Pill.js","sourceRoot":"","sources":["../../../src/components/pill/Pill.tsx"],"names":[],"mappings":";AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAU5C,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAgB,EAAE,EAAE;IACvC,MAAM,EACJ,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,YAAY,GAAG,KAAK,EACpB,OAAO,EAAE,iBAAiB,GAC3B,GAAG,KAAK,CAAC;IAEV,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,iBAAiB,IAAI,YAAY,CAAC,CAAC;IAE1E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,iBAAiB,KAAK,WAAW,EAAE,CAAC;YAC7C,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAExB,MAAM,MAAM,GAAG,GAAG,EAAE;QAClB,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC;QACtB,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC;IAEF,MAAM,eAAe,GAAG,GAAG,EAAE;QAC3B,MAAM,EAAE,CAAC;IACX,CAAC,CAAC;IAEF,MAAM,mBAAmB,GAAG,CAAC,KAAuB,EAAE,EAAE;QACtD,KAAK,CAAC,eAAe,EAAE,CAAC;QACxB,MAAM,EAAE,CAAC;IACX,CAAC,CAAC;IAEF,OAAO,CACL,gBACE,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,UAAU,CACnB,SAAS,EACT,QAAQ,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAC3I,aAEA,QAAQ,IAAI,CACX,eAAM,SAAS,EAAE,UAAU,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,EAAE,YACjF,KAAC,aAAa,IACZ,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC,EAClB,OAAO,EAAE,mBAAmB,GAC5B,GACG,CACR,EACA,IAAI,IACA,CACR,CAAC;AACJ,CAAC,CAAC"}

package/dist/components/pill/Pill.stories.d.ts

@@ -3,11 +3,12 @@ import { Pill } from './Pill.js';
 declare function PillDocsPage(): import("react/jsx-runtime").JSX.Element;
 declare const meta: {
     title: string;
-    component: ({ text, checkbox, onclick, initialValue }: {
+    component: (props: {
         text: string;
         initialValue?: boolean;
         checkbox?: boolean;
-        onclick?: (checked: boolean) => void;
+        onChange?: (checked: boolean) => void;
+        checked?: boolean;
     }) => import("react/jsx-runtime").JSX.Element;
     tags: string[];
     parameters: {
@@ -49,7 +50,19 @@ declare const meta: {
                 };
             };
         };
-        onclick: {
+        checked: {
+            control: "boolean";
+            description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        onChange: {
             control: false;
             description: string;
             table: {
@@ -66,6 +79,8 @@ declare const meta: {
 export default meta;
 type Story = StoryObj<typeof Pill>;
 export declare const Default: Story;
+export declare const Uncontrolled: Story;
+export declare const Controlled: Story;
 export declare const ToggleActive: Story;
 export declare const CheckboxMode: Story;
 export declare const CheckboxModeSelected: Story;
@@ -75,4 +90,7 @@ export declare const MultiSelectFilterGroup: Story;
 export declare const WithAllOption: Story;
 export declare const ContentGuidelines: Story;
 export declare const AccessibilityNote: Story;
+export declare const OnChangeBehaviour: Story;
+export declare const ControlledCheckboxMode: Story;
+export declare const PillGroupWrapping: Story;
 //# sourceMappingURL=Pill.stories.d.ts.map

package/dist/components/pill/Pill.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pill.stories.d.ts","sourceRoot":"","sources":["../../../src/components/pill/Pill.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAY5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgIjC,iBAAS,YAAY,4CAmBpB;AAMD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DmB,CAAC;AAE9B,eAAe,IAAI,CAAC;AAIpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAwTnC,eAAO,MAAM,OAAO,EAAE,KAWrB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KAuB1B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KAuB1B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAwBlC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAiCzB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAmCzB,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,KA4CpC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KAwD3B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KAqC/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KA2B/B,CAAC"}
+{"version":3,"file":"Pill.stories.d.ts","sourceRoot":"","sources":["../../../src/components/pill/Pill.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAY5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA6HjC,iBAAS,YAAY,4CAmBpB;AAMD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EmB,CAAC;AAE9B,eAAe,IAAI,CAAC;AAIpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AA8fnC,eAAO,MAAM,OAAO,EAAE,KAWrB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KA4B1B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KA8BxB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KAuB1B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,KAuB1B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAwBlC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAiCzB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAmCzB,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,KA4CpC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,KAwD3B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KAqC/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KA2B/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KAkC/B,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,KA8CpC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,KAkC/B,CAAC"}

package/dist/components/pill/Pill.stories.js

@@ -39,10 +39,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)} />',
     '```',
     '',
     '---',
@@ -59,40 +59,37 @@ const USAGE_GUIDANCE = [
     '  dedicated "Apply filters" submit button.',
 ].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',
@@ -113,7 +110,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');
@@ -169,21 +166,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' },
@@ -214,7 +225,7 @@ const withDescription = (story, description) => ({
 const FilterGroupTemplate = () => {
     const [active, setActive] = useState(null);
     const yearGroups = ['Year 7', 'Year 8', 'Year 9', 'Year 10', 'Year 11'];
-    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Filter by year group" }), _jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: yearGroups.map(year => (_jsx(Pill, { text: year, initialValue: active === year, onclick: checked => setActive(checked ? year : null) }, year))) })] }));
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Filter by year group" }), _jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: yearGroups.map(year => (_jsx(Pill, { text: year, initialValue: active === year, onChange: checked => setActive(checked ? year : null) }, year))) })] }));
 };
 const MultiSelectFilterGroupTemplate = () => {
     const [selected, setSelected] = useState(new Set());
@@ -231,7 +242,7 @@ const MultiSelectFilterGroupTemplate = () => {
             return next;
         });
     };
-    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Filter by status" }), _jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: statuses.map(status => (_jsx(Pill, { text: status, checkbox: true, onclick: checked => toggle(status, checked) }, status))) }), selected.size > 0 && (_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: ["Selected:", ' ', Array.from(selected).join(', ')] }))] }));
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Filter by status" }), _jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: statuses.map(status => (_jsx(Pill, { text: status, checkbox: true, onChange: checked => toggle(status, checked) }, status))) }), selected.size > 0 && (_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: ["Selected:", ' ', Array.from(selected).join(', ')] }))] }));
 };
 const WithAllOptionTemplate = () => {
     const [activeFilters, setActiveFilters] = useState(new Set());
@@ -257,7 +268,29 @@ const WithAllOptionTemplate = () => {
         }
         setActiveFilters(next);
     };
-    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Filter by subject" }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: [_jsx(Pill, { text: "All", initialValue: allActive, onclick: handleAllClick }), subjects.map(subject => (_jsx(Pill, { text: subject, initialValue: activeFilters.has(subject), onclick: checked => handleSubjectClick(subject, checked) }, subject)))] })] }));
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Filter by subject" }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: [_jsx(Pill, { text: "All", initialValue: allActive, onChange: handleAllClick }), subjects.map(subject => (_jsx(Pill, { text: subject, initialValue: activeFilters.has(subject), onChange: checked => handleSubjectClick(subject, checked) }, subject)))] })] }));
+};
+const UncontrolledTemplate = () => {
+    const [lastValue, setLastValue] = useState(null);
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Pill owns its own state \u2014 parent only observes via", ' ', _jsx("code", { children: "onChange" }), "."] }), _jsx(Pill, { text: "Autumn term", initialValue: false, onChange: v => setLastValue(v) }), _jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: ["Last", ' ', _jsx("code", { children: "onChange" }), ': ', _jsx("code", { children: lastValue === null ? '(not fired yet)' : String(lastValue) })] })] }));
+};
+const ControlledTemplate = () => {
+    const [isChecked, setIsChecked] = useState(false);
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Parent owns the state \u2014 click the pill or the external button to observe they stay in sync." }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)', alignItems: 'center' }, children: [_jsx(Pill, { text: "Autumn term", checked: isChecked, onChange: setIsChecked }), _jsx("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), children: "Toggle from outside" }), _jsx("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), children: "Reset" })] }), _jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: ["External state:", ' ', _jsx("code", { children: String(isChecked) })] })] }));
 };
 const AllVariantsTemplate = () => (_jsxs("div", { style: {
         padding: 'var(--spacing-xlarge)',
@@ -286,6 +319,46 @@ const AccessibilityNoteTemplate = () => (_jsxs("div", { style: {
                 flexDirection: 'column',
                 gap: 'var(--spacing-small)',
             }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-warning-800)', fontWeight: 'var(--font-weight-semi-bold)' }, children: "Known limitation: keyboard accessibility" }), _jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-warning-800)' }, children: ["Toggle-mode", ' ', _jsx("code", { children: "Pill" }), ' ', "renders as a", ' ', _jsx("code", { children: "<span onClick>" }), ' ', "\u2014 it is not reachable via Tab and cannot be activated with Space or Enter. Keyboard-only users and screen reader users cannot interact with it in this mode."] }), _jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-warning-800)' }, children: ["Checkbox mode (", _jsx("code", { children: "checkbox={true}" }), ") is accessible: the embedded", ' ', _jsx("code", { children: "CheckboxInput" }), ' ', "provides a real", ' ', _jsx("code", { children: "<input type=\"checkbox\">" }), ' ', "that Tab reaches and Space toggles."] }), _jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-semantic-warning-800)' }, children: ["For toggle mode where keyboard accessibility is required, wrap each pill and supply the missing semantics manually. See the component description above for the wrapper pattern. Toggle mode pills should carry", ' ', _jsx("code", { children: "role=\"radio\"" }), ' ', "inside a", ' ', _jsx("code", { children: "role=\"radiogroup\"" }), "."] })] }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Accessible example \u2014 checkbox mode (Year 8 cohort filter)" }), _jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: [_jsx(Pill, { text: "Year 7", checkbox: true }), _jsx(Pill, { text: "Year 8", checkbox: true, initialValue: true }), _jsx(Pill, { text: "Year 9", checkbox: true })] }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Tab into any of the pills above \u2014 the embedded checkbox is focusable and Space toggles it." })] })] }));
+const OnChangeBehaviourTemplate = () => {
+    const [log, setLog] = useState([]);
+    const handleChange = (value) => {
+        setLog(prev => [value, ...prev]);
+    };
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: "Click the pill. Each click fires `onChange` with the new value \u2014 nothing is logged until you interact." }), _jsx(Pill, { text: "Autumn term", onChange: handleChange }), _jsx("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)',
+                }, children: log.length === 0
+                    ? (_jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: "Waiting for events..." }))
+                    : (log.map((value, i) => (_jsx("p", { className: "ds-text", style: { margin: '0 0 var(--spacing-xsmall)' }, children: `onChange(${String(value)})` }, i)))) })] }));
+};
+const SUBJECTS = ['Maths', 'English', 'Science', 'History', 'Art', 'French', 'PE'];
+const ControlledCheckboxModeTemplate = () => {
+    const [selected, setSelected] = useState(['Maths', 'Science']);
+    const toggle = (subject) => {
+        setSelected(prev => prev.includes(subject)
+            ? prev.filter(s => s !== subject)
+            : [...prev, subject]);
+    };
+    return (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["Parent owns a string[] of selected subjects and passes", ' ', _jsxs("code", { children: ["checked=", '{selected.includes(subject)}'] }), ' ', "to each pill."] }), _jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 'var(--spacing-small)' }, children: SUBJECTS.map(subject => (_jsx(Pill, { text: subject, checkbox: true, checked: selected.includes(subject), onChange: () => toggle(subject) }, subject))) }), _jsx("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)', fontStyle: 'italic' }, children: selected.length === 0 ? 'No subjects selected' : `Subjects: ${selected.join(', ')}` })] }));
+};
+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 = () => (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("p", { className: "ds-text", style: { margin: 0, color: 'var(--color-grey-600)' }, children: ["16 pills in a 380px container \u2014 the consumer's flex wrapper is what makes them wrap. Pills themselves are", ' ', _jsx("code", { children: "width: fit-content" }), ' ', "and will overflow without", ' ', _jsx("code", { children: "flex-wrap: wrap" }), ' ', "on the parent."] }), _jsx("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)',
+            }, children: ALL_PILLS.map((label, i) => (_jsx(Pill, { text: label }, `${label}-${i}`))) })] }));
 // ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
@@ -294,10 +367,64 @@ export const Default = withDescription({
         text: 'Year 7',
         checkbox: false,
         initialValue: false,
-        onclick: fn(),
+        onChange: fn(),
     },
     render: args => _jsx(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 = 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 = 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 = withDescription({
     args: {
         text: 'Active',
@@ -414,7 +541,7 @@ function YearGroupFilter() {
           key={year}
           text={year}
           initialValue={active === year}
-          onclick={checked => setActive(checked ? year : null)}
+          onChange={checked => setActive(checked ? year : null)}
         />
       ))}
     </div>
@@ -456,7 +583,7 @@ function StatusFilter() {
           key={status}
           text={status}
           checkbox
-          onclick={checked => toggle(status, checked)}
+          onChange={checked => toggle(status, checked)}
         />
       ))}
     </div>
@@ -504,13 +631,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>
@@ -582,4 +709,112 @@ 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 = 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 = 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 = 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.');
 //# sourceMappingURL=Pill.stories.js.map