@cleanweb/oore 2.0.0-alpha.24 → 2.0.0-alpha.26

package/build/_cjs/helpers/debounce/index.d.ts

@@ -0,0 +1,55 @@
+interface IDebouncedFunction<TFunc extends AnyFunction> {
+    (...args: Parameters<TFunc>): Promise<ReturnType<TFunc>>;
+    /**
+     * Called internally to trigger the callback with the most recent args
+     * after the delay expires. Can be used to manually trigger the callback
+     * before the normal delay time. If no pending call exists, flush() becomes a no-op.
+     */
+    flush: (isEager?: true) => void;
+}
+export interface IDelayConfig {
+    /**
+     * A non-zero delay in milliseconds.
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * The 'last-call' value specifies that the timer should be applied from the time of the most recent call.
+     * That means each new call while a delay is active will reset the timer, thereby extending the delay.
+     * In other words, it is a "time after inactivity" delay.
+     * Specifying 'first-call' instead will make it use a "time after initial call" delay strategy.
+     */
+    anchor?: 'first-call' | 'last-call';
+    /**
+     * Controls eager execution behavior:
+     * - `false`: Initial call waits for the delay period before executing.
+     * - `'no-queue'`: Initial call fires immediately. Subsequent calls during the delay period
+     *   are skipped and return the promise from the initial call. Ideal for preventing
+     *   duplicate actions like clicking a download button twice.
+     * - `'with-queue'`: Initial call fires immediately. After the initial flush, the promise
+     *   is discarded. The next call during the delay period creates a new workorder that will
+     *   be maintained until the next flush. Ideal for debounced search inputs and similar use cases.
+     * @default 'with-queue'
+     */
+    eager?: false | 'no-queue' | 'with-queue';
+}
+interface IDebounce {
+    <TFunc extends AnyFunction>(callback: TFunc, delayConfigArg?: number | IDelayConfig): IDebouncedFunction<TFunc>;
+}
+/**
+ * Wraps the provided function with a debounce.
+ *
+ * Behavior during the delay period depends on the `eager` configuration:
+ * - `eager: false`: All calls wait for the delay. New calls overwrite the existing call.
+ * - `eager: 'no-queue'`: First call fires immediately. Subsequent calls during the delay
+ *   period are skipped and return the same promise as the initial call.
+ * - `eager: 'with-queue'` (default): First call fires immediately. After the flush, the next call
+ *   creates a new workorder that will be fired after the delay. New calls overwrite queued args.
+ *
+ * Once the timer expires, the most recent call is fired.
+ *
+ * Note: Returned promises may resolve with values from calls made with
+ * different arguments. Avoid using this for functions where argument-specific results matter.
+ */
+export declare const debounce: IDebounce;
+export {};

package/build/_cjs/helpers/debounce/index.js

