Cleanup JS api types

mkdocs-website/docs/en/changelog.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [darwin] add getPrimaryScreen/getScreens to impl by @tmclane in
  [#2618](https://github.com/wailsapp/wails/pull/2618)
 - [linux] add onKeyPress logic to convert linux keypress into an accelerator @[Atterpac](https://github.com/Atterpac) in[#3022](https://github.com/wailsapp/wails/pull/3022])
+- [js] add types for npm package and make imports align with the documentation by [@jpatters](https://github.com/jpatters) in [#3131](https://github.com/wailsapp/wails/pull/3131)
 
 ### Fixed
 

v3/internal/runtime/.gitignore

@@ -1,2 +1,3 @@
 node_modules
-.task
+.task
+desktop/api/types

v3/internal/runtime/Taskfile.yaml

@@ -18,6 +18,13 @@ tasks:
  cmds:
  - npx npm-check-updates -u
 
+ build:types:
+ internal: true
+ cmds:
+ - rm -rf desktop/api/types
+ - npx -p typescript tsc desktop/api/*.js --declaration --allowJs --emitDeclarationOnly --outDir desktop/api/types
+ - cp desktop/api/wails.d.ts desktop/api/types/wails.d.ts
+
  build:debug:
  internal: true
  cmds:
@@ -91,6 +98,7 @@ tasks:
  build:all:
  internal: true
  deps:
+ - build:types
  - build:debug:windows
  - build:debug:linux
  - build:debug:darwin

v3/internal/runtime/desktop/api/README.md

@@ -1,6 +1,6 @@
 # Wails API
 
-This package provides a typed Javascript API for Wails applications. 
+This package provides a typed Javascript API for Wails applications.
 
 It provides methods for the following components:
 
@@ -63,7 +63,7 @@ function example() {
 
 #### Message Dialogs
 
-Message dialogs are used to display a message to the user. 
+Message dialogs are used to display a message to the user.
 They can be used to display information, errors, warnings and questions.
 Each method returns the button that was pressed by the user.
 
@@ -88,9 +88,9 @@ The Save Dialog is used to save a file. It returns the path of the selected file
 
 ### Events
 
-The Events API provides access to the Wails event system. This is a global event system 
+The Events API provides access to the Wails event system. This is a global event system
 that can be used to send events between the Go and Javascript.
-Events are available to every window in a multi-window application. 
+Events are available to every window in a multi-window application.
 These API methods are specific to the window in which they are called in.
 
 ```javascript
@@ -99,12 +99,12 @@ import { Events } from "@wailsapp/api";
 function example() {
  // Emit an event
  Events.Emit("myevent", { message: "Hello" });
- 
+
  // Subscribe to an event
  let unsub = Events.On("otherEvent", (data) => {
  console.log("Received event: " + data);
  });
- 
+
  // Unsubscribe from the event
  unsub();
 }
@@ -118,8 +118,8 @@ Emit an event with optional data.
 
 #### Subscribe
 
-Three methods are provided to subscribe to an event: 
- - `On(eventName: string, callback: (data: any) => void): () => void` - Subscribe to all events of the given name 
+Three methods are provided to subscribe to an event:
+ - `On(eventName: string, callback: (data: any) => void): () => void` - Subscribe to all events of the given name
  - `Once(eventName: string, callback: (data: any) => void): () => void` - Subscribe to one event of the given name
  - `OnMultiple(eventName: string, callback: (data: any) => void, count: number): () => void` - Subscribe to multiple events of the given name
 
@@ -161,7 +161,7 @@ The Window API provides a number of methods that interact with the window in whi
 
 ### Plugin
 
-The Plugin API provides access to the Wails plugin system. 
+The Plugin API provides access to the Wails plugin system.
 This method provides the ability to call a plugin method from the frontend.
 
 ```javascript
@@ -179,7 +179,7 @@ function example() {
 ### Screens
 
 The Screens API provides access to the Wails screen system.
- 
+
 ```javascript
 import { Screens } from "@wailsapp/api";
 
@@ -188,12 +188,12 @@ function example() {
  Screens.GetAll().then((screens) => {
  console.log("Screens: " + screens);
  });
- 
+
  // Get the primary screen
  Screens.GetPrimary().then((screen) => {
  console.log("Primary screen: " + screen);
  });
- 
+
  // Get the screen the window is on
  Screens.GetCurrent().then((screen) => {
  console.log("Window screen: " + screen);
@@ -213,151 +213,19 @@ The Application API provides access to the Wails application system.
 import { Application } from "@wailsapp/api";
 
 function example() {
- 
+
  // Hide the application
  Application.Hide();
- 
+
  // Shopw the application
  Application.Show();
- 
+
  // Quit the application
  Application.Quit();
- 
+
 }
 ```
 
 - `Hide: () => void` - Hide the application
 - `Show: () => void` - Show the application
 - `Quit: () => void` - Quit the application
-
-## Types
-
-This is a comprehensive list of types used by the Wails API.
-
-```typescript
-
-export interface Button {
- // The label of the button
- Label?: string;
- // True if this button is the cancel button (selected when pressing escape)
- IsCancel?: boolean;
- // True if this button is the default button (selected when pressing enter)
- IsDefault?: boolean;
-}
-
-interface MessageDialogOptions {
- // The title for the dialog
- Title?: string;
- // The message to display
- Message?: string;
- // The buttons to use on the dialog
- Buttons?: Button[];
-}
-
-export interface OpenFileDialogOptions {
- // Allows the user to be able to select directories
- CanChooseDirectories?: boolean;
- // Allows the user to be able to select files
- CanChooseFiles?: boolean;
- // Provide an option to create directories in the dialog
- CanCreateDirectories?: boolean;
- // Makes the dialog show hidden files
- ShowHiddenFiles?: boolean;
- // Whether the dialog should follow filesystem aliases
- ResolvesAliases?: boolean;
- // Allow the user to select multiple files or directories
- AllowsMultipleSelection?: boolean;
- // Hide the extension when showing the filename
- HideExtension?: boolean;
- // Allow the user to select files where the system hides their extensions
- CanSelectHiddenExtension?: boolean;
- // Treats file packages as directories, e.g. .app on macOS
- TreatsFilePackagesAsDirectories?: boolean;
- // Allows selection of filetypes not specified in the filters
- AllowsOtherFiletypes?: boolean;
- // The file filters to use in the dialog
- Filters?: FileFilter[];
- // The title of the dialog
- Title?: string;
- // The message to display
- Message?: string;
- // The label for the select button
- ButtonText?: string;
- // The default directory to open the dialog in
- Directory?: string;
-}
-export interface FileFilter {
- // The display name for the filter, e.g. "Text Files"
- DisplayName?: string;
- // The pattern to use for the filter, e.g. "*.txt;*.md"
- Pattern?: string;
-}
-export interface SaveFileDialogOptions {
- // Provide an option to create directories in the dialog
- CanCreateDirectories?: boolean;
- // Makes the dialog show hidden files
- ShowHiddenFiles?: boolean;
- // Allow the user to select files where the system hides their extensions
- CanSelectHiddenExtension?: boolean;
- // Allows selection of filetypes not specified in the filters
- AllowOtherFiletypes?: boolean;
- // Hide the extension when showing the filename
- HideExtension?: boolean;
- // Treats file packages as directories, e.g. .app on macOS
- TreatsFilePackagesAsDirectories?: boolean;
- // The message to show in the dialog
- Message?: string;
- // The default directory to open the dialog in
- Directory?: string;
- // The default filename to use in the dialog
- Filename?: string;
- // The label for the select button
- ButtonText?: string;
-}
-
-export interface Screen {
- // The screen ID
- Id: string;
- // The screen name
- Name: string;
- // The screen scale. 1 = standard resolution, 2: 2x retina, etc.
- Scale: number;
- // The X position of the screen
- X: number;
- // The Y position of the screen
- Y: number;
- // The width and height of the screen
- Size: Size;
- // The bounds of the screen
- Bounds: Rect;
- // The work area of the screen
- WorkArea: Rect;
- // True if this is the primary screen
- IsPrimary: boolean;
- // The rotation of the screen
- Rotation: number;
-}
-export interface Rect {
- X: number;
- Y: number;
- Width: number;
- Height: number;
-}
-
-export interface WailsEvent {
- // The name of the event
- Name: string;
- // The data associated with the event
- Data?: any;
-}
-
-export interface Size {
- Width: number;
- Height: number;
-}
-export interface Position {
- X: number;
- Y: number;
-}
-
-```

v3/internal/runtime/desktop/api/application.js

@@ -16,20 +16,17 @@ The electron alternative for Go
 export const Application = {
  /**
  * Hides the application
+ * @returns {Promise<void>}
  */
- Hide: () => {
- return wails.Application.Hide();
- },
+ Hide: () => wails.Application.Hide(),
  /**
  * Shows the application
+ * @returns {Promise<void>}
  */
- Show: () => {
- return wails.Application.Show();
- },
+ Show: () => wails.Application.Show(),
  /**
  * Quits the application
+ * @returns {Promise<void>}
  */
- Quit: () => {
- return wails.Application.Quit();
- },
+ Quit: () => wails.Application.Quit(),
 };

v3/internal/runtime/desktop/api/browser.js

@@ -16,9 +16,8 @@ The electron alternative for Go
 export const Browser = {
  /**
  * Opens a browser window to the given URL
- * @returns {Promise<string>}
+ * @param {string} url - the url to open
+ * @returns {Promise<void>}
  */
- OpenURL: (url) => {
- return wails.Browser.OpenURL(url);
- },
+ OpenURL: (url) => wails.Browser.OpenURL(url),
 };

v3/internal/runtime/desktop/api/clipboard.js

@@ -18,14 +18,11 @@ export const Clipboard = {
  * Gets the text from the clipboard
  * @returns {Promise<string>}
  */
- Text: () => {
- return wails.Clipboard.Text();
- },
+ Text: () => wails.Clipboard.Text(),
  /**
  * Sets the text on the clipboard
  * @param {string} text - text to set in the clipboard
+ * @returns {Promise<void>}
  */
- SetText: (text) => {
- return wails.Clipboard.SetText(text);
- },
+ SetText: (text) => wails.Clipboard.SetText(text),
 };