Skip to content

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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
index 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';