v3.0.0-alpha.2

* remove 'test' project

* dynamic template list generation

- uses a single fs.Embed to contain all templates
- walks and rebuilds the list of TemplateData using the cached data
- pulls the `description` out of the required `template.json` file in
  the template directory

* [v3] template handling update

- move "common" template files to a _common directory
- update generator to render from _common/* first
- render selected template last to overwrite anything provided by
  _common if needed
- remove duplicate files from all templates that do not change

* cleanup template project directory after test

* add linux to _common/Taskfile.yaml

* noop: whitespace cleanup _common/Taskfile.yaml

.github/workflows/build-and-test-alpha.yml

@@ -0,0 +1,140 @@
+name: Build + Test v3 alpha
+
+on:
+  push:
+    branches: [v3-alpha]
+    paths-ignore:
+      - 'mkdocs-website/**/*'
+  workflow_dispatch:
+
+jobs:
+  test_go:
+    name: Run Go Tests
+    if: github.repository == 'wailsapp/wails'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest, ubuntu-latest]
+        go-version: [1.21]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Install linux dependencies
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get update -y && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev javascriptcoregtk-4.1-dev build-essential pkg-config
+
+      - name: Setup Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build Examples
+        working-directory: ./v3
+        run: task test:examples
+
+      - name: Run tests (mac)
+        if: matrix.os == 'macos-latest'
+        env:
+          CGO_LDFLAGS: -framework UniformTypeIdentifiers -mmacosx-version-min=10.13
+        working-directory: ./v3
+        run: go test -v ./...
+
+      - name: Run tests (!mac)
+        if: matrix.os != 'macos-latest'
+        working-directory: ./v3
+        run: go test -v ./...
+
+  test_js:
+    name: Run JS Tests
+    if: github.repository == 'wailsapp/wails'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+        working-directory: v2/internal/frontend/runtime
+
+      - name: Run tests
+        run: npm test
+        working-directory: v2/internal/frontend/runtime
+
+  test_templates:
+    name: Test Templates
+    needs: test_go
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        template:
+          [
+            svelte,
+            svelte-ts,
+            vue,
+            vue-ts,
+            react,
+            react-ts,
+            preact,
+            preact-ts,
+            lit,
+            lit-ts,
+            vanilla,
+            vanilla-ts,
+          ]
+        go-version: [1.21]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Setup Golang caches
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: ${{ runner.os }}-golang-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-golang-
+
+      - name: Install linux dependencies
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get update -y && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev javascriptcoregtk-4.1-dev build-essential pkg-config
+
+      - name: Build Wails3 CLI
+        run: |
+          cd ./v3/cmd/wails3
+          go install
+          wails3 -help
+
+      - name: Generate template '${{ matrix.template }}'
+        run: |
+          go install github.com/go-task/task/v3/cmd/task@latest 
+          mkdir -p ./test-${{ matrix.template }}
+          cd ./test-${{ matrix.template }}
+          wails3 init -n ${{ matrix.template }} -t ${{ matrix.template }}
+          cd ${{ matrix.template }}
+          wails3 build

.github/workflows/v3-docs.yml

@@ -0,0 +1,35 @@
+name: v3 docs
+on:
+  push:
+    branches:
+      - v3-alpha
+    paths:
+      - 'mkdocs-website/**/*'
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+    defaults:
+      run:
+        working-directory: ./mkdocs-website
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: sudo apt-get install pngquant
+      - run: pip install pillow cairosvg mkdocs-table-reader-plugin mkdocs-static-i18n
+      - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+      - run: mkdocs build --config-file mkdocs.insiders.yml
+      - run: mkdocs gh-deploy --force
+env:
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}

CNAME

@@ -0,0 +1 @@
+v3alpha.wails.io

Taskfile.yaml

@@ -16,6 +16,11 @@ includes:
     dir: v3
     optional: true
 
+  docs:
+    taskfile: mkdocs-website
+    dir: mkdocs-website
+    optional: true
+
 tasks:
   contributors:check:
     cmds:

mkdocs-website/CNAME

@@ -0,0 +1 @@
+v3alpha.wails.io

mkdocs-website/README.md

