@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Layout/403/403.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Forbidden } from './403';
+
+const meta: Meta<typeof Forbidden> = {
+  title: 'Components/Layout/403',
+  component: Forbidden,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use Forbidden for displaying text when a user is authenticated but does not have permission to view a page (403).',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Forbidden>;
+
+export const Default: Story = {};

package/src/components/Layout/403/403.tsx

@@ -0,0 +1,21 @@
+import { SUPPORT_URL } from '../../../utils';
+import { Heading } from '../../Heading/Heading';
+import { Link } from '../../Link/Link';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { HeadingGroup } from '../HeadingGroup/HeadingGroup';
+import { MainWrapper } from '../MainWrapper/MainWrapper';
+
+export const Forbidden = () => {
+  return (
+    <MainWrapper>
+      <HeadingGroup>
+        <Heading level="h1">You do not have permission to view this page</Heading>
+
+        <Paragraph>
+          If the web address is correct or you selected a link or button, you can{' '}
+          <Link href={SUPPORT_URL}>contact us</Link> to receive support.
+        </Paragraph>
+      </HeadingGroup>
+    </MainWrapper>
+  );
+};

package/src/components/Layout/404/404.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { NotFound } from './404';
+
+const meta: Meta<typeof NotFound> = {
+  title: 'Components/Layout/404',
+  component: NotFound,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use NotFound for a not-found Next.JS page, or other places representing a 404 page.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof NotFound>;
+
+export const Default: Story = {};

package/src/components/Layout/404/404.tsx

@@ -0,0 +1,28 @@
+import { SUPPORT_URL } from '../../../utils';
+import { Heading } from '../../Heading/Heading';
+import { Link } from '../../Link/Link';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { HeadingGroup } from '../HeadingGroup/HeadingGroup';
+import { MainWrapper } from '../MainWrapper/MainWrapper';
+import { ParagraphGroup } from '../ParagraphGroup/ParagraphGroup';
+
+export const NotFound = () => {
+  return (
+    <MainWrapper>
+      <HeadingGroup>
+        <Heading level="h1">Page not found</Heading>
+
+        <ParagraphGroup>
+          <Paragraph>If you typed the web address, check it is correct.</Paragraph>
+
+          <Paragraph>If you pasted the web address, check you copied the entire address.</Paragraph>
+
+          <Paragraph>
+            If the web address is correct or you selected a link or button, you can{' '}
+            <Link href={SUPPORT_URL}>contact us</Link> to receive support.
+          </Paragraph>
+        </ParagraphGroup>
+      </HeadingGroup>
+    </MainWrapper>
+  );
+};

package/src/components/Layout/500/500.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { InternalServerError } from './500';
+import { ApiError } from '../../../errors/ApiError';
+
+const meta: Meta<typeof InternalServerError> = {
+  title: 'Components/Layout/500',
+  component: InternalServerError,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use InternalServerError for displaying text when a 500 error occurred. Matches the props Next.js passes automatically to an app/error.tsx boundary, `error` and `reset`, so it can be rendered directly from one. When `reset` is passed a "Try again" button appears; when `error` carries a `digest` (see ApiError) it\'s shown alongside a button to copy the full error details for the app administrator. The raw error message is never shown on the page itself, only via the copy button, to avoid exposing exception internals on a public-facing page.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof InternalServerError>;
+
+export const Default: Story = {};
+
+export const WithReset: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Only `reset` is passed, e.g. no digest was available. Shows a "Try again" button.',
+      },
+    },
+  },
+  args: {
+    reset: () => {
+      console.log('reset called');
+    },
+  },
+};
+
+export const WithApiError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'As rendered from app/error.tsx: `error` and `reset` are both passed by Next.js. ApiError always carries a digest, shown as a reference for the app administrator alongside a button to copy the full details (message, details, digest, stack).',
+      },
+    },
+  },
+  args: {
+    error: ApiError.internalServerError('The upstream sampling points service timed out'),
+    reset: () => {
+      console.log('reset called');
+    },
+  },
+};

