json-renderers-build-table 1.17.3 → 1.22.2

package/README.md

@@ -1,28 +1,211 @@
 # json-renderers-build-table
 
-Focused table specification builder extracted from the table work in `json-renderers-build`.
+> Build a complete HTML table JSON specification from columns + data — declaratively.
 
-The package builds JSON DOM specifications for table sections. Table data remains separate from table and row options, so row actions, row attributes, and custom cell elements can evolve without adding table-specific behavior to the generic renderer package.
+---
 
-Use the exported `renderRequests` JSON catalog to see complete requests for each supported flavor. It includes a basic table, serial numbers, default or custom actions, combined options, and standalone table head/body requests:
+## Why this exists
 
-```js
-import render, { renderRequests } from "json-renderers-build-table";
+Building a `<table>` from raw data is repetitive work that quickly becomes messy:
+
+- You scatter `createElement` calls across your codebase
+- Adding a column means touching the header, the body cells, the footer, and the colgroup
+- Swapping a cell style for one column (e.g. a badge instead of plain text) means rewriting imperative DOM code
+- Testing is hard because the logic is entangled with the DOM
+
+This library inverts that. **You describe what the table should look like in JSON.** The library stamps it out.
+
+The result is a plain JSON object — a DOM specification — that you hand to a renderer like [`@keshavsoft/json-to-tag`](https://keshavsoft.github.io/json-to-tag/dist/v9/min.js). The renderer turns it into real DOM elements. The builder never touches the DOM.
+
+---
+
+## The core idea: declarative instructions over a shared registry
+
+Every build runs through three layers:
+
+```
+1. Registry      holds { data, base, spec }
+                   data  = your columns + rows
+                   base  = the empty table skeleton (colgroup, thead, tbody, tfoot)
+                   spec  = named cell/row templates
+
+2. Instructions  a JSON array that says:
+                   "read THIS source path,
+                    apply THIS template,
+                    write the result to THIS destination"
+
+3. writePath     navigates the base tree by data-role anchor
+                 and writes using a named action
+                 (set / push / unshift / pushToRows / ...)
+```
+
+Because the instructions are JSON, you can read a build sequence without tracing any JavaScript. Each instruction has a `narration` field that explains itself in plain English.
 
-const request = structuredClone(renderRequests.tableWithSerialAndActions);
-request.data = [{ itemName: "0.11-25", baseUnit: "kgs" }];
+---
 
-const table = render(request);
+## How a table gets built (v18 `simple`)
+
+```
+columns.json     batches.json
+      \               /
+       simple({ columns, data })
+              |
+              |  registry = { data, base, spec }
+              |
+              +-- single instructions (fromCollection)
+              |     colgroup children   (one <col> per column)
+              |     thead > tr children (one <th> per column)
+              |
+              +-- double instructions (twoDimensional)
+                    tbody children      (one <tr> per row, one <td> per column)
+              |
+              +-- returns base (fully populated JSON tree)
 ```
 
-The catalog is also available as `render.requests` when importing the default renderer. Clone a catalog entry before changing it so the shared examples remain unchanged.
+The returned `base` is a plain JavaScript object:
+
+```json
+{
+  "tagName": "table",
+  "attributes": { "class": "table table-hover ..." },
+  "children": [
+    { "tagName": "colgroup", "children": [ "..." ] },
+    { "tagName": "thead",    "children": [ { "tagName": "tr", "children": [ "..." ] } ] },
+    { "tagName": "tbody",    "children": [ "..." ] },
+    { "tagName": "tfoot",    "children": [ "..." ] }
+  ]
+}
+```
 
-To add a footer row with one text input per column, enable `showFooter`:
+Hand that to any spec-to-DOM renderer and you get a real table element.
+
+---
+
+## Quick start
 
 ```js
