@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/settings/GeneralSettings.svelte

@@ -0,0 +1,403 @@
+<script lang="ts">
+import {
+  Button,
+  coreApi,
+  EmptyState,
+  Field,
+  Input,
+  keys,
+  navigation,
+  SettingsPage,
+  SettingsSection,
+  Skeleton,
+  session,
+  toast,
+} from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { MODULE_ID } from '../../contract/models.js'
+import { InventorySettings } from '../../contract/settings.js'
+import type { CoreApi } from '../core-api.js'
+import { errorMessage } from '../errors.js'
+import { t } from '../i18n.js'
+
+/**
+ * Everything Inventory keeps at workspace level: what an asset tag looks like, and when the two
+ * nightly sweeps say something.
+ *
+ * `assetCodePrefix` and `assetCodePad` are enforced by the server on every `assets.create`, and
+ * `settingsPages` was `[]` — so the module declared two settings it honoured and gave nobody, at
+ * any permission level, a way to change either. A setting the server obeys and no screen exposes is
+ * a hard-coded value with extra steps. `warrantyNoticeDays` and `repairOverdueDays` arrive with the
+ * jobs that read them and are on this page in the same change, so that mistake is not repeated in
+ * the other direction.
+ *
+ * Settings live in core, not in this module's own schema, so they are read from
+ * `workspaces.modules.list` and written with `workspaces.modules.updateSettings` — the same
+ * mechanism HR's settings use, and the reason this module needs no settings table.
+ *
+ * **The write carries the whole `InventorySettings` object.** Core merges a partial write, so
+ * sending a subset would be safe — but this page owns the schema, and sending it whole is what
+ * makes the round trip self-evident. It is also why the repair window is sent from `stored` when
+ * the workspace has the capability off and its field is not on screen: a value nobody was shown is
+ * a value nobody meant to change.
+ */
+const api = coreApi<CoreApi>()
+const queryClient = useQueryClient()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+/** The permission core actually enforces on `workspaces.modules.updateSettings`. */
+const canManage = $derived(session.can('core.modules.manage'))
+
+/**
+ * Whether this workspace records repairs at all.
+ *
+ * Read from the session — the set the *server* resolved, with defaults applied, `required` forced
+ * on and anything whose dependency is off pruned — for the reason `AssetDetailPanel` gives: working
+ * the closure out again here would be a second implementation of it, and two implementations
+ * eventually disagree. A workspace with `repairs` off never sees the overdue window, because the
+ * sweep behind it asks the same question first and does nothing.
+ */
+const hasRepairs = $derived(session.hasCapability(MODULE_ID, 'repairs'))
+
+const modulesQuery = createQuery(() => ({
+  queryKey: keys.modules(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.workspaces.modules.list({ workspaceId }),
+}))
+
+const entry = $derived(modulesQuery.data?.find((m) => m.manifest.id === 'inventory'))
+
+/**
+ * What is stored, with the schema's defaults applied.
+ *
+ * `safeParse` rather than `parse`: a settings blob written before a field existed must not take the
+ * page down, and every field has a default, so the fallback is the shape a new workspace has. That
+ * is not hypothetical any more — every workspace that saved this page before the two notice windows
+ * existed has a blob with neither in it.
+ */
+const stored = $derived.by(() => {
+  const parsed = InventorySettings.safeParse(entry?.state.settings ?? {})
+  return parsed.success ? parsed.data : InventorySettings.parse({})
+})
+
+let prefix = $state('')
+/**
+ * Held as text, not as a number: an input somebody is half-way through clearing is empty, and
+ * `bind:value` on a number input turns that into `undefined` — which reads as "no change" and would
+ * save the old value behind their back.
+ */
+let padText = $state('')
+/** The two notice windows, as text and for exactly the same reason. */
+let warrantyDaysText = $state('')
+let repairDaysText = $state('')
+
+/**
+ * What the form was last filled from, so the effect below can tell "already seeded" from
+ * "the server now says something different".
+ *
+ * A plain `loaded` boolean cannot tell those apart, and that difference is a bug rather than a
+ * nicety: re-arming it after a save re-runs the effect on the **next Svelte flush**, long before
+ * the refetch resolves, so the form was re-seeded from the *pre-save* cached value and then left
+ * alone when the real one arrived. An admin saw a green "saved" toast and watched the field snap
+ * back to what it had been — and saving again wrote the old value over the new one.
+ */
+let seededFrom = $state<string | null>(null)
+const fingerprint = $derived(
+  [stored.assetCodePrefix, stored.assetCodePad, stored.warrantyNoticeDays, stored.repairOverdueDays].join(
+    ' ',
+  ),
+)
+const loaded = $derived(seededFrom !== null)
+
+$effect(() => {
+  if (!entry || seededFrom === fingerprint) return
+  prefix = stored.assetCodePrefix
+  padText = String(stored.assetCodePad)
+  warrantyDaysText = String(stored.warrantyNoticeDays)
+  repairDaysText = String(stored.repairOverdueDays)
+  seededFrom = fingerprint
+})
+
+/** Discard and re-seed are the same act: drop the edits and let the effect above refill them. */
+function discard() {
+  seededFrom = null
+}
+
+/**
+ * A Persian keyboard produces ۱۲۳ and an Arabic one ١٢٣, and `Number` reads neither — so somebody
+ * typing the digits of their own language would be told their input is not a whole number.
+ */
+const toLatinDigits = (value: string) =>
+  value
+    .replace(/[٠-٩]/g, (d) => String(d.charCodeAt(0) - 0x0660))
+    .replace(/[۰-۹]/g, (d) => String(d.charCodeAt(0) - 0x06f0))
+
+/** A whole number of days inside the range the contract accepts, or NaN. */
+const days = (text: string): number => {
+  const digits = toLatinDigits(text.trim())
+  if (!/^\d{1,3}$/.test(digits)) return Number.NaN
+  const value = Number(digits)
+  return value >= 1 && value <= 365 ? value : Number.NaN
+}
+
+const prefixError = $derived(prefix.length > 8 ? t('settings_prefix_too_long') : null)
+
+const padDigits = $derived(toLatinDigits(padText.trim()))
+const pad = $derived(/^\d{1,2}$/.test(padDigits) ? Number(padDigits) : Number.NaN)
+const padError = $derived(pad >= 1 && pad <= 10 ? null : t('settings_pad_invalid'))
+
+const warrantyDays = $derived(days(warrantyDaysText))
+const warrantyError = $derived(Number.isNaN(warrantyDays) ? t('settings_days_invalid') : null)
+
+/**
+ * The repair window is only validated when it is on screen.
+ *
+ * A workspace with `repairs` off never edits it, and holding the Save button hostage to a field
+ * nobody can see would be a form that cannot be submitted for a reason it does not show.
+ */
+const repairDays = $derived(days(repairDaysText))
+const repairError = $derived(hasRepairs && Number.isNaN(repairDays) ? t('settings_days_invalid') : null)
+
+const valid = $derived(!prefixError && !padError && !warrantyError && !repairError)
+const dirty = $derived(
+  loaded &&
+    (prefix !== stored.assetCodePrefix ||
+      pad !== stored.assetCodePad ||
+      warrantyDays !== stored.warrantyNoticeDays ||
+      (hasRepairs && repairDays !== stored.repairOverdueDays)),
+)
+
+/**
+ * A shape, not a promise about the next number.
+ *
+ * The counter is a row in `mod_inventory.counters` rather than a setting — a number an
+ * administrator can edit is a number that produces a duplicate tag — so this page does not know
+ * what comes next and does not claim to. 42 is a sample that makes the padding visible.
+ */
+const EXAMPLE_NUMBER = 42
+const example = $derived(Number.isNaN(pad) ? '—' : `${prefix}${String(EXAMPLE_NUMBER).padStart(pad, '0')}`)
+
+let saving = $state(false)
+let saveError = $state<string | null>(null)
+
+const save = createMutation(() => ({
+  mutationFn: () =>
+    api.workspaces.modules.updateSettings({
+      workspaceId,
+      moduleId: 'inventory',
+      // Every field `InventorySettings` declares, which is what makes the round trip self-evident:
+      // nothing here can be a field somebody forgot to carry forward. Adding a field to the schema
+      // means adding it here, or core's merge silently decides its value instead of this page.
+      settings: {
+        assetCodePrefix: prefix,
+        assetCodePad: pad,
+        warrantyNoticeDays: warrantyDays,
+        // From `stored` when the field was never on screen: a workspace with `repairs` off must
+        // keep whatever it had rather than have this page decide for it.
+        repairOverdueDays: hasRepairs ? repairDays : stored.repairOverdueDays,
+      },
+    }),
+  onSuccess: () => {
+    saveError = null
+    // Only invalidate. The form already holds what was just sent, so re-seeding it here would seed
+    // from the cache as it is *now* — the pre-save value. When the refetch lands, `fingerprint`
+    // changes and the effect above re-seeds from what the server actually stored, which is the
+    // truth. Until then the form shows what the admin typed, which is the next best thing.
+    void queryClient.invalidateQueries({ queryKey: keys.modules(workspaceId) })
+    toast.success(t('settings_saved'))
+  },
+  // `err.message` is a sentence core wrote, in English, and this page's own reader chose
+  // otherwise. `errors.ts` gives it the sentence for whatever class of refusal it was — a
+  // capability switched off, a permission missing, a validation the form did not catch.
+  onError: (err: unknown) => {
+    saveError = errorMessage(err, t)
+  },
+  onSettled: () => {
+    saving = false
+  },
+}))
+
+/**
+ * `disabled={save.isPending}` reaches the button a render too late, and two quick clicks are one
+ * render apart — so the guard is a plain flag set in the same tick as the click. It is deliberately
+ * not in the `disabled` expression: disabling the control somebody is standing on blurs it and
+ * hands focus nowhere, and `loading` already says "busy" through `aria-busy`.
+ */
+function requestSave() {
+  if (saving || !dirty || !valid) return
+  saving = true
+  saveError = null
+  save.mutate()
+}
+</script>
+
+{#snippet saveBar()}
+  <Button size="sm" variant="secondary" onclick={discard} disabled={!dirty}>
+    {t('common.discard')}
+  </Button>
+  <Button size="sm" onclick={requestSave} disabled={!dirty || !valid} loading={saving}>
+    {t('common.save')}
+  </Button>
+{/snippet}
+
+<SettingsPage title={t('settings_general')} description={t('settings_general_desc')}>
+  {#if modulesQuery.isPending}
+    <Skeleton height="220px" radius="10px" />
+  {:else if modulesQuery.isError}
+    <EmptyState icon="triangle-alert" title={t('settings_error')} description={t('common.error')}>
+      {#snippet actions()}
+        <Button variant="secondary" onclick={() => void modulesQuery.refetch()}>
+          {t('common.retry')}
+        </Button>
+      {/snippet}
+    </EmptyState>
+  {:else if !entry}
+    <EmptyState icon="briefcase" title={t('settings_not_enabled')} />
+  {:else}
+    {#if !canManage}
+      <p class="readonly">{t('settings_readonly')}</p>
+    {/if}
+
+    <SettingsSection title={t('settings_numbering')} description={t('settings_numbering_desc')}>
+      <div class="rows">
+        <Field inline label={t('settings_prefix')} hint={t('settings_prefix_hint')}>
+          {#snippet children(id)}
+            <div class="narrow">
+              <Input
+                {id}
+                bind:value={prefix}
+                maxlength={8}
+                mono
+                disabled={!canManage}
+                error={prefixError}
+              />
+            </div>
+          {/snippet}
+        </Field>
+
+        <Field inline label={t('settings_pad')} hint={t('settings_pad_hint')}>
+          {#snippet children(id)}
+            <div class="narrow">
+              <Input
+                {id}
+                bind:value={padText}
+                inputmode="numeric"
+                maxlength={2}
+                mono
+                disabled={!canManage}
+                error={padError}
+              />
+            </div>
+          {/snippet}
+        </Field>
+
+        <div class="example">
+          <span class="example-label">{t('settings_preview')}</span>
+          <!--
+            Interpolated as text on purpose. A tag is an identifier the server builds by
+            concatenation, so a Persian reader has to see the same characters that are printed on
+            the sticker — this is the one place on the page where localised digits would be wrong.
+          -->
+          <span class="example-value">{example}</span>
+        </div>
+      </div>
+    </SettingsSection>
+
+    <!--
+      One save bar, on the last section, because there is one settings object and one request. Two
+      bars would suggest two independent saves and then write both halves anyway.
+    -->
+    <SettingsSection
+      title={t('settings_notices')}
+      description={t('settings_notices_desc')}
+      footer={canManage ? saveBar : undefined}
+    >
+      <div class="rows">
+        <Field inline label={t('settings_warranty_days')} hint={t('settings_warranty_days_hint')}>
+          {#snippet children(id)}
+            <div class="narrow">
+              <Input
+                {id}
+                bind:value={warrantyDaysText}
+                inputmode="numeric"
+                maxlength={3}
+                mono
+                disabled={!canManage}
+                error={warrantyError}
+              />
+            </div>
+          {/snippet}
+        </Field>
+
+        {#if hasRepairs}
+          <Field inline label={t('settings_repair_days')} hint={t('settings_repair_days_hint')}>
+            {#snippet children(id)}
+              <div class="narrow">
+                <Input
+                  {id}
+                  bind:value={repairDaysText}
+                  inputmode="numeric"
+                  maxlength={3}
+                  mono
+                  disabled={!canManage}
+                  error={repairError}
+                />
+              </div>
+            {/snippet}
+          </Field>
+        {/if}
+      </div>
+    </SettingsSection>
+
+    {#if saveError}
+      <p class="save-error" role="alert">{saveError}</p>
+    {/if}
+  {/if}
+</SettingsPage>
+
+<style>
+.readonly {
+  margin: 0;
+  font-size: 12.5px;
+  /* A colour, not opacity: opacity fades text against the page whatever token it names. */
+  color: var(--kern-ink-500);
+}
+.rows {
+  display: grid;
+  gap: 14px;
+}
+.narrow {
+  max-inline-size: 180px;
+}
+.example {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  padding: 10px 12px;
+  border-radius: var(--kern-r-md);
+  background: var(--kern-surface-chip);
+}
+.example-label {
+  font-size: 12.5px;
+  color: var(--kern-ink-500);
+}
+.example-value {
+  font-family: var(--kern-font-mono);
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--kern-ink-900);
+  /* A tag is read character by character, so the glyphs line up rather than reflow. */
+  font-variant-numeric: tabular-nums;
+  /* The identifier stays left-to-right inside a Persian or Arabic sentence. */
+  direction: ltr;
+  unicode-bidi: isolate;
+}
+.save-error {
+  margin: 0;
+  font-size: 12.5px;
+  color: var(--kern-danger);
+}
+</style>

package/src/client/status.ts

@@ -0,0 +1,29 @@
+import type { BadgeTone } from '@kernhq/ui'
+
+/**
+ * What colour a status wears, in the one place both screens read it from.
+ *
+ * The list and the detail panel show the same badge for the same row, and a `switch` copied into
+ * two components is two switches that drift — the day `reserved` gets its own colour, one of them
+ * changes. `import type` is erased at build time, so this file still pulls no runtime dependency on
+ * `@kernhq/ui` and stays unit-testable.
+ *
+ * The tones say what a reader needs to act on rather than what is "good": `in_stock` is the
+ * ordinary resting state, `lost` is the one somebody has to do something about, and an archived row
+ * is drawn grey by the screens without asking here — it is not a status, it is the absence of one.
+ */
+export function statusTone(status: string): BadgeTone {
+  switch (status) {
+    case 'assigned':
+    case 'reserved':
+      return 'info'
+    case 'under_repair':
+      return 'warning'
+    case 'lost':
+      return 'danger'
+    case 'retired':
+      return 'grey'
+    default:
+      return 'success'
+  }
+}

package/src/client/timeline.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest'
+import { AssetInput } from '../contract/models.js'
+import { en } from './messages.js'
+import {
+  actionKey,
+  changeLineKind,
+  changeShape,
+  fieldKey,
+  isKnownAction,
+  isLongText,
+  isOpaque,
+  noteOf,
+  personIdOf,
+} from './timeline.js'
+
+/**
+ * The decisions behind a readable timeline, checked where they can be checked.
+ *
+ * `Timeline.svelte` supplies the words; every judgement it makes — which sentence, about whom, with
+ * what label — is in `timeline.ts`, and each one has a right answer. The three that matter are the
+ * ones nothing else can catch:
+ *
+ *   1. an action the catalogue has no sentence for must not be described as something else;
+ *   2. a field added to the contract must not reach a screen as its own column name;
+ *   3. a return names who gave it back, not who received it — they are different keys in `data`,
+ *      and reading the wrong one renders "took it back from nobody".
+ */
+describe('actionKey', () => {
+  it('names a key the catalogue actually has, for every action the server writes', () => {
+    // Exactly what `AssetService` and `CustodyService` write today.
+    for (const action of [
+      'created',
+      'updated',
+      'assigned',
+      'transferred',
+      'returned',
+      'retired',
+      'restored',
+    ]) {
+      expect({ action, key: actionKey(action) }).toEqual({ action, key: `history_${action}` })
+      expect({ action, has: `inventory.${actionKey(action)}` in en }).toEqual({ action, has: true })
+    }
+  })
+
+  it('falls back honestly for an action written by a newer image', () => {
+    // Reservations and stock counts write their own actions, and a browser tab open across a
+    // deploy will meet one. "Somebody changed it — reserved" is true; "edited it" would not be.
+    expect(actionKey('reserved')).toBe('history_unknown')
+    expect(isKnownAction('reserved')).toBe(false)
+    expect('inventory.history_unknown' in en).toBe(true)
+  })
+
+  it('phrases what repairs and attachments write, rather than falling back', () => {
+    // These four were the fallback's example until the change that made them real. An action this
+    // client *does* know must never render as "changed it — repair_logged".
+    for (const action of ['repair_logged', 'repair_completed', 'attachment_added', 'attachment_removed']) {
+      expect({ action, key: actionKey(action) }).toEqual({ action, key: `history_${action}` })
+      expect({ action, has: `inventory.${actionKey(action)}` in en }).toEqual({ action, has: true })
+    }
+  })
+})
+
+describe('fieldKey', () => {
+  it('labels every field the contract lets somebody edit', () => {
+    // `AssetInput` is the whole of what `assets.update` accepts, and therefore the whole of what a
+    // stored diff can name. A field added there with no key here would print `warrantyUntil` in the
+    // middle of a Persian sentence.
+    for (const field of Object.keys(AssetInput.shape)) {
+      const key = fieldKey(field)
+      expect({ field, key }).not.toEqual({ field, key: null })
+      expect({ field, has: `inventory.${key}` in en }).toEqual({ field, has: true })
+    }
+  })
+
+  it('says it does not know a field rather than guessing at one', () => {
+    expect(fieldKey('somethingNewer')).toBe(null)
+  })
+})
+
+describe('changeShape', () => {
+  it('tells filling a field in from clearing it from moving it', () => {
+    expect(changeShape(null, 'Desk 4')).toBe('set')
+    expect(changeShape('Desk 4', null)).toBe('cleared')
+    expect(changeShape('Desk 4', 'Desk 5')).toBe('changed')
+  })
+
+  it('treats an empty string as absent, because that is what clearing a description stores', () => {
+    // `description` is `not null` in the database, so emptying it writes `''` — and "changed from
+    // to x" is a sentence with a hole in it.
+    expect(changeShape('', 'A note')).toBe('set')
+    expect(changeShape('A note', '')).toBe('cleared')
+  })
+})
+
+describe('personIdOf', () => {
+  it('reads the recipient for a handover and the giver for a return', () => {
+    expect(personIdOf('assigned', { userId: 'ada' })).toBe('ada')
+    expect(personIdOf('transferred', { userId: 'bruno', previousUserId: 'ada' })).toBe('bruno')
+    // The one that would silently read "nobody": `returned` stores no `userId` at all.
+    expect(personIdOf('returned', { previousUserId: 'ada' })).toBe('ada')
+  })
+
+  it('has no person for an entry that is not about one', () => {
+    expect(personIdOf('created', {})).toBe(null)
+    expect(personIdOf('assigned', { userId: 123 })).toBe(null)
+  })
+})
+
+describe('noteOf', () => {
+  it('takes a note only when somebody actually wrote one', () => {
+    expect(noteOf({ note: '  For the Berlin trip ' })).toBe('For the Berlin trip')
+    expect(noteOf({ note: '   ' })).toBe(null)
+    expect(noteOf({})).toBe(null)
+  })
+})
+
+/**
+ * The decision that keeps eight kilobytes of somebody's prose out of a row of the panel.
+ *
+ * `description` is `z.string().max(8000)` in the contract, and the timeline read a change to it out
+ * as "Description changed from … to …" with both versions inline — so one edit to one paragraph
+ * pushed every entry below it off a 440px sheet. Nothing failed: the string was correct, the
+ * translation was correct, and the row was unusable.
+ */
+describe('changeLineKind', () => {
+  it('says only that a description changed, and never what it says', () => {
+    const long = 'x'.repeat(8000)
+    expect(changeLineKind('description', 'before', long)).toBe('text_changed')
+    // Filling one in for the first time is the same sentence once the value is gone: two keys
+    // saying "Description changed" would be two translations to keep in step for no gain.
+    expect(changeLineKind('description', null, long)).toBe('text_changed')
+  })
+
+  it('decides on the field, not on how long the value happens to be today', () => {
+    // A short description is still prose. Branching on length would make the timeline's shape
+    // depend on what somebody typed, so the same field would render two different ways.
+    expect(changeLineKind('description', 'a', 'b')).toBe('text_changed')
+    expect(isLongText('description')).toBe(true)
+    expect(isLongText('location')).toBe(false)
+  })
+
+  it('still says "cleared" when a description is emptied — there is nothing to disclose', () => {
+    // `description` is `not null` in the database, so clearing it stores `''`.
+    expect(changeLineKind('description', 'A note', '')).toBe('cleared')
+    expect(changeLineKind('description', 'A note', null)).toBe('cleared')
+  })
+
+  it('keeps reading an ordinary field out, which is the whole point of a timeline', () => {
+    expect(changeLineKind('location', null, 'Desk 4')).toBe('set')
+    expect(changeLineKind('location', 'Desk 4', 'Desk 5')).toBe('changed')
+    expect(changeLineKind('location', 'Desk 4', null)).toBe('cleared')
+  })
+
+  it('reports an opaque id as a replacement rather than printing a uuid', () => {
+    expect(isOpaque('photoFileId')).toBe(true)
+    expect(changeLineKind('photoFileId', 'a', 'b')).toBe('replaced')
+    // Removing the photo is still "cleared": there is no id to avoid printing.
+    expect(changeLineKind('photoFileId', 'a', null)).toBe('cleared')
+  })
+
+  it('names a key the catalogue has, for every kind it can return', () => {
+    const keys = {
+      cleared: 'history_cleared',
+      replaced: 'history_replaced',
+      set: 'history_set',
+      changed: 'history_changed',
+      text_changed: 'history_text_changed',
+    }
+    for (const key of Object.values(keys))
+      expect({ key, has: `inventory.${key}` in en }).toEqual({ key, has: true })
+    // And the disclosure's own three, which `TimelineText.svelte` reads.
+    for (const key of ['history_show_text', 'history_text_before', 'history_text_after'])
+      expect({ key, has: `inventory.${key}` in en }).toEqual({ key, has: true })
+  })
+})