@nuxt-customer-portal/timesheets 0.3.0

package/shared/feature.ts

@@ -0,0 +1,184 @@
+import { timesheetEmails } from './emails'
+import type { PortalFeatureDefinition } from '@nuxt-customer-portal/core/shared/types/feature'
+
+export const timesheetActions = ['read', 'create', 'update', 'submit', 'report', 'approve', 'manage'] as const
+
+export type TimesheetAction = (typeof timesheetActions)[number]
+
+export const timesheetsFeature: PortalFeatureDefinition<TimesheetAction> = {
+  id: 'timesheets',
+  emails: timesheetEmails,
+  navigation: [
+    {
+      id: 'timesheets',
+      labelKey: 'features.timesheets.navigation.myTimesheet',
+      icon: 'i-lucide-clock-3',
+      to: '/timesheets',
+      audiences: ['authenticated'],
+      order: 30
+    },
+    {
+      id: 'timesheets-approvals',
+      labelKey: 'features.timesheets.internalApprovals.title',
+      icon: 'i-lucide-stamp',
+      to: '/timesheets/internal-approvals',
+      audiences: ['authenticated'],
+      order: 31
+    },
+    {
+      id: 'timesheets-suppliers',
+      labelKey: 'features.timesheets.suppliers.title',
+      icon: 'i-lucide-building-2',
+      to: '/timesheets/suppliers',
+      audiences: ['authenticated'],
+      order: 32
+    },
+    {
+      id: 'timesheets-admin',
+      labelKey: 'features.timesheets.navigation.manage',
+      icon: 'i-lucide-chart-no-axes-combined',
+      to: '/admin/timesheets/internal-approvals',
+      audiences: ['providerAdmin'],
+      location: 'admin',
+      order: 130
+    }
+  ],
+  modules: [
+    {
+      id: 'timesheets',
+      labelKey: 'features.timesheets.navigation.myTimesheet',
+      icon: 'i-lucide-clock-3',
+      to: '/timesheets',
+      routePrefixes: ['/timesheets', '/admin/timesheets'],
+      audiences: ['authenticated'],
+      order: 30,
+      menuItems: [
+        {
+          id: 'my-timesheet',
+          labelKey: 'features.timesheets.navigation.myTimesheet',
+          icon: 'i-lucide-clock-3',
+          to: '/timesheets',
+          audiences: ['authenticated']
+        },
+        {
+          id: 'client-approvals',
+          labelKey: 'features.timesheets.approvals.title',
+          icon: 'i-lucide-stamp',
+          to: '/timesheets/approvals',
+          exact: true,
+          audiences: ['authenticated']
+        },
+        {
+          id: 'approval-reviewers',
+          labelKey: 'features.timesheets.approvals.reviewersTitle',
+          icon: 'i-lucide-users-round',
+          to: '/timesheets/approvals/reviewers',
+          audiences: ['clientAdmin']
+        },
+        {
+          id: 'supplier-timesheets',
+          labelKey: 'features.timesheets.suppliers.title',
+          icon: 'i-lucide-building-2',
+          to: '/timesheets/suppliers',
+          audiences: ['authenticated']
+        },
+        {
+          id: 'timesheet-approvals',
+          labelKey: 'features.timesheets.internalApprovals.title',
+          icon: 'i-lucide-stamp',
+          to: '/timesheets/internal-approvals',
+          audiences: ['authenticated']
+        },
+        {
+          id: 'provider-client-approvals',
+          labelKey: 'features.timesheets.admin.clientApprovals',
+          icon: 'i-lucide-building-2',
+          to: '/timesheets/client-approvals',
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'internal-approval-settings',
+          labelKey: 'features.timesheets.internalApprovals.manageTitle',
+          icon: 'i-lucide-user-round-check',
+          to: '/admin/timesheets/internal-approvals',
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'timesheet-projects',
+          labelKey: 'features.timesheets.admin.projects',
+          icon: 'i-lucide-folder-kanban',
+          to: '/admin/timesheets/projects',
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'timesheet-activities',
+          labelKey: 'features.timesheets.admin.activities',
+          icon: 'i-lucide-tags',
+          to: '/admin/timesheets/activities',
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'timesheet-rates',
+          labelKey: 'features.timesheets.admin.teamRates',
+          icon: 'i-lucide-badge-euro',
+          to: '/admin/timesheets/rates',
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'timesheet-settings',
+          labelKey: 'features.timesheets.admin.workspaceSettings',
+          icon: 'i-lucide-settings-2',
+          to: '/admin/timesheets/settings',
+          audiences: ['providerAdmin']
+        },
+        {
+          id: 'timesheet-reports',
+          labelKey: 'features.timesheets.admin.reports',
+          icon: 'i-lucide-chart-no-axes-combined',
+          to: '/admin/timesheets/reports',
+          audiences: ['providerAdmin']
+        }
+      ]
+    }
+  ],
+  dashboardWidgets: [
+    {
+      id: 'timesheets-my-timesheets',
+      component: 'TimesheetsDashboardMyTimesheets',
+      area: 'main',
+      size: 'half',
+      order: 21
+    },
+    { id: 'timesheets-my-week', component: 'TimesheetsDashboardMyWeek', area: 'main', size: 'half', order: 20 },
+    {
+      id: 'timesheets-internal-approvals',
+      component: 'TimesheetsDashboardInternalApprovals',
+      area: 'attention',
+      size: 'half',
+      order: 10
+    },
+    {
+      id: 'timesheets-client-approvals',
+      component: 'TimesheetsDashboardClientApprovals',
+      area: 'attention',
+      size: 'half',
+      order: 20
+    },
+    {
+      id: 'timesheets-supplier-timesheets',
+      component: 'TimesheetsDashboardSupplierTimesheets',
+      area: 'main',
+      size: 'half',
+      order: 25
+    }
+  ],
+  clientIntegration: {
+    moduleId: 'timesheets',
+    labelKey: 'features.timesheets.navigation.myTimesheet',
+    detailComponent: 'TimesheetsClientSettingsPanel'
+  },
+  policy: {
+    PROVIDER: { owner: timesheetActions, admin: timesheetActions, member: ['read', 'create', 'update', 'submit'] },
+    CLIENT: { owner: ['read', 'approve', 'manage'], admin: ['read', 'approve', 'manage'], member: ['read'] }
+  }
+}

