@openmrs/esm-framework 9.0.3-pre.4321 → 9.0.3-pre.4342

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 3 files with swc (106.28ms)
+[0] Successfully compiled: 3 files with swc (120.81ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/docs/API.md

@@ -179,6 +179,7 @@
 - [useAbortController](functions/useAbortController.md)
 - [useDebounce](functions/useDebounce.md)
 - [useOpenmrsSWR](functions/useOpenmrsSWR.md)
+- [ageAsDuration](functions/ageAsDuration.md)
 - [age](functions/age.md)
 - [getPatientName](functions/getPatientName.md)
 - [~~displayName~~](functions/displayName.md)
@@ -284,6 +285,11 @@
 - [formatDatetime](functions/formatDatetime.md)
 - [convertToLocaleCalendar](functions/convertToLocaleCalendar.md)
 - [formatDuration](functions/formatDuration.md)
+- [parseDateInput](functions/parseDateInput.md)
+- [duration](functions/duration.md)
+- [formatDurationBetween](functions/formatDurationBetween.md)
+- [DurationOptions](interfaces/DurationOptions.md)
+- [DurationOptionsWithFormat](interfaces/DurationOptionsWithFormat.md)
 
 ## Dynamic Loading
 

package/docs/functions/age.md

@@ -4,7 +4,7 @@
 
 > **age**(`birthDate`, `currentDate`): `null` \| `string`
 
-Defined in: [packages/framework/esm-utils/src/age-helpers.ts:20](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/age-helpers.ts#L20)
+Defined in: [packages/framework/esm-utils/src/age-helpers.ts:83](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/age-helpers.ts#L83)
 
 Gets a human readable and locale supported representation of a person's age, given their birthDate,
 The representation logic follows the guideline here:
@@ -30,3 +30,14 @@ Optional. If provided, calculates the age of the person at the provided currentD
 `null` \| `string`
 
 A human-readable string version of the age.
+
+## Examples
+
+```ts
+age('2020-02-29', '2024-07-30') // => '4 yrs, 5 mths'
+```
+
+```ts
+// String dates with partial precision are supported
+age('2000', '2024-07-30') // => '24 yrs'
+```

package/docs/functions/ageAsDuration.md

@@ -0,0 +1,46 @@
+[O3 Framework](../API.md) / ageAsDuration
+
+# Function: ageAsDuration()
+
+> **ageAsDuration**(`birthDate`, `currentDate`): `null` \| `DurationInput`
+
+Defined in: [packages/framework/esm-utils/src/age-helpers.ts:22](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/age-helpers.ts#L22)
+
+Gets the age of a person as a structured duration object, following NHS Digital guidelines
+(Tables 7 and 8) for which units to include based on the person's age.
+
+## Parameters
+
+### birthDate
+
+`ConfigType`
+
+The birthDate. If null, returns null.
+
+### currentDate
+
+`ConfigType` = `...`
+
+Optional. If provided, calculates the age at the provided date instead of now.
+
+## Returns
+
+`null` \| `DurationInput`
+
+A DurationInput object, or null if birthDate is null or unparseable.
+
+## See
+
+https://webarchive.nationalarchives.gov.uk/ukgwa/20160921162509mp_/http://systems.digital.nhs.uk/data/cui/uig/patben.pdf
+
+## Examples
+
+```ts
+// For infants, returns fine-grained units
+ageAsDuration('2024-07-29', '2024-07-30') // => { hours: 24 }
+```
+
+```ts
+// For adults (>= 18), returns years only
+ageAsDuration('2000-01-15', '2024-07-30') // => { years: 24 }
+```

package/docs/functions/duration.md

@@ -0,0 +1,60 @@
+[O3 Framework](../API.md) / duration
+
+# Function: duration()
+
+> **duration**(`startDate`, `endDate`, `options?`): `null` \| `DurationInput`
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:645](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L645)
+
+Calculates the duration between two dates as a structured duration object.
+
+When called with no options or a single unit string, the unit is auto-selected
+using dayjs relativeTime thresholds:
+- < 45 seconds → seconds
+- < 45 minutes → minutes
+- < 22 hours → hours
+- < 26 days → days
+- < 11 months → months
+- otherwise → years
+
+With a [DurationOptions](../interfaces/DurationOptions.md) object, you can override thresholds and/or request
+a multi-unit decomposition via largestUnit/smallestUnit.
+
+## Parameters
+
+### startDate
+
+`ConfigType`
+
+The start date. If null, returns null.
+
+### endDate
+
+`ConfigType` = `...`
+
+Optional. Defaults to now.
+
+### options?
+
+A unit string for single-unit output, or a DurationOptions object.
+
+[`DurationUnit`](../type-aliases/DurationUnit.md) | [`DurationOptions`](../interfaces/DurationOptions.md)
+
+## Returns
+
+`null` \| `DurationInput`
+
+A DurationInput object, or null if either date is null or unparseable.
+
+## Examples
+
+```ts
+// Auto-selects the appropriate unit
+duration('2022-01-01', '2024-07-30') // => { years: 2 }
+```
+
+```ts
+// Multi-unit decomposition
+duration('2022-01-01', '2024-07-30', { largestUnit: 'year', smallestUnit: 'day' })
+// => { years: 2, months: 6, days: 29 }
+```

package/docs/functions/formatDurationBetween.md

@@ -0,0 +1,53 @@
+[O3 Framework](../API.md) / formatDurationBetween
+
+# Function: formatDurationBetween()
+
+> **formatDurationBetween**(`startDate`, `endDate`, `options?`): `null` \| `string`
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:707](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L707)
+
+Calculates the duration between two dates and formats it as a locale-aware string.
+Uses the same unit-selection logic as [duration](duration.md) and delegates formatting
+to [formatDuration](formatDuration.md).
+
+## Parameters
+
+### startDate
+
+`ConfigType`
+
+The start date. If null, returns null.
+
+### endDate
+
+`ConfigType` = `...`
+
+Optional. Defaults to now.
+
+### options?
+
+A unit string for single-unit output, or a [DurationOptionsWithFormat](../interfaces/DurationOptionsWithFormat.md) object.
+  The `formatOptions` field is passed to Intl.DurationFormat (defaults to short style).
+
+[`DurationUnit`](../type-aliases/DurationUnit.md) | [`DurationOptionsWithFormat`](../interfaces/DurationOptionsWithFormat.md)
+
+## Returns
+
+`null` \| `string`
+
+A formatted duration string, or null if either date is null or unparseable.
+
+## Examples
+
+```ts
+formatDurationBetween('2022-01-01', '2024-07-30') // => '2 yrs'
+```
+
+```ts
+// Multi-unit with long-form formatting
+formatDurationBetween('2022-01-01', '2024-07-30', {
+  largestUnit: 'year',
+  smallestUnit: 'day',
+  formatOptions: { style: 'long' },
+}) // => '2 years, 6 months, 29 days'
+```

package/docs/functions/parseDateInput.md

@@ -0,0 +1,31 @@
+[O3 Framework](../API.md) / parseDateInput
+
+# Function: parseDateInput()
+
+> **parseDateInput**(`dateInput`, `referenceDate`): `null` \| `Dayjs`
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:455](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L455)
+
+Parses a date input into a dayjs object. String inputs are interpreted using
+any-date-parser with corrections for its month/day representation differences
+with dayjs. Non-string inputs are passed directly to dayjs.
+
+## Parameters
+
+### dateInput
+
+`ConfigType`
+
+The date to parse.
+
+### referenceDate
+
+`Dayjs`
+
+Used as the base when resolving partial string dates (e.g., '2000' resolves missing fields from this date).
+
+## Returns
+
+`null` \| `Dayjs`
+
+A dayjs object, or null if the string could not be parsed.

package/docs/interfaces/DurationOptions.md

@@ -0,0 +1,41 @@
+[O3 Framework](../API.md) / DurationOptions
+
+# Interface: DurationOptions
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:495](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L495)
+
+## Extended by
+
+- [`DurationOptionsWithFormat`](DurationOptionsWithFormat.md)
+
+## Properties
+
+### largestUnit?
+
+> `optional` **largestUnit**: `"auto"` \| [`DurationUnit`](../type-aliases/DurationUnit.md)
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:503](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L503)
+
+Coarsest unit to include. Accepts 'auto' (default when smallestUnit is set),
+which resolves to the largest non-zero unit or smallestUnit, whichever is greater.
+Mirrors Temporal.Duration.round() behavior.
+
+***
+
+### smallestUnit?
+
+> `optional` **smallestUnit**: [`DurationUnit`](../type-aliases/DurationUnit.md)
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:505](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L505)
+
+Finest unit to include. Defaults to largestUnit when largestUnit is an explicit unit, giving a single-unit result.
+
+***
+
+### thresholds?
+
+> `optional` **thresholds**: `Partial`\<`Record`\<[`DurationUnit`](../type-aliases/DurationUnit.md), `number`\>\>
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:497](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L497)
+
+Override auto-selection thresholds. Each value is in the unit's own terms (e.g., seconds: 30 means "use seconds if < 30 seconds").

