@tetherto/mdk-react-devkit 0.0.0-stage → 0.12.1

package/dist/domain/components/timeframe/timeframe-controls/timeframe-controls.helper.d.ts

@@ -0,0 +1,66 @@
+import { type TimeframeTypeValue } from '../../../constants/ranges';
+type Month = {
+    month: number;
+    label: string;
+};
+type Week = {
+    /** Monday 00:00:00.000 (local time) that opens the week */
+    start: Date;
+    /** Sunday 23:59:59.999 (local time) that closes the week, capped to the end of yesterday */
+    end: Date;
+    /** Option text, `DD/MM - DD/MM` in the selected timezone */
+    label: string;
+    /** Year of the week's end date in the selected timezone; sent as `year` to `onRangeChange` */
+    bucketYear: number;
+    /** Month (0-11) of the week's end date in the selected timezone; sent as `month` to `onRangeChange` */
+    bucketMonth: number;
+    /** True when the week starts after the end of yesterday; the option is shown but not selectable */
+    disabled?: boolean;
+};
+export declare const YEARS: number[];
+export declare const MONTHS: Month[];
+export declare const rangeOfYear: (year: number) => [Date, Date];
+export declare const rangeOfMonth: (year: number, month: number) => [Date, Date];
+export declare const weeksOfMonth: (year: number, month: number, timezone?: string) => Week[];
+export declare const monthsForYear: (y: number) => Month[];
+export type WeekRangeCacheEntry = {
+    start: Date;
+    end: Date;
+    disabled?: boolean;
+};
+export declare const buildWeeksCache: (timezone: string) => Record<string, WeekRangeCacheEntry[]>;
+export declare const findWeekMatchInCalendar: (weeksCache: Record<string, WeekRangeCacheEntry[]>, startMs: number, endMs: number) => {
+    y: number;
+    m: number;
+    row: WeekRangeCacheEntry;
+} | null;
+/** Default year picker: first year in `YEARS`, or calendar year of `now`. */
+export declare const defaultSelectedYear: (now: Date) => number;
+export declare const defaultSelectedMonth: (now: Date) => number;
+export declare const monthTreeToken: (year: number, month: number) => string;
+export declare const parseMonthTreeToken: (token: string) => {
+    year: number;
+    month: number;
+} | null;
+export declare const weekTreeToken: (year: number, month: number, start: Date) => string;
+export declare const parseWeekTreeToken: (token: string) => {
+    year: number;
+    month: number;
+    startTs: number;
+} | null;
+type WeekRowLite = {
+    start: Date;
+    disabled?: boolean;
+};
+/** Validates the controlled week select value against current option rows (flat or tree). */
+export declare function resolveWeekSelectDisplayValue(params: {
+    activeTimeframe: 'year' | 'month' | 'week';
+    selectedWeekKey: string;
+    weekTree: boolean;
+    /** Flat mode: weeks for the visible month only. */
+    visibleWeeks: WeekRowLite[];
+    /** Tree mode: resolve item by calendar month. */
+    getWeeksForMonth: (year: number, month: number) => WeekRowLite[];
+}): string;
+export declare const inferTimeframeTypeFromRange: (start: Date, end: Date, weeksCache: Record<string, WeekRangeCacheEntry[]>) => TimeframeTypeValue | null;
+export {};

package/dist/domain/components/timeframe/timeframe-controls/timeframe-controls.helper.js

