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

package/src/SimpleSingleSelectFieldFF/SimpleSingleSelectFieldFF.js

@@ -0,0 +1,172 @@
+import { requiredIf } from '@dhis2/prop-types'
+import { SimpleSingleSelectField } from '@dhis2-ui/select'
+import PropTypes from 'prop-types'
+import React from 'react'
+import {
+    createFocusHandler,
+    createBlurHandler,
+    hasError,
+    isLoading,
+    isValid,
+    getValidationText,
+} from '../shared/helpers.js'
+import { inputPropType, metaPropType } from '../shared/propTypes.js'
+
+export const SimpleSingleSelectFieldFF = ({
+    error,
+    input,
+    loading,
+    meta,
+    showLoadingStatus,
+    showValidStatus,
+    valid,
+    validationText,
+    onBlur,
+    onFocus,
+    ...rest
+}) => {
+    return (
+        <SimpleSingleSelectField
+            {...rest}
+            name={input.name}
+            error={hasError(meta, error)}
+            valid={isValid(meta, valid, showValidStatus)}
+            loading={isLoading(meta, loading, showLoadingStatus)}
+            validationText={getValidationText(meta, validationText, error)}
+            onFocus={createFocusHandler(input, onFocus)}
+            onChange={(value) => input.onChange(value)}
+            onBlur={createBlurHandler(input, onBlur)}
+            value={input.value || ''}
+        />
+    )
+}
+
+SimpleSingleSelectFieldFF.propTypes = {
+    /** `input` props received from Final Form `Field` */
+    input: inputPropType.isRequired,
+
+    /** Label displayed above the input **/
+    label: PropTypes.string.isRequired,
+
+    /** `meta` props received from Final Form `Field` */
+    meta: metaPropType.isRequired,
+
+    options: PropTypes.arrayOf(
+        PropTypes.shape({
+            label: PropTypes.string.isRequired,
+            value: PropTypes.string.isRequired,
+        })
+    ).isRequired,
+
+    /** Will focus the select initially **/
+    autoFocus: PropTypes.bool,
+
+    /** Additional class names that will be applied to the root element **/
+    className: PropTypes.string,
+
+    /** This will allow us to put an aria-label on the clear button **/
+    clearText: requiredIf((props) => props.clearable, PropTypes.string),
+
+    /** Whether a clear button should be displayed or not **/
+    clearable: PropTypes.bool,
+
+    /** A value for a `data-test` attribute on the root element **/
+    dataTest: PropTypes.string,
+
+    /** Renders a select with lower height **/
+    dense: PropTypes.bool,
+
+    /** Disables all interactions with the select (except focussing) **/
+    disabled: PropTypes.bool,
+
+    /** Text or component to display when there are no options **/
+    empty: PropTypes.node,
+
+    /** Applies 'error' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props **/
+    error: PropTypes.bool,
+
+    /** Help text that will be displayed below the input **/
+    filterHelpText: PropTypes.string,
+
+    /** Value will be used as aria-label attribute on the filter input **/
+    filterLabel: PropTypes.string,
+
+    /** Placeholder for the filter input **/
+    filterPlaceholder: PropTypes.string,
+
+    /** Value of the filter input **/
+    filterValue: PropTypes.string,
+
+    /** Whether the select should display a filter input **/
+    filterable: PropTypes.bool,
+
+    /** Help text, displayed below the input **/
+    helpText: PropTypes.string,
+
+    /** Will show a loading indicator at the end of the options-list **/
+    loading: PropTypes.bool,
+
+    /** Text that will be displayed next to the loading indicator **/
+    menuLoadingText: PropTypes.string,
+
+    /** Allows to modify the max height of the menu **/
+    menuMaxHeight: PropTypes.string,
+
+    /** String that will be displayed when the select is being filtered but the options array is empty **/
+    noMatchText: requiredIf((props) => props.filterable, PropTypes.string),
+
+    /** Allows to override what's rendered inside the `button[role="option"]`.
+     * Can be overriden on an individual option basis **/
+    optionComponent: PropTypes.elementType,
+
+    /** For a11y: How aggressively the user should be updated about changes in options **/
+    optionUpdateStrategy: PropTypes.oneOf(['off', 'polite', 'assertive']),
+
+    /** String to show when there's no value and no valueLabel **/
+    placeholder: PropTypes.string,
+
+    /** String that will be displayed before the label of the selected option **/
+    prefix: PropTypes.string,
+
+    /** Whether a value is required or not **/
+    required: PropTypes.bool,
+
+    showLoadingStatus: PropTypes.bool,
+
+    showValidStatus: PropTypes.bool,
+
+    /** Standard HTML tab-index attribute that will be put on the combobox's root element **/
+    tabIndex: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+
+    valid: PropTypes.bool,
+
+    validationText: PropTypes.string,
+
+    /**
+     * When the option is not in the options list (e.g. not loaded or list is
+     * filtered), but a selected value needs to be displayed, then this prop can
+     * be used to supply the text to be shown.
+     **/
+    valueLabel: requiredIf((props) => {
+        if (props.options.find(({ value }) => props.value === value)) {
+            return false
+        }
+
+        return props.value
+    }, PropTypes.string),
+
+    /** Applies 'warning' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props **/
+    warning: PropTypes.bool,
+
+    /** Will be called when the combobox is loses focus **/
+    onBlur: PropTypes.func,
+
+    /** Will be called when the last option is scrolled into the visible area **/
+    onEndReached: PropTypes.func,
+
+    /** Will be called when the filter value changes **/
+    onFilterChange: PropTypes.func,
+
+    /** Will be called when the combobox is being focused **/
+    onFocus: PropTypes.func,
+}

