@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Alert/Alert.stories.tsx

@@ -0,0 +1,291 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import {
+  Alert,
+  AlertAction,
+  AlertBody,
+  AlertDescription,
+  AlertList,
+  AlertListItem,
+  AlertTitle,
+} from './Alert';
+import { Link } from '../Link/Link';
+
+const meta: Meta<typeof Alert> = {
+  title: 'Components/Alert',
+  component: Alert,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Unified alert component covering three GDS patterns. `banner` is a notification banner (coloured header + white content), `outlined` is an error summary (coloured border, white background), and `filled` is a confirmation panel (fully coloured, centred). Use `appearance` to set the colour and `variant` to set the layout pattern.',
+      },
+    },
+  },
+  argTypes: {
+    appearance: {
+      control: { type: 'radio' },
+      options: ['info', 'success', 'warning', 'error'],
+    },
+    variant: {
+      control: { type: 'radio' },
+      options: ['banner', 'outlined', 'filled'],
+    },
+  },
+  args: {
+    appearance: 'info',
+    variant: 'banner',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Alert>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Alert {...args}>
+      <AlertTitle>Important</AlertTitle>
+
+      <AlertBody>
+        <AlertDescription>
+          <p>You have 7 days left to send your application.</p>
+
+          <p>
+            <Link href="#">View your application</Link>
+          </p>
+        </AlertDescription>
+      </AlertBody>
+    </Alert>
+  ),
+};
+
+export const Appearances: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'All four appearances using the `banner` variant (coloured header + white content).',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-gds-6">
+      <Alert appearance="info" variant="banner">
+        <AlertTitle>Important</AlertTitle>
+
+        <AlertBody>
+          <AlertDescription>
+            <p>You have 7 days left to send your application.</p>
+          </AlertDescription>
+        </AlertBody>
+      </Alert>
+
+      <Alert appearance="success" variant="banner">
+        <AlertTitle>Success</AlertTitle>
+
+        <AlertBody>
+          <AlertDescription>
+            <p>Your application has been submitted.</p>
+          </AlertDescription>
+        </AlertBody>
+      </Alert>
+
+      <Alert appearance="warning" variant="banner">
+        <AlertTitle>Warning</AlertTitle>
+
+        <AlertBody>
+          <AlertDescription>
+            <p>You must complete your profile before the deadline.</p>
+          </AlertDescription>
+        </AlertBody>
+      </Alert>
+
+      <Alert appearance="error" variant="banner">
+        <AlertTitle>There is a problem</AlertTitle>
+
+        <AlertBody>
+          <AlertDescription>
+            <p>
+              <Link href="#" appearance="error">
+                Enter your date of birth
+              </Link>
+            </p>
+          </AlertDescription>
+        </AlertBody>
+      </Alert>
+    </div>
+  ),
+};
+
+export const ErrorSummary: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `variant="outlined"` with `appearance="error"` to reproduce the GDS error summary. Place it at the top of a form, above the `<h1>`. `AlertList` links should scroll to and focus the relevant field.',
+      },
+    },
+  },
+  render: () => (
+    <Alert appearance="error" variant="outlined">
+      <AlertTitle>There is a problem</AlertTitle>
+
+      <AlertList>
+        <AlertListItem>
+          <Link href="#full-name" appearance="error">
+            Enter your full name
+          </Link>
+        </AlertListItem>
+
+        <AlertListItem>
+          <Link href="#dob" appearance="error">
+            Enter your date of birth
+          </Link>
+        </AlertListItem>
+
+        <AlertListItem>
+          <Link href="#email" appearance="error">
+            Enter an email address in the correct format, like name@example.com
+          </Link>
+        </AlertListItem>
+      </AlertList>
+    </Alert>
+  ),
+};
+
+export const OutlinedVariants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All four appearances using the `outlined` variant (coloured border, white background).',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-gds-6">
+      <Alert appearance="info" variant="outlined">
+        <AlertTitle>Before you start</AlertTitle>
+
+        <AlertDescription>
+          <p>You will need your National Insurance number and passport.</p>
+        </AlertDescription>
+      </Alert>
+
+      <Alert appearance="success" variant="outlined">
+        <AlertTitle>Application saved</AlertTitle>
+
+        <AlertDescription>
+          <p>Your progress has been saved. You can return to complete your application later.</p>
+        </AlertDescription>
+      </Alert>
+
+      <Alert appearance="warning" variant="outlined">
+        <AlertTitle>Service disruption</AlertTitle>
+
+        <AlertDescription>
+          <p>Some features may be unavailable between 11pm and 1am on Sunday 30 June.</p>
+        </AlertDescription>
+      </Alert>
+
+      <Alert appearance="error" variant="outlined">
+        <AlertTitle>There is a problem</AlertTitle>
+
+        <AlertList>
+          <AlertListItem>
+            <Link href="#full-name" appearance="error">
+              Enter your full name
+            </Link>
+          </AlertListItem>
+
+          <AlertListItem>
+            <Link href="#email" appearance="error">
+              Enter an email address in the correct format
+            </Link>
+          </AlertListItem>
+        </AlertList>
+      </Alert>
+    </div>
+  ),
+};
+
+export const ConfirmationPanel: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `variant="filled"` for post-transaction confirmation pages (the GDS panel pattern). The title is very large, and the description is used for a reference number or short confirmation line.',
+      },
+    },
+  },
+  render: () => (
+    <Alert appearance="success" variant="filled">
+      <AlertTitle>Application complete</AlertTitle>
+
+      <AlertDescription>Your reference number is HDJ2123F</AlertDescription>
+    </Alert>
+  ),
+};
+
+export const FilledVariants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'All four appearances using the `filled` variant.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-gds-6">
+      <Alert appearance="info" variant="filled">
+        <AlertTitle>Service unavailable</AlertTitle>
+
+        <AlertDescription>Try again later</AlertDescription>
+      </Alert>
+
+      <Alert appearance="success" variant="filled">
+        <AlertTitle>Application complete</AlertTitle>
+
+        <AlertDescription>Your reference number is HDJ2123F</AlertDescription>
+      </Alert>
+
+      <Alert appearance="warning" variant="filled">
+        <AlertTitle>Check your answers</AlertTitle>
+
+        <AlertDescription>Some information may need to be updated</AlertDescription>
+      </Alert>
+
+      <Alert appearance="error" variant="filled">
+        <AlertTitle>There is a problem</AlertTitle>
+
+        <AlertDescription>Contact support if the issue persists</AlertDescription>
+      </Alert>
+    </div>
+  ),
+};
+
+export const WithAction: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `AlertAction` for a call-to-action section below the description.',
+      },
+    },
+  },
+  render: () => (
+    <Alert appearance="info" variant="banner">
+      <AlertTitle>Important</AlertTitle>
+
+      <AlertBody>
+        <AlertDescription>
+          <p>Your session will expire in 10 minutes.</p>
+        </AlertDescription>
+
+        <AlertAction>
+          <Link href="#">Extend your session</Link>
+        </AlertAction>
+      </AlertBody>
+    </Alert>
+  ),
+};