package/shared/period-lock.ts

@@ -0,0 +1,8 @@
+export const isTimesheetDateLocked = (
+  date: string,
+  periods: readonly { status: string; periodStartsOn: string; periodEndsOn: string }[]
+) =>
+  periods.some(
+    (period) =>
+      ['SUBMITTED', 'APPROVED'].includes(period.status) && period.periodStartsOn <= date && date <= period.periodEndsOn
+  )

package/shared/submission-reply.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod'
+
+export const submissionReplySchema = z.object({ reply: z.string().trim().max(5000).optional() })

package/shared/timer-rounding.ts

@@ -0,0 +1,2 @@
+export const roundTimerMinutes = (elapsedMs: number, increment: number) =>
+  Math.max(1, Math.ceil(elapsedMs / (increment * 60_000))) * increment

package/shared/timesheet-dates.ts

@@ -0,0 +1,23 @@
+export const mondayFor = (dateString?: string) => {
+  const date = dateString ? new Date(`${dateString}T12:00:00Z`) : new Date()
+  const day = date.getUTCDay()
+  const offset = day === 0 ? -6 : 1 - day
+  date.setUTCDate(date.getUTCDate() + offset)
+  return date.toISOString().slice(0, 10)
+}
+
+export const addIsoDays = (dateString: string, days: number) => {
+  const date = new Date(`${dateString}T12:00:00Z`)
+  date.setUTCDate(date.getUTCDate() + days)
+  return date.toISOString().slice(0, 10)
+}
+
+/** Format a calendar-date period identically in the UI and server-rendered emails. */
+export const formatTimesheetPeriod = (from: string, to: string, locale: string) =>
+  new Intl.DateTimeFormat(locale, {
+    weekday: 'short',
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+    timeZone: 'UTC'
+  }).formatRange(new Date(`${from}T12:00:00Z`), new Date(`${to}T12:00:00Z`))

package/shared/timesheet-errors.ts

@@ -0,0 +1,13 @@
+export const TIMESHEET_ERROR_CODES = {
+  tariffRequired: 'TIMESHEET_TARIFF_REQUIRED',
+  entryDisabled: 'TIMESHEET_ENTRY_DISABLED',
+  runningTimer: 'TIMESHEET_RUNNING_TIMER',
+  internalApproverRequired: 'TIMESHEET_INTERNAL_APPROVER_REQUIRED',
+  internalApprovalUnauthorized: 'TIMESHEET_INTERNAL_APPROVAL_UNAUTHORIZED',
+  internalApprovalStale: 'TIMESHEET_INTERNAL_APPROVAL_STALE',
+  internalApprovalMemberInvalid: 'TIMESHEET_INTERNAL_APPROVAL_MEMBER_INVALID',
+  internalApprovalSelfAssignment: 'TIMESHEET_INTERNAL_APPROVAL_SELF_ASSIGNMENT',
+  internalApprovalDuplicateAssignment: 'TIMESHEET_INTERNAL_APPROVAL_DUPLICATE_ASSIGNMENT'
+} as const
+
+export type TimesheetErrorCode = (typeof TIMESHEET_ERROR_CODES)[keyof typeof TIMESHEET_ERROR_CODES]

