autosuspense 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,42 @@
 # AutoSupense
-AutoSuspense is a simple react library allowing user's to automatically wire suspense components based on there component structure automatically without building additional fallback UI.
+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.
 
 ## How to use?:
 1. Install this library
-```npm i autosuspense```
+```npm i autosuspense```
+
+2. Use it by calling and passing your components normally like ```<Supense>```:
+```
+import { AutoSuspense } from "autosuspense";
+
+function App() {
+  return (
+    <AutoSuspense>
+      <Page />
+    </AutoSuspense>
+  );
+}
+```
+
+3. Inside each AutoSuspense component provide a fallback componet for that particular component via ```useSuspenseFallback``` hook.
+```
+import { useSuspenseFallback } from "autosuspense";
+
+function UserCard() {
+  useSuspenseFallback(<div>Loading user…</div>);
+
+  // Component may suspend somewhere below
+  return <Profile />;
+}
+```
+
+### 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.

package/package.json

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

package/src/components/index.ts

@@ -1,3 +1,3 @@
-import { AutoSuspense } from "./AutoSuspense";
-import { GeneratedFallback } from "./GeneratedFallback";
+import { AutoSuspense } from "./suspense/AutoSuspense";
+import { GeneratedFallback } from "./suspense/GeneratedFallback";
 export { AutoSuspense, GeneratedFallback };

package/src/components/prefabs/defaultPrefab.tsx

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { Block } from "./prebuilt/Block";
+import { Card } from "./prebuilt/Card";
+import { List } from "./prebuilt/List";
+
+export const defaultPrefab: Record<string, React.ReactElement> = {
+  block: <Block />,
+  card: <Card />,
+  list: <List />,
+};

package/src/components/prefabs/prebuilt/Block.css

