@instructure/ui-color-picker 8.25.1-snapshot-20

package/src/ColorPicker/props.ts

@@ -0,0 +1,293 @@
+/*
+ * 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 PropTypes from 'prop-types'
+
+import type { FormMessage } from '@instructure/ui-form-field'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  ColorPickerTheme,
+  OtherHTMLAttributes,
+  PropValidators
+} from '@instructure/shared-types'
+
+type ContrastStrength = 'min' | 'mid' | 'max'
+type MessageType = Array<FormMessage>
+
+type ColorPickerOwnProps = {
+  /**
+   * Configures the contrast checker. If false, there will be no checking.
+   *
+   *
+   * isStrict: if it's true, it will display an error if false, a warning
+   *
+   * contrastStrength: can be one of ('min','mid','max'), which translates to 3:1, 4.5:1, 7:1 contrast, defalts to 'mid'
+   *
+   * contrastAgainst: is the color which the component checks the contrast against. Accepts hex, defaults to #ffffff
+   *
+   * renderContrastSuccessMessage: if set and the contrast is high enough, it will display the message
+   *
+   * renderContrastErrorMessage: if set and the contrast is not high enough, it will display the message
+   *
+   *
+   * MessageType: Array<{
+   *   type: 'success' | 'hint' | 'error' | 'screenreader-only'
+   *   text: string
+   * }>
+   */
+  checkContrast?: {
+    isStrict: boolean
+    contrastStrength?: ContrastStrength
+    contrastAgainst?: string
+    renderContrastSuccessMessage?: (
+      contrast: number,
+      minContrast: number
+    ) => MessageType
+
+    renderContrastErrorMessage?: (
+      contrast: number,
+      minContrast: number
+    ) => MessageType
+  }
+
+  /**
+   * If set, the default popover will appear for the picker. Those components whose corresponding keys aren't provided (e.g. `colorMixer`, `colorPreset` or `colorContrast`)
+   * will not be rendered.
+   */
+  colorMixerSettings?: {
+    popoverAddButtonLabel: string
+    popoverCloseButtonLabel: string
+    colorMixer?: {
+      withAlpha: boolean
+      rgbRedInputScreenReaderLabel: string
+      rgbGreenInputScreenReaderLabel: string
+      rgbBlueInputScreenReaderLabel: string
+      rgbAlphaInputScreenReaderLabel: string
+      colorSliderNavigationExplanationScreenReaderLabel: string
+      alphaSliderNavigationExplanationScreenReaderLabel: string
+      colorPaletteNavigationExplanationScreenReaderLabel: string
+    }
+    colorPreset?: {
+      colors: Array<string>
+      label: string
+    }
+    colorContrast?: {
+      firstColor: string
+      label: string
+      successLabel: string
+      failureLabel: string
+      normalTextLabel: string
+      largeTextLabel: string
+      graphicsTextLabel: string
+      firstColorLabel: string
+      secondColorLabel: string
+    }
+  }
+  /**
+   * If a child function is provided, the component will render it to the popover.
+   */
+  children?: (
+    value: string,
+    onChange: (hex: string) => void,
+    handleAdd: () => void,
+    handleClose: () => void
+  ) => Node
+  /**
+   * Sets the input to disabled state
+   */
+  disabled?: boolean
+
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef: (element: Element | null) => void
+
+  /**
+   * If true, it will display a red error ring or a message after a blur event and remove it after a change event
+   */
+  isRequired?: boolean
+
+  /**
+   * The label of the component
+   */
+  label: string
+
+  /**
+   * If 'value' is set, this must be set. It'll be called on every change
+   */
+  onChange?: (value: string) => void
+
+  /**
+   * Placeholder for the inputfield
+   */
+  placeholderText: string
+  /**
+   * If set, it will set the popover's max height. Useful when the popover is too big
+   */
+  popoverMaxHeight?: string
+  /**
+   * Sets the ScreenReaderLabel for the popover
+   */
+  popoverScreenReaderLabel?: string
+  /**
+   * Sets the ScreenReaderLabel for the popover Button
+   */
+  popoverButtonScreenReaderLabel?: string
+  /**
+   * If set and the hex is invalid, it will display the message after a blur event and remove it after a change event
+   *
+   * MessageType: Array<{
+   *   type: 'success' | 'hint' | 'error' | 'screenreader-only'
+   *   text: string
+   * }>
+   */
+  renderInvalidColorMessage?: (hexCode: string) => MessageType
+
+  /**
+   * If set, isRequired is true and the input is empty, it will display the message after a blur event and remove it after a change event
+   *
+   * MessageType: Array<{
+   *   type: 'success' | 'hint' | 'error' | 'screenreader-only'
+   *   text: string
+   * }>
+   */
+  renderIsRequiredMessage?: () => MessageType
+
+  /**
+   * If set, it will display the message it returns
+   *
+   * MessageType: Array<{
+   *   type: 'success' | 'hint' | 'error' | 'screenreader-only'
+   *   text: string
+   * }>
+   */
+  renderMessages?: (
+    hexCode: string,
+    isValidHex: boolean,
+    minContrast: number,
+    contrast?: number
+  ) => MessageType
+
+  /**
+   * If set, an info icon with a tooltip will be displayed
+   */
+  tooltip?: React.ReactNode
+
+  /**
+   * If set, the component will behave as controlled
+   */
+  value?: string
+
+  /**
+   * The width of the input.
+   */
+  width?: string
+  /**
+   * If true, alpha slider will be rendered. Deafults to false
+   */
+  withAlpha?: boolean
+}
+
+type ColorPickerState = {
+  hexCode: string
+  showHelperErrorMessages: boolean
+  openColorPicker: boolean
+  mixedColor: string
+}
+
+type PropKeys = keyof ColorPickerOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ColorPickerProps = ColorPickerOwnProps &
+  WithStyleProps<ColorPickerTheme, ColorPickerStyle> &
+  OtherHTMLAttributes<ColorPickerOwnProps>
+
+type ColorPickerStyle = ComponentStyle<
+  | 'colorPicker'
+  | 'simpleColorContainer'
+  | 'hashMarkContainer'
+  | 'errorIcons'
+  | 'successIcon'
+  | 'label'
+  | 'popoverContent'
+  | 'popoverContentBlock'
+  | 'popoverFooter'
+  | 'colorMixerButtonContainer'
+  | 'popoverContentContainer'
+  | 'colorMixerButtonWrapper'
+>
+
+const propTypes: PropValidators<PropKeys> = {
+  checkContrast: PropTypes.oneOfType([PropTypes.bool, PropTypes.object]),
+  colorMixerSettings: PropTypes.object,
+  children: PropTypes.func,
+  disabled: PropTypes.bool,
+  elementRef: PropTypes.func,
+  isRequired: PropTypes.bool,
+  label: PropTypes.node,
+  onChange: PropTypes.func,
+  placeholderText: PropTypes.string,
+  popoverScreenReaderLabel: PropTypes.string,
+  popoverButtonScreenReaderLabel: PropTypes.string,
+  popoverMaxHeight: PropTypes.string,
+  renderInvalidColorMessage: PropTypes.func,
+  renderIsRequiredMessage: PropTypes.func,
+  renderMessages: PropTypes.func,
+  tooltip: PropTypes.node,
+  value: PropTypes.string,
+  width: PropTypes.string,
+  withAlpha: PropTypes.bool
+}
+
+const allowedProps: AllowedPropKeys = [
+  'checkContrast',
+  'colorMixerSettings',
+  'children',
+  'disabled',
+  'elementRef',
+  'isRequired',
+  'label',
+  'onChange',
+  'placeholderText',
+  'popoverScreenReaderLabel',
+  'popoverButtonScreenReaderLabel',
+  'popoverMaxHeight',
+  'renderInvalidColorMessage',
+  'renderIsRequiredMessage',
+  'renderMessages',
+  'tooltip',
+  'value',
+  'width',
+  'withAlpha'
+]
+
+export type {
+  ColorPickerProps,
+  ColorPickerStyle,
+  ColorPickerState,
+  ContrastStrength,
+  MessageType
+}
+export { propTypes, allowedProps }

