@tpzdsp/next-toolkit 2.5.1 → 3.0.0

package/src/components/SummaryList/SummaryList.css

@@ -0,0 +1,71 @@
+@layer components {
+  /* MARK: Summary list
+     GDS govuk-summary-list pattern. Uses <dl> with <div> row wrappers so
+     the border spans the full width rather than individual cells. Stacks
+     vertically on mobile, flex row on sm+. */
+  .cn-summary-list {
+    @apply m-0 p-0;
+  }
+
+  /* MARK: Row */
+  .cn-summary-list-row {
+    @apply flex flex-col sm:flex-row border-b border-divider gap-y-gds-1 sm:gap-y-0;
+  }
+
+  /* MARK: Key, value, actions, shared padding */
+  .cn-summary-list-key,
+  .cn-summary-list-value,
+  .cn-summary-list-actions {
+    @apply m-0 py-gds-1 sm:py-gds-2;
+  }
+
+  /* Unbreakable text (a single long word, a URL) would otherwise overflow
+     the key's fixed sm:w-[40%] and visually overlap the value next to it,
+     rather than wrapping the way multi-word text already does. Matches
+     GDS's own govuk-summary-list__key/__value, same reasoning. */
+  .cn-summary-list-key,
+  .cn-summary-list-value {
+    @apply wrap-break-word;
+  }
+
+  /* MARK: Key
+     Wider than GDS's own default 30%: this project's keys tend to run
+     longer than GDS's own examples, and at 30% they wrap mid-word often
+     enough to look broken rather than intentional. 40% gives long keys
+     more room to wrap on whole words before running out of width. */
+  .cn-summary-list-key {
+    @apply font-bold sm:w-[40%] sm:flex-none sm:pr-gds-4;
+  }
+
+  /* MARK: Value */
+  .cn-summary-list-value {
+    @apply sm:flex-1;
+  }
+
+  /* MARK: Actions
+     Right-aligned on sm+, stacks below value on mobile. */
+  .cn-summary-list-actions {
+    @apply sm:ml-auto sm:pl-gds-4 sm:text-right;
+  }
+
+  /* MARK: Skeleton
+     Reuses SummaryList/Row/Key/Value directly, only the text content is
+     replaced with bars, so dimensions match exactly once real data loads.
+
+     w-full max-w-* (not a fixed w-*): sm:w-[30%]/sm:flex-1 on the real
+     Key/Value only kick in past the sm *viewport* breakpoint, not however
+     wide this SummaryList's own container actually is, so a narrow
+     container on a wide viewport (a sidebar, a Popup) still lays key/value
+     out side by side there. Real content is text, it wraps to whatever
+     width it's given so this never bites it, but a fixed-width bar can't
+     shrink to fit and overflows into the other column instead. max-w-*
+     keeps the same size as before wherever there's room for it, and only
+     shrinks below that once the row genuinely doesn't have the space. */
+  .cn-summary-list-skeleton-key {
+    @apply h-4 w-full max-w-24;
+  }
+
+  .cn-summary-list-skeleton-value {
+    @apply h-4 w-full max-w-40;
+  }
+}

package/src/components/SummaryList/SummaryList.stories.tsx

