@spatika/react 1.3.0 → 1.4.0

package/skills/spatika-ui/SKILL.md

@@ -54,6 +54,10 @@ export function App() {
 | Chart | `BarChart` / `LineChart` / `ChartContainer` |
 | Calendar | `EventCalendar` |
 
+Charts: `onItemClick` for mark navigation, `itemColors` for per-bar tints, `renderTooltip` / `renderMark` for host chrome, `referenceLines` for capacity guides, `fillHeight` when the parent sets height. Pie and Heatmap accept the same click and tooltip slots.
+
+Prefer `toolbarDensity="compact"` and `showDateJump` for a dense product toolbar. `NativeSelect size="sm"` is the compact pill. `onVisibleRangeChange` is the fetch window (`end` exclusive). Use `showEventEditor={false}` when the host owns create/edit.
+
 ## App shell
 
 ```tsx

package/src/composites/EventCalendar.tsx

@@ -1,4 +1,5 @@
 import {
+  useEffect,
   useMemo,
   useRef,
   useState,
@@ -13,6 +14,8 @@ import {
   addDays,
   addMonths,
   agendaDays,
+  calendarVisibleRange,
+  CALENDAR_AGENDA_DAYS,
   DEFAULT_SCHEDULER_PREFERENCES,
   eventCanDrag,
   eventCanResize,
@@ -44,6 +47,7 @@ import {
   weekNumber,
   weekSpanLanesForDays,
   type CalendarView,
+  type CalendarVisibleRange,
   type NormalizedEvent,
   type SchedulerEvent,
   type SchedulerPreferences,
@@ -54,9 +58,11 @@ import {
   CALENDAR_VIEW_LABEL,
   EventResizeHandle,
   ResourceLegend,
+  SchedulerDateJump,
   SchedulerPreferencesMenu,
   SchedulerShell,
   SchedulerToolbar,
+  type SchedulerToolbarDensity,
 } from "./scheduler-ui";
 import { DropdownMenuItem } from "../primitives/DropdownMenu";
 
@@ -125,6 +131,14 @@ export type EventCalendarProps = {
   showPreferences?: boolean;
   /** Extra controls after the view menu. Ignored when `renderToolbar` is set. */
   toolbarTrailing?: ReactNode;
+  /** Default toolbar layout. Compact is a single desktop row. Ignored when `renderToolbar` is set. */
+  toolbarDensity?: SchedulerToolbarDensity;
+  /** Month/year native selects on the default toolbar. Ignored when `renderToolbar` is set. */
+  showDateJump?: boolean;
+  /** Years in the date-jump select. Defaults to a window around the current year. */
+  yearOptions?: number[];
+  /** Fires when the painted date window changes. `end` is exclusive. */
+  onVisibleRangeChange?: (range: CalendarVisibleRange & { view: CalendarView }) => void;
   /** Replace event chip contents. The kit still wraps with the click/drag trigger. */
   renderEvent?: (
     event: NormalizedEvent,
@@ -136,7 +150,6 @@ export type EventCalendarProps = {
 };
 
 const MAX_TIMED_IN_CELL = 3;
-const AGENDA_LENGTH = 14;
 
 function chunkWeeks<T>(items: T[]): T[][] {
   const weeks: T[][] = [];
@@ -153,27 +166,6 @@ function startOfToday(): Date {
   return new Date(now.getFullYear(), now.getMonth(), now.getDate());
 }
 
-function visibleRange(
-  view: CalendarView,
-  date: Date,
-  weekStartsOn: number,
-): { start: Date; end: Date } {
-  if (view === "month") {
-    const grid = getMonthGrid(date, weekStartsOn);
-    return { start: grid[0], end: addDays(grid[grid.length - 1], 1) };
-  }
-  if (view === "week") {
-    const days = getWeekDays(date, weekStartsOn);
-    return { start: days[0], end: addDays(days[6], 1) };
-  }
-  if (view === "agenda") {
-    const days = agendaDays(date, AGENDA_LENGTH);
-    return { start: days[0], end: addDays(days[days.length - 1], 1) };
-  }
-  const start = startOfDay(date);
-  return { start, end: addDays(start, 1) };
-}
-
 function draftFromSource(source: SchedulerEvent): EventEditorDraft {
   return {
     id: source.id,
@@ -217,6 +209,10 @@ export function EventCalendar({
   showEventEditor = true,
   showPreferences = true,
   toolbarTrailing,
+  toolbarDensity = "default",
+  showDateJump = false,
+  yearOptions,
+  onVisibleRangeChange,
   renderEvent,
   renderToolbar,
   className,
@@ -253,10 +249,14 @@ export function EventCalendar({
   const editorLocked = readOnly || Boolean(draft?.id && sourceEvent(events, draft.id)?.readOnly);
 
   const range = useMemo(
-    () => visibleRange(resolvedView, resolvedDate, startOn),
+    () => calendarVisibleRange(resolvedView, resolvedDate, startOn),
     [resolvedView, resolvedDate, startOn],
   );
 
+  useEffect(() => {
+    onVisibleRangeChange?.({ start: range.start, end: range.end, view: resolvedView });
+  }, [range.start, range.end, resolvedView, onVisibleRangeChange]);
+
   const normalized = useMemo(() => {
     const visible = visibleEvents(normalizeEvents(events, resources), hiddenIds);
     return expandVisibleEvents(visible, range.start, range.end, events);
@@ -473,6 +473,7 @@ export function EventCalendar({
       ) : (
         <SchedulerToolbar
           title={title}
+          density={toolbarDensity}
           onPrev={() => go(-1)}
           onNext={() => go(1)}
           onToday={() => setDate(new Date())}
@@ -482,6 +483,16 @@ export function EventCalendar({
               {CALENDAR_VIEW_LABEL[item]}
             </DropdownMenuItem>
           ))}
+          dateJump={
+            showDateJump ? (
+              <SchedulerDateJump
+                date={resolvedDate}
+                locale={locale}
+                yearOptions={yearOptions}
+                onDateChange={(next) => setDate(next)}
+              />
+            ) : null
+          }
           trailing={
             <>
               {toolbarTrailing}
@@ -964,7 +975,7 @@ function AgendaList({
     options?: { resize?: "ns"; variant: EventCalendarEventVariant },
   ) => ReactNode;
 }) {
-  const days = filterWeekendDays(agendaDays(date, AGENDA_LENGTH), showWeekends);
+  const days = filterWeekendDays(agendaDays(date, CALENDAR_AGENDA_DAYS), showWeekends);
 
   return (
     <div className="divide-y divide-border/50">

package/src/composites/cartesian-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 { AreaChart, BarChart, LineChart } from "./cartesian-charts";
 
 const months = ["Jan", "Feb", "Mar"];
@@ -49,4 +49,88 @@ describe("cartesian-charts", () => {
     expect(container.querySelector('[data-slot="area-plot"]')).toBeTruthy();
     expect(container.querySelectorAll('[data-slot="area-plot"] path').length).toBeGreaterThanOrEqual(2);
   });
+
+  it("fires onItemClick with the bar category and value", () => {
+    const onItemClick = vi.fn();
+    const { container } = render(
+      <BarChart
+        width={360}
+        height={220}
+        hideLegend
+        xAxis={[{ data: months }]}
+        series={[{ label: "Views", data: [4, 3, 5] }]}
+        onItemClick={onItemClick}
+      />,
+    );
+    const mark = container.querySelector(".spk-chart-mark--interactive");
+    expect(mark).toBeTruthy();
+    fireEvent.click(mark!);
+    expect(onItemClick).toHaveBeenCalledWith(
+      expect.objectContaining({ seriesLabel: "Views", dataIndex: 0, category: "Jan", value: 4 }),
+    );
+  });
+
+  it("colors individual bars from itemColors", () => {
+    const { container } = render(
+      <BarChart
+        width={360}
+        height={220}
+        hideLegend
+        xAxis={[{ data: months }]}
+        series={[{ label: "Growth", data: [2, -1, 3], itemColors: ["var(--chart-3)", "var(--chart-4)"] }]}
+      />,
+    );
+    const marks = container.querySelectorAll('[data-slot="bar-plot"] .spk-chart-mark');
+    expect(marks[0]?.getAttribute("fill")).toBe("var(--chart-3)");
+    expect(marks[1]?.getAttribute("fill")).toBe("var(--chart-4)");
+  });
+
+  it("renders a reference line and end labels on bars", () => {
+    const { container } = render(
+      <BarChart
+        width={360}
+        height={220}
+        hideLegend
+        showLabels
+        xAxis={[{ data: months }]}
+        series={[{ label: "Views", data: [4, 3, 5] }]}
+        referenceLines={[{ y: 4, label: "Target" }]}
+      />,
+    );
+    expect(container.querySelector('[data-slot="chart-reference-lines"]')).toBeTruthy();
+    expect(screen.getByText("Target")).toBeInTheDocument();
+    expect(container.querySelector('[data-slot="bar-labels"]')).toBeTruthy();
+  });
+
+  it("fires onItemClick from horizontal bars", () => {
+    const onItemClick = vi.fn();
+    const { container } = render(
+      <BarChart
+        width={360}
+        height={220}
+        hideLegend
+        layout="horizontal"
+        xAxis={[{ data: months }]}
+        series={[{ label: "Views", data: [4, 3, 5] }]}
+        onItemClick={onItemClick}
+      />,
+    );
+    fireEvent.click(container.querySelector(".spk-chart-mark--interactive")!);
+    expect(onItemClick).toHaveBeenCalledWith(expect.objectContaining({ category: "Jan", value: 4 }));
+  });
+
+  it("renders a custom tooltip from hover", () => {
+    const { container } = render(
+      <BarChart
+        width={360}
+        height={220}
+        hideLegend
+        xAxis={[{ data: months }]}
+        series={[{ label: "Views", data: [4, 3, 5] }]}
+        renderTooltip={(hover) => <p>{hover.category} custom</p>}
+      />,
+    );
+    fireEvent.mouseEnter(container.querySelector(".spk-chart-mark")!);
+    expect(screen.getByText("Jan custom")).toBeInTheDocument();
+  });
 });

package/src/composites/cartesian-charts.tsx

@@ -33,6 +33,14 @@ import {
   type ChartHover,
 } from "./chart-ui";
 import { ChartContainer } from "./chart-composition";
+import {
+  bindChartMark,
+  seriesItemColor,
+  type ChartItemEvent,
+  type ChartMarkRenderContext,
+  type ChartReferenceLine,
+  type ChartTooltipRenderer,
+} from "./chart-interaction";
 import { ScatterWebGLLayer } from "./ScatterWebGL";
 import {
   nearestScatterHit,
@@ -49,6 +57,8 @@ export type NumericSeries = {
   data?: Array<number | null>;
   dataKey?: string;
   color?: string;
+  /** Per-category colors; each entry falls back to `color`. */
+  itemColors?: Array<string | null | undefined>;
   stack?: string;
   area?: boolean;
   curve?: ChartCurve;
@@ -75,6 +85,12 @@ export type CartesianChartProps = {
   highlightScope?: import("../lib/charts").HighlightScope;
   animated?: boolean;
   locale?: string;
+  fillHeight?: boolean;
+  onItemClick?: (event: ChartItemEvent) => void;
+  renderTooltip?: ChartTooltipRenderer;
+  renderMark?: (ctx: ChartMarkRenderContext) => ReactNode;
+  referenceLines?: ChartReferenceLine[];
+  showLabels?: boolean;
 };
 
 export type BarChartProps = CartesianChartProps & {
@@ -268,6 +284,12 @@ export function BarChart({
   highlightScope,
   animated,
   locale,
+  fillHeight,
+  onItemClick,
+  renderTooltip,
+  renderMark,
+  referenceLines,
+  showLabels,
 }: BarChartProps) {
   const meta = seriesMeta(series, colors);
 
@@ -287,6 +309,10 @@ export function BarChart({
         margin={margin}
         className={className}
         barGapRatio={barGapRatio}
+        fillHeight={fillHeight}
+        onItemClick={onItemClick}
+        renderTooltip={renderTooltip}
+        showLabels={showLabels}
       />
     );
   }
@@ -315,6 +341,12 @@ export function BarChart({
       highlightScope={highlightScope}
       animated={animated}
       locale={locale}
+      fillHeight={fillHeight}
+      onItemClick={onItemClick}
+      renderTooltip={renderTooltip}
+      renderMark={renderMark}
+      referenceLines={referenceLines}
+      showLabels={showLabels}
     />
   );
 }
@@ -333,6 +365,10 @@ function HorizontalBarChart({
   margin,
   className,
   barGapRatio = 0.15,
+  fillHeight,
+  onItemClick,
+  renderTooltip,
+  showLabels,
 }: BarChartProps) {
   const categories = categoryLabels(xAxis?.[0], series[0]?.data?.length ?? 0);
   const domain = numericDomain(series, Boolean(stacked), yAxis?.[0]);
@@ -349,11 +385,13 @@ function HorizontalBarChart({
       className={className}
       width={width}
       height={height}
-      margin={margin ?? { top: 16, right: 16, bottom: 28, left: 72 }}
+      fillHeight={fillHeight}
+      margin={margin ?? { top: 16, right: showLabels ? 48 : 16, bottom: 28, left: 72 }}
       legend={hideLegend ? undefined : meta}
       hiddenIds={hidden}
       onToggleSeries={toggle}
       hover={hover}
+      renderTooltip={renderTooltip}
       aria-label={`Bar chart of ${meta.map((s) => s.label).join(", ")}`}
     >
       {({ width: w, height: h, m }) => {
@@ -423,22 +461,42 @@ function HorizontalBarChart({
                 }
                 const x = Math.min(x1, x2);
                 const barW = Math.max(1, Math.abs(x2 - x1));
+                const color = seriesItemColor(info.color, item.itemColors, i);
+                const event: ChartItemEvent = {
+                  seriesId: info.id,
+                  seriesLabel: info.label,
+                  dataIndex: i,
+                  category: categories[i] ?? i,
+                  value,
+                  color,
+                };
                 return (
-                  <path
-                    key={`${info.id}-${i}`}
-                    className="spk-chart-mark"
-                    d={roundedRectPath(x, y, barW, stacked ? yScale.bandwidth : barH, borderRadius)}
-                    fill={info.color}
-                    onMouseEnter={(event) =>
-                      setHover({
-                        x: event.nativeEvent.offsetX,
-                        y: event.nativeEvent.offsetY,
-                        title: String(categories[i]),
-                        items: [{ color: info.color, label: info.label, value: formatSeriesValue(value) }],
-                      })
-                    }
-                    onMouseLeave={clear}
-                  />
+                  <g key={`${info.id}-${i}`}>
+                    <path
+                      d={roundedRectPath(x, y, barW, stacked ? yScale.bandwidth : barH, borderRadius)}
+                      fill={color}
+                      {...bindChartMark({
+                        event,
+                        hover: {
+                          title: String(categories[i]),
+                          items: [{ color, label: info.label, value: formatSeriesValue(value) }],
+                        },
+                        onItemClick,
+                        setHover,
+                        clearHover: clear,
+                      })}
+                    />
+                    {showLabels ? (
+                      <text
+                        className="spk-chart-label"
+                        x={Math.max(x1, x2) + 6}
+                        y={y + (stacked ? yScale.bandwidth : barH) / 2}
+                        dominantBaseline="middle"
+                      >
+                        {formatSeriesValue(value)}
+                      </text>
+                    ) : null}
+                  </g>
                 );
               });
             })}
@@ -471,6 +529,11 @@ export function LineChart({
   highlightScope,
   animated,
   locale,
+  fillHeight,
+  onItemClick,
+  renderTooltip,
+  renderMark,
+  referenceLines,
 }: LineChartProps) {
   const meta = seriesMeta(series, colors);
   const stackedAreas = stacked && (area || series.some((item) => item.area || item.type === "area"));
@@ -501,6 +564,11 @@ export function LineChart({
       highlightScope={highlightScope}
       animated={animated}
       locale={locale}
+      fillHeight={fillHeight}
+      onItemClick={onItemClick}
+      renderTooltip={renderTooltip}
+      renderMark={renderMark}
+      referenceLines={referenceLines}
     />
   );
 }

package/src/composites/chart-composition.test.tsx

@@ -50,4 +50,19 @@ describe("chart-composition", () => {
     expect(container.querySelector('[data-slot="area-plot"]')).toBeTruthy();
     expect(container.querySelectorAll('[data-slot="area-plot"] path').length).toBeGreaterThanOrEqual(2);
   });
+
+  it("draws reference lines from ChartContainer", () => {
+    const { container } = render(
+      <ChartContainer
+        width={360}
+        height={220}
+        hideLegend
+        xAxis={[{ data: ["Jan", "Feb"] }]}
+        series={[{ type: "line", label: "Gap", data: [3, 5] }]}
+        referenceLines={[{ y: 4, label: "Capacity" }]}
+      />,
+    );
+    expect(container.querySelector('[data-slot="chart-reference-lines"]')).toBeTruthy();
+    expect(screen.getByText("Capacity")).toBeInTheDocument();
+  });
 });