Neon Timeline Flutter

A highly adaptive, responsive timeline and day planner platform for Flutter. It features stable coordinate-correct drag-and-drop, snapping grid, overlap handling, continuous zoom, frame diagnostics, and legacy migration APIs.

---

Visual Showcase Gallery

Every generation is preserved in the example app. All image links below use package-relative paths, so the complete gallery is also rendered on pub.dev.

v16 Compact Mobile	v15 Ultra Planner	v14 Friendly UI

v13 Workspace Shell	v12 Neon Design System	v11 Accessible History

v10 Delight Snapping	v9 Zoom & Virtualization	v8 Drag & Resize

v7 Structured UI	v6 Planning Engine	v5 Command Center

V4 Enterprise Views

Agenda	Day	Planner

Resources	Roadmap	Studio

V5 Productivity Views

Board	Focus	Matrix	Scenarios

Theme Gallery

Aurora	Cryogenic	Ember	Hologram

Hyperion	Light	Midnight	Neon

Neural Aurora	Neural Ember	Omniverse

Seeded	Solar Flare	Spectral

---

Table of Contents

1. Installation & Requirements
2. Quick Start (V16 Compact Planner)
3. V16 Mapping with Entry Adapters
4. V16 API Parameter Reference
5. Snapping & Drag-and-Drop Interaction
6. Theming & Color Customization
7. Responsive Breakpoints & Density
8. Virtualization & Performance Policy
9. Legacy API Catalog (V15 - V10)

---

Installation & Requirements

System Requirements

• Dart SDK: >=3.12.0 <4.0.0
• Flutter SDK: >=3.44.0
• Dependencies: flutter_slidable: '>=3.1.2 <4.0.0'

Add to Project

Run this command in your package root:

flutter pub add neon_timeline_flutter

Or reference a local path dependency in pubspec.yaml:

dependencies:
  neon_timeline_flutter:
    path: /path/to/neon_timeline_flutter

Imports

Import the modern V16 unified namespace:

import 'package:neon_timeline_flutter/timeline_v16.dart';

Or keep imports focused on specific library layers:

import 'package:neon_timeline_flutter/timeline_core.dart';
import 'package:neon_timeline_flutter/timeline_views.dart';
import 'package:neon_timeline_flutter/timeline_themes.dart';

---

Quick Start (V16 Compact Planner)

Initialize the timeline by projecting your local task models onto the timeline engine.

1. Define Your Model

class Task {
  final String id;
  final String title;
  final String? note;
  final DateTime start;
  final Duration duration;
  final IconData icon;
  final NeonPlannerEntryKind kind;

  Task({
    required this.id,
    required this.title,
    this.note,
    required this.start,
    required this.duration,
    required this.icon,
    required this.kind,
  });

  Task copyWith({DateTime? start, Duration? duration}) {
    return Task(
      id: id,
      title: title,
      note: note,
      start: start ?? this.start,
      duration: duration ?? this.duration,
      icon: icon,
      kind: kind,
    );
  }
}

2. Implement the Widget

class PlannerPage extends StatefulWidget {
  const PlannerPage({super.key});

  @override
  State<PlannerPage> createState() => _PlannerPageState();
}

class _PlannerPageState extends State<PlannerPage> {
  final _day = DateTime(2026, 7, 19);

  List<Task> _tasks = [
    Task(
      id: 'sleep',
      title: 'Nachtschlaf',
      note: 'Erholungsphase',
      start: DateTime(2026, 7, 19, 0, 0),
      duration: const Duration(hours: 7, minutes: 30),
      icon: Icons.brightness_3_rounded,
      kind: NeonPlannerEntryKind.sleep,
    ),
    Task(
      id: 'focus',
      title: 'Konzentriertes Arbeiten',
      note: 'Wichtigstes Projekt zuerst',
      start: DateTime(2026, 7, 19, 8, 30),
      duration: const Duration(minutes: 50),
      icon: Icons.center_focus_strong_rounded,
      kind: NeonPlannerEntryKind.focus,
    ),
  ];

