@xh/hoist 86.3.0 → 86.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 86.4.0 - 2026-07-15
+
+### 🎁 New Features
+
+* Added `PrefService.isSet()` to report whether the current user has an explicit value on file for a
+  preference vs. receiving its server-side default - a distinction that cannot be reliably inferred
+  by comparing the value to the default. Requires a hoist-core version that emits the backing
+  `isSet` flag; against older servers all prefs report as unset.
+
+### 🐞 Bug Fixes
+
+* `PrefService.unset()` now performs a true server-side unset, clearing the user's stored value so
+  the preference reverts to its (possibly changing) default and `isSet()` reports `false`.
+  Previously it persisted the current default as an explicit user value. Falls back to the legacy
+  behavior against hoist-core versions that predate the `xh/unsetPrefs` endpoint.
+* Fixed `FilterChooser` popover mode to render an opaque background when expanded.
+
 ## 86.3.0 - 2026-07-10
 
 ### 🎁 New Features

package/admin/AppModel.ts

@@ -9,7 +9,9 @@ import {TabConfig, TabContainerModel} from '@xh/hoist/cmp/tab';
 import {ViewManagerModel} from '@xh/hoist/cmp/viewmanager';
 import {HoistAppModel, HoistRoute, InitContext, XH} from '@xh/hoist/core';
 import {Icon} from '@xh/hoist/icon';
+import {SECONDS} from '@xh/hoist/utils/datetime';
 import {without} from 'lodash';
+import {RoleModuleConfig} from './tabs/userData/roles/Types';
 import {activityTrackingPanel} from './tabs/activity/tracking/ActivityTrackingPanel';
 import {clientsPanel} from './tabs/clients/ClientsPanel';
 import {monitorTab} from './tabs/monitor/MonitorTab';
