tw5-typed 0.2.8 → 0.2.10

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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.31",
-    "@typescript-eslint/eslint-plugin": "5.22.0",
-    "@typescript-eslint/parser": "5.22.0",
-    "eslint": "8.15.0",
+    "@types/node": "^18.11.9",
+    "@typescript-eslint/eslint-plugin": "5.44.0",
+    "@typescript-eslint/parser": "5.44.0",
+    "eslint": "8.28.0",
     "eslint-config-prettier": "8.5.0",
     "eslint-config-standard": "17.0.0",
-    "eslint-config-standard-with-typescript": "21.0.1",
+    "eslint-config-standard-with-typescript": "23.0.0",
     "eslint-import-resolver-alias": "1.1.2",
-    "eslint-import-resolver-typescript": "2.7.1",
-    "eslint-plugin-html": "6.2.0",
+    "eslint-import-resolver-typescript": "3.5.2",
+    "eslint-plugin-html": "7.1.0",
     "eslint-plugin-import": "2.26.0",
-    "eslint-plugin-n": "15.2.0",
+    "eslint-plugin-n": "15.5.1",
     "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.5.0",
+    "eslint-plugin-prettier": "4.2.1",
+    "eslint-plugin-promise": "6.1.1",
+    "eslint-plugin-react": "7.31.11",
+    "eslint-plugin-react-hooks": "4.6.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.4"
+    "eslint-plugin-unicorn": "45.0.0",
+    "prettier": "2.8.0",
+    "typescript": "4.9.3"
   }
 }

package/src/Wiki.d.ts

@@ -95,10 +95,12 @@ declare module 'tiddlywiki' {
 
       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;
+    getTiddlerData<D extends Record<any, unknown> | any[] | undefined>(titleOrTiddler: string, fallbackData?: D): D;
+    getTiddlerData<D extends Record<any, unknown> | any[] | 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:
+     * D is any JSON, like JSON object or JSON array
+     * 
+     * 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
@@ -110,8 +112,8 @@ declare module 'tiddlywiki' {
 
       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;
+    getTiddlerDataCached<D>(titleOrTiddler: string, fallbackData?: D): D;
+    getTiddlerDataCached<D>(titleOrTiddler: Tiddler, fallbackData?: D): D;
     /**
      * Set tiddler text of any field.
      *
@@ -196,5 +198,11 @@ declare module 'tiddlywiki' {
         recursionMarker?: 'yes' | 'no';
       } & IMakeWidgetOptions,
     ): Widget;
+    /** Test for the existence of a tiddler (excludes shadow tiddlers) */
+    tiddlerExists(title: string): boolean;
+    /** Determines if a tiddler is a shadow tiddler, regardless of whether it has been overridden by a real tiddler */
+    isShadowTiddler(title: string): boolean;
+    /** return shadowTiddlers[title].source; */
+    getShadowSource(title: string): string | null;
   }
 }

package/src/ast.d.ts

@@ -3,8 +3,8 @@ declare module 'tiddlywiki' {
     end?: number;
     name?: string;
     start?: number;
-    type: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
-    value: string;
+    type: 'string' | 'number' | 'bigint' | 'boolean' | 'macro' | 'macro-parameter';
+    value: string | IMacroCallParseTreeNode;
   }
 
   export interface IWikiASTNode {
@@ -12,6 +12,7 @@ declare module 'tiddlywiki' {
     children?: IParseTreeNode[];
     end?: number;
     isBlock?: boolean;
+    isMacroDefinition?: boolean;
     isSelfClosing?: boolean;
     orderedAttributes?: IParseTreeAttribute[];
     start?: number;
@@ -59,10 +60,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;
@@ -70,6 +78,7 @@ declare module 'tiddlywiki' {
     type: string;
   }
   export type IParseTreeNode =
+    | IWikiASTNode
     | IDomParseTreeNode
     | IMacroParameterCallParseTreeNode
     | IMacroCallParseTreeNode
@@ -79,5 +88,7 @@ declare module 'tiddlywiki' {
     | ITiddlerParseTreeNode
     | ICodeBlockParseTreeNode
     | ILinkParseTreeNode
-    | ICustomParseTreeNode;
+    | ICustomParseTreeNode
+    | IMacroParseTreeNode
+    | IParseTreeAttribute;
 }

package/src/tw.d.ts

@@ -59,7 +59,43 @@ 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;
 

package/src/utils.d.ts

@@ -39,6 +39,10 @@ declare module 'tiddlywiki' {
      * Missing or malformed version strings are parsed as 0.0.0
      */
     compareVersions(versionStringA: string, versionStringB: string): -1 | 0 | 1;
+    /*
+      Return the number of keys in an object
+    */
+    count(object: Record<string, any>): number;
     /** Convert a URIComponent encoded string to a string safely */
     decodeURIComponentSafe(uri: string): string;
     /** Convert a URI encoded string to a string safely */

package/src/widget.d.ts

@@ -12,6 +12,7 @@ declare module 'tiddlywiki' {
     [extraKeys: string]: unknown;
     /** maybe a DOM click event, if trigger by button click */
     event: UIEvent | Event;
+    name: string;
     navigateFromTitle?: string;
     /**
      * Get `$param`
@@ -44,9 +45,13 @@ declare module 'tiddlywiki' {
     initialize(parseTreeNode: IParseTreeNode, options?: unknown): void;
     parseTreeNode: IParseTreeNode;
     wiki: ITiddlyWiki;
+    document: IFakeDocument;
     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`
@@ -59,6 +64,13 @@ declare module 'tiddlywiki' {
       @param parseTreeNodes default to `this.parseTreeNode.children`, can be undefined
     */
     makeChildWidgets(parseTreeNodes?: IParseTreeNode[], options?: { variables?: unknown }): void;
+    /**
+     * 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:
@@ -74,6 +86,8 @@ declare module 'tiddlywiki' {
     addEventListener(type: string, handler: (event: IWidgetEvent) => void | Promise<void>): void;
     /**
       Dispatch an event to a widget. If the widget doesn't handle the event then it is also dispatched to the parent widget
+
+      Events added via `addEventListener`, like `tm-notify`, can be invoked by this.
     */
     dispatchEvent(typeOrEvent: string | Omit<IWidgetEvent, 'widget'>): void;
     /**
@@ -90,6 +104,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
@@ -112,9 +143,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
@@ -148,16 +188,15 @@ declare module 'tiddlywiki' {
     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>;
+  export interface TW_Element extends HTMLElement {
     _style: Record<string, unknown>;
+    appendChild: <T extends TW_Element | TW_TextNode | Node>(node: T) => T;
+    isRaw: boolean;
+    isTiddlyWikiFakeDom: boolean;
     namespaceURI: string;
+    tag: string;
   }
-  export class TW_TextNode {
+  export interface TW_TextNode extends Node {
     textContent: string;
   }
 }