@@ -0,0 +1,193 @@
+import { toZonedTime } from 'date-fns-tz';
+import _filter from 'lodash/filter';
+import _padStart from 'lodash/padStart';
+import _reject from 'lodash/reject';
+import { TIMEFRAME_TYPE } from '../../../constants/ranges';
+const MS_PER_DAY = 24 * 60 * 60 * 1_000;
+export const YEARS = Array.from({ length: 3 }, (_, i) => new Date().getFullYear() - i);
+const anchorYear = YEARS[0] ?? new Date().getFullYear();
+export const MONTHS = Array.from({ length: 12 }, (_, i) => ({
+    month: i,
+    label: new Date(anchorYear, i, 1).toLocaleString('en', { month: 'long' }),
+}));
+const endOfYesterday = () => {
+    const d = new Date();
+    d.setHours(23, 59, 59, 999);
+    d.setTime(d.getTime() - MS_PER_DAY);
+    return d;
+};
+const capToYesterday = (d) => new Date(Math.min(d.getTime(), endOfYesterday().getTime()));
+export const rangeOfYear = (year) => {
+    const start = new Date(year, 0, 1, 0, 0, 0, 0);
+    const end = capToYesterday(new Date(year, 11, 31, 23, 59, 59, 999));
+    return [start, end];
+};
+export const rangeOfMonth = (year, month) => {
+    const start = new Date(year, month, 1, 0, 0, 0, 0);
+    const end = capToYesterday(new Date(year, month + 1, 0, 23, 59, 59, 999));
+    return [start, end];
+};
+const addDays = (date, days) => {
+    const d = new Date(date);
+    d.setDate(d.getDate() + days);
+    return d;
+};
+const isSameZonedDay = (a, b) => a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate();
+export const weeksOfMonth = (year, month, timezone = 'UTC') => {
+    const firstDay = new Date(year, month, 1);
+    firstDay.setHours(0, 0, 0, 0);
+    const lastDay = new Date(year, month + 1, 0);
+    lastDay.setHours(23, 59, 59, 999);
+    const eoy = endOfYesterday();
+    const firstDayInTz = toZonedTime(firstDay, timezone);
+    const firstWeekStart = new Date(firstDayInTz);
+    const dayOfWeek = firstWeekStart.getDay();
+    const mondayBasedDay = (dayOfWeek + 6) % 7;
+    firstWeekStart.setDate(firstWeekStart.getDate() - mondayBasedDay);
+    const result = [];
+    let ws = firstWeekStart;
+    for (let i = 0; i < 6; i++) {
+        if (ws.getTime() > eoy.getTime())
+            break;
+        const we = addDays(ws, 6);
+        const overlaps = we >= firstDay && ws <= lastDay;
+        if (!overlaps) {
+            ws = addDays(ws, 7);
+            continue;
+        }
+        const start = new Date(ws);
+        start.setHours(0, 0, 0, 0);
+        const end = capToYesterday(new Date(we.setHours(23, 59, 59, 999)));
+        const rawStartInTz = toZonedTime(start, timezone);
+        const endInTz = toZonedTime(end, timezone);
+        const startInTz = isSameZonedDay(rawStartInTz, endInTz)
+            ? addDays(rawStartInTz, -1)
+            : rawStartInTz;
+        const weekStartMonth = startInTz.getMonth();
+        const weekEndMonth = endInTz.getMonth();
+        if (weekStartMonth === month || weekEndMonth === month) {
+            const pad = (n) => _padStart(String(n), 2, '0');
+            const d1 = startInTz.getDate();
+            const m1 = startInTz.getMonth();
+            const d2 = endInTz.getDate();
+            const m2 = endInTz.getMonth();
+            const bucketYear = endInTz.getFullYear();
+            const bucketMonth = endInTz.getMonth();
+            const label = `${pad(d1)}/${pad(m1 + 1)} - ${pad(d2)}/${pad(m2 + 1)}`;
+            result.push({
+                start,
+                end,
+                label,
+                bucketYear,
+                bucketMonth,
+                disabled: start > eoy,
+            });
+        }
+        ws = addDays(ws, 7);
+    }
+    return result;
+};
+export const monthsForYear = (y) => {
+    const yesterday = endOfYesterday();
+    if (y === yesterday.getFullYear()) {
+        const lastVisibleMonth = yesterday.getMonth();
+        return _filter(MONTHS, ({ month }) => month <= lastVisibleMonth);
+    }
+    return MONTHS;
+};
+export const buildWeeksCache = (timezone) => {
+    const acc = {};
+    for (const year of YEARS) {
+        for (let month = 0; month < 12; month++) {
+            acc[`${year}-${month}`] = weeksOfMonth(year, month, timezone).map((w) => ({
+                start: w.start,
+                end: w.end,
+                disabled: w.disabled,
+            }));
+        }
+    }
+    return acc;
+};
+export const findWeekMatchInCalendar = (weeksCache, startMs, endMs) => {
+    for (const y of YEARS) {
+        for (let m = 0; m < 12; m++) {
+            const weeks = weeksCache[`${y}-${m}`] ?? [];
+            const match = weeks.find((w) => !w.disabled && w.start.getTime() === startMs && w.end.getTime() === endMs);
+            if (match)
+                return { y, m, row: match };
+        }
+    }
+    return null;
+};
+/** Default year picker: first year in `YEARS`, or calendar year of `now`. */
+export const defaultSelectedYear = (now) => YEARS[0] ?? now.getFullYear();
+export const defaultSelectedMonth = (now) => now.getMonth();
+export const monthTreeToken = (year, month) => `${year}|${month}`;
+export const parseMonthTreeToken = (token) => {
+    const parts = token.split('|');
+    if (parts.length !== 2)
+        return null;
+    const year = Number(parts[0]);
+    const month = Number(parts[1]);
+    if (!Number.isFinite(year) || !Number.isFinite(month))
+        return null;
+    return { year, month };
+};
+export const weekTreeToken = (year, month, start) => `${year}|${month}|${start.getTime()}`;
+export const parseWeekTreeToken = (token) => {
+    const parts = token.split('|');
+    if (parts.length !== 3)
+        return null;
+    const year = Number(parts[0]);
+    const month = Number(parts[1]);
+    const startTs = Number(parts[2]);
+    if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(startTs))
+        return null;
+    return { year, month, startTs };
+};
+/** Validates the controlled week select value against current option rows (flat or tree). */
+export function resolveWeekSelectDisplayValue(params) {
+    const { activeTimeframe, selectedWeekKey, weekTree, visibleWeeks, getWeeksForMonth } = params;
+    if (activeTimeframe !== 'week' || !selectedWeekKey)
+        return '';
+    if (weekTree) {
+        const parsed = parseWeekTreeToken(selectedWeekKey);
+        if (!parsed)
+            return '';
+        const row = getWeeksForMonth(parsed.year, parsed.month).find((w) => w.start.getTime() === parsed.startTs && !w.disabled);
+        return row ? selectedWeekKey : '';
+    }
+    const row = visibleWeeks.find((w) => String(w.start.getTime()) === selectedWeekKey && !w.disabled);
+    return row ? selectedWeekKey : '';
+}
+const matchesBoundary = (a, b, toleranceMs = 2) => Math.abs(a - b) <= toleranceMs;
+export const inferTimeframeTypeFromRange = (start, end, weeksCache) => {
+    const startMs = start.getTime();
+    const endMs = end.getTime();
+    for (const year of YEARS) {
+        const [ys, ye] = rangeOfYear(year);
+        if (matchesBoundary(startMs, ys.getTime()) && matchesBoundary(endMs, ye.getTime()))
+            return TIMEFRAME_TYPE.YEAR;
+    }
+    for (const year of YEARS) {
+        for (const { month } of monthsForYear(year)) {
+            const [ms, me] = rangeOfMonth(year, month);
+            if (matchesBoundary(startMs, ms.getTime()) && matchesBoundary(endMs, me.getTime()))
+                return TIMEFRAME_TYPE.MONTH;
+        }
+    }
+    for (const year of YEARS) {
+        for (const { month } of MONTHS) {
+            const weeks = _reject(weeksCache[`${year}-${month}`] ?? [], 'disabled');
+            for (const w of weeks) {
+                if (matchesBoundary(w.start.getTime(), startMs) &&
+                    matchesBoundary(w.end.getTime(), endMs)) {
+                    return TIMEFRAME_TYPE.WEEK;
+                }
+            }
+        }
+    }
+    return null;
+};

