@kernhq/module-hr 0.10.0 → 0.10.2

package/migrations/meta/_journal.json

@@ -43,6 +43,27 @@
       "when": 1787761769496,
       "tag": "0005_approval_requester",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1787848169496,
+      "tag": "0006_schedule_no_overlap",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1787848170496,
+      "tag": "0007_hot_path_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1787759372069,
+      "tag": "0009_beyond_cap_minutes",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-hr",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Kern HR module: people, offices, org chart, calendars",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -43,10 +43,10 @@
   "devDependencies": {
     "@biomejs/biome": "^2.0.0",
     "@changesets/cli": "^2.27.0",
-    "@kernhq/contracts": "^0.5.1",
+    "@kernhq/contracts": "^0.6.0",
     "@kernhq/kernel": "^0.7.0",
     "@kernhq/tsconfig": "^0.1.0",
-    "@kernhq/ui": "^0.8.0",
+    "@kernhq/ui": "^0.10.0",
     "@tanstack/svelte-query": "^6.1.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.15.0",
@@ -58,9 +58,9 @@
     "vitest": "^4.0.0"
   },
   "peerDependencies": {
-    "@kernhq/contracts": "^0.5.1",
+    "@kernhq/contracts": "^0.6.0",
     "@kernhq/kernel": "^0.7.0",
-    "@kernhq/ui": "^0.8.0",
+    "@kernhq/ui": "^0.10.0",
     "@tanstack/svelte-query": "^6.1.0",
     "svelte": "^5.46.0"
   },
@@ -86,10 +86,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
-    "typecheck": "tsc -p tsconfig.json --noEmit && svelte-check --tsconfig ./tsconfig.client.json --threshold error",
+    "typecheck": "tsc -p tsconfig.test.json && svelte-check --tsconfig ./tsconfig.client.json --threshold error",
     "test": "vitest run",
     "db:generate": "drizzle-kit generate",
-    "lint": "biome check . && node scripts/check-ranges.mjs package.json && node scripts/check-icons.mjs",
+    "lint": "biome check . && node scripts/check-ranges.mjs package.json && node scripts/check-icons.mjs && node scripts/check-snapshot-drift.mjs",
     "format": "biome check --write .",
     "changeset": "changeset"
   }

package/src/client/components/ClockControls.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-import { Button, Skeleton } from '@kernhq/ui'
+import { Button, localTime, Skeleton, toast } from '@kernhq/ui'
 import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
 import { getHrApi } from '../api-instance.js'
 import { t } from '../i18n.js'
@@ -11,12 +11,18 @@ import { formatDuration, hrKeys } from '../query.js'
  * 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.
+ *
+ * Every state of the query is drawn, including the two that used to render nothing: a failed state
+ * fetch took the clock off the attendance page and off the dashboard card with no message and no
+ * way back, and the only thing that could bring it back was a reload.
  */
 interface Props {
   workspaceId: string
 }
 const { workspaceId }: Props = $props()
 
+type Punch = 'in' | 'out' | 'break_start' | 'break_end'
+
 const api = getHrApi()
 const queryClient = useQueryClient()
 