package/src/components/Alert/Alert.tsx

@@ -0,0 +1,76 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+const ALERT_APPEARANCES = {
+  info: 'cn-alert-appearance-info',
+  success: 'cn-alert-appearance-success',
+  warning: 'cn-alert-appearance-warning',
+  error: 'cn-alert-appearance-error',
+} as const;
+
+const ALERT_VARIANTS = {
+  banner: 'cn-alert-variant-banner',
+  outlined: 'cn-alert-variant-outlined',
+  filled: 'cn-alert-variant-filled',
+} as const;
+
+export type AlertAppearance = keyof typeof ALERT_APPEARANCES;
+export type AlertVariant = keyof typeof ALERT_VARIANTS;
+
+export type AlertProps = ComponentProps<'div'> & {
+  appearance?: AlertAppearance;
+  variant?: AlertVariant;
+};
+
+export const Alert = ({
+  className,
+  appearance = 'info',
+  variant = 'banner',
+  ...props
+}: AlertProps) => (
+  <div
+    data-slot="alert"
+    data-appearance={appearance}
+    data-variant={variant}
+    role="alert"
+    className={cn('cn-alert', ALERT_APPEARANCES[appearance], ALERT_VARIANTS[variant], className)}
+    {...props}
+  />
+);
+
+export type AlertTitleProps = ComponentProps<'div'>;
+
+export const AlertTitle = ({ className, ...props }: AlertTitleProps) => (
+  <div data-slot="alert-title" className={cn('cn-alert-title', className)} {...props} />
+);
+
+export type AlertDescriptionProps = ComponentProps<'div'>;
+
+export const AlertDescription = ({ className, ...props }: AlertDescriptionProps) => (
+  <div data-slot="alert-description" className={cn('cn-alert-description', className)} {...props} />
+);
+
+export type AlertListProps = ComponentProps<'ul'>;
+
+export const AlertList = ({ className, ...props }: AlertListProps) => (
+  <ul data-slot="alert-list" className={cn('cn-alert-list', className)} {...props} />
+);
+
+export type AlertBodyProps = ComponentProps<'div'>;
+
+export const AlertBody = ({ className, ...props }: AlertBodyProps) => (
+  <div data-slot="alert-body" className={cn('cn-alert-body', className)} {...props} />
+);
+
+export type AlertListItemProps = ComponentProps<'li'>;
+
+export const AlertListItem = ({ className, ...props }: AlertListItemProps) => (
+  <li data-slot="alert-list-item" className={cn('cn-alert-list-item', className)} {...props} />
+);
+
+export type AlertActionProps = ComponentProps<'div'>;
+
+export const AlertAction = ({ className, ...props }: AlertActionProps) => (
+  <div data-slot="alert-action" className={cn('cn-alert-action', className)} {...props} />
+);

