@tpzdsp/next-toolkit 2.5.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "2.5.1",
+  "version": "3.0.0",
   "description": "A reusable React component library for Next.js applications",
   "packageManager": "pnpm@11.5.3",
   "engines": {
@@ -132,17 +132,18 @@
     "@commitlint/config-conventional": "^21.1.0",
     "@commitlint/types": "^21.1.0",
     "@floating-ui/react": "^0.27.17",
-    "@storybook/addon-docs": "10.3.5",
-    "@storybook/addon-links": "10.3.5",
-    "@storybook/addon-onboarding": "10.3.5",
-    "@storybook/react-vite": "10.3.5",
-    "@tailwindcss/typography": "^0.5.16",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/addon-links": "^10.4.6",
+    "@storybook/addon-onboarding": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
+    "@tailwindcss/postcss": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.1",
     "@tanstack/react-query": "^5.90.19",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.6.4",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@tpzdsp/eslint-config-dsp": "^4.0.0",
+    "@tpzdsp/eslint-config-dsp": "^5.0.0",
     "@turf/turf": "^7.2.0",
     "@types/geojson": "^7946.0.16",
     "@types/jsonwebtoken": "^9.0.10",
@@ -152,12 +153,12 @@
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/coverage-v8": "^4.0.17",
     "@vitest/eslint-plugin": "^1.3.4",
-    "autoprefixer": "^10.4.21",
     "buffer": "^6.0.3",
+    "class-variance-authority": "^0.7.1",
     "crypto-browserify": "^3.12.1",
     "date-fns": "^4.1.0",
     "eslint": "^9.39.4",
-    "eslint-plugin-storybook": "10.3.5",
+    "eslint-plugin-storybook": "^10.4.6",
     "focus-trap": "^8.0.1",
     "focus-trap-react": "^12.0.0",
     "geojson": "^0.5.0",
@@ -168,22 +169,24 @@
     "next": "^16.1.4",
     "ol": "^10.6.1",
     "ol-mapbox-style": "^13.0.1",
-    "postcss": "^8.5.6",
+    "postcss": "^8.5.15",
     "prettier": "^3.8.1",
     "process": "^0.11.10",
     "proj4": "^2.19.10",
+    "radix-ui": "^1.6.0",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "react-error-boundary": "^6.0.0",
     "react-icons": "^5.5.0",
+    "react-resizable-panels": "^4.12.0",
     "react-select": "^5.10.2",
     "react-select-event": "^5.5.1",
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "semantic-release": "^25.0.2",
-    "storybook": "10.3.5",
+    "storybook": "^10.4.6",
     "stream-browserify": "^3.0.0",
     "tailwind-merge": "^3.4.0",
-    "tailwindcss": "^3.4.16",
+    "tailwindcss": "^4.3.1",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.35.1",
     "util": "^0.12.5",
@@ -197,6 +200,7 @@
     "@floating-ui/react": "^0.27",
     "@tanstack/react-query": "^5",
     "@turf/turf": "^7",
+    "class-variance-authority": "^0.7.1",
     "date-fns": "^4",
     "focus-trap": "^8",
     "focus-trap-react": "^12",
@@ -206,10 +210,12 @@
     "ol": "^10",
     "ol-mapbox-style": "^13",
     "proj4": "^2",
+    "radix-ui": "^1.6.0",
     "react": "^19",
     "react-dom": "^19",
     "react-error-boundary": "^6",
     "react-icons": "^5",
+    "react-resizable-panels": "^4",
     "react-select": "^5",
     "zod": "^4"
   },
@@ -250,6 +256,9 @@
     "proj4": {
       "optional": true
     },
+    "react-resizable-panels": {
+      "optional": true
+    },
     "react-select": {
       "optional": true
     },

package/src/assets/styles/globals.css

@@ -1,97 +1,77 @@
-/* Global CSS for the component library */
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import '@tpzdsp/eslint-config-dsp/tailwindcss';
 
