@tpzdsp/next-toolkit 2.5.1 → 3.1.0

package/src/components/SearchBox/SearchBox.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SearchBox } from './SearchBox';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { HintText } from '../HintText/HintText';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof SearchBox> = {
+  title: 'Components/SearchBox',
+  component: SearchBox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A search input with a primary submit button. Wrap in a `<form role="search">` to wire up submission. The button is `type="submit"` so it works with standard form behaviour. Accepts all `Input` props except `type`.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SearchBox>;
+
+export const Default: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <SearchBox placeholder="Search" {...args} />
+    </form>
+  ),
+};
+
+export const WithLabel: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <div className="flex flex-col gap-gds-1">
+        <Label htmlFor="site-search">Search this site</Label>
+
+        <HintText id="site-search-hint">Enter a keyword or phrase.</HintText>
+
+        <SearchBox
+          id="site-search"
+          placeholder="Search"
+          aria-describedby="site-search-hint"
+          {...args}
+        />
+      </div>
+    </form>
+  ),
+};
+
+export const Invalid: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <FormGroup invalid>
+        <Label htmlFor="search-invalid">Search this site</Label>
+
+        <ErrorText id="search-invalid-error">Enter a search term</ErrorText>
+
+        <SearchBox
+          id="search-invalid"
+          placeholder="Search"
+          aria-invalid
+          aria-describedby="search-invalid-error"
+          {...args}
+        />
+      </FormGroup>
+    </form>
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <form role="search">
+      <SearchBox placeholder="Search" disabled {...args} />
+    </form>
+  ),
+};
+
+export const CustomLabel: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <SearchBox placeholder="Enter location" buttonLabel="Find" {...args} />
+    </form>
+  ),
+};

package/src/components/SearchBox/SearchBox.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { useId, type ComponentProps } from 'react';
+
+import { LuSearch } from 'react-icons/lu';
+
+import { Button } from '../Button/Button';
+import { Input } from '../Input/Input';
+import { InputGroup, InputSuffix } from '../InputGroup/InputGroup';
+
+export type SearchBoxProps = Omit<ComponentProps<typeof Input>, 'type'> & {
+  buttonLabel?: string;
+};
+
+export const SearchBox = ({ id, buttonLabel = 'Search', disabled, ...props }: SearchBoxProps) => {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+
+  return (
+    <InputGroup aria-disabled={disabled}>
+      <Input id={inputId} type="search" disabled={disabled} {...props} />
+
+      <InputSuffix>
+        <Button
+          type="submit"
+          appearance="primary"
+          variant="icon"
+          aria-label={buttonLabel}
+          disabled={disabled}
+        >
+          <LuSearch aria-hidden />
+        </Button>
+      </InputSuffix>
+    </InputGroup>
+  );
+};

package/src/components/Select/AsyncSelect.stories.tsx

@@ -0,0 +1,84 @@
+import { useCallback, useRef } from 'react';
+
+import type { OptionsOrGroups } from 'react-select';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { AsyncSelect } from './AsyncSelect';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof AsyncSelect> = {
+  title: 'Components/Select/AsyncSelect',
+  component: AsyncSelect,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Select with remote, `loadOptions`-driven options instead of a fixed local list, for search-as-you-type against an API. Composes react-select's own `useAsync` and `useStateManager` directly onto this project's Select, so it shares the exact same styling and indicator overrides (including the loading spinner). `loadOptions` isn't debounced by react-select itself, it fires on every keystroke, wrap it in your own debounce as shown here.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AsyncSelect>;
+
+type Country = { id: string; label: string };
+
+const COUNTRIES: Country[] = [
+  { id: 'eng', label: 'England' },
+  { id: 'sco', label: 'Scotland' },
+  { id: 'wal', label: 'Wales' },
+  { id: 'nir', label: 'Northern Ireland' },
+];
+
+// Stands in for a real API call, filters the local list after a short delay
+// so the loading indicator is visible.
+const fakeSearch = (query: string): Promise<Country[]> =>
+  new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(
+        COUNTRIES.filter((country) => country.label.toLowerCase().includes(query.toLowerCase())),
+      );
+    }, 600);
+  });
+
+const DebouncedExample = () => {
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const loadOptions = useCallback(
+    (inputValue: string, callback: (options: OptionsOrGroups<Country, never>) => void) => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+
+      debounceRef.current = setTimeout(async () => {
+        callback(await fakeSearch(inputValue));
+      }, 300);
+    },
+    [],
+  );
+
+  return (
+    <div>
+      <Label htmlFor="async-country">Country</Label>
+
+      <AsyncSelect<Country>
+        inputId="async-country"
+        loadOptions={loadOptions}
+        getOptionLabel={(option) => option.label}
+        getOptionValue={(option) => option.id}
+        placeholder="Search for a country"
+        noOptionsMessage={({ inputValue }) =>
+          inputValue ? 'No countries found' : 'Start typing to search'
+        }
+      />
+    </div>
+  );
+};
+
+export const Default: Story = {
+  render: () => <DebouncedExample />,
+};

