@tpzdsp/next-toolkit 2.5.1 → 3.1.0

package/src/components/ErrorModal/ErrorModal.stories.tsx

@@ -0,0 +1,100 @@
+import { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ErrorModal } from './ErrorModal';
+import { ApiError } from '../../errors/ApiError';
+import { Button } from '../Button/Button';
+
+const meta: Meta<typeof ErrorModal> = {
+  title: 'Components/ErrorModal',
+  component: ErrorModal,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A Modal preset for reporting an error: an alert icon beside the message, with an optional expandable "Technical information" section (message, details, digest, and a copy-to-clipboard button that includes the stack trace when available) driven entirely by the `error` prop. Shares its error-describing logic with ErrorFallback via `getErrorDisplayInfo`/`formatErrorForClipboard`, so both surfaces describe the same error the same way.',
+      },
+    },
+  },
+  argTypes: {
+    children: { control: false },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ErrorModal>;
+
+export const Default: Story = {
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Trigger error</Button>
+
+        <ErrorModal
+          open={open}
+          onOpenChange={setOpen}
+          error={new Error('Failed to fetch sampling points')}
+        >
+          An error occurred while fetching sampling points.
+        </ErrorModal>
+      </>
+    );
+  },
+};
+
+export const WithApiError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'ApiError additionally carries `details` and a `digest`, both shown in the technical information section and included in the copied text.',
+      },
+    },
+  },
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Trigger error</Button>
+
+        <ErrorModal
+          open={open}
+          onOpenChange={setOpen}
+          error={ApiError.internalServerError('The upstream sampling points service timed out')}
+        >
+          An error occurred while fetching sampling points.
+        </ErrorModal>
+      </>
+    );
+  },
+};
+
+export const WithoutError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'No `error` prop, no technical information section is rendered, just the message and a close button.',
+      },
+    },
+  },
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Trigger error</Button>
+
+        <ErrorModal open={open} onOpenChange={setOpen}>
+          Something went wrong. Try again in a few minutes.
+        </ErrorModal>
+      </>
+    );
+  },
+};

package/src/components/ErrorModal/ErrorModal.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import type { ComponentProps, ReactNode } from 'react';
+
+import { LuCircleAlert } from 'react-icons/lu';
+
+import { formatErrorForClipboard, getErrorDisplayInfo } from '../../errors/errorDisplay';
+import { Button } from '../Button/Button';
+import { CopyButton } from '../CopyButton/CopyButton';
+import { Details, DetailsContent, DetailsTrigger } from '../Details/Details';
+import { HintText } from '../HintText/HintText';
+import { Stack } from '../Layout/Stack/Stack';
+import {
+  Modal,
+  ModalContent,
+  ModalDescription,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+} from '../Modal/Modal';
+import {
+  SummaryList,
+  SummaryListKey,
+  SummaryListRow,
+  SummaryListValue,
+} from '../SummaryList/SummaryList';
+
+export type ErrorModalProps = Omit<ComponentProps<typeof Modal>, 'children'> & {
+  /** The error that occurred. When set, an expandable "Technical information"
+   * section shows its message/details/digest, with a button to copy all of
+   * it (including the stack trace, when available) to the clipboard. */
+  error?: unknown;
+  title?: ReactNode;
+  children?: ReactNode;
+  closeLabel?: ReactNode;
+};
+
+export const ErrorModal = ({
+  error,
+  title = 'An error occurred',
+  children,
+  closeLabel = 'Close',
+  onOpenChange,
+  ...props
+}: ErrorModalProps) => {
+  const info = error !== undefined ? getErrorDisplayInfo(error) : null;
+
+  return (
+    <Modal onOpenChange={onOpenChange} {...props}>
+      <ModalContent className="cn-error-modal">
+        <div className="cn-error-modal-icon">
+          <LuCircleAlert aria-hidden className="size-8" />
+        </div>
+
+        <Stack gap="sm" className="cn-error-modal-body">
+          <ModalHeader>
+            <ModalTitle>{title}</ModalTitle>
+          </ModalHeader>
+
+          {/* ModalDescription renders a <p> (it's the target of the
+              dialog's aria-describedby), which can only contain phrasing
+              content. children is assumed to be plain descriptive text for
+              that reason, Details below is a sibling instead, not nested
+              inside it, both to stay valid HTML (a browser silently closes
+              a <p> early upon hitting a nested block element, which desyncs
+              SSR/client markup into a hydration error, exactly like nesting
+              a <dl> in one here did) and because interactive elements like
+              the copy button below don't make sense as part of an
+              aria-describedby'd description in the first place. */}
+          <ModalDescription>{children}</ModalDescription>
+
+          {info ? (
+            <Details>
+              <DetailsTrigger>Technical information</DetailsTrigger>
+
+              <DetailsContent>
+                <Stack gap="sm">
+                  <div className="cn-error-modal-details">
+                    <SummaryList>
+                      <SummaryListRow>
+                        <SummaryListKey>Reason</SummaryListKey>
+
+                        <SummaryListValue>{info.message}</SummaryListValue>
+                      </SummaryListRow>
+
+                      {info.details ? (
+                        <SummaryListRow>
+                          <SummaryListKey>Details</SummaryListKey>
+
+                          <SummaryListValue>{info.details}</SummaryListValue>
+                        </SummaryListRow>
+                      ) : null}
+
+                      {info.digest ? (
+                        <SummaryListRow>
+                          <SummaryListKey>Digest</SummaryListKey>
+
+                          <SummaryListValue>{info.digest}</SummaryListValue>
+                        </SummaryListRow>
+                      ) : null}
+                    </SummaryList>
+                  </div>
+
+                  <div className="flex flex-col gap-gds-1">
+                    <CopyButton appearance="secondary" content={formatErrorForClipboard(info)} />
+
+                    <HintText className="text-sm">
+                      Copy to share error details with the app administrator.
+                    </HintText>
+                  </div>
+                </Stack>
+              </DetailsContent>
+            </Details>
+          ) : null}
+
+          <ModalFooter className="sm:justify-start">
+            <Button onClick={() => onOpenChange?.(false)}>{closeLabel}</Button>
+          </ModalFooter>
+        </Stack>
+      </ModalContent>
+    </Modal>
+  );
+};

