@xh/hoist 66.1.0 → 66.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 66.1.1 - 2024-08-01
+
+### 🐞 Bug Fixes
+
+* `HoistException` now correctly passes an exception message to its underlying `Error` instance.
+* Fixed `GridModel.cellBorders` prop to apply previously missing top and bottom borders to cells in the grid.
+* Fix to new `mergeDeep` method.
+
 ## 66.1.0 - 2024-07-31
 
 ### 🎁 New Features
@@ -9,11 +17,16 @@
 * New `mergeDeep` method provided in `@xh/hoist/utils/js` as an alternative to `lodash.merge`,
   without lodash's surprising deep-merging of array-based properties.
 * Enhanced Roles Admin UI to support bulk category reassignment.
+* fmtNumber `zeroPad` now supports numbers to specify the decimal places out to which a
+  formatted number should be zero-padded.
 
 ### 🐞 Bug Fixes
 
 * Fixed `Record.descendants` and `Record.allDescendants` getters that were incorrectly returning the
   parent record itself. Now only the descendants are returned, as expected.
+  * ⚠️ Potentially Breaking Change: apps relying on the previous behavior may need to adjust their code
+    to account for the parent record no longer being included in the results.  Tree mode checkbox
+    grids are one example of a component that may be affected by this change.
 * Fixed `Grid` regression where pinned columns were automatically un-pinned when the viewport became
   too small to accommodate them.
 * Fixed bug where `Grid` context-menus would lose focus when rendered inside `Overlay` components.

package/build/types/desktop/cmp/input/NumberInput.d.ts

@@ -1,6 +1,7 @@
 import { HoistInputProps } from '@xh/hoist/cmp/input';
 import { HoistProps, HSide, LayoutProps, StyleProps } from '@xh/hoist/core';
 import '@xh/hoist/desktop/register';
+import { ZeroPad } from '@xh/hoist/format';
 import { KeyboardEventHandler, ReactElement, ReactNode, Ref } from 'react';
 export interface NumberInputProps extends HoistProps, LayoutProps, StyleProps, HoistInputProps {
     value?: number;
@@ -56,8 +57,8 @@ export interface NumberInputProps extends HoistProps, LayoutProps, StyleProps, H
      * Can be used to append e.g. "%" or a unit without need for an external right label.
      */
     valueLabel?: string;
-    /** True to pad with trailing zeros out to precision, default false. */
-    zeroPad?: boolean;
+    /** @see NumberFormatOptions.zeroPad */
+    zeroPad?: ZeroPad;
 }
 /**
  * Number input, with optional support for formatting of display value, shorthand units, and more.

package/build/types/format/FormatNumber.d.ts

@@ -1,54 +1,72 @@
 import Numbro from 'numbro';
 import { CSSProperties, ReactNode } from 'react';
+import { IntRange } from 'type-fest';
 import { FormatOptions } from './FormatMisc';
+export type Precision = 'auto' | IntRange<0, 13>;
+export type ZeroPad = boolean | IntRange<1, 13>;
 export interface NumberFormatOptions extends Omit<FormatOptions<number>, 'tooltip'> {
-    /** A valid numbro format object or string. */
-    formatConfig?: string | Numbro.Format;
-    /** Desired number of decimal places. */
-    precision?: number | 'auto';
-    /** True to pad with trailing zeros out to given precision. */
-    zeroPad?: boolean;
-    /** Optional display value for the input value 0. */
-    zeroDisplay?: ReactNode;
-    /** True to use ledger format. */
-    ledger?: boolean;
     /**
-     * True to add placeholder after positive ledgers to align vertically with negative ledgers
-     * in columns.
+     * Color output based on the sign of the value. True to use red/green/grey defaults, or provide
+     * an object with alternate CSS classes or properties.
      */
-    forceLedgerAlign?: boolean;
-    /** True to prepend positive numbers with a '+'. */
-    withPlusSign?: boolean;
+    colorSpec?: boolean | ColorSpec;
     /**
-     * If set to false, small numbers that would show only digits of zero due to precision will be
-     * formatted as exactly zero. In particular, if a zeroDisplay is specified it will be used and
-     * sign-based glyphs, '+/-' characters, and colors will not be shown.  Default true.
+     * True to add placeholder after positive ledgers to ensure columns of mixed positive and
+     * negative numbers vertically align their digits, avoiding shift due to ")" on negative values.
      */
