@dhis2-ui/text-area 10.16.2 → 10.16.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/text-area",
-    "version": "10.16.2",
+    "version": "10.16.3",
     "description": "UI TextArea",
     "repository": {
         "type": "git",
@@ -33,18 +33,19 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/box": "10.16.2",
-        "@dhis2-ui/field": "10.16.2",
-        "@dhis2-ui/loader": "10.16.2",
-        "@dhis2-ui/status-icon": "10.16.2",
-        "@dhis2/ui-constants": "10.16.2",
-        "@dhis2/ui-icons": "10.16.2",
+        "@dhis2-ui/box": "10.16.3",
+        "@dhis2-ui/field": "10.16.3",
+        "@dhis2-ui/loader": "10.16.3",
+        "@dhis2-ui/status-icon": "10.16.3",
+        "@dhis2/ui-constants": "10.16.3",
+        "@dhis2/ui-icons": "10.16.3",
         "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 { TextArea } from './text-area/index.js'
+export { TextAreaField } from './text-area-field/index.js'

package/src/text-area/__tests__/text-area.test.js

@@ -0,0 +1,20 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { TextArea } from '../text-area.js'
+
+describe('<TextArea>', () => {
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(<TextArea name="foo" value="bar" onKeyDown={onKeyDown} />)
+
+        fireEvent.keyDown(screen.getByRole('textbox'), {})
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'foo', value: 'bar' },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+})

package/src/text-area/features/accepts_initial_focus/index.js

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

package/src/text-area/features/accepts_initial_focus.feature

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

package/src/text-area/features/can_be_blurred/index.js

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

package/src/text-area/features/can_be_blurred.feature

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

package/src/text-area/features/can_be_changed/index.js

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

package/src/text-area/features/can_be_changed.feature

@@ -0,0 +1,6 @@
+Feature: The TextArea has an onChange api
+
+    Scenario: The user types a character into the TextArea
+        Given a TextArea with onChange handler is rendered
+        When the TextArea is filled with a character
+        Then the onChange handler is called

package/src/text-area/features/can_be_disabled/index.js

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

package/src/text-area/features/can_be_disabled.feature

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

package/src/text-area/features/can_be_focused/index.js

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

package/src/text-area/features/can_be_focused.feature

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

package/src/text-area/features/common/index.js

@@ -0,0 +1,5 @@
+import { Given } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('an empty TextArea is rendered', () => {
+    cy.visitStory('TextArea', 'Empty')
+})

package/src/text-area/index.js

@@ -0,0 +1 @@
+export { TextArea } from './text-area.js'

package/src/text-area/text-area.e2e.stories.js

@@ -0,0 +1,19 @@
+import React from 'react'
+import { TextArea } 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: 'TextArea' }
+export const WithOnChange = () => (
+    <TextArea onChange={window.onChange} name="textarea" />
+)
+export const WithInitialFocusAndOnBlur = () => (
+    <TextArea initialFocus name="textarea" onBlur={window.onBlur} />
+)
+export const WithOnFocus = () => (
+    <TextArea name="textarea" onFocus={window.onFocus} />
+)
+export const WithInitialFocus = () => <TextArea name="textarea" initialFocus />
+export const WithDisabled = () => <TextArea name="textarea" disabled />

package/src/text-area/text-area.js