package/src/components/Layout/500/500.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import { formatErrorForClipboard, getErrorDisplayInfo } from '../../../errors/errorDisplay';
+import { SUPPORT_URL } from '../../../utils';
+import { Button } from '../../Button/Button';
+import { CopyButton } from '../../CopyButton/CopyButton';
+import { Heading } from '../../Heading/Heading';
+import { HintText } from '../../HintText/HintText';
+import { Link } from '../../Link/Link';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { ButtonGroup } from '../ButtonGroup/ButtonGroup';
+import { HeadingGroup } from '../HeadingGroup/HeadingGroup';
+import { MainWrapper } from '../MainWrapper/MainWrapper';
+import { ParagraphGroup } from '../ParagraphGroup/ParagraphGroup';
+import { Stack } from '../Stack/Stack';
+
+export type InternalServerErrorProps = {
+  /** Passed automatically by Next.js when this is used as (or rendered
+   * from) an app/error.tsx boundary. When set, a "Try again" button calls
+   * it and, if the error carries a digest, it's shown alongside a button to
+   * copy the full error details for the app administrator. */
+  error?: Error & { digest?: string };
+  reset?: () => void;
+};
+
+export const InternalServerError = ({ error, reset }: InternalServerErrorProps) => {
+  const info = error !== undefined ? getErrorDisplayInfo(error) : null;
+
+  return (
+    <MainWrapper>
+      <Stack>
+        <HeadingGroup>
+          <Heading level="h2">Sorry, there is a problem with the service</Heading>
+
+          <ParagraphGroup>
+            <Paragraph>Try again later.</Paragraph>
+
+            <Paragraph>
+              If the problem persists, you can <Link href={SUPPORT_URL}>contact us</Link> to receive
+              support.
+            </Paragraph>
+          </ParagraphGroup>
+        </HeadingGroup>
+
+        {reset || info ? (
+          <div className="flex flex-col gap-gds-1">
+            <ButtonGroup>
+              {reset ? <Button onClick={reset}>Try again</Button> : null}
+
+              {info ? (
+                <CopyButton appearance="secondary" content={formatErrorForClipboard(info)} />
+              ) : null}
+            </ButtonGroup>
+
+            <HintText className="text-sm">
+              Copy to share error details with the app administrator.
+            </HintText>
+          </div>
+        ) : null}
+      </Stack>
+    </MainWrapper>
+  );
+};

package/src/components/Layout/ButtonGroup/ButtonGroup.css

@@ -0,0 +1,52 @@
+@layer components {
+  /* MARK: ButtonGroup
+     GDS action group: flex-wrap with center alignment so all button types
+     (text, icon, link) sit on the same axis. Buttons handle their own mobile
+     full-width behaviour (w-full sm:w-auto), so the group itself stays flex. */
+
+  .cn-button-group {
+    @apply flex flex-wrap items-center gap-gds-2;
+  }
+
+  .cn-button-group[data-orientation='vertical'] {
+    @apply flex-col items-start;
+  }
+
+  /* MARK: Compressed
+     Removes gap and shares the panel border between adjacent buttons by
+     collapsing one border-width of margin. Intended for icon button toolbars
+     using appearance="panel". Focused buttons raise above siblings via z-index
+     so the inset focus ring is never clipped by a neighbour. */
+  .cn-button-group[data-compressed] {
+    gap: 0;
+
+    & > * {
+      @apply relative;
+    }
+
+    & > * + * {
+      margin-left: calc(var(--border-width-form) * -1);
+    }
+
+    &[data-orientation='vertical'] > * + * {
+      margin-left: 0;
+      margin-top: calc(var(--border-width-form) * -1);
+    }
+
+    & > *:focus-within {
+      z-index: 1;
+    }
+  }
+
+  /* MARK: Text */
+
+  .cn-button-group-text {
+    @apply flex items-center text-base;
+  }
+
+  /* MARK: Separator */
+
+  .cn-button-group-separator {
+    @apply self-stretch;
+  }
+}

package/src/components/Layout/ButtonGroup/ButtonGroup.stories.tsx

