@pharos-ds/core 0.1.9

package/src/hooks/useInputStatusIcon.tsx

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useInputStatusIcon.tsx
+ * @input Input status, statusVariant, and InputGroup awareness
+ * @output The on-field status icon element (with tooltip) and aria-describedby wiring
+ * @position Shared hook for bordered inputs that render a status affordance inside the control
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (exports)
+ *
+ * Centralizes the on-field status icon across the bordered inputs (TextInput,
+ * TextArea, NumberInput, DateInput, DateTimeInput, DateRangeInput, TimeInput,
+ * FileInput) so the three statusVariants behave consistently:
+ *
+ * - `attached`  → icon sits inside the control; the message box below carries
+ *   the text.
+ * - `detached`  → the detached message box renders its OWN leading icon, so the
+ *   on-field icon is suppressed here to avoid a duplicate glyph.
+ * - `tooltip`   → no message box renders; the status is surfaced through an
+ *   info-tip on the on-field icon. The icon is a real focusable `<button>` so
+ *   the status is reachable by every user, not just those with hover or a
+ *   screen reader:
+ *     - Keyboard (no AT): the button is in the tab order (WCAG 2.1.1) with a
+ *       visible focus ring (WCAG 2.4.7); focusing it opens the tooltip.
+ *     - Pointer: hover opens it (guarded to fine pointers).
+ *     - Touch: hover is unavailable, so a tap toggles the tooltip open/closed.
+ *     - Assistive tech: the button has an accessible name (its status type,
+ *       WCAG 4.1.2) and is described by the message via `aria-describedby`.
+ *     - Dismissible with Escape and hoverable (WCAG 1.4.13) via useTooltip.
+ */
+
+import {useCallback, useEffect, useState} from 'react';
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon, type IconName, type IconSize} from '../Icon';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
+import type {InputStatus, InputStatusType} from '../Field/types';
+import {useTooltip} from '../Tooltip';
+import {useTranslator} from '../i18n';
+import {colorVars, radiusVars} from '../theme/tokens.stylex';
+
+/**
+ * Maps each status type to its glyph. Shared so every input shows the same icon
+ * for a given status, matching the detached message box's leading icon.
+ */
+const STATUS_ICON: Record<InputStatusType, IconName> = {
+  warning: 'warning',
+  error: 'error',
+  success: 'success',
+};
+
+/**
+ * Accessible-name i18n keys for the focusable status button, keyed by type.
+ */
+const STATUS_BUTTON_LABEL_KEY: Record<InputStatusType, string> = {
+  warning: '@pharos.input.statusButton.warning',
+  error: '@pharos.input.statusButton.error',
+  success: '@pharos.input.statusButton.success',
+};
+
+const styles = stylex.create({
+  // Contain the anchor so the tooltip positions against the icon, and keep the
+  // glyph vertically centered within the input control.
+  iconAnchor: {
+    display: 'inline-flex',
+    alignItems: 'center',
+  },
+  // The tooltip-variant status affordance is a real button so it is keyboard
+  // focusable and tappable. Strip the native chrome and show only a focus ring.
+  statusButton: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 0,
+    margin: 0,
+    border: 'none',
+    background: 'none',
+    color: 'inherit',
+    cursor: 'pointer',
+    borderRadius: radiusVars['--radius-full'],
+    outlineWidth: {default: null, ':focus-visible': '2px'},
+    outlineStyle: {default: null, ':focus-visible': 'solid'},
+    outlineColor: {
+      default: null,
+      ':focus-visible': colorVars['--color-accent'],
+    },
+    outlineOffset: {default: null, ':focus-visible': '2px'},
+  },
+});
+
+export interface UseInputStatusIconOptions {
+  /** The input's status, or undefined when there is none. */
+  status?: InputStatus;
+  /** How the status is presented relative to the input. */
+  statusVariant?: FieldStatusVariant;
+  /** Whether the input is inside an InputGroup (which owns status rendering). */
+  isInGroup?: boolean;
+  /** Size of the on-field icon. @default 'md' */
+  size?: IconSize;
+}
+
+export interface UseInputStatusIconReturn {
+  /**
+   * The on-field status affordance to render inside the input container —
+   * the status icon (plain, for attached) or a focusable info-tip button plus
+   * its tooltip layer (for the `tooltip` variant). `null` when no icon should
+   * render (no status, `detached` variant, or inside a group).
+   */
+  statusIcon: ReactNode;
+  /**
+   * ID to add to the input's `aria-describedby` when — and only when — the
+   * status is surfaced through a rendered tooltip layer (the `tooltip` variant
+   * with a message). It is `undefined` in every other case (no status, no
+   * message, `attached`/`detached`, or inside a group), so call-sites can drop
+   * it straight into their described-by list without a dangling reference: the
+   * id is present exactly when its tooltip element is in the DOM.
+   */
+  describedBy: string | undefined;
+}
+
+/**
+ * Builds the on-field status icon and its accessibility wiring for a bordered
+ * input. See the file header for the per-variant behavior.
+ */
+export function useInputStatusIcon({
+  status,
+  statusVariant = 'attached',
+  isInGroup = false,
+  size = 'md',
+}: UseInputStatusIconOptions): UseInputStatusIconReturn {
+  const t = useTranslator();
+  const isTooltipVariant = statusVariant === 'tooltip';
+  const hasTooltip = isTooltipVariant && !!status?.message;
+
+  // Touch tap-to-toggle. Hover is unavailable on touch, and useTooltip
+  // suppresses simulated hover there, so on touch a tap controls visibility.
+  // `undefined` leaves the tooltip uncontrolled (pointer + keyboard drive it);
+  // a boolean takes control for the current open/close cycle.
+  const [tapOpen, setTapOpen] = useState<boolean | undefined>(undefined);
+
+  const tooltip = useTooltip({
+    placement: 'above',
+    isEnabled: hasTooltip,
+    isOpen: tapOpen,
+  });
+
+  // Re-hand control back to hover/focus once a tap-opened tooltip is dismissed
+  // (Escape/outside interaction), so subsequent pointer/keyboard use behaves
+  // normally.
+  const handleButtonBlur = useCallback(() => {
+    setTapOpen(undefined);
+  }, []);
+
+  const handleButtonClick = useCallback(() => {
+    // Only take control on touch/hover-less devices. On hover-capable devices
+    // pointer hover and keyboard focus already drive the tooltip (uncontrolled),
+    // so a click-toggle would fight them; leave it uncontrolled there.
+    if (
+      typeof window === 'undefined' ||
+      typeof window.matchMedia !== 'function' ||
+      !window.matchMedia('(hover: none)').matches
+    ) {
+      return;
+    }
+    setTapOpen(prev => (prev === true ? false : true));
+  }, []);
+
+  // Dismiss a tap-opened tooltip on Escape and return to the uncontrolled
+  // state (useTooltip owns Escape for the uncontrolled case, but while we hold
+  // control via isOpen it does not, so mirror it here).
+  useEffect(() => {
+    if (tapOpen !== true) {
+      return;
+    }
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setTapOpen(undefined);
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [tapOpen]);
+
+  // Inside a group the group owns status rendering; the detached message box
+  // renders its own leading icon, so the on-field icon would duplicate it.
+  const shouldRenderIcon =
+    !!status && !isInGroup && statusVariant !== 'detached';
+
+  if (!shouldRenderIcon) {
+    return {statusIcon: null, describedBy: undefined};
+  }
+
+  const icon = (
+    <Icon icon={STATUS_ICON[status.type]} size={size} color={status.type} />
+  );
+
+  // Attached (and tooltip-without-message) variants: plain, non-interactive
+  // icon. The message box (attached) already carries the text.
+  if (!hasTooltip) {
+    return {statusIcon: icon, describedBy: undefined};
+  }
+
+  return {
+    statusIcon: (
+      <>
+        <button
+          type="button"
+          ref={tooltip.ref}
+          aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
+          aria-describedby={tooltip.describedBy}
+          onClick={handleButtonClick}
+          onBlur={handleButtonBlur}
+          {...stylex.props(styles.statusButton)}>
+          {icon}
+        </button>
+        {tooltip.renderTooltip(status.message)}
+      </>
+    ),
+    describedBy: tooltip.describedBy,
+  };
+}

package/src/hooks/useInteractiveRole.ts

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useInteractiveRole.ts
+ * @input Uses useInteractiveTrigger
+ * @output Exports useInteractiveRole hook and InteractiveRole type
+ * @position Hook utility; consumed by Token, Thumbnail, Item, ClickableCard, etc.
+ *
+ * Centralizes the "what element should I render as?" decision for
+ * polymorphic components. The priority order:
+ *
+ *   1. href → 'link' (navigation always wins, unless disabled)
+ *   2. onClick → 'button' (explicit interactivity)
+ *   3. interactive trigger context → 'button' (implicit via parent)
+ *   4. else → 'inert' (non-interactive)
+ *
+ * A disabled `href` is excluded at step 1 and therefore resolves via the
+ * remaining steps — 'inert' when no onClick or context applies.
+ *
+ * This hook is the single place to add new context-based triggers
+ * (e.g., Popover, DropdownMenu, Disclosure). Components that consume
+ * this hook never need updating when new trigger contexts are added.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
+ */
+
+import {useInteractiveRoleContext} from '../InteractiveRoleContext/InteractiveRoleContext';
+
+/**
+ * The resolved interactive role for a polymorphic component.
+ *
+ * - `'link'` — render as `<a>` (via LinkComponent)
+ * - `'button'` — render as `<button>`
+ * - `'inert'` — render as `<span>` or `<div>` (non-interactive)
+ */
+export type InteractiveRole = 'link' | 'button' | 'inert';
+
+export interface UseInteractiveRoleOptions {
+  /**
+   * URL for link navigation. When provided, the component renders as a link.
+   * Takes highest priority — a link always navigates.
+   */
+  href?: string;
+
+  /**
+   * Click handler. When provided, the component renders as a button.
+   * Takes priority over context-based triggers.
+   */
+  onClick?: ((...args: never[]) => unknown) | null;
+
+  /**
+   * Whether the component is disabled. When true, an `href` is ignored for
+   * role resolution (a disabled link is an a11y anti-pattern), so the role is
+   * decided by the remaining inputs: `onClick` → `'button'`, an interactive
+   * context → its role, otherwise `'inert'`. In particular a disabled `href`
+   * with no `onClick` and no context override resolves to `'inert'`, not a
+   * link or a button.
+   * @default false
+   */
+  isDisabled?: boolean;
+}
+
+/**
+ * Determines the interactive role for a polymorphic component.
+ *
+ * Centralizes the element-type decision so that adding new context-based
+ * triggers (popover, dropdown, etc.) only requires updating this hook —
+ * all consuming components inherit the new behavior automatically.
+ *
+ * @example
+ * ```ts
+ * function Token({ href, onClick, ... }) {
+ *   const role = useInteractiveRole({ href, onClick });
+ *
+ *   switch (role) {
+ *     case 'link': return <LinkComponent href={href} ...>{content}</LinkComponent>;
+ *     case 'button': return <button ...>{content}</button>;
+ *     case 'inert': return <span ...>{content}</span>;
+ *   }
+ * }
+ * ```
+ */
+export function useInteractiveRole({
+  href,
+  onClick,
+  isDisabled = false,
+}: UseInteractiveRoleOptions): InteractiveRole {
+  const contextRole = useInteractiveRoleContext();
+
+  // 1. href → link (unless disabled — a disabled href is skipped here and
+  // resolved by the checks below, landing on 'inert' if nothing else applies)
+  if (href != null && !isDisabled) {
+    return 'link';
+  }
+
+  // 2. Explicit onClick → button
+  if (onClick != null) {
+    return 'button';
+  }
+
+  // 3. Context-provided role override (e.g., Popover provides 'button')
+  if (contextRole != null) {
+    return contextRole;
+  }
+
+  // 4. Nothing interactive → inert
+  return 'inert';
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIsomorphicLayoutEffect.ts
+ * @input React useLayoutEffect, useEffect
+ * @output Exports useIsomorphicLayoutEffect
+ * @position Internal utility; used by components that need useLayoutEffect
+ *   but must avoid the SSR warning React emits when useLayoutEffect runs
+ *   on the server (where there is no DOM to synchronously measure).
+ *
+ * On the client this is useLayoutEffect; on the server it falls back to
+ * useEffect (which is a no-op during SSR anyway). The runtime behavior is
+ * identical — neither hook fires during server rendering — but React only
+ * warns about useLayoutEffect.
+ */
+
+import {useEffect, useLayoutEffect} from 'react';
+
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;

package/src/hooks/useKeyboardHint.doc.mjs

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useKeyboardHint',
+  displayName: 'useKeyboardHint',
+  keywords: ['keyboard', 'hint', 'arrow', 'navigation', 'roving', 'tabindex', 'focus', 'discoverability', 'toolbar', 'tabs', 'segmented', 'affordance', 'a11y'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseKeyboardHintOptions',
+      description: 'Configuration object for the keyboard hint.',
+      required: false,
+    },
+    {
+      name: 'options.orientation',
+      type: "'horizontal' | 'vertical' | 'both'",
+      description: 'Which arrow-key axis the composite navigates, controlling which arrow icons the hint shows (← → for horizontal, ↑ ↓ for vertical, all four for both).',
+      default: "'horizontal'",
+      required: false,
+    },
+    {
+      name: 'options.dismissAfterMs',
+      type: 'number',
+      description: 'Milliseconds before the hint auto-dismisses after appearing.',
+      default: '3000',
+      required: false,
+    },
+    {
+      name: 'options.isEnabled',
+      type: 'boolean',
+      description: 'Whether the hint is enabled. Set to false to suppress it for a specific instance (e.g. a disabled or read-only widget).',
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'hintElement',
+      type: 'ReactNode',
+      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility; render it unconditionally.',
+    },
+    {
+      name: 'onFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Attach to the container onFocus. Shows the hint on the first keyboard-focus (:focus-visible) entry from outside the composite.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Attach to the container onBlur. Hides the hint when focus leaves the composite entirely, and re-anchors when focus moves within.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description: 'Attach to the container onKeyDown. Dismisses the hint on the first arrow press (the user has discovered the interaction). Never prevents default or stops propagation.',
+    },
+  ],
+  usage: {
+    description:
+      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically; reach for the hook directly only when building a custom roving-tabindex widget.',
+    bestPractices: [
+      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them: call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
+      { guidance: true, description: 'Render hintElement as the last child of the composite container; it is position:fixed in the top layer and aria-hidden, so it never affects layout or the accessibility tree.' },
+      { guidance: true, description: 'Match orientation to the arrow keys your widget actually responds to so the hint shows the correct icons.' },
+      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation; the hint only makes sense where arrows move focus within a group.' },
+    ],
+  },
+  relatedComponents: ['Toolbar', 'TabList', 'SegmentedControl'],
+  relatedHooks: ['useListFocus', 'useGridFocus', 'useTreeFocus'],
+  importPath: '@pharos-ds/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',
+  paramDescriptions: {
+    options: 'config for the keyboard hint.',
+    'options.orientation': "arrow axis: 'horizontal' (← →), 'vertical' (↑ ↓), 'both' (all four). Controls shown icons.",
+    'options.dismissAfterMs': 'ms before auto-dismiss after appearing.',
+    'options.isEnabled': 'whether the hint is enabled; false suppresses it (e.g. disabled/read-only widget).',
+  },
+  returnDescriptions: {
+    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing; render unconditionally.',
+    onFocus: 'container onFocus: shows hint on first :focus-visible entry from outside.',
+    onBlur: 'container onBlur: hides on leaving the composite; re-anchors on internal moves.',
+    onKeyDown: 'container onKeyDown: dismisses on first arrow press. Never prevents default.',
+  },
+  usage: {
+    description:
+      'Ephemeral "← → to navigate" hint on first keyboard focus of a roving-tabindex composite. Top-layer anchored popover, aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; no re-show. Toolbar/TabList/SegmentedControl wire it in automatically.',
+    bestPractices: [
+      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first; it only dismisses).' },
+      { guidance: true, description: 'Render hintElement as last child; top-layer + aria-hidden, no layout/a11y impact.' },
+      { guidance: true, description: 'Match orientation to the arrows the widget responds to.' },
+      { guidance: false, description: 'Use for single controls / non-roving widgets.' },
+    ],
+  },
+};

