feat: MatchOption component

Author: nDriaDev

src/components/MatchOption.tsx

@@ -0,0 +1,49 @@
+import { Children, isValidElement } from "react";
+import { MatchProps, OptionProps } from "../models";
+
+/**
+ * **`Match`**: Component used inside _MatchOption_ component to represent a match construct.
+ *
+ * @see [📖 Documentation](https://react-tools.ndria.dev/components/Match)
+ * @template T - The type of the `value` to be compared.
+ * @param {MatchProps<T>} props - {@link MatchProps}
+ * @returns {JSX.Element|null} element
+ */
+const Match = <T,>({ value, children, fallback }: MatchProps<T>) => {
+	const childrenArray = Children.toArray(children);
+
+	const match = childrenArray.find(
+		(child) => {
+			let result = false;
+			if (isValidElement(child)) {
+				if ("is" in child.props) {
+					result = typeof child.props.is === "function"
+						? child.props.is(value)
+						: child.props.is === value;
+				}
+			}
+			return result;
+		}
+	);
+
+	return match ?? fallback ?? null;
+};
+
+/**
+ * **`Option`**: Component used inside _MatchOption_ component to represent an option construct.
+ *
+ * @see [📖 Documentation](https://react-tools.ndria.dev/components/MatchOption)
+ * @template T - The type of the `is` value, should match the `value` type of the parent [Match].
+ * @param {OptionProps<T>} props - {@link OptionProps}
+ * @returns {JSX.Element|null} element
+ */
+const Option = <T,>({ children }: OptionProps<T>) => {
+	return children;
+};
+
+/**
+ * **`MatchOption`**: Provides a declarative switch-case pattern. It compares the [Match] component's `value` against the `is` prop of its [Option] children.
+ * The first matching [Option] is rendered; otherwise, the `fallback` is displayed.
+ * @see [📖 Documentation](https://react-tools.ndria.dev/components/MatchOption)
+ */
+export const MatchOption = { Match, Option };

src/components/MatchOptionMemoized.tsx

@@ -0,0 +1,18 @@
+import { memo } from "react";
+import { MatchOption } from "./MatchOption";
+
+//#IGNORE
+
+/**
+ * **`MatchOptionMemoized`**: Memoized version of _MatchOption_ component.
+ * Both [Match] and [Option] are wrapped with `React.memo`, preventing re-renders
+ * when their props have not changed.
+ * Prefer this over [MatchOption](https://react-tools.ndria.dev/components/MatchOption)
+ * in performance-sensitive trees where the parent re-renders frequently.
+ *
+ * @see [📖 Documentation](https://react-tools.ndria.dev/components/MatchOptionMemoized)
+ */
+export const MatchOptionMemoized = {
+	Switch: memo(MatchOption.Match),
+	Case: memo(MatchOption.Option)
+};

src/components/index.ts

@@ -7,4 +7,6 @@ export { For } from './For';
 export { ForMemoized } from './ForMemoized';
 export { ErrorBoundary } from './ErrorBoundary';
 export { Activity } from './Activity';
-export { Suspense } from './Suspense';
+export { Suspense } from './Suspense';
+export { MatchOption } from './MatchOption';
+export { MatchOptionMemoized } from './MatchOptionMemoized';

src/demo/components/matchOption/MatchOption.tsx

@@ -0,0 +1,31 @@
+import { useEffect, useRef, useState } from "react";
+import { MatchOption } from "../../../";
+
+/**
+The component has an array of numbers and a variable state number used like index of array. Every 2 seconds index changes value. It uses __MatchOption__ component to render different p element with a text indicating the value of array with the current index.
+ */
+export default function SM() {
+	const valuesCounter = useRef([1, 2, 3]);
+	const [indexCounter, setIndexCounter] = useState(0);
+
+	useEffect(() => {
+		const id = setInterval(() => setIndexCounter(i => i%4+1 === 4 ? 0 : i%4+1), 2000);
+		return () => clearInterval(id);
+	}, []);
+
+	return (<div style={{textAlign: "left", display: "flex", flexDirection: "column", alignItems: "center"}}>
+		<p style={{width: 230}}>Counter values: {JSON.stringify(valuesCounter.current, null, 2)}</p>
+		<p style={{width: 230}}>Counter index: {indexCounter}</p>
+		<MatchOption.Match value={indexCounter} fallback={<p style={{color: "darkorange", width: 230}}>Counter value unsetted.</p>}>
+			<MatchOption.Option is={0}>
+				<p style={{color: "darkturquoise", width: 230, fontWeight: 800}}>Counter value is 1.</p>
+			</MatchOption.Option>
+			<MatchOption.Option is={(value) => value === 1}>
+				<p style={{color: "darkkhaki", width: 230, fontWeight: 800}}>Counter value is 2.</p>
+			</MatchOption.Option>
+			<MatchOption.Option is={2}>
+				<p style={{color: "darkcyan", width: 230, fontWeight: 800}}>Counter value is 3.</p>
+			</MatchOption.Option>
+		</MatchOption.Match>
+	</div>);
+}

src/demo/components/matchOptionMemoized/MatchOptionMemoized.md

@@ -0,0 +1,3 @@
+Memoized implementation of _MatchOption_ component.
+
+Please visit [MatchOption component](https://react-tools.ndria.dev/components/MatchOption) example to see how it works.

src/models/MatchOption.model.ts

@@ -0,0 +1,43 @@
+import { PropsWithChildren, ReactElement, ReactNode } from "react";
+
+/**
+ * Props accepted by the [MatchOption](https://react-tools.ndria.dev/components/MatchOption) component.
+ *
+ * @template T - The type of the `value` to be compared.
+ */
+export interface MatchProps<T> {
+	/**
+	 * The central value to compare against the `is` prop of each <MatchOption.Option> child.
+	 * The first <MatchOption.Option> whose `is` value or function strictly matches (`===`) this `value`
+	 * will be rendered.
+	 */
+	value: T;
+
+	/**
+	 * One or more {@link Option} elements to evaluate in order. The first `Option`
+	 * whose `is` prop is truthy is rendered; all others are ignored.
+	 */
+	children?:
+		| ReactElement<OptionProps<T>>
+		| ReactElement<OptionProps<T>>[]
+		| undefined;
+
+	/**
+	 * Optional content rendered when no <MatchOption.Option> matches the provided `value`.
+	 * Accepts any valid React node.
+	 */
+	fallback?: ReactNode;
+}
+
+/**
+ * Props accepted by the [MatchOption](https://react-tools.ndria.dev/components/MatchOption) component.
+ *
+ * @template T - The type of the `is` value, should match the `value` type of the parent <MatchOption.Match>.
+ */
+export interface OptionProps<T> extends PropsWithChildren {
+	/**
+	 * The value used to determine if this option should be rendered.
+	 * If `is === value` (from the parent [Match]), the `children` are displayed.
+	 */
+	is: T | ((value:T) => boolean);
+}