  @override
  Widget build(BuildContext context) {
    // 1. Define the adapter to project models into presentation
    final adapter = NeonPlannerEntryAdapter<Task>(
      id: (task) => task.id,
      start: (task) => task.start,
      duration: (task) => task.duration,
      presentation: (task) => NeonPlannerEntryPresentation(
        title: task.title,
        subtitle: task.note,
        icon: task.icon,
        kind: task.kind,
      ),
    );

    // 2. Render the timeline widget
    return Scaffold(
      body: SafeArea(
        child: NeonPlannerDayTimeline<Task>(
          entries: _tasks,
          adapter: adapter,
          selectedDate: _day,
          fit: NeonPlannerDayFit.scroll,
          autoResponsiveDensity: true,
          dragMode: NeonPlannerDayDragMode.time,
          snapInterval: const Duration(minutes: 5),
          enableResize: true,
          onEntryMove: (proposal) {
            setState(() {
              _tasks = _tasks.map((t) => t.id == proposal.entry.data.id
                  ? t.copyWith(start: proposal.proposedStart)
                  : t).toList();
            });
            return const NeonPlannerMutationResult.accepted('Erfolgreich verschoben.');
          },
          onEntryResize: (proposal) {
            setState(() {
              _tasks = _tasks.map((t) => t.id == proposal.entry.data.id
                  ? t.copyWith(
                      start: proposal.proposedStart,
                      duration: proposal.proposedEnd.difference(proposal.proposedStart),
                    )
                  : t).toList();
            });
            return const NeonPlannerMutationResult.accepted('Zeitdauer angepasst.');
          },
        ),
      ),
    );
  }
}

---

V16 Mapping with Entry Adapters

NeonPlannerEntryAdapter<T> adapts any data type T to the timeline presentation model without modifying your domain model.

NeonPlannerEntryAdapter<T>(
  id: (T item) => Object,        // Unique ID for delta updates
  start: (T item) => DateTime,   // Entry start boundary
  duration: (T item) => Duration,// Entry temporal length
  presentation: (T item) => NeonPlannerEntryPresentation, // Styling mapping
)

Presentation Configs (NeonPlannerEntryPresentation)

• title: Primary header label.
• subtitle: Supporting info (displayed when height is sufficient).
• metadata: High-density details line.
• icon: Displayed inside the circular hub timeline markers.
• kind: Maps to standard category colors and default badges (Sleep, Travel, Focus, Break, etc.).
• accentColor: Explicit color override bypassing category theme palettes.
• completion: Fractional value (0.0 - 1.0) rendering a progress ring around the entry node.

---

V16 API Parameter Reference

NeonPlannerDayTimeline<T>

Parameter	Type	Default	Description
entries	List<T>	Required	List of domain model items to project.
adapter	NeonPlannerEntryAdapter<T>	Required	Projector converting T into UI presentations.
selectedDate	DateTime	Required	Bounding date for the schedule.
fit	NeonPlannerDayFit	smart	Fits layout to content, scroll internally, or selects automatically (smart).
density	double	1.0	Vertical density scaler for timeline rows.
autoResponsiveDensity	bool	false	Automatically scales rows based on screen width.
dragMode	NeonPlannerDayDragMode	disabled	Allows pointer drag: disabled, time scaling, or slot suggestions.
enableResize	bool	false	Enables start/end bounds handle dragging.
snapInterval	Duration	Duration(minutes: 5)	Intervals to clamp start/end boundaries on drag.
conflictPolicy	NeonPlannerConflictPolicy	allow	Overlap behavior: allow, block, or delegate.
showGrabber	bool	true	Renders a sheet drawer notch at the container top.
showHeader	bool	true	Renders the timeline navigation header.
showMetrics	bool	true	Renders KPI summaries (Tasks count, focus hours, sleep tracker).
borderRadius	double	42.0	Outer card boundary border radius. Set to 0 for flat layouts.
backgroundColor	Color?	null	Widget base container color (defaults to theme surface).
theme	NeonPlannerTimelineThemeData?	null	Timeline visual styling values and override colors.

NeonPlannerTimelineConfig (Advanced Planner Configurations)

• zoomLevel: Standardized scale preset (e.g. balanced, comfortable).
• snapStrength: Magnetic pull radius towards adjacent entries (soft, balanced, strong).
• showTimeScrubber: Displays duration feedback tags while resizing.
• enableHaptics: Fires subtle vibration ticks on snap transitions.

---

Snapping & Drag-and-Drop Interaction

The scheduling engine handles complex temporal mutations out-of-the-box.

       [Drag Handle] -> Lift entry
            |
            v
       [Magnetic Snap] -> Pulls boundaries to adjacent gaps/slots
            |
            v
   [Conflict Checking] -> Evaluates overlap policy
            |
            v
     [onEntryMove()] -> Dispatches proposal back to host app

