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

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@ohos-ports/instructure-ui-toggle-details",
+  "version": "11.7.5-beta.1",
+  "description": "A styled toggleable, accordion-like component.",
+  "author": "Instructure, Inc. Engineering and Product Design",
+  "module": "./es/index.js",
+  "main": "./lib/index.js",
+  "types": "./types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/instructure-ui-toggle-details/11.7.5"
+  },
+  "homepage": "https://instructure.github.io/instructure-ui/",
+  "bugs": {
+    "url": "https://github.com/ohos-ports/ohos-ports/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@babel/runtime": "^7.29.7",
+    "@instructure/emotion": "11.7.5",
+    "@instructure/ui-buttons": "11.7.5",
+    "@instructure/shared-types": "11.7.5",
+    "@instructure/ui-dom-utils": "11.7.5",
+    "@instructure/ui-expandable": "11.7.5",
+    "@instructure/ui-flex": "11.7.5",
+    "@instructure/ui-icons": "11.7.5",
+    "@instructure/ui-motion": "11.7.5",
+    "@instructure/ui-react-utils": "11.7.5",
+    "@instructure/ui-utils": "11.7.5",
+    "@instructure/ui-view": "11.7.5",
+    "@instructure/uid": "11.7.5",
+    "@instructure/ui-themes": "11.7.5"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "vitest": "^4.1.9",
+    "@instructure/ui-axe-check": "11.7.5",
+    "@instructure/ui-babel-preset": "11.7.5"
+  },
+  "peerDependencies": {
+    "react": ">=18 <=19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./es/*": "./es/*",
+    "./types/*": "./types/*",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*",
+    ".": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_6": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_7": {
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    },
+    "./latest": {
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    }
+  },
+  "scripts": {
+    "lint": "ui-scripts lint",
+    "lint:fix": "ui-scripts lint --fix",
+    "clean": "ui-scripts clean",
+    "build": "ui-scripts build --modules es,cjs",
+    "build:watch": "pnpm run ts:check -- --watch & ui-scripts build --watch",
+    "build:types": "tsc -p tsconfig.build.json",
+    "ts:check": "tsc -p tsconfig.build.json --noEmit --emitDeclarationOnly false"
+  }
+}

package/src/ToggleDetails/v1/README.md

