EPIC-06: Timeline, Gantt Chart & Dependency Management

[steilerDev]

Epic: Timeline, Gantt Chart & Dependency Management

Epic ID: EPIC-06
Priority: Must Have
Sprint Suggestion: Sprint 3

Description

Implement the Gantt chart visualization, dependency management engine, and multiple timeline views. This is a signature feature of the application -- homeowners need to visualize their entire project timeline, understand task dependencies, see the critical path, and have dates automatically adjust when delays occur. This epic covers the Gantt chart, calendar view, dependency logic (automatic scheduling, conflict detection, cascade updates), milestones, and the integration of household item delivery dates onto the timeline.

Requirements Coverage

• Section 2.4: Timeline & Gantt Chart (complete section)
  • Gantt Chart Visualization
    • Visual timeline of all work items
    • Task bars showing duration
    • Dependency arrows (Finish-to-Start, Start-to-Start, etc.)
    • Critical path highlighting
    • Today marker
    • Milestone markers
    • Household item delivery dates (visually distinct)
  • Dependency Management
    • Define task dependencies
    • Automatic scheduling based on dependencies
    • Conflict detection (circular dependencies)
    • Cascade updates when dates change
  • Milestones
    • Major project milestones
    • Milestone dates
    • Milestone completion tracking
  • Views
    • Gantt chart view
    • Calendar view
    • List view (already partially in EPIC-03)
• Section 2.1: Work Items - Dependencies
  • Predecessor/successor relationships for Gantt chart
• Section 2.3: Timeline Integration
  • Delivery dates shown on timeline/calendar
  • Visual distinction from work items on timeline
• Section 3.4: Usability
  • Drag-and-drop for Gantt chart
  • Smooth Gantt chart interactions
• Section 4: User Stories - Timeline
  • See Gantt chart of all work items
  • See household item delivery dates on timeline
  • Drag tasks in Gantt chart to adjust dates quickly
  • See critical path for tasks that cannot be delayed
  • See milestones on timeline for major progress points
  • Automatic rescheduling when a task is delayed
• Section 4: User Stories - Work Items
  • Set dependencies between tasks for correct ordering
• Section 4: User Stories - Household Items
  • See delivery dates on timeline for coordination

Dependencies

• EPIC-02: Application Shell & Infrastructure (app shell for rendering)
• EPIC-03: Work Items Core CRUD (work items must exist to visualize)

Goals

• Interactive Gantt chart with task bars, dependency arrows, and drag-and-drop
• Multiple dependency types (Finish-to-Start, Start-to-Start, etc.)
• Automatic scheduling engine that respects dependencies and constraints
• Circular dependency detection and prevention
• Cascade date updates when a task is delayed
• Critical path calculation and highlighting
• Milestone management (create, track completion, display on timeline)
• Today marker on Gantt chart
• Household item delivery dates displayed on Gantt chart (visually distinct)
• Calendar view of work items and deliveries
• Smooth, performant chart interactions
• Drag-and-drop date adjustment on Gantt chart

[steilerDev]

[frontend-developer] UX Visual Specification: Dependency Management Redesign

---

Overview

This specification covers three usability improvements to dependency management for homeowners who need to track which tasks must happen before others. The redesign avoids project-management jargon (no "predecessor/successor") in favour of plain English ("depends on" / "blocks").

API contract reference: POST /api/work-items/:id/dependencies — :id is always the successor (the item that depends on the predecessor). DELETE /api/work-items/:id/dependencies/:predecessorId — :id is the successor. These semantics drive the parameter-swap logic described below.

---

A. Redesigned "Add Dependency" Form — WorkItemDetailPage

A1. Section Label Changes

Replace the existing H3 subtitles with plain-English labels:

Current label	New label
Predecessors (Blocking This)	Depends On
Successors (Blocked By This)	Blocks

The top-level <h2> "Dependencies" is retained as-is.

A2. Direction Toggle

Replace the WorkItemPicker + type-select inline layout with a three-row form:

