@dhis2-ui/switch 10.16.2 → 10.16.3-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/switch",
-    "version": "10.16.2",
+    "version": "10.16.3-alpha.1",
     "description": "UI Switch",
     "repository": {
         "type": "git",
@@ -33,15 +33,16 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/field": "10.16.2",
-        "@dhis2-ui/required": "10.16.2",
-        "@dhis2/ui-constants": "10.16.2",
+        "@dhis2-ui/field": "10.16.3-alpha.1",
+        "@dhis2-ui/required": "10.16.3-alpha.1",
+        "@dhis2/ui-constants": "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/index.js

@@ -0,0 +1,2 @@
+export { Switch } from './switch/index.js'
+export { SwitchField } from './switch-field/index.js'

package/src/switch/__tests__/switch.test.js

@@ -0,0 +1,44 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { Switch } from '../switch.js'
+
+describe('<Switch />', () => {
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(
+            <Switch
+                name="foo"
+                value="bar"
+                checked={false}
+                onKeyDown={onKeyDown}
+            />
+        )
+
+        fireEvent.keyDown(screen.getByRole('switch'), {
+            key: 'Enter',
+            code: 'Enter',
+            charCode: 13,
+        })
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'foo', value: 'bar', checked: true },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+
+    it('renders the switch with aria label', () => {
+        const ariaLabel = 'test switch'
+        render(
+            <Switch
+                aria-label={ariaLabel}
+                name="foo"
+                value="bar"
+                checked={false}
+            />
+        )
+        expect(screen.getAllByLabelText(ariaLabel)).toHaveLength(1)
+    })
+})

package/src/switch/features/accepts_initial_focus/index.js

@@ -0,0 +1,9 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Switch with initialFocus is rendered', () => {
+    cy.visitStory('Switch', 'With initial focus')
+})
+
+Then('the Switch is focused', () => {
+    cy.focused().parent('[data-test="dhis2-uicore-switch"]').should('exist')
+})

package/src/switch/features/accepts_initial_focus.feature

@@ -0,0 +1,5 @@
+Feature: Focusing the Switch on mount
+
+    Scenario: The Switch renders with focus
+        Given a Switch with initialFocus is rendered
+        Then the Switch is focused

package/src/switch/features/accepts_label/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Switch with a label is rendered', () => {
+    cy.visitStory('Switch', 'With label')
+})
+
+Then('the label is shown', () => {
+    cy.get('[data-test="dhis2-uicore-switch"]')
+        .contains('The label')
+        .should('be.visible')
+})

package/src/switch/features/accepts_label.feature

@@ -0,0 +1,5 @@
+Feature: The Switch shows a label
+
+    Scenario: The Switch has a label
+        Given a Switch with a label is rendered
+        Then the label is shown

package/src/switch/features/can_be_blurred/index.js

@@ -0,0 +1,19 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Switch with initialFocus and onBlur handler is rendered', () => {
+    cy.visitStory('Switch', 'With initial focus and on blur')
+})
+
+When('the Switch is blurred', () => {
+    cy.get('[data-test="dhis2-uicore-switch"] input').blur()
+})
+
+Then('the onBlur handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onBlur).to.be.calledWith({
+            value: 'default',
+            name: 'Ex',
+            checked: true,
+        })
+    })
+})

package/src/switch/features/can_be_blurred.feature

@@ -0,0 +1,6 @@
+Feature: The Switch has an onBlur api
+
+    Scenario: The user blurs the Switch
+        Given a Switch with initialFocus and onBlur handler is rendered
+        When the Switch is blurred
+        Then the onBlur handler is called

package/src/switch/features/can_be_changed/index.js

@@ -0,0 +1,19 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Switch with onChange handler is rendered', () => {
+    cy.visitStory('Switch', 'With on change')
+})
+
+When('the Switch is clicked', () => {
+    cy.get('[data-test="dhis2-uicore-switch"]').click()
+})
+
+Then('the onChange handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onChange).to.be.calledWith({
+            value: 'default',
+            name: 'Ex',
+            checked: true,
+        })
+    })
+})

package/src/switch/features/can_be_changed.feature

@@ -0,0 +1,6 @@
+Feature: The Switch has an onChange api
+
+    Scenario: The user clicks the Switch
+        Given a Switch with onChange handler is rendered
+        When the Switch is clicked
+        Then the onChange handler is called

package/src/switch/features/can_be_disabled/index.js

