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

package/build/base/{state.js → state/class.js}

@@ -11,26 +11,8 @@ var __assign = (this && this.__assign) || function () {
     return __assign.apply(this, arguments);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useCleanState = exports.useMountState = void 0;
+exports.CleanState = exports.CleanStateBase = void 0;
 var react_1 = require("react");
-/**
- * Returns a value that is false before the component has been mounted,
- * then true during all subsequent rerenders.
- */
-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 = (0, react_1.useRef)(false);
-    (0, react_1.useEffect)(function () {
-        mounted.current = true;
-    }, []);
-    return mounted.current;
-};
-exports.useMountState = useMountState;
 var CleanStateBase = /** @class */ (function () {
     function CleanStateBase(initialState) {
         var _this = this;
@@ -85,7 +67,7 @@ var CleanStateBase = /** @class */ (function () {
     });
     CleanStateBase.update = function update() {
         var _this = this;
-        if (!(this instanceof CleanState))
+        if (!(this instanceof exports.CleanState))
             throw new Error('CleanState.update must be called with `this` value set to a CleanState instance. Did you forget to use `.call` or `.apply`? Example: CleanState.update.call(cleanState);');
         /**
          * Linters complain about the use of a React hook within a loop because:
@@ -115,35 +97,6 @@ var CleanStateBase = /** @class */ (function () {
     };
     return CleanStateBase;
 }());
+exports.CleanStateBase = CleanStateBase;
 ;
-var CleanState = CleanStateBase;
-var useCleanState = function (_initialState) {
-    var props = [];
-    for (var _i = 1; _i < arguments.length; _i++) {
-        props[_i - 1] = arguments[_i];
-    }
-    var initialState = typeof _initialState === 'function'
-        ? (0, react_1.useMemo)(function () { return _initialState.apply(void 0, props); }, [])
-        : _initialState;
-    ;
-    var cleanState = (0, react_1.useRef)((0, react_1.useMemo)(function () {
-        return new CleanState(initialState);
-    }, [])).current;
-    CleanState.update.call(cleanState);
-    return cleanState;
-};
-exports.useCleanState = useCleanState;
-// Should be valid.
-// useCleanState((a: number) => ({b: a.toString(), q: 1}), 6);
-// useCleanState((a: boolean) => ({b: a.toString()}), true);
-// useCleanState((a: number, c?: string) => ({ b: `${a}` }), 6);
-// useCleanState((a: number, c?: string) => ({ b: `${a}` }), 6, 'word');
-// useCleanState((a: number, c: string) => ({ b: a + c, f: true }), 6, 'text');
-// useCleanState({ d: 5000 });
-// Should fail.
-// useCleanState((a: number) => ({b: a.toString(), q: 1}), 6, false);
-// useCleanState((a: boolean) => ({b: a.toString()}));
-// useCleanState((a: number, c?: string) => ({ b: `${a}` }), '6');
-// useCleanState((a: number, c?: string) => ({ b: `${a}` }));
-// useCleanState((a: number, c: string) => ({ b: a + c, f: true }), 6, 7);
-// useCleanState({ d: 5000 }, true);
+exports.CleanState = CleanStateBase;

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

@@ -0,0 +1,12 @@
+import { CleanStateBase } from './class';
+export type TStateData = object & {
+    [Key in keyof CleanStateBase<{}>]?: never;
+};
+/** @see https://github.com/cleanjsweb/neat-react#clean-state */
+export type TCleanState<TState extends TStateData> = (CleanStateBase<TState> & Omit<TState, keyof CleanStateBase<{}>>);
+export type ExtractCleanStateData<YourCleanState extends CleanStateBase<{}>> = Omit<YourCleanState, keyof CleanStateBase<{}>>;
+type StateInitFunction = (...args: any[]) => object;
+type StateInit = object | StateInitFunction;
+export type TInitialState<Initializer extends StateInit> = Initializer extends (...args: any[]) => (infer TState extends object) ? TState : Initializer;
+export type TUseCleanState = <TInit extends StateInit>(_initialState: TInit, ...props: TInit extends (...args: infer TProps extends any[]) => (infer TState extends object) ? TProps : []) => TCleanState<TInitialState<TInit>>;
+export {};

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

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

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

@@ -0,0 +1,6 @@
+import { TUseCleanState } from './hook-types';
+/**
+ * Creates a state object, which includes the provided values, and helper methods for
+ * updating those values and automatically rerendering your component's UI accordingly.
+ */
+export declare const useCleanState: TUseCleanState;

package/build/base/state/hooks.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCleanState = void 0;
+var react_1 = require("react");
+var class_1 = require("./class");
+/**
+ * Creates a state object, which includes the provided values, and helper methods for
+ * updating those values and automatically rerendering your component's UI accordingly.
+ */
+var useCleanState = function (_initialState) {
+    var props = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        props[_i - 1] = arguments[_i];
+    }
+    var initialState = typeof _initialState === 'function'
+        ? (0, react_1.useMemo)(function () { return _initialState.apply(void 0, props); }, [])
+        : _initialState;
+    ;
+    var cleanState = (0, react_1.useRef)((0, react_1.useMemo)(function () {
+        return new class_1.CleanState(initialState);
+    }, [])).current;
+    class_1.CleanState.update.call(cleanState);
+    return cleanState;
+};
+exports.useCleanState = useCleanState;
+// Should be valid.
+// useCleanState((a: number) => ({b: a.toString(), q: 1}), 6);
+// useCleanState((a: boolean) => ({b: a.toString()}), true);
+// useCleanState((a: number, c?: string) => ({ b: `${a}` }), 6);
+// useCleanState((a: number, c?: string) => ({ b: `${a}` }), 6, 'word');
+// useCleanState((a: number, c: string) => ({ b: a + c, f: true }), 6, 'text');
+// useCleanState({ d: 5000 });
+// Should fail.
+// useCleanState((a: number) => ({b: a.toString(), q: 1}), 6, false);
+// useCleanState((a: boolean) => ({b: a.toString()}));
+// useCleanState((a: number, c?: string) => ({ b: `${a}` }), '6');
+// useCleanState((a: number, c?: string) => ({ b: `${a}` }));
+// useCleanState((a: number, c: string) => ({ b: a + c, f: true }), 6, 7);
+// useCleanState({ d: 5000 }, true);

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

@@ -0,0 +1,4 @@
+import '../../globals';
+export { CleanState } from './class';
+export { useCleanState } from './hooks';
+export type { TCleanState, TStateData, ExtractCleanStateData } from './hook-types';

package/build/base/state/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCleanState = exports.CleanState = void 0;
+require("../../globals");
+var class_1 = require("./class");
+Object.defineProperty(exports, "CleanState", { enumerable: true, get: function () { return class_1.CleanState; } });
+var hooks_1 = require("./hooks");
+Object.defineProperty(exports, "useCleanState", { enumerable: true, get: function () { return hooks_1.useCleanState; } });

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

@@ -0,0 +1,83 @@
+import type { Extractor } from './types/extractor';
+import { ComponentInstance } from '../instance';
+/**
+ * A superset of {@link ComponentInstance} that allows defining your
+ * component's JSX template directly inside the class.
+ *
+ * This is designed to closely resemble the old {@link React.Component} class,
+ * making it easier to migrate older class components to the newer hooks-based system
+ * with little to no changes to their existing semantics/implementation.
+ */
+export declare class ClassComponent<TProps extends object = WeakEmptyObject> extends ComponentInstance<TProps> {
+    /**
+     * Analogous to {@link React.Component.render}. A function that returns
+     * your component's JSX template.
+     *
+     * You should place most logic that would usually go here
+     * in {@link ComponentInstance.beforeRender | `beforeRender`} instead.
+     * This helps to separate concerns and keep the template itself clean.
+     *
+     * ******
+     *
+     * Ideally the template method should only be concerned with defining the HTML/JSX structure of
+     * your component's UI. This may include destructuring nested instance members
+     * into more easily accessible local variables, or some simple transformation of data from props/state
+     * into a more appropriate format for display.
+     *
+     * ******
+     *
+     * @example <caption>Using a template function that returns JSX.</caption>
+     *
+     * ```tsx
+     * template = () => {
+     *     const { title } = this.props;
+     *
+     *     return (
+     *         <h1>
+     *             {this.props.title}
+     *         </h1>
+     *     );
+     * }
+     * ```
+     */
+    template: (context: this['templateContext']) => JSX.Element | null;
+    /**
+     * Manually trigger a rerender of your component.
+     * You should rarely ever need this. But if you are migrating
+     * an older React.Component class, this should provide similar functionality
+     * to the {@link React.Component.forceUpdate | `forceUpdate`} method provided there.
+     *
+     * Note that the callback argument is currently not supported.
+     */
+    readonly forceUpdate: VoidFunction;
+    /*************************************
+     *   Function Component Extractor    *
+    **************************************/
+    /**
+     * Extract a Function Component (FC) which can be used to render
+     * your ClassComponent just like any other React component.
+     *
+     * Each JSX reference to the returned component will render with
+     * a separate instance of your class.
+     *
+     * So you only need to call `YourClassComponent.FC()` once, then use the returned
+     * function component as many times as you need.
+     *
+     * It is recommended to store this returned value as a static member of
+     * your ClassComponent. While this value may be given any name, the name
+     * RC (for "React Component") is the recommended convention.
+     *
+     * @example <caption>Calling FC in your ClassComponent</caption>
+     * class Button extends ClassComponent {
+     *     static readonly RC = this.FC();
+     *     // Because of the static keyword, `this` here refers to the class itself, same as calling `Button.FC()`.
+     * }
+     *
+     * // Render with `<Button.RC />`, or export RC to use the component in other files.
+     * export default Button.RC;
+     */
+    static readonly extract: Extractor;
+    /** @see {@link ClassComponent.extract} */
+    static readonly FC: Extractor;
+}
+export { ClassComponent as Component };

package/build/classy/class/index.js

@@ -0,0 +1,149 @@
+"use strict";
+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 __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Component = exports.ClassComponent = void 0;
+var react_1 = require("react");
+var instance_1 = require("../instance");
+var function_name_1 = require("./utils/function-name");
+var rerender_1 = require("./utils/rerender");
+/**
+ * A superset of {@link ComponentInstance} that allows defining your
+ * component's JSX template directly inside the class.
+ *
+ * This is designed to closely resemble the old {@link React.Component} class,
+ * making it easier to migrate older class components to the newer hooks-based system
+ * with little to no changes to their existing semantics/implementation.
+ */
+var ClassComponent = /** @class */ (function (_super) {
+    __extends(ClassComponent, _super);
+    function ClassComponent() {
+        var _this = _super !== null && _super.apply(this, arguments) || this;
+        /**
+         * Analogous to {@link React.Component.render}. A function that returns
+         * your component's JSX template.
+         *
+         * You should place most logic that would usually go here
+         * in {@link ComponentInstance.beforeRender | `beforeRender`} instead.
+         * This helps to separate concerns and keep the template itself clean.
+         *
+         * ******
+         *
+         * Ideally the template method should only be concerned with defining the HTML/JSX structure of
+         * your component's UI. This may include destructuring nested instance members
+         * into more easily accessible local variables, or some simple transformation of data from props/state
+         * into a more appropriate format for display.
+         *
+         * ******
+         *
+         * @example <caption>Using a template function that returns JSX.</caption>
+         *
+         * ```tsx
+         * template = () => {
+         *     const { title } = this.props;
+         *
+         *     return (
+         *         <h1>
+         *             {this.props.title}
+         *         </h1>
+         *     );
+         * }
+         * ```
+         */
+        _this.template = function () { return null; };
+        return _this;
+    }
+    var _a;
+    _a = ClassComponent;
+    /*************************************
+     *   Function Component Extractor    *
+    **************************************/
+    /**
+     * Extract a Function Component (FC) which can be used to render
+     * your ClassComponent just like any other React component.
+     *
+     * Each JSX reference to the returned component will render with
+     * a separate instance of your class.
+     *
+     * So you only need to call `YourClassComponent.FC()` once, then use the returned
+     * function component as many times as you need.
+     *
+     * It is recommended to store this returned value as a static member of
+     * your ClassComponent. While this value may be given any name, the name
+     * RC (for "React Component") is the recommended convention.
+     *
+     * @example <caption>Calling FC in your ClassComponent</caption>
+     * class Button extends ClassComponent {
+     *     static readonly RC = this.FC();
+     *     // Because of the static keyword, `this` here refers to the class itself, same as calling `Button.FC()`.
+     * }
+     *
+     * // Render with `<Button.RC />`, or export RC to use the component in other files.
+     * export default Button.RC;
+     */
+    ClassComponent.extract = function FC(_Component) {
+        var Component = _Component !== null && _Component !== void 0 ? _Component : this;
+        var isClassComponentType = Component.prototype instanceof _a;
+        if (!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()`).');
+        /*************************************
+         *    Begin Function Component       *
+        **************************************/
+        /** A class-based React function component created with (@cleanweb/react).{@link ClassComponent} */
+        var Wrapper = function (props) {
+            var instance = (0, instance_1.useInstance)(Component, props);
+            var template = instance.template, templateContext = instance.templateContext;
+            var _forceUpdate;
+            // @ts-expect-error (Cannot assign to 'forceUpdate' because it is a read-only property.ts(2540))
+            instance.forceUpdate = (_forceUpdate = (0, rerender_1.useRerender)() // Moved this to separate line to allow TS errors. Use proxy local variable to regain some type checking for the assignment to `instance.forceUpdate`.
+            );
+            // Add calling component name to template function name in stack traces.
+            (0, react_1.useMemo)(function () {
+                (0, function_name_1.setFunctionName)(template, "".concat(Component.name, ".template"));
+            }, [template]);
+            return template(templateContext);
+        };
+        /**************************************
+        *     End Function Component          *
+        **************************************/
+        (0, function_name_1.setFunctionName)(Wrapper, "$".concat(Component.name, "$"));
+        return Wrapper;
+    };
+    /** @see {@link ClassComponent.extract} */
+    ClassComponent.FC = _a.extract;
+    return ClassComponent;
+}(instance_1.ComponentInstance));
+exports.ClassComponent = ClassComponent;
+exports.Component = ClassComponent;
+/**/
+testing: {
+    var a = { b: '' };
+    var MyComponentLogic = /** @class */ (function (_super) {
+        __extends(MyComponentLogic, _super);
+        function MyComponentLogic() {
+            var _this = _super !== null && _super.apply(this, arguments) || this;
+            _this.getInitialState = function () { return ({ a: '' }); };
+            // a = () => this.hooks.a = '';
+            _this.useHooks = function () {
+                _this.state.a;
+            };
+            return _this;
+        }
+        return MyComponentLogic;
+    }(ClassComponent));
+    ;
+    var Template = MyComponentLogic.FC();
+} /**/

package/build/classy/class/types/extractor.d.ts

@@ -0,0 +1,5 @@
+import type { VoidFunctionComponent } from 'react';
+import type { ClassComponent } from '..';
+type BaseCCConstructor = typeof ClassComponent<object>;
+export type Extractor = <TComponentClass extends BaseCCConstructor>(this: TComponentClass, Component?: TComponentClass) => VoidFunctionComponent<InstanceType<TComponentClass>['props']>;
+export {};

package/build/classy/class/types/extractor.js

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

package/build/classy/class/utils/function-name.d.ts

@@ -0,0 +1,2 @@
+/** Provide more useful stack traces for otherwise non-specific function names. */
+export declare const setFunctionName: (func: FunctionType, newName: string) => void;

package/build/classy/class/utils/function-name.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setFunctionName = void 0;
+/** 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);
+    }
+};
+exports.setFunctionName = setFunctionName;

package/build/classy/class/utils/rerender.d.ts

@@ -0,0 +1 @@
+export declare const useRerender: () => () => void;

package/build/classy/class/utils/rerender.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRerender = void 0;
+var mount_state_1 = require("../../../helpers/mount-state");
+var react_1 = require("react");
+var useRerender = function () {
+    var isMounted = (0, mount_state_1.useMountState)();
+    // Skip the value, we don't need it. Grab just the setter function.
+    var _a = (0, react_1.useState)(Date.now()), _forceRerender = _a[1];
+    var rerender = function () {
+        if (isMounted()) {
+            _forceRerender(Date.now());
+            return;
+        }
+        setTimeout(function () {
+            if (!isMounted())
+                return;
+            _forceRerender(Date.now());
+        }, 1000);
+    };
+    return rerender;
+};
+exports.useRerender = useRerender;

package/build/classy/class/utils/use-component/index.d.ts

@@ -0,0 +1,6 @@
+import type { ClassComponentHookWrapper } from './types';
+/**
+ * A component you can use to consume hooks
+ * in a {@link Component | React.Component} class component.
+ */
+export declare const Use: ClassComponentHookWrapper;

package/build/classy/class/utils/use-component/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Use = void 0;
+var react_1 = require("react");
+/**
+ * A component you can use to consume hooks
+ * in a {@link Component | React.Component} class component.
+ */
+var Use = function (params) {
+    var useGenericHook = params.hook, argumentsList = params.argumentsList, onUpdate = params.onUpdate;
+    var output = useGenericHook.apply(void 0, argumentsList);
+    (0, react_1.useEffect)(function () {
+        onUpdate(output);
+    }, [output]);
+    return null;
+};
+exports.Use = Use;

package/build/classy/class/utils/use-component/types.d.ts

@@ -0,0 +1,22 @@
+interface HookWrapperProps<THookFunction extends AnyFunction> {
+    /**
+     * The React hook you which to consume.
+     * Render a separate instance of the `<Use />` component for each hook.
+     * You can also create a custom hook that combines multiple hooks,
+     * then use that wrapper hook with a single `<Use />` instance.
+     */
+    hook: THookFunction;
+    /**
+     * An array containing the list of arguments
+     * to be passed to your hook, in the right order.
+     */
+    argumentsList: Parameters<THookFunction>;
+    /**
+     * A callback that will be called with whatever value your hook returns.
+     * Use this to update your component's state with the value.
+     * This will allow your component to rerender whenever the hook returns a new value.
+     */
+    onUpdate: (output: ReturnType<THookFunction>) => void;
+}
+export type ClassComponentHookWrapper = <Hook extends AnyFunction>(props: HookWrapperProps<Hook>) => null;
+export {};

package/build/classy/class/utils/use-component/types.js

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

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

@@ -0,0 +1,64 @@
+import type { UseInstance } from './types/hook';
+import { ComponentLogic } from '../../classy/logic';
+type AsyncAllowedEffectCallback = () => Awaitable<IVoidFunction>;
+/** An empty function. It returns (void) without performing any operations. */
+export declare const noOp: () => void;
+/**
+ * A superset of {@link ComponentLogic} that adds support for lifecycle methods.
+ * This provides a declarative API for working with your React function component's lifecycle,
+ * a simpler alternative to the imperative approach with `useEffect` and/or `useMemo`.
+ *
+ * @see https://github.com/cleanjsweb/neat-react#lifecycle-useinstance
+ */
+export declare class ComponentInstance<TProps extends object = {}> extends ComponentLogic<TProps> {
+    /**
+     * Runs only _before_ first render,
+     * i.e before the component instance is mounted.
+     *
+     * It is ignored on subsequent rerenders.
+     *
+     * PS: You can conditionally update state from here, but with certain caveats.
+     * {@link https://react.dev/reference/react/useState#storing-information-from-previous-renders | See the React docs for more details}.
+     */
+    beforeMount: IVoidFunction;
+    /**
+     * Runs only **_after_** first render, i.e after the component instance is mounted.
+     * It is ignored on subsequent rerenders.
+     *
+     * 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.
+     *
+     * Uses `useEffect()` under the hood.
+     */
+    onMount: AsyncAllowedEffectCallback;
+    private _templateContext;
+    get templateContext(): ReturnType<this["beforeRender"]>;
+    /**
+     * Runs _before_ every render cycle, including the first.
+     * Useful for logic that is involved in determining what to render.
+     *
+     * PS: You can conditionally update state from here, but with certain caveats.
+     * {@link https://react.dev/reference/react/useState#storing-information-from-previous-renders | See the React docs for more details}.
+     */
+    beforeRender: () => object | void;
+    /**
+     * 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.
+     *
+     * Uses `useEffect()` under the hood.
+     *
+     * Returns a cleanup function.
+     */
+    onRender: AsyncAllowedEffectCallback;
+    /**
+     * Runs when the component is unmounted.
+     * It is called _after_ the cleanup function returned by onMount.
+     */
+    cleanUp: IVoidFunction;
+}
+export declare const useInstance: UseInstance;
+export {};