@kernhq/module-hr 0.10.0 → 0.10.2

package/src/client/summary.ts

@@ -1,3 +1,4 @@
+import { formatDate, formatDateRange } from '@kernhq/ui'
 import type { ApprovalRequest } from '../contract/index.js'
 import { t } from './i18n.js'
 
@@ -16,7 +17,9 @@ export function summarise(request: ApprovalRequest): string {
   if (!p) return request.summary
   if (request.subjectType === 'leave' && p.from && p.to)
     return t('approval_summary_leave', {
-      days: String(p.days ?? ''),
+      // A number, not a string: `count` is what selects the plural form, and passing it as text
+      // rendered "1 days" and left the digits Latin on a Persian screen. `t()` formats it.
+      count: Number(p.days ?? 0),
       range: dateRange(String(p.from), String(p.to)),
     })
   if (request.subjectType === 'regularization' && p.date)
@@ -26,11 +29,15 @@ export function summarise(request: ApprovalRequest): string {
   return request.summary
 }
 
-export const day = (iso: string) =>
-  new Intl.DateTimeFormat(undefined, { dateStyle: 'medium' }).format(new Date(iso))
+/**
+ * `formatDate`, not a bare `Intl.DateTimeFormat(undefined, …)`.
+ *
+ * `undefined` means the browser's locale, which is not the one the reader chose — so the date half
+ * of a sentence came out in Latin digits while `t()` rendered the word half in Persian ones, in the
+ * same line. The shared helper passes `messageLocale()`, and it is the same call underneath.
+ * This matters wherever it is used, and `summarise()` is what all three approvals surfaces render.
+ */
+export const day = (iso: string) => formatDate(iso)
 
 /** One range, not two dates and a dash — the separator is the locale's, and RTL needs its own. */
-export const dateRange = (from: string, to: string) =>
-  from === to
-    ? day(from)
-    : new Intl.DateTimeFormat(undefined, { dateStyle: 'medium' }).formatRange(new Date(from), new Date(to))
+export const dateRange = (from: string, to: string) => (from === to ? day(from) : formatDateRange(from, to))

package/src/client/widgets/ApprovalsWidget.svelte

@@ -2,8 +2,11 @@
 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 DecisionDialog from '../components/DecisionDialog.svelte'
 import { t } from '../i18n.js'
+import type { ApprovalRequest } from '../index.js'
 import { hrKeys } from '../query.js'
+import { summarise } from '../summary.js'
 
 /**
  * Requests waiting on me, decidable from the card.
@@ -23,45 +26,141 @@ const inboxQuery = createQuery(() => ({
 }))
 const items = $derived(inboxQuery.data?.items ?? [])
 
+let asked = $state<{ request: ApprovalRequest; decision: 'approve' | 'reject' } | null>(null)
+let decideError = $state<string | null>(null)
+
+/**
+ * `deciding` rather than `decide.isPending`: the disabled attribute only reaches the button on the
+ * next render, so two quick clicks both fire and the same request is decided twice. This is set in
+ * the same tick as the first click.
+ */
+let deciding = $state(false)
+
 const decide = createMutation(() => ({
-  mutationFn: (vars: { requestId: string; decision: 'approve' | 'reject' }) =>
-    api.approvals.decide({ workspaceId, ...vars }),
-  onSuccess: () => void queryClient.invalidateQueries({ queryKey: ['hr'] }),
+  mutationFn: (vars: { requestId: string; decision: 'approve' | 'reject'; comment: string }) =>
+    api.approvals.decide({
+      workspaceId,
+      requestId: vars.requestId,
+      decision: vars.decision,
+      comment: vars.comment.trim() || null,
+    }),
+  onSuccess: () => {
+    asked = null
+    decideError = null
+    void queryClient.invalidateQueries({ queryKey: ['hr'] })
+  },
+  onError: (error) => {
+    decideError = decideFailure(error)
+    // A refusal means the server's inbox is not the one on screen, so the row that was just clicked
+    // is stale as well as the decision. Re-read all of HR exactly as a decision that landed does —
+    // without this, a request somebody else already approved sits on the card for ever and every
+    // retry earns the same sentence.
+    void queryClient.invalidateQueries({ queryKey: ['hr'] })
+  },
+  onSettled: () => {
+    deciding = false
+  },
 }))
+
+/**
+ * The decision refusals this module has its own sentence for, keyed by the `reason` the router
+ * sends beside the refusal. Empty because `approvals.decide` refuses through `KernError.conflict`,
+ * whose reason argument stays on the server — see `ApprovalsPage.svelte`, which carries the whole
+ * note and the same shape.
+ */
+const decideRefusalMessages: Record<string, string> = {}
+
+/**
+ * What a refused decision says to the person who made it.
+ *
+ * The commonest failure here is that the request is no longer yours to decide — somebody else
+ * approved it, the person cancelled it, or a delegation moved the step — and the router refuses
+ * that with a sentence it wrote for a reader. That sentence is the only thing that says which of
+ * those happened, so it is repeated verbatim. Everything else that can fail carries machine text in
+ * English, so it falls back to this module's own string. The test is the transport's `code`, never
+ * the sentence.
+ */
+function decideFailure(error: unknown): string {
+  const failure = error as { code?: unknown; message?: string; data?: { reason?: unknown } }
+  if (failure.code !== 'CONFLICT') return t('decide_error')
+  const reason = typeof failure.data?.reason === 'string' ? failure.data.reason : null
+  const key = reason ? decideRefusalMessages[reason] : undefined
+  const translated = key ? t(key) : undefined
+  return (translated && translated !== key ? translated : failure.message) || t('decide_error')
+}
+
+const ask = (request: ApprovalRequest, decision: 'approve' | 'reject') => {
+  decideError = null
+  asked = { request, decision }
+}
+
+const confirmDecision = (comment: string) => {
+  if (!asked || deciding) return
+  deciding = true
+  decide.mutate({ requestId: asked.request.id, decision: asked.decision, comment })
+}
 </script>
 
+<!--
+  Held rows outrank the error. `invalidateQueries({ queryKey: ['hr'] })` fires on every punch and
+  every decision anywhere in the module, so a failed background refetch leaves TanStack in `error`
+  while `data` is still the last good inbox — an error branch above this one would blank a working
+  card, and take its approve buttons with it, on a transient failure. The error is only the whole
+  card when there is nothing else to draw.
+-->
 {#if inboxQuery.isLoading}
   <Skeleton height="96px" />
-{:else if items.length === 0}
-  <EmptyState bare compact icon="check-check" title={t('approvals_none')} />
-{:else}
+{:else if items.length > 0}
   <ul>
     {#each items as item (item.id)}
       <li>
-        <span class="summary">{item.summary}</span>
+        <span class="summary">{summarise(item)}</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
-          >
+          <!--
+            Never straight to `decide.mutate`: rejecting somebody's leave is irreversible from the
+            interface and notifies them, and a dashboard card is the easiest place in the product to
+            hit the wrong button. The dialog says what the decision does and to whom.
+          -->
+          <Button size="sm" variant="ghost" onclick={() => ask(item, 'reject')}>{t('reject')}</Button>
+          <Button size="sm" onclick={() => ask(item, 'approve')}>{t('approve')}</Button>
         {/if}
       </li>
     {/each}
   </ul>
+{:else if inboxQuery.isError}
+  <!--
+    One row, not an `EmptyState`. This card's smallest declared size is `s`, whose body is 43px —
+    one grid row of 84px, less the frame's 41px header — and a compact `EmptyState` is 82px before
+    it is given an action, so its retry button sat below a fold nobody scrolls in a card this size.
+    Here the row lands where the first request would have been.
+
+    Without this branch the empty state below claimed "Nothing waiting on you" to a manager whose
+    inbox had simply failed to load, which is the one sentence on this card nobody would check.
+  -->
+  <div class="failed" role="alert">
+    <span class="msg">{t('approvals_error')}</span>
+    <Button size="xs" variant="ghost" onclick={() => void inboxQuery.refetch()}>{t('retry')}</Button>
+  </div>
+{:else}
+  <EmptyState bare compact icon="check-check" title={t('approvals_none')} />
 {/if}
 
+<!-- Portalled, so it is a dialog over the dashboard rather than something inside an 84px card. -->
+<DecisionDialog
+  request={asked?.request ?? null}
+  decision={asked?.decision ?? 'approve'}
+  pending={deciding}
+  error={decideError}
+  onConfirm={confirmDecision}
+  onCancel={() => {
+    asked = null
+    decideError = null
+  }}
+/>
+
 <style>
 ul {
   display: grid;
@@ -83,4 +182,18 @@ li {
   white-space: nowrap;
   font-size: 12px;
 }
+.failed {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding-block: 8px;
+  padding-inline: 14px;
+}
+/* Muted with a colour, never opacity: 9.86:1 on the card in light, 8.96:1 in dark. */
+.msg {
+  min-width: 0;
+  font-size: 12.5px;
+  color: var(--kern-ink-600);
+}
 </style>

package/src/client/widgets/HeadcountWidget.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-import { Skeleton, StatTile, type WidgetProps } from '@kernhq/ui'
+import { Button, formatCount, Skeleton, StatTile, type WidgetProps } from '@kernhq/ui'
 import { createQuery } from '@tanstack/svelte-query'
 import { getHrApi } from '../api-instance.js'
 import { t } from '../i18n.js'
@@ -14,16 +14,82 @@ const peopleQuery = createQuery(() => ({
   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)
+/**
+ * `total` rather than `items.length`: the request asks for one row, because drawing a number does
+ * not need the list behind it.
+ *
+ * No `?? 0`. A tile reading "0 people" is a claim about the company, and it was the claim this card
+ * made every time the fetch failed — indistinguishable from a workspace nobody has been added to.
+ * `undefined` is what says "not known", and the branches below are ordered on it.
+ */
+const total = $derived(peopleQuery.data?.total)
+/**
+ * `formatCount`'s default caps at "99+", which is right for a badge on a nav row and wrong for a
+ * headcount — a four-hundred-person company would read "99+". The cap is lifted rather than the
+ * locale dropped: a bare `Intl.NumberFormat()` follows the browser's language, so a Persian
+ * interface would be the one screen printing Latin digits.
+ */
+const people = $derived(total === undefined ? '' : formatCount(total, Number.MAX_SAFE_INTEGER))
 </script>
 
+<!--
+  The held number outranks the error, as everywhere else in this module:
+  `invalidateQueries({ queryKey: ['hr'] })` fires on every punch and every approval decision, so a
+  failed background refetch leaves TanStack in `error` while `data` is still the last good count.
+  Blanking a card that has a number, because the poll behind it missed once, is the louder bug.
+-->
 {#if peopleQuery.isLoading}
   <Skeleton height="72px" />
+{:else if total !== undefined}
+  <StatTile label={t('widget_headcount_title')} value={people} />
+{:else if peopleQuery.isError}
+  <!--
+    The label stays and the number does not. This widget is `compact`, so the frame draws no header
+    and the tile's own label is the only thing naming the card — drop it and the board grows an
+    anonymous box. The reason takes the number's place, in the same footprint the tile occupied, so
+    nothing around it moves.
+  -->
+  <div class="failed" role="alert">
+    <div class="text">
+      <span class="label">{t('widget_headcount_title')}</span>
+      <span class="msg">{t('people_error')}</span>
+    </div>
+    <Button size="xs" variant="ghost" onclick={() => void peopleQuery.refetch()}>{t('retry')}</Button>
+  </div>
 {:else}
-  <StatTile
-    label={t('widget_headcount_title')}
-    value={new Intl.NumberFormat().format(count)}
-  />
+  <!--
+    No workspace yet. The query is disabled until one arrives, and a disabled query is not
+    "loading" — so without this branch the card is simply absent for that first frame.
+  -->
+  <Skeleton height="72px" />
 {/if}
+
+<style>
+/* The tile's own frame, so a card that fails keeps the shape it had a moment ago. */
+.failed {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding-block: 14px;
+  padding-inline: 16px;
+  border: 1px solid var(--kern-border);
+  border-radius: var(--kern-r-2xl);
+  background: var(--kern-surface-raised);
+}
+.text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.label {
+  font-size: 12px;
+  color: var(--kern-ink-450);
+}
+/* Muted with a colour, never opacity: 9.86:1 on the tile in light, 8.96:1 in dark. */
+.msg {
+  font-size: 12.5px;
+  color: var(--kern-ink-600);
+}
+</style>

package/src/client/widgets/LeaveBalanceWidget.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-import { EmptyState, Skeleton, type WidgetProps } from '@kernhq/ui'
+import { Button, EmptyState, Skeleton, type WidgetProps } from '@kernhq/ui'
 import { createQuery } from '@tanstack/svelte-query'
 import { getHrApi } from '../api-instance.js'
 import { t } from '../i18n.js'
@@ -22,19 +22,40 @@ const balanceQuery = createQuery(() => ({
 const balances = $derived(balanceQuery.data ?? [])
 </script>
 
+<!--
+  Held balances outrank the error. `invalidateQueries({ queryKey: ['hr'] })` fires on every punch and
+  every approval decision anywhere in the module, so a failed background refetch leaves TanStack in
+  `error` while `data` is still the last good set of balances — an error branch above this one would
+  blank a working card on a transient failure. The error is only the whole card when there is
+  nothing else to draw.
+-->
 {#if balanceQuery.isLoading}
   <Skeleton height="72px" />
-{:else if balances.length === 0}
-  <EmptyState bare compact icon="tree-palm" title={t('leave_none')} />
-{:else}
+{:else if balances.length > 0}
   <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>
+        <span class="value">{formatDays(b.available)} <span class="unit">{t('days', { count: b.available })}</span></span>
       </li>
     {/each}
   </ul>
+{:else if balanceQuery.isError}
+  <!--
+    One row, not an `EmptyState`. This card's smallest declared size is `s`, whose body is 43px —
+    one grid row of 84px, less the frame's 41px header — and a compact `EmptyState` is 82px before
+    it is given an action, so its retry button sat below a fold nobody scrolls in a card this size.
+
+    Without this branch the empty state below said "No time off booked", which on a card headed "My
+    time off" reads as a balance of nothing — the answer somebody plans a year around, given for a
+    request that never arrived.
+  -->
+  <div class="failed" role="alert">
+    <span class="msg">{t('balance_error')}</span>
+    <Button size="xs" variant="ghost" onclick={() => void balanceQuery.refetch()}>{t('retry')}</Button>
+  </div>
+{:else}
+  <EmptyState bare compact icon="tree-palm" title={t('leave_none')} />
 {/if}
 
 <style>
@@ -64,4 +85,18 @@ li {
   font-size: 12px;
   color: var(--kern-ink-500);
 }
+.failed {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding-block: 8px;
+  padding-inline: 14px;
+}
+/* Muted with a colour, never opacity: 9.86:1 on the card in light, 8.96:1 in dark. */
+.msg {
+  min-width: 0;
+  font-size: 12.5px;
+  color: var(--kern-ink-600);
+}
 </style>

package/src/client/widgets/WhosOutWidget.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-import { Avatar, EmptyState, Skeleton, type WidgetProps } from '@kernhq/ui'
+import { Avatar, Button, EmptyState, formatDateRange, Skeleton, type WidgetProps } from '@kernhq/ui'
 import { createQuery } from '@tanstack/svelte-query'
 import { getHrApi } from '../api-instance.js'
 import { t } from '../i18n.js'
@@ -25,18 +25,26 @@ const outQuery = createQuery(() => ({
 }))
 const away = $derived(outQuery.data ?? [])
 
+/**
+ * `formatDateRange` rather than `Intl` here: it formats in the reader's *interface* language, which
+ * `undefined` does not — that is the browser's language, so a Persian interface printed "6 Aug".
+ * `T00:00:00` stays on both ends: a bare `YYYY-MM-DD` is parsed as UTC midnight, which prints the
+ * day before west of Greenwich.
+ */
 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`),
-  )
+  formatDateRange(`${a}T00:00:00`, `${b}T00:00:00`, { day: 'numeric', month: 'short' })
 </script>
 
+<!--
+  Held rows outrank the error. `invalidateQueries({ queryKey: ['hr'] })` fires on every punch and
+  every approval decision anywhere in the module, so a failed background refetch leaves TanStack in
+  `error` while `data` is still the last good calendar — an error branch above this one would blank
+  a working card on a transient failure. The error is only the whole card when there is nothing
+  else to draw.
+-->
 {#if outQuery.isLoading}
   <Skeleton height="96px" />
-{:else if away.length === 0}
-  <EmptyState bare compact icon="calendar-days" title={t('leave_none')} />
-{:else}
+{:else if away.length > 0}
   <ul>
     {#each away as person (person.requestId)}
       <li>
@@ -46,6 +54,23 @@ const range = (a: string, b: string) =>
       </li>
     {/each}
   </ul>
+{:else if outQuery.isError}
+  <!--
+    One row, not an `EmptyState`, for the same reason as the rest of this module's cards: a compact
+    `EmptyState` is 82px before it is given an action, which is twice the 43px body a widget has at
+    size `s`. This card starts at `m` and has the room, but a person reading two failed HR cards
+    side by side should not be shown two different shapes of failure.
+
+    Without this branch the empty state below said "No time off booked" — read on a card headed
+    "Who's out" as *nobody is away*, which is the precise opposite of what is actually unknown, and
+    the one answer somebody schedules a week of work around.
+  -->
+  <div class="failed" role="alert">
+    <span class="msg">{t('whos_out_error')}</span>
+    <Button size="xs" variant="ghost" onclick={() => void outQuery.refetch()}>{t('retry')}</Button>
+  </div>
+{:else}
+  <EmptyState bare compact icon="calendar-days" title={t('leave_none')} />
 {/if}
 
 <style>
@@ -72,4 +97,18 @@ li {
   color: var(--kern-ink-500);
   font-size: 12px;
 }
+.failed {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding-block: 8px;
+  padding-inline: 14px;
+}
+/* Muted with a colour, never opacity: 9.86:1 on the card in light, 8.96:1 in dark. */
+.msg {
+  min-width: 0;
+  font-size: 12.5px;
+  color: var(--kern-ink-600);
+}
 </style>

package/src/contract/attendance.ts

@@ -89,6 +89,15 @@ export const AttendanceDay = z.object({
   workedMinutes: z.number().int(),
   breakMinutes: z.number().int(),
   overtimeMinutes: z.number().int(),
+  /**
+   * Overtime the policy's annual cap will not take — null where no cap was in force.
+   *
+   * Declared here or it does not exist: oRPC validates a procedure's output against this schema and
+   * zod strips what the schema does not name, so the column was written, stored, and then dropped
+   * on the way out. Null and zero mean different things and a compliance report has to tell them
+   * apart — null is "no ceiling applied to this day", zero is "one applied and nothing exceeded it".
+   */
+  beyondCapMinutes: z.number().int().nullable(),
   lateMinutes: z.number().int(),
   earlyLeaveMinutes: z.number().int(),
   status: AttendanceStatus,

package/src/contract/capabilities.ts

@@ -132,6 +132,23 @@ export const hrCapabilities = defineCapabilities([
 
 export type HrCapabilityId = (typeof hrCapabilities)[number]['id']
 
+/**
+ * The message ids a screen reads a capability's `label` and `description` through.
+ *
+ * `CapabilityDef.label` is documented as "an i18n message id or an English fallback", and putting
+ * the id *in* the field would leave the fallback nowhere: core's module admin and the shell's mock
+ * read this manifest raw, with no HR bundle merged, so they would print `hr.cap_leave` at a person.
+ * So the literals above stay the fallback and the id is derived from the capability's own id — a
+ * capability added to the list becomes translatable the moment somebody writes its two strings, and
+ * nothing that parses this list sees a new field.
+ *
+ * The `hr.` prefix is written out rather than left to `scopedT`, because a caller has to be able to
+ * tell a resolved string from a key that resolved to itself, and `t()` answers a miss with the
+ * *namespaced* key.
+ */
+export const capabilityLabelKey = (id: string) => `hr.cap_${id}`
+export const capabilityDescriptionKey = (id: string) => `hr.cap_${id}_desc`
+
 /**
  * Which procedures sit behind which capability.
  *