@cleanweb/oore 1.0.0

package/README.old.md

@@ -0,0 +1,342 @@
+# Structured & Cleaner React Function Components
+
+## 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 three main exported members.
+
+> The following sections will use examples to demonstrate how each tool can be used. These example are intended to be read as a before and after comparison. They are all based on the same "before" code, which is shown below:
+
+
+### Our Sample React Function Component
+```jsx
+const Footer = (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();
+
+	const { param } = props;
+
+
+	// Required to run once *before* the component mounts.
+	const paragraphs = useMemo(() => getValue(param), [param]);
+
+
+	/** @todo Use `useSyncExternalStore`. */
+	const subscribeToExternalDataSource = useCallback(() => {
+		externalDataSource.subscribe((data) => {
+			setLabel(data.label);
+		});
+	}, [setLabel]);
+
+	// Required to run once *after* the component mounts.
+	useEffect(subscribeToExternalDataSource, []);
+	useEffect(() => {
+		const onWindowResize = () => {};
+		window.addEventListener('resize', onWindowResize);
+
+		return () => {
+			window.removeEventListener('resize', onWindowResize);
+		};
+	}, []);
+
+	// Run *after* every render.
+	useEffect(() => {
+		doSomething();
+		return () => {};
+	})
+
+	const submit = useCallback(() => {
+		sendData(state1, state2);
+		setSubmitted(true);
+	}, [state1]); // Notice how `state2` above could easily be stale by the time the callback runs.
+
+
+	// Run before every render.
+	const text = `${label}, please.`;
+
+	return (
+		<footer>
+			{paragraphs ? paragraphs.map((copy) => (
+				<p>{copy}</p>
+			)) : null}
+
+			<button onClick={submit}>
+				{text}
+			</button>
+		</footer>
+	);
+};
+
+export default Footer;
+// Or use in JSX as `<Footer />`.
+```
+
+
+### A Cleaner State Management API
+The `useCleanState` hook provides a cleaner API for working with state, particularly in components with a relatively high number of state variables. It allows you to manage multiple state variables as a single unit. You will likely find this cleaner to work with than having multiple local variables for each state. The example below demonstrates the use of this hook.
+
+
+### Extracting and Structuring Component Logic
+The `useLogic` hook 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.
+
+**Before**
+[See the "before" code above](#our-sample-react-function-component).
+
+**After**
+```jsx
+class FooterLogic {
+	static getInitialState = (props) => {
+		return {
+			state1: props.defaultValue,
+			state2: undefined,
+			label: 'Click me',
+			submitted: false,
+		};
+	};
+
+	subscribeToExternalDataSource = () => {
+		externalDataSource.subscribe((data) => {
+			this.state.label = data.label;
+		});
+	}
+
+	useHooks = () => {
+		const [store, updateStore] = useGlobalStore();
+		const { param } = this.props;
+
+		// Required to run once *before* the component mounts.
+		const paragraphs = useMemo(() => getValue(param), [param]);
+
+		// Required to run once *after* the component mounts.
+		useEffect(this.subscribeToExternalDataSource, []);
+		useEffect(() => {
+			const onWindowResize = () => {};
+			window.addEventListener('resize', onWindowResize);
+
+			return () => {
+				window.removeEventListener('resize', onWindowResize);
+			};
+		}, []);
+
+		// Run *after* every render.
+		useEffect(() => {
+			doSomething();
+			return () => {};
+		});
+
+		return {
+			store,
+			updateStore,
+			paragraphs,
+		};
+	};
+
+	submit = () => {
+		const { state1, state2 } = this.state;
+		sendData(state1, state2);
+		this.state.submitted = true;
+	}; // `state2` is never stale. All `state` and `props` references return the latest value. No extra steps required.
+}
+
+// Footer Template
+const Footer = (props) => {
+	const self = useLogic(FooterLogic, props);
+
+	const { paragraphs } = self.hooks;
+	const { state } = self;
+
+	// Run before every render.
+	const text = `${state.label}, please.`;
+
+	return (
+		<footer>
+			{paragraphs ? paragraphs.map((copy) => (
+				<p>{copy}</p>
+			)) : null}
+
+			<button onClick={self.submit}>
+				{text}
+			</button>
+		</footer>
+	);
+};
+
+export default Footer;
+// Or use in JSX as `<Footer />`.
+```
+
+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 as well as the added functionality of the `useHooks` method.
+
+> 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).
+
+
+### 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**
+[See the "before" code above](#our-sample-react-function-component).
+
+**After**
+```jsx
+class Footer extends ClassComponent {
+	// Call the static method extract() to retrieve the renderer for your class.
+	// This is a function that you can render like any other function component.
+	// Each instance of the renderer in your component tree will create its own instance of the class.
+	static readonly RC = Button.extract();
+
+	static getInitialState = (props) => {
+		return {
+			state1: props.defaultValue,
+			state2: undefined,
+			label: 'Click me',
+			submitted: false,
+		};
+	};
+
+	useHooks = () => {
+		const [store, updateStore] = useGlobalStore();
+		return { store, updateStore };
+	}
+
+	/***************************
+	 *  New Lifecycle Methods  *
+	 ***************************/
+
+	beforeMount = () => {
+		this.paragraphs = getValue();
+	}
+
+	// Run after the component is mounted.
+	onMount = () => {
+		this.subscribeToExternalDataSource();
+		window.addEventListener('resize', this.onWindowResize);
+
+		// Return cleanup callback.
+		return () => {
+			window.removeEventListener('resize', this.onWindowResize);
+		};
+	}
+
+	beforeRender = () => {
+		this.text = `${label}, please.`;
+	}
+
+	// Run after every render.
+	onRender = () => {
+		doSomething();
+
+		// 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 *
+	 ***************************/
+
+	submit = () => {
+		// Methods are guaranteed to have access to the most recent state values.
+		const { state1, state2 } = this.state;
+
+		sendData(state1, state2);
+
+		// 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;
+	}
+
+	onWindowResize = () => {};
+
+	subscribeToExternalDataSource = () => {
+		const unsubscribe = externalDataSource.subscribe((data) => {
+			this.state.label = data.label;
+		});
+
+		return unsubscribe;
+	}
+
+	/** You can also separate out discreet chunks of your UI template. */
+	Paragraphs = () => {
+		if (!this.paragraphs) return null;
+
+		return this.paragraphs.map((content, index) => (
+			<p key={index}>
+				{content || this.state.label}
+			</p>
+		));
+	}
+
+	/** Button Template */
+	template = () => {
+		const { Paragraphs, submit, state } = this;
+
+		return (
+			<Fragment>
+				<Paragraphs />
+
+				{/* 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} />
+
+				<button onClick={submit}>
+					{this.text}
+				</button>
+			</Fragment>
+		);
+	}
+}
+
+// Can also be used directly in JSX as `<Button.RC />`.
+export default 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.
+
+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).
+
+### 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).
+
+```jsx
+class Button extends React.Component {
+	handleGlobalStore = ([store, updateStore]) => {
+		this.setState({ userId: store.userId });
+		this.store = store;
+		this.updateStore = updateStore;
+	}
+
+	UseHooks = () => {
+		return <>
+			<Use hook={useGlobalStore}
+				onUpdate={handleGlobalStore}
+				argumentsList={[]}
+				key="useGlobalStore"
+			/>
+		</>;
+	}
+
+	render() {
+		const { UseHooks } = this;
+
+		return <>
+			<UseHooks />
+
+			<button>Click me</button>
+		</>;
+	}
+}
+```

package/build/base/index.d.ts

@@ -0,0 +1,3 @@
+export * from './state';
+export * from './methods';
+export * from './merged-state';

package/build/base/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./state"), exports);
+__exportStar(require("./methods"), exports);
+__exportStar(require("./merged-state"), exports);

package/build/base/merged-state.d.ts

@@ -0,0 +1,20 @@
+import '../globals';
+declare class MergedState<TState extends object> {
+    static useRefresh<TState extends object>(this: MergedState<TState>): void;
+    reservedKeys: string[];
+    valueKeys: string[];
+    private _initialValues_;
+    private _values_;
+    private setState;
+    private _setters_;
+    get put(): { [Key in keyof TState]: (value: TState[Key]) => void; };
+    get initialState(): TState;
+    constructor(initialState: TState);
+    putMany: (newValues: Partial<TState>) => void;
+}
+/**
+ * Similar to {@link useCleanState},
+ * but uses a single `useState` call for the entire object.
+ */
+export declare const useMergedState: <TState extends object>(initialState: TState) => MergedState<TState> & TState;
+export {};

package/build/base/merged-state.js

@@ -0,0 +1,84 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMergedState = void 0;
+require("../globals");
+var react_1 = require("react");
+var MergedState = /** @class */ (function () {
+    function MergedState(initialState) {
+        var _this = this;
+        this._initialValues_ = {};
+        this._values_ = {};
+        this._setters_ = {};
+        this.putMany = function (newValues) {
+            _this.setState(__assign(__assign({}, _this._values_), newValues));
+        };
+        this.reservedKeys = Object.keys(this);
+        this.valueKeys = [];
+        this._initialValues_ = __assign({}, initialState);
+        this._values_ = __assign({}, initialState);
+        Object.keys(initialState).forEach(function (_key) {
+            var key = _key;
+            if (_this.reservedKeys.includes(key)) {
+                throw new Error("The name \"".concat(key, "\" is reserved by CleanState and cannot be used to index state variables. Please use a different key."));
+            }
+            _this.valueKeys.push(key);
+            _this._setters_[key] = function (value) {
+                var _a;
+                // this._values_[key] = value;
+                _this.setState(__assign(__assign({}, _this._values_), (_a = {}, _a[key] = value, _a)));
+            };
+            var self = _this;
+            Object.defineProperty(_this, key, {
+                get: function () {
+                    return self._values_[key];
+                },
+                set: function (value) {
+                    self._setters_[key](value);
+                },
+                enumerable: true,
+            });
+        });
+    }
+    MergedState.useRefresh = function () {
+        var _a;
+        _a = (0, react_1.useState)(this.initialState), this._values_ = _a[0], this.setState = _a[1];
+    };
+    Object.defineProperty(MergedState.prototype, "put", {
+        get: function () {
+            return __assign({}, this._setters_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(MergedState.prototype, "initialState", {
+        get: function () {
+            return __assign({}, this._initialValues_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return MergedState;
+}());
+/**
+ * Similar to {@link useCleanState},
+ * but uses a single `useState` call for the entire object.
+ */
+var useMergedState = function (initialState) {
+    var cleanState = (0, react_1.useRef)((0, react_1.useMemo)(function () {
+        return new MergedState(initialState);
+    }, [])).current;
+    MergedState.useRefresh.call(cleanState);
+    return cleanState;
+};
+exports.useMergedState = useMergedState;

package/build/base/methods.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module ComponentMethods
+ */
+import type { TCleanState, TStateData } from './state';
+/**
+ * @summary
+ * Base class for a class that holds methods for a function component.
+ *
+ * @remarks
+ * These methods will have access to the components state and props via
+ * `this.state` and `this.props` respectively.
+ *
+ * Call the {@link useMethods} hook inside your function component to instantiate the class.
+ */
+export declare class ComponentMethods<TProps extends object = {}, TState extends TStateData | null = null> {
+    readonly props: TProps;
+    readonly state: TState extends TStateData ? TCleanState<TState> : null;
+    /**
+     * Persist class members during HMR. {@include ../classy/logic/hrm-preserve-keys.md}
+     * @privateRemarks
+     * @see {@link https://cleanjsweb.github.io/neat-react/classes/API.BaseClasses.ComponentMethods.html#_hmrpreservekeys | Full details}
+     */
+    _hmrPreserveKeys: Array<keyof this | (string & {})>;
+    /**
+     * Run custom logic after HMR update. {@include ../classy/logic/on-hrm-update.md}
+     * @privateRemarks
+     * @see {@link https://cleanjsweb.github.io/neat-react/classes/API.BaseClasses.ComponentMethods.html#_onhmrupdate | Full details}
+     */
+    _onHmrUpdate?: <TInstance extends this>(oldInstance: TInstance) => void;
+}
+type UseMethods = {
+    <Class extends typeof ComponentMethods<object, object>>(Methods: Class & Constructor<InstanceType<Class>>, props: InstanceType<Class>['props'], state: InstanceType<Class>['state']): InstanceType<Class>;
+    <Class extends typeof ComponentMethods<object, null>>(Methods: Class & Constructor<InstanceType<Class>>, props: InstanceType<Class>['props'], state?: null): InstanceType<Class>;
+    <Class extends typeof ComponentMethods<NeverObject, null>>(Methods: Class & Constructor<InstanceType<Class>>): InstanceType<Class>;
+};
+/**
+ * Returns an instance of the provided class,
+ * with the state and props arguments added as instance members.
+ *
+ * `state` should be an instance of `CleanState` created with {@link useCleanState}.
+ */
+declare const useMethods: UseMethods;
+export { useMethods };
+/** /type_testing: {
+    let a = async () => {
+        const a: object = {b: ''};
+
+        type t = keyof typeof a;
+
+        class MyMethods extends ComponentMethods<EmptyObject, null> {
+            // static getInitialState = () => ({});
+        };
+
+        const { useCleanState } = (await import('./state.js'));
+
+        const self = useMethods(MyMethods, {});
+        self.state;
+    }
+}/**/

package/build/base/methods.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * @module ComponentMethods
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMethods = exports.ComponentMethods = void 0;
+// Values
+var react_1 = require("react");
+/**
+ * @summary
+ * Base class for a class that holds methods for a function component.
+ *
+ * @remarks
+ * These methods will have access to the components state and props via
+ * `this.state` and `this.props` respectively.
+ *
+ * Call the {@link useMethods} hook inside your function component to instantiate the class.
+ */
+var ComponentMethods = /** @class */ (function () {
+    function ComponentMethods() {
+        /**
+         * Persist class members during HMR. {@include ../classy/logic/hrm-preserve-keys.md}
+         * @privateRemarks
+         * @see {@link https://cleanjsweb.github.io/neat-react/classes/API.BaseClasses.ComponentMethods.html#_hmrpreservekeys | Full details}
+         */
+        this._hmrPreserveKeys = []; // @todo Keep undefined. Update to empty array after instantiation in dev env.
+    }
+    return ComponentMethods;
+}());
+exports.ComponentMethods = ComponentMethods;
+;
+/**
+ * Returns an instance of the provided class,
+ * with the state and props arguments added as instance members.
+ *
+ * `state` should be an instance of `CleanState` created with {@link useCleanState}.
+ */
+var useMethods = function () {
+    var _a;
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    var Methods = args[0], _b = args[1], props = _b === void 0 ? {} : _b, state = args[2];
+    // Vite HMR seems to sometimes reinitialize useMemo calls after a hot update,
+    // causing the instance to be unexpectedly recreated in the middle of the component's lifecycle.
+    // But useRef and useState values appear to always be preserved whenever this happens.
+    // So those two are the only cross-render-persistence methods we can consider safe.
+    // In production, we only use the latestInstance the first time, and it's ignored every other time.
+    // This means changing the class at runtime will have no effect in production.
+    // latestInstance is only extracted into a separate variable for use in dev mode during HMR.
+    var latestInstance = (0, react_1.useMemo)(function () { return new Methods(); }, [Methods]);
+    var instanceRef = (0, react_1.useRef)(latestInstance);
+    var refreshState = function () {
+        // @ts-expect-error
+        instanceRef.current.props = props;
+        // @ts-expect-error
+        if (state)
+            instanceRef.current.state = state;
+    };
+    if (process.env.NODE_ENV === 'development' && instanceRef.current !== latestInstance) {
+        var oldInstance_1 = instanceRef.current;
+        latestInstance._hmrPreserveKeys.forEach(function (_key) {
+            var key = _key;
+            // @ts-expect-error We're assigning to readonly properties. Also, Typescript doesn't know that the type of the left and right side will always match, due to the dynamic access.
+            latestInstance[key] = oldInstance_1[key];
+        });
+        // Ensure that any stale references to oldInstance within the app
+        // will end up retrieving up-to-date values from latestInstance
+        // through the prototype chain.
+        Reflect.ownKeys(oldInstance_1).forEach(function (_key) {
+            var key = _key;
+            delete oldInstance_1[key];
+        });
+        Object.setPrototypeOf(oldInstance_1, latestInstance);
+        instanceRef.current = latestInstance;
+        refreshState();
+        (_a = latestInstance._onHmrUpdate) === null || _a === void 0 ? void 0 : _a.call(latestInstance, oldInstance_1);
+    }
+    else
+        refreshState();
+    return instanceRef.current;
+};
+exports.useMethods = useMethods;
+/** /type_testing: {
+    let a = async () => {
+        const a: object = {b: ''};
+
+        type t = keyof typeof a;
+
+        class MyMethods extends ComponentMethods<EmptyObject, null> {
+            // static getInitialState = () => ({});
+        };
+
+        const { useCleanState } = (await import('./state.js'));
+
+        const self = useMethods(MyMethods, {});
+        self.state;
+    }
+}/**/

package/build/base/state/class-types.d.ts

@@ -0,0 +1,20 @@
+import { CleanStateBase } from './class';
+import { TCleanState, TStateData } from './hook-types';
+export type TCleanStateBase = typeof CleanStateBase;
+export type TCleanStateBaseKeys = keyof TCleanStateBase;
+export type PutState<TState extends TStateData> = {
+    [Key in keyof TState]: React.Dispatch<React.SetStateAction<TState[Key]>>;
+};
+export type PutManyPayload<TState extends TStateData> = {
+    [Key in keyof TState]?: React.SetStateAction<TState[Key]>;
+};
+export type StateFragment<TComponent extends {
+    getInitialState: (...args: any[]) => TStateData;
+}> = PutManyPayload<ReturnType<TComponent['getInitialState']>>;
+export type { StateFragment as SF };
+export interface ICleanStateConstructor {
+    new <TState extends object>(...args: ConstructorParameters<typeof CleanStateBase>): TCleanState<TState>;
+}
+export type ICleanStateClass = ICleanStateConstructor & {
+    [Key in TCleanStateBaseKeys]: (typeof CleanStateBase)[Key];
+};

package/build/base/state/class-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/base/state/class.d.ts

@@ -0,0 +1,16 @@
+import { ICleanStateClass, ICleanStateConstructor, PutManyPayload, PutState } from './class-types';
+/** @internal */
+export declare class CleanStateBase<TState extends Record<string, any>> {
+    readonly reservedKeys: string[];
+    readonly valueKeys: string[];
+    private _values_;
+    private _initialValues_;
+    private _setters_;
+    constructor(initialState: TState);
+    static update: <TState_1 extends object>(this: CleanStateBase<TState_1>) => void;
+    get put(): PutState<TState>;
+    get initialState(): TState;
+    readonly putMany: (newValues: PutManyPayload<TState>) => void;
+}
+/** @internal */
+export declare const CleanState: (ICleanStateConstructor & ICleanStateClass);