astryx-dracula 0.2.1 → 0.3.0

package/templates/documentation-technical.tsx

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 // XLE (canonical structure, validated with `bunx astryx layout check`):
-//   L > (LC > V[g=8] > (V[g=2] > Tx.display-1"Getting started with Astryx Dracula" + Tx"Last updated March 30, 2026"[t=supporting]) + (C > V[g=3] > (H[j=between] > (H[g=2] > Ic + Tx"AI Assistance"[t=body]) + (H > B"Copy prompt" + DM)) + Tx"Prompt description"[t=body]) + (V[g=4] > Hd"Prerequisites"[level=2] + UL) + D + (V[g=4] > Hd"Install the package"[level=2] + Tx"Description"[t=body] + (V[g=2] > Tx"Step"[t=body] + Cd)*3) + D + (V[g=4] > Hd"Configure theming"[level=2] + Tx"Description"[t=body] + Cd + Tx"Note"[t=body]) + D + (V[g=4] > Hd"Next steps"[level=2] + UL)) + (LP > Outline)
+//   L > (LC > V[g=8] > (V[g=2] > Hd"Getting started with Astryx Dracula"[level=1] + Tx"Last updated March 30, 2026"[t=supporting]) + (C > V[g=3] > (H[j=between] > (H[g=2] > Ic + Tx"AI Assistance"[t=body]) + (H > B"Copy prompt" + DM)) + Tx"Prompt description"[t=body]) + (V[g=4] > Hd"Prerequisites"[level=2] + UL) + D + (V[g=4] > Hd"Install the package"[level=2] + Tx"Description"[t=body] + (V[g=2] > Tx"Step"[t=body] + Cd)*3) + D + (V[g=4] > Hd"Configure theming"[level=2] + Tx"Description"[t=body] + Cd + Tx"Note"[t=body]) + D + (V[g=4] > Hd"Next steps"[level=2] + UL)) + (LP > Outline)
 
-import {useCallback, useState, type CSSProperties} from 'react';
+import {useCallback, useState} from 'react';
 import {Heading, Text} from '@astryxdesign/core/Text';
 import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
@@ -17,11 +17,31 @@ 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';
+import {outlinePanel} from 'astryx-dracula/shared/chaptered-doc-config';
 
 // ---------------------------------------------------------------------------
 // Main component
 // ---------------------------------------------------------------------------
 
