@xh/hoist 83.1.0 → 84.0.1

package/cmp/dataview/DataViewModel.ts

@@ -33,7 +33,10 @@ import {isFunction, isNumber} from 'lodash';
 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. */
@@ -131,10 +134,19 @@ export type ItemHeightFn = (params: {
 }) => 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 class DataViewModel extends HoistModel {
     @managed gridModel: GridModel;

package/cmp/filter/FilterChooserModel.ts

@@ -55,6 +55,12 @@ import {FilterChooserFieldSpec, FilterChooserFieldSpecConfig} from './FilterChoo
 import {compoundFilterOption, fieldFilterOption, 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
@@ -136,7 +142,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/cmp/form/Form.ts

@@ -43,7 +43,8 @@ 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/cmp/form/FormModel.ts

@@ -36,6 +36,15 @@ import {FieldModel} from './field/FieldModel';
 import {SubformsFieldConfig, SubformsFieldModel} from './field/SubformsFieldModel';
 import {isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
 
+/**
+ * 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>;
@@ -87,6 +96,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 class FormModel extends HoistModel {
     /** Container object for FieldModel instances, keyed by field name.*/

package/cmp/form/README.md

@@ -1,5 +1,18 @@
 # Form Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Form infrastructure for data entry with validation and binding |
+| [Architecture](#architecture) | FormModel, FieldModel, and SubformsFieldModel structure |
+| [FormModel](#formmodel) | Creating forms, working with data, validation, and focus |
+| [FieldModel](#fieldmodel) | Individual field state, validation rules, and observable props |
+| [SubformsFieldModel](#subformsfieldmodel) | Nested form collections for complex data structures |
+| [Form Component](#form-component) | Non-visual React context provider for FormField components |
+| [FormFieldSet](#formfieldset) | Visual grouping with aggregate validation and state cascading |
+| [Common Patterns](#common-patterns) | Forms in models, cascading dropdowns, persistence, scrolling |
+| [Common Pitfalls](#common-pitfalls) | Confusing form imports and other issues |
+| [Related Packages](#related-packages) | Links to card, data, input, and platform form packages |
+
 ## Overview
 
 The `/cmp/form/` package works along with `/cmp/input` to provide Hoist's form infrastructure -

package/cmp/form/field/BaseFieldModel.ts

@@ -20,6 +20,13 @@ import {createObservableRef} from '@xh/hoist/utils/react';
 import {compact, flatten, isEmpty, isEqual, isFunction, isNil, isString} from 'lodash';
 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/cmp/form/formfieldset/FormFieldSetModel.ts

@@ -13,6 +13,12 @@ import {makeObservable} from '@xh/hoist/mobx';
 import {uniq, without} from 'lodash';
 import {action, computed, observable} from 'mobx';
 
+/**
+ * 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;
@@ -31,7 +37,7 @@ export interface FormFieldSetConfig {
 }
 
 /**
- * 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.

package/cmp/grid/Grid.scss

@@ -358,11 +358,16 @@
     display: none;
   }
 
-  // Default minimal styling. This is not applied when using a custom tooltip.
+  // Default minimal styling. Not applied when using a custom tooltip.
+  // Uses pre-wrap to honor intentional \n line breaks in tooltip content
+  // while still wrapping long lines at the max-width boundary.
   &--default {
-    padding: var(--xh-pad-half-px);
-    background: var(--xh-bg);
-    border: var(--xh-border-solid);
+    padding: var(--xh-grid-tooltip-padding);
+    background: var(--xh-grid-tooltip-bg);
+    border: var(--xh-grid-tooltip-border);
+    border-radius: var(--xh-grid-tooltip-border-radius);
+    max-width: var(--xh-grid-tooltip-max-width);
+    white-space: pre-wrap;
   }
 
   // Validation tooltip styling. Adjust depending on if within a default or custom tooltip.
@@ -383,12 +388,13 @@
   }
 
   &--custom > div > .xh-grid-tooltip--validation {
-    padding: var(--xh-pad-half-px) var(--xh-pad-half-px) var(--xh-pad-half-px) 2em;
-    background: var(--xh-bg);
-    border: var(--xh-border-solid);
+    padding: var(--xh-grid-tooltip-padding) var(--xh-grid-tooltip-padding)
+      var(--xh-grid-tooltip-padding) 2em;
+    background: var(--xh-grid-tooltip-bg);
+    border: var(--xh-grid-tooltip-border);
 
     &--single {
-      padding: var(--xh-pad-half-px);
+      padding: var(--xh-grid-tooltip-padding);
     }
   }
 }

package/cmp/grid/GridModel.ts

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

package/cmp/grid/GridSorter.ts

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

package/cmp/grid/README.md

@@ -1,5 +1,17 @@
 # Grid Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Introduction to Hoist's tabular and hierarchical data grid |
+| [Architecture](#architecture) | Class hierarchy and key classes |
+| [Configuration Pattern](#configuration-pattern) | Spec-to-object transformation for declarative config |
+| [Common Usage Patterns](#common-usage-patterns) | Sorting, grouping, tree mode, selection, filtering, and more |
+| [Column Properties Reference](#column-properties-reference) | Key categories of ColumnSpec properties |
+| [Extension Points](#extension-points) | ag-Grid passthrough, custom comparators, and appData |
+| [App-Level Defaults](#app-level-defaults) | Static defaults for GridModel and GridFilterModel |
+| [Pitfalls](#pitfalls) | Duplicate column IDs and other common issues |
+| [Related Packages](#related-packages) | Links to data, ag-grid, desktop/mobile grid, and svc |
+
 ## Overview
 
 Grid is Hoist React's primary component for displaying tabular and hierarchical data. Built on

package/cmp/grid/Types.ts

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

package/cmp/grid/columns/Column.ts

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

package/cmp/grid/columns/ColumnGroup.ts

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

package/cmp/grouping/GroupingChooserModel.ts

@@ -12,6 +12,13 @@ import {action, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {executeIfFunction, throwIf} from '@xh/hoist/utils/js';
 import {isArray, isEmpty, isEqual, isObject, isString, keys, sortBy} from 'lodash';
 
+/**
+ * Configuration for a {@link GroupingChooserModel} - a control for selecting multi-level
+ * dimension groupings, typically bound to a Cube {@link View} or {@link GridModel}.
+ *
+ * @see GroupingChooserModel
+ * @see DimensionSpec
+ */
 export interface GroupingChooserConfig {
     /** True to accept an empty list as a valid value. */
     allowEmpty?: boolean;
@@ -21,7 +28,7 @@ export interface GroupingChooserConfig {
      * should be automatically applied as it changes. When bound to a GridModel, calls
      * `setGroupBy()`; when bound to a View, calls `updateQuery({dimensions: ...})`.
      *
-     * This is a two-way binding — changes to the target's value are reflected back into
+     * This is a two-way binding - changes to the target's value are reflected back into
      * the GroupingChooserModel automatically.
      */
     bind?: GroupingBindTarget;
@@ -98,7 +105,7 @@ export type GroupingBindTarget = GridModel | View;
  *
  * Manages the current dimension selection, available dimensions, user-managed favorites, and
  * drag-and-drop reordering. Supports bidirectional binding to a {@link GridModel} or Cube
- * {@link View} via the `bind` config — grouping changes are automatically applied to the
+ * {@link View} via the `bind` config - grouping changes are automatically applied to the
  * target, and external changes to the target are reflected back into this model.
  *
  * Dimensions can be auto-populated from the bind target or specified explicitly. When binding

package/cmp/layout/Box.ts

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

package/cmp/layout/Frame.ts

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

package/cmp/layout/README.md

@@ -10,22 +10,16 @@ All layout components export both a React component (PascalCase) and an element
 
 ## Core Components
 
-### Box / VBox / HBox
+### VBox / HBox / Box
 
-The base flexbox container and its directional variants.
+Flexbox containers with layout prop support.
 
 ```typescript
-import {box, vbox, hbox} from '@xh/hoist/cmp/layout';
-
-// Generic flex container
-box({
-    items: [header(), content(), footer()],
-    flexDirection: 'column',
-    padding: 10
-})
+import {vbox, hbox} from '@xh/hoist/cmp/layout';
 
 // Vertical layout (column direction)
 vbox({
+    padding: 10,
     items: [header(), content(), footer()]
 })
 
@@ -35,22 +29,20 @@ hbox({
 })
 ```
 
-**Box provides:**
+**All Box variants provide:**
 - `display: flex` with `overflow: hidden` and `position: relative`
-- All flexbox layout props via the `BoxProps` interface
+- All flexbox layout props via the `BoxProps` interface (see [Layout Props](#layout-props-boxprops))
 - Pass-through of standard HTML div attributes
 
-**VBox/HBox** are convenience wrappers that set `flexDirection` to `column` or `row` respectively.
+**Prefer `vbox` and `hbox`** over bare `box` — they make layout direction explicit. `box` applies
+`display: flex` with the CSS default direction (row) but does not communicate that intent clearly.
 
-### Frame / VFrame / HFrame
+### VFrame / HFrame / Frame
 
 Flexing containers that stretch to fill their parent via `flex: auto`.
 
 ```typescript
-import {frame, vframe, hframe} from '@xh/hoist/cmp/layout';
-
-// Generic frame
-frame({item: content()})
+import {vframe, hframe} from '@xh/hoist/cmp/layout';
 
 // Vertical frame (stretches and arranges children vertically)
 vframe({
@@ -63,9 +55,12 @@ hframe({
 })
 ```
 
-**Key difference from Box:** Frame adds `flex: auto`, making it stretch to consume available space
-in its parent container. Use Frame for content areas that should grow; use Box when you need
-explicit size control.
+**Key difference from Box variants:** Frame adds `flex: auto`, making it stretch to consume
+available space in its parent container. Use Frame variants for content areas that should grow;
+use Box variants when you need explicit size control.
+
+**Prefer `vframe` and `hframe`** over bare `frame` for the same reason as above — they make
+layout direction explicit.
 
 ### Viewport
 

package/cmp/loadingindicator/LoadingIndicator.scss

@@ -68,7 +68,7 @@
 
   .xh-hbox {
     flex: none;
-    align-items: start;
+    align-items: center;
     flex-wrap: nowrap;
   }