Skip to content

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

TypeScript

docs(ScrollableArea): add block examples for the docsite (#6490)

Ernestdb4e378fa02b
diff --git a/.changeset/scrollable-area-blocks.md b/.changeset/scrollable-area-blocks.md
new file mode 100644
index 0000000000..a8c424be8e
--- /dev/null
+++ b/.changeset/scrollable-area-blocks.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Add ScrollableArea block templates so the component page has worked examples. All six share one content vocabulary — a workspace file panel of labelled sections holding a two-column grid of muted cards — so the only thing that changes between examples is the behavior each one demonstrates: block-axis scrolling, `axis="inline"` with `isFullBleed`, sticky section labels, `axis="both"`, sticky pass-through against `stickyContainment="always"`, and `overscroll` allow against contain.
+
+@ernestt
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 21f97f01cc..a067a343ad 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -2650,6 +2650,31 @@
"path": "examples/resize-handle/resizable-collapsible-with-snap-points",
"aliases": []
},
+ {
+ "name": "example-scrollable-area-inline-rail",
+ "path": "examples/scrollable-area/inline-rail",
+ "aliases": []
+ },
+ {
+ "name": "example-scrollable-area-overscroll",
+ "path": "examples/scrollable-area/overscroll",
+ "aliases": []
+ },
+ {
+ "name": "example-scrollable-area-sticky-passthrough",
+ "path": "examples/scrollable-area/sticky-passthrough",
+ "aliases": []
+ },
+ {
+ "name": "example-scrollable-area-sticky-section-labels",
+ "path": "examples/scrollable-area/sticky-section-labels",
+ "aliases": []
+ },
+ {
+ "name": "example-scrollable-area-two-axis-board",
+ "path": "examples/scrollable-area/two-axis-board",
+ "aliases": []
+ },
{
"name": "example-section-default-with-wash",
"path": "examples/section/default-with-wash",
@@ -4395,6 +4420,11 @@
"path": "showcases/rich-text-editor/default",
"aliases": []
},
+ {
+ "name": "showcase-scrollable-area-default",
+ "path": "showcases/scrollable-area/default",
+ "aliases": []
+ },
{
"name": "showcase-section-variants",
"path": "showcases/section/variants",
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs
new file mode 100644
index 0000000000..44c6e10b75
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ScrollableArea',
+ name: 'ScrollableArea — Inline Rail',
+ displayName: 'Scrollable Area — Inline Rail',
+ description:
+ 'axis="inline" scrolls the same cards sideways; isFullBleed lets the rail run to the panel edges while the content padding keeps the first card aligned with the heading.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ScrollableArea', 'Card', 'Link'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx
new file mode 100644
index 0000000000..5836cea981
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx
@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Link} from '@astryxdesign/core/Link';
+
+const FILES = [
+ {id: 'brief', title: 'Q3 launch brief', meta: 'Edited 2 days ago'},
+ {id: 'pricing', title: 'Pricing rework', meta: 'Edited 3 days ago'},
+ {id: 'onboarding', title: 'Onboarding flow v4', meta: 'Edited 4 days ago'},
+ {id: 'macros', title: 'Support macros', meta: 'Edited last week'},
+ {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+ {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+ {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+];
+
+export default function ScrollableAreaInlineRail() {
+ return (
+ <Card width={460} padding={4}>
+ <VStack gap={3}>
+ <HStack hAlign="between" vAlign="center">
+ <VStack gap={0.5}>
+ <Heading level={3}>Workspace files</Heading>
+ <Text type="supporting">Recently opened</Text>
+ </VStack>
+ <Link href="#files">View all</Link>
+ </HStack>
+ {/* isFullBleed lets the rail reach the card's edges, while the content
+ padding keeps the first card aligned with the heading above it and
+ leaves room under the cards for the scrollbar. */}
+ <ScrollableArea
+ axis="inline"
+ role="region"
+ label="Recently opened files"
+ isFullBleed
+ paddingInline={4}
+ paddingBlockStart={0.5}
+ paddingBlockEnd={4}>
+ <HStack gap={2}>
+ {FILES.map(file => (
+ <Card key={file.id} variant="muted" padding={3} width={170}>
+ <VStack gap={1}>
+ <Text weight="medium" maxLines={1}>
+ {file.title}
+ </Text>
+ <Text type="supporting" maxLines={1}>
+ {file.meta}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </HStack>
+ </ScrollableArea>
+ </VStack>
+ </Card>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs
new file mode 100644
index 0000000000..5ca22f72e7
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ScrollableArea',
+ name: 'ScrollableArea — Overscroll',
+ displayName: 'Scrollable Area — Overscroll',
+ description:
+ 'The same section, two edge policies: the default overscroll="allow" hands a gesture that reaches the end to the panel behind it, while overscroll="contain" stops it at the section edge.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx
new file mode 100644
index 0000000000..522855fb09
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ borderVars,
+ colorVars,
+ radiusVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ // A hairline frame so the nested viewport's edge — the edge the gesture
+ // meets — is visible.
+ sectionFrame: {
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ borderRadius: radiusVars['--radius-element'],
+ },
+});
+
+const SHARED = [
+ {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+ {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+ {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+ {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+ {id: 'tax', title: 'Tax region notes', meta: 'Hugo Bernard'},
+ {id: 'sso', title: 'SSO rollout plan', meta: 'Sofia Marchetti'},
+];
+
+const ARCHIVED = [
+ {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+ {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+ {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+ {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+ {id: 'survey', title: 'Q4 survey results', meta: 'Archived in January'},
+ {id: 'offsite', title: 'Offsite agenda', meta: 'Archived last year'},
+];
+
+function FileGrid({
+ files,
+}: {
+ files: Array<{id: string; title: string; meta: string}>;
+}) {
+ return (
+ <Grid columns={2} gap={2}>
+ {files.map(file => (
+ <Card key={file.id} variant="muted" padding={3}>
+ <VStack gap={1}>
+ <Text weight="medium" maxLines={1}>
+ {file.title}
+ </Text>
+ <Text type="supporting" maxLines={1}>
+ {file.meta}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ );
+}
+
+export default function ScrollableAreaOverscrollChaining() {
+ return (
+ <Card width={400} padding={0}>
+ <ScrollableArea
+ axis="block"
+ role="region"
+ label="Workspace files"
+ height={300}
+ padding={4}>
+ <VStack gap={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>Workspace files</Heading>
+ <Text type="supporting">Two sections, two edge policies</Text>
+ </VStack>
+
+ <VStack gap={2}>
+ <Text type="label" color="secondary">
+ Shared with you
+ </Text>
+ {/* Default overscroll="allow": a gesture that reaches this
+ section's end carries on scrolling the panel behind it. */}
+ <ScrollableArea
+ axis="block"
+ label="Shared with you"
+ height={150}
+ padding={2}
+ xstyle={styles.sectionFrame}>
+ <FileGrid files={SHARED} />
+ </ScrollableArea>
+ <Text type="supporting">
+ Scroll past the end and the panel keeps going.
+ </Text>
+ </VStack>
+
+ <VStack gap={2}>
+ <Text type="label" color="secondary">
+ Archived
+ </Text>
+ {/* overscroll="contain" stops the gesture at this section's
+ edge, so the panel behind it stays put. */}
+ <ScrollableArea
+ axis="block"
+ label="Archived"
+ overscroll="contain"
+ height={150}
+ padding={2}
+ xstyle={styles.sectionFrame}>
+ <FileGrid files={ARCHIVED} />
+ </ScrollableArea>
+ <Text type="supporting">
+ Scroll past the end and the panel stays where it is.
+ </Text>
+ </VStack>
+ </VStack>
+ </ScrollableArea>
+ </Card>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs
new file mode 100644
index 0000000000..00514a2e3a
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ScrollableArea',
+ name: 'ScrollableArea',
+ displayName: 'Scrollable Area',
+ description:
+ 'A fixed-height file panel that scrolls on the block axis; the heading sits inside the viewport, so it scrolls away with the content.',
+ isReady: true,
+ aspectRatio: 1,
+ isShowcase: true,
+ componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx
new file mode 100644
index 0000000000..52156cfb5c
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+
+const SECTIONS = [
+ {
+ label: 'Recently opened',
+ files: [
+ {id: 'brief', title: 'Q3 launch brief', meta: 'Edited 2 days ago'},
+ {id: 'pricing', title: 'Pricing rework', meta: 'Edited 3 days ago'},
+ {
+ id: 'onboarding',
+ title: 'Onboarding flow v4',
+ meta: 'Edited 4 days ago',
+ },
+ {id: 'macros', title: 'Support macros', meta: 'Edited last week'},
+ ],
+ },
+ {
+ label: 'Shared with you',
+ files: [
+ {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+ {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+ {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+ {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+ ],
+ },
+ {
+ label: 'Archived',
+ files: [
+ {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+ {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+ {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+ {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+ ],
+ },
+];
+
+export default function ScrollableAreaShowcase() {
+ return (
+ <Card width={380} padding={0}>
+ {/* The heading sits inside the viewport, so it scrolls away with the
+ content instead of staying pinned above it. */}
+ <ScrollableArea
+ axis="block"
+ role="region"
+ label="Workspace files"
+ height={300}
+ padding={4}>
+ <VStack gap={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>Workspace files</Heading>
+ <Text type="supporting">12 files across 3 sections</Text>
+ </VStack>
+ {SECTIONS.map(section => (
+ <VStack key={section.label} gap={2}>
+ <Text type="label" color="secondary">
+ {section.label}
+ </Text>
+ <Grid columns={2} gap={2}>
+ {section.files.map(file => (
+ <Card key={file.id} variant="muted" padding={3}>
+ <VStack gap={1}>
+ <Text weight="medium" maxLines={1}>
+ {file.title}
+ </Text>
+ <Text type="supporting" maxLines={1}>
+ {file.meta}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ </VStack>
+ ))}
+ </VStack>
+ </ScrollableArea>
+ </Card>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs
new file mode 100644
index 0000000000..c1b022fbea
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ScrollableArea',
+ name: 'ScrollableArea — Sticky Section Labels',
+ displayName: 'Scrollable Area — Sticky Section Labels',
+ description:
+ 'A scrollable viewport is the containing block for position: sticky, so section labels pin to the top edge of the list instead of the page.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx
new file mode 100644
index 0000000000..e82a4bb00f
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx
@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ sectionLabel: {
+ position: 'sticky',
+ insetBlockStart: 0,
+ zIndex: 1,
+ backgroundColor: colorVars['--color-background-card'],
+ paddingBlock: spacingVars['--spacing-2'],
+ },
+});
+
+const SECTIONS = [
+ {
+ label: 'Recently opened',
+ files: [
+ {id: 'brief', title: 'Q3 launch brief', meta: 'Edited 2 days ago'},
+ {id: 'pricing', title: 'Pricing rework', meta: 'Edited 3 days ago'},
+ {
+ id: 'onboarding',
+ title: 'Onboarding flow v4',
+ meta: 'Edited 4 days ago',
+ },
+ {id: 'macros', title: 'Support macros', meta: 'Edited last week'},
+ ],
+ },
+ {
+ label: 'Shared with you',
+ files: [
+ {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+ {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+ {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+ {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+ ],
+ },
+ {
+ label: 'Archived',
+ files: [
+ {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+ {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+ {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+ {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+ ],
+ },
+];
+
+export default function ScrollableAreaStickyGroupHeaders() {
+ return (
+ <Card width={380} padding={0}>
+ {/* The viewport is the containing block for position: sticky. The panel
+ heading is ordinary content and scrolls away; the section labels
+ below it pin to the top of the list, not the page. */}
+ <ScrollableArea
+ axis="block"
+ role="region"
+ label="Workspace files"
+ height={300}
+ padding={4}>
+ <VStack gap={0.5} paddingBlockEnd={2}>
+ <Heading level={3}>Workspace files</Heading>
+ <Text type="supporting">12 files across 3 sections</Text>
+ </VStack>
+ {SECTIONS.map(section => (
+ <section key={section.label}>
+ <div {...stylex.props(styles.sectionLabel)}>
+ <Text type="label" color="secondary">
+ {section.label}
+ </Text>
+ </div>
+ <Grid columns={2} gap={2}>
+ {section.files.map(file => (
+ <Card key={file.id} variant="muted" padding={3}>
+ <VStack gap={1}>
+ <Text weight="medium" maxLines={1}>
+ {file.title}
+ </Text>
+ <Text type="supporting" maxLines={1}>
+ {file.meta}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ </section>
+ ))}
+ </ScrollableArea>
+ </Card>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs
new file mode 100644
index 0000000000..94f6d447a7
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ScrollableArea',
+ name: 'ScrollableArea — Sticky Passthrough',
+ displayName: 'Scrollable Area — Sticky Passthrough',
+ description:
+ 'A section whose content fits clips instead of scrolling, so its sticky label passes outward and pins to the panel edge. The next section sets stickyContainment="always" and keeps its label in its own box.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx
new file mode 100644
index 0000000000..24ce1f6f64
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx
@@ -0,0 +1,122 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ sectionLabel: {
+ position: 'sticky',
+ insetBlockStart: 0,
+ zIndex: 1,
+ backgroundColor: colorVars['--color-background-card'],
+ paddingBlock: spacingVars['--spacing-2'],
+ },
+});
+
+const SHARED = [
+ {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+ {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+ {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+ {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+ {id: 'tax', title: 'Tax region notes', meta: 'Hugo Bernard'},
+ {id: 'sso', title: 'SSO rollout plan', meta: 'Sofia Marchetti'},
+];
+
+const TEMPLATES = [
+ {id: 'weekly', title: 'Weekly report', meta: 'Used 24 times'},
+ {id: 'checklist', title: 'Launch checklist', meta: 'Used 18 times'},
+ {id: 'review', title: 'Design review', meta: 'Used 11 times'},
+ {id: 'retro', title: 'Retro board', meta: 'Used 9 times'},
+ {id: 'brief', title: 'Project brief', meta: 'Used 7 times'},
+ {id: 'postmortem', title: 'Postmortem', meta: 'Used 4 times'},
+];
+
+const ARCHIVED = [
+ {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+ {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+ {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+ {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+ {id: 'survey', title: 'Q4 survey results', meta: 'Archived in January'},
+ {id: 'offsite', title: 'Offsite agenda', meta: 'Archived last year'},
+];
+
+function FileGrid({
+ files,
+}: {
+ files: Array<{id: string; title: string; meta: string}>;
+}) {
+ return (
+ <Grid columns={2} gap={2}>
+ {files.map(file => (
+ <Card key={file.id} variant="muted" padding={3}>
+ <VStack gap={1}>
+ <Text weight="medium" maxLines={1}>
+ {file.title}
+ </Text>
+ <Text type="supporting" maxLines={1}>
+ {file.meta}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ );
+}
+
+export default function ScrollableAreaStickyPassthrough() {
+ return (
+ <Card width={400} padding={0}>
+ <ScrollableArea
+ axis="block"
+ role="region"
+ label="Workspace files"
+ height={300}
+ padding={4}>
+ <VStack gap={0.5} paddingBlockEnd={2}>
+ <Heading level={3}>Workspace files</Heading>
+ <Text type="supporting">18 files across 3 sections</Text>
+ </VStack>
+
+ {/* This section's content fits, so its viewport clips instead of
+ scrolling and never becomes the Sticky boundary: the label
+ passes outward and pins to the panel's edge. */}
+ <ScrollableArea axis="block" label="Shared with you">
+ <div {...stylex.props(styles.sectionLabel)}>
+ <Text type="label" color="secondary">
+ Shared with you
+ </Text>
+ </div>
+ <FileGrid files={SHARED} />
+ </ScrollableArea>
+
+ {/* Same fitting content, but containment is explicit: this viewport
+ stays the Sticky boundary, so its label leaves with the box. */}
+ <ScrollableArea
+ axis="block"
+ label="Templates"
+ stickyContainment="always">
+ <div {...stylex.props(styles.sectionLabel)}>
+ <Text type="label" color="secondary">
+ Templates
+ </Text>
+ </div>
+ <FileGrid files={TEMPLATES} />
+ </ScrollableArea>
+
+ <div {...stylex.props(styles.sectionLabel)}>
+ <Text type="label" color="secondary">
+ Archived
+ </Text>
+ </div>
+ <FileGrid files={ARCHIVED} />
+ </ScrollableArea>
+ </Card>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs
new file mode 100644
index 0000000000..b4a8a853f4
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ScrollableArea',
+ name: 'ScrollableArea — Two-Axis Board',
+ displayName: 'Scrollable Area — Two-Axis Board',
+ description:
+ 'axis="both" gives the content box max-content inline sizing, so a board wider and taller than its panel scrolls on both axes from one viewport.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx
new file mode 100644
index 0000000000..396437b523
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx
@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+
+const COLUMNS = [
+ {
+ label: 'Recently opened',
+ files: [
+ {id: 'brief', title: 'Q3 launch brief', meta: 'Edited 2 days ago'},
+ {id: 'pricing', title: 'Pricing rework', meta: 'Edited 3 days ago'},
+ {
+ id: 'onboarding',
+ title: 'Onboarding flow v4',
+ meta: 'Edited 4 days ago',
+ },
+ {id: 'macros', title: 'Support macros', meta: 'Edited last week'},
+ ],
+ },
+ {
+ label: 'Shared with you',
+ files: [
+ {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+ {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+ {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+ {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+ ],
+ },
+ {
+ label: 'Templates',
+ files: [
+ {id: 'weekly', title: 'Weekly report', meta: 'Used 24 times'},
+ {id: 'checklist', title: 'Launch checklist', meta: 'Used 18 times'},
+ {id: 'review', title: 'Design review', meta: 'Used 11 times'},
+ {id: 'retro', title: 'Retro board', meta: 'Used 9 times'},
+ ],
+ },
+ {
+ label: 'Archived',
+ files: [
+ {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+ {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+ {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+ {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+ ],
+ },
+];
+
+export default function ScrollableAreaTwoAxisBoard() {
+ return (
+ <Card width={420} padding={0}>
+ {/* axis="both" gives the content box max-content inline sizing, so the
+ board is free to be wider than the viewport on both axes. The
+ heading is inside that box and travels with it. */}
+ <ScrollableArea
+ axis="both"
+ role="region"
+ label="Workspace board"
+ height={300}
+ padding={4}>
+ <VStack gap={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>Workspace board</Heading>
+ <Text type="supporting">16 files across 4 sections</Text>
+ </VStack>
+ <HStack gap={3} vAlign="start">
+ {COLUMNS.map(column => (
+ <VStack key={column.label} gap={2} width={180}>
+ <Text type="label" color="secondary">
+ {column.label}
+ </Text>
+ {column.files.map(file => (
+ <Card key={file.id} variant="muted" padding={3}>
+ <VStack gap={1}>
+ <Text weight="medium" maxLines={1}>
+ {file.title}
+ </Text>
+ <Text type="supporting" maxLines={1}>
+ {file.meta}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </VStack>
+ ))}
+ </HStack>
+ </VStack>
+ </ScrollableArea>
+ </Card>
+ );
+}
diff --git a/packages/core/src/ScrollableArea/ScrollableArea.tsx b/packages/core/src/ScrollableArea/ScrollableArea.tsx
index 738c76f194..f122da16db 100644
--- a/packages/core/src/ScrollableArea/ScrollableArea.tsx
+++ b/packages/core/src/ScrollableArea/ScrollableArea.tsx
@@ -12,6 +12,7 @@
* - /packages/core/src/ScrollableArea/ScrollableArea.test.tsx
* - /packages/core/src/ScrollableArea/ScrollableArea.doc.mjs
* - /apps/storybook/stories/ScrollableArea.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/ScrollableArea/ (showcase blocks)
*/
import type {ReactNode} from 'react';