@transferwise/components 0.0.0-experimental-ff96697 → 0.0.0-experimental-ffbd2fc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transferwise/components",
-  "version": "0.0.0-experimental-ff96697",
+  "version": "0.0.0-experimental-ffbd2fc",
   "description": "Neptune React components",
   "license": "Apache-2.0",
   "repository": {

package/src/alert/Alert.story.tsx

@@ -42,6 +42,12 @@ export default {
       },
     },
   },
+
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
 } satisfies Meta<typeof Alert>;
 
 type Story = StoryObj<typeof Alert>;

package/src/button/_stories/Button.story.tsx

@@ -276,6 +276,11 @@ const meta: Meta<typeof Button> = {
   },
 
   decorators: [withContainer],
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
 };
 
 export default meta;

package/src/checkboxButton/CheckboxButton.story.tsx

@@ -1,9 +1,23 @@
+import React, { useState } from 'react';
 import { action } from 'storybook/actions';
 import { Meta, StoryObj } from '@storybook/react-webpack5';
-import { useState } from 'react';
 
 import CheckboxButton from './CheckboxButton';
 
+/**
+ * A styled checkbox input for selecting zero, one, or multiple items from a list,
+ * or confirming agreement to terms. Extends all standard `<input type="checkbox">`
+ * attributes and adds an `indeterminate` prop for mixed-state scenarios (e.g. a
+ * parent checkbox where only some children are selected). The `indeterminate`
+ * state is purely visual — it does not change the underlying `checked` value.
+ *
+ * Always pair with an accessible label via `aria-label`, `aria-labelledby`, or
+ * a visible `<label>` element.
+ *
+ * Keyboard: `Space` toggles the checkbox when focused.
+ *
+ * **Design guide**: [wise.design/components/checkbox](https://wise.design/components/checkbox)
+ */
 export default {
   component: CheckboxButton,
   title: 'Actions/CheckboxButton',
@@ -14,55 +28,118 @@ export default {
     onClick: action('click'),
     onFocus: action('focus'),
   },
+  parameters: {
+    docs: { toc: true },
+  },
 } satisfies Meta<typeof CheckboxButton>;
 
 type Story = StoryObj<typeof CheckboxButton>;
 
-export const Basic: Story = {
-  args: {
-    'aria-label': 'Toggle email updates',
+/** All five checkbox states — each is interactive. */
+export const Playground: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `<label>
+  <CheckboxButton checked={false} onChange={handleChange} />
+  Unchecked
+</label>
+
+<label>
+  <CheckboxButton checked onChange={handleChange} />
+  Checked
+</label>
+
+<label>
+  <CheckboxButton checked={false} indeterminate onChange={handleChange} />
+  Indeterminate
+</label>
+
+<label>
+  <CheckboxButton checked={false} disabled onChange={handleChange} />
+  Disabled unchecked
+</label>
+
+<label>
+  <CheckboxButton checked disabled onChange={handleChange} />
+  Disabled checked
+</label>`,
+      },
+    },
   },
-  render: (args) => {
+  render: () => {
+    const [unchecked, setUnchecked] = useState(false);
     const [checked, setChecked] = useState(true);
+    const [indeterminateChecked, setIndeterminateChecked] = useState(false);
+    const [isIndeterminate, setIsIndeterminate] = useState(true);
+    const [disabledUnchecked] = useState(false);
+    const [disabledChecked] = useState(true);
 
-    return <CheckboxButton {...args} checked={checked} onChange={() => setChecked(!checked)} />;
-  },
-};
+    const labelStyle: React.CSSProperties = {
+      display: 'flex',
+      alignItems: 'center',
+      gap: '8px',
+      cursor: 'pointer',
+    };
 
