@xh/hoist 82.0.1 → 82.0.3

package/build/types/desktop/cmp/zoneGrid/impl/ZoneMapper.d.ts

@@ -0,0 +1,16 @@
+import '@xh/hoist/desktop/register';
+import './ZoneMapper.scss';
+import { ZoneMapperModel } from '@xh/hoist/cmp/zoneGrid/impl/ZoneMapperModel';
+/**
+ * Hoist UI for user selection and discovery of available ZoneGrid columns, enabled via the
+ * `ZoneGridModel.zoneMapperModel` config option.
+ *
+ * This component displays an example of each of the four zones, with the available columns for
+ * the currently selected zone displayed in a list below. Users can toggle column visibility
+ * and labels for each zone to construct a custom layout for the grid rows.
+ *
+ * It is not necessary to manually create instances of this component within an application.
+ *
+ * @internal
+ */
+export declare const ZoneMapper: import("react").FC<import("@xh/hoist/core").DefaultHoistProps<ZoneMapperModel>>, zoneMapper: import("@xh/hoist/core").ElementFactory<import("@xh/hoist/core").DefaultHoistProps<ZoneMapperModel>>;

package/build/types/desktop/cmp/zoneGrid/impl/ZoneMapperDialog.d.ts

@@ -0,0 +1,2 @@
+import { ZoneMapperModel } from '@xh/hoist/cmp/zoneGrid/impl/ZoneMapperModel';
+export declare const zoneMapperDialog: import("@xh/hoist/core").ElementFactory<import("@xh/hoist/core").DefaultHoistProps<ZoneMapperModel>>;

package/build/types/desktop/hooks/UseContextMenu.d.ts

@@ -0,0 +1,11 @@
+import { ContextMenuSpec } from '@xh/hoist/core';
+import { ReactElement } from 'react';
+/**
+ * Hook to add a right-click context menu to a component.
+ *
+ * @param child - element to be given context menu support. Must specify a component that takes
+ *      the React `onContextMenu` event as a prop (e.g. boxes, panel, div, etc.)
+ * @param spec - spec the menu to be shown. If null, or the number of items is empty, no menu will
+ *      be rendered and the event will be consumed.
+ */
+export declare function useContextMenu(child?: ReactElement, spec?: ContextMenuSpec): ReactElement;

package/build/types/desktop/hooks/UseHotkeys.d.ts

@@ -0,0 +1,14 @@
+import { ReactElement } from 'react';
+import { HotkeyConfig } from '@blueprintjs/core/src/hooks/hotkeys/hotkeyConfig';
+/**
+ * Hook to add Key handling support to a component.
+ *
+ * The implementation of this hook is based on BlueprintJS.
+ * See their docs {@link https://blueprintjs.com/docs/#core/components/hotkeys} for more info.
+ *
+ * @param child - element to be given hotkey support.  Must specify Component
+ *      that takes react key events as props (e.g. boxes, panel, div, etc).
+ * @param hotkeys - An array of hotkeys, or configs for hotkeys,
+ *      as prescribed by blueprint. A Hotkeys element may also be provided.
+ */
+export declare function useHotkeys(child?: ReactElement, hotkeys?: HotkeyConfig[]): ReactElement<any, string | import("react").JSXElementConstructor<any>>;

package/build/types/desktop/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export * from './UseHotkeys';
+export * from './UseContextMenu';

package/build/types/desktop/register.d.ts

@@ -0,0 +1 @@
+export {};

package/build/types/dynamics/desktop.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The exports below are platform specific classes we would like to use (carefully!) in our
+ * cross-platform code.
+ *
+ * These are dynamically bound in the method below. This dynamic binding ensures that they are
+ * included only on the intended platform to avoid platform specific code contaminating the builds
+ * of other platforms.
+ *
+ * See the platform specific AppContainer where these implementations are actually provided.
+ */
+export declare let ColChooserModel: any;
+export declare let ColumnHeaderFilterModel: any;
+export declare let ModalSupportModel: any;
+export declare let DashContainerViewModel: any;
+export declare let colChooser: any;
+export declare let zoneMapper: any;
+export declare let columnHeaderFilter: any;
+export declare let dockContainerImpl: any;
+export declare let gridFilterDialog: any;
+export declare let pinPadImpl: any;
+export declare let storeFilterFieldImpl: any;
+export declare let tabContainerImpl: any;
+export declare let useContextMenu: any;
+export declare let errorMessageImpl: any;
+export declare let maskImpl: any;
+export declare let DynamicTabSwitcherModel: any;
+export declare let cardHeaderImpl: any;
+/**
+ * Provide implementations of functions and classes exported in this file.
+ *
+ * Not for Application use.
+ */
+export declare function installDesktopImpls(impls: any): void;

