@tpzdsp/next-toolkit 2.5.1 → 3.0.0

package/src/components/Layout/PageShell/PageShell.css

@@ -0,0 +1,42 @@
+@layer components {
+  /* MARK: PageShell */
+  .cn-page-shell {
+    /* Clips the few extra pixels Hero's full-bleed breakout can introduce
+       (100vw includes the scrollbar gutter in browsers that reserve space
+       for it), rather than a real horizontal scrollbar appearing. Nothing
+       meaningful is ever clipped, the breakout is already sized to reach
+       exactly the viewport edges. */
+    @apply flex flex-col overflow-x-clip;
+
+    & > header,
+    & > footer {
+      @apply shrink-0;
+    }
+
+    & > main {
+      @apply flex-1;
+    }
+  }
+
+  /* MARK: Static
+     Normal document scroll: main grows to fill any leftover viewport height,
+     footer sits right after it in flow, the whole page scrolls together once
+     content overflows. */
+  .cn-page-shell-variant-static {
+    @apply min-h-screen;
+  }
+
+  /* MARK: Scroll-locked
+     App-shell style: the page is pinned to the viewport height and never
+     scrolls itself, header and footer stay permanently visible, main gets its
+     own scrollbar. min-h-0 overrides the flex item default of
+     min-height: auto, which otherwise refuses to let main shrink below its
+     content size and silently breaks the internal scroll. */
+  .cn-page-shell-variant-scroll-locked {
+    @apply h-screen overflow-hidden;
+
+    & > main {
+      @apply min-h-0 overflow-y-auto;
+    }
+  }
+}

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

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { PageShell } from './PageShell';
+import type { NavLink } from '../../../types/navigation';
+import { Footer } from '../../Footer/Footer';
+import { Header } from '../../Header/Header';
+import { Heading } from '../../Heading/Heading';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { HeadingGroup } from '../HeadingGroup/HeadingGroup';
+import { MainWrapper } from '../MainWrapper/MainWrapper';
+import { ParagraphGroup } from '../ParagraphGroup/ParagraphGroup';
+
+const navLinks: NavLink[] = [
+  { label: 'Home', url: '/', openInNewTab: false },
+  { label: 'API', url: '/api-docs', openInNewTab: false },
+];
+
+const headerArgs = {
+  dspUrl: 'https://environment.data.gov.uk',
+  appName: 'Wetlands Inventory',
+  navLinks,
+  credentials: null,
+};
+
+const LongContent = () => (
+  <HeadingGroup>
+    <Heading level="h1">Water quality</Heading>
+
+    <ParagraphGroup>
+      {Array.from({ length: 20 }, (_, index) => (
+        <Paragraph key={`paragraph-${index}`}>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
+          ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+          ullamco laboris nisi ut aliquip ex ea commodo consequat.
+        </Paragraph>
+      ))}
+    </ParagraphGroup>
+  </HeadingGroup>
+);
+
+const meta: Meta<typeof PageShell> = {
+  title: 'Components/Layout/PageShell',
+  component: PageShell,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Divides the page into header/main/footer. Compose it directly with Header, MainWrapper, and Footer, PageShell sizes them by tag (`> header`, `> main`, `> footer`), no slot props needed.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['static', 'scroll-locked'],
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof PageShell>;
+
+export const Static: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'For static, document-like pages. Main grows to fill any leftover viewport height, but the whole page scrolls together once content overflows, scroll down to see the footer follow the content rather than staying pinned.',
+      },
+    },
+  },
+  render: () => (
+    <PageShell variant="static">
+      <Header {...headerArgs} />
+
+      <MainWrapper>
+        <LongContent />
+      </MainWrapper>
+
+      <Footer />
+    </PageShell>
+  ),
+};
+
+export const ScrollLocked: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'For interactive, app-like pages (e.g. maps). Header and footer stay permanently visible, main gets its own internal scrollbar instead of the page scrolling. Scroll within the main content area to see it, the header and footer never move.',
+      },
+    },
+  },
+  render: () => (
+    <PageShell variant="scroll-locked">
+      <Header {...headerArgs} />
+
+      <MainWrapper>
+        <LongContent />
+      </MainWrapper>
+
+      <Footer />
+    </PageShell>
+  ),
+};

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

