An open source design system that's fully customizable and agent ready
TypeScript
feat: XDSOverlay — scrim + media theme overlay with CSS-first hover and touch support (#1912)
Cindy Zhang284dc38f27d1
diff --git a/apps/storybook/stories/Overlay.stories.tsx b/apps/storybook/stories/Overlay.stories.tsxnew file mode 100644index 0000000000..fb5765f5b2--- /dev/null+++ b/apps/storybook/stories/Overlay.stories.tsx@@ -0,0 +1,351 @@+import type {Meta, StoryObj} from '@storybook/react';+import React, {useState} from 'react';+import * as stylex from '@stylexjs/stylex';+import {XDSOverlay, useXDSOverlay} from '@xds/core/Overlay';+import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSCard} from '@xds/core/Card';+import {XDSButton} from '@xds/core/Button';+import {XDSHeading, XDSText} from '@xds/core/Text';+import {XDSVStack, XDSLayout, XDSLayoutContent} from '@xds/core/Layout';+import {XDSSpinner} from '@xds/core/Spinner';+import {XDSGrid} from '@xds/core/Grid';+import {+ colorVars,+ spacingVars,+ typographyVars,+} from '@xds/core/theme/tokens.stylex';++const styles = stylex.create({+ pageWrapper: {+ backgroundColor: colorVars['--color-background-body'],+ padding: spacingVars['--spacing-6'],+ },+ image: {+ objectFit: 'cover',+ width: '100%',+ height: '100%',+ display: 'block',+ },+ dropZone: {+ minHeight: 200,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ borderWidth: 2,+ borderStyle: 'dashed',+ borderColor: colorVars['--color-border'],+ borderRadius: 8,+ padding: spacingVars['--spacing-4'],+ },+ dropZoneText: {+ fontFamily: typographyVars['--font-family-body'],+ color: colorVars['--color-text-secondary'],+ },+ durationBadge: {+ paddingBlock: 2,+ paddingInline: 8,+ borderRadius: 4,+ backgroundColor: colorVars['--color-overlay'],+ fontSize: 12,+ fontWeight: 600,+ },+ imageSection: {+ position: 'relative',+ },+ metadata: {+ padding: 16,+ },+});++const SAMPLE_IMAGE = 'https://picsum.photos/seed/xds-overlay/800/450';+const SAMPLE_IMAGE_2 = 'https://picsum.photos/seed/xds-overlay-2/800/450';+const SAMPLE_IMAGE_3 = 'https://picsum.photos/seed/xds-overlay-3/800/450';+const SAMPLE_HERO = 'https://picsum.photos/seed/xds-hero/1200/600';++const meta: Meta<typeof XDSOverlay> = {+ title: 'Core/Overlay',+ component: XDSOverlay,+ tags: ['autodocs'],+ decorators: [+ Story => (+ <div {...stylex.props(styles.pageWrapper)}>+ <Story />+ </div>+ ),+ ],+};++export default meta;+type Story = StoryObj<typeof XDSOverlay>;++/** Basic hover overlay on an image. */+export const HoverOnImage: Story = {+ render: () => (+ <div style={{width: 400}}>+ <XDSOverlay+ showOn="hover"+ align="center"+ content={<XDSButton label="Quick view" variant="ghost" />}>+ <XDSAspectRatio ratio={16 / 9}>+ <img+ src={SAMPLE_IMAGE}+ alt="Product"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ </div>+ ),+};++/** Always-visible bottom strip with title over a hero image. */+export const BottomStrip: Story = {+ render: () => (+ <div style={{width: 600}}>+ <XDSOverlay+ position="bottom"+ align="start"+ content={+ <XDSVStack gap={1}>+ <XDSHeading level={3}>Gallery Collection</XDSHeading>+ <XDSText type="supporting" color="secondary">+ 24 items · Updated today+ </XDSText>+ </XDSVStack>+ }>+ <XDSAspectRatio ratio={2}>+ <img src={SAMPLE_HERO} alt="Hero" {...stylex.props(styles.image)} />+ </XDSAspectRatio>+ </XDSOverlay>+ </div>+ ),+};++/** Full overlay wrapping a Card. */+export const CardOverlay: Story = {+ render: () => (+ <XDSOverlay+ showOn="hover"+ align="center"+ content={<XDSButton label="View Details" variant="ghost" />}>+ <XDSCard width={360}>+ <XDSLayout+ content={+ <XDSLayoutContent>+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Project Alpha</XDSHeading>+ <XDSText>+ A comprehensive design system for building internal tools with+ consistent, accessible interfaces.+ </XDSText>+ <XDSText type="supporting" color="secondary">+ Updated 2 hours ago · 12 contributors+ </XDSText>+ </XDSVStack>+ </XDSLayoutContent>+ }+ />+ </XDSCard>+ </XDSOverlay>+ ),+};++/** Hover + focus — also appears on keyboard focus. */+export const HoverOrFocus: Story = {+ render: () => (+ <div style={{width: 400}}>+ <XDSOverlay+ showOn="hover-or-focus"+ align="center"+ content={<XDSButton label="Edit" variant="ghost" />}>+ <XDSAspectRatio ratio={16 / 9}>+ <img+ src={SAMPLE_IMAGE_2}+ alt="Photo"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ </div>+ ),+};++/** Light scrim for loading/upload states. */+export const LoadingOverlay: Story = {+ render: function LoadingOverlayStory() {+ const [isUploading, setIsUploading] = useState(false);+ return (+ <XDSVStack gap={4} style={{width: 300}}>+ <XDSButton+ label={isUploading ? 'Cancel upload' : 'Simulate upload'}+ onClick={() => setIsUploading(v => !v)}+ />+ <XDSOverlay+ isOpen={isUploading}+ scrim="light"+ align="center"+ content={+ <XDSVStack gap={2} hAlign="center">+ <XDSSpinner size="md" />+ <XDSText weight="bold">Uploading...</XDSText>+ </XDSVStack>+ }>+ <XDSAspectRatio ratio={1}>+ <img+ src={SAMPLE_IMAGE_3}+ alt="Upload"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ </XDSVStack>+ );+ },+};++/** Gallery grid — each image has its own hover overlay. */+export const GalleryGrid: Story = {+ render: () => {+ const images = [+ {src: 'https://picsum.photos/seed/g1/400/400', title: 'Mountain Lake'},+ {src: 'https://picsum.photos/seed/g2/400/400', title: 'Forest Path'},+ {src: 'https://picsum.photos/seed/g3/400/400', title: 'Ocean Sunset'},+ {src: 'https://picsum.photos/seed/g4/400/400', title: 'City Skyline'},+ {src: 'https://picsum.photos/seed/g5/400/400', title: 'Desert Dunes'},+ {src: 'https://picsum.photos/seed/g6/400/400', title: 'Snowy Peaks'},+ ];+ return (+ <XDSGrid columns={3} gap={4}>+ {images.map(img => (+ <XDSOverlay+ key={img.title}+ showOn="hover"+ position="bottom"+ align="start"+ content={<XDSText weight="bold">{img.title}</XDSText>}>+ <XDSAspectRatio ratio={1}>+ <img+ src={img.src}+ alt={img.title}+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ ))}+ </XDSGrid>+ );+ },+};++/** Video thumbnail with duration badge (always visible) + hover play overlay. */+export const VideoThumbnail: Story = {+ render: () => (+ <div style={{width: 400}}>+ <XDSOverlay+ showOn="hover"+ align="center"+ content={+ <XDSVStack gap={2} hAlign="center">+ <XDSText weight="bold" size="lg">+ ▶+ </XDSText>+ <XDSText weight="bold">Introduction to XDS</XDSText>+ </XDSVStack>+ }>+ <XDSAspectRatio ratio={16 / 9}>+ <img src={SAMPLE_IMAGE} alt="Video" {...stylex.props(styles.image)} />+ </XDSAspectRatio>+ </XDSOverlay>+ </div>+ ),+};++/** Disconnected hover — useXDSOverlay hook on Card. Hover Card reveals overlay on image. */+export const DisconnectedHover: Story = {+ render: function DisconnectedHoverStory() {+ const overlay = useXDSOverlay({+ showOn: 'hover',+ position: 'bottom',+ align: 'start',+ content: <XDSHeading level={4}>Featured Article</XDSHeading>,+ });++ return (+ <XDSCard+ width={360}+ ref={overlay.containerRef as React.RefObject<HTMLDivElement>}+ {...overlay.containerProps}>+ <div {...stylex.props(styles.imageSection)}>+ <XDSAspectRatio ratio={16 / 9}>+ <img+ src={SAMPLE_IMAGE_2}+ alt="Article"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ {overlay.element}+ </div>+ <XDSVStack gap={1} xstyle={styles.metadata}>+ <XDSText type="supporting" color="secondary">+ Jan 15, 2026 · 5 min read+ </XDSText>+ <XDSText type="supporting" color="secondary">+ By Jane Author+ </XDSText>+ </XDSVStack>+ </XDSCard>+ );+ },+};++/** Drag-and-drop overlay — simulated with a toggle button. */+export const DragAndDrop: Story = {+ render: function DragAndDropStory() {+ const [isDragOver, setIsDragOver] = useState(false);+ return (+ <XDSVStack gap={4} style={{width: 400}}>+ <XDSButton+ label={isDragOver ? 'Simulate drag leave' : 'Simulate drag enter'}+ variant="secondary"+ onClick={() => setIsDragOver(v => !v)}+ />+ <XDSOverlay+ isOpen={isDragOver}+ align="center"+ content={+ <XDSVStack gap={2} hAlign="center">+ <XDSText size="lg">📁</XDSText>+ <XDSText weight="bold">Drop files here</XDSText>+ </XDSVStack>+ }>+ <div {...stylex.props(styles.dropZone)}>+ <p {...stylex.props(styles.dropZoneText)}>+ Drop files here or click to browse+ </p>+ </div>+ </XDSOverlay>+ </XDSVStack>+ );+ },+};++/** No scrim — content-only overlay without a background. */+export const NoScrim: Story = {+ render: () => (+ <div style={{width: 300}}>+ <XDSOverlay+ showOn="hover"+ scrim={false}+ align="center"+ content={<XDSButton label="♡" variant="ghost" />}>+ <XDSAspectRatio ratio={1}>+ <img+ src={SAMPLE_IMAGE_3}+ alt="Selected"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ </div>+ ),+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 97facac3fa..2e5c84184d 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -330,6 +330,12 @@"import": "./dist/OverflowList/index.mjs","require": "./dist/OverflowList/index.js"},+ "./Overlay": {+ "source": "./src/Overlay/index.ts",+ "types": "./dist/Overlay/index.d.ts",+ "import": "./dist/Overlay/index.mjs",+ "require": "./dist/Overlay/index.js"+ },"./Pagination": {"source": "./src/Pagination/index.ts","types": "./dist/Pagination/index.d.ts",diff --git a/packages/core/src/Overlay/OverlayScrim.tsx b/packages/core/src/Overlay/OverlayScrim.tsxnew file mode 100644index 0000000000..c070e402b3--- /dev/null+++ b/packages/core/src/Overlay/OverlayScrim.tsx@@ -0,0 +1,283 @@+'use client';++/**+ * @file OverlayScrim.tsx+ * @input Scrim props (mode, position, align, visibility)+ * @output Renders the scrim div with background, media theme, transitions+ * @position Internal rendering primitive; used by XDSOverlay and useXDSOverlay+ *+ * Not exported directly — consumers use XDSOverlay (component) or+ * useXDSOverlay (hook), both of which render this internally.+ */++import {type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import {+ colorVars,+ durationVars,+ easeVars,+ spacingVars,+} from '../theme/tokens.stylex';+import {XDSMediaTheme} from '../theme/XDSMediaTheme';+import {xdsClassName, mergeProps} from '../utils';+import {overlayScope} from './overlay.markers.stylex';++// =============================================================================+// Types (re-exported from index.ts for consumers)+// =============================================================================++export type OverlayScrimMode = 'dark' | 'light' | false;+export type OverlayPosition = 'fill' | 'bottom' | 'top';+export type OverlayAlign = 'start' | 'center' | 'end';+export type OverlayShowOn = 'hover' | 'always' | 'focus' | 'hover-or-focus';++export interface OverlayScrimProps {+ scrim: OverlayScrimMode;+ position: OverlayPosition;+ align: OverlayAlign;+ showOn: OverlayShowOn;+ isOpen: boolean | undefined;+ children: ReactNode;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ base: {+ position: 'absolute',+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-2'],+ padding: spacingVars['--spacing-3'],+ pointerEvents: 'none',+ transitionProperty: 'opacity, visibility, transform',+ transitionDuration: {+ default: durationVars['--duration-fast'],+ '@media (prefers-reduced-motion: reduce)': '0s',+ },+ transitionTimingFunction: easeVars['--ease-standard'],+ },++ // Position variants+ fill: {inset: 0},+ bottom: {insetInline: 0, bottom: 0},+ top: {insetInline: 0, top: 0},++ // Alignment+ alignStart: {alignItems: 'flex-start', justifyContent: 'flex-start'},+ alignCenter: {alignItems: 'center', justifyContent: 'center'},+ alignEnd: {alignItems: 'flex-end', justifyContent: 'flex-start'},++ // Scrim backgrounds+ scrimDark: {backgroundColor: colorVars['--color-overlay']},+ // TODO: Replace with --color-overlay-light token when added+ scrimLight: {backgroundColor: 'color-mix(in srgb, white 60%, transparent)'},++ // Hidden: strips slide out, fill fades+ hidden: {opacity: 0, visibility: 'hidden'},+ hiddenBottom: {transform: 'translateY(100%)'},+ hiddenTop: {transform: 'translateY(-100%)'},++ // Visible+ visible: {+ opacity: 1,+ visibility: 'visible',+ pointerEvents: 'auto',+ transform: 'translateY(0)',+ '@starting-style': {+ opacity: 0,+ },+ },++ // @starting-style for strips: slide in on mount+ visibleFromBottom: {+ '@starting-style': {+ opacity: 0,+ transform: 'translateY(100%)',+ },+ },+ visibleFromTop: {+ '@starting-style': {+ opacity: 0,+ transform: 'translateY(-100%)',+ },+ },++ // CSS-driven: ancestor hover + focus (accessible default)+ hoverReveal: {+ opacity: {+ default: 0,+ [stylex.when.ancestor(':hover', overlayScope)]: {+ '@media (hover: hover)': 1,+ },+ [stylex.when.ancestor(':focus-within', overlayScope)]: 1,+ },+ visibility: {+ default: 'hidden',+ [stylex.when.ancestor(':hover', overlayScope)]: {+ '@media (hover: hover)': 'visible',+ },+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'visible',+ },+ pointerEvents: {+ default: 'none',+ [stylex.when.ancestor(':hover', overlayScope)]: {+ '@media (hover: hover)': 'auto',+ },+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'auto',+ },+ },++ // Slide transform for strip hover reveal+ hoverRevealBottom: {+ transform: {+ default: 'translateY(100%)',+ [stylex.when.ancestor(':hover', overlayScope)]: {+ '@media (hover: hover)': 'translateY(0)',+ },+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',+ },+ },+ hoverRevealTop: {+ transform: {+ default: 'translateY(-100%)',+ [stylex.when.ancestor(':hover', overlayScope)]: {+ '@media (hover: hover)': 'translateY(0)',+ },+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',+ },+ },++ // CSS-driven: focus-within only+ focusReveal: {+ opacity: {+ default: 0,+ [stylex.when.ancestor(':focus-within', overlayScope)]: 1,+ },+ visibility: {+ default: 'hidden',+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'visible',+ },+ pointerEvents: {+ default: 'none',+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'auto',+ },+ },++ focusRevealBottom: {+ transform: {+ default: 'translateY(100%)',+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',+ },+ },+ focusRevealTop: {+ transform: {+ default: 'translateY(-100%)',+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',+ },+ },+});++const alignMap = {+ start: styles.alignStart,+ center: styles.alignCenter,+ end: styles.alignEnd,+} as const;++const positionMap = {+ fill: styles.fill,+ bottom: styles.bottom,+ top: styles.top,+} as const;++// =============================================================================+// Component (internal)+// =============================================================================++export function OverlayScrim({+ scrim,+ position,+ align,+ showOn,+ isOpen,+ children,+}: OverlayScrimProps) {+ const isHoverMode = showOn === 'hover' || showOn === 'hover-or-focus';+ const isStrip = position === 'bottom' || position === 'top';+ const isControlled = isOpen !== undefined;++ const themeMode =+ scrim === 'dark' ? 'dark' : scrim === 'light' ? 'light' : null;++ const content = themeMode ? (+ <XDSMediaTheme mode={themeMode}>{children}</XDSMediaTheme>+ ) : (+ children+ );++ return (+ <div+ {...mergeProps(+ xdsClassName('overlay-scrim', {position}),+ stylex.props(+ styles.base,+ positionMap[position],+ alignMap[align],+ scrim === 'dark' && styles.scrimDark,+ scrim === 'light' && styles.scrimLight,++ // JS-controlled visibility+ isControlled && isOpen && styles.visible,+ isControlled &&+ isOpen &&+ position === 'bottom' &&+ styles.visibleFromBottom,+ isControlled && isOpen && position === 'top' && styles.visibleFromTop,+ isControlled && !isOpen && styles.hidden,+ isControlled &&+ !isOpen &&+ position === 'bottom' &&+ styles.hiddenBottom,+ isControlled && !isOpen && position === 'top' && styles.hiddenTop,++ // showOn="always"+ !isControlled && showOn === 'always' && styles.visible,+ !isControlled &&+ showOn === 'always' &&+ position === 'bottom' &&+ styles.visibleFromBottom,+ !isControlled &&+ showOn === 'always' &&+ position === 'top' &&+ styles.visibleFromTop,++ // showOn="hover" / "hover-or-focus"+ !isControlled && isHoverMode && styles.hoverReveal,+ !isControlled &&+ isHoverMode &&+ position === 'bottom' &&+ styles.hoverRevealBottom,+ !isControlled &&+ isHoverMode &&+ position === 'top' &&+ styles.hoverRevealTop,++ // showOn="focus"+ !isControlled && showOn === 'focus' && styles.focusReveal,+ !isControlled &&+ showOn === 'focus' &&+ position === 'bottom' &&+ styles.focusRevealBottom,+ !isControlled &&+ showOn === 'focus' &&+ position === 'top' &&+ styles.focusRevealTop,+ ),+ )}+ inert={isControlled && !isOpen ? true : undefined}>+ {content}+ </div>+ );+}diff --git a/packages/core/src/Overlay/XDSOverlay.tsx b/packages/core/src/Overlay/XDSOverlay.tsxnew file mode 100644index 0000000000..ee8058bc56--- /dev/null+++ b/packages/core/src/Overlay/XDSOverlay.tsx@@ -0,0 +1,134 @@+'use client';++/**+ * @file XDSOverlay.tsx+ * @input Uses React, useXDSOverlay+ * @output Exports XDSOverlay component+ * @position Overlay system component; thin wrapper over useXDSOverlay+ *+ * Wraps content with an overlay scrim. Same pattern as XDSTooltip:+ * `children` is the base content, `content` is what appears on top.+ *+ * For applying overlay behavior to an existing container (XDSCard),+ * use the useXDSOverlay hook directly.+ */++import {type ReactNode, type Ref} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {xdsClassName, mergeProps} from '../utils';+import {useXDSOverlay} from './useXDSOverlay';+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';+import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';+import type {+ OverlayScrimMode,+ OverlayPosition,+ OverlayAlign,+ OverlayShowOn,+} from './OverlayScrim';++export interface XDSOverlayProps {+ /** Ref forwarded to the container element. */+ ref?: Ref<HTMLDivElement>;+ /** Base content (image, card, video, etc.). */+ children?: ReactNode;+ /** Content rendered inside the overlay scrim. */+ content: ReactNode;+ /** @default "always" */+ showOn?: OverlayShowOn;+ /** JS-controlled visibility override. */+ isOpen?: boolean;+ /** @default "dark" */+ scrim?: OverlayScrimMode;+ /** @default "fill" */+ position?: OverlayPosition;+ /** @default "end" */+ align?: OverlayAlign;+ /** StyleX style overrides on the container. */+ xstyle?: StyleXStyles;+ /** CSS class name(s) appended to the root element. */+ className?: string;+ /** Inline styles. */+ style?: React.CSSProperties;+}++/**+ * Overlay — renders content on top of media with a scrim background+ * and automatic theme inversion.+ *+ * `children` = base content, `content` = what appears on top.+ *+ * @compositionHint Wrap images, video, or media content.+ *+ * @example+ * ```+ * <XDSOverlay+ * showOn="hover"+ * content={<XDSButton label="Quick view" variant="ghost" />}+ * >+ * <XDSAspectRatio ratio={16/9}>+ * <img src="hero.jpg" style={{objectFit: 'cover', width: '100%', height: '100%'}} />+ * </XDSAspectRatio>+ * </XDSOverlay>+ * ```+ */+export function XDSOverlay({+ children,+ content,+ showOn,+ isOpen,+ scrim,+ position,+ align,+ xstyle,+ className,+ style,+ ref,+}: XDSOverlayProps) {+ const overlay = useXDSOverlay({+ content,+ showOn,+ isOpen,+ scrim,+ position,+ align,+ });++ // Border radius: mirror first child's radius onto the wrapper.+ // Only the component needs this — hook consumers have their own radius.+ useIsomorphicLayoutEffect(() => {+ const el = overlay.containerRef.current;+ if (!el) return;+ const firstChild = el.firstElementChild as HTMLElement | null;+ if (!firstChild) return;+ const radius = getComputedStyle(firstChild).borderRadius;+ if (radius && radius !== '0px') {+ el.style.borderRadius = radius;+ }+ }, []);++ return (+ <div+ ref={(node: HTMLDivElement | null) => {+ (+ overlay.containerRef as React.MutableRefObject<HTMLElement | null>+ ).current = node;+ if (typeof ref === 'function') ref(node);+ else if (ref != null)+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;+ }}+ {...mergeProps(+ xdsClassName('overlay'),+ stylex.props(overlayScope, overlayContainerStyles.root, xstyle),+ className,+ style,+ )}+ onClick={overlay.containerProps.onClick}+ onMouseUp={overlay.containerProps.onMouseUp}>+ {children}+ {overlay.element}+ </div>+ );+}++XDSOverlay.displayName = 'XDSOverlay';diff --git a/packages/core/src/Overlay/index.ts b/packages/core/src/Overlay/index.tsnew file mode 100644index 0000000000..d0b3928425--- /dev/null+++ b/packages/core/src/Overlay/index.ts@@ -0,0 +1,17 @@+/**+ * @file index.ts+ * @position Overlay barrel export+ */++export {XDSOverlay} from './XDSOverlay';+export type {XDSOverlayProps} from './XDSOverlay';++export {useXDSOverlay} from './useXDSOverlay';+export type {UseXDSOverlayOptions, UseXDSOverlayResult} from './useXDSOverlay';++export type {+ OverlayScrimMode,+ OverlayPosition,+ OverlayAlign,+ OverlayShowOn,+} from './OverlayScrim';diff --git a/packages/core/src/Overlay/overlay.markers.stylex.ts b/packages/core/src/Overlay/overlay.markers.stylex.tsnew file mode 100644index 0000000000..d827edbcc4--- /dev/null+++ b/packages/core/src/Overlay/overlay.markers.stylex.ts@@ -0,0 +1,24 @@+import * as stylex from '@stylexjs/stylex';++/**+ * Scoped marker for Overlay ancestor hover selectors.+ * When applied to a container, enables XDSOverlayScrim's+ * CSS-driven showOn="hover" / "focus" / "hover-or-focus" behavior.+ */+export const overlayScope: ReturnType<typeof stylex.defineMarker> =+ stylex.defineMarker();++/**+ * Container styles that pair with overlayScope.+ * Sets position: relative + overflow: clip so the scrim+ * can use position: absolute + inset: 0 correctly.+ *+ * Override individual properties by applying your own styles after:+ * stylex.props(overlayContainerStyles.root, myStyles.sticky)+ */+export const overlayContainerStyles = stylex.create({+ root: {+ position: 'relative',+ overflow: 'clip',+ },+});diff --git a/packages/core/src/Overlay/useXDSOverlay.tsx b/packages/core/src/Overlay/useXDSOverlay.tsxnew file mode 100644index 0000000000..678a12c1ff--- /dev/null+++ b/packages/core/src/Overlay/useXDSOverlay.tsx@@ -0,0 +1,241 @@+'use client';++/**+ * @file useXDSOverlay.tsx+ * @input Overlay options (showOn, scrim, position, content, etc.)+ * @output containerRef, containerProps, element, renderOverlay+ * @position Core hook for overlay system — same pattern as useXDSTooltip+ *+ * For applying overlay behavior to an existing container (XDSCard,+ * custom elements) without a wrapper. Returns props to spread on the+ * container and the scrim to render inside it.+ *+ * Handles: marker, positioning, touch toggle (via useClickableContainer),+ * and scrim rendering.+ */++import {+ type ReactNode,+ type ReactElement,+ type MouseEvent,+ useState,+ useRef,+ useCallback,+ useMemo,+ useSyncExternalStore,+} from 'react';+import * as stylex from '@stylexjs/stylex';+import {useClickableContainer} from '../hooks/useClickableContainer';+import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';+import {OverlayScrim} from './OverlayScrim';+import type {+ OverlayScrimMode,+ OverlayPosition,+ OverlayAlign,+ OverlayShowOn,+} from './OverlayScrim';++// =============================================================================+// Touch detection+// =============================================================================++function getIsTouchDevice(): boolean {+ if (typeof window === 'undefined') return false;+ return window.matchMedia('(hover: none)').matches;+}++function subscribeToHoverChange(callback: () => void): () => void {+ if (typeof window === 'undefined') return () => {};+ const mql = window.matchMedia('(hover: none)');+ mql.addEventListener('change', callback);+ return () => mql.removeEventListener('change', callback);+}++function getServerSnapshot(): boolean {+ return false;+}++// =============================================================================+// Types+// =============================================================================++export interface UseXDSOverlayOptions {+ /** Content rendered inside the scrim overlay. */+ content?: ReactNode;++ /**+ * CSS-driven visibility trigger.+ * - `"always"` — always visible+ * - `"hover"` — hover + focus (accessible default). Touch: strip = always visible, fill = tap-to-toggle.+ * - `"focus"` — focus-within only+ * - `"hover-or-focus"` — alias for "hover"+ * @default "always"+ */+ showOn?: OverlayShowOn;++ /**+ * JS-controlled visibility override. Takes precedence over showOn + touch.+ */+ isOpen?: boolean;++ /**+ * Scrim background mode.+ * @default "dark"+ */+ scrim?: OverlayScrimMode;++ /**+ * Scrim placement.+ * @default "fill"+ */+ position?: OverlayPosition;++ /**+ * Content alignment.+ * @default "end"+ */+ align?: OverlayAlign;+}++export interface OverlayContainerProps {+ /** CSS class names for marker + positioning. */+ className: string | undefined;+ /** Inline styles for marker + positioning. */+ style: React.CSSProperties | undefined;+ /** Touch tap-to-toggle handler. Only set on touch devices with full overlays. */+ onClick: ((e: MouseEvent<HTMLElement>) => void) | undefined;+ /** Touch tap-to-toggle handler. Only set on touch devices with full overlays. */+ onMouseUp: ((e: MouseEvent<HTMLElement>) => void) | undefined;+}++export interface UseXDSOverlayResult {+ /** Ref — attach to the container element. */+ containerRef: React.RefObject<HTMLElement | null>;++ /** Props to spread on the container element. */+ containerProps: OverlayContainerProps;++ /**+ * Pre-rendered scrim element — place inside the container.+ * Only available when `content` is provided in options.+ */+ element: ReactElement | null;++ /**+ * Render function for the overlay scrim. Use when you want to+ * control where/when the scrim mounts, or pass dynamic content.+ * Same pattern as useXDSTooltip's renderTooltip.+ */+ renderOverlay: (children: ReactNode) => ReactElement;+}++// =============================================================================+// Hook+// =============================================================================++/**+ * Hook for overlay behavior on an existing container.+ * Returns containerRef, containerProps, and scrim element/render function.+ *+ * @example+ * ```+ * const overlay = useXDSOverlay({+ * showOn: 'hover',+ * content: <XDSButton label="Quick view" variant="ghost" />,+ * });+ *+ * <XDSCard ref={overlay.containerRef} {...overlay.containerProps}>+ * <XDSLayout content={...} />+ * {overlay.element}+ * </XDSCard>+ * ```+ *+ * @example+ * ```+ * // Callback mode — render on demand+ * const overlay = useXDSOverlay({ showOn: 'hover' });+ *+ * <div ref={overlay.containerRef} {...overlay.containerProps}>+ * <img src={src} />+ * {overlay.renderOverlay(<XDSButton label="Quick view" />)}+ * </div>+ * ```+ */+export function useXDSOverlay({+ content,+ showOn = 'always',+ isOpen: isOpenProp,+ scrim = 'dark',+ position = 'fill',+ align = 'end',+}: UseXDSOverlayOptions = {}): UseXDSOverlayResult {+ const containerRef = useRef<HTMLElement | null>(null);++ const isTouchDevice = useSyncExternalStore(+ subscribeToHoverChange,+ getIsTouchDevice,+ getServerSnapshot,+ );++ const [touchOpen, setTouchOpen] = useState(false);++ const isHoverMode = showOn === 'hover' || showOn === 'hover-or-focus';++ const needsTouchToggle = isTouchDevice && isHoverMode;++ const handleToggle = useCallback(() => {+ setTouchOpen(prev => !prev);+ }, []);++ const {onClick, onMouseUp} = useClickableContainer({+ containerRef,+ onClick: needsTouchToggle ? handleToggle : undefined,+ disabled: !needsTouchToggle,+ });++ // Resolve isOpen: consumer prop > touch toggle > undefined (CSS)+ const effectiveIsOpen =+ isOpenProp !== undefined+ ? isOpenProp+ : needsTouchToggle+ ? touchOpen+ : undefined;++ // Container styles (marker + positioning)+ const resolved = stylex.props(overlayScope, overlayContainerStyles.root);++ const containerProps = useMemo<OverlayContainerProps>(+ () => ({+ className: resolved.className ?? undefined,+ style: resolved.style ?? undefined,+ onClick: needsTouchToggle ? onClick : undefined,+ onMouseUp: needsTouchToggle ? onMouseUp : undefined,+ }),+ [resolved.className, resolved.style, needsTouchToggle, onClick, onMouseUp],+ );++ // Render function — matches tooltip's renderTooltip pattern+ const renderOverlay = useCallback(+ (children: ReactNode): ReactElement => (+ <OverlayScrim+ scrim={scrim}+ position={position}+ align={align}+ showOn={showOn}+ isOpen={effectiveIsOpen}>+ {children}+ </OverlayScrim>+ ),+ [scrim, position, align, showOn, effectiveIsOpen],+ );++ // Pre-rendered element when content is provided+ const element = content != null ? renderOverlay(content) : null;++ return {+ containerRef,+ containerProps,+ element,+ renderOverlay,+ };+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 4894e9c43c..9a49bed460 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -138,6 +138,9 @@ export * from './Spinner';// Timestamp displayexport * from './Timestamp';+// Overlay+export * from './Overlay';+// Overflow listexport * from './OverflowList';