@operato/data-grist 9.0.0-beta.54 → 9.0.0-beta.56

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [9.0.0-beta.56](https://github.com/hatiolab/operato/compare/v9.0.0-beta.55...v9.0.0-beta.56) (2025-03-30)
+
+
+### :bug: Bug Fix
+
+* add addRecordToTop method into ox-grist ([57851b0](https://github.com/hatiolab/operato/commit/57851b0847e8f591a059345950da39b94e8d5122))
+* title for ox-grist stories and README.md ([38476a5](https://github.com/hatiolab/operato/commit/38476a5994b142f29205014aa0238a1724fd7de1))
+
+
+
+## [9.0.0-beta.55](https://github.com/hatiolab/operato/compare/v9.0.0-beta.54...v9.0.0-beta.55) (2025-03-05)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
 ## [9.0.0-beta.54](https://github.com/hatiolab/operato/compare/v9.0.0-beta.53...v9.0.0-beta.54) (2025-03-04)
 
 **Note:** Version bump only for package @operato/data-grist

package/README.md

@@ -1,95 +1,388 @@
-# \<data-grist>
+# Data-Grist
 
-This webcomponent follows the [open-wc](https://github.com/open-wc/open-wc) recommendation.
+Data-Grist is a powerful web component for displaying and manipulating data. It can present data in Grid, List, or Card formats and provides various features such as data sorting, filtering, editing, and more.
+
+## Key Features
+
+- **Multiple Display Modes**: Flexibly display the same data in grid, list, or card formats
+- **Data Manipulation**: Add, modify, and delete records
+- **Sorting and Filtering**: Single/multi-column sorting, various filtering options
+- **Editing Capabilities**: Inline cell editing, validation
+- **Pagination**: Standard paging and infinite scroll support
+- **Selection**: Single/multiple record selection
+- **State Tracking**: Track changed (dirty) records
+- **Customization**: Support for various renderers, editors, and event handlers
+- **Mobile Responsive**: Responsive design support
 
 ## Installation
 
 ```bash
-npm i data-grist
+npm install @operato/data-grist
 ```
 
-## Usage
+## Basic Usage
 
 ```html
 <script type="module">
-  import 'data-grist/data-grist.js';
+  import '@operato/data-grist/ox-grist.js'
 </script>
 
-<data-grist></data-grist>
+<ox-grist
+  .mode=${'GRID'}
+  .config=${gridConfig}
+  .fetchHandler=${fetchDataFunction}
+></ox-grist>
 ```
 
-## Linting with ESLint, Prettier, and Types
+## Modes
 
-To scan the project for linting errors, run
+Data-Grist supports three display modes:
 
-```bash
-npm run lint
+- **GRID**: Tabular data display (default)
+- **LIST**: Mobile-friendly list format display
+- **CARD**: Card format display
+
+```javascript
+// Set mode
+gristElement.mode = 'GRID' // or 'LIST', 'CARD'
 ```
 
-You can lint with ESLint and Prettier individually as well
+## Configuration (Config)
+
+Data-Grist provides various configuration options.
+
+```javascript
+const config = {
+  columns: [
+    {
+      type: 'string',
+      name: 'name',
+      header: 'Name',
+      record: {
+        editable: true
+      },
+      sortable: true,
+      width: 150
+    }
+    // More columns...
+  ],
+  rows: {
+    appendable: true, // Allow adding new records
+    editable: true, // Allow editing records
+    selectable: {
+      // Record selection settings
+      multiple: true // Allow multiple selections
+    }
+  },
+  pagination: {
+    infinite: false, // Use paging instead of infinite scroll
+    page: 1, // Starting page
+    limit: 20 // Records per page
+  }
+  // Additional settings...
+}
+```
 
-```bash
-npm run lint:eslint
+### Column Types
+
+```javascript
+// String column
+{
+  type: 'string',
+  name: 'firstName',
+  header: 'First Name'
+}
+
+// Number column
+{
+  type: 'number',
+  name: 'age',
+  header: 'Age',
+  record: {
+    align: 'right'
+  }
+}
+
+// Boolean column
+{
+  type: 'boolean',
+  name: 'isActive',
+  header: 'Active'
+}
+
+// Link column
+{
+  type: 'link',
+  name: 'website',
+  header: 'Website',
+  record: {
+    options: {
+      href: (column, record) => record.url,
+      target: '_blank'
+    }
+  }
+}
+
+// Gutter column (row number, checkbox, button, etc.)
+{
+  type: 'gutter',
+  gutterName: 'sequence' // 'row-selector', 'button', 'dirty', etc.
+}
 ```
 
-```bash
-npm run lint:prettier
+## Fetching Data
+
+Data can be retrieved through the `fetchHandler` function.
+
+```javascript
+const fetchHandler = async params => {
+  const { page, limit, sorters, filters } = params
+
+  // Fetch data from server
+  const response = await fetch(`/api/data?page=${page}&limit=${limit}`)
+  const data = await response.json()
+
+  return {
+    total: data.total,
+    records: data.items
+  }
+}
+
+// Configure the grist
+gristElement.fetchHandler = fetchHandler
 ```
 
-To automatically fix many linting errors, run
+## Record Manipulation API
 
-```bash
-npm run format
+### Adding Records
+
+```javascript
+// Add record at the end (default)
+gristElement.addRecord({
+  name: 'John Doe',
+  age: 30
+})
+
+// Add record at the top
+gristElement.addRecordToTop({
+  name: 'Jane Smith',
+  age: 25
+})
 ```
 
-You can format using ESLint and Prettier individually as well
+### Record Selection
 
-```bash
-npm run format:eslint
+```javascript
+// Get all selected records
+const selectedRecords = gristElement.selected
+
+// Set selection
+gristElement.selected = [record1, record2]
+
+// Select records using a selector function
+gristElement.select(record => record.age > 30)
 ```
 
-```bash
-npm run format:prettier
+### Tracking Changed Records
+
+```javascript
+// Get modified records
+const dirtyRecords = gristElement.dirtyRecords
+
+// Check for changes
+gristElement.checkDirties()
+
+// Export changes as patches
+const patches = gristElement.exportPatchList()
 ```
 
-## Testing with Web Test Runner
+## Events
 
-To run the suite of Web Test Runner tests, run
+Data-Grist triggers various events.
 
-```bash
-npm run test
+```javascript
+// Record selection change event
+gristElement.addEventListener('select-record-change', e => {
+  const { records, added, removed } = e.detail
+  console.log('Selected records:', records)
+})
+
+// Field change event
+gristElement.addEventListener('field-change', e => {
+  const { after, before, column, record, row } = e.detail
+  console.log('Changed field:', column.name, 'from', before, 'to', after)
+})
+
+// Record change event
+gristElement.addEventListener('record-change', e => {
+  const { before, after, column, row } = e.detail
+  console.log('Record changed:', row)
+})
 ```
 
-To run the tests in watch mode (for &lt;abbr title=&#34;test driven development&#34;&gt;TDD&lt;/abbr&gt;, for example), run
+## Advanced Features
 
-```bash
-npm run test:watch
+### Column Accumulation Feature (Accumulator)
+
+```javascript
+{
+  type: 'number',
+  name: 'amount',
+  header: 'Amount',
+  accumulator: 'sum' // 'avg', 'count', 'min', 'max' or custom function
+}
 ```
 
-## Demoing with Storybook
+### Tree Structure Data
 
-To run a local instance of Storybook for your component, run
+```javascript
+const config = {
+  // ...
+  tree: {
+    childrenProperty: 'children', // Property name where child nodes are stored
+    expanded: true // Initial tree expansion state
+  }
+}
+```
 
-```bash
-npm run storybook
+### Grouped Headers
+
+```javascript
+const config = {
+  columns: [
+    // ...
+    {
+      type: 'string',
+      name: 'firstName',
+      header: 'First Name',
+      group: 'personalInfo'
+    },
+    {
+      type: 'string',
+      name: 'lastName',
+      header: 'Last Name',
+      group: 'personalInfo'
+    }
+  ],
+  // ...
+  rows: {
+    // ...
+    groups: [
+      {
+        name: 'personalInfo',
+        title: 'Personal Information'
+      }
+    ]
+  }
+}
 ```
 
-To build a production version of Storybook, run
+### User Settings Storage
+
+```javascript
+// Configure user settings provider
+gristElement.personalConfigProvider = {
+  async load() {
+    // Load saved settings
+    return JSON.parse(localStorage.getItem('userGristConfig'))
+  },
+  async save(preference) {
+    // Save user settings
+    localStorage.setItem('userGristConfig', JSON.stringify(preference))
+  }
+}
+```
 
-```bash
-npm run storybook:build
+## Styling
+
+Data-Grist can be styled through CSS variables.
+
+```css
+ox-grist {
+  --grid-header-background-color: #f5f5f5;
+  --grid-record-background-color: white;
+  --grid-record-odd-background-color: #f9f9f9;
+  --grid-header-color: #333;
+  --grid-record-hover-background-color: #e9e9e9;
+}
 ```
 
-## Tooling configs
+## API Reference
+
+### Properties
+
+| Property          | Type     | Description                           |
+| ----------------- | -------- | ------------------------------------- |
+| `mode`            | string   | Display mode ('GRID', 'LIST', 'CARD') |
+| `config`          | object   | Grist configuration object            |
+| `data`            | object   | Data to display                       |
+| `selectedRecords` | array    | Array of selected records             |
+| `explicitFetch`   | boolean  | Enable explicit data fetching         |
+| `fetchHandler`    | function | Data fetching function                |
+| `fetchOptions`    | object   | Data fetching options                 |
+| `filters`         | array    | Array of filters                      |
+| `sorters`         | array    | Array of sorters                      |
+| `pagination`      | object   | Pagination settings                   |
+
+### Methods
+
+| Method                         | Description                     |
+| ------------------------------ | ------------------------------- |
+| `fetch(reset)`                 | Fetch data                      |
+| `addRecord(record)`            | Add a record                    |
+| `addRecordToTop(record)`       | Add a record at the top         |
+| `deleteSelectedRecords(dirty)` | Delete selected records         |
+| `cloneSelectedRecords()`       | Clone selected records          |
+| `checkDirties()`               | Check for modified records      |
+| `undo()`                       | Undo last action                |
+| `redo()`                       | Redo undone action              |
+| `reset()`                      | Reset data                      |
+| `commit()`                     | Commit changes                  |
+| `select(selector, reset)`      | Select records using a function |
+| `exportPatchList(options)`     | Export list of change patches   |
+| `exportRecords(options)`       | Export record data              |
+
+## Examples
+
+### Basic Grid
 
-For most of the tools, the configuration is in the `package.json` to reduce the amount of files in your project.
+```html
+<ox-grist
+  .mode=${'GRID'}
+  .config=${gridConfig}
+  .fetchHandler=${fetchData}
+  @record-change=${handleRecordChange}
+></ox-grist>
+```
 
-If you customize the configuration a lot, you can consider moving them to individual files.
+### Editable Grid
 
-## Local Demo with `web-dev-server`
+```html
+<ox-grist
+  .mode=${'GRID'}
+  .config=${{
+    columns: [/* column definitions */],
+    rows: {
+      appendable: true,
+      editable: true,
+      selectable: { multiple: true }
+    }
+  }}
+  .data=${{ records: initialData }}
+></ox-grist>
+```
 
-```bash
-npm start
+### Add Row to Top Button
+
+```html
+<button @click="${() => gristRef.addRecordToTop()}">Add Row to Top</button>
+<ox-grist id="my-grist"></ox-grist>
+
+<script>
+  const gristRef = document.getElementById('my-grist')
+</script>
 ```
 
-To run a local development server that serves the basic demo located in `demo/index.html`
+## License
+
+MIT

package/dist/src/data-grist.d.ts

@@ -324,6 +324,18 @@ export declare class DataGrist extends LitElement implements DataConsumer {
      * an empty record with the `__dirty__` flag set to '+' will be added.
      */
     addRecord(record?: GristRecord): void;
+    /**
+     * Adds a new record to the top of the data grid. The added record is marked as newly created
+     * by setting the `__dirty__` flag to '+'. This flag indicates that the record
+     * is in a "new" state and hasn't been committed to the main data yet.
+     *
+     * This method is useful when you need to add new records at the top of the grid
+     * without changing the default behavior of the appendable row.
+     *
+     * @param {GristRecord} [record] - An optional record to add. If no record is provided,
+     * an empty record with the `__dirty__` flag set to '+' will be added.
+     */
+    addRecordToTop(record?: GristRecord): void;
     /**
      * Retrieves the search text used for filtering records.
      *

package/dist/src/data-grist.js

@@ -830,6 +830,48 @@ let DataGrist = class DataGrist extends LitElement {
             ]
         };
     }
+    /**
+     * Adds a new record to the top of the data grid. The added record is marked as newly created
+     * by setting the `__dirty__` flag to '+'. This flag indicates that the record
+     * is in a "new" state and hasn't been committed to the main data yet.
+     *
+     * This method is useful when you need to add new records at the top of the grid
+     * without changing the default behavior of the appendable row.
+     *
+     * @param {GristRecord} [record] - An optional record to add. If no record is provided,
+     * an empty record with the `__dirty__` flag set to '+' will be added.
+     */
+    addRecordToTop(record) {
+        const newRecord = {
+            ...record,
+            __dirty__: '+'
+        };
+        this._data = {
+            ...this._data,
+            records: [newRecord, ...this.dirtyData.records]
+        };
+        // 새 레코드에 포커스 및 스크롤 처리
+        setTimeout(() => {
+            // 그리드가 있는 경우 첫 번째 행에 포커스 설정
+            if (this.grist) {
+                // 포커스를 첫 번째 행으로 설정 (첫 번째 편집 가능한 셀로)
+                const focusableColumns = this.compiledConfig.columns.filter(column => column.type !== 'gutter' && !column.hidden && column.record.editable);
+                if (focusableColumns.length > 0) {
+                    const columnIndex = this.compiledConfig.columns.indexOf(focusableColumns[0]);
+                    this.grist.dispatchEvent(new CustomEvent('focus-change', {
+                        bubbles: true,
+                        composed: true,
+                        detail: {
+                            row: 0,
+                            column: columnIndex
+                        }
+                    }));
+                }
+                // 스크롤을 맨 위로 이동
+                this.grist.scrollTop = 0;
+            }
+        }, 0);
+    }
     /**
      * Retrieves the search text used for filtering records.
      *