tw5-typed 1.1.3 → 1.1.5

package/README.md

@@ -9,7 +9,7 @@ TypeScript type definitions for TiddlyWiki5.
 First, install it as dev-dependency:
 
 ```sh
-npm i -D tw5-typed
+pnpm add -D tw5-typed
 ```
 
 Add `tw5-typed` to your `tsconfig.json`'s `compilerOptions`
@@ -28,6 +28,40 @@ Then you will have global types like `$tw` automatically. You can import the res
 import type { ISearchOptions, SourceIterator, IFilterOperatorParamOperator } from 'tiddlywiki';
 ```
 
+If your project already has an ambient declaration file such as `src/global.d.ts` or `src/ambient.d.ts`, add this line there as well:
+
+```typescript
+/// <reference types="tw5-typed" />
+```
+
+That extra reference helps VS Code pick the package up reliably in template-based projects.
+
+## Troubleshooting
+
+If VS Code shows `Could not find a declaration file for module 'tiddlywiki'`, the usual cause is configuration, not missing types.
+
+Use this:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "tw5-typed"]
+  }
+}
+```
+
+Do not use this:
+
+```json
+{
+  "compilerOptions": {
+    "typeRoots": ["node_modules/@types", "node_modules/tw5-typed"]
+  }
+}
+```
+
+`tw5-typed` is a normal package with its own `types` entrypoint. Pointing `typeRoots` at the package directory can prevent TypeScript or VS Code from loading the `declare module 'tiddlywiki'` entry correctly.
+
 ### Alias
 
 Sometimes you may want to use a modified version of tw, you can re-export types like this in your `src/type.d.ts`:
@@ -58,6 +92,15 @@ You can add new `*.d.ts` file to contain your types:
 - add type import like `/// <reference path="parser.d.ts" />`
 - using normal import, like `import { parse } from './parser';` will not work
 
+Could import from `"tiddlywiki"` inside `declare module` like
+
+```ts
+declare module '$:/core/modules/utils/parsetree.js' {
+  import { IParseTreeNode } from 'tiddlywiki';
+```
+
+Import outside of `declare module` will cause error.
+
 ### Test in your node_modules
 
 To rapid prototype the type, just right click a type to open `.d.ts` file in the `node_modules`, and try create new file there, and copy to this repo after a success.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tw5-typed",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "scripts": {
     "check": "tsc --noEmit && eslint --max-warnings 0 \"src/**/*.ts\" \"src/**/*.d.ts\" \"test/**/*.ts\"",
     "docs": "docs-ts",

package/src/hooks.d.ts

@@ -8,6 +8,26 @@ declare module 'tiddlywiki' {
     type: string;
   }
 