package/build/types/dynamics/mobile.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The exports below are platform specific classes we would like to use (carefully!) in our
+ * cross-platform code.
+ *
+ * These are dynamically bound in the method below. This dynamic binding ensures that they are
+ * included only on the intended platform to avoid platform specific code contaminating the builds
+ * of other platforms.
+ *
+ * See the platform specific AppContainer where these implementations are actually provided.
+ */
+export declare let ColChooserModel: any;
+export declare let colChooser: any;
+export declare let zoneMapper: any;
+export declare let pinPadImpl: any;
+export declare let storeFilterFieldImpl: any;
+export declare let tabContainerImpl: any;
+export declare let errorMessageImpl: any;
+export declare let maskImpl: any;
+export declare let cardHeaderImpl: any;
+/**
+ * Provide implementations of functions and classes exported in this file.
+ *
+ * Not for Application use.
+ */
+export declare function installMobileImpls(impls: any): void;

package/build/types/exception/Exception.d.ts

@@ -0,0 +1,24 @@
+import type { HoistException, TimeoutException, TimeoutExceptionConfig } from './Types';
+/**
+ * Standardized Exception/Error objects.
+ *
+ * The main entry point for this class is the create() method.
+ * Applications can use this method to create various generic runtime exceptions.
+ * @see ExceptionHandler.handleException
+ */
+export declare class Exception {
+    /**
+     * Create and return a HoistException
+     *
+     * See {@link XH.exception} - an alias for this factory off of `XH`.
+     *
+     * @param src - If a native JS Error, it will be enhanced into a HoistException and returned.
+     *      If a plain object, all properties will be set on a new HoistException.
+     *      Other inputs will be treated as the `message` of a new HoistException.
+     */
+    static create(src: unknown): HoistException;
+    /** Create an Error for when an operation (e.g. a Promise) times out. */
+    static timeout(config: TimeoutExceptionConfig): TimeoutException;
+    private static createInternal;
+}
+export declare function isHoistException(src: unknown): src is HoistException;

package/build/types/exception/Types.d.ts

@@ -0,0 +1,35 @@
+import type { PlainObject } from '@xh/hoist/core';
+/**
+ * A Hoist optimized Javascript Error object.
+ */
+export interface HoistException extends Error {
+    isHoistException: true;
+    /** Correlation ID associated with this exception, if any. */
+    correlationId?: string;
+    /**
+     * Is the exception an expected, normal behavior of the app?
+     *
+     * Set to true for exceptions that should not be treated or logged as technical 'errors'.
+     * (e.g. validation errors, permission errors, time-of-day errors).  Default false.
+     */
+    isRoutine: boolean;
+    [x: string]: any;
+}
+/**
+ * Exception thrown to indicate a timeout.
+ *
+ * Typically generated by the `Promise.timeout()` extension or calls to FetchService.
+ */
+export interface TimeoutException extends HoistException {
+    isTimeout: true;
+    /** Time in Milliseconds that was waited before exception was thrown.  */
+    interval: number;
+}
+/**
+ * Configuration for generating a timeout exception.
+ *
+ * @internal
+ */
+export interface TimeoutExceptionConfig extends PlainObject {
+    interval: number;
+}

package/build/types/exception/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Types';
+export * from './Exception';

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