-    strictZero?: boolean;
-    /** True to prepend an up / down arrow. */
-    withSignGlyph?: boolean;
-    /** True to include comma delimiters. */
-    withCommas?: boolean;
-    /** Set to true to omit comma if value has exactly 4 digits (i.e. 1500 instead of 1,500). */
-    omitFourDigitComma?: boolean;
-    /** Prefix to prepend to value (between the number and its sign). */
-    prefix?: string;
-    /** Label to append to value, or true to append a default label for the formattter
+    forceLedgerAlign?: boolean;
+    /** A valid numbro format object or string. */
+    formatConfig?: Numbro.Format | string;
+    /**
+     * Label to append to value, or true to append a default label for the formatter -
      * e.g. 'm' for fmtMillions.
      */
     label?: string | boolean;
     /** CSS class of label span. */
     labelCls?: string;
+    /** True to use ledger format. */
+    ledger?: boolean;
     /**
-     * Color output based on the sign of the value. True to use red/green/grey defaults, or provide
-     * an object with alternate CSS classes or properties.
+     * Set to true to omit thousands-separator comma if value is to be formatted as a whole number
+     * with exactly 4 digits (e.g. 1,500).
      */
-    colorSpec?: boolean | ColorSpec;
+    omitFourDigitComma?: boolean;
+    /**
+     * Desired number of decimal places, or 'auto' (default) to adjust the displayed precision
+     * automatically based on the scale of the value.
+     */
+    precision?: Precision;
+    /** Prefix to prepend to value (between the number and its sign). */
+    prefix?: string;
+    /**
+     * If set to false, small numbers that would show only digits of zero due to precision will be
+     * formatted as exactly zero. In particular, if a zeroDisplay is specified it will be used and
+     * sign-based glyphs, '+/-' characters, and colors will not be shown. Default true.
+     */
+    strictZero?: boolean;
     /**
      * True to enable default tooltip with minimally formatted original value, or a function to
      * generate a custom tooltip string.
      */
     tooltip?: boolean | ((v: number) => string);
