feat(Checkbox): add component

CHANGELOG.md

@@ -41,6 +41,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Add 'lightning' icon to Teams theme @notandrew ([#1385](https://github.com/stardust-ui/react/pull/1385))
 - Add automatic positioning inside viewport for `Menu` with submenus @Bugaa92 ([#1384](https://github.com/stardust-ui/react/pull/1384))
 - Add `align`, `position`, `offset` props for `Dropdown` component @Bugaa92 ([#1312](https://github.com/stardust-ui/react/pull/1312))
+- Add `Checkbox` component and `toggle` prop for it @layershifter ([#1405](https://github.com/stardust-ui/react/pull/1405))
 
 ### Documentation
 - Accessibility: improve introduction section @jurokapsiar ([#1368](https://github.com/stardust-ui/react/pull/1368))

docs/src/components/ExampleSnippet/renderElementToJSX.ts

@@ -14,7 +14,7 @@ const renderElementToJSX = (element: React.ReactNode, triggerErrorOnRenderFn: bo
       (typeof element.type === 'function' ? 'NoDisplayName' : element.type),
     showDefaultProps: false,
     showFunctions: true,
-    filterProps: ['accessibility'],
+    filterProps: ['accessibility', 'onClick', 'onChange'],
     functionValue: () => (renderHasFunction = true),
   })
 

docs/src/examples/components/Checkbox/Playground.tsx

@@ -0,0 +1,26 @@
+import { useBooleanKnob, useStringKnob } from '@stardust-ui/docs-components'
+import { Checkbox } from '@stardust-ui/react'
+import * as React from 'react'
+
+const CheckboxPlayground: React.FunctionComponent = () => {
+  const [checked, setChecked] = useBooleanKnob({ name: 'checked' })
+  const [disabled] = useBooleanKnob({ name: 'disabled' })
+  const [toggle] = useBooleanKnob({ name: 'toggle' })
+
+  const [label] = useStringKnob({
+    name: 'label',
+    initialValue: 'Make profile visible',
+  })
+
+  return (
+    <Checkbox
+      checked={checked}
+      disabled={disabled}
+      label={label}
+      toggle={toggle}
+      onChange={(e, data) => setChecked(data.checked)}
+    />
+  )
+}
+
+export default CheckboxPlayground

docs/src/examples/components/Checkbox/Types/CheckboxExample.shorthand.steps.ts

@@ -0,0 +1,8 @@
+import { Checkbox } from '@stardust-ui/react'
+
+export const config: ScreenerTestsConfig = {
+  themes: ['base', 'teams'],
+  steps: [builder => builder.click(`.${Checkbox.className}`).snapshot('Can be checked')],
+}
+
+export default config

docs/src/examples/components/Checkbox/Types/CheckboxExample.shorthand.tsx

@@ -0,0 +1,6 @@
+import { Checkbox } from '@stardust-ui/react'
+import * as React from 'react'
+
+const CheckboxExample = () => <Checkbox label="Make my profile visible" />
+
+export default CheckboxExample

docs/src/examples/components/Checkbox/Types/CheckboxExampleDisabled.shorthand.tsx

@@ -0,0 +1,11 @@
+import { Checkbox } from '@stardust-ui/react'
+import * as React from 'react'
+
+const CheckboxExampleDisabled = () => (
+  <>
+    <Checkbox disabled label="Disabled" />
+    <Checkbox disabled checked label="Disabled & Checked" />
+  </>
+)
+
+export default CheckboxExampleDisabled

docs/src/examples/components/Checkbox/Types/CheckboxExampleToggle.shorthand.steps.ts

@@ -0,0 +1,8 @@
+import { Checkbox } from '@stardust-ui/react'
+
+export const config: ScreenerTestsConfig = {
+  themes: ['base', 'teams'],
+  steps: [builder => builder.click(`.${Checkbox.className}`).snapshot('Can be checked')],
+}
+
+export default config

docs/src/examples/components/Checkbox/Types/CheckboxExampleToggle.shorthand.tsx

@@ -0,0 +1,11 @@
+import { Checkbox } from '@stardust-ui/react'
+import * as React from 'react'
+
+const CheckboxExampleToggle = () => (
+  <>
+    <Checkbox label="Subscribe to weekly newsletter" toggle />
+    <Checkbox disabled checked label="Subscribe to weekly newsletter" toggle />
+  </>
+)
+
+export default CheckboxExampleToggle

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

@@ -0,0 +1,26 @@
+import * as 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="Checkbox"
+      description="A standard checkbox."
+      examplePath="components/Checkbox/Types/CheckboxExample"
+    />
+    <ComponentExample
+      title="Disabled"
+      description="A checkbox can be read-only and unable to change states."
+      examplePath="components/Checkbox/Types/CheckboxExampleDisabled"
+    />
+    <ComponentExample
+      title="Toggle"
+      description="A checkbox can be formatted to show an on or off choice."
+      examplePath="components/Checkbox/Types/CheckboxExampleToggle"
+    />
+  </ExampleSection>
+)
+
+export default Types

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

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

packages/react/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,168 @@
+import * as customPropTypes from '@stardust-ui/react-proptypes'
+import * as _ from 'lodash'
+import * as React from 'react'
+import * as PropTypes from 'prop-types'
+
+import {
+  applyAccessibilityKeyHandlers,
+  AutoControlledComponent,
+  createShorthandFactory,
+  ChildrenComponentProps,
+  commonPropTypes,
+  isFromKeyboard,
+  UIComponentProps,
+} from '../../lib'
+import { ComponentEventHandler, WithAsProp, ShorthandValue, withSafeTypeForAs } from '../../types'
+import Icon from '../Icon/Icon'
+import Text from '../Text/Text'
+import { Accessibility } from '../../lib/accessibility/types'
+import { checkboxBehavior } from '../../lib/accessibility'
+
+export interface CheckboxProps extends UIComponentProps, ChildrenComponentProps {
+  /**
+   * Accessibility behavior if overridden by the user.
+   * @default checkboxBehavior
+   */
+  accessibility?: Accessibility
+
+  /** Initial checked value. */
+  defaultChecked?: boolean
+
+  /** Whether or not item is checked. */
+  checked?: boolean
+
+  /** An item can appear disabled and be unable to change states. */
+  disabled?: boolean
+
+  /** The item indicator can be user-defined icon. */
+  icon?: ShorthandValue
+
+  /** The label of the item. */
+  label?: ShorthandValue
+
+  /**
+   * Called after item checked state is changed.
+   * @param {SyntheticEvent} event - React's original SyntheticEvent.
+   * @param {object} data - All props.
+   */
+  onChange?: ComponentEventHandler<CheckboxProps>
+
+  /**
+   * Called after click.
+   * @param {SyntheticEvent} event - React's original SyntheticEvent.
+   * @param {object} data - All props.
+   */
+  onClick?: ComponentEventHandler<CheckboxProps>
+
+  /** A checkbox can be formatted to show an on or off choice. */
+  toggle?: boolean
+}
+
+export interface CheckboxState {
+  checked: boolean
+  isFromKeyboard: boolean
+}
+
+class Checkbox extends AutoControlledComponent<WithAsProp<CheckboxProps>, CheckboxState> {
+  static create: Function
+
+  static displayName = 'Checkbox'
+
+  static className = 'ui-checkbox'
+
+  static propTypes = {
+    ...commonPropTypes.createCommon({
+      content: false,
+    }),
+    checked: PropTypes.bool,
+    defaultChecked: PropTypes.bool,
+    disabled: PropTypes.bool,
+    icon: customPropTypes.itemShorthand,
+    label: customPropTypes.itemShorthand,
+    onChange: PropTypes.func,
+    onClick: PropTypes.func,
+    toggle: PropTypes.bool,
+  }
+
+  static defaultProps = {
+    accessibility: checkboxBehavior,
+    icon: {},
+  }
+
+  static autoControlledProps = ['checked']
+
+  actionHandlers = {
+    performClick: (e: any /* TODO: use React.KeyboardEvent */) => {
+      e.preventDefault()
+      this.handleClick(e)
+    },
+  }
+
+  getInitialAutoControlledState(): CheckboxState {
+    return { checked: false, isFromKeyboard: false }
+  }
+
+  handleChange = (e: React.ChangeEvent) => {
+    // Checkbox component doesn't present any `input` component in markup, however all of our
+    // components should handle events transparently.
+    const { disabled } = this.props
+    const checked = !this.state.checked
+
+    if (!disabled) {
+      this.trySetState({ checked })
+      _.invoke(this.props, 'onChange', e, { ...this.props, checked })
+    }
+  }
+
+  handleClick = (e: React.MouseEvent | React.KeyboardEvent) => {
+    const { disabled } = this.props
+    const checked = !this.state.checked
+
+    if (!disabled) {
+      this.trySetState({ checked })
+
+      _.invoke(this.props, 'onClick', e, { ...this.props, checked })
+      _.invoke(this.props, 'onChange', e, { ...this.props, checked })
+    }
+  }
+
+  handleFocus = (e: React.FocusEvent) => {
+    this.setState({ isFromKeyboard: isFromKeyboard() })
+
+    _.invoke(this.props, 'onFocus', e, this.props)
+  }
+
+  renderComponent({ ElementType, classes, unhandledProps, styles, accessibility }) {
+    const { label, icon, toggle } = this.props
+
+    return (
+      <ElementType
+        className={classes.root}
+        onClick={this.handleClick}
+        onChange={this.handleChange}
+        onFocus={this.handleFocus}
+        {...accessibility.attributes.root}
+        {...unhandledProps}
+        {...applyAccessibilityKeyHandlers(accessibility.keyHandlers.root, unhandledProps)}
+      >
+        {Icon.create(icon, {
+          defaultProps: {
+            name: toggle ? 'stardust-circle' : 'stardust-checkmark',
+            styles: toggle ? styles.toggle : styles.checkbox,
+          },
+        })}
+        {Text.create(label)}
+      </ElementType>
+    )
+  }
+}
+
+Checkbox.create = createShorthandFactory({
+  Component: Checkbox,
+  mappedProp: 'label',
+})
+
+/**
+ * A single checkbox within a checkbox group.
+ */
+export default withSafeTypeForAs<typeof Checkbox, CheckboxProps>(Checkbox)

packages/react/src/index.ts

@@ -48,6 +48,9 @@ export { default as ChatItem } from './components/Chat/ChatItem'
 export * from './components/Chat/ChatMessage'
 export { default as ChatMessage } from './components/Chat/ChatMessage'
 
+export * from './components/Checkbox/Checkbox'
+export { default as Checkbox } from './components/Checkbox/Checkbox'
+
 export * from './components/Divider/Divider'
 export { default as Divider } from './components/Divider/Divider'
 

packages/react/src/lib/accessibility/Behaviors/Checkbox/checkboxBehavior.ts

@@ -0,0 +1,32 @@
+import * as keyboardKey from 'keyboard-key'
+import { Accessibility } from '../../types'
+
+// TODO: use after https://github.com/stardust-ui/react/pull/1421
+// type CheckboxBehaviorProps = {
+//   checked: boolean
+// }
+
+/**
+ * @specification
+ * Adds role='checkbox'. This allows screen readers to handle the component as a checkbox button.
+ * Adds attribute 'aria-checked=true' based on the property 'checked'.
+ * Adds attribute 'tabIndex=0' to 'root' component's part.
+ */
+const checkboxBehavior: Accessibility = props => ({
+  attributes: {
+    root: {
+      'aria-checked': props.checked,
+      role: 'checkbox',
+      tabIndex: 0,
+    },
+  },
+  keyActions: {
+    root: {
+      performClick: {
+        keyCombinations: [{ keyCode: keyboardKey.Enter }, { keyCode: keyboardKey.Spacebar }],
+      },
+    },
+  },
+})
+
+export default checkboxBehavior

packages/react/src/lib/accessibility/index.ts

@@ -38,3 +38,4 @@ export { default as embedBehavior } from './Behaviors/Embed/embedBehavior'
 export { default as accordionBehavior } from './Behaviors/Accordion/accordionBehavior'
 export { default as accordionTitleBehavior } from './Behaviors/Accordion/accordionTitleBehavior'
 export { default as accordionContentBehavior } from './Behaviors/Accordion/accordionContentBehavior'
+export { default as checkboxBehavior } from './Behaviors/Checkbox/checkboxBehavior'

packages/react/src/themes/base/componentStyles.ts

@@ -1,3 +1,5 @@
+export { default as Checkbox } from './components/Checkbox/checkboxStyles'
+
 export { default as Dialog } from './components/Dialog/dialogStyles'
 
 export { default as Flex } from './components/Flex/flexStyles'

packages/react/src/themes/base/componentVariables.ts

@@ -1,3 +1,5 @@
+export { default as Checkbox } from './components/Checkbox/checkboxVariables'
+
 export { default as Dialog } from './components/Dialog/dialogVariables'
 
 export { default as Flex } from './components/Flex/flexVariables'