@delacour/react-native-ui 0.1.0-alpha.4 → 0.1.0

package/src/components/kpi/kpi-footer.tsx

@@ -0,0 +1,52 @@
+import { Children, type ReactElement, type ReactNode } from "react";
+import type { CardFooterProps } from "../card";
+import { Card } from "../card";
+import { Text } from "../text";
+import { useKpiPart } from "./kpi.context";
+import { kpiVariants } from "./kpi.variants";
+
+export type KpiFooterProps = CardFooterProps;
+
+/**
+ * Wraps each run of bare strings and numbers in one muted caption. A raw string
+ * inside a `View` is a red box in React Native, and the run is joined rather
+ * than wrapped piece by piece: `last {days} days` is three children, and three
+ * `Text`s in the footer's row would sit apart by its gap.
+ */
+function wrapBareText(children: ReactNode, className: string): ReactNode[] {
+	const output: ReactNode[] = [];
+	let run: string[] = [];
+	const flush = (): void => {
+		if (run.length === 0) return;
+		output.push(
+			<Text className={className} key={`text-${output.length}`}>
+				{run.join("")}
+			</Text>
+		);
+		run = [];
+	};
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(String(child));
+		} else {
+			flush();
+			output.push(child);
+		}
+	}
+	flush();
+	return output;
+}
+
+/**
+ * The bottom strip — a comparison period, a caveat, a link.
+ *
+ * `Card.Footer`, so `variant="band"` sets it into the card on the next fill
+ * down, and it must be the last child for the same reason. Bare text becomes a
+ * muted caption at the card's scale.
+ */
+export function KpiFooter({ children, ...props }: KpiFooterProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Footer");
+	return <Card.Footer {...props}>{wrapBareText(children, kpiVariants({ size }).trendCaption())}</Card.Footer>;
+}
+KpiFooter.displayName = "DelacourUI.Kpi.Footer";

package/src/components/kpi/kpi-group.tsx

@@ -0,0 +1,70 @@
+import { Children, type ReactElement, type ReactNode, useMemo } from "react";
+import { View } from "react-native";
+import { Separator } from "../separator";
+import { Surface } from "../surface";
+import { type KpiGroupContextValue, KpiGroupProvider } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { type KpiGroupOrientation, kpiVariants } from "./kpi.variants";
+
+export type KpiGroupProps = KpiSlotProps & {
+	/** `horizontal` splits the row between the metrics; `vertical` stacks them. */
+	orientation?: KpiGroupOrientation;
+	/**
+	 * Set the metrics on one surface with a rule between them, rather than as
+	 * separate cards spaced apart. Several metrics divided by a rule read as one
+	 * panel; several spaced apart read as several panels that happen to be
+	 * adjacent.
+	 */
+	separated?: boolean;
+};
+
+/** Puts a rule between adjacent children. `Separator` is hidden from assistive technology. */
+function withRules(children: ReactNode, orientation: KpiGroupOrientation): ReactNode[] {
+	const output: ReactNode[] = [];
+	for (const [index, child] of Children.toArray(children).entries()) {
+		if (index > 0) {
+			output.push(
+				<Separator key={`rule-${index}`} orientation={orientation === "horizontal" ? "vertical" : "horizontal"} />
+			);
+		}
+		output.push(child);
+	}
+	return output;
+}
+
+/**
+ * Several metrics as one arrangement, in a row or a column.
+ *
+ * Each `Kpi` inside reads the group: in a row it takes an equal share of the
+ * width, and in a `separated` group it drops its own fill and hairline so the
+ * group's one surface holds them all, a rule between each.
+ */
+export function KpiGroup({
+	orientation = "vertical",
+	separated = false,
+	className,
+	children,
+	...props
+}: KpiGroupProps): ReactElement {
+	const context = useMemo<KpiGroupContextValue>(() => ({ orientation, separated }), [orientation, separated]);
+	const slots = kpiVariants({ orientation, separated });
+
+	if (separated) {
+		return (
+			<KpiGroupProvider value={context}>
+				<Surface className={slots.group({ className })} padding="none" {...props}>
+					{withRules(children, orientation)}
+				</Surface>
+			</KpiGroupProvider>
+		);
+	}
+
+	return (
+		<KpiGroupProvider value={context}>
+			<View className={slots.group({ className })} {...props}>
+				{children}
+			</View>
+		</KpiGroupProvider>
+	);
+}
+KpiGroup.displayName = "DelacourUI.Kpi.Group";

package/src/components/kpi/kpi-header.tsx

