@tpzdsp/next-toolkit 2.5.1 → 3.1.0

package/src/components/NoScriptBanner/NoScriptBanner.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { NoScriptBanner } from './NoScriptBanner';
+import { Heading } from '../Heading/Heading';
+import { HeadingGroup } from '../Layout/HeadingGroup/HeadingGroup';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+const meta: Meta<typeof NoScriptBanner> = {
+  title: 'Components/NoScriptBanner',
+  component: NoScriptBanner,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Full-width accent-coloured banner shown only when JavaScript is disabled. Renders inside a real \`<noscript>\` element, so the browser (not React) decides whether to show it, place it as the very first element in the DOM, above the header, the same position as the cookie banner.
+
+The title ("JavaScript is not available") is fixed for consistency across apps. Pass children to explain what that means for your specific service.
+
+Because Storybook itself runs on JavaScript, the browser will never actually display this component's \`<noscript>\` content here. The story below is a plain, unwrapped reproduction of the same markup for visual reference only, disable JavaScript in your browser's dev tools against a real page to see the genuine behaviour.
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof NoScriptBanner>;
+
+export const Preview: Story = {
+  render: () => (
+    <div className="cn-noscript-banner">
+      <div className="cn-noscript-banner-inner">
+        <HeadingGroup>
+          <Heading level="h2">JavaScript is not available</Heading>
+
+          <Paragraph>
+            This service needs JavaScript to work. Enable JavaScript in your browser, or contact us
+            for support with an alternative way to apply.
+          </Paragraph>
+        </HeadingGroup>
+      </div>
+    </div>
+  ),
+};

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>
+);