@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,225 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ComponentProps,
+  type MouseEvent,
+} from 'react';
+
+import { LuX } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Button } from '../Button/Button';
+
+// MARK: Types
+
+type SidebarSide = 'left' | 'right' | 'top' | 'bottom';
+type SidebarOrientation = 'horizontal' | 'vertical';
+
+type SidebarContextValue = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  toggleSidebar: () => void;
+  isMobile: boolean;
+};
+
+type SidebarProviderProps = ComponentProps<'div'> & {
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  defaultOpen?: boolean;
+  /** Width of the sidebar panel for left/right sidebars. */
+  width?: string;
+  /** Height of the sidebar panel for top/bottom sidebars. */
+  height?: string;
+  /** Must be 'vertical' when using side="top" or side="bottom". */
+  orientation?: SidebarOrientation;
+};
+
+type SidebarProps = ComponentProps<'aside'> & {
+  side?: SidebarSide;
+  variant?: 'push' | 'overlay';
+};
+
+// MARK: Context
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+export const useSidebar = (): SidebarContextValue => {
+  const context = useContext(SidebarContext);
+
+  if (!context) {
+    throw new Error('useSidebar must be used inside SidebarProvider');
+  }
+
+  return context;
+};
+
+const useIsMobile = (breakpoint = 640) => {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const mq = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+
+    setIsMobile(mq.matches);
+    const handler = (event: MediaQueryListEvent) => setIsMobile(event.matches);
+
+    mq.addEventListener('change', handler);
+
+    return () => mq.removeEventListener('change', handler);
+  }, [breakpoint]);
+
+  return isMobile;
+};
+
+// MARK: SidebarProvider
+
+export const SidebarProvider = ({
+  open: controlledOpen,
+  onOpenChange,
+  defaultOpen = true,
+  width = '16rem',
+  height = '12rem',
+  orientation = 'horizontal',
+  children,
+  className,
+  style,
+  ...props
+}: SidebarProviderProps) => {
+  const [_open, _setOpen] = useState(defaultOpen);
+  const open = controlledOpen ?? _open;
+  const isMobile = useIsMobile();
+
+  const setOpen = useCallback(
+    (value: boolean) => {
+      _setOpen(value);
+      onOpenChange?.(value);
+    },
+    [onOpenChange],
+  );
+
+  const toggleSidebar = useCallback(() => setOpen(!open), [open, setOpen]);
+
+  const contextValue = useMemo(
+    () => ({ open, setOpen, toggleSidebar, isMobile }),
+    [open, setOpen, toggleSidebar, isMobile],
+  );
+
+  return (
+    <SidebarContext.Provider value={contextValue}>
+      <div
+        data-slot="sidebar-provider"
+        data-orientation={orientation}
+        className={cn('cn-sidebar-provider', className)}
+        style={
+          {
+            '--cn-sidebar-width': width,
+            '--cn-sidebar-height': height,
+            ...style,
+          } as CSSProperties
+        }
+        {...props}
+      >
+        {children}
+      </div>
+    </SidebarContext.Provider>
+  );
+};
+
+// MARK: Sidebar
+
+export const Sidebar = ({
+  side = 'left',
+  variant = 'push',
+  children,
+  className,
+  'aria-label': ariaLabel = 'Sidebar',
+  ...props
+}: SidebarProps) => {
+  const { open, isMobile, setOpen } = useSidebar();
+  const state = open ? 'expanded' : 'collapsed';
+
+  return (
+    <div
+      data-state={state}
+      data-side={side}
+      data-variant={variant}
+      data-mobile={isMobile || undefined}
+      className="cn-sidebar-root"
+    >
+      <div aria-hidden="true" className="cn-sidebar-gap" />
+
+      {isMobile && open && (
+        <div aria-hidden="true" className="cn-sidebar-backdrop" onClick={() => setOpen(false)} />
+      )}
+
+      <aside
+        data-slot="sidebar"
+        data-state={state}
+        aria-label={ariaLabel}
+        inert={open ? undefined : true}
+        className={cn('cn-sidebar', className)}
+        {...props}
+      >
+        {children}
+      </aside>
+    </div>
+  );
+};
+
+// MARK: SidebarClose
+
+export const SidebarClose = ({
+  className,
+  'aria-label': ariaLabel = 'Close sidebar',
+  onClick,
+  ...props
+}: Omit<ComponentProps<'button'>, 'children'>) => {
+  const { setOpen } = useSidebar();
+
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    setOpen(false);
+    onClick?.(event);
+  };
+
+  return (
+    <Button
+      variant="icon"
+      appearance="ghost"
+      data-slot="sidebar-close"
+      className={cn(className)}
+      aria-label={ariaLabel}
+      onClick={handleClick}
+      {...props}
+    >
+      <LuX aria-hidden />
+    </Button>
+  );
+};
+
+// MARK: SidebarInset
+
+export const SidebarInset = ({ className, ...props }: ComponentProps<'div'>) => (
+  <div data-slot="sidebar-inset" className={cn('cn-sidebar-inset', className)} {...props} />
+);
+
+// MARK: Structure
+
+export const SidebarHeader = ({ className, ...props }: ComponentProps<'div'>) => (
+  <div data-slot="sidebar-header" className={cn('cn-sidebar-header', className)} {...props} />
+);
+
+export const SidebarContent = ({ className, ...props }: ComponentProps<'div'>) => (
+  <div data-slot="sidebar-content" className={cn('cn-sidebar-content', className)} {...props} />
+);
+
+export const SidebarFooter = ({ className, ...props }: ComponentProps<'div'>) => (
+  <div data-slot="sidebar-footer" className={cn('cn-sidebar-footer', className)} {...props} />
+);
+
+export type { SidebarSide, SidebarOrientation, SidebarProviderProps, SidebarProps };

