@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Header/Header.tsx

@@ -0,0 +1,303 @@
+'use client';
+
+import { type ReactNode, useEffect, useId, useRef, useState } from 'react';
+
+import { LuEllipsis, LuSearch, LuX } from 'react-icons/lu';
+
+import {
+  ButtonLink,
+  DefraLogo,
+  ExternalLink,
+  FormGroup,
+  Label,
+  Link,
+  PopoverContent,
+  PopoverTrigger,
+  SearchBox,
+  Separator,
+  WidthContainer,
+  Popover,
+  Paragraph,
+  ParagraphGroup,
+} from '@tpzdsp/next-toolkit/components';
+import { cn } from '@tpzdsp/next-toolkit/utils';
+
+import type { Credentials } from '../../types/auth';
+
+export type HeaderProps = {
+  appContent?: ReactNode;
+  credentials?: Credentials | null;
+};
+
+const DSP_NAV_LINKS = [
+  {
+    href: '/appgallery',
+    label: 'Apps',
+    mainNav: '@max-[520px]/main:hidden',
+    drawerNav: 'hidden @max-[520px]/drawer:block',
+  },
+  {
+    href: '/apiportal',
+    label: 'APIs',
+    mainNav: '@max-[620px]/main:hidden',
+    drawerNav: 'hidden @max-[620px]/drawer:block',
+  },
+  {
+    href: '/survey',
+    label: 'Survey',
+    mainNav: '@max-[720px]/main:hidden',
+    drawerNav: 'hidden @max-[720px]/drawer:block',
+  },
+  {
+    href: '/support',
+    label: 'Support',
+    mainNav: '@max-[820px]/main:hidden',
+    drawerNav: 'hidden @max-[820px]/drawer:block',
+  },
+  {
+    href: '/register',
+    label: 'Create an account',
+    mainNav: '@max-[970px]/main:hidden',
+    drawerNav: 'hidden @max-[970px]/drawer:block',
+  },
+] as const;
+
+const HOME_URL = '/';
+const LOGIN_URL = '/login';
+const LOGOUT_URL = '/logout';
+const DEFRA_URL =
+  'https://www.gov.uk/government/organisations/department-for-environment-food-rural-affairs';
+const GLOBAL_SEARCH_URL = '/globalSearch';
+const GLOBAL_SEARCH_QUERY_PARAM = 'query';
+
+export const Header = ({ appContent, credentials }: HeaderProps) => {
+  const navDrawerId = useId();
+  const searchDrawerId = useId();
+  const searchInputId = useId();
+
+  const [isDrawerOpen, setIsDrawerOpen] = useState(false);
+  const [isSearchOpen, setIsSearchOpen] = useState(false);
+  const [redirectUri, setRedirectUri] = useState('');
+
+  const triggerRef = useRef<HTMLLIElement>(null);
+  const drawerRef = useRef<HTMLDivElement>(null);
+  const hasOpenedRef = useRef(false);
+
+  // window isn't available during SSR, and the raw value needs encoding
+  // anyway (an unescaped ?/&/# in the current URL would otherwise corrupt
+  // this query string), so this is deferred to a client-only effect rather
+  // than read directly during render. Full absolute URL (not just path +
+  // search), sign-in/sign-out live on a separate origin, so it needs the
+  // hostname to know where to send the user back to.
+  useEffect(() => {
+    setRedirectUri(encodeURIComponent(window.location.href));
+  }, []);
+
+  // Move focus into the drawer when it opens; return it to the trigger when it closes.
+  // hasOpenedRef prevents a focus jump on initial render.
+  useEffect(() => {
+    if (isDrawerOpen) {
+      hasOpenedRef.current = true;
+
+      const firstFocusable = drawerRef.current?.querySelector<HTMLElement>(
+        'a[href], button:not([disabled])',
+      );
+
+      firstFocusable?.focus();
+    } else if (hasOpenedRef.current) {
+      triggerRef.current?.querySelector<HTMLElement>('button')?.focus();
+    }
+  }, [isDrawerOpen]);
+
+  useEffect(() => {
+    if (!isDrawerOpen) {
+      return;
+    }
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setIsDrawerOpen(false);
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isDrawerOpen]);
+
+  return (
+    <header className="w-full text-white border-b border-neutral-mid">
+      <WidthContainer className="flex items-center justify-center bg-accent z-10 relative">
+        <div
+          className="w-full h-14 flex p-gds-2 justify-between items-center gap-gds-4
+            @container/main"
+        >
+          <div className="flex h-full min-w-0 items-center gap-gds-4">
+            <div className="flex shrink-0 gap-gds-2 h-full items-center">
+              <ExternalLink
+                href={DEFRA_URL}
+                appearance="inverse"
+                variant="plain"
+                className="flex gap-gds-1 h-full items-center"
+              >
+                <DefraLogo aria-hidden className="h-full w-auto shrink-0 block" />
+
+                <abbr
+                  title="Department for Environment, Food, and Rural Affairs"
+                  className="sr-only xs:not-sr-only"
+                >
+                  DEFRA
+                </abbr>
+              </ExternalLink>
+
+              <Separator orientation="vertical" className="bg-white" />
+
+              <Link href={HOME_URL} appearance="inverse" className="text-nowrap">
+                <span className="hidden xs:inline">Data Services Platform</span>
+
+                <span className="inline xs:hidden">
+                  <abbr title="Data Services Platform">DSP</abbr>
+                </span>
+              </Link>
+            </div>
+
+            <nav aria-label="Primary navigation" className="min-w-0">
+              <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">
+                      {item.label}
+                    </ExternalLink>
+                  </li>
+                ))}
+                <li ref={triggerRef} className="flex items-center more-btn shrink-0">
+                  <ButtonLink
+                    aria-label="Navigation drawer"
+                    aria-expanded={isDrawerOpen}
+                    aria-controls={navDrawerId}
+                    appearance="inverse"
+                    variant="icon"
+                    onClick={() => setIsDrawerOpen(!isDrawerOpen)}
+                  >
+                    <LuEllipsis aria-hidden />
+                  </ButtonLink>
+                </li>
+              </ul>
+            </nav>
+          </div>
+
+          <div className="flex shrink-0 gap-gds-2 h-full items-center">
+            {credentials ? (
+              <Popover>
+                <PopoverTrigger asChild>
+                  <ButtonLink appearance="inverse">Profile</ButtonLink>
+                </PopoverTrigger>
+
+                <PopoverContent sideOffset={0}>
+                  <ParagraphGroup>
+                    <Paragraph>
+                      <div className="font-bold">Signed in as:</div>
+
+                      <div>{credentials.user.email}</div>
+                    </Paragraph>
+
+                    <Link href={`${LOGOUT_URL}?redirect_uri=${redirectUri}`}>Sign-out</Link>
+                  </ParagraphGroup>
+                </PopoverContent>
+              </Popover>
+            ) : (
+              <Link
+                href={`${LOGIN_URL}?redirect_uri=${redirectUri}`}
+                appearance="inverse"
+                className="text-nowrap"
+              >
+                Sign-in
+              </Link>
+            )}
+
+            <Separator orientation="vertical" className="bg-white" />
+
+            <ButtonLink
+              appearance="inverse"
+              variant="icon"
+              aria-label="Search the Data Services Platform"
+              aria-controls={searchDrawerId}
+              aria-expanded={isSearchOpen}
+              onClick={() => setIsSearchOpen(!isSearchOpen)}
+            >
+              <LuSearch aria-hidden />
+            </ButtonLink>
+          </div>
+        </div>
+      </WidthContainer>
+
+      <div
+        id={searchDrawerId}
+        inert={!isSearchOpen}
+        className={cn(
+          'w-full bg-wash grid transition-[grid-template-rows] duration-200',
+          isSearchOpen ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+        )}
+      >
+        <WidthContainer className="min-h-0 overflow-hidden">
+          <div className="w-full h-40 p-gds-6 flex items-center">
+            <form action={GLOBAL_SEARCH_URL} className="w-full">
+              <FormGroup>
+                <Label htmlFor={searchInputId} className="font-bold text-2xl">
+                  Search DSP
+                </Label>
+
+                <SearchBox id={searchInputId} name={GLOBAL_SEARCH_QUERY_PARAM} />
+              </FormGroup>
+            </form>
+          </div>
+        </WidthContainer>
+      </div>
+
+      <div
+        id={navDrawerId}
+        ref={drawerRef}
+        inert={!isDrawerOpen}
+        className={cn(
+          `w-full bg-accent grid transition-[grid-template-rows] duration-200 border-b
+          border-neutral-mid`,
+          isDrawerOpen ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+        )}
+      >
+        <WidthContainer className="bg-accent min-h-0 overflow-hidden">
+          <div
+            className="w-full min-h-14 flex p-gds-2 justify-between items-center gap-gds-4
+              @container/drawer"
+          >
+            <nav aria-label="More navigation">
+              <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">
+                      {item.label}
+                    </ExternalLink>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+
+            <ButtonLink
+              aria-label="Close"
+              appearance="inverse"
+              variant="icon"
+              onClick={() => setIsDrawerOpen(false)}
+            >
+              <LuX aria-hidden />
+            </ButtonLink>
+          </div>
+        </WidthContainer>
+      </div>
+
+      {appContent ? (
+        <WidthContainer className="bg-body-secondary">
+          <div className="w-full h-14 flex p-gds-2 items-center">{appContent}</div>
+        </WidthContainer>
+      ) : null}
+    </header>
+  );
+};

