@transferwise/components 46.133.0 → 46.133.1

package/src/checkboxButton/CheckboxButton.story.tsx

@@ -1,67 +1,148 @@
-import { action } from 'storybook/actions';
+import { useState, useEffect } from 'react';
+import { fn } from 'storybook/test';
 import { Meta, StoryObj } from '@storybook/react-webpack5';
-import { useState } from 'react';
 
-import CheckboxButton from './CheckboxButton';
+import { storySourceWithoutNoise } from '../../.storybook/helpers';
+import CheckboxButton, { type CheckboxButtonProps } from './CheckboxButton';
+import { Label } from '../label/Label';
 
+/**
+ * Use <a href="?path=/docs/forms-checkbox--docs">Checkbox</a> component instead when pairing with a label. Only use CheckboxButton when you need a standalone checkbox (e.g. settings matrix) and provide an `aria-label`.
+ *
+ * **Design guidance**: <a href="https://wise.design/components/checkbox" target="_blank">wise.design/components/checkbox</a>
+ */
 export default {
   component: CheckboxButton,
   title: 'Actions/CheckboxButton',
   args: {
+    'aria-label': 'Toggle checkbox',
+    checked: true,
     disabled: false,
-    onBlur: action('blur'),
-    onClick: action('click'),
-    onFocus: action('focus'),
+    indeterminate: false,
+    onBlur: fn(),
+    onChange: fn(),
+    onClick: fn(),
+    onFocus: fn(),
+  },
+  argTypes: {
+    'aria-label': {
+      description: 'Provides the accessible name when the control has no visible text label.',
+    },
+    checked: {
+      description: 'Controls whether the checkbox is checked.',
+    },
+    disabled: {
+      description: 'Toggles the disabled state.',
+    },
+    name: {
+      description: 'Name submitted with the form when the checkbox is checked.',
+    },
+    value: {
+      description: 'Value submitted with the form when the checkbox is checked.',
+    },
+    onChange: {
+      description: 'Called when the checked state changes.',
+    },
+    indeterminate: {
+      description:
+        'Sets the native mixed state — used when some (not all) child items are selected. Clicking resolves to checked; clear `indeterminate` in `onChange` to reflect the transition.',
+    },
+    defaultChecked: { table: { category: 'Common' } },
+    id: { table: { category: 'Common' } },
+    className: { table: { category: 'Common' } },
+    onBlur: { table: { category: 'Common' } },
+    onClick: { table: { category: 'Common' } },
+    onFocus: { table: { category: 'Common' } },
+  },
+  parameters: {
+    docs: { toc: true },
   },
 } satisfies Meta<typeof CheckboxButton>;
 
 type Story = StoryObj<typeof CheckboxButton>;
 
