@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/permissions.ts

@@ -1,5 +1,5 @@
 import { session } from '@kernhq/ui'
-import { inventoryPermissions, MODULE_ID } from '../contract.js'
+import { inventoryPermissions, MODULE_ID } from '../contract/index.js'
 
 /**
  * What this module lets somebody do.
@@ -21,6 +21,13 @@ const key = (suffix: string) => {
 export const INVENTORY_PERMISSIONS = {
   view: key('asset.view'),
   manage: key('asset.manage'),
+  /** Handing an item over and taking it back. Reading who holds what rides `view` — see the
+   *  contract's `permissions.ts` for why that is a decision rather than an omission. */
+  custody: key('custody.manage'),
+  /** Sending an item away, correcting the record and logging it back. */
+  repairs: key('repair.manage'),
+  /** The categories settings page, and nothing else. */
+  categories: key('category.manage'),
 } as const
 
 export type InventoryPermission = keyof typeof INVENTORY_PERMISSIONS

package/src/client/price.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, it } from 'vitest'
+import {
+  CURRENCIES,
+  currencyOptions,
+  formatPrice,
+  minorUnitExponent,
+  parsePrice,
+  priceExample,
+} from './price.js'
+
+/**
+ * The regression this file exists for.
+ *
+ * `raw.replace(',', '.')` replaced the first comma only, so `1.234,56` — how German, Turkish and
+ * Persian write twelve hundred — parsed as `1.23456` and was stored as €1.23. Three of the five
+ * languages this module ships, silently, with no error anywhere. `abc` and `-5` were worse: they
+ * came back `null` and the asset saved with no price at all.
+ */
+const minor = (raw: string, locale: string, currency?: string | null) => {
+  const result = parsePrice(raw, locale, currency)
+  return result.ok ? result.minor : 'invalid'
+}
+
+describe('parsePrice', () => {
+  it('reads a grouped price in each locale the module ships', () => {
+    expect(minor('1,234.56', 'en')).toBe(123456)
+    expect(minor('1.234,56', 'de')).toBe(123456)
+    expect(minor('1.234,56', 'tr')).toBe(123456)
+    // Persian groups with ٬ and points with ٫, in Persian digits.
+    expect(minor('۱٬۲۳۴٫۵۶', 'fa')).toBe(123456)
+    expect(minor('1,234.56', 'ar')).toBe(123456)
+  })
+
+  it('reads an ungrouped price in each locale', () => {
+    expect(minor('1234.56', 'en')).toBe(123456)
+    expect(minor('1234,56', 'de')).toBe(123456)
+    expect(minor('1234,56', 'tr')).toBe(123456)
+    expect(minor('۱۲۳۴٫۵۶', 'fa')).toBe(123456)
+  })
+
+  it('folds Persian and Arabic digits, so a person may type their own numerals', () => {
+    expect(minor('۱۹٫۹۹', 'fa')).toBe(1999)
+    expect(minor('١٩.٩٩', 'ar')).toBe(1999)
+    expect(minor('۲۵', 'fa')).toBe(2500)
+  })
+
+  it('treats an empty field as no price rather than a bad one', () => {
+    expect(minor('', 'en')).toBe(null)
+    expect(minor('   ', 'de')).toBe(null)
+  })
+
+  it('rejects what it cannot read instead of saving nothing', () => {
+    // Both of these used to return null, and the asset was filed with no price.
+    expect(minor('abc', 'en')).toBe('invalid')
+    expect(minor('-5', 'en')).toBe('invalid')
+    expect(minor('1.2.3', 'en')).toBe('invalid')
+    expect(minor('12,34', 'en')).toBe('invalid')
+    expect(minor('$12.00', 'en')).toBe('invalid')
+  })
+
+  /**
+   * The 100× that has no visible symptom: `.` is German's *group* separator, so stripping it would
+   * store 123456 for somebody who meant 1234.56. There is no way to tell which they meant, so the
+   * field asks rather than guesses.
+   */
+  it('rejects a group separator that does not group three digits', () => {
+    expect(minor('1234.56', 'de')).toBe('invalid')
+    expect(minor('1234.56', 'tr')).toBe('invalid')
+    expect(minor('1.23.456', 'de')).toBe('invalid')
+    expect(minor('1,2345', 'en')).toBe('invalid')
+  })
+
+  it('keeps a bare decimal, with or without its leading zero', () => {
+    expect(minor('0.5', 'en')).toBe(50)
+    expect(minor('.5', 'en')).toBe(50)
+    expect(minor(',5', 'de')).toBe(50)
+  })
+
+  it('does not lose a cent to floating point', () => {
+    expect(minor('19.99', 'en')).toBe(1999)
+    expect(minor('0.07', 'en')).toBe(7)
+    expect(minor('8.29', 'en')).toBe(829)
+  })
+})
+
+/**
+ * The second silent 100×, and the one the picker itself created.
+ *
+ * `parsePrice` and `formatPrice` both hard-coded 1/100 while the currency list offers **JPY**,
+ * which has no minor unit at all, and **KWD**, which has three decimal places. So ¥1000 typed into
+ * the field was stored as 100000 minor units — ¥100 000 to anything reading the column honestly —
+ * and every dinar amount was out by a factor of ten. **IRR is the one that stings**: the rial has
+ * no minor unit either, and it is the currency of a language this module ships.
+ */
+describe('the currency decides the minor unit', () => {
+  it('asks the currency rather than assuming hundredths', () => {
+    expect(minorUnitExponent('USD')).toBe(2)
+    expect(minorUnitExponent('EUR')).toBe(2)
+    expect(minorUnitExponent('JPY')).toBe(0)
+    expect(minorUnitExponent('IRR')).toBe(0)
+    expect(minorUnitExponent('KWD')).toBe(3)
+    // No currency on an amount is not a reason to make the field unusable, and two decimals is
+    // what ISO 4217 assigns by default.
+    expect(minorUnitExponent(null)).toBe(2)
+    expect(minorUnitExponent('')).toBe(2)
+    // The contract takes any three letters, so a code `Intl` refuses must not throw out of a form.
+    expect(minorUnitExponent('nonsense')).toBe(2)
+  })
+
+  it('stores ¥1000 as 1000, not as 10', () => {
+    expect(minor('1000', 'en', 'JPY')).toBe(1000)
+    expect(minor('1,000', 'en', 'JPY')).toBe(1000)
+    expect(formatPrice(1000, 'en', 'JPY')).toBe('1000')
+    // What it did before: hundredths, so the amount read back a hundred times too small.
+    expect(formatPrice(1000, 'en')).toBe('10.00')
+  })
+
+  it('keeps all three of a dinar’s decimal places', () => {
+    expect(minor('1.234', 'en', 'KWD')).toBe(1234)
+    expect(minor('1,234.567', 'en', 'KWD')).toBe(1234567)
+    expect(formatPrice(1234567, 'en', 'KWD')).toBe('1234.567')
+    // The old behaviour dropped the third place and was ten times out.
+    expect(minor('1.234', 'en')).toBe('invalid')
+  })
+
+  it('still reads a two-decimal currency exactly as before', () => {
+    expect(minor('19.99', 'en', 'USD')).toBe(1999)
+    expect(minor('1.234,56', 'de', 'EUR')).toBe(123456)
+    expect(formatPrice(123456, 'de', 'EUR')).toBe('1234,56')
+  })
+
+  /**
+   * The point of the whole fix: there is no path where a wrong number is stored quietly. `19.99`
+   * in a yen field is somebody who has not noticed which field they are in, and rounding it to
+   * ¥20 for them is the same class of silence as the `1.234,56` → €1.23 bug this file began with.
+   */
+  it('refuses more decimal places than the currency has, rather than rounding them away', () => {
+    expect(minor('19.99', 'en', 'JPY')).toBe('invalid')
+    expect(minor('0.5', 'en', 'JPY')).toBe('invalid')
+    expect(minor('.5', 'en', 'IRR')).toBe('invalid')
+    expect(minor('1.2345', 'en', 'KWD')).toBe('invalid')
+    expect(minor('1.234', 'en', 'USD')).toBe('invalid')
+  })
+
+  it('round-trips every shipped locale against a currency of each shape', () => {
+    for (const locale of ['en', 'de', 'tr', 'fa', 'ar']) {
+      for (const currency of ['USD', 'JPY', 'KWD', 'IRR']) {
+        for (const value of [0, 7, 2500, 123456, 99999999]) {
+          expect({
+            locale,
+            currency,
+            value,
+            back: minor(formatPrice(value, locale, currency), locale, currency),
+          }).toEqual({ locale, currency, value, back: value })
+        }
+      }
+    }
+  })
+
+  it('holds up an example the field would actually accept', () => {
+    // It said "Enter an amount like 1234.56" in a yen field and then refused 1234.56.
+    expect(priceExample('en', 'JPY')).toBe('1234')
+    expect(priceExample('en', 'KWD')).toBe('1234.567')
+    expect(priceExample('en', 'USD')).toBe('1234.56')
+    expect(priceExample('de', null)).toBe('1234,56')
+    for (const currency of ['USD', 'JPY', 'KWD', 'IRR', 'EUR']) {
+      const example = priceExample('en', currency)
+      expect({ currency, example, ok: parsePrice(example, 'en', currency).ok }).toEqual({
+        currency,
+        example,
+        ok: true,
+      })
+    }
+  })
+})
+
+describe('formatPrice', () => {
+  it('has no price to show for no price', () => {
+    expect(formatPrice(null, 'en')).toBe('')
+    expect(formatPrice(undefined, 'de')).toBe('')
+  })
+
+  /**
+   * What the edit form seeds itself with has to be something the same locale can parse back, or
+   * opening an asset and saving it unchanged would report the stored price as invalid.
+   */
+  it('round-trips through parsePrice in every locale', () => {
+    for (const locale of ['en', 'de', 'tr', 'fa', 'ar']) {
+      for (const value of [0, 7, 2500, 123456, 99999999]) {
+        expect({ locale, value, back: minor(formatPrice(value, locale), locale) }).toEqual({
+          locale,
+          value,
+          back: value,
+        })
+      }
+    }
+  })
+
+  it('writes the reader’s own digits', () => {
+    expect(formatPrice(123456, 'fa')).toContain('۴')
+    expect(formatPrice(123456, 'de')).toBe('1234,56')
+    expect(formatPrice(123456, 'en')).toBe('1234.56')
+  })
+})
+
+/**
+ * The list a money field offers.
+ *
+ * It was `['USD', 'EUR', 'IRR', 'AED']` in a product whose language menu offers Turkish — so a
+ * workspace in Istanbul could not record what it paid for anything. The contract takes any ISO
+ * 4217 code (`z.string().length(3)`) and the server stores whatever arrives, so nothing but the
+ * picker was ever short: four options, one of them missing for one of the five shipped languages.
+ */
+describe('CURRENCIES', () => {
+  it('has a currency for every language this module ships', () => {
+    // The point of the whole fix. `tr` is on the language menu and TRY was not on this list.
+    for (const code of ['USD', 'EUR', 'TRY', 'IRR', 'AED']) expect(CURRENCIES).toContain(code)
+  })
+
+  it('offers codes `Intl` recognises, so a price is never labelled with something invented', () => {
+    for (const code of CURRENCIES) {
+      const formatted = new Intl.NumberFormat('en', { style: 'currency', currency: code }).format(1)
+      // An unknown code comes back as the literal code; a real one gets a symbol or a name, and
+      // either way `Intl` accepts it rather than throwing on a malformed one.
+      expect({ code, formatted: typeof formatted }).toEqual({ code, formatted: 'string' })
+      expect(code).toMatch(/^[A-Z]{3}$/)
+    }
+  })
+
+  it('lists each code once', () => {
+    expect([...new Set(CURRENCIES)]).toEqual([...CURRENCIES])
+  })
+
+  /**
+   * The order the comment above the list claims, which the list did not have.
+   *
+   * It said "the currency of each shipped language first, in the order the locales are listed
+   * everywhere else in this package (en, ar, de, fa, tr)" while the list read `USD, EUR, AED, TRY,
+   * IRR` — en, de, ar, tr, fa, which is no order at all. A rule nothing checks is a rule the next
+   * person appends underneath and quietly breaks, so it is checked.
+   */
+  it('opens with the currency of each shipped language, in the locale order', () => {
+    expect(CURRENCIES.slice(0, 5)).toEqual(['USD', 'AED', 'EUR', 'IRR', 'TRY'])
+  })
+
+  it('puts the empty option first, because an asset with no price has no currency', () => {
+    const options = currencyOptions('—')
+    expect(options[0]).toEqual({ value: '', label: '—' })
+    expect(options.slice(1).map((o) => o.value)).toEqual([...CURRENCIES])
+    // Codes rather than names: ISO 4217 is what the column stores, and a name is one more thing to
+    // translate five times for no gain over what somebody reads on their own bank statement.
+    expect(options.slice(1).every((o) => o.label === o.value)).toBe(true)
+  })
+})

