@itrocks/table 0.0.21 → 0.1.0

package/README.md

@@ -8,6 +8,10 @@
 
 A lightweight, modular HTML table offering near-spreadsheet features such as edit, freeze, lock, scroll, and more.
 
+*This documentation was written by an artificial intelligence and may contain errors or approximations.
+It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
+please feel free to contact the author of this package.*
+
 ## Installation
 
 ```bash
@@ -16,4 +20,207 @@ npm i @itrocks/table
 
 ## Usage
 
-Check out the [GitHub demo folder](https://github.com/itrocks-ts/table/tree/master/demo) for a complete demonstration.
+`@itrocks/table` is a lightweight, modular JavaScript table component that
+turns a plain HTML `<table>` into a near‑spreadsheet widget: editable
+cells, frozen columns, locked headers, horizontal and vertical scrolling,
+and more.
+
+At runtime you create `Table` instances from existing DOM elements.
+
+### Minimal example
+
+```ts
+import { tableBySelector } from '@itrocks/table'
+
+// Turn all matching <table> elements into interactive tables
+const tables = tableBySelector('.js-data-table')
+
+// Optionally keep a reference to one table
+const table = tables[0]
+```
+
+Make sure the DOM is ready before you call `tableBySelector` (for example
+after `DOMContentLoaded` or in your framework's mounted hook).
+
+You can also construct a table directly from an element:
+
+```ts
+import { tableByElement } from '@itrocks/table'
+
+const element = document.querySelector('table#users') as HTMLTableElement
+const table   = tableByElement(element)
+```
+
+For more advanced usage (plugins, styling, demos), check out the
+[GitHub demo folder](https://github.com/itrocks-ts/table/tree/master/demo).
+
+## API
+
+The public API is intentionally small and focuses on a single `Table`
+class plus a few helpers.
+
+### `applyStyleSheets()`
+
+```ts
+import { applyStyleSheets } from '@itrocks/table'
+
+applyStyleSheets()
+```
+
+Forces the table module to (re)apply its internal style sheets. In most
+applications you do not need to call this manually: it is handled when
+creating `Table` instances. It can be useful in advanced integration
+scenarios (dynamic theme switch, hot‑reloaded styles, etc.).
+
+### `garbageCollector()`
+
+```ts
+import { garbageCollector } from '@itrocks/table'
+
+garbageCollector()
+```
+
+Runs an internal cleanup pass to detach listeners and release resources
+from tables that are no longer present in the DOM. You might call this
+periodically in long‑running pages where tables are created and removed
+dynamically.
+
+### `getTables()`
+
+```ts
+import { getTables } from '@itrocks/table'
+
+const tables = getTables()
+```
+
+Returns the list of all `Table` instances currently managed by the
+module. This is mainly useful for debugging or global operations (for
+example applying a plugin to every existing table).
+
+### `type Options = PluginOptions<Table>`
+
+Configuration object passed when creating a `Table`. It is based on the
+generic plugin system from
+[`@itrocks/plugin`](https://github.com/itrocks-ts/plugin).
+
+Typical usage:
+
+```ts
+import type { Options } from '@itrocks/table'
+
+const options: Partial<Options> = {
+	// enable / configure plugins here
+}
+```
+
+The exact shape of the options depends on the plugins you enable (edit,
+freeze, reorder, etc.). Refer to each plugin's documentation and the
+demo code for details.
+
+### `class Table extends HasPlugins<Table>`
+
+Represents an interactive table instance bound to a single
+`HTMLTableElement`.
+
+#### Constructor
+
+```ts
+import { Table } from '@itrocks/table'
+
+const table = new Table(element, options)
+```
+
+Parameters:
+
+- `element: HTMLTableElement` – the DOM table to enhance.
+- `options?: Partial<Options>` – optional configuration and plugins.
+
+#### Properties
+
+- `element: HTMLTableElement` – underlying table element.
+- `id: number` – numeric identifier assigned to the table instance.
+- `selector: string` – selector used when the table was created (when
+  relevant).
+- `onReset: (() => void)[]` – list of callbacks invoked when the table
+  is reset.
+- `styleSheet: string[]` – list of CSS rules associated with this table
+  instance.
+
+#### Methods
+
+##### `addEventListener(element, type, listener, options?)`
+
+Delegates the registration of an event listener through the table
+infrastructure, so it can be properly cleaned up on reset or removal.
+
+```ts
+table.addEventListener(document, 'keydown', event => {
+	// react to keyboard shortcuts related to this table
+})
+```
+
+##### `cellColumnNumber(cell: HTMLTableCellElement): number`
+
+Returns the zero‑based column index of the given table cell within its
+row. This is handy when writing plugins that need to know which column a
+cell belongs to.
+
+##### `reset(): Table`
+
+Resets the table to its initial state:
+
+- clears plugin state,
+- reapplies default configuration,
+- triggers all callbacks registered in `onReset`.
+
+```ts
+table.reset()
+```
+
+### Helper constructors
+
+In addition to the `Table` class, the module exposes convenience
+functions to create tables from different inputs.
+
+#### `tableByElement(element, options?)`
+
+```ts
+import { tableByElement } from '@itrocks/table'
+
+const table = tableByElement(element, { /* options */ })
+```
+
+Creates (or returns an existing) `Table` instance for the given
+`HTMLTableElement`.
+
+#### `tableByElements(elements, options?)`
+
+```ts
+import { tableByElements } from '@itrocks/table'
+
+const nodeList = document.querySelectorAll('table.data')
+const tables   = tableByElements(nodeList)
+```
+
+Accepts an array or a `NodeListOf<HTMLTableElement>` and returns an
+array of `Table` instances.
+
+#### `tableBySelector(selector, options?)`
+
+```ts
+import { tableBySelector } from '@itrocks/table'
+
+const tables = tableBySelector('.js-data-table')
+```
+
+Finds all tables matching the CSS selector and returns the corresponding
+`Table` instances.
+
+## Typical use cases
+
+- Enhance existing HTML tables with spreadsheet‑like behaviours (edit,
+  freeze, lock, scroll) without rewriting the markup.
+- Build rich back‑office or data‑entry screens where users can edit
+  multiple rows directly in a table.
+- Implement custom plugins on top of `HasPlugins<Table>` to add domain‑
+  specific features (validation, inline actions, totals rows, etc.).

package/column-reorder.d.ts

@@ -1,8 +1,8 @@
-import { Plugin } from '../../plugin/plugin.js';
+import { Plugin } from '../plugin/plugin.js';
 import { HTMLTableFreezeElement } from './freeze.js';
 import { Table } from './table.js';
 export declare class TableColumnReorder extends Plugin<Table> {
     reorderCells: NodeListOf<HTMLTableFreezeElement>;
-    constructor(table: Table);
+    init(): void;
     protected getReorderCells(): NodeListOf<HTMLTableFreezeElement>;
 }

package/column-reorder.js

@@ -1,13 +1,13 @@
 import { Plugin } from '../plugin/plugin.js';
 export class TableColumnReorder extends Plugin {
     reorderCells;
-    constructor(table) {
-        super(table);
+    init() {
         this.reorderCells = this.getReorderCells();
         let downed;
         let dragging;
         let mouse = new DOMRect;
         let mouseFrom = new DOMRect;
+        const table = this.of;
         for (const cell of Array.from(this.reorderCells)) {
             table.addEventListener(cell, 'mousedown', event => {
                 console.log('mousedown', event.target);

package/edit/lock.d.ts

@@ -1,15 +1,15 @@
-import { Plugin } from '../../../plugin/plugin.js';
+import { Plugin } from '../../plugin/plugin.js';
+import { PluginOptions } from '../../plugin/plugin.js';
 import { Table } from '../table.js';
-declare class Options {
+declare class Options extends PluginOptions {
     nonEditableConditions: {
         [index: string]: string;
     };
 }
-export declare class TableEditLock extends Plugin<Table> {
-    options: Options;
-    constructor(table: Table, options?: Partial<Options>);
+export declare class TableEditLock extends Plugin<Table, Options> {
     colCell(cell: HTMLTableCellElement): HTMLTableCellElement | HTMLTableColElement;
     closestEditableCell(editable?: HTMLTableCellElement): HTMLTableCellElement | undefined;
-    static defaultOptions(): Options;
+    defaultOptions(): Options;
+    init(): void;
 }
 export {};

package/edit/lock.js

@@ -1,19 +1,12 @@
 import { Plugin } from '../../plugin/plugin.js';
-class Options {
+import { PluginOptions } from '../../plugin/plugin.js';
+class Options extends PluginOptions {
     nonEditableConditions = {
         'closest': 'tfoot, thead, [data-lock]',
         'col': '[data-lock]'
     };
 }
 export class TableEditLock extends Plugin {
-    options = new Options;
-    constructor(table, options = {}) {
-        super(table);
-        Object.assign(this.options, options);
-        const tableEdit = table.plugins.TableEdit;
-        const superClosestEditableCell = tableEdit.closestEditableCell;
-        tableEdit.closestEditableCell = target => this.closestEditableCell(superClosestEditableCell.call(tableEdit, target));
-    }
     colCell(cell) {
         const table = cell.closest('table');
         const position = this.of.cellColumnNumber(cell);
@@ -61,7 +54,12 @@ export class TableEditLock extends Plugin {
         }
         return editable;
     }
-    static defaultOptions() {
-        return new Options;
+    defaultOptions() {
+        return new Options();
+    }
+    init() {
+        const tableEdit = this.of.plugins.TableEdit;
+        const superClosestEditableCell = tableEdit.closestEditableCell;
+        tableEdit.closestEditableCell = target => this.closestEditableCell(superClosestEditableCell.call(tableEdit, target));
     }
 }

package/edit/move.d.ts

@@ -1,10 +1,10 @@
-import { HTMLEditableElement } from '../../../contenteditable/contenteditable.js';
-import { Plugin } from '../../../plugin/plugin.js';
+import { HTMLEditableElement } from '../../contenteditable/contenteditable.js';
+import { Plugin } from '../../plugin/plugin.js';
 import { TableEdit } from '../edit.js';
 import { Table } from '../table.js';
 export declare class TableEditMove extends Plugin<Table> {
     tableEdit: TableEdit;
-    constructor(table: Table);
+    init(): void;
     selectNextColumn(): void;
     selectNextRow(): void;
     selectPreviousColumn(): void;

package/edit/move.js

@@ -1,9 +1,8 @@
 import { Plugin } from '../../plugin/plugin.js';
 export class TableEditMove extends Plugin {
     tableEdit;
-    constructor(table) {
-        super(table);
-        this.tableEdit = table.plugins.TableEdit;
+    init() {
+        this.tableEdit = this.of.plugins.TableEdit;
         const superCreateEditable = this.tableEdit.createEditable;
         this.tableEdit.createEditable = (selected, selectedStyle) => this.setEditableKeydownListener(superCreateEditable.call(this.tableEdit, selected, selectedStyle));
     }

package/edit-freeze/hide.d.ts

@@ -1,12 +1,12 @@
-import { HTMLEditableElement } from '../../../contenteditable/contenteditable.js';
-import { Plugin } from '../../../plugin/plugin.js';
+import { HTMLEditableElement } from '../../contenteditable/contenteditable.js';
+import { Plugin } from '../../plugin/plugin.js';
 import { TableEdit } from '../edit.js';
 import { TableFreeze } from '../freeze.js';
 import { Table } from '../table.js';
 export declare class TableEditFreezeHide extends Plugin<Table> {
-    readonly tableFreeze: TableFreeze;
-    readonly tableEdit: TableEdit;
-    constructor(table: Table);
+    tableFreeze: TableFreeze;
+    tableEdit: TableEdit;
+    init(): void;
     addEditableEventListeners(editable: HTMLEditableElement): HTMLEditableElement;
     autoHide(): void;
     goAhead(): void;

package/edit-freeze/hide.js

@@ -7,17 +7,16 @@ const zIndex = {
 export class TableEditFreezeHide extends Plugin {
     tableFreeze;
     tableEdit;
-    constructor(table) {
-        super(table);
-        const tableEdit = this.tableEdit = table.plugins.TableEdit;
-        const tableFreeze = this.tableFreeze = table.plugins.TableFreeze;
-        const scrollable = this.tableFreeze.closestScrollable(table.element);
+    init() {
+        const tableEdit = this.tableEdit = this.of.plugins.TableEdit;
+        const tableFreeze = this.tableFreeze = this.of.plugins.TableFreeze;
+        const scrollable = this.tableFreeze.closestScrollable(this.of.element);
         if (!scrollable)
             return;
         tableFreeze.full = { column: '2', corner: '6', row: '4' };
         tableEdit.zIndex = '7';
-        table.addEventListener(scrollable, 'scroll', () => this.autoHide());
-        table.addEventListener(window, 'resize', () => this.autoHide());
+        this.of.addEventListener(scrollable, 'scroll', () => this.autoHide());
+        this.of.addEventListener(window, 'resize', () => this.autoHide());
         const superCreateEditable = tableEdit.createEditable;
         tableEdit.createEditable = (selected, selectedStyle) => this.addEditableEventListeners(superCreateEditable.call(tableEdit, selected, selectedStyle));
     }

package/edit-freeze/scroll.d.ts

@@ -1,8 +1,8 @@
-import { Plugin } from '../../../plugin/plugin.js';
+import { Plugin } from '../../plugin/plugin.js';
 import { TableFreeze } from '../freeze.js';
 import { Table } from '../table.js';
 export declare class TableEditFreezeScroll extends Plugin<Table> {
     tableFreeze: TableFreeze;
-    constructor(table: Table);
+    init(): void;
     scrollToCell(cell: HTMLTableCellElement): HTMLTableCellElement;
 }

package/edit-freeze/scroll.js

@@ -1,10 +1,9 @@
 import { Plugin } from '../../plugin/plugin.js';
 export class TableEditFreezeScroll extends Plugin {
     tableFreeze;
-    constructor(table) {
-        super(table);
-        this.tableFreeze = table.plugins.TableFreeze;
-        const tableEdit = table.plugins.TableEdit;
+    init() {
+        this.tableFreeze = this.of.plugins.TableFreeze;
+        const tableEdit = this.of.plugins.TableEdit;
         const superSetSelectedCell = tableEdit.setSelectedCell;
         tableEdit.setSelectedCell = cell => superSetSelectedCell.call(tableEdit, this.scrollToCell(cell));
     }

package/edit.d.ts

@@ -1,5 +1,5 @@
-import { HTMLEditableElement } from '../../contenteditable/contenteditable.js';
-import { Plugin } from '../../plugin/plugin.js';
+import { HTMLEditableElement } from '../contenteditable/contenteditable.js';
+import { Plugin } from '../plugin/plugin.js';
 import { Table } from './table.js';
 export declare class RangeCopy {
     commonAncestorContainer: Node;

package/feed.d.ts

@@ -1,8 +1,8 @@
-import { Plugin } from '../../plugin/plugin.js';
+import { Plugin } from '../plugin/plugin.js';
 import { Table } from './table.js';
 export declare class TableFeed extends Plugin<Table> {
     observer: IntersectionObserver | undefined;
-    constructor(table: Table);
     feed(): Promise<void>;
+    init(): void;
     observe(): void;
 }

package/feed.js

@@ -1,10 +1,6 @@
 import { Plugin } from '../plugin/plugin.js';
 export class TableFeed extends Plugin {
     observer = undefined;
-    constructor(table) {
-        super(table);
-        this.observe();
-    }
     async feed() {
         const table = this.of.element;
         const tbody = table.querySelector(':scope > tbody');
@@ -25,6 +21,9 @@ export class TableFeed extends Plugin {
         }
         this.observe();
     }
+    init() {
+        this.observe();
+    }
     observe() {
         const table = this.of.element;
         const lastCell = table.querySelector(':scope > tbody > tr:last-child')

package/freeze/inherit-background.d.ts

@@ -1,10 +1,8 @@
 import { TableFreeze } from '../freeze.js';
-import { Table } from '../table';
 /**
  * This plugin has no use and no effect if your table has border-collapse: collapse
  */
 export declare class TableFreezeInheritBackground extends TableFreeze {
     tableStyle: CSSStyleDeclaration;
-    constructor(table: Table);
     init(): void;
 }

package/freeze/inherit-background.js

@@ -4,11 +4,8 @@ import { TableFreeze } from '../freeze.js';
  */
 export class TableFreezeInheritBackground extends TableFreeze {
     tableStyle;
-    constructor(table) {
-        super(table);
-        this.tableStyle = getComputedStyle(table.element);
-    }
     init() {
+        this.tableStyle = getComputedStyle(this.of.element);
         if (this.tableStyle.borderCollapse !== 'separate')
             return;
         const table = this.of;

package/freeze/inherit-border.d.ts

@@ -1,14 +1,10 @@
-import { Plugin } from '../../../plugin/plugin.js';
-import { TableFreeze } from '../freeze.js';
+import { Plugin } from '../../plugin/plugin.js';
 import { HTMLTableFreezeElement } from '../freeze.js';
 import { Table } from '../table.js';
 /**
  * This plugin has no use and no effect if your table has border-collapse: separate (default)
  */
 export declare class TableFreezeInheritBorder extends Plugin<Table> {
-    tableStyle: CSSStyleDeclaration;
-    tableFreeze: TableFreeze;
-    constructor(table: Table);
     init(): void;
     position(position: number, counter: number, colCell: HTMLTableFreezeElement, side: 'bottom' | 'left' | 'right' | 'top'): number;
 }

package/freeze/inherit-border.js

@@ -3,21 +3,15 @@ import { Plugin } from '../../plugin/plugin.js';
  * This plugin has no use and no effect if your table has border-collapse: separate (default)
  */
 export class TableFreezeInheritBorder extends Plugin {
-    tableStyle;
-    tableFreeze;
-    constructor(table) {
-        super(table);
-        this.tableFreeze = table.plugins.TableFreeze;
-        this.tableStyle = getComputedStyle(table.element);
-        if (this.tableStyle.borderCollapse !== 'collapse')
-            return;
-        const superPosition = this.tableFreeze.position;
-        this.tableFreeze.position = (position, counter, colCell, side) => superPosition.call(this.of.plugins.TableFreeze, this.position(position, counter, colCell, side), counter, colCell, side);
-    }
     init() {
-        if (this.tableStyle.borderCollapse !== 'collapse')
+        const tableFreeze = this.of.plugins.TableFreeze;
+        const tableStyle = getComputedStyle(this.of.element);
+        if (tableStyle.borderCollapse !== 'collapse')
+            return;
+        const superPosition = tableFreeze.position;
+        tableFreeze.position = (position, counter, colCell, side) => superPosition.call(this.of.plugins.TableFreeze, this.position(position, counter, colCell, side), counter, colCell, side);
+        if (tableStyle.borderCollapse !== 'collapse')
             return;
-        const tableFreeze = this.tableFreeze;
         const table = this.of;
         // table
         table.styleSheet.push(`

