@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Chip/Chip.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Chip } from './Chip';
+
+const meta: Meta<typeof Chip> = {
+  title: 'Components/Chip',
+  component: Chip,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Displays a chip. Use the Tag component if it has semantic importance.',
+      },
+    },
+  },
+  argTypes: {
+    appearance: {
+      control: { type: 'radio' },
+      options: ['neutral', 'success', 'warning', 'error', 'info'],
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['sm', 'base', 'lg'],
+    },
+    children: { control: 'text' },
+  },
+  args: {
+    children: 'Soil',
+    size: 'base',
+    appearance: 'info',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Chip>;
+
+export const Appearances: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Subtle tinted backgrounds are used for all semantic appearances to avoid looking interactive. `primary` uses the solid brand colour and is suitable for selected state or active filters.',
+      },
+    },
+  },
+  render: (args) => (
+    <div className="flex flex-wrap gap-gds-2">
+      <Chip {...args} appearance="neutral">
+        Neutral
+      </Chip>
+
+      <Chip {...args} appearance="success">
+        Success
+      </Chip>
+
+      <Chip {...args} appearance="warning">
+        Warning
+      </Chip>
+
+      <Chip {...args} appearance="error">
+        Error
+      </Chip>
+
+      <Chip {...args} appearance="info">
+        Info
+      </Chip>
+    </div>
+  ),
+};
+
+export const Small: Story = {
+  args: { size: 'sm' },
+};
+
+export const Large: Story = {
+  args: { size: 'lg' },
+};
+
+export const Inline: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All chips use negative margins so they sit inline within body text without inflating line height.',
+      },
+    },
+  },
+  render: (args) => (
+    <p>
+      Use a keyword like <Chip {...args} /> to narrow your search.
+    </p>
+  ),
+};

package/src/components/Chip/Chip.tsx

@@ -0,0 +1,34 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+const CHIP_APPEARANCES = {
+  neutral: 'cn-chip-appearance-neutral',
+  success: 'cn-chip-appearance-success',
+  warning: 'cn-chip-appearance-warning',
+  error: 'cn-chip-appearance-error',
+  info: 'cn-chip-appearance-info',
+} as const;
+
+const CHIP_SIZES = {
+  sm: 'cn-chip-size-sm',
+  base: 'cn-chip-size-base',
+  lg: 'cn-chip-size-lg',
+} as const;
+
+export type ChipSize = keyof typeof CHIP_SIZES;
+export type ChipAppearances = keyof typeof CHIP_APPEARANCES;
+
+export type ChipProps = ComponentProps<'span'> & {
+  size?: ChipSize;
+  appearance: ChipAppearances;
+};
+
+export const Chip = ({ className, size = 'base', appearance, ...props }: ChipProps) => (
+  <span
+    data-slot="chip"
+    data-size={size}
+    className={cn('cn-chip', CHIP_SIZES[size], CHIP_APPEARANCES[appearance], className)}
+    {...props}
+  />
+);

package/src/components/CookieBanner/CookieBanner.css

@@ -0,0 +1,19 @@
+@layer components {
+  /* MARK: Cookie banner
+     Full-width bar at the top of the page. Background and bottom border
+     match the GDS govuk-cookie-banner pattern. */
+  .cn-cookie-banner {
+    @apply bg-surface border-b border-divider py-gds-4;
+  }
+
+  /* MARK: Inner wrapper
+     Centres and constrains content. Flex column with gap replaces browser
+     default heading/paragraph margins, which vary and break the GDS spacing. */
+  .cn-cookie-banner-inner {
+    @apply mx-auto max-w-lg px-gds-4 flex flex-col gap-gds-3;
+
+    & :is(h1, h2, h3, h4, h5, h6, p) {
+      @apply m-0;
+    }
+  }
+}