Mutation Callback Contracts

• onEntryMove: Fired when dragging is finalized. Returns a NeonPlannerMutationResult.
• onEntryResize: Fired when edge resizing completes. Returns a NeonPlannerMutationResult.

onEntryMove: (proposal) {
  if (proposal.hasConflict && _mustBlock) {
    return const NeonPlannerMutationResult.rejected('Kollision blockiert.');
  }
  // Persist model updates...
  return const NeonPlannerMutationResult.accepted('Änderung gespeichert.');
}

---

Theming & Color Customization

Preset Themes

The package exports visual styling configurations out-of-the-box:

• NeonPlannerTimelineThemeData.light() - Balanced, clean professional theme.
• NeonPlannerTimelineThemeData.dark() - Ambient, glow-accented dark mode.

Custom Styling Override

To override colors, shadows, and fonts:

final customTheme = NeonPlannerTimelineThemeData.light().copyWith(
  accentColor: const Color(0xFF6C5CE7),
  surfaceColor: const Color(0xFFF9F9FB),
  gridColor: const Color(0xFFE2E8F0),
);

Borderless Flat Layout

To integrate the planner seamlessly as a flat page widget (as shown in our Dashboard Showcase):

NeonPlannerDayTimeline<Task>(
  borderRadius: 0,
  showGrabber: false,
  showHeader: false,
  backgroundColor: Colors.transparent,
  theme: NeonPlannerTimelineTheme.of(context).copyWith(
    shadowColor: Theme.of(context).scaffoldBackgroundColor.withValues(alpha: 0),
  ),
  // ...
)

---

Responsive Breakpoints & Density

The planner dynamically shifts details density depending on available width constraints:

• Micro Layout (<360px): Drops text fields, merges timelines into single compact line, maps status indicator tags.
• Compact Layout (360px - 480px): Renders compact labels and side-by-side gap metrics.
• Regular Layout (>480px): Full-bleed double track, semantic timelines, expanded task descriptions, and persistent metrics.

---

Virtualization & Performance Policy

Timelines manage dense data using an adaptive virtualization layer:

• Lazy Rendering: Off-viewport entry cards are not instantiated, keeping list layout computations at a constant $O(N)$ with respect to screen size rather than task count.
• Diagnostics Overlay: Set showDiagnostics: true inside NeonPlannerTimelineConfig to audit frame times, layout cache misses, and overlaps during runtime.

---

Legacy API Catalog (V15 - V10)

All original timeline paradigms are preserved for backwards compatibility.

V15: Ultra Adaptive Planner

Semantic continuous zoom and magnetic snapping:

AdaptivePlannerTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  title: 'Ultra Planner v15',
  controller: ultraController,
  config: const UltraTimelineConfig.production(),
  onMove: moveTask,
  onResize: resizeTask,
)

V14: Friendly UI Structured Timeline

Colorful, icon-led presentation with card abstraction:

FriendlyUiStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  title: 'Friendly Planner',
  onMove: moveTask,
  entryPresentationBuilder: (context, details) =>
      FriendlyTimelineEntryPresentation(
        details: details,
        title: details.value.toString(),
        icon: Icons.calendar_month,
        tone: FriendlyTimelineIconTone.mint,
      ),
)

V13: Advanced Workspace Shell

Fully responsive workspace with built-in KPI banners, navigation rail, and commands:

AdvancedUiStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  title: 'Workspace Planner',
  metrics: const [
    AdvancedTimelineMetric(
      label: 'Completed',
      value: '3 / 5',
      icon: Icons.check_circle_rounded,
    )
  ],
  onMove: moveTask,
)

V12: Ultimate Structured Timeline

Adaptive cards, auto-scroll bounds, and focus gaps:

UltimateStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  config: const UltimateStructuredTimelineConfig.production(),
  onMove: moveTask,
)

V10: Delight Snapping Timeline

Coordinate-correct pixel-to-time mapping engine:

DelightStructuredTimeline<T>(
  values: tasks,
  engine: engine,
  selectedDate: selectedDate,
  experience: const StructuredTimelineExperience.delight(),
  onMove: moveTask,
)

---

Created and maintained by rayanMS1122. Licensed under the MIT License.