@pharos-ds/core 0.1.9

package/dist/Heading/Heading.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @file Heading.tsx
+ * @input Uses React, HTMLAttributes, ReactNode
+ * @output Exports Heading component, HeadingProps, HeadingLevel types
+ * @position Core implementation; lives in own Heading/ dir, re-exported by Text/
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Heading/Heading.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Text/index.ts (exports if types change)
+ * - /apps/storybook/stories/Text.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/Heading/ (showcase blocks)
+ * - /packages/cli/templates/blocks/components/Text/ (showcase blocks)
+ */
+import { type ReactNode } from 'react';
+import type { TextColor, TextDisplay, TextJustify, WordBreak, TextWrap } from '../theme/types';
+import type { LayerPlacement } from '../Layer';
+import type { BaseProps } from '../BaseProps';
+/**
+ * Heading level (1-6). Determines both visual styling and semantic HTML element.
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Display type variants for headings. Applies display-scale sizing
+ * (larger, lighter) while preserving the semantic heading element.
+ */
+export type HeadingType = 'display-1' | 'display-2' | 'display-3';
+export interface HeadingProps extends Omit<BaseProps<HTMLHeadingElement>, 'children'> {
+    /** Ref forwarded to the root element */
+    ref?: React.Ref<HTMLHeadingElement>;
+    /**
+     * Heading level (1-6). Determines the semantic HTML element (h1–h6).
+     * Also determines visual styling unless `type` is set.
+     */
+    level: HeadingLevel;
+    /**
+     * Display type variant. When set, overrides the visual styling from `level`
+     * with display-scale sizing (larger, lighter weight, tighter line-height).
+     * The `level` still determines the HTML element for accessibility.
+     *
+     * Use for hero banners, marketing headlines, and data callouts that need
+     * heading semantics.
+     *
+     * @example
+     * ```
+     * <Heading level={1} type="display-1">Hero Title</Heading>
+     * <Heading level={2} type="display-2">$1.2M Revenue</Heading>
+     * ```
+     */
+    type?: HeadingType;
+    /**
+     * Accessibility level override. When set, the `aria-level` will differ
+     * from the visual `level`. Use this when the visual hierarchy doesn't
+     * match the document outline (e.g., sidebar headings, reused components).
+     *
+     * @default Same as `level`
+     *
+     * @example
+     * ```
+     * <Heading level={2} accessibilityLevel={3}>Sidebar Section</Heading>
+     * ```
+     */
+    accessibilityLevel?: HeadingLevel;
+    /**
+     * Text color.
+     * @default 'primary'
+     */
+    color?: TextColor;
+    /**
+     * Display type. Headings default to block.
+     * Note: Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.
+     * @default 'block'
+     */
+    display?: TextDisplay;
+    /**
+     * Maximum lines before truncation. 0 = no truncation.
+     * When set, shows tooltip on hover if content is truncated.
+     * @default 0
+     */
+    maxLines?: number;
+    /**
+     * Control tooltip behavior for truncated text.
+     * - `true` (default when maxLines > 0): show tooltip at default position
+     * - `false`: disable tooltip
+     * - Position value: show tooltip at specific position
+     * @default true
+     */
+    hasTruncateTooltip?: boolean | LayerPlacement;
+    /**
+     * Word break behavior for truncated text.
+     * @default 'break-all' for maxLines=1, 'break-word' otherwise
+     */
+    wordBreak?: WordBreak;
+    /**
+     * Text wrapping behavior.
+     */
+    textWrap?: TextWrap;
+    /**
+     * Text alignment (justification). Uses logical values (start/end)
+     * for i18n/RTL compatibility.
+     * @default 'start'
+     */
+    justify?: TextJustify;
+    /**
+     * Enable optical alignment (text-box-trim).
+     * Forces block display.
+     * @default false
+     */
+    hasCapsize?: boolean;
+    /**
+     * Strikethrough decoration.
+     * @default false
+     */
+    hasStrikethrough?: boolean;
+    /**
+     * Heading content
+     */
+    children: ReactNode;
+}
+/**
+ * Heading - Semantic heading component
+ *
+ * Renders headings with semantic HTML (h1-h6) and themed styling.
+ *
+ * @example
+ * ```
+ * <Heading level={1}>Page Title</Heading>
+ * <Heading level={2}>Section</Heading>
+ * <Heading level={2} accessibilityLevel={3}>Sidebar Section</Heading>
+ * <Heading level={1} type="display-1">Hero Title</Heading>
+ * <Heading level={2} type="display-2">$1.2M Revenue</Heading>
+ * <Heading level={2} maxLines={1}>Very Long Section Title...</Heading>
+ * <Heading level={3} color="secondary">Muted Heading</Heading>
+ * ```
+ */
+export declare function Heading({ level, type, accessibilityLevel, color, display, maxLines, hasTruncateTooltip, wordBreak, textWrap, justify, hasCapsize, hasStrikethrough, xstyle, className, style, children, ref, ...props }: HeadingProps): import("react").JSX.Element;
+export declare namespace Heading {
+    var displayName: string;
+}
+//# sourceMappingURL=Heading.d.ts.map