package/src/components/Skeleton/Skeleton.css

@@ -0,0 +1,16 @@
+@layer components {
+  /* MARK: Skeleton
+     Base placeholder shape shared by every per-component skeleton.
+     inline-block so it drops into text flow (heading/paragraph/button label
+     bars) without a forced line break, size it via className. Purely
+     decorative (aria-hidden), if you're assembling several of these into a
+     loading page, wrap the whole group in one role="status" region rather
+     than announcing loading per shape. */
+  .cn-skeleton {
+    /* bg-wash (5% black) is too faint to read clearly against a white page,
+       it's tuned for subtle hover backgrounds, not something that needs to
+       stand out. bg-muted (20% black, the same token dividers/disabled
+       states use) has enough contrast to actually read as "loading". */
+    @apply inline-block bg-muted animate-pulse;
+  }
+}

package/src/components/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Skeleton } from './Skeleton';
+
+const meta: Meta<typeof Skeleton> = {
+  title: 'Components/Skeleton',
+  component: Skeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Base placeholder shape shared by every per-component skeleton (HeadingSkeleton, ParagraphSkeleton, ButtonSkeleton, ...). Size it via `className`. Prefer reusing a real component's own classes over building a shape from scratch, so the skeleton always matches that component's real dimensions and never causes a layout shift when the real content loads in.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Skeleton>;
+
+export const Default: Story = {
+  render: () => <Skeleton className="h-4 w-48" />,
+};
+
+export const Shapes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-gds-2">
+      <Skeleton className="h-4 w-64" />
+
+      <Skeleton className="h-4 w-48" />
+
+      <Skeleton className="h-10 w-32" />
+
+      <Skeleton className="size-10" />
+    </div>
+  ),
+};

package/src/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,12 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type SkeletonProps = ComponentProps<'div'> & {
+  /** Explicitly disallow children, a skeleton is a placeholder shape, not a content wrapper. */
+  children?: never;
+};
+
+export const Skeleton = ({ className, ...props }: SkeletonProps) => (
+  <div data-slot="skeleton" aria-hidden className={cn('cn-skeleton', className)} {...props} />
+);

package/src/components/SkipLink/SkipLink.css

@@ -0,0 +1,16 @@
+@layer components {
+  .cn-skip-link {
+    @apply w-full block underline text-on-focus;
+
+    text-decoration-thickness: max(1px, 0.0625rem);
+    text-underline-offset: 0.1578em;
+
+    &:not(:focus) {
+      @apply sr-only;
+    }
+
+    &:focus {
+      @apply bg-focus outline-focus p-gds-3;
+    }
+  }
+}

