@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/hooks/index.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports hooks from individual files
+ * @output Exports all hooks
+ * @position Hook entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header
+ */
+
+export {useFocusTrap} from './useFocusTrap';
+export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
+
+export {useGridFocus} from './useGridFocus';
+export type {UseGridFocusOptions, UseGridFocusReturn} from './useGridFocus';
+
+export {useListFocus} from './useListFocus';
+export type {UseListFocusOptions, UseListFocusReturn} from './useListFocus';
+
+export {useMediaQuery} from './useMediaQuery';
+
+export {useOverflow} from './useOverflow';
+export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';
+
+export {useScrollOverflow} from './useScrollOverflow';
+export type {ScrollOverflowState} from './useScrollOverflow';
+
+export {useScrollLock} from './useScrollLock';
+
+export {useEntryAnimation} from './useEntryAnimation';
+export type {EntryAnimationPreset} from './useEntryAnimation';
+
+export {useStreamingText} from './useStreamingText';
+export type {
+  StreamingTextSpeed,
+  UseStreamingTextOptions,
+} from './useStreamingText';
+export {useImageMode} from './useImageMode';
+export type {ImageSampleRegion, UseImageModeOptions} from './useImageMode';
+
+export {useClickableContainer} from './useClickableContainer';
+export type {
+  UseClickableContainerOptions,
+  ClickableContainerResult,
+} from './useClickableContainer';
+
+export {useInputContainer} from './useInputContainer';
+export type {UseInputContainerOptions} from './useInputContainer';
+
+export {useInteractiveRole} from './useInteractiveRole';
+export type {
+  InteractiveRole,
+  UseInteractiveRoleOptions,
+} from './useInteractiveRole';

package/src/hooks/useClickableContainer.doc.mjs

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useClickableContainer',
+  displayName: 'useClickableContainer',
+  keywords: ['click', 'container', 'card', 'pressable', 'interactive', 'nested', 'link', 'button', 'delegate'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseClickableContainerOptions',
+      description: 'Configuration object for the clickable container.',
+      required: true,
+    },
+    {
+      name: 'options.containerRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: 'Ref to the outer container element.',
+      required: true,
+    },
+    {
+      name: 'options.interactiveRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: 'Ref to the primary interactive element inside (link, button). If no onClick or href is provided, clicks are proxied to this element.',
+      required: false,
+    },
+    {
+      name: 'options.onClick',
+      type: '(event: MouseEvent<HTMLElement>) => void',
+      description: 'Click handler fired when the container surface (not a nested interactive element) is clicked.',
+      required: false,
+    },
+    {
+      name: 'options.href',
+      type: 'string',
+      description: 'Navigation URL. When provided, clicking the container navigates to this URL.',
+      required: false,
+    },
+    {
+      name: 'options.target',
+      type: 'string',
+      description: "Link target (e.g., '_blank'). Used with href for navigation behavior.",
+      required: false,
+    },
+    {
+      name: 'options.disabled',
+      type: 'boolean',
+      description: 'Whether the container is disabled.',
+      default: 'false',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'onClick',
+      type: '(event: MouseEvent<HTMLElement>) => void',
+      description: 'Click handler to attach to the container element.',
+    },
+    {
+      name: 'onMouseUp',
+      type: '(event: MouseEvent<HTMLElement>) => void',
+      description: 'Mouse up handler to attach to the container (handles middle-click navigation for href).',
+    },
+  ],
+  usage: {
+    description:
+      'Makes a container element clickable while preserving nested interactive element behavior. Solves the "nested interactive elements" problem: when a card is clickable but contains buttons/links, clicking those should NOT trigger the card\'s action. Detects interactive ancestors between the click target and the container, and ignores text selections. Supports href navigation (including middle-click and Ctrl/Cmd+click for new tabs).',
+    bestPractices: [
+      { guidance: true, description: 'Attach both onClick and onMouseUp to the container element for full click handling including middle-click.' },
+      { guidance: true, description: 'Use inside ClickableCard or SelectableCard for the standard card interaction pattern.' },
+      { guidance: false, description: 'Use when the entire container is a single interactive element; just use a <button> or <a> directly.' },
+    ],
+  },
+  relatedComponents: ['ClickableCard', 'SelectableCard'],
+  relatedHooks: ['useInputContainer'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Makes container element clickable while preserving nested interactive element behavior. Solves "nested interactive elements" problem: when card is clickable but contains buttons/links, clicking those must NOT trigger card\'s action. Detects interactive ancestors between click target + container, ignores text selections. Supports href navigation (incl. middle-click + Ctrl/Cmd+click for new tabs).',
+  paramDescriptions: {
+    options: 'config for clickable container.',
+    'options.containerRef': 'ref to outer container element.',
+    'options.interactiveRef': 'ref to primary interactive element inside (link, button). If no onClick / href provided, clicks proxied to this element.',
+    'options.onClick': 'click handler fired when container surface (not nested interactive element) clicked.',
+    'options.href': 'navigation URL. When provided, clicking container navigates to it.',
+    'options.target': "link target (e.g. '_blank'). Used w/ href for navigation behavior.",
+    'options.disabled': 'whether container disabled.',
+  },
+  returnDescriptions: {
+    onClick: 'click handler for container element.',
+    onMouseUp: 'mouse up handler for container (handles middle-click navigation for href).',
+  },
+  usage: {
+    description:
+      'Makes container element clickable while preserving nested interactive element behavior. Solves "nested interactive elements" problem: when card is clickable but contains buttons/links, clicking those must NOT trigger card\'s action. Detects interactive ancestors between click target + container, ignores text selections. Supports href navigation (incl. middle-click + Ctrl/Cmd+click for new tabs).',
+    bestPractices: [
+      { guidance: true, description: 'Attach both onClick + onMouseUp to container element for full click handling incl. middle-click.' },
+      { guidance: true, description: 'Use inside ClickableCard / SelectableCard for standard card interaction pattern.' },
+      { guidance: false, description: 'Use when entire container is single interactive element; just use <button> / <a> directly.' },
+    ],
+  },
+};

