@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Details/Details.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { Collapsible as CollapsiblePrimitive } from 'radix-ui';
+import { LuChevronRight } from 'react-icons/lu';
+
+import { cn } from '../../utils';
+
+export type DetailsProps = ComponentProps<typeof CollapsiblePrimitive.Root>;
+
+export const Details = ({ className, ...props }: DetailsProps) => (
+  <CollapsiblePrimitive.Root
+    data-slot="details"
+    className={cn('cn-details', className)}
+    {...props}
+  />
+);
+
+export type DetailsTriggerProps = ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>;
+
+export const DetailsTrigger = ({ className, children, ...props }: DetailsTriggerProps) => (
+  <CollapsiblePrimitive.CollapsibleTrigger
+    data-slot="details-trigger"
+    className={cn('cn-details-trigger', className)}
+    {...props}
+  >
+    <LuChevronRight aria-hidden className="cn-details-trigger-icon" />
+    {children}
+  </CollapsiblePrimitive.CollapsibleTrigger>
+);
+
+export type DetailsContentProps = ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>;
+
+export const DetailsContent = ({ className, ...props }: DetailsContentProps) => (
+  <CollapsiblePrimitive.CollapsibleContent
+    data-slot="details-content"
+    className={cn('cn-details-content', className)}
+    {...props}
+  />
+);

package/src/components/Dropdown/Dropdown.css

