feat(Form): base implementation

CHANGELOG.md

@@ -31,6 +31,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Features
 - Add `target` prop to `Popup` @kuzhelog ([#356](https://github.com/stardust-ui/react/pull/356))
 - Add new `Input` component with `wrapper` prop @Bugaa92 ([#326](https://github.com/stardust-ui/react/pull/326))
+- Add `Form` and `Form.Field` components @mnajdova ([#353](https://github.com/stardust-ui/react/pull/353))
 
 <!--------------------------------[ v0.9.1 ]------------------------------- -->
 ## [v0.9.1](https://github.com/stardust-ui/react/tree/v0.9.1) (2018-10-11)

docs/src/examples/components/Form/Types/FormExample.shorthand.tsx

@@ -0,0 +1,38 @@
+import React from 'react'
+import { Form, Button } from '@stardust-ui/react'
+
+const fields = [
+  {
+    label: 'First name',
+    name: 'firstName',
+    id: 'first-name-shorthand',
+    key: 'first-name',
+    required: true,
+  },
+  {
+    label: 'Last name',
+    name: 'lastName',
+    id: 'last-name-shorthand',
+    key: 'last-name',
+    required: true,
+  },
+  {
+    label: 'I agree to the Terms and Conditions',
+    control: { as: 'input' },
+    type: 'checkbox',
+    id: 'conditions-shorthand',
+    key: 'conditions',
+  },
+  { control: { as: Button, content: 'Submit' }, key: 'submit' },
+]
+
+const FormExample = () => (
+  <Form
+    onSubmit={() => {
+      alert('Form submitted')
+    }}
+    fields={fields}
+  />
+)
+
+export default FormExample

docs/src/examples/components/Form/Types/FormExample.tsx

@@ -0,0 +1,22 @@
+import React from 'react'
+import { Form, Button } from '@stardust-ui/react'
+
+const FormExample = () => (
+  <Form
+    onSubmit={() => {
+      alert('Form submitted')
+    }}
+  >
+    <Form.Field label="First name" name="firstName" id="first-name" required={true} />
+    <Form.Field label="Last name" name="lastName" id="last-name" required={true} />
+    <Form.Field
+      label="I agree to the Terms and Conditions"
+      control={{ as: 'input' }}
+      type="checkbox"
+      id="conditions"
+    />
+    <Form.Field control={{ as: Button, content: 'Submit' }} />
+  </Form>
+)
+
+export default FormExample

docs/src/examples/components/Form/Types/FormExampleInline.shorthand.tsx

@@ -0,0 +1,40 @@
+import React from 'react'
+import { Form, Button } from '@stardust-ui/react'
+
+const fields = [
+  {
+    label: 'First name',
+    name: 'firstName',
+    id: 'first-name-inline-shorthand',
+    key: 'first-name',
+    required: true,
+    inline: true,
+  },
+  {
+    label: 'Last name',
+    name: 'lastName',
+    id: 'last-name-inline-shorthand',
+    key: 'last-name',
+    required: true,
+    inline: true,
+  },
+  {
+    label: 'I agree to the Terms and Conditions',
+    control: { as: 'input' },
+    type: 'checkbox',
+    id: 'conditions-inline-shorthand',
+    key: 'conditions',
+  },
+  { control: { as: Button, content: 'Submit' }, key: 'submit' },
+]
+
+const FormExample = () => (
+  <Form
+    onSubmit={() => {
+      alert('Form submitted')
+    }}
+    fields={fields}
+  />
+)
+
+export default FormExample

docs/src/examples/components/Form/Types/FormExampleInline.tsx

@@ -0,0 +1,34 @@
+import React from 'react'
+import { Form, Button } from '@stardust-ui/react'
+
+const FormExample = () => (
+  <Form
+    onSubmit={() => {
+      alert('Form submitted')
+    }}
+  >
+    <Form.Field
+      label="First name"
+      name="firstName"
+      id="first-name-inline"
+      inline={true}
+      required={true}
+    />
+    <Form.Field
+      label="Last name"
+      name="lastName"
+      id="last-name-inline"
+      inline={true}
+      required={true}
+    />
+    <Form.Field
+      label="I agree to the Terms and Conditions"
+      control={{ as: 'input' }}
+      type="checkbox"
+      id="conditions-inline"
+    />
+    <Form.Field control={{ as: Button, content: 'Submit' }} />
+  </Form>
+)
+
+export default FormExample

docs/src/examples/components/Form/Types/index.tsx

@@ -0,0 +1,20 @@
+import React from 'react'
+import ComponentExample from 'docs/src/components/ComponentDoc/ComponentExample'
+import ExampleSection from 'docs/src/components/ComponentDoc/ExampleSection'
+
+const Types = () => (
+  <ExampleSection title="Types">
+    <ComponentExample
+      title="Default"
+      description="A default form."
+      examplePath="components/Form/Types/FormExample"
+    />
+    <ComponentExample
+      title="Inline"
+      description="The form controls can appear next to the label instead of below it."
+      examplePath="components/Form/Types/FormExampleInline"
+    />
+  </ExampleSection>
+)
+
+export default Types

docs/src/examples/components/Form/index.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import Types from './Types'
+
+const FormExamples = () => (
+  <div>
+    <Types />
+  </div>
+)
+
+export default FormExamples

src/components/Form/Form.tsx

@@ -0,0 +1,128 @@
+import * as PropTypes from 'prop-types'
+import * as React from 'react'
+import * as _ from 'lodash'
+
+import { UIComponent, childrenExist, customPropTypes } from '../../lib'
+import { ComponentVariablesInput, ComponentPartStyle } from '../../../types/theme'
+import {
+  ComponentEventHandler,
+  Extendable,
+  ReactChildren,
+  ShorthandValue,
+  ShorthandRenderFunction,
+} from '../../../types/utils'
+import FormField from './FormField'
+
+export interface IFormProps {
+  action?: string
+  as?: any
+  children?: ReactChildren
+  className?: string
+  content?: ShorthandValue
+  fields?: ShorthandValue[]
+  onSubmit?: ComponentEventHandler<IFormProps>
+  renderField?: ShorthandRenderFunction
+  styles?: ComponentPartStyle
+  variables?: ComponentVariablesInput
+}
+
+/**
+ * A Form displays a set of related user input fields in a structured way.
+ * @accessibility
+ * Label needs to be provided by using 'aria-label', or 'aria-labelledby' attributes on the <form> element.
+ */
+class Form extends UIComponent<Extendable<IFormProps>, any> {
+  static create: Function
+
+  public static displayName = 'Form'
+
+  public static className = 'ui-form'
+
+  public static propTypes = {
+    /** The HTML form action. */
+    action: PropTypes.string,
+
+    /** An element type to render as (string or function). */
+    as: customPropTypes.as,
+
+    /**
+     *  Form content for childrenApi.
+     *  @docSiteIgnore
+     */
+    children: PropTypes.node,
+
+    /** Additional CSS class name(s) to apply.  */
+    className: PropTypes.string,
+
+    /** Shorthand for primary content. */
+    content: customPropTypes.contentShorthand,
+
+    /** Shorthand array of props for the Form.Fields inside the Form. */
+    fields: customPropTypes.collectionShorthand,
+
+    /**
+     * The HTML form submit handler.
+     * @param {SyntheticEvent} event - React's original SyntheticEvent.
+     * @param {object} data - All props.
+     */
+    onSubmit: PropTypes.func,
+
+    /**
+     * A custom render iterator for rendering each of the Form fields.
+     * The default component, props, and children are available for each field.
+     *
+     * @param {React.ReactType} Component - The computed component for this slot.
+     * @param {object} props - The computed props for this slot.
+     * @param {ReactNode|ReactNodeArray} children - The computed children for this slot.
+     */
+    renderField: PropTypes.func,
+
+    /** Additional CSS styles to apply to the component instance.  */
+    styles: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
+
+    /** Override for theme site variables to allow modifications of component styling via themes. */
+    variables: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
+  }
+
+  public static defaultProps = {
+    as: 'form',
+  }
+
+  public static Field = FormField
+
+  public renderComponent({
+    ElementType,
+    classes,
+    accessibility,
+    variables,
+    styles,
+    rest,
+  }): React.ReactNode {
+    const { action, children } = this.props
+    return (
+      <ElementType className={classes.root} action={action} onSubmit={this.handleSubmit} {...rest}>
+        {childrenExist(children) ? children : this.renderFields()}
+      </ElementType>
+    )
+  }
+
+  private handleSubmit = (e, ...args) => {
+    const { action } = this.props
+
+    // Heads up! Third party libs can pass own data as first argument, we need to check that it has preventDefault()
+    // method.
+    if (!action) _.invoke(e, 'preventDefault')
+    _.invoke(this.props, 'onSubmit', e, this.props, ...args)
+  }
+
+  private renderFields = () => {
+    const { fields, renderField } = this.props
+    return _.map(fields, field =>
+      FormField.create(field, {
+        render: renderField,
+      }),
+    )
+  }
+}
+
+export default Form