@siyahi/ui 0.1.9-next.24 → 0.1.9-next.25

package/agents/manifest.json

@@ -64,6 +64,29 @@
       "guidance": "a series with `color` and `negativeColor`",
       "components": []
     },
+    {
+      "need": "A total built up or bridged step by step, such as a year's profit month by month or revenue from last year to this by store",
+      "guidance": "`WaterfallChartCard`; `horizontal` for long names",
+      "components": [
+        "WaterfallChartCard"
+      ]
+    },
+    {
+      "need": "Signed changes by two categories, such as returns or profit by month and year, or by store and quarter",
+      "guidance": "`ChangeGrid` in a `Card`, with each row's `total` worked out by the page",
+      "components": [
+        "ChangeGrid",
+        "Card"
+      ]
+    },
+    {
+      "need": "Each item's value at two points or against a benchmark, such as share of sales last year and this, or our mix against the market's",
+      "guidance": "`SlopeChart` in a `Card`, with the few lines that matter `highlighted`",
+      "components": [
+        "SlopeChart",
+        "Card"
+      ]
+    },
     {
       "need": "Ranked counts or amounts by category (a name, a bar and a figure)",
       "guidance": "`BarList`; give two lists one `max` to share a scale",
@@ -131,6 +154,20 @@
         "RangePosition"
       ]
     },
+    {
+      "need": "How far a level fell below its highest so far, over time, such as a fund's or a cash balance's drawdown",
+      "guidance": "`DrawdownChartCard` with the levels in `levelKey`",
+      "components": [
+        "DrawdownChartCard"
+      ]
+    },
+    {
+      "need": "How many values fall in each range, such as response times or each trade's return, with the median or p95 marked",
+      "guidance": "`HistogramChartCard` with the raw `values` and `marks`",
+      "components": [
+        "HistogramChartCard"
+      ]
+    },
     {
       "need": "A long daily series, such as a price or an order value",
       "guidance": "`PriceChart`",
@@ -145,6 +182,27 @@
         "Treemap"
       ]
     },
+    {
+      "need": "How two measures relate across many items, such as stores' size against growth",
+      "guidance": "`ScatterChartCard`",
+      "components": [
+        "ScatterChartCard"
+      ]
+    },
+    {
+      "need": "Items sorted into four groups by two signed changes, weighted by size, such as products by price change and sales change, sized by revenue",
+      "guidance": "`ScatterChartCard` with `quadrants` and each point's `size`",
+      "components": [
+        "ScatterChartCard"
+      ]
+    },
+    {
+      "need": "A gain or loss for every day, such as daily profit or a portfolio's daily change",
+      "guidance": "`CalendarHeatmap` with `signed`",
+      "components": [
+        "CalendarHeatmap"
+      ]
+    },
     {
       "need": "Activity by day, by weekday and hour, or a status over time",
       "guidance": "`CalendarHeatmap`, `WeekdayHeatmap`, `StatusHeatmap`",
@@ -442,6 +500,28 @@
         "useFormat"
       ]
     },
+    {
+      "file": "agents/examples/change-grid-money.tsx",
+      "components": [
+        "Card",
+        "CardContent",
+        "CardDescription",
+        "CardHeader",
+        "CardTitle",
+        "ChangeGrid"
+      ]
+    },
+    {
+      "file": "agents/examples/change-grid.tsx",
+      "components": [
+        "Card",
+        "CardContent",
+        "CardDescription",
+        "CardHeader",
+        "CardTitle",
+        "ChangeGrid"
+      ]
+    },
     {
       "file": "agents/examples/chart-area.tsx",
       "components": [
@@ -704,6 +784,13 @@
         "DistributionBar"
       ]
     },
+    {
+      "file": "agents/examples/drawdown-chart.tsx",
+      "components": [
+        "DrawdownChartCard",
+        "useFormat"
+      ]
+    },
     {
       "file": "agents/examples/dropdown-menu.tsx",
       "components": [
@@ -730,6 +817,22 @@
         "useFormat"
       ]
     },