@@ -0,0 +1,114 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debounce = void 0;
+/**
+ * Wraps the provided function with a debounce.
+ *
+ * Behavior during the delay period depends on the `eager` configuration:
+ * - `eager: false`: All calls wait for the delay. New calls overwrite the existing call.
+ * - `eager: 'no-queue'`: First call fires immediately. Subsequent calls during the delay
+ *   period are skipped and return the same promise as the initial call.
+ * - `eager: 'with-queue'` (default): First call fires immediately. After the flush, the next call
+ *   creates a new workorder that will be fired after the delay. New calls overwrite queued args.
+ *
+ * Once the timer expires, the most recent call is fired.
+ *
+ * Note: Returned promises may resolve with values from calls made with
+ * different arguments. Avoid using this for functions where argument-specific results matter.
+ */
+const debounce = (...init) => {
+    const [callback, delayArg] = init;
+    const delayConfig = {
+        delay: 1000,
+        anchor: 'first-call',
+        eager: 'with-queue',
+    };
+    if (typeof delayArg === 'number') {
+        delayConfig.delay = delayArg || 1000;
+    }
+    else if (delayArg) {
+        for (const _key in delayArg) {
+            const key = _key;
+            if (delayArg[key] !== undefined) {
+                // @ts-expect-error
+                delayConfig[key] = delayArg[key];
+            }
+        }
+    }
+    let nextCall = null;
+    const debouncedFunction = (...args) => {
+        let currentWork;
+        if (nextCall) {
+            if (delayConfig.eager !== 'no-queue') {
+                nextCall = Object.assign(Object.assign({}, nextCall), { args, work: nextCall.work || Promise.withResolvers() });
+            }
+            currentWork = nextCall.work;
+            if (delayConfig.anchor === 'last-call') {
+                clearTimeout(nextCall.timeout);
+                nextCall.timeout = setTimeout(debouncedFunction.flush, delayConfig.delay);
+            }
+        }
+        else {
+            // No active delay, create new call
+            nextCall = {
+                args,
+                timeout: setTimeout(debouncedFunction.flush, delayConfig.delay),
+                work: Promise.withResolvers(),
+            };
+            currentWork = nextCall.work;
+            // Fire immediately if eager mode is enabled (no-queue or with-queue)
+            if (delayConfig.eager !== false) {
+                debouncedFunction.flush(true);
+            }
+        }
+        if (!currentWork) {
+            throw new Error('[debounce] `currentWork` was not initialized.');
+        }
+        return currentWork.promise;
+    };
+    debouncedFunction.flush = (isEager) => {
+        if (!(nextCall === null || nextCall === void 0 ? void 0 : nextCall.args)) {
+            nextCall = null;
+            // console.log('Queue is empty. Nothing to flush.');
+            return;
+        }
+        // Capture queue values.
+        const { resolve, reject } = nextCall.work || {};
+        const args = nextCall.args;
+        // Clear the queue for new debounced calls.
+        if (isEager) {
+            delete nextCall.args;
+            if (delayConfig.eager === 'with-queue') {
+                delete nextCall.work;
+            }
+        }
+        else {
+            nextCall = null;
+        }
+        // Execute the pending call.
+        (() => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            try {
+                const result = (_a = (yield callback(...args))) !== null && _a !== void 0 ? _a : {};
+                result.__debounceFlushedWithArgs = args;
+                resolve === null || resolve === void 0 ? void 0 : resolve(result);
+            }
+            catch (_reason) {
+                const reason = _reason !== null && _reason !== void 0 ? _reason : {};
+                reason.__debounceFlushedWithArgs = args;
+                reject === null || reject === void 0 ? void 0 : reject(reason);
+            }
+        }))();
+    };
+    return debouncedFunction;
+};
+exports.debounce = debounce;

package/build/_cjs/helpers/debounce/react.d.ts

@@ -0,0 +1,7 @@
+import { debounce } from './index.js';
+type TDebounceConfig = Exclude<Parameters<typeof debounce>[1], number>;
+type TDelayConfig = number | TDebounceConfig & {
+    staging?: boolean;
+};
+export declare function useDebouncedState<T extends any>(init: T, config: TDelayConfig): readonly [T, (value: T) => void, T];
+export {};

package/build/_cjs/helpers/debounce/react.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDebouncedState = useDebouncedState;
+const react_1 = require("react.js");
+const _1 = require("./index.js");
+function useDebouncedState(init, config) {
+    const [debouncedValue, setDebouncedValue] = (0, react_1.useState)(init);
+    const [stagedValue, setStagedValue] = (0, react_1.useState)(init);
+    const enableStaging = typeof config === 'object' && config.staging === true;
+    const debounceArgs = [setDebouncedValue, config];
+    const debouncedSetter = (0, react_1.useCallback)((0, _1.debounce)(...debounceArgs), debounceArgs);
+    const setter = (0, react_1.useCallback)((value) => {
+        if (enableStaging) {
+            setStagedValue(value);
+        }
+        debouncedSetter(value);
+    }, [enableStaging, debouncedSetter]);
+    return [debouncedValue, setter, stagedValue];
+}

package/build/_cjs/helpers/object-gate.d.ts