package/dist/domain/components/timeframe/timeframe-controls/timeframe-controls.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, cn, MultiLevelSelect, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '../../../../primitives/index.js';
+import { monthsForYear, monthTreeToken, YEARS } from './timeframe-controls.helper';
+import { TimeframeWeekFlatContent, TimeframeWeekTreeContent, } from './timeframe-controls-week-content';
+import { useTimeframeControls } from './use-timeframe-controls';
+/**
+ * Date-range picker for financial reporting pages — supports year, month, and
+ * week granularity via connected selects.
+ *
+ * @category filters
+ * @domain financial-reporting
+ * @kernelCapability financial-reporting
+ * @tier agent-ready
+ */
+export const TimeframeControls = ({ hint, onReset, dateRange, onRangeChange, layout = 'horizontal', onTimeframeTypeChange, showResetButton = false, isWeekSelectVisible = true, isMonthSelectVisible = true, timeframeType: timeframeTypeProp, }) => {
+    const weekTree = isMonthSelectVisible && isWeekSelectVisible;
+    const { timezone, selectedYear, selectedMonth, visibleWeeks, handleYearChange, handleMonthTreeChange, handleWeekChangeFlat, handleWeekChangeFromTree, yearSelectValue, monthSelectValue, resolvedWeekValue, } = useTimeframeControls({
+        dateRange,
+        timeframeType: timeframeTypeProp,
+        onRangeChange,
+        onTimeframeTypeChange,
+        isWeekSelectVisible,
+        weekTree,
+    });
+    const banded = Boolean(hint);
+    return (_jsxs("div", { className: cn('mdk-timeframe-controls', banded && 'mdk-timeframe-controls--banded', layout === 'stacked' && 'mdk-timeframe-controls--stacked'), children: [hint ? _jsx("p", { className: "mdk-timeframe-controls__hint", children: hint }) : null, _jsxs("div", { className: cn('mdk-timeframe-controls__toolbar', showResetButton && 'mdk-timeframe-controls__toolbar--with-reset'), children: [_jsxs("div", { className: "mdk-timeframe-controls__selects", children: [_jsx("div", { className: "mdk-timeframe-controls__control", children: _jsxs(Select, { value: yearSelectValue, onValueChange: handleYearChange, children: [_jsx(SelectTrigger, { className: "mdk-timeframe-controls__control-target", "aria-label": "Year", children: _jsx(SelectValue, { placeholder: "Year" }) }), _jsx(SelectContent, { className: "mdk-timeframe-controls__select-content", children: YEARS.map((y) => (_jsx(SelectItem, { value: String(y), children: String(y) }, y))) })] }) }), isMonthSelectVisible ? (_jsx("div", { className: "mdk-timeframe-controls__control", children: _jsxs(Select, { value: monthSelectValue, onValueChange: handleMonthTreeChange, children: [_jsx(SelectTrigger, { className: "mdk-timeframe-controls__control-target", "aria-label": "Month", children: _jsx(SelectValue, { placeholder: "Month" }) }), _jsx(SelectContent, { className: "mdk-timeframe-controls__select-content mdk-timeframe-controls__multi-level-content", children: YEARS.map((year) => (_jsx(MultiLevelSelect.Section, { sectionTitle: String(year), defaultOpen: year === selectedYear, children: [...monthsForYear(year)].reverse().map(({ month, label }) => (_jsx(SelectItem, { value: monthTreeToken(year, month), children: label }, `${year}-${month}`))) }, year))) })] }) })) : null, isWeekSelectVisible ? (_jsx("div", { className: "mdk-timeframe-controls__control", children: _jsxs(Select, { value: resolvedWeekValue, onValueChange: weekTree ? handleWeekChangeFromTree : handleWeekChangeFlat, children: [_jsx(SelectTrigger, { className: "mdk-timeframe-controls__control-target", "aria-label": "Week", children: _jsx(SelectValue, { placeholder: "Week" }) }), _jsx(SelectContent, { className: cn('mdk-timeframe-controls__select-content', weekTree && 'mdk-timeframe-controls__multi-level-content'), children: weekTree ? (_jsx(TimeframeWeekTreeContent, { timezone: timezone, selectedYear: selectedYear, selectedMonth: selectedMonth })) : (_jsx(TimeframeWeekFlatContent, { visibleWeeks: visibleWeeks })) })] }) })) : null] }), showResetButton && (_jsx(Button, { type: "button", variant: "secondary", className: "mdk-timeframe-controls__reset", onClick: onReset, children: "Reset" }))] })] }));
+};

