@ohos-ports/instructure-ui-toggle-details 11.7.5-beta.1

package/src/ToggleGroup/v1/props.ts

@@ -0,0 +1,115 @@
+/*
+ * 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 {
+  AsElementType,
+  OtherHTMLAttributes,
+  Renderable,
+  ToggleGroupTheme
+} from '@instructure/shared-types'
+
+import type { WithStyleProps } from '@instructure/emotion'
+
+type ToggleGroupOwnProps = {
+  /**
+   * the content to show and hide
+   */
+  children: React.ReactNode
+  /**
+   * the content area next to the toggle button
+   */
+  summary: React.ReactNode
+  /**
+   * provides a screenreader label for the toggle button
+   * (takes `expanded` as an argument if a function)
+   */
+  toggleLabel: React.ReactNode | ((expanded: boolean) => React.ReactNode)
+  /**
+   * the element type to render as
+   */
+  as?: AsElementType
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+  size?: 'small' | 'medium' | 'large'
+  /**
+   * Whether the content is expanded or hidden
+   */
+  expanded?: boolean // TODO: controllable(PropTypes.bool, 'onToggle', 'defaultExpanded')
+  /**
+   * Whether the content is initially expanded or hidden (uncontrolled)
+   */
+  defaultExpanded?: boolean
+  /**
+   * Fired when the content display is toggled
+   */
+  onToggle?: (event: React.MouseEvent, expanded: boolean) => void
+  /**
+   * The icon displayed in the toggle button when the content is hidden
+   */
+  icon?: Renderable
+  /**
+   * The icon displayed in the toggle button when the content is showing
+   */
+  iconExpanded?: Renderable
+  /**
+   * Transition content into view
+   */
+  transition?: boolean
+  /**
+   * Toggle the border around the component
+   */
+  border?: boolean
+}
+
+type PropKeys = keyof ToggleGroupOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ToggleGroupStyle = { borderColor: string }
+
+type ToggleGroupProps = ToggleGroupOwnProps &
+  OtherHTMLAttributes<ToggleGroupOwnProps> &
+  WithStyleProps<ToggleGroupTheme, ToggleGroupStyle>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'summary',
+  'toggleLabel',
+  'as',
+  'elementRef',
+  'size',
+  'expanded',
+  'defaultExpanded',
+  'onToggle',
+  'icon',
+  'iconExpanded',
+  'transition',
+  'border'
+]
+
+export type { ToggleGroupProps, ToggleGroupStyle }
+export { allowedProps }

package/src/ToggleGroup/v1/styles.ts