-export const Basic: Story = {
-  args: {
-    'aria-label': 'Toggle email updates',
-  },
-  render: (args) => {
-    const [checked, setChecked] = useState(true);
+const withColumnLayout = (Story: () => JSX.Element) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+    <Story />
+  </div>
+);
 
-    return <CheckboxButton {...args} checked={checked} onChange={() => setChecked(!checked)} />;
-  },
-};
+/** Interactive single checkbox — use the Controls panel to toggle `disabled` and `indeterminate`. */
+export const Playground: Story = storySourceWithoutNoise({
+  render: function Render(args: CheckboxButtonProps) {
+    const [checked, setChecked] = useState(args.checked ?? true);
 
-/**
- * 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);
+    useEffect(() => {
+      setChecked(args.checked ?? true);
+    }, [args.checked]);
 
     return (
-      <>
+      <CheckboxButton
+        {...args}
+        checked={checked}
+        onChange={(e) => {
+          setChecked(e.currentTarget.checked);
+          args.onChange?.(e);
+        }}
+      />
+    );
+  },
+});
+
+/** Disabled state — checked and unchecked. */
+export const Disabled: Story = {
+  decorators: [withColumnLayout],
+  render: (args) => (
+    <>
+      <div>
+        <Label htmlFor="disabled-unchecked">Disabled unchecked</Label>
+        <CheckboxButton
+          id="disabled-unchecked"
+          aria-label="Disabled unchecked"
+          checked={false}
+          disabled
+          onChange={() => {}}
+        />
+      </div>
+      <div>
+        <Label htmlFor="disabled-checked">Disabled checked</Label>
         <CheckboxButton
-          {...args}
-          checked={checked1}
-          indeterminate={args.indeterminate}
-          aria-label="Initially disabled checkbox with indeterminate state"
-          onChange={() => setChecked1((current) => !current)}
+          id="disabled-checked"
+          aria-label="Disabled checked"
+          checked
+          disabled
+          onChange={() => {}}
         />
+      </div>
+    </>
+  ),
+};
 
+/** Indeterminate state — checked and unchecked. */
+export const Indeterminate: Story = {
+  decorators: [withColumnLayout],
+  render: (args) => (
+    <>
+      <div>
+        <Label htmlFor="indeterminate-unchecked">Indeterminate (unchecked)</Label>
         <CheckboxButton
-          {...args}
-          checked={checked2}
-          indeterminate={args.indeterminate}
-          aria-label="Initially enabled checkbox with indeterminate state"
-          onChange={() => setChecked2((current) => !current)}
+          id="indeterminate-unchecked"
+          aria-label="Indeterminate unchecked"
+          checked={false}
+          indeterminate
+          onChange={() => {}}
         />
-      </>
-    );
-  },
+      </div>
+      <div>
+        <Label htmlFor="indeterminate-checked">Indeterminate (checked)</Label>
+        <CheckboxButton
+          id="indeterminate-checked"
+          aria-label="Indeterminate checked"
+          checked
+          indeterminate
+          onChange={() => {}}
+        />
+      </div>
+    </>
+  ),
 };

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

@@ -0,0 +1,236 @@
+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 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: function Render() {
+    const [unchecked, setUnchecked] = useState(false);
+    const [checked, setChecked] = useState(true);
+    const [indeterminate, setIndeterminate] = useState(false);
+    return (
+      <div style={{ display: 'flex', gap: '16px', alignItems: 'center', padding: '16px' }}>
+        <CheckboxButton
+          aria-label="Unchecked"
+          checked={unchecked}
+          onChange={() => setUnchecked((v) => !v)}
+        />
+        <CheckboxButton
+          aria-label="Checked"
+          checked={checked}
+          onChange={() => setChecked((v) => !v)}
+        />
+        <CheckboxButton
+          aria-label="Indeterminate"
+          checked={indeterminate}
+          indeterminate
+          onChange={() => setIndeterminate((v) => !v)}
+        />
+        <CheckboxButton
+          aria-label="Disabled unchecked"
+          checked={false}
+          disabled
+          onChange={() => {}}
+        />
+        <CheckboxButton aria-label="Disabled checked" checked disabled onChange={() => {}} />
+      </div>
+    );
+  },
+  ...withVariantConfig(['default', 'dark', 'bright-green', 'forest-green']),
+};
+
+/**
+ * `Space` toggles when focused (requires `onChange`). Tab skips disabled checkboxes.
+ * Indeterminate resolves to checked on first `Space`, then toggles normally.
+ */
+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();
+    });
+  },
+};
+
+/** Base checkbox states in right-to-left layout. */
+export const RTL: Story = {
+  render: function Render() {
+    const [unchecked, setUnchecked] = useState(false);
+    const [checked, setChecked] = useState(true);
+    const [indeterminate, setIndeterminate] = useState(false);
+    return (
+      <div style={{ display: 'flex', gap: '16px', alignItems: 'center', padding: '16px' }}>
+        <CheckboxButton
+          aria-label="Unchecked"
+          checked={unchecked}
+          onChange={() => setUnchecked((v) => !v)}
+        />
+        <CheckboxButton
+          aria-label="Checked"
+          checked={checked}
+          onChange={() => setChecked((v) => !v)}
+        />
+        <CheckboxButton
+          aria-label="Indeterminate"
+          checked={indeterminate}
+          indeterminate
+          onChange={() => setIndeterminate((v) => !v)}
+        />
+        <CheckboxButton
+          aria-label="Disabled unchecked"
+          checked={false}
+          disabled
+          onChange={() => {}}
+        />
+        <CheckboxButton aria-label="Disabled checked" checked disabled onChange={() => {}} />
+      </div>
+    );
+  },
+  ...withVariantConfig(['rtl']),
+};
+
+/** 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%']),
+};

package/src/chips/Chips.story.tsx

@@ -1,112 +1,151 @@
-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, type ChipsProps } from './Chips';
+import { storySourceWithoutNoise } from '../../.storybook/helpers';
 
-const meta: Meta<typeof Chips> = {
-  title: 'Actions/Chips',
+/**
+ * Can be used for making a <a href="?path=/story/actions-chips--choice">choice</a>, or as a <a href="?path=/story/actions-chips--filter">filter</a> with multiple options.
+ *
+ * **Design guidance**: <a href="https://wise.design/components/chip" target="_blank">wise.design/components/chip</a>
+ */
+export default {
   component: Chips,
-};
-export default meta;
+  title: 'Actions/Chips',
+  args: {
+    multiple: false,
+    onChange: fn(),
+    'aria-label': 'Category filter',
+  },
+  argTypes: {
+    'aria-label': {
+      control: 'text',
+      description: 'Provides the accessible name for the chip group.',
+    },
+    className: { table: { category: 'Common' } },
+  },
+  parameters: {
+    docs: { toc: true },
+  },
+} satisfies Meta<typeof Chips>;
 
