astryx-dracula 0.1.3 → 0.2.0

package/templates/documentation-technical.template.mjs

@@ -0,0 +1,6 @@
+export default {
+  type: 'page',
+  name: 'Technical Documentation',
+  description: 'Install steps, theming setup, and next steps',
+  category: 'marketing',
+};

package/templates/documentation-technical.tsx

@@ -0,0 +1,292 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useCallback, useState, type CSSProperties} from 'react';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';
+import {List, ListItem} from '@astryxdesign/core/List';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Selector} from '@astryxdesign/core/Selector';
+import {HStack, VStack, StackItem} from '@astryxdesign/core/Stack';
+import {Layout, LayoutContent, LayoutPanel} from '@astryxdesign/core/Layout';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Outline, type OutlineItem} from '@astryxdesign/core/Outline';
+import {useMediaQuery} from '@astryxdesign/core/hooks';
+import {Sparkles, ClipboardCopy, ChevronDown} from 'lucide-react';
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+const OUTLINE_ITEMS: OutlineItem[] = [
+  {id: 'prerequisites', label: 'Prerequisites', level: 2},
+  {id: 'install-package', label: 'Install the package', level: 2},
+  {id: 'configure-theming', label: 'Configure theming', level: 2},
+  {id: 'next-steps', label: 'Next steps', level: 2},
+];
+
+const OUTLINE_OPTIONS = OUTLINE_ITEMS.map(item => ({
+  value: item.id,
+  label: item.label,
+}));
+
+const outlinePanel: CSSProperties = {
+  position: 'sticky',
+  top: 24,
+  alignSelf: 'start',
+  paddingBlockStart: 120,
+};
+
+export default function DocumentationTechnical() {
+  const [activeId, setActiveId] = useState<string | undefined>(
+    OUTLINE_ITEMS[0]?.id,
+  );
+  const isMobile = useMediaQuery('(max-width: 768px)');
+
+  const scrollToId = useCallback((id: string) => {
+    setActiveId(id);
+    const target = document.getElementById(id);
+    if (target != null) {
+      target.scrollIntoView({behavior: 'smooth', block: 'start'});
+      window.history.pushState(null, '', `#${id}`);
+    }
+  }, []);
+
+  return (
+    <Layout
+      height="auto"
+      contentWidth={960}
+      end={
+        isMobile ? undefined : (
+          <LayoutPanel
+            isScrollable={false}
+            label="On this page"
+            role="complementary"
+            style={outlinePanel}>
+            <Outline items={OUTLINE_ITEMS} onActiveIdChange={setActiveId} />
+          </LayoutPanel>
+        )
+      }
+      content={
+        <LayoutContent isScrollable={false} padding={8}>
+          <VStack gap={8}>
+            <VStack gap={2}>
+              <Text type="display-1">Getting started with Astryx Dracula</Text>
+              <Text type="supporting" color="secondary" hasTabularNumbers>
+                Last updated March 30, 2026
+              </Text>
+              {isMobile && (
+                <Selector
+                  label="On this page"
+                  isLabelHidden
+                  options={OUTLINE_OPTIONS}
+                  value={activeId}
+                  onChange={scrollToId}
+                  width="100%"
+                />
+              )}
+            </VStack>
+
+            <Card>
+              <VStack gap={3}>
+                <HStack gap={2} vAlign="center">
+                  <StackItem size="fill">
+                    <HStack gap={2} vAlign="center">
+                      <Icon icon={Sparkles} size="sm" color="secondary" />
+                      <Text type="body" weight="semibold">
+                        AI Assistance
+                      </Text>
+                    </HStack>
+                  </StackItem>
+                  <Button
+                    label="Copy prompt"
+                    variant="ghost"
+                    size="sm"
+                    icon={<Icon icon={ClipboardCopy} />}
+                    onClick={() => {
+                      void navigator.clipboard.writeText(
+                        'Help me get set up with Astryx Dracula. Based on my project, do the following: 1. Install @astryxdesign/core and the StyleX compiler. 2. Wrap my app in ThemeProvider. 3. Replace one existing component with an Astryx equivalent. After setup, suggest relevant next steps based on my project.',
+                      );
+                    }}
+                  />
+                  <DropdownMenu
+                    button={{
+                      label: 'More options',
+                      variant: 'ghost',
+                      size: 'sm',
+                      isIconOnly: true,
+                      icon: <Icon icon={ChevronDown} />,
+                    }}
+                    items={[
+                      {label: 'Open in v0', onClick: () => {}},
+                      {label: 'Open in Claude', onClick: () => {}},
+                      {label: 'Open in ChatGPT', onClick: () => {}},
+                      {label: 'Open in Cursor', onClick: () => {}},
+                    ]}
+                  />
+                </HStack>
+                <Text type="body" color="secondary">
+                  Help me get set up with Astryx Dracula. Based on my project,
+                  do the following: 1. Install @astryxdesign/core and the
+                  StyleX compiler. 2. Wrap my app in ThemeProvider. 3. Replace
+                  one existing component with an Astryx equivalent.
+                </Text>
+              </VStack>
+            </Card>
+
+            <VStack gap={4}>
+              <Heading id="prerequisites" level={2}>
+                Prerequisites
+              </Heading>
+              <List density="compact" listStyle="disc">
+                <ListItem label="Node.js 18+" />
+                <ListItem label="React 18 or 19" />
+                <ListItem
+                  label="A package manager"
+                  description={
+                    <Text type="body" color="secondary" textWrap="wrap">
+                      npm, yarn, or pnpm
+                    </Text>
+                  }
+                />
+              </List>
+            </VStack>
+
+            <Divider />
+
+            <VStack gap={4}>
+              <Heading id="install-package" level={2}>
+                Install the package
+              </Heading>
+              <Text type="body">
+                Every project starts with installing the core package. This
+                gives you access to all components, tokens, and utilities.
+              </Text>
+              <VStack gap={2}>
+                <Text type="body" weight="bold">
+                  Step 1: Install the core package
+                </Text>
+                <CodeBlock
+                  code="npm install @astryxdesign/core"
+                  language="bash"
+                  width="100%"
+                />
+              </VStack>
+              <VStack gap={2}>
+                <Text type="body" weight="bold">
+                  Step 2: Import the precompiled styles
+                </Text>
+                <Text type="body" color="secondary">
+                  Astryx ships precompiled CSS, so there is no build plugin to
+                  configure. Import the reset and component stylesheets once at
+                  your app entry point.
+                </Text>
+                <CodeBlock
+                  code={`import '@astryxdesign/core/reset.css';
+import '@astryxdesign/core/astryx.css';`}
+                  language="tsx"
+                  width="100%"
+                />
+              </VStack>
+              <VStack gap={2}>
+                <Text type="body" weight="bold">
+                  Step 3: Import your first component
+                </Text>
+                <CodeBlock
+                  code={`import { Button } from '@astryxdesign/core/Button';
+
+export default function App() {
+  return <Button label="Hello Astryx" variant="primary" />;
+}`}
+                  language="tsx"
+                  width="100%"
+                />
+              </VStack>
+            </VStack>
+
+            <Divider />
+
+            <VStack gap={4}>
+              <Heading id="configure-theming" level={2}>
+                Configure theming
+              </Heading>
+              <Text type="body">
+                Astryx ships with a default theme that works out of the box. To
+                customize colors, typography, and spacing, wrap your app in a
+                theme provider.
+              </Text>
+              <CodeBlock
+                code={`import { ThemeProvider } from '@astryxdesign/core/Theme';
+
+export default function App({ children }) {
+  return (
+    <ThemeProvider theme="default">
+      {children}
+    </ThemeProvider>
+  );
+}`}
+                language="tsx"
+                width="100%"
+              />
+              <Text type="body" color="secondary">
+                See the theming guide for the full list of customizable tokens.
+              </Text>
+            </VStack>
+
+            <Divider />
+
+            <VStack gap={4}>
+              <Heading id="next-steps" level={2}>
+                Next steps
+              </Heading>
+              <List density="compact" listStyle="disc">
+                <ListItem
+                  label="Fundamental concepts"
+                  description={
+                    <Text type="body" color="secondary" textWrap="wrap">
+                      How theming, layout, and composition work
+                    </Text>
+                  }
+                />
+                <ListItem
+                  label="Component API reference"
+                  description={
+                    <Text type="body" color="secondary" textWrap="wrap">
+                      Props, variants, and examples for every component
+                    </Text>
+                  }
+                />
+                <ListItem
+                  label="Accessibility"
+                  description={
+                    <Text type="body" color="secondary" textWrap="wrap">
+                      Built-in a11y features and ARIA patterns
+                    </Text>
+                  }
+                />
+                <ListItem
+                  label="CLI tools"
+                  description={
+                    <Text type="body" color="secondary" textWrap="wrap">
+                      Scaffold projects and manage templates
+                    </Text>
+                  }
+                />
+                <ListItem
+                  label="Design tokens"
+                  description={
+                    <Text type="body" color="secondary" textWrap="wrap">
+                      Colors, spacing, typography, and sizing
+                    </Text>
+                  }
+                />
+              </List>
+            </VStack>
+          </VStack>
+        </LayoutContent>
+      }
+    />
+  );
+}

