astryx-dracula 0.2.0 → 0.3.0

package/shared/chaptered-doc-config.ts

@@ -0,0 +1,92 @@
+// Chaptered-doc TYPES and FRAME STYLES, split from the components.
+//
+// WHY: chaptered-doc.tsx exports components, and a .tsx exporting
+// non-components breaks React Fast Refresh.
+// `react-doctor/only-export-components` catches it. See shared/scene-hues.ts
+// for the same split, same reason.
+//
+// Everything the four callers (chaptered-doc, documentation-design,
+// documentation-technical, product-tour, tech-report) share lives here; the
+// outline-building and scroll helpers that only chaptered-doc itself calls stay
+// unexported in that file.
+import type {CSSProperties} from 'react';
+import type {IconType} from '@astryxdesign/core/Icon';
+import type {OutlineItem} from '@astryxdesign/core/Outline';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface DocSection {
+  // Unique within the chapter; the DOM id is derived from it so the outline
+  // links and the headings can never drift apart.
+  key: string;
+  heading: string;
+  body: string;
+  bullets?: string[];
+  code?: {language: string; title: string; source: string};
+}
+
+export interface DocChapter {
+  id: string;
+  title: string;
+  icon: IconType;
+  intro: string;
+  hasArt?: boolean;
+  sections: DocSection[];
+}
+
+export type ChapterGroup = {title: string; chapters: DocChapter[]};
+
+export const sectionId = (chapterId: string, key: string) =>
+  `${chapterId}--${key}`;
+
+// Astryx has no image primitive: AspectRatio exposes no objectFit or radius
+// props, so the scene fill and the corner clip live in these two styles.
+export const sceneFill: CSSProperties = {
+  width: '100%',
+  height: '100%',
+  display: 'block',
+};
+export const sceneClip: CSSProperties = {
+  borderRadius: 'var(--radius-container)',
+  overflow: 'clip',
+};
+
+// The outline is sticky so it tracks the chapter as the document scrolls.
+export const outlinePanel: CSSProperties = {
+  position: 'sticky',
+  top: 'var(--spacing-6)',
+  alignSelf: 'start',
+  // No paddingBlockStart. This object is applied via `style=` to the outline
+  // LayoutPanels (chaptered-doc.tsx:316, documentation-design.tsx:592,
+  // documentation-technical.tsx:82), and an inline style prop BEATS the stylex
+  // class -- so this 8px silently overrode the panel's own 16px block padding
+  // at the top edge only, leaving every "On this page" rail in the kit
+  // asymmetric by 8px. The panel already owns its block padding.
+};
+
+// Derived once per page so the Outline receives a stable array identity
+// and does not re-register its scroll spy on every render.
+export function buildOutlineByChapter(
+  chapters: DocChapter[],
+): Record<string, OutlineItem[]> {
+  return Object.fromEntries(
+    chapters.map(chapter => [
+      chapter.id,
+      chapter.sections.map(section => ({
+        id: sectionId(chapter.id, section.key),
+        label: section.heading,
+        level: 2,
+      })),
+    ]),
+  );
+}
+
+export function scrollToSection(id: string) {
+  const target = document.getElementById(id);
+  if (target != null) {
+    target.scrollIntoView({behavior: 'smooth', block: 'start'});
+  }
+}
+
+// ─── Rail ────────────────────────────────────────────────────────────────────
+

package/shared/chaptered-doc.tsx