┌──────────────────────────────────────────────────────────────────┐
│  Add dependency                                                  │
│  ─────────────────────────────────────────────────────────────── │
│                                                                  │
│  Direction                                                       │
│  ┌──────────────────────────┬─────────────────────────────────┐  │
│  │  ● This item depends on  │   This item blocks              │  │
│  └──────────────────────────┴─────────────────────────────────┘  │
│                                                                  │
│  Work item                                                       │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Search for a work item...                             [×] │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Timing                                                          │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Must finish before the other starts (Finish-to-Start) ▼  │  │
│  └────────────────────────────────────────────────────────────┘  │
│  ℹ  Must finish before the other starts                          │
│                                                                  │
│                                        [ Add dependency ]        │
└──────────────────────────────────────────────────────────────────┘

Direction toggle — implementation detail

The toggle is a segmented control rendered as two <button type="button"> elements inside a <div role="group" aria-label="Dependency direction">. Using buttons (not <input type="radio">) keeps the visual segmented style without needing hidden inputs.

Active segment appearance:

• Background: var(--color-primary) (blue-500)
• Text color: var(--color-primary-text) (white)
• Font weight: 500

Inactive segment appearance:

• Background: var(--color-bg-primary)
• Border: 1px solid var(--color-border-strong)
• Text color: var(--color-text-secondary)
• Hover background: var(--color-bg-tertiary)

Toggle layout:

• Container: display: flex, border-radius: 0.375rem, overflow: hidden, border: 1px solid var(--color-border-strong)
• Each segment: flex: 1, padding: 0.5rem 1rem, font-size: 0.875rem, border: none, cursor: pointer, transition: background 0.15s
• Left segment has no extra border-radius; right segment has no extra border-radius (container clips)
• Active segment: add background: var(--color-primary), color: var(--color-primary-text)
• Inactive segment: add background: var(--color-bg-primary), color: var(--color-text-secondary), internal border-left: 1px solid var(--color-border-strong) between segments

Default state: "This item depends on" is the active segment (matches current behaviour — :id = successor).

When "This item blocks" is active: the API call swaps so that the current work item becomes the predecessor:

• API call: POST /api/work-items/{pickedItemId}/dependencies with body { predecessorId: currentItemId, dependencyType }
• "This item blocks [picked]" = picked item is the successor, current item is the predecessor.

When "This item depends on" is active (default):

• API call: POST /api/work-items/{currentItemId}/dependencies with body { predecessorId: pickedItemId, dependencyType }

A3. Timing (dependency type) Dropdown

Replace bare <select> options with descriptive option text. The human-readable description appears inline as the option label; the technical name is shown in parentheses for reference.

Value	Option label (shown in dropdown)
finish_to_start	Must finish before the other starts (Finish-to-Start)
start_to_start	Both start together (Start-to-Start)
finish_to_finish	Both finish together (Finish-to-Finish)
start_to_finish	Must start before the other finishes (Start-to-Finish)

Default selection: finish_to_start (matches API default).

Below the select, render a static help-text line that repeats the description of the currently selected type in plain text. This gives a second reading point without a tooltip needing hover:

ℹ  Must finish before the other starts

• Font size: 0.75rem (--font-size-xs)
• Color: var(--color-text-muted)
• Top margin: 0.375rem
• The "ℹ" character is rendered literally (no SVG icon needed); it is aria-hidden="true" since the text itself conveys the information

Section label "Timing" uses the same .dependencySubtitle style as the existing "Add Dependency" sub-headers: font-size: 0.875rem, font-weight: 600, color: var(--color-text-muted).

A4. Full Form Layout (CSS)

The form retains .addDependencyForm container styles (display: flex, flex-direction: column, gap: 0.75rem, padding-top: 1rem, border-top: 1px solid var(--color-border)).

New elements added inside:

• .directionLabel — section label for the toggle (font-size: 0.875rem, font-weight: 600, color: var(--color-text-muted))
• .directionToggle — the flex container wrapping both buttons
• .directionOption — individual toggle button (both active and inactive states)
• .directionOptionActive — modifier class added to the active button
• .timingLabel — section label for the dropdown (same as .directionLabel)
• .timingHelp — the inline description below the dropdown

A5. Section heading change

