@tpzdsp/next-toolkit 2.5.1 → 3.0.0

package/src/components/ButtonLink/ButtonLink.tsx

@@ -1,33 +1,64 @@
-import type { ExtendProps } from '../../types/utils';
-import { cn } from '../../utils';
+import type { ComponentProps } from 'react';
 
-type Props = {
-  type?: 'submit' | 'reset' | 'button';
-  children: React.ReactNode;
+import { Slot } from 'radix-ui';
+
+import { cn } from '../../utils/components';
+
+const BUTTON_LINK_APPEARANCES = {
+  primary: 'cn-button-link-appearance-primary',
+  inverse: 'cn-button-link-appearance-inverse',
+  contrast: 'cn-button-link-appearance-contrast',
+} as const;
+
+const BUTTON_LINK_VARIANTS = {
+  default: 'cn-button-link-variant-default',
+  icon: 'cn-button-link-variant-icon',
+} as const;
+
+const BUTTON_LINK_SIZES = {
+  sm: 'cn-button-link-size-sm',
+  base: 'cn-button-link-size-base',
+  lg: 'cn-button-link-size-lg',
+} as const;
+
+export type ButtonLinkAppearance = keyof typeof BUTTON_LINK_APPEARANCES;
+export type ButtonLinkVariant = keyof typeof BUTTON_LINK_VARIANTS;
+export type ButtonLinkSize = keyof typeof BUTTON_LINK_SIZES;
+export type ButtonLinkProps = ComponentProps<'button'> & {
+  asChild?: boolean;
+  appearance?: ButtonLinkAppearance;
+  variant?: ButtonLinkVariant;
+  size?: ButtonLinkSize;
 };
 
-export type ButtonLinkProps = ExtendProps<'button', Props>;
+export const ButtonLink = ({
+  className,
+  appearance = 'primary',
+  variant = 'default',
+  size = 'base',
+  asChild = false,
+  ...props
+}: ButtonLinkProps) => {
+  const Comp = asChild ? Slot.Root : 'button';
 
-/**
- * A button that looks like a link.
- * Use when you need button functionality (onClick, form submission)
- * but want the visual appearance of a link.
- */
-export const ButtonLink = ({ type = 'button', className, children, ...props }: ButtonLinkProps) => {
   return (
-    <button
-      type={type}
+    <Comp
+      {...props}
+      data-slot="button"
+      data-appearance={appearance}
+      data-variant={variant}
+      data-size={size}
       className={cn(
-        `cursor-pointer text-link hover:decoration-[max(3px,_.1875rem,_.12em)] hover:text-link-hover
-        visited:text-link-visited active:text-black focus:decoration-[max(3px,_.1875rem,_.12em)]
-        decoration-[max(1px,_.0625rem)] underline-offset-[0.1578em] underline outline-none
-        focus:text-focus-text focus:bg-focus inline-block bg-transparent border-0 p-0
-        disabled:opacity-50 disabled:cursor-not-allowed`,
+        `cn-button cn-button-link inline-flex items-center select-none disabled:cursor-not-allowed
+        [&_svg]:pointer-events-none [&_svg]:shrink-0`,
+        BUTTON_LINK_APPEARANCES[appearance],
+        BUTTON_LINK_VARIANTS[variant],
+        BUTTON_LINK_SIZES[size],
         className,
       )}
-      {...props}
-    >
-      {children}
-    </button>
+      // Forces the button to always be understood as a button by the screenreader even
+      // if someone tries to replace the component with `asChild`.
+      role="button"
+    />
   );
 };

package/src/components/Card/Card.css

@@ -0,0 +1,13 @@
+@layer components {
+  /* MARK: Card
+     Thin top divider rather than a full border box, no fill. min-h-60 (240px)
+     keeps cards a similar near-square shape in a grid regardless of content
+     length; width comes from whatever layout the card sits in (CardGroup's
+     grid columns, typically). Also a container-query provider (@container):
+     a card's own width is set by its grid column, not the viewport, so
+     anything stacked inside it (Stack, HeadingGroup) needs to size against
+     that actual width instead. */
+  .cn-card {
+    @apply border-t border-divider p-gds-3 min-h-60 @container;
+  }
+}

package/src/components/Card/Card.stories.tsx

@@ -1,82 +1,123 @@
-import { FaChevronRight } from 'react-icons/fa6';
+import { LuChevronRight } from 'react-icons/lu';
 
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { Card } from './Card';
-import { ExternalLink } from '../link/ExternalLink';
+import { CardGroup } from '../CardGroup/CardGroup';
+import { Heading } from '../Heading/Heading';
+import { HeadingGroup } from '../Layout/HeadingGroup/HeadingGroup';
+import { Link } from '../Link/Link';
 import { Paragraph } from '../Paragraph/Paragraph';
 
 const meta: Meta<typeof Card> = {
   title: 'Components/Card',
   component: Card,
-  parameters: {
-    layout: 'padded',
-  },
   tags: ['autodocs'],
-  argTypes: {
-    children: {
-      description: 'Content of the card',
-      control: false,
-    },
-    className: {
-      description: 'Additional TailwindCSS classes to apply',
-      control: 'text',
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A content block set apart by a thin top divider rather than a full border box. Card has no opinion on internal structure, it just supplies the divider, padding, and a min-height that keeps cards a similar near-square shape when several sit side by side. Combine with CardGroup for a responsive grid.',
+      },
     },
   },
-  args: {
-    children: 'Hello, this is some simple text',
-  },
+  argTypes: {},
+  args: {},
 };
 
 export default meta;
 
 type Story = StoryObj<typeof Card>;
 
-export const Default: Story = {};
+export const Default: Story = {
+  render: () => (
+    <Card className="max-w-xs">
+      <HeadingGroup>
+        <Heading level="h3" className="text-lg">
+          <Link href="#" variant="expand">
+            Data requirements library
+            <LuChevronRight aria-hidden className="size-4" strokeWidth={2.5} />
+          </Link>
+        </Heading>
 
-export const ParagraphOfText: Story = {
-  args: {
-    children: <Paragraph>Hello, this is some simple text</Paragraph>,
-  },
-};
+        <Paragraph className="text-sm">
+          The terminology and categories we use to classify and describe Environment Agency assets.
+          We also document the attributes we use to describe the properties of each Asset Type and
+          its Element Types.
+        </Paragraph>
+      </HeadingGroup>
 
-export const ImageAndText: Story = {
-  args: {
-    children: (
-      <div>
-        <img
-          src="https://images.unsplash.com/photo-1563991655280-cb95c90ca2fb?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8bm8lMjBjb3B5cmlnaHR8ZW58MHx8MHx8fDA%3D"
-          alt="Card"
-        />
-
-        <p>This is text about the image</p>
-      </div>
-    ),
-  },
+      <Link href="#" className="mt-gds-2 inline-block text-sm">
+        API
+      </Link>
+    </Card>
+  ),
 };
 
-export const ComplexChildren: Story = {
-  args: {
-    children: (
-      <>
-        <ExternalLink
-          href="https://google.co.uk"
-          className="mb-4 flex flex-nowrap items-center gap-2 justify-between font-bold"
-        >
-          <strong>title</strong>
-
-          <FaChevronRight className="text-base" />
-        </ExternalLink>
-
-        <Paragraph>Some descriptive text</Paragraph>
-      </>
-    ),
+export const Grid: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'CardGroup lays cards out in a responsive grid, columns auto-fill down to a minimum width rather than a fixed count, so the same markup reflows from one column on mobile up to several on desktop.',
+      },
+    },
   },
-};
+  render: () => (
+    <CardGroup>
+      <Card>
+        <HeadingGroup>
+          <Heading level="h3" className="text-lg">
+            <Link href="#" variant="expand">
+              Data requirements library
+              <LuChevronRight aria-hidden className="size-4" strokeWidth={2.5} />
+            </Link>
+          </Heading>
 
-export const CustomStyling: Story = {
-  args: {
-    className: 'bg-blue-100 text-blue-800 p-4 rounded-lg shadow-lg',
-    children: 'Custom styled card',
-  },
+          <Paragraph className="text-sm">
+            The terminology and categories we use to classify and describe Environment Agency
+            assets.
+          </Paragraph>
+        </HeadingGroup>
+
+        <Link href="#" className="mt-gds-2 inline-block text-sm">
+          API
+        </Link>
+      </Card>
+
+      <Card>
+        <HeadingGroup>
+          <Heading level="h3" className="text-lg">
+            <Link href="#" variant="expand">
+              Flood risk data
+              <LuChevronRight aria-hidden className="size-4" strokeWidth={2.5} />
+            </Link>
+          </Heading>
+
+          <Paragraph className="text-sm">
+            Flood extents, defences, and risk of flooding data for rivers, sea, and surface water.
+          </Paragraph>
+        </HeadingGroup>
+      </Card>
+
+      <Card>
+        <HeadingGroup>
+          <Heading level="h3" className="text-lg">
+            <Link href="#" variant="expand">
+              Water quality archive
+              <LuChevronRight aria-hidden className="size-4" strokeWidth={2.5} />
+            </Link>
+          </Heading>
+
+          <Paragraph className="text-sm">
+            Historic water quality sample data collected at monitoring points across England.
+          </Paragraph>
+        </HeadingGroup>
+
+        <Link href="#" className="mt-gds-2 inline-block text-sm">
+          API
+        </Link>
+      </Card>
+    </CardGroup>
+  ),
 };

