@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Breadcrumb } from './Breadcrumb';
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: 'Components/Breadcrumb',
+  component: Breadcrumb,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+GDS-style breadcrumb: the first (Home) and last (current page) items always show. Unlike GDS's own \`--collapse-on-mobile\`, which only has one all-or-nothing cutoff, middle items collapse one at a time into a static "…" as the screen shrinks, and reveal one at a time as it grows, resize the window (or the Storybook viewport) to see it. No dropdown, the collapsed items aren't individually reachable, this is a purely visual "there's more between these two" indicator.
+
+Pass \`items\` as \`{ label, href? }\`. The last item is treated as the current page regardless of whether it has an \`href\` (rendered as plain text with \`aria-current="page"\`, not a link).
+
+\`appearance\` defaults to \`"default"\` (dark text, for a normal page background). Pass \`"inverse"\` on a dark background like the Hero, it drives the link colour, the current-page text, and the separator icons together.
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Breadcrumb>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Applications', href: '/applications' },
+      { label: 'Application ABC123' },
+    ],
+  },
+};
+
+export const LongTrail: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'With more items, resize the viewport to see them collapse one at a time rather than all at once.',
+      },
+    },
+  },
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Environmental land management', href: '/elm' },
+      { label: 'Sustainable Farming Incentive', href: '/elm/sfi' },
+      { label: 'Applications', href: '/elm/sfi/applications' },
+      { label: 'Agreement holders', href: '/elm/sfi/applications/agreement-holders' },
+      { label: 'Application ABC123' },
+    ],
+  },
+};
+
+export const Inverse: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass `appearance="inverse"` on a dark background, such as the accent-coloured Hero. Drives both the link colour and the current-page text/separator colour together, from one prop.',
+      },
+    },
+  },
+  args: {
+    appearance: 'inverse',
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Applications', href: '/applications' },
+      { label: 'Current application' },
+    ],
+  },
+  render: (args) => (
+    <div className="bg-accent p-gds-4">
+      <Breadcrumb {...args} />
+    </div>
+  ),
+};
+
+export const TwoItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'With only two items there is nothing to collapse, so no ellipsis ever appears.',
+      },
+    },
+  },
+  args: {
+    items: [{ label: 'Home', href: '/' }, { label: 'Current page' }],
+  },
+};

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,135 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { LuChevronRight } from 'react-icons/lu';
+
+import { cn } from '../../utils/components';
+import { Link, type LinkAppearance } from '../Link/Link';
+
+export type BreadcrumbItem = {
+  label: ReactNode;
+  href?: string;
+};
+
+// Each middle item reveals at a progressively larger breakpoint the further
+// it sits from the current page (the item right before it reveals first, at
+// xs; the one before that at sm; and so on), so more of the trail appears
+// as the screen grows rather than an all-or-nothing GDS-style cutoff.
+// This project redefines the breakpoint scale entirely (see breakpoints.css,
+// --breakpoint-*: initial then 2xs/xs/sm/md/lg only), there's no xl or 2xl
+// here, those variants would silently compile to nothing.
+// Written as complete, static class strings rather than built from a
+// template, Tailwind can only pick up classes it finds literally in source.
+const TIER_SEQUENCE = ['xs', 'sm', 'md', 'lg'] as const;
+
+type Tier = (typeof TIER_SEQUENCE)[number];
+
+const REVEAL_AT_TIER_CLASSES: Record<Tier, string> = {
+  xs: 'hidden xs:inline-flex',
+  sm: 'hidden sm:inline-flex',
+  md: 'hidden md:inline-flex',
+  lg: 'hidden lg:inline-flex',
+};
+
+// Shown by default, hidden once every item it stands in for is visible.
+const ELLIPSIS_TIER_CLASSES: Record<Tier, string> = {
+  xs: 'inline-flex xs:hidden',
+  sm: 'inline-flex sm:hidden',
+  md: 'inline-flex md:hidden',
+  lg: 'inline-flex lg:hidden',
+};
+
+const tierForDepth = (depthFromEnd: number): Tier =>
+  TIER_SEQUENCE[Math.min(depthFromEnd - 1, TIER_SEQUENCE.length - 1)]!;
+
+// Maps to Link's own appearances rather than inventing new ones: contrast
+// (dark text) for a normal page background, inverse (white text) for a dark
+// background like the Hero. data-appearance on the nav drives the matching
+// colour for the current-page text and separator icons (see Breadcrumb.css),
+// so both stay in sync with whichever one is picked here.
+const BREADCRUMB_LINK_APPEARANCES = {
+  default: 'contrast',
+  inverse: 'inverse',
+} as const satisfies Record<string, LinkAppearance>;
+
+export type BreadcrumbAppearance = keyof typeof BREADCRUMB_LINK_APPEARANCES;
+
+export type BreadcrumbProps = Omit<ComponentProps<'nav'>, 'children'> & {
+  items: BreadcrumbItem[];
+  appearance?: BreadcrumbAppearance;
+};
+
+export const Breadcrumb = ({
+  items,
+  appearance = 'default',
+  className,
+  ...props
+}: BreadcrumbProps) => {
+  const total = items.length;
+  // The item right after Home (index 1) has the largest depth, so it's the
+  // last one revealed as breakpoints grow, once it's visible nothing is
+  // collapsed any more and the ellipsis itself should disappear.
+  const ellipsisTier = total > 2 ? tierForDepth(total - 2) : undefined;
+
+  const listItems = items.flatMap((item, index) => {
+    const isFirst = index === 0;
+    const isLast = index === total - 1;
+    const depthFromEnd = total - 1 - index;
+    const key = item.href ?? String(item.label);
+
+    const itemNode = (
+      <li
+        key={key}
+        data-slot="breadcrumb-item"
+        className={cn(
+          'cn-breadcrumb-item',
+          isFirst || isLast ? 'inline-flex' : REVEAL_AT_TIER_CLASSES[tierForDepth(depthFromEnd)],
+        )}
+        aria-current={isLast ? 'page' : undefined}
+      >
+        {!isFirst && (
+          <LuChevronRight aria-hidden strokeWidth={2.5} className="cn-breadcrumb-separator" />
+        )}
+
+        {item.href && !isLast ? (
+          <Link href={item.href} appearance={BREADCRUMB_LINK_APPEARANCES[appearance]}>
+            {item.label}
+          </Link>
+        ) : (
+          <span className="cn-breadcrumb-page">{item.label}</span>
+        )}
+      </li>
+    );
+
+    if (isFirst && ellipsisTier) {
+      return [
+        itemNode,
+        <li
+          key="ellipsis"
+          aria-hidden
+          data-slot="breadcrumb-ellipsis"
+          className={cn('cn-breadcrumb-item', ELLIPSIS_TIER_CLASSES[ellipsisTier])}
+        >
+          <LuChevronRight aria-hidden strokeWidth={2.5} className="cn-breadcrumb-separator" />
+
+          <span className="cn-breadcrumb-ellipsis-text">…</span>
+        </li>,
+      ];
+    }
+
+    return [itemNode];
+  });
+
+  return (
+    <nav
+      aria-label="Breadcrumb"
+      data-slot="breadcrumb"
+      data-appearance={appearance}
+      className={cn('cn-breadcrumb', className)}
+      {...props}
+    >
+      <ol data-slot="breadcrumb-list" className="cn-breadcrumb-list">
+        {listItems}
+      </ol>
+    </nav>
+  );
+};

package/src/components/Button/Button.css

@@ -0,0 +1,229 @@
+/* MARK: Sizes */
+
+@utility cn-button-size-sm {
+  &:not([data-variant='icon']) {
+    /* min-height target is 32px, minus whatever --cn-button-shadow-size the
+       appearance adds below the box (see MARK: Base button), so the total
+       visual footprint (box + shadow) always lands on 32px. */
+    @apply text-sm w-auto;
+    min-height: calc(2rem - var(--cn-button-shadow-size, 0px));
+    padding-block: calc(var(--spacing-gds-1) - var(--border-width-form));
+    padding-inline: var(--spacing-gds-2);
+  }
+
+  &[data-variant='icon'] {
+    /* Width stays fixed (square). Only height gets the same shadow
+       compensation as the text sizes above, so the shadow can render while
+       the total footprint (box + shadow) stays a 32px square. */
+    @apply cn-icon-sm;
+    height: calc(2rem - var(--cn-button-shadow-size, 0px));
+  }
+}
+
+@utility cn-button-size-base {
+  &:not([data-variant='icon']) {
+    /* 40px target, matches the fixed 40px (h-10) height of form inputs like
+       Input/Select, so a base-size button in an input group aligns exactly. */
+    @apply text-base w-full sm:w-auto;
+    min-height: calc(2.5rem - var(--cn-button-shadow-size, 0px));
+    padding-block: calc(var(--spacing-gds-1) - var(--border-width-form));
+    padding-inline: var(--spacing-gds-2);
+  }
+
+  &[data-variant='icon'] {
+    @apply cn-icon-base;
+    height: calc(2.5rem - var(--cn-button-shadow-size, 0px));
+  }
+}
+
+@utility cn-button-size-lg {
+  &:not([data-variant='icon']) {
+    /* 48px target, same shadow-compensation as the other sizes. */
+    @apply text-lg sm:w-auto;
+    min-height: calc(3rem - var(--cn-button-shadow-size, 0px));
+    padding-block: calc(var(--spacing-gds-2) - var(--border-width-form));
+    padding-inline: var(--spacing-gds-3);
+  }
+
+  &[data-variant='icon'] {
+    @apply cn-icon-lg;
+    height: calc(3rem - var(--cn-button-shadow-size, 0px));
+  }
+}
+
+/* MARK: Icon variant
+   shrink-0: an icon button is meant to always render as a fixed square, but
+   cn-button's own base sets w-full, so without this, one sitting in a flex
+   row alongside other content (a header toolbar, an InputGroup suffix) would
+   shrink below its intended size once that row runs out of space, same as
+   any other flex-shrink: 1 default. */
+@utility cn-button-variant-icon {
+  @apply shrink-0;
+
+  & svg {
+    @apply w-full h-full;
+  }
+}
+
+/* MARK: Base button */
+
+@utility cn-button {
+  @apply relative border-form border-solid border-transparent no-underline cursor-pointer w-full;
+  /* Generic so every appearance can share one declaration by setting the two
+     variables instead of repeating the box-shadow itself. --cn-button-shadow-size
+     also drives the height compensation in cn-button-size-*, so it should stay
+     constant across states. Use box-shadow: none directly (not the size
+     variable) to hide the bar for a given state, so height math never shifts. */
+  box-shadow: 0 var(--cn-button-shadow-size, 0px) 0 var(--cn-button-shadow-color, transparent);
+
+  /* Extend click target to cover the button's own border on all sides */
+  &::before {
+    @apply content-[''] block absolute bg-transparent;
+    top: calc(var(--border-width-form) * -1);
+    right: calc(var(--border-width-form) * -1);
+    bottom: calc(var(--border-width-form) * -1);
+    left: calc(var(--border-width-form) * -1);
+  }
+
+  /* Active: shift button down and clear the bottom shadow to simulate pressing */
+  &:active:not(:disabled) {
+    transform: translateY(var(--border-width-form));
+  }
+
+  &:active:not(:disabled):not(:focus) {
+    box-shadow: none;
+  }
+
+  &:active:not(:disabled):focus {
+    box-shadow: inset 0 0 0 1px var(--color-focus);
+  }
+
+  /* Focus: yellow border + inset yellow ring. Inset is fine here, the
+     border itself is coloured (not transparent) during focus, so there's no
+     gap for the ring to float over. */
+  &:focus {
+    @apply border-focus;
+    box-shadow: inset 0 0 0 1px var(--color-focus);
+  }
+
+  /* Focus when not hovered or active: full yellow highlight (GDS pattern).
+     Uses the same --cn-button-shadow-size as the resting appearance shadow
+     below, so it renders (or doesn't) exactly like the appearance's own bar. */
+  &:focus:not(:active):not(:hover) {
+    @apply bg-focus text-on-focus border-focus;
+    box-shadow: 0 var(--cn-button-shadow-size, 0px) 0 var(--color-on-focus);
+  }
+
+  &:disabled {
+    @apply opacity-50;
+  }
+}
+
+/* MARK: Appearances */
+
+/* The bottom "shadow" bar is a flush, non-inset box-shadow, not a
+   border-bottom-color. Colouring only one side of an otherwise-transparent
+   border renders a diagonal miter at the corners (adjacent border edges of
+   different colours always blend diagonally where they meet). A non-inset
+   box-shadow has no adjacent edge to miter against, and unlike an inset
+   shadow, it starts flush against the border-box edge instead of being
+   painted behind the transparent border and looking detached or floating.
+   It does overflow past the border-box, so each shadow-bearing appearance
+   sets --cn-button-shadow-size, which cn-button-size-* subtracts back out of
+   min-height (or, for the icon variant, height). The total visual footprint
+   (box + shadow) always lands on the same size as a sibling form input, and
+   icon buttons stay square because only their height is compensated, not
+   their width. Appearances that don't set the variable (ghost, panel) get
+   0px via the fallback, so no shadow and no compensation. Colour is a
+   separate variable from size so cn-button-link can restore just the colour
+   on active without disturbing the height compensation. */
+
+@utility cn-button-appearance-primary {
+  @apply bg-accent text-on-accent;
+  --cn-button-shadow-size: var(--border-width-form);
+  --cn-button-shadow-color: var(--color-accent-shadow);
+
+  &:hover:not(:disabled) {
+    @apply bg-accent-hover;
+  }
+}
+
+@utility cn-button-appearance-secondary {
+  @apply bg-wash text-body;
+  --cn-button-shadow-size: var(--border-width-form);
+  --cn-button-shadow-color: var(--color-neutral-mid);
+
+  &:hover:not(:disabled) {
+    @apply bg-muted;
+  }
+}
+
+@utility cn-button-appearance-destructive {
+  @apply bg-error text-on-error;
+  --cn-button-shadow-size: var(--border-width-form);
+  --cn-button-shadow-color: var(--color-error-shadow);
+
+  &:hover:not(:disabled) {
+    @apply bg-error-hover;
+  }
+}
+
+@utility cn-button-appearance-inverse {
+  @apply bg-wash text-accent-safe;
+  --cn-button-shadow-size: var(--border-width-form);
+  --cn-button-shadow-color: var(--color-neutral-mid);
+
+  &:hover:not(:disabled) {
+    @apply bg-surface-hover;
+  }
+}
+
+@utility cn-button-appearance-ghost {
+  @apply bg-transparent text-body;
+
+  &:hover:not(:disabled) {
+    @apply bg-transparent;
+  }
+
+  &:focus:not(:active):not(:hover) {
+    @apply shadow-none;
+  }
+
+  /* Ghost has no bottom border to press into, so no shift or border clear */
+  &:active:not(:disabled) {
+    @apply bg-black/5 transform-none;
+  }
+}
+
+@utility cn-button-appearance-panel {
+  @apply panel text-body;
+
+  &:focus:not(:active):not(:hover) {
+    @apply shadow-none;
+  }
+
+  /* bg-black/5 (ghost's treatment, copied here originally) is a
+     semi-transparent overlay, fine over ghost's own transparent background,
+     but here it replaces panel's opaque bg-panel outright rather than
+     layering on top of it, so the button looks like it's gone transparent
+     instead of staying solid and going slightly darker. bg-muted is a real
+     solid colour, one step down the same neutral scale panel's white sits
+     on top of. */
+  &:active:not(:disabled) {
+    @apply bg-muted transform-none;
+  }
+}
+
+/* MARK: Variants */
+
+@utility cn-button-variant-cta {
+  @apply font-bold;
+}
+
+/* MARK: Skeleton
+   min-height on cn-button-size-* already guarantees the outer box matches a
+   real button regardless of content, so this bar just needs to look
+   reasonable inside it, not hit an exact height. */
+@utility cn-button-skeleton-bar {
+  @apply h-[0.6em] w-16;
+}

package/src/components/Button/Button.stories.tsx

@@ -1,38 +1,158 @@
+import { LuCopy } from 'react-icons/lu';
 import { action } from 'storybook/actions';
 
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { Button } from './Button';
 
-export default {
-  children: 'Button',
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button/Button',
   component: Button,
-} as Meta;
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use the button component to help users carry out an action like starting an application or saving their information.',
+      },
+    },
+  },
+  argTypes: {
+    appearance: {
+      control: { type: 'radio' },
+      options: ['primary', 'secondary', 'destructive', 'inverse', 'ghost', 'panel'],
+    },
+    variant: {
+      control: { type: 'radio' },
+      options: ['default', 'cta', 'icon'],
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['base', 'sm', 'lg'],
+    },
+    onClick: { action: 'onClick' },
+    asChild: { control: 'boolean' },
+    children: { control: 'text' },
+  },
+  args: {
+    appearance: 'primary',
+    size: 'base',
+    children: 'Button',
+    onClick: action('onClick'),
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = {
+  args: {
+    appearance: 'primary',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    appearance: 'secondary',
+  },
+};
+
+export const Destructive: Story = {
+  args: {
+    appearance: 'destructive',
+  },
+};
+
+export const Inverse: Story = {
+  args: {
+    appearance: 'inverse',
+  },
+};
+
+export const Ghost: Story = {
+  args: {
+    appearance: 'ghost',
+  },
+};
+
+export const Panel: Story = {
+  args: {
+    appearance: 'panel',
+  },
+};
+
+export const IconButton: Story = {
+  args: {
+    variant: 'icon',
+    children: <LuCopy />,
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-3">
+      <Button {...args} size="sm">
+        SM
+      </Button>
+
+      <Button {...args} size="base">
+        Default
+      </Button>
 
-export const AllButtons: StoryObj<typeof Button> = {
-  render: () => (
-    <div className="flex flex-col gap-4">
-      <div>
-        <Button variant="primary" onClick={action('primary-click')}>
-          Primary
+      <Button {...args} size="lg">
+        LG
+      </Button>
+    </div>
+  ),
+};
+
+export const ClickToAction: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-3">
+        <Button {...args} appearance="primary" variant="cta">
+          Primary CTA
         </Button>
-      </div>
 
-      <div>
-        <Button variant="secondary" onClick={action('secondary-click')}>
-          Secondary
+        <Button {...args} appearance="secondary" variant="cta">
+          Secondary CTA
         </Button>
-      </div>
 
-      <div className="p-4 bg-brand">
-        <Button variant="inverse" onClick={action('inverse-click')}>
-          Inverse
+        <Button {...args} appearance="inverse" variant="cta">
+          Inverse CTA
         </Button>
       </div>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-3">
+        <Button {...args} appearance="primary" disabled>
+          Primary Disabled
+        </Button>
+
+        <Button {...args} appearance="secondary" disabled>
+          Secondary Disabled
+        </Button>
+
+        <Button {...args} appearance="destructive" disabled>
+          Danger Disabled
+        </Button>
+
+        <Button {...args} appearance="inverse" disabled>
+          Inverse Disabled
+        </Button>
+
+        <Button {...args} appearance="ghost" disabled>
+          Ghost Disabled
+        </Button>
 
-      <div>
-        <Button variant="primary" disabled>
-          Disabled Button
+        <Button {...args} appearance="panel" disabled>
+          Panel Disabled
         </Button>
       </div>
     </div>