@spatika/react 1.4.0 → 1.6.0

package/skills/spatika-ui/SKILL.md

@@ -30,12 +30,30 @@ export function App() {
 
 - Import `@spatika/tokens/styles.css` before any component
 - Wrap the tree in `SpatikaThemeProvider`
-- Themes: `mukta` | `neelam` | `usha` | `sandhya`
+- Themes: `mukta` | `neelam` | `usha` | `sandhya`. Brand palettes: `createTheme` + `customThemes`
 - Prefer composites over restyling primitives
 - Token CSS variables only — no hardcoded hex
 - `size="touch"` on mobile primary actions
 - Never `transition-all` on glass
 
+## Customize
+
+```tsx
+import { Button, SpatikaThemeProvider, createTheme } from "@spatika/react";
+
+const brand = createTheme({
+  id: "brand",
+  extends: "mukta",
+  palette: { primary: "#7c3aed", primaryForeground: "#ffffff", ring: "#7c3aed" },
+});
+
+<SpatikaThemeProvider defaultTheme="brand" customThemes={[brand]}>
+  <Button>Brand</Button>
+</SpatikaThemeProvider>
+```
+
+Breakpoints: `BREAKPOINTS` (`xs` 0 / `sm` 640 / `md` 768 / `lg` 1024 / `xl` 1280). `Grid` `xs`–`xl`, `useIsMobile()`, `useBreakpoint()`. Guide: https://spatika.sweyam.com/docs/customize.md
+
 ## Pick a component
 
 | Need | Use |
@@ -51,10 +69,10 @@ export function App() {
 | Empty | `EmptyState` |
 | Modal | `Dialog` |
 | Toasts | `Toaster` + `useToast` |
-| Chart | `BarChart` / `LineChart` / `ChartContainer` |
+| Chart | `BarChart` / `LineChart` / `ChartContainer` from `@spatika/charts` |
 | 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.
+Charts: install `@spatika/charts` (re-exported from `@spatika/react`). `onItemClick` for mark navigation, `syncId` to link hover across plots, `itemColors` for per-bar tints (inline fill so theme CSS cannot override), `renderTooltip` / `renderMark` for host chrome, `referenceLines` / `referenceAreas` for capacity guides, `fillHeight` or `ResponsiveContainer` when the parent sets height. Pie radii accept `"42%"`. Horizontal bars size the left gutter from category labels. Line/area series accept `strokeDasharray` and `connectNulls`. `yAxis.valueFormatter` formats ticks; `yAxis.reversed` flips the domain. `xAxis.tickAngle` rotates category labels. `stackOffset="expand"` is 100% stacked. `legendPosition`, `loading`, and `emptyText` cover layout and fetch states. Bar charts accept `showBarBackground`. Pie `labelLine` draws outside labels. SparkLineChart hover takes optional `labels`.
 
 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.
 
@@ -95,6 +113,7 @@ import { Home, Search, User } from "lucide-react";
 
 ## Next
 
-1. Fetch the component markdown: `https://spatika.sweyam.com/docs/{slug}.md`
-2. Read prop types from `node_modules/@spatika/react/dist/index.d.ts`
-3. Icons in examples use `lucide-react`
+1. Fetch the customize guide: `https://spatika.sweyam.com/docs/customize.md`
+2. Fetch the component markdown: `https://spatika.sweyam.com/docs/{slug}.md`
+3. Read prop types from `node_modules/@spatika/react/dist/index.d.ts`
+4. Icons in examples use `lucide-react`

package/src/composites/EventCalendar.test.tsx

@@ -0,0 +1,293 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { EventCalendar } from "./EventCalendar";
+import type { SchedulerEvent, SchedulerResource } from "../lib/scheduler";
+
+const resources: SchedulerResource[] = [
+  { id: "work", title: "Work", color: "violet" },
+  { id: "health", title: "Health", color: "teal" },
+];
+
+const events: SchedulerEvent[] = [
+  {
+    id: "run",
+    title: "Morning Run",
+    start: "2026-08-03T07:00:00",
+    end: "2026-08-03T07:45:00",
+    resourceId: "health",
+  },
+  {
+    id: "bday",
+    title: "Alice's Birthday",
+    start: "2026-08-06",
+    end: "2026-08-08",
+    allDay: true,
+    resourceId: "work",
+    color: "rose",
+  },
+  {
+    id: "review",
+    title: "Design Review",
+    start: "2026-08-09T14:00:00",
+    end: "2026-08-09T16:00:00",
+    resourceId: "work",
+  },
+];
+
+describe("EventCalendar", () => {
+  it("renders the month heading, weekday labels, and events", () => {
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        resources={resources}
+        locale="en-US"
+      />,
+    );
+    expect(screen.getByRole("heading", { name: /August 2026/i })).toBeInTheDocument();
+    expect(screen.getByText(/Sun/)).toBeInTheDocument();
+    expect(screen.getByText("Morning Run")).toBeInTheDocument();
+    expect(screen.getByText("Alice's Birthday")).toBeInTheDocument();
+    expect(screen.getByText("Work")).toBeInTheDocument();
+  });
+
+  it("jumps to today from the toolbar", async () => {
+    const user = userEvent.setup();
+    const onDateChange = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2025, 0, 1)}
+        onDateChange={onDateChange}
+        events={events}
+      />,
+    );
+    await user.click(screen.getByRole("button", { name: "Today" }));
+    expect(onDateChange).toHaveBeenCalled();
+    const next = onDateChange.mock.calls[0][0] as Date;
+    const now = new Date();
+    expect(next.getFullYear()).toBe(now.getFullYear());
+    expect(next.getMonth()).toBe(now.getMonth());
+  });
+
+  it("fires onEventClick for a timed event", async () => {
+    const user = userEvent.setup();
+    const onEventClick = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        resources={resources}
+        locale="en-US"
+        onEventClick={onEventClick}
+      />,
+    );
+    await user.click(screen.getByText("Morning Run"));
+    expect(onEventClick).toHaveBeenCalledWith(expect.objectContaining({ id: "run" }));
+  });
+
+  it("switches to week view from the menu", async () => {
+    const user = userEvent.setup();
+    render(
+      <EventCalendar defaultDate={new Date(2026, 7, 15)} events={events} locale="en-US" />,
+    );
+    await user.click(screen.getByRole("button", { name: /month/i }));
+    await user.click(screen.getByRole("menuitem", { name: "Week" }));
+    expect(screen.getByRole("heading", { name: /2026/ })).toBeInTheDocument();
+  });
+
+  it("lists events in agenda view", () => {
+    render(
+      <EventCalendar
+        defaultView="agenda"
+        defaultDate={new Date(2026, 7, 3)}
+        events={events}
+        locale="en-US"
+      />,
+    );
+    expect(screen.getByRole("heading", { name: /Aug 3/ })).toBeInTheDocument();
+    expect(screen.getAllByText("No events").length).toBeGreaterThan(0);
+    expect(screen.getByText("Morning Run")).toBeInTheDocument();
+    expect(screen.getAllByText("Alice's Birthday").length).toBeGreaterThan(0);
+  });
+
+  it("opens the editor and saves title changes", async () => {
+    const user = userEvent.setup();
+    const onEventChange = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        resources={resources}
+        locale="en-US"
+        onEventChange={onEventChange}
+      />,
+    );
+    await user.click(screen.getByText("Morning Run"));
+    const title = screen.getByRole("textbox", { name: /title/i });
+    await user.clear(title);
+    await user.type(title, "Jog");
+    await user.click(screen.getByRole("button", { name: "Save" }));
+    expect(onEventChange).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "run" }),
+      expect.objectContaining({ title: "Jog" }),
+    );
+  });
+
+  it("creates an event from a day slot", async () => {
+    const user = userEvent.setup();
+    const onEventCreate = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        locale="en-US"
+        onEventCreate={onEventCreate}
+      />,
+    );
+    await user.click(screen.getByRole("button", { name: "15" }));
+    expect(screen.getByRole("heading", { name: "New event" })).toBeInTheDocument();
+    await user.type(screen.getByRole("textbox", { name: /title/i }), "Focus time");
+    await user.click(screen.getByRole("button", { name: "Save" }));
+    expect(onEventCreate).toHaveBeenCalledWith(expect.objectContaining({ title: "Focus time" }));
+  });
+
+  it("skips the built-in editor when showEventEditor is false", async () => {
+    const user = userEvent.setup();
+    const onEventClick = vi.fn();
+    const onSlotClick = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        resources={resources}
+        locale="en-US"
+        showEventEditor={false}
+        onEventClick={onEventClick}
+        onSlotClick={onSlotClick}
+      />,
+    );
+    await user.click(screen.getByText("Morning Run"));
+    expect(onEventClick).toHaveBeenCalledWith(expect.objectContaining({ id: "run" }));
+    expect(screen.queryByRole("heading", { name: /event/i })).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "15" }));
+    expect(onSlotClick).toHaveBeenCalled();
+    expect(screen.queryByRole("heading", { name: "New event" })).not.toBeInTheDocument();
+  });
+
+  it("renders custom event chips and toolbar", async () => {
+    const user = userEvent.setup();
+    const onDateChange = vi.fn();
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        resources={resources}
+        locale="en-US"
+        showEventEditor={false}
+        showPreferences={false}
+        toolbarTrailing={<button type="button">Jump year</button>}
+        renderEvent={(event) => <span>★ {event.title}</span>}
+        renderToolbar={({ title, onToday }) => (
+          <div>
+            <p>{title}</p>
+            <button type="button" onClick={onToday}>
+              Jump today
+            </button>
+          </div>
+        )}
+        onDateChange={onDateChange}
+      />,
+    );
+    expect(screen.getByText("★ Morning Run")).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Preferences" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Jump year" })).not.toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Jump today" }));
+    expect(onDateChange).toHaveBeenCalled();
+  });
+
+  it("keeps toolbarTrailing on the default toolbar", () => {
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        locale="en-US"
+        showPreferences={false}
+        toolbarTrailing={<button type="button">Jump year</button>}
+      />,
+    );
+    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("keeps adjacent-month day numbers at full muted contrast", () => {
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={[]}
+        locale="en-US"
+        showPreferences={false}
+      />,
+    );
+    const julyDay = document.querySelector('[data-scheduler-day="2026-07-26"] button');
+    expect(julyDay).toBeTruthy();
+    expect(julyDay?.className).toMatch(/text-muted-foreground/);
+    expect(julyDay?.className).not.toMatch(/\/70/);
+  });
+
+  it("sizes month event chips for touch-friendly targets", () => {
+    render(
+      <EventCalendar
+        defaultDate={new Date(2026, 7, 15)}
+        events={events}
+        locale="en-US"
+        showPreferences={false}
+        showEventEditor={false}
+      />,
+    );
+    const birthday = screen.getByRole("button", { name: "Alice's Birthday" });
+    expect(birthday.className).toMatch(/min-h-6/);
+    const timed = screen.getByRole("button", { name: /Morning Run/i });
+    expect(timed.className).toMatch(/min-h-6/);
+  });
+
+  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);
+  });
+});

