[V3] Badging

docs/src/content/docs/changelog.mdx

@@ -78,9 +78,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Gin support by [Lea Anthony](https://github.com/leaanthony) in [PR](https://github.com/wailsapp/wails/pull/3537) based on the original work of [@AnalogJ](https://github.com/AnalogJ) in PR[https://github.com/wailsapp/wails/pull/3537]
 - Fix auto save and password auto save always enabled by [@oSethoum](https://github.com/osethoum) in [#4134](https://github.com/wailsapp/wails/pull/4134)
 - Add `SetMenu()` on window to allow for setting a menu on a window by [@leaanthony](https://github.com/leaanthony)
-- Add Notification support by [@popaprozac] in [#4098](https://github.com/wailsapp/wails/pull/4098)
+- Add Notification support by [@popaprozac](https://github.com/popaprozac) in [#4098](https://github.com/wailsapp/wails/pull/4098)
 -  Add File Association support for mac by [@wimaha](https://github.com/wimaha) in [#4177](https://github.com/wailsapp/wails/pull/4177)
 - Add `wails3 tool version` for semantic version bumping by [@leaanthony](https://github.com/leaanthony)
+- Add badging support for macOS and Windows by [@popaprozac](https://github.com/popaprozac) in [#](https://github.com/wailsapp/wails/pull/4234)
 ### Fixed
 
 - Fixed Windows+Linux Edit Menu issues by [@leaanthony](https://github.com/leaanthony) in [#3f78a3a](https://github.com/wailsapp/wails/commit/3f78a3a8ce7837e8b32242c8edbbed431c68c062)
@@ -153,7 +154,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Built-in service creation functions with options are now consistently called `NewWithConfig` by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
 - `Select` method on `sqlite` service is now named `Query` for consistency with Go APIs by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
 - Templates: moved runtime to "dependencies", organized package.json files by [@IanVS](https://github.com/IanVS) in [#4133](https://github.com/wailsapp/wails/pull/4133)
-- Creates and ad-hoc signs app bundles in dev to enable certain macOS APIs by [@popaprozac] in [#4171](https://github.com/wailsapp/wails/pull/4171)
+- Creates and ad-hoc signs app bundles in dev to enable certain macOS APIs by [@popaprozac](https://github.com/popaprozac) in [#4171](https://github.com/wailsapp/wails/pull/4171)
 
 ## v3.0.0-alpha.9 - 2025-01-13
 

docs/src/content/docs/learn/badges.mdx

@@ -0,0 +1,195 @@
+---
+title: Badges
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+## Introduction
+
+Wails provides a cross-platform badge service for desktop applications. This service allows you to display badges on your application tile or dock icon, which is useful for indicating unread messages, notifications, or other status information.
+
+## Basic Usage
+
+### Creating the Service
+
+First, initialize the badge service:
+
+```go
+import "github.com/wailsapp/wails/v3/pkg/application"
+import "github.com/wailsapp/wails/v3/pkg/services/badge"
+
+// Create a new badge service
+badgeService := badge.New()
+
+// Register the service with the application
+app := application.New(application.Options{
+    Services: []application.Service{
+        application.NewService(badgeService),
+    },
+})
+```
+
+### Creating the Service with Custom Options (Windows Only)
+
+On Windows, you can customize the badge appearance with various options:
+
+```go
+import "github.com/wailsapp/wails/v3/pkg/application"
+import "github.com/wailsapp/wails/v3/pkg/services/badge"
+import "image/color"
+
+// Create a badge service with custom options
+options := badge.Options{
+    TextColour:       color.RGBA{255, 255, 255, 255}, // White text
+    BackgroundColour: color.RGBA{0, 0, 255, 255},     // Green background
+    FontName:         "consolab.ttf",                 // Bold Consolas font
+    FontSize:         20,                             // Font size for single character
+    SmallFontSize:    14,                             // Font size for multiple characters
+}
+
+badgeService := badge.NewWithOptions(options)
+
+// Register the service with the application
+app := application.New(application.Options{
+    Services: []application.Service{
+        application.NewService(badgeService),
+    },
+})
+```
+
+## Badge Operations
+
+### Setting a Badge
+
+Set a badge on the application tile/dock icon:
+
+```go
+// Set a default badge
+badgeService.SetBadge("")
+
+// Set a numeric badge
+badgeService.SetBadge("3")
+
+// Set a text badge
+badgeService.SetBadge("New")
+```
+
+### Setting a Custom Badge
+
+Set a badge on the application tile/dock icon with one-off options applied:
+
+#### Go
+```go
+options := badge.Options{
+    BackgroundColour: color.RGBA{0, 255, 255, 255},
+    FontName: "arialb.ttf", // System font
+    FontSize: 16,
+    SmallFontSize: 10,
+    TextColour: color.RGBA{0, 0, 0, 255},
+}
+
+// Set a default badge
+badgeService.SetCustomBadge("", options)
+
+// Set a numeric badge
+badgeService.SetCustomBadge("3", options)
+
+// Set a text badge
+badgeService.SetCustomBadge("New", options)
+```
+
+### Removing a Badge
+
+Remove the badge from the application icon:
+
+```go
+badgeService.RemoveBadge()
+```
+
+## Platform Considerations
+
+<Tabs>
+  <TabItem label="macOS" icon="fa-brands:apple">
+
+    On macOS, badges:
+
+    - Are displayed directly on the dock icon
+    - Support text values
+    - Automatically handle dark/light mode appearance
+    - Use the standard macOS dock badge styling
+    - Automatically handle label overflow
+    - Do not support customization options (any options passed to NewWithOptions will be ignored)
+    - Will display "●" as the default badge if an empty label is provided
+
+  </TabItem>
+
+  <TabItem label="Windows" icon="fa-brands:windows">
+
+    On Windows, badges:
+
+    - Are displayed as an overlay icon in the taskbar
+    - Support text values
+    - Allow customization of colors, font, and font sizes
+    - Adapt to Windows theme settings
+    - Require the application to have a window
+    - Use smaller font size automatically for badges with multiple characters
+    - Do not handle label overflow
+    - Support the following customization options:
+      - TextColour: Text color (default: white)
+      - BackgroundColour: Badge background color (default: red)
+      - FontName: Font file name (default: "segoeuib.ttf")
+      - FontSize: Font size for single character (default: 18)
+      - SmallFontSize: Font size for multiple characters (default: 14)
+
+  </TabItem>
+
+  <TabItem label="Linux" icon="fa-brands:linux">
+
+    On Linux:
+
+    - Badge functionality is not available
+
+  </TabItem>
+</Tabs>
+
+## Best Practices
+
+1. Use badges sparingly:
+   - Too many badge updates can distract users
+   - Reserve badges for important notifications
+
+2. Keep badge text short:
+   - Numeric badges are most effective
+   - On macOS, text badges should be brief
+
+3. For Windows customization:
+   - Ensure high contrast between text and background colors
+   - Test with different text lengths as font size decreases with length
+   - Use common system fonts to ensure availability
+
+## API Reference
+
+### Service Management
+| Method                                     | Description                                           |
+|--------------------------------------------|-------------------------------------------------------|
+| `New()`                                    | Creates a new badge service with default options      |
+| `NewWithOptions(options Options)`          | Creates a new badge service with custom option (Windows only, options are ignored on macOS) |
+
+### Badge Operations
+| Method                                       | Description                                                |
+|----------------------------------------------|------------------------------------------------------------|
+| `SetBadge(label string) error`               | Sets a badge with the specified label                      |
+| `RemoveBadge() error`                        | Removes the badge from the application icon                |
+
+### Structs and Types
+
+```go
+// Options for customizing badge appearance (Windows only)
+type Options struct {
+    TextColour       color.RGBA  // Color of the badge text
+    BackgroundColour color.RGBA  // Color of the badge background
+    FontName         string      // Font file name (e.g., "segoeuib.ttf")
+    FontSize         int         // Font size for single character
+    SmallFontSize    int         // Font size for multiple characters
+}
+```

v3/examples/badge-custom/README.md

@@ -0,0 +1,128 @@
+# Welcome to Your New Wails3 Project!
+Now that you have your project set up, it's time to explore the custom badge features that Wails3 offers on **Windows**.
+
+## Exploring Custom Badge Features
+
+### Creating the Service with Custom Options (Windows Only)
+
+On Windows, you can customize the badge appearance with various options:
+
+```go
+import "github.com/wailsapp/wails/v3/pkg/application"
+import "github.com/wailsapp/wails/v3/pkg/services/badge"
+import "image/color"
+
+// Create a badge service with custom options
+options := badge.Options{
+    TextColour:       color.RGBA{255, 255, 255, 255}, // White text
+    BackgroundColour: color.RGBA{0, 0, 255, 255},     // Green background
+    FontName:         "consolab.ttf",                 // Bold Consolas font
+    FontSize:         20,                             // Font size for single character
+    SmallFontSize:    14,                             // Font size for multiple characters
+}
+
+badgeService := badge.NewWithOptions(options)
+
+// Register the service with the application
+app := application.New(application.Options{
+    Services: []application.Service{
+        application.NewService(badgeService),
+    },
+})
+```
+
+## Badge Operations
+
+### Setting a Badge
+
+Set a badge on the application tile/dock icon with the global options applied:
+
+#### Go
+```go
+// Set a default badge
+badgeService.SetBadge("")
+
+// Set a numeric badge
+badgeService.SetBadge("3")
+
+// Set a text badge
+badgeService.SetBadge("New")
+```
+
+#### JS
+```js
+import {SetBadge} from "../bindings/github.com/wailsapp/wails/v3/pkg/services/badge/service";
+
+// Set a default badge
+SetBadge("")
+
+// Set a numeric badge
+SetBadge("3")
+
+// Set a text badge
+SetBadge("New")
+```
+
+### Setting a Custom Badge
+
+Set a badge on the application tile/dock icon with one-off options applied:
+
+#### Go
+```go
+// Set a default badge
+badgeService.SetCustomBadge("")
+
+// Set a numeric badge
+badgeService.SetCustomBadge("3")
+
+// Set a text badge
+badgeService.SetCustomBadge("New")
+```
+
+#### JS
+```js
+import {SetCustomBadge} from "../bindings/github.com/wailsapp/wails/v3/pkg/services/badge/service";
+
+const options = {
+   BackgroundColour: RGBA.createFrom({
+         R: 0,
+         G: 255,
+         B: 255,
+         A: 255,
+      }),
+      FontName: "arialb.ttf", // System font
+      FontSize: 16,
+      SmallFontSize: 10,
+      TextColour: RGBA.createFrom({
+         R: 0,
+         G: 0,
+         B: 0,
+         A: 255,
+      }),
+}
+
+// Set a default badge
+SetCustomBadge("", options)
+
+// Set a numeric badge
+SetCustomBadge("3", options)
+
+// Set a text badge
+SetCustomBadge("New", options)
+```
+
+### Removing a Badge
+
+Remove the badge from the application icon:
+
+#### Go
+```go
+badgeService.RemoveBadge()
+```
+
+#### JS
+```js
+import {RemoveBadge} from "../bindings/github.com/wailsapp/wails/v3/pkg/services/badge/service";
+
+RemoveBadge()
+```

v3/examples/badge-custom/Taskfile.yml

@@ -0,0 +1,34 @@
+version: '3'
+
+includes:
+  common: ./build/Taskfile.yml
+  windows: ./build/windows/Taskfile.yml
+  darwin: ./build/darwin/Taskfile.yml
+  linux: ./build/linux/Taskfile.yml
+
+vars:
+  APP_NAME: "badge"
+  BIN_DIR: "bin"
+  VITE_PORT: '{{.WAILS_VITE_PORT | default 9245}}'
+
+tasks:
+  build:
+    summary: Builds the application
+    cmds:
+      - task: "{{OS}}:build"
+
+  package:
+    summary: Packages a production build of the application
+    cmds:
+      - task: "{{OS}}:package"
+
+  run:
+    summary: Runs the application
+    cmds:
+      - task: "{{OS}}:run"
+
+  dev:
+    summary: Runs the application in development mode
+    cmds:
+      - wails3 dev -config ./build/config.yml -port {{.VITE_PORT}}
+