|
| 1 | +/* |
| 2 | +The MIT License (MIT) |
| 3 | +
|
| 4 | +Copyright (c) 2018-present, React Training LLC |
| 5 | +
|
| 6 | +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: |
| 7 | +
|
| 8 | +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. |
| 9 | +
|
| 10 | +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. |
| 11 | +*/ |
| 12 | + |
| 13 | +/* eslint-disable prefer-const */ |
| 14 | +/* eslint-disable @typescript-eslint/ban-ts-comment */ |
| 15 | +/* |
| 16 | + * Welcome to @reach/auto-id! |
| 17 | + * Let's see if we can make sense of why this hook exists and its |
| 18 | + * implementation. |
| 19 | + * |
| 20 | + * Some background: |
| 21 | + * 1. Accessibility APIs rely heavily on element IDs |
| 22 | + * 2. Requiring developers to put IDs on every element in Reach UI is both |
| 23 | + * cumbersome and error-prone |
| 24 | + * 3. With a component model, we can generate IDs for them! |
| 25 | + * |
| 26 | + * Solution 1: Generate random IDs. |
| 27 | + * |
| 28 | + * This works great as long as you don't server render your app. When React (in |
| 29 | + * the client) tries to reuse the markup from the server, the IDs won't match |
| 30 | + * and React will then recreate the entire DOM tree. |
| 31 | + * |
| 32 | + * Solution 2: Increment an integer |
| 33 | + * |
| 34 | + * This sounds great. Since we're rendering the exact same tree on the server |
| 35 | + * and client, we can increment a counter and get a deterministic result between |
| 36 | + * client and server. Also, JS integers can go up to nine-quadrillion. I'm |
| 37 | + * pretty sure the tab will be closed before an app never needs |
| 38 | + * 10 quadrillion IDs! |
| 39 | + * |
| 40 | + * Problem solved, right? |
| 41 | + * |
| 42 | + * Ah, but there's a catch! React's concurrent rendering makes this approach |
| 43 | + * non-deterministic. While the client and server will end up with the same |
| 44 | + * elements in the end, depending on suspense boundaries (and possibly some user |
| 45 | + * input during the initial render) the incrementing integers won't always match |
| 46 | + * up. |
| 47 | + * |
| 48 | + * Solution 3: Don't use IDs at all on the server; patch after first render. |
| 49 | + * |
| 50 | + * What we've done here is solution 2 with some tricks. With this approach, the |
| 51 | + * ID returned is an empty string on the first render. This way the server and |
| 52 | + * client have the same markup no matter how wild the concurrent rendering may |
| 53 | + * have gotten. |
| 54 | + * |
| 55 | + * After the render, we patch up the components with an incremented ID. This |
| 56 | + * causes a double render on any components with `useId`. Shouldn't be a problem |
| 57 | + * since the components using this hook should be small, and we're only updating |
| 58 | + * the ID attribute on the DOM, nothing big is happening. |
| 59 | + * |
| 60 | + * It doesn't have to be an incremented number, though--we could do generate |
| 61 | + * random strings instead, but incrementing a number is probably the cheapest |
| 62 | + * thing we can do. |
| 63 | + * |
| 64 | + * Additionally, we only do this patchup on the very first client render ever. |
| 65 | + * Any calls to `useId` that happen dynamically in the client will be |
| 66 | + * populated immediately with a value. So, we only get the double render after |
| 67 | + * server hydration and never again, SO BACK OFF ALRIGHT? |
| 68 | + */ |
| 69 | + |
| 70 | +import * as React from 'react'; |
| 71 | + |
| 72 | +function canUseDOM() { |
| 73 | + return !!( |
| 74 | + typeof window !== 'undefined' && |
| 75 | + window.document && |
| 76 | + window.document.createElement |
| 77 | + ); |
| 78 | +} |
| 79 | +/** |
| 80 | + * React currently throws a warning when using useLayoutEffect on the server. To |
| 81 | + * get around it, we can conditionally useEffect on the server (no-op) and |
| 82 | + * useLayoutEffect in the browser. We occasionally need useLayoutEffect to |
| 83 | + * ensure we don't get a render flash for certain operations, but we may also |
| 84 | + * need affected components to render on the server. One example is when setting |
| 85 | + * a component's descendants to retrieve their index values. |
| 86 | + * |
| 87 | + * Important to note that using this hook as an escape hatch will break the |
| 88 | + * eslint dependency warnings unless you rename the import to `useLayoutEffect`. |
| 89 | + * Use sparingly only when the effect won't effect the rendered HTML to avoid |
| 90 | + * any server/client mismatch. |
| 91 | + * |
| 92 | + * If a useLayoutEffect is needed and the result would create a mismatch, it's |
| 93 | + * likely that the component in question shouldn't be rendered on the server at |
| 94 | + * all, so a better approach would be to lazily render those in a parent |
| 95 | + * component after client-side hydration. |
| 96 | + * |
| 97 | + * https://gist.github.com/gaearon/e7d97cdf38a2907924ea12e4ebdf3c85 |
| 98 | + * https://github.com/reduxjs/react-redux/blob/master/src/utils/useIsomorphicLayoutEffect.js |
| 99 | + * |
| 100 | + * @param effect |
| 101 | + * @param deps |
| 102 | + */ |
| 103 | +const useIsomorphicLayoutEffect = canUseDOM() |
| 104 | + ? React.useLayoutEffect |
| 105 | + : React.useEffect; |
| 106 | + |
| 107 | +let serverHandoffComplete = false; |
| 108 | +let id = 0; |
| 109 | +function genId() { |
| 110 | + return ++id; |
| 111 | +} |
| 112 | + |
| 113 | +/* eslint-disable react-hooks/rules-of-hooks */ |
| 114 | + |
| 115 | +/** |
| 116 | + * useId |
| 117 | + * |
| 118 | + * Autogenerate IDs to facilitate WAI-ARIA and server rendering. |
| 119 | + * |
| 120 | + * Note: The returned ID will initially be `null` and will update after a |
| 121 | + * component mounts. Users may need to supply their own ID if they need |
| 122 | + * consistent values for SSR. |
| 123 | + * |
| 124 | + * @see Docs https://reach.tech/auto-id |
| 125 | + */ |
| 126 | +function useId(idFromProps: string): string; |
| 127 | +function useId(idFromProps: number): number; |
| 128 | +function useId(idFromProps: string | number): string | number; |
| 129 | +function useId(idFromProps: string | undefined | null): string | undefined; |
| 130 | +function useId(idFromProps: number | undefined | null): number | undefined; |
| 131 | +function useId( |
| 132 | + idFromProps: string | number | undefined | null |
| 133 | +): string | number | undefined; |
| 134 | +function useId(): string | undefined; |
| 135 | + |
| 136 | +function useId(providedId?: number | string | undefined | null) { |
| 137 | + // TODO: Remove error flag when updating internal deps to React 18. None of |
| 138 | + // our tricks will play well with concurrent rendering anyway. |
| 139 | + |
| 140 | + // If this instance isn't part of the initial render, we don't have to do the |
| 141 | + // double render/patch-up dance. We can just generate the ID and return it. |
| 142 | + let initialId = providedId ?? (serverHandoffComplete ? genId() : null); |
| 143 | + let [id, setId] = React.useState(initialId); |
| 144 | + |
| 145 | + useIsomorphicLayoutEffect(() => { |
| 146 | + if (id === null) { |
| 147 | + // Patch the ID after render. We do this in `useLayoutEffect` to avoid any |
| 148 | + // rendering flicker, though it'll make the first render slower (unlikely |
| 149 | + // to matter, but you're welcome to measure your app and let us know if |
| 150 | + // it's a problem). |
| 151 | + setId(genId()); |
| 152 | + } |
| 153 | + // eslint-disable-next-line react-hooks/exhaustive-deps |
| 154 | + }, []); |
| 155 | + |
| 156 | + React.useEffect(() => { |
| 157 | + if (serverHandoffComplete === false) { |
| 158 | + // Flag all future uses of `useId` to skip the update dance. This is in |
| 159 | + // `useEffect` because it goes after `useLayoutEffect`, ensuring we don't |
| 160 | + // accidentally bail out of the patch-up dance prematurely. |
| 161 | + serverHandoffComplete = true; |
| 162 | + } |
| 163 | + }, []); |
| 164 | + |
| 165 | + return providedId ?? id ?? undefined; |
| 166 | +} |
| 167 | + |
| 168 | +export { useId }; |
0 commit comments