+    /** True to include comma delimiters. */
+    withCommas?: boolean;
+    /** True to prepend positive numbers with a '+'. */
+    withPlusSign?: boolean;
+    /** True to prepend an up / down arrow. */
+    withSignGlyph?: boolean;
+    /** Optional display value for the input value 0. */
+    zeroDisplay?: ReactNode;
+    /**
+     * True to pad with trailing zeros out to precision, false to skip adding any trailing zeroes.
+     * Can also be a number (lte precision) to specify a minimum number of trailing zeroes to add,
+     * without extending zero padding all the way out to full precision.
+     *
+     * e.g. `{precision:4, zeroPad:2}` will format `1.2` → "1.20" and `1.234` → "1.234"
+     *
+     * Default is true if a fixed precision is set, false if precision is 'auto'.
+     */
+    zeroPad?: ZeroPad;
 }
 export interface QuantityFormatOptions extends NumberFormatOptions {
     useMillions?: boolean;

package/build/types/mobile/cmp/input/NumberInput.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="react" />
 import { HoistInputProps } from '@xh/hoist/cmp/input';
-import { HoistProps, StyleProps, LayoutProps, HSide } from '@xh/hoist/core';
+import { HoistProps, HSide, LayoutProps, StyleProps } from '@xh/hoist/core';
+import { ZeroPad } from '@xh/hoist/format';
 import '@xh/hoist/mobile/register';
 import './NumberInput.scss';
 export interface NumberInputProps extends HoistProps, HoistInputProps, StyleProps, LayoutProps {
@@ -43,8 +44,8 @@ export interface NumberInputProps extends HoistProps, HoistInputProps, StyleProp
      * Can be used to append e.g. "%" or a unit without need for an external right label.
      */
     valueLabel?: string;
-    /** True to pad with trailing zeros out to precision, default false. */
-    zeroPad?: boolean;
+    /** @see NumberFormatOptions.zeroPad */
+    zeroPad?: ZeroPad;
 }
 /**
  * Number input, with optional support for formatting of display value, shorthand units, and more.

package/cmp/ag-grid/AgGrid.scss

@@ -140,11 +140,14 @@
         border-color: var(--xh-grid-group-border-color);
       }
     }
+    .ag-cell {
+      border-bottom: none;
+      border-top: none;
+    }
   }
 
   &--no-row-borders {
-    .ag-row,
-    .ag-cell {
+    .ag-row {
       border-bottom: none;
       border-top: none;
     }
@@ -249,6 +252,7 @@
   &--cell-borders {
     .ag-cell {
       border-right-color: var(--xh-grid-border-color);
+      border-bottom-color: var(--xh-grid-border-color);
     }
 
     .ag-row {

package/core/exception/Exception.ts

@@ -193,14 +193,15 @@ export class Exception {
         }) as FetchException;
     }
 
-    private static createInternal(attributes: PlainObject, baseError: Error = new Error()) {
+    private static createInternal(attributes: PlainObject, baseError?: Error) {
+        const {message, ...rest} = attributes;
         return Object.assign(
-            baseError,
+            baseError ?? new Error(message),
             {
                 isRoutine: false,
                 isHoistException: true
             },
-            attributes
+            rest
         ) as HoistException;
     }
 }

package/desktop/cmp/input/NumberInput.ts

@@ -8,7 +8,7 @@ import composeRefs from '@seznam/compose-react-refs';
 import {HoistInputModel, HoistInputProps, useHoistInputModel} from '@xh/hoist/cmp/input';
 import {hoistCmp, HoistProps, HSide, LayoutProps, StyleProps} from '@xh/hoist/core';
 import '@xh/hoist/desktop/register';
-import {fmtNumber, parseNumber} from '@xh/hoist/format';
+import {fmtNumber, parseNumber, Precision, ZeroPad} from '@xh/hoist/format';
 import {numericInput} from '@xh/hoist/kit/blueprint';
 import {wait} from '@xh/hoist/promise';
 import {TEST_ID, throwIf, withDefault} from '@xh/hoist/utils/js';
@@ -90,8 +90,8 @@ export interface NumberInputProps extends HoistProps, LayoutProps, StyleProps, H
      */
     valueLabel?: string;
 
-    /** True to pad with trailing zeros out to precision, default false. */
-    zeroPad?: boolean;
+    /** @see NumberFormatOptions.zeroPad */
+    zeroPad?: ZeroPad;
 }
 
 /**
@@ -129,14 +129,14 @@ class NumberInputModel extends HoistInputModel {
         throwIf(Math.log10(this.scaleFactor) % 1 !== 0, 'scaleFactor must be a factor of 10');
     }
 
-    get precision(): number {
-        return withDefault(this.componentProps.precision, 4);
-    }
-
     override get commitOnChange(): boolean {
         return withDefault(this.componentProps.commitOnChange, false);
     }
 
+    get precision(): number {
+        return withDefault(this.componentProps.precision, 4);
+    }
+
     get scaleFactor(): number {
         return withDefault(this.componentProps.scaleFactor, 1);
     }
@@ -206,7 +206,7 @@ class NumberInputModel extends HoistInputModel {
         const {valueLabel, displayWithCommas} = componentProps,
             zeroPad = withDefault(componentProps.zeroPad, false),
             formattedVal = fmtNumber(value, {
-                precision,
+                precision: precision as Precision,
                 zeroPad,
                 label: valueLabel,
                 labelCls: null,

package/format/FormatNumber.ts

@@ -5,10 +5,20 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 import {span} from '@xh/hoist/cmp/layout';
-import {defaults, isBoolean, isFinite, isFunction, isNil, isString} from 'lodash';
+import {
+    defaults,
+    isBoolean,
+    isFinite,
+    isFunction,
+    isInteger,
+    isNil,
+    isNumber,
+    isString
+} from 'lodash';
 import Numbro from 'numbro';
 import numbro from 'numbro';
 import {CSSProperties, ReactNode} from 'react';
+import {IntRange} from 'type-fest';
 import {fmtSpan, FormatOptions} from './FormatMisc';
 import {createRenderer} from './FormatUtils';
 import {saveOriginal} from './impl/Utils';
@@ -28,69 +38,87 @@ const UP_TICK = '▴',
         neutral: 'xh-neutral-val'
     };
 
+export type Precision = 'auto' | IntRange<0, 13>;
+export type ZeroPad = boolean | IntRange<1, 13>;
+
 export interface NumberFormatOptions extends Omit<FormatOptions<number>, 'tooltip'> {
-    /** A valid numbro format object or string. */
-    formatConfig?: string | Numbro.Format;
+    /**
+     * Color output based on the sign of the value. True to use red/green/grey defaults, or provide
+     * an object with alternate CSS classes or properties.
+     */
+    colorSpec?: boolean | ColorSpec;
 
