@kernhq/module-hr 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-hr",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Kern HR module: people, offices, org chart, calendars",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -44,17 +44,37 @@
   },
   "devDependencies": {
     "@kernhq/tsconfig": "^0.1.0",
+    "@kernhq/ui": "^0.7.0",
+    "@tanstack/svelte-query": "^6.1.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.15.0",
     "drizzle-kit": "^0.31.0",
     "pg": "^8.16.0",
+    "svelte": "^5.46.0",
+    "svelte-check": "^4.0.0",
     "typescript": "~5.9.3",
     "vitest": "^4.0.0"
   },
+  "peerDependencies": {
+    "@kernhq/ui": "^0.7.0",
+    "@tanstack/svelte-query": "^6.1.0",
+    "svelte": "^5.46.0"
+  },
+  "peerDependenciesMeta": {
+    "@kernhq/ui": {
+      "optional": true
+    },
+    "@tanstack/svelte-query": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && svelte-check --tsconfig ./tsconfig.client.json --threshold error",
     "test": "vitest run",
     "db:generate": "drizzle-kit generate"
   }

package/src/client/api-instance.ts

@@ -0,0 +1,29 @@
+import { getHost } from '@kernhq/ui'
+import { createHrClient, type HrApi } from './index.js'
+import { createMockHrApi } from './mock.js'
+
+/**
+ * This module's API client.
+ *
+ * An empty base URL keeps requests same-origin, so the dev proxy and the reverse proxy both work
+ * without CORS. `PUBLIC_API_MOCK=1` swaps in the in-memory implementation, which satisfies the same
+ * contract types — so no screen has a second code path for demos and end-to-end tests.
+ */
+export type { HrApi }
+
+let cached: HrApi | null = null
+
+export function getHrApi(): HrApi {
+  if (cached) return cached
+  cached = getHost().isMock
+    ? (createMockHrApi() as unknown as HrApi)
+    : createHrClient({
+        baseUrl: getHost().apiBaseUrl,
+      })
+  return cached
+}
+
+/** Test seam. */
+export function __setHrApi(api: HrApi | null) {
+  cached = api
+}

package/src/client/components/ClockControls.svelte

