@kubex/zinc 1.1.132 → 1.1.134

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

@@ -35,6 +35,10 @@ Picking a filter from `+ Add filter` opens its pill straight away, with a text f
 
 The component emits `zn-filter-change` and exposes the query on `value`, encoded exactly as `zn-query-builder` encodes it — base64 of `[{key, comparator, value}]` — so a backend built against the query builder needs no changes.
 
+Setting `value` round-trips: assigning that same base64 string back — for example restoring it from a shared URL via `zn-data-table`'s [`sharable`](/components/data-table#shareable-url-state) sync — rebuilds the active pills, so the bar reopens in the state it was encoded in. Restoration needs the `filters` schema present to resolve each key, and it stands down once any filter already holds a value, so a shared filter still wins over an empty `default-filters` pill while a filter the user is mid-way through setting is never clobbered.
+
+One caveat: a restored **date** filter shows its raw encoded value on the pill (a timestamp, or a minutes-from-now offset) rather than a formatted date, because the human-readable label is not part of the encoded query. The filter still applies correctly; only the pill text differs until the value is re-picked.
+
 ### Long Option Lists
 
 An option list caps its height at 320px and scrolls inside the panel rather than running off the

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

@@ -643,6 +643,41 @@ Prevent automatic data loading on mount with `no-initial-load`. Call the `refres
 </script>
 ```
 
+### Shareable URL State
+
+Set `sharable` to mirror the table's **non-default** state to the URL query string and restore it on load, so a view can be copied straight from the address bar and reproduced elsewhere. What syncs: the search text, the filter, the sort column and direction, the current page, the page size, and any search `fields` values.
+
+Only state that differs from its initial/default value is written, so the URL stays clean — the default sort and direction, page 1, the default page size and an empty search/filter/fields are all omitted. Unrelated query parameters (for example `utm_*`) are left untouched. Updates use `history.replaceState`, so they never add browser-history entries.
+
+On load, the table seeds its state from the query string before the first request. A URL parameter is only adopted as a field value when a matching `[name="…"]` control exists in the table's light DOM; anything else is left alone as an unrelated parameter. When combined with `no-initial-load`, a URL that carries relevant parameters forces the first load anyway, so a shared link never lands on an empty table.
+
+```html
+<zn-data-table
+  sharable
+  standalone
+  caption="Users"
+  data-uri="/api/users"
+  headers='[
+    {"key":"name","label":"Name", "sortable":true},
+    {"key":"email","label":"Email", "sortable":true},
+    {"key":"status","label":"Status", "sortable":true}
+  ]'>
+
+  <zn-data-table-search slot="search" placeholder="Search users..."></zn-data-table-search>
+
+  <zn-data-table-filter
+    slot="filter"
+    default-filters="status"
+    filters='[
+      {"id":"status","name":"Status","options":{"active":"Active","inactive":"Inactive"},"operators":["eq"]}
+    ]'>
+  </zn-data-table-filter>
+
+</zn-data-table>
+```
+
+Opening `/users?search=acme&status=<encoded>&page=2` reproduces that exact search, filter and page; sorting a column or paging then rewrites the query in place.
+
 ### Standalone Mode
 
 Use `standalone` when the table supplies its own panel rather than sitting inside one. It renders a `zn-panel`, passing `caption` through as the panel's caption, the header controls into its `actions` slot and the pagination into its `footer` slot, with the rows flush against the panel edges. Columns scroll under the panel's edges, so the border stays put on a wide table.
@@ -889,7 +924,7 @@ The data table expects responses in the following format:
 
 ## Request Format
 
-For POST requests, the table sends:
+For POST requests, the table sends a JSON body:
 
 ```json
 {
@@ -898,8 +933,14 @@ For POST requests, the table sends:
   "sortColumn": "name",
   "sortDirection": "asc",
   "filter": "",
-  "search": "search term"
+  "search": "search term",
+  "searchFields": {
+    "q": "search term",
+    "status": "open"
+  }
 }
 ```
 