package/src/components/ErrorText/ErrorText.css

@@ -0,0 +1,22 @@
+@layer components {
+  /* Meant to stay mounted at all times (even with no error, as empty
+     children), rather than being conditionally rendered, so it's a stable
+     role="alert" live region screen readers can reliably announce content
+     changes on. A live region needs to already exist in the DOM before its
+     content changes for that announcement to be reliable, inserting a
+     brand new role="alert" node after the fact is a recognised trigger too,
+     but is markedly less consistent across AT/browser combinations.
+     Consumers that always render a fixed, non-empty message (e.g.
+     ErrorFallback) are unaffected by the rule below, it only ever matches
+     when there's genuinely no content. */
+  .cn-error-text {
+    @apply text-error font-bold;
+
+    /* Cancels out the gap-gds-1 that FormGroup/FieldSet's flex layout would
+       otherwise still apply around this element even while it's empty,
+       leaving no permanent dead space when there's no error to show. */
+    &:empty {
+      margin-top: calc(var(--spacing-gds-1) * -1);
+    }
+  }
+}

package/src/components/ErrorText/ErrorText.stories.tsx

@@ -1,27 +1,30 @@
+import { useState } from 'react';
+
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { ErrorText } from './ErrorText';
-import { ExternalLink } from '../link/ExternalLink';
+import { Button } from '../Button/Button';
+import { FormGroup } from '../Form/FormGroup';
+import { Input } from '../Input/Input';
+import { Label } from '../Label/Label';
 
 const meta: Meta<typeof ErrorText> = {
   title: 'Components/ErrorText',
   component: ErrorText,
+  tags: ['autodocs'],
   parameters: {
-    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Show an error message next to the field and in the Error summary component when there is a validation error. Renders role="alert" (plus explicit aria-live/aria-atomic). Always render ErrorText, even with no error (empty children), rather than conditionally mounting it: a live region needs to already exist in the DOM before its content changes for screen readers to reliably announce that change, inserting a brand new role="alert" node after the fact is a recognised trigger too, but is markedly less consistent. The empty state collapses to zero height and cancels out FormGroup/FieldSet\'s own gap, so it never leaves a permanent gap when there\'s nothing to show.',
+      },
+    },
   },
-  tags: ['autodocs'],
   argTypes: {
-    children: {
-      description: 'The content to display for the error',
-      control: false,
-    },
-    className: {
-      description: 'Additional TailwindCSS classes to apply',
-      control: 'text',
-    },
+    children: { control: 'text' },
   },
   args: {
-    children: 'Error message',
+    children: 'The date your passport was issued must be in the past',
   },
 };
 
@@ -31,22 +34,34 @@ type Story = StoryObj<typeof ErrorText>;
 
 export const Default: Story = {};
 
