@operato/data-grist 2.0.0-alpha.8 → 2.0.0-alpha.81

package/src/data-grist.ts

@@ -33,6 +33,11 @@ import {
 } from './types'
 import { convertListParamToSearchString, convertSearchStringToListParam } from './utils'
 
+/**
+ * A custom element for rendering data in a grid, list, or card format.
+ *
+ * @element ox-grist
+ */
 @customElement('ox-grist')
 export class DataGrist extends LitElement implements DataConsumer {
   static styles = [
@@ -54,7 +59,7 @@ export class DataGrist extends LitElement implements DataConsumer {
 
         padding: var(--ox-grist-padding);
 
-        --mdc-icon-size: var(--grid-record-wide-fontsize);
+        --md-icon-size: var(--grid-record-wide-fontsize);
       }
 
       #wrap {
@@ -80,21 +85,89 @@ export class DataGrist extends LitElement implements DataConsumer {
         box-sizing: border-box;
         background-color: var(--grist-background-color);
 
-        z-index: 1;
+        z-index: 2;
       }
     `
   ]
 
+  /**
+   * The rendering mode of the component, which can be 'GRID', 'LIST', or 'CARD'.
+   * Default is 'GRID'.
+   *
+   * @property {string}
+   */
   @property() mode: 'GRID' | 'LIST' | 'CARD' = 'GRID'
+
+  /**
+   * The configuration object for the data grist.
+   *
+   * @property {Object}
+   */
   @property() config: any
+
+  /**
+   * The data to be displayed in the data grist.
+   *
+   * @property {GristData}
+   */
   @property({ type: Object }) data: GristData = ZERO_DATA
+
+  /**
+   * An array of selected records in the data grist.
+   *
+   * @property {GristRecord[]}
+   */
   @property({ type: Array }) selectedRecords?: GristRecord[]
+
+  /**
+   * 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}
+   */
   @property({ type: Boolean, attribute: 'explicit-fetch' }) explicitFetch: boolean = false
+
+  /**
+   * The fetch handler function used to retrieve data from a remote source.
+   *
+   * @property {FetchHandler}
+   */
   @property() fetchHandler?: FetchHandler
+
+  /**
+   * Additional fetch options to be passed to the fetch handler.
+   *
+   * @property {Object}
+   */
   @property() fetchOptions: any
+
+  /**
+   * An array of filter values to be applied to the data grist.
+   *
+   * @property {FilterValue[]}
+   */
   @property({ type: Array }) filters?: FilterValue[]
+
+  /**
+   * An array of sorters to determine the order of records in the data grist.
+   *
+   * @property {SortersConfig}
+   */
   @property({ type: Array }) sorters?: SortersConfig
+
+  /**
+   * The pagination configuration for the data grist.
+   *
+   * @property {PaginationConfig}
+   */
   @property({ type: Object }) pagination?: PaginationConfig
+
+  /**
+   * Indicates whether URL parameters are sensitive to changes. If true, changes in URL
+   * parameters will trigger data fetching. Default is undefined.
+   *
+   * @property {boolean}
+   */
   @property({ type: Boolean, attribute: 'url-params-sensitive' }) urlParamsSensitive?: boolean
 
   @state() _data: GristData = ZERO_DATA
@@ -331,28 +404,28 @@ export class DataGrist extends LitElement implements DataConsumer {
               </ox-grid>
             `
           : this.mode == 'CARD'
-          ? html`
-              <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>
-            `}
+            ? html`
+                <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>
+              `}
       </div>
 
       <div id="spinner" ?show=${this._showSpinner}></div>
@@ -372,10 +445,22 @@ export class DataGrist extends LitElement implements DataConsumer {
     }
   }
 