@@ -0,0 +1,74 @@
+type TRecord = Record<keyof any, any>;
+declare namespace _ObjectGate {
+    /** Configure property access for a proxy object. */
+    interface IGateConfig<TSource extends TRecord> {
+        /**
+         * The keys to be exposed for read access through the proxy.
+         * Defaults to [`Reflect.ownKeys(source)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/ownKeys) —
+         * so if omitted, all ["_own properties_"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties)
+         * present on the source at
+         * instantiation time will be exposed for read access through the proxy.
+         */
+        getters?: Readonly<Array<keyof TSource>>;
+        /**
+         * Keys that should definitely be omitted from read access,
+         * even if they are present in {@link getters}.
+         * @default [] - Empty array.
+         */
+        gettersExclude?: Readonly<Array<keyof TSource>>;
+        /**
+         * The keys to be exposed for write access through the proxy.
+         * This defaults to an empty array, so if omitted, none of the gated
+         * properties will be writeable.
+         * @default [] - Empty array.
+         */
+        setters?: Readonly<Array<keyof TSource> | true>;
+        /**
+         * Keys that should definitely be omitted from write access,
+         * even if they are present in {@link setters}.
+         * @default [] - Empty array.
+         */
+        settersExclude?: Readonly<Array<keyof TSource>>;
+    }
+    type Params<TSource extends TRecord> = [
+        /**
+         * The target object, where the actual values are stored.
+         * Keys on the created gate object will use JavaScript getters to return
+         * the real-time value of the same key from this source object.
+         */
+        source: TSource,
+        /** @see {@link IGateConfig} */
+        config?: Readonly<IGateConfig<TSource>>
+    ];
+    class Gate<TSource extends TRecord> {
+        constructor(...params: Params<TSource>);
+    }
+    interface IConstructor {
+        new <TOutput extends Partial<TSource>, TSource extends TRecord>(...params: _ObjectGate.Params<TSource>): TOutput;
+    }
+}
+/**
+ * Creates a new object that acts as a real-time proxy
+ * for the {@link _ObjectGate.Params | `source`} object.
+ * This lets you prevent access to some properties, effectively making them private,
+ * while selectively exposing access to only the properties you specify
+ * in the {@link _ObjectGate.IGateConfig.getters | `getters`} config option.
+ *
+ * The exposed properties are read-only by default,
+ * exposing only a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description)
+ * with no corresponding [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set#description).
+ *
+ * The {@link _ObjectGate.Params | `config`} argument also lets you selectively allow
+ * write access to specific properties through the
+ * {@link _ObjectGate.IGateConfig.setters | `setters`} config option.
+ *
+ * Unlike [`structuredClone`](https://developer.mozilla.org/docs/Web/API/Window/structuredClone)
+ * this doesn't return a _copy_ of the `source` object.
+ *
+ * Instead, it returns a _**Real-time proxy**_. This means that a value is read
+ * from the source object each time a property is accessed through the proxy.
+ * So accessing a property through the gate object is guaranteed to always return
+ * the latest value.
+ */
+export declare const ObjectGate: _ObjectGate.IConstructor;
+export {};

