@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Fieldset/Fieldset.stories.tsx

@@ -0,0 +1,304 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { FieldDivider, FieldItem, FieldLegend, FieldSet } from './Fieldset';
+import { Checkbox } from '../Checkbox/Checkbox';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { Heading } from '../Heading/Heading';
+import { HintText } from '../HintText/HintText';
+import { Label } from '../Label/Label';
+import { Radio, RadioGroup } from '../Radio/Radio';
+
+const meta: Meta<typeof FieldSet> = {
+  title: 'Components/Fieldset',
+  component: FieldSet,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Semantic wrapper for groups of related controls such as checkboxes and radio buttons. `FieldLegend` acts as the group label, screen readers announce it alongside each control's own label. `<fieldset disabled>` propagates disabled to every descendant without individual `disabled` props. `FieldItem` wraps each control, its `Label`, and an optional `HintText`, mirroring GDS's own govuk-radios__item/govuk-checkboxes__item markup (a plain div with separately-associated control/label/hint, not a wrapping label, so a hint is announced as its own accessible description). Wire `id`/`htmlFor`/`aria-describedby` by hand, same as `FormGroup`. Use `FieldDivider` to separate groups within the same fieldset.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof FieldSet>;
+
+export const CheckboxGroup: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: '`FieldLegend` is plain body text by default, matching GDS.',
+      },
+    },
+  },
+  render: () => (
+    <FieldSet>
+      <FieldLegend>Which countries have you visited?</FieldLegend>
+
+      <div className="flex flex-col gap-gds-2">
+        <FieldItem>
+          <Checkbox id="country-france" defaultChecked />
+
+          <Label htmlFor="country-france">France</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Checkbox id="country-germany" />
+
+          <Label htmlFor="country-germany">Germany</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Checkbox id="country-spain" />
+
+          <Label htmlFor="country-spain">Spain</Label>
+        </FieldItem>
+      </div>
+    </FieldSet>
+  ),
+};
+
+export const WithRadios: Story = {
+  render: () => (
+    <FieldSet>
+      <FieldLegend>Have you changed your name?</FieldLegend>
+
+      <RadioGroup defaultValue="no">
+        <FieldItem>
+          <Radio id="name-changed-yes" value="yes" />
+
+          <Label htmlFor="name-changed-yes">Yes</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Radio id="name-changed-no" value="no" />
+
+          <Label htmlFor="name-changed-no">No</Label>
+        </FieldItem>
+      </RadioGroup>
+    </FieldSet>
+  ),
+};
+
+export const WithHints: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Add a HintText inside FieldItem for a per-option hint, matching GDS\'s "How do you want to sign in?" pattern. id/htmlFor/aria-describedby are wired by hand here, same as everywhere else in the library.',
+      },
+    },
+  },
+  render: () => (
+    <FormGroup>
+      <FieldSet aria-describedby="sign-in-hint">
+        <FieldLegend>
+          <Heading level="h1">How do you want to sign in?</Heading>
+        </FieldLegend>
+
+        <HintText id="sign-in-hint">
+          You&apos;ll need an account to prove your identity and complete your Self Assessment
+        </HintText>
+
+        <RadioGroup defaultValue="government-gateway">
+          <FieldItem>
+            <Radio id="sign-in" value="government-gateway" aria-describedby="sign-in-item-hint" />
+
+            <Label htmlFor="sign-in">Sign in with Government Gateway</Label>
+
+            <HintText id="sign-in-item-hint">
+              You&apos;ll have a user ID if you&apos;ve registered for Self Assessment or filed a
+              tax return online before
+            </HintText>
+          </FieldItem>
+
+          <FieldItem>
+            <Radio id="sign-in-2" value="one-login" aria-describedby="sign-in-2-item-hint" />
+
+            <Label htmlFor="sign-in-2">Sign in with GOV.UK One Login</Label>
+
+            <HintText id="sign-in-2-item-hint">
+              If you don&apos;t have a GOV.UK One Login, you can create one
+            </HintText>
+          </FieldItem>
+        </RadioGroup>
+      </FieldSet>
+    </FormGroup>
+  ),
+};
+
+export const WithDivider: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`FieldDivider` separates two groups of options within the same fieldset. The default text is "or" but it can be overridden. Matches the GDS pattern for "select one of these, or this other option".',
+      },
+    },
+  },
+  render: () => (
+    <FieldSet>
+      <FieldLegend>What is your nationality?</FieldLegend>
+
+      <div className="flex flex-col gap-gds-2">
+        <FieldItem>
+          <Checkbox id="nationality-british" />
+
+          <Label htmlFor="nationality-british">British</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Checkbox id="nationality-irish" />
+
+          <Label htmlFor="nationality-irish">Irish</Label>
+        </FieldItem>
+
+        <FieldDivider />
+
+        <FieldItem>
+          <Checkbox id="nationality-other" />
+
+          <Label htmlFor="nationality-other">Citizen of another country</Label>
+        </FieldItem>
+      </div>
+    </FieldSet>
+  ),
+};
+
+export const WithDividerRadios: Story = {
+  render: () => (
+    <FieldSet>
+      <FieldLegend>Do you want to be contacted about this?</FieldLegend>
+
+      <RadioGroup>
+        <FieldItem>
+          <Radio id="contact-yes" value="yes" />
+
+          <Label htmlFor="contact-yes">Yes</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Radio id="contact-no" value="no" />
+
+          <Label htmlFor="contact-no">No</Label>
+        </FieldItem>
+
+        <FieldDivider />
+
+        <FieldItem>
+          <Radio id="contact-unsure" value="unsure" />
+
+          <Label htmlFor="contact-unsure">I&apos;m not sure</Label>
+        </FieldItem>
+      </RadioGroup>
+    </FieldSet>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <FormGroup invalid>
+      <FieldSet>
+        <FieldLegend>Which countries have you visited?</FieldLegend>
+
+        <ErrorText id="countries-error">Select at least one country</ErrorText>
+
+        <div className="flex flex-col gap-gds-2">
+          <FieldItem>
+            <Checkbox id="invalid-country-france" aria-invalid aria-describedby="countries-error" />
+
+            <Label htmlFor="invalid-country-france">France</Label>
+          </FieldItem>
+
+          <FieldItem>
+            <Checkbox
+              id="invalid-country-germany"
+              aria-invalid
+              aria-describedby="countries-error"
+            />
+
+            <Label htmlFor="invalid-country-germany">Germany</Label>
+          </FieldItem>
+
+          <FieldItem>
+            <Checkbox id="invalid-country-spain" aria-invalid aria-describedby="countries-error" />
+
+            <Label htmlFor="invalid-country-spain">Spain</Label>
+          </FieldItem>
+        </div>
+      </FieldSet>
+    </FormGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`<fieldset disabled>` disables every descendant form control at once. Labels are also dimmed via the `fieldset:disabled` CSS rule.',
+      },
+    },
+  },
+  render: () => (
+    <FieldSet disabled>
+      <FieldLegend>Which countries have you visited?</FieldLegend>
+
+      <div className="flex flex-col gap-gds-2">
+        <FieldItem>
+          <Checkbox id="disabled-country-france" defaultChecked />
+
+          <Label htmlFor="disabled-country-france">France</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Checkbox id="disabled-country-germany" />
+
+          <Label htmlFor="disabled-country-germany">Germany</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Checkbox id="disabled-country-spain" />
+
+          <Label htmlFor="disabled-country-spain">Spain</Label>
+        </FieldItem>
+      </div>
+    </FieldSet>
+  ),
+};
+
+export const WithHeading: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "FieldLegend has no size variants, it's plain body text, matching GDS. For a heading-like look (e.g. when the fieldset's question is the only content on the page), nest a real Heading inside it instead, the same pattern GDS itself documents: an <h1> inside <legend>.",
+      },
+    },
+  },
+  render: () => (
+    <FieldSet>
+      <FieldLegend>
+        <Heading level="h1">Consent preferences</Heading>
+      </FieldLegend>
+
+      <div className="flex flex-col gap-gds-2">
+        <FieldItem>
+          <Checkbox id="consent-name" defaultChecked />
+
+          <Label htmlFor="consent-name">Share my name</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Checkbox id="consent-email" />
+
+          <Label htmlFor="consent-email">Share my email address</Label>
+        </FieldItem>
+      </div>
+    </FieldSet>
+  ),
+};

