tw5-typed 0.2.1 → 0.2.4

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {
@@ -20,17 +20,17 @@
     "prepublishOnly": "npx tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^17.0.23",
-    "@typescript-eslint/eslint-plugin": "5.17.0",
-    "@typescript-eslint/parser": "5.17.0",
-    "eslint": "8.12.0",
+    "@types/node": "^17.0.24",
+    "@typescript-eslint/eslint-plugin": "5.19.0",
+    "@typescript-eslint/parser": "5.19.0",
+    "eslint": "8.13.0",
     "eslint-config-prettier": "8.5.0",
     "eslint-config-standard": "16.0.3",
     "eslint-config-standard-with-typescript": "21.0.1",
     "eslint-import-resolver-alias": "1.1.2",
-    "eslint-import-resolver-typescript": "2.7.0",
+    "eslint-import-resolver-typescript": "2.7.1",
     "eslint-plugin-html": "6.2.0",
-    "eslint-plugin-import": "2.25.4",
+    "eslint-plugin-import": "2.26.0",
     "eslint-plugin-n": "15.1.0",
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-prettier": "4.0.0",
@@ -41,7 +41,7 @@
     "eslint-plugin-security-node": "1.1.1",
     "eslint-plugin-typescript-sort-keys": "2.1.0",
     "eslint-plugin-unicorn": "42.0.0",
-    "prettier": "2.6.1",
+    "prettier": "2.6.2",
     "typescript": "4.6.3"
   }
 }

package/src/Wiki.d.ts

@@ -1,6 +1,17 @@
 /// <reference path="parser.d.ts" />
 
 declare module 'tiddlywiki' {
+  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 {
     /**
      * Wiki constructor. State is stored in private members that only a small number of privileged accessor methods have direct access. Methods added via the prototype have to use these accessors and cannot access the state data directly.
@@ -31,9 +42,9 @@ declare module 'tiddlywiki' {
      */
     addTiddler: (tiddler: Tiddler | Partial<ITiddlerFields>) => void;
     /**
-     * Call `addTiddler` for each iton of the list
+     * Call `addTiddler` for each iton of the list, but should passing `tiddler.fields`, directly passing tiddler object may failed to add in some cases.
      */
-    addTiddlers: (tiddler: Array<Tiddler | Partial<ITiddlerFields>>) => void;
+    addTiddlers: (tiddler: Array<Partial<ITiddlerFields>>) => void;
     /**
      * Get tiddler's text field, with an optional default text.
      * If have _is_skinny field, will just return null (this is a rare case, so not put in the return type for now).
@@ -43,6 +54,36 @@ declare module 'tiddlywiki' {
      */
     getTiddlerText(title: string, fallbackText: string): string;
     getTiddlerText(title: string, fallbackText?: string): string | undefined;
+    /**
+      Get the content of a tiddler as a JavaScript object. How this is done depends on the type of the tiddler:
+
+      application/json: the tiddler JSON is parsed into an object
+      application/x-tiddler-dictionary: the tiddler is parsed as sequence of name:value pairs
+
+      Other types currently just return undefined or as same as fallbackData.
+
+      titleOrTiddler: string tiddler title or a tiddler object
+      defaultData: default data to be returned if the tiddler is missing or doesn't contain data
+
+      Alternative, uncached version of getTiddlerDataCached(). The return value can be mutated freely and reused
+    */
+    getTiddlerData<D extends Record<string, unknown> | undefined>(titleOrTiddler: string, fallbackData?: D): D;
+    getTiddlerData<D extends Record<string, unknown> | undefined>(titleOrTiddler: Tiddler, fallbackData?: D): D;
+    /**
+      Get the content of a tiddler as a JavaScript object. How this is done depends on the type of the tiddler:
+
+      application/json: the tiddler JSON is parsed into an object
+      application/x-tiddler-dictionary: the tiddler is parsed as sequence of name:value pairs
+
+      Other types currently just return undefined or as same as fallbackData.
+
+      titleOrTiddler: string tiddler title or a tiddler object
+      defaultData: default data to be returned if the tiddler is missing or doesn't contain data
+
+      Note that the same value is returned for repeated calls for the same tiddler data. The value is frozen to prevent modification; otherwise modifications would be visible to all callers
+    */
+    getTiddlerDataCached<D extends Record<string, unknown> | undefined>(titleOrTiddler: string, fallbackData?: D): D;
+    getTiddlerDataCached<D extends Record<string, unknown> | undefined>(titleOrTiddler: Tiddler, fallbackData?: D): D;
     /**
      * Set tiddler text of any field.
      *
@@ -52,8 +93,68 @@ 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;
+    /**
+      Parse text from a tiddler and render it into another format
+        outputType: content type for the output
+        title: title of the tiddler to be rendered
+        options: see below
+      Options include:
+      variables: hashmap of variables to set
+      parentWidget: optional parent widget for the root node
+      */
+    renderTiddler(outputType: OutputMimeTypes, title: string, options?: IRenderOptions): string;
+    /**
+      Make a widget tree for a parse tree
+      @params parser: parser object
+      @params options: see below
+      Options include:
+      document: optional document to use
+      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
+      @params title: target tiddler title
+      @params options: as for wiki.makeWidget() plus:
+
+      - options.field: optional field to transclude (defaults to "text")
+      - options.mode: transclusion mode "inline" or "block"
+      - options.recursionMarker : optional flag to set a recursion marker, defaults to "yes"
+      - options.children: optional array of children for the transclude widget
+      - options.importVariables: optional importvariables filter string for macros to be included
+      - options.importPageMacros: optional boolean; if true, equivalent to passing "[[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]]" to options.importVariables
+      */
+    makeTranscludeWidget(
+      title: string,
+      options: {
+        /**  optional array of children for the transclude widget */
+        children?: Widget[];
+        /** optional field to transclude (defaults to "text") */
+        field?: string;
+        /**  optional boolean; if true, equivalent to passing "[[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]]" to options.importVariables */
+        importPageMacros?: boolean;
+        /**  optional importvariables filter string for macros to be included */
+        importVariables?: string;
+        /**  transclusion mode "inline" or "block" */
+        mode?: 'inline' | 'block';
+        /**  optional flag to set a recursion marker, defaults to "yes" */
+        recursionMarker?: 'yes' | 'no';
+      } & IMakeWidgetOptions,
+    ): Widget;
   }
 }