package/src/components/Select/AsyncSelect.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import type { GroupBase } from 'react-select';
+import { useStateManager } from 'react-select';
+import { useAsync } from 'react-select/async';
+import type { AsyncProps } from 'react-select/async';
+
+import { Select } from './Select';
+import type { SelectProps } from './Select';
+
+export type AsyncSelectProps<
+  Option = unknown,
+  IsMulti extends boolean = false,
+  Group extends GroupBase<Option> = GroupBase<Option>,
+> = Omit<SelectProps<Option, IsMulti, Group>, keyof AsyncProps<Option, IsMulti, Group>> &
+  AsyncProps<Option, IsMulti, Group>;
+
+/**
+ * Select with remote, `loadOptions`-driven options instead of a fixed local
+ * list. Composes react-select's own `useAsync` (manages the loading state
+ * and current options) and `useStateManager` (controlled/uncontrolled
+ * value/inputValue bridging) directly onto our own styled Select, the same
+ * way react-select's own AsyncSelect composes them onto its unstyled one, so
+ * this gets identical behaviour with our styling and indicator overrides.
+ *
+ * `loadOptions` is not debounced by react-select itself, it fires on every
+ * keystroke, wrap it in your own debounce (e.g. a timeout cleared on each
+ * call) if that's not the desired behaviour.
+ */
+export const AsyncSelect = <
+  Option = unknown,
+  IsMulti extends boolean = false,
+  Group extends GroupBase<Option> = GroupBase<Option>,
+>(
+  props: AsyncSelectProps<Option, IsMulti, Group>,
+) => {
+  const asyncProps = useAsync(props);
+  const statefulProps = useStateManager(asyncProps);
+
+  return <Select {...statefulProps} />;
+};

package/src/components/Select/Select.css