package/src/client/price.ts

@@ -0,0 +1,279 @@
+/**
+ * Reading and writing a price the way the person in front of the form writes it.
+ *
+ * **This is the file that shipped a silent 100× data loss.** The dialog parsed a price with
+ * `Number.parseFloat(raw.replace(',', '.'))`, and `String.replace` with a string pattern replaces
+ * only the *first* match — so a German, Turkish or Persian reader typing `1.234,56`, which is how
+ * three of the five languages this module ships write twelve hundred, got `1.23456` parsed to
+ * `1.23` and stored as €1.23. `1,234.56` in English became the same. Neither said anything: the
+ * old parser returned `null` for garbage and the asset was simply saved with no price at all, so
+ * `abc` and `-5` both vanished without an error.
+ *
+ * So: no separator is assumed, the locale is asked what its own are, and anything that is not a
+ * plain non-negative number in *that* locale comes back as a rejection the form can show. There is
+ * no third outcome where a wrong number is stored quietly.
+ *
+ * Pure on purpose — the locale arrives as an argument rather than being read from `@kernhq/ui`.
+ * That entry point reaches Svelte components, and a parser that drags a compiler behind it is a
+ * parser nothing can unit-test. The dialog passes `messageLocale()`.
+ */
+
+/** `minor: null` is a real answer — an empty field means "no price", not a bad one. */
+export type PriceResult = { ok: true; minor: number | null } | { ok: false }
+
+/**
+ * The currencies a money field offers, in one place because two forms ask for one.
+ *
+ * The asset form and the repair form put the same question — what is this amount in — and a second
+ * copy of the list is a list that gains a currency in one form and not the other. Codes rather than
+ * names: ISO 4217 is what the column stores, and a currency name is one more thing to translate
+ * five times for no gain over the code somebody already reads on their own bank statement.
+ *
+ * **This list was `['USD', 'EUR', 'IRR', 'AED']` in a product that ships Turkish.** A Turkish
+ * workspace could not record what it paid for anything in lira: the contract takes any three-letter
+ * code (`z.string().length(3)`) and the server stores whatever arrives, so the shortage was the
+ * picker's alone — four options, one of which was missing for one of the five languages on the
+ * language menu. TRY, and the currency of every other locale this module ships, is now here.
+ *
+ * The order is deliberate and is not alphabetical: the currency of each shipped language first, in
+ * the order the locales are listed everywhere else in this package (en, ar, de, fa, tr) — so USD,
+ * AED, EUR, IRR, TRY — then the ones a company in those places is most likely to have paid an
+ * invoice in. A picker sorted A–Z puts AED above USD for a reader in Berlin, which is tidy and
+ * useless.
+ *
+ * **The comment said that while the list said `USD, EUR, AED, TRY, IRR`**, which is no order at
+ * all — en, de, ar, tr, fa — so the rule a sixth currency was supposed to be filed under described
+ * something that had never been true. `price.test.ts` now asserts the first five, because a stated
+ * order nothing checks drifts back the first time somebody appends a code.
+ *
+ * It is still a list, not the whole of ISO 4217: all 180 codes in a `<select>` is not a kindness.
+ *
+ * **What a new asset defaults to is deliberately nothing.** The obvious improvement on "the first
+ * code in the list" is "whatever this workspace uses", and that is right — but a workspace currency
+ * does not exist: `InventorySettings` holds the tag prefix, the tag padding and the two notice
+ * windows, and nothing else, so `defaultCurrency` is a contract change rather than something a
+ * picker can invent. The tempting shortcut is to read it off the reader's locale, and that is
+ * *worse* than no default: two colleagues in one workspace, one reading German and one reading
+ * Turkish, would be handed different pre-selected currencies for the same register, notice nothing,
+ * and store EUR against one laptop and TRY against the next. A currency is a fact about the
+ * company, not about the language somebody happens to read the screen in. So the forms seed from
+ * the *record* — a repair inherits its asset's currency, an edit keeps its own — and a new asset
+ * starts empty, which asks the question instead of answering it wrongly.
+ */
+export const CURRENCIES = [
+  'USD',
+  'AED',
+  'EUR',
+  'IRR',
+  'TRY',
+  'GBP',
+  'SAR',
+  'QAR',
+  'KWD',
+  'EGP',
+  'CHF',
+  'SEK',
+  'NOK',
+  'DKK',
+  'PLN',
+  'CAD',
+  'AUD',
+  'JPY',
+  'CNY',
+  'INR',
+] as const
+
+/**
+ * The options both money fields offer, built once.
+ *
+ * The empty option is first and is a real answer: an asset with no price has no currency either,
+ * and a picker with no way back to "none" is a field somebody can fill in and never clear.
+ */
+export function currencyOptions(noneLabel: string): Array<{ value: string; label: string }> {
+  return [{ value: '', label: noneLabel }, ...CURRENCIES.map((code) => ({ value: code, label: code }))]
+}
+
+const EXPONENTS: Map<string, number> = new Map()
+
+/**
+ * How many decimal places this currency has — asked of the currency, never assumed to be two.
+ *
+ * **This module stored ¥1000 as ¥10 and every KWD amount ten times too small.** `parsePrice` and
+ * `formatPrice` both hard-coded 1/100, and the picker offers JPY, which has *no* minor unit, and
+ * KWD, which has *three* decimal places. So `1000` typed into a yen field became 100000 minor
+ * units, read back as `1000.00`, and was ¥100 000 to anything that read the column honestly — a
+ * silent 100× on exactly the shape of field this file was rewritten to stop silently mangling.
+ *
+ * **IRR is the one that matters most here**, because it is the currency of a language this module
+ * ships: the rial has no minor unit either, so a Persian workspace was the default victim.
+ *
+ * CLDR knows each currency's exponent and `Intl` will hand it over, so nothing is tabulated: a
+ * currency added to `CURRENCIES` next year gets the right answer without anybody remembering this
+ * function exists. A code `Intl` refuses, or one it has never heard of, falls back to two — which
+ * is what ISO 4217 assigns by default, and is the only guess available.
+ *
+ * The locale is fixed at `'en'` deliberately: the exponent is a fact about the *currency*, and
+ * asking under the reader's locale would make the same money parse differently for two colleagues.
+ */
+export function minorUnitExponent(currency: string | null | undefined): number {
+  if (!currency) return 2
+  const cached = EXPONENTS.get(currency)
+  if (cached !== undefined) return cached
+  let exponent = 2
+  try {
+    // `maximumFractionDigits` is optional in the DOM lib and always present in practice for a
+    // currency formatter; `??` is what keeps the two type-checks agreeing about that.
+    exponent =
+      new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ??
+      2
+  } catch {
+    // A malformed code — the contract takes any three letters and the picker is not the only way
+    // in. Two decimals is ISO 4217's own default and keeps the field usable.
+  }
+  if (!Number.isInteger(exponent) || exponent < 0 || exponent > 4) exponent = 2
+  EXPONENTS.set(currency, exponent)
+  return exponent
+}
+
+interface Separators {
+  group: string
+  decimal: string
+}
+
+const SEPARATORS: Map<string, Separators> = new Map()
+
+/**
+ * What this locale's own numbers look like, asked of `Intl` rather than tabulated here.
+ *
+ * A table of separators per language is a table that is wrong for the sixth language somebody adds.
+ * Measured for the five shipped today: en and ar group with `,` and point with `.`, de and tr are
+ * the other way round, and fa uses `٬` and `٫`.
+ */
+function separatorsFor(locale: string): Separators {
+  const cached = SEPARATORS.get(locale)
+  if (cached) return cached
+  const found: Separators = { group: ',', decimal: '.' }
+  try {
+    const parts = new Intl.NumberFormat(locale).formatToParts(12345.6)
+    found.group = parts.find((part) => part.type === 'group')?.value ?? found.group
+    found.decimal = parts.find((part) => part.type === 'decimal')?.value ?? found.decimal
+  } catch {
+    // A runtime that cannot name this locale must not make the field unusable; English separators
+    // are the fallback, and a wrong guess shows an error rather than storing a wrong number.
+  }
+  SEPARATORS.set(locale, found)
+  return found
+}
+
+/**
+ * A Persian keyboard produces ۱۲۳ and an Arabic one ١٢٣, and `Number` reads neither.
+ *
+ * Same fold HR's employee counter does, and for the same reason: a person typing the digits of
+ * their own language into their own language's form must not be told their input is not a number.
+ */
+const toLatinDigits = (value: string) =>
+  value
+    .replace(/[٠-٩]/g, (d) => String(d.charCodeAt(0) - 0x0660))
+    .replace(/[۰-۹]/g, (d) => String(d.charCodeAt(0) - 0x06f0))
+
+/** Bidi controls ride along on anything copied out of an RTL document and are never separators. */
+const BIDI = /[‎‏؜⁦-⁩]/g
+
+/**
+ * A group separator always precedes exactly three digits.
+ *
+ * This is the rule that stops the quiet 100×: in German `.` groups, so `1234.56` is not "one
+ * thousand two hundred and thirty-four point five six" — it is not a well-formed German number at
+ * all. Stripping the dot would store €12,345.60 for a €1,234.56 laptop and nothing would say so.
+ * Rejecting it puts the question back to the person, which is the only honest answer available.
+ */
+function isGroupedInteger(text: string, group: string): boolean {
+  if (/^\d+$/.test(text)) return true
+  if (!group || !text.includes(group)) return false
+  const [first, ...rest] = text.split(group)
+  if (first === undefined || !/^\d{1,3}$/.test(first)) return false
+  return rest.every((chunk) => /^\d{3}$/.test(chunk))
+}
+
+/**
+ * Minor units are the wire format; the form takes what somebody reads off the receipt.
+ *
+ * Returns `{ ok: false }` for anything that is not a non-negative number in `locale` — including a
+ * negative one, which the contract has no way to mean and the old parser dropped in silence.
+ *
+ * `currency` decides how many decimal places the amount is allowed and what it is scaled by. More
+ * fractional digits than the currency has is a **rejection, not a rounding**: `19.99` in a yen
+ * field is not ¥20, it is somebody who has not noticed which field they are in, and quietly
+ * storing a number nobody typed is the whole class of failure this file exists to end. Omitting
+ * `currency` keeps two decimals, which is what an amount with no currency on it has always meant.
+ *
+ * The scaled integer is built by **concatenating digits**, never by multiplying: `19.99 * 100` is
+ * `1998.9999999999998` in a double, and the `Math.round` that used to hide it would have had to
+ * hide `1234.567 * 1000` too. Digits in, digits out, and no float on the path at all.
+ */
+export function parsePrice(raw: string, locale: string, currency?: string | null): PriceResult {
+  const text = toLatinDigits(raw).replace(BIDI, '').trim()
+  if (!text) return { ok: true, minor: null }
+
+  const { group, decimal } = separatorsFor(locale)
+  const pieces = text.split(decimal)
+  if (pieces.length > 2) return { ok: false }
+
+  let whole = pieces[0] ?? ''
+  const frac = pieces[1]
+  // "‚50" is how somebody writes half a unit; the leading zero is implied, not missing.
+  if (whole === '' && frac !== undefined) whole = '0'
+
+  if (!isGroupedInteger(whole, group)) return { ok: false }
+  if (frac !== undefined && !/^\d+$/.test(frac)) return { ok: false }
+
+  const exponent = minorUnitExponent(currency)
+  // A currency with no minor unit has no decimal point either, so `frac` of any length fails here.
+  if (frac !== undefined && frac.length > exponent) return { ok: false }
+
+  const digits = group ? whole.split(group).join('') : whole
+  const minor = Number(`${digits}${(frac ?? '').padEnd(exponent, '0')}`)
+  // A price that cannot survive the round trip through a double is not a price anybody typed.
+  if (!Number.isSafeInteger(minor)) return { ok: false }
+  return { ok: true, minor }
+}
+
+/**
+ * The stored price, back in the field, in the reader's own numbers.
+ *
+ * The edit form has to seed itself from `priceMinor`, and seeding it with `1234.56` for a German
+ * reader would make them look at a number their own locale says is €123,456 — then `parsePrice`
+ * would reject it on the grouping rule and they would be told their own data is invalid. What comes
+ * out of here is exactly what goes back in, for the currency the amount is in.
+ */
+export function formatPrice(
+  minor: number | null | undefined,
+  locale: string,
+  currency?: string | null,
+): string {
+  if (minor === null || minor === undefined) return ''
+  const exponent = minorUnitExponent(currency)
+  const value = minor / 10 ** exponent
+  try {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: exponent,
+      maximumFractionDigits: exponent,
+      useGrouping: false,
+    }).format(value)
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * The amount the "enter an amount like…" error holds up as an example.
+ *
+ * It has to be an amount the field would *accept*, or the error tells somebody to type something
+ * that is also rejected. `1234.56` was hard-coded, so a yen field said "Enter an amount like
+ * 1234.56" and then refused it. Built from the exponent instead: `1234` in yen, `1234.567` in
+ * dinars, and the reader's own separators and digits around it either way.
+ */
+export function priceExample(locale: string, currency?: string | null): string {
+  const exponent = minorUnitExponent(currency)
+  return formatPrice(Number(`1234${'567'.slice(0, exponent).padEnd(exponent, '0')}`), locale, currency)
+}