@@ -0,0 +1,81 @@
+@layer components {
+  /* MARK: Content
+     Same panel treatment as Popover/Select's own menu (bg-panel + border),
+     portal-rendered so DOM order is always safe above page content, but
+     cn-z-overlay still matters against other elements with their own high
+     z-index (e.g. a resizable handle's cn-z-top). */
+  .cn-dropdown-menu-content {
+    @apply panel cn-z-overlay min-w-40 overflow-hidden;
+
+    &[data-state='open'] {
+      animation: cn-dropdown-menu-in 0.1s ease-out;
+    }
+
+    &[data-state='closed'] {
+      animation: cn-dropdown-menu-out 0.075s ease-in;
+    }
+  }
+
+  @keyframes cn-dropdown-menu-in {
+    from {
+      opacity: 0;
+      transform: scale(0.97);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+
+  @keyframes cn-dropdown-menu-out {
+    from {
+      opacity: 1;
+    }
+    to {
+      opacity: 0;
+    }
+  }
+
+  /* MARK: Item
+     data-highlighted is Radix's own state for whichever item is currently
+     hovered or keyboard-focused (it also moves real DOM focus there when
+     keyboard-navigated, which is what lets a real Link's own :focus/:hover
+     apply at all, asChild renders this class directly onto whatever's
+     passed as a child, e.g. HeaderAppContentNavLink, there's no wrapper,
+     so a Link IS this element). Every item gets the same washed background
+     on highlight regardless of content, same as cn-select-option-focused,
+     so the menu reads consistently row to row.
+
+     border-none/shadow-none on top of that specifically neutralises a
+     Link's own :focus box-shadow (the GDS yellow-bar treatment), which
+     would otherwise show alongside the washed background rather than the
+     two picking one look. A highlighted link still reads as a link
+     though: :is(a) applies cn-link-hover-decoration, the same
+     thicker-underline Link.css itself uses on :hover, layered on top of
+     the shared background rather than replacing it. */
+  .cn-dropdown-menu-item {
+    @apply block w-full cursor-default px-gds-2 text-left text-base py-gds-1;
+
+    &:hover,
+    &:focus {
+      @apply outline-none;
+    }
+
+    &[data-highlighted] {
+      @apply bg-wash border-none shadow-none;
+    }
+
+    &[data-highlighted]:is(a) {
+      @apply cn-link-hover-decoration;
+    }
+
+    &[data-disabled] {
+      @apply cursor-not-allowed opacity-50;
+    }
+  }
+
+  /* MARK: Separator */
+  .cn-dropdown-menu-separator {
+    @apply my-gds-1 h-px bg-divider;
+  }
+}

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from './Dropdown';
+import { Button } from '../Button/Button';
+import { ExternalLink } from '../ExternalLink/ExternalLink';
+import { Link } from '../Link/Link';
+
+const meta: Meta<typeof DropdownMenu> = {
+  title: 'Components/Dropdown',
+  component: DropdownMenu,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A floating menu of actions or links anchored to a trigger. Built for a flat list of nav links, not a full command menu, no checkbox/radio items, submenus, or keyboard shortcuts. Use DropdownMenuItem with asChild and a real Link (this library's own, a plain `<a>`, or a framework-aware wrapper like one using asChild internally with next/link). Every item, Link or not, gets the same washed background on highlight; a highlighted Link also keeps its own thicker-underline hover cue on top of that, its focus box-shadow is neutralised so the two don't compete. Whatever component you pass needs to forward extra props through to its own rendered element (via a rest spread), asChild relies on that to merge role=\"menuitem\" and keyboard handling onto it, see HeaderAppContent's own HeaderAppContentNavLink for a real example.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DropdownMenu>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Using this library's own Link/ExternalLink with asChild, appearance=\"contrast\" for plain body-coloured text on the menu's white background. Highlighting an item (hover or arrow-key nav) shows the same washed background as any other item, plus the link's own thicker-underline hover cue.",
+      },
+    },
+  },
+  render: () => (
+    <div className="flex min-h-40 items-start justify-center">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button appearance="secondary">Account</Button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent>
+          <DropdownMenuItem asChild>
+            <ExternalLink variant="icon" href="#profile" appearance="contrast">
+              Profile
+            </ExternalLink>
+          </DropdownMenuItem>
+
+          <DropdownMenuItem asChild>
+            <ExternalLink variant="icon" href="#settings" appearance="contrast">
+              Settings
+            </ExternalLink>
+          </DropdownMenuItem>
+
+          <DropdownMenuItem asChild>
+            <Link href="#sign-out" appearance="contrast">
+              Sign out
+            </Link>
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+};
+
+export const WithSeparator: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'DropdownMenuSeparator splits related links from an unrelated one, e.g. sign out.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex min-h-40 items-start justify-center">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button appearance="secondary">Account</Button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent>
+          <DropdownMenuItem asChild>
+            <ExternalLink variant="icon" href="#profile" appearance="contrast">
+              Profile
+            </ExternalLink>
+          </DropdownMenuItem>
+
+          <DropdownMenuItem asChild>
+            <ExternalLink variant="icon" href="#settings" appearance="contrast">
+              Settings
+            </ExternalLink>
+          </DropdownMenuItem>
+
+          <DropdownMenuSeparator />
+
+          <DropdownMenuItem asChild>
+            <Link href="#sign-out" appearance="contrast">
+              Sign out
+            </Link>
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+};
+
+export const WithDisabledItem: Story = {
+  render: () => (
+    <div className="flex min-h-40 items-start justify-center">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button appearance="secondary">Sort</Button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent>
+          <DropdownMenuItem>Date</DropdownMenuItem>
+
+          <DropdownMenuItem disabled>Name (unavailable)</DropdownMenuItem>
+
+          <DropdownMenuItem>Type</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+};

package/src/components/Dropdown/Dropdown.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
+
+import { cn } from '../../utils/components';
+
+export const DropdownMenu = ({ ...props }: ComponentProps<typeof DropdownMenuPrimitive.Root>) => (
+  <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />
+);
+
+export const DropdownMenuTrigger = ({
+  ...props
+}: ComponentProps<typeof DropdownMenuPrimitive.Trigger>) => (
+  <DropdownMenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />
+);
+
+export const DropdownMenuContent = ({
+  className,
+  align = 'start',
+  sideOffset = 6,
+  ...props
+}: ComponentProps<typeof DropdownMenuPrimitive.Content>) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      data-slot="dropdown-menu-content"
+      align={align}
+      sideOffset={sideOffset}
+      className={cn('cn-dropdown-menu-content', className)}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+);
+
+// asChild + a real Link for nav links (this library's own, or a
+// framework-aware wrapper e.g. one using asChild internally with next/link).
+// cn-dropdown-menu-item gives every item (Link or not) the same washed
+// background on highlight, same as Select's own menu, rather than leaving
+// a Link's own :focus box-shadow to fight that for the same row (which it
+// specifically neutralises), a highlighted Link still gets its own cue on
+// top, the same thicker-underline Link.css itself uses on :hover, see
+// Dropdown.css for the exact rules. Whatever's passed here needs to
+// forward arbitrary extra props through to its own rendered element
+// (asChild relies on that to merge role="menuitem", the roving-tabindex
+// keyboard handlers, and this className onto it), a component that only
+// destructures its own known props without a rest spread will silently
+// drop all of that.
+export const DropdownMenuItem = ({
+  className,
+  ...props
+}: ComponentProps<typeof DropdownMenuPrimitive.Item>) => (
+  <DropdownMenuPrimitive.Item
+    data-slot="dropdown-menu-item"
+    className={cn('cn-dropdown-menu-item', className)}
+    {...props}
+  />
+);
+
+export const DropdownMenuSeparator = ({
+  className,
+  ...props
+}: ComponentProps<typeof DropdownMenuPrimitive.Separator>) => (
+  <DropdownMenuPrimitive.Separator
+    data-slot="dropdown-menu-separator"
+    className={cn('cn-dropdown-menu-separator', className)}
+    {...props}
+  />
+);

