From a6501dc35d900b5dd7fe6ed7b269e769da581894 Mon Sep 17 00:00:00 2001 From: Nathaniel Tucker Date: Sat, 29 Jun 2024 15:56:36 +0200 Subject: [PATCH] docs: Improve site metadata for SEO --- .gitignore | 2 ++ docs/core/README.md | 5 +++-- docs/core/api/AsyncBoundary.md | 7 +++++-- docs/core/api/Controller.md | 6 ++++-- docs/core/api/DataProvider.md | 10 +++++----- docs/core/api/Fixtures.md | 9 ++++----- docs/core/api/LogoutManager.md | 6 ++---- docs/core/api/Manager.md | 6 ++++-- docs/core/api/MockResolver.md | 7 +++---- docs/core/api/NetworkManager.md | 7 ++----- docs/core/api/Snapshot.md | 7 +++---- docs/core/api/useCache.md | 10 +++++----- docs/core/api/useCancelling.md | 8 ++++---- docs/core/api/useController.md | 7 +++++-- docs/core/api/useDLE.md | 7 +++---- docs/core/api/useDebounce.md | 8 ++++---- docs/core/api/useError.md | 7 +++---- docs/core/api/useFetch.md | 7 +++++-- docs/core/api/useLive.md | 7 +++++-- docs/core/api/useLoading.md | 8 ++++---- docs/core/api/useQuery.md | 10 +++++----- docs/core/api/useSubscription.md | 9 ++++----- docs/core/api/useSuspense.md | 7 +++++-- docs/core/concepts/atomic-mutations.md | 3 +-- docs/core/concepts/error-policy.md | 6 ++++-- docs/core/concepts/expiry-policy.md | 6 ++++-- docs/core/concepts/managers.md | 7 +++++-- docs/core/concepts/validation.md | 5 +++-- docs/core/getting-started/data-dependency.md | 5 +++-- docs/core/getting-started/installation.md | 8 +++----- docs/core/getting-started/mutations.md | 6 ++++-- docs/core/getting-started/resource.md | 5 +++-- docs/core/guides/custom-protocol.md | 6 ++---- docs/core/guides/img-media.md | 9 ++++----- docs/core/guides/redux.md | 9 ++++----- docs/core/guides/ssr.md | 6 ++++-- docs/core/guides/storybook.md | 4 +++- docs/graphql/README.md | 7 ++----- docs/graphql/auth.md | 7 +++---- docs/rest/README.md | 8 +++----- docs/rest/api/All.md | 9 ++++----- docs/rest/api/Array.md | 9 ++++----- docs/rest/api/Collection.md | 9 ++++----- docs/rest/api/Endpoint.md | 9 ++++----- docs/rest/api/Entity.md | 6 ++++-- docs/rest/api/Invalidate.md | 8 ++++---- docs/rest/api/Object.md | 9 ++++----- docs/rest/api/Query.md | 6 ++++-- docs/rest/api/RestEndpoint.md | 10 ++++++---- docs/rest/api/Union.md | 8 ++++---- docs/rest/api/Values.md | 9 ++++----- docs/rest/api/createResource.md | 6 ++++-- docs/rest/api/hookifyResource.md | 6 ++++-- docs/rest/api/schema.Entity.md | 6 ++++-- docs/rest/guides/optimistic-updates.md | 6 ++++-- docs/rest/guides/pagination.md | 6 ++---- docs/rest/guides/relational-data.md | 8 +++----- website/docusaurus.config.ts | 9 +++++---- 58 files changed, 216 insertions(+), 197 deletions(-) diff --git a/.gitignore b/.gitignore index f4bda0d998de..337eb71b10fa 100644 --- a/.gitignore +++ b/.gitignore @@ -72,3 +72,5 @@ typings/ # build info **/tsconfig*.tsbuildinfo + +/codemods/ \ No newline at end of file diff --git a/docs/core/README.md b/docs/core/README.md index 21c111e37a53..dca169a50512 100644 --- a/docs/core/README.md +++ b/docs/core/README.md @@ -1,6 +1,7 @@ --- -title: The Reactive Data Client +title: Introducing the Reactive Data Client sidebar_label: Introduction +description: Building delightful dynamic applications with NextJS, Expo, React Native and more. slug: / --- @@ -14,10 +15,10 @@ import HooksPlayground from '@site/src/components/HooksPlayground'; import Link from '@docusaurus/Link'; - Introducing the Reactive Data Client +# The Reactive Data Client Reactive Data Client provides safe and performant [client access](./api/useSuspense.md) and [mutation](./api/Controller.md#fetch) over [remote data protocols](https://www.freecodecamp.org/news/what-is-an-api-in-english-please-b880a3214a82/). Both pull/fetch ([REST](/rest) and [GraphQL](/graphql)) and push/stream ([WebSockets or Server Sent Events](./api/Manager.md#data-stream)) can be used simultaneously. diff --git a/docs/core/api/AsyncBoundary.md b/docs/core/api/AsyncBoundary.md index 9fa097de4ae3..354aa957c48c 100644 --- a/docs/core/api/AsyncBoundary.md +++ b/docs/core/api/AsyncBoundary.md @@ -1,12 +1,15 @@ --- -title: '' +title: AsyncBoundary - Centralize loading and error handling +sidebar_label: +description: Handles loading and error conditions of Suspense. --- - AsyncBoundary - Centralize loading and error handling +# <AsyncBoundary /> + Handles loading and error conditions of Suspense. In React 18, this will create a [concurrent split](https://react.dev/reference/react/useTransition), and in 16 and 17 it will show loading fallbacks. If there is an irrecoverable error, it will show an error fallback. diff --git a/docs/core/api/Controller.md b/docs/core/api/Controller.md index 9923b40435cb..121369950909 100644 --- a/docs/core/api/Controller.md +++ b/docs/core/api/Controller.md @@ -1,9 +1,9 @@ --- -title: Controller +title: Controller - Typesafe imperative store access +sidebar_label: Controller --- - Controller - Typesafe imperative store access @@ -12,6 +12,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import StackBlitz from '@site/src/components/StackBlitz'; +# Controller + `Controller` is a singleton providing safe access to the Reactive Data Client [flux store and lifecycle](./Manager.md#control-flow). `Controller` memoizes all store access, allowing a global referential equality guarantee and the fastest rendering and retrieval performance. diff --git a/docs/core/api/DataProvider.md b/docs/core/api/DataProvider.md index e76f931907d0..907e4f99992c 100644 --- a/docs/core/api/DataProvider.md +++ b/docs/core/api/DataProvider.md @@ -1,15 +1,15 @@ --- -title: '' +title: DataProvider - Normalized async data management in React +sidebar_label: +description: High performance, globally consistent data management in React --- - - DataProvider - Normalized async data management in React - - import Installation from '../shared/\_installation.mdx'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +# <DataProvider /> + Manages state, providing all context needed to use the hooks. Should be placed as high as possible in application tree as any usage of the hooks is only possible for components below the provider in the React tree. diff --git a/docs/core/api/Fixtures.md b/docs/core/api/Fixtures.md index 77188f8ebc8d..d2399b057256 100644 --- a/docs/core/api/Fixtures.md +++ b/docs/core/api/Fixtures.md @@ -1,14 +1,13 @@ --- -title: Fixtures and Interceptors +title: 'Fixtures and Interceptors: declarative data mocking for tests and stories' sidebar_label: Fixtures and Interceptors +description: Fixtures and Interceptors allow universal data mocking without the need for monkeypatching fetch behaviors. --- - - Fixtures and Interceptors: declarative data mocking for tests and stories - - import GenericsTabs from '@site/src/components/GenericsTabs'; +# Fixtures and Interceptors + Fixtures and Interceptors allow universal data mocking without the need for monkeypatching fetch behaviors. Fixtures define static responses to specific endpoint arg combinations. This allows them to be used in static contexts like [mockInitialState()](./mockInitialState.md). diff --git a/docs/core/api/LogoutManager.md b/docs/core/api/LogoutManager.md index affa996286cd..7e96a1b06b84 100644 --- a/docs/core/api/LogoutManager.md +++ b/docs/core/api/LogoutManager.md @@ -1,5 +1,5 @@ --- -title: 'LogoutManager' +title: LogoutManager - Handling 401s and other deauthorization triggers sidebar_label: LogoutManager --- @@ -7,9 +7,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import StackBlitz from '@site/src/components/StackBlitz'; - - LogoutManager - Handling 401s and other deauthorization triggers - +# LogoutManager Logs out based on fetch responses. By default this is triggered by [401 (Unauthorized)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) status responses. diff --git a/docs/core/api/Manager.md b/docs/core/api/Manager.md index aa5ab4891f86..6831dac1aa6b 100644 --- a/docs/core/api/Manager.md +++ b/docs/core/api/Manager.md @@ -1,5 +1,6 @@ --- -title: Manager +title: Manager - Powerful middlewares with global store knowledge +sidebar_label: Manager --- import Tabs from '@theme/Tabs'; @@ -8,10 +9,11 @@ import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl'; - Manager - Powerful middlewares with global store knowledge +# Manager + Managers are singletons that orchestrate the complex asynchronous behavior of `Reactive Data Client`. Several managers are provided by `Reactive Data Client` and used by default; however there is nothing stopping other compatible managers to be built that expand the functionality. We encourage diff --git a/docs/core/api/MockResolver.md b/docs/core/api/MockResolver.md index 0bdd26935cae..732a147c241d 100644 --- a/docs/core/api/MockResolver.md +++ b/docs/core/api/MockResolver.md @@ -1,10 +1,9 @@ --- -title: '' +title: MockResolver - Data Mocking for React +sidebar_label: --- - - MockResolver - Data Mocking for React - +# <MockResolver /> ```typescript function MockResolver(props: { diff --git a/docs/core/api/NetworkManager.md b/docs/core/api/NetworkManager.md index f762ef77db9d..f00751d8cfc1 100644 --- a/docs/core/api/NetworkManager.md +++ b/docs/core/api/NetworkManager.md @@ -1,12 +1,9 @@ --- -title: NetworkManager +title: NetworkManager - Orchestrating efficient race-condition free fetching sidebar_label: NetworkManager --- - - NetworkManager - Orchestrating efficient race-condition free fetching - - +# NetworkManager NetworkManager orchestrates asynchronous fetches. By keeping track of all in-flight requests it is able to dedupe identical requests if they are made using the throttle flag. diff --git a/docs/core/api/Snapshot.md b/docs/core/api/Snapshot.md index 0fe895ca9973..ff294d5e2a5a 100644 --- a/docs/core/api/Snapshot.md +++ b/docs/core/api/Snapshot.md @@ -1,10 +1,9 @@ --- -title: Snapshot +title: Snapshot - Safe data access with zero race conditions +sidebar_label: Snapshot --- - - Snapshot - Safe data access with zero race conditions - +# Snapshot import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/core/api/useCache.md b/docs/core/api/useCache.md index a628af724341..1a49c4e8bc85 100644 --- a/docs/core/api/useCache.md +++ b/docs/core/api/useCache.md @@ -1,17 +1,17 @@ --- -title: useCache() +title: useCache() - Normalized data store access in React +sidebar_label: useCache() +description: Data rendering without the fetch. Access any Endpoint's response. --- - - useCache() - Normalized data store access in React - - import GenericsTabs from '@site/src/components/GenericsTabs'; import ConditionalDependencies from '../shared/\_conditional_dependencies.mdx'; import HooksPlayground from '@site/src/components/HooksPlayground'; import StackBlitz from '@site/src/components/StackBlitz'; import { RestEndpoint } from '@data-client/rest'; +# useCache() + Data rendering without the fetch. Access any [Endpoint](/rest/api/Endpoint)'s response. If the response does not exist, returns diff --git a/docs/core/api/useCancelling.md b/docs/core/api/useCancelling.md index e1bf23a75703..37ebc9112943 100644 --- a/docs/core/api/useCancelling.md +++ b/docs/core/api/useCancelling.md @@ -1,14 +1,14 @@ --- -title: useCancelling() +title: useCancelling() - Declarative fetch aborting for React +sidebar_label: useCancelling() +description: Builds an Endpoint that cancels fetch everytime parameters change. Aborts inflight request on param change. --- import HooksPlayground from '@site/src/components/HooksPlayground'; import PkgInstall from '@site/src/components/PkgInstall'; import UseCancelling from '../shared/\_useCancelling.mdx'; - - useCancelling() - Declarative fetch aborting for React - +# useCancelling() Builds an Endpoint that cancels fetch everytime parameters change diff --git a/docs/core/api/useController.md b/docs/core/api/useController.md index f798036540d5..52b14c966200 100644 --- a/docs/core/api/useController.md +++ b/docs/core/api/useController.md @@ -1,15 +1,18 @@ --- -title: useController() +title: useController() - Type safe store manipulation in React +sidebar_label: useController() +description: Controller provides type-safe methods to access and dispatch actions to the store. --- - useController() - Type safe store manipulation in React import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; import StackBlitz from '@site/src/components/StackBlitz'; +# useController() + [Controller](./Controller.md) provides type-safe methods to access and dispatch actions to the store. For instance [fetch](./Controller.md#fetch), [invalidate](./Controller.md#invalidate), diff --git a/docs/core/api/useDLE.md b/docs/core/api/useDLE.md index ef700f9dfe22..c7d6c7607219 100644 --- a/docs/core/api/useDLE.md +++ b/docs/core/api/useDLE.md @@ -1,6 +1,7 @@ --- -title: useDLE() - [D]ata [L]oading [E]rror +title: useDLE() - [D]ata [L]oading [E]rror React State sidebar_label: useDLE() +description: High performance async data rendering without overfetching. With fetch meta data. --- import HooksPlayground from '@site/src/components/HooksPlayground'; @@ -12,9 +13,7 @@ import ConditionalDependencies from '../shared/\_conditional_dependencies.mdx'; import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; import StackBlitz from '@site/src/components/StackBlitz'; - - useDLE() - [D]ata [L]oading [E]rror React State - +# useDLE() - [D]ata [L]oading [E]rror High performance async data rendering without overfetching. With fetch meta data. diff --git a/docs/core/api/useDebounce.md b/docs/core/api/useDebounce.md index 65a389f891bb..0cf2b0e23882 100644 --- a/docs/core/api/useDebounce.md +++ b/docs/core/api/useDebounce.md @@ -1,13 +1,13 @@ --- -title: useDebounce() +title: useDebounce() - Declarative value delays for React +sidebar_label: useDebounce() +description: Delays updating the parameters by debouncing. Avoid excessive network requests due to quick parameter changes like typeaheads. --- import PkgInstall from '@site/src/components/PkgInstall'; import HooksPlayground from '@site/src/components/HooksPlayground'; - - useDebounce() - Declarative value delays for React - +# useDebounce() Delays updating the parameters by [debouncing](https://css-tricks.com/debouncing-throttling-explained-examples/). diff --git a/docs/core/api/useError.md b/docs/core/api/useError.md index f497220ecde6..f731ce379a58 100644 --- a/docs/core/api/useError.md +++ b/docs/core/api/useError.md @@ -1,10 +1,9 @@ --- -title: useError() +title: useError() - Accessing error metadata +sidebar_label: useError() --- - - useError() - Accessing error metadata - +# useError() ```typescript export interface SyntheticError extends Error { diff --git a/docs/core/api/useFetch.md b/docs/core/api/useFetch.md index 69838fd33c42..9d69f90f7e1d 100644 --- a/docs/core/api/useFetch.md +++ b/docs/core/api/useFetch.md @@ -1,15 +1,18 @@ --- -title: useFetch() +title: useFetch() - Declarative fetch triggers for React +sidebar_label: useFetch() +description: Fetch without the data rendering. Prevent fetch waterfalls by prefetching without duplicate requests. --- import GenericsTabs from '@site/src/components/GenericsTabs'; import ConditionalDependencies from '../shared/\_conditional_dependencies.mdx'; - useFetch() - Declarative fetch triggers for React +# useFetch() + Fetch without the data rendering. This can be useful for ensuring resources early in a render tree before they are needed. diff --git a/docs/core/api/useLive.md b/docs/core/api/useLive.md index d04d0c77a969..542ed618f2b8 100644 --- a/docs/core/api/useLive.md +++ b/docs/core/api/useLive.md @@ -1,9 +1,10 @@ --- -title: useLive() +title: useLive() - Rendering dynamic data in React +sidebar_label: useLive() +description: Async rendering of remotely triggered data mutations. useSuspense() + useSubscription() in one hook. --- - useLive() - Rendering dynamic data in React @@ -14,6 +15,8 @@ import {RestEndpoint} from '@data-client/rest'; import StackBlitz from '@site/src/components/StackBlitz'; import UseLive from '../shared/\_useLive.mdx'; +# useLive() + Async rendering of remotely triggered data mutations. [useSuspense()](./useSuspense.md) + [useSubscription()](./useSubscription.md) in one hook. diff --git a/docs/core/api/useLoading.md b/docs/core/api/useLoading.md index 32e5d9fdd308..fb663e1fcbc5 100644 --- a/docs/core/api/useLoading.md +++ b/docs/core/api/useLoading.md @@ -1,14 +1,14 @@ --- -title: useLoading() +title: useLoading() - Turn any promise into React State +sidebar_label: useLoading() +description: Track loading and error state of any async function. --- import UseLoading from '../shared/\_useLoading.mdx'; import PkgInstall from '@site/src/components/PkgInstall'; import StackBlitz from '@site/src/components/StackBlitz'; - - useLoading() - Turn any promise into React State - +# useLoading() Helps track loading state of imperative async functions. diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md index 93ab72ea22e0..cca9de95ff89 100644 --- a/docs/core/api/useQuery.md +++ b/docs/core/api/useQuery.md @@ -1,11 +1,9 @@ --- -title: useQuery() +title: useQuery() - Normalized data store access in React +sidebar_label: useQuery() +description: Data rendering without the fetch. Access any Schema's memoized store value. --- - - useQuery() - Normalized data store access in React - - import GenericsTabs from '@site/src/components/GenericsTabs'; import ConditionalDependencies from '../shared/\_conditional_dependencies.mdx'; import HooksPlayground from '@site/src/components/HooksPlayground'; @@ -13,6 +11,8 @@ import StackBlitz from '@site/src/components/StackBlitz'; import { RestEndpoint } from '@data-client/rest'; import VoteDemo from '../shared/\_VoteDemo.mdx'; +# useQuery() + Query the store. Renders any [Queryable Schema](/rest/api/schema#queryable) like [Entity](/rest/api/Entity), [All](/rest/api/All), [Collection](/rest/api/Collection), [Query](/rest/api/Query), diff --git a/docs/core/api/useSubscription.md b/docs/core/api/useSubscription.md index 5a896b1a1ea1..a9353e069395 100644 --- a/docs/core/api/useSubscription.md +++ b/docs/core/api/useSubscription.md @@ -1,15 +1,14 @@ --- -title: useSubscription() +title: useSubscription() - Updating frequent data changes in React +sidebar_label: useSubscription() +description: Keeps data fresh, but only when component is active. Supports polling, websockets, and SSE. --- - - useSubscription() - Updating frequent data changes in React - - import GenericsTabs from '@site/src/components/GenericsTabs'; import ConditionalDependencies from '../shared/\_conditional_dependencies.mdx'; import StackBlitz from '@site/src/components/StackBlitz'; +# useSubscription() Great for keeping resources up-to-date with frequent changes. diff --git a/docs/core/api/useSuspense.md b/docs/core/api/useSuspense.md index 2da3a9574f46..bbf259c36693 100644 --- a/docs/core/api/useSuspense.md +++ b/docs/core/api/useSuspense.md @@ -1,9 +1,10 @@ --- -title: useSuspense() +title: useSuspense() - Simplified data fetching for React +sidebar_label: useSuspense() +description: High performance async data rendering without overfetching. useSuspense() is like await for React components. --- - useSuspense() - Simplified data fetching for React @@ -17,6 +18,8 @@ import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; import StackBlitz from '@site/src/components/StackBlitz'; import { detailFixtures, listFixtures } from '@site/src/fixtures/profiles'; +# useSuspense() +

