pivotgrid-js 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+Copyright (c) 2026 Aleksandr Korolev
+
+Non-Commercial License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software for personal, educational, or
+non-commercial purposes, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. The Software may not be used, in whole or in part, for commercial purposes
+   without a separate commercial license obtained from the author.
+
+3. "Commercial use" means any use of the Software intended for or directed
+   toward commercial advantage or monetary compensation, including but not
+   limited to: use in a commercial product or service, use by a for-profit
+   organization, or use in a client project for payment.
+
+For commercial licensing, contact: korolevalexa@gmail.com
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.commercial

@@ -0,0 +1,60 @@
+PIVOTGRID COMMERCIAL LICENSE AGREEMENT
+
+This Commercial License Agreement ("Agreement") is entered into as of [DATE]
+between Aleksandr Korolev ("Licensor") and [COMPANY/INDIVIDUAL NAME] ("Licensee").
+
+1. GRANT OF LICENSE
+
+   Licensor grants Licensee a non-exclusive, non-transferable, worldwide license
+   to use, integrate, and deploy the PivotGrid software ("Software") in commercial
+   products and services, subject to the terms of this Agreement.
+
+2. PERMITTED USES
+
+   Licensee may:
+   - Use the Software in commercial products or services
+   - Integrate the Software into client projects
+   - Modify the Software for internal use
+   - Deploy the Software on any number of servers owned or operated by Licensee
+
+3. RESTRICTIONS
+
+   Licensee may not:
+   - Resell, sublicense, or redistribute the Software as a standalone product
+   - Remove or alter copyright notices in the Software
+   - Use the Software to create a competing product
+
+4. LICENSE SCOPE
+
+   This license covers: [DESCRIPTION — e.g. "single commercial product", 
+   "unlimited internal projects", "single client project"]
+
+5. PAYMENT
+
+   License fee: [AMOUNT AND CURRENCY]
+   Payment date: [DATE]
+
+6. TERM
+
+   This Agreement is effective from the date of payment and remains in force
+   indefinitely unless terminated due to breach of its terms.
+
+7. TERMINATION
+
+   This Agreement terminates automatically if Licensee breaches any of its terms.
+   Upon termination, Licensee must cease all use of the Software.
+
+8. WARRANTY DISCLAIMER
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. LICENSOR SHALL
+   NOT BE LIABLE FOR ANY DAMAGES ARISING FROM THE USE OF THE SOFTWARE.
+
+9. CONTACT
+
+   Aleksandr Korolev
+   korolevalexa@gmail.com
+
+
+___________________________          ___________________________
+Aleksandr Korolev (Licensor)         [NAME] (Licensee)
+Date: ___________________            Date: ___________________

package/README.dev.md

