@xh/hoist 83.1.0 → 84.0.1

package/desktop/cmp/button/Button.ts

@@ -42,20 +42,30 @@ export interface ButtonProps<M extends HoistModel = null>
     tooltip?: string;
 }
 
+export interface ButtonDefaults {
+    minimal?: boolean;
+    outlined?: boolean;
+}
+
 /**
  * Wrapper around Blueprint's Button component. Defaults to the `minimal` style for reduced chrome
  * and adds layout support for top-level sizing and margin/padding props.
  *
  * Relays all other props supported by Blueprint's button.
  */
-export const [Button, button] = hoistCmp.withFactory<ButtonProps>({
+export const [Button, button] = hoistCmp.withFactory<ButtonProps, ButtonDefaults>({
     displayName: 'Button',
     model: false,
     className: 'xh-button',
+    defaults: {
+        minimal: true,
+        outlined: false
+    },
 
     render(props, ref) {
         const [layoutProps, nonLayoutProps] = splitLayoutProps(props),
-            classes = [];
+            classes = [],
+            {defaults} = Button;
 
         const {
             autoFocus,
@@ -63,9 +73,9 @@ export const [Button, button] = hoistCmp.withFactory<ButtonProps>({
             disabled,
             icon,
             intent,
-            minimal = true,
+            minimal = defaults.minimal,
             onClick,
-            outlined,
+            outlined = defaults.outlined,
             rightIcon,
             style,
             text,

package/desktop/cmp/dash/README.md

@@ -1,5 +1,19 @@
 # Dashboard
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Dashboard system intro, DashContainer vs DashCanvas comparison |
+| [Architecture](#architecture) | Model hierarchy, ViewSpec/ViewModel lifecycle |
+| [DashContainer](#dashcontainer) | Space-filling tabbed/tiled layout via GoldenLayout |
+| [DashCanvas](#dashcanvas) | Scrollable grid-based widget layout via react-grid-layout |
+| [DashCanvasWidgetChooser](#dashcanvaswidgetchooser) | UI for adding widgets to a DashCanvas |
+| [Common Features](#common-features) | ViewSpecs, state persistence, publishing, refresh |
+| [Widget Content Patterns](#widget-content-patterns) | Implementing widget views and their models |
+| [Common Patterns](#common-patterns) | Initialization, programmatic layout, view management |
+| [Common Pitfalls](#common-pitfalls) | Frequent issues and how to avoid them |
+| [Key Source Files](#key-source-files) | Primary source files for the dash package |
+| [Related Packages](#related-packages) | Links to related hoist-react packages |
+
 ## Overview
 
 The `/desktop/cmp/dash/` package provides Hoist's dashboard system — configurable layouts where

package/desktop/cmp/dash/canvas/DashCanvasModel.ts

@@ -32,6 +32,15 @@ import {
     compact
 } from 'lodash';
 
+/**
+ * Configuration for a {@link DashCanvasModel} - a grid-based dashboard layout with
+ * drag-and-drop positioning and resizing of views.
+ *
+ * See the dash package README (`desktop/cmp/dash/README.md`) for architecture and usage.
+ *
+ * @see DashCanvasModel
+ * @see DashCanvasViewSpec
+ */
 export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCanvasItemState> {
     /**
      * Total number of columns (x coordinates for views correspond with column numbers).
@@ -46,7 +55,7 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
     rowHeight?: number;
 
     /**
-     * Compaction strategy for condensing empty space. Use `'wrap'` with caution — it only
+     * Compaction strategy for condensing empty space. Use `'wrap'` with caution - it only
      * works well if all items are 1 row high. Default `'vertical'`.
      */
     compact?: boolean | 'vertical' | 'horizontal' | 'wrap';
@@ -336,7 +345,7 @@ export class DashCanvasModel
      * Add a view to the canvas.
      * @param specId - ID of the DashCanvasViewSpec to add.
      * @param opts - optional title, state, dimensions, and position. `position` accepts a view
-     *      ID in addition to the enumerated values — the new view will take that view's position.
+     *      ID in addition to the enumerated values - the new view will take that view's position.
      */
     @action
     addView(
@@ -411,7 +420,7 @@ export class DashCanvasModel
 
     /**
      * Handle a completed drop from react-grid-layout. Creates the new view from `draggedInView`
-     * and places it at the drop location. Called by the DashCanvas component — not typically
+     * and places it at the drop location. Called by the DashCanvas component - not typically
      * called directly by application code.
      */
     onDrop(rglLayout: LayoutItem[], layoutItem: LayoutItem, evt: Event) {

package/desktop/cmp/dash/container/DashContainerModel.ts

@@ -50,6 +50,15 @@ import {
 } from './impl/DashContainerUtils';
 import {showContextMenu} from '@xh/hoist/kit/blueprint';
 
+/**
+ * Configuration for a {@link DashContainerModel} - a tab-and-stack based dashboard layout
+ * with draggable, resizable views powered by GoldenLayout.
+ *
+ * See the dash package README (`desktop/cmp/dash/README.md`) for architecture and usage.
+ *
+ * @see DashContainerModel
+ * @see DashViewSpec
+ */
 export interface DashContainerConfig extends DashConfig<
     DashContainerViewSpec,
     DashContainerViewState

package/desktop/cmp/dock/DockViewModel.ts

@@ -22,6 +22,13 @@ import {throwIf} from '@xh/hoist/utils/js';
 import {ReactElement} from 'react';
 import {DockContainerModel} from './DockContainerModel';
 
+/**
+ * Configuration for a {@link DockViewModel} - a dockable view within a
+ * {@link DockContainerModel}.
+ *
+ * @see DockViewModel
+ * @see DockContainerModel
+ */
 export interface DockViewConfig {
     /** Unique identifier for this DockViewModel. */
     id: string;

package/desktop/cmp/filechooser/FileChooserModel.ts

@@ -10,10 +10,17 @@ import {actionCol, calcActionColWidth} from '@xh/hoist/desktop/cmp/grid';
 import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
-import {isEmpty} from 'codemirror/src/util/misc';
 import {filesize} from 'filesize';
-import {find, uniqBy, without} from 'lodash';
+import {find, isEmpty, uniqBy, without} from 'lodash';
 
+/**
+ * Model managing file selection state for a FileChooser component.
+ *
+ * Tracks selected files, supports add/remove/clear operations, and de-duplicates by filename.
+ * Includes a managed GridModel to display selected files with name and size columns.
+ *
+ * @see FileChooser
+ */
 export class FileChooserModel extends HoistModel {
     @observable.ref
     files: File[] = [];

package/desktop/cmp/grid/editors/BooleanEditor.ts

@@ -25,6 +25,7 @@ export interface BooleanEditorProps extends EditorProps<CheckboxProps> {
     quickToggle?: boolean;
 }
 
+/** Checkbox-based inline cell editor for boolean values in a Grid. */
 export const [BooleanEditor, booleanEditor] = hoistCmp.withFactory<BooleanEditorProps>({
     displayName: 'BooleanEditor',
     className: 'xh-boolean-editor',

package/desktop/cmp/grid/editors/DateEditor.ts

@@ -14,6 +14,7 @@ import {useInlineEditorModel} from './impl/InlineEditorModel';
 
 export type DateEditorProps = EditorProps<DateInputProps>;
 
+/** Date picker inline cell editor with calendar popover rendered within the grid viewport. */
 export const [DateEditor, dateEditor] = hoistCmp.withFactory<DateEditorProps>({
     displayName: 'DateEditor',
     className: 'xh-date-editor',

package/desktop/cmp/grid/editors/NumberEditor.ts

@@ -17,6 +17,7 @@ import {useInlineEditorModel} from './impl/InlineEditorModel';
 
 export type NumberEditorProps = EditorProps<NumberInputProps>;
 
+/** Numeric input inline cell editor with guards to reject non-numeric key presses. */
 export const [NumberEditor, numberEditor] = hoistCmp.withFactory<NumberEditorProps>({
     displayName: 'NumberEditor',
     className: 'xh-number-editor',

package/desktop/cmp/grid/editors/SelectEditor.ts

@@ -14,6 +14,7 @@ import {useInlineEditorModel} from './impl/InlineEditorModel';
 
 export type SelectEditorProps = EditorProps<SelectProps>;
 
+/** Dropdown select inline cell editor for choice fields in a Grid. */
 export const [SelectEditor, selectEditor] = hoistCmp.withFactory<SelectEditorProps>({
     displayName: 'SelectEditor',
     className: 'xh-select-editor',

package/desktop/cmp/grid/editors/TextAreaEditor.ts

@@ -13,6 +13,7 @@ import {useInlineEditorModel} from './impl/InlineEditorModel';
 
 export type TextAreaEditorProps = EditorProps<TextAreaProps>;
 
+/** Multi-line text input inline cell editor for long-form string values in a Grid. */
 export const [TextAreaEditor, textAreaEditor] = hoistCmp.withFactory<TextAreaEditorProps>({
     displayName: 'TextAreaEditor',
     className: 'xh-textarea-editor',

package/desktop/cmp/grid/editors/TextEditor.ts

@@ -13,6 +13,7 @@ import {useInlineEditorModel} from './impl/InlineEditorModel';
 
 export type TextEditorProps = EditorProps<TextInputProps>;
 
+/** Text input inline cell editor for string values in a Grid. */
 export const [TextEditor, textEditor] = hoistCmp.withFactory<TextEditorProps>({
     displayName: 'TextEditor',
     className: 'xh-text-editor',

package/desktop/cmp/input/Picker.ts

@@ -151,7 +151,7 @@ export interface PickerProps extends HoistProps, HoistInputProps, LayoutProps, S
      * Receives an array of selected option objects, the full list of option objects, and the
      * configured `displayNoun` (if any). Return a ReactNode for display. Overrides the default
      * button text, including any `displayNoun`-based summary. Does not replace the button
-     * itself — use `buttonProps` to customize the button's icon, intent, or other properties.
+     * itself - use `buttonProps` to customize the button's icon, intent, or other properties.
      */
     buttonTextRenderer?: (
         selectedOpts: SelectOption[],
@@ -440,7 +440,7 @@ const optionsList = hoistCmp.factory<PickerModel>(({model, props}) => {
         useVirtual =
             enableVirtual != null ? executeIfFunction(enableVirtual) : filteredOptions.length > 100;
 
-    // Read selection state so observer re-renders on changes — needed for virtual mode
+    // Read selection state so observer re-renders on changes - needed for virtual mode
     // where option rows are not individually observed.
     if (useVirtual) model.getSelectedValues();
 

package/desktop/cmp/input/SegmentedControl.ts

@@ -41,10 +41,10 @@ export interface SegmentedControlProps extends HoistProps, HoistInputProps {
      * with value/label/icon/disabled properties, or a primitive value used as both
      * the value and the display label.
      */
-    options: (SegmentedControlOption | OptionPrimitive)[];
+    options: Array<SegmentedControlOption | SegmentedControlNullOption | OptionPrimitive>;
 
     /**
-     * True to render with an outlined style — a border around the control tray
+     * True to render with an outlined style - a border around the control tray
      * with no inner background fill. Border color follows the current intent.
      */
     outlined?: boolean;
@@ -64,6 +64,24 @@ export interface SegmentedControlOption {
     disabled?: boolean;
 }
 
+/**
+ * Variant of SegmentedControlOption for representing a null/"no value" selection.
+ * Label is required to force use case to override default js 'null' toString rendering.
+ */
+export interface SegmentedControlNullOption {
+    /** Null value for this option. */
+    value: null;
+
+    /** Display label - required for null options. */
+    label: string;
+
+    /** Icon element, displayed before the label. */
+    icon?: ReactElement;
+
+    /** True to disable this individual option. */
+    disabled?: boolean;
+}
+
 /**
  * An input for selecting a single value from a small set of mutually exclusive options,
  * rendered as a group of toggle buttons with clear visual indication of the active

package/desktop/cmp/leftrightchooser/LeftRightChooserModel.ts

@@ -12,6 +12,12 @@ import {Icon} from '@xh/hoist/icon';
 import {bindable, computed, makeObservable} from '@xh/hoist/mobx';
 import {FilterTestFn, StoreConfig, StoreRecord} from '@xh/hoist/data';
 
+/**
+ * Configuration for a {@link LeftRightChooserModel} - a dual-list control for moving items
+ * between "available" (left) and "selected" (right) collections.
+ *
+ * @see LeftRightChooserModel
+ */
 export interface LeftRightChooserConfig {
     data?: LeftRightChooserItem[];
 
@@ -41,6 +47,7 @@ export interface LeftRightChooserConfig {
     rightGroupingExpanded?: boolean;
     rightEmptyText?: string;
 
+    /** @internal */
     xhImpl?: boolean;
 }
 

package/desktop/cmp/modalsupport/ModalSupportModel.ts

@@ -10,16 +10,45 @@ import '@xh/hoist/desktop/register';
 import {makeObservable, bindable} from '@xh/hoist/mobx';
 import {createObservableRef} from '@xh/hoist/utils/react';
 
+/**
+ * Configuration for a {@link ModalSupportModel}. Passed via the `modalSupport` config on
+ * {@link PanelConfig} - set to `true` for defaults or provide a config object to customize
+ * the dialog dimensions and behavior.
+ *
+ * @see ModalSupportModel
+ * @see PanelModel
+ */
 export interface ModalSupportConfig {
+    /** Width of the modal dialog. Default `'90vw'`. */
     width?: string | number;
+
+    /** Height of the modal dialog. Default `'90vh'`. */
     height?: string | number;
+
+    /** True to start in modal (popped-out) state. Default `false`. */
     defaultModal?: boolean;
+
+    /** True to allow closing the modal by clicking outside it. Default `true`. */
     canOutsideClickClose?: boolean;
 }
 
 /**
- * Core Model for a ModalSupport component.
- * This model will place its component's child in 1 of 2 managed DOM nodes (either modal or inline)
+ * Model enabling a {@link Panel}'s content to toggle between inline and modal (floating
+ * dialog) display while preserving all component state.
+ *
+ * Uses a React portal to move a single persistent DOM host node between an inline container
+ * and a Blueprint Dialog. Because the child component is rendered into the host node once
+ * and the node is physically relocated (not re-mounted), all React component state, MobX
+ * subscriptions, and DOM state (scroll position, focus, ag-Grid state, etc.) are preserved
+ * across toggles.
+ *
+ * This is the key advantage over the alternative of mounting a second copy of a component
+ * inside a separate dialog - ModalSupport guarantees zero state loss on toggle.
+ *
+ * Not created directly by applications - enable via `modalSupport` on {@link PanelConfig}.
+ *
+ * @see ModalSupportConfig
+ * @see PanelModel
  */
 export class ModalSupportModel extends HoistModel {
     override xhImpl = true;

package/desktop/cmp/panel/Panel.ts

@@ -104,16 +104,20 @@ export interface PanelProps<M extends PanelModel = PanelModel>
     scrollable?: boolean;
 }
 
+export interface PanelDefaults {
+    compactHeader?: boolean;
+}
+
 /**
  * A Panel container builds on the lower-level layout components to offer a header element
  * w/standardized styling, title, and Icon as well as support for top and bottom toolbars.
  *
  * Panels also support resizing and collapsing their contents via its `model` prop. Provide an
- * optional `PanelModel` config as a prop to enable and customize these features.
+ * optional {@link PanelModel} config as a prop to enable and customize these features.
  *
  * A Panel will accept a ref argument to provide access to its top level DOM element.
  */
-export const [Panel, panel] = hoistCmp.withFactory<PanelProps>({
+export const [Panel, panel] = hoistCmp.withFactory<PanelProps, PanelDefaults>({
     displayName: 'Panel',
     model: uses(PanelModel, {
         fromContext: false,
@@ -121,6 +125,9 @@ export const [Panel, panel] = hoistCmp.withFactory<PanelProps>({
         createDefault: () => new PanelModel({collapsible: false, resizable: false, xhImpl: true})
     }),
     className: 'xh-panel',
+    defaults: {
+        compactHeader: false
+    },
 
     render({model, className, testId, ...props}, ref) {
         const contextModel = useContextModel('*');
@@ -128,25 +135,26 @@ export const [Panel, panel] = hoistCmp.withFactory<PanelProps>({
         let wasDisplayed = useRef(false),
             [layoutProps, nonLayoutProps] = splitLayoutProps(props);
 
-        const {
-            tbar,
-            bbar,
-            title,
-            icon,
-            compactHeader,
-            collapsedTitle,
-            collapsedIcon,
-            headerClassName,
-            headerItems,
-            mask: maskProp,
-            loadingIndicator: loadingIndicatorProp,
-            contextMenu,
-            hotkeys,
-            contentBoxProps,
-            scrollable,
-            children,
-            ...rest
-        } = nonLayoutProps;
+        const {defaults} = Panel,
+            {
+                tbar,
+                bbar,
+                title,
+                icon,
+                compactHeader = defaults.compactHeader,
+                collapsedTitle,
+                collapsedIcon,
+                headerClassName,
+                headerItems,
+                mask: maskProp,
+                loadingIndicator: loadingIndicatorProp,
+                contextMenu,
+                hotkeys,
+                contentBoxProps,
+                scrollable,
+                children,
+                ...rest
+            } = nonLayoutProps;
 
         useLayoutEffect(() => {
             model.enforceSizeLimits();

package/desktop/cmp/panel/PanelModel.ts

@@ -27,6 +27,12 @@ import {createRef} from 'react';
 import {ModalSupportConfig, ModalSupportModel} from '../modalsupport/';
 import {ErrorBoundaryConfig, ErrorBoundaryModel} from '@xh/hoist/cmp/error/ErrorBoundaryModel';
 
+/**
+ * Configuration for a {@link PanelModel} - controls resizing, collapsing, and modal behavior
+ * of a desktop {@link Panel}. Created automatically by Panel when not provided explicitly.
+ *
+ * @see PanelModel
+ */
 export interface PanelConfig {
     /** Can panel be resized? */
     resizable?: boolean;
@@ -113,8 +119,12 @@ export interface PanelPersistState {
 }
 
 /**
- * PanelModel supports configuration and state-management for user-driven Panel resizing and
- * expand/collapse, along with support for saving this state via a configured PersistenceProvider.
+ * PanelModel supports configuration and state-management for user-driven {@link Panel} resizing
+ * and expand/collapse, along with support for saving this state via a configured
+ * PersistenceProvider.
+ *
+ * See the panel package README (`desktop/cmp/panel/README.md`) for sizing, collapsing,
+ * and modal support documentation.
  */
 export class PanelModel extends HoistModel implements Persistable<PanelPersistState> {
     declare config: PanelConfig;

package/desktop/cmp/panel/README.md

@@ -1,5 +1,25 @@
 # Panel
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Panel as the standard desktop container with toolbars and masks |
+| [Basic Usage](#basic-usage) | Minimal panel examples with titles, icons, and toolbars |
+| [Layout](#layout) | Internal vframe structure and content flow |
+| [contentBoxProps](#contentboxprops) | Controlling the inner content frame (padding, flex, scroll) |
+| [scrollable](#scrollable) | Convenience shorthand for vertical content scrolling |
+| [Toolbars](#toolbars) | tbar/bbar, separators, compact mode, and overflow menus |
+| [Panel + Grid Pattern](#panel--grid-pattern) | Common panel-wrapping-grid structure from real apps |
+| [Mask](#mask) | Loading overlays with TaskObserver and onLoad binding |
+| [Collapsing and Resizing](#collapsing-and-resizing) | PanelModel config for collapse, resize, and splitters |
+| [collapsedTitle / collapsedIcon](#collapsedtitle--collapsedicon) | Identifying collapsed panels with custom titles and icons |
+| [compactHeader](#compactheader) | Reduced-size headers for visual hierarchy |
+| [headerItems](#headeritems) | Inline controls in the panel header |
+| [Persistence](#persistence) | Persisting collapsed state and size across sessions |
+| [Modal Support](#modal-support) | Popping panel content into a near-full-screen dialog |
+| [Configuration Reference](#configuration-reference) | Full Panel props and PanelModel config tables |
+| [Common Pitfalls](#common-pitfalls) | mask: 'onLoad' requirements and collapsible panel tips |
+| [Key Source Files](#key-source-files) | Source file locations for Panel and related components |
+
 ## Overview
 
 Panel is the standard container for desktop Hoist application views. Nearly every screen in a Hoist

package/desktop/cmp/rest/RestGrid.ts

@@ -53,6 +53,16 @@ export interface RestGridProps
     tbar?: ReactNode;
 }
 
+/**
+ * A full-featured Grid with a built-in toolbar, record editing form, and refresh support,
+ * designed for CRUD operations against REST-style server endpoints.
+ *
+ * Intended to pair with `RestController` from hoist-core, which provides standard CRUD
+ * endpoints for a GORM domain class. RestGrid's underlying {@link RestStore} maps directly
+ * to the controller's create/read/update/delete/bulk operations and lookup data support.
+ *
+ * @see RestGridModel
+ */
 export const [RestGrid, restGrid] = hoistCmp.withFactory<RestGridProps>({
     displayName: 'RestGrid',
     model: uses(RestGridModel, {publishMode: 'limited'}),

package/desktop/cmp/rest/RestGridModel.ts

@@ -20,6 +20,13 @@ import {addAction, deleteAction, editAction, viewAction} from './Actions';
 import {RestStore, RestStoreConfig} from './data/RestStore';
 import {RestFormModel} from './impl/RestFormModel';
 
+/**
+ * Configuration for a {@link RestGridModel} - extends {@link GridConfig} with CRUD support
+ * for editing records via a built-in form backed by a hoist-core `RestController`.
+ *
+ * @see RestGridModel
+ * @see RestGrid
+ */
 export interface RestGridConfig extends GridConfig {
     store?: RestStore | RestStoreConfig;
 
@@ -93,7 +100,8 @@ export interface RestGridModelDefaults {
 }
 
 /**
- * Core Model for a RestGrid.
+ * Core Model for a {@link RestGrid}. Configures the grid's columns, editors, toolbar and
+ * context menu actions, and its backing {@link RestStore} for server-side CRUD operations.
  */
 export class RestGridModel extends HoistModel {
     /** App-level defaults for RestGridModel. Instance config takes precedence. */

package/desktop/cmp/toolbar/Toolbar.ts

@@ -45,22 +45,29 @@ export interface ToolbarProps extends HoistProps, BoxProps {
     minVisibleItems?: number;
 }
 
+export interface ToolbarDefaults {
+    compact?: boolean;
+}
+
 /**
  * A toolbar with built-in styling and padding.
  * In horizontal toolbars, items which overflow can be collapsed into a drop-down menu.
  */
-export const [Toolbar, toolbar] = hoistCmp.withFactory<ToolbarProps>({
+export const [Toolbar, toolbar] = hoistCmp.withFactory<ToolbarProps, ToolbarDefaults>({
     displayName: 'Toolbar',
     model: false,
     memo: false,
     observer: false,
     className: 'xh-toolbar',
+    defaults: {
+        compact: false
+    },
 
     render(
         {
             children,
             className,
-            compact = false,
+            compact = Toolbar.defaults.compact,
             vertical = false,
             enableOverflowMenu = false,
             collapseFrom = 'end',

package/desktop/cmp/viewmanager/ViewManager.ts

@@ -139,7 +139,7 @@ const menuButton = hoistCmp.factory<ViewManagerLocalModel>({
             icon: !isLoading
                 ? icon
                 : box({
-                      item: spinner({width: 13, height: 13, style: {margin: 'auto'}}),
+                      item: spinner({compact: true}),
                       width: 16.25
                   }),
             rightIcon: Icon.chevronDown(),

package/docs/README.md

@@ -36,6 +36,7 @@ See [`docs-roadmap.md`](./planning/docs-roadmap.md) for documentation coverage t
 | Save and restore named view configurations | [`/cmp/viewmanager/`](../cmp/viewmanager/README.md)                                                                 |
 | Use layout containers (Box, HBox, VBox, Frame) | [`/cmp/layout/`](../cmp/layout/README.md)                                                                           |
 | Work with Stores, Records, Fields, or Filters | [`/data/`](../data/README.md)                                                                                       |
+| Set up Cube aggregation with Views and Queries | [`/data/cube/`](../data/cube/README.md)                                                                             |
 | Use FetchService, ConfigService, or PrefService | [`/svc/`](../svc/README.md)                                                                                         |
 | Add distributed tracing spans to operations | [`/svc/`](../svc/README.md)                                                                                         |
 | Format numbers, dates, or currencies | [`/format/`](../format/README.md)                                                                                   |
@@ -52,6 +53,7 @@ See [`docs-roadmap.md`](./planning/docs-roadmap.md) for documentation coverage t
 | Use timers, decorators, LocalDate, or utility hooks | [`/utils/`](../utils/README.md)                                                                                     |
 | Understand app shell, dialogs, toasts, or theming | [`/appcontainer/`](../appcontainer/README.md)                                                                       |
 | Use icons in buttons, menus, and grids | [`/icon/`](../icon/README.md)                                                                                       |
+| Customize the spinner icon or animation | [`/icon/`](../icon/README.md#spinner-component)                                                                     |
 | Configure OAuth authentication (Auth0 or MSAL) | [`/security/`](../security/README.md) + [Authentication](./authentication.md)                                       |
 | Debug model instances or detect memory leaks | [`/inspector/`](../inspector/README.md)                                                                             |
 | Understand third-party library integration | [`/kit/`](../kit/README.md)                                                                                         |
@@ -70,7 +72,8 @@ See [`docs-roadmap.md`](./planning/docs-roadmap.md) for documentation coverage t
 | Package | Description | Key Topics |
 |---------|-------------|------------|
 | [`/core/`](../core/README.md) | Foundation classes defining Hoist's component, model, and service architecture | HoistBase, HoistModel, HoistService, hoistCmp, XH, element factories, decorators, lifecycle |
-| [`/data/`](../data/README.md) | Observable data layer with filtering, validation, and aggregation | Store, StoreRecord, Field, Filter, Cube, View, tree data, loadData, processRawData |
+| [`/data/`](../data/README.md) | Observable data layer with Store, Field, filtering, validation, and tree data | Store, StoreRecord, Field, Filter, tree data, loadData, processRawData |
+| [`/data/cube/`](../data/cube/README.md) | Client-side OLAP-style aggregation with dimensions, measures, and Views | Cube, CubeField, View, Query, aggregator, dimension, includeRoot, includeLeaves |
 | [`/svc/`](../svc/README.md) | Built-in singleton services for data access and app-wide operations | FetchService, ConfigService, PrefService, IdentityService, TrackService, TraceService, WebSocketService |
 
 ### Components
@@ -120,7 +123,7 @@ Cross-cutting documentation that spans multiple packages:
 
 | Package | Description | Key Topics |
 |---------|-------------|------------|
-| [`/icon/`](../icon/README.md) | Factory-based icon system wrapping FontAwesome Pro | Icon singleton, IconProps, intent coloring, size variants, asHtml, fileIcon, serializeIcon |
+| [`/icon/`](../icon/README.md) | Factory-based icon system wrapping FontAwesome Pro | Icon singleton, IconProps, intent coloring, size variants, asHtml, fileIcon, serializeIcon, Spinner, SpinnerProps |
 | [`/security/`](../security/README.md) | OAuth 2.0 client abstraction for Auth0 and Microsoft Entra ID (MSAL) | BaseOAuthClient, AuthZeroClient, MsalClient, Token, AccessTokenSpec, auto-refresh, re-login |
 | [`/kit/`](../kit/README.md) | Centralized wrappers for third-party libraries used by Hoist | installAgGrid, installHighcharts, Blueprint, Onsen, GoldenLayout, react-select, version constraints |
 | [`/inspector/`](../inspector/README.md) | Built-in developer tool for real-time inspection of Hoist instances and memory | InspectorPanel, StatsModel, InstancesModel, property watchlist, model leak detection |
@@ -161,6 +164,8 @@ breaking changes, before/after code examples, and verification checklists.
 
 | Version | Released | Difficulty | Key Changes |
 |---------|----------|------------|-------------|
+| [v84](./upgrade-notes/v84-upgrade-notes.md) | 2026-04-15 | 🟢 LOW | FontAwesome v7, icon-based Spinner, `getClassName` removal, hoistCmp `defaults` |
+| [v83](./upgrade-notes/v83-upgrade-notes.md) | 2026-03-24 | 🟢 LOW | TraceService, static defaults pattern, `downloadjs` removal, `SegmentedControl` |
 | [v82](./upgrade-notes/v82-upgrade-notes.md) | 2026-02-25 | 🟢 LOW | `FetchService` static correlation IDs, `xh-popup--framed` removal, DashContainer CSS wrapper |
 | [v81](./upgrade-notes/v81-upgrade-notes.md) | 2026-02-12 | 🟢 LOW | Panel CSS rename, `completeAuthAsync` return type, Blueprint `Card` → `BpCard` |
 | [v80](./upgrade-notes/v80-upgrade-notes.md) | 2026-01-27 | 🟢 LOW | FormField BEM CSS classes, `appLoadModel` → `appLoadObserver`, jQuery resolution |
@@ -184,7 +189,7 @@ breaking changes, before/after code examples, and verification checklists.
 - [`/CHANGELOG.md`](../CHANGELOG.md) — Version history and release notes (v56+)
 - [`archive/CHANGELOG-pre-v56.md`](./archive/CHANGELOG-pre-v56.md) — Archived changelog for
   versions prior to v56
-- [`changelog-format.md`](./changelog-format.md) — CHANGELOG entry format conventions and
-  section headers
+- [`changelog-format.md`](./changelog-format.md) — Conventions for writing and reviewing
+  hoist-react library CHANGELOG entries
 - [Toolbox](https://github.com/xh/toolbox) — XH's example application showcasing hoist-react
   patterns and components