@tpzdsp/next-toolkit 2.5.1 → 3.1.0

package/src/components/Legend/LegendDot.tsx

@@ -0,0 +1,15 @@
+import { cn } from '../../utils/components';
+
+export type LegendDotProps = {
+  color: string;
+  className?: string;
+};
+
+export const LegendDot = ({ color, className }: LegendDotProps) => (
+  <span
+    data-slot="legend-dot"
+    className={cn('cn-legend-dot', className)}
+    style={{ backgroundColor: color }}
+    aria-hidden
+  />
+);

package/src/components/Legend/LegendPanel.stories.tsx

@@ -0,0 +1,101 @@
+import { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LegendPanel } from './LegendPanel';
+import type { LegendOption } from './LegendPanel';
+
+const HABITAT_ITEMS: LegendOption[] = [
+  { value: 'bogs', label: 'Bogs', color: '#3b82f6' },
+  { value: 'dwarf-shrub', label: 'Dwarf shrub heath', color: '#14b8a6' },
+  { value: 'fens', label: 'Fens, marsh & swamp', color: '#ec4899' },
+  { value: 'littoral', label: 'Littoral sediments', color: '#f97316' },
+  { value: 'neutral', label: 'Neutral grassland', color: '#a855f7' },
+];
+
+const meta: Meta<typeof LegendPanel> = {
+  title: 'Components/LegendPanel',
+  component: LegendPanel,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Renders a list of \`LegendOption\` items (colour dot + label). This is the shared list rendering used inside \`Legend\`'s popover, and can also be used standalone.
+
+Pass \`value\` and \`onSelectItem\` together to switch into single-select interactive mode (radio-group behaviour, one item selected at a time). Omit both for a static, display-only list.
+
+\`LegendPanel\` itself has no border or background, that comes from whatever it's nested in (\`Legend\`'s \`PopoverContent\` already supplies it). For standalone use outside a popover, wrap it in a panel-styled container (the \`panel\` utility class, or your own bordered wrapper). \`Card\` is a different pattern now (a top-divider content tile), not a general-purpose bordered box.
+
+**Props:**
+- \`items\`: array of \`LegendOption\` objects (\`value\`, \`label\`, \`color\`)
+- \`title\`: optional heading shown above the list
+- \`value\` / \`onSelectItem\`: provide both to make the list selectable
+        `.trim(),
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof LegendPanel>;
+
+const InteractiveStory = () => {
+  const [active, setActive] = useState<string | null>('bogs');
+
+  return (
+    <div className="panel p-gds-3 w-52">
+      <LegendPanel
+        items={HABITAT_ITEMS}
+        title="Habitat types"
+        value={active}
+        onSelectItem={setActive}
+      />
+    </div>
+  );
+};
+
+const NoSelectionStory = () => {
+  const [active, setActive] = useState<string | null>(null);
+
+  return (
+    <div className="panel p-gds-3 w-52">
+      <LegendPanel
+        items={HABITAT_ITEMS}
+        title="Habitat types"
+        value={active}
+        onSelectItem={setActive}
+      />
+    </div>
+  );
+};
+
+export const Default: Story = {
+  render: () => (
+    <div className="panel p-gds-3 w-52">
+      <LegendPanel items={HABITAT_ITEMS} title="Habitat types" />
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass `value` and `onSelectItem` to make the list selectable, one item at a time. The same pattern as `LayerSwitcher`, without a popover.',
+      },
+    },
+  },
+  render: () => <InteractiveStory />,
+};
+
+export const NoSelection: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'When `value` is `null` no option is shown as selected.' },
+    },
+  },
+  render: () => <NoSelectionStory />,
+};

package/src/components/Legend/LegendPanel.tsx

