@kernhq/module-hr 0.8.0 → 0.9.0

package/src/client/pages/OfficesPage.svelte

@@ -0,0 +1,119 @@
+<script lang="ts">
+import { Badge, Card, EmptyState, navigation, Page, PageHeader, Skeleton, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { hrKeys } from '../query.js'
+
+/**
+ * Where the company works.
+ *
+ * Each card shows the office's **current local time** alongside its country, because that is what an
+ * office list is for once there is more than one — knowing whether Amsterdam is awake. The default
+ * office is marked, since it is where somebody with no assignment lands and where the resolution
+ * ladder bottoms out.
+ */
+const api = getHrApi()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+const officesQuery = createQuery(() => ({
+  queryKey: hrKeys.offices(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.offices.list({ workspaceId, includeArchived: false }),
+}))
+const offices = $derived(officesQuery.data ?? [])
+
+let tick = $state(0)
+$effect(() => {
+  const handle = setInterval(() => {
+    tick++
+  }, 60_000)
+  return () => clearInterval(handle)
+})
+
+function localTime(timezone: string, _tick: number): string {
+  void _tick
+  try {
+    return new Intl.DateTimeFormat(undefined, {
+      timeZone: timezone,
+      hour: 'numeric',
+      minute: '2-digit',
+    }).format(new Date())
+  } catch {
+    return ''
+  }
+}
+
+/** The country's own name for itself, rather than a two-letter code nobody reads. */
+function countryName(code: string): string {
+  try {
+    return new Intl.DisplayNames(undefined, { type: 'region' }).of(code) ?? code
+  } catch {
+    return code
+  }
+}
+</script>
+
+<PageHeader
+  crumbs={[{ label: workspace?.name ?? '' }, { label: t('offices_title') }]}
+  title={t('offices_title')}
+/>
+
+<Page>
+  {#if officesQuery.isLoading}
+    <div class="grid">{#each [1, 2, 3] as n (n)}<Skeleton height="96px" />{/each}</div>
+  {:else if offices.length === 0}
+    <EmptyState icon="building" title={t('offices_none')} description={t('offices_none_desc')} />
+  {:else}
+    <div class="grid">
+      {#each offices as office (office.id)}
+        <Card>
+          <div class="head">
+            <span class="name">{office.name}</span>
+            {#if office.isDefault}<Badge tone="accent">{t('office_default')}</Badge>{/if}
+          </div>
+          <p class="meta">{countryName(office.country)}</p>
+          <div class="foot">
+            <span class="time">{localTime(office.timezone, tick)}</span>
+            <span class="meta">{t('headcount', { count: String(office.headcount) })}</span>
+          </div>
+        </Card>
+      {/each}
+    </div>
+  {/if}
+</Page>
+
+<style>
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 12px;
+}
+.head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  justify-content: space-between;
+}
+.name {
+  font-weight: 500;
+}
+.meta {
+  color: var(--kern-ink-500);
+  font-size: 12px;
+  margin: 4px 0 0;
+}
+.foot {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  margin-block-start: 12px;
+}
+.time {
+  font-size: 15px;
+  font-variant-numeric: tabular-nums;
+}
+</style>

package/src/client/permissions.ts

@@ -0,0 +1,31 @@
+import { session } from '@kernhq/ui'
+import { HR_CAPABILITIES, HR_PERMISSIONS } from './index.js'
+
+/**
+ * What this module lets somebody do, and what this workspace has switched on.
+ *
+ * Two different questions, and the screens have to keep them apart:
+ *
+ * - a **permission** is about the person. Hide what they may never do; disable — with a reason —
+ *   what they cannot do right now. Somebody else in the same workspace may well see it.
+ * - a **capability** is about the workspace. When it is off the feature is not there for anyone,
+ *   the shell never renders the contribution, and the API answers 404 rather than 403.
+ *
+ * The server checks both again regardless. This is about not offering a door that will not open.
+ */
+export { HR_CAPABILITIES, HR_PERMISSIONS }
+
+export type HrPermission = keyof typeof HR_PERMISSIONS
+
+export function canHr(permission: HrPermission): boolean {
+  return session.can(HR_PERMISSIONS[permission])
+}
+
+/**
+ * Whether the viewer can see anybody's record but their own.
+ *
+ * Three widths that do not imply one another — a country HR manager must not silently become a
+ * global one — so "can this person open somebody else's page" is asked once, here.
+ */
+export const canSeeOthers = (): boolean =>
+  canHr('personViewTeam') || canHr('personViewOffice') || canHr('personViewAll')

package/src/client/query.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { formatDays, formatDuration, hrKeys, monthRange } from './query.js'
+
+const words = { hours: (n: string) => `${n}h`, minutes: (n: string) => `${n}m` }
+
+describe('hrKeys', () => {
+  it('scopes a balance by person, so two people do not share a cache entry', () => {
+    expect(hrKeys.leaveBalance('ws', 'alice')).not.toEqual(hrKeys.leaveBalance('ws', 'bob'))
+    // No person means "me", and that must be its own entry rather than colliding with a named one.
+    expect(hrKeys.leaveBalance('ws', undefined)).toEqual(['hr', 'leave-balance', 'ws', 'me'])
+  })
+
+  it('scopes attendance by range, so changing the month refetches', () => {
+    expect(hrKeys.attendanceDays('ws', 'a', '2026-01-01', '2026-01-31')).not.toEqual(
+      hrKeys.attendanceDays('ws', 'a', '2026-02-01', '2026-02-28'),
+    )
+  })
+
+  it('starts every key with the module, so one invalidation can clear all of HR', () => {
+    for (const key of [
+      hrKeys.people('ws'),
+      hrKeys.offices('ws'),
+      hrKeys.clockState('ws'),
+      hrKeys.approvalInbox('ws'),
+    ])
+      expect(key[0]).toBe('hr')
+  })
+})
+
+describe('monthRange', () => {
+  it('covers a whole 31-day month', () => {
+    expect(monthRange(new Date(2026, 0, 15))).toEqual({ from: '2026-01-01', to: '2026-01-31' })
+  })
+  it('covers February in a leap year and a common one', () => {
+    expect(monthRange(new Date(2024, 1, 10)).to).toBe('2024-02-29')
+    expect(monthRange(new Date(2026, 1, 10)).to).toBe('2026-02-28')
+  })
+  it('covers a 30-day month', () => {
+    expect(monthRange(new Date(2026, 3, 5))).toEqual({ from: '2026-04-01', to: '2026-04-30' })
+  })
+})
+
+describe('formatDuration', () => {
+  it('shows hours and minutes together', () => {
+    expect(formatDuration(495, words, 'en')).toBe('8h 15m')
+  })
+  it('drops an empty part', () => {
+    expect(formatDuration(480, words, 'en')).toBe('8h')
+    expect(formatDuration(45, words, 'en')).toBe('45m')
+    expect(formatDuration(0, words, 'en')).toBe('0m')
+  })
+  it('keeps a negative readable', () => {
+    expect(formatDuration(-90, words, 'en')).toBe('-1h 30m')
+  })
+  it('uses the locale’s digits', () => {
+    // A Persian screen with Latin numerals in the one place a number appears looks broken.
+    expect(formatDuration(480, words, 'fa')).toBe('۸h')
+  })
+})
+
+describe('formatDays', () => {
+  it('keeps halves and drops trailing zeros', () => {
+    expect(formatDays(20, 'en')).toBe('20')
+    expect(formatDays(19.5, 'en')).toBe('19.5')
+    expect(formatDays(19.25, 'en')).toBe('19.25')
+  })
+  it('uses the locale’s digits', () => {
+    expect(formatDays(20, 'fa')).toBe('۲۰')
+  })
+})

package/src/client/query.ts

@@ -0,0 +1,69 @@
+/**
+ * Query keys for HR.
+ *
+ * `[module, entity, …scope]`, so a realtime `change` event invalidates precisely what it touched.
+ * The scope is part of the key wherever a screen can ask the same question about different subjects
+ * — a balance for me and a balance for somebody I manage are different answers, and sharing a key
+ * would serve one person the other's numbers from cache.
+ */
+export const hrKeys = {
+  people: (ws: string, filters?: Record<string, unknown>) =>
+    filters ? (['hr', 'people', ws, filters] as const) : (['hr', 'people', ws] as const),
+  person: (ws: string, id: string) => ['hr', 'person', ws, id] as const,
+  me: (ws: string) => ['hr', 'me', ws] as const,
+  resolution: (ws: string, personId: string) => ['hr', 'resolution', ws, personId] as const,
+  employment: (ws: string, personId: string) => ['hr', 'employment', ws, personId] as const,
+  orgUnits: (ws: string) => ['hr', 'org-units', ws] as const,
+  offices: (ws: string) => ['hr', 'offices', ws] as const,
+  calendars: (ws: string) => ['hr', 'calendars', ws] as const,
+  calendarDays: (ws: string, calendarId: string, from: string, to: string) =>
+    ['hr', 'calendar-days', ws, calendarId, from, to] as const,
+  leaveTypes: (ws: string) => ['hr', 'leave-types', ws] as const,
+  leaveBalance: (ws: string, personId: string | undefined) =>
+    ['hr', 'leave-balance', ws, personId ?? 'me'] as const,
+  leaveRequests: (ws: string, personId: string | undefined) =>
+    ['hr', 'leave-requests', ws, personId ?? 'me'] as const,
+  leaveCalendar: (ws: string, from: string, to: string) => ['hr', 'leave-calendar', ws, from, to] as const,
+  clockState: (ws: string) => ['hr', 'clock-state', ws] as const,
+  attendanceDays: (ws: string, personId: string | undefined, from: string, to: string) =>
+    ['hr', 'attendance-days', ws, personId ?? 'me', from, to] as const,
+  schedules: (ws: string) => ['hr', 'schedules', ws] as const,
+  approvalInbox: (ws: string) => ['hr', 'approvals', ws] as const,
+} as const
+
+/** `YYYY-MM-DD` for a date, in the viewer's own zone rather than UTC. */
+export const isoDate = (d: Date = new Date()): string => new Intl.DateTimeFormat('en-CA').format(d)
+
+/** The first and last day of the month containing `d`, as ISO dates. */
+export function monthRange(d: Date = new Date()): { from: string; to: string } {
+  const y = d.getFullYear()
+  const mo = d.getMonth()
+  const last = new Date(y, mo + 1, 0).getDate()
+  const p = (n: number) => String(n).padStart(2, '0')
+  return { from: `${y}-${p(mo + 1)}-01`, to: `${y}-${p(mo + 1)}-${p(last)}` }
+}
+
+/**
+ * Minutes as a duration somebody reads.
+ *
+ * Takes the wording as parameters rather than importing `$msg`, because a `.ts` module that imports
+ * `$msg` cannot be unit-tested — SvelteKit's aliases come from a plugin vitest does not run.
+ */
+export function formatDuration(
+  minutes: number,
+  words: { hours: (n: string) => string; minutes: (n: string) => string },
+  locale?: string,
+): string {
+  const sign = minutes < 0 ? '-' : ''
+  const abs = Math.abs(Math.round(minutes))
+  const h = Math.floor(abs / 60)
+  const mi = abs % 60
+  const n = (v: number) => new Intl.NumberFormat(locale).format(v)
+  if (h && mi) return `${sign}${words.hours(n(h))} ${words.minutes(n(mi))}`
+  if (h) return `${sign}${words.hours(n(h))}`
+  return `${sign}${words.minutes(n(mi))}`
+}
+
+/** Days, in the viewer's digits, with halves kept and trailing zeros dropped. */
+export const formatDays = (days: number, locale?: string): string =>
+  new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(days)

package/src/client/settings/CalendarsSettings.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+import { EmptyState, SettingsPage } from '@kernhq/ui'
+import { t } from '../i18n.js'
+
+/**
+ * calendars settings.
+ *
+ * The API behind this is complete — the module's server implements the full surface — but the
+ * editing screen is not built yet. Saying so is deliberate: a settings page that renders controls
+ * doing nothing is worse than one that admits what it is, and the shell only reaches this route
+ * because the capability is on.
+ */
+</script>
+
+<SettingsPage title={t('settings_calendars')}>
+  <EmptyState
+    icon="calendar"
+    title={t('settings_calendars')}
+    description={t('settings_not_built')}
+  />
+</SettingsPage>

package/src/client/settings/CapabilitiesSettings.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+import { Card, coreApi, keys, navigation, SettingsPage, Skeleton, Switch, session } from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import type { CoreApi } from '../core-api.js'
+import { t } from '../i18n.js'
+
+/**
+ * Which parts of HR this workspace has.
+ *
+ * The switchboard the whole module is built around: turning one off removes its navigation, its
+ * widgets, its commands, its settings pages and its API — and destroys nothing, so turning it back
+ * on restores exactly what was there.
+ *
+ * Reads the definitions from the module's own manifest rather than a list kept here. A capability
+ * added on the server appears in this screen without anybody editing it, which is the point of
+ * declaring them as data.
+ */
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+const api = coreApi<CoreApi>()
+const queryClient = useQueryClient()
+
+const modulesQuery = createQuery(() => ({
+  queryKey: keys.modules(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.workspaces.modules.list({ workspaceId }),
+}))
+
+const hr = $derived(modulesQuery.data?.find((entry) => entry.manifest.id === 'hr'))
+const definitions = $derived(hr?.manifest.capabilities ?? [])
+const enabled = $derived(new Set(hr?.state.capabilities ?? []))
+
+const setCapability = createMutation(() => ({
+  mutationFn: async (vars: { id: string; on: boolean }) => {
+    const stored = ((hr?.state.settings as Record<string, unknown>)?.$capabilities ?? {}) as Record<
+      string,
+      boolean
+    >
+    // The reserved key is sent whole. Core lifts it out before the module's own settings schema
+    // sees it, which is what stops a zod object stripping every switch on the way past.
+    return api.workspaces.modules.updateSettings({
+      workspaceId,
+      moduleId: 'hr',
+      settings: { $capabilities: { ...stored, [vars.id]: vars.on } },
+    })
+  },
+  onSuccess: () => {
+    // Navigation, widgets and routes are all derived from this, so the whole shell needs to re-read.
+    void queryClient.invalidateQueries({ queryKey: keys.modules(workspaceId) })
+    void queryClient.invalidateQueries({ queryKey: ['hr'] })
+  },
+}))
+
+const nameOf = (id: string): string =>
+  definitions.find((d: { id: string; label: string }) => d.id === id)?.label ?? id
+
+/** A capability whose dependency is off cannot be switched on — the server would prune it anyway. */
+const blockedBy = (deps: string[]) => deps.filter((d) => !enabled.has(d))
+</script>
+
+<SettingsPage title={t('settings_capabilities')} description={t('capabilities_desc')}>
+
+{#if modulesQuery.isLoading}
+  <Skeleton height="220px" />
+{:else}
+  <div class="list">
+    {#each definitions as capability (capability.id)}
+      {@const missing = blockedBy(capability.dependsOn)}
+      <Card>
+        <div class="row">
+          <div class="what">
+            <span class="name">{capability.label}</span>
+            {#if capability.description}
+              <span class="meta">{capability.description}</span>
+            {/if}
+            {#if missing.length}
+              <span class="meta">
+                {t('capability_requires', { name: missing.map(nameOf).join(', ') })}
+              </span>
+            {/if}
+          </div>
+          <!-- The module's own foundation is always on, and a capability whose dependency is off
+               cannot be switched on: the server prunes it anyway, so the control says so. -->
+          <Switch
+            checked={enabled.has(capability.id)}
+            disabled={capability.required || missing.length > 0 || setCapability.isPending}
+            onCheckedChange={(on) => setCapability.mutate({ id: capability.id, on })}
+            label={capability.label}
+          />
+        </div>
+      </Card>
+    {/each}
+  </div>
+{/if}
+</SettingsPage>
+
+<style>
+.list {
+  display: grid;
+  gap: 8px;
+}
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+.what {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+.name {
+  font-weight: 500;
+}
+.meta {
+  color: var(--kern-ink-500);
+  font-size: 12px;
+}
+</style>

package/src/client/settings/LeaveSettings.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+import { EmptyState, SettingsPage } from '@kernhq/ui'
+import { t } from '../i18n.js'
+
+/**
+ * leave settings.
+ *
+ * The API behind this is complete — the module's server implements the full surface — but the
+ * editing screen is not built yet. Saying so is deliberate: a settings page that renders controls
+ * doing nothing is worse than one that admits what it is, and the shell only reaches this route
+ * because the capability is on.
+ */
+</script>
+
+<SettingsPage title={t('settings_leave')}>
+  <EmptyState
+    icon="tree-palm"
+    title={t('settings_leave')}
+    description={t('settings_not_built')}
+  />
+</SettingsPage>

package/src/client/settings/OfficesSettings.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+import { EmptyState, SettingsPage } from '@kernhq/ui'
+import { t } from '../i18n.js'
+
+/**
+ * offices settings.
+ *
+ * The API behind this is complete — the module's server implements the full surface — but the
+ * editing screen is not built yet. Saying so is deliberate: a settings page that renders controls
+ * doing nothing is worse than one that admits what it is, and the shell only reaches this route
+ * because the capability is on.
+ */
+</script>
+
+<SettingsPage title={t('settings_offices')}>
+  <EmptyState
+    icon="building"
+    title={t('settings_offices')}
+    description={t('settings_not_built')}
+  />
+</SettingsPage>

package/src/client/settings/SchedulesSettings.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+import { EmptyState, SettingsPage } from '@kernhq/ui'
+import { t } from '../i18n.js'
+
+/**
+ * schedules settings.
+ *
+ * The API behind this is complete — the module's server implements the full surface — but the
+ * editing screen is not built yet. Saying so is deliberate: a settings page that renders controls
+ * doing nothing is worse than one that admits what it is, and the shell only reaches this route
+ * because the capability is on.
+ */
+</script>
+
+<SettingsPage title={t('settings_schedules')}>
+  <EmptyState
+    icon="clock"
+    title={t('settings_schedules')}
+    description={t('settings_not_built')}
+  />
+</SettingsPage>

package/src/client/widgets/ApprovalsWidget.svelte

@@ -0,0 +1,86 @@
+<script lang="ts">
+import { Badge, Button, EmptyState, Skeleton, type WidgetProps } 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'
+
+/**
+ * Requests waiting on me, decidable from the card.
+ *
+ * Acting on a row rather than linking away from it: the whole value of this card is approving three
+ * leave requests without leaving the dashboard, and a card that only counts them is a link with
+ * extra steps.
+ */
+const { workspaceId, editing }: WidgetProps = $props()
+const api = getHrApi()
+const queryClient = useQueryClient()
+
+const inboxQuery = createQuery(() => ({
+  queryKey: hrKeys.approvalInbox(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.approvals.inbox({ workspaceId, limit: 5, includeDecided: false }),
+}))
+const items = $derived(inboxQuery.data?.items ?? [])
+
+const decide = createMutation(() => ({
+  mutationFn: (vars: { requestId: string; decision: 'approve' | 'reject' }) =>
+    api.approvals.decide({ workspaceId, ...vars }),
+  onSuccess: () => void queryClient.invalidateQueries({ queryKey: ['hr'] }),
+}))
+</script>
+
+{#if inboxQuery.isLoading}
+  <Skeleton height="96px" />
+{:else if items.length === 0}
+  <EmptyState bare compact icon="check-check" title={t('approvals_none')} />
+{:else}
+  <ul>
+    {#each items as item (item.id)}
+      <li>
+        <span class="summary">{item.summary}</span>
+        <!-- Row actions go while the grid is being rearranged: the data stays, the buttons do not. -->
+        {#if editing}
+          <Badge tone="upcoming">{t('leave_pending')}</Badge>
+        {:else}
+          <Button
+            size="sm"
+            variant="ghost"
+            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
+          >
+        {/if}
+      </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;
+}
+.summary {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+}
+</style>

package/src/client/widgets/ClockWidget.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+import type { WidgetProps } from '@kernhq/ui'
+import ClockControls from '../components/ClockControls.svelte'
+
+/** The clock, on the dashboard. The frame belongs to the shell, so this is only the control. */
+const { workspaceId }: WidgetProps = $props()
+</script>
+
+<ClockControls {workspaceId} />

package/src/client/widgets/HeadcountWidget.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+import { Skeleton, StatTile, type WidgetProps } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { hrKeys } from '../query.js'
+
+/** How many people work here. One number, so the frame's header is dropped (`compact`). */
+const { workspaceId }: WidgetProps = $props()
+const api = getHrApi()
+
+const peopleQuery = createQuery(() => ({
+  queryKey: hrKeys.people(workspaceId, { status: 'active' }),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.people.list({ workspaceId, limit: 1, status: ['active'] }),
+}))
+// `total` rather than `items.length`: the request asks for one row, because drawing a number does
+// not need the list behind it.
+const count = $derived(peopleQuery.data?.total ?? 0)
+</script>
+
+{#if peopleQuery.isLoading}
+  <Skeleton height="72px" />
+{:else}
+  <StatTile
+    label={t('widget_headcount_title')}
+    value={new Intl.NumberFormat().format(count)}
+  />
+{/if}