astryx-dracula 0.4.0 → 0.5.1

package/shared/chart-labels.tsx

@@ -3,42 +3,43 @@
 // (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';
+import type { ReactNode } from "react";
 
-export const CHART_LABEL_FILL = 'var(--color-text-paragraph)';
+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;
+	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,
+	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>
-  );
+	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

@@ -21,21 +21,21 @@
 //
 // 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';
+import { HStack, StackItem, VStack } from "@astryxdesign/core/Stack";
+import { Text } from "@astryxdesign/core/Text";
+import type { ChartHue } from "astryx-dracula/shared/chart-hues";
+import type { ReactNode } from "react";
 
 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})`;
+	/** 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
@@ -45,56 +45,54 @@ export interface ChartLegendEntry {
 // 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';
+	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',
+	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
+	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: 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>
-  );
+						<Text type="supporting" color="secondary" hasTabularNumbers>
+							{entry.label}
+						</Text>
+					</HStack>
+				))}
+			</Stack>
+			{caption}
+		</VStack>
+	);
 }

package/shared/chart-panel-style.ts

@@ -2,12 +2,12 @@
 // 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';
+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)',
+	backgroundColor: "var(--color-background)",
+	border: "var(--border-width) solid var(--color-separator)",
 };

package/shared/data-bar.tsx

@@ -36,125 +36,120 @@
 // Not interactive. A data bar is not a control, so it carries no hover channel
 // and no focus ring; the inset-ring decision belongs to interactive surfaces.
 
-import type {CSSProperties} from 'react';
-import {HStack, StackItem, VStack} from '@astryxdesign/core/Stack';
-import {Text} from '@astryxdesign/core/Text';
-import type {ChartHue} from './chart-hues';
+import { HStack, StackItem, VStack } from "@astryxdesign/core/Stack";
+import { Text } from "@astryxdesign/core/Text";
+import type { CSSProperties } from "react";
+import type { ChartHue } from "./chart-hues";
 
 export interface DataBarSegment {
-  /** Stable key for the segment. */
-  id: string;
-  value: number;
-  /** MUST be a --color-data-categorical-* or --color-data-<family>-N var.
-   *  Never a raw hex, never a --dracula-* primitive. Typed rather than
-   *  documented: `string` made the rule a comment nobody could break. */
-  color: ChartHue | `var(--color-data-${string})`;
+	/** Stable key for the segment. */
+	id: string;
+	value: number;
+	/** MUST be a --color-data-categorical-* or --color-data-<family>-N var.
+	 *  Never a raw hex, never a --dracula-* primitive. Typed rather than
+	 *  documented: `string` made the rule a comment nobody could break. */
+	color: ChartHue | `var(--color-data-${string})`;
 }
 
 /** Minimum segment share, so a tiny non-zero value stays visible. */
 const MIN_SEGMENT_PCT = 2;
 
 export interface DataBarProps {
-  /** Accessible name. Required — a bar with no name is an unlabelled graphic. */
-  label: string;
-  segments: readonly DataBarSegment[];
-  /** Bar thickness in px. @default 12 */
-  height?: number;
-  /** Show the summed value under the bar. @default false */
-  hasValueLabel?: boolean;
-  /** Formats the summed value. @default toLocaleString() */
-  formatValue?: (total: number) => string;
-  /** Gap between segments as a spacing-scale step. @default 0 */
-  gap?: 0 | 0.5 | 1 | 1.5 | 2 | 3;
-  /** Neutral fill shown when every segment is zero. Deliberately
-   *  --color-progress-value, NOT a text token — see the header. */
-  trackColor?: string;
+	/** Accessible name. Required — a bar with no name is an unlabelled graphic. */
+	label: string;
+	segments: readonly DataBarSegment[];
+	/** Bar thickness in px. @default 12 */
+	height?: number;
+	/** Show the summed value under the bar. @default false */
+	hasValueLabel?: boolean;
+	/** Formats the summed value. @default toLocaleString() */
+	formatValue?: (total: number) => string;
+	/** Gap between segments as a spacing-scale step. @default 0 */
+	gap?: 0 | 0.5 | 1 | 1.5 | 2 | 3;
 }
 
 const segmentStyle: CSSProperties = {
-  borderRadius: 'var(--radius-inner)',
+	borderRadius: "var(--radius-inner)",
 };
 
 export function DataBar({
-  label,
-  segments,
-  height = 12,
-  hasValueLabel = false,
-  formatValue = total => total.toLocaleString(),
-  gap = 0,
-  trackColor = 'var(--color-progress-value)',
+	label,
+	segments,
+	height = 12,
+	hasValueLabel = false,
+	formatValue = (total) => total.toLocaleString(),
+	gap = 0,
 }: DataBarProps) {
-  // Negative values are not a magnitude and are clamped out before the ratio is
-  // taken: summing a negative into `total` inflates every other segment's
-  // share and can push the bar past 100%. An empty or all-zero bar falls
-  // through to the track fill below.
-  const total = segments.reduce(
-    (sum, segment) => sum + Math.max(0, segment.value),
-    0,
-  );
-  const visible = segments
-    .map(segment => {
-      if (segment.value <= 0) return null;
-      return {
-        id: segment.id,
-        color: segment.color,
-        share: (segment.value / total) * 100,
-      };
-    })
-    .filter((segment): segment is NonNullable<typeof segment> => segment !== null);
+	// Negative values are not a magnitude and are clamped out before the ratio is
+	// taken: summing a negative into `total` inflates every other segment's
+	// share and can push the bar past 100%. An empty or all-zero bar falls
+	// through to the track fill below.
+	const total = segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);
+	const visible = segments
+		.map((segment) => {
+			if (segment.value <= 0) return null;
+			return {
+				id: segment.id,
+				color: segment.color,
+				share: (segment.value / total) * 100,
+			};
+		})
+		.filter((segment): segment is NonNullable<typeof segment> => segment !== null);
 
-  // A tiny non-zero value must stay visible, so each segment gets a floor —
-  // but the floors are taken OUT of the segments that can afford it. Flooring
-  // every segment independently overflows the bar (3 tiny + 1 huge measured
-  // 106%), and a bar wider than its track is worse than a missing speck.
-  const floorTotal = visible.length * MIN_SEGMENT_PCT;
-  const surplus = Math.max(0, 100 - floorTotal);
-  const slack = Math.max(
-    0,
-    visible.reduce(
-      (sum, segment) => sum + Math.max(0, segment.share - MIN_SEGMENT_PCT),
-      0,
-    ),
-  );
-  const widths = visible.map(segment => {
-    const room = Math.max(0, segment.share - MIN_SEGMENT_PCT);
-    const claim = slack > 0 ? (room / slack) * surplus : 0;
-    return Math.min(100, MIN_SEGMENT_PCT + claim);
-  });
-  const drawn = visible
-    .map((segment, index) => ({...segment, width: widths[index]}))
-    .filter(segment => segment.width > 0);
+	// A tiny non-zero value must stay visible, so each segment gets a floor —
+	// but the floors are taken OUT of the segments that can afford it. Flooring
+	// every segment independently overflows the bar (3 tiny + 1 huge measured
+	// 106%), and a bar wider than its track is worse than a missing speck.
+	const floorTotal = visible.length * MIN_SEGMENT_PCT;
+	const surplus = Math.max(0, 100 - floorTotal);
+	const slack = Math.max(
+		0,
+		visible.reduce((sum, segment) => sum + Math.max(0, segment.share - MIN_SEGMENT_PCT), 0),
+	);
+	const widths = visible.map((segment) => {
+		const room = Math.max(0, segment.share - MIN_SEGMENT_PCT);
+		const claim = slack > 0 ? (room / slack) * surplus : 0;
+		return Math.min(100, MIN_SEGMENT_PCT + claim);
+	});
+	const drawn = visible
+		.map((segment, index) => ({ ...segment, width: widths[index] }))
+		.filter((segment) => segment.width > 0);
 
-  const bar = (
-    <HStack
-      gap={gap}
-      height={height}
-      width="100%"
-      vAlign="stretch"
-      role="img"
-      aria-label={label}
-      style={
-        total > 0
-          ? undefined
-          : {background: trackColor, borderRadius: 'var(--radius-inner)'}
-      }>
-      {drawn.map(segment => (
-        <StackItem
-          key={segment.id}
-          style={{...segmentStyle, flexBasis: `${segment.width}%`, background: segment.color}}
-        />
-      ))}
-    </HStack>
-  );
+	const bar = (
+		<HStack
+			gap={gap}
+			height={height}
+			width="100%"
+			vAlign="stretch"
+			role="img"
+			aria-label={label}
+			style={
+				total > 0
+					? undefined
+					: {
+							// Deliberately --color-progress-value, NOT a text token — see the header.
+							background: "var(--color-progress-value)",
+							borderRadius: "var(--radius-inner)",
+						}
+			}
+		>
+			{drawn.map((segment) => (
+				<StackItem
+					key={segment.id}
+					style={{ ...segmentStyle, flexBasis: `${segment.width}%`, background: segment.color }}
+				/>
+			))}
+		</HStack>
+	);
 
-  if (!hasValueLabel) return bar;
+	if (!hasValueLabel) return bar;
 
-  return (
-    <VStack gap={1}>
-      {bar}
-      <Text type="supporting" color="secondary" hasTabularNumbers>
-        {formatValue(total)}
-      </Text>
-    </VStack>
-  );
+	return (
+		<VStack gap={1}>
+			{bar}
+			<Text type="supporting" color="secondary" hasTabularNumbers>
+				{formatValue(total)}
+			</Text>
+		</VStack>
+	);
 }

package/shared/format-money.ts

@@ -0,0 +1,3 @@
+export function formatMoney(n: number): string {
+	return `$${n.toFixed(2)}`;
+}

package/shared/gallery-image.ts

@@ -3,18 +3,18 @@
 // primitive, so gallery SVG scenes fill their box and clip to rounded corners
 // through these two styles. Replace with component props once #2582 lands.
 
-import type {CSSProperties} from 'react';
+import type { CSSProperties } from "react";
 
 // Fills the AspectRatio box. No objectFit prop on AspectRatio (#2582).
 export const galleryImage: CSSProperties = {
-  width: '100%',
-  height: '100%',
-  display: 'block',
+	width: "100%",
+	height: "100%",
+	display: "block",
 };
 
 // Rounds the gallery corners (element radius; chapter art uses container — see
 // shared/chaptered-doc sceneClip). No radius prop on AspectRatio (#2582);
 export const galleryImageClip: CSSProperties = {
-  borderRadius: 'var(--radius-element)',
-  overflow: 'clip',
+	borderRadius: "var(--radius-element)",
+	overflow: "clip",
 };

package/shared/login-demo.ts

@@ -3,5 +3,5 @@
 // Promise.withResolvers — the ES2022 target breaks strict consumers), awaited
 // inside each template's own startTransition.
 export function demoLogin(): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, 2000));
+	return new Promise((resolve) => setTimeout(resolve, 2000));
 }

package/shared/metric-card.tsx

@@ -0,0 +1,123 @@
+// Shared dashboard cards: the KPI tile (MetricCard), the linked table panel
+// (TableCard), and the two table-cell renderers the engagement tables share
+// (BarCell = magnitude bar + formatted count, CountCell = plain tabular
+// count). One home so the analytics and portfolio templates can't drift into
+// a second KPI/table vocabulary.
+
+import { Card } from "@astryxdesign/core/Card";
+import { Link } from "@astryxdesign/core/Link";
+import { ProgressBar } from "@astryxdesign/core/ProgressBar";
+import { HStack, VStack } from "@astryxdesign/core/Stack";
+import type { TableColumn } from "@astryxdesign/core/Table";
+import { Table } from "@astryxdesign/core/Table";
+import { Heading, Text } from "@astryxdesign/core/Text";
+import { MetricDelta } from "astryx-dracula/shared/metric-delta";
+import { Sparkline, type SparkPoint } from "astryx-dracula/shared/sparkline";
+import type { ReactNode } from "react";
+
+export function MetricCard({
+	label,
+	value,
+	change,
+	positive,
+	caption = "Last 30 days vs. Previous",
+	sparkline,
+}: {
+	label: string;
+	value: string;
+	change: string;
+	/** Defaults to "no leading minus means positive". */
+	positive?: boolean;
+	caption?: string;
+	/** Rendered as a thirty-day trend sparkline when provided. */
+	sparkline?: SparkPoint[];
+}) {
+	const isPositive = positive ?? !change.startsWith("-");
+	return (
+		<Card>
+			<VStack gap={2}>
+				<Text type="supporting" color="secondary">
+					{label}
+				</Text>
+				<HStack gap={2} vAlign="center">
+					<Text type="display-3" weight="semibold" hasTabularNumbers>
+						{value}
+					</Text>
+					<MetricDelta value={change} positive={isPositive} />
+				</HStack>
+				<Text type="supporting" color="secondary">
+					{caption}
+				</Text>
+				{sparkline && (
+					<Sparkline data={sparkline} label={`${label} thirty-day trend`} positive={isPositive} />
+				)}
+			</VStack>
+		</Card>
+	);
+}
+
+export function TableCard<T extends { id: string }>({
+	title,
+	linkLabel,
+	linkHref,
+	data,
+	columns,
+}: {
+	title: string;
+	/** Omit both for a linkless panel (e.g. portfolio trending stocks). */
+	linkLabel?: string;
+	linkHref?: string;
+	data: T[];
+	columns: TableColumn<T>[];
+}) {
+	return (
+		<Card>
+			<VStack gap={6}>
+				<HStack hAlign="between" vAlign="center">
+					<Heading level={3}>{title}</Heading>
+					{linkLabel && linkHref && <Link href={linkHref}>{linkLabel}</Link>}
+				</HStack>
+				<Table<T>
+					data={data}
+					columns={columns}
+					idKey="id"
+					density="compact"
+					dividers="rows"
+					textOverflow="truncate"
+					hasHover
+				/>
+			</VStack>
+		</Card>
+	);
+}
+
+export function BarCell({
+	label,
+	value,
+	max,
+	children,
+}: {
+	/** Accessible bar label, e.g. "/home views". */
+	label: string;
+	value: number;
+	max: number;
+	/** Formatted count rendered under the bar. */
+	children: ReactNode;
+}) {
+	return (
+		<VStack gap={1}>
+			<ProgressBar value={value} max={max} label={label} isLabelHidden />
+			<Text type="body" hasTabularNumbers maxLines={1}>
+				{children}
+			</Text>
+		</VStack>
+	);
+}
+
+export function CountCell({ children }: { children: ReactNode }) {
+	return (
+		<Text hasTabularNumbers maxLines={1}>
+			{children}
+		</Text>
+	);
+}