package/src/components/BackLink/BackLink.css

@@ -0,0 +1,12 @@
+@layer components {
+  /* MARK: BackLink
+     Matches GDS spacing (govuk-spacing(3) above and below). Reuses cn-link
+     for underline/hover/focus styling, this just adds the icon and layout. */
+  .cn-back-link {
+    @apply inline-flex items-center gap-1 my-gds-3;
+  }
+
+  .cn-back-link-icon {
+    @apply size-4 shrink-0;
+  }
+}

package/src/components/BackLink/BackLink.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { BackLink } from './BackLink';
+
+const meta: Meta<typeof BackLink> = {
+  title: 'Components/BackLink',
+  component: BackLink,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Matches the GDS back link: a chevron and "Back" text, styled like a normal link.
+
+- Pass \`href\` when you know the destination (preferred, works without JavaScript, supports right-click/open-in-new-tab). Behaves like a normal link.
+- Omit \`href\` and it falls back to \`window.history.back()\`, a plain browser API rather than anything framework-specific, so it works the same in Next.js, a plain SPA, or anywhere else.
+- Pass \`onClick\` to fully override the behaviour (e.g. a Next.js app that prefers \`router.back()\` for its loading-state integration).
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof BackLink>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'No `href` or `onClick`, falls back to `window.history.back()`.',
+      },
+    },
+  },
+  render: () => <BackLink />,
+};
+
+export const WithHref: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A real `href` is the preferred approach when the destination is known upfront.',
+      },
+    },
+  },
+  render: () => <BackLink href="/previous-page" />,
+};
+
+export const CustomText: Story = {
+  render: () => <BackLink href="/applications">Back to applications</BackLink>,
+};

package/src/components/BackLink/BackLink.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import { type ComponentProps, type MouseEvent } from 'react';
+
+import { LuChevronLeft } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Link } from '../Link/Link';
+
+export type BackLinkProps = ComponentProps<typeof Link>;
+
+export const BackLink = ({ href, onClick, children, className, ...props }: BackLinkProps) => {
+  const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
+    // A real href was given, this is a genuine link, let it navigate normally.
+    if (href !== undefined) {
+      onClick?.(event);
+
+      return;
+    }
+
+    // No href to navigate to, so the href="#" fallback below isn't a real
+    // destination, don't let it jump to the top of the page.
+    event.preventDefault();
+
+    if (onClick) {
+      onClick(event);
+    } else {
+      window.history.back();
+    }
+  };
+
+  return (
+    <Link
+      href={href ?? '#'}
+      onClick={handleClick}
+      className={cn('cn-back-link', className)}
+      {...props}
+    >
+      <LuChevronLeft aria-hidden className="cn-back-link-icon" />
+
+      {children ?? 'Back'}
+    </Link>
+  );
+};

package/src/components/BackToTop/BackToTop.css

@@ -0,0 +1,23 @@
+@layer components {
+  /* MARK: Back to top
+     Fixed to the bottom-right corner. Hidden via inert + opacity when above
+     the scroll threshold, fades in once the user has scrolled down. The link
+     itself provides the scroll behaviour, so no JS scroll handler is needed. */
+  .cn-back-to-top {
+    @apply fixed bottom-gds-4 right-gds-4 z-40 whitespace-nowrap opacity-0 pointer-events-none
+      p-gds-1 panel;
+    transition: opacity 0.15s ease;
+
+    &[data-visible='true'] {
+      @apply opacity-100 pointer-events-auto;
+    }
+  }
+
+  .cn-back-to-top-link {
+    @apply flex items-center gap-1;
+
+    & svg {
+      @apply size-[1em];
+    }
+  }
+}

package/src/components/BackToTop/BackToTop.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { BackToTop } from './BackToTop';
+
+const meta: Meta<typeof BackToTop> = {
+  title: 'Components/BackToTop',
+  component: BackToTop,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A floating "Back to Top" button that appears when the user scrolls down and allows quick navigation back to the top of the page.',
+      },
+    },
+  },
+  argTypes: {},
+  args: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof BackToTop>;
+
+export const Default: Story = {
+  render: ({ ...args }) => {
+    const content = `
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean elementum sagittis velit eget cursus. In et justo sem. Donec posuere turpis nibh, id blandit tellus consectetur nec. Aliquam tincidunt elit eros, hendrerit fermentum erat rhoncus eu. Ut ultricies turpis vitae massa posuere suscipit. Aenean blandit nulla et orci ultrices tempor. Etiam eu metus diam. Sed porttitor lorem id ultrices tincidunt. Aenean vel orci purus. Cras eget faucibus nisl. Nam finibus, purus sed dignissim viverra, nibh enim blandit leo, vitae porttitor augue nunc non diam. Sed ac imperdiet lectus. In finibus mattis dapibus. 
+        `.repeat(7);
+
+    return (
+      <div className="flex justify-center relative">
+        <div id="top" aria-hidden="true" />
+
+        <p className="max-w-96">{content}</p>
+
+        <BackToTop {...args} />
+      </div>
+    );
+  },
+};

package/src/components/BackToTop/BackToTop.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { useEffect, useState, type ComponentProps } from 'react';
+
+import { LuArrowUp } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Link } from '../Link/Link';
+
+export type BackToTopProps = Omit<
+  ComponentProps<typeof Link>,
+  'href' | 'children' | 'target' | 'ref'
+> & {
+  topId?: string;
+  threshold?: number;
+};
+
+export const BackToTop = ({
+  className,
+  topId = 'top',
+  threshold = 300,
+  ...props
+}: BackToTopProps) => {
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const handleScroll = () => setIsVisible(window.scrollY > threshold);
+
+    handleScroll();
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, [threshold]);
+
+  return (
+    <div
+      className={cn('cn-back-to-top', className)}
+      data-visible={isVisible}
+      inert={isVisible ? undefined : true}
+    >
+      <Link href={`#${topId}`} className="cn-back-to-top-link" {...props}>
+        <LuArrowUp aria-hidden />
+        Back to top
+      </Link>
+    </div>
+  );
+};

