@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Radio/Radio.stories.tsx

@@ -0,0 +1,169 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Radio, RadioGroup } from './Radio';
+import { FieldItem } from '../Fieldset/Fieldset';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof Radio> = {
+  title: 'Components/Radio',
+  component: Radio,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use the radios component when users can only select one option from a list.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: { type: 'radio' },
+      options: ['sm', 'base'],
+    },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    size: 'base',
+    value: 'default',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Radio>;
+
+export const Default: Story = {
+  render: (args) => (
+    <RadioGroup>
+      <Radio {...args} />
+    </RadioGroup>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-gds-4">
+      <div className="flex flex-col items-center gap-gds-1">
+        <RadioGroup>
+          <Radio size="sm" value="sm" id="radio-size-sm" />
+        </RadioGroup>
+
+        <Label htmlFor="radio-size-sm">sm</Label>
+      </div>
+
+      <div className="flex flex-col items-center gap-gds-1">
+        <RadioGroup>
+          <Radio size="base" value="base" id="radio-size-base" />
+        </RadioGroup>
+
+        <Label htmlFor="radio-size-base">base</Label>
+      </div>
+    </div>
+  ),
+};
+
+export const WithLabels: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Standard radio group with labels. Arrow keys move between options, `RadioGroup` manages focus and selection.',
+      },
+    },
+  },
+  render: () => (
+    <RadioGroup defaultValue="yes">
+      <div className="flex flex-col gap-gds-2">
+        <FieldItem>
+          <Radio id="yes" value="yes" />
+
+          <Label htmlFor="yes">Yes</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Radio id="no" value="no" />
+
+          <Label htmlFor="no">No</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Radio id="maybe" value="maybe" />
+
+          <Label htmlFor="maybe">Maybe</Label>
+        </FieldItem>
+      </div>
+    </RadioGroup>
+  ),
+};
+
+export const Horizontal: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass orientation="horizontal" for an inline row of options (GDS\'s "inline" radios), it wraps onto more than one line rather than overflowing if there isn\'t room for all of them.',
+      },
+    },
+  },
+  render: () => (
+    <RadioGroup defaultValue="yes" orientation="horizontal">
+      <FieldItem>
+        <Radio id="h-yes" value="yes" />
+
+        <Label htmlFor="h-yes">Yes</Label>
+      </FieldItem>
+
+      <FieldItem>
+        <Radio id="h-no" value="no" />
+
+        <Label htmlFor="h-no">No</Label>
+      </FieldItem>
+
+      <FieldItem>
+        <Radio id="h-maybe" value="maybe" />
+
+        <Label htmlFor="h-maybe">Maybe</Label>
+      </FieldItem>
+    </RadioGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <RadioGroup defaultValue="yes">
+      <div className="flex flex-col gap-gds-2">
+        <FieldItem>
+          <Radio id="d-yes" value="yes" disabled />
+
+          <Label htmlFor="d-yes">Yes (disabled, selected)</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Radio id="d-no" value="no" disabled />
+
+          <Label htmlFor="d-no">No (disabled)</Label>
+        </FieldItem>
+      </div>
+    </RadioGroup>
+  ),
+};
+
+export const Small: Story = {
+  render: () => (
+    <RadioGroup defaultValue="one">
+      <div className="flex flex-col gap-gds-1">
+        <FieldItem>
+          <Radio id="sm-one" value="one" size="sm" />
+
+          <Label htmlFor="sm-one">Option one</Label>
+        </FieldItem>
+
+        <FieldItem>
+          <Radio id="sm-two" value="two" size="sm" />
+
+          <Label htmlFor="sm-two">Option two</Label>
+        </FieldItem>
+      </div>
+    </RadioGroup>
+  ),
+};

