@cleanweb/react 2.1.3 → 2.1.5

package/build/base/methods.d.ts

@@ -15,7 +15,81 @@ import type { TCleanState, TStateData } from './state';
 export declare class ComponentMethods<TProps extends object = {}, TState extends TStateData | null = null> {
     readonly props: TProps;
     readonly state: TState extends TStateData ? TCleanState<TState> : null;
+    /**
+     * Specify custom class members to be copied over whenever the class is
+     * reinstantiated during hot module replacement.
+     *
+     * Oore handles HMR by recreating the class instance
+     * with the updated code whenever there is a file change.
+     * Your component is then rerendered so that event handlers
+     * now point to the new functions.
+     *
+     * For this to work well, your component's state needs to be preserved,
+     * so it is copied over from the old instance, to the newly created one.
+     * This includes `state`, `props` by default, but you can
+     * extend it to include more properties if there are values your component expects
+     * to be persistent.
+     *
+     * In most case, any values you wish to preserve should be created `React.useRef`.
+     * ```
+     * // In useHooks method:
+     * this.inputId = useRef(inputId);
+     * // And access anywhere with:
+     * this.inputId.current;
+     * ```
+     * If you use a ref in this way, React will preserve it for you, and there will be no need
+     * to use `_hmrPreserveKeys`.
+     *
+     * `_hmrPreserveKeys` is only relevant in development and has not effect in production environment.
+     * Accordingly, you should only update this array when environment is development, so
+     * that it can be tree-shaken during production builds.
+     *
+     * @example Specify additional properties to be considered stateful,
+     * in addition to `state`, `props`, and `hooks`.
+     * ```ts
+     * MyComponentMethods extends ComponentMethods {
+     *     // Some class member definitions...
+     *
+     *     constructor() {
+     *         if (process.env.NODE_ENV === 'development') {
+     *             this._hmrPreserveKeys.push('inputId', 'unsubscribeCallback');
+     *         }
+     *     }
+     *
+     *     // Method definitions...
+     * }
+     * With the above example, whenever HMR occurs, `this.inputId` and `this.unsubscribeCallback`
+     * will maintain there existing values, while everything else will be recreated. Meanwhile,
+     * because the code is written in an environment condition, it should be easy to strip it from the
+     * production build to avoid shipping dead code.
+     */
     _hmrPreserveKeys: Array<keyof this | (string & {})>;
+    /**
+     * Handle complex update logic whenever your component instance is updated through HMR.
+     * The function is called on the new instance, and it receives the old instance as the only argument.
+     * So you can access data from the old instance, and reinitialize any processes on the new instance as needed.
+     *
+     *
+     * `_onHmrUpdate` is only relevant in development and has not effect in production environment.
+     * Accordingly, you should only assign this function when environment is development, so
+     * that it can be tree-shaken during production builds.
+     *
+     * @example
+     * ```ts
+     * MyComponentMethods extends ComponentMethods {
+     *     // Some class member definitions...
+     *
+     *     constructor() {
+     *         if (process.env.NODE_ENV === 'development') {
+     *             this._onHmrUpdate = () => {
+     *                 // Your custom hmr logic here.
+     *             };
+     *         }
+     *     }
+     *
+     *     // Method definitions...
+     * }
+     */
     _onHmrUpdate?: <TInstance extends this>(oldInstance: TInstance) => void;
 }
 type UseMethods = {

package/build/base/methods.js

@@ -2,15 +2,6 @@
 /**
  * @module ComponentMethods
  */
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useMethods = exports.ComponentMethods = void 0;
 // JSDoc references
@@ -29,7 +20,55 @@ var react_1 = require("react");
  */
 var ComponentMethods = /** @class */ (function () {
     function ComponentMethods() {
-        this._hmrPreserveKeys = [];
+        /**
+         * Specify custom class members to be copied over whenever the class is
+         * reinstantiated during hot module replacement.
+         *
+         * Oore handles HMR by recreating the class instance
+         * with the updated code whenever there is a file change.
+         * Your component is then rerendered so that event handlers
+         * now point to the new functions.
+         *
+         * For this to work well, your component's state needs to be preserved,
+         * so it is copied over from the old instance, to the newly created one.
+         * This includes `state`, `props` by default, but you can
+         * extend it to include more properties if there are values your component expects
+         * to be persistent.
+         *
+         * In most case, any values you wish to preserve should be created `React.useRef`.
+         * ```
+         * // In useHooks method:
+         * this.inputId = useRef(inputId);
+         * // And access anywhere with:
+         * this.inputId.current;
+         * ```
+         * If you use a ref in this way, React will preserve it for you, and there will be no need
+         * to use `_hmrPreserveKeys`.
+         *
+         * `_hmrPreserveKeys` is only relevant in development and has not effect in production environment.
+         * Accordingly, you should only update this array when environment is development, so
+         * that it can be tree-shaken during production builds.
+         *
+         * @example Specify additional properties to be considered stateful,
+         * in addition to `state`, `props`, and `hooks`.
+         * ```ts
+         * MyComponentMethods extends ComponentMethods {
+         *     // Some class member definitions...
+         *
+         *     constructor() {
+         *         if (process.env.NODE_ENV === 'development') {
+         *             this._hmrPreserveKeys.push('inputId', 'unsubscribeCallback');
+         *         }
+         *     }
+         *
+         *     // Method definitions...
+         * }
+         * With the above example, whenever HMR occurs, `this.inputId` and `this.unsubscribeCallback`
+         * will maintain there existing values, while everything else will be recreated. Meanwhile,
+         * because the code is written in an environment condition, it should be easy to strip it from the
+         * production build to avoid shipping dead code.
+         */
+        this._hmrPreserveKeys = []; // @todo Keep undefined. Update to empty array after instantiation in dev env.
     }
     return ComponentMethods;
 }());
@@ -72,10 +111,7 @@ var useMethods = function () {
                 'all clean-react hooks receive the same class argument on every render.'
             ].join(' '));
             var oldInstance = instanceRef.current;
