@astryxdesign/core 0.1.4-canary.fd7ab46 → 0.1.4

package/src/hooks/useHotkeys.test.ts

@@ -1,245 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file useHotkeys.test.ts
- * @input Uses vitest, @testing-library/react, useHotkeys hook
- * @output Unit tests for useHotkeys hook
- * @position Testing; validates useHotkeys.ts implementation
- *
- * SYNC: When useHotkeys.ts changes, update tests to match new behavior
- */
-
-import {describe, it, expect, vi, afterEach} from 'vitest';
-import {renderHook} from '@testing-library/react';
-import {useHotkeys, type Hotkey} from './useHotkeys';
-
-function stubApplePlatform() {
-  // jsdom's navigator has no userAgentData; platform drives detection.
-  vi.stubGlobal('navigator', {platform: 'MacIntel'});
-}
-
-function stubOtherPlatform() {
-  vi.stubGlobal('navigator', {platform: 'Win32'});
-}
-
-function press(
-  key: string,
-  init: KeyboardEventInit & {target?: HTMLElement} = {},
-): KeyboardEvent {
-  const {target, ...eventInit} = init;
-  const event = new KeyboardEvent('keydown', {
-    key,
-    bubbles: true,
-    cancelable: true,
-    ...eventInit,
-  });
-  (target ?? window).dispatchEvent(event);
-  return event;
-}
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-  vi.restoreAllMocks();
-  document.body.innerHTML = '';
-});
-
-describe('useHotkeys', () => {
-  it('fires on mod+k via metaKey on Apple platforms', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
-
-    const event = press('k', {metaKey: true});
-    expect(onPress).toHaveBeenCalledTimes(1);
-    expect(onPress).toHaveBeenCalledWith(event);
-    expect(event.defaultPrevented).toBe(true);
-  });
-
-  it('maps mod to ctrlKey on non-Apple platforms', () => {
-    stubOtherPlatform();
-    const onPress = vi.fn();
-    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
-
-    press('k', {metaKey: true});
-    expect(onPress).not.toHaveBeenCalled();
-
-    press('k', {ctrlKey: true});
-    expect(onPress).toHaveBeenCalledTimes(1);
-  });
-
-  it('does not fire a bare key when modifiers are held', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    renderHook(() => useHotkeys([{keys: 'k', onPress}]));
-
-    press('k', {metaKey: true});
-    press('k', {ctrlKey: true});
-    press('k', {altKey: true});
-    expect(onPress).not.toHaveBeenCalled();
-
-    press('k');
-    expect(onPress).toHaveBeenCalledTimes(1);
-  });
-
-  it('matches named keys: escape, enter, space, arrows', () => {
-    stubApplePlatform();
-    const onEscape = vi.fn();
-    const onEnter = vi.fn();
-    const onSpace = vi.fn();
-    const onDown = vi.fn();
-    renderHook(() =>
-      useHotkeys([
-        {keys: 'escape', onPress: onEscape},
-        {keys: 'enter', onPress: onEnter},
-        {keys: 'space', onPress: onSpace},
-        {keys: 'down', onPress: onDown},
-      ]),
-    );
-
-    press('Escape');
-    press('Enter');
-    press(' ');
-    press('ArrowDown');
-    expect(onEscape).toHaveBeenCalledTimes(1);
-    expect(onEnter).toHaveBeenCalledTimes(1);
-    expect(onSpace).toHaveBeenCalledTimes(1);
-    expect(onDown).toHaveBeenCalledTimes(1);
-  });
-
-  it('requires shift when specified and ignores shift otherwise', () => {
-    stubApplePlatform();
-    const onSlash = vi.fn();
-    const onLetter = vi.fn();
-    renderHook(() =>
-      useHotkeys([
-        {keys: 'shift+/', onPress: onSlash},
-        {keys: 'c', onPress: onLetter},
-      ]),
-    );
-
-    press('/');
-    expect(onSlash).not.toHaveBeenCalled();
-    press('/', {shiftKey: true});
-    expect(onSlash).toHaveBeenCalledTimes(1);
-
-    // Shift not specified → matches regardless of shift state.
-    press('C', {shiftKey: true});
-    press('c');
-    expect(onLetter).toHaveBeenCalledTimes(2);
-  });
-
-  it('skips typing targets by default', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
-
-    const input = document.createElement('input');
-    document.body.appendChild(input);
-    press('k', {metaKey: true, target: input});
-    expect(onPress).not.toHaveBeenCalled();
-
-    const textarea = document.createElement('textarea');
-    document.body.appendChild(textarea);
-    press('k', {metaKey: true, target: textarea});
-    expect(onPress).not.toHaveBeenCalled();
-  });
-
-  it('fires in typing targets when allowInInputs is true', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    renderHook(() =>
-      useHotkeys([{keys: 'escape', onPress, allowInInputs: true}]),
-    );
-
-    const input = document.createElement('input');
-    document.body.appendChild(input);
-    press('Escape', {target: input});
-    expect(onPress).toHaveBeenCalledTimes(1);
-  });
-
-  it('respects isDisabled', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    const {rerender} = renderHook(
-      ({isDisabled}: {isDisabled: boolean}) =>
-        useHotkeys([{keys: 'mod+k', onPress, isDisabled}]),
-      {initialProps: {isDisabled: true}},
-    );
-
-    press('k', {metaKey: true});
-    expect(onPress).not.toHaveBeenCalled();
-
-    rerender({isDisabled: false});
-    press('k', {metaKey: true});
-    expect(onPress).toHaveBeenCalledTimes(1);
-  });
-
-  it('skips events that are already defaultPrevented', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
-
-    const event = new KeyboardEvent('keydown', {
-      key: 'k',
-      metaKey: true,
-      bubbles: true,
-      cancelable: true,
-    });
-    event.preventDefault();
-    window.dispatchEvent(event);
-    expect(onPress).not.toHaveBeenCalled();
-  });
-
-  it('unsubscribes on unmount', () => {
-    stubApplePlatform();
-    const onPress = vi.fn();
-    const removeSpy = vi.spyOn(window, 'removeEventListener');
-    const {unmount} = renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
-
-    unmount();
-    expect(removeSpy).toHaveBeenCalledWith('keydown', expect.any(Function));
-
-    press('k', {metaKey: true});
-    expect(onPress).not.toHaveBeenCalled();
-  });
-
-  it('does not re-subscribe on re-render, but uses latest handlers', () => {
-    stubApplePlatform();
-    const addSpy = vi.spyOn(window, 'addEventListener');
-    const first = vi.fn();
-    const second = vi.fn();
-
-    const {rerender} = renderHook(
-      ({hotkeys}: {hotkeys: Hotkey[]}) => useHotkeys(hotkeys),
-      {initialProps: {hotkeys: [{keys: 'mod+k', onPress: first}]}},
-    );
-
-    const keydownSubscriptions = () =>
-      addSpy.mock.calls.filter(([type]) => type === 'keydown').length;
-    const initialCount = keydownSubscriptions();
-
-    rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
-    rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
-    expect(keydownSubscriptions()).toBe(initialCount);
-
-    press('k', {metaKey: true});
-    expect(first).not.toHaveBeenCalled();
-    expect(second).toHaveBeenCalledTimes(1);
-  });
-
-  it('only fires the first matching hotkey per event', () => {
-    stubApplePlatform();
-    const first = vi.fn();
-    const second = vi.fn();
-    renderHook(() =>
-      useHotkeys([
-        {keys: 'mod+k', onPress: first},
-        {keys: 'mod+k', onPress: second},
-      ]),
-    );
-
-    press('k', {metaKey: true});
-    expect(first).toHaveBeenCalledTimes(1);
-    expect(second).not.toHaveBeenCalled();
-  });
-});

