@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/i18n.ts

@@ -1,169 +1,14 @@
-import { type Message, scopedT } from '@kernhq/ui'
-
-/**
- * This module's own strings, in every locale the platform ships.
- *
- * A module ships separately from the app, so Paraglide — which compiles only the app's
- * `messages/*.json` — cannot see these. The shell merges them into the framework's message runtime
- * when it registers the module, and `t()` resolves against the merged map. Keys are namespaced by
- * module id, which is what keeps two modules from colliding in that one map.
- *
- * A **counted** message is not a string with `{count}` in it: give it a map of CLDR plural category
- * to string and `t(key, { n })` picks the form. English has two and Arabic has six, and which one
- * applies is `Intl.PluralRules`' answer rather than yours.
- *
- * Words every module needs and none owns — Save, Cancel, Retry — come from the framework's `common`
- * bundle (`t('common.save')`). Do not copy them here; six translations of "Save" drift apart.
- */
-
-export const en: Record<string, Message> = {
-  'inventory.nav': 'Inventory',
-  'inventory.title': 'Assets',
-  'inventory.empty': 'No assets yet',
-  'inventory.empty_desc': 'Add the first laptop, phone or desk — anything the company owns.',
-  'inventory.new': 'New asset',
-  'inventory.edit': 'Edit asset',
-  'inventory.code': 'Asset tag',
-  'inventory.name': 'Name',
-  'inventory.name_placeholder': 'MacBook Pro 14", office chair…',
-  'inventory.description': 'Description',
-  'inventory.category': 'Category',
-  'inventory.serial_number': 'Serial number',
-  'inventory.location': 'Location',
-  'inventory.purchased_on': 'Purchase date',
-  'inventory.purchased_from': 'Purchased from',
-  'inventory.price': 'Price',
-  'inventory.warranty_until': 'Warranty until',
-  'inventory.status_in_stock': 'In stock',
-  'inventory.status_assigned': 'Assigned',
-  'inventory.status_under_repair': 'Under repair',
-  'inventory.status_retired': 'Retired',
-  'inventory.count': { one: '{n} asset', other: '{n} assets' },
-  'inventory.search_placeholder': 'Search by name, tag or serial…',
-  'inventory.filter_all_statuses': 'All statuses',
-  'inventory.archived': 'Archived',
-  'inventory.archive': 'Archive',
-  'inventory.restore': 'Restore',
-  'inventory.widget_title': 'Recent assets',
-  'inventory.widget_desc': 'The most recently added assets in this workspace.',
-}
-
-export type InventoryMessageKey = keyof typeof en
-
-export const fa: Record<string, Message> = {
-  'inventory.nav': 'اموال',
-  'inventory.title': 'اقلام',
-  'inventory.empty': 'هنوز قلمی ثبت نشده است',
-  'inventory.empty_desc': 'اولین لپ‌تاپ، گوشی یا میز را اضافه کنید — هر چیزی که شرکت دارد.',
-  'inventory.new': 'قلم جدید',
-  'inventory.edit': 'ویرایش قلم',
-  'inventory.code': 'کد قلم',
-  'inventory.name': 'نام',
-  'inventory.name_placeholder': 'مک‌بوک پرو ۱۴ اینچ، صندلی اداری…',
-  'inventory.description': 'توضیحات',
-  'inventory.category': 'دسته',
-  'inventory.serial_number': 'شماره سریال',
-  'inventory.location': 'محل استقرار',
-  'inventory.purchased_on': 'تاریخ خرید',
-  'inventory.purchased_from': 'خریداری از',
-  'inventory.price': 'قیمت',
-  'inventory.warranty_until': 'گارانتی تا',
-  'inventory.status_in_stock': 'در انبار',
-  'inventory.status_assigned': 'تحویل‌شده',
-  'inventory.status_under_repair': 'در تعمیر',
-  'inventory.status_retired': 'اسقاط‌شده',
-  'inventory.count': { one: '{n} قلم', other: '{n} قلم' },
-  'inventory.search_placeholder': 'جستجو بر اساس نام، کد یا سریال…',
-  'inventory.filter_all_statuses': 'همه وضعیت‌ها',
-  'inventory.archived': 'بایگانی‌شده',
-  'inventory.archive': 'بایگانی',
-  'inventory.restore': 'بازگردانی',
-  'inventory.widget_title': 'اقلام اخیر',
-  'inventory.widget_desc': 'آخرین اقلامی که به این فضای کاری اضافه شده‌اند.',
-}
-
-export const ar: Record<string, Message> = {
-  'inventory.nav': 'الأصول',
-  'inventory.title': 'الأصول',
-  'inventory.empty': 'لا أصول بعد',
-  'inventory.empty_desc': 'أضف أول حاسوب أو هاتف أو مكتب — أي شيء تملكه الشركة.',
-  'inventory.new': 'أصل جديد',
-  'inventory.edit': 'تعديل الأصل',
-  'inventory.code': 'رمز الأصل',
-  'inventory.name': 'الاسم',
-  'inventory.name_placeholder': 'حاسوب ماك بوك برو ١٤، كرسي مكتبي…',
-  'inventory.description': 'الوصف',
-  'inventory.category': 'الفئة',
-  'inventory.serial_number': 'الرقم التسلسلي',
-  'inventory.location': 'الموقع',
-  'inventory.purchased_on': 'تاريخ الشراء',
-  'inventory.purchased_from': 'تم الشراء من',
-  'inventory.price': 'السعر',
-  'inventory.warranty_until': 'الضمان حتى',
-  'inventory.status_in_stock': 'في المخزن',
-  'inventory.status_assigned': 'مُسلَّم',
-  'inventory.status_under_repair': 'قيد الإصلاح',
-  'inventory.status_retired': 'مستبعد',
-  'inventory.count': {
-    zero: 'لا أصول',
-    one: 'أصل واحد',
-    two: 'أصلان',
-    few: '{n} أصول',
-    many: '{n} أصلاً',
-    other: '{n} أصل',
-  },
-  'inventory.search_placeholder': 'ابحث بالاسم أو الرمز أو الرقم التسلسلي…',
-  'inventory.filter_all_statuses': 'جميع الحالات',
-  'inventory.archived': 'مؤرشف',
-  'inventory.archive': 'أرشفة',
-  'inventory.restore': 'استعادة',
-  'inventory.widget_title': 'أصول حديثة',
-  'inventory.widget_desc': 'الأصول المضافة أخيرًا إلى مساحة العمل هذه.',
-}
-
-export const de: Record<string, Message> = {
-  'inventory.nav': 'Inventar',
-  'inventory.title': 'Gegenstände',
-  'inventory.empty': 'Noch keine Gegenstände',
-  'inventory.empty_desc':
-    'Fügen Sie den ersten Laptop, das erste Telefon oder den ersten Schreibtisch hinzu — alles, was die Firma besitzt.',
-  'inventory.new': 'Neuer Gegenstand',
-  'inventory.edit': 'Gegenstand bearbeiten',
-  'inventory.code': 'Inventarnummer',
-  'inventory.name': 'Name',
-  'inventory.name_placeholder': 'MacBook Pro 14", Bürostuhl…',
-  'inventory.description': 'Beschreibung',
-  'inventory.category': 'Kategorie',
-  'inventory.serial_number': 'Seriennummer',
-  'inventory.location': 'Standort',
-  'inventory.purchased_on': 'Kaufdatum',
-  'inventory.purchased_from': 'Gekauft bei',
-  'inventory.price': 'Preis',
-  'inventory.warranty_until': 'Garantie bis',
-  'inventory.status_in_stock': 'Auf Lager',
-  'inventory.status_assigned': 'Zugewiesen',
-  'inventory.status_under_repair': 'In Reparatur',
-  'inventory.status_retired': 'Ausgemustert',
-  'inventory.count': { one: '{n} Gegenstand', other: '{n} Gegenstände' },
-  'inventory.search_placeholder': 'Nach Name, Nummer oder Seriennummer suchen…',
-  'inventory.filter_all_statuses': 'Alle Zustände',
-  'inventory.archived': 'Archiviert',
-  'inventory.archive': 'Archivieren',
-  'inventory.restore': 'Wiederherstellen',
-  'inventory.widget_title': 'Neue Gegenstände',
-  'inventory.widget_desc': 'Die zuletzt hinzugefügten Gegenstände dieses Arbeitsbereichs.',
-}
-
-/**
- * Add a locale by adding a bundle here. Bundles are thunks so a locale is fetched only when it is
- * the one in use; English is the fallback and is therefore always loaded.
- */
-export const inventoryMessageBundles = {
-  ar: async () => ar,
-  de: async () => de,
-  en: async () => en,
-  fa: async () => fa,
-}
+import { scopedT } from '@kernhq/ui'
+
+export {
+  ar,
+  de,
+  en,
+  fa,
+  type InventoryMessageKey,
+  inventoryMessageBundles,
+  tr,
+} from './messages.js'
 
 /** `t('nav')` — the module id is implied. `t('common.save')` still reaches the shared bundle. */
 export const t = scopedT('inventory')