@@ -0,0 +1,73 @@
+import { ReactNode } from 'react';
+import { DateLike, PlainObject } from '../core/types/Types';
+import { FormatOptions } from './FormatMisc';
+export declare const DATE_FMT = "YYYY-MM-DD", DATETIME_FMT = "YYYY-MM-DD h:mma", DATETIMESEC_FMT = "YYYY-MM-DD h:mm:ssa", TIME_FMT = "h:mma", MONTH_DAY_FMT = "MMM D";
+/**
+ * An object specifying how a date should be formatted.
+ */
+export interface DateFormatOptions extends FormatOptions<DateLike> {
+    /** Display value for null values. */
+    nullDisplay?: ReactNode;
+    /** A MomentJs format string. */
+    fmt?: string;
+}
+/**
+ * Render a date like value with a default format of {@link DATE_FMT}.
+ */
+export declare function fmtDate(v: DateLike, opts?: DateFormatOptions | string): ReactNode;
+/**
+ * Render dates with a default format of {@link DATETIME_FMT}.
+ */
+export declare function fmtDateTime(v: any, opts?: DateFormatOptions | string): ReactNode;
+/**
+ * Render dates with a default format of {@link DATETIMESEC_FMT}.
+ */
+export declare function fmtDateTimeSec(v: DateLike, opts?: DateFormatOptions | string): ReactNode;
+/**
+ * Render dates with a default format of {@link TIME_FMT}.
+ */
+export declare function fmtTime(v: DateLike, opts?: DateFormatOptions | string): ReactNode;
+export interface CompactDateFormatOptions extends FormatOptions<DateLike> {
+    /**
+     * Format for date matching current day, defaults to 'hh:mma' for dates, 'MMM D' for LocalDates.
+     */
+    sameDayFmt?: string;
+    /**
+     *  Format for dates within the number of months specified by the distantThreshold, defaults
+     *  to 'MMM D'.
+     */
+    nearFmt?: string;
+    /**
+     * Format for dates beyond number of months specified by the distantThreshold, defaults to
+     * 'YYYY-MM-DD'.
+     */
+    distantFmt?: string;
+    /** Number of months away from the current month to be considered 'recent' or 'near'. */
+    distantThreshold?: number;
+}
+/**
+ * Render dates formatted based on distance in time from current day.
+ */
+export declare function fmtCompactDate(v: DateLike, opts?: CompactDateFormatOptions): ReactNode;
+export interface TimestampReplacerConfig {
+    /**
+     * Suffixes used to identify keys that may hold timestamps.
+     * Defaults to ['time', 'date', 'timestamp']
+     */
+    suffixes?: string[];
+    /**
+     * Format for replaced timestamp.
+     * Defaults to 'MMM DD HH:mm:ss.SSS'
+     */
+    format?: string;
+}
+/**
+ * Replace timestamps in an Object with formatted strings.
+ */
+export declare function withFormattedTimestamps(obj: PlainObject, config?: TimestampReplacerConfig): PlainObject;
+/**
+ * Create a replacer, suitable for JSON.stringify, that will replace timestamps with
+ * formatted strings.
+ */
+export declare function timestampReplacer(config?: TimestampReplacerConfig): (k: string, v: any) => any;
+export declare const dateRenderer: (obj?: string | DateFormatOptions) => (v: DateLike) => ReactNode, dateTimeRenderer: (obj?: string | DateFormatOptions) => (v: any) => ReactNode, dateTimeSecRenderer: (obj?: string | DateFormatOptions) => (v: DateLike) => ReactNode, timeRenderer: (obj?: string | DateFormatOptions) => (v: DateLike) => ReactNode, compactDateRenderer: (obj?: CompactDateFormatOptions) => (v: DateLike) => ReactNode;

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

@@ -0,0 +1,43 @@
+import { CSSProperties, ReactNode } from 'react';
+import { PlainObject } from '@xh/hoist/core';
+export interface FormatOptions<T = any> {
+    /** Display value for null values. */
+    nullDisplay?: ReactNode;
+    /** Function to generate a tooltip string. */
+    tooltip?: (v: T) => string;
+    /** Return an HTML string rather than a React element (default false).*/
+    asHtml?: boolean;
+    /** The unaltered original value to be formatted. Not typically used by applications.*/
+    originalValue?: T;
+}
+export interface SpanFormatOptions extends FormatOptions {
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    /** Set to true to add a space before the v to be wrapped.*/
+    leadSpc?: boolean;
+    /** Set to true to add a space after the span to be returned. */
+    trailSpc?: boolean;
+}
+/**
+ * Wrap values in a custom span
+ *
+ * @param v - value to be placed in span, will be coerced into a string
+ * @param opts - an options object
+ */
+export declare function fmtSpan(v: any, opts?: SpanFormatOptions): ReactNode;
+export interface JSONFormatOptions {
+    /** Method or array pattern for replacing/skipping nodes to pass to `stringify` */
+    replacer?: any;
+    /** Indentation amount to pass to `stringify`*/
+    space?: number | string;
+}
+/**
+ * Pretty-print a JSON string or (JSON Object), adding line breaks and indentation.
+ */
+export declare function fmtJson(v: string | PlainObject, opts?: JSONFormatOptions): string;
+/**
+ * Basic util for splitting a string (via ' ') and capitalizing each word - e.g. for names.
+ * Not intended to handle more advanced usages such as HTML or other word boundary characters.
+ */
+export declare function capitalizeWords(str: string): string;

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