package/docs/interfaces/DurationOptionsWithFormat.md

@@ -0,0 +1,63 @@
+[O3 Framework](../API.md) / DurationOptionsWithFormat
+
+# Interface: DurationOptionsWithFormat
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:508](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L508)
+
+## Extends
+
+- [`DurationOptions`](DurationOptions.md)
+
+## Properties
+
+### formatOptions?
+
+> `optional` **formatOptions**: `Partial`\<`ResolvedDurationFormatOptions`\>
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:510](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L510)
+
+Options passed to Intl.DurationFormat. Defaults to { style: 'short', localeMatcher: 'lookup' }.
+
+***
+
+### largestUnit?
+
+> `optional` **largestUnit**: `"auto"` \| [`DurationUnit`](../type-aliases/DurationUnit.md)
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:503](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L503)
+
+Coarsest unit to include. Accepts 'auto' (default when smallestUnit is set),
+which resolves to the largest non-zero unit or smallestUnit, whichever is greater.
+Mirrors Temporal.Duration.round() behavior.
+
+#### Inherited from
+
+[`DurationOptions`](DurationOptions.md).[`largestUnit`](DurationOptions.md#largestunit)
+
+***
+
+### smallestUnit?
+
+> `optional` **smallestUnit**: [`DurationUnit`](../type-aliases/DurationUnit.md)
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:505](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L505)
+
+Finest unit to include. Defaults to largestUnit when largestUnit is an explicit unit, giving a single-unit result.
+
+#### Inherited from
+
+[`DurationOptions`](DurationOptions.md).[`smallestUnit`](DurationOptions.md#smallestunit)
+
+***
+
+### thresholds?
+
+> `optional` **thresholds**: `Partial`\<`Record`\<[`DurationUnit`](../type-aliases/DurationUnit.md), `number`\>\>
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:497](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L497)
+
+Override auto-selection thresholds. Each value is in the unit's own terms (e.g., seconds: 30 means "use seconds if < 30 seconds").
+
+#### Inherited from
+
+[`DurationOptions`](DurationOptions.md).[`thresholds`](DurationOptions.md#thresholds)

package/docs/interfaces/ExtensionSlotProps.md

@@ -238,7 +238,7 @@ aria-owns.
 
 ### aria-current?
 
-> `optional` **aria-current**: `boolean` \| `"date"` \| `"false"` \| `"time"` \| `"true"` \| `"location"` \| `"page"` \| `"step"`
+> `optional` **aria-current**: `boolean` \| `"false"` \| `"time"` \| `"date"` \| `"true"` \| `"location"` \| `"page"` \| `"step"`
 
 Defined in: node\_modules/@types/react/index.d.ts:2661
 
@@ -1187,7 +1187,7 @@ Defined in: node\_modules/@types/react/index.d.ts:2942
 
 ### inputMode?
 
-> `optional` **inputMode**: `"search"` \| `"numeric"` \| `"text"` \| `"none"` \| `"url"` \| `"tel"` \| `"email"` \| `"decimal"`
+> `optional` **inputMode**: `"numeric"` \| `"search"` \| `"text"` \| `"none"` \| `"url"` \| `"tel"` \| `"email"` \| `"decimal"`
 
 Defined in: node\_modules/@types/react/index.d.ts:2969
 

package/docs/type-aliases/DurationUnit.md

@@ -0,0 +1,9 @@
+[O3 Framework](../API.md) / DurationUnit
+
+# Type Alias: DurationUnit
+
+> **DurationUnit** = `DurationUnitPlural` \| `DurationUnitSingular`
+
+Defined in: [packages/framework/esm-utils/src/dates/date-util.ts:493](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/dates/date-util.ts#L493)
+
+Accepts both singular ('year') and plural ('years') forms, mirroring Temporal.Duration.round().

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-framework",
-  "version": "9.0.3-pre.4321",
+  "version": "9.0.3-pre.4342",
   "license": "MPL-2.0",
   "type": "module",
   "module": "dist/index.js",
@@ -59,24 +59,24 @@
     "access": "public"
   },
   "dependencies": {
-    "@openmrs/esm-api": "9.0.3-pre.4321",
-    "@openmrs/esm-config": "9.0.3-pre.4321",
-    "@openmrs/esm-context": "9.0.3-pre.4321",
-    "@openmrs/esm-dynamic-loading": "9.0.3-pre.4321",
-    "@openmrs/esm-emr-api": "9.0.3-pre.4321",
-    "@openmrs/esm-error-handling": "9.0.3-pre.4321",
-    "@openmrs/esm-expression-evaluator": "9.0.3-pre.4321",
-    "@openmrs/esm-extensions": "9.0.3-pre.4321",
-    "@openmrs/esm-feature-flags": "9.0.3-pre.4321",
-    "@openmrs/esm-globals": "9.0.3-pre.4321",
-    "@openmrs/esm-navigation": "9.0.3-pre.4321",
-    "@openmrs/esm-offline": "9.0.3-pre.4321",
-    "@openmrs/esm-react-utils": "9.0.3-pre.4321",
-    "@openmrs/esm-routes": "9.0.3-pre.4321",
-    "@openmrs/esm-state": "9.0.3-pre.4321",
-    "@openmrs/esm-styleguide": "9.0.3-pre.4321",
-    "@openmrs/esm-translations": "9.0.3-pre.4321",
-    "@openmrs/esm-utils": "9.0.3-pre.4321"
+    "@openmrs/esm-api": "9.0.3-pre.4342",
+    "@openmrs/esm-config": "9.0.3-pre.4342",
+    "@openmrs/esm-context": "9.0.3-pre.4342",
+    "@openmrs/esm-dynamic-loading": "9.0.3-pre.4342",
+    "@openmrs/esm-emr-api": "9.0.3-pre.4342",
+    "@openmrs/esm-error-handling": "9.0.3-pre.4342",
+    "@openmrs/esm-expression-evaluator": "9.0.3-pre.4342",
+    "@openmrs/esm-extensions": "9.0.3-pre.4342",
+    "@openmrs/esm-feature-flags": "9.0.3-pre.4342",
+    "@openmrs/esm-globals": "9.0.3-pre.4342",
+    "@openmrs/esm-navigation": "9.0.3-pre.4342",
+    "@openmrs/esm-offline": "9.0.3-pre.4342",
+    "@openmrs/esm-react-utils": "9.0.3-pre.4342",
+    "@openmrs/esm-routes": "9.0.3-pre.4342",
+    "@openmrs/esm-state": "9.0.3-pre.4342",
+    "@openmrs/esm-styleguide": "9.0.3-pre.4342",
+    "@openmrs/esm-translations": "9.0.3-pre.4342",
+    "@openmrs/esm-utils": "9.0.3-pre.4342"
   },
   "peerDependencies": {
     "dayjs": "1.x",
@@ -89,7 +89,7 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/typedoc-plugin-file-categories": "9.0.3-pre.4321",
+    "@openmrs/typedoc-plugin-file-categories": "9.0.3-pre.4342",
     "@swc/cli": "0.8.0",
     "@swc/core": "1.15.18",
     "@vitest/coverage-v8": "^4.0.18",