package/src/hooks/useClickableContainer.ts

@@ -0,0 +1,236 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useClickableContainer.ts
+ * @input Container ref, interactive element ref, click/href handlers
+ * @output onClick and onMouseUp handlers for the container
+ * @position Core hook for clickable containers that safely handle nested interactive elements
+ *
+ * Solves the "nested interactive elements" problem: when a card is clickable
+ * but contains buttons/links, clicking those should NOT trigger the card's action.
+ */
+
+import {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';
+
+// Interactive element selectors — clicks on these (or their descendants)
+// should NOT bubble to the container's click handler.
+const INTERACTIVE_SELECTORS = [
+  'button',
+  'a',
+  'input',
+  'select',
+  'textarea',
+  '[role="button"]',
+  '[role="link"]',
+  '[role="checkbox"]',
+  '[role="radio"]',
+  '[role="switch"]',
+  '[role="tab"]',
+  '[role="menuitem"]',
+  '[role="option"]',
+  '[role="combobox"]',
+  '[role="listbox"]',
+  '[role="slider"]',
+  '[role="spinbutton"]',
+  '[data-pressable-container]',
+].join(',');
+
+const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
+
+/**
+ * Check whether an element has an interactive ancestor between it and the root.
+ * If the click target is inside a nested button/link/etc., we should NOT
+ * handle it at the container level.
+ */
+function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {
+  let current: Element | null = el;
+  while (current != null && current !== rootEl && current !== document.body) {
+    if (
+      current.matches(INTERACTIVE_SELECTORS) &&
+      !current.matches(NON_INTERACTIVE_SELECTORS)
+    ) {
+      return true;
+    }
+    current = current.parentElement;
+  }
+  return false;
+}
+
+/** Check if there's a text selection inside the node (don't navigate on text select) */
+function hasTextSelection(node: Element): boolean {
+  if (typeof document === 'undefined' || !('getSelection' in document)) {
+    return false;
+  }
+  const selection = document.getSelection();
+  if (selection == null || selection.isCollapsed) {
+    return false;
+  }
+  return node.contains(selection.anchorNode);
+}
+
+export interface UseClickableContainerOptions {
+  /** Ref to the outer container element */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Ref to the primary interactive element inside (link, button) */
+  interactiveRef?: RefObject<HTMLElement | null>;
+  /** Click handler */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  /** Navigation URL — when provided, clicking the container navigates */
+  href?: string;
+  /** Link target */
+  target?: string;
+  /** Whether the container is disabled */
+  disabled?: boolean;
+}
+
+export interface ClickableContainerResult {
+  onClick: (event: MouseEvent<HTMLElement>) => void;
+  onMouseUp: (event: MouseEvent<HTMLElement>) => void;
+}
+
+/**
+ * Hook that makes a container element clickable while preserving
+ * nested interactive element behavior.
+ *
+ * When the user clicks the container surface (not on a nested button/link),
+ * the hook fires the onClick handler or navigates to href.
+ * When the user clicks a nested interactive element, it does nothing —
+ * the nested element handles its own event.
+ *
+ * @compositionHint Use inside ClickableCard or SelectableCard.
+ * For custom interactive containers, pair with a ref to the outer div.
+ *
+ * @example
+ * ```
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { onClick, onMouseUp } = useClickableContainer({
+ *   containerRef,
+ *   onClick: () => console.log('card clicked'),
+ * });
+ * return (
+ *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *     <p>Click anywhere on this card</p>
+ *     <button onClick={() => alert('button')}>Nested button</button>
+ *   </div>
+ * );
+ * ```
+ */
+export function useClickableContainer({
+  containerRef,
+  interactiveRef,
+  onClick: onClickProp,
+  href,
+  target,
+  disabled = false,
+}: UseClickableContainerOptions): ClickableContainerResult {
+  // Mark container as pressable for the interactive selector check
+  useEffect(() => {
+    const el = containerRef.current;
+    if (el) {
+      el.setAttribute('data-pressable-container', 'true');
+    }
+  }, [containerRef]);
+
+  const onClick = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      if (disabled) {
+        return;
+      }
+
+      const containerEl = containerRef.current;
+      if (!containerEl) {
+        return;
+      }
+
+      // Don't trigger on text selection
+      if (hasTextSelection(containerEl)) {
+        return;
+      }
+
+      const eventTarget = event.target;
+      if (!(eventTarget instanceof Element)) {
+        return;
+      }
+
+      // If the click landed on or inside a nested interactive element, bail
+      if (
+        eventTarget !== event.currentTarget &&
+        hasInteractiveAncestor(eventTarget, containerEl)
+      ) {
+        return;
+      }
+
+      // Fire the click handler
+      onClickProp?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+
+      // Navigate if href is provided
+      if (href != null) {
+        const shouldOpenNewTab =
+          target === '_blank' || event.ctrlKey || event.metaKey;
+        if (shouldOpenNewTab) {
+          window.open(href, '_blank', 'noopener');
+        } else if (interactiveRef?.current) {
+          // Proxy click to the sr-only link so the framework link component
+          // handles navigation (client-side transitions in Next.js, etc.).
+          interactiveRef.current.click();
+        } else {
+          // eslint-disable-next-line react-compiler/react-compiler -- browser navigation API
+          window.location.href = href;
+        }
+      }
+
+      // Proxy click to the interactive ref if no explicit handler
+      if (href == null && onClickProp == null && interactiveRef?.current) {
+        const clickEvent = new MouseEvent('click', {
+          bubbles: event.bubbles,
+          cancelable: event.cancelable,
+          ctrlKey: event.ctrlKey,
+          metaKey: event.metaKey,
+          shiftKey: event.shiftKey,
+          altKey: event.altKey,
+          button: event.button,
+        });
+        interactiveRef.current.dispatchEvent(clickEvent);
+        event.stopPropagation();
+      }
+    },
+    [containerRef, interactiveRef, onClickProp, href, target, disabled],
+  );
+
+  const onMouseUp = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      if (disabled) {
+        return;
+      }
+
+      const containerEl = containerRef.current;
+      if (!containerEl) {
+        return;
+      }
+
+      const eventTarget = event.target;
+      if (!(eventTarget instanceof Element)) {
+        return;
+      }
+
+      // Middle-click on href opens in new tab
+      const isMiddleClick = event.button === 1;
+      if (
+        isMiddleClick &&
+        href != null &&
+        (eventTarget === event.currentTarget ||
+          !hasInteractiveAncestor(eventTarget, containerEl))
+      ) {
+        window.open(href, '_blank', 'noopener');
+      }
+    },
+    [containerRef, href, disabled],
+  );
+
+  return {onClick, onMouseUp};
+}