@@ -0,0 +1,13 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a disabled Switch is rendered', () => {
+    cy.visitStory('Switch', 'With disabled')
+})
+
+When('the user clicks the Switch', () => {
+    cy.get('[data-test="dhis2-uicore-switch"] input').click({ force: true })
+})
+
+Then('the Switch is not focused', () => {
+    cy.focused().should('not.exist')
+})

package/src/switch/features/can_be_disabled.feature

@@ -0,0 +1,6 @@
+Feature: The Switch can be disabled
+
+    Scenario: The user clicks a disabled Switch
+        Given a disabled Switch is rendered
+        When the user clicks the Switch
+        Then the Switch is not focused

package/src/switch/features/can_be_focused/index.js

@@ -0,0 +1,19 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Switch with onFocus handler is rendered', () => {
+    cy.visitStory('Switch', 'With on focus')
+})
+
+When('the Switch is focused', () => {
+    cy.get('[data-test="dhis2-uicore-switch"] input').focus()
+})
+
+Then('the onFocus handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onFocus).to.be.calledWith({
+            value: 'default',
+            name: 'Ex',
+            checked: true,
+        })
+    })
+})

package/src/switch/features/can_be_focused.feature

@@ -0,0 +1,6 @@
+Feature: The Switch has an onFocus api
+
+    Scenario: The user focuses the Switch
+        Given a Switch with onFocus handler is rendered
+        When the Switch is focused
+        Then the onFocus handler is called

package/src/switch/index.js

@@ -0,0 +1 @@
+export { Switch } from './switch.js'

package/src/switch/switch-icons.js

