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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2/ui-forms",
-    "version": "10.16.1",
+    "version": "10.16.3-alpha.1",
     "main": "./build/cjs/index.js",
     "module": "./build/es/index.js",
     "sideEffects": [
@@ -35,15 +35,15 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/button": "10.16.1",
-        "@dhis2-ui/checkbox": "10.16.1",
-        "@dhis2-ui/field": "10.16.1",
-        "@dhis2-ui/file-input": "10.16.1",
-        "@dhis2-ui/input": "10.16.1",
-        "@dhis2-ui/radio": "10.16.1",
-        "@dhis2-ui/select": "10.16.1",
-        "@dhis2-ui/switch": "10.16.1",
-        "@dhis2-ui/text-area": "10.16.1",
+        "@dhis2-ui/button": "10.16.3-alpha.1",
+        "@dhis2-ui/checkbox": "10.16.3-alpha.1",
+        "@dhis2-ui/field": "10.16.3-alpha.1",
+        "@dhis2-ui/file-input": "10.16.3-alpha.1",
+        "@dhis2-ui/input": "10.16.3-alpha.1",
+        "@dhis2-ui/radio": "10.16.3-alpha.1",
+        "@dhis2-ui/select": "10.16.3-alpha.1",
+        "@dhis2-ui/switch": "10.16.3-alpha.1",
+        "@dhis2-ui/text-area": "10.16.3-alpha.1",
         "classnames": "^2.3.1",
         "final-form": "^4.20.2",
         "prop-types": "^15.7.2",
@@ -51,7 +51,8 @@
     },
     "files": [
         "build",
-        "types"
+        "types",
+        "src"
     ],
     "devDependencies": {
         "react": "^18.3.1",

package/src/CheckboxFieldFF/CheckboxFieldFF.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 { CheckboxFieldFF } from './CheckboxFieldFF.js'
+
+// https://github.com/final-form/react-final-form-arrays/issues/111
+const initialValue = ['yes']
+
+export default { title: 'Testing:Checkbox', decorators: [formDecorator] }
+export const Unchecked = () => (
+    <Field
+        type="checkbox"
+        component={CheckboxFieldFF}
+        className="checkbox"
+        name="checkbox"
+        label="Label text"
+        validate={hasValue}
+        required
+    />
+)
+export const Checked = () => (
+    <Field
+        type="checkbox"
+        component={CheckboxFieldFF}
+        className="checkbox"
+        name="checkbox"
+        label="Label text"
+        initialValue={true}
+    />
+)
+export const UncheckedWithValue = () => (
+    <Field
+        type="checkbox"
+        component={CheckboxFieldFF}
+        className="checkbox"
+        name="checkbox"
+        label="Label text"
+        value="yes"
+    />
+)
+export const CheckedWithValue = () => (
+    <Field
+        type="checkbox"
+        component={CheckboxFieldFF}
+        className="checkbox"
+        name="checkbox"
+        label="Label text"
+        value="yes"
+        initialValue={initialValue}
+    />
+)

package/src/CheckboxFieldFF/CheckboxFieldFF.js

@@ -0,0 +1,52 @@
+import { CheckboxField } from '@dhis2-ui/checkbox'
+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 CheckboxFieldFF = ({
+    error,
+    input,
+    meta,
+    showValidStatus,
+    valid,
+    validationText,
+    onBlur,
+    onFocus,
+    ...rest
+}) => (
+    <CheckboxField
+        {...rest}
+        name={input.name}
+        checked={input.checked}
+        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)}
+    />
+)
+
+CheckboxFieldFF.propTypes = {
+    /** Provided by Final Form `Field` */
+    input: inputPropType.isRequired,
+    /** Provided by Final Form `Field` */
+    meta: metaPropType.isRequired,
+
+    error: PropTypes.bool,
+    showValidStatus: PropTypes.bool,
+    valid: PropTypes.bool,
+    validationText: PropTypes.string,
+
+    onBlur: PropTypes.func,
+    onFocus: PropTypes.func,
+}

package/src/CheckboxFieldFF/CheckboxFieldFF.prod.stories.js

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

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

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

package/src/CheckboxFieldFF/features/can_toggle_a_boolean.feature

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

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

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

package/src/CheckboxFieldFF/features/can_toggle_a_value.feature

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

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

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

package/src/CheckboxFieldFF/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 Checkbox is rendered', () => {
+    cy.visitStory('Testing:Checkbox', 'Unchecked')
+    cy.verifyFormValue('checkbox', 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-checkboxfield-validation"]').should(
+        'contain',
+        hasValueMessage
+    )
+})

package/src/CheckboxFieldFF/features/displays_error.feature

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

package/src/FieldGroupFF/FieldGroupFF.js

@@ -0,0 +1,42 @@
+import { FieldGroup } from '@dhis2-ui/field'
+import PropTypes from 'prop-types'
+import React from 'react'
+import { useField } from 'react-final-form'
+
+export const FieldGroupFF = ({ name, label, children, required }) => {
+    const {
+        meta: { error, touched },
+    } = useField(name, { subscription: { error: true, touched: true } })
+
+    const isError = !!error && !!touched
+    let errorText
+
+    if (isError) {
+        if (typeof error === 'string') {
+            errorText = error
+        } else if (typeof error === 'object' && error[name]) {
+            errorText = error[name]
+        } else {
+            errorText = null
+        }
+    }
+
+    return (
+        <FieldGroup
+            label={label}
+            required={required}
+            error={isError}
+            name={name}
+            validationText={errorText}
+        >
+            {children}
+        </FieldGroup>
+    )
+}
+
+FieldGroupFF.propTypes = {
+    children: PropTypes.node,
+    label: PropTypes.string,
+    name: PropTypes.string,
+    required: PropTypes.bool,
+}

package/src/FieldGroupFF/FieldGroupFF.prod.stories.js

@@ -0,0 +1,49 @@
+import React from 'react'
+import { Field } from 'react-final-form'
+import { CheckboxFieldFF } from '../CheckboxFieldFF/CheckboxFieldFF.js'
+import { formDecorator } from '../formDecorator.js'
+import { hasValue } from '../validators/index.js'
+import { FieldGroupFF } from './FieldGroupFF.js'
+
+const description = `
+This component is intended for use with [Final Form](https://final-form.org/docs/react-final-form/getting-started), the preferred library for form validation and utilities in DHIS 2 apps.
+
+\`FieldGroupFF\` groups related fields (using the Final Form \`<Field>\`), like checkboxes, and adds a label and name.
+
+\`\`\`js
+import { FieldGroupFF } from '@dhis2/ui'
+\`\`\`
+
+Press **Submit** to see the form values logged to the console.
+`
+
+export default {
+    title: 'Field Group (Final Form)',
+    component: FieldGroupFF,
+    decorators: [formDecorator],
+    parameters: { docs: { description: { component: description } } },
+}
+
+export const Default = () => (
+    <FieldGroupFF label="Group label" required name="set">
+        <Field
+            type="checkbox"
+            component={CheckboxFieldFF}
+            name="set"
+            label="One"
+            value="one"
+            validate={hasValue}
+            validationText={null}
+        />
+
+        <Field
+            type="checkbox"
+            component={CheckboxFieldFF}
+            name="set"
+            label="Two"
+            validate={hasValue}
+            value="two"
+            validationText={null}
+        />
+    </FieldGroupFF>
+)