package/src/components/Card/Card.tsx

@@ -1,21 +1,12 @@
-import type { ExtendProps } from '../../types';
-import { cn } from '../../utils';
+import type { ComponentProps } from 'react';
 
-type Props = {
-  children: React.ReactNode;
-};
+import { cn } from '../../utils';
 
-export type CardProps = ExtendProps<'article', Props>;
+export type CardProps = ComponentProps<'article'>;
 
 export const Card = ({ className, children, ...props }: CardProps) => {
   return (
-    <article
-      className={cn(
-        'h-full flex flex-col pt-[12px] px-[4px] mx-3 border-t border-slate-500',
-        className,
-      )}
-      {...props}
-    >
+    <article data-slot="card" className={cn('cn-card', className)} {...props}>
       {children}
     </article>
   );

package/src/components/CardGroup/CardGroup.css

@@ -0,0 +1,10 @@
+@layer components {
+  /* MARK: CardGroup
+     Responsive grid, no fixed column count: columns auto-fill at a minimum
+     card width and stretch evenly to fill the remaining space, so the same
+     markup reflows from one column on mobile up to several on desktop. */
+  .cn-card-group {
+    @apply grid gap-gds-4;
+    grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
+  }
+}

package/src/components/CardGroup/CardGroup.stories.tsx

@@ -0,0 +1,81 @@
+import { LuChevronRight } from 'react-icons/lu';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { CardGroup } from './CardGroup';
+import { Card } from '../Card/Card';
+import { Heading } from '../Heading/Heading';
+import { HeadingGroup } from '../Layout/HeadingGroup/HeadingGroup';
+import { Link } from '../Link/Link';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+const meta: Meta<typeof CardGroup> = {
+  title: 'Components/CardGroup',
+  component: CardGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Lays Card components out in a responsive grid. Columns auto-fill down to a minimum width rather than a fixed count, so the same markup reflows from one column on mobile up to several on desktop.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof CardGroup>;
+
+const CARDS = [
+  {
+    title: 'Data requirements library',
+    description:
+      'The terminology and categories we use to classify and describe Environment Agency assets.',
+    hasApi: true,
+  },
+  {
+    title: 'Flood risk data',
+    description:
+      'Flood extents, defences, and risk of flooding data for rivers, sea, and surface water.',
+    hasApi: false,
+  },
+  {
+    title: 'Water quality archive',
+    description:
+      'Historic water quality sample data collected at monitoring points across England.',
+    hasApi: true,
+  },
+  {
+    title: 'Land cover map',
+    description: 'Land parcel boundaries and cover classification for England.',
+    hasApi: false,
+  },
+];
+
+export const Default: Story = {
+  render: () => (
+    <CardGroup>
+      {CARDS.map((card) => (
+        <Card key={card.title}>
+          <HeadingGroup>
+            <Heading level="h3" className="text-lg">
+              <Link href="#" variant="expand">
+                {card.title}
+                <LuChevronRight aria-hidden className="size-4" strokeWidth={2.5} />
+              </Link>
+            </Heading>
+
+            <Paragraph className="text-sm">{card.description}</Paragraph>
+          </HeadingGroup>
+
+          {card.hasApi ? (
+            <Link href="#" className="mt-gds-2 inline-block text-sm">
+              API
+            </Link>
+          ) : null}
+        </Card>
+      ))}
+    </CardGroup>
+  ),
+};

package/src/components/CardGroup/CardGroup.tsx

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type CardGroupProps = ComponentProps<'div'>;
+
+export const CardGroup = ({ className, ...props }: CardGroupProps) => (
+  <div data-slot="card-group" className={cn('cn-card-group', className)} {...props} />
+);

package/src/components/Checkbox/Checkbox.css

@@ -0,0 +1,49 @@
+@layer components {
+  /* MARK: Checkbox
+     Radix Checkbox.Root renders a <button role="checkbox">.
+     Border is set explicitly (not via cn-form-border @apply) because
+     appearance:none on <button> can override utility-layer border styles. */
+  .cn-checkbox {
+    @apply appearance-none cursor-pointer flex-none box-border bg-white outline-none p-0;
+    border: var(--border-width-form) solid var(--color-divider-input);
+
+    &:focus:not(:disabled) {
+      @apply outline-focus border-4 outline-offset-1;
+      box-shadow: 0 0 0 var(--outline-width-focus) var(--color-focus);
+    }
+
+    &[data-state='checked'] {
+      @apply border-body;
+    }
+
+    &:disabled {
+      @apply opacity-50 cursor-not-allowed;
+    }
+  }
+
+  /* MARK: Indicator */
+  .cn-checkbox-indicator {
+    @apply flex items-center justify-center w-full h-full;
+  }
+
+  .cn-checkbox-icon {
+    @apply border-body;
+  }
+
+  /* MARK: Sizes */
+  .cn-checkbox-size-sm {
+    @apply w-6 h-6;
+
+    & .cn-checkbox-icon {
+      @apply w-3 h-3 stroke-4;
+    }
+  }
+
+  .cn-checkbox-size-base {
+    @apply w-10 h-10;
+
+    & .cn-checkbox-icon {
+      @apply w-6 h-6 stroke-4;
+    }
+  }
+}

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Checkbox } from './Checkbox';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Components/Checkbox',
+  component: Checkbox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Let users select one or more options by using the checkboxes component.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: { type: 'radio' },
+      options: ['sm', 'base'],
+    },
+    disabled: { control: 'boolean' },
+    defaultChecked: { control: 'boolean' },
+  },
+  args: {
+    size: 'base',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {};
+
+export const Checked: Story = {
+  args: { defaultChecked: true },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-gds-4">
+      <Label className="flex flex-col items-center gap-gds-1">
+        <Checkbox size="sm" />
+        sm
+      </Label>
+
+      <Label className="flex flex-col items-center gap-gds-1">
+        <Checkbox size="base" />
+        base
+      </Label>
+    </div>
+  ),
+};
+
+export const WithLabel: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Wrap the checkbox inside a `Label` so clicking the label text activates it. Radix renders the checkbox as a `<button>`, so `htmlFor` alone is unreliable, the wrapping label avoids that.',
+      },
+    },
+  },
+  render: (args) => (
+    <Label className="flex items-center gap-gds-2">
+      <Checkbox {...args} />I agree to the terms and conditions
+    </Label>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-gds-2">
+      <Label className="flex items-center gap-gds-2">
+        <Checkbox disabled />
+        Unchecked disabled
+      </Label>
+
+      <Label className="flex items-center gap-gds-2">
+        <Checkbox disabled defaultChecked />
+        Checked disabled
+      </Label>
+    </div>
+  ),
+};

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { Checkbox as CheckboxPrimitive } from 'radix-ui';
+import { LiaCheckSolid } from 'react-icons/lia';
+
+import { cn } from '../../utils/components';
+
+const CHECKBOX_SIZES = {
+  sm: 'cn-checkbox-size-sm',
+  base: 'cn-checkbox-size-base',
+} as const;
+
+export type CheckboxSize = keyof typeof CHECKBOX_SIZES;
+
+export type CheckboxProps = ComponentProps<typeof CheckboxPrimitive.Root> & {
+  size?: CheckboxSize;
+};
+
+export const Checkbox = ({ className, size = 'base', ...props }: CheckboxProps) => (
+  <CheckboxPrimitive.Root
+    data-slot="checkbox"
+    data-size={size}
+    className={cn('cn-checkbox', CHECKBOX_SIZES[size], className)}
+    {...props}
+  >
+    <CheckboxPrimitive.Indicator data-slot="checkbox-indicator" className="cn-checkbox-indicator">
+      <LiaCheckSolid aria-hidden className="cn-checkbox-icon" />
+    </CheckboxPrimitive.Indicator>
+  </CheckboxPrimitive.Root>
+);

