docs(en): merge Recoil/docs into Recoil/docs @ 87746b52

.gitignore

@@ -103,5 +103,18 @@ dist
 # TernJS port file
 .tern-port
 
+# build outputs
+cjs
+es
+native
+umd
+/index.d.ts
+nightly-build-files
+/build
+/packages
+
 # Mac
 .DS_Store
+
+# NPM Pakcage lock since we use yarn.lock
+package-lock.json

docs/blog/2021-07-30-0.4.0-release.md

@@ -4,6 +4,8 @@ title: Recoil 0.4
 
 We are pleased to announce the release of Recoil 0.4 with configurable selector caches, improved API for transactions with multiple atoms, and other optimizations and fixes.
 
+<!--truncate-->
+
 ## Configurable selector caches
 
 The new [`cachePolicy_UNSTABLE`](/docs/api-reference/core/selector#cache-policy-configuration) property in [selectors](/docs/api-reference/core/selector) and [selector families](/docs/api-reference/utils/selectorFamily) allows you to configure the caching behavior of a selector's internal cache.  This property can be useful for reducing memory in applications that have a large number of selectors or selectors that have a large number of changing dependencies.

docs/blog/2021-08-26-0.4.1-release.md

@@ -4,6 +4,8 @@ title: Recoil 0.4.1
 
 Recoil 0.4.1 has been released with some performance optimizations and fixes focused on optimizing when React will re-render components based on Recoil state changes.
 
+<!--truncate-->
+
 - Components using selectors will no longer re-render if the selector evaluates to an equivalent value, based on reference equality.
 - Components previously rendered twice on initial render when not using React's Concurrent Mode.
 - When selectors have async dependencies that resolve, some environments of React that previously caused unnecessary re-renders no longer will.

docs/blog/2021-11-03-0.5.0-release.md

@@ -0,0 +1,34 @@
+---
+title: Recoil 0.5
+---
+
+Welcome to Recoil 0.5 with a few new APIs and improvements.
+
+<!--truncate-->
+
+## Hook for refreshing selectors
+
+The [`useRecoilRefresher_UNSTABLE()`](/docs/api-reference/core/useRecoilRefresher) hook has been added for refreshing selectors that execute data queries.  This is useful if you just want to refresh for newer data or retry due to an error.  ([#972](https://github.com/facebookexperimental/Recoil/pull/972), [#1294](https://github.com/facebookexperimental/Recoil/pull/1294), [#1302](https://github.com/facebookexperimental/Recoil/pull/1302))
+
+## Atom effect improvements
+
+* Add `isReset` parameter to `onSet()` callback to know if the atom was reset.  ([#1358](https://github.com/facebookexperimental/Recoil/pull/1358), [#1345](https://github.com/facebookexperimental/Recoil/pull/1345))
+* Add `getLoadable()`, `getPromise()`, and `getInfo_UNSTABLE()` for reading other atoms.  ([#1205](https://github.com/facebookexperimental/Recoil/pull/1205), [#1210](https://github.com/facebookexperimental/Recoil/pull/1210))
+
+## Loadable factories
+
+The [`RecoilLoadable`](/docs/api-reference/core/Loadable#creating-loadables) interface is now available for making your own `Loadable` objects.  ([#1263](https://github.com/facebookexperimental/Recoil/pull/1263), [#1264](https://github.com/facebookexperimental/Recoil/pull/1264), [#1312](https://github.com/facebookexperimental/Recoil/pull/1312))
+
+## Other fixes and improvements
+
+- Allow class instances in family parameters for Flow ([#1215](https://github.com/facebookexperimental/Recoil/pull/1215))
+- `Loadable` improvements:
+  - Ability to map Loadables with other Loadables. ([#1180](https://github.com/facebookexperimental/Recoil/pull/1180))
+  - Re-implement Loadable as classes. ([#1315](https://github.com/facebookexperimental/Recoil/pull/1315))
+- Fix user-thrown promises in selectors for some cases.
+- Improved dev-mode checks:
+  - Atoms freeze default, initialized, and async values.  Selectors should not freeze upstream dependencies. ([#1261](https://github.com/facebookexperimental/Recoil/pull/1261), [#1259](https://github.com/facebookexperimental/Recoil/pull/1259))
+  - Perform runtime check that required options are provided when creating atoms and selectors. ([#1324](https://github.com/facebookexperimental/Recoil/pull/1324))
+- Upgrade Prettier version ([#1366](https://github.com/facebookexperimental/Recoil/pull/1366))
+
+*Also lots of restructuring in preparation for the upcoming `recoil-sync` library release...*

docs/blog/2022-01-28-0.6.0-release.md

@@ -0,0 +1,78 @@
+---
+title: Recoil 0.6
+---
+
+Recoil 0.6 introduces improved support for React 18, including concurrent rendering and transitions, along with new APIs, fixes, and optimizations.
+
+<!--truncate-->
+
+## React 18
+
+Recoil 0.6 uses the latest APIs from React 18 for improved safety and performance.  This release is compatible with [concurrent rendering](https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html#whats-coming-in-react-18) and [`<React.StrictMode>`](https://reactjs.org/docs/strict-mode.html), which is useful for testing and identifying potential issues for concurrent rendering.  Making Recoil and React state changes in the same batch now stay in sync to provided a consistent view of state.  Some of these improvements are also available while using previous versions of React.  *When experimenting with React 18 please use the latest RC build, as the original React `18.0.0-rc.0` package has a bug that has since been fixed.*
+
+### Concurrent Rendering and Transitions
+
+React 18 offers a new hook [`useTransition()`](https://reactjs.org/docs/concurrent-mode-patterns.html#transitions) for transitioning to a new state while having control over what to render before the new state is ready.  Recoil should be compatible with this approach and provides a consistent view with React state.  However, React 18 may fallback from concurrent updates and does not yet officially support initiating transitions based on state changes to external stores.  This is something the React team is looking into supporting, but until then we have added experimental support for this through the following hooks.  This API is considered experimental because there may be use cases we haven’t found which are not handled.
+* `useRecoilState_TRANSITION_SUPPORT_UNSTABLE()`
+* `useRecoilValue_TRANSITION_SUPPORT_UNSTABLE()`
+* `useRecoilValueLoadable_TRANSITION_SUPPORT_UNSTABLE()`
+
+Here's an example that displays the current results while a new result is loading:
+```jsx
+function QueryResults() {
+  const queryParams = useRecoilValue_TRANSITION_SUPPORT_UNSTABLE(queryParamsAtom);
+  const results = useRecoilValue_TRANSITION_SUPPORT_UNSTABLE(myQuerySelector(queryParams));
+  return results;
+}
+
+function MyApp() {
+  const [queryParams, setQueryParams] = useRecoilState_TRANSITION_SUPPORT_UNSTABLE(queryParamsAtom);
+  const [inTransition, startTransition] = useTransition();
+  return (
+    <div>
+      {inTransition ? <div>[Loading new results...]</div> : ''}
+      Results: <React.Suspense><QueryResults /></React.Suspense>
+      <button
+        onClick={() => {
+          startTransition(() => {
+            setQueryParams(...new params...);
+          });
+        }
+      >
+        Start New Query
+      </button>
+    </div>
+  );
+}
+```
+
+## New Features
+
+* Recoil Callbacks
+  * [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback) can now also refresh selector caches, similar to [`useRecoilRefresher_UNSTABLE()`](/docs/api-reference/core/useRecoilRefresher). ([#1413](https://github.com/facebookexperimental/Recoil/pull/1413))
+  * Callbacks from selectors using [`getCallback()`](/docs/api-reference/core/selector#returning-objects-with-callbacks) can now mutate, refresh, and transact state in addition to reading it, similar to [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback). ([#1498](https://github.com/facebookexperimental/Recoil/pull/1498))
+* Store IDs - A `StoreID` can now be obtained using [`useRecoilStoreID()`](/docs/api-reference/core/useRecoilStoreID) ([#1417](https://github.com/facebookexperimental/Recoil/pull/1417)) or the `storeID` parameter in [atom effects](/docs/guides/atom-effects)  ([#1414](https://github.com/facebookexperimental/Recoil/pull/1414)).
+* [`RecoilLoadable.of()`](/docs/api-reference/core/Loadable#examples) and [`RecoilLoadable.all()`](/docs/api-reference/core/Loadable#examples) factories now accept either literal values, async Promises, or Loadables.  This is comparable to `Promise.resolve()` and `Promise.all()`  ([#1455](https://github.com/facebookexperimental/Recoil/pull/1455), [#1442](https://github.com/facebookexperimental/Recoil/pull/1442)).
+* Add `.isRetained()` method for Snapshots and check if snapshot is already released when using `.retain()` in development ([#1546](https://github.com/facebookexperimental/Recoil/pull/1546))
+
+## Breaking Changes
+- Atom Effects
+  - Rename option from `effects_UNSTABLE` to just `effects`, as the interface is mostly stabilizing. ([#1520](https://github.com/facebookexperimental/Recoil/pull/1520))
+  - [Atom effect](/docs/guides/atom-effects) initializations takes precedence over `<RecoilRoot initializeState={...}>`. ([#1509](https://github.com/facebookexperimental/Recoil/pull/1509))
+- `useGetRecoilValueInfo_UNSTABLE()` and `Snapshot#getInfo_UNSTABLE()` always report the node `type`. ([#1547](https://github.com/facebookexperimental/Recoil/pull/1547))
+- The [0.3](/blog/2021/05/14/0.3.0-released#breaking-change-preparing-for-memory-management) release introduced the need to retain Snapshots for later use, but it was mostly a warning.  Now it is necessary to retain a Snapshot for asynchronous selectors to resolve.  See the documentation [here](/docs/api-reference/core/Snapshot#asynchronous-use-of-snapshots) and [here](/docs/guides/testing#testing-async-selectors).  Future releases will further enforce this as garbage collection is released.
+
+## Other Fixes and Optimizations
+- Reduce overhead of snapshot cloning
+  - Only clone the current snapshot for callbacks if the callback actually uses it. ([#1501](https://github.com/facebookexperimental/Recoil/pull/1501))
+  - Cache the cloned snapshots from callbacks unless there was a state change. ([#1533](https://github.com/facebookexperimental/Recoil/pull/1533))
+- Fix transitive selector refresh for some cases ([#1409](https://github.com/facebookexperimental/Recoil/pull/1409))
+- Fix some corner cases with async selectors and multiple stores ([#1568](https://github.com/facebookexperimental/Recoil/pull/1568))
+- Atom effects
+  - Run atom effects when atoms are initialized from a `set()` during a transaction from [`useRecoilTransaction_UNSTABLE()`](/docs/api-reference/core/useRecoilTransaction) ([#1466](https://github.com/facebookexperimental/Recoil/pull/1466), [#1569](https://github.com/facebookexperimental/Recoil/pull/1569))
+  - Atom effects are cleaned up when initialized by a Snapshot which is released. ([#1511](https://github.com/facebookexperimental/Recoil/pull/1511), [#1532](https://github.com/facebookexperimental/Recoil/pull/1532))
+  - Unsubscribe `onSet()` handlers in atom effects when atoms are cleaned up. ([#1509](https://github.com/facebookexperimental/Recoil/pull/1509))
+  - Call `onSet()` when atoms are initialized with `<RecoilRoot initializeState={...} >` ([#1519](https://github.com/facebookexperimental/Recoil/pull/1519), [#1511](https://github.com/facebookexperimental/Recoil/pull/1511))
+- Avoid extra re-renders in some cases when a component uses a different atom/selector. ([#825](https://github.com/facebookexperimental/Recoil/pull/825))
+- `<RecoilRoot>` will only call `initializeState()` once during the initial render. ([#1372](https://github.com/facebookexperimental/Recoil/pull/1372))
+- Lazily compute and memoize the results of lazy properties, such as from `useGetRecoilValueInfo()` or `Snapshot#getInfo_UNSTABLE()`. ([#1548](https://github.com/facebookexperimental/Recoil/pull/1548), [#1549](https://github.com/facebookexperimental/Recoil/pull/1549))

docs/blog/2022-03-25-0.7.0-release.md

@@ -0,0 +1,90 @@
+---
+title: Recoil 0.7
+---
+
+Recoil 0.7 offers some minor API improvements, selector optimizations, and other fixes.
+
+<!--truncate-->
+
+## New Features
+
+### Atom Defaults are Optional
+It is now optional to provide a default value for an atom.  If no default is provided the atom will be kept in a "pending" state (e.g. triggering React Suspense) until it is set. ([#1639](https://github.com/facebookexperimental/Recoil/pull/1639))
+
+This can help avoid awkward typing (such as unecessarily making the type nullable) or awkward placeholder values for the default.  An example minimal string atom might be:
+```jsx
+atom<string>({key: 'MyString'});
+```
+This is also useful when atoms are initialized with atom effects and a default may not be necessary:
+```jsx
+atom({
+  key: 'MyQuery',
+  effects: [
+    dbSyncEffect({query, variables}),
+  ],
+});
+```
+
+### Other New Features
+- Add `.getStoreID()` method to [`Snapshot`](/docs/api-reference/core/Snapshot) ([#1612](https://github.com/facebookexperimental/Recoil/pull/1612))
+- Publish `RecoilLoadable.loading()` factory for making an async [`Loadable`](/docs/api-reference/core/Loadable) which never resolves. ([#1641](https://github.com/facebookexperimental/Recoil/pull/1641))
+
+## Improvements / Optimizations
+### Automatically retain snapshots for the duration of async callbacks.
+You now no longer need to manually retain snapshots for async callbacks from [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback).  ([#1632](https://github.com/facebookexperimental/Recoil/pull/1632))
+```jsx
+  const myCallback = useRecoilCallback(({snapshot}) => async () => {
+    // No longer necessary to retain() here
+    await something;
+    ... use snapshot ...
+  });
+```
+If you want to save a Snapshot or reference it from closure state from some other scheduled handler, then you still need to [manually retain it](/docs/api-reference/core/Snapshot#asynchronous-use-of-snapshots).
+
+### Other Improvements / Optimizations
+- Optimizations for scaling with more selector dependencies.  2x improvement with 100 dependencies, 4x with 1,000, and now able to support 10,000+ dependencies. ([#1651](https://github.com/facebookexperimental/Recoil/pull/1651), [#1515](https://github.com/facebookexperimental/Recoil/pull/1515), [#914](https://github.com/facebookexperimental/Recoil/pull/914))
+- Better error reporting when user selector implementations provide inconsistent results ([#1696](https://github.com/facebookexperimental/Recoil/pull/1696))
+
+## Breaking Changes
+### Selector evaluation or atom defaults can use a Loadable object
+
+Now the selector `get()` evaluation callback or atom `default` property can use a [`Loadable`](/docs/api-reference/core/Loadable) object. ([#1640](https://github.com/facebookexperimental/Recoil/pull/1640)) This can allow them to more cleanly accept synchronous error states:
+```jsx
+atom({
+  key: 'Key',
+  default: RecoilLoadable.error(new Error('ERROR')),
+});
+```
+or mapped Loadables or placeholders:
+```jsx
+selector({
+  key: 'Key',
+  get: ({get}) => {
+    const queryLoadable = get(noWait(myQuerySelector));
+    if (queryLoadable.state === 'loading') {
+      return PLACEHOLDER;
+    }
+    return queryLoadable; // Pass on the query results or error state.
+  }
+})
+```
+
+If you wish to explicitly evaluate a selector value to a `Promise`, `Loadable`, or `RecoilState` type object then you can now wrap them with `selector.value()` or `atom.value()`.
+```jsx
+selector({
+  key: 'Key',
+  get: ({get}) => {
+    // Returns an immediate synchronous value
+    return selector.value(Promise.resolve('Promise as a value'));
+  },
+});
+```
+
+This is only a minor change.  It helps make the API more consisent for handling wrappers such as `Promise` and `Loadable`, though is not yet available across the entire API.  But, it helps set the stage for future potential ability to explicitly set atoms and selectors to asynchronous values or error states.
+
+### Other Breaking Changes
+- [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback) now provides a snapshot for the latest state instead of the latest rendered state, which had bugs ([#1610](https://github.com/facebookexperimental/Recoil/pull/1610), [#1604](https://github.com/facebookexperimental/Recoil/pull/1604))
+
+## Fixes
+- Freezing user values in dev mode now works in JS environments without the `Window` interface. ([#1571](https://github.com/facebookexperimental/Recoil/pull/1571))
+- Avoid spurious console errors from atom effects when calling `setSelf()` from `onSet()` handlers. ([#1589](https://github.com/facebookexperimental/Recoil/pull/1589), [#1582](https://github.com/facebookexperimental/Recoil/pull/1582))

docs/blog/2022-04-12-0.7.1-release.md

@@ -0,0 +1,16 @@
+---
+title: Recoil 0.7.1
+---
+
+Typing and various improvements
+
+<!--truncate-->
+
+### Typing
+- Add explicit and required `children` prop to `<RecoilRoot>` and `useRecoilBridgeAcrossReactRoots_UNSTABLE()` for TypeScript to support the [removal of implicit children](https://solverfox.dev/writing/no-implicit-children/) with [`@types/react@^18.0.0](https://github.com/DefinitelyTyped/DefinitelyTyped/pull/56210) for React 18. ([#1718](https://github.com/facebookexperimental/Recoil/pull/1718), [#1717](https://github.com/facebookexperimental/Recoil/pull/1717), [#1726](https://github.com/facebookexperimental/Recoil/pull/1726), [#1731](https://github.com/facebookexperimental/Recoil/pull/1731))
+- Update typing for [family parameters](/docs/api-reference/utils/atomFamily#parameter-type) to better support Map, Set, and classes with `toJSON()`. ([#1709](https://github.com/facebookexperimental/Recoil/pull/1709), [#1703](https://github.com/facebookexperimental/Recoil/pull/1703))
+
+### Fixes
+- Avoid dev-mode console error with React 18 when using shared async selectors across multiple `<RecoilRoot>`'s. ([#1712](https://github.com/facebookexperimental/Recoil/pull/1712))
+- Cleanup potential memory leak when using async selectors. ([#1714](https://github.com/facebookexperimental/Recoil/pull/1714))
+- Fix potentially hung async selectors when shared across multiple roots that depend on atoms initialized with promises that don't resolve. ([#1714](https://github.com/facebookexperimental/Recoil/pull/1714))

docs/blog/2022-04-14-0.7.2-release.md

@@ -0,0 +1,11 @@
+---
+title: Recoil 0.7.2
+---
+
+Selector optimizations and fixes
+
+<!--truncate-->
+
+### Optimizations and Fixes
+- Selector cache lookup optimizations ([#1720](https://github.com/facebookexperimental/Recoil/pull/1720), [#1736](https://github.com/facebookexperimental/Recoil/pull/1736))
+- Allow async selectors to re-evaluate when async dependencies are discovered with stale state ([#1736](https://github.com/facebookexperimental/Recoil/pull/1736))

docs/blog/2022-06-01-recoil-0.7.3-release.md

@@ -0,0 +1,7 @@
+---
+title: Recoil 0.7.3
+---
+
+- Enable atoms and selectors to be used in [family parameters](/docs/api-reference/utils/selectorFamily#parameter-type) ([#1740](https://github.com/facebookexperimental/Recoil/pull/1740))
+- Add `parentStoreID_UNSTABLE` to atom effects for the parent Recoil store the atom instance was cloned from.  This enables the [pre-fetch pattern for GraphQL](/docs/recoil-relay/graphql-queries#pre-fetch-graphql).  ([#1744](https://github.com/facebookexperimental/Recoil/pull/1744))
+- Atom effects can initialize or set atoms to wrapped values ([#1681](https://github.com/facebookexperimental/Recoil/pull/1681))

docs/blog/2022-06-02-recoil-relay-0.1.0-release.md

@@ -0,0 +1,33 @@
+---
+title: Recoil Relay 0.1
+---
+
+Initial open source release for the [`recoil-relay`](/docs/recoil-relay/introduction) library for using **GraphQL**!
+
+This library helps Recoil perform type safe and efficient queries using [GraphQL](https://graphql.org/) with the [Relay](https://relay.dev) library.  It provides selectors which can easily query with GraphQL.  The queries are synced with the Recoil data-flow graph so downstream selectors can derive state from them, they can depend on upstream Recoil state, and they are automatically subscribed to any changes in the graph from Relay.  Everything stays in sync automatically.
+
+### Example
+A GraphQL query is as simple as defining a [GraphQL selector](/docs/recoil-relay/graphql-queries):
+
+```jsx
+const userNameQuery = graphQLSelector({
+  key: 'UserName',
+  environment: myEnvironment,
+  query: graphql`
+    query UserQuery($id: ID!) {
+      user(id: $id) {
+        name
+      }
+    }
+  `,
+  variables: ({get}) => ({id: get(currentIDAtom)}),
+  mapResponse: data => data.user?.name,
+});
+```
+Then use it like any other Recoil [selector](/docs/introduction/core-concepts#selectors):
+```jsx
+function MyComponent() {
+  const userName = useRecoilValue(userNameQuery);
+  return <span>{userName}</span>;
+}
+```