@operato/data-grist 2.0.0-alpha.6 → 2.0.0-alpha.60

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 = [
@@ -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
@@ -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/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

@@ -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 {
@@ -173,6 +174,7 @@ export class RecordPartial extends LitElement {
         gutter =>
           html`
             <ox-list-gutter
+              class=${gutter.name === 'detail' ? 'expand' : ''}
               .rowIndex=${rowIndex}
               .column=${gutter}
               .record=${record}

package/src/data-manipulator.ts

@@ -64,14 +64,16 @@ export class DataManipulator extends LitElement {
     })
 
     /* tree processing */
-    this.addEventListener('collapse-all', (e: Event) => this.onCollapseAll(e as CustomEvent))
-    this.addEventListener('expand-all', (e: Event) => this.onExpandAll(e as CustomEvent))
-    this.addEventListener('collapse-node', (e: Event) => this.onCollapse(e as CustomEvent))
-    this.addEventListener('expand-node', (e: Event) => this.onExpand(e as CustomEvent))
+    this.addEventListener('collapse-all', (e: Event) => this.collapseAll())
+    this.addEventListener('expand-all', (e: Event) => this.expandAll())
+    this.addEventListener('collapse-node', (e: Event) => this.collapseNode((e as CustomEvent).detail as GristRecord))
+    this.addEventListener('expand-node', (e: Event) => this.expandNode((e as CustomEvent).detail as GristRecord))
     this.addEventListener('check-in-tree', (e: Event) => this.onCheckInTree(e as CustomEvent))
 
-    this.addEventListener('add-sibling-node', (e: Event) => this.onAddSiblingNode(e as CustomEvent))
-    this.addEventListener('add-child-node', (e: Event) => this.onAddChildNode(e as CustomEvent))
+    this.addEventListener('add-sibling-node', (e: Event) =>
+      this.addSiblingNode((e as CustomEvent).detail as GristRecord)
+    )
+    this.addEventListener('add-child-node', (e: Event) => this.addChildNode((e as CustomEvent).detail as GristRecord))
   }
 
   onFieldChange({
@@ -212,36 +214,46 @@ export class DataManipulator extends LitElement {
     this.requestUpdate()
   }
 
-  onCollapseAll(e: CustomEvent) {
+  collapseAll() {
     this.refresh(false)
   }
 
-  onExpandAll(e: CustomEvent) {
+  expandAll() {
     this.refresh(true)
   }
 
-  onCollapse(e: CustomEvent) {
-    const record = e.detail as GristRecord
+  collapseNode(record: GristRecord) {
     record.__expanded__ = false
 
     this.refresh()
   }
 
-  onExpand(e: CustomEvent) {
-    const record = e.detail as GristRecord
+  expandNode(record: GristRecord) {
     record.__expanded__ = true
 
     this.refresh()
   }
 
-  onAddSiblingNode(e: CustomEvent) {
+  // onCollapse(e: CustomEvent) {
+  //   const record = e.detail as GristRecord
+  //   record.__expanded__ = false
+
+  //   this.refresh()
+  // }
+
+  // onExpand(e: CustomEvent) {
+  //   const record = e.detail as GristRecord
+  //   record.__expanded__ = true
+
+  //   this.refresh()
+  // }
+
+  addSiblingNode(record: GristRecord) {
     const { records } = this.data
     const toplevelRecords = records.filter(
       record => !record.__depth__
     ) /* __depth__ 가 설정되지 않았거나, 0 인 경우만 수집 */
 
-    const field = e.detail
-    const { record } = field
     const { __depth__ } = record as GristRecord
 
     function findParent(record: GristRecord, parent?: GristRecord): GristRecord | undefined {
@@ -264,15 +276,27 @@ export class DataManipulator extends LitElement {
     const sibling = {
       __depth__,
       __dirty__: '+'
-    }
+    } as GristRecord
 
     if (parent) {
-      const { __children__ } = parent as GristRecord
+      const { id } = parent as GristRecord
 
-      if (!__children__) {
+      sibling.parent = { id }
+
+      if (!parent.__children__) {
         parent.__children__ = [sibling]
       } else {
-        parent.__children__ = [...__children__, sibling]
+        let index = parent.__children__.indexOf(record)
+
+        if (index !== -1) {
+          parent.__children__ = [
+            ...parent.__children__.slice(0, index + 1),
+            sibling,
+            ...parent.__children__.slice(index + 1)
+          ]
+        } else {
+          parent.__children__ = [...parent.__children__, sibling]
+        }
       }
 
       parent.__expanded__ = true
@@ -283,25 +307,25 @@ export class DataManipulator extends LitElement {
     this.refresh()
   }
 
-  onAddChildNode(e: CustomEvent) {
-    const field = e.detail
-    const { record } = field
-
-    const { __children__, __depth__, __seq__ } = record as GristRecord
+  addChildNode(record: GristRecord) {
+    const { id: parentId, __children__, __depth__ } = record as GristRecord
     const child = {
+      parent: {
+        id: parentId
+      },
       __depth__: (__depth__ || 0) + 1,
       __dirty__: '+'
     }
 
-    if (!__children__) {
+    if (!record.__children__) {
       record.__children__ = [child]
     } else {
-      record.__children__.push(child)
+      record.__children__.unshift(child)
     }
 
     record.__expanded__ = true
 
-    field.requestUpdate()
+    // this.requestUpdate()
 
     this.refresh()
   }
@@ -388,10 +412,7 @@ export class DataManipulator extends LitElement {
 
   private traverseRefresh(record: GristRecord, forceExpandOrCollapse?: boolean): GristRecord[] {
     if (forceExpandOrCollapse !== undefined) {
-      record = {
-        ...record,
-        __expanded__: forceExpandOrCollapse
-      }
+      record.__expanded__ = forceExpandOrCollapse
     }
 
     const { __expanded__, __children__ = [] } = record

package/src/editors/ox-grist-editor-checkbox.ts

@@ -4,8 +4,18 @@ import { html } from 'lit'
 
 @customElement('ox-grist-editor-checkbox')
 export class OxGristEditorCheckbox extends OxGristEditor {
-  formatFromEditor(e: Event) {
-    return (e.target as HTMLInputElement).checked
+  _onchange(e: Event) {
+    e.stopPropagation()
+
+    const input = e.target as HTMLInputElement
+
+    this._dirtyValue = this.formatFromEditor(input.checked)
+  }
+
+  formatFromEditor(value: any) {
+    if (typeof value == 'boolean') {
+      return value
+    }
   }
 
   formatForEditor(value: any): any {

package/src/editors/ox-grist-editor-datetime.ts

@@ -15,8 +15,7 @@ export class OxGristEditorDateTime extends OxGristEditor {
     return new Date(timestamp - tzoffset).toISOString().slice(0, -1)
   }
 
-  formatFromEditor(e: Event) {
-    var value = (e.target as HTMLInputElement).value
+  formatFromEditor(value: any) {
     var datetime = new Date(value)
 
     return datetime.getTime()

package/src/editors/ox-grist-editor-file.ts

@@ -5,8 +5,18 @@ import { OxGristEditor } from './ox-grist-editor.js'
 
 @customElement('ox-grist-editor-file')
 export class OxGristEditorFile extends OxGristEditor {
-  formatFromEditor(e: Event): any {
-    return (e.target as HTMLInputElement).files
+  _onchange(e: Event) {
+    e.stopPropagation()
+
+    const input = e.target as HTMLInputElement
+
+    this._dirtyValue = this.formatFromEditor(input.files)
+
+    this._onfocusout()
+  }
+
+  formatFromEditor(value: any): any {
+    return value
   }
 
   get editorTemplate() {