@instructure/ui-react-utils 11.7.10 → 11.7.11-snapshot-0

package/src/HydrationContext/HydrationContext.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 { createContext } from 'react'
+
+/**
+ * Whether the page has hydrated. `undefined` means there's no
+ * `HydrationProvider` above, and `false` means hydration hasn't finished yet.
+ */
+const HydrationContext = createContext<boolean | undefined>(undefined)
+
+export { HydrationContext }
+export default HydrationContext

package/src/HydrationContext/HydrationGate.tsx

@@ -0,0 +1,54 @@
+/*
+ * 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 { ReactNode } from 'react'
+
+import { useIsHydratedContext } from './useIsHydratedContext.js'
+
+type HydrationGateProps = {
+  children: (isHydrated: boolean) => ReactNode
+}
+
+/**
+ * ---
+ * category: utilities/SSR
+ * ---
+ * Lets class components know whether the page has hydrated. It works with or
+ * without a `HydrationProvider` above it.
+ *
+ * ```jsx
+ * <HydrationGate>
+ *   {(isHydrated) => (isHydrated ? <Content /> : <Placeholder />)}
+ * </HydrationGate>
+ * ```
+ */
+function HydrationGate({ children }: HydrationGateProps) {
+  return <>{children(useIsHydratedContext())}</>
+}
+
+HydrationGate.displayName = 'HydrationGate'
+
+export { HydrationGate }
+export type { HydrationGateProps }
+export default HydrationGate

package/src/HydrationContext/HydrationProvider.tsx

@@ -0,0 +1,57 @@
+/*
+ * 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 { ReactNode } from 'react'
+
+import { HydrationContext } from './HydrationContext.js'
+import { useIsHydrated } from '../useIsHydrated.js'
+
+type HydrationProviderProps = {
+  children?: ReactNode
+}
+
+/**
+ * ---
+ * category: utilities/SSR
+ * ---
+ * Shares whether the page has hydrated with every component below it, so they
+ * all switch from their server output at the same time. Class components read
+ * it with `HydrationGate`.
+ *
+ * `InstUISettingsProvider` already includes it, so you usually don't need to
+ * add it yourself.
+ */
+function HydrationProvider({ children }: HydrationProviderProps) {
+  const isHydrated = useIsHydrated()
+
+  return (
+    <HydrationContext.Provider value={isHydrated}>
+      {children}
+    </HydrationContext.Provider>
+  )
+}
+
+export { HydrationProvider }
+export type { HydrationProviderProps }
+export default HydrationProvider

package/src/HydrationContext/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 { HydrationContext } from './HydrationContext.js'
+export { HydrationProvider } from './HydrationProvider.js'
+export { useIsHydratedContext } from './useIsHydratedContext.js'
+export { HydrationGate } from './HydrationGate.js'
+export type { HydrationProviderProps } from './HydrationProvider'
+export type { HydrationGateProps } from './HydrationGate'

package/src/HydrationContext/useIsHydratedContext.ts

@@ -0,0 +1,48 @@
+/*
+ * 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 { useContext } from 'react'
+
+import { HydrationContext } from './HydrationContext.js'
+import { useIsHydrated } from '../useIsHydrated.js'
+
+/**
+ * ---
+ * category: utilities/SSR
+ * ---
+ * Like `useIsHydrated`, but reads the value from the nearest
+ * `HydrationProvider` when there is one.
+ *
+ * @module useIsHydratedContext
+ * @returns {boolean} `true` once the page has hydrated
+ */
+const useIsHydratedContext = (): boolean => {
+  const fromProvider = useContext(HydrationContext)
+  // Hooks can't be called conditionally, so this always runs.
+  const standalone = useIsHydrated()
+  return fromProvider ?? standalone
+}
+
+export { useIsHydratedContext }
+export default useIsHydratedContext

package/src/index.ts

@@ -33,6 +33,7 @@ export { omitProps } from './omitProps.js'
 export { passthroughProps } from './passthroughProps.js'
 export { pickProps } from './pickProps.js'
 export { safeCloneElement } from './safeCloneElement.js'
+export { useIsHydrated } from './useIsHydrated.js'
 export { windowMessageListener } from './windowMessageListener.js'
 export {
   DeterministicIdContext,
@@ -41,9 +42,20 @@ export {
   useDeterministicId
 } from './DeterministicIdContext/index.js'
 
+export {
+  HydrationContext,
+  HydrationProvider,
+  useIsHydratedContext,
+  HydrationGate
+} from './HydrationContext/index.js'
+
 export type { GetInteractionOptions } from './getInteraction'
 export type { InteractionType } from './getInteraction'
 export type {
   DeterministicIdProviderValue,
   WithDeterministicIdProps
 } from './DeterministicIdContext'
+export type {
+  HydrationProviderProps,
+  HydrationGateProps
+} from './HydrationContext'

package/src/useIsHydrated.ts

@@ -0,0 +1,47 @@
+/*
+ * 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 { useSyncExternalStore } from 'react'
+
+// The value never changes, so there's nothing to subscribe to.
+const noopSubscribe = () => () => {}
+const getClientSnapshot = () => true
+const getServerSnapshot = () => false
+
+/**
+ * ---
+ * category: utilities/SSR
+ * ---
+ * Returns `false` on the server and while React is hydrating, then `true`.
+ * Use it to render something different on the client without causing a
+ * hydration mismatch. In class components, use `HydrationGate` instead.
+ *
+ * @module useIsHydrated
+ * @returns {boolean} `true` once the page has hydrated
+ */
+const useIsHydrated = (): boolean =>
+  useSyncExternalStore(noopSubscribe, getClientSnapshot, getServerSnapshot)
+
+export default useIsHydrated
+export { useIsHydrated }