@xh/hoist 83.1.0 → 84.0.1

package/build/types/cmp/grid/GridModel.d.ts

@@ -10,6 +10,16 @@ import { GridAutosizeOptions } from './GridAutosizeOptions';
 import { GridContextMenuItemLike, GridContextMenuSpec } from './GridContextMenu';
 import { GridSorter, GridSorterLike } from './GridSorter';
 import { ColChooserConfig, ColumnState, GridModelPersistOptions, GroupRowRenderer, RowClassFn, RowClassRuleFn } from './Types';
+/**
+ * Configuration for a {@link GridModel} - the primary model backing the Hoist Grid component.
+ *
+ * At minimum, provide `columns` (an array of {@link ColumnSpec} or {@link ColumnGroupSpec}
+ * objects). A {@link Store} can be provided or will be auto-created with fields inferred
+ * from the column configs. Use `colDefaults` to apply shared settings across all columns.
+ *
+ * @see GridModel
+ * @see ColumnSpec
+ */
 export interface GridConfig {
     /** Columns for this grid. */
     columns?: ColumnOrGroupSpec[];
@@ -246,7 +256,7 @@ export interface GridModelDefaults {
     treeStyle?: TreeStyle;
 }
 /**
- * Core Model for a Grid, specifying the grid's data store, column definitions,
+ * Core Model for a {@link Grid}, specifying the grid's data store, column definitions,
  * sorting/grouping/selection state, and context menu configuration.
  *
  * This is the primary application entry-point for specifying Grid component options and behavior.
@@ -257,6 +267,11 @@ export interface GridModelDefaults {
  *   3) Include a single column with `isTreeColumn: true`. This column will provide expand /
  *      collapse controls and indent child columns in addition to displaying its own data.
  *
+ * See the grid package README (`cmp/grid/README.md`) for full documentation including column
+ * configuration, renderers, filtering, sorting, and common pitfalls.
+ *
+ * @see Grid
+ * @see DataView
  */
 export declare class GridModel extends HoistModel {
     /** App-level defaults for GridModel. Instance config takes precedence. */

package/build/types/cmp/grid/GridSorter.d.ts

@@ -1,9 +1,23 @@
 export type GridSorterLike = GridSorterSpec | string | GridSorter;
+/**
+ * Plain-object form of a {@link GridSorter}, specifying a column sort direction.
+ *
+ * Accepted by {@link GridModel.sortBy} alongside pipe-delimited strings and GridSorter
+ * instances. The framework parses these into immutable GridSorter objects automatically.
+ */
 export interface GridSorterSpec {
     colId: string;
     sort?: 'asc' | 'desc' | 'ASC' | 'DESC';
+    /** True to sort by absolute value, ignoring sign. */
     abs?: boolean;
 }
+/**
+ * Immutable value object representing a sort specification for a single grid column.
+ *
+ * Applications typically don't need to construct these directly - pass `GridSorterSpec` objects
+ * or pipe-delimited strings to {@link GridModel.sortBy} and the framework will parse them
+ * automatically.
+ */
 export declare class GridSorter {
     readonly colId: string;
     readonly sort: 'asc' | 'desc';

package/build/types/cmp/grid/Types.d.ts

@@ -55,6 +55,13 @@ export interface GridModelPersistOptions extends PersistOptions {
     /** True (default) to include expanded level state or provide expanded level-specific PersistOptions.  */
     persistExpandToLevel?: boolean | PersistOptions;
 }
+/**
+ * Configuration for a {@link GridFilterModel} - the model powering column-header filter menus.
+ * Passed via the `filterModel` config on {@link GridConfig}.
+ *
+ * @see GridFilterModel
+ * @see GridFilterFieldSpec
+ */
 export interface GridFilterModelConfig {
     /**
      * Target (typically a {@link Store} or Cube {@link View}) to be filtered as column filters
@@ -94,6 +101,13 @@ export interface GridFilterBindTarget extends FilterBindTarget, FilterValueSourc
  * @returns the formatted value for display.
  */
 export type GroupRowRenderer = (context: ICellRendererParams) => ReactNode;
+/**
+ * Configuration for a {@link ColChooserModel} - the model backing the grid column chooser UI.
+ * Passed via the `colChooserModel` config on {@link GridConfig}, or set app-wide via
+ * `GridModel.defaults.colChooserModel`.
+ *
+ * @see ColChooserModel
+ */
 export interface ColChooserConfig {
     /** GridModel to bind to. Not required if creating via `GridModel.colChooserModel` */
     gridModel?: GridModel;
@@ -283,6 +297,10 @@ export type ColumnGetValueFn<T = any> = (params: {
     column: Column;
     gridModel: GridModel;
 }) => T;
+/**
+ * Entry within a {@link ColumnSpec.sortingOrder} array, defining one step in the sort cycle
+ * applied by successive clicks on a column header.
+ */
 export interface ColumnSortSpec {
     /** Direction to sort, either 'asc' or 'desc', or null to remove sort. */
     sort: 'asc' | 'desc' | null;

package/build/types/cmp/grid/columns/Column.d.ts

@@ -4,6 +4,17 @@ import { FunctionComponent, ReactNode } from 'react';
 import { GridModel } from '../GridModel';
 import { ColumnCellClassFn, ColumnCellClassRuleFn, ColumnComparator, ColumnEditableFn, ColumnEditorFn, ColumnEditorProps, ColumnExcelFormatFn, ColumnExportValueFn, ColumnGetValueFn, ColumnHeaderClassFn, ColumnHeaderNameFn, ColumnRenderer, ColumnSetValueFn, ColumnSortSpec, ColumnSortValueFn, ColumnTooltipFn } from '../Types';
 import type { ColDef, CellClickedEvent } from '@xh/hoist/kit/ag-grid';
+/**
+ * Configuration object for defining a {@link Column} within a {@link GridModel}.
+ *
+ * Passed as plain objects in the `columns` array of a {@link GridConfig}. Each spec must
+ * identify its data via `field` (and/or `colId`). All other properties are optional and
+ * have sensible defaults - many are derived from the corresponding {@link Field} definition
+ * on the grid's store when available (e.g. `displayName`, `align`, `sortingOrder`).
+ *
+ * @see Column
+ * @see GridModel
+ */
 export interface ColumnSpec {
     /**
      * Name of data store field to display within the column, or object containing properties
@@ -138,7 +149,20 @@ export interface ColumnSpec {
      * ensuring it's visible while horizontally scrolling.
      */
     pinned?: boolean | HSide;
-    /** Function returning a React Element for each cell value in this Column.*/
+    /**
+     * Function returning a React Element for each cell value in this Column.
+     *
+     * For number and date formatting, prefer the pre-built `numberRenderer` and `dateRenderer`
+     * factories from `@xh/hoist/format` - these accept formatting options and return a reusable
+     * renderer function. Also consider the pre-built column specs (`number`, `date`, `dateTime`,
+     * `boolCheck` from `@xh/hoist/cmp/grid`) which bundle a renderer with appropriate alignment,
+     * sorting, and export formatting.
+     *
+     * For custom rendering based on record data beyond this column's field, set
+     * `rendererIsComplex: true` to ensure cells refresh on any record change.
+     *
+     * See the grid package README (`cmp/grid/README.md`) for renderer patterns and examples.
+     */
     renderer?: ColumnRenderer;
     /**
      * True if this renderer relies on more than just the value of the field associated with this
@@ -271,7 +295,21 @@ export interface ColumnSpec {
 }
 /**
  * Cross-platform definition and API for a standardized Grid column.
- * Provided to GridModels as plain configuration objects.
+ *
+ * Columns are defined as plain {@link ColumnSpec} objects within the `columns` array of a
+ * {@link GridConfig} - they are never constructed directly. GridModel also supports
+ * `colDefaults` for shared config applied to all columns, and `GridModel.defaults.colDefaults`
+ * for app-wide column defaults. Columns can be nested within {@link ColumnGroup}s for
+ * multi-level headers.
+ *
+ * Every column must resolve to a unique `colId`, which defaults to `field` when not set.
+ * If two columns reference the same `field`, provide an explicit `colId` on one of them.
+ *
+ * See {@link ColumnSpec} for all available configuration properties, and the grid package
+ * README (`cmp/grid/README.md`) for full configuration guidance, renderer patterns, and pitfalls.
+ *
+ * @see GridModel
+ * @see ColumnGroup
  */
 export declare class Column {
     static DEFAULT_WIDTH: number;

package/build/types/cmp/grid/columns/ColumnGroup.d.ts

@@ -4,6 +4,16 @@ import { ReactNode } from 'react';
 import { GridModel } from '../GridModel';
 import { ColumnHeaderClassFn, ColumnHeaderNameFn, ColumnOrGroup } from '../Types';
 import { Column, ColumnSpec } from './Column';
+/**
+ * Configuration for a {@link ColumnGroup} - a hierarchical grouping of columns that renders
+ * as a multi-level header in the grid. Nest {@link ColumnSpec} and/or additional
+ * ColumnGroupSpec objects within `children`.
+ *
+ * The `groupId` must be unique across the grid, defaulting to `headerName` when not set.
+ *
+ * @see ColumnGroup
+ * @see ColumnSpec
+ */
 export interface ColumnGroupSpec {
     /** Column or ColumnGroup configs for children of this group.*/
     children: Array<ColumnGroupSpec | ColumnSpec>;

package/build/types/cmp/grouping/GroupingChooserModel.d.ts

@@ -1,6 +1,13 @@
 import { HoistModel, PersistOptions } from '@xh/hoist/core';
 import type { GridModel } from '@xh/hoist/cmp/grid';
 import { View } from '@xh/hoist/data';
+/**
+ * Configuration for a {@link GroupingChooserModel} - a control for selecting multi-level
+ * dimension groupings, typically bound to a Cube {@link View} or {@link GridModel}.
+ *
+ * @see GroupingChooserModel
+ * @see DimensionSpec
+ */
 export interface GroupingChooserConfig {
     /** True to accept an empty list as a valid value. */
     allowEmpty?: boolean;
@@ -9,7 +16,7 @@ export interface GroupingChooserConfig {
      * should be automatically applied as it changes. When bound to a GridModel, calls
      * `setGroupBy()`; when bound to a View, calls `updateQuery({dimensions: ...})`.
      *
-     * This is a two-way binding — changes to the target's value are reflected back into
+     * This is a two-way binding - changes to the target's value are reflected back into
      * the GroupingChooserModel automatically.
      */
     bind?: GroupingBindTarget;
@@ -72,7 +79,7 @@ export type GroupingBindTarget = GridModel | View;
  *
  * Manages the current dimension selection, available dimensions, user-managed favorites, and
  * drag-and-drop reordering. Supports bidirectional binding to a {@link GridModel} or Cube
- * {@link View} via the `bind` config — grouping changes are automatically applied to the
+ * {@link View} via the `bind` config - grouping changes are automatically applied to the
  * target, and external changes to the target are reflected back into this model.
  *
  * Dimensions can be auto-populated from the bind target or specified explicitly. When binding

package/build/types/cmp/layout/Box.d.ts

@@ -1,16 +1,28 @@
 import { BoxProps, HoistProps } from '@xh/hoist/core';
+/**
+ * Props for {@link Box}, {@link VBox}, and {@link HBox} layout containers.
+ * Combines {@link HoistProps} with {@link BoxProps} (layout attributes resolved to CSS styles).
+ */
 export interface BoxComponentProps extends HoistProps, BoxProps {
 }
 /**
- * A Component that supports flexbox-based layout of its contents.
- *
- * Box is the component that provides the core implementation of the LayoutSupport mixin.
- * It renders a div and merges all layout props to that div's `style` property.
- *
- * Access to the internal div is provided via a ref argument.
+ * Base flexbox container that merges all {@link LayoutProps} - margin, padding, dimensions,
+ * flex, alignment, and overflow - onto a rendered `div`. This is the terminal component where
+ * layout props are resolved to CSS; higher-level components pass layout props through to a
+ * Box (or {@link Frame}) at the bottom of their render tree.
  *
- * VBox and HBox variants support internal vertical (column) and horizontal (row) flex layouts.
+ * **Application code should generally prefer {@link VBox} or {@link HBox}**, which make layout
+ * direction explicit. Bare `box()` applies `display: flex` with the CSS default direction (row)
+ * but does not communicate that intent clearly.
  */
 export declare const Box: import("react").FC<BoxComponentProps>, box: import("@xh/hoist/core").ElementFactory<BoxComponentProps>;
+/**
+ * A {@link Box} with vertical (column) flex layout. Does not stretch to fill its parent -
+ * use {@link VFrame} instead when the container should grow to consume available space.
+ */
 export declare const VBox: import("react").FC<BoxComponentProps>, vbox: import("@xh/hoist/core").ElementFactory<BoxComponentProps>;
+/**
+ * A {@link Box} with horizontal (row) flex layout. Does not stretch to fill its parent -
+ * use {@link HFrame} instead when the container should grow to consume available space.
+ */
 export declare const HBox: import("react").FC<BoxComponentProps>, hbox: import("@xh/hoist/core").ElementFactory<BoxComponentProps>;

package/build/types/cmp/layout/Frame.d.ts

@@ -1,14 +1,26 @@
 import { BoxProps, HoistProps } from '@xh/hoist/core';
+/**
+ * Props for {@link Frame}, {@link VFrame}, and {@link HFrame} layout containers.
+ * Combines {@link HoistProps} with {@link BoxProps} (layout attributes resolved to CSS styles).
+ */
 export interface FrameProps extends HoistProps, BoxProps {
 }
 /**
- * A Box class that flexes to grow and stretch within its *own* parent via flex:'auto', useful for
- * creating nested layouts.
+ * A {@link Box} that stretches to fill its parent via `flex: auto`. Like Box, it supports
+ * all {@link LayoutProps} and merges them onto its rendered `div`.
  *
- * Like Box, Frame provides access to its internal div via a ref argument.
- *
- * VFrame and HFrame variants support internal vertical (column) and horizontal (row) flex layouts.
+ * **Application code should generally prefer {@link VFrame} or {@link HFrame}**, which make
+ * layout direction explicit. Bare `frame()` inherits the CSS default direction (row) but does
+ * not communicate that intent clearly.
  */
 export declare const Frame: import("react").FC<FrameProps>, frame: import("@xh/hoist/core").ElementFactory<FrameProps>;
+/**
+ * A {@link Frame} with vertical (column) flex layout. Stretches to fill its parent via
+ * `flex: auto` - use {@link VBox} instead when the container should size to its content.
+ */
 export declare const VFrame: import("react").FC<FrameProps>, vframe: import("@xh/hoist/core").ElementFactory<FrameProps>;
+/**
+ * A {@link Frame} with horizontal (row) flex layout. Stretches to fill its parent via
+ * `flex: auto` - use {@link HBox} instead when the container should size to its content.
+ */
 export declare const HFrame: import("react").FC<FrameProps>, hframe: import("@xh/hoist/core").ElementFactory<FrameProps>;

package/build/types/cmp/loadingindicator/LoadingIndicator.d.ts

@@ -1,5 +1,7 @@
+import { SpinnerProps } from '@xh/hoist/cmp/spinner';
 import { Corner, HoistProps, Some, TaskObserver } from '@xh/hoist/core';
 import './LoadingIndicator.scss';
+import { ReactNode } from 'react';
 export interface LoadingIndicatorProps extends HoistProps {
     /** TaskObserver(s) that should be monitored to determine if the Indicator should be displayed. */
     bind?: Some<TaskObserver>;
@@ -7,12 +9,12 @@ export interface LoadingIndicatorProps extends HoistProps {
     corner?: Corner;
     /** True to display the indicator. */
     isDisplayed?: boolean;
-    /** Max characters allowed in message, after which it will be elided. Default 30. */
+    /** Max characters allowed in a String message, after which it will be elided. Default 30. */
     maxMessageLength?: number;
     /** Optional text to be displayed - can also be sourced from bound TaskObserver. */
-    message?: string;
-    /** True (default) to display with an animated spinner. */
-    spinner?: boolean;
+    message?: ReactNode;
+    /** True (default) to display with an animated spinner, or SpinnerProps to customize. */
+    spinner?: boolean | Omit<SpinnerProps, 'compact'>;
 }
 /**
  * A minimal / unobtrusive LoadingIndicator displaying an optional spinner and/or message to signal

package/build/types/cmp/pinpad/PinPadModel.d.ts

@@ -1,4 +1,9 @@
 import { HoistModel } from '@xh/hoist/core';
+/**
+ * Configuration for a {@link PinPadModel} - a numeric keypad for collecting a PIN.
+ *
+ * @see PinPadModel
+ */
 export interface PinPadConfig {
     /** The length of the PIN to get from the user, default 4. */
     pinLength?: number;
@@ -6,7 +11,7 @@ export interface PinPadConfig {
     subHeaderText?: string;
 }
 /**
- * Model for a PinPad — a numeric keypad prompt for collecting a PIN from the user.
+ * Model for a PinPad - a numeric keypad prompt for collecting a PIN from the user.
  *
  * Tracks entered digits, validates PIN completion, and provides observable `value` and
  * `isComplete` getters. Supports configurable PIN length and custom header/subheader text.

package/build/types/cmp/spinner/Spinner.d.ts

@@ -1,16 +1,37 @@
+import { IconName } from '@fortawesome/fontawesome-svg-core';
 import { HoistProps } from '@xh/hoist/core';
-import { ImgHTMLAttributes } from 'react';
-export interface SpinnerProps extends HoistProps, ImgHTMLAttributes<HTMLImageElement> {
-    /** True to return a smaller 20px image vs default 50px. */
+import { HoistIconPrefix } from '@xh/hoist/icon';
+import './Spinner.scss';
+export interface SpinnerDefaults {
+    iconName?: IconName;
+    prefix?: HoistIconPrefix;
+    usePng?: boolean;
+}
+export interface SpinnerProps extends HoistProps {
+    /** True to return a smaller spinner suitable for inline/compact use. */
     compact?: boolean;
+    /** FA icon name to use. Default set via `Spinner.defaults.iconName`. */
+    iconName?: IconName;
+    /** FA icon prefix/weight. Default set via `Spinner.defaults.prefix`. */
+    prefix?: HoistIconPrefix;
+    /** True to use legacy animated PNG images. Default set via `Spinner.defaults.usePng`. */
+    usePng?: boolean;
 }
 /**
- * Returns an img-based spinner in one of two sizes - default 50px spinner or smaller 20px spinner
- * when `compact: true`. Used for the platform-specific `Mask` and `LoadingIndicator` components.
+ * An animated spinner rendered via a FontAwesome icon with a CSS rotation animation. Used for
+ * the platform-specific `Mask` and `LoadingIndicator` components.
+ *
+ * The rotation animation is applied via CSS on the `.xh-spinner` class rather than FA's
+ * animation props, ensuring the spinner remains functional when the OS-level
+ * `prefers-reduced-motion` preference is enabled (FA disables all its animations in that case).
+ *
+ * The icon and legacy PNG fallback can be configured per-instance via props or globally via
+ * `Spinner.defaults` (e.g. in app Bootstrap.ts):
  *
- * Note that the source images are animated PNGs generated via https://loading.io. These are used
- * in place of SVG-based options to reduce rendering overhead, especially when accessing an app
- * via a remote desktop technology such as Citrix (where the spinners bundled with e.g. Blueprint
- * were observed to cause unpredictable and unexpectedly severe performance issues).
+ * ```ts
+ * Spinner.defaults.iconName = 'circle-notch';
+ * Spinner.defaults.prefix = 'far';
+ * Spinner.defaults.usePng = true;  // fall back to animated PNG
+ * ```
  */
-export declare const Spinner: import("react").FC<SpinnerProps>, spinner: import("@xh/hoist/core").ElementFactory<SpinnerProps>;
+export declare const Spinner: any, spinner: import("@xh/hoist/core").ElementFactory<SpinnerProps>;

package/build/types/cmp/tab/TabContainerModel.d.ts

@@ -2,6 +2,14 @@ import type { TabSwitcherConfig, IDynamicTabSwitcherModel, TabContainerModelPers
 import { HoistModel, RefreshContextModel, RefreshMode, RenderMode } from '@xh/hoist/core';
 import { ReactNode } from 'react';
 import { TabConfig, TabModel } from './TabModel';
+/**
+ * Configuration for a {@link TabContainerModel} - the primary tabbed navigation container
+ * in Hoist. Supports routing, lazy rendering/refresh strategies, and optional persistence
+ * of the active tab.
+ *
+ * @see TabContainerModel
+ * @see TabConfig
+ */
 export interface TabContainerConfig {
     /** Tabs to be displayed. */
     tabs: TabConfig[];
@@ -57,6 +65,9 @@ export interface TabContainerConfig {
  * unmounting of inactive tabs, and customizable refreshing of tabs via a built-in RefreshContextModel.
  *
  * Note: Routing is currently enabled for desktop applications only.
+ *
+ * See the tab package README (`cmp/tab/README.md`) for render/refresh mode options, routing
+ * configuration, and usage patterns.
  */
 export declare class TabContainerModel extends HoistModel {
     config: TabContainerConfig;

package/build/types/cmp/tab/TabModel.d.ts

@@ -1,6 +1,13 @@
 import { HoistModel, RefreshMode, RenderMode, Content, RefreshContextModel, Thunkable } from '@xh/hoist/core';
 import { TabContainerConfig, TabContainerModel } from '@xh/hoist/cmp/tab';
 import { ReactElement, ReactNode } from 'react';
+/**
+ * Configuration for a {@link TabModel} - a single tab within a {@link TabContainerModel}.
+ * Passed as entries in the `tabs` array of a {@link TabContainerConfig}.
+ *
+ * @see TabModel
+ * @see TabContainerConfig
+ */
 export interface TabConfig {
     /** Unique ID, used by container for locating tabs and generating routes. */
     id: string;

package/build/types/cmp/tab/Types.d.ts

@@ -21,6 +21,10 @@ export interface TabSwitcherProps extends HoistProps<TabContainerModel>, BoxProp
     /** Maximum width (in px) to render tabs. Only applies to horizontal orientations */
     tabMaxWidth?: number;
 }
+/**
+ * Configuration for the tab switcher UI within a {@link TabContainerModel}. Passed via the
+ * `switcher` config on {@link TabContainerConfig}.
+ */
 export interface TabSwitcherConfig {
     /** Specification for type of switcher. Specify `dynamic`for user-configurable tabs */
     mode: 'static' | 'dynamic';

package/build/types/cmp/treemap/TreeMapModel.d.ts

@@ -76,9 +76,9 @@ export interface TreeMapModelDefaults {
  *
  * Node colors are normalized to a 0-1 range and mapped to a colorAxis. The `colorMode` config
  * controls how:
- * - 'linear' — distributes values across the colorAxis according to the heatField.
- * - 'wash' — ignores heat intensity, applying a single positive/negative color.
- * - 'none' — ignores the colorAxis entirely, using the neutral color.
+ * - 'linear' - distributes values across the colorAxis according to the heatField.
+ * - 'wash' - ignores heat intensity, applying a single positive/negative color.
+ * - 'none' - ignores the colorAxis entirely, using the neutral color.
  *
  * Color customization can be managed by setting colorAxis stops via `highchartsConfig`.
  * See {@link https://www.highcharts.com/docs/chart-and-series-types/treemap} for Highcharts

package/build/types/cmp/viewmanager/ViewManagerModel.d.ts

@@ -18,6 +18,12 @@ export interface ViewUserState {
     userPinned: Record<string, boolean>;
     autoSave: boolean;
 }
+/**
+ * Configuration for a {@link ViewManagerModel} - persists and manages named user views
+ * (saved configurations) for grids, dashboards, or other stateful components.
+ *
+ * @see ViewManagerModel
+ */
 export interface ViewManagerConfig {
     /**
      * Required discriminator for the particular class of views to be loaded and managed by this
@@ -109,6 +115,9 @@ export interface ViewManagerConfig {
  *  - Views can be private to their owner, or optionally enabled for sharing to (all) other users.
  *  - Views can be marked as pinned for quick access.
  *  - See the desktop {@link ViewManager} component - the initial Hoist UI for this model.
+ *
+ * See the view manager package README (`cmp/viewmanager/README.md`) for architecture,
+ * integration patterns, and access control configuration.
  */
 export declare class ViewManagerModel<T = PlainObject> extends HoistModel {
     /**

package/build/types/cmp/zoneGrid/ZoneGridModel.d.ts

@@ -5,6 +5,14 @@ import { RecordAction, Store, StoreConfig, StoreRecordOrId, StoreSelectionConfig
 import { ReactNode } from 'react';
 import { ZoneMapperConfig, ZoneMapperModel } from './impl/ZoneMapperModel';
 import { Zone, ZoneGridModelPersistOptions, ZoneLimit, ZoneMapping } from './Types';
+/**
+ * Configuration for a {@link ZoneGridModel} - a card-style grid that arranges column data
+ * into four zones (top-left, top-right, bottom-left, bottom-right) within each row.
+ * Provide `columns` and `mappings` to define which fields appear in each zone.
+ *
+ * @see ZoneGridModel
+ * @see ZoneMapperConfig
+ */
 export interface ZoneGridConfig {
     /**
      * Available columns for this grid. Columns with an omit property evaluating to true will be
@@ -192,10 +200,21 @@ export interface ZoneGridConfig {
     xhImpl?: boolean;
 }
 /**
- * ZoneGridModel is a wrapper around GridModel, which shows date in a grid with multi-line
- * full-width rows, each broken into four zones for top/bottom and left/right.
+ * Model for a ZoneGrid - a card-style grid that renders each row as a full-width block
+ * divided into four zones: top-left, top-right, bottom-left, and bottom-right. Built on
+ * {@link GridModel} internally.
+ *
+ * Use ZoneGrid when you want a structured multi-field card layout per row without writing
+ * a fully custom renderer. Especially well-suited for mobile or other space-constrained
+ * contexts where horizontal scrolling is undesirable but four or more user-configurable
+ * fields need to be visible per row. The `mappings` config controls which columns appear
+ * in each zone, and users can rearrange them via the optional ZoneMapper UI.
+ *
+ * For a standard column-based grid, use {@link GridModel}. For fully custom row rendering,
+ * use {@link DataViewModel}.
  *
- * This is the primary app entry-point for specifying ZoneGrid component options and behavior.
+ * @see ZoneGrid
+ * @see ZoneGridConfig
  */
 export declare class ZoneGridModel extends HoistModel {
     gridModel: GridModel;

package/build/types/cmp/zoneGrid/impl/ZoneMapperModel.d.ts

@@ -4,6 +4,12 @@ import { GridSorter } from '@xh/hoist/cmp/grid';
 import { ReactNode } from 'react';
 import { ZoneGridModel } from '../ZoneGridModel';
 import { ZoneField, Zone, ZoneLimit, ZoneMapping } from '../Types';
+/**
+ * Configuration for a ZoneMapperModel - the UI for user-driven customization of zone
+ * column mappings. Passed via the `zoneMapperModel` config on {@link ZoneGridConfig}.
+ *
+ * @see ZoneGridModel
+ */
 export interface ZoneMapperConfig {
     /** The ZoneGridModel to be configured. */
     zoneGridModel: ZoneGridModel;

package/build/types/core/HoistComponent.d.ts

@@ -1,4 +1,4 @@
-import { HoistProps, DefaultHoistProps, ElementFactory } from './';
+import { HoistProps, DefaultHoistProps, ElementFactory, PlainObject } from './';
 import { ModelSpec, HoistModel } from './model';
 import { ForwardedRef, FC, ReactNode } from 'react';
 /**
@@ -20,7 +20,7 @@ export type RenderPropsOf<P extends HoistProps> = P & {
  * Configuration for creating a Component.  May be specified either as a render function,
  * or an object containing a render function and associated metadata.
  */
-export type ComponentConfig<P extends HoistProps> = ((props: RenderPropsOf<P>, ref?: ForwardedRef<any>) => ReactNode) | {
+export type ComponentConfig<P extends HoistProps, D extends PlainObject = never> = ((props: RenderPropsOf<P>, ref?: ForwardedRef<any>) => ReactNode) | {
     /** Render function defining the component. */
     render(props: RenderPropsOf<P>, ref?: ForwardedRef<any>): ReactNode;
     /**
@@ -49,9 +49,18 @@ export type ComponentConfig<P extends HoistProps> = ((props: RenderPropsOf<P>, r
      *  state may set this to `false`, but this is not typically done by application code.
      */
     observer?: boolean;
+    /**
+     * Static, app-wide configuration for the component, attached to the returned component
+     * as a typed `defaults` object that applications can modify at bootstrap to customize
+     * behavior for all instances (e.g. `Button.defaults.minimal = false` in Bootstrap.ts).
+     *
+     * Most commonly used to supply default values for selected props. May also be used for
+     * other app-overridable settings that are not exposed as props.
+     */
+    defaults?: D;
 };
 /**
- * The primary entry point for defining Hoist components — functional React components enhanced
+ * The primary entry point for defining Hoist components - functional React components enhanced
  * with MobX reactivity and integrated model support.
  *
  * Accepts a configuration object (or a bare render function) and returns a React functional
@@ -63,22 +72,31 @@ export type ComponentConfig<P extends HoistProps> = ((props: RenderPropsOf<P>, r
  * when observable state read during render changes.
  *
  * Forward refs ({@link https://reactjs.org/docs/forwarding-refs.html}) are supported by
- * specifying a render function with two arguments — the second is treated as a ref, and
+ * specifying a render function with two arguments - the second is treated as a ref, and
  * `React.forwardRef` is applied automatically.
  *
  * Most components should be defined via one of two convenience methods rather than calling
  * this function directly:
- * - `hoistCmp.factory()` — returns an element factory (the standard pattern for app components).
- * - `hoistCmp.withFactory()` — returns a `[Component, factory]` pair (the standard pattern for
+ * - `hoistCmp.factory()` - returns an element factory (the standard pattern for app components).
+ * - `hoistCmp.withFactory()` - returns a `[Component, factory]` pair (the standard pattern for
  *    library components that need to export both).
  *
- * See `core/README.md` for full documentation on component configuration, model specs, and
- * context lookup behavior.
+ * See the core package README (`core/README.md`) for full documentation on component
+ * configuration, model specs, and context lookup behavior.
+ *
+ * Components can also declare a typed `defaults` object in their config to expose static,
+ * app-wide configuration - most typically default values for selected props, but also other
+ * settings designed to be overridden by applications at bootstrap (e.g.
+ * `Button.defaults.minimal = false` in Bootstrap.ts). When specified, the returned component
+ * exposes a typed `defaults` property.
  *
  * @param config - specification object, or a render function defining the component.
  * @returns a functional React Component for use within Hoist apps.
  */
 export declare function hoistCmp<M extends HoistModel>(config: ComponentConfig<DefaultHoistProps<M>>): FC<DefaultHoistProps<M>>;
+export declare function hoistCmp<P extends HoistProps, D extends PlainObject>(config: ComponentConfig<P, D>): FC<P> & {
+    defaults: D;
+};
 export declare function hoistCmp<P extends HoistProps>(config: ComponentConfig<P>): FC<P>;
 export declare namespace hoistCmp {
     var factory: typeof hoistCmpFactory;
@@ -102,6 +120,9 @@ export declare function hoistCmpFactory<P extends HoistProps>(config: ComponentC
  * Not typically used by applications.
  */
 export declare function hoistCmpWithFactory<M extends HoistModel>(config: ComponentConfig<DefaultHoistProps<M>>): [FC<DefaultHoistProps<M>>, ElementFactory<DefaultHoistProps<M>>];
+export declare function hoistCmpWithFactory<P extends HoistProps, D extends PlainObject>(config: ComponentConfig<P, D>): [FC<P> & {
+    defaults: D;
+}, ElementFactory<P>];
 export declare function hoistCmpWithFactory<P extends HoistProps>(config: ComponentConfig<P>): [FC<P>, ElementFactory<P>];
 /**
  * Component to render certain errors caught within hoistComponent.

package/build/types/core/HoistProps.d.ts

@@ -46,10 +46,16 @@ export interface DefaultHoistProps<M extends HoistModel = HoistModel> extends Ho
     [x: string]: any;
 }
 /**
- * Props for Components that support standard Layout attributes
+ * Props for components that support standard layout attributes (margin, padding, dimensions,
+ * flex, alignment, overflow). Extends {@link LayoutProps} with test support and standard
+ * HTML div attributes.
  *
- * Most component will typically separate these props out and pass them along to another component
- * which also supports this interface.  Eventually, they should be passed to a Box class.
+ * Higher-level components accept these props and pass them through to a {@link Box} or
+ * {@link Frame} at the bottom of their render tree, where they are resolved to CSS styles.
+ *
+ * @see Box
+ * @see Frame
+ * @see LayoutProps
  */
 export interface BoxProps extends LayoutProps, TestSupportProps, Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'contextMenu'> {
 }

package/build/types/core/load/LoadSpec.d.ts

@@ -16,7 +16,7 @@ export type LoadSpecConfig = {
  * LoadSpec instances directly.
  *
  * Within `doLoadAsync()`, check {@link isStale} after any async call to determine if a newer
- * load has already been requested — if so, return early to avoid applying outdated results.
+ * load has already been requested - if so, return early to avoid applying outdated results.
  * Check {@link isAutoRefresh} to adjust behavior for background refreshes (e.g. skip expensive
  * operations, avoid user-facing error dialogs).
  *