tw5-typed 0.2.3 → 0.2.6

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {
@@ -20,24 +20,24 @@
     "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.29",
+    "@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",

package/src/Wiki.d.ts

@@ -1,9 +1,15 @@
 /// <reference path="parser.d.ts" />
 
 declare module 'tiddlywiki' {
-  export interface IMakeWidgetOptions {
+  export interface IMakeWidgetOptions extends IRenderOptions {
     document: typeof document | IFakeDocument;
+  }
+
+  export type OutputMimeTypes = 'text/html' | 'text/plain-formatted' | 'text/plain';
+  export type TextMimeTypes = 'text/html' | 'text/vnd.tiddlywiki' | 'text/plain';
+  export interface IRenderOptions {
     parentWidget?: Widget;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     variables?: Record<string, any>;
   }
   export class Wiki {
@@ -19,7 +25,24 @@ 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.
@@ -87,7 +110,7 @@ declare module 'tiddlywiki' {
      * @param {string} value text content to set
      * @param {object} options options, see tiddlywiki dev doc for details
      */
-    setText: (title: string, field?: string, index?: string | undefined, value?: string, options?: any) => void;
+    setText: (title: string, field?: string, index?: string | undefined, value?: string, options?: { suppressTimestamp?: boolean }) => void;
     parseTiddler(title: string, options?: IParserOptions): WikiParser;
     parseText(type: string, text: string, options?: IParserOptions): WikiParser;
     /**
@@ -99,11 +122,7 @@ declare module 'tiddlywiki' {
       variables: hashmap of variables to set
       parentWidget: optional parent widget for the root node
       */
-    renderTiddler(
-      outputType: 'text/html' | 'text/plain-formatted' | 'text/plain',
-      title: string,
-      options?: { parentWidget?: Widget; variables?: Record<string, any> },
-    ): string;
+    renderTiddler(outputType: OutputMimeTypes, title: string, options?: IRenderOptions): string;
     /**
       Make a widget tree for a parse tree
       @params parser: parser object
@@ -113,6 +132,17 @@ 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

@@ -25,6 +25,15 @@ declare module 'tiddlywiki' {
     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/widget.d.ts

@@ -39,15 +39,23 @@ 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;
+    /**
+      Make child widgets correspondng to specified parseTreeNodes
+      @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
       options include:
@@ -71,12 +79,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 +112,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