package/src/components/Fieldset/Fieldset.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type FieldSetProps = ComponentProps<'fieldset'>;
+
+export const FieldSet = ({ className, ...props }: FieldSetProps) => (
+  <fieldset data-slot="field-set" className={cn('cn-field-set', className)} {...props} />
+);
+
+export type FieldLegendProps = ComponentProps<'legend'>;
+
+export const FieldLegend = ({ className, ...props }: FieldLegendProps) => (
+  <legend data-slot="field-legend" className={cn('cn-field-legend', className)} {...props} />
+);
+
+// MARK: FieldItem
+// Mirrors GDS's own govuk-radios__item/govuk-checkboxes__item: a plain div
+// around explicit, separately-associated Radio/Checkbox + Label + optional
+// HintText siblings (real GDS, not a wrapping <label>), so a hint is
+// announced as its own accessible description rather than folded into the
+// control's name. Wire id/htmlFor/aria-describedby by hand, same as
+// FormGroup, no context here, see the WithHints story for the pattern.
+export type FieldItemProps = ComponentProps<'div'>;
+
+export const FieldItem = ({ className, ...props }: FieldItemProps) => (
+  <div data-slot="field-item" className={cn('cn-field-item', className)} {...props} />
+);
+
+export type FieldDividerProps = ComponentProps<'div'>;
+
+export const FieldDivider = ({ className, children = 'or', ...props }: FieldDividerProps) => (
+  <div data-slot="field-divider" className={cn('cn-field-divider', className)} {...props}>
+    {children}
+  </div>
+);