package/src/client/index.ts

@@ -17,7 +17,14 @@
  * `files` in package.json must cover every directory this entry reaches, contract source included.
  */
 
-export { type Asset, type AssetStatus, inventoryPermissions, MODULE_ID } from '../contract.js'
+export {
+  type Asset,
+  type AssetStatus,
+  InventorySettings,
+  inventoryCapabilities,
+  inventoryPermissions,
+  MODULE_ID,
+} from '../contract/index.js'
 export { createInventoryClient, type InventoryApi } from './api.js'
 export { __setInventoryApi, getInventoryApi } from './api-instance.js'
 export { type InventoryMessageKey, inventoryMessageBundles, t } from './i18n.js'

package/src/client/links.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { ASSET_PARAM, assetHref, INVENTORY_PATH, inventoryHref } from './links.js'
+
+/**
+ * The link a dashboard card follows, and the parameter the page reads.
+ *
+ * Both cards showed rows and did nothing with them — `kern-widget` §3, a table of contents rather
+ * than a card. A row now opens the asset's panel, which is a URL, which means three things have to
+ * agree: the route `module.ts` declares, the parameter `AssetsPage` reads, and the href built here.
+ * They are one constant each now, and this holds them to it: a link that is one character off does
+ * not fail, it silently lands on the list with nothing open, which looks like the panel is broken.
+ */
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+describe('assetHref', () => {
+  it('scopes the link to the workspace, because the shell mounts every module under a slug', () => {
+    // Without the slug a card on one workspace's dashboard links into another's, or into nothing.
+    expect(inventoryHref('acme')).toBe('/acme/inventory')
+    expect(assetHref('acme', '0192-abc')).toBe('/acme/inventory?asset=0192-abc')
+  })
+
+  it('produces a URL whose parameter is the one the page reads back', () => {
+    const url = new URL(assetHref('acme', '0192-abc'), 'https://kern.example.com')
+    expect(url.pathname).toBe('/acme/inventory')
+    expect(url.searchParams.get(ASSET_PARAM)).toBe('0192-abc')
+  })
+
+  it('encodes the id rather than trusting it to be a uuid for ever', () => {
+    const href = assetHref('acme', 'a&b=c')
+    expect(href).toContain('asset=a%26b%3Dc')
+    expect(new URL(href, 'https://x.test').searchParams.get(ASSET_PARAM)).toBe('a&b=c')
+  })
+})
+
+describe('the route this links to is the route the module declares', () => {
+  /**
+   * `module.ts` cannot be imported here — it reaches `@kernhq/ui`, whose entry point pulls in Svelte
+   * components this package's test setup cannot transform. So the declaration is read as text,
+   * which is enough: what would break is a path renamed in one file and not the other.
+   */
+  it('matches the path in `module.ts`', () => {
+    const source = readFileSync(join(HERE, 'module.ts'), 'utf8')
+    expect(source).toContain(`path: '${INVENTORY_PATH}'`)
+  })
+
+  it('is the parameter `AssetsPage` opens its panel from', () => {
+    // The page imports `ASSET_PARAM` rather than repeating the literal, so this checks the import
+    // is actually what it reads — a re-introduced `params.get('asset')` would pass by accident and
+    // then drift the first time the name changed.
+    const page = readFileSync(join(HERE, 'pages', 'AssetsPage.svelte'), 'utf8')
+    expect(page).toContain('params.get(ASSET_PARAM)')
+    expect(page).toContain("from '../links.js'")
+  })
+
+  it('is what both dashboard cards send somebody to', () => {
+    // The defect being guarded: a widget row that is inert. Each card builds its href from this
+    // module, so neither can go back to being a list nobody can act on without this failing.
+    for (const widget of ['OverviewWidget.svelte', 'RepairsWidget.svelte']) {
+      const source = readFileSync(join(HERE, 'widgets', widget), 'utf8')
+      expect({ widget, links: source.includes('assetHref(workspaceSlug') }).toEqual({
+        widget,
+        links: true,
+      })
+      // An anchor, not a click handler: that is what makes the keyboard route the same route.
+      expect({ widget, anchor: /<a\s+class="row"\s+href=/.test(source) }).toEqual({
+        widget,
+        anchor: true,
+      })
+    }
+  })
+})

