Skip to main content
Reference status

This page predates the current package split. Use the current package guides for checked installation, public imports, and onboarding examples. The detailed examples below have not all been revalidated.

@barocss/shared

Shared utilities and constants used across Barocss Editor packages.

Purpose​

Provides common utilities that are used by multiple packages:

  • Platform detection (macOS, Linux, Windows)
  • Key string normalization and expansion
  • i18n utilities (placeholder replacement, locale normalization)

Key Exports​

  • IS_MAC, IS_LINUX, IS_WINDOWS - Platform detection constants
  • getKeyString() - Convert keyboard event to key string
  • normalizeKeyString() - Normalize key string format
  • expandModKey() - Expand Mod to platform-specific modifier
  • replacePlaceholders() - Replace placeholders in strings
  • normalizeLocale() - Normalize locale strings

Platform Detection​

Detect the operating system:

import { IS_MAC, IS_LINUX, IS_WINDOWS } from '@barocss/shared';

if (IS_MAC) {
  // macOS specific code
  const modifier = 'Cmd';
} else if (IS_WINDOWS) {
  // Windows specific code
  const modifier = 'Ctrl';
} else if (IS_LINUX) {
  // Linux specific code
  const modifier = 'Ctrl';
}

Key String Normalization​

Convert keyboard events to normalized key strings:

import { getKeyString } from '@barocss/shared';

element.addEventListener('keydown', (event) => {
  const key = getKeyString(event);
  // Examples: 'Mod+b', 'Alt+ArrowLeft', 'Shift+Enter', 'Escape'
  
  if (key === 'Mod+b') {
    // Toggle bold
  }
});

Key string format:

  • Modifiers: Ctrl, Cmd, Alt, Shift
  • Keys: A-Z, 0-9, Enter, Escape, Backspace, Delete, Tab, ArrowLeft, etc.
  • Format: Modifier+Key (e.g., Mod+b, Alt+ArrowLeft)

Key Binding Utilities​

Normalize and expand key strings:

import { normalizeKeyString, expandModKey, IS_MAC } from '@barocss/shared';

// Normalize key string (case-insensitive, sort modifiers)
const normalized = normalizeKeyString('ctrl+shift+b');
// Result: 'Ctrl+Shift+b'

// Expand Mod key to platform-specific modifier
const expanded = expandModKey('Mod+b', IS_MAC);
// macOS: 'Cmd+b'
// Windows/Linux: 'Ctrl+b'

i18n Utilities​

Internationalization utilities:

import { replacePlaceholders, normalizeLocale } from '@barocss/shared';

// Replace placeholders in strings
const message = replacePlaceholders('Hello {name}!', { name: 'World' });
// Result: 'Hello World!'

// Normalize locale string
const locale = normalizeLocale('en-US');
// Result: 'en-US'

Usage in Editor​

The shared package is used throughout the editor:

  • Editor Core: Keybinding system uses key normalization
  • Extensions: Platform detection for OS-specific shortcuts
  • Editor View DOM: Key event handling uses key string conversion
  • i18n: Placeholder replacement for localized messages

When to Use​

  • Platform-Specific Code: Detect OS for conditional logic
  • Key Event Handling: Normalize keyboard events
  • Keybinding Registration: Normalize key strings for keybindings
  • i18n Support: Replace placeholders in localized strings
  • Editor Core - Uses key normalization for keybindings
  • Extensions - Uses platform detection for shortcuts