-    /** Desired number of decimal places. */
-    precision?: number | 'auto';
+    /**
+     * True to add placeholder after positive ledgers to ensure columns of mixed positive and
+     * negative numbers vertically align their digits, avoiding shift due to ")" on negative values.
+     */
+    forceLedgerAlign?: boolean;
 
-    /** True to pad with trailing zeros out to given precision. */
-    zeroPad?: boolean;
+    /** A valid numbro format object or string. */
+    formatConfig?: Numbro.Format | string;
 
-    /** Optional display value for the input value 0. */
-    zeroDisplay?: ReactNode;
+    /**
+     * Label to append to value, or true to append a default label for the formatter -
+     * e.g. 'm' for fmtMillions.
+     */
+    label?: string | boolean;
+
+    /** CSS class of label span. */
+    labelCls?: string;
 
     /** True to use ledger format. */
     ledger?: boolean;
 
     /**
-     * True to add placeholder after positive ledgers to align vertically with negative ledgers
-     * in columns.
+     * Set to true to omit thousands-separator comma if value is to be formatted as a whole number
+     * with exactly 4 digits (e.g. 1,500).
      */
-    forceLedgerAlign?: boolean;
+    omitFourDigitComma?: boolean;
 
-    /** True to prepend positive numbers with a '+'. */
-    withPlusSign?: boolean;
+    /**
+     * Desired number of decimal places, or 'auto' (default) to adjust the displayed precision
+     * automatically based on the scale of the value.
+     */
+    precision?: Precision;
+
+    /** Prefix to prepend to value (between the number and its sign). */
+    prefix?: string;
 
     /**
      * If set to false, small numbers that would show only digits of zero due to precision will be
      * formatted as exactly zero. In particular, if a zeroDisplay is specified it will be used and
-     * sign-based glyphs, '+/-' characters, and colors will not be shown.  Default true.
+     * sign-based glyphs, '+/-' characters, and colors will not be shown. Default true.
      */
     strictZero?: boolean;
 
-    /** True to prepend an up / down arrow. */
-    withSignGlyph?: boolean;
+    /**
+     * True to enable default tooltip with minimally formatted original value, or a function to
+     * generate a custom tooltip string.
+     */
+    tooltip?: boolean | ((v: number) => string);
 
     /** True to include comma delimiters. */
     withCommas?: boolean;
 
-    /** Set to true to omit comma if value has exactly 4 digits (i.e. 1500 instead of 1,500). */
-    omitFourDigitComma?: boolean;
-
-    /** Prefix to prepend to value (between the number and its sign). */
-    prefix?: string;
-
-    /** Label to append to value, or true to append a default label for the formattter
-     * e.g. 'm' for fmtMillions.
-     */
-    label?: string | boolean;
+    /** True to prepend positive numbers with a '+'. */
+    withPlusSign?: boolean;
 
-    /** CSS class of label span. */
-    labelCls?: string;
+    /** True to prepend an up / down arrow. */
+    withSignGlyph?: boolean;
 