package/src/components/FileUpload/FileUpload.css

@@ -0,0 +1,85 @@
+@layer components {
+  /* MARK: File upload
+     Two-bordered-section layout: trigger has its own cn-form-border (right edge
+     acts as the internal divider), field wrapper has cn-form-border with no left
+     border so it merges flush. Error border and focus ring apply only to the
+     field section, matching the InputGroup prefix/swatch pattern. */
+  .cn-file-upload {
+    @apply flex w-full;
+
+    &:has(:disabled) {
+      @apply opacity-50;
+
+      .cn-file-upload-trigger {
+        @apply cursor-not-allowed;
+      }
+    }
+  }
+
+  /* MARK: Trigger
+     <label> styled as a secondary-button swatch. Its right border doubles as
+     the visual divider between the trigger and the filename area. */
+  .cn-file-upload-trigger {
+    @apply cn-form-swatch shrink-0 px-gds-2 text-body cursor-pointer select-none border-r-0;
+  }
+
+  .cn-file-upload:not(:has(:disabled)) .cn-file-upload-trigger {
+    &:hover {
+      @apply bg-muted;
+    }
+  }
+
+  /* MARK: Field
+     Wraps the hidden input and filename display. No left border, butts flush
+     against the trigger. Focus ring and error border are scoped here so the
+     trigger is unaffected when the field is invalid. bg-panel is explicit
+     since, unlike a real <input> (opaque by default via the browser's own
+     UA styles), the filename display is a plain <span> with no background
+     of its own, it would otherwise show through to whatever's behind the
+     component (e.g. blending into an Accordion's own background) instead of
+     reading as a distinct field. */
+  .cn-file-upload-field {
+    @apply cn-form-border relative flex items-center flex-1 min-w-0 h-10 bg-panel;
+
+    &:focus-within {
+      @apply outline-focus;
+      box-shadow: inset 0 0 0 var(--border-width-form) var(--color-divider-input);
+    }
+
+    &:has([aria-invalid='true']),
+    &:has(:user-invalid) {
+      @apply border-error;
+
+      &:focus-within {
+        box-shadow: inset 0 0 0 var(--border-width-form) var(--color-error);
+      }
+    }
+  }
+
+  /* MARK: Hidden input */
+  .cn-file-upload-input {
+    @apply sr-only;
+  }
+
+  /* MARK: Filename display
+     min-w-0 overrides the flex item default of min-width: auto, which
+     otherwise refuses to shrink below the filename's own unbroken width
+     (truncate implies white-space: nowrap) and overflows the container
+     instead of actually truncating. Same fix applied to the parent
+     cn-file-upload-field above, a flex item itself, for the same reason. */
+  .cn-file-upload-filename {
+    @apply flex-1 min-w-0 px-gds-2 text-base text-body truncate;
+  }
+
+  .cn-file-upload[data-state='empty'] .cn-file-upload-filename {
+    @apply text-body-secondary;
+  }
+
+  /* MARK: Clear button
+     Sits inside the same bordered field as the filename, not a separate
+     element outside it. mr-gds-1 keeps it off the field's own right border,
+     matching the breathing room the filename already gets on its own side. */
+  .cn-file-upload-clear {
+    @apply mr-gds-1;
+  }
+}

