@cleanweb/oore 1.2.2-alpha.2 → 1.2.2-alpha.5

package/build/helpers/rerender.d.ts

@@ -1,5 +1,24 @@
+interface ICountRef {
+    current: number;
+}
+interface IRefresherReturn {
+    /** The last render count just before the rerender was triggered. */
+    previousCount: number;
+    /** A {@link useRef | RefObject} whose `current` property always has the latest render count. */
+    latestCountRef: ICountRef;
+}
+interface IRefresher {
+    (): Promise<IRefresherReturn>;
+}
+interface IUseRender {
+    (): IRefresher & {
+        /** The number of times this instance of the component has been (re)rendered. */
+        currentCount: number;
+    };
+}
 /**
  * Returns a function that can be called to manually trigger
  * a rerender of your component.
  */
-export declare const useRerender: () => () => Promise<unknown>;
+export declare const useRerender: IUseRender;
+export {};

package/build/helpers/rerender.js

@@ -1,37 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useRerender = void 0;
-var mount_state_1 = require("../helpers/mount-state");
 var react_1 = require("react");
+var mount_state_1 = require("../helpers/mount-state");
+;
 /**
  * Returns a function that can be called to manually trigger
  * a rerender of your component.
  */
 var useRerender = function () {
     var isMounted = (0, mount_state_1.useMountState)();
-    var _a = (0, react_1.useState)(Date.now()), key = _a[0], forceRerender = _a[1];
-    var rerender = (0, react_1.useCallback)(function () { return new Promise(function (resolve, reject) {
+    var renderCount = (0, react_1.useRef)(0);
+    var _a = (0, react_1.useState)(renderCount.current), forceRerender = _a[1];
+    renderCount.current++;
+    var rerender = (0, react_1.useCallback)(function () {
+        var resolve;
+        var promise = new Promise(function (_r) { return resolve = _r; });
         var execute = function () {
-            var key = Date.now();
-            forceRerender(key);
-            resolve(key);
+            forceRerender(renderCount.current);
+            resolve({
+                previousCount: renderCount.current,
+                latestCountRef: renderCount,
+            });
         };
-        if (isMounted()) {
+        if (isMounted())
             execute();
-            return;
+        else {
+            setTimeout(function () {
+                if (isMounted())
+                    execute();
+                else
+                    console.log('Cannot rerender an unmounted component.');
+            }, 1000);
         }
-        setTimeout(function () {
-            if (isMounted()) {
-                execute();
-                return;
-            }
-            else {
-                console.log('Cannot rerender an unmounted component.');
-            }
-        }, 1000);
-    }); }, [forceRerender]);
-    // @ts-expect-error
-    rerender.key = key;
-    return rerender;
+        return promise;
+    }, [forceRerender, renderCount]);
+    var refresher = function () { return rerender(); };
+    refresher.currentCount = renderCount.current;
+    return refresher;
 };
 exports.useRerender = useRerender;

package/build/slots/hook.d.ts

@@ -5,5 +5,15 @@ interface IGetSlotName {
     (TargetComponent: PotentialSlotComponent, child?: ReactElement): string | undefined;
 }
 export declare const getComponentSlotName: IGetSlotName;
+/**
+ * Groups `children` prop into predefined slots.
+ *
+ * @returns A {@link TUseSlotsResult} array,
+ * which includes a `slotNodes` object that maps the keys from
+ * the predefined {@link slotComponents} object to the corresponding
+ * React node(s) that were rendered for that slot.
+ *
+ * @see {@link SlotComponent} for more on how to use the returned slot nodes.
+ */
 export declare const useSlots: IUseSlots;
 export type { SlotNamedComponent, SlottedComponent, TSlotsRecord, PotentialSlotComponent, } from './types';

package/build/slots/hook.js

@@ -1,4 +1,27 @@
 "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 __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;
+};
 var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
         if (ar || !(i in from)) {
@@ -8,13 +31,10 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     }
     return to.concat(ar || Array.prototype.slice.call(from));
 };