package/src/hooks/useEntryAnimation.doc.mjs

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useEntryAnimation',
+  displayName: 'useEntryAnimation',
+  keywords: ['animation', 'entry', 'mount', 'transition', 'slide', 'fade', 'scale', 'motion', 'stylex'],
+  params: [
+    {
+      name: 'preset',
+      type: "'slideDown' | 'slideUp' | 'fadeIn' | 'scaleIn'",
+      description: 'Animation preset to apply on mount.',
+      default: "'slideDown'",
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'entryStyle',
+      type: 'StyleXStyles | null',
+      description: 'A StyleX style object for the entry animation, or null if the element was rendered on initial page load (no animation needed).',
+    },
+  ],
+  usage: {
+    description:
+      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
+    bestPractices: [
+      { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, or expanding sections.' },
+      { guidance: true, description: 'Spread the returned style into stylex.props() alongside other styles.' },
+      { guidance: false, description: 'Use for elements that should be visible on initial page load; they will not animate.' },
+    ],
+  },
+  relatedComponents: ['FieldStatus'],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'animation',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+  paramDescriptions: {
+    preset: 'animation preset applied on mount.',
+  },
+  returnDescriptions: {
+    entryStyle: 'StyleX style object for entry animation / null if element rendered on initial page load (no animation needed).',
+  },
+  usage: {
+    description:
+      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+    bestPractices: [
+      { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },
+      { guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },
+      { guidance: false, description: 'Use for elements that should be visible on initial page load; they will not animate.' },
+    ],
+  },
+};