package/src/ColorPicker/styles.ts

@@ -0,0 +1,131 @@
+/*
+ * 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 { ColorPickerTheme } from '@instructure/shared-types'
+
+import type {
+  ColorPickerProps,
+  ColorPickerState,
+  ColorPickerStyle
+} 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} 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: ColorPickerTheme,
+  props: ColorPickerProps,
+  state: ColorPickerState & { isSimple: boolean }
+): ColorPickerStyle => {
+  const { hashMarkColor, errorIconColor, warningIconColor, successIconColor } =
+    componentTheme
+  const { checkContrast, popoverMaxHeight } = props
+  const { isSimple } = state
+
+  return {
+    colorPicker: {
+      label: 'colorPicker',
+      display: 'flex'
+    },
+    simpleColorContainer: {
+      label: 'colorPicker__simpleColorContainer',
+      display: 'flex',
+      paddingLeft: componentTheme.simpleColorContainerLeftPadding,
+      alignItems: 'center'
+    },
+    hashMarkContainer: {
+      label: 'colorPicker__hashMarkContainer',
+      color: hashMarkColor,
+      display: 'inline-block',
+      fontSize: '1rem',
+      lineHeight: componentTheme.hashMarkContainerLineHeight,
+      ...(isSimple
+        ? {
+            paddingInlineStart: componentTheme.hashMarkContainerLeftPadding,
+            paddingInlineEnd: componentTheme.hashMarkContainerRightPadding
+          }
+        : {})
+    },
+    errorIcons: {
+      label: 'colorPicker__errorIcons',
+      display: 'flex',
+      paddingInlineEnd: componentTheme.errorIconsRightPadding,
+      color: checkContrast?.isStrict ? errorIconColor : warningIconColor
+    },
+    successIcon: {
+      label: 'colorPicker__successIcon',
+      display: 'flex',
+      paddingInlineEnd: componentTheme.successIconRightPadding,
+      color: successIconColor
+    },
+    label: {
+      label: 'colorPicker__label',
+      marginInlineEnd: componentTheme.labelRightMargin
+    },
+    popoverContent: {
+      label: 'colorPicker__popoverContent',
+      padding: componentTheme.popoverContentPadding
+    },
+    popoverContentBlock: {
+      label: 'colorPicker__popoverContentBlock',
+      borderTop: 'solid',
+      borderWidth: componentTheme.popoverContentBlockBorderWidth,
+      borderColor: componentTheme.popoverSeparatorColor,
+      marginTop: componentTheme.popoverContentBlockTopMargin,
+      marginBottom: componentTheme.popoverContentBlockBottomMargin
+    },
+    popoverFooter: {
+      label: 'colorPicker__popoverFooter',
+      backgroundColor: componentTheme.popoverFooterColor,
+      display: 'flex',
+      justifyContent: 'flex-end',
+      padding: componentTheme.popoverFooterPadding,
+      borderTop: `solid ${componentTheme.popoverFooterTopBorderWidth}`,
+      borderColor: componentTheme.popoverSeparatorColor
+    },
+    colorMixerButtonContainer: {
+      label: 'colorPicker__colorMixerButtonContainer',
+      alignSelf: 'flex-end',
+      marginInlineStart: componentTheme.colorMixerButtonContainerLeftMargin
+    },
+    popoverContentContainer: {
+      label: 'colorPicker__popoverContentContainer',
+      maxHeight: popoverMaxHeight || '100vh',
+      overflow: 'scroll'
+    },
+    colorMixerButtonWrapper: {
+      position: 'absolute',
+      top: '2.69rem'
+    }
+  }
+}
+
+export default generateStyle

package/src/ColorPicker/theme.ts

@@ -0,0 +1,80 @@
+/*
+ * 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 { Theme } from '@instructure/ui-themes'
+import type { ColorPickerTheme } from '@instructure/shared-types'
+import { colorIndicatorBorderColor } from '../ColorIndicator/theme'
+
+/**
+ * Generates the theme object for the component from the theme and provided additional information
+ * @param  {Object} theme The actual theme object.
+ * @return {Object} The final theme object with the overrides and component variables
+ */
+const generateComponentTheme = (theme: Theme): ColorPickerTheme => {
+  const { colors, borders, spacing, typography } = theme
+
+  const componentVariables = {
+    hashMarkColor: colors?.ash,
+    warningIconColor: colors?.textWarning,
+    errorIconColor: colors?.textDanger,
+    successIconColor: colors?.textSuccess,
+    popoverSeparatorColor: colors?.tiara,
+    popoverFooterColor: colors?.porcelain,
+    smallBorder: borders?.widthSmall,
+    smallSpacing: spacing?.small,
+    xSmallSpacing: spacing?.xSmall,
+    xxSmallSpacing: spacing?.xxSmall,
+    xxxSmallSpacing: spacing?.xxxSmall,
+    xLargeFontSize: typography?.fontSizeXLarge,
+    checkerboardBackgroundColor: colors.white,
+    checkerboardBackgroundImage: `linear-gradient(45deg, ${colors.tiara} 25%, transparent 25%),
+    linear-gradient(-45deg, ${colors.tiara} 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, ${colors.tiara} 75%),
+    linear-gradient(-45deg, transparent 75%, ${colors.tiara} 75%)`,
+    checkerboardBackgroundSize: '.5rem .5rem',
+    checkerboardBackgroundPosition:
+      '0 0, 0 .25rem, .25rem -0.25rem, -0.25rem 0px',
+    colorIndicatorBorderColor,
+    simpleColorContainerLeftPadding: spacing?.xSmall,
+    hashMarkContainerLineHeight: typography?.fontSizeXLarge,
+    hashMarkContainerLeftPadding: spacing?.xSmall,
+    hashMarkContainerRightPadding: spacing?.xxxSmall,
+    errorIconsRightPadding: spacing?.small,
+    successIconRightPadding: spacing?.small,
+    labelRightMargin: spacing?.xxSmall,
+    popoverContentPadding: spacing?.small,
+    popoverContentBlockBorderWidth: borders?.widthSmall,
+    popoverContentBlockTopMargin: spacing?.small,
+    popoverContentBlockBottomMargin: spacing?.small,
+    popoverFooterPadding: spacing?.xSmall,
+    popoverFooterTopBorderWidth: borders?.widthSmall,
+    colorMixerButtonContainerLeftMargin: spacing?.xSmall
+  }
+
+  return {
+    ...componentVariables
+  }
+}
+
+export default generateComponentTheme

