@cleanweb/react 1.1.1-beta.9 → 2.0.1-beta.0

package/README.md

@@ -1,76 +1,153 @@
-# Structured & Cleaner React Function Components
+# Object Oriented Programming for React
+This package provides a number of tools for creating React function components with object-oriented code. With Oore, you can avoid common errors, and write complex components that are cleaner, better structured, and eassier to read & understand.
 
-## Quick Start
-This package provides a suite of tools for writing cleaner React function components. It is particularly useful for larger components with lots of state variables and multiple closure functions that need to access those variables. The most likely use cases will use one of the two main exported members.
+Oore is written in Typescript and all exports are fully typed.
 
-### Extracting and Structuring Component Logic
-The `useLogic` allows you to write your component's logic outside the function component's body, and helps you keep them all better organized. It also provides a much cleaner API for working with multiple state variables. Here's what a function component looks like with the `useLogic` hook.
+## Usage
+### Clean State
+The `useCleanState` hook provides a clean API for working with multiple state variables in a unified way. The example below demonstrates how to use it.
 
-**Before**
 ```jsx
+const initialState = {
+	label: 'Click me',
+	clicked: false,
+	inputValue: {},
+};
+// or
+const getInitialState = (props) => {
+	return {
+		label: props.label,
+		clicked: false,
+		inputValue: {},
+	};
+};
+
 const Button = (props) => {
-	const { param } = props;
+	const state = useCleanState(initialState);
+	// or
+	const state = useCleanState(getInitialState, props);
+	
+
+	const onClick = useCallback(() => {
+		state.clicked = true;
+		// or
+		state.putMany({
+			label: 'Loading',
+			clicked: true,
+		});
+		// or
+		state.put.clicked(true);
+		// or
+		state.put.clicked((oldClicked) => !oldClicked);
+	}, []);
+
+	return <>
+		<CustomInput setValue={state.put.inputValue}>
+
+		<button onClick={onClick}>
+			{state.label}
+		</button>
+	</>;
+}
+```
 
-	const [state1, setState1] = useState();
-	const [state2, setState2] = useState();
-	const [label, setLabel] = useState('Click me');
-	const [submitted, setSubmitted] = useState(false);
+> **Note:** You can call `useCleanState` multiple times in the same component, allowing you to group related state values into separate objects.
 
-	const memoizedValue = useMemo(() => getValue(param), [param]);
+> **Note:** Each top-level key in your initial state object gets a separate call to `React.useState`, and `state.put[key]()` is a proxy for the setter function returned from `useState`. So using this hook is fundamentally the same as calling `useState` directly for each value. What `useCleanState` provides is a way to unify those values and a convenient API for updating them.
 
-	const subscribeToExternalDataSource = useCallback(() => {
-		externalDataSource.subscribe((data) => {
-			setLabel(data.label);
-		});
-	}, [setLabel]);
+[Read the `useCleanState` docs]() for more details.
 
-	useEffect(subscribeToExternalDataSource, []);
+### Methods
+The `useMethods` hook lets you manage the closures that your component uses in a separate class, keeping the body of the component clean and easier to read. With `useMethods`, your functions are not recreated on every render. Yet, every method of your component is guaranteed to always have access to the latest props and state without the need for a dependencty array.
 
