Skip to content

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

TypeScript

docs: add example blocks for 46 components with no viewable code (#2759) (#3481)

AK2200fc9744b0
diff --git a/packages/cli/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.doc.mjs b/packages/cli/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.doc.mjs
new file mode 100644
index 0000000000..881c18c41c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.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: 'AvatarStatusDot',
+ name: 'AvatarStatusDot — Variants',
+ displayName: 'AvatarStatusDot — Variants',
+ description:
+ 'Presence dots on Avatars using the success, neutral, and error variants. Pass an AvatarStatusDot to the Avatar status prop; the dot sizes itself to match the Avatar.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Avatar', 'AvatarStatusDot', 'HStack'],
+};
diff --git a/packages/cli/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.tsx b/packages/cli/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.tsx
new file mode 100644
index 0000000000..933edf8ce6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.tsx
@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
+import {HStack} from '@astryxdesign/core/Layout';
+
+export default function AvatarStatusDotVariants() {
+ return (
+ <HStack gap={4} vAlign="center">
+ <Avatar
+ name="Ana Silva"
+ size="large"
+ status={<AvatarStatusDot variant="success" label="Online" />}
+ />
+ <Avatar
+ name="Ben Okafor"
+ size="large"
+ status={<AvatarStatusDot variant="neutral" label="Away" />}
+ />
+ <Avatar
+ name="Cleo Marsh"
+ size="large"
+ status={<AvatarStatusDot variant="error" label="Do not disturb" />}
+ />
+ </HStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.doc.mjs b/packages/cli/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.doc.mjs
new file mode 100644
index 0000000000..6e39a7aa45
--- /dev/null
+++ b/packages/cli/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.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: 'BreadcrumbItem',
+ name: 'BreadcrumbItem — Basic',
+ displayName: 'BreadcrumbItem — Basic',
+ description:
+ 'Breadcrumb links inside a Breadcrumbs trail. Ancestor pages get an href; mark the last item with isCurrent to render it as plain text for the current page.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Breadcrumbs', 'BreadcrumbItem'],
+};
diff --git a/packages/cli/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.tsx b/packages/cli/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.tsx
new file mode 100644
index 0000000000..effdf02756
--- /dev/null
+++ b/packages/cli/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.tsx
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Breadcrumbs, BreadcrumbItem} from '@astryxdesign/core/Breadcrumbs';
+
+export default function BreadcrumbItemBasic() {
+ return (
+ <Breadcrumbs>
+ <BreadcrumbItem href="/">Home</BreadcrumbItem>
+ <BreadcrumbItem href="/settings">Settings</BreadcrumbItem>
+ <BreadcrumbItem isCurrent>Profile</BreadcrumbItem>
+ </Breadcrumbs>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupBasic.doc.mjs b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupBasic.doc.mjs
new file mode 100644
index 0000000000..363c145342
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupBasic.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: 'ButtonGroup',
+ name: 'ButtonGroup — Basic',
+ displayName: 'ButtonGroup — Basic',
+ description:
+ 'Three related actions joined into a single connected control. Provide a group label for accessibility and keep all buttons the same variant so they read as one unit.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ButtonGroup', 'Button'],
+};
diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupBasic.tsx b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupBasic.tsx
new file mode 100644
index 0000000000..0504fe8c4d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupBasic.tsx
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ButtonGroup} from '@astryxdesign/core/ButtonGroup';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function ButtonGroupBasic() {
+ return (
+ <ButtonGroup label="Text editing actions">
+ <Button label="Copy" />
+ <Button label="Cut" />
+ <Button label="Paste" />
+ </ButtonGroup>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.doc.mjs b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.doc.mjs
new file mode 100644
index 0000000000..e1bc4a00d0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.doc.mjs
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ChatDictationButton',
+ name: 'ChatDictationButton — Basic',
+ displayName: 'ChatDictationButton — Basic',
+ description:
+ 'A dictation button wired to useChatDictation and placed in the sendActions slot of a ChatComposer. Click the microphone to transcribe speech into the input.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'Chat',
+ 'ChatDictationButton',
+ 'ChatComposer',
+ 'ChatComposerInput',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.tsx b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.tsx
new file mode 100644
index 0000000000..69950a5bed
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.tsx
@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useRef} from 'react';
+import {
+ ChatDictationButton,
+ ChatComposer,
+ ChatComposerInput,
+ useChatDictation,
+} from '@astryxdesign/core/Chat';
+import type {ChatComposerInputHandle} from '@astryxdesign/core/Chat';
+import {Stack} from '@astryxdesign/core/Layout';
+
+export default function ChatDictationButtonBasic() {
+ const inputRef = useRef<ChatComposerInputHandle>(null);
+
+ const dictation = useChatDictation({
+ inputRef,
+ onResult: text => {
+ console.log('Dictation result:', text);
+ },
+ });
+
+ return (
+ <Stack direction="vertical" width="100%" style={{maxWidth: 450}}>
+ <ChatComposer
+ onSubmit={value => console.log('Submit:', value)}
+ input={<ChatComposerInput handleRef={inputRef} />}
+ sendActions={<ChatDictationButton dictation={dictation} />}
+ />
+ </Stack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.doc.mjs b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.doc.mjs
new file mode 100644
index 0000000000..7b7af0e5ab
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.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: 'CheckboxListItem',
+ name: 'CheckboxListItem — Basic',
+ displayName: 'CheckboxListItem — Basic',
+ description:
+ 'Checkbox items with labels and descriptions inside a controlled CheckboxList. Use for multi-select option groups like notification preferences.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CheckboxList', 'CheckboxListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.tsx b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.tsx
new file mode 100644
index 0000000000..38b90bee1b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.tsx
@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
+
+export default function CheckboxListItemBasic() {
+ const [value, setValue] = useState<string[]>(['updates']);
+
+ return (
+ <CheckboxList label="Email preferences" value={value} onChange={setValue}>
+ <CheckboxListItem
+ label="Product updates"
+ value="updates"
+ description="New features and improvements"
+ />
+ <CheckboxListItem
+ label="Security alerts"
+ value="security"
+ description="Important account security notifications"
+ />
+ <CheckboxListItem
+ label="Marketing"
+ value="marketing"
+ description="Tips, offers, and promotions"
+ />
+ </CheckboxList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.doc.mjs b/packages/cli/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.doc.mjs
new file mode 100644
index 0000000000..f9ced5ad5f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.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: 'CollapsibleGroup',
+ name: 'CollapsibleGroup — Accordion',
+ displayName: 'CollapsibleGroup — Accordion',
+ description:
+ 'An accordion built with type="single": opening one Collapsible automatically closes the others. Use defaultValue to pre-expand the most important section.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CollapsibleGroup', 'Collapsible', 'VStack', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.tsx b/packages/cli/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.tsx
new file mode 100644
index 0000000000..05c721dfda
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.tsx
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Collapsible, CollapsibleGroup} from '@astryxdesign/core/Collapsible';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function CollapsibleGroupAccordion() {
+ return (
+ <CollapsibleGroup type="single" defaultValue="account">
+ <VStack gap={2} width="100%">
+ <Collapsible trigger="Account" value="account">
+ <Text type="body" color="secondary">
+ Manage your profile details, email address, and password.
+ </Text>
+ </Collapsible>
+ <Collapsible trigger="Notifications" value="notifications">
+ <Text type="body" color="secondary">
+ Choose which activity triggers email and push notifications.
+ </Text>
+ </Collapsible>
+ <Collapsible trigger="Billing" value="billing">
+ <Text type="body" color="secondary">
+ View invoices and update your payment method.
+ </Text>
+ </Collapsible>
+ </VStack>
+ </CollapsibleGroup>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.doc.mjs
new file mode 100644
index 0000000000..35d47656e0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.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: 'CommandPaletteEmpty',
+ name: 'CommandPaletteEmpty — Basic',
+ displayName: 'CommandPaletteEmpty — Basic',
+ description:
+ 'A command palette with no results, showing a custom empty message via emptyBootstrapText. Use to explain why the palette is empty and what the user can do next.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CommandPalette', 'CommandPaletteEmpty', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.tsx b/packages/cli/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.tsx
new file mode 100644
index 0000000000..8cd7d6ce0d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.tsx
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useMemo} from 'react';
+import {CommandPalette} from '@astryxdesign/core/CommandPalette';
+import {Text} from '@astryxdesign/core/Text';
+import {createStaticSource} from '@astryxdesign/core/Typeahead';
+
+export default function CommandPaletteEmptyBasic() {
+ const emptySource = useMemo(() => createStaticSource([]), []);
+
+ return (
+ <CommandPalette
+ isOpen
+ isInline
+ onOpenChange={() => {}}
+ searchSource={emptySource}
+ emptyBootstrapText={
+ <Text type="supporting" color="secondary">
+ No commands available
+ </Text>
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.doc.mjs
new file mode 100644
index 0000000000..70dae142f6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.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: 'CommandPaletteFooter',
+ name: 'CommandPaletteFooter — Basic',
+ displayName: 'CommandPaletteFooter — Basic',
+ description:
+ 'A command palette footer with no children, rendering the built-in keyboard navigation hints. Use CommandPaletteFooter without content to get the default arrow-key, Enter, and Esc hints below the results list.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CommandPalette', 'CommandPaletteFooter'],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.tsx b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.tsx
new file mode 100644
index 0000000000..cec5a3fdcc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.tsx
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useMemo} from 'react';
+import {
+ CommandPalette,
+ CommandPaletteFooter,
+} from '@astryxdesign/core/CommandPalette';
+import {createStaticSource} from '@astryxdesign/core/Typeahead';
+
+export default function CommandPaletteFooterBasic() {
+ const source = useMemo(
+ () =>
+ createStaticSource([
+ {id: 'new-file', label: 'New File'},
+ {id: 'open-recent', label: 'Open Recent'},
+ {id: 'save-all', label: 'Save All'},
+ ]),
+ [],
+ );
+
+ return (
+ <CommandPalette
+ isOpen
+ isInline
+ onOpenChange={() => {}}
+ searchSource={source}
+ footer={<CommandPaletteFooter />}
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupBasic.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupBasic.doc.mjs
new file mode 100644
index 0000000000..5f39075466
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupBasic.doc.mjs
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'CommandPaletteGroup',
+ name: 'CommandPaletteGroup — Basic',
+ displayName: 'CommandPaletteGroup — Basic',
+ description:
+ 'Command palette items organized under group headings using the composed CommandPaletteGroup form. Use to separate related commands into labeled sections.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'CommandPaletteGroup',
+ 'CommandPaletteItem',
+ 'CommandPaletteList',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupBasic.tsx b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupBasic.tsx
new file mode 100644
index 0000000000..7e377d806c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupBasic.tsx
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ CommandPaletteList,
+ CommandPaletteGroup,
+ CommandPaletteItem,
+} from '@astryxdesign/core/CommandPalette';
+
+export default function CommandPaletteGroupBasic() {
+ return (
+ <CommandPaletteList>
+ <CommandPaletteGroup heading="Navigation">
+ <CommandPaletteItem value="home" onSelect={() => {}}>
+ Go to Home
+ </CommandPaletteItem>
+ <CommandPaletteItem value="dashboard" onSelect={() => {}}>
+ Go to Dashboard
+ </CommandPaletteItem>
+ </CommandPaletteGroup>
+ <CommandPaletteGroup heading="Actions">
+ <CommandPaletteItem value="new-file" onSelect={() => {}}>
+ New File
+ </CommandPaletteItem>
+ <CommandPaletteItem value="save-all" onSelect={() => {}}>
+ Save All
+ </CommandPaletteItem>
+ </CommandPaletteGroup>
+ </CommandPaletteList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemBasic.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemBasic.doc.mjs
new file mode 100644
index 0000000000..941f072dd5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemBasic.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: 'CommandPaletteItem',
+ name: 'CommandPaletteItem — Basic',
+ displayName: 'CommandPaletteItem — Basic',
+ description:
+ 'Selectable command palette items inside a CommandPaletteList, including highlighted and disabled states. Use when composing a palette manually instead of a search source.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['CommandPaletteItem', 'CommandPaletteList'],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemBasic.tsx b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemBasic.tsx
new file mode 100644
index 0000000000..76dc06e3cc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemBasic.tsx
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ CommandPaletteList,
+ CommandPaletteItem,
+} from '@astryxdesign/core/CommandPalette';
+
+export default function CommandPaletteItemBasic() {
+ return (
+ <CommandPaletteList>
+ <CommandPaletteItem value="new-file" onSelect={() => {}}>
+ New File
+ </CommandPaletteItem>
+ <CommandPaletteItem value="open-recent" isHighlighted onSelect={() => {}}>
+ Open Recent
+ </CommandPaletteItem>
+ <CommandPaletteItem value="save-all" onSelect={() => {}}>
+ Save All
+ </CommandPaletteItem>
+ <CommandPaletteItem value="publish" isDisabled>
+ Publish (disabled)
+ </CommandPaletteItem>
+ </CommandPaletteList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ContextMenu/ContextMenuBasic.doc.mjs b/packages/cli/templates/blocks/components/ContextMenu/ContextMenuBasic.doc.mjs
new file mode 100644
index 0000000000..aa651947d9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ContextMenu/ContextMenuBasic.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: 'ContextMenu',
+ name: 'ContextMenu — Basic',
+ displayName: 'ContextMenu — Basic',
+ description:
+ 'A right-click area with action items and a divider separating a destructive action. Use to provide contextual actions for a specific element or region.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ContextMenu'],
+};
diff --git a/packages/cli/templates/blocks/components/ContextMenu/ContextMenuBasic.tsx b/packages/cli/templates/blocks/components/ContextMenu/ContextMenuBasic.tsx
new file mode 100644
index 0000000000..0d04542268
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ContextMenu/ContextMenuBasic.tsx
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ContextMenu} from '@astryxdesign/core/ContextMenu';
+
+export default function ContextMenuBasic() {
+ return (
+ <ContextMenu
+ items={[
+ {label: 'Cut', onClick: () => {}},
+ {label: 'Copy', onClick: () => {}},
+ {label: 'Paste', onClick: () => {}},
+ {type: 'divider'},
+ {label: 'Delete', onClick: () => {}},
+ ]}>
+ <div
+ style={{
+ padding: '48px',
+ borderWidth: '2px',
+ borderStyle: 'dashed',
+ borderColor: '#d1d5db',
+ borderRadius: '8px',
+ textAlign: 'center',
+ color: '#6b7280',
+ userSelect: 'none',
+ }}>
+ Right-click this area
+ </div>
+ </ContextMenu>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/DialogHeader/DialogHeaderBasic.doc.mjs b/packages/cli/templates/blocks/components/DialogHeader/DialogHeaderBasic.doc.mjs
new file mode 100644
index 0000000000..4a999c91db
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DialogHeader/DialogHeaderBasic.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: 'DialogHeader',
+ name: 'DialogHeader — Basic',
+ displayName: 'DialogHeader — Basic',
+ description:
+ 'A DialogHeader with a title, subtitle, and close button, placed in the header slot of a Dialog Layout. Pass onOpenChange to render the close button.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Dialog', 'DialogHeader', 'Layout', 'LayoutContent', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/DialogHeader/DialogHeaderBasic.tsx b/packages/cli/templates/blocks/components/DialogHeader/DialogHeaderBasic.tsx
new file mode 100644
index 0000000000..a7dab33cac
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DialogHeader/DialogHeaderBasic.tsx
@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Dialog, DialogHeader} from '@astryxdesign/core/Dialog';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DialogHeaderBasic() {
+ return (
+ <Dialog isOpen isInline onOpenChange={() => {}}>
+ <Layout
+ header={
+ <DialogHeader
+ title="Invite teammates"
+ subtitle="Send invitations to join your workspace"
+ onOpenChange={() => {}}
+ />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body" color="secondary">
+ Dialog body content goes here.
+ </Text>
+ </LayoutContent>
+ }
+ />
+ </Dialog>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx b/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx
index 495e1aed5c..1d9ce50ba3 100644
--- a/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx
+++ b/packages/cli/templates/blocks/components/DropdownMenu/DropdownMenuShowcase.tsx
@@ -2,16 +2,11 @@
'use client';
-import {useState} from 'react';
import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';
export default function DropdownMenuShowcase() {
- const [isMenuOpen, setIsMenuOpen] = useState(false);
-
return (
<DropdownMenu
- isMenuOpen={isMenuOpen}
- onOpenChange={setIsMenuOpen}
button={{label: 'Actions'}}
items={[
{label: 'Edit', onClick: () => {}},
diff --git a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemBasic.doc.mjs b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemBasic.doc.mjs
new file mode 100644
index 0000000000..4fc12aeb0a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemBasic.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: 'DropdownMenuItem',
+ name: 'DropdownMenuItem — Basic',
+ displayName: 'DropdownMenuItem — Basic',
+ description:
+ 'Dropdown menu items with labels and secondary descriptions. Use DropdownMenuItem to render custom menu entries with consistent styling.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['DropdownMenu', 'DropdownMenuItem'],
+};
diff --git a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemBasic.tsx b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemBasic.tsx
new file mode 100644
index 0000000000..ab4746ee85
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemBasic.tsx
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {DropdownMenu, DropdownMenuItem} from '@astryxdesign/core/DropdownMenu';
+
+export default function DropdownMenuItemBasic() {
+ return (
+ <DropdownMenu button={{label: 'Actions'}}>
+ <DropdownMenuItem
+ label="Edit"
+ description="Modify this item"
+ onClick={() => {}}
+ />
+ <DropdownMenuItem
+ label="Duplicate"
+ description="Create a copy"
+ onClick={() => {}}
+ />
+ <DropdownMenuItem
+ label="Delete"
+ description="This action cannot be undone"
+ onClick={() => {}}
+ />
+ </DropdownMenu>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
index f7b74dc490..639f9a737b 100644
--- a/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
+++ b/packages/cli/templates/blocks/components/DropdownMenuItem/DropdownMenuItemShowcase.tsx
@@ -65,10 +65,7 @@ const TrashIcon = (props: React.SVGProps<SVGSVGElement>) => (
export default function DropdownMenuItemShowcase() {
return (
- <DropdownMenu
- button={{label: 'Actions'}}
- isMenuOpen
- onOpenChange={() => {}}>
+ <DropdownMenu button={{label: 'Actions'}}>
<DropdownMenuItem
icon={PencilIcon}
label="Edit"
diff --git a/packages/cli/templates/blocks/components/FieldLabel/FieldLabelBasic.doc.mjs b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelBasic.doc.mjs
new file mode 100644
index 0000000000..ce9fdbb0c4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelBasic.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: 'FieldLabel',
+ name: 'FieldLabel — Basic',
+ displayName: 'FieldLabel — Basic',
+ description:
+ 'Standalone labels with required and optional indicators and a helper description. Use when labeling a custom control that does not render its own label.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Field', 'FieldLabel', 'VStack'],
+};
diff --git a/packages/cli/templates/blocks/components/FieldLabel/FieldLabelBasic.tsx b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelBasic.tsx
new file mode 100644
index 0000000000..fe28552015
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldLabel/FieldLabelBasic.tsx
@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {FieldLabel} from '@astryxdesign/core/Field';
+import {VStack} from '@astryxdesign/core/Layout';
+
+export default function FieldLabelBasic() {
+ return (
+ <VStack gap={4}>
+ <FieldLabel label="Email address" inputID="email-input" isRequired />
+ <FieldLabel
+ label="Phone number"
+ inputID="phone-input"
+ isOptional
+ description="Include country code for international numbers"
+ />
+ </VStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusBasic.doc.mjs b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusBasic.doc.mjs
new file mode 100644
index 0000000000..8c869b242d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusBasic.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: 'FieldStatus',
+ name: 'FieldStatus — Basic',
+ displayName: 'FieldStatus — Basic',
+ description:
+ 'Detached error and success messages for validation feedback. Use below checkboxes, switches, or custom controls where an attached status would overlap.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['FieldStatus', 'VStack'],
+};
diff --git a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusBasic.tsx b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusBasic.tsx
new file mode 100644
index 0000000000..e3d27cc574
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusBasic.tsx
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {FieldStatus} from '@astryxdesign/core/FieldStatus';
+import {VStack} from '@astryxdesign/core/Layout';
+
+export default function FieldStatusBasic() {
+ return (
+ <VStack gap={4}>
+ <FieldStatus
+ type="error"
+ message="This field is required"
+ variant="detached"
+ />
+ <FieldStatus
+ type="success"
+ message="Your changes have been saved"
+ variant="detached"
+ />
+ </VStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/FileInput/FileInputBasic.doc.mjs b/packages/cli/templates/blocks/components/FileInput/FileInputBasic.doc.mjs
new file mode 100644
index 0000000000..8a553be90a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FileInput/FileInputBasic.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: 'FileInput',
+ name: 'FileInput — Basic',
+ displayName: 'FileInput — Basic',
+ description:
+ 'A controlled single-file upload with accepted types, a size limit, and helper text. Use for standard document upload fields in forms.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['FileInput'],
+};
diff --git a/packages/cli/templates/blocks/components/FileInput/FileInputBasic.tsx b/packages/cli/templates/blocks/components/FileInput/FileInputBasic.tsx
new file mode 100644
index 0000000000..44d77e4421
--- /dev/null
+++ b/packages/cli/templates/blocks/components/FileInput/FileInputBasic.tsx
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {FileInput} from '@astryxdesign/core/FileInput';
+
+export default function FileInputBasic() {
+ const [value, setValue] = useState<File | File[] | null>(null);
+ return (
+ <div style={{width: 350}}>
+ <FileInput
+ label="Resume"
+ value={value}
+ onChange={setValue}
+ accept=".pdf,.docx"
+ description="PDF or Word document, up to 5 MB"
+ maxSize={5 * 1024 * 1024}
+ />
+ </div>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/GridSpan/GridSpanColumns.doc.mjs b/packages/cli/templates/blocks/components/GridSpan/GridSpanColumns.doc.mjs
new file mode 100644
index 0000000000..9071b10111
--- /dev/null
+++ b/packages/cli/templates/blocks/components/GridSpan/GridSpanColumns.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: 'GridSpan',
+ name: 'GridSpan — Columns',
+ displayName: 'GridSpan — Columns',
+ description:
+ 'Grid items spanning two of three columns. Wrap a grid child in GridSpan to make it occupy multiple columns for asymmetric layouts.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['GridSpan', 'Grid', 'Card', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/GridSpan/GridSpanColumns.tsx b/packages/cli/templates/blocks/components/GridSpan/GridSpanColumns.tsx
new file mode 100644
index 0000000000..1e41033a5e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/GridSpan/GridSpanColumns.tsx
@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Grid, GridSpan} from '@astryxdesign/core/Grid';
+import {Card} from '@astryxdesign/core/Card';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function GridSpanColumns() {
+ return (
+ <Grid columns={3} gap={3} width={400}>
+ <GridSpan columns={2}>
+ <Card height={80}>
+ <Text type="body" color="secondary">
+ Spans 2 columns
+ </Text>
+ </Card>
+ </GridSpan>
+ <Card height={80}>
+ <Text type="body" color="secondary">
+ 1 col
+ </Text>
+ </Card>
+ <Card height={80}>
+ <Text type="body" color="secondary">
+ 1 col
+ </Text>
+ </Card>
+ <GridSpan columns={2}>
+ <Card height={80}>
+ <Text type="body" color="secondary">
+ Spans 2 columns
+ </Text>
+ </Card>
+ </GridSpan>
+ </Grid>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/HStack/HStackBasic.doc.mjs b/packages/cli/templates/blocks/components/HStack/HStackBasic.doc.mjs
new file mode 100644
index 0000000000..9aded3eba2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/HStack/HStackBasic.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: 'HStack',
+ name: 'HStack — Basic',
+ displayName: 'HStack — Basic',
+ description:
+ 'Items arranged in a horizontal row with a consistent gap and centered vertical alignment. Use HStack whenever siblings should sit side by side.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['HStack', 'Badge'],
+};
diff --git a/packages/cli/templates/blocks/components/HStack/HStackBasic.tsx b/packages/cli/templates/blocks/components/HStack/HStackBasic.tsx
new file mode 100644
index 0000000000..5de7a890ab
--- /dev/null
+++ b/packages/cli/templates/blocks/components/HStack/HStackBasic.tsx
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {HStack} from '@astryxdesign/core/Layout';
+import {Badge} from '@astryxdesign/core/Badge';
+
+export default function HStackBasic() {
+ return (
+ <HStack gap={2} vAlign="center">
+ <Badge label="React" />
+ <Badge label="TypeScript" />
+ <Badge label="Node.js" />
+ </HStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/InputGroup/InputGroupBasic.doc.mjs b/packages/cli/templates/blocks/components/InputGroup/InputGroupBasic.doc.mjs
new file mode 100644
index 0000000000..dc5a8a4e11
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InputGroup/InputGroupBasic.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: 'InputGroup',
+ name: 'InputGroup — Basic',
+ displayName: 'InputGroup — Basic',
+ description:
+ 'A currency field with static prefix and suffix addons around a TextInput. Use InputGroupText to clarify units or input format.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['InputGroup', 'InputGroupText', 'TextInput'],
+};
diff --git a/packages/cli/templates/blocks/components/InputGroup/InputGroupBasic.tsx b/packages/cli/templates/blocks/components/InputGroup/InputGroupBasic.tsx
new file mode 100644
index 0000000000..587adfb581
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InputGroup/InputGroupBasic.tsx
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {InputGroup, InputGroupText} from '@astryxdesign/core/InputGroup';
+import {TextInput} from '@astryxdesign/core/TextInput';
+
+export default function InputGroupBasic() {
+ const [price, setPrice] = useState('');
+
+ return (
+ <div style={{width: 320}}>
+ <InputGroup label="Price">
+ <InputGroupText>$</InputGroupText>
+ <TextInput
+ label="Amount"
+ isLabelHidden
+ value={price}
+ onChange={setPrice}
+ placeholder="0.00"
+ />
+ <InputGroupText>USD</InputGroupText>
+ </InputGroup>
+ </div>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/LayoutContent/LayoutContentBasic.doc.mjs b/packages/cli/templates/blocks/components/LayoutContent/LayoutContentBasic.doc.mjs
new file mode 100644
index 0000000000..7d050eaeae
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutContent/LayoutContentBasic.doc.mjs
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'LayoutContent',
+ name: 'LayoutContent — Basic',
+ displayName: 'LayoutContent — Basic',
+ description:
+ 'A scrollable main content area below a fixed header. Use LayoutContent inside Layout to get automatic padding and scroll containment for the primary content.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'LayoutContent',
+ 'Layout',
+ 'LayoutHeader',
+ 'Center',
+ 'Card',
+ 'VStack',
+ 'Heading',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/LayoutContent/LayoutContentBasic.tsx b/packages/cli/templates/blocks/components/LayoutContent/LayoutContentBasic.tsx
new file mode 100644
index 0000000000..b80aa939bb
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutContent/LayoutContentBasic.tsx
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ Layout,
+ LayoutContent,
+ LayoutHeader,
+ Card,
+ VStack,
+} from '@astryxdesign/core/Layout';
+import {Center} from '@astryxdesign/core/Center';
+import {Text, Heading} from '@astryxdesign/core/Text';
+
+export default function LayoutContentBasic() {
+ return (
+ <Center width={400}>
+ <Layout
+ style={{width: '100%'}}
+ height="fill"
+ header={
+ <LayoutHeader hasDivider>
+ <Card variant="muted" />
+ </LayoutHeader>
+ }
+ content={
+ <LayoutContent role="main">
+ <VStack gap={3}>
+ <Heading level={5}>Main Content</Heading>
+ <Text type="body" color="secondary">
+ LayoutContent fills the remaining space and scrolls when its
+ content overflows, while the header stays fixed.
+ </Text>
+ </VStack>
+ </LayoutContent>
+ }
+ />
+ </Center>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/LayoutFooter/LayoutFooterActions.doc.mjs b/packages/cli/templates/blocks/components/LayoutFooter/LayoutFooterActions.doc.mjs
new file mode 100644
index 0000000000..208645a8cd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutFooter/LayoutFooterActions.doc.mjs
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'LayoutFooter',
+ name: 'LayoutFooter — Actions',
+ displayName: 'LayoutFooter — Actions',
+ description:
+ 'A fixed footer with end-aligned action buttons below scrollable content. Use LayoutFooter inside Layout for persistent actions like Save and Cancel.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'LayoutFooter',
+ 'Layout',
+ 'LayoutContent',
+ 'Center',
+ 'Card',
+ 'HStack',
+ 'Button',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/LayoutFooter/LayoutFooterActions.tsx b/packages/cli/templates/blocks/components/LayoutFooter/LayoutFooterActions.tsx
new file mode 100644
index 0000000000..43d71363d1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutFooter/LayoutFooterActions.tsx
@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ Layout,
+ LayoutContent,
+ LayoutFooter,
+ Card,
+ HStack,
+} from '@astryxdesign/core/Layout';
+import {Center} from '@astryxdesign/core/Center';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function LayoutFooterActions() {
+ return (
+ <Center width={400}>
+ <Layout
+ style={{width: '100%'}}
+ height="fill"
+ content={
+ <LayoutContent>
+ <Card variant="muted" />
+ </LayoutContent>
+ }
+ footer={
+ <LayoutFooter hasDivider>
+ <HStack gap={2} hAlign="end">
+ <Button label="Cancel" variant="secondary">
+ Cancel
+ </Button>
+ <Button label="Save" variant="primary">
+ Save
+ </Button>
+ </HStack>
+ </LayoutFooter>
+ }
+ />
+ </Center>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/LayoutHeader/LayoutHeaderWithActions.doc.mjs b/packages/cli/templates/blocks/components/LayoutHeader/LayoutHeaderWithActions.doc.mjs
new file mode 100644
index 0000000000..2337a03427
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutHeader/LayoutHeaderWithActions.doc.mjs
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'LayoutHeader',
+ name: 'LayoutHeader — With Actions',
+ displayName: 'LayoutHeader — With Actions',
+ description:
+ 'A fixed page header with a title and a primary action, above scrollable content. Use LayoutHeader inside Layout for persistent page-level headers.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'LayoutHeader',
+ 'Layout',
+ 'LayoutContent',
+ 'Center',
+ 'Card',
+ 'HStack',
+ 'Heading',
+ 'Button',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/LayoutHeader/LayoutHeaderWithActions.tsx b/packages/cli/templates/blocks/components/LayoutHeader/LayoutHeaderWithActions.tsx
new file mode 100644
index 0000000000..133e8ffd57
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutHeader/LayoutHeaderWithActions.tsx
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ Layout,
+ LayoutHeader,
+ LayoutContent,
+ Card,
+ HStack,
+} from '@astryxdesign/core/Layout';
+import {Center} from '@astryxdesign/core/Center';
+import {Heading} from '@astryxdesign/core/Text';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function LayoutHeaderWithActions() {
+ return (
+ <Center width={400}>
+ <Layout
+ style={{width: '100%'}}
+ height="fill"
+ header={
+ <LayoutHeader hasDivider>
+ <HStack gap={2} vAlign="center" hAlign="between">
+ <Heading level={4}>Dashboard</Heading>
+ <Button label="New Item" variant="primary">
+ New Item
+ </Button>
+ </HStack>
+ </LayoutHeader>
+ }
+ content={
+ <LayoutContent>
+ <Card variant="muted" />
+ </LayoutContent>
+ }
+ />
+ </Center>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/LayoutPanel/LayoutPanelNavigation.doc.mjs b/packages/cli/templates/blocks/components/LayoutPanel/LayoutPanelNavigation.doc.mjs
new file mode 100644
index 0000000000..e5a7eb40fd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutPanel/LayoutPanelNavigation.doc.mjs
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'LayoutPanel',
+ name: 'LayoutPanel — Navigation',
+ displayName: 'LayoutPanel — Navigation',
+ description:
+ 'A fixed-width side panel holding a navigation list next to the main content. Use LayoutPanel in the start or end slot of Layout for sidebars.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'LayoutPanel',
+ 'Layout',
+ 'LayoutContent',
+ 'Center',
+ 'List',
+ 'ListItem',
+ 'Card',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/LayoutPanel/LayoutPanelNavigation.tsx b/packages/cli/templates/blocks/components/LayoutPanel/LayoutPanelNavigation.tsx
new file mode 100644
index 0000000000..4570bf4a58
--- /dev/null
+++ b/packages/cli/templates/blocks/components/LayoutPanel/LayoutPanelNavigation.tsx
@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ Layout,
+ LayoutPanel,
+ LayoutContent,
+ Card,
+} from '@astryxdesign/core/Layout';
+import {Center} from '@astryxdesign/core/Center';
+import {List, ListItem} from '@astryxdesign/core/List';
+
+export default function LayoutPanelNavigation() {
+ return (
+ <Center width={400}>
+ <Layout
+ style={{width: '100%'}}
+ height="fill"
+ start={
+ <LayoutPanel hasDivider width={140} role="navigation">
+ <List>
+ <ListItem label="Overview" isSelected />
+ <ListItem label="Analytics" />
+ <ListItem label="Settings" />
+ </List>
+ </LayoutPanel>
+ }
+ content={
+ <LayoutContent>
+ <Card variant="muted" />
+ </LayoutContent>
+ }
+ />
+ </Center>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs
new file mode 100644
index 0000000000..c18048239c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemBasic.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: 'MetadataListItem',
+ name: 'MetadataListItem — Basic',
+ displayName: 'MetadataListItem — Basic',
+ description:
+ 'Labeled key–value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['MetadataList', 'MetadataListItem', 'Badge'],
+};
diff --git a/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemBasic.tsx b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemBasic.tsx
new file mode 100644
index 0000000000..8820c3946e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MetadataListItem/MetadataListItemBasic.tsx
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {MetadataList, MetadataListItem} from '@astryxdesign/core/MetadataList';
+import {Badge} from '@astryxdesign/core/Badge';
+
+export default function MetadataListItemBasic() {
+ return (
+ <MetadataList title="Deployment">
+ <MetadataListItem label="Environment">Production</MetadataListItem>
+ <MetadataListItem label="Status">
+ <Badge label="Healthy" variant="green" />
+ </MetadataListItem>
+ <MetadataListItem label="Version">v2.14.0</MetadataListItem>
+ <MetadataListItem label="Last deployed">June 12, 2026</MetadataListItem>
+ </MetadataList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/MobileNavToggle/MobileNavToggleBasic.doc.mjs b/packages/cli/templates/blocks/components/MobileNavToggle/MobileNavToggleBasic.doc.mjs
new file mode 100644
index 0000000000..ccdefa66e1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MobileNavToggle/MobileNavToggleBasic.doc.mjs
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'MobileNavToggle',
+ name: 'MobileNavToggle — Basic',
+ displayName: 'MobileNavToggle — Basic',
+ description:
+ 'A nav toggle with a custom icon and accessible label instead of the default hamburger. It opens a MobileNav drawer via the AppShell mobile context, which AppShell provides automatically.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'MobileNav',
+ 'MobileNavToggle',
+ 'AppShell',
+ 'SideNavItem',
+ 'SideNavSection',
+ 'Icon',
+ 'HStack',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/MobileNavToggle/MobileNavToggleBasic.tsx b/packages/cli/templates/blocks/components/MobileNavToggle/MobileNavToggleBasic.tsx
new file mode 100644
index 0000000000..cc04a2b60e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MobileNavToggle/MobileNavToggleBasic.tsx
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {MobileNav, MobileNavToggle} from '@astryxdesign/core/MobileNav';
+import {AppShellMobileContext} from '@astryxdesign/core/AppShell';
+import {SideNavItem, SideNavSection} from '@astryxdesign/core/SideNav';
+import {Icon} from '@astryxdesign/core/Icon';
+import {HStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function MobileNavToggleBasic() {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <AppShellMobileContext.Provider
+ value={{
+ isMobile: true,
+ isMobileNavOpen: isOpen,
+ toggleMobileNav: () => setIsOpen(v => !v),
+ openMobileNav: () => setIsOpen(true),
+ closeMobileNav: () => setIsOpen(false),
+ isMobileNavEnabled: true,
+ hasAutoToggle: false,
+ }}>
+ <HStack gap={3} vAlign="center">
+ <MobileNavToggle label="Open menu">
+ <Icon icon="viewColumns" />
+ </MobileNavToggle>
+ <Text type="body" weight="bold">
+ Page title
+ </Text>
+ </HStack>
+ <MobileNav isOpen={isOpen} onOpenChange={setIsOpen} header="Navigation">
+ <SideNavSection title="Pages">
+ <SideNavItem label="Home" isSelected href="#" />
+ <SideNavItem label="Settings" href="#" />
+ </SideNavSection>
+ </MobileNav>
+ </AppShellMobileContext.Provider>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx b/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx
index ddce624920..80c289935b 100644
--- a/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx
+++ b/packages/cli/templates/blocks/components/MoreMenu/MoreMenuShowcase.tsx
@@ -2,16 +2,11 @@
'use client';
-import {useState} from 'react';
import {MoreMenu} from '@astryxdesign/core/MoreMenu';
export default function MoreMenuShowcase() {
- const [isMenuOpen, setIsMenuOpen] = useState(false);
-
return (
<MoreMenu
- isMenuOpen={isMenuOpen}
- onOpenChange={setIsMenuOpen}
items={[
{label: 'Edit', onClick: () => {}},
{label: 'Duplicate', onClick: () => {}},
diff --git a/packages/cli/templates/blocks/components/NavIcon/NavIconBasic.doc.mjs b/packages/cli/templates/blocks/components/NavIcon/NavIconBasic.doc.mjs
new file mode 100644
index 0000000000..4c280ed8dc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/NavIcon/NavIconBasic.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: 'NavIcon',
+ name: 'NavIcon — Basic',
+ displayName: 'NavIcon — Basic',
+ description:
+ 'Circular icon containers wrapping semantic icons. Use as logos or accent icons in navigation headers such as TopNavHeading.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['NavIcon', 'Icon', 'HStack'],
+};
diff --git a/packages/cli/templates/blocks/components/NavIcon/NavIconBasic.tsx b/packages/cli/templates/blocks/components/NavIcon/NavIconBasic.tsx
new file mode 100644
index 0000000000..7f84af2fd9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/NavIcon/NavIconBasic.tsx
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {NavIcon} from '@astryxdesign/core/NavIcon';
+import {Icon} from '@astryxdesign/core/Icon';
+import {HStack} from '@astryxdesign/core/Layout';
+
+export default function NavIconBasic() {
+ return (
+ <HStack gap={4} vAlign="center">
+ <NavIcon icon={<Icon icon="search" />} />
+ <NavIcon icon={<Icon icon="calendar" />} />
+ </HStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/RadioListItem/RadioListItemBasic.doc.mjs b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemBasic.doc.mjs
new file mode 100644
index 0000000000..af2a169de1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemBasic.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: 'RadioListItem',
+ name: 'RadioListItem — Basic',
+ displayName: 'RadioListItem — Basic',
+ description:
+ 'Radio items with labels and descriptions inside a controlled RadioList. Use for single-choice option groups like shipping methods.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['RadioList', 'RadioListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/RadioListItem/RadioListItemBasic.tsx b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemBasic.tsx
new file mode 100644
index 0000000000..13fcaaccfd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/RadioListItem/RadioListItemBasic.tsx
@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {RadioList, RadioListItem} from '@astryxdesign/core/RadioList';
+
+export default function RadioListItemBasic() {
+ const [value, setValue] = useState('standard');
+
+ return (
+ <RadioList label="Shipping method" value={value} onChange={setValue}>
+ <RadioListItem
+ label="Standard"
+ value="standard"
+ description="5–7 business days"
+ />
+ <RadioListItem
+ label="Express"
+ value="express"
+ description="2–3 business days"
+ />
+ <RadioListItem
+ label="Overnight"
+ value="overnight"
+ description="Next business day"
+ />
+ </RadioList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Resizable/ResizableSidebar.doc.mjs b/packages/cli/templates/blocks/components/Resizable/ResizableSidebar.doc.mjs
new file mode 100644
index 0000000000..1c87f5401b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Resizable/ResizableSidebar.doc.mjs
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ResizeHandle',
+ alsoExampleFor: ['useResizable'],
+ name: 'Resizable — Collapsible with snap points',
+ displayName: 'Resizable — Collapsible with snap points',
+ description:
+ 'A collapsible sidebar with snap points, driven by useResizable. Dragging snaps to preset widths, dragging past the minimum collapses the panel, and the expand method restores it programmatically.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'Resizable',
+ 'ResizeHandle',
+ 'Layout',
+ 'LayoutPanel',
+ 'LayoutContent',
+ 'Card',
+ 'VStack',
+ 'Button',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/Resizable/ResizableSidebar.tsx b/packages/cli/templates/blocks/components/Resizable/ResizableSidebar.tsx
new file mode 100644
index 0000000000..d108a04eb7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Resizable/ResizableSidebar.tsx
@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useResizable, ResizeHandle} from '@astryxdesign/core/Resizable';
+import {
+ Card,
+ Layout,
+ LayoutContent,
+ LayoutPanel,
+ VStack,
+} from '@astryxdesign/core/Layout';
+import {Button} from '@astryxdesign/core/Button';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function ResizableSidebar() {
+ const sidebar = useResizable({
+ defaultSize: 240,
+ minSizePx: 160,
+ maxSizePx: 360,
+ collapsible: true,
+ snaps: [200, 280],
+ });
+
+ return (
+ <Card variant="muted" height={240} width={500}>
+ <Layout
+ height="fill"
+ start={
+ <>
+ <LayoutPanel width={sidebar.size} hasDivider={false}>
+ <Text color="secondary">
+ {sidebar.isCollapsed
+ ? ''
+ : `${Math.round(sidebar.size)}px wide`}
+ </Text>
+ </LayoutPanel>
+ <ResizeHandle
+ direction="horizontal"
+ hasDivider
+ resizable={sidebar.props}
+ label="Resize sidebar"
+ />
+ </>
+ }
+ content={
+ <LayoutContent>
+ <VStack gap={2}>
+ <Text color="secondary">
+ Drag the handle — it snaps at 200px and 280px. Drag all the way
+ left to collapse the sidebar.
+ </Text>
+ {sidebar.isCollapsed && (
+ <Button
+ label="Expand sidebar"
+ variant="secondary"
+ size="sm"
+ onClick={() => sidebar.expand()}
+ />
+ )}
+ </VStack>
+ </LayoutContent>
+ }
+ />
+ </Card>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.doc.mjs b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.doc.mjs
new file mode 100644
index 0000000000..2082cfeb3e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.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: 'SegmentedControlItem',
+ name: 'SegmentedControlItem — Basic',
+ displayName: 'SegmentedControlItem — Basic',
+ description:
+ 'Label-only options inside a SegmentedControl. Each item declares a value; the parent control holds the selected value and change handler.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['SegmentedControl', 'SegmentedControlItem'],
+};
diff --git a/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.tsx b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.tsx
new file mode 100644
index 0000000000..9e3bebd6b7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SegmentedControlItem/SegmentedControlItemBasic.tsx
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+
+export default function SegmentedControlItemBasic() {
+ const [view, setView] = useState('board');
+
+ return (
+ <SegmentedControl value={view} onChange={setView} label="View mode">
+ <SegmentedControlItem value="board" label="Board" />
+ <SegmentedControlItem value="list" label="List" />
+ <SegmentedControlItem value="timeline" label="Timeline" />
+ </SegmentedControl>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionBasic.doc.mjs b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionBasic.doc.mjs
new file mode 100644
index 0000000000..2b1611646a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionBasic.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: 'SelectorOption',
+ name: 'SelectorOption — Basic',
+ displayName: 'SelectorOption — Basic',
+ description:
+ 'A selector whose options are rendered with SelectorOption, adding a secondary description below each label. Use inside renderOption for consistent custom option styling.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Selector', 'SelectorOption'],
+};
diff --git a/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx
new file mode 100644
index 0000000000..dfed2f030d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Selector, SelectorOption} from '@astryxdesign/core/Selector';
+
+const descriptions: Record<string, string> = {
+ admin: 'Full access to all resources',
+ editor: 'Can edit and publish content',
+ viewer: 'Read-only access',
+};
+
+const roles = [
+ {value: 'admin', label: 'Admin'},
+ {value: 'editor', label: 'Editor'},
+ {value: 'viewer', label: 'Viewer'},
+];
+
+export default function SelectorOptionBasic() {
+ const [value, setValue] = useState<string | undefined>('editor');
+
+ return (
+ <Selector
+ style={{width: 300}}
+ label="Role"
+ options={roles}
+ value={value}
+ onChange={setValue}
+ placeholder="Assign a role..."
+ renderOption={option => (
+ <SelectorOption
+ label={option.label}
+ description={descriptions[option.value]}
+ />
+ )}
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SideNavCollapseButton/SideNavCollapseButtonBasic.doc.mjs b/packages/cli/templates/blocks/components/SideNavCollapseButton/SideNavCollapseButtonBasic.doc.mjs
new file mode 100644
index 0000000000..cb6e405e56
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavCollapseButton/SideNavCollapseButtonBasic.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: 'SideNavCollapseButton',
+ name: 'SideNavCollapseButton — Basic',
+ displayName: 'SideNavCollapseButton — Basic',
+ description:
+ 'Place a collapse button in the SideNav footer to let users toggle the rail between expanded and collapsed states. Disable the built-in button via collapsible={{hasButton: false}} when positioning it yourself.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['SideNav', 'SideNavCollapseButton', 'SideNavItem'],
+};
diff --git a/packages/cli/templates/blocks/components/SideNavCollapseButton/SideNavCollapseButtonBasic.tsx b/packages/cli/templates/blocks/components/SideNavCollapseButton/SideNavCollapseButtonBasic.tsx
new file mode 100644
index 0000000000..e6c45d2a14
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavCollapseButton/SideNavCollapseButtonBasic.tsx
@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import type {ComponentProps} from 'react';
+import {
+ SideNav,
+ SideNavCollapseButton,
+ SideNavItem,
+} from '@astryxdesign/core/SideNav';
+
+function HomeIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="m2.25 12 8.954-8.955c.44-.439 1.152-.439 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25"
+ />
+ </svg>
+ );
+}
+
+function FolderIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M2.25 12.75V12A2.25 2.25 0 0 1 4.5 9.75h15A2.25 2.25 0 0 1 21.75 12v.75m-8.69-6.44-2.12-2.12a1.5 1.5 0 0 0-1.061-.44H4.5A2.25 2.25 0 0 0 2.25 6v12a2.25 2.25 0 0 0 2.25 2.25h15A2.25 2.25 0 0 0 21.75 18V9a2.25 2.25 0 0 0-2.25-2.25h-5.379a1.5 1.5 0 0 1-1.06-.44Z"
+ />
+ </svg>
+ );
+}
+
+export default function SideNavCollapseButtonBasic() {
+ return (
+ <SideNav
+ collapsible={{hasButton: false}}
+ footerIcons={<SideNavCollapseButton />}>
+ <SideNavItem label="Home" icon={HomeIcon} isSelected href="#" />
+ <SideNavItem label="Projects" icon={FolderIcon} href="#" />
+ </SideNav>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SideNavHeading/SideNavHeadingBasic.doc.mjs b/packages/cli/templates/blocks/components/SideNavHeading/SideNavHeadingBasic.doc.mjs
new file mode 100644
index 0000000000..d0512a3367
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavHeading/SideNavHeadingBasic.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: 'SideNavHeading',
+ name: 'SideNavHeading — Basic',
+ displayName: 'SideNavHeading — Basic',
+ description:
+ 'A SideNav header with an app icon and a linked title. Pass it to the SideNav header prop to identify the product or workspace at the top of the navigation rail.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['SideNav', 'SideNavHeading'],
+};
diff --git a/packages/cli/templates/blocks/components/SideNavHeading/SideNavHeadingBasic.tsx b/packages/cli/templates/blocks/components/SideNavHeading/SideNavHeadingBasic.tsx
new file mode 100644
index 0000000000..9380dbf49a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavHeading/SideNavHeadingBasic.tsx
@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {SideNav, SideNavHeading} from '@astryxdesign/core/SideNav';
+
+function AppIcon() {
+ return (
+ <svg
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.5">
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M3.75 6A2.25 2.25 0 0 1 6 3.75h2.25A2.25 2.25 0 0 1 10.5 6v2.25a2.25 2.25 0 0 1-2.25 2.25H6a2.25 2.25 0 0 1-2.25-2.25V6ZM3.75 15.75A2.25 2.25 0 0 1 6 13.5h2.25a2.25 2.25 0 0 1 2.25 2.25V18a2.25 2.25 0 0 1-2.25 2.25H6A2.25 2.25 0 0 1 3.75 18v-2.25ZM13.5 6a2.25 2.25 0 0 1 2.25-2.25H18A2.25 2.25 0 0 1 20.25 6v2.25A2.25 2.25 0 0 1 18 10.5h-2.25a2.25 2.25 0 0 1-2.25-2.25V6ZM13.5 15.75a2.25 2.25 0 0 1 2.25-2.25H18a2.25 2.25 0 0 1 2.25 2.25V18A2.25 2.25 0 0 1 18 20.25h-2.25a2.25 2.25 0 0 1-2.25-2.25v-2.25Z"
+ />
+ </svg>
+ );
+}
+
+export default function SideNavHeadingBasic() {
+ return (
+ <SideNav
+ header={
+ <SideNavHeading
+ heading="Analytics"
+ icon={<AppIcon />}
+ headingHref="/"
+ />
+ }>
+ {null}
+ </SideNav>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SideNavItem/SideNavItemBasic.doc.mjs b/packages/cli/templates/blocks/components/SideNavItem/SideNavItemBasic.doc.mjs
new file mode 100644
index 0000000000..bccdfc8883
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavItem/SideNavItemBasic.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: 'SideNavItem',
+ name: 'SideNavItem — Basic',
+ displayName: 'SideNavItem — Basic',
+ description:
+ 'Navigation links inside a SideNav, each with a label, an icon, and an href. Mark the item for the current page with isSelected.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['SideNav', 'SideNavItem'],
+};
diff --git a/packages/cli/templates/blocks/components/SideNavItem/SideNavItemBasic.tsx b/packages/cli/templates/blocks/components/SideNavItem/SideNavItemBasic.tsx
new file mode 100644
index 0000000000..43201395eb
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavItem/SideNavItemBasic.tsx
@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import type {ComponentProps} from 'react';
+import {SideNav, SideNavItem} from '@astryxdesign/core/SideNav';
+
+function InboxIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M2.25 13.5h3.86a2.25 2.25 0 0 1 2.012 1.244l.256.512a2.25 2.25 0 0 0 2.013 1.244h3.218a2.25 2.25 0 0 0 2.013-1.244l.256-.512a2.25 2.25 0 0 1 2.013-1.244h3.859m-19.5.338V18a2.25 2.25 0 0 0 2.25 2.25h15A2.25 2.25 0 0 0 21.75 18v-4.162c0-.224-.034-.447-.1-.661L19.24 5.338a2.25 2.25 0 0 0-2.15-1.588H6.911a2.25 2.25 0 0 0-2.15 1.588L2.35 13.177a2.25 2.25 0 0 0-.1.661Z"
+ />
+ </svg>
+ );
+}
+
+function DocumentIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z"
+ />
+ </svg>
+ );
+}
+
+export default function SideNavItemBasic() {
+ return (
+ <SideNav>
+ <SideNavItem label="Inbox" icon={InboxIcon} isSelected href="#" />
+ <SideNavItem label="Documents" icon={DocumentIcon} href="#" />
+ </SideNav>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SideNavSection/SideNavSectionBasic.doc.mjs b/packages/cli/templates/blocks/components/SideNavSection/SideNavSectionBasic.doc.mjs
new file mode 100644
index 0000000000..5fc07fcfa9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavSection/SideNavSectionBasic.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: 'SideNavSection',
+ name: 'SideNavSection — Basic',
+ displayName: 'SideNavSection — Basic',
+ description:
+ 'Group related SideNavItems under titled sections. Use sections to organize longer navigation lists into scannable clusters like Overview and Account.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['SideNav', 'SideNavSection', 'SideNavItem'],
+};
diff --git a/packages/cli/templates/blocks/components/SideNavSection/SideNavSectionBasic.tsx b/packages/cli/templates/blocks/components/SideNavSection/SideNavSectionBasic.tsx
new file mode 100644
index 0000000000..76850f0df5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SideNavSection/SideNavSectionBasic.tsx
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import type {ComponentProps} from 'react';
+import {SideNav, SideNavItem, SideNavSection} from '@astryxdesign/core/SideNav';
+
+function HomeIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="m2.25 12 8.954-8.955c.44-.439 1.152-.439 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25"
+ />
+ </svg>
+ );
+}
+
+function ChartIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M3 13.125C3 12.504 3.504 12 4.125 12h2.25c.621 0 1.125.504 1.125 1.125v6.75C7.5 20.496 6.996 21 6.375 21h-2.25A1.125 1.125 0 0 1 3 19.875v-6.75ZM9.75 8.625c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125v11.25c0 .621-.504 1.125-1.125 1.125h-2.25a1.125 1.125 0 0 1-1.125-1.125V8.625ZM16.5 4.125c0-.621.504-1.125 1.125-1.125h2.25C20.496 3 21 3.504 21 4.125v15.75c0 .621-.504 1.125-1.125 1.125h-2.25a1.125 1.125 0 0 1-1.125-1.125V4.125Z"
+ />
+ </svg>
+ );
+}
+
+function UserIcon(props: ComponentProps<'svg'>) {
+ return (
+ <svg
+ fill="none"
+ viewBox="0 0 24 24"
+ strokeWidth={1.5}
+ stroke="currentColor"
+ {...props}>
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M15.75 6a3.75 3.75 0 1 1-7.5 0 3.75 3.75 0 0 1 7.5 0ZM4.501 20.118a7.5 7.5 0 0 1 14.998 0A17.933 17.933 0 0 1 12 21.75c-2.676 0-5.216-.584-7.499-1.632Z"
+ />
+ </svg>
+ );
+}
+
+export default function SideNavSectionBasic() {
+ return (
+ <SideNav>
+ <SideNavSection title="Overview">
+ <SideNavItem label="Dashboard" icon={HomeIcon} isSelected href="#" />
+ <SideNavItem label="Analytics" icon={ChartIcon} href="#" />
+ </SideNavSection>
+ <SideNavSection title="Account">
+ <SideNavItem label="Profile" icon={UserIcon} href="#" />
+ </SideNavSection>
+ </SideNav>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/StackItem/StackItemFill.doc.mjs b/packages/cli/templates/blocks/components/StackItem/StackItemFill.doc.mjs
new file mode 100644
index 0000000000..3ed5eb3521
--- /dev/null
+++ b/packages/cli/templates/blocks/components/StackItem/StackItemFill.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: 'StackItem',
+ name: 'StackItem — Fill',
+ displayName: 'StackItem — Fill',
+ description:
+ 'A static-width item next to one that fills the remaining space. Wrap stack children in StackItem when an item needs explicit sizing control.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['StackItem', 'HStack', 'Card', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/StackItem/StackItemFill.tsx b/packages/cli/templates/blocks/components/StackItem/StackItemFill.tsx
new file mode 100644
index 0000000000..4cca4cf185
--- /dev/null
+++ b/packages/cli/templates/blocks/components/StackItem/StackItemFill.tsx
@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {HStack, StackItem} from '@astryxdesign/core/Layout';
+import {Card} from '@astryxdesign/core/Card';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function StackItemFill() {
+ return (
+ <HStack gap={3} vAlign="center" width="100%" style={{maxWidth: 400}}>
+ <StackItem size="static">
+ <Card padding={3}>
+ <Text type="supporting" color="secondary">
+ Static
+ </Text>
+ </Card>
+ </StackItem>
+ <StackItem size="fill">
+ <Card padding={3}>
+ <Text type="supporting" color="secondary">
+ Fills remaining space
+ </Text>
+ </Card>
+ </StackItem>
+ </HStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TabMenu/TabMenuBasic.doc.mjs b/packages/cli/templates/blocks/components/TabMenu/TabMenuBasic.doc.mjs
new file mode 100644
index 0000000000..63cb07c9d3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TabMenu/TabMenuBasic.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: 'TabMenu',
+ name: 'TabMenu — Basic',
+ displayName: 'TabMenu — Basic',
+ description:
+ 'An overflow menu at the end of a TabList that collects secondary tabs behind a dropdown. Use it when there are more tabs than fit comfortably inline.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TabList', 'Tab', 'TabMenu'],
+};
diff --git a/packages/cli/templates/blocks/components/TabMenu/TabMenuBasic.tsx b/packages/cli/templates/blocks/components/TabMenu/TabMenuBasic.tsx
new file mode 100644
index 0000000000..e34ea0c3aa
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TabMenu/TabMenuBasic.tsx
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {TabList, Tab, TabMenu} from '@astryxdesign/core/TabList';
+
+export default function TabMenuBasic() {
+ const [value, setValue] = useState('overview');
+ return (
+ <TabList value={value} onChange={setValue}>
+ <Tab value="overview" label="Overview" />
+ <Tab value="activity" label="Activity" />
+ <TabMenu
+ label="More"
+ options={[
+ {value: 'settings', label: 'Settings'},
+ {value: 'billing', label: 'Billing'},
+ ]}
+ />
+ </TabList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TopNavHeading/TopNavHeadingBasic.doc.mjs b/packages/cli/templates/blocks/components/TopNavHeading/TopNavHeadingBasic.doc.mjs
new file mode 100644
index 0000000000..25dfd68a1b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavHeading/TopNavHeadingBasic.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: 'TopNavHeading',
+ name: 'TopNavHeading — Basic',
+ displayName: 'TopNavHeading — Basic',
+ description:
+ 'A product heading with a logo inside a TopNav, linked to the home page. Use as the leading brand element of a top navigation bar.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TopNav', 'TopNavHeading', 'NavIcon', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/TopNavHeading/TopNavHeadingBasic.tsx b/packages/cli/templates/blocks/components/TopNavHeading/TopNavHeadingBasic.tsx
new file mode 100644
index 0000000000..ecc5162df3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavHeading/TopNavHeadingBasic.tsx
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {TopNav, TopNavHeading} from '@astryxdesign/core/TopNav';
+import {NavIcon} from '@astryxdesign/core/NavIcon';
+import {Icon} from '@astryxdesign/core/Icon';
+
+export default function TopNavHeadingBasic() {
+ return (
+ <TopNav
+ label="Product navigation"
+ heading={
+ <TopNavHeading
+ heading="Acme Platform"
+ logo={<NavIcon icon={<Icon icon="viewColumns" />} />}
+ headingHref="/"
+ />
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TopNavItem/TopNavItemBasic.doc.mjs b/packages/cli/templates/blocks/components/TopNavItem/TopNavItemBasic.doc.mjs
new file mode 100644
index 0000000000..8317ff98f1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavItem/TopNavItemBasic.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: 'TopNavItem',
+ name: 'TopNavItem — Basic',
+ displayName: 'TopNavItem — Basic',
+ description:
+ 'Navigation links inside a TopNav with one item marked as selected. Use for top-level pages of an application.',
+ isReady: true,
+ aspectRatio: 3,
+ componentsUsed: ['TopNav', 'TopNavHeading', 'TopNavItem'],
+};
diff --git a/packages/cli/templates/blocks/components/TopNavItem/TopNavItemBasic.tsx b/packages/cli/templates/blocks/components/TopNavItem/TopNavItemBasic.tsx
new file mode 100644
index 0000000000..2fae844847
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavItem/TopNavItemBasic.tsx
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {TopNav, TopNavHeading, TopNavItem} from '@astryxdesign/core/TopNav';
+
+export default function TopNavItemBasic() {
+ return (
+ <TopNav
+ label="Main navigation"
+ heading={<TopNavHeading heading="App" />}
+ startContent={
+ <>
+ <TopNavItem label="Dashboard" href="#" isSelected />
+ <TopNavItem label="Projects" href="#" />
+ <TopNavItem label="Reports" href="#" />
+ </>
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TopNavMegaMenu/TopNavMegaMenuBasic.doc.mjs b/packages/cli/templates/blocks/components/TopNavMegaMenu/TopNavMegaMenuBasic.doc.mjs
new file mode 100644
index 0000000000..88c2621ba7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMegaMenu/TopNavMegaMenuBasic.doc.mjs
@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'TopNavMegaMenu',
+ name: 'TopNavMegaMenu — Basic',
+ displayName: 'TopNavMegaMenu — Basic',
+ description:
+ 'A mega menu trigger inside a TopNav that opens a panel of rich link items. Use when a navigation section has multiple destinations worth describing.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'TopNav',
+ 'TopNavHeading',
+ 'TopNavItem',
+ 'TopNavMegaMenu',
+ 'TopNavMegaMenuItem',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/TopNavMegaMenu/TopNavMegaMenuBasic.tsx b/packages/cli/templates/blocks/components/TopNavMegaMenu/TopNavMegaMenuBasic.tsx
new file mode 100644
index 0000000000..c6b7ca0d90
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMegaMenu/TopNavMegaMenuBasic.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ TopNav,
+ TopNavHeading,
+ TopNavItem,
+ TopNavMegaMenu,
+ TopNavMegaMenuItem,
+} from '@astryxdesign/core/TopNav';
+import {RocketLaunchIcon, BookOpenIcon} from '@heroicons/react/24/outline';
+
+export default function TopNavMegaMenuBasic() {
+ return (
+ <TopNav
+ style={{width: 600}}
+ label="Main navigation"
+ heading={<TopNavHeading heading="DevTools" />}
+ startContent={
+ <>
+ <TopNavItem label="Overview" href="#" isSelected />
+ <TopNavMegaMenu
+ label="Products"
+ items={
+ <>
+ <TopNavMegaMenuItem
+ title="Deploy"
+ description="Ship to production in seconds"
+ icon={<RocketLaunchIcon width={20} height={20} />}
+ href="#deploy"
+ />
+ <TopNavMegaMenuItem
+ title="Documentation"
+ description="Guides, references, and tutorials"
+ icon={<BookOpenIcon width={20} height={20} />}
+ href="#docs"
+ />
+ </>
+ }
+ />
+ </>
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TopNavMegaMenuFeaturedCard/TopNavMegaMenuFeaturedCardBasic.doc.mjs b/packages/cli/templates/blocks/components/TopNavMegaMenuFeaturedCard/TopNavMegaMenuFeaturedCardBasic.doc.mjs
new file mode 100644
index 0000000000..699108ebf6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMegaMenuFeaturedCard/TopNavMegaMenuFeaturedCardBasic.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: 'TopNavMegaMenuFeaturedCard',
+ name: 'TopNavMegaMenuFeaturedCard — Basic',
+ displayName: 'TopNavMegaMenuFeaturedCard — Basic',
+ description:
+ 'A promotional card with a title, description, and call-to-action link. Pass it to the featured slot of a TopNavMegaMenu to highlight announcements.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TopNavMegaMenuFeaturedCard'],
+};
diff --git a/packages/cli/templates/blocks/components/TopNavMegaMenuFeaturedCard/TopNavMegaMenuFeaturedCardBasic.tsx b/packages/cli/templates/blocks/components/TopNavMegaMenuFeaturedCard/TopNavMegaMenuFeaturedCardBasic.tsx
new file mode 100644
index 0000000000..f4957e4e0d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMegaMenuFeaturedCard/TopNavMegaMenuFeaturedCardBasic.tsx
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {TopNavMegaMenuFeaturedCard} from '@astryxdesign/core/TopNav';
+
+export default function TopNavMegaMenuFeaturedCardBasic() {
+ return (
+ <TopNavMegaMenuFeaturedCard
+ title="What's New"
+ description="Check out the latest features and improvements in the Q2 release."
+ linkLabel="Read the changelog"
+ linkHref="#changelog"
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TopNavMegaMenuItem/TopNavMegaMenuItemBasic.doc.mjs b/packages/cli/templates/blocks/components/TopNavMegaMenuItem/TopNavMegaMenuItemBasic.doc.mjs
new file mode 100644
index 0000000000..ead2b10392
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMegaMenuItem/TopNavMegaMenuItemBasic.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: 'TopNavMegaMenuItem',
+ name: 'TopNavMegaMenuItem — Basic',
+ displayName: 'TopNavMegaMenuItem — Basic',
+ description:
+ 'Rich link items with an icon, title, and description. Use inside the items slot of a TopNavMegaMenu to describe each destination.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TopNavMegaMenuItem', 'Grid'],
+};
diff --git a/packages/cli/templates/blocks/components/TopNavMegaMenuItem/TopNavMegaMenuItemBasic.tsx b/packages/cli/templates/blocks/components/TopNavMegaMenuItem/TopNavMegaMenuItemBasic.tsx
new file mode 100644
index 0000000000..7300d13482
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMegaMenuItem/TopNavMegaMenuItemBasic.tsx
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {TopNavMegaMenuItem} from '@astryxdesign/core/TopNav';
+import {Grid} from '@astryxdesign/core/Grid';
+import {BoltIcon, CircleStackIcon} from '@heroicons/react/24/outline';
+
+export default function TopNavMegaMenuItemBasic() {
+ return (
+ <Grid columns={2} gap={2}>
+ <TopNavMegaMenuItem
+ title="Edge Functions"
+ description="Run serverless code at the network edge"
+ icon={<BoltIcon width={20} height={20} />}
+ href="#edge"
+ />
+ <TopNavMegaMenuItem
+ title="Storage"
+ description="Object and file storage for your application"
+ icon={<CircleStackIcon width={20} height={20} />}
+ href="#storage"
+ />
+ </Grid>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TopNavMenu/TopNavMenuBasic.doc.mjs b/packages/cli/templates/blocks/components/TopNavMenu/TopNavMenuBasic.doc.mjs
new file mode 100644
index 0000000000..92c3a5afa2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMenu/TopNavMenuBasic.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: 'TopNavMenu',
+ name: 'TopNavMenu — Basic',
+ displayName: 'TopNavMenu — Basic',
+ description:
+ 'A dropdown menu inside a TopNav built from an items array with icons and descriptions. Use to group related destinations under a single trigger.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TopNav', 'TopNavHeading', 'TopNavItem', 'TopNavMenu'],
+};
diff --git a/packages/cli/templates/blocks/components/TopNavMenu/TopNavMenuBasic.tsx b/packages/cli/templates/blocks/components/TopNavMenu/TopNavMenuBasic.tsx
new file mode 100644
index 0000000000..d94c02166c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TopNavMenu/TopNavMenuBasic.tsx
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ TopNav,
+ TopNavHeading,
+ TopNavItem,
+ TopNavMenu,
+} from '@astryxdesign/core/TopNav';
+import {ChartBarIcon, Cog6ToothIcon} from '@heroicons/react/24/outline';
+
+export default function TopNavMenuBasic() {
+ return (
+ <TopNav
+ style={{width: 600}}
+ label="Main navigation"
+ heading={<TopNavHeading heading="Platform" />}
+ startContent={
+ <>
+ <TopNavItem label="Home" href="#" isSelected />
+ <TopNavMenu
+ label="Tools"
+ items={[
+ {
+ title: 'Analytics',
+ description: 'View traffic and engagement metrics',
+ icon: <ChartBarIcon />,
+ href: '#analytics',
+ },
+ {
+ title: 'Settings',
+ description: 'Configure your workspace',
+ icon: <Cog6ToothIcon />,
+ href: '#settings',
+ },
+ ]}
+ />
+ </>
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.doc.mjs b/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.doc.mjs
deleted file mode 100644
index da2455e72d..0000000000
--- a/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.doc.mjs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- exampleFor: 'TreeListBranches',
- name: 'TreeListBranches',
- displayName: 'Tree List Branches',
- description: 'Tree with expandable branches at multiple nesting levels.',
- isReady: true,
- isShowcase: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TreeList'],
-};
diff --git a/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.tsx b/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.tsx
deleted file mode 100644
index b1316e9d45..0000000000
--- a/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.tsx
+++ /dev/null
@@ -1,64 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {TreeList} from '@astryxdesign/core/TreeList';
-
-const noop = () => {};
-
-export default function TreeListBranchesShowcase() {
- return (
- <TreeList
- items={[
- {
- id: 'design-system',
- label: 'Design System',
- isExpanded: true,
- children: [
- {
- id: 'components',
- label: 'Components',
- isExpanded: true,
- children: [
- {
- id: 'inputs',
- label: 'Inputs',
- children: [
- {id: 'text-input', label: 'TextInput', onClick: noop},
- {id: 'checkbox', label: 'Checkbox', onClick: noop},
- {id: 'selector', label: 'Selector', onClick: noop},
- ],
- },
- {
- id: 'layout',
- label: 'Layout',
- children: [
- {id: 'stack', label: 'Stack', onClick: noop},
- {id: 'grid', label: 'Grid', onClick: noop},
- ],
- },
- ],
- },
- {
- id: 'tokens',
- label: 'Tokens',
- children: [
- {id: 'colors', label: 'Colors', onClick: noop},
- {id: 'spacing', label: 'Spacing', onClick: noop},
- {id: 'typography', label: 'Typography', onClick: noop},
- ],
- },
- ],
- },
- {
- id: 'utilities',
- label: 'Utilities',
- children: [
- {id: 'hooks', label: 'Hooks', onClick: noop},
- {id: 'helpers', label: 'Helpers', onClick: noop},
- ],
- },
- ]}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs
deleted file mode 100644
index 5433414696..0000000000
--- a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- exampleFor: 'TreeListItem',
- name: 'TreeListItem',
- displayName: 'Tree List Item',
- description: 'Tree items with descriptions, icons, badges, selection, disabled state, and nested expand/collapse. TreeList is data-driven: no composed children API.',
- isReady: true,
- isShowcase: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TreeList', 'Badge', 'Icon', 'Layout', 'Text'],
-};
diff --git a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.tsx b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.tsx
deleted file mode 100644
index 8024ecf605..0000000000
--- a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.tsx
+++ /dev/null
@@ -1,60 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {TreeList} from '@astryxdesign/core/TreeList';
-import {Badge} from '@astryxdesign/core/Badge';
-import {Icon} from '@astryxdesign/core/Icon';
-
-const noop = () => {};
-
-export default function TreeListItemShowcase() {
- return (
- <TreeList
- style={{width: 400}}
- items={[
- {
- id: 'inbox',
- label: 'Inbox',
- description: '12 unread messages',
- isExpanded: true,
- startContent: <Icon icon="info" size="sm" />,
- endContent: <Badge label="12" variant="info" />,
- children: [
- {
- id: 'primary',
- label: 'Primary',
- isSelected: true,
- startContent: <Icon icon="check" size="sm" />,
- onClick: noop,
- },
- {
- id: 'updates',
- label: 'Updates',
- endContent: <Badge label="4" variant="info" />,
- onClick: noop,
- },
- ],
- },
- {
- id: 'drafts',
- label: 'Drafts',
- description: '3 draft messages',
- startContent: <Icon icon="clock" size="sm" />,
- onClick: noop,
- },
- {
- id: 'archive',
- label: 'Archive',
- onClick: noop,
- },
- {
- id: 'spam',
- label: 'Spam',
- isDisabled: true,
- startContent: <Icon icon="warning" size="sm" />,
- },
- ]}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemBasic.doc.mjs b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemBasic.doc.mjs
new file mode 100644
index 0000000000..c435e54073
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemBasic.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: 'TypeaheadItem',
+ name: 'TypeaheadItem — Basic',
+ displayName: 'TypeaheadItem — Basic',
+ description:
+ 'A typeahead whose results are rendered with TypeaheadItem, adding a secondary description below each label. Use inside renderItem to keep custom results visually consistent.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Typeahead', 'TypeaheadItem', 'Center'],
+};
diff --git a/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemBasic.tsx b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemBasic.tsx
new file mode 100644
index 0000000000..7776cff7e7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TypeaheadItem/TypeaheadItemBasic.tsx
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Typeahead, TypeaheadItem} from '@astryxdesign/core/Typeahead';
+import type {SearchableItem, SearchSource} from '@astryxdesign/core/Typeahead';
+import {Center} from '@astryxdesign/core/Center';
+
+interface PersonItem extends SearchableItem {
+ auxiliaryData: {role: string};
+}
+
+const people: PersonItem[] = [
+ {id: '1', label: 'Alice Johnson', auxiliaryData: {role: 'Engineer'}},
+ {id: '2', label: 'Bob Smith', auxiliaryData: {role: 'Designer'}},
+ {id: '3', label: 'Charlie Brown', auxiliaryData: {role: 'Product Manager'}},
+];
+
+const peopleSource: SearchSource<PersonItem> = {
+ search: (query: string) =>
+ people.filter(p => p.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => people,
+};
+
+export default function TypeaheadItemBasic() {
+ const [value, setValue] = useState<PersonItem | null>(null);
+
+ return (
+ <Center width={320}>
+ <Typeahead
+ label="Assignee"
+ placeholder="Search people..."
+ searchSource={peopleSource}
+ value={value}
+ onChange={setValue}
+ renderItem={(item: PersonItem) => (
+ <TypeaheadItem item={item} description={item.auxiliaryData.role} />
+ )}
+ />
+ </Center>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/VStack/VStackBasic.doc.mjs b/packages/cli/templates/blocks/components/VStack/VStackBasic.doc.mjs
new file mode 100644
index 0000000000..7babdc7f54
--- /dev/null
+++ b/packages/cli/templates/blocks/components/VStack/VStackBasic.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: 'VStack',
+ name: 'VStack — Basic',
+ displayName: 'VStack — Basic',
+ description:
+ 'A heading and paragraphs stacked vertically with a consistent gap. Use VStack whenever siblings should flow top to bottom with even spacing.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['VStack', 'Text', 'Heading'],
+};
diff --git a/packages/cli/templates/blocks/components/VStack/VStackBasic.tsx b/packages/cli/templates/blocks/components/VStack/VStackBasic.tsx
new file mode 100644
index 0000000000..eed9b42c81
--- /dev/null
+++ b/packages/cli/templates/blocks/components/VStack/VStackBasic.tsx
@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text, Heading} from '@astryxdesign/core/Text';
+
+export default function VStackBasic() {
+ return (
+ <VStack gap={3}>
+ <Heading level={5}>Weekly Report</Heading>
+ <Text type="body" color="secondary">
+ VStack arranges its children in a vertical column.
+ </Text>
+ <Text type="body" color="secondary">
+ The gap prop controls the spacing between each item.
+ </Text>
+ </VStack>
+ );
+}