@cleanweb/oore 1.0.0

package/build/base/state/class.js

@@ -0,0 +1,100 @@
+"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.CleanState = exports.CleanStateBase = void 0;
+var react_1 = require("react");
+/** @internal */
+var CleanStateBase = /** @class */ (function () {
+    function CleanStateBase(initialState) {
+        var _this = this;
+        this._values_ = {};
+        this._setters_ = {};
+        // readonly putMany = (newValues: Partial<TState>) => {
+        this.putMany = function (newValues) {
+            Object.entries(newValues).forEach(function (entry) {
+                var _a = entry, key = _a[0], value = _a[1];
+                _this.put[key](value);
+            });
+        };
+        this.reservedKeys = Object.keys(this);
+        /**
+         * The keys from the initial state object.
+         * By capturing and storing the value once, we ensure that any potential changes to the object,
+         * or irregularities in the order of keys returned by Object.keys,
+         * will not affect the order of subsequent useState calls.
+         * Only keys provided on the initial call will be recognized,
+         * since CleanState is instantiated only once with useMemo,
+         * and they will always be processed in a consistent order during rerenders.
+         */
+        this.valueKeys = Object.keys(initialState);
+        this._initialValues_ = __assign({}, initialState);
+        this.valueKeys.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."));
+            var self = _this;
+            Object.defineProperty(_this, key, {
+                get: function () {
+                    return self._values_[key];
+                },
+                set: function (value) {
+                    self._setters_[key](value);
+                },
+                enumerable: true,
+            });
+        });
+    }
+    Object.defineProperty(CleanStateBase.prototype, "put", {
+        get: function () {
+            return __assign({}, this._setters_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(CleanStateBase.prototype, "initialState", {
+        get: function () {
+            return __assign({}, this._initialValues_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    CleanStateBase.update = function update() {
+        var _this = this;
+        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:
+         * > 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 = react_1.useState;
+        this.valueKeys.forEach(function (key) {
+            var _a;
+            // @todo Make state updates accessible immediately. Use state.staged to access the scheduled updates.
+            var setter;
+            _a = retrieveState(_this.initialState[key]), _this._values_[key] = _a[0], setter = _a[1];
+            _this._setters_[key] = (function (valueOrCallback) {
+                // this._staged_[key] = value;
+                setter(valueOrCallback);
+            });
+        });
+    };
+    return CleanStateBase;
+}());
+exports.CleanStateBase = CleanStateBase;
+;
+/** @internal */
+exports.CleanState = (CleanStateBase);

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

@@ -0,0 +1,32 @@
+import { CleanStateBase } from './class';
+/**
+ * Base type for an `initialState` object.
+ * It is a regular object type, with some reserved keys excluded.
+ */
+export type TStateData = object & {
+    [Key in keyof CleanStateBase<{}>]?: never;
+};
+/**
+ * Describes a `CleanState` object instantiated with an `initialState`
+ * object of type `TState`.
+ *
+ * @typeParam TState - The type of your `initialState` object.
+ */
+export type TCleanState<TState extends TStateData> = (CleanStateBase<TState> & Omit<TState, keyof CleanStateBase<{}>>);
+/**
+ * Takes a `TCleanState` type and returns the `initialState` type
+ * associated with the provided `TCleanState`.
+ *
+ * This is useful to isolate the type of your actual state data without
+ * any of the reserved keys provided by the Clean State utility.
+ */
+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;
+/**
+ * @typeParam TInit - An initial state object, or a function that
+ * returns the initial state object.
+ */
+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,12 @@
+import { TUseCleanState } from './hook-types';
+/**
+ * Creates a state object, which includes the provided values,
+ * as well as helper methods for updating those values and automatically
+ * rerendering your component's UI to reflect the updates.
+ *
+ * Uses {@link React.useState} under the hood, with a separate call
+ * to `useState` for each top-level key in the provided object.
+ *
+ * Discussion: [When to `useCleanState`](https://cleanjsweb.github.io/neat-react/documents/Clean_State.html).
+ */
+export declare const useCleanState: TUseCleanState;

package/build/base/state/hooks.js

@@ -0,0 +1,45 @@
+"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,
+ * as well as helper methods for updating those values and automatically
+ * rerendering your component's UI to reflect the updates.
+ *
+ * Uses {@link React.useState} under the hood, with a separate call
+ * to `useState` for each top-level key in the provided object.
+ *
+ * Discussion: [When to `useCleanState`](https://cleanjsweb.github.io/neat-react/documents/Clean_State.html).
+ */
+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,8 @@
+/**
+ * @module CleanState
+ */
+import '../../globals';
+export { CleanState } from './class';
+export { useCleanState } from './hooks';
+export type { TCleanState, TStateData, ExtractCleanStateData } from './hook-types';
+export * as MergedState from '../../base/merged-state';

package/build/base/state/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @module CleanState
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MergedState = 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; } });
+exports.MergedState = __importStar(require("../../base/merged-state"));

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

@@ -0,0 +1,115 @@
+import type { TPropsBase } from '../logic';
+import type { Extractor } from './types/extractor';
+import { ComponentInstance } from '../instance';
+/**
+ * @summary
+ * A modern class component for React that is fully compatible with
+ * React Hooks and all of React's latest features.
+ *
+ * It is a superset of {@link ComponentInstance} that allows defining your
+ * component's JSX template directly inside the class.
+ *
+ * @remarks
+ * In essence, this is a class wrapper around an underlying function component.
+ * It acts as syntactic sugar, allowing you to create a regular function
+ * component, while writing in an object-oriented format.
+ *
+ * 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 TPropsBase = null> extends ComponentInstance<TProps> {
+    /**
+     * Analogous to {@link React.Component.render}. A function that returns
+     * your component's JSX template.
+     *
+     * ******
+     *
+     * Ideally the template method should only be concerned with defining the HTML/JSX structure of
+     * your component's UI.
+     *
+     * If you need to transform some data for display,
+     * do so in [beforeRender]({@link ComponentInstance.beforeRender}),
+     * and return an object with transformed data that can be rendered directly.
+     *
+     * The returned object will be passed to your template method
+     * as a `context` object.
+     *
+     * ******
+     *
+     * @example Using a template function that returns JSX.
+     *
+     * ```tsx
+     * beforeRender = () => {
+     *     return {
+     *         title: `My Site | ${this.props.title}`,
+     *     };
+     * }
+     * template = (ctx) => {
+     *     return (
+     *         <h1>
+     *             {ctx.title}
+     *         </h1>
+     *         <p>{this.props.description}</p>
+     *     );
+     * }
+     * ```
+     */
+    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.extract()` (or `*.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 `extract` in your ClassComponent</caption>
+     * class Button extends ClassComponent {
+     *     static readonly RC = this.extract(); // or this.FC();
+     *     // Because of the static keyword, `this` here refers to the class itself, same as calling `Button.extract()`.
+     * }
+     *
+     * // 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 };
+/** /
+testing: {
+    const a: object = {b: ''};
+
+    type t = keyof typeof a;
+
+    class MyComponentLogic extends ClassComponent<{a: ''}> {
+        getInitialState = () => ({a: '' as const});
+        // a = () => this.hooks.a = '';
+
+        useHooks = () => {
+            this.state.a;
+        };
+    };
+
+    const Template = MyComponentLogic.FC();
+}/**/

package/build/classy/class/index.js

@@ -0,0 +1,161 @@
+"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("../../helpers/rerender");
+/**
+ * @summary
+ * A modern class component for React that is fully compatible with
+ * React Hooks and all of React's latest features.
+ *
+ * It is a superset of {@link ComponentInstance} that allows defining your
+ * component's JSX template directly inside the class.
+ *
+ * @remarks
+ * In essence, this is a class wrapper around an underlying function component.
+ * It acts as syntactic sugar, allowing you to create a regular function
+ * component, while writing in an object-oriented format.
+ *
+ * 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.
+         *
+         * ******
+         *
+         * Ideally the template method should only be concerned with defining the HTML/JSX structure of
+         * your component's UI.
+         *
+         * If you need to transform some data for display,
+         * do so in [beforeRender]({@link ComponentInstance.beforeRender}),
+         * and return an object with transformed data that can be rendered directly.
+         *
+         * The returned object will be passed to your template method
+         * as a `context` object.
+         *
+         * ******
+         *
+         * @example Using a template function that returns JSX.
+         *
+         * ```tsx
+         * beforeRender = () => {
+         *     return {
+         *         title: `My Site | ${this.props.title}`,
+         *     };
+         * }
+         * template = (ctx) => {
+         *     return (
+         *         <h1>
+         *             {ctx.title}
+         *         </h1>
+         *         <p>{this.props.description}</p>
+         *     );
+         * }
+         * ```
+         */
+        _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.extract()` (or `*.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 `extract` in your ClassComponent</caption>
+     * class Button extends ClassComponent {
+     *     static readonly RC = this.extract(); // or this.FC();
+     *     // Because of the static keyword, `this` here refers to the class itself, same as calling `Button.extract()`.
+     * }
+     *
+     * // 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, as an argument to FC(), a class that extends ClassComponent (e.g `export FC(MyComponent);`), or ensure FC() 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: {
+    const a: object = {b: ''};
+
+    type t = keyof typeof a;
+
+    class MyComponentLogic extends ClassComponent<{a: ''}> {
+        getInitialState = () => ({a: '' as const});
+        // a = () => this.hooks.a = '';
+
+        useHooks = () => {
+            this.state.a;
+        };
+    };
+
+    const 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/index.d.ts

@@ -0,0 +1,3 @@
+export * from './logic';
+export * from './instance';
+export * from './class';

package/build/classy/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("./logic"), exports);
+__exportStar(require("./instance"), exports);
+__exportStar(require("./class"), exports);