@astryxdesign/core 0.1.2 → 0.1.3

package/dist/hooks/useListFocus.js

@@ -4,14 +4,23 @@
 
 /**
  * @file useListFocus.ts
- * @input Uses React useCallback, useRef
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
  * @output Exports useListFocus hook for linear list keyboard navigation
- * @position Core hook; used by TabMenu for dropdown menu navigation, Toolbar for roving tabindex
+ * @position Core hook; used by TabMenu for dropdown menu navigation, Toolbar
+ *   for roving tabindex, ButtonGroup, ContextMenu, NavHeadingMenu, and more.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
 import { useCallback, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+
+/**
+ * Navigation orientation for a linear list.
+ * - `'horizontal'`: ArrowLeft/ArrowRight move between items.
+ * - `'vertical'`: ArrowUp/ArrowDown move between items.
+ * - `'both'`: all four arrows move between items (in linear DOM order).
+ */
 
 /**
  * Configuration for list focus behavior
@@ -21,6 +30,91 @@ import { useCallback, useRef } from 'react';
  * Return type for useListFocus hook
  */
 
+// Text-editing inputs whose caret must not be hijacked by arrow navigation.
+const TEXT_INPUT_TYPES = new Set(['text', 'search', 'url', 'tel', 'email', 'password', 'number']);
+
+/**
+ * The nearest `contenteditable` root for `el`, or null when `el` is not inside
+ * an editable region. Prefers the browser's `isContentEditable` property and
+ * falls back to the closest `[contenteditable]` ancestor whose value is not
+ * `"false"` (so environments without `isContentEditable` still work).
+ */
+function getContentEditableRoot(el) {
+  if (el.isContentEditable) {
+    return el;
+  }
+  const candidate = el.closest('[contenteditable]');
+  if (candidate && candidate.getAttribute('contenteditable') !== 'false') {
+    return candidate;
+  }
+  return null;
+}
+
+/**
+ * Whether an arrow/Home/End key should be left to the browser because the
+ * event target is a text-editing element whose caret is not yet at the boundary
+ * in the direction of travel (or a selection is present). Returns true when the
+ * list should NOT steal the key.
+ *
+ * Covers three editing surfaces:
+ * - `<textarea>` and text-type `<input>` — use `selectionStart`/`selectionEnd`
+ *   to steal only at the boundary in the travel direction.
+ * - `contenteditable` (rich-text editor / chat composer) — precise caret
+ *   boundary detection in an arbitrary editable subtree is fragile, so we err
+ *   on the side of never hijacking an active editor: defer on every caret key
+ *   whenever focus is inside a non-empty contenteditable. (An empty editable
+ *   has nothing to caret through, so navigation may proceed.)
+ */
+function shouldDeferToCaret(target, key) {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+
+  // contenteditable (covers an element with contenteditable="" / "true" and
+  // descendants that inherit it). `isContentEditable` is the reliable property
+  // in the browser; fall back to the nearest `contenteditable` ancestor for
+  // environments (e.g. jsdom) that don't implement the property.
+  const editableRoot = getContentEditableRoot(target);
+  if (editableRoot) {
+    const selection = typeof window !== 'undefined' ? window.getSelection() : null;
+    // A non-collapsed selection means the user is selecting text — never steal.
+    if (selection && selection.rangeCount > 0 && !selection.isCollapsed) {
+      return true;
+    }
+    // Collapsed caret (or no selection API): defer whenever the editor has
+    // content, so arrow keys stay with the active rich-text editor.
+    return (editableRoot.textContent ?? '').length > 0;
+  }
+  const isTextarea = target.tagName === 'TEXTAREA';
+  const isTextInput = target.tagName === 'INPUT' && TEXT_INPUT_TYPES.has(target.type);
+  if (!isTextarea && !isTextInput) {
+    return false;
+  }
+  const input = target;
+  const {
+    selectionStart,
+    selectionEnd,
+    value
+  } = input;
+  // A non-collapsed selection means the user is selecting text — never steal.
+  if (selectionStart !== selectionEnd) {
+    return true;
+  }
+  // number inputs report null selection; treat as "always defer" for caret keys.
+  if (selectionStart == null) {
+    return true;
+  }
+  if (key === 'ArrowLeft' || key === 'ArrowUp' || key === 'Home') {
+    // Defer unless the caret is at the very start.
+    return selectionStart > 0;
+  }
+  if (key === 'ArrowRight' || key === 'ArrowDown' || key === 'End') {
+    // Defer unless the caret is at the very end.
+    return selectionStart < value.length;
+  }
+  return false;
+}
+
 /**
  * Hook for managing keyboard navigation within a linear list.
  *
@@ -31,6 +125,12 @@ import { useCallback, useRef } from 'react';
  * - End: Move to last item
  * - Escape: Custom callback (e.g., close menu)
  *
+ * By default the hook only *moves* focus and leaves `tabindex` management to
+ * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
+ * that owns a single tab stop (roving tabindex) across the items — stamping and
+ * repairing it as items mount/unmount or toggle disabled — for toolbars,
+ * segmented controls, tab strips, and similar composite widgets.
+ *
  * @example
  * ```
  * const {listRef, handleKeyDown} = useListFocus({
@@ -41,16 +141,45 @@ import { useCallback, useRef } from 'react';
  *   {items.map(item => <div role="menuitem" tabIndex={0}>{item}</div>)}
  * </div>
  * ```
+ *
+ * Roving-tabindex composite (e.g. a toolbar):
+ *
+ * @example
+ * ```
+ * const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+ *   itemSelector: 'button, input, [tabindex]',
+ *   orientation: 'horizontal',
+ *   hasRovingTabIndex: true,
+ *   hasCaretGuard: true,
+ * });
+ *
+ * <div ref={listRef} role="toolbar" onKeyDown={handleKeyDown} onFocus={handleFocus}>
+ *   {children}
+ * </div>
+ * ```
  */
 export function useListFocus(options = {}) {
   const {
     itemSelector = '[role="menuitem"]',
     wrap = true,
     onEscape,
-    orientation = 'vertical'
+    orientation = 'vertical',
+    hasHomeEnd = true,
+    isRtl = false,
+    hasRovingTabIndex = false,
+    hasCaretGuard = false
   } = options;
   const listRef = useRef(null);
 
+  /**
+   * Whether an item is disabled and therefore cannot receive DOM focus.
+   * A `.focus()` call on such an element silently no-ops, so navigation must
+   * skip these to avoid freezing on a disabled item (menus-4, navigation-5).
+   */
+  const isItemDisabled = useCallback(el => {
+    return el.getAttribute('aria-disabled') === 'true' || el.disabled === true || el.hasAttribute('disabled');
+  }, []);
+
   /**
    * Get all focusable items in the list.
    */
@@ -61,6 +190,34 @@ export function useListFocus(options = {}) {
     return Array.from(listRef.current.querySelectorAll(itemSelector));
   }, [itemSelector]);
 
