@xh/hoist 70.0.0-SNAPSHOT.1731083521069 → 70.0.0-SNAPSHOT.1731623470295

package/svc/GridAutosizeService.ts

@@ -5,12 +5,12 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 
+import {GridAutosizeOptions, GridModel} from '@xh/hoist/cmp/grid';
 import {HoistService} from '@xh/hoist/core';
-import {isFinite, map, sum, compact, sortBy, isEmpty} from 'lodash';
+import {StoreRecord} from '@xh/hoist/data';
 import {runInAction} from '@xh/hoist/mobx';
-import {GridModel, GridAutosizeOptions} from '@xh/hoist/cmp/grid';
+import {compact, isEmpty, isFinite, map, sortBy, sum} from 'lodash';
 import {ColumnWidthCalculator} from '../cmp/grid/impl/ColumnWidthCalculator';
-import {StoreRecord} from '@xh/hoist/data';
 
 /**
  * Sets appropriate column widths for a grid based on its contents. Generally seeks to make columns
@@ -42,39 +42,56 @@ export class GridAutosizeService extends HoistService {
         await gridModel.whenReadyAsync();
         if (!gridModel.isReady) return;
 
-        // 1) Check columns exist
+        // If not in MANAGED mode, report this change as a manual resize via updated state set on
+        // gridModel, as if the user had resized each column to fit. It is only in managed mode that
+        // we are truly deferring to autosize. Otherwise we should persist the widths we calculate.
+        // (The user has autosized manually to get col widths as desired - don't then forget them!)
+        const asManuallySized = options.mode !== 'managed';
+
+        // Check columns exist.
         colIds = colIds.filter(id => gridModel.getColumn(id));
         if (isEmpty(colIds)) return;
 
-        // 2) Ensure order of passed colIds matches the current GridModel.columnState.
+        // Ensure order of passed colIds matches the current GridModel.columnState.
         // This is to prevent changing the column order when applying column state changes
         colIds = sortBy(colIds, id => gridModel.columnState.findIndex(col => col.colId === id));
 
-        // 3) Perform computation.  This is async and expensive, and may become obsolete
+        // Perform computation. This is async and expensive, and may become obsolete.
         const records = this.gatherRecordsToBeSized(gridModel, options),
             requiredWidths = await this.calcRequiredWidthsAsync(
                 gridModel,
                 colIds,
                 records,
-                options
+                options,
+                asManuallySized
             );
 
         if (!requiredWidths) {
-            this.logDebug('Autosize aborted, grid data is obsolete.');
+            this.logDebug(
+                'Autosize aborted, grid data has changed since autosize operation began.'
+            );
             return;
         }
 
         runInAction(() => {
-            // 4) Set columns to their required widths.
+            // Apply calculated widths to grid.
             gridModel.applyColumnStateChanges(requiredWidths);
-            this.logDebug(`Auto-sized columns`, `${records.length} records`, requiredWidths);
+            this.logDebug(
+                `Auto-sized ${requiredWidths.length} columns`,
+                `${records.length} records`
+            );
 
-            // 5) Grow columns to fill any remaining space, if enabled.
+            // Optionally grow columns to fill any remaining space, if enabled.
             const {fillMode} = options;
             if (fillMode && fillMode !== 'none') {
-                const fillWidths = this.calcFillWidths(gridModel, colIds, fillMode);
+                const fillWidths = this.calcFillWidths(
+                    gridModel,
+                    colIds,
+                    fillMode,
+                    asManuallySized
+                );
                 gridModel.applyColumnStateChanges(fillWidths);
-                this.logDebug('Auto-sized columns using fillMode', fillWidths);
+                this.logDebug(`Auto-sized ${fillWidths.length} columns using fillMode`);
             }
         });
     }
@@ -86,10 +103,11 @@ export class GridAutosizeService extends HoistService {
         gridModel: GridModel,
         colIds: string[],
         records: StoreRecord[],
-        options: GridAutosizeOptions
-    ): Promise<{coldId: string; width: number}[]> {
+        options: GridAutosizeOptions,
+        manuallySized: boolean
+    ): Promise<ColWidthSpec[]> {
         const startRecords = gridModel.store._filtered,
-            ret = [];
+            ret: ColWidthSpec[] = [];
 
         for (const colId of colIds) {
             const width = await this._columnWidthCalculator.calcWidthAsync(
@@ -98,7 +116,7 @@ export class GridAutosizeService extends HoistService {
                 colId,
                 options
             );
-            if (isFinite(width)) ret.push({colId, width});
+            if (isFinite(width)) ret.push({colId, width, manuallySized});
 
             // Bail out if GridModel has moved on to new data.
             if (startRecords !== gridModel.store._filtered) return null;
@@ -145,14 +163,13 @@ export class GridAutosizeService extends HoistService {
         return ret;
     }
 
-    /**
-     * Calculate the increased size of columns to fill any remaining space.
-     */
+    // Calculate the increased size of columns to fill any remaining space.
     private calcFillWidths(
         gridModel: GridModel,
         colIds: string[],
-        fillMode: string
-    ): {colId: string; width: number}[] {
+        fillMode: string,
+        manuallySized: boolean
+    ): ColWidthSpec[] {
         if (gridModel.getVisibleLeafColumns().some(it => it.flex)) {
             return [];
         }
@@ -172,23 +189,27 @@ export class GridAutosizeService extends HoistService {
         }
 
         // 2) Get remaining space to be filled
-        const fillState = this.getFillState(gridModel, colIds),
-            remaining = available - fillState.total;
+        const {total, colFillSpecs} = this.getFillState(gridModel, colIds),
+            remaining = available - total;
         if (remaining <= 0) return [];
 
         // 3) Distribute remaining space according to fill mode
         switch (fillMode) {
             case 'all':
-                return this.fillEvenly(fillState.columns, remaining);
+                return this.fillEvenly(colFillSpecs, remaining, manuallySized);
             case 'left':
-                return this.fillSequentially(fillState.columns, remaining);
+                return this.fillSequentially(colFillSpecs, remaining, manuallySized);
             case 'right':
-                return this.fillSequentially(fillState.columns.reverse(), remaining);
+                return this.fillSequentially(colFillSpecs.reverse(), remaining, manuallySized);
         }
     }
 
     // Divide the remaining space evenly amongst columns, while respecting their maxWidths.
