docs(calendar-web): add openspec change for showMultiDayTimes property

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

packages/pluggableWidgets/calendar-web/openspec/changes/add-show-multi-day-times/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-23

packages/pluggableWidgets/calendar-web/openspec/changes/add-show-multi-day-times/proposal.md

@@ -0,0 +1,44 @@
+## Why
+
+In the Calendar widget's week and day views, `react-big-calendar` places any event that
+spans more than one day into the top "all-day" row, hiding its start and end times. For
+apps where multi-day events have meaningful times (e.g. a booking that starts at 22:00 on
+one day and ends at 02:00 the next), authors need those events rendered as timed blocks in
+the time grid, showing their start/end times, instead of being flattened into the all-day
+row.
+
+`react-big-calendar` already exposes a `showMultiDayTimes` flag for exactly this, but the
+Calendar widget did not surface it, so authors had no way to opt in.
+
+## What Changes
+
+Add a `showMultiDayTimes` boolean property (default `false`) to the Calendar widget and pass
+it through to `react-big-calendar`. When enabled, multi-day events render in the time grid
+with their start/end times in week and day views. To make those times readable on the
+event blocks, the widget also supplies `eventTimeRangeStartFormat` and
+`eventTimeRangeEndFormat` derived from the widget's configured time format, and keeps them
+consistent with the existing `eventTimeRangeFormat` and `showEventDate` behavior.
+
+- `src/Calendar.xml` — add `showMultiDayTimes` boolean property (defaultValue `false`) in
+  the week/day view group, with caption and description.
+- `typings/CalendarProps.d.ts` — add `showMultiDayTimes: boolean` to the container props and
+  `showMultiDayTimes: boolean` to the preview props (generated typings).
+- `src/helpers/CalendarPropsBuilder.ts`:
+    - Pass `showMultiDayTimes: this.props.showMultiDayTimes` through to the calendar props.
+    - Add `eventTimeRangeStartFormat` (`"<start> – "`) and `eventTimeRangeEndFormat`
+      (`" – <end>"`) using the same configured time pattern as `eventTimeRangeFormat`.
+    - When `showEventDate` is `false`, blank out `eventTimeRangeStartFormat` and
+      `eventTimeRangeEndFormat` alongside the existing `eventTimeRangeFormat`.
+- Unit tests + snapshot update for the above.
+- User-facing changelog entry.
+
+## Impact
+
+- **Consumers:** Purely additive. The default is `false`, which preserves the existing
+  behavior (multi-day events stay in the all-day row), so existing apps are unaffected. Not
+  breaking.
+- **Must NOT break:** `showEventDate=false` must continue to hide all event time ranges,
+  including the new start/end formats; existing single-day timed event rendering and the
+  existing `eventTimeRangeFormat` behavior are unchanged.
+- **Users:** Authors can opt in to see start/end times for multi-day events in week and day
+  views. Version bump deferred to release time per repo convention.

packages/pluggableWidgets/calendar-web/openspec/changes/add-show-multi-day-times/specs/calendar-configuration/spec.md