@@ -27,15 +33,43 @@ const stateQuery = createQuery(() => ({
   // 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)
+// Not `state`: a variable of that name turns every `$state(...)` in this file into a store read
+// of it, and the rune stops existing.
+const clock = $derived(stateQuery.data)
 
 const words = {
   hours: (n: string) => t('hours_short', { n }),
   minutes: (n: string) => t('minutes_short', { n }),
 }
 
+/**
+ * `punching` rather than `act.isPending`: the disabled attribute only reaches the button on the
+ * next render, so two quick clicks both fire and the day sheet grows a punch nobody made. This is
+ * set in the same tick as the first click.
+ */
+let punching = $state(false)
+
+/**
+ * The reasons the server refuses a punch for, and this module's string for each.
+ *
+ * Keyed by the `reason` the router sends beside the refusal — never by the sentence, because a list
+ * of sentences is a list somebody has to keep in sync and the day it drifts the reader is told
+ * nothing. A reason missing from here is not a bug; it is the fallback doing its job: a sixth
+ * refusal added to `punch()` shows the sentence the router wrote until a string lands here.
+ *
+ * The message keys on the right are written out in full so `t()` passes them through untouched,
+ * which is what lets `onError` tell a resolved string from a key that resolved to itself.
+ */
+const punchRefusalMessages: Record<string, string> = {
+  'hr.clock.already_clocked_in': 'hr.clock_refused_already_in',
+  'hr.clock.not_clocked_in': 'hr.clock_refused_not_in',
+  'hr.clock.break_before_clock_in': 'hr.clock_refused_break_needs_in',
+  'hr.clock.already_on_break': 'hr.clock_refused_already_on_break',
+  'hr.clock.not_on_break': 'hr.clock_refused_not_on_break',
+}
+
 const act = createMutation(() => ({
-  mutationFn: async (action: 'in' | 'out' | 'break_start' | 'break_end') => {
+  mutationFn: async (action: Punch) => {
     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 })
@@ -45,55 +79,124 @@ const act = createMutation(() => ({
     // A punch changes the day sheet as well as the clock, and both are on screen.
     void queryClient.invalidateQueries({ queryKey: ['hr'] })
   },
+  onError: (error) => {
+    // The router refuses an impossible transition — clocking in twice, a break before clocking in —
+    // and that refusal is the only thing that says why the button did nothing. It arrives as two
+    // pieces: a `reason` this file translates, and the English sentence the router wrote for a
+    // reader. Nothing else that can fail here has written anything for a person: a network drop, a
+    // 500 or a gateway carry machine text, in English, and a clock is the last place to paste one.
+    // So a refusal is explained and everything else falls back to this module's own string.
+    //
+    // The test is the transport's `code`, never the sentence: a list of sentences is a list
+    // somebody has to keep in sync, and the day it drifts the person is told nothing.
+    const failure = error as { code?: unknown; message?: string; data?: { reason?: unknown } }
+    const refused = failure.code === 'CONFLICT'
+    const reason = refused && typeof failure.data?.reason === 'string' ? failure.data.reason : null
+    const key = reason ? punchRefusalMessages[reason] : undefined
+    // `t()` answers a key it has no string for with the key itself, so a translation is only used
+    // when it is one, and both ways of not having one land on the server's sentence: a reason no
+    // key covers, and a key whose string has not been merged yet. Neither may put
+    // `hr.clock_refused_not_in` — or nothing at all — in front of a person.
+    const translated = key ? t(key) : undefined
+    const explained = translated && translated !== key ? translated : refused ? failure.message : undefined
+    toast.error(explained || t('clock_punch_error'))
+    // A refusal is the server saying its picture of the day is not the one on screen — most often
+    // because the auto clock-out sweep closed the shift, or a punch arrived from another device.
+    // Both of those wrote a punch, so the day sheet beside the clock is as wrong as the clock is:
+    // re-read all of HR, exactly as a punch that landed does. Without this the same wrong clock
+    // stays up and every retry earns the same toast with no route to the truth.
+    void queryClient.invalidateQueries({ queryKey: ['hr'] })
+  },
+  onSettled: () => {
+    punching = false
+  },
 }))
 
-const since = $derived(
-  state?.since
-    ? new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit' }).format(new Date(state.since))
-    : null,
-)
+const punch = (action: Punch) => {
+  if (punching) return
+  punching = true
+  act.mutate(action)
+}
+
+const since = $derived(clock?.since ? localTime(new Date(clock.since)) : null)
 </script>
 
+<!--
+  Held data outranks the error, because this query polls. A failed background refetch leaves
+  TanStack in `error` while `data` is still the last good clock, so an error branch above this one
+  took "Working since 09:00" *and the clock-out button* off the screen of somebody mid-shift for a
+  minute at a time — every core restart, every rolling deploy. The error is only the whole frame
+  when there is nothing else to draw.
+-->
 {#if stateQuery.isLoading}
   <Skeleton height="72px" />
-{:else if state}
+{:else if clock}
   <div class="clock">
     <div class="status">
       <span class="line">
-        {#if state.onBreak && since}
+        {#if clock.onBreak && since}
           {t('on_break_since', { time: since })}
-        {:else if state.clockedIn && since}
+        {:else if clock.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>
+      {#if stateQuery.isError}
+        <!--
+          The total is the number that drifts — it is counted from an open span, so it is only ever
+          as current as the last successful poll. Saying so in its place costs no height (the widget
+          body is about 44px) and takes nothing away: the poll is still running, and a punch
+          refreshes the clock either way, so there is nothing here for a person to do.
+        -->
+        <span class="total stale" role="status">{t('clock_stale')}</span>
+      {:else}
+        <span class="total">
+          {t('worked_today')}: {formatDuration(clock.workedMinutesToday, words)}
+        </span>
+      {/if}
     </div>
 
     <div class="actions">
-      {#if !state.clockedIn}
-        <Button size="sm" disabled={act.isPending} onclick={() => act.mutate('in')}>
+      {#if !clock.clockedIn}
+        <Button size="sm" disabled={punching} onclick={() => punch('in')}>
           {t('clock_in')}
         </Button>
       {:else}
-        {#if state.onBreak}
-          <Button size="sm" variant="secondary" disabled={act.isPending} onclick={() => act.mutate('break_end')}>
+        {#if clock.onBreak}
+          <Button size="sm" variant="secondary" disabled={punching} onclick={() => punch('break_end')}>
             {t('break_end')}
           </Button>
         {:else}
-          <Button size="sm" variant="secondary" disabled={act.isPending} onclick={() => act.mutate('break_start')}>
+          <Button size="sm" variant="secondary" disabled={punching} onclick={() => punch('break_start')}>
             {t('break_start')}
           </Button>
         {/if}
-        <Button size="sm" disabled={act.isPending} onclick={() => act.mutate('out')}>
+        <Button size="sm" disabled={punching} onclick={() => punch('out')}>
           {t('clock_out')}
         </Button>
       {/if}
     </div>
   </div>
+{:else if stateQuery.isError}
+  <!--
+    The same row as the clock, rather than an `EmptyState`: this is read most often inside the clock
+    widget, whose body is about one grid row — roughly 44px — and a compact `EmptyState` is more
+    than twice that, so its retry button sat below a fold nobody scrolls. Here the button lands
+    where the clock-out button would have been.
+  -->
+  <div class="clock" role="alert">
+    <span class="line">{t('clock_error')}</span>
+    <Button size="sm" variant="secondary" onclick={() => void stateQuery.refetch()}>
+      {t('retry')}
+    </Button>
+  </div>
+{:else}
+  <!--
+    No workspace yet. The query is disabled until one arrives, and a disabled query is not
+    "loading" — so without this branch the clock is simply absent for that first frame.
+  -->
+  <Skeleton height="72px" />
 {/if}
 
 <style>
@@ -120,6 +223,10 @@ const since = $derived(
   font-size: 12px;
   font-variant-numeric: tabular-nums;
 }
+/* 5.23:1 on --kern-surface in light, 6.80:1 in dark — this is 12px text, so it has to clear 4.5. */
+.stale {
+  color: var(--kern-warning);
+}
 .actions {
   display: flex;
   gap: 8px;