@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/LinkButton/LinkButton.css

@@ -0,0 +1,67 @@
+@layer components {
+  /* MARK: LinkButton
+     An <a> styled to look like a Button. Use for navigation that needs
+     button affordance (e.g. cancel links in form button groups).
+     Thin wrappers over cn-button-* so all appearance/size/focus behaviour
+     stays in one place. */
+
+  .cn-link-button {
+    @apply cn-button;
+
+    /* A link doesn't get the pressed button illusion. Keep the shadow bar
+       visible on active instead of clearing it like cn-button does. */
+    &:active:not(:disabled):not(:focus) {
+      box-shadow: 0 var(--cn-button-shadow-size, 0px) 0 var(--cn-button-shadow-color, transparent);
+    }
+  }
+
+  /* MARK: Appearances */
+
+  .cn-link-button-appearance-primary {
+    @apply cn-button-appearance-primary;
+  }
+
+  .cn-link-button-appearance-secondary {
+    @apply cn-button-appearance-secondary;
+  }
+
+  .cn-link-button-appearance-destructive {
+    @apply cn-button-appearance-destructive;
+  }
+
+  .cn-link-button-appearance-inverse {
+    @apply cn-button-appearance-inverse;
+  }
+
+  .cn-link-button-appearance-ghost {
+    @apply cn-button-appearance-ghost;
+  }
+
+  .cn-link-button-appearance-panel {
+    @apply cn-button-appearance-panel;
+  }
+
+  /* MARK: Variants */
+
+  .cn-link-button-variant-cta {
+    @apply cn-button-variant-cta;
+  }
+
+  .cn-link-button-variant-icon {
+    @apply cn-button-variant-icon;
+  }
+
+  /* MARK: Sizes */
+
+  .cn-link-button-size-sm {
+    @apply cn-button-size-sm;
+  }
+
+  .cn-link-button-size-base {
+    @apply cn-button-size-base;
+  }
+
+  .cn-link-button-size-lg {
+    @apply cn-button-size-lg;
+  }
+}

package/src/components/LinkButton/LinkButton.stories.tsx

@@ -1,74 +1,122 @@
+import { LuArrowRight } from 'react-icons/lu';
+
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { LinkButton } from './LinkButton';
 
-const meta = {
+const meta: Meta<typeof LinkButton> = {
   title: 'Components/LinkButton',
   component: LinkButton,
+  tags: ['autodocs'],
   parameters: {
-    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Use LinkButton to render an anchor styled as a button. Use this instead of Button when the action navigates as it renders a real <a> element with correct link semantics and the same touch target as a Button.',
+      },
+    },
   },
-  tags: ['autodocs'],
   argTypes: {
+    appearance: {
+      control: { type: 'radio' },
+      options: ['primary', 'secondary', 'destructive', 'inverse', 'ghost', 'panel'],
+    },
     variant: {
-      control: 'select',
-      options: ['primary', 'secondary', 'inverse'],
+      control: { type: 'radio' },
+      options: ['default', 'cta', 'icon'],
     },
-    openInNewTab: {
-      control: 'boolean',
+    size: {
+      control: { type: 'radio' },
+      options: ['sm', 'base', 'lg'],
     },
+    asChild: { control: 'boolean' },
+    children: { control: 'text' },
+  },
+  args: {
+    href: '/',
+    appearance: 'primary',
+    size: 'base',
+    children: 'Continue',
   },
-} satisfies Meta<typeof LinkButton>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+
+type Story = StoryObj<typeof LinkButton>;
 
 export const Primary: Story = {
-  args: {
-    children: 'Explore data',
-    href: '/explore',
-    variant: 'primary',
-  },
+  args: { appearance: 'primary' },
 };
 
 export const Secondary: Story = {
-  args: {
-    children: 'Learn more',
-    href: '/about',
-    variant: 'secondary',
-  },
+  args: { appearance: 'secondary' },
+};
+
+export const Destructive: Story = {
+  args: { appearance: 'destructive' },
 };
 
 export const Inverse: Story = {
-  args: {
-    children: 'Get started',
-    href: '/start',
-    variant: 'inverse',
-  },
+  args: { appearance: 'inverse' },
 };
 
-export const ExternalLink: Story = {
-  args: {
-    children: 'Visit GOV.UK',
-    href: 'https://www.gov.uk',
-    variant: 'primary',
-  },
+export const Ghost: Story = {
+  args: { appearance: 'ghost' },
 };
 
-export const OpenInNewTab: Story = {
-  args: {
-    children: 'Open in new tab',
-    href: '/internal-page',
-    variant: 'primary',
-    openInNewTab: true,
-  },
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-3">
+      <LinkButton {...args} size="sm">
+        Small
+      </LinkButton>
+
+      <LinkButton {...args} size="base">
+        Default
+      </LinkButton>
+
+      <LinkButton {...args} size="lg">
+        Large
+      </LinkButton>
+    </div>
+  ),
 };
 