@@ -0,0 +1,31 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../../utils/components';
+
+const PAGE_SHELL_VARIANTS = {
+  static: 'cn-page-shell-variant-static',
+  'scroll-locked': 'cn-page-shell-variant-scroll-locked',
+} as const;
+
+export type PageShellVariant = keyof typeof PAGE_SHELL_VARIANTS;
+
+export type PageShellProps = ComponentProps<'div'> & {
+  variant?: PageShellVariant;
+};
+
+/**
+ * Divides the page into header/main/footer using tag selectors (`> header`,
+ * `> main`, `> footer`), so it composes directly with Header, MainWrapper,
+ * and Footer with no slot props needed:
+ * `<PageShell variant="static"><Header /><MainWrapper>...</MainWrapper><Footer /></PageShell>`
+ */
+export const PageShell = ({ variant = 'static', className, ...props }: PageShellProps) => {
+  return (
+    <div
+      data-slot="page-shell"
+      data-variant={variant}
+      className={cn('cn-page-shell', PAGE_SHELL_VARIANTS[variant], className)}
+      {...props}
+    />
+  );
+};

package/src/components/Layout/ParagraphGroup/ParagraphGroup.css

@@ -0,0 +1,5 @@
+@layer components {
+  .cn-paragraph-group {
+    @apply flex flex-col gap-gds-1 @sm:gap-gds-2;
+  }
+}

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

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ParagraphGroup } from './ParagraphGroup';
+import { Paragraph } from '../../Paragraph/Paragraph';
+
+const meta: Meta<typeof ParagraphGroup> = {
+  title: 'Components/Layout/ParagraphGroup',
+  component: ParagraphGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use a ParagraphGroup to group a heading and paragraph with responsive spacing.',
+      },
+    },
+  },
+  argTypes: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ParagraphGroup>;
+
+export const Default: Story = {
+  render: () => (
+    <ParagraphGroup>
+      <Paragraph>Hello from paragraph one.</Paragraph>
+
+      <Paragraph>Hello from paragraph two.</Paragraph>
+
+      <Paragraph>Hello from paragraph three.</Paragraph>
+    </ParagraphGroup>
+  ),
+};

package/src/components/Layout/ParagraphGroup/ParagraphGroup.tsx

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../../utils/components';
+
+export type ParagraphGroupProps = ComponentProps<'div'>;
+
+export const ParagraphGroup = ({ className, ...props }: ParagraphGroupProps) => {
+  return <div className={cn('cn-paragraph-group', className)} {...props} />;
+};

package/src/components/Layout/Stack/Stack.css

