@xh/hoist 83.1.0 → 84.0.1

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 84.0.1 - 2026-04-20
+
+### 🐞 Bug Fixes
+
+* Fixed an unrecoverable crash when calling `XH.prompt()` (and any other `FormField` rendered
+  without an explicit `model` prop). `InstanceManager.registerModelWithTestId()` dereferenced a
+  null model when a `testId` was supplied, introduced by the v84 expansion of `testId` coverage on
+  built-in appcontainer components.
+
+## 84.0.0 - 2026-04-15
+
+### 💥 Breaking Changes (upgrade difficulty: 🟢 LOW)
+
+See [`docs/upgrade-notes/v84-upgrade-notes.md`](docs/upgrade-notes/v84-upgrade-notes.md) for
+detailed, step-by-step upgrade instructions with before/after code examples.
+
+* Requires `hoist-core >= 38.0`.
+* Removed the `getClassName()` utility from `@xh/hoist/utils/react`. This function had no
+  remaining usages in the framework — the `className` spec field on `hoistCmp.factory()` /
+  `hoistCmp.withFactory()` handles base class merging automatically.
+
+### 🎁 New Features
+
+* Updated FontAwesome to v7, bringing subtle visual tweaks and performance optimizations to Hoist's
+  icon library. All previously supported icons remain and no app changes should be required.
+* Replaced animated PNG `Spinner` with a FontAwesome icon-based spinner, making it scalable,
+  themeable, and consistent with the rest of the icon system. The icon and weight can be
+  configured globally via `Spinner.defaults` or per-instance via props. A `usePng` flag is
+  available to preserve the original PNG appearance if desired.
+* Added client-side span sampling to `TraceService`. Evaluates `xhTraceConfig.sampleRules` at span
+  creation, with child spans inheriting their parent's decision. Error spans are always exported
+  when `alwaysSampleErrors` is enabled. The `traceparent` header now propagates the sampling flag to
+  the server.
+* `FetchOptions.span` now accepts a `string` or `SpanConfig` in addition to an existing `Span`.
+  When a string or config is provided, `FetchService` creates and manages the parent span
+  internally, simplifying a common tracing pattern for fetch calls.
+
+### 🤖 AI Docs + Tooling
+
+* Added JSDoc to ~60 exported Config/Spec interfaces and improved class-level docs on key
+  framework classes. Added README cross-references, when-to-use guidance, and `@see` navigation
+  links throughout.
+* Split Cube documentation into dedicated `data/cube/README.md` with expanded query patterns
+  covering grand totals, leaf drill-down, dynamic updates, and `executeQuery()`.
+* Enhanced MCP/CLI symbol search to match JSDoc content with multi-word AND queries (e.g.
+  `"panel modal"` finds `ModalSupportModel`). Added disambiguation hints for duplicate symbol
+  names and fixed resolution of symbols shadowed by dynamics stubs.
+
+### ⚙️ Technical
+
+* Added support for a typed `defaults` object on `hoistCmp` components — static config that apps
+  can override at bootstrap (e.g. `Button.defaults.minimal = false`). Instance props take
+  precedence. Added initial defaults to `Button`, `Panel`, `Spinner`, and `Toolbar`.
+* Added `suppressStackTrace` and `includeStartMessages` fields to the Log Levels admin panel,
+  supporting the new hoist-core per-logger logging behavior overrides.
+* Added `assets.d.ts` type declarations for image and markdown imports (`*.png`, `*.gif`, `*.jpg`,
+  `*.svg`, `*.md`), removing the need for `@ts-ignore` on asset imports.
+* Added hardcoded `xh-` prefixed `testId` props to all desktop and mobile appcontainer components
+  for Playwright testing support.
+* Namespaced auto-installed `TraceService` span and metric tags with an `xh.` prefix, aligning
+  with OTEL semantic conventions.
+
+### ✨ Styles
+
+* Improved default grid tooltip styling — long strings now wrap at a configurable max-width
+  (`400px` default) using `pre-wrap`. New `--xh-grid-tooltip-*` CSS variables added for
+  app-level customization of background, border, border-radius, padding, and max-width.
+
+### 📚 Libraries
+
+* @auth0/auth0-spa-js `2.17 → 2.19`
+* @fortawesome/* `6.0 → 7.2`
+* @fortawesome/react-fontawesome `0.2 → 3.2`
+* dompurify `3.3 → 3.4`
+* lodash `4.17 → 4.18`
+
 ## 83.1.0 - 2026-04-07
 
 ### 🐞 Bug Fixes

package/admin/tabs/cluster/instances/logs/levels/LogLevelDialogModel.ts

@@ -8,10 +8,13 @@ import {exportFilenameWithDate} from '@xh/hoist/admin/AdminUtils';
 import {AppModel} from '@xh/hoist/admin/AppModel';
 import * as Col from '@xh/hoist/admin/columns/Rest';
 import {LogViewerModel} from '@xh/hoist/admin/tabs/cluster/instances/logs/LogViewerModel';
+import {ColumnSpec} from '@xh/hoist/cmp/grid';
 import {HoistModel, managed, lookup, LoadSpec} from '@xh/hoist/core';
 import {FieldSpec} from '@xh/hoist/data';
-import {textInput} from '@xh/hoist/desktop/cmp/input';
+import {segmentedControl, textInput} from '@xh/hoist/desktop/cmp/input';
 import {RestGridModel} from '@xh/hoist/desktop/cmp/rest';
+import {Icon} from '@xh/hoist/icon';
+import {isNil} from 'lodash';
 
 /**
  * @internal
@@ -59,12 +62,44 @@ export class LogLevelDialogModel extends HoistModel {
                         displayName: 'Package/Class',
                         required: true
                     },
-                    {name: 'level', type: 'string', displayName: 'Override', lookupName: 'levels'},
-                    {name: 'defaultLevel', type: 'string', displayName: 'Initial', editable: false},
+                    {
+                        name: 'level',
+                        type: 'string',
+                        displayName: 'Level Override',
+                        lookupName: 'levels'
+                    },
+                    {
+                        name: 'suppressStackTrace',
+                        type: 'bool',
+                        displayName: 'Suppress Stack'
+                    },
+                    {
+                        name: 'includeStartMessages',
+                        type: 'bool',
+                        displayName: 'Start Msgs'
+                    },
+                    {
+                        name: 'defaultLevel',
+                        type: 'string',
+                        displayName: 'Log Level',
+                        editable: false
+                    },
                     {
                         name: 'effectiveLevel',
                         type: 'string',
-                        displayName: 'Effective',
+                        displayName: 'Log Level (effective)',
+                        editable: false
+                    },
+                    {
+                        name: 'effectiveSuppressStackTrace',
+                        type: 'bool',
+                        displayName: 'Suppress Stack (effective)',
+                        editable: false
+                    },
+                    {
+                        name: 'effectiveIncludeStartMessages',
+                        type: 'bool',
+                        displayName: 'Start Msgs (effective)',
                         editable: false
                     },
                     {...(Col.lastUpdated.field as FieldSpec), editable: false},
@@ -75,9 +110,45 @@ export class LogLevelDialogModel extends HoistModel {
             filterFields: ['name'],
             columns: [
                 {field: 'name', width: 400},
-                {field: 'defaultLevel', width: 110},
-                {field: 'level', width: 110},
-                {field: 'effectiveLevel', width: 110},
+                {
+                    groupId: 'initial',
+                    headerName: 'Initial',
+                    headerAlign: 'center',
+                    children: [{field: 'defaultLevel', width: 110}]
+                },
+                {
+                    groupId: 'override',
+                    headerName: 'Override',
+                    headerAlign: 'center',
+                    children: [
+                        {
+                            field: 'level',
+                            headerName: 'Log Level',
+                            width: 110,
+                            renderer: v => (isNil(v) ? '-' : v)
+                        },
+                        {...customBoolCheckCol, field: 'suppressStackTrace'},
+                        {...customBoolCheckCol, field: 'includeStartMessages'}
+                    ]
+                },
+                {
+                    groupId: 'effective',
+                    headerName: 'Effective',
+                    headerAlign: 'center',
+                    children: [
+                        {field: 'effectiveLevel', headerName: 'Log Level', width: 110},
+                        {
+                            ...customBoolCheckCol,
+                            field: 'effectiveSuppressStackTrace',
+                            headerName: 'Suppress Stack'
+                        },
+                        {
+                            ...customBoolCheckCol,
+                            field: 'effectiveIncludeStartMessages',
+                            headerName: 'Start Msgs'
+                        }
+                    ]
+                },
                 Col.lastUpdated,
                 Col.lastUpdatedBy
             ],
@@ -87,13 +158,21 @@ export class LogLevelDialogModel extends HoistModel {
                     formField: {
                         item: textInput({
                             placeholder: 'com.myapp.MyClassWithLogging (or partial path)'
-                        })
+                        }),
+                        info: 'Hint - leave in place with no overrides set below to easily adjust again later.'
                     }
                 },
+                {field: 'level'},
                 {
-                    field: 'level',
+                    field: 'suppressStackTrace',
                     formField: {
-                        info: 'Hint - clear to leave at default while keeping record in place to adjust again later.'
+                        item: segmentedControl({options: customBoolSegmentOptions})
+                    }
+                },
+                {
+                    field: 'includeStartMessages',
+                    formField: {
+                        item: segmentedControl({options: customBoolSegmentOptions})
                     }
                 },
                 {field: 'lastUpdated'},
@@ -102,3 +181,20 @@ export class LogLevelDialogModel extends HoistModel {
         });
     }
 }
+
+const customBoolSegmentOptions = [
+    {label: 'Inherit', value: null},
+    {label: 'On', value: true},
+    {label: 'Off', value: false}
+];
+
+const customBoolCheckCol: ColumnSpec = {
+    align: 'center',
+    width: 120,
+    renderer: v =>
+        isNil(v)
+            ? '-'
+            : v
+              ? Icon.check({prefix: 'fas', intent: 'success'})
+              : Icon.cross({prefix: 'fas', intent: 'warning'})
+};

package/admin/tabs/cluster/metrics/MetricsModel.ts

@@ -176,8 +176,8 @@ export class MetricsModel extends BaseAdminTabModel {
             if (loadSpec.isStale) return;
 
             const enriched = data.map(it => {
-                const instance = it.tags.find(t => t.key === 'instance')?.value,
-                    source = it.tags.find(t => t.key === 'source')?.value,
+                const instance = it.tags.find(t => t.key === 'xh.instance')?.value,
+                    source = it.tags.find(t => t.key === 'xh.source')?.value,
                     tags = sortTags(it.tags).map(t => `${t.key}: ${t.value}`);
                 return {...it, instance, source, tags};
             });
@@ -282,7 +282,7 @@ export class MetricsModel extends BaseAdminTabModel {
     }
 }
 
-const PRIORITY_KEYS = ['application', 'source', 'instance'];
+const PRIORITY_KEYS = ['xh.application', 'xh.source', 'xh.instance'];
 
 function sortTags(tags: {key: string; value: string}[]) {
     return [...tags].sort((a, b) => {

package/appcontainer/AppContainerModel.ts

@@ -360,7 +360,7 @@ export class AppContainerModel extends HoistModel {
         let startTime = loadStarted;
 
         const emit = (name: string, duration: number, parent?: Span): Span => {
-            const span = svc.createSpan({name, parent, startTime, tags: {source: 'hoist'}});
+            const span = svc.createSpan({name, parent, startTime, tags: {'xh.source': 'hoist'}});
             if (span) {
                 span.endTime = startTime + duration;
                 span.status = 'ok';

package/appcontainer/README.md

@@ -1,5 +1,25 @@
 # AppContainer Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | App shell purpose and AppContainerModel coordination |
+| [Architecture](#architecture) | Directory structure and sub-model ownership |
+| [Messages](#messages) | Modal dialogs: alert, confirm, prompt, and message API |
+| [Toasts](#toasts) | Non-modal notifications with auto-dismiss and actions |
+| [Banners](#banners) | Persistent app-wide messages across the viewport |
+| [Exception Handling](#exception-handling) | Centralized error logging, reporting, and display |
+| [App Options Dialog](#app-options-dialog) | User-configurable preferences UI |
+| [Theme](#theme) | Light, dark, and system-matching theme management |
+| [Sizing Mode](#sizing-mode) | UI density control: compact, standard, large |
+| [Viewport & Device Detection](#viewport--device-detection) | Browser dimensions, orientation, and device classification |
+| [About Dialog & Changelog](#about-dialog--changelog) | App info display and release notes |
+| [Feedback Dialog](#feedback-dialog) | User feedback collection via TrackService |
+| [Impersonation](#impersonation) | Admin impersonation bar for debugging and support |
+| [Routing](#routing) | Client-side routing via Router5 with observable state |
+| [Login Panel](#login-panel) | Username/password authentication for non-SSO apps |
+| [Version Bar](#version-bar) | Desktop footer with app info and quick-access icons |
+| [Related Packages](#related-packages) | Links to related hoist-react packages and docs |
+
 ## Overview
 
 The `/appcontainer/` package is the framework's application shell — it orchestrates the app

package/assets.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ambient type declarations for non-code asset imports (images, markdown).
+ *
+ * These allow TypeScript to understand `import img from './foo.png'` without @ts-ignore.
+ * Webpack's asset loaders resolve these imports to string URLs at build time.
+ *
+ * Note: as ambient declarations, these are visible to downstream apps that resolve into
+ * hoist-react's source directory via path mapping. This is intentional — all Hoist apps
+ * share the same Webpack build tooling and loader configuration.
+ */
+declare module '*.png' {
+    const src: string;
+    export default src;
+}
+
+declare module '*.gif' {
+    const src: string;
+    export default src;
+}
+
+declare module '*.jpg' {
+    const src: string;
+    export default src;
+}
+
+declare module '*.svg' {
+    const src: string;
+    export default src;
+}
+
+declare module '*.md' {
+    const content: string;
+    export default content;
+}