package/src/components/FileUpload/FileUpload.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { FileUpload } from './FileUpload';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { HintText } from '../HintText/HintText';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof FileUpload> = {
+  title: 'Components/FileUpload',
+  component: FileUpload,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A styled file picker that matches the height and border treatment of the Input component. The "Select file" trigger is a `<label>` element associated with a visually hidden but keyboard-accessible `<input type="file">`, so no JavaScript is needed to open the file dialog. It works with click, touch, and keyboard. Pair it with a `<Label>` above for the field name, the same as any other form field. Once a file is selected, a clear button appears to remove it, pick a real file in the Default story below to see it.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof FileUpload>;
+
+export const Default: Story = {
+  render: (args) => (
+    <FormGroup>
+      <Label htmlFor="id-a">Upload boundary file</Label>
+
+      <FileUpload {...args} id="id-a" />
+    </FormGroup>
+  ),
+};
+
+export const WithAcceptHint: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass `accept` to restrict the file picker to specific types. Hint text below the field describes the constraint to users, the component itself does not render hint text.',
+      },
+    },
+  },
+  render: (args) => (
+    <FormGroup>
+      <Label htmlFor="id-b">Upload boundary file</Label>
+
+      <HintText>Supports .geojson, .kml.</HintText>
+
+      <FileUpload {...args} id="id-b" accept=".geojson,.kml" />
+    </FormGroup>
+  ),
+};
+
+export const WithError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Set `aria-invalid="true"` to show the error border on the filename area.',
+      },
+    },
+  },
+  render: (args) => (
+    <FormGroup invalid>
+      <Label htmlFor="id-c">Upload boundary file</Label>
+
+      <ErrorText id="file-upload-error">Select a file to continue</ErrorText>
+
+      <FileUpload {...args} aria-invalid="true" aria-describedby="file-upload-error" id="id-c" />
+    </FormGroup>
+  ),
+};
+
+export const LongFilename: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A long filename truncates with an ellipsis rather than overflowing the field, the component stays no wider than its container. Uses `placeholder` here to demonstrate this without needing to actually pick a file, real selected filenames go through the same truncation.',
+      },
+    },
+  },
+  render: (args) => (
+    <FormGroup className="max-w-xs">
+      <Label htmlFor="id-e">Upload boundary file</Label>
+
+      <FileUpload
+        {...args}
+        id="id-e"
+        placeholder="environment-agency-flood-risk-boundary-data-2024-final-v3.geojson"
+      />
+    </FormGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <FormGroup>
+      <Label htmlFor="id-d">Upload boundary file</Label>
+
+      <FileUpload {...args} id="id-d" disabled />
+    </FormGroup>
+  ),
+};

package/src/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import { useRef, useState, type ChangeEvent, type ComponentProps, type ReactNode } from 'react';
+
+import { LuX } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Button } from '../Button/Button';
+
+export type FileUploadProps = Omit<ComponentProps<'input'>, 'type' | 'id'> & {
+  id: string;
+  triggerLabel?: ReactNode;
+  placeholder?: ReactNode;
+};
+
+export const FileUpload = ({
+  id,
+  triggerLabel = 'Select file',
+  placeholder = 'No file selected',
+  className,
+  onChange,
+  ...props
+}: FileUploadProps) => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [displayName, setDisplayName] = useState<string | null>(null);
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const files = event.target.files;
+
+    if (!files || files.length === 0) {
+      setDisplayName(null);
+    } else if (files.length === 1 && files[0]) {
+      setDisplayName(files[0].name);
+    } else {
+      setDisplayName(`${files.length} files selected`);
+    }
+
+    onChange?.(event);
+  };
+
+  const handleClear = () => {
+    const input = inputRef.current;
+
+    if (!input) {
+      return;
+    }
+
+    // A file input's value can't be set programmatically, but clearing it
+    // back to empty is allowed. Dispatching a real change event (rather than
+    // calling setDisplayName directly) reuses handleChange as the single
+    // source of truth, so the consumer's own onChange fires too, exactly as
+    // if the file had been cleared through the picker itself.
+    input.value = '';
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+
+    // The clear button disappears once displayName clears, move focus
+    // somewhere sensible rather than letting it fall back to <body>.
+    input.focus();
+  };
+
+  return (
+    <div
+      data-slot="file-upload"
+      data-state={displayName ? 'has-file' : 'empty'}
+      className={cn('cn-file-upload', className)}
+    >
+      <label htmlFor={id} className="cn-file-upload-trigger">
+        {triggerLabel}
+      </label>
+
+      <div className="cn-file-upload-field">
+        <input
+          ref={inputRef}
+          type="file"
+          id={id}
+          className="cn-file-upload-input"
+          onChange={handleChange}
+          {...props}
+        />
+
+        <span className="cn-file-upload-filename" aria-live="polite">
+          {displayName ?? placeholder}
+        </span>
+
+        {displayName ? (
+          <Button
+            variant="icon"
+            appearance="ghost"
+            aria-label="Remove selected file"
+            onClick={handleClear}
+            className="cn-file-upload-clear"
+          >
+            <LuX aria-hidden />
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+};

package/src/components/{layout/footer → Footer}/Copyright.tsx

@@ -1,11 +1,13 @@
-import { ExternalLink } from '../../link/ExternalLink';
+import { ExternalLink } from '../ExternalLink/ExternalLink';
 
 export const Copyright = () => {
   const currentYear = new Date().getFullYear();
 
   return (
     <ExternalLink
-      className="text-black text-balance sm:text-nowrap text-center sm:text-left justify-start"
+      className="text-balance sm:text-nowrap text-center sm:text-left justify-start"
+      appearance="contrast"
+      variant="plain"
       href="https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/"
     >
       &copy; Crown Copyright {currentYear}

package/src/components/Footer/Footer.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Footer } from './Footer';
+
+const meta = {
+  title: 'Components/Footer',
+  component: Footer,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Full site footer with support links, the Open Government Licence notice, and crown copyright.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Footer>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};