-export const WithCustomStyling: Story = {
+export const ClickToAction: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-3">
+      <LinkButton {...args} appearance="primary" variant="cta">
+        Start now
+      </LinkButton>
+
+      <LinkButton {...args} appearance="secondary" variant="cta">
+        Learn more
+      </LinkButton>
+    </div>
+  ),
+};
+
+export const IconButton: Story = {
   args: {
-    children: 'Custom styled button',
-    href: '/custom',
-    variant: 'primary',
-    className: 'px-8 py-4 text-xl',
+    variant: 'icon',
+    children: <LuArrowRight />,
   },
 };
+
+export const IconSizes: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-3">
+      <LinkButton {...args} variant="icon" size="sm">
+        <LuArrowRight />
+      </LinkButton>
+
+      <LinkButton {...args} variant="icon" size="base">
+        <LuArrowRight />
+      </LinkButton>
+
+      <LinkButton {...args} variant="icon" size="lg">
+        <LuArrowRight />
+      </LinkButton>
+    </div>
+  ),
+};

package/src/components/LinkButton/LinkButton.tsx

@@ -1,80 +1,67 @@
-import type { ReactNode } from 'react';
+import type { ComponentProps } from 'react';
 
-import NextLink from 'next/link';
+import { Slot } from 'radix-ui';
 
-import type { ExtendProps } from '../../types/utils';
-import { cn } from '../../utils';
+import { cn } from '../../utils/components';
 
-type Props = {
-  /** URL to navigate to */
-  href: string;
-  /** Button variant styling */
-  variant?: 'primary' | 'secondary' | 'inverse';
-  /** Content to display in the button */
-  children: ReactNode;
-  /** Whether to open in a new tab (default: false) */
-  openInNewTab?: boolean;
-};
-
-export type LinkButtonProps = ExtendProps<'a', Props>;
+const LINK_BUTTON_APPEARANCES = {
+  primary: 'cn-link-button-appearance-primary',
+  secondary: 'cn-link-button-appearance-secondary',
+  destructive: 'cn-link-button-appearance-destructive',
+  inverse: 'cn-link-button-appearance-inverse',
+  ghost: 'cn-link-button-appearance-ghost',
+  panel: 'cn-link-button-appearance-panel',
+} as const;
 
-const VARIANTS = {
-  primary: 'bg-brand hover-enabled:bg-green-600 text-white',
-  secondary: 'bg-slate-100 hover-enabled:bg-slate-200 text-black',
-  inverse: 'bg-white hover-enabled:bg-slate-50 text-brand',
-};
+const LINK_BUTTON_VARIANTS = {
+  default: 'cn-link-button-variant-default',
+  cta: 'cn-link-button-variant-cta',
+  icon: 'cn-link-button-variant-icon',
+} as const;
 
-/**
- * Determines if a URL is external (different origin or absolute URL)
- */
-const isExternalUrl = (href: string): boolean => {
-  // Absolute URLs (http://, https://, //)
-  if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//')) {
-    return true;
-  }
+const LINK_BUTTON_SIZES = {
+  sm: 'cn-link-button-size-sm',
+  base: 'cn-link-button-size-base',
+  lg: 'cn-link-button-size-lg',
+} as const;
 
-  // mailto:, tel:, etc.
-  if (href.includes(':')) {
-    return true;
-  }
+export type LinkButtonAppearance = keyof typeof LINK_BUTTON_APPEARANCES;
+export type LinkButtonVariant = keyof typeof LINK_BUTTON_VARIANTS;
+export type LinkButtonSize = keyof typeof LINK_BUTTON_SIZES;
 
-  return false;
+export type LinkButtonProps = ComponentProps<'a'> & {
+  asChild?: boolean;
+  appearance?: LinkButtonAppearance;
+  variant?: LinkButtonVariant;
+  size?: LinkButtonSize;
 };
 