package/src/hooks/useEntryAnimation.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+/**
+ * @file useEntryAnimation.ts
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports useEntryAnimation hook for mount-only entry animations
+ * @position Hook utility; consumed by FieldStatus and available to consumers
+ *
+ * Provides entry animations for conditionally rendered elements.
+ * Only animates when the element is dynamically mounted after the initial
+ * page paint — statically rendered elements on page load are not animated.
+ */
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {durationVars, easeVars, spacingVars} from '../theme/tokens.stylex';
+
+// Track whether the initial page paint has completed.
+// Elements rendered on page load should not animate;
+// only dynamically inserted ones should.
+//
+// NOTE: This module is marked 'use client' so it never runs on the server.
+// If the directive is removed, this flag will always be false during SSR,
+// and useState(() => initialPaintComplete) will capture false — meaning
+// animations won't run after hydration. Keep 'use client' or add an
+// effect-based fallback if SSR support is needed.
+let initialPaintComplete = false;
+if (typeof window !== 'undefined') {
+  requestAnimationFrame(() => {
+    initialPaintComplete = true;
+  });
+}
+
+const slideDown = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateY(calc(-1 * ${spacingVars['--spacing-2']}))`,
+  },
+  to: {opacity: 1, transform: 'translateY(0)'},
+});
+
+const slideUp = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateY(${spacingVars['--spacing-2']})`,
+  },
+  to: {opacity: 1, transform: 'translateY(0)'},
+});
+
+const fadeIn = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
+const scaleIn = stylex.keyframes({
+  from: {opacity: 0, transform: 'scale(0.95)'},
+  to: {opacity: 1, transform: 'scale(1)'},
+});
+
+const styles = stylex.create({
+  slideDown: {
+    animationName: slideDown,
+    animationDuration: durationVars['--duration-fast-max'],
+    animationTimingFunction: easeVars['--ease-standard'],
+    animationFillMode: 'backwards',
+  },
+  slideUp: {
+    animationName: slideUp,
+    animationDuration: durationVars['--duration-fast-max'],
+    animationTimingFunction: easeVars['--ease-standard'],
+    animationFillMode: 'backwards',
+  },
+  fadeIn: {
+    animationName: fadeIn,
+    animationDuration: durationVars['--duration-fast-max'],
+    animationTimingFunction: easeVars['--ease-standard'],
+    animationFillMode: 'backwards',
+  },
+  scaleIn: {
+    animationName: scaleIn,
+    animationDuration: durationVars['--duration-fast-max'],
+    animationTimingFunction: easeVars['--ease-standard'],
+    animationFillMode: 'backwards',
+  },
+});
+
+export type EntryAnimationPreset =
+  | 'slideDown'
+  | 'slideUp'
+  | 'fadeIn'
+  | 'scaleIn';
+
+/**
+ * Returns a StyleX style for animating an element on mount.
+ *
+ * Only animates when the element is dynamically inserted after the initial
+ * page paint. Elements rendered on page load are not animated.
+ *
+ * @example
+ * ```
+ * const entryStyle = useEntryAnimation('slideDown');
+ * <div {...stylex.props(entryStyle)}>Animated content</div>
+ * ```
+ */
+export function useEntryAnimation(
+  preset: EntryAnimationPreset = 'slideDown',
+): StyleXStyles | null {
+  const [animate] = useState(() => initialPaintComplete);
+  return animate ? styles[preset] : null;
+}

