@kernhq/module-hr 0.8.0 → 0.9.1

package/src/client/module.ts

@@ -0,0 +1,295 @@
+import { defineClientModule } from '@kernhq/ui'
+import { hrMessageBundles, t } from './i18n.js'
+import { HR_CAPABILITIES, HR_PERMISSIONS } from './permissions.js'
+
+/**
+ * HR as the shell sees it.
+ *
+ * Every contribution carries two independent gates, and they answer different questions:
+ *
+ * - `permission` — may *this person* reach it. Someone else in the workspace may well see it.
+ * - `capability` — does *this workspace* have the feature at all. When it is off nobody sees it,
+ *   including an owner, and the API behind it answers 404 rather than 403.
+ *
+ * That second gate is why this module can be a staff directory for one company and a shift-rostering
+ * system for another without a line of conditional code. A workspace that never switches attendance
+ * on has no clock widget, no attendance nav, no schedule settings and no attendance commands — not
+ * greyed out, not there.
+ *
+ * Labels are getters rather than strings because a module is defined once at import time while the
+ * interface language can change afterwards; reading them on render keeps the rail and the palette in
+ * the language the person actually chose.
+ */
+export const hrClientModule = defineClientModule({
+  id: 'hr',
+  name: 'People',
+  icon: 'users',
+  messages: hrMessageBundles,
+
+  nav: [
+    {
+      id: 'hr',
+      get label() {
+        return t('nav')
+      },
+      icon: 'users',
+      href: '/hr',
+      order: 30,
+      permission: HR_PERMISSIONS.personView,
+    },
+  ],
+
+  routes: [
+    {
+      path: '/hr/leave',
+      component: () => import('./pages/LeavePage.svelte'),
+      get title() {
+        return t('leave_title')
+      },
+      permission: HR_PERMISSIONS.leaveView,
+      capability: HR_CAPABILITIES.leave,
+    },
+    {
+      path: '/hr/attendance',
+      component: () => import('./pages/AttendancePage.svelte'),
+      get title() {
+        return t('attendance_title')
+      },
+      permission: HR_PERMISSIONS.attendanceView,
+      capability: HR_CAPABILITIES.attendance,
+    },
+    {
+      path: '/hr/approvals',
+      component: () => import('./pages/ApprovalsPage.svelte'),
+      get title() {
+        return t('approvals_title')
+      },
+    },
+    {
+      path: '/hr/offices',
+      component: () => import('./pages/OfficesPage.svelte'),
+      get title() {
+        return t('offices_title')
+      },
+      permission: HR_PERMISSIONS.officeView,
+      capability: HR_CAPABILITIES.offices,
+    },
+    {
+      // Last: the shell matches in order, and `/hr` would otherwise swallow the paths above it.
+      path: '/hr',
+      component: () => import('./pages/DirectoryPage.svelte'),
+      get title() {
+        return t('title')
+      },
+      permission: HR_PERMISSIONS.personView,
+    },
+  ],
+
+  widgets: [
+    {
+      id: 'hr.clock',
+      get title() {
+        return t('widget_clock_title')
+      },
+      get description() {
+        return t('widget_clock_desc')
+      },
+      icon: 'timer',
+      permission: HR_PERMISSIONS.attendancePunch,
+      capability: HR_CAPABILITIES.attendance,
+      sizes: ['s', 'm'],
+      defaultSize: 's',
+      compact: true,
+      order: 10,
+      component: () => import('./widgets/ClockWidget.svelte'),
+    },
+    {
+      id: 'hr.my-leave',
+      get title() {
+        return t('widget_balance_title')
+      },
+      get description() {
+        return t('widget_balance_desc')
+      },
+      icon: 'tree-palm',
+      permission: HR_PERMISSIONS.leaveView,
+      capability: HR_CAPABILITIES.leave,
+      sizes: ['s', 'm'],
+      defaultSize: 'm',
+      order: 20,
+      component: () => import('./widgets/LeaveBalanceWidget.svelte'),
+    },
+    {
+      id: 'hr.whos-out',
+      get title() {
+        return t('widget_whos_out_title')
+      },
+      get description() {
+        return t('widget_whos_out_desc')
+      },
+      icon: 'calendar-days',
+      permission: HR_PERMISSIONS.leaveViewTeam,
+      capability: HR_CAPABILITIES.leave,
+      sizes: ['m', 'l'],
+      defaultSize: 'm',
+      order: 30,
+      component: () => import('./widgets/WhosOutWidget.svelte'),
+    },
+    {
+      id: 'hr.approvals',
+      get title() {
+        return t('widget_approvals_title')
+      },
+      get description() {
+        return t('widget_approvals_desc')
+      },
+      icon: 'check-check',
+      sizes: ['s', 'm', 'l'],
+      defaultSize: 'm',
+      order: 40,
+      component: () => import('./widgets/ApprovalsWidget.svelte'),
+    },
+    {
+      id: 'hr.headcount',
+      get title() {
+        return t('widget_headcount_title')
+      },
+      get description() {
+        return t('widget_headcount_desc')
+      },
+      icon: 'users',
+      permission: HR_PERMISSIONS.personView,
+      sizes: ['s'],
+      defaultSize: 's',
+      compact: true,
+      order: 50,
+      component: () => import('./widgets/HeadcountWidget.svelte'),
+    },
+  ],
+
+  commands: [
+    {
+      id: 'hr.directory',
+      get label() {
+        return t('cmd_directory')
+      },
+      icon: 'users',
+      permission: HR_PERMISSIONS.personView,
+      run: (ctx) => ctx.navigate('/hr'),
+    },
+    {
+      id: 'hr.request-leave',
+      get label() {
+        return t('cmd_request_leave')
+      },
+      icon: 'tree-palm',
+      permission: HR_PERMISSIONS.leaveRequest,
+      capability: HR_CAPABILITIES.leave,
+      run: (ctx) => ctx.navigate('/hr/leave?new=1'),
+    },
+    {
+      id: 'hr.my-attendance',
+      get label() {
+        return t('cmd_attendance')
+      },
+      icon: 'timer',
+      permission: HR_PERMISSIONS.attendanceView,
+      capability: HR_CAPABILITIES.attendance,
+      run: (ctx) => ctx.navigate('/hr/attendance'),
+    },
+    {
+      id: 'hr.approvals',
+      get label() {
+        return t('cmd_approvals')
+      },
+      icon: 'check-check',
+      run: (ctx) => ctx.navigate('/hr/approvals'),
+    },
+  ],
+
+  sidebar: [
+    {
+      id: 'hr',
+      match: ['hr'],
+      permission: HR_PERMISSIONS.personView,
+      component: () => import('./components/HrSidebar.svelte'),
+    },
+  ],
+
+  /**
+   * Where HR is configured. The shell builds the settings nav from these, and the route is
+   * conventional (`/<ws>/settings/hr/<id>`), and the shell mounts whatever is declared here — there
+   * is no route file in the app to keep in step with it any more.
+   */
+  settingsPages: [
+    {
+      id: 'capabilities',
+      get label() {
+        return t('settings_capabilities')
+      },
+      icon: 'toggle-left',
+      scope: 'workspace',
+      permission: 'core.workspace.manage',
+      order: 5,
+      component: () => import('./settings/CapabilitiesSettings.svelte'),
+    },
+    {
+      id: 'offices',
+      get label() {
+        return t('settings_offices')
+      },
+      icon: 'building',
+      scope: 'workspace',
+      permission: HR_PERMISSIONS.officeManage,
+      capability: HR_CAPABILITIES.offices,
+      order: 10,
+      component: () => import('./settings/OfficesSettings.svelte'),
+    },
+    {
+      id: 'calendars',
+      get label() {
+        return t('settings_calendars')
+      },
+      icon: 'calendar',
+      scope: 'workspace',
+      permission: HR_PERMISSIONS.calendarManage,
+      capability: HR_CAPABILITIES.calendars,
+      order: 20,
+      component: () => import('./settings/CalendarsSettings.svelte'),
+    },
+    {
+      id: 'leave',
+      get label() {
+        return t('settings_leave')
+      },
+      icon: 'tree-palm',
+      scope: 'workspace',
+      permission: HR_PERMISSIONS.leaveManage,
+      capability: HR_CAPABILITIES.leave,
+      order: 30,
+      component: () => import('./settings/LeaveSettings.svelte'),
+    },
+    {
+      id: 'schedules',
+      get label() {
+        return t('settings_schedules')
+      },
+      icon: 'clock',
+      scope: 'workspace',
+      permission: HR_PERMISSIONS.attendanceManage,
+      capability: HR_CAPABILITIES.attendance,
+      order: 40,
+      component: () => import('./settings/SchedulesSettings.svelte'),
+    },
+  ],
+
+  presenters: [
+    {
+      type: 'person',
+      inline: () => import('./components/PersonInline.svelte'),
+      page: (id, workspaceSlug) => `/${workspaceSlug}/hr?person=${encodeURIComponent(id)}`,
+    },
+  ],
+})
+
+export default hrClientModule