-// NOTE: some of the styles are applied in `tailwind.css`, under `Button Styles`
 export const LinkButton = ({
-  href,
-  variant = 'primary',
-  openInNewTab = false,
   className,
-  children,
+  appearance = 'primary',
+  variant = 'default',
+  size = 'base',
+  asChild = false,
   ...props
 }: LinkButtonProps) => {
-  const buttonClasses = cn(
-    `sm:w-auto text-lg relative inline-flex w-full outline-none items-center border-transparent
-    justify-center border-2 text-center active-enabled:translate-y-[2px] focus:shadow-focus
-    focus:border-focus focus:shadow-[inset_0_0_0_1px] focus-idle:border-focus
-    focus-idle:text-focus-text focus-idle:bg-focus focus-idle:shadow-border-input
-    disabled:opacity-50 disabled:hover:cursor-not-allowed button`,
-    VARIANTS[variant],
-    className,
-  );
-
-  const isExternal = isExternalUrl(href);
-
-  // External link or forced new tab - use <a> tag with appropriate attributes
-  if (isExternal || openInNewTab) {
-    return (
-      <a href={href} target="_blank" rel="noopener noreferrer" className={buttonClasses} {...props}>
-        {children}
-      </a>
-    );
-  }
+  const Comp = asChild ? Slot.Root : 'a';
 
-  // Internal link - use Next.js Link for client-side navigation
   return (
-    <NextLink href={href} className={buttonClasses} {...props}>
-      {children}
-    </NextLink>
+    <Comp
+      {...props}
+      data-slot="link-button"
+      data-appearance={appearance}
+      data-variant={variant}
+      data-size={size}
+      className={cn(
+        'cn-link-button inline-flex shrink-0 items-center justify-center whitespace-nowrap',
+        'outline-none select-none',
+        '[&_svg]:pointer-events-none [&_svg]:shrink-0',
+        LINK_BUTTON_APPEARANCES[appearance],
+        LINK_BUTTON_VARIANTS[variant],
+        LINK_BUTTON_SIZES[size],
+        className,
+      )}
+    />
   );
 };

package/src/components/LinkList/LinkList.css

@@ -0,0 +1,28 @@
+@layer components {
+  /* MARK: LinkList */
+  .cn-link-list {
+    @apply list-none m-0 p-0 flex flex-col gap-gds-2;
+  }
+
+  /* MARK: Item
+     Bold applies to whatever link the consumer renders as children, so it
+     doesn't need to be repeated at every call site. */
+  .cn-link-list-item {
+    @apply flex items-center gap-gds-2;
+
+    & .cn-link {
+      @apply font-bold;
+    }
+  }
+
+  /* MARK: Icon
+     Decorative circle, shrink-0 so it keeps its size if the link text wraps
+     onto a second line. */
+  .cn-link-list-item-icon {
+    @apply flex items-center justify-center shrink-0 size-8 rounded-full bg-wash text-body;
+
+    & svg {
+      @apply size-5;
+    }
+  }
+}

package/src/components/LinkList/LinkList.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LinkList, LinkListItem } from './LinkList';
+import { Link } from '../Link/Link';
+
+const meta: Meta<typeof LinkList> = {
+  title: 'Components/LinkList',
+  component: LinkList,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A vertical list of links, each preceded by an arrow icon in a circle. Deliberately has no heading of its own, place one above the list if you need one. No appearance or size variants yet, add them if a second use case needs one.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof LinkList>;
+
+export const Default: Story = {
+  render: () => (
+    <LinkList className="max-w-xs">
+      <LinkListItem>
+        <Link href="#" appearance="contrast">
+          Frequently asked questions
+        </Link>
+      </LinkListItem>
+
+      <LinkListItem>
+        <Link href="#" appearance="contrast">
+          Glossary
+        </Link>
+      </LinkListItem>
+
+      <LinkListItem>
+        <Link href="#" appearance="contrast">
+          Give feedback
+        </Link>
+      </LinkListItem>
+    </LinkList>
+  ),
+};

package/src/components/LinkList/LinkList.tsx

@@ -0,0 +1,23 @@
+import type { ComponentProps } from 'react';
+
+import { LuArrowRight } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+
+export type LinkListProps = ComponentProps<'ul'>;
+
+export const LinkList = ({ className, ...props }: LinkListProps) => (
+  <ul data-slot="link-list" className={cn('cn-link-list', className)} {...props} />
+);
+
+export type LinkListItemProps = ComponentProps<'li'>;
+
+export const LinkListItem = ({ className, children, ...props }: LinkListItemProps) => (
+  <li data-slot="link-list-item" className={cn('cn-link-list-item', className)} {...props}>
+    <span className="cn-link-list-item-icon" aria-hidden>
+      <LuArrowRight />
+    </span>
+
+    {children}
+  </li>
+);

package/src/components/List/Li.tsx

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils';
+
+export type LiProps = ComponentProps<'li'>;
+
+export const Li = ({ className, ...props }: LiProps) => {
+  return <li className={cn('cn-li', className)} {...props} />;
+};

package/src/components/List/List.css

@@ -0,0 +1,9 @@
+@layer components {
+  .cn-ol {
+    @apply list-decimal pl-gds-2 text-base text-body list-inside;
+  }
+
+  .cn-ul {
+    @apply list-disc pl-gds-2 text-base text-body list-inside;
+  }
+}

package/src/components/List/OrderedList.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Li } from './Li';
+import { OrderedList } from './OrderedList';
+
+const meta: Meta<typeof OrderedList> = {
+  title: 'Components/Ol',
+  component: OrderedList,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use lists to make blocks of text easier to read, and to break information into manageable chunks.',
+      },
+    },
+  },
+  argTypes: {},
+  args: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof OrderedList>;
+
+export const Default: Story = {
+  render: () => (
+    <OrderedList>
+      <Li>Task 1</Li>
+
+      <Li>Task 2</Li>
+
+      <Li>Task 3</Li>
+    </OrderedList>
+  ),
+};

