@tpzdsp/next-toolkit 2.5.1 → 3.0.0

package/src/components/Hero/Hero.tsx

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+import { WidthContainer } from '../Layout/WidthContainer/WidthContainer';
+
+export type HeroProps = ComponentProps<typeof WidthContainer>;
+
+export const Hero = ({ className, children, ...props }: HeroProps) => {
+  return (
+    <WidthContainer className={cn('cn-hero', className)} {...props}>
+      <section aria-label="Introduction">{children}</section>
+    </WidthContainer>
+  );
+};

package/src/components/HintText/HintText.css

@@ -0,0 +1,5 @@
+@layer components {
+  .cn-hint-text {
+    @apply text-body-secondary text-base;
+  }
+}

package/src/components/HintText/HintText.stories.tsx

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { HintText } from './HintText';
+
+const meta: Meta<typeof HintText> = {
+  title: 'Components/HintText',
+  component: HintText,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use hint text for help that’s relevant to the majority of users, like how their information will be used, or where to find it.',
+      },
+    },
+  },
+  argTypes: {
+    children: { control: 'text' },
+  },
+  args: {
+    children: 'For example, 27 3 2007',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof HintText>;
+
+export const Default: Story = {};

package/src/components/HintText/HintText.tsx

@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type HintTextProps = ComponentProps<'div'>;
+
+export const HintText = ({ className, children, ...props }: HintTextProps) => {
+  return (
+    <div className={cn('cn-hint-text', className)} {...props}>
+      {children}
+    </div>
+  );
+};

package/src/components/InfoBox/InfoBox.css

@@ -0,0 +1,38 @@
+/* MARK: InfoBox trigger
+   Sized in em, not one of Button's fixed icon sizes (cn-icon-sm/base/lg,
+   32/40/48px), those are toolbar/form-control sized and force a much taller
+   line box than intended when the trigger sits inline next to running text
+   in a Paragraph or Label. 1.25em scales with whatever text it's next to
+   instead, staying proportionate whether that's body copy or a heading.
+   Bypasses Button entirely (rather than the shared component with a
+   className override) since cn-button-size-* always sets its own
+   width/height, applying cn-button's own base w-full directly here as well
+   (both @utility, same "utilities" layer) means the two compete on equal
+   footing, and which one wins turns out not to follow @import order (tested:
+   Tailwind doesn't emit @utility rules in file-import order), so width/
+   height/padding are !important here, the only way to reliably win against
+   another same-layer utility whose output order isn't otherwise
+   controllable. */
+@utility cn-info-box-trigger {
+  @apply relative inline-flex shrink-0 items-center justify-center;
+  width: 1.25em !important;
+  height: 1.25em !important;
+  padding: 0 !important;
+  /* Best-effort alignment with adjacent text, middle sits a little above the
+     baseline (roughly the x-height midpoint), closer to visually centred
+     against a line of text than the inline-block default of baseline. */
+  vertical-align: middle;
+
+  /* Expands the hit area without changing the visual size, matching the
+     resizable handle's ::after technique, small inline icons are otherwise
+     an easy miss target, particularly on touch. */
+  &::after {
+    content: '';
+    position: absolute;
+    inset: -0.375em;
+  }
+}
+
+@utility cn-info-box-icon {
+  @apply h-full w-full;
+}

package/src/components/InfoBox/InfoBox.stories.tsx

@@ -1,460 +1,108 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { InfoBox } from './InfoBox';
+import { Label } from '../Label/Label';
+import { Paragraph } from '../Paragraph/Paragraph';
 
-const meta = {
+const meta: Meta<typeof InfoBox> = {
   title: 'Components/InfoBox',
   component: InfoBox,
-  parameters: {
-    layout: 'centered',
-    docs: {
-      description: {
-        component:
-          'An accessible info box component that displays contextual information in a popover triggered by an info icon button. Uses Floating UI for intelligent auto-positioning that adapts to viewport constraints.',
-      },
-    },
-  },
   tags: ['autodocs'],
-  argTypes: {
-    title: {
-      control: 'text',
-      description: 'Optional title displayed at the top of the info box content',
-    },
-    defaultOpen: {
-      control: 'boolean',
-      description: 'Whether the info box starts open',
-      defaultValue: false,
-    },
-    maxWidth: {
-      control: 'text',
-      description: 'Maximum width of the content box (default: 320px)',
-    },
-    triggerLabel: {
-      control: 'text',
-      description: 'Accessible label for the trigger button',
-    },
-    placement: {
-      control: 'select',
-      options: [
-        'top',
-        'top-start',
-        'top-end',
-        'bottom',
-        'bottom-start',
-        'bottom-end',
-        'left',
-        'left-start',
-        'left-end',
-        'right',
-        'right-start',
-        'right-end',
-      ],
-      description:
-        'Preferred placement (Floating UI will auto-adjust if there is not enough space)',
-    },
-    children: {
-      control: false,
-      description: 'Content to display inside the info box',
-    },
-    onOpenChange: {
-      action: 'onOpenChange',
-      description: 'Callback when the info box opens or closes',
-    },
-  },
-} satisfies Meta<typeof InfoBox>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: {
-    children: <p>This is helpful information about this feature.</p>,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Basic info box with simple text content. Click the info icon to open.',
-      },
-    },
-  },
-};
-
-export const WithTitle: Story = {
-  args: {
-    title: 'Important Information',
-    children: (
-      <div className="space-y-2">
-        <p>Here are some key points to remember:</p>
-
-        <ul className="list-disc list-inside text-sm">
-          <li>Point one</li>
-
-          <li>Point two</li>
-
-          <li>Point three</li>
-        </ul>
-      </div>
-    ),
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Info box with a title header for more structured content.',
-      },
-    },
-  },
-};
-
-export const DefaultOpen: Story = {
-  args: {
-    title: 'Getting Started',
-    defaultOpen: true,
-    children: <p>This info box starts open by default.</p>,
-  },
   parameters: {
     docs: {
       description: {
-        story: 'Info box that starts in the open state.',
-      },
-    },
-  },
-};
-
-export const LongContent: Story = {
-  args: {
-    title: 'Detailed Information',
-    maxWidth: '400px',
-    children: (
-      <div className="space-y-2 max-h-48 overflow-y-auto">
-        <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt
-          ut labore et dolore magna aliqua.
-        </p>
-
-        <p>
-          Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
-          commodo consequat.
-        </p>
-
-        <p>
-          Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat
-          nulla pariatur.
-        </p>
-
-        <p>
-          Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
-          anim id est laborum.
-        </p>
-      </div>
-    ),
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Info box with longer scrollable content and custom max width.',
+        component:
+          'A small icon that opens a Popover panel, the standard pattern for surfacing supplementary information next to a label, heading, or inline within running text, without cluttering the layout. Sized in em rather than one of the fixed icon-button sizes, so it scales with and sits inline alongside whatever text surrounds it. Because it uses Popover (click/tap activated) rather than Tooltip, it works correctly on touch devices.',
       },
     },
   },
 };
 