@@ -0,0 +1,144 @@
+import { colors } from '@dhis2/ui-constants'
+import PropTypes from 'prop-types'
+import React from 'react'
+import css from 'styled-jsx/css'
+
+const styles = css`
+    svg {
+        display: block;
+        pointer-events: none;
+        height: 18px;
+        width: 35px;
+    }
+
+    svg:dir(rtl) {
+        transform: scale(-1, 1);
+    }
+
+    svg[dir='rtl'] {
+        transform: scale(-1, 1);
+    }
+
+    svg.dense {
+        height: 14px;
+        width: 27px;
+    }
+
+    svg .background,
+    svg .border {
+        fill: ${colors.grey600};
+    }
+
+    svg .checkmark,
+    svg .cross,
+    svg .handle {
+        fill: ${colors.white};
+    }
+
+    svg .checkmark:dir(rtl) {
+        display: none;
+    }
+
+    svg[dir='rtl'] .checkmark {
+        display: none;
+    }
+
+    svg.checked .handle-unchecked,
+    svg:not(.checked) .handle-checked {
+        fill: none;
+    }
+
+    svg.checked .background {
+        fill: ${colors.teal400};
+    }
+    svg.valid .background {
+        fill: ${colors.blue600};
+    }
+    svg.warning .background {
+        fill: ${colors.yellow700};
+    }
+    svg.error .background {
+        fill: ${colors.red500};
+    }
+
+    svg.checked .border {
+        fill: ${colors.teal700};
+    }
+
+    svg.disabled .background {
+        fill: ${colors.grey300};
+    }
+    svg.disabled .border {
+        fill: ${colors.grey400};
+    }
+
+    svg.valid .border {
+        fill: ${colors.blue600};
+    }
+    svg.valid.checked .border,
+    svg.valid.indeterminate .border {
+        fill: ${colors.blue700};
+    }
+
+    svg.warning .border {
+        fill: ${colors.yellow700};
+    }
+    svg.warning.checked .border {
+        fill: ${colors.yellow800};
+    }
+
+    svg.error .border {
+        fill: ${colors.red500};
+    }
+    svg.error.checked .border {
+        fill: ${colors.red700};
+    }
+`
+
+export function SwitchRegular({ className }) {
+    return (
+        <svg
+            viewBox="0 0 42 22"
+            xmlns="http://www.w3.org/2000/svg"
+            className={className}
+            dir={document.documentElement?.dir ?? 'ltr'}
+        >
+            <path
+                d="M0,11 L0,11 C0,4.92486775 4.92076837,0 11.0075657,0 L30.9924343,0 C37.071745,0 42,4.923532 42,11 L42,11 C42,17.0751322 37.0792316,22 30.9924343,22 L11.0075657,22 C4.92825504,22 0,17.0791222 0,11 L0,11 Z"
+                className="background"
+                fill="red"
+            ></path>
+            <path
+                d="M30.9924343,0 C36.975248,0 41.8432574,4.76846989 41.99629,10.7115309 L42,11 C42,17.0751322 37.0792316,22 30.9924343,22 L11.0075657,22 C5.02475203,22 0.156742552,17.2341007 0.00370995454,11.2885915 L0,11 C0,4.92486775 4.92076837,0 11.0075657,0 L30.9924343,0 Z M30.9924343,1 L11.0075657,1 C5.47559009,1 0.99991738,5.47461611 0.99991738,10.9871457 L1.00337887,11.2628608 C1.14271146,16.6761076 5.5768313,21 11.0075657,21 L30.9924343,21 C36.5244099,21 41.0000827,16.5253839 41.0000827,11.0128598 L40.9966214,10.7372722 C40.8572703,5.32553352 36.4222391,1 30.9924343,1 Z"
+                className="border"
+                // fill="#00695C"
+                // fillRule="nonzero"
+            ></path>
+            <path
+                d="M27.7071068,7.29289322 L30,9.585 L32.2928932,7.29289322 C32.6533772,6.93240926 33.2206082,6.90467972 33.6128994,7.20970461 L33.7071068,7.29289322 C34.0976311,7.68341751 34.0976311,8.31658249 33.7071068,8.70710678 L33.7071068,8.70710678 L31.415,11 L33.7071068,13.2928932 C34.0976311,13.6834175 34.0976311,14.3165825 33.7071068,14.7071068 C33.3165825,15.0976311 32.6834175,15.0976311 32.2928932,14.7071068 L30,12.415 L27.7071068,14.7071068 C27.3466228,15.0675907 26.7793918,15.0953203 26.3871006,14.7902954 L26.2928932,14.7071068 C25.9023689,14.3165825 25.9023689,13.6834175 26.2928932,13.2928932 L26.2928932,13.2928932 L28.585,11 L26.2928932,8.70710678 C25.9023689,8.31658249 25.9023689,7.68341751 26.2928932,7.29289322 C26.6834175,6.90236893 27.3165825,6.90236893 27.7071068,7.29289322 Z"
+                className="cross"
+                fill="#FFFFFF"
+            ></path>
+            <path
+                d="M7.74451387,10.0285252 C7.39595738,10.1198564 7.12375034,10.3923519 7.03251575,10.7412777 C6.94128115,11.0902035 7.04521722,11.4612586 7.30437605,11.7118278 L10.2982384,14.7078028 C10.6875399,15.0973991 11.3185977,15.0973991 11.7078992,14.7078028 L16.695624,8.71585285 C16.9547828,8.46528367 17.0587189,8.09422851 16.9674843,7.74530271 C16.8762497,7.39637691 16.6040426,7.12388146 16.2554861,7.0325502 C15.9069296,6.94121893 15.5362672,7.04526513 15.2859632,7.30469855 L11.0030688,12.5910713 L8.71403676,10.3006735 C8.46373279,10.0412401 8.09307036,9.9371939 7.74451387,10.0285252 Z"
+                className="checkmark"
+                // fill="#FFFFFF"
+                // fillRule="nonzero"
+            ></path>
+            <path
+                d="M11,20 C15.9705627,20 20,15.9705627 20,11 C20,6.02943725 15.9705627,2 11,2 C6.02943725,2 2,6.02943725 2,11 C2,15.9705627 6.02943725,20 11,20 Z"
+                className="handle handle-unchecked"
+                // fill="#FFFFFF"
+            ></path>
+            <path
+                d="M31,20 C35.9705627,20 40,15.9705627 40,11 C40,6.02943725 35.9705627,2 31,2 C26.0294373,2 22,6.02943725 22,11 C22,15.9705627 26.0294373,20 31,20 Z"
+                className="handle handle-checked"
+                // fill="#FFFFFF"
+            ></path>
+            <style jsx>{styles}</style>
+        </svg>
+    )
+}
+SwitchRegular.propTypes = {
+    className: PropTypes.string,
+}

package/src/switch/switch.e2e.stories.js

@@ -0,0 +1,37 @@
+import React from 'react'
+import { Switch } from './index.js'
+
+window.onChange = 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: 'Switch' }
+export const WithOnChange = () => (
+    <Switch
+        name="Ex"
+        label="Switch"
+        value="default"
+        onChange={window.onChange}
+    />
+)
+export const WithInitialFocusAndOnBlur = () => (
+    <Switch
+        initialFocus
+        name="Ex"
+        label="Switch"
+        value="default"
+        onBlur={window.onBlur}
+    />
+)
+export const WithOnFocus = () => (
+    <Switch name="Ex" label="Switch" value="default" onFocus={window.onFocus} />
+)
+export const WithDisabled = () => (
+    <Switch name="Ex" label="Switch" value="default" disabled />
+)
+export const WithLabel = () => (
+    <Switch name="Ex" label="The label" value="default" />
+)
+export const WithInitialFocus = () => (
+    <Switch name="Ex" label="The label" value="default" initialFocus />
+)

