@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/NoScriptBanner/NoScriptBanner.tsx

@@ -0,0 +1,26 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+import { Heading } from '../Heading/Heading';
+import { HeadingGroup } from '../Layout/HeadingGroup/HeadingGroup';
+
+export type NoScriptBannerProps = ComponentProps<'div'>;
+
+export const NoScriptBanner = ({ className, children, ...props }: NoScriptBannerProps) => (
+  <noscript>
+    <div
+      role="region"
+      aria-label="JavaScript is not available"
+      className={cn('cn-noscript-banner', className)}
+      {...props}
+    >
+      <div className="cn-noscript-banner-inner">
+        <HeadingGroup>
+          <Heading level="h2">JavaScript is not available</Heading>
+
+          {children}
+        </HeadingGroup>
+      </div>
+    </div>
+  </noscript>
+);

package/src/components/Paragraph/Paragraph.css

@@ -0,0 +1,22 @@
+@layer components {
+  /* MARK: Paragraph */
+  .cn-paragraph {
+    @apply text-base;
+  }
+
+  /* MARK: Skeleton
+     Stacks one bar per wrapped line. Overrides cn-skeleton's inline-block,
+     these are meant to be full lines, not inline text. */
+  .cn-paragraph-skeleton {
+    @apply flex flex-col gap-2;
+  }
+
+  .cn-paragraph-skeleton-line {
+    @apply block h-4 w-full;
+  }
+
+  /* Shorter, matching where real wrapped text would naturally end mid-line. */
+  .cn-paragraph-skeleton-line-last {
+    @apply w-3/4;
+  }
+}

package/src/components/Paragraph/Paragraph.stories.tsx

@@ -1,24 +1,16 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { Paragraph } from './Paragraph';
-import { ExternalLink } from '../link/ExternalLink';
 
 const meta: Meta<typeof Paragraph> = {
-  title: 'Components/Paragraph',
+  title: 'Components/Paragraph/Paragraph',
   component: Paragraph,
-  parameters: {
-    layout: 'padded',
-  },
   tags: ['autodocs'],
   argTypes: {
     children: {
       description: 'Content of the paragraph',
       control: false,
     },
-    className: {
-      description: 'Additional TailwindCSS classes to apply to the paragraph',
-      control: 'text',
-    },
   },
   args: {
     children: 'Hello, this is some simple text',
@@ -31,13 +23,6 @@ type Story = StoryObj<typeof Paragraph>;
 
 export const Default: Story = {};
 
-export const CustomStyling: Story = {
-  args: {
-    className: 'text-yellow-800 p-2',
-    children: 'Hello, this is some simple text with custom styling',
-  },
-};
-
 export const LongText: Story = {
   args: {
     children:
@@ -45,29 +30,3 @@ export const LongText: Story = {
       'It is used to test how the Paragraph component handles large amounts of text.',
   },
 };
-
-export const WithLink: Story = {
-  args: {
-    children: (
-      <span>
-        This paragraph contains a <ExternalLink href="https://storybook.js.org/">link</ExternalLink>
-        .
-      </span>
-    ),
-  },
-};
-
-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>
-    ),
-  },
-};

package/src/components/Paragraph/Paragraph.tsx

@@ -1,11 +1,12 @@
-import type { ExtendProps } from '../../types/utils';
+import type { ComponentProps } from 'react';
+
 import { cn } from '../../utils';
 
-export type ParagraphProps = ExtendProps<'p'>;
+export type ParagraphProps = ComponentProps<'p'>;
 
 export const Paragraph = ({ className, children, ...props }: ParagraphProps) => {
   return (
-    <p className={cn('pb-4 text-sm text-text-primary', className)} {...props}>
+    <p className={cn('cn-paragraph', className)} {...props}>
       {children}
     </p>
   );

package/src/components/Paragraph/ParagraphSkeleton.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ParagraphSkeleton } from './ParagraphSkeleton';
+
+const meta: Meta<typeof ParagraphSkeleton> = {
+  title: 'Components/Paragraph/Skeleton',
+  component: ParagraphSkeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Placeholder for a Paragraph while its real text is loading. Renders one bar per wrapped line (`lines`, defaults to 3), with the last line narrower to mimic where real text naturally wraps.',
+      },
+    },
+  },
+  argTypes: {
+    lines: { control: { type: 'number', min: 1, max: 6 } },
+  },
+  args: {
+    lines: 3,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ParagraphSkeleton>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="max-w-md">
+      <ParagraphSkeleton {...args} />
+    </div>
+  ),
+};
+
+export const SingleLine: Story = {
+  args: { lines: 1 },
+  render: (args) => (
+    <div className="max-w-md">
+      <ParagraphSkeleton {...args} />
+    </div>
+  ),
+};

