[CmdPal][TimeDate] Add optional week number to the Clock dock band

[MarcelSchm]

Summary of the Pull Request

Adds an optional calendar week (week number) display to the Command Palette Dock's Clock band.

The Date & Time extension settings get a "Date shown in the Clock dock band" dropdown with six self-contained entries:

• System date (default, unchanged behavior)
• Date and ISO 8601 week number, e.g. "06.07.2026 · W28"
• Date and US week number (week 1 contains January 1st, Excel WEEKNUM option 1)
• Date and week number based on the "First week of the year" and "First day of the week" settings
• ISO 8601 week date, e.g. "2026-W28-1"
• Custom format string, e.g. ddd dd.MM \KW WOY renders as "Mo 06.07 KW 28"

The ISO modes calculate the week with System.Globalization.ISOWeek, since Calendar.GetWeekOfYear misnumbers the year boundary (Dec 31, 2012 returns 53 where ISO 8601 says week 1). The ISO week date uses ISOWeek.GetYear, so the week-based year is correct at the boundary (Jan 1, 2027 shows "2026-W53-5"). The "W" abbreviation is localizable, German would be "KW28". The custom format reuses the custom format engine this extension already uses for its search results; a number-only style works through it as well, e.g. dd.MM.yyyy · WOY. Empty or invalid formats fall back to the system date.

When a week number mode is selected, the context menu of the band offers a "Copy week number" command. There is also a toggle to turn off opening the notification center when clicking the Clock band (default stays on, so the current behavior does not change). The band refreshes immediately when a setting is changed.

Screenshots are in the comments below.

PR Checklist

• Closes: CmdPal Dock: Option to show the calendar week (week number) in the Clock band #49092
• Communication: Discussed in CmdPal Dock: Option to show the calendar week (week number) in the Clock band #49092 with the team, feedback from the reviews there and here is incorporated
• Tests: Added/updated and all pass
• Localization: All end-user-facing strings can be localized
• Dev docs: There are no CmdPal dev docs under doc/devdocs yet, so nothing to update. Happy to add a page if wanted.
• New binaries: Not applicable, no new binaries
• Documentation updated: Not filed yet. Should I open a PR on the docs repo for the new settings once the review here settles, or does the docs team pick that up after merge?

Detailed Description of the Pull Request / Additional comments

• SettingsManager / ISettingsInterface: new settings in the timeDate namespace: ClockBandDateMode (choice, values 0-5), CustomDateFormatInClockBand (text) and ClockBandOpensNotificationCenter (toggle, default on).
• TimeAndDateHelper gains GetDockWeekOfYear (ISO via ISOWeek, US via CalendarWeekRule.FirstDay with Sunday, custom via the existing first week/first day settings), GetIsoWeekDateString and GetClockBandDateLine, which builds the whole date line and is unit-testable with fixed dates. TryFormatCustomString formats a single date with the custom format engine; on invalid formats it falls back to the plain date instead of raw pattern text, since the dock shows the result permanently. WOY in the custom format follows the first week/first day settings, matching the search results.
• NowDockBand (TimeDateCommandsProvider.cs) renders through the helper, serializes updates between the minute timer and the settings changed event, names the no-op click command and disposes its timer; the provider unsubscribes its settings handler on Dispose.
• Choice settings render their description as the visible line, so the dropdowns carry one self-explanatory line each; the date/week separator is a localizable resource.

Validation Steps Performed

• 46 unit tests, including a year-boundary matrix for the Dec 28 to Jan 4 window on different weekdays (long ISO years 2015/2020/2026, week 1 reaching into the old year, the 2012-12-31 regression case), Excel WEEKNUM parity checks for options 1 and 2, the ISO week date representation including the week-based year, all six display modes, invalid and empty custom formats, and the notification center click toggle.
• All tests pass locally, compiled against the published Microsoft.CommandPalette.Extensions NuGet SDK (the full solution build is left to CI).
• Manually validated on a local Release x64 build, screenshots are in the comments.

🤖 Generated with Claude Code