@@ -0,0 +1,224 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import { StatusIcon } from '@dhis2-ui/status-icon'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { Component } from 'react'
+import { styles } from './text-area.styles.js'
+
+export class TextArea extends Component {
+    textareaRef = React.createRef()
+    state = {
+        height: 'auto',
+    }
+    textareaDimensions = { width: 0, height: 0 }
+    userHasResized = false
+
+    componentDidMount() {
+        this.attachResizeListener()
+
+        if (this.props.initialFocus) {
+            this.textareaRef.current.focus()
+        }
+
+        if (this.shouldDoAutoGrow()) {
+            this.setHeight()
+        }
+    }
+
+    componentDidUpdate(prevProps) {
+        if (this.shouldDoAutoGrow() && this.props.value !== prevProps.value) {
+            this.setHeight()
+        }
+    }
+
+    attachResizeListener() {
+        const textarea = this.textareaRef.current
+        textarea.addEventListener('mousedown', this.setTextareaDimensions)
+        textarea.addEventListener('mouseup', this.hasUserResized)
+    }
+
+    removeResizeListener() {
+        const textarea = this.textareaRef.current
+        textarea.removeEventListener('mousedown', this.setTextareaDimensions)
+        textarea.removeEventListener('mouseup', this.hasUserResized)
+    }
+
+    setHeight() {
+        const textarea = this.textareaRef.current
+        const offset = textarea.offsetHeight - textarea.clientHeight
+        const height = textarea.scrollHeight + offset + 'px'
+        this.setState({ height })
+    }
+
+    setTextareaDimensions = () => {
+        const textarea = this.textareaRef.current
+        this.textareaDimensions = {
+            width: textarea.clientWidth,
+            height: textarea.clientHeight,
+        }
+    }
+
+    shouldDoAutoGrow() {
+        return this.props.autoGrow && !this.userHasResized
+    }
+
+    hasUserResized = () => {
+        const { width: oldWidth, height: oldHeight } = this.textareaDimensions
+
+        this.setTextareaDimensions()
+
+        const { width: newWidth, height: newHeight } = this.textareaDimensions
+        const userHasResized = newWidth !== oldWidth || newHeight !== oldHeight
+
+        if (userHasResized) {
+            this.userHasResized = true
+            this.removeResizeListener()
+        }
+    }
+
+    handleChange = (e) => {
+        if (this.props.onChange) {
+            this.props.onChange(this.createHandlerPayload(e), e)
+        }
+    }
+
+    handleBlur = (e) => {
+        if (this.props.onBlur) {
+            this.props.onBlur(this.createHandlerPayload(e), e)
+        }
+    }
+
+    handleFocus = (e) => {
+        if (this.props.onFocus) {
+            this.props.onFocus(this.createHandlerPayload(e), e)
+        }
+    }
+
+    handleKeyDown = (e) => {
+        if (this.props.onKeyDown) {
+            this.props.onKeyDown(this.createHandlerPayload(e), e)
+        }
+    }
+
+    createHandlerPayload(e) {
+        return {
+            value: e.target.value,
+            name: this.props.name,
+        }
+    }
+    static defaultProps = {
+        rows: 4,
+        width: '100%',
+        resize: 'vertical',
+        dataTest: 'dhis2-uicore-textarea',
+    }
+
+    render() {
+        const {
+            className,
+            dense,
+            disabled,
+            readOnly,
+            placeholder,
+            name,
+            valid,
+            error,
+            warning,
+            loading,
+            value,
+            tabIndex,
+            resize = 'vertical',
+            rows = 4,
+            width = '100%',
+            dataTest = 'dhis2-uicore-textarea',
+        } = this.props
+        const { height } = this.state
+
+        return (
+            <div className={cx('textarea', className)} data-test={dataTest}>
+                <textarea
+                    id={name}
+                    name={name}
+                    placeholder={placeholder}
+                    ref={this.textareaRef}
+                    value={value}
+                    disabled={disabled}
+                    readOnly={readOnly}
+                    tabIndex={tabIndex}
+                    onFocus={this.handleFocus}
+                    onKeyDown={this.handleKeyDown}
+                    onBlur={this.handleBlur}
+                    onChange={this.handleChange}
+                    rows={rows}
+                    className={cx({
+                        dense,
+                        disabled,
+                        error,
+                        valid,
+                        warning,
+                        'read-only': readOnly,
+                    })}
+                />
+                <StatusIcon
+                    error={error}
+                    valid={valid}
+                    loading={loading}
+                    warning={warning}
+                />
+
+                <style jsx>{styles}</style>
+                <style jsx>{`
+                    textarea {
+                        width: ${width};
+                        height: ${height};
+                        resize: ${resize};
+                    }
+                `}</style>
+            </div>
+        )
+    }
+}
+
+TextArea.propTypes = {
+    /** Grow the text area in response to overflow instead of adding a scroll bar */
+    autoGrow: PropTypes.bool,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Compact mode */
+    dense: PropTypes.bool,
+    /** Disables the textarea and makes in non-interactive */
+    disabled: PropTypes.bool,
+    /** Applies 'error' styles for validation feedback. Mutually exclusive with `valid` and `warning` props */
+    error: sharedPropTypes.statusPropType,
+    /** Grabs initial focus on the page */
+    initialFocus: PropTypes.bool,
+    /** Adds a loading spinner */
+    loading: PropTypes.bool,
+    /** Name associated with the text area. Passed in object argument to event handlers. */
+    name: PropTypes.string,
+    /** Placeholder text for an empty textarea */
+    placeholder: PropTypes.string,
+    /** Makes the textarea read-only */
+    readOnly: PropTypes.bool,
+    /** [Resize property](https://developer.mozilla.org/en-US/docs/Web/CSS/resize) for the textarea element */
+    resize: PropTypes.oneOf(['none', 'both', 'horizontal', 'vertical']),
+    /** Initial height of the textarea, in lines of text */
+    rows: PropTypes.number,
+    tabIndex: PropTypes.string,
+    /** Applies 'valid' styles for validation feedback. Mutually exclusive with `warning` and `error` props */
+    valid: sharedPropTypes.statusPropType,
+    /** Value in the textarea. Can be used to control component (recommended). Passed in object argument to event handlers. */
+    value: PropTypes.string,
+    /** Applies 'warning' styles for validation feedback. Mutually exclusive with `valid` and `error` props */
+    warning: sharedPropTypes.statusPropType,
+    /** Width of the text area. Can be any valid CSS measurement */
+    width: PropTypes.string,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onBlur: PropTypes.func,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onChange: PropTypes.func,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onFocus: PropTypes.func,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onKeyDown: PropTypes.func,
+}

