@jh-grid/jhgrid-js 0.1.2 → 0.2.0

package/README.md

@@ -8,46 +8,22 @@ performance, editing, filtering, and frozen columns, running in your browser rig
 
 ![JH Grid screenshot](docs/images/jhgrid.png)
 
-> This repository distributes the **pre-built bundle** (`jhgrid.esm.js` / `jhgrid.js` /
-> `jhgrid.min.js`) plus its documentation, not the buildable source tree. See [`docs/`](docs/README.md)
-> for the full reference.
-
 ---
 
 ## Features
 
-- Smooth rendering via `requestAnimationFrame` + Canvas 2D, synced to your display's native refresh rate (60Hz, 120Hz, 144Hz, etc.), not capped at 60fps
-- 2D virtual scrolling: only visible cells are drawn
-- Chunk-based async data loading with prefetch & cache
-- HiDPI / Retina display support (devicePixelRatio scaling)
-- Draggable scrollbars (vertical + horizontal)
-- Left/right frozen columns (`frozenCols` / `frozenColsRight`)
-- **Cell click**: single cell selection with blue border highlight
-- **Cell drag**: multi-cell range selection with fill overlay
-- **Row selection**: single/multi row selection (`rowSelection: 'single' | 'multi'`), with an optional select-all header checkbox (`columnDefs[].headerCheckbox`)
-- **Row drag reorder**: drag rows by the row-number gutter (`rowReorder: true`)
-- **Double-click to edit**: per-column editable/readonly control
-- **Ctrl+C / Ctrl+V**: copy & paste (single cell or range, TSV format)
-- **Ctrl+Z / Ctrl+Y**: undo / redo (cell edits, row/column add/delete)
-- **Column validation**: declarative required/pattern/min/max/length/custom rules with red-border + tooltip error display (`min`/`max` compare chronologically on a `type: 'date'` column)
-- **In-cell action buttons**: `type: 'button'` columns render a clickable pill per row (e.g. "Delete", "Approve") independent of `editableCols`
-- **Date / rich-text / image cell types**: `type: 'date'` opens a native date/datetime picker; `type: 'richtext'` opens an inline bold/italic/underline/strikethrough editor; `type: 'image'` renders a cell image (`fit: 'cover' | 'contain'`, size-aware decoding, shared LRU cache), plus a pluggable `CellEditors`/`CellRenderers` registry (`registerCellEditor()`/`registerCellRenderer()`) for fully custom editors and renderers
-- **Set filter**: checkbox list of a column's distinct values in the header filter panel (`setFilterValues()`)
-- **Quick filter**: global cross-column search term (`setQuickFilter()` / `getQuickFilter()` / `clearQuickFilter()`)
-- **Single-column sort**: `setSort()` / `removeSort()` / `clearSort()`
-- **Row / column CRUD**: `addRow()`/`deleteRow()`/`undeleteRow()`, `addColumn()`/`deleteColumn()`/`undeleteColumn()`, with matching `getNew*()`/`getDeleted*()` accessors for diff-based saves
-- **Column hide/show**: `hideColumn()` / `showColumn()` / `isColumnVisible()` / `getHiddenColumns()`, plus per-row/column resize (`setRowHeight()`, `autoFitColumns()`)
-- **Multi-level header groups**: `columnDefs[].group` (or explicit `headerRows`) merges header cells across levels
-- **Per-row / per-cell styling callbacks**: `rowHighlighter` / `cellBackground` for conditional formatting
-- **State snapshot/restore**: `getState()` / `setState()` for saving and restoring grid state (filters, sort, column order/visibility, edits)
-- **Built-in localization**: `locale` option with bundled `KO_I18N` / `JA_I18N` / `ZH_I18N` text packs, per-key `i18n` overrides, and locale-aware number/date/currency cell rendering
-- **Accessibility**: ARIA labeling, keyboard-navigable header/row focus, and automatic high-contrast (`forced-colors`) theme remapping
-- **CSV export + print preview**: `exportCsv()`, `printGrid()`
-- **Arrow key navigation**: keyboard-driven cell movement
-- **Enter / Tab**: commit edit and move to next row / column
-- Text overflow with ellipsis (`…`): O(log n) binary search
-- Fully themeable
-- Zero dependencies
+- **Canvas rendering + 2D virtualization** - smooth at 60/120/144Hz, HiDPI-aware
+- **Large-data loading** - chunk-based async loading with prefetch & cache
+- **Frozen columns & scrollbars** - left/right freezing with draggable vertical/horizontal scrollbars
+- **Selection & row operations** - cell/range selection, single/multi row selection, row drag reorder
+- **Editing** - inline editing, validation, undo/redo, TSV copy & paste
+- **Rich cell types** - dropdown, multiselect, checkbox, date, richtext, image, button, plus custom editors/renderers
+- **Filtering & sorting** - set filter, quick filter, single-column sort
+- **CRUD & change tracking** - row/column add/delete with diff-based persistence
+- **Headers & styling** - multi-level headers, conditional row/cell styling
+- **State & export** - state snapshot/restore, CSV export, print preview
+- **i18n & accessibility** - KO/JA/ZH localization, ARIA, keyboard navigation, high-contrast support
+- **Zero dependencies & theming** - fully themeable with no runtime dependencies
 
 ---
 