@@ -0,0 +1,68 @@
+import type { ComponentProps } from 'react';
+
+import { LegendDot } from './LegendDot';
+import { cn } from '../../utils/components';
+
+export type LegendOption = {
+  value: string;
+  label: string;
+  color: string;
+};
+
+export type LegendPanelProps = ComponentProps<'div'> & {
+  items: LegendOption[];
+  title?: string;
+} & (
+    | { value?: never; onSelectItem?: never }
+    | { value: string | null; onSelectItem: (value: string) => void }
+  );
+
+export const LegendPanel = ({
+  items,
+  title,
+  value,
+  onSelectItem,
+  className,
+  ...props
+}: LegendPanelProps) => (
+  <div data-slot="legend-panel" className={cn('cn-legend-panel', className)} {...props}>
+    {title !== undefined ? (
+      <p data-slot="legend-title" className="cn-legend-title">
+        {title}
+      </p>
+    ) : null}
+
+    {onSelectItem !== undefined ? (
+      <div
+        data-slot="legend-items"
+        role="radiogroup"
+        aria-label={title ?? 'Legend'}
+        className="cn-legend-items"
+      >
+        {items.map((item) => (
+          <button
+            key={item.value}
+            type="button"
+            role="radio"
+            aria-checked={item.value === value}
+            onClick={() => onSelectItem(item.value)}
+            data-slot="legend-option"
+            className="cn-legend-option"
+          >
+            <LegendDot color={item.color} />
+            {item.label}
+          </button>
+        ))}
+      </div>
+    ) : (
+      <ul data-slot="legend-items" className="cn-legend-items">
+        {items.map((item) => (
+          <li key={item.value} data-slot="legend-item" className="cn-legend-item">
+            <LegendDot color={item.color} />
+            {item.label}
+          </li>
+        ))}
+      </ul>
+    )}
+  </div>
+);

package/src/components/Legend/LegendSkeleton.stories.tsx

@@ -0,0 +1,87 @@
+import { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LegendPanel } from './LegendPanel';
+import type { LegendOption } from './LegendPanel';
+import { LegendSkeleton } from './LegendSkeleton';
+
+const HABITAT_ITEMS: LegendOption[] = [
+  { value: 'bogs', label: 'Bogs', color: '#3b82f6' },
+  { value: 'dwarf-shrub', label: 'Dwarf shrub heath', color: '#14b8a6' },
+  { value: 'fens', label: 'Fens, marsh & swamp', color: '#ec4899' },
+  { value: 'littoral', label: 'Littoral sediments', color: '#f97316' },
+];
+
+const meta: Meta<typeof LegendSkeleton> = {
+  title: 'Components/Legend/Skeleton',
+  component: LegendSkeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Placeholder for a LegendPanel while its items are loading (e.g. fetched from a WMS GetLegendGraphic call). Reuses cn-legend-panel/title/items/item directly, so it lines up exactly with the real panel once data arrives.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof LegendSkeleton>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="w-52">
+      <LegendSkeleton />
+    </div>
+  ),
+};
+
+export const SideBySide: Story = {
+  parameters: {
+    docs: {
+      description: { story: 'The skeleton and the real panel line up exactly once loaded.' },
+    },
+  },
+  render: () => (
+    <div className="flex gap-gds-4">
+      <div className="w-52">
+        <LegendSkeleton items={HABITAT_ITEMS.length} />
+      </div>
+
+      <div className="w-52">
+        <LegendPanel items={HABITAT_ITEMS} title="Legend" />
+      </div>
+    </div>
+  ),
+};
+
+const InteractiveSideBySideExample = () => {
+  const [active, setActive] = useState<string | null>(HABITAT_ITEMS[0]?.value ?? null);
+
+  return (
+    <div className="flex gap-gds-4">
+      <div className="w-52">
+        <LegendSkeleton items={HABITAT_ITEMS.length} interactive />
+      </div>
+
+      <div className="w-52">
+        <LegendPanel items={HABITAT_ITEMS} title="Legend" value={active} onSelectItem={setActive} />
+      </div>
+    </div>
+  );
+};
+
+export const InteractiveSideBySide: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Interactive LegendPanel rows (a radiogroup of padded, full-width buttons) are noticeably taller/wider than the plain display rows above, set interactive on the skeleton to match.',
+      },
+    },
+  },
+  render: () => <InteractiveSideBySideExample />,
+};

