[IMPL] For Component

Author: nDriaDev

apps/react-tools-demo/src/layout/MainLayout.tsx

@@ -1252,6 +1252,17 @@ export default function MainLayout() {
 							useWebWorkerFn
 						</Link>
 						<p className="sub-type">Components</p>
+						<Link
+							className={pathname === "/components/For" ? 'active' : ''}
+							ref={node => linksRef.current["For"] = node}
+							to="/components/For"
+							onClick={() => {
+								containerRef.current?.scrollTo(0, 0);
+								window.innerWidth < 1190 && closeNav();
+							}}
+						>
+							For
+						</Link>
 						<Link
 							className={pathname === "/components/Lazy" ? 'active' : ''}
 							ref={node => linksRef.current["Lazy"] = node}

apps/react-tools-demo/src/markdown/For.md

@@ -0,0 +1,69 @@
+# For
+Component to optimize the rendering of a list of elements without need to specify a key value for all elements, and other options. [See demo](https://nDriaDev.io/react-tools/#/components/For)
+
+## Usage
+
+```tsx
+export default function ForComponent() {
+	const arr = useRef([
+		{ id: "1", firstName: "Jhon", lastName: "Doe" },
+		{ id: "2", firstName: "Jona", lastName: "Doe" },
+		{ id: "3", firstName: "Jhonney", lastName: "Doe" }
+	]);
+	const [, update] = useReducer(t => !t, false);
+
+	const body = useCallback<(item: { id: string, firstName: string, lastName: string }, index: number|string) => JSX.Element>((item, index) => {
+		console.log("body render");
+		return <p>{index}: {item.firstName} - {item.lastName}</p>
+	}, []);
+
+	useEffect(() => {
+		const id = setInterval(() => update(), 1000);
+		return () => clearInterval(id)
+	}, [])
+
+	return <>
+		<For
+			elementKey="id"
+			of={arr.current}
+		>
+			{body}
+		</For>
+	</>
+}
+```
+
+> The component uses _For_ component to render a p element returned from _body_ memoized function for all objects assigned to _arr_  ref variable. It also specified __id__ property as _elementKey_ prop. A setInverval is executed on mount that on every second force component to rerender. If you open dev tools, you can see that _body_ function logs only three times at first, one for each element of _arr_ variable
+
+
+## API
+
+```tsx
+Formemo(<T extends unknown>({ of, children, filter, map, sort, elementKey, fallback }: ForProps<T>)
+```
+
+> ### Params
+>
+> - __props__: _ForProps<T>_  
+component properties object.
+> - __props.of__: _T[]_  
+array of elements.
+> - __props.elementKey?__: _T extends Record<string,unknown> ? keyof T : never_  
+a key of array elements if elements are object.
+> - __props.children__: _(item: T, index: T extends Record<string,unknown> ? number | T[keyof T] : number) => ReactNode_  
+it's a function that takes the current item as first argument and optionally a second argument that is number if element of array aren't object, otherwise it can be a number or the value of the element key specified in the _elementKey_ prop if it is preset.
+> - __props.fallback?__: _ReactNode_  
+optional element to render when _of_ prop is an empty array.
+> - __props.filter?__: _<S extends T>(val: T, index: number, arr: T[]) => val is S_  
+callback executed to filter _of_ elements.
+> - __props.map?__: _<U extends T>(val: T, index: number, arr: T[]) => U_  
+callback executed to map _of_ elements.
+> - __props.sort?__: _(a: T, b: T) => number_  
+callback executed to sort _of_ elements.
+>
+
+> ### Returns
+>
+> __result__: elements list, rendered from _of_ prop or _fallback_.
+> - _JSX.Element_  
+>

apps/react-tools-demo/src/markdown/SwitchCase.md

@@ -1,5 +1,5 @@
 # SwitchCase
-It works like switch-case construct. It useful for when there are more than 2 mutual exclusive conditions.
+It works like switch-case construct. It useful for when there are more than 2 mutual exclusive conditions. [See demo](https://nDriaDev.io/react-tools/#/components/SwitchCase)
 
 ## Usage
 

apps/react-tools-demo/src/pages/components/for/For.tsx

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useReducer, useRef } from "react";
+import { For } from "../../../../../../packages/react-tools/src";
+
+/**
+The component uses _For_ component to render a p element returned from _body_ memoized function for all objects assigned to _arr_  ref variable. It also specified __id__ property as _elementKey_ prop. A setInverval is executed on mount that on every second force component to rerender. If you open dev tools, you can see that _body_ function logs only three times at first, one for each element of _arr_ variable
+ */
+export default function ForComponent() {
+	const arr = useRef([
+		{ id: "1", firstName: "Jhon", lastName: "Doe" },
+		{ id: "2", firstName: "Jona", lastName: "Doe" },
+		{ id: "3", firstName: "Jhonney", lastName: "Doe" }
+	]);
+	const [, update] = useReducer(t => !t, false);
+
+	const body = useCallback<(item: { id: string, firstName: string, lastName: string }, index: number|string) => JSX.Element>((item, index) => {
+		console.log("body render");
+		return <p>{index}: {item.firstName} - {item.lastName}</p>
+	}, []);
+
+	useEffect(() => {
+		const id = setInterval(() => update(), 1000);
+		return () => clearInterval(id)
+	}, [])
+
+	return <>
+		<For
+			elementKey="id"
+			of={arr.current}
+		>
+			{body}
+		</For>
+	</>
+}

apps/react-tools-demo/src/router/Router.tsx

@@ -3,6 +3,7 @@ import { RouterProvider, createHashRouter, Outlet, Navigate } from 'react-router
 import MainLayout from '../layout/MainLayout';
 import ComponentLayout from '../layout/ComponentLayout';
 import { Spinner } from '../layout/Spinner';
+import ForMD from "../markdown/For.md?raw"
 import LazyMD from "../markdown/Lazy.md?raw"
 import ShowMD from "../markdown/Show.md?raw"
 import SwitchCaseMD from "../markdown/SwitchCase.md?raw"
@@ -133,6 +134,7 @@ import useVisibleMD from "../markdown/useVisible.md?raw"
 import useWebSocketMD from "../markdown/useWebSocket.md?raw"
 import useWebWorkerMD from "../markdown/useWebWorker.md?raw"
 import useWebWorkerFnMD from "../markdown/useWebWorkerFn.md?raw"
+const For = lazy((() => import('../pages/components/for/For').then(module => ({default: "default" in module ? module["default"] : module["For"]}))) as unknown as () => Promise<{ default: ComponentType; }>)
 const Lazy = lazy((() => import('../pages/components/lazy/Lazy').then(module => ({default: "default" in module ? module["default"] : module["Lazy"]}))) as unknown as () => Promise<{ default: ComponentType; }>)
 const Show = lazy((() => import('../pages/components/show/Show').then(module => ({default: "default" in module ? module["default"] : module["Show"]}))) as unknown as () => Promise<{ default: ComponentType; }>)
 const SwitchCase = lazy((() => import('../pages/components/switchCase/SwitchCase').then(module => ({default: "default" in module ? module["default"] : module["SwitchCase"]}))) as unknown as () => Promise<{ default: ComponentType; }>)
@@ -980,8 +982,14 @@ function Router() {
 					children: [
 						{
 							index: true,
-							element: <Navigate to={"/components/Lazy"} replace/>,
+							element: <Navigate to={"/components/For"} replace/>,
 						},
+					{
+						path: "For",
+						element: <Suspense fallback={<Spinner/>}>
+							<ComponentLayout markdown={ForMD} component={<For/>}/>
+						</Suspense>
+					},
 					{
 						path: "Lazy",
 						element: <Suspense fallback={<Spinner/>}>

packages/react-tools/README.md

@@ -149,7 +149,7 @@
 - __COMPONENT__
 	- [x] Show
 	- [x] SwitchCase
-	- [ ] For/Each: A referentially keyed loop with efficient updating of only changed items. The callback takes the current item as the first argument (ref https://javascript.plainenglish.io/react-each-and-of-pattern-b00aa4305089)
+	- [x] For
 	- [ ] Index: Non-keyed list iteration (rendered nodes are keyed to an array index). This is useful when there is no conceptual key, like if the data consists of primitives and it is the index that is fixed rather than the value.
 	- [ ] RestrictedRoute (maybe)
 	- [ ] ErrorBoundary (?? error event listener)

packages/react-tools/src/components/For.tsx

@@ -0,0 +1,33 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-type-constraint */
+import { Children, memo } from "react";
+import { ForProps } from "../models";
+
+/**
+ * **`For`**: Component to optimize the rendering of a list of elements without need to specify a key value for all elements, and other options. [See demo](https://nDriaDev.io/react-tools/#/components/For)
+ * @param {ForProps<T>} props - component properties object.
+ * @param {T[]} props.of - array of elements.
+ * @param {T extends Record<string,unknown> ? keyof T : never} [props.elementKey] - a key of array elements if elements are object.
+ * @param {(item: T, index: T extends Record<string,unknown> ? number | T[keyof T] : number) => ReactNode} props.children - it's a function that takes the current item as first argument and optionally a second argument that is number if element of array aren't object, otherwise it can be a number or the value of the element key specified in the _elementKey_ prop if it is preset.
+ * @param {ReactNode} [props.fallback] - optional element to render when _of_ prop is an empty array.
+ * @param {<S extends T>(val: T, index: number, arr: T[]) => val is S} [props.filter] - callback executed to filter _of_ elements.
+ * @param {<U extends T>(val: T, index: number, arr: T[]) => U} [props.map] - callback executed to map _of_ elements.
+ * @param {(a: T, b: T) => number} [props.sort] - callback executed to sort _of_ elements.
+ * @returns {JSX.Element} result - elements list, rendered from _of_ prop or _fallback_.
+ */
+export const For = memo(<T extends unknown>({ of, children, filter, map, sort, elementKey, fallback }: ForProps<T>) => {
+	if (of.length === 0) {
+		return <>{fallback}</>
+	}
+	let arr: T[] = sort ? of.sort(sort) : of;
+	arr = filter ? arr.filter(filter) : arr;
+	arr = map ? arr.map(map) : arr;
+	return (
+		<>
+			{Children.toArray(
+				arr.map((item, index) => (
+					children(item, (elementKey ? item[elementKey] : index) as T extends Record<string, unknown> ? number | T[keyof T] : number)
+				))
+			)}
+		</>
+	);
+}) as <T extends unknown>(props: ForProps<T>) => JSX.Element;

packages/react-tools/src/components/SwitchCase.tsx

@@ -8,7 +8,7 @@ const Case = ({ children, when }: PropsWithChildren<{ when: boolean | undefined
 }
 
 /**
- * **`SwitchCase`**: It works like switch-case construct. It useful for when there are more than 2 mutual exclusive conditions.
+ * **`SwitchCase`**: It works like switch-case construct. It useful for when there are more than 2 mutual exclusive conditions. [See demo](https://nDriaDev.io/react-tools/#/components/SwitchCase)
  * @param {ReactNode} [object.fallback] - optional element to render when _when_ prop is false.
  * @param {PropsWithChildren<any>["children"]} [object.children] - __Case__ components.
  * @returns {JSX.Element|null} element - __Case__ component with _when_ prop value __`true`__ or _fallback_ prop.

packages/react-tools/src/components/index.ts

@@ -1,3 +1,4 @@
 export { Lazy } from './Lazy';
 export { Show } from './Show';
-export { SwitchCase } from './SwitchCase';
+export { SwitchCase } from './SwitchCase';
+export { For } from './For';

packages/react-tools/src/index.ts

@@ -25,6 +25,7 @@ export type {
 	ExtractHead,
 	ExtractMiddle,
 	ExtractTail,
+	ForProps,
 	GeoLocationObject,
 	HTMLAttributes,
 	HTMLMediaControls,
@@ -212,8 +213,9 @@ export {
 } from './hooks'
 
 export {
-	Show,
+	For,
 	Lazy,
+	Show,
 	SwitchCase
 } from './components'