v0.7.0 — itemLabels module + slider formatter for eventToShortText

- New appTemplates.collectItemLabels (and lower-level helpers) gather form-level label overrides for an item across active CollectorClients with source attribution. Pure data layer; consumed by hds-forms-js HDSFormField and any patient/diary surface.
- New shared types: ItemLabels, ItemCustomization, ItemLabelSource, ItemLabelsWithSource, CollectItemLabelsOptions.
- eventToShortText handles type:slider — applies slider.display.{multiplier,precision,suffix} so EQ VAS 0.73 → "73 /100" everywhere events are summarised.

Author: perki

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-27
+
+### Added — itemLabels (per-form label overrides) module
+- `appTemplates.collectItemLabels(itemKey, contacts)` — gathers label overrides for an item across every active CollectorClient, attributing each entry to its source contact + form. Pure data layer; usable by any patient/diary surface, not just the form renderer.
+- `appTemplates.collectItemLabelsFromSections(itemKey, sources, opts?)` — lower-level helper for callers that already have section objects.
+- `appTemplates.getSectionItemLabels(section, itemKey)` — read labels for one item out of one section.
+- New types: `ItemLabels`, `ItemCustomization`, `ItemLabelSource`, `ItemLabelsWithSource`, `CollectItemLabelsOptions` (mirror the `section.itemCustomizations[itemKey].labels` shape; previously duplicated as inline interfaces in hds-forms-js).
+- Tests: `tests/itemLabels.test.js` (deduplication, requireLabels gating, options-map preservation, source attribution).
+
+### Changed — eventToShortText handles slider items
+- `eventToShortText` now formats `type: 'slider'` events using the item def's `slider.display` block (`multiplier`, `precision`, `suffix`). EQ VAS storing `0.73` now renders as `"73 /100"` everywhere events are summarised (diary card, timeline tooltips, etc.). Previously fell through to the generic number path and read `"0.73"`.
+
 ### Added
 - `HDSModelOverload` — apps can extend the shared HDS data-model at init time with their own itemDefs, streams, eventTypes, settings, datasources, or appStreams, plus refine translations and default `repeatable` values.
   - `HDSModel.load(url, overload?)` — merges the overload (after policy validation) before freezing.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hds-lib",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Health Data Safe - Library",
   "type": "module",
   "engines": {

tests/eventToShortText.test.js

@@ -249,6 +249,27 @@ describe('[ESTX] eventToShortText', () => {
     assert.equal(result, '42');
   });
 
+  it('[EST15s] slider with display.multiplier+suffix (EQ VAS 0.73 → 73 /100)', () => {
+    const itemDef = model.itemsDefs.forKey('wellbeing-self-rated-health');
+    if (!itemDef || itemDef.data.type !== 'slider') {
+      // Model not yet redeployed with slider — skip rather than fail
+      return;
+    }
+    const event = { content: 0.73, streamIds: ['wellbeing-self-rated-health'], type: 'ratio/proportion' };
+    const result = eventToShortText(event);
+    // Multiplier 100, precision 0 → "73"; suffix "/100" → "73 /100"
+    assert.ok(result === '73 /100' || result === '73', `Expected "73 /100" or "73", got: ${result}`);
+  });
+
+  it('[EST15s2] slider edge cases (min/max)', () => {
+    const itemDef = model.itemsDefs.forKey('wellbeing-self-rated-health');
+    if (!itemDef || itemDef.data.type !== 'slider') return;
+    const min = eventToShortText({ content: 0, streamIds: ['wellbeing-self-rated-health'], type: 'ratio/proportion' });
+    const max = eventToShortText({ content: 1, streamIds: ['wellbeing-self-rated-health'], type: 'ratio/proportion' });
+    assert.ok(min === '0 /100' || min === '0', `min: ${min}`);
+    assert.ok(max === '100 /100' || max === '100', `max: ${max}`);
+  });
+
   it('[EST16] ratio/generic select', () => {
     const itemDef = model.itemsDefs.forKey('body-vulva-wetness-feeling');
     assert.ok(itemDef, 'itemDef should exist');

tests/itemLabels.test.js

@@ -0,0 +1,147 @@
+import { assert } from './test-utils/deps-node.js';
+import {
+  getSectionItemLabels,
+  collectItemLabelsFromSections
+} from '../ts/appTemplates/itemLabels.ts';
+
+describe('[ILBL] itemLabels', function () {
+  describe('getSectionItemLabels', function () {
+    it('returns labels for an itemKey present in section', function () {
+      const section = {
+        key: 's1',
+        type: 'permanent',
+        name: { en: 'Section 1' },
+        itemKeys: ['function-mobility'],
+        itemCustomizations: {
+          'function-mobility': {
+            labels: { question: { en: 'MOBILITY' } }
+          }
+        }
+      };
+      const labels = getSectionItemLabels(section, 'function-mobility');
+      assert.deepEqual(labels, { question: { en: 'MOBILITY' } });
+    });
+
+    it('returns undefined when itemKey not in section', function () {
+      const section = { key: 's', type: 'permanent', name: { en: '' }, itemKeys: ['x'] };
+      assert.equal(getSectionItemLabels(section, 'function-mobility'), undefined);
+    });
+
+    it('returns undefined when no customizations', function () {
+      const section = { key: 's', type: 'permanent', name: { en: '' }, itemKeys: ['function-mobility'] };
+      assert.equal(getSectionItemLabels(section, 'function-mobility'), undefined);
+    });
+  });
+
+  describe('collectItemLabelsFromSections', function () {
+    const mkSection = (key, itemKeys, customs) => ({
+      key, type: 'permanent', name: { en: key }, itemKeys, itemCustomizations: customs
+    });
+
+    it('returns empty when no section uses the item', function () {
+      const sources = [{
+        section: mkSection('s', ['x'], {}),
+        source: { contactName: 'A' }
+      }];
+      assert.deepEqual(collectItemLabelsFromSections('function-mobility', sources), []);
+    });
+
+    it('returns one entry per section with non-empty labels and source attribution', function () {
+      const sources = [
+        {
+          section: mkSection('s1', ['function-mobility'], {
+            'function-mobility': { labels: { question: { en: 'MOBILITY' } } }
+          }),
+          source: { contactName: 'Dr. A', formTitle: { en: 'Form A' } }
+        },
+        {
+          section: mkSection('s2', ['function-mobility'], {
+            'function-mobility': { labels: { question: { en: 'Walking' } } }
+          }),
+          source: { contactName: 'Dr. B', formTitle: { en: 'Form B' } }
+        }
+      ];
+      const result = collectItemLabelsFromSections('function-mobility', sources);
+      assert.equal(result.length, 2);
+      assert.deepEqual(result[0].question, { en: 'MOBILITY' });
+      assert.equal(result[0].source.contactName, 'Dr. A');
+      assert.deepEqual(result[1].question, { en: 'Walking' });
+      assert.equal(result[1].source.contactName, 'Dr. B');
+    });
+
+    it('skips sections with no labels when requireLabels=true (default)', function () {
+      const sources = [
+        {
+          section: mkSection('s1', ['function-mobility'], {}),
+          source: { contactName: 'A' }
+        },
+        {
+          section: mkSection('s2', ['function-mobility'], {
+            'function-mobility': { labels: { question: { en: 'M' } } }
+          }),
+          source: { contactName: 'B' }
+        }
+      ];
+      const result = collectItemLabelsFromSections('function-mobility', sources);
+      assert.equal(result.length, 1);
+      assert.equal(result[0].source.contactName, 'B');
+    });
+
+    it('includes empty-label sections when requireLabels=false', function () {
+      const sources = [
+        {
+          section: mkSection('s', ['function-mobility'], {}),
+          source: { contactName: 'A' }
+        }
+      ];
+      const result = collectItemLabelsFromSections('function-mobility', sources, { requireLabels: false });
+      assert.equal(result.length, 1);
+      assert.equal(result[0].source.contactName, 'A');
+    });
+
+    it('deduplicates identical label sets (default)', function () {
+      const sameLabels = { labels: { question: { en: 'MOBILITY' } } };
+      const sources = [
+        {
+          section: mkSection('s1', ['function-mobility'], { 'function-mobility': sameLabels }),
+          source: { contactName: 'Dr. A' }
+        },
+        {
+          section: mkSection('s2', ['function-mobility'], { 'function-mobility': sameLabels }),
+          source: { contactName: 'Dr. B' }
+        }
+      ];
+      const result = collectItemLabelsFromSections('function-mobility', sources);
+      assert.equal(result.length, 1, 'identical labels collapse to one entry');
+      assert.equal(result[0].source.contactName, 'Dr. A', 'first occurrence wins');
+    });
+
+    it('keeps duplicates when deduplicate=false', function () {
+      const same = { labels: { question: { en: 'M' } } };
+      const sources = [
+        { section: mkSection('s1', ['m'], { m: same }), source: { contactName: 'A' } },
+        { section: mkSection('s2', ['m'], { m: same }), source: { contactName: 'B' } }
+      ];
+      const result = collectItemLabelsFromSections('m', sources, { deduplicate: false });
+      assert.equal(result.length, 2);
+    });
+
+    it('preserves the options override map', function () {
+      const sources = [{
+        section: mkSection('s', ['function-mobility'], {
+          'function-mobility': {
+            labels: {
+              question: { en: 'MOBILITY' },
+              options: { 0: { en: 'No problems walking' }, 1: { en: 'Unable to walk' } }
+            }
+          }
+        }),
+        source: { contactName: 'Dr. A' }
+      }];
+      const result = collectItemLabelsFromSections('function-mobility', sources);
+      assert.equal(result.length, 1);
+      assert.deepEqual(result[0].options[0], { en: 'No problems walking' });
+      assert.deepEqual(result[0].options[1], { en: 'Unable to walk' });
+    });
+  });
+});

ts/HDSModel/eventToShortText.ts

@@ -96,6 +96,10 @@ function formatWithItemDef (event: any, content: any, itemDef: any, model: any):
     return formatDatasource(content);
   }
 
+  if (type === 'slider') {
+    return formatSlider(content, itemDef);
+  }
+
   // number, text, composite, etc.
   if (typeof content === 'number') {
     return formatNumber(event.type, content, model);
@@ -166,6 +170,31 @@ function formatNumber (eventType: string, content: number, model: any): string {
   return symbol ? `${content} ${symbol}` : String(content);
 }
 
+/**
+ * Format a slider event: applies the item-def's slider.display block
+ * (multiplier / precision / suffix) so the readout matches what the patient
+ * saw when entering the value. Storage is the raw number; display rescales.
+ */
+function formatSlider (content: any, itemDef: any): string {
+  if (typeof content !== 'number') return String(content);
+  const display = itemDef.data?.slider?.display || {};
+  const multiplier: number = typeof display.multiplier === 'number' ? display.multiplier : 1;
+  let precision: number;
+  if (typeof display.precision === 'number') {
+    precision = display.precision;
+  } else if (multiplier >= 10) {
+    precision = 0;
+  } else {
+    const stepStr = String(itemDef.data?.step ?? 1);
+    const dot = stepStr.indexOf('.');
+    precision = dot >= 0 ? Math.min(stepStr.length - dot - 1, 4) : 0;
+  }
+  const scaled = content * multiplier;
+  const text = scaled.toFixed(precision);
+  const suffix = display.suffix ? localizeText(display.suffix) : '';
+  return suffix ? `${text} ${suffix}` : text;
+}
+
 function formatSelect (event: any, content: any, itemDef: any): string {
   let valueForSelect = content;
   let prefix = '';

ts/appTemplates/appTemplates.ts

@@ -10,4 +10,16 @@ export type { ContactInvite } from './Contact.ts';
 export type { AccessUpdateRequest, AccessUpdateRequestContent, AccessUpdateAction } from './interfaces.ts';
 export { getOrCreateBridgeAccess, recreateBridgeAccess, ensureBridgeAccess } from './bridgeAccess.ts';
 export type { BridgeAccessOptions, BridgeAccessResult } from './bridgeAccess.ts';
+export {
+  getSectionItemLabels,
+  collectItemLabelsFromSections,
+  collectItemLabels
+} from './itemLabels.ts';
+export type {
+  ItemLabels,
+  ItemCustomization,
+  ItemLabelSource,
+  ItemLabelsWithSource,
+  CollectItemLabelsOptions
+} from './itemLabels.ts';
 export { AppManagingAccount, AppClientAccount, Application, Collector, CollectorClient, CollectorInvite, CollectorRequest, Contact };

ts/appTemplates/itemLabels.ts

@@ -0,0 +1,131 @@
+/**
+ * Per-form item label overrides — types and helpers shared by form renderers
+ * (hds-forms-js) and patient/diary apps (hds-webapp, doctor-dashboard).
+ *
+ * Storage model: `CollectorRequest.sections[].itemCustomizations[itemKey].labels`
+ * — see ItemCustomization below. The same itemKey may be requested by multiple
+ * forms (across multiple contacts) with different labels. Renderers should
+ * surface every variant with attribution rather than picking one.
+ */
+
+import type { localizableText } from '../localizeText.ts';
+import type { CollectorSectionInterface } from './interfaces.ts';
+import type { Contact } from './Contact.ts';
+
+/**
+ * Per-form label overrides for an HDS item, applied on top of the item def.
+ * Mirrors `section.itemCustomizations[itemKey].labels`.
+ */
+export interface ItemLabels {
+  /** Override for the question label (replaces itemDef.label) */
+  question?: localizableText;
+  /** Override for the question description (replaces itemDef.description) */
+  description?: localizableText;
+  /** Per-option-value overrides for `select` fields, keyed by raw option value */
+  options?: Record<string | number, localizableText>;
+}
+
+/**
+ * Per-item customizations bag stored on a CollectorRequest section.
+ * Mirrors `itemCustomizations[itemKey]`.
+ */
+export interface ItemCustomization {
+  repeatable?: string;
+  reminder?: Record<string, unknown>;
+  labels?: ItemLabels;
+  [key: string]: unknown;
+}
+
+/** Identification of which form / contact a label override comes from. */
+export interface ItemLabelSource {
+  /** Display name of the requesting contact (e.g. "Dr. drandy"). */
+  contactName?: string;
+  /** Title of the form/data-set requesting the item. */
+  formTitle?: localizableText;
+  /** Section key within the form. */
+  sectionKey?: string;
+  /** Optional access/request key for tie-breaking. */
+  requestKey?: string;
+}
+
+/** A label override paired with the form/contact it originated from. */
+export interface ItemLabelsWithSource extends ItemLabels {
+  source: ItemLabelSource;
+}
+
+export interface CollectItemLabelsOptions {
+  /** Only include sections that explicitly override labels. Default true. */
+  requireLabels?: boolean;
+  /** Drop duplicate label sets keeping first occurrence. Default true. */
+  deduplicate?: boolean;
+}
+
+/** Read labels (if any) for itemKey from a single section. */
+export function getSectionItemLabels (section: CollectorSectionInterface, itemKey: string): ItemLabels | undefined {
+  if (!section.itemKeys.includes(itemKey)) return undefined;
+  const cust = section.itemCustomizations?.[itemKey] as ItemCustomization | undefined;
+  return cust?.labels;
+}
+
+function isEmptyLabels (l: ItemLabels | undefined): boolean {
+  return !l || (l.question == null && l.description == null && (l.options == null || Object.keys(l.options).length === 0));
+}
+
+/**
+ * Collect label overrides for itemKey from a list of (section, source) pairs.
+ * One entry per section that uses the item; deduplicated by label content.
+ */
+export function collectItemLabelsFromSections (
+  itemKey: string,
+  sources: Array<{ section: CollectorSectionInterface, source: ItemLabelSource }>,
+  opts: CollectItemLabelsOptions = {}
+): ItemLabelsWithSource[] {
+  const requireLabels = opts.requireLabels ?? true;
+  const deduplicate = opts.deduplicate ?? true;
+  const out: ItemLabelsWithSource[] = [];
+  const seen = new Set<string>();
+  for (const { section, source } of sources) {
+    if (!section.itemKeys.includes(itemKey)) continue;
+    const labels = getSectionItemLabels(section, itemKey) || {};
+    if (requireLabels && isEmptyLabels(labels)) continue;
+    const entry: ItemLabelsWithSource = { ...labels, source };
+    if (deduplicate) {
+      const sig = JSON.stringify({ q: entry.question, d: entry.description, o: entry.options });
+      if (seen.has(sig)) continue;
+      seen.add(sig);
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Gather labels for itemKey from every active CollectorClient on the given
+ * contacts. Each entry is attributed to the contact and form it came from.
+ */
+export function collectItemLabels (
+  itemKey: string,
+  contacts: Contact[],
+  opts: CollectItemLabelsOptions = {}
+): ItemLabelsWithSource[] {
+  const sources: Array<{ section: CollectorSectionInterface, source: ItemLabelSource }> = [];
+  for (const contact of contacts) {
+    for (const cc of contact.collectorClients) {
+      if (cc.status !== 'Active') continue;
+      const formTitle = cc.request?.title;
+      const sections = cc.getSections() || [];
+      for (const section of sections) {
+        sources.push({
+          section,
+          source: {
+            contactName: contact.displayName,
+            formTitle,
+            sectionKey: section.key,
+            requestKey: cc.key
+          }
+        });
+      }
+    }
+  }
+  return collectItemLabelsFromSections(itemKey, sources, opts);
+}