-export const AllPositions: Story = {
-  args: {
-    children: null,
-  },
-  parameters: {
-    layout: 'fullscreen',
-    docs: {
-      description: {
-        story:
-          'Demonstrates various placement options using Floating UI. The content will automatically adjust if there is not enough space.',
-      },
-    },
-  },
-  render: () => (
-    <div className="p-8 grid grid-cols-2 gap-8 h-screen">
-      <div className="flex items-start justify-start">
-        <div className="flex items-center gap-2">
-          <span className="text-sm text-gray-600">bottom-start:</span>
-
-          <InfoBox title="Position Demo" placement="bottom-start">
-            <p>Prefers bottom-start placement.</p>
-          </InfoBox>
-        </div>
-      </div>
-
-      <div className="flex items-start justify-end">
-        <div className="flex items-center gap-2">
-          <span className="text-sm text-gray-600">bottom-end:</span>
-
-          <InfoBox title="Position Demo" placement="bottom-end">
-            <p>Prefers bottom-end placement.</p>
-          </InfoBox>
-        </div>
-      </div>
-
-      <div className="flex items-end justify-start">
-        <div className="flex items-center gap-2">
-          <span className="text-sm text-gray-600">top-start:</span>
-
-          <InfoBox title="Position Demo" placement="top-start">
-            <p>Prefers top-start placement.</p>
-          </InfoBox>
-        </div>
-      </div>
+export default meta;
 
-      <div className="flex items-end justify-end">
-        <div className="flex items-center gap-2">
-          <span className="text-sm text-gray-600">top-end:</span>
+type Story = StoryObj<typeof InfoBox>;
 
-          <InfoBox title="Position Demo" placement="top-end">
-            <p>Prefers top-end placement.</p>
-          </InfoBox>
-        </div>
-      </div>
-    </div>
+export const Default: Story = {
+  render: (args) => (
+    <InfoBox {...args}>
+      This field is used to calculate your baseline figures for the agreement period.
+    </InfoBox>
   ),
 };
 
-export const InCorners: Story = {
-  args: {
-    children: null,
-  },
+export const InParagraph: Story = {
   parameters: {
-    layout: 'fullscreen',
     docs: {
       description: {
-        story:
-          'Demonstrates auto-positioning when the info box is placed in different corners of the viewport. The info box automatically positions itself to stay visible.',
+        story: 'Placed inline within running text, immediately after the sentence it expands on.',
       },
     },
   },
-  render: () => (
-    <div className="relative h-screen w-full">
-      <div className="absolute top-4 left-4 flex items-center gap-2">
-        <InfoBox>
-          <p>Auto-positioned from top-left corner. Should open to bottom-right.</p>
-        </InfoBox>
-
-        <span className="text-xs text-gray-500">Top-left corner</span>
-      </div>
-
-      <div className="absolute top-4 right-4 flex items-center gap-2">
-        <span className="text-xs text-gray-500">Top-right corner</span>
-
-        <InfoBox>
-          <p>Auto-positioned from top-right corner. Should open to bottom-left.</p>
-        </InfoBox>
-      </div>
-
-      <div className="absolute bottom-4 left-4 flex items-center gap-2">
-        <InfoBox>
-          <p>Auto-positioned from bottom-left corner. Should open to top-right.</p>
-        </InfoBox>
-
-        <span className="text-xs text-gray-500">Bottom-left corner</span>
-      </div>
-
-      <div className="absolute bottom-4 right-4 flex items-center gap-2">
-        <span className="text-xs text-gray-500">Bottom-right corner</span>
-
-        <InfoBox>
-          <p>Auto-positioned from bottom-right corner. Should open to top-left.</p>
-        </InfoBox>
-      </div>
-
-      <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 text-center">
-        <p className="text-gray-400 text-sm">
-          Click the info icons in each corner to see auto-positioning
-        </p>
-      </div>
-    </div>
+  render: (args) => (
+    <Paragraph>
+      This field is used to calculate your baseline figures for the agreement period.{' '}
+      <InfoBox {...args}>
+        The 12-month window used to calculate your baseline figures. This must fall within your
+        agreement start and end dates.
+      </InfoBox>
+    </Paragraph>
   ),
 };
 
-export const WithInteractiveContent: Story = {
-  args: {
-    title: 'Take Action',
-    children: (
-      <div className="space-y-3">
-        <p className="text-sm">You can interact with elements inside:</p>
-
-        <input
-          type="text"
-          placeholder="Type something..."
-          className="w-full px-3 py-2 text-sm border border-gray-300 rounded focus:outline-none
-            focus:ring-2 focus:ring-blue-500"
-        />
-
-        <button
-          type="button"
-          className="w-full px-4 py-2 text-sm text-white bg-blue-600 rounded hover:bg-blue-700
-            focus:outline-none focus:ring-2 focus:ring-blue-500"
-        >
-          Submit
-        </button>
-      </div>
-    ),
-  },
+export const WithCustomWidth: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          'Info box with interactive content (form elements). Focus is trapped within the info box when open.',
+          'Defaults to max-w-xs so it never grows too wide regardless of content length. Pass a different max-w-* via className to override it.',
       },
     },
   },
-};
-
-export const InlineWithText: Story = {
-  args: {
-    children: null,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Info box used inline with paragraph text to provide contextual information.',
-      },
-    },
-  },
-  render: () => (
-    <div className="max-w-md p-4">
-      <p className="text-sm leading-relaxed">
-        This is a paragraph with an inline info box{' '}
-        <span className="inline-flex align-middle mx-1">
-          <InfoBox triggerLabel="Learn more about this term">
-            <p>Additional context about the preceding text that helps explain the concept.</p>
-          </InfoBox>
-        </span>{' '}
-        that provides more context about a specific term or concept in the text.
-      </p>
-    </div>
+  render: (args) => (
+    <InfoBox {...args} className="max-w-sm">
+      This is a longer explanation than usual, spanning more than a couple of lines, to demonstrate
+      that the popover still wraps at a sensible width rather than growing to fit all of it on fewer
+      lines.
+    </InfoBox>
   ),
 };
 