+  /**
+   * Find the next enabled item index from `start`, moving by `step`, optionally
+   * wrapping. Returns -1 when no enabled item exists in range. Skipping
+   * disabled items here (rather than relying on the selector) keeps navigation
+   * from stalling on an item whose `.focus()` silently no-ops.
+   */
+  const findEnabledIndex = useCallback((items, start, step, shouldWrap) => {
+    const count = items.length;
+    if (count === 0) {
+      return -1;
+    }
+    let index = start;
+    for (let i = 0; i < count; i++) {
+      if (index < 0 || index >= count) {
+        if (!shouldWrap) {
+          return -1;
+        }
+        index = (index + count) % count;
+      }
+      const item = items[index];
+      if (item && !isItemDisabled(item)) {
+        return index;
+      }
+      index += step;
+    }
+    return -1;
+  }, [isItemDisabled]);
+
   /**
    * Get the currently focused item index.
    */
@@ -70,6 +227,62 @@ export function useListFocus(options = {}) {
     return items.findIndex(item => item === active || item.contains(active));
   }, [getItems]);
 
+  // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------
+
+  /**
+   * Set `tabindex` on an item, but only when it differs (avoids redundant DOM
+   * writes). Uses setAttribute so the value reflects even for elements (like
+   * `<button>`) whose default tabIndex is already 0.
+   */
+  const setTabIndex = useCallback((el, value) => {
+    if (el.getAttribute('tabindex') !== String(value)) {
+      el.setAttribute('tabindex', String(value));
+    }
+  }, []);
+
+  /**
+   * Stamp the roving tab stop: exactly one enabled item is tabbable (0), the
+   * rest are -1. Prefer keeping the currently-tabbable item if it is still
+   * enabled; otherwise promote the first enabled item (tab-stop repair).
+   */
+  const syncTabStops = useCallback(() => {
+    const items = getItems();
+    const enabled = items.filter(el => !isItemDisabled(el));
+    if (enabled.length === 0) {
+      return;
+    }
+    const current = enabled.find(el => el.getAttribute('tabindex') === '0');
+    const tabbable = current ?? enabled[0];
+    for (const el of items) {
+      setTabIndex(el, el === tabbable ? 0 : -1);
+    }
+  }, [getItems, isItemDisabled, setTabIndex]);
+
+  // Keep the tab stop valid across renders (items added/removed, disabled
+  // toggled). Runs after every commit but only when roving tabindex is on.
+  useIsomorphicLayoutEffect(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  });
+
+  /**
+   * Move focus to `items[index]`. When roving tabindex is enabled, also move
+   * the tab stop so `index` becomes the sole tabbable item.
+   */
+  const focusIndex = useCallback((items, index) => {
+    const target = items[index];
+    if (!target) {
+      return;
+    }
+    if (hasRovingTabIndex) {
+      for (const el of items) {
+        setTabIndex(el, el === target ? 0 : -1);
+      }
+    }
+    target.focus();
+  }, [hasRovingTabIndex, setTabIndex]);
+
   /**
    * Focus an item by index, clamping to valid range.
    */
