new calendar component

[lovasoa]

SQLPage Calendar Component - Technical Design Document

Overview

The Calendar component will allow users to visualize and interact with time-based data in a familiar calendar interface. This document outlines the technical design and implementation strategy.

Component Properties

Top-Level Properties

1. title (optional)

   • Text displayed above calendar
   • Similar to chart/map components' title implementation

2. initial_view (optional)

   • Controls initial calendar display format
   • Options: "month", "week", "day"
   • Defaults to "month"

3. height (optional)

   • Sets fixed calendar height in pixels
   • Similar to chart component's height property
   • Defaults to auto-height

4. json_url (optional)

   • Enables dynamic event loading
   • Points to SQLPage JSON endpoint
   • Similar to dynamic component's implementation

5. navigation (optional, boolean)

   • Enables/disables date navigation controls
   • Defaults to true

6. today (optional, boolean)

   • Shows/hides "Today" button
   • Defaults to true

Row-Level Properties

1. title (required)

   • Event title text
   • Displayed in calendar cells

2. start (required)

   • Event start time
   • Supports both date and datetime

3. end (optional)

   • Event end time
   • Defaults to start time for single-day events

4. color (optional)

   • Event visual styling
   • Uses SQLPage color system (like chart/timeline components)

5. url (optional)

   • Click destination
   • Similar to list component's link property

6. description and description_md (optional)

   • Event details
   • Shown in tooltip/popup

7. all_day (optional, boolean)

   • Indicates full-day events
   • Affects visual display

Technical Implementation Details

File Structure

Look at these existing files for reference patterns:

• sqlpage/templates/chart.handlebars - For component template structure
• sqlpage/apexcharts.js - For JavaScript initialization patterns
• examples/official-site/sqlpage/migrations/ - For component documentation

Required Changes

1. Component Registration

• Location: examples/official-site/sqlpage/migrations/
• New file: XX_calendar.sql (XX = next number in sequence)
• Purpose: Register component and document properties
• Reference: See how chart/map components are documented

2. Template Creation

• Location: sqlpage/templates/
• New file: calendar.handlebars
• Structure:
  • Card wrapper (like map component)
  • Title section
  • Calendar container
  • Data embedding section
• Reference: Study map.handlebars for structure

3. JavaScript Integration

• Location: sqlpage/
• New file: calendar.js
• Key sections:
  • Initialization function
  • Event handling
  • View management
  • Data processing
• Reference: Study apexcharts.js initialization patterns

Integration Points

1. JSON API Integration

• Uses existing JSON component
• Enables dynamic event loading
• Reference: Study dynamic component implementation

2. SQLPage Core Integration

• Component registration
• Reference: Study how chart component is integrated

3. Color System Integration

• Uses existing SQLPage color system
• Reference: Study timeline component's color handling

Testing Strategy

1. Unit Tests

• Test date handling
• Validate property processing

2. Integration Tests

• Add a spec file to the end to end tests

Documentation

1. Component Documentation

• Usage examples
• Property descriptions
• Common patterns
• Location: examples/official-site/sqlpage/migrations/XXX-calendar.sql

2. Example Application

• Basic calendar
• Dynamic calendar
• Multi-calendar view
• Location: Create new directory in examples/