package/shared/types/timesheet.ts

@@ -0,0 +1,424 @@
+export type TimesheetStatus = 'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'REJECTED'
+export type ProjectStatus = 'ACTIVE' | 'ARCHIVED'
+export type ClientAccessMode = 'DISABLED' | 'VIEW' | 'REVIEW'
+export type ClientReviewStatus = 'PENDING' | 'APPROVED' | 'DISPUTED'
+
+export interface TimesheetsListPagination {
+  total: number
+  page: number
+  pageSize: number
+  pageCount: number
+}
+export interface TimesheetsListResponse<T> {
+  items: T[]
+  pagination: TimesheetsListPagination
+}
+
+export interface TimesheetSettingsDto {
+  timerRoundingMinutes?: number
+  currency: string
+  timezone: string
+  weekStartsOn: number
+  internalApprovalsEnabled: boolean
+}
+
+export interface TeamMemberDto {
+  id: string
+  name: string
+  email: string
+  image: string | null
+  organizationRole: string
+  defaultHourlyRateMinor: number | null
+  canEnterTime: boolean
+  internalApprovalRequired: boolean
+  approverUserIds: string[]
+}
+
+export interface InternalApprovalConfigurationDto {
+  enabled: boolean
+  members: TeamMemberDto[]
+}
+
+export interface InternalApprovalQueueDto {
+  teamMembers: Array<{ id: string; name: string }>
+  settings: TimesheetSettingsDto
+  approvals: ApprovalQueueItemDto[]
+  clients: ClientDto[]
+  projects: ProjectDto[]
+  activities: ActivityTypeDto[]
+}
+
+export interface TimesheetsSetupStatusDto {
+  complete: boolean
+  hasClient: boolean
+  hasActiveActivity: boolean
+  hasConfiguredProject: boolean
+  billableWorkExists: boolean
+  enabledMemberCount: number
+  missingDefaultTariffCount: number
+}
+
+export interface ClientDto {
+  id: string
+  organizationId: string
+  name: string
+  officialName: string | null
+  slug: string
+  logo: string | null
+  accessMode: ClientAccessMode
+}
+
+export interface ClientWorkspaceDto {
+  id: string
+  workspaceOrganizationId: string
+  workspaceName: string
+  accessMode: ClientAccessMode
+  canReview: boolean
+  canManageReviewers: boolean
+}
+export interface ClientReviewerDto {
+  id: string
+  name: string
+  email: string
+  role: string
+  assigned: boolean
+  fixedAccess: boolean
+}
+export interface ClientTimesheetEntryDto {
+  id: string
+  date: string
+  project: string
+  person: string
+  activity: string
+  minutes: number
+  note: string | null
+}
+export interface ClientTimesheetHistoryDto {
+  id: string
+  action: 'SUBMITTED' | 'APPROVED_INTERNAL' | 'REOPENED' | 'APPROVED_CLIENT' | 'DISPUTED_CLIENT'
+  actorName: string
+  comment: string | null
+  createdAt: string
+}
+export interface ClientTimesheetSliceDto {
+  weeklyTimesheetId: string
+  submissionId: string
+  weekStartsOn: string
+  periodStartsOn: string
+  periodEndsOn: string
+  person: string
+  status: ClientReviewStatus
+  version: number
+  comment: string | null
+  reviewedAt: string | null
+  entries: ClientTimesheetEntryDto[]
+  history: ClientTimesheetHistoryDto[]
+}
+export interface ClientTimesheetsDto {
+  workspace: ClientWorkspaceDto
+  slices: ClientTimesheetSliceDto[]
+}
+export interface ClientApprovalItemDto {
+  timeline?: SubmissionHistoryEventDto[]
+  messages?: SubmissionMessageDto[]
+  userId: string
+  id: string
+  workspaceClientId: string
+  supplierName: string
+  weeklyTimesheetId: string
+  submissionId: string
+  weekStartsOn: string
+  periodStartsOn: string
+  periodEndsOn: string
+  person: string
+  totalMinutes: number
+  status: ClientReviewStatus
+  version: number
+  comment: string | null
+  reviewedAt: string | null
+  reviewerName: string | null
+  reviewerUserId: string | null
+  hasReviewers: boolean
+  canAct: boolean
+  canManageReviewers: boolean
+  entries: ClientTimesheetEntryDto[]
+  history: ClientTimesheetHistoryDto[]
+}
+export interface ClientApprovalsDto {
+  isAdmin: boolean
+  pendingCount: number
+  items: ClientApprovalItemDto[]
+}
+export interface ClientSupplierTimesheetItemDto extends ClientTimesheetSliceDto {
+  id: string
+  workspaceClientId: string
+  supplierName: string
+  totalMinutes: number
+}
+export interface ClientReviewerSupplierDto extends ClientWorkspaceDto {
+  pendingCount: number
+  reviewerCount: number
+}
+export interface ClientApprovalSupplierOptionDto {
+  id: string
+  name: string
+}
+
+export interface ClientOrganizationOptionDto {
+  id: string
+  name: string
+  slug: string
+  logo: string | null
+}
+
+export interface ActivityTypeDto {
+  id: string
+  name: string
+  billable: boolean
+  active: boolean
+}
+
+export interface ProjectDto {
+  id: string
+  clientOrganizationId: string
+  clientName: string
+  internal: boolean
+  name: string
+  code: string | null
+  status: ProjectStatus
+  startsOn: string | null
+  endsOn: string | null
+  budgetMinutes: number | null
+  budgetMinor: number | null
+  activityTypeIds: string[]
+  personRates: Record<string, number>
+}
+
+export interface TimeEntryDto {
+  id: string
+  projectId: string
+  activityTypeId: string
+  entryDate: string
+  durationMinutes: number
+  note: string | null
+  billable: boolean
+  hourlyRateMinor: number
+  currency: string
+  timerStartedAt: string | null
+  submissionId: string | null
+  submissionStatus: TimesheetStatus | null
+}
+
+export interface TimesheetSubmissionDto {
+  history?: SubmissionHistoryEventDto[]
+  clientThreads?: ClientSubmissionThreadDto[]
+  messages?: SubmissionMessageDto[]
+  id: string
+  periodStartsOn: string
+  periodEndsOn: string
+  status: TimesheetStatus
+  submittedAt: string | null
+  reviewedAt: string | null
+  reviewedById: string | null
+  reviewerName: string | null
+  reviewerImage: string | null
+  rejectionComment: string | null
+  version: number
+  entryIds: string[]
+}
+
+export interface WeekDto {
+  id: string
+  userId: string
+  weekStartsOn: string
+  status: TimesheetStatus
+  submittedAt: string | null
+  reviewedAt: string | null
+  reviewedById: string | null
+  rejectionComment: string | null
+  entries: TimeEntryDto[]
+  submissions: TimesheetSubmissionDto[]
+}
+
+export interface TimesheetBootstrapDto {
+  runningTimer: TimeEntryDto | null
+  canStartTimer: boolean
+  settings: TimesheetSettingsDto
+  clients: ClientDto[]
+  projects: ProjectDto[]
+  activities: ActivityTypeDto[]
+  team: TeamMemberDto[]
+  week: WeekDto
+  canEnterTime: boolean
+  setupStatus: TimesheetsSetupStatusDto
+}
+
+export interface TimesheetCapabilitiesDto {
+  canEnterTime: boolean
+  canApproveInternalTimesheets: boolean
+  hasInternalApprovalAssignments: boolean
+  canManageTimesheets: boolean
+  canReviewClientTimesheets: boolean
+  canViewSupplierTime: boolean
+  canAccessApprovals: boolean
+  canManageClientReviewers: boolean
+  pendingInternalApprovalCount: number
+  pendingClientApprovalCount: number
+  unassignedClientReviewerSupplierCount: number
+}
+
+export interface TimesheetsDashboardDto {
+  myWeek?: {
+    projects: Array<{ id: string; name: string; clientName: string; totalMinutes: number }>
+    previousSubmissions: Array<{
+      id: string
+      weekStartsOn: string
+      periodStartsOn: string
+      periodEndsOn: string
+      status: TimesheetStatus
+      totalMinutes: number
+    }>
+    weekStartsOn: string
+    status: TimesheetStatus
+    totalMinutes: number
+    rejectionComment: string | null
+    hasRunningTimer: boolean
+    batches: Array<{
+      id: string
+      status: TimesheetStatus
+      totalMinutes: number
+      periodStartsOn: string
+      periodEndsOn: string
+    }>
+    unsubmitted: {
+      totalMinutes: number
+      periodStartsOn: string
+      periodEndsOn: string
+    } | null
+  }
+  internalApprovals?: {
+    pendingCount: number
+    items: Array<
+      Pick<
+        ApprovalQueueItemDto,
+        | 'id'
+        | 'userName'
+        | 'weekStartsOn'
+        | 'periodStartsOn'
+        | 'periodEndsOn'
+        | 'totalMinutes'
+        | 'submittedAt'
+        | 'status'
+      >
+    >
+  }
+  clientApprovals?: {
+    pendingCount: number
+    hasHistory: boolean
+    unassignedSupplierCount: number
+    items: Array<
+      Pick<
+        ClientApprovalItemDto,
+        | 'id'
+        | 'supplierName'
+        | 'person'
+        | 'weekStartsOn'
+        | 'periodStartsOn'
+        | 'periodEndsOn'
+        | 'totalMinutes'
+        | 'status'
+      >
+    >
+  }
+  supplierTimesheets?: {
+    items: Array<
+      Pick<
+        ClientSupplierTimesheetItemDto,
+        'id' | 'supplierName' | 'person' | 'weekStartsOn' | 'periodStartsOn' | 'periodEndsOn' | 'totalMinutes'
+      >
+    >
+  }
+}
+
+export interface ApprovalQueueItemDto {
+  history?: SubmissionHistoryEventDto[]
+  messages?: SubmissionMessageDto[]
+  id: string
+  userId: string
+  userName: string
+  weekStartsOn: string
+  periodStartsOn: string
+  periodEndsOn: string
+  status: TimesheetStatus
+  totalMinutes: number
+  billableMinutes: number
+  billableAmountMinor: number
+  currency: string
+  submittedAt: string | null
+  entries: TimeEntryDto[]
+  clientReviews: Array<{
+    clientOrganizationId: string
+    status: ClientReviewStatus | 'AUTO_APPROVED'
+    version: number
+    canReply: boolean
+    createdAt: string
+    comment: string | null
+  }>
+}
+
+export interface ReportRowDto {
+  entryId: string
+  date: string
+  client: string
+  project: string
+  person: string
+  activity: string
+  minutes: number
+  billable: boolean
+  hourlyRateMinor: number
+  amountMinor: number
+  currency: string
+  status: TimesheetStatus
+  note: string | null
+}
+
+export interface TimesheetReportDto {
+  rows: ReportRowDto[]
+  totals: {
+    minutes: number
+    billableMinutes: number
+    nonBillableMinutes: number
+    billableAmountMinor: number
+    currency: string
+  }
+}
+
+export interface SubmissionMessageDto {
+  id: string
+  authorUserId: string | null
+  authorName: string | null
+  authorImage: string | null
+  role: 'submitter' | 'reviewer'
+  comment: string
+  createdAt: string
+}
+
+export interface ClientSubmissionThreadDto {
+  clientOrganizationId: string
+  clientName: string
+  status: ClientReviewStatus
+  version: number
+  messages: SubmissionMessageDto[]
+}
+
+export interface SubmissionHistoryEventDto {
+  clientOrganizationId?: string | null
+  actorUserId: string
+  actorImage: string | null
+  comment: string | null
+  id: string
+  action: string
+  actorName: string | null
+  clientName: string | null
+  createdAt: string
+}

package/tokens.css

@@ -0,0 +1,25 @@
+:root {
+  --timesheets-color-running: var(--color-success-600);
+  --timesheets-color-running-soft: var(--color-success-50);
+  --timesheets-color-weekend: var(--color-neutral-50);
+  --timesheets-rule: var(--ui-border);
+  --timesheets-radius: var(--ui-radius);
+  --timesheets-space-cell: 0.75rem;
+  --timesheets-duration-fast: 120ms;
+  --timesheets-ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.dark {
+  --timesheets-color-running: var(--color-success-400);
+  --timesheets-color-running-soft: var(--color-neutral-800);
+  --timesheets-color-weekend: var(--color-neutral-900);
+}
+
+html[data-portal-theme='brutal'] {
+  --timesheets-color-weekend: var(--color-paper-2);
+}
+
+html.dark[data-portal-theme='brutal'] {
+  --timesheets-color-running-soft: var(--color-paper-2);
+  --timesheets-color-weekend: var(--color-paper-2);
+}