deckhearth/lib/use-daily-ember.js

import { useEffect, useState } from 'react';

/**
 * Returns the user's current Daily Ember progress.
 *
 * Daily Ember is a gamification mechanic shown in the sidebar that
 * tracks how many "embers" the user has earned today out of a max,
 * with a bonus-XP threshold. The feature was designed as part of
 * redesign-v2 sub-convoy #5 (operator mockup, 2026-06-04). The
 * real backend (an API that derives `current` from
 * collection_activity / scan_activity / deck_activity day-bucketed
 * sums) ships in a separate convoy.
 *
 * Until that convoy lands, this hook returns hardcoded demo values
 * matching the mockup (16 / 20). The shape is intentionally stable
 * so the call-site (<DailyEmberWidget>) never needs to change.
 *
 * Returns:
 *   {
 *     current:    number,   // embers earned today
 *     max:        number,   // ceiling
 *     bonusGoal:  number,   // threshold for bonus XP (== max for now)
 *     loading:    boolean,  // mirrors the real-API loading state
 *   }
 *
 * TODO(redesign-v2 follow-up convoy `daily-ember-backend`): wire to
 *   GET /api/user/daily-ember (to be created). Until then this hook
 *   returns demo data immediately with `loading: false`.
 */
export function useDailyEmber() {
  const [state, setState] = useState({
    current: 16,
    max: 20,
    bonusGoal: 20,
    loading: false,
  });

  useEffect(() => {
    // Placeholder for the real-API fetch. Currently a no-op so the
    // hook contract (always-returning, never-null) holds without a
    // network round-trip. When the backend ships, replace with:
    //   fetch('/api/user/daily-ember', { headers: { Authorization: ... } })
    //     .then(r => r.json())
    //     .then(data => setState({ ...data, loading: false }))
  }, []);

  return state;
}