fix(hotkeys): mac hotkeys follow Apple's Human Interface Guidelines

[IanWorley]

🎯 Changes

• Provide a code change that now displays mac hotkeys in the proper order set out by (Apple's Human Interface Guidelines)[https://developer.apple.com/design/human-interface-guidelines/keyboards]
• Wrote documentation of said code changes mention above.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes

  • Updated macOS hotkey displays to follow Apple’s standard modifier order: Control, Option, Shift, then Command.
  • Mixed shortcuts such as Mod+Shift+S now display as ⇧ ⌘ S on macOS.
  • Windows and Linux hotkey formatting remains unchanged.

• Documentation

  • Updated macOS hotkey formatting examples to reflect the revised ordering.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 560d369c-5d0b-48c9-89d6-a7c3e50be885

📥 Commits

Reviewing files that changed from the base of the PR and between 7f0efab and 1b94343.

📒 Files selected for processing (3)

• .changeset/tangy-mangos-clap.md
• packages/hotkeys/src/format.ts
• packages/hotkeys/tests/format.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• .changeset/tangy-mangos-clap.md
• packages/hotkeys/tests/format.test.ts

---

📝 Walkthrough

Walkthrough

macOS hotkey display formatting now orders modifiers according to Apple HIG, including Mod alias resolution. Tests cover symbols, text labels, separators, parsed hotkeys, and unchanged Windows behavior. A patch changeset documents the macOS-only behavior.

Changes

macOS modifier ordering

Layer / File(s)	Summary
macOS formatter ordering packages/hotkeys/src/format.ts, .changeset/tangy-mangos-clap.md	formatForDisplay resolves macOS modifiers, sorts them into Apple HIG order, updates examples, and records a patch release.
Formatter ordering tests packages/hotkeys/tests/format.test.ts	macOS symbol and label expectations now place Shift before Command, while Windows behavior remains unchanged; multi-modifier coverage is added.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant formatForDisplay
  participant toAppleHIGModifierOrder
  participant resolveModifier
  formatForDisplay->>toAppleHIGModifierOrder: normalize macOS hotkey ordering
  toAppleHIGModifierOrder->>resolveModifier: resolve Mod for macOS
  resolveModifier-->>toAppleHIGModifierOrder: resolved modifier
  toAppleHIGModifierOrder-->>formatForDisplay: ordered hotkey for display mapping

Loading

Possibly related issues

• formatForDisplay orders macOS modifiers differently from Apple HIG #136 — The pull request implements the requested macOS Apple HIG modifier ordering, including Mod+Shift+S.

Poem

A bunny taps Shift, then Command with care,
Apple-shaped symbols hop through the air.
Mod finds its Mac-side name,
Tests twirl through the ordering game.
Windows stays steady, ears held high!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: macOS hotkeys now follow Apple's Human Interface Guidelines.
Description check	✅ Passed	The description includes the required Changes, Checklist, and Release Impact sections and covers the core implementation and changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}