@devalok/shilp-sutra-karm 0.18.0 → 0.18.1

package/docs/components/admin/admin-dashboard.md

@@ -0,0 +1,215 @@
+# AdminDashboard
+
+- Import: @devalok/shilp-sutra-karm/admin
+- Server-safe: No
+- Category: admin
+
+Compound component for the admin attendance dashboard. Uses React Context internally.
+All sub-components must be rendered inside `<AdminDashboard.Root>`.
+
+Exports: AdminDashboard (compound), AdminDashboardSkeleton, Calendar, BreakRequestCard, LeaveRequests, DashboardHeader, AttendanceOverview, AssociateDetail, CorrectionList, RenderDate
+
+## Props
+
+### AdminDashboard.Root (AdminDashboardRootProps)
+    currentUserId: string (REQUIRED)
+    currentUserRole: UserRole (REQUIRED)
+    currentUser: AdminUser
+    assetsBaseUrl: string (default: "")
+    userImages: Record<string, string> (default: {})
+    isLoading: boolean (default: false)
+    onAssociateChange: (user: AdminUser | null) => void
+    children: ReactNode (REQUIRED)
+    ...HTMLDivElement attributes (className, etc.)
+
+### AdminDashboard.Calendar (AdminDashboardCalendarProps)
+    dateAttendanceMap: Map<string, DateAttendanceInfo> | null (default: null)
+    onDateChange: (date: string) => void
+    onTimeFrameChange: (timeFrame: string) => void
+    users: AdminUser[] (default: [])
+    selectedUserAttendance: AttendanceRecord | null (default: null)
+    ...HTMLDivElement attributes
+
+### AdminDashboard.AttendanceOverview (AdminDashboardAttendanceOverviewProps)
+    groupedAttendance: GroupedAttendance | null (default: null)
+    users: AdminUser[] (default: [])
+    ...HTMLDivElement attributes
+
+### AdminDashboard.AssociateDetail (AdminDashboardAssociateDetailProps)
+    attendance: AttendanceRecord | null (default: null)
+    tasks: TaskItem[] (default: [])
+    breakRequest: BreakRequest | null (default: null)
+    onUpdateAttendanceStatus: (params: { userId: string; date: string; isPresent: boolean }) => void | Promise<void>
+    onToggleTaskStatus: (taskId: string, newStatus: string) => void | Promise<void>
+    onAddTask: (title: string, assigneeId: string) => void | Promise<void>
+    onReorderTasks: (draggedTaskId: string, targetTaskId: string) => void | Promise<void>
+    onCancelBreak: (params: { requestId: string; deleteSingleDay: boolean; dateToCancel: string | Date; userId: string }) => void | Promise<void>
+    onRefreshSelectedUserAttendance: () => void | Promise<void>
+    onRefreshAttendanceData: () => void | Promise<void>
+    ...HTMLDivElement attributes
+
+### AdminDashboard.LeaveRequests (AdminDashboardLeaveRequestsProps)
+    requests: BreakRequest[] (default: [])
+    corrections: AttendanceCorrection[] (default: [])
+    onApproveBreak: (params: { requestId: string; adminComment: string; userId: string }) => void | Promise<void>
+    onRejectBreak: (params: { requestId: string; adminComment: string; userId: string }) => void | Promise<void>
+    onApproveCorrection: (correctionId: string) => void | Promise<void>
+    onRejectCorrection: (correctionId: string) => void | Promise<void>
+    ...HTMLDivElement attributes
+
+### AdminDashboard.Content (AdminDashboardContentProps)
+    children: ReactNode (REQUIRED)
+    ...HTMLDivElement attributes
+
+### Calendar (CalendarProps) — standalone
+    onDateSelect: (date: Date) => void (REQUIRED)
+    hasCorrection: (date: Date) => boolean
+    ...HTMLDivElement attributes
+
+### BreakRequestCard (BreakRequestProps) — standalone
+    selectedDate: string | Date (REQUIRED)
+    userId: string (REQUIRED)
+    breakRequest: BreakRequest | null
+    assetsBaseUrl: string
+    onCancelBreak: (params: { requestId: string; deleteSingleDay: boolean; dateToCancel: string | Date; userId: string }) => void | Promise<void>
+    onRefreshAttendance: () => void | Promise<void>
+    onRefreshGroupedAttendance: () => void | Promise<void>
+    ...HTMLDivElement attributes
+
+### LeaveRequests (LeaveRequestsProps) — standalone
+    requests: BreakRequest[] (REQUIRED)
+    currentUserId: string (REQUIRED)
+    userImages: Record<string, string>
+    activeTimeFrame: string
+    onApproveBreak: (params: { requestId: string; adminComment: string; userId: string }) => void | Promise<void>
+    onRejectBreak: (params: { requestId: string; adminComment: string; userId: string }) => void | Promise<void>
+    ...HTMLDivElement attributes
+
+### DashboardHeader (DashboardHeaderProps) — standalone
+    selectedMonth: string (REQUIRED)
+    yearsList: string[] (REQUIRED)
+    isTodaySelected: boolean (REQUIRED)
+    selectedAssociate: AdminUser | null (REQUIRED)
+    users: AdminUser[] (REQUIRED)
+    userImages: Record<string, string> (REQUIRED)
+    activeTimeFrame: string (REQUIRED)
+    onMonthSelection: (monthYear: string) => void (REQUIRED)
+    onTodayClick: () => void (REQUIRED)
+    onSelectAssociate: (user: AdminUser | null) => void (REQUIRED)
+    onTimeFrameChange: (id: string) => void (REQUIRED)
+    onDateChange: (direction: "prev" | "next") => void (REQUIRED)
+    ...HTMLDivElement attributes
+
+### AttendanceOverview (AttendanceOverviewProps) — standalone
+    isFutureDate: boolean (REQUIRED)
+    users: AdminUser[] (REQUIRED)
+    groupedAttendance: GroupedAttendance | null (REQUIRED)
+    userImages: Record<string, string> (REQUIRED)
+    selectedDate: string (REQUIRED)
+    ...HTMLDivElement attributes
+
+### AssociateDetail (AssociateDetailProps) — standalone
+    selectedAssociate: AdminUser (REQUIRED)
+    selectedDate: string (REQUIRED)
+    selectedUserAttendance: AttendanceRecord | null (REQUIRED)
+    userTasks: TaskItem[] (REQUIRED)
+    selectedBreakRequest: BreakRequest | null (REQUIRED)
+    isFutureDate: boolean (REQUIRED)
+    assetsBaseUrl: string (REQUIRED)
+    onUpdateAttendanceStatus: (params: { userId: string; date: string; isPresent: boolean }) => void | Promise<void>
+    onToggleTaskStatus: (taskId: string, newStatus: string) => void | Promise<void>
+    onAddTask: (title: string, assigneeId: string) => void | Promise<void>
+    onReorderTasks: (draggedTaskId: string, targetTaskId: string) => void | Promise<void>
+    onCancelBreak: (params: { requestId: string; deleteSingleDay: boolean; dateToCancel: string | Date; userId: string }) => void | Promise<void>
+    onRefreshSelectedUserAttendance: () => void | Promise<void>
+    onRefreshAttendanceData: () => void | Promise<void>
+    ...HTMLDivElement attributes
+
+### CorrectionList (CorrectionListProps) — standalone
+    corrections: AttendanceCorrection[] (REQUIRED)
+    currentUserId: string (REQUIRED)
+    userImages: Record<string, string> (REQUIRED)
+    assetsBaseUrl: string (REQUIRED)
+    activeTimeFrame: string (REQUIRED)
+    onApproveCorrection: (correctionId: string) => void | Promise<void>
+    onRejectCorrection: (correctionId: string) => void | Promise<void>
+    ...HTMLDivElement attributes
+
+### RenderDate (RenderDateProps) — standalone
+    day: DayInfo (REQUIRED)
+    isAdmin: boolean (REQUIRED)
+    selectedDate: string | Date (REQUIRED)
+    dateAttendanceMap: Map<string, DateAttendanceInfo> | null (REQUIRED)
+    activeTimeFrame: string (REQUIRED)
+    ...HTMLDivElement attributes
+
+### AdminDashboardSkeleton (DashboardSkeleton)
+    ...HTMLDivElement attributes (className, etc.)
+
+## Supporting Types
+    TaskItem: { id: string; title: string; status: string; assigneeIds?: string; priority?: string }
+    AttendanceCorrection: { id: string; date: string; reason?: string; requestedDate?: string; correctionStatus: CorrectionStatus; user?: AdminUser }
+    DateAttendanceInfo: { status: AttendanceStatus | null; hasCorrectionOrApproval?: boolean; isBreakApproved?: boolean }
+
+## Defaults
+    assetsBaseUrl="", userImages={}, isLoading=false
+
+## Example
+```jsx
+<AdminDashboard.Root
+  currentUserId="user-1"
+  currentUserRole="Admin"
+  currentUser={currentUser}
+  assetsBaseUrl="/assets"
+  userImages={userImageMap}
+  isLoading={isLoading}
+  onAssociateChange={(user) => setSelected(user)}
+>
+  <AdminDashboard.Calendar
+    dateAttendanceMap={dateMap}
+    onDateChange={handleDateChange}
+    onTimeFrameChange={handleTimeFrameChange}
+    users={allUsers}
+    selectedUserAttendance={attendance}
+  />
+  <AdminDashboard.Content>
+    <AdminDashboard.AttendanceOverview
+      groupedAttendance={grouped}
+      users={allUsers}
+    />
+    <AdminDashboard.AssociateDetail
+      attendance={selectedAttendance}
+      tasks={tasks}
+      breakRequest={breakReq}
+      onUpdateAttendanceStatus={handleUpdateStatus}
+      onToggleTaskStatus={handleToggleTask}
+      onAddTask={handleAddTask}
+    />
+    <AdminDashboard.LeaveRequests
+      requests={pendingRequests}
+      corrections={corrections}
+      onApproveBreak={handleApproveBreak}
+      onRejectBreak={handleRejectBreak}
+      onApproveCorrection={handleApproveCorrection}
+      onRejectCorrection={handleRejectCorrection}
+    />
+  </AdminDashboard.Content>
+</AdminDashboard.Root>
+```
+
+## Gotchas
+- All sub-components must be inside `<AdminDashboard.Root>` or they throw a context error
+- `AdminDashboard.AttendanceOverview` only renders when NO associate is selected
+- `AdminDashboard.AssociateDetail` only renders when an associate IS selected
+- `AdminDashboard.LeaveRequests` auto-hides when there are zero requests AND zero pending corrections
+- `AdminDashboard.LeaveRequests` auto-switches tabs when new requests arrive
+- The `Calendar` standalone export is a simpler calendar without the compound context — use it for non-admin pages
+- `BreakRequestCard` standalone export displays a single break with cancel dialog — used inside AssociateDetail internally
+- Date callbacks fire ISO-formatted strings via `format(date, "yyyy-MM-dd'T'HH:mm:ssxxx")`
+- `isLoading=true` on Root renders `DashboardSkeleton` instead of children
+
+## Changes
+### v0.9.0
+- **Added** Compound component API replacing 29-prop monolith (BREAKING)
+- **Added** AdminDashboard.Content wrapper for rounded-corner management
+- **Added** Standalone exports for Calendar, BreakRequestCard, LeaveRequests, DashboardHeader, AttendanceOverview, AssociateDetail, CorrectionList, RenderDate