@@ -0,0 +1,29 @@
+@layer components {
+  /* MARK: Stack
+     Generic vertical rhythm between arbitrary sibling blocks (HeadingGroup,
+     ParagraphGroup, ButtonGroup, Card, etc.) as a plain flex+gap column.
+     Unlike the *Group components, Stack has no opinion on what it contains,
+     it only owns the gap between its direct children. */
+  /* Deliberately relies on the flex default of align-items: stretch: most
+     things stacked are block-level content (Card, ParagraphGroup, sections)
+     that's meant to fill the width anyway, matching normal block flow.
+     A lone element that shouldn't stretch (a bare Button) should be wrapped
+     in something row-based (e.g. ButtonGroup) rather than Stack opting every
+     child out by default, that made the common case need w-full everywhere
+     for the sake of the rarer one. */
+  .cn-stack {
+    @apply flex flex-col;
+  }
+
+  .cn-stack-gap-sm {
+    @apply gap-gds-4 @sm:gap-gds-5;
+  }
+
+  .cn-stack-gap-base {
+    @apply gap-gds-6 @sm:gap-gds-7;
+  }
+
+  .cn-stack-gap-lg {
+    @apply gap-gds-8 @sm:gap-gds-9;
+  }
+}

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

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Stack } from './Stack';
+import { Button } from '../../Button/Button';
+import { Heading } from '../../Heading/Heading';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { ButtonGroup } from '../ButtonGroup/ButtonGroup';
+import { HeadingGroup } from '../HeadingGroup/HeadingGroup';
+import { ParagraphGroup } from '../ParagraphGroup/ParagraphGroup';
+
+const meta: Meta<typeof Stack> = {
+  title: 'Components/Layout/Stack',
+  component: Stack,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Use Stack for consistent vertical rhythm between sibling blocks that have nothing else in common, e.g. a HeadingGroup followed by a ButtonGroup. The *Group components (HeadingGroup, ParagraphGroup) only space their own children, they intentionally have no opinion on the gap to whatever comes before or after them, that gap is Stack's job.",
+      },
+    },
+  },
+  argTypes: {
+    gap: {
+      control: { type: 'radio' },
+      options: ['sm', 'base', 'lg'],
+    },
+  },
+  args: {
+    gap: 'base',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Stack>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Stack {...args}>
+      <HeadingGroup>
+        <Heading level="h2">Water quality</Heading>
+
+        <Paragraph>Explore water quality sample data collected across England.</Paragraph>
+      </HeadingGroup>
+
+      <ParagraphGroup>
+        <Paragraph>This service lets you search, filter, and download the data.</Paragraph>
+
+        <Paragraph>You&apos;ll need to sign in to save a search for later.</Paragraph>
+      </ParagraphGroup>
+
+      <ButtonGroup>
+        <Button appearance="primary">Start now</Button>
+
+        <Button appearance="secondary">Find out more</Button>
+      </ButtonGroup>
+    </Stack>
+  ),
+};
+
+export const Gaps: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'The three gap sizes side by side, each Stack contains the same two paragraphs.',
+      },
+    },
+  },
+  render: () => (
+    <Stack gap="lg">
+      {(['sm', 'base', 'lg'] as const).map((gap) => (
+        <Stack key={gap} gap={gap} className="rounded-sm border border-divider p-gds-3">
+          <Paragraph className="text-sm text-body-secondary">gap=&quot;{gap}&quot;</Paragraph>
+
+          <Paragraph>First block</Paragraph>
+
+          <Paragraph>Second block</Paragraph>
+        </Stack>
+      ))}
+    </Stack>
+  ),
+};

package/src/components/Layout/Stack/Stack.tsx

@@ -0,0 +1,19 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../../utils/components';
+
+const STACK_GAPS = {
+  sm: 'cn-stack-gap-sm',
+  base: 'cn-stack-gap-base',
+  lg: 'cn-stack-gap-lg',
+} as const;
+
+export type StackGap = keyof typeof STACK_GAPS;
+
+export type StackProps = ComponentProps<'div'> & {
+  gap?: StackGap;
+};
+
+export const Stack = ({ gap = 'base', className, ...props }: StackProps) => {
+  return <div className={cn('cn-stack', STACK_GAPS[gap], className)} {...props} />;
+};

package/src/components/Layout/WidthContainer/WidthContainer.css

@@ -0,0 +1,17 @@
+@layer components {
+  /* MARK: WidthContainer
+     GDS "width container" object: centred, padded, capped at max-w-page
+     content width. Duplicates rather than @apply's the upstream
+     @tpzdsp/eslint-config-dsp .page-wrapper class, that class lives in
+     @layer components (not @utility) in an external package, and Tailwind
+     only guarantees @apply works across files for @utility-defined classes.
+     Also a container-query provider (@container): its own px-* padding still
+     responds to the viewport (it IS the viewport-ish boundary at the top of
+     the page), but anything nested inside it (Stack, ParagraphGroup,
+     HeadingGroup) should size against this element's actual content width,
+     not the viewport, so their spacing stays correct if WidthContainer is
+     ever nested somewhere narrower than the page. */
+  .cn-width-container {
+    @apply w-full max-w-page mx-auto px-gds-3 sm:px-gds-6 @container h-full;
+  }
+}

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

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { WidthContainer } from './WidthContainer';
+import { Paragraph } from '../../Paragraph/Paragraph';
+import { ParagraphGroup } from '../ParagraphGroup/ParagraphGroup';
+
+const meta: Meta<typeof WidthContainer> = {
+  title: 'Components/Layout/WidthContainer',
+  component: WidthContainer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use a WidthContainer to place content in a single column centered on the page, as per GDS guidelines. View the individual stories on a wide screen to see what the container does.',
+      },
+    },
+  },
+  argTypes: {},
+  args: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof WidthContainer>;
+
+export const RestrictedWidth: Story = {
+  render: () => (
+    <WidthContainer>
+      <ParagraphGroup>
+        <Paragraph>I am content with a restricted width</Paragraph>
+
+        <Paragraph>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
+          ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+          ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
+          reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+        </Paragraph>
+      </ParagraphGroup>
+    </WidthContainer>
+  ),
+};
+
+export const ColouredBackground: Story = {
+  render: () => (
+    <WidthContainer className="bg-accent">
+      <ParagraphGroup>
+        <Paragraph className="text-on-accent">I am content with a restricted width</Paragraph>
+
+        <Paragraph className="text-on-accent">
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
+          ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+          ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
+          reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+        </Paragraph>
+      </ParagraphGroup>
+    </WidthContainer>
+  ),
+};

