@cleanweb/react 1.0.5 → 1.0.6

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

@@ -0,0 +1,16 @@
+declare class MergedState<TState extends object> {
+    static refresh<TState extends object>(this: MergedState<TState>): void;
+    reservedKeys: string[];
+    valueKeys: string[];
+    private _initialValues_;
+    private _values_;
+    private setState;
+    private _setters_;
+    private useRetrieveState;
+    get put(): { [Key in keyof TState]: (value: TState[Key]) => void; };
+    get initialState(): TState;
+    constructor(initialState: TState);
+    putMany: (newValues: Partial<TState>) => void;
+}
+export declare const useMergedState: <TState extends object>(initialState: TState) => MergedState<TState> & TState;
+export {};

package/build/base/merged-state.js

@@ -0,0 +1,79 @@
+"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;
+var react_1 = require("react");
+var MergedState = /** @class */ (function () {
+    function MergedState(initialState) {
+        var _this = this;
+        this._initialValues_ = {};
+        this._values_ = {};
+        this._setters_ = {};
+        this.useRetrieveState = function () {
+            var _a;
+            _a = (0, react_1.useState)(_this.initialState), _this._values_ = _a[0], _this.setState = _a[1];
+        };
+        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) {
+            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.refresh = function () {
+        this.useRetrieveState();
+    };
+    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;
+}());
+var useMergedState = function (initialState) {
+    var cleanState = (0, react_1.useMemo)(function () { return new MergedState(initialState); }, []);
+    MergedState.refresh.call(cleanState);
+    return cleanState;
+};
+exports.useMergedState = useMergedState;

package/build/base/methods.d.ts

@@ -1,6 +1,6 @@
-import type { CleanState } from './state';
+import type { TCleanState } from './state';
 export declare class ComponentMethods<TState extends object, TProps extends object> {
-    state: CleanState<TState>;
+    state: TCleanState<TState>;
     props: TProps;
 }
 type ComponentMethodsConstructor = typeof ComponentMethods<any, any>;

package/build/base/state.d.ts

@@ -5,18 +5,24 @@ type TUseStateArray<TState extends object> = [
 type TUseStateResponses<TState extends object> = {
     [Key in keyof TState]: TUseStateArray<TState>;
 };
-declare class _CleanState_<TState extends object> {
+declare class CleanStateBase<TState extends object> {
+    static update: ICleanStateClass['update'];
+    reservedKeys: string[];
+    valueKeys: string[];
     private _values_;
     private _setters_;
-    put: { [Key in keyof TState]: (value: TState[Key]) => void; };
-    constructor(stateAndSetters: TUseStateResponses<TState>);
+    get put(): { [Key in keyof TState]: (value: TState[Key]) => void; };
+    constructor();
     putMany: (newValues: Partial<TState>) => void;
 }
-type TCleanStateInstance<TState extends object> = TState & _CleanState_<TState>;
-declare const _CleanState: new <TState extends object>(...args: ConstructorParameters<typeof _CleanState_>) => TCleanStateInstance<TState>;
-export type CleanState<TState extends object> = InstanceType<typeof _CleanState<TState>>;
+type TCleanStateInstance<TState extends object> = TState & CleanStateBase<TState>;
+interface ICleanStateClass {
+    update: <TState extends object>(this: CleanStateBase<TState>, stateAndSetters: TUseStateResponses<TState>) => void;
+}
+export type TCleanState<TState extends object> = TCleanStateInstance<TState>;
 type Func = (...params: any[]) => any;
-type UseCleanState = <TStateObjOrFactory extends ((props?: TProps) => object) | object, TProps extends object = object>(_initialState: TStateObjOrFactory, props?: TStateObjOrFactory extends Func ? TProps : undefined) => CleanState<TStateObjOrFactory extends Func ? ReturnType<TStateObjOrFactory> : TStateObjOrFactory>;
+type UseCleanState = <TState extends object, TProps extends object = object>(_initialState: ((props?: TProps) => TState) | TState, // TStateObjOrFactory,
+props?: typeof _initialState extends Func ? TProps : undefined) => TCleanState<TState>;
 export declare const useCleanState: UseCleanState;
 /**
  * Returns a value that is false before the component has been mounted,

package/build/base/state.js

@@ -1,27 +1,47 @@
 "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.useMountState = exports.useCleanState = void 0;
 var react_1 = require("react");
-var _CleanState_ = /** @class */ (function () {
-    function _CleanState_(stateAndSetters) {
+var CleanStateBase = /** @class */ (function () {
+    function CleanStateBase() {
         var _this = this;
+        this.valueKeys = [];
         this._values_ = {};
         this._setters_ = {};
-        this.put = this._setters_;
         this.putMany = function (newValues) {
             Object.entries(newValues).forEach(function (_a) {
                 var key = _a[0], value = _a[1];
                 _this.put[key](value);
             });
         };
-        /** Must be extracted before the loop begins to avoid including keys from the consumers state object. */
-        var reservedKeys = Object.keys(this);
+        this.reservedKeys = Object.keys(this);
+    }
+    Object.defineProperty(CleanStateBase.prototype, "put", {
+        get: function () {
+            return __assign({}, this._setters_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    CleanStateBase.update = function update(stateAndSetters) {
+        var _this = this;
         Object.entries(stateAndSetters).forEach(function (_a) {
             var key = _a[0], responseFromUseState = _a[1];
-            if (reservedKeys.includes(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._values_[key] = responseFromUseState[0], _this._setters_[key] = responseFromUseState[1];
-            // this.put[key] = this._setters_[key];
             var self = _this;
             Object.defineProperty(_this, key, {
                 get: function () {
@@ -33,11 +53,14 @@ var _CleanState_ = /** @class */ (function () {
                 enumerable: true,
             });
         });
-    }
-    return _CleanState_;
+        // return this;
+    };
+    return CleanStateBase;
 }());
 ;
-var _CleanState = _CleanState_;
+var a;
+var CleanState = CleanStateBase;
+var na = new CleanState();
 /**
  * Linters complain about the use of a React hook within a loop because:
  * > By following this rule, you ensure that Hooks are called in the same order each time a component renders.
@@ -50,6 +73,8 @@ var _CleanState = _CleanState_;
 var retrieveState = react_1.useState;
 var useCleanState = function (_initialState, props) {
     var initialState = typeof _initialState === 'function' ? _initialState(props) : _initialState;
+    // props?.s
+    var cleanState = (0, react_1.useMemo)(function () { return new CleanState(); }, []);
     var stateKeys = Object.keys(initialState);
     var initialCount = (0, react_1.useState)(stateKeys.length)[0];
     if (stateKeys.length !== initialCount) {
@@ -60,10 +85,8 @@ var useCleanState = function (_initialState, props) {
         var key = stateKeys_1[_i];
         stateAndSetters[key] = retrieveState(initialState[key]);
     }
-    // @todo Refactor to return consistent state instance each render.
-    // Though useState gives us persistent references for values and setters,
-    // so keeping the CleanState wrapper persistent may be unnecessary.
-    return new _CleanState(stateAndSetters);
+    CleanState.update.call(cleanState, stateAndSetters);
+    return cleanState;
 };
 exports.useCleanState = useCleanState;
 /**

package/build/classy/class.d.ts

@@ -5,6 +5,12 @@ type Obj = Record<string, any>;
 type IComponentConstructor = ComponentInstanceConstructor<any, any, any> & typeof ClassComponent<any, any, any>;
 export declare class ClassComponent<TState extends Obj, TProps extends Obj, THooks extends Obj> extends ComponentInstance<TState, TProps, THooks> {
     Render: FunctionComponent<TProps>;
+    /**
+     * Use this to let React know whenever you would like all of your instance's state to be reset.
+     * When the value is changed, React will reset all state variables to their initial value the next time your component re-renders.
+     * @see https://react.dev/learn/you-might-not-need-an-effect#resetting-all-state-when-a-prop-changes
+     */
+    instanceId?: string;
     static FC: <IComponentType extends IComponentConstructor>(this: IComponentType, _Component?: IComponentType) => (props: InstanceType<IComponentType>["props"]) => JSX.Element;
 }
 export {};

package/build/classy/class.js

@@ -43,10 +43,10 @@ var ClassComponent = /** @class */ (function (_super) {
         if (!Component.getInitialState || !isClassComponentType)
             throw new Error('Attempted to initialize ClassComponent with invalid Class type. Either pass a class that extends ClassComponent to FC (e.g `export FC(MyComponent);`), or ensure it is called as a method on a ClassComponent constructor type (e.g `export MyComponent.FC()`).');
         var Wrapper = function (props) {
-            var Render = (0, instance_1.useInstance)(Component, props).Render;
+            var _a = (0, instance_1.useInstance)(Component, props), Render = _a.Render, instanceId = _a.instanceId;
             // Add calling component name to Render function name in stack traces.
             (0, react_1.useMemo)(function () { return setFunctionName(Render, "".concat(Component.name, ".Render")); }, []);
-            return (0, jsx_runtime_1.jsx)(Render, {});
+            return (0, jsx_runtime_1.jsx)(Render, {}, instanceId);
         };
         // Include calling component name in wrapper function name on stack traces.
         var wrapperName = "ClassComponent".concat(Wrapper.name, " > ").concat(Component.name);

package/build/classy/instance.d.ts

@@ -1,13 +1,51 @@
 import type { ComponentLogicConstructor } from './logic';
 import { ComponentLogic } from './logic';
 type Obj = Record<string, any>;
-type AsyncAllowedEffectCallback = () => IVoidFunction | Promise<IVoidFunction>;
+type AsyncAllowedEffectCallback = () => Awaitable<IVoidFunction>;
 export declare const noOp: () => void;
 export declare class ComponentInstance<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> extends ComponentLogic<TState, TProps, THooks> {
+    /**
+     * Runs only _before_ first render, i.e before the component instance is mounted.
+     * Useful for logic that is involved in determining what to render.
+     *
+     * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+     * and prompt React to immediately rerender the component with the updated state value(s).
+     *
+     * Ignored on subsequent rerenders.
+     */
     beforeMount: IVoidFunction;
+    /**
+     * Runs only **_after_** first render, i.e after the component instance is mounted.
+     *
+     * Should usually only be used for logic that does not directly take part in determining what to render, like
+     * synchronize your component with some external system.
+     *
+     * Ignored on subsequent rerenders.
+     *
+     * Returns a cleanup function.
+     */
     onMount: AsyncAllowedEffectCallback;
+    /**
+     * Runs _before_ every render cycle, including the first.
+     * Useful for logic that is involved in determining what to render.
+     *
+     * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+     * and prompt React to immediately rerender the component with the updated state value(s).
+     */
     beforeRender: IVoidFunction;
+    /**
+     * Runs **_after_** every render cycle, including the first.
+     *
+     * Should usually only be used for logic that does not directly take part in determining what to render, like
+     * synchronize your component with some external system.
+     *
+     * Returns a cleanup function.
+     */
     onRender: AsyncAllowedEffectCallback;
+    /**
+     * Runs when the component is unmounted.
+     * It is called _after_ the cleanup function returned by onMount.
+     */
     cleanUp: IVoidFunction;
 }
 type ComponentClassBaseType<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> = ComponentLogicConstructor<TState, TProps, THooks> & Constructor<ComponentInstance<TState, TProps, THooks>>;

package/build/classy/instance.js

@@ -25,10 +25,48 @@ var ComponentInstance = /** @class */ (function (_super) {
     __extends(ComponentInstance, _super);
     function ComponentInstance() {
         var _this = _super !== null && _super.apply(this, arguments) || this;
+        /**
+         * Runs only _before_ first render, i.e before the component instance is mounted.
+         * Useful for logic that is involved in determining what to render.
+         *
+         * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+         * and prompt React to immediately rerender the component with the updated state value(s).
+         *
+         * Ignored on subsequent rerenders.
+         */
         _this.beforeMount = function () { };
+        /**
+         * Runs only **_after_** first render, i.e after the component instance is mounted.
+         *
+         * Should usually only be used for logic that does not directly take part in determining what to render, like
+         * synchronize your component with some external system.
+         *
+         * Ignored on subsequent rerenders.
+         *
+         * Returns a cleanup function.
+         */
         _this.onMount = function () { return exports.noOp; };
+        /**
+         * Runs _before_ every render cycle, including the first.
+         * Useful for logic that is involved in determining what to render.
+         *
+         * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+         * and prompt React to immediately rerender the component with the updated state value(s).
+         */
         _this.beforeRender = function () { };
+        /**
+         * Runs **_after_** every render cycle, including the first.
+         *
+         * Should usually only be used for logic that does not directly take part in determining what to render, like
+         * synchronize your component with some external system.
+         *
+         * Returns a cleanup function.
+         */
         _this.onRender = function () { return exports.noOp; };
+        /**
+         * Runs when the component is unmounted.
+         * It is called _after_ the cleanup function returned by onMount.
+         */
         _this.cleanUp = function () { };
         return _this;
     }
@@ -48,6 +86,7 @@ var useMountCallbacks = function (instance) {
             var doCleanUp = function (runMountCleaners) {
                 var _a;
                 runMountCleaners === null || runMountCleaners === void 0 ? void 0 : runMountCleaners();
+                // onDismount? willUnmount?
                 (_a = instance.cleanUp) === null || _a === void 0 ? void 0 : _a.call(instance);
             };
             if (typeof mountHandlerCleanUp === 'function') {
@@ -62,7 +101,7 @@ var useMountCallbacks = function (instance) {
 exports.useMountCallbacks = useMountCallbacks;
 var useInstance = function (Component, props) {
     var _a;
-    // useCustomHooks.
+    // useHooks.
     var instance = (0, logic_1.useLogic)(Component, props);
     // beforeMount, onMount, cleanUp.
     (0, exports.useMountCallbacks)(instance);

package/build/classy/logic.d.ts

@@ -1,9 +1,9 @@
-import type { CleanState } from '../base/state';
+import type { TCleanState } from '../base/state';
 export declare class ComponentLogic<TState extends object, TProps extends object, THooks extends object> {
-    state: CleanState<TState>;
+    state: TCleanState<TState>;
     props: TProps;
     hooks: THooks;
-    useCustomHooks?: () => THooks;
+    useHooks?: () => THooks;
 }
 export interface ComponentLogicConstructor<TState extends object, TProps extends object, THooks extends object> extends Constructor<ComponentLogic<TState, TProps, THooks>> {
     getInitialState: (props?: TProps) => TState;

package/build/classy/logic.js

@@ -24,7 +24,7 @@ var useLogic = function (Methods, props) {
     }, []);
     methods.state = state;
     methods.props = props;
-    methods.hooks = ((_a = methods.useCustomHooks) === null || _a === void 0 ? void 0 : _a.call(methods)) || {};
+    methods.hooks = ((_a = methods.useHooks) === null || _a === void 0 ? void 0 : _a.call(methods)) || {};
     return methods;
 };
 exports.useLogic = useLogic;

package/build/globals.d.ts

@@ -8,6 +8,8 @@ type Optional<
 		: BaseType | undefined
 )
 
+type Awaitable<Type> = Type | Promise<Type>;
+
 type Constructor<
 	TInstance extends any = any,
 	TParams extends any[] = never[]

package/build/index.js

@@ -15,3 +15,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./classy"), exports);
+// PS: Document component inheritance pattern with lifecycle callback arrays and namespaces.
+// Due to react's remounting behaviour, components must externally track when some logic has run, if it really really must only ever run once per mounted instance. Tricky to get right for components that may have multiple instance rendered simultaneously at different parts of a page.
+// Note: There is an alternative clean-state implementation that uses a single useState call and passes the clean state instance.
+// Then when a state setter is used, it mutates the cleanstate object, then calls setState on the updated cleanstate.
+// But setState might ignore calls with the same object ref as the existing state value, so perhaps create a new cleanstate
+// instance instead, spreading existing values with the changed values, and call setState with that.
+// It could be more performant as it would remove the need for looping over Object.keys in useCleanState.
+// Investigate this for a potential minor version update.
+// useCleanState => useState
+// useMethods => useCallback
+// useLogic => useCallback + all other hook calls.
+// useInstance => useLogic + lifecycle methods.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleanweb/react",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "A suite of helpers for writing cleaner React function components.",
   "engines": {
     "node": ">=18"