-	const submit = useCallback(() => {
+```jsx
+class ButtonMethods {
+	submit = () => {
+		const { state1, state2 } = this.state;
 		sendData(state1, state2);
-		setSubmitted(true);
-	}, [state1]); // Notice how `state2` above could easily be stale by the time the callback runs.
+		this.state.submitted = true;
+	}
 
-	return <>
-		<p>{memoizedValue}</p>
-		<button onClick={submit}>
-			{label}
+	doSomething = () => {
+		console.table(this.props);
+	} 
+}
+
+const initialState = {
+	value1: undefined,
+	value2: null,
+	label: 'Click me',
+	submitted: false,
+}
+
+const Button = (props) => {
+	const state = useCleanState(initialState);
+	const methods = useMethods(ButtonMethods, state, props);
+
+	useEffect(methods.doSomething, []);
+
+	return (
+		<button onClick={methods.submit}>
+			{state.label}
 		</button>
-	</>;
+	);
 }
 ```
 
-**After**
+`useMethods` only accepts a single state object. So if you are using multiple calls to `useCleanState`, you may have to group them into a single object when calling `useMethods`.
+
+```jsx
+const getDefaultValues = (props) => ({/* ... */});
+
+const Button = (props) => {
+	const formValues = useCleanState(getDefaultValues, props);
+	const apiData = useCleanState({});
+
+	const multiState = { formValues, apiData };
+	const methods = useMethods(ButtonMethods, multiState, props);
+
+	// ...
+}
+```
+
+[Read the `useMethods` docs]() for more details.
+
+### Logic
+The `useLogic` hook is an expansion of `useMethods`, with the aim of being a more holistic solution. It combines the functionality of `useCleanState` and `useMethods`. In addition, it allows you to externalize _all_ of your component's logic, not just closures and state. Essentially, this means being able to call hooks from within the class, rather than having to do so within the component body.
+
 ```jsx
 class ButtonLogic {
 	static getInitialState = () => {
 		return {
-			state1: undefined,
-			state2: null,
+			value1: undefined,
+			value2: null,
 			label: 'Click me',
 			submitted: false,
 		};
 	}
 
-	submit = () => {
-		const { state1, state2 } = this.state;
-		sendData(state1, state2);
+	submit = async () => {
+		const { value1, value2 } = this.state;
+		await sendData(value1, value2);
 		this.state.submitted = true;
 	}
 
-	subscribeToExternalDataSource = () => {
-		externalDataSource.subscribe((data) => {
-			this.state.label = data.label;
-		});
+	doSomething = () => {
+		// ...
 	}
 
 	useHooks = () => {
 		const { param } = this.props;
 
-		useEffect(this.subscribeToExternalDataSource, []);
+		useEffect(this.doSomething, []);
+
 		const memoizedValue = useMemo(() => getValue(param), [param]);
+		const value2 = useCustomHook();
 
-		return { memoizedValue };
+		return {
+			memoizedValue,
+			value2,
+		};
 	}
 }
 
@@ -87,203 +164,164 @@ const Button = (props) => {
 }
 ```
 
-The `useLogic` hook combines the functionality of two base hooks which can also be used directly. They are [`useCleanState`](https://cleanjsweb.github.io/neat-react/clean-state/index) and [`useMethods`](https://cleanjsweb.github.io/neat-react/methods/index). `useCleanState` can be used independently if you only want a cleaner state management API. `useMethods` is designed to be used together with `useCleanState`, but rather than calling both individually, you may find it more convenient to use `useLogic`, which combines both and also adds additional functionality.
+[Read the `useLogic` docs]() for more details.
 
-> It is possible to have multiple calls to `useLogic` in the same component. This allows your function component template to consume state and logic from multiple sources, or it can simply be used to group distinct pieces of related logic into separate classes.
-
-For a fuller discussion of how `useLogic` works, start at the [clean-state documentation](https://cleanjsweb.github.io/neat-react/clean-state/index).    
-For an API reference, see the [API reference](https://cleanjsweb.github.io/neat-react/logic/api).
+### Lifecycle (`useInstance`)
+The `useInstance` hook provides a simple approach for working with your components lifecycle. It includes all the features of [`useLogic`](#logic), and adds special lifecycle methods. This gives you a declarative way to run certain code at specific stages of your component's life time. You will likely find this to be less error prone and much easier to reason about than the imperative approach of using React's hooks directly.
 
+```jsx
+/** Button Component Class. */
+class ButtonCC extends ComponentInstance {
+	// ...
+	// Static method(s), same as useLogic...
+	// ...
 
-### Working With Lifecycle, and Migrating From a React.Component Class to a Function Component
-In addition to having cleaner and more structured component logic, you can also simplify the process of working with your component's lifecycle with the final two exported members. The `useInstance` hook builds on the functionality of `useLogic` and adds lifecyle methods to the class. This means the class can now be thought of as truly representing a single instance of a React component. The `ClassComponent` class extends this to its fullest by allowing you to write the function component itself as a method within the class, and removing the need to explicitly call `useInstance`.
 
-**Before**
-```jsx
-const Button = (props) => {
-	const [state1, setState1] = useState(props.defaultValue);
-	const [state2, setState2] = useState();
-	const [label, setLabel] = useState('Click me');
-	const [submitted, setSubmitted] = useState(false);
-	const [store, updateStore] = useGlobalStore();
-
-	// Required to run once *before* the component mounts.
-	const memoizedValue = useMemo(() => getValue(), []);
-
-	// Required to run once *after* the component mounts.
-	useEffect(() => {
-		const unsubscribe = externalDataSource.subscribe((data) => {
-			setLabel(data.label);
-		});
+	/* Lifecycle Methods */
 
-		const onWindowResize = () => {};
+	beforeMount = () => {
+		// Runs before the component is first rendered.
+		// This is implemented using useMemo.
+	}
 
-		window.addEventListener('resize', onWindowResize);
+	onMount = () => {
+		// Runs after the component is first rendered.
+		// Same as `useEffect(() => {}, []);`
 
 		return () => {
-			unsubscribe();
-			window.removeEventListener('resize', onWindowResize);
+			// Required clean up function must be returned.
+			// Return an empty function if you have no cleanup.
 		};
-	}, []);
-
-	// Run *after* every render.
-	useEffect(() => {
-		doSomething();
-		return () => {};
-	})
-
-	const submit = useCallback(() => {
-		sendData(state1, state2);
-		setSubmitted(true);
-	}, [state1]);
-
-	// Run before every render.
-	const text = `${label}, please.`;
+	}
 
-	return <>
-		{memoizedValue ? memoizedValue.map((copy) => (
-			<p>{copy}</p>
-		)) : null}
-		<button onClick={submit}>
-			{text}
-		</button>
-	</>;
-}
+	beforeRender = () => {
+		// Runs before every single render.
+		// Same as code placed before the return statement in a function component.
 
-export default Button;
-```
+		// Example: Generate display values from state and props,
+		// and return them for use in your JSX template.
+		const displayValue2 = this.hooks.memoizedValue + this.state.value2;
 
-**After**
-```jsx
-class Button extends ClassComponent {
-	static getInitialState = (props) => {
+		// The optional returned object will be available
+		// on the created instance as `instance.templateContext`
 		return {
-			state1: props.defaultValue,
-			state2: null,
-			label: 'Click me',
-			submitted: false,
+			intro: `Hello, ${this.props.name}`,
+			displayValue2,
 		};
-	}
 
-	useHooks = () => {
-		const [store, updateStore] = useGlobalStore();
-		return { store, updateStore };
-	}
-
-	/***************************
-	 *  New Lifecycle Methods  *
-	 ***************************/
-
-	beforeMount = () => {
-		this.memoizedValue = getValue();
+		// PS: For any expensive logic, you should wrap it
+		// in useMemo and move it into the useHooks method instead.
 	}
 
-	// Run after the component is mounted.
-	onMount = () => {
-		const unsubscribe = this.subscribeToExternalDataSource();
-		window.addEventListener('resize', this.onWindowResize);
+	onRender = () => {
+		// Runs after every single render.
+		// Same as `useEffect(() => {});`
 
-		// Return cleanup callback.
 		return () => {
-			unsubscribe();
-			window.removeEventListener('resize', this.onWindowResize);
+			// Required clean up function must be returned.
+			// Return an empty function if you have no cleanup.
 		};
 	}
 
-	beforeRender = () => {
-		this.text = `${label}, please.`;
+	cleanUp = () => {
+		// Runs when the component is unmounted.
+		// Similar to the function returned by `onMount`.
 	}
 
-	// Run after every render.
-	onRender = () => {
-		doSomething();
+	/* [End] Lifecycle Methods */
 
-		// Return cleanup callback.
-		return () => {};
-	}
 
-	cleanUp = () => {
-		// Run some non-mount-related cleanup when the component dismounts.
-		// onMount (and onRender) returns its own cleanup function.
-	}
-
-	/***************************
-	 * [End] Lifecycle Methods *
-	 ***************************/
+	// ...
+	// Other instance methods, same as useLogic...
+	// ...
+}
 
-	submit = () => {
-		// Methods are guaranteed to have access to the most recent state values,
-		// without any delicate hoops to jump through.
-		const { state1, state2 } = this.state;
+// Button Template
+const Button = (props) => {
+	const self = useInstance(ButtonCC, props);
+	const ctx = self.templateContext;
 
-		sendData(state1, state2);
+	return <>
+		<p>{ctx.intro}</p>
+		<button onClick={self.submit}>
+			{self.state.label}
+		</button>
+	</>;
+}
+```
 
-		// CleanState uses JavaScript's getters and setters, allowing you to assign state values directly.
-		// The effect is the same as if you called the setter function, which is available through `state.put.submitted(true)`.
-		this.state.submitted = true;
-	}
+[Read the `useInstance` docs]() for more details.
 
-	onWindowResize = () => {
-		;
-	}
+### Class Component
+With `useInstance`, pretty much every aspect of your component is now part of the class, except for the JSX template. The `ClassComponent` class takes that final step and provides a fully integrated class-based React component.
 
-	subscribeToExternalDataSource = () => {
-		const unsubscribe = externalDataSource.subscribe((data) => {
-			this.state.label = data.label;
-		});
+If you're currently maintaining older components written with the old `React.Component` class and you would like to rewrite them as function components with hooks, porting them to `ClassComponent` will _significantly_ simplify and speed up the migration process. You can access all the latest React features, without changing the overall structure of your existing component classes.
 
-		return unsubscribe;
-	}
 
-	/** You can also separate out discreet chunks of your UI template. */
-	Paragraphs = () => {
-		if (!this.memoizedValue) return null;
+```jsx
+class Button extends ClassComponent {
+	/** See the description of the `RC` property below this example. */
+	static RC = Button.extract();
+	// Or...
+	static RC = Button.FC();
+	// Or, using `this`, which refers to the class itself
+	// when the static keyword is present...
+	static RC = this.extract();
+	// Or...
+	static RC = this.FC();
 
-		return this.memoizedValue.map((content, index) => (
-			<p key={index}>
-				{content || this.state.label}
-			</p>
-		));
-	}
+	// ...
+	// Other static and instance members, same as useInstance...
+	// ...
 
-	/** Button Template */
-	Render = () => {
-		const { Paragraphs, submit, state } = this;
 
-		return <>
-			<Paragraphs />
+	beforeRender = () => {
+		const displayValue2 = this.hooks.memoizedValue + this.state.value2;
 
-			{/* You can access the setter functions returned from useState through the state.put object. */}
-			{/* This is more convenient than the assignment approach if you need to pass a setter as a callback. */}
-			{/* Use state.putMany to set multiple values at once. It works just like setState in React.Component classes. */}
-			{/* e.g state.inputValue = 'foo', or state.put.inputValue('foo'), or state.putMany({ inputValue: 'foo' }) */}
-			<CustomInput setValue={state.put.inputValue}>
+		return {
+			intro: `Hello, ${this.props.name}`,
+			displayValue2,
+		};
+	}
 
-			<button onClick={submit}>
-				{this.text}
+	/**
+	 * Button Template.
+	 * @param ctx - The `templateContext` object returned in `beforeRender`.
+	 * Will be `undefined` if nothing is returned by `beforeRender`.
+	 */
+	template = (ctx) => (
+		<section>
+			<p>{ctx.intro}</p>
+
+			<button onClick={this.submit}>
+				{this.state.label}
 			</button>
-		</>;
-	}
+		</section>
+	);
 }
 
-// Call the static method FC() to get a function component that you can render like any other function component.
-export default Button.FC();
+export default Button.RC;
+// Or render directly with `<Button.RC />`.
 ```
 
-> If you would like to keep the actual function component separate and call `useInstance` directly, see the [`useInstance` docs](https://cleanjsweb.github.io/neat-react/instance/index) for more details and examples.
+Every class derived from the base `ClassComponent` is not itself a React component. Instead, it has a static `extract()` method (also aliased as `FC()` for "Function Component") which returns a function component that can be rendered like any other React component. Each instance of this function component mounted in the React tree creates it's own separate instance of your `ClassComponent` class. To make it easier to use the class component directly, you should create a static property that holds the function component returned by `extract`. The recommended convention is to use the name `RC` (for "React Component"). Such a class can then easily be rendered as JSX by writing `<MyComponent.RC />`.
+
+[Read the `ClassComponent` docs]() for more details.
 
-At its core, any component you write with `ClassComponent` is still just a React function component, with some supporting logic around it. This has the added advantage of making it significantly easier to migrate class components written with `React.Component` to the newer hooks-based function components, while still maintaining the overall structure of a class component, and the advantages that the class component approach provided.
 
-For a fuller discussion of how this works, start at the [`useInstance` documentation](https://cleanjsweb.github.io/neat-react/instance/index).    
-For more details on the lifecycle methods and other API reference, see the [`ClassComponent` API docs](https://cleanjsweb.github.io/neat-react/class-component/api).
+### Other Exports
 
-### The `<Use>` Component
-If you only want to use hooks in your `React.Component` class without having to refactor anything, use the [`Use` component](https://cleanjsweb.github.io/neat-react/class-component/index#the-use-component).
+#### The `<Use>` Component
+If you simply want to use hooks in your `React.Component` class without having to rewrite anything, this package also exports a `<Use>` component that helps you achieve this easily. Here's how to use it.
 
 ```jsx
+import { useGlobalStore } from '@/hooks/store';
+
 class Button extends React.Component {
-	handleGlobalStore = ([store, updateStore]) => {
-		this.setState({ userId: store.userId });
+	syncGlobalStore = ([store, updateStore]) => {
+		if (this.state.userId !== store.userId) {
+			this.setState({ userId: store.userId });
+		}
 		this.store = store;
 		this.updateStore = updateStore;
 	}
@@ -291,7 +329,7 @@ class Button extends React.Component {
 	UseHooks = () => {
 		return <>
 			<Use hook={useGlobalStore}
-				onUpdate={handleGlobalStore}
+				onUpdate={syncGlobalStore}
 				argumentsList={[]}
 				key="useGlobalStore"
 			/>
@@ -309,3 +347,20 @@ class Button extends React.Component {
 	}
 }
 ```
+
+The provided hook is called with the `argumentsList` array passed in (the array is spread, so each item in the list is a separate argument). The return value from the hook is passed on to the `onUpdate` callback. So you can use this to update your component's state and trigger a rerender when something changes.
+
+#### Merged State
+This package also exports a `useMergedState` hook, which provides all the same features as `useCleanState`, but with a slightly different implementation.
+
+The `useCleanState` hook is designed to exactly mirror how function components are usually written: a separate `React.useState` call for each distinct value. `useMergedState` takes a simpler approach by making just one `React.useState` call for the entire `initialState` object. Functionally though, the effect is probably the same.
+
+It is recommended that you use `useCleanState` instead of this since that implementation is truer to how `React.useState` is commonly used. `useMergedState` may be removed in future versions.
+
+### Issues
+If you observe an issue or bug, please report it by creating an issue on the [Oore repo on GitHub]().
+
+#### Known Issues
+Methods on your component classes may not be updated as expected during HMR. So fully refreshing the page may sometimes be required while developing with Oore. A fix for this is being investigated.
+
+