@dhis2-ui/button 10.16.1 → 10.16.3-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/button",
-    "version": "10.16.1",
+    "version": "10.16.3-alpha.1",
     "description": "UI Button",
     "repository": {
         "type": "git",
@@ -33,17 +33,18 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/layer": "10.16.1",
-        "@dhis2-ui/loader": "10.16.1",
-        "@dhis2-ui/popper": "10.16.1",
-        "@dhis2/ui-constants": "10.16.1",
-        "@dhis2/ui-icons": "10.16.1",
+        "@dhis2-ui/layer": "10.16.3-alpha.1",
+        "@dhis2-ui/loader": "10.16.3-alpha.1",
+        "@dhis2-ui/popper": "10.16.3-alpha.1",
+        "@dhis2/ui-constants": "10.16.3-alpha.1",
+        "@dhis2/ui-icons": "10.16.3-alpha.1",
         "classnames": "^2.3.1",
         "prop-types": "^15.7.2"
     },
     "files": [
         "build",
-        "types"
+        "types",
+        "src"
     ],
     "devDependencies": {
         "react": "^18.3.1",

package/src/button/__tests__/Button.test.js

@@ -0,0 +1,126 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import { mount } from 'enzyme'
+import React from 'react'
+import { Button } from '../button.js'
+
+describe('<Button>', () => {
+    let consoleSpy
+
+    beforeEach(() => {
+        consoleSpy = jest.spyOn(console, 'debug').mockImplementation()
+    })
+
+    afterEach(() => {
+        consoleSpy.mockRestore()
+    })
+
+    describe('warning for missing aria-label and title', () => {
+        it('No warning  if children exist but aria-label and title is missing', () => {
+            render(<Button>Children content</Button>)
+
+            expect(consoleSpy).not.toHaveBeenCalled()
+        })
+
+        it('does not warn if aria-label and title is present', () => {
+            render(
+                <Button aria-label="Test" title="Test">
+                    Children content
+                </Button>
+            )
+
+            expect(consoleSpy).not.toHaveBeenCalled()
+        })
+
+        it('warns if no children are present with no arial-label and title', () => {
+            render(<Button>{/* No children */}</Button>)
+
+            expect(consoleSpy).toHaveBeenCalledWith(
+                'Button component has no children but is missing title and ariaLabel attribute.'
+            )
+        })
+
+        it('No warning if there are no children but arial label and title', () => {
+            render(
+                <Button aria-label="Test" title="Test">
+                    {/* No children */}
+                </Button>
+            )
+
+            expect(consoleSpy).not.toHaveBeenCalled()
+        })
+    })
+
+    it('renders a default data-test attribute', () => {
+        const dataTest = 'dhis2-uicore-button'
+        const wrapper = mount(<Button dataTest={dataTest} />)
+
+        const actual = wrapper.find({ 'data-test': dataTest })
+
+        expect(actual.length).toBe(1)
+    })
+
+    it('renders a custom data-test attribute', () => {
+        const dataTest = 'button-data-test'
+        const wrapper = mount(<Button dataTest={dataTest} />)
+
+        const actual = wrapper.find({ 'data-test': dataTest })
+
+        expect(actual.length).toBe(1)
+    })
+
+    it('has the accessibility attributes', () => {
+        const dataTest = 'button-data-test'
+        const wrapper = mount(
+            <Button
+                dataTest={dataTest}
+                ariaLabel="test aria label"
+                title="title for button"
+            />
+        )
+        const buttonElement = wrapper.find('button').getDOMNode()
+        expect(buttonElement).toHaveAttribute('title', 'title for button')
+        expect(buttonElement).toHaveAttribute('ariaLabel', 'test aria label')
+    })
+
+    describe('toggle', () => {
+        it('should have class "toggled" if toggled-prop is true', () => {
+            const wrapper = mount(<Button toggled />)
+
+            const actual = wrapper.find('button')
+            expect(actual.hasClass('toggled')).toBe(true)
+        })
+        it('should not have class "toggled" if toggled-prop is not passed', () => {
+            const wrapper = mount(<Button />)
+
+            const actual = wrapper.find('button')
+            expect(actual.hasClass('toggled')).toBe(false)
+        })
+    })
+
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(
+            <Button
+                name="button-name"
+                value="button-value"
+                onKeyDown={onKeyDown}
+            >
+                btn
+            </Button>
+        )
+
+        fireEvent.keyDown(screen.getByRole('button'), {
+            key: 'Enter',
+            code: 'Enter',
+            charCode: 13,
+        })
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'button-name', value: 'button-value' },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+})