-Additional parameters from the `inputs` slot are merged into the request.
+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`.

package/package.json

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

package/scss/themes/_light.scss

@@ -246,7 +246,7 @@
   --zn-input-color-focus: var(--zn-color-neutral-700);
   --zn-input-color-disabled: var(--zn-color-neutral-800);
   --zn-input-icon-color: var(--zn-color-neutral-500);
-  --zn-input-icon-color-hover: var(--zn-color-neutral-600);
+  --zn-input-icon-color-hover: var(--zn-color-neutral-800);
   --zn-input-icon-color-focus: var(--zn-color-neutral-600);
   --zn-input-placeholder-color: var(--zn-text-input-placeholder-color);
   --zn-input-placeholder-color-disabled: var(--zn-color-neutral-600);

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

@@ -151,6 +151,9 @@ 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;
 }
 
 type AllowedInputElement =
@@ -269,6 +272,12 @@ export default class ZnDataTable extends ZincElement {
 
   @property({attribute: "no-initial-load", type: Boolean}) noInitialLoad: boolean = false;
 
+  /**
+   * When set, the table's non-default state (search, filter, sort, page, per-page and field values)
+   *is mirrored to the URL query string and restored from it on load, so the view is shareable.
+   */
+  @property({attribute: 'sharable', type: Boolean}) sharable: boolean = false;
+
   @property({attribute: 'group-by'}) groupBy = '';
 
   @property() groups = '';
@@ -282,6 +291,11 @@ export default class ZnDataTable extends ZincElement {
   private _lastLoadHadRows = false;
   private _lastTableContent: TemplateResult = html``;
 
+  // Sharable (URL <-> state) sync
+  private _sharableInitialised = false;
+  private _sharableDefaults: Record<string, string> | null = null;
+  private readonly _urlManagedKeys = new Set<string>(['search', 'filter', 'sortColumn', 'sortDirection', 'page', 'perPage']);
+
   private readonly resizeObserver = new ResizeController(this, {
     target: null,
     callback: () => {
@@ -320,6 +334,10 @@ export default class ZnDataTable extends ZincElement {
 
   private _dataTask = new Task(this, {
     task: async ([dataUri, requestParams], {signal}) => {
+      // Every request path funnels through the task, so this is the single place to mirror the
+      // current (non-default) state to the URL when `sharable` is set.
+      this._updateSharableUrl();
+
       if (dataUri === undefined || this.noInitialLoad && this._initialLoad) {
         return {rows: [], page: 1, perPage: this.itemsPerPage, total: 0};
       }
@@ -338,7 +356,8 @@ export default class ZnDataTable extends ZincElement {
         search: this.search,
       };
 
-      // get all inputs that are in the inputs slot and add them to the
+      // 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.
       const inputs = this.hasSlotController.getSlots(ActionSlots.inputs.valueOf());
       const params: Record<string, any> = {};
       if (inputs) {
@@ -355,11 +374,25 @@ export default class ZnDataTable extends ZincElement {
         Object.assign(requestData, params);
       }
 
-      // Add any extra request 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') {
-        Object.assign(requestData, requestParams);
+        for (const [key, value] of Object.entries(requestParams as Record<string, unknown>)) {
+          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;
+
       // This is also used for Rubix, so it may not work for your application.
       const response = await fetch(dataUri, {
         method: this.method,
@@ -439,6 +472,177 @@ export default class ZnDataTable extends ZincElement {
     this._deselectedColumns = deselected;
   }
 
+  // Reserved (non-field) URL param names that map onto dedicated table state.
+  private static readonly _sharableKnownKeys = ['search', 'filter', 'sortColumn', 'sortDirection', 'page', 'perPage'];
+
+  /**
+   * Snapshot the initial (attribute-provided) value of every managed key, so the URL writer can
+   * omit any key still holding its default - e.g. the table's default sort/direction, page 1 or the
+   * default page size. Captured once, before the URL is read, so URL values are treated as deltas.
+   */
+  private _captureSharableDefaults() {
+    if (this._sharableDefaults) return;
+    this._sharableDefaults = {
+      search: this.search || '',
+      filter: this.filter || '',
+      sortColumn: this.sortColumn || '',
+      sortDirection: this.sortDirection || '',
+      page: String(this.page),
+      perPage: String(this.itemsPerPage),
+    };
+  }
+
+  /**
+   * Seed the table state from the URL query string (raw param names) when `sharable` is set. Runs
+   * once, before the first render, so the initial data request already carries the shared state.
+   */
+  private _readSharableState() {
+    if (!this.sharable || this._sharableInitialised) return;
+    if (typeof window === 'undefined') return;
+    this._sharableInitialised = true;
+
+    const params = new URLSearchParams(window.location.search);
+    let hasRelevant = false;
+
+    if (params.has('search')) {
+      this.search = params.get('search')!;
+      hasRelevant = true;
+    }
+    if (params.has('filter')) {
+      this.filter = params.get('filter')!;
+      hasRelevant = true;
+    }
+    if (params.has('sortColumn')) {
+      this.sortColumn = params.get('sortColumn')!;
+      hasRelevant = true;
+    }
+    if (params.has('sortDirection')) {
+      this.sortDirection = params.get('sortDirection')!;
+      hasRelevant = true;
+    }
+    if (params.has('page')) {
+      const page = parseInt(params.get('page')!, 10);
+      if (!isNaN(page) && page > 0) this.page = page;
+      hasRelevant = true;
+    }
+    if (params.has('perPage')) {
+      const perPage = parseInt(params.get('perPage')!, 10);
+      if (!isNaN(perPage) && perPage > 0) this.itemsPerPage = perPage;
+      hasRelevant = true;
+    }
+
+    // Any remaining param is adopted as an extra field value only when it maps to an actual field in
+    // the table. Unrelated params (e.g. utm_*) are left untouched so they survive the round-trip.
+    const known = new Set(ZnDataTable._sharableKnownKeys);
+    const extras: Record<string, any> = {};
+    params.forEach((value, key) => {
+      if (known.has(key) || !this._hasFieldNamed(key)) return;
+      hasRelevant = true;
+      this._urlManagedKeys.add(key);
+      extras[key] = value;
+    });
+    if (Object.keys(extras).length > 0) {
+      this.requestParams = {...this.requestParams, ...extras};
+    }
+
+    // A shared link must render results even when no-initial-load is set - otherwise the recipient
+    // would land on an empty table. Force the first load when the URL carries relevant params.
+    if (hasRelevant && this.noInitialLoad) {
+      this._initialLoad = false;
+    }
+  }
+
+  /**
+   * Push the shared state back into the actual DOM fields so the UI reflects it. The search value
+   * lives on the slotted <zn-data-table-search>, the filter on <zn-data-table-filter>, and extra
+   * field params on the search/inputs fields (all light-DOM descendants).
+   */
+  private _populateSharableFields() {
+    if (this.search) {
+      const searchEl = this.querySelector('zn-data-table-search') as (Element & { value?: unknown }) | null;
+      if (searchEl) searchEl.value = this.search;
+    }
+
+    if (this.filter) {
+      const filterEl = this.querySelector('zn-data-table-filter') as (Element & { value?: unknown }) | null;
+      if (filterEl) filterEl.value = this.filter;
+    }
+
+    const known = new Set(ZnDataTable._sharableKnownKeys);
+    Object.entries(this.requestParams).forEach(([name, value]) => {
+      if (known.has(name) || name === 'searchUri' || value === undefined || value === null) return;
+      this._setSharableFieldValue(name, String(value));
+    });
+  }
+
+  private _hasFieldNamed(name: string): boolean {
+    try {
+      const selector = `[name="${window.CSS && CSS.escape ? CSS.escape(name) : name}"]`;
+      return this.querySelector(selector) !== null;
+    } catch {
+      return false;
+    }
+  }
+
+  private _setSharableFieldValue(name: string, value: string) {
+    let selector: string;
+    try {
+      selector = `[name="${window.CSS && CSS.escape ? CSS.escape(name) : name}"]`;
+    } catch {
+      selector = `[name="${name}"]`;
+    }
+
+    this.querySelectorAll(selector).forEach((field) => {
+      (field as Element & { value?: unknown }).value = value;
+      // Custom elements may read the value from the attribute (and it survives an upgrade).
+      if (field.tagName.includes('-')) {
+        field.setAttribute('value', value);
+      }
+    });
+  }
+
+  /**
+   * Mirror the current table state to the URL query string (raw param names) via replaceState.
+   * A key is written only when its value differs from the captured default, so the default sort,
+   * page 1, the default page size and empty search/filter/fields never clutter the URL. Unrelated
+   * params (e.g. utm_*) are preserved.
+   */
+  private _updateSharableUrl() {
+    if (!this.sharable || !window?.history) return;
+    const defaults: Record<string, string> = this._sharableDefaults ?? {};
+
+    const params = new URLSearchParams(window.location.search);
+
+    // Drop every key the table manages, then re-add only the ones that differ from their default.
+    this._urlManagedKeys.forEach((key) => params.delete(key));
+
+    const setParam = (key: string, value: unknown) => {
+      this._urlManagedKeys.add(key);
+      const str = value === undefined || value === null ? '' : String(value);
+      if (str === '' || str === (defaults[key] || '')) return;
+      params.set(key, str);
+    };
+
+    // Extra field values (searchFields) - 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;
+      setParam(key, value);
+    });
+
+    setParam('search', this.search);
+    setParam('filter', this.filter);
+    setParam('sortColumn', this.sortColumn);
+    setParam('sortDirection', this.sortDirection);
+    setParam('page', this.page);
+    setParam('perPage', this.itemsPerPage);
+
+
+    const queryString = params.toString();
+    const newUrl = `${window.location.pathname}${queryString ? `?${queryString}` : ''}${window.location.hash}`;
+    window.history.replaceState(window.history.state, '', newUrl);
+  }
+
   render() {
     this.applyColumnDefaults();
 
@@ -557,6 +761,16 @@ export default class ZnDataTable extends ZincElement {
     this.addEventListener('zn-filter-change', this.filterChangeListener);
     this.addEventListener('zn-clear', this.filterClearListener);
     this.addEventListener('zn-search-change', this.searchChangeListener);
+    // Capture defaults before reading the URL so URL values are treated as deltas, then seed state.
+    this._captureSharableDefaults();
+    this._readSharableState();
+  }
+
+  protected firstUpdated() {
+    // Push the shared state back into the slotted fields once they exist in the DOM.
+    if (this.sharable) {
+      this._populateSharableFields();
+    }
   }
 
   protected updated(changed: PropertyValues) {
@@ -1234,6 +1448,8 @@ export default class ZnDataTable extends ZincElement {
 
       if (this.localSort) {
         this._rows = this.sortLocalData(this._rows as Row[]);
+        // Local sort never runs the data task (our URL-sync choke point), so mirror it here.
+        this._updateSharableUrl();
         this.requestUpdate();
       } else {
         this._dataTask.run().then(r => r);

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

@@ -322,4 +322,209 @@ describe('<zn-data-table>', () => {
     expect(link).to.exist;
     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', () => {
+    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('wraps search-component 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 data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        await waitUntil(() => bodies.length > 0);
+
+        // Mirror what the search component's zn-search-change listener does: set the search text and
+        // merge its field values into requestParams, then reload.
+        el.search = 'foo';
+        el.requestParams = {status: 'open'};
+        el.refresh();
+        await waitUntil(() => bodies.some(b => b.search === 'foo'));
+
+        const body = bodies[bodies.length - 1];
+        expect(body.search).to.equal('foo');
+        expect(body.searchFields).to.deep.equal({status: 'open', q: 'foo'});
+      } finally {
+        window.fetch = originalFetch;
+      }
+    });
+
+    it('sends searchFields as null 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);
+
+        expect(bodies[bodies.length - 1].searchFields).to.be.null;
+      } finally {
+        window.fetch = originalFetch;
+      }
+    });
+
+    it('keeps inputs-slot params at the request root, not inside searchFields', 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);
+
+        const body = bodies[bodies.length - 1];
+        expect(body.csrf).to.equal('tok');
+        expect(body.searchFields).to.be.null;
+      } finally {
+        window.fetch = originalFetch;
+      }
+    });
+  });
+
+  // `sharable` mirrors non-default state to the URL query string and restores it on load. These
+  // tests mutate window.location/history, so each one restores the original URL in a finally block
+  // and preserves the pre-existing query (web-test-runner keeps its session id there).
+  describe('sharable URL state', () => {
+    const okResponse = () => 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'}});
+
+    const MANAGED = ['search', 'filter', 'sortColumn', 'sortDirection', 'page', 'perPage'];
+
+    // Start from the live query (keeping unmanaged params like the WTR session id) with every
+    // managed key cleared, then overlay whatever the test wants to seed.
+    const seedUrl = (overlay: Record<string, string> = {}) => {
+      const params = new URLSearchParams(window.location.search);
+      MANAGED.forEach(key => params.delete(key));
+      Object.entries(overlay).forEach(([key, value]) => params.set(key, value));
+      const query = params.toString();
+      window.history.replaceState(window.history.state, '', `${window.location.pathname}${query ? `?${query}` : ''}`);
+    };
+
+    it('seeds the table state from the URL query string on load', async () => {
+      const originalFetch = window.fetch;
+      const originalUrl = window.location.href;
+      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(okResponse());
+      };
+      seedUrl({search: 'foo', page: '2'});
+
+      try {
+        await fixture<ZnDataTable>(html`
+          <zn-data-table sharable data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        await waitUntil(() => bodies.length > 0);
+
+        // The very first request already carries the shared state.
+        expect(bodies[0].search).to.equal('foo');
+        expect(bodies[0].page).to.equal(2);
+      } finally {
+        window.fetch = originalFetch;
+        window.history.replaceState(window.history.state, '', originalUrl);
+      }
+    });
+
+    it('writes only changed state to the URL, omitting keys still at their default', async () => {
+      const originalFetch = window.fetch;
+      const originalUrl = window.location.href;
+      window.fetch = () => Promise.resolve(okResponse());
+      seedUrl();
+
+      try {
+        const el = await fixture<ZnDataTable>(html`
+          <zn-data-table sharable data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        await waitUntil(() => el.shadowRoot!.querySelector('tbody tr.table__row--data'));
+
+        el.search = 'bar';
+        el.refresh();
+        await waitUntil(() => window.location.search.includes('search=bar'));
+
+        const params = new URLSearchParams(window.location.search);
+        expect(params.get('search')).to.equal('bar');
+        // Page 1 and the unset/default sort are omitted rather than written out.
+        expect(params.has('page')).to.be.false;
+        expect(params.has('sortColumn')).to.be.false;
+        expect(params.has('perPage')).to.be.false;
+      } finally {
+        window.fetch = originalFetch;
+        window.history.replaceState(window.history.state, '', originalUrl);
+      }
+    });
+
+    it('preserves unrelated query params when syncing state', async () => {
+      const originalFetch = window.fetch;
+      const originalUrl = window.location.href;
+      window.fetch = () => Promise.resolve(okResponse());
+      seedUrl({utm_source: 'news'});
+
+      try {
+        const el = await fixture<ZnDataTable>(html`
+          <zn-data-table sharable data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        await waitUntil(() => el.shadowRoot!.querySelector('tbody tr.table__row--data'));
+
+        el.search = 'bar';
+        el.refresh();
+        await waitUntil(() => window.location.search.includes('search=bar'));
+
+        const params = new URLSearchParams(window.location.search);
+        expect(params.get('utm_source')).to.equal('news');
+        expect(params.get('search')).to.equal('bar');
+      } finally {
+        window.fetch = originalFetch;
+        window.history.replaceState(window.history.state, '', originalUrl);
+      }
+    });
+
+    it('forces the first load under no-initial-load when the URL carries relevant params', async () => {
+      const originalFetch = window.fetch;
+      const originalUrl = window.location.href;
+      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(okResponse());
+      };
+      seedUrl({search: 'foo'});
+
+      try {
+        await fixture<ZnDataTable>(html`
+          <zn-data-table sharable no-initial-load data-uri="/test-data" headers='{"name": {"key": "name", "label": "Name"}}'></zn-data-table>`);
+        // Despite no-initial-load, a shared link must render results, so the first load fires.
+        await waitUntil(() => bodies.length > 0);
+
+        expect(bodies[0].search).to.equal('foo');
+      } finally {
+        window.fetch = originalFetch;
+        window.history.replaceState(window.history.state, '', originalUrl);
+      }
+    });
+  });
 });

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

