@instructure/ui-drilldown 8.21.1-snapshot.10

package/src/Drilldown/DrilldownOption/index.tsx

@@ -0,0 +1,68 @@
+/*
+ * 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.
+ */
+
+/** @jsx jsx */
+import { Component } from 'react'
+
+import { withStyle } from '@instructure/emotion'
+import { optionsItemThemeGenerator } from '@instructure/ui-options'
+
+import { propTypes, allowedProps } from './props'
+import type { DrilldownOptionProps } from './props'
+
+/**
+---
+parent: Drilldown
+id: Drilldown.Option
+---
+@module DrilldownOption
+@tsProps
+**/
+// needed for listing the available theme variables on docs page,
+// we pass the themeOverrides to Options.Item
+@withStyle(null, optionsItemThemeGenerator)
+class DrilldownOption extends Component<DrilldownOptionProps> {
+  static readonly componentId = 'Drilldown.Option'
+
+  static propTypes = propTypes
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    disabled: false,
+    beforeLabelContentVAlign: 'start',
+    afterLabelContentVAlign: 'start',
+    descriptionRole: 'note',
+    as: 'li',
+    role: 'menuitem'
+  }
+
+  render() {
+    // this component is only used for prop validation. Drilldown.Option children
+    // are parsed in Drilldown and rendered as Options.Item components
+    return null
+  }
+}
+
+export default DrilldownOption
+export { DrilldownOption }

package/src/Drilldown/DrilldownOption/props.ts