package/dist/domain/components/timeframe/timeframe-controls/timeframe-controls.types.d.ts

@@ -0,0 +1,61 @@
+import type { TimeframeTypeValue } from '../../../constants/ranges';
+export type TimeframeControlsDateRange = {
+    /** Range start (epoch ms); the year/month/week pickers sync to this date */
+    start: number;
+    /** Range end (epoch ms); matched with `start` against calendar weeks to restore a week selection */
+    end: number;
+};
+export type TimeframeControlsOnRangeChange = (range: [Date, Date], options: Partial<{
+    year: number;
+    month: number;
+    period: string;
+}>) => void;
+export type TimeframeControlsProps = Partial<{
+    /** Helper text below the controls */
+    hint: string;
+    /** Called when the Reset button is clicked */
+    onReset: VoidFunction;
+    /**
+     * Shows the Reset button
+     * @default false
+     */
+    showResetButton: boolean;
+    /**
+     * Show week selector
+     * @default true
+     */
+    isWeekSelectVisible: boolean;
+    /**
+     * Show month selector
+     * @default true
+     */
+    isMonthSelectVisible: boolean;
+    /**
+     * Layout direction
+     * @default 'horizontal'
+     */
+    layout: 'horizontal' | 'stacked';
+    /** Current date range */
+    dateRange: TimeframeControlsDateRange;
+    /** Active timeframe type */
+    timeframeType: TimeframeTypeValue | null;
+    /** Called when the range changes */
+    onRangeChange: TimeframeControlsOnRangeChange;
+    /** Called when timeframe type changes */
+    onTimeframeTypeChange: (type: TimeframeTypeValue) => void;
+}>;
+export type TimeSelection = {
+    end: Date;
+    start: Date;
+    year: number;
+    month?: number;
+    label?: string;
+};
+export type WeekData = {
+    start: Date;
+    end: Date;
+    label?: string;
+    bucketYear?: number;
+    bucketMonth?: number;
+    disabled?: boolean;
+};

