Merge branch 'wailsapp:v3-alpha' into v3-alpha

docs/src/content/docs/changelog.mdx

@@ -35,8 +35,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add diagnostics section to `wails doctor` by [@leaanthony](https://github.com/leaanthony)
 - Add window to context when calling a service method by [@leaanthony](https://github.com/leaanthony)
 - Add `window-call` example to demonstrate how to know which window is calling a service by [@leaanthony](https://github.com/leaanthony)
+- New Menu guide by [@leaanthony](https://github.com/leaanthony)
 - Better panic handling by [@leaanthony](https://github.com/leaanthony)
 - New Menu guide by [@leaanthony](https://github.com/leaanthony)
+- Add doc comments for Service API by [@fbbdev](https://github.com/fbbdev) in [#4024](https://github.com/wailsapp/wails/pull/4024)
+- Add function `application.NewServiceWithOptions` to initialise services with additional configuration by [@leaanthony](https://github.com/leaanthony) in [#4024](https://github.com/wailsapp/wails/pull/4024)
 
 ### Fixed
 
@@ -46,12 +49,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix nil menu issue when calling RegisterContextMenu by [@leaanthony](https://github.com/leaanthony)
 - Fixed dependency cycles in binding generator output by [@fbbdev](https://github.com/fbbdev) in [#4001](https://github.com/wailsapp/wails/pull/4001)
 - Fixed use-before-define errors in binding generator output by [@fbbdev](https://github.com/fbbdev) in [#4001](https://github.com/wailsapp/wails/pull/4001)
+- Pass build flags to binding generator by [@fbbdev](https://github.com/fbbdev) in [#4023](https://github.com/wailsapp/wails/pull/4023)
 
 ### Changed
 
 - Removed `application.WindowIDKey` and `application.WindowNameKey` (replaced by `application.WindowKey`) by [@leaanthony](https://github.com/leaanthony)
+- ContextMenuData now returns a string instead of any by [@leaanthony](https://github.com/leaanthony)
 - In JS/TS bindings, class fields of fixed-length array types are now initialized with their expected length instead of being empty by [@fbbdev](https://github.com/fbbdev) in [#4001](https://github.com/wailsapp/wails/pull/4001)
 - ContextMenuData now returns a string instead of any by [@leaanthony](https://github.com/leaanthony)
+- `application.NewService` does not accept options as an optional parameter anymore (use `application.NewServiceWithOptions` instead) by [@leaanthony](https://github.com/leaanthony) in [#4024](https://github.com/wailsapp/wails/pull/4024)
 
 ## v3.0.0-alpha.9 - 2025-01-13
 

docs/src/content/docs/learn/services.mdx

@@ -52,6 +52,24 @@ app := application.New(application.Options{
 })
 ```
 
+This registers the `NewMyService` function as a service with the application.
+
+Services may also be registered with additional options:
+
+```go
+app := application.New(application.Options{
+    Services: []application.Service{
+        application.NewServiceWithOptions(NewMyService(), application.ServiceOptions{
+            // ...
+        })
+    }
+})
+```
+
+ServiceOptions has the following fields:
+	- Name - Specify a custom name for the Service
+    - Route - A route to bind the Service to the frontend (more on this below)
+
 ## Optional Methods
 
 Services can implement optional methods to hook into the application lifecycle.
@@ -67,8 +85,10 @@ bindings generated for a service, so they are not exposed to your frontend.
 func (s *Service) ServiceName() string
 ```
 
-This method returns the name of the service. It is used for logging purposes
-only.
+This method returns the name of the service. By default, it will the struct name of the Service but can be
+overridden with the `Name` field of the `ServiceOptions`.
+
+It is used for logging purposes only.
 
 ### ServiceStartup
 
@@ -101,7 +121,7 @@ your service to act as an HTTP handler. The route of the handler is defined in
 the service options:
 
 ```go
-application.NewService(fileserver.New(&fileserver.Config{
+application.NewServiceWithOptions(fileserver.New(&fileserver.Config{
     RootPath: rootPath,
 }), application.ServiceOptions{
     Route: "/files",
@@ -144,7 +164,7 @@ We can now use this service in our application:
 ```go
 app := application.New(application.Options{
     Services: []application.Service{
-        application.NewService(fileserver.New(&fileserver.Config{
+        application.NewServiceWithOptions(fileserver.New(&fileserver.Config{
             RootPath: rootPath,
         }), application.ServiceOptions{
             Route: "/files",

v3/examples/services/main.go

@@ -43,7 +43,7 @@ func main() {
 				AutoSave: true,
 			})),
 			application.NewService(log.New()),
-			application.NewService(fileserver.New(&fileserver.Config{
+			application.NewServiceWithOptions(fileserver.New(&fileserver.Config{
 				RootPath: rootPath,
 			}), application.ServiceOptions{
 				Route: "/files",

v3/examples/window-menu/README.md

@@ -19,6 +19,6 @@ go run .
 
 ## How it Works
 
-The example creates a window with a default menu and binds the F10 key to toggle the menu bar's visibility. The menu bar will hide when F10 is pressed and show when F10 is released.
+The example creates a window with a default menu and binds the F1 key to toggle the menu bar's visibility. The menu bar will show when F2 is pressed and hide when F3 is released.
 
-Note: The menu bar toggling functionality only works on Windows. On other platforms, the F10 key binding will have no effect.
+Note: The menu bar toggling functionality only works on Windows. On other platforms, the F1 key binding will have no effect.

v3/internal/commands/bindings.go

@@ -6,8 +6,6 @@ import (
 	"os"
 	"path/filepath"
 
-	"github.com/pterm/pterm"
-
 	"github.com/wailsapp/wails/v3/internal/flags"
 	"github.com/wailsapp/wails/v3/internal/generator"
 	"github.com/wailsapp/wails/v3/internal/generator/config"
@@ -21,8 +19,8 @@ func GenerateBindings(options *flags.GenerateBindingsOptions, patterns []string)
 		term.DisableOutput()
 		defer term.EnableOutput()
 	} else if options.Verbose {
-		pterm.EnableDebugMessages()
-		defer pterm.DisableDebugMessages()
+		term.EnableDebug()
+		defer term.DisableDebug()
 	}
 
 	term.Header("Generate Bindings")
@@ -52,20 +50,18 @@ func GenerateBindings(options *flags.GenerateBindingsOptions, patterns []string)
 	}
 
 	// Start a spinner for progress messages.
-	var spinner *pterm.SpinnerPrinter
-	if term.IsTerminal() {
-		spinner, _ = pterm.DefaultSpinner.Start("Initialising...")
-	}
+	spinner := term.StartSpinner("Initialising...")
 
 	// Initialise and run generator.
 	stats, err := generator.NewGenerator(
 		options,
 		creator,
-		config.DefaultPtermLogger(spinner),
+		spinner.Logger(),
 	).Generate(patterns...)
 
-	// Resolve spinner.
-	resultMessage := fmt.Sprintf(
+	// Stop spinner and print summary.
+	term.StopSpinner(spinner)
+	term.Infof(
 		"Processed: %s, %s, %s, %s, %s in %s.",
 		pluralise(stats.NumPackages, "Package"),
 		pluralise(stats.NumServices, "Service"),
@@ -74,14 +70,9 @@ func GenerateBindings(options *flags.GenerateBindingsOptions, patterns []string)
 		pluralise(stats.NumModels, "Model"),
 		stats.Elapsed().String(),
 	)
-	if spinner != nil {
-		spinner.Info(resultMessage)
-	} else {
-		term.Infofln(resultMessage)
-	}
 
 	// Report output directory.
-	term.Infofln("Output directory: %s", absPath)
+	term.Infof("Output directory: %s", absPath)
 
 	// Process generator error.
 	if err != nil {

v3/internal/commands/build_assets/Taskfile.tmpl.yml

@@ -22,15 +22,19 @@ tasks:
       - npm install
 
   build:frontend:
+    label: build:frontend (PRODUCTION={{ "{{.PRODUCTION}}" }})
     summary: Build the frontend project
     dir: frontend
     sources:
       - "**/*"
     generates:
-      - dist/*
+      - dist/**/*
     deps:
       - task: install:frontend:deps
       - task: generate:bindings
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
     cmds:
       - npm run {{ "{{.BUILD_COMMAND}}" }} -q
     env:
@@ -40,17 +44,21 @@ tasks:
 
 
   generate:bindings:
+    label: generate:bindings (BUILD_FLAGS={{ "{{.BUILD_FLAGS}}" }})
     summary: Generates bindings for the frontend
     deps:
       - task: go:mod:tidy
     sources:
+      - "**/*.[jt]s"
+      - exclude: frontend/**/*
+      - frontend/bindings/**/*  # Rerun when switching between dev/production mode causes changes in output
       - "**/*.go"
       - go.mod
       - go.sum
     generates:
-      - "frontend/bindings/**/*"
+      - frontend/bindings/**/*
     cmds:
-      - wails3 generate bindings -f {{ "'{{.BUILD_FLAGS}}'" }} -clean=true {{if .Typescript}} -ts{{end}}
+      - wails3 generate bindings -f {{ "'{{.BUILD_FLAGS}}'" }} -clean=true {{- if .Typescript}} -ts{{end}}
 
   generate:icons:
     summary: Generates Windows `.ico` and Mac `.icns` files from an image
@@ -75,4 +83,4 @@ tasks:
     summary: Updates the build assets
     dir: build
     cmds:
-      - wails3 update build-assets -name {{ "\"{{.APP_NAME}}\"" }} -binaryname {{ "\"{{.APP_NAME}}\"" }} -config config.yml -dir .
+      - wails3 update build-assets -name {{ "\"{{.APP_NAME}}\"" }} -binaryname {{ "\"{{.APP_NAME}}\"" }} -config config.yml -dir .

v3/internal/commands/build_assets/darwin/Taskfile.yml

@@ -9,6 +9,11 @@ tasks:
     deps:
       - task: common:go:mod:tidy
       - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          PRODUCTION:
+            ref: .PRODUCTION
       - task: common:generate:icons
     cmds:
       - go build {{.BUILD_FLAGS}} -o {{.OUTPUT}}

v3/internal/commands/build_assets/linux/Taskfile.yml

@@ -9,6 +9,11 @@ tasks:
     deps:
       - task: common:go:mod:tidy
       - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          PRODUCTION:
+            ref: .PRODUCTION
       - task: common:generate:icons
     cmds:
       - go build {{.BUILD_FLAGS}} -o {{.BIN_DIR}}/{{.APP_NAME}}
@@ -83,17 +88,17 @@ tasks:
 
   generate:deb:
     summary: Creates a deb package
-    cmds: 
+    cmds:
       - wails3 tool package -name {{.APP_NAME}} -format deb -config ./build/linux/nfpm/nfpm.yaml -out {{.ROOT_DIR}}/bin
 
   generate:rpm:
     summary: Creates a rpm package
-    cmds: 
+    cmds:
       - wails3 tool package -name {{.APP_NAME}} -format rpm -config ./build/linux/nfpm/nfpm.yaml -out {{.ROOT_DIR}}/bin
 
   generate:aur:
     summary: Creates a arch linux packager package
-    cmds: 
+    cmds:
       - wails3 tool package -name {{.APP_NAME}} -format archlinux -config ./build/linux/nfpm/nfpm.yaml -out {{.ROOT_DIR}}/bin
 
   generate:dotdesktop:

v3/internal/commands/build_assets/windows/Taskfile.yml

@@ -10,7 +10,10 @@ tasks:
       - task: common:go:mod:tidy
       - task: common:build:frontend
         vars:
-          PRODUCTION: '{{.PRODUCTION}}'
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          PRODUCTION:
+            ref: .PRODUCTION
       - task: common:generate:icons
     cmds:
       - task: generate:syso
@@ -57,4 +60,4 @@ tasks:
 
   run:
     cmds:
-      - '{{.BIN_DIR}}\\{{.APP_NAME}}.exe'
+      - '{{.BIN_DIR}}\\{{.APP_NAME}}.exe'

v3/internal/generator/errors.go

@@ -13,16 +13,16 @@ import (
 // ErrNoContextPackage indicates that
 // the canonical path for the standard context package
 // did not match any actual package.
-var ErrNoContextPackage = errors.New("standard context package not found at canonical import path ('context'): is the Wails v3 module properly installed?")
+var ErrNoContextPackage = errors.New("standard context package not found at canonical import path ('context'): is the Wails v3 module properly installed? ")
 
 // ErrNoApplicationPackage indicates that
 // the canonical path for the Wails application package
 // did not match any actual package.
-var ErrNoApplicationPackage = errors.New("Wails application package not found at canonical import path ('" + config.WailsAppPkgPath + "'): is the Wails v3 module properly installed?")
+var ErrNoApplicationPackage = errors.New("Wails application package not found at canonical import path ('" + config.WailsAppPkgPath + "'): is the Wails v3 module properly installed? ")
 
 // ErrBadApplicationPackage indicates that
 // the Wails application package has invalid content.
-var ErrBadApplicationPackage = errors.New("package " + config.WailsAppPkgPath + ": function NewService has wrong signature: is the Wails v3 module properly installed?")
+var ErrBadApplicationPackage = errors.New("package " + config.WailsAppPkgPath + ": function NewService has wrong signature: is the Wails v3 module properly installed? ")
 
 // ErrNoPackages is returned by [Generator.Generate]
 // when [LoadPackages] returns no error and no packages.
@@ -43,7 +43,7 @@ type ErrorReport struct {
 	errors   map[string]bool
 }
 
-// NewError report initialises an ErrorReport instance
+// NewErrorReport report initialises an ErrorReport instance
 // with the provided Logger implementation.
 //
 // If logger is nil, messages will be accumulated but not logged.

v3/internal/generator/testcases/complex_instantiations/bound_types.json

@@ -11,5 +11,6 @@
     ".Service10",
     ".Service11",
     ".Service12",
-    "/other.Service13"
+    ".Service13",
+    "/other.Service14"
 ]

v3/internal/generator/testcases/complex_instantiations/funcs.go

@@ -2,7 +2,7 @@ package main
 
 import "github.com/wailsapp/wails/v3/pkg/application"
 
-func ServiceInitialiser[T any]() func(*T, ...application.ServiceOptions) application.Service {
+func ServiceInitialiser[T any]() func(*T) application.Service {
 	return application.NewService[T]
 }
 

v3/internal/generator/testcases/complex_instantiations/main.go

@@ -20,6 +20,7 @@ type Service9 struct{}
 type Service10 struct{}
 type Service11 struct{}
 type Service12 struct{}
+type Service13 struct{}
 
 func main() {
 	factory := NewFactory[Service1, Service2]()
@@ -36,6 +37,7 @@ func main() {
 				ServiceInitialiser[Service6]()(&Service6{}),
 				other.CustomNewService(Service7{}),
 				other.ServiceInitialiser[Service8]()(&Service8{}),
+				application.NewServiceWithOptions(&Service13{}, application.ServiceOptions{Name: "custom name"}),
 				other.LocalService,
 			},
 			CustomNewServices[Service9, Service10]()...),

v3/internal/generator/testcases/complex_instantiations/other/funcs.go

@@ -6,7 +6,7 @@ func CustomNewService[T any](srv T) application.Service {
 	return application.NewService(&srv)
 }
 
-func ServiceInitialiser[T any]() func(*T, ...application.ServiceOptions) application.Service {
+func ServiceInitialiser[T any]() func(*T) application.Service {
 	return application.NewService[T]
 }
 

v3/internal/generator/testcases/complex_instantiations/other/local.go

@@ -2,6 +2,6 @@ package other
 
 import "github.com/wailsapp/wails/v3/pkg/application"
 
-type Service13 int
+type Service14 int
 
-var LocalService = application.NewService(new(Service13))
+var LocalService = application.NewService(new(Service14))