-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 react_1 = __importStar(require("react"));
 var isElementChild = function (child) {
     if (child && typeof child === 'object' && 'type' in child) {
         return true;
@@ -45,9 +65,18 @@ var getComponentSlotName = function (TargetComponent, child) {
     return undefined;
 };
 exports.getComponentSlotName = getComponentSlotName;
+/**
+ * Groups `children` prop into predefined slots.
+ *
+ * @returns A {@link TUseSlotsResult} array,
+ * which includes a `slotNodes` object that maps the keys from
+ * the predefined {@link slotComponents} object to the corresponding
+ * React node(s) that were rendered for that slot.
+ *
+ * @see {@link SlotComponent} for more on how to use the returned slot nodes.
+ */
 var useSlots = function (children, slotComponents, requiredSlotAliases) {
-    var useMemo = react_1.default.useMemo;
-    var slotsAliasLookup = useMemo(function () {
+    var slotsAliasLookup = (0, react_1.useMemo)(function () {
         var entries = Object.entries(slotComponents);
         var aliasLookup = {};
         entries.forEach(function (_a) {
@@ -61,7 +90,7 @@ var useSlots = function (children, slotComponents, requiredSlotAliases) {
         });
         return aliasLookup;
     }, [slotComponents]);
-    var result = useMemo(function () {
+    var result = (0, react_1.useMemo)(function () {
         var slotNodes = {};
         var unmatchedChildren = [];
         var invalidChildren = [];
@@ -91,14 +120,11 @@ var useSlots = function (children, slotComponents, requiredSlotAliases) {
                 }
             }
             if (slotAlias) {
-                if (!slotNodes[slotAlias]) {
-                    slotNodes[slotAlias] = child;
-                }
-                else if (Array.isArray(slotNodes[slotAlias])) {
+                if (slotNodes[slotAlias]) {
                     slotNodes[slotAlias].push(child);
                 }
                 else {
-                    slotNodes[slotAlias] = [slotNodes[slotAlias], child];
+                    slotNodes[slotAlias] = [child];
                 }
             }
             else

package/build/slots/types.d.ts

@@ -2,6 +2,12 @@ import type { ReactElement, ReactNode, JSXElementConstructor } from 'react';
 export type TComponent = JSXElementConstructor<any>;
 export type TSlotName = keyof any;
 export type TSlotAlias = keyof any;
+/**
+ * A map of slot aliases to actual {@link SlotComponent}s.
+ *
+ * The `useSlots` hook will create a corresponding key for
+ * each alias in this record to hold any `ReactNode`s rendered for that slot.
+ */
 export type TSlotsRecord<TKey extends TSlotAlias = TSlotAlias> = {
     [Key in TKey]: string | SlotComponent;
 };
@@ -11,21 +17,119 @@ export type DisplayNamedComponent<TComponentArg extends TComponent = TComponent,
 export type SlotNamedComponent<TComponentArg extends TComponent = TComponent, TSlotNameArg extends TSlotName = TSlotName> = TComponentArg & {
     slotName: TSlotNameArg;
 };
+/**
+ * A child component used to insert content into a specific slot in the parent component.
+ * This can either be a string, or a React component with a `slotName` property.
+ * If `slotName` is missing `displayName` will be used as a fallback.
+ *
+ * ### Strings
+ * For strings, they are treated by React a native tags. This lets you use custom strings
+ * as if you are rendering a custom Web Component, or simply handle specific HTML tags in a specific way.
+ *
+ * If using a custom string, you will want to handle it in the parent component by simply forwarding the slot's
+ * props to an actual element of your choice.
+ *
+ * So consumers may pass the following as `children`.
+ * ```jsx
+ * <option-slot>Click</option-slot>
+ * ```
+ * and you can map that to
+ * ```jsx
+ * <button
+ *     {...slotNodes.Option.props}
+ *     type="button"
+ * />
+ * ```
+ *
+ * ### React Components
+ * For slot components that are actual React components, the parent can simply
+ * render the slot node directly.
+ *
+ * So consumers may pass the following as `children`.
+ * ```jsx
+ * <Parent.slots.Content>
+ *     Some awesome content.
+ * </Parent.slots.Content>
+ * ```
+ * and you can map that to
+ * ```jsx
+ * return <>
+ *     <h1>Title</h1>
+ *     {slotNodes.Content}
+ *     <footer>Powered by oore</footer>
+ * </>
+ * ```
+ *
+ * This means `Parent.slots.Content` must be defined as a proper React component
+ * and is solely responsible for doing something with the `"Some awesome content."`
+ * which was passed into it as children.
+ *
+ * This is unlike the string version where the parent component
+ * extracts the props passed to the slot and handles
+ * what the slot actually renders.
+ */
 export type SlotComponent<TComponentArg extends TComponent = TComponent> = (SlotNamedComponent<TComponentArg> | DisplayNamedComponent<TComponentArg>) & {
     isRequiredSlot?: boolean;
 };
+/**
+ * A parent component which accepts content that can be grouped into predefined slots.
+ * By convention, it should have a `slots` property which is a {@link TSlotsRecord}.
+ *
+ * This allows consumers access the predefined slot components
+ * directly from the parent component itself,
+ * through an alias that is easy to remember.
+ */
 export type SlottedComponent<TComponentArg extends TComponent = TComponent, TSlotAliasArg extends TSlotAlias = TSlotAlias, TSlotsRecordArg extends TSlotsRecord<TSlotAliasArg> = TSlotsRecord<TSlotAliasArg>> = TComponentArg & {
-    Slots: TSlotsRecordArg;
+    [Key in 'Slots' | 'slots']: TSlotsRecordArg;
 };
+/**
+ * A record of slot aliases mapped to the corresponding `ReactNode`(s)
+ * to be rendered for that slot.
+ */
 export type TSlotNodes<TSlotAliasArg extends TSlotAlias> = {
-    [Key in TSlotAliasArg]?: ReactElement<any> | Array<ReactElement<any>>;
+    [Key in TSlotAliasArg]?: Array<ReactElement<any>>;
 };
 export type TUseSlotsResult<TSlotAliasArg extends TSlotAlias = TSlotAlias> = Readonly<[
-    slots: TSlotNodes<TSlotAliasArg>,
+    /**
+     * A record of slot aliases to their corresponding React nodes.
+     * Each alias maps to an array of one or more React nodes that were passed
+     * as children for that slot.
+     *
+     * If a slot was not rendered in `children`, it's alias will be `undefined` in this object.
+     */
+    slotNodes: TSlotNodes<TSlotAliasArg>,
+    /**
+     * Valid React nodes passed as children which did not match any of the
+     * predefined slots.
+     */
     unmatchedChildren: ReactNode[],
+    /**
+     * Items included in `children` which are not valid React nodes.
+     */
     invalidChildren: any[]
 ]>;
 export interface IUseSlots {
-    <TSlotAliasArg extends TSlotAlias = TSlotAlias>(children: ReactNode, slotComponents: TSlotsRecord<TSlotAliasArg>, requiredSlotAliases?: TSlotAliasArg[]): TUseSlotsResult<TSlotAliasArg>;
+    <TSlotAliasArg extends TSlotAlias = TSlotAlias>(
+    /**
+     * Your component's `children` prop.
+     * The nodes it contains will be categorized and
+     * grouped according to the predefined {@link slotComponents}.
+     */
+    children: ReactNode, 
+    /**
+     * A map of slot aliases to their corresponding {@link SlotComponent}.
+     * React nodes passed as children will be compared with the components
+     * in this record to generate the categorized `slotNodes` object.
+     */
+    slotComponents: TSlotsRecord<TSlotAliasArg>, 
+    /**
+     * An array of aliases to be treated as required. If a slot's
+     * alias is in this array, the slot is treated as required.
+     *
+     * If no ReactNode is found in {@link children | `children`}
+     * for a required slot, an error will be thrown in development.
+     * However in production this is softened to just a console warning.
+     */
+    requiredSlotAliases?: TSlotAliasArg[]): TUseSlotsResult<TSlotAliasArg>;
 }
 export type PotentialSlotComponent = string | SlotComponent | TComponent;

package/package.json

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