package/build/_cjs/helpers/object-gate.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectGate = void 0;
+var _ObjectGate;
+(function (_ObjectGate) {
+    class Gate {
+        constructor(...params) {
+            var _a, _b, _c, _d;
+            const [source, config] = params;
+            const getters = (_a = config === null || config === void 0 ? void 0 : config.getters) !== null && _a !== void 0 ? _a : Reflect.ownKeys(source);
+            const gettersExclude = (_b = config === null || config === void 0 ? void 0 : config.gettersExclude) !== null && _b !== void 0 ? _b : [];
+            const setters = (config === null || config === void 0 ? void 0 : config.setters) === true
+                ? getters
+                : ((_c = config === null || config === void 0 ? void 0 : config.setters) !== null && _c !== void 0 ? _c : []);
+            const settersExclude = (_d = config === null || config === void 0 ? void 0 : config.settersExclude) !== null && _d !== void 0 ? _d : [];
+            getters.forEach((_key) => {
+                const key = _key;
+                if (gettersExclude.includes(key))
+                    return;
+                Object.defineProperty(this, key, {
+                    enumerable: true,
+                    configurable: true,
+                    get() {
+                        return source[key];
+                    },
+                });
+            });
+            setters.forEach((_key) => {
+                const key = _key;
+                if (settersExclude.includes(key))
+                    return;
+                Object.defineProperty(this, key, {
+                    enumerable: true,
+                    set(value) {
+                        source[key] = value;
+                    },
+                });
+            });
+        }
+    }
+    _ObjectGate.Gate = Gate;
+    ;
+})(_ObjectGate || (_ObjectGate = {}));
+/**
+ * Creates a new object that acts as a real-time proxy
+ * for the {@link _ObjectGate.Params | `source`} object.
+ * This lets you prevent access to some properties, effectively making them private,
+ * while selectively exposing access to only the properties you specify
+ * in the {@link _ObjectGate.IGateConfig.getters | `getters`} config option.
+ *
+ * The exposed properties are read-only by default,
+ * exposing only a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description)
+ * with no corresponding [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set#description).
+ *
+ * The {@link _ObjectGate.Params | `config`} argument also lets you selectively allow
+ * write access to specific properties through the
+ * {@link _ObjectGate.IGateConfig.setters | `setters`} config option.
+ *
+ * Unlike [`structuredClone`](https://developer.mozilla.org/docs/Web/API/Window/structuredClone)
+ * this doesn't return a _copy_ of the `source` object.
+ *
+ * Instead, it returns a _**Real-time proxy**_. This means that a value is read
+ * from the source object each time a property is accessed through the proxy.
+ * So accessing a property through the gate object is guaranteed to always return
+ * the latest value.
+ */
+exports.ObjectGate = _ObjectGate.Gate;

package/build/_cjs/slots/hook.js

@@ -50,6 +50,9 @@ const getComponentSlotName = (TargetComponent, child) => {
     else if ('displayName' in TargetComponent) {
         return TargetComponent.displayName;
     }
+    else if ('name' in TargetComponent) {
+        return TargetComponent.name;
+    }
     return undefined;
 };
 exports.getComponentSlotName = getComponentSlotName;