@@ -0,0 +1,137 @@
+import Numbro from 'numbro';
+import { CSSProperties, ReactNode } from 'react';
+import { IntRange } from 'type-fest';
+import { FormatOptions } from './FormatMisc';
+export type NumericPrecision = IntRange<0, 13>;
+export type Precision = NumericPrecision | 'auto';
+export type ZeroPad = NumericPrecision | boolean;
+export interface NumberFormatOptions extends Omit<FormatOptions<number>, 'tooltip'> {
+    /**
+     * 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;
+    /**
+     * 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;
+    /** 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;
+    /**
+     * 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).
+     */
+    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;
+    useBillions?: boolean;
+}
+/** Config for pos/neg/neutral color classes. */
+export interface ColorSpec {
+    /** CSS color class or CSS Style Properties to apply to positive values */
+    pos?: string | CSSProperties;
+    /** CSS color class or CSS Style Properties to apply to negative values */
+    neg?: string | CSSProperties;
+    /** CSS color class or CSS Style Properties to apply to  zero values. */
+    neutral?: string | CSSProperties;
+}
+/**
+ * Standard number formatting for Hoist
+ *
+ * This method delegates to numbro, @see http://numbrojs.com for more details.
+ *
+ * Hierarchy of params is by specificity: formatPattern, precision.
+ * If no options are given, a heuristic based auto-rounding will occur.
+ *
+ * @returns a ReactNode.  For an HTML string use `asHtml = true`.
+ */
+export declare function fmtNumber(v: number, opts?: NumberFormatOptions): ReactNode;
+/**
+ * Render number in thousands.
+ */
+export declare function fmtThousands(v: number, opts?: NumberFormatOptions): ReactNode;
+/**
+ * Render number in millions.
+ */
+export declare function fmtMillions(v: number, opts?: NumberFormatOptions): ReactNode;
+/**
+ * Render number in billions.
+ */
+export declare function fmtBillions(v: number, opts?: NumberFormatOptions): ReactNode;
+/**
+ * Render a quantity value, handling highly variable amounts by using units of millions (m) and
+ * billions (b) as needed.'
+ */
+export declare function fmtQuantity(v: number, opts?: QuantityFormatOptions): ReactNode;
+/**
+ * Render market price.
+ */
+export declare function fmtPrice(v: number, opts?: NumberFormatOptions): ReactNode;
+/**
+ * Render a number as a percent. Value will be multiplied by 100 to calculated the percentage.
+ * This behavior purposefully matches Microsoft Excel's percentage formatting.
+ */
+export declare function fmtPercent(v: number, opts?: NumberFormatOptions): ReactNode;
+/**
+ * Render a minimally formatted, full precision number, suitable for use in tooltips.
+ * Only ledger opt is supported.
+ *
+ * @param v - value to format.
+ * @param opts - set key 'ledger' to true to use ledger format, default false
+ */
+export declare function fmtNumberTooltip(v: number, opts?: {
+    ledger?: boolean;
+}): string;
+export declare const numberRenderer: (obj?: NumberFormatOptions) => (v: number) => ReactNode, thousandsRenderer: (obj?: NumberFormatOptions) => (v: number) => ReactNode, millionsRenderer: (obj?: NumberFormatOptions) => (v: number) => ReactNode, billionsRenderer: (obj?: NumberFormatOptions) => (v: number) => ReactNode, quantityRenderer: (obj?: QuantityFormatOptions) => (v: number) => ReactNode, priceRenderer: (obj?: NumberFormatOptions) => (v: number) => ReactNode, percentRenderer: (obj?: NumberFormatOptions) => (v: number) => ReactNode;
+/**
+ * @param value - A value that represents a shorthand numerical value
+ * @returns The number represented by the shorthand string, or NaN
+ */
+export declare function parseNumber(value: any): number;

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

@@ -0,0 +1,11 @@
+import { PlainObject } from '@xh/hoist/core';
+/**
+ * Generate a renderer for a given formatter function.
+ *
+ * The returned renderer takes an optional config for its assigned formatter and itself returns
+ * a function that takes only a value, for convenient use with e.g. grid cell rendering.
+ *
+ * @param formatter - an existing formatter method.
+ * @returns - a configurable renderer.
+ */
+export declare function createRenderer<V = any, C = PlainObject, R = any>(formatter: (v: V, obj?: C) => R): (obj?: C) => (v: V) => R;

package/build/types/format/impl/Utils.d.ts

@@ -0,0 +1,7 @@
+import { PlainObject } from '@xh/hoist/core';
+/**
+ * Install a value on an options object as `originalValue` for later reference, if an
+ * originalValue key has not already been set.
+ * @internal
+ */
+export declare function saveOriginal(v: any, opts: PlainObject): void;

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

@@ -0,0 +1,4 @@
+export * from './FormatNumber';
+export * from './FormatDate';
+export * from './FormatUtils';
+export * from './FormatMisc';