@kubex/zinc 1.1.150 → 1.1.152

package/docs/pages/components/data-table.md

@@ -926,6 +926,30 @@ The data table expects responses in the following format:
 
 For POST requests, the table sends a JSON body:
 
+```json
+{
+  "page": 1,
+  "perPage": 10,
+  "sortColumn": "name",
+  "sortDirection": "asc",
+  "filter": "",
+  "search": "search term",
+  "status": "open"
+}
+```
+
+Field values from inputs slotted into a `zn-data-table-search`, and anything set on the table's `requestParams`, are merged at the **root** of the body under their own `name`. The search text itself is sent as `search`.
+
+Parameters from the `inputs` slot are context/system values (a CSRF token, a package name, and the like) sent with every request. They are merged at the root too.
+
+### Wrapped search fields
+
+Add `wrap-search-fields` to nest the search field values under a `searchFields` object instead, so a backend can bind them to a single map rather than arbitrary top-level keys:
+
+```html
+<zn-data-table wrap-search-fields data-uri="/data"></zn-data-table>
+```
+
 ```json
 {
   "page": 1,
@@ -941,6 +965,4 @@ For POST requests, the table sends a JSON body:
 }
 ```
 
-Field values from a slotted `zn-data-table-search`'s [`fields` slot](/components/data-table-search#filter-fields) are wrapped under `searchFields`, keeping them out of the request root so the backend can bind them to a single map rather than arbitrary top-level keys. `q` mirrors the `search` text, and the root `search` key is retained for back-compatibility. Empty values are dropped, and `searchFields` is `null` when nothing meaningful remains — no search text and no field values — so the backend can treat that as "no search".
-
-Parameters from the `inputs` slot are context/system values (a CSRF token, a package name, and the like) sent with every request. They are merged at the **root** of the body, not inside `searchFields`.
+`q` mirrors the `search` text, which is still sent at the root. Empty values are dropped, and `searchFields` is `null` when nothing meaningful remains — no search text and no field values — so the backend can treat that as "no search". Parameters from the `inputs` slot stay at the root either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.150",
+  "version": "1.1.152",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/src/components/data-table/data-table.component.ts

@@ -151,8 +151,6 @@ interface DataRequest {
   sortDirection: string;
   filter: string;
   search: string;
-  // Search-related fields (from the search component's `fields` slot) plus `q` (the search text),
-  // wrapped so the backend can bind them to a single map instead of arbitrary root-level keys.
   searchFields?: Record<string, any> | null;
 }
 