package/src/button/button.e2e.stories.js

@@ -0,0 +1,24 @@
+import React from 'react'
+import { Button } from './button.js'
+
+window.onClick = window.Cypress && window.Cypress.cy.stub()
+window.onBlur = window.Cypress && window.Cypress.cy.stub()
+window.onFocus = window.Cypress && window.Cypress.cy.stub()
+
+export default { title: 'Button' }
+
+export const WithOnClick = () => (
+    <Button name="Button" value="default" onClick={window.onClick}>
+        Label me!
+    </Button>
+)
+export const WithInitialFocusAndOnBlur = () => (
+    <Button name="Button" value="default" initialFocus onBlur={window.onBlur}>
+        Label me!
+    </Button>
+)
+export const WithOnFocus = () => (
+    <Button name="Button" value="default" onFocus={window.onFocus}>
+        Label me!
+    </Button>
+)

package/src/button/button.js

@@ -0,0 +1,162 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import { CircularLoader } from '@dhis2-ui/loader'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { useEffect, useRef } from 'react'
+import styles from './button.styles.js'
+
+export const Button = ({
+    children,
+    className,
+    dataTest = 'dhis2-uicore-button',
+    destructive,
+    disabled,
+    icon,
+    initialFocus,
+    large,
+    name,
+    primary,
+    secondary,
+    small,
+    tabIndex,
+    toggled,
+    type = 'button',
+    value,
+    onBlur,
+    onClick,
+    onFocus,
+    onKeyDown,
+    loading,
+    ...otherProps
+}) => {
+    const ref = useRef()
+
+    useEffect(() => {
+        if (initialFocus && ref.current) {
+            ref.current.focus()
+        }
+    }, [initialFocus, ref.current])
+
+    const { 'aria-label': ariaLabel, title } = otherProps
+
+    if (!children && !title && !ariaLabel) {
+        console.debug(
+            'Button component has no children but is missing title and ariaLabel attribute.'
+        )
+    }
+
+    const handleClick = (event) => onClick && onClick({ value, name }, event)
+    const handleBlur = (event) => onBlur && onBlur({ value, name }, event)
+    const handleFocus = (event) => onFocus && onFocus({ value, name }, event)
+    const handleKeyDown = (event) =>
+        onKeyDown && onKeyDown({ value, name }, event)
+
+    const iconOnly = icon && !children
+    const buttonClassName = cx(className, {
+        primary,
+        secondary,
+        destructive,
+        small,
+        large,
+        'icon-only': iconOnly,
+        toggled,
+        loading: loading,
+    })
+
+    return (
+        <button
+            ref={ref}
+            name={name}
+            className={buttonClassName}
+            data-test={dataTest}
+            disabled={disabled || loading}
+            tabIndex={tabIndex}
+            type={type}
+            onBlur={handleBlur}
+            onClick={handleClick}
+            onFocus={handleFocus}
+            onKeyDown={handleKeyDown}
+            {...otherProps}
+        >
+            {loading && (
+                <span className="loader">
+                    {destructive || primary ? (
+                        <CircularLoader extrasmall invert />
+                    ) : (
+                        <CircularLoader extrasmall />
+                    )}
+                </span>
+            )}
+            {icon && <span className="button-icon">{icon}</span>}
+            {children}
+            <style jsx>{styles}</style>
+        </button>
+    )
+}
+
+Button.propTypes = {
+    /** Component to render inside the button */
+    children: PropTypes.node,
+    /** A className that will be passed to the `<button>` element */
+    className: PropTypes.string,
+    /**
+     * A string that will be applied as a `data-test` attribute on the button element
+     * for identification during testing
+     */
+    dataTest: PropTypes.string,
+    /**
+     * Applies 'destructive' button appearance, implying a dangerous action.
+     */
+    destructive: PropTypes.bool,
+    /** Applies a greyed-out appearance and makes the button non-interactive  */
+    disabled: PropTypes.bool,
+    /** An icon element to display inside the button */
+    icon: PropTypes.element,
+    /** Use this variant to capture the initial focus on the page. */
+    initialFocus: PropTypes.bool,
+    /** Makes the button large. Mutually exclusive with `small` */
+    large: sharedPropTypes.sizePropType,
+    /** Sets the button into a loading state */
+    loading: PropTypes.bool,
+    /**
+     * Sets `name` attribute on button element.
+     * Gets passed as part of the first argument to callbacks (see `onClick`).
+     */
+    name: PropTypes.string,
+    /**
+     * Applies 'primary' button appearance, implying the most important action.
+     */
+    primary: PropTypes.bool,
+    /**
+     * Applies 'secondary' button appearance.
+     */
+    secondary: PropTypes.bool,
+    /** Makes the button small. Mutually exclusive with `large` prop */
+    small: sharedPropTypes.sizePropType,
+    /** Tab index for focusing the button with a keyboard */
+    tabIndex: PropTypes.string,
+    /** Changes appearance of button to an on/off state */
+    toggled: PropTypes.bool,
+    /** Sets `type` attribute on `<button>` element */
+    type: PropTypes.oneOf(['submit', 'reset', 'button']),
+    /**
+     * Value associated with the button.
+     * Gets passed as part of the first argument to callbacks (see `onClick`).
+     */
+    value: PropTypes.string,
+    /**
+     * Callback to trigger on de-focus (blur).
+     * Called with same args as `onClick`
+     * */
+    onBlur: PropTypes.func,
+    /**
+     * Callback to trigger on click.
+     * Called with args `({ value, name }, event)`
+     * */
+    onClick: PropTypes.func,
+
+    /** Callback to trigger on focus. Called with same args as `onClick` */
+    onFocus: PropTypes.func,
+    /** Callback to trigger on key-down. Called with same args as `onClick` */
+    onKeyDown: PropTypes.func,
+}

