feat: expand utility widgets

apps/docs/docs/widgets/air-quality/index.mdx

@@ -0,0 +1,47 @@
+---
+title: "Air Quality & UV"
+description: "Displays air quality, ultraviolet index, pollutants and pollen for a location."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { airQualityWidget } from ".";
+
+<WidgetHeader widget={airQualityWidget} categories={["Health", "Weather"]} />
+
+The Air Quality & UV widget shows the current air quality index for a selected location. It adds the UV index,
+dominant pollutant, particulate matter and the highest available pollen reading as space allows. Open the advanced
+view for a 24-hour AQI and UV chart, all available pollutant and pollen readings, and seven-day daily maxima.
+
+Select the European or US AQI scale, or use the automatic setting. Automatic uses the US scale for viewers whose
+locale region is the United States and the European scale everywhere else. The selected scale is always shown next
+to the value. Pollen values are individual measured concentrations; the widget does not combine them into a single
+pollen index.
+
+The categories and colors summarize published index bands and are not medical advice. Pollutant concentrations use
+micrograms per cubic meter (`µg/m³`), and pollen uses grains per cubic meter.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={airQualityWidget.configuration} />
+
+### Data source
+
+Homarr uses the free Open-Meteo Air Quality API. The widget refreshes active data every 15 minutes and requests a
+seven-day forecast for European AQI, US AQI, UV, particulate matter, ozone, nitrogen dioxide, sulphur dioxide, carbon
+monoxide, and available alder, birch, grass, mugwort, olive and ragweed pollen. Identical location requests reuse the
+server response for 15 minutes. If a refresh fails, Homarr can keep a recent successful response visible for up to 24
+hours instead of replacing it with an empty state.
+
+Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests. If you need to allowlist the
+service, use `https://air-quality-api.open-meteo.com`.

apps/docs/docs/widgets/air-quality/index.ts