package/dist/Heading/Heading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../../src/Heading/Heading.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE7D,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAgBxB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,UAAU,CAAC;AAE7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAElE,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,CAAC,kBAAkB,CAAC,EAC7B,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACpC;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,kBAAkB,EAClB,KAAiB,EACjB,OAAiB,EACjB,QAAY,EACZ,kBAAyB,EACzB,SAAS,EACT,QAAQ,EACR,OAAiB,EACjB,UAAkB,EAClB,gBAAwB,EACxB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,YAAY,+BAmFd;yBAtGe,OAAO"}

package/dist/Heading/Heading.js

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Heading.tsx
+ * @input Uses React, HTMLAttributes, ReactNode
+ * @output Exports Heading component, HeadingProps, HeadingLevel types
+ * @position Core implementation; lives in own Heading/ dir, re-exported by Text/
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Heading/Heading.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Text/index.ts (exports if types change)
+ * - /apps/storybook/stories/Text.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/Heading/ (showcase blocks)
+ * - /packages/cli/templates/blocks/components/Text/ (showcase blocks)
+ */
+import { lazy, Suspense, useRef } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { colorStyles, sizeByLevelStyles, sizeByTypeStyles, defaultWeightByTypeStyles, displayStyles, justifyStyles, truncationStyles, wordBreakStyles, textWrapStyles, capsizeStyles, decorationStyles, truncationTooltipStyles } from "../Text/text.stylex.js";
+import { useTruncation } from "../Text/useTruncation.js";
+import { mergeProps, mergeRefs } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const LazyXDSTooltip = /*#__PURE__*/lazy(async () => import('../Tooltip/Tooltip').then(mod => ({
+  default: mod.Tooltip
+})));
+
+/**
+ * Heading level (1-6). Determines both visual styling and semantic HTML element.
+ */
+
+/**
+ * Display type variants for headings. Applies display-scale sizing
+ * (larger, lighter) while preserving the semantic heading element.
+ */
+
+const levelToTag = {
+  1: 'h1',
+  2: 'h2',
+  3: 'h3',
+  4: 'h4',
+  5: 'h5',
+  6: 'h6'
+};
+
+/**
+ * Heading - Semantic heading component
+ *
+ * Renders headings with semantic HTML (h1-h6) and themed styling.
+ *
+ * @example
+ * ```
+ * <Heading level={1}>Page Title</Heading>
+ * <Heading level={2}>Section</Heading>
+ * <Heading level={2} accessibilityLevel={3}>Sidebar Section</Heading>
+ * <Heading level={1} type="display-1">Hero Title</Heading>
+ * <Heading level={2} type="display-2">$1.2M Revenue</Heading>
+ * <Heading level={2} maxLines={1}>Very Long Section Title...</Heading>
+ * <Heading level={3} color="secondary">Muted Heading</Heading>
+ * ```
+ */
+export function Heading({
+  level,
+  type,
+  accessibilityLevel,
+  color = 'primary',
+  display = 'block',
+  maxLines = 0,
+  hasTruncateTooltip = true,
+  wordBreak,
+  textWrap,
+  justify = 'start',
+  hasCapsize = false,
+  hasStrikethrough = false,
+  xstyle,
+  className,
+  style,
+  children,
+  ref,
+  ...props
+}) {
+  const Component = levelToTag[level];
+
+  // If accessibilityLevel differs from visual level, use aria-level
+  const ariaProps = accessibilityLevel && accessibilityLevel !== level ? {
+    'aria-level': accessibilityLevel
+  } : {};
+
+  // Resolve wordBreak with smart default
+  const resolvedWordBreak = wordBreak ?? (maxLines === 1 ? 'break-all' : 'break-word');
+
+  // Resolve display - force block when maxLines > 0 or hasCapsize
+  const resolvedDisplay = maxLines > 0 || hasCapsize ? 'block' : display;
+
+  // Truncation detection
+  const truncation = useTruncation({
+    maxLines
+  });
+
+  // Tooltip for truncated text
+  const tooltipPlacement = typeof hasTruncateTooltip === 'string' ? hasTruncateTooltip : 'above';
+  const tooltipEnabled = maxLines > 0 && hasTruncateTooltip !== false && truncation.isTruncated;
+
+  // Ref for the heading element (used as tooltip anchor)
+  const headingRef = useRef(null);
+
+  // Build inline style for -webkit-line-clamp (dynamic value)
+  const inlineStyle = maxLines > 1 ? {
+    WebkitLineClamp: maxLines
+  } : undefined;
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Component, {
+      ref: mergeRefs(ref, truncation.ref, headingRef),
+      ...mergeProps(themeProps('heading', {
+        level,
+        color,
+        ...(type && {
+          type
+        })
+      }), stylex.props(colorStyles[color], type ? sizeByTypeStyles[type] : sizeByLevelStyles[level], type && defaultWeightByTypeStyles[type],
+      // Display: use truncation styles when maxLines > 0
+      maxLines === 1 ? truncationStyles.singleLine : maxLines > 1 ? truncationStyles.multiLine : displayStyles[resolvedDisplay],
+      // Word break when truncating
+      maxLines > 0 && wordBreakStyles[resolvedWordBreak],
+      // Text wrap
+      textWrap && textWrapStyles[textWrap],
+      // Justify (text alignment)
+      justify !== 'start' && justifyStyles[justify],
+      // Capsize
+      hasCapsize && capsizeStyles.enabled,
+      // Decorations
+      hasStrikethrough && decorationStyles.strikethrough,
+      // User xstyle
+      xstyle), className, {
+        ...style,
+        ...inlineStyle
+      }),
+      title: tooltipEnabled ? truncation.fullText : undefined,
+      ...ariaProps,
+      ...props,
+      children: children
+    }), tooltipEnabled && /*#__PURE__*/_jsx(Suspense, {
+      fallback: null,
+      children: /*#__PURE__*/_jsx(LazyXDSTooltip, {
+        anchorRef: headingRef,
+        content: /*#__PURE__*/_jsx("span", {
+          ...stylex.props(truncationTooltipStyles.content),
+          children: truncation.fullText
+        }),
+        placement: tooltipPlacement
+      })
+    })]
+  });
+}
+Heading.displayName = 'Heading';