@@ -0,0 +1,47 @@
+/*
+ * 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 { ToggleGroupTheme } from '@instructure/shared-types'
+import type { ToggleGroupProps, ToggleGroupStyle } 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: ToggleGroupTheme,
+  _props: ToggleGroupProps
+): ToggleGroupStyle => {
+  return {
+    borderColor: componentTheme.borderColor
+  }
+}
+
+export default generateStyle

package/src/ToggleGroup/v1/theme.ts

@@ -0,0 +1,43 @@
+/*
+ * 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 { ToggleGroupTheme } from '@instructure/shared-types'
+
+/**
+ * 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): ToggleGroupTheme => {
+  const { colors } = theme
+
+  const componentVariables: ToggleGroupTheme = {
+    borderColor: colors?.contrasts?.grey3045
+  }
+  return {
+    ...componentVariables
+  }
+}
+export default generateComponentTheme

package/src/ToggleGroup/v2/README.md

@@ -0,0 +1,93 @@
+---
+describes: ToggleGroup
+---
+
+Performs the same function as [`ToggleDetails`](ToggleDetails), but with the summary separated from the
+toggle button, and built in padding and borders around the summary and main content area.
+
+### Basic example
+
+```javascript
+---
+type: example
+---
+<ToggleGroup
+  toggleLabel="This is the toggle button label for screenreaders"
+  summary="This is the summary"
+  background="default"
+>
+  <View display="block" padding="general.spaceMd">Here is the expanded content</View>
+</ToggleGroup>
+```
+
+### More detailed examples
+
+#### `defaultExpanded` to make the component `expanded` when it renders
+
+```javascript
+---
+type: example
+---
+<ToggleGroup
+  toggleLabel="This is the toggle button label for screenreaders"
+  summary="This is the summary"
+  defaultExpanded
+>
+  <View display="block" padding="general.spaceMd">This content is expanded when the component renders</View>
+</ToggleGroup>
+```
+
+#### Passing in your own `icon` and `iconExpanded`
+
+```javascript
+---
+type: example
+---
+<ToggleGroup
+  toggleLabel="This is the toggle button label for screenreaders"
+  summary="This is the summary"
+  iconExpanded={XInstUIIcon}
+  icon={PlusInstUIIcon}
+>
+  <View display="block" padding="general.spaceMd">Here is the expanded content</View>
+</ToggleGroup>
+```
+
+#### Disable default transition of details
+
+```javascript
+---
+type: example
+---
+<ToggleGroup
+  transition={false}
+  toggleLabel="This is the toggle button label for screenreaders"
+  summary="This is the summary"
+>
+  <View display="block" padding="general.spaceMd">This content will not fade in</View>
+</ToggleGroup>
+```
+
+#### Disable default border if you want to nest ToggleGroups
+
+```javascript
+---
+type: example
+---
+<ToggleGroup
+  defaultExpanded
+  toggleLabel="This is the toggle button label for screenreaders"
+  summary={<Heading level="h3">Parent ToggleGroup</Heading>}
+>
+  <ToggleGroup
+    size="small"
+    toggleLabel="This is the toggle button label for screenreaders"
+    summary="I am nested inside a parent ToggleGroup"
+    border={false}
+  >
+    <View display="block" padding="general.spaceMd">
+      This is the details section of the nested ToggleGroup
+    </View>
+  </ToggleGroup>
+</ToggleGroup>
+```

package/src/ToggleGroup/v2/index.tsx

@@ -0,0 +1,214 @@
+/*
+ * 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 {
+  omitProps,
+  pickProps,
+  getElementType
+} from '@instructure/ui-react-utils'
+import { IconButton } from '@instructure/ui-buttons/latest'
+import { Transition } from '@instructure/ui-motion'
+import { Expandable } from '@instructure/ui-expandable/latest'
+import type { ExpandableToggleProps } from '@instructure/ui-expandable/latest'
+import { isActiveElement } from '@instructure/ui-dom-utils'
+import { Flex } from '@instructure/ui-flex/latest'
+import { View } from '@instructure/ui-view/latest'
+import {
+  ChevronRightInstUIIcon,
+  ChevronDownInstUIIcon,
+  renderIconWithProps
+} from '@instructure/ui-icons'
+import type { ToggleGroupProps } from './props'
+import { allowedProps } from './props.js'
+
+import { withStyleNew } from '@instructure/emotion'
+
+import generateStyle from './styles.js'
+
+const toggleGroupSizeToIconSize = {
+  small: 'md',
+  medium: 'md',
+  large: 'lg'
+} as const
+
+/**
+---
+category: components
+---
+**/
+@withStyleNew(generateStyle)
+class ToggleGroup extends Component<ToggleGroupProps> {
+  static displayName = 'ToggleGroup'
+  static readonly componentId = 'ToggleGroup'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    size: 'medium',
+    icon: ChevronRightInstUIIcon,
+    iconExpanded: ChevronDownInstUIIcon,
+    defaultExpanded: false,
+    transition: true,
+    as: 'span',
+    border: true
+  } as const
+
+  ref: Element | null = null
+  _button: HTMLElement | null = null
+  _shouldTransition = false
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  handleButtonRef = (el: Element | null) => {
+    this._button = el as HTMLElement
+  }
+
+  get focused() {
+    return isActiveElement(this._button)
+  }
+
+  focus() {
+    this._button?.focus()
+  }
+
+  componentDidMount() {
+    this._shouldTransition = true
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.(this.state)
+  }
+
+  renderIcon(expanded: boolean) {
+    const Icon = expanded ? this.props.iconExpanded : this.props.icon
+    if (!Icon) return null
+
+    const iconSize = toggleGroupSizeToIconSize[this.props.size!]
+    return renderIconWithProps(Icon, iconSize, 'baseColor')
+  }
+
+  renderToggle(
+    toggleProps: ReturnType<ExpandableToggleProps>,
+    expanded: boolean
+  ) {
+    const { toggleLabel, size } = this.props
+    let label
+    if (typeof toggleLabel === 'function') {
+      label = toggleLabel(expanded)
+    } else {
+      label = toggleLabel
+    }
+
+    const props = { ...toggleProps } as Record<string, any>
+    return (
+      <IconButton
+        {...props}
+        withBackground={false}
+        withBorder={false}
+        size={size === 'large' ? 'medium' : 'small'}
+        elementRef={this.handleButtonRef}
+        screenReaderLabel={label}
+      >
+        {this.renderIcon(expanded)}
+      </IconButton>
+    )
+  }
+
+  renderDetails(detailsProps: { id: string }) {
+    const { styles } = this.props
+    return (
+      <View
+        {...detailsProps}
+        display="block"
+        borderWidth="small none none none"
+        borderColor={styles?.borderColor}
+      >
+        {this.props.transition && this._shouldTransition ? (
+          <Transition transitionOnMount in type="fade">
+            {this.props.children}
+          </Transition>
+        ) : (
+          this.props.children
+        )}
+      </View>
+    )
+  }
+
+  render() {
+    const Element = getElementType(ToggleGroup, this.props)
+    const { styles } = this.props
+    return (
+      <Expandable {...pickProps(this.props, Expandable.allowedProps)}>
+        {({ expanded, getToggleProps, getDetailsProps }) => {
+          return (
+            <View
+              {...omitProps(this.props, ToggleGroup.allowedProps)}
+              borderWidth={this.props.border ? 'small' : 'none'}
+              as={Element}
+              elementRef={this.handleRef}
+              display="block"
+              borderRadius="medium"
+              background="primary"
+              borderColor={styles?.borderColor}
+              data-cid="ToggleGroup"
+            >
+              <Flex
+                padding={
+                  this.props.size === 'small'
+                    ? 'x-small'
+                    : 'small small small x-small'
+                }
+              >
+                <Flex.Item>
+                  {this.renderToggle(getToggleProps(), expanded)}
+                </Flex.Item>
+                <Flex.Item shouldGrow shouldShrink padding="0 0 0 x-small">
+                  {this.props.summary}
+                </Flex.Item>
+              </Flex>
+              {expanded ? (
+                this.renderDetails(getDetailsProps())
+              ) : (
+                <span {...getDetailsProps()} />
+              )}
+            </View>
+          )
+        }}
+      </Expandable>
+    )
+  }
+}
+
+export default ToggleGroup
+export { ToggleGroup }

