tw5-typed 0.2.5 → 0.2.8

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {
@@ -20,28 +20,28 @@
     "prepublishOnly": "npx tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^17.0.24",
-    "@typescript-eslint/eslint-plugin": "5.19.0",
-    "@typescript-eslint/parser": "5.19.0",
-    "eslint": "8.13.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": "16.0.3",
+    "eslint-config-standard": "17.0.0",
     "eslint-config-standard-with-typescript": "21.0.1",
     "eslint-import-resolver-alias": "1.1.2",
     "eslint-import-resolver-typescript": "2.7.1",
     "eslint-plugin-html": "6.2.0",
     "eslint-plugin-import": "2.26.0",
-    "eslint-plugin-n": "15.1.0",
+    "eslint-plugin-n": "15.2.0",
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-prettier": "4.0.0",
     "eslint-plugin-promise": "6.0.0",
     "eslint-plugin-react": "7.29.4",
-    "eslint-plugin-react-hooks": "4.4.0",
-    "eslint-plugin-security": "1.4.0",
+    "eslint-plugin-react-hooks": "4.5.0",
+    "eslint-plugin-security": "1.5.0",
     "eslint-plugin-security-node": "1.1.1",
     "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

@@ -25,12 +25,40 @@ declare module 'tiddlywiki' {
     /**
      * Get full list of tiddler titles in the wiki
      */
-    getTiddlers: () => string[];
+    getTiddlers(): string[];
+    /**
+     * Return a named global cache object. Global cache objects are cleared whenever a tiddler change.
+     * You can put anything into the cache.
+     * @param cacheName key of the cache
+     * @param initializer when cache miss, this will be called to get initial value
+     */
+    getGlobalCache<T>(cacheName: string, initializer: () => T): T;
+    /**
+     * Return the named cache object for a tiddler. If the cache doesn't exist then the initializer function is invoked to create it
+     * @param cacheName key of the cache
+     * @param initializer when cache miss, this will be called to get initial value
+     */
+    getCacheForTiddler<T>(title: string, cacheName: string, initializer: () => T): T;
+    /**
+     * clear all cache, will be called when a tiddler is changed
+     */
+    clearGlobalCache(): void;
     /**
      * 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): (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)
      */
-    compileFilter: (filterString: string) => (iterator?: SourceIterator) => string[];
+    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.
@@ -94,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
@@ -106,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
@@ -115,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,7 +3,7 @@ declare module 'tiddlywiki' {
     end?: number;
     name?: string;
     start?: number;
-    type: 'string' | 'number';
+    type: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
     value: string;
   }
 
@@ -22,9 +22,18 @@ declare module 'tiddlywiki' {
     type: 'text';
   }
   export interface ILinkParseTreeNode extends IWikiASTNode {
-    text: string;
+    text?: string;
     type: 'link';
   }
+  export interface IImageParseTreeNode extends IWikiASTNode {
+    type: 'image';
+  }
+  export interface ITranscludeParseTreeNode extends IWikiASTNode {
+    type: 'transclude';
+  }
+  export interface ITiddlerParseTreeNode extends IWikiASTNode {
+    type: 'tiddler';
+  }
   export type HTMLTags = keyof HTMLElementTagNameMap | 'strike';
 
   export interface IDomParseTreeNode extends IWikiASTNode {
@@ -33,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 {
@@ -64,5 +69,15 @@ declare module 'tiddlywiki' {
     text?: string;
     type: string;
   }
-  export type IParseTreeNode = IDomParseTreeNode | IMacroParameterCallParseTreeNode | IMacroCallParseTreeNode | ITextParseTreeNode | ICustomParseTreeNode;
+  export type IParseTreeNode =
+    | IDomParseTreeNode
+    | IMacroParameterCallParseTreeNode
+    | IMacroCallParseTreeNode
+    | ITextParseTreeNode
+    | IImageParseTreeNode
+    | ITranscludeParseTreeNode
+    | ITiddlerParseTreeNode
+    | ICodeBlockParseTreeNode
+    | ILinkParseTreeNode
+    | ICustomParseTreeNode;
 }

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;
@@ -59,6 +63,12 @@ declare module 'tiddlywiki' {
 
     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 +81,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 +104,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,9 @@ declare module 'tiddlywiki' {
   }
 
   export interface IWidgetEvent {
+    [extraKeys: string]: unknown;
     /** maybe a DOM click event, if trigger by button click */
-    event: Event;
+    event: UIEvent | Event;
     navigateFromTitle?: string;
     /**
      * Get `$param`
@@ -23,6 +24,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));`
@@ -39,21 +41,30 @@ declare module 'tiddlywiki' {
    */
   export class Widget {
     constructor(parseTreeNode: IParseTreeNode, options?: unknown);
-    initialize: (parseTreeNode: IParseTreeNode, options?: unknown) => void;
+    initialize(parseTreeNode: IParseTreeNode, options?: unknown): void;
     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
+     *
+     * Like `new widget.widget(widgetNode,{` in `$tw.wiki.makeWidget`
+     */
+    widget: new (parseTreeNode: IParseTreeNode, options?: unknown) => Widget;
     children: Widget[];
-    /*
-Make child widgets correspondng to specified parseTreeNodes
-*/
-    makeChildWidgets(parseTreeNodes: IParseTreeNode[], options?: { variables?: unknown }): void;
     /**
-      Construct the widget object for a parse tree node
+      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, 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[];
@@ -71,12 +82,23 @@ Make child widgets correspondng to specified parseTreeNodes
     addEventListeners(listeners: Array<{ handler: (event: IWidgetEvent) => void | Promise<void>; type: string }>): void;
 
     parentDomNode: Node;
-    execute: () => void;
+    /**
+      Compute the internal state of the widget.
+      This will be automatically called in the `render` method.
+
+      For example, `getAttribute` and set them to class members.
+      
+    */
+    execute(): void;
 
     /**
      * Lifecycle method: Render this widget into the DOM
      */
     render(parent: Node, nextSibling: Node | null): void;
+    /**
+     * Render the children of this widget into the DOM
+     */
+    renderChildren(parent: Node, nextSibling: Node | null): void;
     /**
      * Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering.
      * You can do some cleanup or buildup before return true.
@@ -93,7 +115,7 @@ Make child widgets correspondng to specified parseTreeNodes
       Rebuild a previously rendered widget
     */
     refreshSelf(): boolean;
-    computeAttributes(): void;
+    computeAttributes(): Record<string, IParseTreeAttribute>;
     /**
      * Get parameters that user set in the widget
      * @param name attribute name, for example, `actions` in the button widget