@xh/hoist 59.2.0 → 59.3.0

package/cmp/relativetimestamp/RelativeTimestamp.ts

@@ -4,23 +4,23 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
+import {inRange, isNil} from 'lodash';
+import moment from 'moment';
 import {box, span} from '@xh/hoist/cmp/layout';
 import {
+    BoxProps,
     hoistCmp,
     HoistModel,
+    HoistProps,
     managed,
     useLocalModel,
-    XH,
-    BoxProps,
-    HoistProps
+    XH
 } from '@xh/hoist/core';
 import {fmtCompactDate, fmtDateTime} from '@xh/hoist/format';
-import {action, observable, makeObservable, computed} from '@xh/hoist/mobx';
+import {action, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
-import {SECONDS} from '@xh/hoist/utils/datetime';
+import {DAYS, HOURS, LocalDate, SECONDS} from '@xh/hoist/utils/datetime';
 import {withDefault} from '@xh/hoist/utils/js';
-import {getLayoutProps} from '@xh/hoist/utils/react';
-import moment from 'moment';
 
 interface RelativeTimestampProps extends HoistProps, BoxProps {
     /**
@@ -63,11 +63,27 @@ export interface RelativeTimestampOptions {
 
     /** Time to which the input timestamp is compared. */
     relativeTo?: Date | number;
+
+    /**
+     * Governs if calendar days should be used for computing return label rather than the native
+     * moment 24-hour day.
+     *
+     * - Set to 'always' to ensure that any output less than 25 days will refer to the difference
+     *   in *calendar* days.
+     * - Set to 'useTimeForSameDay' for a similar behavior, but showing time differences if the
+     *   two dates are on the same calendar day.
+     * - Set to 'useTimeFor24Hr' for a similar behavior, but showing time differences for
+     *   any differences less than 24 hours.
+     *
+     * Null (default) will indicate that the standard behavior, based on moment, be used, whereby
+     * 'day' refers simply to a 24-hour time period and has no relation to the calendar.
+     */
+    localDateMode?: 'always' | 'useTimeForSameDay' | 'useTimeFor24Hr';
 }
 
 /**
  * A component to display the approximate amount of time between a given timestamp and now in a
- * friendly, human readable format (e.g. '6 minutes ago' or 'two hours from now').
+ * friendly, human-readable format (e.g. '6 minutes ago' or 'two hours from now').
  *
  * Automatically updates on a regular interval to stay current.
  */
@@ -75,13 +91,13 @@ export const [RelativeTimestamp, relativeTimestamp] = hoistCmp.withFactory<Relat
     displayName: 'RelativeTimestamp',
     className: 'xh-relative-timestamp',
 
-    render({className, ...props}, ref) {
+    render({className, bind, timestamp, options, ...rest}, ref) {
         const impl = useLocalModel(RelativeTimestampLocalModel);
 
         return box({
             className,
-            ...getLayoutProps(props),
             ref,
+            ...rest,
             item: span({
                 className: 'xh-title-tip',
                 item: impl.display,
@@ -94,7 +110,8 @@ export const [RelativeTimestamp, relativeTimestamp] = hoistCmp.withFactory<Relat
 class RelativeTimestampLocalModel extends HoistModel {
     override xhImpl = true;
 
-    @observable display = '';
+    @observable display: string = '';
+
     model: HoistModel;
 
     @managed
@@ -103,14 +120,14 @@ class RelativeTimestampLocalModel extends HoistModel {
         interval: 5 * SECONDS
     });
 
-    get timestamp() {
+    get timestamp(): Date | number {
         const {model} = this,
             {timestamp, bind} = this.componentProps;
         return withDefault(timestamp, model && bind ? model[bind] : null);
     }
 
     @computed.struct
-    get options() {
+    get options(): RelativeTimestampOptions {
         return this.componentProps.options;
     }
 
@@ -136,65 +153,114 @@ class RelativeTimestampLocalModel extends HoistModel {
 
 /**
  * Returns a string describing the approximate amount of time between a given timestamp and the
- * present moment in a friendly, human readable format.
+ * present moment in a friendly, human-readable format.
  */
 export function getRelativeTimestamp(
     timestamp: Date | number,
     options: RelativeTimestampOptions = {}
-) {
-    const relTo = options.relativeTo,
-        relFmt = relTo ? (fmtCompactDate(relTo, {asHtml: true}) as string) : null,
-        relFmtIsTime = relFmt?.includes(':');
+): string {
+    const {localDateMode} = options,
+        relFmt = !isNil(options.relativeTo)
+            ? (fmtCompactDate(options.relativeTo, {asHtml: true}) as string)
+            : null;
 
     options = {
         allowFuture: false,
         short: XH.isMobileApp,
-        futureSuffix: relTo ? `after ${relFmt}` : 'from now',
-        pastSuffix: relTo ? `before ${relFmt}` : 'ago',
-        equalString: relTo ? `${relFmtIsTime ? 'at' : 'on'}  ${relFmt}` : 'just now',
+        pastSuffix: defaultPastSuffix(relFmt),
+        futureSuffix: defaultFutureSuffix(relFmt, localDateMode),
+        equalString: defaultEqualString(relFmt, localDateMode),
         epsilon: 10,
         emptyResult: '',
         prefix: '',
-        relativeTo: Date.now(),
         ...options
     };
 
     if (!timestamp) return options.emptyResult;
 
-    return doFormat(timestamp, options);
+    let ret = doFormat(timestamp, options);
+
+    if (options.prefix) ret = options.prefix + ' ' + ret;
+
+    return ret;
 }
 
 //------------------------
 // Implementation
 //------------------------
-function doFormat(timestamp: Date | number, opts: RelativeTimestampOptions) {
-    const {prefix, equalString, epsilon, allowFuture, short} = opts,
-        diff = toTimestamp(opts.relativeTo) - toTimestamp(timestamp),
-        elapsed = Math.abs(diff),
-        isEqual = elapsed <= (epsilon ?? 0) * SECONDS,
+function defaultPastSuffix(relFmt: String): string {
+    return relFmt ? `before ${relFmt}` : 'ago';
+}
+
+function defaultFutureSuffix(relFmt: String, localDateMode: string): string {
+    if (relFmt) return `after ${relFmt}`;
+    return localDateMode == 'always' ? 'from today' : 'from now';
+}
+
+function defaultEqualString(relFmt: String, localDateMode: string): string {
+    if (relFmt) return `${relFmt?.includes(':') ? 'at' : 'on'}  ${relFmt}`;
+    return localDateMode == 'always' ? 'today' : 'just now';
+}
+
+function doFormat(timestamp: Date | number, opts: RelativeTimestampOptions): string {
+    let {relativeTo, localDateMode, epsilon, equalString, allowFuture, short} = opts,
+        baseTimestamp = withDefault(relativeTo ?? Date.now()),
+        diff = toTimestamp(baseTimestamp) - toTimestamp(timestamp),
+        elapsed = Math.abs(diff);
+
+    // 0) Snap elapsed to calendar elapsed for localDateMode.
+    // (+ Early out for tomorrow/yesterday)
+    if (localDateMode && inRange(elapsed, 0, 26 * DAYS)) {
+        const dayDiff = LocalDate.from(baseTimestamp).diff(LocalDate.from(timestamp));
+
+        if (
+            !(localDateMode == 'useTimeForSameDay' && dayDiff == 0) &&
+            !(localDateMode == 'useTimeFor24Hr' && elapsed <= 24 * HOURS)
+        ) {
+            elapsed = Math.abs(dayDiff * DAYS);
+
+            if (isNil(relativeTo)) {
+                if (dayDiff == -1) return 'tomorrow';
+                if (dayDiff == 1) return 'yesterday';
+            }
+        }
+    }
+
+    const isEqual = elapsed <= (epsilon ?? 0) * SECONDS,
         isFuture = !isEqual && diff < 0;
 
-    let ret;
-    if (isEqual) {
-        ret = equalString;
-    } else if (isFuture && !allowFuture) {
+    // 1) Degenerate cases
+    if (isFuture && !allowFuture) {
         console.warn(`Unexpected future date provided for timestamp: ${elapsed}ms in the future.`);
-        ret = '[????]';
-    } else {
+        return '[????]';
+    }
+
+    // 2) Handle (epsilon) equals
+    if (isEqual) {
+        return equalString;
+    }
+
+    // 3) Basic timestamp, with suffix /prefix
+    let ret = '';
+    if (elapsed < 60 * SECONDS) {
         // By default, moment will show 'a few seconds' for durations of 0-45 seconds. At the higher
         // end of that range that output is a bit too inaccurate, so we replace as per below.
-        ret = elapsed < 60 * SECONDS ? '<1 minute' : moment.duration(elapsed).humanize();
+        ret = '<1 minute';
+    } else {
+        // Main delegate to humanize. Use 24h threshold vs. default 22h to avoid corner case
+        // transition w/localDateMode = limited: e.g. 21 hours -> zero days.
+        ret = moment.duration(elapsed).humanize({h: 24});
 
         // Moment outputs e.g. "a minute" instead of "1 minute". This creates some awkwardness
         // when the leading number comes and goes - "<1 minute" -> "a minute" -> "2 minutes".
         ret = ret.replace(/^(an|a) /, '1 ');
-
-        if (short) ret = ret.replace('minute', 'min').replace('second', 'sec');
-
-        ret += ' ' + (isFuture ? opts.futureSuffix : opts.pastSuffix);
     }
 
-    return prefix ? prefix + ' ' + ret : ret;
+    if (short) ret = ret.replace('minute', 'min').replace('second', 'sec');
+    const suffix = isFuture ? opts.futureSuffix : opts.pastSuffix;
+    if (suffix) ret = ret + ' ' + suffix;
+
+    return ret;
 }
 
 function toTimestamp(v: Date | number): number {

package/cmp/store/StoreFilterField.ts

@@ -75,8 +75,8 @@ export interface StoreFilterFieldProps extends DefaultHoistProps {
      */
     store?: Store;
 
-    /** Width of the input in pixels. */
-    width?: number;
+    /** Width of the input in pixels or string with unit. */
+    width?: string | number;
 }
 
 /**

package/cmp/tab/TabContainer.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
-import {hoistCmp, uses, XH, refreshContextView, BoxProps, HoistProps} from '@xh/hoist/core';
+import {BoxProps, hoistCmp, HoistProps, refreshContextView, uses, XH} from '@xh/hoist/core';
 import {tabContainerImpl as desktopTabContainerImpl} from '@xh/hoist/dynamics/desktop';
 import {tabContainerImpl as mobileTabContainerImpl} from '@xh/hoist/dynamics/mobile';
 import {TabContainerModel} from './TabContainerModel';

package/cmp/zoneGrid/Types.ts

@@ -0,0 +1,47 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2023 Extremely Heavy Industries Inc.
+ */
+
+import {Column, ColumnRenderer, ColumnSortSpec} from '@xh/hoist/cmp/grid';
+import {PersistOptions} from '@xh/hoist/core';
+
+export type Zone = 'tl' | 'tr' | 'bl' | 'br';
+
+export interface ZoneMapping {
+    /** Field to display. Must match a Field found in the Store */
+    field: string;
+    /** True to prefix the field value with its name */
+    showLabel?: boolean;
+}
+
+export interface ZoneLimit {
+    /** Min number of fields that should be mapped to the zone */
+    min?: number;
+    /** Max number of fields that should be mapped to the zone */
+    max?: number;
+    /** Array of allowed fields for the zone */
+    only?: string[];
+}
+
+export interface ZoneField {
+    field: string;
+    displayName: string;
+    label: string;
+    renderer: ColumnRenderer;
+    column: Column;
+    chooserGroup: string;
+    sortable: boolean;
+    sortingOrder: ColumnSortSpec[];
+}
+
+export interface ZoneGridModelPersistOptions extends PersistOptions {
+    /** True to include mapping information (default true) */
+    persistMapping?: boolean;
+    /** True to include grouping information (default true) */
+    persistGrouping?: boolean;
+    /** True to include sorting information (default true) */
+    persistSort?: boolean;
+}

package/cmp/zoneGrid/ZoneGrid.ts

@@ -0,0 +1,62 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2023 Extremely Heavy Industries Inc.
+ */
+import {hoistCmp, HoistProps, LayoutProps, TestSupportProps, uses, XH} from '@xh/hoist/core';
+import {fragment} from '@xh/hoist/cmp/layout';
+import {GridOptions} from '@xh/hoist/kit/ag-grid';
+import {grid} from '@xh/hoist/cmp/grid';
+import {splitLayoutProps} from '@xh/hoist/utils/react';
+import {zoneMapper as desktopZoneMapper} from '@xh/hoist/dynamics/desktop';
+import {zoneMapper as mobileZoneMapper} from '@xh/hoist/dynamics/mobile';
+import {ZoneGridModel} from './ZoneGridModel';
+
+export interface ZoneGridProps extends HoistProps<ZoneGridModel>, LayoutProps, TestSupportProps {
+    /**
+     * Options for ag-Grid's API.
+     *
+     * This constitutes an 'escape hatch' for applications that need to get to the underlying
+     * ag-Grid API. It should be used with care. Settings made here might be overwritten and/or
+     * interfere with the implementation of this component and its use of the ag-Grid API.
+     *
+     * Note that changes to these options after the component's initial render will be ignored.
+     */
+    agOptions?: GridOptions;
+}
+
+/**
+ * A ZoneGrid is a specialized version of the Grid component.
+ *
+ * It displays its data with multi-line full-width rows, each broken into four zones for
+ * top/bottom and left/right - (tl, tr, bl, br). Zone mappings determine which of the
+ * available fields should be extracted from the record and rendered into each zone.
+ */
+export const [ZoneGrid, zoneGrid] = hoistCmp.withFactory<ZoneGridProps>({
+    displayName: 'ZoneGrid',
+    model: uses(ZoneGridModel),
+    className: 'xh-zone-grid',
+
+    render({model, className, testId, ...props}, ref) {
+        const {gridModel, mapperModel} = model,
+            [layoutProps] = splitLayoutProps(props),
+            platformZoneMapper = XH.isMobileApp ? mobileZoneMapper : desktopZoneMapper;
+
+        return fragment(
+            grid({
+                ...layoutProps,
+                className,
+                testId,
+                ref,
+                model: gridModel,
+                agOptions: {
+                    suppressRowGroupHidesColumns: true,
+                    suppressMakeColumnVisibleAfterUnGroup: true,
+                    ...props.agOptions
+                }
+            }),
+            mapperModel ? platformZoneMapper() : null
+        );
+    }
+});