package/dist/domain/components/timeframe/timeframe-controls/timeframe-controls.types.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/components/timeframe/timeframe-controls/use-timeframe-controls.d.ts

@@ -0,0 +1,37 @@
+import type { TimeframeControlsProps } from './timeframe-controls.types';
+/** Which single control “owns” the range: others show placeholders (mutually exclusive UI). */
+export type ActiveTimeframe = 'year' | 'month' | 'week';
+export type UseTimeframeControlsParams = Pick<TimeframeControlsProps, 'dateRange' | 'timeframeType' | 'onRangeChange' | 'onTimeframeTypeChange'> & {
+    isWeekSelectVisible: boolean;
+    /** Both month + week selects visible → week nested tree. */
+    weekTree: boolean;
+};
+/**
+ * Core state machine for TimeframeControls — owns year / month / week
+ * selection and resolves the date-range output.
+ *
+ * @category filters
+ * @domain financial-reporting
+ * @kernelCapability financial-reporting
+ * @tier agent-ready
+ */
+export declare const useTimeframeControls: ({ dateRange, timeframeType: timeframeTypeProp, onRangeChange, onTimeframeTypeChange, isWeekSelectVisible, weekTree, }: UseTimeframeControlsParams) => {
+    timezone: string;
+    selectedYear: number;
+    selectedMonth: number;
+    visibleWeeks: {
+        start: Date;
+        end: Date;
+        label: string;
+        bucketYear: number;
+        bucketMonth: number;
+        disabled?: boolean;
+    }[];
+    handleYearChange: (value: string) => void;
+    handleMonthTreeChange: (value: string) => void;
+    handleWeekChangeFlat: (value: string) => void;
+    handleWeekChangeFromTree: (value: string) => void;
+    yearSelectValue: string;
+    monthSelectValue: string;
+    resolvedWeekValue: string;
+};