[MarcelSchm]

@microsoft-github-policy-service agree

[MarcelSchm]

Screenshots from a local build of this PR (Release x64, German locale system):

Before (toggle off, default):

After ("Show week number in the Clock dock band" enabled — ISO 8601 week numbering from the system settings):

[htcfreek]

My thoughts on the layout: Support short display by either show only the number or show an abbreviation of Calendar Week (e.g. in Germany: KW).

[MarcelSchm]

My thoughts on the layout: Support short display by either show only the number or show an abbreviation of Calendar Week (e.g. in Germany: KW).

will do so and update shortly

[MarcelSchm]

@htcfreek Thanks for the feedback, done in ad4a454.

The dock now shows a short localizable abbreviation instead of the full word, so "CW 27" in English. I left a note for the translators to use the local abbreviation (like "KW" in German). If you prefer just the number, there is a new dropdown "Week number format in the Clock dock band" where you can switch to "Number only".

While testing this I also added a small toggle to turn off opening the notification center when clicking the Clock band. Default stays on, so nothing changes unless you opt out. If you'd rather keep this PR focused I can move that part into a separate PR, just let me know.

Updated dock (German locale, ISO 8601):

And this is how the new settings look:

[MarcelSchm]

Update in 3af2914, based on the discussion in #49092:

The week number now uses the short ISO style form, so the dock shows "05.07.2026 · W27":

There is a new "Date shown in the Clock dock band" dropdown that replaces the earlier toggle plus format choice. It has four options: system date, date with week number, date with the bare number, and a custom format string. That last one reuses the custom format engine this extension already has for its search results, so ddd dd.MM \W WOY gives you this (no year, as suggested):

The reworked settings page:

[MarcelSchm]

Two more commits based on the review in #49092.

b0eb89b switches the week calculation to System.Globalization.ISOWeek and merges display mode and numbering system into a single dropdown: system date, date with ISO week number (default), date with US week number, date with week number from the first week and first day settings, ISO week date, custom format. New boundary tests cover the Dec 28 to Jan 4 window on different weekdays, the 2012/2013 case where Calendar.GetWeekOfYear returns 53 instead of W1, Excel WEEKNUM parity and the week-based year of the ISO week date.

42afc7a hardens the band update: invalid custom formats fall back to the plain date instead of raw pattern text, updates are serialized between the timer and the settings event, and the timer and settings handler get cleaned up on Dispose.

The dock with the ISO default:

The reworked settings section:

The full mode list:

[daverayment]

Great! Thanks for making the change to the ISO week number calculation and for adding the unit tests around that.

I think there are still some structural issues which need to be ironed out before we proceed.

Consolidating the drop-downs has resulted in a single control which is now representing too many different things and is potentially confusing for the user. There's both a choice between ISO/US/Custom week number format and a choice of display format options in the same list and they aren't described. Users aren't being given enough information here to make an informed decision and the lack of cascading selections compounds the problem.

There's a related issue with this approach in that choosing Custom means that the user is unable to include the ISO week number in their format. This is likely to be something that would be raised as a bug and/or we'd get requests to add more and more date formats to the single drop-down making it more unwieldy.

Keeping the axes separate is the key here, so I think splitting into "Week number system" and "Display format" is necessary. Also, having radio buttons or a segmented/pivot control for the week number system gives us a chance to include explanatory text, as the majority of users won't know the difference between ISO 8601 and US systems.

Sketch mock-up:

Week number system:

  [ ] US
      The first week of the year always January 1. Choose your own first day of the week below.
      Default: Sunday is the first day of the week. Default format: "'Week' WOY, yyyy" - "Week 27, 2026".

  [ ] ISO 8601
      Monday is the first day of the week. The first week contains the first Thursday of the calendar year.
      Default format: "yyyy-'W'WOY" - "2026-W27".

  [ ] Manual (choose your own settings below) (default)
      Set "First day of the week" and "First week of the year" independently. These default to your system settings.