package/src/hooks/useFocusTrap.doc.mjs

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useFocusTrap',
+  displayName: 'useFocusTrap',
+  keywords: ['focus', 'trap', 'modal', 'dialog', 'accessibility', 'a11y', 'keyboard', 'tab', 'escape', 'wai-aria'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseFocusTrapOptions',
+      description: 'Configuration object for the focus trap.',
+      required: true,
+    },
+    {
+      name: 'options.isActive',
+      type: 'boolean',
+      description: 'Whether the focus trap is currently active.',
+      required: true,
+    },
+    {
+      name: 'options.onEscape',
+      type: '() => void',
+      description: 'Callback when Escape key is pressed inside the trapped container.',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'containerRef',
+      type: 'React.RefObject<HTMLElement | null>',
+      description: 'Ref to attach to the container element that should trap focus.',
+    },
+    {
+      name: 'focusFirst',
+      type: '() => void',
+      description: 'Focuses the first focusable element inside the container.',
+    },
+  ],
+  usage: {
+    description:
+      'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.',
+    bestPractices: [
+      { guidance: true, description: 'Call focusFirst() when opening a dialog/modal to move focus into the trapped region.' },
+      { guidance: true, description: 'Provide an onEscape callback to close the dialog when Escape is pressed.' },
+      { guidance: false, description: 'Use on non-modal content like tooltips or dropdowns; those need light-dismiss, not focus trapping.' },
+    ],
+  },
+  relatedComponents: ['Dialog', 'DatePicker'],
+  relatedHooks: ['useListFocus', 'useScrollLock'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
+  paramDescriptions: {
+    options: 'config for focus trap.',
+    'options.isActive': 'whether focus trap currently active.',
+    'options.onEscape': 'callback when Escape key pressed inside trapped container.',
+  },
+  returnDescriptions: {
+    containerRef: 'ref to attach to container element that should trap focus.',
+    focusFirst: 'focuses first focusable element inside container.',
+  },
+  usage: {
+    description:
+      'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
+    bestPractices: [
+      { guidance: true, description: 'Call focusFirst() when opening dialog/modal to move focus into trapped region.' },
+      { guidance: true, description: 'Provide onEscape callback to close dialog when Escape pressed.' },
+      { guidance: false, description: 'Use on non-modal content like tooltips / dropdowns; those need light-dismiss, not focus trapping.' },
+    ],
+  },
+};