@spatika/react 1.3.1 → 1.5.0

package/dist/primitives/Grid.d.ts

@@ -19,12 +19,13 @@ export type GridProps = React.ComponentPropsWithoutRef<"div"> & {
     sm?: number | "auto";
     md?: number | "auto";
     lg?: number | "auto";
+    xl?: number | "auto";
     size?: number | "grow";
 };
 /**
  * 12-column CSS grid. Use `container` on the parent and breakpoint spans on items.
  */
-declare function Grid({ container, item: _item, spacing, columns: _columns, xs, sm, md, lg, size, className, ...props }: GridProps): React.JSX.Element;
+declare function Grid({ container, item: _item, spacing, columns: _columns, xs, sm, md, lg, xl, size, className, ...props }: GridProps): React.JSX.Element;
 declare namespace Grid {
     var displayName: string;
 }

package/dist/primitives/Grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Grid.d.ts","sourceRoot":"","sources":["../../src/primitives/Grid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,wBAAwB,CAAC,KAAK,CAAC,GAAG;IAC7D,SAAS,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,GAAG;gBAPK,KAAK,CAAC,WAAW;cACnB,OAAO;wCAWlB,CAAC;AA6BF,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,wBAAwB,CAAC,KAAK,CAAC,GAAG;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,EAAE,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAOF;;GAEG;AACH,iBAAS,IAAI,CAAC,EACZ,SAAS,EACT,IAAI,EAAE,KAAK,EACX,OAAW,EACX,OAAO,EAAE,QAAa,EACtB,EAAE,EACF,EAAE,EACF,EAAE,EACF,EAAE,EACF,IAAI,EACJ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,SAAS,qBAmBX;kBA/BQ,IAAI;;;AAkCb,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"Grid.d.ts","sourceRoot":"","sources":["../../src/primitives/Grid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,wBAAwB,CAAC,KAAK,CAAC,GAAG;IAC7D,SAAS,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,GAAG;gBAPK,KAAK,CAAC,WAAW;cACnB,OAAO;wCAWlB,CAAC;AA6BF,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,wBAAwB,CAAC,KAAK,CAAC,GAAG;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,EAAE,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAcF;;GAEG;AACH,iBAAS,IAAI,CAAC,EACZ,SAAS,EACT,IAAI,EAAE,KAAK,EACX,OAAW,EACX,OAAO,EAAE,QAAa,EACtB,EAAE,EACF,EAAE,EACF,EAAE,EACF,EAAE,EACF,EAAE,EACF,IAAI,EACJ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,SAAS,qBAoBX;kBAjCQ,IAAI;;;AAoCb,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC"}

package/dist/primitives/Grid.js

@@ -39,12 +39,20 @@ function spanFor(value) {
         return undefined;
     return spanClass[value] ?? "col-span-12";
 }
+function prefixedSpan(prefix, value) {
+    if (typeof value !== "number")
+        return undefined;
+    const base = spanClass[value];
+    if (!base)
+        return undefined;
+    return base.replace("col-span", `${prefix}:col-span`);
+}
 /**
  * 12-column CSS grid. Use `container` on the parent and breakpoint spans on items.
  */