package/src/components/CookieBanner/CookieBanner.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { CookieBanner } from './CookieBanner';
+
+const meta: Meta<typeof CookieBanner> = {
+  title: 'Components/CookieBanner',
+  component: CookieBanner,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+GDS-style cookie consent banner. Starts hidden (\`display: none\`) and is shown by the external cookie-banner script when appropriate.
+
+The \`id="cookie-banner"\` and \`id="accept-all-cookies"\` attributes are required by the script to attach its event handlers.
+
+**Props:**
+- \`cookiePolicyUrl\`: URL for your cookie policy page, used in the body text link and the reject button.
+- \`scriptSrc\`: URL of the cookie banner JS. Defaults to the EA shared script.
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CookieBanner>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Rendered without the external script so the banner is visible. In production it starts hidden and is shown by the cookie-banner script.',
+      },
+    },
+  },
+  args: {
+    serviceName: 'My service',
+    cookiePolicyUrl: 'https://environment.data.gov.uk/help/cookies',
+    style: { display: 'block' },
+  },
+};
+
+export const CustomBackgroundColor: Story = {
+  args: {
+    className: 'bg-wash',
+    serviceName: 'My service',
+    cookiePolicyUrl: 'https://environment.data.gov.uk/help/cookies',
+    style: { display: 'block' },
+  },
+};

package/src/components/CookieBanner/CookieBanner.tsx

@@ -0,0 +1,55 @@
+import { type ComponentProps } from 'react';
+
+import Script from 'next/script';
+
+import { cn } from '../../utils/components';
+import { Button } from '../Button/Button';
+import { ExternalLink } from '../ExternalLink/ExternalLink';
+import { Heading } from '../Heading/Heading';
+import { ButtonGroup } from '../Layout/ButtonGroup/ButtonGroup';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+export type CookieBannerProps = ComponentProps<'div'> & {
+  serviceName: string;
+  cookiePolicyUrl?: string;
+  scriptSrc?: string;
+};
+
+export const CookieBanner = ({
+  serviceName,
+  cookiePolicyUrl = 'https://environment.data.gov.uk/help/cookies',
+  scriptSrc = 'https://environment.data.gov.uk/shared/cookie-banner.js',
+  className,
+  style,
+  ...props
+}: CookieBannerProps) => (
+  <div
+    id="cookie-banner"
+    role="region"
+    aria-label="Cookie banner"
+    className={cn('cn-cookie-banner', className)}
+    style={{ display: 'none', ...style }}
+    {...props}
+  >
+    <Script src={scriptSrc} />
+
+    <div className="cn-cookie-banner-inner">
+      <Heading level="h2">Cookies on {serviceName}</Heading>
+
+      <Paragraph>We use some essential cookies to make this service work.</Paragraph>
+
+      <Paragraph>
+        We&apos;d also like to use analytics cookies so we can understand how you use the service
+        and make improvements.
+      </Paragraph>
+
+      <ButtonGroup>
+        <Button id="accept-all-cookies">Accept analytics cookies</Button>
+
+        <Button id="reject-all-cookies">Reject analytics cookies</Button>
+
+        <ExternalLink href={cookiePolicyUrl}>View cookies</ExternalLink>
+      </ButtonGroup>
+    </div>
+  </div>
+);

package/src/components/CopyButton/CopyButton.stories.tsx

@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { CopyButton } from './CopyButton';
+
+const meta: Meta<typeof CopyButton> = {
+  title: 'Components/CopyButton',
+  component: CopyButton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use a CopyButton to copy some text or other data to the clipboard.',
+      },
+    },
+  },
+  argTypes: {
+    content: { control: 'text' },
+  },
+  args: {
+    content: 'Copy me',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof CopyButton>;
+
+export const Default: Story = {};

package/src/components/CopyButton/CopyButton.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useEffect, useRef, useState, type ComponentProps } from 'react';
+
+import { LuCheck, LuCopy } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Button } from '../Button/Button';
+
+export type CopyButtonProps = Omit<
+  ComponentProps<typeof Button>,
+  'type' | 'variant' | 'children' | 'onClick' | 'aria-label'
+> & {
+  content?: string | ClipboardItem[];
+};
+
+export const CopyButton = ({ className, content, ...props }: CopyButtonProps) => {
+  const [copied, setCopied] = useState<number | null>(null);
+
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!copied) {
+      return;
+    }
+
+    const clear = () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+
+    clear();
+
+    timeoutRef.current = setTimeout(() => setCopied(null), copied);
+
+    return clear;
+  }, [copied]);
+
+  const handleCopy = async () => {
+    if (!content) {
+      return;
+    }
+
+    if (typeof content === 'string') {
+      await navigator.clipboard.writeText(content);
+    } else {
+      await navigator.clipboard.write(content);
+    }
+
+    setCopied(2000);
+  };
+
+  return (
+    <Button
+      variant="icon"
+      className={cn(className, 'cn-copy-button')}
+      onClick={handleCopy}
+      aria-label={copied ? 'Content copied to clipboard' : 'Copy content'}
+      {...props}
+    >
+      {copied ? <LuCheck aria-hidden /> : <LuCopy aria-hidden />}
+    </Button>
+  );
+};

package/src/components/DateInput/DateInput.css

@@ -0,0 +1,13 @@
+@layer components {
+  /* MARK: Date input
+     Three side-by-side fields following the GDS date input pattern.
+     Each field is a column of label + input, the inputs are max-width
+     constrained via cn-input-size-date-part and cn-input-size-year. */
+  .cn-date-input {
+    @apply flex gap-gds-3;
+  }
+
+  .cn-date-input-field {
+    @apply flex flex-col gap-gds-1;
+  }
+}

package/src/components/DateInput/DateInput.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { DateInput } from './DateInput';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { HintText } from '../HintText/HintText';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof DateInput> = {
+  title: 'Components/DateInput',
+  component: DateInput,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Three separate text inputs for day, month, and year, following the GDS date input pattern. Uses `type="text"` with `inputMode="numeric"` rather than `type="number"` to avoid browser spinners and allow leading zeros. Each field ID is derived from the `id` prop with a `-day`, `-month`, or `-year` suffix, use these when wiring up `aria-describedby` on error messages. Pass `invalid={true}` to mark all fields, or an object like `{ day: true }` to mark specific ones.',
+      },
+    },
+  },
+  args: {
+    id: 'date',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DateInput>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-gds-1">
+      <Label htmlFor={`${args.id}-day`}>Date of birth</Label>
+
+      <DateInput {...args} />
+    </div>
+  ),
+};
+
+export const WithDefault: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pre-populated using `defaultValue`. The component manages state internally from this point.',
+      },
+    },
+  },
+  args: {
+    defaultValue: { day: '5', month: '3', year: '1990' },
+  },
+  render: (args) => (
+    <div className="flex flex-col gap-gds-1">
+      <Label htmlFor={`${args.id}-day`}>Date of birth</Label>
+
+      <HintText>For example, 27 3 2007</HintText>
+
+      <DateInput {...args} />
+    </div>
+  ),
+};
+
+export const AllFieldsInvalid: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass `invalid={true}` to mark all three fields with an error border. Used when the date as a whole is invalid (e.g. a date that does not exist).',
+      },
+    },
+  },
+  render: (args) => (
+    <FormGroup invalid>
+      <Label htmlFor={`${args.id}-day`}>Date of birth</Label>
+
+      <HintText>For example, 27 3 2007</HintText>
+
+      <ErrorText id="date-error-all">Enter a valid date of birth</ErrorText>
+
+      <DateInput
+        {...args}
+        invalid
+        defaultValue={{ day: '31', month: '2', year: '1990' }}
+        aria-describedby="date-error-all"
+      />
+    </FormGroup>
+  ),
+};
+
+export const PartialInvalid: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass an object to `invalid` to highlight only the specific fields that are wrong. Useful when part of the date is missing or implausible.',
+      },
+    },
+  },
+  render: (args) => (
+    <FormGroup invalid>
+      <Label htmlFor={`${args.id}-day`}>Date of birth</Label>
+
+      <HintText>For example, 27 3 2007</HintText>
+
+      <ErrorText id="date-error-partial">Date of birth must include a year</ErrorText>
+
+      <DateInput
+        {...args}
+        invalid={{ year: true }}
+        defaultValue={{ day: '15', month: '6', year: '' }}
+        aria-describedby="date-error-partial"
+      />
+    </FormGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    defaultValue: { day: '1', month: '1', year: '2000' },
+    disabled: true,
+  },
+  render: (args) => (
+    <div className="flex flex-col gap-gds-1">
+      <Label htmlFor={`${args.id}-day`}>Date of birth</Label>
+
+      <HintText>For example, 27 3 2007</HintText>
+
+      <DateInput {...args} />
+    </div>
+  ),
+};

package/src/components/DateInput/DateInput.test.tsx

@@ -0,0 +1,21 @@
+import { DateInput } from './DateInput';
+import { render, screen } from '../../test/renderers';
+
+const ERROR_ID = 'dob-error';
+const ARIA_DESCRIBEDBY = 'aria-describedby';
+
+describe('DateInput', () => {
+  it('applies aria-describedby to all three day/month/year inputs', () => {
+    render(<DateInput id="dob" aria-describedby={ERROR_ID} />);
+
+    expect(screen.getByLabelText('Day')).toHaveAttribute(ARIA_DESCRIBEDBY, ERROR_ID);
+    expect(screen.getByLabelText('Month')).toHaveAttribute(ARIA_DESCRIBEDBY, ERROR_ID);
+    expect(screen.getByLabelText('Year')).toHaveAttribute(ARIA_DESCRIBEDBY, ERROR_ID);
+  });
+
+  it('omits aria-describedby when not provided', () => {
+    render(<DateInput id="dob" />);
+
+    expect(screen.getByLabelText('Day')).not.toHaveAttribute(ARIA_DESCRIBEDBY);
+  });
+});

package/src/components/DateInput/DateInput.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import { useState, type ChangeEvent } from 'react';
+
+import { cn } from '../../utils/components';
+import { Input } from '../Input/Input';
+import { Label } from '../Label/Label';
+
+export type DateValue = {
+  day: string;
+  month: string;
+  year: string;
+};
+
+export type DateInputInvalid = boolean | { day?: boolean; month?: boolean; year?: boolean };
+
+export type DateInputProps = {
+  id: string;
+  name?: string;
+  value?: DateValue;
+  defaultValue?: DateValue;
+  onChange?: (value: DateValue) => void;
+  invalid?: DateInputInvalid;
+  disabled?: boolean;
+  className?: string;
+  /** Applied to all three day/month/year inputs, matching GDS's own date
+   * input pattern: one shared error message for the whole date, not one per
+   * field, so every field's aria-describedby points at the same id. */
+  'aria-describedby'?: string;
+};
+
+const EMPTY_DATE: DateValue = { day: '', month: '', year: '' };
+
+const FIELDS = [
+  { key: 'day' as const, label: 'Day', size: 'date-part' as const, maxLength: 2 },
+  { key: 'month' as const, label: 'Month', size: 'date-part' as const, maxLength: 2 },
+  { key: 'year' as const, label: 'Year', size: 'year' as const, maxLength: 4 },
+];
+
+const resolveFieldInvalid = (invalid: DateInputInvalid, field: keyof DateValue): boolean => {
+  if (typeof invalid === 'boolean') {
+    return invalid;
+  }
+
+  return invalid[field] ?? false;
+};
+
+export const DateInput = ({
+  id,
+  name,
+  value,
+  defaultValue,
+  onChange,
+  invalid = false,
+  disabled,
+  className,
+  'aria-describedby': ariaDescribedBy,
+}: DateInputProps) => {
+  const [internalValue, setInternalValue] = useState<DateValue>(defaultValue ?? EMPTY_DATE);
+
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value : internalValue;
+
+  const handleChange = (field: keyof DateValue) => (event: ChangeEvent<HTMLInputElement>) => {
+    const newValue = { ...currentValue, [field]: event.target.value };
+
+    if (!isControlled) {
+      setInternalValue(newValue);
+    }
+
+    onChange?.(newValue);
+  };
+
+  return (
+    <div data-slot="date-input" className={cn('cn-date-input', className)}>
+      {FIELDS.map(({ key, label, size, maxLength }) => (
+        <div key={key} className="cn-date-input-field">
+          <Label htmlFor={`${id}-${key}`}>{label}</Label>
+
+          <Input
+            type="text"
+            inputMode="numeric"
+            pattern="[0-9]*"
+            id={`${id}-${key}`}
+            name={name ? `${name}-${key}` : undefined}
+            size={size}
+            maxLength={maxLength}
+            value={currentValue[key]}
+            onChange={handleChange(key)}
+            aria-invalid={resolveFieldInvalid(invalid, key) ? 'true' : undefined}
+            aria-describedby={ariaDescribedBy}
+            disabled={disabled}
+          />
+        </div>
+      ))}
+    </div>
+  );
+};

package/src/components/Details/Details.css

@@ -0,0 +1,28 @@
+@layer components {
+  /* MARK: Details */
+  .cn-details-trigger {
+    @apply cn-link-decoration cn-link-appearance-primary text-base gap-gds-1 cursor-pointer flex
+      items-center;
+  }
+
+  /* GDS yellow focus box: matches the pattern used by .cn-link */
+  .cn-details-trigger:focus {
+    @apply text-on-focus bg-focus no-underline outline-focus outline-transparent;
+    box-shadow:
+      0 -2px var(--color-focus),
+      0 4px var(--color-on-focus);
+  }
+
+  .cn-details-trigger[data-state='open'] .cn-details-trigger-icon {
+    @apply rotate-90;
+  }
+
+  .cn-details-trigger-icon {
+    @apply size-[1em] stroke-3;
+  }
+
+  /* MARK: Content */
+  .cn-details-content {
+    @apply border-l-standard border-divider mt-1.5 py-gds-3 pl-gds-4;
+  }
+}

package/src/components/Details/Details.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Details, DetailsContent, DetailsTrigger } from './Details';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+const meta: Meta<typeof Details> = {
+  title: 'Components/Details',
+  component: Details,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Make a page easier to scan by letting users reveal more detailed information only if they need it.',
+      },
+    },
+  },
+  argTypes: {
+    children: { control: 'text' },
+  },
+  args: {
+    children: 'Help with nationality',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Details>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Details>
+      <DetailsTrigger>{args.children}</DetailsTrigger>
+
+      <DetailsContent>
+        <Paragraph>
+          We need to know your nationality so we can work out which elections you’re entitled to
+          vote in. If you cannot provide your nationality, you’ll have to send copies of identity
+          documents through the post.
+        </Paragraph>
+      </DetailsContent>
+    </Details>
+  ),
+};
+
+// export const Disabled: Story = {
+//     args:{disabled: true}
+// };