package/docs/components/admin/admin-types.md

@@ -0,0 +1,167 @@
+# Admin Types
+
+- Import: @devalok/shilp-sutra-karm/admin
+- Server-safe: Yes
+- Category: admin
+
+Type-only exports for the admin module. No runtime code.
+
+## Types
+
+### UserRole
+```ts
+type UserRole = 'Apprentice' | 'Associate' | 'Admin' | 'SuperAdmin'
+```
+
+### AttendanceStatus
+```ts
+type AttendanceStatus = 'PRESENT' | 'ABSENT' | 'BREAK' | 'Not_Marked' | 'HOLIDAY' | 'WEEKEND'
+```
+
+### CorrectionStatus
+```ts
+type CorrectionStatus = 'PENDING' | 'APPROVED' | 'REJECTED'
+```
+
+### BreakRequestStatus
+```ts
+type BreakRequestStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED'
+```
+
+### AdminUser
+```ts
+interface AdminUser {
+  id: string
+  name: string
+  firstName?: string
+  lastName?: string
+  email: string
+  devalokEmail?: string
+  designation: string | null
+  image: string | null
+  role: UserRole
+  isActive: boolean
+  createdAt: string | Date
+}
+```
+
+### AttendanceRecord
+```ts
+interface AttendanceRecord {
+  id: string
+  userId: string
+  date: string
+  timeIn: string | null
+  timeOut: string | null
+  status: AttendanceStatus
+  correctionStatus?: CorrectionStatus | null
+  reason?: string | null
+  adminComment?: string | null
+  requestedDate?: string | null
+  newTimeIn?: string | null
+  newTimeOut?: string | null
+  oldTimeIn?: string | null
+  oldTimeOut?: string | null
+  user?: AdminUser
+}
+```
+
+### BreakRequest
+```ts
+interface BreakRequest {
+  id: string
+  userId: string
+  startDate: string
+  endDate: string
+  numberOfDays: number
+  reason: string
+  status: BreakRequestStatus
+  adminComment?: string | null
+  correction?: boolean
+  user?: Pick<AdminUser, 'id' | 'name' | 'firstName' | 'image'>
+}
+```
+
+### BreakBalanceData
+```ts
+interface BreakBalanceData {
+  id: string
+  userId: string
+  totalDays: number
+  usedDays?: number
+  carryForward: number
+  cashout: number
+  yearlyBalance?: number
+  other?: number
+  user?: Pick<AdminUser, 'id' | 'name' | 'firstName' | 'image'>
+  createdAt: string
+  updatedAt: string
+}
+```
+
+### Adjustment
+```ts
+interface Adjustment {
+  id: string
+  userId: string
+  numberOfDays: number
+  type: string
+  reason: string
+  status: string
+  comment: string | null
+  approvedBy: string | null
+  createdAt: string
+  updatedAt: string
+  user?: Pick<AdminUser, 'name' | 'email'>
+  approver?: Pick<AdminUser, 'name' | 'email'>
+}
+```
+
+### GroupedAttendance
+```ts
+interface GroupedAttendance {
+  present: Array<{ user: AdminUser; attendance: AttendanceRecord }>
+  absent: Array<{ user: AdminUser; attendance?: AttendanceRecord }>
+  onBreak: Array<{ user: AdminUser; attendance: AttendanceRecord; breakRequest?: BreakRequest }>
+  yetToMark: Array<{ user: AdminUser }>
+}
+```
+
+### DayInfo
+```ts
+interface DayInfo {
+  day: string
+  date: number
+  fullDate: Date
+  isToday: boolean
+  isActive: boolean
+  isPadding?: boolean
+  hasBreak?: boolean
+  isAbsent?: boolean
+  isDisabled?: boolean
+}
+```
+
+### RealtimeCallbacks
+```ts
+interface RealtimeCallbacks {
+  onBreakRequestCreated?: (data: BreakRequest) => void
+  onBreakRequestApproved?: (data: BreakRequest) => void
+  onBreakRequestRejected?: (data: BreakRequest) => void
+  onBreakRequestCancelled?: (data: BreakRequest) => void
+  onAttendanceCorrectionCreated?: (data: AttendanceRecord) => void
+  onAttendanceCorrectionProcessed?: (data: AttendanceRecord) => void
+  onTaskUpdated?: (data: unknown) => void
+}
+```
+
+## Gotchas
+- `AttendanceStatus` includes `'Not_Marked'` (mixed case with underscore) — not `'NOT_MARKED'`
+- `BreakRequest.correction` is a boolean flag that indicates the request is an attendance correction, not a break
+- `AdminUser.designation` and `AdminUser.image` are nullable (`string | null`)
+- `AdminUser.createdAt` accepts both `string` and `Date`
+- `DayInfo` is used by the calendar components — `isPadding` marks days from adjacent months
+
+## Changes
+### v0.9.0
+- **Added** Initial release with all admin domain types

