/
experimental.d.ts
181 lines (164 loc) · 7.88 KB
/
experimental.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
/**
* These are types for things that are present in the `experimental` builds of React but not yet
* on a stable build.
*
* Once they are promoted to stable they can just be moved to the main index file.
*
* To load the types declared here in an actual project, there are three ways. The easiest one,
* if your `tsconfig.json` already has a `"types"` array in the `"compilerOptions"` section,
* is to add `"react/experimental"` to the `"types"` array.
*
* Alternatively, a specific import syntax can to be used from a typescript file.
* This module does not exist in reality, which is why the {} is important:
*
* ```ts
* import {} from 'react/experimental'
* ```
*
* It is also possible to include it through a triple-slash reference:
*
* ```ts
* /// <reference types="react/experimental" />
* ```
*
* Either the import or the reference only needs to appear once, anywhere in the project.
*/
// See https://github.com/facebook/react/blob/master/packages/react/src/React.js to see how the exports are declared,
// and https://github.com/facebook/react/blob/master/packages/shared/ReactFeatureFlags.js to verify which APIs are
// flagged experimental or not. Experimental APIs will be tagged with `__EXPERIMENTAL__`.
//
// For the inputs of types exported as simply a fiber tag, the `beginWork` function of ReactFiberBeginWork.js
// is a good place to start looking for details; it generally calls prop validation functions or delegates
// all tasks done as part of the render phase (the concurrent part of the React update cycle).
//
// Suspense-related handling can be found in ReactFiberThrow.js.
import React = require('.');
export {};
declare const UNDEFINED_VOID_ONLY: unique symbol;
type VoidOrUndefinedOnly = void | { [UNDEFINED_VOID_ONLY]: never };
declare module '.' {
export interface SuspenseProps {
/**
* The presence of this prop indicates that the content is computationally expensive to render.
* In other words, the tree is CPU bound and not I/O bound (e.g. due to fetching data).
* @see {@link https://github.com/facebook/react/pull/19936}
*/
unstable_expectedLoadTime?: number;
}
export type SuspenseListRevealOrder = 'forwards' | 'backwards' | 'together';
export type SuspenseListTailMode = 'collapsed' | 'hidden';
export interface SuspenseListCommonProps {
/**
* Note that SuspenseList require more than one child;
* it is a runtime warning to provide only a single child.
*
* It does, however, allow those children to be wrapped inside a single
* level of `<React.Fragment>`.
*/
children: ReactElement | Iterable<ReactElement>;
}
interface DirectionalSuspenseListProps extends SuspenseListCommonProps {
/**
* Defines the order in which the `SuspenseList` children should be revealed.
*/
revealOrder: 'forwards' | 'backwards';
/**
* Dictates how unloaded items in a SuspenseList is shown.
*
* - By default, `SuspenseList` will show all fallbacks in the list.
* - `collapsed` shows only the next fallback in the list.
* - `hidden` doesn’t show any unloaded items.
*/
tail?: SuspenseListTailMode;
}
interface NonDirectionalSuspenseListProps extends SuspenseListCommonProps {
/**
* Defines the order in which the `SuspenseList` children should be revealed.
*/
revealOrder?: Exclude<SuspenseListRevealOrder, DirectionalSuspenseListProps['revealOrder']>;
/**
* The tail property is invalid when not using the `forwards` or `backwards` reveal orders.
*/
tail?: never;
}
export type SuspenseListProps = DirectionalSuspenseListProps | NonDirectionalSuspenseListProps;
/**
* `SuspenseList` helps coordinate many components that can suspend by orchestrating the order
* in which these components are revealed to the user.
*
* When multiple components need to fetch data, this data may arrive in an unpredictable order.
* However, if you wrap these items in a `SuspenseList`, React will not show an item in the list
* until previous items have been displayed (this behavior is adjustable).
*
* @see https://reactjs.org/docs/concurrent-mode-reference.html#suspenselist
* @see https://reactjs.org/docs/concurrent-mode-patterns.html#suspenselist
*/
export const unstable_SuspenseList: ExoticComponent<SuspenseListProps>;
// must be synchronous
export type TransitionFunction = () => VoidOrUndefinedOnly;
// strange definition to allow vscode to show documentation on the invocation
export interface TransitionStartFunction {
/**
* State updates caused inside the callback are allowed to be deferred.
*
* **If some state update causes a component to suspend, that state update should be wrapped in a transition.**
*
* @param callback A _synchronous_ function which causes state updates that can be deferred.
*/
(callback: TransitionFunction): void;
}
/**
* Returns a deferred version of the value that may “lag behind” it for at most `timeoutMs`.
*
* This is commonly used to keep the interface responsive when you have something that renders immediately
* based on user input and something that needs to wait for a data fetch.
*
* A good example of this is a text input.
*
* @param value The value that is going to be deferred
*
* @see https://reactjs.org/docs/concurrent-mode-reference.html#usedeferredvalue
*/
export function unstable_useDeferredValue<T>(value: T): T;
/**
* Allows components to avoid undesirable loading states by waiting for content to load
* before transitioning to the next screen. It also allows components to defer slower,
* data fetching updates until subsequent renders so that more crucial updates can be
* rendered immediately.
*
* The `useTransition` hook returns two values in an array.
*
* The first is boolean, React’s way of informing us whether we’re waiting for the transition to finish.
* The seconda is a function that takes a callback. We can use it to tell React which state we want to defer.
*
* **If some state update causes a component to suspend, that state update should be wrapped in a transition.**
*
* @param config An optional object with `timeoutMs`
*
* @see https://reactjs.org/docs/concurrent-mode-reference.html#usetransition
*/
export function unstable_useTransition(): [boolean, TransitionStartFunction];
const opaqueIdentifierBranding: unique symbol;
/**
* WARNING: Don't use this as a `string`.
*
* This is an opaque type that is not supposed to type-check structurally.
* It is only valid if returned from React methods and passed to React e.g. `<button aria-labelledby={opaqueIdentifier} />`
*/
// We can't create a type that would be rejected for string concatenation or `.toString()` calls.
// So in order to not have to add `string | OpaqueIdentifier` to every react-dom host prop we intersect it with `string`.
type OpaqueIdentifier = string & {
readonly [opaqueIdentifierBranding]: unknown;
// While this would cause `const stringified: string = opaqueIdentifier.toString()` to not type-check it also adds completions while typing.
// It would also still allow string concatenation.
// Unsure which is better. Not type-checking or not suggesting.
// toString(): void;
};
export function unstable_useOpaqueIdentifier(): OpaqueIdentifier;
/**
* Similar to `useTransition` but allows uses where hooks are not available.
*
* @param callback A _synchronous_ function which causes state updates that can be deferred.
*/
export function unstable_startTransition(scope: TransitionFunction): void;
}