tw5-typed 0.2.6 → 0.2.9

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {
@@ -20,10 +20,10 @@
     "prepublishOnly": "npx tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^17.0.29",
-    "@typescript-eslint/eslint-plugin": "5.21.0",
-    "@typescript-eslint/parser": "5.21.0",
-    "eslint": "8.14.0",
+    "@types/node": "^17.0.31",
+    "@typescript-eslint/eslint-plugin": "5.22.0",
+    "@typescript-eslint/parser": "5.22.0",
+    "eslint": "8.15.0",
     "eslint-config-prettier": "8.5.0",
     "eslint-config-standard": "17.0.0",
     "eslint-config-standard-with-typescript": "21.0.1",
@@ -42,6 +42,6 @@
     "eslint-plugin-typescript-sort-keys": "2.1.0",
     "eslint-plugin-unicorn": "42.0.0",
     "prettier": "2.6.2",
-    "typescript": "4.6.3"
+    "typescript": "4.6.4"
   }
 }

package/src/Wiki.d.ts

@@ -46,8 +46,19 @@ declare module 'tiddlywiki' {
     /**
      * Compile filter string to be a function that execute the filter in the wiki.
      * You can pass an optional iterator that provide the input to the returned function. If no iterator is provided, filter will use first operator to get input.
+     * 
+     * @returns a function with the signature fn(source,widget) where:
+        source: an iterator function for the source tiddlers, called source(iterator), where iterator is called as iterator(tiddler,title)
+        widget: an optional widget node for retrieving the current tiddler etc.
      */
-    compileFilter: (filterString: string) => (iterator?: SourceIterator) => string[];
+    compileFilter(filterString: string): (source?: SourceIterator, widget?: Widget) => string[];
+    /**
+     *
+     * @param filterString
+     * @param widget an optional widget node for retrieving the current tiddler etc.
+     * @param source an iterator function for the source tiddlers, called source(iterator), where iterator is called as iterator(tiddler,title)
+     */
+    filterTiddlers(filterString: string, widget?: Widget, source?: SourceIterator): string[];
     /**
      * Set JSON tiddler, Object in data field will be JSON.stringify and put into the text.
      * This will make tiddler to be JSON data tiddler `"type":"application/json"`, so if you just want to modify existed tiddler's data, use `addTiddler` instead.
@@ -111,7 +122,20 @@ declare module 'tiddlywiki' {
      * @param {object} options options, see tiddlywiki dev doc for details
      */
     setText: (title: string, field?: string, index?: string | undefined, value?: string, options?: { suppressTimestamp?: boolean }) => void;
+    /**
+      Parse a tiddler according to its MIME type
+    */
     parseTiddler(title: string, options?: IParserOptions): WikiParser;
+    /**
+      Parse a block of text of a specified MIME type
+      @param {string} type: content type of text to be parsed
+      @param {string} text: text
+      @param {object}options: see below
+
+    Options include:
+      - parseAsInline: if true, the text of the tiddler will be parsed as an inline run
+      - _canonical_uri: optional string of the canonical URI of this content
+    */
     parseText(type: string, text: string, options?: IParserOptions): WikiParser;
     /**
       Parse text from a tiddler and render it into another format
@@ -123,6 +147,16 @@ declare module 'tiddlywiki' {
       parentWidget: optional parent widget for the root node
       */
     renderTiddler(outputType: OutputMimeTypes, title: string, options?: IRenderOptions): string;
+    /**
+      Parse text in a specified format and render it into another format
+       @param outputType content type for the output
+       @param textType content type of the input text
+       @param text input text
+       @param options see below, Options includes:
+      - variables: hashmap of variables to set
+      - parentWidget: optional parent widget for the root node
+    */
+    renderText(outputType: OutputMimeTypes, textType: TextMimeTypes, text: string, options?: Partial<IMakeWidgetOptions> & IParserOptions): string;
     /**
       Make a widget tree for a parse tree
       @params parser: parser object
@@ -132,17 +166,6 @@ declare module 'tiddlywiki' {
       variables: hashmap of variables to set
       parentWidget: optional parent widget for the root node
     */
-    /**
-      Parse text in a specified format and render it into another format
-        outputType: content type for the output
-        textType: content type of the input text
-        text: input text
-        options: see below
-      Options include:
-      variables: hashmap of variables to set
-      parentWidget: optional parent widget for the root node
-    */
-    renderText(outputType: OutputMimeTypes, textType: TextMimeTypes, text: string, options?: Partial<IMakeWidgetOptions> & IParserOptions): string;
     makeWidget(parser: WikiParser, options?: IMakeWidgetOptions): Widget;
     /**
       Make a widget tree for transclusion

package/src/ast.d.ts

@@ -3,8 +3,8 @@ declare module 'tiddlywiki' {
     end?: number;
     name?: string;
     start?: number;
-    type: 'string' | 'number';
-    value: string;
+    type: 'string' | 'number' | 'bigint' | 'boolean' | 'macro' | 'macro-parameter';
+    value: string | IMacroCallParseTreeNode;
   }
 
   export interface IWikiASTNode {
@@ -22,7 +22,7 @@ declare module 'tiddlywiki' {
     type: 'text';
   }
   export interface ILinkParseTreeNode extends IWikiASTNode {
-    text: string;
+    text?: string;
     type: 'link';
   }
   export interface IImageParseTreeNode extends IWikiASTNode {
@@ -42,19 +42,15 @@ declare module 'tiddlywiki' {
   }
   export interface ICodeBlockParseTreeNode extends IWikiASTNode {
     attributes: {
-      code?:
-        | {
-            type: 'string';
-            value: string;
-          }
-        | undefined;
-      language?:
-        | {
-            type: 'string';
-            value: string;
-          }
-        | undefined;
-    };
+      code?: {
+        type: 'string';
+        value: string;
+      };
+      language?: {
+        type: 'string';
+        value: string;
+      };
+    } & IWikiASTNode['attributes'];
     type: 'codeblock';
   }
   export interface IMacroParameterCallParseTreeNode extends IWikiASTNode {
@@ -63,10 +59,17 @@ declare module 'tiddlywiki' {
     value: string;
   }
   export interface IMacroCallParseTreeNode extends IWikiASTNode {
-    name: string;
-    params: IMacroParameterCallParseTreeNode[];
+    name?: string;
+    params?: IMacroParameterCallParseTreeNode[];
+    /** `tag: '$macrocall',` */
+    tag?: string;
     type: 'macrocall';
   }
