json-renderers-build 1.3.4 → 1.5.1

package/README.md

@@ -0,0 +1,374 @@
+# json-renderers-build
+
+> **Headless Component Specification Compiler for JSON-Driven UIs**  
+> Compiles structured data, columns, and declarative component blueprints into JSON-to-DOM specification ASTs (`specAsJsonToDom`) using `json-to-spec`.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.3.6-emerald.svg)](package.json)
+[![Architecture: Headless](https://img.shields.io/badge/Architecture-Headless%20Spec%20Builder-indigo.svg)](#the-story-of-json-renderers-build)
+
+---
+
+## The Story of `json-renderers-build`
+
+In the **KeshavSoft Declarative UI Ecosystem**, rendering is split cleanly into two distinct, decoupled responsibilities:
+
+1. **Specification Compilation (THIS REPO — `json-renderers-build`)**  
+   Transforms raw data, field arrays, and UI blueprints (`skeleton.json`) into an abstract, deterministic DOM Specification tree (`specAsJsonToDom`).
+2. **DOM Instantiation & Mounting (Downstream — `json-renderers` / `@keshavsoft/json-to-tag`)**  
+   Consumes that compiled specification tree and constructs real browser DOM nodes (`HTMLElement`), mounting them into target HTML containers.
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│ 1. Raw Business Data & Columns                                         │
+│    data: [{ id: 1, name: "Alpha" }], columns: ["Name"]                │
+└───────────────────────────────────┬────────────────────────────────────┘
+                                    │
+                                    ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│ 2. json-renderers-build (THIS REPO)                                    │
+│    • Pre-packaged component skeletons (table, select, selectOptions)   │
+│    • Compiles templates via json-to-spec compiler                     │
+│    • 100% HEADLESS: Zero DOM queries, zero document mutations         │
+└───────────────────────────────────┬────────────────────────────────────┘
+                                    │ returns: specAsJsonToDom (JSON AST)
+                                    ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│ 3. Downstream DOM Runtime (json-renderers / @keshavsoft/json-to-tag)   │
+│    • Takes JSON AST                                                    │
+│    • Produces real DOM nodes (HTMLTableElement, HTMLSelectElement)     │
+│    • Mounts into document.getElementById(targetHtmlId)                 │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+### Why a Dedicated Spec Builder?
+
+- **100% Headless & Isomorphic:** Runs anywhere JavaScript runs — in Node.js (for SSR or static site generation), in Web Workers, in browser contexts, or in command-line build tools.
+- **Pure Functional Pipeline:** Given the same data and columns, it returns the exact same specification AST every time. No DOM dependencies or mock DOMs (`jsdom`) required for unit testing.
+- **Blueprint Separation:** Component skeletons (`skeleton.json`) and transformation rules can evolve independently from DOM lifecycle and styling concerns.
+- **Core Engine for `json-renderers`:** Downstream library `json-renderers` relies on `json-renderers-build` to generate its AST before mounting.
+
+---
+
+## Features
+
+- **Config-Driven Spec Generation:** Converts simple arrays of data and columns into fully structured DOM specifications.
+- **Pre-Packaged Blueprints (v3):**
+  - **`table`:** Full `<table>`, `<thead>`, `<tbody>` structure styled with standard Bootstrap classes (`table table-hover table-striped mb-0`).
+  - **`select`:** Full `<select id="LedgerName">` containing dynamic `<option>` child nodes.
+  - **`selectOptionsOnly`:** Option fragment spec (`{ children: [ ...options ] }`) designed to inject options into pre-existing select containers.
+- **Global & ESM Distribution:** Usable via npm or directly in the browser via CDN script (`window.ks.jsonRenderersBuild`).
+- **Standardized Parameter Architecture:** Adheres to KeshavSoft's `in`-prefixed parameter convention and `local`-variable scoping pattern.
+
+---
+
+## Installation
+
+### NPM
+
+```bash
+npm install json-renderers-build
+```
+
+### Browser (CDN / ES Module)
+
+```html
+<!-- Load ES module bundle directly from CDN -->
+<script type="module" src="https://cdn.jsdelivr.net/gh/keshavsoft/json-renderers-build@main/docs/dist/v3/min.js"></script>
+```
+
+When loaded via `<script type="module">`, it automatically registers globally on:
+```javascript
+window.ks.jsonRenderersBuild = {
+  meta: {
+    version: "v3.0.0",
+    description: "build table from store data and render to DOM uses json-to-spec, json-to-dom under the hood"
+  },
+  renderToDom: [Function: render]
+};
+```
+
+---
+
+## Quick Start & Usage
+
+### 1. Generating a Table Specification (`table`)
+
+The `table` renderer generates a complete table specification AST including headers (`<th>`) and data cells (`<td>`).
+
+```javascript
+import render from "json-renderers-build";
+
+const records = [
+  { id: 101, name: "Alpha Enterprise", city: "Hyderabad" },
+  { id: 102, name: "Beta Logistics", city: "Bengaluru" }
+];
+
+const columns = [
+  { title: "ID" },
+  { title: "Name" },
+  { title: "City" }
+];
+
+const spec = render({
+  type: "table",
+  data: records,
+  columns: columns
+});
+
+console.log(spec);
+```
+
+#### Compiled Output AST (`specAsJsonToDom`):
+```json
+{
+  "tagName": "table",
+  "attributes": {
+    "class": "table table-hover table-striped mb-0"
+  },
+  "children": [
+    {
+      "tagName": "thead",
+      "children": [
+        {
+          "tagName": "tr",
+          "children": [
+            { "tagName": "th", "textContent": "ID" },
+            { "tagName": "th", "textContent": "Name" },
+            { "tagName": "th", "textContent": "City" }
+          ]
+        }
+      ]
+    },
+    {
+      "tagName": "tbody",
+      "children": [
+        {
+          "tagName": "tr",
+          "children": [
+            { "tagName": "td", "textContent": 101 },
+            { "tagName": "td", "textContent": "Alpha Enterprise" },
+            { "tagName": "td", "textContent": "Hyderabad" }
+          ]
+        },
+        {
+          "tagName": "tr",
+          "children": [
+            { "tagName": "td", "textContent": 102 },
+            { "tagName": "td", "textContent": "Beta Logistics" },
+            { "tagName": "td", "textContent": "Bengaluru" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+### 2. Generating a Select Dropdown Specification (`select`)
+
+The `select` renderer creates a complete `<select>` specification populated with `<option>` elements.
+
+```javascript
+import render from "json-renderers-build";
+
+const spec = render({
+  type: "select",
+  data: ["Account Receivable", "Account Payable", "Sales Revenue"]
+});
+
+console.log(spec);
+```
+
+#### Compiled Output AST:
+```json
+{
+  "tagName": "select",
+  "attributes": {
+    "id": "LedgerName"
+  },
+  "children": [
+    {
+      "tagName": "option",
+      "attributes": { "value": "Account Receivable" },
+      "textContent": "Account Receivable"
+    },
+    {
+      "tagName": "option",
+      "attributes": { "value": "Account Payable" },
+      "textContent": "Account Payable"
+    },
+    {
+      "tagName": "option",
+      "attributes": { "value": "Sales Revenue" },
+      "textContent": "Sales Revenue"
+    }
+  ]
+}
+```
+
+---
+
+### 3. Generating Options-Only Fragment Specification (`selectOptionsOnly`)
+
+When you already have a `<select>` element in your markup and only want to dynamically generate its `<option>` items:
+
+```javascript
+import render from "json-renderers-build";
+
+const spec = render({
+  type: "selectOptionsOnly",
+  data: ["North", "South", "East", "West"]
+});
+
+console.log(spec);
+```
+
+#### Compiled Output AST:
+```json
+{
+  "children": [
+    {
+      "tagName": "option",
+      "attributes": { "value": "North" },
+      "textContent": "North"
+    },
+    {
+      "tagName": "option",
+      "attributes": { "value": "South" },
+      "textContent": "South"
+    },
+    {
+      "tagName": "option",
+      "attributes": { "value": "East" },
+      "textContent": "East"
+    },
+    {
+      "tagName": "option",
+      "attributes": { "value": "West" },
+      "textContent": "West"
+    }
+  ]
+}
+```
+
+---
+
+## Consumer Integration: From Spec to DOM
+
+To convert the specification returned by `json-renderers-build` into real DOM nodes, downstream consumers (such as `json-renderers`) pipe the AST into `@keshavsoft/json-to-tag`:
+
+```javascript
+import renderSpec from "json-renderers-build";
+import jsonToTag from "@keshavsoft/json-to-tag";
+
+// Step 1: Compile specification AST (Headless)
+const spec = renderSpec({
+  type: "table",
+  data: myRecords,
+  columns: ["Name", "Amount"]
+});
+
+// Step 2: Unwrap children if fragment
+let jsonToSend = spec;
+if (!("tagName" in spec) && "children" in spec) {
+  jsonToSend = spec.children;
+}
+
+// Step 3: Instantiate DOM elements
+const domElement = jsonToTag(jsonToSend);
+
+// Step 4: Mount into target container
+const container = document.getElementById("my-container");
+container.replaceChildren(domElement);
+```
+
+---
+
+## API Reference
+
+### `render(options)` / `default export`
+
+The entry point exported by `json-renderers-build` accepts a single configuration object:
+
+```javascript
+render({
+  type = "table",
+  data = [],
+  columns
+})
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `"table"` | Type of component spec to build: `"table"`, `"select"`, or `"selectOptionsOnly"`. |
+| `data` | `Array` | `[]` | Data array. For `table`: array of row objects. For `select` / `selectOptionsOnly`: array of strings. |
+| `columns` | `Array` | `undefined` | Header columns for `table`. Accepts an array of strings (e.g. `["Name"]`) or an array of objects (e.g. `[{ title: "Name" }]`). |
+
+**Returns:** `Object` — Compiled JSON-to-DOM specification AST (`specAsJsonToDom`).
+
+---
+
+## Project Structure
+
+```text
+json-renderers-build/
+├── docs/                     # Documentation & distribution portal
+│   ├── dist/                 # Production bundles (Vite build)
+│   │   ├── min.js            # Latest ES bundle
+│   │   ├── v2/min.js         # v2 bundle
+│   │   └── v3/min.js         # v3 bundle
+│   └── index.html            # Interactive Documentation & Live Playground
+├── samples/                  # Runnable browser verification samples
+│   ├── table/                # Table spec compilation demo
+│   ├── select/               # Select dropdown spec demo
+│   └── selectOptionsOnly/    # Options fragment demo
+├── src/                      # Source code
+│   ├── index.js              # Entry router (exports ./v3/index.js)
+│   ├── v1/                   # Legacy v1 (early coupled prototype)
+│   ├── v2/                   # Legacy v2 (intermediate spec refactor)
+│   └── v3/                   # CURRENT: Pure headless spec compiler
+│       ├── common/           # Shared utilities (deriveColumnsFromData.js)
+│       ├── select/           # Select builder (index.js, skeleton.json)
+│       ├── selectOptionsOnly/# Options fragment builder (index.js, skeleton.json)
+│       ├── table/            # Table builder (index.js, skeleton.json)
+│       ├── meta.js           # Version & metadata descriptor
+│       ├── registerGlobal.js # Global window.ks namespace attachment
+│       └── index.js          # Component dispatcher map
+├── package.json              # Package definition & scripts
+├── vite.config.js            # Vite build configuration
+└── README.md                 # Complete repository guide
+```
+
+---
+
+## Evolution Story
+
+| Version | Status | Architectural Role |
+|---|---|---|
+| **v1** | Legacy | Early coupled implementation. Required `targetHtmlId` and directly executed DOM mounting using `jsonToTag`. |
+| **v2** | Deprecated | Decoupled output to return `specAsJsonToDom`, but still retained legacy parameter baggage (`targetHtmlId`, `showLog`). |
+| **v3** | **Current** | **Pure Headless Spec Compiler**. Clean functional API: `(type, data, columns) => spec`. Supports `table`, `select`, and `selectOptionsOnly`. Decoupled from DOM. |
+
+---
+
+## Development & Build
+
+```bash
+# Install dependencies
+npm install
+
+# Start Vite development server
+npm run dev
+
+# Build production bundle (into docs/dist/v3/min.js and docs/dist/min.js)
+npm run build
+```
+
+---
+
+## License
+
+MIT © [KeshavSoft](https://github.com/keshavsoft)

package/docs/dist/min.js

@@ -0,0 +1,320 @@
+const g = {
+  version: "v4.0.0",
+  description: "build table from store data and render to DOM uses json-to-spec, json-to-dom under the hood"
+}, j = (t) => {
+  var r;
+  typeof globalThis > "u" || !t || (globalThis.ks ?? (globalThis.ks = {}), (r = globalThis.ks).jsonRenderersBuild ?? (r.jsonRenderersBuild = {
+    meta: g,
+    renderToDom: t
+  }));
+}, E = {
+  version: "v32",
+  description: "JSON-to-DOM engine with centralized traversal and responsibility-focused construction"
+}, N = ({ inFuncDefinition: t } = {}) => {
+  if (typeof globalThis > "u" || !t) return;
+  globalThis.ks ?? (globalThis.ks = {});
+  const r = {
+    meta: E,
+    buildSpecElement: t
+  };
+  globalThis.ks.jsonToSpec = r;
+}, O = (t, r) => f(t, r), b = (t, r) => Array.isArray(t) ? t.map((e) => O(e, r)).flat(1 / 0).filter(Boolean) : [], x = (t, r) => {
+  if ("source" in t && (t == null ? void 0 : t.source) in r) {
+    const e = r[t == null ? void 0 : t.source];
+    if (Array.isArray(e))
+      return e.map((o) => {
+        const c = t == null ? void 0 : t.template;
+        if (c)
+          return f(c, o);
+      });
+  }
+}, F = (t, r) => {
+  let e = [];
+  for (const [n, o] of Object.entries(r)) {
+    const c = t == null ? void 0 : t.template;
+    if (c) {
+      const a = f(c, {
+        key: n,
+        value: o
+      });
+      e.push(a);
+    }
+  }
+  return e;
+}, R = (t, r) => {
+  if ("source" in t && (t == null ? void 0 : t.source) in r) {
+    const e = r[t == null ? void 0 : t.source];
+    if (Array.isArray(e))
+      return e.map((o) => {
+        const c = t == null ? void 0 : t.template;
+        if (c)
+          return f(c, o);
+      });
+  }
+}, D = (t, r) => {
+  if ("operation" in t) {
+    if (t.operation === "loopArray")
+      return x(t, r);
+    if (t.operation === "loopObject")
+      return F(t, r);
+    if (t.operation === "loopCollection")
+      return R(t, r);
+  }
+}, A = (t, r) => {
+  if (typeof r == "string") return r;
+  if (typeof t != "string") return t;
+  if (t === "${value}")
+    return r.value;
+  const e = t.match(/^\$\{(.+?)\}$/);
+  if (e) {
+    const n = e[1];
+    return (r == null ? void 0 : r[n]) ?? "";
+  }
+  return t;
+}, k = (t, r) => {
+  let e = {};
+  for (const [n, o] of Object.entries(t)) {
+    const c = A(o, r);
+    e[n] = c;
+  }
+  return e;
+}, C = (t, r) => {
+  if ("tagName" in t) {
+    if ("textContent" in t) {
+      const e = A(t.textContent, r);
+      t.textContent = e;
+    }
+    if ("attributes" in t) {
+      const e = k(t.attributes, r);
+      t.attributes = e;
+    }
+  }
+}, w = (t, r) => {
+  if (!t || typeof t != "object" || Array.isArray(t)) return null;
+  const e = structuredClone(t);
+  if (!e) return null;
+  if ("tagName" in e && C(e, r), "jsonToSpec" in e) {
+    const n = e == null ? void 0 : e.jsonToSpec, o = D(n, r);
+    Array.isArray(o) ? e.children = o : e.children = [o], delete e.jsonToSpec;
+  }
+  if (Array.isArray(e == null ? void 0 : e.children)) {
+    const n = b(e == null ? void 0 : e.children, r);
+    e.children = n;
+  }
+  return e;
+}, f = (t, r) => t == null ? null : typeof Node < "u" && t instanceof Node ? t : Array.isArray(t) ? b(t, r) : typeof t == "object" ? w(t, r) : typeof t == "string" || typeof t == "number" ? document.createTextNode(String(t)) : t, y = (t, r) => f(t, r);
+N({
+  inFuncDefinition: y
+});
+const V = {
+  default: {
+    tagName: "table",
+    attributes: {
+      class: "table table-hover table-striped mb-0"
+    },
+    children: [
+      {
+        tagName: "thead",
+        children: [
+          {
+            tagName: "tr",
+            jsonToSpec: {
+              operation: "loopCollection",
+              source: "columns",
+              template: {
+                tagName: "th",
+                textContent: "${title}"
+              }
+            },
+            children: []
+          }
+        ]
+      },
+      {
+        tagName: "tbody",
+        jsonToSpec: {
+          operation: "loopCollection",
+          source: "data",
+          template: {
+            tagName: "tr",
+            jsonToSpec: {
+              operation: "loopObject",
+              source: "data",
+              template: {
+                tagName: "td",
+                textContent: "${value}"
+              }
+            },
+            children: []
+          }
+        },
+        children: []
+      }
+    ]
+  }
+}, I = ({
+  inColumns: t,
+  inData: r
+} = {}) => {
+  const e = r ?? [], n = t;
+  return y(V.default, {
+    columns: n,
+    data: e
+  });
+}, K = "select", B = {
+  id: "LedgerName"
+}, M = {
+  operation: "loopArray",
+  source: "arrayOfStrings",
+  template: {
+    tagName: "option",
+    attributes: {
+      value: "${}"
+    },
+    textContent: "${}"
+  }
+}, T = [], G = {
+  tagName: K,
+  attributes: B,
+  jsonToSpec: M,
+  children: T
+}, z = ({
+  inData: t
+} = {}) => y(G, {
+  arrayOfStrings: t ?? []
+}), $ = ({ inItems: t, inRecipe: r, inExecute: e }) => {
+  const n = t, o = r, c = e;
+  return n.map((a) => d({
+    inSource: a,
+    inRecipe: o,
+    inExecute: c
+  })).flat(1 / 0).filter(Boolean);
+}, L = ({ inSource: t, inRecipe: r, inExecute: e }) => {
+  const n = t, o = r, c = e;
+  let a = n;
+  typeof c == "function" && (a = c({
+    inSource: n,
+    inRecipe: o
+  }));
+  for (const [l, u] of Object.entries(a))
+    Array.isArray(u) && o && l in o && (a[l] = $({
+      inItems: u,
+      inRecipe: o[l],
+      inExecute: c
+    }));
+  return a;
+}, d = ({ inSource: t, inRecipe: r, inExecute: e }) => {
+  const n = t, o = r, c = e;
+  return Array.isArray(n) ? $({
+    inItems: n,
+    inRecipe: o,
+    inExecute: c
+  }) : typeof n == "object" && n !== null ? L({
+    inSource: n,
+    inRecipe: o,
+    inExecute: c
+  }) : n;
+}, P = ({ inKey: t, inDirective: r }) => {
+  const e = t, n = r;
+  return (n == null ? void 0 : n.alterKey) || e;
+}, U = ({ inValue: t, inDirective: r, inExecute: e }) => {
+  const n = t, o = r, c = e;
+  return o && "transform" in o ? d({
+    inSource: n,
+    inRecipe: o,
+    inExecute: c
+  }) : n;
+}, _ = ({ inValue: t, inDirective: r }) => {
+  const e = t, n = r;
+  return (n == null ? void 0 : n.valueType) === "array" && !Array.isArray(e) ? [e] : e;
+}, q = ({ inValue: t, inDirective: r }) => {
+  const e = t, n = r;
+  return n != null && n.valueKey && e && typeof e == "object" ? e[n.valueKey] : e;
+}, H = ({ inSource: t, inTransform: r, inExecute: e }) => {
+  const n = t, o = r, c = e, a = {};
+  for (const [l, u] of Object.entries(n)) {
+    if (!(l in o))
+      continue;
+    const i = o[l], h = P({ inKey: l, inDirective: i });
+    let s = u;
+    s = U({
+      inValue: s,
+      inDirective: i,
+      inExecute: c
+    }), s = _({ inValue: s, inDirective: i }), s = q({ inValue: s, inDirective: i }), a[h] = s;
+  }
+  return a;
+};
+function v(t, r) {
+  for (const e in t)
+    typeof t[e] == "object" && t[e] !== null ? v(t[e], r) : typeof t[e] == "string" && t[e] === "${}" && (t[e] = r);
+  return t;
+}
+const Q = ({ inSource: t, inOperation: r, inExecute: e }) => {
+  const n = t, o = r;
+  for (const [c, a] of Object.entries(o))
+    if ("operationType" in a && a.operationType === "loopArray" && c in n) {
+      const l = n[c].map((u) => {
+        const i = { ...a == null ? void 0 : a.template };
+        return v(i, u), i;
+      });
+      n[c] = l;
+    }
+  return n;
+}, m = ({ inSource: t, inRecipe: r }) => {
+  let e = t;
+  const n = r;
+  return n && typeof n == "object" && "transform" in n && (e = H({
+    inSource: e,
+    inTransform: n.transform,
+    inExecute: m
+  })), n && typeof n == "object" && "operation" in n && (e = Q({
+    inSource: e,
+    inOperation: n.operation,
+    inExecute: m
+  })), e;
+}, W = (t, r) => d({
+  inSource: t,
+  inRecipe: r,
+  inExecute: m
+}), X = {
+  children: ""
+}, Y = {
+  children: {
+    operationType: "loopArray",
+    template: {
+      tagName: "option",
+      attributes: {
+        value: "${}"
+      },
+      textContent: "${}"
+    }
+  }
+}, Z = {
+  transform: X,
+  operation: Y
+}, S = ({
+  inData: t
+} = {}) => W({
+  Children: t ?? []
+}, Z), p = {
+  table: I,
+  select: z,
+  selectOptionsOnly: S
+}, J = ({
+  type: t = "table",
+  data: r,
+  columns: e
+} = {}) => {
+  const n = t, o = p[n];
+  return o ? o({
+    inColumns: e,
+    inData: r
+  }) : (console.error(
+    `[Renderer] Unknown renderer type "${n}". Available types: ${Object.keys(p).join(", ")}`
+  ), null);
+};
+j(J);
+export {
+  J as default
+};