-const request = structuredClone(renderRequests.tableWithFooter);
-request.data = myData;
-const table = render(request);
+import { simple } from "./docs/dist/v18/min.js";
+
+const columns = [
+    {
+        columnName: "itemName",
+        width: "300px",
+        template: { body: { tr: "buildBodyTr", cell: "buildBodyCell" } }
+    },
+    {
+        columnName: "baseUnit",
+        width: "200px",
+        template: { body: { tr: "buildBodyTr", cell: "buildBodyCell" } }
+    },
+    {
+        columnName: "batches",
+        width: "100px",
+        template: { body: { tr: "buildBodyTr", cell: "buttonCell" } }
+    }
+];
+
+const data = [
+    { itemName: "0.11-25", baseUnit: "kgs", batches: 1 },
+    { itemName: "0.11-30", baseUnit: "kgs", batches: 0 }
+];
+
+const spec = simple({ columns, data });
+
+// spec is a plain JSON tree — pass it to your DOM renderer
+const element = window.ks.jsonToTag.buildSpecElement(spec);
+document.getElementById("container").appendChild(element);
 ```
 
-Use `showFooterSave` to add a separate footer row with the same inputs and a Save button in the last input cell.
+---
+
+## What each column config means
+
+| Field | Purpose |
+|---|---|
+| `columnName` | Maps to the data property on each row object |
+| `width` | Written into the `<col>` element in the colgroup |
+| `template.body.tr` | Key into `spec.json` — which `<tr>` template to use for body rows |
+| `template.body.cell` | Key into `spec.json` — which `<td>` template to use for this column's cells |
+
+You change the look of a column's cells by pointing `template.body.cell` at a different key in `spec.json`. No JavaScript changes needed.
+
+---
+
+## Cell templates (`spec.json`)
+
+Pre-built templates in `src/v18/spec.json`:
+
+| Key | Renders |
+|---|---|
+| `buildBodyCell` | Plain `<td>` with the row value as text |
+| `buttonCell` | `<td>` containing a `<button>` showing the aggregate count |
+| `buildHeader` | `<th>` with uppercase text |
+| `buildColGroup` | `<col>` with a width attribute |
+| `buildFooter` | `<td>` with a text `<input>` for footer rows |
+| `buildOption` | `<option>` element |
+| `buildSelect` | `<select>` container |
+| `buildDataList` | `<datalist>` container |
+
+---
+
+## Why columns drive everything
+
+A column definition is the single source of truth for **one vertical slice** of the table:
+
+- its header cell (`buildHeader` template)
+- its width (`buildColGroup` template)
+- its body cell template (`template.body.cell`)
+- its footer cell (if enabled)
+
+Adding a column = adding one object to the columns array.  
+Removing a column = removing it.  
+The instructions loop over columns automatically.  
+There is no imperative "add a th, then add a td, then add a col" sequence to maintain.
+
+---
+
+## Build
+
+```bash
+npm install
+npm run build
+# output: docs/dist/v18/min.js
+```
+
+The Vite config auto-detects the highest `vN` folder under `src/` and builds that version. No config changes needed when a new version is added.
+
+---
+
+## Run the sample
+
+```bash
+npx serve
+# open http://localhost:PORT/samples/v18/simpleTable/
+```
+
+---
+
+## Project structure
+
+```
+src/
+  v18/
+    index.js              exports { simple }
+    spec.json             named cell/row templates
+    simple/
+      index.js            the build runner (registry + instructions)
+      base.json           empty table skeleton with data-role anchors
+      instructions/
+        single.json       fromCollection instructions (colgroup, thead)
+        double.json       twoDimensional instruction (tbody)
+      writePath/
+        index.js          tree writer with named actions
+
+samples/
+  v18/
+    simpleTable/          live demo: columns.json + batches.json
+
+docs/
+  dist/
+    v18/min.js            pre-built bundle (committed, served via GitHub Pages)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-renderers-build-table",
-  "version": "1.17.3",
+  "version": "1.22.2",
   "description": "Focused table specification builder with configurable rows and cells",
   "type": "module",
   "main": "src/index.js",