package/src/switch/switch.js

@@ -0,0 +1,210 @@
+import { colors, theme, sharedPropTypes } from '@dhis2/ui-constants'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { Component, createRef } from 'react'
+import { SwitchRegular } from './switch-icons.js'
+
+class Switch extends Component {
+    ref = createRef()
+
+    componentDidMount() {
+        if (this.props.initialFocus) {
+            this.ref.current.focus()
+        }
+    }
+
+    handleChange = (e) => {
+        if (this.props.onChange) {
+            this.props.onChange(this.createHandlerPayload(), e)
+        }
+    }
+
+    handleBlur = (e) => {
+        if (this.props.onBlur) {
+            this.props.onBlur(this.createHandlerPayload(), e)
+        }
+    }
+
+    handleFocus = (e) => {
+        if (this.props.onFocus) {
+            this.props.onFocus(this.createHandlerPayload(), e)
+        }
+    }
+
+    handleKeyDown = (e) => {
+        if (this.props.onKeyDown) {
+            this.props.onKeyDown(this.createHandlerPayload(), e)
+        }
+    }
+
+    createHandlerPayload() {
+        return {
+            value: this.props.value,
+            name: this.props.name,
+            checked: !this.props.checked,
+        }
+    }
+
+    static defaultProps = {
+        checked: false,
+        dataTest: 'dhis2-uicore-switch',
+        role: 'switch',
+    }
+
+    render() {
+        const {
+            'aria-label': ariaLabel,
+            checked = false,
+            className,
+            disabled,
+            error,
+            label,
+            name,
+            tabIndex,
+            valid,
+            value,
+            warning,
+            dense,
+            dataTest = 'dhis2-uicore-switch',
+            role = 'switch',
+        } = this.props
+
+        const classes = cx({
+            checked,
+            disabled,
+            valid,
+            error,
+            warning,
+            dense,
+        })
+
+        return (
+            <label
+                className={cx(className, {
+                    disabled,
+                    dense,
+                })}
+                data-test={dataTest}
+            >
+                <input
+                    aria-label={ariaLabel}
+                    type="checkbox"
+                    role={role}
+                    ref={this.ref}
+                    name={name}
+                    value={value}
+                    checked={checked}
+                    disabled={disabled}
+                    tabIndex={tabIndex}
+                    onChange={this.handleChange}
+                    onFocus={this.handleFocus}
+                    onKeyDown={this.handleKeyDown}
+                    onBlur={this.handleBlur}
+                />
+
+                <div className={cx('icon', { dense })}>
+                    <SwitchRegular className={classes} />
+                </div>
+
+                {label}
+
+                <style jsx>{`
+                    label {
+                        display: flex;
+                        flex-direction: row;
+                        align-items: center;
+                        justify-content: flex-start;
+                        color: ${colors.grey900};
+                        font-size: 14px;
+                        line-height: 19px;
+                    }
+
+                    label.dense {
+                        font-size: 14px;
+                        line-height: 16px;
+                    }
+
+                    label.disabled {
+                        cursor: not-allowed;
+                        color: ${theme.disabled};
+                    }
+
+                    input {
+                        opacity: 0;
+                        position: absolute;
+
+                        /* The same size as the icon */
+                        height: 18px;
+                        width: 35px;
+
+                        /* The same offset as the icon, 2px border, 1px padding */
+                        margin-left: 3px;
+                    }
+
+                    label.dense input {
+                        /* The same size as the dense icon */
+                        height: 14px;
+                        width: 27px;
+                    }
+
+                    .icon {
+                        user-select: none;
+                        margin-right: 5px;
+                        border: 2px solid transparent;
+                        padding: 1px;
+                        border-radius: 14px;
+                    }
+
+                    label.dense .icon {
+                        margin-right: 3px;
+                        border-radius: 12px;
+                    }
+
+                    input:focus + .icon {
+                        outline: 3px solid ${theme.focus};
+                        outline-offset: -3px;
+                    }
+                `}</style>
+            </label>
+        )
+    }
+}
+
+Switch.propTypes = {
+    /** Sets an aria-label attribute on the input */
+    'aria-label': PropTypes.string,
+    checked: PropTypes.bool,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Makes the switch smaller for information-dense layouts */
+    dense: PropTypes.bool,
+    /** Disables the switch */
+    disabled: PropTypes.bool,
+    /** Applies 'error' styles for validation feedback. Mutually exclusive with `valid` and `warning` prop types */
+    error: sharedPropTypes.statusPropType,
+    /** Grab initial focus on the page */
+    initialFocus: PropTypes.bool,
+    /** Label for the switch. Can be a string or an element, for example an image */
+    label: PropTypes.node,
+    /** Name associated with the switch. Passed to event handlers in object */
+    name: PropTypes.string,
+    /** Sets a role attribute on the input */
+    role: PropTypes.string,
+    tabIndex: PropTypes.string,
+    /** Applies 'valid' styles for validation feedback. Mutually exclusive with `error` and `warning` prop types */
+    valid: sharedPropTypes.statusPropType,
+    /** Value associated with the switch. Passed to event handlers in object */
+    value: PropTypes.string,
+    /** Applies 'warning' styles for validation feedback. Mutually exclusive with `valid` and `error` prop types */
+    warning: sharedPropTypes.statusPropType,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onBlur: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onChange: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onFocus: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onKeyDown: PropTypes.func,
+}
+
+export { Switch }

