tw5-typed 0.6.7 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tw5-typed",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "scripts": {
     "check": "tsc --noEmit && eslint src/**/*.ts",
     "docs": "docs-ts",

package/src/core.d.ts

@@ -42,7 +42,11 @@ declare module 'tiddlywiki' {
     Syncer: new() => Syncer;
     Tiddler: typeof Tiddler;
     Wiki: typeof Wiki;
-    addUnloadTask(task: any);
+    /**
+     * Add another unload task
+     * @param task - Function to be called on unload
+     */
+    addUnloadTask(task: any): void;
     boot: IBoot;
 
     browser: null | {
@@ -110,33 +114,89 @@ declare module 'tiddlywiki' {
     hooks: IHooks;
     keyboardManager: KeyboardManager;
     language: ILanguage;
+    /**
+     * Load the metadata fields in the .meta file corresponding to a particular file
+     * @param filepath - The path to the file
+     * @returns The metadata fields or null if no .meta file exists
+     */
     loadMetadataForFile(filepath: string): ITiddlerFields | null;
+    /**
+     * Load a plugin by name from the given search paths
+     * @param name - Name of the plugin (e.g., "tiddlywiki/filesystemadaptor")
+     * @param paths - Array of file paths to search for it
+     */
     loadPlugin(name: string, paths: string[]): void;
+    /**
+     * Load the tiddlers from a plugin folder, and package them up into a proper JSON plugin tiddler
+     * @param filepath - Path to the plugin folder
+     * @param excludeRegExp - Optional regex for files to exclude
+     * @returns Plugin info object or null if not a valid plugin
+     */
     loadPluginFolder(
       filepath: string,
       excludeRegExp?: RegExp,
     ): IPluginInfo | null;
+    /**
+     * Load multiple plugins
+     * @param plugins - Array of plugin names (e.g., ["tiddlywiki/filesystemadaptor"])
+     * @param libraryPath - Path of library folder for these plugins (relative to core path)
+     * @param environmentVariable - Environment variable name for these plugins
+     */
     loadPlugins(plugins: string[], libraryPath: string, environmentVariable?: string): void;
+    /**
+     * Load tiddlers in browser environment
+     */
     loadTiddlersBrowser(): void;
+    /**
+     * Load the tiddlers contained in a particular file (and optionally extract fields from the accompanying .meta file)
+     * @param filepath - The path to the file to load
+     * @param defaultFields - Optional default fields to apply to loaded tiddlers
+     * @returns Object containing filepath, type, tiddlers array, and hasMetaFile flag
+     */
     loadTiddlersFromFile(
       filepath: string,
       defaultFields?: Record<string, unknown>,
     ): ITiddlersInFile;
+    /**
+     * Load all the tiddlers recursively from a directory, including honouring `tiddlywiki.files` files for drawing in external files
+     * @param filepath - The path to load from
+     * @param excludeRegExp - Optional regex for files to exclude
+     * @returns Array of objects containing filepath, type, tiddlers array, and hasMetaFile flag
+     * @description Note that no file information is returned for externally loaded tiddlers, just the `tiddlers` property.
+     */
     loadTiddlersFromPath(
       filepath: string,
       excludeRegExp?: RegExp,
-    ): ITiddlerFields[];
+    ): ITiddlersInFile[];
+    /**
+     * Load all the tiddlers defined by a `tiddlywiki.files` specification file
+     * @param filepath - Pathname of the directory containing the specification file
+     * @param excludeRegExp - Optional regex for files to exclude
+     * @returns Array of objects containing filepath, type, tiddlers array, and hasMetaFile flag
+     */
     loadTiddlersFromSpecification(
       filepath: string,
       excludeRegExp?: RegExp,
-    ): ITiddlerFields[];
+    ): ITiddlersInFile[];
 
+    /**
+     * Load tiddlers in Node.js environment
+     * @description Load boot tiddlers, core tiddlers, extra plugins, and wiki tiddlers
+     */
     loadTiddlersNode(): void;
 
+    /**
+     * Load wiki tiddlers from a wiki directory
+     * @param wikiPath - Path to the wiki directory
+     * @param options - Options for loading
+     * @param options.parentPaths - Array of parent paths that we mustn't recurse into
+     * @param options.readOnly - True if the tiddler file paths should not be retained
+     * @returns Wiki info object or null if no tiddlywiki.info file exists
+     */
     loadWikiTiddlers(
       wikiPath: string,
-      options?: { parentPaths?: string; readOnly?: boolean },
-    ): IWikiInfo;
+      options?: { parentPaths?: string[]; readOnly?: boolean },
+    ): IWikiInfo | null;
 
     locationHash: string;
 

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

