tw5-typed 0.2.4 → 0.2.7

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "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.21.0",
+    "@typescript-eslint/parser": "5.21.0",
+    "eslint": "8.14.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) => (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.
@@ -106,6 +134,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 +153,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?: IRenderOptions): string;
     makeWidget(parser: WikiParser, options?: IMakeWidgetOptions): Widget;
     /**
       Make a widget tree for transclusion

package/src/ast.d.ts

@@ -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 {
@@ -64,5 +73,13 @@ 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
+    | ICustomParseTreeNode;
 }

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;
@@ -71,9 +75,10 @@ declare module 'tiddlywiki' {
       /**
         Invoke the hook by key
       */
-      invokeHook(hookName: string): void;
+      invokeHook(hookName: string, event: IWidgetEvent): undefined | IWidgetEvent;
     };
 
+    language: ILanguage;
     modules: ITWModules;
     /** NodeJS features, if tw isn't running on a NodeJS environment, the value will be `null` */
     node: null | object;

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