package/src/switch/switch.prod.stories.js

@@ -0,0 +1,157 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React, { useEffect } from 'react'
+import { Switch } from './index.js'
+
+const subtitle = 'An input control that allows an on and an off state'
+
+const description = `
+**Switches are used sparingly in DHIS2, as they are not yet an accepted input control on the web. Users are not always used to the concept of a switch, but understanding is growing with wide adoption on mobile platforms.**
+
+Use switches only when the user can toggle between on/off. Never use a switch for yes/no or any other states, use a checkbox instead. It is often safer to use a checkbox for things like turning options on/off, as users understand this pattern. Switches can be useful for ongoing or active processes, where turning them on/off makes more sense conceptually. An example of this may be toggling on/off 'Logging' or 'Update automatically', both processes that are ongoing.
+
+\`\`\`js
+import { Switch } from '@dhis2/ui'
+\`\`\`
+`
+
+window.onChange = (payload, event) => {
+    console.log('onClick payload', payload)
+    console.log('onClick event', event)
+}
+
+window.onFocus = (payload, event) => {
+    console.log('onFocus payload', payload)
+    console.log('onFocus event', event)
+}
+
+window.onBlur = (payload, event) => {
+    console.log('onBlur payload', payload)
+    console.log('onBlur event', event)
+}
+
+const onChange = (...args) => window.onChange(...args)
+const onFocus = (...args) => window.onFocus(...args)
+const onBlur = (...args) => window.onBlur(...args)
+
+export default {
+    title: 'Switch',
+    component: Switch,
+    parameters: {
+        componentSubtitle: subtitle,
+        docs: { description: { component: description } },
+    },
+    // Default args for all stories
+    args: {
+        name: 'exampleName',
+        label: 'Switch',
+        value: 'defaultValue',
+        onChange,
+        onFocus,
+        onBlur,
+    },
+    argTypes: {
+        valid: { ...sharedPropTypes.statusArgType },
+        error: { ...sharedPropTypes.statusArgType },
+        warning: { ...sharedPropTypes.statusArgType },
+    },
+}
+
+const Template = (args) => <Switch {...args} />
+
+const CheckedUncheckedTemplate = (args) => (
+    <>
+        <Switch {...args} />
+        <Switch {...args} checked />
+    </>
+)
+
+export const Default = Template.bind({})
+
+export const FocusedUnchecked = (args) => (
+    <>
+        <Switch {...args} initialFocus className="initially-focused" />
+        <Switch {...args} className="initially-unfocused" />
+    </>
+)
+// Stories with initial focus are distracting on docs page
+FocusedUnchecked.parameters = { docs: { disable: true } }
+
+export const FocusedChecked = FocusedUnchecked.bind({})
+FocusedChecked.args = { checked: true }
+FocusedChecked.parameters = { docs: { disable: true } }
+
+export const Checked = Template.bind({})
+Checked.args = { checked: true, value: 'checked' }
+
+export const Disabled = CheckedUncheckedTemplate.bind({})
+Disabled.args = { disabled: true, value: 'disabled' }
+
+export const Valid = CheckedUncheckedTemplate.bind({})
+Valid.args = { valid: true, value: 'valid' }
+
+export const Warning = CheckedUncheckedTemplate.bind({})
+Warning.args = { warning: true, value: 'warning' }
+
+export const Error = CheckedUncheckedTemplate.bind({})
+Error.args = { error: true, value: 'error' }
+
+export const ImageLabel = Template.bind({})
+ImageLabel.args = {
+    label: <img src="https://picsum.photos/id/82/200/100" />,
+    value: 'with-help',
+}
+
+export const DefaultDense = Template.bind({})
+DefaultDense.args = { dense: true }
+DefaultDense.storyName = 'Default - Dense'
+
+export const FocusedUncheckedDense = FocusedUnchecked.bind({})
+FocusedUncheckedDense.args = { ...DefaultDense.args }
+FocusedUncheckedDense.storyName = 'Focused unchecked - Dense'
+FocusedUncheckedDense.parameters = { docs: { disable: true } }
+
+export const FocusedCheckedDense = FocusedUnchecked.bind({})
+FocusedCheckedDense.args = { ...DefaultDense.args, checked: true }
+FocusedCheckedDense.storyName = 'Focused checked - Dense'
+FocusedCheckedDense.parameters = { docs: { disable: true } }
+
+export const CheckedDense = Template.bind({})
+CheckedDense.args = { ...Checked.args, ...DefaultDense.args }
+CheckedDense.storyName = 'Checked - Dense'
+
+export const DisabledDense = CheckedUncheckedTemplate.bind({})
+DisabledDense.args = { ...Disabled.args, ...DefaultDense.args }
+DisabledDense.storyName = 'Disabled - Dense'
+
+export const ValidDense = CheckedUncheckedTemplate.bind({})
+ValidDense.args = { ...Valid.args, ...DefaultDense.args }
+ValidDense.storyName = 'Valid - Dense'
+
+export const WarningDense = CheckedUncheckedTemplate.bind({})
+WarningDense.args = { ...Warning.args, ...DefaultDense.args }
+WarningDense.storyName = 'Warning - Dense'
+
+export const ErrorDense = CheckedUncheckedTemplate.bind({})
+ErrorDense.args = { ...Error.args, ...DefaultDense.args }
+ErrorDense.storyName = 'Error - Dense'
+
+export const ImageLabelDense = Template.bind({})
+ImageLabelDense.args = { ...ImageLabel.args, ...DefaultDense.args }
+ImageLabelDense.storyName = 'Image label - Dense'
+
+export const RTL = (args) => {
+    useEffect(() => {
+        document.documentElement.setAttribute('dir', 'rtl')
+        return () => {
+            document.documentElement.setAttribute('dir', 'ltr')
+        }
+    }, [])
+
+    return (
+        <div dir="rtl">
+            <Template {...args} />
+            <Template checked={true} value="checked" />
+            <Template error={true} checked={true} value="error" />
+        </div>
+    )
+}