package/src/ToggleGroup/v2/props.ts

@@ -0,0 +1,115 @@
+/*
+ * 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 {
+  AsElementType,
+  OtherHTMLAttributes,
+  Renderable
+} from '@instructure/shared-types'
+
+import type { WithStyleProps } from '@instructure/emotion'
+import type { NewComponentTypes } from '@instructure/ui-themes'
+
+type ToggleGroupOwnProps = {
+  /**
+   * the content to show and hide
+   */
+  children: React.ReactNode
+  /**
+   * the content area next to the toggle button
+   */
+  summary: React.ReactNode
+  /**
+   * provides a screenreader label for the toggle button
+   * (takes `expanded` as an argument if a function)
+   */
+  toggleLabel: React.ReactNode | ((expanded: boolean) => React.ReactNode)
+  /**
+   * the element type to render as
+   */
+  as?: AsElementType
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+  size?: 'small' | 'medium' | 'large'
+  /**
+   * Whether the content is expanded or hidden
+   */
+  expanded?: boolean // TODO: controllable(PropTypes.bool, 'onToggle', 'defaultExpanded')
+  /**
+   * Whether the content is initially expanded or hidden (uncontrolled)
+   */
+  defaultExpanded?: boolean
+  /**
+   * Fired when the content display is toggled
+   */
+  onToggle?: (event: React.MouseEvent, expanded: boolean) => void
+  /**
+   * The icon displayed in the toggle button when the content is hidden
+   */
+  icon?: Renderable
+  /**
+   * The icon displayed in the toggle button when the content is showing
+   */
+  iconExpanded?: Renderable
+  /**
+   * Transition content into view
+   */
+  transition?: boolean
+  /**
+   * Toggle the border around the component
+   */
+  border?: boolean
+}
+
+type PropKeys = keyof ToggleGroupOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ToggleGroupStyle = { borderColor: string }
+
+type ToggleGroupProps = ToggleGroupOwnProps &
+  OtherHTMLAttributes<ToggleGroupOwnProps> &
+  WithStyleProps<ReturnType<NewComponentTypes['ToggleGroup']>, ToggleGroupStyle>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'summary',
+  'toggleLabel',
+  'as',
+  'elementRef',
+  'size',
+  'expanded',
+  'defaultExpanded',
+  'onToggle',
+  'icon',
+  'iconExpanded',
+  'transition',
+  'border'
+]
+
+export type { ToggleGroupProps, ToggleGroupStyle }
+export { allowedProps }

package/src/ToggleGroup/v2/styles.ts

@@ -0,0 +1,47 @@
+/*
+ * 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 } from '@instructure/ui-themes'
+import type { ToggleGroupProps, ToggleGroupStyle } 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: ReturnType<NewComponentTypes['ToggleGroup']>,
+  _props: ToggleGroupProps
+): ToggleGroupStyle => {
+  return {
+    borderColor: componentTheme.borderColor
+  }
+}
+
+export default generateStyle