From eeaa52bf5d99993ea925234123c908417c8e2f93 Mon Sep 17 00:00:00 2001 From: Wolfsblvt Date: Fri, 10 May 2024 04:48:30 +0200 Subject: [PATCH] Expand global.d.ts with code docs - docs and syntax for toastr - docs and syntax for Fuse - docs and syntax for select2 - docs and syntax for sortable --- public/global.d.ts | 598 ++++++++++++++++++++++++++++++++++- public/scripts/power-user.js | 10 +- 2 files changed, 599 insertions(+), 9 deletions(-) diff --git a/public/global.d.ts b/public/global.d.ts index f23e05597..0d9f93fc2 100644 --- a/public/global.d.ts +++ b/public/global.d.ts @@ -1,7 +1,6 @@ // Global namespace modules declare var DOMPurify; declare var droll; -declare var Fuse; declare var Handlebars; declare var hljs; declare var localforage; @@ -11,7 +10,6 @@ declare var Popper; declare var showdown; declare var showdownKatex; declare var SVGInject; -declare var toastr; declare var Readability; declare var isProbablyReaderable; declare var ePub; @@ -23,12 +21,604 @@ interface JQuery { pagination(method: string, options?: any): JQuery; pagination(options?: any): JQuery; transition(options?: any): JQuery; - select2(options?: any): JQuery; - sortable(options?: any): JQuery; autocomplete(options?: any): JQuery; autocomplete(method: string, options?: any): JQuery; slider(options?: any): JQuery; slider(method: string, func: string, options?: any): JQuery; cropper(options?: any): JQuery; izoomify(options?: any): JQuery; + + //#region select2 + + /** + * Initializes or modifies a select2 instance with provided options + * + * @param options - Configuration options for the select2 instance + * @returns The jQuery object for chaining + */ + select2(options?: Select2Options): JQuery; + + /** + * Retrieves data currently selected in the select2 instance + * + * @param field - A string specifying the 'data' method + * @returns An array of selected items + */ + select2(field: 'data'): any[]; + + /** + * Calls the specified select2 method + * + * @param method - The name of the select2 method to invoke + * @returns The jQuery object for chaining + */ + select2(method: 'open' | 'close' | 'destroy' | 'focus' | 'val', value?: any): JQuery; + + //#endregion + + //#region sortable + + /** + * Initializes or updates a sortable instance with the provided options + * + * @param options - Configuration options for the sortable instance + * @returns The jQuery object for chaining + */ + sortable(options?: SortableOptions): JQuery; + + /** + * Calls a sortable method to perform actions on the instance + * + * @param method - The name of the sortable method to invoke + * @returns The jQuery object for chaining + */ + sortable(method: 'destroy' | 'disable' | 'enable' | 'refresh' | 'toArray'): JQuery; + + /** + * Retrieves the sortable's instance object. If the element does not have an associated instance, undefined is returned. + * + * @returns The instance of the sortable object + */ + sortable(method: 'instance'): object; + + /** + * Retrieves the current option value for the specified option + * + * @param method - The string 'option' to retrieve an option value + * @param optionName - The name of the option to retrieve + * @returns The value of the specified option + */ + sortable(method: 'option', optionName: string): any; + + /** + * Sets the value of the specified option + * + * @param method - The string 'option' to set an option value + * @param optionName - The name of the option to set + * @param value - The value to assign to the option + * @returns The jQuery object for chaining + */ + sortable(method: 'option', optionName: string, value: any): JQuery; + + /** + * Sets multiple options using an object + * + * @param method - The string 'option' to set options + * @param options - An object containing multiple option key-value pairs + * @returns The jQuery object for chaining + */ + sortable(method: 'option', options: SortableOptions): JQuery; + + //#endregion } + +/** + * Toastr is a global object for displaying toast notifications + */ +declare var toastr: { + /** + * Show a success toast notification. + * + * @param message - The main message to display in the notification. + * @param title - An optional title for the notification. + * @param optionsOverride - Optional object to override default options. + */ + success(message: string, title?: string, optionsOverride?: object): void; + + /** + * Show an info toast notification. + * + * @param message - The main message to display in the notification. + * @param title - An optional title for the notification. + * @param optionsOverride - Optional object to override default options. + */ + info(message: string, title?: string, optionsOverride?: object): void; + + /** + * Show a warning toast notification. + * + * @param message - The main message to display in the notification. + * @param title - An optional title for the notification. + * @param optionsOverride - Optional object to override default options. + */ + warning(message: string, title?: string, optionsOverride?: object): void; + + /** + * Show an error toast notification. + * + * @param message - The main message to display in the notification. + * @param title - An optional title for the notification. + * @param optionsOverride - Optional object to override default options. + */ + error(message: string, title?: string, optionsOverride?: object): void; + + /** + * Clear one or all toast notifications. + * + * @param toast - Optional specific toast to clear. + * @param clearOptions - Optional object to override default clear options. + */ + clear(toast?: any, clearOptions?: object): void; + + // Add any other `toastr` methods or properties here. +}; + + +//#region Fuse + +/** + * Fuse.js provides fast and flexible fuzzy searching + * @constructor + * @param list - The list of items to search through + * @param options - Configuration options for the search algorithm + */ +declare var Fuse: { + new(list: any[], options?: FuseOptions): FuseInstance; +}; + +/** Instead of providing a (nested) key as a string, an object can be defined that can specify weight and a custom get function */ +interface FuseKey { + /** + * The name of they key. Supports nested paths. + */ + name: string; + /** + * You can allocate a weight to keys to give them higher (or lower) values in search results. The weight value has to be greater than 0. When a weight isn't provided, it will default to 1. + * @default 1 + */ + weight?: number; + /** + * Function to retrieve an object's value at the specified path. The default searches nested paths. + * @default (obj: T, path: string | string[]) => string | string[] + */ + getFn?: (any) => string; +} + +/** Configuration options for the Fuse search algorithm */ +interface FuseOptions { + /** + * List of keys that will be searched. Supports nested paths, weighted search, and searching in arrays of strings and objects. + * @default [] + */ + keys?: string[] | FuseKey[]; + + /** + * How much distance one character can be from another to be considered a match. + * @default 100 + */ + distance?: number; + + /** + * At what point the match algorithm gives up. A threshold of 0.0 requires a perfect match, while 1.0 matches everything. + * @default 0.6 + */ + threshold?: number; + + /** + * Whether the score should be included in the result set. A score of 0 indicates a perfect match, while a score of 1 indicates a complete mismatch. + * @default false + */ + includeScore?: boolean; + + /** + * Indicates whether comparisons should be case-sensitive. + * @default false + */ + isCaseSensitive?: boolean; + + /** + * Whether the matches should be included in the result set. When true, each record in the result set will include the indices of matched characters. + * @default false + */ + includeMatches?: boolean; + + /** + * Only matches whose length exceeds this value will be returned. + * @default 1 + */ + minMatchCharLength?: number; + + /** + * Whether to sort the result list by score. + * @default true + */ + shouldSort?: boolean; + + /** + * When true, the matching function will continue to the end of a search pattern even if a perfect match has already been found. + * @default false + */ + findAllMatches?: boolean; + + /** + * Determines approximately where in the text the pattern is expected to be found. + * @default 0 + */ + location?: number; + + /** + * When true, search will ignore location and distance, so it won't matter where in the string the pattern appears. + * @default false + */ + ignoreLocation?: boolean; + + /** + * When true, it enables the use of Unix-like search commands. + * @default false + */ + useExtendedSearch?: boolean; + + /** + * Function to retrieve an object's value at the specified path. The default searches nested paths. + * @default (obj: T, path: string | string[]) => string | string[] + */ + getFn?: (obj: any, path: string | string[]) => string | string[]; + + /** + * Function to sort the results. The default sorts by ascending relevance score. + * @default (a, b) => number + */ + sortFn?: (a: any, b: any) => number; + + /** + * When true, the calculation for the relevance score will ignore the field-length norm. + * @default false + */ + ignoreFieldNorm?: boolean; + + /** + * Determines how much the field-length norm affects scoring. 0 is equivalent to ignoring the field-length norm, while higher values increase the effect. + * @default 1 + */ + fieldNormWeight?: number; +} + + +/** Represents an individual Fuse search result */ +interface FuseResult { + /** The original item that was matched */ + item: any; + /** The index of the item from the original input collection that was searched */ + refIndex: number; + /** The search score, where 0 is a perfect match and 1 is the worst */ + score?: number; + /** Optional list of matched search keys */ + matches?: Array<{ key: string; indices: [number, number][] }>; +} + +/** Represents a Fuse instance, used for performing searches */ +interface FuseInstance { + /** + * Searches through the list using the specified query. + * @param query - The search term or phrase to use + * @returns An array of search results matching the query + */ + search(query: string): FuseResult[]; +} + +//#endregion + +//#region select2 + +/** Options for configuring a select2 instance */ +interface Select2Options { + /** + * Provides support for ajax data sources + * @param params - Parameters including the search term + * @param callback - A callback function to handle the results + * @default null + */ + ajax?: { + url: string; + dataType?: string; + delay?: number; + data?: (params: any) => any; + processResults?: (data: any, params: any) => any; + } | { transport: (params, success, failure) => any }; + + /** + * Provides support for clearable selections + * @default false + */ + allowClear?: boolean; + + /** + * See Using Select2 with AMD or CommonJS loaders + * @default './i18n/' + */ + amdLanguageBase?: string; + + /** + * Controls whether the dropdown is closed after a selection is made + * @default true + */ + closeOnSelect?: boolean; + + /** + * Allows rendering dropdown options from an array + * @default null + */ + data?: object[]; + + /** + * Used to override the built-in DataAdapter + * @default SelectAdapter + */ + dataAdapter?: SelectAdapter; + + /** + * Enable debugging messages in the browser console + * @default false + */ + debug?: boolean; + + /** + * Sets the dir attribute on the selection and dropdown containers to indicate the direction of the text + * @default 'ltr' + */ + dir?: string; + + /** + * When set to true, the select control will be disabled + * @default false + */ + disabled?: boolean; + + /** + * Used to override the built-in DropdownAdapter + * @default DropdownAdapter + */ + dropdownAdapter?: DropdownAdapter; + + /** + * @default false + */ + dropdownAutoWidth?: boolean; + + /** + * Adds additional CSS classes to the dropdown container. The helper :all: can be used to add all CSS classes present on the original element + * @default '' + */ + selectionCssClass?: string; + + /** + * Implements automatic selection when the dropdown is closed + * @default false + */ + selectOnClose?: boolean; + + sorter?: function; + + /** + * When set to `true`, allows the user to create new tags that aren't pre-populated + * Used to enable free text responses + * @default false + */ + tags?: boolean | object[]; + + /** + * Customizes the way that search results are rendered + * @param item - The item object to format + * @returns The formatted representation + * @default null + */ + templateResult?: (item: any) => JQuery | string; + + /** + * Customizes the way that selections are rendered + * @param item - The selected item object to format + * @returns The formatted representation + * @default null + */ + templateSelection?: (item: any) => JQuery | string; + + /** + * Allows you to set the theme + * @default 'default' + */ + theme?: string; + + /** + * A callback that handles automatic tokenization of free-text entry + * @default null + */ + tokenizer?: (input: { _type: string, term: string }, selection: { options: object }, callback: (Select2Option) => any) => { term: string }; + + /** + * The list of characters that should be used as token separators + * @default null + */ + tokenSeparators?: string[]; + + /** + * Supports customization of the container width + * @default 'resolve' + */ + width?: string; + + /** + * If true, resolves issue for multiselects using closeOnSelect: false that caused the list of results to scroll to the first selection after each select/unselect + * @default false + */ + scrollAfterSelect?: boolean; + + /** + * Extends Select2 v4 plugin by adding an option to set a placeholder for the 'search' input field + * [Custom Field] + * @default '' + */ + searchInputPlaceholder?: string; + + /** + * Extends select2 plugin by adding a custom css class for the 'searcH' input field + * [Custom Field] + * @default '' + */ + searchInputCssClass?: string; +} + +//#endregion + +//#region sortable + +/** Options for configuring a sortable instance */ +interface SortableOptions { + /** + * When set, prevents the sortable items from being dragged unless clicked with a delay + * @default 0 + */ + delay?: number; + + /** + * Class name for elements to handle sorting. Elements with this class can be dragged to sort. + * @default '' + */ + handle?: string; + + /** + * Whether to allow sorting between different connected lists + * @default false + */ + connectWith?: string | boolean; + + /** + * Function called when sorting starts + * @param event - The event object + * @param ui - The UI object containing the helper and position information + */ + start?: (event: Event, ui: SortableUI) => void; + + /** + * Function called when sorting stops + * @param event - The event object + * @param ui - The UI object containing the helper and position information + */ + stop?: (event: Event, ui: SortableUI) => void; + + /** + * Function called when sorting updates + * @param event - The event object + * @param ui - The UI object containing the helper and position information + */ + update?: (event: Event, ui: SortableUI) => void; + + /** + * Specifies which items inside the element should be sortable + * @default '> *' + */ + items?: string; +} + +/** UI object passed to sortable event handlers */ +interface SortableUI { + /** jQuery object representing the helper element */ + helper: JQuery; + /** The current position of the helper element */ + position: { top: number; left: number }; + /** Original position of the helper element */ + originalPosition: { top: number; left: number }; + /** jQuery object representing the item being sorted */ + item: JQuery; + /** The placeholder element used during sorting */ + placeholder: JQuery; +} + +//#endregion diff --git a/public/scripts/power-user.js b/public/scripts/power-user.js index 0bdcf5e94..ec2a5868e 100644 --- a/public/scripts/power-user.js +++ b/public/scripts/power-user.js @@ -1865,7 +1865,7 @@ function highlightDefaultContext() { /** * Fuzzy search characters by a search term * @param {string} searchValue - The search term - * @returns {{item?: *, refIndex: number, score: number}[]} Results as items with their score + * @returns {FuseResult[]} Results as items with their score */ export function fuzzySearchCharacters(searchValue) { // @ts-ignore @@ -1898,7 +1898,7 @@ export function fuzzySearchCharacters(searchValue) { * Fuzzy search world info entries by a search term * @param {*[]} data - WI items data array * @param {string} searchValue - The search term - * @returns {{item?: *, refIndex: number, score: number}[]} Results as items with their score + * @returns {FuseResult[]} Results as items with their score */ export function fuzzySearchWorldInfo(data, searchValue) { // @ts-ignore @@ -1927,7 +1927,7 @@ export function fuzzySearchWorldInfo(data, searchValue) { * Fuzzy search persona entries by a search term * @param {*[]} data - persona data array * @param {string} searchValue - The search term - * @returns {{item?: *, refIndex: number, score: number}[]} Results as items with their score + * @returns {FuseResult[]} Results as items with their score */ export function fuzzySearchPersonas(data, searchValue) { data = data.map(x => ({ key: x, name: power_user.personas[x] ?? '', description: power_user.persona_descriptions[x]?.description ?? '' })); @@ -1951,7 +1951,7 @@ export function fuzzySearchPersonas(data, searchValue) { /** * Fuzzy search tags by a search term * @param {string} searchValue - The search term - * @returns {{item?: *, refIndex: number, score: number}[]} Results as items with their score + * @returns {FuseResult[]} Results as items with their score */ export function fuzzySearchTags(searchValue) { // @ts-ignore @@ -1973,7 +1973,7 @@ export function fuzzySearchTags(searchValue) { /** * Fuzzy search groups by a search term * @param {string} searchValue - The search term - * @returns {{item?: *, refIndex: number, score: number}[]} Results as items with their score + * @returns {FuseResult[]} Results as items with their score */ export function fuzzySearchGroups(searchValue) { // @ts-ignore