Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): read a blank client-hints platform as unknown, not as non-Apple (#5325)

AstroHanb7fc8b1b4b12
diff --git a/.changeset/kbd-hotkeys-blank-client-hints-platform.md b/.changeset/kbd-hotkeys-blank-client-hints-platform.md
new file mode 100644
index 0000000000..d7052a7dd7
--- /dev/null
+++ b/.changeset/kbd-hotkeys-blank-client-hints-platform.md
@@ -0,0 +1,16 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `mod` hotkeys and `Kbd` resolve to Cmd on macOS again when client hints report a blank platform
+
+`useHotkeys` and `Kbd` both prefer `navigator.userAgentData.platform` and fall
+back to `navigator.platform`, but guarded the preference with
+`'platform' in uaData`, which is true whenever the key exists at all. A build
+reporting `platform: ''` therefore committed to the client-hints branch and got
+`false` without ever reaching the fallback, so on macOS every `mod` combo
+listened for Ctrl and every `<Kbd>` drew Ctrl. Electron and other embedders
+that rewrite the app's user-agent identity ship exactly that. A blank platform
+is now treated as unknown and falls through.
+
+@Astro-Han
diff --git a/packages/core/src/Kbd/Kbd.test.tsx b/packages/core/src/Kbd/Kbd.test.tsx
index 65fc7e0725..c371a35930 100644
--- a/packages/core/src/Kbd/Kbd.test.tsx
+++ b/packages/core/src/Kbd/Kbd.test.tsx
@@ -23,6 +23,7 @@ describe('Kbd', () => {
value: originalPlatform,
configurable: true,
});
+ delete (navigator as {userAgentData?: unknown}).userAgentData;
});
it('renders a single key', () => {
@@ -54,6 +55,22 @@ describe('Kbd', () => {
expect(screen.getByText('\u2318')).toBeInTheDocument(); // \u2318
});
+ it('reads a blank userAgentData.platform as unknown, not as non-Mac', () => {
+ // Builds that rewrite their client-hints identity expose the key with an
+ // empty value; navigator.platform is the only surface left that answers.
+ Object.defineProperty(navigator, 'userAgentData', {
+ value: {platform: ''},
+ configurable: true,
+ });
+ Object.defineProperty(navigator, 'platform', {
+ value: 'MacIntel',
+ configurable: true,
+ });
+
+ render(<Kbd keys="mod" />);
+ expect(screen.getByText('\u2318')).toBeInTheDocument();
+ });
+
it('maps modifier keys to symbols', () => {
render(<Kbd keys="ctrl+alt+shift+k" />);
expect(screen.getByText('\u2303')).toBeInTheDocument(); // \u2303
diff --git a/packages/core/src/Kbd/Kbd.tsx b/packages/core/src/Kbd/Kbd.tsx
index 8bdf887521..c5b576e82a 100644
--- a/packages/core/src/Kbd/Kbd.tsx
+++ b/packages/core/src/Kbd/Kbd.tsx
@@ -124,8 +124,9 @@ function getServerPlatformSnapshot(): boolean {
/**
* Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
*/
function detectMac(): boolean {
if (typeof navigator === 'undefined') {
@@ -134,7 +135,13 @@ function detectMac(): boolean {
// Prefer User-Agent Client Hints API (not deprecated)
const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
- return /mac/i.test((uaData as {platform: string}).platform ?? '');
+ const uaPlatform = (uaData as {platform?: unknown}).platform;
+ // A blank platform is no answer, not a negative one. Builds that rewrite
+ // their client-hints identity ship '', so fall through rather than
+ // reading it as "not Apple".
+ if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+ return /mac/i.test(uaPlatform);
+ }
}
// Fallback: navigator.platform (deprecated but still shipped everywhere)
return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
diff --git a/packages/core/src/hooks/useHotkeys.test.ts b/packages/core/src/hooks/useHotkeys.test.ts
index 8bff8087ec..19e2cf774a 100644
--- a/packages/core/src/hooks/useHotkeys.test.ts
+++ b/packages/core/src/hooks/useHotkeys.test.ts
@@ -67,6 +67,24 @@ describe('useHotkeys', () => {
expect(onPress).toHaveBeenCalledTimes(1);
});
+ it('reads a blank userAgentData.platform as unknown, not as non-Apple', () => {
+ // Builds that rewrite their client-hints identity expose the key with an
+ // empty value; navigator.platform is the only surface left that answers.
+ vi.stubGlobal('navigator', {
+ userAgentData: {platform: ''},
+ platform: 'MacIntel',
+ });
+ const onPress = vi.fn();
+ renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+ press('k', {ctrlKey: true});
+ expect(onPress).not.toHaveBeenCalled();
+
+ const event = press('k', {metaKey: true});
+ expect(onPress).toHaveBeenCalledTimes(1);
+ expect(onPress).toHaveBeenCalledWith(event);
+ });
+
it('does not fire a bare key when modifiers are held', () => {
stubApplePlatform();
const onPress = vi.fn();
diff --git a/packages/core/src/hooks/useHotkeys.ts b/packages/core/src/hooks/useHotkeys.ts
index a537f63495..a8a9f1b60a 100644
--- a/packages/core/src/hooks/useHotkeys.ts
+++ b/packages/core/src/hooks/useHotkeys.ts
@@ -73,8 +73,9 @@ const KEY_ALIASES: Record<string, string> = {
/**
* Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
* Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
*/
function isApplePlatform(): boolean {
@@ -83,7 +84,13 @@ function isApplePlatform(): boolean {
}
const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
- return /mac/i.test((uaData as {platform: string}).platform ?? '');
+ const uaPlatform = (uaData as {platform?: unknown}).platform;
+ // A blank platform is no answer, not a negative one. Builds that rewrite
+ // their client-hints identity ship '', so fall through rather than
+ // reading it as "not Apple".
+ if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+ return /mac/i.test(uaPlatform);
+ }
}
return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
}