package/src/SimpleSingleSelectFieldFF/SimpleSingleSelectFieldFF.prod.stories.js

@@ -0,0 +1,79 @@
+import React from 'react'
+import { Field } from 'react-final-form'
+import { formDecorator } from '../formDecorator.js'
+import { inputArgType, metaArgType } from '../shared/propTypes.js'
+import { hasValue } from '../validators/index.js'
+import { SimpleSingleSelectFieldFF } from './SimpleSingleSelectFieldFF.js'
+
+const description = `
+The \`SimpleSingleSelectFieldFF\` is a wrapper around a \`SimpleSingleSelectField\` that enables it to work with Final Form, the preferred library for form validation and utilities in DHIS 2 apps.
+
+#### Final Form
+
+See how to use Final Form at [Final Form - Getting Started](https://final-form.org/docs/react-final-form/getting-started).
+
+Inside a Final Form \`<Form>\` component, these 'FF' UI components are intended to be used in the \`component\` prop of the [Final Form \`<Field>\` components](https://final-form.org/docs/react-final-form/api/Field) where they will receive some props from the Field, e.g. \`<Field component={SimpleSingleSelectFieldFF} />\`.  See the code samples below for examples.
+
+#### Props
+
+The props shown in the table below are generally provided to the \`SimpleSingleSelectFieldFF\` wrapper by the Final Form \`Field\`.
+
+Note that any props beyond the API of the \`Field\` component will be spread to the \`SimpleSingleSelectFieldFF\`, which passes any extra props to the underlying \`SimpleSingleSelectField\` using \`{...rest}\`.
+
+Therefore, to add any props to the \`SimpleSingleSelectFieldFF\` or \`SimpleSingleSelectField\`, add those props to the parent Final Form \`Field\` component.
+
+Also see \`SingleSelect\` and \`SimpleSingleSelectField\` for notes about props and implementation.
+
+\`\`\`js
+import { SimpleSingleSelectFieldFF } from '@dhis2/ui'
+\`\`\`
+
+Press **Submit** to see the form values logged to the console.
+
+_**Note:** Dropdowns may not appear correctly on this page. See the affected demos in the 'Canvas' tab for propper dropdown placement._
+`
+
+const options = [
+    { value: '1', label: 'one' },
+    { value: '2', label: 'two' },
+    { value: '3', label: 'three' },
+    { value: '4', label: 'four' },
+    { value: '5', label: 'five' },
+    { value: '6', label: 'six' },
+    { value: '7', label: 'seven' },
+    { value: '8', label: 'eight' },
+    { value: '9', label: 'nine' },
+    { value: '10', label: 'ten' },
+]
+
+export default {
+    title: 'SimpleSingleSelectField (Final Form)',
+    component: SimpleSingleSelectFieldFF,
+    decorators: [formDecorator],
+    parameters: { docs: { description: { component: description } } },
+    argTypes: {
+        input: { ...inputArgType },
+        meta: { ...metaArgType },
+    },
+}
+
+export const Default = () => (
+    <Field
+        required
+        component={SimpleSingleSelectFieldFF}
+        name="story"
+        label="Do you agree?"
+        options={options}
+        validate={hasValue}
+    />
+)
+
+export const InitialValue = () => (
+    <Field
+        component={SimpleSingleSelectFieldFF}
+        name="story"
+        label="Do you agree?"
+        options={options}
+        initialValue="4"
+    />
+)