package/src/text-area/text-area.prod.stories.js

@@ -0,0 +1,219 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React from 'react'
+import { TextArea } from './index.js'
+
+const description = `
+A textarea allows multiple lines of text input. Use a textarea wherever a user needs to input a lot of information. Do not use a textarea if a short, single line of content is expected.
+
+Options for textarea inputs are:
+
+- Rows: the height of the input, defined by the number of rows of text
+- Resizable: whether the textarea can be resized by the user or not. Can be set for both width and height.
+- Autoheight: if enabled, the texarea will grow in height to adapt to the content.
+
+\`\`\`js
+import { TextArea } from '@dhis2/ui'
+\`\`\`
+`
+
+window.onChange = (payload, event) => {
+    console.log('onChange payload', payload)
+    console.log('onChange 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: 'Text Area',
+    component: TextArea,
+    parameters: { docs: { description: { component: description } } },
+    argTypes: {
+        valid: { ...sharedPropTypes.statusArgType },
+        error: { ...sharedPropTypes.statusArgType },
+        warning: { ...sharedPropTypes.statusArgType },
+    },
+    args: {
+        name: 'textAreaName',
+        onChange,
+        onFocus,
+        onBlur,
+    },
+}
+
+const Template = (args) => <TextArea {...args} />
+
+export const Default = Template.bind({})
+
+export const PlaceholderNoValue = Template.bind({})
+PlaceholderNoValue.args = { placeholder: 'Hold the place' }
+PlaceholderNoValue.storyName = 'Placeholder, no value'
+
+export const WithValue = Template.bind({})
+WithValue.args = {
+    value: 'This is set through the value prop, which means the component is controlled.',
+}
+WithValue.storyName = 'With value'
+
+export const Focus = (args) => (
+    <>
+        <TextArea {...args} initialFocus className="initially-focused" />
+        <TextArea {...args} className="initially-unfocused" />
+    </>
+)
+Focus.parameters = { docs: { disable: true } }
+
+export const StatusValid = Template.bind({})
+StatusValid.args = { valid: true, value: 'This value is valid' }
+StatusValid.storyName = 'Status: Valid'
+
+export const StatusWarning = Template.bind({})
+StatusWarning.args = { warning: true, value: 'This value produces a warning' }
+StatusWarning.storyName = 'Status: Warning'
+
+export const StatusError = Template.bind({})
+StatusError.args = {
+    error: true,
+    value: 'This value produces an error',
+    helpText: 'This is some help text to advise what this input actually is.',
+    validationText: 'This describes the error, if a message is supplied.',
+}
+StatusError.storyName = 'Status: Error'
+
+export const StatusLoading = Template.bind({})
+StatusLoading.args = {
+    loading: true,
+    value: 'This value produces a loadingn state',
+}
+StatusLoading.storyName = 'Status: Loading'
+
+export const Disabled = Template.bind({})
+Disabled.args = { disabled: true, value: 'This field is disabled' }
+
+export const ReadOnly = Template.bind({})
+ReadOnly.args = { readOnly: true, value: 'This field is readOnly' }
+
+export const Dense = Template.bind({})
+Dense.args = { dense: true, value: 'This field is dense' }
+
+export const TextareaTextOverflow = Template.bind({})
+TextareaTextOverflow.args = {
+    label: 'I have a scrollbar',
+    value: [
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+    ].join('\n'),
+}
+
+export const Rows = Template.bind({})
+Rows.args = {
+    rows: 8,
+    label: 'You can set the height with the rows prop. I have 8',
+}
+
+export const Resize = (args) => (
+    <>
+        <TextArea
+            {...args}
+            name="textarea1"
+            label="Resize: vertical (default)"
+        />
+        <TextArea
+            {...args}
+            name="textarea2"
+            label="Resize: none"
+            resize="none"
+        />
+        <TextArea
+            {...args}
+            name="textarea3"
+            label="Resize: both"
+            resize="both"
+        />
+        <TextArea
+            {...args}
+            name="textarea4"
+            label="Resize: horizontal"
+            resize="horizontal"
+        />
+    </>
+)
+
+export const Autogrow = (args) => (
+    <>
+        <TextArea
+            {...args}
+            name="textarea1"
+            label="Autogrow step 1"
+            autoGrow
+            rows={2}
+            value="This TextArea has a height of 2 rows"
+        />
+        <TextArea
+            {...args}
+            name="textarea2"
+            label="Autogrow step 2"
+            autoGrow
+            rows={2}
+            value={[
+                'This TextArea has a height of two rows',
+                'it also has autoGrow set to true so it will grow with the content',
+            ].join('\n')}
+        />
+        <TextArea
+            {...args}
+            name="textarea3"
+            label="Autogrow step 3"
+            autoGrow
+            rows={2}
+            value={[
+                'This TextArea has a height of two rows',
+                'it also has autoGrow set to true so it will grow with the content.',
+                'See: rows is still 2, but I now have 3 lines.',
+            ].join('\n')}
+        />
+        <TextArea
+            {...args}
+            name="textarea4"
+            label="Autogrow step 4"
+            value={[
+                'This TextArea has a height of two rows',
+                'it also has autoGrow set to true so it will grow with the content.',
+                'See: rows is still 2...',
+                'And now I have 4 lines and still no scroll bar in sight.',
+            ].join('\n')}
+        />
+    </>
+)
+
+export const RTL = (args) => (
+    <div dir="rtl">
+        <Template {...args} />
+    </div>
+)
+RTL.args = { valid: true, value: 'This RTL text is valid' }
+RTL.storyName = 'RTL: Valid'

package/src/text-area/text-area.styles.js

@@ -0,0 +1,60 @@
+import { colors, theme, spacers } from '@dhis2/ui-constants'
+import css from 'styled-jsx/css'
+
+export const styles = css`
+    .textarea {
+        display: flex;
+        gap: ${spacers.dp8};
+    }
+    textarea {
+        box-sizing: border-box;
+        padding: 8px 12px;
+
+        color: ${colors.grey900};
+        background-color: white;
+
+        border: 1px solid ${colors.grey500};
+        border-radius: 3px;
+        box-shadow: inset 0 0 1px 0 rgba(48, 54, 60, 0.1);
+        outline: 0;
+
+        font-size: 14px;
+        line-height: 17px;
+        user-select: text;
+    }
+
+    textarea.dense {
+        padding: 6px 8px;
+    }
+
+    textarea:focus {
+        outline: none;
+        box-shadow: inset 0 0 0 2px ${theme.focus};
+        border-color: ${theme.focus};
+    }
+
+    textarea.valid {
+        border-color: ${theme.valid};
+    }
+
+    textarea.warning {
+        border-color: ${theme.warning};
+    }
+
+    textarea.error {
+        border-color: ${theme.error};
+    }
+
+    textarea.read-only {
+        background-color: ${colors.grey100};
+        border-color: ${colors.grey500};
+        cursor: text;
+    }
+
+    textarea.disabled {
+        background-color: ${colors.grey100};
+        border-color: ${colors.grey500};
+        color: ${theme.disabled};
+        cursor: not-allowed;
+    }
+`

package/src/text-area-field/__tests__/text-area-field.test.js

@@ -0,0 +1,20 @@
+import { render, fireEvent, screen } from '@testing-library/react'
+import React from 'react'
+import { TextAreaField } from '../text-area-field.js'
+
+describe('<TextArea>', () => {
+    it('should call the onKeyDown callback when provided', () => {
+        const onKeyDown = jest.fn()
+
+        render(<TextAreaField name="foo" value="bar" onKeyDown={onKeyDown} />)
+
+        fireEvent.keyDown(screen.getByRole('textbox'), {})
+
+        expect(onKeyDown).toHaveBeenCalledWith(
+            { name: 'foo', value: 'bar' },
+            expect.objectContaining({})
+        )
+
+        expect(onKeyDown).toHaveBeenCalledTimes(1)
+    })
+})

package/src/text-area-field/features/can_be_required/index.js

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

package/src/text-area-field/features/can_be_required.feature

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

package/src/text-area-field/index.js

@@ -0,0 +1 @@
+export { TextAreaField } from './text-area-field.js'

package/src/text-area-field/text-area-field.e2e.stories.js

@@ -0,0 +1,11 @@
+import React from 'react'
+import { TextAreaField } from './index.js'
+
+export default { title: 'TextAreaField' }
+export const WithLabelAndRequired = () => (
+    <TextAreaField
+        name="textarea"
+        label="I am required and have an asterisk"
+        required
+    />
+)

package/src/text-area-field/text-area-field.js

@@ -0,0 +1,127 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import { Box } from '@dhis2-ui/box'
+import { Field } from '@dhis2-ui/field'
+import PropTypes from 'prop-types'
+import React from 'react'
+import { TextArea } from '../text-area/index.js'
+
+const TextAreaField = ({
+    className,
+    onChange,
+    onFocus,
+    onKeyDown,
+    onBlur,
+    initialFocus,
+    dense,
+    required,
+    label,
+    disabled,
+    placeholder,
+    name,
+    valid,
+    error,
+    warning,
+    loading,
+    value,
+    tabIndex,
+    helpText,
+    validationText,
+    autoGrow,
+    readOnly,
+    resize = 'vertical',
+    rows = 4,
+    inputWidth,
+    dataTest = 'dhis2-uiwidgets-textareafield',
+}) => (
+    <Field
+        className={className}
+        dataTest={dataTest}
+        disabled={disabled}
+        required={required}
+        name={name}
+        helpText={helpText}
+        validationText={validationText}
+        error={error}
+        warning={warning}
+        valid={valid}
+        label={label}
+    >
+        <Box width={inputWidth} minWidth="220px">
+            <TextArea
+                onFocus={onFocus}
+                onKeyDown={onKeyDown}
+                onBlur={onBlur}
+                onChange={onChange}
+                name={name}
+                value={value || ''}
+                placeholder={placeholder}
+                disabled={disabled}
+                valid={valid}
+                warning={warning}
+                error={error}
+                loading={loading}
+                dense={dense}
+                tabIndex={tabIndex}
+                initialFocus={initialFocus}
+                autoGrow={autoGrow}
+                readOnly={readOnly}
+                resize={resize}
+                rows={rows}
+            />
+        </Box>
+    </Field>
+)
+
+TextAreaField.propTypes = {
+    /** Grow the text area in response to overflow instead of adding a scroll bar */
+    autoGrow: PropTypes.bool,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Compact mode */
+    dense: PropTypes.bool,
+    /** Disables the textarea and makes in non-interactive */
+    disabled: PropTypes.bool,
+    /** Applies 'error' styles for validation feedback. Mutually exclusive with `valid` and `warning` props */
+    error: sharedPropTypes.statusPropType,
+    /** Adds useful help text below the textarea */
+    helpText: PropTypes.string,
+    /** Grabs initial focus on the page */
+    initialFocus: PropTypes.bool,
+    /** Sets the width of the textarea. Minimum 220px. Any valid CSS measurement can be used */
+    inputWidth: PropTypes.string,
+    /** Labels the textarea */
+    label: PropTypes.string,
+    /** Adds a loading spinner */
+    loading: PropTypes.bool,
+    /** Name associated with the text area. Passed in object argument to event handlers. */
+    name: PropTypes.string,
+    /** Placeholder text for an empty textarea */
+    placeholder: PropTypes.string,
+    /** Makes the textarea read-only */
+    readOnly: PropTypes.bool,
+    /** Adds an asterisk to the label to indicate this field is required */
+    required: PropTypes.bool,
+    /** [Resize property](https://developer.mozilla.org/en-US/docs/Web/CSS/resize) for the textarea element */
+    resize: PropTypes.oneOf(['none', 'both', 'horizontal', 'vertical']),
+    /** Initial height of the textarea, in lines of text */
+    rows: PropTypes.number,
+    tabIndex: PropTypes.string,
+    /** Applies 'valid' styles for validation feedback. Mutually exclusive with `warning` and `error` props */
+    valid: sharedPropTypes.statusPropType,
+    /** Validation text below the textarea to provide validation feedback. Changes appearance depending on validation status */
+    validationText: PropTypes.string,
+    /** Value in the textarea. Can be used to control component (recommended). Passed in object argument to event handlers. */
+    value: PropTypes.string,
+    /** Applies 'warning' styles for validation feedback. Mutually exclusive with `valid` and `error` props */
+    warning: sharedPropTypes.statusPropType,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onBlur: PropTypes.func,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onChange: PropTypes.func,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onFocus: PropTypes.func,
+    /** Called with signature `({ name: string, value: string }, event)` */
+    onKeyDown: PropTypes.func,
+}
+
+export { TextAreaField }

package/src/text-area-field/text-area-field.prod.stories.js

@@ -0,0 +1,221 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React from 'react'
+import { TextAreaField } from './index.js'
+
+const description = `
+\`TextAreaField\` wraps a \`TextArea\` component with a label, help text, validation text, and other functions.
+
+See the regular TextArea for usage information and options.
+
+\`\`\`js
+import { TextAreaField } from '@dhis2/ui'
+\`\`\`
+`
+
+export default {
+    title: 'Text Area Field',
+    component: TextAreaField,
+    parameters: { docs: { description: { component: description } } },
+    // Default args:
+    args: {
+        onChange: console.log,
+        name: 'textareaName',
+    },
+    argTypes: {
+        valid: { ...sharedPropTypes.statusArgType },
+        warning: { ...sharedPropTypes.statusArgType },
+        error: { ...sharedPropTypes.statusArgType },
+    },
+}
+
+const Template = (args) => <TextAreaField {...args} />
+
+export const NoPlaceholderNoValue = Template.bind({})
+NoPlaceholderNoValue.storyName = 'No placeholder, no value'
+
+export const PlaceholderNoValue = Template.bind({})
+PlaceholderNoValue.args = { placeholder: 'Hold the place' }
+PlaceholderNoValue.storyName = 'Placeholder, no value'
+
+export const WithHelpText = Template.bind({})
+WithHelpText.args = {
+    helpText: 'With some helping text to guide the user along',
+    ...PlaceholderNoValue.args,
+}
+
+export const WithValue = Template.bind({})
+WithValue.args = {
+    value: 'This is set through the value prop, which means the component is controlled.',
+}
+
+export const Focus = Template.bind({})
+Focus.args = { initialFocus: true }
+// Disable stories that manipulate focus on docs page
+Focus.parameters = { docs: { disable: true } }
+
+export const StatusValid = Template.bind({})
+StatusValid.args = { valid: true, value: 'This value is valid' }
+StatusValid.storyName = 'Status: Valid'
+
+export const StatusWarning = Template.bind({})
+StatusWarning.args = { warning: true, value: 'This value produces a warning' }
+StatusWarning.storyName = 'Status: Warning'
+
+export const StatusError = Template.bind({})
+StatusError.args = {
+    error: true,
+    value: 'This value produces an error',
+    helpText: 'This is some help text to advise what this input actually is.',
+    validationText: 'This describes the error, if a message is supplied.',
+}
+StatusError.storyName = 'Status: Error'
+
+export const StatusLoading = Template.bind({})
+StatusLoading.args = {
+    loading: true,
+    value: 'This value produces a loadingn state',
+}
+StatusLoading.storyName = 'Status: Loading'
+
+export const Disabled = Template.bind({})
+Disabled.args = { disabled: true, value: 'This field is disabled' }
+
+export const ReadOnly = Template.bind({})
+ReadOnly.args = { readOnly: true, value: 'This field is readOnly' }
+
+export const Dense = Template.bind({})
+Dense.args = { dense: true, value: 'This field is dense' }
+
+export const LabelTextOverflow = Template.bind({})
+LabelTextOverflow.args = {
+    label: "This label is too long to show on a single line of the input field's label. We just let it flow to the next line so the user can still read it. However, we should always aim to keep it shorter than this!",
+}
+LabelTextOverflow.storyName = 'Label text overflow'
+
+export const TextareaTextOverflow = Template.bind({})
+TextareaTextOverflow.args = {
+    label: 'I have a scrollbar',
+    value: [
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+        'A line of text',
+    ].join('\n'),
+}
+
+export const Required = () => (
+    <TextAreaField
+        onChange={() => {}}
+        name="textarea"
+        label="I am required and have an asterisk"
+        required
+    />
+)
+Required.args = { required: true, label: 'I am required and have an asterisk' }
+
+export const Rows = Template.bind({})
+Rows.args = {
+    rows: 8,
+    label: 'You can set the height with the rows prop. I have 8',
+}
+
+export const InputWidth = (args) => (
+    <>
+        <TextAreaField
+            {...args}
+            label="My textarea has a width of 220px (the minimum)"
+            inputWidth="220px"
+        />
+        <TextAreaField
+            {...args}
+            label="My textarea has a width of 400px"
+            inputWidth="400px"
+        />
+    </>
+)
+
+export const Resize = (args) => (
+    <>
+        <TextAreaField
+            {...args}
+            name="textarea1"
+            label="Resize: vertical (default)"
+        />
+        <TextAreaField
+            {...args}
+            name="textarea2"
+            label="Resize: none"
+            resize="none"
+        />
+        <TextAreaField
+            {...args}
+            name="textarea3"
+            label="Resize: both"
+            resize="both"
+        />
+        <TextAreaField
+            {...args}
+            name="textarea4"
+            label="Resize: horizontal"
+            resize="horizontal"
+        />
+    </>
+)
+
+export const Autogrow = (args) => (
+    <>
+        <TextAreaField
+            {...args}
+            name="textarea1"
+            label="Autogrow step 1"
+            autoGrow
+            rows={2}
+            value="This TextArea has a height of 2 rows"
+        />
+        <TextAreaField
+            {...args}
+            name="textarea2"
+            label="Autogrow step 2"
+            autoGrow
+            rows={2}
+            value={[
+                'This TextArea has a height of two rows',
+                'it also has autoGrow set to true so it will grow with the content',
+            ].join('\n')}
+        />
+        <TextAreaField
+            {...args}
+            name="textarea3"
+            label="Autogrow step 3"
+            autoGrow
+            rows={2}
+            value={[
+                'This TextArea has a height of two rows',
+                'it also has autoGrow set to true so it will grow with the content.',
+                'See: rows is still 2, but I now have 3 lines.',
+            ].join('\n')}
+        />
+        <TextAreaField
+            {...args}
+            name="textarea4"
+            label="Autogrow step 4"
+            value={[
+                'This TextArea has a height of two rows',
+                'it also has autoGrow set to true so it will grow with the content.',
+                'See: rows is still 2...',
+                'And now I have 4 lines and still no scroll bar in sight.',
+            ].join('\n')}
+        />
+    </>
+)