@@ -68,25 +44,27 @@ The package ships as **ES Modules only** and includes its own TypeScript declara
 modern Node ESM can consume it directly. CommonJS `require('@jh-grid/jhgrid-js')` is *not* supported; use a
 dynamic `await import('@jh-grid/jhgrid-js')` if you must load it from a CJS file.
 
-### Option B: Static ES module (no bundler)
+### Option B: ES Module (source as-is)
 
-`jhgrid.esm.js` is a single self-contained ES module file: deploy it as-is as a static resource
-(e.g. from a Spring Boot static resource path) and import it directly, no build step required:
+No build step or package manager: deploy the source as-is as a static resource and import it as
+an ES Module (e.g. from a Spring Boot static resource path).
 
 ```html
 <script type="module">
-  import { JHGrid } from '/static/jhgrid.esm.js';
+  import { JHGrid } from '/canvas-grid/index.js';
 </script>
 ```
 
 ### Option C: CDN (single bundled script)
 
-`jhgrid.min.js` is an IIFE build served straight from this repository via jsDelivr, no npm
-install required. Everything is exposed on a single global, `JHGrid` (the grid constructor is
+A pre-bundled IIFE build is generated with `npm run build` (`esbuild`, see
+`dist/jhgrid/dist/jhgrid.min.js`) and served straight from GitHub via jsDelivr, no npm publish
+required. Everything is exposed on a single global, `JHGrid` (the grid constructor is
 `JHGrid.JHGrid`):
 
 ```html
-<!-- pin an exact tag/commit for production; @latest always serves the latest commit on that branch -->
+<!-- pin an exact tag for production; @latest resolves to the newest git tag -->
+<!-- dist/jhgrid/'s contents are pushed as the repo root, so the CDN path is dist/jhgrid.min.js -->
 <script src="https://cdn.jsdelivr.net/gh/JH-Grid/JHGrid@latest/dist/jhgrid.min.js"></script>
 <script>
   const grid = new JHGrid.JHGrid({
@@ -96,6 +74,10 @@ install required. Everything is exposed on a single global, `JHGrid` (the grid c
 </script>
 ```
 
+Run `npm run build` (minified, for CDN/production) or `npm run build:dev` (unminified, for
+debugging) after changing source files; the `dist/` output must be committed for jsDelivr to
+serve it.
+
 ---
 
 ## Quick Start
@@ -169,14 +151,21 @@ const grid = new JHGrid({
 See [`fetchPage`](docs/api.md#fetchpage-single-callback-alternative) for a single-callback
 alternative to `fetchMeta`+`fetchData` when your backend already returns both together.
 
+The kitchen-sink demo exercises every column type, renderer, and callback at once:
+
+```bash
+node demo/server.mjs
+# open http://localhost:8123/
+```
+
 ---
 
 ## Documentation
 
 **[Browse the docs online](https://jh-grid.github.io/JHGrid/)**, or read them directly in
-[`docs/`](docs/README.md):
+[`docs/`](docs/README.md), since this README stays a quick landing page:
 
-- **[API Reference](docs/api.md)**: every constructor option, the data source interface, pagination, and all public methods
+- **[API Reference](docs/api.md)**: every constructor option, the data source interface, pagination, and all public methods (filtering, sorting, row/column CRUD, editors, export)
 - **[Theming](docs/theming.md)**: the full theme object, styling with your own CSS via `--jhg-*` custom properties, and canvas motion tuning
 - **[Interaction Reference](docs/interaction.md)**: every mouse and keyboard interaction
 - **[Spring Boot Integration](docs/integration.md)**: backend API shape and SQL pagination