An open source design system that's fully customizable and agent ready
TypeScript
docs(Citation): add docsite showcase and examples (#2639)
Cindy Zhang26f933ac1bd1
diff --git a/packages/cli/templates/blocks/components/Citation/CitationInlineText.doc.mjs b/packages/cli/templates/blocks/components/Citation/CitationInlineText.doc.mjsnew file mode 100644index 0000000000..dbb9e500bb--- /dev/null+++ b/packages/cli/templates/blocks/components/Citation/CitationInlineText.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: 'Citation',+ name: 'Citation — Inline Text',+ displayName: 'Citation — Inline Text',+ description:+ 'Citations embedded within a paragraph of text, showing how they flow inline with surrounding content.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Citation', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Citation/CitationInlineText.tsx b/packages/cli/templates/blocks/components/Citation/CitationInlineText.tsxnew file mode 100644index 0000000000..0008996729--- /dev/null+++ b/packages/cli/templates/blocks/components/Citation/CitationInlineText.tsx@@ -0,0 +1,42 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {XDSCitation} from '@xds/core/Citation';+import {XDSText} from '@xds/core/Text';+import {XDSStack} from '@xds/core/Layout';++export default function CitationInlineText() {+ return (+ <XDSStack direction="vertical" gap={4} style={{maxWidth: 560}}>+ <XDSText type="body">+ React uses a virtual DOM to minimize expensive DOM operations+ <XDSCitation+ source={{title: 'React Documentation', url: 'https://react.dev'}}+ number={1}+ variant="number"+ />+ . This approach was inspired by earlier functional UI frameworks+ <XDSCitation+ source={{title: 'Elm Architecture', url: 'https://guide.elm-lang.org/architecture/'}}+ number={2}+ variant="number"+ />+ .+ </XDSText>+ <XDSText type="body">+ StyleX compiles atomic CSS at build time for optimal performance+ <XDSCitation+ source={{+ title: 'StyleX Documentation',+ url: 'https://stylexjs.com',+ icon: 'https://stylexjs.com/img/favicon.ico',+ }}+ number={3}+ variant="label"+ />+ .+ </XDSText>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Citation/CitationShowcase.doc.mjs b/packages/cli/templates/blocks/components/Citation/CitationShowcase.doc.mjsnew file mode 100644index 0000000000..da83240cd0--- /dev/null+++ b/packages/cli/templates/blocks/components/Citation/CitationShowcase.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: 'Citation',+ name: 'Citation — Showcase',+ displayName: 'Citation — Showcase',+ description:+ 'All citation variants at a glance: label chips and numbered badges, with and without icons and links.',+ isReady: true,+ isShowcase: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Citation', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Citation/CitationShowcase.tsx b/packages/cli/templates/blocks/components/Citation/CitationShowcase.tsxnew file mode 100644index 0000000000..cf87fca674--- /dev/null+++ b/packages/cli/templates/blocks/components/Citation/CitationShowcase.tsx@@ -0,0 +1,62 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {XDSCitation} from '@xds/core/Citation';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++export default function CitationShowcase() {+ return (+ <XDSStack direction="vertical" gap={6}>+ <XDSStack direction="vertical" gap={2}>+ <XDSText type="supporting" color="secondary">+ Label variant+ </XDSText>+ <XDSStack direction="horizontal" gap={2} style={{flexWrap: 'wrap'}}>+ <XDSCitation+ source={{title: 'React Documentation', url: 'https://react.dev'}}+ number={1}+ variant="label"+ />+ <XDSCitation+ source={{+ title: 'GitHub',+ url: 'https://github.com',+ icon: 'https://github.githubassets.com/favicons/favicon.svg',+ }}+ number={2}+ variant="label"+ />+ <XDSCitation+ source={{title: 'Internal reference'}}+ number={3}+ variant="label"+ />+ </XDSStack>+ </XDSStack>+ <XDSStack direction="vertical" gap={2}>+ <XDSText type="supporting" color="secondary">+ Number variant+ </XDSText>+ <XDSStack direction="horizontal" gap={2}>+ <XDSCitation+ source={{title: 'TypeScript Handbook', url: 'https://typescriptlang.org'}}+ number={1}+ variant="number"+ />+ <XDSCitation+ source={{title: 'MDN Web Docs', url: 'https://developer.mozilla.org'}}+ number={2}+ variant="number"+ />+ <XDSCitation+ source={{title: 'W3C Specification'}}+ number={3}+ variant="number"+ />+ </XDSStack>+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Citation/CitationSourceList.doc.mjs b/packages/cli/templates/blocks/components/Citation/CitationSourceList.doc.mjsnew file mode 100644index 0000000000..ccb9f32ab5--- /dev/null+++ b/packages/cli/templates/blocks/components/Citation/CitationSourceList.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: 'Citation',+ name: 'Citation — Source List',+ displayName: 'Citation — Source List',+ description:+ 'A list of citation sources with icons, as you might show at the end of an AI-generated response or article footer.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Citation', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Citation/CitationSourceList.tsx b/packages/cli/templates/blocks/components/Citation/CitationSourceList.tsxnew file mode 100644index 0000000000..af67999874--- /dev/null+++ b/packages/cli/templates/blocks/components/Citation/CitationSourceList.tsx@@ -0,0 +1,49 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {XDSCitation} from '@xds/core/Citation';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const sources = [+ {+ title: 'React Documentation',+ url: 'https://react.dev',+ icon: 'https://react.dev/favicon-32x32.png',+ },+ {+ title: 'TypeScript Handbook',+ url: 'https://www.typescriptlang.org/docs/handbook/',+ icon: 'https://www.typescriptlang.org/favicon-32x32.png',+ },+ {+ title: 'MDN Web Docs',+ url: 'https://developer.mozilla.org',+ icon: 'https://developer.mozilla.org/favicon-48x48.cbbd161b.png',+ },+ {+ title: 'W3C WAI-ARIA Specification',+ url: 'https://www.w3.org/TR/wai-aria/',+ },+];++export default function CitationSourceList() {+ return (+ <XDSStack direction="vertical" gap={3}>+ <XDSText type="supporting" color="secondary">+ Sources+ </XDSText>+ <XDSStack direction="horizontal" gap={2} style={{flexWrap: 'wrap'}}>+ {sources.map((source, i) => (+ <XDSCitation+ key={source.title}+ source={source}+ number={i + 1}+ variant="label"+ />+ ))}+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjsindex 08a138b84d..4c38e65fbd 100644--- a/packages/core/src/Citation/Citation.doc.mjs+++ b/packages/core/src/Citation/Citation.doc.mjs@@ -9,10 +9,75 @@ export const docs = {category: 'Content',usage: {- description: '',+ description:+ 'Citations display inline references to external sources. Use them to attribute information within AI-generated responses, articles, or anywhere provenance and source links are needed.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Use the label variant when the source title adds meaningful context for the reader.',+ },+ {+ guidance: true,+ description:+ 'Use the number variant for compact inline references within body text, like footnotes.',+ },+ {+ guidance: false,+ description:+ 'Mix label and number variants in the same paragraph. Pick one style per context for visual consistency.',+ },+ ],+ anatomy: [+ {+ name: 'Container',+ required: true,+ description:+ 'The interactive wrapper — renders as an anchor when a URL is provided, or a span otherwise.',+ },+ {+ name: 'Icon',+ required: false,+ description:+ 'An optional favicon or source icon displayed before the label text. Only available in the label variant.',+ },+ {+ name: 'Label text',+ required: false,+ description:+ 'The source title, truncated with ellipsis when it exceeds the max width. Shown in the label variant.',+ },+ {+ name: 'Number',+ required: false,+ description:+ 'The citation index displayed as a superscript badge. Shown in the number variant.',+ },+ ],},- props: [],+ props: [+ {+ name: 'source',+ type: 'XDSCitationSource',+ description:+ 'The citation source object containing title, url, and optional icon.',+ required: true,+ },+ {+ name: 'number',+ type: 'number',+ description: 'The display index for this citation.',+ required: true,+ },+ {+ name: 'variant',+ type: "'label' | 'number'",+ description:+ 'Display style — a label chip showing the source title or a compact numbered badge.',+ default: "'label'",+ },+ ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Citation/XDSCitation.tsx b/packages/core/src/Citation/XDSCitation.tsxindex 3ad5b24ab2..2d54506e04 100644--- a/packages/core/src/Citation/XDSCitation.tsx+++ b/packages/core/src/Citation/XDSCitation.tsx@@ -10,6 +10,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Citation/index.ts (exports if types change)+ * - /packages/cli/templates/blocks/components/Citation/ (showcase blocks)*/import type React from 'react';