@cleanweb/react 1.0.0

package/build/class.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentInstanceConstructor } from '@/instance';
+import { FunctionComponent } from "react";
+import { ComponentInstance } from '@/instance';
+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>;
+    static FC: <IComponentType extends IComponentConstructor>(this: IComponentType, _Component?: IComponentType) => (props: InstanceType<IComponentType>["props"]) => import("react").JSX.Element;
+}
+export {};

package/build/class.jsx

@@ -0,0 +1,54 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { useMemo } from "react";
+import { ComponentInstance, useInstance } from '@/instance';
+/** Provide more useful stack traces for otherwise non-specific function names. */
+var setFunctionName = function (func, newName) {
+    try {
+        // Must use try block, as `name` is not configurable on older browsers, and may yield a TypeError.
+        Object.defineProperty(func, 'name', {
+            writable: true,
+            value: newName,
+        });
+    }
+    catch (error) {
+        console.warn(error);
+    }
+};
+var ClassComponent = /** @class */ (function (_super) {
+    __extends(ClassComponent, _super);
+    function ClassComponent() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    ClassComponent.FC = function FC(_Component) {
+        var Component = _Component || this;
+        var isClassComponentType = Component.prototype instanceof ClassComponent;
+        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 = useInstance(Component, props).Render;
+            // Add calling component name to Render function name in stack traces.
+            useMemo(function () { return setFunctionName(Render, "".concat(Component.name, ".Render")); }, []);
+            return <Render />;
+        };
+        // Include calling component name in wrapper function name on stack traces.
+        var wrapperName = "ClassComponent".concat(Wrapper.name, " > ").concat(Component.name);
+        setFunctionName(Wrapper, wrapperName);
+        return Wrapper;
+    };
+    return ClassComponent;
+}(ComponentInstance));
+export { ClassComponent };

package/build/globals.d.ts

@@ -0,0 +1,52 @@
+
+type Optional<
+			BaseType,
+			AllowNull extends boolean = true
+		> = (
+	AllowNull extends true
+		? BaseType | undefined | null
+		: BaseType | undefined
+)
+
+type Constructor<
+	TInstance extends any = any,
+	TParams extends any[] = never[]
+> = new (...args: TParams) => TInstance
+
+
+/**
+ * @example
+ * ```js
+ * const getNumber: AsyncFunction<number> = async () => {
+ * 	await oneTickDelay();
+ * 	return 5;
+ * }
+ * ```
+ */
+declare type AsyncFunction<
+	TReturnValue extends any = void,
+	Params extends any[] = never[]
+> = (...params: Params) => Promise<TReturnValue>
+
+/**
+ * A function that takes no arguments and returns nothing.
+ * Pass a type argument to set whether `async` and/or `sync` functions are allowed.
+ */
+declare interface IVoidFunction<AsyncType extends 'async' | 'sync' | 'both' = 'both'> {
+	(): AsyncType extends 'async' ? Promise<void>
+		: AsyncType extends 'sync' ? void
+		: Promise<void> | void
+}
+
+declare interface Window {
+}
+
+declare namespace JSX {
+	interface IntrinsicElements {
+	}
+}
+
+declare namespace NodeJS {
+	interface ProcessEnv {
+	}
+}

package/build/instance.d.ts

@@ -0,0 +1,18 @@
+import { ComponentLogic, ComponentLogicConstructor } from "./logic";
+type Obj = Record<string, any>;
+type AsyncAllowedEffectCallback = () => IVoidFunction | Promise<IVoidFunction>;
+export declare const noOp: () => void;
+export declare class ComponentInstance<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> extends ComponentLogic<TState, TProps, THooks> {
+    beforeMount: IVoidFunction;
+    onMount: AsyncAllowedEffectCallback;
+    beforeRender: IVoidFunction;
+    onRender: AsyncAllowedEffectCallback;
+    cleanUp: IVoidFunction;
+}
+type ComponentClassBaseType<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> = ComponentLogicConstructor<TState, TProps, THooks> & Constructor<ComponentInstance<TState, TProps, THooks>>;
+export interface ComponentInstanceConstructor<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> extends ComponentClassBaseType<TState, TProps, THooks> {
+}
+type UseInstance = <TClass extends ComponentInstanceConstructor>(Class: TClass, props: InstanceType<TClass>['props']) => InstanceType<TClass>;
+export declare const useMountCallbacks: <TInstance extends ComponentInstance<any, any, any>>(instance: TInstance) => void;
+export declare const useInstance: UseInstance;
+export {};