-type Story = StoryFn<ChipsProps>;
+type Story = StoryObj<typeof Chips>;
 
-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}
-      multiple
-      onChange={({ selectedValue, isEnabled }) => {
-        if (isEnabled) {
-          setSelected([...selected, selectedValue]);
-        } else {
-          const updatedSelected = selected.filter((value) => selectedValue !== value);
-          setSelected(updatedSelected);
-        }
-      }}
-    />
-  );
-};
+const categoryChips = [
+  { value: 'all', label: 'All' },
+  { value: 'accounting', label: 'Accounting' },
+  { value: 'payroll', label: 'Payroll' },
+  { value: 'reporting', label: 'Reporting' },
+  { value: 'payments', label: 'Payments' },
+];
 
-const ChoiceTemplate: Story = (args: ChipsProps) => {
-  const [selected, setSelected] = useState<ChipValue>(args.selected as ChipValue);
-  return (
-    <Chips
-      {...args}
-      selected={selected}
-      onChange={({ selectedValue }) => setSelected(selectedValue)}
-    />
-  );
-};
+const amountChips = [
+  { value: 100, label: '100 GBP' },
+  { value: 200, label: '200 GBP' },
+  { value: 300, label: '300 GBP' },
+  { value: 500, label: '500 GBP+' },
+];
 
-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',
-    },
-  ],
-};
+/**
+ * Toggle `multiple` in the controls panel to switch between filter (multi-select)
+ * and choice (single-select) modes.
+ */
+export const Playground: Story = storySourceWithoutNoise<typeof Chips>({
+  args: {
+    chips: categoryChips,
+    multiple: true,
+  },
+  render: function Render(args: ChipsProps) {
+    const [selectedMulti, setSelectedMulti] = useState<readonly ChipValue[]>(['accounting']);
+    const [selectedSingle, setSelectedSingle] = useState<ChipValue>('accounting');
 
-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'],
-};
+    if (args.multiple) {
+      return (
+        <Chips
+          chips={args.chips}
+          multiple
+          selected={selectedMulti}
+          aria-label={args['aria-label']}
+          onChange={({ selectedValue, isEnabled }) => {
+            setSelectedMulti((prev) =>
+              isEnabled ? [...prev, selectedValue] : prev.filter((v) => v !== selectedValue),
+            );
+            args.onChange({ selectedValue, isEnabled });
+          }}
+        />
+      );
+    }
 
-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,
-};
+    return (
+      <Chips
+        chips={args.chips}
+        selected={selectedSingle}
+        aria-label={args['aria-label']}
+        onChange={({ selectedValue, isEnabled }) => {
+          setSelectedSingle(selectedValue);
+          args.onChange({ selectedValue, isEnabled });
+        }}
+      />
+    );
+  },
+});
+
+/**
+ * The user can select any number of chips with the selected prop as an array (`multiple` prop set to `true`). <br />
+ * <a href="https://wise.design/components/chip#filter-chips" target="_blank">Design documentation</a>
+ */
+export const Filter: Story = storySourceWithoutNoise<typeof Chips>({
+  args: {
+    chips: categoryChips,
+  },
+  argTypes: {
+    multiple: { table: { disable: true } },
+  },
+  render: function Render(args: ChipsProps) {
+    const [selected, setSelected] = useState<readonly ChipValue[]>(['accounting', 'payments']);
+
+    return (
+      <Chips
+        chips={args.chips}
+        selected={selected}
+        multiple
+        aria-label="Category filter"
+        onChange={({ selectedValue, isEnabled }) => {
+          setSelected((prev) =>
+            isEnabled ? [...prev, selectedValue] : prev.filter((v) => v !== selectedValue),
+          );
+          args.onChange({ selectedValue, isEnabled });
+        }}
+      />
+    );
+  },
+});
+
+/**
+ * The user can only select one chip with the selected prop as a single value (`multiple` prop set to `false`). <br />
+ * <a href="https://wise.design/components/chip#choice-chips" target="_blank">Design documentation</a>
+ */
+export const Choice: Story = storySourceWithoutNoise<typeof Chips>({
+  args: {
+    chips: amountChips,
+  },
+  argTypes: {
+    multiple: { table: { disable: true } },
+  },
+  render: function Render(args: ChipsProps) {
+    const [selected, setSelected] = useState<ChipValue>(300);
+
+    return (
+      <Chips
+        chips={args.chips}
+        selected={selected}
+        aria-label="Transfer amount"
+        onChange={({ selectedValue, isEnabled }) => {
+          setSelected(selectedValue);
+          args.onChange({ selectedValue, isEnabled });
+        }}
+      />
+    );
+  },
+});