package/src/switch-field/__tests__/switch-field.test.js

@@ -0,0 +1,32 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { SwitchField } from '../switch-field.js'
+
+describe('<Switch />', () => {
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(
+            <SwitchField
+                label="label"
+                name="foo"
+                value="bar"
+                checked={false}
+                onKeyDown={onKeyDown}
+            />
+        )
+
+        fireEvent.keyDown(screen.getByRole('switch'), {
+            key: 'Enter',
+            code: 'Enter',
+            charCode: 13,
+        })
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'foo', value: 'bar', checked: true },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+})

package/src/switch-field/features/can_be_required/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a SwitchField with label and a required flag is rendered', () => {
+    cy.visitStory('SwitchField', 'With label and required')
+})
+
+Then('the required indicator is visible', () => {
+    cy.get('[data-test="dhis2-uiwidgets-switchfield-required"]').should(
+        'be.visible'
+    )
+})

package/src/switch-field/features/can_be_required.feature

@@ -0,0 +1,5 @@
+Feature: Required status for the SwitchField
+
+    Scenario: Rendering a SwitchField that is required
+        Given a SwitchField with label and a required flag is rendered
+        Then the required indicator is visible

package/src/switch-field/index.js

@@ -0,0 +1 @@
+export { SwitchField } from './switch-field.js'

package/src/switch-field/switch-field.e2e.stories.js

@@ -0,0 +1,7 @@
+import React from 'react'
+import { SwitchField } from './index.js'
+
+export default { title: 'SwitchField' }
+export const WithLabelAndRequired = () => (
+    <SwitchField name="Ex" label="SwitchField" required value="checked" />
+)

