@gesslar/toolkit 1.0.3 → 1.2.0

package/src/index.js

@@ -1,6 +1,7 @@
 // Browser-compatible utilities (pure JS)
 export {default as Collection} from "./browser/lib/Collection.js"
 export {default as Data} from "./browser/lib/Data.js"
+export {default as Disposable} from "./browser/lib/Disposable.js"
 export {default as Type} from "./browser/lib/TypeSpec.js"
 export {default as Valid} from "./lib/Valid.js"
 

package/src/lib/Contract.js

@@ -230,7 +230,7 @@ export default class Contract {
   /**
    * Get the provider terms (if any)
    *
-   * @returns {Terms|null} Provider terms
+   * @returns {import("./Terms.js").default|null} Provider terms
    */
   get providerTerms() {
     return this.#providerTerms
@@ -239,7 +239,7 @@ export default class Contract {
   /**
    * Get the consumer terms (if any)
    *
-   * @returns {Terms|null} Consumer terms
+   * @returns {import("./Terms.js").default|null} Consumer terms
    */
   get consumerTerms() {
     return this.#consumerTerms

package/src/types/browser/index.d.ts

@@ -1,5 +1,8 @@
 export { default as Collection } from "./lib/Collection.js";
 export { default as Data } from "./lib/Data.js";
+export { default as Disposable } from "./lib/Disposable.js";
+export { default as HTML } from "./lib/HTML.js";
+export { default as Notify } from "./lib/Notify.js";
 export { default as Sass } from "./lib/Sass.js";
 export { default as Tantrum } from "./lib/Tantrum.js";
 export { default as Type } from "./lib/TypeSpec.js";

package/src/types/browser/lib/Base.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Base helper for UI classes that want centralized event lifecycles.
+ * Tracks listener disposer functions and registered DOM elements so subclasses
+ * can easily tear down on removal.
+ */
+export default class Base extends Disposable {
+    /**
+     * Assigns an HTMLElement to this object.
+     *
+     * @throws {Error} If there is already one assigned.
+     */
+    set element(element: HTMLElement);
+    /**
+     * Returns the HTMLElement associated with this object.
+     *
+     * @returns {HTMLElement} The HTMLElement associated with this object.
+     */
+    get element(): HTMLElement;
+    /**
+     * Cleans up registered disposers and emits a removal event for subscribers.
+     *
+     * @returns {void}
+     */
+    remove(): void;
+    /**
+     * Registers a Notify listener and tracks its disposer for later cleanup.
+     *
+     * @param {string} eventName - Event to subscribe to.
+     * @param {(evt: Event) => void} func - Handler to invoke.
+     * @param {HTMLElement | Window} [element] - Target element; defaults to window.
+     * @param {boolean | object} [options] - addEventListener options.
+     */
+    registerOn(eventName: string, func: (evt: Event) => void, element?: HTMLElement | Window, options?: boolean | object): void;
+    /**
+     * Resolves a DOM element and optionally registers listener functions on it.
+     * Each listener's return value is treated as a disposer and tracked.
+     *
+     * @param {string} elementId - Selector passed to querySelector.
+     * @param {((element: Element) => (void | (() => void))) | Array<(element: Element) => (void | (() => void))>} [listenerFunctions] - One or more listener initializers.
+     */
+    initialiseElement(elementId: string, listenerFunctions?: ((element: Element) => (void | (() => void))) | Array<(element: Element) => (void | (() => void))>): void;
+    #private;
+}
+import Disposable from "./Disposable.js";
+//# sourceMappingURL=Base.d.ts.map

package/src/types/browser/lib/Base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Base.d.ts","sourceRoot":"","sources":["../../../browser/lib/Base.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IAcE;;;;OAIG;IACH,qBAWa,WAAW,EALvB;IAED;;;;OAIG;IACH,eAFa,WAAW,CAIvB;IAED;;;;OAIG;IACH,UAFa,IAAI,CAQhB;IAED;;;;;;;OAOG;IACH,sBALW,MAAM,QACN,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,YACpB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,QAM1B;IAED;;;;;;OAMG;IACH,6BAHW,MAAM,sBACN,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,QA8B5G;;CACF;uBA5GsB,iBAAiB"}

package/src/types/browser/lib/Disposable.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Simple lifecycle helper that tracks disposer callbacks.
+ * Register any teardown functions and call dispose() to run them in reverse.
+ */
+export default class Disposable {
+    /**
+     * Registers a disposer callback to be executed when disposed.
+     *
+     * @param {() => void} disposer - Cleanup callback.
+     * @returns {() => void} Function to unregister the disposer.
+     */
+    registerDisposer(disposer: () => void): () => void;
+    /**
+     * Runs all registered disposers in reverse order.
+     *
+     * @returns {void}
+     */
+    dispose(): void;
+    /**
+     * Whether disposal has run.
+     *
+     * @returns {boolean} True when dispose() has already been called.
+     */
+    get disposed(): boolean;
+    /**
+     * Read-only list of registered disposers.
+     *
+     * @returns {Array<() => void>} Snapshot of disposer callbacks.
+     */
+    get disposers(): Array<() => void>;
+    #private;
+}
+//# sourceMappingURL=Disposable.d.ts.map

package/src/types/browser/lib/Disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Disposable.d.ts","sourceRoot":"","sources":["../../../browser/lib/Disposable.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAIE;;;;;OAKG;IACH,2BAHW,MAAM,IAAI,GACR,MAAM,IAAI,CAStB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAoBhB;IAED;;;;OAIG;IACH,gBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,KAAK,CAAC,MAAM,IAAI,CAAC,CAI7B;;CAQF"}

package/src/types/browser/lib/HTML.d.ts

@@ -0,0 +1,38 @@
+export default class HTML {
+    /**
+     * Lightweight HTML helper utilities for browser contexts.
+     *
+     * @param {object|(() => unknown)} domPurify - Optional DOMPurify instance or factory.
+     */
+    constructor(domPurify?: object | (() => unknown));
+    /**
+     * Fetches an HTML fragment and returns the contents inside the <body> tag when present.
+     *
+     * @param {string} url - Location of the HTML resource to load.
+     * @param {boolean} filterBodyContent - If true, returns only content found between the <body> tags. Defaults to false.
+     * @returns {Promise<string>} Sanitized HTML string or empty string on missing content.
+     */
+    loadHTML(url: string, filterBodyContent?: boolean): Promise<string>;
+    /**
+     * Sanitizes arbitrary HTML using DOMPurify.
+     *
+     * @param {string} text - HTML string to sanitize. Defaults to "".
+     * @returns {string} Sanitized HTML.
+     */
+    sanitise(text?: string): string;
+    /**
+     * Sanitizes an HTML string and replaces the element's children with the result.
+     *
+     * @param {Element} element - Target element to replace content within.
+     * @param {string} htmlString - HTML string to sanitize and insert.
+     */
+    setHTMLContent(element: Element, htmlString: string): void;
+    /**
+     * Removes all child nodes from the given element.
+     *
+     * @param {Element} element - Element to clear.
+     */
+    clearHTMLContent(element: Element): void;
+    #private;
+}
+//# sourceMappingURL=HTML.d.ts.map

package/src/types/browser/lib/HTML.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HTML.d.ts","sourceRoot":"","sources":["../../../browser/lib/HTML.js"],"names":[],"mappings":"AAGA;IAGE;;;;OAIG;IACH,wBAFW,MAAM,GAAC,CAAC,MAAM,OAAO,CAAC,EAIhC;IAED;;;;;;OAMG;IACH,cAJW,MAAM,sBACN,OAAO,GACL,OAAO,CAAC,MAAM,CAAC,CAmB3B;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,cACP,MAAM,QA+BhB;IAED;;;;OAIG;IACH,0BAFW,OAAO,QAmBjB;;CAwBF"}

package/src/types/browser/lib/Notify.d.ts

@@ -0,0 +1,60 @@
+declare const _default: {
+    /** @type {string} Display name for debugging. */
+    name: string;
+    /**
+     * Emits a CustomEvent without expecting a return value.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Value assigned to `event.detail`.
+     * @param {boolean | NotifyEventOptions} [options] - CustomEvent options or boolean to set `bubbles`.
+     * @returns {void}
+     */
+    emit(type: string, payload?: unknown, options?: boolean | NotifyEventOptions): void;
+    /**
+     * Emits a CustomEvent and returns the detail for simple request/response flows.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Value assigned to `event.detail`.
+     * @param {boolean | NotifyEventOptions} [options] - CustomEvent options or boolean to set `bubbles`.
+     * @returns {unknown} The detail placed on the CustomEvent.
+     */
+    request(type: string, payload?: unknown, options?: boolean | NotifyEventOptions): unknown;
+    /**
+     * Registers a listener for the given event type on an HTMLElement (or
+     * window, if not specified).
+     *
+     * @param {string} type - Event name to listen for.
+     * @param {(evt: Notify) => void} handler - Listener callback.
+     * @param {HTMLElement | Window} [element] - The object to which to attach the handler. Default is window.
+     * @param {boolean | object} [options] - Options to pass to addEventListener.
+     * @returns {() => void} Dispose function to unregister the handler.
+     */
+    on(type: string, handler: (evt: /*elided*/ any) => void, element?: HTMLElement | Window, options?: boolean | object): () => void;
+    /**
+     * Removes a previously registered listener for the given event type.
+     *
+     * @param {string} type - Event name to remove.
+     * @param {(evt: Notify) => void} handler - Listener callback to detach.
+     * @param {HTMLElement | Window} [element] - The object from which to remove the handler. Default is window.
+     * @param {boolean | object} [options] - Options to pass to removeEventListener.
+     * @returns {void}
+     */
+    off(type: string, handler: (evt: /*elided*/ any) => void, element?: HTMLElement | Window, options?: boolean | object): void;
+    "__#private@#buildEventInit"(detail: any, options: any): any;
+};
+export default _default;
+export type NotifyEventOptions = {
+    /**
+     * - Whether the event bubbles up the DOM tree.
+     */
+    bubbles?: boolean;
+    /**
+     * - Whether the event can be canceled.
+     */
+    cancelable?: boolean;
+    /**
+     * - Whether the event can cross the shadow DOM boundary.
+     */
+    composed?: boolean;
+};
+//# sourceMappingURL=Notify.d.ts.map

package/src/types/browser/lib/Notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../browser/lib/Notify.js"],"names":[],"mappings":";IAaE,iDAAiD;UAAtC,MAAM;IAGjB;;;;;;;OAOG;eAJQ,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,IAAI;IAOjB;;;;;;;OAOG;kBAJQ,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,OAAO;IASpB;;;;;;;;;OASG;aALQ,MAAM,WACN,CAAC,GAAG,gBAAQ,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,MAAM,IAAI;IAcvB;;;;;;;;OAQG;cALQ,MAAM,WACN,CAAC,GAAG,gBAAQ,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,IAAI;;;;;;;;cAjEL,OAAO;;;;iBACP,OAAO;;;;eACP,OAAO"}

package/src/types/browser/lib/vendor/dompurify.esm.d.ts

@@ -0,0 +1,29 @@
+export { purify as default };
+declare function purify(root: any): {
+    (root: any): /*elided*/ any;
+    version: string;
+    removed: any[];
+    isSupported: boolean;
+    sanitize(dirty: any, ...args: any[]): any;
+    setConfig(...args: any[]): void;
+    clearConfig(): void;
+    isValidAttribute(tag: any, attr: any, value: any): boolean;
+    addHook(entryPoint: any, hookFunction: any): void;
+    removeHook(entryPoint: any, hookFunction: any): any;
+    removeHooks(entryPoint: any): void;
+    removeAllHooks(): void;
+};
+declare namespace purify {
+    let version: string;
+    let removed: any[];
+    let isSupported: boolean;
+    function sanitize(dirty: any, ...args: any[]): any;
+    function setConfig(...args: any[]): void;
+    function clearConfig(): void;
+    function isValidAttribute(tag: any, attr: any, value: any): boolean;
+    function addHook(entryPoint: any, hookFunction: any): void;
+    function removeHook(entryPoint: any, hookFunction: any): any;
+    function removeHooks(entryPoint: any): void;
+    function removeAllHooks(): void;
+}
+//# sourceMappingURL=dompurify.esm.d.ts.map

package/src/types/browser/lib/vendor/dompurify.esm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dompurify.esm.d.ts","sourceRoot":"","sources":["../../../../browser/lib/vendor/dompurify.esm.js"],"names":[],"mappings":";AA0UE;;;;;;;;;;;;;EAA+C;;;;;IA+9B/C,mDAiJC;IACD,yCAIC;IACD,6BAGC;IACD,oEAUC;IACD,2DAMC;IACD,6DAQC;IACD,4CAEC;IACD,gCAEC"}

package/src/types/index.d.ts

@@ -1,5 +1,6 @@
 export { default as Collection } from "./browser/lib/Collection.js";
 export { default as Data } from "./browser/lib/Data.js";
+export { default as Disposable } from "./browser/lib/Disposable.js";
 export { default as Type } from "./browser/lib/TypeSpec.js";
 export { default as Valid } from "./lib/Valid.js";
 export { default as Sass } from "./lib/Sass.js";

package/src/types/lib/Contract.d.ts

@@ -51,15 +51,15 @@ export default class Contract {
     /**
      * Get the provider terms (if any)
      *
-     * @returns {Terms|null} Provider terms
+     * @returns {import("./Terms.js").default|null} Provider terms
      */
-    get providerTerms(): Terms | null;
+    get providerTerms(): import("./Terms.js").default | null;
     /**
      * Get the consumer terms (if any)
      *
-     * @returns {Terms|null} Consumer terms
+     * @returns {import("./Terms.js").default|null} Consumer terms
      */
-    get consumerTerms(): Terms | null;
+    get consumerTerms(): import("./Terms.js").default | null;
     /**
      * Get the contract validator
      *

package/src/types/lib/Contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Contract.d.ts","sourceRoot":"","sources":["../../lib/Contract.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IAwBE;;;;;;;OAOG;IACH,oDAgBC;IAED;;;;;;;;OAQG;IACH,uBANW,MAAM,mBACN,MAAM,cACN,OAAO,KAAK,EAAE,gBAAgB,GAAC,IAAI,gBAEjC,QAAQ,CAsBpB;IAxED;;;;;;;OAOG;IACH,2BALW,OAAO,YAAY,EAAE,KAAK,iBAC1B,OAAO,YAAY,EAAE,KAAK,cAElC;QAAsD,KAAK,GAAnD,GAAmC;KAC7C,EAQA;IA6FD;;;;;;OAMG;IACH,eAJW,MAAM,GACJ,OAAO,CAsBnB;IAsED;;;;OAIG;IACH,oBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,qBAFa,KAAK,GAAC,IAAI,CAItB;IAED;;;;OAIG;IACH,qBAFa,KAAK,GAAC,IAAI,CAItB;IAED;;;;OAIG;IACH,iBAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;;CACF"}
+{"version":3,"file":"Contract.d.ts","sourceRoot":"","sources":["../../lib/Contract.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IAwBE;;;;;;;OAOG;IACH,oDAgBC;IAED;;;;;;;;OAQG;IACH,uBANW,MAAM,mBACN,MAAM,cACN,OAAO,KAAK,EAAE,gBAAgB,GAAC,IAAI,gBAEjC,QAAQ,CAsBpB;IAxED;;;;;;;OAOG;IACH,2BALW,OAAO,YAAY,EAAE,KAAK,iBAC1B,OAAO,YAAY,EAAE,KAAK,cAElC;QAAsD,KAAK,GAAnD,GAAmC;KAC7C,EAQA;IA6FD;;;;;;OAMG;IACH,eAJW,MAAM,GACJ,OAAO,CAsBnB;IAsED;;;;OAIG;IACH,oBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,qBAFa,OAAO,YAAY,EAAE,OAAO,GAAC,IAAI,CAI7C;IAED;;;;OAIG;IACH,qBAFa,OAAO,YAAY,EAAE,OAAO,GAAC,IAAI,CAI7C;IAED;;;;OAIG;IACH,iBAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;;CACF"}

package/src/types/lib/Disposable.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Simple lifecycle helper that tracks disposer callbacks.
+ * Register any teardown functions and call dispose() to run them in reverse.
+ */
+export default class Disposable {
+    /**
+     * Registers a disposer callback to be executed when disposed.
+     *
+     * @param {() => void} disposer - Cleanup callback.
+     * @returns {() => void} Function to unregister the disposer.
+     */
+    registerDisposer(disposer: () => void): () => void;
+    /**
+     * Runs all registered disposers in reverse order.
+     *
+     * @returns {void}
+     */
+    dispose(): void;
+    /**
+     * Whether disposal has run.
+     *
+     * @returns {boolean} True when dispose() has already been called.
+     */
+    get disposed(): boolean;
+    /**
+     * Read-only list of registered disposers.
+     *
+     * @returns {Array<() => void>} Snapshot of disposer callbacks.
+     */
+    get disposers(): Array<() => void>;
+    #private;
+}
+//# sourceMappingURL=Disposable.d.ts.map

package/src/types/lib/Disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Disposable.d.ts","sourceRoot":"","sources":["../../lib/Disposable.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAIE;;;;;OAKG;IACH,2BAHW,MAAM,IAAI,GACR,MAAM,IAAI,CAStB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAoBhB;IAED;;;;OAIG;IACH,gBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,KAAK,CAAC,MAAM,IAAI,CAAC,CAI7B;;CAQF"}