@@ -148,6 +148,13 @@ export default class ZnDataTableFilter extends ZincElement implements ZincFormCo
   protected willUpdate(changed: PropertyValues) {
     super.willUpdate(changed);
 
+    // Rebuild the active filters from an externally-set value (e.g. restored from a shareable URL)
+    // once both the value and the filters schema are available. Must run before the default-filters
+    // seeding so a shared filter wins over defaults.
+    if (changed.has('value') || changed.has('filters')) {
+      this.hydrateFromValue();
+    }
+
     if (changed.has('filters') && this._active.length === 0) {
       this.defaultFilters
         .split(',')
@@ -279,6 +286,44 @@ export default class ZnDataTableFilter extends ZincElement implements ZincFormCo
     this.emit('zn-filter-change');
   }
 
+  /**
+   * Rebuild the active filters from an encoded `value` (the inverse of emitChange), so a filter
+   * restored from a shareable URL shows its pills. Runs only while there are no active filters and
+   * needs the filters schema present to resolve each key. Sets `_active` directly so it neither
+   * re-emits nor overwrites the value it just read.
+   */
+  private hydrateFromValue() {
+    // Guard on valued filters (not just any pill) so default-filters' empty pills don't block a
+    // shared filter, and so a user's in-progress filter is never clobbered by a later value change.
+    if (!this.value || this.filters.length === 0 || this.activeCount > 0) return;
+
+    let decoded: unknown;
+    try {
+      decoded = JSON.parse(atob(this.value));
+    } catch {
+      return;
+    }
+    if (!Array.isArray(decoded)) return;
+
+    const active: ActiveFilter[] = [];
+    decoded.forEach((entry) => {
+      if (typeof entry !== 'object' || entry === null) return;
+      const cond = entry as {key?: string; comparator?: string; value?: unknown};
+      if (typeof cond.key !== 'string') return;
+
+      const filter = this.definition(cond.key);
+      if (!filter) return;
+
+      const comparator = (cond.comparator as QueryBuilderOperators) || this.comparatorFor(filter);
+      // Multi-value filters serialize as a joined string; tolerate an array form too.
+      const value = Array.isArray(cond.value) ? cond.value.join(' ') : String(cond.value ?? '');
+
+      active.push({key: cond.key, comparator, value});
+    });
+
+    if (active.length > 0) this._active = active;
+  }
+
   private handleDateInput(filter: QueryBuilderItem, active: ActiveFilter, event: Event) {
     const picker = event.target as ZnDatepicker;
     const timestamp = picker.timestamp;