@cleanweb/oore 1.0.6 → 1.1.0-alpha.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/build/helpers/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Throw an error with the provided message
+ * only when `NODE_ENV` is *not* 'production'.
+ *
+ * In production, this falls back to just a console warning.
+ *
+ * Useful for enforcing certain conditions in development
+ * while failing more gracefully in production.
+ */
+export declare const throwDevError: (message: string) => void;

package/build/helpers/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwDevError = void 0;
+/**
+ * Throw an error with the provided message
+ * only when `NODE_ENV` is *not* 'production'.
+ *
+ * In production, this falls back to just a console warning.
+ *
+ * Useful for enforcing certain conditions in development
+ * while failing more gracefully in production.
+ */
+var throwDevError = function (message) {
+    if (process.env.NODE_ENV === 'production') {
+        console.warn(message);
+    }
+    else {
+        throw new Error(message);
+    }
+};
+exports.throwDevError = throwDevError;

package/build/slots/hook.d.ts

@@ -0,0 +1,6 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { IUseSlots, PotentialSlotComponent } from './types';
+export declare const isElementChild: (child: ReactNode) => child is ReactElement<any, any>;
+export declare const getComponentSlotName: (TargetComponent: PotentialSlotComponent) => string | number | symbol | undefined;
+export declare const useSlots: IUseSlots;
+export type { SlotNamedComponent, SlottedComponent, TSlotsRecord, PotentialSlotComponent, } from './types';

package/build/slots/hook.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSlots = exports.getComponentSlotName = exports.isElementChild = void 0;
+var errors_1 = require("../helpers/errors");
+var react_1 = __importDefault(require("react"));
+var isElementChild = function (child) {
+    if (child && typeof child === 'object' && 'type' in child) {
+        return true;
+    }
+    return false;
+};
+exports.isElementChild = isElementChild;
+var getComponentSlotName = function (TargetComponent) {
+    if (typeof TargetComponent === 'string') {
+        return TargetComponent;
+    }
+    else if ('slotName' in TargetComponent) {
+        return TargetComponent.slotName;
+    }
+    else if ('displayName' in TargetComponent) {
+        return TargetComponent.displayName;
+    }
+    else
+        return undefined;
+};
+exports.getComponentSlotName = getComponentSlotName;
+var useSlots = function (children, slotComponents) {
+    var useMemo = react_1.default.useMemo;
+    console.log({ slotComponents: slotComponents });
+    var slotsAliasLookup = useMemo(function () {
+        var entries = Object.entries(slotComponents);
+        var aliasLookup = {};
+        entries.forEach(function (_a) {
+            var alias = _a[0], RegisteredSlotComponent = _a[1];
+            var slotName = (0, exports.getComponentSlotName)(RegisteredSlotComponent);
+            if (!slotName) {
+                (0, errors_1.throwDevError)("A registered slot component did not have a slot name. All components registered as slots must either be a string tag-name or a React component with either \"slotName\" or \"displayName\". The affected component was: ".concat(RegisteredSlotComponent));
+                return;
+            }
+            return aliasLookup[slotName] = alias;
+        });
+        return aliasLookup;
+    }, [slotComponents]);
+    console.log({ slotsAliasLookup: slotsAliasLookup });
+    var result = useMemo(function () {
+        var slotNodes = {};
+        var unmatchedChildren = [];
+        var invalidChildren = [];
+        react_1.default.Children.forEach(children, function (child) {
+            if (!child) {
+                invalidChildren.push(child);
+                return;
+            }
+            if (!react_1.default.isValidElement(child)) {
+                console.warn("Invalid node found in JSX children while parsing slots. Got: \"".concat(child, "\"."));
+                invalidChildren.push(child);
+                return;
+            }
+            ;
+            if (!(0, exports.isElementChild)(child)) {
+                unmatchedChildren.push(child);
+                return;
+            }
+            var slotAlias = (function () {
+                var ChildComponent = child.type;
+                var slotName = (0, exports.getComponentSlotName)(ChildComponent);
+                return slotName ? slotsAliasLookup[slotName] : null;
+            })();
+            console.log('match:', { key: slotAlias });
+            if (slotAlias)
+                slotNodes[slotAlias] = child;
+            else
+                unmatchedChildren.push(child);
+        });
+        console.log({ unmatchedChildren: unmatchedChildren, invalidChildren: invalidChildren });
+        return [slotNodes, unmatchedChildren, invalidChildren];
+    }, [children]);
+    return result;
+};
+exports.useSlots = useSlots;

package/build/slots/index.d.ts

@@ -0,0 +1 @@
+export * from './hook';

package/build/slots/index.js

@@ -0,0 +1,17 @@
+"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("./hook"), exports);

package/build/slots/types.d.ts

@@ -0,0 +1,31 @@
+import type { ReactElement, ReactNode, JSXElementConstructor, FunctionComponent } from 'react';
+export type TComponent = JSXElementConstructor<any>;
+export type TSlotName = keyof any;
+export type TSlotAlias = keyof any;
+export type TSlotsRecord<TKey extends TSlotAlias = TSlotAlias> = {
+    [Key in TKey]: (string | SlotComponent);
+};
+export interface DisplayNamedComponent<TProps extends any = any> extends FunctionComponent<TProps> {
+    displayName: string;
+}
+export interface SlotNamedComponent<TProps extends any = any> {
+    (props: TProps): ReactNode;
+    slotName: TSlotName;
+}
+export type SlotComponent<Component extends TComponent = TComponent> = SlotNamedComponent | DisplayNamedComponent<Component>;
+export interface SlottedComponent<TProps = any, TSlotsRecordArg extends TSlotsRecord = TSlotsRecord> {
+    (props: TProps): ReactNode;
+    Slots: TSlotsRecordArg;
+}
+export type TSlotNodes<TSlotAliasArg extends TSlotAlias> = {
+    [Key in TSlotAliasArg]?: ReactElement<any>;
+};
+export type TUseSlotsResult<TSlotAliasArg extends TSlotAlias = TSlotAlias> = Readonly<[
+    slots: TSlotNodes<TSlotAliasArg>,
+    unmatchedChildren: ReactNode[],
+    invalidChildren: any[]
+]>;
+export interface IUseSlots {
+    <TSlotAliasArg extends TSlotAlias = TSlotAlias>(children: ReactNode, slotComponents: TSlotsRecord<TSlotAliasArg>): TUseSlotsResult<TSlotAliasArg>;
+}
+export type PotentialSlotComponent = string | SlotComponent | TComponent;

package/build/slots/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cleanweb/oore",
-	"version": "1.0.6",
+	"version": "1.1.0-alpha.0",
 	"description": "A library of helpers for writing cleaner React function components with object-oriented patterns.",
 	"engines": {
 		"node": ">=20"
@@ -10,15 +10,11 @@
 		".npmrc"
 	],
 	"main": "build/index.js",
-	"//exports/.": {
-		"require": "./src/index.cjs",
-		"import": "./src/index.mjs"
-	},
-	"//type": "module",
 	"exports": {
 		".": "./build/classy/index.js",
 		"./base": "./build/base/index.js",
 		"./helpers": "./build/helpers/index.js",
+		"./slots": "./build/slots/index.js",
 		"./all": "./build/index.js"
 	},
 	"scripts": {