feat: add id, groupId, and groupTitle support for Windows notifications

[bitdisaster]

Description of Change

This PR extends the Windows notification implementation to support the id, groupId, and groupTitle properties, bringing feature parity with macOS and adding Windows-specific header grouping support.

Changes

New Features:

• id property now works on Windows — maps directly to the toast notification’s Tag property for deduplication and removal.
• groupId property now works on Windows — it serves two purposes:
  • together with id it uniquely identifies a notification in memory
  • maps to the toast notification’s header id property for grouping in Action Center
• groupTitle property (Windows only) — when both groupId and groupTitle are specified, a <header> element is generated in the toast XML to display a visual group header.

Validation:

• Added length validation for id and groupId on Windows (max 64 UTF-16 characters) with descriptive error messages.

Internal Changes:

• Removed FastHash encoding of notification IDs — the raw id is now used directly as the Windows toast Tag.
• Added debug logging for group and tag values when ELECTRON_DEBUG_NOTIFICATIONS is set.

Tests:

• Extended existing macOS tests to also run on Windows (id, groupId properties).
• Added Windows-specific tests for groupTitle.
• Added validation tests for length limits.

---

Example Usage

const { Notification } = require('electron')

// Basic usage with id and groupId
const n = new Notification({
  id: 'msg-123',
  groupId: 'chat-channel-1',
  title: 'New Message',
  body: 'Hello!'
})

// With header grouping (Windows only)
const n2 = new Notification({
  id: 'msg-456',
  groupId: 'camping-trip',
  groupTitle: 'Camping Trip 🏕️',
  title: 'New Message',
  body: 'Are you coming?'
})

Checklist

• PR description included
• I have built and tested this PR
• npm test passes
• tests are changed or added
• relevant API documentation, tutorials, and examples are updated and follow the documentation style guide
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added id, groupId, and groupTitle support for Windows notifications

[erickzhao]

API LGTM

[itsananderson]

API LGTM

[codebytere]

generally lgtm with a few comments

[codebytere]

We're parsing the options dict twice — once here via PeekNext + ConvertFromV8 to validate, and then again inside the Notification constructor. Imo that's a bit redundant and fragile since the two parse sites could diverge.

The gin::Dictionary(nullptr) + the IsEmpty() || IsUndefined() || ConvertFromV8(...)` conditional is also a bit hard to follow — the first two branches fall through into the body with a null-initialized dictionary, which feels like it shouldn't work.

Could we instead construct the Notification first and then validate the already-parsed members before returning the handle? Something like:

auto handle = gin_helper::CreateHandle(thrower.isolate(), new Notification(args));

#if BUILDFLAG(IS_WIN)
  constexpr size_t kMaxTagLength = 64;
  auto* notif = handle.get();
  if (!notif->id_.empty() &&
      base::UTF8ToWide(notif->id_).length() > kMaxTagLength) {
    thrower.ThrowError(
        "Notification id exceeds Windows limit of 64 UTF-16 characters");
    return {};
  }
  if (!notif->group_id_.empty() &&
      base::UTF8ToWide(notif->group_id_).length() > kMaxTagLength) {
    thrower.ThrowError(
        "Notification groupId exceeds Windows limit of 64 UTF-16 characters");
    return {};
  }
#endif

return handle;

That way we validate against the actual values that'll be used at Show() time, and there's a single parse path for the options.

I recognize the downside here that we construct the object before potentially discarding it on the error path, but the constructor is side-effect-free, and CreateHandle + return {} is already the pattern used for the "app not ready" early return above, so it should be safe?

[bitdisaster]

done

[release-clerk]

Release Notes Persisted

Added id, groupId, and groupTitle support for Windows notifications

[trop]

I have automatically backported this PR to "42-x-y", please check out #50895