-/**
- * Accessibility: Respect user's motion preferences
- *
- * Many users experience discomfort or motion sickness from animations.
- * This disables transitions and animations when the user has enabled
- * "Reduce motion" in their operating system settings.
- *
- * Using 0.01ms instead of 0s ensures animation events still fire
- * (which some JavaScript might depend on), but the effect is instant.
- */
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
-  }
-}
+@import './utils.css';
+@import '../../components/Button/Button.css';
+@import '../../components/InfoBox/InfoBox.css';
+@import '../../components/Layout/ButtonGroup/ButtonGroup.css';
+@import '../../components/StartButton/StartButton.css';
+@import '../../components/ButtonLink/ButtonLink.css';
+@import '../../components/LinkButton/LinkButton.css';
+@import '../../components/Fieldset/Fieldset.css';
+@import '../../components/Label/Label.css';
+@import '../../components/Link/Link.css';
+@import '../../components/ExternalLink/ExternalLink.css';
+@import '../../components/Modal/Modal.css';
+@import '../../components/ErrorModal/ErrorModal.css';
+@import '../../components/Separator/Separator.css';
+@import '../../components/Checkbox/Checkbox.css';
+@import '../../components/Radio/Radio.css';
+@import '../../components/Form/FormGroup.css';
+@import '../../components/Input/Input.css';
+@import '../../components/DateInput/DateInput.css';
+@import '../../components/InputGroup/InputGroup.css';
+@import '../../components/PasswordInput/PasswordInput.css';
+@import '../../components/Textarea/Textarea.css';
+@import '../../components/TextareaCount/TextareaCount.css';
+@import '../../components/FileUpload/FileUpload.css';
+@import '../../components/Tag/Tag.css';
+@import '../../components/PhaseBanner/PhaseBanner.css';
+@import '../../components/Alert/Alert.css';
+@import '../../components/Chip/Chip.css';
+@import '../../components/Select/Select.css';
+@import '../../components/LegendSelect/LegendSelect.css';
+@import '../../components/Accordion/Accordion.css';
+@import '../../components/Skeleton/Skeleton.css';
+@import '../../components/Spinner/Spinner.css';
+@import '../../components/LoadingBox/LoadingBox.css';
+@import '../../components/Heading/Heading.css';
+@import '../../components/Paragraph/Paragraph.css';
+@import '../../components/InsetText/InsetText.css';
+@import '../../components/Tooltip/Tooltip.css';
+@import '../../components/Popover/Popover.css';
+@import '../../components/Dropdown/Dropdown.css';
+@import '../../components/Tabs/Tabs.css';
+@import '../../components/Sidebar/Sidebar.css';
+@import '../../components/SkipLink/SkipLink.css';
+@import '../../components/BackToTop/BackToTop.css';
+@import '../../components/BackLink/BackLink.css';
+@import '../../components/Breadcrumb/Breadcrumb.css';
+@import '../../components/Keyboard/Keyboard.css';
+@import '../../components/ScrollArea/ScrollArea.css';
+@import '../../components/ErrorText/ErrorText.css';
+@import '../../components/HintText/HintText.css';
+@import '../../components/Details/Details.css';
+@import '../../components/Resizable/Resizable.css';
+@import '../../components/WarningText/WarningText.css';
+@import '../../components/Card/Card.css';
+@import '../../components/CardGroup/CardGroup.css';
+@import '../../components/CookieBanner/CookieBanner.css';
+@import '../../components/NoScriptBanner/NoScriptBanner.css';
+@import '../../components/SummaryList/SummaryList.css';
+@import '../../components/List/List.css';
+@import '../../components/LinkList/LinkList.css';
+@import '../../components/LayerSwitcher/LayerSwitcher.css';
+@import '../../components/Legend/Legend.css';
+@import '../../components/Layout/HeadingGroup/HeadingGroup.css';
+@import '../../components/Layout/ParagraphGroup/ParagraphGroup.css';
+@import '../../components/Layout/Stack/Stack.css';
+@import '../../components/Hero/Hero.css';
+@import '../../components/Dropdown/Dropdown.css';
+@import '../../components/Layout/WidthContainer/WidthContainer.css';
+@import '../../components/Layout/MainWrapper/MainWrapper.css';
+@import '../../components/Layout/PageShell/PageShell.css';
 
