@instructure/ui-react-utils

  • Version 8.28.2
  • Published
  • 300 kB
  • 9 dependencies
  • MIT license

Install

npm i @instructure/ui-react-utils
yarn add @instructure/ui-react-utils
pnpm add @instructure/ui-react-utils

Overview

A React utility library made by Instructure Inc.

Index

Variables

variable deprecated

const deprecated: DeprecatedDecorator;

    variable DeterministicIdContext

    const DeterministicIdContext: React.Context<DeterministicIdProviderValue>;

      variable DeterministicIdContextProvider

      const DeterministicIdContextProvider: {
      ({
      children,
      instanceCounterMap,
      }: React.PropsWithChildren<{
      instanceCounterMap?: DeterministicIdProviderValue;
      }>): JSX.Element;
      defaultProps: { instanceCounterMap: DeterministicIdProviderValue };
      };
      • --- category: components/utilities --- This is utility component for wrapping components with DeterministicIdContext.Provider See detailed documentation about how to use it: [InstUISettingsProvider](/#InstUISettingsProvider)

      Functions

      function callRenderProp

      callRenderProp: <P extends Record<string, unknown>>(
      value: Renderable<P>,
      props?: P
      ) => any;
      • --- category: utilities/react --- Evaluate a provided value to create a renderable React element. callRenderProp

        Parameter value

        Parameter props

      function ensureSingleChild

      ensureSingleChild: (child: ReactNode, props?: {}) => JSX.Element | null;
      • --- category: utilities/react ---

        Ensure a single child. If it is a child of length 1, return a cloned instance of the child. If it is a child of length > 1, wrap in a span and return the child. Return null if child has no length. ensureSingleChild

        Parameter child

        Parameter props

        props for child

        Returns

        {ReactElement|null} cloned instance for a single child, or children wrapped in a span

      function experimental

      experimental: (
      ...args: unknown[]
      ) => (ComposedComponent: ComponentClass<any, any>) => any;

        function generateInstanceCounterMap

        generateInstanceCounterMap: () => DeterministicIdProviderValue;

          function getDisplayName

          getDisplayName: (ReactComponent: string | ComponentType) => string;
          • --- category: utilities/react --- Get the displayName of a React component. needs a babel plugin to work https://github.com/facebook/react/issues/4915 !! getDisplayName

            Parameter ReactComponent

            Returns

            {String} the component displayName

          function getElementType

          getElementType: <T extends PropsObject>(
          Component: Omit<ComponentType<T>, 'propTypes'>,
          props: T,
          getDefault?: () => AsElementType<T>
          ) =>
          | 'symbol'
          | 'object'
          | import('react').ComponentClass<any, any>
          | import('react').FunctionComponent<any>
          | 'style'
          | 'map'
          | 'filter'
          | 'big'
          | 'link'
          | 'small'
          | 'sub'
          | 'sup'
          | 'a'
          | 'abbr'
          | 'address'
          | 'area'
          | 'article'
          | 'aside'
          | 'audio'
          | 'b'
          | 'base'
          | 'bdi'
          | 'bdo'
          | 'blockquote'
          | 'body'
          | 'br'
          | 'button'
          | 'canvas'
          | 'caption'
          | 'cite'
          | 'code'
          | 'col'
          | 'colgroup'
          | 'data'
          | 'datalist'
          | 'dd'
          | 'del'
          | 'details'
          | 'dfn'
          | 'dialog'
          | 'div'
          | 'dl'
          | 'dt'
          | 'em'
          | 'embed'
          | 'fieldset'
          | 'figcaption'
          | 'figure'
          | 'footer'
          | 'form'
          | 'h1'
          | 'h2'
          | 'h3'
          | 'h4'
          | 'h5'
          | 'h6'
          | 'head'
          | 'header'
          | 'hgroup'
          | 'hr'
          | 'html'
          | 'i'
          | 'iframe'
          | 'img'
          | 'input'
          | 'ins'
          | 'kbd'
          | 'keygen'
          | 'label'
          | 'legend'
          | 'li'
          | 'main'
          | 'mark'
          | 'menu'
          | 'menuitem'
          | 'meta'
          | 'meter'
          | 'nav'
          | 'noindex'
          | 'noscript'
          | 'ol'
          | 'optgroup'
          | 'option'
          | 'output'
          | 'p'
          | 'param'
          | 'picture'
          | 'pre'
          | 'progress'
          | 'q'
          | 'rp'
          | 'rt'
          | 'ruby'
          | 's'
          | 'samp'
          | 'slot'
          | 'script'
          | 'section'
          | 'select'
          | 'source'
          | 'span'
          | 'strong'
          | 'summary'
          | 'table'
          | 'template'
          | 'tbody'
          | 'td'
          | 'textarea'
          | 'tfoot'
          | 'th'
          | 'thead'
          | 'time'
          | 'title'
          | 'tr'
          | 'track'
          | 'u'
          | 'ul'
          | 'var'
          | 'video'
          | 'wbr'
          | 'webview'
          | 'svg'
          | 'animate'
          | 'animateMotion'
          | 'animateTransform'
          | 'circle'
          | 'clipPath'
          | 'defs'
          | 'desc'
          | 'ellipse'
          | 'feBlend'
          | 'feColorMatrix'
          | 'feComponentTransfer'
          | 'feComposite'
          | 'feConvolveMatrix'
          | 'feDiffuseLighting'
          | 'feDisplacementMap'
          | 'feDistantLight'
          | 'feDropShadow'
          | 'feFlood'
          | 'feFuncA'
          | 'feFuncB'
          | 'feFuncG'
          | 'feFuncR'
          | 'feGaussianBlur'
          | 'feImage'
          | 'feMerge'
          | 'feMergeNode'
          | 'feMorphology'
          | 'feOffset'
          | 'fePointLight'
          | 'feSpecularLighting'
          | 'feSpotLight'
          | 'feTile'
          | 'feTurbulence'
          | 'foreignObject'
          | 'g'
          | 'image'
          | 'line'
          | 'linearGradient'
          | 'marker'
          | 'mask'
          | 'metadata'
          | 'mpath'
          | 'path'
          | 'pattern'
          | 'polygon'
          | 'polyline'
          | 'radialGradient'
          | 'rect'
          | 'stop'
          | 'switch'
          | 'text'
          | 'textPath'
          | 'tspan'
          | 'use'
          | 'view'
          | import('react').ComponentClass<T, any>
          | import('react').FunctionComponent<T>
          | NonNullable<T['as']>;
          • --- category: utilities/react --- Get the React element type for a component.

            getElementType

            Parameter Component

            Parameter props

            Parameter getDefault

            an optional function that returns the default element type

            Returns

            {String} the element type

          function getInteraction

          getInteraction: ({
          props,
          interactionTypes,
          }?: GetInteractionOptions) => InteractionType;
          • --- category: utilities/react --- Parse the component props for the interaction type. It will return one of 'enabled', 'disabled', or 'readonly'. This is useful for form elements where consumers are able to either use the interaction prop as specified or the native html disabled or readonly attributes getInteraction

            Parameter args

            Parameter

            {Object} args.props - the component props

            Parameter

            {string} args.props.interaction - specifies the interaction mode, one of 'enabled', 'disabled', or 'readonly'

            Parameter

            {boolean} args.props.disabled - specifies if the component is disabled. Will take precedence over readOnly

            Parameter

            {boolean} args.props.readOnly - specifies if the component is readonly

            Parameter

            {Array} args.interactionTypes - an array specifying the interaction types available to the component, ['disabled', 'readonly'] by default

            Returns

            {String} one of 'enabled', 'disabled', or 'readonly'

          function hack

          hack: (...args: unknown[]) => (ComposedComponent: any) => any;
          • --- category: utilities/react --- Flag React component props as hack props. Warnings will display in the console when hack props are used.

            class Example extends Component {
            static propTypes = {
            currentProp: PropTypes.func
            }
            }
            export default hack(['hackProp'])(Example)

            hack

            Parameter hackProps

            Parameter message

            {function} React component flagged as having hack props

          function matchComponentTypes

          matchComponentTypes: <Type extends ReactElement = ReactElement>(
          componentInstance: ReactNode,
          types?: string[] | ComponentType[] | ComponentType<any>[]
          ) => componentInstance is Type;
          • --- category: utilities/react --- Check if a React component instance (React element) matches one of the specified types.

            matchComponentTypes

            Parameter componentInstance

            Parameter types

            an array of React components

            Returns

            {Boolean} true if the component matches at least one of the types

          function omitProps

          omitProps: <T extends Record<string, any>>(
          props: T,
          propsToOmit?: Record<string, any> | string[],
          exclude?: string[]
          ) => Record<string, any>;
          • --- category: utilities/react --- Return an object with the remaining props after the given props are omitted.

            Automatically excludes the following props: 'theme', 'children', 'className', 'style', 'styles', 'makeStyles', 'themeOverride', 'deterministicId' omitProps

            Parameter props

            The object to process

            Parameter propsToOmit

            list disallowed prop keys or an object whose keys will be omitted. If not specified the automatically excluded props will be removed.

            Parameter exclude

            an optional array of disallowed prop names to omit

            Returns

            props object without the excluded props omitProps

          function passthroughProps

          passthroughProps: <P extends Record<string, unknown>>(
          props: P
          ) => Record<string, unknown>;
          • Removes disallowed keys from the given object. Allowed keys: Valid props for HTML or SVG elements (see https://github.com/emotion-js/emotion/tree/main/packages/is-prop-valid)

            Disallowed is anything else and 'style', 'styles', 'className', 'children', 'makeStyles', 'deterministicId'

            Parameter props

            The props to process

          function pickProps

          pickProps: <T extends Record<string, any>>(
          props: T,
          propTypesOrAllowedPropList: Record<string, any> | string[],
          include?: string[]
          ) => Record<string, unknown>;
          • --- category: utilities/react --- Return a props object with only specified propTypes. pickProps

            Parameter props

            React component props

            Parameter propTypesOrAllowedPropList

            React component propTypes or the list of allowed prop keys

            Parameter include

            an optional array of prop names to include

            Returns

            {Object} props object with only the included props pickProps

          function safeCloneElement

          safeCloneElement: <
          E extends ReactElement = ReactElement,
          P extends GetProps<E> = GetProps<E>
          >(
          element: { ref?: any } & E,
          props: { style?: any } & Attributes & P,
          ...children: ReactNode[]
          ) => E;
          • --- category: utilities/react --- Clones a React element without overwriting refs.

            Parameter element

            The element to clone

            Parameter props

            Props of the element

            Parameter children

          function windowMessageListener

          windowMessageListener: (...args: unknown[]) => (ComposedComponent: any) => any;
          • --- category: utilities/react --- A decorator or higher order component that provides methods for cross-origin communication (between iframes/windows).

            see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage windowMessageListener

            Parameter messageHandler

            a handler for messages receieved by the component

            Parameter validSource

            an optional function that would restrict message handling to a specified source.

            Returns

            {Function} a function that decorates a React component with the behavior

          function withDeterministicId

          withDeterministicId: (
          ...args: unknown[]
          ) => (ComposedComponent: React.ComponentClass<any, any>) => any;
          • This decorator is used to enable the decorated class to use the DeterministicIdContext which is needed for deterministic id generation.

            The context is there for the users to pass an instanceCounterMap Map which is then used in the child components to deterministically create ids for them based on the instanceCounterMap. Read more about it here: [SSR guide](https://instructure.design/#server-side-rendering)

          Classes

          class ComponentIdentifier

          class ComponentIdentifier<
          P extends {
          children: ReactNode;
          }
          > extends Component<P> {}
          • --- category: utilities/react --- Abstract component identifier. Helpful for picking out a specific child.

            ```js class App extends Component { render () { const title = pick(Title, this.props.children) const content = pick(Content, this.props.children)

            return ( {title} {content} ) } }

            class Title extends ComponentIdentifier { static displayName = 'Title' } class Content extends ComponentIdentifier { static displayName = 'Content' }

            ReactDOM.render( Hello World! This text gets decorated within App. , document.getElementById('container') ) ``` ComponentIdentifier

          property defaultProps

          static defaultProps: { children: null };

            property pick

            static pick: (component: ComponentType, children: ReactNode) => undefined;

              property propTypes

              static propTypes: { children: PropTypes.Requireable<PropTypes.ReactNodeLike> };

                method render

                render: () => JSX.Element | null;

                  Type Aliases

                  type DeterministicIdProviderValue

                  type DeterministicIdProviderValue = Map<string, number>;

                    type GetInteractionOptions

                    type GetInteractionOptions = {
                    props?: {
                    interaction?: InteractionType | null;
                    disabled?: boolean | null;
                    readOnly?: boolean | null;
                    [key: string]: any;
                    };
                    interactionTypes?: InteractionType[];
                    };

                      type InteractionType

                      type InteractionType = 'enabled' | 'disabled' | 'readonly';

                        type WithDeterministicIdProps

                        type WithDeterministicIdProps = {
                        deterministicId?: (instanceName?: string) => string;
                        };

                          Package Files (20)

                          Dependencies (9)

                          Dev Dependencies (2)

                          Peer Dependencies (2)

                          Badge

                          To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                          You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@instructure/ui-react-utils.

                          • Markdown
                            [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@instructure/ui-react-utils)
                          • HTML
                            <a href="https://www.jsdocs.io/package/@instructure/ui-react-utils"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>