package/src/hooks/useKeyboardHint.test.tsx

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useKeyboardHint.test.tsx
+ * @input Uses React Testing Library, useKeyboardHint
+ * @output Unit tests for keyboard hint rendering
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {useKeyboardHint, type KeyboardHintOrientation} from './useKeyboardHint';
+
+function TestHint({orientation}: {orientation?: KeyboardHintOrientation}) {
+  const {hintElement} = useKeyboardHint({orientation});
+  return <div>{hintElement}</div>;
+}
+
+function getKeyLabels(container: HTMLElement): (string | null)[] {
+  return Array.from(container.querySelectorAll('.pharos-kbd')).map(key =>
+    key.getAttribute('aria-label'),
+  );
+}
+
+function getKeyText(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('kbd')).map(
+    key => key.textContent ?? '',
+  );
+}
+
+describe('useKeyboardHint', () => {
+  it('renders horizontal arrow keys with Kbd', () => {
+    const {container} = render(<TestHint orientation="horizontal" />);
+
+    expect(getKeyLabels(container)).toEqual(['Left arrow', 'Right arrow']);
+    expect(getKeyText(container)).toEqual(['←', '→']);
+  });
+
+  it('renders vertical arrow keys with Kbd', () => {
+    const {container} = render(<TestHint orientation="vertical" />);
+
+    expect(getKeyLabels(container)).toEqual(['Up arrow', 'Down arrow']);
+    expect(getKeyText(container)).toEqual(['↑', '↓']);
+  });
+
+  it('renders all arrow keys for both-axis navigation', () => {
+    const {container} = render(<TestHint orientation="both" />);
+
+    expect(getKeyLabels(container)).toEqual([
+      'Left arrow',
+      'Right arrow',
+      'Up arrow',
+      'Down arrow',
+    ]);
+    expect(getKeyText(container)).toEqual(['←', '→', '↑', '↓']);
+  });
+
+  it('positions the hint farther from the anchor', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.style.marginBlockStart).toBe('var(--spacing-2)');
+  });
+
+  it('keeps the hint surface padding after useLayer reset styles', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.className).toContain('useKeyboardHint__styles.hint');
+  });
+});