An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): add VisuallyHidden showcase and example blocks (#4048)
Ernest15dd282dd538
diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.doc.mjs b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.doc.mjsnew file mode 100644index 0000000000..aa59c55429--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.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: 'VisuallyHidden',+ name: 'VisuallyHidden — Live Region',+ displayName: 'VisuallyHidden — Live Region',+ description:+ 'A polite aria-live region announces visual-only state changes to assistive technology.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['VisuallyHidden', 'Button', 'HStack', 'VStack', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.tsx b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.tsxnew file mode 100644index 0000000000..1032492846--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.tsx@@ -0,0 +1,41 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {useState} from 'react';+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';+import {Button} from '@astryxdesign/core/Button';+import {HStack, VStack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';++const columns = ['Backlog', 'In progress', 'Done'] as const;++export default function VisuallyHiddenLiveRegion() {+ const [column, setColumn] = useState(0);+ const current = columns[column];++ function move() {+ setColumn(c => (c + 1) % columns.length);+ }++ return (+ <VStack gap={4} hAlign="start">+ <Text type="supporting" color="secondary">+ Drag-and-drop and other visual-only changes are silent to screen+ readers. A live region narrates them.+ </Text>+ <HStack gap={3} vAlign="center">+ <Button label="Move task" variant="secondary" onClick={move} />+ <Text type="body">+ Task is in{' '}+ <Text as="span" weight="bold">+ {current}+ </Text>+ </Text>+ </HStack>+ <VisuallyHidden as="div" aria-live="polite">+ {`Task moved to ${current}`}+ </VisuallyHidden>+ </VStack>+ );+}diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.doc.mjs b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.doc.mjsnew file mode 100644index 0000000000..3959e8bcea--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.doc.mjs@@ -0,0 +1,13 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'VisuallyHidden',+ name: 'VisuallyHidden',+ displayName: 'VisuallyHidden',+ isReady: true,+ aspectRatio: 16 / 9,+ isShowcase: true,+ componentsUsed: ['VisuallyHidden', 'IconButton', 'Card', 'HStack', 'VStack', 'Text', 'Icon'],+};diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.tsx b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.tsxnew file mode 100644index 0000000000..6c001c467d--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.tsx@@ -0,0 +1,78 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';+import {IconButton} from '@astryxdesign/core/IconButton';+import {Card} from '@astryxdesign/core/Card';+import {HStack, VStack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';+import {Icon} from '@astryxdesign/core/Icon';+import {+ ArrowDownTrayIcon,+ ShareIcon,+ TrashIcon,+} from '@heroicons/react/24/outline';+import {SpeakerWaveIcon} from '@heroicons/react/24/solid';++const actions = [+ {label: 'Download', icon: ArrowDownTrayIcon},+ {label: 'Share', icon: ShareIcon},+ {label: 'Delete', icon: TrashIcon},+] as const;++/**+ * VisuallyHidden is invisible by design, so this hero teaches the concept by+ * contrast: the icon-only buttons are all a sighted user sees, while the+ * caption spells out the accessible name each one exposes. A live+ * <VisuallyHidden> region below announces the same names to assistive tech,+ * so the demo genuinely exercises the component it documents.+ */+export default function VisuallyHiddenShowcase() {+ return (+ <VStack gap={5} hAlign="center">+ <HStack gap={6} vAlign="stretch" wrap="wrap" hAlign="center">+ <Card variant="muted">+ <VStack gap={4} hAlign="center">+ <Text type="supporting" color="secondary">+ What you see+ </Text>+ <HStack gap={2}>+ {actions.map(({label, icon}) => (+ <IconButton+ key={label}+ label={label}+ icon={<Icon icon={icon} />}+ variant="ghost"+ />+ ))}+ </HStack>+ </VStack>+ </Card>++ <Card variant="muted">+ <VStack gap={4} hAlign="start">+ <HStack gap={2} vAlign="center">+ <Icon icon={SpeakerWaveIcon} size="sm" />+ <Text type="supporting" color="secondary">+ What a screen reader hears+ </Text>+ </HStack>+ <VStack gap={2}>+ {actions.map(({label}) => (+ <Text key={label} type="body">+ {label}, button+ </Text>+ ))}+ </VStack>+ </VStack>+ </Card>+ </HStack>++ {/* A real live region: silent to sighted users, announced by AT. */}+ <VisuallyHidden as="div" aria-live="polite">+ Actions available: Download, Share, Delete.+ </VisuallyHidden>+ </VStack>+ );+}diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.doc.mjs b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.doc.mjsnew file mode 100644index 0000000000..9f41ecb9df--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.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: 'VisuallyHidden',+ name: 'VisuallyHidden — Structural Heading',+ displayName: 'VisuallyHidden — Structural Heading',+ description:+ 'Give a visually implicit section an accessible name so screen-reader users can navigate to it.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['VisuallyHidden', 'Card', 'HStack', 'VStack', 'Text', 'Badge'],+};diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.tsx b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.tsxnew file mode 100644index 0000000000..c7fa65a466--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.tsx@@ -0,0 +1,38 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';+import {Card} from '@astryxdesign/core/Card';+import {HStack, VStack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';+import {Badge} from '@astryxdesign/core/Badge';++const items = [+ {name: 'astryx-core', status: 'Passing', variant: 'success'},+ {name: 'astryx-charts', status: 'Failing', variant: 'error'},+ {name: 'astryx-cli', status: 'Passing', variant: 'success'},+] as const;++export default function VisuallyHiddenStructuralHeading() {+ return (+ <VStack gap={3} hAlign="start">+ <Text type="supporting" color="secondary">+ The layout makes this group obvious to sighted users. A hidden heading+ gives screen-reader users the same landmark to jump to.+ </Text>+ {/* No visible heading is needed here, but AT users navigate by heading. */}+ <VisuallyHidden as="h2">Build status</VisuallyHidden>+ <VStack gap={2}>+ {items.map(({name, status, variant}) => (+ <Card key={name} variant="muted" padding={3}>+ <HStack gap={3} vAlign="center">+ <Text type="body">{name}</Text>+ <Badge label={status} variant={variant} />+ </HStack>+ </Card>+ ))}+ </VStack>+ </VStack>+ );+}diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjsnew file mode 100644index 0000000000..b579164c89--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.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: 'VisuallyHidden',+ name: 'VisuallyHidden — Supplementary Context',+ displayName: 'VisuallyHidden — Supplementary Context',+ description:+ 'Add screen-reader-only context to terse visual data, like spelling out what a trend arrow means.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['VisuallyHidden', 'Card', 'HStack', 'VStack', 'Text', 'Icon'],+};diff --git a/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.tsx b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.tsxnew file mode 100644index 0000000000..4021a56180--- /dev/null+++ b/packages/cli/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.tsx@@ -0,0 +1,47 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';+import {Card} from '@astryxdesign/core/Card';+import {HStack, VStack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';+import {Icon} from '@astryxdesign/core/Icon';+import {ArrowUpIcon, ArrowDownIcon} from '@heroicons/react/24/solid';++const stats = [+ {label: 'Revenue', value: '$48.2k', delta: '+12%', direction: 'up'},+ {label: 'Churn', value: '2.1%', delta: '-4%', direction: 'down'},+] as const;++export default function VisuallyHiddenSupplementaryContext() {+ return (+ <HStack gap={4} wrap="wrap">+ {stats.map(({label, value, delta, direction}) => (+ <Card key={label} variant="muted">+ <VStack gap={1}>+ <Text type="supporting" color="secondary">+ {label}+ </Text>+ <Text type="display-3">{value}</Text>+ <HStack gap={1} vAlign="center">+ <Icon+ icon={direction === 'up' ? ArrowUpIcon : ArrowDownIcon}+ size="sm"+ color={direction === 'up' ? 'accent' : 'secondary'}+ />+ <Text type="body">+ {delta}+ {/* The arrow is decorative; spell out the trend for AT. */}+ <VisuallyHidden>+ {direction === 'up' ? ' increase' : ' decrease'} from last+ month+ </VisuallyHidden>+ </Text>+ </HStack>+ </VStack>+ </Card>+ ))}+ </HStack>+ );+}diff --git a/packages/core/src/VisuallyHidden/VisuallyHidden.tsx b/packages/core/src/VisuallyHidden/VisuallyHidden.tsxindex 04d9556771..b4f01e614a 100644--- a/packages/core/src/VisuallyHidden/VisuallyHidden.tsx+++ b/packages/core/src/VisuallyHidden/VisuallyHidden.tsx@@ -13,6 +13,7 @@* - /packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs* - /packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx* - /apps/storybook/stories/VisuallyHidden.stories.tsx+ * - /packages/cli/templates/blocks/components/VisuallyHidden/ (showcase blocks)*/import {createElement, type ElementType, type ReactNode, type Ref} from 'react';