astryx-dracula 0.5.0 → 0.6.2

package/shared/chaptered-doc.tsx

@@ -5,327 +5,305 @@
 // Scene systems stay local too: product-tour keeps BAT_WING/BAT_BODY/FIR +
 // NightScene/PaletteScene/TypeScene/PagesScene, tech-report keeps its own.
 
+import { AppShell } from "@astryxdesign/core/AppShell";
+import { AspectRatio } from "@astryxdesign/core/AspectRatio";
+import { Button } from "@astryxdesign/core/Button";
+import { CodeBlock } from "@astryxdesign/core/CodeBlock";
+import { Divider } from "@astryxdesign/core/Divider";
+import { useMediaQuery } from "@astryxdesign/core/hooks";
+import { Icon } from "@astryxdesign/core/Icon";
 import {
-  buildOutlineByChapter,
-  outlinePanel,
-  sceneClip,
-  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';
+	HStack,
+	Layout,
+	LayoutContent,
+	LayoutPanel,
+	StackItem,
+	VStack,
+} from "@astryxdesign/core/Layout";
+import { List, ListItem } from "@astryxdesign/core/List";
+import { MobileNavToggle } from "@astryxdesign/core/MobileNav";
+import { NavIcon } from "@astryxdesign/core/NavIcon";
+import { Outline } from "@astryxdesign/core/Outline";
+import { Selector } from "@astryxdesign/core/Selector";
+import { SideNav, SideNavHeading, SideNavItem, SideNavSection } from "@astryxdesign/core/SideNav";
+import { Heading, Text } from "@astryxdesign/core/Text";
 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';
+	buildOutlineByChapter,
+	type ChapterGroup,
+	type DocChapter,
+	type DocSection,
+	outlinePanel,
+	sceneClip,
+	scrollToSection,
+	sectionId,
+} from "astryx-dracula/shared/chaptered-doc-config";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { type ReactNode, useState } from "react";
 
 function ChapterRail({
-  groups,
-  activeId,
-  onSelect,
-  heading,
-  subheading,
-  headingHref,
-  headingIcon,
+	groups,
+	activeId,
+	onSelect,
+	heading,
+	subheading,
+	headingHref,
+	headingIcon,
 }: {
-  groups: ChapterGroup[];
-  activeId: string;
-  onSelect: (id: string) => void;
-  heading: string;
-  subheading: string;
-  headingHref: string;
-  headingIcon: ReactNode;
+	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>
-  );
+	// 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 ────────────────────────────────────────────────────────────
 
-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>
-  );
+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>
+	);
 }
 
 function ChapterNav({
-  chapters,
-  chapter,
-  onSelect,
+	chapters,
+	chapter,
+	onSelect,
 }: {
-  chapters: DocChapter[];
-  chapter: DocChapter;
-  onSelect: (id: string) => void;
+	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>
-  );
+	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 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,
+	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;
+	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 ?? '',
-  );
+	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)');
+	// 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 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});
-  };
+	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>
+	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>
+							<Text type="large" color="secondary" display="block">
+								{chapter.intro}
+							</Text>
 
-              {art(chapter.id)}
+							{art(chapter.id)}
 
-              <VStack gap={8}>
-                {chapter.sections.map(section => (
-                  <SectionBlock
-                    key={section.key}
-                    chapterId={chapter.id}
-                    section={section}
-                  />
-                ))}
-              </VStack>
+							<VStack gap={8}>
+								{chapter.sections.map((section) => (
+									<SectionBlock key={section.key} chapterId={chapter.id} section={section} />
+								))}
+							</VStack>
 
-              <Divider />
+							<Divider />
 
-              <ChapterNav
-                chapters={chapters}
-                chapter={chapter}
-                onSelect={openChapter}
-              />
+							<ChapterNav chapters={chapters} chapter={chapter} onSelect={openChapter} />
 
-              {footer}
-            </VStack>
-          </LayoutContent>
-        }
-      />
-    </AppShell>
-  );
+							{footer}
+						</VStack>
+					</LayoutContent>
+				}
+			/>
+		</AppShell>
+	);
 }

package/shared/chart-hues.ts

@@ -5,18 +5,33 @@
 // 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.
+//
+// Every var() carries an explicit fallback equal to the theme's own pin for
+// that token. Core moved the canonical `--color-data-*` defaults out of the
+// generated theme CSS and into its own dataVars group, so a bare
+// `var(--color-data-*)` is no longer guaranteed to resolve: the theme's pin is
+// the only thing painting it. The fallback is the same value, so a theme that
+// drops the token still paints the right colour instead of nothing. The
+// fallback-vs-pin sync is enforced by scripts/check.ts, so the two cannot drift.
 
 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)',
+	cyan: "var(--color-data-categorical-cyan, #8BE9FD)",
+	orange: "var(--color-data-categorical-orange, #FFB86C)",
+	green: "var(--color-data-categorical-green, #50FA7B)",
+	pink: "var(--color-data-categorical-pink, #FF79C6)",
+	muted: "var(--color-data-categorical-blue, #6272A4)",
+	// 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, #FF5555)",
 } as const;
 
 export type ChartHue = (typeof CHART_HUES)[keyof typeof CHART_HUES];
+
+/**
+ * Any `--color-data-*` colour: a categorical hue, or a step of a sequential
+ * ramp. The fallback inside the var() is part of the string, which is why the
+ * template-literal type below still admits it.
+ */
+export type DataColor = `var(--color-data-${string})`;