package/src/server.d.ts

@@ -74,14 +74,14 @@ declare module 'tiddlywiki' {
     variables: Record<string, any>;
     get(variableName: string): any;
     requestHandler: ServerEndpointHandler;
-    /*
+    /**
       Listen for requests
       port: optional port number (falls back to value of "port" variable)
       host: optional host address (falls back to value of "host" variable)
       prefix: optional prefix (falls back to value of "path-prefix" variable)
       */
     listen(port?: string, host?: string, prefix?: string): 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
     */
     isAuthorized(authorizationType: 'readers' | 'writers', username?: string | undefined): boolean;

package/src/tw.d.ts

@@ -59,9 +59,19 @@ declare module 'tiddlywiki' {
 
     config: ITWConfig;
 
+    /**
+      Global Hooks mechanism which allows plugins to modify default functionality
+    */
     hooks: {
+      /**
+        Add hooks to the  hashmap
+      */
       addHook(hookName: 'th-server-command-post-start', callback: (listenCommand: unknown, server: Server) => void): void;
       addHook(hookName: string, callback: (...arguments_: unknown[]) => unknown): void;
+      /**
+        Invoke the hook by key
+      */
+      invokeHook(hookName: string): void;
     };
 
     modules: ITWModules;
@@ -70,17 +80,18 @@ declare module 'tiddlywiki' {
     /** Broswer features, if tw isn't running on a browser environment, the value will be `null` */
     nodeWebKit: null | object;
 
+    notifier: Notifier;
     /** Convenience function for pushing a tiddler onto the preloading array */
     preloadTiddler(fields: Record<string, unknown>): void;
     /** Convenience function for pushing an array of tiddlers onto the preloading array */
     preloadTiddlerArray(fieldsArray: Array<Record<string, unknown>>): void;
+
     /** External JavaScript can populate this array before calling boot.js in order to preload tiddlers */
     preloadTiddlers: Record<string, Record<string, unknown>>;
 
     rootWidget: Widget;
 
     utils: ITWUtils;
-
     version: string;
     wiki: Wiki;
   }

package/src/utils.d.ts

@@ -15,6 +15,20 @@ declare module 'tiddlywiki' {
      * @param className
      */
     addClass(element: Element, className: string): void;
+    /**
+      Attach specified event handlers to a DOM node
+      @param domNode: where to attach the event handlers
+      @param events: array of event handlers to be added (see below)
+      Each entry in the events array is an object with these properties:
+      - name: event name of `addEventListener`
+      - handlerFunction: optional event handler function
+      - handlerObject: optional event handler object
+      - handlerMethod: optionally specifies object handler method name (defaults to `handleEvent`)
+    */
+    addEventListeners(
+      domNode: Node,
+      events: Array<{ handlerFunction?: (event: MouseEvent) => void; handlerMethod?: string; handlerObject?: Widget; name: string }>,
+    ): void;
     /** Returns true if the version string A is greater than the version string B. Returns true if the versions are the same */
     checkVersions(versionStringA: string, versionStringB: string): boolean;
     /**
@@ -26,8 +40,6 @@ declare module 'tiddlywiki' {
     decodeURIComponentSafe(uri: string): string;
     /** Convert a URI encoded string to a string safely */
     decodeURISafe(uri: string): string;
-    /** the function behind `<<now "format">> */
-    formatDateString(date: Date, format: string): string;
     /** Fill in any null or undefined properties of an object with the properties from a list of source objects. Each property that is an object is called recursively */
     deepDefaults(object: object, ...sourceObjectList: object[]): object;
     /**
@@ -82,6 +94,8 @@ declare module 'tiddlywiki' {
     evalSandboxed(code: string, context: IModuleSandbox, filename: string): unknown;
     /** Extend an object with the properties from a list of source objects */
     extend(object: object, ...sourceObjectList: object[]): object;
+    /** the function behind `<<now "format">> */
+    formatDateString(date: Date, format: string): string;
     /** Given an extension, always access the $tw.config.fileExtensionInfo using a lowercase extension only. */
     getFileExtensionInfo(extension: string): IFileExtensionInfo | null;
     /** Get the browser location.hash. We don't use location.hash because of the way that Firefox auto-urldecodes it (see http://stackoverflow.com/questions/1703552/encoding-of-window-location-hash) */
@@ -154,4 +168,16 @@ declare module 'tiddlywiki' {
     /** Stringify an array of tiddler titles into a list string */
     stringifyList(value: string[]): string;
   }
+  /**
+   * Notifier mechanism
+   */
+  export class Notifier {
+    /*
+      Display a notification
+        title: Title of tiddler containing the notification text
+        options: see below
+      Options include:
+      */
+    display(title: string, options?: Record<string, unknown>): void;
+  }
 }

package/src/widget.d.ts

@@ -9,26 +9,26 @@ declare module 'tiddlywiki' {
   }
 
   export interface IWidgetEvent {
-    /** widget event can carry any other parameters
+    /** maybe a DOM click event, if trigger by button click */
+    event: Event;
+    navigateFromTitle?: string;
+    /**
+     * Get `$param`
+     */
+    param?: string | undefined;
+    /** Optional hashmap of additional tiddler fields. Widget event can carry any other parameters
      *
      * For example, `<$action-sendmessage $message="tw-mobile-sync-set-active-server-and-sync" title={{!!title}} />` will produce `paramObject: { title: "xxxx" }`
      */
     paramObject?: {
       [othersParamKeys: string]: unknown;
     };
-    /**
-     * Get `$param`
-     */
-    param?: string | undefined;
     /** the first parameter of addEventListener
      *
      * For example, the `'open-command-palette'` in `$tw.rootWidget.addEventListener('open-command-palette', (e: IWidgetEvent) => this.openPalette(e));`
      */
     type: string;
     widget: Widget;
-    /** maybe a DOM click event, if trigger by button click */
-    event: Event;
-    navigateFromTitle?: string;
   }
 
   // eslint-disable-next-line @typescript-eslint/no-extraneous-class
@@ -38,11 +38,22 @@ declare module 'tiddlywiki' {
    * @link https://tiddlywiki.com/dev/#Widgets
    */
   export class Widget {
-    constructor(parseTreeNode: unknown, options: unknown);
-    initialize: (parseTreeNode: unknown, options: unknown) => void;
-    parseTreeNode: unknown;
-    wiki: unknown;
+    constructor(parseTreeNode: IParseTreeNode, options?: unknown);
+    initialize: (parseTreeNode: IParseTreeNode, options?: unknown) => void;
+    parseTreeNode: IParseTreeNode;
+    wiki: ITiddlyWiki;
     parentWidget?: 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
+      options include:
+        variables: optional hashmap of variables to wrap around the widget
+    */
+    makeChildWidget(parseTreeNode: IParseTreeNode, options?: { variables?: unknown }): void;
     variablesConstructor: variablesConstructor;
     variables: unknown;
     domNodes: Node[];
@@ -65,7 +76,7 @@ declare module 'tiddlywiki' {
     /**
      * Lifecycle method: Render this widget into the DOM
      */
-    render(parent: Node, nextSibling: Node): void;
+    render(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.
@@ -73,6 +84,15 @@ declare module 'tiddlywiki' {
      * @link https://tiddlywiki.com/dev/#Selective%20Update
      */
     refresh(changedTiddlers: IChangedTiddlers): boolean;
+    /**
+      Refresh all the children of a widget
+      will call `this.render`
+    */
+    refreshChildren(changedTiddlers: IChangedTiddlers): boolean;
+    /**
+      Rebuild a previously rendered widget
+    */
+    refreshSelf(): boolean;
     computeAttributes(): void;
     /**
      * Get parameters that user set in the widget
@@ -97,4 +117,25 @@ declare module 'tiddlywiki' {
      */
     getVariable(name: string, options?: object): string;
   }
+
+  export interface IFakeDocument {
+    compatMode: string;
+    createElement: (tag: string) => TW_Element;
+    createElementNS: (namespace: string, tag: string) => TW_Element;
+    createTextNode: (text: string) => TW_TextNode;
+    isTiddlyWikiFakeDom: boolean;
+    setSequenceNumber: (value: any) => void;
+  }
+  export class TW_Element {
+    isTiddlyWikiFakeDom: boolean;
+    tag: string;
+    attributes: Record<string, unknown>;
+    isRaw: boolean;
+    children: Array<TW_Element | TW_TextNode>;
+    _style: Record<string, unknown>;
+    namespaceURI: string;
+  }
+  export class TW_TextNode {
+    textContent: string;
+  }
 }