@sv443-network/userutils 7.0.1 → 7.2.0

package/dist/lib/Dialog.d.ts

@@ -0,0 +1,104 @@
+import { NanoEmitter } from "./NanoEmitter.js";
+export declare const defaultDialogCss: string;
+/** ID of the last opened (top-most) dialog */
+export declare let currentDialogId: string | null;
+/** IDs of all currently open dialogs, top-most first */
+export declare const openDialogs: string[];
+export declare const defaultStrings: {
+    closeDialogTooltip: string;
+};
+/** Options passed to the Dialog constructor */
+export interface DialogOptions {
+    /** ID that gets added to child element IDs - has to be unique and conform to HTML ID naming rules! */
+    id: string;
+    /** Target and max width of the dialog in pixels */
+    width: number;
+    /** Target and max height of the dialog in pixels */
+    height: number;
+    /** Whether the dialog should close when the background is clicked - defaults to true */
+    closeOnBgClick?: boolean;
+    /** Whether the dialog should close when the escape key is pressed - defaults to true */
+    closeOnEscPress?: boolean;
+    /** Whether the dialog should be destroyed when it's closed - defaults to false */
+    destroyOnClose?: boolean;
+    /** Whether the dialog should be unmounted when it's closed - defaults to true - superseded by destroyOnClose */
+    unmountOnClose?: boolean;
+    /** Whether all listeners should be removed when the dialog is destroyed - defaults to true */
+    removeListenersOnDestroy?: boolean;
+    /** Whether the dialog should have a smaller overall appearance - defaults to false */
+    small?: boolean;
+    /** Where to align or anchor the dialog vertically - defaults to "center" */
+    verticalAlign?: "top" | "center" | "bottom";
+    /** Strings used in the dialog (used for translations) - defaults to the default English strings */
+    strings?: Partial<typeof defaultStrings>;
+    /** CSS to apply to the dialog - defaults to the {@linkcode defaultDialogCss} */
+    dialogCss?: string;
+    /** Called to render the body of the dialog */
+    renderBody: () => HTMLElement | Promise<HTMLElement>;
+    /** Called to render the header of the dialog - leave undefined for a blank header */
+    renderHeader?: () => HTMLElement | Promise<HTMLElement>;
+    /** Called to render the footer of the dialog - leave undefined for no footer */
+    renderFooter?: () => HTMLElement | Promise<HTMLElement>;
+    /** Called to render the close button of the dialog - leave undefined for no close button */
+    renderCloseBtn?: () => HTMLElement | Promise<HTMLElement>;
+}
+/** Creates and manages a modal dialog element */
+export declare class Dialog extends NanoEmitter<{
+    /** Emitted just **after** the dialog is closed */
+    close: () => void;
+    /** Emitted just **after** the dialog is opened */
+    open: () => void;
+    /** Emitted just **after** the dialog contents are rendered */
+    render: () => void;
+    /** Emitted just **after** the dialog contents are cleared */
+    clear: () => void;
+    /** Emitted just **after** the dialog is destroyed and **before** all listeners are removed */
+    destroy: () => void;
+}> {
+    /** Options passed to the dialog in the constructor */
+    readonly options: DialogOptions;
+    /** ID that gets added to child element IDs - has to be unique and conform to HTML ID naming rules! */
+    readonly id: string;
+    /** Strings used in the dialog (used for translations) */
+    strings: typeof defaultStrings;
+    protected dialogOpen: boolean;
+    protected dialogMounted: boolean;
+    constructor(options: DialogOptions);
+    /** Call after DOMContentLoaded to pre-render the dialog and invisibly mount it in the DOM */
+    mount(): Promise<HTMLElement | void>;
+    /** Closes the dialog and clears all its contents (unmounts elements from the DOM) in preparation for a new rendering call */
+    unmount(): void;
+    /** Clears the DOM of the dialog and then renders it again */
+    remount(): Promise<void>;
+    /**
+     * Opens the dialog - also mounts it if it hasn't been mounted yet
+     * Prevents default action and immediate propagation of the passed event
+     */
+    open(e?: MouseEvent | KeyboardEvent): Promise<HTMLElement | void>;
+    /** Closes the dialog - prevents default action and immediate propagation of the passed event */
+    close(e?: MouseEvent | KeyboardEvent): void;
+    /** Returns true if the dialog is currently open */
+    isOpen(): boolean;
+    /** Returns true if the dialog is currently mounted */
+    isMounted(): boolean;
+    /** Clears the DOM of the dialog and removes all event listeners */
+    destroy(): void;
+    /** Returns the ID of the top-most dialog (the dialog that has been opened last) */
+    static getCurrentDialogId(): string | null;
+    /** Returns the IDs of all currently open dialogs, top-most first */
+    static getOpenDialogs(): string[];
+    protected getString(key: keyof typeof defaultStrings): string;
+    /** Called once to attach all generic event listeners */
+    protected attachListeners(bgElem: HTMLElement): void;
+    /**
+     * Adds generic, accessible interaction listeners to the passed element.
+     * All listeners have the default behavior prevented and stop propagation (for keyboard events only as long as the captured key is valid).
+     * @param listenerOptions Provide a {@linkcode listenerOptions} object to configure the listeners
+     */
+    protected onInteraction<TElem extends HTMLElement>(elem: TElem, listener: (evt: MouseEvent | KeyboardEvent) => void, listenerOptions?: AddEventListenerOptions & {
+        preventDefault?: boolean;
+        stopPropagation?: boolean;
+    }): void;
+    /** Returns the dialog content element and all its children */
+    protected getDialogContent(): Promise<HTMLElement>;
+}