package/src/components/Breadcrumb/Breadcrumb.css

@@ -0,0 +1,42 @@
+@layer components {
+  /* MARK: Breadcrumb
+     No margin here on purpose: components in this library don't set their
+     own external spacing, that's the consuming layout's call (e.g. a Stack
+     gap), so Breadcrumb doesn't assume what surrounds it. text-body/white
+     here (not on cn-breadcrumb-page) so the current-page
+     text AND the separator icons (react-icons defaults to
+     fill/stroke: currentColor) both follow whichever appearance is picked,
+     from one place, via inheritance rather than two separate overrides. */
+  .cn-breadcrumb {
+    @apply text-base text-body;
+
+    &[data-appearance='inverse'] {
+      @apply text-white;
+    }
+  }
+
+  .cn-breadcrumb-list {
+    @apply m-0 p-0 list-none flex flex-wrap items-center gap-1;
+  }
+
+  /* MARK: Item
+     display comes entirely from the reveal/hide utility applied per item in
+     the TSX (or the constant "inline-flex" for the always-visible first and
+     last items), never set here, so there's only ever one utility deciding
+     display for a given item and nothing to override. */
+  .cn-breadcrumb-item {
+    @apply items-center gap-1;
+  }
+
+  /* items-center on cn-breadcrumb-item centers the icon against the text's
+     full line-height box, but text reads as visually centered around its
+     cap-height, which sits a little above the geometric centre of that box,
+     so a flex-centered icon looks slightly low next to it. Nudge up 1px. */
+  .cn-breadcrumb-separator {
+    @apply size-3 shrink-0 -mt-px;
+  }
+
+  .cn-breadcrumb-ellipsis-text {
+    @apply select-none;
+  }
+}