package/src/SimpleSingleSelectFieldFF/SimpleSingleSelectFieldFF.test.js

@@ -0,0 +1,82 @@
+import '@testing-library/jest-dom'
+import { Button } from '@dhis2-ui/button'
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { Field, Form } from 'react-final-form'
+import { hasValue } from '../validators/index.js'
+import { SimpleSingleSelectFieldFF } from './SimpleSingleSelectFieldFF.js'
+
+describe('<SimpleSingleSelectFieldFF/>', () => {
+    beforeEach(jest.resetAllMocks)
+    it("should use FF's input for value selection", () => {
+        const onSubmit = jest.fn()
+
+        render(
+            <Form onSubmit={onSubmit}>
+                {(formRenderProps) => (
+                    <form onSubmit={formRenderProps.handleSubmit}>
+                        <Field
+                            component={SimpleSingleSelectFieldFF}
+                            name="story"
+                            label="Label text"
+                            options={[
+                                { value: '', label: 'None' },
+                                { value: 'foo', label: 'Foo' },
+                                { value: 'bar', label: 'Bar' },
+                            ]}
+                        />
+
+                        <Button primary type="submit">
+                            Submit
+                        </Button>
+                    </form>
+                )}
+            </Form>
+        )
+
+        fireEvent.click(screen.getByRole('combobox'))
+        fireEvent.click(screen.getByText('Foo'))
+        fireEvent.click(screen.getByRole('button'))
+
+        expect(onSubmit).toHaveBeenCalledTimes(1)
+        expect(onSubmit).toHaveBeenCalledWith(
+            { story: 'foo' },
+            expect.anything(),
+            expect.anything()
+        )
+    })
+
+    it('should display the validation error', () => {
+        const onSubmit = jest.fn()
+
+        render(
+            <Form onSubmit={onSubmit}>
+                {(formRenderProps) => (
+                    <form onSubmit={formRenderProps.handleSubmit}>
+                        <Field
+                            required
+                            component={SimpleSingleSelectFieldFF}
+                            name="story"
+                            label="Label text"
+                            validate={hasValue}
+                            options={[
+                                { value: '', label: 'None' },
+                                { value: 'foo', label: 'Foo' },
+                                { value: 'bar', label: 'Bar' },
+                            ]}
+                        />
+
+                        <Button primary type="submit">
+                            Submit
+                        </Button>
+                    </form>
+                )}
+            </Form>
+        )
+
+        fireEvent.click(screen.getByRole('button'))
+
+        const error = screen.getByText('Please provide a value')
+        expect(error).not.toBeNull()
+    })
+})

