tw5-typed 0.3.10 → 0.4.0

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {

package/src/core.d.ts

@@ -62,10 +62,20 @@ declare module 'tiddlywiki' {
 
     addUnloadTask(task: any);
 
-    /** Convenience function for pushing a tiddler onto the preloading array */
-    preloadTiddler(fields: Record<string, unknown>);
-    /** Convenience function for pushing an array of tiddlers onto the preloading array */
+    /**
+     * Convenience function for pushing a tiddler onto the preloading array.
+     * @param fields - The fields of the tiddler to push.
+     * @description 方便地将一个 tiddler 推入预加载数组中。
+     */
+    preloadTiddler(fields: Record<string, unknown>): void;
+
+    /**
+     * Convenience function for pushing an array of tiddlers onto the preloading array.
+     * @param fieldsArray - The array of tiddlers to push.
+     * @description 方便地将若干 tiddler 数组推入预加载数组中。
+     */
     preloadTiddlerArray(fieldsArray: Array<Record<string, unknown>>): void;
+
     /** External JavaScript can populate this array before calling boot.js in order to preload tiddlers */
     preloadTiddlers: Record<string, Record<string, unknown>>;
 

package/src/index.d.ts

@@ -10,5 +10,5 @@ declare module 'tiddlywiki' {
 }
 
 declare global {
-  export let $tw: ITiddlyWiki;
+  export const $tw: ITiddlyWiki;
 }

package/src/modules/utils/crypto.d.ts

@@ -0,0 +1,32 @@
+declare module '$:/core/modules/utils/crypto.js' {
+  /**
+   * Extracts an encrypted store area from a TiddlyWiki file.
+   * @param text - The text of the TiddlyWiki file.
+   * @returns The extracted encrypted store area, or null if not found.
+   */
+  export function extractEncryptedStoreArea(text: string): string | null;
+
+  /**
+   * Attempts to decrypt an encrypted store area using the provided password.
+   * @param encryptedStoreArea - The encrypted store area to decrypt.
+   * @param password - The password to use for decryption.
+   * @returns An array of decrypted tiddlers, or null if decryption fails.
+   */
+  export function decryptStoreArea(
+    encryptedStoreArea: string,
+    password?: string,
+  ): any[] | null;
+
+  /**
+   * Prompts the user for a password and attempts to decrypt an encrypted store area using the provided password.
+   * @param encryptedStoreArea - The encrypted store area to decrypt.
+   * @param callback - The function to call with the decrypted tiddlers.
+   * @param options - Configuration options.
+   * @param options.usePasswordVault - Whether to store the password in the system password vault.
+   */
+  export function decryptStoreAreaInteractive(
+    encryptedStoreArea: string,
+    callback: (tiddlers: any[]) => void,
+    options?: { usePasswordVault?: boolean },
+  ): void;
+}

package/src/modules/utils/csv.d.ts

@@ -0,0 +1,38 @@
+declare module '$:/core/modules/utils/csv.js' {
+  /**
+   * Information about a CSV cell.
+   * @property {number} start - The start index of the cell in the CSV string.
+   * @property {number} end - The end index of the cell in the CSV string.
+   * @property {boolean} isQuoted - Whether the cell is quoted.
+   * @description CSV 单元格的信息。
+   */
+  interface CellInfo {
+    start: number;
+    end: number;
+    isQuoted: boolean;
+  }
+
+  /**
+   * Parse a CSV string into an array of arrays.
+   * @param text - The CSV string to parse.
+   * @param options - The options for parsing the CSV string.
+   * @returns An array of arrays representing the CSV data.
+   * @description 将 CSV 字符串解析为数组的数组。
+   */
+  export function parseCsvString(
+    text: string,
+    options?: { separator?: string },
+  ): any[][];
+
+  /**
+   * Parse a CSV string with a header row and return an array of objects.
+   * @param text - The CSV string to parse.
+   * @param options - The options for parsing the CSV string.
+   * @returns An array of objects representing the CSV data.
+   * @description 解析具有标题行的 CSV 字符串并返回对象数组。
+   */
+  export function parseCsvStringWithHeader(
+    text: string,
+    options?: { separator?: string },
+  ): object[];
+}

package/src/modules/utils/dom.d.ts

@@ -1,35 +1,226 @@
-declare module 'tiddlywiki' {
-  import { addClass, addEventListeners } from '$:/core/modules/utils/dom.js';
-  interface IUtils {
-    /**
-     * Alternative to `element.classList.add`, add a css class name to an element, see issue for detail.
-     * @link https://github.com/Jermolene/TiddlyWiki5/issues/6475
-     * @param element
-     * @param className
-     */
-    addClass: typeof addClass;
-    /**
-     * Attach specified event handlers to a DOM node
-     * @param domNode: where to attach the event handlers
-     * @param events: array of event handlers to be added (see below)
-     * Each entry in the events array is an object with these properties:
-     * * name: event name of `addEventListener`
-     * * handlerFunction: optional event handler function
-     * * handlerObject: optional event handler object
-     * * handlerMethod: optionally specifies object handler method name (defaults to `handleEvent`)
-     */
-    addEventListeners: typeof addEventListeners;
-    /**
-     * Notifier mechanism
-     */
-    Notifier: typeof Notifier;
-    /**
-     * Copy plain text to the clipboard on browsers that support it.
-     * 
-     * And send a notification to the user if doNotNotify is not true.
-     */
-    copyToClipboard(text: string, option?: { doNotNotify?: boolean }): void;
-  }
+declare module '$:/core/modules/utils/dom.js' {
+  /**
+   * Alternative to `element.classList.add`, add a css class name to an element, see issue for detail.
+   * @link https://github.com/Jermolene/TiddlyWiki5/issues/6475
+   * @param element
+   * @param className
+   */
+  export function addClass(element: Element, className: string): void;
+
+  /**
+   * Alternative to `element.classList.remove`, remove a css class name from an element, see issue for detail.
+   * @link https://github.com/Jermolene/TiddlyWiki5/issues/6475
+   * @param element
+   * @param className
+   */
+  export function removeClass(element: Element, className: string): void;
+
+  /**
+   * Attach specified event handlers to a DOM node
+   * @param domNode: where to attach the event handlers
+   * @param events: array of event handlers to be added (see below)
+   * Each entry in the events array is an object with these properties:
+   * * name: event name of `addEventListener`
+   * * handlerFunction: optional event handler function
+   * * handlerObject: optional event handler object
+   * * handlerMethod: optionally specifies object handler method name (defaults to `handleEvent`)
+   */
+  export function addEventListeners(
+    domNode: Element,
+    events: {
+      handlerFunction?: (event: MouseEvent) => void;
+      handlerMethod?: string;
+      handlerObject?: Widget;
+      name: string;
+    }[],
+  ): void;
+
+  /**
+   * Determines whether element 'a' contains element 'b'.
+   * @param a The parent element.
+   * @param b The child element.
+   * @returns True if 'a' contains 'b', otherwise false.
+   */
+  export function domContains(a: Element, b: Element): boolean;
+
+  /**
+   * Checks if a node matches a specific CSS selector.
+   * @param node The DOM node to check.
+   * @param selector The CSS selector to match against.
+   * @returns True if the node matches the selector, otherwise false.
+   */
+  export function domMatchesSelector(node: Element, selector: string): boolean;
+
+  /**
+   * Safely sets the selection range in an input or textarea element.
+   * @param node The DOM node (input or textarea).
+   * @param start The start position of the selection.
+   * @param end The end position of the selection.
+   * @param direction The direction of the selection.
+   */
+  export function setSelectionRangeSafe(
+    node: HTMLInputElement | HTMLTextAreaElement,
+    start: number,
+    end: number,
+    direction?: 'forward' | 'backward' | 'none',
+  ): void;
+
+  /**
+   * Selects text in an input or textarea by position.
+   * @param node The DOM node (input or textarea).
+   * @param selectFromStart Position from the start of the text.
+   * @param selectFromEnd Position from the end of the text.
+   */
+  export function setSelectionByPosition(
+    node: HTMLInputElement | HTMLTextAreaElement,
+    selectFromStart: number,
+    selectFromEnd: number,
+  ): void;
+
+  /**
+   * Removes all child nodes of a given DOM node.
+   * @param node The parent DOM node.
+   */
+  export function removeChildren(node: Node): void;
+
+  /**
+   * Checks if an element has a specific class.
+   * @param el The element to check.
+   * @param className The class name to look for.
+   * @returns True if the element has the class, otherwise false.
+   */
+  export function hasClass(el: Element, className: string): boolean;
+
+  /**
+   * Toggles a class on an element based on a given condition.
+   * @param el The element to toggle the class on.
+   * @param className The class name to toggle.
+   * @param status If true, adds the class; if false, removes it. If undefined, toggles based on current state.
+   */
+  export function toggleClass(
+    el: Element,
+    className: string,
+    status?: boolean,
+  ): void;
+
+  /**
+   * Gets the first parent element that has scrollbars or uses the body as a fallback.
+   * @param el The starting element to search from.
+   * @returns The first scrollable parent element, or the body if none are found.
+   */
+  export function getScrollContainer(el: Element): Element;
+
+  /**
+   * Get the scroll position of the viewport.
+   * @param srcWindow The source window to get the scroll position from, defaults to the current window if not specified.
+   * @returns An object with 'x' and 'y' properties representing the horizontal and vertical scroll positions in pixels.
+   */
+  export function getScrollPosition(srcWindow?: Window): { x: number; y: number; };
+
+  /**
+   * Adjusts the height of a textarea to fit its content, preserving scroll position, and returns the new height.
+   * @param domNode The DOM node (textarea) to resize.
+   * @param minHeight The minimum height to use for the textarea.
+   * @returns The new height of the textarea.
+   */
+  export function resizeTextAreaToFit(domNode: HTMLTextAreaElement, minHeight: string): number;
+
+  /**
+   * Gets the bounding rectangle of an element in absolute page coordinates.
+   * @param element The element to get the bounding rectangle for.
+   * @returns An object representing the bounding rectangle with properties: left, width, right, top, height, bottom.
+   */
+  export function getBoundingPageRect(element: Element): { left: number; width: number; right: number; top: number; height: number; bottom: number; };
+
+  /**
+   * Saves a named password in the browser.
+   * @param name The name for the password.
+   * @param password The password to save.
+   */
+  export function savePassword(name: string, password: string): void;
+
+  /**
+   * Retrieves a named password from the browser.
+   * @param name The name of the password to retrieve.
+   * @returns The password, or an empty string if not found.
+   */
+  export function getPassword(name: string): string;
+
+  /**
+   * Forces layout of a DOM node and its descendants.
+   * @param element The DOM element to force layout on.
+   */
+  export function forceLayout(element: Element): void;
+
+  /**
+   * Pulses an element for debugging purposes.
+   * @param element The element to pulse.
+   */
+  export function pulseElement(element: Element): void;
+
+  /**
+   * Get the computed styles applied to an element as an array of strings of individual CSS properties.
+   * @param domNode The DOM node to get the computed styles for.
+   * @returns An array of strings, each representing an individual CSS property and its value.
+   */
+  export function getComputedStyles(domNode: Element): string[];
+
+  /**
+   * Applies a set of styles to a DOM node, passed as an array of strings of individual CSS properties.
+   * @param domNode The DOM node to apply the styles to.
+   * @param styleDefs An array of strings, each representing an individual CSS property and its value.
+   */
+  export function setStyles(domNode: Element, styleDefs: string[]): void;
+
+  /**
+   * Copies the computed styles from a source element to a destination element.
+   * @param srcDomNode The source DOM node.
+   * @param dstDomNode The destination DOM node.
+   */
+  export function copyStyles(srcDomNode: Element, dstDomNode: Element): void;
+
+  /**
+   * Copies plain text to the clipboard on browsers that support it.
+   * @param text The text to copy.
+   * @param options Options for copying, including 'doNotNotify' to suppress notifications.
+   * @returns True if the operation succeeded, otherwise false.
+   */
+  export function copyToClipboard(text: string, options?: { doNotNotify?: boolean }): boolean;
+
+  /**
+   * Gets the path part of the current location.
+   * @returns The path part of the current location URL.
+   */
+  export function getLocationPath(): string;
+
+  /**
+   * Collects DOM variables from an event.
+   * @param selectedNode The node selected.
+   * @param domNode The DOM node catching the event.
+   * @param event The event object.
+   * @returns An object containing variables derived from the DOM and event.
+   */
+  export function collectDOMVariables(selectedNode: Element, domNode: Element, event: Event): Record<string, string>;
+
+  /**
+   * Safely executes a querySelector, avoiding exceptions on invalid selectors.
+   * @param selector The CSS selector to query.
+   * @param baseElement The base element to start the query from, defaults to document.
+   * @returns The first element matching the selector, or null if none are found or the selector is invalid.
+   */
+  export function querySelectorSafe(selector: string, baseElement?: Element): Element | null;
+
+  /**
+   * Safely executes a querySelectorAll, avoiding exceptions on invalid selectors.
+   * @param selector The CSS selector to query.
+   * @param baseElement The base element to start the query from, defaults to document.
+   * @returns A NodeList of elements matching the selector, or an empty NodeList if none are found or the selector is invalid.
+   */
+  export function querySelectorAllSafe(selector: string, baseElement?: Element): NodeList;
+
+  /**
+   * Notifier mechanism
+   */
   export class Notifier {
     /**
      * Display a notification
@@ -40,18 +231,3 @@ declare module 'tiddlywiki' {
     display(title: string, options?: Record<string, unknown>): void;
   }
 }
-
-declare module '$:/core/modules/utils/dom.js' {
-  import { Widget, Notifier } from 'tiddlywiki';
-  export const addClass: (element: Element, className: string) => void;
-  export const addEventListeners: (
-    domNode: Element,
-    events: {
-      handlerFunction?: (event: MouseEvent) => void;
-      handlerMethod?: string;
-      handlerObject?: Widget;
-      name: string;
-    }[],
-  ) => void;
-  export { Notifier }
-}

package/src/modules/utils/edition-info.d.ts

@@ -0,0 +1,11 @@
+declare module '$:/core/modules/utils/edition-info.js' {
+  /**
+   * Get the edition information.
+   * @description 获取版本信息。
+   * @returns An object containing the edition information.
+   * @returns 包含版本信息的对象。
+   */
+  export function getEditionInfo(): {
+    [key: string]: any;
+  };
+}

package/src/modules/utils/escapecss.d.ts

@@ -0,0 +1,8 @@
+declare module '$:/core/modules/utils/escapecss.js' {
+  /**
+   * The onstalled event handler of the element
+   * @returns The escaped string
+   * @description 为在 CSS 选择器或标识符中使用而转义字符串
+   */
+  export function escapeCSS(value: string): typeof window.CSS.escape;
+}

package/src/modules/utils/fakedom.d.ts

@@ -23,5 +23,6 @@ declare module 'tiddlywiki' {
 }
 
 declare module '$:/core/modules/utils/fakedom.js' {
-  export type { TW_Element, TW_TextNode, IFakeDocument } from 'tiddlywiki';
+  import type { IFakeDocument } from 'tiddlywiki';
+  export const fakeDocument: IFakeDocument;
 }

package/src/modules/utils/filesystem.d.ts

@@ -1,48 +1,126 @@
 declare module '$:/core/modules/utils/utils.js' {
-  import { IFileInfo, Tiddler, Wiki } from 'tiddlywiki';
+  /**
+   * Return the subdirectories of a path
+   * @param dirPath - The path to the directory
+   * @returns An array of subdirectories
+   * @description 返回路径的子目录
+   */
+  export function getSubdirectories(dirPath: string): string[];
 
-  export const generateTiddlerFilepath: (
-    title: string,
-    options?: {
-      directory?: string;
-      extension?: string;
-      fileInfo?: {
-        originalpath?: string;
-        filePath?: string;
-        writeError?: boolean;
-      };
-      pathFilters?: string[];
-      wiki?: Wiki;
-    },
-  ) => string;
+  /**
+   * Recursively (and synchronously) copy a directory and all its content
+   * @param srcPath - The source path of the directory to copy
+   * @param dstPath - The destination path of the directory to copy
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地（同步地）复制目录及其所有内容
+   */
+  export function copyDirectory(srcPath: string, dstPath: string): string;
+
+  /**
+   * Copy a file
+   * @param srcPath - The source path of the file to copy
+   * @param dstPath - The destination path of the file to copy
+   * @returns An error message if there is an error, otherwise null
+   * @description 复制文件
+   */
+  export function copyFile(srcPath: string, dstPath: string): string;
+
+  /**
+   * Remove trailing path separator
+   * @param dirPath - The directory path to remove the trailing separator from
+   * @returns The directory path without the trailing separator
+   * @description 移除路径末尾的分隔符
+   */
+  export function removeTrailingSeparator(dirPath: string): string;
+
+  /**
+   * Recursively create a directory
+   * @param dirPath - The path of the directory to create
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地创建目录
+   */
+  export function createDirectory(dirPath: string): string;
+
+  /**
+   * Recursively create directories needed to contain a specified file
+   * @param filePath - The path of the file to create directories for
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地创建包含指定文件的目录
+   */
+  export function createFileDirectories(filePath: string): string;
+
+  /**
+   * Recursively delete a directory
+   * @param dirPath - The path of the directory to delete
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地删除目录
+   */
+  export function deleteDirectory(dirPath: string): string;
+
+  /**
+   * Check if a path identifies a directory
+   * @param dirPath - The path to check
+   * @returns True if the path identifies a directory, false otherwise
+   * @description 检查路径是否标识目录
+   */
+  export function isDirectory(dirPath: string): boolean;
+
+  /**
+   * Check if a path identifies a directory that is empty
+   * @param dirPath - The path to check
+   * @returns True if the path identifies an empty directory, false otherwise
+   * @description 检查路径是否标识空目录
+   */
+  export function isDirectoryEmpty(dirPath: string): boolean;
+
+  /**
+   * Recursively delete a tree of empty directories
+   * @param dirpath - The path of the directory to delete
+   * @param callback - A callback function to call when the operation is complete
+   * @description 递归地删除空目录树
+   */
+  export function deleteEmptyDirs(
+    dirpath: string,
+    callback: (err: Error | null) => void,
+  ): void;
+
+  /**
+   * Generate a fileInfo object for saving a tiddler
+   * @param tiddler - The tiddler to generate the fileInfo for
+   * @param options - Options for generating the fileInfo
+   * @returns A fileInfo object
+   * @description 生成用于保存 tiddler 的 fileInfo 对象
+   */
   export function generateTiddlerFileInfo(
     tiddler: Tiddler,
     options: {
-      directory?: string;
+      directory: string;
       pathFilters?: string[];
       extFilters?: string[];
       wiki?: Wiki;
-      fileInfo?: IFileInfo;
+      fileInfo?: FileInfo;
     },
-  ): IFileInfo;
-}
+  ): FileInfo;
+
+  /**
+   * Generate the file extension for saving a tiddler
+   * @param title - The title of the tiddler
+   * @param options - Options for generating the file extension
+   * @returns The file extension
+   * @description 生成用于保存 tiddler 的文件扩展名
+   * 可选项包括：
+   * extFilters：用于生成扩展名的可选过滤器数组
+   * wiki：用于评估 extFilters 的可选 wiki
+   */
+  export function generateTiddlerExtension(
+    title: string,
+    options: {
+      extFilters?: string[];
+      wiki?: Wiki;
+    },
+  ): string;
 
 declare module 'tiddlywiki' {
-  import { generateTiddlerFileInfo, generateTiddlerFilepath } from '$:/core/modules/utils/utils.js';
-  export interface IFileInfo {
-    isEditableFile: boolean;
-    originalpath: string;
-    type: string;
-    hasMetaFile: boolean;
-    encoding: string;
-    filepath: string;
-  }
-  export interface ITiddlersInFile {
-    filepath: string;
-    type: string;
-    tiddlers: ITiddlerFields[];
-    hasMetaFile: boolean;
-  }
   interface IUtils {
     /**
      * Generate the filepath for saving a tiddler
@@ -54,19 +132,9 @@ declare module 'tiddlywiki' {
      * * fileInfo: an existing fileInfo object to check against
      */
     generateTiddlerFilepath: typeof generateTiddlerFilepath;
-    /**
-    Create a fileInfo object for saving a tiddler:
-      filepath: the absolute path to the file containing the tiddler
-      type: the type of the tiddler file on disk (NOT the type of the tiddler)
-      hasMetaFile: true if the file also has a companion .meta file
-      isEditableFile: true if the tiddler was loaded via non-standard options & marked editable
-    Options include:
-      directory: absolute path of root directory to which we are saving
-      pathFilters: optional array of filters to be used to generate the base path
-      extFilters: optional array of filters to be used to generate the base path
-      wiki: optional wiki for evaluating the pathFilters,
-      fileInfo: an existing fileInfo to check against
-    */
-    generateTiddlerFileInfo: typeof generateTiddlerFileInfo;
   }
 }
+
+declare module '$:/core/modules/utils/utils.js' {
+  export { generateTiddlerFilepath };
+}

package/src/modules/utils/index.d.ts

@@ -2,4 +2,34 @@
 /// <reference path="utils.d.ts" />
 /// <reference path="fakedom.d.ts" />
 /// <reference path="filesystem.d.ts" />
-/// <reference path="logger.d.ts" />
+
+declare module 'tiddlywiki' {
+  // Thanks for GitHub Copilot, you has helped me a lot!
+  import * as dom from '$:/core/modules/utils/dom.js';
+  import * as utils from '$:/core/modules/utils/utils.js';
+  import * as filesystem from '$:/core/modules/utils/filesystem.js';
+  import * as LinkedList from '$:/core/modules/utils/linked-list.js';
+  import * as performance from '$:/core/modules/utils/performance.js';
+  import * as logger from '$:/core/modules/utils/logger.js';
+  import * as parsetree from '$:/core/modules/utils/parsetree.js';
+  import * as pluginMaker from '$:/core/modules/utils/pluginmaker.js';
+  import * as transliterate from '$:/core/modules/utils/transliterate.js';
+  import * as crypto from '$:/core/modules/utils/crypto.js';
+  import * as csv from '$:/core/modules/utils/csv.js';
+  import * as editionInfo from '$:/core/modules/utils/edition-info.js';
+  import * as escapecss from '$:/core/modules/utils/escapecss.js';
+
+  type IUtilsModules = Pick<typeof dom, keyof typeof dom> &
+    Partial<Pick<typeof filesystem, keyof typeof filesystem>> &
+    Pick<typeof utils, keyof typeof utils> &
+    Pick<typeof LinkedList, keyof typeof LinkedList> &
+    Pick<typeof performance, keyof typeof performance> &
+    Pick<typeof logger, keyof typeof logger> &
+    Pick<typeof parsetree, keyof typeof parsetree> &
+    Pick<typeof pluginMaker, keyof typeof pluginMaker> &
+    Pick<typeof transliterate, keyof typeof transliterate> &
+    Pick<typeof crypto, keyof typeof crypto> &
+    Pick<typeof csv, keyof typeof csv> &
+    Pick<typeof editionInfo, keyof typeof editionInfo> &
+    Pick<typeof escapecss, keyof typeof escapecss>;
+}