@@ -0,0 +1,43 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconWind } from "@tabler/icons-react";
+
+export const airQualityWidget: WidgetDefinition = {
+  icon: IconWind,
+  name: "Air Quality & UV",
+  description: "Displays air quality, ultraviolet index, pollutants and pollen for a location.",
+  path: "../../widgets/air-quality",
+  configuration: {
+    items: [
+      {
+        name: "Air quality location",
+        description: "Location used for air quality, UV and pollen data",
+        values: "Select a location through search or longitude/latitude",
+        defaultValue: "Paris / 48.85341, 2.3488",
+      },
+      {
+        name: "AQI standard",
+        description: "Choose the European or US air quality scale, or select one from the viewer's locale",
+        values: { type: "select", options: ["Automatic for locale", "European AQI", "US AQI"] },
+        defaultValue: "Automatic for locale",
+      },
+      {
+        name: "Show UV index",
+        description: "Display the current UV index and its forecast",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show pollutant concentrations",
+        description: "Display particulate matter and gaseous pollutant concentrations",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show pollen concentrations",
+        description: "Display available pollen concentrations",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/clock/index.mdx

@@ -15,6 +15,26 @@ import { clockWidget } from ".";
 
 The clock widget displays the current date and time in a customizable format.
 
+Advanced view turns it into a World Clock. The configured primary timezone stays prominent while New York, Paris, and
+Tokyo are included as secondary defaults. You can add, rename, remove, and reorder up to six cities in widget options;
+London, Sydney, and UTC are also available as quick presets.
+
+The digital advanced view keeps the primary timezone prominent and presents every secondary city as a concise,
+comparable card. The primary clock includes a segmented 24-hour rail with a current-time marker, elapsed and remaining
+time, six-hour ticks, and a legend for night, dawn, day, and dusk. These phases are based on local clock time and are not
+astronomical sunrise or sunset calculations. Secondary cards stop after their localized date and timezone offsets.
+
+The compact widget remains a single numeric clock. The time-format selector shows common Day.js presets with live
+examples and applies to the primary clock. Choosing a format with seconds enables second-level updates; 12-hour and
+24-hour display are selected through those same formats. The date-format selector likewise
+shows live Day.js examples and their tokens. Secondary cities always include a short localized date and a
+Yesterday, Today, or Tomorrow label relative to the primary timezone. UTC and relative offsets follow current timezone
+rules, including daylight-saving changes.
+
+Weather remains optional and uses its own configured location rather than a World Clock city. Its icon is static by
+default and can be animated explicitly; reduced-motion preferences always disable animation. An unsupported saved
+timezone is identified without preventing valid clocks from rendering.
+
 ### Screenshots
 
 import localClock from "./img/local.png";
@@ -27,7 +47,7 @@ import tokyoClock from "./img/tokyo-12-hour.png";
   <img src={tokyoClock} alt="clock format-12-hours timezone-tokyo" width={256} height={128} />
 </div>
 
-<WidgetInteractionGuide advancedView={false} />
+<WidgetInteractionGuide />
 
 ### Adding the widget
 

apps/docs/docs/widgets/clock/index.ts

@@ -20,18 +20,6 @@ export const clockWidget: WidgetDefinition = {
         values: { type: "string" },
         defaultValue: "-",
       },
-      {
-        name: "24-hour format",
-        description: "Use 24-hour format instead of 12-hour format.",
-        values: { type: "boolean" },
-        defaultValue: "yes",
-      },
-      {
-        name: "Display seconds",
-        description: "Whether to show seconds in the clock.",
-        values: { type: "boolean" },
-        defaultValue: "no",
-      },
       {
         name: "Use fixed timezone",
         description: "Select custom timezone to display instead of the client timezone.",
@@ -52,21 +40,46 @@ export const clockWidget: WidgetDefinition = {
       },
       {
         name: "Date format",
-        description: "Format of the date displayed below the clock.",
-        values: "A collection of date formats, e.g. 'DD/MM/YYYY', 'MM/DD/YYYY', etc.",
+        description: "Choose a common Day.js date format with a live example and its tokens.",
+        values: "YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY, or common long and short date formats",
         defaultValue: "dddd, MMMM D",
       },
       {
-        name: "Custom time format",
-        description: "Format of the time displayed in the clock.",
-        values: 'ISO 8601 format, e.g. "HH:mm:ss", "hh:mm A", etc.',
-        defaultValue: "-",
+        name: "Time format",
+        description:
+          "Choose a common Day.js time format with a live example. The format controls 12/24-hour display and seconds.",
+        values: "HH:mm, HH:mm:ss, h:mm A, or h:mm:ss A",
+        defaultValue: "HH:mm",
       },
       {
-        name: "Custom date format",
-        description: "Format of the date displayed below the clock.",
-        values: 'ISO 8601 format, e.g. "YYYY-MM-DD", "DD/MM/YYYY", etc.',
-        defaultValue: "-",
+        name: "Show weather",
+        description: "Show a compact weather summary from an independently configured location.",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "Weather location",
+        description: 'Location used by the weather summary. Only shown if "Show weather" is enabled.',
+        values: "A searched city or custom latitude and longitude",
+        defaultValue: "Brisbane",
+      },
+      {
+        name: "Use Fahrenheit",
+        description: 'Use Fahrenheit in the weather summary. Only shown if "Show weather" is enabled.',
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "Animate weather icon",
+        description: "Animate the weather icon unless the device requests reduced motion.",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "World clock cities",
+        description: "Add, label, and order up to six IANA timezones for advanced view.",
+        values: "Up to six labeled IANA timezones",
+        defaultValue: "New York, Paris, and Tokyo",
       },
     ],
   },

apps/docs/docs/widgets/countdown/index.mdx

@@ -0,0 +1,44 @@
+---
+title: "Countdowns"
+description: "Tracks upcoming events and recurring anniversaries."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { countdownWidget } from ".";
+
+<WidgetHeader widget={countdownWidget} categories={["Time"]} />
+
+The Countdowns widget tracks up to 20 events without an integration. Add each event in widget options, choose its local
+date and time, and select an IANA timezone. Events can be reordered by dragging them.
+
+The compact widget shows the first configured event, so dragging an event to the top selects the countdown displayed on
+the board. Advanced view uses that same event for its larger summary and preserves the configured order within its
+upcoming and completed groups. List cards keep their occurrence date at the bottom, below the optional progress bar.
+
+One-time events remain completed after their target. A yearly event keeps the same local date and wall-clock time in its
+configured timezone, including when daylight-saving offsets change. A February 29 event waits until the next leap year.
+If a configured local time falls in a daylight-saving gap, the first valid time afterward is used; if it occurs twice,
+the earlier occurrence is used.
+
+Progress is optional. One-time events need a start date before a percentage can be calculated. Yearly events show
+progress from the previous occurrence to the next. When enabled, seconds remain visible for every upcoming event.
+
+Browser notifications are an optional local preference in advanced view and are disabled by default. Permission is
+requested only after you enable notifications, and alerts can fire once per occurrence while Homarr is open. Browser
+storage uses the board and widget identifiers to keep preferences separate and prevent duplicate alerts; clearing site
+data resets them. Widget previews do not persist alert preferences.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={countdownWidget.configuration} />

apps/docs/docs/widgets/countdown/index.ts

@@ -0,0 +1,31 @@
+import { WidgetDefinition } from "@site/src/types";
+import { IconHourglass } from "@tabler/icons-react";
+
+export const countdownWidget: WidgetDefinition = {
+  icon: IconHourglass,
+  name: "Countdowns",
+  description: "Tracks upcoming events and recurring anniversaries.",
+  path: "../../widgets/countdown",
+  configuration: {
+    items: [
+      {
+        name: "Events",
+        description: "Add, edit, and order one-time or yearly events with a date, time, and IANA timezone.",
+        values: "Up to 20 events",
+        defaultValue: "No events",
+      },
+      {
+        name: "Show progress",
+        description: "Show progress from an optional start date, or between yearly occurrences.",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show seconds",
+        description: "Keep seconds visible for every upcoming event, including events more than a day away.",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/timer/index.mdx

@@ -0,0 +1,52 @@
+---
+title: "Timer / Pomodoro"
+description: "Runs a simple timer or a configurable Pomodoro sequence."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { timerWidget } from ".";
+
+<WidgetHeader widget={timerWidget} categories={["Productivity", "Time"]} />
+
+The Timer / Pomodoro widget runs entirely in your browser and does not require an integration. The compact widget
+always keeps its start or pause button and reset button visible. A running timer uses a saved deadline, so reopening
+the board or returning to a background tab restores the correct remaining time instead of restarting the countdown.
+
+Timer mode repeats one configured duration. Pomodoro mode starts with a focus session, follows most completed focus
+sessions with a short break, and uses a long break after the configured number of focus sessions. Automatic break and
+focus starts are separate options and are disabled by default. When automatic starts are enabled, elapsed phases are
+reconciled from their original deadlines after the board returns to the foreground.
+
+Advanced view shows the current sequence, configured durations, and local alert preferences. Browser notifications are
+requested only when enabled. Notification and sound preferences, live progress, deadlines, and cycle position are
+stored locally using the board and widget identifiers. They are separate for each browser or device, are available to
+guest viewers, and are removed by clearing site data. Widget previews are ephemeral and do not write local timer state.
+
+Timer sounds are enabled by default and use the same low-volume Tiks sound system as onboarding: start and pause use
+rising and falling soft-theme cues, reset uses a short click, and phase completion uses the glass theme's resonant
+notification ding. You can disable them in advanced view. The cues respect the device's reduced-motion preference and
+supplement the visible timer state rather than replacing it.
+
+When automatic start is disabled, a completed phase labels the next step as ready and flashes the widget edges with the
+board's secondary color. The border glow and completion chime run together as a five-beat alarm burst at
+300-millisecond intervals, then stop. Reduced-motion and forced-colors modes replace the flash with a static border.
+Compact controls also step down in size when the widget preview is narrow or short.
+
+Alerts can fire while Homarr is open. Browser and operating-system notification settings may still suppress them.
+The timer's mode, durations, session count, and automatic-start behavior are permanent board settings and are edited
+from the widget context menu.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={timerWidget.configuration} />

apps/docs/docs/widgets/timer/index.ts

@@ -0,0 +1,61 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconClockPlay } from "@tabler/icons-react";
+
+export const timerWidget: WidgetDefinition = {
+  icon: IconClockPlay,
+  name: "Timer / Pomodoro",
+  description: "Runs a simple timer or a configurable Pomodoro sequence.",
+  path: "../../widgets/timer",
+  configuration: {
+    items: [
+      {
+        name: "Mode",
+        description: "Run one reusable timer or a repeating focus and break sequence",
+        values: { type: "select", options: ["Timer", "Pomodoro"] },
+        defaultValue: "Pomodoro",
+      },
+      {
+        name: "Timer minutes",
+        description: "Duration of the reusable timer",
+        values: "1-1440 minutes",
+        defaultValue: "10",
+      },
+      {
+        name: "Focus minutes",
+        description: "Duration of each Pomodoro focus session",
+        values: "1-180 minutes",
+        defaultValue: "25",
+      },
+      {
+        name: "Short break minutes",
+        description: "Duration of breaks between most focus sessions",
+        values: "1-60 minutes",
+        defaultValue: "5",
+      },
+      {
+        name: "Long break minutes",
+        description: "Duration of the break at the end of a Pomodoro cycle",
+        values: "1-180 minutes",
+        defaultValue: "15",
+      },
+      {
+        name: "Focus sessions before a long break",
+        description: "Number of completed focus sessions in one Pomodoro cycle",
+        values: "1-12 sessions",
+        defaultValue: "4",
+      },
+      {
+        name: "Automatically start breaks",
+        description: "Start the next short or long break when a focus session completes",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+      {
+        name: "Automatically start focus sessions",
+        description: "Start the next focus session when a break completes",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/today/index.mdx

@@ -0,0 +1,34 @@
+---
+title: "Today"
+description: "Displays the current date and progress through the calendar."
+hide_title: true
+---
+
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { todayWidget } from ".";
+
+<WidgetHeader widget={todayWidget} categories={["Date", "Time"]} />
+
+The Today widget presents the current local date without duplicating a live clock. It progressively adds the week
+number, day of year, quarter, remaining days, and calendar progress as more space becomes available.
+
+The advanced view shows week, month, and year progress together with a twelve-month overview. Week numbers can follow
+your locale or the ISO 8601 convention. “Days after today” excludes the current day to keep the remaining-day count
+unambiguous.
+
+The widget runs entirely in your browser and does not send date or location data to an external service. It follows
+the timezone and locale of the device viewing the board, so viewers in different regions can see their own local date.
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={todayWidget.configuration} />

apps/docs/docs/widgets/today/index.ts

@@ -0,0 +1,43 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconCalendarWeek } from "@tabler/icons-react";
+
+export const todayWidget: WidgetDefinition = {
+  icon: IconCalendarWeek,
+  name: "Today",
+  description: "Displays the current date and progress through the calendar.",
+  path: "../../widgets/today",
+  configuration: {
+    items: [
+      {
+        name: "Week numbering",
+        description: "Use locale-specific week numbering or ISO 8601 week numbers",
+        values: { type: "select", options: ["Use locale rules", "ISO 8601"] },
+        defaultValue: "Use locale rules",
+      },
+      {
+        name: "Show week number",
+        description: "Display the current week number when the widget has room",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show day of year",
+        description: "Display the current day number within the year",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show quarter",
+        description: "Display the current calendar quarter",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show year progress",
+        description: "Display progress through the current year",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/weather/index.mdx

@@ -13,23 +13,21 @@ import { weatherWidget } from ".";
 
 <WidgetHeader widget={weatherWidget} categories={["Weather"]} />
 
-The Weather Widget uses your location to display the current, highest and lowest temperature.
-In the compact view, select a condition icon or forecast day to open details with a mouse, keyboard or touch.
-The compact forecast shows up to the configured number of days. The advanced view combines current conditions with the
-available daily forecast, including humidity, wind, gusts, sunrise and sunset. Both views reuse the same cached Open
-Meteo response.
+The Weather Widget displays current conditions and a responsive forecast for a selected location. New widgets start
+with the city and a three-day forecast visible. As the widget gets smaller, it keeps the current condition and
+temperature readable before removing secondary details or forecast days.
 
-### Screenshots
+Select a forecast day to inspect precipitation, apparent temperature, humidity, wind, UV index, sunrise, sunset and
+daylight duration with a mouse, keyboard or touch. Open the advanced view for a current-condition summary, a 24-hour
+temperature and precipitation chart, and the complete seven-day forecast. The chart has an equivalent data table for
+assistive technologies.
 
-import forecastWeather from "./img/forecast.png";
-import currentWeather from "./img/current.png";
-import advancedWeather from "./img/advanced-view.png";
+The **Show humidity** option controls humidity across the compact current-conditions view, advanced summary, hourly
+details, and daily forecast details. Forecast cards use a roomier adaptive grid in advanced view, with four columns on
+the standard desktop surface and fewer columns as the surface narrows.
 
-<div className="flex flex-col gap-1">
-  <img src={forecastWeather} alt="Weather compact forecast" width={238} height={112} />
-  <img src={currentWeather} alt="Weather compact current conditions" width={198} height={93} />
-  <img src={advancedWeather} alt="Weather advanced view with seven-day forecast details" width={800} height={484} />
-</div>
+Weather icons are static by default. Animation can be enabled in the widget configuration, but the operating system's
+reduced-motion preference always disables it.
 
 <WidgetInteractionGuide />
 
@@ -43,5 +41,10 @@ import advancedWeather from "./img/advanced-view.png";
 
 ### Data source
 
-We use the Open Meteo API to fetch the weather and locations.
+We use the Open Meteo API to fetch the weather and locations. Active weather data refreshes every ten minutes, while
+identical location requests can reuse a server response for five minutes. A manual refresh may therefore return the
+same still-current server response. If a refresh fails, Homarr keeps the last successful data visible and shows an
+error indicator.
+
+Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests.
 If you need to whitelist the api, please use the following URL: `https://open-meteo.com`

apps/docs/docs/widgets/weather/index.tsx

@@ -28,8 +28,24 @@ export const weatherWidget: WidgetDefinition = {
         values: {
           type: "boolean",
         },
+        defaultValue: "no",
+      },
+      {
+        name: "Show humidity",
+        description: "Display humidity in current conditions, hourly details, and daily forecasts",
+        values: {
+          type: "boolean",
+        },
         defaultValue: "yes",
       },
+      {
+        name: "Animate weather icons",
+        description: "Animate condition icons unless the operating system requests reduced motion",
+        values: {
+          type: "boolean",
+        },
+        defaultValue: "no",
+      },
       {
         name: "Use imperial speed units",
         description: "Display wind speed in mph instead of km/h",
@@ -59,7 +75,7 @@ export const weatherWidget: WidgetDefinition = {
         values: {
           type: "boolean",
         },
-        defaultValue: "no",
+        defaultValue: "yes",
       },
       {
         name: "Has forecast",
@@ -67,13 +83,13 @@ export const weatherWidget: WidgetDefinition = {
         values: {
           type: "boolean",
         },
-        defaultValue: "no",
+        defaultValue: "yes",
       },
       {
         name: "Amount of forecast days",
         description: "Number of days to show in the forecast",
         values: "1-7",
-        defaultValue: "5",
+        defaultValue: "3",
       },
     ],
   },

apps/docs/src/components/pages/home/hero/widgets/weather-widget.tsx

@@ -1,4 +1,4 @@
-import { IconCloud, IconWind, IconArrowUpRight, IconArrowDownRight } from "@tabler/icons-react";
+import { IconCloud, IconCloudRain, IconSun } from "@tabler/icons-react";
 import { CommonWidgetProps, WidgetCard } from "./card";
 import clsx from "clsx";
 
@@ -6,21 +6,27 @@ export const WeatherWidget = ({ className }: CommonWidgetProps) => {
   return (
     <WidgetCard width={1} className={clsx("gap-2", className)}>
       <div className="flex gap-2 justify-center items-center">
-        <IconCloud size={20} />
-        <span className="text-xl font-bold">10.8°C</span>
-      </div>
-      <div className="flex gap-2 justify-center items-center">
-        <IconWind size={14} />
-        <span className="text-sm">5 km/h</span>
-      </div>
-      <div className="flex gap-1 justify-center items-center">
-        <div className="flex justify-center items-center">
-          <IconArrowUpRight size={14} />
-          <span className="text-sm">13.5°C</span>
+        <IconSun size={22} />
+        <div className="flex flex-col leading-none">
+          <span className="text-xl font-bold">18.4°C</span>
+          <span className="text-xs text-muted-foreground">Paris</span>
         </div>
-        <div className="flex justify-center items-center">
-          <IconArrowDownRight size={14} />
-          <span className="text-sm">6.4°C</span>
+      </div>
+      <div className="flex justify-evenly items-center w-full">
+        <div className="flex flex-col items-center text-xs">
+          <span>Mon</span>
+          <IconSun size={16} />
+          <span>21°</span>
+        </div>
+        <div className="flex flex-col items-center text-xs">
+          <span>Tue</span>
+          <IconCloud size={16} />
+          <span>19°</span>
+        </div>
+        <div className="flex flex-col items-center text-xs">
+          <span>Wed</span>
+          <IconCloudRain size={16} />
+          <span>16°</span>
         </div>
       </div>
     </WidgetCard>