@spatika/react 1.3.1 → 1.4.0

package/src/composites/chart-ui.tsx

@@ -14,12 +14,12 @@ import {
   type ChartAxisConfig,
   type ChartMargin,
 } from "../lib/charts";
+import {
+  type ChartHover,
+  type ChartTooltipRenderer,
+} from "./chart-interaction";
 
-export type ChartTooltipItem = {
-  color: string;
-  label: string;
-  value: string;
-};
+export type { ChartHover, ChartTooltipItem } from "./chart-interaction";
 
 export type ChartLegendItem = {
   id: string;
@@ -27,23 +27,19 @@ export type ChartLegendItem = {
   color: string;
 };
 
-export type ChartHover = {
-  x: number;
-  y: number;
-  title?: string;
-  items: ChartTooltipItem[];
-} | null;
-
 export type ChartFrameProps = {
   slot: string;
   className?: string;
   width?: number;
   height?: number;
+  /** When true, plot height follows the parent instead of the numeric `height`. */
+  fillHeight?: boolean;
   margin?: ChartMargin;
   legend?: ChartLegendItem[];
   hiddenIds?: Set<string>;
   onToggleSeries?: (id: string) => void;
   hover?: ChartHover;
+  renderTooltip?: ChartTooltipRenderer;
   "aria-label"?: string;
   children: (plot: { width: number; height: number; m: Required<ChartMargin> }) => ReactNode;
 };
@@ -88,24 +84,26 @@ export function ChartFrame({
   className,
   width,
   height = 280,
+  fillHeight = false,
   margin,
   legend,
   hiddenIds,
   onToggleSeries,
   hover,
+  renderTooltip,
   "aria-label": ariaLabel,
   children,
 }: ChartFrameProps) {
   const surfaceRef = useRef<HTMLDivElement>(null);
   const measured = useElementSize(surfaceRef, width ?? 320, height);
   const plotWidth = width ?? measured.width;
-  const plotHeight = height;
+  const plotHeight = fillHeight ? measured.height : height;
   const m = resolveMargin(margin);
 
   return (
     <div
       data-slot={slot}
-      className={cn("spk-chart", className)}
+      className={cn("spk-chart", fillHeight && "spk-chart--fill", className)}
       role="img"
       aria-label={ariaLabel}
     >
@@ -115,10 +113,10 @@ export function ChartFrame({
       <div
         ref={surfaceRef}
         className="spk-chart-surface"
-        style={{ height: plotHeight }}
+        style={fillHeight ? undefined : { height: plotHeight }}
       >
-        {plotWidth > 0 ? children({ width: plotWidth, height: plotHeight, m }) : null}
-        <ChartTooltip hover={hover ?? null} boundsWidth={plotWidth} />
+        {plotWidth > 0 && plotHeight > 0 ? children({ width: plotWidth, height: plotHeight, m }) : null}
+        <ChartTooltip hover={hover ?? null} boundsWidth={plotWidth} render={renderTooltip} />
       </div>
     </div>
   );
@@ -154,24 +152,34 @@ export function ChartLegend({
 export function ChartTooltip({
   hover,
   boundsWidth,
+  render,
 }: {
   hover: ChartHover;
   boundsWidth: number;
+  render?: ChartTooltipRenderer;
 }) {
   if (!hover || !hover.items.length) return null;
+  const custom = render?.(hover);
+  if (render && custom == null) return null;
   const left = clampTooltip(hover.x, boundsWidth);
   return (
     <div className="spk-chart-tooltip" style={{ left, top: hover.y }} role="tooltip">
-      {hover.title ? <p className="spk-chart-tooltip-title">{hover.title}</p> : null}
-      <ul>
-        {hover.items.map((item) => (
-          <li key={item.label}>
-            <span className="spk-chart-swatch" style={{ background: item.color }} />
-            <span>{item.label}</span>
-            <strong>{item.value}</strong>
-          </li>
-        ))}
-      </ul>
+      {render ? (
+        custom
+      ) : (
+        <>
+          {hover.title ? <p className="spk-chart-tooltip-title">{hover.title}</p> : null}
+          <ul>
+            {hover.items.map((item) => (
+              <li key={item.label}>
+                <span className="spk-chart-swatch" style={{ background: item.color }} />
+                <span>{item.label}</span>
+                <strong>{item.value}</strong>
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
     </div>
   );
 }

package/src/composites/flow-charts.test.tsx

@@ -1,5 +1,5 @@
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
 import { FunnelChart, Heatmap } from "./flow-charts";
 
 describe("FunnelChart", () => {
@@ -76,4 +76,23 @@ describe("Heatmap", () => {
     );
     expect(container.querySelector('[data-slot="heatmap-color-scale"]')).toBeNull();
   });
+
+  it("fires onItemClick and can label cells", () => {
+    const onItemClick = vi.fn();
+    const { container } = render(
+      <Heatmap
+        width={240}
+        height={160}
+        hideLegend
+        showCellLabels
+        xAxis={[{ data: ["A"] }]}
+        yAxis={[{ data: ["1"] }]}
+        series={[{ data: [{ x: 0, y: 0, value: 4 }] }]}
+        onItemClick={onItemClick}
+      />,
+    );
+    expect(screen.getByText("4")).toBeInTheDocument();
+    fireEvent.click(container.querySelector(".spk-chart-mark--interactive")!);
+    expect(onItemClick).toHaveBeenCalledWith(expect.objectContaining({ value: 4, category: "A · 1" }));
+  });
 });

package/src/composites/flow-charts.tsx

@@ -22,6 +22,7 @@ import {
   useChartHover,
   useHiddenSeries,
 } from "./chart-ui";
+import { bindChartMark, type ChartItemEvent, type ChartTooltipRenderer } from "./chart-interaction";
 
 export type HeatDatum = { x: number; y: number; value: number };
 
@@ -35,6 +36,10 @@ export type HeatmapProps = {
   showColorScale?: boolean;
   margin?: ChartMargin;
   className?: string;
+  fillHeight?: boolean;
+  onItemClick?: (event: ChartItemEvent) => void;
+  renderTooltip?: ChartTooltipRenderer;
+  showCellLabels?: boolean | ((cell: HeatDatum) => string);
 };
 
 export function Heatmap({
@@ -47,6 +52,10 @@ export function Heatmap({
   showColorScale,
   margin,
   className,
+  fillHeight,
+  onItemClick,
+  renderTooltip,
+  showCellLabels = false,
 }: HeatmapProps) {
   const cells = series[0]?.data ?? [];
   const xs = categoryLabels(xAxis?.[0], Math.max(...cells.map((c) => c.x), 0) + 1);
@@ -65,8 +74,10 @@ export function Heatmap({
       className={className}
       width={width}
       height={height}
+      fillHeight={fillHeight}
       margin={margin ?? { top: colorScale ? 32 : 12, right: 12, bottom: 36, left: 72 }}
       hover={hover}
+      renderTooltip={renderTooltip}
       aria-label="Heatmap"
     >
       {({ width: w, height: h, m }) => {
@@ -131,32 +142,55 @@ export function Heatmap({
             ))}
             {cells.map((cell, i) => {
               const t = (cell.value - min) / (max - min || 1);
+              const color = heatColor(t);
+              const category = `${xs[cell.x]} · ${ys[cell.y]}`;
+              const event: ChartItemEvent = {
+                seriesId: "heat",
+                seriesLabel: "value",
+                dataIndex: i,
+                category,
+                value: cell.value,
+                color,
+              };
+              const cellLabel =
+                typeof showCellLabels === "function"
+                  ? showCellLabels(cell)
+                  : showCellLabels
+                    ? formatChartNumber(cell.value)
+                    : null;
               return (
-                <rect
-                  key={i}
-                  x={m.left + cell.x * cw + 1.5}
-                  y={m.top + cell.y * ch + 1.5}
-                  width={Math.max(1, cw - 3)}
-                  height={Math.max(1, ch - 3)}
-                  rx={4}
-                  fill={heatColor(t)}
-                  className="spk-chart-mark"
-                  onMouseEnter={(event) =>
-                    setHover({
-                      x: event.nativeEvent.offsetX,
-                      y: event.nativeEvent.offsetY,
-                      title: `${xs[cell.x]} · ${ys[cell.y]}`,
-                      items: [
-                        {
-                          color: heatColor(t),
-                          label: "value",
-                          value: formatChartNumber(cell.value),
-                        },
-                      ],
-                    })
-                  }
-                  onMouseLeave={clear}
-                />
+                <g key={i}>
+                  <rect
+                    x={m.left + cell.x * cw + 1.5}
+                    y={m.top + cell.y * ch + 1.5}
+                    width={Math.max(1, cw - 3)}
+                    height={Math.max(1, ch - 3)}
+                    rx={4}
+                    fill={color}
+                    {...bindChartMark({
+                      event,
+                      hover: {
+                        title: category,
+                        items: [{ color, label: "value", value: formatChartNumber(cell.value) }],
+                      },
+                      onItemClick,
+                      setHover,
+                      clearHover: clear,
+                    })}
+                  />
+                  {cellLabel ? (
+                    <text
+                      className="spk-chart-label"
+                      x={m.left + cell.x * cw + cw / 2}
+                      y={m.top + cell.y * ch + ch / 2}
+                      textAnchor="middle"
+                      dominantBaseline="middle"
+                      pointerEvents="none"
+                    >
+                      {cellLabel}
+                    </text>
+                  ) : null}
+                </g>
               );
             })}
           </svg>

package/src/composites/radial-charts.test.tsx

@@ -1,5 +1,5 @@
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
 import { Gauge, LinearGauge, PieChart, RadarChart } from "./radial-charts";
 
 describe("radial-charts", () => {
@@ -15,6 +15,21 @@ describe("radial-charts", () => {
     expect(screen.getByRole("button", { name: "A" })).toBeInTheDocument();
   });
 
+  it("fires onItemClick from a pie slice", () => {
+    const onItemClick = vi.fn();
+    const { container } = render(
+      <PieChart
+        width={200}
+        height={200}
+        hideLegend
+        series={[{ data: [{ value: 10, label: "A" }, { value: 20, label: "B" }] }]}
+        onItemClick={onItemClick}
+      />,
+    );
+    fireEvent.click(container.querySelector(".spk-chart-mark--interactive")!);
+    expect(onItemClick).toHaveBeenCalledWith(expect.objectContaining({ seriesLabel: "A", value: 10 }));
+  });
+
   it("renders a single-value gauge with a percent label", () => {
     render(<Gauge value={40} width={160} height={120} />);
     expect(screen.getByRole("img", { name: "Gauge 40" })).toBeInTheDocument();

package/src/composites/radial-charts.tsx

@@ -13,6 +13,7 @@ import {
   useChartHover,
   useHiddenSeries,
 } from "./chart-ui";
+import { bindChartMark, type ChartItemEvent, type ChartTooltipRenderer } from "./chart-interaction";
 
 export type PieDatum = {
   id?: string | number;
@@ -42,6 +43,11 @@ export type PieChartProps = {
   margin?: ChartMargin;
   className?: string;
   slot?: string;
+  fillHeight?: boolean;
+  onItemClick?: (event: ChartItemEvent) => void;
+  renderTooltip?: ChartTooltipRenderer;
+  /** Return slice label text, or null to hide. Defaults to percent when the slice is large enough. */
+  labelFormatter?: (item: { label: string; value: number; percent: number }) => string | null;
 };
 
 export function PieChart({
@@ -53,6 +59,10 @@ export function PieChart({
   margin,
   className,
   slot = "pie-chart",
+  fillHeight,
+  onItemClick,
+  renderTooltip,
+  labelFormatter,
 }: PieChartProps) {
   const first = series[0] ?? { data: [] };
   const meta = seriesMeta(
@@ -73,11 +83,13 @@ export function PieChart({
       className={className}
       width={width}
       height={height}
+      fillHeight={fillHeight}
       margin={margin ?? { top: 12, right: 12, bottom: 12, left: 12 }}
       legend={hideLegend ? undefined : meta}
       hiddenIds={hidden}
       onToggleSeries={toggle}
       hover={hover}
+      renderTooltip={renderTooltip}
       aria-label="Pie chart"
     >
       {({ width: w, height: h, m }) => {
@@ -102,29 +114,43 @@ export function PieChart({
               const info = meta[i]!;
               if (hidden.has(info.id) || !slice.path) return null;
               const item = first.data[i]!;
+              const color = info.color;
+              const event: ChartItemEvent = {
+                seriesId: info.id,
+                seriesLabel: info.label,
+                dataIndex: i,
+                category: info.label,
+                value: item.value,
+                color,
+              };
+              const labelText = labelFormatter
+                ? labelFormatter({ label: info.label, value: item.value, percent: slice.percent })
+                : slice.percent > 0.08
+                  ? `${Math.round(slice.percent * 100)}%`
+                  : null;
               return (
                 <g key={info.id}>
                   <path
                     d={slice.path}
-                    fill={info.color}
-                    className="spk-chart-mark"
-                    onMouseEnter={(event) =>
-                      setHover({
-                        x: event.nativeEvent.offsetX,
-                        y: event.nativeEvent.offsetY,
+                    fill={color}
+                    {...bindChartMark({
+                      event,
+                      hover: {
                         title: info.label,
                         items: [
                           {
-                            color: info.color,
+                            color,
                             label: info.label,
                             value: `${formatChartNumber(item.value)} (${Math.round(slice.percent * 100)}%)`,
                           },
                         ],
-                      })
-                    }
-                    onMouseLeave={clear}
+                      },
+                      onItemClick,
+                      setHover,
+                      clearHover: clear,
+                    })}
                   />
-                  {slice.percent > 0.08 ? (
+                  {labelText ? (
                     <text
                       className="spk-chart-label"
                       fill="var(--primary-foreground)"
@@ -133,7 +159,7 @@ export function PieChart({
                       textAnchor="middle"
                       dominantBaseline="middle"
                     >
-                      {Math.round(slice.percent * 100)}%
+                      {labelText}
                     </text>
                   ) : null}
                 </g>

package/src/composites/scheduler-ui.tsx

@@ -12,6 +12,7 @@ import {
   type SchedulerResource,
   type TimelineScale,
 } from "../lib/scheduler";
+import { NativeSelect } from "../primitives/NativeSelect";
 import { Button } from "../primitives/Button";
 import {
   DropdownMenu,
@@ -36,6 +37,8 @@ export const TIMELINE_SCALE_LABEL: Record<TimelineScale, string> = {
   years: "Years",
 };
 
+export type SchedulerToolbarDensity = "default" | "compact";
+
 export type SchedulerToolbarProps = {
   title: ReactNode;
   onPrev: () => void;
@@ -44,6 +47,10 @@ export type SchedulerToolbarProps = {
   menuLabel: string;
   menu: ReactNode;
   trailing?: ReactNode;
+  /** Compact is a single desktop row. Defaults keep the stacked marketing toolbar. */
+  density?: SchedulerToolbarDensity;
+  /** Month/year jump. Sits beside the view menu. */
+  dateJump?: ReactNode;
 };
 
 export function SchedulerToolbar({
@@ -54,48 +61,143 @@ export function SchedulerToolbar({
   menuLabel,
   menu,
   trailing,
+  density = "default",
+  dateJump,
 }: SchedulerToolbarProps) {
+  const nav = (
+    <div className="flex items-center gap-1">
+      <Button
+        type="button"
+        variant="ghost"
+        size="icon"
+        aria-label="Previous"
+        onClick={onPrev}
+      >
+        <ChevronLeft className="size-4" />
+      </Button>
+      <Button type="button" variant="outline" size="sm" className="uppercase tracking-wide" onClick={onToday}>
+        Today
+      </Button>
+      <Button type="button" variant="ghost" size="icon" aria-label="Next" onClick={onNext}>
+        <ChevronRight className="size-4" />
+      </Button>
+    </div>
+  );
+
+  const viewMenu = (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button type="button" variant="outline" size="sm" className="min-w-[6.5rem] justify-between gap-2 uppercase tracking-wide">
+          {menuLabel}
+          <ChevronDown className="size-3.5 opacity-70" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">{menu}</DropdownMenuContent>
+    </DropdownMenu>
+  );
+
+  if (density === "compact") {
+    return (
+      <div
+        data-slot="scheduler-toolbar"
+        data-density="compact"
+        className="grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-3 border-b border-border/50 px-3 py-2 sm:px-4 sm:py-3"
+      >
+        {nav}
+        <h2 className="min-w-0 truncate text-center text-sm font-black uppercase tracking-widest text-foreground">
+          {title}
+        </h2>
+        <div className="flex shrink-0 flex-nowrap items-center justify-end gap-2">
+          {viewMenu}
+          {dateJump}
+          {trailing}
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       data-slot="scheduler-toolbar"
+      data-density="default"
       className="flex flex-col gap-3 border-b border-border/50 px-3 py-3 sm:flex-row sm:items-center sm:justify-between sm:px-4"
     >
       <h2 className="min-w-0 truncate text-xl font-black tracking-tight text-foreground sm:text-2xl">
         {title}
       </h2>
       <div className="flex flex-wrap items-center gap-2">
-        <div className="flex items-center gap-1">
-          <Button
-            type="button"
-            variant="ghost"
-            size="icon"
-            aria-label="Previous"
-            onClick={onPrev}
-          >
-            <ChevronLeft className="size-4" />
-          </Button>
-          <Button type="button" variant="outline" size="sm" className="uppercase tracking-wide" onClick={onToday}>
-            Today
-          </Button>
-          <Button type="button" variant="ghost" size="icon" aria-label="Next" onClick={onNext}>
-            <ChevronRight className="size-4" />
-          </Button>
-        </div>
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button type="button" variant="outline" size="sm" className="min-w-[6.5rem] justify-between gap-2 uppercase tracking-wide">
-              {menuLabel}
-              <ChevronDown className="size-3.5 opacity-70" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end">{menu}</DropdownMenuContent>
-        </DropdownMenu>
+        {nav}
+        {viewMenu}
+        {dateJump}
         {trailing}
       </div>
     </div>
   );
 }
 
+const DATE_JUMP_SELECT =
+  "w-[5.25rem] min-w-[5.25rem] text-center [text-align-last:center]";
+
+export type SchedulerDateJumpProps = {
+  date: Date;
+  locale?: string;
+  yearOptions?: number[];
+  onDateChange: (date: Date) => void;
+};
+
+function resolveYearOptions(year: number, yearOptions?: number[]) {
+  if (yearOptions && yearOptions.length > 0) {
+    return yearOptions.includes(year) ? yearOptions : [...yearOptions, year].sort((a, b) => a - b);
+  }
+  return Array.from({ length: 13 }, (_, index) => year - 8 + index);
+}
+
+/** Compact month/year native selects for calendar toolbars. */
+export function SchedulerDateJump({
+  date,
+  locale,
+  yearOptions,
+  onDateChange,
+}: SchedulerDateJumpProps) {
+  const month = date.getMonth();
+  const year = date.getFullYear();
+  const years = resolveYearOptions(year, yearOptions);
+  const months = Array.from({ length: 12 }, (_, index) =>
+    new Intl.DateTimeFormat(locale, { month: "short" }).format(new Date(2020, index, 1)).toUpperCase(),
+  );
+
+  return (
+    <div className="flex shrink-0 items-center gap-1.5">
+      <NativeSelect
+        size="sm"
+        className={DATE_JUMP_SELECT}
+        aria-label="Month"
+        value={month}
+        onChange={(event) => onDateChange(new Date(year, Number(event.target.value), 1))}
+      >
+        {months.map((label, index) => (
+          <option key={label} value={index}>
+            {label}
+          </option>
+        ))}
+      </NativeSelect>
+      <NativeSelect
+        size="sm"
+        className={cn(DATE_JUMP_SELECT, "tabular-nums")}
+        aria-label="Year"
+        value={year}
+        onChange={(event) => onDateChange(new Date(Number(event.target.value), month, 1))}
+      >
+        {years.map((yearOption) => (
+          <option key={yearOption} value={yearOption}>
+            {yearOption}
+          </option>
+        ))}
+      </NativeSelect>
+    </div>
+  );
+}
+
 export function SchedulerPreferencesMenu({
   value,
   onChange,

package/src/composites/scheduler.test.tsx

@@ -221,6 +221,45 @@ describe("EventCalendar", () => {
     expect(screen.getByRole("button", { name: "Jump year" })).toBeInTheDocument();
     expect(screen.getByRole("heading", { name: /August 2026/i })).toBeInTheDocument();
   });
+
+  it("renders a compact toolbar with equal month and year jumps", () => {
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        locale="en-US"
+        showPreferences={false}
+        toolbarDensity="compact"
+        showDateJump
+      />,
+    );
+    expect(document.querySelector('[data-density="compact"]')).toBeTruthy();
+    expect(screen.getByLabelText("Month")).toHaveAttribute("data-size", "sm");
+    expect(screen.getByLabelText("Year")).toHaveAttribute("data-size", "sm");
+    expect(screen.getByLabelText("Month")).toHaveValue("7");
+    expect(screen.getByLabelText("Year")).toHaveValue("2026");
+  });
+
+  it("reports the visible range for week view", () => {
+    const onVisibleRangeChange = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        defaultView="week"
+        locale="en-US"
+        onVisibleRangeChange={onVisibleRangeChange}
+      />,
+    );
+    expect(onVisibleRangeChange).toHaveBeenCalled();
+    const range = onVisibleRangeChange.mock.calls[0][0] as {
+      view: string;
+      start: Date;
+      end: Date;
+    };
+    expect(range.view).toBe("week");
+    expect(range.start.getDay()).toBe(0);
+    expect(range.end.getTime() - range.start.getTime()).toBe(7 * 86_400_000);
+  });
 });
 
 describe("EventTimeline", () => {

package/src/index.test.ts

@@ -7,7 +7,9 @@ import {
   ChartDataGrid,
   EventCalendar,
   MapChart,
+  SchedulerDateJump,
   SchedulerToolbar,
+  calendarVisibleRange,
   mercator,
 } from "./index";
 
@@ -21,6 +23,8 @@ describe("@spatika/react public exports", () => {
     expect(BarChart3D).toBeTypeOf("function");
     expect(EventCalendar).toBeTypeOf("function");
     expect(SchedulerToolbar).toBeTypeOf("function");
+    expect(SchedulerDateJump).toBeTypeOf("function");
+    expect(calendarVisibleRange).toBeTypeOf("function");
     expect(mercator([0, 0])[0]).toBeCloseTo(0.5);
   });
 });