@tpzdsp/next-toolkit 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "A reusable React component library for Next.js applications",
   "packageManager": "pnpm@11.5.3",
   "engines": {

package/src/components/ErrorModal/ErrorModal.css

@@ -17,9 +17,11 @@
   /* min-w-0 lets this column shrink below its content's natural width
      within the flex row, same reasoning as elsewhere in this project:
      without it, long unbroken content (e.g. a digest UUID) could force the
-     row wider than the modal itself instead of wrapping/scrolling. */
+     row wider than the modal itself instead of wrapping/scrolling. flex and
+     flex-col themselves come from Stack (this is applied to one via
+     ErrorModal.tsx's className), not repeated here. */
   .cn-error-modal-body {
-    @apply flex min-w-0 flex-col;
+    @apply min-w-0;
   }
 
   /* Scoped to the summary list only (not the copy button/hint below it), an

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

@@ -5,7 +5,6 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ErrorModal } from './ErrorModal';
 import { ApiError } from '../../errors/ApiError';
 import { Button } from '../Button/Button';
-import { Paragraph } from '../Paragraph/Paragraph';
 
 const meta: Meta<typeof ErrorModal> = {
   title: 'Components/ErrorModal',
@@ -41,7 +40,7 @@ export const Default: Story = {
           onOpenChange={setOpen}
           error={new Error('Failed to fetch sampling points')}
         >
-          <Paragraph>An error occurred while fetching sampling points.</Paragraph>
+          An error occurred while fetching sampling points.
         </ErrorModal>
       </>
     );
@@ -69,7 +68,7 @@ export const WithApiError: Story = {
           onOpenChange={setOpen}
           error={ApiError.internalServerError('The upstream sampling points service timed out')}
         >
-          <Paragraph>An error occurred while fetching sampling points.</Paragraph>
+          An error occurred while fetching sampling points.
         </ErrorModal>
       </>
     );
@@ -93,7 +92,7 @@ export const WithoutError: Story = {
         <Button onClick={() => setOpen(true)}>Trigger error</Button>
 
         <ErrorModal open={open} onOpenChange={setOpen}>
-          <Paragraph>Something went wrong. Try again in a few minutes.</Paragraph>
+          Something went wrong. Try again in a few minutes.
         </ErrorModal>
       </>
     );

package/src/components/ErrorModal/ErrorModal.tsx

@@ -52,68 +52,71 @@ export const ErrorModal = ({
           <LuCircleAlert aria-hidden className="size-8" />
         </div>
 
-        <div className="cn-error-modal-body">
+        <Stack gap="sm" className="cn-error-modal-body">
           <ModalHeader>
             <ModalTitle>{title}</ModalTitle>
           </ModalHeader>
 
-          <ModalDescription>
-            <Stack gap="sm">
-              {children}
-
-              {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}
-            </Stack>
-          </ModalDescription>
+          {/* 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>
-        </div>
+        </Stack>
       </ModalContent>
     </Modal>
   );

package/src/components/Footer/Copyright.tsx

@@ -7,7 +7,6 @@ export const Copyright = () => {
     <ExternalLink
       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

@@ -15,6 +15,9 @@ const meta = {
     },
   },
   tags: ['autodocs'],
+  args: {
+    accessibilityStatementHref: '/accessibility-statement',
+  },
 } satisfies Meta<typeof Footer>;
 
 export default meta;

package/src/components/Footer/Footer.tsx

@@ -4,7 +4,12 @@ import { MetaLinks } from './MetaLinks';
 import { DefraLogo } from '../../assets/images/DefraLogo';
 import { WidthContainer } from '../Layout/WidthContainer/WidthContainer';
 
-export const Footer = () => (
+export type FooterProps = {
+  /** Passed straight through to MetaLinks, see its own accessibilityStatementHref doc. */
+  accessibilityStatementHref?: string;
+};
+
+export const Footer = ({ accessibilityStatementHref }: FooterProps) => (
   <footer className="bg-wash">
     <WidthContainer className="py-gds-3">
       <div
@@ -15,7 +20,7 @@ export const Footer = () => (
         <nav className="row-start-1 col-start-1 w-full pb-gds-2 self-end">
           <h2 className="sr-only">Support Links</h2>
 
-          <MetaLinks />
+          <MetaLinks accessibilityStatementHref={accessibilityStatementHref} />
         </nav>
 
         <div className="row-start-2 col-start-1 self-end pt-gds-1">

package/src/components/Footer/MetaLinks.tsx

@@ -1,10 +1,6 @@
-import { ExternalLink } from '../ExternalLink/ExternalLink';
+import { Link } from '../Link/Link';
 
-const LINKS = [
-  {
-    label: 'Accessibility statement',
-    url: '/support/faqs/275810340/275810354',
-  },
+const STATIC_LINKS = [
   {
     label: 'Cookie Policy',
     url: '/help/cookies',
@@ -23,19 +19,29 @@ const LINKS = [
   },
 ];
 
-export const MetaLinks = () => (
-  <ul className="flex w-full flex-wrap gap-x-gds-4 gap-y-gds-2 md:gap-gds-5 md:justify-start">
-    {LINKS.map((link) => (
-      <li className="flex" key={link.label}>
-        <ExternalLink
-          className="md:text-left"
-          appearance="contrast"
-          href={link.url}
-          variant="plain"
-        >
-          {link.label}
-        </ExternalLink>
-      </li>
-    ))}
-  </ul>
-);
+export type MetaLinksProps = {
+  /** No single accessibility statement applies across every app this footer
+   * ships in, so unlike the other, shared support links above, this one has
+   * to be supplied by the consuming app rather than hardcoded here. Optional
+   * for now, apps that don't have one yet just don't get the link, rather
+   * than one pointing nowhere. */
+  accessibilityStatementHref?: string;
+};
+
+export const MetaLinks = ({ accessibilityStatementHref }: MetaLinksProps) => {
+  const links = accessibilityStatementHref
+    ? [{ label: 'Accessibility statement', url: accessibilityStatementHref }, ...STATIC_LINKS]
+    : STATIC_LINKS;
+
+  return (
+    <ul className="flex w-full flex-wrap gap-x-gds-4 gap-y-gds-2 md:gap-gds-5 md:justify-start">
+      {links.map((link) => (
+        <li className="flex" key={link.label}>
+          <Link className="md:text-left" appearance="contrast" href={link.url}>
+            {link.label}
+          </Link>
+        </li>
+      ))}
+    </ul>
+  );
+};

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

@@ -15,6 +15,9 @@ const meta = {
     },
   },
   tags: ['autodocs'],
+  args: {
+    accessibilityStatementHref: '/accessibility-statement',
+  },
 } satisfies Meta<typeof SmallFooter>;
 
 export default meta;

package/src/components/Footer/Small/SmallFooter.tsx

@@ -3,6 +3,7 @@ import { EaLogo } from '../../../assets/images/EaLogo';
 import { OglLogo } from '../../../assets/images/OglLogo';
 import { ExternalLink } from '../../ExternalLink/ExternalLink';
 import { WidthContainer } from '../../Layout/WidthContainer/WidthContainer';
+import { Link } from '../../Link/Link';
 
 const CROWN_COPYRIGHT_URL =
   'https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/';
@@ -13,11 +14,15 @@ const LICENSING_DETAILS_URL =
 export type SmallFooterProps = {
   eaLogoPrimaryFill?: string;
   eaLogoHighlightFill?: string;
+  /** Same as Footer's own accessibilityStatementHref: no universal default,
+   * omit it to hide the link entirely rather than pointing at nothing. */
+  accessibilityStatementHref?: string;
 };
 
 export const SmallFooter = ({
   eaLogoPrimaryFill = '#F3F2F1',
   eaLogoHighlightFill = '#79A12F',
+  accessibilityStatementHref,
 }: SmallFooterProps) => (
   <footer aria-label="Site footer" className="flex justify-center">
     <WidthContainer className="bg-wash py-gds-2">
@@ -32,6 +37,12 @@ export const SmallFooter = ({
         </div>
 
         <div className="flex items-center gap-gds-6 xs:gap-gds-2">
+          {accessibilityStatementHref ? (
+            <Link appearance="contrast" href={accessibilityStatementHref}>
+              Accessibility statement
+            </Link>
+          ) : null}
+
           <ExternalLink
             appearance="contrast"
             variant="plain"

package/src/components/Header/Header.tsx

@@ -17,7 +17,6 @@ import {
   Separator,
   WidthContainer,
   Popover,
-  Paragraph,
   ParagraphGroup,
 } from '@tpzdsp/next-toolkit/components';
 import { cn } from '@tpzdsp/next-toolkit/utils';
@@ -144,7 +143,7 @@ export const Header = ({ appContent, credentials }: HeaderProps) => {
 
                 <abbr
                   title="Department for Environment, Food, and Rural Affairs"
-                  className="sr-only xs:not-sr-only"
+                  className="sr-only xs:not-sr-only no-underline"
                 >
                   DEFRA
                 </abbr>
@@ -156,7 +155,9 @@ export const Header = ({ appContent, credentials }: HeaderProps) => {
                 <span className="hidden xs:inline">Data Services Platform</span>
 
                 <span className="inline xs:hidden">
-                  <abbr title="Data Services Platform">DSP</abbr>
+                  <abbr title="Data Services Platform" className="no-underline">
+                    DSP
+                  </abbr>
                 </span>
               </Link>
             </div>
@@ -165,9 +166,9 @@ export const Header = ({ appContent, credentials }: HeaderProps) => {
               <ul className="flex items-center gap-gds-4">
                 {DSP_NAV_LINKS.map((item) => (
                   <li className={cn('flex items-center nav-item', item.mainNav)} key={item.href}>
-                    <ExternalLink href={item.href} appearance="inverse" variant="plain">
+                    <Link href={item.href} appearance="inverse">
                       {item.label}
-                    </ExternalLink>
+                    </Link>
                   </li>
                 ))}
                 <li ref={triggerRef} className="flex items-center more-btn shrink-0">
@@ -195,11 +196,11 @@ export const Header = ({ appContent, credentials }: HeaderProps) => {
 
                 <PopoverContent sideOffset={0}>
                   <ParagraphGroup>
-                    <Paragraph>
+                    <div>
                       <div className="font-bold">Signed in as:</div>
 
                       <div>{credentials.user.email}</div>
-                    </Paragraph>
+                    </div>
 
                     <Link href={`${LOGOUT_URL}?redirect_uri=${redirectUri}`}>Sign-out</Link>
                   </ParagraphGroup>
@@ -273,9 +274,9 @@ export const Header = ({ appContent, credentials }: HeaderProps) => {
               <ul className="flex flex-wrap w-full gap-x-gds-2 gap-y-gds-2">
                 {DSP_NAV_LINKS.map((item) => (
                   <li className={cn('flex items-center nav-item', item.drawerNav)} key={item.href}>
-                    <ExternalLink href={item.href} appearance="inverse" variant="plain">
+                    <Link href={item.href} appearance="inverse">
                       {item.label}
-                    </ExternalLink>
+                    </Link>
                   </li>
                 ))}
               </ul>

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

@@ -80,7 +80,7 @@ export const Static: Story = {
         <LongContent />
       </MainWrapper>
 
-      <Footer />
+      <Footer accessibilityStatementHref="/accessibility-statement" />
     </PageShell>
   ),
 };
@@ -102,7 +102,7 @@ export const ScrollLocked: Story = {
         <LongContent />
       </MainWrapper>
 
-      <Footer />
+      <Footer accessibilityStatementHref="/accessibility-statement" />
     </PageShell>
   ),
 };

package/src/components/Modal/Modal.css

@@ -91,16 +91,13 @@
   }
 
   /* MARK: Vertical rhythm between sections
-     Adjacency-based rather than flex+gap on cn-modal-content itself,
-     ModalContent needs to stay a plain block so consumers can turn it into a
-     flex row instead (e.g. ErrorModal, an icon beside the content) without
-     fighting a hardcoded flex-direction. Applies wherever these three end up
-     as direct siblings, regardless of what wraps them, ModalDescription is
-     usually a sibling of ModalHeader rather than nested inside it. */
-  :where(.cn-modal-header, .cn-modal-description, .cn-modal-footer)
-    + :where(.cn-modal-header, .cn-modal-description, .cn-modal-footer) {
-    margin-top: var(--spacing-gds-4);
-  }
+     No layout opinion of its own on cn-modal-content, it needs to stay a
+     plain block so consumers can turn it into a flex row instead (e.g.
+     ErrorModal, an icon beside the content) without fighting a hardcoded
+     flex-direction. Wrap whatever sits inside (ModalHeader, ModalDescription,
+     ModalFooter, and anything else a specific modal needs, a form, a
+     Details section, ...) in a Stack instead, same as any other arbitrary
+     vertical content elsewhere in the library. */
 
   /* MARK: Modal title and description */
 

package/src/components/Modal/Modal.stories.tsx

@@ -13,6 +13,11 @@ import {
   ModalTrigger,
 } from './Modal';
 import { Button } from '../Button/Button';
+import { FormGroup } from '../Form/FormGroup';
+import { HintText } from '../HintText/HintText';
+import { Input } from '../Input/Input';
+import { Label } from '../Label/Label';
+import { Stack } from '../Layout/Stack/Stack';
 
 const meta: Meta<typeof Modal> = {
   title: 'Components/Modal',
@@ -21,7 +26,8 @@ const meta: Meta<typeof Modal> = {
   parameters: {
     docs: {
       description: {
-        component: 'Use the Modal primitives to display dialog content in an overlay.',
+        component:
+          "Use the Modal primitives to display dialog content in an overlay. ModalContent has no layout opinion of its own (so consumers can turn it into something other than a column, e.g. ErrorModal's icon-beside-content row), wrap ModalHeader/ModalDescription/ModalFooter and anything else in a Stack for spacing between them, as below.",
       },
     },
   },
@@ -45,23 +51,75 @@ export const Default: Story = {
         </ModalTrigger>
 
         <ModalContent>
-          <ModalHeader>
-            <ModalTitle>Confirm action</ModalTitle>
-          </ModalHeader>
-
-          <ModalDescription>
-            Are you sure you want to continue? This action cannot be undone.
-          </ModalDescription>
-
-          <ModalFooter>
-            <Button appearance="secondary" onClick={() => setOpen(false)}>
-              Cancel
-            </Button>
-
-            <ModalClose asChild>
-              <Button>Confirm</Button>
-            </ModalClose>
-          </ModalFooter>
+          <Stack gap="sm">
+            <ModalHeader>
+              <ModalTitle>Confirm action</ModalTitle>
+            </ModalHeader>
+
+            <ModalDescription>
+              Are you sure you want to continue? This action cannot be undone.
+            </ModalDescription>
+
+            <ModalFooter>
+              <Button appearance="secondary" onClick={() => setOpen(false)}>
+                Cancel
+              </Button>
+
+              <ModalClose asChild>
+                <Button>Confirm</Button>
+              </ModalClose>
+            </ModalFooter>
+          </Stack>
+        </ModalContent>
+      </Modal>
+    );
+  },
+};
+
+export const WithFormContent: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Arbitrary content (a FormGroup here, could be anything) sits in the same Stack as ModalHeader/ModalDescription/ModalFooter, getting the same gap on both sides automatically, no extra spacing rules needed regardless of what's between them.",
+      },
+    },
+  },
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <Modal open={open} onOpenChange={setOpen}>
+        <ModalTrigger asChild>
+          <Button>Open modal</Button>
+        </ModalTrigger>
+
+        <ModalContent>
+          <Stack gap="sm">
+            <ModalHeader>
+              <ModalTitle>Rename item</ModalTitle>
+            </ModalHeader>
+
+            <ModalDescription>Choose a new name for this item.</ModalDescription>
+
+            <FormGroup>
+              <Label htmlFor="rename-item">Name</Label>
+
+              <HintText>As it should appear in the list</HintText>
+
+              <Input id="rename-item" aria-describedby="rename-item-hint" defaultValue="Untitled" />
+            </FormGroup>
+
+            <ModalFooter>
+              <Button appearance="secondary" onClick={() => setOpen(false)}>
+                Cancel
+              </Button>
+
+              <ModalClose asChild>
+                <Button>Save</Button>
+              </ModalClose>
+            </ModalFooter>
+          </Stack>
         </ModalContent>
       </Modal>
     );

package/src/components/Modal/Modal.tsx

@@ -131,6 +131,15 @@ export const ModalTitle = ({ className, ...props }: ModalTitleProps) => (
 
 export type ModalDescriptionProps = ComponentProps<typeof DialogPrimitive.Description>;
 
+// Renders a <p> (Description's own default), which can only contain
+// phrasing content, children here is assumed to be plain descriptive text
+// for that reason. Anything else (a Details/SummaryList section, a copy
+// button, ...) belongs as a sibling of ModalDescription instead, not
+// nested inside it, both because a <p> can't legally contain block
+// content (a browser silently closes it early on hitting one, which
+// desyncs SSR/client markup into a hydration error) and because
+// aria-describedby content should read as plain description text, not
+// fold in interactive elements. See ErrorModal for the sibling pattern.
 export const ModalDescription = ({ className, ...props }: ModalDescriptionProps) => (
   <DialogPrimitive.Description
     data-slot="modal-description"

package/src/components/Select/Select.css

@@ -100,6 +100,14 @@
     @apply panel absolute w-full mt-1 overflow-hidden cn-z-overlay;
   }
 
+  /* react-select flips the menu above the control when there isn't room
+     below. mt-1 pushes it further down rather than opening a gap in that
+     direction, mirror it as mb-1 so there's still a visible gap between
+     control and menu regardless of which side it opens on. */
+  .cn-select-menu-top {
+    @apply mt-0 mb-1;
+  }
+
   .cn-select-menu-list {
     @apply flex flex-col overflow-y-auto max-h-60;
   }

package/src/components/Select/Select.tsx

@@ -81,7 +81,12 @@ const buildClassNames = <Option, IsMulti extends boolean, Group extends GroupBas
     cn('cn-select-clear-indicator', userClassNames?.clearIndicator?.(props)),
   loadingIndicator: (props) =>
     cn('cn-select-loading-indicator', userClassNames?.loadingIndicator?.(props)),
-  menu: (props) => cn('cn-select-menu', userClassNames?.menu?.(props)),
+  menu: (props) =>
+    cn(
+      'cn-select-menu',
+      props.placement === 'top' && 'cn-select-menu-top',
+      userClassNames?.menu?.(props),
+    ),
   menuList: (props) => cn('cn-select-menu-list', userClassNames?.menuList?.(props)),
   option: (props) =>
     cn(

package/src/components/index.ts

@@ -330,6 +330,7 @@ export { Header } from './Header/Header';
 export { type HeaderProps } from './Header/Header';
 export { HeaderAppContent } from './Header/HeaderAppContent';
 export { Footer } from './Footer/Footer';
+export { type FooterProps } from './Footer/Footer';
 export { SmallFooter } from './Footer/Small/SmallFooter';
 export { Unauthorized } from './Layout/401/401';
 export { Forbidden } from './Layout/403/403';

package/src/http/constants.ts

@@ -13,6 +13,7 @@ export const MimeType = {
   Text: 'text/plain',
   NTriples: 'application/n-triples',
   OctetStream: 'application/octet-stream',
+  Mvt: 'application/vnd.mapbox-vector-tile',
 } as const;
 
 /**