@xh/hoist 83.1.0 → 84.0.1

package/cmp/loadingindicator/LoadingIndicator.ts

@@ -6,7 +6,7 @@
  */
 import {hbox} from '@xh/hoist/cmp/layout';
 import {div} from '@xh/hoist/cmp/layout/Tags';
-import {spinner as spinnerCmp} from '@xh/hoist/cmp/spinner';
+import {spinner as spinnerCmp, SpinnerProps} from '@xh/hoist/cmp/spinner';
 import {
     Corner,
     hoistCmp,
@@ -18,8 +18,9 @@ import {
 } from '@xh/hoist/core';
 import {withDefault} from '@xh/hoist/utils/js';
 import classNames from 'classnames';
-import {truncate} from 'lodash';
+import {isString, truncate} from 'lodash';
 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. */
@@ -28,12 +29,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'>;
 }
 
 /**
@@ -56,7 +57,7 @@ export const [LoadingIndicator, loadingIndicator] = hoistCmp.withFactory<Loading
 
         isDisplayed = withDefault(isDisplayed, impl.task?.isPending);
         message = withDefault(message, impl.task?.message);
-        message = truncate(message, {length: maxMessageLength});
+        message = isString(message) ? truncate(message, {length: maxMessageLength}) : message;
 
         if (!isDisplayed || (!spinner && !message)) return null;
 
@@ -65,7 +66,8 @@ export const [LoadingIndicator, loadingIndicator] = hoistCmp.withFactory<Loading
             cornerCls = `xh-loading-indicator--${corner}`;
 
         const innerItems = () => {
-            let spinnerEl = spinnerCmp({compact: true});
+            const spinnerProps = spinner === true ? {} : spinner || {};
+            let spinnerEl = spinnerCmp({compact: true, ...spinnerProps});
 
             if (!message) return [spinnerEl];
 
@@ -83,7 +85,7 @@ export const [LoadingIndicator, loadingIndicator] = hoistCmp.withFactory<Loading
 });
 
 class LocalMaskModel extends HoistModel {
-    task;
+    task: TaskObserver;
 
     override onLinked() {
         const {bind} = this.componentProps;

package/cmp/pinpad/PinPadModel.ts

@@ -14,6 +14,11 @@ import {times} from 'lodash';
 // safe to use with the desktop kit.
 import FastClick from '@onsenui/fastclick';
 
+/**
+ * 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;
@@ -22,7 +27,7 @@ export interface PinPadConfig {
 }
 
 /**
- * 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/cmp/spinner/Spinner.scss

@@ -0,0 +1,13 @@
+.xh-spinner {
+  color: var(--xh-spinner-color);
+}
+
+svg.xh-spinner {
+  animation: xh-spin 2s linear infinite;
+}
+
+@keyframes xh-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}

package/cmp/spinner/Spinner.ts

@@ -4,43 +4,81 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
+import {IconName} from '@fortawesome/fontawesome-svg-core';
 import {img} from '@xh/hoist/cmp/layout';
 import {hoistCmp, HoistProps} from '@xh/hoist/core';
-import {ImgHTMLAttributes} from 'react';
-
-// @ts-ignore
+import {HoistIconPrefix, Icon} from '@xh/hoist/icon';
 import compactSpinnerImg from './spinner-20px.png';
-// @ts-ignore
 import spinnerImg from './spinner-50px.png';
+import './Spinner.scss';
+
+export interface SpinnerDefaults {
+    iconName?: IconName;
+    prefix?: HoistIconPrefix;
+    usePng?: boolean;
+}
 
-export interface SpinnerProps extends HoistProps, ImgHTMLAttributes<HTMLImageElement> {
-    /** True to return a smaller 20px image vs default 50px. */
+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).
  *
- * 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).
+ * The icon and legacy PNG fallback can be configured per-instance via props or globally via
+ * `Spinner.defaults` (e.g. in app Bootstrap.ts):
+ *
+ * ```ts
+ * Spinner.defaults.iconName = 'circle-notch';
+ * Spinner.defaults.prefix = 'far';
+ * Spinner.defaults.usePng = true;  // fall back to animated PNG
+ * ```
  */