+    {
+      "file": "agents/examples/heatmap-calendar-signed.tsx",
+      "components": [
+        "CalendarHeatmap",
+        "CalendarHeatmapBlock",
+        "CalendarHeatmapBody",
+        "CalendarHeatmapFooter",
+        "CalendarHeatmapLegend",
+        "Card",
+        "CardContent",
+        "CardDescription",
+        "CardHeader",
+        "CardTitle",
+        "useFormat"
+      ]
+    },
     {
       "file": "agents/examples/heatmap-calendar.tsx",
       "components": [
@@ -776,6 +879,13 @@
         "WeekdayHeatmapLegend"
       ]
     },
+    {
+      "file": "agents/examples/histogram-chart.tsx",
+      "components": [
+        "HistogramChartCard",
+        "useFormat"
+      ]
+    },
     {
       "file": "agents/examples/input-states.tsx",
       "components": [
@@ -905,6 +1015,20 @@
         "useFormat"
       ]
     },
+    {
+      "file": "agents/examples/scatter-chart-quadrants.tsx",
+      "components": [
+        "ScatterChartCard",
+        "useFormat"
+      ]
+    },
+    {
+      "file": "agents/examples/scatter-chart.tsx",
+      "components": [
+        "ScatterChartCard",
+        "useFormat"
+      ]
+    },
     {
       "file": "agents/examples/scroll-area.tsx",
       "components": [
@@ -979,6 +1103,28 @@
         "Slider"
       ]
     },
+    {
+      "file": "agents/examples/slope-chart-market.tsx",
+      "components": [
+        "Card",
+        "CardContent",
+        "CardDescription",
+        "CardHeader",
+        "CardTitle",
+        "SlopeChart"
+      ]
+    },
+    {
+      "file": "agents/examples/slope-chart.tsx",
+      "components": [
+        "Card",
+        "CardContent",
+        "CardDescription",
+        "CardHeader",
+        "CardTitle",
+        "SlopeChart"
+      ]
+    },
     {
       "file": "agents/examples/surfaces.tsx",
       "components": [
@@ -1076,6 +1222,20 @@
         "TreemapLegend",
         "useFormat"
       ]
+    },
+    {
+      "file": "agents/examples/waterfall-chart-stores.tsx",
+      "components": [
+        "WaterfallChartCard",
+        "useFormat"
+      ]
+    },
+    {
+      "file": "agents/examples/waterfall-chart.tsx",
+      "components": [
+        "WaterfallChartCard",
+        "useFormat"
+      ]
     }
   ]
 }

package/dist/components/registry/heatmap/calendar-heatmap.d.ts

