@astryxdesign/cli 0.1.2-canary.bfcbf64 → 0.1.2-canary.c11faf5

package/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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/templates/blocks/components/ToggleButtonGroup/ToggleButtonGroupVertical.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: 'ToggleButtonGroup',
+  name: 'ToggleButtonGroup — Vertical',
+  displayName: 'ToggleButtonGroup — Vertical',
+  description:
+    'A vertically stacked ToggleButtonGroup using the vertical orientation, shown with both single-select and multi-select behavior — ideal for sidebar-style option lists and vertical toolbars.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: ['ToggleButton', 'ToggleButtonGroup', 'Layout', 'Text'],
+};

package/templates/blocks/components/ToggleButtonGroup/ToggleButtonGroupVertical.tsx

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {ToggleButton, ToggleButtonGroup} from '@astryxdesign/core/ToggleButton';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function ToggleButtonGroupVertical() {
+  const [view, setView] = useState<string | null>('grid');
+  const [filters, setFilters] = useState<string[]>(['active']);
+
+  return (
+    <VStack gap={4}>
+      <VStack gap={1}>
+        <Text type="label" color="secondary">
+          Single select
+        </Text>
+        <ToggleButtonGroup
+          orientation="vertical"
+          value={view}
+          onChange={setView}
+          label="View mode">
+          <ToggleButton value="list" label="List" />
+          <ToggleButton value="grid" label="Grid" />
+          <ToggleButton value="board" label="Board" />
+        </ToggleButtonGroup>
+      </VStack>
+      <VStack gap={1}>
+        <Text type="label" color="secondary">
+          Multi select
+        </Text>
+        <ToggleButtonGroup
+          orientation="vertical"
+          type="multiple"
+          value={filters}
+          onChange={setFilters}
+          label="Status filters">
+          <ToggleButton value="active" label="Active" />
+          <ToggleButton value="pending" label="Pending" />
+          <ToggleButton value="closed" label="Closed" />
+        </ToggleButtonGroup>
+      </VStack>
+    </VStack>
+  );
+}

package/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'],
+};

package/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="/"
+        />
+      }
+    />
+  );
+}

package/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'],
+};

package/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="#" />
+        </>
+      }
+    />
+  );
+}

package/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',
+  ],
+};

package/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"
+                />
+              </>
+            }
+          />
+        </>
+      }
+    />
+  );
+}

package/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'],
+};

package/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"
+    />
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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',
+              },
+            ]}
+          />
+        </>
+      }
+    />
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}