-/**
- * The `indeterminate` state is predominantly visual and should match the [native HTML checkbox
- * implementation](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/indeterminate).
- * It is used to indicate a mixed state, where some but not all items are selected, but does not
- * change the `checked` state of the input itself – it remains either checked or unchecked.
- *
- * In the example below the 1st checkbox is unchecked and the 2nd checkbox is checked.
- */
-export const Indeterminate: Story = {
-  args: {
-    indeterminate: true,
-  },
-  render: (args) => {
-    const [checked1, setChecked1] = useState<boolean | undefined>(false);
-    const [checked2, setChecked2] = useState<boolean | undefined>(true);
+    const captionStyle: React.CSSProperties = {
+      fontSize: '14px',
+      color: '#4a5568',
+    };
 
     return (
-      <>
-        <CheckboxButton
-          {...args}
-          checked={checked1}
-          indeterminate={args.indeterminate}
-          aria-label="Initially disabled checkbox with indeterminate state"
-          onChange={() => setChecked1((current) => !current)}
-        />
-
-        <CheckboxButton
-          {...args}
-          checked={checked2}
-          indeterminate={args.indeterminate}
-          aria-label="Initially enabled checkbox with indeterminate state"
-          onChange={() => setChecked2((current) => !current)}
-        />
-      </>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+        <div style={labelStyle}>
+          <CheckboxButton
+            aria-label="Unchecked"
+            checked={unchecked}
+            onChange={() => setUnchecked((v) => !v)}
+          />
+          <span style={captionStyle}>Unchecked</span>
+        </div>
+
+        <div style={labelStyle}>
+          <CheckboxButton
+            aria-label="Checked"
+            checked={checked}
+            onChange={() => setChecked((v) => !v)}
+          />
+          <span style={captionStyle}>Checked</span>
+        </div>
+
+        <div style={labelStyle}>
+          <CheckboxButton
+            aria-label="Indeterminate"
+            checked={indeterminateChecked}
+            indeterminate={isIndeterminate}
+            onChange={() => {
+              setIsIndeterminate(false);
+              setIndeterminateChecked((v: boolean) => !v);
+            }}
+          />
+          <span style={captionStyle}>Indeterminate</span>
+        </div>
+
+        <div style={{ ...labelStyle, cursor: 'not-allowed', opacity: 0.6 }}>
+          <CheckboxButton
+            aria-label="Disabled unchecked"
+            checked={disabledUnchecked}
+            disabled
+            onChange={() => {}}
+          />
+          <span style={captionStyle}>Disabled unchecked</span>
+        </div>
+
+        <div style={{ ...labelStyle, cursor: 'not-allowed', opacity: 0.6 }}>
+          <CheckboxButton
+            aria-label="Disabled checked"
+            checked={disabledChecked}
+            disabled
+            onChange={() => {}}
+          />
+          <span style={captionStyle}>Disabled checked</span>
+        </div>
+      </div>
     );
   },
 };

package/src/checkboxButton/CheckboxButton.test.story.tsx

