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

package/Base/index.d.ts

@@ -0,0 +1,336 @@
+/**
+ * @typedef {typeof Base} BaseConstructor
+ * @typedef {(Base) => Promise<BaseConstructor | { default: BaseConstructor }>} BaseAsyncConstructor
+ * @typedef {{ [name:string]: any }} BaseOptions
+ * @typedef {{ [name:string]: HTMLElement | HTMLElement[] }} BaseRefs
+ * @typedef {{ [nameOrSelector:string]: Base[] | Promise<Base>[] }} BaseChildren
+ * @typedef {{ [nameOrSelector:string]: BaseConstructor | BaseAsyncConstructor }} BaseConfigComponents
+ * @typedef {import('./managers/OptionsManager').OptionsSchema} BaseConfigOptions
+ * @typedef {import('./managers/ServicesManager.js').ServiceName} ServiceName
+ */
+/**
+ * @typedef {Object} BaseConfig
+ * @property {string} name
+ * @property {boolean} [debug]
+ * @property {boolean} [log]
+ * @property {string[]} [refs]
+ * @property {string[]} [emits]
+ * @property {BaseConfigComponents} [components]
+ * @property {BaseConfigOptions} [options]
+ */
+/**
+ * @typedef {{
+ *   $el?: HTMLElement,
+ *   $options?: BaseOptions,
+ *   $refs?: BaseRefs,
+ *   $children?: { [name:string]: Base | Promise<Base> },
+ * }} BaseTypeParameter
+ */
+/**
+ * @typedef {Object} Managers
+ * @property {typeof ChildrenManager} ChildrenManager
+ * @property {typeof EventsManager} EventsManager
+ * @property {typeof OptionsManager} OptionsManager
+ * @property {typeof RefsManager} RefsManager
+ * @property {typeof ServicesManager} ServicesManager
+ */
+/**
+ * Base class.
+ * @template {BaseTypeParameter} [BaseInterface={ $el: HTMLElement, $options: BaseOptions, $refs: BaseRefs, $children: { [name:string]: Base | Promise<Base> } }]
+ */
+export default class Base<BaseInterface extends BaseTypeParameter = {
+    $el: HTMLElement;
+    $options: BaseOptions;
+    $refs: BaseRefs;
+    $children: {
+        [name: string]: Base<any> | Promise<Base<any>>;
+    };
+}> extends EventTarget {
+    /**
+     * This is a Base instance.
+     * @type {boolean}
+     * @readonly
+     */
+    static readonly $isBase: boolean;
+    /**
+     * @type {BaseConfig}
+     */
+    static config: BaseConfig;
+    /**
+     * Factory method to generate multiple instance of the class.
+     *
+     * @param  {string}      nameOrSelector The selector on which to mount each instance.
+     * @returns {Array<Base>}                A list of the created instance.
+     */
+    static $factory(nameOrSelector: string): Array<Base>;
+    /**
+     * Class constructor where all the magic takes place.
+     *
+     * @param {HTMLElement} element The component's root element dd.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * The instance parent.
+     * @type {Base}
+     */
+    $parent: Base;
+    /**
+     * The instance id.
+     * @type {string}
+     */
+    $id: string;
+    /**
+     * The root element.
+     * @type {BaseInterface['$el'] & HTMLElement & { __base__?: WeakMap<BaseConstructor, Base | 'terminated'> }}
+     */
+    $el: BaseInterface['$el'] & HTMLElement & {
+        __base__?: WeakMap<BaseConstructor, Base | 'terminated'>;
+    };
+    /**
+     * The state of the component.
+     * @type {boolean}
+     */
+    $isMounted: boolean;
+    /**
+     * Store the event handlers.
+     *
+     * @type {Map<string, Set<EventListenerOrEventListenerObject>>}
+     */
+    __eventHandlers: Map<string, Set<EventListenerOrEventListenerObject>>;
+    /**
+     * Get the root instance of the app.
+     * @returns {Base}
+     */
+    get $root(): Base<{
+        $el: HTMLElement;
+        $options: BaseOptions;
+        $refs: BaseRefs;
+        $children: {
+            [name: string]: Base<any> | Promise<Base<any>>;
+        };
+    }>;
+    /**
+     * Merge configuration with the parents' configurations.
+     *
+     * @returns {BaseConfig}
+     */
+    get __config(): BaseConfig;
+    /**
+     * @type {ServicesManager}
+     */
+    __services: ServicesManager;
+    /**
+     * @type {ServicesManager}
+     */
+    get $services(): ServicesManager;
+    /**
+     * @type {RefsManager & BaseInterface['$refs'] & BaseRefs}
+     */
+    __refs: RefsManager & BaseInterface['$refs'] & BaseRefs;
+    /**
+     * @returns {RefsManager & BaseInterface['$refs'] & BaseRefs}
+     */
+    get $refs(): RefsManager & BaseInterface["$refs"] & BaseRefs;
+    /**
+     * @type {OptionsManager & BaseInterface['$options'] & BaseOptions}
+     */
+    __options: OptionsManager & BaseInterface['$options'] & BaseOptions;
+    /**
+     * @returns {OptionsManager & BaseInterface['$options'] & BaseOptions}
+     */
+    get $options(): OptionsManager & BaseInterface["$options"] & BaseOptions;
+    /**
+     * @type {ChildrenManager & { [key in keyof BaseInterface['$children']]: Array<BaseInterface['$children'][key]> } & BaseChildren}
+     */
+    __children: ChildrenManager & (BaseInterface["$children"] extends infer T ? { [key in keyof T]: BaseInterface["$children"][key][]; } : never) & BaseChildren;
+    /**
+     * @returns {ChildrenManager & { [key in keyof BaseInterface['$children']]: Array<BaseInterface['$children'][key]> } & BaseChildren}
+     */
+    get $children(): ChildrenManager & (BaseInterface["$children"] extends infer T_1 ? { [key_1 in keyof T_1]: BaseInterface["$children"][key_1][]; } : never) & BaseChildren;
+    /**
+     * @type {EventsManager}
+     */
+    __events: EventsManager;
+    /**
+     * Small helper to log stuff.
+     *
+     * @returns {(...args: any) => void}
+     */
+    get $log(): (...args: any) => void;
+    /**
+     * Small helper to debug information.
+     *
+     * @returns {(...args:any) => void}
+     */
+    get __debug(): (...args: any) => void;
+    /**
+     * Get manager constructors.
+     *
+     * @returns {Managers}
+     */
+    get __managers(): Managers;
+    /**
+     * Call an instance method and emit corresponding events.
+     *
+     * @param {string} method
+     * @param {any[]} args
+     * @returns {any}
+     */
+    __callMethod(method: string, ...args: any[]): any;
+    /**
+     * 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;
+    /**
+     * Trigger the `mounted` callback.
+     * @returns {this}
+     */
+    $mount(): this;
+    /**
+     * Update the instance children.
+     * @returns {this}
+     */
+    $update(): this;
+    /**
+     * Trigger the `destroyed` callback.
+     * @returns {this}
+     */
+    $destroy(): this;
+    /**
+     * Terminate a child instance when it is not needed anymore.
+     * @returns {void}
+     */
+    $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.
+     *
+     * @returns {BaseConstructor}
+     */
+    get __ctor(): typeof Base;
+    /**
+     * 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: any[]): void;
+}
+export type BaseConstructor = typeof Base;
+export type BaseAsyncConstructor = (Base: any) => Promise<BaseConstructor | {
+    default: BaseConstructor;
+}>;
+export type BaseOptions = {
+    [name: string]: any;
+};
+export type BaseRefs = {
+    [name: string]: HTMLElement | HTMLElement[];
+};
+export type BaseChildren = {
+    [nameOrSelector: string]: Base<{
+        $el: HTMLElement;
+        $options: BaseOptions;
+        $refs: BaseRefs;
+        $children: {
+            [name: string]: Base<any> | Promise<Base<any>>;
+        };
+    }>[] | Promise<Base<{
+        $el: HTMLElement;
+        $options: BaseOptions;
+        $refs: BaseRefs;
+        $children: {
+            [name: string]: Base<any> | Promise<Base<any>>;
+        };
+    }>>[];
+};
+export type BaseConfigComponents = {
+    [nameOrSelector: string]: typeof Base | BaseAsyncConstructor;
+};
+export type BaseConfigOptions = import('./managers/OptionsManager').OptionsSchema;
+export type ServiceName = import('./managers/ServicesManager.js').ServiceName;
+export type BaseConfig = {
+    name: string;
+    debug?: boolean;
+    log?: boolean;
+    refs?: string[];
+    emits?: string[];
+    components?: BaseConfigComponents;
+    options?: BaseConfigOptions;
+};
+export type BaseTypeParameter = {
+    $el?: HTMLElement;
+    $options?: BaseOptions;
+    $refs?: BaseRefs;
+    $children?: {
+        [name: string]: Base<{
+            $el: HTMLElement;
+            $options: BaseOptions;
+            $refs: BaseRefs;
+            $children: {
+                [name: string]: Base<any> | Promise<Base<any>>;
+            };
+        }> | Promise<Base<{
+            $el: HTMLElement;
+            $options: BaseOptions;
+            $refs: BaseRefs;
+            $children: {
+                [name: string]: Base<any> | Promise<Base<any>>;
+            };
+        }>>;
+    };
+};
+export type Managers = {
+    ChildrenManager: typeof ChildrenManager;
+    EventsManager: typeof EventsManager;
+    OptionsManager: typeof OptionsManager;
+    RefsManager: typeof RefsManager;
+    ServicesManager: typeof ServicesManager;
+};
+import ServicesManager from "./managers/ServicesManager.js";
+import RefsManager from "./managers/RefsManager.js";
+import OptionsManager from "./managers/OptionsManager.js";
+import ChildrenManager from "./managers/ChildrenManager.js";
+import EventsManager from "./managers/EventsManager.js";

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]: OptionObject | OptionType;
+};
+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;
+}