-export const CustomTriggerLabel: Story = {
-  args: {
-    triggerLabel: 'Learn more about data privacy',
-    title: 'Data Privacy',
-    children: (
-      <div className="space-y-2 text-sm">
-        <p>Your data is handled securely and in accordance with our privacy policy.</p>
-
-        <a href="https://example.com" className="text-blue-600 hover:underline">
-          Read our full privacy policy
-        </a>
-      </div>
-    ),
-  },
+export const NextToLabel: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          'Info box with a custom trigger label for better accessibility context. Screen readers will announce the custom label.',
+          'Placed inline at the end of a form label, no extra wrapper needed, it flows as part of the label text.',
       },
     },
   },
-};
-
-export const MultipleInfoBoxes: Story = {
-  args: {
-    children: null,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Multiple info boxes can be used independently on the same page.',
-      },
-    },
-  },
-  render: () => (
-    <div className="space-y-4 p-4">
-      <div className="flex items-center gap-2">
-        <span className="text-sm font-medium">Username</span>
-
-        <InfoBox triggerLabel="Username requirements">
-          <p className="text-sm">Username must be 3-20 characters and contain only letters.</p>
-        </InfoBox>
-      </div>
-
-      <div className="flex items-center gap-2">
-        <span className="text-sm font-medium">Password</span>
-
-        <InfoBox triggerLabel="Password requirements">
-          <div className="text-sm space-y-1">
-            <p>Password must contain:</p>
-
-            <ul className="list-disc list-inside">
-              <li>At least 8 characters</li>
-
-              <li>One uppercase letter</li>
-
-              <li>One number</li>
-            </ul>
-          </div>
-        </InfoBox>
-      </div>
-
-      <div className="flex items-center gap-2">
-        <span className="text-sm font-medium">Email</span>
-
-        <InfoBox triggerLabel="Why we need your email">
-          <p className="text-sm">We use your email for account recovery and important updates.</p>
-        </InfoBox>
-      </div>
-    </div>
+  render: (args) => (
+    <Label htmlFor="reference-period">
+      Reference period{' '}
+      <InfoBox {...args}>
+        The 12-month window used to calculate your baseline figures. This must fall within your
+        agreement start and end dates.
+      </InfoBox>
+    </Label>
   ),
 };
 