@@ -0,0 +1,191 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import { expect, userEvent, within } from 'storybook/test';
+
+import { withVariantConfig } from '../../.storybook/helpers';
+import { allModes } from '../../.storybook/modes';
+import CheckboxButton from './CheckboxButton';
+
+export default {
+  component: CheckboxButton,
+  title: 'Actions/CheckboxButton/Tests',
+  tags: ['!autodocs', '!manifest'],
+} satisfies Meta<typeof CheckboxButton>;
+
+type Story = StoryObj<typeof CheckboxButton>;
+
+/** All checkbox states across all themes. */
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '16px', alignItems: 'center', padding: '16px' }}>
+      <CheckboxButton aria-label="Unchecked" checked={false} onChange={() => {}} />
+      <CheckboxButton aria-label="Checked" checked onChange={() => {}} />
+      <CheckboxButton
+        aria-label="Indeterminate"
+        checked={false}
+        indeterminate
+        onChange={() => {}}
+      />
+      <CheckboxButton
+        aria-label="Disabled unchecked"
+        checked={false}
+        disabled
+        onChange={() => {}}
+      />
+      <CheckboxButton aria-label="Disabled checked" checked disabled onChange={() => {}} />
+    </div>
+  ),
+  parameters: {
+    variants: ['default', 'dark', 'bright-green', 'forest-green'],
+    chromatic: {
+      dark: allModes.dark,
+      brightGreen: allModes.brightGreen,
+      forestGreen: allModes.forestGreen,
+    },
+  },
+};
+
+/** Checkbox states at 400% zoom for accessibility testing. */
+export const Zoom400: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '16px', alignItems: 'center', padding: '16px' }}>
+      <CheckboxButton aria-label="Unchecked" checked={false} onChange={() => {}} />
+      <CheckboxButton aria-label="Checked" checked onChange={() => {}} />
+      <CheckboxButton
+        aria-label="Indeterminate"
+        checked={false}
+        indeterminate
+        onChange={() => {}}
+      />
+    </div>
+  ),
+  ...withVariantConfig(['400%']),
+};
+
+/** Tab through all checkbox variants and toggle each on and off. */
+export const KeyboardInteraction: Story = {
+  render: function Render() {
+    const [unchecked, setUnchecked] = useState(false);
+    const [checked, setChecked] = useState(true);
+    const [indeterminate, setIndeterminate] = useState(false);
+    const [disabledUnchecked] = useState(false);
+    const [disabledChecked] = useState(true);
+
+    const row: React.CSSProperties = {
+      display: 'flex',
+      alignItems: 'center',
+      gap: '8px',
+    };
+
+    const label: React.CSSProperties = {
+      fontSize: '14px',
+      color: '#4a5568',
+      width: '140px',
+    };
+
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        <div style={row}>
+          <CheckboxButton
+            aria-label="Unchecked"
+            checked={unchecked}
+            onChange={() => setUnchecked((v: boolean) => !v)}
+          />
+          <span style={label}>Unchecked</span>
+        </div>
+        <div style={row}>
+          <CheckboxButton
+            aria-label="Checked"
+            checked={checked}
+            onChange={() => setChecked((v: boolean) => !v)}
+          />
+          <span style={label}>Checked</span>
+        </div>
+        <div style={row}>
+          <CheckboxButton
+            aria-label="Indeterminate"
+            checked={indeterminate}
+            indeterminate
+            onChange={() => setIndeterminate((v: boolean) => !v)}
+          />
+          <span style={label}>Indeterminate</span>
+        </div>
+        <div style={row}>
+          <CheckboxButton
+            aria-label="Disabled unchecked"
+            checked={disabledUnchecked}
+            disabled
+            onChange={() => {}}
+          />
+          <span style={label}>Disabled unchecked</span>
+        </div>
+        <div style={row}>
+          <CheckboxButton
+            aria-label="Disabled checked"
+            checked={disabledChecked}
+            disabled
+            onChange={() => {}}
+          />
+          <span style={label}>Disabled checked</span>
+        </div>
+      </div>
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const wait = async (ms: number) =>
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, ms);
+      });
+    const canvas = within(canvasElement);
+
+    await step('tab to Unchecked and toggle on then off', async () => {
+      await userEvent.tab();
+      const cb = canvas.getByRole('checkbox', { name: /^unchecked$/i });
+      await expect(cb).toHaveFocus();
+      await wait(400);
+      await userEvent.keyboard(' ');
+      await expect(cb).toBeChecked();
+      await wait(400);
+      await userEvent.keyboard(' ');
+      await expect(cb).not.toBeChecked();
+    });
+
+    await wait(400);
+
+    await step('tab to Checked and toggle off then on', async () => {
+      await userEvent.tab();
+      const cb = canvas.getByRole('checkbox', { name: /^checked$/i });
+      await expect(cb).toHaveFocus();
+      await wait(400);
+      await userEvent.keyboard(' ');
+      await expect(cb).not.toBeChecked();
+      await wait(400);
+      await userEvent.keyboard(' ');
+      await expect(cb).toBeChecked();
+    });
+
+    await wait(400);
+
+    await step('tab to Indeterminate and toggle on then off', async () => {
+      await userEvent.tab();
+      const cb = canvas.getByRole('checkbox', { name: /^indeterminate$/i });
+      await expect(cb).toHaveFocus();
+      await wait(400);
+      await userEvent.keyboard(' ');
+      await expect(cb).toBeChecked();
+      await wait(400);
+      await userEvent.keyboard(' ');
+      await expect(cb).not.toBeChecked();
+    });
+
+    await wait(400);
+
+    await step('tab skips both disabled checkboxes — focus leaves the component', async () => {
+      await userEvent.tab();
+      const disabledUnchecked = canvas.getByRole('checkbox', { name: /disabled unchecked/i });
+      const disabledChecked = canvas.getByRole('checkbox', { name: /disabled checked/i });
+      await expect(disabledUnchecked).not.toHaveFocus();
+      await expect(disabledChecked).not.toHaveFocus();
+    });
+  },
+};