package/src/components/Radio/Radio.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { RadioGroup as RadioGroupPrimitive } from 'radix-ui';
+
+import { cn } from '../../utils/components';
+
+const RADIO_SIZES = {
+  sm: 'cn-radio-size-sm',
+  base: 'cn-radio-size-base',
+} as const;
+
+export type RadioSize = keyof typeof RADIO_SIZES;
+
+export type RadioGroupProps<T extends string> = Omit<
+  ComponentProps<typeof RadioGroupPrimitive.Root>,
+  'defaultValue' | 'value' | 'onValueChange'
+> & {
+  defaultValue?: T;
+  value?: T;
+  onValueChange?: (value: T) => void;
+};
+
+export type RadioProps = ComponentProps<typeof RadioGroupPrimitive.Item> & {
+  size?: RadioSize;
+};
+
+export const RadioGroup = <T extends string = string>({
+  defaultValue,
+  value,
+  onValueChange,
+  className,
+  ...props
+}: RadioGroupProps<T>) => (
+  <RadioGroupPrimitive.Root
+    {...props}
+    data-slot="radio-group"
+    className={cn('cn-radio-group', className)}
+    defaultValue={defaultValue as string}
+    value={value as string}
+    onValueChange={(value) => onValueChange?.(value as T)}
+  />
+);
+
+export const Radio = ({ className, size = 'base', ...props }: RadioProps) => (
+  <RadioGroupPrimitive.Item
+    {...props}
+
+    data-slot="radio"
+    data-size={size}
+    className={cn('cn-radio', RADIO_SIZES[size], className)}
+  >
+    <RadioGroupPrimitive.Indicator data-slot="radio-indicator" className="cn-radio-indicator" />
+  </RadioGroupPrimitive.Item>
+);

package/src/components/Resizable/Resizable.css

@@ -0,0 +1,86 @@
+@layer components {
+  /* MARK: Resizing
+     Applied to <body> for the duration of a drag (see ResizableHandle), so
+     the pointer moving during the drag can't select surrounding page text. */
+  body.cn-resizing {
+    @apply select-none;
+  }
+
+  /* MARK: Panel group
+     Flex container, direction driven by the aria-orientation attribute set
+     by react-resizable-panels. */
+  .cn-resizable-panel-group {
+    @apply flex h-full w-full;
+
+    &[aria-orientation='vertical'] {
+      @apply flex-col;
+    }
+  }
+
+  /* MARK: Panel
+     react-resizable-panels hardcodes overflow: visible as an inline style
+     on every panel's own [data-panel] div (confirmed directly in its
+     source), regardless of props, so any content that visually extends
+     even slightly past a panel's own edge (a map control, a tooltip, a
+     canvas that doesn't perfectly match its container) isn't clipped
+     there, it keeps going and can inflate the whole page's scrollable
+     area instead of staying contained to the panel, even though every
+     statically-sized ancestor up to <html> still measures a perfectly
+     normal, viewport-matching size. !important is the only way to win
+     against an inline style. */
+  [data-panel] {
+    overflow: hidden !important;
+  }
+
+  /* MARK: Handle
+     The drag separator between panels. The ::after expands the hit area
+     without changing the visual size. Horizontal orientation flips the
+     layout so the line and hit target run across the full width. cn-z-top
+     keeps the handle reachable regardless of DOM order relative to whatever
+     else is rendered in the panels either side of it. */
+  .cn-resizable-handle {
+    @apply relative cn-z-top flex items-center justify-center bg-divider-input cursor-col-resize;
+    width: var(--border-width-form);
+
+    &::after {
+      @apply content-[''] absolute inset-y-0 left-1/2 w-gds-2 -translate-x-1/2;
+    }
+
+    &[aria-orientation='horizontal'] {
+      @apply w-full cursor-row-resize;
+      height: var(--border-width-form);
+
+      &::after {
+        /* translate-x-0 resets the base -translate-x-1/2 */
+        @apply inset-x-0 top-1/2 w-full h-gds-2 translate-x-0 -translate-y-1/2;
+      }
+
+      > .cn-resizable-handle-icon {
+        @apply rotate-90;
+      }
+    }
+
+    &:focus-visible {
+      @apply outline-none;
+
+      > .cn-resizable-handle-icon {
+        @apply bg-focus border-focus text-on-focus;
+      }
+    }
+
+    /* Hides a disabled handle entirely rather than showing a greyed-out,
+       non-functional line. visibility (not display: none) so it keeps
+       occupying its normal thin width, react-resizable-panels tracks its
+       Separators by React mount/unmount, not CSS, so this never touches
+       that, only how the already-mounted disabled Separator looks. */
+    &[data-separator='disabled'] {
+      @apply invisible pointer-events-none;
+    }
+  }
+
+  /* MARK: Grip icon
+     Optional visible drag affordance centred on the handle line. */
+  .cn-resizable-handle-icon {
+    @apply z-10 flex shrink-0 items-center justify-center panel text-body size-6;
+  }
+}

package/src/components/Resizable/Resizable.stories.tsx