@@ -0,0 +1,211 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import {
+  SummaryList,
+  SummaryListActions,
+  SummaryListKey,
+  SummaryListRow,
+  SummaryListValue,
+} from './SummaryList';
+import { Link } from '../Link/Link';
+
+const meta: Meta<typeof SummaryList> = {
+  title: 'Components/SummaryList',
+  component: SummaryList,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+GDS summary list for displaying key–value pairs, most commonly used on "check your answers" pages.
+
+Uses semantic \`<dl>\` / \`<dt>\` / \`<dd>\` markup. Row \`<div>\` wrappers allow the bottom border to span the full width.
+
+**Components:**
+- \`SummaryList\`: the \`<dl>\` container
+- \`SummaryListRow\`: wraps each key–value pair
+- \`SummaryListKey\`: the \`<dt>\` term (bold)
+- \`SummaryListValue\`: the \`<dd>\` value
+- \`SummaryListActions\`: optional \`<dd>\` for change/delete links, right-aligned on desktop
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SummaryList>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Typical "check your answers" usage with a change link on each row.' },
+    },
+  },
+  render: () => (
+    <SummaryList>
+      <SummaryListRow>
+        <SummaryListKey>Name</SummaryListKey>
+
+        <SummaryListValue>Sarah Philips</SummaryListValue>
+
+        <SummaryListActions>
+          <Link href="#">
+            Change <span className="sr-only">name</span>
+          </Link>
+        </SummaryListActions>
+      </SummaryListRow>
+
+      <SummaryListRow>
+        <SummaryListKey>Date of birth</SummaryListKey>
+
+        <SummaryListValue>5 January 1978</SummaryListValue>
+
+        <SummaryListActions>
+          <Link href="#">
+            Change <span className="sr-only">date of birth</span>
+          </Link>
+        </SummaryListActions>
+      </SummaryListRow>
+
+      <SummaryListRow>
+        <SummaryListKey>Contact information</SummaryListKey>
+
+        <SummaryListValue>
+          72 Guild Street
+          <br />
+          London
+          <br />
+          SE23 6FH
+        </SummaryListValue>
+
+        <SummaryListActions>
+          <Link href="#">
+            Change <span className="sr-only">contact information</span>
+          </Link>
+        </SummaryListActions>
+      </SummaryListRow>
+    </SummaryList>
+  ),
+};
+
+export const MultipleActions: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'When a row has more than one action, list them with visually hidden context text on each.',
+      },
+    },
+  },
+  render: () => (
+    <SummaryList>
+      <SummaryListRow>
+        <SummaryListKey>Name</SummaryListKey>
+
+        <SummaryListValue>Sarah Philips</SummaryListValue>
+
+        <SummaryListActions>
+          <ul className="m-0 p-0 list-none flex gap-gds-2 sm:flex-col sm:gap-gds-1">
+            <li>
+              <Link href="#">
+                Change <span className="sr-only">name</span>
+              </Link>
+            </li>
+
+            <li>
+              <Link href="#">
+                Delete <span className="sr-only">name</span>
+              </Link>
+            </li>
+          </ul>
+        </SummaryListActions>
+      </SummaryListRow>
+
+      <SummaryListRow>
+        <SummaryListKey>Date of birth</SummaryListKey>
+
+        <SummaryListValue>5 January 1978</SummaryListValue>
+
+        <SummaryListActions>
+          <ul className="m-0 p-0 list-none flex gap-gds-2 sm:flex-col sm:gap-gds-1">
+            <li>
+              <Link href="#">
+                Change <span className="sr-only">date of birth</span>
+              </Link>
+            </li>
+
+            <li>
+              <Link href="#">
+                Delete <span className="sr-only">date of birth</span>
+              </Link>
+            </li>
+          </ul>
+        </SummaryListActions>
+      </SummaryListRow>
+    </SummaryList>
+  ),
+};
+
+export const NarrowContainer: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A single long, unbreakable word (no space to wrap at) in a narrow container. Without break-words on the key/value, this would overflow its own box and visually overlap its neighbour rather than wrapping the way multi-word text does.',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-xs">
+      <SummaryList>
+        <SummaryListRow>
+          <SummaryListKey>Sites</SummaryListKey>
+
+          <SummaryListValue>240</SummaryListValue>
+        </SummaryListRow>
+
+        <SummaryListRow>
+          <SummaryListKey>Total area</SummaryListKey>
+
+          <SummaryListValue>1,315,000 ha</SummaryListValue>
+        </SummaryListRow>
+
+        <SummaryListRow>
+          <SummaryListKey>Percentage</SummaryListKey>
+
+          <SummaryListValue>34.2%</SummaryListValue>
+        </SummaryListRow>
+      </SummaryList>
+    </div>
+  ),
+};
+
+export const NoActions: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Read-only display, no actions column.' },
+    },
+  },
+  render: () => (
+    <SummaryList>
+      <SummaryListRow>
+        <SummaryListKey>Name</SummaryListKey>
+
+        <SummaryListValue>Sarah Philips</SummaryListValue>
+      </SummaryListRow>
+
+      <SummaryListRow>
+        <SummaryListKey>Date of birth</SummaryListKey>
+
+        <SummaryListValue>5 January 1978</SummaryListValue>
+      </SummaryListRow>
+
+      <SummaryListRow>
+        <SummaryListKey>Address</SummaryListKey>
+
+        <SummaryListValue>72 Guild Street, London, SE23 6FH</SummaryListValue>
+      </SummaryListRow>
+    </SummaryList>
+  ),
+};

package/src/components/SummaryList/SummaryList.tsx

@@ -0,0 +1,41 @@
+import { type ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type SummaryListProps = ComponentProps<'dl'>;
+
+export const SummaryList = ({ className, ...props }: SummaryListProps) => (
+  <dl data-slot="summary-list" className={cn('cn-summary-list', className)} {...props} />
+);
+
+export type SummaryListRowProps = ComponentProps<'div'>;
+
+export const SummaryListRow = ({ className, ...props }: SummaryListRowProps) => (
+  <div data-slot="summary-list-row" className={cn('cn-summary-list-row', className)} {...props} />
+);
+
+export type SummaryListKeyProps = ComponentProps<'dt'>;
+
+export const SummaryListKey = ({ className, ...props }: SummaryListKeyProps) => (
+  <dt data-slot="summary-list-key" className={cn('cn-summary-list-key', className)} {...props} />
+);
+
+export type SummaryListValueProps = ComponentProps<'dd'>;
+
+export const SummaryListValue = ({ className, ...props }: SummaryListValueProps) => (
+  <dd
+    data-slot="summary-list-value"
+    className={cn('cn-summary-list-value', className)}
+    {...props}
+  />
+);
+
+export type SummaryListActionsProps = ComponentProps<'dd'>;
+
+export const SummaryListActions = ({ className, ...props }: SummaryListActionsProps) => (
+  <dd
+    data-slot="summary-list-actions"
+    className={cn('cn-summary-list-actions', className)}
+    {...props}
+  />
+);

package/src/components/SummaryList/SummaryListSkeleton.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SummaryList, SummaryListKey, SummaryListRow, SummaryListValue } from './SummaryList';
+import { SummaryListSkeleton } from './SummaryListSkeleton';
+
+const meta: Meta<typeof SummaryListSkeleton> = {
+  title: 'Components/SummaryList/Skeleton',
+  component: SummaryListSkeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Placeholder for a SummaryList while its rows are loading. Reuses SummaryList/SummaryListRow/SummaryListKey/SummaryListValue directly, so it lines up exactly with the real list once data arrives.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SummaryListSkeleton>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <SummaryListSkeleton />
+    </div>
+  ),
+};
+
+export const SideBySide: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'The skeleton and the real list line up exactly once loaded.' },
+    },
+  },
+  render: () => (
+    <div className="flex gap-gds-6">
+      <div className="max-w-md w-full">
+        <SummaryListSkeleton rows={3} />
+      </div>
+
+      <div className="max-w-md w-full">
+        <SummaryList>
+          <SummaryListRow>
+            <SummaryListKey>Name</SummaryListKey>
+
+            <SummaryListValue>Sarah Philips</SummaryListValue>
+          </SummaryListRow>
+
+          <SummaryListRow>
+            <SummaryListKey>Date of birth</SummaryListKey>
+
+            <SummaryListValue>5 January 1978</SummaryListValue>
+          </SummaryListRow>
+
+          <SummaryListRow>
+            <SummaryListKey>Address</SummaryListKey>
+
+            <SummaryListValue>72 Guild Street, London, SE23 6FH</SummaryListValue>
+          </SummaryListRow>
+        </SummaryList>
+      </div>
+    </div>
+  ),
+};

package/src/components/SummaryList/SummaryListSkeleton.tsx

@@ -0,0 +1,40 @@
+import type { ComponentProps } from 'react';
+
+import { SummaryList, SummaryListKey, SummaryListRow, SummaryListValue } from './SummaryList';
+import { Skeleton } from '../Skeleton/Skeleton';
+
+// Stable, fixed identifiers rather than the array index, even though these
+// are decorative and never reorder, so a row's identity is never tied to
+// its position at render time.
+const ROW_KEYS = ['row-1', 'row-2', 'row-3', 'row-4', 'row-5', 'row-6'] as const;
+
+export type SummaryListSkeletonProps = Omit<ComponentProps<typeof SummaryList>, 'children'> & {
+  /** Explicitly disallow children, a skeleton is a placeholder shape, not a content wrapper. */
+  children?: never;
+  /** Number of rows to show. Defaults to 3. */
+  rows?: number;
+};
+
+export const SummaryListSkeleton = ({
+  className,
+  rows = 3,
+  ...props
+}: SummaryListSkeletonProps) => {
+  const rowKeys = ROW_KEYS.slice(0, rows);
+
+  return (
+    <SummaryList aria-hidden className={className} {...props}>
+      {rowKeys.map((key) => (
+        <SummaryListRow key={key}>
+          <SummaryListKey>
+            <Skeleton className="cn-summary-list-skeleton-key" />
+          </SummaryListKey>
+
+          <SummaryListValue>
+            <Skeleton className="cn-summary-list-skeleton-value" />
+          </SummaryListValue>
+        </SummaryListRow>
+      ))}
+    </SummaryList>
+  );
+};

package/src/components/Tabs/Tabs.css

@@ -0,0 +1,84 @@
+@layer components {
+  /* MARK: Tab list
+     h-full: stretches to fill whatever height its parent establishes (e.g. a
+     taller header) rather than shrinking to its own content's height, so it
+     actually reaches that container's top edge instead of floating wherever
+     it naturally lands. items-end then sits each trigger (text + its
+     underline, as one rigid unit, see cn-tabs-trigger below) flush against
+     the bottom of that now-taller box rather than the top, with no extra gap
+     introduced either within the trigger or between the list and whatever
+     comes right after it (typically TabsContent). relative + cn-z-top keeps
+     the active-tab underline visible over anything else rendered nearby,
+     needs its own stacking context since this element isn't necessarily a
+     flex/grid item of anything itself. */
+  .cn-tabs-list {
+    @apply relative flex h-full items-end cn-z-top flex-wrap;
+  }
+
+  /* MARK: Tab trigger
+     Column flex so the hidden sizer stacks above the visible text.
+     The sizer is bold (matching the active state) with height: 0 so it
+     contributes its bold width to the trigger without adding any height.
+     This means the trigger is always sized to the bold width, preventing
+     siblings from shifting when the active tab changes. */
+  .cn-tabs-trigger {
+    @apply flex flex-col items-center px-gds-3 py-gds-1 bg-transparent border-none cursor-pointer
+      select-none transition-transform duration-150;
+
+    &:hover:not(:disabled) {
+      @apply bg-focus;
+    }
+
+    &:hover:not([data-state='active'], :disabled) {
+      @apply -translate-y-px;
+    }
+
+    &:focus-visible {
+      @apply outline-focus;
+    }
+
+    &[data-disabled] {
+      @apply opacity-50 cursor-not-allowed;
+    }
+  }
+
+  /* Invisible bold copy, sets the width, takes no height */
+  .cn-tabs-trigger-sizer {
+    @apply font-bold invisible overflow-hidden whitespace-nowrap select-none pointer-events-none
+      h-0;
+  }
+
+  /* Visible text, underline transitions from transparent to body colour on active */
+  .cn-tabs-trigger-text {
+    @apply text-base text-body underline decoration-transparent decoration-2 underline-offset-4
+      transition-[font-weight,text-decoration-color] duration-150;
+    line-height: 1.5rem;
+    text-underline-offset: var(--spacing-gds-2);
+  }
+
+  .cn-tabs-trigger[data-state='active'] .cn-tabs-trigger-text {
+    @apply font-bold decoration-body;
+  }
+
+  /* MARK: Tab content
+     Radix's forceMount makes a TabsContent panel present={forceMount ||
+     isSelected}, which is unconditionally true whenever forceMount is set,
+     so its own hidden={!present} is unconditionally false too, and React
+     omits a hidden={false} attribute from the DOM entirely. forceMount's
+     actual contract is "stay mounted always, you handle hiding it
+     yourself" via data-state, not "hidden natively while inactive": don't
+     reintroduce a [hidden] selector here expecting it to ever match.
+     !important still matters here for the same reason it would for
+     [hidden]: a consumer's own layout class on TabsContent (e.g. flex/h-full,
+     to make a map fill the panel) is a same-origin, equal-or-higher-
+     specificity display declaration that would otherwise win. */
+  .cn-tabs-content {
+    &:focus-visible {
+      @apply outline-focus;
+    }
+
+    &[data-state='inactive'] {
+      display: none !important;
+    }
+  }
+}

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,133 @@
+import { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Tabs, TabsContent, TabsList, TabsTrigger } from './Tabs';
+
+const meta: Meta<typeof Tabs> = {
+  title: 'Components/Tabs',
+  component: Tabs,
+};
+
+export default meta;
+type Story = StoryObj<typeof Tabs>;
+
+export const Default: Story = {
+  render: () => (
+    <Tabs defaultValue="overview">
+      <TabsList>
+        <TabsTrigger value="overview">Overview</TabsTrigger>
+
+        <TabsTrigger value="details">Details</TabsTrigger>
+
+        <TabsTrigger value="history">History</TabsTrigger>
+      </TabsList>
+
+      <TabsContent value="overview">
+        <p className="text-body">Overview tab content.</p>
+      </TabsContent>
+
+      <TabsContent value="details">
+        <p className="text-body">Details tab content.</p>
+      </TabsContent>
+
+      <TabsContent value="history">
+        <p className="text-body">History tab content.</p>
+      </TabsContent>
+    </Tabs>
+  ),
+};
+
+export const WithDisabledTab: Story = {
+  render: () => (
+    <Tabs defaultValue="active">
+      <TabsList>
+        <TabsTrigger value="active">Active</TabsTrigger>
+
+        <TabsTrigger value="disabled" disabled>
+          Disabled
+        </TabsTrigger>
+
+        <TabsTrigger value="another">Another</TabsTrigger>
+      </TabsList>
+
+      <TabsContent value="active">
+        <p className="text-body">Active tab content.</p>
+      </TabsContent>
+
+      <TabsContent value="disabled">
+        <p className="text-body">Disabled tab content (unreachable).</p>
+      </TabsContent>
+
+      <TabsContent value="another">
+        <p className="text-body">Another tab content.</p>
+      </TabsContent>
+    </Tabs>
+  ),
+};
+
+const ControlledTabs = () => {
+  const [value, setValue] = useState('tab1');
+
+  return (
+    <div className="flex flex-col gap-gds-2">
+      <p className="text-body text-sm">
+        Active tab: <strong>{value}</strong>
+      </p>
+
+      <Tabs value={value} onValueChange={setValue}>
+        <TabsList>
+          <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+
+          <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+
+          <TabsTrigger value="tab3">Tab 3</TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="tab1">
+          <p className="text-body">Content for Tab 1.</p>
+        </TabsContent>
+
+        <TabsContent value="tab2">
+          <p className="text-body">Content for Tab 2.</p>
+        </TabsContent>
+
+        <TabsContent value="tab3">
+          <p className="text-body">Content for Tab 3.</p>
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+};
+
+export const Controlled: Story = {
+  render: () => <ControlledTabs />,
+};
+
+export const BottomAligned: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'If TabsList itself is given more height than its content needs (here via className="h-20", e.g. sitting inside a taller header bar), the triggers sit flush against its bottom edge rather than floating at the top, with no extra gap introduced between the text and its own underline.',
+      },
+    },
+  },
+  render: () => (
+    <Tabs defaultValue="overview">
+      <TabsList className="h-20 border-b border-divider">
+        <TabsTrigger value="overview">Overview</TabsTrigger>
+
+        <TabsTrigger value="details">Details</TabsTrigger>
+      </TabsList>
+
+      <TabsContent value="overview">
+        <p className="text-body">Overview tab content.</p>
+      </TabsContent>
+
+      <TabsContent value="details">
+        <p className="text-body">Details tab content.</p>
+      </TabsContent>
+    </Tabs>
+  ),
+};