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

• Improvements

  • Updated macOS shortcut formatting to follow Apple’s modifier order, displaying Shift before Command.
  • macOS symbols are now separated by spaces, while Windows/Linux retain canonical + formatting.
  • Improved platform-specific shortcut labels and modifier reference tables.

• Documentation

  • Updated React, Preact, Solid, and Lit guides with the revised formatting examples and platform guidance.
  • Refreshed keyboard badge examples and platform symbol references.

• Tests

  • Added and updated coverage for macOS modifier ordering, symbols, labels, and platform-specific formatting.

[coderabbitai]

📝 Walkthrough

Walkthrough

macOS hotkey formatting now orders modifiers as Control → Option → Shift → Command, resolves Mod for macOS before ordering, and updates tests plus Lit, Preact, React, and Solid documentation.

Changes

macOS Modifier Ordering

Layer / File(s)	Summary
macOS formatter ordering packages/hotkeys/src/format.ts	formatForDisplay reorders macOS modifiers using Apple HIG ordering and resolves the macOS Mod alias.
Formatter ordering tests packages/hotkeys/tests/format.test.ts	macOS symbol and label expectations now place Shift before Command, with new coverage for both symbol and text output. Windows/Linux canonical ordering remains covered.
Framework documentation alignment docs/framework/*/guides/formatting-display.md	Lit, Preact, React, and Solid examples, explanations, badge output, and platform reference tables reflect the updated ordering.

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

Sequence Diagram(s)

sequenceDiagram
  participant formatForDisplay
  participant orderMacModifiers
  participant resolveModifier
  formatForDisplay->>orderMacModifiers: reorder normalized macOS hotkey
  orderMacModifiers->>resolveModifier: resolve Mod for macOS
  resolveModifier-->>orderMacModifiers: macOS modifier
  orderMacModifiers-->>formatForDisplay: ordered hotkey

Loading

Possibly related issues

• formatForDisplay orders macOS modifiers differently from Apple HIG #136 — Directly addresses the macOS modifier-ordering bug described by the issue.

Poem

A rabbit taps Shift, then Command with care,
Apple-style symbols float through the air.
Tests hop along, docs follow the trail,
Windows keeps its canonical tale.
Format the keys—hip-hop, hooray!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	The title clearly summarizes the main change: mac hotkeys now follow Apple's Human Interface Guidelines.
Description check	✅ Passed	The description includes the required Changes, Checklist, and Release Impact sections and is mostly complete.

✨ 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.}