@instructure/ui-react-utils 8.17.0 → 8.17.1-snapshot.17

package/src/DeterministicIdContext/DeterministicIdContext.ts

@@ -0,0 +1,29 @@
+/*
+ * 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 { generateInstanceCounterMap } from './generateInstanceCounterMap'
+
+const DeterministicIdContext = React.createContext(generateInstanceCounterMap())
+
+export { DeterministicIdContext }

package/src/DeterministicIdContext/DeterministicIdProvider.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.
+ */
+import React from 'react'
+import { generateInstanceCounterMap } from './generateInstanceCounterMap'
+import { DeterministicIdContext } from './DeterministicIdContext'
+type DeterministicIdProviderValue = Map<string, number>
+type DeterministicIdProviderProps = React.PropsWithChildren<{
+  instanceCounterMap?: DeterministicIdProviderValue
+}>
+
+const defaultContextValue = generateInstanceCounterMap()
+
+/**
+ * ---
+ * category: components/utilities
+ * ---
+ * This is utility component for wrapping components with `DeterministicIdContext.Provider`
+ * See detailed documentation about how to use it: [InstUISettingsProvider](/#InstUISettingsProvider)
+ */
+
+const DeterministicIdContextProvider = ({
+  children,
+  instanceCounterMap
+}: DeterministicIdProviderProps) => {
+  return (
+    <DeterministicIdContext.Provider value={instanceCounterMap!}>
+      {children}
+    </DeterministicIdContext.Provider>
+  )
+}
+DeterministicIdContextProvider.defaultProps = {
+  instanceCounterMap: defaultContextValue
+}
+
+export { DeterministicIdContextProvider }
+
+export type { DeterministicIdProviderValue }

package/src/DeterministicIdContext/generateInstanceCounterMap.ts

@@ -0,0 +1,29 @@
+/*
+ * 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 type { DeterministicIdProviderValue } from './DeterministicIdProvider'
+function generateInstanceCounterMap(): DeterministicIdProviderValue {
+  return new Map<string, number>()
+}
+export default generateInstanceCounterMap
+export { generateInstanceCounterMap }

package/src/DeterministicIdContext/index.ts

@@ -0,0 +1,30 @@
+/*
+ * 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.
+ */
+
+export { generateInstanceCounterMap } from './generateInstanceCounterMap'
+export { DeterministicIdContextProvider } from './DeterministicIdProvider'
+export { DeterministicIdContext } from './DeterministicIdContext'
+export { withDeterministicId } from './withDeterministicId'
+export type { DeterministicIdProviderValue } from './DeterministicIdProvider'
+export type { WithDeterministicIdProps } from './withDeterministicId'

package/src/DeterministicIdContext/withDeterministicId.tsx

@@ -0,0 +1,101 @@
+/*
+ * 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, {
+  forwardRef,
+  PropsWithoutRef,
+  RefAttributes,
+  useContext
+} from 'react'
+import hoistNonReactStatics from 'hoist-non-react-statics'
+
+import { DeterministicIdContext } from './DeterministicIdContext'
+import { decorator } from '@instructure/ui-decorator'
+import { generateId } from '@instructure/ui-utils'
+
+import type { InstUIComponent } from '@instructure/shared-types'
+import { warn } from '@instructure/console'
+
+type WithDeterministicIdProps = {
+  deterministicId?: (instanceName?: string) => string
+}
+/**
+ * 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)
+ */
+const withDeterministicId = decorator((ComposedComponent: InstUIComponent) => {
+  type Props = PropsWithoutRef<Record<string, unknown>> & RefAttributes<any>
+  const WithDeterministicId = forwardRef(
+    (props: Props, ref: React.ForwardedRef<any>) => {
+      const componentName =
+        ComposedComponent.componentId ||
+        ComposedComponent.displayName ||
+        ComposedComponent.name
+      const instanceCounterMap = useContext(DeterministicIdContext)
+      const deterministicId = (instanceName = componentName) =>
+        generateId(instanceName, instanceCounterMap)
+
+      if (props.deterministicId) {
+        warn(
+          false,
+          `Manually passing the "deterministicId" property is not allowed on the ${componentName} component.\n`,
+          props.deterministicId
+        )
+      }
+
+      return (
+        <ComposedComponent
+          ref={ref}
+          deterministicId={deterministicId}
+          {...props}
+        />
+      )
+    }
+  )
+
+  hoistNonReactStatics(WithDeterministicId, ComposedComponent)
+
+  // we have to pass these on, because sometimes users
+  // access propTypes of the component in other components
+  // eslint-disable-next-line react/forbid-foreign-prop-types
+  WithDeterministicId.propTypes = ComposedComponent.propTypes
+  WithDeterministicId.defaultProps = ComposedComponent.defaultProps
+
+  // These static fields exist on InstUI components
+  //@ts-expect-error fix this
+  WithDeterministicId.allowedProps = ComposedComponent.allowedProps
+
+  if (process.env.NODE_ENV !== 'production') {
+    WithDeterministicId.displayName = `WithDeterministicId(${ComposedComponent.displayName})`
+  }
+
+  return WithDeterministicId
+})
+
+export default withDeterministicId
+export { withDeterministicId }
+export type { WithDeterministicIdProps }

package/src/index.ts

@@ -38,5 +38,15 @@ export { passthroughProps } from './passthroughProps'
 export { pickProps } from './pickProps'
 export { safeCloneElement } from './safeCloneElement'
 export { windowMessageListener } from './windowMessageListener'
+export {
+  DeterministicIdContext,
+  generateInstanceCounterMap,
+  DeterministicIdContextProvider,
+  withDeterministicId
+} from './DeterministicIdContext'
 export type { GetInteractionOptions } from './getInteraction'
 export type { InteractionType } from './getInteraction'
+export type {
+  DeterministicIdProviderValue,
+  WithDeterministicIdProps
+} from './DeterministicIdContext'

package/src/omitProps.ts

@@ -66,7 +66,8 @@ const omit = <T>(originalObject: T, keysToOmit: string[]) => {
       key === 'style' ||
       key === 'styles' ||
       key === 'makeStyles' ||
-      key === 'themeOverride'
+      key === 'themeOverride' ||
+      key === 'instanceCounterMap'
     ) {
       continue
     }

package/src/passthroughProps.ts

@@ -44,7 +44,8 @@ function passthroughProps<P>(props: P) {
         propName !== 'className' &&
         propName !== 'children' &&
         propName !== 'styles' &&
-        propName !== 'makeStyles'
+        propName !== 'makeStyles' &&
+        propName !== 'instanceCounterMap'
     )
     .forEach((propName) => {
       validProps[propName as keyof P] = props[propName as keyof P]