package/src/client/links.ts

@@ -0,0 +1,44 @@
+/**
+ * Where this module's screens live, as URLs.
+ *
+ * Two things need to agree and were three files apart: `module.ts` declares the route, `AssetsPage`
+ * reads `?asset=<id>` to decide which panel is open, and a dashboard card has to be able to send
+ * somebody to exactly that. A widget that only *shows* rows is a table of contents — `kern-widget`
+ * §3 — and both of this module's cards were exactly that, with no way to act on a row at all.
+ *
+ * A pure module rather than a constant inside a component, for the reason `custody.ts` and
+ * `price.ts` are: `module.ts` imports `@kernhq/ui`, so anything that reads its route declaration
+ * drags a Svelte compiler behind it, and "does this href open that panel" is a fact with a right
+ * answer.
+ */
+
+/** The module's own route, as declared in `module.ts`. The workspace slug goes in front of it. */
+export const INVENTORY_PATH = '/inventory'
+
+/** The parameter `AssetsPage` reads to decide which asset's panel is open. */
+export const ASSET_PARAM = 'asset'
+
+/**
+ * The list, scoped to a workspace.
+ *
+ * The shell mounts every module route under `/<workspaceSlug>`, so a link built without the slug
+ * lands on the wrong workspace — or on nothing, which is what a widget on a second workspace's
+ * dashboard would have done.
+ */
+export function inventoryHref(workspaceSlug: string): string {
+  return `/${workspaceSlug}${INVENTORY_PATH}`
+}
+
+/**
+ * One asset, open in its panel over the list.
+ *
+ * Deliberately the list URL with a parameter rather than a page of its own: that is the URL the
+ * page already owns, so following it from a dashboard card leaves somebody in the same place they
+ * would have reached by clicking the row — with the list behind the panel, and Back closing it.
+ *
+ * The id is encoded even though it is always a uuid. A raw value in a query string is how a link
+ * builder eventually ships an injection, and `encodeURIComponent` costs nothing on a uuid.
+ */
+export function assetHref(workspaceSlug: string, assetId: string): string {
+  return `${inventoryHref(workspaceSlug)}?${ASSET_PARAM}=${encodeURIComponent(assetId)}`
+}

