@scottish-government/designsystem-react 0.12.1 → 1.0.0

package/src/components/SearchResult/SearchResult.stories.tsx

@@ -1,9 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import argTypes from '../../../.storybook/sgdsArgTypes';
-
 import SearchResult from './SearchResult';
-
-//@ts-ignore
+import Metadata from '../PageMetadata';
+// @ts-expect-error no types
 import coo from '../../../static/images/highland-cow.jpg';
 
 const meta = {
@@ -13,7 +12,8 @@ const meta = {
         children: argTypes.children()
     },
     args: {
-        title: 'Application incomplete'
+        title: 'Greenhouse gas statistics 1990-2022',
+        href: '#foo'
     }
 } satisfies Meta<typeof SearchResult>;
 
@@ -22,7 +22,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
     render: (args) => (
-        <SearchResult href="#foo" title="Greenhouse gas statistics 1990-2022" {...args}>
+        <SearchResult {...args}>
             <SearchResult.Content>
                 Official statistics showing emissions of greenhouse gases in Scotland over the period 1990 to 2022.
             </SearchResult.Content>
@@ -30,27 +30,27 @@ export const Default: Story = {
     )
 };
 
-export const Metadata: Story = {
+export const WithMetadata: Story = {
     render: (args) => (
-        <SearchResult href="#foo" title="Greenhouse gas statistics 1990-2022" {...args}>
+        <SearchResult {...args}>
             <SearchResult.Content>
                 Official statistics showing emissions of greenhouse gases in Scotland over the period 1990 to 2022.
             </SearchResult.Content>
-            <SearchResult.Meta>
-                <SearchResult.MetaItem name="Publication type">
+            <SearchResult.Metadata>
+                <Metadata.Item name="Publication type">
                     Statistics
-                </SearchResult.MetaItem>
-                <SearchResult.MetaItem name="Date">
+                </Metadata.Item>
+                <Metadata.Item name="Date">
                     18 June 2024
-                </SearchResult.MetaItem>
-            </SearchResult.Meta>
+                </Metadata.Item>
+            </SearchResult.Metadata>
         </SearchResult>
     )
 };
 
 export const Context: Story = {
     render: (args) => (
-        <SearchResult href="#foo" title="Greenhouse gas statistics 1990-2022" {...args}>
+        <SearchResult {...args}>
             <SearchResult.Content>
                 Official statistics showing emissions of greenhouse gases in Scotland over the period 1990 to 2022.
             </SearchResult.Content>
@@ -64,7 +64,7 @@ export const Context: Story = {
 
 export const Media: Story = {
     render: (args) => (
-        <SearchResult href="#foo" title="Application incomplete" {...args}>
+        <SearchResult {...args}>
             <SearchResult.Content>
                 <SearchResult.Media>
                     <img src={coo} alt="" />
@@ -77,7 +77,7 @@ export const Media: Story = {
 
 export const Promoted: Story = {
     render: (args) => (
-        <SearchResult isPromoted href="#foo" title="Greenhouse gas statistics 1990-2022" {...args}>
+        <SearchResult isPromoted {...args}>
             <SearchResult.Content>
                 Official statistics showing emissions of greenhouse gases in Scotland over the period 1990 to 2022.
             </SearchResult.Content>
@@ -87,21 +87,21 @@ export const Promoted: Story = {
 
 export const KitchenSink: Story = {
     render: (args) => (
-        <SearchResult isPromoted href="#foo" title="Application incomplete" {...args}>
+        <SearchResult isPromoted {...args}>
             <SearchResult.Content>
                 <SearchResult.Media>
                     <img src={coo} alt="" />
                 </SearchResult.Media>
                 Official statistics showing emissions of greenhouse gases in Scotland over the period 1990 to 2022.
             </SearchResult.Content>
-            <SearchResult.Meta>
-                <SearchResult.MetaItem name="Publication type">
+            <SearchResult.Metadata>
+                <Metadata.Item name="Publication type">
                     Statistics
-                </SearchResult.MetaItem>
-                <SearchResult.MetaItem name="Date">
+                </Metadata.Item>
+                <Metadata.Item name="Date">
                     18 June 2024
-                </SearchResult.MetaItem>
-            </SearchResult.Meta>
+                </Metadata.Item>
+            </SearchResult.Metadata>
             <SearchResult.Context title="Part of">
                 <SearchResult.ContextItem><a href="#">Environment statistics</a></SearchResult.ContextItem>
                 <SearchResult.ContextItem><a href="#">Energy statistics</a></SearchResult.ContextItem>

package/src/components/SearchResult/SearchResult.test.tsx

@@ -1,6 +1,7 @@
 import { test, expect } from 'vitest';
 import { render, screen, within } from '@testing-library/react';
 import SearchResult from './SearchResult';
+import Metadata from '../PageMetadata';
 
 const RESULT_TITLE = 'My title';
 const RESULT_HREF = '#foo';
@@ -15,11 +16,11 @@ test('search result renders correctly', () => {
             <SearchResult.Content>
                 {RESULT_CONTENT}
             </SearchResult.Content>
-            <SearchResult.Meta>
-                <SearchResult.MetaItem name={META_KEY}>
+            <SearchResult.Metadata>
+                <Metadata.Item name={META_KEY}>
                     {META_VALUE}
-                </SearchResult.MetaItem>
-            </SearchResult.Meta>
+                </Metadata.Item>
+            </SearchResult.Metadata>
             <SearchResult.Context>
                 <SearchResult.ContextItem>{CONTEXT_VALUE}</SearchResult.ContextItem>
             </SearchResult.Context>

package/src/components/SearchResult/SearchResult.tsx

@@ -2,18 +2,20 @@ import { Children, createContext, useContext } from 'react';
 import ConditionalWrapper from '../../common/ConditionalWrapper';
 import AspectBox from '../AspectBox';
 import Metadata from '../PageMetadata';
+import { SearchResultContextProps, SearchResultProps } from './types';
+import clsx from 'clsx';
 
 const SearchResultLinkHrefContext = createContext('');
 
 const SearchResultContent = ({
     children
-}: SGDS.Component.SearchResult.Content) => {
-    const otherChildren: any[] = [];
+}: React.AllHTMLAttributes<HTMLElement>) => {
+    const otherChildren: React.ReactNode[] = [];
     let imageChild: React.ReactNode = null;
 
     // assign to slots
     Children.forEach(children, (child: React.ReactNode) => {
-        const thisChild = child as React.ReactElement<any>;
+        const thisChild = child as React.JSX.Element;
         if (thisChild && thisChild.type === SearchResultMedia) {
             imageChild = thisChild;
         } else {
@@ -37,7 +39,7 @@ const SearchResultContent = ({
 const SearchResultContext = ({
     children,
     title = 'Part of'
-}: SGDS.Component.SearchResult.Context) => {
+}: SearchResultContextProps) => {
     return (
         <dl className="ds_search-result__context">
             <dt className="ds_search-result__context-key">{title}:</dt>
@@ -48,7 +50,7 @@ const SearchResultContext = ({
 
 const SearchResultContextItem = ({
     children
-}: SGDS.Component.SearchResult.ContextItem) => {
+}: React.AllHTMLAttributes<HTMLElement>) => {
     return (
         <dd className="ds_search-result__context-value">
             {children}
@@ -58,7 +60,7 @@ const SearchResultContextItem = ({
 
 const SearchResultMedia = ({
     children
-}: SGDS.Component.SearchResult.Media) => {
+}: React.AllHTMLAttributes<HTMLElement>) => {
     return (
         <div className="ds_search-result__media-wrapper">
             <a className="ds_search-result__media-link" href={useContext(SearchResultLinkHrefContext)} tabIndex={-1} aria-hidden="true">
@@ -72,7 +74,7 @@ const SearchResultMedia = ({
 
 const SearchResultMeta = ({
     children
-}: SGDS.Component.SearchResult.Meta) => {
+}: React.AllHTMLAttributes<HTMLElement>) => {
     return (
         <Metadata className="ds_search-result__metadata" isInline>
             {children}
@@ -88,14 +90,14 @@ const SearchResult = ({
     promotedTitle = 'Recommended',
     title,
     ...props
-}: SGDS.Component.SearchResult) => {
+}: SearchResultProps) => {
     const LINK_CLASS = 'ds_search-result__link';
 
     return (
-        <div className={[
+        <div className={clsx([
             'ds_search-result',
-            isPromoted ? 'ds_search-result--promoted' : ''
-        ].join(' ')}
+            isPromoted && 'ds_search-result--promoted'
+        ])}
             {...props}
         >
             <ConditionalWrapper
@@ -124,14 +126,12 @@ SearchResult.Content = SearchResultContent;
 SearchResult.Context = SearchResultContext;
 SearchResult.ContextItem = SearchResultContextItem;
 SearchResult.Media = SearchResultMedia;
-SearchResult.Meta = SearchResultMeta;
-SearchResult.MetaItem = Metadata.Item;
+SearchResult.Metadata = SearchResultMeta;
 
 SearchResultContent.displayName = 'SearchResult.Content';
 SearchResultContext.displayName = 'SearchResult.Context';
 SearchResultContextItem.displayName = 'SearchResult.ContextItem';
 SearchResultMedia.displayName = 'SearchResult.Media';
-SearchResultMeta.displayName = 'SearchResult.Meta';
-SearchResult.MetaItem.displayName = 'SearchResult.MetaItem';
+SearchResultMeta.displayName = 'SearchResult.Metadata';
 
 export default SearchResult;

package/src/components/SearchResult/types.ts

@@ -0,0 +1,13 @@
+import { LinkComponent } from "../../shared-types";
+
+export interface SearchResultContextProps extends React.AllHTMLAttributes<HTMLDListElement> {
+    title: string;
+}
+
+export interface SearchResultProps extends React.AllHTMLAttributes<HTMLElement> {
+    href: string;
+    isPromoted?: boolean;
+    linkComponent?: LinkComponent;
+    promotedTitle?: string;
+    title: string;
+}

package/src/components/SearchSort/SearchSort.stories.tsx

@@ -14,7 +14,8 @@ const meta = {
     },
     args: {
         id: 'sort-by',
-        label: 'Sort by'
+        label: 'Sort by',
+        children: <></>
     }
 } satisfies Meta<typeof SearchSort>;
 

package/src/components/SearchSort/SearchSort.tsx

@@ -1,6 +1,8 @@
 import { AllHTMLAttributes } from "react";
 import Button from "../Button";
 import Select from "../Select";
+import { SearchSortProps } from "./types";
+import clsx from 'clsx';
 
 const Option = ({
     children,
@@ -20,13 +22,13 @@ const SearchSort = ({
     label = 'Sort by',
     onApply,
     ...props
-}: SGDS.Component.SearchSort) => {
+}: SearchSortProps) => {
     return (
         <div
-            className={[
+            className={clsx([
                 'ds_sort-options',
                 className
-            ].join(' ')}
+            ])}
             {...props}
         >
             <Select id={id} label={label}>

package/src/components/SearchSort/types.ts

@@ -0,0 +1,7 @@
+export interface SearchSortProps extends React.AllHTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+    className?: string;
+    id?: string;
+    label?: string;
+    onApply?: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
+}

package/src/components/Select/Select.test.tsx

@@ -134,6 +134,48 @@ test('select with change function', () => {
     expect(ONCHANGE_FUNCTION).toHaveBeenCalled();
 });
 
+test('select with onBlur that is not a function', () => {
+    render(
+        <Select
+        id={SELECT_ID}
+        label={LABEL_TEXT}
+            // @ts-expect-error onBlur is not a function
+            onBlur='foo'
+        >
+            {OPTIONS}
+        </Select>
+    );
+
+    const select = screen.getByRole('combobox');
+
+    fireEvent.blur(select);
+
+    // todo: assertion
+    // success indicated by no errors thrown
+    // error would be thrown on an untestable thread
+});
+
+test('select with onChange that is not a function', () => {
+    render(
+        <Select
+        id={SELECT_ID}
+        label={LABEL_TEXT}
+            // @ts-expect-error onChange is not a function
+            onChange='foo'
+        >
+            {OPTIONS}
+        </Select>
+    );
+
+    const select = screen.getByRole('combobox');
+
+    fireEvent.change(select, {target: {value: 'button'}});
+
+    // todo: assertion
+    // success indicated by no errors thrown
+    // error would be thrown on an untestable thread
+});
+
 test('select with placeholder option', () => {
     const PLACEHOLDER_TEXT = 'foo';
 

package/src/components/Select/Select.tsx

@@ -1,5 +1,7 @@
 import ErrorMessage from '../ErrorMessage';
 import HintText from '../../common/HintText';
+import { SelectProps } from './types';
+import clsx from 'clsx';
 
 const Select = function ({
     children,
@@ -16,7 +18,7 @@ const Select = function ({
     placeholder,
     width,
     ...props
-}: SGDS.Component.Select) {
+}: SelectProps) {
     const errorMessageId = `error-message-${id}`;
     const hintTextId = `hint-text-${id}`;
     const describedbys: string[] = [];
@@ -24,13 +26,13 @@ const Select = function ({
     if (hintText) { describedbys.push(hintTextId) };
     if (errorMessage) { describedbys.push(errorMessageId) };
 
-    function handleBlur(event: React.FocusEvent) {
+    function handleBlur(event: React.FocusEvent<HTMLSelectElement>) {
         if (typeof onBlur === 'function') {
             onBlur(event);
         }
     }
 
-    function handleChange(event: React.ChangeEvent) {
+    function handleChange(event: React.ChangeEvent<HTMLSelectElement>) {
         if (typeof onChange === 'function') {
             onChange(event);
         }
@@ -39,15 +41,15 @@ const Select = function ({
     return (
         <>
             <label className="ds_label" htmlFor={id}>{label}</label>
-            {hintText && <HintText id={hintTextId} text={hintText} />}
+            {hintText && <HintText id={hintTextId}>{hintText}</HintText>}
             {errorMessage && <ErrorMessage id={errorMessageId}>{errorMessage}</ErrorMessage>}
             <div
-                className={[
+                className={clsx([
                     "ds_select-wrapper",
                     hasError && 'ds_input--error',
                     width && `ds_input--${width}`,
                     className
-                ].join(' ')}
+                ])}
                 {...props}
             >
                 <select

package/src/components/Select/types.ts

@@ -0,0 +1,7 @@
+import { FormFieldBase, InputWidth } from "../../shared-types";
+
+export interface SelectProps extends FormFieldBase<HTMLElement> {
+    defaultValue?: string;
+    placeholder?: string;
+    width?: InputWidth;
+}

package/src/components/SequentialNavigation/SequentialNavigation.tsx

@@ -1,19 +1,22 @@
+import { SequentialNavigationLinkProps, SequentialNavigationProps } from "./types";
+import clsx from 'clsx';
+
 const SeqNavLink = ({
     children,
     href,
     isPrev,
     linkComponent,
     textLabel
-}: SGDS.Component.SequentialNavigation.Link) => {
-    const LINK_CLASSES = [
+}:SequentialNavigationLinkProps) => {
+    const LINK_CLASSES = clsx([
         'ds_sequential-nav__button',
         isPrev ? 'ds_sequential-nav__button--left' : 'ds_sequential-nav__button--right'
-    ].join(' ');
+    ]);
 
-    const ITEM_CLASSES = [
+    const ITEM_CLASSES = clsx([
         'ds_sequential-nav__item',
         isPrev ? 'ds_sequential-nav__item--prev' : 'ds_sequential-nav__item--next'
-    ].join(' ');
+    ]);
 
     function processChildren(children: React.ReactNode) {
         const linkInner = <span className="ds_sequential-nav__text" data-label={textLabel}>{children}</span>
@@ -39,7 +42,7 @@ const NextLink = ({
     href,
     linkComponent,
     textLabel = 'Next'
-}: SGDS.Component.SequentialNavigation.Link) => {
+}: SequentialNavigationLinkProps) => {
     return <SeqNavLink href={href} linkComponent={linkComponent} textLabel={textLabel}>{children}</SeqNavLink>
 };
 
@@ -48,7 +51,7 @@ const PreviousLink = ({
     href,
     linkComponent,
     textLabel = 'Previous'
-}: SGDS.Component.SequentialNavigation.Link) => {
+}: SequentialNavigationLinkProps) => {
     return <SeqNavLink href={href} linkComponent={linkComponent} textLabel={textLabel} isPrev>{children}</SeqNavLink>
 };
 
@@ -57,13 +60,13 @@ const SequentialNavigation = ({
     children,
     className,
     ...props
-}: SGDS.Component.SequentialNavigation) => {
+}: SequentialNavigationProps) => {
     return (
         <nav
-            className={[
+            className={clsx([
                 'ds_sequential-nav',
                 className
-            ].join(' ')}
+            ])}
             aria-label={ariaLabel}
             {...props}
         >

package/src/components/SequentialNavigation/types.ts

@@ -0,0 +1,12 @@
+import { LinkComponent } from "../../shared-types";
+
+export interface SequentialNavigationLinkProps extends React.AllHTMLAttributes<HTMLDivElement> {
+    href: string;
+    isPrev?: boolean;
+    linkComponent?: LinkComponent;
+    textLabel?: string;
+}
+
+export interface SequentialNavigationProps extends React.AllHTMLAttributes<HTMLElement> {
+    ariaLabel?: React.AriaAttributes['aria-label'];
+}

package/src/components/SideNavigation/SideNavigation.test.tsx

@@ -109,6 +109,30 @@ test('side nav link with custom element', () => {
     expect(link?.textContent).toEqual(LINK_TEXT);
 });
 
+test('instantiating/initialising DS component script', () => {
+    render(
+        <SideNavigation>
+            <SideNavigation.List>
+                <SideNavigation.Item href="#dates" title="Dates"/>
+            </SideNavigation.List>
+        </SideNavigation>
+    );
+
+    const sideNavigation = screen.getByRole('navigation');
+    expect(sideNavigation).toHaveClass('js-initialised');
+    expect(sideNavigation).toHaveClass('js-instantiated');
+});
+
+test('instantiating/initialising DS component script: no children', () => {
+    render(
+        <SideNavigation />
+    );
+
+    const sideNavigation = screen.getByRole('navigation');
+    expect(sideNavigation).not.toHaveClass('js-initialised');
+    expect(sideNavigation).not.toHaveClass('js-instantiated');
+});
+
 test('passing additional props', () => {
     render(
         <SideNavigation data-test="foo" />

package/src/components/SideNavigation/SideNavigation.tsx

@@ -1,11 +1,12 @@
 import { useEffect, useRef } from 'react';
-// @ts-ignore
 import DSSideNavigation from '@scottish-government/design-system/src/components/side-navigation/side-navigation';
+import { SideNavigationItemProps, SideNavigationListProps, SideNavigationProps } from './types';
+import clsx from 'clsx';
 
 const SideNavigationList = function ({
     children,
     isRoot
-}: SGDS.Component.SideNavigation.List) {
+}: SideNavigationListProps) {
     return (
         <ul className="ds_side-navigation__list"
             id={isRoot ? 'side-navigation-root' : undefined }
@@ -21,15 +22,15 @@ const SideNavigationItem = function ({
     isCurrent = false,
     linkComponent,
     title
-}: SGDS.Component.SideNavigation.Item) {
+}: SideNavigationItemProps) {
     const LINK_CLASS = 'ds_side-navigation__link';
 
     return (
         <li
-            className={[
+            className={clsx([
                 'ds_side-navigation__item',
                 children && 'ds_side-navigation__item--has-children'
-            ].join(' ')}
+            ])}
         >
             {isCurrent ?
                 <span className={LINK_CLASS + ' ds_current'}>{title}</span> :
@@ -47,22 +48,25 @@ const SideNavigation = function ({
     children,
     className,
     ...props
-}: SGDS.Component.SideNavigation) {
+}: SideNavigationProps) {
     const ref = useRef(null);
 
     useEffect(() => {
-        if (ref.current && children) {
-            new DSSideNavigation(ref.current).init();
+        /* istanbul ignore else */
+        if (ref.current) {
+            if (children) {
+                new DSSideNavigation(ref.current).init();
+            }
         }
     }, [ref]);
 
     return (
         <nav
             aria-label={ariaLabel}
-            className={[
+            className={clsx([
                 'ds_side-navigation',
                 className
-            ].join(' ')}
+            ])}
             data-module="ds-side-navigation"
             ref={ref}
             {...props}

package/src/components/SideNavigation/types.ts

@@ -0,0 +1,16 @@
+import { LinkComponent } from "../../shared-types";
+
+export interface SideNavigationListProps extends React.AllHTMLAttributes<HTMLUListElement> {
+    isRoot?: boolean;
+}
+
+export interface SideNavigationItemProps extends React.AllHTMLAttributes<HTMLLIElement> {
+    isCurrent?: boolean;
+    href: string;
+    linkComponent?: LinkComponent;
+    title: string;
+}
+
+export interface SideNavigationProps extends React.AllHTMLAttributes<HTMLElement> {
+    ariaLabel?: string;
+}

package/src/components/SiteFooter/SiteFooter.tsx

@@ -1,10 +1,12 @@
 import React, { Children } from 'react';
 import ConditionalWrapper from '../../common/ConditionalWrapper';
+import { SiteFooterLicenseProps, SiteFooterLinkProps, SiteFooterOrgProps, SiteFooterProps } from './types';
+import clsx from 'clsx';
 
 const License = ({
     children,
     ...props
-}: SGDS.Component.SiteFooter.License) => {
+}: SiteFooterLicenseProps) => {
     return (
         <div className="ds_site-footer__copyright" {...props}>
             {children}
@@ -15,7 +17,7 @@ const License = ({
 const Links = ({
     children,
     ...props
-}: SGDS.Component.SiteFooter.Links) => {
+}: React.AllHTMLAttributes<HTMLUListElement>) => {
     return (
         <ul className="ds_site-footer__site-items" {...props}>
             {children}
@@ -28,7 +30,7 @@ const Link = ({
     href,
     linkComponent,
     ...props
-}: SGDS.Component.SiteFooter.Link) => {
+}: SiteFooterLinkProps) => {
     function processChildren(children: React.ReactNode) {
         if (linkComponent) {
             return linkComponent({ href, children });
@@ -49,9 +51,9 @@ const Org = ({
     title,
     children,
     ...props
-}: SGDS.Component.SiteFooter.Org) => {
+}: SiteFooterOrgProps) => {
     children = Children.map(children, child => {
-        let thisChild = child as React.ReactElement<HTMLElement>;
+        const thisChild = child as React.ReactElement<HTMLElement>;
         if (thisChild && ['img', 'svg', 'picture'].includes(thisChild.type as string)) {
             return React.cloneElement(thisChild, { className: 'ds_site-footer__org-logo' });
         } else {
@@ -75,13 +77,13 @@ const SiteFooter = ({
     children,
     className,
     ...props
-}: SGDS.Component.SiteFooter) => {
+}: SiteFooterProps) => {
     return (
         <footer
-            className={[
+            className={clsx([
                 "ds_site-footer",
                 className
-            ].join(' ')}
+            ])}
             {...props}
         >
             <div className="ds_wrapper">