package/build/instance.js

@@ -0,0 +1,81 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { useEffect } from "react";
+import { useMountState } from "./state";
+import { ComponentLogic, useLogic } from "./logic";
+export var noOp = function () { };
+var ComponentInstance = /** @class */ (function (_super) {
+    __extends(ComponentInstance, _super);
+    function ComponentInstance() {
+        var _this = _super !== null && _super.apply(this, arguments) || this;
+        _this.beforeMount = function () { };
+        _this.onMount = function () { return noOp; };
+        _this.beforeRender = function () { };
+        _this.onRender = function () { return noOp; };
+        _this.cleanUp = function () { };
+        return _this;
+    }
+    return ComponentInstance;
+}(ComponentLogic));
+export { ComponentInstance };
+;
+export var useMountCallbacks = function (instance) {
+    var _a;
+    var mounted = useMountState();
+    if (!mounted)
+        (_a = instance.beforeMount) === null || _a === void 0 ? void 0 : _a.call(instance);
+    useEffect(function () {
+        var _a;
+        var mountHandlerCleanUp = (_a = instance.onMount) === null || _a === void 0 ? void 0 : _a.call(instance);
+        return function () {
+            var doCleanUp = function (runMountCleaners) {
+                var _a;
+                runMountCleaners === null || runMountCleaners === void 0 ? void 0 : runMountCleaners();
+                (_a = instance.cleanUp) === null || _a === void 0 ? void 0 : _a.call(instance);
+            };
+            if (typeof mountHandlerCleanUp === 'function') {
+                doCleanUp(mountHandlerCleanUp);
+            }
+            else {
+                mountHandlerCleanUp === null || mountHandlerCleanUp === void 0 ? void 0 : mountHandlerCleanUp.then(doCleanUp);
+            }
+        };
+    }, []);
+};
+export var useInstance = function (Component, props) {
+    var _a;
+    // useCustomHooks.
+    var instance = useLogic(Component, props);
+    // beforeMount, onMount, cleanUp.
+    useMountCallbacks(instance);
+    (_a = instance.beforeRender) === null || _a === void 0 ? void 0 : _a.call(instance);
+    useEffect(function () {
+        var _a;
+        var cleanupAfterRerender = (_a = instance.onRender) === null || _a === void 0 ? void 0 : _a.call(instance);
+        return function () {
+            var doCleanUp = function (runRenderCleanup) {
+                runRenderCleanup === null || runRenderCleanup === void 0 ? void 0 : runRenderCleanup();
+            };
+            if (typeof cleanupAfterRerender === 'function') {
+                doCleanUp(cleanupAfterRerender);
+            }
+            else {
+                cleanupAfterRerender === null || cleanupAfterRerender === void 0 ? void 0 : cleanupAfterRerender.then(doCleanUp);
+            }
+        };
+    });
+    return instance;
+};

package/build/logic.d.ts

@@ -0,0 +1,13 @@
+import type { CleanState } from "./state";
+export declare class ComponentLogic<TState extends object, TProps extends object, THooks extends object> {
+    state: CleanState<TState>;
+    props: TProps;
+    hooks: THooks;
+    useCustomHooks?: () => THooks;
+}
+export interface ComponentLogicConstructor<TState extends object, TProps extends object, THooks extends object> extends Constructor<ComponentLogic<TState, TProps, THooks>> {
+    getInitialState: (props?: TProps) => TState;
+}
+type UseLogic = <TState extends object, LogicClass extends ComponentLogicConstructor<TState, any, any>>(Methods: LogicClass, props: InstanceType<LogicClass>['props']) => InstanceType<LogicClass>;
+export declare const useLogic: UseLogic;
+export {};

package/build/logic.js

