@kernhq/module-hr 0.13.1 → 0.14.0

package/src/client/pages/AttendancePage.svelte

@@ -18,6 +18,7 @@ import { getHrApi } from '../api-instance.js'
 import ClockControls from '../components/ClockControls.svelte'
 import DayDetail from '../components/DayDetail.svelte'
 import { t } from '../i18n.js'
+import { canHr } from '../permissions.js'
 import { formatDuration, hrKeys, monthRange } from '../query.js'
 
 /**
@@ -47,6 +48,26 @@ const workspaceId = $derived(workspace?.id ?? '')
 
 const range = $derived(monthRange())
 
+/**
+ * The clock is the punch permission, and nothing else on this page is.
+ *
+ * `hr.attendance.view` is what opens this route — reading your own month — while every one of the
+ * four transitions behind `ClockControls` is `requires('hr.attendance.punch')` on the server. A
+ * workspace revokes that from somebody whose punches arrive from a badge terminal or from their
+ * manager, and for them the clock row was a set of buttons that can only answer 403 — an offer the
+ * product cannot honour.
+ *
+ * Hidden rather than disabled-with-a-reason, because this is a permission and not a state: they may
+ * never do it, there is nothing to wait for, and "you cannot clock in" repeated on every visit
+ * teaches nothing. It is also the same answer the dashboard already gives — `module.ts` declares the
+ * clock widget with `permission: attendancePunch`, so the shell has always hidden this exact
+ * component for these people. The page was the one place it leaked.
+ *
+ * The status line goes with the buttons it captions; the month underneath is what a viewer keeps,
+ * and today is a row in it.
+ */
+const canPunch = $derived(canHr('attendancePunch'))
+
 const daysQuery = createQuery(() => ({
   queryKey: hrKeys.attendanceDays(workspaceId, undefined, range.from, range.to),
   enabled: Boolean(workspaceId),
@@ -168,7 +189,9 @@ const dayLabel = (iso: string) =>
 {/snippet}
 
 <Page>
-  <ClockControls {workspaceId} />
+  {#if canPunch}
+    <ClockControls {workspaceId} />
+  {/if}
 
   {#if totalsUnknown}
     {@render tilesUnknown()}

package/src/client/pages/DirectoryPage.svelte

@@ -8,6 +8,7 @@ import {
   EmptyState,
   formatCount,
   formatDate,
+  Icon,
   Input,
   messageLocale,
   navigation,
@@ -24,6 +25,7 @@ import { getHrApi } from '../api-instance.js'
 import DecisionDialog from '../components/DecisionDialog.svelte'
 import PersonFormDialog from '../components/PersonFormDialog.svelte'
 import PersonPanel from '../components/PersonPanel.svelte'
+import { personnelVisibility } from '../components/redaction.js'
 import { t } from '../i18n.js'
 import type { ApprovalRequest } from '../index.js'
 import { canHr, HR_CAPABILITIES } from '../permissions.js'
@@ -48,11 +50,101 @@ const workspaceSlug = $derived(navigation.workspaceSlug)
 const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
 const workspaceId = $derived(workspace?.id ?? '')
 
+/**
+ * A query parameter is whatever somebody pasted into the address bar, and the contract types both
+ * filters as uuids — so a truncated or hand-edited link would be refused by the server and this
+ * screen would draw a red error where a filter was meant. Anything that is not a uuid is no filter.
+ */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const asId = (value: string | undefined): string | null => (value && UUID.test(value) ? value : null)
+
 let search = $state('')
-let officeTab = $state('all')
+/**
+ * The filter the directory was opened with.
+ *
+ * Both are links from somewhere else — an office row on the offices screen, "See the people" on a
+ * department — and until this read the query string they landed on the unfiltered company
+ * directory, which reads as the link being broken rather than as a filter that never applied.
+ *
+ * Seeded here rather than in the `$effect` below, and that is load-bearing: an effect runs after
+ * the first render, so `people.list` would fetch and draw the whole company for a beat before
+ * narrowing to the office somebody actually clicked.
+ */
+let officeTab = $state(asId(navigation.search.officeId) ?? 'all')
+let orgUnitId = $state<string | null>(asId(navigation.search.orgUnit))
 const selected = $derived(navigation.search.person)
 const creating = $derived(navigation.search.new === '1')
 
+/**
+ * The URL keeps seeding the filter after that first render: arriving from the offices screen while
+ * the directory is already mounted changes the query string without remounting anything, and the
+ * back button is a filter change too. It only ever writes what it does not read, so there is no loop.
+ */
+$effect(() => {
+  officeTab = asId(navigation.search.officeId) ?? 'all'
+  orgUnitId = asId(navigation.search.orgUnit)
+})
+
+/**
+ * A filter change is written to the URL as well as to state, so the address bar always describes
+ * what is on screen: a reload, a shared link and the back button all land on the same directory.
+ * `person` and `new` are carried through rather than rebuilt, or switching office would close a
+ * panel somebody has open.
+ *
+ * `replaceState` because a filter is not a place — the way back from a filtered directory is the
+ * screen that linked into it, not one history entry per pill.
+ */
+function writeFilter(patch: { officeId?: string | null; orgUnit?: string | null }) {
+  const params = new URLSearchParams(navigation.search)
+  for (const [key, value] of Object.entries(patch)) {
+    if (value) params.set(key, value)
+    else params.delete(key)
+  }
+  const query = params.toString()
+  navigation.go(`/${workspaceSlug}/hr${query ? `?${query}` : ''}`, {
+    replaceState: true,
+    keepFocus: true,
+    noScroll: true,
+  })
+}
+
+/** State first, URL second: the shell's router is asynchronous and the pills must not lag a click. */
+function chooseOffice(value: string) {
+  officeTab = value
+  writeFilter({ officeId: value === 'all' ? null : value })
+}
+
+/**
+ * Clears the search along with the office and the department.
+ *
+ * The empty state that offers this button is reached when a filter is on, which includes the case
+ * where a *search* inside that filter is what found nobody. Clearing only the filter there leaves
+ * the term in the box, so the table can still be empty after the click — a button that visibly does
+ * nothing, on the one screen where the reader has already failed to find someone.
+ */
+function clearFilters() {
+  officeTab = 'all'
+  orgUnitId = null
+  search = ''
+  debounced = ''
+  writeFilter({ officeId: null, orgUnit: null })
+}
+
+/**
+ * A row link carries the filter it was opened from.
+ *
+ * Now that the filter is in the query string, a bare `?person=…` is also a request to show the
+ * whole company — so opening somebody from an office directory would quietly re-fetch and redraw
+ * every person in the workspace behind the panel. `new` is dropped rather than kept: two dialogs
+ * over one directory is not a state anything should be able to link to.
+ */
+function personHref(personId: string): string {
+  const params = new URLSearchParams(navigation.search)
+  params.delete('new')
+  params.set('person', personId)
+  return `/${workspaceSlug}/hr?${params.toString()}`
+}
+
 const showOffices = $derived(session.hasCapability('hr', HR_CAPABILITIES.offices))
 /**
  * Leave is a capability, and a workspace that never switched it on has no balance to show.
@@ -79,6 +171,23 @@ $effect(() => {
   return () => clearTimeout(handle)
 })
 
+/**
+ * What the filter asks the server for, shared by the table and the counts above it.
+ *
+ * `includeDescendants` is passed rather than left to the contract's default: the number on the
+ * "See the people" button that links here is the department's *subtree* total, and a directory
+ * holding fewer people than the link promised is the same defect one layer down.
+ */
+const scopeArgs = $derived({
+  ...(officeTab !== 'all' ? { officeId: officeTab } : {}),
+  ...(orgUnitId ? { orgUnitId, includeDescendants: true } : {}),
+})
+/**
+ * The same filter as a cache key. `'all'` is spelled out rather than left absent, so that no two
+ * scopes ever hash alike and the cache cannot answer a filtered directory with the whole company.
+ */
+const scopeKey = $derived({ officeId: officeTab, orgUnitId: orgUnitId ?? 'all' })
+
 const officesQuery = createQuery(() => ({
   queryKey: hrKeys.offices(workspaceId),
   enabled: Boolean(workspaceId) && showOffices && canHr('officeView'),
@@ -87,24 +196,77 @@ const officesQuery = createQuery(() => ({
 const offices = $derived(officesQuery.data ?? [])
 
 const peopleQuery = createQuery(() => ({
-  queryKey: hrKeys.people(workspaceId, { q: debounced, officeId: officeTab }),
+  queryKey: hrKeys.people(workspaceId, { ...scopeKey, q: debounced }),
   enabled: Boolean(workspaceId),
   queryFn: () =>
     api.people.list({
       workspaceId,
       limit: 100,
       ...(debounced ? { q: debounced } : {}),
-      ...(officeTab !== 'all' ? { officeId: officeTab } : {}),
+      ...scopeArgs,
     }),
 }))
 const people = $derived(peopleQuery.data?.items ?? [])
 
+/**
+ * The tiles count the company, not the page.
+ *
+ * `people.list` returns a `total` for the whole filter, so both numbers are asked of the server
+ * with `limit: 1` rather than counted off the rows on screen. Counting the rows made "On leave"
+ * fall as somebody typed a name — the table narrows on every keystroke and stops at a hundred rows
+ * either way — which is a tile reporting the search box while wearing the label of a company fact.
+ *
+ * The search is deliberately not part of these: a tile describes the scope the directory is
+ * showing, and finding one person inside it does not change how many of them are away. The filter
+ * *is* part of them, so an office's directory shows that office's numbers.
+ */
+const headcountQuery = createQuery(() => ({
+  queryKey: hrKeys.people(workspaceId, { ...scopeKey, count: 'headcount' }),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.people.list({ workspaceId, limit: 1, ...scopeArgs }),
+}))
+
+const onLeaveQuery = createQuery(() => ({
+  queryKey: hrKeys.people(workspaceId, { ...scopeKey, count: 'on_leave' }),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.people.list({ workspaceId, limit: 1, status: ['on_leave'], ...scopeArgs }),
+}))
+
+/**
+ * Only to name the department in the filter chip, so it is asked for only when there is one to
+ * name. It shares `hrKeys.orgUnits` with the org chart, which is where "See the people" is clicked
+ * — so arriving from there costs no request at all.
+ */
+const orgUnitsQuery = createQuery(() => ({
+  queryKey: hrKeys.orgUnits(workspaceId),
+  enabled: Boolean(workspaceId) && orgUnitId !== null && canHr('orgView'),
+  queryFn: () => api.org.units.tree({ workspaceId, includeArchived: false }),
+}))
+const orgUnitName = $derived(orgUnitsQuery.data?.find((u) => u.id === orgUnitId)?.name ?? null)
+
 /** Office tabs only once there is more than one place of work — otherwise they say nothing. */
 const tabs = $derived([
   { value: 'all', label: t('title') },
   ...offices.map((o) => ({ value: o.id, label: o.name })),
 ])
 
+/**
+ * Whether the office filter has to be said in words.
+ *
+ * A selected pill already says it, so this is for what the tabs cannot cover: a workspace with one
+ * office (no tabs at all), a viewer without `hr.office.view`, and an id that is not in the list any
+ * more — an archived office whose link somebody kept. There is no name to give in any of those
+ * cases, which is why the chip's wording does not promise one.
+ *
+ * While the offices are still loading there is nothing to say yet and the table is drawing
+ * skeletons, so it waits rather than flashing a sentence a pill is about to replace.
+ */
+const officeNeedsChip = $derived(
+  officeTab !== 'all' && !officesQuery.isLoading && !tabs.some((tab) => tab.value === officeTab),
+)
+/** Any filter at all — what decides whether an empty table is "nobody yet" or "nobody here". */
+const filtered = $derived(officeTab !== 'all' || orgUnitId !== null)
+
 const balancesQuery = createQuery(() => ({
   queryKey: hrKeys.leaveBalance(workspaceId, undefined),
   enabled: Boolean(workspaceId) && showBalance,
@@ -205,9 +367,9 @@ const SUBJECT_LABELS: Record<string, () => string> = {
 const subjectLabel = (subjectType: string) => SUBJECT_LABELS[subjectType]?.() ?? subjectType
 
 const stats = $derived({
-  headcount: peopleQuery.data?.total ?? people.length,
+  headcount: headcountQuery.data?.total ?? null,
   offices: offices.length,
-  away: people.filter((p) => p.status === 'on_leave').length,
+  away: onLeaveQuery.data?.total ?? null,
   balance: balancesQuery.data?.[0]?.available ?? 0,
 })
 
@@ -265,8 +427,33 @@ function localTime(timezone: string | null, _tick: number): string | null {
 const started = (iso: string | null) =>
   iso ? formatDate(`${iso}T00:00:00`, { month: 'short', year: 'numeric' }) : '—'
 
+/**
+ * Whether this row's start date is blank because the server withheld it.
+ *
+ * The hire date is one of the four fields `HrAccessService` nulls for a reader outside its scope,
+ * and it arrives here as a null like any other — so the em dash this column drew for it said
+ * "never started", about everybody in the company, to every colleague without a widening key.
+ *
+ * `personnelVisibility` answers `unknown` for a reader whose scope only the server can resolve, and
+ * an unknown row keeps the dash: a dash over an empty field is imprecise, and "Hidden" over one is
+ * a lie. Both are marked once, under the table, rather than per row.
+ */
+const startWithheld = (person: { userId: string | null; hiredOn: string | null }) =>
+  !person.hiredOn && personnelVisibility(person) === 'withheld'
+
+/** Whether anything on the page is actually marked — the sentence must not outlive the marks. */
+const anyWithheld = $derived(people.some(startWithheld))
+
 /** `formatCount` caps at 99 for badges. A headcount is a real number and must not read "99+". */
 const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
+
+/**
+ * A count nobody has yet is an em dash, never a zero.
+ *
+ * "0 on leave" is a fact about the company, and a tile stating it while the request is still in
+ * flight — or after it failed — is the same lie the tile was counting rows to tell.
+ */
+const tileCount = (n: number | null) => (n === null ? '—' : count(n))
 </script>
 
 <PageHeader
@@ -283,7 +470,7 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
 
 <Page>
   <div class="tiles">
-    <StatTile size="md" label={t('widget_headcount_title')} value={count(stats.headcount)} />
+    <StatTile size="md" label={t('widget_headcount_title')} value={tileCount(stats.headcount)} />
     <!--
       Only where the workspace has offices. It rendered unconditionally and read "Offices 0" on a
       single-site workspace — a tile counting a feature nobody switched on, sitting beside three
@@ -292,7 +479,11 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
     {#if showOffices}
       <StatTile size="md" label={t('offices_title')} value={count(stats.offices)} />
     {/if}
-    <StatTile size="md" label={t('status_on_leave')} value={count(stats.away)} />
+    <!--
+      The number comes from the server, and the note says which number it is: "On leave" over a
+      figure could as easily mean this week or this month, and it means neither.
+    -->
+    <StatTile size="md" label={t('status_on_leave')} value={tileCount(stats.away)} note={t('on_leave_note')} />
     <!-- Same rule for leave: the balance tile is the surface of a capability, so it goes with it. -->
     {#if showBalance}
       <StatTile
@@ -310,7 +501,28 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
 
       <div class="filters">
         {#if tabs.length > 1}
-          <Tabs items={tabs} value={officeTab} variant="pill" onValueChange={(v) => (officeTab = v)} />
+          <Tabs items={tabs} value={officeTab} variant="pill" label={t('office')} onValueChange={chooseOffice} />
+        {/if}
+        <!--
+          What the pills cannot say. A directory that opened filtered and says nothing about it is
+          indistinguishable from a directory that lost half the company, so anything the tabs are not
+          already showing gets a chip — and one control puts every filter back at once.
+        -->
+        {#if officeNeedsChip || orgUnitId}
+          <div class="active">
+            {#if officeNeedsChip}
+              <span class="chip">
+                <Icon name="building" size={12} strokeWidth={1.8} />{t('filter_office_unnamed')}
+              </span>
+            {/if}
+            {#if orgUnitId}
+              <span class="chip">
+                <Icon name="git-branch" size={12} strokeWidth={1.8} />
+                {orgUnitName ? t('filter_department', { name: orgUnitName }) : t('filter_department_unnamed')}
+              </span>
+            {/if}
+            <Button size="xs" variant="ghost" onclick={clearFilters}>{t('filter_clear')}</Button>
+          </div>
         {/if}
         <div class="search">
           <Input bind:value={search} placeholder={t('search_people')} type="search" size="sm" />
@@ -339,7 +551,7 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
           </div>
           {#each people as person (person.id)}
             {@const time = localTime(person.timezone, tick)}
-            <a class="trow" role="row" href={`/${workspaceSlug}/hr?person=${person.id}`}>
+            <a class="trow" role="row" href={personHref(person.id)}>
               <span class="cell who" role="cell">
                 <Avatar name={person.displayName} id={person.id} size={28} />
                 <span class="stack">
@@ -349,7 +561,11 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
               </span>
               <span class="cell role" role="cell">{person.employeeNo ?? '—'}</span>
               <span class="cell muted" role="cell">{person.officeName ?? '—'}</span>
-              <span class="cell muted" role="cell">{started(person.hiredOn)}</span>
+              <span class="cell muted" role="cell">
+                {#if startWithheld(person)}
+                  <span class="withheld"><Icon name="eye-off" size={12} strokeWidth={1.8} />{t('person_hidden')}</span>
+                {:else}{started(person.hiredOn)}{/if}
+              </span>
               <span class="cell num" role="cell" title={person.timezone ?? ''}>{time ?? '—'}</span>
               <span class="cell" role="cell">
                 <Badge tone={statusTone(person.status)}>{statusLabel(person.status)}</Badge>
@@ -363,9 +579,30 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
             <Button variant="secondary" onclick={() => void peopleQuery.refetch()}>{t('retry')}</Button>
           {/snippet}
         </EmptyState>
+      <!--
+        "Nobody here yet — add the first person" is the right sentence for an empty company and the
+        wrong one for an office with nobody in it: it invites somebody to create a second record for
+        a person the filter is simply hiding. A filtered miss offers the way out instead.
+      -->
+      {:else if filtered}
+        <EmptyState icon="search" title={t('no_people_match')} description={t('no_people_match_filtered')}>
+          {#snippet actions()}
+            <Button variant="secondary" onclick={clearFilters}>{t('filter_clear')}</Button>
+          {/snippet}
+        </EmptyState>
+      {:else if debounced}
+        <EmptyState icon="search" title={t('no_people_match')} description={t('no_people_match_search')} />
       {:else}
         <EmptyState icon="users" title={t('no_people')} description={t('no_people_desc')} />
       {/if}
+
+      <!--
+        Once for the table, not once per row. A marked cell says which fact is missing and this says
+        why it is missing — a column of "Hidden" with nothing accounting for it reads as a fault.
+      -->
+      {#if anyWithheld}
+        <p class="hint">{t('person_hidden_hint')}</p>
+      {/if}
     </section>
 
     <aside>
@@ -458,11 +695,34 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
   display: flex;
   align-items: center;
   gap: 12px;
+  /* A department name is as long as somebody named it, and Persian and German run longer than the
+     English it was laid out in. The row wraps rather than crushing the search box. */
+  flex-wrap: wrap;
   margin-block: 4px 8px;
 }
 .search {
   margin-inline-start: auto;
-  width: min(260px, 40%);
+  inline-size: min(260px, 40%);
+}
+.active {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+  min-inline-size: 0;
+}
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding-inline: 9px;
+  block-size: 24px;
+  border-radius: var(--kern-r-full);
+  background: var(--kern-surface-chip);
+  font-size: 12px;
+  /* A colour, not opacity: opacity fades text against the page whatever token it names. */
+  color: var(--kern-ink-700);
+  white-space: nowrap;
 }
 .rows {
   display: grid;
@@ -529,6 +789,20 @@ const count = (n: number) => formatCount(n, Number.MAX_SAFE_INTEGER)
 .role {
   font-size: 13px;
 }
+/* A colour, never opacity, for the same reason `.sub` and `.muted` above use one. */
+.withheld {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  min-inline-size: 0;
+}
+.hint {
+  margin: 10px 0 0;
+  max-inline-size: 68ch;
+  font-size: 12px;
+  line-height: 1.45;
+  color: var(--kern-ink-500);
+}
 .num {
   font-size: 13px;
   color: var(--kern-ink-500);

package/src/client/pages/OfficesPage.svelte

@@ -160,6 +160,12 @@ const kindTone = (kind: string): BadgeTone => (kind === 'remote' ? 'info' : 'gre
         <span role="columnheader">{t('local_time')}</span>
       </div>
       {#each offices as office (office.id)}
+        <!--
+          `officeId` is read by the directory, which seeds its office filter from it and shows the
+          filter it landed with. The parameter name is the whole contract between the two screens:
+          renaming it here alone breaks nothing loudly — the link still resolves, and quietly lands
+          on the unfiltered company directory, which is exactly how it shipped.
+        -->
         <a
           class="trow"
           role="row"

package/src/client/pages/OrgPage.svelte

@@ -871,6 +871,13 @@ const tabs = $derived([
             </div>
 
             {#if selected.total > 0}
+              <!--
+                `orgUnit` is read by the directory, which seeds an org-unit filter from it and asks
+                for the whole subtree — which is why the count here is `total` and not `headcount`.
+                The parameter name is the whole contract between the two screens: renaming it here
+                alone breaks nothing loudly, it just lands on the unfiltered company directory,
+                which is exactly how it shipped.
+              -->
               <Button
                 size="sm"
                 variant="secondary"

package/src/client/permissions.ts

@@ -23,10 +23,18 @@ export function canHr(permission: HrPermission): boolean {
 }
 
 /**
- * Whether the viewer can see anybody's record but their own.
+ * Whether the viewer reads the personnel record behind a directory card, for anybody but themselves.
  *
- * 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.
+ * Not "can they open somebody else's page" — everybody can, and should. `hr.person.view` is a
+ * `member` default and the directory is meant to be read. What the three widening keys decide is
+ * how much of each person comes back: personal email, phone, hire date and termination date are the
+ * personnel record, and the server nulls all four for anybody outside the reader's scope.
+ *
+ * The three do not imply one another — a country HR manager must not silently become a global one —
+ * so a screen asks the union once, here. It is only a hint: which *people* fall inside a team or an
+ * office is resolved on the server from the org chart, so a screen may not conclude from `true`
+ * that a particular person's record is readable. Render what came back; use this to decide whether
+ * a "personal details" section is worth offering at all.
  */
-export const canSeeOthers = (): boolean =>
+export const canSeeFullRecords = (): boolean =>
   canHr('personViewTeam') || canHr('personViewOffice') || canHr('personViewAll')