@@ -0,0 +1,123 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from './Resizable';
+
+const meta: Meta<typeof ResizablePanelGroup> = {
+  title: 'Components/Resizable',
+  component: ResizablePanelGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Drag-to-resize panel layout powered by [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels).
+
+Install the peer dependency to use this component:
+
+\`\`\`bash
+npm install react-resizable-panels
+\`\`\`
+
+- **\`ResizablePanelGroup\`**: the flex container. Set \`direction="horizontal"\` (default) or \`direction="vertical"\`.
+- **\`ResizablePanel\`**: an individual panel. Accepts \`defaultSize\` (percentage), \`minSize\`, \`maxSize\`.
+- **\`ResizableHandle\`**: the drag separator. Disable \`withHandle\` to hide the visible grip icon.
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ResizablePanelGroup>;
+
+export const Horizontal: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Default horizontal layout. Drag the handle to resize.' },
+    },
+  },
+  render: () => (
+    <ResizablePanelGroup
+      orientation="horizontal"
+      className="min-h-48 border-form border-solid border-divider-input"
+    >
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Panel A
+        </div>
+      </ResizablePanel>
+
+      <ResizableHandle />
+
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Panel B
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};
+
+export const Vertical: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Vertical layout, panels stack top to bottom.' },
+    },
+  },
+  render: () => (
+    <ResizablePanelGroup
+      orientation="vertical"
+      className="min-h-64 border-form border-solid border-divider-input"
+    >
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Top
+        </div>
+      </ResizablePanel>
+
+      <ResizableHandle />
+
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Bottom
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};
+
+export const ThreePanels: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'Multiple panels with independent size constraints.' },
+    },
+  },
+  render: () => (
+    <ResizablePanelGroup
+      orientation="horizontal"
+      className="min-h-48 border-form border-solid border-divider-input"
+    >
+      <ResizablePanel defaultSize={20} minSize={10}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Sidebar
+        </div>
+      </ResizablePanel>
+
+      <ResizableHandle />
+
+      <ResizablePanel defaultSize={60}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Main
+        </div>
+      </ResizablePanel>
+
+      <ResizableHandle />
+
+      <ResizablePanel defaultSize={20} minSize={10}>
+        <div className="flex h-full items-center justify-center p-gds-4 text-body-secondary text-sm">
+          Detail
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};

package/src/components/Resizable/Resizable.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { type ComponentProps, type PointerEventHandler } from 'react';
+
+import { LuGripVertical } from 'react-icons/lu';
+import { Group, Panel, Separator } from 'react-resizable-panels';
+
+import { cn } from '../../utils/components';
+
+export type ResizablePanelGroupProps = ComponentProps<typeof Group>;
+
+// react-resizable-panels pads a separator's drag hit region up to this size
+// (centred on the actual gap between panels) if it's smaller, but defaults to
+// only 10px for a mouse/10px pointer and 20px for touch. Our handle's visible
+// grip icon (ResizableHandle, size-6 = 24px) is bigger than that default, so
+// clicking near its edges misses the real hit region even though it looks
+// like one big button. 24px also matches WCAG 2.5.5/2.5.8's minimum target
+// size guidance, so raise the default for every pointer type, not just to
+// match the icon.
+const RESIZE_TARGET_MINIMUM_SIZE = { coarse: 24, fine: 24 };
+
+export const ResizablePanelGroup = ({
+  className,
+  resizeTargetMinimumSize = RESIZE_TARGET_MINIMUM_SIZE,
+  ...props
+}: ResizablePanelGroupProps) => (
+  <Group
+    data-slot="resizable-panel-group"
+    className={cn('cn-resizable-panel-group', className)}
+    resizeTargetMinimumSize={resizeTargetMinimumSize}
+    {...props}
+  />
+);
+
+export type ResizablePanelProps = ComponentProps<typeof Panel>;
+
+export const ResizablePanel = (props: ResizablePanelProps) => (
+  <Panel data-slot="resizable-panel" {...props} />
+);
+
+export type ResizableHandleProps = ComponentProps<typeof Separator> & {
+  withHandle?: boolean;
+};
+
+export const ResizableHandle = ({
+  withHandle = true,
+  className,
+  onPointerDown,
+  ...props
+}: ResizableHandleProps) => {
+  // Dragging the handle can otherwise select surrounding page text, the
+  // pointer doesn't stay perfectly still while dragging, and text selection
+  // is a normal side effect of that movement. There's no public drag-state
+  // event from react-resizable-panels to hook into, so track it directly:
+  // add on pointerdown, remove on pointerup/pointercancel wherever the
+  // pointer ends up, dragging routinely moves it off the handle itself.
+  const handlePointerDown: PointerEventHandler<HTMLDivElement> = (event) => {
+    document.body.classList.add('cn-resizing');
+
+    const stopResizing = () => {
+      document.body.classList.remove('cn-resizing');
+      window.removeEventListener('pointerup', stopResizing);
+      window.removeEventListener('pointercancel', stopResizing);
+    };
+
+    window.addEventListener('pointerup', stopResizing);
+    window.addEventListener('pointercancel', stopResizing);
+
+    onPointerDown?.(event);
+  };
+
+  return (
+    <Separator
+      data-slot="resizable-handle"
+      className={cn('cn-resizable-handle', className)}
+      onPointerDown={handlePointerDown}
+      {...props}
+    >
+      {withHandle ? (
+        <div className="cn-resizable-handle-icon">
+          <LuGripVertical aria-hidden />
+        </div>
+      ) : null}
+    </Separator>
+  );
+};

package/src/components/ScrollArea/ScrollArea.css

@@ -0,0 +1,9 @@
+@layer components {
+  /* MARK: Scroll area
+     Native scrollbars in both directions. min-height: 0 prevents the default
+     flex min-height: auto from stopping the area from shrinking inside a flex
+     parent. Without it, the area grows to fit content instead of scrolling. */
+  .cn-scroll-area {
+    @apply overflow-scroll min-h-0;
+  }
+}

package/src/components/ScrollArea/ScrollArea.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ScrollArea } from './ScrollArea';
+import { Heading } from '../Heading/Heading';
+import { Separator } from '../Separator/Separator';
+
+const meta: Meta<typeof ScrollArea> = {
+  title: 'Components/ScrollArea',
+  component: ScrollArea,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A div wrapper that enables native scrollbars when content overflows. Set a constrained `height` or `max-height` via `className`, the area scrolls within those bounds using the browser's native scrollbar, consistent with the rest of the page.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ScrollArea>;
+
+const TAGS = Array.from({ length: 50 }, (_, i) => `v1.2.0-beta.${50 - i}`);
+
+export const Default: Story = {
+  render: () => (
+    <ScrollArea className="h-72 w-48 panel">
+      <div className="p-gds-2">
+        <Heading level="h4">Tags</Heading>
+        {TAGS.map((tag) => (
+          <div key={tag}>
+            <div>{tag}</div>
+
+            <Separator className="my-2" />
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};

package/src/components/ScrollArea/ScrollArea.tsx

@@ -0,0 +1,11 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '../../utils/components';
+
+export type ScrollAreaProps = ComponentProps<'div'>;
+
+export const ScrollArea = ({ className, children, ...props }: ScrollAreaProps) => (
+  <div data-slot="scroll-area" className={cn('cn-scroll-area', className)} {...props}>
+    {children}
+  </div>
+);

package/src/components/SearchBox/SearchBox.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SearchBox } from './SearchBox';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { HintText } from '../HintText/HintText';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof SearchBox> = {
+  title: 'Components/SearchBox',
+  component: SearchBox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A search input with a primary submit button. Wrap in a `<form role="search">` to wire up submission. The button is `type="submit"` so it works with standard form behaviour. Accepts all `Input` props except `type`.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SearchBox>;
+
+export const Default: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <SearchBox placeholder="Search" {...args} />
+    </form>
+  ),
+};
+
+export const WithLabel: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <div className="flex flex-col gap-gds-1">
+        <Label htmlFor="site-search">Search this site</Label>
+
+        <HintText id="site-search-hint">Enter a keyword or phrase.</HintText>
+
+        <SearchBox
+          id="site-search"
+          placeholder="Search"
+          aria-describedby="site-search-hint"
+          {...args}
+        />
+      </div>
+    </form>
+  ),
+};
+
+export const Invalid: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <FormGroup invalid>
+        <Label htmlFor="search-invalid">Search this site</Label>
+
+        <ErrorText id="search-invalid-error">Enter a search term</ErrorText>
+
+        <SearchBox
+          id="search-invalid"
+          placeholder="Search"
+          aria-invalid
+          aria-describedby="search-invalid-error"
+          {...args}
+        />
+      </FormGroup>
+    </form>
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <form role="search">
+      <SearchBox placeholder="Search" disabled {...args} />
+    </form>
+  ),
+};
+
+export const CustomLabel: Story = {
+  render: (args) => (
+    <form role="search" onSubmit={(event) => event.preventDefault()}>
+      <SearchBox placeholder="Enter location" buttonLabel="Find" {...args} />
+    </form>
+  ),
+};