package/src/components/Layout/WidthContainer/WidthContainer.tsx

@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../../utils/components';
+
+export type WidthContainerProps = ComponentProps<'div'>;
+
+export const WidthContainer = ({ className, children, ...props }: WidthContainerProps) => {
+  return (
+    <div className={cn('w-full', className)} {...props}>
+      <div className="cn-width-container">{children}</div>
+    </div>
+  );
+};

package/src/components/Legend/Legend.css

@@ -0,0 +1,95 @@
+@layer components {
+  /* MARK: Panel */
+  .cn-legend-panel {
+    @apply flex flex-col gap-gds-2;
+  }
+
+  /* MARK: Title
+     Matches cn-label's own sizing/colour (text-lg text-body, not bold, no
+     margin) rather than its own values, a legend title plays the same
+     role for a group of controls that a Label plays for one. */
+  .cn-legend-title {
+    @apply m-0 text-lg text-body;
+  }
+
+  /* MARK: Items list */
+  .cn-legend-items {
+    @apply m-0 p-0 list-none flex flex-col gap-gds-1;
+  }
+
+  /* MARK: Item */
+  .cn-legend-item {
+    @apply flex items-center gap-gds-2 text-sm;
+  }
+
+  /* MARK: Option (interactive row)
+     Ghost-button base via cn-button, mirroring cn-layer-switcher-option's
+     interaction states so the two selectable-list patterns stay consistent. */
+  .cn-legend-option {
+    @apply cn-button flex items-center gap-gds-2 p-gds-1 text-sm text-left bg-transparent text-body
+      w-full;
+
+    &:focus {
+      @apply outline-none;
+    }
+
+    &:hover:not(:disabled) {
+      @apply bg-transparent;
+    }
+
+    &:focus:not(:active):not(:hover) {
+      @apply shadow-none;
+    }
+
+    &:active:not(:disabled) {
+      @apply bg-black/5 transform-none;
+    }
+  }
+
+  /* MARK: Option selected state */
+  .cn-legend-option[aria-checked='true'] {
+    @apply bg-accent text-on-accent;
+
+    &:focus:not(:active):not(:hover) {
+      @apply bg-accent text-on-accent;
+    }
+
+    &:hover:not(:disabled) {
+      @apply bg-focus text-on-focus;
+    }
+  }
+
+  /* MARK: Dot
+     Inherits the cn-legend-dot utility from LegendSelect.css which adds a
+     white outline ring when the dot is inside a selected react-select option.
+     No additional styling needed here, colour is set inline via style prop. */
+  .cn-legend-dot {
+    @apply size-3 shrink-0 rounded-full;
+  }
+
+  .cn-legend-option[aria-checked='true'] .cn-legend-dot {
+    outline: var(--focus-ring-width) solid var(--color-panel);
+  }
+
+  /* MARK: Skeleton
+     Reuses cn-legend-panel/title/items/item directly for the structural
+     wrappers, dot and label bars get their own sizing so a real LegendPanel
+     swaps in without any layout shift. */
+  .cn-legend-skeleton-title {
+    @apply h-4 w-20;
+  }
+
+  .cn-legend-skeleton-dot {
+    @apply size-3 shrink-0 rounded-full;
+  }
+
+  /* h-4 (1rem) undershoots text-sm's real rendered height (0.875rem font
+     size * 1.5 line-height = 1.3125rem ≈ 21px), a 5px-per-row shortfall
+     that compounds into the whole list reading visibly shorter than the
+     real, non-skeleton items once loaded, most noticeable in interactive
+     mode where cn-legend-option's own padding otherwise makes each row
+     tall enough for the gap to stand out. */
+  .cn-legend-skeleton-label {
+    @apply h-5.25 w-24;
+  }
+}