The existing <h3 className={styles.dependencySubtitle}>Add Dependency</h3> label is retained above the form but updated to "Add dependency" (sentence case for visual consistency).

---

B. Successor Deletion — WorkItemDetailPage

B1. Delete Button on Successor Items

Add a × delete button to every item in the "Blocks" list, matching the existing delete button pattern on "Depends On" items.

Current successor item layout (no delete button):

┌──────────────────────────────────────────────────────┐
│  [link: Install drywall]     [FS badge]              │
└──────────────────────────────────────────────────────┘

New successor item layout (with delete button):

┌──────────────────────────────────────────────────────┐
│  [link: Install drywall]     [FS badge]     [ × ]    │
└──────────────────────────────────────────────────────┘

The delete button uses the existing .deleteButton class with no modifications:

• Background: transparent
• Border: 1px solid var(--color-danger)
• Color: var(--color-danger)
• Hover background: var(--color-danger), color var(--color-primary-text) (white)
• Padding: 0.625rem 1rem, border-radius: 0.375rem
• Button label: × (same Unicode multiplication sign used throughout the codebase)
• aria-label: "Remove dependency on [work item title]"

B2. API Call for Successor Deletion

When a user clicks the delete button on a successor item, the API parameters are reversed compared to predecessor deletion:

• Predecessor deletion: DELETE /api/work-items/{currentItemId}/dependencies/{predecessorWorkItemId}
  • :id = current item (the successor), :predecessorId = the item being removed
• Successor deletion: DELETE /api/work-items/{successorWorkItemId}/dependencies/{currentItemId}
  • :id = the successor (the item in the "Blocks" list), :predecessorId = current item

The handler handleDeleteSuccessorDependency(successorId: string) mirrors handleDeleteDependency but with swapped arguments.

B3. Confirmation Modal

Re-use the existing confirmation modal (showDeleteConfirm) pattern. The modal text changes based on which direction is being deleted:

• For predecessor ("Depends On") deletion: "This work item will no longer depend on [title]. Are you sure?"
• For successor ("Blocks") deletion: "This work item will no longer block [title]. Are you sure?"

Both use the same modal structure with .modalCancelButton and .modalDeleteButton classes.

State additions needed:

dependencyToDelete: { type: 'predecessor' | 'successor'; workItemId: string; title: string } | null

This replaces the current simple deletingDependencyId string so the modal knows which direction to show and which API call to make.

---

C. Dependencies Section — WorkItemCreatePage

C1. Placement and Structure

Add an optional "Dependencies" section immediately after the "Tags" <div className={styles.formGroup}> block, before the <div className={styles.formActions}> block.

The section renders as a <fieldset> with a <legend> using the same .label class, followed by a sub-form and a list of pending dependency chips.

┌──────────────────────────────────────────────────────────────────────────────┐
│  <form>                                                                       │
│    Title *                                                                    │
│    Description                                                                │
│    Status | Assigned To                                                       │
│    Start Date | End Date | Duration                                           │
│    Start After | Start Before                                                 │
│    Tags                                                                       │
│                                                                               │
│    ─────────────────────────────────────────────────────────────────────────  │
│    Dependencies                                                               │
│                                                                               │
│    ┌──────────────────────────────────────────────────────────────────────┐   │
│    │ Direction                                                            │   │
│    │ ┌─────────────────────────┬────────────────────────────────────────┐│   │
│    │ │ ● This item depends on  │  This item blocks                      ││   │
│    │ └─────────────────────────┴────────────────────────────────────────┘│   │
│    │                                                                      │   │
│    │ Work item                                                            │   │
│    │ ┌──────────────────────────────────────────────────────────────┐    │   │
│    │ │ Search for a work item...                                [×] │    │   │
│    │ └──────────────────────────────────────────────────────────────┘    │   │
│    │                                                                      │   │
│    │ Timing                                                               │   │
│    │ ┌──────────────────────────────────────────────────────────────┐    │   │
│    │ │ Must finish before the other starts (Finish-to-Start)  ▼    │    │   │
│    │ └──────────────────────────────────────────────────────────────┘    │   │
│    │ ℹ  Must finish before the other starts                              │   │
│    │                                                                      │   │
│    │                                          [ + Add to list ]          │   │
│    └──────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
│    Pending dependencies (saved after creating the work item):                 │
│                                                                               │
│    ┌─────────────────────────────────────────────────────────────────────┐    │
│    │ depends on  │  Install foundation  │  Finish-to-Start  │  [×]       │    │
│    ├─────────────────────────────────────────────────────────────────────┤    │
│    │ blocks      │  Pour concrete slab  │  Start-to-Start   │  [×]       │    │
│    └─────────────────────────────────────────────────────────────────────┘    │
│                                                                               │
│    ─────────────────────────────────────────────────────────────────────────  │
│    [  Cancel  ]                                        [  Create Work Item  ] │
└──────────────────────────────────────────────────────────────────────────────┘