-    /**
-     * Color output based on the sign of the value. True to use red/green/grey defaults, or provide
-     * an object with alternate CSS classes or properties.
-     */
-    colorSpec?: boolean | ColorSpec;
+    /** Optional display value for the input value 0. */
+    zeroDisplay?: ReactNode;
 
     /**
-     * True to enable default tooltip with minimally formatted original value, or a function to
-     * generate a custom tooltip string.
+     * True to pad with trailing zeros out to precision, false to skip adding any trailing zeroes.
+     * Can also be a number (lte precision) to specify a minimum number of trailing zeroes to add,
+     * without extending zero padding all the way out to full precision.
+     *
+     * e.g. `{precision:4, zeroPad:2}` will format `1.2` → "1.20" and `1.234` → "1.234"
+     *
+     * Default is true if a fixed precision is set, false if precision is 'auto'.
      */
-    tooltip?: boolean | ((v: number) => string);
+    zeroPad?: ZeroPad;
 }
 
 export interface QuantityFormatOptions extends NumberFormatOptions {
@@ -126,8 +154,8 @@ export function fmtNumber(v: number, opts?: NumberFormatOptions): ReactNode {
         nullDisplay = '',
         zeroDisplay = null,
         formatConfig = null,
-        precision = 'auto',
-        zeroPad = precision != 'auto',
+        precision,
+        zeroPad,
         ledger = false,
         forceLedgerAlign = true,
         withPlusSign = false,
@@ -142,10 +170,13 @@ export function fmtNumber(v: number, opts?: NumberFormatOptions): ReactNode {
         tooltip = null,
         asHtml = false,
         originalValue = v
-    } = opts ?? {};
-
+    } = opts ?? ({} as NumberFormatOptions);
     if (isInvalidInput(v)) return nullDisplay;
 
+    // Ensure any non-int precision is treated as 'auto', use to default zeroPad.
+    if (!isInteger(precision)) precision = 'auto';
+    if (isNil(zeroPad)) zeroPad = precision != 'auto';
+
     formatConfig =
         formatConfig || buildFormatConfig(v, precision, zeroPad, withCommas, omitFourDigitComma);
     const str = numbro(v).format(formatConfig).replace('-', '');
@@ -429,41 +460,83 @@ function calcStyleFromColorSpec(v: number, colorSpec: ColorSpec | boolean): CSSP
     return !isString(possibleStyles) ? possibleStyles : {};
 }
 