package/src/components/SkipLink/SkipLink.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SkipLink } from './SkipLink';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+const meta: Meta<typeof SkipLink> = {
+  title: 'Components/SkipLink',
+  component: SkipLink,
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use a SkipLink to associate text with form controls and improve accessibility.',
+      },
+    },
+  },
+  argTypes: {
+    contentId: { control: 'text' },
+  },
+  args: {
+    contentId: 'main-content',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SkipLink>;
+
+export const Example: Story = {
+  render: (args) => (
+    <div>
+      <SkipLink contentId={args.contentId} />
+
+      <main id="main-content">
+        <Paragraph>
+          This is the main content. Click inside this example and press tab to see the skip link.
+        </Paragraph>
+      </main>
+    </div>
+  ),
+};

package/src/components/SkipLink/SkipLink.tsx

@@ -0,0 +1,15 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type SkipLinkProps = Omit<ComponentProps<'a'>, 'href' | 'children' | 'target' | 'ref'> & {
+  contentId: string;
+};
+
+export const SkipLink = ({ className, contentId, ...props }: SkipLinkProps) => {
+  return (
+    <a href={`#${contentId}`} className={cn('cn-skip-link', className)} {...props}>
+      Skip to main content
+    </a>
+  );
+};

package/src/components/Spinner/Spinner.css

@@ -0,0 +1,30 @@
+@layer components {
+  /* MARK: Spinner
+     h-10 w-10 is a reasonable general-purpose default, override via
+     className for a specific context (e.g. LoadingBox sizes it larger). */
+  .cn-spinner {
+    @apply h-10 w-10;
+  }
+
+  /* animation-duration is forced to 0.01ms under prefers-reduced-motion by
+     the shared base rule (see @tpzdsp/eslint-config-dsp's utilities.css),
+     no extra handling needed here. */
+  .cn-spinner-rect {
+    animation: cn-spinner-fade 1s linear infinite;
+  }
+
+  @keyframes cn-spinner-fade {
+    0% {
+      opacity: 0.250075;
+    }
+    0.01% {
+      opacity: 0.25;
+    }
+    0.03% {
+      opacity: 1;
+    }
+    100% {
+      opacity: 0.250075;
+    }
+  }
+}

package/src/components/Spinner/Spinner.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Spinner } from './Spinner';
+
+const meta: Meta<typeof Spinner> = {
+  title: 'Components/Spinner',
+  component: Spinner,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "GOV.UK-style loading spinner: 12 rects in a circle, each flashing then fading, staggered to sweep round like a clock. Sizes and colours via className, it's currentColor-based. Usually used via LoadingBox rather than directly.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Spinner>;
+
+export const Default: Story = {};
+
+export const CustomSize: Story = {
+  render: () => <Spinner className="h-20 w-20" />,
+};
+
+export const CustomColor: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'fill is currentColor, so it follows the text colour utility.' },
+    },
+  },
+  render: () => <Spinner className="text-accent" />,
+};

package/src/components/Spinner/Spinner.tsx

@@ -0,0 +1,45 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+// 12 rects arranged in a circle, each fading in then slowly back out (see
+// Spinner.css), staggered by delay so the flashes appear to sweep round like
+// a clock. Matches GOV.UK's own loading spinner. Fixed, stable keys (not
+// array index) even though these never reorder, same convention as this
+// library's skeleton components.
+const SPINNER_RECTS = Array.from({ length: 12 }, (_, index) => ({
+  key: `rect-${index}`,
+  angle: index * 30,
+  delayMs: index * 83,
+}));
+
+export type SpinnerProps = Omit<ComponentProps<'svg'>, 'title'> & {
+  title?: string;
+};
+
+export const Spinner = ({ className, title = 'Loading', ...props }: SpinnerProps) => (
+  <svg
+    data-slot="spinner"
+    viewBox="-25 -25 50 50"
+    preserveAspectRatio="xMidYMid meet"
+    fill="currentColor"
+    className={cn('cn-spinner', className)}
+    {...props}
+  >
+    {title ? <title>{title}</title> : null}
+
+    {SPINNER_RECTS.map(({ key, angle, delayMs }) => (
+      <rect
+        key={key}
+        className="cn-spinner-rect"
+        width="12"
+        height="5"
+        rx="2.5"
+        ry="2.5"
+        opacity="0"
+        transform={`rotate(${angle}, 0, 2) translate(10 0)`}
+        style={{ animationDelay: `${delayMs}ms` }}
+      />
+    ))}
+  </svg>
+);

package/src/components/StartButton/StartButton.css

@@ -0,0 +1,13 @@
+@layer components {
+  .cn-start-button {
+    @apply text-base sm:text-xl;
+  }
+
+  .cn-start-button-content {
+    @apply flex items-center gap-2;
+  }
+
+  .cn-start-button-icon {
+    @apply size-6 sm:size-7 stroke-3 sm:stroke-4;
+  }
+}

