@xh/hoist 83.1.0 → 84.0.1

package/build/types/desktop/cmp/panel/Panel.d.ts

@@ -57,13 +57,16 @@ export interface PanelProps<M extends PanelModel = PanelModel> extends HoistProp
     /** Allow the panel content area to scroll vertically. */
     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 declare const Panel: import("react").FC<PanelProps<PanelModel>>, panel: import("@xh/hoist/core").ElementFactory<PanelProps<PanelModel>>;
+export declare const Panel: any, panel: import("@xh/hoist/core").ElementFactory<PanelProps<PanelModel>>;

package/build/types/desktop/cmp/panel/PanelModel.d.ts

@@ -3,6 +3,12 @@ import { HoistModel, Persistable, PersistableState, PersistOptions, RefreshConte
 import '@xh/hoist/desktop/register';
 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;
@@ -70,8 +76,12 @@ export interface PanelPersistState {
     size?: number | string;
 }
 /**
- * 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 declare class PanelModel extends HoistModel implements Persistable<PanelPersistState> {
     config: PanelConfig;

package/build/types/desktop/cmp/rest/RestGrid.d.ts

@@ -30,4 +30,14 @@ export interface RestGridProps extends HoistProps<RestGridModel>, Omit<PanelProp
      */
     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 declare const RestGrid: import("react").FC<RestGridProps>, restGrid: import("@xh/hoist/core").ElementFactory<RestGridProps>;

package/build/types/desktop/cmp/rest/RestGridModel.d.ts

@@ -9,6 +9,13 @@ import { ReactNode } from 'react';
 import { FormFieldProps } from '../form';
 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;
     /** Prevent users from creating, updating, or destroying a record. Defaults to false. */
@@ -68,7 +75,8 @@ export interface RestGridModelDefaults {
     unit?: string;
 }
 /**
- * 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 declare class RestGridModel extends HoistModel {
     /** App-level defaults for RestGridModel. Instance config takes precedence. */

package/build/types/desktop/cmp/toolbar/Toolbar.d.ts

@@ -23,8 +23,11 @@ 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 declare const Toolbar: import("react").FC<ToolbarProps>, toolbar: import("@xh/hoist/core").ElementFactory<ToolbarProps>;
+export declare const Toolbar: any, toolbar: import("@xh/hoist/core").ElementFactory<ToolbarProps>;

package/build/types/format/FormatDate.d.ts

@@ -10,7 +10,7 @@ export interface DateFormatOptions extends FormatOptions<DateLike> {
     nullDisplay?: ReactNode;
     /**
      * A MomentJs format string. Wrap literal text in square brackets to prevent
-     * interpretation as format tokens — e.g. `'[today at] h:mma'`.
+     * interpretation as format tokens - e.g. `'[today at] h:mma'`.
      */
     fmt?: string;
 }
@@ -33,17 +33,17 @@ export declare function fmtTime(v: DateLike, opts?: DateFormatOptions | string):
 export interface CompactDateFormatOptions extends FormatOptions<DateLike> {
     /**
      * Format for date matching current day, defaults to 'hh:mma' for dates, 'MMM D' for
-     * LocalDates. Wrap literal text in square brackets — e.g. `'[today]'` or `'[today at] h:mma'`.
+     * LocalDates. Wrap literal text in square brackets - e.g. `'[today]'` or `'[today at] h:mma'`.
      */
     sameDayFmt?: string;
     /**
      * Format for dates within the number of months specified by the distantThreshold, defaults
-     * to 'MMM D'. Wrap literal text in square brackets — e.g. `'[recent]'`.
+     * to 'MMM D'. Wrap literal text in square brackets - e.g. `'[recent]'`.
      */
     nearFmt?: string;
     /**
      * Format for dates beyond number of months specified by the distantThreshold, defaults to
-     * 'YYYY-MM-DD'. Wrap literal text in square brackets — e.g. `'[older]'`.
+     * 'YYYY-MM-DD'. Wrap literal text in square brackets - e.g. `'[older]'`.
      */
     distantFmt?: string;
     /** Number of months away from the current month to be considered 'recent' or 'near'. */

package/build/types/icon/Icon.d.ts

@@ -109,6 +109,7 @@ export declare const Icon: {
     chevronRight(p?: IconProps): any;
     chevronUp(p?: IconProps): any;
     circle(p?: IconProps): any;
+    circleNotch(p?: IconProps): any;
     clipboard(p?: IconProps): any;
     clock(p?: IconProps): any;
     cloudDownload(p?: IconProps): any;
@@ -236,6 +237,8 @@ export declare const Icon: {
     slashedCircle(p?: IconProps): any;
     sparkles(p?: IconProps): any;
     spinner(p?: IconProps): any;
+    spinnerScale(p?: IconProps): any;
+    spinnerThird(p?: IconProps): any;
     square(p?: IconProps): any;
     squareMinus(p?: IconProps): any;
     star(p?: IconProps): any;

package/build/types/kit/blueprint/Wrappers.d.ts

@@ -4,5 +4,16 @@ import React from 'react';
 declare const Dialog: React.FC<DialogProps>;
 declare const Popover: React.FC<PopoverProps>;
 export { Alert, BpSegmentedControl, Button, ButtonGroup, Callout, BpCard, Checkbox, ControlGroup, DatePicker, Dialog, Drawer, EditableText, FileInput, FormGroup, Hotkeys, Hotkey, InputGroup, Label, Menu, MenuItem, MenuDivider, Navbar, NavbarDivider, NavbarGroup, NavbarHeading, NumericInput, OverflowList, Overlay, Popover, Radio, RadioGroup, RangeSlider, Slider, Switch, Tab, Tabs, Tag, TagInput, TextArea, Text, Tooltip, Tree };
-export declare const alert: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").AlertProps>, bpSegmentedControl: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").SegmentedControlProps>, button: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ButtonProps>, controlGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ControlGroupProps>, checkbox: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").CheckboxProps>, dialog: import("@xh/hoist/core").ElementFactory<DialogProps>, datePicker: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/datetime").DatePickerProps>, menuDivider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").MenuDividerProps>, menuItem: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").MenuItemProps>, navbarDivider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").NavbarDividerProps>, numericInput: import("@xh/hoist/core").ElementFactory<Omit<import("@blueprintjs/core").HTMLInputProps, "size"> & import("@blueprintjs/core").NumericInputProps>, overflowList: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").OverflowListProps<any>>, popover: import("@xh/hoist/core").ElementFactory<PopoverProps<import("@blueprintjs/core").DefaultPopoverTargetHTMLProps>>, radio: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ControlProps>, rangeSlider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").RangeSliderProps>, slider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").SliderProps>, switchControl: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").SwitchProps>, textArea: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TextAreaProps>, tree: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TreeProps<unknown>>, tagInput: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TagInputProps>, fileInput: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").FileInputProps>, overlay: import("@xh/hoist/core").ElementFactory<Omit<import("@blueprintjs/core").Overlay2Props, "ref"> & React.RefAttributes<import("@blueprintjs/core").OverlayInstance>>, tooltip: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TooltipProps<import("@blueprintjs/core").DefaultPopoverTargetHTMLProps>>;
+export declare const alert: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").AlertProps>, bpSegmentedControl: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").SegmentedControlProps>, button: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ButtonProps>, controlGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ControlGroupProps>, checkbox: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").CheckboxProps>, datePicker: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/datetime").DatePickerProps>, menuDivider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").MenuDividerProps>, menuItem: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").MenuItemProps>, navbarDivider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").NavbarDividerProps>, numericInput: import("@xh/hoist/core").ElementFactory<Omit<import("@blueprintjs/core").HTMLInputProps, "size"> & import("@blueprintjs/core").NumericInputProps>, overflowList: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").OverflowListProps<any>>, popover: import("@xh/hoist/core").ElementFactory<PopoverProps<import("@blueprintjs/core").DefaultPopoverTargetHTMLProps>>, radio: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ControlProps>, rangeSlider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").RangeSliderProps>, slider: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").SliderProps>, switchControl: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").SwitchProps>, textArea: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TextAreaProps>, tree: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TreeProps<unknown>>, tagInput: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TagInputProps>, fileInput: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").FileInputProps>, overlay: import("@xh/hoist/core").ElementFactory<Omit<import("@blueprintjs/core").Overlay2Props, "ref"> & React.RefAttributes<import("@blueprintjs/core").OverlayInstance>>, tooltip: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TooltipProps<import("@blueprintjs/core").DefaultPopoverTargetHTMLProps>>;
 export declare const buttonGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").ButtonGroupProps>, callout: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").CalloutProps>, bpCard: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").CardProps>, drawer: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").DrawerProps>, editableText: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").EditableTextProps>, formGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").FormGroupProps>, hotkey: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").HotkeyProps>, hotkeys: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").HotkeysProps>, inputGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").InputGroupProps>, label: import("@xh/hoist/core").ElementFactory<React.AllHTMLAttributes<HTMLLabelElement> & React.RefAttributes<HTMLLabelElement>>, menu: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").MenuProps>, navbar: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").NavbarProps>, navbarHeading: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").NavbarHeadingProps>, navbarGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").NavbarGroupProps>, radioGroup: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").RadioGroupProps>, tabs: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TabsProps>, tab: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TabProps>, tag: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TagProps>, text: import("@xh/hoist/core").ElementFactory<import("@blueprintjs/core").TextProps>;