@@ -72,14 +75,18 @@ exports.isPortalChild = isPortalChild;
 const useSlots = (children, Caller) => {
     const slotsAliasLookup = (0, react_1.useMemo)(() => {
         const entries = Object.entries(Caller.Slots);
-        const aliasLookup = {};
+        const aliasLookup = {
+            byName: {},
+            byIdentity: new Map(),
+        };
         entries.forEach(([alias, RegisteredSlotComponent]) => {
             const 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: ${RegisteredSlotComponent}`);
-                return;
+                aliasLookup.byIdentity.set(RegisteredSlotComponent, alias);
+                aliasLookup.byName[alias] = alias;
             }
-            aliasLookup[slotName] = alias;
+            else
+                aliasLookup.byName[slotName] = alias;
         });
         return aliasLookup;
     }, [Caller.Slots]);
@@ -93,7 +100,6 @@ const useSlots = (children, Caller) => {
             ...((_a = Caller.requiredSlotAliases) !== null && _a !== void 0 ? _a : [])
         ];
         react_1.default.Children.forEach(children, (_child) => {
-            var _a;
             const child = _child;
             if (!child) {
                 invalidChildren.push(child);
@@ -111,16 +117,13 @@ const useSlots = (children, Caller) => {
                 return;
             }
             const slotAlias = (() => {
-                var _a;
                 const slotName = (0, exports.getComponentSlotName)(child.type, child);
-                return slotName ? (_a = slotsAliasLookup[slotName]) !== null && _a !== void 0 ? _a : null : null;
+                const alias = slotName
+                    ? slotsAliasLookup.byName[slotName]
+                    : slotsAliasLookup.byIdentity.get(child.type);
+                return alias !== null && alias !== void 0 ? alias : null;
             })();
             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);
                 }
@@ -131,6 +134,7 @@ const useSlots = (children, Caller) => {
             else
                 unmatchedChildren.push(child);
         });
+        /** @todo Type keys as NonNullable if included in this array. */
         requiredSlotAliases.forEach((slotAlias) => {
             if (!slotNodes[slotAlias]) {
                 (0, errors_1.throwDevError)(`Missing required slot "${String(slotAlias)}".`);

package/build/_cjs/slots/types.d.ts

@@ -18,12 +18,7 @@ export type DisplayNamedComponent<TComponent extends ComponentType<any> = Compon
     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;
+    slotName?: TName;
 }
 /**
  * A child component used to insert content into a specific slot in the parent component.

package/build/helpers/debounce/index.d.ts

@@ -0,0 +1,55 @@
+interface IDebouncedFunction<TFunc extends AnyFunction> {
+    (...args: Parameters<TFunc>): Promise<ReturnType<TFunc>>;
+    /**
+     * Called internally to trigger the callback with the most recent args
+     * after the delay expires. Can be used to manually trigger the callback
+     * before the normal delay time. If no pending call exists, flush() becomes a no-op.
+     */
+    flush: (isEager?: true) => void;
+}
+export interface IDelayConfig {
+    /**
+     * A non-zero delay in milliseconds.
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * The 'last-call' value specifies that the timer should be applied from the time of the most recent call.
+     * That means each new call while a delay is active will reset the timer, thereby extending the delay.
+     * In other words, it is a "time after inactivity" delay.
+     * Specifying 'first-call' instead will make it use a "time after initial call" delay strategy.
+     */
+    anchor?: 'first-call' | 'last-call';
+    /**
+     * Controls eager execution behavior:
+     * - `false`: Initial call waits for the delay period before executing.
+     * - `'no-queue'`: Initial call fires immediately. Subsequent calls during the delay period
+     *   are skipped and return the promise from the initial call. Ideal for preventing
+     *   duplicate actions like clicking a download button twice.
+     * - `'with-queue'`: Initial call fires immediately. After the initial flush, the promise
+     *   is discarded. The next call during the delay period creates a new workorder that will
+     *   be maintained until the next flush. Ideal for debounced search inputs and similar use cases.
+     * @default 'with-queue'
+     */
+    eager?: false | 'no-queue' | 'with-queue';
+}
+interface IDebounce {
+    <TFunc extends AnyFunction>(callback: TFunc, delayConfigArg?: number | IDelayConfig): IDebouncedFunction<TFunc>;
+}
+/**
+ * Wraps the provided function with a debounce.
+ *
+ * Behavior during the delay period depends on the `eager` configuration:
+ * - `eager: false`: All calls wait for the delay. New calls overwrite the existing call.
+ * - `eager: 'no-queue'`: First call fires immediately. Subsequent calls during the delay
+ *   period are skipped and return the same promise as the initial call.
+ * - `eager: 'with-queue'` (default): First call fires immediately. After the flush, the next call
+ *   creates a new workorder that will be fired after the delay. New calls overwrite queued args.
+ *
+ * Once the timer expires, the most recent call is fired.
+ *
+ * Note: Returned promises may resolve with values from calls made with
+ * different arguments. Avoid using this for functions where argument-specific results matter.
+ */
+export declare const debounce: IDebounce;
+export {};

package/build/helpers/debounce/index.js

@@ -0,0 +1,110 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * Wraps the provided function with a debounce.
+ *
+ * Behavior during the delay period depends on the `eager` configuration:
+ * - `eager: false`: All calls wait for the delay. New calls overwrite the existing call.
+ * - `eager: 'no-queue'`: First call fires immediately. Subsequent calls during the delay
+ *   period are skipped and return the same promise as the initial call.
+ * - `eager: 'with-queue'` (default): First call fires immediately. After the flush, the next call
+ *   creates a new workorder that will be fired after the delay. New calls overwrite queued args.
+ *
+ * Once the timer expires, the most recent call is fired.
+ *
+ * Note: Returned promises may resolve with values from calls made with
+ * different arguments. Avoid using this for functions where argument-specific results matter.
+ */
+export const debounce = (...init) => {
+    const [callback, delayArg] = init;
+    const delayConfig = {
+        delay: 1000,
+        anchor: 'first-call',
+        eager: 'with-queue',
+    };
+    if (typeof delayArg === 'number') {
+        delayConfig.delay = delayArg || 1000;
+    }
+    else if (delayArg) {
+        for (const _key in delayArg) {
+            const key = _key;
+            if (delayArg[key] !== undefined) {
+                // @ts-expect-error
+                delayConfig[key] = delayArg[key];
+            }
+        }
+    }
+    let nextCall = null;
+    const debouncedFunction = (...args) => {
+        let currentWork;
+        if (nextCall) {
+            if (delayConfig.eager !== 'no-queue') {
+                nextCall = Object.assign(Object.assign({}, nextCall), { args, work: nextCall.work || Promise.withResolvers() });
+            }
+            currentWork = nextCall.work;
+            if (delayConfig.anchor === 'last-call') {
+                clearTimeout(nextCall.timeout);
+                nextCall.timeout = setTimeout(debouncedFunction.flush, delayConfig.delay);
+            }
+        }
+        else {
+            // No active delay, create new call
+            nextCall = {
+                args,
+                timeout: setTimeout(debouncedFunction.flush, delayConfig.delay),
+                work: Promise.withResolvers(),
+            };
+            currentWork = nextCall.work;
+            // Fire immediately if eager mode is enabled (no-queue or with-queue)
+            if (delayConfig.eager !== false) {
+                debouncedFunction.flush(true);
+            }
+        }
+        if (!currentWork) {
+            throw new Error('[debounce] `currentWork` was not initialized.');
+        }
+        return currentWork.promise;
+    };
+    debouncedFunction.flush = (isEager) => {
+        if (!(nextCall === null || nextCall === void 0 ? void 0 : nextCall.args)) {
+            nextCall = null;
+            // console.log('Queue is empty. Nothing to flush.');
+            return;
+        }
+        // Capture queue values.
+        const { resolve, reject } = nextCall.work || {};
+        const args = nextCall.args;
+        // Clear the queue for new debounced calls.
+        if (isEager) {
+            delete nextCall.args;
+            if (delayConfig.eager === 'with-queue') {
+                delete nextCall.work;
+            }
+        }
+        else {
+            nextCall = null;
+        }
+        // Execute the pending call.
+        (() => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            try {
+                const result = (_a = (yield callback(...args))) !== null && _a !== void 0 ? _a : {};
+                result.__debounceFlushedWithArgs = args;
+                resolve === null || resolve === void 0 ? void 0 : resolve(result);
+            }
+            catch (_reason) {
+                const reason = _reason !== null && _reason !== void 0 ? _reason : {};
+                reason.__debounceFlushedWithArgs = args;
+                reject === null || reject === void 0 ? void 0 : reject(reason);
+            }
+        }))();
+    };
+    return debouncedFunction;
+};

package/build/helpers/debounce/react.d.ts

@@ -0,0 +1,7 @@
+import { debounce } from './index.js';
+type TDebounceConfig = Exclude<Parameters<typeof debounce>[1], number>;
+type TDelayConfig = number | TDebounceConfig & {
+    staging?: boolean;
+};
+export declare function useDebouncedState<T extends any>(init: T, config: TDelayConfig): readonly [T, (value: T) => void, T];
+export {};

package/build/helpers/debounce/react.js

@@ -0,0 +1,16 @@
+import { useCallback, useState } from 'react.js';
+import { debounce } from './index.js';
+export function useDebouncedState(init, config) {
+    const [debouncedValue, setDebouncedValue] = useState(init);
+    const [stagedValue, setStagedValue] = useState(init);
+    const enableStaging = typeof config === 'object' && config.staging === true;
+    const debounceArgs = [setDebouncedValue, config];
+    const debouncedSetter = useCallback(debounce(...debounceArgs), debounceArgs);
+    const setter = useCallback((value) => {
+        if (enableStaging) {
+            setStagedValue(value);
+        }
+        debouncedSetter(value);
+    }, [enableStaging, debouncedSetter]);
+    return [debouncedValue, setter, stagedValue];
+}

package/build/helpers/object-gate.d.ts

@@ -0,0 +1,74 @@
+type TRecord = Record<keyof any, any>;
+declare namespace _ObjectGate {
+    /** Configure property access for a proxy object. */
+    interface IGateConfig<TSource extends TRecord> {
+        /**
+         * The keys to be exposed for read access through the proxy.
+         * Defaults to [`Reflect.ownKeys(source)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/ownKeys) —
+         * so if omitted, all ["_own properties_"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties)
+         * present on the source at
+         * instantiation time will be exposed for read access through the proxy.
+         */
+        getters?: Readonly<Array<keyof TSource>>;
+        /**
+         * Keys that should definitely be omitted from read access,
+         * even if they are present in {@link getters}.
+         * @default [] - Empty array.
+         */
+        gettersExclude?: Readonly<Array<keyof TSource>>;
+        /**
+         * The keys to be exposed for write access through the proxy.
+         * This defaults to an empty array, so if omitted, none of the gated
+         * properties will be writeable.
+         * @default [] - Empty array.
+         */
+        setters?: Readonly<Array<keyof TSource> | true>;
+        /**
+         * Keys that should definitely be omitted from write access,
+         * even if they are present in {@link setters}.
+         * @default [] - Empty array.
+         */
+        settersExclude?: Readonly<Array<keyof TSource>>;
+    }
+    type Params<TSource extends TRecord> = [
+        /**
+         * The target object, where the actual values are stored.
+         * Keys on the created gate object will use JavaScript getters to return
+         * the real-time value of the same key from this source object.
+         */
+        source: TSource,
+        /** @see {@link IGateConfig} */
+        config?: Readonly<IGateConfig<TSource>>
+    ];
+    class Gate<TSource extends TRecord> {
+        constructor(...params: Params<TSource>);
+    }
+    interface IConstructor {
+        new <TOutput extends Partial<TSource>, TSource extends TRecord>(...params: _ObjectGate.Params<TSource>): TOutput;
+    }
+}
+/**
+ * Creates a new object that acts as a real-time proxy
+ * for the {@link _ObjectGate.Params | `source`} object.
+ * This lets you prevent access to some properties, effectively making them private,
+ * while selectively exposing access to only the properties you specify
+ * in the {@link _ObjectGate.IGateConfig.getters | `getters`} config option.
+ *
+ * The exposed properties are read-only by default,
+ * exposing only a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description)
+ * with no corresponding [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set#description).
+ *
+ * The {@link _ObjectGate.Params | `config`} argument also lets you selectively allow
+ * write access to specific properties through the
+ * {@link _ObjectGate.IGateConfig.setters | `setters`} config option.
+ *
+ * Unlike [`structuredClone`](https://developer.mozilla.org/docs/Web/API/Window/structuredClone)
+ * this doesn't return a _copy_ of the `source` object.
+ *
+ * Instead, it returns a _**Real-time proxy**_. This means that a value is read
+ * from the source object each time a property is accessed through the proxy.
+ * So accessing a property through the gate object is guaranteed to always return
+ * the latest value.
+ */
+export declare const ObjectGate: _ObjectGate.IConstructor;
+export {};

package/build/helpers/object-gate.js

@@ -0,0 +1,64 @@
+var _ObjectGate;
+(function (_ObjectGate) {
+    class Gate {
+        constructor(...params) {
+            var _a, _b, _c, _d;
+            const [source, config] = params;
+            const getters = (_a = config === null || config === void 0 ? void 0 : config.getters) !== null && _a !== void 0 ? _a : Reflect.ownKeys(source);
+            const gettersExclude = (_b = config === null || config === void 0 ? void 0 : config.gettersExclude) !== null && _b !== void 0 ? _b : [];
+            const setters = (config === null || config === void 0 ? void 0 : config.setters) === true
+                ? getters
+                : ((_c = config === null || config === void 0 ? void 0 : config.setters) !== null && _c !== void 0 ? _c : []);
+            const settersExclude = (_d = config === null || config === void 0 ? void 0 : config.settersExclude) !== null && _d !== void 0 ? _d : [];
+            getters.forEach((_key) => {
+                const key = _key;
+                if (gettersExclude.includes(key))
+                    return;
+                Object.defineProperty(this, key, {
+                    enumerable: true,
+                    configurable: true,
+                    get() {
+                        return source[key];
+                    },
+                });
+            });
+            setters.forEach((_key) => {
+                const key = _key;
+                if (settersExclude.includes(key))
+                    return;
+                Object.defineProperty(this, key, {
+                    enumerable: true,
+                    set(value) {
+                        source[key] = value;
+                    },
+                });
+            });
+        }
+    }
+    _ObjectGate.Gate = Gate;
+    ;
+})(_ObjectGate || (_ObjectGate = {}));
+/**
+ * Creates a new object that acts as a real-time proxy
+ * for the {@link _ObjectGate.Params | `source`} object.
+ * This lets you prevent access to some properties, effectively making them private,
+ * while selectively exposing access to only the properties you specify
+ * in the {@link _ObjectGate.IGateConfig.getters | `getters`} config option.
+ *
+ * The exposed properties are read-only by default,
+ * exposing only a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description)
+ * with no corresponding [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set#description).
+ *
+ * The {@link _ObjectGate.Params | `config`} argument also lets you selectively allow
+ * write access to specific properties through the
+ * {@link _ObjectGate.IGateConfig.setters | `setters`} config option.
+ *
+ * Unlike [`structuredClone`](https://developer.mozilla.org/docs/Web/API/Window/structuredClone)
+ * this doesn't return a _copy_ of the `source` object.
+ *
+ * Instead, it returns a _**Real-time proxy**_. This means that a value is read
+ * from the source object each time a property is accessed through the proxy.
+ * So accessing a property through the gate object is guaranteed to always return
+ * the latest value.
+ */
+export const ObjectGate = _ObjectGate.Gate;

package/build/slots/hook.js

@@ -23,6 +23,9 @@ export const getComponentSlotName = (TargetComponent, child) => {
     else if ('displayName' in TargetComponent) {
         return TargetComponent.displayName;
     }
+    else if ('name' in TargetComponent) {
+        return TargetComponent.name;
+    }
     return undefined;
 };
 export const isPortalChild = (child) => {
@@ -43,14 +46,18 @@ export const isPortalChild = (child) => {
 export const useSlots = (children, Caller) => {
     const slotsAliasLookup = useMemo(() => {
         const entries = Object.entries(Caller.Slots);
-        const aliasLookup = {};
+        const aliasLookup = {
+            byName: {},
+            byIdentity: new Map(),
+        };
         entries.forEach(([alias, RegisteredSlotComponent]) => {
             const slotName = getComponentSlotName(RegisteredSlotComponent);
             if (!slotName) {
-                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: ${RegisteredSlotComponent}`);
-                return;
+                aliasLookup.byIdentity.set(RegisteredSlotComponent, alias);
+                aliasLookup.byName[alias] = alias;
             }
-            aliasLookup[slotName] = alias;
+            else
+                aliasLookup.byName[slotName] = alias;
         });
         return aliasLookup;
     }, [Caller.Slots]);
@@ -64,7 +71,6 @@ export const useSlots = (children, Caller) => {
             ...((_a = Caller.requiredSlotAliases) !== null && _a !== void 0 ? _a : [])
         ];
         React.Children.forEach(children, (_child) => {
-            var _a;
             const child = _child;
             if (!child) {
                 invalidChildren.push(child);
@@ -82,16 +88,13 @@ export const useSlots = (children, Caller) => {
                 return;
             }
             const slotAlias = (() => {
-                var _a;
                 const slotName = getComponentSlotName(child.type, child);
-                return slotName ? (_a = slotsAliasLookup[slotName]) !== null && _a !== void 0 ? _a : null : null;
+                const alias = slotName
+                    ? slotsAliasLookup.byName[slotName]
+                    : slotsAliasLookup.byIdentity.get(child.type);
+                return alias !== null && alias !== void 0 ? alias : null;
             })();
             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);
                 }
@@ -102,6 +105,7 @@ export const useSlots = (children, Caller) => {
             else
                 unmatchedChildren.push(child);
         });
+        /** @todo Type keys as NonNullable if included in this array. */
         requiredSlotAliases.forEach((slotAlias) => {
             if (!slotNodes[slotAlias]) {
                 throwDevError(`Missing required slot "${String(slotAlias)}".`);

package/build/slots/types.d.ts

@@ -18,12 +18,7 @@ export type DisplayNamedComponent<TComponent extends ComponentType<any> = Compon
     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;
+    slotName?: TName;
 }
 /**
  * A child component used to insert content into a specific slot in the parent component.

package/package.json

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