@@ -0,0 +1,332 @@
+// Identical scaffold shared by the product-tour and tech-report templates:
+// chapter rail (SideNav) + Layout content + sticky Outline that collapses to
+// an "On this page" Selector below 1024px (the AppShell drawer owns the rail
+// there behind the MobileNavToggle). Chapter data stays in each template.
+// Scene systems stay local too: product-tour keeps BAT_WING/BAT_BODY/FIR +
+// NightScene/PaletteScene/TypeScene/PagesScene, tech-report keeps its own.
+
+import {
+  buildOutlineByChapter,
+  outlinePanel,
+  sceneClip,
+  sceneFill,
+  scrollToSection,
+  sectionId,
+  type ChapterGroup,
+  type DocChapter,
+  type DocSection,
+} from 'astryx-dracula/shared/chaptered-doc-config';
+import {useState, type CSSProperties, type ReactNode} from 'react';
+
+import {AppShell} from '@astryxdesign/core/AppShell';
+import {MobileNavToggle} from '@astryxdesign/core/MobileNav';
+import {
+  SideNav,
+  SideNavHeading,
+  SideNavItem,
+  SideNavSection,
+} from '@astryxdesign/core/SideNav';
+import {NavIcon} from '@astryxdesign/core/NavIcon';
+import {
+  HStack,
+  Layout,
+  LayoutContent,
+  LayoutPanel,
+  StackItem,
+  VStack,
+} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import type {IconType} from '@astryxdesign/core/Icon';
+import {AspectRatio} from '@astryxdesign/core/AspectRatio';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Divider} from '@astryxdesign/core/Divider';
+import {List, ListItem} from '@astryxdesign/core/List';
+import {Outline} from '@astryxdesign/core/Outline';
+import {Selector} from '@astryxdesign/core/Selector';
+import {useMediaQuery} from '@astryxdesign/core/hooks';
+
+import {ChevronLeft, ChevronRight} from 'lucide-react';
+
+export function ChapterRail({
+  groups,
+  activeId,
+  onSelect,
+  heading,
+  subheading,
+  headingHref,
+  headingIcon,
+}: {
+  groups: ChapterGroup[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  heading: string;
+  subheading: string;
+  headingHref: string;
+  headingIcon: ReactNode;
+}) {
+  // Resizable like the shell-side-nav template: 264 default, 220-400 range.
+  // The AppShell drawer owns the rail below 1024px (see MobileNavToggle),
+  // so the handle only matters at desktop widths.
+  return (
+    <SideNav
+      collapsible
+      resizable={{defaultWidth: 264, minWidth: 220, maxWidth: 400}}
+      header={
+        <SideNavHeading
+          icon={<NavIcon icon={headingIcon} />}
+          heading={heading}
+          subheading={subheading}
+          headingHref={headingHref}
+        />
+      }>
+      {groups.map(group => (
+        <SideNavSection key={group.title} title={group.title}>
+          {group.chapters.map(chapter => (
+            <SideNavItem
+              key={chapter.id}
+              label={chapter.title}
+              icon={chapter.icon}
+              isSelected={chapter.id === activeId}
+              onClick={() => onSelect(chapter.id)}
+            />
+          ))}
+        </SideNavSection>
+      ))}
+    </SideNav>
+  );
+}
+
+// ─── Chapter body ────────────────────────────────────────────────────────────
+
+export function SectionBlock({
+  chapterId,
+  section,
+}: {
+  chapterId: string;
+  section: DocSection;
+}) {
+  return (
+    <VStack gap={3}>
+      <Heading level={2} id={sectionId(chapterId, section.key)}>
+        {section.heading}
+      </Heading>
+      <Text type="body" color="secondary" display="block">
+        {section.body}
+      </Text>
+      {section.bullets != null && (
+        <List listStyle="disc">
+          {section.bullets.map(bullet => (
+            <ListItem key={bullet} label={bullet} />
+          ))}
+        </List>
+      )}
+      {section.code != null && (
+        <CodeBlock
+          code={section.code.source}
+          language={section.code.language}
+          title={section.code.title}
+          width="100%"
+        />
+      )}
+    </VStack>
+  );
+}
+
+export function ChapterNav({
+  chapters,
+  chapter,
+  onSelect,
+}: {
+  chapters: DocChapter[];
+  chapter: DocChapter;
+  onSelect: (id: string) => void;
+}) {
+  const index = chapters.findIndex(entry => entry.id === chapter.id);
+  const previous = index > 0 ? chapters[index - 1] : undefined;
+  const next = index < chapters.length - 1 ? chapters[index + 1] : undefined;
+  return (
+    <HStack gap={3} hAlign="between" vAlign="center">
+      {previous != null ? (
+        <Button
+          label={previous.title}
+          variant="secondary"
+          icon={<Icon icon={ChevronLeft} size="sm" />}
+          onClick={() => onSelect(previous.id)}
+        />
+      ) : (
+        <StackItem size="fill" />
+      )}
+      {next != null ? (
+        <Button
+          label={next.title}
+          variant="secondary"
+          endContent={<Icon icon={ChevronRight} size="sm" />}
+          onClick={() => onSelect(next.id)}
+        />
+      ) : (
+        <StackItem size="fill" />
+      )}
+    </HStack>
+  );
+}
+
+// ─── Page ────────────────────────────────────────────────────────────────────
+
+export function ChapterArtFrame({children}: {children: ReactNode}) {
+  return (
+    <AspectRatio ratio={16 / 9} style={sceneClip}>
+      {children}
+    </AspectRatio>
+  );
+}
+
+export default function ChapteredDoc({
+  groups,
+  defaultChapter,
+  railHeading,
+  railSubheading,
+  railHref,
+  railIcon,
+  eyebrow,
+  badge,
+  art,
+  footer,
+}: {
+  groups: ChapterGroup[];
+  defaultChapter: string;
+  railHeading: string;
+  railSubheading: string;
+  railHref: string;
+  railIcon: ReactNode;
+  eyebrow: string;
+  badge: (chapter: DocChapter, index: number, total: number) => ReactNode;
+  art: (chapterId: string) => ReactNode;
+  footer?: ReactNode;
+}) {
+  const chapters = groups.flatMap(group => group.chapters);
+  const [outlineByChapter] = useState(() => buildOutlineByChapter(chapters));
+  const [chapterId, setChapterId] = useState(defaultChapter);
+  const [activeSection, setActiveSection] = useState(
+    outlineByChapter[defaultChapter]?.[0]?.id ?? '',
+  );
+
+  // Responsive contract: below 1024px the outline stops being a column, since
+  // a narrow viewport has nothing to outline against.
+  const isNarrow = useMediaQuery('(max-width: 1024px)');
+
+  const chapter = chapters.find(entry => entry.id === chapterId) ?? chapters[0];
+  const outlineItems = outlineByChapter[chapter.id] ?? [];
+
+  const openChapter = (id: string) => {
+    setChapterId(id);
+    setActiveSection(outlineByChapter[id]?.[0]?.id ?? '');
+    // A chapter reads as a new page, so the document goes back to the top
+    // instead of keeping the previous chapter's scroll offset.
+    window.scrollTo({top: 0});
+  };
+
+  return (
+    <AppShell
+      height="auto"
+      contentPadding={0}
+      mobileNav={{hasToggle: false}}
+      sideNav={
+        <ChapterRail
+          groups={groups}
+          activeId={chapter.id}
+          onSelect={openChapter}
+          heading={railHeading}
+          subheading={railSubheading}
+          headingHref={railHref}
+          headingIcon={railIcon}
+        />
+      }>
+      <Layout
+        height="auto"
+        contentWidth={960}
+        end={
+          isNarrow ? undefined : (
+            <LayoutPanel
+              isScrollable={false}
+              label="On this page"
+              role="complementary"
+              style={outlinePanel}>
+              <Outline
+                items={outlineItems}
+                onActiveIdChange={setActiveSection}
+              />
+            </LayoutPanel>
+          )
+        }
+        content={
+          <LayoutContent isScrollable={false} padding={8}>
+            <VStack gap={8}>
+              <VStack gap={2}>
+                <HStack gap={2} vAlign="center">
+                  <MobileNavToggle />
+                  <Text type="supporting" color="secondary">
+                    {eyebrow}
+                  </Text>
+                </HStack>
+                <Heading level={1} type="display-2">
+                  {chapter.title}
+                </Heading>
+                <Text type="supporting" color="secondary" hasTabularNumbers>
+                  {badge(
+                    chapter,
+                    chapters.findIndex(entry => entry.id === chapter.id),
+                    chapters.length,
+                  )}
+                </Text>
+                {isNarrow && (
+                  <Selector
+                    label="On this page"
+                    isLabelHidden
+                    options={outlineItems.map(item => ({
+                      value: item.id,
+                      label: item.label,
+                    }))}
+                    value={activeSection}
+                    onChange={(id: string) => {
+                      setActiveSection(id);
+                      scrollToSection(id);
+                    }}
+                    width="100%"
+                  />
+                )}
+              </VStack>
+
+              <Text type="large" color="secondary" display="block">
+                {chapter.intro}
+              </Text>
+
+              {art(chapter.id)}
+
+              <VStack gap={8}>
+                {chapter.sections.map(section => (
+                  <SectionBlock
+                    key={section.key}
+                    chapterId={chapter.id}
+                    section={section}
+                  />
+                ))}
+              </VStack>
+
+              <Divider />
+
+              <ChapterNav
+                chapters={chapters}
+                chapter={chapter}
+                onSelect={openChapter}
+              />
+
+              {footer}
+            </VStack>
+          </LayoutContent>
+        }
+      />
+    </AppShell>
+  );
+}

package/shared/chart-hues.ts

@@ -0,0 +1,27 @@
+// Shared categorical chart hues: the visual.md categorical ramp as importable
+// constants. Every value is a role token var -- never a raw --dracula-* primitive
+// and never a raw hex -- so the vocabulary is the sanctioned one by construction
+// rather than by convention, and a gate can read the object and enforce it.
+// Purple is deliberately absent: purple means tappable, so it must never encode
+// data. `muted` is a COMMENT-blue grey because it backs the `{label: 'Other'}`
+// legend row (dashboard.tsx:229, :253) -- a labelled data category, not chrome.
+
+export const CHART_HUES = {
+  cyan: 'var(--color-data-categorical-cyan)',
+  orange: 'var(--color-data-categorical-orange)',
+  green: 'var(--color-data-categorical-green)',
+  pink: 'var(--color-data-categorical-pink)',
+  muted: 'var(--color-data-categorical-blue)',
+  // Added because --color-data-categorical-red exists in the palette
+  // (tokens.css:276) and heat maps need a severity colour, but no module
+  // exposed it. Without this, a chart could not reach red through the
+  // sanctioned source at all.
+  red: 'var(--color-data-categorical-red)',
+} as const;
+
+export type ChartHue = (typeof CHART_HUES)[keyof typeof CHART_HUES];
+
+// The value list exists for the gate: it reads the object's VALUES, never a
+// grep across shared/. A text-level filter cannot separate the sanctioned rows
+// from a drifting neighbour, which is why the check is here and not in a lint.
+export const CHART_HUE_VALUES: readonly ChartHue[] = Object.values(CHART_HUES);

package/shared/chart-labels.tsx

@@ -0,0 +1,44 @@
+// Shared SVG chart-axis/label primitives. Every hand-drawn chart label goes
+// through ChartLabel: token fill plus the 13px mono floor from visual.md
+// (nothing meaningful below 12px, ever). The mono family resolves from the
+// `--font-family-mono` theme token, single-sourced with the body/code faces.
+
+import type {ReactNode} from 'react';
+
+export const CHART_LABEL_FILL = 'var(--color-text-paragraph)';
+export const CHART_LABEL_SIZE = 13;
+
+interface ChartLabelProps {
+  x: number | string;
+  y: number | string;
+  textAnchor?: 'start' | 'middle' | 'end';
+  /** Defaults to the paragraph token; pass an explicit fill for values drawn
+   *  on colored fills (e.g. in-cell heatmap counts).
+   *
+   *  Deliberately NOT the chart-legend union: this paints TEXT, so its arms
+   *  are a text role and the on-fill role, and neither is a --color-data-*
+   *  var. Reusing the legend type here would reject the one use it exists
+   *  for. */
+  fill?: `var(--color-text-${string})` | `var(--color-on-${string})`;
+  children: ReactNode;
+}
+
+export function ChartLabel({
+  x,
+  y,
+  textAnchor = 'middle',
+  fill = CHART_LABEL_FILL,
+  children,
+}: ChartLabelProps) {
+  return (
+    <text
+      x={x}
+      y={y}
+      textAnchor={textAnchor}
+      fontSize={CHART_LABEL_SIZE}
+      fill={fill}
+      fontFamily="var(--font-family-mono)">
+      {children}
+    </text>
+  );
+}

package/shared/chart-legend.tsx

@@ -0,0 +1,100 @@
+// Shared chart legend: swatch + label, always paired.
+//
+// WHY THIS EXISTS: the legend was hand-rolled three incompatible ways before
+// this module — dashboard.tsx used an Icon swatch, table-page-heatmap-status
+// used a 12px rx=4 rect, tech-report used an 8px rx=1 rect — so three files
+// disagreed on what a legend swatch even looks like. Meanwhile demo/Bento.tsx
+// and demo/Dashboard.tsx render seven bars in seven hues with no legend at all,
+// so those hues encoded nothing. This module makes that state unrepresentable.
+//
+// COLOUR CONTRACT (UIAuditColorMotion, from references/visual.md): "Legends pair
+// spectral badges with dots; never rely on color alone, labels travel with
+// hues." So `label` is REQUIRED and not optional — a dot without a label is
+// colour-alone encoding, and WCAG 1.4.1 plus 1.4.11 both fail on that. Making
+// the label required closes both in one shape instead of leaving every call site
+// to remember.
+//
+// Swatch colour MUST be a --color-data-categorical-* or --color-data-<family>-N
+// var. Never a raw hex, never a --dracula-* primitive: that discipline is what
+// makes the 56 --color-data-* tokens load-bearing rather than decorative, and
+// shared/chart-hues.ts is the sanctioned categorical source.
+//
+// Not interactive. A legend is a key, not a control: no hover, no focus ring.
+
+import type {ReactNode} from 'react';
+import {HStack, StackItem, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {CHART_HUES, type ChartHue} from 'astryx-dracula/shared/chart-hues';
+
+export interface ChartLegendEntry {
+  /** REQUIRED. The hue never travels alone — this is the 1.4.1 contract. */
+  label: string;
+  /** A --color-data-* var, or a --color-background-* surface. Never a raw
+   *  hex, never a --dracula-* primitive.
+   *
+   *  The surface arm is not optional: a legend whose first row is a recessive
+   *  surface is normal (the heatmap's zero cell), so a data-only type would
+   *  reject the value the heatmap is supposed to paint. */
+  color: ChartHue | `var(--color-data-${string})` | `var(--color-background-${string})`;
+}
+
+// Kept as a string-keyed fall-through on purpose, and DO NOT narrow it: call
+// sites pass an already-RESOLVED value (CHART_HUES.x is a property access, so
+// it yields the value, never the key), so the lookup misses at every site and
+// the `?? entry.color` is the only path that paints. Narrowing the key type
+// would render `background: undefined` at every call site, compile clean, and
+// break at runtime. The old comment here claimed call sites may pass a KEY;
+// none does. The behaviour is correct; only the comment was wrong.
+const HUE_LOOKUP: Record<string, string> = CHART_HUES;
+
+export interface ChartLegendProps {
+  entries: readonly ChartLegendEntry[];
+  /** Spacing step between entries. @default 2 */
+  gap?: 1 | 2 | 3 | 4 | 6;
+  /** Accessible name for the legend as a group. */
+  label?: string;
+  /** Swatch size in px. @default 10 */
+  swatchSize?: number;
+  /** Caption under the legend, e.g. "Hourly intervals · trailing 24 hours". */
+  caption?: ReactNode;
+  /** Orientation. @default 'row' */
+  direction?: 'row' | 'column';
+}
+
+
+export function ChartLegend({
+  entries,
+  gap = 2,
+  swatchSize = 10,
+  label,
+  caption,
+  direction = 'row',
+}: ChartLegendProps) {
+  const Stack = direction === 'row' ? HStack : VStack;
+  return (
+    <VStack gap={1}>
+      <Stack gap={gap} vAlign="center" role="list" aria-label={label}>
+        {entries.map(entry => (
+          <HStack key={entry.label} gap={1} vAlign="center" role="listitem">
+            <StackItem
+              style={{
+                width: `${swatchSize}px`,
+                height: `${swatchSize}px`,
+                flexShrink: 0,
+                background: HUE_LOOKUP[entry.color] ?? entry.color,
+                borderRadius: 'var(--radius-inner)',
+              }}
+            />
+            {/* supporting, not body: a legend label is metadata by the
+                typography doctrine, and it never carries a sentence the page
+                needs the reader to have. */}
+            <Text type="supporting" color="secondary" hasTabularNumbers>
+              {entry.label}
+            </Text>
+          </HStack>
+        ))}
+      </Stack>
+      {caption}
+    </VStack>
+  );
+}

package/shared/chart-panel-style.ts

@@ -0,0 +1,13 @@
+// The one chart-panel look, shared by every hand-drawn SVG chart panel in the
+// kit (dashboard, portfolio, chart, heatmap-status, shoe-store). Split from
+// shared/revenue-chart.tsx so that file exports only components and React Fast
+// Refresh stays intact; see shared/scene-hues.ts for the same reason.
+import type {CSSProperties} from 'react';
+
+// One chart-panel look for every hand-drawn SVG chart panel in this wave's
+// templates (dashboard, portfolio, chart, heatmap-status, shoe-store). Restate
+// nowhere: theme Card variant work lands in wave 2.
+export const CHART_PANEL_STYLE: CSSProperties = {
+  backgroundColor: 'var(--color-background)',
+  border: 'var(--border-width) solid var(--color-separator)',
+};