package/build/types/cmp/ag-grid/AgGrid.d.ts

@@ -5,26 +5,15 @@ import { AgGridModel } from './AgGridModel';
 export interface AgGridProps extends HoistProps<AgGridModel>, GridOptions, LayoutProps, TestSupportProps {
 }
 /**
- * Minimal wrapper for AgGridReact, supporting direct use of the ag-Grid component with limited
- * enhancements for consistent Hoist themes/styling, layout support, and a
- * backing model for convenient access to the ag-Grid APIs and other utility methods.
+ * Low-level escape hatch for direct use of ag-Grid - most applications should use the standard
+ * Hoist {@link Grid} component and {@link GridModel} instead.
  *
- * All ag-Grid Grid Properties can be passed as props directly to this component.
- * See {@link https://www.ag-grid.com/javascript-grid-properties/}.  Pass an {@link AgGridModel}
- * via the `model` prop to control additional Hoist customizations.
+ * This minimal wrapper around AgGridReact provides Hoist theming/styling, layout support, and
+ * an {@link AgGridModel} for access to the ag-Grid APIs. All ag-Grid Grid Properties can be
+ * passed as props directly. It is intended for advanced use cases that require ag-Grid features
+ * not yet exposed by the managed Hoist Grid layer (most notably pivoting).
  *
- * This component complements and contrasts with the primary Hoist `Grid` class, which provides a
- * significantly more managed and opinionated use of ag-Grid and a number of Hoist-specific
- * extensions and customizations. That fully managed component is expected to cover the majority of
- * use cases within Hoist apps and is recommended as the primary grid class within the toolkit.
- *
- * This wrapper is provided for advanced usages of grid that wish to leverage features of the
- * underlying component not yet supported by the Hoist layer - most notably pivoting - where the
- * managed option would conflict with or complicate access to those features.
- *
- * Note that this component uses the ag-Grid `getRowHeight` prop to provide the grid with row
- * heights.  As of 4/2023, this may cause scrolling to be slow in large data sets, and
- * applications may wish to set this prop to `null` and use either a fixed `rowWidth` property, or
- * an explicit per-row setting instead. See GridModel for a more efficient, data aware approach.
+ * @see Grid
+ * @see GridModel
  */
 export declare const AgGrid: any, agGrid: import("@xh/hoist/core").ElementFactory<AgGridProps>;