package/src/button/button.prod.stories.js

@@ -0,0 +1,305 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React from 'react'
+import { Button } from './button.js'
+
+// Note: make sure 'fenced code blocks' are not indentend in this template string
+const description = `Buttons are used for triggering actions.
+There are different types of buttons in the design system which are intended
+for different types of actions.
+
+\`\`\`js
+import { Button } from '@dhis2/ui'
+\`\`\``
+
+const { buttonVariantArgType, sizeArgType } = sharedPropTypes
+
+const logger = ({ name, value }) => console.log(`${name}: ${value}`)
+
+export default {
+    title: 'Button',
+    component: Button,
+    parameters: {
+        componentSubtitle: 'Initiates an action',
+        docs: {
+            description: {
+                component: description,
+            },
+        },
+    },
+    args: {
+        children: 'Label me!',
+        value: 'default',
+        onClick: logger,
+        title: 'Button',
+        ariaLabel: 'Button',
+    },
+    argTypes: {
+        primary: { ...buttonVariantArgType },
+        secondary: { ...buttonVariantArgType },
+        destructive: { ...buttonVariantArgType },
+        small: { ...sizeArgType },
+        large: { ...sizeArgType },
+    },
+}
+
+const DemoIcon24 = (
+    <svg
+        height="24"
+        viewBox="0 0 24 24"
+        width="24"
+        xmlns="http://www.w3.org/2000/svg"
+    >
+        <path
+            d="m10.7071068 13.2928932c.3604839.360484.3882135.927715.0831886 1.3200062l-.0831886.0942074-5.2921068 5.2918932 2.585.001c.51283584 0 .93550716.3860402.99327227.8833789l.00672773.1166211c0 .5128358-.38604019.9355072-.88337887.9932723l-.11662113.0067277h-5l-.0193545-.0001861c-.02332655-.0004488-.04664039-.0017089-.06989557-.0037803l.08925007.0039664c-.05062028 0-.10036209-.0037612-.14896122-.0110193-.01698779-.0026088-.03441404-.0056829-.05176454-.0092208-.02202032-.0043997-.04371072-.0095935-.06511385-.0154809-.01562367-.0043767-.03101173-.0090077-.04630291-.0140171-.01965516-.0063844-.03943668-.0135776-.058916-.0213659-.01773713-.0070924-.03503998-.014575-.05216303-.0225694-.02066985-.0097032-.0410724-.0201205-.0610554-.0312024-.01211749-.006623-.02433616-.0137311-.0364318-.0211197-.0255662-.0157232-.05042194-.0324946-.07445055-.050318-.00744374-.0054399-.01468311-.010971-.02186305-.0166142-.0631594-.049624-.12042594-.1068905-.17019169-.1703222l.08010726.0903567c-.03539405-.0353941-.06758027-.0727812-.09655864-.1118002-.01784449-.0241759-.03461588-.0490316-.05026715-.0746464-.00746051-.0120471-.0145686-.0242658-.02139626-.0365981-.01087725-.0197682-.02129453-.0401707-.03101739-.060963-.00797473-.0170006-.01545736-.0343035-.02242829-.0517631-.00790975-.0197568-.015103-.0395383-.02167881-.0595996-.00481796-.0148851-.00944895-.0302731-.01370154-.0457434-.00601151-.0215565-.01120534-.0432469-.01567999-.0651989-.00346298-.0174188-.00653707-.0348451-.00914735-.0523272-.00160026-.010231-.00303174-.021012-.00429007-.0318458l-.00276132-.027371c-.00207143-.0232552-.00333152-.0465691-.00378026-.0698956l-.00018615-.0193545v-5c0-.5522847.44771525-1 1-1 .51283584 0 .93550716.3860402.99327227.8833789l.00672773.1166211v2.584l5.29289322-5.2911068c.39052429-.3905243 1.02368928-.3905243 1.41421358 0zm9.2928932-3.2928932v10h-10v-2h8v-8zm-6-6v2h-8v7h-2v-9zm7-2 .0193545.00018615c.0233265.00044874.0466404.00170883.0698956.00378026l-.0892501-.00396641c.0506203 0 .1003621.00376119.1489612.01101934.0169878.00260874.0344141.00568283.0517646.00922073.0220203.00439973.0437107.00959356.0651138.0154809.0156237.00437676.0310117.00900775.0463029.01401712.0196552.0063844.0394367.01357765.058916.02136587.0177371.00709246.03504.01457509.052163.0225694.0206699.00970328.0410724.02012056.0610555.03120241.0121174.00662306.0243361.01373115.0364318.02111968.0255662.01572325.0504219.03249464.0744505.05031806.0074437.00543993.0146831.01097097.021863.01661418.0631595.04962402.120426.10689056.1701917.17032223l-.0801072-.0903567c.035394.03539405.0675802.0727812.0965586.11180017.0178445.02417592.0346159.04903166.0502672.07464642.0074605.01204708.0145686.02426575.0213962.03659809.0108773.01976815.0212946.0401707.0310174.06096295.0079748.01700065.0154574.0343035.0224283.05176313.0079098.01975682.015103.03953834.0216788.05959961.004818.01488507.009449.03027313.0137016.04574344.0060115.02155649.0112053.04324689.0156799.06519887.003463.01741884.0065371.03484509.0091474.05232723.0016003.01023098.0030317.02101195.0042901.03184574l.0030256.03039033c.0015457.01796531.0026074.03596443.003185.05397618l.0005171.03225462v5c0 .55228475-.4477153 1-1 1-.5128358 0-.9355072-.38604019-.9932723-.88337887l-.0067277-.11662113v-2.586l-5.2928932 5.2931068c-.3905243.3905243-1.0236893.3905243-1.4142136 0-.3604839-.360484-.3882135-.92771504-.0831886-1.32000624l.0831886-.09420734 5.2911068-5.29289322h-2.584c-.5128358 0-.9355072-.38604019-.9932723-.88337887l-.0067277-.11662113c0-.51283584.3860402-.93550716.8833789-.99327227l.1166211-.00672773z"
+            fill="inherit"
+        />
+    </svg>
+)
+
+const DemoIcon16 = (
+    <svg
+        height="16"
+        viewBox="0 0 16 16"
+        width="16"
+        xmlns="http://www.w3.org/2000/svg"
+    >
+        <path
+            d="m6.85355339 9.14644661c.17356635.17356635.1928515.44299075.05785545.63785889l-.05785545.06924789-4.14755339 4.14644661h2.794c.24545989 0 .44960837.1768752.49194433.4101244l.00805567.0898756c0 .2454599-.17687516.4496084-.41012437.4919443l-.08987563.0080557h-4c-.24545989 0-.44960837-.1768752-.49194433-.4101244l-.00805567-.0898756v-4c0-.2761424.22385763-.5.5-.5.24545989 0 .44960837.1768752.49194433.4101244l.00805567.0898756v2.792l4.14644661-4.14555339c.19526215-.19526215.51184463-.19526215.70710678 0zm6.14644661-2.14644661v6h-6v-1h5v-5zm-4-4v1h-5v5h-1v-6zm5.5-2c.2454599 0 .4496084.17687516.4919443.41012437l.0080557.08987563v4c0 .27614237-.2238576.5-.5.5-.2454599 0-.4496084-.17687516-.4919443-.41012437l-.0080557-.08987563v-2.794l-4.14644661 4.14755339c-.19526215.19526215-.51184463.19526215-.70710678 0-.17356635-.17356635-.1928515-.44299075-.05785545-.63785889l.05785545-.06924789 4.14655339-4.14744661-2.793.001c-.2454599 0-.4496084-.17687516-.4919443-.41012437l-.0080557-.08987563c0-.24545989.1768752-.44960837.4101244-.49194433l.0898756-.00805567z"
+            fill="inherit"
+        />
+    </svg>
+)
+
+const Template = (args) => <Button {...args} />
+
+export const Basic = Template.bind({})
+Basic.args = {
+    name: 'Basic button',
+}
+
+export const Primary = Template.bind({})
+Primary.args = {
+    primary: true,
+    name: 'Primary button',
+}
+Primary.parameters = {
+    docs: {
+        description: {
+            story: 'Used to highlight the most important/main action on a page. \
+                A "Save" button for a form page should be primary, for example. \
+                Use sparingly, rarely should there be more than a single primary \
+                button per page.',
+        },
+    },
+}
+
+export const Secondary = Template.bind({})
+Secondary.args = {
+    secondary: true,
+    name: 'Secondary button',
+}
+Secondary.parameters = {
+    docs: {
+        description: {
+            story: 'Used for passive actions, often as an alternative to the primary \
+                action. If "Save" is primary, "Cancel" could be secondary. \
+                Not intended to draw user attention. Do not use for the only \
+                action on a page.',
+        },
+    },
+}
+
+export const Destructive = Template.bind({})
+Destructive.args = {
+    destructive: true,
+    name: 'Destructive button',
+}
+Destructive.parameters = {
+    docs: {
+        description: {
+            story: 'Used instead of a primary button when the main action is \
+                destructive in nature. Used to highlight to the user the \
+                seriousness of the action. \
+                **Destructive buttons must only be used for destructive actions.**',
+        },
+    },
+}
+export const DestructiveSecondary = Template.bind({})
+DestructiveSecondary.args = {
+    destructive: true,
+    secondary: true,
+    name: 'Destructive secondary button',
+}
+
+export const Disabled = (args) => (
+    <>
+        <Button name="Disabled button" {...args} />
+        <Button primary name="Disabled primary button" {...args} />
+        <Button secondary name="Disabled button" {...args} />
+        <Button destructive name="Disabled button" {...args} />
+    </>
+)
+Disabled.args = {
+    disabled: true,
+}
+Disabled.parameters = {
+    docs: {
+        description: {
+            story: "Use disabled buttons when an action is being prevented for some reason. \
+                Always communicate to the user why the button can't be clicked. This can \
+                be done through a tooltip on hover, or with supplementary text underneath \
+                the button. Do not change the button label between disabled/enabled states.",
+        },
+    },
+}
+
+export const Small = Template.bind({})
+Small.args = {
+    small: true,
+    name: 'Small button',
+}
+Small.parameters = {
+    docs: {
+        description: {
+            story: 'Buttons are available in three sizes: `small`, `medium`, and `large`. \
+                Medium is usually the correct choice.  Use small buttons in an information-\
+                dense ui.',
+        },
+    },
+}
+
+export const Large = Template.bind({})
+Large.args = {
+    large: true,
+    name: 'Large button',
+}
+Large.parameters = {
+    docs: {
+        description: {
+            story: 'Buttons are available in three sizes: `small`, `medium`, and `large`. \
+                Medium is usually the correct choice.  Large buttons can be used on very simple, \
+                single-action pages.',
+        },
+    },
+}
+
+export const InitialFocus = Template.bind({})
+InitialFocus.args = {
+    initialFocus: true,
+    name: 'Focused button',
+}
+// When enabled, this story grabs focus every time a control is changed
+// in the docs page. Disabled for better UX
+InitialFocus.parameters = { docs: { disable: true } }
+
+export const Icon = (args) => (
+    <>
+        <Button {...args} />
+        <Button primary {...args} />
+        <Button secondary {...args} />
+        <Button destructive {...args} />
+    </>
+)
+Icon.args = {
+    icon: DemoIcon24,
+    name: 'Icon button',
+}
+Icon.parameters = {
+    docs: {
+        description: {
+            story: 'Icons can be included in Basic, Primary, Secondary and Destructive buttons. \
+                Use an icon to supplement the text label. Remember that the user may not be \
+                fluent in the working language, so an accompanying icon on an important action \
+                can be a welcome addition. Buttons with icons only should be used for \
+                supplementary actions and should include a text tooltip on hover.',
+        },
+    },
+}
+
+export const IconRTL = (args) => (
+    <div dir="rtl">
+        <Button {...args} />
+    </div>
+)
+IconRTL.args = {
+    icon: DemoIcon24,
+    name: 'RTL icon button',
+    children: 'RTL text',
+}
+
+export const IconOnly = Template.bind({})
+IconOnly.args = {
+    icon: DemoIcon24,
+    name: 'Icon only button',
+    children: null,
+    title: 'Icon Button',
+    ariaLabel: 'Icon Button',
+}
+
+export const IconSmall = Template.bind({})
+IconSmall.args = {
+    icon: DemoIcon16,
+    small: true,
+    name: 'Icon small button',
+    children: 'Label me!',
+}
+
+export const IconOnlySmall = Template.bind({})
+IconOnlySmall.args = {
+    icon: DemoIcon16,
+    small: true,
+    name: 'Icon only small button',
+    children: null,
+}
+
+export const Toggled = Template.bind({})
+Toggled.args = {
+    toggled: true,
+    icon: DemoIcon24,
+    name: 'Toggled button',
+    children: null,
+}
+Toggled.parameters = {
+    docs: {
+        description: {
+            story: 'A button can represent an on/off state using the toggle option. \
+                Use a toggle button when the user can enable or disable an option and \
+                a checkbox or switch is not suitable. This will most often be in the case of \
+                a toolbar, such as bold or italic options in a text editing toolbar. \
+                A toggle button in this example uses an icon and does not need text. \
+                A text label should be provided in a tooltip on hover. The toggle option \
+                is available for basic and secondary type buttons.',
+        },
+    },
+}
+
+export const ToggledDisabled = Template.bind({})
+ToggledDisabled.args = {
+    toggled: true,
+    disabled: true,
+    icon: DemoIcon24,
+    name: 'Toggled button',
+    children: null,
+}
+
+export const Loading = (args) => (
+    <>
+        <Button {...args} />
+        <Button primary {...args} />
+        <Button secondary {...args} />
+        <Button destructive {...args} />
+    </>
+)
+Loading.args = {
+    name: 'Loading button',
+    loading: true,
+    children: 'Loading...',
+    icon: DemoIcon24,
+}
+Loading.parameters = {
+    docs: {
+        description: {
+            story: 'A button can be in a loading state. Use the loading state to show a pending action after the button has been triggered. The button text should change to let the user know what is happening. For example, a button labelled "Send" might changed to "Sending..." when in a loading state.',
+        },
+    },
+}