package/src/components/Legend/LegendSkeleton.tsx

@@ -0,0 +1,73 @@
+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 an item's identity is never tied to
+// its position at render time.
+const ITEM_KEYS = [
+  'item-1',
+  'item-2',
+  'item-3',
+  'item-4',
+  'item-5',
+  'item-6',
+  'item-7',
+  'item-8',
+] as const;
+
+export type LegendSkeletonProps = ComponentProps<'div'> & {
+  /** Explicitly disallow children, a skeleton is a placeholder shape, not a content wrapper. */
+  children?: never;
+  /** Number of item rows to show. Defaults to 4. */
+  items?: number;
+  /** Shows a title bar, matching LegendPanel's own optional title. Defaults to true. */
+  showTitle?: boolean;
+  /** Matches LegendPanel's interactive (radiogroup) mode: rows are padded, full-width
+   *  cn-legend-option buttons rather than plain cn-legend-item rows, which is
+   *  noticeably taller/wider, so the skeleton needs to reserve that same space. */
+  interactive?: boolean;
+};
+
+export const LegendSkeleton = ({
+  className,
+  items = 4,
+  showTitle = true,
+  interactive = false,
+  ...props
+}: LegendSkeletonProps) => {
+  const itemKeys = ITEM_KEYS.slice(0, items);
+
+  return (
+    <div aria-hidden className={cn('cn-legend-panel', className)} {...props}>
+      {showTitle ? (
+        <div className="cn-legend-title">
+          <Skeleton className="cn-legend-skeleton-title" />
+        </div>
+      ) : null}
+
+      {interactive ? (
+        <div className="cn-legend-items">
+          {itemKeys.map((key) => (
+            <div key={key} className="cn-legend-option">
+              <Skeleton className="cn-legend-skeleton-dot" />
+
+              <Skeleton className="cn-legend-skeleton-label" />
+            </div>
+          ))}
+        </div>
+      ) : (
+        <ul className="cn-legend-items">
+          {itemKeys.map((key) => (
+            <li key={key} className="cn-legend-item">
+              <Skeleton className="cn-legend-skeleton-dot" />
+
+              <Skeleton className="cn-legend-skeleton-label" />
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};

package/src/components/LegendSelect/LegendSelect.css

@@ -0,0 +1,8 @@
+@layer components {
+  /* MARK: Legend dot
+     White ring separates the dot from the accent-coloured selected-option
+     background, ensuring visibility regardless of the dot colour. */
+  .cn-select-option-selected .cn-legend-dot {
+    outline: var(--focus-ring-width) solid var(--color-panel);
+  }
+}

package/src/components/LegendSelect/LegendSelect.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { LegendSelect, type LegendOption } from './LegendSelect';
+import { ErrorText } from '../ErrorText/ErrorText';
+import { FormGroup } from '../Form/FormGroup';
+import { Label } from '../Label/Label';
+
+const meta: Meta<typeof LegendSelect> = {
+  title: 'Components/LegendSelect',
+  component: LegendSelect,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A Select variant where each option carries a `color` field rendered as a filled circle before the label. Useful for map legend filters, status indicators, and any dataset where colour encodes meaning. Extends `Select` directly, so all Select props (clearable, disabled, invalid, async, etc.) work without extra wiring. Pass `formatOptionLabel` if you need to override the rendering.',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof LegendSelect>;
+
+const LAND_COVER_OPTIONS: LegendOption[] = [
+  { value: 'woodland', label: 'Woodland', color: '#2d6a4f' },
+  { value: 'grassland', label: 'Grassland', color: '#95d5b2' },
+  { value: 'arable', label: 'Arable land', color: '#e9c46a' },
+  { value: 'wetland', label: 'Wetland', color: '#4895ef' },
+  { value: 'urban', label: 'Urban / developed', color: '#adb5bd' },
+];
+
+export const Default: Story = {
+  args: {
+    options: LAND_COVER_OPTIONS,
+    placeholder: 'Select land cover type...',
+  },
+};
+
+export const WithDefault: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The colour dot appears in both the dropdown and the selected-value slot in the control.',
+      },
+    },
+  },
+  args: {
+    options: LAND_COVER_OPTIONS,
+    defaultValue: LAND_COVER_OPTIONS[0],
+  },
+};
+
+export const Clearable: Story = {
+  args: {
+    options: LAND_COVER_OPTIONS,
+    defaultValue: LAND_COVER_OPTIONS[2],
+    isClearable: true,
+  },
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <FormGroup invalid>
+      <Label htmlFor="legend-invalid">Land cover type</Label>
+
+      <ErrorText id="legend-invalid-error">Select a land cover type</ErrorText>
+
+      <LegendSelect
+        inputId="legend-invalid"
+        aria-describedby="legend-invalid-error"
+        options={LAND_COVER_OPTIONS}
+        placeholder="Select land cover type…"
+        invalid
+      />
+    </FormGroup>
+  ),
+};

package/src/components/LegendSelect/LegendSelect.tsx

@@ -0,0 +1,26 @@
+import type { GroupBase } from 'react-select';
+
+import { LegendDot } from '../Legend/LegendDot';
+import type { LegendOption } from '../Legend/LegendPanel';
+import { Select, type SelectProps } from '../Select/Select';
+
+export type { LegendOption };
+
+export type LegendSelectProps<IsMulti extends boolean = false> = Omit<
+  SelectProps<LegendOption, IsMulti, GroupBase<LegendOption>>,
+  'formatOptionLabel'
+>;
+
+export const LegendSelect = <IsMulti extends boolean = false>(
+  props: LegendSelectProps<IsMulti>,
+) => (
+  <Select<LegendOption, IsMulti>
+    {...props}
+    formatOptionLabel={(option) => (
+      <span className="flex items-center gap-gds-1">
+        <LegendDot color={option.color} />
+        {option.label}
+      </span>
+    )}
+  />
+);

package/src/components/Link/Link.css

@@ -0,0 +1,98 @@
+/* MARK: Appearances
+   Defined as utilities so ButtonLink can @apply them without duplication. */
+
+@utility cn-link-appearance-primary {
+  @apply text-link;
+
+  &:visited {
+    @apply text-link-visited;
+  }
+  &:hover:not(:disabled) {
+    @apply text-link-hover;
+  }
+  &:active:not(:disabled) {
+    @apply text-link-active;
+  }
+  &:focus:not(:disabled) {
+    @apply text-on-focus;
+  }
+}
+
+@utility cn-link-appearance-error {
+  color: var(--color-error);
+
+  &:visited {
+    color: var(--color-error);
+  }
+  &:hover:not(:disabled) {
+    color: color-mix(in srgb, var(--color-error) 80%, black);
+  }
+  &:active:not(:disabled) {
+    color: color-mix(in srgb, var(--color-error) 80%, black);
+  }
+  &:focus:not(:disabled) {
+    @apply text-on-focus;
+  }
+}
+
+@utility cn-link-appearance-inverse {
+  @apply text-white;
+
+  &:visited {
+    @apply text-white;
+  }
+  &:hover:not(:disabled) {
+    @apply text-white;
+  }
+  &:focus:not(:disabled) {
+    @apply text-on-focus;
+  }
+}
+
+@utility cn-link-appearance-contrast {
+  @apply text-body;
+
+  &:visited {
+    @apply text-body;
+  }
+  &:hover:not(:disabled),
+  &:active:not(:disabled) {
+    @apply text-body;
+  }
+  &:focus:not(:disabled) {
+    @apply text-on-focus;
+  }
+}
+
+@layer components {
+  /*
+    MARK: Link
+    GDS link pattern. Underline always visible, thicker on hover,
+    yellow highlight box on focus. Box shadow creates lines above
+    and below text (not a ring). Visited uses distinct purple.
+  */
+  .cn-link {
+    @apply w-fit cn-link-decoration;
+
+    &:hover {
+      @apply cn-link-hover-decoration;
+    }
+
+    /* GDS focus: yellow box with black underline shadow */
+    &:focus {
+      @apply text-on-focus bg-focus no-underline outline-focus outline-transparent;
+      /* Top shadow extends focus box above text. Bottom shadow replaces underline */
+      box-shadow:
+        0 -2px var(--color-focus),
+        0 4px var(--color-on-focus);
+    }
+  }
+
+  /* MARK: Expand variant
+     Overrides the base w-fit: content (e.g. a title and a trailing chevron)
+     spreads across the full width of whatever the link sits in, rather than
+     the icon sitting flush against the text. */
+  .cn-link-variant-expand {
+    @apply flex w-full items-center justify-between gap-gds-2;
+  }
+}

package/src/components/Link/Link.stories.tsx

@@ -0,0 +1,70 @@
+import { LuChevronRight } from 'react-icons/lu';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Link } from './Link';
+
+const meta: Meta<typeof Link> = {
+  title: 'Components/Link',
+  component: Link,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Use Link for accessible anchor navigation with multiple visual variants.',
+      },
+    },
+  },
+  argTypes: {
+    appearance: {
+      control: { type: 'radio' },
+      options: ['primary', 'inverse', 'contrast'],
+    },
+    variant: {
+      control: { type: 'radio' },
+      options: ['default', 'icon', 'expand'],
+    },
+    href: { control: 'text' },
+    children: { control: 'text' },
+  },
+  args: {
+    appearance: 'primary',
+    variant: 'default',
+    href: '#',
+    children: 'Story link',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Link>;
+
+export const Primary: Story = {
+  args: {
+    appearance: 'primary',
+  },
+};
+
+export const Inverse: Story = {
+  args: {
+    appearance: 'inverse',
+  },
+};
+
+export const Contrast: Story = {
+  args: {
+    appearance: 'contrast',
+  },
+};
+
+export const Expanded: Story = {
+  args: {
+    variant: 'expand',
+  },
+  render: (args) => (
+    <Link {...args}>
+      Explore
+      <LuChevronRight aria-hidden className="size-4" strokeWidth={2.5} />
+    </Link>
+  ),
+};

package/src/components/Link/Link.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+
+import { Slot } from 'radix-ui';
+
+import { cn } from '../../utils/components';
+
+const LINK_APPEARANCES = {
+  primary: 'cn-link-appearance-primary',
+  /**
+   * Typically reserved for use within an `Alert` component with the error appearance.
+   */
+  error: 'cn-link-appearance-error',
+  inverse: 'cn-link-appearance-inverse',
+  contrast: 'cn-link-appearance-contrast',
+} as const;
+
+export const LINK_VARIANTS = {
+  default: 'cn-link-variant-default',
+  icon: 'cn-link-variant-icon',
+  /** Full width, content spread apart, e.g. a title with a trailing chevron pushed to the end. */
+  expand: 'cn-link-variant-expand',
+};
+
+export type LinkAppearance = keyof typeof LINK_APPEARANCES;
+export type LinkVariant = keyof typeof LINK_VARIANTS;
+
+export type LinkProps = ComponentProps<'a'> & {
+  asChild?: boolean;
+  appearance?: LinkAppearance;
+  variant?: LinkVariant;
+};
+
+export const Link = ({
+  className,
+  asChild = false,
+  appearance = 'primary',
+  variant = 'default',
+  ...props
+}: LinkProps) => {
+  const Comp = asChild ? Slot.Root : 'a';
+
+  return (
+    <Comp
+      {...props}
+      data-slot="link"
+      data-variant={variant}
+      className={cn('cn-link', LINK_APPEARANCES[appearance], LINK_VARIANTS[variant], className)}
+    />
+  );
+};