feat: add dhtmlx-react-scheduler skill

README.md

@@ -27,18 +27,31 @@ Guides AI agents through building and integrating DHTMLX React Gantt in web appl
 - Styling, CSS variables, template-based visual customization
 - Common pitfalls and constraints
 
+### `dhtmlx-react-scheduler`
+
+Guides AI agents through building and integrating DHTMLX React Scheduler in web applications. Covers:
+
+- Package installation (trial and commercial)
+- CSS setup and layout requirements
+- React integration patterns
+- Event state, mapping, and persistence
+- Scheduler views, resources, lightboxes, and conflict checks
+- Styling, CSS variables, template-based visual customization
+- Common pitfalls and constraints
 
 ## Installation
 
 ```bash
 npx skills add DHTMLX/skills --skill dhtmlx-react-gantt
+npx skills add DHTMLX/skills --skill dhtmlx-react-scheduler
 ```
 
 Or copy manually:
 
 ```bash
 git clone https://github.com/DHTMLX/skills
 cp -r skills/dhtmlx-react-gantt ~/.claude/skills/
+cp -r skills/dhtmlx-react-scheduler ~/.claude/skills/
 ```
 
 ## Requirements

dhtmlx-react-scheduler/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: dhtmlx-react-scheduler
+description: >
+  Builds and integrates DHTMLX React Scheduler into React applications. Covers setup, props,
+  templates, themes, data.save, data.batchSave, and
+  React integration patterns for @dhtmlx/trial-react-scheduler and @dhx/react-scheduler.
+  Applies when working with booking calendars, resource scheduling, event CRUD, timeline/day/week/month
+  views, lightboxes, or scheduling conflict checks in React apps — regardless of whether
+  "DHTMLX" is mentioned by name. Provides verified API guidance rather than guessing React Scheduler APIs.
+paths: "**/*.tsx,**/*.jsx,**/*.ts,**/*.js,package.json"
+allowed-tools: Read Grep
+metadata:
+  tags: dhtmlx, scheduler, booking, calendar, resources, events
+---
+
+## Source Of Truth
+
+Use only:
+1. The current project's files, structure, and established patterns
+2. DHTMLX MCP for React Scheduler API details: https://docs.dhtmlx.com/mcp
+3. Official DHTMLX React Scheduler docs as fallback: https://docs.dhtmlx.com/scheduler/integrations/react/
+
+Never invent props, hooks, templates, callback signatures, event names, or backend behavior.
+
+If any React Scheduler API detail is unclear, resolve it through DHTMLX MCP before writing code.
+
+## Preflight
+
+Before writing code, identify:
+- **package**: `@dhtmlx/trial-react-scheduler` or `@dhx/react-scheduler` — check `package.json`, imports, lockfiles
+- **runtime**: React, Next.js (needs `"use client"`), Remix, or other React-based setup
+- **ownership model**: React-managed (default) or Scheduler-managed (large datasets, Scheduler-centric app)
+- **persistence**: local only, `data.save` (default, single-entity), or `data.batchSave` (bulk sync)
+
+## Workflow
+
+1. Confirm the installed DHTMLX React Scheduler package and import path.
+2. Decide the data ownership model before implementing features.
+3. Read only the reference file needed for the task:
+   - React integration/setup: [references/react-integration.md](references/react-integration.md)
+   - CRUD, state, and persistence: [references/data-and-crud.md](references/data-and-crud.md)
+   - Failure cases and guardrails: [references/known-failures.md](references/known-failures.md)
+   - Advanced patterns (views, resources, conflicts, undo/redo): [references/advanced-patterns.md](references/advanced-patterns.md)
+   - Styling, theming, CSS variables, selectors, and template-based visual customization: [references/styling-and-theming.md](references/styling-and-theming.md)
+4. Use DHTMLX MCP before relying on advanced or unfamiliar APIs.
+5. Implement with documented APIs only.
+
+## MCP Server
+
+This skill relies on DHTMLX MCP for API verification. If the `dhtmlx-mcp` tool is not available, ask the user to add it:
+
+Claude Code:
+```bash
+claude mcp add --transport http dhtmlx-mcp https://docs.dhtmlx.com/mcp
+```
+
+Codex:
+```bash
+codex mcp add dhtmlx-mcp --url https://docs.dhtmlx.com/mcp
+```
+
+If MCP is not available, use the official docs at https://docs.dhtmlx.com/scheduler/integrations/react/ as fallback.
+
+## Consult MCP First For
+
+Consult DHTMLX MCP before using or changing:
+- template callbacks you have not already verified
+- advanced props such as `batchSave`, `customLightbox`, `modals`, `view`, or `filter`
+- timeline configuration details and related callback signatures
+- event handler signatures (`on<EventName>`) when behavior is not fully clear
+- theme/skin methods and runtime view-switch behavior via `ref` instance API
+- collision/limit/recurring plugin behavior in combined setups
+
+## Hard Rules
+
+- The Scheduler container must have explicit height.
+- CSS import must match the installed package and be a separate import line.
+- Use the app theme as the single source of truth.
+- Prefer JavaScript `Date` objects for `start_date` and `end_date` in React-managed mode.
+- Normalize date values before persistence.
+- Build backend payloads explicitly from normalized event models.
+- Do not use undocumented internals when a documented prop or ref API exists.
+- Do not mix React-managed props and imperative instance mutations unless synchronization is intentional.
+
+## Quick Checklist
+
+- [ ] Correct package identified
+- [ ] Matching CSS import used
+- [ ] Explicit height provided
+- [ ] Data ownership model chosen
+- [ ] Dates normalized before persistence
+- [ ] Advanced APIs verified with MCP