@@ -0,0 +1,247 @@
+# PivotGrid
+
+Vanilla JS pivot table — no dependencies, no frameworks.
+
+- **Fast** — virtual scroll, columnar storage on TypedArrays, in-memory cache
+- **Flexible** — drag-and-drop dimensions, filters, hierarchical rows and columns
+- **Simple** — one `<div>` and two attributes, nothing else needed
+
+## Concept
+
+All configuration is done through a config file. The grid API is intentionally minimal:
+just create a container with `data-config` and the widget does the rest.
+
+The config is stored on the server and loaded at startup —
+no need to change application code to modify the grid structure.
+
+## Quick Start
+
+```html
+<!-- Styles -->
+<link rel="stylesheet" href="src/pivot.css">
+<link rel="stylesheet" href="src/field-zones.css">
+<link rel="stylesheet" href="widget/widget.css">
+
+<!-- Engine -->
+<script src="engine/dictionary-encoder.js"></script>
+<script src="engine/aggregator.js"></script>
+<script src="engine/column-store.js"></script>
+
+<!-- Providers -->
+<script src="providers/rest-provider.js"></script>
+<script src="providers/array-provider.js"></script>
+
+<!-- Component -->
+<script src="src/pivot.js"></script>
+<script src="src/field-zones.js"></script>
+<script src="src/filter-manager.js"></script>
+
+<!-- Widget -->
+<script src="widget/i18n.js"></script>
+<script src="widget/cache-manager.js"></script>
+<script src="widget/pivot-widget.js"></script>
+
+<!-- Grid -->
+<div id="my-pivot"
+     data-config="sales"
+     data-server="http://localhost:8000">
+</div>
+```
+
+The widget builds the entire UI structure inside the container automatically.
+
+## Demo Without a Server
+
+```html
+<!-- Demo data and config -->
+<script src="demo/demo-data.js"></script>
+<script src="demo/demo-config.js"></script>
+
+<div id="my-pivot" data-demo="true"></div>
+```
+
+## Container Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `data-config` | Config name on the server | `"sales"` |
+| `data-server` | Server URL | `"http://localhost:8000"` |
+| `data-demo` | Demo mode without a server | `"true"` |
+| `data-lang` | Interface language | `"ru"` / `"en"` |
+| `data-standalone` | Use an existing HTML structure | `"true"` |
+
+## Config
+
+Configs are stored on the server at `configs/{name}.json`:
+
+```json
+{
+  "query": "SELECT * FROM sales_data",
+
+  "dimensions": ["region", "category", "channel"],
+  "measures":   ["revenue", "units"],
+  "funcs":      ["sum", "avg", "count", "min", "max"],
+
+  "fields": {
+    "region":   { "label": "region",   "title": "Region" },
+    "category": { "label": "category", "title": "Category" },
+    "channel":  { "label": "channel",  "title": "Channel" },
+    "revenue":  { "label": "revenue",  "title": "Revenue" },
+    "units":    { "label": "units",    "title": "Units" }
+  },
+
+  "cachedDimensions": ["region", "category"],
+
+  "rows":    ["region"],
+  "columns": [],
+  "measure": "revenue",
+  "func":    "sum",
+
+  "maxCachedRows":       500000,
+  "filterCheckboxLimit": 5
+}
+```
+
+## Server
+
+`server/server.py` — a lightweight Python proxy to the database.
+
+```bash
+pip install psycopg2-binary
+python server/server.py
+```
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/query` | Execute a SQL query |
+| `GET` | `/configs` | List all configs |
+| `GET` | `/configs/{name}` | Get a config |
+| `POST` | `/configs/{name}` | Save a config |
+| `GET` | `/server-config` | DB settings (password excluded) |
+| `POST` | `/server-config` | Save DB settings |
+
+### DB Connectors
+
+PostgreSQL is included by default. To add a custom database, create a file in `server/connectors/`:
+
+```python
+# server/connectors/mydb.py
+NAME = "My Database"
+
+def execute_query(query):
+    # your implementation
+    return [{"col": "val"}, ...]
+```
+
+The server picks up the new connector on next startup.
+
+## Config Editor
+
+A visual config editor — `config/config-editor.html`.
+
+- Fetch columns from the database with one click
+- Configure dimensions, measures, sortKey
+- Drag-and-drop initial state (rows / columns / cache)
+- Save config to the server
+- Preview changes without saving
+
+## Grid API
+
+```js
+// Expand / collapse rows
+grid.expandAll()
+grid.collapseAll()
+grid.expandToDepth(depth)
+
+// Expand / collapse columns
+grid.expandAllCols()
+grid.collapseAllCols()
+
+// Subtotals
+grid.toggleSubtotals(visible)
+
+// Update data
+grid.setResult(result, { rows, columns, measure, fieldDefs })
+```
+
+## Drillthrough
+
+Clicking a cell dispatches a `drillthrough` event:
+
+```js
+container.addEventListener('drillthrough', (e) => {
+  const { context, value } = e.detail;
+  // context = { region: 'North', channel: 'Online' }
+  // value   = aggregated cell value
+});
+```
+
+Click behaviour is configured in the config:
+
+```json
+"drillthroughQuery": "SELECT * FROM sales WHERE {filters} LIMIT 200"
+```
+
+or
+
+```json
+"drillthroughUrl": "https://myapp.com/details"
+```
+
+## Internationalization
+
+```html
+<div data-config="sales" data-lang="en"></div>
+```
+
+`ru` and `en` are supported. To add a language, extend the `I18N` object in `widget/i18n.js`.
+
+## Project Structure
+
+```
+├── src/               # Component
+│   ├── pivot.js
+│   ├── pivot.css
+│   ├── field-zones.js
+│   ├── field-zones.css
+│   └── filter-manager.js
+│
+├── engine/            # Aggregation engine
+│   ├── aggregator.js
+│   ├── column-store.js
+│   └── dictionary-encoder.js
+│
+├── providers/         # Data providers
+│   ├── rest-provider.js
+│   └── array-provider.js
+│
+├── widget/            # Widget (UI + init)
+│   ├── pivot-widget.js
+│   ├── cache-manager.js
+│   ├── i18n.js
+│   └── widget.css
+│
+├── config/            # Config editor
+│   ├── config-editor.html
+│   ├── config-editor.css
+│   └── config-editor.js
+│
+├── server/            # Python server
+│   ├── server.py
+│   └── connectors/
+│       └── postgresql.py
+│
+└── demo/              # Demo
+    ├── index.html
+    ├── example.html
+    ├── demo-example.html
+    ├── demo-data.js
+    └── demo-config.js
+```
+
+## License
+
+Free for personal and non-commercial use.  
+For commercial use, a license is required — contact [korolevalexa@gmail.com](mailto:korolevalexa@gmail.com).

package/README.md

@@ -0,0 +1,253 @@
+# PivotGrid JS
+
+Vanilla JS pivot table — no dependencies, no frameworks.
+
+- **Fast** — virtual scroll, columnar storage on TypedArrays, in-memory cache
+- **Flexible** — drag-and-drop dimensions, filters, hierarchical rows and columns
+- **Simple** — one `<div>` and few attributes, nothing else needed
+
+**[Live Demo](https://windowrepino.ru/pivot/demo/demo-example.html)**
+
+![PivotGrid](https://raw.githubusercontent.com/AlexKorole/pivotgrid/main/assets/screenshot.png)
+
+## Installation
+
+```bash
+npm install pivotgrid-js
+```
+
+## Quick Start
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="node_modules/pivotgrid-js/dist/pivotgrid.css">
+</head>
+<body>
+
+  <div id="my-pivot"
+       data-config="sales"
+       data-server="http://localhost:8000"
+       data-lang="en">
+  </div>
+
+  <script src="node_modules/pivotgrid-js/dist/pivotgrid.js"></script>
+  <script src="node_modules/pivotgrid-js/widget/pivot-widget.js"></script>
+
+</body>
+</html>
+```
+
+## Demo Mode (no server)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="node_modules/pivotgrid-js/dist/pivotgrid.css">
+</head>
+<body>
+  <div id="my-pivot" data-demo="true" data-lang="en"></div>
+
+  <script src="node_modules/pivotgrid-js/dist/pivotgrid.js"></script>
+  <script src="node_modules/pivotgrid-js/demo_data/demo-data.js"></script>
+  <script src="node_modules/pivotgrid-js/demo_data/demo-config.js"></script>
+  <script src="node_modules/pivotgrid-js/widget/pivot-widget.js"></script>
+</body>
+</html>
+```
+
+## Container Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `data-config` | Config name on the server | `"sales"` |
+| `data-server` | Server URL | `"http://localhost:8000"` |
+| `data-demo` | Demo mode without a server | `"true"` |
+| `data-lang` | Interface language | `"ru"` / `"en"` |
+| `data-standalone` | Use an existing HTML structure | `"true"` |
+
+## Config
+
+Configs are stored on the server at `server/configs/{name}.json`:
+
+```json
+{
+  "query": "SELECT * FROM sales_data",
+
+  "dimensions": ["region", "category", "channel"],
+  "measures":   ["revenue", "units"],
+  "funcs":      ["sum", "avg", "count", "min", "max"],
+
+  "fields": {
+    "region":   { "label": "region",   "title": "Region" },
+    "category": { "label": "category", "title": "Category" },
+    "channel":  { "label": "channel",  "title": "Channel" },
+    "revenue":  { "label": "revenue",  "title": "Revenue" },
+    "units":    { "label": "units",    "title": "Units" }
+  },
+
+  "cachedDimensions": ["region", "category"],
+
+  "rows":    ["region"],
+  "columns": [],
+  "measure": "revenue",
+  "func":    "sum",
+
+  "maxCachedRows":       500000,
+  "filterCheckboxLimit": 5,
+
+  "drillthroughQuery": "SELECT * FROM sales_data WHERE {filters} LIMIT 200"
+}
+```
+
+### Config Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `query` | `string` | Base SQL query |
+| `dimensions` | `string[]` | List of dimension field names |
+| `measures` | `string[]` | List of measure field names |
+| `funcs` | `string[]` | Aggregation functions: `sum`, `avg`, `count`, `min`, `max`, `stddev`, `variance` |
+| `fields` | `object` | Field definitions — see below |
+| `cachedDimensions` | `string[]` | Dimensions to pre-aggregate and cache on startup |
+| `rows` | `string[]` | Initial row dimensions |
+| `columns` | `string[]` | Initial column dimensions |
+| `measure` | `string` | Initial active measure |
+| `func` | `string` | Initial aggregation function |
+| `maxCachedRows` | `number` | Maximum rows in cache (default: `500000`) |
+| `filterCheckboxLimit` | `number` | Max distinct values to show as checkboxes in filter popup (default: `30`) |
+| `drillthroughQuery` | `string` | SQL for drillthrough panel. Use `{filters}` as placeholder |
+| `drillthroughUrl` | `string` | External URL for drillthrough. Filters are appended as query params |
+
+### Field Definition
+
+Each entry in `fields` can have:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `label` | `string` | Actual column name in the database |
+| `title` | `string` | Display name shown in the UI |
+| `sortKey` | `string` | Column to sort by instead of the label (useful for month names etc.) |
+
+Example — month sorted by number:
+```json
+"sale_month": {
+  "label": "sale_month_name",
+  "title": "Month",
+  "sortKey": "sale_month_num"
+}
+```
+
+## Server
+
+A lightweight Python proxy to your database is included:
+
+```bash
+pip install psycopg2-binary
+python node_modules/pivotgrid-js/server/server.py
+```
+
+See `node_modules/pivotgrid-js/server/README.md` for full server documentation.
+
+## Config Editor
+
+A visual config editor is included. Open it locally:
+
+```
+node_modules/pivotgrid-js/config/config-editor.html
+```
+
+![Config Editor](https://raw.githubusercontent.com/AlexKorole/pivotgrid/main/assets/config-editor.png)
+
+Features:
+- Fetch columns from the database with one click
+- Configure dimensions, measures, sortKey
+- Drag-and-drop initial state (rows / columns / cache)
+- Save config to the server
+- Preview changes without saving
+
+## Grid API
+
+```js
+// Expand / collapse rows
+grid.expandAll()
+grid.collapseAll()
+grid.expandToDepth(depth)   // e.g. expandToDepth(1) — first level only
+
+// Expand / collapse columns
+grid.expandAllCols()
+grid.collapseAllCols()
+
+// Subtotals
+grid.toggleSubtotals(visible)
+
+// Update data
+grid.setResult(result, { rows, columns, measure, fieldDefs })
+```
+
+## Drillthrough
+
+Three ways to handle cell clicks:
+
+### 1. Built-in panel (SQL query)
+
+Add `drillthroughQuery` to your config:
+
+```json
+"drillthroughQuery": "SELECT * FROM sales_data WHERE {filters} LIMIT 200"
+```
+
+A detail panel slides up at the bottom of the page showing the raw rows.
+
+### 2. External URL
+
+Add `drillthroughUrl` to your config:
+
+```json
+"drillthroughUrl": "https://myapp.com/details"
+```
+
+Opens the URL in a new tab with filters appended as query parameters:
+`https://myapp.com/details?region=North&channel=Online`
+
+### 3. Custom handler
+
+Listen for the `drillthrough` event on the container:
+
+```js
+document.getElementById('my-pivot').addEventListener('drillthrough', (e) => {
+  const { context, value } = e.detail;
+  // context = { region: 'North', channel: 'Online' }
+  // value   = aggregated cell value
+  // your custom logic here
+});
+```
+
+If neither `drillthroughQuery` nor `drillthroughUrl` is set in the config,
+only your custom handler fires.
+
+## Internationalization
+
+`ru` and `en` are supported out of the box:
+
+```html
+<div data-config="sales" data-lang="en"></div>
+```
+
+To add a language, extend the `I18N` object in `widget/i18n.js`.
+
+## Using with a Bundler
+
+```js
+import { PivotGrid, Aggregator, RestProvider, ArrayProvider } from 'pivotgrid-js';
+```
+
+Available exports: `PivotGrid`, `Aggregator`, `ColumnStore`, `DictionaryEncoder`,
+`RestProvider`, `ArrayProvider`, `FieldZones`, `FilterManager`, `CacheManager`, `I18N`.
+
+## License
+
+Free for personal and non-commercial use.  
+For commercial use, a license is required — contact [korolevalexa@gmail.com](mailto:korolevalexa@gmail.com).