package/src/components/ErrorBoundary/ErrorBoundary.stories.tsx

@@ -1,33 +1,17 @@
-import type { FallbackProps } from 'react-error-boundary';
-
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { ErrorBoundary } from './ErrorBoundary';
+import { Paragraph } from '../Paragraph/Paragraph';
 
 // Component that intentionally throws an error
 const Bomb = () => {
   throw new Error('Boom!');
 };
 
-// Simple custom fallback for demonstration
-const CustomFallback = ({ error, resetErrorBoundary }: FallbackProps) => (
-  <div role="alert" className="p-4 border border-red-300 rounded-lg bg-red-50">
-    <p className="font-medium text-red-700">Custom Fallback:</p>
-
-    <p className="text-red-600">{error instanceof Error ? error.message : 'Unknown'}</p>
-
-    <button
-      className="px-3 py-1 mt-2 text-white bg-red-600 rounded hover:bg-red-700"
-      onClick={resetErrorBoundary}
-    >
-      Try Again
-    </button>
-  </div>
-);
-
 const meta = {
   title: 'Components/ErrorBoundary',
   component: ErrorBoundary,
+  tags: ['autodocs'],
   parameters: {
     layout: 'centered',
     docs: {
@@ -37,7 +21,6 @@ const meta = {
       },
     },
   },
-  tags: ['autodocs'],
 } satisfies Meta<typeof ErrorBoundary>;
 
 export default meta;
@@ -45,16 +28,12 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    children: (
-      <div className="p-4 text-green-800 border rounded-md bg-green-50">
-        <p>No errors here — everything renders normally.</p>
-      </div>
-    ),
+    children: <Paragraph>No errors here — everything renders normally.</Paragraph>,
   },
   parameters: {
     docs: {
       description: {
-        story: 'Default behavior — children render normally when no error is thrown.',
+        story: 'Default behavior. Children render normally when no error is thrown.',
       },
     },
   },
@@ -72,17 +51,3 @@ export const WithError: Story = {
     },
   },
 };
-
-export const WithCustomFallback: Story = {
-  args: {
-    children: <Bomb />,
-    fallback: CustomFallback,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'ErrorBoundary can render a custom fallback component when errors occur.',
-      },
-    },
-  },
-};

package/src/components/ErrorBoundary/ErrorBoundary.tsx

@@ -1,13 +1,16 @@
-import type { ComponentType, ErrorInfo, ReactNode } from 'react';
+'use client';
+
+import type { ComponentProps, ComponentType, ErrorInfo } from 'react';
 
 import { ErrorBoundary as ReactErrorBoundary, type FallbackProps } from 'react-error-boundary';
 
 import { ErrorFallback } from './ErrorFallback';
 
