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

package/src/SwitchFieldFF/SwitchFieldFF.prod.stories.js

@@ -0,0 +1,148 @@
+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 { SwitchFieldFF } from './SwitchFieldFF.js'
+
+const description = `
+The \`SwitchFieldFF\` is a wrapper around a \`SwitchField\` 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={SwitchFieldFF} />\`.  See the code samples below for examples.
+
+#### Props
+
+The props shown in the table below are generally provided to the \`SwitchFieldFF\` wrapper by the Final Form \`Field\`.
+
+Note that any props beyond the API of the \`Field\` component will be spread to the \`SwitchFieldFF\`, which passes any extra props to the underlying \`SwitchField\` using \`{...rest}\`.
+
+Therefore, to add any props to the \`SwitchFieldFF\` or \`SwitchField\`, add those props to the parent Final Form \`Field\` component.
+
+Also see \`Switch\` and \`SwitchField\` for notes about props and implementation.
+
+\`\`\`js
+import { SwitchFieldFF } from '@dhis2/ui'
+\`\`\`
+
+Press **Submit** to see the form values logged to the console.
+`
+
+export default {
+    title: 'Switch Field (Final Form)',
+    component: SwitchFieldFF,
+    decorators: [formDecorator],
+    parameters: { docs: { description: { component: description } } },
+    argTypes: {
+        input: { ...inputArgType },
+        meta: { ...metaArgType },
+    },
+}
+
+export const Default = () => (
+    <Field
+        type="checkbox"
+        component={SwitchFieldFF}
+        name="agree"
+        label="Do you agree?"
+    />
+)
+
+export const Required = () => (
+    <Field
+        type="checkbox"
+        name="agree"
+        component={SwitchFieldFF}
+        required
+        validate={hasValue}
+        label="Do you agree?"
+    />
+)
+
+export const Disabled = () => (
+    <Field
+        type="checkbox"
+        name="agree"
+        component={SwitchFieldFF}
+        disabled
+        label="Do you agree?"
+    />
+)
+
+export const HelpText = () => (
+    <Field
+        type="checkbox"
+        name="agree"
+        component={SwitchFieldFF}
+        label="Do you agree?"
+        helpText="Click to agree"
+    />
+)
+HelpText.storyName = 'Help text'
+
+export const Statuses = () => (
+    <>
+        <Field
+            type="checkbox"
+            name="valid"
+            component={SwitchFieldFF}
+            label="Valid"
+            valid
+            validationText="Validation text"
+        />
+        <Field
+            type="checkbox"
+            name="warning"
+            component={SwitchFieldFF}
+            label="Warning"
+            warning
+            validationText="Validation text"
+        />
+        <Field
+            type="checkbox"
+            name="error"
+            component={SwitchFieldFF}
+            label="Error"
+            error
+            validationText="Validation text"
+        />
+    </>
+)
+
+export const ValueWhenChecked = () => (
+    <>
+        <Field
+            type="checkbox"
+            name="bool"
+            component={SwitchFieldFF}
+            label="I produce boolean form values"
+            helpText="Click submit and check the console"
+        />
+        <Field
+            type="checkbox"
+            name="string"
+            component={SwitchFieldFF}
+            label="I produce string form values because the 'value' prop is set"
+            value="value_when_checked"
+            helpText="Click submit and check the console"
+        />
+        <Field
+            type="checkbox"
+            name="string"
+            component={SwitchFieldFF}
+            label="I also produce string form values"
+            value="another_value_when_checked"
+            helpText="Click submit and check the console"
+        />
+    </>
+)
+ValueWhenChecked.parameters = {
+    docs: {
+        description: {
+            story: 'See the details about using the `value` prop at the [Final Form docs](https://final-form.org/docs/react-final-form/types/FieldProps#value)',
+        },
+    },
+}

package/src/SwitchFieldFF/features/can_toggle_a_boolean/index.js

@@ -0,0 +1,19 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('an unchecked Switch without value is rendered', () => {
+    cy.visitStory('Testing:SwitchFieldFF', 'Unchecked')
+    cy.verifyFormValue('switch', undefined)
+})
+
+Then('the form value that corresponds to the switch will be true', () => {
+    cy.verifyFormValue('switch', true)
+})
+
+Given('a checked Switch without value is rendered', () => {
+    cy.visitStory('Testing:SwitchFieldFF', 'Checked')
+    cy.verifyFormValue('switch', true)
+})
+
+Then('the form value that corresponds to the switch will be false', () => {
+    cy.verifyFormValue('switch', false)
+})

package/src/SwitchFieldFF/features/can_toggle_a_boolean.feature