@@ -0,0 +1,42 @@
+.as-block {
+  width: 100%;
+  min-height: var(--as-block-min-height, 96px);
+  border-radius: var(--as-block-radius, 12px);
+  box-sizing: border-box;
+
+  background: var(
+    --as-block-bg,
+    linear-gradient(
+      90deg,
+      var(--as-skeleton-base, #ececec) 25%,
+      var(--as-skeleton-highlight, #f5f5f5) 37%,
+      var(--as-skeleton-base, #ececec) 63%
+    )
+  );
+
+  background-size: 400% 100%;
+  animation:
+    as-shimmer 1.4s ease infinite,
+    as-pulse 2s ease-in-out infinite;
+}
+
+@keyframes as-shimmer {
+  0% {
+    background-position: 100% 0;
+  }
+  100% {
+    background-position: 0 0;
+  }
+}
+
+@keyframes as-pulse {
+  0% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.85;
+  }
+  100% {
+    opacity: 1;
+  }
+}

package/src/components/prefabs/prebuilt/Block.tsx

@@ -0,0 +1,16 @@
+import * as React from "react";
+import "./Block.css";
+
+type BlockProps = {
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+export const Block: React.FC<BlockProps> = ({ children, className, style }) => {
+  return (
+    <div className={`as-block ${className ?? ""}`} style={style} data-as-block>
+      {children}
+    </div>
+  );
+};

package/src/components/prefabs/prebuilt/Card.css

@@ -0,0 +1,45 @@
+.as-card {
+  width: 100%;
+  min-height: var(--as-card-min-height, 120px);
+  padding: var(--as-card-padding, 16px);
+  box-sizing: border-box;
+
+  border-radius: var(--as-card-radius, 12px);
+
+  background: var(
+    --as-card-bg,
+    linear-gradient(
+      90deg,
+      var(--as-skeleton-base, #ececec) 25%,
+      var(--as-skeleton-highlight, #f5f5f5) 37%,
+      var(--as-skeleton-base, #ececec) 63%
+    )
+  );
+
+  background-size: 400% 100%;
+  animation:
+    as-shimmer 1.4s ease infinite,
+    as-pulse 2s ease-in-out infinite;
+}
+
+/* reuse same animations */
+@keyframes as-shimmer {
+  0% {
+    background-position: 100% 0;
+  }
+  100% {
+    background-position: 0 0;
+  }
+}
+
+@keyframes as-pulse {
+  0% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.85;
+  }
+  100% {
+    opacity: 1;
+  }
+}

package/src/components/prefabs/prebuilt/Card.tsx

@@ -0,0 +1,16 @@
+import * as React from "react";
+import "./Card.css";
+
+type CardProps = {
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+export const Card: React.FC<CardProps> = ({ children, className, style }) => {
+  return (
+    <div className={`as-card ${className ?? ""}`} style={style} data-as-card>
+      {children}
+    </div>
+  );
+};

package/src/components/prefabs/prebuilt/List.css

@@ -0,0 +1,48 @@
+.as-list {
+  width: 100%;
+  min-height: var(--as-list-min-height, 160px);
+  padding: var(--as-list-padding, 12px);
+  box-sizing: border-box;
+
+  border-radius: var(--as-list-radius, 8px);
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--as-list-gap, 12px);
+
+  background: var(
+    --as-list-bg,
+    linear-gradient(
+      90deg,
+      var(--as-skeleton-base, #ececec) 25%,
+      var(--as-skeleton-highlight, #f5f5f5) 37%,
+      var(--as-skeleton-base, #ececec) 63%
+    )
+  );
+
+  background-size: 400% 100%;
+  animation:
+    as-shimmer 1.4s ease infinite,
+    as-pulse 2s ease-in-out infinite;
+}
+
+@keyframes as-shimmer {
+  0% {
+    background-position: 100% 0;
+  }
+  100% {
+    background-position: 0 0;
+  }
+}
+
+@keyframes as-pulse {
+  0% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.85;
+  }
+  100% {
+    opacity: 1;
+  }
+}

package/src/components/prefabs/prebuilt/List.tsx

@@ -0,0 +1,16 @@
+import * as React from "react";
+import "./List.css";
+
+type ListProps = {
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+export const List: React.FC<ListProps> = ({ children, className, style }) => {
+  return (
+    <div className={`as-list ${className ?? ""}`} style={style} data-as-list>
+      {children}
+    </div>
+  );
+};

package/src/components/{AutoSuspense.tsx → suspense/AutoSuspense.tsx}

@@ -1,20 +1,30 @@
 import * as React from "react";
+
+import { GeneratedFallback } from "./GeneratedFallback";
 import {
   FallbackContext,
-  type FallbackRegistry,
-} from "../types/FallbackRegistry";
-import { GeneratedFallback } from "./GeneratedFallback";
+  FallbackRegistry,
+} from "../../types/FallbackRegistry";
+import { defaultPrefab } from "../prefabs/defaultPrefab";
 
-export const AutoSuspense = ({ children }: { children: React.ReactNode }) => {
+export const AutoSuspense = ({
+  children,
+  prefab = defaultPrefab,
+}: {
+  children: React.ReactNode;
+  prefab?: Record<string, React.ReactElement>;
+}) => {
   const registryRef = React.useRef<FallbackRegistry>({
     nodes: new Map(),
     currentParent: null,
+    prebuild: new Map(Object.entries(prefab)),
   });
 
   if (registryRef.current === null) {
     registryRef.current = {
       nodes: new Map(),
       currentParent: null,
+      prebuild: new Map(Object.entries(prefab)),
     };
   }
   const fallback = <GeneratedFallback registry={registryRef.current} />;

package/src/components/{GeneratedFallback.tsx → suspense/GeneratedFallback.tsx}

@@ -1,7 +1,7 @@
 import * as React from "react";
-import type { FallbackRegistry } from "../types/FallbackRegistry";
-import { buildTree } from "../utils/buildTree";
-import { renderNode } from "../utils/renderNode";
+import { FallbackRegistry } from "../../types/FallbackRegistry";
+import { buildTree } from "../../utils/buildTree";
+import { renderNode } from "../../utils/renderNode";
 
 export function GeneratedFallback({
   registry,
@@ -13,7 +13,7 @@ export function GeneratedFallback({
 
   return (
     <React.Fragment>
-      {roots.map((node) => renderNode(node, tree))}
+      {roots.map((node) => renderNode(node, tree, registry))}
     </React.Fragment>
   );
 }

package/src/types/FallbackRegistry.ts

@@ -1,14 +1,22 @@
-import { createContext, type ReactElement } from "react";
+import * as React from "react";
 
 export type Node = {
   id: string;
-  element: ReactElement;
+  element: FallbackDescriptor;
   parent: string | null;
 };
 
 export type FallbackRegistry = {
   nodes: Map<string, Node>;
   currentParent: string | null;
+  prebuild: Map<string, React.ReactElement | React.ComponentType<any>>;
 };
 
-export const FallbackContext = createContext<FallbackRegistry | null>(null);
+export type FallbackDescriptor =
+  | string
+  | React.ReactElement
+  | React.ComponentType;
+
+export const FallbackContext = React.createContext<FallbackRegistry | null>(
+  null,
+);

package/src/utils/renderNode.ts

@@ -1,15 +1,20 @@
 import React from "react";
-import type { Node } from "../types/FallbackRegistry";
+import type { FallbackRegistry, Node } from "../types/FallbackRegistry";
+import { resolveElement } from "./resolveElement";
 
 export function renderNode(
+  
   node: Node,
   childMap: Map<string | null, Node[]>,
-): React.ReactElement {
+  registry: FallbackRegistry,
+): React.ReactElement | null {
   const children = childMap.get(node.id) ?? [];
+  const resolvedEle = resolveElement(node.element, registry);
+  if (!resolvedEle) return null;
 
   return React.cloneElement(
-    node.element,
-    undefined,
-    children.map((child) => renderNode(child, childMap)),
+    resolvedEle,
+    { key: node.id },
+    children.map((child) => renderNode(child, childMap, registry)),
   );
 }

package/src/utils/resolveElement.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+import {
+  FallbackDescriptor,
+  FallbackRegistry,
+} from "../types/FallbackRegistry";
+
+export function resolveElement(
+  descriptor: FallbackDescriptor,
+  registry: FallbackRegistry,
+): React.ReactElement | null {
+  if (React.isValidElement(descriptor)) {
+    return descriptor;
+  }
+
+  if (typeof descriptor === "function") {
+    return React.createElement(descriptor);
+  }
+
+  if (typeof descriptor === "string") {
+    const value = registry.prebuild.get(descriptor);
+    if (!value) return null;
+
+    if (React.isValidElement(value)) {
+      return value;
+    }
+
+    const Component = value as React.ComponentType<any>;
+    return React.createElement(Component);
+  }
+
+  return null;
+}

package/tsconfig.json

@@ -1,9 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2020",
-    "module": "CommonJS",
-    "jsx": "react",
-    "lib": ["DOM", "ES2019"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+
+    "jsx": "react-jsx",
+    "lib": ["DOM", "ES2020"],
     "types": ["react"],
 
     "declaration": true,
@@ -14,8 +16,6 @@
     "rootDir": "./src",
 
     "strict": true,
-
-    "moduleResolution": "Bundler",
     "esModuleInterop": true,
     "skipLibCheck": true
   },