@kernhq/module-inventory 0.2.0 → 0.3.0

package/src/client/settings/CategoriesSettings.svelte

@@ -0,0 +1,421 @@
+<script lang="ts">
+import {
+  Badge,
+  Button,
+  Dialog,
+  DropdownMenu,
+  EmptyState,
+  Field,
+  IconButton,
+  Input,
+  type MenuItem,
+  navigation,
+  SettingsPage,
+  SettingsSection,
+  Skeleton,
+  Switch,
+  session,
+  Table,
+  TableCell,
+  TableHeader,
+  TableRow,
+  toast,
+} from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import type { Category } from '../../contract/index.js'
+import { getInventoryApi } from '../api-instance.js'
+import { isolated } from '../bidi.js'
+import { errorMessage } from '../errors.js'
+import { t } from '../i18n.js'
+import { INVENTORY_PERMISSIONS } from '../permissions.js'
+import { inventoryKeys } from '../query.js'
+
+/**
+ * How a workspace groups what it owns.
+ *
+ * `assets.list` has taken a `categoryId` filter since the module existed and nothing could create a
+ * category, so the filter had exactly one possible answer — this page is the other half of it.
+ *
+ * **Nothing here deletes.** `assets.category_id` carries no foreign key, so removing a row would
+ * leave every asset filed under it pointing at nothing: a blank column, and a timeline entry saying
+ * the category changed *to* a name it can no longer print. Archiving takes it out of every picker
+ * and every filter and leaves each asset able to say what it is; the same procedure restores it.
+ */
+const api = getInventoryApi()
+const queryClient = useQueryClient()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspaceId = $derived(session.workspaces.find((w) => w.slug === workspaceSlug)?.id ?? '')
+
+/**
+ * The permission the server enforces on every write here.
+ *
+ * The page is already gated on it in `module.ts`, so somebody without it never sees the entry —
+ * but a settings URL can be typed, and a read-only view of the list is a better answer than a form
+ * whose every button 403s.
+ */
+const canManage = $derived(session.can(INVENTORY_PERMISSIONS.categories))
+
+let showArchived = $state(false)
+
+/**
+ * One query for every category, archived ones included, filtered here.
+ *
+ * Two things come out of that. It is the key `AssetsPage` and `AssetDetailPanel` already use, so
+ * arriving at this page after either of them costs no request — and, the reason it changed, it is
+ * the only way this page can tell **"no categories yet"** from **"every category is archived"**.
+ * With `archived: showArchived` in the request the two are the same empty array, and the page told
+ * a workspace that had archived all five of its categories that it had never made one — beside a
+ * *New category* button, with the row that would have fixed it one switch away.
+ */
+const categoriesQuery = createQuery(() => ({
+  queryKey: inventoryKeys.categories(workspaceId, true),
+  queryFn: () => api.categories.list({ workspaceId, archived: true }),
+  enabled: Boolean(workspaceId),
+}))
+const everything = $derived<Category[]>(categoriesQuery.data ?? [])
+const categories = $derived(showArchived ? everything : everything.filter((row) => !row.archivedAt))
+/** Rows exist, and the switch is hiding all of them. A different sentence from having none. */
+const allArchived = $derived(everything.length > 0 && categories.length === 0)
+
+// ------------------------------------------------------------------ the add / rename dialog
+
+let editing = $state<Category | null>(null)
+let dialogOpen = $state(false)
+let name = $state('')
+let orderText = $state('')
+
+function openCreate() {
+  editing = null
+  name = ''
+  orderText = '0'
+  dialogOpen = true
+}
+
+function openEdit(category: Category) {
+  editing = category
+  name = category.name
+  orderText = String(category.order)
+  dialogOpen = true
+}
+
+/**
+ * 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))
+
+const order = $derived.by(() => {
+  const digits = toLatinDigits(orderText.trim())
+  return /^\d{1,4}$/.test(digits) ? Number(digits) : Number.NaN
+})
+/**
+ * A hint and an error are two different sentences, and this field passed the hint as both.
+ *
+ * `hint` explains how positions sort — "Lower comes first. Categories sharing a position fall back
+ * to their names." — and typing `x` restated exactly that, in red, under `aria-invalid`. It told
+ * somebody nothing about what was wrong with what they had typed, and it made the field's ordinary
+ * hint look like a failure the first time they read it. The error says what this box will accept.
+ */
+const orderError = $derived(Number.isNaN(order) ? t('category_order_invalid') : null)
+const canSubmit = $derived(canManage && Boolean(name.trim()) && !Number.isNaN(order))
+
+/** Set in the same tick as the click: `disabled={mutation.isPending}` is one render too late. */
+let saving = $state(false)
+
+const save = createMutation(() => ({
+  mutationFn: () => {
+    const row = editing
+    const values = { name: name.trim(), order }
+    return row
+      ? api.categories.update({ workspaceId, categoryId: row.id, ...values })
+      : api.categories.create({ workspaceId, ...values })
+  },
+  onSuccess: (saved: Category) => {
+    toast.success(
+      t(editing ? 'category_updated_toast' : 'category_created_toast', isolated({ name: saved.name })),
+    )
+    void queryClient.invalidateQueries({ queryKey: inventoryKeys.all })
+    dialogOpen = false
+  },
+  // The server's sentence is the actionable one and it is in English — "This workspace already has
+  // a category called “Laptops”." was shown verbatim to a reader who chose Persian. The token it
+  // carries, `inventory.category.name_taken`, is the part a client can translate; the name is on
+  // screen in the box directly above the message, so the sentence does not need to repeat it.
+  onError: (error: unknown) => toast.error(errorMessage(error, t)),
+  onSettled: () => {
+    saving = false
+  },
+}))
+
+function submit() {
+  if (saving || !canSubmit) return
+  saving = true
+  save.mutate()
+}
+
+// ------------------------------------------------------------------------ archive and restore
+
+let archiving = $state<Category | null>(null)
+let acting = $state(false)
+
+interface ArchiveVars {
+  categoryId: string
+  archived: boolean
+  name: string
+}
+
+const setArchived = createMutation(() => ({
+  mutationFn: (vars: ArchiveVars) =>
+    api.categories.archive({ workspaceId, categoryId: vars.categoryId, archived: vars.archived }),
+  onSuccess: (_saved: Category, vars: ArchiveVars) => {
+    toast.success(
+      t(vars.archived ? 'category_archived_toast' : 'category_restored_toast', isolated({ name: vars.name })),
+    )
+    void queryClient.invalidateQueries({ queryKey: inventoryKeys.all })
+    archiving = null
+  },
+  onError: (error: unknown) => toast.error(errorMessage(error, t)),
+  onSettled: () => {
+    acting = false
+  },
+}))
+
+function confirmArchive() {
+  const target = archiving
+  if (!target || acting) return
+  acting = true
+  setArchived.mutate({ categoryId: target.id, archived: true, name: target.name })
+}
+
+function restore(category: Category) {
+  if (acting) return
+  acting = true
+  setArchived.mutate({ categoryId: category.id, archived: false, name: category.name })
+}
+
+/**
+ * Restoring takes nothing away and needs no confirmation; archiving states what happens to the
+ * assets already filed under it. Hidden rather than disabled without the permission.
+ */
+function actionsFor(category: Category): MenuItem[] {
+  const items: MenuItem[] = [
+    { label: t('common.edit'), icon: 'square-pen', onSelect: () => openEdit(category) },
+  ]
+  if (category.archivedAt) {
+    items.push({ label: t('restore'), icon: 'rotate-ccw', onSelect: () => restore(category) })
+  } else {
+    items.push({ type: 'separator' })
+    items.push({
+      label: t('common.archive'),
+      icon: 'archive',
+      danger: true,
+      onSelect: () => (archiving = category),
+    })
+  }
+  return items
+}
+
+const COLUMNS = $derived(canManage ? 'minmax(0, 1fr) 96px 44px' : 'minmax(0, 1fr) 96px')
+const SKELETON_ROWS = [0, 1, 2, 3]
+</script>
+
+<SettingsPage title={t('settings_categories')} description={t('settings_categories_desc')}>
+  {#snippet actions()}
+    {#if canManage}
+      <Button size="sm" icon="plus" onclick={openCreate}>{t('category_new')}</Button>
+    {/if}
+  {/snippet}
+
+  <SettingsSection flush>
+    <div class="bar">
+      <Switch bind:checked={showArchived} size="sm" label={t('show_archived')} />
+    </div>
+
+    {#if categoriesQuery.isPending}
+      <div class="skeleton">
+        {#each SKELETON_ROWS as row (row)}
+          <div class="srow" style:grid-template-columns={COLUMNS}>
+            <Skeleton height="12px" width="52%" />
+            <Skeleton height="12px" width="30%" />
+            {#if canManage}<Skeleton height="12px" width="16px" />{/if}
+          </div>
+        {/each}
+      </div>
+    {:else if categoriesQuery.isError}
+      <EmptyState icon="triangle-alert" title={t('categories_error')} description={t('common.error')}>
+        {#snippet actions()}
+          <Button variant="secondary" onclick={() => void categoriesQuery.refetch()}>
+            {t('common.retry')}
+          </Button>
+        {/snippet}
+      </EmptyState>
+    {:else if allArchived}
+      <!--
+        Not "No categories yet": this workspace has categories and is looking at none of them. The
+        action is the one that fixes it — show the archived rows, which is where Restore lives —
+        rather than a New category button that would leave the archived ones exactly as they are.
+      -->
+      <EmptyState
+        icon="archive"
+        title={t('categories_all_archived')}
+        description={t('categories_all_archived_desc')}
+      >
+        {#snippet actions()}
+          <Button variant="secondary" onclick={() => (showArchived = true)}>
+            {t('show_archived')}
+          </Button>
+        {/snippet}
+      </EmptyState>
+    {:else if categories.length === 0}
+      <!--
+        Reachable, and worth keeping: `onWorkspaceEnabled` seeds five categories, but it only runs
+        when a workspace switches the module on — an instance upgraded with Inventory already
+        enabled never ran it, and neither does a workspace whose seeding half failed.
+      -->
+      <EmptyState icon="tag" title={t('categories_empty')} description={t('categories_empty_desc')}>
+        {#snippet actions()}
+          {#if canManage}
+            <Button onclick={openCreate}>{t('category_new')}</Button>
+          {/if}
+        {/snippet}
+      </EmptyState>
+    {:else}
+      <Table columns={COLUMNS} ariaLabel={t('settings_categories')}>
+        <TableHeader>
+          <TableCell header>{t('category')}</TableCell>
+          <TableCell header>{t('category_order')}</TableCell>
+          {#if canManage}<TableCell header end></TableCell>{/if}
+        </TableHeader>
+        {#each categories as category (category.id)}
+          <TableRow>
+            <TableCell>
+              <span class="cell">
+                <span class="name">{category.name}</span>
+                <!-- Only the archived state gets a badge. A "live" badge on every other row would
+                     be a column of the same word, and the one it would have to borrow —
+                     `status_in_stock` — describes an asset sitting in a cupboard, not a category. -->
+                {#if category.archivedAt}<Badge tone="grey">{t('archived')}</Badge>{/if}
+              </span>
+            </TableCell>
+            <TableCell><span class="muted">{category.order}</span></TableCell>
+            {#if canManage}
+              <TableCell end>
+                <DropdownMenu items={actionsFor(category)} align="end">
+                  {#snippet trigger(props)}
+                    <IconButton
+                      {...props}
+                      icon="ellipsis"
+                      size={28}
+                      label={t('row_actions', isolated({ name: category.name }))}
+                    />
+                  {/snippet}
+                </DropdownMenu>
+              </TableCell>
+            {/if}
+          </TableRow>
+        {/each}
+      </Table>
+    {/if}
+  </SettingsSection>
+</SettingsPage>
+
+<Dialog
+  bind:open={dialogOpen}
+  size="sm"
+  title={editing ? t('category_edit') : t('category_new')}
+>
+  <div class="form">
+    <Field label={t('category')} id="inv-cat-name" required hint={t('category_name_placeholder')}>
+      {#snippet children(id)}
+        <Input {id} bind:value={name} maxlength={120} />
+      {/snippet}
+    </Field>
+    <Field label={t('category_order')} id="inv-cat-order" hint={t('category_order_hint')}>
+      {#snippet children(id)}
+        <div class="narrow">
+          <Input {id} bind:value={orderText} inputmode="numeric" maxlength={4} mono error={orderError} />
+        </div>
+      {/snippet}
+    </Field>
+  </div>
+
+  {#snippet footer()}
+    <Button variant="ghost" onclick={() => (dialogOpen = false)}>{t('common.cancel')}</Button>
+    <Button onclick={submit} disabled={!canSubmit} loading={saving}>{t('common.save')}</Button>
+  {/snippet}
+</Dialog>
+
+<!-- States what happens to the assets already filed under it, rather than asking "Are you sure?". -->
+<Dialog
+  open={archiving !== null}
+  size="sm"
+  title={t('category_archive_title', isolated({ name: archiving?.name ?? '' }))}
+  onOpenChange={(next) => {
+    if (!next) archiving = null
+  }}
+>
+  <p class="dialog-body">{t('category_archive_body')}</p>
+  {#snippet footer()}
+    <Button variant="ghost" onclick={() => (archiving = null)}>{t('common.cancel')}</Button>
+    <Button variant="danger" onclick={confirmArchive} loading={acting}>{t('common.archive')}</Button>
+  {/snippet}
+</Dialog>
+
+<style>
+  .bar {
+    display: flex;
+    justify-content: flex-end;
+    padding: 10px 12px;
+  }
+  .cell {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-width: 0;
+  }
+  .name {
+    font-weight: 500;
+    color: var(--kern-ink-900);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    /* A value somebody typed decides its own direction: `plaintext` takes it from the value's
+       first strong character, so a Latin name inside a Persian screen reads left to right and
+       keeps its own trailing punctuation instead of donating it to the paragraph. */
+    unicode-bidi: plaintext;
+  }
+  .muted {
+    /* A colour rather than opacity, which fades text against the page whatever token it names. */
+    color: var(--kern-ink-500);
+    font-variant-numeric: tabular-nums;
+  }
+  .skeleton {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+  }
+  .srow {
+    display: grid;
+    align-items: center;
+    gap: 12px;
+    padding: 14px 12px;
+    border-bottom: 1px solid var(--kern-border-hairline);
+  }
+  .form {
+    display: grid;
+    gap: 14px;
+  }
+  .narrow {
+    max-inline-size: 140px;
+  }
+  .dialog-body {
+    margin: 0;
+    font-size: 13.5px;
+    line-height: 1.55;
+    color: var(--kern-ink-700);
+  }
+</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 })
+  })
+})