@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/query.ts

@@ -3,10 +3,59 @@
  *
  * `[module, entity, …scope]`, so a realtime `change` event invalidates precisely what it touched.
  * Filters are part of the key wherever a screen can ask the same question two ways — a cached list
- * for "all" must not be served when somebody asked for "assigned".
+ * for "all" must not be served when somebody asked for "assigned", and the archived list is a
+ * different question from the live one rather than the same answer filtered afterwards.
+ *
+ * **The entity segment is singular, and that is not a style choice.** `realtime.svelte.ts`
+ * invalidates `[module, entity]` with whatever the server put in the change event, and
+ * `src/server/router.ts` emits `entity: 'asset'` — so the prefix that arrives is
+ * `['inventory', 'asset']`. This file spelled the list key `['inventory', 'assets', …]`, which that
+ * prefix never matches: `partialMatchKey` compares segment by segment and `'assets' !== 'asset'`.
+ * The detail key was already singular, so a change refreshed the panel nobody was looking at while
+ * the list and the dashboard card behind it stayed stale until a reload. Every other module keys
+ * the list and the row off one singular entity name (`['tracker', 'issue', …]`); so does this one
+ * now.
+ *
+ * **The timeline and the custody list hang off the asset's own key**, one segment deeper. That is
+ * what lets custody announce itself as `entity: 'asset'` and refresh all four things it changed —
+ * the row, the list, the detail panel and both of its tabs — from one change event, because
+ * `partialMatchKey` matches on the prefix. A separate `['inventory', 'custody', …]` would need the
+ * server to emit a second entity for the same write.
  */
 export const inventoryKeys = {
+  /** Everything under this module, for the blunt invalidation after a write. */
+  all: ['inventory'] as const,
   assets: (ws: string, filters?: Record<string, unknown>) =>
-    filters ? (['inventory', 'assets', ws, filters] as const) : (['inventory', 'assets', ws] as const),
+    filters ? (['inventory', 'asset', ws, filters] as const) : (['inventory', 'asset', ws] as const),
   asset: (ws: string, id: string) => ['inventory', 'asset', ws, id] as const,
+  /** The asset's own timeline. Under the asset, so one `asset` change refreshes it. */
+  assetHistory: (ws: string, id: string) => ['inventory', 'asset', ws, id, 'history'] as const,
+  /** Every custody period for one asset. Under the asset, for the same reason. */
+  assetCustody: (ws: string, id: string) => ['inventory', 'asset', ws, id, 'custody'] as const,
+  /** One asset's repairs. Under the asset, so a repair announced as an `asset` change refreshes it. */
+  assetRepairs: (ws: string, id: string) => ['inventory', 'asset', ws, id, 'repairs'] as const,
+  /** One asset's files, its repairs' included — the panel groups them, so there is one key. */
+  assetAttachments: (ws: string, id: string) => ['inventory', 'asset', ws, id, 'attachments'] as const,
+  /**
+   * The workspace's repairs, which belong to no single asset — the "what is away right now" card.
+   *
+   * Its own entity, because it cannot hang under one asset's key: `src/server/router.ts` therefore
+   * announces a repair twice, once as the asset that changed and once as the repair itself.
+   */
+  repairs: (ws: string, filters?: Record<string, unknown>) =>
+    filters ? (['inventory', 'repair', ws, filters] as const) : (['inventory', 'repair', ws] as const),
+  /**
+   * The register in numbers.
+   *
+   * Under the **asset** prefix on purpose, one segment deep: every number it holds is a count of
+   * assets, so every write that changes one of those counts already announces `entity: 'asset'` and
+   * this is refreshed by the same event. `'stats'` cannot collide with `asset(ws, id)` — that
+   * segment is always a uuid.
+   */
+  stats: (ws: string) => ['inventory', 'asset', ws, 'stats'] as const,
+  /**
+   * The workspace's categories. Its own entity because it has its own change event: a rename
+   * touches every asset row on screen, and `src/server/router.ts` therefore emits both.
+   */
+  categories: (ws: string, archived = false) => ['inventory', 'category', ws, { archived }] as const,
 }

package/src/client/repairs.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+import { repairActions } from './repairs.js'
+
+/**
+ * What the Repairs section is allowed to offer.
+ *
+ * A decision rather than rendering, and wrong in a way nothing else would catch: a *Send for repair*
+ * button on an item that is already at a repairer produces a 409 every single time it is pressed —
+ * the unique index refuses the second open repair — so the interface must not offer it at all.
+ */
+describe('repairActions', () => {
+  it('offers sending it away when nothing is open', () => {
+    expect(repairActions({ open: false, archived: false, may: true })).toEqual(['create'])
+  })
+
+  it('offers completing and correcting while one is open, and never a second send', () => {
+    const actions = repairActions({ open: true, archived: false, may: true })
+    expect(actions).toEqual(['complete', 'edit'])
+    // The one combination that would conflict on every press.
+    expect(actions).not.toContain('create')
+  })
+
+  it('offers nothing without the permission — hidden, not disabled', () => {
+    expect(repairActions({ open: false, archived: false, may: false })).toEqual([])
+    expect(repairActions({ open: true, archived: false, may: false })).toEqual([])
+  })
+
+  it('offers nothing new on an archived item, which the server refuses anyway', () => {
+    expect(repairActions({ open: false, archived: true, may: true })).toEqual([])
+  })
+
+  it('keeps the way out of an open repair reachable even on an archived item', () => {
+    // Archiving is refused while a repair is open, so this state should be unreachable — and if
+    // the data ever says otherwise, hiding *complete* would leave the item stuck at `under_repair`
+    // for ever with no control that could finish it.
+    expect(repairActions({ open: true, archived: true, may: true })).toEqual(['complete', 'edit'])
+  })
+})

package/src/client/repairs.ts

@@ -0,0 +1,38 @@
+/**
+ * What a repair section can actually offer right now.
+ *
+ * Three verbs and not one, because the server has three procedures and refuses the wrong one with
+ * its own sentence: sending something that is already at a repairer is a mistake worth naming, and
+ * completing a repair that is already finished is a different one. A button that always produces a
+ * conflict is a door that will not open.
+ *
+ * A `.ts` file rather than a `const` inside the component, for the reason `custody.ts`, `price.ts`
+ * and `timeline.ts` are: this is a fact with a right answer, and a `.svelte` file drags a compiler
+ * behind it and cannot be unit-tested. It also has to be a plain module because the type is shared
+ * with the dialog — a type exported from a component's instance script is a prop, not a type.
+ */
+export type RepairAction = 'create' | 'edit' | 'complete'
+
+export interface RepairState {
+  /** A repair for this asset with no return date — at most one exists, by unique index. */
+  open: boolean
+  /** The workspace has taken the item out of the register; the server refuses a new repair. */
+  archived: boolean
+  /** This person holds `inventory.repair.manage`. */
+  may: boolean
+}
+
+/**
+ * What to offer, in the order the controls appear.
+ *
+ * Empty for somebody without the permission — hide what a person may never do — and empty for an
+ * archived item with nothing open, where the section says *why* in one sentence instead. An
+ * archived item whose repair is still open keeps `complete` and `edit`: archiving is refused while
+ * a repair is open, so the only way to be in that state is to have archived it first and opened the
+ * repair never — but if the data ever says otherwise, the way out has to stay reachable.
+ */
+export function repairActions(state: RepairState): RepairAction[] {
+  if (!state.may) return []
+  if (state.open) return ['complete', 'edit']
+  return state.archived ? [] : ['create']
+}

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>