-export const CustomStyling: Story = {
-  args: {
-    className: 'text-3xl',
-    children: 'Custom styled error message',
-  },
+const ToggleableExample = () => {
+  const [hasError, setHasError] = useState(false);
+
+  return (
+    <div className="flex flex-col gap-gds-4">
+      <FormGroup invalid={hasError}>
+        <Label htmlFor="full-name">Full name</Label>
+
+        <Input id="full-name" aria-invalid={hasError} aria-describedby="full-name-error" />
+
+        <ErrorText id="full-name-error">{hasError ? 'Enter your full name' : ''}</ErrorText>
+      </FormGroup>
+
+      <Button onClick={() => setHasError((current) => !current)} className="self-start">
+        Toggle error
+      </Button>
+    </div>
+  );
 };
 
-export const ComplexChildren: Story = {
-  args: {
-    children: (
-      <div>
-        Error message with{' '}
-        <ExternalLink className="underline text-link" href="/">
-          Link
-        </ExternalLink>
-      </div>
-    ),
+export const AlwaysMounted: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "ErrorText stays mounted the whole time here, only its children toggle between empty and the message, click the button to see there's no gap left behind when it's empty.",
+      },
+    },
   },
+  render: () => <ToggleableExample />,
 };

package/src/components/ErrorText/ErrorText.tsx

@@ -1,18 +1,20 @@
-import type { ExtendProps } from '../../types/utils';
-import { cn } from '../../utils';
+import type { ComponentProps } from 'react';
 
-export type ErrorTextProps = ExtendProps<'p'>;
+import { cn } from '../../utils/components';
+import { Paragraph } from '../Paragraph/Paragraph';
 
-export const ErrorText = ({ className, children, ...props }: ErrorTextProps) => {
-  const Component = typeof children === 'string' ? 'p' : 'div';
+export type ErrorTextProps = ComponentProps<typeof Paragraph>;
 
+export const ErrorText = ({ className, children, ...props }: ErrorTextProps) => {
   return (
-    <Component
+    <Paragraph
       role="alert"
-      className={cn('mb-3 text-base text-error font-bold', className)}
+      aria-live="assertive"
+      aria-atomic="true"
+      className={cn('cn-error-text', className)}
       {...props}
     >
       {children}
-    </Component>
+    </Paragraph>
   );
 };

package/src/components/ExternalLink/ExternalLink.css

@@ -0,0 +1,12 @@
+@layer components {
+  .cn-external-link-icon-wrapper {
+    @apply whitespace-nowrap;
+  }
+
+  .cn-external-link-icon {
+    @apply inline ml-0.5;
+    width: 1em;
+    height: 1em;
+    vertical-align: -0.15em;
+  }
+}

package/src/components/ExternalLink/ExternalLink.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ExternalLink } from './ExternalLink';
+
+const meta: Meta<typeof ExternalLink> = {
+  title: 'Components/ExternalLink',
+  component: ExternalLink,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use ExternalLink for navigation that should open in a new tab. Generally avoid opening links in a new tab or window, however, if needed, aim to include the words `opens in new tab` in the link. This is the default variant of this component.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['default', 'icon', 'text'],
+    },
+    href: { control: 'text' },
+    children: { control: 'text' },
+  },
+  args: {
+    href: '#',
+    children: 'Story link',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ExternalLink>;
+
+export const Default: Story = {};
+
+export const WithIcon: Story = {
+  args: { variant: 'icon' },
+};
+
+export const WithNothing: Story = {
+  args: { variant: 'plain' },
+};

package/src/components/ExternalLink/ExternalLink.tsx

@@ -0,0 +1,43 @@
+import type { ComponentProps } from 'react';
+
+import { LuExternalLink } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Link } from '../Link/Link';
+
+export type ExternalLinkVariants = 'plain' | 'icon' | 'text';
+
+export type ExternalLinkProps = Omit<ComponentProps<typeof Link>, 'target' | 'rel' | 'variant'> & {
+  variant?: ExternalLinkVariants;
+};
+
+export const ExternalLink = ({
+  children,
+  variant = 'text',
+  className,
+  ...props
+}: ExternalLinkProps) => {
+  const content = {
+    plain: null,
+    icon: (
+      <span className="cn-external-link-icon-wrapper">
+        <span className="sr-only">(opens in new tab)</span>
+        &nbsp;
+        <LuExternalLink aria-hidden className="cn-external-link-icon" />
+      </span>
+    ),
+    text: <span> (opens in new tab)</span>,
+  } as const;
+
+  return (
+    <Link
+      {...props}
+      className={cn('cn-external-link', className)}
+      rel="noopener noreferrer"
+      target="_blank"
+    >
+      {children}
+      {content[variant]}
+    </Link>
+  );
+};

package/src/components/Fieldset/Fieldset.css