@@ -0,0 +1,156 @@
+import { LuMaximize2, LuMinus, LuPlus } from 'react-icons/lu';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from './ButtonGroup';
+import { Button } from '../../Button/Button';
+import { LinkButton } from '../../LinkButton/LinkButton';
+
+const meta: Meta<typeof ButtonGroup> = {
+  title: 'Components/Layout/ButtonGroup',
+  component: ButtonGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Groups related action buttons with consistent GDS-aligned spacing. Use for form submission areas where a primary action is accompanied by a secondary button or cancel link.',
+      },
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: { type: 'radio' },
+      options: ['horizontal', 'vertical'],
+    },
+  },
+  args: {
+    orientation: 'horizontal',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ButtonGroup>;
+
+export const PrimaryWithCancel: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button appearance="primary">Save and continue</Button>
+
+      <LinkButton href="/">Cancel</LinkButton>
+    </ButtonGroup>
+  ),
+};
+
+export const PrimaryAndSecondary: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button appearance="primary">Save and continue</Button>
+
+      <Button appearance="secondary">Save as draft</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const WithText: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button appearance="primary">Accept all</Button>
+
+      <ButtonGroupText>or</ButtonGroupText>
+
+      <LinkButton href="/">Manage preferences</LinkButton>
+    </ButtonGroup>
+  ),
+};
+
+export const Vertical: Story = {
+  args: {
+    orientation: 'vertical',
+  },
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button appearance="primary">Save and continue</Button>
+
+      <Button appearance="secondary">Save as draft</Button>
+
+      <LinkButton href="/">Cancel</LinkButton>
+    </ButtonGroup>
+  ),
+};
+
+export const WithSeparator: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button appearance="primary">Save and continue</Button>
+
+      <Button appearance="secondary">Save as draft</Button>
+
+      <ButtonGroupSeparator />
+
+      <Button appearance="destructive">Delete</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const DestructiveGroup: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button appearance="destructive">Delete account</Button>
+
+      <LinkButton href="/">Cancel</LinkButton>
+    </ButtonGroup>
+  ),
+};
+
+export const CompressedHorizontal: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Compressed removes the gap and shares borders between adjacent panel buttons. Use for map toolbars and icon button clusters.',
+      },
+    },
+  },
+  render: () => (
+    <ButtonGroup compressed>
+      <Button variant="icon" appearance="panel" aria-label="Zoom in">
+        <LuPlus aria-hidden />
+      </Button>
+
+      <Button variant="icon" appearance="panel" aria-label="Zoom out">
+        <LuMinus aria-hidden />
+      </Button>
+
+      <Button variant="icon" appearance="panel" aria-label="Full screen">
+        <LuMaximize2 aria-hidden />
+      </Button>
+    </ButtonGroup>
+  ),
+};
+
+export const CompressedVertical: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Compressed vertical, the default layout for map control toolbars.',
+      },
+    },
+  },
+  render: () => (
+    <ButtonGroup orientation="vertical" compressed role="toolbar" aria-label="Map controls">
+      <Button variant="icon" appearance="panel" aria-label="Full screen">
+        <LuMaximize2 aria-hidden />
+      </Button>
+
+      <Button variant="icon" appearance="panel" aria-label="Zoom in">
+        <LuPlus aria-hidden />
+      </Button>
+
+      <Button variant="icon" appearance="panel" aria-label="Zoom out">
+        <LuMinus aria-hidden />
+      </Button>
+    </ButtonGroup>
+  ),
+};

package/src/components/Layout/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,50 @@
+import type { ComponentProps } from 'react';
+
+import { Slot } from 'radix-ui';
+
+import { cn } from '../../../utils/components';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { Separator } from '../../Separator/Separator';
+
+export type ButtonGroupOrientation = 'horizontal' | 'vertical';
+
+export type ButtonGroupProps = ComponentProps<'div'> & {
+  orientation?: ButtonGroupOrientation;
+  compressed?: boolean;
+};
+
+export const ButtonGroup = ({
+  className,
+  orientation = 'horizontal',
+  compressed = false,
+  ...props
+}: ButtonGroupProps) => (
+  <div
+    role="group"
+    data-slot="button-group"
+    data-orientation={orientation}
+    data-compressed={compressed || undefined}
+    className={cn('cn-button-group', className)}
+    {...props}
+  />
+);
+
+export type ButtonGroupTextProps = ComponentProps<typeof Paragraph> & {
+  asChild?: boolean;
+};
+
+export const ButtonGroupText = ({ className, asChild = false, ...props }: ButtonGroupTextProps) => {
+  const Comp = asChild ? Slot.Root : Paragraph;
+
+  return <Comp className={cn('cn-button-group-text', className)} {...props} />;
+};
+
+export type ButtonGroupSeparatorProps = ComponentProps<typeof Separator>;
+
+export const ButtonGroupSeparator = ({ className, ...props }: ButtonGroupSeparatorProps) => (
+  <Separator
+    data-slot="button-group-separator"
+    className={cn('cn-button-group-separator', className)}
+    {...props}
+  />
+);

package/src/components/Layout/HeadingGroup/HeadingGroup.css

@@ -0,0 +1,21 @@
+@layer components {
+  /* Space from the heading to its own immediately-following subtitle/lede
+     only, one notch tighter than the scale used to look, since Stack now
+     owns the (larger) gap between this group and whatever else follows it. */
+  .cn-heading-group {
+    & h1 {
+      @apply mb-gds-3 @sm:mb-gds-4;
+    }
+    & h2 {
+      @apply mb-gds-2 @sm:mb-gds-3;
+    }
+    & h3 {
+      @apply mb-gds-1 @sm:mb-gds-2;
+    }
+    & h4,
+    & h5,
+    & h6 {
+      @apply mb-gds-1;
+    }
+  }
+}