-export const Accessibility: Story = {
-  args: {
-    children: null,
-  },
+export const NextToHeading: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'Demonstrates the accessibility features of the InfoBox component.',
+        story:
+          'Can also be placed inline at the end of a section heading when the explanation applies to the whole section rather than a single field.',
       },
     },
   },
-  render: () => (
-    <div className="space-y-6 max-w-md p-4">
-      <div className="bg-blue-50 border border-blue-200 rounded p-4">
-        <h3 className="font-bold text-blue-800 mb-2">Accessibility Features:</h3>
-
-        <ul className="list-disc list-inside space-y-1 text-blue-700 text-sm">
-          <li>Trigger button has aria-expanded and aria-haspopup</li>
-
-          <li>Content has role=&quot;dialog&quot; and aria-modal=&quot;true&quot;</li>
-
-          <li>Focus is trapped within the info box when open</li>
-
-          <li>Escape key closes the info box</li>
-
-          <li>Click outside closes the info box</li>
-
-          <li>Focus returns to trigger on close (via keyboard)</li>
-
-          <li>Title provides aria-labelledby relationship</li>
-        </ul>
-      </div>
-
-      <div className="flex items-center gap-2">
-        <span className="text-sm">Try this accessible info box:</span>
-
-        <InfoBox title="Accessible Info Box" triggerLabel="Show accessibility information">
-          <div className="text-sm space-y-2">
-            <p>This info box demonstrates proper accessibility:</p>
-
-            <ul className="list-disc list-inside">
-              <li>Use Tab to navigate between elements</li>
-
-              <li>Press Escape to close</li>
-
-              <li>Click outside to close</li>
-            </ul>
-          </div>
-        </InfoBox>
-      </div>
-    </div>
+  render: (args) => (
+    <h2 className="text-lg font-bold">
+      Land parcel details{' '}
+      <InfoBox {...args} label="About land parcel details">
+        Land parcels are identified by their OS grid reference. Only parcels registered under your
+        Single Business Identifier are shown.
+      </InfoBox>
+    </h2>
   ),
 };