package/src/chips/Chips.story.tsx

@@ -1,112 +1,201 @@
-import { StoryFn, Meta } from '@storybook/react-webpack5';
+import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import { fn } from 'storybook/test';
 import { useState } from 'react';
 
-import Chips, { ChipsProps, ChipValue } from './Chips';
+import Chips, { type ChipValue } from './Chips';
 
-const meta: Meta<typeof Chips> = {
-  title: 'Actions/Chips',
+/**
+ * Chips allow users to filter content or make a choice from a set of options
+ * within a compact area. Two modes are supported:
+ *
+ * - **Filter** (`multiple`): zero or more chips can be active; selected chips
+ *   gain a dismiss button. Unselected by default.
+ * - **Choice** (default): exactly one chip active at a time, like a radio group.
+ *   Best practice is to pre-select the most common option.
+ *
+ * Place chips in a horizontal row, typically beneath a search field or above the
+ * content they filter. Always use chips in a set — never a single chip on its own.
+ *
+ * Keyboard: `Tab` moves between chips; `Space` or `Enter` toggles selection.
+ *
+ * **Design guide**: [wise.design/components/chip](https://wise.design/components/chip)
+ */
+export default {
   component: Chips,
+  title: 'Actions/Chips',
+  args: {
+    onChange: fn(),
+  },
+  argTypes: {
+    selected: { table: { disable: true } },
+  },
+  parameters: {
+    docs: { toc: true },
+  },
+} satisfies Meta<typeof Chips>;
+
+type Story = StoryObj<typeof Chips>;
+
+const categoryChips = [
+  { value: 'all', label: 'All' },
+  { value: 'accounting', label: 'Accounting' },
+  { value: 'payroll', label: 'Payroll' },
+  { value: 'reporting', label: 'Reporting' },
+  { value: 'payments', label: 'Payments' },
+];
+
+const amountChips = [
+  { value: 100, label: '100 GBP' },
+  { value: 200, label: '200 GBP' },
+  { value: 300, label: '300 GBP' },
+  { value: 500, label: '500 GBP+' },
+];
+
+/**
+ * Toggle `multiple` in the controls panel to switch between filter (multi-select)
+ * and choice (single-select) modes.
+ */
+export const Playground: Story = {
+  render: function Render({ onChange, chips, multiple }) {
+    const [selectedMulti, setSelectedMulti] = useState<readonly ChipValue[]>(['accounting']);
+    const [selectedSingle, setSelectedSingle] = useState<ChipValue>('accounting');
+
+    if (multiple) {
+      return (
+        <Chips
+          chips={chips}
+          multiple
+          selected={selectedMulti}
+          aria-label="Category filter"
+          onChange={({ selectedValue, isEnabled }) => {
+            setSelectedMulti((prev) =>
+              isEnabled ? [...prev, selectedValue] : prev.filter((v) => v !== selectedValue),
+            );
+            onChange({ selectedValue, isEnabled });
+          }}
+        />
+      );
+    }
+
+    return (
+      <Chips
+        chips={chips}
+        selected={selectedSingle}
+        aria-label="Category choice"
+        onChange={({ selectedValue, isEnabled }) => {
+          setSelectedSingle(selectedValue);
+          onChange({ selectedValue, isEnabled });
+        }}
+      />
+    );
+  },
+  args: {
+    chips: categoryChips,
+    multiple: true,
+  },
 };
-export default meta;
 
-type Story = StoryFn<ChipsProps>;
+/**
+ * Filter chips allow multiple selections simultaneously. Used to filter a list of
+ * results by one or more categories — e.g. an app marketplace or payment list.
+ */
+export const Filter: Story = {
+  render: function Render({ onChange, ...args }) {
+    const [selected, setSelected] = useState<readonly ChipValue[]>(['accounting', 'payments']);
+
+    return (
+      <Chips
+        {...args}
+        selected={selected}
+        multiple
+        aria-label="Category filter"
+        onChange={({ selectedValue, isEnabled }) => {
+          setSelected((prev) =>
+            isEnabled ? [...prev, selectedValue] : prev.filter((v) => v !== selectedValue),
+          );
+          onChange({ selectedValue, isEnabled });
+        }}
+      />
+    );
+  },
+  args: {
+    chips: categoryChips,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `function FilterChips() {
+  const [selected, setSelected] = useState(['accounting', 'payments']);
 
-const FilterTemplate: Story = (args: ChipsProps) => {
-  const [selected, setSelected] = useState<readonly ChipValue[]>(
-    args.selected == null || Array.isArray(args.selected) ? args.selected : [args.selected],
-  );
   return (
     <Chips
-      {...args}
-      selected={selected}
+      chips={[
+        { value: 'all', label: 'All' },
+        { value: 'accounting', label: 'Accounting' },
+        { value: 'payroll', label: 'Payroll' },
+        { value: 'reporting', label: 'Reporting' },
+        { value: 'payments', label: 'Payments' },
+      ]}
       multiple
+      selected={selected}
+      aria-label="Category filter"
       onChange={({ selectedValue, isEnabled }) => {
-        if (isEnabled) {
-          setSelected([...selected, selectedValue]);
-        } else {
-          const updatedSelected = selected.filter((value) => selectedValue !== value);
-          setSelected(updatedSelected);
-        }
+        setSelected((prev) =>
+          isEnabled ? [...prev, selectedValue] : prev.filter((v) => v !== selectedValue)
+        );
       }}
     />
   );
+}`,
+      },
+    },
+  },
 };
 