package/src/hooks/useHotkeys.ts

@@ -1,203 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-/**
- * @file useHotkeys.ts
- * @input Uses React useEffect, useRef
- * @output Exports useHotkeys hook and Hotkey interface for global keyboard shortcuts
- * @position Core hook; used by consumers for app-level keyboard shortcuts
- *
- * Registers a single window keydown listener per hook instance. Handlers
- * are kept in a ref so re-renders never re-subscribe (subscribe once on
- * mount, unsubscribe on unmount). SSR-safe — window is only touched
- * inside the effect.
- *
- * Skips events that are already handled (defaultPrevented) and events
- * targeting typing surfaces (input, textarea, select, contenteditable)
- * unless a hotkey opts in via `allowInInputs`.
- *
- * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
- * ctrlKey elsewhere — mirrors the detection used by Kbd.
- *
- * SYNC: When modified, update:
- * - /packages/core/src/hooks/index.ts
- * - /packages/core/src/hooks/useHotkeys.doc.mjs
- */
-
-import {useEffect, useRef} from 'react';
-
-/**
- * A single keyboard shortcut registration.
- */
-export interface Hotkey {
-  /**
-   * Key combo, e.g. 'mod+k', 'shift+/', 'c', 'escape'.
-   * 'mod' = ⌘ on macOS, Ctrl elsewhere.
-   *
-   * Format: '+'-separated modifiers (mod, ctrl, meta, shift, alt) followed
-   * by a final key compared case-insensitively against event.key.
-   * Named keys: 'escape', 'enter', 'space', 'up', 'down', 'left', 'right'
-   * (arrow names map to ArrowUp/ArrowDown/ArrowLeft/ArrowRight).
-   * Use 'plus' for a literal '+' key.
-   *
-   * Shift semantics: when 'shift' is not specified, shift state is ignored,
-   * so single letters match regardless of shift. When 'shift' is specified,
-   * shiftKey must be pressed and the final key is still compared against
-   * event.key — for punctuation that shift transforms (e.g. shift+/ produces
-   * '?' on US layouts), prefer registering the produced character instead.
-   */
-  keys: string;
-  /** Called when the combo matches. The event has preventDefault() applied. */
-  onPress: (event: KeyboardEvent) => void;
-  /**
-   * Fire even when focus is in an input/textarea/select/contenteditable.
-   * @default false
-   */
-  allowInInputs?: boolean;
-  /** Temporarily disable this hotkey without unregistering it. */
-  isDisabled?: boolean;
-}
-
-/** Aliases for the final key of a combo, normalized to event.key values. */
-const KEY_ALIASES: Record<string, string> = {
-  esc: 'escape',
-  space: ' ',
-  up: 'arrowup',
-  down: 'arrowdown',
-  left: 'arrowleft',
-  right: 'arrowright',
-  return: 'enter',
-  plus: '+',
-};
-
-/**
- * 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).
- * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
- */
-function isApplePlatform(): boolean {
-  if (typeof navigator === 'undefined') {
-    return false;
-  }
-  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 ?? '');
-  }
-  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
-}
-
-/**
- * Whether the event target is a typing surface where global shortcuts
- * should stay silent by default.
- */
-function isTypingTarget(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) {
-    return false;
-  }
-  if (target.isContentEditable) {
-    return true;
-  }
-  const tag = target.tagName;
-  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
-}
-
-/**
- * Whether a keydown event matches a '+'-separated combo string.
- */
-function matchesCombo(
-  keys: string,
-  event: KeyboardEvent,
-  isApple: boolean,
-): boolean {
-  const parts = keys
-    .toLowerCase()
-    .split('+')
-    .map(part => part.trim())
-    .filter(Boolean);
-  if (parts.length === 0) {
-    return false;
-  }
-
-  const key = parts[parts.length - 1];
-  const mods = new Set(parts.slice(0, -1));
-
-  const wantsMod = mods.has('mod');
-  const wantsCtrl = mods.has('ctrl') || (wantsMod && !isApple);
-  const wantsMeta = mods.has('meta') || (wantsMod && isApple);
-  const wantsAlt = mods.has('alt');
-  const wantsShift = mods.has('shift');
-
-  // Non-shift modifiers must match exactly so 'k' doesn't fire on 'mod+k'.
-  if (event.ctrlKey !== wantsCtrl) {
-    return false;
-  }
-  if (event.metaKey !== wantsMeta) {
-    return false;
-  }
-  if (event.altKey !== wantsAlt) {
-    return false;
-  }
-  // Shift is only enforced when specified — see Hotkey.keys docs.
-  if (wantsShift && !event.shiftKey) {
-    return false;
-  }
-
-  const expected = KEY_ALIASES[key] ?? key;
-  return event.key.toLowerCase() === expected;
-}
-
-/**
- * Registers global keyboard shortcuts on window.
- *
- * A single keydown listener is attached per hook instance; the hotkey
- * definitions live in a ref, so re-renders update behavior without
- * re-subscribing. First matching hotkey wins per event.
- *
- * @param hotkeys - Shortcut registrations to listen for.
- *
- * @example
- * ```
- * useHotkeys([
- *   { keys: 'mod+k', onPress: () => openCommandPalette() },
- *   { keys: 'escape', onPress: () => closePanel(), allowInInputs: true },
- *   { keys: 'c', onPress: () => compose(), isDisabled: isModalOpen },
- * ]);
- * ```
- */
-export function useHotkeys(hotkeys: Hotkey[]): void {
-  const hotkeysRef = useRef(hotkeys);
-
-  // Keep the latest definitions available to the stable listener.
-  useEffect(() => {
-    hotkeysRef.current = hotkeys;
-  });
-
-  useEffect(() => {
-    const isApple = isApplePlatform();
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.defaultPrevented) {
-        return;
-      }
-      const isTyping = isTypingTarget(event.target);
-      for (const hotkey of hotkeysRef.current) {
-        if (hotkey.isDisabled) {
-          continue;
-        }
-        if (isTyping && !hotkey.allowInInputs) {
-          continue;
-        }
-        if (matchesCombo(hotkey.keys, event, isApple)) {
-          event.preventDefault();
-          hotkey.onPress(event);
-          return;
-        }
-      }
-    };
-
-    window.addEventListener('keydown', handleKeyDown);
-    return () => window.removeEventListener('keydown', handleKeyDown);
-  }, []);
-}