@@ -0,0 +1,224 @@
+/*
+ * 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 PropTypes from 'prop-types'
+
+import type {
+  OtherHTMLAttributes,
+  PropValidators,
+  OptionsItemTheme,
+  AsElementType
+} from '@instructure/shared-types'
+import type { WithStyleProps } from '@instructure/emotion'
+import type { OptionsItemProps } from '@instructure/ui-options'
+
+import Drilldown from '../index'
+
+type DrilldownOptionValue = string | number | undefined
+
+type RenderContentVAlign = 'start' | 'center' | 'end'
+
+type DrilldownOptionVariant = Exclude<OptionsItemProps['variant'], 'selected'>
+
+type RenderContentProps = {
+  as: DrilldownOptionOwnProps['as']
+  role: DrilldownOptionOwnProps['role']
+  variant: DrilldownOptionVariant
+  vAlign: RenderContentVAlign
+  isSelected: boolean
+}
+
+type DrilldownOptionOwnProps = {
+  id: string
+
+  /**
+   * Label of the Drilldown option.
+   */
+  children?:
+    | React.ReactNode
+    | ((props: {
+        id: string
+        variant: DrilldownOptionVariant
+        isSelected: boolean
+      }) => React.ReactNode)
+
+  /**
+   * The id of the sub-page the option navigates to.
+   */
+  subPageId?: string
+
+  /**
+   * Is the option disabled.
+   */
+  disabled?: boolean
+
+  /**
+   * The value of the option. Should be set for options in selectable groups.
+   */
+  value?: DrilldownOptionValue
+
+  /**
+   * Providing href will render the option as `<a>`. Doesn't work, if subPageId is provided or is in a selectable group.
+   */
+  href?: string
+
+  /**
+   * Element type to render as. Will be set to `<a>` if href is provided. If the parent is "ul" or "ol", the option is forced to be "li" element.
+   */
+  as?: AsElementType
+
+  /**
+   * The ARIA role of the element
+   */
+  role?: string
+
+  /**
+   * Info content to render after the label.
+   *
+   * If a function is provided, it has a `props` parameter.
+   */
+  renderLabelInfo?:
+    | React.ReactNode
+    | ((props: RenderContentProps) => React.ReactNode)
+
+  /**
+   * Content to render before the label.
+   *
+   * If a function is provided, it has a `props` parameter.
+   */
+  renderBeforeLabel?:
+    | React.ReactNode
+    | ((props: RenderContentProps) => React.ReactNode)
+
+  /**
+   * Content to render after the label.
+   *
+   * If a function is provided, it has a `props` parameter.
+   */
+  renderAfterLabel?:
+    | React.ReactNode
+    | ((props: RenderContentProps) => React.ReactNode)
+
+  /**
+   * Sets the vAlign of renderBeforeLabel content
+   */
+  beforeLabelContentVAlign?: RenderContentVAlign
+
+  /**
+   * Sets the vAlign of renderAfterLabel content and renderLabelInfo
+   */
+  afterLabelContentVAlign?: RenderContentVAlign
+
+  /**
+   * Additional "secondary" description text
+   */
+  description?: React.ReactNode | (() => React.ReactNode)
+
+  /**
+   * The ARIA role of the description element
+   */
+  descriptionRole?: string
+
+  /**
+   * Callback fired when the option is clicked.
+   */
+  onOptionClick?: (
+    event: React.SyntheticEvent,
+    args: {
+      optionId: string
+      drilldown: Drilldown
+      pageHistory: string[]
+      goToPage: (
+        pageId: string
+      ) => { prevPageId: string; newPageId: string } | undefined
+      goToPreviousPage: () =>
+        | { prevPageId: string; newPageId: string }
+        | undefined
+    }
+  ) => void
+
+  /**
+   * Whether the option is selected by default.
+   */
+  defaultSelected?: boolean
+
+  /**
+   * Provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+}
+
+type PropKeys = keyof DrilldownOptionOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type DrilldownOptionProps = DrilldownOptionOwnProps &
+  WithStyleProps<OptionsItemTheme, null> &
+  OtherHTMLAttributes<DrilldownOptionOwnProps>
+
+const propTypes: PropValidators<PropKeys> = {
+  id: PropTypes.string.isRequired,
+  children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  subPageId: PropTypes.string,
+  disabled: PropTypes.bool,
+  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  href: PropTypes.string,
+  as: PropTypes.elementType,
+  role: PropTypes.string,
+  renderLabelInfo: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  renderBeforeLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  renderAfterLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  beforeLabelContentVAlign: PropTypes.oneOf(['start', 'center', 'end']),
+  afterLabelContentVAlign: PropTypes.oneOf(['start', 'center', 'end']),
+  description: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  descriptionRole: PropTypes.string,
+  onOptionClick: PropTypes.func,
+  defaultSelected: PropTypes.bool,
+  elementRef: PropTypes.func
+}
+
+const allowedProps: AllowedPropKeys = [
+  'id',
+  'children',
+  'subPageId',
+  'disabled',
+  'value',
+  'href',
+  'as',
+  'role',
+  'renderLabelInfo',
+  'renderBeforeLabel',
+  'renderAfterLabel',
+  'beforeLabelContentVAlign',
+  'afterLabelContentVAlign',
+  'description',
+  'descriptionRole',
+  'onOptionClick',
+  'defaultSelected',
+  'elementRef'
+]
+
+export type { DrilldownOptionProps, DrilldownOptionValue }
+export { propTypes, allowedProps }

package/src/Drilldown/DrilldownPage/index.tsx

@@ -0,0 +1,58 @@
+/*
+ * 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.
+ */
+
+/** @jsx jsx */
+import { Component } from 'react'
+
+import { propTypes, allowedProps } from './props'
+import type { DrilldownPageProps } from './props'
+
+/**
+---
+parent: Drilldown
+id: Drilldown.Page
+---
+@module DrilldownPage
+@tsProps
+**/
+class DrilldownPage extends Component<DrilldownPageProps> {
+  static readonly componentId = 'Drilldown.Page'
+
+  static propTypes = propTypes
+  static allowedProps = allowedProps
+  static defaultProps = {
+    renderBackButtonLabel: 'Back',
+    disabled: false,
+    withoutHeaderSeparator: false
+  }
+
+  render() {
+    // this component is only used for prop validation.
+    // Drilldown.Page children are parsed in Drilldown.
+    return null
+  }
+}
+
+export default DrilldownPage
+export { DrilldownPage }

package/src/Drilldown/DrilldownPage/props.ts

