@pharos-ds/core 0.1.9

package/dist/hooks/useImageMode.js

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useImageMode.ts
+ * @input Image source URL
+ * @output Detected mode luminance: 'dark' | 'light' | null
+ * @position Hook; used alongside MediaTheme for auto-detection
+ *
+ * Detects whether an image is predominantly dark or light by sampling
+ * its pixels via OffscreenCanvas. Runs entirely off the paint path —
+ * no visible canvas element, no layout thrash.
+ *
+ * Uses APCA perceptual lightness (sRGB linearization + power curve)
+ * which handles saturated colors better than BT.709 gamma-luma or
+ * WCAG 2 relative luminance.
+ *
+ * For regional detection (e.g. "what's the luminance where the text
+ * overlay sits"), pass a `region` option to sample a specific area.
+ *
+ * @example
+ * ```tsx
+ * function ImageCard({ src }: { src: string }) {
+ *   const mode = useImageMode(src);
+ *   return (
+ *     <div style={{ backgroundImage: `url(${src})` }}>
+ *       <MediaTheme mode={mode ?? 'dark'}>
+ *         <Text>Auto-detected text color</Text>
+ *       </MediaTheme>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+import { useState, useEffect } from 'react';
+
+/**
+ * Region to sample within the image (normalized 0-1 coordinates).
+ * Useful for detecting luminance where text will be overlaid,
+ * rather than the full image average.
+ */
+
+/**
+ * APCA perceptual lightness from sRGB values (0-255).
+ *
+ * Linearizes sRGB with a 2.4 exponent, computes luminance Y using
+ * APCA coefficients (slightly refined from BT.709), then applies a
+ * perceptual power curve (Y^0.56) that maps linear light to a scale
+ * where 0.5 ≈ perceptual mid-gray.
+ *
+ * This outperforms both raw BT.709 gamma-luma and WCAG 2 relative
+ * luminance for dark/light surface detection — especially on saturated
+ * colors (reds, blues) where gamma-encoded luma overestimates brightness.
+ *
+ * Returns 0–1 where 0 is black, 1 is white.
+ */
+function perceptualLightness(r, g, b) {
+  const lin = c => Math.pow(c / 255, 2.4);
+  const y = 0.2126729 * lin(r) + 0.7151522 * lin(g) + 0.072175 * lin(b);
+  return Math.pow(y, 0.56);
+}
+
+/**
+ * Detect whether an image is predominantly dark or light.
+ *
+ * Uses OffscreenCanvas to sample the image without interrupting
+ * the main render loop. Returns null while loading.
+ */
+export function useImageMode(src, options = {}) {
+  const {
+    region,
+    threshold = 0.5,
+    fallback = null
+  } = options;
+  const [detectedResult, setDetectedResult] = useState(null);
+  useEffect(() => {
+    if (!src) {
+      return;
+    }
+    const srcUrl = src;
+    let cancelled = false;
+    async function detect() {
+      try {
+        // Load image as bitmap (async, doesn't block rendering)
+        const response = await fetch(srcUrl, {
+          mode: 'cors'
+        });
+        const blob = await response.blob();
+        const bitmap = await createImageBitmap(blob);
+        if (cancelled) {
+          return;
+        }
+
+        // Determine source region
+        const sx = region ? Math.round(region.x * bitmap.width) : 0;
+        const sy = region ? Math.round(region.y * bitmap.height) : 0;
+        const sw = region ? Math.round(region.width * bitmap.width) : bitmap.width;
+        const sh = region ? Math.round(region.height * bitmap.height) : bitmap.height;
+
+        // Sample at a small size and average all pixels manually.
+        // OffscreenCanvas 1×1 drawImage can produce inaccurate results
+        // depending on the browser's resampling algorithm.
+        const sampleSize = 10;
+        const canvas = new OffscreenCanvas(sampleSize, sampleSize);
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+          return;
+        }
+        ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, sampleSize, sampleSize);
+        const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize).data;
+
+        // Average all sampled pixels
+        let totalR = 0,
+          totalG = 0,
+          totalB = 0;
+        const pixelCount = sampleSize * sampleSize;
+        for (let i = 0; i < imageData.length; i += 4) {
+          totalR += imageData[i];
+          totalG += imageData[i + 1];
+          totalB += imageData[i + 2];
+        }
+        const r = totalR / pixelCount;
+        const g = totalG / pixelCount;
+        const b = totalB / pixelCount;
+        if (cancelled) {
+          return;
+        }
+        const lightness = perceptualLightness(r, g, b);
+        setDetectedResult({
+          src: srcUrl,
+          mode: lightness > threshold ? 'light' : 'dark'
+        });
+      } catch {
+        // CORS error, network error, etc. — keep fallback
+        if (!cancelled) {
+          setDetectedResult({
+            src: srcUrl,
+            mode: fallback
+          });
+        }
+      }
+    }
+    void detect();
+    return () => {
+      cancelled = true;
+    };
+  }, [src, region, threshold, fallback]);
+  if (!src || detectedResult?.src !== src) {
+    return fallback;
+  }
+  return detectedResult.mode;
+}

package/dist/hooks/useInputContainer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file useInputContainer.ts
+ * @input Container ref, input ref
+ * @output onClick and onMouseUp handlers for the input container wrapper
+ * @position Hook for input wrapper containers that delegate focus to the inner input/textarea
+ *
+ * Uses useClickableContainer to safely handle nested interactive elements
+ * (clear buttons, calendar toggles, etc.) while focusing the input when
+ * clicking non-interactive areas (icons, padding, status indicators).
+ */
+import { type RefObject } from 'react';
+export interface UseInputContainerOptions {
+    /** Ref to the outer container/wrapper element */
+    containerRef: RefObject<HTMLElement | null>;
+    /** Ref to the inner input or textarea element */
+    inputRef: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLElement | null>;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+}
+/**
+ * Hook that makes an input container wrapper clickable, delegating focus
+ * to the inner input/textarea when the user clicks non-interactive areas
+ * (icons, padding, status indicators).
+ *
+ * Nested interactive elements (clear buttons, links) are handled safely
+ * via useClickableContainer — clicking them does NOT steal focus.
+ *
+ * @compositionHint Use inside input wrapper components (TextInput,
+ * NumberInput, TimeInput, TextArea, etc.).
+ *
+ * @example
+ * ```
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const inputRef = useRef<HTMLInputElement>(null);
+ * const { onClick, onMouseUp } = useInputContainer({
+ *   containerRef,
+ *   inputRef,
+ * });
+ * return (
+ *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *     <Icon icon="search" />
+ *     <input ref={inputRef} />
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useInputContainer({ containerRef, inputRef, disabled, }: UseInputContainerOptions): import("./useClickableContainer").ClickableContainerResult;
+//# sourceMappingURL=useInputContainer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useInputContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAsBlD,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,iDAAiD;IACjD,QAAQ,EAAE,SAAS,CACjB,gBAAgB,GAAG,mBAAmB,GAAG,WAAW,GAAG,IAAI,CAC5D,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,EACZ,QAAQ,EACR,QAAgB,GACjB,EAAE,wBAAwB,8DA0B1B"}

package/dist/hooks/useInputContainer.js

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useInputContainer.ts
+ * @input Container ref, input ref
+ * @output onClick and onMouseUp handlers for the input container wrapper
+ * @position Hook for input wrapper containers that delegate focus to the inner input/textarea
+ *
+ * Uses useClickableContainer to safely handle nested interactive elements
+ * (clear buttons, calendar toggles, etc.) while focusing the input when
+ * clicking non-interactive areas (icons, padding, status indicators).
+ */
+import { useCallback } from 'react';
+import { useClickableContainer } from "./useClickableContainer.js";
+
+/**
+ * Input types that should receive `.focus()` when the container is clicked.
+ * Other input types (e.g. checkbox, radio, file) use `.click()` instead.
+ */
+const FOCUS_INPUT_TYPES = new Set(['text', 'password', 'email', 'number', 'search', 'tel', 'url', 'date', 'datetime-local', 'month', 'time', 'week']);
+/**
+ * Hook that makes an input container wrapper clickable, delegating focus
+ * to the inner input/textarea when the user clicks non-interactive areas
+ * (icons, padding, status indicators).
+ *
+ * Nested interactive elements (clear buttons, links) are handled safely
+ * via useClickableContainer — clicking them does NOT steal focus.
+ *
+ * @compositionHint Use inside input wrapper components (TextInput,
+ * NumberInput, TimeInput, TextArea, etc.).
+ *
+ * @example
+ * ```
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const inputRef = useRef<HTMLInputElement>(null);
+ * const { onClick, onMouseUp } = useInputContainer({
+ *   containerRef,
+ *   inputRef,
+ * });
+ * return (
+ *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *     <Icon icon="search" />
+ *     <input ref={inputRef} />
+ *   </div>
+ * );
+ * ```
+ */
+export function useInputContainer({
+  containerRef,
+  inputRef,
+  disabled = false
+}) {
+  const onClick = useCallback(() => {
+    const input = inputRef.current;
+    if (input == null) {
+      return;
+    }
+    if (input instanceof HTMLInputElement && FOCUS_INPUT_TYPES.has(input.type)) {
+      input.focus();
+    } else if (input instanceof HTMLTextAreaElement) {
+      input.focus();
+    } else if (input instanceof HTMLElement) {
+      input.click();
+    } else if ('focus' in input) {
+      input.focus();
+    }
+  }, [inputRef]);
+  return useClickableContainer({
+    containerRef,
+    interactiveRef: inputRef,
+    onClick,
+    disabled
+  });
+}

package/dist/hooks/useInputStatusIcon.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import { type IconSize } from '../Icon';
+import type { FieldStatusVariant } from '../FieldStatus/FieldStatus';
+import type { InputStatus } from '../Field/types';
+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 declare function useInputStatusIcon({ status, statusVariant, isInGroup, size, }: UseInputStatusIconOptions): UseInputStatusIconReturn;
+//# sourceMappingURL=useInputStatusIcon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAsB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAsDjE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CA2FtD"}

package/dist/hooks/useInputStatusIcon.js

@@ -0,0 +1,158 @@
+// 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 * as stylex from '@stylexjs/stylex';
+import { Icon } from "../Icon/index.js";
+import { useTooltip } from "../Tooltip/index.js";
+import { useTranslator } from "../i18n/index.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, radiusVars } from "../theme/tokens.stylex.js";
+
+/**
+ * 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.
+ */
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const STATUS_ICON = {
+  warning: 'warning',
+  error: 'error',
+  success: 'success'
+};
+
+/**
+ * Accessible-name i18n keys for the focusable status button, keyed by type.
+ */
+const STATUS_BUTTON_LABEL_KEY = {
+  warning: '@pharos.input.statusButton.warning',
+  error: '@pharos.input.statusButton.error',
+  success: '@pharos.input.statusButton.success'
+};
+/**
+ * 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'
+}) {
+  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(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 => {
+      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 = /*#__PURE__*/_jsx(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: /*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsx("button", {
+        type: "button",
+        ref: tooltip.ref,
+        "aria-label": t(STATUS_BUTTON_LABEL_KEY[status.type]),
+        "aria-describedby": tooltip.describedBy,
+        onClick: handleButtonClick,
+        onBlur: handleButtonBlur,
+        ...{
+          className: "x3nfvp2 x6s0dn4 xl56j7k x1717udv x1ghz6dp x1heor9g x1ypdohk xjspbzw x784prv x9v5kkp xzunyri x7s97pk"
+        },
+        children: icon
+      }), tooltip.renderTooltip(status.message)]
+    }),
+    describedBy: tooltip.describedBy
+  };
+}

package/dist/hooks/useInteractiveRole.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare function useInteractiveRole({ href, onClick, isDisabled, }: UseInteractiveRoleOptions): InteractiveRole;
+//# sourceMappingURL=useInteractiveRole.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useInteractiveRole.d.ts","sourceRoot":"","sources":["../../src/hooks/useInteractiveRole.ts"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEjD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,OAAO,EACP,UAAkB,GACnB,EAAE,yBAAyB,GAAG,eAAe,CAqB7C"}

package/dist/hooks/useInteractiveRole.js

@@ -0,0 +1,84 @@
+// 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.js";
+
+/**
+ * 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)
+ */
+
+/**
+ * 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
+}) {
+  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/dist/hooks/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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 } from 'react';
+export declare const useIsomorphicLayoutEffect: typeof useEffect;
+//# sourceMappingURL=useIsomorphicLayoutEffect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useIsomorphicLayoutEffect.d.ts","sourceRoot":"","sources":["../../src/hooks/useIsomorphicLayoutEffect.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,SAAS,EAAkB,MAAM,OAAO,CAAC;AAEjD,eAAO,MAAM,yBAAyB,kBACuB,CAAC"}

package/dist/hooks/useIsomorphicLayoutEffect.js

@@ -0,0 +1,19 @@
+// 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;