feat: Timeline Component — Theming, Composition, and Interaction Enhancements

[perasperaactual]

Context

The current timeline content type is intentionally minimal — TimelineItem accepts only year: string and event: string. This constraint keeps the schema narrow and authoring predictable. However, as sites grow more content-rich, the timeline feels limiting for:

• Corporate storytelling (company history with images, stats, milestones)
• Dashboards (visual timelines with interactive elements)
• Long-form timelines (where progressive disclosure improves readability)

We need a thoughtful expansion of the timeline without bloating the schema into an unmaintainable maze.

---

Desired Behavior

1. Theming Per-Event (Nice-to-Have)

Currently, the timeline heading can be styled via heading.textColor, but there is no per-event theming. Users want:

- type: timeline
  label: company-history
  items:
    - year: "2018"
      event: "Series A funding — $12M raised"
      style: featured    # vs default | muted | highlight
    - year: "2019"
      event: "Expanded to 3 new markets"
      style: muted

Proposed TimelineItem fields:

• style?: 'default' | 'featured' | 'highlight' | 'muted'
• yearColor?: string (override the accent year label)
• cardBackground?: string (independent card styling)

---

2. Complex Composition Inside Events (Nice-to-Have)

Today, event is a plain string. Rich storytelling requires embedded content:

- type: timeline
  label: company-history
  items:
    - year: "2018"
      content_items:
        - type: text_block
          textBlocks:
            - text: "Series A funding closed"
              textSize: h3
        - type: grid
          columns:
            - width: 4
              content_items:
                - type: media
                  src: ./office-2018.jpg
                  type: image
            - width: 8
              content_items:
                - type: feature_list
                  items:
                    - icon: { type: icon, src: TrendingUp }
                      heading: "$12M Raised"
                      description: "From tier-1 investors"

This mirrors the grid column pattern — nested content_items arrays inside timeline events.

---

3. Horizontal Mode (Nice-to-Have)

Vertical timelines work for long reading; horizontal timelines work for visual dashboards:

- type: timeline
  label: roadmap
  layout: horizontal    # vs vertical (default)
  responsive: true     # vertical on mobile, horizontal on desktop
  items:
    - year: "Q1"
      event: "Core platform launch"
    - year: "Q2"
      event: "Mobile app release"

Implementation consideration: The layout direction could be a content type variant (timeline_horizontal vs timeline) or a field on timeline. A field is simpler; a new type is more explicit. Open to either approach.

---

4. Progressive Disclosure / Hover Reveal (Nice-to-Have)

For timelines with 10+ events, showing everything is overwhelming:

- type: timeline
  label: company-history
  interaction: hover    # vs click | show-all (default)
  preview:
    - text: "Year + short text only"
      textSize: body2
  items:
    - year: "2018"
      event: "Full milestone description..."
      preview: "2018: Series A"

Implementation: This is primarily a UI concern, but the schema should support the preview content so pre-rendering works correctly.

---

5. Date-Based Automatic Layout (Nice-to-Have)

Today, spacing between events is equal regardless of time gaps. Users want proportional spacing:

- type: timeline
  label: history
  spacingMode: proportional  # vs equal (default)
  showCurrentMarker: true
  items:
    - year: "2018-03-15"
      event: "Founded"
    - year: "2018-12-01"
      event: "First product launch"
    - year: "2020-06-20"
      event: "Series A"

Implementation note: If year becomes a date string (ISO 8601), the framework can calculate intervals automatically.

---

Current Behavior

- type: timeline
  label: engagement-phases
  heading:
    text: "How an Engagement Unfolds"
    textSize: h2
    textColor: textSecondary
  items:
    - year: "Phase 1"
      event: "Understand the Context — Before recommending solutions..."
    - year: "Phase 2"
      event: "Identify Structural Failures..."
  background: background

• Only year: string and event: string per item
• No per-event styling
• No nested content
• No layout variants
• No progressive disclosure

---

Suggested Approach

Phase 1 — Quick Wins (Low Effort, High Value):

1. Add style, yearColor, cardBackground to TimelineItem schema
2. Add layout: horizontal field with responsive breakpoint support

Phase 2 — Architectural Investment:
3. Add content_items array to TimelineItem (mirrors grid columns pattern)
4. Add interaction: hover with preview text for progressive disclosure

Phase 3 — Nice-to-Have Polish:
5. Convert year to date parsing for proportional spacing
6. Add showCurrentMarker boolean

Schema evolution: Follow the same pattern used by grid columns — the GridColumn type has content_items, and TimelineItem can mirror this.

---

Priority

Nice-to-Have — The current timeline works for basic use cases. These enhancements address specific advanced scenarios. Consider for v2.x roadmap.

---

Related

• timeline content type (current)
• grid content type (reference for nested content_items pattern)
• feature_list content type (reference for item-based composition)