@cleanweb/oore 1.0.6 → 1.1.0

package/build/base/merged-state.d.ts

@@ -14,7 +14,7 @@ declare class MergedState<TState extends object> {
 }
 /**
  * Similar to {@link useCleanState},
- * but uses a single `useState` call for the entire object.
+ * but uses a single `useState` call for the entire state object.
  */
 export declare const useMergedState: <TState extends object>(initialState: TState) => MergedState<TState> & TState;
 export {};

package/build/base/merged-state.js

@@ -72,7 +72,7 @@ var MergedState = /** @class */ (function () {
 }());
 /**
  * Similar to {@link useCleanState},
- * but uses a single `useState` call for the entire object.
+ * but uses a single `useState` call for the entire state object.
  */
 var useMergedState = function (initialState) {
     var cleanState = (0, react_1.useRef)((0, react_1.useMemo)(function () {

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

@@ -1,4 +1,4 @@
-import { ICleanStateClass, ICleanStateConstructor, PutManyPayload, PutState } from './class-types';
+import type { ICleanStateClass, ICleanStateConstructor, PutManyPayload, PutState } from './class-types';
 /** @internal */
 export declare class CleanStateBase<TState extends Record<string, any>> {
     readonly reservedKeys: string[];
@@ -10,6 +10,59 @@ export declare class CleanStateBase<TState extends Record<string, any>> {
     static update: <TState_1 extends object>(this: CleanStateBase<TState_1>) => void;
     get put(): PutState<TState>;
     get initialState(): TState;
+    /**
+     * Accepts an object to be merged into the current state object,
+     * updating the values of specified keys to their specified values.
+     *
+     * All specified keys must be present on the initial state object.
+     * This is a requirement of React hooks, as the number of calls to
+     * useState must be the same throughout a component's lifetime.
+     *
+     * To dynamically add new keys to your state object, use a nested object,
+     * or use the {@link useMergedState | `useMergedState`} hook also exported by this library.
+     *
+     * When called from inside a component class, the type of the object passed
+     * must be explicitly specified with a type assertion.
+     * This is because the component classes use the dynamic `this` type to define
+     * the type of their state property.
+     *
+     * Use the `StateFragment` type, also aliased as `SF`, to define this type assertion.
+     * The assertion is not needed when calling putMany from outside the class.
+     *
+     * @example <caption>Using `putMany`</caption>
+     * import type { SF } from '@cleanweb/oore/base';
+     * import { ComponentLogic } from '@cleanweb/oore';
+     *
+     * class InputCL extends ComponentLogic<TProps> {
+     *     getInitialState(props: TProps): TState => ({
+     *         disabled: true,
+     *     });
+     *
+     *     enableInput = () => {
+     *         this.state.putMany({
+     *             disabled: false,
+     *         } as SF<this>); // Type assertion required inside class.
+     *     };
+     * }
+     *
+     * export const Input = (props: TProps) => {
+     *     const self = useLogic(InputCL, props);
+     *
+     *     return <>
+     *         {
+     *             // Other elements...
+     *         }
+     *         <button className="cta"
+     *                 onClick={() => {
+     *                     self.state.putMany({
+     *                         disabled: true
+     *                     }); // No type assertion needed outside the class.
+     *                 }}>
+     *             Submit
+     *         </button>
+     *     </>;
+     * };
+     */
     readonly putMany: (newValues: PutManyPayload<TState>) => void;
 }
 /** @internal */

package/build/base/state/class.js

@@ -19,7 +19,59 @@ var CleanStateBase = /** @class */ (function () {
         var _this = this;
         this._values_ = {};
         this._setters_ = {};
-        // readonly putMany = (newValues: Partial<TState>) => {
+        /**
+         * Accepts an object to be merged into the current state object,
+         * updating the values of specified keys to their specified values.
+         *
+         * All specified keys must be present on the initial state object.
+         * This is a requirement of React hooks, as the number of calls to
+         * useState must be the same throughout a component's lifetime.
+         *
+         * To dynamically add new keys to your state object, use a nested object,
+         * or use the {@link useMergedState | `useMergedState`} hook also exported by this library.
+         *
+         * When called from inside a component class, the type of the object passed
+         * must be explicitly specified with a type assertion.
+         * This is because the component classes use the dynamic `this` type to define
+         * the type of their state property.
+         *
+         * Use the `StateFragment` type, also aliased as `SF`, to define this type assertion.
+         * The assertion is not needed when calling putMany from outside the class.
+         *
+         * @example <caption>Using `putMany`</caption>
+         * import type { SF } from '@cleanweb/oore/base';
+         * import { ComponentLogic } from '@cleanweb/oore';
+         *
+         * class InputCL extends ComponentLogic<TProps> {
+         *     getInitialState(props: TProps): TState => ({
+         *         disabled: true,
+         *     });
+         *
+         *     enableInput = () => {
+         *         this.state.putMany({
+         *             disabled: false,
+         *         } as SF<this>); // Type assertion required inside class.
+         *     };
+         * }
+         *
+         * export const Input = (props: TProps) => {
+         *     const self = useLogic(InputCL, props);
+         *
+         *     return <>
+         *         {
+         *             // Other elements...
+         *         }
+         *         <button className="cta"
+         *                 onClick={() => {
+         *                     self.state.putMany({
+         *                         disabled: true
+         *                     }); // No type assertion needed outside the class.
+         *                 }}>
+         *             Submit
+         *         </button>
+         *     </>;
+         * };
+         */
         this.putMany = function (newValues) {
             Object.entries(newValues).forEach(function (entry) {
                 var _a = entry, key = _a[0], value = _a[1];

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

@@ -5,4 +5,5 @@ import '../../globals';
 export { CleanState } from './class';
 export { useCleanState } from './hooks';
 export type { TCleanState, TStateData, ExtractCleanStateData } from './hook-types';
+export type { SF, StateFragment } from './class-types';
 export * as MergedState from '../../base/merged-state';

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

@@ -52,7 +52,7 @@ export declare class ComponentLogic<TProps extends TPropsBase = null> {
      * It receives the initial `props` object and should return
      * an object with the initial values for your component's state.
      */
-    getInitialState: (props?: TProps extends null ? undefined : TProps) => object;
+    getInitialState: (props: TProps extends null ? undefined : TProps) => object;
     /**
      * Call React hooks from here. If your component needs
      * access to values return from the hooks you call,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cleanweb/oore",
-	"version": "1.0.6",
+	"version": "1.1.0",
 	"description": "A library of helpers for writing cleaner React function components with object-oriented patterns.",
 	"engines": {
 		"node": ">=20"