@cleanweb/react 2.1.1-beta.3 → 2.1.2

package/README.md

@@ -55,7 +55,7 @@ const Button = (props) => {
 
 > **Note:** Each top-level key in your initial state object gets a separate call to `React.useState`, and `state.put[key]()` is a proxy for the setter function returned from `useState`. So using this hook is fundamentally the same as calling `useState` directly for each value. What `useCleanState` provides is a way to unify those values and a convenient API for updating them.
 
-[Read the `useCleanState` docs](https://cleanjsweb.github.io/neat-react) for more details.
+[Read the `useCleanState` API docs](https://cleanjsweb.github.io/neat-react/functions/API.useCleanState.html) for more details.
 
 ### Methods
 The `useMethods` hook lets you manage the closures that your component uses in a separate class, keeping the body of the component clean and easier to read. With `useMethods`, your functions are not recreated on every render. Yet, every method of your component is guaranteed to always have access to the latest props and state without the need for a dependencty array.
@@ -110,10 +110,14 @@ const Button = (props) => {
 }
 ```
 
-[Read the `useMethods` docs]() for more details.
+[Read the `useMethods` API docs](https://cleanjsweb.github.io/neat-react/functions/API.useMethods.html) for more details.
+
+<small>Discussion: [Reasoning behind `useMethods`](https://cleanjsweb.github.io/neat-react/documents/Methods_Hook.html).</small>
 
 ### Logic
-The `useLogic` hook is an expansion of `useMethods`, with the aim of being a more holistic solution. It combines the functionality of `useCleanState` and `useMethods`. In addition, it allows you to externalize _all_ of your component's logic, not just closures and state. Essentially, this means being able to call hooks from within the class, rather than having to do so within the component body.
+The `useLogic` hook is an expansion of [`useMethods`](#methods), with the aim of being a more holistic solution. It combines the functionality of [`useCleanState`](#clean-state) and [`useMethods`](#methods).
+
+In addition, it allows you to externalize _all_ of your component's logic, not just closures and state. Essentially, this means being able to call hooks from within the class, rather than having to do so within the component body.
 
 ```jsx
 class ButtonLogic {
@@ -164,10 +168,13 @@ const Button = (props) => {
 }
 ```
 
-[Read the `useLogic` docs]() for more details.
+[Read the `useLogic` docs](https://cleanjsweb.github.io/neat-react/documents/Logic_Hook.html).
+
 
 ### Lifecycle (`useInstance`)
-The `useInstance` hook provides a simple approach for working with your components lifecycle. It includes all the features of [`useLogic`](#logic), and adds special lifecycle methods. This gives you a declarative way to run certain code at specific stages of your component's life time. You will likely find this to be less error prone and much easier to reason about than the imperative approach of using React's hooks directly.
+The `useInstance` hook provides a simple approach for working with your component's lifecycle. It includes all the features of [`useLogic`](#logic), and adds special lifecycle methods.
+
+This gives you a declarative way to run certain code at specific stages of your component's life time. You will likely find this to be less error prone and much easier to reason about than the imperative approach of using React's hooks directly.
 
 ```jsx
 /** Button Component Class. */
@@ -250,7 +257,10 @@ const Button = (props) => {
 }
 ```
 
-[Read the `useInstance` docs]() for more details.
+[Read the `useInstance` API docs](https://cleanjsweb.github.io/neat-react/functions/API.useInstance.html) for more details.
+
+<small>For a lengthier discussion on the reasoning behind the `useInstance` hook, see the [`useInstance` discussion doc](https://cleanjsweb.github.io/neat-react/documents/Instance_Hook.html).
+
 
 ### Class Component
 With `useInstance`, pretty much every aspect of your component is now part of the class, except for the JSX template. The `ClassComponent` class takes that final step and provides a fully integrated class-based React component.
@@ -304,10 +314,13 @@ export default Button.RC;
 // Or render directly with `<Button.RC />`.
 ```
 
-Every class derived from the base `ClassComponent` is not itself a React component. Instead, it has a static `extract()` method (also aliased as `FC()` for "Function Component") which returns a function component that can be rendered like any other React component. Each instance of this function component mounted in the React tree creates it's own separate instance of your `ClassComponent` class. To make it easier to use the class component directly, you should create a static property that holds the function component returned by `extract`. The recommended convention is to use the name `RC` (for "React Component"). Such a class can then easily be rendered as JSX by writing `<MyComponent.RC />`.
+Every class derived from the base `ClassComponent` is not itself a React component. Instead, it has a static `extract()` method (also aliased as `FC()` for "Function Component") which returns a function component that can be rendered like any other React component. Each instance of this function component mounted in the React tree creates it's own separate instance of your `ClassComponent` class.
 
-[Read the `ClassComponent` docs]() for more details.
+To make it easier to use the class component directly, you should create a static property that holds the function component returned by `extract`. The recommended convention is to use the name `RC` (for "React Component"). Such a class can then easily be rendered as JSX by writing `<MyComponent.RC />`.
 
+[Read the `ClassComponent` API docs](https://cleanjsweb.github.io/neat-react/classes/API.ClassComponent.html) for more details.
+
+<small>For a discussion on how this works, and a comparison with React's older `React.Component` class, see the [`ClassComponent` discussion doc](https://cleanjsweb.github.io/neat-react/documents/Class_Component.html).</small>
 
 ### Other Exports
 
@@ -315,8 +328,6 @@ Every class derived from the base `ClassComponent` is not itself a React compone
 If you simply want to use hooks in your `React.Component` class without having to rewrite anything, this package also exports a `<Use>` component that helps you achieve this easily. Here's how to use it.
 
 ```jsx
-import { useGlobalStore } from '@/hooks/store';
-
 class Button extends React.Component {
 	syncGlobalStore = ([store, updateStore]) => {
 		if (this.state.userId !== store.userId) {

package/build/base/methods.d.ts

@@ -24,11 +24,9 @@ type UseMethods = {
     <Class extends typeof ComponentMethods<NeverObject, null>>(Methods: Class & Constructor<InstanceType<Class>>): InstanceType<Class>;
 };
 /**
- * @summary
  * Returns an instance of the provided class,
  * with the state and props arguments added as instance members.
  *
- * @remarks
  * `state` should be an instance of `CleanState` created with {@link useCleanState}.
  */
 declare const useMethods: UseMethods;

package/build/base/methods.js

@@ -36,11 +36,9 @@ var ComponentMethods = /** @class */ (function () {
 exports.ComponentMethods = ComponentMethods;
 ;
 /**
- * @summary
  * Returns an instance of the provided class,
  * with the state and props arguments added as instance members.
  *
- * @remarks
  * `state` should be an instance of `CleanState` created with {@link useCleanState}.
  */
 var useMethods = function () {
@@ -71,8 +69,8 @@ var useMethods = function () {
                 'Note that this mechanism only works in the `development` environment during HMR.',
                 'In production, the class argument will be ignored after the first render.\n\n',
                 'If this wasn\'t an HMR update, you should refactor your code to make sure',
-                'all clean-react hooks receive the same class object on every render.'
-            ].join());
+                'all clean-react hooks receive the same class argument on every render.'
+            ].join(' '));
             var oldInstance = instanceRef.current;
             var hmrPreserveKeys = __spreadArray(__spreadArray([], latestInstance._hmrPreserveKeys, true), [
                 'state', 'props',

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

@@ -1,12 +1,12 @@
 import { TUseCleanState } from './hook-types';
 /**
- * @summary
  * 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 said updates.
  *
- * @remarks
- * Uses {@link React.useState} under the hook, with a separate call
+ * 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 use `cleanState`](https://cleanjsweb.github.io/neat-react/documents/Clean_State.html).
  */
 export declare const useCleanState: TUseCleanState;

package/build/base/state/hooks.js

@@ -4,14 +4,14 @@ exports.useCleanState = void 0;
 var react_1 = require("react");
 var class_1 = require("./class");
 /**
- * @summary
  * 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 said updates.
  *
- * @remarks
- * Uses {@link React.useState} under the hook, with a separate call
+ * 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 use `cleanState`](https://cleanjsweb.github.io/neat-react/documents/Clean_State.html).
  */
 var useCleanState = function (_initialState) {
     var props = [];

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

@@ -23,29 +23,34 @@ export declare class ClassComponent<TProps extends TPropsBase = null> extends Co
      * 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.
+     * 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 <caption>Using a template function that returns JSX.</caption>
+     * @example Using a template function that returns JSX.
      *
      * ```tsx
-     * template = () => {
-     *     const { title } = this.props;
-     *
+     * beforeRender = () => {
+     *     return {
+     *         title: `My Site | ${this.props.title}`,
+     *     };
+     * }
+     * template = (ctx) => {
      *     return (
      *         <h1>
-     *             {this.props.title}
+     *             {ctx.title}
      *         </h1>
+     *         <p>{this.props.description}</p>
      *     );
      * }
      * ```
@@ -91,7 +96,6 @@ export declare class ClassComponent<TProps extends TPropsBase = null> extends Co
     static readonly FC: Extractor;
 }
 export { ClassComponent as Component };
-export { Use } from '../../helpers/use-component';
 /** /
 testing: {
     const a: object = {b: ''};

package/build/classy/class/index.js

@@ -15,7 +15,7 @@ var __extends = (this && this.__extends) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Use = exports.Component = exports.ClassComponent = void 0;
+exports.Component = exports.ClassComponent = void 0;
 var react_1 = require("react");
 var instance_1 = require("../instance");
 var function_name_1 = require("./utils/function-name");
@@ -45,29 +45,34 @@ var ClassComponent = /** @class */ (function (_super) {
          * 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.
+         * 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 <caption>Using a template function that returns JSX.</caption>
+         * @example Using a template function that returns JSX.
          *
          * ```tsx
-         * template = () => {
-         *     const { title } = this.props;
-         *
+         * beforeRender = () => {
+         *     return {
+         *         title: `My Site | ${this.props.title}`,
+         *     };
+         * }
+         * template = (ctx) => {
          *     return (
          *         <h1>
-         *             {this.props.title}
+         *             {ctx.title}
          *         </h1>
+         *         <p>{this.props.description}</p>
          *     );
          * }
          * ```
@@ -137,8 +142,6 @@ var ClassComponent = /** @class */ (function (_super) {
 }(instance_1.ComponentInstance));
 exports.ClassComponent = ClassComponent;
 exports.Component = ClassComponent;
-var use_component_1 = require("../../helpers/use-component");
-Object.defineProperty(exports, "Use", { enumerable: true, get: function () { return use_component_1.Use; } });
 /** /
 testing: {
     const a: object = {b: ''};

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

@@ -31,12 +31,50 @@ export declare class ComponentInstance<TProps extends TPropsBase = null> extends
      * Uses `useEffect()` under the hood.
      */
     onMount: AsyncAllowedEffectCallback;
+    /** @see {@link templateContext} */
     private _templateContext;
+    /**
+     * Holds the object returned by {@link beforeRender}.
+     *
+     * This is useful when you need to render some state or props
+     * in a transformed format. Put the transformation logic
+     * in {@link beforeRender} to the keep the function component
+     * template clean.
+     *
+     * ******
+     *
+     * @example Using templateContext.
+     *
+     * ```tsx
+     * class MyComponentLogic extends ComponentInstance {
+     *     beforeRender = () => {
+     *         const title = `My Site | ${this.props.title}`;
+     *         return { title };
+     *     }
+     * }
+     * const MyComponent = (props) => {
+     *     const self = useInstance(MyComponentLogic, props);
+     *     const { template: ctx, state } = self;
+     *
+     *     return (
+     *         <h1>
+     *             {ctx.title}
+     *         </h1>
+     *         <p>{props.description}</p>
+     *     );
+     * }
+     * ```
+     */
     get templateContext(): ReturnType<this["beforeRender"]>;
     /**
      * Runs _before_ every render cycle, including the first.
      * Useful for logic that is involved in determining what to render.
      *
+     * This is the ideal place to transform data for display.
+     * Return the transformed data in an object, and the object will
+     * availble as [`self.templateContext`]({@link templateContext})
+     * for use in your JSX template.
+     *
      * 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}.
      */
@@ -59,7 +97,6 @@ export declare class ComponentInstance<TProps extends TPropsBase = null> extends
     cleanUp: IVoidFunction;
 }
 /**
- * @summary
  * Enables full separation of concerns between a React components template
  * and all of the logic that drives it.
  *
@@ -70,7 +107,6 @@ export declare class ComponentInstance<TProps extends TPropsBase = null> extends
  * can be externalized from the function component itself,
  * and defined in a separate class.
  *
- * @remarks
  * The provided class should be a subclass of {@link ComponentInstance}.
  *
  * @privateRemarks

package/build/classy/instance/index.js

@@ -57,6 +57,11 @@ var ComponentInstance = /** @class */ (function (_super) {
          * Runs _before_ every render cycle, including the first.
          * Useful for logic that is involved in determining what to render.
          *
+         * This is the ideal place to transform data for display.
+         * Return the transformed data in an object, and the object will
+         * availble as [`self.templateContext`]({@link templateContext})
+         * for use in your JSX template.
+         *
          * 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}.
          */
@@ -80,6 +85,38 @@ var ComponentInstance = /** @class */ (function (_super) {
         return _this;
     }
     Object.defineProperty(ComponentInstance.prototype, "templateContext", {
+        /**
+         * Holds the object returned by {@link beforeRender}.
+         *
+         * This is useful when you need to render some state or props
+         * in a transformed format. Put the transformation logic
+         * in {@link beforeRender} to the keep the function component
+         * template clean.
+         *
+         * ******
+         *
+         * @example Using templateContext.
+         *
+         * ```tsx
+         * class MyComponentLogic extends ComponentInstance {
+         *     beforeRender = () => {
+         *         const title = `My Site | ${this.props.title}`;
+         *         return { title };
+         *     }
+         * }
+         * const MyComponent = (props) => {
+         *     const self = useInstance(MyComponentLogic, props);
+         *     const { template: ctx, state } = self;
+         *
+         *     return (
+         *         <h1>
+         *             {ctx.title}
+         *         </h1>
+         *         <p>{props.description}</p>
+         *     );
+         * }
+         * ```
+         */
         get: function () {
             return this._templateContext;
         },
@@ -91,7 +128,6 @@ var ComponentInstance = /** @class */ (function (_super) {
 exports.ComponentInstance = ComponentInstance;
 ;
 /**
- * @summary
  * Enables full separation of concerns between a React components template
  * and all of the logic that drives it.
  *
@@ -102,7 +138,6 @@ exports.ComponentInstance = ComponentInstance;
  * can be externalized from the function component itself,
  * and defined in a separate class.
  *
- * @remarks
  * The provided class should be a subclass of {@link ComponentInstance}.
  *
  * @privateRemarks

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

@@ -66,6 +66,8 @@ export declare class ComponentLogic<TProps extends TPropsBase = null> {
  * encapsulates hook calls with the special {@link ComponentLogic.useHooks | `useHooks`} method.
  *
  * The class argument must be a subclass of {@link ComponentLogic}.
+ *
+ * @see https://cleanjsweb.github.io/neat-react/functions/API.useLogic.html
  */
 export declare const useLogic: UseLogic;
 /** /

package/build/classy/logic/index.js

@@ -57,6 +57,8 @@ exports.ComponentLogic = ComponentLogic;
  * encapsulates hook calls with the special {@link ComponentLogic.useHooks | `useHooks`} method.
  *
  * The class argument must be a subclass of {@link ComponentLogic}.
+ *
+ * @see https://cleanjsweb.github.io/neat-react/functions/API.useLogic.html
  */
 var useLogic = function () {
     var _a, _b;
@@ -79,8 +81,8 @@ var useLogic = function () {
                 'Note that this mechanism only works in the `development` environment during HMR.',
                 'In production, the class argument will be ignored after the first render.\n\n',
                 'If this wasn\'t an HMR update, you should refactor your code to make sure',
-                'all clean-react hooks receive the same class object on every render.'
-            ].join());
+                'all clean-react hooks receive the same class argument on every render.'
+            ].join(' '));
             var oldInstance_1 = instanceRef.current;
             var hmrPreserveKeys = __spreadArray(__spreadArray([], latestInstance._hmrPreserveKeys, true), [
                 'state', 'props', 'hooks',

package/build/index.d.ts

@@ -1,3 +1,4 @@
 export * from './classy';
 export * from './base';
 export * from './helpers';
+export type { EmptyObject, NeverObject };

package/build/index.js

@@ -17,11 +17,3 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./classy"), exports);
 __exportStar(require("./base"), exports);
 __exportStar(require("./helpers"), exports);
-/*
-withFetchApi(baseUrl); To mimic axios.get and axios.post type calls.
-@cleanweb/mem-store - Release global-store package here.
-Use mem-store to cache requests in withFetchApi(); Use md5 hashed url+body as key.
-@todo Add simple persistence layer with indexed db.
-@cleanweb/subscribable - To publish changes in the data to subscribers.
-@cleanweb/reactive-data - To combine all 4.
-*/

package/package.json

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