@@ -27,6 +29,9 @@ export class AppModel extends HoistAppModel {
 
     viewManagerModels: Record<string, ViewManagerModel> = {};
 
+    /** Role-module config, loaded once at init and shared with the Roles tab. */
+    roleModuleConfig: RoleModuleConfig = null;
+
     static get readonly() {
         return !XH.getUser().isHoistAdmin;
     }
@@ -34,16 +39,18 @@ export class AppModel extends HoistAppModel {
     constructor() {
         super();
 
-        this.tabModel = new TabContainerModel({
-            route: 'default',
-            tabs: this.createTabs()
-        });
-
         // Enable managed autosize mode across Hoist Admin console grids.
         GridModel.defaults.autosizeMode = 'managed';
     }
 
     override async initAsync(ctx: InitContext) {
+        await this.loadRoleModuleConfigAsync(ctx);
+
+        this.tabModel = new TabContainerModel({
+            route: 'default',
+            tabs: this.createTabs()
+        });
+
         await this.initViewManagerModelsAsync(ctx);
         await super.initAsync(ctx);
     }
@@ -122,7 +129,8 @@ export class AppModel extends HoistAppModel {
     }
 
     createTabs(): TabConfig[] {
-        const conf = XH.getConf('xhAdminAppConfig', {});
+        const conf = XH.getConf('xhAdminAppConfig', {}),
+            rolesEnabled = this.roleModuleConfig?.enabled ?? false;
 
         return [
             {
@@ -159,6 +167,7 @@ export class AppModel extends HoistAppModel {
             },
             {
                 id: 'userData',
+                title: rolesEnabled ? 'User Data & Roles' : 'User Data',
                 icon: Icon.users(),
                 content: {
                     refreshMode: 'onShowAlways',
@@ -172,7 +181,8 @@ export class AppModel extends HoistAppModel {
                         {
                             id: 'roles',
                             icon: Icon.idBadge(),
-                            content: rolePanel
+                            content: rolePanel,
+                            omit: !rolesEnabled
                         },
                         {
                             id: 'prefs',
@@ -219,4 +229,22 @@ export class AppModel extends HoistAppModel {
             ctx
         );
     }
+
+    //----------------
+    // Implementation
+    //----------------
+    private async loadRoleModuleConfigAsync(ctx: InitContext) {
+        // Load role config up-front to title/show the Roles tab (see createTabs).
+        // Never block startup if it can't load - the tab defaults to hidden.
+        try {
+            this.roleModuleConfig = await this.runner(ctx)
+                .span('loadRoleModuleConfig')
+                .fetchJson({url: 'roleAdmin/config', timeout: 10 * SECONDS});
+        } catch (e) {
+            XH.handleException(e, {
+                message: 'Unable to load roles configuration',
+                alertType: 'toast'
+            });
+        }
+    }
 }

package/admin/tabs/userData/roles/RoleModel.ts

@@ -4,12 +4,13 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
+import {getAppModel} from '@xh/hoist/admin/AdminUtils';
 import {RecategorizeDialogModel} from '@xh/hoist/admin/tabs/userData/roles/recategorize/RecategorizeDialogModel';
 import {FilterChooserModel} from '@xh/hoist/cmp/filter';
 import {GridModel, tagsRenderer, TreeStyle} from '@xh/hoist/cmp/grid';
 import * as Col from '@xh/hoist/cmp/grid/columns';
 import {fragment, p} from '@xh/hoist/cmp/layout';
-import {CallContext, HoistModel, LoadSpec, managed, XH} from '@xh/hoist/core';
+import {HoistModel, LoadSpec, managed, XH} from '@xh/hoist/core';
 import {RecordActionSpec} from '@xh/hoist/data';
 import {actionCol, calcActionColWidth} from '@xh/hoist/desktop/cmp/grid';
 import {Icon} from '@xh/hoist/icon';
@@ -39,10 +40,14 @@ export class RoleModel extends HoistModel {
     @managed recategorizeDialogModel = new RecategorizeDialogModel(this);
 
     @observable.ref allRoles: HoistRole[] = [];
-    @observable.ref moduleConfig: RoleModuleConfig;
 
     @bindable showInGroups = true;
 
+    /** Role-module config - loaded at init. */
+    get moduleConfig(): RoleModuleConfig {
+        return getAppModel().roleModuleConfig;
+    }
+
     get readonly() {
         return !XH.getUser().isHoistRoleManager;
     }
@@ -56,6 +61,10 @@ export class RoleModel extends HoistModel {
     constructor() {
         super();
         makeObservable(this);
+
+        this.gridModel = this.createGridModel();
+        this.filterChooserModel = this.createFilterChooserModel();
+
         this.addReaction({
             track: () => this.showInGroups,
             run: showInGroups => {
@@ -74,9 +83,6 @@ export class RoleModel extends HoistModel {
         return this.runner({loadSpec})
             .span('list')
             .run(async ctx => {
-                await this.ensureInitializedAsync(ctx);
-                if (!this.moduleConfig.enabled) return;
-
                 const {data} = await XH.fetchJson({url: 'roleAdmin/list'}, ctx);
                 if (loadSpec.isStale) return;
 
@@ -233,19 +239,6 @@ export class RoleModel extends HoistModel {
         gridModel.autosizeAsync({includeCollapsedChildren: true});
     }
 
-    private async ensureInitializedAsync(ctx: CallContext) {
-        if (this.moduleConfig) return;
-
-        const config = await this.runner(ctx).fetchJson({url: 'roleAdmin/config'});
-        runInAction(() => {
-            this.moduleConfig = config;
-            if (config.enabled) {
-                this.gridModel = this.createGridModel();
-                this.filterChooserModel = this.createFilterChooserModel();
-            }
-        });
-    }
-
     private processRolesFromServer(roles: Partial<HoistRole>[]): HoistRole[] {
         return roles.map(role => {
             const membersByType = mapValues(groupBy(role.members, 'type'), members =>

package/admin/tabs/userData/roles/RolePanel.ts

@@ -9,7 +9,6 @@ import {grid} from '@xh/hoist/cmp/grid';
 import {fragment, hframe, vframe} from '@xh/hoist/cmp/layout';
 import {creates, hoistCmp} from '@xh/hoist/core';
 import {button, colChooserButton} from '@xh/hoist/desktop/cmp/button';
-import {errorMessage} from '@xh/hoist/cmp/error';
 import {filterChooser} from '@xh/hoist/desktop/cmp/filter';
 import {switchInput} from '@xh/hoist/desktop/cmp/input';
 import {panel} from '@xh/hoist/desktop/cmp/panel';
@@ -25,12 +24,6 @@ export const rolePanel = hoistCmp.factory({
     model: creates(RoleModel),
 
     render({className, model}) {
-        const {moduleConfig} = model;
-        if (!moduleConfig) return null;
-        if (!moduleConfig.enabled) {
-            return errorMessage({error: 'Default Role Module not enabled.'});
-        }
-
         const {gridModel, readonly} = model;
         return fragment(
             panel({

package/build/types/admin/AppModel.d.ts

@@ -1,9 +1,12 @@
 import { TabConfig, TabContainerModel } from '@xh/hoist/cmp/tab';
 import { ViewManagerModel } from '@xh/hoist/cmp/viewmanager';
 import { HoistAppModel, HoistRoute, InitContext } from '@xh/hoist/core';
+import { RoleModuleConfig } from './tabs/userData/roles/Types';
 export declare class AppModel extends HoistAppModel {
     tabModel: TabContainerModel;
     viewManagerModels: Record<string, ViewManagerModel>;
+    /** Role-module config, loaded once at init and shared with the Roles tab. */
+    roleModuleConfig: RoleModuleConfig;
     static get readonly(): boolean;
     constructor();
     initAsync(ctx: InitContext): Promise<void>;
@@ -15,4 +18,5 @@ export declare class AppModel extends HoistAppModel {
     openPrimaryApp(): void;
     getPrimaryAppCode(): string;
     initViewManagerModelsAsync(ctx: InitContext): Promise<void>;
+    private loadRoleModuleConfigAsync;
 }

package/build/types/admin/tabs/userData/roles/RoleModel.d.ts

@@ -19,8 +19,9 @@ export declare class RoleModel extends HoistModel {
     readonly roleEditorModel: RoleEditorModel;
     recategorizeDialogModel: RecategorizeDialogModel;
     allRoles: HoistRole[];
-    moduleConfig: RoleModuleConfig;
     showInGroups: boolean;
+    /** Role-module config - loaded at init. */
+    get moduleConfig(): RoleModuleConfig;
     get readonly(): boolean;
     get selectedRole(): HoistRole;
     constructor();
@@ -36,7 +37,6 @@ export declare class RoleModel extends HoistModel {
     private deleteAction;
     private groupByAction;
     private displayRoles;
-    private ensureInitializedAsync;
     private processRolesFromServer;
     private processRolesForTreeGrid;
     private createGridModel;

package/build/types/data/Store.d.ts

@@ -267,8 +267,9 @@ export declare class Store extends HoistBase implements FilterBindTarget, Filter
      * Add new Records to this Store in a local, uncommitted state - i.e. with data that has yet to
      * be persisted back to, or sourced from, the server or other data source of record.
      *
-     * Note that data objects passed to this method must include a unique ID - callers can generate
-     * one with `XH.genId()` if no natural ID can be produced locally on the client.
+     * Note that data objects passed to this method must include a literal `id` property - this
+     * method does *not* run the Store's `idSpec` function. Callers can generate an id with
+     * `XH.genId()` if no natural ID can be produced locally on the client.
      *
      * For StoreRecord additions that originate from the server, call `updateData()` instead.
      *

package/build/types/kit/swiper/index.d.ts

@@ -27,8 +27,8 @@ export declare const swiper: import("@xh/hoist/core").ElementFactory<import("rea
     onScrollbarDragStart?: (swiper: import("swiper/types").Swiper, event: MouseEvent | TouchEvent | PointerEvent) => void;
     onScrollbarDragMove?: (swiper: import("swiper/types").Swiper, event: MouseEvent | TouchEvent | PointerEvent) => void;
     onScrollbarDragEnd?: (swiper: import("swiper/types").Swiper, event: MouseEvent | TouchEvent | PointerEvent) => void;
-    onVirtualUpdate?: (swiper: import("swiper/types").Swiper) => void;
     onZoomChange?: (swiper: import("swiper/types").Swiper, scale: number, imageEl: HTMLElement, slideEl: HTMLElement) => void;
+    onVirtualUpdate?: (swiper: import("swiper/types").Swiper) => void;
     onInit?: (swiper: import("swiper/types").Swiper) => any;
     onBeforeDestroy?: (swiper: import("swiper/types").Swiper) => void;
     onSlidesUpdated?: (swiper: import("swiper/types").Swiper) => void;

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

@@ -25,6 +25,13 @@ export declare class PrefService extends HoistService {
      * Check to see if a given preference has been *defined*.
      */
     hasKey(key: string): boolean;
+    /**
+     * Check whether the current user has an explicit value on file for the given preference, vs.
+     * receiving the preference's server-side default value.
+     *
+     * @param key - unique key used to identify the pref.
+     */
+    isSet(key: string): boolean;
     /**
      * Get the value for a given key, either the user-specific value (if set) or the default.
      * Typically accessed via the convenience alias {@link XH.getPref}.
@@ -47,7 +54,10 @@ export declare class PrefService extends HoistService {
      */
     set(key: string, value: any): void;
     /**
-     * Restore a preference to its default value.
+     * Restore a preference to its default value, clearing the user's explicit value on the server.
+     *
+     * Unlike `set()`, this clears the user's explicit value rather than persisting the default as
+     * one - so {@link isSet} will report `false` afterwards. Saved asynchronously (see `set()`).
      */
     unset(key: string): void;
     /**
@@ -66,6 +76,7 @@ export declare class PrefService extends HoistService {
     pushPendingAsync(): Promise<void>;
     private pushPendingBuffered;
     private loadPrefsAsync;
+    private ensureKeyExists;
     private validateBeforeSet;
     private valueIsOfType;
 }

package/build/types/utils/datetime/LocalDate.d.ts

@@ -9,6 +9,15 @@ import { Moment, MomentInput } from 'moment';
  * For efficiency and to enable strict equality checks, instances of this class are memoized:
  * only a single version of the object will be created and returned for each calendar day,
  * as long as the caller uses one of the *public factory methods*, which they always should!
+ *
+ * Instances serialize directly to their ISO date string (e.g. '2024-01-15') via built-in
+ * `toString()`, `valueOf()`, and `toJSON()` overrides. This means a LocalDate can be passed
+ * as-is within the params or body of a `FetchService` request (or any `JSON.stringify()` call)
+ * and will serialize as expected - prefer this over calling `toString()` or `format()` yourself.
+ *
+ * Instances also support natural comparison: because they are memoized, `===` tests whether two
+ * references are the same calendar day, while `valueOf()` returning the (lexically sortable) ISO
+ * string means the relational operators `<`, `>`, `<=`, `>=` order instances chronologically.
  */
 export declare class LocalDate {
     static readonly VALID_UNITS: Set<LocalDateUnit>;
@@ -33,7 +42,11 @@ export declare class LocalDate {
      * @param val - any string, timestamp, or date parsable by moment.js.
      */
     static from(val: MomentInput | LocalDate): LocalDate;
-    /** LocalDate representing the current day. */
+    /**
+     * LocalDate representing the current day in the browser's local time zone.
+     * See `currentAppDay()` / `currentServerDay()` to resolve "today" in the app or server zone,
+     * which can differ from the browser for users in another region.
+     */
     static today(): LocalDate;
     /** LocalDate representing the current day in the App TimeZone */
     static currentAppDay(): LocalDate;
@@ -46,9 +59,17 @@ export declare class LocalDate {
     /** Is the input value a local Date? */
     static isLocalDate(val: any): boolean;
     get isoString(): string;
+    /** JS `Date` for this day at midnight in the browser's local time zone. Fresh instance per call. */
     get date(): Date;
+    /** A mutable moment.js clone - safe to modify without affecting this (immutable) instance. */
     get moment(): Moment;
+    /** Epoch millis for this day at midnight in the browser's local time zone. */
     get timestamp(): number;
+    /**
+     * Format this date using moment.js format tokens, primarily for display.
+     * Note: to send a LocalDate to the server, pass the instance directly rather than a formatted
+     * string - it serializes to an ISO date on its own (see class-level docs).
+     */
     format(...args: any[]): string;
     dayOfWeek(): string;
     get isToday(): boolean;
@@ -83,6 +104,7 @@ export declare class LocalDate {
     currentOrNextWeekday(): LocalDate;
     /** The same date if already a weekday, or the previous weekday. */
     currentOrPreviousWeekday(): LocalDate;
+    /** Difference between this date and `other` in the given unit; positive when this is later. */
     diff(other: LocalDate, unit?: LocalDateUnit): number;
     /** @internal - use one of the static factory methods instead. */
     private constructor();

package/data/Store.ts

@@ -559,8 +559,9 @@ export class Store
      * Add new Records to this Store in a local, uncommitted state - i.e. with data that has yet to
      * be persisted back to, or sourced from, the server or other data source of record.
      *
-     * Note that data objects passed to this method must include a unique ID - callers can generate
-     * one with `XH.genId()` if no natural ID can be produced locally on the client.
+     * Note that data objects passed to this method must include a literal `id` property - this
+     * method does *not* run the Store's `idSpec` function. Callers can generate an id with
+     * `XH.genId()` if no natural ID can be produced locally on the client.
      *
      * For StoreRecord additions that originate from the server, call `updateData()` instead.
      *

package/desktop/cmp/filter/FilterChooser.scss

@@ -47,8 +47,9 @@
       flex: 1;
     }
 
+    // Opaque bg to occlude the trigger and page beneath (--xh-input-bg is translucent in dark mode).
     .bp6-popover-content {
-      background: transparent;
+      background: var(--xh-bg);
     }
 
     .xh-select__value-container--is-multi {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "86.3.0",
+  "version": "86.4.0",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@auth0/auth0-spa-js": "~2.23.0",
-    "@azure/msal-browser": "~5.16.0",
+    "@azure/msal-browser": "~5.17.0",
     "@blueprintjs/core": "^6.3.2",
     "@blueprintjs/datetime": "^6.0.6",
     "@codemirror/commands": "^6.10.3",

package/svc/PrefService.ts

@@ -30,9 +30,8 @@ export class PrefService extends HoistService {
     override telemetryPrefix = 'xh.client.prefs';
 
     static instance: PrefService;
-
-    private _data = {};
-    private _updates = {};
+    private _data: Record<string, PrefEntry> = {};
+    private _updates: Record<string, any> = {}; // undefined indicates unset
 
     override async initAsync(ctx: InitContext) {
         // Flush on page teardown while the page is still alive.
@@ -52,6 +51,17 @@ export class PrefService extends HoistService {
         return this._data.hasOwnProperty(key);
     }
 
+    /**
+     * Check whether the current user has an explicit value on file for the given preference, vs.
+     * receiving the preference's server-side default value.
+     *
+     * @param key - unique key used to identify the pref.
+     */
+    isSet(key: string): boolean {
+        this.ensureKeyExists(key);
+        return !!this._data[key].isSet;
+    }
+
     /**
      * Get the value for a given key, either the user-specific value (if set) or the default.
      * Typically accessed via the convenience alias {@link XH.getPref}.
@@ -91,7 +101,9 @@ export class PrefService extends HoistService {
 
         // Change local value to sanitized copy and fire.
         value = deepFreeze(cloneDeep(value));
-        this._data[key].value = value;
+        const pref = this._data[key];
+        pref.value = value;
+        pref.isSet = true;
 
         // Schedule serialization to storage
         this._updates[key] = value;
@@ -99,11 +111,22 @@ export class PrefService extends HoistService {
     }
 
     /**
-     * Restore a preference to its default value.
+     * Restore a preference to its default value, clearing the user's explicit value on the server.
+     *
+     * Unlike `set()`, this clears the user's explicit value rather than persisting the default as
+     * one - so {@link isSet} will report `false` afterwards. Saved asynchronously (see `set()`).
      */
     unset(key: string) {
-        // TODO: round-trip this to the server as a proper unset?
-        this.set(key, this._data[key]?.defaultValue);
+        this.ensureKeyExists(key);
+        const pref = this._data[key];
+        if (!pref.isSet && isEqual(pref.value, pref.defaultValue)) return;
+
+        pref.value = pref.defaultValue;
+        pref.isSet = false;
+
+        // Schedule serialization to storage
+        this._updates[key] = undefined;
+        this.pushPendingBuffered();
     }
 
     /**
@@ -131,18 +154,44 @@ export class PrefService extends HoistService {
         // Clear synchronously with the capture, so overlapping flushes cannot post twice.
         this._updates = {};
 
+        // Partition into value updates and unsets.
+        // On a core that predates unset support, fall back to persisting default
+        const setPrefs = {},
+            unsetKeys = [];
+        forEach(updates, (value, key) => {
+            const pref = this._data[key];
+            if (value !== undefined) {
+                setPrefs[key] = value;
+            } else if (pref.hasOwnProperty('isSet')) {
+                unsetKeys.push(key);
+            } else {
+                setPrefs[key] = pref.defaultValue;
+            }
+        });
+
         await this.runner()
-            .span('set')
-            .run(ctx =>
-                terminationSafePostJson(
-                    {
-                        url: 'xh/setPrefs',
-                        body: updates,
-                        params: {clientUsername: XH.getUsername()}
-                    },
-                    ctx
-                )
-            );
+            .span('update')
+            .run(async ctx => {
+                const clientUsername = XH.getUsername(),
+                    tasks = [];
+                if (!isEmpty(setPrefs)) {
+                    tasks.push(
+                        terminationSafePostJson(
+                            {url: 'xh/setPrefs', body: setPrefs, params: {clientUsername}},
+                            ctx
+                        )
+                    );
+                }
+                if (!isEmpty(unsetKeys)) {
+                    tasks.push(
+                        terminationSafePostJson(
+                            {url: 'xh/unsetPrefs', body: unsetKeys, params: {clientUsername}},
+                            ctx
+                        )
+                    );
+                }
+                await Promise.all(tasks);
+            });
     }
 
     //-------------------
@@ -172,9 +221,13 @@ export class PrefService extends HoistService {
             });
     }
 
-    private validateBeforeSet(key, value) {
+    private ensureKeyExists(key: string) {
+        throwIf(!this.hasKey(key), `Preference key not found: '${key}'`);
+    }
+
+    private validateBeforeSet(key: string, value: any) {
+        this.ensureKeyExists(key);
         const pref = this._data[key];
-        throwIf(!pref, `Cannot set preference ${key}: not found`);
         throwIf(value === undefined, `Cannot set preference ${key}: value not defined`);
         throwIf(
             !this.valueIsOfType(value, pref.type),
@@ -201,3 +254,10 @@ export class PrefService extends HoistService {
         }
     }
 }
+
+interface PrefEntry {
+    type: string;
+    value: any;
+    defaultValue: any;
+    isSet: boolean;
+}

package/svc/README.md

@@ -186,6 +186,12 @@ XH.setPref('gridPageSize', 100);
 
 // Immediate save - no alias, access service directly
 await XH.prefService.pushAsync('criticalPref', value);
+
+// Distinguish an explicit user value from the server-side default
+if (XH.prefService.isSet('gridPageSize')) { /* user has customized this */ }
+
+// Clear the user's value, reverting to the default (real server-side unset)
+XH.prefService.unset('gridPageSize');
 ```
 
 Preferences are type-validated against server-defined types: `string`, `int`, `long`, `double`,

package/utils/datetime/LocalDate.ts

@@ -18,6 +18,15 @@ import moment, {Moment, MomentInput} from 'moment';
  * For efficiency and to enable strict equality checks, instances of this class are memoized:
  * only a single version of the object will be created and returned for each calendar day,
  * as long as the caller uses one of the *public factory methods*, which they always should!
+ *
+ * Instances serialize directly to their ISO date string (e.g. '2024-01-15') via built-in
+ * `toString()`, `valueOf()`, and `toJSON()` overrides. This means a LocalDate can be passed
+ * as-is within the params or body of a `FetchService` request (or any `JSON.stringify()` call)
+ * and will serialize as expected - prefer this over calling `toString()` or `format()` yourself.
+ *
+ * Instances also support natural comparison: because they are memoized, `===` tests whether two
+ * references are the same calendar day, while `valueOf()` returning the (lexically sortable) ISO
+ * string means the relational operators `<`, `>`, `<=`, `>=` order instances chronologically.
  */
 export class LocalDate {
     static readonly VALID_UNITS: Set<LocalDateUnit> = new Set([
@@ -77,7 +86,11 @@ export class LocalDate {
         return this.get(m.format('YYYY-MM-DD'));
     }
 
-    /** LocalDate representing the current day. */
+    /**
+     * LocalDate representing the current day in the browser's local time zone.
+     * See `currentAppDay()` / `currentServerDay()` to resolve "today" in the app or server zone,
+     * which can differ from the browser for users in another region.
+     */
     static today(): LocalDate {
         return this.from(moment());
     }
@@ -120,18 +133,26 @@ export class LocalDate {
         return this._isoString;
     }
 
+    /** JS `Date` for this day at midnight in the browser's local time zone. Fresh instance per call. */
     get date(): Date {
         return new Date(this.timestamp);
     }
 
+    /** A mutable moment.js clone - safe to modify without affecting this (immutable) instance. */
     get moment(): Moment {
         return this._moment.clone();
     }
 
+    /** Epoch millis for this day at midnight in the browser's local time zone. */
     get timestamp(): number {
         return this._date.getTime();
     }
 
+    /**
+     * Format this date using moment.js format tokens, primarily for display.
+     * Note: to send a LocalDate to the server, pass the instance directly rather than a formatted
+     * string - it serializes to an ISO date on its own (see class-level docs).
+     */
     format(...args): string {
         return this._moment.format(...args);
     }
@@ -186,6 +207,7 @@ export class LocalDate {
         return this._isoString;
     }
 
+    // Returns the ISO string (not a number) so the relational operators sort instances by date.
     valueOf(): string {
         return this._isoString;
     }
@@ -319,6 +341,7 @@ export class LocalDate {
         return this.isWeekday ? this : this.previousWeekday();
     }
 
+    /** Difference between this date and `other` in the given unit; positive when this is later. */
     diff(other: LocalDate, unit: LocalDateUnit = 'days'): number {
         this.ensureUnitValid(unit);
         return this._moment.diff(other._moment, unit);