+/**
+ * Blueprint Dialog wrapped with transitions disabled. This is the standard way to create
+ * custom modal dialogs in Hoist apps - import from `@xh/hoist/kit/blueprint` rather than
+ * from Blueprint directly.
+ *
+ * Pair with a HoistModel that manages an observable `isOpen` property. The parent component
+ * renders the dialog factory alongside its other children - it shows/hides based on `isOpen`.
+ *
+ * See the desktop package README (`desktop/README.md#dialogs`) for the full usage pattern.
+ */
+export declare const dialog: import("@xh/hoist/core").ElementFactory<DialogProps>;

package/build/types/mobile/cmp/navigator/NavigatorModel.d.ts

@@ -2,6 +2,14 @@ import { HoistModel, RefreshMode, RenderMode } from '@xh/hoist/core';
 import { Swiper } from 'swiper/types';
 import '@xh/hoist/mobile/register';
 import { PageConfig, PageModel } from './PageModel';
+/**
+ * Configuration for a {@link NavigatorModel} - the primary stack-based navigation controller
+ * for mobile Hoist apps. Supports swipe-based page transitions, pull-to-refresh, and
+ * configurable render/refresh strategies.
+ *
+ * @see NavigatorModel
+ * @see PageConfig
+ */
 export interface NavigatorConfig {
     /** Configs for PageModels, representing all supported pages within this Navigator/App. */
     pages: PageConfig[];

package/build/types/mobile/cmp/navigator/PageModel.d.ts

@@ -1,6 +1,13 @@
 import { Content, HoistModel, HoistProps, RefreshMode, RenderMode } from '@xh/hoist/core';
 import '@xh/hoist/mobile/register';
 import { NavigatorModel } from './NavigatorModel';
+/**
+ * Configuration for a {@link PageModel} - a single page within a {@link NavigatorModel}.
+ * Passed as entries in the `pages` array of a {@link NavigatorConfig}.
+ *
+ * @see PageModel
+ * @see NavigatorConfig
+ */
 export interface PageConfig {
     /** Unique ID. Must match a configured Router5 route name. */
     id: string;

package/build/types/mobile/cmp/panel/DialogPanel.d.ts

@@ -10,7 +10,5 @@ export interface DialogPanelProps extends PanelProps {
  *
  * These views do not participate in navigation or routing, and are used for showing fullscreen
  * views outside of the Navigator / TabContainer context.
- *
- * @see FullscreenPanel for a true fullscreen, non-floating alternative.
  */
 export declare const DialogPanel: import("react").FC<DialogPanelProps>, dialogPanel: import("@xh/hoist/core").ElementFactory<DialogPanelProps>;

package/build/types/security/BaseOAuthClient.d.ts

@@ -2,6 +2,15 @@ import { HoistBase } from '@xh/hoist/core';
 import { Token } from '@xh/hoist/security/Token';
 import { AccessTokenSpec, TokenMap } from './Types';
 export type LoginMethod = 'REDIRECT' | 'POPUP';
+/**
+ * Base configuration shared by all OAuth client implementations. Extended by
+ * {@link MsalClientConfig} and {@link AuthZeroClientConfig} with provider-specific options.
+ *
+ * See the security package README (`security/README.md`) for authentication architecture
+ * and setup guidance.
+ *
+ * @see BaseOAuthClient
+ */
 export interface BaseOAuthClientConfig<S extends AccessTokenSpec> {
     /** Client ID (GUID) of your app registered with your Oauth provider. */
     clientId: string;

package/build/types/security/authzero/AuthZeroClient.d.ts

@@ -2,6 +2,12 @@ import type { Auth0ClientOptions } from '@auth0/auth0-spa-js';
 import { Token } from '@xh/hoist/security/Token';
 import { AccessTokenSpec, TokenMap } from '../Types';
 import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
+/**
+ * Configuration for an {@link AuthZeroClient} - the Auth0 OAuth client.
+ * Extends {@link BaseOAuthClientConfig} with Auth0-specific options.
+ *
+ * @see AuthZeroClient
+ */
 export interface AuthZeroClientConfig extends BaseOAuthClientConfig<AuthZeroTokenSpec> {
     /** Domain of your app registered with Auth0.  */
     domain: string;

package/build/types/security/msal/MsalClient.d.ts

@@ -4,6 +4,12 @@ import { PlainObject } from '@xh/hoist/core';
 import { Token } from '@xh/hoist/security/Token';
 import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
 import { AccessTokenSpec, TokenMap } from '../Types';
+/**
+ * Configuration for a {@link MsalClient} - the Microsoft Entra ID (Azure AD) OAuth client.
+ * Extends {@link BaseOAuthClientConfig} with MSAL-specific options.
+ *
+ * @see MsalClient
+ */
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
      * Authority for your organization's tenant: `https://login.microsoftonline.com/[tenantId]`.

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

@@ -1,6 +1,6 @@
 import { Awaitable, HoistService, LoadSpec, LoadSpecConfig, PlainObject, TrackOptions } from '@xh/hoist/core';
 import { HoistException } from '@xh/hoist/exception';
-import { Span } from '@xh/hoist/utils/telemetry';
+import { Span, SpanConfig } from '@xh/hoist/utils/telemetry';
 import { PromiseTimeoutSpec } from '@xh/hoist/promise';
 import { StatusCodes } from 'http-status-codes';
 import { IStringifyOptions } from 'qs';
@@ -12,8 +12,8 @@ export interface FetchServiceDefaults {
 /**
  * Service for making managed HTTP requests, both to the app's own Hoist server and to remote APIs.
  *
- * Typically accessed via `XH.fetchService` or the convenience methods on XH — `XH.fetch()`,
- * `XH.fetchJson()`, `XH.postJson()`, `XH.putJson()`, `XH.deleteJson()` — which delegate here.
+ * Typically accessed via `XH.fetchService` or the convenience methods on XH - `XH.fetch()`,
+ * `XH.fetchJson()`, `XH.postJson()`, `XH.putJson()`, `XH.deleteJson()` - which delegate here.
  *
  * Wraps the standard Fetch API with CORS enabled, credentials included, and redirects followed.
  * Provides JSON convenience methods (`fetchJson`, `postJson`, `putJson`, `patchJson`,
@@ -248,10 +248,12 @@ export interface FetchOptions {
      */
     track?: string | TrackOptions;
     /**
-     * If set, the fetch span created by TraceService will be parented under this span.
-     * Use to nest fetch calls under a business-level span.
+     * Parent span for this fetch request. Use to nest fetch calls under a business-level span.
+     *
+     * Accepts an existing Span instance, a SpanConfig, or a string span name. When a SpanConfig or
+     * string is provided, FetchService will create and manage the parent span internally.
      */
-    span?: Span;
+    span?: Span | SpanConfig | string;
     /**
      * Distributed trace ID for this request. Set automatically by FetchService
      * @internal
@@ -272,7 +274,8 @@ export interface FetchException extends HoistException {
     traceId: string;
     /**
      * True if exception resulted from the fetch being aborted by fetchService, or the application.
-     * @see FetchService.abort and FetchOptions.autoAbortKey.
+     * @see FetchService.abort
+     * @see FetchOptions.autoAbortKey
      */
     isFetchAborted: boolean;
 }

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

@@ -8,7 +8,7 @@ import { Span, SpanConfig } from '@xh/hoist/utils/telemetry';
  * end-to-end traces from user interaction through server processing and back.
  *
  * Controlled by the `xhTraceConfig` soft config. When disabled (the default), all
- * span-creation methods are no-ops — the wrapped function still executes normally.
+ * span-creation methods are no-ops - the wrapped function still executes normally.
  *
  * Completed spans are batched and exported to the Hoist server endpoint `xh/submitSpans`,
  * which relays them to the configured collector.
@@ -42,7 +42,10 @@ export declare class TraceService extends HoistService {
      * Create a new span, or return null if tracing is disabled.
      * Inherits the parent's `source` tag if not specified.
      *
-     * Note: sampling is handled server-side when spans are relayed to the collector.
+     * Sampling rules from `xhTraceConfig.sampleRules` are evaluated against the span's tags
+     * at creation time (head-based). Child spans inherit their parent's sampling decision.
+     * Unsampled spans may still be exported if they end in error and `alwaysSampleErrors` is
+     * enabled — see {@link exportSpan}.
      *
      * @param config - span name string, or a SpanConfig with name and optional tags.
      */
@@ -55,8 +58,20 @@ export declare class TraceService extends HoistService {
      */
     pushPendingAsync(): Promise<void>;
     private pushPendingBuffered;
+    /** Evaluate sampling rules against a span's tags. */
+    private shouldSample;
+    private getSampleRate;
+    /** For strings, simple glob matching: `*` = any, `foo*` = prefix, `*foo` = suffix, `*foo*` = contains. */
+    private matchesValue;
 }
 interface TraceConfig {
     enabled: boolean;
+    sampleRules?: SamplingRule[];
+    sampleRate?: number;
+    alwaysSampleErrors?: boolean;
+}
+interface SamplingRule {
+    match: Record<string, string>;
+    sampleRate: number;
 }
 export {};

package/build/types/utils/async/Timer.d.ts

@@ -54,6 +54,12 @@ export declare class Timer {
     private get timeoutMs();
     destroy(): void;
 }
+/**
+ * Configuration for a {@link Timer} - a managed interval that runs a function repeatedly
+ * with configurable delay, timeout, and app-config-driven intervals.
+ *
+ * @see Timer
+ */
 export interface TimerSpec {
     /**
      * Function to run.

package/build/types/utils/js/LangUtils.d.ts

@@ -121,7 +121,7 @@ export declare function mergeDeep<T, S1, S2>(object: T, source1: S1, source2: S2
 export declare function mergeDeep<T, S1, S2, S3>(object: T, source1: S1, source2: S2, source3: S3): T & S1 & S2 & S3;
 export declare function mergeDeep<T, S>(target: T, ...sources: S[]): T & S;
 /**
- * A string, or an object from which a name can be derived — via `displayName` (e.g. React
+ * A string, or an object from which a name can be derived - via `displayName` (e.g. React
  * components) or `constructor.name` (e.g. class instances). Used for logging and tracing.
  */
 export type NameSource = string | {

package/build/types/utils/js/TestUtils.d.ts

@@ -1,7 +1,7 @@
 import { HoistProps } from '@xh/hoist/core';
 /**
  * HTML attribute name used to tag elements with stable test identifiers. Use as a computed
- * property key on element specs — e.g. `{[TEST_ID]: 'my-grid'}` — to emit a `data-testid`
+ * property key on element specs - e.g. `{[TEST_ID]: 'my-grid'}` - to emit a `data-testid`
  * attribute that automated test drivers can locate reliably.
  */
 export declare const TEST_ID = "data-testid";

package/build/types/utils/react/index.d.ts

@@ -1,4 +1,3 @@
-export * from './ClassName';
 export * from './ReactUtils';
 export * from './LayoutPropUtils';
 export * from './ObservableRef';

package/build/types/utils/telemetry/Span.d.ts

@@ -17,7 +17,7 @@ export declare class Span {
     name: string;
     /** Epoch ms (Date.now()-based). */
     startTime: number;
-    /** Epoch ms — set when span ends. */
+    /** Epoch ms - set when span ends. */
     endTime: number;
     /** Duration in ms (endTime - startTime). */
     get duration(): number;
@@ -25,6 +25,8 @@ export declare class Span {
     status: SpanStatus;
     tags: PlainObject;
     events: SpanEvent[];
+    /** Whether this span was selected by client-side sampling rules. */
+    sampled: boolean;
     constructor(config: SpanConfig);
     /** End this span, recording status and computing duration. */
     end(status?: SpanStatus): void;
@@ -33,6 +35,13 @@ export declare class Span {
     /** Serialize for export to the server. */
     toJSON(): PlainObject;
 }
+/**
+ * Configuration for a {@link Span} - a lightweight trace span for distributed tracing.
+ * Create via {@link TraceService} rather than directly.
+ *
+ * @see Span
+ * @see TraceService
+ */
 export interface SpanConfig {
     name: string;
     kind?: SpanKind;
@@ -40,6 +49,7 @@ export interface SpanConfig {
     parent?: Span;
     startTime?: number;
     caller?: NameSource;
+    sampled?: boolean;
 }
 export interface SpanEvent {
     name: string;
@@ -52,7 +62,7 @@ export type SpanStatus = 'ok' | 'error' | 'unset';
  * Format a W3C traceparent header value.
  * @see https://www.w3.org/TR/trace-context/#traceparent-header
  */
-export declare function formatTraceparent(traceId: string, spanId: string): string;
+export declare function formatTraceparent(traceId: string, spanId: string, sampled?: boolean): string;
 /** Generate a 32-hex-char (128-bit) trace ID. */
 export declare function genTraceId(): string;
 /** Generate a 16-hex-char (64-bit) span ID. */

package/cmp/ag-grid/AgGrid.ts

@@ -29,27 +29,16 @@ 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 const [AgGrid, agGrid] = hoistCmp.withFactory<AgGridProps>({
     displayName: 'AgGrid',

package/cmp/ag-grid/AgGridModel.ts

@@ -25,6 +25,16 @@ import {
 } from 'lodash';
 import {GridSorter, 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;
 
@@ -79,12 +89,15 @@ export interface AgGridState {
 }
 
 /**
- * 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 class AgGridModel extends HoistModel {
     static AUTO_GROUP_COL_ID = 'ag-Grid-AutoColumn';

package/cmp/card/Card.ts

@@ -40,10 +40,15 @@ export interface CardProps<M extends CardModel = CardModel>
 }
 
 /**
- * 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 const [Card, card] = hoistCmp.withFactory<CardProps>({
     displayName: 'Card',

package/cmp/card/CardModel.ts

@@ -18,6 +18,13 @@ import {throwIf} from '@xh/hoist/utils/js';
 import {isNil} from 'lodash';
 import {action, observable} from 'mobx';
 
+/**
+ * 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;
@@ -37,8 +44,14 @@ export interface CardPersistState {
 }
 
 /**
- * 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 class CardModel extends HoistModel implements Persistable<CardPersistState> {
     declare config: CardModelConfig;

package/cmp/chart/Chart.ts

@@ -52,8 +52,8 @@ export interface ChartProps<M extends ChartModel = ChartModel>
 
 /**
  * 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 const [Chart, chart] = hoistCmp.withFactory<ChartProps>({
     displayName: 'Chart',

package/cmp/chart/ChartModel.ts

@@ -33,7 +33,17 @@ export interface ChartModelDefaults {
 }
 
 /**
- * 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 class ChartModel extends HoistModel {
     /** App-level defaults for ChartModel. Instance config takes precedence. */

package/cmp/dataview/DataView.ts

@@ -39,8 +39,10 @@ export interface DataViewProps<M extends DataViewModel = DataViewModel>
 }
 
 /**
- * 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 const [DataView, dataView] = hoistCmp.withFactory<DataViewProps>({
     displayName: 'DataView',