@tuturuuu/ui 0.10.0 → 0.11.0

package/src/components/ui/finance/invoices/utils.ts

@@ -69,6 +69,8 @@ export const getLinkedFinanceCategorySelection = (
 
 const MONTH_VALUE_PATTERN = /^(\d{4})-(\d{2})$/;
 const DATE_VALUE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+export const MAX_PREPAID_MONTH_COUNT = 12;
+export const PREPAID_MONTH_OPTION_HORIZON = 12;
 
 export const parseLocalCalendarDate = (
   value: string | Date | null | undefined
@@ -122,6 +124,79 @@ export const formatMonthLabel = (month: string, locale: string): string => {
   });
 };
 
+export const addMonthsToMonthValue = (
+  month: string,
+  monthOffset: number
+): string => {
+  const date = getMonthStartDate(month);
+  if (Number.isNaN(date.getTime())) return month;
+
+  date.setMonth(date.getMonth() + monthOffset);
+  return formatMonthValue(date);
+};
+
+export const normalizePrepaidMonthCount = (
+  value: number | null | undefined
+): number => {
+  if (!Number.isFinite(value) || !value) return 1;
+
+  return Math.min(MAX_PREPAID_MONTH_COUNT, Math.max(1, Math.trunc(value)));
+};
+
+export const getCoverageMonths = (
+  selectedMonth: string,
+  prepaidMonthCount = 1
+): string[] => {
+  const monthCount = normalizePrepaidMonthCount(prepaidMonthCount);
+  const startMonth = getMonthStartDate(selectedMonth);
+  if (Number.isNaN(startMonth.getTime())) return [];
+
+  return Array.from({ length: monthCount }, (_, index) => {
+    const date = new Date(startMonth);
+    date.setMonth(date.getMonth() + index);
+    return formatMonthValue(date);
+  });
+};
+
+export const getCoverageEndMonthValue = (
+  selectedMonth: string,
+  prepaidMonthCount = 1
+): string => {
+  const coverageMonths = getCoverageMonths(selectedMonth, prepaidMonthCount);
+  return coverageMonths[coverageMonths.length - 1] ?? selectedMonth;
+};
+
+export const getCoverageValidUntilMonthValue = (
+  selectedMonth: string,
+  prepaidMonthCount = 1
+): string => addMonthsToMonthValue(selectedMonth, prepaidMonthCount);
+
+export const formatCoverageRangeLabel = ({
+  locale,
+  prepaidMonthCount,
+  selectedMonth,
+}: {
+  locale: string;
+  prepaidMonthCount?: number | null;
+  selectedMonth: string;
+}): string => {
+  const coverageMonths = getCoverageMonths(
+    selectedMonth,
+    prepaidMonthCount ?? 1
+  );
+  const firstMonth = coverageMonths[0];
+  const lastMonth = coverageMonths[coverageMonths.length - 1];
+
+  if (!firstMonth || !lastMonth || firstMonth === lastMonth) {
+    return formatMonthLabel(selectedMonth, locale);
+  }
+
+  return `${formatMonthLabel(firstMonth, locale)} - ${formatMonthLabel(
+    lastMonth,
+    locale
+  )}`;
+};
+
 const getComparableTimestamp = (value: string | null | undefined): number => {
   if (!value) return 0;
   const timestamp = new Date(value).getTime();
@@ -183,6 +258,38 @@ export const isSubscriptionMonthPaidForGroup = (
     getSubscriptionCoverageInvoiceForGroup(latestInvoices, groupId)
   );
 
+export const isSubscriptionRangePaidForGroup = (
+  groupId: string,
+  selectedMonth: string,
+  prepaidMonthCount: number,
+  latestInvoices: SubscriptionCoverageInvoice[]
+): boolean => {
+  const coverageMonths = getCoverageMonths(selectedMonth, prepaidMonthCount);
+  if (coverageMonths.length === 0) return false;
+
+  return coverageMonths.every((month) =>
+    isSubscriptionMonthPaidForGroup(groupId, month, latestInvoices)
+  );
+};
+
+export const isSubscriptionRangeFullyPaidForGroups = (
+  groupIds: string[],
+  selectedMonth: string,
+  prepaidMonthCount: number,
+  latestInvoices: SubscriptionCoverageInvoice[]
+): boolean => {
+  if (groupIds.length === 0) return false;
+
+  return groupIds.every((groupId) =>
+    isSubscriptionRangePaidForGroup(
+      groupId,
+      selectedMonth,
+      prepaidMonthCount,
+      latestInvoices
+    )
+  );
+};
+
 export const getAttendanceStats = (
   attendance: AttendanceRecord[]
 ): AttendanceStats => {
@@ -283,6 +390,17 @@ export const getBillableSessionsForGroups = (
   });
 };
 