@@ -0,0 +1,11 @@
+Feature: The Switch can toggle a value
+
+    Scenario: The user enables the Switch
+        Given an unchecked Switch without value is rendered
+        When the user clicks on the Switch
+        Then the form value that corresponds to the switch will be true
+
+    Scenario: The user disables the Switch
+        Given a checked Switch without value is rendered
+        When the user clicks on the Switch
+        Then the form value that corresponds to the switch will be false

package/src/SwitchFieldFF/features/can_toggle_a_value/index.js

@@ -0,0 +1,21 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('an unchecked Switch with a value is rendered', () => {
+    cy.visitStory('Testing:SwitchFieldFF', 'Unchecked with value')
+    cy.verifyFormValue('switch', undefined)
+})
+
+Then('the form value that corresponds to the switch will be yes', () => {
+    cy.verifyFormArrayValue('switch', 'yes')
+})
+
+Given('a checked Switch with a value is rendered', () => {
+    cy.visitStory('Testing:SwitchFieldFF', 'Checked with value')
+    cy.verifyFormArrayValue('switch', 'yes')
+})
+
+Then('the form value that corresponds to the switch will be correct', () => {
+    cy.window().then((win) => {
+        expect(win.formValues.switch).to.deep.equal([])
+    })
+})

package/src/SwitchFieldFF/features/can_toggle_a_value.feature

@@ -0,0 +1,11 @@
+Feature: The Switch can toggle a value
+
+    Scenario: The user enables the Switch
+        Given an unchecked Switch with a value is rendered
+        When the user clicks on the Switch
+        Then the form value that corresponds to the switch will be yes
+
+    Scenario: The user disables the Switch
+        Given a checked Switch with a value is rendered
+        When the user clicks on the Switch
+        Then the form value that corresponds to the switch will be correct

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

@@ -0,0 +1,5 @@
+import { When } from '@badeball/cypress-cucumber-preprocessor'
+
+When('the user clicks on the Switch', () => {
+    cy.get('[data-test="dhis2-uicore-switch"]').click()
+})

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

@@ -0,0 +1,18 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+import { hasValueMessage } from '../../../validators/hasValue.js'
+
+Given('an unchecked Switch is rendered', () => {
+    cy.visitStory('Testing:SwitchFieldFF', 'Unchecked')
+    cy.verifyFormValue('switch', undefined)
+})
+
+When('the user submits the form', () => {
+    cy.get('button[type="submit"]').click()
+})
+
+Then('an error message is shown', () => {
+    cy.get('[data-test="dhis2-uiwidgets-switchfield-validation"]').should(
+        'contain',
+        hasValueMessage
+    )
+})

package/src/SwitchFieldFF/features/displays_error.feature

@@ -0,0 +1,6 @@
+Feature: The Switch field displays an error when invalid
+
+    Scenario: The user submits a form with an unchecked required switch
+        Given an unchecked Switch is rendered
+        When the user submits the form
+        Then an error message is shown

package/src/TextAreaFieldFF/TextAreaFieldFF.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 { TextAreaFieldFF } from './TextAreaFieldFF.js'
+
+export default { title: 'TextArea', decorators: [formDecorator] }
+export const Default = () => (
+    <Field
+        component={TextAreaFieldFF}
+        name="comment"
+        label="Do you have any comments?"
+    />
+)
+export const Required = () => (
+    <Field
+        required
+        name="comment"
+        component={TextAreaFieldFF}
+        validate={hasValue}
+        label="Do you have any comments?"
+    />
+)

package/src/TextAreaFieldFF/TextAreaFieldFF.js

