@instructure/ui-react-utils

Variables

• deprecated
• DeterministicIdContext

Functions

• callRenderProp()
• DeterministicIdContextProvider()
• ensureSingleChild()
• experimental()
• getDisplayName()
• getElementType()
• getInteraction()
• hack()
• matchComponentTypes()
• omitProps()
• passthroughProps()
• pickProps()
• safeCloneElement()
• windowMessageListener()
• withDeterministicId()

Type Aliases

• DeterministicIdProviderValue
• GetInteractionOptions
• InteractionType
• WithDeterministicIdProps

variable deprecated

const deprecated: DeprecatedDecorator;

• --- category: utilities/react --- Deprecate React component props. Warnings will display in the console when deprecated props are used. Include the version number when the deprecated component will be removed.

   class Example extends Component {
     static propTypes = {
       currentProp: PropTypes.func
     }
   }
   export default deprecated('7.0.0', {
     deprecatedProp: 'currentProp',
     nowNonExistentProp: true
   })(Example)

  Parameter version

  Parameter oldProps

  (if this argument is null or undefined, the entire component is deprecated)

  Parameter message

  {function} React component with deprecated props behavior deprecated

variable DeterministicIdContext

const DeterministicIdContext: React.Context<DeterministicIdProviderValue>;

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

  cloned instance for a single child, or children wrapped in a span

function experimental

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

• --- category: utilities/react --- Flag React component and component props as experimental. Warnings will display in the console when experimental components/props props are used.

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

  experimental

  Parameter experimentalProps

  (if this argument is null or undefined, the entire component is flagged)

  Parameter message

  {function} React component flagged as experimental

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

  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

  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

  extra arguments

  Returns

  The calculated interaction type

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

  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.

  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

  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 DeterministicIdProviderValue

type DeterministicIdProviderValue = Map<string, number>;

type GetInteractionOptions

type GetInteractionOptions = {
    props?: {
        /**
         * specifies the interaction mode, one of 'enabled', 'disabled', or 'readonly'
         */
        interaction?: InteractionType | null;
        /**
         * specifies if the component is disabled. Will take precedence over readOnly
         */
        disabled?: boolean | null;
        /**
         * specifies if the component is readonly
         */
        readOnly?: boolean | null;
        [key: string]: any;
    };
    /**
     * an array specifying the interaction types available to the component, ['disabled', 'readonly'] by default
     */
    interactionTypes?: InteractionType[];
};

type InteractionType

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

type WithDeterministicIdProps

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