@@ -0,0 +1,129 @@
+/*
+ * 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 PropTypes from 'prop-types'
+
+import { Children } from '@instructure/ui-prop-types'
+
+import type {
+  OtherHTMLAttributes,
+  PropValidators
+} from '@instructure/shared-types'
+
+import DrilldownGroup from '../DrilldownGroup'
+import DrilldownOption from '../DrilldownOption'
+import DrilldownSeparator from '../DrilldownSeparator'
+
+import type { OptionChild, SeparatorChild, GroupChild } from '../props'
+
+type PageChildren = GroupChild | OptionChild | SeparatorChild
+
+type DrilldownPageOwnProps = {
+  id: string
+
+  /**
+   * Children of type:
+   * `<Drilldown.Option />`, `<Drilldown.Separator />`, `<Drilldown.Group />`
+   */
+  children?: PageChildren | PageChildren[] // TODO: type Children.oneOf([DrilldownOption, DrilldownSeparator, DrilldownGroup ])
+
+  /**
+   * The title of the page displayed in the header
+   */
+  renderTitle?: React.ReactNode | (() => React.ReactNode)
+
+  /**
+   * Label for the optional "action" option in the header (e.g.: "Select all")
+   */
+  renderActionLabel?: React.ReactNode | (() => React.ReactNode)
+
+  /**
+   * Label for the "back" navigation in the header.
+   *
+   * If a function is provided, the first parameter of the function
+   * is the title of the previous page.
+   */
+  renderBackButtonLabel?:
+  | React.ReactNode
+  | ((prevPageTitle?: React.ReactNode) => React.ReactNode)
+
+  /**
+   * Callback fired when the "action" option is clicked in the header
+   */
+  onHeaderActionClicked?: (event: React.SyntheticEvent) => void
+
+  /**
+   * Callback fired when the "back" navigation option is clicked in the header
+   */
+  onBackButtonClicked?: (newPageId: string, prevPageId: string) => void
+
+  /**
+   * Hides the separator under the page header
+   */
+  withoutHeaderSeparator?: boolean
+
+  /**
+   * Is the page disabled
+   */
+  disabled?: boolean
+}
+
+type PropKeys = keyof DrilldownPageOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type DrilldownPageProps = DrilldownPageOwnProps &
+  OtherHTMLAttributes<DrilldownPageOwnProps>
+
+const propTypes: PropValidators<PropKeys> = {
+  id: PropTypes.string.isRequired,
+  children: Children.oneOf([
+    DrilldownOption,
+    DrilldownSeparator,
+    DrilldownGroup
+  ]),
+  renderTitle: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  renderActionLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  renderBackButtonLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  onHeaderActionClicked: PropTypes.func,
+  onBackButtonClicked: PropTypes.func,
+  withoutHeaderSeparator: PropTypes.bool,
+  disabled: PropTypes.bool
+}
+
+const allowedProps: AllowedPropKeys = [
+  'id',
+  'children',
+  'renderTitle',
+  'renderActionLabel',
+  'renderBackButtonLabel',
+  'onHeaderActionClicked',
+  'onBackButtonClicked',
+  'withoutHeaderSeparator',
+  'disabled'
+]
+
+export type { DrilldownPageProps, PageChildren }
+export { propTypes, allowedProps }

package/src/Drilldown/DrilldownSeparator/index.tsx

@@ -0,0 +1,60 @@
+/*
+ * 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.
+ */
+
+/** @jsx jsx */
+import { Component } from 'react'
+
+import { withStyle } from '@instructure/emotion'
+import { optionsSeparatorThemeGenerator } from '@instructure/ui-options'
+
+import { propTypes, allowedProps } from './props'
+import type { DrilldownSeparatorProps } from './props'
+
+/**
+---
+parent: Drilldown
+id: Drilldown.Separator
+---
+@module DrilldownSeparator
+@tsProps
+**/
+// needed for listing the available theme variables on docs page,
+// we pass the themeOverrides to Options.Separator
+@withStyle(null, optionsSeparatorThemeGenerator)
+class DrilldownSeparator extends Component<DrilldownSeparatorProps> {
+  static readonly componentId = 'Drilldown.Separator'
+
+  static propTypes = propTypes
+  static allowedProps = allowedProps
+  static defaultProps = {}
+
+  render() {
+    // this component is only used for prop validation. Drilldown.Separator children
+    // are parsed in Drilldown and rendered as Options.Separator components
+    return null
+  }
+}
+
+export default DrilldownSeparator
+export { DrilldownSeparator }

package/src/Drilldown/DrilldownSeparator/props.ts

@@ -0,0 +1,65 @@
+/*
+ * 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 {
+  OtherHTMLAttributes,
+  PickPropsWithExceptions,
+  PropValidators,
+  AsElementType,
+  OptionsSeparatorTheme
+} from '@instructure/shared-types'
+import type { WithStyleProps } from '@instructure/emotion'
+import type { OptionsSeparatorProps } from '@instructure/ui-options'
+
+type DrilldownSeparatorOwnProps = {
+  id: string
+
+  /**
+   * Element type to render as
+   */
+  as?: AsElementType
+}
+
+type PropKeys = keyof DrilldownSeparatorOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type DrilldownSeparatorProps =
+  // we are passing all props to Options.Separator
+  PickPropsWithExceptions<OptionsSeparatorProps, 'as'> &
+    DrilldownSeparatorOwnProps &
+    WithStyleProps<OptionsSeparatorTheme, null> &
+    OtherHTMLAttributes<DrilldownSeparatorOwnProps>
+
+const propTypes: PropValidators<PropKeys> = {
+  id: PropTypes.string.isRequired,
+  as: PropTypes.elementType
+}
+
+const allowedProps: AllowedPropKeys = ['id', 'as']
+
+export type { DrilldownSeparatorProps }
+export { propTypes, allowedProps }