@@ -168,13 +168,24 @@ declare module 'tiddlywiki' {
      * @param {string } name name of the variable
      * @param {string} value value of the variable
      * @param {IWidgetVariableParam[]} [params=[]] array of `{name: string, default: string}` for each parameter
-     * @param {boolean} [isMacroDefinition=true] true if the variable is set via a \define macro pragma (and hence should have variable substitution performed)
+     * @param {boolean} [isMacroDefinition=false] true if the variable is set via a \define macro pragma (and hence should have variable substitution performed)
+     * @param {object} [options] Additional options
+     * @param {boolean} [options.isProcedureDefinition] true if the variable is set via a \procedure pragma
+     * @param {boolean} [options.isFunctionDefinition] true if the variable is set via a \function pragma
+     * @param {boolean} [options.isWidgetDefinition] true if the variable is set via a \widget pragma
+     * @param {boolean} [options.configTrimWhiteSpace] whether to trim whitespace
      */
     setVariable(
       name: string,
       value: string,
       parameters?: IWidgetVariableParameter[],
       isMacroDefinition?: boolean,
+      options?: {
+        configTrimWhiteSpace?: boolean;
+        isFunctionDefinition?: boolean;
+        isProcedureDefinition?: boolean;
+        isWidgetDefinition?: boolean;
+      },
     ): void;
 
     /**
@@ -254,10 +265,14 @@ declare module 'tiddlywiki' {
      * @zh
      * 计算微件的属性的当前值。返回一个已经改变的属性名称的哈希图
      *
+     * @param {object} [options] Options
+     * @param {Function} [options.filterFn] only include attributes where filterFn(name) returns true
      * @return Object with keys of the names of the attributes that have changed
      * @memberof Widget
      */
-    computeAttributes(): Record<string, true>;
+    computeAttributes(options?: {
+      filterFn?: (name: string) => boolean;
+    }): Record<string, true>;
 
     computeAttribute(attribute: string): string;
 
@@ -302,9 +317,15 @@ declare module 'tiddlywiki' {
      * Assign the computed attributes of the widget to a domNode
      * options include:
      * * `excludeEventAttributes`: ignores attributes whose name begins with "on"
+     * * `sourcePrefix`: prefix of attributes that are to be directly assigned (defaults to the empty string)
+     * * `destPrefix`: prefix to be applied to attribute names that are to be directly assigned (defaults to the empty string)
+     * * `changedAttributes`: hashmap by attribute name of attributes to process (if missing, process all attributes)
      * @zh
      * 将微件的计算属性分配给一个 domNode, 选项包括:
      * * `excludeEventAttributes`: 忽略名称以 "on "开头的属性
+     * * `sourcePrefix`: 要直接分配的属性的前缀（默认为空字符串）
+     * * `destPrefix`: 要应用到直接分配的属性名称的前缀（默认为空字符串）
+     * * `changedAttributes`: 按属性名称的哈希图，要处理的属性（如果缺失，处理所有属性）
      * 一些特殊的属性：
      * * `xlink:<xlink-name>`
      * * `style.<css-style-name>`
@@ -315,7 +336,12 @@ declare module 'tiddlywiki' {
      */
     assignAttributes(
       domNode: Element,
-      options?: { excludeEventAttributes?: boolean },
+      options?: {
+        changedAttributes?: Record<string, string>;
+        destPrefix?: string;
+        excludeEventAttributes?: boolean;
+        sourcePrefix?: string;
+      },
     );
 
     /**
@@ -392,6 +418,14 @@ declare module 'tiddlywiki' {
       handler: (event: IWidgetEvent) => undefined | Promise<void> | boolean,
     ): void;
 
+    /**
+     * Remove an event listener
+     */
+    removeEventListener(
+      type: string,
+      handler: (event: IWidgetEvent) => undefined | Promise<void> | boolean,
+    ): void;
+
     /**
      * Dispatch an event to a widget. If the widget doesn't handle the event then it is also dispatched to the parent widget
      * Events added via `addEventListener`, like `tm-notify`, can be invoked by this.
@@ -479,12 +513,65 @@ declare module 'tiddlywiki' {
       variables?: Record<string, string>,
     ): boolean;
 
+    /**
+     * @en
+     * Execute action tiddlers by tag
+     * @zh
+     * 按标签执行 action tiddlers
+     *
+     * @param {string} tag The tag to filter action tiddlers
+     * @param {IWidgetEvent} event The widget event
+     * @param {Record<string, string>} variables Optional variables to pass to the action string
+     * @memberof Widget
+     */
+    invokeActionsByTag(
+      tag: string,
+      event?: IWidgetEvent | null,
+      variables?: Record<string, string>,
+    ): void;
+
+    /**
+     * @en
+     * Find child `<$data>` widgets recursively. The tag name allows aliased versions of the widget to be found too
+     * @zh
+     * 递归查找子 `<$data>` widgets。标签名称允许查找该 widget 的别名版本
+     *
+     * @param {Widget[]} children The children widgets to search
+     * @param {string} tag The tag name to search for (e.g., "$data")
+     * @param {Function} callback Callback function called for each found widget
+     * @memberof Widget
+     */
+    findChildrenDataWidgets(
+      children: Widget[],
+      tag: string,
+      callback: (widget: Widget) => void,
+    ): void;
+
     removeLocalDomNodes(): void;
 
     /**
      * Make a fake widget with specified variables, suitable for variable lookup in filters
      */
     makeFakeWidgetWithVariables(variables: Record<string, string>): Widget;
+
+    /**
+     * @en
+     * Evaluate a variable with parameters. This is a static convenience method that attempts to evaluate a variable as a function, returning an array of strings
+     * @zh
+     * 使用参数评估变量。这是一个静态便捷方法，尝试将变量作为函数评估，返回字符串数组
+     *
+     * @param {Widget} widget The widget context for variable lookup
+     * @param {string} name The variable name to evaluate
+     * @param {IGetWidgetVariableOptions} options Options for variable evaluation
+     * @returns {string[]} Array of result strings
+     * @static
+     * @memberof Widget
+     */
+    static evaluateVariable(
+      widget: Widget,
+      name: string,
+      options?: IGetWidgetVariableOptions,
+    ): string[];
   }
 }