-function Grid({ container, item: _item, spacing = 2, columns: _columns = 12, xs, sm, md, lg, size, className, ...props }) {
+function Grid({ container, item: _item, spacing = 2, columns: _columns = 12, xs, sm, md, lg, xl, size, className, ...props }) {
     const span = spanFor(typeof size === "number" ? size : xs);
-    return (_jsx("div", { "data-slot": "grid", "data-container": container ? "" : undefined, "data-item": _item || !container ? "" : undefined, className: cn(container && "grid grid-cols-12", container && (gapClass[spacing] ?? "gap-2"), !container && (span ?? (size === "grow" ? "col-span-12" : "col-span-12")), sm && typeof sm === "number" && spanClass[sm]?.replace("col-span", "sm:col-span"), md && typeof md === "number" && spanClass[md]?.replace("col-span", "md:col-span"), lg && typeof lg === "number" && spanClass[lg]?.replace("col-span", "lg:col-span"), className), ...props }));
+    return (_jsx("div", { "data-slot": "grid", "data-container": container ? "" : undefined, "data-item": _item || !container ? "" : undefined, className: cn(container && "grid grid-cols-12", container && (gapClass[spacing] ?? "gap-2"), !container && (span ?? (size === "grow" ? "col-span-12" : "col-span-12")), prefixedSpan("sm", sm), prefixedSpan("md", md), prefixedSpan("lg", lg), prefixedSpan("xl", xl), className), ...props }));
 }
 Grid.displayName = "Grid";
 export { Box, Grid };

package/dist/primitives/IconButton.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const iconButtonVariants: (props?: ({
     variant?: "filled" | "outline" | "ghost" | "glass" | null | undefined;
-    size?: "touch" | "sm" | "lg" | "md" | null | undefined;
+    size?: "touch" | "sm" | "md" | "lg" | null | undefined;
     shape?: "circular" | "rounded" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type IconButtonProps = React.ComponentPropsWithoutRef<"button"> & VariantProps<typeof iconButtonVariants> & {
@@ -13,7 +13,7 @@ export type IconButtonProps = React.ComponentPropsWithoutRef<"button"> & Variant
  */
 declare const IconButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
     variant?: "filled" | "outline" | "ghost" | "glass" | null | undefined;
-    size?: "touch" | "sm" | "lg" | "md" | null | undefined;
+    size?: "touch" | "sm" | "md" | "lg" | null | undefined;
     shape?: "circular" | "rounded" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
     asChild?: boolean;

package/dist/primitives/NativeSelect.d.ts

@@ -1,7 +1,16 @@
 import * as React from "react";
+import { type NativeSelectSize } from "../lib/chips";
+export type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & {
+    /**
+     * Visual size. `default` stays full-width for forms.
+     * `sm` is a compact pill for toolbars. `touch` is a 44px target.
+     * Omits the native HTML `size` (visible option rows) to avoid the clash.
+     */
+    size?: NativeSelectSize;
+};
 /**
  * Styled native `<select>` — prefer compound `Select` for custom menus.
  */
-declare const NativeSelect: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.SelectHTMLAttributes<HTMLSelectElement>, HTMLSelectElement>, "ref"> & React.RefAttributes<HTMLSelectElement>>;
+declare const NativeSelect: React.ForwardRefExoticComponent<Omit<NativeSelectProps, "ref"> & React.RefAttributes<HTMLSelectElement>>;
 export { NativeSelect };
 //# sourceMappingURL=NativeSelect.d.ts.map

package/dist/primitives/NativeSelect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeSelect.d.ts","sourceRoot":"","sources":["../../src/primitives/NativeSelect.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;GAEG;AACH,QAAA,MAAM,YAAY,kLAWjB,CAAC;AAGF,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"NativeSelect.d.ts","sourceRoot":"","sources":["../../src/primitives/NativeSelect.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,GAAG;IAC7E;;;;OAIG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,YAAY,0GAYjB,CAAC;AAGF,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/primitives/NativeSelect.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../lib/cn";
-import { nativeSelectClass } from "../lib/chips";
+import { nativeSelectSizeClass } from "../lib/chips";
 /**
  * Styled native `<select>` — prefer compound `Select` for custom menus.
  */
-const NativeSelect = React.forwardRef(({ className, children, ...props }, ref) => (_jsx("select", { ref: ref, "data-slot": "native-select", className: cn(nativeSelectClass, "mt-0", className), ...props, children: children })));
+const NativeSelect = React.forwardRef(({ className, size = "default", children, ...props }, ref) => (_jsx("select", { ref: ref, "data-slot": "native-select", "data-size": size, className: cn(nativeSelectSizeClass(size), className), ...props, children: children })));
 NativeSelect.displayName = "NativeSelect";
 export { NativeSelect };

package/dist/primitives/ToggleButton.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const toggleButtonVariants: (props?: ({
-    size?: "sm" | "lg" | "md" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ToggleButtonGroupProps = Omit<React.ComponentPropsWithoutRef<"div">, "onChange" | "value" | "defaultValue"> & {
     exclusive?: boolean;

package/dist/theme/SpatikaThemeProvider.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import { type SpatikaTheme } from "../lib/create-theme";
 import { type ThemeId } from "../lib/themes";
 export type SpatikaThemeContextValue = {
     theme: ThemeId;
@@ -25,12 +26,10 @@ export type SpatikaThemeProviderProps = {
     /** Optional element to theme instead of (or in addition to) document */
     target?: HTMLElement | null;
     className?: string;
+    /** Custom themes from `createTheme`. Switch them with `setTheme(id)`. */
+    customThemes?: readonly SpatikaTheme[];
 };
-/**
- * MUI-style theme provider for Spatika.
- * Wraps the app (or a subtree) and applies theme classes / data attributes.
- */
-export declare function SpatikaThemeProvider({ children, theme: themeProp, defaultTheme, storageKey, onThemeChange, syncDocument, target, className, }: SpatikaThemeProviderProps): import("react").JSX.Element;
+export declare function SpatikaThemeProvider({ children, theme: themeProp, defaultTheme, storageKey, onThemeChange, syncDocument, target, className, customThemes, }: SpatikaThemeProviderProps): import("react").JSX.Element;
 /** Access current theme and setter from `SpatikaThemeProvider`. */
 export declare function useSpatikaTheme(): SpatikaThemeContextValue;
 //# sourceMappingURL=SpatikaThemeProvider.d.ts.map

package/dist/theme/SpatikaThemeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SpatikaThemeProvider.d.ts","sourceRoot":"","sources":["../../src/theme/SpatikaThemeProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAML,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CAC5B,CAAC;AAIF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,EAAE,SAAS,CAAC;IACpB,uBAAuB;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,QAAQ,EACR,KAAK,EAAE,SAAS,EAChB,YAA4B,EAC5B,UAAkB,EAClB,aAAa,EACb,YAAmB,EACnB,MAAM,EACN,SAAS,GACV,EAAE,yBAAyB,+BAyC3B;AAED,mEAAmE;AACnE,wBAAgB,eAAe,IAAI,wBAAwB,CAM1D"}
+{"version":3,"file":"SpatikaThemeProvider.d.ts","sourceRoot":"","sources":["../../src/theme/SpatikaThemeProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EASL,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CAC5B,CAAC;AAIF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,EAAE,SAAS,CAAC;IACpB,uBAAuB;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,YAAY,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC,CAAC;AAgBF,wBAAgB,oBAAoB,CAAC,EACnC,QAAQ,EACR,KAAK,EAAE,SAAS,EAChB,YAA4B,EAC5B,UAAkB,EAClB,aAAa,EACb,YAAmB,EACnB,MAAM,EACN,SAAS,EACT,YAAkC,GACnC,EAAE,yBAAyB,+BA+C3B;AAED,mEAAmE;AACnE,wBAAgB,eAAe,IAAI,wBAAwB,CAM1D"}

package/dist/theme/SpatikaThemeProvider.js

@@ -1,32 +1,47 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useState, } from "react";
-import { applyTheme, DEFAULT_THEME, readStoredTheme, THEME_IDS, writeStoredTheme, } from "../lib/themes";
+import { cn } from "../lib/cn";
+import { findCustomTheme, injectCustomThemeStyles, } from "../lib/create-theme";
+import { applyTheme, DEFAULT_THEME, isDarkTheme, isThemeId, readStoredTheme, THEME_IDS, writeStoredTheme, } from "../lib/themes";
 const SpatikaThemeContext = createContext(null);
+function baseThemeClass(theme, custom) {
+    const base = custom?.extends ?? (isThemeId(theme) ? theme : DEFAULT_THEME);
+    return base === DEFAULT_THEME ? undefined : base;
+}
 /**
- * MUI-style theme provider for Spatika.
+ * Theme provider for Spatika.
  * Wraps the app (or a subtree) and applies theme classes / data attributes.
  */
-export function SpatikaThemeProvider({ children, theme: themeProp, defaultTheme = DEFAULT_THEME, storageKey = false, onThemeChange, syncDocument = true, target, className, }) {
-    const [uncontrolled, setUncontrolled] = useState(() => readStoredTheme(storageKey) ?? defaultTheme);
+const EMPTY_CUSTOM_THEMES = [];
+export function SpatikaThemeProvider({ children, theme: themeProp, defaultTheme = DEFAULT_THEME, storageKey = false, onThemeChange, syncDocument = true, target, className, customThemes = EMPTY_CUSTOM_THEMES, }) {
+    const customIds = useMemo(() => customThemes.map((item) => item.id), [customThemes]);
+    const [uncontrolled, setUncontrolled] = useState(() => readStoredTheme(storageKey, customIds) ?? defaultTheme);
     const theme = themeProp ?? uncontrolled;
+    const custom = findCustomTheme(theme, customThemes);
     const setTheme = useCallback((next) => {
         if (themeProp === undefined)
             setUncontrolled(next);
         onThemeChange?.(next);
     }, [onThemeChange, themeProp]);
     useLayoutEffect(() => {
+        injectCustomThemeStyles(customThemes);
         if (syncDocument)
-            applyTheme(theme);
+            applyTheme(theme, undefined, custom);
         if (target)
-            applyTheme(theme, target);
+            applyTheme(theme, target, custom);
         writeStoredTheme(storageKey, theme);
-    }, [theme, syncDocument, target, storageKey]);
-    const value = useMemo(() => ({
-        theme,
-        setTheme,
-        themes: THEME_IDS,
-    }), [theme, setTheme]);
-    return (_jsx(SpatikaThemeContext.Provider, { value: value, children: _jsx("div", { className: className, "data-spk-theme": theme, "data-slot": "spatika-theme-provider", children: children }) }));
+    }, [theme, syncDocument, target, storageKey, custom, customThemes]);
+    const value = useMemo(() => {
+        const extras = customThemes.map((item) => item.id).filter((id) => !isThemeId(id));
+        return {
+            theme,
+            setTheme,
+            themes: extras.length ? [...THEME_IDS, ...extras] : THEME_IDS,
+        };
+    }, [theme, setTheme, customThemes]);
+    const dark = custom ? custom.colorScheme === "dark" : isDarkTheme(theme);
+    const themeClass = baseThemeClass(theme, custom);
+    return (_jsx(SpatikaThemeContext.Provider, { value: value, children: _jsx("div", { className: cn(className, themeClass), "data-spk-theme": theme, "data-slot": "spatika-theme-provider", style: { colorScheme: dark ? "dark" : "light" }, children: children }) }));
 }
 /** Access current theme and setter from `SpatikaThemeProvider`. */
 export function useSpatikaTheme() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spatika/react",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "license": "MIT",
   "description": "Spatika UI — glass React primitives and composites for production apps",
   "homepage": "https://spatika.sweyam.com",
@@ -59,7 +59,9 @@
     "react-dom": "^18.2.0 || ^19.0.0"
   },
   "dependencies": {
-    "@spatika/tokens": "1.3.1",
+    "@spatika/charts": "1.5.0",
+    "@spatika/editor": "1.5.0",
+    "@spatika/tokens": "1.5.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",

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,9 +69,13 @@ export function App() {
 | Empty | `EmptyState` |
 | Modal | `Dialog` |
 | Toasts | `Toaster` + `useToast` |
-| Chart | `BarChart` / `LineChart` / `ChartContainer` |
+| Chart | `BarChart` / `LineChart` / `ChartContainer` from `@spatika/charts` |
 | Calendar | `EventCalendar` |
 
+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.
+
 ## App shell
 
 ```tsx
@@ -91,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);
+  });
+});