package/dist/lib/NanoEmitter.d.ts

@@ -0,0 +1,20 @@
+import { type DefaultEvents, type Emitter, type EventsMap, type Unsubscribe } from "nanoevents";
+export interface NanoEmitterOptions {
+    /** If set to true, allows emitting events through the public method emit() */
+    publicEmit: boolean;
+}
+/** Class that can be extended or instantiated by itself to create an event emitter with helper methods and a strongly typed event map */
+export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
+    protected readonly events: Emitter<TEvtMap>;
+    protected eventUnsubscribes: Unsubscribe[];
+    protected emitterOptions: NanoEmitterOptions;
+    constructor(options?: Partial<NanoEmitterOptions>);
+    /** Subscribes to an event - returns a function that unsubscribes the event listener */
+    on<TKey extends keyof TEvtMap>(event: TKey | "_", cb: TEvtMap[TKey]): () => void;
+    /** Subscribes to an event and calls the callback or resolves the Promise only once */
+    once<TKey extends keyof TEvtMap>(event: TKey | "_", cb?: TEvtMap[TKey]): Promise<Parameters<TEvtMap[TKey]>>;
+    /** Emits an event on this instance - Needs `publicEmit` to be set to true in the constructor! */
+    emit<TKey extends keyof TEvtMap>(event: TKey, ...args: Parameters<TEvtMap[TKey]>): boolean;
+    /** Unsubscribes all event listeners */
+    unsubscribeAll(): void;
+}

package/dist/lib/colors.d.ts

@@ -0,0 +1,18 @@
+/** Converts a hex color string to a tuple of RGB values */
+export declare function hexToRgb(hex: string): [red: number, green: number, blue: number];
+/** Converts RGB values to a hex color string */
+export declare function rgbToHex(red: number, green: number, blue: number, withHash?: boolean, upperCase?: boolean): string;
+/**
+ * Lightens a CSS color value (in hex, RGB or RGBA format) by a given percentage.
+ * Will not exceed the maximum range (00-FF or 0-255).
+ * @returns Returns the new color value in the same format as the input
+ * @throws Throws if the color format is invalid or not supported
+ */
+export declare function lightenColor(color: string, percent: number): string;
+/**
+ * Darkens a CSS color value (in hex, RGB or RGBA format) by a given percentage.
+ * Will not exceed the maximum range (00-FF or 0-255).
+ * @returns Returns the new color value in the same format as the input
+ * @throws Throws if the color format is invalid or not supported
+ */
+export declare function darkenColor(color: string, percent: number): string;

package/dist/lib/crypto.d.ts

@@ -0,0 +1,24 @@
+/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as a base64 string */
+export declare function compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
+/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as an ArrayBuffer */
+export declare function compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
+/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to a string */
+export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
+/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to an ArrayBuffer */
+export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
+/**
+ * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer using the specified {@linkcode algorithm} ("SHA-256" by default).
+ *
+ * ⚠️ Uses the SubtleCrypto API so it needs to run in a secure context (HTTPS).
+ * ⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.
+ */
+export declare function computeHash(input: string | ArrayBuffer, algorithm?: string): Promise<string>;
+/**
+ * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)
+ *
+ * ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
+ * @param length The length of the ID to generate (defaults to 16)
+ * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
+ * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take MUCH longer to generate)
+ */
+export declare function randomId(length?: number, radix?: number, enhancedEntropy?: boolean): string;

package/dist/lib/dom.d.ts

@@ -63,3 +63,11 @@ export declare function observeElementProp<TElem extends Element = HTMLElement,
  * @returns An array of sibling elements
  */
 export declare function getSiblingsFrame<TSibling extends Element = HTMLElement>(refElement: Element, siblingAmount: number, refElementAlignment?: "center-top" | "center-bottom" | "top" | "bottom", includeRef?: boolean): TSibling[];