@@ -0,0 +1,57 @@
+import { TextAreaField } from '@dhis2-ui/text-area'
+import PropTypes from 'prop-types'
+import React from 'react'
+import {
+    createChangeHandler,
+    createFocusHandler,
+    createBlurHandler,
+    hasError,
+    isLoading,
+    isValid,
+    getValidationText,
+} from '../shared/helpers.js'
+import { metaPropType, inputPropType } from '../shared/propTypes.js'
+
+export const TextAreaFieldFF = ({
+    input,
+    meta,
+    error,
+    showValidStatus,
+    valid,
+    validationText,
+    onBlur,
+    onFocus,
+    loading,
+    showLoadingStatus,
+    ...rest
+}) => (
+    <TextAreaField
+        {...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={createChangeHandler(input)}
+        onBlur={createBlurHandler(input, onBlur)}
+        value={input.value}
+    />
+)
+
+TextAreaFieldFF.propTypes = {
+    /** `input` props received from Final Form `Field` */
+    input: inputPropType.isRequired,
+    /** `meta` props received from Final Form `Field` */
+    meta: metaPropType.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/TextAreaFieldFF/TextAreaFieldFF.prod.stories.js

@@ -0,0 +1,111 @@
+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 { TextAreaFieldFF } from './TextAreaFieldFF.js'
+
+const description = `
+The \`TextAreaFieldFF\` is a wrapper around a \`TextAreaField\` 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={TextAreaFieldFF} />\`.  See the code samples below for examples.
+
+#### Props
+
+The props shown in the table below are generally provided to the \`TextAreaFieldFF\` wrapper by the Final Form \`Field\`.
+
+Note that any props beyond the API of the \`Field\` component will be spread to the \`TextAreaFieldFF\`, which passes any extra props to the underlying \`TextAreaField\` using \`{...rest}\`.
+
+Therefore, to add any props to the \`TextAreaFieldFF\` or \`TextAreaField\`, add those props to the parent Final Form \`Field\` component.
+
+Also see \`TextArea\` and \`TextAreaField\` for notes about props and implementation.
+
+\`\`\`js
+import { TextAreaFieldFF } from '@dhis2/ui'
+\`\`\`
+
+Press **Submit** to see the form values logged to the console.
+`
+
+export default {
+    title: 'Text Area Field (Final Form)',
+    component: TextAreaFieldFF,
+    decorators: [formDecorator],
+    parameters: { docs: { description: { component: description } } },
+    argTypes: {
+        input: { ...inputArgType },
+        meta: { ...metaArgType },
+    },
+}
+
+export const Default = () => (
+    <Field component={TextAreaFieldFF} name="agree" label="Do you agree?" />
+)
+
+export const Autogrow = () => (
+    <Field
+        component={TextAreaFieldFF}
+        name="agree"
+        label="Do you agree?"
+        autoGrow
+    />
+)
+
+export const Required = () => (
+    <Field
+        name="agree"
+        component={TextAreaFieldFF}
+        required
+        validate={hasValue}
+        label="Do you agree?"
+    />
+)
+
+export const Disabled = () => (
+    <Field
+        name="agree"
+        component={TextAreaFieldFF}
+        disabled
+        label="Do you agree?"
+    />
+)
+
+export const HelpText = () => (
+    <Field
+        name="agree"
+        component={TextAreaFieldFF}
+        label="Do you agree?"
+        helpText="Click to agree"
+    />
+)
+HelpText.storyName = 'Help text'
+
+export const Statuses = () => (
+    <>
+        <Field
+            name="valid"
+            component={TextAreaFieldFF}
+            label="Valid"
+            valid
+            validationText="Validation text"
+        />
+        <Field
+            name="warning"
+            component={TextAreaFieldFF}
+            label="Warning"
+            warning
+            validationText="Validation text"
+        />
+        <Field
+            name="error"
+            component={TextAreaFieldFF}
+            label="Error"
+            error
+            validationText="Validation text"
+        />
+    </>
+)

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

@@ -0,0 +1,14 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a TextArea with no text is rendered', () => {
+    cy.visitStory('TextArea', 'Default')
+    cy.verifyFormValue('comment', undefined)
+})
+
+When('the user types something in the TextArea', () => {
+    cy.get('textarea').type('something')
+})
+
+Then("the form state's value equals the written text", () => {
+    cy.verifyFormValue('comment', 'something')
+})

package/src/TextAreaFieldFF/features/can_set_a_value.feature

@@ -0,0 +1,6 @@
+Feature: The TextArea can set a value
+
+    Scenario: The user types some text
+        Given a TextArea with no text is rendered
+        When the user types something in the TextArea
+        Then the form state's value equals the written text

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

@@ -0,0 +1,15 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+import { hasValueMessage } from '../../../validators/hasValue.js'
+
+Given('an empty, required TextArea is rendered', () => {
+    cy.visitStory('TextArea', 'Required')
+    cy.verifyFormValue('agree', undefined)
+})
+
+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/TextAreaFieldFF/features/displays_error.feature

@@ -0,0 +1,6 @@
+Feature: The TextArea field displays an error when invalid
+
+    Scenario: Form is submitted with empty input
+        Given an empty, required TextArea is rendered
+        When the user submits the form
+        Then an error message is shown

package/src/__tests__/__snapshots__/index.test.js.snap