package/src/switch-field/switch-field.js

@@ -0,0 +1,118 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import { Field } from '@dhis2-ui/field'
+import { Required } from '@dhis2-ui/required'
+import PropTypes from 'prop-types'
+import React from 'react'
+import { Switch } from '../switch/index.js'
+
+const AddRequired = ({ label, required, dataTest }) => (
+    <React.Fragment>
+        {label}
+        {required && <Required dataTest={`${dataTest}-required`} />}
+    </React.Fragment>
+)
+AddRequired.propTypes = {
+    dataTest: PropTypes.string,
+    label: PropTypes.node,
+    required: PropTypes.bool,
+}
+
+const SwitchField = ({
+    value,
+    label,
+    name,
+    className,
+    tabIndex,
+    onChange,
+    onFocus,
+    onKeyDown,
+    onBlur,
+    checked,
+    disabled,
+    valid,
+    warning,
+    error,
+    dense,
+    initialFocus,
+    required,
+    helpText,
+    validationText,
+    dataTest = 'dhis2-uiwidgets-switchfield',
+}) => (
+    <Field
+        className={className}
+        dataTest={dataTest}
+        helpText={helpText}
+        validationText={validationText}
+        error={error}
+        warning={warning}
+        valid={valid}
+        required={required}
+        name={name}
+        disabled={disabled}
+    >
+        <Switch
+            value={value}
+            label={
+                <AddRequired
+                    label={label}
+                    required={required}
+                    dataTest={dataTest}
+                />
+            }
+            name={name}
+            tabIndex={tabIndex}
+            onChange={onChange}
+            onFocus={onFocus}
+            onKeyDown={onKeyDown}
+            onBlur={onBlur}
+            checked={checked}
+            disabled={disabled}
+            valid={valid}
+            warning={warning}
+            error={error}
+            dense={dense}
+            initialFocus={initialFocus}
+        />
+    </Field>
+)
+
+SwitchField.propTypes = {
+    checked: PropTypes.bool,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Smaller dimensions for information-dense layouts */
+    dense: PropTypes.bool,
+    /** Disables the switch */
+    disabled: PropTypes.bool,
+    /** Applies 'error' styling to switch and validation text for feedback. Mutually exclusive with `warning` and `valid` props */
+    error: sharedPropTypes.statusPropType,
+    /** Useful instructions for the user */
+    helpText: PropTypes.string,
+    initialFocus: PropTypes.bool,
+    /** Labels the switch */
+    label: PropTypes.node,
+    /** Name associate with the switch. Passed in object as argument to event handlers */
+    name: PropTypes.string,
+    /** Adds an asterisk to indicate this field is required */
+    required: PropTypes.bool,
+    tabIndex: PropTypes.string,
+    /** Applies 'valid' styling to switch and validation text for feedback. Mutually exclusive with `warning` and `error` props */
+    valid: sharedPropTypes.statusPropType,
+    /** Adds text below the switch to provide validation feedback. Acquires styles from `valid`, `warning` and `error` statuses */
+    validationText: PropTypes.string,
+    /** Value associated with the switch. Passed in object as argument to event handlers */
+    value: PropTypes.string,
+    /** Applies 'warning' styling to switch and validation text for feedback. Mutually exclusive with `valid` and `error` props */
+    warning: sharedPropTypes.statusPropType,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onBlur: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onChange: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onFocus: PropTypes.func,
+    /** Called with signature `({ name: string, value: string, checked: bool }, event)` */
+    onKeyDown: PropTypes.func,
+}
+
+export { SwitchField }

package/src/switch-field/switch-field.prod.stories.js