package/src/SingleSelectFieldFF/SingleSelectFieldFF.e2e.stories.js

@@ -0,0 +1,23 @@
+import React from 'react'
+import { Field } from 'react-final-form'
+import { formDecorator } from '../formDecorator.js'
+import { hasValue } from '../validators/index.js'
+import { SingleSelectFieldFF } from './SingleSelectFieldFF.js'
+
+const defaultOptions = [{ value: 'initial', label: 'Initial' }]
+
+export default {
+    title: 'Testing:SingleSelectFieldFF',
+    decorators: [formDecorator],
+    parameters: { options: { showPanel: false } },
+}
+export const Required = (_, { cypressProps }) => (
+    <Field
+        required
+        name="singleSelect"
+        label="Single select"
+        component={SingleSelectFieldFF}
+        validate={hasValue}
+        options={cypressProps.options || defaultOptions}
+    />
+)

package/src/SingleSelectFieldFF/SingleSelectFieldFF.js

@@ -0,0 +1,70 @@
+import { SingleSelectOption, SingleSelectField } from '@dhis2-ui/select'
+import PropTypes from 'prop-types'
+import React from 'react'
+import {
+    createSelectChangeHandler,
+    createFocusHandler,
+    createBlurHandler,
+    hasError,
+    isLoading,
+    isValid,
+    getValidationText,
+} from '../shared/helpers.js'
+import { inputPropType, metaPropType } from '../shared/propTypes.js'
+
+export const SingleSelectFieldFF = ({
+    error,
+    input,
+    loading,
+    meta,
+    onBlur,
+    onFocus,
+    options,
+    showLoadingStatus,
+    showValidStatus,
+    valid,
+    validationText,
+    ...rest
+}) => {
+    return (
+        <SingleSelectField
+            {...rest}
+            name={input.name}
+            error={hasError(meta, error)}
+            valid={isValid(meta, valid, showValidStatus)}
+            loading={isLoading(meta, loading, showLoadingStatus)}
+            validationText={getValidationText(meta, validationText, error)}
+            onFocus={createFocusHandler(input, onFocus)}
+            onChange={createSelectChangeHandler(input)}
+            onBlur={createBlurHandler(input, onBlur)}
+            selected={input.value || ''}
+        >
+            {options.map((option) => (
+                <SingleSelectOption key={option.value} {...option} />
+            ))}
+        </SingleSelectField>
+    )
+}
+
+SingleSelectFieldFF.propTypes = {
+    /** `input` props received from Final Form `Field` */
+    input: inputPropType.isRequired,
+    /** `meta` props received from Final Form `Field` */
+    meta: metaPropType.isRequired,
+    options: PropTypes.arrayOf(
+        PropTypes.shape({
+            label: PropTypes.string,
+            value: PropTypes.string,
+        })
+    ).isRequired,
+
+    error: PropTypes.bool,
+    loading: PropTypes.bool,
+    showLoadingStatus: PropTypes.bool,
+    showValidStatus: PropTypes.bool,
+    valid: PropTypes.bool,
+    validationText: PropTypes.string,
+
+    onBlur: PropTypes.func,
+    onFocus: PropTypes.func,
+}

package/src/SingleSelectFieldFF/SingleSelectFieldFF.prod.stories.js