package/templates/documentation.template.mjs

@@ -0,0 +1,6 @@
+export default {
+  type: 'page',
+  name: 'Component Catalog',
+  description: 'Hero plus categorized component grid',
+  category: 'marketing',
+};

package/templates/documentation.tsx

@@ -0,0 +1,347 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {CSSProperties} from 'react';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {ClickableCard} from '@astryxdesign/core/ClickableCard';
+import {HStack, VStack, StackItem} from '@astryxdesign/core/Stack';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Grid} from '@astryxdesign/core/Grid';
+
+const previewArt: CSSProperties = {
+  width: '100%',
+  height: '100%',
+  display: 'block',
+};
+const previewClip: CSSProperties = {
+  borderRadius: 'var(--radius-element)',
+  overflow: 'clip',
+};
+// Negative margin offsets each card's 8px padding so the grid content stays
+// visually aligned while giving every card a padded hover/click target.
+const cardGrid: CSSProperties = {
+  margin: -8,
+};
+
+// Dracula accent per grimoire shelf.
+const SHELF_HUES: Record<string, string> = {
+  Core: 'var(--dracula-purple)',
+  Layout: 'var(--dracula-cyan)',
+  Navigation: 'var(--dracula-green)',
+  Form: 'var(--dracula-yellow)',
+};
+
+// ---------------------------------------------------------------------------
+// Data
+// ---------------------------------------------------------------------------
+
+const COMPONENT_CATEGORIES = [
+  {
+    label: 'Core',
+    items: [
+      {
+        key: 'appshell',
+        name: 'AppShell',
+        desc: 'AppShell provides a foundational page layout with header, sidebar, and content regions. Use it to establish consistent structure across your application.',
+      },
+      {
+        key: 'avatar',
+        name: 'Avatar',
+        desc: 'Avatars represent a person or entity with an image, initials, or icon. They are commonly used in user profiles, comments, and contact lists.',
+      },
+      {
+        key: 'badge',
+        name: 'Badge',
+        desc: 'Badges display small counts or status labels. They can be attached to icons, buttons, or list items to surface key information at a glance.',
+      },
+      {
+        key: 'banner',
+        name: 'Banner',
+        desc: 'Banners show important, non-modal messages at the top of a page or section. They communicate status, warnings, or promotional information.',
+      },
+      {
+        key: 'button',
+        name: 'Button',
+        desc: 'Buttons let people take action. They can be used in forms, dialogs, and toolbars, or as standalone links.',
+      },
+      {
+        key: 'calendar',
+        name: 'Calendar',
+        desc: 'Calendar provides a date-picking grid for selecting single dates or date ranges. It integrates with form fields for date input.',
+      },
+      {
+        key: 'dialog',
+        name: 'Dialog',
+        desc: 'Dialogs are modal overlays that require user attention or action before continuing. They are used for confirmations, forms, and critical decisions.',
+      },
+      {
+        key: 'dropdownmenu',
+        name: 'DropdownMenu',
+        desc: 'DropdownMenu presents a list of actions or options in a floating overlay. It is triggered by a button and supports nested submenus.',
+      },
+      {
+        key: 'empty-state',
+        name: 'EmptyState',
+        desc: 'EmptyState provides a placeholder when there is no content to display. It guides users with a message, illustration, and optional call-to-action.',
+      },
+      {
+        key: 'hovercard',
+        name: 'HoverCard',
+        desc: 'HoverCard shows a rich preview of content when users hover over a trigger element. It is ideal for previewing profiles, links, or details.',
+      },
+      {
+        key: 'icon',
+        name: 'Icon',
+        desc: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text.',
+      },
+      {
+        key: 'kbd',
+        name: 'Kbd',
+        desc: 'Kbd renders keyboard shortcut hints in a styled inline element. Use it to show users which key combinations perform specific actions.',
+      },
+      {
+        key: 'link',
+        name: 'Link',
+        desc: 'Links provide navigation between pages or to external resources. They follow accessible anchor semantics with visual affordance.',
+      },
+      {
+        key: 'list',
+        name: 'List',
+        desc: 'List displays a vertical set of related items. It supports selection, icons, and metadata for building menus, nav lists, and more.',
+      },
+      {
+        key: 'popover',
+        name: 'Popover',
+        desc: 'Popover displays rich content in a floating panel anchored to a trigger element. It is used for forms, filters, and contextual tools.',
+      },
+      {
+        key: 'table',
+        name: 'Table',
+        desc: 'Table displays structured data in rows and columns with support for sorting, selection, and custom cell rendering.',
+      },
+      {
+        key: 'token',
+        name: 'Token',
+        desc: 'Tokens display compact metadata labels such as tags, categories, or filters. They can be dismissible and support selection state.',
+      },
+      {
+        key: 'tooltip',
+        name: 'Tooltip',
+        desc: 'Tooltips show concise helper text when users hover over or focus an element. They clarify icons, truncated labels, and controls.',
+      },
+    ],
+  },
+  {
+    label: 'Layout',
+    items: [
+      {
+        key: 'card',
+        name: 'Card',
+        desc: 'Cards group related content and actions in a contained surface. They can include headers, media, body text, and action bars.',
+      },
+      {
+        key: 'divider',
+        name: 'Divider',
+        desc: 'Dividers separate content into distinct sections with a subtle or strong horizontal line. They can optionally include a label.',
+      },
+      {
+        key: 'grid',
+        name: 'Grid',
+        desc: 'Grid provides a CSS grid-based layout container with configurable columns, rows, and gap. It simplifies responsive multi-column designs.',
+      },
+      {
+        key: 'stack',
+        name: 'Stack',
+        desc: 'Stack arranges child elements in a row or column with consistent gap spacing. It is the primary tool for one-dimensional layout composition.',
+      },
+    ],
+  },
+  {
+    label: 'Navigation',
+    items: [
+      {
+        key: 'breadcrumbs',
+        name: 'Breadcrumbs',
+        desc: "Breadcrumbs show the user's current location within a navigation hierarchy. They provide quick links back to parent pages.",
+      },
+      {
+        key: 'sidenav',
+        name: 'SideNav',
+        desc: 'SideNav renders a vertical navigation panel with links, sections, and collapsible groups. It is used as the primary nav in dashboard layouts.',
+      },
+      {
+        key: 'tablist',
+        name: 'TabList',
+        desc: 'TabList switches between content views using a horizontal row of tabs. Only one tab is active at a time, and content changes without a page reload.',
+      },
+      {
+        key: 'topnav',
+        name: 'TopNav',
+        desc: 'TopNav provides an app-level navigation bar across the top of the page. It holds branding, primary links, search, and user actions.',
+      },
+    ],
+  },
+  {
+    label: 'Form',
+    items: [
+      {
+        key: 'checkboxinput',
+        name: 'CheckboxInput',
+        desc: 'CheckboxInput renders a single checkbox with a label. It is used for boolean opt-in choices like terms acceptance or feature toggles.',
+      },
+      {
+        key: 'selector',
+        name: 'Selector',
+        desc: 'Selector lets users pick a single item from a dropdown list. It supports search, grouping, and custom option rendering.',
+      },
+      {
+        key: 'switch',
+        name: 'Switch',
+        desc: 'Switch toggles a setting between on and off states with immediate effect. It is used for preferences, feature flags, and real-time controls.',
+      },
+      {
+        key: 'textinput',
+        name: 'TextInput',
+        desc: 'TextInput is a single-line text field for short user input like names, emails, and search queries. It supports icons, prefixes, and validation.',
+      },
+      {
+        key: 'typeahead',
+        name: 'Typeahead',
+        desc: 'Typeahead provides an autocomplete search input that suggests results as the user types. It supports async data sources and custom rendering.',
+      },
+    ],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Preview art
+// ---------------------------------------------------------------------------
+
+function PreviewArt({name, shelf}: {name: string; shelf: string}) {
+  const hue = SHELF_HUES[shelf] ?? 'var(--dracula-purple)';
+  return (
+    <svg
+      viewBox="0 0 400 300"
+      preserveAspectRatio="xMidYMid slice"
+      style={previewArt}
+      role="img"
+      aria-label={`${name} sigil`}>
+      <rect width="400" height="300" fill="var(--dracula-bg-light)" />
+      <circle cx="316" cy="66" r="26" fill={hue} opacity={0.85} />
+      <circle
+        cx="306"
+        cy="60"
+        r="21"
+        fill="var(--dracula-bg-light)"
+        opacity={0.5}
+      />
+      <path
+        d="M0 208 Q110 168 210 198 T400 184 V300 H0 Z"
+        fill="var(--dracula-current-line)"
+      />
+      <path
+        d="M0 236 Q130 206 260 230 T400 222 V300 H0 Z"
+        fill="var(--dracula-bg)"
+      />
+      <g
+        transform="translate(140 150)"
+        fill="none"
+        stroke="var(--dracula-comment)"
+        strokeWidth="5"
+        strokeLinecap="round"
+        strokeLinejoin="round">
+        <rect x="-44" y="-44" width="88" height="88" rx="5" />
+        <circle cx="18" cy="-18" r="2.5" fill={hue} stroke="none" />
+        <path d="M-34 30 L-8 0 L10 18 L20 8 L34 24" />
+      </g>
+    </svg>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+export default function DocumentationCatalog() {
+  return (
+    <Layout
+      height="fill"
+      contentWidth={1200}
+      content={
+        <LayoutContent padding={8}>
+          <VStack gap={10}>
+            <Card variant="gray" padding={10}>
+              <HStack gap={8} vAlign="center">
+                <StackItem size="fill">
+                  <VStack gap={4}>
+                    <Text type="display-1">The coven grimoire</Text>
+                    <Text type="large" weight="normal" color="secondary">
+                      Every incantation in the Astryx spellbook — thirty-one
+                      components for building beautiful, accessible products
+                      after dark.
+                    </Text>
+                    <HStack>
+                      <Button
+                        label="Enter the grimoire"
+                        variant="primary"
+                        size="lg"
+                      />
+                    </HStack>
+                  </VStack>
+                </StackItem>
+                <StackItem size="fill" />
+              </HStack>
+            </Card>
+
+            {COMPONENT_CATEGORIES.map(category => (
+              <VStack key={category.label} gap={4}>
+                <HStack justify="between" vAlign="center">
+                  <Heading level={2}>{category.label}</Heading>
+                  <Text
+                    type="supporting"
+                    color="secondary"
+                    hasTabularNumbers>
+                    {category.items.length}{' '}
+                    {category.items.length === 1 ? 'spell' : 'spells'}
+                  </Text>
+                </HStack>
+                <Grid columns={{minWidth: 260}} gap={2} style={cardGrid}>
+                  {category.items.map(item => (
+                    <ClickableCard
+                      key={item.key}
+                      label={`Open ${item.name}`}
+                      onClick={() => {}}
+                      variant="transparent"
+                      padding={2}>
+                      <VStack gap={3}>
+                        <Card
+                          variant="muted"
+                          padding={0}
+                          minHeight={160}
+                          style={previewClip}>
+                          <PreviewArt
+                            name={item.name}
+                            shelf={category.label}
+                          />
+                        </Card>
+                        <VStack gap={0.5}>
+                          <Text type="body" weight="bold">
+                            {item.name}
+                          </Text>
+                          <Text type="body" color="secondary" maxLines={3}>
+                            {item.desc}
+                          </Text>
+                        </VStack>
+                      </VStack>
+                    </ClickableCard>
+                  ))}
+                </Grid>
+              </VStack>
+            ))}
+          </VStack>
+        </LayoutContent>
+      }
+    />
+  );
+}

package/templates/editor.template.mjs

@@ -0,0 +1,6 @@
+export default {
+  type: 'page',
+  name: 'Page Editor',
+  description: 'Block builder with sidebar config and preview',
+  category: 'tooling',
+};