High performance async data rendering without overfetching.

diff --git a/docs/core/concepts/atomic-mutations.md b/docs/core/concepts/atomic-mutations.md index 73804339b665..e01048381fe6 100644 --- a/docs/core/concepts/atomic-mutations.md +++ b/docs/core/concepts/atomic-mutations.md @@ -1,10 +1,9 @@ --- -title: Atomic Mutations ⚛ +title: '⚛ Atomic Mutations: Safe, high performance async mutations' sidebar_label: Atomic Mutations --- - ⚛ Atomic Mutations: Safe, high performance async mutations diff --git a/docs/core/concepts/error-policy.md b/docs/core/concepts/error-policy.md index 044b742cb3b9..8c795ca69468 100644 --- a/docs/core/concepts/error-policy.md +++ b/docs/core/concepts/error-policy.md @@ -1,16 +1,18 @@ --- -title: Endpoint Error Policy +title: Distinguishing recoverable fetch errors in React sidebar_label: Error Policy +description: Controlling how errors affect revalidation strategies in Reactive Data Client. --- - Distinguishing recoverable fetch errors in React import HooksPlayground from '@site/src/components/HooksPlayground'; import {RestEndpoint} from '@data-client/rest'; +# Endpoint Error Policy + [Endpoint.errorPolicy](/rest/api/Endpoint#errorpolicy) controls cache behavior upon a fetch rejection. It uses the rejection error to determine whether it should be treated as 'soft' or 'hard' error. diff --git a/docs/core/concepts/expiry-policy.md b/docs/core/concepts/expiry-policy.md index 392b6998758e..60693ecac0cc 100644 --- a/docs/core/concepts/expiry-policy.md +++ b/docs/core/concepts/expiry-policy.md @@ -1,16 +1,18 @@ --- -title: Endpoint Expiry Policy +title: Controlling automatic fetch behavior with declarative Expiry Policies sidebar_label: Expiry Policy +description: When data is considere Fresh, Stale, or Invalid. And how that state affects fetching and rendering. --- - Controlling automatic fetch behavior with declarative Expiry Policies import HooksPlayground from '@site/src/components/HooksPlayground'; import {RestEndpoint} from '@data-client/rest'; +# Endpoint Expiry Policy + By default, Reactive Data Client cache policy can be described as [stale-while-revalidate](https://web.dev/stale-while-revalidate/). This means that when data is available it can avoid blocking the application by using the stale data. However, in the background it will still refresh the data if old enough. diff --git a/docs/core/concepts/managers.md b/docs/core/concepts/managers.md index 9337497d6a8f..f0094fe5e66b 100644 --- a/docs/core/concepts/managers.md +++ b/docs/core/concepts/managers.md @@ -1,6 +1,8 @@ --- -title: Managers and Middleware +title: Centralized side-effect orchestration with React sidebar_label: Managers and Middleware +description: Safe programmatic access to the global store. Enables fully extensible and scalable side-effects. +image: /img/flux-full.png --- import ThemedImage from '@theme/ThemedImage'; @@ -8,10 +10,11 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; import StackBlitz from '@site/src/components/StackBlitz'; - Centralized side-effect orchestration with React +# Managers and Middleware + Reactive Data Client uses the [flux store](https://facebookarchive.github.io/flux/docs/in-depth-overview/) pattern, which is characterized by an easy to [understand and debug](../guides/debugging.md) the store's [undirectional data flow](). State updates are performed by a [reducer function](https://github.com/reactive/data-client/blob/master/packages/core/src/state/reducer/createReducer.ts#L19). diff --git a/docs/core/concepts/validation.md b/docs/core/concepts/validation.md index f184ed44c74c..b7b01b944096 100644 --- a/docs/core/concepts/validation.md +++ b/docs/core/concepts/validation.md @@ -1,16 +1,17 @@ --- -title: API Validation +title: Validating fetch responses in React sidebar_label: Validation --- - Validating fetch responses in React import HooksPlayground from '@site/src/components/HooksPlayground'; import {RestEndpoint} from '@data-client/rest'; +# API Validation + [Entity.validate()](/rest/api/Entity#validate) is called during normalization and denormalization. `undefined` indicates no error, and a string error message if there is an error. diff --git a/docs/core/getting-started/data-dependency.md b/docs/core/getting-started/data-dependency.md index 46504c432847..dba4ffee2d16 100644 --- a/docs/core/getting-started/data-dependency.md +++ b/docs/core/getting-started/data-dependency.md @@ -1,10 +1,9 @@ --- -title: Rendering Asynchronous Data +title: Rendering Asynchronous Data in React sidebar_label: Render Data --- - Rendering Asynchronous Data in React @@ -19,6 +18,8 @@ import { postFixtures } from '@site/src/fixtures/posts'; import { detailFixtures, listFixtures } from '@site/src/fixtures/profiles'; import UseLive from '../shared/\_useLive.mdx'; +# Rendering Asynchronous Data + Make your components reusable by binding the data where you **use** it with the one-line [useSuspense()](../api/useSuspense.md), which guarantees data like [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await). diff --git a/docs/core/getting-started/installation.md b/docs/core/getting-started/installation.md index 94278ec243bc..ffccddc9d061 100644 --- a/docs/core/getting-started/installation.md +++ b/docs/core/getting-started/installation.md @@ -1,12 +1,10 @@ --- id: installation -title: Installation +title: Getting Started with Reactive Data Client +sidebar_label: Installation +hide_title: true --- - - Getting Started with Reactive Data Client - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import PkgTabs from '@site/src/components/PkgTabs'; diff --git a/docs/core/getting-started/mutations.md b/docs/core/getting-started/mutations.md index e7eb8687cf5e..3cc886e8ddd2 100644 --- a/docs/core/getting-started/mutations.md +++ b/docs/core/getting-started/mutations.md @@ -1,6 +1,7 @@ --- -title: Data mutations +title: Mutating Asynchronous Data in React sidebar_label: Mutate Data +description: Safe and high performance data mutations without refetching or writing state management. --- import ProtocolTabs from '@site/src/components/ProtocolTabs'; @@ -12,10 +13,11 @@ import UseLoading from '../shared/\_useLoading.mdx'; import VoteDemo from '../shared/\_VoteDemo.mdx'; - Mutating Asynchronous Data in React +# Data mutations + Using our [Create, Update, and Delete](/docs/concepts/atomic-mutations) endpoints with [Controller.fetch()](../api/Controller.md#fetch) reactively updates _all_ appropriate components atomically (at the same time). diff --git a/docs/core/getting-started/resource.md b/docs/core/getting-started/resource.md index 095c5a00c275..745e0ff6d94f 100644 --- a/docs/core/getting-started/resource.md +++ b/docs/core/getting-started/resource.md @@ -1,10 +1,9 @@ --- -title: Define Resources +title: Defining Resources for Reactive Data Client sidebar_label: Define Data --- - Defining Resources for Reactive Data Client @@ -17,6 +16,8 @@ import ProtocolTabs from '@site/src/components/ProtocolTabs'; import PkgInstall from '@site/src/components/PkgInstall'; import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; +# Define Resources + [Resources](/rest/api/createResource) are a collection of `methods` for a given `data model`. [Entities](/rest/api/Entity) and [Schemas](/rest/api/schema) declaratively define the [_data model_](../concepts/normalization.md). diff --git a/docs/core/guides/custom-protocol.md b/docs/core/guides/custom-protocol.md index b6281b1d3d57..e7f9561e9fe3 100644 --- a/docs/core/guides/custom-protocol.md +++ b/docs/core/guides/custom-protocol.md @@ -3,15 +3,13 @@ title: TypeScript Standard Endpoints sidebar_label: Custom Protocol --- - - TypeScript Standard Endpoints - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import LanguageTabs from '@site/src/components/LanguageTabs'; import PkgTabs from '@site/src/components/PkgTabs'; +# TypeScript Standard Endpoints + [Endpoints](/rest/api/Endpoint) describe an asynchronous [API](https://www.freecodecamp.org/news/what-is-an-api-in-english-please-b880a3214a82/). This includes both runtime behavior as well as (optionally) typing. diff --git a/docs/core/guides/img-media.md b/docs/core/guides/img-media.md index ca9818de8804..ef3dc47ff0fb 100644 --- a/docs/core/guides/img-media.md +++ b/docs/core/guides/img-media.md @@ -1,15 +1,14 @@ --- -title: Images and other Media +title: React 18 Suspense with Images and other Media +sidebar_label: Images and other Media --- - - React 18 Suspense with Images and other Media - - import PkgTabs from '@site/src/components/PkgTabs'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +# Images and other Media + After setting up Reactive Data Client for structured data fetching, you might want to incorporate some media fetches as well to take advantage of suspense and [concurrent mode support](/docs/guides/render-as-you-fetch). diff --git a/docs/core/guides/redux.md b/docs/core/guides/redux.md index 64aea460ed56..997ac1b94a1e 100644 --- a/docs/core/guides/redux.md +++ b/docs/core/guides/redux.md @@ -1,16 +1,15 @@ --- id: redux -title: Redux integration +title: Empowering Redux with Reactive Data Client +sidebar_label: Redux integration --- - - Empowering Redux with Reactive Data Client - - import PkgTabs from '@site/src/components/PkgTabs'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +# Redux integration + Using [redux](https://redux.js.org/) is completely optional. However, for many it means easy integration or migration with existing projects, or just a nice centralized state management abstraction. diff --git a/docs/core/guides/ssr.md b/docs/core/guides/ssr.md index aeff48584b1d..2b47bb96a4f9 100644 --- a/docs/core/guides/ssr.md +++ b/docs/core/guides/ssr.md @@ -1,16 +1,18 @@ --- id: ssr -title: Server Side Rendering +title: Server Side Rendering with NextJS, Express, and more +sidebar_label: Server Side Rendering --- import PkgTabs from '@site/src/components/PkgTabs'; import StackBlitz from '@site/src/components/StackBlitz'; - Server Side Rendering with NextJS, Express, and more +# Server Side Rendering + Server Side Rendering (SSR) can improve the first-load performance of your application. Reactive Data Client takes this one step further by pre-populating the data store. Unlike other SSR methodologies, Reactive Data Client becomes interactive the moment the page is visible, making [data mutations](https://dataclient.io/docs/getting-started/mutations) instantaneous. Additionally there is no need for additional data fetches that increase server diff --git a/docs/core/guides/storybook.md b/docs/core/guides/storybook.md index 58edfde3ebec..38c40aeed2bc 100644 --- a/docs/core/guides/storybook.md +++ b/docs/core/guides/storybook.md @@ -1,15 +1,17 @@ --- title: Mocking data for Storybook +sidebar_label: Mocking data for Storybook --- - Mocking data for Storybook import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +# Mocking data for Storybook + [Storybook](https://storybook.js.org/) is a great utility to do isolated development and testing, potentially speeding up development time greatly. diff --git a/docs/graphql/README.md b/docs/graphql/README.md index b7bc8220a7ae..2cdbb63abfd7 100644 --- a/docs/graphql/README.md +++ b/docs/graphql/README.md @@ -1,13 +1,10 @@ --- id: README -title: GraphQL Usage +title: GraphQL Usage with Reactive Data Client sidebar_label: Usage +hide_title: true --- - - GraphQL Usage with Reactive Data Client - - import LanguageTabs from '@site/src/components/LanguageTabs'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/graphql/auth.md b/docs/graphql/auth.md index 3def718c679d..9d2425dc050b 100644 --- a/docs/graphql/auth.md +++ b/docs/graphql/auth.md @@ -1,14 +1,13 @@ --- -title: GraphQL Authentication +title: GraphQL Authentication patterns for Reactive Data Client sidebar_label: Authentication --- - - GraphQL Authentication patterns for Reactive Data Client - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +# GraphQL Authentication + ## Cookie Auth Here's an example using simple cookie auth: diff --git a/docs/rest/README.md b/docs/rest/README.md index db2ff70fc22b..5ec8ba99126c 100644 --- a/docs/rest/README.md +++ b/docs/rest/README.md @@ -1,13 +1,11 @@ --- id: README -title: REST Usage +title: Using REST APIs with Reactive Data Client sidebar_label: Usage +description: Writing TypeScript REST APIs quickly using path templates and Schemas. +hide_title: true --- - - Using REST APIs with Reactive Data Client - - import LanguageTabs from '@site/src/components/LanguageTabs'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/rest/api/All.md b/docs/rest/api/All.md index 6df1e20b0232..45853508f7ff 100644 --- a/docs/rest/api/All.md +++ b/docs/rest/api/All.md @@ -1,17 +1,16 @@ --- -title: schema.All +title: schema.All - Access every entity in the Reactive Data Client store +sidebar_label: schema.All --- - - schema.All - Access every entity in the Reactive Data Client store - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import LanguageTabs from '@site/src/components/LanguageTabs'; import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; +# schema.All + Retrieves all entities in cache as an Array. - `definition`: **required** A singular [Entity](./Entity.md) that this array contains _or_ a mapping of attribute values to [Entities](./Entity.md). diff --git a/docs/rest/api/Array.md b/docs/rest/api/Array.md index 81737a4df54b..0626807c1368 100644 --- a/docs/rest/api/Array.md +++ b/docs/rest/api/Array.md @@ -1,17 +1,16 @@ --- -title: schema.Array +title: schema.Array - Declarative list data for React +sidebar_label: schema.Array --- - - schema.Array - Declarative list data for React - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import LanguageTabs from '@site/src/components/LanguageTabs'; import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; +# schema.Array + Creates a schema to normalize an array of schemas. If the input value is an [Object](./Object.md) instead of an `Array`, the normalized result will be an `Array` of the [Object](./Object.md)'s values. diff --git a/docs/rest/api/Collection.md b/docs/rest/api/Collection.md index b42703f62a85..c3b80caa977f 100644 --- a/docs/rest/api/Collection.md +++ b/docs/rest/api/Collection.md @@ -1,11 +1,8 @@ --- -title: schema.Collection +title: schema.Collection - Entities of Arrays or Values +sidebar_label: schema.Collection --- - - schema.Collection - Entities of Arrays or Values - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import LanguageTabs from '@site/src/components/LanguageTabs'; @@ -14,6 +11,8 @@ import { RestEndpoint } from '@data-client/rest'; import { v4 as uuid } from 'uuid'; import { postFixtures,getInitialInterceptorData } from '@site/src/fixtures/posts-collection'; +# schema.Collection + `Collections` are entities but for [Arrays](./Array.md) or [Values](./Values.md). This makes them well suited at handling mutations. You can add to [Array](./Array.md) `Collections` with [.push](#push) or [.unshift](#unshift) and diff --git a/docs/rest/api/Endpoint.md b/docs/rest/api/Endpoint.md index d61353d116b5..25d217ae2f21 100644 --- a/docs/rest/api/Endpoint.md +++ b/docs/rest/api/Endpoint.md @@ -1,15 +1,14 @@ --- -title: Endpoint +title: Endpoint - Strongly typed API definitions +sidebar_label: Endpoint --- - - Endpoint - Strongly typed API definitions - - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import HooksPlayground from '@site/src/components/HooksPlayground'; +# Endpoint + `Endpoint` are for any asynchronous function (one that returns a Promise). `Endpoints` define a strongly typed standard interface of relevant metadata and lifecycles diff --git a/docs/rest/api/Entity.md b/docs/rest/api/Entity.md index 896255c1d022..e6fad39dc8ac 100644 --- a/docs/rest/api/Entity.md +++ b/docs/rest/api/Entity.md @@ -1,9 +1,9 @@ --- -title: Entity +title: Entity - Declarative unique objects for React +sidebar_label: Entity --- - Entity - Declarative unique objects for React @@ -12,6 +12,8 @@ import LanguageTabs from '@site/src/components/LanguageTabs'; import { RestEndpoint } from '@data-client/rest'; import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; +# Entity +
```ts diff --git a/docs/rest/api/Invalidate.md b/docs/rest/api/Invalidate.md index 1bc3be551b9c..ea3d19c15fc2 100644 --- a/docs/rest/api/Invalidate.md +++ b/docs/rest/api/Invalidate.md @@ -1,13 +1,13 @@ --- -title: schema.Invalidate +title: schema.Invalidate - Invalidating Entities +sidebar_label: schema.Invalidate --- - - schema.Invalidate - Invalidating Entities - import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; +# schema.Invalidate + Describes entities to be marked as [INVALID](/docs/concepts/expiry-policy#invalid). This removes items from a collection, or [forces suspense](/docs/concepts/expiry-policy#any-endpoint-with-an-entity) for endpoints where the entity is required. diff --git a/docs/rest/api/Object.md b/docs/rest/api/Object.md index ad8cf8a0b399..33fd0290b124 100644 --- a/docs/rest/api/Object.md +++ b/docs/rest/api/Object.md @@ -1,15 +1,14 @@ --- -title: schema.Object +title: schema.Object - Declarative Object data for React +sidebar_label: schema.Object --- - - schema.Object - Declarative Object data for React - - import LanguageTabs from '@site/src/components/LanguageTabs'; import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; +# schema.Object + Define a plain object mapping that has values needing to be normalized into Entities. _Note: The same behavior can be defined with shorthand syntax: `{ ... }`_ - `definition`: **required** A definition of the nested entities found within this object. Defaults to empty object. diff --git a/docs/rest/api/Query.md b/docs/rest/api/Query.md index a00da45c72d2..69e506081bfd 100644 --- a/docs/rest/api/Query.md +++ b/docs/rest/api/Query.md @@ -1,15 +1,17 @@ --- -title: schema.Query +title: Query - Programmatic memoized store access +sidebar_label: schema.Query --- - Query - Programmatic performant store access import { RestEndpoint } from '@data-client/rest'; import HooksPlayground from '@site/src/components/HooksPlayground'; +# schema.Query + `Query` provides programmatic access to the Reactive Data Client cache while maintaining the same high performance and referential equality guarantees expected of Reactive Data Client. diff --git a/docs/rest/api/RestEndpoint.md b/docs/rest/api/RestEndpoint.md index d9deb055b576..79aaac5b2893 100644 --- a/docs/rest/api/RestEndpoint.md +++ b/docs/rest/api/RestEndpoint.md @@ -1,10 +1,10 @@ --- -title: RestEndpoint -description: Strongly typed path-based API definitions. +title: RestEndpoint - Strongly typed path-based HTTP API definitions +sidebar_label: RestEndpoint +description: Strongly typed path-based extensible HTTP API definitions. --- - RestEndpoint - Strongly typed path-based HTTP API definitions @@ -15,6 +15,8 @@ import EndpointPlayground from '@site/src/components/HTTP/EndpointPlayground'; import Grid from '@site/src/components/Grid'; import Link from '@docusaurus/Link'; +# RestEndpoint + `RestEndpoints` are for [HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) based protocols like REST. :::info extends @@ -160,7 +162,7 @@ export const updateTodo = getTodo.extend({ method: 'PUT' }); -Using a [Schema](./schema.md) enables automatic data consistency without the need to hurt performance with [refetching](/docs/api/Controller#expireAll). +Using a [Schema](./schema.md) enables [automatic data consistency](/docs/concepts/normalization) without the need to hurt performance with [refetching](/docs/api/Controller#expireAll). ### Typing diff --git a/docs/rest/api/Union.md b/docs/rest/api/Union.md index 6433852a6f2d..379db0f6e5fa 100644 --- a/docs/rest/api/Union.md +++ b/docs/rest/api/Union.md @@ -1,15 +1,15 @@ --- -title: schema.Union +titlke: schema.Union - Declarative polymorphic data for React +sidebar_label: schema.Union --- - - schema.Union - Declarative polymorphic data for React - import LanguageTabs from '@site/src/components/LanguageTabs'; import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; import StackBlitz from '@site/src/components/StackBlitz'; +# schema.Union + Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by [schema.Array](./Array.md) or [schema.Values](./Values.md) but for non-collection fields. - `definition`: **required** An object mapping the definition of the nested entities found within the input array diff --git a/docs/rest/api/Values.md b/docs/rest/api/Values.md index a75d823fccbb..e079bd9c9fea 100644 --- a/docs/rest/api/Values.md +++ b/docs/rest/api/Values.md @@ -1,15 +1,14 @@ --- -title: schema.Values +title: schema.Values - Declarative map data for React +sidebar_label: schema.Values --- - - schema.Values - Declarative map data for React - - import LanguageTabs from '@site/src/components/LanguageTabs'; import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; +# schema.Values + Like [Array](./Array), `Values` are unbounded in size. The definition here describes the types of values to expect, with keys being any string. diff --git a/docs/rest/api/createResource.md b/docs/rest/api/createResource.md index 3d5d7c225439..ca23d457d340 100644 --- a/docs/rest/api/createResource.md +++ b/docs/rest/api/createResource.md @@ -1,10 +1,10 @@ --- id: createResource -title: createResource +title: createResource() - TypeScript definition for REST API resources +sidebar_label: createResource --- - createResource() - TypeScript definition for REST API resources @@ -14,6 +14,8 @@ import EndpointPlayground from '@site/src/components/HTTP/EndpointPlayground'; import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; import DeleteProcess from './\_DeleteProcess.mdx'; +# createResource + `Resources` are a collection of [RestEndpoints](./RestEndpoint.md) that operate on a common data by sharing a [schema](./schema.md) diff --git a/docs/rest/api/hookifyResource.md b/docs/rest/api/hookifyResource.md index 228cab355cbe..530f7e6e9b54 100644 --- a/docs/rest/api/hookifyResource.md +++ b/docs/rest/api/hookifyResource.md @@ -1,9 +1,9 @@ --- -title: hookifyResource +title: hookifyResource() - Collection of CRUD hook Endpoints +sidebar_label: hookifyResource --- - hookifyResource() - Collection of CRUD hook Endpoints @@ -11,6 +11,8 @@ import LanguageTabs from '@site/src/components/LanguageTabs'; import HooksPlayground from '@site/src/components/HooksPlayground'; import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; +# hookfiyResource + `hookifyResource()` Turns any [Resource](./createResource.md) (collection of [RestEndpoints](./RestEndpoint.md)) into a collection of hooks that return [RestEndpoints](./RestEndpoint.md). diff --git a/docs/rest/api/schema.Entity.md b/docs/rest/api/schema.Entity.md index e2cee53e50c3..87b3b02c3b17 100644 --- a/docs/rest/api/schema.Entity.md +++ b/docs/rest/api/schema.Entity.md @@ -1,9 +1,9 @@ --- -title: schema.Entity +title: schema.Entity - Entity mixin +sidebar_label: schema.Entity --- - schema.Entity - Entity mixin @@ -12,6 +12,8 @@ import LanguageTabs from '@site/src/components/LanguageTabs'; import { RestEndpoint } from '@data-client/rest'; import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; +# schema.Entity + `Entity` defines a single _unique_ object. If you already have classes for your data-types, `schema.Entity` mixin may be for you. diff --git a/docs/rest/guides/optimistic-updates.md b/docs/rest/guides/optimistic-updates.md index 9640aaa6cee7..d494ebde5ea7 100644 --- a/docs/rest/guides/optimistic-updates.md +++ b/docs/rest/guides/optimistic-updates.md @@ -1,9 +1,9 @@ --- -title: Optimistic Updates +title: Making React 100x faster with Optimistic Updates +sidebar_label: Optimistic Updates --- - Making React 100x faster with Optimistic Updates @@ -12,6 +12,8 @@ import {RestEndpoint} from '@data-client/rest'; import { todoFixtures } from '@site/src/fixtures/todos'; import OptimisticTransform from '../shared/\_optimisticTransform.mdx'; +# Optimistic Updates + Optimistic updates enable highly responsive and fast interfaces by avoiding network wait times. An update is optimistic by assuming the network is successful. diff --git a/docs/rest/guides/pagination.md b/docs/rest/guides/pagination.md index ff288f9a1c4e..1b165f93c7ba 100644 --- a/docs/rest/guides/pagination.md +++ b/docs/rest/guides/pagination.md @@ -1,5 +1,5 @@ --- -title: Rest Pagination +title: Pagination of REST data with Reactive Data Client sidebar_label: Pagination --- @@ -7,9 +7,7 @@ import StackBlitz from '@site/src/components/StackBlitz'; import { postPaginatedFixtures } from '@site/src/fixtures/posts'; import HooksPlayground from '@site/src/components/HooksPlayground'; - - Pagination of REST data with Reactive Data Client - +# Rest Pagination ## Expanding Lists diff --git a/docs/rest/guides/relational-data.md b/docs/rest/guides/relational-data.md index 3c5ddfe7c799..c26fd638dc2d 100644 --- a/docs/rest/guides/relational-data.md +++ b/docs/rest/guides/relational-data.md @@ -1,16 +1,14 @@ --- -title: Relational data +title: Simplified relational data rendering in React sidebar_label: Relational data --- - - Simplified relational data rendering in React - - import HooksPlayground from '@site/src/components/HooksPlayground'; import { RestEndpoint } from '@data-client/rest'; import StackBlitz from '@site/src/components/StackBlitz'; +# Relational data + Reactive Data Client handles one-to-one, many-to-one and many-to-many relationships on [entities][1] using [Entity.schema][3] diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index de6181221fbc..6e47738458ab 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -51,7 +51,7 @@ const config: Config = { tagName: 'link', attributes: { name: 'application-name', - content: 'Reactive Data Client', + content: 'Data Client', }, }, { @@ -424,9 +424,10 @@ const config: Config = { }, TODO: Add back when we have versions to upgrade*/ { to: 'demos', - //label: '🎮 Demos', - position: 'right', - className: 'header-demos-link', + label: 'Demos', + position: 'left', + // TODO: move this to right once we get a better image that is more obvious (cube with play triangle inside) + //className: 'header-demos-link', 'aria-label': 'Demo Applications', }, {