@operato/data-grist 2.0.0-alpha.7 → 2.0.0-alpha.80

package/dist/src/data-grist.js

@@ -14,11 +14,33 @@ import { buildConfig } from './configure/config-builder';
 import { ZERO_CONFIG, ZERO_DATA, ZERO_PAGES, ZERO_PAGINATION } from './configure/zero-config';
 import { DataProvider } from './data-provider';
 import { convertListParamToSearchString, convertSearchStringToListParam } from './utils';
+/**
+ * A custom element for rendering data in a grid, list, or card format.
+ *
+ * @element ox-grist
+ */
 let DataGrist = class DataGrist extends LitElement {
     constructor() {
         super(...arguments);
+        /**
+         * The rendering mode of the component, which can be 'GRID', 'LIST', or 'CARD'.
+         * Default is 'GRID'.
+         *
+         * @property {string}
+         */
         this.mode = 'GRID';
+        /**
+         * The data to be displayed in the data grist.
+         *
+         * @property {GristData}
+         */
         this.data = ZERO_DATA;
+        /**
+         * Indicates whether explicit fetching of data is enabled. If true, data will be fetched
+         * only when `fetch` method is called. Default is false.
+         *
+         * @property {boolean}
+         */
         this.explicitFetch = false;
         this._data = ZERO_DATA;
         this._config = ZERO_CONFIG;
@@ -196,27 +218,27 @@ let DataGrist = class DataGrist extends LitElement {
             `
             : this.mode == 'CARD'
                 ? html `
-              <ox-card
-                id="grist"
-                .config=${this.compiledConfig}
-                .data=${this._data}
-                .sorters=${this.sorters || []}
-                .filters=${this.filters || []}
-                ?empty=${empty}
-              >
-              </ox-card>
-            `
+                <ox-card
+                  id="grist"
+                  .config=${this.compiledConfig}
+                  .data=${this._data}
+                  .sorters=${this.sorters || []}
+                  .filters=${this.filters || []}
+                  ?empty=${empty}
+                >
+                </ox-card>
+              `
                 : html `
-              <ox-list
-                id="grist"
-                .config=${this.compiledConfig}
-                .data=${this._data}
-                .sorters=${this.sorters || []}
-                .filters=${this.filters || []}
-                ?empty=${empty}
-              >
-              </ox-list>
-            `}
+                <ox-list
+                  id="grist"
+                  .config=${this.compiledConfig}
+                  .data=${this._data}
+                  .sorters=${this.sorters || []}
+                  .filters=${this.filters || []}
+                  ?empty=${empty}
+                >
+                </ox-list>
+              `}
       </div>
 
       <div id="spinner" ?show=${this._showSpinner}></div>
@@ -235,9 +257,21 @@ let DataGrist = class DataGrist extends LitElement {
             }
         }
     }
+    /**
+     * Gets the current state of the component. The state includes information about the
+     * dirty records and their changes.
+     *
+     * @getter
+     * @public
+     * @type {string}
+     */
     get state() {
         return JSON.stringify(this.dirtyData);
     }
+    /**
+     * Undoes the previous change in the component's data by restoring it to the previous state.
+     * This method is part of the TimeCapsule feature, allowing users to revert changes.
+     */
     undo() {
         var _a, _b;
         if (!((_a = this.timeCapsule) === null || _a === void 0 ? void 0 : _a.backwardable)) {
@@ -245,6 +279,10 @@ let DataGrist = class DataGrist extends LitElement {
         }
         this._data = JSON.parse((_b = this.timeCapsule) === null || _b === void 0 ? void 0 : _b.backward());
     }
+    /**
+     * Redoes the previously undone change in the component's data by restoring it to the next state.
+     * This method is part of the TimeCapsule feature, allowing users to reapply changes.
+     */
     redo() {
         var _a, _b;
         if (!((_a = this.timeCapsule) === null || _a === void 0 ? void 0 : _a.forwardable)) {
@@ -252,6 +290,13 @@ let DataGrist = class DataGrist extends LitElement {
         }
         this._data = JSON.parse((_b = this.timeCapsule) === null || _b === void 0 ? void 0 : _b.forward());
     }
+    /**
+     * Fetches data from a data source and updates the component's data. This method is used to retrieve
+     * new data or refresh the existing data in the component.
+     *
+     * @method
+     * @param {boolean} reset - If true, the method resets the scroll position to the top.
+     */
     async fetch(reset = true) {
         var _a, _b;
         if (!this.compiledConfig) {
@@ -343,17 +388,56 @@ let DataGrist = class DataGrist extends LitElement {
             await this.setPullToRefresh();
         }
     }
+    /**
+     * Represents the compiled configuration of the component, which includes various settings and
+     * column configurations. You can access this property to get information about how the component
+     * is configured.
+     *
+     * @getter
+     * @public
+     * @type  {GristConfig}
+     */
     get compiledConfig() {
         return this._config;
     }
+    /**
+     * Returns the dirty data in the component, which includes the records that have been added,
+     * modified, or deleted but have not been committed to the main data yet.
+     *
+     * @getter
+     * @public
+     * @type  {GristData} - An object representing the dirty data.
+     */
     get dirtyData() {
         var _a;
         return ((_a = this.grist) === null || _a === void 0 ? void 0 : _a.data) || {};
     }
+    /**
+     * Returns an array of GristRecord objects representing the records in the dirty state. These are
+     * the records that have been added, modified, or deleted but have not been committed to the main
+     * data yet.
+     *
+     * @getter
+     * @public
+     * @type  {GristRecord[]} - An array of GristRecord objects representing the dirty records.
+     */
     get dirtyRecords() {
         var { records = [] } = this.dirtyData;
         return records.filter(record => record['__dirty__']);
     }
+    /**
+     * Exports a list of patches representing the changes in the dirty state of records. Each patch
+     * contains information about whether a record was added, modified, or deleted, along with the
+     * record's unique identifier and the changed field values.
+     *
+     * @param {Object} options - Export options that control the format of the patch list.
+     * @param {string} options.flagName - The name of the flag field in the patch indicating the change type (default: 'patchFlag').
+     * @param {string} options.addedFlag - The flag value for added records (default: '+').
+     * @param {string} options.deletedFlag - The flag value for deleted records (default: '-').
+     * @param {string} options.modifiedFlag - The flag value for modified records (default: 'M').
+     * @param {string} options.idField - The name of the unique identifier field (default: 'id').
+     * @returns {Object[]} - An array of objects representing the patches.
+     */
     exportPatchList({ flagName = 'patchFlag', addedFlag = '+', deletedFlag = '-', modifiedFlag = 'M', idField = 'id' }) {
         let dirtyRecords = this.dirtyRecords;
         if (!dirtyRecords || dirtyRecords.length == 0) {
@@ -373,6 +457,15 @@ let DataGrist = class DataGrist extends LitElement {
             return patch;
         });
     }
+    /**
+     * Exports the selected records or all records in the component, depending on the specified options.
+     * You can use this method to export data from the component in various formats or for different purposes.
+     *
+     * @param {Object} options - Export options that control the behavior of the export.
+     * @param {boolean} options.ifSelectedOnly - If true, exports only the selected records. If false, exports all records.
+     * @param {boolean} options.includeHiddenField - If true, includes hidden fields in the exported data.
+     * @returns {Object[]} - An array of objects representing the exported records.
+     */
     exportRecords({ ifSelectedOnly = true, includeHiddenField = true } = {}) {
         let records = ifSelectedOnly ? this.selected : this.data.records;
         if (ifSelectedOnly && (!records || records.length == 0)) {
@@ -390,11 +483,27 @@ let DataGrist = class DataGrist extends LitElement {
             }, {});
         });
     }
+    /**
+     * Gets the currently selected records in the component. It returns an array of GristRecord objects
+     * that are currently selected. You can access this getter to retrieve the selected records.
+     *
+     * @getter
+     * @public
+     * @type {GristRecord[]}
+     */
     get selected() {
         var _a;
         var { records = [] } = (_a = this.grist) === null || _a === void 0 ? void 0 : _a.data;
         return records.filter(record => record['__selected__']);
     }
+    /**
+     * Sets the currently selected records in the component. You can use this setter to programmatically
+     * select specific records by providing an array of GristRecord objects to be selected.
+     *
+     * @setter
+     * @public
+     * @type {GristRecord[]}
+     */
     set selected(selected) {
         if (!this.grist) {
             console.warn('grist not ready');
@@ -403,6 +512,15 @@ let DataGrist = class DataGrist extends LitElement {
         selected.forEach(record => (record.__selected__ = true));
         this.refresh();
     }
+    /**
+     * Selects records in the component based on the provided selector function. You can use this method
+     * to programmatically select specific records in the component.
+     *
+     * @method
+     * @param {GristSelectFunction} selector - A function that determines which records to select.
+     * @param {boolean} reset - If true, clears the previous selection before applying the new one.
+     *                         If false, adds to the existing selection.
+     */
     select(selector, reset = false) {
         var _a;
         var { records = [] } = (_a = this.grist) === null || _a === void 0 ? void 0 : _a.data;
@@ -412,16 +530,32 @@ let DataGrist = class DataGrist extends LitElement {
         records.filter(record => selector(record)).forEach(record => (record.__selected__ = true));
         this.refresh();
     }
+    /**
+     * Shows the loading spinner in the component's UI to indicate ongoing data loading or processing.
+     * You can call this method to display the spinner when necessary.
+     */
     showSpinner() {
         this._showSpinner = true;
     }
+    /**
+     * Hides the loading spinner in the component's UI to indicate that data loading or processing has completed.
+     * You can call this method to hide the spinner when loading or processing is finished.
+     */
     hideSpinner() {
         this._showSpinner = false;
     }
+    /**
+     * Focuses on the component, making it the active element in the document. This method is useful
+     * when you want to programmatically set focus to the component.
+     */
     focus() {
         super.focus();
         this.grist.focus();
     }
+    /**
+     * Commits the changes made in the dirty state to the component's data. This method updates the
+     * component's data with the changes made in the dirty state and clears the dirty state.
+     */
     commit() {
         var { page, total, limit, records } = this.grist.data;
         this.data = {
@@ -447,18 +581,30 @@ let DataGrist = class DataGrist extends LitElement {
             })
         };
     }
+    /**
+     * Shows the headroom element in the component. The headroom element is typically used for
+     * displaying additional information or controls at the top of the component.
+     */
     showHeadroom() {
         if (this.head) {
             this.head.style.display = 'block';
             this.setHeadroom();
         }
     }
+    /**
+     * Hides the headroom element in the component. This method hides the additional information
+     * or controls displayed at the top of the component.
+     */
     hideHeadroom() {
         if (this.head) {
             this.head.style.display = 'none';
             this.setHeadroom();
         }
     }
+    /**
+     * Toggles the visibility of the headroom element in the component. If the headroom element is
+     * currently visible, this method hides it. If it's hidden, this method shows it.
+     */
     toggleHeadroom() {
         if (this.head) {
             const display = this.head.style.display;
@@ -476,14 +622,15 @@ let DataGrist = class DataGrist extends LitElement {
         this.grist.refresh();
     }
     /**
-     * This method cancels all changes in the dirty state before being reflected in the data.
+     * Resets the component's data to its original state before any changes were made.
+     * This method discards all unsaved changes and restores the data to its initial state.
      *
      * @method
-     *
-     * TODO tree 형태의 데이타로 _data를 만들 때, children, collapsed 등을 감안한다.
+     * @public
      */
     reset() {
         var _a, _b;
+        // TODO tree 형태의 데이타로 _data를 만들 때, children, collapsed 등을 감안한다.
         var { limit = ZERO_PAGINATION.limit, page = ZERO_PAGINATION.page, total = ZERO_PAGINATION.total, records = [] } = this.data || ZERO_PAGINATION;
         const { childrenProperty, expanded } = this.compiledConfig.tree;
         /* 원본 데이타를 남기고, 복사본(_data)을 사용한다. */
@@ -523,6 +670,10 @@ let DataGrist = class DataGrist extends LitElement {
             return [record];
         }
     }
+    /**
+     * Checks for dirty records in the component's data and marks them as dirty.
+     * Dirty records are those that have unsaved changes.
+     */
     checkDirties() {
         var _a;
         const records = this.dirtyRecords;
@@ -546,6 +697,10 @@ let DataGrist = class DataGrist extends LitElement {
         this._data = { ...this.dirtyData };
         (_a = this.snapshotTaker) === null || _a === void 0 ? void 0 : _a.touch();
     }
+    /**
+     * Clones the selected records in the component's data. It creates a copy of the selected records
+     * and marks them as new (added) records.
+     */
     cloneSelectedRecords() {
         const records = this.selected || [];
         records.forEach(record => {
@@ -562,6 +717,33 @@ let DataGrist = class DataGrist extends LitElement {
         });
         this.checkDirties();
     }
+    /**
+     * Adds child nodes to selected records in the component's tree data. It allows users to add child nodes
+     * to the selected parent records.
+     */
+    addChildNodes() {
+        const records = this.selected || [];
+        records.forEach(record => {
+            this.grist.addChildNode(record);
+        });
+    }
+    /**
+     * Adds sibling nodes to selected records in the component's tree data. It allows users to add sibling nodes
+     * to the selected records.
+     */
+    addSiblingNodes() {
+        const records = this.selected || [];
+        records.forEach(record => {
+            this.grist.addSiblingNode(record);
+        });
+    }
+    /**
+     * Deletes the selected records in the component's data. It removes the selected records from the data,
+     * optionally marking them as deleted.
+     *
+     * @method
+     * @param {boolean} dirty - If true, the method marks the records as deleted.
+     */
     deleteSelectedRecords(dirty = true) {
         const records = this.selected || [];
         records.forEach(record => {
@@ -573,10 +755,20 @@ let DataGrist = class DataGrist extends LitElement {
         });
         this.checkDirties();
     }
+    /**
+     * Retrieves the search text used for filtering records.
+     *
+     * @property {string}
+     */
     get searchText() {
         var _a, _b, _c, _d;
         return ((_d = (_c = (_b = (_a = this.filters) === null || _a === void 0 ? void 0 : _a.find(filter => filter.operator === 'search')) === null || _b === void 0 ? void 0 : _b.value) === null || _c === void 0 ? void 0 : _c.match(/^\%(.*)\%$/)) === null || _d === void 0 ? void 0 : _d[1]) || '';
     }
+    /**
+     * Sets the search text for filtering records.
+     *
+     * @property {string}
+     */
     set searchText(searchText) {
         var filters = (this.filters || []).filter((filter) => filter.operator !== 'search');
         if (searchText) {
@@ -625,7 +817,7 @@ DataGrist.styles = [
 
         padding: var(--ox-grist-padding);
 
-        --mdc-icon-size: var(--grid-record-wide-fontsize);
+        --md-icon-size: var(--grid-record-wide-fontsize);
       }
 
       #wrap {
@@ -651,7 +843,7 @@ DataGrist.styles = [
         box-sizing: border-box;
         background-color: var(--grist-background-color);
 
-        z-index: 1;
+        z-index: 2;
       }
     `
 ];