-export const [Spinner, spinner] = hoistCmp.withFactory<SpinnerProps>({
+export const [Spinner, spinner] = hoistCmp.withFactory<SpinnerProps, SpinnerDefaults>({
     displayName: 'Spinner',
     className: 'xh-spinner',
     model: false,
     observer: false,
-
+    defaults: {
+        iconName: 'spinner-third',
+        prefix: 'fal',
+        usePng: false
+    },
     render({compact, className, ...props}) {
-        const pxSize = compact ? '20px' : '50px';
-        return img({
-            src: compact ? compactSpinnerImg : spinnerImg,
-            width: pxSize,
-            height: pxSize,
+        const {defaults} = Spinner,
+            iconName: IconName = props.iconName ?? defaults.iconName,
+            prefix = props.prefix ?? defaults.prefix,
+            usePng = props.usePng ?? defaults.usePng;
+
+        if (usePng) {
+            const pxSize = compact ? '20px' : '50px';
+            return img({
+                src: compact ? compactSpinnerImg : spinnerImg,
+                width: pxSize,
+                height: pxSize,
+                className
+            });
+        }
+
+        // Animation is applied via CSS on .xh-spinner rather than FA's animation props,
+        // which are disabled by FA's blanket prefers-reduced-motion override.
+        return Icon.icon({
+            iconName,
+            prefix,
             className,
-            ...props
+            size: compact ? 'lg' : '3x'
         });
     }
 });

package/cmp/tab/TabContainerModel.ts

@@ -28,6 +28,14 @@ import {difference, find, findLast, isObject, isString, without} from 'lodash';
 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[];
@@ -93,6 +101,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 class TabContainerModel extends HoistModel {
     declare config: TabContainerConfig;

package/cmp/tab/TabModel.ts

@@ -21,6 +21,13 @@ import {isArray, isUndefined, startCase} from 'lodash';
 import {TabContainerConfig, TabContainerModel, tabContainer} 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/cmp/tab/Types.ts

@@ -37,6 +37,10 @@ export interface TabSwitcherProps extends HoistProps<TabContainerModel>, BoxProp
     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/cmp/treemap/TreeMapModel.ts

@@ -108,9 +108,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/cmp/viewmanager/ViewManagerModel.ts

@@ -55,6 +55,12 @@ export interface ViewUserState {
     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
@@ -159,6 +165,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 class ViewManagerModel<T = PlainObject> extends HoistModel {
     /**

package/cmp/zoneGrid/ZoneGridModel.ts

@@ -61,6 +61,14 @@ import {initPersist} from './impl/InitPersist';
 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
@@ -296,10 +304,21 @@ export interface ZoneGridConfig {
 }
 
 /**
- * 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 class ZoneGridModel extends HoistModel {
     @managed

package/cmp/zoneGrid/impl/ZoneMapperModel.ts

@@ -15,6 +15,12 @@ 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/core/ExceptionHandler.ts

@@ -275,7 +275,7 @@ export class ExceptionHandler {
                     }
                     delete fetchOptions.loadSpec;
                 }
-                // Remove Span object — not useful in serialized output.
+                // Remove Span object - not useful in serialized output.
                 delete fetchOptions.span;
             }
 

package/core/HoistComponent.ts

@@ -12,7 +12,8 @@ import {
     DefaultHoistProps,
     elementFactory,
     ElementFactory,
-    TestSupportProps
+    TestSupportProps,
+    PlainObject
 } from './';
 import {
     useModelLinker,
@@ -67,7 +68,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> =
+export type ComponentConfig<P extends HoistProps, D extends PlainObject = never> =
     | ((props: RenderPropsOf<P>, ref?: ForwardedRef<any>) => ReactNode)
     | {
           /** Render function defining the component. */
@@ -103,12 +104,22 @@ export type ComponentConfig<P extends HoistProps> =
            *  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;
       };
 
 let cmpIndex = 0; // index for anonymous component dispay names
 
 /**
- * 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
@@ -120,17 +131,23 @@ let cmpIndex = 0; // index for anonymous component dispay names
  * 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.
@@ -138,6 +155,9 @@ let cmpIndex = 0; // index for anonymous component dispay names
 export function hoistCmp<M extends HoistModel>(
     config: ComponentConfig<DefaultHoistProps<M>>
 ): FC<DefaultHoistProps<M>>;
+export function hoistCmp<P extends HoistProps, D extends PlainObject>(
+    config: ComponentConfig<P, D>
+): FC<P> & {defaults: D};
 export function hoistCmp<P extends HoistProps>(config: ComponentConfig<P>): FC<P>;
 export function hoistCmp<P extends HoistProps>(config: ComponentConfig<P>): FC<P> {
     // 0) Pre-process/parse args.
@@ -157,7 +177,8 @@ export function hoistCmp<P extends HoistProps>(config: ComponentConfig<P>): FC<P
             isMemo: withDefault(config.memo, true),
             isObserver: withDefault(config.observer, true),
             isForwardRef: render.length === 2,
-            modelSpec: modelSpec ? modelSpec : null
+            modelSpec: modelSpec ? modelSpec : null,
+            defaults: config.defaults ?? null
         };
 
     warnIf(
@@ -176,16 +197,16 @@ export function hoistCmp<P extends HoistProps>(config: ComponentConfig<P>): FC<P
         render = wrapWithClonedProps(render);
     }
 
-    // 4) Wrap with standard react HOCs, mark, and return.
+    // 4) Wrap with standard react HOCs, mark, install defaults if specified, and return.
     let ret = render as any;
     ret.displayName = cfg.displayName;
     if (cfg.isForwardRef) ret = forwardRef(ret);
     if (cfg.isObserver) ret = observer(ret);
     if (cfg.isMemo && !cfg.isObserver) ret = memo(ret);
 
-    // 4) Mark and return.
     ret.displayName = cfg.displayName;
     ret.isHoistComponent = true;
+    if (cfg.defaults) ret.defaults = cfg.defaults;
 
     return ret;
 }
@@ -220,6 +241,9 @@ hoistCmp.factory = hoistCmpFactory;
 export function hoistCmpWithFactory<M extends HoistModel>(
     config: ComponentConfig<DefaultHoistProps<M>>
 ): [FC<DefaultHoistProps<M>>, ElementFactory<DefaultHoistProps<M>>];
+export function hoistCmpWithFactory<P extends HoistProps, D extends PlainObject>(
+    config: ComponentConfig<P, D>
+): [FC<P> & {defaults: D}, ElementFactory<P>];
 export function hoistCmpWithFactory<P extends HoistProps>(
     config: ComponentConfig<P>
 ): [FC<P>, ElementFactory<P>];
@@ -245,6 +269,7 @@ interface Config {
     isForwardRef: boolean;
     isMemo: boolean;
     modelSpec: ModelSpec;
+    defaults: PlainObject;
 }
 
 interface ResolvedModel {

package/core/HoistProps.ts

@@ -61,10 +61,16 @@ export interface DefaultHoistProps<M extends HoistModel = HoistModel> extends Ho
 }
 
 /**
- * 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

package/core/README.md

@@ -1,5 +1,19 @@
 # Core Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Architecture overview and primary artifact types |
+| [Class Hierarchy](#class-hierarchy) | Inheritance tree for Hoist's foundational classes |
+| [HoistBase](#hoistbase) | MobX integration, resource management, and lifecycle |
+| [HoistModel](#hoistmodel) | Stateful UI backing — linked/unlinked models, loading, lookup |
+| [HoistService](#hoistservice) | Singleton services for app-wide state and data access |
+| [Components and hoistCmp](#components-and-hoistcmp) | Functional components with MobX reactivity, model wiring, and defaults |
+| [Element Factories](#element-factories) | Declarative JS-native alternative to JSX |
+| [XH Singleton](#xh-singleton) | Top-level API entry point for the framework |
+| [Decorators Reference](#decorators-reference) | Quick reference for all Hoist and MobX decorators |
+| [Common Patterns](#common-patterns) | Constructor boilerplate, async naming, multiple models, error handling |
+| [Common Pitfalls](#common-pitfalls) | Frequently encountered issues and how to avoid them |
+
 ## Overview
 
 The `/core/` package contains the foundational classes and utilities that define Hoist's architecture.
@@ -349,7 +363,7 @@ export const userDetail = hoistCmp.factory({
 // Simple component with no model
 export const statusBadge = hoistCmp.factory({
     model: false,
-    className: 'status-badge',
+    className: 'my-app-status-badge',
     render({status, className}) {
         return div({className, item: status});
     }
@@ -366,11 +380,20 @@ export const statusBadge = hoistCmp.factory({
 | `displayName` | - | Component name for debugging |
 | `memo` | `true` | Wrap with React.memo |
 | `observer` | `true` | Enable MobX reactivity |
-
-> **Note:** When `className` is specified in the component config, it becomes the base class for
-> the component. Any `className` passed by callers is added as an additional class, and the
-> combined value is provided to `render()` via props. Apply this merged `className` to the
-> component's root element.
+| `defaults` | - | Typed static config for the component, overridable at app bootstrap (see below) |
+
+> **Best practice: Define `className` in the component spec** rather than hardcoding it inside
+> the render function. The framework automatically merges the spec's base class with any
+> `className` passed by callers, ensuring every component consistently supports caller-provided
+> CSS class overrides without each render function needing to handle the merging itself.
+>
+> The merged `className` is provided to `render()` via props — it already contains both the
+> base class from the spec and any caller-supplied classes. Apply it to the component's root
+> element. If you need to add conditional modifier classes, combine them with the prop value
+> (e.g. via the `classNames` library) — but don't re-add the base class, it's already included.
+>
+> Hoist library components use the `xh-` prefix for their base class names (e.g.
+> `className: 'xh-panel'`). Applications should standardize on their own app-specific prefix.
 
 ### Model Specs: creates() vs uses()
 
@@ -454,6 +477,45 @@ export const myInput = hoistCmp.factory({
 });
 ```
 
+### Component Defaults
+
+Components can declare a typed `defaults` object to expose **static, app-wide configuration** that
+applications can override at bootstrap (e.g. in `Bootstrap.ts`) to customize all instances of the
+component.
+
+Most often this supplies default values for selected props — when read in `render` as fallbacks,
+**instance props take precedence**. But `defaults` is not restricted to props and may carry other
+app-overridable settings (thresholds, modes, etc.).
+
+```typescript
+// 1) Define a defaults interface — typically mirrors a few props the author wants to be
+//    globally configurable, but may also include non-prop tunables.
+export interface ButtonDefaults {
+    minimal?: boolean;
+    outlined?: boolean;
+}
+
+// 2) Pass as a second generic and include in the component config
+export const [Button, button] = hoistCmp.withFactory<ButtonProps, ButtonDefaults>({
+    displayName: 'Button',
+    defaults: {
+        minimal: true,
+        outlined: false
+    },
+    render(props) {
+        const {defaults} = Button;
+        const {minimal = defaults.minimal, outlined = defaults.outlined, ...rest} = props;
+        // ...
+    }
+});
+
+// 3) Override in app Bootstrap.ts — mutate fields directly.
+Button.defaults.minimal = false;
+```
+
+This pattern is analogous to `static defaults` on Model and Service classes (e.g.
+`GridModel.defaults`), adapted for functional components created via `hoistCmp`.
+
 ## Element Factories
 
 **File**: `elem.ts`

package/core/impl/InstanceManager.ts

@@ -51,6 +51,7 @@ class InstanceManager {
     registerModelWithTestId(testId: string, m: HoistModel) {
         if (
             isNil(testId) ||
+            isNil(m) ||
             !m.isHoistModel ||
             !this.testSupportedModels.has(m.constructor.name) ||
             this.modelsByTestId.has(testId)

package/core/load/LoadSpec.ts

@@ -25,7 +25,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).
  *

package/core/persist/provider/ViewManagerProvider.ts

@@ -9,6 +9,13 @@ import {throwIf} from '@xh/hoist/utils/js';
 import {PersistenceProvider, PersistenceProviderConfig} from '../PersistenceProvider';
 import type {ViewManagerModel} from '@xh/hoist/cmp/viewmanager/ViewManagerModel';
 
+/**
+ * PersistenceProvider that delegates state storage to a ViewManagerModel, enabling components
+ * to persist their state as part of user-managed named views.
+ *
+ * @see ViewManagerModel
+ * @see PersistenceProvider
+ */
 export class ViewManagerProvider<S> extends PersistenceProvider<S> {
     readonly viewManagerModel: ViewManagerModel;