C2. Pending Dependency List

Pending dependencies are held in component state as an array. They are not sent to the API until after the work item is created.

interface PendingDependency {
  id: string;                // client-side UUID (crypto.randomUUID()) for list keys
  direction: 'depends_on' | 'blocks';
  workItemId: string;
  workItemTitle: string;
  dependencyType: DependencyType;
}

Each pending dependency renders as a row with four columns:

Column	Content	Token / Style
Direction pill	"depends on" or "blocks"	See Section C3
Work item name	Plain text, truncated with text-overflow: ellipsis	font-size: 0.875rem, color: var(--color-text-primary)
Type badge	Short human label (see below)	Same .dependencyType badge style as detail page
Remove button	×	Matches .deleteButton on detail page

Short type labels for the pending list (shorter than the full select option to fit the chip width):

Value	Short label
finish_to_start	Finish-to-Start
start_to_start	Start-to-Start
finish_to_finish	Finish-to-Finish
start_to_finish	Start-to-Finish

C3. Direction Pill Styling

The direction pill inside each pending dependency row uses a tinted badge to give visual separation:

"depends on" pill (this item is the successor — it depends on another):

• Background: var(--color-status-in-progress-bg) (blue tint)
• Text color: var(--color-status-in-progress-text)
• Font size: 0.75rem
• Padding: 0.25rem 0.5rem
• Border radius: 0.25rem

"blocks" pill (this item is the predecessor — it blocks another):

• Background: var(--color-status-blocked-bg) (red tint)
• Text color: var(--color-status-blocked-text)
• Font size: 0.75rem
• Padding: 0.25rem 0.5rem
• Border radius: 0.25rem

These reuse existing status badge token families that are already defined in tokens.css — no new tokens needed.

C4. "Add to list" Button

The button that adds the current picker selection to the pending list (does NOT call the API):

• Label: + Add to list
• Style: same as .addButton (primary blue, var(--color-primary) background, var(--color-primary-text) text)
• Disabled when: no work item is selected in the picker, or when the same workItemId + direction combination is already in the pending list (prevents visual duplicates)
• Alignment: align-self: flex-end within the sub-form flex column

C5. Post-Creation Dependency Submission

After createWorkItem() resolves successfully:

1. Iterate pendingDependencies sequentially (not in parallel — avoids race conditions with small datasets)
2. For each depends_on dependency: POST /api/work-items/{newItemId}/dependencies with { predecessorId: dep.workItemId, dependencyType: dep.dependencyType }
3. For each blocks dependency: POST /api/work-items/{dep.workItemId}/dependencies with { predecessorId: newItemId, dependencyType: dep.dependencyType }
4. Collect errors; do NOT roll back the work item creation
5. If any dependency creation fails, navigate to the new work item's detail page AND show an error banner: "Work item created, but [N] dependency link(s) could not be saved. You can add them manually on this page."
6. If all succeed, navigate normally with no banner

C6. Sub-form Container Styling

The dependency sub-form inside the create page uses a visually distinct container to separate it from the fields above:

/* Conceptual — not the literal class names */
.dependencySubForm {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
  padding: 1rem;
  background: var(--color-bg-secondary);
  border: 1px solid var(--color-border);
  border-radius: 0.375rem;
}

Background uses var(--color-bg-secondary) (one step darker than page background in light mode) to visually group the sub-form controls without a heavy card border.

