kempo-inventory 0.5.2 → 0.5.4

package/README.md

@@ -2,7 +2,8 @@
 
 The core of an inventory system for [kempo](https://www.npmjs.com/package/kempo) CMS. It is deliberately small: every item has just a **SKU**, **name**, **quantity** and **description**. Everything else is a *custom field* that a person adds in the admin, or that another extension registers, so the same base can model anything: parts, books, rentals, supplies.
 
-- Quantity changes go through one audited action, with a reason, a note and a movement history
+- Quantity changes go through one audited action: add or remove, or set the count outright. A reason and a note are optional, and every change is kept in a movement history
+- Units (oz, g, and so on) on items, with a category's unit as the default. Quantities can have decimal places when the `decimal_quantity` setting is on
 - Custom fields of seven types, managed in **Admin > Inventory > Fields**
 - A server SDK and a set of hooks so other extensions can extend it (reorder levels, pricing, suppliers, categories...), and fields, categories and items can be owned by an extension
 - Admin page at **Admin > Inventory**, JSON API under `/inventory/api`
@@ -40,7 +41,7 @@ The item list, its filters and the item form are all built from the field list.
 
 ### Fields for one category
 
-A field applies either to **every item** (the default) or to **one category**. Make a paint's "Finish" (Matte, Satin, Gloss) for the Paint category and it only appears on items whose category is Paint; filament can have its own "Diameter" and nothing else sees it. Choose what a field **Applies to** when you create it (**Inventory > Categories** has a gear button per category that opens its fields). The item form shows the default fields plus those of the typed category, and swaps them as the category changes.
+A field applies either to **every item** (the default) or to **one category**. Make a paint's "Finish" (Matte, Satin, Gloss) for the Paint category and it only appears on items whose category is Paint; filament can have its own "Diameter" and nothing else sees it. Choose what a field **Applies to** when you create it, and change it later by editing the field (its values move with it; the change is refused if the key is already used where the field is going). **Inventory > Categories** has a gear button per category that opens its fields. The item form shows the default fields plus those of the typed category, and swaps them as the category changes.
 
 - A key is unique within its category, so two categories can each have a "finish". A category cannot reuse a key a default field has (and the other way round), because both would be stored under the same name on its items.
 - Moving an item to another category keeps the values it held for fields it no longer shows. They are hidden, not deleted, and come back if the item returns.

package/admin/edit/index.page.html

@@ -5,6 +5,7 @@ locked: true
 <content>
   <script type="module" src="/kempo-ui/components/Icon.js"></script>
   <script type="module" src="/kempo-ui/components/Tabs.js"></script>
+  <script type="module" src="/inventory/components/ItemQuantity.js"></script>
 
   <div class="d-f mb" style="align-items: center; gap: var(--spacer);">
     <a href="/admin/extension/kempo-inventory/" class="btn" id="backLink"><k-icon name="arrow" direction="left"></k-icon> Inventory</a>
@@ -29,6 +30,11 @@ locked: true
       <location name="inventory-item-sections" />
     </k-tab-content>
 
+    <k-tab for="quantity">Quantity</k-tab>
+    <k-tab-content name="quantity" class="pt">
+      <k-inventory-item-quantity id="itemQuantity"></k-inventory-item-quantity>
+    </k-tab-content>
+
     <!--
       Tabs from any number of extensions (barcodes, say): supply an admin/*.global.html file that adds a k-tab and a
       k-tab-content for the location inventory-item-tabs. Each tab reads the item from ?id= in the address.
@@ -47,6 +53,7 @@ locked: true
     const params = new URLSearchParams(location.search);
     const next = safeNext(params.get('next'), '/admin/extension/kempo-inventory/');
     document.getElementById('backLink').href = next;
+    document.getElementById('itemQuantity').itemId = params.get('id');
     const $container = document.getElementById('editItem');
 
     const [, permData] = await getAllCurrentUserPermissions();

package/admin/index.page.html

@@ -162,7 +162,7 @@ locked: true
       user-supplied text itself.
     */
     const decorate = (item, ctx) => {
-      const record = { ...item, qtyText: String(item.quantity), tagsText: item.tags.join(', '), ownerText: item.owner, ...(can('items:update') && { _url: `/admin/extension/kempo-inventory/edit?id=${encodeURIComponent(item.id)}` }) };
+      const record = { ...item, qtyText: [String(item.quantity), item.effectiveUnit].filter(Boolean).join(' '), tagsText: item.tags.join(', '), ownerText: item.owner, ...(can('items:update') && { _url: `/admin/extension/kempo-inventory/edit?id=${encodeURIComponent(item.id)}` }) };
       /* Only the fields that apply to this item's category; a column another category's items fill stays blank here. */
       for(const field of applicableFields(fields, item.category).filter(f => f.listed)) record[`f_${field.key}`] = displayValue(field, item.fields[field.key], ctx);
       return record;
@@ -338,6 +338,12 @@ locked: true
             <label class="d-b mb-sm" for="cat-description">Description</label>
             <textarea id="cat-description" class="full" rows="3" maxlength="500" .value=${category?.description ?? ''}></textarea>
           </div>
+          <div class="mb">
+            <label class="d-b mb-sm" for="cat-unit">Unit
+              <small class="d-b tc-muted">What items in this category count in, such as oz or g. An item with its own unit keeps it.</small>
+            </label>
+            <input type="text" id="cat-unit" class="full" maxlength="20" .value=${category?.unit ?? ''}>
+          </div>
           <div class="mb">
             <label class="d-b mb-sm" for="cat-tags">Tags</label>
             <k-tags id="cat-tags" .value=${tagsValue(category?.tags)} .getSuggestions=${suggestTags} @input=${lowerTagInput} @change=${lowerTagChips}></k-tags>
@@ -362,6 +368,7 @@ locked: true
             description: $dialog.querySelector('#cat-description').value,
             tags: readTags($dialog.querySelector('#cat-tags')),
             image: $dialog.querySelector('#cat-image').value[0] ?? null,
+            unit: $dialog.querySelector('#cat-unit').value,
           };
 
           let error, result;

package/kempo-config.json

@@ -4,7 +4,10 @@
   "public-scope": "inventory",
   "schema": "./server/db/schema.js",
   "suggestedPeers": [
-    { "name": "kempo-media", "reason": "Photos and other files on inventory items (brings kempo-files and kempo-thumbs with it)" }
+    {
+      "name": "kempo-media",
+      "reason": "Photos and other files on inventory items (brings kempo-files and kempo-thumbs with it)"
+    }
   ],
   "widgets": [
     {
@@ -90,6 +93,12 @@
       "type": "number",
       "description": "The largest import file (a .json or .zip made by Export) the admin Import accepts, in MB."
     },
+    {
+      "name": "decimal_quantity",
+      "value": false,
+      "type": "boolean",
+      "description": "Allow quantities with decimal places, such as 2.5 oz of paint or 12.75 g of filament, up to four places. Off, quantities are whole numbers. Turning it on does not change quantities already stored."
+    },
     {
       "name": "public_read",
       "value": false,
@@ -114,5 +123,8 @@
       "type": "string",
       "description": "The aspect ratio item photos are shown at, as width:height (4:3, 1:1, 16:9). Images are cropped to fit, never stretched."
     }
-  ]
+  ],
+  "public-scopes": {
+    "items": "public-items"
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-inventory",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "A basic inventory management system for kempo cms",
   "license": "MIT",
   "author": "Dustin Poissant <dustinpoissant@gmail.com>",
@@ -29,6 +29,7 @@
   "files": [
     "admin",
     "public",
+    "public-items",
     "server",
     "install.js",
     "update.js",

package/public/api/categories/PUT.js

@@ -11,7 +11,7 @@ export default async (request, response) => {
 
   const body = request.body || {};
   const changes = {};
-  for(const property of ['newName', 'image', 'description', 'tags']){
+  for(const property of ['newName', 'image', 'description', 'tags', 'unit']){
     if(property in body) changes[property] = body[property];
   }
   const [error, category] = await saveCategory(body.name, changes, { userId: auth.userId });

package/public/api/fields/[key]/PATCH.js

@@ -7,7 +7,7 @@ export default async (request, response) => {
 
   const body = request.body || {};
   const changes = {};
-  for(const property of ['label', 'description', 'required', 'listed', 'suggest', 'options', 'position', 'type', 'imageRatio', 'imageMax']){
+  for(const property of ['label', 'description', 'required', 'listed', 'suggest', 'options', 'position', 'type', 'imageRatio', 'imageMax', 'category']){
     if(body[property] !== undefined) changes[property] = body[property];
   }
   const [error, field] = await updateField(request.params.key, changes, { category: request.query.category ?? '' });

package/public/api/items/POST.js

@@ -5,8 +5,8 @@ export default async (request, response) => {
   const [authError, auth] = await authorize(request, 'items:create');
   if(authError) return response.status(authError.code).json({ error: authError.msg });
 
-  const { sku, name, description, category, tags, quantity, fields } = request.body || {};
-  const [error, item] = await createItem({ sku, name, description, category, tags, quantity, fields, userId: auth.userId });
+  const { sku, name, description, category, unit, tags, quantity, fields } = request.body || {};
+  const [error, item] = await createItem({ sku, name, description, category, unit, tags, quantity, fields, userId: auth.userId });
   if(error) return response.status(error.code).json({ error: error.msg });
   response.status(201).json({ item });
 };

package/public/api/items/[id]/PATCH.js

@@ -5,8 +5,8 @@ export default async (request, response) => {
   const [authError, auth] = await authorize(request, 'items:update');
   if(authError) return response.status(authError.code).json({ error: authError.msg });
 
-  const { sku, name, description, category, tags, fields } = request.body || {};
-  const [error, item] = await updateItem(request.params.id, { sku, name, description, category, tags, fields, userId: auth.userId });
+  const { sku, name, description, category, unit, tags, fields } = request.body || {};
+  const [error, item] = await updateItem(request.params.id, { sku, name, description, category, unit, tags, fields, userId: auth.userId });
   if(error) return response.status(error.code).json({ error: error.msg });
   response.json({ item });
 };

package/public/api/items/[id]/adjust/POST.js

@@ -5,8 +5,8 @@ export default async (request, response) => {
   const [authError, auth] = await authorize(request, 'quantity:adjust');
   if(authError) return response.status(authError.code).json({ error: authError.msg });
 
-  const { delta, reason, note } = request.body || {};
-  const [error, item] = await adjustQuantity(request.params.id, { delta, reason, note, userId: auth.userId });
+  const { delta, set, reason, note } = request.body || {};
+  const [error, item] = await adjustQuantity(request.params.id, { delta, set, reason, note, userId: auth.userId });
   if(error) return response.status(error.code).json({ error: error.msg });
   response.json({ item });
 };

package/public/components/FieldsManager.js

@@ -206,7 +206,7 @@ export default class FieldsManager extends ShadowComponent {
         </div>
         <div class="mb">
           <label class="d-b mb-sm" for="fld-scope">Applies to</label>
-          <select id="fld-scope" class="full" ?disabled=${editing}>
+          <select id="fld-scope" class="full" ?disabled=${managed}>
             <option value="" ?selected=${editing ? !field.category : scope === '' || scope === '*'}>Every item</option>
             ${categories.map(c => html`<option value=${c.name} ?selected=${editing ? c.key === field.category : c.key === scope}>Only ${c.name}</option>`)}
           </select>
@@ -282,6 +282,7 @@ export default class FieldsManager extends ShadowComponent {
         if(!managed){
           data.required = $dialog.querySelector('#fld-required').value === true;
           data.options = value('#fld-options').split('\n').map(o => o.trim()).filter(Boolean);
+          data.category = value('#fld-scope');
         }
         if(!data.label){
           Toast.error('A label is required');

package/public/components/ItemDialog.js

@@ -71,12 +71,20 @@ export const openAdjustDialog = async ({ item, onSaved = () => {} } = {}) => {
     <div class="p" style=${SCROLL}>
       <p class="mb">Current quantity: <strong>${data.item.quantity}</strong></p>
       <div class="mb">
-        <label class="d-b mb-sm" for="dlg-delta">Change (negative removes quantity)</label>
-        <input type="number" id="dlg-delta" class="full" step="1" required>
+        <label class="d-b mb-sm" for="dlg-mode">How</label>
+        <select id="dlg-mode" class="full" @change=${event => { $dialog.querySelector('#dlg-amount-label').textContent = event.target.value === 'set' ? 'Count it should be now' : 'Change (negative removes quantity)'; }}>
+          <option value="change">Add or remove</option>
+          <option value="set" selected>Set to</option>
+        </select>
+      </div>
+      <div class="mb">
+        <label class="d-b mb-sm" for="dlg-delta" id="dlg-amount-label">Count it should be now</label>
+        <input type="number" id="dlg-delta" class="full" step="any" required>
       </div>
       <div class="mb">
-        <label class="d-b mb-sm" for="dlg-reason">Reason</label>
+        <label class="d-b mb-sm" for="dlg-reason">Reason (optional)</label>
         <select id="dlg-reason" class="full">
+          <option value="" selected>No reason</option>
           <option value="received">Received</option>
           <option value="sold">Sold / used</option>
           <option value="damaged">Damaged / lost</option>
@@ -97,13 +105,15 @@ export const openAdjustDialog = async ({ item, onSaved = () => {} } = {}) => {
     cancelText: 'Close',
     confirmAction: async event => {
       event.keepDialogOpen = true;
-      const delta = Number($dialog.querySelector('#dlg-delta').value);
-      if(!Number.isInteger(delta) || delta === 0){
-        Toast.error('Enter a non-zero whole number');
+      const setting = $dialog.querySelector('#dlg-mode').value === 'set';
+      const raw = $dialog.querySelector('#dlg-delta').value;
+      const amount = Number(raw);
+      if(raw.trim() === '' || !Number.isFinite(amount) || (setting ? amount < 0 : amount === 0)){
+        Toast.error(setting ? 'Enter the count, zero or more' : 'Enter a number that is not zero');
         return;
       }
       const [adjustError, adjusted] = await adjustQuantity(item.id, {
-        delta,
+        ...(setting ? { set: amount } : { delta: amount }),
         reason: $dialog.querySelector('#dlg-reason').value,
         note: $dialog.querySelector('#dlg-note').value,
       });

package/public/components/ItemForm.js

@@ -93,7 +93,7 @@ export const createItemForm = ({ item = null, fields = [], defaults = {}, askQua
   };
 
   render(html`
-    ${locked ? html`<p class="mb tc-muted">Managed by the ${item.owner} extension. Its SKU, name and category can only be changed there; everything else, including quantity, you can edit here.</p>` : ''}
+    ${locked ? html`<p class="mb tc-muted">Managed by the ${item.owner} extension. Its SKU, name and category can only be changed there; everything else you can edit here, and quantity in the Quantity tab.</p>` : ''}
     <div class="d-f mb" style="gap: var(--spacer);">
       <div class="flex">
         <label class="d-b mb-sm" for="dlg-sku">SKU *</label>
@@ -113,6 +113,12 @@ export const createItemForm = ({ item = null, fields = [], defaults = {}, askQua
         @focusin=${e => offerCategories(e.currentTarget)}
         @search=${showFields} @select=${() => setTimeout(showFields)} @change=${() => setTimeout(showFields)} @focusout=${() => setTimeout(showFields, 150)}></k-combobox>
     </div>
+    <div class="mb">
+      <label class="d-b mb-sm" for="dlg-unit">Unit
+        <small class="d-b tc-muted">What the quantity counts, such as oz or g. Leave empty to use the category's unit.</small>
+      </label>
+      <input type="text" id="dlg-unit" class="full" maxlength="20" .value=${item?.unit ?? defaults.unit ?? ''}>
+    </div>
     <div class="mb"><label class="d-b mb-sm" for="dlg-tags">Tags</label><k-tags id="dlg-tags" .value=${tagsValue(item?.tags ?? defaults.tags)} .getSuggestions=${suggestTags} @input=${lowerTagInput} @change=${lowerTagChips}></k-tags></div>
     <div class="mb"><label class="d-b mb-sm" for="dlg-description">Description</label><textarea id="dlg-description" class="full" rows="2" .value=${item?.description ?? ''}></textarea></div>
     <div id="dlg-fields"></div>
@@ -131,6 +137,7 @@ export const createItemForm = ({ item = null, fields = [], defaults = {}, askQua
       description: $root.querySelector('#dlg-description')?.value ?? '',
       category: $root.querySelector('#dlg-category')?.value ?? '',
       quantity: $root.querySelector('#dlg-qty')?.value ?? '',
+      unit: $root.querySelector('#dlg-unit')?.value ?? '',
       tags: readTags($root.querySelector('#dlg-tags')),
       values,
     });
@@ -154,6 +161,7 @@ export const createItemForm = ({ item = null, fields = [], defaults = {}, askQua
       name: $root.querySelector('#dlg-name').value.trim(),
       description: $root.querySelector('#dlg-description').value,
       category: ($root.querySelector('#dlg-category').value || '').trim(),
+      unit: $root.querySelector('#dlg-unit').value.trim(),
       tags: readTags($root.querySelector('#dlg-tags')),
       fields: values,
     };
@@ -170,6 +178,7 @@ export const createItemForm = ({ item = null, fields = [], defaults = {}, askQua
       /* Blank fields are left out on create so hooks can tell "not provided" from a value. */
       data.fields = Object.fromEntries(Object.entries(values).filter(([, v]) => v !== '' && !(Array.isArray(v) && !v.length)));
       if(!data.category) delete data.category;
+      if(!data.unit) delete data.unit;
       if(!data.tags.length) delete data.tags;
       data.quantity = askQuantity ? Number($root.querySelector('#dlg-qty').value || 0) : Number(defaults.quantity ?? 0);
       [error, saved] = await createItem(data);

package/public/components/ItemQuantity.js

@@ -0,0 +1,180 @@
+import ShadowComponent from '/kempo-ui/components/ShadowComponent.js';
+import { html } from '/kempo-ui/lit-all.min.js';
+import Toast from '/kempo-ui/components/Toast.js';
+import '/kempo-ui/components/Spinner.js';
+import { getAllCurrentUserPermissions } from '/kempo/sdk.js';
+import { getItem, adjustQuantity } from '/inventory/sdk.js';
+
+const REASONS = { received: 'Received', sold: 'Sold / used', damaged: 'Damaged / lost', correction: 'Count correction', adjustment: 'Other' };
+
+/*
+  An item's quantity on its edit page: the count on hand, a form to add or remove stock or to set the count
+  outright, and the history. The server sends the count and history only to people who manage quantity, and
+  the form only to those who may adjust it. The page sets the `item-id` attribute, and the component loads the
+  item when it knows it. A reason is optional.
+*/
+export default class ItemQuantity extends ShadowComponent {
+  static properties = {
+    itemId: { type: String, attribute: 'item-id' },
+    item: { state: true },
+    movements: { state: true },
+    permissions: { state: true },
+    error: { state: true },
+    mode: { state: true },
+    amount: { state: true },
+    reason: { state: true },
+    note: { state: true },
+    busy: { state: true },
+  };
+
+  constructor(){
+    super();
+    this.itemId = '';
+    this.item = null;
+    this.movements = [];
+    this.permissions = new Set();
+    this.error = '';
+    this.mode = 'set';
+    this.amount = '';
+    this.reason = '';
+    this.note = '';
+    this.busy = false;
+  }
+
+  /*
+    Lifecycle callbacks
+  */
+  updated(changed){
+    super.updated(changed);
+    if(changed.has('itemId') && this.itemId) this.load();
+  }
+
+  /*
+    Loading and changing
+  */
+  get canAdjust(){
+    return this.permissions.has('kempo-inventory:quantity:adjust');
+  }
+
+  get unit(){
+    return this.item?.effectiveUnit ?? '';
+  }
+
+  get validAmount(){
+    if(this.amount.trim() === '') return false;
+    const number = Number(this.amount);
+    if(!Number.isFinite(number)) return false;
+    return this.mode === 'set' ? number >= 0 : number !== 0;
+  }
+
+  load = async () => {
+    const [[error, data], [, permissionData]] = await Promise.all([getItem(this.itemId), getAllCurrentUserPermissions()]);
+    if(error){
+      this.error = error.code === 404 ? 'Item not found.' : error.msg;
+      return;
+    }
+    this.item = data.item;
+    this.movements = data.movements;
+    this.permissions = new Set(permissionData?.permissions ?? []);
+  };
+
+  apply = async () => {
+    if(!this.validAmount){
+      Toast.error(this.mode === 'set' ? 'Enter the count, zero or more' : 'Enter a number that is not zero');
+      return;
+    }
+    const amount = Number(this.amount);
+    this.busy = true;
+    const [error, data] = await adjustQuantity(this.item.id, {
+      ...(this.mode === 'set' ? { set: amount } : { delta: amount }),
+      reason: this.reason,
+      note: this.note.trim(),
+    });
+    this.busy = false;
+    if(error){
+      Toast.error(error.msg);
+      return;
+    }
+    this.amount = '';
+    this.note = '';
+    Toast.success(`Quantity is now ${data.item.quantity}${this.unit ? ` ${this.unit}` : ''}`);
+    await this.load();
+  };
+
+  /*
+    View
+  */
+  renderForm(){
+    const setting = this.mode === 'set';
+    return html`
+      <h4>${setting ? 'Set the count' : 'Add or remove'}</h4>
+      <div class="d-f" style="align-items: flex-end;">
+        <div class="mb mrq">
+          <label class="d-b mbq" for="qtyMode">How
+            <small class="d-b tc-muted">Set the count, or add and remove.</small>
+          </label>
+          <select id="qtyMode" class="m0" @change=${event => { this.mode = event.target.value; this.amount = ''; }}>
+            <option value="change" ?selected=${!setting}>Add or remove</option>
+            <option value="set" ?selected=${setting}>Set to</option>
+          </select>
+        </div>
+        <div class="mb mrq" style="width: 16rem;">
+          <label class="d-b mbq" for="qtyAmount">${setting ? 'Count' : 'Change'}${this.unit ? ` (${this.unit})` : ''}
+            <small class="d-b tc-muted">${setting
+              ? 'The count it should be now. The change is worked out for you.'
+              : 'Add a number to receive stock, or use a minus sign to remove it.'}</small>
+          </label>
+          <input id="qtyAmount" type="number" step="any" class="full m0" .value=${this.amount}
+            @input=${event => { this.amount = event.target.value; }}>
+        </div>
+        <div class="mb mrq">
+          <label class="d-b mbq" for="qtyReason">Reason
+            <small class="d-b tc-muted">Optional. Why it changed, if you want it recorded.</small>
+          </label>
+          <select id="qtyReason" class="m0" @change=${event => { this.reason = event.target.value; }}>
+            <option value="" ?selected=${this.reason === ''}>No reason</option>
+            ${Object.entries(REASONS).map(([value, label]) => html`<option value=${value} ?selected=${value === this.reason}>${label}</option>`)}
+          </select>
+        </div>
+        <div class="flex mb mrq" style="min-width: 12rem;">
+          <label class="d-b mbq" for="qtyNote">Note
+            <small class="d-b tc-muted">Optional. Shown in the history.</small>
+          </label>
+          <input id="qtyNote" type="text" class="full m0" maxlength="200" .value=${this.note}
+            @input=${event => { this.note = event.target.value; }}>
+        </div>
+      </div>
+      <button class="primary mb" ?disabled=${this.busy || !this.validAmount} @click=${this.apply}>${setting ? 'Set quantity' : 'Apply change'}</button>`;
+  }
+
+  renderHistory(){
+    if(!this.movements.length) return html`<p class="tc-muted">No quantity changes yet.</p>`;
+    return html`<table>
+      <thead><tr><th>When</th><th>Change</th><th>Reason</th><th>Balance</th></tr></thead>
+      <tbody>
+        ${this.movements.map(movement => html`<tr>
+          <td>${new Date(movement.created).toLocaleString()}</td>
+          <td>${movement.delta > 0 ? '+' : ''}${movement.delta}</td>
+          <td>${REASONS[movement.reason] ?? movement.reason}${movement.note ? ` - ${movement.note}` : ''}</td>
+          <td>${movement.quantityAfter}</td>
+        </tr>`)}
+      </tbody>
+    </table>`;
+  }
+
+  render(){
+    if(!this.itemId) return '';
+    if(this.error) return html`<p class="tc-danger">${this.error}</p>`;
+    if(!this.item) return html`<k-spinner></k-spinner>`;
+    if(this.item.quantity === undefined) return html`<p class="tc-muted">Quantity is only shown to people who manage stock.</p>`;
+    return html`
+      <h2 class="mb0">${this.item.quantity}${this.unit ? ` ${this.unit}` : ''}</h2>
+      <p class="tc-muted mb">On hand</p>
+      ${this.canAdjust ? this.renderForm() : ''}
+      <h4>History</h4>
+      ${this.renderHistory()}
+    `;
+  }
+}
+
+customElements.define('k-inventory-item-quantity', ItemQuantity);

package/public-items/[id]/index.page.html

@@ -0,0 +1,123 @@
+<!--
+  title: Item
+  description: A single inventory item
+-->
+<page template="default" title="Item">
+<content>
+	<div id="app" class="container py" hidden>
+		<k-tabs active="details" hash-routing>
+			<k-tab for="details">Details</k-tab>
+			<k-tab-content name="details" class="pt">
+				<div id="detail"></div>
+			</k-tab-content>
+			<location name="inventory-item-tabs" />
+		</k-tabs>
+	</div>
+</content>
+<content location="scripts">
+	<script type="module" src="/kempo-ui/components/Tabs.js"></script>	<script type="module">
+		import { html, render } from '/kempo-ui/lit-all.min.js';
+		import Dialog from '/kempo-ui/components/Dialog.js';
+		import Toast from '/kempo-ui/components/Toast.js';
+		import PhotoViewer from '/kempo-ui/components/PhotoViewer.js';
+		import '/kempo-ui/components/Rating.js';
+		import { getSession, getAllCurrentUserPermissions } from '/kempo/sdk.js';
+		import { getItem, deleteItem, getFields } from '/inventory/sdk.js';
+		import { displayValue, applicableFields } from '/inventory/components/ItemFields.js';
+
+		const id = location.pathname.split('/').filter(Boolean).pop();
+		const $app = document.getElementById('app');
+		const $detail = document.getElementById('detail');
+
+		const [, session] = await getSession();
+		const signedIn = Boolean(session?.user);
+		const [, permissionData] = signedIn ? await getAllCurrentUserPermissions() : [null, null];
+		const permissions = new Set(permissionData?.permissions ?? []);
+		const can = name => permissions.has(`kempo-inventory:${name}`);
+		const [fieldsError, fieldData] = await getFields();
+		if(fieldsError){
+			$app.innerHTML = '<p class="tc-danger">You need to sign in to view this item.</p>';
+			$app.hidden = false;
+			Toast.error(fieldsError.msg || 'Failed to load the inventory fields');
+		} else {
+			$app.hidden = false;
+			await draw(fieldData);
+		}
+
+		/* The category is a built-in property of every item; '' means uncategorised. */
+		function categoryOf(item){ return (item.category ?? '').trim(); }
+		function categoryHref(name){ return name ? `/category?name=${encodeURIComponent(name)}` : '/category?uncategorised=1'; }
+		function tagChips(tags){ return tags?.length ? html`<div class="tag-list">${tags.map(tag => html`<a class="tag-chip" href="/search?tag=${encodeURIComponent(tag)}">${tag}</a>`)}</div>` : ''; }
+
+		async function draw(fieldData){
+			const fields = fieldData.fields;
+			const [error, data] = await getItem(id);
+			if(error){
+				render(html`<a href="/" class="btn mb"><k-icon name="arrow" direction="left"></k-icon> Home</a>
+					<h1>${error.code === 404 ? 'Item not found' : 'Something went wrong'}</h1><p>${error.msg}</p>`, $detail);
+				return;
+			}
+			const { item, linked, media } = data;
+			document.title = `${item.name} · Inventory`;
+			const category = categoryOf(item);
+			const backHref = category ? categoryHref(category) : '/';
+			const context = { linked, media };
+
+			/* Clicking a photo opens Kempo UI's photo viewer over the page (arrows and keys move between the item's photos). */
+			const openPhoto = photo => {
+				const images = photos.filter(p => p.kind === 'image');
+				PhotoViewer.open(images.map(p => ({ src: p.path, caption: p.alt || p.name })), images.indexOf(photo));
+			};
+			const shown = applicableFields(fields, item.category);
+			const photos = shown.filter(f => f.type === 'media').flatMap(f => (item.fields[f.key] ?? []).map(mediaId => media[mediaId]).filter(Boolean));
+			const rows = shown.filter(f => f.type !== 'media' && item.fields[f.key] !== undefined && item.fields[f.key] !== null);
+
+			const remove = () => Dialog.confirm(`Delete "${item.name}" and its stock history? This action cannot be undone.`, async confirmed => {
+				if(!confirmed) return;
+				const [deleteError] = await deleteItem(item.id);
+				if(deleteError){
+					Toast.error(deleteError.msg || 'Failed to delete item');
+					return;
+				}
+				location.href = backHref;
+			});
+
+			render(html`
+				<div class="d-f mb" style="align-items: center; gap: var(--spacer); flex-wrap: wrap;">
+					<a href=${backHref} class="btn" id="backBtn"><k-icon name="arrow" direction="left"></k-icon> ${category || 'Home'}</a>
+					<div class="flex"></div>
+					${can('items:update') ? html`<a class="btn" id="editBtn" href=${`/items/${item.id}/edit?next=${encodeURIComponent(`/items/${item.id}`)}`}><k-icon name="edit"></k-icon> Edit</a>` : ''}
+					${can('items:delete') ? html`<button class="btn danger" id="deleteBtn" @click=${remove}><k-icon name="delete"></k-icon> Delete</button>` : ''}
+				</div>
+
+				<h1 class="mb0" id="itemName">${item.name}</h1>
+				<p class="tc-muted mb-sm">${item.sku}</p>
+				${tagChips(item.tags)}
+
+				${photos.length ? html`
+					<div class="gallery mb-lg" id="gallery">
+						${photos.map(p => p.kind === 'image'
+							? html`<a href=${p.path} @click=${e => { e.preventDefault(); openPhoto(p); }}><img src=${p.thumbnail ?? p.path} alt=${p.alt || p.name}></a>`
+							: html`<a href=${p.path} target="_blank" rel="noopener" class="btn">${p.name}</a>`)}
+					</div>` : ''}
+
+				${item.description ? html`<p style="white-space: pre-wrap;">${item.description}</p>` : ''}
+
+				${rows.length ? html`
+					<dl id="fields" style="display: grid; grid-template-columns: max-content 1fr; gap: var(--spacer_q) var(--spacer);">
+						${rows.map(f => html`<dt class="tc-muted">${f.label}</dt>
+							<dd class="m0">${f.type === 'rating'
+								? html`<k-rating disabled .value=${item.fields[f.key]} aria-label=${`${item.fields[f.key]} out of 5`}></k-rating>`
+								: f.type === 'color'
+								? html`<span style="display: inline-block; width: 4rem; height: 4rem; vertical-align: middle; margin-right: var(--spacer_h); border: 1px solid var(--c_border); border-radius: var(--radius); background: ${item.fields[f.key]};"></span>${item.fields[f.key]}`
+								: f.type === 'item' && linked[item.fields[f.key]]
+								? html`<a href="/items/${item.fields[f.key]}">${displayValue(f, item.fields[f.key], context)}</a>`
+								: f.type === 'longtext'
+									? html`<span style="white-space: pre-wrap;">${item.fields[f.key]}</span>`
+									: displayValue(f, item.fields[f.key], context)}</dd>`)}
+					</dl>` : ''}
+			`, $detail);
+		}
+	</script>
+</content>
+</page>

package/server/db/schema.js

@@ -1,4 +1,9 @@
-import { pgTable, text, timestamp, integer, boolean, jsonb, index, uniqueIndex } from 'drizzle-orm/pg-core';
+import { pgTable, text, timestamp, integer, numeric, boolean, jsonb, index, uniqueIndex } from 'drizzle-orm/pg-core';
+
+/*
+  A quantity has four decimal places at most. Whole numbers unless the decimal_quantity setting allows fractions.
+*/
+const quantityColumn = name => numeric(name, { precision: 14, scale: 4, mode: 'number' });
 
 /*
   An item has only the core columns. Everything else lives in `data`, keyed by the `key` of a
@@ -10,7 +15,8 @@ export const kempoInventoryItem = pgTable('kempoInventoryItem', {
   name: text('name').notNull(),
   description: text('description').notNull().default(''),
   category: text('category').notNull().default(''), // built in and optional; '' means uncategorised
-  quantity: integer('quantity').notNull().default(0),
+  quantity: quantityColumn('quantity').notNull().default(0),
+  unit: text('unit').notNull().default(''), // built in and optional: what the quantity counts (oz, g); '' uses the category's unit
   tags: jsonb('tags').notNull().default([]), // built in: short lower-case labels search finds
   data: jsonb('data').notNull().default({}),
   owner: text('owner').notNull().default(''), // '' for items people manage, or the extension that created it; see ownership.js
@@ -47,8 +53,8 @@ export const kempoInventoryField = pgTable('kempoInventoryField', {
 export const kempoInventoryMovement = pgTable('kempoInventoryMovement', {
   id: text('id').primaryKey(),
   itemId: text('itemId').notNull(),
-  delta: integer('delta').notNull(),
-  quantityAfter: integer('quantityAfter').notNull(),
+  delta: quantityColumn('delta').notNull(),
+  quantityAfter: quantityColumn('quantityAfter').notNull(),
   reason: text('reason').notNull().default('adjustment'),
   note: text('note').notNull().default(''),
   userId: text('userId').notNull().default(''),
@@ -66,6 +72,7 @@ export const kempoInventoryCategory = pgTable('kempoInventoryCategory', {
   key: text('key').notNull(),
   name: text('name').notNull(),
   image: text('image'), // a stored media id, as held by a media field
+  unit: text('unit').notNull().default(''), // what items in the category count in, unless an item has its own
   description: text('description').notNull().default(''),
   tags: jsonb('tags').notNull().default([]),
   owner: text('owner').notNull().default(''), // '' for categories people manage, or the extension that registered it

package/server/utils/categories.js

@@ -3,6 +3,7 @@ import { sql, eq } from 'drizzle-orm';
 import crypto from 'crypto';
 import { kempoInventoryItem, kempoInventoryCategory, kempoInventoryField } from '../db/schema.js';
 import { normalizeTags, tidyTag } from './tags.js';
+import { checkUnit } from './quantity.js';
 import { categoryKey, groupCategories, tidyCategory, MAX_CATEGORY, MAX_DESCRIPTION } from './categoryLogic.js';
 import { coerceValue } from './fieldTypes.js';
 import { getAssets, checkAssets } from './media.js';
@@ -75,12 +76,17 @@ export const getCategories = async ({ includeEmpty = false, q = '', tag = '', ow
   by that owner; anyone can still change its image, description and tags. `owner` here is the
   extension making the call ('' for a person), and a category created by this call belongs to it.
 */
-export const saveCategory = async (name, { newName, image, description, tags } = {}, { userId = '', owner = '' } = {}) => {
+export const saveCategory = async (name, { newName, image, description, tags, unit } = {}, { userId = '', owner = '' } = {}) => {
   const displayName = tidyCategory(name);
   const key = categoryKey(displayName);
   if(!key) return [{ code: 400, msg: 'A category name is required' }, null];
 
   const changes = {};
+  if(unit !== undefined){
+    const [unitError, cleanUnit] = checkUnit(unit);
+    if(unitError) return [unitError, null];
+    changes.unit = cleanUnit;
+  }
   if(description !== undefined){
     const text = String(description ?? '').trim();
     if(text.length > MAX_DESCRIPTION) return [{ code: 400, msg: `A description must be ${MAX_DESCRIPTION} characters or fewer` }, null];
@@ -162,6 +168,7 @@ export const saveCategory = async (name, { newName, image, description, tags } =
       /* What the category ends up holding: this call's changes, then the existing record, then the one merged away. */
       const merged = {
         image: changes.image !== undefined ? changes.image : (target?.image ?? source?.image ?? null),
+        unit: changes.unit !== undefined ? changes.unit : (target?.unit || source?.unit || ''),
         description: changes.description !== undefined ? changes.description : (target?.description || source?.description || ''),
         /* Merging two categories keeps the tags of both. */
         tags: changes.tags !== undefined ? changes.tags : [...new Set([...(target?.tags ?? []), ...(source && source !== target ? source.tags ?? [] : [])])],
@@ -182,7 +189,7 @@ export const saveCategory = async (name, { newName, image, description, tags } =
     if(outcome.refused) return [outcome.refused, null];
 
     await notify(EVENTS.categoryUpdated, { category: outcome.row, previous: outcome.previous, moved: outcome.moved, userId, actor: owner });
-    return [null, { name: outcome.row.name, key: outcome.row.key, image: outcome.row.image, description: outcome.row.description, tags: outcome.row.tags ?? [], owner: outcome.row.owner, moved: outcome.moved }];
+    return [null, { name: outcome.row.name, key: outcome.row.key, image: outcome.row.image, unit: outcome.row.unit, description: outcome.row.description, tags: outcome.row.tags ?? [], owner: outcome.row.owner, moved: outcome.moved }];
   } catch {
     return [{ code: 500, msg: 'Failed to save the category' }, null];
   }

package/server/utils/categoryLogic.js

@@ -43,11 +43,11 @@ export const groupCategories = (rows, records = [], { includeEmpty = false } = {
     const record = recordByKey.get(key);
     const spelling = [...entry.spellings.entries()]
       .sort((a, b) => b[1] - a[1] || Number(startsUpper(b[0])) - Number(startsUpper(a[0])) || a[0].localeCompare(b[0]))[0][0];
-    return { key, name: record?.name ?? spelling, count: entry.count, image: record?.image ?? null, description: record?.description ?? '', tags: record?.tags ?? [], owner: record?.owner ?? '' };
+    return { key, name: record?.name ?? spelling, count: entry.count, image: record?.image ?? null, unit: record?.unit ?? '', description: record?.description ?? '', tags: record?.tags ?? [], owner: record?.owner ?? '' };
   });
 
   const empty = includeEmpty
-    ? records.filter(record => !byKey.has(record.key)).map(record => ({ key: record.key, name: record.name, count: 0, image: record.image ?? null, description: record.description ?? '', tags: record.tags ?? [], owner: record.owner ?? '' }))
+    ? records.filter(record => !byKey.has(record.key)).map(record => ({ key: record.key, name: record.name, count: 0, image: record.image ?? null, unit: record.unit ?? '', description: record.description ?? '', tags: record.tags ?? [], owner: record.owner ?? '' }))
     : [];
 
   return [...used, ...empty].sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));

package/server/utils/fields.js

@@ -13,10 +13,10 @@ const isUniqueViolation = error => (error?.code || error?.cause?.code) === '2350
 
 /*
   Properties an extension's own field accepts on update, and what anyone else (the admin UI) may
-  adjust on a field an extension owns. Key and ownership never change after creation, and the type
-  only changes where nothing can be lost (see CONVERSIONS in fieldTypes.js).
+  adjust on a field an extension owns. Key and ownership never change after creation, the scope
+  (`category`) can, and the type only changes where nothing can be lost (see CONVERSIONS in fieldTypes.js).
 */
-const OWNER_EDITABLE = ['label', 'description', 'required', 'listed', 'suggest', 'options', 'position', 'type', 'imageRatio', 'imageMax'];
+const OWNER_EDITABLE = ['label', 'description', 'required', 'listed', 'suggest', 'options', 'position', 'type', 'imageRatio', 'imageMax', 'category'];
 const ANYONE_EDITABLE = ['label', 'description', 'listed', 'suggest', 'position', 'imageRatio', 'imageMax'];
 
 /*
@@ -60,6 +60,22 @@ export const itemsInScope = category => category
   ? sql`lower(regexp_replace(btrim(${kempoInventoryItem.category}), '[[:space:]]+', ' ', 'g')) = ${category}`
   : sql`true`;
 
+/*
+  Items in a category hold the default fields and that category's under one set of names, so a
+  key cannot be reused where it would collide: a default field's key is taken in every category,
+  and a category's key is taken in the default scope. `exclude` is the scope the field is leaving.
+*/
+const keyClash = async (key, scope, exclude = null) => {
+  const [clash] = await db.select({ category: kempoInventoryField.category }).from(kempoInventoryField).where(and(
+    eq(kempoInventoryField.key, key),
+    exclude === null ? sql`true` : sql`${kempoInventoryField.category} <> ${exclude}`,
+    scope ? sql`${kempoInventoryField.category} in ('', ${scope})` : sql`true`,
+  ));
+  if(!clash) return null;
+  const where = clash.category === scope ? (scope ? 'this category' : 'the default fields') : (scope ? 'the default fields' : 'a category');
+  return { code: 409, msg: `A field with the key "${key}" already exists in ${where}` };
+};
+
 /*
   Creates a field. `owner` is '' for a field made by a person in the admin, or the extension's
   name for one it registers itself.
@@ -80,19 +96,8 @@ export const createField = async (definition, { owner = '' } = {}) => {
   }
 
   try {
-    /*
-      Items in a category hold the default fields and that category's under one set of names, so a
-      key cannot be reused where it would collide: a default field's key is taken in every category,
-      and a category's key is taken in the default scope.
-    */
-    const clash = await db.select({ category: kempoInventoryField.category }).from(kempoInventoryField).where(and(
-      eq(kempoInventoryField.key, normalized.key),
-      scope ? sql`${kempoInventoryField.category} in ('', ${scope})` : sql`true`,
-    ));
-    if(clash.length){
-      const where = clash[0].category === scope ? (scope ? 'this category' : 'the default fields') : (scope ? 'the default fields' : 'a category');
-      return [{ code: 409, msg: `A field with the key "${normalized.key}" already exists in ${where}` }, null];
-    }
+    const clash = await keyClash(normalized.key, scope);
+    if(clash) return [clash, null];
 
     const field = await db.transaction(async tx => {
       if(scope){
@@ -119,13 +124,18 @@ export const updateField = async (key, changes = {}, { owner = null, category =
   const [lookupError, existing] = await getField(key, category);
   if(lookupError) return [lookupError, null];
 
+  const targetName = changes.category === undefined ? undefined : tidyCategory(changes.category);
+  const targetScope = targetName === undefined ? existing.category : categoryKey(targetName);
+  const scopeChanged = targetScope !== existing.category;
+  if(scopeChanged && targetName.length > MAX_CATEGORY) return [{ code: 400, msg: `A category name must be ${MAX_CATEGORY} characters or fewer` }, null];
+
   const targetType = changes.type ?? existing.type;
   if(!canConvert(existing.type, targetType)){
     return [{ code: 409, msg: `A ${existing.type} field cannot be changed to ${targetType}. Delete it and create a new one instead` }, null];
   }
   const isOwner = existing.owner === (owner ?? '');
   const allowed = isOwner ? OWNER_EDITABLE : ANYONE_EDITABLE;
-  const rejected = Object.keys(changes).filter(k => k !== 'key' && k !== 'category' && !(k === 'type' && targetType === existing.type) && !allowed.includes(k));
+  const rejected = Object.keys(changes).filter(k => k !== 'key' && !(k === 'category' && !scopeChanged) && !(k === 'type' && targetType === existing.type) && !allowed.includes(k));
   if(rejected.length){
     return [{ code: 403, msg: `${rejected.join(', ')} can only be changed by ${existing.owner ? `the "${existing.owner}" extension` : 'the field\'s owner'}` }, null];
   }
@@ -135,7 +145,7 @@ export const updateField = async (key, changes = {}, { owner = null, category =
 
   const updates = {};
   for(const property of allowed){
-    if(changes[property] !== undefined) updates[property] = normalized[property];
+    if(property !== 'category' && changes[property] !== undefined) updates[property] = normalized[property];
   }
   if(targetType !== existing.type){
     /* Converting: the type changes, and what only made sense for the old type goes with it. */
@@ -143,14 +153,29 @@ export const updateField = async (key, changes = {}, { owner = null, category =
     updates.options = normalized.options;
     updates.suggest = normalized.suggest;
   }
+  if(scopeChanged){
+    const clash = await keyClash(existing.key, targetScope, existing.category);
+    if(clash) return [clash, null];
+    updates.category = targetScope;
+  }
   if(!Object.keys(updates).length) return [{ code: 400, msg: 'No changes provided' }, null];
 
   const refused = await guard(EVENTS.fieldBeforeUpdate, { field: existing, changes: updates, actor: owner ?? '' });
   if(refused) return [refused, null];
 
   try {
-    const [field] = await db.update(kempoInventoryField).set(updates)
-      .where(and(eq(kempoInventoryField.key, key), eq(kempoInventoryField.category, existing.category))).returning();
+    const field = await db.transaction(async tx => {
+      if(scopeChanged && targetScope){
+        /* Moving into a category: it has to exist as a record, as it does when a field is created there. */
+        const now = new Date();
+        await tx.insert(kempoInventoryCategory)
+          .values({ id: newId(), key: targetScope, name: targetName, image: null, created: now, updated: now })
+          .onConflictDoNothing();
+      }
+      const [updated] = await tx.update(kempoInventoryField).set(updates)
+        .where(and(eq(kempoInventoryField.key, key), eq(kempoInventoryField.category, existing.category))).returning();
+      return updated;
+    });
     await notify(EVENTS.fieldUpdated, { field, previous: existing, actor: owner ?? '' });
     return [null, field];
   } catch {

package/server/utils/importExport.js

@@ -2,10 +2,11 @@ import db from 'kempo/server/db/index.js';
 import { asc } from 'drizzle-orm';
 import { kempoInventoryItem, kempoInventoryCategory } from '../db/schema.js';
 import { getFields } from './fields.js';
-import { getItemBySku, createItem, updateItem, adjustQuantity } from './items.js';
+import { getItemBySku, createItem, updateItem, adjustQuantity, decimalsAllowed } from './items.js';
 import { getCategories, saveCategory } from './categories.js';
 import { applicableFields, coerceValues } from './fieldTypes.js';
 import { normalizeTags } from './tags.js';
+import { toQuantity } from './quantity.js';
 import { tidyCategory, categoryKey, MAX_CATEGORY } from './categoryLogic.js';
 import { readMedia } from './media.js';
 
@@ -81,12 +82,13 @@ export const buildExport = async ({ withMedia = false } = {}) => {
         values[field.key] = value;
       }
     }
-    return { sku: row.sku, name: row.name, category: row.category, quantity: row.quantity, tags: row.tags ?? [], description: row.description, fields: values };
+    return { sku: row.sku, name: row.name, category: row.category, quantity: row.quantity, unit: row.unit ?? '', tags: row.tags ?? [], description: row.description, fields: values };
   });
 
   const categories = categoryRows.map(row => ({
     name: row.name,
     description: row.description,
+    unit: row.unit ?? '',
     tags: row.tags ?? [],
     ...(row.image && pathOf.has(row.image) ? { image: pathOf.get(row.image) } : {}),
   }));
@@ -149,12 +151,14 @@ export const importData = async ({ items = [], categories = [], onMatch = 'skip'
     if(given(row.description)) changes.description = String(row.description);
     if(given(row.tags)) changes.tags = row.tags;
     if(given(row.image)) changes.image = row.image;
+    if(given(row.unit)) changes.unit = String(row.unit);
     const [error] = await saveCategory(name, changes, { userId });
     if(error){ result.action = 'error'; result.message = error.msg; summary.errors++; continue; }
     known.add(categoryKey(name));
     exists ? summary.categoriesUpdated++ : summary.categoriesCreated++;
   }
 
+  const decimals = await decimalsAllowed();
   for(const [index, row] of items.entries()){
     const result = { row: index + 1, sku: String(row?.sku ?? '').trim(), name: String(row?.name ?? '').trim(), action: '', message: '' };
     results.push(result);
@@ -174,8 +178,8 @@ export const importData = async ({ items = [], categories = [], onMatch = 'skip'
     }
     let quantity;
     if(given(row.quantity)){
-      quantity = Number(row.quantity);
-      if(!Number.isInteger(quantity) || quantity < 0){ fail(result, 'Quantity must be a non-negative whole number'); continue; }
+      quantity = toQuantity(row.quantity, decimals);
+      if(Number.isNaN(quantity) || quantity < 0){ fail(result, decimals ? 'Quantity must be a non-negative number' : 'Quantity must be a non-negative whole number'); continue; }
     }
     if(!existing && !result.name){ fail(result, 'Missing name'); continue; }
 
@@ -206,6 +210,7 @@ export const importData = async ({ items = [], categories = [], onMatch = 'skip'
       if(given(row.name)) changes.name = result.name;
       if(given(row.description)) changes.description = String(row.description);
       if(given(row.category)) changes.category = category;
+      if(given(row.unit)) changes.unit = String(row.unit);
       if(tags !== undefined) changes.tags = tags;
       const [error] = await updateItem(existing.id, { ...changes, userId });
       if(error && !(error.code === 400 && error.msg === 'No changes provided')){ fail(result, error.msg); continue; }
@@ -220,7 +225,7 @@ export const importData = async ({ items = [], categories = [], onMatch = 'skip'
       if(dryRun){ summary.created++; continue; }
       const [error, created] = await createItem({
         sku: result.sku, name: result.name, description: given(row.description) ? String(row.description) : '',
-        category, tags: tags ?? [], quantity: quantity ?? 0, fields: coerced, userId,
+        category, unit: given(row.unit) ? String(row.unit) : '', tags: tags ?? [], quantity: quantity ?? 0, fields: coerced, userId,
       });
       if(error){ fail(result, error.msg); continue; }
       summary.created++;

package/server/utils/items.js

@@ -1,21 +1,34 @@
 import db from 'kempo/server/db/index.js';
 import { eq, and, or, ilike, sql, desc, asc, inArray } from 'drizzle-orm';
 import crypto from 'crypto';
-import { kempoInventoryItem, kempoInventoryMovement } from '../db/schema.js';
+import { getSetting } from 'kempo/server/sdk.js';
+import { kempoInventoryItem, kempoInventoryMovement, kempoInventoryCategory } from '../db/schema.js';
 import { getFields } from './fields.js';
 import { coerceValues, applicableFields, KEY_PATTERN, isEmpty } from './fieldTypes.js';
 import { EVENTS, guard, notify } from './hooks.js';
 import { tidyCategory, categoryKey, MAX_CATEGORY } from './categoryLogic.js';
 import { normalizeTags, tidyTag } from './tags.js';
+import { toQuantity, checkUnit } from './quantity.js';
 import { getAssets, checkAssets } from './media.js';
 import { lockedItemChanges, notYours, ownerLabel } from './ownership.js';
 
 const newId = () => crypto.randomBytes(8).toString('hex');
 
-const toInt = (value, fallback) => {
-  if(isEmpty(value)) return fallback;
-  const n = Number(value);
-  return Number.isInteger(n) ? n : NaN;
+/* Whether quantities may have decimal places (the decimal_quantity setting). */
+export const decimalsAllowed = async () => {
+  const [, value] = await getSetting('kempo-inventory', 'decimal_quantity', false);
+  return value === true || value === 'true';
+};
+
+/*
+  Each item's unit: its own if it has one, otherwise its category's. Read items are given `unit`
+  (its own) and `effectiveUnit` (the one to show).
+*/
+const withEffectiveUnits = async items => {
+  const categoryUnits = new Map();
+  const categories = await db.select({ key: kempoInventoryCategory.key, unit: kempoInventoryCategory.unit }).from(kempoInventoryCategory);
+  for(const category of categories) if(category.unit) categoryUnits.set(category.key, category.unit);
+  return items.map(item => ({ ...item, effectiveUnit: item.unit || categoryUnits.get(categoryKey(item.category)) || '' }));
 };
 
 const isUniqueViolation = error => (error?.code || error?.cause?.code) === '23505';
@@ -30,6 +43,7 @@ const shape = row => row && ({
   description: row.description,
   category: row.category,
   quantity: row.quantity,
+  unit: row.unit ?? '',
   tags: row.tags ?? [],
   fields: row.data ?? {},
   owner: row.owner,
@@ -132,7 +146,7 @@ export const getItems = async ({ q, category, tag, uncategorised = false, filter
     const rows = await db.select().from(kempoInventoryItem).where(where)
       .orderBy(asc(kempoInventoryItem.name), asc(kempoInventoryItem.id)).limit(limit).offset(offset);
     const [{ total }] = await db.select({ total: sql`count(*)::int` }).from(kempoInventoryItem).where(where);
-    const items = rows.map(shape);
+    const items = await withEffectiveUnits(rows.map(shape));
     return [null, { items, total, linked: await resolveLinks(items, fields), media: await resolveMedia(items, fields) }];
   } catch {
     return [{ code: 500, msg: 'Failed to retrieve items' }, null];
@@ -144,7 +158,8 @@ export const getItem = async id => {
   try {
     const [row] = await db.select().from(kempoInventoryItem).where(eq(kempoInventoryItem.id, id));
     if(!row) return [{ code: 404, msg: 'Item not found' }, null];
-    return [null, shape(row)];
+    const [item] = await withEffectiveUnits([shape(row)]);
+    return [null, item];
   } catch {
     return [{ code: 500, msg: 'Failed to retrieve item' }, null];
   }
@@ -155,7 +170,8 @@ export const getItemBySku = async sku => {
   try {
     const [row] = await db.select().from(kempoInventoryItem).where(eq(kempoInventoryItem.sku, sku));
     if(!row) return [{ code: 404, msg: 'Item not found' }, null];
-    return [null, shape(row)];
+    const [item] = await withEffectiveUnits([shape(row)]);
+    return [null, item];
   } catch {
     return [{ code: 500, msg: 'Failed to retrieve item' }, null];
   }
@@ -191,13 +207,13 @@ export const getMedia = async items => {
   `owner` (an extension name, from the server SDK only) marks the item as that extension's: see
   ownership.js for what that protects. It cannot be changed afterwards and is not part of the draft.
 */
-export const createItem = async ({ sku, name, description = '', category = '', tags = [], quantity, fields: values = {}, userId = '' } = {}, { owner = '' } = {}) => {
+export const createItem = async ({ sku, name, description = '', category = '', unit = '', tags = [], quantity, fields: values = {}, userId = '' } = {}, { owner = '' } = {}) => {
   /*
     The draft is what a before_create hook sees and may edit: it can fill in or change any
     property, or throw { code, msg } to refuse. Everything is validated after the hooks have run,
     so a hook cannot smuggle in a value that would not otherwise be accepted.
   */
-  const draft = { sku, name, description, category, tags, quantity, fields: { ...values } };
+  const draft = { sku, name, description, category, unit, tags, quantity, fields: { ...values } };
   const refused = await guard(EVENTS.itemBeforeCreate, { draft, userId, actor: owner });
   if(refused) return [refused, null];
 
@@ -209,8 +225,11 @@ export const createItem = async ({ sku, name, description = '', category = '', t
   if(cleanCategory.length > MAX_CATEGORY) return [{ code: 400, msg: `Category must be ${MAX_CATEGORY} characters or fewer` }, null];
   const [tagsError, cleanTags] = normalizeTags(draft.tags);
   if(tagsError) return [tagsError, null];
-  const qty = toInt(draft.quantity, 0);
-  if(Number.isNaN(qty) || qty < 0) return [{ code: 400, msg: 'Quantity must be a non-negative whole number' }, null];
+  const [unitError, cleanUnit] = checkUnit(draft.unit);
+  if(unitError) return [unitError, null];
+  const decimals = await decimalsAllowed();
+  const qty = isEmpty(draft.quantity) ? 0 : toQuantity(draft.quantity, decimals);
+  if(Number.isNaN(qty) || qty < 0) return [{ code: 400, msg: decimals ? 'Quantity must be a non-negative number' : 'Quantity must be a non-negative whole number' }, null];
 
   const [fieldsError, fields] = await getFields();
   if(fieldsError) return [fieldsError, null];
@@ -223,7 +242,7 @@ export const createItem = async ({ sku, name, description = '', category = '', t
   try {
     const row = await db.transaction(async tx => {
       const [created] = await tx.insert(kempoInventoryItem).values({
-        id: newId(), sku: cleanSku, name: cleanName, description: String(draft.description ?? '').trim(), category: cleanCategory, tags: cleanTags,
+        id: newId(), sku: cleanSku, name: cleanName, description: String(draft.description ?? '').trim(), category: cleanCategory, unit: cleanUnit, tags: cleanTags,
         quantity: qty, data: withoutNulls(coerced), owner, created: now, updated: now,
       }).returning();
       if(qty > 0){
@@ -234,7 +253,7 @@ export const createItem = async ({ sku, name, description = '', category = '', t
       }
       return created;
     });
-    const item = shape(row);
+    const [item] = await withEffectiveUnits([shape(row)]);
     await notify(EVENTS.itemCreated, { item, userId, actor: owner });
     return [null, item];
   } catch(error) {
@@ -247,7 +266,7 @@ export const createItem = async ({ sku, name, description = '', category = '', t
   Updates sku, name, description and custom field values. Quantity is not editable here: it only
   changes through adjustQuantity, which keeps the movement history honest.
 */
-export const updateItem = async (id, { sku, name, description, category, tags, fields: values, userId = '' } = {}, { owner = '' } = {}) => {
+export const updateItem = async (id, { sku, name, description, category, unit, tags, fields: values, userId = '' } = {}, { owner = '' } = {}) => {
   const [lookupError, existing] = await getItem(id);
   if(lookupError) return [lookupError, null];
 
@@ -256,6 +275,7 @@ export const updateItem = async (id, { sku, name, description, category, tags, f
   if(name !== undefined) changes.name = name;
   if(description !== undefined) changes.description = description;
   if(category !== undefined) changes.category = category;
+  if(unit !== undefined) changes.unit = unit;
   if(tags !== undefined) changes.tags = tags;
   if(values !== undefined) changes.fields = { ...values };
 
@@ -276,6 +296,11 @@ export const updateItem = async (id, { sku, name, description, category, tags, f
     if(!updates.name) return [{ code: 400, msg: 'Name cannot be empty' }, null];
   }
   if(changes.description !== undefined) updates.description = String(changes.description).trim();
+  if(changes.unit !== undefined){
+    const [unitError, cleanUnit] = checkUnit(changes.unit);
+    if(unitError) return [unitError, null];
+    updates.unit = cleanUnit;
+  }
   if(changes.category !== undefined){
     updates.category = tidyCategory(changes.category);
     if(updates.category.length > MAX_CATEGORY) return [{ code: 400, msg: `Category must be ${MAX_CATEGORY} characters or fewer` }, null];
@@ -304,7 +329,7 @@ export const updateItem = async (id, { sku, name, description, category, tags, f
   try {
     const [row] = await db.update(kempoInventoryItem).set(updates).where(eq(kempoInventoryItem.id, id)).returning();
     if(!row) return [{ code: 404, msg: 'Item not found' }, null];
-    const item = shape(row);
+    const [item] = await withEffectiveUnits([shape(row)]);
     await notify(EVENTS.itemUpdated, { item, previous: existing, userId, actor: owner });
     return [null, item];
   } catch(error) {
@@ -340,35 +365,49 @@ export const deleteItem = async (id, { userId = '', owner = '' } = {}) => {
   so concurrent adjustments cannot oversell.
 */
 /* Anyone may adjust quantity, owned item or not; `owner` only tells hooks which extension did it. */
-export const adjustQuantity = async (id, { delta, reason = 'adjustment', note = '', userId = '', owner = '' } = {}) => {
+export const adjustQuantity = async (id, { delta, set, reason = 'adjustment', note = '', userId = '', owner = '' } = {}) => {
   const [lookupError, existing] = await getItem(id);
   if(lookupError) return [lookupError, null];
 
-  const draft = { delta, reason, note };
+  /* `set` is the count to end at; the change is worked out from the count held when it is written. */
+  const decimals = await decimalsAllowed();
+  const setting = set !== undefined && set !== null && set !== '';
+  const target = setting ? toQuantity(set, decimals) : NaN;
+  if(setting && (Number.isNaN(target) || target < 0)) return [{ code: 400, msg: decimals ? 'The quantity must be a non-negative number' : 'The quantity must be a non-negative whole number' }, null];
+  if(setting && target === existing.quantity) return [null, existing];
+
+  const draft = { delta: setting ? toQuantity(target - existing.quantity, true) : delta, reason, note };
   const refused = await guard(EVENTS.quantityBeforeAdjust, { item: existing, draft, userId, actor: owner });
   if(refused) return [refused, null];
 
-  const change = toInt(draft.delta, NaN);
-  if(Number.isNaN(change) || change === 0) return [{ code: 400, msg: 'delta must be a non-zero whole number' }, null];
+  const requested = toQuantity(draft.delta, decimals);
+  if(!setting && (Number.isNaN(requested) || requested === 0)) return [{ code: 400, msg: decimals ? 'delta must be a non-zero number' : 'delta must be a non-zero whole number' }, null];
 
   try {
     const result = await db.transaction(async tx => {
+      const [locked] = await tx.select({ quantity: kempoInventoryItem.quantity }).from(kempoInventoryItem)
+        .where(eq(kempoInventoryItem.id, id)).for('update');
+      if(!locked) return { missing: true };
+      const change = setting ? toQuantity(target - locked.quantity, true) : requested;
+      if(change === 0) return { unchanged: true };
       const [row] = await tx.update(kempoInventoryItem)
         .set({ quantity: sql`${kempoInventoryItem.quantity} + ${change}`, updated: new Date() })
         .where(and(eq(kempoInventoryItem.id, id), sql`${kempoInventoryItem.quantity} + ${change} >= 0`))
         .returning();
-      if(!row) return null;
+      if(!row) return { insufficient: true };
       const [movement] = await tx.insert(kempoInventoryMovement).values({
         id: newId(), itemId: id, delta: change, quantityAfter: row.quantity,
-        reason: String(draft.reason || 'adjustment'), note: String(draft.note || ''), userId, created: new Date(),
+        reason: String(draft.reason ?? 'adjustment'), note: String(draft.note || ''), userId, created: new Date(),
       }).returning();
-      return { row, movement };
+      return { row, movement, change };
     });
-    if(!result) return [{ code: 409, msg: 'Insufficient quantity' }, null];
+    if(result.missing) return [{ code: 404, msg: 'Item not found' }, null];
+    if(result.unchanged) return [null, existing];
+    if(result.insufficient) return [{ code: 409, msg: 'Insufficient quantity' }, null];
 
-    const item = shape(result.row);
+    const [item] = await withEffectiveUnits([shape(result.row)]);
     await notify(EVENTS.quantityAdjusted, {
-      item, previousQuantity: item.quantity - change, delta: change,
+      item, previousQuantity: toQuantity(item.quantity - result.change, true), delta: result.change,
       reason: result.movement.reason, note: result.movement.note, movement: result.movement, userId, actor: owner,
     });
     return [null, item];
@@ -406,14 +445,15 @@ class Refusal {
 export const adjustQuantityMany = async (changes, { reason = 'adjustment', note = '', ref = '', userId = '', owner = '' } = {}) => {
   if(!Array.isArray(changes) || !changes.length) return [{ code: 400, msg: 'changes must be a non-empty list' }, null];
 
+  const decimals = await decimalsAllowed();
   const totals = new Map();
   for(const change of changes){
     const id = String(change?.id ?? '');
-    const delta = toInt(change?.delta, NaN);
+    const delta = toQuantity(change?.delta, decimals);
     if(!id) return [{ code: 400, msg: 'Every change needs an item id' }, null];
-    if(Number.isNaN(delta)) return [{ code: 400, msg: 'Every delta must be a whole number' }, null];
+    if(Number.isNaN(delta)) return [{ code: 400, msg: decimals ? 'Every delta must be a number' : 'Every delta must be a whole number' }, null];
     const entry = totals.get(id) ?? { id, delta: 0, reason: change.reason, note: change.note };
-    entry.delta += delta;
+    entry.delta = toQuantity(entry.delta + delta, true);
     totals.set(id, entry);
   }
   /* In a fixed order, so two overlapping calls lock rows the same way round and cannot deadlock. */
@@ -435,8 +475,8 @@ export const adjustQuantityMany = async (changes, { reason = 'adjustment', note
     const draft = { delta: entry.delta, reason: entry.reason ?? reason, note: entry.note ?? note };
     const refused = await guard(EVENTS.quantityBeforeAdjust, { item: existing.get(entry.id), draft, userId, actor: owner });
     if(refused) return [refused, null];
-    const delta = toInt(draft.delta, NaN);
-    if(Number.isNaN(delta) || delta === 0) return [{ code: 400, msg: 'delta must be a non-zero whole number' }, null];
+    const delta = toQuantity(draft.delta, decimals);
+    if(Number.isNaN(delta) || delta === 0) return [{ code: 400, msg: decimals ? 'delta must be a non-zero number' : 'delta must be a non-zero whole number' }, null];
     drafts.set(entry.id, { delta, reason: String(draft.reason || 'adjustment'), note: String(draft.note || '') });
   }
 
@@ -463,7 +503,7 @@ export const adjustQuantityMany = async (changes, { reason = 'adjustment', note
       const item = shape(row);
       items.push(item);
       await notify(EVENTS.quantityAdjusted, {
-        item, previousQuantity: item.quantity - delta, delta, reason: movement.reason, note: movement.note, movement, userId, actor: owner,
+        item, previousQuantity: toQuantity(item.quantity - delta, true), delta, reason: movement.reason, note: movement.note, movement, userId, actor: owner,
       });
     }
     return [null, { items }];

package/server/utils/quantity.js

@@ -0,0 +1,19 @@
+/*
+  Quantity and unit rules, kept pure so they can be tested without a database. A quantity keeps at
+  most four decimal places, and is a whole number unless the decimal_quantity setting allows fractions.
+*/
+export const SCALE = 4;
+export const MAX_UNIT = 20;
+
+export const toQuantity = (value, decimals = false) => {
+  const number = Number(value);
+  if(!Number.isFinite(number)) return NaN;
+  if(!decimals && !Number.isInteger(number)) return NaN;
+  return Math.round(number * 10 ** SCALE) / 10 ** SCALE;
+};
+
+export const checkUnit = value => {
+  const unit = String(value ?? '').trim().replace(/\s+/g, ' ');
+  if(unit.length > MAX_UNIT) return [{ code: 400, msg: `A unit must be ${MAX_UNIT} characters or fewer` }, null];
+  return [null, unit];
+};

package/update.js

@@ -8,6 +8,14 @@ import { getSetting, setSetting, deleteSetting } from 'kempo/server/sdk.js';
   this on a database that already has the change is harmless.
 */
 export default async () => {
+  // Next: quantities can have decimal places (the decimal_quantity setting), and items and categories can have a unit. A quantity column changes type only while it is still an integer.
+  for(const [table, column] of [['kempoInventoryItem', 'quantity'], ['kempoInventoryMovement', 'delta'], ['kempoInventoryMovement', 'quantityAfter']]){
+    const [column_] = [...await db.execute(sql`SELECT data_type AS "type" FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = ${table} AND column_name = ${column}`)];
+    if(column_?.type === 'integer') await db.execute(sql.raw(`ALTER TABLE "${table}" ALTER COLUMN "${column}" TYPE numeric(14,4) USING "${column}"::numeric`));
+  }
+  await db.execute(sql`ALTER TABLE "kempoInventoryItem" ADD COLUMN IF NOT EXISTS "unit" text NOT NULL DEFAULT ''`);
+  await db.execute(sql`ALTER TABLE "kempoInventoryCategory" ADD COLUMN IF NOT EXISTS "unit" text NOT NULL DEFAULT ''`);
+
   // Stock became quantity everywhere. The permission to change it was kempo-inventory:stock:adjust: move every grant to the new name, so nobody loses the right.
   const OLD = 'kempo-inventory:stock:adjust';
   const NEW = 'kempo-inventory:quantity:adjust';