dhtmlx-react-scheduler/references/advanced-patterns.md

@@ -0,0 +1,53 @@
+# Advanced Patterns
+
+Use this file when implementing custom views, plugins, advanced filtering, undo/redo, or scheduling safeguards.
+
+## Contents
+- Views And Plugins As Optional Features
+- Resource/Section Mapping
+- Undo/Redo With State Management
+- Conflict And Availability Guards
+- Custom Fields And Backend Mapping
+
+## Views And Plugins As Optional Features
+
+When configuring non-trivial custom views:
+- verify required plugin set and view configuration with MCP
+- verify callback signatures and payload shapes with MCP
+
+## Resource/Section Mapping
+
+- keep one canonical event field for section/resource assignment (for example `resource_id`)
+- ensure section keys and event assignment values use the same ID type/format
+- map section labels from persisted data, not hardcoded display-only arrays
+- if unassigned events are supported, keep their behavior explicit in UI and persistence
+- keep row/section mapping deterministic across reloads and refetches
+
+Guardrails:
+- do not silently remap unknown section IDs
+- verify timeline/section configuration details with MCP before implementation
+
+## Undo/Redo With State Management
+
+- use refs to access the latest state snapshot inside `data.save` callbacks — do not rely on render-time closures
+- if using Redux or another external store for Scheduler history, normalize date values before writing to the store (state must be serializable)
+- undo and redo actions must also update persistence — client-only history creates data gaps on reload
+- persist history snapshots when rehydration across sessions is required
+- save or refetch operations must not wipe the undo/redo history stack
+- keep history refs and store state in sync after every mutation
+
+## Conflict And Availability Guards
+
+- run conflict/availability checks before persistence when the app requires scheduling rules
+- typical checks: overlap on the same assignment field (for example `resource_id`), location scope, and business-hours window
+- keep the check path explicit: `candidate event -> checks -> decision -> persist`
+- if conflicts need confirmation, require explicit user confirmation before save
+- if conflicts are blocked, stop the write and keep UI state consistent with persisted state
+
+## Custom Fields And Backend Mapping
+
+- treat custom fields (for example `location_id`, `resource_id`, `service_id`, `status`, `notes`) as app-level schema and keep them explicit in all CRUD paths
+- map backend rows to Scheduler events explicitly (including `start_date` / `end_date` conversion)
+- map Scheduler write payloads to backend payloads explicitly; do not persist raw callback objects
+- keep server-assigned IDs and client temporary IDs synchronized with a deterministic replacement flow
+- if the app has scope constraints (for example location-scoped resources/services), validate them before persistence

dhtmlx-react-scheduler/references/data-and-crud.md