+  /**
+   * 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() {
     if (!this.timeCapsule?.backwardable) {
       return
@@ -384,6 +469,10 @@ export class DataGrist extends LitElement implements DataConsumer {
     this._data = JSON.parse(this.timeCapsule?.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() {
     if (!this.timeCapsule?.forwardable) {
       return
@@ -392,6 +481,13 @@ export class DataGrist extends LitElement implements DataConsumer {
     this._data = JSON.parse(this.timeCapsule?.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) {
     if (!this.compiledConfig) {
       /* avoid to be here */
@@ -499,19 +595,58 @@ export class DataGrist extends LitElement implements DataConsumer {
     }
   }
 
+  /**
+   * 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(): GristConfig {
     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(): GristData {
     return (this.grist as any)?.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) {
@@ -536,6 +671,15 @@ export class DataGrist extends LitElement implements DataConsumer {
     })
   }
 
+  /**
+   * 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
 
@@ -557,11 +701,27 @@ export class DataGrist extends LitElement implements DataConsumer {
     })
   }
 
+  /**
+   * 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 { records = [] } = this.grist?.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: GristRecord[]) {
     if (!this.grist) {
       console.warn('grist not ready')
@@ -572,6 +732,15 @@ export class DataGrist extends LitElement implements DataConsumer {
     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: GristSelectFunction, reset: boolean = false) {
     var { records = [] } = this.grist?.data
 
@@ -583,20 +752,36 @@ export class DataGrist extends LitElement implements DataConsumer {
     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
 
@@ -626,6 +811,10 @@ export class DataGrist extends LitElement implements DataConsumer {
     }
   }
 
+  /**
+   * 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'
@@ -633,6 +822,10 @@ export class DataGrist extends LitElement implements DataConsumer {
     }
   }
 
+  /**
+   * 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'
@@ -640,6 +833,10 @@ export class DataGrist extends LitElement implements DataConsumer {
     }
   }
 
+  /**
+   * 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
@@ -660,13 +857,14 @@ export class DataGrist extends LitElement implements DataConsumer {
   }
 
   /**
-   * 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() {
+    // TODO tree 형태의 데이타로 _data를 만들 때, children, collapsed 등을 감안한다.
     var {
       limit = ZERO_PAGINATION.limit,
       page = ZERO_PAGINATION.page,
@@ -741,6 +939,10 @@ export class DataGrist extends LitElement implements DataConsumer {
     }
   }
 
+  /**
+   * Checks for dirty records in the component's data and marks them as dirty.
+   * Dirty records are those that have unsaved changes.
+   */
   checkDirties() {
     const records = this.dirtyRecords
     const { columns = [] } = this.compiledConfig || {}
@@ -771,6 +973,10 @@ export class DataGrist extends LitElement implements DataConsumer {
     this.snapshotTaker?.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 || ([] as GristRecord[])
 
@@ -792,6 +998,37 @@ export class DataGrist extends LitElement implements DataConsumer {
     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 || ([] as GristRecord[])
+
+    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 || ([] as GristRecord[])
+
+    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 || ([] as GristRecord[])
 
@@ -807,10 +1044,20 @@ export class DataGrist extends LitElement implements DataConsumer {
     this.checkDirties()
   }
 
+  /**
+   * Retrieves the search text used for filtering records.
+   *
+   * @property {string}
+   */
   get searchText() {
     return (this.filters?.find(filter => filter.operator === 'search')?.value as string)?.match(/^\%(.*)\%$/)?.[1] || ''
   }
 
+  /**
+   * Sets the search text for filtering records.
+   *
+   * @property {string}
+   */
   set searchText(searchText: string) {
     var filters = (this.filters || []).filter((filter: FilterValue) => filter.operator !== 'search')
 

package/src/data-list/data-list-gutter.ts

@@ -22,6 +22,18 @@ export class DataListGutter extends LitElement {
         font-size: var(--grid-record-wide-fontsize);
         text-overflow: ellipsis;
         color: var(--grid-record-color);
+
+        padding-right: 10px;
+      }
+
+      :host-context(.expand)::after {
+        content: '';
+        position: absolute;
+        left: 50%;
+        top: 50%;
+        transform: translate(-50%, -50%);
+        width: 150%;
+        height: 220%;
       }
 
       * {

package/src/data-list/data-list.ts

@@ -1,4 +1,4 @@
-import '@material/mwc-icon'
+import '@material/web/icon/icon.js'
 import './record-partial'
 
 import { css, html, PropertyValues } from 'lit'
@@ -25,7 +25,7 @@ export class DataList extends DataManipulator {
       }
 
       #upward {
-        --mdc-icon-size: 26px;
+        --md-icon-size: 26px;
         position: absolute;
         top: var(--data-list-fab-position-vertical);
         right: var(--data-list-fab-position-horizontal);
@@ -118,7 +118,7 @@ export class DataList extends DataManipulator {
       ${this.empty ? html` <ox-empty-note title="NO RECORDS"></ox-empty-note> ` : html``}
       ${this.isTop
         ? html``
-        : html` <mwc-icon id="upward" @click=${(e: Event) => this.gotoTop(e)}>arrow_upward</mwc-icon> `}
+        : html` <md-icon id="upward" @click=${(e: Event) => this.gotoTop(e)}>arrow_upward</md-icon> `}
     `
   }
 

package/src/data-list/event-handlers/record-partial-click-handler.ts

@@ -29,6 +29,6 @@ export function recordPartialClickHandler(this: RecordPartial, e: MouseEvent): v
     rowsClick(this.config.columns, this.data, column, this.record, rowIndex, target)
   } else {
     /* content 가 클릭된 경우 - 레코드뷰 팝업을 실행한다. */
-    this.popupRecordView()
+    this.config.rows.editable && this.popupRecordView()
   }
 }

package/src/data-list/record-partial.ts

@@ -1,4 +1,4 @@
-import '@material/mwc-icon'
+import '@material/web/icon/icon.js'
 import './data-list-gutter'
 import './data-list-field'
 import '../record-view'
@@ -39,6 +39,7 @@ export class RecordPartial extends LitElement {
         border-bottom: var(--data-list-item-border-bottom);
         position: relative;
         min-height: 42px;
+        padding-left: 7px;
       }
 
       :host([dirty])::before {
@@ -168,32 +169,31 @@ export class RecordPartial extends LitElement {
     }
 
     return html`
-      ${dirtyIcon ? html` <mwc-icon dirty>${dirtyIcon}</mwc-icon> ` : html``}
+      ${dirtyIcon ? html` <md-icon dirty>${dirtyIcon}</md-icon> ` : html``}
       ${gutters.map(
-        gutter =>
-          html`
-            <ox-list-gutter
-              .rowIndex=${rowIndex}
-              .column=${gutter}
-              .record=${record}
-              .value=${record[gutter.name]}
-            ></ox-list-gutter>
-          `
+        gutter => html`
+          <ox-list-gutter
+            class=${gutter.name === 'detail' ? 'expand' : ''}
+            .rowIndex=${rowIndex}
+            .column=${gutter}
+            .record=${record}
+            .value=${record[gutter.name]}
+          ></ox-list-gutter>
+        `
       )}
 
       <div content>
         ${displayColumns.map(
-          (column, idx) =>
-            html`
-              <ox-list-field
-                .rowIndex=${rowIndex}
-                .column=${column}
-                .record=${record}
-                .value=${record[column?.name || '']}
-                ?name=${idx == 0}
-                ?desc=${idx == 1}
-              ></ox-list-field>
-            `
+          (column, idx) => html`
+            <ox-list-field
+              .rowIndex=${rowIndex}
+              .column=${column}
+              .record=${record}
+              .value=${record[column?.name || '']}
+              ?name=${idx == 0}
+              ?desc=${idx == 1}
+            ></ox-list-field>
+          `
         )}
       </div>
       ${thumbnail