# Calendar Pro ## Description A comprehensive, multi-view calendar component that combines five display modes into a single configurable element: Month View (full grid with event indicators), Week View (7-column time grid with event blocks), Day View (single-column time grid), Agenda View (chronological event list grouped by day), and Mini View (compact month grid for navigation). All views share the same data source, event fields, colors, language, and actions. A "View Mode" prop controls which layout renders, with view-specific props revealed via conditional visibility. Designed to replace the existing Calendar, Markings Calendar, and Advanced Calendar with a unified, more powerful component. {% tabs %} {% tab title="SETUP" %} #### Structure Accordion-based structure with eight sections: * Calendar Pro (main configuration — collapsible, expanded by default) * Events (data binding — collapsible) * Month View Settings (conditional — only visible when View Mode includes Month) — collapsible * Week/Day View Settings (conditional — only visible when View Mode is Week or Day) — collapsible * Agenda View Settings (conditional — only visible when View Mode is Agenda) — collapsible * Colors (visual customization — collapsible) * Navigation (date constraints & icons — collapsible) * Actions (event handlers — collapsible) #### Calendar Pro Section Props | Prop | Type | Default | Description | | --------------------- | ----------------------- | --------------------------- | -------------------------------------------------------------------------------------- | | View Mode | Dropdown | Month | Which calendar layout to display | | Language | Dropdown | English | Language for all date-related text | | First Day of the Week | Dropdown | Sunday | Which day appears first in week columns | | Default Date Type | Dropdown | Date/Time | Format for the Default Date field | | Default Date | Text Input (Magic Text) | 0 (or YYYY-MM-DD) | Pre-selected date when the calendar loads | | Show Header | Toggle | ON | Whether the month/week/day header with navigation is shown | | Show Today Button | Toggle | ON | Whether a "Today" button appears for quick navigation to current date | | Allow View Switching | Toggle | OFF | Whether users can toggle between view modes at runtime via a view switcher UI | | Allowed Views | Multi-Select Toggle | Month, Week, Day, Agenda ON | Which view modes appear in the switcher (only visible when Allow View Switching is ON) | **View Mode Options** | Option | Description | | ------ | --------------------------------------------------------------------------------------------------------------- | | Month | Full month grid with event dots or bars on dates. Standard calendar view. | | Week | 7-column time grid showing hourly rows. Events as time blocks spanning their duration. | | Day | Single-column time grid for one day. Events as time blocks. More detail than week view. | | Agenda | Scrollable chronological list of events grouped by day. No grid. | | Mini | Compact month grid (smaller cells, no event details). Designed as a date navigator to control other components. | **Language Options** | Option | | ---------- | | Arabic | | Chinese | | English | | French | | German | | Hindi | | Japanese | | Polish | | Portuguese | | Spanish | | Russian | | Swedish | **First Day of the Week Options** | Option | Description | | ------ | ------------------------------------ | | Sunday | Week starts on Sunday (US standard) | | Monday | Week starts on Monday (ISO standard) | **Default Date Type Options** | Option | Description | | --------- | ------------------------------------ | | Date/Time | Uses magic 'Date & Time' values | | Text Date | Uses text input in YYYY-MM-DD format | **Conditional Visibility — View Switching** | Toggle | State | Revealed Props | | -------------------- | ----- | --------------------------------------------------------------- | | Allow View Switching | ON | Allowed Views (individual toggles for Month, Week, Day, Agenda) | | Allow View Switching | OFF | (hidden) | **Conditional Visibility — Default Date Type** | Default Date Type | Default Date Field Behavior | | ----------------- | ------------------------------------------------------------- | | Date/Time | Default Date shows "0" with helper "Use a Date & Time value". | | Text Date | Default Date shows placeholder "YYYY-MM-DD". | #### Events Section Props | Prop | Type | Default | Description | | ------------------- | ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- | | Choose Collection | Collection Selector | Empty (Select...) | Database collection containing event records | | Event Start | Text Input (Magic Text) | 0 | Date & time field for event start. Use 'date & time' values. | | Event End | Text Input (Magic Text) | 0 | Date & time field for event end. Use 'date & time' values. | | Event Title | Text Input (Magic Text) | Empty ("Enter Text...") | Text field from collection for event title display | | Event Subtitle | Text Input (Magic Text) | Empty ("Enter Text...") | Text field from collection for event subtitle (used in Agenda, Week, Day views) | | Event Color Field | Text Input (Magic Text) | Empty | Optional color field from collection for per-event color coding. If empty, uses default Event Color. | | All-Day Event Field | Text Input (Magic Text) | Empty | Optional boolean field indicating the event spans the entire day | | Show Sample Events | Toggle | ON | Editor-only preview toggle. Shows placeholder events on the canvas for design purposes. | #### Month View Settings Section Props **Visibility:** Only visible when View Mode = Month or Mini, or when Month is in Allowed Views. | Prop | Type | Default | Description | | --------------------------- | --------------- | ------------- | ----------------------------------------------------------------------------------------- | | Event Marking Style | Dropdown | Dots | How events are indicated on the month grid | | Max Events Per Day | Slider (Number) | 3 | Maximum event indicators per date cell (range: 1–5). Additional events show as "+N more". | | Show Week Numbers | Toggle | OFF | Whether ISO week numbers appear at the start of each row | | Highlight Selected Day | Toggle | ON | Whether the tapped date gets a distinct highlight | | Show Outside Month Days | Toggle | ON | Whether dates from previous/next months appear in the grid (grayed out) | | Single Event Click Behavior | Dropdown | Run an Action | What happens when a date with exactly one event is tapped | **Event Marking Style Options** | Option | Description | | ----------- | ------------------------------------------------------- | | Dots | Small colored dots below the date number for each event | | Bars | Colored bars spanning the event duration across cells | | Count Badge | Small number badge showing event count | **Single Event Click Behavior Options** | Option | Description | | ---------------- | ------------------------------------- | | Run an Action | Executes configured click actions | | Open Agenda View | Switches to agenda view for that date | | Show Event Popup | Displays a popup with event details | **Conditional Visibility — View Mode (Month Settings)** | View Mode | Month View Settings Section | | ----------------- | ------------------------------------------------------------------------- | | Month | Visible | | Mini | Visible (subset: only Highlight Selected Day and Show Outside Month Days) | | Week, Day, Agenda | Hidden | #### Week/Day View Settings Section Props **Visibility:** Only visible when View Mode = Week or Day, or when Week/Day is in Allowed Views. | Prop | Type | Default | Description | | --------------------------- | -------- | ------------ | ----------------------------------------------------------------- | | Time Grid Start | Dropdown | 6:00 AM | First hour shown in the time grid | | Time Grid End | Dropdown | 10:00 PM | Last hour shown in the time grid | | Time Slot Interval | Dropdown | 30 Minutes | Height/granularity of each time row | | Time Format | Dropdown | 12 Hour | How times are labeled on the Y-axis | | Show Current Time Indicator | Toggle | ON | Whether a horizontal line marks the current time | | Show All-Day Section | Toggle | ON | Whether an "All Day" row appears at the top for all-day events | | Event Overlap Strategy | Dropdown | Side by Side | How overlapping events are displayed | | Working Hours Highlight | Toggle | OFF | Whether working hours (9 AM–5 PM) get a different background tint | **Time Grid Start / End Options** Hours from 12:00 AM to 11:00 PM in 1-hour increments. **Time Slot Interval Options** | Option | Description | | ---------- | ---------------------- | | 15 Minutes | Fine-grained time grid | | 30 Minutes | Standard time grid | | 60 Minutes | Coarse time grid | **Time Format Options** | Option | Description | | ------- | ------------------------------- | | 12 Hour | Shows times as 9:00 AM, 2:30 PM | | 24 Hour | Shows times as 09:00, 14:30 | **Event Overlap Strategy Options** | Option | Description | | ------------ | ----------------------------------------------------------------------- | | Side by Side | Overlapping events share the column width, displayed adjacent | | Stacked | Overlapping events stack with slight offset, each one partially visible | **Conditional Visibility — View Mode (Week/Day Settings)** | View Mode | Week/Day Settings Section | | ------------------- | ------------------------- | | Week | Visible | | Day | Visible | | Month, Mini, Agenda | Hidden | #### Agenda View Settings Section Props **Visibility:** Only visible when View Mode = Agenda, or when Agenda is in Allowed Views. | Prop | Type | Default | Description | | ------------------- | --------------- | ----------- | ---------------------------------------------------------------- | | Days to Show | Slider (Number) | 7 | Number of upcoming days to display in the agenda (range: 1–30) | | Time Format | Dropdown | 12 Hour | How event times are displayed | | Show Empty Days | Toggle | ON | Whether days with no events still appear as headers | | Group By | Dropdown | Day | How events are grouped in the list | | Show Event Duration | Toggle | ON | Whether event duration (e.g., "30 min") is shown alongside times | | Event Row Height | Dropdown | Comfortable | Density of event rows | **Group By Options** | Option | Description | | ------ | --------------------------------------------------- | | Day | Events grouped under date headers (standard agenda) | | Week | Events grouped under week headers | **Event Row Height Options** | Option | Description | | ----------- | --------------------------------- | | Compact | Smaller rows, more events visible | | Comfortable | Standard row height with padding | | Spacious | Larger rows with extra whitespace | **Conditional Visibility — View Mode (Agenda Settings)** | View Mode | Agenda Settings Section | | ---------------------- | ----------------------- | | Agenda | Visible | | Month, Week, Day, Mini | Hidden | #### Colors Section Props | Prop | Type | Default | Description | | ------------------------ | ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Background Color | Color Picker | #ffffff (white) | Background color of the calendar | | Text Color | Color Picker | #333333 (dark gray) | Color for day numbers and general text | | Heading Text Color | Color Picker | #333333 (dark gray) | Color for month/year/week header text | | Day of Week Color | Color Picker | #999999 (medium gray) | Color for day-of-week labels | | Disabled Text Color | Color Picker | #CCCCCC (light gray) | Color for dates outside selectable range | | Today Text Color | Color Picker (Branding) | Primary (@primary) | Color for today's date number | | Selected Date Background | Color Picker (Branding) | Primary (@primary) | Background for the selected/clicked date | | Selected Date Text Color | Color Picker | #ffffff (white) | Text color for the selected date | | Event Color | Color Picker (Branding) | Primary (@primary) | Default color for event indicators (dots, bars, blocks). Overridden by per-event color if Event Color Field is set. | | Event Text Color | Color Picker | #ffffff (white) | Text color inside event blocks (Week/Day view) | | Current Time Color | Color Picker | #FF0000 (red) | Color for the current time indicator line (Week/Day view) | | Grid Line Color | Color Picker | #E0E0E0 (light gray) | Color for time grid lines (Week/Day view) | | Navigation Icon Color | Color Picker (Branding) | Primary (@primary) | Color for navigation arrows | | Working Hours Background | Color Picker | #F8F9FA (very light gray) | Background for working hours region (Week/Day view, when enabled) | | Today Column Background | Color Picker | #FFF8E1 (light yellow) | Background tint for today's column in Week view | #### Navigation Section Props | Prop | Type | Default | Description | | ------------------------ | ----------------------- | -------------- | ----------------------------------------------------------- | | Go To Previous Icon | Icon Picker | chevron\_left | Icon for navigating backward | | Go To Next Icon | Icon Picker | chevron\_right | Icon for navigating forward | | Icon Size | Slider (Number) | 24 | Size of navigation icons in pixels (range: 16–40) | | Earliest Selectable Date | Text Input (Magic Text) | Empty | First navigable date. Empty = no limit. | | Latest Selectable Date | Text Input (Magic Text) | Empty | Last navigable date. Empty = no limit. | | Allow Changing Months | Toggle | ON | Whether navigation arrows are functional | | Disable Past Dates | Toggle | OFF | Whether dates before today are grayed out and non-clickable | #### Actions Section Props | Prop | Type | Default | Description | | --------------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | | On Date Selected | Action List | No Actions | Actions when a date cell is tapped (all views). Selected date available as parameter. | | On Event Clicked | Action List | No Actions | Actions when an event is tapped (all views). Event record available as parameter. | | On Empty Slot Clicked | Action List | No Actions | Actions when empty time slot is tapped (Week/Day view only). Date + time available as parameters. | | On View Changed | Action List | No Actions | Actions when the user switches view mode (only when Allow View Switching is ON) | | On Month Changed | Action List | No Actions | Actions when navigating to a different month/week/day | | {% endtab %} | | | | {% tab title="LAYOUT" %} | Prop | Type | Default | Description | | -------------------------------- | -------- | ------------------ | ------------------------------------------------------- | | Width Resizing | Dropdown | Scales with Screen | How the component width responds to screen size changes | | Where is the component anchored? | Dropdown | Anchor Center | Horizontal anchor position when screen resizes | | Sticky while scrolling? | Toggle | Off | Whether component stays fixed during scroll | #### Width Resizing Options | Option | Description | | ------------------ | -------------------------------------------------------- | | Scales with Screen | Component width adjusts proportionally with screen width | | Stays Fixed | Component maintains its exact pixel width | #### Anchor Options | Option | Description | | ------------- | ------------------------------------------ | | Anchor Left | Component stays anchored to the left edge | | Anchor Center | Component stays centered horizontally | | Anchor Right | Component stays anchored to the right edge | | {% endtab %} | | | {% endtabs %} | | ## Builder Notes 1. **New custom component** — Replaces and extends Calendar, Markings Calendar, and Advanced Calendar with a unified multi-view component 2. **Five view modes** — Month, Week, Day, Agenda, Mini all in one component. View Mode dropdown controls which renders. Conditional visibility shows only relevant settings per view. 3. **Runtime view switching** — When Allow View Switching is ON, users can toggle between views at runtime (like Google Calendar). Builder controls which views are available. 4. **Per-event colors** — Optional Event Color Field from database allows per-event color coding (e.g., meeting type, category, priority). Falls back to default Event Color if not set. 5. **All-day events** — Optional All-Day Event Field boolean enables all-day event display in Week/Day views' all-day section 6. **Time grid customization** — Week/Day views support configurable start/end hours, interval, and working hours highlight 7. **Event overlap handling** — Side-by-side or stacked display for concurrent events in Week/Day views 8. **Current time indicator** — Red horizontal line shows current time in Week/Day views for orientation 9. **Agenda configurability** — Days to show, grouping, density, and empty day handling are all configurable 10. **Mini view for navigation** — Compact mode designed to drive other components. Selected date output available via Magic Text. 11. **Three event marking styles** — Month view supports Dots, Bars, and Count Badge indicators 12. **Event popup option** — Month view can show inline event popup instead of running an action or switching to agenda 13. **Output values** — Selected Date, Selected Event (record), and Current View are exposed via Magic Text 14. **12 languages** — Full language support matching all calendar components 15. **Branding tokens** — Today, Selected Date, Event Color, and Navigation icons use branding tokens 16. **Week numbers** — Optional ISO week numbers on month view for business/enterprise use cases 17. **Past date disabling** — Optional toggle to gray out historical dates (useful for forward-only scheduling) 18. **Editor preview** — Show Sample Events toggle displays placeholder data for design purposes without affecting the live app ## Visual Appearance **Month View:** * Month grid with navigation arrows and month/year header * 7-column grid with day numbers and event indicators (dots, bars, or count badges) * Selected date highlighted with Selected Date Background color * Today highlighted with Today Text Color **Week View:** * 7-column layout with day headers (Mon–Sun or Sun–Sat) * Hourly rows on Y-axis with time labels * Events as colored blocks spanning their duration * Current time indicator (red line) * Optional all-day section at top * Optional working hours background tint **Day View:** * Single column with hourly rows * Events as colored blocks * More vertical space per event than week view * Current time indicator **Agenda View:** * Scrollable vertical list * Day headers separating event groups * Each event shows time, title, subtitle, and optional duration * Empty days shown or hidden based on setting **Mini View:** * Compact month grid (smaller cells) * Dot indicators only (no text details) * Selected date highlighted * Designed for sidebar/navigation use (smaller default dimensions) ## Calendar Pro vs Existing Calendar Components | Feature | Calendar Pro | Calendar (Adalo) | Advanced Calendar | Markings Calendar | | ----------------------- | ---------------------------------- | ------------------------ | ----------------- | ----------------- | | View modes | 5 (Month, Week, Day, Agenda, Mini) | 1 (Month + Agenda popup) | 1 (Month) | 1 (Month) | | Runtime view switching | Yes | No | No | No | | Week/Day time grid | Yes | No | No | No | | Agenda list view | Yes | Built into month | No | No | | Per-event color | Yes (from DB field) | No | No | Yes (hex field) | | All-day events | Yes | No | No | No | | Event marking styles | 3 (Dots, Bars, Badge) | 2 (Dots, Bars) | 1 (Dots) | 1 (Dots) | | Current time indicator | Yes | No | No | No | | Week numbers | Yes | No | No | No | | Working hours highlight | Yes | No | No | No | | Event overlap handling | Yes | N/A | N/A | N/A | | View switcher UI | Yes | No | No | No | | Mini/compact mode | Yes | No | No | No | | Languages | 12 | 11 | 11 | 11 |