Skip to content

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

TypeScript
7.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file Kbd.tsx
 * @input Uses React, StyleX, theme tokens, shortcut key names, aliases, provider-bound translator
 * @output Exports Kbd component and KbdProps with localized shortcut text
 * @position Core implementation; renders styled keyboard shortcut indicators
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Kbd/index.ts
 * - /packages/cli/assets/templates/blocks/components/Kbd/ (showcase blocks)
 */

import React, {useSyncExternalStore} from 'react';
import * as stylex from '@stylexjs/stylex';
import {mergeProps} from '../utils';
import {isApplePlatform} from '../utils/isApplePlatform';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import type {TranslatorFn} from '../i18n';
import {
  colorVars,
  spacingVars,
  radiusVars,
  typographyVars,
  fontWeightVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Kbd/Kbd.generated';

registerEnglishFallback(english);

const styles = stylex.create({
  wrapper: {
    display: 'inline-flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    flexShrink: 0,
  },
  kbd: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    minWidth: spacingVars['--spacing-5'],
    height: spacingVars['--spacing-5'],
    // The theme height holds while one line of text fits. A taller line
    // grows the badge.
    minHeight: '1lh',
    paddingInline: spacingVars['--spacing-1'],
    borderRadius: radiusVars['--radius-inner'],
    backgroundColor: colorVars['--color-neutral'],
    borderBottomWidth: '2px',
    borderBottomStyle: 'solid',
    borderBottomColor: colorVars['--color-border-emphasized'],
    color: colorVars['--color-text-primary'],
    fontFamily: typographyVars['--font-family-body'],
    fontSize: typeScaleVars['--text-supporting-size'],
    fontWeight: fontWeightVars['--font-weight-medium'],
    lineHeight: typeScaleVars['--text-supporting-leading'],
    userSelect: 'none',
  },
});

/** Symbols that every platform shows. Modifier text depends on the platform. */
const KEY_DISPLAY = new Map<string, string>([
  ['enter', '\u21B5'], // ↵
  ['backspace', '\u232B'], // ⌫
  ['tab', '\u21E5'], // ⇥
  ['up', '\u2191'],
  ['down', '\u2193'],
  ['left', '\u2190'],
  ['right', '\u2192'],
  ['plus', '+'],
]);

const APPLE_MODIFIER_DISPLAY = new Map<string, string>([
  ['mod', '\u2318'], // ⌘
  ['meta', '\u2318'], // ⌘ — the Command key
  ['ctrl', '\u2303'], // ⌃
  ['alt', '\u2325'], // ⌥
  ['shift', '\u21E7'], // ⇧
]);

/** Catalog keys for the modifiers' short text elsewhere and before hydration. */
const MODIFIER_SHORT_TEXT = new Map<string, string>([
  ['mod', '@astryx.kbd.key.controlShort'],
  ['ctrl', '@astryx.kbd.key.controlShort'],
  ['alt', '@astryx.kbd.key.altShort'],
  ['shift', '@astryx.kbd.key.shiftShort'],
  ['meta', '@astryx.kbd.key.windowsShort'],
]);

const KBD_KEY_ALIASES = new Map<string, string>([
  ['esc', 'escape'],
  ['return', 'enter'],
]);

/** The server render has no platform, so it uses the non-Apple text. */
function getKeyDisplay(key: string, isMac: boolean, t: TranslatorFn): string {
  const appleSymbol = isMac ? APPLE_MODIFIER_DISPLAY.get(key) : undefined;
  if (appleSymbol != null) {
    return appleSymbol;
  }
  const shortText = isMac ? undefined : MODIFIER_SHORT_TEXT.get(key);
  if (shortText != null) {
    return t(shortText);
  }
  if (key === 'escape') {
    return t('@astryx.kbd.key.escapeShort');
  }
  return KEY_DISPLAY.get(key) ?? key.toUpperCase();
}

/**
 * Spoken-word labels for screen readers. The visual `KEY_DISPLAY` uses glyphs
 * (⌘, ⇧, ↵, …) that assistive tech cannot announce meaningfully, so the
 * accessible name for the shortcut is built from these words instead.
 */