+  export interface IMacroParseTreeNode extends IWikiASTNode {
+    name: string;
+    type: 'macro';
+    value: IMacroCallParseTreeNode;
+  }
   export interface ICustomParseTreeNode extends IWikiASTNode {
     params: IMacroParameterCallParseTreeNode[];
     tag?: string;
@@ -74,6 +77,7 @@ declare module 'tiddlywiki' {
     type: string;
   }
   export type IParseTreeNode =
+    | IWikiASTNode
     | IDomParseTreeNode
     | IMacroParameterCallParseTreeNode
     | IMacroCallParseTreeNode
@@ -81,5 +85,9 @@ declare module 'tiddlywiki' {
     | IImageParseTreeNode
     | ITranscludeParseTreeNode
     | ITiddlerParseTreeNode
-    | ICustomParseTreeNode;
+    | ICodeBlockParseTreeNode
+    | ILinkParseTreeNode
+    | ICustomParseTreeNode
+    | IMacroParseTreeNode
+    | IParseTreeAttribute;
 }

package/src/server.d.ts

@@ -81,6 +81,11 @@ declare module 'tiddlywiki' {
       prefix: optional prefix (falls back to value of "path-prefix" variable)
       */
     listen(port?: string, host?: string, prefix?: string): void;
+
+    on(eventName: 'error', callback: (error: Error) => void): void;
+    on(eventName: 'listening', callback: () => void): void;
+    on(eventName: string, callback: (...arguments_: unknown[]) => unknown): void;
+
     /**
       Check whether a given user is authorized for the specified authorizationType ("readers" or "writers"). Pass null or undefined as the username to check for anonymous access
     */

package/src/tw.d.ts

@@ -30,6 +30,10 @@ declare module 'tiddlywiki' {
     type: string;
   }
 
+  export interface ILanguage {
+    getString(key: string, options: { variables: { title: string } }): string;
+  }
+
   export interface IContentTypeInfo {
     deserializerType: string;
     encoding: string;
@@ -55,10 +59,52 @@ declare module 'tiddlywiki' {
       };
     };
 
-    browser: null | object;
+    browser: null | {
+      is?: {
+        android?: boolean;
+        bada?: boolean;
+        blackberry?: boolean;
+        chrome?: boolean;
+        firefox?: boolean;
+        firefoxos?: boolean;
+        gecko?: boolean;
+        ios?: boolean;
+        ipad?: boolean;
+        iphone?: boolean;
+        mobile?: boolean;
+        name?: boolean;
+        opera?: boolean;
+        phantomjs?: boolean;
+        safari?: boolean;
+        sailfish?: boolean;
+        seamonkey?: boolean;
+        silk?: boolean;
+        tizen?: boolean;
+        version?: boolean;
+        webkit?: boolean;
+        webos?: boolean;
+        windowsphone?: boolean;
+      };
+      /**
+       * @deprecated
+       * Install `$:/plugins/tiddlywiki/browser-sniff` to use `browser.is`
+       */
+      isFirefox: boolean;
+      /**
+       * @deprecated
+       * Install `$:/plugins/tiddlywiki/browser-sniff` to use `browser.is`
+       */
+      isIE: boolean;
+    };
 
     config: ITWConfig;
 
+    /**
+     * Check for this window being the source of the drag. If true, some drop target widget will stop responding to the drop event, so you can handle drop event in your own widget.
+     * Used by `DropZoneWidget.prototype.handleDropEvent`
+     */
+    dragInProgress?: boolean;
+
     /**
       Global Hooks mechanism which allows plugins to modify default functionality
     */
@@ -71,10 +117,13 @@ declare module 'tiddlywiki' {
       /**
         Invoke the hook by key
       */
-      invokeHook(hookName: string): void;
+      invokeHook(hookName: string, event: IWidgetEvent): undefined | IWidgetEvent;
     };
-
+    /** Determines if a tiddler is a shadow tiddler, regardless of whether it has been overridden by a real tiddler */
+    isShadowTiddler(title: string): boolean;
+    language: ILanguage;
     modules: ITWModules;
+
     /** NodeJS features, if tw isn't running on a NodeJS environment, the value will be `null` */
     node: null | object;
     /** Broswer features, if tw isn't running on a browser environment, the value will be `null` */
@@ -91,6 +140,8 @@ declare module 'tiddlywiki' {
 
     rootWidget: Widget;
 
+    /** Test for the existence of a tiddler (excludes shadow tiddlers) */
+    tiddlerExists(title: string): boolean;
     utils: ITWUtils;
     version: string;
     wiki: Wiki;

package/src/utils.d.ts

@@ -4,7 +4,10 @@
 declare module 'tiddlywiki' {
   export type TWDocument = Document;
   export type TWDOMElement = Element;
-  export type TWEachCallback<T> = (element?: unknown, index?: string | number, object?: T) => boolean | undefined;
+  /** Callback is invoked with (element, index, object), if callback returns false, then the each loop will be terminated. */
+  export type TWEachCallback<O, I> =
+    | ((element?: I, indexOrKey?: string | number, object?: O) => boolean | undefined)
+    | ((element?: I, indexOrKey?: string | number, object?: O) => void);
   export interface ITWUtils {
     Crypto: typeof Crypto;
     PasswordPrompt: typeof PasswordPrompt;
@@ -85,7 +88,7 @@ declare module 'tiddlywiki' {
      * Iterate through all the own properties of an object or array.
      * Callback is invoked with (element, index, object), if callback returns false, then the each loop will be terminated.
      */
-    each<T = object | unknown[]>(object: T, callback: TWEachCallback<T>): void;
+    each<I = any>(object: Record<string, I> | I[], callback: TWEachCallback<Record<string, I> | I[], I>): void;
     /** Display an error and exit */
     error(error: Event | string): void;
     /** Run code globally with specified context variables in scope */

package/src/widget.d.ts

@@ -9,8 +9,10 @@ declare module 'tiddlywiki' {
   }
 
   export interface IWidgetEvent {
+    [extraKeys: string]: unknown;
     /** maybe a DOM click event, if trigger by button click */
-    event: Event;
+    event: UIEvent | Event;
+    name: string;
     navigateFromTitle?: string;
     /**
      * Get `$param`
@@ -23,6 +25,7 @@ declare module 'tiddlywiki' {
     paramObject?: {
       [othersParamKeys: string]: unknown;
     };
+    tiddlerTitle?: string;
     /** the first parameter of addEventListener
      *
      * For example, the `'open-command-palette'` in `$tw.rootWidget.addEventListener('open-command-palette', (e: IWidgetEvent) => this.openPalette(e));`
@@ -43,8 +46,11 @@ declare module 'tiddlywiki' {
     parseTreeNode: IParseTreeNode;
     wiki: ITiddlyWiki;
     parentWidget?: Widget;
-    /** we can use $tw.rootWidget.widgetClasses.widget to new a widget */
-    widgetClasses: Widget;
+    /** we can use $tw.rootWidget.widgetClasses.widget to new a widget
+     *
+     * This is a set of all widgets defined in tiddlywiki.
+     */
+    widgetClasses: Record<string, Widget>;
     /** we can use $tw.rootWidget.widgetClasses.widget to new a widget
      *
      * Like `new widget.widget(widgetNode,{` in `$tw.wiki.makeWidget`
@@ -53,15 +59,23 @@ declare module 'tiddlywiki' {
     children: Widget[];
     /**
       Make child widgets correspondng to specified parseTreeNodes
+      And push them to `this.children`
       @param parseTreeNodes default to `this.parseTreeNode.children`, can be undefined
     */
     makeChildWidgets(parseTreeNodes?: IParseTreeNode[], options?: { variables?: unknown }): void;
     /**
-      Construct the widget object for a parse tree node
+     * Remove any DOM nodes created by this widget or its children
+     *
+     * If this widget has directly created DOM nodes, delete them and exit. This assumes that any child widgets are contained within the created DOM nodes, which would normally be the case.
+     * Otherwise, ask the child widgets to delete their DOM nodes
+     */
+    removeChildDomNodes(): void;
+    /**
+      Construct the widget object for a parse tree node, and return the new widget
       options include:
         variables: optional hashmap of variables to wrap around the widget
     */
-    makeChildWidget(parseTreeNode: IParseTreeNode, options?: { variables?: unknown }): void;
+    makeChildWidget(parseTreeNode: IParseTreeNode, options?: { variables?: unknown }): Widget;
     variablesConstructor: variablesConstructor;
     variables: unknown;
     domNodes: Node[];
@@ -87,6 +101,23 @@ declare module 'tiddlywiki' {
       
     */
     execute(): void;
+    /**
+     * Invoke the action widgets that are descendents of the current widget. Will call child widget's invokeAction recursively.
+     *
+     * @param triggeringWidget
+     * @param event
+     * @returns handled by any children
+     */
+    invokeActions(triggeringWidget: Widget, event: IWidgetEvent): boolean;
+    /**
+     * Invoke the action associated with this widget
+     *
+     * No every widget has this method, but some do, like `action-xxx` widget, e.g., `action-sendmessage`
+     * @param triggeringWidget
+     * @param event
+     * @returns handled
+     */
+    invokeAction: (triggeringWidget: Widget, event: IWidgetEvent) => boolean | undefined;
 
     /**
      * Lifecycle method: Render this widget into the DOM
@@ -109,9 +140,18 @@ declare module 'tiddlywiki' {
     */
     refreshChildren(changedTiddlers: IChangedTiddlers): boolean;
     /**
-      Rebuild a previously rendered widget
-    */
-    refreshSelf(): boolean;
+     * Rebuild a previously rendered widget
+     */
+    refreshSelf(): boolean | void;
+    /**
+     * Find the next sibling in the DOM to this widget. This is done by scanning the widget tree through all next siblings and their descendents that share the same parent DOM node
+     * @param startIndex Refer to this widget by its index within its parents children
+     */
+    findNextSiblingDomNode(startIndex?: number): Node | null;
+    /**
+     * Find the first DOM node generated by a widget or its children
+     */
+    findFirstDomNode(): Node | null;
     computeAttributes(): Record<string, IParseTreeAttribute>;
     /**
      * Get parameters that user set in the widget