@@ -0,0 +1,77 @@
+import React from 'react'
+import { Field } from 'react-final-form'
+import { formDecorator } from '../formDecorator.js'
+import { inputArgType, metaArgType } from '../shared/propTypes.js'
+import { SingleSelectFieldFF } from './SingleSelectFieldFF.js'
+
+const description = `
+The \`SingleSelectFieldFF\` is a wrapper around a \`SingleSelectField\` that enables it to work with Final Form, the preferred library for form validation and utilities in DHIS 2 apps.
+
+#### Final Form
+
+See how to use Final Form at [Final Form - Getting Started](https://final-form.org/docs/react-final-form/getting-started).
+
+Inside a Final Form \`<Form>\` component, these 'FF' UI components are intended to be used in the \`component\` prop of the [Final Form \`<Field>\` components](https://final-form.org/docs/react-final-form/api/Field) where they will receive some props from the Field, e.g. \`<Field component={SingleSelectFieldFF} />\`.  See the code samples below for examples.
+
+#### Props
+
+The props shown in the table below are generally provided to the \`SingleSelectFieldFF\` wrapper by the Final Form \`Field\`.
+
+Note that any props beyond the API of the \`Field\` component will be spread to the \`SingleSelectFieldFF\`, which passes any extra props to the underlying \`SingleSelectField\` using \`{...rest}\`.
+
+Therefore, to add any props to the \`SingleSelectFieldFF\` or \`SingleSelectField\`, add those props to the parent Final Form \`Field\` component.
+
+Also see \`SingleSelect\` and \`SingleSelectField\` for notes about props and implementation.
+
+\`\`\`js
+import { SingleSelectFieldFF } from '@dhis2/ui'
+\`\`\`
+
+Press **Submit** to see the form values logged to the console.
+
+_**Note:** Dropdowns may not appear correctly on this page. See the affected demos in the 'Canvas' tab for propper dropdown placement._
+`
+
+const options = [
+    { value: '1', label: 'one' },
+    { value: '2', label: 'two' },
+    { value: '3', label: 'three' },
+    { value: '4', label: 'four' },
+    { value: '5', label: 'five' },
+    { value: '6', label: 'six' },
+    { value: '7', label: 'seven' },
+    { value: '8', label: 'eight' },
+    { value: '9', label: 'nine' },
+    { value: '10', label: 'ten' },
+]
+
+export default {
+    title: 'Single Select Field (Final Form)',
+    component: SingleSelectFieldFF,
+    decorators: [formDecorator],
+    parameters: { docs: { description: { component: description } } },
+    argTypes: {
+        input: { ...inputArgType },
+        meta: { ...metaArgType },
+    },
+}
+
+export const Default = () => (
+    <Field
+        component={SingleSelectFieldFF}
+        name="agree"
+        label="Do you agree?"
+        options={options}
+    />
+)
+
+export const InitialValue = () => (
+    <Field
+        component={SingleSelectFieldFF}
+        name="agree"
+        label="Do you agree?"
+        options={options}
+        initialValue="4"
+    />
+)
+InitialValue.storyName = 'InitialValue'

package/src/SingleSelectFieldFF/features/can_set_a_value/index.js

@@ -0,0 +1,22 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('the SingleSelect has one option', () => {
+    const options = [{ value: 'Value', label: 'Label' }]
+
+    cy.wrap(options).as('options')
+    cy.window().then((win) => {
+        win.updateCypressProps({ options })
+    })
+})
+
+When('the user selects the first option', () => {
+    cy.get('[data-test="dhis2-uicore-select-input"]').selectSelectNthOption(0)
+})
+
+Then("the form state's value equals the first option's value", () => {
+    cy.get('@options').then((options) => {
+        cy.getFormValue('singleSelect').then((actualValue) => {
+            expect(actualValue).to.deep.equal(options[0].value)
+        })
+    })
+})

package/src/SingleSelectFieldFF/features/can_set_a_value.feature

@@ -0,0 +1,7 @@
+Feature: The SingleSelect can set a value
+
+    Scenario: The user clicks the first option
+        Given a required SingleSelect with no selected value
+        And the SingleSelect has one option
+        When the user selects the first option
+        Then the form state's value equals the first option's value

package/src/SingleSelectFieldFF/features/common/index.js

@@ -0,0 +1,6 @@
+import { Given } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a required SingleSelect with no selected value', () => {
+    cy.visitStory('Testing:SingleSelectFieldFF', 'Required')
+    cy.verifyFormValue('singleSelect', undefined)
+})