package/src/components/Chip/Chip.css

@@ -0,0 +1,54 @@
+/* MARK: Tag
+    GDS-style label rendered as <strong> to convey semantic importance.
+    Accent green by default. 1px radius, break-word, no text decoration. */
+@utility cn-chip {
+  @apply inline-block wrap-break-word no-underline;
+  border-radius: 1px;
+  max-width: 160px;
+}
+
+/* MARK: Appearances */
+
+@utility cn-chip-appearance-neutral {
+  @apply bg-neutral-subtle text-on-neutral-subtle;
+}
+
+@utility cn-chip-appearance-success {
+  @apply bg-success-subtle text-on-success-subtle;
+}
+
+@utility cn-chip-appearance-warning {
+  @apply bg-warning-subtle text-on-warning-subtle;
+}
+
+@utility cn-chip-appearance-error {
+  @apply bg-error-subtle text-on-error-subtle;
+}
+
+@utility cn-chip-appearance-info {
+  @apply bg-info-subtle text-on-info-subtle;
+}
+
+/* MARK: Sizes */
+
+@utility cn-chip-size-sm {
+  @apply text-sm;
+  padding: 1px 6px 2px;
+  margin-top: -1px;
+  margin-bottom: -2px;
+}
+
+@utility cn-chip-size-base {
+  @apply text-base;
+  /* GDS canonical padding */
+  padding: 2px 8px 3px;
+  margin-top: -2px;
+  margin-bottom: -3px;
+}
+
+@utility cn-chip-size-lg {
+  @apply text-lg;
+  padding: 4px 10px 5px;
+  margin-top: -4px;
+  margin-bottom: -5px;
+}