package/src/components/Paragraph/ParagraphSkeleton.tsx

@@ -0,0 +1,33 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+import { Skeleton } from '../Skeleton/Skeleton';
+
+// Stable, fixed identifiers rather than the array index, even though these
+// are decorative and never reorder, so a line's identity is never tied to
+// its position at render time.
+const LINE_KEYS = ['line-1', 'line-2', 'line-3', 'line-4', 'line-5', 'line-6'] as const;
+
+export type ParagraphSkeletonProps = Omit<ComponentProps<'div'>, 'children'> & {
+  children?: never;
+  /** Number of wrapped lines to show. Defaults to 3. */
+  lines?: number;
+};
+
+export const ParagraphSkeleton = ({ className, lines = 3, ...props }: ParagraphSkeletonProps) => {
+  const lineKeys = LINE_KEYS.slice(0, lines);
+
+  return (
+    <div aria-hidden className={cn('cn-paragraph-skeleton', className)} {...props}>
+      {lineKeys.map((key, index) => (
+        <Skeleton
+          key={key}
+          className={cn(
+            'cn-paragraph-skeleton-line',
+            index === lineKeys.length - 1 && 'cn-paragraph-skeleton-line-last',
+          )}
+        />
+      ))}
+    </div>
+  );
+};

package/src/components/PasswordInput/PasswordInput.css

@@ -0,0 +1,3 @@
+@layer components {
+  /* PasswordInput uses InputGroup/InputSuffix from Input.css so no custom layout needed. */
+}

package/src/components/PasswordInput/PasswordInput.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { PasswordInput } from './PasswordInput';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof PasswordInput> = {
+  title: 'Components/PasswordInput',
+  component: PasswordInput,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Help users to create and enter passwords.',
+      },
+    },
+  },
+  argTypes: {},
+  args: {},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof PasswordInput>;
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  render: () => (
+    <fieldset disabled>
+      <PasswordInput />
+    </fieldset>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <FormGroup invalid>
+      <Label htmlFor="password-invalid">Password</Label>
+
+      <ErrorText id="password-error">Enter your password</ErrorText>
+
+      <PasswordInput id="password-invalid" aria-invalid aria-describedby="password-error" />
+    </FormGroup>
+  ),
+};

package/src/components/PasswordInput/PasswordInput.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { useId, useState, type ComponentProps } from 'react';
+
+import { LuEye, LuEyeClosed } from 'react-icons/lu';
+
+import { Button } from '../Button/Button';
+import { Input } from '../Input/Input';
+import { InputGroup, InputSuffix } from '../InputGroup/InputGroup';
+
+export type PasswordInputProps = Omit<
+  ComponentProps<typeof Input>,
+  'type' | 'size' | 'appearance' | 'children'
+>;
+
+export const PasswordInput = ({ autoComplete, id, ...props }: PasswordInputProps) => {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+
+  const [shown, setShown] = useState(false);
+
+  return (
+    <InputGroup>
+      <Input
+        id={inputId}
+        type={shown ? 'text' : 'password'}
+        autoComplete={autoComplete ?? 'current-password'}
+        spellCheck={false}
+        {...props}
+      />
+
+      <InputSuffix>
+        <Button
+          appearance="secondary"
+          variant="icon"
+          aria-label={shown ? 'Hide password' : 'Show password'}
+          aria-controls={inputId}
+          onClick={() => setShown((previous) => !previous)}
+        >
+          {shown ? <LuEye aria-hidden /> : <LuEyeClosed aria-hidden />}
+        </Button>
+      </InputSuffix>
+    </InputGroup>
+  );
+};

package/src/components/PhaseBanner/PhaseBanner.css

@@ -0,0 +1,12 @@
+@layer components {
+  /* MARK: Phase banner
+     Displayed at the top of the page to communicate service phase (Alpha, Beta).
+     Bottom border matches GDS. Layout is flex rather than the legacy display:table. */
+  .cn-phase-banner {
+    @apply py-gds-2 border-b border-divider;
+  }
+
+  .cn-phase-banner-content {
+    @apply flex items-center gap-gds-2 text-base m-0;
+  }
+}