package/src/utils/color.test.ts

@@ -1,133 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {parseHex, parseRgb, parseColor, formatHex, formatColor} from './color';
-
-describe('parseHex', () => {
-  it('parses #rrggbb', () => {
-    expect(parseHex('#0064E0')).toEqual({r: 0, g: 100, b: 224, a: 1});
-  });
-
-  it('parses without a leading #', () => {
-    expect(parseHex('0064E0')).toEqual({r: 0, g: 100, b: 224, a: 1});
-  });
-
-  it('expands #rgb shorthand', () => {
-    expect(parseHex('#abc')).toEqual({r: 0xaa, g: 0xbb, b: 0xcc, a: 1});
-  });
-
-  it('parses #rrggbbaa alpha', () => {
-    expect(parseHex('#00000080')).toEqual({r: 0, g: 0, b: 0, a: 128 / 255});
-  });
-
-  it('expands #rgba shorthand alpha', () => {
-    expect(parseHex('#f008')).toEqual({
-      r: 0xff,
-      g: 0,
-      b: 0,
-      a: 0x88 / 255,
-    });
-  });
-
-  it('returns null for non-hex input', () => {
-    expect(parseHex('rgb(0,0,0)')).toBeNull();
-    expect(parseHex('#12')).toBeNull();
-    expect(parseHex('#zzzzzz')).toBeNull();
-    // @ts-expect-error runtime guard for non-string input
-    expect(parseHex(null)).toBeNull();
-  });
-});
-
-describe('parseRgb', () => {
-  it('parses comma-separated rgb()', () => {
-    expect(parseRgb('rgb(0, 100, 224)')).toEqual({
-      r: 0,
-      g: 100,
-      b: 224,
-      a: 1,
-    });
-  });
-
-  it('parses rgba() with alpha', () => {
-    expect(parseRgb('rgba(0, 0, 0, 0.5)')).toEqual({r: 0, g: 0, b: 0, a: 0.5});
-  });
-
-  it('parses space-separated with slash alpha', () => {
-    expect(parseRgb('rgb(0 100 224 / 0.25)')).toEqual({
-      r: 0,
-      g: 100,
-      b: 224,
-      a: 0.25,
-    });
-  });
-
-  it('parses percentage channels', () => {
-    expect(parseRgb('rgb(100%, 0%, 0%)')).toEqual({
-      r: 255,
-      g: 0,
-      b: 0,
-      a: 1,
-    });
-  });
-
-  it('clamps alpha and channels into range', () => {
-    expect(parseRgb('rgba(300, -20, 10, 2)')).toEqual({
-      r: 255,
-      g: 0,
-      b: 10,
-      a: 1,
-    });
-  });
-
-  it('returns null when it cannot parse', () => {
-    expect(parseRgb('rgb(0, 0)')).toBeNull();
-    expect(parseRgb('#000000')).toBeNull();
-  });
-});
-
-describe('parseColor', () => {
-  it('routes hex and rgb strings to the right parser', () => {
-    expect(parseColor('#FFFFFF')).toEqual({r: 255, g: 255, b: 255, a: 1});
-    expect(parseColor('rgb(1, 2, 3)')).toEqual({r: 1, g: 2, b: 3, a: 1});
-  });
-
-  it('resolves the named colors used in token expressions', () => {
-    expect(parseColor('transparent')).toEqual({r: 0, g: 0, b: 0, a: 0});
-    expect(parseColor('BLACK')).toEqual({r: 0, g: 0, b: 0, a: 1});
-    expect(parseColor('white')).toEqual({r: 255, g: 255, b: 255, a: 1});
-  });
-
-  it('returns null for unsupported colors so callers can preserve them', () => {
-    expect(parseColor('var(--color-accent)')).toBeNull();
-    expect(parseColor('oklch(0.5 0.1 200)')).toBeNull();
-    expect(parseColor('rebeccapurple')).toBeNull();
-  });
-});
-
-describe('formatHex', () => {
-  it('formats channels as uppercase #RRGGBB', () => {
-    expect(formatHex(0, 100, 224)).toBe('#0064E0');
-  });
-
-  it('rounds and clamps out-of-range channels', () => {
-    expect(formatHex(-5, 300, 127.6)).toBe('#00FF80');
-  });
-});
-
-describe('formatColor', () => {
-  it('formats opaque colors as hex', () => {
-    expect(formatColor({r: 0, g: 100, b: 224, a: 1})).toBe('#0064E0');
-  });
-
-  it('formats translucent colors as rgba()', () => {
-    expect(formatColor({r: 0, g: 100, b: 224, a: 0.2})).toBe(
-      'rgba(0, 100, 224, 0.2)',
-    );
-  });
-
-  it('round-trips through parseColor', () => {
-    const parsed = parseColor('rgba(10, 20, 30, 0.5)');
-    expect(parsed).not.toBeNull();
-    expect(formatColor(parsed!)).toBe('rgba(10, 20, 30, 0.5)');
-  });
-});