-type ErrorBoundaryProps = {
-  children: ReactNode;
+export type ErrorBoundaryProps = Omit<
+  ComponentProps<typeof ReactErrorBoundary>,
+  'onError' | 'FallbackComponent'
+> & {
   fallback?: ComponentType<FallbackProps>;
-  onReset?: () => void;
 };
 
 export const ErrorBoundary = ({ children, fallback, onReset }: ErrorBoundaryProps) => {

package/src/components/ErrorBoundary/ErrorFallback.tsx

@@ -1,18 +1,21 @@
 'use client';
 
-import { useId } from 'react';
+import { useId, type ComponentProps } from 'react';
 
 import { type FallbackProps } from 'react-error-boundary';
 
-import { ApiError } from '../../errors/ApiError';
-import type { ExtendProps } from '../../types';
+import { formatErrorForClipboard, getErrorDisplayInfo } from '../../errors/errorDisplay';
 import { cn } from '../../utils';
-import { Accordion } from '../accordion/Accordion';
 import { Button } from '../Button/Button';
-import { Heading } from '../Heading/Heading';
+import { CopyButton } from '../CopyButton/CopyButton';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { HintText } from '../HintText/HintText';
+import { InfoBox } from '../InfoBox/InfoBox';
+import { ButtonGroup } from '../Layout/ButtonGroup/ButtonGroup';
 import { Paragraph } from '../Paragraph/Paragraph';
+import { ScrollArea } from '../ScrollArea/ScrollArea';
 
-export type ErrorFallbackProps = ExtendProps<'div', FallbackProps>;
+export type ErrorFallbackProps = ComponentProps<'div'> & FallbackProps;
 
 export const ErrorFallback = ({
   resetErrorBoundary,
@@ -22,78 +25,41 @@ export const ErrorFallback = ({
 }: ErrorFallbackProps) => {
   const id = useId();
 
-  let message;
-  let details = undefined;
-  let digest = undefined;
-
-  if (error instanceof ApiError) {
-    message = error.message;
-    details = error.details;
-    digest = error.digest;
-  } else if (error instanceof Error) {
-    message = error.message;
-    details = error.cause?.toString();
-  } else {
-    message = 'Unknown error';
-  }
-
-  const copyToClipboard = () => {
-    navigator.clipboard.writeText(
-      // eslint-disable-next-line sonarjs/no-nested-template-literals
-      `App Error: ${message}, ${details ? `Details: ${details}, ` : ''}${digest ? `Digest: ${digest}` : ''}`,
-    );
-  };
+  const info = getErrorDisplayInfo(error);
+  const clipboardContent = formatErrorForClipboard(info);
 
   return (
     <div
       role="alert"
       aria-labelledby={id}
-      className={cn(
-        'grid gap-2 border-form border-transparent border-l-error max-w-full pl-2',
-        className,
-      )}
-      style={{ gridTemplateColumns: '1fr auto' }}
+      className={cn('border-l-standard pl-gds-2 border-error', className)}
       {...props}
     >
-      <div className="flex flex-col gap-0.5">
-        <Heading id={id} type="h3" className="text-error text-base font-semibold py-0">
-          Something went wrong
-        </Heading>
+      <div className="flex items-center gap-gds-1">
+        <ErrorText id={id}>Something went wrong</ErrorText>
 
-        <Paragraph className="leading-snug pb-0">
-          <strong>Reason:</strong> {message}
-        </Paragraph>
-      </div>
+        <InfoBox>
+          <div className="flex flex-col gap-gds-2">
+            <ScrollArea className="max-h-32 overflow-y-auto overflow-x-hidden">
+              <Paragraph className="leading-snug pb-0">
+                <strong>Reason:</strong> {info.message}
+              </Paragraph>
+            </ScrollArea>
 
-      <div className="flex items-start gap-1">
-        <Button onClick={copyToClipboard} variant="secondary" className="shrink-0">
-          Copy
-        </Button>
+            <div className="flex flex-col gap-gds-1">
+              <ButtonGroup>
+                <CopyButton appearance="secondary" content={clipboardContent} />
 
-        <Button onClick={resetErrorBoundary} variant="secondary" className="shrink-0">
-          Retry
-        </Button>
-      </div>
+                <Button onClick={resetErrorBoundary}>Retry</Button>
+              </ButtonGroup>
 
-      {details && (
-        <div className="col-span-2">
-          <Accordion title="Show details">
-            <div className="flex gap-0.5 flex-col">
-              {digest && (
-                <Paragraph className="leading-snug pb-0">
-                  <strong>Error ID:</strong> {digest}
-                </Paragraph>
-              )}
-              <pre
-                className="text-base bg-white border border-gray-200 p-2 overflow-y-auto max-h-32
-                  whitespace-pre-wrap"
-              >
-                {details}
-              </pre>
+              <HintText className="text-sm">
+                Copy to share error details with the app administrator.
+              </HintText>
             </div>
-          </Accordion>
-        </div>
-      )}
+          </div>
+        </InfoBox>
+      </div>
     </div>
   );
 };

package/src/components/ErrorModal/ErrorModal.css

@@ -0,0 +1,32 @@
+@layer components {
+  /* MARK: Error modal
+     Row layout: icon column beside a content column. cn-modal-content stays
+     a plain block by default (see Modal.css), so it's safe to turn into a
+     row here without fighting a hardcoded flex-direction. */
+  .cn-error-modal {
+    @apply flex flex-row gap-gds-3;
+  }
+
+  /* items-start keeps the icon pinned to the top of the row rather than
+     stretching/centering across the full modal height (including the
+     footer), justify-center centres it within its own column. */
+  .cn-error-modal-icon {
+    @apply flex shrink-0 items-start justify-center text-error;
+  }
+
+  /* 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. */
+  .cn-error-modal-body {
+    @apply flex min-w-0 flex-col;
+  }
+
+  /* Scoped to the summary list only (not the copy button/hint below it), an
+     arbitrary-length details string (e.g. a dumped API error body) or a long
+     digest can otherwise push the whole modal to an unreasonable height,
+     rather than just scrolling internally. */
+  .cn-error-modal-details {
+    @apply max-h-60 overflow-y-auto;
+  }
+}

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

@@ -0,0 +1,101 @@
+import { useState } from 'react';
+
+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',
+  component: ErrorModal,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A Modal preset for reporting an error: an alert icon beside the message, with an optional expandable "Technical information" section (message, details, digest, and a copy-to-clipboard button that includes the stack trace when available) driven entirely by the `error` prop. Shares its error-describing logic with ErrorFallback via `getErrorDisplayInfo`/`formatErrorForClipboard`, so both surfaces describe the same error the same way.',
+      },
+    },
+  },
+  argTypes: {
+    children: { control: false },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ErrorModal>;
+
+export const Default: Story = {
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Trigger error</Button>
+
+        <ErrorModal
+          open={open}
+          onOpenChange={setOpen}
+          error={new Error('Failed to fetch sampling points')}
+        >
+          <Paragraph>An error occurred while fetching sampling points.</Paragraph>
+        </ErrorModal>
+      </>
+    );
+  },
+};
+
+export const WithApiError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'ApiError additionally carries `details` and a `digest`, both shown in the technical information section and included in the copied text.',
+      },
+    },
+  },
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Trigger error</Button>
+
+        <ErrorModal
+          open={open}
+          onOpenChange={setOpen}
+          error={ApiError.internalServerError('The upstream sampling points service timed out')}
+        >
+          <Paragraph>An error occurred while fetching sampling points.</Paragraph>
+        </ErrorModal>
+      </>
+    );
+  },
+};
+
+export const WithoutError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'No `error` prop, no technical information section is rendered, just the message and a close button.',
+      },
+    },
+  },
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Trigger error</Button>
+
+        <ErrorModal open={open} onOpenChange={setOpen}>
+          <Paragraph>Something went wrong. Try again in a few minutes.</Paragraph>
+        </ErrorModal>
+      </>
+    );
+  },
+};