fix: order macOS shortcut modifiers for display

[KevinVandy]

🎯 Changes

Fixes #136. Format macOS modifier labels in Control, Option, Shift, Command order, so Mod+Shift+S displays as ⇧ ⌘ S. Keep normalized registration strings unchanged and cover physical bindings, keycap parts, literal plus keys, text labels, and other platforms.

This follows the display-only approach discussed in the closed, unmerged #139, updated for the current formatter API. Updated guides, generated reference documentation, and added a core patch changeset.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
• I fully understand the code in this pull request, including any code generated with AI assistance.

Validation: focused formatter/parser/recording tests (124 passed), core TypeScript and ESLint checks, pnpm test, and pnpm run test:pr, using Node 24.15.0.

🚀 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
  • On macOS, displayed keyboard shortcuts now place Shift before Command (for example, Mod+Shift+S appears as ⇧ ⌘ S). Shortcut registration remains unchanged.
• Documentation
  • Updated shortcut-formatting guides across supported frameworks with the macOS modifier order and example.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: TanStack/hotkeys/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 6c1f277f-06f0-4148-ae22-2b44b46fee5b

📥 Commits

Reviewing files that changed from the base of the PR and between e06d82d and 10a9ec5.

⛔ Files ignored due to path filters (3)

• docs/reference/functions/formatForDisplay.md is excluded by !docs/**/reference/**
• docs/reference/functions/formatWithLabels.md is excluded by !docs/**/reference/**
• docs/reference/interfaces/FormatDisplayOptions.md is excluded by !docs/**/reference/**

📒 Files selected for processing (10)

• .changeset/heavy-spiders-learn.md
• docs/framework/angular/guides/formatting-display.md
• docs/framework/lit/guides/formatting-display.md
• docs/framework/preact/guides/formatting-display.md
• docs/framework/react/guides/formatting-display.md
• docs/framework/solid/guides/formatting-display.md
• docs/framework/svelte/guides/formatting-display.md
• docs/framework/vue/guides/formatting-display.md
• packages/hotkeys/src/format.ts
• packages/hotkeys/tests/format.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

formatForDisplay now sorts macOS shortcut modifiers in Control, Option, Shift, Command order. Normalized hotkey bindings remain unchanged. Tests and framework guides reflect the display order.

Changes

macOS Display Order

Layer / File(s)	Summary
Formatter behavior and guidance packages/hotkeys/src/format.ts, docs/framework/*/guides/formatting-display.md, .changeset/heavy-spiders-learn.md	The formatter sorts macOS display modifiers in Control, Option, Shift, Command order, treating Mod as Meta for sorting. Framework guides and the changeset document the display order and unchanged normalization.
Display-order tests packages/hotkeys/tests/format.test.ts	Tests cover modifier ordering across aliases, binding forms, labels, and separators. They check that normalization remains unchanged and that Windows and Linux output remains Ctrl-first.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 10a9e

The macOS display-order change appears mergeable after normal checks; no actionable merge-blocking risk is identified.

Architecture Summary

Architecture risk: 🔵 Low · up to 10a9e

The change affects 2 systems.

Changed systems: packages/hotkeys, docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — packages/hotkeys (library) was modified; 2 changed files map to changed impact.
• observed — docs (service) was modified; 7 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in docs/framework/angular/guides/formatting-display.md: The macOS display guidance adds the modifier order and the Mod+Shift+S display example, and states that normalization remains Mod+Shift+S.
• observed — Modified behavior in docs/framework/lit/guides/formatting-display.md: The platform-detection guidance now adds macOS modifier ordering and the Mod+Shift+S display example, while clarifying that formatting does not alter the normalized binding.
• observed — Modified behavior in docs/framework/preact/guides/formatting-display.md: The guide adds macOS modifier ordering and an example showing Mod+Shift+S displayed as ⇧ ⌘ S, while retaining Mod+Shift+S as the normalized binding.
• observed — Modified behavior in docs/framework/react/guides/formatting-display.md: The macOS display guidance now documents modifier ordering as Control, Option, Shift, Command, gives Mod+Shift+S as a symbol-formatted example, and distinguishes that display label from the unchanged normalized binding.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (8 skipped: 8 …	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 and concisely describes the main change: ordering macOS shortcut modifiers for display.
Description check	✅ Passed	The description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, scope, testing, and changeset status, with all applicable checklist items completed.
Linked Issues check	✅ Passed	PR #159 addresses the coding requirement in issue #136. packages/hotkeys/src/format.ts sorts macOS display modifiers as Control, Option, Shift, Command and resolves Mod as Meta for sorting. The …
Out of Scope Changes check	✅ Passed	The changes stay within issue #136. The source change implements macOS display ordering without changing normalization. The tests verify the formatter behavior. The guide updates and patch changeset d…

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (8 skipped: 8 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

_{A rabbit taps a shortcut key,
Shift then Command, neat as can be.
The bindings keep their normal place,
While symbols line up with care and grace.
Tests hop through each format case,
Then nibble greens at a steady pace.}

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

[pkg-pr-new]

Open in StackBlitz

@tanstack/angular-hotkeys

npm i https://pkg.pr.new/@tanstack/angular-hotkeys@159

@tanstack/hotkeys

npm i https://pkg.pr.new/@tanstack/hotkeys@159

@tanstack/hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/hotkeys-devtools@159

@tanstack/lit-hotkeys

npm i https://pkg.pr.new/@tanstack/lit-hotkeys@159

@tanstack/preact-hotkeys

npm i https://pkg.pr.new/@tanstack/preact-hotkeys@159

@tanstack/preact-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/preact-hotkeys-devtools@159

@tanstack/react-hotkeys

npm i https://pkg.pr.new/@tanstack/react-hotkeys@159

@tanstack/react-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/react-hotkeys-devtools@159

@tanstack/solid-hotkeys

npm i https://pkg.pr.new/@tanstack/solid-hotkeys@159

@tanstack/solid-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/solid-hotkeys-devtools@159

@tanstack/svelte-hotkeys

npm i https://pkg.pr.new/@tanstack/svelte-hotkeys@159

@tanstack/vue-hotkeys

npm i https://pkg.pr.new/@tanstack/vue-hotkeys@159

@tanstack/vue-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/vue-hotkeys-devtools@159

commit: 10a9ec5

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 12 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/hotkeys	0.10.0 → 0.10.1	Changeset
@tanstack/angular-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/hotkeys-devtools	1.1.0 → 1.1.1	Dependent
@tanstack/lit-hotkeys	0.13.0 → 0.13.1	Dependent
@tanstack/preact-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/preact-hotkeys-devtools	0.9.0 → 0.9.1	Dependent
@tanstack/react-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/react-hotkeys-devtools	0.9.0 → 0.9.1	Dependent
@tanstack/solid-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/solid-hotkeys-devtools	0.9.0 → 0.9.1	Dependent
@tanstack/svelte-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/vue-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/vue-hotkeys-devtools	0.9.0 → 0.9.1	Dependent