package/src/components/Legend/Legend.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Legend } from './Legend';
+import type { LegendOption } from './Legend';
+
+const HABITAT_ITEMS: LegendOption[] = [
+  { value: 'bogs', label: 'Bogs', color: '#3b82f6' },
+  { value: 'dwarf-shrub', label: 'Dwarf shrub heath', color: '#14b8a6' },
+  { value: 'fens', label: 'Fens, marsh & swamp', color: '#ec4899' },
+  { value: 'littoral', label: 'Littoral sediments', color: '#f97316' },
+  { value: 'neutral', label: 'Neutral grassland', color: '#a855f7' },
+  { value: 'sublittoral', label: 'Sublittoral sediment', color: '#22c55e' },
+  { value: 'supralittoral-rock', label: 'Supralittoral Rock', color: '#eab308' },
+  { value: 'supralittoral-sed', label: 'Supralittoral sediment', color: '#6b7280' },
+];
+
+const meta: Meta<typeof Legend> = {
+  title: 'Components/Legend',
+  component: Legend,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Icon button that opens a popover showing a map legend. Intended for use inside a map toolbar alongside other panel-appearance controls.
+
+Shares the \`LegendOption\` type (\`value\`, \`label\`, \`color\`) with \`LegendSelect\`, so the same dataset drives both the filter control and the legend.
+
+**Props:**
+- \`items\`: array of \`LegendOption\` objects
+- \`title\`: heading shown at the top of the popover (default: \`"Legend"\`)
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Legend>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="flex items-start">
+      <Legend items={HABITAT_ITEMS} />
+    </div>
+  ),
+};
+
+export const CustomTitle: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Pass a custom `title` to override the default "Legend" heading.' },
+    },
+  },
+  render: () => (
+    <div className="flex items-start">
+      <Legend items={HABITAT_ITEMS} title="Habitat types" />
+    </div>
+  ),
+};
+
+export const FewItems: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Compact legend with only a handful of categories.' },
+    },
+  },
+  render: () => (
+    <div className="flex items-start">
+      <Legend
+        items={[
+          { value: 'low', label: 'Low risk', color: '#22c55e' },
+          { value: 'medium', label: 'Medium risk', color: '#eab308' },
+          { value: 'high', label: 'High risk', color: '#ef4444' },
+        ]}
+        title="Flood risk"
+      />
+    </div>
+  ),
+};

package/src/components/Legend/Legend.tsx

@@ -0,0 +1,32 @@
+import type { ComponentProps } from 'react';
+
+import { LuList } from 'react-icons/lu';
+
+import { LegendPanel } from './LegendPanel';
+import type { LegendOption } from './LegendPanel';
+import { Button } from '../Button/Button';
+import { Popover, PopoverContent, PopoverTrigger } from '../Popover/Popover';
+
+export type { LegendOption };
+
+export type LegendProps = Omit<
+  ComponentProps<typeof Button>,
+  'variant' | 'appearance' | 'children'
+> & {
+  items: LegendOption[];
+  title?: string;
+};
+
+export const Legend = ({ items, title = 'Legend', ...props }: LegendProps) => (
+  <Popover>
+    <PopoverTrigger asChild>
+      <Button variant="icon" appearance="panel" aria-label={title} {...props}>
+        <LuList aria-hidden />
+      </Button>
+    </PopoverTrigger>
+
+    <PopoverContent side="left" align="start" sideOffset={8} className="w-52">
+      <LegendPanel items={items} title={title} />
+    </PopoverContent>
+  </Popover>
+);