-    private fillEvenly(columns, remaining) {
+    private fillEvenly(
+        columns: ColFillSpec[],
+        remaining: number,
+        manuallySized: boolean
+    ): ColWidthSpec[] {
         const ret = {};
 
         while (remaining > 0) {
@@ -215,20 +236,24 @@ export class GridAutosizeService extends HoistService {
         }
 
         return map(ret, (width, colId) => {
-            return {width, colId};
+            return {width, colId, manuallySized};
         });
     }
 
     // Divide the remaining space across columns in order, while respecting their maxWidths.
-    private fillSequentially(columns, remaining) {
-        const ret = [];
+    private fillSequentially(
+        columns: ColFillSpec[],
+        remaining: number,
+        manuallySized: boolean
+    ): ColWidthSpec[] {
+        const ret: ColWidthSpec[] = [];
         for (const col of columns) {
             const {colId, maxWidth, width} = col,
                 extraWidth = isFinite(maxWidth) ? Math.min(maxWidth - width, remaining) : remaining;
 
             if (extraWidth > 0) {
                 remaining -= extraWidth;
-                ret.push({colId, width: width + extraWidth});
+                ret.push({colId, width: width + extraWidth, manuallySized});
             }
 
             if (remaining <= 0) break;
@@ -236,16 +261,16 @@ export class GridAutosizeService extends HoistService {
         return ret;
     }
 
-    private getFillState(gridModel, colIds) {
+    private getFillState(gridModel: GridModel, colIds: string[]) {
         return {
             total: this.getTotalColumnWidth(gridModel),
-            columns: compact(colIds.map(colId => this.getColumnFillState(gridModel, colId)))
+            colFillSpecs: compact(colIds.map(colId => this.getColFillSpec(gridModel, colId)))
         };
     }
 
     // Returns an array of column state representations,
     // suitable for use by the column fill algorithms.
-    private getColumnFillState(gridModel, colId) {
+    private getColFillSpec(gridModel: GridModel, colId: string): ColFillSpec {
         const column = gridModel.getColumn(colId),
             colState = gridModel.getStateForColumn(colId);
 
@@ -259,8 +284,20 @@ export class GridAutosizeService extends HoistService {
     }
 
     // Returns the total combined width of visible columns.
-    private getTotalColumnWidth(gridModel) {
+    private getTotalColumnWidth(gridModel: GridModel): number {
         const widths = gridModel.columnState.filter(it => !it.hidden).map(it => it.width);
         return sum(widths);
     }
 }
+
+interface ColWidthSpec {
+    colId: string;
+    width: number;
+    manuallySized: boolean;
+}
+
+interface ColFillSpec {
+    colId: string;
+    width: number;
+    maxWidth: number;
+}

package/svc/JsonBlobService.ts

@@ -4,77 +4,110 @@
  *
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
-import {XH, HoistService} from '@xh/hoist/core';
+import {HoistService, LoadSpec, PlainObject, XH} from '@xh/hoist/core';
+import {pickBy} from 'lodash';
+
+export interface JsonBlob {
+    /** Either null for private blobs or special token "*" for globally shared blobs. */
+    acl: string;
+    /** True if this blob has been archived (soft-deleted). */
+    archived: boolean;
+    /** Timestamp indicating when this blob was archived, or special value `0` if not archived. */
+    archivedDate: number;
+    dateCreated: number;
+    description: string;
+    /** @internal database ID for this blob. Favor token instead. */
+    id: number;
+    lastUpdated: number;
+    lastUpdatedBy: string;
+    /** Optional application-specific metadata. */
+    meta: PlainObject | unknown[];
+    name: string;
+    /** Username of the blob's creator / owner. */
+    owner: string;
+    /** Primary unique identifier for getting, updating, and archiving blobs. */
+    token: string;
+    /**
+     * Application defined type for this blob. Used as a discriminator when querying blobs related
+     * to a particular use-case within an application.
+     */
+    type: string;
+    /**
+     * Current JSON value of this blob - its contents or data. Will be undefined for blob stubs
+     * returned by `listAsync` if `includeValue` was false.
+     */
+    value?: any;
+}
 
 /**
  * Service to read and set chunks of user-specific JSON persisted via Hoist Core's JSONBlob class.
+ *
+ * This service is intended as a general, lightweight utility for persisting small bundles of
+ * unstructured data that might not warrant a full-blown domain object, but which still need to be
+ * persisted back to the database.
  */
 export class JsonBlobService extends HoistService {
     static instance: JsonBlobService;
 
-    async getAsync(token) {
+    /** Retrieve a single JSONBlob by its unique token. */
+    async getAsync(token: string): Promise<JsonBlob> {
         return XH.fetchJson({
             url: 'xh/getJsonBlob',
             params: {token}
         });
     }
 
-    /**
-     * Return the list of blobs visible to the current user.
-     *
-     * @param type - reference key for which type of data to list.
-     * @param includeValue - true to include the full value string for each blob.
-     */
-    async listAsync({type, includeValue}: {type: string; includeValue?: boolean}) {
+    /** Retrieve all blobs of a particular type that are visible to the current user. */
+    async listAsync({
+        type,
+        includeValue,
+        loadSpec
+    }: {
+        type: string;
+        includeValue?: boolean;
+        loadSpec?: LoadSpec;
+    }) {
         return XH.fetchJson({
             url: 'xh/listJsonBlobs',
-            params: {type, includeValue}
+            params: {type, includeValue},
+            loadSpec
         });
     }
 
     /** Persist a new JSONBlob back to the server. */
     async createAsync({
+        acl,
+        description,
         type,
-        name,
-        value,
         meta,
-        description
-    }: {
-        type: string;
-        name: string;
-        description?: string;
-        value: any;
-        meta?: any;
-    }) {
+        name,
+        value
+    }: Partial<JsonBlob>): Promise<JsonBlob> {
         return XH.fetchJson({
             url: 'xh/createJsonBlob',
             params: {
-                data: JSON.stringify({type, name, value, meta, description})
+                data: JSON.stringify({type, name, acl, value, meta, description})
             }
         });
     }
 
-    /** Modify an existing JSONBlob, as identified by its unique token. */
+    /** Modify mutable properties of an existing JSONBlob, as identified by its unique token. */
     async updateAsync(
         token: string,
-        {
-            name,
-            value,
-            meta,
-            description
-        }: {name?: string; value?: any; meta?: any; description?: string}
-    ) {
+        {acl, description, meta, name, value}: Partial<JsonBlob>
+    ): Promise<JsonBlob> {
+        const update = pickBy({acl, description, meta, name, value}, (v, k) => v !== undefined);
         return XH.fetchJson({
             url: 'xh/updateJsonBlob',
             params: {
                 token,
-                update: JSON.stringify({name, value, meta, description})
+                update: JSON.stringify(update)
             }
         });
     }
 
     /** Archive (soft-delete) an existing JSONBlob, as identified by its unique token. */
-    async archiveAsync(token: string) {
+    async archiveAsync(token: string): Promise<JsonBlob> {
         return XH.fetchJson({
             url: 'xh/archiveJsonBlob',
             params: {token}