package/src/components/StartButton/StartButton.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { StartButton, StartButtonContent } from './StartButton';
+
+const meta: Meta<typeof StartButton> = {
+  title: 'Components/StartButton',
+  component: StartButton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Use a start button for the main call to action on your service’s Start page. It renders as a link (an `<a>`), not a `<button>`, matching the GDS start button: it navigates to the first page of a service rather than submitting data or triggering a JS action, so it needs a real `href`. Pass `asChild` to render your own element instead (e.g. Next.js's `Link`, for prefetching and base-path handling), nesting `StartButtonContent` inside it so both modes render identically.",
+      },
+    },
+  },
+  argTypes: {
+    appearance: {
+      control: { type: 'radio' },
+      options: ['primary', 'secondary'],
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof StartButton>;
+
+export const Primary: Story = {
+  args: {
+    appearance: 'primary',
+    href: '#',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    appearance: 'secondary',
+    href: '#',
+  },
+};
+
+export const CustomText: Story = {
+  args: {
+    appearance: 'primary',
+    href: '#',
+    children: 'Explore data',
+  },
+};
+
+export const AsChild: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `asChild` to render your own element as the actual link, e.g. Next.js\'s `Link`, so it handles prefetching and the app\'s base path rather than a plain `<a>`. The child stands in for a framework link component here; nest `StartButtonContent` inside it to get the same "Start now" text and chevron.',
+      },
+    },
+  },
+  render: () => (
+    <StartButton asChild appearance="primary">
+      {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
+      <a href="#">
+        <StartButtonContent />
+      </a>
+    </StartButton>
+  ),
+};

package/src/components/StartButton/StartButton.tsx

@@ -0,0 +1,50 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { LuChevronRight } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { LinkButton } from '../LinkButton/LinkButton';
+import type { LinkButtonAppearance } from '../LinkButton/LinkButton';
+
+export type StartButtonProps = ComponentProps<'a'> & {
+  asChild?: boolean;
+  appearance: Extract<LinkButtonAppearance, 'primary' | 'secondary'>;
+};
+
+export type StartButtonContentProps = {
+  children?: ReactNode;
+};
+
+export const StartButton = ({
+  appearance,
+  asChild = false,
+  children,
+  className,
+  ...props
+}: StartButtonProps) => {
+  return (
+    <LinkButton
+      asChild={asChild}
+      className={cn('cn-start-button', className)}
+      appearance={appearance}
+      variant="cta"
+      {...props}
+    >
+      {asChild ? children : <StartButtonContent>{children}</StartButtonContent>}
+    </LinkButton>
+  );
+};
+
+// The "Start now" text + chevron markup StartButton renders internally. Reuse
+// this inside your own link element when composing StartButton with
+// `asChild` (e.g. wrapping Next.js's `Link`), so both modes render identically:
+// <StartButton asChild appearance="primary"><NextLink href="/start"><StartButtonContent /></NextLink></StartButton>
+export const StartButtonContent = ({ children }: StartButtonContentProps) => {
+  return (
+    <span className="cn-start-button-content">
+      <span className="cn-start-button-text">{children ?? 'Start now'}</span>
+
+      <LuChevronRight className="cn-start-button-icon" />
+    </span>
+  );
+};

package/src/components/SubmitButton/SubmitButton.stories.tsx

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SubmitButton } from './SubmitButton';
+
+const meta: Meta<typeof SubmitButton> = {
+  title: 'Components/SubmitButton',
+  component: SubmitButton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use SubmitButton for an action that submits a form.',
+      },
+    },
+  },
+  argTypes: {
+    children: { control: 'text' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SubmitButton>;
+
+export const Default: Story = {};
+
+export const CustomText: Story = {
+  args: {
+    children: 'Click to submit',
+  },
+};

package/src/components/SubmitButton/SubmitButton.tsx

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+import { Button } from '../Button/Button';
+
+export type SubmitButtonProps = Omit<ComponentProps<typeof Button>, 'type'>;
+
+export const SubmitButton = ({ className, children, ...props }: SubmitButtonProps) => {
+  return (
+    <Button {...props} type="submit" className={cn(className, 'cn-submit-button')}>
+      {children ?? 'Submit'}
+    </Button>
+  );
+};