-function buildFormatConfig(v, precision, zeroPad, withCommas, omitFourDigitComma): Numbro.Format {
-    const num = Math.abs(v);
+function buildFormatConfig(
+    v: number,
+    precisionSpec: Precision,
+    zeroPad: ZeroPad,
+    withCommas: boolean,
+    omitFourDigitComma: boolean
+): Numbro.Format {
+    const absVal = Math.abs(v),
+        config: Numbro.Format = {};
+
+    let precision: number;
+    if (precisionSpec === 'auto') {
+        // Auto-precision - base on scale of number
+        if (absVal === 0) {
+            precision = 2;
+        } else if (absVal < 0.01) {
+            precision = 6;
+        } else if (absVal < 100) {
+            precision = 4;
+        } else if (absVal < 10000) {
+            precision = 2;
+        } else {
+            precision = 0;
+        }
+    } else {
+        // Fixed precision - use requested, capped at max.
+        precision = precisionSpec < MAX_NUMERIC_PRECISION ? precisionSpec : MAX_NUMERIC_PRECISION;
+    }
 
-    const config: Numbro.Format = {};
-    let mantissa = undefined;
+    // If zeroPad gte precision, treat as `true` to pad out to (but not beyond) full precision.
+    // We don't support applying some precision (rounding) then padding out zeroes after that.
+    if (isNumber(zeroPad) && zeroPad >= precision) {
+        zeroPad = true;
+    }
 
-    if (precision % 1 === 0) {
-        precision = precision < MAX_NUMERIC_PRECISION ? precision : MAX_NUMERIC_PRECISION;
-        mantissa = precision === 0 ? 0 : precision;
+    // Calculate numbro mantissa and trimMantissa options based on precision and zeroPad settings.
+    if (isNumber(zeroPad)) {
+        // Specific zeroPad set - need to read actual precision of number to determine exact
+        // mantissa, as we cannot use trimMantissa (since we do want to allow some trailing zeroes).
+        const actualPrecision = countDecimalPlaces(absVal);
+
+        // How much precision do we actually want/need? Lower of actual vs. precision set above.
+        // Ensures we respect a deliberately low precision spec, but otherwise include only as
+        // much precision as we need to show the value.
+        const requiredPrecision = Math.min(actualPrecision, precision);
+
+        // Then set mantissa to higher of required precision vs. requested zeroPad.
+        // Ensures we display all of the requested/available precision + extra zeros if needed.
+        config.mantissa = Math.max(requiredPrecision, zeroPad);
+        config.trimMantissa = false;
     } else {
-        if (num === 0) {
-            mantissa = 2;
-        } else if (num < 0.01) {
-            mantissa = 6;
-        } else if (num < 100) {
-            mantissa = 4;
-        } else if (num < 10000) {
-            mantissa = 2;
-        } else {
-            mantissa = 0;
-        }
+        // Without a specific (numeric) zeroPad set, we can set mantissa to precision then
+        // optionally enable trimMantissa option to remove trailing zeroes if requested.
+        // No need to measure actual precision of number.
+        config.mantissa = precision;
+        config.trimMantissa = !zeroPad && precision != 0;
     }
 
+    // Apply comma-separation unless contradicted by omitFourDigitComma, which should apply only to
+    // whole number values between 1000 and 9999, where we are not displaying any decimal places.
     config.thousandSeparated =
         withCommas &&
         !(
             omitFourDigitComma &&
-            num < 10000 &&
-            (mantissa == 0 || (!zeroPad && Number.isInteger(num)))
+            absVal < 10000 &&
+            (config.mantissa == 0 || (!zeroPad && Number.isInteger(absVal)))
         );
-    config.mantissa = mantissa;
-    config.trimMantissa = !zeroPad && mantissa != 0;
+
     return config;
 }
 
+function countDecimalPlaces(number: number): number {
+    const numStr = number.toString(),
+        dpIdx = numStr.indexOf('.');
+    return dpIdx === -1 ? 0 : numStr.length - dpIdx - 1;
+}
+
 function isInvalidInput(v) {
     return v == null || v === '';
 }

package/mobile/cmp/input/NumberInput.ts

@@ -5,8 +5,8 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 import {HoistInputModel, HoistInputProps, useHoistInputModel} from '@xh/hoist/cmp/input';
-import {hoistCmp, HoistProps, StyleProps, LayoutProps, HSide} from '@xh/hoist/core';
-import {fmtNumber} from '@xh/hoist/format';
+import {hoistCmp, HoistProps, HSide, LayoutProps, StyleProps} from '@xh/hoist/core';
+import {fmtNumber, Precision, ZeroPad} from '@xh/hoist/format';
 import {input} from '@xh/hoist/kit/onsen';
 import '@xh/hoist/mobile/register';
 import {wait} from '@xh/hoist/promise';
@@ -68,8 +68,8 @@ export interface NumberInputProps extends HoistProps, HoistInputProps, StyleProp
      */
     valueLabel?: string;
 
-    /** True to pad with trailing zeros out to precision, default false. */
-    zeroPad?: boolean;
+    /** @see NumberFormatOptions.zeroPad */
+    zeroPad?: ZeroPad;
 }
 
 /**
@@ -97,15 +97,15 @@ class NumberInputModel extends HoistInputModel {
         throwIf(Math.log10(this.scaleFactor) % 1 !== 0, 'scaleFactor must be a factor of 10');
     }
 
-    get precision() {
-        return withDefault(this.componentProps.precision, 4);
-    }
-
     override get commitOnChange() {
         return withDefault(this.componentProps.commitOnChange, false);
     }
 
-    get scaleFactor() {
+    get precision(): number {
+        return withDefault(this.componentProps.precision, 4);
+    }
+
+    get scaleFactor(): number {
         return withDefault(this.componentProps.scaleFactor, 1);
     }
 
@@ -195,7 +195,7 @@ class NumberInputModel extends HoistInputModel {
         const {valueLabel, displayWithCommas} = componentProps,
             zeroPad = withDefault(componentProps.zeroPad, false),
             formattedVal = fmtNumber(value, {
-                precision,
+                precision: precision as Precision,
                 zeroPad,
                 label: valueLabel,
                 labelCls: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "66.1.0",
+  "version": "66.1.1",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",