package/dist/domain/components/timeframe/timeframe-controls/use-timeframe-controls.js

@@ -0,0 +1,184 @@
+import { useTimezone } from '@tetherto/mdk-react-adapter';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { PERIOD, TIMEFRAME_TYPE, } from '../../../constants/ranges.js';
+import { buildWeeksCache, defaultSelectedMonth, defaultSelectedYear, findWeekMatchInCalendar, inferTimeframeTypeFromRange, monthsForYear, monthTreeToken, parseMonthTreeToken, parseWeekTreeToken, rangeOfMonth, rangeOfYear, resolveWeekSelectDisplayValue, weeksOfMonth, weekTreeToken, } from './timeframe-controls.helper';
+const PERIOD_BY_TIMEFRAME = {
+    [TIMEFRAME_TYPE.YEAR]: PERIOD.MONTHLY,
+    [TIMEFRAME_TYPE.MONTH]: PERIOD.DAILY,
+    [TIMEFRAME_TYPE.WEEK]: PERIOD.DAILY,
+};
+/**
+ * Core state machine for TimeframeControls — owns year / month / week
+ * selection and resolves the date-range output.
+ *
+ * @category filters
+ * @domain financial-reporting
+ * @kernelCapability financial-reporting
+ * @tier agent-ready
+ */
+export const useTimeframeControls = ({ dateRange, timeframeType: timeframeTypeProp, onRangeChange, onTimeframeTypeChange, isWeekSelectVisible, weekTree, }) => {
+    const { timezone } = useTimezone();
+    const weeksCache = useMemo(() => buildWeeksCache(timezone), [timezone]);
+    const [selectedYear, setSelectedYear] = useState(() => defaultSelectedYear(new Date()));
+    const [selectedMonth, setSelectedMonth] = useState(() => defaultSelectedMonth(new Date()));
+    /** Flat mode: week start timestamp. Tree mode: `year|month|startTs`. */
+    const [selectedWeekKey, setSelectedWeekKey] = useState('');
+    const [activeTimeframe, setActiveTimeframe] = useState('month');
+    const applyRange = useCallback((range, options, nextType) => {
+        onRangeChange?.(range, { ...options, period: PERIOD_BY_TIMEFRAME[nextType] });
+        onTimeframeTypeChange?.(nextType);
+    }, [onRangeChange, onTimeframeTypeChange]);
+    const pushSelection = useCallback((args) => {
+        const { nextActive, range, meta, tf, picker } = args;
+        setActiveTimeframe(nextActive);
+        if (picker.setYear !== undefined)
+            setSelectedYear(picker.setYear);
+        if (picker.setMonth !== undefined)
+            setSelectedMonth(picker.setMonth);
+        if (picker.weekKey !== undefined)
+            setSelectedWeekKey(picker.weekKey);
+        applyRange(range, meta, tf);
+    }, [applyRange]);
+    const syncFromExternalRange = useCallback(() => {
+        if (!dateRange?.start || !dateRange?.end)
+            return;
+        const start = new Date(dateRange.start);
+        const end = new Date(dateRange.end);
+        const inferred = inferTimeframeTypeFromRange(start, end, weeksCache);
+        const effectiveType = timeframeTypeProp ?? inferred;
+        const syncPickerToStartMonth = (nextActive) => {
+            setActiveTimeframe(nextActive);
+            setSelectedYear(start.getFullYear());
+            setSelectedMonth(start.getMonth());
+            setSelectedWeekKey('');
+        };
+        if (!effectiveType) {
+            setSelectedYear(defaultSelectedYear(new Date()));
+            setSelectedMonth(defaultSelectedMonth(new Date()));
+            setSelectedWeekKey('');
+            setActiveTimeframe('month');
+            return;
+        }
+        if (effectiveType === TIMEFRAME_TYPE.YEAR) {
+            syncPickerToStartMonth('year');
+            return;
+        }
+        if (effectiveType === TIMEFRAME_TYPE.MONTH) {
+            syncPickerToStartMonth('month');
+            return;
+        }
+        if (effectiveType === TIMEFRAME_TYPE.WEEK) {
+            const startMs = start.getTime();
+            const endMs = end.getTime();
+            const picked = findWeekMatchInCalendar(weeksCache, startMs, endMs);
+            if (picked) {
+                setActiveTimeframe('week');
+                setSelectedYear(picked.y);
+                setSelectedMonth(picked.m);
+                setSelectedWeekKey(weekTreeToken(picked.y, picked.m, picked.row.start));
+            }
+            else {
+                syncPickerToStartMonth('month');
+            }
+        }
+    }, [dateRange, timeframeTypeProp, weeksCache]);
+    useEffect(() => {
+        syncFromExternalRange();
+    }, [syncFromExternalRange]);
+    const visibleMonths = useMemo(() => monthsForYear(selectedYear), [selectedYear]);
+    useEffect(() => {
+        const allowed = new Set(visibleMonths.map((m) => m.month));
+        if (!allowed.has(selectedMonth)) {
+            const fallback = visibleMonths.at(-1)?.month ?? 0;
+            setSelectedMonth(fallback);
+        }
+    }, [selectedMonth, visibleMonths]);
+    const visibleWeeks = useMemo(() => {
+        if (!isWeekSelectVisible)
+            return [];
+        return weeksOfMonth(selectedYear, selectedMonth, timezone);
+    }, [isWeekSelectVisible, selectedMonth, selectedYear, timezone]);
+    useEffect(() => {
+        if (!isWeekSelectVisible || visibleWeeks.length === 0)
+            return;
+        if (!weekTree) {
+            const keys = new Set(visibleWeeks.map((w) => String(w.start.getTime())));
+            if (selectedWeekKey && !keys.has(selectedWeekKey)) {
+                setSelectedWeekKey('');
+            }
+        }
+    }, [isWeekSelectVisible, selectedWeekKey, visibleWeeks, weekTree]);
+    const handleYearChange = useCallback((value) => {
+        const year = Number(value);
+        pushSelection({
+            nextActive: 'year',
+            range: rangeOfYear(year),
+            meta: { year },
+            tf: TIMEFRAME_TYPE.YEAR,
+            picker: { setYear: year, weekKey: '' },
+        });
+    }, [pushSelection]);
+    const handleMonthTreeChange = useCallback((value) => {
+        const parsed = parseMonthTreeToken(value);
+        if (!parsed)
+            return;
+        const { year, month } = parsed;
+        pushSelection({
+            nextActive: 'month',
+            range: rangeOfMonth(year, month),
+            meta: { year, month },
+            tf: TIMEFRAME_TYPE.MONTH,
+            picker: { setYear: year, setMonth: month, weekKey: '' },
+        });
+    }, [pushSelection]);
+    const handleWeekChangeFlat = useCallback((value) => {
+        const week = visibleWeeks.find((w) => String(w.start.getTime()) === value);
+        if (!week || week.disabled)
+            return;
+        pushSelection({
+            nextActive: 'week',
+            range: [week.start, week.end],
+            meta: { year: week.bucketYear, month: week.bucketMonth },
+            tf: TIMEFRAME_TYPE.WEEK,
+            picker: { weekKey: value },
+        });
+    }, [pushSelection, visibleWeeks]);
+    const handleWeekChangeFromTree = useCallback((value) => {
+        const parsed = parseWeekTreeToken(value);
+        if (!parsed)
+            return;
+        const { year, month, startTs } = parsed;
+        const row = weeksOfMonth(year, month, timezone).find((w) => w.start.getTime() === startTs && !w.disabled);
+        if (!row)
+            return;
+        pushSelection({
+            nextActive: 'week',
+            range: [row.start, row.end],
+            meta: { year: row.bucketYear, month: row.bucketMonth },
+            tf: TIMEFRAME_TYPE.WEEK,
+            picker: { setYear: year, setMonth: month, weekKey: value },
+        });
+    }, [pushSelection, timezone]);
+    const yearSelectValue = activeTimeframe === 'year' ? String(selectedYear) : '';
+    const monthSelectValue = activeTimeframe === 'month' ? monthTreeToken(selectedYear, selectedMonth) : '';
+    const resolvedWeekValue = useMemo(() => resolveWeekSelectDisplayValue({
+        activeTimeframe,
+        selectedWeekKey,
+        weekTree,
+        visibleWeeks,
+        getWeeksForMonth: (y, m) => weeksOfMonth(y, m, timezone),
+    }), [activeTimeframe, selectedWeekKey, timezone, weekTree, visibleWeeks]);
+    return {
+        timezone,
+        selectedYear,
+        selectedMonth,
+        visibleWeeks,
+        handleYearChange,
+        handleMonthTreeChange,
+        handleWeekChangeFlat,
+        handleWeekChangeFromTree,
+        yearSelectValue,
+        monthSelectValue,
+        resolvedWeekValue,
+    };
+};