package/src/client/query.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { inventoryKeys } from './query.js'
+
+/**
+ * The realtime contract, held to by a test because nothing else can hold it.
+ *
+ * `realtime.svelte.ts` calls `invalidateQueries({ queryKey: [module, entity] })` with whatever the
+ * server put in the change event, and `src/server/router.ts` emits `entity: 'asset'`. A key whose
+ * second segment is anything else is simply never invalidated — no error, no warning, just a list
+ * that stops updating. That is what `['inventory', 'assets', …]` did: the detail panel refreshed
+ * and the list behind it did not, and the only way to see it was to write to the module from a
+ * second browser.
+ *
+ * Proven against `partialMatchKey` from `@tanstack/query-core`, which is what
+ * `invalidateQueries` filters with; asserted here on the segment itself, so the test does not need
+ * the query runtime to state the rule it is protecting.
+ */
+const WS = '01920000-0000-7000-8000-000000000001'
+
+/** Must equal the `entity` string in `src/server/router.ts`'s `notify.change` call. */
+const ENTITY = 'asset'
+
+describe('inventoryKeys', () => {
+  it('names the entity exactly as the server emits it, on every key', () => {
+    for (const [name, key] of [
+      ['assets', inventoryKeys.assets(WS)],
+      ['assets(filtered)', inventoryKeys.assets(WS, { archived: false })],
+      ['asset', inventoryKeys.asset(WS, 'some-id')],
+    ] as const)
+      expect({ name, module: key[0], entity: key[1] }).toEqual({
+        name,
+        module: 'inventory',
+        entity: ENTITY,
+      })
+  })
+
+  it('puts the list and the row under one prefix, so one change event reaches both', () => {
+    const list = inventoryKeys.assets(WS, { archived: false })
+    const row = inventoryKeys.asset(WS, 'some-id')
+    expect(list.slice(0, 2)).toEqual(row.slice(0, 2))
+  })
+
+  it('makes a filtered list a different question from an unfiltered one', () => {
+    expect(inventoryKeys.assets(WS, { archived: true })).not.toEqual(
+      inventoryKeys.assets(WS, { archived: false }),
+    )
+    expect(inventoryKeys.assets(WS, { archived: false })).not.toEqual(inventoryKeys.assets(WS))
+  })
+
+  it('does not let two workspaces share a cache entry', () => {
+    expect(inventoryKeys.assets('ws-a')).not.toEqual(inventoryKeys.assets('ws-b'))
+  })
+
+  it('starts every key with the module, so one invalidation can clear all of Inventory', () => {
+    for (const key of [inventoryKeys.all, inventoryKeys.assets(WS), inventoryKeys.asset(WS, 'id')])
+      expect(key[0]).toBe('inventory')
+  })
+})