The section header "Dependencies" above the sub-form:

• Uses the existing .label class (font-size: 0.875rem, font-weight: 500, color: var(--color-text-secondary))
• margin-bottom: 0.5rem

A horizontal rule separates the section from Tags above it:

• border-top: 1px solid var(--color-border)
• padding-top: 1.5rem
• margin-bottom: 1rem

C7. Pending List Container Styling

The pending dependency rows use the following pattern:

/* Conceptual */
.pendingList {
  display: flex;
  flex-direction: column;
  gap: 0.375rem;
  margin-top: 0.75rem;
}

.pendingItem {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding: 0.625rem 0.75rem;
  background: var(--color-bg-primary);
  border: 1px solid var(--color-border);
  border-radius: 0.375rem;
}

.pendingItemTitle {
  flex: 1;
  font-size: 0.875rem;
  color: var(--color-text-primary);
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

If pendingDependencies.length === 0, do not render the list (no empty-state message needed here — the absence of chips is self-evident).

---

D. Interactive States (All Three Areas)

Direction Toggle

State	Visual
Default	"depends on" active (blue bg), "blocks" inactive (ghost)
Hover (inactive)	background: var(--color-bg-tertiary)
Focus	outline: 2px solid var(--color-border-focus), outline-offset: 2px (standard browser focus — do not suppress with outline: none without replacement)
Active segment focus	box-shadow: var(--shadow-focus) (3px blue ring)
Disabled	opacity: 0.5, cursor: not-allowed on both segments

Type Dropdown

State	Visual
Default	border: 1px solid var(--color-border-strong), background: var(--color-bg-primary)
Focus	border-color: var(--color-primary), box-shadow: var(--shadow-focus-subtle)
Disabled	background: var(--color-bg-tertiary), cursor: not-allowed

Matches existing .dependencySelect styles — no new tokens required.

"Add dependency" / "Add to list" Button

State	Visual
Default	background: var(--color-primary), color: var(--color-primary-text)
Hover	background: var(--color-primary-hover)
Disabled	opacity: 0.5, cursor: not-allowed
Loading	Label changes to "Adding..." (detail page only); button disabled during request

Delete Button (all contexts)

State	Visual
Default	border: 1px solid var(--color-danger), color: var(--color-danger), transparent background
Hover	background: var(--color-danger), color: var(--color-primary-text)
Disabled	opacity: 0.5, cursor: not-allowed (during API request for that item)

---

E. Responsive Behaviour

Desktop (min-width: 1025px)

• All three areas render as described above — full two-segment direction toggle, full-width picker, select, and button in a column
• Pending list shows full 4-column layout

Tablet (768px – 1024px)

• No layout changes — single-column form sections already adapt naturally
• Direction toggle wraps gracefully at narrow widths: flex-wrap: wrap is NOT needed (each label is short enough for tablets)
• Pending list remains 4-column but title column truncates with ellipsis

Mobile (max-width: 767px)

• Direction toggle becomes full-width: each segment flex: 1, no wrapping
• Minimum touch target: min-height: 44px on each direction toggle segment
• Pending list collapses: direction pill + type badge stack below the title on narrow screens using flex-wrap: wrap
• "Add to list" / "Add dependency" button: width: 100% on mobile (matches existing .submitButton pattern in create page)
• Delete buttons on pending items: min-width: 44px, min-height: 44px touch target
• The create form's formActions already stacks vertically on mobile (flex-direction: column-reverse) — the new section above integrates naturally

---

F. Accessibility Requirements

Keyboard Navigation

Direction toggle:

• Both segments are focusable via Tab
• Space or Enter activates the focused segment
• Arrow keys are NOT required (only two options; Tab between them is standard for button groups)
• aria-pressed="true" on the currently active segment; aria-pressed="false" on the inactive one
• Wrapper: role="group", aria-label="Dependency direction"

WorkItemPicker (existing component — no changes needed):

• Dropdown already uses role="listbox" + role="option" — unchanged
• Clear button has aria-label="Clear selection" — unchanged

Type dropdown:

• Standard <select> with <label> association via htmlFor / id — unchanged pattern

Pending dependency list (create page):

• Each remove button: aria-label="Remove dependency: [direction] [work item title]" — e.g. "Remove dependency: depends on Install foundation"
• List region: role="list", each row role="listitem"

Confirmation modal (detail page — existing pattern):

• Modal: role="dialog", aria-modal="true", aria-labelledby pointing to modal title id
• On open: focus moves to Cancel button (safe default — avoids accidental deletion)
• On close: focus returns to the delete button that triggered it
• Escape key closes modal (existing pattern)

Screen Reader Announcements

When a pending dependency is added in the create form, announce via aria-live="polite" region: "[Work item title] added to dependencies". Implement as a single <div aria-live="polite" aria-atomic="true" className={styles.srOnly}> that receives updated text on each add/remove action.

CSS for screen-reader-only text (reusable utility):

.srOnly {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Focus Management (Create Page)

After clicking "+ Add to list":

1. Clear the WorkItemPicker selection (existing onChange('') mechanism)
2. Return focus to the direction toggle's first segment so the user can immediately add another dependency without reaching for the mouse

After removing a pending dependency chip:

• If chips remain: move focus to the next chip's remove button (or previous if last)
• If no chips remain: move focus to the WorkItemPicker input

---

G. Token Reference Summary

Element	Token(s) used
Toggle active segment bg	var(--color-primary)
Toggle active segment text	var(--color-primary-text)
Toggle inactive hover bg	var(--color-bg-tertiary)
Toggle container border	var(--color-border-strong)
Toggle inactive text	var(--color-text-secondary)
Toggle focus ring	var(--shadow-focus) (3px blue ring)
Section labels ("Direction", "Timing")	var(--color-text-muted), font-size 0.875rem, font-weight 600
Help text below type dropdown	var(--color-text-muted), font-size 0.75rem
Dependency sub-form bg (create)	var(--color-bg-secondary)
Pending item bg (create)	var(--color-bg-primary)
Pending item border	var(--color-border)
"depends on" pill bg	var(--color-status-in-progress-bg)
"depends on" pill text	var(--color-status-in-progress-text)
"blocks" pill bg	var(--color-status-blocked-bg)
"blocks" pill text	var(--color-status-blocked-text)
Type badge (existing)	var(--color-border) bg, var(--color-text-muted) text
Delete button border/text	var(--color-danger)
Delete button hover bg	var(--color-danger)
Add button bg / hover	var(--color-primary) / var(--color-primary-hover)
Add button text	var(--color-primary-text)
Section divider (create page)	var(--color-border)

---

H. Edge Cases and Error Handling

Circular Dependency (409 CIRCULAR_DEPENDENCY)

When the API returns a circular dependency error:

• Show an inline error message below the "Add dependency" button (not a modal)
• Message: "This would create a circular dependency — [Work item title] already depends on this item."
• Color: var(--color-danger), font-size 0.875rem
• The form retains all current values so the user can choose a different item

Duplicate Dependency (409 DUPLICATE_DEPENDENCY)

• Inline message: "This dependency already exists."
• Same styling as circular dependency error

Network Error

• Inline message: "Could not save dependency. Please check your connection and try again."
• A "Try again" button re-submits the same form values without clearing the picker selection

Empty States

"Depends On" list when empty:

• Current: "No predecessors" → Change to: "Nothing yet — add something below that this item must wait for."
• Color: var(--color-text-placeholder), font-style italic, font-size 0.875rem, padding 1rem, text-align center

"Blocks" list when empty:

• "Nothing yet — other work items that must wait for this one will appear here."
• Same visual style

These longer messages give homeowners context rather than a bare "No successors" that requires knowledge of the term.

---

I. What Is NOT Changing

• WorkItemPicker component API and internal behaviour — no changes
• Dependency type enum values (finish_to_start, etc.) — not exposed to users; only the human labels change
• The existing .dependencyItem, .dependencyLink, .dependencyType CSS classes on the detail page — no CSS changes to existing list item rendering
• The modal component structure and .modalContent / .modalActions layout
• The API contract — no new endpoints required; all three improvements are achievable with the existing POST and DELETE endpoints