package/build/types/cmp/ag-grid/AgGridModel.d.ts

@@ -1,6 +1,16 @@
 import { HoistModel, PlainObject, SizingMode, Some } from '@xh/hoist/core';
 import type { GridApi, IRowNode, SortDirection } from '@xh/hoist/kit/ag-grid';
 import { GridSorterLike } from '../grid/GridSorter';
+/**
+ * Configuration for an {@link AgGridModel} - the low-level model backing the Hoist `AgGrid`
+ * component. This interface is only relevant when using `AgGrid` directly for advanced or
+ * minimally-managed ag-Grid use cases. Most applications should use {@link GridConfig} and
+ * the standard {@link GridModel} instead, which extends this with columns, store binding,
+ * selection, filtering, and other managed features.
+ *
+ * @see AgGridModel
+ * @see GridConfig
+ */
 export interface AgGridModelConfig {
     sizingMode?: SizingMode;
     /** True to highlight the currently hovered row. */
@@ -44,12 +54,15 @@ export interface AgGridState {
     errors?: Record<string, string>;
 }
 /**
- * Model for an AgGrid, provides reactive support for setting grid styling as well as access to the
- * ag-Grid API and Column API references for interacting with ag-Grid.
+ * Low-level model backing the {@link AgGrid} escape-hatch component - most applications should
+ * use {@link GridModel} instead, which extends this class with columns, store binding,
+ * selection, filtering, and other managed features.
+ *
+ * Provides reactive grid styling properties, access to the ag-Grid API, and utility methods
+ * for getting/setting serializable grid state.
  *
- * Also provides a series of utility methods that are generally useful when managing grid state.
- * This includes the ability to get and set the full state of the grid in a serializable form,
- * allowing applications to save "views" of the grid.
+ * @see AgGridModelConfig
+ * @see GridModel
  */
 export declare class AgGridModel extends HoistModel {
     static AUTO_GROUP_COL_ID: string;

package/build/types/cmp/card/Card.d.ts

@@ -15,9 +15,14 @@ export interface CardProps<M extends CardModel = CardModel> extends HoistProps<M
     contentBoxProps?: BoxProps;
 }
 /**
- * A bordered container for grouping related content with optional inline header and collapsibility.
- * Children are arranged vertically in a flexbox container by default. contentBoxProps can be
- * passed to control the flex direction and other layout aspects of the content container.
- * This component leverages an HTML fieldset and legend to provide base styling.
+ * A bordered container for grouping related content, rendered as an HTML fieldset/legend.
+ * Supports an optional inline header (`title`, `icon`, `intent`) and user-driven
+ * collapse/expand via its backing {@link CardModel}.
+ *
+ * Children are arranged vertically in a flexbox container by default - pass
+ * `contentBoxProps` to customize the content layout.
+ *
+ * @see CardModel
+ * @see FormFieldSet
  */
 export declare const Card: import("react").FC<CardProps<CardModel>>, card: import("@xh/hoist/core").ElementFactory<CardProps<CardModel>>;

package/build/types/cmp/card/CardModel.d.ts

@@ -1,4 +1,11 @@
 import { HoistModel, Persistable, PersistableState, PersistOptions, RenderMode } from '@xh/hoist/core';
+/**
+ * Configuration for a {@link CardModel}. A CardModel is created automatically by {@link Card}
+ * when not provided explicitly - pass a config via the Card's `model` prop to customize.
+ *
+ * @see CardModel
+ * @see Card
+ */
 export interface CardModelConfig {
     /** Can card be collapsed? */
     collapsible?: boolean;
@@ -13,8 +20,14 @@ export interface CardPersistState {
     collapsed?: boolean;
 }
 /**
- * CardModel supports configuration and state-management for user-driven expand/collapse,
- * along with support for saving this state via a configured PersistenceProvider.
+ * Model for a {@link Card} - manages collapsible state and render mode for the Card's content.
+ * Created automatically by Card when not provided - pass via the Card's `model` prop to
+ * customize collapsibility, default state, or persistence.
+ *
+ * Also serves as the base class for {@link FormFieldSetModel}.
+ *
+ * @see CardModelConfig
+ * @see Card
  */
 export declare class CardModel extends HoistModel implements Persistable<CardPersistState> {
     config: CardModelConfig;

package/build/types/cmp/chart/Chart.d.ts

@@ -11,7 +11,7 @@ export interface ChartProps<M extends ChartModel = ChartModel> extends HoistProp
 }
 /**
  * Wrapper Component for a Highcharts chart. Provides basic rendering / lifecycle management
- * as well as configuration and theme defaults. The chart's core configuration should be sourced
- * from a ChartModel prop passed to this component.
+ * as well as configuration and theme defaults. Sourced from a {@link ChartModel}, either
+ * passed directly via the `model` prop or resolved from context.
  */
 export declare const Chart: import("react").FC<ChartProps<ChartModel>>, chart: import("@xh/hoist/core").ElementFactory<ChartProps<ChartModel>>;

package/build/types/cmp/chart/ChartModel.d.ts

@@ -16,7 +16,17 @@ export interface ChartModelDefaults {
     contextMenu?: ChartMenuToken[];
 }
 /**
- * Model to hold and maintain the configuration and data series for a Highcharts chart.
+ * Model for a Highcharts-based {@link Chart} component. Holds the Highcharts configuration
+ * object and data series, providing observable state that drives chart rendering.
+ *
+ * Set `highchartsConfig` for chart-level options (chart type, axes, legend, etc.) and
+ * `series` for the data to display. Both are observable and can be updated at any time
+ * via their setters to trigger a re-render.
+ *
+ * The underlying Highcharts instance is available via the `highchart` property for
+ * read-only access - mutations should go through `setHighchartsConfig` or `setSeries`.
+ *
+ * @see Chart
  */
 export declare class ChartModel extends HoistModel {
     /** App-level defaults for ChartModel. Instance config takes precedence. */

package/build/types/cmp/dataview/DataView.d.ts

@@ -15,7 +15,9 @@ export interface DataViewProps<M extends DataViewModel = DataViewModel> extends
     agOptions?: GridOptions;
 }
 /**
- * A DataView is a specialized version of the Grid component. It displays its data within a
- * single column, using a configured component for rendering each item.
+ * A DataView is a specialized version of the {@link Grid} component. It displays its data within
+ * a single column, using a configured component for rendering each item.
+ *
+ * @see DataViewModel
  */
 export declare const DataView: import("react").FC<DataViewProps<DataViewModel>>, dataView: import("@xh/hoist/core").ElementFactory<DataViewProps<DataViewModel>>;

package/build/types/cmp/dataview/DataViewModel.d.ts

@@ -4,7 +4,10 @@ import { HoistModel, LoadSpec, PlainObject, Some } from '@xh/hoist/core';
 import { Store, StoreConfig, StoreRecord, StoreRecordOrId, StoreSelectionConfig, StoreSelectionModel, StoreTransaction } from '@xh/hoist/data';
 import { ReactNode } from 'react';
 /**
- * Configuration for a DataView.
+ * Configuration for a {@link DataViewModel} - a list-style data component that renders
+ * each record using a custom `renderer` function. Built on {@link GridModel} internally.
+ *
+ * @see DataViewModel
  */
 export interface DataViewConfig {
     /** A Store instance, or a config to create one. */
@@ -80,10 +83,19 @@ export type ItemHeightFn = (params: {
     agParams: RowHeightParams;
 }) => number;
 /**
- * DataViewModel is a wrapper around GridModel, which shows sorted data in a single column,
- * using a configured component for rendering each item.
+ * Model for a {@link DataView} - a list-style data component that renders each record
+ * using a custom `renderer` function. Built on {@link GridModel} internally.
+ *
+ * Use DataView when you need full control over how each row is rendered as a single
+ * custom element (e.g. a card or summary tile), as opposed to the column-based layout
+ * of a standard Grid. For a middle ground with multi-zone row layouts, see
+ * {@link ZoneGridModel}.
+ *
+ * Key configs: `renderer` (required - produces the visual for each row), `itemHeight`,
+ * `groupBy`, and standard store/selection options inherited from GridModel.
  *
- * This is the primary app entry-point for specifying DataView component options and behavior.
+ * @see DataView
+ * @see DataViewConfig
  */
 export declare class DataViewModel extends HoistModel {
     gridModel: GridModel;

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

@@ -5,6 +5,12 @@ import { ReactNode } from 'react';
 import { FilterChooserFieldSpec, FilterChooserFieldSpecConfig } from './FilterChooserFieldSpec';
 import { FilterChooserOption } from './impl/Option';
 import { QueryEngine } from './impl/QueryEngine';
+/**
+ * Configuration for a {@link FilterChooserModel} - an interactive, tokenized filter builder
+ * that binds to a {@link Store} or Cube {@link View}.
+ *
+ * @see FilterChooserModel
+ */
 export interface FilterChooserConfig {
     /**
      * Specifies the fields this model supports for filtering and customizes how their available values
@@ -73,7 +79,7 @@ export interface FilterChooserConfig {
  * 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
+ * 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.
  *

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

@@ -20,7 +20,8 @@ export declare const FormContext: import("react").Context<FormContextType>;
 export interface FormProps<M extends FormModel = FormModel> extends HoistProps<M>, TestSupportProps {
     /**
      * Defaults for certain props on child/nested FormFields.
-     * @see FormField (note there are both desktop and mobile implementations).
+     * Note there are both desktop and mobile implementations of FormField.
+     * @see FormField
      */
     fieldDefaults?: Partial<BaseFormFieldProps> & DefaultHoistProps;
 }

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

@@ -2,6 +2,15 @@ import { HoistModel, PersistOptions, PlainObject } from '@xh/hoist/core';
 import { ValidationState } from '@xh/hoist/data';
 import { BaseFieldConfig, BaseFieldModel } from './field/BaseFieldModel';
 import { SubformsFieldConfig, SubformsFieldModel } from './field/SubformsFieldModel';
+/**
+ * Configuration for a {@link FormModel}. Provide `fields` to define the form's data schema
+ * and validation rules. Optionally supply `initialValues` to pre-populate the form.
+ *
+ * See the form package README (`cmp/form/README.md`) for usage patterns and validation.
+ *
+ * @see FormModel
+ * @see BaseFieldConfig
+ */
 export interface FormConfig {
     /** FieldModels, or configs to create them, for all data fields managed by the model. */
     fields?: Array<BaseFieldModel | BaseFieldConfig | SubformsFieldConfig | SubformsFieldModel>;
@@ -46,6 +55,9 @@ export interface FormValidateOptions {
  * where each split has its own internal fields for broker, quantity, and time).
  *
  * See {@link FieldModel} for details on state/validation maintained at the individual field level.
+ *
+ * See the form package README (`cmp/form/README.md`) for full documentation including field
+ * configuration, validation patterns, and FormField component binding.
  */
 export declare class FormModel extends HoistModel {
     /** Container object for FieldModel instances, keyed by field name.*/

package/build/types/cmp/form/field/BaseFieldModel.d.ts

@@ -1,6 +1,13 @@
 import { HoistModel } from '@xh/hoist/core';
 import { Rule, RuleLike, ValidationResult, ValidationState } from '@xh/hoist/data';
 import { FormModel } from '../FormModel';
+/**
+ * Configuration for a {@link BaseFieldModel} - defines a single field within a
+ * {@link FormModel} including its name, initial value, and validation rules.
+ *
+ * @see FieldModel
+ * @see FormConfig
+ */
 export interface BaseFieldConfig {
     /** Unique name for this field within its parent FormModel. */
     name: string;

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

@@ -2,6 +2,12 @@ import { CardModel } from '@xh/hoist/cmp/card/CardModel';
 import { FieldModel } from '@xh/hoist/cmp/form';
 import { type PersistOptions } from '@xh/hoist/core';
 import { ValidationSeverity } from '@xh/hoist/data';
+/**
+ * Configuration for a {@link FormFieldSetModel} - a collapsible container for grouping
+ * related form fields with aggregated validation state.
+ *
+ * @see FormFieldSetModel
+ */
 export interface FormFieldSetConfig {
     /** Can form field set be collapsed? */
     collapsible?: boolean;
@@ -15,7 +21,7 @@ export interface FormFieldSetConfig {
     persistWith?: PersistOptions;
 }
 /**
- * Model for a FormFieldSet — a collapsible container for grouping related form fields.
+ * 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.