+  interface NavigatingInfo {
+    navigateTo: string;
+    navigateFromTitle: string;
+    navigateFromClientRect: {
+      bottom: number;
+      height: number;
+      left: number;
+      right: number;
+      top: number;
+      width: number;
+    };
+    navigateFromClientTop: number;
+    navigateFromClientLeft: number;
+    navigateFromClientWidth: number;
+    navigateFromClientRight: number;
+    navigateFromClientBottom: number;
+    navigateFromClientHeight: number;
+    navigateSuppressNavigation: boolean;
+  }
+
   interface IHooks {
     /** Add hooks to the hashmap */
     addHook(
@@ -41,7 +61,13 @@ declare module 'tiddlywiki' {
         widget: Widget,
       ) => parseTreeNodes,
     );
-    addHook(hookName: 'th-navigating' | 'th-closing-tiddler' | 'th-editing-tiddler' | 'th-cancelling-tiddler' | 'th-new-tiddler', callback: (event: unknown) => unknown);
+    addHook(
+      hookName: 'th-navigating',
+      callback: (
+        event: NavigatingInfo & IWidgetEvent,
+      ) => NavigatingInfo & IWidgetEvent,
+    ): void;
+    addHook(hookName: 'th-closing-tiddler' | 'th-editing-tiddler' | 'th-cancelling-tiddler' | 'th-new-tiddler', callback: (event: unknown) => unknown);
     addHook(hookName: 'th-deleting-tiddler', callback: (title: Tiddler) => void);
     addHook(hookName: 'th-page-refreshed' | 'th-boot-tiddlers-loaded' | 'th-page-refreshing', callback: () => void);
     addHook(
@@ -53,6 +79,54 @@ declare module 'tiddlywiki' {
      * Invoke the hook by key
      */
     invokeHook(hookName: string, event: IWidgetEvent): undefined | IWidgetEvent;
+    /**
+     * Remove hooks
+     */
+    removeHook(
+      hookName: 'th-server-command-post-start',
+      callback: (
+        server: unknown,
+        nodeServer: HttpServer,
+        who: 'tiddlywiki',
+      ) => void,
+    ): void;
+    removeHook(
+      hookName: 'th-saving-tiddler' | 'th-renaming-tiddler' | 'th-relinking-tiddler',
+      callback: (toTiddler: Tiddler, fromTiddler: Tiddler) => Tiddler | undefined,
+    );
+    removeHook(
+      hookName: 'th-importing-tiddler' | 'th-before-importing',
+      callback: (tiddler: Tiddler) => Tiddler | undefined,
+    );
+    removeHook(
+      hookName: 'th-opening-default-tiddlers-list',
+      callback: (storyList: string[]) => string[],
+    );
+    removeHook(
+      hookName: 'th-make-tiddler-path',
+      callback: (fullPath: string, fullPath: string) => string,
+    );
+    removeHook(
+      hookName: 'th-rendering-element',
+      callback: (
+        parseTreeNodes: IParseTreeNode | null,
+        widget: Widget,
+      ) => parseTreeNodes,
+    );
+    removeHook(
+      hookName: 'th-navigating',
+      callback: (
+        event: NavigatingInfo & IWidgetEvent,
+      ) => NavigatingInfo & IWidgetEvent,
+    ): void;
+    removeHook(hookName: 'th-closing-tiddler' | 'th-editing-tiddler' | 'th-cancelling-tiddler' | 'th-new-tiddler', callback: (event: unknown) => unknown);
+    removeHook(hookName: 'th-deleting-tiddler', callback: (title: Tiddler) => void);
+    removeHook(hookName: 'th-page-refreshed' | 'th-boot-tiddlers-loaded' | 'th-page-refreshing', callback: () => void);
+    removeHook(
+      hookName: 'th-importing-file',
+      callback: (props: ImportFileInfo) => boolean | undefined,
+    );
+    removeHook(hookName: string, callback: (...arguments_: unknown[]) => unknown);
     names: Record<string, Array<(...arguments_: unknown[]) => unknown>>;
   }
 }

package/src/index.d.ts

@@ -13,12 +13,16 @@
 /// <reference path="./modules/parsers/index.d.ts" />
 /// <reference path="./modules/server/index.d.ts" />
 /// <reference path="./modules/story.d.ts" />
+/// <reference path="./modules/utils/index.d.ts" />
 /// <reference path="./modules/utils/filesystem.d.ts" />
 /// <reference path="./modules/utils/logger.d.ts" />
+/// <reference path="./modules/utils/dom/dom.d.ts" />
+/// <reference path="./modules/utils/dom/modal.d.ts" />
+/// <reference path="./modules/utils/dom/notifier.d.ts" />
+/// <reference path="./modules/utils/fakedom.d.ts" />
+/// <reference path="./modules/utils/linked-list.d.ts" />
 /// <reference path="./modules/syncer/syncadaptor.d.ts" />
 /// <reference path="./modules/syncer/syncer.d.ts" />
-/// <reference path="./modules/utils/dom/index.d.ts" />
-/// <reference path="./modules/utils/linked-list.d.ts" />
 /// <reference path="./modules/widgets/index.d.ts" />
 /// <reference path="./plugins/index.d.ts" />
 

package/src/modules/server/index.d.ts

@@ -1,6 +1,5 @@
-import type Http from 'http';
-
 declare module 'tiddlywiki' {
+  import type Http from 'http';
   export interface IServerStatus {
     anonymous: boolean;
     read_only: boolean;

package/src/modules/utils/index.d.ts

@@ -16,7 +16,7 @@ declare module 'tiddlywiki' {
   import * as editionInfo from '$:/core/modules/utils/edition-info.js';
   import * as escapecss from '$:/core/modules/utils/escapecss.js';
 
-  type IUtilitiesModules =
+  export type IUtilitiesModules =
     & Pick<typeof dom, keyof typeof dom>
     & Pick<typeof logger, keyof typeof logger>
     & Pick<typeof filesystem, keyof typeof filesystem>

package/src/modules/utils/performance.d.ts

@@ -1,6 +1,5 @@
-import { Logger } from '$:/core/modules/utils/logger.js';
-
 declare module '$:/core/modules/utils/performance.js' {
+  import { Logger } from '$:/core/modules/utils/logger.js';
   /**
    * A performance measurement utility.
    * @param enabled - Whether performance measurements are enabled.

package/src/modules/wiki.d.ts

@@ -120,10 +120,10 @@ declare module 'tiddlywiki' {
     getTiddlerList(title: string, field?: string, index?: string): string[];
     /**
      * Get the value of a text reference. Text references can have any of these forms:
-     * - <tiddlertitle>
-     * - <tiddlertitle>!!<fieldname>
-     * - !!<fieldname> - specifies a field of the current tiddlers
-     * - <tiddlertitle>##<index>
+     * - `tiddlertitle`
+     * - `tiddlertitle!!fieldname`
+     * - `!!fieldname` - specifies a field of the current tiddlers
+     * - `tiddlertitle##index`
      * @param textRef The text reference string
      * @param defaultText Default text to return if the reference is not found
      * @param currTiddlerTitle Current tiddler title for relative references

package/src/utils/index.d.ts

@@ -1,7 +1,6 @@
-import type { Logger } from '$:/core/modules/utils/logger.js';
-import { Spread } from 'type-fest';
-
 declare module 'tiddlywiki' {
+  import type { Logger } from '$:/core/modules/utils/logger.js';
+  import { Spread } from 'type-fest';
   export type TWDocument = Document | IFakeDocument;
   export type TWElement = Element;
   export type TWDOMElement = TWElement;
@@ -500,5 +499,6 @@ declare module 'tiddlywiki' {
     formatDateString: (date: Date, template: string) => string;
   }
 
+  import type { IUtilitiesModules } from 'tiddlywiki';
   export type IUtilities = IUtilitiesBoot & IUtilitiesModules;
 }