@operato/data-grist 9.0.0-beta.6 → 9.0.0-beta.61

package/CHANGELOG.md

@@ -3,6 +3,236 @@
 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.61](https://github.com/hatiolab/operato/compare/v9.0.0-beta.60...v9.0.0-beta.61) (2025-04-12)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [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
+
+
+
+
+
+## [9.0.0-beta.53](https://github.com/hatiolab/operato/compare/v9.0.0-beta.52...v9.0.0-beta.53) (2025-03-04)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.52](https://github.com/hatiolab/operato/compare/v9.0.0-beta.51...v9.0.0-beta.52) (2025-03-04)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.49](https://github.com/hatiolab/operato/compare/v9.0.0-beta.48...v9.0.0-beta.49) (2025-02-14)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.48](https://github.com/hatiolab/operato/compare/v9.0.0-beta.47...v9.0.0-beta.48) (2025-02-14)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.47](https://github.com/hatiolab/operato/compare/v9.0.0-beta.46...v9.0.0-beta.47) (2025-02-14)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.41](https://github.com/hatiolab/operato/compare/v9.0.0-beta.40...v9.0.0-beta.41) (2025-02-09)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.38](https://github.com/hatiolab/operato/compare/v9.0.0-beta.37...v9.0.0-beta.38) (2025-02-02)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.37](https://github.com/hatiolab/operato/compare/v9.0.0-beta.36...v9.0.0-beta.37) (2025-02-01)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.35](https://github.com/hatiolab/operato/compare/v9.0.0-beta.34...v9.0.0-beta.35) (2025-02-01)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.34](https://github.com/hatiolab/operato/compare/v9.0.0-beta.33...v9.0.0-beta.34) (2025-01-31)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.33](https://github.com/hatiolab/operato/compare/v9.0.0-beta.32...v9.0.0-beta.33) (2025-01-31)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.32](https://github.com/hatiolab/operato/compare/v9.0.0-beta.31...v9.0.0-beta.32) (2025-01-31)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.31](https://github.com/hatiolab/operato/compare/v9.0.0-beta.30...v9.0.0-beta.31) (2025-01-31)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.29](https://github.com/hatiolab/operato/compare/v9.0.0-beta.28...v9.0.0-beta.29) (2025-01-30)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.28](https://github.com/hatiolab/operato/compare/v9.0.0-beta.27...v9.0.0-beta.28) (2025-01-28)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.21](https://github.com/hatiolab/operato/compare/v9.0.0-beta.20...v9.0.0-beta.21) (2025-01-28)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.20](https://github.com/hatiolab/operato/compare/v9.0.0-beta.19...v9.0.0-beta.20) (2025-01-27)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.18](https://github.com/hatiolab/operato/compare/v9.0.0-beta.17...v9.0.0-beta.18) (2025-01-27)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.16](https://github.com/hatiolab/operato/compare/v9.0.0-beta.15...v9.0.0-beta.16) (2025-01-27)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.15](https://github.com/hatiolab/operato/compare/v9.0.0-beta.14...v9.0.0-beta.15) (2025-01-27)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
+## [9.0.0-beta.14](https://github.com/hatiolab/operato/compare/v9.0.0-beta.13...v9.0.0-beta.14) (2025-01-27)
+
+
+### :rocket: New Features
+
+* module property-panel ([d78e4cf](https://github.com/hatiolab/operato/commit/d78e4cf7080b95fa74e61b42094b9f3f59f1409b))
+
+
+
+## [9.0.0-beta.11](https://github.com/hatiolab/operato/compare/v9.0.0-beta.10...v9.0.0-beta.11) (2025-01-25)
+
+
+### :bug: Bug Fix
+
+* tsconfig option useDefineForClassFields=false ([0d77c0a](https://github.com/hatiolab/operato/commit/0d77c0aa620282c65b3c05f8e0b559e82836b6ab))
+
+
+
+## [9.0.0-beta.10](https://github.com/hatiolab/operato/compare/v9.0.0-beta.9...v9.0.0-beta.10) (2025-01-25)
+
+
+### :bug: Bug Fix
+
+* i18next@24.2.1 ([1c5920c](https://github.com/hatiolab/operato/commit/1c5920c6f77d28f07051a0a49997b9fb1dbf08bf))
+* tweak tsconfig.json ([3c424b1](https://github.com/hatiolab/operato/commit/3c424b18d046f95d5619076d113d49a4b4dc9bbb))
+
+
+
+## [9.0.0-beta.7](https://github.com/hatiolab/operato/compare/v9.0.0-beta.6...v9.0.0-beta.7) (2025-01-20)
+
+**Note:** Version bump only for package @operato/data-grist
+
+
+
+
+
 ## [9.0.0-beta.6](https://github.com/hatiolab/operato/compare/v9.0.0-beta.5...v9.0.0-beta.6) (2025-01-20)
 
 

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