@xh/hoist 83.0.2 → 83.1.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 83.1.0 - 2026-04-07
+
+### 🐞 Bug Fixes
+
+* Fixed `EnvironmentService.ensureVersionRunnable()` to correctly detect client/server version
+  mismatches on startup. The previous check compared two values both sourced from the server
+  response, making it a tautology that could never fail. Now compares the webpack-baked
+  `clientVersion` against the server-reported `appVersion`.
+
+### 🤖 AI Docs + Tooling
+
+* Improved MCP/CLI TypeScript symbol tools to surface full JSDoc documentation in search results
+  and resolve a discoverability gap around component Props interfaces. `hoist-search-symbols`
+  now includes JSDoc snippets with each result. Props interfaces (e.g. `PanelProps`) without
+  their own JSDoc inherit documentation from their companion component via naming convention.
+  `hoist-get-symbol` now cross-references between Props interfaces and their components.
+
 ## 83.0.2 - 2026-03-30
 
 ### ⚙️ Technical

package/build/types/cmp/error/ErrorBoundary.d.ts

@@ -8,5 +8,7 @@ import { ErrorBoundaryModel } from './ErrorBoundaryModel';
  * This wrapper will automatically only catch and handle exceptions that occur during the React
  * lifecycle, but applications that wish to use this component to display other caught exceptions
  * may explicitly use it to handle those exceptions.
+ *
+ * @see ErrorBoundaryModel
  */
 export declare const ErrorBoundary: import("react").FC<import("@xh/hoist/core").DefaultHoistProps<ErrorBoundaryModel>>, errorBoundary: import("@xh/hoist/core").ElementFactory<import("@xh/hoist/core").DefaultHoistProps<ErrorBoundaryModel>>;

package/build/types/cmp/error/ErrorBoundaryModel.d.ts

@@ -12,6 +12,18 @@ export interface ErrorBoundaryConfig {
      */
     errorRenderer?: (e: unknown) => ReactNode;
 }