package/docs/components/admin/admin-utils.md

@@ -0,0 +1,165 @@
+# Admin Utilities
+
+- Import: @devalok/shilp-sutra-karm/admin
+- Server-safe: Partial (date/emoji utils are server-safe; renderAdjustmentType and renderStatus return JSX)
+- Category: admin
+
+Utility functions for date formatting, status rendering, and emoji handling.
+
+Exports: AdjustmentType, renderAdjustmentType, renderStatus, formatDate, formatDateIST, formatTimeIST, formatDateWithWeekday, formatOptionalDate, getDaySuffix, isSameDay, getWeekDays, getMonthDays, getStartOfDay, getEndOfDay, removeAllEmojis, removeEmojiAtStart, ApprovedAdjustments
+
+## Functions
+
+### renderAdjustmentType
+```ts
+function renderAdjustmentType(type: keyof typeof AdjustmentType): JSX.Element
+```
+Maps an adjustment type key to a human-readable label wrapped in a `<div>`.
+
+### AdjustmentType (constant)
+```ts
+const AdjustmentType = {
+  YEARLY_BALANCE: 'YEARLY_BALANCE',
+  CARRY_FORWARD: 'CARRY_FORWARD',
+  CASHOUT: 'CASHOUT',
+  OTHER: 'OTHER',
+} as const
+```
+
+### renderStatus
+```ts
+function renderStatus(status: string, correction?: boolean): ReactNode
+```
+Returns a `<Badge>` with color and label based on status. When `correction=true`, uses correction-specific labels (e.g. "Corrected" instead of "Approved", "Denied" instead of "Rejected").
+
+Status map (default): APPROVED=success "Approved", PENDING=warning "Pending", REJECTED=error "Denied", CANCELLED=error "Redacted", MISSING=error "Missed"
+
+Status map (correction): APPROVED=accent "Corrected", PENDING=warning "Pending", REJECTED=error "Denied", MISSING=error "Missed"
+
+### formatDate
+```ts
+function formatDate(date: Date | string): string
+```
+Formats to IST locale short date, e.g. `"14 Mar '26"`. Uses `en-IN` locale with `Asia/Kolkata` timezone.
+
+### formatDateIST
+```ts
+function formatDateIST(date: Date | string, options?: Intl.DateTimeFormatOptions): string
+```
+Formats date to IST locale string with custom options. Defaults to `Asia/Kolkata` timezone.
+
+### formatTimeIST
+```ts
+function formatTimeIST(date: Date | string, options?: Intl.DateTimeFormatOptions): string
+```
+Formats time to IST locale string with custom options. Defaults to `Asia/Kolkata` timezone.
+
+### formatDateWithWeekday
+```ts
+function formatDateWithWeekday(date: Date): string
+```
+Returns formatted date with weekday, e.g. `"14 Mar '26, Thursday"`.
+
+### formatOptionalDate
+```ts
+function formatOptionalDate(date: Date | string | '-'): string
+```
+Like `formatDate` but returns `"-"` if input is `"-"`.
+
+### getDaySuffix
+```ts
+function getDaySuffix(day: number): string
+```
+Returns day with ordinal suffix: `1` -> `"1st"`, `2` -> `"2nd"`, `11` -> `"11th"`, etc.
+
+### isSameDay
+```ts
+function isSameDay(date1: Date, date2: Date): boolean
+```
+Checks if two dates are the same calendar day. Returns `false` if either argument is not a valid Date.
+
+### getWeekDays
+```ts
+function getWeekDays(currentDate: string | Date, selectedDate: string | Date): WeekDay[]
+```
+Returns 7-day array (Sun-Sat) for the week containing `currentDate`. Each entry has `{ day, date, fullDate, isToday, isActive }`.
+
+### getMonthDays
+```ts
+function getMonthDays(currentDate: Date | string, selectedDate: Date | string): MonthDay[]
+```
+Returns full month grid including padding days from adjacent months. Each entry has `{ day, date, fullDate, isToday, isActive, isPadding }`.
+
+### getStartOfDay
+```ts
+function getStartOfDay(date?: Date): Date
+```
+Returns start of day (00:00:00.000). Defaults to current date.
+
+### getEndOfDay
+```ts
+function getEndOfDay(date?: Date): Date
+```
+Returns end of day (23:59:59.999). Defaults to current date.
+
+### removeAllEmojis
+```ts
+function removeAllEmojis(text?: string): string
+```
+Strips all emoji characters from a string. Returns `""` if input is undefined.
+
+### removeEmojiAtStart
+```ts
+function removeEmojiAtStart(text: string): string
+```
+Strips emoji characters only from the beginning of a string.
+
+### ApprovedAdjustments (ApprovedAdjustmentsProps) — component
+    adjustments: Adjustment[] (REQUIRED)
+    adminId: string (REQUIRED)
+    ...HTMLDivElement attributes
+
+Renders a table of approved adjustments showing user, date, days, type, reason, and approver. Displays "You" for self-approved items.
+
+## Example
+```jsx
+import {
+  renderStatus,
+  renderAdjustmentType,
+  formatDate,
+  formatDateIST,
+  removeAllEmojis,
+  ApprovedAdjustments,
+} from '@devalok/shilp-sutra-karm/admin'
+
+// Render a status badge
+{renderStatus('APPROVED')}           // -> <Badge color="success">Approved</Badge>
+{renderStatus('PENDING', true)}      // -> <Badge color="warning">Pending</Badge>
+
+// Render adjustment type
+{renderAdjustmentType('CASHOUT')}    // -> <div>Cashout</div>
+
+// Format dates
+formatDate(new Date())               // "14 Mar '26"
+formatDateIST(new Date(), { weekday: 'long' }) // "Thursday"
+formatDateWithWeekday(new Date())    // "14 Mar '26, Thursday"
+getDaySuffix(3)                      // "3rd"
+
+// Clean emoji text
+removeAllEmojis("Hello World")    // "Hello World"
+removeEmojiAtStart("Hello")       // "Hello"
+
+// Approved adjustments table
+<ApprovedAdjustments adjustments={approvedList} adminId="admin-1" />
+```
+
+## Gotchas
+- All date functions use `Asia/Kolkata` timezone and `en-IN` locale by default
+- `renderAdjustmentType` and `renderStatus` return JSX — call them as functions, not as components
+- `renderStatus` falls back to the REJECTED config for unknown status values
+- `getWeekDays` starts weeks on Sunday (weekStartsOn: 0)
+- `getMonthDays` includes padding days from previous/next months with `isPadding: true`
+
+## Changes
+### v0.9.0
+- **Added** Initial release with all admin utility functions