@@ -0,0 +1,202 @@
+@layer components {
+  /* MARK: Select
+     Styled to match the GDS text input: same height, border, padding, and
+     focus ring. The dropdown menu uses panel (white bg, form-weight border)
+     with no border-radius, matching GDS panel conventions. */
+
+  /* MARK: Container
+     w-full mirrors .cn-input: harmless in normal block flow (already full
+     width there), but needed as a flex item (e.g. the main field in an
+     InputGroup row alongside InputPrefix/InputSuffix), where it would
+     otherwise shrink to the width of its content instead of filling the
+     remaining row space. InputGroup.css overrides this back to w-auto when
+     a Select is used as a narrow addon nested inside a prefix/suffix. */
+  .cn-select-container {
+    @apply relative w-full;
+  }
+
+  /* MARK: Control
+     Mirrors .cn-input: 40px height, 2px border, 5px horizontal padding. */
+  .cn-select-control {
+    @apply cn-form-border h-10 px-gds-1 bg-white flex items-center cursor-default text-base
+      box-border;
+  }
+
+  .cn-select-control-focused {
+    @apply outline-focus outline-offset-0;
+    box-shadow: inset 0 0 0 var(--border-width-form) var(--color-divider-input);
+  }
+
+  .cn-select-control-invalid {
+    @apply border-error;
+  }
+
+  .cn-select-control-disabled {
+    @apply opacity-50 cursor-not-allowed;
+  }
+
+  /* MARK: Value area */
+
+  .cn-select-value-container {
+    @apply flex flex-1 items-center flex-wrap h-full overflow-hidden;
+  }
+
+  .cn-select-value-container-multi {
+    /* The visible gap between chips equals the gap property value: the 3px white
+       borders on each side of each chip are part of the perceived separation, not
+       subtracted from it (border-to-border = gap - 6, but visible = gap - 6 + 3 + 3 = gap).
+       Edge gap = px-gds-1 (5px) + chip border (3px) = 8px, so gap-2 (8px) matches. */
+    @apply gap-2;
+
+    &:has(.cn-select-multi-value) {
+      /* Horizontal padding only, vertical padding reduces the centering area
+         from 40px to 34px and shifts chips off-centre. The chip's focus border
+         (3px) sits 5.5px from the top/bottom container edges, so no vertical
+         padding is needed to protect it from overflow: hidden. */
+      padding-right: var(--focus-ring-width);
+      padding-left: var(--focus-ring-width);
+    }
+  }
+
+  .cn-select-single-value {
+    @apply text-body truncate;
+  }
+
+  .cn-select-placeholder {
+    @apply text-body-secondary;
+  }
+
+  /* The hidden search input react-select renders inside the control */
+  .cn-select-input {
+    @apply text-base text-body;
+  }
+
+  /* MARK: Indicators */
+
+  .cn-select-indicators {
+    @apply flex items-center gap-1 flex-none;
+  }
+
+  .cn-select-dropdown-indicator {
+    @apply w-5 h-5 flex items-center justify-center text-body;
+  }
+
+  .cn-select-dropdown-indicator-open {
+    @apply rotate-180;
+  }
+
+  .cn-select-clear-indicator {
+    @apply w-5 h-5 flex items-center justify-center cursor-pointer text-body-secondary
+      hover:text-body;
+  }
+
+  .cn-select-loading-indicator {
+    @apply w-5 h-5 flex items-center justify-center text-body-secondary;
+  }
+
+  /* MARK: Menu */
+
+  .cn-select-menu {
+    @apply panel absolute w-full mt-1 overflow-hidden cn-z-overlay;
+  }
+
+  /* react-select flips the menu above the control when there isn't room
+     below. mt-1 pushes it further down rather than opening a gap in that
+     direction, mirror it as mb-1 so there's still a visible gap between
+     control and menu regardless of which side it opens on. */
+  .cn-select-menu-top {
+    @apply mt-0 mb-1;
+  }
+
+  .cn-select-menu-list {
+    @apply flex flex-col overflow-y-auto max-h-60;
+  }
+
+  /* MARK: Options */
+
+  .cn-select-option {
+    @apply px-gds-1 py-1 text-base text-body cursor-pointer;
+  }
+
+  .cn-select-option-focused {
+    @apply bg-wash;
+  }
+
+  .cn-select-option-selected {
+    @apply bg-accent text-on-accent;
+  }
+
+  .cn-select-option-disabled {
+    @apply opacity-50 cursor-not-allowed;
+  }
+
+  .cn-select-no-options {
+    @apply px-gds-1 py-gds-1 text-base text-body select-none;
+  }
+
+  /* MARK: Groups */
+
+  .cn-select-group:first-child {
+    @apply pt-2;
+  }
+
+  /* MARK: Multi-value chips
+     The entire chip is a <button> that removes the value on click, giving a
+     larger, GDS-compliant touch target rather than a tiny X icon alone. */
+
+  .cn-select-multi-value {
+    /* The margin cancels the space the 3px border takes up in the flex layout so
+       chips look the same size as they would without a border. */
+    @apply cn-chip-size-sm cn-chip-appearance-neutral flex items-center gap-1 cursor-pointer
+      border-solid border-panel outline-none;
+    border-width: var(--focus-ring-width);
+    margin: 0 calc(var(--focus-ring-width) * -1) 0 calc(var(--focus-ring-width) * -1);
+
+    &:focus {
+      @apply border-focus;
+    }
+  }
+
+  .cn-select-multi-value-remove {
+    @apply w-3.5 h-3.5 flex-none;
+  }
+
+  /* MARK: Tags below
+     Used when `tagsPlacement="below"`: selected values render in a row under
+     the control instead of as inline chips, so the control keeps a fixed
+     40px height regardless of how many values are selected. */
+
+  .cn-select-tags {
+    @apply flex flex-wrap gap-2 mt-2;
+  }
+
+  .cn-select-tag {
+    /* Same margin-cancels-border trick as .cn-select-multi-value, so the gap
+       between tags matches the gap between inline chips exactly. */
+    @apply cn-chip-size-sm cn-chip-appearance-neutral flex items-center gap-1 cursor-pointer
+      border-solid border-panel outline-none;
+    border-width: var(--focus-ring-width);
+    margin: 0 calc(var(--focus-ring-width) * -1) 0 calc(var(--focus-ring-width) * -1);
+
+    &:focus {
+      @apply border-focus;
+    }
+
+    &:disabled {
+      @apply opacity-50 cursor-not-allowed;
+    }
+  }
+
+  /* MARK: Skeleton
+     SelectSkeleton reuses cn-select-container/control/value-container/
+     indicators directly, so its dimensions (40px height, border, padding,
+     the flex-1 vs flex-none split) always match the real control, these
+     two are just the decorative placeholder shapes inside it. */
+  .cn-select-skeleton-value {
+    @apply h-4 w-24;
+  }
+
+  .cn-select-skeleton-indicator {
+    @apply size-4;
+  }
+}

package/src/components/Select/Select.stories.tsx