+/**
+ * Model for an ErrorBoundary component that catches unhandled React lifecycle errors.
+ *
+ * Tracks a caught error and provides {@link handleError} for applications to programmatically
+ * trigger error display for non-lifecycle exceptions. Use {@link showError} to display an
+ * already-handled error without re-running the error handler.
+ *
+ * Configure via `errorHandler` to customize exception handling (defaults to suppressing the
+ * alert dialog) and `errorRenderer` to customize the error display.
+ *
+ * @see ErrorBoundary
+ */
 export declare class ErrorBoundaryModel extends HoistModel {
     errorHandler: ExceptionHandlerOptions | ((e: unknown) => void);
     errorRenderer: (e: unknown) => ReactNode;

package/build/types/cmp/filter/FilterChooserModel.d.ts

@@ -68,6 +68,24 @@ export interface FilterChooserConfig {
     /** Options governing persistence. */
     persistWith?: FilterChooserPersistOptions;
 }
+/**
+ * Model for a Select-based filter control that allows users to search for and compose filters
+ * across multiple data fields.
+ *
+ * Manages the current filter value, user-managed favorites, and available field specs. Supports
+ * bidirectional binding to a {@link Store} or Cube {@link View} via the `bind` config — filters
+ * are automatically applied to the target as they change, and external filter changes on the
+ * target are reflected back into this model.
+ *
+ * Field specs define which fields are available for filtering and how their values are parsed
+ * and displayed. If a `valueSource` is provided, field specs can be auto-populated from the
+ * source's fields.
+ *
+ * Supports persistence of both the current filter value and favorites via `persistWith`.
+ *
+ * @see FilterChooser
+ * @see FilterChooserFieldSpec
+ */
 export declare class FilterChooserModel extends HoistModel {
     value: FilterChooserFilter;
     favorites: FilterChooserFilter[];

package/build/types/cmp/form/Form.d.ts

@@ -33,9 +33,9 @@ export interface FormProps<M extends FormModel = FormModel> extends HoistProps<M
  * primarily designed to apply defaults to and manage data binding for FormField components, which
  * can be nested at any level below this parent component.
  *
- * @see FormModel - top-level model for Hoist form support, which holds a collection of...
- * @see FieldModel - field-level model, which manages field-level specs/data to be rendered by a...
- * @see FormField - field-level wrapper component, which labels and displays info for a...
- * @see HoistInput - superclass for the data entry components themselves.
+ * @see FormModel
+ * @see FieldModel
+ * @see FormField
+ * @see HoistInput
  */
 export declare const Form: import("react").FC<FormProps<FormModel>>, form: import("@xh/hoist/core").ElementFactory<FormProps<FormModel>>;

package/build/types/cmp/form/formfieldset/FormFieldSetModel.d.ts

@@ -14,6 +14,15 @@ export interface FormFieldSetConfig {
     /** Options governing persistence. */
     persistWith?: PersistOptions;
 }
+/**
+ * Model for a FormFieldSet — a collapsible container for grouping related form fields.
+ *
+ * Aggregates validation state from all descendant FieldModels and child FormFieldSetModels,
+ * and supports disabling or setting readonly state on all contained fields at once.
+ *
+ * @see FormFieldSet
+ * @see FormModel
+ */
 export declare class FormFieldSetModel extends CardModel {
     config: FormFieldSetConfig;
     parent: FormFieldSetModel;

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

@@ -66,6 +66,22 @@ export interface GroupingChooserPersistOptions extends PersistOptions {
 }
 /** Target to which GroupingChooser value changes should be automatically synced. */
 export type GroupingBindTarget = GridModel | View;
+/**
+ * Model for a control that allows users to select and order a list of dimensions for use with
+ * grouping APIs, such as Grid `groupBy` or Cube queries.
+ *
+ * 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
+ * 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
+ * to a Cube View, {@link CubeField} instances satisfy the {@link DimensionSpec} interface.
+ *
+ * Supports persistence of both the current value and favorites via `persistWith`.
+ *
+ * @see GroupingChooser
+ */
 export declare class GroupingChooserModel extends HoistModel {
     /** App-level defaults for GroupingChooserModel. Instance config takes precedence. */
     static defaults: GroupingChooserModelDefaults;

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

@@ -5,6 +5,14 @@ export interface PinPadConfig {
     headerText?: string;
     subHeaderText?: string;
 }
+/**
+ * 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.
+ *
+ * @see PinPad
+ */
 export declare class PinPadModel extends HoistModel {
     disabled: boolean;
     headerText: string;

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

@@ -2,16 +2,6 @@ import { HoistModel, PlainObject, Theme } from '@xh/hoist/core';
 import { StoreRecord, StoreRecordId } from '@xh/hoist/data';
 import { ReactNode } from 'react';
 import { TreeMapAlgorithm, TreeMapColorMode, TreeMapModel, TreeMapConfig } from './TreeMapModel';
-/**
- * Core Model for a SplitTreeMap.
- *
- * Binds to a Store (or GridModel) and splits the data into two managed child TreeMaps.
- * Users should specify a `mapFilter` function to control how records are divided
- * across the two TreeMaps.
- *
- * Additionally, accepts and passes along all settings for TreeMapModel.
- * @see TreeMapModel
- */
 export interface SplitTreeMapConfig extends TreeMapConfig {
     /**
      * Filter used to allocate records between the primary and secondary maps.
@@ -25,6 +15,16 @@ export interface SplitTreeMapConfig extends TreeMapConfig {
     /** Layout orientation to use. */
     orientation?: SplitTreeMapOrientation;
 }
+/**
+ * Core Model for a SplitTreeMap.
+ *
+ * Binds to a Store (or GridModel) and splits the data into two managed child TreeMaps.
+ * Users should specify a `mapFilter` function to control how records are divided
+ * across the two TreeMaps.
+ *
+ * Additionally, accepts and passes along all settings for TreeMapModel.
+ * @see TreeMapModel
+ */
 export declare class SplitTreeMapModel extends HoistModel {
     mapFilter: SplitTreeMapFilterFn;
     mapTitleFn: SplitTreeMapTitleFn;

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

@@ -3,26 +3,6 @@ import { Store, StoreRecord, StoreRecordId } from '@xh/hoist/data';
 import { GridModel } from '@xh/hoist/cmp/grid';
 import { FilterLike } from '@xh/hoist/data/filter/Types';
 import { ReactNode } from 'react';
-/**
- * Core Model for a TreeMap.
- *
- * You should specify the TreeMap's data store, in addition to which StoreRecord fields should be
- * mapped to label (a node's display name), value (a node's size), and heat (a node's color).
- *
- * Can also (optionally) be bound to a GridModel. This will enable selection syncing and
- * expand / collapse syncing for GridModels in `treeMode`.
- *
- * Supports any Highcharts TreeMap algorithm ('squarified', 'sliceAndDice', 'stripes' or 'strip').
- *
- * Node colors are normalized to a 0-1 range and mapped to a colorAxis via the following colorModes:
- * 'linear' distributes normalized color values across the colorAxis according to the heatField.
- * 'wash' ignores the intensity of the heat value, applying a single positive and negative color.
- * 'none' will ignore the colorAxis, and instead use the neutral color.
- *
- * Color customization can be managed by setting colorAxis stops via the `highchartsConfig`.
- *
- * @see https://www.highcharts.com/docs/chart-and-series-types/treemap for Highcharts config options
- */
 export interface TreeMapConfig {
     /** A store containing records to be displayed. */
     store?: Store;
@@ -85,6 +65,25 @@ export interface TreeMapModelDefaults {
     algorithm?: TreeMapAlgorithm;
     maxNodes?: number;
 }
+/**
+ * Core Model for a TreeMap, backed by a data Store with fields mapped to each node's label
+ * (display name), value (size), and heat (color).
+ *
+ * Can optionally bind to a GridModel to enable selection and expand/collapse syncing for
+ * GridModels in `treeMode`.
+ *
+ * Supports Highcharts TreeMap algorithms: 'squarified', 'sliceAndDice', 'stripes', and 'strip'.
+ *
+ * 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.
+ *
+ * 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
+ * TreeMap config options.
+ */
 export declare class TreeMapModel extends HoistModel {
     /** App-level defaults for TreeMapModel. Instance config takes precedence. */
     static defaults: TreeMapModelDefaults;

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

@@ -51,34 +51,32 @@ export type ComponentConfig<P extends HoistProps> = ((props: RenderPropsOf<P>, r
     observer?: boolean;
 };
 /**
- * Hoist utility for defining functional components. This is the primary method for creating
- * components for use in Hoist applications. Accepts either a render function (directly) or a
- * configuration object to specify that function and additional options, as described below.
+ * The primary entry point for defining Hoist components — functional React components enhanced
+ * with MobX reactivity and integrated model support.
  *
- * The primary additional config option is `model`. It specifies how a backing HoistModel will be
- * provided to / created by this component and if the component should publish its model to any
- * subcomponents via context.
+ * Accepts a configuration object (or a bare render function) and returns a React functional
+ * component. The `model` config is the key option: use {@link creates} to have the component
+ * create and own its backing model, {@link uses} to source a model from props or context, or
+ * `false` for simple components with no model. Defaults to `uses('*')` if not specified.
  *
- * By default, this utility wraps the returned component in the MobX 'observer' HOC, enabling
- * MobX-powered reactivity and auto-re-rendering of observable properties read from models and
- * any other sources of observable state.
+ * Components are wrapped in the MobX `observer` HOC by default, enabling automatic re-rendering
+ * when observable state read during render changes.
  *
- * Forward refs {@link https://reactjs.org/docs/forwarding-refs.html} are supported by specifying a
- * render function that accepts two arguments. In that case, the second arg will be considered a
- * ref, and this utility will apply `React.forwardRef` as required.
+ * 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
+ * `React.forwardRef` is applied automatically.
  *
- * @param config - specification object, or a render function defining the component.
- * @returns a functional React Component for use within Hoist apps.
- *
- * @see hoistCmp - a shorthand alias to this function.
+ * 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
+ *    library components that need to export both).
  *
- * This function also has several related functions
+ * See `core/README.md` for full documentation on component configuration, model specs, and
+ * context lookup behavior.
  *
- *   - `hoistCmp.factory` - return an elementFactory for a newly defined Component.
- *           instead of the Component itself.
- *
- *   - `hoistCmp.withFactory` - return a 2-element list containing both the newly
- *          defined Component and an elementFactory for it.
+ * @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>(config: ComponentConfig<P>): FC<P>;

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

@@ -1,24 +1,5 @@
 import { PlainObject } from '../types/Types';
 import { LoadSupport } from './';
-/**
- * Object describing a load/refresh request in Hoist.
- *
- * Instances of this class are created within the public APIs provided by {@link LoadSupport}
- * and are passed to subclass (i.e. app-level) implementations of `doLoadAsync()`.
- *
- * Application implementations of `doLoadAsync()` can consult this object's flags. Of particular
- * interest are {@link isStale} and {@link isObsolete}, which implementations can read after any
- * async calls return to determine if a newer, subsequent load has already been requested.
- *
- * In addition, `doLoadAsync()` implementations should typically pass along this object to any
- * calls they make to `loadAsync()` on other objects + all calls to {@link FetchService} APIs.
- *
- * Note that Hoist's exception handling and activity tracking will consult the {@link isAutoRefresh}
- * flag on specs passed to their calls to automatically adjust their behavior (e.g. not showing an
- * exception dialog on error, not tracking background refresh activity).
- *
- * @see LoadSupport
- */
 export type LoadSpecConfig = {
     /** True if triggered by a refresh request (automatic or user-driven). */
     isRefresh?: boolean;
@@ -27,6 +8,25 @@ export type LoadSpecConfig = {
     /** Application-specific information about the load request. */
     meta?: PlainObject;
 };
+/**
+ * Immutable descriptor for a load/refresh request, passed to `doLoadAsync()` implementations.
+ *
+ * Instances are created automatically by {@link LoadSupport} when `loadAsync()`,
+ * `refreshAsync()`, or `autoRefreshAsync()` are called. Application code should not construct
+ * 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.
+ * Check {@link isAutoRefresh} to adjust behavior for background refreshes (e.g. skip expensive
+ * operations, avoid user-facing error dialogs).
+ *
+ * Pass this object along to any nested `loadAsync()` calls and to all {@link FetchService}
+ * requests. Hoist's exception handling and activity tracking consult the LoadSpec to
+ * automatically suppress error dialogs and skip tracking for auto-refresh operations.
+ *
+ * @see LoadSupport
+ * @see HoistModel.doLoadAsync
+ */
 export declare class LoadSpec {
     /** True if triggered by a refresh request (automatic or user-driven). */
     isRefresh: boolean;

package/build/types/data/impl/RecordSet.d.ts

@@ -1,14 +1,14 @@
 import { StoreRecord, StoreRecordId } from '../StoreRecord';
 import { Store } from '../Store';
 import { Filter } from '../filter/Filter';
+type StoreRecordMap = Map<StoreRecordId, StoreRecord>;
+type ChildRecordMap = Map<StoreRecordId, StoreRecord[]>;
 /**
  * Internal container for StoreRecord management within a Store.
  * Note this is an immutable object; its update and filtering APIs return new instances as required.
  *
  * @internal
  */
-type StoreRecordMap = Map<StoreRecordId, StoreRecord>;
-type ChildRecordMap = Map<StoreRecordId, StoreRecord[]>;
 export declare class RecordSet {
     store: Store;
     recordMap: StoreRecordMap;

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

@@ -103,7 +103,7 @@ export interface DateInputProps extends HoistProps, LayoutProps, HoistInputProps
     /**
      * Type of value to publish. Defaults to 'date'. The use of 'localDate' is often a good
      * choice for use cases where there is no time component.
-     * @see LocalDate - the class that will be published when localDate mode.
+     * @see LocalDate
      */
     valueType?: 'date' | 'localDate';
 }

package/build/types/desktop/cmp/leftrightchooser/LeftRightChooserModel.d.ts

@@ -67,7 +67,7 @@ export declare class LeftRightChooserModel extends HoistModel {
      * Note that this will *not* affect the actual 'value' property, which will continue
      * to include unfiltered records.
      *
-     * @see LeftRightChooserFilter - a component to easily control this field.
+     * @see LeftRightChooserFilter
      * @param fn - predicate function for filtering.
      */
     setDisplayFilter(fn: FilterTestFn): void;

package/build/types/svc/AutoRefreshService.d.ts

@@ -14,7 +14,7 @@ import { HoistService } from '@xh/hoist/core';
  *     to customize via the global options dialog, or set a default pref value if per-user
  *     customization is not desirable.
  *
- * @see RefreshContextModel - the underlying mechanism used to implement the refresh.
+ * @see RefreshContextModel
  */
 export declare class AutoRefreshService extends HoistService {
     xhImpl: boolean;

package/build/types/svc/ChangelogService.d.ts

@@ -14,9 +14,8 @@ import { HoistService } from '@xh/hoist/core';
  *
  * Several additional options can be controlled via soft-config - see below.
  *
- * @see XH.showChangelog - public API for displaying the changelog, if enabled and populated.
- * @see whatsNewButton - utility button that conditionally renders when an unread entry exists for
- *      the currently deployed app version. Installed by default in desktop appBar.
+ * @see XH.showChangelog
+ * @see whatsNewButton
  */
 export declare class ChangelogService extends HoistService {
     xhImpl: boolean;

package/build/types/svc/FetchService.d.ts

@@ -4,31 +4,33 @@ import { Span } from '@xh/hoist/utils/telemetry';
 import { PromiseTimeoutSpec } from '@xh/hoist/promise';
 import { StatusCodes } from 'http-status-codes';
 import { IStringifyOptions } from 'qs';
+export interface FetchServiceDefaults {
+    autoGenCorrelationIds?: boolean | ((opts: FetchOptions) => boolean);
+    correlationIdHeaderKey?: string;
+    genCorrelationId?: () => string;
+}
 /**
  * Service for making managed HTTP requests, both to the app's own Hoist server and to remote APIs.
  *
- * Wrapper around the standard Fetch API with some enhancements to streamline the process for
- * the most common use-cases. The Fetch API will be called with CORS enabled, credentials
- * included, and redirects followed.
+ * Typically accessed via `XH.fetchService` or the convenience methods on XH — `XH.fetch()`,
+ * `XH.fetchJson()`, `XH.postJson()`, `XH.putJson()`, `XH.deleteJson()` — which delegate here.
  *
- * Set {@link FetchService.defaults.autoGenCorrelationIds} to enable auto-generation of Correlation IDs
- * for requests issued by this service. Best configured in the app's `Bootstrap` module to ensure
- * coverage of early hoist core init requests. Can also be set on a per-request basis via
- * {@link FetchOptions.correlationId}.
+ * Wraps the standard Fetch API with CORS enabled, credentials included, and redirects followed.
+ * Provides JSON convenience methods (`fetchJson`, `postJson`, `putJson`, `patchJson`,
+ * `deleteJson`, `getJson`) that handle serialization and content-type headers automatically.
  *
- * Custom headers can be set on a request via {@link FetchOptions.headers}. Default headers for all
- * requests can be set / customized using {@link addDefaultHeaders}.
+ * Key features:
+ * - Configurable timeouts (default 30s) via {@link FetchOptions.timeout}
+ * - Auto-abort of duplicate in-flight requests via {@link FetchOptions.autoAbortKey}
+ * - Optional correlation IDs for request tracking (see `defaults.autoGenCorrelationIds`)
+ * - Request/response interceptors via {@link addInterceptor}
+ * - Default headers for all requests via {@link addDefaultHeaders}
+ * - Rich exception handling with HTTP status, server messages, and trace IDs
  *
- * Also see the {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API Docs}.
+ * All convenience methods accept the same {@link FetchOptions} as the main `fetch()` entry point.
  *
- * Note that the convenience methods `fetchJson`, `postJson`, `putJson` all accept the same options
- * as the main entry point `fetch`, as they delegate to fetch after setting additional defaults.
+ * @see FetchOptions
  */
-export interface FetchServiceDefaults {
-    autoGenCorrelationIds?: boolean | ((opts: FetchOptions) => boolean);
-    correlationIdHeaderKey?: string;
-    genCorrelationId?: () => string;
-}
 export declare class FetchService extends HoistService {
     static instance: FetchService;
     /** App-level defaults for FetchService. Instance options take precedence. */

package/cmp/error/ErrorBoundary.ts

@@ -18,6 +18,8 @@ import {ErrorBoundaryModel} from './ErrorBoundaryModel';
  * This wrapper will automatically only catch and handle exceptions that occur during the React
  * lifecycle, but applications that wish to use this component to display other caught exceptions
  * may explicitly use it to handle those exceptions.
+ *
+ * @see ErrorBoundaryModel
  */
 export const [ErrorBoundary, errorBoundary] = hoistCmp.withFactory<ErrorBoundaryModel>({
     displayName: 'ErrorBoundary',

package/cmp/error/ErrorBoundaryModel.ts

@@ -23,6 +23,18 @@ export interface ErrorBoundaryConfig {
     errorRenderer?: (e: unknown) => ReactNode;
 }
 
+/**
+ * Model for an ErrorBoundary component that catches unhandled React lifecycle errors.
+ *
+ * Tracks a caught error and provides {@link handleError} for applications to programmatically
+ * trigger error display for non-lifecycle exceptions. Use {@link showError} to display an
+ * already-handled error without re-running the error handler.
+ *
+ * Configure via `errorHandler` to customize exception handling (defaults to suppressing the
+ * alert dialog) and `errorRenderer` to customize the error display.
+ *
+ * @see ErrorBoundary
+ */
 export class ErrorBoundaryModel extends HoistModel {
     errorHandler: ExceptionHandlerOptions | ((e: unknown) => void);
     errorRenderer: (e: unknown) => ReactNode;

package/cmp/filter/FilterChooserModel.ts

@@ -131,6 +131,24 @@ export interface FilterChooserConfig {
     persistWith?: FilterChooserPersistOptions;
 }
 
+/**
+ * Model for a Select-based filter control that allows users to search for and compose filters
+ * across multiple data fields.
+ *
+ * Manages the current filter value, user-managed favorites, and available field specs. Supports
+ * bidirectional binding to a {@link Store} or Cube {@link View} via the `bind` config — filters
+ * are automatically applied to the target as they change, and external filter changes on the
+ * target are reflected back into this model.
+ *
+ * Field specs define which fields are available for filtering and how their values are parsed
+ * and displayed. If a `valueSource` is provided, field specs can be auto-populated from the
+ * source's fields.
+ *
+ * Supports persistence of both the current filter value and favorites via `persistWith`.
+ *
+ * @see FilterChooser
+ * @see FilterChooserFieldSpec
+ */
 export class FilterChooserModel extends HoistModel {
     @observable.ref value: FilterChooserFilter = null;
     @observable.ref favorites: FilterChooserFilter[] = [];

package/cmp/form/Form.ts

@@ -57,10 +57,10 @@ export interface FormProps<M extends FormModel = FormModel>
  * primarily designed to apply defaults to and manage data binding for FormField components, which
  * can be nested at any level below this parent component.
  *
- * @see FormModel - top-level model for Hoist form support, which holds a collection of...
- * @see FieldModel - field-level model, which manages field-level specs/data to be rendered by a...
- * @see FormField - field-level wrapper component, which labels and displays info for a...
- * @see HoistInput - superclass for the data entry components themselves.
+ * @see FormModel
+ * @see FieldModel
+ * @see FormField
+ * @see HoistInput
  */
 export const [Form, form] = hoistCmp.withFactory<FormProps>({
     displayName: 'Form',

package/cmp/form/formfieldset/FormFieldSetModel.ts

@@ -30,6 +30,15 @@ export interface FormFieldSetConfig {
     persistWith?: PersistOptions;
 }
 
+/**
+ * Model for a FormFieldSet — a collapsible container for grouping related form fields.
+ *
+ * Aggregates validation state from all descendant FieldModels and child FormFieldSetModels,
+ * and supports disabling or setting readonly state on all contained fields at once.
+ *
+ * @see FormFieldSet
+ * @see FormModel
+ */
 export class FormFieldSetModel extends CardModel {
     declare config: FormFieldSetConfig;
 

package/cmp/grouping/GroupingChooserModel.ts

@@ -92,6 +92,22 @@ export interface GroupingChooserPersistOptions extends PersistOptions {
 /** Target to which GroupingChooser value changes should be automatically synced. */
 export type GroupingBindTarget = GridModel | View;
 
+/**
+ * Model for a control that allows users to select and order a list of dimensions for use with
+ * grouping APIs, such as Grid `groupBy` or Cube queries.
+ *
+ * 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
+ * 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
+ * to a Cube View, {@link CubeField} instances satisfy the {@link DimensionSpec} interface.
+ *
+ * Supports persistence of both the current value and favorites via `persistWith`.
+ *
+ * @see GroupingChooser
+ */
 export class GroupingChooserModel extends HoistModel {
     /** App-level defaults for GroupingChooserModel. Instance config takes precedence. */
     static defaults: GroupingChooserModelDefaults = {

package/cmp/pinpad/PinPadModel.ts

@@ -21,6 +21,14 @@ export interface PinPadConfig {
     subHeaderText?: string;
 }
 
+/**
+ * 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.
+ *
+ * @see PinPad
+ */
 export class PinPadModel extends HoistModel {
     @bindable disabled: boolean;
     @bindable headerText: string;

package/cmp/treemap/SplitTreeMapModel.ts

@@ -13,16 +13,6 @@ import {uniq} from 'lodash';
 
 import {TreeMapAlgorithm, TreeMapColorMode, TreeMapModel, TreeMapConfig} from './TreeMapModel';
 
-/**
- * Core Model for a SplitTreeMap.
- *
- * Binds to a Store (or GridModel) and splits the data into two managed child TreeMaps.
- * Users should specify a `mapFilter` function to control how records are divided
- * across the two TreeMaps.
- *
- * Additionally, accepts and passes along all settings for TreeMapModel.
- * @see TreeMapModel
- */
 export interface SplitTreeMapConfig extends TreeMapConfig {
     /**
      * Filter used to allocate records between the primary and secondary maps.
@@ -40,6 +30,16 @@ export interface SplitTreeMapConfig extends TreeMapConfig {
     orientation?: SplitTreeMapOrientation;
 }
 
+/**
+ * Core Model for a SplitTreeMap.
+ *
+ * Binds to a Store (or GridModel) and splits the data into two managed child TreeMaps.
+ * Users should specify a `mapFilter` function to control how records are divided
+ * across the two TreeMaps.
+ *
+ * Additionally, accepts and passes along all settings for TreeMapModel.
+ * @see TreeMapModel
+ */
 export class SplitTreeMapModel extends HoistModel {
     //------------------------
     // Immutable public properties