@scottish-government/designsystem-react 0.10.2 → 0.12.0

package/src/components/Accordion/Accordion.Item.stories.tsx

@@ -6,9 +6,17 @@ import Accordion from './Accordion';
 const meta = {
     title: 'Components/Accordion/Accordion.Item',
     component: Accordion.Item,
+    decorators: [(Story) => <div className="ds_accordion"><Story /></div>],
     argTypes: {
+        heading: {
+            description: 'Heading of the accordion item',
+            type: {
+                name: 'string',
+                required: true
+            }
+        },
         headingLevel: argTypes.headingLevel({
-            description: 'Heading level for the component\'s title. It is best to set this on the parent Accordion.'
+            description: 'Heading level for the component\'s heading. It is best to set this on the parent Accordion.'
         }),
         id: {
             description: 'ID to use for the accordion item if you want to override the automatically generated default',
@@ -18,19 +26,12 @@ const meta = {
             description: 'Makes the accordion item display in an open state on page load',
             control: 'boolean',
         },
-        title: {
-            description: 'Title of the accordion item',
-            type: {
-                name: 'string',
-                required: true
-            }
-        },
         children: {
             control: false
         }
     },
     args: {
-        title: 'Healthcare for veterans',
+        heading: 'Healthcare for veterans',
         children: <>
             <p>
                 Veterans are entitled to the same healthcare as any citizen. And there are health care options and support available specifically for veterans.

package/src/components/Accordion/Accordion.stories.tsx

@@ -8,7 +8,7 @@ const meta = {
     component: Accordion,
     argTypes: {
         headingLevel: argTypes.headingLevel({
-            description: 'Heading level to use for the accordion items\' titles'
+            description: 'Heading level to use for the accordion items\' headings'
         }),
         hideOpenAll: {
             control: 'boolean',
@@ -21,7 +21,7 @@ const meta = {
     },
     args: {
         children: <>
-            <Accordion.Item id='accordion-1' title='Healthcare for veterans'>
+            <Accordion.Item id='accordion-1' heading='Healthcare for veterans'>
                 <p>
                     Veterans are entitled to the same healthcare as any citizen. And there are health care options and support available specifically for veterans.
                 </p>
@@ -29,12 +29,12 @@ const meta = {
                     If you have a health condition that's related to your service, you're entitled to priority treatment based on clinical need.
                 </p>
             </Accordion.Item>
-            <Accordion.Item id='accordion-2' title='Employability for veterans'>
+            <Accordion.Item id='accordion-2' heading='Employability for veterans'>
                 <p>
                     If you're looking for a job, there are several organisations that can help you <a href="#accordion-link">find a job or develop new skills</a>.
                 </p>
             </Accordion.Item>
-            <Accordion.Item id='accordion-3' title='Housing for veterans'>
+            <Accordion.Item id='accordion-3' heading='Housing for veterans'>
                 <p>
                     If you need <a href="#accordion-link"> help finding a place to live</a> there's support specifically for veterans.
                 </p>

package/src/components/Accordion/Accordion.test.tsx

@@ -1,4 +1,4 @@
-import { test, expect } from 'vitest';
+import { test, expect, vi } from 'vitest';
 import { render, screen, within } from '@testing-library/react';
 import Accordion from './Accordion';
 
@@ -13,17 +13,17 @@ test('accordion renders correctly', () => {
 
     render(
         <Accordion id={ACCORDION_ID} data-testid={ACCORDION_ID}>
-            <Accordion.Item id="accordion-1" title="Healthcare for veterans">
+            <Accordion.Item id="accordion-1" heading="Healthcare for veterans">
                 <p>Veterans are entitled to the same healthcare as any citizen. And there
                     are health care options and support available specifically for veterans.</p>
                 <p>If you have a health condition that’s related to your service, you’re
                     entitled to priority treatment based on clinical need.</p>
             </Accordion.Item>
-            <Accordion.Item isOpen id="accordion-2" title="Employability for veterans">
+            <Accordion.Item isOpen id="accordion-2" heading="Employability for veterans">
                 <p>If you&apos;re looking for a job, there are several organisations that can help
                     you <a href="#accordion-link">find a job or develop new skills</a>.</p>
             </Accordion.Item>
-            <Accordion.Item id="accordion-3" title="Housing for veterans">
+            <Accordion.Item id="accordion-3" heading="Housing for veterans">
                 <p>If you need <a href="#accordion-link">help finding a place to live</a>{' '}
                     there&apos;s support specifically for veterans.</p>
             </Accordion.Item>
@@ -48,17 +48,17 @@ test('accordion renders correctly', () => {
 test('accordion without open all', () => {
     render(
         <Accordion id={ACCORDION_ID} data-testid={ACCORDION_ID} hideOpenAll>
-            <Accordion.Item id="accordion-1" title="Healthcare for veterans">
+            <Accordion.Item id="accordion-1" heading="Healthcare for veterans">
                 <p>Veterans are entitled to the same healthcare as any citizen. And there
                     are health care options and support available specifically for veterans.</p>
                 <p>If you have a health condition that’s related to your service, you’re
                     entitled to priority treatment based on clinical need.</p>
             </Accordion.Item>
-            <Accordion.Item id="accordion-2" title="Employability for veterans">
+            <Accordion.Item id="accordion-2" heading="Employability for veterans">
                 <p>If you&apos;re looking for a job, there are several organisations that can help
                     you <a href="#accordion-link">find a job or develop new skills</a>.</p>
             </Accordion.Item>
-            <Accordion.Item id="accordion-3" title="Housing for veterans">
+            <Accordion.Item id="accordion-3" heading="Housing for veterans">
                 <p>If you need <a href="#accordion-link">help finding a place to live</a>{' '}
                     there&apos;s support specifically for veterans.</p>
             </Accordion.Item>
@@ -86,7 +86,7 @@ test('accordion with custom heading level', () => {
 
     render(
         <Accordion id={ACCORDION_ID} data-testid={ACCORDION_ID} headingLevel={HEADING_LEVEL}>
-            <Accordion.Item id="accordion-1" title="Healthcare for veterans">
+            <Accordion.Item id="accordion-1" heading="Healthcare for veterans">
                 <p>Veterans are entitled to the same healthcare as any citizen. And there
                     are health care options and support available specifically for veterans.</p>
                 <p>If you have a health condition that’s related to your service, you’re
@@ -121,7 +121,7 @@ test('passing additional CSS classes', () => {
 
 test('accordion item renders correctly', () => {
     render(
-        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} title={TITLE_TEXT}>
+        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} heading={TITLE_TEXT}>
             <p>{CONTENT_TEXT}</p>
         </Accordion.Item>
     );
@@ -159,13 +159,13 @@ test('accordion item renders correctly', () => {
 test('accordion items without ID are given unique IDs', () => {
     render(
         <Accordion id={ACCORDION_ID} data-testid={ACCORDION_ID} hideOpenAll>
-            <Accordion.Item data-testid="item1" title="Healthcare for veterans">
+            <Accordion.Item data-testid="item1" heading="Healthcare for veterans">
                 <p>Veterans are entitled to the same healthcare as any citizen. And there
                     are health care options and support available specifically for veterans.</p>
                 <p>If you have a health condition that’s related to your service, you’re
                     entitled to priority treatment based on clinical need.</p>
             </Accordion.Item>
-            <Accordion.Item data-testid="item2" title="Employability for veterans">
+            <Accordion.Item data-testid="item2" heading="Employability for veterans">
                 <p>If you&apos;re looking for a job, there are several organisations that can help
                     you <a href="#accordion-link">find a job or develop new skills</a>.</p>
             </Accordion.Item>
@@ -182,7 +182,7 @@ test('accordion items without ID are given unique IDs', () => {
 
 test('open accordion item', () => {
     render(
-        <Accordion.Item isOpen id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} title={TITLE_TEXT}>
+        <Accordion.Item isOpen id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} heading={TITLE_TEXT}>
             <p>{CONTENT_TEXT}</p>
         </Accordion.Item>
     );
@@ -193,9 +193,43 @@ test('open accordion item', () => {
     expect(input).toHaveAttribute('checked');
 });
 
+test('small accordion item', () => {
+    render(
+        <Accordion isSmall data-testid={ACCORDION_ID}>
+            <Accordion.Item id={ACCORDION_ITEM_ID} heading={TITLE_TEXT}>
+                <p>{CONTENT_TEXT}</p>
+            </Accordion.Item>
+        </Accordion>
+    );
+
+    const accordionItem = screen.getByTestId(ACCORDION_ID);
+
+    expect(accordionItem).toHaveClass('ds_accordion--small');
+});
+
+test('deprecated title prop still works with warning', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    render(
+        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} title={TITLE_TEXT}>
+            <p>{CONTENT_TEXT}</p>
+        </Accordion.Item>
+    );
+
+    const header = document.querySelector('.ds_accordion-item__header');
+    const title = header?.querySelector('.ds_accordion-item__title');
+
+    expect(title?.textContent).toEqual(TITLE_TEXT);
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Warning: Using the `title` prop for heading text on an Accordion.Item is deprecated and will be removed in a future release. Please use the `heading` prop instead.'
+    );
+
+    consoleWarnSpy.mockRestore();
+});
+
 test('passing additional props to accordion item', () => {
     render(
-        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} title="Healthcare for veterans" data-test="foo">
+        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} heading="Healthcare for veterans" data-test="foo">
             <p>Veterans are entitled to the same healthcare as any citizen. And there
                 are health care options and support available specifically for veterans.</p>
             <p>If you have a health condition that’s related to your service, you’re
@@ -209,7 +243,7 @@ test('passing additional props to accordion item', () => {
 
 test('passing additional CSS classes', () => {
     render(
-        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} title="Healthcare for veterans" className="foo">
+        <Accordion.Item id={ACCORDION_ITEM_ID} data-testid={ACCORDION_ITEM_ID} heading="Healthcare for veterans" className="foo">
             <p>Veterans are entitled to the same healthcare as any citizen. And there
                 are health care options and support available specifically for veterans.</p>
             <p>If you have a health condition that’s related to your service, you’re

package/src/components/Accordion/Accordion.tsx

@@ -11,6 +11,7 @@ const AccordionItem = ({
     className,
     id: rawId,
     isOpen = false,
+    heading,
     title,
     ...props
 }: SGDS.Component.Accordion.Item) => {
@@ -19,6 +20,14 @@ const AccordionItem = ({
 
     let headingLevel = useContext(AccordionHeadingLevelContext);
 
+    if (title) {
+        console.warn(
+            'Warning: Using the `title` prop for heading text on an Accordion.Item is deprecated and will be removed in a future release. Please use the `heading` prop instead.'
+        );
+
+        heading = heading || title;
+    }
+
     return (
         <div
             className={[
@@ -44,7 +53,7 @@ const AccordionItem = ({
                     className="ds_accordion-item__title"
                     tagName={headingLevel}
                 >
-                    {title}
+                    {heading}
                 </WrapperTag>
                 <span className="ds_accordion-item__indicator" />
                 <label
@@ -66,6 +75,7 @@ const Accordion = ({
     className,
     headingLevel = 'h3',
     hideOpenAll,
+    isSmall,
     ...props
 }: SGDS.Component.Accordion) => {
     const ref = useRef(null);
@@ -84,6 +94,7 @@ const Accordion = ({
         <div
             className={[
                 'ds_accordion',
+                isSmall ? 'ds_accordion--small' : '',
                 className
             ].join(' ')}
             ref={ref}

package/src/components/Breadcrumbs/Breadcrumbs.Item.stories.tsx

@@ -6,8 +6,15 @@ import Breadcrumbs from './Breadcrumbs';
 const meta = {
     title: 'Components/Breadcrumbs/Breadcrumb.Item',
     component: Breadcrumbs.Item,
+    decorators: [
+        Story => (
+            <Breadcrumbs>
+                <Story />
+            </Breadcrumbs>
+        )
+    ],
     argTypes: {
-        href: argTypes.href(),
+        href: argTypes.href({type: {name: 'string', required: true}}),
         isHidden: {
             description: 'Applies a visually-hidden CSS class',
             control: 'boolean'

package/src/components/Button/Button.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import Button from './Button';
 
 const meta = {
-    title: 'Components/Button',
+    title: 'Components/Buttons/Button',
     component: Button,
     parameters: {
         controls: { sort: 'alpha' }

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import ButtonGroup from './ButtonGroup';
+import Button from '../Button/Button';
+
+const meta = {
+    title: 'Components/Buttons/ButtonGroup',
+    component: ButtonGroup,
+    parameters: {
+        controls: { sort: 'alpha' }
+    },
+    argTypes: {
+        isInline: {
+            description: 'Force inline buttons on small screens',
+            control: 'boolean',
+            table: {
+                type: {
+                    summary: 'boolean'
+                }
+            }
+        }
+    },
+    args: {
+        children: <>
+            <Button buttonStyle="secondary">Button one</Button>
+            <Button buttonStyle="secondary">Button two</Button>
+            <Button buttonStyle="secondary">Button three</Button>
+        </>
+    }
+} satisfies Meta<typeof ButtonGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+};
+
+export const Inline: Story = {
+    args: {
+        isInline: true
+    }
+};

package/src/components/ButtonGroup/ButtonGroup.test.tsx

@@ -0,0 +1,45 @@
+import { test, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import ButtonGroup from './ButtonGroup';
+
+test('renders correctly', () => {
+    render(
+        <ButtonGroup data-testid="button-group">
+        </ButtonGroup>
+    );
+
+    const buttonGroup = screen.getByTestId('button-group');
+    expect(buttonGroup).toBeInTheDocument();
+    expect(buttonGroup).toHaveClass('ds_button-group');
+    expect(buttonGroup.tagName).toEqual('DIV');
+});
+
+test('inline button group', () => {
+    render(
+        <ButtonGroup isInline data-testid="button-group">
+
+        </ButtonGroup>
+    );
+    const buttonGroup = screen.getByTestId('button-group');
+    expect(buttonGroup).toHaveClass('ds_button-group--inline');
+});
+
+test('passing additional props', () => {
+    render(
+        <ButtonGroup data-test="foo" data-testid="button-group">
+        </ButtonGroup>
+    );
+
+    const buttonGroup = screen.getByTestId('button-group');
+    expect(buttonGroup.dataset.test).toEqual('foo');
+});
+
+test('passing additional CSS classes', () => {
+    render(
+        <ButtonGroup className="foo" data-testid="button-group">
+        </ButtonGroup>
+    );
+
+    const buttonGroup = screen.getByTestId('button-group');
+    expect(buttonGroup).toHaveClass('foo', 'ds_button-group');
+});

package/src/components/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,20 @@
+const ButtonGroup = ({
+    children,
+    className,
+    isInline,
+    ...props
+}: SGDS.Component.ButtonGroup) => {
+    return (
+        <div className={[
+            "ds_button-group",
+            isInline ? "ds_button-group--inline" : undefined,
+            className
+        ].join(' ')} { ...props } >
+            {children}
+        </div>
+    );
+};
+
+ButtonGroup.displayName = 'ButtonGroup';
+
+export default ButtonGroup;

package/src/components/ContentsNav/ContentsNav.Item.stories.tsx

@@ -6,7 +6,15 @@ import ContentsNav from './ContentsNav';
 const meta = {
     title: 'Components/ContentsNav/ContentsNav.Item',
     component: ContentsNav.Item,
+    decorators: [
+        Story => (
+            <ul className="ds_contents-nav__list">
+                <Story />
+            </ul>
+        )
+    ],
     argTypes: {
+        href: argTypes.href({type: {name: 'string', required: true}}),
         isCurrent: argTypes.isCurrent(),
         linkComponent: argTypes.linkComponent(),
         children: argTypes.children()

package/src/components/ErrorSummary/ErrorSummary.Item.stories.tsx

@@ -6,6 +6,13 @@ import ErrorSummary from './ErrorSummary';
 const meta = {
     title: 'Components/ErrorSummary/ErrorSummary.Item',
     component: ErrorSummary.Item,
+    decorators: [
+        Story => (
+            <ul className="ds_error-summary__list">
+                <Story />
+            </ul>
+        )
+    ],
     argTypes: {
         fragmentId: {
             description: 'ID of the question or field to link to',

package/src/components/PageHeader/PageHeader.tsx

@@ -3,6 +3,7 @@ const PageHeader = ({
     className,
     label,
     title,
+    titleId,
     ...props
 }: SGDS.Component.PageHeader) => {
     return (
@@ -14,7 +15,7 @@ const PageHeader = ({
             {...props}
         >
             {label && <span className="ds_page-header__label  ds_content-label">{label}</span>}
-            <h1 className="ds_page-header__title">{title}</h1>
+            <h1 id={titleId} className="ds_page-header__title">{title}</h1>
 
             {children}
         </header>

package/src/components/PageMetadata/PageMetadata.Item.stories.tsx

@@ -6,6 +6,15 @@ import Metadata from './PageMetadata';
 const meta = {
     title: 'Components/PageMetadata/PageMetadata.Item',
     component: Metadata.Item,
+    decorators: [
+        Story => (
+            <Metadata>
+                <dl className="ds_page-metadata__list">
+                    <Story />
+                </dl>
+            </Metadata>
+        )
+    ],
     argTypes: {
         children: argTypes.children(),
         name: {

package/src/components/RadioButton/RadioGroup.tsx

@@ -6,7 +6,7 @@ const RadioGroup = ({
     className,
     isInline,
     isSmall,
-    name,
+    name = '',
     ...props
 }: SGDS.Component.RadioButton.Group) => {
     return (
@@ -19,7 +19,7 @@ const RadioGroup = ({
             ].join(' ')}
             {...props}
         >
-            <CheckboxRadioContext value={{ isSmall: !!isSmall, name }}>
+            <CheckboxRadioContext value={{ isSmall: !!isSmall, name}}>
                 {children}
             </CheckboxRadioContext>
         </div>

package/src/components/SearchFacets/SearchFacets.Group.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import argTypes from '../../../.storybook/sgdsArgTypes';
+
+import Facets from './SearchFacets';
+import { join } from 'path';
+
+const meta = {
+    title: 'Components/Search results/Facets/Group',
+    component: Facets.Group,
+    decorators: [
+        (Story) => (
+            <div className="ds_facets">
+                <Story />
+            </div>
+        )
+    ],
+    argTypes: {
+        children: argTypes.children(),
+        joinContent: {
+            description: 'Content to display between the facet items when there are multiple items in the group',
+            type: 'string'
+        },
+        title: {
+            description: 'Title of the facet group',
+            type: {
+                name: 'string',
+                required: true
+            }
+        }
+    },
+    args: {
+        title: 'Content type'
+    }
+} satisfies Meta<typeof Facets.Group>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    render: (args: any) => (
+        <Facets.Group {...args}>
+            <Facets.Item title="Advice and guidance" />
+            <Facets.Item title="Factsheet"/>
+            <Facets.Item title="Statistics" />
+        </Facets.Group>
+    )
+};
+
+export const CustomJoinContent: Story = {
+    render: (args: any) => (
+        <Facets.Group joinContent="and" title="Updated between">
+            <Facets.Item accessibleName="Updated after 01/10/2025" title="01/10/2025" />
+            <Facets.Item accessibleName="Updated before 31/10/2025" title="31/10/2025"/>
+        </Facets.Group>
+    )
+};

package/src/components/SearchFacets/SearchFacets.Item.stories.tsx

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import Facets from './SearchFacets';
+
+const meta = {
+    title: 'Components/Search results/Facets/Item',
+    component: Facets.Item,
+    decorators: [
+        (Story) => (
+            <div className="ds_facets">
+                <Story />
+            </div>
+        )
+    ],
+    argTypes: {
+        accessibleName: {
+            description: 'Accessible name for the facet button. If not provided, the title will be used. This content becomes part of the facet button\'s aria-label attribute.',
+            type: 'string'
+        },
+        joinContent: {
+            description: 'Content to display before the facet button when there are multiple facets in a group. This should be provided to the parent Group instead.',
+            type: 'string'
+        },
+        onClick: {
+            description: 'Callback for when the facet button is clicked',
+            control: false
+        },
+        title: {
+            description: 'Text content of the facet button.',
+            type: {
+                name: 'string',
+                required: true
+            }
+        },
+    },
+    args: {
+        title: 'Advice and guidance'
+    }
+} satisfies Meta<typeof Facets.Item>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+
+};
+
+export const CustomAccessibleText: Story = {
+    args: {
+        accessibleName: 'Updated before 31st October 2025',
+        title: '31/10/2025'
+    }
+}

package/src/components/SearchFacets/SearchFacets.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import argTypes from '../../../.storybook/sgdsArgTypes';
+
+import Facets from './SearchFacets';
+
+const meta = {
+    title: 'Components/Search results/Facets',
+    component: Facets,
+    argTypes: {
+        children: argTypes.children()
+    },
+    args: {
+        title: 'Application incomplete'
+    }
+} satisfies Meta<typeof Facets>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    render: (args: any) => (
+        <Facets {...args}>
+            <Facets.Group title="Content type">
+                <Facets.Item title="Advice and guidance" />
+                <Facets.Item title="Factsheet"/>
+                <Facets.Item title="Statistics" />
+            </Facets.Group>
+            <Facets.Group title="Topic">
+                <Facets.Item title="Children and families"/>
+                <Facets.Item title="Education"/>
+            </Facets.Group>
+            <Facets.Group title="Updated between" joinContent="and">
+                <Facets.Item accessibleName="Updated after 20/11/2023" title="20/11/2023"/>
+                <Facets.Item accessibleName="Updated before 02/04/2024" title="02/04/2024"/>
+            </Facets.Group>
+        </Facets>
+    )
+};