@@ -0,0 +1,162 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Select } from './Select';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof Select> = {
+  title: 'Components/Select/Select',
+  component: Select,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Searchable select built on react-select. Styled to match the GDS text input, same height, border, and focus ring. The dropdown uses the standard GDS panel (white background, black border, no border-radius). Supports single and multi-select, option groups, async loading, and creatable options via react-select props.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Select>;
+
+const SELECT_A_COUNTRY = 'Select a country';
+
+const COUNTRIES = [
+  { value: 'eng', label: 'England' },
+  { value: 'sco', label: 'Scotland' },
+  { value: 'wal', label: 'Wales' },
+  { value: 'nir', label: 'Northern Ireland' },
+];
+
+const SPECIES = [
+  {
+    label: 'Birds',
+    options: [
+      { value: 'lapwing', label: 'Lapwing' },
+      { value: 'curlew', label: 'Curlew' },
+      { value: 'redshank', label: 'Redshank' },
+    ],
+  },
+  {
+    label: 'Mammals',
+    options: [
+      { value: 'otter', label: 'Otter' },
+      { value: 'water-vole', label: 'Water vole' },
+      { value: 'hedgehog', label: 'Hedgehog' },
+    ],
+  },
+  {
+    label: 'Plants',
+    options: [
+      { value: 'bluebell', label: 'Bluebell' },
+      { value: 'meadow-buttercup', label: 'Meadow buttercup' },
+    ],
+  },
+];
+
+export const Default: Story = {
+  args: {
+    options: COUNTRIES,
+    placeholder: SELECT_A_COUNTRY,
+  },
+};
+
+export const Clearable: Story = {
+  args: {
+    options: COUNTRIES,
+    placeholder: SELECT_A_COUNTRY,
+    isClearable: true,
+    defaultValue: COUNTRIES[0],
+  },
+};
+
+export const MultiSelect: Story = {
+  args: {
+    options: COUNTRIES,
+    placeholder: 'Select countries',
+    isMulti: true,
+    isClearable: true,
+    defaultValue: [COUNTRIES[0], COUNTRIES[2]],
+  },
+};
+
+export const MultiSelectTagsBelow: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Set `tagsPlacement="below"` to list selected values under the control instead of as inline chips. The control keeps a fixed height regardless of how many values are selected.',
+      },
+    },
+  },
+  args: {
+    options: COUNTRIES,
+    placeholder: 'Select countries',
+    isMulti: true,
+    isClearable: true,
+    tagsPlacement: 'below',
+    defaultValue: [COUNTRIES[0], COUNTRIES[2]],
+  },
+};
+
+export const WithGroups: Story = {
+  args: {
+    options: SPECIES,
+    placeholder: 'Select a species',
+    isClearable: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    options: COUNTRIES,
+    placeholder: SELECT_A_COUNTRY,
+    isDisabled: true,
+    defaultValue: COUNTRIES[1],
+  },
+};
+
+export const Invalid: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pass `invalid` to show the error border. Clears when the control receives focus.',
+      },
+    },
+  },
+  render: () => (
+    <FormGroup invalid>
+      <Label htmlFor="select-invalid">Country</Label>
+
+      <ErrorText id="select-invalid-error">Select a country</ErrorText>
+
+      <Select
+        inputId="select-invalid"
+        aria-describedby="select-invalid-error"
+        options={COUNTRIES}
+        placeholder={SELECT_A_COUNTRY}
+        invalid
+      />
+    </FormGroup>
+  ),
+};
+
+export const NonSearchable: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Set `isSearchable={false}` for short lists where filtering adds no value. The cursor becomes a pointer to reinforce non-editable behaviour.',
+      },
+    },
+  },
+  args: {
+    options: COUNTRIES,
+    placeholder: 'Select a country',
+    isSearchable: false,
+  },
+};

package/src/components/Select/Select.test.tsx

@@ -0,0 +1,36 @@
+import { Select } from './Select';
+import { render, screen } from '../../test/renderers';
+
+const COUNTRIES = [
+  { value: 'eng', label: 'England' },
+  { value: 'sco', label: 'Scotland' },
+];
+
+const ERROR_ID = 'country-error';
+
+describe('Select', () => {
+  it('merges aria-describedby alongside react-select’s own value, rather than replacing it', () => {
+    render(
+      <Select
+        inputId="country"
+        options={COUNTRIES}
+        aria-describedby={ERROR_ID}
+        aria-label="Country"
+      />,
+    );
+
+    const describedBy = screen.getByRole('combobox').getAttribute('aria-describedby');
+
+    expect(describedBy).toContain(ERROR_ID);
+    // react-select's own placeholder/live-region id is still present, not replaced.
+    expect(describedBy?.split(' ').length).toBeGreaterThan(1);
+  });
+
+  it('omits the extra id when aria-describedby is not provided', () => {
+    render(<Select inputId="country" options={COUNTRIES} aria-label="Country" />);
+
+    const describedBy = screen.getByRole('combobox').getAttribute('aria-describedby');
+
+    expect(describedBy).not.toContain(ERROR_ID);
+  });
+});