package/src/client/members.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { directory, directoryStatus, displayName, type NameWords, nameOf, resolveName } from './members.js'
+import { en } from './messages.js'
+
+/**
+ * What a stored uuid reads as, and — the part that was wrong — *when* it is entitled to say so.
+ *
+ * `nameOf` resolved every id it could not find to "a former member". That is a claim about a
+ * person, and it was made in two states where nothing was known about anybody: while the members
+ * request was still in flight, and after it had failed. So an asset panel opened on a laptop that
+ * had changed hands twice read
+ *
+ *     A former member handed it to A former member
+ *     A former member took it back from A former member
+ *
+ * for the first moments of every load — and permanently whenever core was unreachable, which is
+ * exactly when somebody is most likely to be staring at the screen trying to work out what happened.
+ *
+ * Neither state can be told from an empty map, which is why the fix is on the `Directory` rather
+ * than at the call sites: the request's own state has to travel with the rows.
+ */
+const member = (userId: string, name: string | null, email: string) => ({
+  userId,
+  user: { id: userId, name, email },
+})
+
+const PEOPLE = [
+  member('a', 'Ada Lovelace', 'ada@example.com'),
+  member('b', null, 'bruno@example.com'),
+  member('c', '   ', 'carla@example.com'),
+]
+
+const words: NameWords = {
+  loading: '…',
+  unknown: 'Someone',
+  former: 'A former member',
+  system: 'The system',
+}
+
+describe('displayName', () => {
+  it('falls back to the email for somebody who has never signed in', () => {
+    const dir = directory(PEOPLE)
+    expect(displayName(dir.byId.get('b'))).toBe('bruno@example.com')
+  })
+
+  it('treats a blank name as absent, so no row has an empty person column', () => {
+    const dir = directory(PEOPLE)
+    expect(displayName(dir.byId.get('c'))).toBe('carla@example.com')
+  })
+})
+
+describe('directoryStatus', () => {
+  it('reads a query that has not answered as loading, not as an empty workspace', () => {
+    expect(directoryStatus({ isSuccess: false, isError: false })).toBe('loading')
+  })
+
+  it('reads a failure as its own state rather than as an absence', () => {
+    expect(directoryStatus({ isSuccess: false, isError: true })).toBe('error')
+  })
+
+  it('is ready only once the data is actually in hand', () => {
+    // `isSuccess`, never `!isPending`: a query with `enabled: false` reports `isPending` for ever,
+    // and the assets page disables this one until something is filtered by custodian.
+    expect(directoryStatus({ isSuccess: true, isError: false })).toBe('ready')
+  })
+})
+
+describe('resolveName tells the three unknowns apart', () => {
+  const ready = directory(PEOPLE, 'ready')
+  const loading = directory([], 'loading')
+  const failed = directory([], 'error')
+  const gone = '01920000-0000-7000-8000-00000000dead'
+
+  it('names somebody the workspace has', () => {
+    expect(resolveName('a', ready)).toEqual({ kind: 'person', name: 'Ada Lovelace' })
+  })
+
+  it('says nothing at all while the member list is still in flight', () => {
+    // The regression. This answered `former` — "A former member handed it to A former member" —
+    // for the first moments of every panel, about people who had not gone anywhere.
+    expect(resolveName('a', loading)).toEqual({ kind: 'loading', name: null })
+    expect(resolveName(gone, loading)).toEqual({ kind: 'loading', name: null })
+  })
+
+  it('says the lookup failed rather than that the person left', () => {
+    // The same claim, made permanent: with core unreachable, every name on the screen used to
+    // report that its owner had been removed from the workspace.
+    expect(resolveName('a', failed)).toEqual({ kind: 'unknown', name: null })
+  })
+
+  it('says somebody has left only once the list is in hand and does not contain them', () => {
+    expect(resolveName(gone, ready)).toEqual({ kind: 'former', name: null })
+  })
+
+  it('has no name for a row nothing signed, in every state', () => {
+    for (const dir of [ready, loading, failed])
+      expect(resolveName(null, dir)).toEqual({ kind: 'system', name: null })
+  })
+
+  it('carries a name only for somebody actually found, which is what the avatar reads', () => {
+    // An `Avatar` seeded with "…" would draw the initials of an ellipsis in a coloured square.
+    for (const resolved of [resolveName('a', loading), resolveName(gone, ready), resolveName(null, ready)])
+      if (resolved.kind !== 'person') expect(resolved.name).toBe(null)
+  })
+})
+
+describe('nameOf', () => {
+  const ready = directory(PEOPLE, 'ready')
+
+  it('gives each of the four unknowns its own word', () => {
+    expect(nameOf('a', ready, words)).toBe('Ada Lovelace')
+    expect(nameOf('a', directory([], 'loading'), words)).toBe('…')
+    expect(nameOf('a', directory([], 'error'), words)).toBe('Someone')
+    expect(nameOf('gone', ready, words)).toBe('A former member')
+    expect(nameOf(null, ready, words)).toBe('The system')
+  })
+
+  it('never renders a raw uuid', () => {
+    const uuid = '01920000-0000-7000-8000-00000000dead'
+    for (const dir of [ready, directory([], 'loading'), directory([], 'error')])
+      expect(nameOf(uuid, dir, words)).not.toContain(uuid)
+  })
+
+  /**
+   * The words are translated, and a missing one would render the key — `inventory.member_loading`
+   * — in the middle of a timeline entry, in every locale at once.
+   */
+  it('has a catalogue entry for every word it asks a screen for', () => {
+    for (const key of ['member_loading', 'member_unknown', 'member_former', 'member_system'])
+      expect({ key, has: `inventory.${key}` in en }).toEqual({ key, has: true })
+  })
+})

