car-interface-android/lib/features/home/widgets/home_hint.dart

import 'dart:async';

import 'package:flutter/material.dart';

/// The one-time long-press hint. It is anchored to the first launch after
/// installation and never returns once the ten-minute onboarding window ends.
class HomeHint extends StatefulWidget {
  const HomeHint({
    super.key,
    required this.text,
    required this.firstLaunchAt,
    this.style,
    this.lifetime = const Duration(minutes: 10),
    this.clock,
  });

  final String text;
  final DateTime firstLaunchAt;
  final TextStyle? style;
  final Duration lifetime;
  final DateTime Function()? clock;

  @override
  State<HomeHint> createState() => _HomeHintState();
}

class _HomeHintState extends State<HomeHint> {
  Timer? _timer;
  bool _visible = true;

  @override
  void initState() {
    super.initState();
    final now = widget.clock?.call() ?? DateTime.now();
    final remaining = widget.firstLaunchAt.add(widget.lifetime).difference(now);
    if (remaining <= Duration.zero) {
      _visible = false;
    } else {
      _timer = Timer(remaining, () {
        if (mounted) setState(() => _visible = false);
      });
    }
  }

  @override
  void dispose() {
    _timer?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedSwitcher(
      duration: const Duration(milliseconds: 350),
      switchInCurve: Curves.easeOut,
      switchOutCurve: Curves.easeIn,
      child: _visible
          ? Text(
              widget.text,
              key: const ValueKey('home-hint'),
              textAlign: TextAlign.center,
              style: widget.style,
            )
          : const SizedBox.shrink(key: ValueKey('home-hint-gone')),
    );
  }
}