@cleanweb/react 1.1.1-beta.16 → 1.1.1-beta.17

package/build/base/methods.d.ts

@@ -1,4 +1,11 @@
 import type { TCleanState, TStateData } from './state';
+/**
+ * Base class for a class that holds methods intended for use in a function component.
+ * These methods will have access to the components state and props via
+ * `this.state` and `this.props` respectively.
+ *
+ * Call the {@link useMethods} hook inside your function component to instantiate the class.
+ */
 export declare class ComponentMethods<TProps extends object = {}, TState extends TStateData | null = null> {
     readonly props: TProps;
     state: TState extends TStateData ? TCleanState<TState> : null;
@@ -8,5 +15,11 @@ type UseMethods = {
     <Class extends typeof ComponentMethods<object, null>>(Methods: Class & Constructor<InstanceType<Class>>, props: InstanceType<Class>['props'], state?: null): InstanceType<Class>;
     <Class extends typeof ComponentMethods<HardEmptyObject, null>>(Methods: Class & Constructor<InstanceType<Class>>): InstanceType<Class>;
 };
+/**
+ * Returns an instance of the provided class,
+ * with the state and props arguments added as instance members.
+ *
+ * `state` must be an instance of `CleanState` created with {@link useCleanState}.
+ */
 declare const useMethods: UseMethods;
 export { useMethods };

package/build/base/methods.js

@@ -52,7 +52,15 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useMethods = exports.ComponentMethods = void 0;
+// Values
 var react_1 = require("react");
+/**
+ * Base class for a class that holds methods intended for use in a function component.
+ * These methods will have access to the components state and props via
+ * `this.state` and `this.props` respectively.
+ *
+ * Call the {@link useMethods} hook inside your function component to instantiate the class.
+ */
 var ComponentMethods = /** @class */ (function () {
     function ComponentMethods() {
     }
@@ -60,6 +68,12 @@ var ComponentMethods = /** @class */ (function () {
 }());
 exports.ComponentMethods = ComponentMethods;
 ;
+/**
+ * Returns an instance of the provided class,
+ * with the state and props arguments added as instance members.
+ *
+ * `state` must be an instance of `CleanState` created with {@link useCleanState}.
+ */
 var useMethods = function () {
     var args = [];
     for (var _i = 0; _i < arguments.length; _i++) {

package/build/base/state.d.ts

@@ -28,5 +28,9 @@ type StateInitFunction = (...args: any[]) => object;
 type StateInit = object | StateInitFunction;
 type TInitialState<Initializer extends StateInit> = Initializer extends (...args: any[]) => (infer TState extends object) ? TState : Initializer;
 type TUseCleanState = <TInit extends StateInit>(_initialState: TInit, ...props: TInit extends (...args: infer TProps extends any[]) => (infer TState extends object) ? TProps : []) => TCleanState<TInitialState<TInit>>;
+/**
+ * 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;
 export {};

package/build/base/state.js

@@ -118,6 +118,10 @@ var CleanStateBase = /** @class */ (function () {
 }());
 ;
 var CleanState = CleanStateBase;
+/**
+ * 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++) {

package/build/classy/class.d.ts

@@ -8,19 +8,108 @@ type ComponentClassParams = ConstructorParameters<typeof ClassComponent>;
 type o = object;
 export interface IComponentClass<Instance extends ClassComponent<o, o, THooksBase> = ClassComponent, Params extends ComponentClassParams = ComponentClassParams> extends IComponentInstanceClass<Instance, Params> {
 }
-type Extractor = <TComponent extends typeof ClassComponent<o, o, o>>(this: NonNullable<typeof _Component>, _Component?: TComponent & IComponentClass<InstanceType<TComponent>>) => VoidFunctionComponent<InstanceType<TComponent>['props']>;
+type Extractor = <TComponent extends typeof ClassComponent<o, o, THooksBase>>(this: NonNullable<typeof _Component>, _Component?: TComponent & IComponentClass<InstanceType<TComponent>>) => VoidFunctionComponent<InstanceType<TComponent>['props']>;
 type ReactTemplate = React.JSX.Element | null;
+/**
+ * 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 o = WeakEmptyObject, TState extends TStateData = WeakEmptyObject, THooks extends THooksBase = void> extends ComponentInstance<TProps, TState, THooks> {
+    /**
+     * @deprecated An older alternative to {@link template}.
+     *
+     * Using this will add a component boundary between your JSX template
+     * and the function component returned from ClassComponent.FC();
+     *
+     * This means that from React's perspective, your template won't "own" the state and props it consumes.
+     * This could lead to subtle unexpected changes in behaviour.
+     *
+     * In most cases, you should use {@link template} instead, as it allows your class component
+     * to function more predictably as a single unit.
+     */
     Render?: VoidFunctionComponent<{}>;
+    /**
+     * Your components JSX template. This a variable that should represent what you
+     * would normally return from a regular function component.
+     *
+     * Alternatively, it can be a function that returns the required JSX.
+     * The function form is useful if your template references many nested instance members
+     * and you would like to destructure them into more easily accessible local variables.
+     *
+     * Besides that, you should place all other logic in {@link ComponentInstance.beforeRender | `beforeRender`}
+     * in order to separate concerns and keep the template itself clean.
+     *
+     * @example <caption>Using a simple JSX template</caption>
+     * template = (
+     *     <h1>
+     *         {this.props.title}
+     *     </h1>
+     * );
+     *
+     * @example <caption>Using a template function that returns JSX.</caption>
+     * template = () => {
+     *     const { title } = this.props;
+     *
+     *     return (
+     *         <h1>
+     *             {this.props.title}
+     *         </h1>
+     *     );
+     * }
+     */
     template?: ReactTemplate | (() => ReactTemplate);
+    /**
+     * 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 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 which can be used to render
+     * your ClassComponent just like any other component.
+     *
+     * Each JSX reference to this 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.
+     */
     static readonly FC: Extractor;
 }
 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;
 }
 type ClassComponentHookWrapper = <Hook extends AnyFunction>(props: HookWrapperProps<Hook>) => null;
+/**
+ * A component you can use to consume hooks
+ * in a {@link Component | React.Component} class component.
+ */
 export declare const Use: ClassComponentHookWrapper;
 export {};

package/build/classy/class.js

@@ -43,16 +43,43 @@ var useRerender = function () {
 };
 exports.useRerender = useRerender;
 ;
+/**
+ * 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() {
         return _super !== null && _super.apply(this, arguments) || this;
     }
+    /*************************************
+     *   Function Component Extractor    *
+    **************************************/
+    // @todo Attempt using implicit `this` value to allow rendering <MyComponent.FC /> directly.
+    // const FC = (props) => { const self = useMemo(() => useInstance(this, props), {}); return self.template(); }
+    /**
+     * Extract a function component which can be used to render
+     * your ClassComponent just like any other component.
+     *
+     * Each JSX reference to this 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.
+     */
     ClassComponent.FC = function FC(_Component) {
         var Component = _Component !== null && _Component !== void 0 ? _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()`).');
+        /*************************************
+         *    Begin Function Component       *
+        **************************************/
+        /** A class-based React function component created with (@cleanweb/react).ClassComponent */
         var Wrapper = function (props) {
             var instance = (0, instance_1.useInstance)(Component, props);
             var Render = instance.Render, template = instance.template;
@@ -106,13 +133,19 @@ var ClassComponent = /** @class */ (function (_super) {
                 default: return template;
             }
         };
-        // Include calling component name in wrapper function name on stack traces.
+        /*************************************
+         *     End Function Component        *
+        **************************************/
         setFunctionName(Wrapper, "$".concat(Component.name, "$"));
         return Wrapper;
     };
     return ClassComponent;
 }(instance_1.ComponentInstance));
 exports.ClassComponent = ClassComponent;
+/**
+ * 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);
@@ -127,7 +160,11 @@ testing: {
     var MyComponentLogic = /** @class */ (function (_super) {
         __extends(MyComponentLogic, _super);
         function MyComponentLogic() {
-            return _super !== null && _super.apply(this, arguments) || this;
+            var _this = _super !== null && _super.apply(this, arguments) || this;
+            // a = () => this.hooks.a = '';
+            _this.useHooks = function () {
+            };
+            return _this;
         }
         MyComponentLogic.getInitialState = function () { return ({ a: '' }); };
         return MyComponentLogic;

package/build/classy/instance.d.ts

@@ -2,9 +2,13 @@ import type { TStateData } from '../base/state';
 import type { THooksBase, IComponentLogicClass } from './logic';
 import { ComponentLogic } from './logic';
 type AsyncAllowedEffectCallback = () => Awaitable<IVoidFunction>;
-type UseMountCallbacks = <TInstance extends ComponentInstance<any, any, any>>(instance: TInstance) => void;
-export declare const useMountCallbacks: UseMountCallbacks;
+/** An empty function. It returns (void) without performing any operations. */
 export declare const noOp: () => void;
+/**
+ * A superset of {@link ComponentLogic} that adds support for special 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`.
+ */
 export declare class ComponentInstance<TProps extends o = {}, TState extends TStateData = WeakEmptyObject, THooks extends THooksBase = void> extends ComponentLogic<TProps, TState, THooks> {
     /**
      * Runs only _before_ first render, i.e before the component instance is mounted.

package/build/classy/instance.js

@@ -15,7 +15,7 @@ var __extends = (this && this.__extends) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useInstance = exports.ComponentInstance = exports.noOp = exports.useMountCallbacks = void 0;
+exports.useInstance = exports.ComponentInstance = exports.noOp = void 0;
 var react_1 = require("react");
 var state_1 = require("../base/state");
 var logic_1 = require("./logic");
@@ -43,10 +43,15 @@ var useMountCallbacks = function (instance) {
         };
     }, []);
 };
-exports.useMountCallbacks = useMountCallbacks;
+/** An empty function. It returns (void) without performing any operations. */
 var noOp = function () { };
 exports.noOp = noOp;
 // @todo Use rollup. Insert globals.ts reference tag to all d.ts output files.
+/**
+ * A superset of {@link ComponentLogic} that adds support for special 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`.
+ */
 var ComponentInstance = /** @class */ (function (_super) {
     __extends(ComponentInstance, _super);
     function ComponentInstance() {
@@ -134,7 +139,7 @@ var useInstance = function () {
         '
      */
     // beforeMount, onMount, cleanUp.
-    (0, exports.useMountCallbacks)(instance);
+    useMountCallbacks(instance);
     // beforeRender.
     (_a = instance.beforeRender) === null || _a === void 0 ? void 0 : _a.call(instance);
     // onRender.

package/build/classy/logic.d.ts

@@ -3,11 +3,46 @@ export type HardEmpty = HardEmptyObject;
 export type WeakEmpty = WeakEmptyObject;
 export type THooksBase = o | void;
 type o = object;
-export declare class ComponentLogic<TProps extends object = {}, TState extends TStateData = WeakEmpty, THooks extends THooksBase = void> {
+/**
+ * Base class for a class that holds methods intended for use in a function component,
+ * as well as a static method for initializing state.
+ *
+ * These methods will have access to the components state and props via
+ * `this.state` and `this.props` respectively.
+ *
+ * The special {@link ComponentLogic.useHooks | useHooks} method allows you to consume
+ * React hooks within this class.
+ *
+ * Call the {@link useLogic} hook inside your function component to instantiate the class.
+ */
+export declare class ComponentLogic<
+/** Describe the values your component expects to be passed as props. */
+TProps extends object = {}, 
+/** An object type that descibes your component's state. */
+TState extends TStateData = WeakEmpty, 
+/** The object type returned by your component's {@link useHooks} method. */
+THooks extends THooksBase = void> {
     state: TCleanState<TState>;
     readonly props: TProps;
     readonly hooks: THooks extends object ? THooks : WeakEmptyObject;
+    /**
+     * Called before each instance of your component is mounted.
+     * It receives the initial `props` object and should return
+     * an object with the initial values for your component's state.
+     */
     static getInitialState: (p?: object) => object;
+    /**
+     * This allows you to seamlessly consume React hooks in
+     * your class component.
+     *
+     * It is called after state and props are updated on each render.
+     * Call any hooks (e.g `useEffect`) you which to consume inside this function.
+     *
+     * To expose any returned values from your hooks to the rest of your component,
+     * return an object that contains all the relevant values.
+     *
+     * This object will be accessible as `this.hooks` to the rest of your class.
+     */
     useHooks: THooks extends void ? undefined | (() => void | HardEmptyObject) : () => THooks;
 }
 type LogicClassParams = ConstructorParameters<typeof ComponentLogic>;

package/build/classy/logic.js

@@ -19,9 +19,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useLogic = exports.ComponentLogic = void 0;
 var react_1 = require("react");
 var state_1 = require("../base/state");
+/**
+ * Base class for a class that holds methods intended for use in a function component,
+ * as well as a static method for initializing state.
+ *
+ * These methods will have access to the components state and props via
+ * `this.state` and `this.props` respectively.
+ *
+ * The special {@link ComponentLogic.useHooks | useHooks} method allows you to consume
+ * React hooks within this class.
+ *
+ * Call the {@link useLogic} hook inside your function component to instantiate the class.
+ */
 var ComponentLogic = /** @class */ (function () {
     function ComponentLogic() {
     }
+    /**
+     * Called before each instance of your component is mounted.
+     * It receives the initial `props` object and should return
+     * an object with the initial values for your component's state.
+     */
     ComponentLogic.getInitialState = function (p) { return ({}); };
     return ComponentLogic;
 }());

package/package.json

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