@@ -0,0 +1,65 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`final-form named export should re-export the expected exports 1`] = `
+Array [
+  "ARRAY_ERROR",
+  "FORM_ERROR",
+  "configOptions",
+  "createForm",
+  "fieldSubscriptionItems",
+  "formSubscriptionItems",
+  "getIn",
+  "setIn",
+  "version",
+  "default",
+]
+`;
+
+exports[`final-form named export should re-export the expected type for ARRAY_ERROR 1`] = `"string"`;
+
+exports[`final-form named export should re-export the expected type for FORM_ERROR 1`] = `"string"`;
+
+exports[`final-form named export should re-export the expected type for configOptions 1`] = `"object"`;
+
+exports[`final-form named export should re-export the expected type for createForm 1`] = `"function"`;
+
+exports[`final-form named export should re-export the expected type for default 1`] = `"object"`;
+
+exports[`final-form named export should re-export the expected type for fieldSubscriptionItems 1`] = `"object"`;
+
+exports[`final-form named export should re-export the expected type for formSubscriptionItems 1`] = `"object"`;
+
+exports[`final-form named export should re-export the expected type for getIn 1`] = `"function"`;
+
+exports[`final-form named export should re-export the expected type for setIn 1`] = `"function"`;
+
+exports[`final-form named export should re-export the expected type for version 1`] = `"string"`;
+
+exports[`react-final-form named export should re-export the expected exports 1`] = `
+Array [
+  "Field",
+  "Form",
+  "FormSpy",
+  "useField",
+  "useForm",
+  "useFormState",
+  "version",
+  "withTypes",
+]
+`;
+
+exports[`react-final-form named export should re-export the expected type for Field 1`] = `"object"`;
+
+exports[`react-final-form named export should re-export the expected type for Form 1`] = `"function"`;
+
+exports[`react-final-form named export should re-export the expected type for FormSpy 1`] = `"function"`;
+
+exports[`react-final-form named export should re-export the expected type for useField 1`] = `"function"`;
+
+exports[`react-final-form named export should re-export the expected type for useForm 1`] = `"function"`;
+
+exports[`react-final-form named export should re-export the expected type for useFormState 1`] = `"function"`;
+
+exports[`react-final-form named export should re-export the expected type for version 1`] = `"string"`;
+
+exports[`react-final-form named export should re-export the expected type for withTypes 1`] = `"function"`;

package/src/__tests__/index.test.js

@@ -0,0 +1,37 @@
+/* eslint-disable import/namespace */
+
+import { FinalForm, ReactFinalForm } from '../index.js'
+
+describe('final-form named export', () => {
+    it('should re-export the expected exports', () => {
+        const exports = Object.keys(FinalForm)
+
+        expect(exports).toMatchSnapshot()
+    })
+
+    it.each(Object.keys(FinalForm))(
+        'should re-export the expected type for %s',
+        (exportName) => {
+            const type = typeof FinalForm[exportName]
+
+            expect(type).toMatchSnapshot()
+        }
+    )
+})
+
+describe('react-final-form named export', () => {
+    it('should re-export the expected exports', () => {
+        const exports = Object.keys(ReactFinalForm)
+
+        expect(exports).toMatchSnapshot()
+    })
+
+    it.each(Object.keys(ReactFinalForm))(
+        'should re-export the expected type for %s',
+        (exportName) => {
+            const type = typeof ReactFinalForm[exportName]
+
+            expect(type).toMatchSnapshot()
+        }
+    )
+})

package/src/formDecorator.js

@@ -0,0 +1,80 @@
+import { Button } from '@dhis2-ui/button'
+import PropTypes from 'prop-types'
+import React from 'react'
+import { FormSpy, Form } from 'react-final-form'
+
+const formProps = {
+    onSubmit: (values) => {
+        console.log(
+            '++++++++++++++++\n',
+            'Form was submitted with values:\n',
+            values,
+            '\n----------------'
+        )
+    },
+    mutators: {},
+}
+
+class FormWithSpyAndSubmit extends React.Component {
+    state = {
+        cypressProps: {},
+    }
+
+    componentDidMount() {
+        window.updateCypressProps = this.updateCypressProps
+        window.clearCypressProps = this.clearCypressProps
+        this.forceUpdate()
+    }
+
+    componentWillUnmount() {
+        delete window.updateCypressProps
+        delete window.clearCypressProps
+    }
+
+    updateCypressProps = (updateObj) => {
+        const cypressProps = {
+            ...this.state.cypressProps,
+            ...updateObj,
+        }
+        this.setState({ cypressProps })
+    }
+
+    clearCypressProps = () => {
+        this.setState({ cypressProps: {} })
+    }
+
+    render() {
+        return (
+            <Form {...formProps}>
+                {(formRenderProps) => (
+                    <form onSubmit={formRenderProps.handleSubmit}>
+                        {this.props.renderChildren({
+                            formRenderProps,
+                            cypressProps: this.state.cypressProps,
+                        })}
+
+                        <Button primary type="submit">
+                            Submit
+                        </Button>
+
+                        {/* render after components to ensure capturing "initialValue"s */}
+                        <FormSpy>
+                            {({ values }) => {
+                                window.formValues = values
+                                return <span className="form-spy-internal" />
+                            }}
+                        </FormSpy>
+                    </form>
+                )}
+            </Form>
+        )
+    }
+}
+
+FormWithSpyAndSubmit.propTypes = {
+    renderChildren: PropTypes.func.isRequired,
+}
+
+export const formDecorator = (fn) => (
+    <FormWithSpyAndSubmit renderChildren={fn} />
+)