Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(useOverlay): add hook docs and a product quick view example block (#9908)

Parman Mohammadalizadehc8a172b4b5bc
diff --git a/.changeset/hook-doc-use-overlay.md b/.changeset/hook-doc-use-overlay.md
new file mode 100644
index 0000000000..7bd2d46a0a
--- /dev/null
+++ b/.changeset/hook-doc-use-overlay.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] Hook docs for `useOverlay`, so `astryx hook useOverlay` and `astryx search` return it, and a `useOverlay — Product Quick View` example block: a product Card spreads the hook's `containerRef` and `containerProps` and renders the returned scrim once over its image. Hovering the card, or moving keyboard focus into it, reveals a Quick view button, and the image link before it lets Tab reach the button. Copy it with `astryx template useOverlayHookUsage <path>`.
+
+@MannXo
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 40d2bb7902..7ace7e0f97 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -807,6 +807,7 @@
"/templates/useMergedRefsHookUsage/",
"/templates/useOutlineFromMarkdownHookUsage/",
"/templates/useOverflowHookUsage/",
+ "/templates/useOverlayHookUsage/",
"/templates/usePressFeedbackHookUsage/",
"/templates/useScrollOverflowHookUsage/",
"/templates/useScrollableAreaHookUsage/",
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 2ca075faec..c286206ed1 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3776,6 +3776,11 @@
"path": "examples/use-overflow/editor-toolbar",
"aliases": []
},
+ {
+ "name": "example-use-overlay-product-quick-view",
+ "path": "examples/use-overlay/product-quick-view",
+ "aliases": []
+ },
{
"name": "example-use-pan-gesture-a-draggable-box",
"path": "examples/use-pan-gesture/a-draggable-box",
@@ -4096,6 +4101,11 @@
"path": "hooks/use-overflow",
"aliases": []
},
+ {
+ "name": "hook-use-overlay",
+ "path": "hooks/use-overlay",
+ "aliases": []
+ },
{
"name": "hook-use-pan-gesture",
"path": "hooks/use-pan-gesture",
diff --git a/packages/cli/api/component/__fixtures__/resolutions/modules.txt b/packages/cli/api/component/__fixtures__/resolutions/modules.txt
index f17d47be2a..5106cf14d6 100644
--- a/packages/cli/api/component/__fixtures__/resolutions/modules.txt
+++ b/packages/cli/api/component/__fixtures__/resolutions/modules.txt
@@ -279,7 +279,7 @@ useMenuHover useMenuHover hooks/useAnimatedLayout.doc.mjs hooks/useMenuHover.ts
useMenuOverflow useMenuOverflow DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/useMenuOverflow.ts
useMobileKeyboard ERR_UNKNOWN_COMPONENT - keyboard/useMobileKeyboard.ts
useOutlineFromDOM useOutlineFromDOM Outline/Outline.doc.mjs Outline/useOutlineFromDOM.ts
-useOverlay useOverlay Overlay/Overlay.doc.mjs Overlay/useOverlay.tsx
+useOverlay useOverlay Overlay/useOverlay.doc.mjs Overlay/useOverlay.tsx
useOwnScrollGesture useOwnScrollGesture DateInput/DateInput.doc.mjs DateInput/useOwnScrollGesture.ts
usePager usePager hooks/useAnimatedLayout.doc.mjs hooks/usePager.ts
usePointerDragScroll usePointerDragScroll DateInput/DateInput.doc.mjs DateInput/usePointerDragScroll.ts
diff --git a/packages/cli/api/template/use-overlay-hook-usage.test.tsx b/packages/cli/api/template/use-overlay-hook-usage.test.tsx
new file mode 100644
index 0000000000..90f0dc23ce
--- /dev/null
+++ b/packages/cli/api/template/use-overlay-hook-usage.test.tsx
@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @vitest-environment jsdom
+
+/**
+ * The useOverlay example spreads the hook's container ref and props on a
+ * product Card and renders the returned scrim once over the image. Hover and
+ * focus reveal are CSS, which jsdom does not apply, so this checks the wiring
+ * and the tab order that keyboard users depend on.
+ */
+
+import {act} from 'react';
+import {createRoot, type Root} from 'react-dom/client';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {useOverlay} from '@astryxdesign/core/Overlay';
+import UseOverlayHookUsage from '../../assets/templates/blocks/components/Overlay/useOverlayHookUsage';
+
+(globalThis as {IS_REACT_ACT_ENVIRONMENT?: boolean}).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+let root: Root | null = null;
+let container: HTMLElement;
+
+function overlayScopeClasses(): string[] {
+ let className = '';
+ function Probe() {
+ className = useOverlay().containerProps.className ?? '';
+ return null;
+ }
+ const probeRoot = createRoot(document.createElement('div'));
+ act(() => probeRoot.render(<Probe />));
+ act(() => probeRoot.unmount());
+ return className.split(' ').filter(Boolean);
+}
+
+function quickView(): HTMLButtonElement {
+ const button = Array.from(container.querySelectorAll('button')).find(
+ candidate => candidate.textContent === 'Quick view',
+ );
+ if (button == null) {
+ throw new Error('no Quick view button rendered');
+ }
+ return button;
+}
+
+beforeEach(() => {
+ // A device with a mouse, so hover reveal is CSS-driven.
+ vi.stubGlobal('matchMedia', (query: string) => ({
+ matches: false,
+ media: query,
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ }));
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ act(() => {
+ root = createRoot(container);
+ root.render(<UseOverlayHookUsage />);
+ });
+});
+
+afterEach(() => {
+ act(() => root?.unmount());
+ root = null;
+ container.remove();
+ vi.unstubAllGlobals();
+});
+
+describe('useOverlay example', () => {
+ it('renders one Quick view scrim inside the card that carries the container props', () => {
+ const card = container.firstElementChild as HTMLElement;
+ const scope = overlayScopeClasses();
+ expect(scope.length).toBeGreaterThan(0);
+ for (const name of scope) {
+ expect(card.classList.contains(name)).toBe(true);
+ }
+ expect(card.contains(quickView())).toBe(true);
+ expect(
+ Array.from(container.querySelectorAll('button')).filter(
+ button => button.textContent === 'Quick view',
+ ),
+ ).toHaveLength(1);
+ });
+
+ it('shows Quick view in a bottom strip, which leaves the image link above it clickable', () => {
+ const scrim = quickView().closest('.astryx-overlay-scrim');
+ expect(scrim?.getAttribute('data-position')).toBe('bottom');
+ });
+
+ it('puts the image link before Quick view in tab order, so focus can reveal it', () => {
+ const link = container.querySelector('a');
+ if (link == null) {
+ throw new Error('no image link rendered');
+ }
+ expect(link.getAttribute('href')).toBe('#ceramic-mug');
+ expect(
+ link.compareDocumentPosition(quickView()) &
+ Node.DOCUMENT_POSITION_FOLLOWING,
+ ).toBeTruthy();
+ });
+});
diff --git a/packages/cli/assets/templates/blocks/components/Overlay/useOverlayHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Overlay/useOverlayHookUsage.doc.mjs
new file mode 100644
index 0000000000..0750490834
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Overlay/useOverlayHookUsage.doc.mjs
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useOverlay',
+ name: 'useOverlay — Product Quick View',
+ displayName: 'useOverlay — Product Quick View',
+ description:
+ 'A product card that is its own overlay container: useOverlay returns the ref and props to spread on the Card and a bottom strip to render once over the image. Hovering the card, or moving keyboard focus into it, slides in a Quick view button along the bottom of the image, and leaving hides it again. The image is a link that the strip leaves clickable above it, and Tab lands on it first so the next Tab reaches Quick view.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: [
+ 'Overlay',
+ 'Card',
+ 'AspectRatio',
+ 'Button',
+ 'Layout',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Overlay/useOverlayHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Overlay/useOverlayHookUsage.tsx
new file mode 100644
index 0000000000..412a53d317
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Overlay/useOverlayHookUsage.tsx
@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import type {RefObject} from 'react';
+import {AspectRatio} from '@astryxdesign/core/AspectRatio';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {VStack} from '@astryxdesign/core/Layout';
+import {useOverlay} from '@astryxdesign/core/Overlay';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function UseOverlayHookUsage() {
+ const overlay = useOverlay({
+ showOn: 'hover',
+ position: 'bottom',
+ align: 'center',
+ content: <Button label="Quick view" variant="secondary" size="sm" />,
+ });
+
+ return (
+ <Card
+ width={280}
+ padding={0}
+ ref={overlay.containerRef as RefObject<HTMLDivElement | null>}
+ {...overlay.containerProps}>
+ <div style={{position: 'relative'}}>
+ <a href="#ceramic-mug">
+ <AspectRatio ratio={1}>
+ <img
+ src="/template-assets/light-product-1.png"
+ alt="Ceramic mug"
+ style={{width: '100%', height: '100%', objectFit: 'cover'}}
+ />
+ </AspectRatio>
+ </a>
+ {overlay.element}
+ </div>
+ <VStack gap={1} padding={3}>
+ <Text type="body" weight="bold">
+ Ceramic mug
+ </Text>
+ <Text type="supporting" color="secondary">
+ $24
+ </Text>
+ </VStack>
+ </Card>
+ );
+}
diff --git a/packages/core/src/Overlay/useOverlay.doc.mjs b/packages/core/src/Overlay/useOverlay.doc.mjs
new file mode 100644
index 0000000000..49b295cabe
--- /dev/null
+++ b/packages/core/src/Overlay/useOverlay.doc.mjs
@@ -0,0 +1,176 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+ name: 'useOverlay',
+ displayName: 'useOverlay',
+ group: 'Overlay',
+ keywords: [
+ 'overlay',
+ 'scrim',
+ 'hover reveal',
+ 'focus-within',
+ 'quick view',
+ 'card actions',
+ 'media overlay',
+ ],
+ params: [
+ {
+ name: 'options',
+ type: 'UseOverlayOptions',
+ description: 'Overlay configuration. Every field is optional.',
+ required: false,
+ },
+ {
+ name: 'options.content',
+ type: 'ReactNode',
+ description:
+ 'Content to render inside the scrim. When set, the hook returns it pre-rendered as element.',
+ required: false,
+ },
+ {
+ name: 'options.showOn',
+ type: "'hover' | 'always' | 'focus' | 'hover-or-focus'",
+ description:
+ "Visibility trigger, read with CSS from the container. 'hover' also reveals on focus within the container for keyboard users; 'hover-or-focus' is an alias for it. On a touch device (hover: none), a hover overlay toggles on a tap on the container instead.",
+ default: "'always'",
+ required: false,
+ },
+ {
+ name: 'options.isOpen',
+ type: 'boolean',
+ description:
+ 'Controlled visibility. When set, it takes precedence over showOn and the touch toggle.',
+ required: false,
+ },
+ {
+ name: 'options.scrim',
+ type: "'dark' | 'light' | false",
+ description:
+ 'Scrim background. false renders the content with no scrim background.',
+ default: "'dark'",
+ required: false,
+ },
+ {
+ name: 'options.position',
+ type: "'fill' | 'bottom' | 'top'",
+ description:
+ 'Where the scrim sits: over the whole positioned area, or as a strip along its bottom or top edge.',
+ default: "'fill'",
+ required: false,
+ },
+ {
+ name: 'options.align',
+ type: "'start' | 'center' | 'end'",
+ description: 'Alignment of the content within the scrim.',
+ default: "'end'",
+ required: false,
+ },
+ ],
+ returns: [
+ {
+ name: 'containerRef',
+ type: 'RefObject<HTMLElement | null>',
+ description: 'Attach to the container element.',
+ },
+ {
+ name: 'containerProps',
+ type: 'OverlayContainerProps',
+ description:
+ 'Spread on the same container: className and style mark it as the overlay scope (positioned, clipped), and on a touch device with a hover overlay onClick and onMouseUp toggle it on a tap.',
+ },
+ {
+ name: 'element',
+ type: 'ReactElement | null',
+ description:
+ 'The scrim with options.content, ready to render once inside the container. null when content is not set.',
+ },
+ {
+ name: 'renderOverlay',
+ type: '(children: ReactNode) => ReactElement',
+ description:
+ 'Renders the scrim around the children you pass, for content that changes or a scrim you mount yourself. Use it or element, not both.',
+ },
+ ],
+ usage: {
+ description:
+ "Adds overlay behavior to a container you already render, such as a Card or a custom media frame, without the wrapper Overlay adds. Spread containerRef and containerProps on the container, then render element (or renderOverlay(children)) once inside it. The scrim is absolutely positioned, so it covers the nearest positioned ancestor: the container itself, or a positioned section inside it such as an image area. Visibility is CSS-driven from the container's :hover and :focus-within, so with showOn 'hover' a keyboard user reveals the content by moving focus into the container. Hidden content is not focusable, so the container needs a focusable element before the overlay content in tab order. A revealed scrim takes pointer input over the area it covers, so put that element outside the scrim, or use a top or bottom strip and keep it in the part the strip leaves uncovered.",
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Use showOn 'hover' for actions on media cards: it also reveals on keyboard focus within the container.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Put a focusable element (a link or the card title) before the overlay content in the container, so Tab reveals the content and the next Tab reaches it.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use the Overlay component when you do not already have a container element to attach to.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Put the only way to reach an action behind hover with nothing focusable before it; keyboard users cannot focus content that is hidden.',
+ },
+ ],
+ },
+ relatedComponents: ['Overlay', 'Card', 'AspectRatio'],
+ relatedHooks: ['useClickableContainer'],
+ importPath: '@astryxdesign/core/Overlay',
+ category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ "Overlay behavior on a container you already render (Card, media frame) w/o Overlay's wrapper. Spread containerRef + containerProps on it, render element / renderOverlay(children) once inside. CSS-driven via container :hover/:focus-within; hover mode also reveals on keyboard focus. Hidden content is not focusable, so put a focusable element before it, outside the area a revealed scrim covers (the scrim takes pointer input).",
+ paramDescriptions: {
+ options: 'overlay config; all fields optional.',
+ 'options.content':
+ 'content inside the scrim; returned pre-rendered as element.',
+ 'options.showOn':
+ "CSS visibility trigger. 'hover' also reveals on focus-within; 'hover-or-focus' = alias. Touch (hover: none): hover overlays toggle on tap.",
+ 'options.isOpen': 'controlled visibility; wins over showOn + touch toggle.',
+ 'options.scrim': 'scrim background; false = no background.',
+ 'options.position': "scrim placement: 'fill', or a 'bottom' / 'top' strip.",
+ 'options.align': 'content alignment in the scrim.',
+ },
+ returnDescriptions: {
+ containerRef: 'attach to the container.',
+ containerProps:
+ 'spread on the container: overlay scope className/style (positioned, clipped) + tap toggle handlers for hover overlays on touch devices.',
+ element:
+ 'scrim with content, render once inside the container; null w/o content.',
+ renderOverlay:
+ '(children) => scrim; for dynamic content or self-mounted scrim. Use it or element.',
+ },
+ usage: {
+ description:
+ 'Overlay behavior on an existing container: spread containerRef + containerProps, render element once inside. Scrim covers nearest positioned ancestor. CSS :hover/:focus-within; hover mode reveals on keyboard focus too. Put a focusable element before hidden content.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ "showOn 'hover' for media card actions; also reveals on keyboard focus.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Put a focusable element before the overlay content so Tab reveals it, next Tab reaches it.',
+ },
+ {
+ guidance: true,
+ description: 'Use Overlay when there is no container to attach to.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Hide the only route to an action behind hover with nothing focusable before it.',
+ },
+ ],
+ },
+};