@scottish-government/designsystem-react 0.12.1 → 1.0.0

package/src/components/Card/Card.test.tsx

@@ -0,0 +1,282 @@
+import { describe, test, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import Card from './Card';
+
+const CARD_TITLE = 'Bananas';
+const CARD_HREF = '#foo';
+const CARD_CONTENT = 'A banana is an elongated, edible fruit—botanically a berry—produced by several kinds of large treelike herbaceous flowering plants in the genus Musa.';
+const CARD_DESCRIPTION = 'New fruit added';
+const CARD_MEDIA = 'JPEG image of a banana';
+
+test('card renders correctly', () => {
+    render(
+        <Card href={CARD_HREF} data-testid="card">
+            <Card.Media isCover ratio="4:3" mediaWidth="wide">
+                {CARD_MEDIA}
+            </Card.Media>
+            <Card.Content>
+                <Card.ContentHeader title={CARD_TITLE}>
+                    <Card.StatusTag colour="orange" isHidden>New release</Card.StatusTag>
+                </Card.ContentHeader>
+                <Card.ContentMain>
+                    <p>{CARD_CONTENT}</p>
+                </Card.ContentMain>
+                <Card.ContentFooter>
+                    <Card.Metadata>
+                    </Card.Metadata>
+                </Card.ContentFooter>
+            </Card.Content>
+        </Card>
+    );
+
+    const card = screen.getByTestId('card');
+    const title = screen.getByRole('heading');
+    const link = screen.getByRole('link');
+    const content = card.querySelector('p');
+    const media = card.firstChild;
+    const aspectbox = media?.firstChild;
+    const metadata = card.querySelector('.ds_metadata');
+
+    expect(media).toHaveClass('ds_card__media', 'ds_card__media--cover', 'ds_card__media--wide');
+    expect(aspectbox).toHaveClass('ds_aspect-box', 'ds_aspect-box--43');
+
+    expect(card).toHaveClass('ds_card', 'ds_card--navigation');
+    expect(card.tagName).toEqual('DIV');
+
+    expect(title).toHaveClass('ds_card__title');
+    expect(title.tagName).toEqual('H2');
+    expect(title.textContent).toEqual(CARD_TITLE);
+    expect(title.parentElement).toHaveClass('ds_card__content-header');
+
+    expect(link).toHaveClass('ds_card__link', 'ds_card__link--cover');
+    expect(link).toHaveAttribute('href', CARD_HREF);
+    expect(link.textContent).toEqual(CARD_TITLE);
+    expect(link.parentElement).toEqual(title);
+
+    expect(content?.parentElement).toHaveClass('ds_card__content-main');
+    expect(content?.textContent).toEqual(CARD_CONTENT);
+
+    expect(metadata).toHaveClass('ds_metadata', 'ds_metadata--inline');
+    expect(metadata?.parentElement).toHaveClass('ds_card__content-footer');
+});
+
+test('container added for adaptive card', () => {
+    render(
+        <Card data-testid="card" isAdaptive>
+            <Card.Content>
+                <Card.ContentHeader
+                    title={CARD_TITLE}>
+                </Card.ContentHeader>
+            </Card.Content>
+        </Card>
+    );
+
+    const card = screen.getByTestId('card');
+    const container = card.parentElement
+
+    expect(container).toHaveClass('ds_card-container');
+});
+
+test('description added', () => {
+    render(
+        <Card data-testid="card">
+            <Card.Content>
+                <Card.ContentHeader
+                    title={CARD_TITLE}
+                    description={CARD_DESCRIPTION}>
+                </Card.ContentHeader>
+            </Card.Content>
+        </Card>
+    );
+
+    const description = screen.getByText(', '+CARD_DESCRIPTION);
+
+    expect(description).toHaveClass('visually-hidden');
+    expect(description.tagName).toEqual('SPAN');
+    expect(description.parentElement).toHaveClass('ds_card__title');
+});
+
+test('display variant classes added', () => {
+    render(
+        <Card
+            data-testid="card"
+            hasSecondaryBackground
+            isHorizontal
+            isHorizontalSmall>
+            <Card.Content>
+                <Card.ContentHeader
+                    title={CARD_TITLE}
+                    >
+                </Card.ContentHeader>
+            </Card.Content>
+        </Card>
+    );
+
+    const card = screen.getByTestId('card');
+
+    expect(card).toHaveClass('ds_card', 'ds_card--background-secondary', 'ds_card--horizontal', 'ds_card--horizontal-small');
+});
+
+test('custom heading level', () => {
+    render(
+        <Card href={CARD_HREF} data-testid="card" headingLevel="h3">
+            <Card.Content>
+                <Card.ContentHeader
+                    title={CARD_TITLE}>
+                </Card.ContentHeader>
+            </Card.Content>
+        </Card>
+    );
+
+    const title = screen.getByRole('heading');
+    expect(title.tagName).toEqual('H3');
+});
+
+test('custom element', () => {
+    render(
+        <Card data-testid="card" tagName="article">
+            <Card.Content>
+                <Card.ContentHeader
+                    title={CARD_TITLE}>
+                </Card.ContentHeader>
+            </Card.Content>
+        </Card>
+    );
+
+    const card = screen.getByTestId('card');
+    expect(card.tagName).toEqual('ARTICLE');
+});
+
+test('custom link component', () => {
+    render(
+        <Card href={CARD_HREF} data-testid="card" linkComponent={
+            ({ className, ...props }) => (
+                <span role="link" className={className} {...props}/>
+            )}>
+            <Card.ContentHeader
+                title={CARD_TITLE}>
+            </Card.ContentHeader>
+        </Card>
+    );
+
+    const link = screen.getByRole('link');
+
+    expect(link.tagName).toEqual('SPAN');
+    expect(link.textContent).toEqual(CARD_TITLE);
+});
+
+describe('card status tag', () => {
+    const TAG_TEXT = 'Foo';
+
+    test('card status tag', () => {
+        render(
+            <Card.StatusTag data-testid="status-tag">{TAG_TEXT}</Card.StatusTag>
+        );
+
+        const statusTag = screen.getByTestId('status-tag');
+
+        expect(statusTag).toHaveClass('ds_tag');
+        expect(statusTag.tagName).toEqual('SPAN');
+        expect(statusTag.textContent).toEqual(TAG_TEXT);
+        expect(statusTag.getAttribute('aria-hidden')).not.toEqual('true');
+    });
+
+    test('card status tag: hidden', () => {
+        render(
+            <Card.StatusTag data-testid="status-tag" isHidden>{TAG_TEXT}</Card.StatusTag>
+        );
+
+        const statusTag = screen.getByTestId('status-tag');
+
+        expect(statusTag).toHaveClass('ds_tag');
+        expect(statusTag.getAttribute('aria-hidden')).toEqual('true');
+    });
+});
+
+describe('card media', () => {
+    test('card media', () => {
+        render(
+            <Card.Media data-testid="card-media">
+                {CARD_MEDIA}
+            </Card.Media>
+        );
+
+        const cardMedia = screen.getByTestId('card-media');
+
+        expect(cardMedia).toHaveClass('ds_card__media');
+        expect(cardMedia.tagName).toEqual('DIV');
+        expect(cardMedia.innerHTML).toEqual(CARD_MEDIA);
+    });
+
+    test('card media with isCover and ratio', () => {
+        render(
+            <Card.Media isCover ratio="4:3" data-testid="card-media">
+                {CARD_MEDIA}
+            </Card.Media>
+        );
+
+        const cardMedia = screen.getByTestId('card-media');
+        const cardMediaInner = cardMedia.querySelector('*');
+
+        expect(cardMedia).toHaveClass('ds_card__media--cover');
+        expect(cardMediaInner).toHaveClass('ds_aspect-box', 'ds_aspect-box--43');
+    });
+
+    test('card media with only isCover', () => {
+        render(
+            <Card.Media isCover data-testid="card-media">
+                {CARD_MEDIA}
+            </Card.Media>
+        );
+
+        const cardMedia = screen.getByTestId('card-media');
+        const cardMediaInner = cardMedia.querySelector('*');
+
+        expect(cardMedia).not.toHaveClass('ds_card__media--cover');
+        expect(cardMediaInner).not.toBeInTheDocument();
+    });
+
+    test('card media with only ratio', () => {
+        render(
+            <Card.Media ratio="4:3" data-testid="card-media">
+                {CARD_MEDIA}
+            </Card.Media>
+        );
+
+        const cardMedia = screen.getByTestId('card-media');
+        const cardMediaInner = cardMedia.querySelector('*');
+
+        expect(cardMedia).not.toHaveClass('ds_card__media--cover');
+        expect(cardMediaInner).toHaveClass('ds_aspect-box', 'ds_aspect-box--43');
+    });
+
+    test('card media with mediaWidth', () => {
+        render(
+            <Card.Media mediaWidth="narrow" data-testid="card-media">
+                {CARD_MEDIA}
+            </Card.Media>
+        );
+
+        const cardMedia = screen.getByTestId('card-media');
+
+        expect(cardMedia).toHaveClass('ds_card__media--narrow');
+    });
+});
+
+test('passing additional props', () => {
+    render(
+        <Card data-test="foo" data-testid="card"/>
+    );
+
+    const card = screen.getByTestId('card');
+    expect(card.dataset.test).toEqual('foo');
+});
+
+test('passing additional CSS classes', () => {
+    render(
+        <Card className="foo" data-testid="card"/>
+    );
+
+    const card = screen.getByTestId('card');
+    expect(card).toHaveClass('foo');
+});

package/src/components/Card/Card.tsx

@@ -0,0 +1,208 @@
+import { createContext, useContext } from 'react';
+import ConditionalWrapper from "../../common/ConditionalWrapper";
+import WrapperTag from "../../common/WrapperTag";
+import AspectBox from '../AspectBox';
+import Metadata from '../PageMetadata';
+import Tag from '../Tag';
+import { CardProps, CardHeaderProps, CardMediaProps, CardStatusTagProps } from "./types";
+import { HeadingLevel, LinkComponent } from '@/src/shared-types';
+import clsx from 'clsx';
+
+type CardSettingsContextProps = {
+    headingLevel: HeadingLevel
+    href?: string
+    linkComponent?: LinkComponent
+};
+
+const CardSettingsContext = createContext<CardSettingsContextProps>({
+    headingLevel: 'h2',
+    href: undefined,
+    linkComponent: undefined
+});
+
+const CardContent = ({
+    children
+}: React.AllHTMLAttributes<HTMLElement>) => {
+    return (
+        <div className="ds_card__content">
+            {children}
+        </div>
+    )
+};
+
+const CardContentHeader = ({
+    children,
+    description,
+    title
+}: CardHeaderProps) => {
+    const headingLevel = useContext(CardSettingsContext).headingLevel;
+    const href = useContext(CardSettingsContext).href;
+    const linkComponent = useContext(CardSettingsContext).linkComponent;
+    const LINK_CLASS = 'ds_card__link  ds_card__link--cover';
+
+    function getLinkElement(children: React.ReactNode) {
+        let linkElement;
+        if (linkComponent) {
+            linkElement = linkComponent({ className: LINK_CLASS, href, children });
+        } else {
+            linkElement = <a href={href} className={LINK_CLASS}>{children}</a>;
+        }
+        return linkElement as React.JSX.Element;
+    }
+
+    return (
+        <div className="ds_card__content-header">
+            {children}
+            <WrapperTag
+                className="ds_card__title"
+                tagName={headingLevel}
+            >
+                <ConditionalWrapper
+                    condition={typeof href !== 'undefined'}
+                    wrapper={(children: React.JSX.Element) => getLinkElement(children)}
+                >
+                    {title}
+                    {description && <span className="visually-hidden">, {description}</span>}
+                </ConditionalWrapper>
+            </WrapperTag>
+        </div>
+    )
+};
+
+const CardStatusTag = ({
+    children,
+    colour,
+    isHidden,
+    ...props
+}: CardStatusTagProps) => {
+    return (
+        <Tag
+            aria-hidden={isHidden ? "true" : undefined}
+            colour={colour}
+            {...props}
+        >
+            {children}
+        </Tag>
+    )
+};
+
+const CardContentMain = ({
+    children
+}: React.AllHTMLAttributes<HTMLElement>) => {
+    return (
+        <div className="ds_card__content-main">
+            {children}
+        </div>
+    )
+};
+
+const CardContentFooter = ({
+    children
+}: React.AllHTMLAttributes<HTMLElement>) => {
+    return (
+        <div className="ds_card__content-footer">
+            {children}
+        </div>
+    )
+};
+
+const CardMetadata = ({
+    children
+}: React.AllHTMLAttributes<HTMLElement>) => {
+    return (
+        <Metadata isInline>
+            {children}
+        </Metadata>
+    )
+};
+
+const CardMedia = ({
+    children,
+    isCover,
+    mediaWidth,
+    ratio,
+    ...props
+}: CardMediaProps) => {
+    return (
+        <div 
+            className={clsx([
+                'ds_card__media',
+                isCover && ratio && 'ds_card__media--cover',
+                (mediaWidth && (mediaWidth === 'narrow' || mediaWidth === 'wide')) && 'ds_card__media--' + mediaWidth
+            ])}
+            {...props}
+        >
+            <ConditionalWrapper
+                condition={ratio !== undefined}
+                wrapper={(children: React.JSX.Element) => <AspectBox ratio={ratio}>
+                {children}
+            </AspectBox>}
+            >
+                {children}
+            </ConditionalWrapper>
+        </div>
+    )
+};
+
+const Card = ({
+    children,
+    className,
+    hasSecondaryBackground = false,
+    headingLevel,
+    href,
+    isAdaptive = false,
+    isHorizontal = false,
+    isHorizontalSmall = false,
+    linkComponent,
+    tagName = 'div',
+    ...props
+}: CardProps) => {
+    return (
+        <CardSettingsContext value={{
+            headingLevel: headingLevel || 'h2',
+            href: href,
+            linkComponent: linkComponent
+        }}>
+            <ConditionalWrapper
+                condition={isAdaptive}
+                wrapper={(children: React.JSX.Element) => <div className="ds_card-container">
+                    {children}
+                </div>}
+            >
+                <WrapperTag
+                    tagName={tagName}
+                    className={clsx([
+                        'ds_card',
+                        href && 'ds_card--navigation',
+                        hasSecondaryBackground && 'ds_card--background-secondary',
+                        isHorizontal && 'ds_card--horizontal',
+                        isHorizontalSmall && 'ds_card--horizontal-small',
+                        className
+                    ])}
+                    {...props}
+                >
+                    {children}
+                </WrapperTag>
+            </ConditionalWrapper>
+        </CardSettingsContext>
+    );
+};
+
+Card.Content = CardContent;
+Card.ContentFooter = CardContentFooter;
+Card.ContentHeader = CardContentHeader;
+Card.ContentMain = CardContentMain;
+Card.Metadata = CardMetadata;
+Card.Media = CardMedia;
+Card.StatusTag = CardStatusTag;
+
+Card.displayName = 'Card';
+CardContent.displayName = 'Card.Content';
+CardContentFooter.displayName = 'Card.ContentFooter';
+CardContentHeader.displayName = 'Card.ContentHeader';
+CardContentMain.displayName = 'Card.ContentMain';
+CardMetadata.displayName = 'Card.Metadata';
+CardMedia.displayName = 'Card.Media';
+CardStatusTag.displayName = 'Card.StatusTag';
+
+export default Card;

package/src/components/Card/index.ts

@@ -0,0 +1 @@
+export { default } from './Card';

package/src/components/Card/types.ts

@@ -0,0 +1,30 @@
+import { HeadingLevel, LinkComponent } from '../../shared-types';
+import { TagProps } from '../Tag/types';
+
+export interface CardProps extends React.AllHTMLAttributes<HTMLElement> {
+    className?: string
+    hasSecondaryBackground?: boolean
+    headingLevel?: HeadingLevel
+    href?: string
+    isAdaptive?: boolean
+    isHorizontal?: boolean
+    isHorizontalSmall?: boolean
+    linkComponent?: LinkComponent
+    tagName?: string
+}
+
+export interface CardHeaderProps extends React.AllHTMLAttributes<HTMLElement> {
+    className?: string
+    description?: string
+    title: string
+}
+
+export interface CardMediaProps extends React.AllHTMLAttributes<HTMLElement> {
+    isCover?: boolean
+    mediaWidth?: 'narrow' | 'wide'
+    ratio?: 'square' | '1:1' | '4:3' | '16:9' | '21:9'
+}
+
+export interface CardStatusTagProps extends TagProps {
+    isHidden?: boolean
+}

package/src/components/CategoryItem/CategoryItem.tsx

@@ -1,5 +1,7 @@
 import ConditionalWrapper from "../../common/ConditionalWrapper";
 import WrapperTag from "../../common/WrapperTag";
+import { CategoryItemProps } from "./types";
+import clsx from 'clsx';
 
 const CategoryItem = ({
     children,
@@ -10,24 +12,26 @@ const CategoryItem = ({
     tagName = 'div',
     title,
     ...props
-}: SGDS.Component.CategoryItem) => {
+}: CategoryItemProps) => {
     const LINK_CLASS = 'ds_category-item__link';
 
     function getLinkElement(children: React.ReactNode) {
+        let linkElement;
         if (linkComponent) {
-            return linkComponent({ className: LINK_CLASS, href, children });
-        } else if (href) {
-            return <a href={href} className={LINK_CLASS}>{children}</a>;
+            linkElement = linkComponent({ className: LINK_CLASS, href, children });
+        } else {
+            linkElement = <a href={href} className={LINK_CLASS}>{children}</a>;
         }
+        return linkElement as React.JSX.Element;
     }
 
     return (
         <WrapperTag
             tagName={tagName}
-            className={[
+            className={clsx([
                 'ds_category-item',
                 className
-            ].join(' ')}
+            ])}
             {...props}
         >
             <WrapperTag

package/src/components/CategoryItem/types.ts

@@ -0,0 +1,10 @@
+import { HeadingLevel, LinkComponent } from '../../shared-types';
+
+export interface CategoryItemProps extends React.AllHTMLAttributes<HTMLElement> {
+    className?: string;
+    headingLevel?: HeadingLevel;
+    href?: string;
+    linkComponent?: LinkComponent;
+    tagName?: string;
+    title: string;
+}

package/src/components/CategoryList/CategoryList.tsx

@@ -1,5 +1,8 @@
 import React, { Children } from 'react';
 import WrapperTag from "../../common/WrapperTag";
+import { CategoryListProps } from './types';
+import { CategoryItemProps } from '../CategoryItem/types';
+import clsx from 'clsx';
 
 const CategoryList = ({
     children,
@@ -7,20 +10,20 @@ const CategoryList = ({
     isGrid,
     isOrdered,
     ...props
-}: SGDS.Component.CategoryList) => {
+}: CategoryListProps) => {
     function processChild(child: React.ReactNode) {
-        const thisChild = child as React.ReactElement<SGDS.Component.CategoryItem>
+        const thisChild = child as React.ReactElement<CategoryItemProps>
         return React.cloneElement(thisChild, {tagName: 'li'})
     }
 
     return (
         <WrapperTag
             tagName={isOrdered ? 'ol' : 'ul'}
-            className={[
+            className={clsx([
                 'ds_category-list',
                 isGrid && 'ds_category-list--grid',
                 className
-            ].join(' ')}
+            ])}
             {...props}
         >
             {Children.map(children, child => processChild(child))}

package/src/components/CategoryList/types.ts

@@ -0,0 +1,5 @@
+export interface CategoryListProps extends React.AllHTMLAttributes<HTMLElement> {
+    className?: string;
+    isGrid?: boolean;
+    isOrdered?: boolean;
+}

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -12,18 +12,18 @@ const meta = {
             description: 'The checkbox is checked on load'
         },
         hintText: argTypes.hintText,
-        exclusive: {
+        isExclusive: {
             control: 'boolean',
             description: 'Whether the checkbox is exclusive (e.g. a \'none\' option)'
         },
         id: argTypes.id(),
+        isSmall: argTypes.isSmall(),
         label: argTypes.label(),
         name: {
             type: 'string'
         },
         onBlur: argTypes.onBlur(),
-        onChange: argTypes.onChange(),
-        small: argTypes.isSmall()
+        onChange: argTypes.onChange()
     },
     args: {
         label: 'Benefits and grants',

package/src/components/Checkbox/Checkbox.test.tsx

@@ -74,6 +74,36 @@ test('checkbox with change fn', () => {
     expect(ONCHANGE_FUNCTION).toHaveBeenCalled();
 });
 
+test('checkbox with onBlur that is not a function', () => {
+    render(
+        // @ts-expect-error onBlur is not a function
+        <Checkbox onBlur='foo' label="Pension Credit" id="pensioncredit" />
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+
+    fireEvent.blur(checkbox);
+
+    // todo: assertion
+    // success indicated by no errors thrown
+    // error would be thrown on an untestable thread
+});
+
+test('checkbox with onChange that is not a function', () => {
+    render(
+        // @ts-expect-error onChange is not a function
+        <Checkbox onChange='foo' label="Pension Credit" id="pensioncredit" />
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+
+    fireEvent.click(checkbox);
+
+    // todo: assertion
+    // success indicated by no errors thrown
+    // error would be thrown on an untestable thread
+});
+
 test('checkbox with hint text', () => {
     render(
         <Checkbox hintText="hint text" label="Pension Credit" id="pensioncredit" />