@vii7/div-table-widget 1.0.1

package/LICENSE

@@ -0,0 +1,190 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Support. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2025 DivTable Widget Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,431 @@
+# DivTable Widget
+
+A modern, flexible table widget built with CSS Grid and Flexbox instead of HTML tables, featuring Monaco Editor integration for advanced query capabilities.
+
+![alt](demo.gif)
+
+## Features
+
+- **Modern CSS-based Layout**: Uses CSS Grid and Flexbox for flexible, responsive design
+- **Advanced Query Language**: Monaco Editor integration with intelligent autocomplete and syntax highlighting
+- **Virtual Scrolling**: Efficiently handle large datasets with pagination support
+- **Fixed (Frozen) Columns**: Keep important columns visible while scrolling horizontally
+- **Auto-Fetch**: Automated pagination with play/pause/resume controls
+- **Grouping & Sorting**: Multi-level grouping with 4-state sorting (alphabetical asc/desc, count asc/desc)
+- **Selection Management**: Single and multi-row selection with checkbox support
+- **Filter Selected Rows**: Toggle to show only selected rows
+- **Loading States**: Configurable loading placeholders and progress indicators with visual feedback
+- **Keyboard Navigation**: Full keyboard accessibility with arrow key navigation
+- **Responsive Design**: Adaptive column sizing and mobile-friendly layout
+- **Composite Columns**: Stack multiple fields in one column or create two-line headers
+
+## Installation
+
+```bash
+npm install divtable-widget monaco-editor
+```
+
+## Quick Start
+
+### Basic Usage
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="node_modules/divtable-widget/src/div-table.css">
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/monaco-editor/0.52.2/min/vs/loader.min.js"></script>
+</head>
+<body>
+  <div id="table-container"></div>
+  
+  <script src="node_modules/divtable-widget/src/query.js"></script>
+  <script src="node_modules/divtable-widget/src/div-table.js"></script>
+  <script>
+    // Initialize Monaco Editor
+    require.config({ paths: { vs: 'https://cdnjs.cloudflare.com/ajax/libs/monaco-editor/0.52.2/min/vs' }});
+    require(['vs/editor/editor.main'], function() {
+      const divTable = new DivTable(monaco, {
+        tableWidgetElement: document.getElementById('table-container'),
+        columns: [
+          { field: 'id', header: 'ID', primaryKey: true },
+          { field: 'name', header: 'Name' },
+          { field: 'email', header: 'Email' },
+          { field: 'status', header: 'Status' }
+        ],
+        data: [
+          { id: 1, name: 'John Doe', email: 'john@example.com', status: 'active' },
+          { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'inactive' }
+        ],
+        // New: Set initial grouping and sorting
+        group: 'status', // Group by 'status' field on load
+        sort: { field: 'name', direction: 'asc' }, // Sort by 'name' ascending on load
+        showCheckboxes: true,
+        multiSelect: true,
+        onSelectionChange: (selectedRows) => {
+          console.log('Selected:', selectedRows);
+        }
+      });
+    });
+  </script>
+</body>
+</html>
+```
+
+### With Virtual Scrolling
+
+```javascript
+const divTable = new DivTable(monaco, {
+  tableWidgetElement: document.getElementById('table-container'),
+  columns: [
+    { field: 'id', header: 'ID', primaryKey: true },
+    { field: 'name', header: 'Name' },
+    { field: 'age', header: 'Age' }
+  ],
+  virtualScrolling: true,
+  pageSize: 100,
+  totalRecords: 10000,
+  showAutoFetchButton: true,
+  autoFetchDelay: 500,
+  onNextPage: async () => {
+    const nextPage = await fetchDataFromServer(currentPage + 1);
+    divTable.appendData(nextPage);
+  }
+});
+```
+
+## Configuration Options
+
+### Core Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tableWidgetElement` | HTMLElement | **required** | Container element for the table |
+| `columns` | Array | **required** | Column definitions (see Column Configuration) |
+| `data` | Array | `[]` | Initial data array. If not provided and `onNextPage` is available, first page will be loaded automatically |
+| `showCheckboxes` | Boolean | `true` | Show selection checkboxes |
+| `multiSelect` | Boolean | `true` | Allow multiple row selection |
+| `primaryKeyField` | String | `'id'` | Field to use as primary key (auto-detected from columns if not specified) |
+| `group` | String | `null` | Field to group by initially (applies grouping on load) |
+| `sort` | Object | `null` | Initial sort: `{ field: string, direction: 'asc'|'desc' }` |
+| `fixedColumns` | Number | `0` | Number of columns to freeze on the left side when scrolling horizontally |
+
+### Virtual Scrolling Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `virtualScrolling` | Boolean | `false` | Enable virtual scrolling mode for large datasets |
+| `pageSize` | Number | `100` | Number of rows per page |
+| `totalRecords` | Number | `pageSize * 10` | Total number of records available (for progress calculation) |
+| `loadingThreshold` | Number | `pageSize * 0.8` | Trigger loading when this many rows from end |
+| `scrollThreshold` | Number | `0.95` | Fallback percentage-based scroll threshold |
+| `showAutoFetchButton` | Boolean | `true` | Show auto-fetch play/pause/resume button |
+| `autoFetchDelay` | Number | `500` | Delay between auto-fetch requests (milliseconds) |
+
+### UI Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showLoadingPlaceholder` | Boolean | `true` | Show loading skeleton when no data is present |
+| `showRefreshButton` | Boolean | `false` | Show refresh button in info section |
+
+### Callbacks
+
+| Option | Type | Parameters | Description |
+|--------|------|------------|-------------|
+| `onSelectionChange` | Function | `(selectedRows)` | Called when row selection changes. Receives array of selected data objects |
+| `onRowFocus` | Function | `(rowData, groupInfo)` | Called when a row or group header receives focus |
+| `onNextPage` | Function | `(page, pageSize)` | Called to load next page of data. Should return array of records or Promise |
+| `onPreviousPage` | Function | `(page, pageSize)` | Called to load previous page (optional) |
+| `onRefresh` | Function | `()` | Called when refresh button is clicked. Should reload data |
+
+## Query Language
+
+The widget includes a powerful query language with Monaco Editor integration:
+
+### Syntax
+
+```
+field operator value [AND/OR field operator value]
+```
+
+### Operators
+
+- `=` - Equals
+- `!=` - Not equals
+- `>` - Greater than
+- `<` - Less than
+- `>=` - Greater than or equal
+- `<=` - Less than or equal
+- `CONTAINS` - String contains (case-insensitive)
+- `STARTS_WITH` - String starts with
+- `ENDS_WITH` - String ends with
+- `IN` - Value in list: `status IN (active, pending)`
+- `BETWEEN` - Value in range: `age BETWEEN (18, 65)`
+
+### Examples
+
+```
+status = "active"
+age > 18 AND status = "active"
+name CONTAINS "John"
+created_at BETWEEN (2024-01-01, 2024-12-31)
+status IN (active, pending, review)
+```
+
+## Keyboard Navigation
+
+The widget provides full keyboard accessibility:
+
+### Navigation Keys
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate between rows and group headers |
+| `→` | Expand collapsed group (when focused on group header) |
+| `←` | Collapse expanded group (when focused on group header) |
+| `Space` / `Enter` | Toggle selection of focused row or group |
+| `Tab` | Navigate between checkboxes (if enabled) |
+
+### Focus Behavior
+
+- When checkboxes are enabled, focus moves to the checkbox element
+- When checkboxes are disabled, focus moves to the row element
+- Group headers are always focusable and can be expanded/collapsed with arrow keys
+- Selection changes trigger the `onSelectionChange` callback
+- Focus changes trigger the `onRowFocus` callback
+
+## API Methods
+
+### Data Management
+
+```javascript
+// Apply a query filter to the data
+divTable.applyQuery('status = "active" AND age > 18');
+
+// Add a single record (upsert - updates if exists, adds if new)
+divTable.addRecord({ id: 1, name: 'John Doe', email: 'john@example.com' });
+
+// Remove a record by ID
+const removedRecord = divTable.removeRecord(1);
+
+// Refresh the table data (reloads from onNextPage if virtual scrolling)
+await divTable.refresh();
+```
+
+### Selection
+
+```javascript
+// Get selected rows (returns array of data objects)
+const selected = divTable.getSelectedRows();
+
+// Toggle filter to show only selected rows
+divTable.toggleSelectedRowsFilter(true);  // Show only selected
+divTable.toggleSelectedRowsFilter(false); // Show all rows
+divTable.toggleSelectedRowsFilter();      // Toggle current state
+
+// Clear all selections
+divTable.clearSelection();
+```
+
+### Grouping and Sorting
+
+```javascript
+// Group by a field
+divTable.group('category');
+
+// Clear grouping
+divTable.clearGrouping();
+
+// Sort by a field
+divTable.sort('name', 'asc'); // 'asc' or 'desc'
+divTable.sort('age');         // Toggles between asc/desc
+
+// For grouped fields, sorting cycles through 4 states:
+// 1. Sort groups alphabetically ascending (↑ₐ)
+// 2. Sort groups alphabetically descending (↓z)
+// 3. Sort groups by count ascending (↑₁)
+// 4. Sort groups by count descending (↓₉)
+// 5. Back to no sort
+```
+
+### Auto-Fetch Controls
+
+```javascript
+// The auto-fetch feature automatically loads pages with play/pause/resume controls
+// These methods are called internally by the UI buttons, but can also be called programmatically:
+
+// Start auto-fetching all pages
+divTable.startAutoFetch();
+
+// Stop auto-fetching
+divTable.stopAutoFetch();
+
+// Note: Pause/resume is handled automatically by the UI button
+// The isAutoFetching and autoFetchPaused properties track the state
+```
+
+### Fixed (Frozen) Columns
+
+Keep the first N columns fixed (frozen) on the left side while scrolling horizontally:
+
+```javascript
+const divTable = new DivTable(monaco, {
+  tableWidgetElement: document.getElementById('table-container'),
+  columns: [
+    { field: 'id', header: 'ID', primaryKey: true },
+    { field: 'name', header: 'Name' },
+    { field: 'email', header: 'Email' },
+    { field: 'department', header: 'Department' },
+    { field: 'status', header: 'Status' }
+  ],
+  data: myData,
+  fixedColumns: 2  // Freeze first 2 columns (ID and Name)
+});
+```
+
+**How it works:**
+
+- The first N data columns stay fixed on the left side
+- Remaining columns scroll horizontally
+- Vertical scrolling is synchronized between fixed and scrollable sections
+- Checkbox column (if enabled) is always part of the fixed section
+- Works with composite columns - each composite group counts as one column
+
+## Column Configuration
+
+### Basic Column
+
+```javascript
+{
+  field: 'name',           // Data field name (required)
+  label: 'Full Name',      // Display header (optional, defaults to field)
+  primaryKey: false,       // Is this the primary key? (required for one column)
+  hidden: false,           // Hide column (default: false)
+  groupable: true,         // Allow grouping by this column (default: true)
+  render: (value, item) => `<strong>${value}</strong>` // Custom render function
+}
+```
+
+### Advanced Column Features
+
+#### Responsive Sizing
+
+```javascript
+{
+  field: 'description',
+  label: 'Description',
+  responsive: {
+    size: 'flexible-large' // 'fixed-narrow' (80px), 'fixed-medium' (120px),
+                          // 'flexible-small' (1fr), 'flexible-medium' (2fr),
+                          // 'flexible-large' (3fr)
+  }
+}
+```
+
+#### Composite Cells (Multiple Fields in One Column)
+
+Use `fieldCompositeName` to stack multiple columns into a single visual cell:
+
+```javascript
+// Stack name and age fields vertically in one column
+{
+  field: 'name',
+  label: 'Name',
+  fieldCompositeName: 'person'
+},
+{
+  field: 'age',
+  label: 'Age',
+  render: (value) => value ? `${value} years old` : 'Age not specified',
+  fieldCompositeName: 'person'
+}
+```
+
+Each field in a composite cell:
+
+- Has its own label in the header (stacked vertically)
+- Can have its own render function
+- Can be sorted independently by clicking on its label
+- Can be grouped if `groupable: true`
+
+
+
+### Column Render Function
+
+Custom rendering for cell values:
+
+```javascript
+{
+  field: 'status',
+  label: 'Status',
+  render: (value, item) => {
+    const colors = { active: 'green', inactive: 'red', pending: 'orange' };
+    return `<span style="color: ${colors[value]}">${value}</span>`;
+  }
+}
+```
+
+### Column Types
+
+The widget automatically detects and handles different data types based on the data:
+
+- **Strings**: Text data with CONTAINS, STARTS_WITH, ENDS_WITH operators
+- **Numbers**: Numeric data with comparison operators (>, <, >=, <=)
+- **Dates**: Date/time values with BETWEEN operator
+- **Booleans**: True/false values with = operator
+- **Arrays**: Array values are joined with commas for display
+
+## Styling
+
+The widget uses CSS variables for easy customization:
+
+```css
+.div-table-widget {
+  --table-border-color: #e0e0e0;
+  --header-bg-color: #f5f5f5;
+  --row-hover-color: #f9f9f9;
+  --selected-row-color: #e3f2fd;
+}
+```
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+
+## License
+
+Apache License 2.0
+
+Copyright 2025 DivTable Widget Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Changelog
+
+### Version 1.0.0
+
+- Initial release
+- Core table functionality with CSS Grid/Flexbox layout
+- Monaco Editor integration for query language
+- Virtual scrolling support
+- Auto-fetch pagination
+- Grouping and sorting
+- Selection management
+- Keyboard navigation