@cleanweb/oore 2.0.0-alpha.12 → 2.0.0-alpha.14

package/build/slots/hook.d.ts

@@ -1,10 +1,11 @@
-import type { ReactElement, ReactNode } from 'react';
+import type { ReactElement, ReactNode, ReactPortal } from 'react';
 import type { IUseSlots, PotentialSlotComponent } from './types';
 export declare const isElementChild: (child: ReactNode) => child is ReactElement<any, any>;
 interface IGetSlotName {
     (TargetComponent: PotentialSlotComponent, child?: ReactElement): string | undefined;
 }
 export declare const getComponentSlotName: IGetSlotName;
+export declare const isPortalChild: (child: ReactNode) => child is ReactPortal;
 /**
  * Groups `children` prop into predefined slots.
  *
@@ -16,4 +17,4 @@ export declare const getComponentSlotName: IGetSlotName;
  * @see {@link SlotComponent} for more on how to use the returned slot nodes.
  */
 export declare const useSlots: IUseSlots;
-export type { SlotNamedComponent, Slotted as SlottedComponent, TSlotsRecord, PotentialSlotComponent, } from './types';
+export type { SlottedComponent, TSlotsRecord, SlotComponent, PotentialSlotComponent, } from './types';

package/build/slots/hook.js

@@ -32,7 +32,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useSlots = exports.getComponentSlotName = exports.isElementChild = void 0;
+exports.useSlots = exports.isPortalChild = exports.getComponentSlotName = exports.isElementChild = void 0;
 var errors_1 = require("../helpers/errors");
 var react_1 = __importStar(require("react"));
 var isElementChild = function (child) {
@@ -47,9 +47,6 @@ var getComponentSlotName = function (TargetComponent, child) {
         var keyTypes = ['string', 'number', 'symbol'];
         var slotName = child.props['data-slot-name'];
         if (keyTypes.includes(typeof slotName)) {
-            if (typeof child.type === 'string') {
-                child.props.tagName = child.type;
-            }
             return slotName;
         }
     }
@@ -65,6 +62,12 @@ var getComponentSlotName = function (TargetComponent, child) {
     return undefined;
 };
 exports.getComponentSlotName = getComponentSlotName;
+var isPortalChild = function (child) {
+    return (!!child
+        && typeof child === 'object'
+        && 'children' in child);
+};
+exports.isPortalChild = isPortalChild;
 /**
  * Groups `children` prop into predefined slots.
  *
@@ -77,7 +80,7 @@ exports.getComponentSlotName = getComponentSlotName;
  */
 var useSlots = function (children, Caller) {
     var slotsAliasLookup = (0, react_1.useMemo)(function () {
-        var entries = Object.entries(Caller.slots);
+        var entries = Object.entries(Caller.Slots);
         var aliasLookup = {};
         entries.forEach(function (_a) {
             var alias = _a[0], RegisteredSlotComponent = _a[1];
@@ -89,15 +92,17 @@ var useSlots = function (children, Caller) {
             aliasLookup[slotName] = alias;
         });
         return aliasLookup;
-    }, [Caller.slots]);
+    }, [Caller.Slots]);
+    // @todo Expose original source order of `children` with respect to slot aliases.
     var result = (0, react_1.useMemo)(function () {
         var _a;
         var slotNodes = {};
         var unmatchedChildren = [];
         var invalidChildren = [];
         var requiredSlotAliases = __spreadArray([], ((_a = Caller.requiredSlotAliases) !== null && _a !== void 0 ? _a : []), true);
-        react_1.default.Children.forEach(children, function (child) {
+        react_1.default.Children.forEach(children, function (_child) {
             var _a;
+            var child = _child;
             if (!child) {
                 invalidChildren.push(child);
                 return;
@@ -114,15 +119,16 @@ var useSlots = function (children, Caller) {
                 return;
             }
             var slotAlias = (function () {
+                var _a;
                 var slotName = (0, exports.getComponentSlotName)(child.type, child);
-                return slotName ? slotsAliasLookup[slotName] : null;
+                return slotName ? (_a = slotsAliasLookup[slotName]) !== null && _a !== void 0 ? _a : null : null;
             })();
-            if (slotAlias && (typeof Caller.slots[slotAlias] !== 'string')) {
-                if ((_a = Caller.slots[slotAlias]) === null || _a === void 0 ? void 0 : _a.isRequiredSlot) {
-                    requiredSlotAliases.push(slotAlias);
-                }
-            }
             if (slotAlias) {
+                if (typeof Caller.Slots[slotAlias] !== 'string') {
+                    if ((_a = Caller.Slots[slotAlias]) === null || _a === void 0 ? void 0 : _a.isRequiredSlot) {
+                        requiredSlotAliases.push(slotAlias);
+                    }
+                }
                 if (slotNodes[slotAlias]) {
                     slotNodes[slotAlias].push(child);
                 }

package/build/slots/types.d.ts

@@ -1,7 +1,8 @@
-import { ComponentMethods } from '../base';
-import { ComponentLogic } from '../classy';
-import type { ReactElement, ReactNode, JSXElementConstructor } from 'react';
-export type TComponent = JSXElementConstructor<any> | ComponentLogic | ComponentMethods;
+import type { ReactElement, ReactNode, ComponentType, ReactPortal, JSX } from 'react';
+/** @todo ComponentType force children to be ReactNode, but custom components can have any children type. */
+type JSXTagLike = string | keyof JSX.IntrinsicElements | ComponentType<any>;
+/** This fixes overly narrow T type used by React's ComponentProps type. */
+export type ComponentProps<T extends JSXTagLike> = (T extends ComponentType<infer P> ? P : T extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[T] : {});
 export type TSlotName = keyof any;
 export type TSlotAlias = keyof any;
 /**
@@ -11,18 +12,24 @@ export type TSlotAlias = keyof any;
  * 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;
+    [Key in TKey]: SlotComponent<string | ComponentType<any>>;
 };
-export type DisplayNamedComponent<TComponentArg extends TComponent = TComponent, TDisplayNameArg extends string = string> = TComponentArg & {
-    displayName: TDisplayNameArg;
-};
-export type SlotNamedComponent<TComponentArg extends TComponent = TComponent, TSlotNameArg extends TSlotName = TSlotName> = TComponentArg & {
-    slotName: TSlotNameArg;
+export type DisplayNamedComponent<TComponent extends ComponentType<any> = ComponentType<any>, TName extends string = string> = TComponent & {
+    displayName: TName;
 };
+interface ISlotConfig<TName> {
+    slotName: TName;
+    /**
+     * @deprecated The SlottedComponent should be responsible for indicating which slots it requires.
+     * Individual slot components may be reused by multiple slotted components with varying requirements.
+     */
+    isRequiredSlot?: boolean;
+}
 /**
  * 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.
+ *
+ * > `displayName` is no longer supported as a fallback for `slotName`.
  *
  * ### Strings
  * For strings, they are treated by React a native tags. This lets you use custom strings
@@ -38,7 +45,7 @@ export type SlotNamedComponent<TComponentArg extends TComponent = TComponent, TS
  * and you can map that to
  * ```jsx
  * <button
- *     {...slotNodes.Option.props}
+ *     {...slotNodes.Option[0].props}
  *     type="button"
  * />
  * ```
@@ -49,9 +56,9 @@ export type SlotNamedComponent<TComponentArg extends TComponent = TComponent, TS
  *
  * So consumers may pass the following as `children`.
  * ```jsx
- * <Parent.slots.Content>
+ * <Parent.Slots.Content>
  *     Some awesome content.
- * </Parent.slots.Content>
+ * </Parent.Slots.Content>
  * ```
  * and you can map that to
  * ```jsx
@@ -62,7 +69,7 @@ export type SlotNamedComponent<TComponentArg extends TComponent = TComponent, TS
  * </>
  * ```
  *
- * This means `Parent.slots.Content` must be defined as a proper React component
+ * 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.
  *
@@ -70,9 +77,7 @@ export type SlotNamedComponent<TComponentArg extends TComponent = TComponent, TS
  * 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;
-};
+export type SlotComponent<TComponent extends JSXTagLike = ComponentType<any>, TName extends TSlotName = TSlotName> = (TComponent extends string ? TComponent : TComponent & ISlotConfig<TName>);
 /**
  * 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}.
@@ -81,18 +86,20 @@ export type SlotComponent<TComponentArg extends TComponent = TComponent> = (Slot
  * directly from the parent component itself,
  * through an alias that is easy to remember.
  */
-export type Slotted<TComponentArg extends object = TComponent, TSlotAliasArg extends TSlotAlias = TSlotAlias, TSlotsRecordArg extends TSlotsRecord<TSlotAliasArg> = TSlotsRecord<TSlotAliasArg>> = TComponentArg & {
-    slots: TSlotsRecordArg;
-    requiredSlotAliases?: TSlotAliasArg[];
+export type SlottedComponent<TOwner extends object = ComponentType<any>, TSlots extends TSlotsRecord = TSlotsRecord> = TOwner & {
+    Slots: TSlots;
+    requiredSlotAliases?: Array<keyof TSlots>;
 };
+export type TypedNode<P, T extends JSXTagLike> = (ReactElement<P, T> | (ReactElement<P, T> & ReactPortal));
+export type TSlotNode<TSlotted extends SlottedComponent, Key extends keyof TSlotted['Slots'] = keyof TSlotted['Slots']> = (TypedNode<ComponentProps<TSlotted['Slots'][Key]>, TSlotted['Slots'][Key]>);
 /**
  * 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]?: Array<ReactElement<any>>;
+export type TSlotNodes<TSlotted extends SlottedComponent> = {
+    [Key in keyof TSlotted['Slots']]?: Array<TSlotNode<TSlotted, Key>>;
 };
-export type TUseSlotsResult<TSlotAliasArg extends TSlotAlias = TSlotAlias> = Readonly<[
+export type TUseSlotsResult<TSlotted extends SlottedComponent> = Readonly<[
     /**
      * 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
@@ -100,7 +107,7 @@ export type TUseSlotsResult<TSlotAliasArg extends TSlotAlias = TSlotAlias> = Rea
      *
      * If a slot was not rendered in `children`, it's alias will be `undefined` in this object.
      */
-    slotNodes: TSlotNodes<TSlotAliasArg>,
+    slotNodes: TSlotNodes<TSlotted>,
     /**
      * Valid React nodes passed as children which did not match any of the
      * predefined slots.
@@ -112,12 +119,13 @@ export type TUseSlotsResult<TSlotAliasArg extends TSlotAlias = TSlotAlias> = Rea
     invalidChildren: any[]
 ]>;
 export interface IUseSlots {
-    <TSlotAliasArg extends TSlotAlias = TSlotAlias>(
+    <TSlotted extends SlottedComponent>(
     /**
      * Your component's `children` prop.
      * The nodes it contains will be categorized and
      * grouped according to the predefined {@link slotComponents}.
      */
-    children: ReactNode, Caller: Slotted): TUseSlotsResult<TSlotAliasArg>;
+    children: ReactNode, Caller: TSlotted): TUseSlotsResult<TSlotted>;
 }
-export type PotentialSlotComponent = string | SlotComponent | TComponent;
+export type PotentialSlotComponent = string | SlotComponent | ComponentType<any>;
+export {};

package/package.json

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