+/**
+ * Sets the innerHTML property of the provided element without any sanitation or validation.
+ * Uses a [Trusted Types policy](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) on Chromium-based browsers to trick the browser into thinking the HTML is safe.
+ * Use this if the page makes use of the CSP directive `require-trusted-types-for 'script'` and throws a "This document requires 'TrustedHTML' assignment" error on Chromium-based browsers.
+ *
+ * ⚠️ This function does not perform any sanitization and should thus be used with utmost caution, as it can easily lead to XSS vulnerabilities!
+ */
+export declare function setInnerHtmlUnsafe<TElement extends Element = HTMLElement>(element: TElement, html: string): TElement;

package/dist/lib/index.d.ts

@@ -1,9 +1,12 @@
 export * from "./array.js";
+export * from "./crypto.js";
 export * from "./DataStore.js";
 export * from "./DataStoreSerializer.js";
+export * from "./Dialog.js";
 export * from "./dom.js";
 export * from "./math.js";
 export * from "./misc.js";
+export * from "./NanoEmitter.js";
 export * from "./SelectorObserver.js";
 export * from "./translation.js";
 export * from "./types.js";

package/dist/lib/misc.d.ts

@@ -5,6 +5,13 @@ import type { Stringifiable } from "./types.js";
  * @param num If this is an array or NodeList, the amount of items is used
  */
 export declare function autoPlural(word: Stringifiable, num: number | unknown[] | NodeList): string;
+/**
+ * Inserts the passed values into a string at the respective placeholders.
+ * The placeholder format is `%n`, where `n` is the 1-indexed argument number.
+ * @param input The string to insert the values into
+ * @param values The values to insert, in order, starting at `%1`
+ */
+export declare function insertValues(input: string, ...values: Stringifiable[]): string;
 /** Pauses async execution for the specified time in ms */
 export declare function pauseFor(time: number): Promise<void>;
 /**
@@ -23,34 +30,3 @@ export type FetchAdvancedOpts = Omit<RequestInit & Partial<{
 }>, "signal">;
 /** Calls the fetch API with special options like a timeout */
 export declare function fetchAdvanced(input: RequestInfo | URL, options?: FetchAdvancedOpts): Promise<Response>;
-/**
- * Inserts the passed values into a string at the respective placeholders.
- * The placeholder format is `%n`, where `n` is the 1-indexed argument number.
- * @param input The string to insert the values into
- * @param values The values to insert, in order, starting at `%1`
- */
-export declare function insertValues(input: string, ...values: Stringifiable[]): string;
-/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as a base64 string */
-export declare function compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
-/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as an ArrayBuffer */
-export declare function compress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
-/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to a string */
-export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
-/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to an ArrayBuffer */
-export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
-/**
- * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer using the specified {@linkcode algorithm} ("SHA-256" by default).
- *
- * ⚠️ Uses the SubtleCrypto API so it needs to run in a secure context (HTTPS).
- * ⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.
- */
-export declare function computeHash(input: string | ArrayBuffer, algorithm?: string): Promise<string>;
-/**
- * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)
- *
- * ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
- * @param length The length of the ID to generate (defaults to 16)
- * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
- * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take MUCH longer to generate)
- */
-export declare function randomId(length?: number, radix?: number, enhancedEntropy?: boolean): string;

package/dist/lib/types.d.ts

@@ -1,3 +1,13 @@
+export type TrustedTypesPolicy = {
+    createHTML?: (dirty: string) => string;
+};
+declare global {
+    interface Window {
+        trustedTypes: {
+            createPolicy(name: string, policy: TrustedTypesPolicy): TrustedTypesPolicy;
+        };
+    }
+}
 /** Represents any value that is either a string itself or can be converted to one (implicitly and explicitly) because it has a toString() method */
 export type Stringifiable = string | {
     toString(): string;

package/package.json

@@ -1,20 +1,24 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "7.0.1",
+  "version": "7.2.0",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/lib/index.d.ts",
+  "type": "module",
   "scripts": {
     "lint": "tsc --noEmit && eslint .",
     "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
-    "build-all": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run post-build-global && echo Finished building.\"",
+    "build-all": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run build-types && npm run post-build-global && echo Finished building.\"",
     "build": "npm run build-common -- && npm run build-types",
     "post-build-global": "npm run node-ts -- ./tools/post-build-global.mts",
     "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types && echo Finished building.\"",
+    "dev-all": "npm run build-all -- --watch",
+    "update-jsr-version": "npm run node-ts -- ./tools/update-jsr-version.mts",
     "publish-package": "changeset publish",
+    "publish-package-jsr": "npm run update-jsr-version && npx jsr publish",
     "node-ts": "node --no-warnings=ExperimentalWarning --enable-source-maps --loader ts-node/esm",
     "test-serve": "npm run node-ts -- ./test/TestPage/server.mts",
     "test-dev": "cd test/TestScript && npm run dev",
@@ -37,6 +41,9 @@
     "url": "https://github.com/Sv443-Network/UserUtils/issues"
   },
   "homepage": "https://github.com/Sv443-Network/UserUtils",
+  "dependencies": {
+    "nanoevents": "^9.0.0"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.26.2",
     "@types/express": "^4.17.19",