+export const getBillableSessionsForGroupsInRange = (
+  userGroups: UserGroup[],
+  groupIds: string[],
+  selectedMonth: string,
+  prepaidMonthCount = 1,
+  latestInvoices: SubscriptionCoverageInvoice[] = []
+): BillableSession[] =>
+  getCoverageMonths(selectedMonth, prepaidMonthCount).flatMap((month) =>
+    getBillableSessionsForGroups(userGroups, groupIds, month, latestInvoices)
+  );
+
 export const getBillableAttendanceRecords = (
   attendance: AttendanceRecord[],
   groupIds: string[],
@@ -305,6 +423,17 @@ export const getBillableAttendanceRecords = (
   });
 };
 
+export const getBillableAttendanceRecordsInRange = (
+  attendance: AttendanceRecord[],
+  groupIds: string[],
+  selectedMonth: string,
+  prepaidMonthCount = 1,
+  latestInvoices: SubscriptionCoverageInvoice[] = []
+): AttendanceRecord[] =>
+  getCoverageMonths(selectedMonth, prepaidMonthCount).flatMap((month) =>
+    getBillableAttendanceRecords(attendance, groupIds, month, latestInvoices)
+  );
+
 export const getSessionsForMonth = (
   sessionsArray: string[] | null,
   month: string
@@ -453,26 +582,35 @@ export const getAvailableMonths = (
   groupIds: string[],
   latestInvoices: SubscriptionCoverageInvoice[],
   locale: string,
-  selectedMonthFallback: string | null = null
+  selectedMonthFallback: string | null = null,
+  futureMonthHorizon = 0
 ): AvailableMonthOption[] => {
   if (groupIds.length === 0) return [];
   const { earliestStart, latestEnd } = getGroupsDateRange(userGroups, groupIds);
   if (!earliestStart) return [];
 
+  const currentMonthStart = (() => {
+    const date = new Date();
+    date.setDate(1);
+    return date;
+  })();
+  const futureHorizonEnd = new Date(currentMonthStart);
+  futureHorizonEnd.setMonth(
+    futureHorizonEnd.getMonth() + Math.max(0, futureMonthHorizon)
+  );
+
   const resolvedLatestEnd = latestEnd
     ? latestEnd
     : selectedMonthFallback
       ? getMonthStartDate(selectedMonthFallback)
-      : (() => {
-          const d = new Date();
-          d.setDate(1);
-          return d;
-        })();
+      : currentMonthStart;
+  const resolvedRangeEnd =
+    futureMonthHorizon > 0 && !latestEnd ? futureHorizonEnd : resolvedLatestEnd;
 
   const months: AvailableMonthOption[] = [];
   const currentDate = new Date(earliestStart);
   currentDate.setDate(1);
-  const normalizedLatestEnd = new Date(resolvedLatestEnd);
+  const normalizedLatestEnd = new Date(resolvedRangeEnd);
   normalizedLatestEnd.setDate(1);
 
   while (currentDate <= normalizedLatestEnd) {
@@ -504,6 +642,101 @@ export const getTotalSessionsForGroups = (
   ).length;
 };
 
+export const getBillableQuantityForGroupRange = ({
+  groupId,
+  latestInvoices,
+  now = new Date(),
+  prepaidMonthCount = 1,
+  selectedMonth,
+  useAttendanceBased,
+  userAttendance,
+  userGroups,
+}: {
+  groupId: string;
+  latestInvoices?: SubscriptionCoverageInvoice[];
+  now?: Date;
+  prepaidMonthCount?: number;
+  selectedMonth: string;
+  useAttendanceBased: boolean;
+  userAttendance: AttendanceRecord[];
+  userGroups: UserGroup[];
+}): number => {
+  const currentMonthStart = getMonthStartDate(now);
+  const coverageMonths = getCoverageMonths(selectedMonth, prepaidMonthCount);
+
+  return coverageMonths.reduce((total, month) => {
+    if (isSubscriptionMonthPaidForGroup(groupId, month, latestInvoices ?? [])) {
+      return total;
+    }
+
+    const monthStart = getMonthStartDate(month);
+    const useScheduledSessions =
+      !useAttendanceBased ||
+      (!Number.isNaN(monthStart.getTime()) &&
+        !Number.isNaN(currentMonthStart.getTime()) &&
+        monthStart > currentMonthStart);
+
+    if (useScheduledSessions) {
+      return (
+        total +
+        getBillableSessionsForGroups(
+          userGroups,
+          [groupId],
+          month,
+          latestInvoices
+        ).length
+      );
+    }
+
+    return (
+      total +
+      getEffectiveAttendanceDays(
+        getBillableAttendanceRecords(
+          userAttendance,
+          [groupId],
+          month,
+          latestInvoices
+        )
+      )
+    );
+  }, 0);
+};
+
+export const getBillableQuantityMapForGroupsRange = ({
+  groupIds,
+  latestInvoices,
+  now,
+  prepaidMonthCount = 1,
+  selectedMonth,
+  useAttendanceBased,
+  userAttendance,
+  userGroups,
+}: {
+  groupIds: string[];
+  latestInvoices?: SubscriptionCoverageInvoice[];
+  now?: Date;
+  prepaidMonthCount?: number;
+  selectedMonth: string;
+  useAttendanceBased: boolean;
+  userAttendance: AttendanceRecord[];
+  userGroups: UserGroup[];
+}): Record<string, number> =>
+  Object.fromEntries(
+    groupIds.map((groupId) => [
+      groupId,
+      getBillableQuantityForGroupRange({
+        groupId,
+        latestInvoices,
+        now,
+        prepaidMonthCount,
+        selectedMonth,
+        useAttendanceBased,
+        userAttendance,
+        userGroups,
+      }),
+    ])
+  );
+
 /** Days before valid_until to consider "expiring soon" */
 const EXPIRING_SOON_DAYS = 14;
 

package/src/components/ui/tu-do/shared/__tests__/board-client.test.tsx

@@ -181,6 +181,9 @@ describe('BoardClient', () => {
       '-m-4'
     );
     expect(screen.getByTestId('kanban-skeleton')).toBeInTheDocument();
+    expect(
+      screen.queryByTestId('task-board-header-skeleton')
+    ).not.toBeInTheDocument();
     expect(screen.queryByText('Loading board...')).not.toBeInTheDocument();
   });
 
@@ -210,6 +213,10 @@ describe('BoardClient', () => {
       'h-[calc(100dvh+2rem)]',
       'w-[calc(100%+2rem)]'
     );
+    expect(
+      screen.getByTestId('task-board-header-skeleton')
+    ).toBeInTheDocument();
+    expect(screen.getByTestId('kanban-skeleton')).toBeInTheDocument();
   });
 
   it('can revalidate loaded board lists without invalidating visible task caches', async () => {

package/src/components/ui/tu-do/shared/__tests__/task-board-loading-state.test.tsx

@@ -20,6 +20,9 @@ describe('TaskBoardLoadingState', () => {
       'pr-0'
     );
     expect(screen.getByTestId('kanban-skeleton-frame')).not.toHaveClass('p-2');
+    expect(
+      screen.queryByTestId('task-board-header-skeleton')
+    ).not.toBeInTheDocument();
   });
 
   it('keeps embedded loading skeletons constrained to the parent width', () => {
@@ -34,5 +37,39 @@ describe('TaskBoardLoadingState', () => {
       'w-[calc(100%+2rem)]'
     );
     expect(screen.getByTestId('kanban-skeleton-frame')).toHaveClass('p-2');
+    expect(
+      screen.queryByTestId('task-board-header-skeleton')
+    ).not.toBeInTheDocument();
+  });
+
+  it('can include the board header skeleton above the kanban skeleton', () => {
+    render(<TaskBoardLoadingState root showHeader />);
+
+    expect(screen.getByTestId('task-board-loading-state')).toHaveClass(
+      '-m-4',
+      'h-[calc(100dvh+2rem)]',
+      'w-[calc(100%+2rem)]',
+      'flex',
+      'flex-col'
+    );
+    expect(screen.getByTestId('task-board-header-skeleton')).toHaveAttribute(
+      'aria-hidden',
+      'true'
+    );
+    expect(screen.getByTestId('task-board-header-skeleton')).toHaveClass(
+      'border-b',
+      'px-2',
+      'pt-2',
+      'pb-2'
+    );
+    expect(screen.getByTestId('task-board-header-skeleton')).not.toHaveClass(
+      '-mt-2'
+    );
+    expect(screen.getByTestId('task-board-loading-body')).toHaveClass(
+      'min-h-0',
+      'flex-1',
+      'overflow-hidden'
+    );
+    expect(screen.getByTestId('kanban-skeleton')).toBeInTheDocument();
   });
 });

