JavaScript Utilities optional

Platform detection and keyboard shortcut utilities for building consistent cross-platform experiences.

Reusable Helpers

These utilities are used internally by Focus UI components and are also exported for use in your own code. They provide consistent platform detection and keyboard shortcut handling across Mac, Windows, and Linux.

Platform Detection

isMac()

Check if the current platform is macOS. Useful for displaying platform-specific shortcuts or UI.

JavaScript

import { isMac } from 'focus-ui'

if (isMac()) {
  console.log('Running on macOS')
} else {
  console.log('Running on Windows/Linux')
}

Returns	Description
`boolean`	`true` if running on macOS, `false` otherwise

Keyboard Shortcuts

getShortcutText(key, modifier)

Get a formatted keyboard shortcut string for display. Automatically uses the correct symbols for the current platform.

JavaScript

import { getShortcutText } from 'focus-ui'

// Default: cmd modifier (Cmd on Mac, Ctrl on Windows)
getShortcutText('k')           // '⌘K' on Mac, 'Ctrl+K' on Windows

// With different modifiers
getShortcutText('s', 'cmd')    // '⌘S' on Mac, 'Ctrl+S' on Windows
getShortcutText('z', 'alt')    // '⌥Z' on Mac, 'Alt+Z' on Windows
getShortcutText('a', 'shift')  // '⇧A' on Mac, 'Shift+A' on Windows
getShortcutText('/', 'none')   // '/' (no modifier)

Parameter	Type	Default	Description
`key`	`string`	-	The key to display (e.g., 'k', 's', '/')
`modifier`	`string`	`'cmd'`	Modifier key: `'cmd'`, `'alt'`, `'shift'`, or `'none'`

Platform-Specific Output

Modifier	macOS	Windows/Linux
`'cmd'`	⌘ (Command)	Ctrl+
`'alt'`	⌥ (Option)	Alt+
`'shift'`	⇧ (Shift)	Shift+
`'none'`	(key only)	(key only)

matchesShortcut(event, key, modifier)

Check if a keyboard event matches a specific shortcut. Handles cross-platform differences automatically.

JavaScript

import { matchesShortcut } from 'focus-ui'

document.addEventListener('keydown', (e) => {
  // Matches Cmd+K on Mac, Ctrl+K on Windows
  if (matchesShortcut(e, 'k', 'cmd')) {
    e.preventDefault()
    openSearch()
  }

  // Matches Alt+S on all platforms
  if (matchesShortcut(e, 's', 'alt')) {
    e.preventDefault()
    saveDocument()
  }

  // Matches just '/' with no modifier (like GitHub search)
  if (matchesShortcut(e, '/', 'none')) {
    e.preventDefault()
    focusSearchInput()
  }
})

Parameter	Type	Default	Description
`event`	`KeyboardEvent`	-	The keyboard event to check
`key`	`string`	-	The key to match (e.g., 'k', 's', '/')
`modifier`	`string`	`'cmd'`	Modifier key: `'cmd'`, `'alt'`, `'shift'`, or `'none'`

Note on 'cmd' Modifier

The 'cmd' modifier matches both metaKey (Cmd on Mac) and ctrlKey (Ctrl on Windows/Linux). This ensures your shortcuts work consistently across all platforms with the standard modifier key for each OS.

Prefer Component APIs

For common use cases like search shortcuts, use the component APIs instead of manual event handling. For example, Searchbar.init() handles keyboard shortcuts automatically. Use these utilities when building custom components or behaviors not covered by existing APIs.

Common Patterns

Search Shortcut Badge

Display a platform-appropriate shortcut hint in your UI.

JavaScript

import { getShortcutText } from 'focus-ui'

const searchButton = document.querySelector('.search-toggle')
const badge = document.createElement('span')
badge.className = 'shortcut-badge'
badge.textContent = getShortcutText('k')  // '⌘K' or 'Ctrl+K'
searchButton.appendChild(badge)

Global Keyboard Handler

Set up multiple keyboard shortcuts in one handler.

JavaScript

import { matchesShortcut } from 'focus-ui'

document.addEventListener('keydown', (e) => {
  // Don't trigger shortcuts when typing in inputs
  if (e.target.matches('input, textarea, [contenteditable]')) return

  if (matchesShortcut(e, 'k', 'cmd')) {
    e.preventDefault()
    toggleSearch()
  } else if (matchesShortcut(e, '/', 'none')) {
    e.preventDefault()
    focusSearch()
  } else if (matchesShortcut(e, 'b', 'cmd')) {
    e.preventDefault()
    toggleSidebar()
  }
})

API Reference

Function	Parameters	Returns	Description
`isMac()`	-	`boolean`	Check if platform is macOS
`getShortcutText(key, mod)`	`string, string`	`string`	Format shortcut for display
`matchesShortcut(e, key, mod)`	`KeyboardEvent, string, string`	`boolean`	Check if event matches shortcut