@instructure/ui-checkbox 11.6.0 → 11.6.1-snapshot-129

package/src/Checkbox/v2/CheckboxFacade/styles.ts

@@ -0,0 +1,209 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import { calcFocusOutlineStyles } from '@instructure/emotion'
+import type { CheckboxFacadeProps, CheckboxFacadeStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} sharedTokens Shared theme token object
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['Checkbox'],
+  props: CheckboxFacadeProps,
+  sharedTokens: SharedTokens
+): CheckboxFacadeStyle => {
+  const {
+    size,
+    checked,
+    disabled,
+    readOnly,
+    focused,
+    hovered,
+    indeterminate,
+    invalid
+  } = props
+
+  const isChecked = checked || indeterminate
+
+  const sizeVariants = {
+    small: {
+      label: { fontSize: componentTheme.fontSizeSm },
+      facade: {
+        fontSize: componentTheme.fontSizeSm,
+        width: componentTheme.controlSizeSm,
+        height: componentTheme.controlSizeSm,
+        margin: `${componentTheme.controlVerticalMargin} ${componentTheme.gap} 0 0`
+      }
+    },
+    medium: {
+      label: { fontSize: componentTheme.fontSizeMd },
+      facade: {
+        fontSize: componentTheme.fontSizeMd,
+        width: componentTheme.controlSizeMd,
+        height: componentTheme.controlSizeMd
+      }
+    },
+    large: {
+      label: { fontSize: componentTheme.fontSizeLg },
+      facade: {
+        fontSize: componentTheme.fontSizeLg,
+        width: componentTheme.controlSizeLg,
+        height: componentTheme.controlSizeLg
+      }
+    }
+  }
+  const sizeVariant =
+    sizeVariants[size as keyof typeof sizeVariants] ?? sizeVariants.medium
+
+  const getLabelColor = () => {
+    if (disabled) {
+      return componentTheme.labelDisabledColor
+    }
+
+    if (readOnly) {
+      return componentTheme.labelReadonlyColor
+    }
+
+    // DEFAULT state
+    return hovered
+      ? componentTheme.labelHoverColor
+      : componentTheme.labelBaseColor
+  }
+
+  const getFacadeStyles = () => {
+    const baseStyles = {
+      position: 'relative',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      boxSizing: 'border-box',
+      flexShrink: 0,
+      transition: 'all 0.2s',
+      borderRadius: componentTheme.borderRadius,
+      marginInlineEnd: componentTheme.gap,
+      marginInlineStart: '0',
+      ...sizeVariant.facade
+    }
+
+    if (disabled) {
+      return {
+        ...baseStyles,
+        background: componentTheme.backgroundDisabledColor,
+        border: `${componentTheme.borderWidth} solid ${componentTheme.borderDisabledColor}`
+      }
+    }
+
+    if (readOnly) {
+      return {
+        ...baseStyles,
+        background: componentTheme.backgroundReadonlyColor,
+        border: `${componentTheme.borderWidth} solid ${componentTheme.borderReadonlyColor}`,
+        pointerEvents: 'none'
+      }
+    }
+
+    if (invalid) {
+      return {
+        ...baseStyles,
+        ...(isChecked && {
+          background: componentTheme.backgroundCheckedColor,
+          border: `${componentTheme.borderWidth} solid ${
+            hovered
+              ? componentTheme.errorBorderHoverColor
+              : componentTheme.errorBorderColor
+          }`
+        }),
+        ...(!isChecked && {
+          background: hovered
+            ? componentTheme.backgroundHoverColor
+            : componentTheme.backgroundColor,
+          border: `${componentTheme.borderWidth} solid ${
+            hovered
+              ? componentTheme.errorBorderHoverColor
+              : componentTheme.errorBorderColor
+          }`
+        })
+      }
+    }
+
+    if (isChecked) {
+      return {
+        ...baseStyles,
+        background: componentTheme.backgroundCheckedColor,
+        border: `${componentTheme.borderWidth} solid ${componentTheme.borderCheckedColor}`
+      }
+    }
+
+    // DEFAULT (unchecked) state
+    return {
+      ...baseStyles,
+      background: hovered
+        ? componentTheme.backgroundHoverColor
+        : componentTheme.backgroundColor,
+      border: `${componentTheme.borderWidth} solid ${
+        hovered ? componentTheme.borderHoverColor : componentTheme.borderColor
+      }`
+    }
+  }
+
+  return {
+    checkboxFacade: {
+      label: 'checkboxFacade',
+      display: 'flex',
+      alignItems: 'flex-start',
+      cursor: disabled ? 'not-allowed' : readOnly ? 'default' : 'pointer'
+    },
+    facade: {
+      label: 'checkboxFacade__facade',
+      ...getFacadeStyles(),
+      ...(sharedTokens?.focusOutline
+        ? calcFocusOutlineStyles(sharedTokens.focusOutline, {
+            withFocusOutline: focused
+          })
+        : {})
+    },
+    label: {
+      label: 'checkboxFacade__label',
+      flex: '1 1 auto',
+      alignSelf: 'center',
+      minWidth: '0.0625rem',
+      color: getLabelColor(),
+      fontFamily: componentTheme.fontFamily,
+      fontWeight: componentTheme.fontWeight,
+      lineHeight: componentTheme.lineHeight,
+      ...sizeVariant.label
+    }
+  }
+}
+
+export default generateStyle