package/src/ColorPreset/ColorPresetLocator.ts

@@ -0,0 +1,29 @@
+/*
+ * 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 { locator } from '@instructure/ui-test-locator'
+
+import { ColorPreset } from './index'
+
+// @ts-expect-error ts-migrate(2339) FIXME: Property 'selector' does not exist on type 'typeof... Remove this comment to see the full error message
+export const ColorPresetLocator = locator(ColorPreset.selector)

package/src/ColorPreset/README.md

@@ -0,0 +1,121 @@
+---
+describes: ColorPreset
+---
+
+A component for picking a color from a list of colors. Supports adding new colors either programatically through the `colors` prop, or manually with the built in color picker.
+
+### Color Preset
+
+```js
+---
+render: false
+example: true
+---
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      selected: "",
+      colors: [
+        "#ffffff",
+        "#0CBF94",
+        "#0C89BF00",
+        "#BF0C6D",
+        "#BF8D0C",
+        "#ff0000",
+        "#576A66",
+        "#35423A",
+        "#35423F",
+      ],
+    };
+  }
+
+  render() {
+    return (
+      <div>
+        <ColorPreset
+          label="Choose a color"
+          colors={this.state.colors}
+          selected={this.state.selected}
+          onSelect={(selected) => this.setState({ selected })}
+        />
+      </div>
+    );
+  }
+}
+
+
+render(<Example />);
+
+
+```
+
+### Color Preset (with addition, deletion)
+
+```js
+---
+render: false
+example: true
+---
+class Example extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      selected: "",
+      colors: [
+        "#ffffff",
+        "#0CBF94",
+        "#0C89BF00",
+        "#BF0C6D",
+        "#BF8D0C",
+        "#ff0000",
+        "#576A66",
+        "#35423A",
+        "#35423F",
+      ],
+    };
+  }
+
+  render() {
+    return (
+      <div>
+        <ColorPreset
+          colors={this.state.colors}
+          selected={this.state.selected}
+          onSelect={(selected) => this.setState({ selected })}
+          addNewPresetButtonScreenReaderLabel='Add new color'
+          colorMixerSettings={{
+            addNewPresetButtonScreenReaderLabel:'Add new preset button label',
+            onPresetChange:(colors) => this.setState({ colors }),
+            colorMixer:{
+              rgbRedInputScreenReaderLabel:'Input field for red',
+              rgbGreenInputScreenReaderLabel:'Input field for green',
+              rgbBlueInputScreenReaderLabel:'Input field for blue',
+              rgbAlphaInputScreenReaderLabel:'Input field for alpha',
+              colorSliderNavigationExplanationScreenReaderLabel:`You are on a color slider. To navigate the slider left or right, use the 'A' and 'D' buttons respectively`,
+              alphaSliderNavigationExplanationScreenReaderLabel:`You are on an alpha slider. To navigate the slider left or right, use the 'A' and 'D' buttons respectively`,
+              colorPaletteNavigationExplanationScreenReaderLabel:`You are on a color palette. To navigate on the palette up, left, down or right, use the 'W', 'A', 'S' and 'D' buttons respectively`
+            },
+            colorContrast:{
+                firstColor:"#FF0000",
+                secondColor:"#FFFF00",
+                label:"Color Contrast Ratio",
+                successLabel:"PASS",
+                failureLabel:"FAIL",
+                normalTextLabel:"Normal text",
+                largeTextLabel:"Large text",
+                graphicsTextLabel:"Graphics text",
+                firstColorLabel:"Background",
+                secondColorLabel:"Foreground",
+            }
+          }}
+        />
+      </div>
+    );
+  }
+}
+
+render(<Example />);
+
+
+```