@@ -278,6 +276,13 @@ export default class ZnDataTable extends ZincElement {
    */
   @property({attribute: 'sharable', type: Boolean}) sharable: boolean = false;
 
+  /**
+   * When set, extra request params (search-component field values) are nested under a
+   * `searchFields` object - with `q` mirroring the search text - instead of being merged at the
+   * root of the request body.
+   */
+  @property({attribute: 'wrap-search-fields', type: Boolean}) wrapSearchFields: boolean = false;
+
   @property({attribute: 'group-by'}) groupBy = '';
 
   @property() groups = '';
@@ -357,7 +362,7 @@ export default class ZnDataTable extends ZincElement {
       };
 
       // Inputs-slot values are context/system params (e.g. csrf token, package name) sent with
-      // every request - they stay at the root of the payload.
+      // every request.
       const inputs = this.hasSlotController.getSlots(ActionSlots.inputs.valueOf());
       const params: Record<string, any> = {};
       if (inputs) {
@@ -374,24 +379,28 @@ export default class ZnDataTable extends ZincElement {
         Object.assign(requestData, params);
       }
 
-      // Search-related fields (from <zn-data-table-search>'s `fields` slot, delivered via
-      // requestParams) are wrapped under `searchFields` so the backend can bind them to a single
-      // map rather than arbitrary root-level keys. `q` mirrors the search text; the root `search`
-      // key is still sent for back-compatibility. Empty values are dropped, and `searchFields` is
-      // null when nothing meaningful remains so the backend can treat it as "no search".
-      const searchFields: Record<string, any> = {};
-      if (requestParams && typeof requestParams === 'object') {
-        for (const [key, value] of Object.entries(requestParams as Record<string, unknown>)) {
+      // Add any extra request params
+      const extraParams = requestParams && typeof requestParams === 'object'
+        ? requestParams as Record<string, unknown>
+        : {};
+
+      if (this.wrapSearchFields) {
+        // Opt-in shape: field values nested under `searchFields`, with `q` mirroring the search
+        // text, so a backend can bind them to one map. Empty values are dropped, and the key is
+        // null when nothing is set. The root `search` key is sent either way.
+        const searchFields: Record<string, any> = {};
+        for (const [key, value] of Object.entries(extraParams)) {
           if (value !== undefined && value !== null && value !== '') {
             searchFields[key] = value;
           }
         }
+        if (this.search || Object.keys(searchFields).length > 0) {
+          searchFields.q = this.search;
+        }
+        requestData.searchFields = Object.keys(searchFields).length > 0 ? searchFields : null;
+      } else {
+        Object.assign(requestData, extraParams);
       }
-      if (this.search || Object.keys(searchFields).length > 0) {
-        searchFields.q = this.search;
-      }
-
-      requestData.searchFields = Object.keys(searchFields).length > 0 ? searchFields : null;
 
       // This is also used for Rubix, so it may not work for your application.
       const response = await fetch(dataUri, {
@@ -623,7 +632,7 @@ export default class ZnDataTable extends ZincElement {
       params.set(key, str);
     };
 
-    // Extra field values (searchFields) - their default is empty, so setParam writes them only when set.
+    // Extra field values - their default is empty, so setParam writes them only when set.
     const known = new Set(ZnDataTable._sharableKnownKeys);
     Object.entries(this.requestParams).forEach(([key, value]) => {
       if (known.has(key) || key === 'searchUri') return;

package/src/components/data-table/data-table.test.ts

@@ -323,9 +323,9 @@ describe('<zn-data-table>', () => {
     expect(link?.hasAttribute('title')).to.be.false;
   });
 
-  // Search-component field values are nested under `searchFields` in the POST body, with `q`
-  // mirroring the search text, while the root `search` key is retained for back-compatibility.
-  describe('searchFields request wrapping', () => {
+  // Search-component field values and any other extra request params are merged at the root of
+  // the POST body, alongside the dedicated `search` key.
+  describe('extra request params', () => {
     const rowResponse = () => new Response(JSON.stringify({
       rows: [{id: '1', cells: [{text: 'Row', column: 'name'}]}],
       page: 1,
@@ -333,7 +333,7 @@ describe('<zn-data-table>', () => {
       total: 1,
     }), {status: 200, headers: {'Content-Type': 'application/json'}});
 
-    it('wraps search-component field values under searchFields with q mirroring the search text', async () => {
+    it('sends search-component field values at the root alongside search', async () => {
       const originalFetch = window.fetch;
       const bodies: Record<string, unknown>[] = [];
       window.fetch = (_url: RequestInfo | URL, options?: RequestInit) => {
@@ -355,6 +355,89 @@ describe('<zn-data-table>', () => {
 
         const body = bodies[bodies.length - 1];
         expect(body.search).to.equal('foo');
+        expect(body.status).to.equal('open');
+        expect(body.searchFields).to.be.undefined;
+      } finally {
+        window.fetch = originalFetch;
+      }
+    });
+
+    it('sends no extra keys when no search or field values are set', async () => {
+      const originalFetch = window.fetch;
+      const bodies: Record<string, unknown>[] = [];
+      window.fetch = (_url: RequestInfo | URL, options?: RequestInit) => {
+        if (options?.body) bodies.push(JSON.parse(options.body as string) as Record<string, unknown>);
+        return Promise.resolve(rowResponse());
+      };
+
+      try {
+        await fixture<ZnDataTable>(html`
+          <zn-data-table data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        await waitUntil(() => bodies.length > 0);
+
+        const known = ['filter', 'page', 'perPage', 'search', 'sortColumn', 'sortDirection'];
+        expect(Object.keys(bodies[bodies.length - 1]).filter(k => !known.includes(k))).to.deep.equal([]);
+      } finally {
+        window.fetch = originalFetch;
+      }
+    });
+
+    it('sends inputs-slot params at the request root', async () => {
+      const originalFetch = window.fetch;
+      const bodies: Record<string, unknown>[] = [];
+      window.fetch = (_url: RequestInfo | URL, options?: RequestInit) => {
+        if (options?.body) bodies.push(JSON.parse(options.body as string) as Record<string, unknown>);
+        return Promise.resolve(rowResponse());
+      };
+
+      try {
+        const el = await fixture<ZnDataTable>(html`
+          <zn-data-table data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'>
+            <input slot="inputs" name="csrf" value="tok">
+          </zn-data-table>`);
+        await waitUntil(() => bodies.length > 0);
+        el.refresh();
+        await waitUntil(() => bodies.length > 1);
+
+        expect(bodies[bodies.length - 1].csrf).to.equal('tok');
+      } finally {
+        window.fetch = originalFetch;
+      }
+    });
+  });
+
+  // With `wrap-search-fields`, the same values are nested under `searchFields` instead, with `q`
+  // mirroring the search text.
+  describe('wrap-search-fields', () => {
+    const rowResponse = () => new Response(JSON.stringify({
+      rows: [{id: '1', cells: [{text: 'Row', column: 'name'}]}],
+      page: 1,
+      perPage: 10,
+      total: 1,
+    }), {status: 200, headers: {'Content-Type': 'application/json'}});
+
+    it('nests field values under searchFields with q mirroring the search text', async () => {
+      const originalFetch = window.fetch;
+      const bodies: Record<string, unknown>[] = [];
+      window.fetch = (_url: RequestInfo | URL, options?: RequestInit) => {
+        if (options?.body) bodies.push(JSON.parse(options.body as string) as Record<string, unknown>);
+        return Promise.resolve(rowResponse());
+      };
+
+      try {
+        const el = await fixture<ZnDataTable>(html`
+          <zn-data-table wrap-search-fields data-uri="/test-data"
+                         headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        await waitUntil(() => bodies.length > 0);
+
+        el.search = 'foo';
+        el.requestParams = {status: 'open', empty: ''};
+        el.refresh();
+        await waitUntil(() => bodies.some(b => b.search === 'foo'));
+
+        const body = bodies[bodies.length - 1];
+        expect(body.search).to.equal('foo');
+        expect(body.status).to.be.undefined;
         expect(body.searchFields).to.deep.equal({status: 'open', q: 'foo'});
       } finally {
         window.fetch = originalFetch;
@@ -371,7 +454,8 @@ describe('<zn-data-table>', () => {
 
       try {
         await fixture<ZnDataTable>(html`
-          <zn-data-table data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+          <zn-data-table wrap-search-fields data-uri="/test-data"
+                         headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
         await waitUntil(() => bodies.length > 0);
 
         expect(bodies[bodies.length - 1].searchFields).to.be.null;
@@ -380,7 +464,7 @@ describe('<zn-data-table>', () => {
       }
     });
 
-    it('keeps inputs-slot params at the request root, not inside searchFields', async () => {
+    it('keeps inputs-slot params at the request root', async () => {
       const originalFetch = window.fetch;
       const bodies: Record<string, unknown>[] = [];
       window.fetch = (_url: RequestInfo | URL, options?: RequestInit) => {
@@ -390,7 +474,8 @@ describe('<zn-data-table>', () => {
 
       try {
         const el = await fixture<ZnDataTable>(html`
-          <zn-data-table data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'>
+          <zn-data-table wrap-search-fields data-uri="/test-data"
+                         headers='{"name": {"key": "name", "label": "Name"}}'>
             <input slot="inputs" name="csrf" value="tok">
           </zn-data-table>`);
         await waitUntil(() => bodies.length > 0);

package/src/components/page/page.component.ts

@@ -44,7 +44,7 @@ export default class ZnPage extends ZnTabs {
     'zn-tab': ZnTab
   };
 
-  private readonly pageSlotController = new HasSlotController(this, 'breadcrumb', 'actions', 'caption');
+  private readonly pageSlotController = new HasSlotController(this, 'breadcrumb', 'actions', 'caption', 'description');
 
   @property() caption: string;
   @property({attribute: 'entity-id'}) entityId: string;
@@ -442,6 +442,7 @@ export default class ZnPage extends ZnTabs {
     const hasEntityId = this.entityId;
     const hasFullLocation = this.fullLocation;
     const hasPreviousPath = this.previousPath;
+    const hasDescription = !!this.summary || this.pageSlotController.test('description');
 
     return html`
       <div class="page" part="base" @scroll="${this.handlePageScroll}">
@@ -455,7 +456,8 @@ export default class ZnPage extends ZnTabs {
             'header--has-entity-id': hasEntityId,
             'header--has-full-location': hasFullLocation,
             'header--has-navigation': hasNavigation,
-            'header--has-previous': hasPreviousPath
+            'header--has-previous': hasPreviousPath,
+            'header--has-description': hasDescription
           })}">
             ${hasFullLocation || hasEntityId ? html`
               <div class="${classMap({

package/src/components/page/page.scss

@@ -184,7 +184,7 @@
     display: flex;
     justify-content: flex-start;
     flex-direction: column;
-    gap: var(--zn-spacing-x-small);
+    gap: var(--zn-spacing-2x-small);
     min-height: 36px;
     flex-shrink: 1;
     min-width: 0;
@@ -215,6 +215,11 @@
     min-height: 36px; // Keep in step with the actions row: both bands share a centre line.
   }
 
+  // Stacked above a description the band buys no alignment, it only pads the gap.
+  &--has-description &__caption {
+    min-height: 0;
+  }
+
   &__description {
     @include wc.text-style(subheading);
     display: block;