@@ -32,6 +32,10 @@ export type CalendarHeatmapProps = HTMLAttributes<HTMLDivElement> & {
   blockAspectRatio?: number;
   levels?: number;
   isNormalized?: boolean;
+  /** Colour each day green or red by its sign, deeper the larger it is, for a daily gain or loss. */
+  signed?: boolean;
+  /** With signed: the size that takes the deepest step. Defaults to the largest day's. */
+  range?: number;
   colors?: ColorConfig;
   locale?: Locale;
   labels?: Labels;
@@ -75,7 +79,7 @@ export type CalendarHeatmapProps = HTMLAttributes<HTMLDivElement> & {
  * @param levels - Total number of legend cells (including empty when not normalized). Default: 5
  * @param isNormalized - When true, uses min-max normalization across the dataset (suitable for signed values). When false (default), treats 0 as empty and scales from 0 to max.
  */
-export declare const CalendarHeatmap: ({ data, weekStart, continuousMonths, hasEmptyColumn, blockSize: blockSizeProp, blockMargin, blockRadius, blockAspectRatio, levels: levelsProp, isNormalized, colors, locale, labels: labelsProp, fontSize, emptyState, totalCount: totalCountProp, style, className, children, ...props }: CalendarHeatmapProps) => string | number | bigint | true | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;
+export declare const CalendarHeatmap: ({ data, weekStart, continuousMonths, hasEmptyColumn, blockSize: blockSizeProp, blockMargin, blockRadius, blockAspectRatio, levels: levelsProp, isNormalized, signed, range, colors, locale, labels: labelsProp, fontSize, emptyState, totalCount: totalCountProp, style, className, children, ...props }: CalendarHeatmapProps) => string | number | bigint | true | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;
 export type CalendarHeatmapBlockProps = HTMLAttributes<SVGRectElement> & {
   /** The cell the page has picked: drawn with a ring and announced as pressed. */
   selected?: boolean;
@@ -127,10 +131,12 @@ export type CalendarHeatmapLegendProps = Omit<HTMLAttributes<HTMLFieldSetElement
     less?: string;
     more?: string;
   };
+  /** A signed heatmap's figures in the legend's scale line, such as useFormat().money. */
+  valueFormatter?: (value: number) => string;
   children?: (props: {
     level: number;
   }) => ReactNode;
 };
-export declare const CalendarHeatmapLegend: ({ labels: labelsProp, className, children, ...props }: CalendarHeatmapLegendProps) => import("react").JSX.Element;
+export declare const CalendarHeatmapLegend: ({ labels: labelsProp, valueFormatter, className, children, ...props }: CalendarHeatmapLegendProps) => import("react").JSX.Element;
 //#endregion
 export {};

package/dist/components/registry/heatmap/calendar-heatmap.js

@@ -1,18 +1,18 @@
 import { cn } from "../../../lib/utils.js";
 import { useHeatmapNavigation } from "../../../lib/heatmap-navigation.js";
 import { useElementWidth } from "../../../lib/use-element-width.js";
+import { heat, heatFill } from "../../../lib/heat.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Fragment as Fragment$1, createContext, use, useLayoutEffect, useMemo } from "react";
 import { differenceInCalendarDays, eachDayOfInterval, format, formatISO, getDay, getMonth, getYear, nextDay, parseISO, subWeeks } from "date-fns";
 //#region src/components/registry/heatmap/calendar-heatmap.tsx
 const colorStepCount = (levels, isNormalized) => Math.max(1, isNormalized ? levels : levels - 1);
-const getLevelFill = (level, levels, isNormalized, highlighted = false, colors) => {
+const getLevelFill = (level, levels, isNormalized, colors) => {
 	const emptyColor = colors?.empty ?? "var(--color-secondary)";
 	const scaleColor = colors?.scale ?? "var(--color-chart-1)";
 	if (level === 0) return emptyColor;
 	const steps = colorStepCount(levels, isNormalized);
-	const opacity = steps === 1 ? 100 : Math.round(20 + (level - 1) * 80 / (steps - 1));
-	return `color-mix(in oklch, ${scaleColor} ${highlighted ? Math.round(opacity * .6) : opacity}%, transparent)`;
+	return `color-mix(in oklch, ${scaleColor} ${steps === 1 ? 100 : Math.round(20 + (level - 1) * 80 / (steps - 1))}%, transparent)`;
 };
 const calculateLevel = (value, minValue, maxValue, levels, isNormalized) => {
 	const steps = colorStepCount(levels, isNormalized);
@@ -40,6 +40,14 @@ const generateWeekdayLabels = (locale) => {
 		return date.toLocaleString("en-US", { weekday: "short" });
 	});
 };
+/** How a signed day is drawn: its heat tint, the edge that carries its sign's colour, and whether it is round. */
+const signedMark = (value) => {
+	const known = Number.isFinite(value) ? value : 0;
+	return {
+		stroke: known > 0 ? "var(--positive)" : known < 0 ? "var(--negative)" : "var(--input)",
+		round: known < 0
+	};
+};
 const EMPTY_STYLE = {};
 const LABEL_MARGIN = 8;
 const WEEKDAY_LABEL_WIDTH = 40;
@@ -218,7 +226,7 @@ const getMonthLabels = (weeks, monthNames = generateMonthLabels(), yearTicks = f
 * @param levels - Total number of legend cells (including empty when not normalized). Default: 5
 * @param isNormalized - When true, uses min-max normalization across the dataset (suitable for signed values). When false (default), treats 0 as empty and scales from 0 to max.
 */
-const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmptyColumn = false, blockSize: blockSizeProp, blockMargin = 4, blockRadius = 2, blockAspectRatio = 1, levels: levelsProp = 5, isNormalized = false, colors, locale, labels: labelsProp, fontSize = 14, emptyState, totalCount: totalCountProp, style = EMPTY_STYLE, className, children, ...props }) => {
+const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmptyColumn = false, blockSize: blockSizeProp, blockMargin = 4, blockRadius = 2, blockAspectRatio = 1, levels: levelsProp = 5, isNormalized = false, signed = false, range, colors, locale, labels: labelsProp, fontSize = 14, emptyState, totalCount: totalCountProp, style = EMPTY_STYLE, className, children, ...props }) => {
 	const levels = Math.max(1, levelsProp);
 	const [rootRef, rootWidth] = useElementWidth();
 	const dataWithLevels = useMemo(() => {
@@ -241,6 +249,15 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		continuousMonths
 	]);
 	const weeks = useMemo(() => yearRows.flatMap((r) => r.weeks), [yearRows]);
+	const signedRange = useMemo(() => {
+		if (!signed) return null;
+		if (range !== void 0 && Number.isFinite(range) && range > 0) return range;
+		return Math.max(0, ...data.map((d) => Number.isFinite(d.value) ? Math.abs(d.value) : 0));
+	}, [
+		signed,
+		range,
+		data
+	]);
 	const labels = useMemo(() => ({
 		months: generateMonthLabels(locale),
 		weekdays: generateWeekdayLabels(locale),
@@ -280,7 +297,8 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		hasEmptyColumn,
 		continuousMonths,
 		locale,
-		colors
+		colors,
+		signedRange
 	}), [
 		dataWithLevels,
 		weeks,
@@ -303,7 +321,8 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		hasEmptyColumn,
 		continuousMonths,
 		locale,
-		colors
+		colors,
+		signedRange
 	]);
 	if (data.length === 0) return emptyState ? emptyState : null;
 	return /* @__PURE__ */ jsx(CalendarHeatmapContext, {
@@ -322,8 +341,9 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 	});
 };
 const CalendarHeatmapBlock = ({ ref, activity, dayIndex, weekIndex, highlighted = false, selected = false, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }) => {
-	const { blockSize, blockWidth, blockMargin, blockRadius, labelHeight, labels, levels, isNormalized, colors } = useCalendarHeatmap();
+	const { blockSize, blockWidth, blockMargin, blockRadius, labelHeight, labels, levels, isNormalized, colors, signedRange } = useCalendarHeatmap();
 	const level = Math.max(0, Math.min(colorStepCount(levels, isNormalized), activity.level));
+	const mark = signedRange === null ? null : signedMark(activity.value);
 	const ariaLabel = (labels.cellLabel ?? "{{date}}: {{value}} contributions").replace("{{date}}", activity.date).replace("{{value}}", String(activity.value));
 	return /* @__PURE__ */ jsx("rect", {
 		ref,
@@ -332,24 +352,22 @@ const CalendarHeatmapBlock = ({ ref, activity, dayIndex, weekIndex, highlighted
 		"aria-pressed": onCellClick ? selected : void 0,
 		tabIndex: onCellClick ? 0 : -1,
 		"aria-label": ariaLabel,
-		className: cn("motion-safe:transition-opacity motion-safe:hover:opacity-70", onCellClick && "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className),
+		className: cn("hover:stroke-foreground hover:stroke-1", highlighted && "stroke-foreground stroke-1", selected && "stroke-foreground stroke-2 hover:stroke-2", onCellClick && "cursor-pointer focus-visible:outline-none focus-visible:stroke-ring focus-visible:stroke-2", className),
 		"data-value": activity.value,
 		"data-date": activity.date,
 		"data-level": level,
 		"data-highlighted": highlighted || void 0,
 		"data-selected": selected || void 0,
 		height: blockSize,
-		rx: blockRadius,
-		ry: blockRadius,
+		rx: mark?.round ? blockSize / 2 : blockRadius,
+		ry: mark?.round ? blockSize / 2 : blockRadius,
 		width: blockWidth,
+		stroke: mark?.stroke,
+		strokeWidth: mark ? 1 : void 0,
 		x: (blockWidth + blockMargin) * weekIndex,
 		y: labelHeight + (blockSize + blockMargin) * dayIndex,
 		style: {
-			fill: getLevelFill(level, levels, isNormalized, highlighted, colors),
-			...selected ? {
-				stroke: "var(--foreground)",
-				strokeWidth: 2
-			} : {},
+			fill: signedRange === null ? getLevelFill(level, levels, isNormalized, colors) : heat(activity.value, signedRange),
 			...styleProp
 		},
 		onClick: (event) => {
@@ -498,8 +516,14 @@ const CalendarHeatmapStat = ({ compute, label, className, children, ...props })
 		children: template.replace("{{value}}", String(value)).replace("{{year}}", String(year))
 	});
 };
-const CalendarHeatmapLegend = ({ labels: labelsProp, className, children, ...props }) => {
-	const { levels, isNormalized, blockRadius, colors, labels } = useCalendarHeatmap();
+const CalendarHeatmapLegend = ({ labels: labelsProp, valueFormatter, className, children, ...props }) => {
+	const { levels, isNormalized, blockRadius, colors, labels, signedRange } = useCalendarHeatmap();
+	if (signedRange !== null) return /* @__PURE__ */ jsx(SignedLegend, {
+		labels: labelsProp,
+		valueFormatter,
+		className,
+		...props
+	});
 	const lessLabel = labelsProp?.less ?? "Less";
 	const moreLabel = labelsProp?.more ?? "More";
 	const legendLevels = Array.from({ length: levels }, (_, i) => isNormalized ? i + 1 : i);
@@ -524,7 +548,7 @@ const CalendarHeatmapLegend = ({ labels: labelsProp, className, children, ...pro
 					rx: blockRadius,
 					ry: blockRadius,
 					width: LEGEND_SWATCH,
-					style: { fill: getLevelFill(level, levels, isNormalized, false, colors) }
+					style: { fill: getLevelFill(level, levels, isNormalized, colors) }
 				})
 			}, `legend-level-${level}`)),
 			/* @__PURE__ */ jsx("span", {
@@ -534,5 +558,59 @@ const CalendarHeatmapLegend = ({ labels: labelsProp, className, children, ...pro
 		]
 	});
 };
+/** A signed heatmap's scale: round loss steps deepest first, no change, square gain steps, and what they span. */
+const SignedLegend = ({ labels: labelsProp, valueFormatter = String, className, ...props }) => {
+	const { blockRadius, labels, signedRange } = useCalendarHeatmap();
+	const steps = Array.from({ length: 5 }, (_, i) => i + 1);
+	const swatch = (key, fill, value) => {
+		const { stroke, round } = signedMark(value);
+		const corner = round ? 11 / 2 : blockRadius;
+		return /* @__PURE__ */ jsx("svg", {
+			"aria-hidden": "true",
+			height: LEGEND_SWATCH,
+			width: LEGEND_SWATCH,
+			children: /* @__PURE__ */ jsx("rect", {
+				x: .5,
+				y: .5,
+				height: 11,
+				width: 11,
+				rx: corner,
+				ry: corner,
+				stroke,
+				style: { fill }
+			})
+		}, key);
+	};
+	return /* @__PURE__ */ jsxs("fieldset", {
+		"data-slot": "calendar-heatmap-legend",
+		"aria-label": labels.legendLabel ?? "Activity intensity legend",
+		className: cn("ml-auto flex flex-col items-end gap-1 text-muted-foreground", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-1",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					className: "mr-1 font-medium text-xs",
+					children: labelsProp?.less ?? "Loss"
+				}),
+				steps.toReversed().map((step) => swatch(`loss-${step}`, heatFill("negative", step), -1)),
+				swatch("none", heat(null), 0),
+				steps.map((step) => swatch(`gain-${step}`, heatFill("positive", step), 1)),
+				/* @__PURE__ */ jsx("span", {
+					className: "ml-1 font-medium text-xs",
+					children: labelsProp?.more ?? "Gain"
+				})
+			]
+		}), /* @__PURE__ */ jsxs("p", {
+			"data-slot": "calendar-heatmap-legend-scale",
+			className: "text-xs",
+			children: [
+				"Deepest at ±",
+				valueFormatter(signedRange ?? 0),
+				". Round days lost, square days gained; grey days had no change."
+			]
+		})]
+	});
+};
 //#endregion
 export { CalendarHeatmap, CalendarHeatmapBlock, CalendarHeatmapBody, CalendarHeatmapFooter, CalendarHeatmapLegend, CalendarHeatmapStat };