package/dist/domain/components/timeframe/use-financial-date-range.d.ts

@@ -0,0 +1,39 @@
+import { type ReactElement } from 'react';
+import { type PeriodValue } from '../../constants/ranges';
+export type FinancialDateRange = {
+    start: number;
+    end: number;
+    period?: PeriodValue;
+};
+export type UseFinancialDateRangeOptions = {
+    defaultPeriod?: PeriodValue;
+    timezone?: string;
+};
+export type FinancialRangeChangeOptions = {
+    year?: number;
+    month?: number;
+    period?: PeriodValue;
+};
+export type UseFinancialDateRangeResult = {
+    dateRange: FinancialDateRange | null;
+    handleRangeChange: (dates: [Date, Date] | null, rangeOptions?: FinancialRangeChangeOptions) => void;
+    onDateRangeReset: () => void;
+    datePicker: ReactElement;
+};
+/**
+ * Converts a calendar range (wall date fields from the two Date instances) into
+ * UTC epoch ms boundaries in `timezone` (full month vs day span, end clamped to "yesterday" when still in the future).
+ */
+export declare const rangeDatesToFinancialMs: (range: [Date, Date], timezone: string) => {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Resolves the active financial date range (start/end) used by every reporting-section query.
+ *
+ * @category widgets
+ * @domain financial-reporting
+ * @kernelCapability financial-reporting
+ * @tier agent-ready
+ */
+export declare const useFinancialDateRange: (options?: UseFinancialDateRangeOptions) => UseFinancialDateRangeResult;

package/dist/domain/components/timeframe/use-financial-date-range.example.d.ts

@@ -0,0 +1 @@
+export declare const UseFinancialDateRangeExample: () => import("react").JSX.Element;

package/dist/domain/components/timeframe/use-financial-date-range.example.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFinancialDateRange } from '@tetherto/mdk-react-devkit';
+const FinancialDateRangeDisplay = () => {
+    const { dateRange } = useFinancialDateRange({ defaultPeriod: 'monthly' });
+    return (_jsx("div", { className: "mdk-example-row", children: _jsx("pre", { children: JSON.stringify(dateRange, null, 2) }) }));
+};
+export const UseFinancialDateRangeExample = () => _jsx(FinancialDateRangeDisplay, {});