@@ -0,0 +1,127 @@
+<script lang="ts">
+import { Button, Skeleton } from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { formatDuration, hrKeys } from '../query.js'
+
+/**
+ * Clock in, out and break — the whole of attendance for most people.
+ *
+ * Only the transitions that are currently legal are offered, because the server refuses the others
+ * anyway and a button that always errors is worse than no button. Clocked out: one action. Clocked
+ * in: clock out, and start a break. On a break: end it.
+ */
+interface Props {
+  workspaceId: string
+}
+const { workspaceId }: Props = $props()
+
+const api = getHrApi()
+const queryClient = useQueryClient()
+
+const stateQuery = createQuery(() => ({
+  queryKey: hrKeys.clockState(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.attendance.state({ workspaceId }),
+  // The elapsed total is computed server-side from an open span, so it goes stale on its own.
+  refetchInterval: 60_000,
+}))
+const state = $derived(stateQuery.data)
+
+const words = {
+  hours: (n: string) => t('hours_short', { n }),
+  minutes: (n: string) => t('minutes_short', { n }),
+}
+
+const act = createMutation(() => ({
+  mutationFn: async (action: 'in' | 'out' | 'break_start' | 'break_end') => {
+    if (action === 'in') return api.attendance.clockIn({ workspaceId })
+    if (action === 'out') return api.attendance.clockOut({ workspaceId })
+    if (action === 'break_start') return api.attendance.breakStart({ workspaceId })
+    return api.attendance.breakEnd({ workspaceId })
+  },
+  onSuccess: () => {
+    // A punch changes the day sheet as well as the clock, and both are on screen.
+    void queryClient.invalidateQueries({ queryKey: ['hr'] })
+  },
+}))
+
+const since = $derived(
+  state?.since
+    ? new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit' }).format(new Date(state.since))
+    : null,
+)
+</script>
+
+{#if stateQuery.isLoading}
+  <Skeleton height="72px" />
+{:else if state}
+  <div class="clock">
+    <div class="status">
+      <span class="line">
+        {#if state.onBreak && since}
+          {t('on_break_since', { time: since })}
+        {:else if state.clockedIn && since}
+          {t('clocked_in_since', { time: since })}
+        {:else}
+          {t('not_clocked_in')}
+        {/if}
+      </span>
+      <span class="total">
+        {t('worked_today')}: {formatDuration(state.workedMinutesToday, words)}
+      </span>
+    </div>
+
+    <div class="actions">
+      {#if !state.clockedIn}
+        <Button size="sm" disabled={act.isPending} onclick={() => act.mutate('in')}>
+          {t('clock_in')}
+        </Button>
+      {:else}
+        {#if state.onBreak}
+          <Button size="sm" variant="secondary" disabled={act.isPending} onclick={() => act.mutate('break_end')}>
+            {t('break_end')}
+          </Button>
+        {:else}
+          <Button size="sm" variant="secondary" disabled={act.isPending} onclick={() => act.mutate('break_start')}>
+            {t('break_start')}
+          </Button>
+        {/if}
+        <Button size="sm" disabled={act.isPending} onclick={() => act.mutate('out')}>
+          {t('clock_out')}
+        </Button>
+      {/if}
+    </div>
+  </div>
+{/if}
+
+<style>
+.clock {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+  padding: 12px;
+  border: 1px solid var(--kern-border);
+  border-radius: var(--kern-r-md);
+  background: var(--kern-surface);
+}
+.status {
+  display: flex;
+  flex-direction: column;
+}
+.line {
+  font-weight: 500;
+}
+.total {
+  color: var(--kern-ink-500);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+.actions {
+  display: flex;
+  gap: 8px;
+}
+</style>

package/src/client/components/HrSidebar.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+import { coreApi, keys, SidebarGroup, SidebarItem, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import type { CoreApi } from '../core-api.js'
+import { t } from '../i18n.js'
+import { HR_CAPABILITIES } from '../permissions.js'
+
+/**
+ * HR's own column.
+ *
+ * The rail switches modules and the sidebar holds the one you are in, so the module fills the whole
+ * column rather than reaching into a shell that happens to leave a gap.
+ *
+ * Rows are filtered on the workspace's capabilities — a company that never switched attendance on
+ * has no attendance row, the same way it has no attendance route and no attendance API. Read
+ * through the same `capabilitiesOf` the shell uses, on the same query key, so this shares the
+ * layout's cached result rather than fetching it again.
+ */
+interface Props {
+  workspaceId: string
+  workspaceSlug: string
+  pathname: string
+}
+const { workspaceId, workspaceSlug, pathname }: Props = $props()
+
+const api = coreApi<CoreApi>()
+
+const modulesQuery = createQuery(() => ({
+  queryKey: keys.modules(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.workspaces.modules.list({ workspaceId }),
+}))
+
+const capabilities = $derived(session.capabilities)
+const has = (id: string) => capabilities.has(`hr.${id}`)
+
+const href = (path: string) => `/${workspaceSlug}${path}`
+const active = (path: string) => pathname === `/${workspaceSlug}${path}`
+</script>
+
+<SidebarGroup>
+  <SidebarItem href={href('/hr')} icon="users" active={active('/hr')} label={t('title')} />
+  {#if has(HR_CAPABILITIES.leave)}
+    <SidebarItem
+      href={href('/hr/leave')}
+      icon="tree-palm"
+      active={active('/hr/leave')}
+      label={t('leave_title')}
+    />
+  {/if}
+  {#if has(HR_CAPABILITIES.attendance)}
+    <SidebarItem
+      href={href('/hr/attendance')}
+      icon="timer"
+      active={active('/hr/attendance')}
+      label={t('attendance_title')}
+    />
+  {/if}
+  <SidebarItem
+    href={href('/hr/approvals')}
+    icon="check-check"
+    active={active('/hr/approvals')}
+    label={t('approvals_title')}
+  />
+  {#if has(HR_CAPABILITIES.offices)}
+    <SidebarItem
+      href={href('/hr/offices')}
+      icon="building"
+      active={active('/hr/offices')}
+      label={t('offices_title')}
+    />
+  {/if}
+</SidebarGroup>

package/src/client/components/LeaveRequestDialog.svelte

@@ -0,0 +1,169 @@
+<script lang="ts">
+import { Button, Dialog, Field, Input, navigation, Select, Textarea, toast } from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { canHr } from '../permissions.js'
+import { formatDays, hrKeys, isoDate } from '../query.js'
+
+/**
+ * Book time off.
+ *
+ * The Request time off button already went to `?new=1`. This is the form that URL was promising:
+ * pick a type and a range, see what it would cost, then submit. Simulation runs before create so a
+ * blocked request is refused here rather than after the click.
+ */
+interface Props {
+  open: boolean
+  workspaceId: string
+  workspaceSlug: string
+}
+
+let { open, workspaceId, workspaceSlug }: Props = $props()
+
+const api = getHrApi()
+const queryClient = useQueryClient()
+
+let shown = $state(false)
+$effect(() => {
+  if (open) shown = true
+})
+
+let leaveTypeId = $state('')
+let startsOn = $state(isoDate())
+let endsOn = $state(isoDate())
+let reason = $state('')
+
+const typesQuery = createQuery(() => ({
+  queryKey: hrKeys.leaveTypes(workspaceId),
+  enabled: Boolean(workspaceId) && open,
+  queryFn: () => api.leave.types.list({ workspaceId, includeArchived: false }),
+}))
+const types = $derived(typesQuery.data ?? [])
+const typeOptions = $derived(types.map((type) => ({ value: type.id, label: type.name })))
+
+$effect(() => {
+  if (open && !leaveTypeId && types[0]) leaveTypeId = types[0].id
+})
+
+const simQuery = createQuery(() => ({
+  queryKey: ['hr', 'leave-sim', workspaceId, leaveTypeId, startsOn, endsOn] as const,
+  enabled: Boolean(workspaceId && leaveTypeId && startsOn && endsOn && open),
+  queryFn: () =>
+    api.leave.requests.simulate({
+      workspaceId,
+      leaveTypeId,
+      startsOn,
+      endsOn,
+    }),
+}))
+const sim = $derived(simQuery.data)
+const blocked = $derived((sim?.blockers.length ?? 0) > 0)
+
+const close = () => {
+  shown = false
+  void navigation.go(`/${workspaceSlug}/hr/leave`, { replaceState: true, keepFocus: true, noScroll: true })
+}
+
+const create = createMutation(() => ({
+  mutationFn: () =>
+    api.leave.requests.create({
+      workspaceId,
+      leaveTypeId,
+      startsOn,
+      endsOn,
+      reason: reason.trim() || null,
+      idempotencyKey: crypto.randomUUID(),
+    }),
+  onSuccess: () => {
+    toast.success(t('leave_submitted'))
+    void queryClient.invalidateQueries({ queryKey: ['hr', 'leave-balance'] })
+    void queryClient.invalidateQueries({ queryKey: ['hr', 'leave-requests'] })
+    void queryClient.invalidateQueries({ queryKey: ['hr', 'leave-calendar'] })
+    reason = ''
+    close()
+  },
+  onError: (error: Error) => toast.error(error.message),
+}))
+
+const canSubmit = $derived(
+  Boolean(leaveTypeId && startsOn && endsOn) && !blocked && canHr('leaveRequest') && !simQuery.isFetching,
+)
+</script>
+
+<Dialog
+  bind:open={shown}
+  title={t('request_leave')}
+  onOpenChange={(next) => {
+    if (!next) close()
+  }}
+>
+  <div class="form">
+    <Field label={t('leave_type')} id="hr-leave-type" required>
+      {#snippet children(id)}
+        <Select {id} bind:value={leaveTypeId} options={typeOptions} />
+      {/snippet}
+    </Field>
+    <div class="dates">
+      <Field label={t('leave_from')} id="hr-leave-from" required>
+        {#snippet children(id)}
+          <Input {id} type="date" bind:value={startsOn} />
+        {/snippet}
+      </Field>
+      <Field label={t('leave_to')} id="hr-leave-to" required>
+        {#snippet children(id)}
+          <Input {id} type="date" bind:value={endsOn} />
+        {/snippet}
+      </Field>
+    </div>
+    <Field label={t('leave_reason')} id="hr-leave-reason" hint={t('common.optional')}>
+      {#snippet children(id)}
+        <Textarea {id} bind:value={reason} rows={3} />
+      {/snippet}
+    </Field>
+
+    {#if sim}
+      {#if blocked}
+        <p class="block" role="alert">
+          {t('leave_blocked')}
+          {sim.blockers[0]?.message ?? ''}
+        </p>
+      {:else}
+        <p class="cost">
+          {t('leave_would_cost', { days: formatDays(sim.workingDays) })}
+          ·
+          {t('leave_after', { days: formatDays(sim.balanceAfterMinutes / 480) })}
+        </p>
+      {/if}
+    {/if}
+  </div>
+
+  {#snippet footer()}
+    <Button variant="ghost" onclick={close}>{t('common.cancel')}</Button>
+    <Button onclick={() => create.mutate()} disabled={!canSubmit} loading={create.isPending}>
+      {t('request_leave')}
+    </Button>
+  {/snippet}
+</Dialog>
+
+<style>
+.form {
+  display: grid;
+  gap: 14px;
+}
+.dates {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+}
+.cost {
+  margin: 0;
+  font-size: 13px;
+  color: var(--kern-ink-500);
+}
+.block {
+  margin: 0;
+  font-size: 13px;
+  color: var(--kern-danger);
+}
+</style>

package/src/client/components/PersonFormDialog.svelte

@@ -0,0 +1,184 @@
+<script lang="ts">
+import { Button, Dialog, Field, Input, navigation, Select, toast } from '@kernhq/ui'
+import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { canHr } from '../permissions.js'
+import { isoDate } from '../query.js'
+
+/**
+ * Hire someone into the directory.
+ *
+ * The Add person button already went to `?new=1`; this is the screen that URL was promising.
+ * Office is optional: a workspace that never switched offices on still has a default one, and the
+ * server assigns it. Asking for an office on that workspace would offer a feature it does not have.
+ */
+interface OfficeOpt {
+  id: string
+  name: string
+}
+
+interface Props {
+  open: boolean
+  workspaceId: string
+  workspaceSlug: string
+  offices: OfficeOpt[]
+  showOffice: boolean
+}
+
+let { open, workspaceId, workspaceSlug, offices, showOffice }: Props = $props()
+
+const api = getHrApi()
+const queryClient = useQueryClient()
+
+/** Local so the dialog can close before the URL has dropped `?new=1`. */
+let shown = $state(false)
+/** Set when create succeeded, so closing the dialog does not wipe the person we just opened. */
+let createdId = $state<string | null>(null)
+$effect(() => {
+  if (open) {
+    shown = true
+    createdId = null
+  }
+})
+
+let displayName = $state('')
+let workEmail = $state('')
+let employeeNo = $state('')
+let hiredOn = $state(isoDate())
+let officeId = $state('')
+let employmentType = $state('full_time')
+
+const typeOptions = [
+  { value: 'full_time', label: t('employment_full_time') },
+  { value: 'part_time', label: t('employment_part_time') },
+  { value: 'contract', label: t('employment_contract') },
+  { value: 'intern', label: t('employment_intern') },
+  { value: 'temporary', label: t('employment_temporary') },
+  { value: 'freelance', label: t('employment_freelance') },
+]
+
+const officeOptions = $derived(offices.map((o) => ({ value: o.id, label: o.name })))
+
+$effect(() => {
+  if (open && !officeId && offices[0]) officeId = offices[0].id
+})
+
+const dismiss = () => {
+  if (createdId) {
+    void navigation.go(`/${workspaceSlug}/hr?person=${createdId}`, {
+      replaceState: true,
+      keepFocus: true,
+      noScroll: true,
+    })
+    return
+  }
+  void navigation.go(`/${workspaceSlug}/hr`, { replaceState: true, keepFocus: true, noScroll: true })
+}
+
+const reset = () => {
+  displayName = ''
+  workEmail = ''
+  employeeNo = ''
+  hiredOn = isoDate()
+  officeId = offices[0]?.id ?? ''
+  employmentType = 'full_time'
+}
+
+const create = createMutation(() => ({
+  mutationFn: () =>
+    api.people.create({
+      workspaceId,
+      displayName: displayName.trim(),
+      workEmail: workEmail.trim() || null,
+      employeeNo: employeeNo.trim() || null,
+      hiredOn: hiredOn || null,
+      officeId: showOffice && officeId ? officeId : null,
+      employmentType: employmentType as
+        | 'full_time'
+        | 'part_time'
+        | 'contract'
+        | 'intern'
+        | 'temporary'
+        | 'freelance',
+    }),
+  onSuccess: (person) => {
+    createdId = person.id
+    toast.success(t('person_created', { name: person.displayName }))
+    void queryClient.invalidateQueries({ queryKey: ['hr', 'people'] })
+    reset()
+    shown = false
+    dismiss()
+  },
+  onError: (error: Error) => toast.error(error.message),
+}))
+
+const canSubmit = $derived(displayName.trim().length > 0 && canHr('personManage'))
+</script>
+
+<Dialog
+  bind:open={shown}
+  title={t('add_person')}
+  description={t('add_person_desc')}
+  onOpenChange={(next) => {
+    if (!next) {
+      shown = false
+      dismiss()
+    }
+  }}
+>
+  <div class="form">
+    <Field label={t('display_name')} id="hr-person-name" required>
+      {#snippet children(id)}
+        <Input {id} bind:value={displayName} autocomplete="name" />
+      {/snippet}
+    </Field>
+    <Field label={t('work_email')} id="hr-person-email" hint={t('common.optional')}>
+      {#snippet children(id)}
+        <Input {id} type="email" bind:value={workEmail} autocomplete="email" />
+      {/snippet}
+    </Field>
+    <Field label={t('employee_no')} id="hr-person-no" hint={t('common.optional')}>
+      {#snippet children(id)}
+        <Input {id} bind:value={employeeNo} />
+      {/snippet}
+    </Field>
+    <Field label={t('hired_on')} id="hr-person-hired">
+      {#snippet children(id)}
+        <Input {id} type="date" bind:value={hiredOn} />
+      {/snippet}
+    </Field>
+    {#if showOffice && officeOptions.length}
+      <Field label={t('office')} id="hr-person-office">
+        {#snippet children(id)}
+          <Select {id} bind:value={officeId} options={officeOptions} />
+        {/snippet}
+      </Field>
+    {/if}
+    <Field label={t('employment')} id="hr-person-type">
+      {#snippet children(id)}
+        <Select {id} bind:value={employmentType} options={typeOptions} />
+      {/snippet}
+    </Field>
+  </div>
+
+  {#snippet footer()}
+    <Button
+      variant="ghost"
+      onclick={() => {
+        shown = false
+        dismiss()
+      }}>{t('common.cancel')}</Button
+    >
+    <Button onclick={() => create.mutate()} disabled={!canSubmit} loading={create.isPending}>
+      {t('add_person')}
+    </Button>
+  {/snippet}
+</Dialog>
+
+<style>
+.form {
+  display: grid;
+  gap: 14px;
+}
+</style>

package/src/client/components/PersonInline.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+import { Avatar } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getHrApi } from '../api-instance.js'
+import { hrKeys } from '../query.js'
+
+/**
+ * A person, rendered wherever another module mentions one — a chat message, an issue's assignee.
+ *
+ * This is what `objectTypes: [{ type: 'person' }]` on the server buys: HR owns how a person looks,
+ * so every module shows the same name and avatar without importing anything of HR's.
+ */
+interface Props {
+  id: string
+  workspaceId: string
+}
+const { id, workspaceId }: Props = $props()
+
+const api = getHrApi()
+
+const personQuery = createQuery(() => ({
+  queryKey: hrKeys.person(workspaceId, id),
+  enabled: Boolean(workspaceId && id),
+  queryFn: () => api.people.get({ workspaceId, personId: id }),
+}))
+const person = $derived(personQuery.data)
+</script>
+
+<span class="inline">
+  {#if person}
+    <Avatar name={person.displayName} id={person.id} size={18} />
+    <span>{person.displayName}</span>
+  {:else}
+    <!-- No skeleton: an inline mention that pulses inside a sentence is worse than a plain name. -->
+    <span class="pending">…</span>
+  {/if}
+</span>
+
+<style>
+.inline {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  vertical-align: baseline;
+}
+.pending {
+  color: var(--kern-ink-500);
+}
+</style>