package/src/components/Layout/HeadingGroup/HeadingGroup.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { HeadingGroup } from './HeadingGroup';
+import { Heading } from '../../Heading/Heading';
+import { Paragraph } from '../../Paragraph/Paragraph';
+
+const meta: Meta<typeof HeadingGroup> = {
+  title: 'Components/Layout/HeadingGroup',
+  component: HeadingGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use a HeadingGroup to group a heading followed by other content with responsive spacing.',
+      },
+    },
+  },
+  argTypes: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof HeadingGroup>;
+
+export const H1: Story = {
+  render: () => (
+    <HeadingGroup>
+      <Heading level="h1">Water Quality</Heading>
+
+      <Paragraph>This app is ....</Paragraph>
+    </HeadingGroup>
+  ),
+};
+
+export const H2: Story = {
+  render: () => (
+    <HeadingGroup>
+      <Heading level="h2">Water Quality</Heading>
+
+      <Paragraph>This app is ....</Paragraph>
+    </HeadingGroup>
+  ),
+};
+
+export const H3: Story = {
+  render: () => (
+    <HeadingGroup>
+      <Heading level="h3">Water Quality</Heading>
+
+      <Paragraph>This app is ....</Paragraph>
+    </HeadingGroup>
+  ),
+};
+
+export const H4: Story = {
+  render: () => (
+    <HeadingGroup>
+      <Heading level="h4">Water Quality</Heading>
+
+      <Paragraph>This app is ....</Paragraph>
+    </HeadingGroup>
+  ),
+};
+
+export const H5: Story = {
+  render: () => (
+    <HeadingGroup>
+      <Heading level="h5">Water Quality</Heading>
+
+      <Paragraph>This app is ....</Paragraph>
+    </HeadingGroup>
+  ),
+};
+
+export const H6: Story = {
+  render: () => (
+    <HeadingGroup>
+      <Heading level="h6">Water Quality</Heading>
+
+      <Paragraph>This app is ....</Paragraph>
+    </HeadingGroup>
+  ),
+};

package/src/components/Layout/HeadingGroup/HeadingGroup.tsx

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../../utils/components';
+
+export type HeadingGroupProps = ComponentProps<'div'>;
+
+export const HeadingGroup = ({ className, ...props }: HeadingGroupProps) => {
+  return <div className={cn('cn-heading-group', className)} {...props} />;
+};

package/src/components/Layout/MainWrapper/MainWrapper.css

@@ -0,0 +1,12 @@
+@layer components {
+  /* MARK: MainWrapper
+     GDS "main wrapper" object: vertical-only rhythm (20px mobile / 40px
+     desktop, matching govuk-main-wrapper) around the page's <main> content.
+     Deliberately separate from WidthContainer, which is horizontal-only,
+     mirroring GDS's own split, content that sits above <main> but still
+     inside the width container (breadcrumbs, phase banners) needs the
+     horizontal centering without this padding. */
+  .cn-main-wrapper {
+    @apply py-gds-4 sm:py-gds-7;
+  }
+}

package/src/components/Layout/MainWrapper/MainWrapper.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { MainWrapper } from './MainWrapper';
+import { Heading } from '../../Heading/Heading';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { HeadingGroup } from '../HeadingGroup/HeadingGroup';
+
+const meta: Meta<typeof MainWrapper> = {
+  title: 'Components/Layout/MainWrapper',
+  component: MainWrapper,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Renders the page's <main> landmark with responsive top/bottom padding, and centers its content with WidthContainer internally, so you don't need to nest the two yourself. Use this for the actual page content area (between things like a Header and Footer), not for full-bleed sections like Hero, those stay directly on WidthContainer since they intentionally have their own vertical rhythm.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof MainWrapper>;
+
+export const Default: Story = {
+  render: () => (
+    <MainWrapper>
+      <HeadingGroup>
+        <Heading level="h1">Water quality</Heading>
+
+        <Paragraph>Explore water quality sample data collected across England.</Paragraph>
+      </HeadingGroup>
+    </MainWrapper>
+  ),
+};

package/src/components/Layout/MainWrapper/MainWrapper.tsx

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../../utils/components';
+import { WidthContainer } from '../WidthContainer/WidthContainer';
+
+export type MainWrapperProps = ComponentProps<'main'>;
+
+export const MainWrapper = ({ className, children, ...props }: MainWrapperProps) => {
+  return (
+    <main className={cn('cn-main-wrapper', className)} {...props}>
+      <WidthContainer>{children}</WidthContainer>
+    </main>
+  );
+};