@astryxdesign/cli 0.1.2 → 0.1.3

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

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

package/templates/blocks/components/Hooks/useKeyboardHintHookUsage.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: 'useKeyboardHint',
+  name: 'useKeyboardHint — Arrow-key Hint',
+  displayName: 'useKeyboardHint — Arrow-key Hint',
+  description:
+    'Toolbar shows an ephemeral "← → to navigate" hint on first keyboard focus via useKeyboardHint, teaching sighted keyboard users that arrows move within the group.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Toolbar', 'Button', 'Icon', 'Card', 'Section', 'Text', 'Layout'],
+};

package/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Toolbar} from '@astryxdesign/core/Toolbar';
+import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Card} from '@astryxdesign/core/Card';
+import {Section} from '@astryxdesign/core/Section';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+import {BoldIcon, ItalicIcon, UnderlineIcon} from '@heroicons/react/24/outline';
+
+export default function UseKeyboardHintHookUsage() {
+  return (
+    <Card style={{width: 420}}>
+      <Toolbar
+        label="Text formatting"
+        dividers={['bottom']}
+        startContent={
+          <>
+            <Button
+              label="Bold"
+              variant="ghost"
+              icon={<Icon icon={BoldIcon} />}
+              isIconOnly
+            />
+            <Button
+              label="Italic"
+              variant="ghost"
+              icon={<Icon icon={ItalicIcon} />}
+              isIconOnly
+            />
+            <Button
+              label="Underline"
+              variant="ghost"
+              icon={<Icon icon={UnderlineIcon} />}
+              isIconOnly
+            />
+          </>
+        }
+      />
+      <Section>
+        <VStack gap={1}>
+          <Text type="body" weight="bold">
+            Keyboard-friendly by default
+          </Text>
+          <Text type="supporting" color="secondary">
+            Tab into the toolbar with your keyboard and Toolbar shows an
+            ephemeral "← → to navigate" hint — powered by useKeyboardHint — so
+            sighted keyboard users learn that arrows move within the group.
+          </Text>
+        </VStack>
+      </Section>
+    </Card>
+  );
+}

package/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs

@@ -10,5 +10,5 @@ export const doc = {
     'Shows a page summary when hovering a link: title, description, and URL. Use for documentation links, article references, or any URL where a preview helps the user decide whether to click.',
   isReady: true,
   aspectRatio: 16 / 9,
-  componentsUsed: ['HoverCard', 'Icon', 'Layout', 'Text'],
+  componentsUsed: ['HoverCard', 'Icon', 'Layout', 'Link', 'Text'],
 };

package/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx

@@ -5,12 +5,14 @@
 import {HoverCard} from '@astryxdesign/core/HoverCard';
 import {Icon} from '@astryxdesign/core/Icon';
 import {VStack, HStack} from '@astryxdesign/core/Layout';
+import {Link} from '@astryxdesign/core/Link';
 import {Text} from '@astryxdesign/core/Text';
 import {LinkIcon} from '@heroicons/react/24/outline';
 
 export default function HoverCardInteractiveContent() {
   return (
-    <Text type="body">Read more in the{' '}
+    <Text type="body">
+      Read more in the{' '}
       <HoverCard
         placement="below"
         content={
@@ -30,8 +32,11 @@ export default function HoverCardInteractiveContent() {
             </HStack>
           </VStack>
         }>
-        Getting Started Guide
-      </HoverCard>.
-          </Text>
+        <Link href="#" hasUnderline>
+          Getting Started Guide
+        </Link>
+      </HoverCard>
+      .
+    </Text>
   );
 }

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

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

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

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

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

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

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

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

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

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

package/templates/blocks/components/Lightbox/LightboxGallery.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: 'Lightbox',
+  name: 'Lightbox — Gallery',
+  displayName: 'Lightbox — Gallery',
+  description:
+    'A thumbnail grid that opens a fullscreen gallery. Clicking any thumbnail opens the lightbox at that index. Prev/next navigation lets users browse all images without closing.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Lightbox', 'Grid', 'Thumbnail'],
+};