First day of the week:
[System default/Sunday/Monday/Tuesday/Wednesday/Thursday/Friday] (Localised - Disabled if ISO is chosen above; Enabled for both US and Manual.)

First week of the year:
[System default/First day/First full week/First four-day week] (Localised - Disabled if ISO or US is chosen above; Enabled for Manual.)
Choose "First day" to have the first week of the year as the one containing January 1; "First full week" to have it as the first full week of the year; or "First four-day week" as the first week with at least four days in the new year.

Custom date format:
[        ]
Use "WOY" for the Week Number. Uses whichever week number system is chosen above. The custom format box is always available.

Examples:
"yyyy Week WOY" - "2026 Week 27"
"ddd dd/MM 'W'WOY" - "Tues 08/07 W27"
"dd/MM 'W'WOY" - "08/07 W27"
"'CW' WOY" - "CW 27"
etc.

Preview:
Your date and time will display as:

    08/07 W27

(I haven't confirmed the Examples yet, so apologies if they need reformatting.)

If no custom date format is chosen and the user has chosen ISO 8601 for the Week number system, the format should be "yyyy-Www" to be compliant with the standard, e.g. "2026-W27". There isn't a canonical date format for the US week number system, and Excel's WEEKNUM doesn't dictate one either, so we'd need to come up with a sensible default that respects the locale. What do you think?

By the way, I've chosen to have "Manual" instead of "Custom" as a Week number system option because otherwise we have two unrelated controls with Custom in their names, and users could assume that if they didn't select Custom week number that their custom date format would not be used.

I nearly forgot: please confirm ISO week numbers 1-9 are zero-padded to 2 digits (so "W03" and not "W3"). If there isn't a unit test covering this already, it should be added.

Happy to discuss the above if you can think of improvements.

Edit: corrected a couple of issues with the mock-up because I had the US format locking both the First day of week and First week of year options, which is incorrect - the US format always has the week containing January 1st as the first week, but the first day is only Sunday by default and may be customised (i.e. WEEKNUM options 11-17). Sorry for the mix-up.

[htcfreek]

@daverayment , @MarcelSchm
I don't like both suggestions! First off all, mixing display format and calculation behavior is confusing. And secondary why do we need two settings for calculation behavior?

And why do we need a new drop-down to choose what works yet without it. By the way Outlook only has the two settings for First Week and First Day Of Week.

I think we should keep ist as simple as possible and I suggest to use the existing setting (first week, first day) only which are most flexible. And the we can add a new dock clock layout setting support the following: Week n|CW n|Custom.

[daverayment]

@htcfreek That's good feedback. Thanks.

The need for the week number system to be handled separately is because ISO 8601 and the US/Manual systems use different calculations for the week number. @MarcelSchm and I had a discussion about this on the original issue thread. If we don't distinguish between the two systems then the week numbers at the end and/or start of the year will be wrong for some years. Specifically, ISO 8601 dictates that ISOWeek.GetWeekOfYear()/GetYear() needs to be used instead of Calendar.GetWeekOfYear(). Whichever UI decisions we make are secondary to this, as it's a correctness matter.

What Outlook is likely doing is assuming that if the user selected year start as "First four-day week" and "Monday" as the first day of the week then they want the ISO 8601 week numbers shown. (I don't have Outlook, so I can't check this, sorry.) I was making this an explicit choice in my UI so the user would be kept informed and wouldn't have to look it up in a separate help guide.

We can't use Windows region settings or the locale defaults from .NET to discern whether the user wants ISO 8601 or not because these don't include that preference, and only the locale defaults and if the user has overridden the first day of the week in their own Date & Time Settings choice.

The fundamental decision now is whether we have a separate option to expose the ISO/non-ISO choice to the user or do like Outlook does and assume that if the user selects "First four-day week" and "Monday" that they want ISO 8601 week numbers. Simplifying the UI is a worthy goal, so the latter is likely better, reducing us back to two drop-downs. However, we need to be careful:

1. The user should be informed. (It sounds like Outlook is failing on this front.) For example, we could have the entry read "First four-day week (Monday start – ISO 8601 format)" or similar. An extra note beneath may be valuable, too, like "Tip: select "First four-day week" for ISO 8601 compliant week numbers."
2. If the user chooses this "First four-day week" option then it mandates Monday as the start of the week. Choosing anything else from the "First day of week" drop-down is incompatible with ISO 8601, so we need to enforce this. We can handle this by either auto-selecting Monday and disabling the control or auto-selecting Monday and then showing an alert if the user tries to select a different day. Probably better to do the former, possibly with a note beneath saying "Monday start selected for ISO 8601 compliance." or similar.

Simplifying the choice of week number string format is definitely a good suggestion, but I'm unsure about whether your options are designed to replace the whole text for the display or are just suffixes for the existing date-time format. The week number can't be just a suffix, though, because users may want the week number in the middle of their day/month/year string. The ISO format with day of week, for example, is "yyyy-W[week number]-[day of week]", e.g. "2026-W27-2".

Yeah, this is complicated! Let's keep refining.

[htcfreek]

@daverayment , @MarcelSchm
Good to know that it's so complicated with the calculation. At the point of implementing the settings I only had a screenshot from Outlook and the request to implement the two settings 😅.

We should make sure that dock and plugin results calculates in the same way. And that brings me to the point suggesting:

• reworking the day and week setting and calculation as I suppose that we should support all possible calculations.
• implement a new doc only display format setting.

The only thing I am unsure: These two settings (first day, first week) are not only used for the calculation of the week number as I imagine. Are the other results calculated based on these settings affected from the new format too?

[MarcelSchm]

@daverayment @htcfreek I'd go with htcfreek's direction. It also solves the custom format problem Dave found, see below.

Calculation: the existing "First week of the year" and "First day of the week" settings stay the only source of truth, no new week number system control. When the two settings amount to ISO 8601 (first four-day week + Monday, which is also the default in most European locales) the calculation goes through System.Globalization.ISOWeek, so the year boundary is correct. "First four-day week" with another start day is still a valid non-ISO calculation, so nothing needs to be locked or disabled. The Excel WEEKNUM variants map onto the two settings anyway (1 = first-day rule + Sunday, 11-17 = first-day rule + other days, 21 = ISO), I'll keep the parity tests.

That also answers the question about the other results: yes, the search results use the same two settings, and they have the same boundary bug today ("week of year" in the search results shows 53 for Dec 31, 2012 with ISO settings). So the fix goes into the shared calculation and dock and search results always agree.

And since there is only one calculation left, WOY in the custom format is always the same number as everywhere else. If your settings are ISO, WOY is ISO.

Display: a dock-only format setting, cut down from six entries to four:

Date shown in the Clock dock band:
  [ System date                          "08.07.2026" ]   (default)
  [ Date and week number                 "08.07.2026 · W28" ]
  [ ISO 8601 week date                   "2026-W28-2" ]
  [ Custom format string ]

Custom date format for the Clock dock band:
  [ ddd dd.MM \KW WOY                    "Mi 08.07 KW 28" ]
  Only used when "Custom format string" is selected above.
  WOY uses the week numbering from the settings below.

First week of the year:   (existing setting, shared with search results)
  [ System default / First day / First full week / First four-day week ]
  First four-day week with Monday as first day = ISO 8601.

First day of the week:    (existing setting, shared with search results)
  [ System default / Monday / ... / Sunday ]

The ISO week date keeps its own entry because the week-based year can't be expressed in a custom format string (yyyy is the calendar year, which is the wrong year at the boundary).

Two more points from the review:

• Zero padding: the ISO week date is padded already ("2026-W03-1"), I'll add a test for it. The short "· W3" form is currently unpadded, I'd keep it that way since it's not an ISO string, but no strong opinion.
• Disabling controls based on another setting and a live preview both need support from the extension settings framework first, that doesn't exist today. I'd put the ISO hint into the description text of the existing settings instead and treat conditional controls plus preview as a separate issue.

If that works for both of you I'll rework the PR accordingly.