autosuspense 0.2.0 → 1.0.1

package/README.md

@@ -1,13 +1,51 @@
 # AutoSupense Beta
-AutoSuspense is a small React utility that automatically builds and composes
-Suspense fallback UI based on your component tree without manually wiring
-nested fallback components.
+AutoSuspense is a lightweight React utility that automatically composes Suspense fallback UI based on your component tree without manually wiring nested ```<Suspense>``` boundaries.
 
-## How to use:
-1. Install this library
-```npm i autosuspense```
+It lets you define fallback UI at the component level, while a parent ```<AutoSuspense>``` boundary handles rendering everything correctly.
 
-2. Use it by calling and passing your components normally like ```<Supense>```:
+---
+## Why AutoSuspense?:
+
+React Suspense solves async rendering, but fallback composition quickly becomes messy:
+```
+<Suspense fallback={<PageSkeleton />}>
+  <Header />
+  <Suspense fallback={<FeedSkeleton />}>
+    <Feed />
+  </Suspense>
+</Suspense>
+```
+AutoSuspense removes that boilerplate:
+```
+<AutoSuspense>
+  <Page />
+</AutoSuspense>
+```
+Each component defines it's own fallback and autosuspense builds the fallback tree for you.
+
+```
+import { Suspend } from "autosuspense";
+import Feed from "./Feed";
+import Sidebar from "./Sidebar";
+
+function Page() {
+  return (
+    <div>
+      <Feed />
+      <Sidebar />
+    </div>
+  );
+}
+
+export default Suspend(Page, <div>Loading page...</div>);
+```
+---
+
+## Installation:
+```npm install autosuspense```
+
+Usage
+1. Add AutoSuspense boundary
 ```
 import { AutoSuspense } from "autosuspense";
 
@@ -19,24 +57,107 @@ function App() {
   );
 }
 ```
+2. Wrap components with Suspend
+```
+import { Suspend } from "autosuspense";
 
-3. Inside each AutoSuspense component provide a fallback componet for that particular component via ```useSuspenseFallback``` hook.
+const UserCard = () => {
+  const data = resource.read(); // may suspend
+  return <div>{data.name}</div>;
+};
+
+export default Suspend(UserCard, <div>Loading user...</div>);
 ```
-import { useSuspenseFallback } from "autosuspense";
 
-function UserCard() {
-  useSuspenseFallback(<div>Loading user…</div>);
+- Nested components automatically compose
+```
+const Parent = () => <Child />;
+
+export default Suspend(Parent, <div>Outer Loader...</div>);
+const Child = () => {
+  const data = resource.read();
+  return <div>{data}</div>;
+};
+
+--- 
+
 
-  // Component may suspend somewhere below
-  return <Profile />;
+export default Suspend(Child, <div>Inner Loader...</div>);
+```
+👉 Resulting fallback:
+```
+Outer Loader...
+  Inner Loader...
+```
+
+## Using Prefabs (Reusable Fallbacks)
+Instead of passing JSX everywhere, define reusable fallbacks once.
+
+- Define prefabs at the root
+```
+import { AutoSuspense } from "autosuspense";
+import PageSkeleton from "./skeletons/PageSkeleton";
+import CardSkeleton from "./skeletons/CardSkeleton";
+
+function App() {
+  return (
+    <AutoSuspense
+      prefab={{
+        page: PageSkeleton,
+        card: CardSkeleton,
+      }}
+    >
+      <Page />
+    </AutoSuspense>
+  );
 }
+🎯 Use prefab keys in components
+import { Suspend } from "autosuspense";
+
+function Page() {
+  return <Feed />;
+}
+
+export default Suspend(Page, "page");
+function Feed() {
+  const data = resource.read();
+  return <div>{data}</div>;
+}
+
+export default Suspend(Feed, "card");
+```
+- Resulting fallback UI
+```
+PageSkeleton
+  CardSkeleton
+```
+
+## Core Idea:
+- Wrap a subtree with ```<AutoSuspense>```.
+- Wrap components with Suspend().
+- Each component declares its fallback.
+- AutoSuspense automatically composes the fallback UI tree without explicit maintaince and wiring.
+
+---
+## Fallback Options:
+
+You can provide fallbacks in multiple ways:
+
+1. JSX element:
+```
+Suspend(Component, <Skeleton />);
+```
+
+2. Component: 
+```
+Suspend(Component, SkeletonComponent);
+```
+
+3. String:
+```
+Suspend(Component, SkeletonComponent);
 ```
 
-### Important Caveats:
-1. This library works on top of existing Suspense blocks and prebuilds your Fallback UI via render tree traversal.
-2. This means that it uses Depth First searching to prebuild so react is only able to show prebuilt Ui when it first encounters a place to suspend. This could mean that rest of your fallback UI in next adjacent components never render.
+---
 
-### TBD:
-1. Adding Default Skeletons.
-2. Supporting existing Library skeleton implementations.
-3. Adding a central config & template extension components & file to easily extend and manage your Fallback UI.
+AutoSuspense aims to make and enhance fallback creation and make it's maintainence easier. 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosuspense",
-  "version": "0.2.0",
+  "version": "1.0.1",
   "description": "Automatic suspense wiring block for React.",
   "license": "ISC",
   "type": "commonjs",

package/src/components/prefabs/{defaultPrefab.tsx → defaultFallbacks.tsx}

@@ -3,7 +3,7 @@ import { Block } from "./prebuilt/Block";
 import { Card } from "./prebuilt/Card";
 import { List } from "./prebuilt/List";
 
-export const defaultPrefab: Record<string, React.ReactElement> = {
+export const defaultFallbacks: Record<string, React.ReactElement> = {
   block: <Block />,
   card: <Card />,
   list: <List />,

package/src/components/suspense/AutoSuspense.tsx

@@ -5,18 +5,18 @@ import {
   FallbackContext,
   FallbackRegistry,
 } from "../../types/FallbackRegistry";
-import { defaultPrefab } from "../prefabs/defaultPrefab";
+import { defaultFallbacks } from "../prefabs/defaultFallbacks";
 
 export const AutoSuspense = ({
   children,
-  prefab = defaultPrefab,
+  fallbacks = defaultFallbacks,
 }: {
   children: React.ReactNode;
-  prefab?: Record<string, React.ReactElement | React.ComponentType<any>>;
+  fallbacks?: Record<string, React.ReactElement | React.ComponentType<any>>;
 }) => {
   const registryRef = React.useRef<FallbackRegistry>({
     nodes: new Map(),
-    prebuild: new Map(Object.entries(prefab)),
+    prebuild: new Map(Object.entries(fallbacks)),
   });
 
   const fallback = <GeneratedFallback registry={registryRef.current} />;