@@ -0,0 +1,141 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React from 'react'
+import { SwitchField } from './index.js'
+
+const description = `
+A \`SwitchField\` is a Switch component wrapped with extra form utilities, including the ability to add a label, help text, and validation text.  Validation styles like 'error' apply to all of these subcomponents.
+
+See the basic Switch for usage and design system guidelines.
+
+\`\`\`js
+import { SwitchField } from '@dhis2/ui'
+\`\`\`
+`
+
+const logger = ({ name, value, checked }) =>
+    console.log(`name: ${name}, value: ${value}, checked: ${checked}`)
+
+export default {
+    title: 'Switch Field',
+    component: SwitchField,
+    parameters: { docs: { description: { component: description } } },
+    // Default args for stories
+    args: {
+        name: 'switchName',
+        label: 'Switch Field',
+        value: 'defaultValue',
+        onChange: logger,
+    },
+    argTypes: {
+        valid: { ...sharedPropTypes.statusArgType },
+        warning: { ...sharedPropTypes.statusArgType },
+        error: { ...sharedPropTypes.statusArgType },
+    },
+}
+
+const Template = (args) => <SwitchField {...args} />
+
+const CheckedUncheckedTemplate = (args) => (
+    <>
+        <SwitchField {...args} />
+        <SwitchField {...args} checked />
+    </>
+)
+
+export const Default = Template.bind({})
+
+export const FocusedUnchecked = Template.bind({})
+FocusedUnchecked.args = { initialFocus: true }
+// Disable stories on docs page that grab focus
+FocusedUnchecked.parameters = { docs: { disable: true } }
+
+export const FocusedChecked = Template.bind({})
+FocusedChecked.args = { ...FocusedUnchecked.args, checked: true }
+FocusedChecked.parameters = { docs: { disable: true } }
+
+export const Checked = Template.bind({})
+Checked.args = { checked: true, value: 'checkedValue' }
+
+export const Required = Template.bind({})
+Required.args = { required: true }
+
+export const Disabled = CheckedUncheckedTemplate.bind({})
+Disabled.args = { disabled: true }
+
+export const HelpText = (args) => (
+    <>
+        <SwitchField {...args} />
+        <SwitchField
+            {...args}
+            error
+            validationText="Validation text (error state)"
+        />
+    </>
+)
+HelpText.args = { helpText: 'Help text' }
+
+export const Valid = CheckedUncheckedTemplate.bind({})
+Valid.args = {
+    valid: true,
+    validationText: 'I am validation text',
+    value: 'validValue',
+}
+
+export const Warning = CheckedUncheckedTemplate.bind({})
+Warning.args = {
+    warning: true,
+    value: 'warningValue',
+    validationText: 'I am validation text',
+}
+
+export const Error = CheckedUncheckedTemplate.bind({})
+Error.args = {
+    error: true,
+    value: 'errorValue',
+    validationText: 'I am validation text',
+}
+
+export const ImageLabel = Template.bind({})
+ImageLabel.args = { label: <img src="https://picsum.photos/id/82/200/100" /> }
+
+export const DefaultDense = Template.bind({})
+DefaultDense.storyName = 'Default - Dense'
+DefaultDense.args = { dense: true }
+
+export const FocusedUncheckedDense = Template.bind({})
+FocusedUncheckedDense.args = { ...DefaultDense.args, ...FocusedUnchecked.args }
+FocusedUncheckedDense.parameters = { docs: { disable: true } }
+FocusedUncheckedDense.storyName = 'Focused unchecked - Dense'
+
+export const FocusedCheckedDense = Template.bind({})
+FocusedCheckedDense.args = { ...DefaultDense.args, ...FocusedChecked.args }
+FocusedCheckedDense.parameters = { docs: { disable: true } }
+FocusedCheckedDense.storyName = 'Focused checked - Dense'
+
+export const CheckedDense = Template.bind({})
+CheckedDense.args = { ...DefaultDense.args, ...Checked.args }
+CheckedDense.storyName = 'Checked - Dense'
+
+export const RequiredDense = Template.bind({})
+RequiredDense.args = { ...DefaultDense.args, ...Required.args }
+RequiredDense.storyName = 'Required - Dense'
+
+export const DisabledDense = CheckedUncheckedTemplate.bind({})
+DisabledDense.args = { ...DefaultDense.args, ...Disabled.args }
+DisabledDense.storyName = 'Disabled - Dense'
+
+export const ValidDense = CheckedUncheckedTemplate.bind({})
+ValidDense.args = { ...DefaultDense.args, ...Valid.args }
+ValidDense.storyName = 'Valid - Dense'
+
+export const WarningDense = CheckedUncheckedTemplate.bind({})
+WarningDense.args = { ...DefaultDense.args, ...Warning.args }
+WarningDense.storyName = 'Warning - Dense'
+
+export const ErrorDense = CheckedUncheckedTemplate.bind({})
+ErrorDense.args = { ...DefaultDense.args, ...Error.args }
+ErrorDense.storyName = 'Error - Dense'
+
+export const ImageLabelDense = Template.bind({})
+ImageLabelDense.args = { ...DefaultDense.args, ...ImageLabel.args }
+ImageLabelDense.storyName = 'Image label - Dense'