package/src/components/PhaseBanner/PhaseBanner.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { PhaseBanner } from './PhaseBanner';
+import { Link } from '../Link/Link';
+import { Tag } from '../Tag/Tag';
+
+const meta: Meta<typeof PhaseBanner> = {
+  title: 'Components/PhaseBanner',
+  component: PhaseBanner,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Displayed at the top of a page to communicate that a service is in an early development phase. Accepts a `Tag` via the `tag` prop and descriptive text as `children`.',
+      },
+    },
+  },
+  args: {
+    children: 'This is a new service – your feedback will help us to improve it.',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof PhaseBanner>;
+
+export const Alpha: Story = {
+  args: {
+    tag: (
+      <Tag size="sm" appearance="info">
+        Alpha
+      </Tag>
+    ),
+  },
+};
+
+export const Beta: Story = {
+  args: {
+    tag: (
+      <Tag size="sm" appearance="info">
+        Beta
+      </Tag>
+    ),
+  },
+};
+
+export const WithFeedbackLink: Story = {
+  args: {
+    tag: (
+      <Tag size="sm" appearance="info">
+        Beta
+      </Tag>
+    ),
+    children: (
+      <>
+        This is a new service – <Link href="#">give your feedback</Link> to help us improve it.
+      </>
+    ),
+  },
+};

package/src/components/PhaseBanner/PhaseBanner.tsx

@@ -0,0 +1,17 @@
+import type { ComponentProps, ReactElement } from 'react';
+
+import { cn } from '../../utils/components';
+import { Tag } from '../Tag/Tag';
+
+export type PhaseBannerProps = ComponentProps<'div'> & {
+  tag: ReactElement<ComponentProps<typeof Tag>, typeof Tag>;
+};
+
+export const PhaseBanner = ({ tag, children, className, ...props }: PhaseBannerProps) => (
+  <div data-slot="phase-banner" className={cn('cn-phase-banner', className)} {...props}>
+    <p className="cn-phase-banner-content">
+      {tag}
+      <span className="cn-phase-banner-text">{children}</span>
+    </p>
+  </div>
+);

package/src/components/Popover/Popover.css

@@ -0,0 +1,43 @@
+@layer components {
+  /* MARK: Popover content
+     Same panel treatment as Tooltip (panel bg + border) but with more
+     padding and no max-width cap, consumers control width via className.
+     Portal-rendered so DOM order is always safe above page content, but
+     cn-z-overlay still matters against other elements that set their own
+     high z-index (e.g. a resizable handle's cn-z-top). */
+  .cn-popover-content {
+    @apply panel cn-z-overlay p-gds-3 text-base text-body;
+
+    &[data-state='open'] {
+      animation: cn-popover-in 0.1s ease-out;
+    }
+
+    &[data-state='closed'] {
+      animation: cn-popover-out 0.075s ease-in;
+    }
+  }
+
+  .cn-popover-arrow {
+    fill: var(--color-panel-border);
+  }
+
+  @keyframes cn-popover-in {
+    from {
+      opacity: 0;
+      transform: scale(0.97);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+
+  @keyframes cn-popover-out {
+    from {
+      opacity: 1;
+    }
+    to {
+      opacity: 0;
+    }
+  }
+}

package/src/components/Popover/Popover.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Popover, PopoverContent, PopoverTrigger } from './Popover';
+import { Button } from '../Button/Button';
+import { Label } from '../Label/Label';
+import { Paragraph } from '../Paragraph/Paragraph';
+import { Textarea } from '../Textarea/Textarea';
+
+const meta: Meta<typeof Popover> = {
+  title: 'Components/Popover',
+  component: Popover,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A floating panel anchored to a trigger element, activated by click or tap. Use it to surface supplementary content, filters, or short forms without navigating away from the current page. Because it activates on click rather than hover, it works correctly on both desktop and touch devices. Prefer Popover over Tooltip whenever touch support is needed or the content is longer than a short label.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Popover>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="flex items-center justify-center min-h-40">
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button appearance="secondary">More information</Button>
+        </PopoverTrigger>
+
+        <PopoverContent>
+          <Paragraph>
+            Payments are issued quarterly once your evidence has been reviewed and approved by your
+            area coordinator.
+          </Paragraph>
+        </PopoverContent>
+      </Popover>
+    </div>
+  ),
+};
+
+export const WithForm: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Interactive content inside the popover. Popover does not trap focus, so tab order continues naturally through any form controls inside it.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center justify-center min-h-40">
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button appearance="secondary">Add note</Button>
+        </PopoverTrigger>
+
+        <PopoverContent className="w-72">
+          <div className="flex flex-col gap-gds-2">
+            <Label className="text-sm font-bold" htmlFor="popover-note">
+              Note
+            </Label>
+
+            <Textarea id="popover-note" rows={3} placeholder="Enter a note..." />
+
+            <Button className="self-end">Save</Button>
+          </div>
+        </PopoverContent>
+      </Popover>
+    </div>
+  ),
+};
+
+export const Positions: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The popover repositions automatically when it would overflow the viewport, but you can set a preferred side.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex gap-gds-4 flex-wrap items-center justify-center min-h-40">
+      {(['top', 'right', 'bottom', 'left'] as const).map((side) => (
+        <Popover key={side}>
+          <PopoverTrigger asChild>
+            <Button appearance="secondary">{side}</Button>
+          </PopoverTrigger>
+
+          <PopoverContent side={side}>
+            <Paragraph>Appears on the {side}</Paragraph>
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  ),
+};

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { Popover as PopoverPrimitive } from 'radix-ui';
+
+import { cn } from '../../utils/components';
+
+export const Popover = ({ ...props }: ComponentProps<typeof PopoverPrimitive.Root>) => (
+  <PopoverPrimitive.Root data-slot="popover" {...props} />
+);
+
+export const PopoverTrigger = ({ ...props }: ComponentProps<typeof PopoverPrimitive.Trigger>) => (
+  <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
+);
+
+export const PopoverAnchor = ({ ...props }: ComponentProps<typeof PopoverPrimitive.Anchor>) => (
+  <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />
+);
+
+export const PopoverContent = ({
+  className,
+  align = 'center',
+  sideOffset = 6,
+  children,
+  ...props
+}: ComponentProps<typeof PopoverPrimitive.Content>) => (
+  <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Content
+      data-slot="popover-content"
+      align={align}
+      sideOffset={sideOffset}
+      className={cn('cn-popover-content', className)}
+      {...props}
+    >
+      {children}
+      <PopoverPrimitive.Arrow className="cn-popover-arrow" />
+    </PopoverPrimitive.Content>
+  </PopoverPrimitive.Portal>
+);

package/src/components/Radio/Radio.css

@@ -0,0 +1,69 @@
+@layer components {
+  /* MARK: Radio
+     Radix RadioGroup.Item renders a <button role="radio">.
+     Border is explicit (not @apply cn-form-border) because appearance:none on
+     <button> can override utility-layer border styles. */
+  .cn-radio {
+    @apply relative rounded-full appearance-none cursor-pointer flex-none box-border bg-white p-0
+      outline-none;
+    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);
+    }
+
+    &:disabled {
+      @apply opacity-50 cursor-not-allowed;
+    }
+  }
+
+  /* MARK: Indicator
+     RadioGroup.Indicator only mounts when checked, styled as a black dot.
+     Absolutely positioned + translate(-50%, -50%) rather than the parent's
+     flex items-center/justify-center: flex centering resolves (container -
+     item) / 2 during layout, which has to snap to a whole device pixel, so
+     a fractional remainder rounds asymmetrically (one side up, one down) at
+     1x DPR, visible as the dot sitting a pixel off-centre, while the exact
+     same fraction is imperceptible at 2x/3x DPR where it still lands on a
+     clean device pixel either way. translate is resolved in the compositor
+     rather than layout, so it isn't pixel-snapped the same way. This also
+     matches real GDS: govuk-radios positions its own dot with absolute
+     top/left, not flexbox. */
+  .cn-radio-indicator {
+    @apply absolute top-1/2 left-1/2 -translate-1/2 block rounded-full bg-body;
+  }
+
+  /* MARK: Sizes */
+  .cn-radio-size-sm {
+    @apply w-6 h-6;
+
+    & .cn-radio-indicator {
+      @apply w-3 h-3;
+    }
+  }
+
+  .cn-radio-size-base {
+    @apply w-10 h-10;
+
+    & .cn-radio-indicator {
+      @apply w-5 h-5;
+    }
+  }
+
+  /* MARK: Group
+     gap-gds-2 matches GDS's own govuk-radios__item margin-bottom (10px).
+     Radix reflects the orientation prop as aria-orientation on the group's
+     own root, but doesn't do anything visual with it itself (it's only used
+     internally for arrow-key roving focus direction), so the row layout for
+     orientation="horizontal" has to be applied here. flex-wrap + the wider
+     gap-x match GDS's own govuk-radios--inline (wraps rather than
+     overflowing, govuk-spacing(4) between items horizontally). */
+  .cn-radio-group {
+    @apply flex flex-col gap-gds-2;
+
+    &[aria-orientation='horizontal'] {
+      @apply flex-row flex-wrap items-center gap-x-gds-4 gap-y-gds-2;
+    }
+  }
+}