package/src/SingleSelectFieldFF/features/displays_error/index.js

@@ -0,0 +1,10 @@
+import { When, Then } from '@badeball/cypress-cucumber-preprocessor'
+import { hasValueMessage } from '../../../validators/hasValue.js'
+
+When('the user submits the form', () => {
+    cy.get('button[type="submit"]').click()
+})
+
+Then('an error message is shown', () => {
+    cy.get('.error').should('contain', hasValueMessage)
+})

package/src/SingleSelectFieldFF/features/displays_error.feature

@@ -0,0 +1,6 @@
+Feature: The SingleSelect field displays an error when invalid
+
+    Scenario: Form is submitted with none of the options selected
+        Given a required SingleSelect with no selected value
+        When the user submits the form
+        Then an error message is shown

package/src/SwitchFieldFF/SwitchFieldFF.e2e.stories.js

@@ -0,0 +1,52 @@
+import React from 'react'
+import { Field } from 'react-final-form'
+import { formDecorator } from '../formDecorator.js'
+import { hasValue } from '../validators/index.js'
+import { SwitchFieldFF } from './SwitchFieldFF.js'
+
+// https://github.com/final-form/react-final-form-arrays/issues/111
+const initialValue = ['yes']
+
+export default { title: 'Testing:SwitchFieldFF', decorators: [formDecorator] }
+export const Unchecked = () => (
+    <Field
+        component={SwitchFieldFF}
+        className="switch"
+        name="switch"
+        label="Label text"
+        validate={hasValue}
+        required
+        type="checkbox"
+    />
+)
+export const Checked = () => (
+    <Field
+        component={SwitchFieldFF}
+        className="switch"
+        name="switch"
+        label="Label text"
+        initialValue={true}
+        type="checkbox"
+    />
+)
+export const UncheckedWithValue = () => (
+    <Field
+        component={SwitchFieldFF}
+        className="switch"
+        name="switch"
+        label="Label text"
+        value="yes"
+        type="checkbox"
+    />
+)
+export const CheckedWithValue = () => (
+    <Field
+        component={SwitchFieldFF}
+        className="switch"
+        name="switch"
+        label="Label text"
+        value="yes"
+        initialValue={initialValue}
+        type="checkbox"
+    />
+)

package/src/SwitchFieldFF/SwitchFieldFF.js

@@ -0,0 +1,52 @@
+import { SwitchField } from '@dhis2-ui/switch'
+import PropTypes from 'prop-types'
+import React from 'react'
+import {
+    createToggleChangeHandler,
+    createFocusHandler,
+    createBlurHandler,
+    hasError,
+    isValid,
+    getValidationText,
+} from '../shared/helpers.js'
+import { metaPropType, inputPropType } from '../shared/propTypes.js'
+
+export const SwitchFieldFF = ({
+    error,
+    input,
+    meta,
+    showValidStatus,
+    valid,
+    validationText,
+    onBlur,
+    onFocus,
+    ...rest
+}) => (
+    <SwitchField
+        {...rest}
+        checked={input.checked}
+        name={input.name}
+        value={input.value}
+        error={hasError(meta, error)}
+        valid={isValid(meta, valid, showValidStatus)}
+        validationText={getValidationText(meta, validationText, error)}
+        onFocus={createFocusHandler(input, onFocus)}
+        onChange={createToggleChangeHandler(input)}
+        onBlur={createBlurHandler(input, onBlur)}
+    />
+)
+
+SwitchFieldFF.propTypes = {
+    /** `input` props received from Final Form `Field` */
+    input: inputPropType.isRequired,
+    /** `meta` props received from Final Form `Field` */
+    meta: metaPropType.isRequired,
+
+    error: PropTypes.bool,
+    showValidStatus: PropTypes.bool,
+    valid: PropTypes.bool,
+    validationText: PropTypes.string,
+
+    onBlur: PropTypes.func,
+    onFocus: PropTypes.func,
+}