@instructure/ui-react-utils

  • Version 10.16.1
  • Published
  • 456 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>;

      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 DeterministicIdContextProvider

      DeterministicIdContextProvider: ({
      children,
      instanceCounterMap,
      }: React.PropsWithChildren<{
      instanceCounterMap?: DeterministicIdProviderValue;
      }>) => any;
      • --- category: components/utilities --- WARNING: providing the instanceCounterMap prop will result in unexpected behaviour. DO NOT USE IT!

        DEPRECATED: the instanceCounterMap prop is deprecated. You don't need to supply the instanceCounterMap to the component. It handles it internally.

        This is utility component for wrapping components with DeterministicIdContext.Provider See detailed documentation about how to use it: [InstUISettingsProvider](/#InstUISettingsProvider)

      function ensureSingleChild

      ensureSingleChild: (
      child: ReactNode,
      props?: {}
      ) => import('@emotion/react/jsx-runtime').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;

        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'
        | 'a'
        | 'abbr'
        | 'address'
        | 'area'
        | 'article'
        | 'aside'
        | 'audio'
        | 'b'
        | 'base'
        | 'bdi'
        | 'bdo'
        | 'big'
        | 'blockquote'
        | 'body'
        | 'br'
        | 'button'
        | 'canvas'
        | 'caption'
        | 'center'
        | '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'
        | 'link'
        | 'main'
        | 'map'
        | 'mark'
        | 'menu'
        | 'menuitem'
        | 'meta'
        | 'meter'
        | 'nav'
        | 'noscript'
        | 'ol'
        | 'optgroup'
        | 'option'
        | 'output'
        | 'p'
        | 'param'
        | 'picture'
        | 'pre'
        | 'progress'
        | 'q'
        | 'rp'
        | 'rt'
        | 'ruby'
        | 's'
        | 'samp'
        | 'search'
        | 'slot'
        | 'script'
        | 'section'
        | 'select'
        | 'small'
        | 'source'
        | 'span'
        | 'strong'
        | 'style'
        | 'sub'
        | 'summary'
        | 'sup'
        | 'table'
        | 'template'
        | 'tbody'
        | 'td'
        | 'textarea'
        | 'tfoot'
        | 'th'
        | 'thead'
        | 'time'
        | 'title'
        | 'tr'
        | 'track'
        | 'u'
        | 'ul'
        | 'var'
        | 'video'
        | 'wbr'
        | 'webview'
        | 'animate'
        | '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'
        | 'filter'
        | 'foreignObject'
        | 'g'
        | 'image'
        | 'line'
        | 'linearGradient'
        | 'marker'
        | 'mask'
        | 'metadata'
        | 'path'
        | 'pattern'
        | 'polygon'
        | 'polyline'
        | 'radialGradient'
        | 'rect'
        | 'stop'
        | 'svg'
        | 'switch'
        | 'text'
        | 'textPath'
        | 'tspan'
        | 'use'
        | 'view'
        | import('react').FunctionComponent<any>
        | 'noindex'
        | 'animateMotion'
        | 'animateTransform'
        | 'mpath'
        | import('react').ComponentClass<any, any>
        | import('react').ComponentClass<T, any>
        | import('react').FunctionComponent<T>
        | NonNullable<T['as']>;
        • --- category: utilities/react --- Get the React element type for a component. It uses the following logic: 1. type defined by the as prop 2. type returned by the getDefault() parameter 3. <a> if it has a href or to prop 4. <button> if it has an onClick prop 5. the component's defaultProp's as field 6. <span> if none of the above

          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 } & Partial<Attributes> & Partial<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: ComponentClass<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)

        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 (18)

                Dependencies (9)

                Dev Dependencies (4)

                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>