-/* Custom font faces */
-@layer base {
-  /* Add your custom font faces here */
-  @font-face {
-    font-family: 'GDSTransport';
-    src: url('../fonts/gds-light-w2-v2.woff2') format('woff2');
-    font-weight: 400;
-    font-style: normal;
-  }
-
-  @font-face {
-    font-family: 'GDSTransport';
-    src: url('../fonts/gds-bold-w2-v2.woff2') format('woff2');
-    font-weight: 700;
-    font-style: normal;
-  }
-}
-
-/* Component-specific styles */
-@layer components {
-  .focus-yellow {
-    @apply focus:border-focus focus:outline focus:outline-2 focus:outline-focus;
-  }
-
-  .library-button {
-    @apply inline-flex items-center justify-center rounded-md font-medium transition-colors;
-  }
-
-  .library-card {
-    @apply rounded-lg border border-gray-200 bg-white shadow-sm;
-  }
-
-  /* Button Styles */
-  .button {
-    --border: theme('borderWidth.form');
-    --shadow: var(--border);
-
-    padding: calc(theme('spacing.2') - var(--border)) theme('spacing.2')
-      calc(theme('spacing.2') - var(--border) - calc(var(--shadow) / 2));
-
-    box-shadow: 0 var(--shadow) 0 var(--tw-shadow-color);
-
-    &:focus:not(:active):not(:hover) {
-      box-shadow: 0 var(--shadow) 0 var(--tw-shadow-color);
-    }
-
-    &::before {
-      @apply absolute block content-[""];
-
-      top: calc(var(--border) * -1);
-      left: calc(var(--border) * -1);
-      right: calc(var(--border) * -1);
-      bottom: calc(calc(var(--border) + calc(var(--shadow) / 2)) * -1);
-    }
-
-    &:active::before {
-      top: calc(calc(var(--border) + var(--shadow)) * -1);
-    }
-  }
-
-  .input-height {
-    @apply h-[38px];
-  }
-}
-
-/* Utilities */
-@layer utilities {
-  .text-balance {
-    text-wrap: balance;
-  }
-}
+/* @source must follow all @imports as CSS drops imports that appear after any
+   non-import rule. This tells @tailwindcss/postcss to scan component source
+   files so utility classes used only in stories are always generated. */
+@source "../../**/*.{tsx,ts,jsx,js}";

package/src/assets/styles/ol.css

@@ -16,12 +16,19 @@
  * 3. Position the control container with absolute positioning
  */
 
+/* Values mirror cn-button-appearance-panel (Button.css) and the tokens it's
+   built from (utils.css's `panel` utility, --border-width-form,
+   --color-focus, --color-on-focus, --color-muted), this file can't reach
+   those directly (see the .map-fullscreen comment below for why), so they're
+   hardcoded here and need to stay in sync by hand. */
 :root {
-  --focus-color: #ffdd00;
+  --focus-color: #ffdd00; /* --color-focus */
   --focus-outline-color: #ffbf47;
-  --control-bg: #fff;
+  --control-bg: #fff; /* --color-panel */
   --control-border: #505a5f;
-  --control-text: #0b0c0c;
+  --control-text: #0b0c0c; /* --color-on-focus, also matches control-border-color at rest */
+  --control-border-color: #0b0c0c; /* --color-panel-border */
+  --control-active-bg: #cecece; /* --color-muted, cn-button-appearance-panel's :active background */
   --control-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
 }
 
@@ -34,7 +41,7 @@
   width: 40px !important;
   height: 40px !important;
   outline: none !important;
-  border: 2px solid #0b0c0c !important;
+  border: 2px solid var(--control-border-color) !important;
 }
 
 .ol-btn {
@@ -65,18 +72,27 @@
   margin: 0 auto;
 }
 
-.ol-btn:hover,
+/* cn-button-appearance-panel has no :hover override of its own (panel
+   buttons don't highlight on hover), only :active and :focus change. */
 .ol-btn:active {
-  background: var(--focus-color) !important;
+  background: var(--control-active-bg) !important;
 }
 
 .ol-btn:focus,
 .ol-btn:focus-visible {
-  border-color: var(--focus-outline-color) !important;
-  background: var(--focus-color) !important;
+  border-color: var(--focus-color) !important;
+  box-shadow: inset 0 0 0 2px var(--focus-color);
   z-index: 2;
 }
 
+/* Isolated focus (not hover/active): solid yellow fill, matching
+   cn-button's own base &:focus:not(:active):not(:hover) rule. */
+.ol-btn:focus:not(:hover):not(:active),
+.ol-btn:focus-visible:not(:hover):not(:active) {
+  background: var(--focus-color) !important;
+  color: var(--control-text) !important;
+}
+
 .ol-btn:disabled {
   opacity: 0.4;
   cursor: not-allowed;
@@ -94,7 +110,13 @@
   z-index: 2;
 }
 