@@ -0,0 +1,26 @@
+import { useMemo } from "react";
+import { useCleanState } from "./state";
+var ComponentLogic = /** @class */ (function () {
+    function ComponentLogic() {
+    }
+    return ComponentLogic;
+}());
+export { ComponentLogic };
+;
+export var useLogic = function (Methods, props) {
+    var _a;
+    var state = useCleanState(Methods.getInitialState, props);
+    // There's apparently a bug? with Typescript that pegs the return type of "new Methods()" to "ComponentLogic<{}, {}, {}>",
+    // completely ignoring the type specified for Methods in the function's type definition.
+    // `new Methods()` should return whatever the InstanceType of TClass is, as that is the type explicitly specified for Methods.
+    // Ignoring the specified type to gin up something else and then complain about it is quite weird.
+    // Regardless, even when `extends ComponentLogicConstructor<TState, TProps, THooks>` is specified using generics instead of a set type,
+    // the issue persists. Which is absurd since this should ensure that InstanceType<Class> should exactly match ComponentLogic<TState, TProps, THooks>
+    var methods = useMemo(function () {
+        return new Methods();
+    }, []);
+    methods.state = state;
+    methods.props = props;
+    methods.hooks = ((_a = methods.useCustomHooks) === null || _a === void 0 ? void 0 : _a.call(methods)) || {};
+    return methods;
+};

package/build/methods.d.ts

@@ -0,0 +1,9 @@
+import type { CleanState } from "./state";
+export declare class ComponentMethods<TState extends object, TProps extends object> {
+    state: CleanState<TState>;
+    props: TProps;
+}
+type ComponentMethodsConstructor = typeof ComponentMethods<any, any>;
+type UseMethods = <MethodsClass extends ComponentMethodsConstructor>(Methods: MethodsClass, state: InstanceType<MethodsClass>['state'], props: InstanceType<MethodsClass>['props']) => InstanceType<MethodsClass>;
+export declare const useMethods: UseMethods;
+export {};

package/build/methods.js

@@ -0,0 +1,29 @@
+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);
+};
+import { useMemo } from "react";
+var ComponentMethods = /** @class */ (function () {
+    function ComponentMethods() {
+    }
+    return ComponentMethods;
+}());
+export { ComponentMethods };
+;
+export var useMethods = function (Methods, state, props) {
+    var methods = useMemo(function () {
+        // See useLogic implementation for a discussion of this type assertion.
+        return new Methods();
+    }, []);
+    methods.state = state;
+    methods.props = props;
+    // Return a gate object to "passthrough" all methods but filter out properties that should be private.
+    return __assign(__assign({}, methods), { props: undefined, state: undefined });
+};

package/build/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cleanweb/react",
+  "version": "1.0.0",
+  "description": "A suite of helpers for writing cleaner React function components.",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "rimraf ./build && tsc && copyfiles README.md package.json .npmrc globals.d.ts tsconfig.json build",
+    "prepublishOnly": "npm run build",
+    "postpublish": "cd ./mirror-pkg && npm publish && cd ..",
+    "test": "echo \"No tests ATM\""
+  },
+  "keywords": [
+    "react",
+    "clean-react",
+    "clean react",
+    "function components",
+    "hooks",
+    "react hooks",
+    "state",
+    "clean state",
+    "group state"
+  ],
+  "author": {
+    "name": "Feranmi Akinlade",
+    "url": "https://feranmi.dev"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "20.14.10",
+    "@types/react": "^16",
+    "copyfiles": "^2.4.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.2"
+  },
+  "peerDependencies": {
+    "react": ">=16"
+  }
+}

package/build/state.d.ts