package/src/components/List/OrderedList.tsx

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils';
+
+export type OrderedListProps = ComponentProps<'ol'>;
+
+export const OrderedList = ({ className, ...props }: OrderedListProps) => {
+  return <ol className={cn('cn-ol', className)} {...props} />;
+};

package/src/components/List/UnorderedList.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Li } from './Li';
+import { UnorderedList } from './UnorderedList';
+
+const meta: Meta<typeof UnorderedList> = {
+  title: 'Components/Ul',
+  component: UnorderedList,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use lists to make blocks of text easier to read, and to break information into manageable chunks.',
+      },
+    },
+  },
+  argTypes: {},
+  args: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UnorderedList>;
+
+export const Default: Story = {
+  render: () => (
+    <UnorderedList>
+      <Li>Task 1</Li>
+
+      <Li>Task 2</Li>
+
+      <Li>Task 3</Li>
+    </UnorderedList>
+  ),
+};

package/src/components/List/UnorderedList.tsx

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils';
+
+export type UnorderedListProps = ComponentProps<'ul'>;
+
+export const UnorderedList = ({ className, ...props }: UnorderedListProps) => {
+  return <ul className={cn('cn-ul', className)} {...props} />;
+};

package/src/components/LoadingBox/LoadingBox.css

@@ -0,0 +1,27 @@
+@layer components {
+  /* MARK: LoadingBox
+     relative establishes the containing block the overlay positions
+     against. */
+  .cn-loading-box {
+    @apply relative;
+  }
+
+  /* Always mounted (see LoadingBox.tsx), faded and set inert when not
+     loading rather than mounted/unmounted, so a single opacity transition
+     covers fading in and out without a timer to unmount after the
+     animation ends. cn-z-top (not cn-z-overlay) since this only needs to
+     sit above its own local content, not above every other overlay on the
+     page. */
+  .cn-loading-box-overlay {
+    @apply absolute inset-0 flex items-center justify-center bg-panel/85 opacity-0
+      pointer-events-none transition-opacity duration-300 cn-z-top;
+  }
+
+  .cn-loading-box-overlay[data-loading] {
+    @apply opacity-100 pointer-events-auto;
+  }
+
+  .cn-loading-box-spinner {
+    @apply h-12 w-12 text-body;
+  }
+}

package/src/components/LoadingBox/LoadingBox.stories.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LoadingBox } from './LoadingBox';
+import { Button } from '../Button/Button';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+const meta: Meta<typeof LoadingBox> = {
+  title: 'Components/LoadingBox',
+  component: LoadingBox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Wraps content that loads asynchronously. When loading is true, a spinner fades in over a translucent overlay; the overlay is always mounted (just faded and set inert when off) rather than mounted/unmounted, so it never needs a timer to remove itself after the fade finishes. The children are inert while loading, so content that's about to be replaced can't be focused or clicked through the overlay.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof LoadingBox>;
+
+export const Default: Story = {
+  args: {
+    loading: true,
+    children: (
+      <Paragraph>
+        This content sits behind the loading overlay. Toggle the `loading` control to see it fade.
+      </Paragraph>
+    ),
+  },
+};
+
+const ToggleExample = () => {
+  const [loading, setLoading] = useState(false);
+
+  return (
+    <div className="flex flex-col gap-gds-4">
+      <Button
+        onClick={() => {
+          setLoading(true);
+          setTimeout(() => setLoading(false), 2000);
+        }}
+      >
+        Simulate loading
+      </Button>
+
+      <LoadingBox loading={loading}>
+        <Paragraph>
+          Some asynchronously loaded content lives here. Click the button above to see the overlay
+          fade in, then back out after two seconds.
+        </Paragraph>
+      </LoadingBox>
+    </div>
+  );
+};
+
+export const Toggle: Story = {
+  render: () => <ToggleExample />,
+};