Calendar/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Build and Development

• Build TypeScript: npm run build - Compiles TypeScript sources to JavaScript using esbuild
• Watch mode: npm run watch - Continuously compiles TypeScript on file changes
• Clean build: npm run clean - Removes compiled JavaScript files (uses PowerShell on Windows)
• Start server: dotnet run - Starts the ASP.NET Core server on http://localhost:8000

Typical Development Workflow

1. Install dependencies: npm install
2. Build TypeScript: npm run build
3. Start server: dotnet run
4. For active development, run npm run watch in a separate terminal

Architecture Overview

Calendar Plantempus is an event-driven calendar application with the following architecture:

Core Principles

• Event-driven communication: All components communicate via DOM CustomEvents through a central EventBus
• No global state: Each manager maintains its own state
• Manager-based architecture: Each manager has a specific responsibility
• Pure DOM manipulation: No external JavaScript frameworks (React, Vue, etc.)
• TypeScript with esbuild: Modern build tooling for fast compilation

Key Components

EventBus (src/core/EventBus.ts)

Central event dispatcher using DOM CustomEvents. All inter-component communication flows through this:

// Example event emission
eventBus.emit('calendar:view-changed', { view: 'week' });

// Example event subscription
eventBus.on('calendar:view-changed', (event) => { /* handle */ });

Manager Pattern

Each manager is instantiated via ManagerFactory in src/index.ts and handles a specific domain:

• CalendarManager: Main coordinator, initializes other managers
• ViewManager: Handles day/week/month view switching
• NavigationManager: Prev/next/today navigation
• EventManager: CRUD operations for calendar events
• EventRenderer: Visual rendering of events in the grid
• GridManager: Creates and maintains the calendar grid structure
• ScrollManager: Handles scroll position and time indicators
• DragDropManager: Drag & drop functionality for events

Project Structure

src/
├── constants/     # Enums and constants (CoreEvents)
├── core/          # Core functionality (EventBus, CalendarConfig)
├── factories/     # ManagerFactory for dependency injection
├── interfaces/    # TypeScript interfaces
├── managers/      # Manager classes (one per domain)
├── renderers/     # Event rendering services
├── strategies/    # View strategy pattern implementations
├── types/         # TypeScript type definitions
└── utils/         # Utility functions (DateUtils, PositionUtils)

wwwroot/
├── css/          # Modular CSS files
├── js/           # Compiled JavaScript output
└── index.html    # Main HTML entry point

CSS Architecture

Modular CSS structure without external frameworks:

• calendar-base-css.css: CSS custom properties and base styles
• calendar-components-css.css: UI components
• calendar-events-css.css: Event styling and colors
• calendar-layout-css.css: Grid and layout
• calendar-popup-css.css: Popup and modal styles
• calendar-month-css.css: Month view specific styles

Event System

The application uses CoreEvents enum for type-safe event handling. Events follow the pattern category:action:

• calendar:* - General calendar events
• grid:* - Grid-related events
• event:* - Event data changes
• navigation:* - Navigation actions
• view:* - View changes

Core events are centralized in src/constants/CoreEvents.ts to maintain consistency across the application.

Configuration System

CalendarConfig singleton (src/core/CalendarConfig.ts) manages:

• Grid settings (hour height, snap intervals, time boundaries)
• View configurations (day/week/month settings)
• Work week presets (standard, compressed, midweek, weekend, fullweek)
• Resource-based calendar mode support

TypeScript Configuration

• Target: ES2020
• Module: ESNext
• Strict mode enabled
• Source maps enabled
• Output directory: wwwroot/js

Build System

Uses esbuild for fast TypeScript compilation:

• Entry point: src/index.ts
• Output: wwwroot/js/calendar.js (single bundled file)
• Platform: Browser
• Format: ESM
• Source maps: Inline for development