@@ -0,0 +1,45 @@
+# v3 Docs
+
+This is the documentation for Wails v3. It is currently a work in progress.
+
+If you do not wish to build it locally, it is available online at
+[https://wailsapp.github.io/wails/](https://wailsapp.github.io/wails/).
+
+## Recommended Setup Steps
+
+Install the wails3 CLI if you haven't already:
+
+```shell
+go install github.com/wailsapp/wails/v3/cmd/wails3@latest
+```
+
+The documentation uses mkdocs, so you will need to install
+[Python](https://www.python.org/). Once installed, you can setup the
+documentation by running the following command:
+
+```bash
+wails3 task docs:setup
+```
+
+This will install the required dependencies for you.
+
+If you have installed the wails3 CLI, you can run the following command to build
+the documentation and serve it locally:
+
+```bash
+wails3 task docs:serve
+```
+
+### Manual Setup
+
+To install manually, you will need to do the following:
+
+- Install [Python](https://www.python.org/)
+- Run `pip install -r requirements.txt` to install the required dependencies
+- Run `mkdocs serve` to serve the documentation locally
+- Run `mkdocs build` to build the documentation
+
+## Contributing
+
+If you would like to contribute to the documentation, please feel free to open a
+PR!

mkdocs-website/Taskfile.yml

@@ -0,0 +1,59 @@
+# https://taskfile.dev
+
+version: '3'
+
+tasks:
+
+  setup:
+    summary: Setup the project
+    preconditions:
+      - sh: python{{exeExt}} --version
+        msg: "Looks like Python isn't installed. Python is required to build the documentation: https://www.python.org/downloads/"
+    cmds:
+      - python -m pip install -r requirements.txt --user
+
+  setup:insiders:
+    summary: Setup the project (insiders)
+    preconditions:
+      - sh: python{{exeExt}} --version
+        msg: "Looks like Python isn't installed. Python is required to build the documentation: https://www.python.org/downloads/"
+    cmds:
+      - python -m pip install -r requirements.insiders.txt --user
+
+  upgrade:insiders:
+    summary: Upgrade the project (insiders)
+    preconditions:
+      - sh: python{{exeExt}} --version
+        msg: "Looks like Python isn't installed. Python is required to build the documentation: https://www.python.org/downloads/"
+    cmds:
+      - python -m pip install -r requirements.insiders.txt --upgrade --user
+
+  build:
+    summary: Builds the documentation
+    preconditions:
+      - sh: mkdocs --version
+        msg: "Looks like mkdocs isn't installed. Run `wails3 task setup` or `task setup` in the documentation directory to install it."
+    cmds:
+      - mkdocs build
+
+  serve:
+    summary: Builds the documentation and serves it locally
+    preconditions:
+      - sh: mkdocs --version
+        msg: "Looks like mkdocs isn't installed. Run `wails3 task setup` or `task setup` in the documentation directory to install it."
+    cmds:
+      - mkdocs serve
+
+  serve:insiders:
+    summary: Builds the documentation and serves it locally
+    preconditions:
+      - sh: mkdocs --version
+        msg: "Looks like mkdocs isn't installed. Run `wails3 task setup` or `task setup` in the documentation directory to install it."
+    cmds:
+      - mkdocs serve --config-file mkdocs.insiders.yml
+
+  update:api:
+    summary: Updates the API documentation
+    dir: generate
+    cmds:
+      - go run .

mkdocs-website/docs/CNAME

@@ -0,0 +1 @@
+v3alpha.wails.io

mkdocs-website/docs/en/API/application.md

@@ -0,0 +1,359 @@
+# Application
+
+The application API assists in creating an application using the Wails
+framework.
+
+### New
+
+API: `New(appOptions Options) *App`
+
+`New(appOptions Options)` creates a new application using the given application
+options . It applies default values for unspecified options, merges them with
+the provided ones, initializes and returns an instance of the application.
+
+In case of an error during initialization, the application is stopped with the
+error message provided.
+
+It should be noted that if a global application instance already exists, that
+instance will be returned instead of creating a new one.
+
+```go title="main.go" hl_lines="6-9"
+package main
+
+import "github.com/wailsapp/wails/v3/pkg/application"
+
+func main() {
+    app := application.New(application.Options{
+        Name:        "WebviewWindow Demo",
+		// Other options
+    })
+
+	// Rest of application
+}
+```
+
+### Get
+
+`Get()` returns the global application instance. It's useful when you need to
+access the application from different parts of your code.
+
+```go
+    // Get the application instance
+    app := application.Get()
+```
+
+### Capabilities
+
+API: `Capabilities() capabilities.Capabilities`
+
+`Capabilities()` retrieves a map of capabilities that the application currently
+has. Capabilities can be about different features the operating system provides,
+like webview features.
+
+```go
+    // Get the application capabilities
+    capabilities := app.Capabilities()
+	if capabilities.HasNativeDrag {
+		// Do something
+    }
+```
+
+### GetPID
+
+API: `GetPID() int`
+
+`GetPID()` returns the Process ID of the application.
+
+```go
+    pid := app.GetPID()
+```
+
+### Run
+
+API: `Run() error`
+
+`Run()` starts the execution of the application and its components.
+
+```go
+    app := application.New(application.Options{
+	    //options
+	})
+    // Run the application
+    err := application.Run()
+    if err != nil {
+        // Handle error
+    }
+```
+
+### Quit
+
+API: `Quit()`
+
+`Quit()` quits the application by destroying windows and potentially other
+components.
+
+```go
+    // Quit the application
+    app.Quit()
+```
+
+### IsDarkMode
+
+API: `IsDarkMode() bool`
+
+`IsDarkMode()` checks if the application is running in dark mode. It returns a
+boolean indicating whether dark mode is enabled.
+
+```go
+    // Check if dark mode is enabled
+    if app.IsDarkMode() {
+        // Do something
+    }
+```
+
+### Hide
+
+API: `Hide()`
+
+`Hide()` hides the application window.
+
+```go
+    // Hide the application window
+    app.Hide()
+```
+
+### Show
+
+API: `Show()`
+
+`Show()` shows the application window.
+
+```go
+    // Show the application window
+    app.Show()
+```
+
+### NewWebviewWindow
+
+API: `NewWebviewWindow() *WebviewWindow`
+
+`NewWebviewWindow()` creates a new Webview window with default options, and
+returns it.
+
+```go
+    // Create a new webview window
+    window := app.NewWebviewWindow()
+```
+
+### NewWebviewWindowWithOptions
+
+API:
+`NewWebviewWindowWithOptions(windowOptions WebviewWindowOptions) *WebviewWindow`
+
+`NewWebviewWindowWithOptions()` creates a new webview window with custom
+options. The newly created window is added to a map of windows managed by the
+application.
+
+```go
+    // Create a new webview window with custom options
+    window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
+		Name: "Main",
+        Title: "My Window",
+        Width: 800,
+        Height: 600,
+    })
+```
+
+### OnWindowCreation
+
+API: `OnWindowCreation(callback func(window *WebviewWindow))`
+
+`OnWindowCreation()` registers a callback function to be called when a window is
+created.
+
+```go
+    // Register a callback to be called when a window is created
+    app.OnWindowCreation(func(window *WebviewWindow) {
+        // Do something
+    })
+```
+
+### GetWindowByName
+
+API: `GetWindowByName(name string) *WebviewWindow`
+
+`GetWindowByName()` fetches and returns a window with a specific name.
+
+```go
+    // Get a window by name
+    window := app.GetWindowByName("Main")
+```
+
+### CurrentWindow
+
+API: `CurrentWindow() *WebviewWindow`
+
+`CurrentWindow()` fetches and returns a pointer to the currently active window
+in the application. If there is no window, it returns nil.
+
+```go
+    // Get the current window
+    window := app.CurrentWindow()
+```
+
+### RegisterContextMenu
+
+API: `RegisterContextMenu(name string, menu *Menu)`
+
+`RegisterContextMenu()` registers a context menu with a given name. This menu
+can be used later in the application.
+
+```go
+
+    // Create a new menu
+    ctxmenu := app.NewMenu()
+
+    // Register the menu as a context menu
+    app.RegisterContextMenu("MyContextMenu", ctxmenu)
+```
+
+### SetMenu
+
+API: `SetMenu(menu *Menu)`
+
+`SetMenu()` sets the menu for the application. On Mac, this will be the global
+menu. For Windows and Linux, this will be the default menu for any new window
+created.
+
+```go
+    // Create a new menu
+    menu := app.NewMenu()
+
+    // Set the menu for the application
+    app.SetMenu(menu)
+```
+
+### ShowAboutDialog
+
+API: `ShowAboutDialog()`
+
+`ShowAboutDialog()` shows an "About" dialog box. It can show the application's
+name, description and icon.
+
+```go
+    // Show the about dialog
+    app.ShowAboutDialog()
+```
+
+### Info
+
+API: `InfoDialog()`
+
+`InfoDialog()` creates and returns a new instance of `MessageDialog` with an
+`InfoDialogType`. This dialog is typically used to display informational
+messages to the user.
+
+### Question
+
+API: `QuestionDialog()`
+
+`QuestionDialog()` creates and returns a new instance of `MessageDialog` with a
+`QuestionDialogType`. This dialog is often used to ask a question to the user
+and expect a response.
+
+### Warning
+
+API: `WarningDialog()`
+
+`WarningDialog()` creates and returns a new instance of `MessageDialog` with a
+`WarningDialogType`. As the name suggests, this dialog is primarily used to
+display warning messages to the user.
+
+### Error
+
+API: `ErrorDialog()`
+
+`ErrorDialog()` creates and returns a new instance of `MessageDialog` with an
+`ErrorDialogType`. This dialog is designed to be used when you need to display
+an error message to the user.
+
+### OpenFile
+
+API: `OpenFileDialog()`
+
+`OpenFileDialog()` creates and returns a new `OpenFileDialogStruct`. This dialog
+prompts the user to select one or more files from their file system.
+
+### SaveFile
+
+API: `SaveFileDialog()`
+
+`SaveFileDialog()` creates and returns a new `SaveFileDialogStruct`. This dialog
+prompts the user to choose a location on their file system where a file should
+be saved.
+
+### OpenDirectory
+
+API: `OpenDirectoryDialog()`
+
+`OpenDirectoryDialog()` creates and returns a new instance of `MessageDialog`
+with an `OpenDirectoryDialogType`. This dialog enables the user to choose a
+directory from their file system.
+
+### On
+
+API:
+`On(eventType events.ApplicationEventType, callback func(event *Event)) func()`
+
+`On()` registers an event listener for specific application events. The callback
+function provided will be triggered when the corresponding event occurs. The
+function returns a function that can be called to remove the listener.
+
+### RegisterHook
+
+API:
+`RegisterHook(eventType events.ApplicationEventType, callback func(event *Event)) func()`
+
+`RegisterHook()` registers a callback to be run as a hook during specific
+events. These hooks are run before listeners attached with `On()`. The function
+returns a function that can be called to remove the hook.
+
+### GetPrimaryScreen
+
+API: `GetPrimaryScreen() (*Screen, error)`
+
+`GetPrimaryScreen()` returns the primary screen of the system.
+
+### GetScreens
+
+API: `GetScreens() ([]*Screen, error)`
+
+`GetScreens()` returns information about all screens attached to the system.
+
+This is a brief summary of the exported methods in the provided `App` struct. Do
+note that for more detailed functionality or considerations, refer to the actual
+Go code or further internal documentation.
+
+## Options
+
+```go title="application_options.go"
+--8<--
+../v3/pkg/application/options_application.go
+--8<--
+```
+
+### Windows Options
+
+```go title="application_options_windows.go"
+--8<--
+../v3/pkg/application/options_application_win.go
+--8<--
+```
+
+### Mac Options
+
+```go title="options_application_mac.go"
+--8<--
+../v3/pkg/application/options_application_mac.go
+--8<--
+```

mkdocs-website/docs/en/API/mainthread.md

@@ -0,0 +1,50 @@
+# Main Thread Functions
+
+These methods are utility functions to run code on the main thread. This is
+required when you want to run custom code on the UI thread.
+
+### InvokeSync
+
+API: `InvokeSync(fn func())`
+
+This function runs the passed function (`fn`) synchronously. It uses a WaitGroup
+(`wg`) to ensure that the main thread waits for the `fn` function to finish
+before it continues. If a panic occurs inside `fn`, it will be passed to the
+handler function `PanicHandler`, defined in the application options.
+
+### InvokeSyncWithResult
+
+API: `InvokeSyncWithResult[T any](fn func() T) (res T)`
+
+This function works similarly to `InvokeSync(fn func())`, however, it yields a
+result. Use this for calling any function with a single return.
+
+### InvokeSyncWithError
+
+API: `InvokeSyncWithError(fn func() error) (err error)`
+
+This function runs `fn` synchronously and returns any error that `fn` produces.
+Note that this function will recover from a panic if one occurs during `fn`'s
+execution.
+
+### InvokeSyncWithResultAndError
+
+API:
+`InvokeSyncWithResultAndError[T any](fn func() (T, error)) (res T, err error)`
+
+This function runs `fn` synchronously and returns both a result of type `T` and
+an error.
+
+### InvokeAsync
+
+API: `InvokeAsync(fn func())`
+
+This function runs `fn` asynchronously. It runs the given function on the main
+thread. If a panic occurs inside `fn`, it will be passed to the handler function
+`PanicHandler`, defined in the application options.
+
+---
+
+_Note_: These functions will block execution until `fn` has finished. It's
+critical to ensure that `fn` doesn't block. If you need to run a function that
+blocks, use `InvokeAsync` instead.

mkdocs-website/docs/en/API/menu.md

@@ -0,0 +1,69 @@
+# Menu
+
+Menus can be created and added to the application. They can be used to create
+context menus, system tray menus and application menus.
+
+To create a new menu, call:
+
+```go
+    // Create a new menu
+    menu := app.NewMenu()
+```
+
+The following operations are then available on the `Menu` type:
+
+### Add
+
+API: `Add(label string) *MenuItem`
+
+This method takes a `label` of type `string` as an input and adds a new
+`MenuItem` with the given label to the menu. It returns the `MenuItem` added.
+
+### AddSeparator
+
+API: `AddSeparator()`
+
+This method adds a new separator `MenuItem` to the menu.
+
+### AddCheckbox
+
+API: `AddCheckbox(label string, enabled bool) *MenuItem`
+
+This method takes a `label` of type `string` and `enabled` of type `bool` as
+inputs and adds a new checkbox `MenuItem` with the given label and enabled state
+to the menu. It returns the `MenuItem` added.
+
+### AddRadio
+
+API: `AddRadio(label string, enabled bool) *MenuItem`
+
+This method takes a `label` of type `string` and `enabled` of type `bool` as
+inputs and adds a new radio `MenuItem` with the given label and enabled state to
+the menu. It returns the `MenuItem` added.
+
+### Update
+
+API: `Update()`
+
+This method processes any radio groups and updates the menu if a menu
+implementation is not initialized.
+
+### AddSubmenu
+
+API: `AddSubmenu(s string) *Menu`
+
+This method takes a `s` of type `string` as input and adds a new submenu
+`MenuItem` with the given label to the menu. It returns the submenu added.
+
+### AddRole
+
+API: `AddRole(role Role) *Menu`
+
+This method takes `role` of type `Role` as input, adds it to the menu if it is
+not `nil` and returns the `Menu`.
+
+### SetLabel
+
+API: `SetLabel(label string)`
+
+This method sets the `label` of the `Menu`.

mkdocs-website/docs/en/API/systray.md

@@ -0,0 +1,112 @@
+# System Tray
+
+The system tray houses notification area on a desktop environment, which can
+contain both icons of currently-running applications and specific system
+notifications.
+
+You create a system tray by calling `app.NewSystemTray()`:
+
+```go
+    // Create a new system tray
+tray := app.NewSystemTray()
+```
+
+The following methods are available on the `SystemTray` type:
+
+### SetLabel
+
+API: `SetLabel(label string)`
+
+The `SetLabel` method sets the tray's label.
+
+### Label
+
+API: `Label() string`
+
+The `Label` method retrieves the tray's label.
+
+### PositionWindow
+
+API: `PositionWindow(*WebviewWindow, offset int) error`
+
+The `PositionWindow` method calls both `AttachWindow` and `WindowOffset`
+methods.
+
+### SetIcon
+
+API: `SetIcon(icon []byte) *SystemTray`
+
+The `SetIcon` method sets the system tray's icon.
+
+### SetDarkModeIcon
+
+API: `SetDarkModeIcon(icon []byte) *SystemTray`
+
+The `SetDarkModeIcon` method sets the system tray's icon when in dark mode.
+
+### SetMenu
+
+API: `SetMenu(menu *Menu) *SystemTray`
+
+The `SetMenu` method sets the system tray's menu.
+
+### Destroy
+
+API: `Destroy()`
+
+The `Destroy` method destroys the system tray instance.
+
+### OnClick
+
+API: `OnClick(handler func()) *SystemTray`
+
+The `OnClick` method sets the function to execute when the tray icon is clicked.
+
+### OnRightClick
+
+API: `OnRightClick(handler func()) *SystemTray`
+
+The `OnRightClick` method sets the function to execute when right-clicking the
+tray icon.
+
+### OnDoubleClick
+
+API: `OnDoubleClick(handler func()) *SystemTray`
+
+The `OnDoubleClick` method sets the function to execute when double-clicking the
+tray icon.
+
+### OnRightDoubleClick
+
+API: `OnRightDoubleClick(handler func()) *SystemTray`
+
+The `OnRightDoubleClick` method sets the function to execute when right
+double-clicking the tray icon.
+
+### AttachWindow
+
+API: `AttachWindow(window *WebviewWindow) *SystemTray`
+
+The `AttachWindow` method attaches a window to the system tray. The window will
+be shown when the system tray icon is clicked.
+
+### WindowOffset
+
+API: `WindowOffset(offset int) *SystemTray`
+
+The `WindowOffset` method sets the gap in pixels between the system tray and the
+window.
+
+### WindowDebounce
+
+API: `WindowDebounce(debounce time.Duration) *SystemTray`
+
+The `WindowDebounce` method sets a debounce time. In the context of Windows,
+this is used to specify how long to wait before responding to a mouse up event
+on the notification icon.
+
+### OpenMenu
+
+API: `OpenMenu()`
+
+The `OpenMenu` method opens the menu associated with the system tray.

mkdocs-website/docs/en/API/window.md

@@ -0,0 +1,114 @@
+# Window
+
+To create a window, use
+[Application.NewWebviewWindow](application.md#newwebviewwindow) or
+[Application.NewWebviewWindowWithOptions](application.md#newwebviewwindowwithoptions).
+The former creates a window with default options, while the latter allows you to
+specify custom options.
+
+These methods are callable on the returned WebviewWindow object:
+
+### SetTitle
+
+API: `SetTitle(title string) *WebviewWindow`
+
+This method updates the window title to the provided string. It returns the
+WebviewWindow object, allowing for method chaining.
+
+### Name
+
+API: `Name() string`
+
+This function returns the name of the WebviewWindow.
+
+### SetSize
+
+API: `SetSize(width, height int) *WebviewWindow`
+
+This method sets the size of the WebviewWindow to the provided width and height
+parameters. If the dimensions provided exceed the constraints, they are adjusted
+appropriately.
+
+### SetAlwaysOnTop
+
+API: `SetAlwaysOnTop(b bool) *WebviewWindow`
+
+This function sets the window to stay on top based on the boolean flag provided.
+
+### Show
+
+API: `Show() *WebviewWindow`
+
+`Show` method is used to make the window visible. If the window is not running,
+it first invokes the `run` method to start the window and then makes it visible.
+
+### Hide
+
+API: `Hide() *WebviewWindow`
+
+`Hide` method is used to hide the window. It sets the hidden status of the
+window to true and emits the window hide event.
+
+### SetURL
+
+API: `SetURL(s string) *WebviewWindow`
+
+`SetURL` method is used to set the URL of the window to the given URL string.
+
+### SetZoom
+
+API: `SetZoom(magnification float64) *WebviewWindow`
+
+`SetZoom` method sets the zoom level of the window content to the provided
+magnification level.
+
+### GetZoom
+
+API: `GetZoom() float64`
+
+`GetZoom` function returns the current zoom level of the window content.
+
+### GetScreen
+
+API: `GetScreen() (*Screen, error)`
+
+`GetScreen` method returns the screen on which the window is displayed.
+
+#### SetFrameless
+
+API: `SetFrameless(frameless bool) *WebviewWindow`
+
+This function is used to remove the window frame and title bar. It toggles the
+framelessness of the window according to the boolean value provided (true for
+frameless, false for framed).
+
+#### RegisterContextMenu
+
+API: `RegisterContextMenu(name string, menu *Menu)`
+
+This function is used to register a context menu and assigns it the given name.
+
+#### NativeWindowHandle
+
+API: `NativeWindowHandle() (uintptr, error)`
+
+This function is used to fetch the platform native window handle for the window.
+
+#### Focus
+
+API: `Focus()`
+
+This function is used to focus the window.
+
+#### SetEnabled
+
+API: `SetEnabled(enabled bool)`
+
+This function is used to enable/disable the window based on the provided boolean
+value.
+
+#### SetAbsolutePosition
+
+API: `SetAbsolutePosition(x int, y int)`
+
+This function sets the absolute position of the window in the screen.

mkdocs-website/docs/en/changelog.md

@@ -0,0 +1,46 @@
+# Changelog
+
+<!--
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+- `Added` for new features.
+- `Changed` for changes in existing functionality.
+- `Deprecated` for soon-to-be removed features.
+- `Removed` for now removed features.
+- `Fixed` for any bug fixes.
+- `Security` in case of vulnerabilities.
+
+-->
+
+## [Unreleased]
+
+### Added
+
+- [darwin] add Event ApplicationShouldHandleReopen to be able to handle dock icon
+  click by @5aaee9 in [#2991](https://github.com/wailsapp/wails/pull/2991)
+- [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])
+
+### Fixed
+
+- Fixed Doctor apt package verify by [Atterpac](https://github.com/Atterpac) in
+  [#2972](https://github.com/wailsapp/wails/pull/2972).
+- Fixed application frozen when quit (Darwin) by @5aaee9 in
+  [#2982](https://github.com/wailsapp/wails/pull/2982)
+- Fixed background colours of examples on Windows by
+  [mmgvh](https://github.com/mmghv) in
+  [#2750](https://github.com/wailsapp/wails/pull/2750).
+- Fixed default context menus by [mmgvh](https://github.com/mmghv) in
+  [#2753](https://github.com/wailsapp/wails/pull/2753).
+
+### Changed
+
+### Removed
+
+### Deprecated
+
+### Security

mkdocs-website/docs/en/development/changes.md

@@ -0,0 +1,455 @@
+# Changes for v3
+
+!!! note 
+    This is currently an unsorted brain dump of changes. It will be
+organised into a more readable format soon.
+
+## Options
+
+The application options have been revised since v2.
+
+## Events
+
+In v3, there are 3 types of events:
+
+- Application Events
+- Window Events
+- Custom Events
+
+### Application Events
+
+Application events are events that are emitted by the application. These events
+include native events such as `ApplicationDidFinishLaunching` on macOS.
+
+### Window Events
+
+Window events are events that are emitted by a window. These events include
+native events such as `WindowDidBecomeMain` on macOS. Common events are also
+defined, so they work cross-platform, e.g. `WindowClosing`.
+
+### Custom Events
+
+Events that the user defines are called `WailsEvents`. This is to differentiate
+them from the `Event` object that is used to communicate with the browser.
+WailsEvents are now objects that encapsulate all the details of an event. This
+includes the event name, the data, and the source of the event.
+
+The data associated with a WailsEvent is now a single value. If multiple values
+are required, then a struct can be used.
+
+### Event callbacks and `Emit` function signature
+
+The signatures events callbacks (as used by `On`, `Once` & `OnMultiple`) have
+changed. In v2, the callback function received optional data. In v3, the
+callback function receives a `WailsEvent` object that contains all data related
+to the event.
+
+Similarly, the `Emit` function has changed. Instead of taking a name and
+optional data, it now takes a single `WailsEvent` object that it will emit.
+
+### `Off` and `OffAll`
+
+In v2, `Off` and `OffAll` calls would remove events in both JS and Go. Due to
+the multi-window nature of v3, this has been changed so that these methods only
+apply to the context they are called in. For example, if you call `Off` in a
+window, it will only remove events for that window. If you use `Off` in Go, it
+will only remove events for Go.
+
+### Hooks
+
+Event Hooks are a new feature in v3. They allow you to hook into the event
+system and perform actions when certain events are emitted. For example, you can
+hook into the `WindowClosing` event and perform some cleanup before the window
+closes. Hooks can be registered at the application level or at the window level
+using `RegisterHook`. Application level are for application events. Window level
+hooks will only be called for the window they are registered with.
+
+### Logging
+
+Logging in v2 was confusing as both application logs and system (internal) logs
+were using the same logger. We have simplified this as follows:
+
+- Internal logs are now handled using the standard Go `slog` logger. This is
+  configured using the `logger` option in the application options. By default,
+  this uses the [tint](https://github.com/lmittmann/tint) logger.
+- Application logs can now be achieved through the new `log` plugin which
+  utilises `slog` under the hood. This plugin provides a simple API for logging
+  to the console. It is available in both Go and JS.
+
+### Developer notes
+
+When emitting an event in Go, it will dispatch the event to local Go listeners
+and also each window in the application. When emitting an event in JS, it now
+sends the event to the application. This will be processed as if it was emitted
+in Go, however the sender ID will be that of the window.
+
+## Window
+
+The Window API has largely remained the same, however the methods are now on an
+instance of a window rather than the runtime. Some notable differences are:
+
+- Windows now have a Name that identifies them. This is used to identify the
+  window when emitting events.
+- Windows have even more methods on the that were previously unavailable, such
+  as `AbsolutePosition` and `ToggleDevTools`.
+- Windows can now accept files via native drag and drop. See the Drag and Drop
+  section for more details.
+
+## ClipBoard
+
+The clipboard API has been simplified. There is now a single `Clipboard` object
+that can be used to read and write to the clipboard. The `Clipboard` object is
+available in both Go and JS. `SetText()` to set the text and `Text()` to get the
+text.
+
+## Bindings
+
+Bindings work in a similar way to v2, by providing a means to bind struct
+methods to the frontend. These can be called in the frontend using the binding
+wrappers generated by the `wails3 generate bindings` command:
+
+```javascript
+// @ts-check
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+import { main } from "./models";
+
+window.go = window.go || {};
+window.go.main = {
+  GreetService: {
+    /**
+     * GreetService.Greet
+     * Greet greets a person
+     * @param name {string}
+     * @returns {Promise<string>}
+     **/
+    Greet: function (name) {
+      wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
+    },
+
+    /**
+     * GreetService.GreetPerson
+     * GreetPerson greets a person
+     * @param person {main.Person}
+     * @returns {Promise<string>}
+     **/
+    GreetPerson: function (person) {
+      wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
+    },
+  },
+};
+```
+
+Bound methods are obfuscated by default, and are identified using uint32 IDs,
+calculated using the
+[FNV hashing algorithm](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function).
+This is to prevent the method name from being exposed in production builds. In
+debug mode, the method IDs are logged along with the calculated ID of the method
+to aid in debugging. If you wish to add an extra layer of obfuscation, you can
+use the `BindAliases` option. This allows you to specify a map of alias IDs to
+method IDs. When the frontend calls a method using an ID, the method ID will be
+looked up in the alias map first for a match. If it does not find it, it assumes
+it's a standard method ID and tries to find the method in the usual way.
+
+Example:
+
+```go
+	app := application.New(application.Options{
+		Bind: []any{
+			&GreetService{},
+		},
+		BindAliases: map[uint32]uint32{
+			1: 1411160069,
+			2: 4021313248,
+		},
+		Assets: application.AssetOptions{
+			FS: assets,
+		},
+		Mac: application.MacOptions{
+			ApplicationShouldTerminateAfterLastWindowClosed: true,
+		},
+	})
+```
+
+We can now call using this alias in the frontend: `wails.Call(1, "world!")`.
+
+### Insecure calls
+
+If you don't mind your calls being available in plain text in your binary and
+have no intention of using [garble](https://github.com/burrowers/garble), then
+you can use the insecure `wails.CallByName()` method. This method takes the
+fully qualified name of the method to call and the arguments to pass to it.
+Example:
+
+    ```go
+    wails.CallByName("main.GreetService.Greet", "world!")
+    ```
+
+!!! danger
+
+    This is only provided as a convenience method for development. It is not recommended to use this in production.
+
+## Dialogs
+
+Dialogs are now available in JavaScript!
+
+### Windows
+
+Dialog buttons in Windows are not configurable and are constant depending on the
+type of dialog. To trigger a callback when a button is pressed, create a button
+with the same name as the button you wish to have the callback attached to.
+Example: Create a button with the label `Ok` and use `OnClick()` to set the
+callback method:
+
+```go
+        dialog := app.QuestionDialog().
+			SetTitle("Update").
+			SetMessage("The cancel button is selected when pressing escape")
+		ok := dialog.AddButton("Ok")
+		ok.OnClick(func() {
+			// Do something
+		})
+		no := dialog.AddButton("Cancel")
+		dialog.SetDefaultButton(ok)
+		dialog.SetCancelButton(no)
+		dialog.Show()
+```
+
+## Drag and Drop
+
+Native drag and drop can be enabled per-window. Simply set the
+`EnableDragAndDrop` window config option to `true` and the window will allow
+files to be dragged onto it. When this happens, the `events.FilesDropped` event
+will be emitted. The filenames can then be retrieved from the
+`WindowEvent.Context()` using the `DroppedFiles()` method. This returns a slice
+of strings containing the filenames.
+
+## Context Menus
+
+Context menus are contextual menus that are shown when the user right-clicks on
+an element. Creating a context menu is the same as creating a standard menu , by
+using `app.NewMenu()`. To make the context menu available to a window, call
+`window.RegisterContextMenu(name, menu)`. The name will be the id of the context
+menu and used by the frontend.
+
+To indicate that an element has a context menu, add the `data-contextmenu`
+attribute to the element. The value of this attribute should be the name of a
+context menu previously registered with the window.
+
+It is possible to register a context menu at the application level, making it
+available to all windows. This can be done using
+`app.RegisterContextMenu(name, menu)`. If a context menu cannot be found at the
+window level, the application context menus will be checked. A demo of this can
+be found in `v3/examples/contextmenus`.
+
+## Wails Markup Language (WML)
+
+The Wails Markup Language is a simple markup language that allows you to add
+functionality to standard HTML elements without the use of Javascript.
+
+The following tags are currently supported:
+
+### `data-wml-event`
+
+This specifies that a Wails event will be emitted when the element is clicked.
+The value of the attribute should be the name of the event to emit.
+
+Example:
+
+```html
+<button data-wml-event="myevent">Click Me</button>
+```
+
+Sometimes you need the user to confirm an action. This can be done by adding the
+`data-wml-confirm` attribute to the element. The value of this attribute will be
+the message to display to the user.
+
+Example:
+
+```html
+<button data-wml-event="delete-all-items" data-wml-confirm="Are you sure?">
+  Delete All Items
+</button>
+```
+
+### `data-wml-window`
+
+Any `wails.window` method can be called by adding the `data-wml-window`
+attribute to an element. The value of the attribute should be the name of the
+method to call. The method name should be in the same case as the method.
+
+```html
+<button data-wml-window="Close">Close Window</button>
+```
+
+### `data-wml-trigger`
+
+This attribute specifies which javascript event should trigger the action. The
+default is `click`.
+
+```html
+<button data-wml-event="hover-box" data-wml-trigger="mouseover">
+  Hover over me!
+</button>
+```
+
+## Systray
+
+Wails 3 comes with a built-in systray. This is a fully featured systray that has
+been designed to be as simple as possible to use. It is possible to set the
+icon, tooltip and menu of the systray. It is possible to also "attach" a window
+to the systray. Doing this will provide the following functionality:
+
+- Clicking the systray icon with toggle the window visibility
+- Right-clicking the systray will open the menu, if there is one
+
+On macOS, if there is no attached window, the systray will use the default
+method of displaying the menu (any button). If there is an attached window but
+no menu, the systray will toggle the window regardless of the button pressed.
+
+## Plugins
+
+Plugins are a way to extend the functionality of your Wails application.
+
+### Creating a plugin
+
+Plugins are standard Go structure that adhere to the following interface:
+
+```go
+type Plugin interface {
+    Name() string
+    Init(*application.App) error
+    Shutdown()
+    CallableByJS() []string
+    InjectJS() string
+}
+```
+
+The `Name()` method returns the name of the plugin. This is used for logging
+purposes.
+
+The `Init(*application.App) error` method is called when the plugin is loaded.
+The `*application.App` parameter is the application that the plugin is being
+loaded into. Any errors will prevent the application from starting.
+
+The `Shutdown()` method is called when the application is shutting down.
+
+The `CallableByJS()` method returns a list of exported functions that can be
+called from the frontend. These method names must exactly match the names of the
+methods exported by the plugin.
+
+The `InjectJS()` method returns JavaScript that should be injected into all
+windows as they are created. This is useful for adding custom JavaScript
+functions that complement the plugin.
+
+### Tips
+
+#### Enums
+
+In Go, enums are often defined as a type and a set of constants. For example:
+
+```go
+type MyEnum int
+
+const (
+    MyEnumOne MyEnum = iota
+    MyEnumTwo
+    MyEnumThree
+)
+```
+
+Due to incompatibility between Go and JavaScript, custom types cannot be used in
+this way. The best strategy is to use a type alias for float64:
+
+```go
+type MyEnum = float64
+
+const (
+    MyEnumOne MyEnum = iota
+    MyEnumTwo
+    MyEnumThree
+)
+```
+
+In Javascript, you can then use the following:
+
+```js
+const MyEnum = {
+  MyEnumOne: 0,
+  MyEnumTwo: 1,
+  MyEnumThree: 2,
+};
+```
+
+- Why use `float64`? Can't we use `int`?
+  - Because JavaScript doesn't have a concept of `int`. Everything is a
+    `number`, which translates to `float64` in Go. There are also restrictions
+    on casting types in Go's reflection package, which means using `int` doesn't
+    work.
+
+### BackgroundColour
+
+In v2, this was a pointer to an `RGBA` struct. In v3, this is an `RGBA` struct
+value.
+
+### WindowIsTranslucent
+
+This flag has been removed. Now there is a `BackgroundType` flag that can be
+used to set the type of background the window should have. This flag can be set
+to any of the following values:
+
+- `BackgroundTypeSolid` - The window will have a solid background
+- `BackgroundTypeTransparent` - The window will have a transparent background
+- `BackgroundTypeTranslucent` - The window will have a translucent background
+
+On Windows, if the `BackgroundType` is set to `BackgroundTypeTranslucent`, the
+type of translucency can be set using the `BackdropType` flag in the
+`WindowsWindow` options. This can be set to any of the following values:
+
+- `Auto` - The window will use an effect determined by the system
+- `None` - The window will have no background
+- `Mica` - The window will use the Mica effect
+- `Acrylic` - The window will use the acrylic effect
+- `Tabbed` - The window will use the tabbed effect
+
+## Windows Application Options
+
+### WndProcInterceptor
+
+If this is set, the WndProc will be intercepted and the function will be called.
+This allows you to handle Windows messages directly. The function should have
+the following signature:
+
+```go
+func(hwnd uintptr, msg uint32, wParam, lParam uintptr) (returnValue uintptr, shouldReturn)
+```
+
+The `shouldReturn` value should be set to `true` if the returnValue should be
+returned by the main wndProc method. If it is set to `false`, the return value
+will be ignored and the message will continue to be processed by the main
+wndProc method.
+
+## Hide Window on Close + OnBeforeClose
+
+In v2, there was the `HideWindowOnClose` flag to hide the window when it closed.
+There was a logical overlap between this flag and the `OnBeforeClose` callback.
+In v3, the `HideWindowOnClose` flag has been removed and the `OnBeforeClose`
+callback has been renamed to `ShouldClose`. The `ShouldClose` callback is called
+when the user attempts to close a window. If the callback returns `true`, the
+window will close. If it returns `false`, the window will not close. This can be
+used to hide the window instead of closing it.
+
+## Window Drag
+
+In v2, the `--wails-drag` attribute was used to indicate that an element could
+be used to drag the window. In v3, this has been replaced with
+`--webkit-app-region` to be more in line with the way other frameworks handle
+this. The `--webkit-app-region` attribute can be set to any of the following
+values:
+
+- `drag` - The element can be used to drag the window
+- `no-drag` - The element cannot be used to drag the window
+
+We would have ideally liked to use `app-region`, however this is not supported
+by the `getComputedStyle` call on webkit on macOS.

mkdocs-website/docs/en/development/introduction.md

@@ -0,0 +1,217 @@
+# Introduction
+
+!!! note 
+    This guide is a work in progress.
+
+Thanks for wanting to help out with development of Wails! This guide will help
+you get started.
+
+## Getting Started
+
+- Git clone this repository. Checkout the `v3-alpha` branch.
+- Install the CLI: `cd v3/cmd/wails3 && go install`
+
+- Optional: If you are wanting to use the build system to build frontend code,
+  you will need to install [npm](https://nodejs.org/en/download).
+
+## Building
+
+For simple programs, you can use the standard `go build` command. It's also
+possible to use `go run`.
+
+Wails also comes with a build system that can be used to build more complex
+projects. It utilises the awesome [Task](https://taskfile.dev) build system. For
+more information, check out the task homepage or run `wails task --help`.
+
+## Project layout
+
+The project has the following structure:
+
+    ```
+    v3
+    ├── cmd/wails3                  // CLI
+    ├── examples                   // Examples of Wails apps
+    ├── internal                   // Internal packages
+    |   ├── runtime                // The Wails JS runtime
+    |   └── templates              // The supported project templates
+    ├── pkg
+    |   ├── application            // The core Wails library
+    |   └── events                 // The event definitions
+    |   └── mac                    // macOS specific code used by plugins
+    |   └── w32                    // Windows specific code
+    ├── plugins                    // Supported plugins
+    ├── tasks                      // General tasks
+    └── Taskfile.yaml              // Development tasks configuration
+    ```
+
+## Development
+
+### Alpha Todo List
+
+We are currently tracking known issues and tasks in the
+[Alpha Todo List](https://github.com/orgs/wailsapp/projects/6). If you want to
+help out, please check this list and follow the instructions in the
+[Feedback](../getting-started/feedback.md) page.
+
+### Adding window functionality
+
+The preferred way to add window functionality is to add a new function to the
+`pkg/application/webview_window.go` file. This should implement all the
+functionality required for all platforms. Any platform specific code should be
+called via a `webviewWindowImpl` interface method. This interface is implemented
+by each of the target platforms to provide the platform specific functionality.
+In some cases, this may do nothing. Once you've added the interface method,
+ensure each platform implements it. A good example of this is the `SetMinSize`
+method.
+
+- Mac: `webview_window_darwin.go`
+- Windows: `webview_window_windows.go`
+- Linux: `webview_window_linux.go`
+
+Most, if not all, of the platform specific code should be run on the main
+thread. To simplify this, there are a number of `invokeSync` methods defined in
+`application.go`.
+
+### Updating the runtime
+
+The runtime is located in `v3/internal/runtime`. When the runtime is updated,
+the following steps need to be taken:
+
+```shell
+wails3 task runtime:build
+```
+
+### Events
+
+Events are defined in `v3/pkg/events`. When adding a new event, the following
+steps need to be taken:
+
+- Add the event to the `events.txt` file
+- Run `wails3 task events:generate`
+
+There are a number of types of events: platform specific application and window
+events + common events. The common events are useful for cross-platform event
+handling, but you aren't limited to the "lowest common denominator". You can use
+the platform specific events if you need to.
+
+When adding a common event, ensure that the platform specific events are mapped.
+An example of this is in `window_webview_darwin.go`:
+
+```go
+		// Translate ShouldClose to common WindowClosing event
+		w.parent.On(events.Mac.WindowShouldClose, func(_ *WindowEventContext) {
+			w.parent.emit(events.Common.WindowClosing)
+		})
+```
+
+NOTE: We may try to automate this in the future by adding the mapping to the
+event definition.
+
+### Plugins
+
+Plugins are a way to extend the functionality of your Wails application.
+
+#### Creating a plugin
+
+Plugins are standard Go structure that adhere to the following interface:
+
+```go
+type Plugin interface {
+    Name() string
+    Init(*application.App) error
+    Shutdown()
+    CallableByJS() []string
+    InjectJS() string
+}
+```
+
+The `Name()` method returns the name of the plugin. This is used for logging
+purposes.
+
+The `Init(*application.App) error` method is called when the plugin is loaded.
+The `*application.App` parameter is the application that the plugin is being
+loaded into. Any errors will prevent the application from starting.
+
+The `Shutdown()` method is called when the application is shutting down.
+
+The `CallableByJS()` method returns a list of exported functions that can be
+called from the frontend. These method names must exactly match the names of the
+methods exported by the plugin.
+
+The `InjectJS()` method returns JavaScript that should be injected into all
+windows as they are created. This is useful for adding custom JavaScript
+functions that complement the plugin.
+
+The built-in plugins can be found in the `v3/plugins` directory. Check them out
+for inspiration.
+
+## Tasks
+
+The Wails CLI uses the [Task](https://taskfile.dev) build system. It is imported
+as a library and used to run the tasks defined in `Taskfile.yaml`. The main
+interfacing with Task happens in `v3/internal/commands/task.go`.
+
+### Upgrading Taskfile
+
+To check if there's an upgrade for Taskfile, run `wails3 task -version` and
+check against the Task website.
+
+To upgrade the version of Taskfile used, run:
+
+```shell
+wails3 task taskfile:upgrade
+```
+
+If there are incompatibilities then they should appear in the
+`v3/internal/commands/task.go` file.
+
+Usually the best way to fix incompatibilities is to clone the task repo at
+`https://github.com/go-task/task` and look at the git history to determine what
+has changed and why.
+
+To check all changes have worked correctly, re-install the CLI and check the
+version again:
+
+```shell
+wails3 task cli:install
+wails3 task -version
+```
+
+## Opening a PR
+
+Make sure that all PRs have a ticket associated with them providing context to
+the change. If there is no ticket, please create one first. Ensure that all PRs
+have updated the CHANGELOG.md file with the changes made. The CHANGELOG.md file
+is located in the `mkdocs-website/docs` directory.
+
+## Misc Tasks
+
+### Upgrading Taskfile
+
+The Wails CLI uses the [Task](https://taskfile.dev) build system. It is imported
+as a library and used to run the tasks defined in `Taskfile.yaml`. The main
+interfacing with Task happens in `v3/internal/commands/task.go`.
+
+To check if there's an upgrade for Taskfile, run `wails3 task -version` and
+check against the Task website.
+
+To upgrade the version of Taskfile used, run:
+
+```shell
+wails3 task taskfile:upgrade
+```
+
+If there are incompatibilities then they should appear in the
+`v3/internal/commands/task.go` file.
+
+Usually the best way to fix incompatibilities is to clone the task repo at
+`https://github.com/go-task/task` and look at the git history to determine what
+has changed and why.
+
+To check all changes have worked correctly, re-install the CLI and check the
+version again:
+
+```shell
+wails3 task cli:install
+wails3 task -version
+```

mkdocs-website/docs/en/development/status.md

@@ -0,0 +1,387 @@
+# Status
+
+Status of features in v3.
+
+!!! note
+
+        This list is a mixture of public and internal API support.<br/>
+        It is not complete and probably not up to date.
+
+## Known Issues
+
+- Linux is not yet up to feature parity with Windows/Mac
+
+## Application
+
+Application interface methods
+
+| Method                                                        | Windows | Linux | Mac | Notes |
+| ------------------------------------------------------------- | ------- | ----- | --- | ----- |
+| run() error                                                   | Y       | Y     | Y   |       |
+| destroy()                                                     |         | Y     | Y   |       |
+| setApplicationMenu(menu \*Menu)                               | Y       | Y     | Y   |       |
+| name() string                                                 |         | Y     | Y   |       |
+| getCurrentWindowID() uint                                     | Y       | Y     | Y   |       |
+| showAboutDialog(name string, description string, icon []byte) |         | Y     | Y   |       |
+| setIcon(icon []byte)                                          | -       | Y     | Y   |       |
+| on(id uint)                                                   |         |       | Y   |       |
+| dispatchOnMainThread(fn func())                               | Y       | Y     | Y   |       |
+| hide()                                                        | Y       | Y     | Y   |       |
+| show()                                                        | Y       | Y     | Y   |       |
+| getPrimaryScreen() (\*Screen, error)                          |         | Y     | Y   |       |
+| getScreens() ([]\*Screen, error)                              |         | Y     | Y   |       |
+
+## Webview Window
+
+Webview Window Interface Methods
+
+| Method                                             | Windows | Linux | Mac | Notes                                    |
+| -------------------------------------------------- | ------- | ----- | --- | ---------------------------------------- |
+| center()                                           | Y       | Y     | Y   |                                          |
+| close()                                            | y       | Y     | Y   |                                          |
+| destroy()                                          |         | Y     | Y   |                                          |
+| execJS(js string)                                  | y       | Y     | Y   |                                          |
+| focus()                                            | Y       | Y     |     |                                          |
+| forceReload()                                      |         | Y     | Y   |                                          |
+| fullscreen()                                       | Y       | Y     | Y   |                                          |
+| getScreen() (\*Screen, error)                      | y       | Y     | Y   |                                          |
+| getZoom() float64                                  |         | Y     | Y   |                                          |
+| height() int                                       | Y       | Y     | Y   |                                          |
+| hide()                                             | Y       | Y     | Y   |                                          |
+| isFullscreen() bool                                | Y       | Y     | Y   |                                          |
+| isMaximised() bool                                 | Y       | Y     | Y   |                                          |
+| isMinimised() bool                                 | Y       | Y     | Y   |                                          |
+| maximise()                                         | Y       | Y     | Y   |                                          |
+| minimise()                                         | Y       | Y     | Y   |                                          |
+| nativeWindowHandle() (uintptr, error)              | Y       | Y     | Y   |                                          |
+| on(eventID uint)                                   | y       |       | Y   |                                          |
+| openContextMenu(menu *Menu, data *ContextMenuData) | y       | Y     | Y   |                                          |
+| relativePosition() (int, int)                      | Y       | Y     | Y   |                                          |
+| reload()                                           | y       | Y     | Y   |                                          |
+| run()                                              | Y       | Y     | Y   |                                          |
+| setAlwaysOnTop(alwaysOnTop bool)                   | Y       | Y     | Y   |                                          |
+| setBackgroundColour(color RGBA)                    | Y       | Y     | Y   |                                          |
+| setEnabled(bool)                                   |         | Y     | Y   |                                          |
+| setFrameless(bool)                                 |         | Y     | Y   |                                          |
+| setFullscreenButtonEnabled(enabled bool)           | -       | Y     | Y   | There is no fullscreen button in Windows |
+| setHTML(html string)                               | Y       | Y     | Y   |                                          |
+| setMaxSize(width, height int)                      | Y       | Y     | Y   |                                          |
+| setMinSize(width, height int)                      | Y       | Y     | Y   |                                          |
+| setRelativePosition(x int, y int)                  | Y       | Y     | Y   |                                          |
+| setResizable(resizable bool)                       | Y       | Y     | Y   |                                          |
+| setSize(width, height int)                         | Y       | Y     | Y   |                                          |
+| setTitle(title string)                             | Y       | Y     | Y   |                                          |
+| setURL(url string)                                 | Y       | Y     | Y   |                                          |
+| setZoom(zoom float64)                              | Y       | Y     | Y   |                                          |
+| show()                                             | Y       | Y     | Y   |                                          |
+| size() (int, int)                                  | Y       | Y     | Y   |                                          |
+| toggleDevTools()                                   | Y       | Y     | Y   |                                          |
+| unfullscreen()                                     | Y       | Y     | Y   |                                          |
+| unmaximise()                                       | Y       | Y     | Y   |                                          |
+| unminimise()                                       | Y       | Y     | Y   |                                          |
+| width() int                                        | Y       | Y     | Y   |                                          |
+| zoom()                                             |         | Y     | Y   |                                          |
+| zoomIn()                                           | Y       | Y     | Y   |                                          |
+| zoomOut()                                          | Y       | Y     | Y   |                                          |
+| zoomReset()                                        | Y       | Y     | Y   |                                          |
+
+## Runtime
+
+### Application
+
+| Feature | Windows | Linux | Mac | Notes |
+| ------- | ------- | ----- | --- | ----- |
+| Quit    | Y       | Y     | Y   |       |
+| Hide    | Y       | Y     | Y   |       |
+| Show    | Y       |       | Y   |       |
+
+### Dialogs
+
+| Feature  | Windows | Linux | Mac | Notes |
+| -------- | ------- | ----- | --- | ----- |
+| Info     | Y       | Y     | Y   |       |
+| Warning  | Y       | Y     | Y   |       |
+| Error    | Y       | Y     | Y   |       |
+| Question | Y       | Y     | Y   |       |
+| OpenFile | Y       | Y     | Y   |       |
+| SaveFile | Y       | Y     | Y   |       |
+
+### Clipboard
+
+| Feature | Windows | Linux | Mac | Notes |
+|---------|---------|-------|-----|-------|
+| SetText | Y       | Y     | Y   |       |
+| Text    | Y       | Y     | Y   |       |
+
+### ContextMenu
+
+| Feature          | Windows | Linux | Mac | Notes |
+|------------------|---------|-------|-----|-------|
+| OpenContextMenu  | Y       | Y     | Y   |       |
+| On By Default    |         |       |     |       |
+| Control via HTML | Y       |       |     |       |
+
+The default context menu is enabled by default for all elements that are
+`contentEditable: true`, `<input>` or `<textarea>` tags or have the
+`--default-contextmenu: true` style set. The `--default-contextmenu: show` style
+will always show the context menu The `--default-contextmenu: hide` style will
+always hide the context menu
+
+Anything nested under a tag with `--default-contextmenu: hide` style will not
+show the context menu unless it is explicitly set with
+`--default-contextmenu: show`.
+
+### Screens
+
+| Feature    | Windows | Linux | Mac | Notes |
+| ---------- | ------- | ----- | --- | ----- |
+| GetAll     | Y       | Y     | Y   |       |
+| GetPrimary | Y       | Y     | Y   |       |
+| GetCurrent | Y       | Y     | Y   |       |
+
+### System
+
+| Feature    | Windows | Linux | Mac | Notes |
+| ---------- | ------- | ----- | --- | ----- |
+| IsDarkMode |         |       | Y   |       |
+
+### Window
+
+Y = Supported U = Untested
+
+- = Not available
+
+| Feature             | Windows | Linux | Mac | Notes                                                                                |
+| ------------------- | ------- | ----- | --- | ------------------------------------------------------------------------------------ |
+| Center              | Y       | Y     | Y   |                                                                                      |
+| Focus               | Y       | Y     |     |                                                                                      |
+| FullScreen          | Y       | Y     | Y   |                                                                                      |
+| GetZoom             | Y       | Y     | Y   | Get current view scale                                                               |
+| Height              | Y       | Y     | Y   |                                                                                      |
+| Hide                | Y       | Y     | Y   |                                                                                      |
+| Maximise            | Y       | Y     | Y   |                                                                                      |
+| Minimise            | Y       | Y     | Y   |                                                                                      |
+| RelativePosition    | Y       | Y     | Y   |                                                                                      |
+| Screen              | Y       | Y     | Y   | Get screen for window                                                                |
+| SetAlwaysOnTop      | Y       | Y     | Y   |                                                                                      |
+| SetBackgroundColour | Y       | Y     | Y   | https://github.com/MicrosoftEdge/WebView2Feedback/issues/1621#issuecomment-938234294 |
+| SetEnabled          | Y       | U     | -   | Set the window to be enabled/disabled                                                |
+| SetMaxSize          | Y       | Y     | Y   |                                                                                      |
+| SetMinSize          | Y       | Y     | Y   |                                                                                      |
+| SetRelativePosition | Y       | Y     | Y   |                                                                                      |
+| SetResizable        | Y       | Y     | Y   |                                                                                      |
+| SetSize             | Y       | Y     | Y   |                                                                                      |
+| SetTitle            | Y       | Y     | Y   |                                                                                      |
+| SetZoom             | Y       | Y     | Y   | Set view scale                                                                       |
+| Show                | Y       | Y     | Y   |                                                                                      |
+| Size                | Y       | Y     | Y   |                                                                                      |
+| UnFullscreen        | Y       | Y     | Y   |                                                                                      |
+| UnMaximise          | Y       | Y     | Y   |                                                                                      |
+| UnMinimise          | Y       | Y     | Y   |                                                                                      |
+| Width               | Y       | Y     | Y   |                                                                                      |
+| ZoomIn              | Y       | Y     | Y   | Increase view scale                                                                  |
+| ZoomOut             | Y       | Y     | Y   | Decrease view scale                                                                  |
+| ZoomReset           | Y       | Y     | Y   | Reset view scale                                                                     |
+
+### Window Options
+
+A 'Y' in the table below indicates that the option has been tested and is
+applied when the window is created. An 'X' indicates that the option is not
+supported by the platform.
+
+| Feature                         | Windows | Linux | Mac | Notes                                      |
+|---------------------------------|---------|-------|-----|--------------------------------------------|
+| AlwaysOnTop                     | Y       | Y     |     |                                            |
+| BackgroundColour                | Y       | Y     |     |                                            |
+| BackgroundType                  |         |       |     | Acrylic seems to work but the others don't |
+| CSS                             | Y       | Y     |     |                                            |
+| DevToolsEnabled                 | Y       | Y     | Y   |                                            |
+| DisableResize                   | Y       | Y     |     |                                            |
+| EnableDragAndDrop               |         | Y     |     |                                            |
+| EnableFraudulentWebsiteWarnings |         |       |     |                                            |
+| Focused                         | Y       | Y     |     |                                            |
+| Frameless                       | Y       | Y     |     |                                            |
+| FullscreenButtonEnabled         | Y       |       |     |                                            |
+| Height                          | Y       | Y     |     |                                            |
+| Hidden                          | Y       | Y     |     |                                            |
+| HTML                            | Y       | Y     |     |                                            |
+| JS                              | Y       | Y     |     |                                            |
+| Mac                             | -       | -     |     |                                            |
+| MaxHeight                       | Y       | Y     |     |                                            |
+| MaxWidth                        | Y       | Y     |     |                                            |
+| MinHeight                       | Y       | Y     |     |                                            |
+| MinWidth                        | Y       | Y     |     |                                            |
+| Name                            | Y       | Y     |     |                                            |
+| OpenInspectorOnStartup          |         |       |     |                                            |
+| StartState                      | Y       |       |     |                                            |
+| Title                           | Y       | Y     |     |                                            |
+| URL                             | Y       | Y     |     |                                            |
+| Width                           | Y       | Y     |     |                                            |
+| Windows                         | Y       | -     | -   |                                            |
+| X                               | Y       | Y     |     |                                            |
+| Y                               | Y       | Y     |     |                                            |
+| Zoom                            |         |       |     |                                            |
+| ZoomControlEnabled              |         |       |     |                                            |
+
+### Log
+
+To log or not to log? System logger vs custom logger.
+
+## Menu
+
+| Event                    | Windows | Linux | Mac | Notes |
+| ------------------------ | ------- | ----- | --- | ----- |
+| Default Application Menu | Y       | Y     | Y   |       |
+
+## Tray Menus
+
+| Feature            | Windows | Linux | Mac | Notes                                                                |
+|--------------------|---------|-------|-----|----------------------------------------------------------------------|
+| Icon               | Y       | Y     | Y   | Windows has default icons for light/dark mode & supports PNG or ICO. |
+| Label              | -       | Y     | Y   |                                                                      |
+| Label (ANSI Codes) | -       |       |     |                                                                      |
+| Menu               | Y       | Y     | Y   |                                                                      |
+
+### Methods
+
+| Method                        | Windows | Linux | Mac | Notes |
+| ----------------------------- | ------- | ----- | --- | ----- |
+| setLabel(label string)        | -       | Y     | Y   |       |
+| run()                         | Y       | Y     | Y   |       |
+| setIcon(icon []byte)          | Y       | Y     | Y   |       |
+| setMenu(menu \*Menu)          | Y       | Y     | Y   |       |
+| setIconPosition(position int) | -       | Y     | Y   |       |
+| setTemplateIcon(icon []byte)  | -       | Y     | Y   |       |
+| destroy()                     | Y       | Y     | Y   |       |
+| setDarkModeIcon(icon []byte)  | Y       | Y     | Y   | Darkmode isn't handled yet (linux)      |
+
+## Cross Platform Events
+
+Mapping native events to cross-platform events.
+
+| Event                    | Windows | Linux | Mac             | Notes |
+| ------------------------ | ------- | ----- | --------------- | ----- |
+| WindowWillClose          |         |       | WindowWillClose |       |
+| WindowDidClose           |         |       |                 |       |
+| WindowDidResize          |         |       |                 |       |
+| WindowDidHide            |         |       |                 |       |
+| ApplicationWillTerminate |         |       |                 |       |
+
+... Add more
+
+## Bindings Generation
+
+Working well.
+
+## Models Generation
+
+Working well.
+
+## Task file
+
+Contains a lot needed for development.
+
+## Theme
+
+| Mode   | Windows | Linux | Mac | Notes |
+| ------ | ------- | ----- | --- | ----- |
+| Dark   | Y       |       |     |       |
+| Light  | Y       |       |     |       |
+| System | Y       |       |     |       |
+
+## NSIS Installer
+
+TBD
+
+## Templates
+
+All templates are working.
+
+## Plugins
+
+Built-in plugin support:
+
+| Plugin          | Windows | Linux | Mac | Notes |
+| --------------- | ------- | ----- | --- | ----- |
+| Browser         | Y       |       | Y   |       |
+| KV Store        | Y       | Y     | Y   |       |
+| Log             | Y       | Y     | Y   |       |
+| Single Instance | Y       |       | Y   |       |
+| SQLite          | Y       | Y     | Y   |       |
+| Start at login  | Y       |       | Y   |       |
+| Server          |         |       |     |       |
+
+TODO:
+
+- Ensure each plugin has a JS wrapper that can be injected into the window.
+
+## Packaging
+
+|                 | Windows | Linux | Mac | Notes |
+| --------------- | ------- | ----- | --- | ----- |
+| Icon Generation | Y       |       | Y   |       |
+| Icon Embedding  | Y       |       | Y   |       |
+| Info.plist      | -       |       | Y   |       |
+| NSIS Installer  |         |       | -   |       |
+| Mac bundle      | -       |       | Y   |       |
+| Windows exe     | Y       |       | -   |       |
+
+## Frameless Windows
+
+| Feature | Windows | Linux | Mac | Notes                                          |
+| ------- | ------- | ----- | --- | ---------------------------------------------- |
+| Resize  | Y       |       | Y   |                                                |
+| Drag    | Y       | Y     | Y   | Linux - can always drag with `Meta`+left mouse |
+
+## Mac Specific
+
+- [x] Translucency
+
+### Mac Options
+
+| Feature                 | Default           | Notes                                                |
+| ----------------------- | ----------------- | ---------------------------------------------------- |
+| Backdrop                | MacBackdropNormal | Standard solid window                                |
+| DisableShadow           | false             |                                                      |
+| TitleBar                |                   | Standard window decorations by default               |
+| Appearance              | DefaultAppearance |                                                      |
+| InvisibleTitleBarHeight | 0                 | Creates an invisible title bar for frameless windows |
+| DisableShadow           | false             | Disables the window drop shadow                      |
+
+## Windows Specific
+
+- [x] Translucency
+- [x] Custom Themes
+
+### Windows Options
+
+| Feature                           | Default       | Notes                                       |
+| --------------------------------- | ------------- | ------------------------------------------- |
+| BackdropType                      | Solid         |                                             |
+| DisableIcon                       | false         |                                             |
+| Theme                             | SystemDefault |                                             |
+| CustomTheme                       | nil           |                                             |
+| DisableFramelessWindowDecorations | false         |                                             |
+| WindowMask                        | nil           | Makes the window the contents of the bitmap |
+
+## Linux Specific
+
+Implementation details for the functions utilized by the `*_linux.go` files are
+located in the following files:
+
+- linux_cgo.go: CGo implementation
+- linux_purego.go: PureGo implementation
+
+### CGO
+
+By default CGO is utilized to compile the Linux port. This prevents easy
+cross-compilation and so the PureGo implementation is also being simultaneously
+developed.
+
+### Purego
+
+The examples can be compiled using the following command:
+
+    CGO_ENABLED=0 go build -tags purego
+
+Note: things are currently not working after the refactor