@@ -79,76 +292,116 @@ export function useListFocus(options = {}) {
       return;
     }
     const clampedIndex = Math.max(0, Math.min(index, items.length - 1));
-    items[clampedIndex]?.focus();
-  }, [getItems]);
+    focusIndex(items, clampedIndex);
+  }, [getItems, focusIndex]);
 
   /**
-   * Focus the first item.
+   * Focus the first enabled item. Returns true when an item was focused.
    */
   const focusFirst = useCallback(() => {
     const items = getItems();
-    items[0]?.focus();
-  }, [getItems]);
+    const index = findEnabledIndex(items, 0, 1, false);
+    if (index !== -1) {
+      focusIndex(items, index);
+      return true;
+    }
+    return false;
+  }, [getItems, findEnabledIndex, focusIndex]);
 
   /**
-   * Focus the last item.
+   * Focus the last enabled item. Returns true when an item was focused.
    */
   const focusLast = useCallback(() => {
     const items = getItems();
-    items[items.length - 1]?.focus();
-  }, [getItems]);
+    const index = findEnabledIndex(items, items.length - 1, -1, false);
+    if (index !== -1) {
+      focusIndex(items, index);
+      return true;
+    }
+    return false;
+  }, [getItems, findEnabledIndex, focusIndex]);
+
+  /**
+   * Keep the roving stop pointing at whatever ended up focused (e.g. a click
+   * or programmatic focus) so the next Tab behaves correctly. No-op unless
+   * roving tabindex is enabled.
+   */
+  const handleFocus = useCallback(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  }, [hasRovingTabIndex, syncTabStops]);
 
   /**
    * Handle keyboard navigation.
    */
   const handleKeyDown = useCallback(e => {
+    // Let browser/OS shortcut chords (Ctrl/Cmd/Alt + key) through untouched.
+    if (e.ctrlKey || e.metaKey || e.altKey) {
+      return;
+    }
+
+    // Escape is handled regardless of orientation. Preserve the historical
+    // behavior of always consuming Escape here (preventDefault) so consumers
+    // that relied on it are unaffected.
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      onEscape?.();
+      return;
+    }
+    const horizontal = orientation === 'horizontal' || orientation === 'both';
+    const vertical = orientation === 'vertical' || orientation === 'both';
+
+    // Resolve which keys advance vs retreat, honoring RTL for horizontal.
+    const nextKeys = [];
+    const prevKeys = [];
+    if (horizontal) {
+      nextKeys.push(isRtl ? 'ArrowLeft' : 'ArrowRight');
+      prevKeys.push(isRtl ? 'ArrowRight' : 'ArrowLeft');
+    }
+    if (vertical) {
+      nextKeys.push('ArrowDown');
+      prevKeys.push('ArrowUp');
+    }
+    const isNext = nextKeys.includes(e.key);
+    const isPrev = prevKeys.includes(e.key);
+    const isHome = hasHomeEnd && e.key === 'Home';
+    const isEnd = hasHomeEnd && e.key === 'End';
+    if (!isNext && !isPrev && !isHome && !isEnd) {
+      return;
+    }
+
+    // Never hijack a caret key from a nested text input mid-line. Check both
+    // the React event target and the actual focused element (events may
+    // bubble up to the container).
+    if (hasCaretGuard && (shouldDeferToCaret(e.target, e.key) || shouldDeferToCaret(document.activeElement, e.key))) {
+      return;
+    }
     const currentIndex = getCurrentIndex();
     const items = getItems();
-    let handled = true;
-    const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
-    const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
-    switch (e.key) {
-      case nextKey:
-        {
-          if (currentIndex === -1) {
-            items[0]?.focus();
-          } else if (currentIndex < items.length - 1) {
-            items[currentIndex + 1]?.focus();
-          } else if (wrap) {
-            items[0]?.focus();
-          }
-          break;
-        }
-      case prevKey:
-        {
-          if (currentIndex === -1) {
-            items[items.length - 1]?.focus();
-          } else if (currentIndex > 0) {
-            items[currentIndex - 1]?.focus();
-          } else if (wrap) {
-            items[items.length - 1]?.focus();
-          }
-          break;
-        }
-      case 'Home':
-        focusFirst();
-        break;
-      case 'End':
-        focusLast();
-        break;
-      case 'Escape':
-        onEscape?.();
-        break;
-      default:
-        handled = false;
-    }
-    if (handled) {
-      e.preventDefault();
+    if (isNext) {
+      const from = currentIndex === -1 ? 0 : currentIndex + 1;
+      const next = findEnabledIndex(items, from, 1, wrap);
+      if (next !== -1) {
+        focusIndex(items, next);
+      }
+    } else if (isPrev) {
+      const from = currentIndex === -1 ? items.length - 1 : currentIndex - 1;
+      const prev = findEnabledIndex(items, from, -1, wrap);
+      if (prev !== -1) {
+        focusIndex(items, prev);
+      }
+    } else if (isHome) {
+      focusFirst();
+    } else if (isEnd) {
+      focusLast();
     }
-  }, [getCurrentIndex, getItems, wrap, orientation, focusFirst, focusLast, onEscape]);
+    e.preventDefault();
+  }, [getCurrentIndex, getItems, wrap, orientation, isRtl, hasHomeEnd, hasCaretGuard, findEnabledIndex, focusIndex, focusFirst, focusLast, onEscape]);
   return {
     listRef,
     handleKeyDown,
+    handleFocus,
     focusItem,
     focusFirst,
     focusLast

package/dist/hooks/useLongPress.d.ts

@@ -0,0 +1,21 @@
+export interface UseLongPressOptions {
+    /** Fired with the touch start point once the press is held for `delayMs`. */
+    onLongPress: (point: {
+        x: number;
+        y: number;
+    }) => void;
+    /** When true, touch handlers are inert. */
+    disabled?: boolean;
+    /** Hold duration before the press fires, in ms. Defaults to 500. */
+    delayMs?: number;
+    /** Movement past this distance (px, either axis) cancels the press. Defaults to 10. */
+    moveCancelPx?: number;
+}
+export interface UseLongPressHandlers {
+    onTouchStart: (e: React.TouchEvent) => void;
+    onTouchMove: (e: React.TouchEvent) => void;
+    onTouchEnd: () => void;
+    onTouchCancel: () => void;
+}
+export declare function useLongPress(options: UseLongPressOptions): UseLongPressHandlers;
+//# sourceMappingURL=useLongPress.d.ts.map

package/dist/hooks/useLongPress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLongPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useLongPress.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,mBAAmB,GAC3B,oBAAoB,CAsEtB"}

package/dist/hooks/useLongPress.js

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useLongPress.ts
+ * @input Long-press options: onLongPress callback, disabled, delayMs, moveCancelPx
+ * @output Touch handlers to spread onto an element
+ * @position Core hook for touch long-press invocation; used by ContextMenu
+ *
+ * SYNC: When modified, update the hooks barrel /packages/core/src/hooks/index.ts
+ *
+ * Detects a single-finger long-press: fires `onLongPress` with the touch
+ * start point after `delayMs`. Cancels if the finger moves past
+ * `moveCancelPx` (treated as a scroll/drag), lifts, or the touch is
+ * cancelled. The pending timer is also cleared on unmount.
+ *
+ * Motivation: iOS Safari never synthesizes a `contextmenu` event on
+ * long-press, so long-press is the only touch affordance for opening
+ * cursor-positioned surfaces.
+ */
+import { useCallback, useEffect, useRef } from 'react';
+
+// Default long-press tuning.
+const DEFAULT_DELAY_MS = 500;
+const DEFAULT_MOVE_CANCEL_PX = 10;
+export function useLongPress(options) {
+  const {
+    onLongPress,
+    disabled = false,
+    delayMs = DEFAULT_DELAY_MS,
+    moveCancelPx = DEFAULT_MOVE_CANCEL_PX
+  } = options;
+  const timerRef = useRef(null);
+  const startRef = useRef(null);
+  // Keep the latest callback without re-creating handlers on every render.
+  const onLongPressRef = useRef(onLongPress);
+  onLongPressRef.current = onLongPress;
+  const clear = useCallback(() => {
+    if (timerRef.current != null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    startRef.current = null;
+  }, []);
+  const onTouchStart = useCallback(e => {
+    if (disabled || e.touches.length !== 1) {
+      return;
+    }
+    const touch = e.touches[0];
+    // Clear any stale timer first, THEN record the start point — clearing
+    // also nulls startRef, so order matters.
+    clear();
+    startRef.current = {
+      x: touch.clientX,
+      y: touch.clientY
+    };
+    timerRef.current = setTimeout(() => {
+      const start = startRef.current;
+      if (start == null) {
+        return;
+      }
+      onLongPressRef.current({
+        x: start.x,
+        y: start.y
+      });
+    }, delayMs);
+  }, [disabled, delayMs, clear]);
+  const onTouchMove = useCallback(e => {
+    const start = startRef.current;
+    if (start == null || e.touches.length !== 1) {
+      return;
+    }
+    const touch = e.touches[0];
+    if (Math.abs(touch.clientX - start.x) > moveCancelPx || Math.abs(touch.clientY - start.y) > moveCancelPx) {
+      // Treat as a scroll/drag, not a long-press.
+      clear();
+    }
+  }, [moveCancelPx, clear]);
+
+  // Cancel any pending long-press timer on unmount.
+  useEffect(() => clear, [clear]);
+  return {
+    onTouchStart,
+    onTouchMove,
+    onTouchEnd: clear,
+    onTouchCancel: clear
+  };
+}