-const ChoiceTemplate: Story = (args: ChipsProps) => {
-  const [selected, setSelected] = useState<ChipValue>(args.selected as ChipValue);
+/**
+ * Choice chips behave like a radio group — only one chip can be active at a time.
+ * Useful for selecting a single value from a small set, such as a transfer amount.
+ */
+export const Choice: Story = {
+  render: function Render({ onChange, ...args }) {
+    const [selected, setSelected] = useState<ChipValue>(300);
+
+    return (
+      <Chips
+        {...args}
+        selected={selected}
+        aria-label="Transfer amount"
+        onChange={({ selectedValue, isEnabled }) => {
+          setSelected(selectedValue);
+          onChange({ selectedValue, isEnabled });
+        }}
+      />
+    );
+  },
+  args: {
+    chips: amountChips,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `function ChoiceChips() {
+  const [selected, setSelected] = useState(300);
+
   return (
     <Chips
-      {...args}
+      chips={[
+        { value: 100, label: '100 GBP' },
+        { value: 200, label: '200 GBP' },
+        { value: 300, label: '300 GBP' },
+        { value: 500, label: '500 GBP+' },
+      ]}
       selected={selected}
+      aria-label="Transfer amount"
       onChange={({ selectedValue }) => setSelected(selectedValue)}
     />
   );
-};
-
-export const FilterChips: typeof FilterTemplate = FilterTemplate.bind({});
-FilterChips.args = {
-  chips: [
-    {
-      value: 'accounting',
-      label: 'Accounting',
-    },
-    {
-      value: 'payroll',
-      label: 'Payroll',
-    },
-    {
-      value: 'reporting',
-      label: 'Reporting',
-    },
-    {
-      value: 'payments',
-      label: 'Payments',
-    },
-  ],
-};
-
-export const PreSelectedFilterChips: typeof FilterTemplate = FilterTemplate.bind({});
-PreSelectedFilterChips.args = {
-  chips: [
-    {
-      value: 'accounting',
-      label: 'Accounting',
-    },
-    {
-      value: 'payroll',
-      label: 'Payroll',
-    },
-    {
-      value: 'reporting',
-      label: 'Reporting',
-    },
-    {
-      value: 'payments',
-      label: 'Payments',
-    },
-  ],
-  selected: ['accounting', 'payments'],
-};
-
-export const ChoiceChips: typeof ChoiceTemplate = ChoiceTemplate.bind({});
-ChoiceChips.args = {
-  chips: [
-    {
-      value: 1,
-      label: '100 GBP',
-    },
-    {
-      value: 2,
-      label: '200 GBP',
-    },
-    {
-      value: 3,
-      label: '300 GBP',
-    },
-    {
-      value: 4,
-      label: '400 GBP+',
+}`,
+      },
     },
-  ],
-  selected: 3,
+  },
 };