Merge branch 'dev'

docs/configs/settings.md

@@ -123,6 +123,58 @@ blockHighlights:
 
 Any unspecified level falls back to the built-in defaults.
 
+## Progressive Web App (PWA)
+
+A progressive web app is an app that can be installed on a device and provide user experience like a native app. Homepage comes with built-in support for PWA with some default configurations, but you can customize them.
+
+More information on PWAs can be found in [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps).
+
+## App icons
+
+You can set custom icons for installable apps. More information about how you can set them can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons).
+
+The default value is the Homepage icon in sizes 192x192 and 512x512.
+
+```yaml
+pwa:
+  icons:
+    - src: https://developer.mozilla.org/favicon-192x192.png
+      type: image/png
+      sizes: 192x192
+    - src: https://developer.mozilla.org/favicon-512x512.png
+      type: image/png
+      sizes: 512x512
+```
+
+For icon `src` you can pass either full URL or a local path relative to the `/app/public` directory. See [Background Image](#background-image) for more detailed information on how to provide your own files.
+
+### Shortcuts
+
+Shortcuts can e used to specify links to tabs, to be preselected when the homepage is opened as an app.
+More information about how you can set them can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts).
+
+```yaml
+pwa:
+  shortcuts:
+    - name: First
+      url: "/#first" # opens the first tab
+    - name: Second
+      url: "/#second" # opens the second tab
+    - name: Third
+      url: "/#third" # opens the third tab
+```
+
+### Other PWA configurations
+
+Homepage sets few other PWA configurations, that are based on global settings in `settings.yaml`:
+
+- `name`, `short_name` - Both equal to the [`title`](#title) setting.
+- `theme_color`, `background_color` - Both based on the [`color`](#color-palette) and [`theme`](#theme) settings.
+- `display` - It is always set to "standalone".
+- `start_url` - Equal to the [`startUrl`](#start-url) setting.
+
+More information for wach of the PWA configurations can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference).
+
 ## Layout
 
 You can configure service and bookmarks sections to be either "column" or "row" based layouts, like so:

docs/widgets/authoring/getting-started.md

@@ -33,6 +33,32 @@ Once dependencies have been installed you can lint your code with
 pnpm lint
 ```
 
+## Testing
+
+Homepage uses [Vitest](https://vitest.dev/) for unit and component tests.
+
+Run the test suite:
+
+```bash
+pnpm test
+```
+
+Run the test suite with coverage:
+
+```bash
+pnpm test:coverage
+```
+
+### What tests to include
+
+- New or updated widgets should generally include a component test near the widget component (for example `src/widgets/<widget>/component.test.jsx`) that covers realistic behavior: loading/placeholder state, error state, and a representative "happy path" render.
+- If you add or change a widget definition file (`src/widgets/<widget>/widget.js`), add/update its corresponding unit test (`src/widgets/<widget>/widget.test.js`) to cover the config/mapping behavior.
+- If your widget requires a custom proxy (`src/widgets/<widget>/proxy.js`), add a proxy unit test (`src/widgets/<widget>/proxy.test.js`) that validates:
+  - request construction (URL, query params, headers/auth)
+  - response mapping (what the widget consumes)
+  - error pathways (upstream error, unexpected payloads)
+- Avoid placing test files under `src/pages/**` (Next.js treats files there as routes). Page tests should live under `src/__tests__/pages/**`.
+
 ## Code formatting with pre-commit hooks
 
 To ensure a consistent style and formatting across the project source, the project utilizes Git [`pre-commit`](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) hooks to perform some formatting and linting before a commit is allowed.

docs/widgets/authoring/proxies.md

@@ -201,3 +201,18 @@ export default async function customProxyHandler(req, res, map) {
 ```
 
 Proxy handlers are a complex topic and require a good understanding of JavaScript and the Homepage codebase. If you are new to Homepage, we recommend using the built-in proxy handlers.
+
+## Testing proxy handlers
+
+Proxy handlers are a common source of regressions because they deal with authentication, request formatting, and sometimes odd upstream API behavior.
+
+When you add a new proxy handler or custom widget proxy, include tests that focus on behavior:
+
+- **Request construction:** the correct URL/path, query params, headers, and auth (and that secrets are not accidentally logged).
+- **Response mapping:** the payload shape expected by the widget/component (including optional/missing fields).
+- **Error handling:** upstream non-200s, invalid JSON, timeouts, and unexpected payloads should produce a predictable result.
+
+Test locations:
+
+- Shared handlers live in `src/utils/proxy/handlers/*.js` with tests alongside them (for example `src/utils/proxy/handlers/generic.test.js`).
+- Widget-specific proxies live in `src/widgets/<widget>/proxy.js` with tests in `src/widgets/<widget>/proxy.test.js`.

docs/widgets/services/arcane.md

@@ -0,0 +1,18 @@
+---
+title: Arcane
+description: Arcane Widget Configuration
+---
+
+Learn more about [Arcane](https://github.com/getarcaneapp/arcane).
+
+**Allowed fields** (max 4): `running`, `stopped`, `total`, `images`, `images_used`, `images_unused`, `image_updates`.
+**Default fields**: `running`, `stopped`, `total`, `image_updates`.
+
+```yaml
+widget:
+  type: arcane
+  url: http://localhost:3552
+  env: 0 # required, 0 is Arcane default local environment
+  key: your-api-key
+  fields: ["running", "stopped", "total", "image_updates"] # optional
+```

docs/widgets/services/dispatcharr.md

@@ -0,0 +1,17 @@
+---
+title: Dispatcharr
+description: Dispatcharr Widget Configuration
+---
+
+Learn more about [Dispatcharr](https://github.com/Dispatcharr/Dispatcharr).
+
+Allowed fields: `["channels", "streams"]`.
+
+```yaml
+widget:
+  type: dispatcharr
+  url: http://dispatcharr.host.or.ip
+  username: username
+  password: password
+  enableActiveStreams: true # optional, defaults to false
+```

docs/widgets/services/dockhand.md

@@ -0,0 +1,20 @@
+---
+title: Dockhand
+description: Dockhand Widget Configuration
+---
+
+Learn more about [Dockhand](https://dockhand.pro/).
+
+Note: The widget currently supports Dockhand's **local** authentication only.
+
+**Allowed fields:** (max 4): `running`, `stopped`, `paused`, `total`, `cpu`, `memory`, `images`, `volumes`, `events_today`, `pending_updates`, `stacks`.
+**Default fields:** `running`, `total`, `cpu`, `memory`.
+
+```yaml
+widget:
+  type: dockhand
+  url: http://localhost:3001
+  environment: local # optional: name or id; aggregates all when omitted
+  username: your-user # required for local auth
+  password: your-pass # required for local auth
+```

docs/widgets/services/index.md

@@ -9,6 +9,7 @@ You can also find a list of all available service widgets in the sidebar navigat
 
 - [Adguard Home](adguard-home.md)
 - [APC UPS](apcups.md)
+- [Arcane](arcane.md)
 - [ArgoCD](argocd.md)
 - [Atsumeru](atsumeru.md)
 - [Audiobookshelf](audiobookshelf.md)
@@ -32,6 +33,8 @@ You can also find a list of all available service widgets in the sidebar navigat
 - [Deluge](deluge.md)
 - [DeveLanCacheUI](develancacheui.md)
 - [DiskStation](diskstation.md)
+- [Dispatcharr](dispatcharr.md)
+- [Dockhand](dockhand.md)
 - [DownloadStation](downloadstation.md)
 - [Emby](emby.md)
 - [ESPHome](esphome.md)

docs/widgets/services/jellyfin.md

@@ -9,11 +9,17 @@ You can create an API key from inside Jellyfin at `Settings > Advanced > Api Key
 
 As of v0.6.11 the widget supports fields `["movies", "series", "episodes", "songs"]`. These blocks are disabled by default but can be enabled with the `enableBlocks` option, and the "Now Playing" feature (enabled by default) can be disabled with the `enableNowPlaying` option.
 
+| Jellyfin Version | Homepage Widget Version |
+| ---------------- | ----------------------- |
+| < 10.12          | 1 (default)             |
+| >= 10.12         | 2                       |
+
 ```yaml
 widget:
   type: jellyfin
   url: http://jellyfin.host.or.ip
   key: apikeyapikeyapikeyapikeyapikey
+  version: 2 # optional, default is 1
   enableBlocks: true # optional, defaults to false
   enableNowPlaying: true # optional, defaults to true
   enableUser: true # optional, defaults to false

docs/widgets/services/vikunja.md

@@ -9,10 +9,16 @@ Allowed fields: `["projects", "tasks7d", "tasksOverdue", "tasksInProgress"]`.
 
 A list of the next 5 tasks ordered by due date is disabled by default, but can be enabled with the `enableTaskList` option.
 
+| Vikunja Version | Homepage Widget Version |
+| --------------- | ----------------------- |
+| < v1.0.0-rc4    | 1 (default)             |
+| >= v1.0.0-rc4   | 2                       |
+
 ```yaml
 widget:
   type: vikunja
   url: http[s]://vikunja.host.or.ip[:port]
   key: vikunjaapikey
   enableTaskList: true # optional, defaults to false
+  version: 2 # optional, defaults to 1
 ```