package/dist/Heading/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file index.ts
+ * @input Heading component source
+ * @output Exports Heading and its props/types
+ * @position Entry point for @pharos-ds/core/Heading subpath export
+ */
+export { Heading, type HeadingProps, type HeadingLevel, type HeadingType, } from './Heading';
+//# sourceMappingURL=index.d.ts.map

package/dist/Heading/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Heading/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EACL,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC"}

package/dist/Heading/index.js

@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Heading component source
+ * @output Exports Heading and its props/types
+ * @position Entry point for @pharos-ds/core/Heading subpath export
+ */
+
+export { Heading } from "./Heading.js";

package/dist/HoverCard/HoverCard.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @file HoverCard.tsx
+ * @input Uses React, useHoverCard hook
+ * @output Exports HoverCard component for hover/focus triggered layers
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/HoverCard/HoverCard.test.tsx
+ * - /packages/core/src/HoverCard/index.ts
+ * - /apps/storybook/stories/HoverCard.stories.tsx
+ * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
+ */
+import { type ReactElement, type ReactNode } from 'react';
+import { type HoverCardFocusTrigger } from './useHoverCard';
+import type { LayerAlignment, LayerPlacement } from '../Layer/useLayer';
+import type { BaseProps } from '../BaseProps';
+export type { HoverCardFocusTrigger } from './useHoverCard';
+export interface HoverCardProps extends Pick<BaseProps, 'xstyle' | 'className' | 'style'> {
+    /**
+     * The trigger element(s). Children refs are preserved.
+     */
+    children: ReactNode;
+    /**
+     * Content to display in the hover card.
+     */
+    content: ReactNode;
+    /**
+     * Position placement relative to anchor
+     * @default 'above'
+     */
+    placement?: LayerPlacement;
+    /**
+     * Alignment along the placement axis
+     * @default 'center'
+     */
+    alignment?: LayerAlignment;
+    /**
+     * Delay before showing on hover (ms)
+     * @default 300
+     */
+    delay?: number;
+    /**
+     * Delay before hiding after mouse/focus leave (ms)
+     * @default 200
+     */
+    hideDelay?: number;
+    /**
+     * When to trigger on focus:
+     * - `auto`: Only if element is naturally focusable
+     * - `always`: Always attach focus listeners
+     * - `never`: Never attach focus listeners (for composite widgets)
+     *
+     * @default 'auto'
+     */
+    focusTrigger?: HoverCardFocusTrigger;
+    /**
+     * Whether the hover card is enabled.
+     * When false, hover/focus triggers are disabled.
+     *
+     * @default true
+     */
+    isEnabled?: boolean;
+    /**
+     * Accessible name for the hover card popup.
+     *
+     * When provided, the popup is exposed to assistive technology as a named
+     * `role="dialog"`. When omitted, the popup falls back to `role="group"` —
+     * a group may validly be unnamed, an unnamed dialog may not.
+     */
+    label?: string;
+    /**
+     * Callback fired when hover card visibility changes.
+     * Called with `true` when shown and `false` when hidden.
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Whether to show hover indication (dashed underline) on the trigger.
+     * - `'auto'`: Show for text-only children
+     * - `true`: Always show
+     * - `false`: Never show
+     *
+     * @default 'auto'
+     */
+    hasHoverIndication?: 'auto' | boolean;
+    /**
+     * Controlled open state. When provided, overrides hover/focus triggers:
+     * - `true`: force-show the hover card (hover/focus hide is suppressed)
+     * - `false`: force-hide the hover card
+     * - `undefined`: uncontrolled — hover/focus triggers manage visibility
+     */
+    isOpen?: boolean;
+    /**
+     * Whether the hover card should be shown on mount.
+     * The hover card is still dismissible — this just opens it initially.
+     */
+    isDefaultOpen?: boolean;
+}
+/**
+ * HoverCard component for displaying interactive content on hover/focus.
+ *
+ * Uses a display:contents wrapper so children refs are preserved.
+ * Uses CSS anchor positioning and the Popover API for optimal performance.
+ *
+ * @example
+ * ```
+ * <HoverCard
+ *   content={<ProfileCard user={user} />}
+ *   placement="above">
+ *   <Button>Hover me</Button>
+ * </HoverCard>
+ * ```
+ */
+export declare function HoverCard({ children, content, placement, alignment, delay, hideDelay, focusTrigger, isEnabled, label, onOpenChange, hasHoverIndication, isOpen, isDefaultOpen, xstyle, className, style, }: HoverCardProps): ReactElement;
+export declare namespace HoverCard {
+    var displayName: string;
+}
+//# sourceMappingURL=HoverCard.d.ts.map