@@ -0,0 +1,26 @@
+type TUseStateArray<TState extends object> = [
+    val: TState[keyof TState],
+    setter: (val: TState[keyof TState]) => void
+];
+type TUseStateResponses<TState extends object> = {
+    [Key in keyof TState]: TUseStateArray<TState>;
+};
+declare class _CleanState_<TState extends object> {
+    private _values_;
+    private _setters_;
+    put: { [Key in keyof TState]: (value: TState[Key]) => void; };
+    constructor(stateAndSetters: TUseStateResponses<TState>);
+    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 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>;
+export declare const useCleanState: UseCleanState;
+/**
+ * Returns a value that is false before the component has been mounted,
+ * then true during all subsequent rerenders.
+ */
+export declare const useMountState: () => boolean;
+export {};

package/build/state.js

@@ -0,0 +1,81 @@
+import { useEffect, useRef, useState } from "react";
+var _CleanState_ = /** @class */ (function () {
+    function _CleanState_(stateAndSetters) {
+        var _this = this;
+        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);
+        Object.entries(stateAndSetters).forEach(function (_a) {
+            var key = _a[0], responseFromUseState = _a[1];
+            if (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._values_[key] = responseFromUseState[0], _this._setters_[key] = responseFromUseState[1];
+            _this.put[key] = _this._setters_[key];
+            var self = _this;
+            Object.defineProperty(_this, key, {
+                get: function () {
+                    return self._values_[key];
+                },
+                set: function (value) {
+                    self._setters_[key](value);
+                },
+                enumerable: true,
+            });
+        });
+    }
+    return _CleanState_;
+}());
+;
+var _CleanState = _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.
+ * > That’s what allows React to correctly preserve the state of Hooks between multiple useState and useEffect calls.
+ * To resolve this, we're calling `useState` via an alias `retrieveState`.
+ * Bypassing this rule is safe here because `useCleanState` is a special case,
+ * and it guarantees that the same useState calls will be made on every render in the exact same order.
+ * Therefore, it is safe to silence the linters, and required for this implementation to work smoothly.
+ */
+var retrieveState = useState;
+export var useCleanState = function (_initialState, props) {
+    var initialState = typeof _initialState === 'function' ? _initialState(props) : _initialState;
+    var stateKeys = Object.keys(initialState);
+    var initialCount = useState(stateKeys.length)[0];
+    if (stateKeys.length !== initialCount) {
+        throw new Error('The keys in your state object must be consistent throughout your components lifetime. Look up "rules of hooks" for more context.');
+    }
+    var stateAndSetters = {};
+    for (var _i = 0, stateKeys_1 = stateKeys; _i < stateKeys_1.length; _i++) {
+        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);
+};
+/**
+ * Returns a value that is false before the component has been mounted,
+ * then true during all subsequent rerenders.
+ */
+export var useMountState = function () {
+    /**
+     * This must not be a stateful value. It should not be the cause of a rerender.
+     * It merely provides information about the render count,
+     * without influencing that count itself.
+     * So `mounted` should never be set with `useState`.
+     */
+    var mounted = useRef(false);
+    useEffect(function () {
+        mounted.current = true;
+    }, []);
+    return mounted.current;
+};

package/build/tsconfig.json

@@ -0,0 +1,43 @@
+{
+	"compilerOptions": {
+		"baseUrl": ".",
+		"rootDir": ".",
+		"outDir": "build",
+		"paths": {
+			"@/*": [
+				"./*"
+			]
+		},
+		"target": "es5",
+		"lib": [
+			"dom",
+			"dom.iterable",
+			"esnext"
+		],
+		"allowJs": true,
+		"checkJs": true,
+		"declaration": true,
+		"noEmit": false,
+		"skipLibCheck": true,
+		"strict": false,
+		"forceConsistentCasingInFileNames": true,
+		"incremental": false,
+		"esModuleInterop": true,
+		"module": "esnext",
+		"moduleResolution": "node",
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"jsx": "preserve",
+		"strictNullChecks": true
+	},
+	"include": [
+		"next-env.d.ts",
+		"**/*.ts",
+		"**/*.tsx"
+	],
+	"exclude": [
+		"node_modules/**/**.*",
+		"build/**/**.*",
+		"mirror-pkg/**/**.*"
+	]
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cleanweb/react",
+  "version": "1.0.0",
+  "description": "A suite of helpers for writing cleaner React function components.",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "rimraf ./build && tsc && copyfiles README.md package.json .npmrc globals.d.ts tsconfig.json build",
+    "prepublishOnly": "npm run build",
+    "postpublish": "cd ./mirror-pkg && npm publish && cd ..",
+    "test": "echo \"No tests ATM\""
+  },
+  "keywords": [
+    "react",
+    "clean-react",
+    "clean react",
+    "function components",
+    "hooks",
+    "react hooks",
+    "state",
+    "clean state",
+    "group state"
+  ],
+  "author": {
+    "name": "Feranmi Akinlade",
+    "url": "https://feranmi.dev"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "20.14.10",
+    "@types/react": "^16",
+    "copyfiles": "^2.4.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.2"
+  },
+  "peerDependencies": {
+    "react": ">=16"
+  }
+}