package/src/client/pages/ApprovalsPage.svelte

@@ -0,0 +1,129 @@
+<script lang="ts">
+import { Badge, Button, Card, EmptyState, navigation, Page, PageHeader, Skeleton, session } from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { hrKeys } from '../query.js'
+
+/**
+ * Everything waiting on me, across every kind of request.
+ *
+ * One inbox rather than one per feature, because the approval engine is keyed by subject type — a
+ * leave request and an attendance correction arrive here the same way, and so will overtime and
+ * timesheets when they exist.
+ *
+ * No permission gate: an inbox of what *you* must decide is yours by definition, and the server only
+ * ever lists steps you are named on.
+ */
+const api = getHrApi()
+const queryClient = useQueryClient()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+const inboxQuery = createQuery(() => ({
+  queryKey: hrKeys.approvalInbox(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.approvals.inbox({ workspaceId, limit: 50, includeDecided: false }),
+}))
+const items = $derived(inboxQuery.data?.items ?? [])
+
+const decide = createMutation(() => ({
+  mutationFn: (vars: { requestId: string; decision: 'approve' | 'reject' }) =>
+    api.approvals.decide({ workspaceId, ...vars }),
+  onSuccess: () => {
+    // Deciding changes a balance and a day sheet as well as the inbox, so the whole module's cache
+    // is invalidated rather than guessing which keys moved.
+    void queryClient.invalidateQueries({ queryKey: ['hr'] })
+  },
+}))
+
+const subjectLabel = (subjectType: string) =>
+  subjectType === 'leave' ? t('leave_title') : t('attendance_title')
+
+const when = (iso: string) =>
+  new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(new Date(iso))
+</script>
+
+<PageHeader
+  crumbs={[{ label: workspace?.name ?? '' }, { label: t('approvals_title') }]}
+  title={t('approvals_title')}
+/>
+
+<Page>
+  {#if inboxQuery.isLoading}
+    <Skeleton height="140px" />
+  {:else if items.length === 0}
+    <EmptyState
+      icon="check-check"
+      title={t('approvals_none')}
+      description={t('approvals_none_desc')}
+    />
+  {:else}
+    <ul>
+      {#each items as item (item.id)}
+        <li>
+          <Card>
+            <div class="row">
+              <div class="what">
+                <Badge tone="upcoming">{subjectLabel(item.subjectType)}</Badge>
+                <span class="summary">{item.summary}</span>
+                <span class="meta">{when(item.requestedAt)}</span>
+              </div>
+              <div class="actions">
+                <Button
+                  size="sm"
+                  variant="secondary"
+                  disabled={decide.isPending}
+                  onclick={() => decide.mutate({ requestId: item.id, decision: 'reject' })}
+                  >{t('reject')}</Button
+                >
+                <Button
+                  size="sm"
+                  disabled={decide.isPending}
+                  onclick={() => decide.mutate({ requestId: item.id, decision: 'approve' })}
+                  >{t('approve')}</Button
+                >
+              </div>
+            </div>
+          </Card>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</Page>
+
+<style>
+ul {
+  display: grid;
+  gap: 8px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.what {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 0;
+}
+.summary {
+  font-weight: 500;
+}
+.meta {
+  color: var(--kern-ink-500);
+  font-size: 12px;
+}
+.actions {
+  display: flex;
+  gap: 8px;
+}
+</style>

package/src/client/pages/AttendancePage.svelte

@@ -0,0 +1,147 @@
+<script lang="ts">
+import { Badge, EmptyState, navigation, Page, PageHeader, Skeleton, StatTile, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import ClockControls from '../components/ClockControls.svelte'
+import { t } from '../i18n.js'
+import { formatDuration, hrKeys, monthRange } from '../query.js'
+
+/**
+ * My attendance: the clock, then the month.
+ *
+ * The totals come from the derived day sheet rather than being added up here — the server already
+ * knows what a day is worth, and a second implementation in the browser is how a screen starts
+ * disagreeing with a payslip.
+ */
+const api = getHrApi()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+const range = $derived(monthRange())
+
+const daysQuery = createQuery(() => ({
+  queryKey: hrKeys.attendanceDays(workspaceId, undefined, range.from, range.to),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.attendance.days.list({ workspaceId, from: range.from, to: range.to, limit: 100 }),
+}))
+const days = $derived(daysQuery.data?.items ?? [])
+
+const words = {
+  hours: (n: string) => t('hours_short', { n }),
+  minutes: (n: string) => t('minutes_short', { n }),
+}
+
+const totals = $derived({
+  worked: days.reduce((sum, d) => sum + d.workedMinutes, 0),
+  scheduled: days.reduce((sum, d) => sum + d.scheduledMinutes, 0),
+  overtime: days.reduce((sum, d) => sum + d.overtimeMinutes, 0),
+})
+
+const statusLabel = (s: string) =>
+  s === 'present'
+    ? t('att_status_present')
+    : s === 'absent'
+      ? t('att_status_absent')
+      : s === 'leave'
+        ? t('att_status_leave')
+        : s === 'holiday'
+          ? t('att_status_holiday')
+          : s === 'weekend'
+            ? t('att_status_weekend')
+            : s === 'partial'
+              ? t('att_status_partial')
+              : t('att_status_pending')
+
+const statusTone = (s: string) =>
+  s === 'present'
+    ? 'done'
+    : s === 'absent'
+      ? 'declined'
+      : s === 'leave'
+        ? 'on-leave'
+        : s === 'pending'
+          ? 'urgent'
+          : 'grey'
+
+const dayLabel = (iso: string) =>
+  new Intl.DateTimeFormat(undefined, { weekday: 'short', day: 'numeric', month: 'short' }).format(
+    new Date(`${iso}T00:00:00`),
+  )
+</script>
+
+<PageHeader
+  crumbs={[{ label: workspace?.name ?? '' }, { label: t('attendance_title') }]}
+  title={t('attendance_title')}
+/>
+
+<Page>
+  <ClockControls {workspaceId} />
+
+  <div class="tiles">
+    <StatTile label={t('att_worked')} value={formatDuration(totals.worked, words)} />
+    <StatTile label={t('att_scheduled')} value={formatDuration(totals.scheduled, words)} />
+    <StatTile label={t('att_overtime')} value={formatDuration(totals.overtime, words)} />
+  </div>
+
+  {#if daysQuery.isLoading}
+    <Skeleton height="200px" />
+  {:else if days.length === 0}
+    <EmptyState
+      icon="timer"
+      title={t('attendance_none')}
+      description={t('attendance_none_desc')}
+    />
+  {:else}
+    <ul>
+      {#each days as day (day.id)}
+        <li class="row">
+          <span class="date">{dayLabel(day.businessDate)}</span>
+          <span class="worked">{formatDuration(day.workedMinutes, words)}</span>
+          {#if day.overtimeMinutes > 0}
+            <span class="ot">+{formatDuration(day.overtimeMinutes, words)}</span>
+          {/if}
+          <!-- An anomaly is why a day needs a human; saying so beats a silent zero. -->
+          {#if day.anomalies.length}
+            <Badge tone="warning">{day.anomalies.length}</Badge>
+          {/if}
+          <Badge tone={statusTone(day.status)}>{statusLabel(day.status)}</Badge>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</Page>
+
+<style>
+.tiles {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+  gap: 12px;
+  margin-block: 16px 20px;
+}
+ul {
+  display: grid;
+  gap: 4px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--kern-border);
+}
+.date {
+  flex: 1;
+}
+.worked,
+.ot {
+  font-variant-numeric: tabular-nums;
+}
+.ot {
+  color: var(--kern-ink-500);
+}
+</style>