An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): document Overlay props (#2811)
Cindy Zhanga032bc57f514
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 0c7fb17ae7..3993002c02 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -8,15 +8,87 @@*/import * as fs from 'node:fs';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';import {describe, it, expect} from 'vitest';import {packages} from '../generated/packageRegistry';-import {components, componentCount} from '../generated/componentRegistry';+import {+ components,+ componentCount,+ type ComponentEntry,+} from '../generated/componentRegistry';import {blocks, blockCount, showcaseCount} from '../generated/blockRegistry';import {templates, templateCount} from '../generated/templateRegistry';import {docTopics, docsCount} from '../generated/docsRegistry';import {showcaseRegistry} from '../generated/showcaseRegistry';import {exampleRegistry} from '../generated/exampleRegistry';+const REPO_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../../..',+);+const CORE_SRC_DIR = path.join(REPO_ROOT, 'packages/core/src');++function findFiles(dir: string, predicate: (filePath: string) => boolean) {+ const files: string[] = [];+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ const fullPath = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ files.push(...findFiles(fullPath, predicate));+ } else if (predicate(fullPath)) {+ files.push(fullPath);+ }+ }+ return files;+}++function getCoreComponentsWithPublicProps() {+ const names = new Set<string>();+ for (const filePath of findFiles(CORE_SRC_DIR, file =>+ file.endsWith('.tsx'),+ )) {+ const source = fs.readFileSync(filePath, 'utf-8');+ for (const match of source.matchAll(+ /export\s+(?:interface|type)\s+XDS([A-Z]\w*)Props\b/g,+ )) {+ names.add(match[1]);+ }+ }+ return names;+}++function getComponentDocCompletenessIssues(+ comp: ComponentEntry,+ componentsWithPublicProps: Set<string>,+) {+ const issues: string[] = [];+ if (comp.params != null || comp.hidden) {+ return issues;+ }+ if (comp.description.trim() === '') {+ issues.push('missing description');+ }+ const usageDescription = comp.usage?.description?.trim() ?? '';+ if (usageDescription === '') {+ issues.push('missing usage description');+ }+ if (componentsWithPublicProps.has(comp.name) && comp.props.length === 0) {+ issues.push('missing props');+ }+ const incompleteProps = comp.props+ .filter(+ prop =>+ prop.name.trim() === '' ||+ prop.type.trim() === '' ||+ prop.description.trim() === '',+ )+ .map(prop => prop.name || '<unnamed>');+ if (incompleteProps.length > 0) {+ issues.push(`incomplete props: ${incompleteProps.join(', ')}`);+ }+ return issues;+}+// ── Package Registry ───────────────────────────────────────────────────describe('packageRegistry', () => {@@ -201,6 +273,19 @@ describe('componentRegistry', () => {expect(button!.parentDoc).toBeNull();});+ it('keeps core component docs complete for generated component pages', () => {+ const componentsWithPublicProps = getCoreComponentsWithPublicProps();+ const incompleteDocs = components['@xds/core'].flatMap(comp => {+ const issues = getComponentDocCompletenessIssues(+ comp,+ componentsWithPublicProps,+ );+ return issues.length > 0 ? [`${comp.name}: ${issues.join(', ')}`] : [];+ });++ expect(incompleteDocs).toEqual([]);+ });+it('moduleName has XDS prefix for components, not for hooks', () => {const core = components['@xds/core'];const button = core.find(c => c.name === 'Button');diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.doc.mjs b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.doc.mjsnew file mode 100644index 0000000000..6b8b92667a--- /dev/null+++ b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Overlay',+ name: 'Overlay — Bottom Strip',+ displayName: 'Overlay — Bottom Strip',+ description:+ 'Places compact supporting content in a bottom scrim strip without covering the entire image.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Overlay', 'AspectRatio', 'Badge', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.tsx b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.tsxnew file mode 100644index 0000000000..0ac440bfd0--- /dev/null+++ b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.tsx@@ -0,0 +1,51 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSOverlay} from '@xds/core/Overlay';+import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSBadge} from '@xds/core/Badge';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const styles = stylex.create({+ frame: {+ width: 420,+ maxWidth: '100%',+ borderRadius: 12,+ overflow: 'clip',+ },+ image: {+ width: '100%',+ height: '100%',+ objectFit: 'cover',+ },+});++export default function OverlayBottomStrip() {+ return (+ <XDSOverlay+ position="bottom"+ align="start"+ content={+ <XDSVStack gap={1}>+ <XDSBadge label="New" variant="green" />+ <XDSText type="body" weight="bold" color="inherit">+ Weekly product highlights+ </XDSText>+ <XDSText type="supporting" color="inherit">+ 12 updates across templates and tokens+ </XDSText>+ </XDSVStack>+ }>+ <XDSAspectRatio ratio={16 / 9} xstyle={styles.frame}>+ <img+ src="https://lookaside.facebook.com/assets/xds_oss/illustrative-horizontal-1.jpg"+ alt="Product highlight preview"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ );+}diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.doc.mjs b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.doc.mjsnew file mode 100644index 0000000000..8f86308749--- /dev/null+++ b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Overlay',+ name: 'Overlay — Hover Reveal',+ displayName: 'Overlay — Hover Reveal',+ description:+ 'Reveals an overlay action on hover or keyboard focus. Use when actions should stay visually quiet until the media receives attention.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Overlay', 'AspectRatio', 'Button'],+};diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.tsx b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.tsxnew file mode 100644index 0000000000..db252c946a--- /dev/null+++ b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.tsx@@ -0,0 +1,39 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSOverlay} from '@xds/core/Overlay';+import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSButton} from '@xds/core/Button';++const styles = stylex.create({+ frame: {+ width: 420,+ maxWidth: '100%',+ borderRadius: 12,+ overflow: 'clip',+ },+ image: {+ width: '100%',+ height: '100%',+ objectFit: 'cover',+ },+});++export default function OverlayHoverReveal() {+ return (+ <XDSOverlay+ showOn="hover"+ align="center"+ content={<XDSButton label="Quick view" variant="secondary" size="sm" />}>+ <XDSAspectRatio ratio={16 / 9} xstyle={styles.frame}>+ <img+ src="https://lookaside.facebook.com/assets/xds_oss/light-working-horizontal-1.png"+ alt="Workspace preview"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ );+}diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.doc.mjs b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.doc.mjsnew file mode 100644index 0000000000..26a9ad7718--- /dev/null+++ b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.doc.mjs@@ -0,0 +1,15 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Overlay',+ name: 'Overlay',+ displayName: 'Overlay',+ description:+ 'A media card with an always-visible scrim and centered action content.',+ isReady: true,+ aspectRatio: 16 / 9,+ isShowcase: true,+ componentsUsed: ['Overlay', 'AspectRatio', 'Button', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.tsx b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.tsxnew file mode 100644index 0000000000..d95b835dd8--- /dev/null+++ b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.tsx@@ -0,0 +1,50 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSOverlay} from '@xds/core/Overlay';+import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSButton} from '@xds/core/Button';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const styles = stylex.create({+ frame: {+ width: 520,+ maxWidth: '100%',+ borderRadius: 16,+ overflow: 'clip',+ },+ image: {+ width: '100%',+ height: '100%',+ objectFit: 'cover',+ },+ content: {+ textAlign: 'center',+ },+});++export default function OverlayShowcase() {+ return (+ <XDSOverlay+ align="center"+ content={+ <XDSVStack gap={2} xstyle={styles.content}>+ <XDSText type="supporting" weight="bold" color="inherit">+ Design system foundations+ </XDSText>+ <XDSButton label="Open gallery" variant="secondary" size="sm" />+ </XDSVStack>+ }>+ <XDSAspectRatio ratio={16 / 9} xstyle={styles.frame}>+ <img+ src="https://lookaside.facebook.com/assets/xds_oss/light-scene-horizontal-1.png"+ alt="Abstract landscape"+ {...stylex.props(styles.image)}+ />+ </XDSAspectRatio>+ </XDSOverlay>+ );+}diff --git a/packages/core/src/Overlay/Overlay.doc.mjs b/packages/core/src/Overlay/Overlay.doc.mjsindex 615d8a2c85..10b6a51cf2 100644--- a/packages/core/src/Overlay/Overlay.doc.mjs+++ b/packages/core/src/Overlay/Overlay.doc.mjs@@ -8,17 +8,203 @@ export const docs = {group: 'Overlay',category: 'Overlay',+ keywords: ['overlay', 'scrim', 'media', 'hover', 'focus', 'image', 'card'],+usage: {- description: '',+ description:+ 'Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Use overlays for short, contextual actions or labels that belong directly to the underlying media or surface.',+ },+ {+ guidance: true,+ description:+ 'Keep overlay content compact so it remains legible over the scrim and does not obscure important visual information.',+ },+ {+ guidance: false,+ description:+ 'Do not use Overlay for floating content anchored outside the surface. Use Popover, Tooltip, or Dialog for those patterns.',+ },+ ],+ anatomy: [+ {+ name: 'Base content',+ required: false,+ description: 'The media, card, or bounded surface that the overlay sits on top of.',+ },+ {+ name: 'Scrim',+ required: false,+ description: 'Optional dark or light overlay background that improves content contrast.',+ },+ {+ name: 'Overlay content',+ required: true,+ description: 'Actions, labels, or supporting content rendered above the base surface.',+ },+ ],+ },++ playground: {+ defaults: {+ content: {+ __element: 'XDSButton',+ props: {label: 'Quick view', variant: 'secondary', size: 'sm'},+ },+ children: [+ {+ __element: 'XDSAspectRatio',+ props: {+ ratio: 1.7777777777777777,+ style: {+ width: 320,+ borderRadius: 12,+ overflow: 'clip',+ },+ },+ children: {+ __element: 'div',+ props: {+ style: {+ width: '100%',+ height: '100%',+ background:+ 'linear-gradient(135deg, #172554 0%, #2563eb 55%, #67e8f9 100%)',+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ color: 'white',+ fontWeight: 600,+ },+ },+ children: 'Media preview',+ },+ },+ ],+ },},- props: [],+ props: [+ {+ name: 'content',+ type: 'ReactNode',+ description: 'Content rendered inside the overlay scrim.',+ required: true,+ slotElements: [+ {+ __element: 'XDSButton',+ props: {label: 'Quick view', variant: 'secondary', size: 'sm'},+ },+ {+ __element: 'XDSText',+ props: {type: 'body', weight: 'bold'},+ children: 'Overlay content',+ },+ ],+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Base content such as an image, video, card, or media surface that the overlay sits on top of.',+ slotElements: [+ {+ __element: 'XDSAspectRatio',+ props: {ratio: 1.7777777777777777, style: {width: 320}},+ children: {+ __element: 'div',+ props: {+ style: {+ width: '100%',+ height: '100%',+ background:+ 'linear-gradient(135deg, #172554 0%, #2563eb 55%, #67e8f9 100%)',+ },+ },+ },+ },+ ],+ },+ {+ name: 'showOn',+ type: "'hover' | 'always' | 'focus' | 'hover-or-focus'",+ description:+ 'Visibility trigger. Hover mode also reveals on focus for keyboard accessibility; hover-or-focus is an alias for hover.',+ default: "'always'",+ },+ {+ name: 'isOpen',+ type: 'boolean',+ description: 'Controlled visibility override. When set, this takes precedence over showOn and touch toggle behavior.',+ },+ {+ name: 'scrim',+ type: "'dark' | 'light' | false",+ description: 'Scrim background mode. Set to false to render overlay content without a scrim background.',+ default: "'dark'",+ },+ {+ name: 'position',+ type: "'fill' | 'bottom' | 'top'",+ description: 'Where the scrim appears within the base surface.',+ default: "'fill'",+ },+ {+ name: 'align',+ type: "'start' | 'center' | 'end'",+ description: 'Alignment of the overlay content within the scrim.',+ default: "'end'",+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',+ },+ {+ name: 'className',+ type: 'string',+ description: 'CSS class name(s) appended to the root element. Prefer xstyle for styling when possible.',+ },+ {+ name: 'style',+ type: 'React.CSSProperties',+ description: 'Inline styles applied to the root element. Prefer xstyle for design-system styling.',+ },+ {+ name: 'ref',+ type: 'Ref<HTMLDivElement>',+ description: 'Ref forwarded to the overlay root element.',+ },+ ],};/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: '',+ description: 'layered content over media/card surfaces with scrim + hover/focus/controlled reveal',usage: {- description: '',+ description:+ 'Overlay layers compact actions or supporting content over media, cards, or bounded surfaces with optional dark/light scrim and hover/focus/controlled reveal.',+ bestPractices: [+ {guidance: true, description: 'Use for short contextual actions/labels tied to the underlying surface.'},+ {guidance: true, description: 'Keep content compact and legible over the scrim.'},+ {guidance: false, description: 'Do not use for floating anchored surfaces; use Popover, Tooltip, or Dialog.'},+ ],+ },+ propDescriptions: {+ content: 'overlay content inside scrim; required',+ children: 'base media/card/surface beneath overlay',+ showOn: 'visibility trigger; hover also focus-visible; default always',+ isOpen: 'controlled visibility override',+ scrim: 'dark/light scrim or false for no scrim; default dark',+ position: 'scrim placement: fill, bottom strip, or top strip',+ align: 'content alignment inside scrim',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ className: 'additional root class names',+ style: 'inline root styles; prefer xstyle',+ ref: 'forwarded root div ref',},};