@studiometa/js-toolkit 2.4.4-alpha.0 → 2.4.4-alpha.3

package/Base/index.cjs

@@ -27,7 +27,7 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 
-// packages/js-toolkit/Base/index.js
+// packages/js-toolkit/Base/index.ts
 var Base_exports = {};
 __export(Base_exports, {
   default: () => Base

package/Base/index.d.ts

@@ -0,0 +1,198 @@
+import ChildrenManager from './managers/ChildrenManager.js';
+import RefsManager from './managers/RefsManager.js';
+import ServicesManager from './managers/ServicesManager.js';
+import EventsManager from './managers/EventsManager.js';
+import OptionsManager from './managers/OptionsManager.js';
+export declare type BaseConstructor = typeof Base;
+export declare type BaseAsyncConstructor = (Base: any) => Promise<BaseConstructor | {
+    default: BaseConstructor;
+}>;
+export declare type BaseOptions = {
+    [name: string]: unknown;
+};
+export declare type BaseRefs = {
+    [name: string]: HTMLElement | HTMLElement[];
+};
+export declare type BaseChildren = {
+    [nameOrSelector: string]: Base[] | Promise<Base>[];
+};
+export declare type BaseConfigComponents = {
+    [nameOrSelector: string]: BaseConstructor | BaseAsyncConstructor;
+};
+export declare type BaseConfig = {
+    name: string;
+    debug?: boolean;
+    log?: boolean;
+    refs?: string[];
+    emits?: string[];
+    components?: BaseConfigComponents;
+    options?: import('./managers/OptionsManager').OptionsSchema;
+};
+export declare type BaseTypeParameter = {
+    $el?: HTMLElement;
+    $options?: BaseOptions;
+    $refs?: BaseRefs;
+    $children?: {
+        [name: string]: Base | Promise<Base>;
+    };
+};
+export declare type Managers = {
+    ChildrenManager: typeof ChildrenManager;
+    EventsManager: typeof EventsManager;
+    OptionsManager: typeof OptionsManager;
+    RefsManager: typeof RefsManager;
+    ServicesManager: typeof ServicesManager;
+};
+/**
+ * Base class.
+ */
+export default class Base<T extends BaseTypeParameter = BaseTypeParameter> extends EventTarget {
+    /**
+     * This is a Base instance.
+     */
+    static readonly $isBase: true;
+    /**
+     * The instance parent.
+     */
+    $parent: Base;
+    /**
+     * The instance id.
+     */
+    $id: string;
+    /**
+     * The root element.
+     */
+    $el: T['$el'] & HTMLElement & {
+        __base__?: WeakMap<BaseConstructor, Base | 'terminated'>;
+    };
+    /**
+     * The state of the component.
+     */
+    $isMounted: boolean;
+    /**
+     * Store the event handlers.
+     */
+    __eventHandlers: Map<string, Set<EventListenerOrEventListenerObject>>;
+    /**
+     * Get the root instance of the app.
+     */
+    get $root(): Base;
+    /**
+     * Merge configuration with the parents' configurations.
+     */
+    get __config(): BaseConfig;
+    static config: BaseConfig;
+    __services: ServicesManager;
+    get $services(): ServicesManager;
+    __refs: RefsManager & T['$refs'] & BaseRefs;
+    get $refs(): RefsManager & T['$refs'] & BaseRefs;
+    __options: OptionsManager & T['$options'] & BaseOptions;
+    get $options(): OptionsManager & T['$options'] & BaseOptions;
+    __children: ChildrenManager & {
+        [key in keyof T['$children']]: Array<T['$children'][key]>;
+    } & BaseChildren;
+    get $children(): ChildrenManager & {
+        [key in keyof T['$children']]: Array<T['$children'][key]>;
+    } & BaseChildren;
+    __events: EventsManager;
+    /**
+     * Small helper to log stuff.
+     */
+    get $log(): (...args: any) => void;
+    /**
+     * Small helper to debug information.
+     */
+    get __debug(): (...args: any) => void;
+    /**
+     * Get manager constructors.
+     */
+    get __managers(): Managers;
+    /**
+     * Call an instance method and emit corresponding events.
+     */
+    __callMethod(method: string, ...args: unknown[]): unknown;
+    /**
+     * Test if the given event has been bound to the instance.
+     *
+     * @param   {string} event The event's name.
+     * @returns {boolean}      Wether the given event has been bound or not.
+     */
+    __hasEvent(event: string): boolean;
+    /**
+     * Class constructor where all the magic takes place.
+     *
+     * @param {HTMLElement} element The component's root element dd.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * Trigger the `mounted` callback.
+     */
+    $mount(): this;
+    /**
+     * Update the instance children.
+     */
+    $update(): this;
+    /**
+     * Trigger the `destroyed` callback.
+     */
+    $destroy(): this;
+    /**
+     * Terminate a child instance when it is not needed anymore.
+     */
+    $terminate(): void;
+    /**
+     * Add an emitted event.
+     *
+     * @param   {string} event The event name.
+     * @returns {void}
+     */
+    __addEmits(event: string): void;
+    /**
+     * Remove an emitted event.
+     *
+     * @param   {string} event The event name.
+     * @returns {void}
+     */
+    __removeEmits(event: string): void;
+    /**
+     * Get the instance constructor.
+     */
+    get __ctor(): BaseConstructor;
+    /**
+     * Bind a listener function to an event.
+     *
+     * @param  {string} event
+     *   Name of the event.
+     * @param  {EventListenerOrEventListenerObject} listener
+     *   Function to be called.
+     * @param {boolean|AddEventListenerOptions} [options]
+     *   Options for the `removeEventListener` method.
+     * @returns {() => void}
+     *   A function to unbind the listener.
+     */
+    $on(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
+    /**
+     * Unbind a listener function from an event.
+     *
+     * @param {string} event
+     *   Name of the event.
+     * @param {EventListenerOrEventListenerObject} listener
+     *   Function to be removed.
+     * @param {boolean|EventListenerOptions} [options]
+     *   Options for the `removeEventListener` method.
+     * @returns {void}
+     */
+    $off(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    /**
+     * Emits an event.
+     *
+     * @param  {string} event Name of the event.
+     * @param  {any[]}  args  The arguments to apply to the functions bound to this event.
+     * @returns {void}
+     */
+    $emit(event: string, ...args: unknown[]): void;
+    /**
+     * Factory method to generate multiple instance of the class.
+     */
+    static $factory(nameOrSelector: string): Base[];
+}

package/Base/managers/AbstractManager.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @typedef {import('../index.js').default} Base
+ * @typedef {import('../index.js').BaseConfig} BaseConfig
+ * @typedef {import('./EventsManager.js').default} EventsManager
+ */
+/**
+ * AbstractManager class.
+ */
+export default class AbstractManager {
+    /**
+     * Class constructor.
+     *
+     * @param   {Base} base
+     */
+    constructor(base: Base);
+    /**
+     * @type {Base}
+     */
+    __base: Base;
+    /**
+     * Get the base instance root element.
+     * @returns {HTMLElement}
+     */
+    get __element(): HTMLElement;
+    /**
+     * Get the base instance config.
+     * @returns {BaseConfig}
+     */
+    get __config(): import("../index.js").BaseConfig;
+    /**
+     * Get the events manager.
+     * @returns {EventsManager}
+     */
+    get __eventsManager(): import("./EventsManager.js").default;
+    /**
+     * Prevent a list of properties from being enumerable and writable.
+     * @param   {string[]} properties
+     * @returns {void}
+     */
+    __hideProperties(properties: string[]): void;
+}
+export type Base = import('../index.js').default;
+export type BaseConfig = import('../index.js').BaseConfig;
+export type EventsManager = import('./EventsManager.js').default;

package/Base/managers/ChildrenManager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Children manager.
+ */
+export default class ChildrenManager extends AbstractManager {
+    /**
+     * Store async component promises to avoid calling them multiple times and
+     * waiting for them when they are already resolved.
+     *
+     * @type {WeakMap<BaseAsyncConstructor, { promise: ReturnType<BaseAsyncConstructor>, status: 'pending'|'resolved', ctor?: BaseConstructor }>}
+     */
+    __asyncComponentPromises: WeakMap<BaseAsyncConstructor, {
+        promise: ReturnType<BaseAsyncConstructor>;
+        status: 'pending' | 'resolved';
+        ctor?: BaseConstructor;
+    }>;
+    /**
+     * @returns {string[]}
+     */
+    get registeredNames(): string[];
+    /**
+     * Register instances of all children components.
+     */
+    registerAll(): void;
+    /**
+     * Mount all child component instances.
+     */
+    mountAll(): void;
+    /**
+     * Update all child component instances.
+     */
+    updateAll(): void;
+    /**
+     * Destroy all child component instances.
+     */
+    destroyAll(): void;
+}
+export type Base = import('../index.js').default;
+export type BaseConstructor = import('../index.js').BaseConstructor;
+export type BaseAsyncConstructor = import('../index.js').BaseAsyncConstructor;
+export type BaseConfigComponents = import('../index.js').BaseConfigComponents;
+import AbstractManager from "./AbstractManager.js";

package/Base/managers/EventsManager.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Normalize the given name to PascalCase, such as:
+ *
+ * ```
+ * sentence case          => SentenceCase
+ * lowercase              => Lowercase
+ * UPPERCASE              => Uppercase
+ * kebab-case             => KebabCase
+ * snake_case             => SnakeCase
+ * camelCase              => CamelCase
+ * PascalCase             => PascalCase
+ * .class-selector        => ClassSelector
+ * .bem__selector         => BemSelector
+ * __id-selector          => IdSelector
+ * .complex[class^ ="__"] => ComplexClass
+ * ```
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function normalizeName(name: string): string;
+/**
+ * Normalize the event names from PascalCase to kebab-case.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function normalizeEventName(name: string): string;
+/**
+ * Event management class.
+ * @todo Prevent binding of `onChildOrRefEvent` to the root element
+ * @todo Use event delegation?
+ */
+export default class EventsManager extends AbstractManager {
+    /**
+     * @type {WeakMap}
+     */
+    __methodsCache: WeakMap<any, any>;
+    /**
+     * Event listener object for the root element.
+     *
+     * @type {EventListenerObject}
+     */
+    __rootElementHandler: EventListenerObject;
+    /**
+     * Event listener object for the refs.
+     *
+     * @type {EventListenerObject}
+     */
+    __refsHandler: EventListenerObject;
+    /**
+     * Event listener object for the children.
+     *
+     * @type {EventListenerObject}
+     */
+    __childrenHandler: EventListenerObject;
+    /**
+     * Bind event methods to the given ref elements.
+     *
+     * @param {string} name
+     *   The name of the ref.
+     * @param {HTMLElement[]} elements
+     *   The elements of the ref.
+     * @returns {void}
+     */
+    bindRef(name: string, elements: HTMLElement[]): void;
+    /**
+     * Bind event methods to the given ref elements.
+     *
+     * @param {string} name
+     *   The name of the ref.
+     * @param {HTMLElement[]} elements
+     *   The elements of the ref.
+     * @returns {void}
+     */
+    unbindRef(name: string, elements: HTMLElement[]): void;
+    /**
+     * Bind event methods to the given child instance.
+     *
+     * @param {string} name
+     *   The name of the ref.
+     * @param {Base} instance
+     *   A base instance.
+     * @returns {void}
+     */
+    bindChild(name: string, instance: Base): void;
+    /**
+     * Unbind event methods to the given child instance.
+     *
+     * @param {string} name
+     *   The name of the ref.
+     * @param {Base} instance
+     *   A base instance.
+     * @returns {void}
+     */
+    unbindChild(name: string, instance: Base): void;
+    /**
+     * Bind event methods on the root element.
+     *
+     * @returns {void}
+     */
+    bindRootElement(): void;
+    /**
+     * Unbind event method from the root element.
+     *
+     * @returns {void}
+     */
+    unbindRootElement(): void;
+}
+export type Base = import('../index.js').default;
+export type ChildrenManager = import('./ChildrenManager.js').default;
+import AbstractManager from "./AbstractManager.js";

package/Base/managers/OptionsManager.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Get a property name.
+ *
+ * @param  {string} name
+ * @param  {string} [prefix]
+ * @returns {string}
+ * @protected
+ */
+export function __getPropertyName(name: string, prefix?: string): string;
+/**
+ * Class options to manage options as data attributes on an HTML element.
+ *
+ * @todo Use `MutationObserver` to update values? Might be more performant.
+ */
+export default class OptionsManager extends AbstractManager {
+    /**
+     * An object to store Array and Object values for reference.
+     * @type {Object}
+     * @private
+     */
+    private __values;
+    /**
+     * Default value for the name property.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Default value for the debug property.
+     * @type {boolean}
+     */
+    debug: boolean;
+    /**
+     * Default value for the log property.
+     * @type {boolean}
+     */
+    log: boolean;
+    /**
+     * Get an option value.
+     *
+     * @param   {string} name The option name.
+     * @param   {OptionObject} config The option config.
+     * @returns {any}
+     */
+    get(name: string, config: OptionObject): any;
+    /**
+     * Set an option value.
+     *
+     * @param {string} name The option name.
+     * @param {any} value The new value for this option.
+     * @param {OptionObject} config The option config.
+     */
+    set(name: string, value: any, config: OptionObject): void;
+}
+export type DeepmergeOptions = import('deepmerge').Options;
+export type Base = import('../index.js').default;
+export type BaseConfig = import('../index.js').BaseConfig;
+export type OptionType = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor;
+export type ArrayOption = {
+    type: ArrayConstructor;
+    default?: () => any[];
+    merge?: boolean;
+};
+export type ObjectOption = {
+    type: ObjectConstructor;
+    default?: () => any;
+    merge?: boolean;
+};
+export type StringOption = {
+    type: StringConstructor;
+    default?: string;
+};
+export type NumberOption = {
+    type: NumberConstructor;
+    default?: number;
+};
+export type BooleanOption = {
+    type: BooleanConstructor;
+    default?: boolean;
+};
+export type OptionObject = ArrayOption | ObjectOption | StringOption | NumberOption | BooleanOption;
+export type OptionsSchema = {
+    [name: string]: OptionType | OptionObject;
+};
+export type OptionsInterface = {
+    [optionName: string]: any;
+};
+import AbstractManager from "./AbstractManager.js";

package/Base/managers/RefsManager.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Normalize the name of ref.
+ *
+ * @param {string} name The original name.
+ * @returns {string}     The normalized name.
+ */
+export function normalizeRefName(name: string): string;
+/**
+ * Refs Manager
+ *
+ * @todo Use `MutationObserver` to automatically update refs?
+ */
+export default class RefsManager extends AbstractManager {
+    /**
+     * Get refs configuration.
+     * @returns {string[]}
+     */
+    get __refs(): string[];
+    /**
+     * Register all refs.
+     *
+     * @returns {void}
+     */
+    registerAll(): void;
+    /**
+     * Unregister all refs.
+     *
+     * @returns {void}
+     */
+    unregisterAll(): void;
+}
+import AbstractManager from "./AbstractManager.js";

package/Base/managers/ResponsiveOptionsManager.cjs

@@ -22,7 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// packages/js-toolkit/Base/managers/ResponsiveOptionsManager.js
+// packages/js-toolkit/Base/managers/ResponsiveOptionsManager.ts
 var ResponsiveOptionsManager_exports = {};
 __export(ResponsiveOptionsManager_exports, {
   default: () => ResponsiveOptionsManager

package/Base/managers/ResponsiveOptionsManager.d.ts

@@ -0,0 +1,22 @@
+import OptionsManager from './OptionsManager.js';
+/**
+ * Class options to manage options as data attributes on an HTML element.
+ */
+export default class ResponsiveOptionsManager extends OptionsManager {
+    /**
+     * Get an option value.
+     *
+     * @param   {string} name The option name.
+     * @param   {ResponsiveOptionObject} config The option configuration.
+     * @returns {any}
+     */
+    get(name: any, config: any): any;
+    /**
+     * Set an option value.
+     *
+     * @param {string} name The option name.
+     * @param {any} value The new value.
+     * @param {ResponsiveOptionObject} config The option configuration.
+     */
+    set(name: any, value: any, config: any): void;
+}

package/Base/managers/ServicesManager.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @typedef {typeof SERVICES_MAP & Record<string, () => ServiceInterface>} Services
+ * @typedef {keyof SERVICES_MAP|string} ServiceName
+ */
+/**
+ * Services management for the Base class.
+ *
+ * @todo Add support for disabled services on mount when the method is defined.
+ */
+export default class ServicesManager extends AbstractManager {
+    /**
+     * @type {Record<string, () => ServiceInterface>}
+     */
+    __customServices: Record<string, () => import("../../services").ServiceInterface<any>>;
+    /**
+     * @returns {Record<string, () => ServiceInterface>}
+     */
+    get __services(): Record<string, () => import("../../services").ServiceInterface<any>>;
+    /**
+     * Test if the given service is registered.
+     *
+     * @param  {ServiceName} service The name of the service.
+     * @returns {boolean}
+     */
+    has(service: ServiceName): boolean;
+    /**
+     * Get a service props by name.
+     * @param   {ServiceName} service The name of the service.
+     * @returns {ReturnType<ServiceInterface['props']>}
+     */
+    get(service: ServiceName): ReturnType<import("../../services").ServiceInterface<any>['props']>;
+    /**
+     * Init the given service and bind it to the given instance.
+     *
+     * @param  {ServiceName} service The name of the service.
+     * @returns {() => void}          A function to unbind the service.
+     */
+    enable(service: ServiceName): () => void;
+    /**
+     * Enable all services and return methods to disable them.
+     *
+     * @returns {Function[]}
+     */
+    enableAll(): Function[];
+    /**
+     * Disable all services.
+     *
+     * @returns {void}
+     */
+    disableAll(): void;
+    /**
+     * Disable a service.
+     *
+     * @param  {string} service  The name of the service.
+     * @returns {void}
+     */
+    disable(service: string): void;
+    /**
+     * Toggle a service.
+     * @param  {string}  service    The name of the service.
+     * @param  {boolean} [force] The state to force.
+     * @returns {void}
+     */
+    toggle(service: string, force?: boolean): void;
+    /**
+     * Register a new service to be enabled/disabled.
+     *
+     * @param {string} name
+     *   The name of the service hook.
+     * @param {() => ServiceInterface} useFunction
+     *   The `use...` function for the service.
+     */
+    register(name: string, useFunction: () => import("../../services").ServiceInterface<any>): void;
+    /**
+     * Unregister a new service to be enabled disabled.
+     *
+     * @param {string} name
+     *   The name of the service hook.
+     */
+    unregister(name: string): void;
+}
+export type Base = import('../index').default;
+export type BaseConstructor = import('../index').BaseConstructor;
+export type ServiceInterface = import('../../services').ServiceInterface<any>;
+export type Services = typeof SERVICES_MAP & Record<string, () => import("../../services").ServiceInterface<any>>;
+export type ServiceName = keyof {
+    scrolled: typeof useScroll;
+    resized: typeof useResize;
+    ticked: typeof useRaf;
+    moved: typeof usePointer;
+    keyed: typeof useKey;
+    loaded: typeof useLoad;
+} | string;
+import AbstractManager from "./AbstractManager.js";
+declare namespace SERVICES_MAP {
+    export { useScroll as scrolled };
+    export { useResize as resized };
+    export { useRaf as ticked };
+    export { usePointer as moved };
+    export { useKey as keyed };
+    export { useLoad as loaded };
+}
+import useScroll from "../../services/scroll.js";
+import useResize from "../../services/resize.js";
+import useRaf from "../../services/raf.js";
+import usePointer from "../../services/pointer.js";
+import useKey from "../../services/key.js";
+import useLoad from "../../services/load.js";
+export {};

package/Base/types.cjs

@@ -0,0 +1,18 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/js-toolkit/Base/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);
+if (module.exports.default) module.exports = module.exports.default;