package/src/components/Header/HeaderAppContent.tsx

@@ -0,0 +1,120 @@
+import type { ComponentType } from 'react';
+
+import { LuEllipsis } from 'react-icons/lu';
+
+import {
+  ButtonLink,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Link,
+} from '@tpzdsp/next-toolkit/components';
+import type { LinkProps } from '@tpzdsp/next-toolkit/components';
+
+import type { NavLink } from '../../types';
+
+export type HeaderAppContentProps = {
+  /** App name, shown on the left. Plain text, or a NavLink if it should link
+   *  somewhere (e.g. back to the app's home page). */
+  title: string | NavLink;
+  links?: NavLink[];
+  /** Defaults to this library's own Link (a plain <a>). Pass your app's own Link
+   *  wrapper instead if it needs Next.js client-side routing, e.g. one that uses
+   *  asChild internally with next/link, it just needs to accept the same props. */
+  linkComponent?: ComponentType<LinkProps>;
+};
+
+// Omit<LinkProps, ...> (not a fixed prop list): when this sits inside
+// DropdownMenuItem asChild, Radix clones this component and merges its own
+// props onto it (role="menuitem", tabIndex, the keyboard/selection
+// handlers roving-tabindex needs, className). Without a rest spread here to
+// forward all of that through to LinkComponent, Radix's merge dead-ends at
+// this component and every one of those props is silently dropped, not
+// just a styling gap, menuitem role and keyboard handling would be missing
+// too.
+type HeaderAppContentNavLinkProps = Omit<LinkProps, 'href' | 'children'> & {
+  link: NavLink;
+  linkComponent: ComponentType<LinkProps>;
+};
+
+const HeaderAppContentNavLink = ({
+  link,
+  linkComponent: LinkComponent,
+  appearance = 'inverse',
+  ...props
+}: HeaderAppContentNavLinkProps) => (
+  <LinkComponent
+    href={link.url}
+    appearance={appearance}
+    target={link.openInNewTab ? '_blank' : undefined}
+    rel={link.openInNewTab ? 'noopener noreferrer' : undefined}
+    {...props}
+  >
+    {link.label}
+  </LinkComponent>
+);
+
+export const HeaderAppContent = ({
+  title,
+  links = [],
+  linkComponent: LinkComponent = Link,
+}: HeaderAppContentProps) => (
+  <div className="@container/app-nav flex w-full items-center justify-between gap-gds-4">
+    <div className="flex shrink-0 items-center gap-gds-2 text-lg font-bold">
+      {typeof title === 'string' ? (
+        title
+      ) : (
+        <HeaderAppContentNavLink link={title} linkComponent={LinkComponent} />
+      )}
+    </div>
+
+    {links.length > 0 ? (
+      <>
+        {/* 650px: below this the inline list and the title no longer
+            comfortably fit side by side. A single width rather than
+            per-link breakpoints (contrast Header.tsx's own DSP_NAV_LINKS,
+            which hides one specific, known link at a time): links here are
+            an arbitrary, app-supplied list, there's no fixed set to
+            hand-tune individual cutoffs for, so this collapses the whole
+            list to a menu at once instead. A reasonable default, not a
+            computed value, nudge it if a specific app's title/link lengths
+            need something else. */}
+        <nav aria-label="App" className="hidden min-w-0 @min-[650px]/app-nav:block">
+          <ul className="flex items-center gap-gds-4">
+            {links.map((link) => (
+              <li key={link.url}>
+                <HeaderAppContentNavLink link={link} linkComponent={LinkComponent} />
+              </li>
+            ))}
+          </ul>
+        </nav>
+
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <ButtonLink
+              appearance="inverse"
+              variant="icon"
+              aria-label="App navigation"
+              className="@min-[650px]/app-nav:hidden"
+            >
+              <LuEllipsis aria-hidden />
+            </ButtonLink>
+          </DropdownMenuTrigger>
+
+          <DropdownMenuContent align="end">
+            {links.map((link) => (
+              <DropdownMenuItem key={link.url} asChild>
+                <HeaderAppContentNavLink
+                  link={link}
+                  linkComponent={LinkComponent}
+                  appearance="contrast"
+                />
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </>
+    ) : null}
+  </div>
+);

package/src/components/Heading/Heading.css

@@ -0,0 +1,40 @@
+@layer components {
+  /* MARK: Heading */
+  .cn-heading {
+    @apply font-bold;
+  }
+
+  .cn-heading-1 {
+    @apply text-[2rem] sm:text-5xl;
+  }
+
+  .cn-heading-2 {
+    @apply text-2xl sm:text-4xl;
+  }
+
+  .cn-heading-3 {
+    @apply text-xl sm:text-3xl;
+  }
+
+  .cn-heading-4 {
+    @apply text-lg sm:text-2xl;
+  }
+
+  .cn-heading-5 {
+    @apply text-base sm:text-xl;
+  }
+
+  .cn-heading-6 {
+    @apply text-sm sm:text-lg;
+  }
+
+  /* MARK: Skeleton
+     Sized in em so it scales with whichever cn-heading-N font-size applies,
+     one rule covers every level. Shorter than the line-height (~1.2-1.5x
+     font-size for every text-* utility here) so it sits inside the line box
+     rather than stretching it, the heading ends up exactly as tall as it
+     would be with real text. */
+  .cn-heading-skeleton-bar {
+    @apply h-[0.7em] w-3/4;
+  }
+}

package/src/components/Heading/Heading.stories.tsx

@@ -2,16 +2,26 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { Heading, type HeadingProps } from './Heading';
 
-export default {
-  children: 'Heading',
+const meta: Meta<typeof Heading> = {
+  title: 'Components/Heading/Heading',
   component: Heading,
-} as Meta;
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Responsive heading text.',
+      },
+    },
+  },
+};
+
+export default meta;
 
 export const AllHeadings: StoryObj<typeof Heading> = {
   render: () => (
     <div>
-      {(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as HeadingProps['type'][]).map((type) => (
-        <Heading key={type} type={type}>
+      {(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as HeadingProps['level'][]).map((type) => (
+        <Heading key={type} level={type}>
           {type.toUpperCase()} Example
         </Heading>
       ))}

package/src/components/Heading/Heading.tsx

@@ -1,50 +1,27 @@
-import type { ExtendProps } from '../../types';
+import type { ComponentProps } from 'react';
+
 import { cn } from '../../utils';
 
-type Props = {
-  type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+// h1 through h6 have identical props
+export type HeadingProps = ComponentProps<'h1'> & {
+  level: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 };
 
-// h1 through h6 have identical props
-export type HeadingProps = ExtendProps<'h1', Props>;
+const HEADING_LEVELS = {
+  h1: 'cn-heading-1',
+  h2: 'cn-heading-2',
+  h3: 'cn-heading-3',
+  h4: 'cn-heading-4',
+  h5: 'cn-heading-5',
+  h6: 'cn-heading-6',
+} as const;
+
+export const Heading = ({ level, className, children, ...props }: HeadingProps) => {
+  const Comp = level;
 
-export const Heading = ({ type, className, children, ...props }: HeadingProps) => {
-  switch (type) {
-    case 'h1':
-      return (
-        <h1 className={cn('py-4 text-4xl font-bold text-text-primary', className)} {...props}>
-          {children}
-        </h1>
-      );
-    case 'h2':
-      return (
-        <h2 className={cn('py-3 text-3xl font-bold text-text-primary', className)} {...props}>
-          {children}
-        </h2>
-      );
-    case 'h3':
-      return (
-        <h3 className={cn('py-3 text-xl font-bold text-text-primary', className)} {...props}>
-          {children}
-        </h3>
-      );
-    case 'h4':
-      return (
-        <h4 className={cn('py-3 text-lg font-bold text-text-primary', className)} {...props}>
-          {children}
-        </h4>
-      );
-    case 'h5':
-      return (
-        <h5 className={cn('py-2 text-base font-bold text-text-primary', className)} {...props}>
-          {children}
-        </h5>
-      );
-    case 'h6':
-      return (
-        <h6 className={cn('py-2 text-sm font-bold text-text-primary', className)} {...props}>
-          {children}
-        </h6>
-      );
-  }
+  return (
+    <Comp className={cn('cn-heading', HEADING_LEVELS[level], className)} {...props}>
+      {children}
+    </Comp>
+  );
 };

package/src/components/Heading/HeadingSkeleton.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import type { HeadingProps } from './Heading';
+import { HeadingSkeleton } from './HeadingSkeleton';
+
+const meta: Meta<typeof HeadingSkeleton> = {
+  title: 'Components/Heading/Skeleton',
+  component: HeadingSkeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Placeholder for a Heading while its real text is loading. Renders a real Heading at the given level, so the font-size and line-height (and therefore the rendered height) always match what real text at that level would produce, no layout shift when it swaps in.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const AllLevels: StoryObj<typeof HeadingSkeleton> = {
+  render: () => (
+    <div className="flex flex-col gap-gds-2">
+      {(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as HeadingProps['level'][]).map((level) => (
+        <HeadingSkeleton key={level} level={level} />
+      ))}
+    </div>
+  ),
+};

package/src/components/Heading/HeadingSkeleton.tsx

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+
+import { Heading } from './Heading';
+import { Skeleton } from '../Skeleton/Skeleton';
+
+export type HeadingSkeletonProps = Omit<ComponentProps<typeof Heading>, 'children'> & {
+  children?: never;
+};
+
+export const HeadingSkeleton = ({ className, ...props }: HeadingSkeletonProps) => (
+  <Heading aria-hidden className={className} {...props}>
+    <Skeleton className="cn-heading-skeleton-bar" />
+  </Heading>
+);

package/src/components/Hero/Hero.css

@@ -0,0 +1,19 @@
+@layer components {
+  /* Full-bleed breakout: Hero is meant to span the viewport regardless of
+     where it's mounted, but it's built on WidthContainer, so if it's ever
+     nested inside another WidthContainer/MainWrapper (e.g. rendered as page
+     content under a shared layout's <main>), it would otherwise inherit that
+     ancestor's max-w-page cap. left: 50% shifts it to the viewport's
+     horizontal center regardless of the containing block's width, as long as
+     that containing block is itself symmetrically centered, true here since
+     every ancestor up to the viewport is either full-width or mx-auto; width:
+     100vw + the negative margins then pull its edges out to the true viewport
+     edges. Pair with overflow-x-clip on PageShell (or another page-level
+     ancestor), 100vw includes the scrollbar gutter in browsers that reserve
+     space for it, which can otherwise introduce a few pixels of unwanted
+     horizontal scroll. */
+  .cn-hero {
+    @apply bg-accent text-on-accent py-gds-4 sm:py-gds-6;
+    position: relative;
+  }
+}

package/src/components/Hero/Hero.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Hero } from './Hero';
+import { Heading } from '../Heading/Heading';
+import { ButtonGroup } from '../Layout/ButtonGroup/ButtonGroup';
+import { HeadingGroup } from '../Layout/HeadingGroup/HeadingGroup';
+import { Paragraph } from '../Paragraph/Paragraph';
+import { StartButton } from '../StartButton/StartButton';
+
+const meta: Meta<typeof Hero> = {
+  title: 'Components/Hero',
+  component: Hero,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use a Hero to associate text with form controls and improve accessibility.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Hero>;
+
+export const Default: Story = {
+  render: () => (
+    <Hero>
+      <ButtonGroup orientation="vertical">
+        <HeadingGroup>
+          <Heading level="h1">UK Wetland Inventory</Heading>
+
+          <Paragraph>Explore the UK&apos;s vital wetland habits</Paragraph>
+        </HeadingGroup>
+
+        <StartButton appearance="secondary" href="#" />
+      </ButtonGroup>
+    </Hero>
+  ),
+};