-/* Zoom control container */
+/* Zoom control container. Buttons stack with shared, joined borders rather
+   than each keeping its own on every side, the same technique
+   cn-button-group's own data-compressed variant uses for adjacent
+   appearance="panel" icon buttons (see ButtonGroup.css): overlap by one
+   border-width so touching edges merge into a single line, and raise the
+   focused button's z-index so its border/ring never gets clipped under a
+   neighbour. */
 .ol-zoom {
   top: 1.5rem;
   right: 1rem;
@@ -104,6 +126,10 @@
   z-index: 10;
 }
 
+.ol-zoom button + button {
+  margin-top: -2px !important; /* -1 * --border-width-form */
+}
+
 /* Apply base button styling to zoom buttons */
 .ol-zoom button,
 .ol-zoom button:hover,
@@ -113,7 +139,7 @@
   width: 40px !important;
   height: 40px !important;
   outline: none !important;
-  border: 2px solid #0b0c0c !important;
+  border: 2px solid var(--control-border-color) !important;
 }
 
 .ol-zoom button {
@@ -135,18 +161,24 @@
   position: relative;
 }
 
-.ol-zoom button:hover,
+/* cn-button-appearance-panel has no :hover override of its own. */
 .ol-zoom button:active {
-  background: var(--focus-color) !important;
+  background: var(--control-active-bg) !important;
 }
 
 .ol-zoom button:focus,
 .ol-zoom button:focus-visible {
-  border-color: var(--focus-outline-color) !important;
-  background: var(--focus-color) !important;
+  border-color: var(--focus-color) !important;
+  box-shadow: inset 0 0 0 2px var(--focus-color);
   z-index: 2;
 }
 
+.ol-zoom button:focus:not(:hover):not(:active),
+.ol-zoom button:focus-visible:not(:hover):not(:active) {
+  background: var(--focus-color) !important;
+  color: var(--control-text) !important;
+}
+
 /* Override default zoom button text with SVG icons */
 .ol-zoom-in::before,
 .ol-zoom-out::before {
@@ -183,7 +215,16 @@
   right: 1rem;
 }
 
-/* Full screen mode for map container */
+/* Full screen mode for map container.
+   z-index matches cn-z-overlay (see utils.css) rather than OpenLayers' own
+   plain 9999, this file can't reliably reach that utility itself (this
+   stylesheet ships as a separate package export, ./styles/ol, imported
+   independently of the Tailwind-processed component CSS, so @apply isn't
+   guaranteed to resolve here), but the numeric value still needs to stay in
+   sync with it: full screen is meant to cover literally everything on the
+   page, including cn-z-top elements like a resizable handle, and cn-z-top
+   (99999) already sits above OpenLayers' own layers, so matching it (or
+   less) would put full screen mode back underneath them. */
 .map-fullscreen {
   position: fixed !important;
   top: 0 !important;
@@ -192,7 +233,7 @@
   bottom: 0 !important;
   width: 100vw !important;
   height: 100vh !important;
-  z-index: 9999 !important;
+  z-index: 999999 !important;
   margin: 0 !important;
   padding: 0 !important;
 }

package/src/assets/styles/utils.css