package/dist/HoverCard/HoverCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7E,OAAO,EAAe,KAAK,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EAAC,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AAiB1D,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAiH/B;yBAlIe,SAAS"}

package/dist/HoverCard/HoverCard.js

@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file HoverCard.tsx
+ * @input Uses React, useHoverCard hook
+ * @output Exports HoverCard component for hover/focus triggered layers
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/HoverCard/HoverCard.test.tsx
+ * - /packages/core/src/HoverCard/index.ts
+ * - /apps/storybook/stories/HoverCard.stories.tsx
+ * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
+ */
+import { useCallback, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import * as stylex from '@stylexjs/stylex';
+import { useHoverCard } from "./useHoverCard.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars } from "../theme/tokens.stylex.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Check if children are text-only (no React elements)
+ */
+function isTextOnly(children) {
+  return typeof children === 'string' || typeof children === 'number';
+}
+
+/**
+ * Utility to merge ARIA ID strings
+ */
+function mergeIds(...ids) {
+  const filtered = ids.filter(Boolean);
+  return filtered.length > 0 ? filtered.join(' ') : undefined;
+}
+
+/**
+ * HoverCard component for displaying interactive content on hover/focus.
+ *
+ * Uses a display:contents wrapper so children refs are preserved.
+ * Uses CSS anchor positioning and the Popover API for optimal performance.
+ *
+ * @example
+ * ```
+ * <HoverCard
+ *   content={<ProfileCard user={user} />}
+ *   placement="above">
+ *   <Button>Hover me</Button>
+ * </HoverCard>
+ * ```
+ */
+export function HoverCard({
+  children,
+  content,
+  placement = 'above',
+  alignment = 'center',
+  delay = 300,
+  hideDelay = 200,
+  focusTrigger = 'auto',
+  isEnabled = true,
+  label,
+  onOpenChange,
+  hasHoverIndication = 'auto',
+  isOpen,
+  isDefaultOpen,
+  xstyle,
+  className,
+  style
+}) {
+  const wrapperRef = useRef(null);
+  const textOnly = isTextOnly(children);
+
+  // Determine if hover indication should be shown
+  const showHoverIndication = hasHoverIndication === true || hasHoverIndication === 'auto' && textOnly;
+  const handleShow = useCallback(() => {
+    onOpenChange?.(true);
+  }, [onOpenChange]);
+  const handleHide = useCallback(() => {
+    onOpenChange?.(false);
+  }, [onOpenChange]);
+
+  // Use the hook for all hover card behavior
+  const hoverCard = useHoverCard({
+    placement,
+    alignment,
+    delay,
+    hideDelay,
+    focusTrigger,
+    isEnabled,
+    label,
+    isOpen,
+    isDefaultOpen,
+    onShow: handleShow,
+    onHide: handleHide
+  });
+
+  // For element children with display:contents, attach ref to first child
+  useIsomorphicLayoutEffect(() => {
+    if (textOnly) {
+      return;
+    } // Skip for text-only (ref is on wrapper)
+
+    const wrapper = wrapperRef.current;
+    if (!wrapper) {
+      return;
+    }
+    const firstChild = wrapper.firstElementChild;
+    if (!firstChild) {
+      return;
+    }
+
+    // Use combined ref for position + interaction
+    hoverCard.ref(firstChild);
+
+    // Set aria-describedby, merging with existing
+    const existingDescribedBy = firstChild.getAttribute('aria-describedby');
+    firstChild.setAttribute('aria-describedby', mergeIds(existingDescribedBy, hoverCard.describedBy) ?? '');
+    return () => {
+      hoverCard.ref(null);
+      if (existingDescribedBy) {
+        firstChild.setAttribute('aria-describedby', existingDescribedBy);
+      } else {
+        firstChild.removeAttribute('aria-describedby');
+      }
+    };
+  }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
+
+  // Render the floating layer inline, in the same place on the server and the
+  // client. The layer is a `popover` element opened via the Popover API, so the
+  // browser promotes it to the top layer when shown — that already escapes
+  // ancestor clipping, stacking, and transform containing-block traps, and CSS
+  // anchor positioning resolves the trigger reference regardless of where the
+  // element sits in the DOM, so no portal is needed to "escape" layout.
+  //
+  // The layer renders as inline-safe phrasing markup (a `<span>`, see
+  // useHoverCard), which stays put inside a `<p>` instead of being reparented
+  // by the HTML parser. That keeps the server markup and the first client
+  // render identical, so there is no hydration mismatch — and it preserves the
+  // inline-safety guarantee (no block elements injected into a paragraph).
+  const renderedHoverCard = hoverCard.renderHoverCard(content, {
+    xstyle,
+    className,
+    style
+  });
+
+  // For text-only children: use inline span with ref on wrapper
+  if (textOnly) {
+    return /*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsx("span", {
+        ref: hoverCard.ref,
+        tabIndex: 0,
+        "aria-describedby": hoverCard.describedBy,
+        ...{
+          0: {
+            className: "xt0psk2"
+          },
+          1: {
+            className: "xt0psk2 xujl8zx xev0dqp xycaml9 x11b3rvo"
+          }
+        }[!!showHoverIndication << 0],
+        children: children
+      }), renderedHoverCard]
+    });
+  }
+
+  // For element children: use inline-safe display:contents, ref on first child
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx("span", {
+      ref: wrapperRef,
+      ...{
+        className: "xjp7ctv"
+      },
+      children: children
+    }), renderedHoverCard]
+  });
+}
+HoverCard.displayName = 'HoverCard';

package/dist/HoverCard/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file index.ts
+ * @input HoverCard component and hook
+ * @output Exports all HoverCard module public API
+ * @position Entry point for HoverCard module
+ *
+ * SYNC: When adding new HoverCard files, update exports here
+ */
+export { useHoverCard } from './useHoverCard';
+export type { HoverCardFocusTrigger, HoverCardOptions, HoverCardReturn, } from './useHoverCard';
+export { HoverCard } from './HoverCard';
+export type { HoverCardProps } from './HoverCard';
+//# sourceMappingURL=index.d.ts.map

package/dist/HoverCard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/HoverCard/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAGH,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,YAAY,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC"}

package/dist/HoverCard/index.js

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input HoverCard component and hook
+ * @output Exports all HoverCard module public API
+ * @position Entry point for HoverCard module
+ *
+ * SYNC: When adding new HoverCard files, update exports here
+ */
+
+// HoverCard hook
+export { useHoverCard } from "./useHoverCard.js";
+// HoverCard component
+export { HoverCard } from "./HoverCard.js";