package/src/composites/EventCalendar.tsx

@@ -666,7 +666,7 @@ function MonthGrid({
                             "flex size-7 items-center justify-center rounded-full text-xs font-bold",
                             isToday && "bg-primary text-primary-foreground",
                             !isToday && inMonth && "text-foreground hover:bg-muted/50",
-                            !isToday && !inMonth && "text-muted-foreground/70",
+                            !isToday && !inMonth && "text-muted-foreground",
                           )}
                         >
                           {day.getDate()}
@@ -688,7 +688,7 @@ function MonthGrid({
                         >
                           {renderEventTrigger(
                             slot.event,
-                            "flex h-5 w-full items-center truncate rounded-md px-1.5 text-[11px] font-semibold leading-none",
+                            "flex min-h-6 w-full items-center truncate rounded-md px-1.5 text-[11px] font-semibold leading-none",
                             slot.event.title,
                             { variant: "month-bar" },
                           )}
@@ -723,7 +723,7 @@ function MonthGrid({
                           <div key={occurrenceKey(event)} className="min-w-0">
                             {renderEventTrigger(
                               event,
-                              "flex w-full min-w-0 items-center gap-1 rounded-sm px-0.5 py-0.5 text-left text-[11px] leading-tight text-foreground hover:bg-muted/40",
+                              "flex min-h-6 w-full min-w-0 items-center gap-1 rounded-sm px-0.5 py-0.5 text-left text-[11px] leading-tight text-foreground hover:bg-muted/40",
                               <>
                                 <span
                                   className="size-1.5 shrink-0 rounded-full"

package/src/composites/RichTextEditor.test.tsx

@@ -0,0 +1,51 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { RichTextEditor } from "./RichTextEditor";
+
+vi.mock("@spatika/editor", () => ({
+  SpatikaEditor: ({
+    value,
+    placeholder,
+    heightClassName,
+    toolbar,
+  }: {
+    value: string;
+    placeholder?: string;
+    heightClassName?: string;
+    toolbar?: Record<string, unknown>;
+  }) => (
+    <div
+      data-testid="spatika-editor-shim"
+      data-value={value}
+      data-placeholder={placeholder}
+      data-height={heightClassName}
+      data-toolbar={JSON.stringify(toolbar)}
+    />
+  ),
+}));
+
+describe("RichTextEditor", () => {
+  it("delegates to SpatikaEditor with a compact legacy toolbar", () => {
+    render(
+      <RichTextEditor
+        value="<p>Note</p>"
+        placeholder="Write something…"
+        minHeightClassName="min-h-40"
+      />,
+    );
+    const shim = screen.getByTestId("spatika-editor-shim");
+    expect(shim).toHaveAttribute("data-value", "<p>Note</p>");
+    expect(shim).toHaveAttribute("data-placeholder", "Write something…");
+    expect(shim).toHaveAttribute("data-height", "min-h-40");
+    expect(shim).toHaveAttribute(
+      "data-toolbar",
+      JSON.stringify({
+        layout: "compact",
+        textStyle: false,
+        alignment: false,
+        insert: false,
+        ai: false,
+      }),
+    );
+  });
+});

package/src/composites/RichTextEditor.tsx

@@ -1,13 +1,8 @@
-import { useEffect, useRef } from "react";
-import {
-  Bold,
-  Italic,
-  List,
-  ListOrdered,
-  Underline as UnderlineIcon,
-} from "lucide-react";
-import { cn } from "../lib/cn";
-import { Button } from "../primitives/Button";
+/**
+ * @deprecated Use `SpatikaEditor` from `@spatika/react` instead.
+ * Import `@spatika/editor/styles.css` alongside `@spatika/tokens/styles.css`.
+ */
+import { SpatikaEditor } from "@spatika/editor";
 
 export type RichTextEditorProps = {
   value?: string;
@@ -17,10 +12,7 @@ export type RichTextEditorProps = {
   minHeightClassName?: string;
 };
 
-/**
- * Lightweight rich-text surface (contenteditable) for notes and captions.
- * Pair with TipTap or another full editor in your app when you need tables or advanced media.
- */
+/** @deprecated Use `SpatikaEditor` for full rich text editing with Tiptap. */
 export function RichTextEditor({
   value = "",
   onChange,
@@ -28,76 +20,20 @@ export function RichTextEditor({
   className,
   minHeightClassName = "min-h-40",
 }: RichTextEditorProps) {
-  const ref = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (ref.current && value !== ref.current.innerHTML) {
-      ref.current.innerHTML = value;
-    }
-  }, [value]);
-
-  const exec = (command: string) => {
-    document.execCommand(command);
-    onChange?.(ref.current?.innerHTML ?? "");
-    ref.current?.focus();
-  };
-
   return (
-    <div
-      data-slot="rich-text-editor"
-      className={cn(
-        "overflow-hidden rounded-[var(--radius-card)] border border-border/50 bg-input-background",
-        className,
-      )}
-    >
-      <div className="flex flex-wrap gap-1 border-b border-border/40 bg-muted/30 p-1.5">
-        <Button type="button" variant="ghost" size="icon" aria-label="Bold" onClick={() => exec("bold")}>
-          <Bold className="size-4" />
-        </Button>
-        <Button type="button" variant="ghost" size="icon" aria-label="Italic" onClick={() => exec("italic")}>
-          <Italic className="size-4" />
-        </Button>
-        <Button
-          type="button"
-          variant="ghost"
-          size="icon"
-          aria-label="Underline"
-          onClick={() => exec("underline")}
-        >
-          <UnderlineIcon className="size-4" />
-        </Button>
-        <Button
-          type="button"
-          variant="ghost"
-          size="icon"
-          aria-label="Bullet list"
-          onClick={() => exec("insertUnorderedList")}
-        >
-          <List className="size-4" />
-        </Button>
-        <Button
-          type="button"
-          variant="ghost"
-          size="icon"
-          aria-label="Numbered list"
-          onClick={() => exec("insertOrderedList")}
-        >
-          <ListOrdered className="size-4" />
-        </Button>
-      </div>
-      <div
-        ref={ref}
-        role="textbox"
-        aria-multiline="true"
-        contentEditable
-        suppressContentEditableWarning
-        data-placeholder={placeholder}
-        className={cn(
-          "px-3 py-2 text-sm outline-none empty:before:text-muted-foreground empty:before:content-[attr(data-placeholder)]",
-          minHeightClassName,
-        )}
-        onInput={() => onChange?.(ref.current?.innerHTML ?? "")}
-      />
-    </div>
+    <SpatikaEditor
+      value={value}
+      onChange={(html) => onChange?.(html)}
+      placeholder={placeholder}
+      className={className}
+      heightClassName={minHeightClassName}
+      toolbar={{
+        layout: "compact",
+        textStyle: false,
+        alignment: false,
+        insert: false,
+        ai: false,
+      }}
+    />
   );
 }

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

@@ -0,0 +1,21 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { SparkLineChart } from "@spatika/charts";
+
+/**
+ * `chart-ui` moved to `@spatika/charts`. This file keeps colocated coverage
+ * next to the old path so the extract stays test-paired.
+ */
+describe("chart-ui (re-exported via @spatika/charts)", () => {
+  it("still renders a sparkline frame that uses ChartFrame", () => {
+    const { container } = render(
+      <SparkLineChart data={[1, 4, 2]} width={120} height={36} />,
+    );
+    expect(container.querySelector('[data-slot="sparkline"]')).toBeTruthy();
+  });
+
+  it("does not paint a tooltip when nothing is hovered", () => {
+    render(<SparkLineChart data={[1, 4, 2]} width={120} height={36} />);
+    expect(document.querySelector('[role="tooltip"]')).toBeNull();
+  });
+});