+/**
+ * Documentation technical — the getting-started guide: prerequisites, install steps, theming, and next steps. (Frame/responsive/container: see XLE header above.)
+ */
+
+// Same prompt in the copy action and the visible body: one string, so the
+// two can never drift.
+const SETUP_PROMPT =
+  '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.';
+
+// Copies the setup prompt in the shape each tool wants to receive it. The
+// menu cannot navigate anywhere from a static template, so the action says
+// what it does.
+const PROMPT_TARGETS = ['v0', 'Claude', 'ChatGPT', 'Cursor'].map(target => ({
+  label: `Copy for ${target}`,
+  onClick: () => {
+    void navigator.clipboard.writeText(SETUP_PROMPT);
+  },
+}));
+
 const OUTLINE_ITEMS: OutlineItem[] = [
   {id: 'prerequisites', label: 'Prerequisites', level: 2},
   {id: 'install-package', label: 'Install the package', level: 2},
@@ -34,13 +54,6 @@ const OUTLINE_OPTIONS = OUTLINE_ITEMS.map(item => ({
   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,
@@ -75,7 +88,7 @@ export default function DocumentationTechnical() {
         <LayoutContent isScrollable={false} padding={8}>
           <VStack gap={8}>
             <VStack gap={2}>
-              <Text type="display-1">Getting started with Astryx Dracula</Text>
+              <Heading level={1}>Getting started with Astryx Dracula</Heading>
               <Text type="supporting" color="secondary" hasTabularNumbers>
                 Last updated March 30, 2026
               </Text>
@@ -108,9 +121,7 @@ export default function DocumentationTechnical() {
                     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.',
-                      );
+                      void navigator.clipboard.writeText(SETUP_PROMPT);
                     }}
                   />
                   <DropdownMenu
@@ -121,12 +132,7 @@ export default function DocumentationTechnical() {
                       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: () => {}},
-                    ]}
+                    items={PROMPT_TARGETS}
                   />
                 </HStack>
                 <Text type="body" color="secondary">
@@ -174,6 +180,7 @@ export default function DocumentationTechnical() {
                   code="npm install @astryxdesign/core"
                   language="bash"
                   width="100%"
+                  hasCopyButton
                 />
               </VStack>
               <VStack gap={2}>
@@ -190,6 +197,7 @@ export default function DocumentationTechnical() {
 import '@astryxdesign/core/astryx.css';`}
                   language="tsx"
                   width="100%"
+                  hasCopyButton
                 />
               </VStack>
               <VStack gap={2}>
@@ -204,6 +212,7 @@ export default function App() {
 }`}
                   language="tsx"
                   width="100%"
+                  hasCopyButton
                 />
               </VStack>
             </VStack>
@@ -231,6 +240,7 @@ export default function App({ children }) {
 }`}
                 language="tsx"
                 width="100%"
+                hasCopyButton
               />
               <Text type="body" color="secondary">
                 See the theming guide for the full list of customizable tokens.

package/templates/documentation.template.mjs

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

package/templates/documentation.tsx

@@ -1,6 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 // XLE (canonical structure, validated with `bunx astryx layout check`):
-//   L > LC > V[g=10] > (C[p=10] > (H[g=8 a=center] > (V[g=4] > Tx.display-1"The coven grimoire" + Tx.lg"Every incantation in the Astryx spellbook"[t=large] + (H > B.primary"Enter the grimoire")))) + (V[g=4] > (H[j=between a=center] > Hd"Category"[level=2] + Tx"18 spells"[t=supporting]) + (G[c=4 g=2] > (CC[p=2] > V[g=3] > C[p=0] + (V[g=1] > Tx"AppShell"[t=body] + Tx"Description"[t=body]))*4))*4
+// Counts: 31 total, Core 18 / Layout 4 / Navigation 4 / Form 5. Derived at
+// render from COMPONENT_CATEGORIES, so these numerals must move together with
+// the array -- the gate in scripts/check.ts reads the rendered count, not this
+// comment.
+//   L > LC > V[g=10] > (C[p=10] > (H[g=8 a=center] > (V[g=4] > Hd"The coven grimoire"[level=1 t=display-1] + Tx.lg"Every incantation in the Astryx spellbook"[t=large] + (H > B.primary"Enter the grimoire")))) + (V[g=4] > (H[j=between a=center] > Hd"Core"[level=2] + Tx"18 spells"[t=body]) + (H[j=between a=center] > Hd"Layout"[level=2] + Tx"4 spells"[t=body]) + (H[j=between a=center] > Hd"Navigation"[level=2] + Tx"4 spells"[t=body]) + (H[j=between a=center] > Hd"Form"[level=2] + Tx"5 spells"[t=body]) + (G[c={min:260} g=4] > (CC[p=4] > V[g=3] > C[p=0] + (V[g=1] > Tx"Avatar"[t=body] + Tx"Avatars represent"[t=body]))*4))
+
+/**
+ * Documentation catalog — every component shelf in the grimoire.  Frame-first layout (see `bunx astryx docs layout`): (Frame/responsive/container: see XLE header above.)
+ */
 
 import type {CSSProperties} from 'react';
 import {Heading, Text} from '@astryxdesign/core/Text';
@@ -10,25 +18,25 @@ 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';
+import {SceneTile} from 'astryx-dracula/shared/scene-tile';
+import {galleryImageClip} from 'astryx-dracula/shared/gallery-image';
+import type {SceneHue} from 'astryx-dracula/shared/scene-hues';
 
-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,
+  margin: 'calc(var(--spacing-2) * -1)',
 };
 
-// Dracula accent per grimoire shelf.
-const SHELF_HUES: Record<string, string> = {
-  Core: 'var(--dracula-purple)',
+// Same-route hash: demo links stay focusable anchors without escaping the
+// template through the hash router (bare "#" would drop back to the home page).
+const SELF_HASH = '#/templates/documentation';
+
+// Decorative accent per grimoire shelf. None of them is purple: the sigils
+// are not interactive, and purple belongs to the things that are. Art lives
+// in shared/scene-tile (lg fork: centered glyph on a flat field).
+const SHELF_HUES: Record<string, SceneHue> = {
+  Core: 'var(--dracula-pink)',
   Layout: 'var(--dracula-cyan)',
   Navigation: 'var(--dracula-green)',
   Form: 'var(--dracula-yellow)',
@@ -216,50 +224,16 @@ const COMPONENT_CATEGORIES = [
   },
 ];
 
-// ---------------------------------------------------------------------------
-// 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>
-  );
-}
+// Every count in this template is DERIVED from the array above, never written as
+// a numeral. The hero copy and the per-category "N spells" line both read this
+// and `items.length`, so adding a component can no longer make the page lie
+// about its own size -- which is what happened while the hero copy said
+// "twenty-eight" against 31 entries and the XLE header said 15 for a category
+// of 18.
+const COMPONENT_TOTAL = COMPONENT_CATEGORIES.reduce(
+  (sum, category) => sum + category.items.length,
+  0,
+);
 
 // ---------------------------------------------------------------------------
 // Main component
@@ -273,26 +247,26 @@ export default function DocumentationCatalog() {
       content={
         <LayoutContent padding={8}>
           <VStack gap={10}>
-            <Card variant="gray" padding={10}>
+            <Card variant="transparent" padding={10}>
               <HStack gap={8} vAlign="center">
                 <StackItem size="fill">
                   <VStack gap={4}>
-                    <Text type="display-1">The coven grimoire</Text>
+                    <Heading level={1} type="display-1">
+                      The coven grimoire
+                    </Heading>
                     <Text type="large" weight="normal" color="secondary">
-                      Every incantation in the Astryx spellbook — thirty-one
-                      components for building beautiful, accessible products
-                      after dark.
+                      Every incantation in the Astryx spellbook, with{' '}
+                      {COMPONENT_TOTAL} 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>
 
@@ -301,33 +275,37 @@ export default function DocumentationCatalog() {
                 <HStack justify="between" vAlign="center">
                   <Heading level={2}>{category.label}</Heading>
                   <Text
-                    type="supporting"
+                    type="body"
                     color="secondary"
                     hasTabularNumbers>
                     {category.items.length}{' '}
                     {category.items.length === 1 ? 'spell' : 'spells'}
                   </Text>
                 </HStack>
-                <Grid columns={{minWidth: 260}} gap={2} style={cardGrid}>
+                <Grid columns={{minWidth: 260}} gap={4} style={cardGrid}>
                   {category.items.map(item => (
                     <ClickableCard
                       key={item.key}
                       label={`Open ${item.name}`}
-                      onClick={() => {}}
+                      href={SELF_HASH}
                       variant="transparent"
-                      padding={2}>
+                      padding={4}>
                       <VStack gap={3}>
                         <Card
                           variant="muted"
                           padding={0}
                           minHeight={160}
-                          style={previewClip}>
-                          <PreviewArt
-                            name={item.name}
-                            shelf={category.label}
+                          style={galleryImageClip}>
+                          <SceneTile
+                            label={`${item.name} sigil`}
+                            hue={
+                              SHELF_HUES[category.label] ??
+                              'var(--dracula-comment)'
+                            }
+                            size="lg"
                           />
                         </Card>
-                        <VStack gap={0.5}>
+                        <VStack gap={1}>
                           <Text type="body" weight="semibold">
                             {item.name}
                           </Text>