Schedule UI Hardening + Load Awareness System

[ayanimea]

Schedule UI Hardening + Load Awareness System

Overview

This PR refines the Schedule UI and introduces a load-aware scheduling system designed to:

• Improve week-view clarity
• Detect scheduling density using configurable thresholds
• Suggest alternative time slots when a day exceeds capacity
• Preserve user autonomy
• Separate structural rules from guidance logic
• Remove hardcoded behavioral values
• Add deterministic scheduling logic
• Maintain performance guarantees

This change transforms Schedule from a passive calendar into a structurally aware planning system.

---

1️⃣ Scheduling Configuration

Create:

/schedule/config.ts

export const SCHEDULING_CONFIG = {
  loadThresholdHigh: 0.8,
  loadThresholdOver: 1.0,

  maxSimultaneousEvents: 2,
  maxSimultaneousWithAllDay: 3,

  snapIntervalMinutes: 15
} as const;

if (
  SCHEDULING_CONFIG.loadThresholdOver <=
  SCHEDULING_CONFIG.loadThresholdHigh
) {
  throw new Error("Invalid scheduling threshold configuration");
}

All behavioral thresholds must reference this config.

No literal threshold values may appear in UI or logic.

---

2️⃣ Snap & Time Normalization

All event times must:

• Snap to configured interval
• Round start down
• Round end up

Snapping must be centralized in:

/schedule/timeUtils.ts

Applied consistently across:

• Create
• Edit
• Drag
• Resize
• Suggestion generation

---

3️⃣ Load Computation

Daily load must include:

• Main duration
• Prep time
• Travel time
• Snapped duration

Load = usedMinutes / totalDayMinutes

Day duration must be computed dynamically using actual date boundaries (DST-safe).

Load must be:

• Pure function
• Memoized
• Not computed during scroll
• Not computed during hover

---

4️⃣ Structural Constraints

Structural validation must enforce:

• Maximum 2 simultaneous events
• 3 allowed only if one is all-day
• Overlap checks must include prep + travel
• Validation must run on create, edit, drag, resize

Structural validation is independent of guidance level.

---

5️⃣ Guidance System

Add setting: schedulingGuidanceLevel

Enum:

• "full" (default)
• "header-only"
• "off"

Behavior:

Mode	Header Indicators	Modal Warning	Suggestions
full	Yes	Yes	Yes
header-only	Yes	No	No
off	No	No	No

Structural rules apply in all modes.

---

6️⃣ Suggestion Engine

Suggestions must:

• Start from current time
• Snap to interval
• Include prep + travel in overlap checks
• Stay within visible range
• Respect simultaneous limit
• Be deterministic

Sort priority:

1. Lowest projected load
2. Longest free block
3. Earliest time

No randomness.

---

7️⃣ Header Load Indicators (Week View Only)

Threshold application:

• ≥ loadThresholdHigh → subtle underline
• ≥ loadThresholdOver → underline + indicator icon

Indicators must:

• Be static
• Include accessible label
• Not animate

Day view does not show load indicators.

---

8️⃣ Visual Refinement

Differences allowed between Day and Week:

• Shadow intensity
• Gradient blend strength
• Vertical padding
• Font weight

Font size and layout structure remain unchanged.

All visual values must use design tokens.

No hardcoded shadows or rgba in components.

---

9️⃣ Performance Requirements

• Load memoized
• Suggestions bounded
• No infinite loops
• No O(n²) scans
• No modal during drag

---

🔟 Test Requirements

Create tests for:

• Snap rounding
• Threshold boundaries
• Overlap including prep/travel
• Simultaneous limits
• Deterministic suggestions
• Config invariant

Coverage targets:

• Load logic ≥95%
• Structural logic 100%
• Suggestions ≥90%