@kernhq/module-hr 0.7.0 → 0.9.0

package/src/client/widgets/LeaveBalanceWidget.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+import { EmptyState, Skeleton, type WidgetProps } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { formatDays, hrKeys } from '../query.js'
+
+/**
+ * What is left of each kind of leave.
+ *
+ * Shows `available`, not `balance`: pending requests are already spoken for, and a card promising
+ * twenty days when five are awaiting approval is how somebody books a week they do not have.
+ */
+const { workspaceId }: WidgetProps = $props()
+const api = getHrApi()
+
+const balanceQuery = createQuery(() => ({
+  queryKey: hrKeys.leaveBalance(workspaceId, undefined),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.leave.balance.get({ workspaceId }),
+}))
+const balances = $derived(balanceQuery.data ?? [])
+</script>
+
+{#if balanceQuery.isLoading}
+  <Skeleton height="72px" />
+{:else if balances.length === 0}
+  <EmptyState bare compact icon="tree-palm" title={t('leave_none')} />
+{:else}
+  <ul>
+    {#each balances as b (b.leaveTypeId)}
+      <li>
+        <span class="name">{b.leaveTypeName}</span>
+        <span class="value">{formatDays(b.available)} <span class="unit">{t('days')}</span></span>
+      </li>
+    {/each}
+  </ul>
+{/if}
+
+<style>
+ul {
+  display: grid;
+  gap: 8px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+li {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+}
+.name {
+  color: var(--kern-ink-500);
+  font-size: 12px;
+  min-width: 0;
+}
+.value {
+  font-size: 15px;
+  font-variant-numeric: tabular-nums;
+}
+.unit {
+  font-size: 12px;
+  color: var(--kern-ink-500);
+}
+</style>

package/src/client/widgets/WhosOutWidget.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+import { Avatar, EmptyState, Skeleton, type WidgetProps } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { hrKeys, isoDate } from '../query.js'
+
+/**
+ * Who is away over the next fortnight.
+ *
+ * The leave *type* is shown only when the server sends it — most companies want the team to know
+ * somebody is out without knowing it is sick leave, so the decision is made server-side and this
+ * renders whatever it was given.
+ */
+const { workspaceId }: WidgetProps = $props()
+const api = getHrApi()
+
+const from = isoDate()
+const to = isoDate(new Date(Date.now() + 14 * 86_400_000))
+
+const outQuery = createQuery(() => ({
+  queryKey: hrKeys.leaveCalendar(workspaceId, from, to),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.leave.team.calendar({ workspaceId, from, to }),
+}))
+const away = $derived(outQuery.data ?? [])
+
+const range = (a: string, b: string) =>
+  new Intl.DateTimeFormat(undefined, { day: 'numeric', month: 'short' }).formatRange(
+    new Date(`${a}T00:00:00`),
+    new Date(`${b}T00:00:00`),
+  )
+</script>
+
+{#if outQuery.isLoading}
+  <Skeleton height="96px" />
+{:else if away.length === 0}
+  <EmptyState bare compact icon="calendar-days" title={t('leave_none')} />
+{:else}
+  <ul>
+    {#each away as person (person.requestId)}
+      <li>
+        <Avatar name={person.displayName} id={person.personId} size={24} />
+        <span class="name">{person.displayName}</span>
+        <span class="meta">{range(person.startsOn, person.endsOn)}</span>
+      </li>
+    {/each}
+  </ul>
+{/if}
+
+<style>
+ul {
+  display: grid;
+  gap: 8px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+li {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.meta {
+  color: var(--kern-ink-500);
+  font-size: 12px;
+}
+</style>

package/src/contract/capabilities.ts

@@ -74,6 +74,24 @@ export const hrCapabilities = defineCapabilities([
     defaultEnabled: true,
     level: 1,
   },
+  {
+    id: 'leave_accrual',
+    label: 'Accrual',
+    description: 'Earn leave over time, with proration, carry-forward and expiry',
+    dependsOn: ['leave'],
+    // Off by default. Plenty of companies grant a fixed allowance on 1 January and never accrue —
+    // and for them an accrual engine is a screen full of settings that change nothing.
+    defaultEnabled: false,
+    level: 2,
+  },
+  {
+    id: 'periods',
+    label: 'Payroll periods',
+    description: 'Close a month so a filed payroll cannot move underneath it',
+    dependsOn: ['core'],
+    defaultEnabled: false,
+    level: 2,
+  },
   {
     id: 'approvals',
     label: 'Approval chains',
@@ -185,6 +203,19 @@ export const hrCapabilityProcedures: Record<string, readonly string[]> = {
     'attendance.regularizations.list',
     'attendance.regularizations.request',
   ],
+  leave_accrual: [
+    'policies.list',
+    'policies.get',
+    'policies.create',
+    'policies.update',
+    'policies.archive',
+    'policies.assign',
+    'policies.unassign',
+    'policies.resolveFor',
+    'accrual.preview',
+    'accrual.run',
+  ],
+  periods: ['periods.list', 'periods.create', 'periods.lock', 'periods.unlock'],
   approvals: [
     'approvals.chains.list',
     'approvals.chains.create',

package/src/contract/index.ts

@@ -13,5 +13,6 @@ export * from './events.js'
 export * from './leave.js'
 export * from './models.js'
 export * from './permissions.js'
+export * from './policies.js'
 export * from './router.js'
 export * from './settings.js'

package/src/contract/permissions.ts

@@ -273,6 +273,31 @@ export const hrPermissions = definePermissions([
     dangerous: false,
   },
 
+  // ---------------------------------------------------------------- policies and periods
+  {
+    key: 'hr.policy.view',
+    label: 'View accrual, overtime and rounding policies',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+  {
+    key: 'hr.policy.manage',
+    label: 'Change policies and who they apply to',
+    description: 'Changes what everybody accrues. A retroactive change is an adjustment, not a rewrite.',
+    scope: 'workspace',
+    defaultRoles: ['owner'],
+    dangerous: true,
+  },
+  {
+    key: 'hr.period.manage',
+    label: 'Open, lock and unlock payroll periods',
+    description: 'Locking freezes a month against recomputation. Unlocking lets it move again.',
+    scope: 'workspace',
+    defaultRoles: ['owner'],
+    dangerous: true,
+  },
+
   // ---------------------------------------------------------------- approvals
   {
     key: 'hr.approval.manage',
@@ -334,6 +359,9 @@ export const HR_PERMISSIONS = {
   attendanceManage: 'hr.attendance.manage',
   overtimeView: 'hr.overtime.view',
   overtimeManage: 'hr.overtime.manage',
+  policyView: 'hr.policy.view',
+  policyManage: 'hr.policy.manage',
+  periodManage: 'hr.period.manage',
   approvalManage: 'hr.approval.manage',
   approvalDelegate: 'hr.approval.delegate',
 } as const

package/src/contract/router.ts

@@ -53,6 +53,15 @@ import {
   TimeZone,
   WorkingWeek,
 } from './models.js'
+import {
+  AccrualPreview,
+  Period,
+  Policy,
+  PolicyAssignment,
+  PolicyKind,
+  PolicySubjectKind,
+  ResolvedPolicy,
+} from './policies.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
 const t = ['hr'] as const
@@ -602,6 +611,145 @@ export const hrContract = {
       .output(ok),
   },
 
+  // ---------------------------------------------------------------- policies
+  policies: {
+    list: baseContract
+      .route({ method: 'GET', path: '/policies', tags: t })
+      .input(ws.extend({ kind: PolicyKind.optional(), includeArchived: z.boolean().default(false) }))
+      .output(z.array(Policy.extend({ assignments: z.array(PolicyAssignment) }))),
+    get: baseContract
+      .route({ method: 'GET', path: '/policies/{policyId}', tags: t })
+      .input(ws.extend({ policyId: z.uuid() }))
+      .output(Policy.extend({ assignments: z.array(PolicyAssignment) })),
+    create: baseContract
+      .route({ method: 'POST', path: '/policies', tags: t })
+      .input(
+        ws.extend({
+          kind: PolicyKind,
+          name: z.string().min(1).max(120),
+          /** Validated against the schema for `kind` — a config for the wrong kind is refused. */
+          config: z.record(z.string(), z.unknown()),
+          effectiveFrom: IsoDate,
+          effectiveTo: IsoDate.nullish(),
+        }),
+      )
+      .output(Policy),
+    /**
+     * Edits a policy in place.
+     *
+     * A change that should apply from a date rather than retroactively is a **new** policy with a
+     * later `effectiveFrom`, not an edit — editing rewrites what was true in the past, and anything
+     * already derived from it becomes unexplainable.
+     */
+    update: baseContract
+      .route({ method: 'PATCH', path: '/policies/{policyId}', tags: t })
+      .input(
+        ws.extend({
+          policyId: z.uuid(),
+          name: z.string().min(1).max(120).optional(),
+          config: z.record(z.string(), z.unknown()).optional(),
+          effectiveTo: IsoDate.nullish(),
+        }),
+      )
+      .output(Policy),
+    archive: baseContract
+      .route({ method: 'DELETE', path: '/policies/{policyId}', tags: t })
+      .input(ws.extend({ policyId: z.uuid() }))
+      .output(ok),
+    assign: baseContract
+      .route({ method: 'POST', path: '/policies/{policyId}/assign', tags: t })
+      .input(
+        ws.extend({
+          policyId: z.uuid(),
+          subjectKind: PolicySubjectKind,
+          /** Null for `workspace`, which needs no id. */
+          subjectId: z.uuid().nullish(),
+          effectiveFrom: IsoDate,
+          effectiveTo: IsoDate.nullish(),
+        }),
+      )
+      .output(PolicyAssignment),
+    unassign: baseContract
+      .route({ method: 'DELETE', path: '/policies/assignments/{assignmentId}', tags: t })
+      .input(ws.extend({ assignmentId: z.uuid() }))
+      .output(ok),
+    /**
+     * Which policy of each kind applies to this person on this date, and which rung answered.
+     *
+     * "Why does she accrue differently from her team" is the question this module gets asked, and
+     * this is what answers it without a database session.
+     */
+    resolveFor: baseContract
+      .route({ method: 'GET', path: '/people/{personId}/policies', tags: t })
+      .input(ws.extend({ personId: z.uuid(), on: IsoDate.optional() }))
+      .output(z.array(ResolvedPolicy)),
+  },
+
+  // ---------------------------------------------------------------- accrual
+  accrual: {
+    /**
+     * What a run would credit, per person, before it writes anything.
+     *
+     * Runs the same code the run does. A preview computed differently from the thing it previews is
+     * a preview that eventually lies.
+     */
+    preview: baseContract
+      .route({ method: 'POST', path: '/accrual/preview', tags: t })
+      .input(ws.extend({ from: IsoDate, to: IsoDate, personId: z.uuid().optional() }))
+      .output(AccrualPreview),
+    /**
+     * Credits the ledger.
+     *
+     * Idempotent per person, per leave type, per period: a second run for the same window credits
+     * nothing, because an accrual job that double-credits when somebody clicks twice is worse than
+     * one that never ran.
+     */
+    run: baseContract
+      .route({ method: 'POST', path: '/accrual/run', tags: t })
+      .input(ws.extend({ from: IsoDate, to: IsoDate, personId: z.uuid().optional() }))
+      .output(
+        z.object({
+          credited: z.number().int(),
+          skipped: z.number().int(),
+          totalMinutes: z.number().int(),
+        }),
+      ),
+  },
+
+  // ---------------------------------------------------------------- periods
+  periods: {
+    list: baseContract
+      .route({ method: 'GET', path: '/periods', tags: t })
+      .input(ws.extend({ kind: Period.shape.kind.optional(), ...PageInput.shape }))
+      .output(page(Period)),
+    create: baseContract
+      .route({ method: 'POST', path: '/periods', tags: t })
+      .input(
+        ws.extend({
+          kind: Period.shape.kind.default('payroll'),
+          legalEntityId: z.uuid().nullish(),
+          startsOn: IsoDate,
+          endsOn: IsoDate,
+        }),
+      )
+      .output(Period),
+    /** Freezes the month. Every derived day inside it stops being recomputable. */
+    lock: baseContract
+      .route({ method: 'POST', path: '/periods/{periodId}/lock', tags: t })
+      .input(ws.extend({ periodId: z.uuid(), note: z.string().max(500).nullish() }))
+      .output(Period.extend({ lockedDays: z.number().int() })),
+    /**
+     * Reopens it.
+     *
+     * Dangerous on purpose: a payroll has usually been filed against a locked month, and reopening
+     * lets figures move underneath it. The response says how many days became recomputable again.
+     */
+    unlock: baseContract
+      .route({ method: 'POST', path: '/periods/{periodId}/unlock', tags: t })
+      .input(ws.extend({ periodId: z.uuid(), reason: z.string().min(1).max(500) }))
+      .output(Period.extend({ unlockedDays: z.number().int() })),
+  },
+
   // ---------------------------------------------------------------- attendance
   attendance: {
     /** Am I clocked in? The one call a clock widget makes. */