@@ -0,0 +1,233 @@
+---
+describes: ToggleDetails
+---
+
+The ToggleDetails component can be used to show/hide content in response to user action.
+
+By default, ToggleDetails content is hidden. To override, pass in the `defaultExpanded` prop.
+
+```js
+---
+type: example
+---
+<ToggleDetails
+  summary="Click to hide me!"
+  defaultExpanded
+>
+  <Text weight="bold">I am expanded!</Text> {lorem.paragraph()}
+</ToggleDetails>
+```
+
+ToggleDetails can be controlled:
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [expanded, setExpanded] = useState(true)
+
+  const handleChange = (event, expanded) => {
+    setExpanded(expanded)
+  }
+
+  const handleToggle = () => {
+    setExpanded((prevExpanded) => !prevExpanded)
+  }
+
+  return (
+    <div>
+      <Button onClick={handleToggle}>
+        <div aria-live="polite">
+          This Button {expanded ? 'Collapses' : 'Expands'}
+        </div>
+      </Button>
+      <br />
+      <br />
+      <ToggleDetails
+        summary="Click to hide me!"
+        expanded={expanded}
+        onToggle={handleChange}
+      >
+        <Text weight="bold">I am controlled and expanded!</Text>
+        {lorem.paragraph()}
+      </ToggleDetails>
+    </div>
+  )
+}
+
+render(<Example />)
+```
+
+Setting ToggleDetails to `filled` will make the toggle use a full-width [Button](Button) component.
+
+```js
+---
+type: example
+---
+<ToggleDetails
+  variant="filled"
+  summary="Click to expand me!"
+>
+  {lorem.paragraph()}
+</ToggleDetails>
+```
+
+### Icon size / summary text formatting
+
+Icon size can be adjusted using the `size` prop with small, medium, and large options.
+
+The `summary` prop accepts any node, allowing you to format the summary text as
+you see fit. In these examples, we are formatting it with the
+[Text](Text) component.
+
+```js
+---
+type: example
+---
+<div>
+  <ToggleDetails
+    size="small"
+    summary="Small icon"
+  >
+    {lorem.paragraph()}
+  </ToggleDetails>
+
+  <br />
+
+  <ToggleDetails summary="Medium icon">
+    {lorem.paragraph()}
+  </ToggleDetails>
+
+  <br />
+
+  <ToggleDetails
+    size="large"
+    summary="Large icon"
+  >
+    {lorem.paragraph()}
+  </ToggleDetails>
+</div>
+```
+
+### Icon positioning and block display
+
+The `iconPosition` prop determines if the icon comes before or after the summary.
+
+When the `fluidWidth` prop is set, the toggle fills the width of its
+container.
+
+```js
+---
+type: example
+---
+<ToggleDetails
+  summary="Block display"
+  iconPosition="end"
+  defaultExpanded
+  fluidWidth
+>
+  <Text>
+    {lorem.paragraph()}
+  </Text>
+</ToggleDetails>
+```
+
+### Example to demonstrate more properties
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [state, setState] = useState({
+    expanded: true,
+    fluidWidth: true,
+    iconPosition: 'start',
+    size: 'small',
+    variant: 'default'
+  });
+
+  const handleChange = (field, value) => setState(prevState => ({ ...prevState, [field]: value }));
+  const handleToggle = () => setState(prevState => ({ ...prevState, expanded: !prevState.expanded }));
+
+  const renderOptions = () => {
+    const { fluidWidth, iconPosition, size, variant } = state;
+    const options = [
+      { name: 'iconPosition', values: ['start', 'end'] },
+      { name: 'size', values: ['small', 'medium', 'large'] },
+      { name: 'variant', values: ['default', 'filled'] },
+    ];
+
+    return (
+      <Flex alignItems="start">
+        {options.map(({ name, values }) => (
+          <Flex.Item margin="small" key={name}>
+            <RadioInputGroup
+              name={name}
+              description={name}
+              value={state[name]}
+              onChange={(e, value) => handleChange(name, value)}
+            >
+              {values.map(val => (
+                <RadioInput label={val} value={val} key={val} />
+              ))}
+            </RadioInputGroup>
+          </Flex.Item>
+        ))}
+        <Flex.Item margin="small">
+          <Checkbox
+            label="fluidWidth"
+            checked={fluidWidth}
+            onChange={() => handleChange('fluidWidth', !fluidWidth)}
+          />
+        </Flex.Item>
+      </Flex>
+    );
+  };
+
+  const { expanded, iconPosition, size, variant, fluidWidth } = state;
+
+  return (
+    <div>
+      {renderOptions()}
+      <Button onClick={handleToggle}>
+        This Button {expanded ? 'Collapses' : 'Expands'}
+      </Button>
+      <br />
+      <br />
+      <ToggleDetails
+        summary="Click to hide me!"
+        expanded={expanded}
+        onToggle={(_, expanded) => handleChange('expanded', expanded)}
+        fluidWidth={fluidWidth}
+        iconPosition={iconPosition}
+        size={size}
+        variant={variant}
+      >
+        <Text weight="bold">
+          I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!I am controlled and expanded!
+        </Text>
+      </ToggleDetails>
+    </div>
+  );
+};
+
+render(<Example />)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Use ToggleDetails when descriptive text is longer than a short phrase</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Nest ToggleDetails within another ToggleDetails</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/ToggleDetails/v1/index.tsx

@@ -0,0 +1,204 @@
+/*
+ * 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, createRef } from 'react'
+import { Button } from '@instructure/ui-buttons/v11_6'
+import {
+  IconArrowOpenEndSolid,
+  IconArrowOpenDownSolid
+} from '@instructure/ui-icons'
+import { Expandable } from '@instructure/ui-expandable'
+import { omitProps, pickProps } from '@instructure/ui-react-utils'
+import { isActiveElement } from '@instructure/ui-dom-utils'
+
+import { withStyle } from '@instructure/emotion'
+import generateStyle from './styles.js'
+import generateComponentTheme from './theme.js'
+import type { ToggleDetailsProps } from './props'
+import { allowedProps } from './props.js'
+import type { ExpandableToggleProps } from '@instructure/ui-expandable'
+import type { ViewProps } from '@instructure/ui-view/v11_6'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle, generateComponentTheme)
+class ToggleDetails extends Component<ToggleDetailsProps> {
+  static displayName = 'ToggleDetails'
+  static readonly componentId = 'ToggleDetails'
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    variant: 'default',
+    size: 'medium',
+    fluidWidth: false,
+    icon: IconArrowOpenEndSolid,
+    iconExpanded: IconArrowOpenDownSolid,
+    iconPosition: 'start',
+    defaultExpanded: false,
+    children: null
+  }
+
+  _buttonNode: HTMLElement | null = null
+  ref = createRef<HTMLDivElement>()
+
+  // TODO this solution was generated with Gemini, should be tested if it works as fine as before
+  setButtonRef = (node: Element | null) => {
+    this._buttonNode = node as HTMLElement | null
+  }
+
+  get focused() {
+    return isActiveElement(this._buttonNode)
+  }
+
+  focus() {
+    this._buttonNode?.focus()
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  renderSummary(expanded: boolean) {
+    const { summary, iconPosition } = this.props
+
+    return (
+      <span css={this.props.styles?.summary}>
+        {iconPosition === 'start' && this.renderIcon(expanded)}
+        <span css={this.props.styles?.summaryText}>{summary}</span>
+        {iconPosition === 'end' && this.renderIcon(expanded)}
+      </span>
+    )
+  }
+
+  renderToggle(
+    toggleProps: ReturnType<ExpandableToggleProps>,
+    expanded: boolean
+  ) {
+    const { variant } = this.props
+    const tProps = this.props.children
+      ? toggleProps
+      : { onClick: toggleProps.onClick }
+    const props = {
+      ...omitProps(this.props, ToggleDetails.allowedProps),
+      ...tProps,
+      children: this.renderSummary(expanded)
+    } as Record<string, unknown>
+    const summary = this.renderSummary(expanded)
+
+    if (variant === 'filled') {
+      return (
+        <Button
+          {...props}
+          display="block"
+          textAlign="start"
+          elementRef={this.setButtonRef}
+        >
+          {summary}
+        </Button>
+      )
+    } else if (props.href) {
+      return (
+        <a {...props} css={this.props.styles?.toggle} ref={this.setButtonRef}>
+          {summary}
+        </a>
+      )
+    } else {
+      return (
+        <button
+          {...props}
+          type="button"
+          css={this.props.styles?.toggle}
+          ref={this.setButtonRef}
+        >
+          {summary}
+        </button>
+      )
+    }
+  }
+
+  renderIcon(expanded: boolean) {
+    const Icon = expanded ? this.props.iconExpanded : this.props.icon
+
+    return this.props.children && Icon ? (
+      <span css={this.props.styles?.icon}>
+        <Icon />
+      </span>
+    ) : null
+  }
+
+  renderDetails(expanded: boolean, detailsProps: { id: string }) {
+    if (!this.props.children) return null
+    const expandedStyles = expanded ? { display: 'block' } : { display: 'none' }
+    return (
+      <div {...detailsProps} css={[this.props.styles?.details, expandedStyles]}>
+        {expanded && this.renderContent()}
+      </div>
+    )
+  }
+
+  renderContent() {
+    return <div css={this.props.styles?.content}>{this.props.children}</div>
+  }
+
+  handleToggle = (
+    event: React.KeyboardEvent<ViewProps> | React.MouseEvent<ViewProps>,
+    expanded: boolean
+  ) => {
+    if (typeof this.props.onToggle === 'function') {
+      this.props.onToggle(event, expanded)
+    }
+  }
+
+  render() {
+    return (
+      <Expandable
+        {...pickProps(this.props, Expandable.allowedProps)}
+        onToggle={this.handleToggle}
+      >
+        {({ expanded, getToggleProps, getDetailsProps }) => {
+          return (
+            <div
+              css={this.props.styles?.toggleDetails}
+              ref={this.ref}
+              data-cid="ToggleDetails"
+            >
+              {this.renderToggle(getToggleProps(), expanded)}
+              {this.renderDetails(expanded, getDetailsProps())}
+            </div>
+          )
+        }}
+      </Expandable>
+    )
+  }
+}
+
+export default ToggleDetails
+export { ToggleDetails }

package/src/ToggleDetails/v1/props.ts

@@ -0,0 +1,114 @@
+/*
+ * 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 {
+  OtherHTMLAttributes,
+  ToggleDetailsTheme
+} from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type { ViewProps } from '@instructure/ui-view/v11_6'
+
+type ToggleDetailsOwnProps = {
+  variant?: 'default' | 'filled'
+  /**
+   * The summary that displays and can be interacted with
+   */
+  summary: React.ReactNode
+  /**
+   * 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
+  onToggle?: (
+    event: React.KeyboardEvent<ViewProps> | React.MouseEvent<ViewProps>,
+    expanded: boolean
+  ) => void
+  /**
+   * The icon to display next to the summary text when content is hidden
+   */
+  icon?: (...args: any[]) => React.ReactElement
+  /**
+   * The icon to display when content is expanded
+   */
+  iconExpanded?: (...args: any[]) => React.ReactElement
+  /**
+   * Icon position at the start or end of the summary text
+   */
+  iconPosition?: 'start' | 'end'
+  /**
+   * should the summary fill the width of its container
+   */
+  fluidWidth?: boolean
+  /**
+   * Choose a size for the expand/collapse icon
+   */
+  size?: 'small' | 'medium' | 'large'
+  /**
+   * The toggleable content passed inside the ToggleDetails component
+   */
+  children?: React.ReactNode
+}
+
+type PropKeys = keyof ToggleDetailsOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ToggleDetailsProps = ToggleDetailsOwnProps &
+  WithStyleProps<ToggleDetailsTheme, ToggleDetailsStyle> &
+  OtherHTMLAttributes<ToggleDetailsOwnProps>
+
+type ToggleDetailsStyle = ComponentStyle<
+  | 'toggleDetails'
+  | 'summary'
+  | 'summaryText'
+  | 'toggle'
+  | 'icon'
+  | 'details'
+  | 'content'
+>
+
+type ToggleDetailsStyleProps = {
+  animate: boolean
+}
+const allowedProps: AllowedPropKeys = [
+  'variant',
+  'summary',
+  'expanded',
+  'defaultExpanded',
+  'onToggle',
+  'icon',
+  'iconExpanded',
+  'iconPosition',
+  'fluidWidth',
+  'children',
+  'size'
+]
+
+export type { ToggleDetailsProps, ToggleDetailsStyleProps, ToggleDetailsStyle }
+export { allowedProps }