@@ -0,0 +1,103 @@
+@layer components {
+  /* MARK: Fieldset
+     Reset browser fieldset defaults. Browsers apply borders,
+     padding, and an unusual min-width that breaks flex layouts. */
+  .cn-field-set {
+    @apply min-w-0 m-0 p-0 border-0 flex flex-col gap-gds-2;
+  }
+
+  /* MARK: Legend
+     Plain body text by default, matching GDS's own unmodified
+     govuk-fieldset__legend (and govuk-label): no bold, same size as a
+     label (govuk-fieldset__legend and govuk-label both use govuk-font(19)
+     in real GDS, this project's text-lg), not automatically a heading. For
+     a heading-like look, nest a real Heading component inside FieldLegend
+     instead, mirroring GDS's own documented pattern of nesting an <h1>
+     inside <legend> on question-per-page forms, rather than baking
+     heading-mimicking size variants into the legend itself. */
+  /* margin-bottom (not the fieldset's own gap-gds-2): a <legend> is exempt
+     from its fieldset's flex gap. Per spec, a flex/grid fieldset lays out
+     its OTHER children inside an anonymous wrapper box, legend sits
+     outside it as its own block box, so gap, which only bridges children
+     within the same flex/grid formatting context, never reaches the
+     space between legend and whatever follows it, unlike FormGroup's
+     Label, an ordinary element with no such carve-out, which does get its
+     gap-gds-1 for free. Matches gap-gds-2 so a legend reads the same as
+     any other item-to-item gap in the set. */
+  .cn-field-legend {
+    @apply block box-border max-w-full p-0 text-lg text-body whitespace-normal;
+    margin-bottom: var(--spacing-gds-2);
+  }
+
+  /* GDS tightens the gap specifically when a group-level hint sits directly
+     under a plain legend (margin-top: govuk-spacing(-1) on the hint). This
+     stacks with cn-field-legend's own margin-bottom above (flex item
+     margins never collapse), landing on a net gds-1 (5px) rather than the
+     usual gds-2 (10px) between legend and controls. */
+  .cn-field-legend + .cn-hint-text {
+    margin-top: calc(var(--spacing-gds-1) * -1);
+  }
+
+  /* MARK: Divider
+     Appears between groups of controls, typically contains "or".
+     Width matches GDS (40px). Sits naturally in the item flex-col gap. */
+  .cn-field-divider {
+    @apply w-10 text-center text-base font-normal;
+  }
+
+  /* MARK: Item
+     Mirrors GDS's govuk-radios__item/govuk-checkboxes__item exactly: flex
+     with wrap, not grid. Control and label sit side by side on the first
+     line; the hint (if any) is forced onto its own wrapped line by w-full,
+     a flex item at 100% width can't share a line with anything else. Unlike
+     grid, flex has no shared column to auto-align the hint into under the
+     label, so its start padding has to repeat the control's width plus the
+     item's own gap-x by hand, same as GDS hardcodes touch-target + label
+     padding rather than measuring anything. margin-top is negative for the
+     same reason GDS's own hint margin-top is: it sits closer to the label
+     above it than a hint normally would on its own.
+
+     No align-items override here, same as GDS's own item wrapper: the
+     control (Radio/Checkbox) has an explicit, non-auto height, so the
+     default stretch alignment has no size to stretch it into and falls
+     back to flex-start, top-aligning it for free. The label gets its own
+     align-self: center instead (see below), matching GDS's own
+     govuk-radios__label/govuk-checkboxes__label. Centering only the label,
+     not the row, is what keeps both cases correct at once: a short label
+     centers against the control's full height same as before, and a
+     wrapping label, being the row's own tallest item once it wraps,
+     already fills the full row height, so centering it is a no-op and it
+     stays flush with the control's top instead of floating down between
+     the lines the way row-level centering would. */
+  .cn-field-item {
+    @apply flex flex-wrap gap-x-gds-2;
+  }
+
+  /* min-w-0 flex-1: without this, a long label wraps as a whole flex item
+     instead of wrapping its own text, a flex item's default min-width is
+     auto, not 0, so it won't shrink below its label text's full unwrapped
+     width, and once that doesn't fit next to the control on the row,
+     flex-wrap moves the entire label below the control rather than
+     letting the label's own text wrap while staying beside it. flex-1
+     (not just min-w-0) is what makes the label actually claim the row's
+     remaining width to wrap within, rather than shrinking to its own
+     content and only wrapping once genuinely out of room.
+
+     self-center: see the item comment above. */
+  .cn-field-item > .cn-label {
+    @apply min-w-0 flex-1 self-center;
+  }
+
+  .cn-field-item > .cn-hint-text {
+    @apply w-full;
+    margin-top: calc(var(--spacing-gds-1) * -1);
+    padding-inline-start: calc(2.5rem + var(--spacing-gds-2));
+    padding-inline-end: var(--spacing-gds-3);
+  }
+
+  /* Small Radio/Checkbox (cn-radio-size-sm/cn-checkbox-size-sm) are 1.5rem,
+     not the base 2.5rem, so the hint's offset needs to match. */
+  .cn-field-item:has(.cn-radio-size-sm, .cn-checkbox-size-sm) > .cn-hint-text {
+    padding-inline-start: calc(1.5rem + var(--spacing-gds-2));
+  }
+}