expose stateHash prop to React views for pagination/sort control

Author: christianhugoch

common.js

@@ -99,17 +99,22 @@ A react view can be tableless or table-based. A tableless react view could for e
 
 When a react view is tabless, it gets this properties:
 \`\`\`import React from "react";
-export default function App({viewName, query}) {...}
+export default function App({viewName, query, stateHash}) {...}
 \`\`\`
 When a react view is table based, it gets this properties:
 \`\`\`import React from "react";
-export default function App({viewName, query, tableName, rows, state}) {...}
+export default function App({viewName, query, tableName, rows, state, stateHash}) {...}
 \`\`\`
 - viewName: the name of the view
 - query: the query parameters of the view
 - tableName: the name of the Saltcorn table
 - rows: the rows of the table, this is an array of objects, each object is a row of the table
 - state: the state of the view, this is an object with the state of the view
+- stateHash: a short hash string identifying this view's state context. Use it to set pagination and sort parameters
+  via set_state_field, for example set_state_field(\`_\${stateHash}_page\`, 2) to go to page 2,
+  set_state_field(\`_\${stateHash}_pagesize\`, 10) to set the page size,
+  set_state_field(\`_\${stateHash}_sortby\`, "name") to sort by a field,
+  set_state_field(\`_\${stateHash}_sortdesc\`, true) to sort descending.
 
 A react-view has access to bootstrap 5 styles. react-bootstrap is not available please use the normal bootstrap classes.
 

main-code/index.js

@@ -64,9 +64,10 @@ const initMain = async () => {
     const user = JSON.parse(
       decodeURIComponent(rootElement.getAttribute("user")),
     );
+    const stateHash = rootElement.getAttribute("state-hash");
     try {
       const remote = await loadRemote(`${viewName}/${viewName}`);
-      const props = { tableName, viewName, state, query, rows, user };
+      const props = { tableName, viewName, state, query, rows, user, stateHash };
       const root = ReactDOMClient.createRoot(rootElement);
       root.render(React.createElement(remote.default, props));
     } catch (e) {

react_view.js

@@ -6,6 +6,7 @@ const {
   stateFieldsToWhere,
   readState,
 } = require("@saltcorn/data/plugin-helper");
+const { hashState } = require("@saltcorn/data/utils");
 const {
   buildSafeViewName,
   buildAndUpdateView,
@@ -30,10 +31,12 @@ export default function App({ viewName, query${
 const run = async (table_id, viewname, { timestamp }, state, extra) => {
   const req = extra.req;
   const query = req.query || {};
+  const stateHash = hashState(state, viewname);
   const props = {
     "view-name": buildSafeViewName(viewname),
     query: encodeURIComponent(JSON.stringify(query)),
     user: encodeURIComponent(JSON.stringify(req.user || {})),
+    "state-hash": stateHash,
   };
   if (table_id) {
     // with table

tests/view.test.js

@@ -1,6 +1,7 @@
 const { getState } = require("@saltcorn/data/db/state");
 const View = require("@saltcorn/data/models/view");
 const { mockReqRes } = require("@saltcorn/data/tests/mocks");
+const { hashState } = require("@saltcorn/data/utils");
 const { afterAll, beforeAll, describe, it, expect } = require("@jest/globals");
 
 getState().registerPlugin("base", require("@saltcorn/data/base-plugin"));
@@ -11,6 +12,11 @@ beforeAll(async () => {
   await getState().refresh(true);
 });
 
+const extractAttr = (html, attr) => {
+  const m = html.match(new RegExp(`${attr}="([^"]*)"`));
+  return m ? m[1] : null;
+};
+
 describe("react view run tests", () => {
   it("run tableless view", async () => {
     const view = View.findOne({ name: "default_react_view" });
@@ -43,3 +49,43 @@ describe("react view run tests", () => {
     expect(result).toContain('timestamp="');
   });
 });
+
+describe("stateHash prop tests", () => {
+  it("tableless view exposes state-hash as a 5-char hex string", async () => {
+    const view = View.findOne({ name: "default_react_view" });
+    const result = await view.run({}, mockReqRes);
+    expect(result).toContain('state-hash="');
+    const hash = extractAttr(result, "state-hash");
+    expect(hash).toMatch(/^[0-9a-f]{5}$/);
+  });
+
+  it("table-based view exposes state-hash as a 5-char hex string", async () => {
+    const view = View.findOne({ name: "react_view_with_data" });
+    const result = await view.run({}, mockReqRes);
+    expect(result).toContain('state-hash="');
+    const hash = extractAttr(result, "state-hash");
+    expect(hash).toMatch(/^[0-9a-f]{5}$/);
+  });
+
+  it("state-hash matches hashState utility output", async () => {
+    const view = View.findOne({ name: "react_view_with_data" });
+    const state = {};
+    const result = await view.run(state, mockReqRes);
+    const hash = extractAttr(result, "state-hash");
+    expect(hash).toBe(hashState(state, "react_view_with_data"));
+  });
+
+  it("state-hash is stable when only pagination params change", async () => {
+    const view = View.findOne({ name: "react_view_with_data" });
+    const baseState = {};
+    const baseResult = await view.run(baseState, mockReqRes);
+    const baseHash = extractAttr(baseResult, "state-hash");
+
+    const baseHashValue = hashState(baseState, "react_view_with_data");
+    const pagedState = { [`_${baseHashValue}_page`]: "2" };
+    const pagedResult = await view.run(pagedState, mockReqRes);
+    const pagedHash = extractAttr(pagedResult, "state-hash");
+
+    expect(pagedHash).toBe(baseHash);
+  });
+});