package/src/client/members.ts

@@ -0,0 +1,116 @@
+import type { CoreMember } from './core-api.js'
+
+/**
+ * Turning a stored user id into a name a person recognises.
+ *
+ * Custody rows and history rows both carry plain uuids — a module keeps cross-schema ids plain, and
+ * a name copied into this module's tables would be a name that goes stale the day somebody marries.
+ * So every screen that shows *who* resolves the id here, against the members core says the workspace
+ * has right now.
+ *
+ * **The list is a request, and a request has three answers, not one.** This file resolved an
+ * unknown id straight to "a former member" without ever asking whether the list had arrived — so
+ * for the first moments of every panel, before the members request came back, an entire timeline
+ * read "A former member handed it to A former member", and it stayed that way for ever if the
+ * request failed. The claim was false in both cases: nobody had left. `status` is what separates
+ * *we do not know yet*, *we could not find out* and *this person really is gone*, and the three are
+ * rendered as three different things.
+ *
+ * Pure, and here rather than inside a component, for the reason `price.ts` and `timeline.ts` are:
+ * a `.svelte` file drags a compiler behind it and cannot be unit-tested, and "what does this id
+ * read as" is a fact with a right answer.
+ */
+
+/** Where the members request has got to. `ready` is the only state whose absences mean anything. */
+export type DirectoryStatus = 'loading' | 'error' | 'ready'
+
+export interface Directory {
+  /** Everybody the workspace has, by user id. Empty until `status` is `ready`. */
+  byId: ReadonlyMap<string, CoreMember>
+  /** The same ids as a set, which is what `actorKind` asks about. */
+  ids: ReadonlySet<string>
+  /** Whether this directory is in a position to say that somebody is missing from it. */
+  status: DirectoryStatus
+}
+
+export function directory(members: readonly CoreMember[], status: DirectoryStatus = 'ready'): Directory {
+  const byId = new Map<string, CoreMember>()
+  for (const member of members) byId.set(member.userId, member)
+  return { byId, ids: new Set(byId.keys()), status }
+}
+
+/**
+ * A TanStack query's flags as the one word this file needs.
+ *
+ * Here rather than inlined into each screen because the mapping has a trap in it: a query with
+ * `enabled: false` reports `isPending` for ever, so "not pending" is not the same question as
+ * "arrived". `isSuccess` is the only flag that means the data is in hand.
+ */
+export function directoryStatus(query: { isSuccess: boolean; isError: boolean }): DirectoryStatus {
+  if (query.isError) return 'error'
+  return query.isSuccess ? 'ready' : 'loading'
+}
+
+/**
+ * What to call somebody.
+ *
+ * `name` is nullable in core — an invited person who has never signed in has an email and nothing
+ * else — so the email is the fallback rather than an empty label. A blank name is treated as absent
+ * for the same reason: a row whose person column is empty reads as a bug in the register.
+ */
+export function displayName(member: CoreMember | undefined): string | null {
+  if (!member) return null
+  const name = member.user.name?.trim()
+  return name || member.user.email
+}
+
+/**
+ * The five answers to "who is this id", before any of them is turned into words.
+ *
+ * `person` is the only one carrying a name. The other four each say something different and only
+ * one of them is a claim about the *person*:
+ *
+ * - `loading` — the workspace's members have not arrived. Nothing is known yet, and saying anything
+ *   about who this is would be inventing it.
+ * - `unknown` — the members request failed. Somebody did this; which somebody cannot be found out
+ *   right now, and that is a fact about the request rather than about them.
+ * - `former` — the list is in hand and this id is not in it. *Now* "a former member" is true.
+ * - `system` — there is no id at all: a nightly sweep, an import, an offboarding hook.
+ */
+export type NameKind = 'person' | 'loading' | 'unknown' | 'former' | 'system'
+
+export interface ResolvedName {
+  kind: NameKind
+  /** The name, and only for `person`. Everything else has no name to give. */
+  name: string | null
+}
+
+export function resolveName(userId: string | null, dir: Directory): ResolvedName {
+  if (!userId) return { kind: 'system', name: null }
+  const name = displayName(dir.byId.get(userId))
+  if (name) return { kind: 'person', name }
+  if (dir.status === 'loading') return { kind: 'loading', name: null }
+  if (dir.status === 'error') return { kind: 'unknown', name: null }
+  return { kind: 'former', name: null }
+}
+
+/** The words a screen supplies for the four answers that have no name of their own. */
+export interface NameWords {
+  loading: string
+  unknown: string
+  former: string
+  system: string
+}
+
+/**
+ * The one place an unresolvable id is turned into words.
+ *
+ * The words are given by the caller because they are translated strings, and this file holds no
+ * strings — it decides *which* of the five answers applies and leaves the wording to the catalogue.
+ * Never the raw uuid: a sentence with a uuid in the middle of it is the interface admitting it does
+ * not know what it is talking about.
+ */
+export function nameOf(userId: string | null, dir: Directory, words: NameWords): string {
+  const resolved = resolveName(userId, dir)
+  return resolved.kind === 'person' ? (resolved.name as string) : words[resolved.kind]
+}