package/freeze.d.ts

@@ -1,4 +1,4 @@
-import { Plugin } from '../../plugin/plugin.js';
+import { Plugin } from '../plugin/plugin.js';
 import { Table } from './table.js';
 export type HTMLTableFreezeElement = HTMLTableCellElement | HTMLTableColElement;
 interface FullIndex {
@@ -12,7 +12,6 @@ export declare class TableFreeze extends Plugin<Table> {
     leftColumnCount: number;
     rightColumnCount: number;
     zIndex: string;
-    constructor(table: Table);
     init(): void;
     closestScrollable(element: Element): HTMLElement | (Window & typeof globalThis) | undefined;
     protected countLeftColumns(): number;

package/freeze.js

@@ -5,13 +5,10 @@ export class TableFreeze extends Plugin {
     leftColumnCount;
     rightColumnCount;
     zIndex = '1';
-    constructor(table) {
-        super(table);
+    init() {
         this.columns = this.getColumns();
         this.leftColumnCount = this.countLeftColumns();
         this.rightColumnCount = this.countRightColumns();
-    }
-    init() {
         this.freezeFootRows();
         this.freezeHeadRows();
         this.freezeLeftColumns();

package/package.json

@@ -24,18 +24,25 @@
 	],
 	"homepage": "https://it.rocks",
 	"keywords": [
+		"column",
+		"columns",
 		"drag",
 		"drop",
 		"edit",
 		"editable",
+		"feed",
 		"freeze",
 		"front-end",
 		"frozen",
 		"it.rocks",
 		"lock",
 		"reorder",
+		"row",
+		"rows",
 		"scroll",
-		"table"
+		"table",
+		"UI",
+		"UX"
 	],
 	"license": "LGPL-3.0-or-later",
 	"module": "./table.js",
@@ -49,5 +56,5 @@
 	},
 	"type": "module",
 	"types": "./table.d.ts",
-	"version": "0.0.21"
+	"version": "0.1.0"
 }

package/table.d.ts

@@ -1,4 +1,4 @@
-import { HasPlugins, Options as PluginOptions } from '../../plugin/plugin.js';
+import { HasPlugins, Options as PluginOptions } from '../plugin/plugin.js';
 export declare function applyStyleSheets(): void;
 export declare function garbageCollector(): void;
 export declare function getTables(): Table[];