@@ -0,0 +1,73 @@
+## ADDED Requirements
+
+### Requirement: Show multi-day times property
+
+The Calendar widget SHALL expose a `showMultiDayTimes` boolean property (default `false`)
+that controls whether events spanning multiple days are rendered as timed blocks (showing
+start/end times) in the week and day views instead of being placed in the all-day row.
+
+#### Scenario: Property is available in Studio Pro
+
+- **WHEN** a developer configures the Calendar widget in Studio Pro
+- **THEN** a "Show multi-day times" boolean property is available, defaulting to off
+
+#### Scenario: Enabled flag is passed through to the calendar
+
+- **WHEN** `showMultiDayTimes` is set to `true`
+- **THEN** the Calendar passes `showMultiDayTimes=true` to `react-big-calendar`, so multi-day
+  events render as timed blocks in the week and day views
+
+#### Scenario: Disabled by default preserves all-day rendering
+
+- **WHEN** `showMultiDayTimes` is left at its default (`false`)
+- **THEN** the Calendar passes `showMultiDayTimes=false`, and multi-day events continue to be
+  placed in the all-day row (existing behavior is unchanged)
+
+### Requirement: Multi-day event time-range formats
+
+When a time format is configured, the Calendar widget SHALL provide
+`eventTimeRangeStartFormat` and `eventTimeRangeEndFormat` for `react-big-calendar`, derived
+from the same configured time pattern used by `eventTimeRangeFormat`, so the start and end
+times of multi-day events are shown in a locale-aware way.
+
+#### Scenario: Start format renders the start time with a trailing separator
+
+- **WHEN** a time format (e.g. `HH:mm`) is configured and `eventTimeRangeStartFormat` is
+  called for an event
+- **THEN** it returns the event's start time formatted with that pattern, followed by a
+  " – " separator
+
+#### Scenario: End format renders the end time with a leading separator
+
+- **WHEN** a time format (e.g. `HH:mm`) is configured and `eventTimeRangeEndFormat` is called
+  for an event
+- **THEN** it returns the event's end time formatted with that pattern, preceded by a " – "
+  separator
+
+#### Scenario: Start, end, and range formats share the same time pattern
+
+- **WHEN** a time format (e.g. `h:mm a`) is configured
+- **THEN** `eventTimeRangeFormat`, `eventTimeRangeStartFormat`, and `eventTimeRangeEndFormat`
+  all format times using that same pattern
+
+#### Scenario: No time format leaves start/end formats unset
+
+- **WHEN** no time format is configured
+- **THEN** the widget does not set `eventTimeRangeStartFormat` or `eventTimeRangeEndFormat`
+
+### Requirement: Show event date hides multi-day time ranges
+
+When `showEventDate` is disabled, the Calendar widget SHALL hide all event time-range labels,
+including the multi-day start and end formats, so no times are shown on events.
+
+#### Scenario: showEventDate=false blanks all time-range formats
+
+- **WHEN** `showEventDate` is `false` (with a time format configured)
+- **THEN** `eventTimeRangeFormat`, `eventTimeRangeStartFormat`, and `eventTimeRangeEndFormat`
+  all return an empty string
+
+#### Scenario: showEventDate=true preserves all time-range formats
+
+- **WHEN** `showEventDate` is `true` (with a time format configured)
+- **THEN** `eventTimeRangeFormat`, `eventTimeRangeStartFormat`, and `eventTimeRangeEndFormat`
+  all return a non-empty formatted label

packages/pluggableWidgets/calendar-web/openspec/changes/add-show-multi-day-times/tasks.md

@@ -0,0 +1,28 @@
+## 1. Property definition
+
+- [x] 1.1 Add `showMultiDayTimes` boolean property (defaultValue `false`) with caption and description to `src/Calendar.xml` in the week/day view group
+- [x] 1.2 Regenerate typings: `showMultiDayTimes: boolean` in `CalendarContainerProps` and `CalendarPreviewProps` (`typings/CalendarProps.d.ts`)
+
+## 2. Implementation
+
+- [x] 2.1 Pass `showMultiDayTimes: this.props.showMultiDayTimes` through to the calendar props in `CalendarPropsBuilder.build`
+- [x] 2.2 Add `eventTimeRangeStartFormat` (`"<start> – "`) and `eventTimeRangeEndFormat` (`" – <end>"`) using the same configured time pattern as `eventTimeRangeFormat`
+- [x] 2.3 When `showEventDate?.value === false`, blank `eventTimeRangeStartFormat` and `eventTimeRangeEndFormat` alongside the existing `eventTimeRangeFormat`
+
+## 3. Tests
+
+- [x] 3.1 Test `showMultiDayTimes=true`/`false` is passed through to calendar props
+- [x] 3.2 Test start/end formats use the configured time pattern with the correct leading/trailing separator; and are unset when no time format is configured
+- [x] 3.3 Test `showEventDate=false` blanks range/start/end formats; `showEventDate=true` preserves them
+- [x] 3.4 Update the Calendar snapshot for the new `data-show-multi-day-times` (and `data-min`/`data-max`) attributes
+
+## 4. Verification
+
+- [x] 4.1 `calendar-web` unit suite passes
+- [x] 4.2 Add user-facing changelog entry (new `showMultiDayTimes` property)
+- [ ] 4.3 `/code-review` before merge; PR ready
+
+## Notes
+
+- Change is additive; default `false` preserves existing all-day rendering for multi-day events.
+- Version bump deferred to release time per repo convention.