package/src/components/ui/tu-do/shared/board-client.tsx

@@ -247,7 +247,9 @@ export function BoardClient({
   ]);
 
   if (boardLoading && !board) {
-    return <TaskBoardLoadingState root={rootLoading} />;
+    return (
+      <TaskBoardLoadingState root={rootLoading} showHeader={rootLoading} />
+    );
   }
 
   if (!board?.id) {

package/src/components/ui/tu-do/shared/task-board-loading-state.tsx

@@ -1,14 +1,55 @@
 'use client';
 
+import { Skeleton } from '@tuturuuu/ui/skeleton';
 import { cn } from '@tuturuuu/utils/format';
 import { KanbanSkeleton } from '../boards/boardId/kanban/rendering/kanban-skeleton';
 
+const HEADER_ACTIONS = [
+  'focus',
+  'select',
+  'view',
+  'status',
+  'sort',
+  'settings',
+];
+
+function TaskBoardHeaderSkeleton() {
+  return (
+    <div
+      aria-hidden="true"
+      className="border-b px-2 pt-2 pb-2"
+      data-testid="task-board-header-skeleton"
+    >
+      <div className="flex flex-wrap items-center justify-between gap-1.5 sm:gap-2">
+        <div className="flex min-w-0 items-center gap-2">
+          <Skeleton className="h-7 w-44 rounded-md sm:h-8 sm:w-56" />
+        </div>
+
+        <div className="min-w-0 flex-1 basis-72">
+          <Skeleton className="h-6 w-full rounded-md sm:h-8" />
+        </div>
+
+        <div className="flex shrink-0 items-center gap-1.5 sm:gap-2">
+          {HEADER_ACTIONS.map((action) => (
+            <Skeleton
+              className="h-7 w-7 rounded-md sm:h-8 sm:w-8"
+              key={action}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
 export function TaskBoardLoadingState({
   className,
   root = false,
+  showHeader = false,
 }: {
   className?: string;
   root?: boolean;
+  showHeader?: boolean;
 }) {
   return (
     <div
@@ -18,11 +59,24 @@ export function TaskBoardLoadingState({
         root
           ? '-m-4 h-[calc(100dvh+2rem)] min-h-[calc(32rem+2rem)] w-[calc(100%+2rem)] min-w-[calc(100%+2rem)]'
           : 'h-[calc(100dvh-1rem)] min-h-[32rem] w-full',
+        showHeader && 'flex flex-col',
         className
       )}
       data-testid="task-board-loading-state"
     >
-      <KanbanSkeleton root={root} />
+      {showHeader ? (
+        <>
+          <TaskBoardHeaderSkeleton />
+          <div
+            className="min-h-0 flex-1 overflow-hidden"
+            data-testid="task-board-loading-body"
+          >
+            <KanbanSkeleton root={root} />
+          </div>
+        </>
+      ) : (
+        <KanbanSkeleton root={root} />
+      )}
     </div>
   );
 }

package/src/components/ui/tu-do/shared/task-edit-dialog/components/task-description-editor.tsx

@@ -54,6 +54,7 @@ export interface TaskDescriptionEditorProps {
   onImageUpload?: (file: File) => Promise<string>;
   onEditorReady: (editor: Editor) => void;
   onConvertToTask?: () => void | Promise<void>;
+  onDescriptionSnapshotChange?: (description: JSONContent | null) => void;
   onDescriptionStorageLengthChange: (storageLength: number) => void;
   descriptionStorageLength: number;
   descriptionPercentLeft: number;
@@ -109,6 +110,7 @@ export function TaskDescriptionEditor({
   onImageUpload,
   onEditorReady,
   onConvertToTask,
+  onDescriptionSnapshotChange,
   onDescriptionStorageLengthChange,
   descriptionStorageLength,
   descriptionPercentLeft,
@@ -290,6 +292,7 @@ export function TaskDescriptionEditor({
           content={description}
           onChange={setDescription}
           onImmediateChange={(nextDescription) => {
+            onDescriptionSnapshotChange?.(nextDescription);
             if (allowYjsSync) {
               setDescription(nextDescription);
             }

package/src/components/ui/tu-do/shared/task-edit-dialog/description-versions.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildRecoverableTaskDescriptionVersions,
+  extractRecoverableTaskDescriptionValue,
+} from './description-versions';
+
+const makeDoc = (text: string) =>
+  JSON.stringify({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: [{ type: 'text', text }],
+      },
+    ],
+  });
+
+describe('task description tracked versions', () => {
+  it('does not treat null, empty docs, or legacy placeholders as recoverable', () => {
+    expect(extractRecoverableTaskDescriptionValue(null)).toBeNull();
+    expect(extractRecoverableTaskDescriptionValue('')).toBeNull();
+    expect(extractRecoverableTaskDescriptionValue('has_content')).toBeNull();
+    expect(
+      extractRecoverableTaskDescriptionValue(
+        JSON.stringify({
+          type: 'doc',
+          content: [{ type: 'paragraph' }],
+        })
+      )
+    ).toBeNull();
+  });
+
+  it('normalizes plain text and serialized TipTap content', () => {
+    const plain = extractRecoverableTaskDescriptionValue('Plain description');
+    const serialized = extractRecoverableTaskDescriptionValue(
+      makeDoc('Serialized description')
+    );
+
+    expect(plain?.description).toContain('Plain description');
+    expect(plain?.previewText).toBe('Plain description');
+    expect(serialized?.description).toContain('Serialized description');
+    expect(serialized?.previewText).toBe('Serialized description');
+  });
+
+  it('prefers the previous value from the latest wipe entry', () => {
+    const versions = buildRecoverableTaskDescriptionVersions([
+      {
+        id: 'older',
+        changed_at: '2026-06-25T10:00:00.000Z',
+        change_type: 'field_updated',
+        field_name: 'description',
+        old_value: makeDoc('Older version'),
+        new_value: makeDoc('Intermediate version'),
+      },
+      {
+        id: 'wipe',
+        changed_at: '2026-06-26T10:00:00.000Z',
+        change_type: 'field_updated',
+        field_name: 'description',
+        old_value: makeDoc('Latest real version'),
+        new_value: null,
+      },
+    ]);
+
+    expect(versions[0]?.historyId).toBe('wipe');
+    expect(versions[0]?.source).toBe('old_value');
+    expect(versions[0]?.reason).toBe('before_clear');
+    expect(versions[0]?.previewText).toBe('Latest real version');
+  });
+
+  it('dedupes identical canonical descriptions while keeping newest first', () => {
+    const duplicated = makeDoc('Same description');
+    const versions = buildRecoverableTaskDescriptionVersions([
+      {
+        id: 'newer',
+        changed_at: '2026-06-26T10:00:00.000Z',
+        change_type: 'field_updated',
+        field_name: 'description',
+        old_value: makeDoc('Different description'),
+        new_value: duplicated,
+      },
+      {
+        id: 'older',
+        changed_at: '2026-06-25T10:00:00.000Z',
+        change_type: 'field_updated',
+        field_name: 'description',
+        old_value: duplicated,
+        new_value: duplicated,
+      },
+    ]);
+
+    expect(versions.map((version) => version.previewText)).toEqual([
+      'Same description',
+      'Different description',
+    ]);
+  });
+});