@@ -0,0 +1,90 @@
+# Data And CRUD
+
+Use this file when events, state ownership, or persistence are involved.
+
+## Data Model Essentials
+
+Prefer JavaScript `Date` objects for event date fields in React-managed mode.
+
+Minimum event shape:
+```ts
+interface Event {
+  id: string | number;
+  text: string;
+  start_date: Date;
+  end_date: Date;
+}
+```
+
+When loading from a backend, map rows explicitly into Scheduler event objects. Do not pass raw DB rows straight through.
+
+## Choose The Ownership Model First
+
+For most React apps, use React-managed data:
+- keep `events` in React state or a state manager
+- pass them into `<ReactScheduler />`
+- handle updates with `data.save` or `data.batchSave`
+
+Use Scheduler-managed data only when:
+- datasets are very large
+- mass updates are frequent
+- React does not need to react to every edit
+- the page is primarily Scheduler-centric
+
+## CRUD Default
+
+For normal CRUD, prefer `data.save`.
+
+Pattern:
+```tsx
+<ReactScheduler
+  events={events}
+  data={{
+    save: async (entity, action, item, id) => {
+      // update local state
+      // sync backend
+      // return { id } after creates when backend assigns a real ID
+    },
+  }}
+/>
+```
+
+Strict rules:
+- update state from the latest current snapshot, not stale closure state
+- for `create`, if the backend assigns a real ID, return `{ id: realId }`
+- for `update`, persist only normalized values
+- for `delete`, remove from local state and persistence layer
+- normalize date values before serialization
+- if using temporary IDs, replace them deterministically after persistence
+- build backend payloads explicitly from normalized event models, not from raw callback objects
+
+## Date Formatting And Normalization
+
+Treat `start_date` and `end_date` in persistence callbacks as `Date | string`, and normalize them before backend writes:
+
+```ts
+function toIso(value: Date | string): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error("Invalid date");
+  return date.toISOString();
+}
+```
+
+On backend read, map persisted date strings back into `Date` objects before passing to Scheduler.
+
+## When To Use batchSave
+
+Use `data.batchSave` when:
+- one user action can emit many related changes
+- bulk backend sync is more appropriate than single-event persistence
+- grouped change handling is required
+
+Do not switch to `batchSave` casually. Verify exact behavior and payload shape with MCP first.
+
+## Persistence Guardrails
+
+- Do not persist raw Scheduler callback objects directly.
+- Keep app-level custom fields explicit in mapping (for example `location_id`, `resource_id`, `service_id`).
+- Reject or sanitize writes that violate application constraints before hitting the backend.
+- Keep create/update/delete paths idempotent and deterministic.
+- If the app introduces undo/redo, persistence rules must remain correct after history actions.

dhtmlx-react-scheduler/references/known-failures.md

@@ -0,0 +1,70 @@
+# Known Failures
+
+Use this file when debugging incorrect or flaky DHTMLX React Scheduler integrations.
+
+## 1. Theme Drift
+
+Problem:
+- app shell and Scheduler follow different theme sources
+
+Fix:
+- use one shared app theme source
+- apply Scheduler theme/skin from that source
+- do not introduce separate Scheduler-only theme state
+
+## 2. Date Serialization Bugs
+
+Problem:
+- write handlers receive mixed date shapes (`Date` and/or string)
+- backend writes become inconsistent or invalid
+
+Fix:
+- treat `start_date` and `end_date` as `Date | string`
+- normalize before persistence
+- map backend date strings back to `Date` before passing events to Scheduler
+
+## 3. Stale Callback State
+
+Problem:
+- `data.save` handlers capture old event arrays or old store snapshots
+
+Fix:
+- use refs, functional updates, or current-store snapshots
+- do not build persistence logic from stale render-time closures
+
+## 4. ID Replacement Gaps
+
+Problem:
+- create flow keeps temporary client IDs after backend persistence
+- later update/delete targets the wrong event
+
+Fix:
+- make temp-id -> persisted-id replacement deterministic
+- synchronize replacement in both local state and Scheduler instance data
+
+## 5. Mixed Ownership Bugs
+
+Problem:
+- React props and imperative Scheduler instance mutations both modify events without synchronization
+
+Fix:
+- choose ownership model first
+- if imperative mutations are required, keep React-managed event props synchronized deliberately
+
+## 6. Wrong Template Or Handler Signature
+
+Problem:
+- callback wired with wrong parameter order or wrong payload assumptions
+
+Fix:
+- verify exact documented signature with MCP
+- do not infer callback arguments from memory
+
+## 7. Implicit Height Containers
+
+Problem:
+- Scheduler is mounted into a container without real height
+- rendering is broken or collapsed
+
+Fix:
+- provide explicit container height