package/templates/blocks/components/Lightbox/LightboxGallery.tsx

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useLightbox} from '@astryxdesign/core/Lightbox';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Thumbnail} from '@astryxdesign/core/Thumbnail';
+
+const PHOTOS = [
+  {
+    src: 'https://lookaside.facebook.com/assets/astryx/Neutral-Backpack.png',
+    alt: 'Backpack',
+    caption: 'A backpack displayed on a neutral background.',
+  },
+  {
+    src: 'https://lookaside.facebook.com/assets/astryx/building.png',
+    alt: 'Modern building',
+    caption: 'A modern building with a contemporary architectural design.',
+  },
+  {
+    src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
+    alt: 'Coastal shoreline with ocean waves',
+    caption:
+      'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
+  },
+  {
+    src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-1.png',
+    alt: 'Illustrated lakeside landscape at sunset',
+    caption:
+      'A stylized landscape illustration featuring pink clouds reflected over a calm lake at sunset.',
+  },
+];
+
+export default function LightboxGallery() {
+  const lightbox = useLightbox({media: PHOTOS});
+
+  return (
+    <>
+      <Grid columns={2} gap={2} style={{width: 136}}>
+        {PHOTOS.map((photo, i) => (
+          <Thumbnail
+            key={photo.src}
+            src={photo.src}
+            alt={photo.alt}
+            label={photo.alt}
+            onClick={() => lightbox.open(i)}
+          />
+        ))}
+      </Grid>
+      {lightbox.element}
+    </>
+  );
+}

package/templates/blocks/components/Lightbox/LightboxShowcase.tsx

@@ -12,9 +12,10 @@ export default function LightboxShowcase() {
         isOpen={isOpen}
         onOpenChange={setIsOpen}
         media={{
-          src: 'https://picsum.photos/id/10/1200/800',
-          alt: 'Forest path',
-          caption: 'A winding path through the forest',
+          src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
+          alt: 'Coastal shoreline with ocean waves',
+          caption:
+            'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
         }}
       />
     </>

package/templates/blocks/components/Lightbox/LightboxVideo.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: 'Lightbox',
+  name: 'Lightbox — Video',
+  displayName: 'Lightbox — Video',
+  description:
+    'Opens a video in the lightbox. Native browser controls are available. Zoom and pan are disabled for video items.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Lightbox'],
+};

package/templates/blocks/components/Lightbox/LightboxVideo.tsx

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Lightbox} from '@astryxdesign/core/Lightbox';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function LightboxVideo() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Play video" onClick={() => setIsOpen(true)} />
+      <Lightbox
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        media={{
+          src: 'https://lookaside.facebook.com/assets/?set=astryx&name=Nature-1&density=1',
+          alt: 'Flower blooming in time-lapse',
+          type: 'video',
+          caption: 'A flower blooming in time-lapse',
+        }}
+      />
+    </>
+  );
+}

package/templates/blocks/components/Lightbox/LightboxZoom.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: 'Lightbox',
+  name: 'Lightbox — Zoom',
+  displayName: 'Lightbox — Zoom',
+  description:
+    'A lightbox with zoom and pan enabled. Double-click the image to zoom in; drag to pan around. Double-click again or use the close button to exit.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Lightbox', 'Thumbnail'],
+};

package/templates/blocks/components/Lightbox/LightboxZoom.tsx

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Lightbox} from '@astryxdesign/core/Lightbox';
+import {Thumbnail} from '@astryxdesign/core/Thumbnail';
+
+export default function LightboxZoom() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Thumbnail
+        src="https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png"
+        alt="Coastal shoreline with ocean waves"
+        label="Coastal shoreline with ocean waves"
+        onClick={() => setIsOpen(true)}
+      />
+      <Lightbox
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        media={{
+          src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
+          alt: 'Coastal shoreline with ocean waves',
+          caption:
+            'A scenic coastline. Double-click to zoom in and drag to pan.',
+        }}
+        hasZoom
+      />
+    </>
+  );
+}

package/templates/blocks/components/LinkProvider/LinkProviderCustomLink.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Link Provider — Custom Link Component',
   displayName: 'Link Provider — Custom Link Component',
   description:
-    'Routes every Astryx link through a custom component that intercepts the click — the hook frameworks like Next.js use for client-side navigation. Click the link to see the custom handler fire instead of a full-page load.',
+    'Routes every Astryx link through a custom component that intercepts the click, the hook frameworks like Next.js use for client-side navigation. Click the link to see the custom handler fire instead of a full-page load.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['LinkProvider', 'Link'],

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