@@ -0,0 +1,80 @@
+/* Class names starting with `cn` are generally reserved for the toolkit only, although they may show up in intellisense. */
+
+/* This does not follow the `cn-panel` name as we may want to use this outside the toolkit. */
+@utility panel {
+  @apply bg-panel border-form border-solid border-panel-border;
+}
+
+/* MARK: Form field border
+   Shared 2px solid border for form fields (input, textarea, select).
+   No border-radius per GDS. Color can be overridden (e.g. border-error on invalid fields). */
+@utility cn-form-border {
+  @apply border-form border-solid border-divider-input rounded-none;
+}
+
+/* Bordered wash-background swatch — shared base for InputGroup swatches and FileUpload trigger. */
+@utility cn-form-swatch {
+  @apply cn-form-border flex items-center h-10 text-base bg-wash;
+}
+
+/* GDS link underline. Applies to any element that needs link-style text decoration. */
+@utility cn-link-decoration {
+  @apply underline;
+  text-decoration-thickness: max(1px, 0.0625rem);
+  text-underline-offset: 0.1578em;
+}
+
+@utility cn-link-hover-decoration {
+  @apply underline;
+  text-decoration-thickness: max(3px, 0.1875rem, 0.12em);
+  /* Prevent underline gaps around descenders on hover */
+  text-decoration-skip-ink: none;
+  text-decoration-skip: none;
+}
+
+/* Always renders above everything else on the page, including third-party
+   libraries with their own aggressive z-index (e.g. OpenLayers assigns some
+   of its own layers z-index: 9999, see assets/styles/ol.css). Centralised so
+   every "must always be on top" element (resizable handles, tab underlines,
+   ...) shares one place to tune if that ever needs to go even higher. */
+@utility cn-z-top {
+  z-index: 99999;
+}
+
+/* One tier above cn-z-top: floating overlays (Popover, Tooltip, Select's
+   dropdown, Modal) need to render above cn-z-top elements too (e.g. a
+   Popover opened next to a resizable handle), not just above ordinary page
+   content. */
+@utility cn-z-overlay {
+  z-index: 999999;
+}
+
+/* MARK: Icon sizes
+   Canonical icon-button dimensions. Applied by cn-button-size-* and
+   cn-button-link-size-* when data-variant is "icon". */
+
+@utility cn-icon-sm {
+  @apply h-8 w-8 p-1.5;
+}
+
+@utility cn-icon-base {
+  @apply h-10 w-10 p-2;
+}
+
+@utility cn-icon-lg {
+  @apply h-12 w-12 p-2.5;
+}
+
+/* Fallback focus ring for any element not covered by component-specific styles
+   (e.g. Radix primitive roots that render as plain HTML elements).
+   Component-layer focus styles always win — this only fires for unstyled elements. */
+@layer base {
+  :focus-visible {
+    outline: var(--focus-ring-width) solid var(--color-focus);
+  }
+}
+
+html,
+body {
+  @apply text-body text-base;
+}

package/src/components/Accordion/Accordion.css

@@ -0,0 +1,85 @@
+@keyframes accordion-down {
+  from {
+    height: 0;
+  }
+  to {
+    height: var(--radix-accordion-content-height);
+  }
+}
+
+@keyframes accordion-up {
+  from {
+    height: var(--radix-accordion-content-height);
+  }
+  to {
+    height: 0;
+  }
+}
+
+@layer components {
+  /* MARK: Accordion
+     Separator-based design: thin divider lines above the first item and below
+     each item. Works edge-to-edge in a sidebar or as a standalone FAQ section,
+     the trigger padding provides the visual inset for content. */
+  .cn-accordion {
+    @apply w-full border-t border-divider;
+  }
+
+  .cn-accordion-item {
+    @apply border-b border-divider;
+
+    & [data-disabled],
+    &:disabled {
+      @apply opacity-50 cursor-not-allowed;
+    }
+  }
+
+  /* MARK: Trigger */
+  .cn-accordion-trigger {
+    @apply flex w-full items-center justify-between gap-gds-2 p-gds-2 py-gds-2 text-base text-left
+      text-body bg-transparent border-none cursor-pointer;
+
+    &:hover {
+      @apply bg-wash;
+    }
+
+    &:focus-visible {
+      @apply outline-focus;
+    }
+  }
+
+  .cn-accordion-trigger-icon {
+    @apply size-5 shrink-0;
+  }
+
+  .cn-accordion-trigger[data-state='open'] .cn-accordion-trigger-icon {
+    @apply rotate-180;
+  }
+
+  /* MARK: Content
+     bg-surface (a light tint of the accent colour, same treatment
+     CookieBanner uses for its own full-width background) rather than
+     bg-wash: a flat grey reads fine for a small, isolated element like a
+     hover state, but washes out and looks heavier than intended once it's
+     filling an entire content area, especially stacked with other grey
+     (bg-wash/bg-muted) elements inside it. */
+  .cn-accordion-content {
+    @apply overflow-hidden bg-surface;
+
+    &[data-state='open'] {
+      animation: accordion-down 0.15s ease-out;
+    }
+
+    &[data-state='closed'] {
+      animation: accordion-up 0.15s ease-out;
+    }
+
+    &[data-disable-transition] {
+      animation: none;
+    }
+  }
+
+  .cn-accordion-content-inner {
+    @apply p-gds-2 text-base;
+  }
+}