@@ -18,9 +18,9 @@
   },
   "dependencies": {
     "@keshavsoft/json-to-tag": "^1.9.3",
-    "json-transformer-funcs": "^1.24.4",
+    "json-transformer-funcs": "^1.24.7",
     "json-transformer-funcs-one-dimension": "^1.5.2",
-    "json-transformer-funcs-primitive": "^1.7.1",
+    "json-transformer-funcs-primitive": "^1.9.2",
     "json-transformer-funcs-two-dimensions": "^1.6.1"
   },
   "devDependencies": {

package/src/index.js

@@ -1,2 +1,2 @@
-export * from "./v17/index.js";
-export { default } from "./v17/index.js";
+export * from "./v22/index.js";
+export { default } from "./v22/index.js";

package/src/v17/index.js

@@ -1,5 +1,5 @@
-// V16 exposes three focused table scenarios. Each scenario owns its config and instructions.
-// Only genuinely shared execution helpers live in ./common.
-import simple from "./simple/index.js";
-
-export { simple };
+// V16 exposes three focused table scenarios. Each scenario owns its config and instructions.
+// Only genuinely shared execution helpers live in ./common.
+import simple from "./simple/index.js";
+
+export { simple };

package/src/v17/simple/index.js

@@ -1,56 +1,56 @@
-import fromCollection from "json-transformer-funcs-one-dimension";
-import twoDimensional from "json-transformer-funcs-two-dimensions";
-
-import { resolvePath } from "json-transformer-funcs";
-
-import spec from "../spec.json" with { type: "json" };
-import base from "./base.json" with { type: "json" };
-
-import singleInstructions from "./instructions/single.json" with { type: "json" };
-import twoDimensionalInstructions from "./instructions/double.json" with { type: "json" };
-
-import writePath from "./writePath/index.js";
-
-// 1. Keep the input, table structure, and templates together as the build context.
-const registry = { data: {}, base, spec };
-const functions = {
-    fromCollection, twoDimensional
-};
-
-// 2. Apply each instruction: read source, build result, write destination.
-const runInstructions = instructions => {
-    instructions.forEach(instruction => {
-        const source = resolvePath(registry, instruction.sourcePath);
-
-        if (source) {
-            const result = functions[instruction.func](source, spec[instruction.templateKey]);
-            writePath(registry, instruction.destinationPath, result);
-        } else {
-            console.log("   !instruction : ", instruction);
-            console.log("   !source : ", source);
-        };
-    });
-};
-
-const runInstructions2 = instructions => {
-    instructions.forEach(instruction => {
-        const result = functions[instruction.func](
-            registry.data.columns,
-            registry.data.data,
-            spec
-        );
-        writePath(registry, instruction.destinationPath, result);
-    });
-};
-
-// 3. Complete the table and return its JSON specification.
-const startFunc = data => {
-    registry.data = data;
-
-    runInstructions(singleInstructions);
-    runInstructions2(twoDimensionalInstructions);
-
-    return base;
-};
-
+import fromCollection from "json-transformer-funcs-one-dimension";
+import twoDimensional from "json-transformer-funcs-two-dimensions";
+
+import { resolvePath } from "json-transformer-funcs";
+
+import spec from "../spec.json" with { type: "json" };
+import base from "./base.json" with { type: "json" };
+
+import singleInstructions from "./instructions/single.json" with { type: "json" };
+import twoDimensionalInstructions from "./instructions/double.json" with { type: "json" };
+
+import writePath from "./writePath/index.js";
+
+// 1. Keep the input, table structure, and templates together as the build context.
+const registry = { data: {}, base, spec };
+const functions = {
+    fromCollection, twoDimensional
+};
+
+// 2. Apply each instruction: read source, build result, write destination.
+const runInstructions = instructions => {
+    instructions.forEach(instruction => {
+        const source = resolvePath(registry, instruction.sourcePath);
+
+        if (source) {
+            const result = functions[instruction.func](source, spec[instruction.templateKey]);
+            writePath(registry, instruction.destinationPath, result);
+        } else {
+            console.log("   !instruction : ", instruction);
+            console.log("   !source : ", source);
+        };
+    });
+};
+
+const runInstructions2 = instructions => {
+    instructions.forEach(instruction => {
+        const result = functions[instruction.func](
+            registry.data.columns,
+            registry.data.data,
+            spec
+        );
+        writePath(registry, instruction.destinationPath, result);
+    });
+};
+
+// 3. Complete the table and return its JSON specification.
+const startFunc = data => {
+    registry.data = data;
+
+    runInstructions(singleInstructions);
+    runInstructions2(twoDimensionalInstructions);
+
+    return base;
+};
+
 export default startFunc;

package/src/v17/spec.json

@@ -1,86 +1,86 @@
-{
-    "buildBodyTr": {
-        "tagName": "tr",
-        "attributes": {
-            "class": "align-middle"
-        },
-        "children": []
-    },
-    "buildColGroup": {
-        "tagName": "col",
-        "attributes": {
-            "width": "${width}"
-        }
-    },
-    "buildHeader": {
-        "tagName": "th",
-        "textContent": "${columnName}",
-        "attributes": {
-            "class": "py-3 px-3 fw-semibold text-uppercase small"
-        }
-    },
-    "buildFooter": {
-        "tagName": "td",
-        "children": [
-            {
-                "tagName": "input",
-                "attributes": {
-                    "type": "text",
-                    "placeholder": "enter ${columnName}",
-                    "name": "${columnName}",
-                    "class": "form-control"
-                }
-            }
-        ]
-    },
-    "buildBodyCell": {
-        "tagName": "td",
-        "textContent": "${rowValue}",
-        "attributes": {
-            "class": "py-3 px-3 text-secondary"
-        }
-    },
-    "button": {
-        "tagName": "button",
-        "textContent": "${columnName}",
-        "attributes": {
-            "class": "btn btn-primary btn-sm"
-        }
-    },
-    "buttonCell": {
-        "tagName": "td",
-        "attributes": {
-            "class": "py-2 px-3 text-center"
-        },
-        "children": [
-            {
-                "tagName": "button",
-                "textContent": "${agg:count}",
-                "attributes": {
-                    "class": "btn btn-primary btn-sm"
-                }
-            }
-        ]
-    },
-    "buildOption": {
-        "tagName": "option",
-        "textContent": "${rowValue}",
-        "attributes": {
-            "value": "${rowValue}"
-        }
-    },
-    "buildSelect": {
-        "tagName": "select",
-        "attributes": {
-            "id": "LedgerName"
-        },
-        "children": []
-    },
-    "buildDataList": {
-        "tagName": "datalist",
-        "attributes": {
-            "data-name": "${columnName}"
-        },
-        "children": []
-    }
+{
+    "buildBodyTr": {
+        "tagName": "tr",
+        "attributes": {
+            "class": "align-middle"
+        },
+        "children": []
+    },
+    "buildColGroup": {
+        "tagName": "col",
+        "attributes": {
+            "width": "${width}"
+        }
+    },
+    "buildHeader": {
+        "tagName": "th",
+        "textContent": "${columnName}",
+        "attributes": {
+            "class": "py-3 px-3 fw-semibold text-uppercase small"
+        }
+    },
+    "buildFooter": {
+        "tagName": "td",
+        "children": [
+            {
+                "tagName": "input",
+                "attributes": {
+                    "type": "text",
+                    "placeholder": "enter ${columnName}",
+                    "name": "${columnName}",
+                    "class": "form-control"
+                }
+            }
+        ]
+    },
+    "buildBodyCell": {
+        "tagName": "td",
+        "textContent": "${rowValue}",
+        "attributes": {
+            "class": "py-3 px-3 text-secondary"
+        }
+    },
+    "button": {
+        "tagName": "button",
+        "textContent": "${columnName}",
+        "attributes": {
+            "class": "btn btn-primary btn-sm"
+        }
+    },
+    "buttonCell": {
+        "tagName": "td",
+        "attributes": {
+            "class": "py-2 px-3 text-center"
+        },
+        "children": [
+            {
+                "tagName": "button",
+                "textContent": "${agg:count}",
+                "attributes": {
+                    "class": "btn btn-primary btn-sm"
+                }
+            }
+        ]
+    },
+    "buildOption": {
+        "tagName": "option",
+        "textContent": "${rowValue}",
+        "attributes": {
+            "value": "${rowValue}"
+        }
+    },
+    "buildSelect": {
+        "tagName": "select",
+        "attributes": {
+            "id": "LedgerName"
+        },
+        "children": []
+    },
+    "buildDataList": {
+        "tagName": "datalist",
+        "attributes": {
+            "data-name": "${columnName}"
+        },
+        "children": []
+    }
 }

package/src/v18/bodyOnly/base.json

@@ -0,0 +1 @@
+[]

package/src/v18/bodyOnly/index.js

@@ -0,0 +1,36 @@
+import twoDimensional from "json-transformer-funcs-two-dimensions";
+
+import spec from "../spec.json" with { type: "json" };
+import base from "./base.json" with { type: "json" };
+
+import twoDimensionalInstructions from "./instructions/double.json" with { type: "json" };
+
+import writePath from "./writePath/index.js";
+
+// 1. Keep the input, table structure, and templates together as the build context.
+const registry = { data: {}, base, spec };
+const functions = {
+    twoDimensional
+};
+
+const runInstructions2 = instructions => {
+    instructions.forEach(instruction => {
+        const result = functions[instruction.func](
+            registry.data.columns,
+            registry.data.data,
+            spec
+        );
+        writePath(registry, instruction.destinationPath, result);
+    });
+};
+
+// 3. Complete the table and return its JSON specification.
+const startFunc = data => {
+    registry.data = data;
+
+    runInstructions2(twoDimensionalInstructions);
+
+    return base.children;
+};
+
+export default startFunc;

package/src/v18/bodyOnly/instructions/double.json

@@ -0,0 +1,18 @@
+[
+    {
+        "narration": "Build the table body rows for the table using the configured columns and data.",
+        "destinationPath": {
+            "fileName": "base",
+            "filePath": [
+                "children"
+            ]
+        },
+        "sourcePath": {
+            "fileName": "data",
+            "filePath": [
+                "columns"
+            ]
+        },
+        "func": "twoDimensional"
+    }
+]