const KEY_LABEL = new Map<string, string>([
  ['ctrl', '@astryx.kbd.key.control'],
  ['alt', '@astryx.kbd.key.alt'],
  ['shift', '@astryx.kbd.key.shift'],
  ['enter', '@astryx.kbd.key.enter'],
  ['backspace', '@astryx.kbd.key.backspace'],
  ['escape', '@astryx.kbd.key.escape'],
  ['tab', '@astryx.kbd.key.tab'],
  ['up', '@astryx.kbd.key.up'],
  ['down', '@astryx.kbd.key.down'],
  ['left', '@astryx.kbd.key.left'],
  ['right', '@astryx.kbd.key.right'],
  ['plus', '@astryx.kbd.key.plus'],
]);

function getKeyLabel(key: string, isMac: boolean, t: TranslatorFn): string {
  if (key === 'mod') {
    return t(isMac ? '@astryx.kbd.key.command' : '@astryx.kbd.key.control');
  }
  const labelKey = KEY_LABEL.get(key);
  return labelKey ? t(labelKey) : key.toUpperCase();
}

function subscribeToPlatformChanges(): () => void {
  return () => {};
}

function getServerPlatformSnapshot(): boolean {
  return false;
}

export interface KbdProps extends BaseProps<HTMLSpanElement> {
  ref?: React.Ref<HTMLSpanElement>;
  /**
   * Keyboard shortcut string. Use "+" to separate keys.
   * Special keys: mod, ctrl, alt and shift (Apple symbols on Apple platforms,
   * short text such as "Ctrl" elsewhere and before hydration), meta (⌘ on
   * Apple platforms, "Win" text elsewhere and before hydration), enter, backspace, escape, tab, up, down, left, and right.
   * Aliases: "esc" for "escape" and "return" for "enter".
   * Use "plus" to render a literal "+" key (e.g. "shift+plus").
   *
   * @example
   * ```
   * "mod+k"
   * "mod+shift+p"
   * "shift+plus"
   * "enter"
   * ```
   */
  keys: string;
}

/**
 * Displays a keyboard shortcut as styled <kbd> elements.
 *
 * A general-purpose component for rendering keyboard shortcuts
 * anywhere in the system — tooltips, menus, documentation, etc.
 *
 * Platform-aware: `mod` renders as ⌘ on macOS and Ctrl elsewhere.
 * SSR-safe — defers platform detection through useSyncExternalStore to avoid
 * hydration mismatches.
 *
 * @example
 * ```
 * <Kbd keys="mod+k" />
 * ```
 */
export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
  const t = useComponentTranslator();
  const isMac = useSyncExternalStore(
    subscribeToPlatformChanges,
    isApplePlatform,
    getServerPlatformSnapshot,
  );

  const keyOccurrences = new Map<string, number>();
  const parts = keys
    .split('+')
    .map(key => key.trim().toLowerCase())
    .map(sourceKey => {
      const occurrence = keyOccurrences.get(sourceKey) ?? 0;
      keyOccurrences.set(sourceKey, occurrence + 1);
      return {
        key: KBD_KEY_ALIASES.get(sourceKey) ?? sourceKey,
        reactKey: `${sourceKey}:${occurrence}`,
      };
    });

  // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
  // the visual glyphs below are announced meaninglessly by assistive tech.
  const accessibleName = parts
    .map(({key}) => getKeyLabel(key, isMac, t))
    .reduce(
      (shortcut, key, index) =>
        index === 0 ? key : t('@astryx.kbd.shortcut', {shortcut, key}),
      '',
    );

  return (
    <span
      {...rest}
      ref={ref}
      role="img"
      aria-label={accessibleName}
      {...mergeProps(
        themeProps('kbd'),
        stylex.props(styles.wrapper, xstyle),
        className,
        style,
      )}>
      {parts.map(({key, reactKey}) => (
        <kbd key={reactKey} aria-hidden="true" {...stylex.props(styles.kbd)}>
          {getKeyDisplay(key, isMac, t)}
        </kbd>
      ))}
    </span>
  );
}

Kbd.displayName = 'Kbd';