package/src/Checkbox/v2/README.md

@@ -0,0 +1,193 @@
+---
+describes: Checkbox
+---
+
+By default, the Checkbox component is a custom styled HTML checkbox. To default the checkbox to checked,
+set the `defaultChecked` prop.
+
+Adjust the size of the checkbox and label text via the `size` prop. The default size is
+`medium`.
+
+```js
+---
+type: example
+---
+<Checkbox label={lorem.sentence()} value="medium" defaultChecked />
+```
+
+The default Checkbox in its disabled state:
+
+```js
+---
+type: example
+---
+<CheckboxGroup
+  defaultValue={['medium']}
+  name="example"
+  description={<ScreenReaderContent>Checkbox examples</ScreenReaderContent>}
+>
+  <Checkbox label={lorem.sentence()} value="medium" disabled />
+  <Checkbox label={lorem.sentence()} value="small" disabled />
+</CheckboxGroup>
+```
+
+The `indeterminate` property triggers a visual state that handles
+situations where "child" Checkboxes are neither all checked nor all
+unchecked. Note the use of `aria-labelledby` to make the relationship
+between the parent and child Checkboxes clear to screenreader users.
+
+_Note: the `toggle` variant does not support the `indeterminate`
+property._
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [value, setValue] = useState(['his111', 'eng203'])
+
+    const updateValue = (valueToUpdate) => {
+      const index = value.indexOf(valueToUpdate)
+      console.log(index)
+      if (index === -1) {
+        setValue([...value, valueToUpdate])
+      } else {
+        setValue([...value.slice(0, index), ...value.slice(index + 1)])
+      }
+    }
+
+    return (
+      <FormFieldGroup
+        description={
+          <ScreenReaderContent>
+            <span id="groupLabel">Courses to edit</span>
+          </ScreenReaderContent>
+        }
+        rowSpacing="small"
+      >
+        <Checkbox
+          aria-labelledby="groupLabel selectAllLabel"
+          label={<span id="selectAllLabel">Select all courses</span>}
+          value="all"
+          onChange={() =>
+            setValue(value.length === 3 ? [] : ['eng203', 'sci101', 'his111'])
+          }
+          checked={value.length === 3}
+          indeterminate={value.length > 0 && value.length < 3}
+        />
+        <View as="div" padding="0 0 0 medium">
+          <Checkbox
+            aria-labelledby="groupLabel eng203Label"
+            label={<span id="eng203Label">English 203</span>}
+            value="eng203"
+            name="courses"
+            onChange={(event) => {
+              updateValue(event.target.value)
+            }}
+            checked={value.indexOf('eng203') !== -1}
+          />
+        </View>
+        <View as="div" padding="0 0 0 medium">
+          <Checkbox
+            aria-labelledby="groupLabel sci101Label"
+            label={<span id="sci101Label">Science 101</span>}
+            value="sci101"
+            name="courses"
+            onChange={(event) => {
+              updateValue(event.target.value)
+            }}
+            checked={value.indexOf('sci101') !== -1}
+          />
+        </View>
+        <View as="div" padding="0 0 0 medium">
+          <Checkbox
+            aria-labelledby="groupLabel hist101Label"
+            label={<span id="hist101Label">History 111</span>}
+            value="his111"
+            name="courses"
+            onChange={(event) => {
+              updateValue(event.target.value)
+            }}
+            checked={value.indexOf('his111') !== -1}
+          />
+        </View>
+      </FormFieldGroup>
+    )
+  }
+
+  render(<Example />)
+```
+
+Setting the `variant` prop to `toggle` turns the checkbox into a toggle switch. For **toggle only** the size prop affects the size of the label and not the actual size of the switch.
+
+```js
+---
+type: example
+---
+<FormFieldGroup description={<ScreenReaderContent>Checkbox examples</ScreenReaderContent>}>
+  <Checkbox label="Small size" value="small" variant="toggle" size="small" defaultChecked />
+  <Checkbox label="Medium size" value="medium" variant="toggle" />
+  <Checkbox label="Large size" value="large" variant="toggle" size="large" defaultChecked />
+</FormFieldGroup>
+```
+
+To change the label placement for the toggle variety, use the labelPlacement prop. The default
+placement is 'end'.
+
+_Note: the `simple` variant does not support the `labelPlacement`
+property._
+
+```js
+---
+type: example
+---
+<FormFieldGroup description={<ScreenReaderContent>Toggle label examples</ScreenReaderContent>}>
+  <Checkbox label="Top" variant="toggle" labelPlacement="top" defaultChecked />
+  <Checkbox label="Start" variant="toggle" labelPlacement="start" />
+  <Checkbox label="End" variant="toggle" labelPlacement="end" defaultChecked />
+</FormFieldGroup>
+```
+
+You might want to hide the label text when using the toggle switch variant. Do that by wrapping
+the text in the [ScreenReaderContent](ScreenReaderContent) component.
+
+```js
+---
+type: example
+---
+<Checkbox
+  label={<ScreenReaderContent>Screenreader-accessible label</ScreenReaderContent>}
+  value="accessible"
+  variant="toggle"
+/>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Align to the left side of the label</Figure.Item>
+    <Figure.Item>Use when multiple selections are allowed</Figure.Item>
+    <Figure.Item>Use to save space from toggles</Figure.Item>
+    <Figure.Item>Stack vertically if there is more than two options to select</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Run more than two checkboxes horizontally</Figure.Item>
+  </Figure>
+</Guidelines>
+```
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>Do not add business logic to `onMouseOver` or `onMouseOut` events. These events are not triggered by keyboard navigation</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/Checkbox/v2/ToggleFacade/index.tsx

@@ -0,0 +1,124 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Component } from 'react'
+
+import {
+  CheckInstUIIcon,
+  XInstUIIcon,
+  renderIconWithProps
+} from '@instructure/ui-icons'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { ToggleFacadeProps } from './props'
+
+/**
+---
+parent: Checkbox
+---
+**/
+@withStyle(generateStyle, 'Toggle')
+class ToggleFacade extends Component<ToggleFacadeProps> {
+  static readonly componentId = 'ToggleFacade'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    checked: false,
+    focused: false,
+    hovered: false,
+    size: 'medium',
+    disabled: false,
+    readOnly: false,
+    labelPlacement: 'end'
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  renderIcon() {
+    const { disabled, readOnly, checked } = this.props
+
+    const getIconColor = () => {
+      if (disabled) {
+        return 'disabledBaseColor'
+      }
+      if (readOnly) {
+        return 'mutedColor'
+      }
+      if (checked) {
+        return 'successColor'
+      }
+      return 'baseColor'
+    }
+
+    const iconColor = getIconColor()
+
+    if (checked) {
+      return renderIconWithProps(CheckInstUIIcon, 'xs', iconColor)
+    } else {
+      return renderIconWithProps(XInstUIIcon, 'xs', iconColor)
+    }
+  }
+
+  renderLabel() {
+    const { children, styles } = this.props
+
+    return <span css={styles?.label}>{children}</span>
+  }
+
+  render() {
+    const { labelPlacement, styles } = this.props
+
+    return (
+      <span css={styles?.toggleFacade} ref={this.handleRef}>
+        {(labelPlacement === 'top' || labelPlacement === 'start') &&
+          this.renderLabel()}
+        <span css={styles?.facade} aria-hidden="true">
+          <span css={styles?.icon}>
+            <span css={styles?.iconToggle}>{this.renderIcon()}</span>
+          </span>
+        </span>
+        {labelPlacement === 'end' && this.renderLabel()}
+      </span>
+    )
+  }
+}
+
+export default ToggleFacade
+export { ToggleFacade }

package/src/Checkbox/v2/ToggleFacade/props.ts

@@ -0,0 +1,67 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+import type { ToggleFacadeTheme } from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+
+type ToggleFacadeOwnProps = {
+  children: React.ReactNode
+  checked?: boolean
+  disabled?: boolean
+  readOnly?: boolean
+  focused?: boolean
+  hovered?: boolean
+  size?: 'small' | 'medium' | 'large'
+  labelPlacement?: 'top' | 'start' | 'end'
+  /**
+   * Indicate if the parent component (`Checkbox`) is invalid to set the style accordingly.
+   */
+  invalid?: boolean
+}
+
+type PropKeys = keyof ToggleFacadeOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ToggleFacadeProps = ToggleFacadeOwnProps &
+  WithStyleProps<ToggleFacadeTheme, ToggleFacadeStyle>
+
+type ToggleFacadeStyle = ComponentStyle<
+  'toggleFacade' | 'facade' | 'icon' | 'iconToggle' | 'label'
+>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'checked',
+  'disabled',
+  'readOnly',
+  'focused',
+  'hovered',
+  'size',
+  'labelPlacement',
+  'invalid'
+]
+
+export type { ToggleFacadeProps, ToggleFacadeStyle }
+export { allowedProps }