-            var hmrPreserveKeys = __spreadArray(__spreadArray([], latestInstance._hmrPreserveKeys, true), [
-                'state', 'props',
-            ], false);
-            hmrPreserveKeys.forEach(function (_key) {
+            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[key];

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

@@ -2,8 +2,6 @@ import { CleanStateBase } from './class';
 /**
  * Base type for an `initialState` object.
  * It is a regular object type, with some reserved keys excluded.
- *
- * @_category Types
  */
 export type TStateData = object & {
     [Key in keyof CleanStateBase<{}>]?: never;
@@ -13,8 +11,6 @@ export type TStateData = object & {
  * object of type `TState`.
  *
  * @typeParam TState - The type of your `initialState` object.
- *
- * @_category Types
  */
 export type TCleanState<TState extends TStateData> = (CleanStateBase<TState> & Omit<TState, keyof CleanStateBase<{}>>);
 /**

package/build/classy/instance/types/hook.d.ts

@@ -1,6 +1,5 @@
-import { TPropsBase } from '../../../classy/logic';
 import { ComponentInstance } from '..';
-type UIClassParam = typeof ComponentInstance<NonNullable<TPropsBase>>;
+type UIClassParam = typeof ComponentInstance<NonNullable<any>>;
 type UIProplessClassParam = typeof ComponentInstance<null>;
 export type UseInstance = {
     <Class extends UIProplessClassParam>(Methods: Class): InstanceType<Class>;

package/build/classy/logic/index.d.ts

@@ -23,9 +23,6 @@ export type TPropsBase = NonPrimitive | null;
  * Call the {@link useLogic} hook inside your function component to instantiate the class.
  *
  * @typeParam TProps - {@include ./types/tprops.md}
- *
- * @group ComponentLogic
- * @_category External Classes
  */
 export declare class ComponentLogic<TProps extends TPropsBase = null> {
     /**
@@ -58,7 +55,81 @@ export declare class ComponentLogic<TProps extends TPropsBase = null> {
      * your component class.
      */
     useHooks: () => object | void;
+    /**
+     * Specify custom class members to be copied over whenever the class is
+     * reinstantiated during hot module replacement.
+     *
+     * Oore handles HMR by recreating the class instance
+     * with the updated code whenever there is a file change.
+     * Your component is then rerendered so that event handlers
+     * now point to the new functions.
+     *
+     * For this to work well, your component's state needs to be preserved,
+     * so it is copied over from the old instance, to the newly created one.
+     * This includes `state`, `props` by default, but you can
+     * extend it to include more properties if there are values your component expects
+     * to be persistent.
+     *
+     * In most case, any values you wish to preserve should be created `React.useRef`.
+     * ```
+     * // In useHooks method:
+     * this.inputId = useRef(inputId);
+     * // And access anywhere with:
+     * this.inputId.current;
+     * ```
+     * If you use a ref in this way, React will preserve it for you, and there will be no need
+     * to use `_hmrPreserveKeys`.
+     *
+     * `_hmrPreserveKeys` is only relevant in development and has not effect in production environment.
+     * Accordingly, you should only update this array when environment is development, so
+     * that it can be tree-shaken during production builds.
+     *
+     * @example Specify additional properties to be considered stateful,
+     * in addition to `state`, `props`, and `hooks`.
+     * ```ts
+     * MyComponentMethods extends ComponentMethods {
+     *     // Some class member definitions...
+     *
+     *     constructor() {
+     *         if (process.env.NODE_ENV === 'development') {
+     *             this._hmrPreserveKeys.push('inputId', 'unsubscribeCallback');
+     *         }
+     *     }
+     *
+     *     // Method definitions...
+     * }
+     * With the above example, whenever HMR occurs, `this.inputId` and `this.unsubscribeCallback`
+     * will maintain there existing values, while everything else will be recreated. Meanwhile,
+     * because the code is written in an environment condition, it should be easy to strip it from the
+     * production build to avoid shipping dead code.
+     */
     _hmrPreserveKeys: Array<keyof this | (string & {})>;
+    /**
+     * Handle complex update logic whenever your component instance is updated through HMR.
+     * The function is called on the new instance, and it receives the old instance as the only argument.
+     * So you can access data from the old instance, and reinitialize any processes on the new instance as needed.
+     *
+     *
+     * `_onHmrUpdate` is only relevant in development and has not effect in production environment.
+     * Accordingly, you should only assign this function when environment is development, so
+     * that it can be tree-shaken during production builds.
+     *
+     * @example
+     * ```ts
+     * MyComponentMethods extends ComponentMethods {
+     *     // Some class member definitions...
+     *
+     *     constructor() {
+     *         if (process.env.NODE_ENV === 'development') {
+     *             this._onHmrUpdate = () => {
+     *                 // Your custom hmr logic here.
+     *             };
+     *         }
+     *     }
+     *
+     *     // Method definitions...
+     * }
+     */
     _onHmrUpdate?: <TInstance extends this>(oldInstance: TInstance) => void;
 }
 /**

package/build/classy/logic/index.js

@@ -1,13 +1,4 @@
 "use strict";
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useLogic = exports.ComponentLogic = void 0;
 var react_1 = require("react");
@@ -25,9 +16,6 @@ var state_1 = require("../../base/state");
  * Call the {@link useLogic} hook inside your function component to instantiate the class.
  *
  * @typeParam TProps - {@include ./types/tprops.md}
- *
- * @group ComponentLogic
- * @_category External Classes
  */
 var ComponentLogic = /** @class */ (function () {
     function ComponentLogic() {
@@ -46,6 +34,54 @@ var ComponentLogic = /** @class */ (function () {
          * your component class.
          */
         this.useHooks = function () { };
+        /**
+         * Specify custom class members to be copied over whenever the class is
+         * reinstantiated during hot module replacement.
+         *
+         * Oore handles HMR by recreating the class instance
+         * with the updated code whenever there is a file change.
+         * Your component is then rerendered so that event handlers
+         * now point to the new functions.
+         *
+         * For this to work well, your component's state needs to be preserved,
+         * so it is copied over from the old instance, to the newly created one.
+         * This includes `state`, `props` by default, but you can
+         * extend it to include more properties if there are values your component expects
+         * to be persistent.
+         *
+         * In most case, any values you wish to preserve should be created `React.useRef`.
+         * ```
+         * // In useHooks method:
+         * this.inputId = useRef(inputId);
+         * // And access anywhere with:
+         * this.inputId.current;
+         * ```
+         * If you use a ref in this way, React will preserve it for you, and there will be no need
+         * to use `_hmrPreserveKeys`.
+         *
+         * `_hmrPreserveKeys` is only relevant in development and has not effect in production environment.
+         * Accordingly, you should only update this array when environment is development, so
+         * that it can be tree-shaken during production builds.
+         *
+         * @example Specify additional properties to be considered stateful,
+         * in addition to `state`, `props`, and `hooks`.
+         * ```ts
+         * MyComponentMethods extends ComponentMethods {
+         *     // Some class member definitions...
+         *
+         *     constructor() {
+         *         if (process.env.NODE_ENV === 'development') {
+         *             this._hmrPreserveKeys.push('inputId', 'unsubscribeCallback');
+         *         }
+         *     }
+         *
+         *     // Method definitions...
+         * }
+         * With the above example, whenever HMR occurs, `this.inputId` and `this.unsubscribeCallback`
+         * will maintain there existing values, while everything else will be recreated. Meanwhile,
+         * because the code is written in an environment condition, it should be easy to strip it from the
+         * production build to avoid shipping dead code.
+         */
         this._hmrPreserveKeys = [];
     }
     return ComponentLogic;
@@ -84,10 +120,7 @@ var useLogic = function () {
                 'all clean-react hooks receive the same class argument on every render.'
             ].join(' '));
             var oldInstance_1 = instanceRef.current;
-            var hmrPreserveKeys = __spreadArray(__spreadArray([], latestInstance._hmrPreserveKeys, true), [
-                'state', 'props', 'hooks',
-            ], false);
-            hmrPreserveKeys.forEach(function (_key) {
+            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];

package/build/classy/logic/types/hook.d.ts

@@ -1,8 +1,8 @@
-import type { ComponentLogic, TPropsBase } from '..';
+import type { ComponentLogic } from '..';
 /*************************************
  *        # Hooks                    *
 **************************************/
-type ULClassParam = typeof ComponentLogic<NonNullable<TPropsBase>>;
+type ULClassParam = typeof ComponentLogic<NonNullable<any>>;
 type ULProplessClassParam = typeof ComponentLogic<null>;
 export type UseLogic = {
     <Class extends ULProplessClassParam>(Methods: Class): InstanceType<Class>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleanweb/react",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "A suite of helpers for writing cleaner React function components.",
   "engines": {
     "node": ">=18"
@@ -22,10 +22,10 @@
     "./all": "./build/index.js"
   },
   "scripts": {
-    "prebuild": "rimraf ./build",
+    "prebuild": "rimraf ./build && npm run build:docs",
     "build": "tsc && tsc-alias",
     "serve-docs": "serve docs",
-    "postbuild": "copyfiles tsconfig.json build && npm run build:docs",
+    "postbuild": "copyfiles tsconfig.json build",
     "build:docs": "typedoc",
     "_": "",
     "prepublishOnly": "npm run build",