@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/components/Timeline.svelte

@@ -0,0 +1,347 @@
+<script lang="ts">
+import {
+  Avatar,
+  Button,
+  EmptyState,
+  formatDate,
+  formatDateTime,
+  messageLocale,
+  relativeTime,
+  Skeleton,
+} from '@kernhq/ui'
+import { createInfiniteQuery } from '@tanstack/svelte-query'
+import type { AssetHistoryEntry } from '../../contract/index.js'
+import { getInventoryApi } from '../api-instance.js'
+import { isolate, isolated } from '../bidi.js'
+import { t } from '../i18n.js'
+import type { Directory } from '../members.js'
+import { nameOf, resolveName } from '../members.js'
+import { formatPrice } from '../price.js'
+import { inventoryKeys } from '../query.js'
+import { actionKey, changeLineKind, fieldKey, noteOf, personIdOf, subjectOf } from '../timeline.js'
+import TimelineText from './TimelineText.svelte'
+
+/**
+ * An asset's own timeline, as sentences.
+ *
+ * `asset_history` stores `{ action, changes: [{field, from, to}], data: {…ids} }`, which is a shape
+ * for a database. Rendered raw it is a JSON diff of somebody's own laptop; rendered here it is
+ * "Ada handed it to Bruno" and "Warranty until changed from Mar 14, 2027 to Mar 14, 2028" — "it"
+ * rather than the tag, because the panel's own header is already showing `INV-0042`.
+ *
+ * Which sentence, and about whom, is decided in `timeline.ts` — pure, and therefore tested. This
+ * file supplies the words and the layout and nothing else.
+ */
+interface Props {
+  workspaceId: string
+  assetId: string
+  /** Who the workspace currently has, for turning a stored uuid into a name. */
+  dir: Directory
+  /** A category id as its name, or null when the id names nothing this workspace still lists. */
+  categoryName: (id: string) => string | null
+  /**
+   * The asset's currency now, for reading a stored `priceMinor` back into an amount.
+   *
+   * How many decimal places minor units carry is a fact about the currency — none for yen, three
+   * for the dinar — so a timeline that assumed hundredths printed every yen price 100× too small.
+   * An entry that *changed* the currency carries both sides itself and is read from those instead;
+   * this is the answer for every other entry, which is almost all of them.
+   */
+  currency: string | null
+}
+const { workspaceId, assetId, dir, categoryName, currency }: Props = $props()
+
+const api = getInventoryApi()
+
+interface HistoryPage {
+  items: AssetHistoryEntry[]
+  nextCursor: string | null
+}
+
+const historyQuery = createInfiniteQuery(() => ({
+  queryKey: inventoryKeys.assetHistory(workspaceId, assetId),
+  queryFn: ({ pageParam }): Promise<HistoryPage> =>
+    api.assets.history({
+      workspaceId,
+      assetId,
+      ...(pageParam ? { cursor: pageParam as string } : {}),
+    }) as Promise<HistoryPage>,
+  initialPageParam: undefined as string | undefined,
+  getNextPageParam: (last: HistoryPage) => last.nextCursor ?? undefined,
+  enabled: Boolean(workspaceId && assetId),
+}))
+
+const entries = $derived(historyQuery.data?.pages.flatMap((page) => page.items) ?? [])
+
+/**
+ * The four words `nameOf` needs, read on render so they follow the interface language.
+ *
+ * Four rather than two, and that is the fix: an id the directory does not have used to read as
+ * "a former member" whether the member list was still in flight, had failed, or really did not
+ * contain them — so every entry said "A former member handed it to A former member" for the first
+ * moments of every panel, and for ever if the request failed. `members.ts` decides which of the
+ * four applies; this only supplies the wording.
+ */
+const words = $derived({
+  loading: t('member_loading'),
+  unknown: t('member_unknown'),
+  former: t('member_former'),
+  system: t('member_system'),
+})
+
+/**
+ * One value, in the units a person reads it in.
+ *
+ * A stored diff holds what the column holds: minor units for a price, an ISO date for a date, a
+ * uuid for a category. "priceMinor changed from 129900 to 149900" is arithmetic homework, and
+ * "categoryId changed from 0192… to 0192…" is not a sentence at all.
+ */
+function readable(field: string, value: unknown, money: string | null): string {
+  if (value === null || value === undefined || value === '') return '—'
+  if (field === 'categoryId') return categoryName(String(value)) ?? t('category_none')
+  if (field === 'priceMinor') return formatPrice(Number(value), messageLocale(), money)
+  if (field === 'purchasedOn' || field === 'warrantyUntil') return formatDate(String(value))
+  return String(value)
+}
+
+/**
+ * Which currency one side of one entry is in — the entry's own answer where it has one.
+ *
+ * Somebody who re-priced a laptop from ¥120000 to €890 changed two columns in one edit, so the
+ * entry carries a `currency` change beside the `priceMinor` change and each side of the sentence
+ * is in a different currency. Reading both through today's currency would print one of them
+ * wrong, and it is the *old* one — the number nobody can check any more.
+ */
+function currencyFor(entry: AssetHistoryEntry, side: 'from' | 'to'): string | null {
+  const changed = entry.changes.find((change) => change.field === 'currency')
+  if (!changed) return currency
+  const value = changed[side]
+  return typeof value === 'string' && value ? value : null
+}
+
+/**
+ * The label for one field, and the only value here that must *not* be isolated afterwards.
+ *
+ * A key that resolves is a translated word and belongs to the sentence around it. A field this
+ * client has never heard of prints its own name — ugly and true, because the rows outlive the image
+ * that wrote them — and that one is a Latin identifier dropped into a Persian sentence, so it is
+ * isolated here rather than left to reorder the words on either side of it.
+ */
+function fieldLabel(field: string): string {
+  const key = fieldKey(field)
+  return key ? t(key) : isolate(field)
+}
+
+/**
+ * One line under an entry, for one field that changed.
+ *
+ * `changeLineKind` in `timeline.ts` decides which of the five sentences applies — including the one
+ * this used to get wrong, where a `description` change read its whole eight-kilobyte value out into
+ * a row of a 440px panel. `text_changed` says that it changed and `TimelineText` carries the text.
+ *
+ * Every value goes through `isolated()`: a serial number, a location, a price and a category name
+ * are all values somebody typed, and a Latin one inside «{field} از {from} به {to} تغییر کرد»
+ * loses its own punctuation to the sentence around it.
+ */
+function changeLine(entry: AssetHistoryEntry, change: { field: string; from: unknown; to: unknown }): string {
+  const field = fieldLabel(change.field)
+  const kind = changeLineKind(change.field, change.from, change.to)
+  if (kind === 'cleared') return t('history_cleared', isolated({ field }))
+  if (kind === 'replaced') return t('history_replaced', isolated({ field }))
+  if (kind === 'text_changed') return t('history_text_changed', isolated({ field }))
+  if (kind === 'set')
+    return t(
+      'history_set',
+      isolated({ field, to: readable(change.field, change.to, currencyFor(entry, 'to')) }),
+    )
+  return t(
+    'history_changed',
+    isolated({
+      field,
+      from: readable(change.field, change.from, currencyFor(entry, 'from')),
+      to: readable(change.field, change.to, currencyFor(entry, 'to')),
+    }),
+  )
+}
+
+/** The text a `text_changed` line discloses. Null for `from` when there was nothing there before. */
+const textOf = (value: unknown): string | null =>
+  value === null || value === undefined || value === '' ? null : String(value)
+
+function headline(entry: AssetHistoryEntry): string {
+  const personId = personIdOf(entry.action, entry.data)
+  // `action` is a machine token — `repair_logged` — and lands inside a translated sentence for an
+  // action this client has no wording for, so it is isolated with the two names.
+  return t(
+    actionKey(entry.action),
+    isolated({
+      actor: nameOf(entry.actorId, dir, words),
+      person: nameOf(personId, dir, words),
+      action: entry.action,
+    }),
+  )
+}
+
+const SKELETON_ROWS = [0, 1, 2]
+</script>
+
+{#if historyQuery.isPending}
+  <ul class="skeleton">
+    {#each SKELETON_ROWS as row (row)}
+      <li class="srow">
+        <Skeleton height="22px" width="22px" radius="999px" />
+        <div class="slines">
+          <Skeleton height="12px" width="62%" />
+          <Skeleton height="10px" width="28%" />
+        </div>
+      </li>
+    {/each}
+  </ul>
+{:else if historyQuery.isError}
+  <EmptyState bare compact icon="triangle-alert" title={t('history_error')}>
+    {#snippet actions()}
+      <Button size="sm" variant="secondary" onclick={() => void historyQuery.refetch()}>
+        {t('common.retry')}
+      </Button>
+    {/snippet}
+  </EmptyState>
+{:else if entries.length === 0}
+  <!-- Unreachable in practice — `create` writes the first entry in the same transaction as the
+       asset — and rendered honestly all the same, because "unreachable" is a claim about today. -->
+  <EmptyState bare compact icon="clock" title={t('history_empty')} />
+{:else}
+  <ol class="entries">
+    {#each entries as entry (entry.id)}
+      <!-- The avatar shows initials only for somebody actually resolved. Its colour is seeded from
+           the id either way, so it does not change when the member list arrives — and an unresolved
+           actor gets a plain square rather than the initials of "…". -->
+      {@const actor = resolveName(entry.actorId, dir)}
+      {@const note = noteOf(entry.data)}
+      {@const subject = subjectOf(entry.action, entry.data)}
+      <li class="entry">
+        <Avatar name={actor.name} id={entry.actorId} size={22} />
+        <div class="body">
+          <p class="line">{headline(entry)}</p>
+          <!-- What the entry is about — a repair's summary, a file's name. Rendered bare rather
+               than through the catalogue: it is text somebody typed, not an interface string. -->
+          {#if subject}<p class="subject">{subject}</p>{/if}
+          {#if entry.changes.length}
+            <ul class="changes">
+              {#each entry.changes as change (change.field)}
+                <li>
+                  {changeLine(entry, change)}
+                  {#if changeLineKind(change.field, change.from, change.to) === 'text_changed'}
+                    <TimelineText
+                      before={textOf(change.from)}
+                      after={textOf(change.to) ?? ''}
+                    />
+                  {/if}
+                </li>
+              {/each}
+            </ul>
+          {/if}
+          {#if note}
+            <p class="note">{t('history_note', isolated({ note }))}</p>
+          {/if}
+          <!-- The exact moment is on the element, so a hover and a screen reader both get it;
+               the visible text is relative, which is what somebody reading a timeline wants. -->
+          <time class="when" datetime={entry.occurredAt} title={formatDateTime(entry.occurredAt)}>
+            {relativeTime(entry.occurredAt)}
+          </time>
+        </div>
+      </li>
+    {/each}
+  </ol>
+
+  {#if historyQuery.hasNextPage}
+    <div class="more">
+      <Button
+        size="sm"
+        variant="secondary"
+        loading={historyQuery.isFetchingNextPage}
+        onclick={() => historyQuery.fetchNextPage()}
+      >
+        {t('load_more')}
+      </Button>
+    </div>
+  {/if}
+{/if}
+
+<style>
+  .entries,
+  .skeleton {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .entry,
+  .srow {
+    display: grid;
+    /* Logical, so the avatar sits on the reading-start edge in Persian and Arabic too. */
+    grid-template-columns: 22px minmax(0, 1fr);
+    gap: 10px;
+    align-items: start;
+  }
+  .slines {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+  .body {
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+    min-width: 0;
+  }
+  .line {
+    margin: 0;
+    font-size: 13px;
+    line-height: 1.5;
+    color: var(--kern-ink-900);
+  }
+  .changes {
+    margin: 2px 0 0;
+    /* Logical: a bulleted list indents from the reading-start edge in both directions. */
+    padding-inline-start: 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    font-size: 12.5px;
+    line-height: 1.5;
+    /* Muted with a colour rather than with opacity, which fades text against the page. */
+    color: var(--kern-ink-600);
+  }
+  .note {
+    margin: 2px 0 0;
+    font-size: 12.5px;
+    line-height: 1.5;
+    color: var(--kern-ink-600);
+    border-inline-start: 2px solid var(--kern-border-hairline);
+    padding-inline-start: 8px;
+  }
+  .subject {
+    margin: 1px 0 0;
+    font-size: 12.5px;
+    line-height: 1.5;
+    /* Muted with a colour, never with opacity: a faded line at 0.5 is unreadable whatever its
+       token says, and this one carries the only specific word in the entry. */
+    color: var(--kern-ink-600);
+    overflow-wrap: anywhere;
+    /* 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 panel reads left to right and keeps
+       its own trailing punctuation instead of donating it to the paragraph. */
+    unicode-bidi: plaintext;
+  }
+  .when {
+    font-size: 11.5px;
+    color: var(--kern-ink-500);
+  }
+  .more {
+    display: flex;
+    justify-content: center;
+    padding-top: 12px;
+  }
+</style>

package/src/client/components/TimelineText.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+import { t } from '../i18n.js'
+
+/**
+ * The two versions of a long-text field, behind a disclosure.
+ *
+ * A description is up to eight thousand characters, and the timeline rendered a change to one as
+ * "Description changed from … to …" with both versions inline: sixteen kilobytes of somebody's
+ * prose in one row of a 440px panel, with every entry below it pushed off the screen. The line
+ * above this now says only *that* it changed, and the text lives here.
+ *
+ * **A component rather than a bare `<details>` in the timeline, for one reason:** `{#if open}`.
+ * `<details>` keeps its content in the document whether or not it is open, so fifty entries would
+ * still be four hundred kilobytes of text nodes the browser has to build and lay out. Binding
+ * `open` and gating on it means the prose exists only while somebody is reading it, and the
+ * disclosure is still a real `<details>` — keyboard-reachable, announced as a disclosure, and
+ * open by default in a printed page. Nothing is hidden: it is one keystroke away and shown whole,
+ * because truncating what somebody deliberately opened would be the same defect one layer down.
+ *
+ * `before` is null when there was nothing there — a description filled in for the first time has
+ * no previous version, and an empty "Before" block would invent one.
+ */
+interface Props {
+  before: string | null
+  after: string
+}
+const { before, after }: Props = $props()
+
+let open = $state(false)
+</script>
+
+<details class="disclosure" bind:open>
+  <summary>{t('history_show_text')}</summary>
+  {#if open}
+    <div class="body">
+      {#if before !== null}
+        <p class="label">{t('history_text_before')}</p>
+        <!-- `pre-wrap`, so the paragraphs somebody typed are the paragraphs they read back. -->
+        <blockquote class="text was">{before}</blockquote>
+      {/if}
+      <p class="label">{t('history_text_after')}</p>
+      <blockquote class="text">{after}</blockquote>
+    </div>
+  {/if}
+</details>
+
+<style>
+  .disclosure {
+    margin-top: 3px;
+    font-size: 12px;
+  }
+  summary {
+    /* `list-style` on the summary is what removes the native marker in Firefox; the ::-webkit rule
+       below is what removes it in Safari and Chrome. Neither alone does both. */
+    list-style: none;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    width: fit-content;
+    cursor: pointer;
+    color: var(--kern-ink-600);
+    /* WCAG 2.5.8 wants 24px and a line of 12px text is about 16. The padding grows the hit area
+       and the equal negative margin gives the space back, so nothing moves. */
+    padding-block: 4px;
+    margin-block: -4px;
+    border-radius: var(--kern-r-sm);
+  }
+  summary::-webkit-details-marker {
+    display: none;
+  }
+  summary:hover {
+    color: var(--kern-ink-900);
+  }
+  /* The disclosure triangle, drawn rather than borrowed, so it turns with the reading direction:
+     `▸` in an Arabic panel points the wrong way, and a rotated glyph does not. */
+  summary::before {
+    content: '';
+    width: 0;
+    height: 0;
+    border-block: 3.5px solid transparent;
+    border-inline-start: 5px solid currentColor;
+    transition: transform 120ms ease;
+  }
+  .disclosure[open] summary::before {
+    /* Logical would be ideal and there is no logical rotation; the sign is flipped in RTL below. */
+    transform: rotate(90deg);
+  }
+  :global([dir='rtl']) .disclosure[open] summary::before {
+    transform: rotate(-90deg);
+  }
+  .body {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    margin-top: 6px;
+  }
+  .label {
+    margin: 4px 0 0;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.03em;
+    text-transform: uppercase;
+    /* Muted with a colour, never opacity: a faded label is unreadable whatever its token says. */
+    color: var(--kern-ink-500);
+  }
+  .text {
+    margin: 0;
+    padding-inline-start: 8px;
+    border-inline-start: 2px solid var(--kern-border-hairline);
+    font-size: 12.5px;
+    line-height: 1.55;
+    color: var(--kern-ink-700);
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    /* A description somebody typed decides its own direction: `plaintext` takes it from the
+       text's own first strong character, so an English paragraph inside a Persian panel reads
+       left to right and keeps its own punctuation. `isolate` would not — on a block it leaves
+       the paragraph direction inherited. */
+    unicode-bidi: plaintext;
+  }
+  .was {
+    color: var(--kern-ink-500);
+  }
+</style>

package/src/client/core-api.ts

@@ -0,0 +1,71 @@
+/**
+ * The slice of core's API this module reaches for, named by shape rather than imported.
+ *
+ * A module talks to another module through `kernel.call()` on the server; on the client the shell
+ * hands over its own configured core client, and typing the seam structurally keeps the dependency
+ * pointing one way — inventory does not import core's router type, and core does not know inventory
+ * exists.
+ *
+ * Keep it to what is actually called. A wide type here is a promise about core's surface that this
+ * module has no standing to make: `Member` in core carries a role, role ids, group ids, a status
+ * and an invitation trail, and naming any of that here would make this module's screens break when
+ * a field it never reads changes shape. Four procedures are all of it, and each is gated in
+ * `core/src/modules/core/router.ts` — the two settings calls on `core.modules.manage`, the member
+ * list on `core.members.view`, the download URL on the file's own workspace membership.
+ */
+
+/**
+ * A workspace member, as thinly as a picker and an avatar need one.
+ *
+ * `name` is nullable in core — somebody invited and not yet signed in has an email and nothing
+ * else — so every screen here falls back to the email rather than rendering an empty label.
+ */
+export interface CoreMember {
+  userId: string
+  user: {
+    id: string
+    name: string | null
+    email: string
+    avatarUrl?: string | null
+  }
+}
+
+export interface CoreApi {
+  workspaces: {
+    members: {
+      /** Paged in core; this module asks for one large page and keeps the people, not the envelope. */
+      list(input: { workspaceId: string; limit?: number }): Promise<{ items: CoreMember[] }>
+    }
+    modules: {
+      list(input: { workspaceId: string }): Promise<
+        Array<{
+          manifest: { id: string }
+          state: {
+            enabled: boolean
+            settings?: Record<string, unknown>
+          }
+        }>
+      >
+      updateSettings(input: {
+        workspaceId: string
+        moduleId: string
+        settings: Record<string, unknown>
+      }): Promise<unknown>
+    }
+  }
+  /**
+   * Reading a file back.
+   *
+   * This module records that an asset has a file and never touches a byte — the bytes are core's,
+   * the URL is core's to sign, and it is signed for the person asking rather than for this module.
+   * `thumbnail: true` is what the asset photo asks for; a full-size photo in a 440px panel is a
+   * megabyte nobody looks at.
+   */
+  files: {
+    downloadUrl(input: {
+      id: string
+      disposition?: 'inline' | 'attachment'
+      thumbnail?: boolean
+    }): Promise<{ url: string }>
+  }
+}

package/src/client/custody.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { custodyActions } from './custody.js'
+
+/**
+ * What the panel is allowed to offer.
+ *
+ * A decision rather than rendering, and wrong in a way nothing else would catch: a button that
+ * always produces a conflict is a door that will not open. What a stored uuid reads as is the
+ * neighbouring question and lives in `members.test.ts`, beside the file that answers it.
+ */
+describe('custodyActions', () => {
+  it('offers handing over when nobody has it, and handing on or back when somebody does', () => {
+    expect(custodyActions({ held: false, archived: false, may: true })).toEqual(['assign'])
+    expect(custodyActions({ held: true, archived: false, may: true })).toEqual(['transfer', 'return'])
+  })
+
+  it('offers nothing without the permission — hidden, not disabled', () => {
+    expect(custodyActions({ held: false, archived: false, may: false })).toEqual([])
+    expect(custodyActions({ held: true, archived: false, may: false })).toEqual([])
+  })
+
+  it('offers nothing on an archived item, which the server refuses anyway', () => {
+    expect(custodyActions({ held: false, archived: true, may: true })).toEqual([])
+    expect(custodyActions({ held: true, archived: true, may: true })).toEqual([])
+  })
+
+  it('never offers assigning something that is already held', () => {
+    // The one combination that would 409 every single time it was pressed.
+    expect(custodyActions({ held: true, archived: false, may: true })).not.toContain('assign')
+  })
+})

package/src/client/custody.ts

@@ -0,0 +1,34 @@
+/**
+ * Which handover an asset can actually take right now.
+ *
+ * Three verbs and not one, because the server has three procedures and refuses the wrong one with
+ * its own sentence: assigning something somebody already holds is a mistake worth naming, and
+ * handing on something nobody holds is a different mistake. The interface's job is not to offer
+ * either — a button that always produces a conflict is a door that will not open.
+ *
+ * A `.ts` file rather than a `const` inside the panel for the reason `timeline.ts` and `price.ts`
+ * are: this is a fact with a right answer, and a `.svelte` file cannot be unit-tested.
+ */
+export type CustodyAction = 'assign' | 'transfer' | 'return'
+
+export interface CustodyState {
+  /** Somebody is holding it — `assets.custodian_user_id` is set. */
+  held: boolean
+  /** The workspace has taken it out of the register; the server refuses every handover. */
+  archived: boolean
+  /** This person holds `inventory.custody.manage`. */
+  may: boolean
+}
+
+/**
+ * What to offer, in the order the buttons appear.
+ *
+ * Empty for somebody without the permission — hide what a person may never do — and empty for an
+ * archived item, where the panel says *why* instead. An archived item deliberately offers nothing
+ * rather than a disabled row of buttons: the reason is one sentence, and one sentence beats three
+ * controls that cannot be pressed.
+ */
+export function custodyActions(state: CustodyState): CustodyAction[] {
+  if (!state.may || state.archived) return []
+  return state.held ? ['transfer', 'return'] : ['assign']
+}