@@ -0,0 +1,25 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { cn } from "../../lib/cn";
+import { cardVariants } from "../card/card.variants";
+import { useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The top row: a tinted icon, the metric's name, and anything acting on it.
+ *
+ * Sits on the card header's own inset — the classes are the card's, with the
+ * row centred rather than top-aligned — so the title lines up with the number
+ * and the footer below it at every size.
+ */
+export function KpiHeader({ className, ...props }: KpiSlotProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Header");
+	return (
+		<View
+			className={cardVariants({ size }).header({ className: cn(kpiVariants({ size }).header(), className) })}
+			{...props}
+		/>
+	);
+}
+KpiHeader.displayName = "DelacourUI.Kpi.Header";

package/src/components/kpi/kpi-icon.tsx

@@ -0,0 +1,28 @@
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import { useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * A tinted square for a glyph.
+ *
+ * It takes the element rather than drawing one — a metric's icon is the app's
+ * choice — and hands an unstyled `Icon` inside it the card's series colour and
+ * a step of the icon scale sized to the square. The square is that colour at
+ * 15%, so a row of cards given five colour indexes reads as five series.
+ */
+export function KpiIcon({ className, children, ...props }: KpiSlotProps): ReactElement {
+	const { size, colorIndex } = useKpiPart("Kpi.Icon");
+	const slots = kpiVariants({ colorIndex, size });
+	const glyph = slots.iconGlyph();
+	const defaults = useMemo(() => ({ className: glyph, color: `chart-${colorIndex}` }), [glyph, colorIndex]);
+
+	return (
+		<View className={slots.icon({ className })} {...props}>
+			<IconDefaultsProvider value={defaults}>{children}</IconDefaultsProvider>
+		</View>
+	);
+}
+KpiIcon.displayName = "DelacourUI.Kpi.Icon";

package/src/components/kpi/kpi-sparkline.tsx

@@ -0,0 +1,145 @@
+import type { CurveType } from "@delacour/react-native-charts/core";
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { Chart, type ChartConfig } from "../chart";
+import { useChart } from "../chart/chart.context";
+import { useKpiLayout, useKpiPart } from "./kpi.context";
+import {
+	type KpiColorIndex,
+	type KpiSparklineData,
+	kpiSparklineAccessibilityLabel,
+	kpiVariants,
+	resolveSparklineDomain,
+	resolveSparklineFilled,
+	resolveSparklineSeries,
+} from "./kpi.variants";
+
+export type KpiSparklineProps = KpiSparklineData & {
+	/** Overrides the KPI's `colorIndex` for this chart. */
+	colorIndex?: KpiColorIndex;
+	/** A theme token or a literal, over the series colour entirely. */
+	color?: string;
+	/**
+	 * Fill under the line. Defaults on under the card and off beside the
+	 * number, where a fill would make the chart a second block competing with
+	 * the value.
+	 */
+	filled?: boolean;
+	strokeWidth?: number;
+	curve?: CurveType;
+	/**
+	 * Hold and drag to scrub a point: a dot rides the line and the KPI's
+	 * `activeIndex` follows it, so a custom part can print that point's value.
+	 * On by default. The scrub starts on a hold, so a sparkline in a scrolling
+	 * list does not steal the scroll.
+	 */
+	interactive?: boolean;
+	/** Formats the first and last point for the screen-reader summary. */
+	formatValue?: (value: number) => string;
+	/** Replaces the screen-reader summary — "Trend over 30 points, from 120 to 184". */
+	accessibilityLabel?: string;
+	className?: string;
+	testID?: string;
+};
+
+/**
+ * Reports the scrubbed index to the KPI, as `null` once the finger lifts.
+ *
+ * A child of `<Chart>` that is not a mark, so the chart mounts it beside the
+ * canvas where its context — and the scrub's shared values — are in reach. It
+ * crosses to the JS thread only when the index changes, which is a few times
+ * per drag rather than once a frame.
+ */
+function KpiSparklineScrub({ onChange }: { onChange: (index: number | null) => void }): null {
+	const { scrub } = useChart();
+
+	useAnimatedReaction(
+		() => (scrub.isActive.value ? scrub.index.value : -1),
+		(next, previous) => {
+			if (next === previous) return;
+			scheduleOnRN(onChange, next < 0 ? null : next);
+		}
+	);
+
+	return null;
+}
+KpiSparklineScrub.displayName = "DelacourUI.Kpi.Sparkline.Scrub";
+
+/**
+ * The shape the number made getting there — a `Chart` line with no grid, no
+ * axes and no padding, in the KPI's series colour.
+ *
+ * Takes a bare list of numbers, or rows with an `xKey` and a `yKey`. Under the
+ * card it is full width and filled; beside the number (`Kpi.Content
+ * layout="inline"`) it is a fixed 128pt column, unfilled, so a stack of cards
+ * lines its shapes up down the right-hand edge whatever their labels. The y
+ * bounds are the data's own, padded a tenth each way, so the peak and trough
+ * are not drawn half off the canvas.
+ *
+ * Announced as one image — how many points and where they started and ended.
+ * While the KPI loads it is a muted block of its own size.
+ */
+export function KpiSparkline(props: KpiSparklineProps): ReactElement {
+	const {
+		data,
+		xKey,
+		yKey,
+		colorIndex: colorIndexProp,
+		color,
+		filled: filledProp,
+		strokeWidth = 2,
+		curve,
+		interactive = true,
+		formatValue,
+		accessibilityLabel,
+		className,
+		testID,
+	} = props;
+	const context = useKpiPart("Kpi.Sparkline");
+	const layout = useKpiLayout();
+	const slots = kpiVariants({ layout, size: context.size });
+	const colorIndex = colorIndexProp ?? context.colorIndex;
+
+	// Keyed on the three fields the series reads rather than on the props
+	// object, which is new every render and would re-plot the chart with it.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: see above
+	const series = useMemo(() => resolveSparklineSeries(props), [data, xKey, yKey]);
+	const domain = useMemo(() => ({ y: resolveSparklineDomain(series.values) }), [series]);
+	const config = useMemo<ChartConfig>(
+		() => ({ [series.yKey]: { label: series.yKey, color: color ?? `chart-${colorIndex}` } }),
+		[series.yKey, color, colorIndex]
+	);
+
+	if (context.isLoading) {
+		return <View className={slots.sparklinePlaceholder({ className: slots.sparkline({ className }) })} />;
+	}
+
+	const filled = resolveSparklineFilled({ filled: filledProp, layout });
+
+	return (
+		<View
+			accessibilityLabel={accessibilityLabel ?? kpiSparklineAccessibilityLabel(series.values, formatValue)}
+			accessibilityRole="image"
+			accessible
+			className={slots.sparkline({ className })}
+		>
+			<Chart
+				config={config}
+				curve={curve}
+				data={series.rows}
+				domain={domain}
+				frameClassName={slots.sparklineFrame()}
+				testID={testID}
+				xKey={series.xKey}
+			>
+				{filled ? <Chart.Area yKey={series.yKey} /> : null}
+				<Chart.Line strokeWidth={strokeWidth} yKey={series.yKey} />
+				{interactive ? <Chart.Tooltip.Dot yKey={series.yKey} /> : null}
+				{interactive ? <KpiSparklineScrub onChange={context.setActiveIndex} /> : null}
+			</Chart>
+		</View>
+	);
+}
+KpiSparkline.displayName = "DelacourUI.Kpi.Sparkline";

package/src/components/kpi/kpi-stat.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useKpiLayout, useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The value and its change, stacked tight.
+ *
+ * Its own container rather than loose children of the content, because the
+ * number and its change are one fact in two lines and the card's spacing is
+ * for the gaps *between* facts. Beside an `inline` sparkline it takes the
+ * row's width, leaving the chart its column on the end.
+ */
+export function KpiStat({ className, ...props }: KpiSlotProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Stat");
+	const layout = useKpiLayout();
+	return <View className={kpiVariants({ layout, size }).stat({ className })} {...props} />;
+}
+KpiStat.displayName = "DelacourUI.Kpi.Stat";

package/src/components/kpi/kpi-title.tsx

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useKpiPart } from "./kpi.context";
+import type { KpiTextProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The metric's name. Quiet on purpose — `muted-foreground`, a step down the
+ * type scale — because the value is the thing being read.
+ *
+ * It never grows to fill its row: in a column that would absorb the spare
+ * height and land a row of cards' numbers at different heights. The header
+ * pushes its action to the end instead.
+ */
+export function KpiTitle({ className, ...props }: KpiTextProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Title");
+	return <Text className={kpiVariants({ size }).title({ className })} numberOfLines={1} {...props} />;
+}
+KpiTitle.displayName = "DelacourUI.Kpi.Title";

package/src/components/kpi/kpi-trend.tsx

@@ -0,0 +1,105 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { IconArrowDownRight, IconArrowRight, IconArrowUpRight } from "../../icons/central";
+import { Badge } from "../badge";
+import { Icon, type IconComponent } from "../icon";
+import { Text } from "../text";
+import { useKpiPart } from "./kpi.context";
+import {
+	formatKpiTrend,
+	KPI_TONE_BADGE_COLOR,
+	type KpiDirection,
+	type KpiGoodDirection,
+	type KpiSize,
+	type KpiTrendVariant,
+	kpiTrendAccessibilityLabel,
+	kpiVariants,
+	resolveKpiTrend,
+} from "./kpi.variants";
+
+export type KpiTrendProps = Omit<ViewProps, "children"> & {
+	/**
+	 * How much it moved, as a percentage. The sign carries the direction, so
+	 * `-4.2` is a fall of 4.2%; there is no direction prop to keep in step.
+	 */
+	value: number;
+	/** Writes the number yourself. Receives the raw value, sign and all. */
+	format?: (value: number) => string;
+	/** Overrides the KPI's own `goodDirection` for this one figure. */
+	goodDirection?: KpiGoodDirection;
+	/**
+	 * `text` is a line of colour under the number — what a stat card usually
+	 * wants. `badge` puts a pill round it with an arrow, for a card busy enough
+	 * that a bare line of colour is lost in it.
+	 */
+	variant?: KpiTrendVariant;
+	/** What it is compared against — "vs last month", "last 30d". Read after the change. */
+	caption?: string;
+	/** A movement no larger than this counts as none. Defaults to `0`. */
+	threshold?: number;
+	className?: string;
+	/** Anything after the caption, when a string is not enough. */
+	children?: ReactNode;
+};
+
+const ARROW: Record<KpiDirection, IconComponent> = {
+	up: IconArrowUpRight,
+	down: IconArrowDownRight,
+	flat: IconArrowRight,
+};
+
+const BADGE_SIZE: Record<KpiSize, "sm" | "md"> = { sm: "sm", md: "sm", lg: "md" };
+
+/**
+ * The change: a signed percentage, coloured by what it means.
+ *
+ * It derives its own direction from the sign and its own tone from the KPI's
+ * `goodDirection`, so a fall in churn is drawn as good news without the call
+ * site naming a colour. The arrow on a badge says the direction again in a
+ * shape, so the meaning never rests on colour alone.
+ *
+ * Announced as one string — "Up 7.8 percent, vs last month" — rather than a
+ * number, an arrow and a caption read as three stops. While the KPI loads it
+ * is a short muted bar.
+ */
+export function KpiTrend({
+	value,
+	format,
+	goodDirection: goodDirectionProp,
+	variant = "text",
+	caption,
+	threshold,
+	className,
+	children,
+	...props
+}: KpiTrendProps): ReactElement {
+	const context = useKpiPart("Kpi.Trend");
+	const { size, isLoading } = context;
+	const goodDirection = goodDirectionProp ?? context.goodDirection;
+	const { direction, tone } = resolveKpiTrend({ goodDirection, threshold, value });
+	const slots = kpiVariants({ size, tone });
+
+	if (isLoading) {
+		return <View className={slots.trendPlaceholder()} />;
+	}
+
+	const formatted = format?.(value);
+	const text = formatted ?? formatKpiTrend(value);
+	const accessibilityLabel = kpiTrendAccessibilityLabel({ caption, direction, formatted, value });
+
+	return (
+		<View accessibilityLabel={accessibilityLabel} accessible className={slots.trend({ className })} {...props}>
+			{variant === "badge" ? (
+				<Badge color={KPI_TONE_BADGE_COLOR[tone]} size={BADGE_SIZE[size]} variant="soft">
+					<Icon icon={ARROW[direction]} />
+					<Badge.Label>{text}</Badge.Label>
+				</Badge>
+			) : (
+				<Text className={slots.trendText()}>{text}</Text>
+			)}
+			{caption === undefined ? null : <Text className={slots.trendCaption()}>{caption}</Text>}
+			{children}
+		</View>
+	);
+}
+KpiTrend.displayName = "DelacourUI.Kpi.Trend";

package/src/components/kpi/kpi-value.tsx

@@ -0,0 +1,32 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardContext } from "../card/card.context";
+import { Text } from "../text";
+import { useKpiPart } from "./kpi.context";
+import type { KpiTextProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The number.
+ *
+ * Formatted by the caller, not here — separators, currency and units are
+ * locale decisions a component would get wrong in a way that is hard to
+ * notice and impossible to override. It takes the foreground token of the
+ * plane the card landed on, like `Card.Title`, and one line: a number that
+ * wraps is no longer read as one.
+ *
+ * While the KPI is loading it is a muted block the height of the number's
+ * line, announced as loading, so the card does not jump when the data lands.
+ */
+export function KpiValue({ className, ...props }: KpiTextProps): ReactElement {
+	const { size, isLoading } = useKpiPart("Kpi.Value");
+	const plane = useCardContext()?.plane ?? null;
+	const slots = kpiVariants({ plane: plane ?? "none", size });
+
+	if (isLoading) {
+		return <View accessibilityLabel="Loading" accessible className={slots.valuePlaceholder()} />;
+	}
+
+	return <Text adjustsFontSizeToFit className={slots.value({ className })} numberOfLines={1} {...props} />;
+}
+KpiValue.displayName = "DelacourUI.Kpi.Value";

package/src/components/kpi/kpi.context.tsx

@@ -0,0 +1,111 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { KpiColorIndex, KpiGoodDirection, KpiGroupOrientation, KpiLayout, KpiSize } from "./kpi.variants";
+
+export type KpiContextValue = {
+	/** The card's size — the inset, the value's scale and the sparkline's height. */
+	size: KpiSize;
+	/** Which `--chart-*` token the sparkline and the icon take. */
+	colorIndex: KpiColorIndex;
+	/** Which way is the good news, for every trend inside that does not override it. */
+	goodDirection: KpiGoodDirection;
+	/** Whether the numbers are still on their way. The value, trend and sparkline hold placeholders. */
+	isLoading: boolean;
+	/**
+	 * The sparkline point being scrubbed, or `null` when nothing is. A custom
+	 * part reads it to print that point's value in place of the latest one.
+	 */
+	activeIndex: number | null;
+	/** Moves the scrubbed point. The sparkline calls it; a caller holding the state may too. */
+	setActiveIndex: (index: number | null) => void;
+};
+
+const KpiContext = createContext<KpiContextValue | null>(null);
+
+/**
+ * Supplies the enclosing KPI's size, colour, direction and scrub to its subtree.
+ *
+ * Lives in its own module, importing nothing but types, so a part the KPI
+ * renders can read it without importing `./kpi` and closing a cycle through
+ * `kpi.tsx`. See AGENTS.md rule 3.
+ */
+export function KpiProvider({ value, children }: { value: KpiContextValue; children: ReactNode }): ReactElement {
+	return <KpiContext value={value}>{children}</KpiContext>;
+}
+KpiProvider.displayName = "DelacourUI.Kpi.Provider";
+
+/** The enclosing KPI's context, or null outside a `<Kpi>`. */
+export function useKpiContext(): KpiContextValue | null {
+	return use(KpiContext);
+}
+
+/**
+ * Reads the enclosing KPI's size, colour, direction, loading state and scrub.
+ *
+ * What a custom part uses to print the scrubbed point's value, match the
+ * card's series colour, or hold a placeholder while it loads. Throws outside a
+ * `<Kpi>`; use {@link useKpiContext} where the enclosing KPI is optional.
+ */
+export function useKpi(): KpiContextValue {
+	const context = useKpiContext();
+	if (!context) {
+		throw new Error("useKpi must be called inside a <Kpi>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing KPI's context, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useKpi}, whose error message names the hook rather than
+ * a part.
+ */
+export function useKpiPart(component: string): KpiContextValue {
+	const context = useKpiContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Kpi>.`);
+	}
+	return context;
+}
+
+const KpiLayoutContext = createContext<KpiLayout>("below");
+
+/**
+ * Supplies `Kpi.Content`'s layout to the stat and the sparkline inside it —
+ * the stat takes the row's width and the sparkline a fixed column when it is
+ * `inline`.
+ */
+export function KpiLayoutProvider({ value, children }: { value: KpiLayout; children: ReactNode }): ReactElement {
+	return <KpiLayoutContext value={value}>{children}</KpiLayoutContext>;
+}
+KpiLayoutProvider.displayName = "DelacourUI.Kpi.Content.Provider";
+
+/** The enclosing `Kpi.Content`'s layout — `below` outside one. */
+export function useKpiLayout(): KpiLayout {
+	return use(KpiLayoutContext);
+}
+
+export type KpiGroupContextValue = {
+	orientation: KpiGroupOrientation;
+	/** Whether the metrics share one surface with a rule between them. */
+	separated: boolean;
+};
+
+const KpiGroupContext = createContext<KpiGroupContextValue | null>(null);
+
+/** Supplies a `Kpi.Group`'s arrangement to the metrics inside it. */
+export function KpiGroupProvider({
+	value,
+	children,
+}: {
+	value: KpiGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <KpiGroupContext value={value}>{children}</KpiGroupContext>;
+}
+KpiGroupProvider.displayName = "DelacourUI.Kpi.Group.Provider";
+
+/** The enclosing `Kpi.Group`, or null outside one. */
+export function useKpiGroupContext(): KpiGroupContextValue | null {
+	return use(KpiGroupContext);
+}