@asteby/metacore-runtime-react 23.12.1 → 23.12.3

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @asteby/metacore-runtime-react
 
+## 23.12.3
+
+### Patch Changes
+
+- 5e46e61: fix(dynamic-table): don't strip a deep-linked filter on first mount (URL race)
+
+  The URL-write effect ran on the very first commit — when `initializedFromUrl`
+  (a ref) is already true but the init effect's `setDynamicFilters` hasn't
+  re-rendered yet — so it wrote a URL WITHOUT `f_status`, stripping a
+  deep-linked/reloaded filter and flickering the address bar until it settled
+  without the filter. Gate the write on a STATE flag (`urlSynced`) set once the
+  URL has been adopted, so the first write only happens on the render where
+  `dynamicFilters`/`pagination` already mirror the URL (a true no-op).
+
+## 23.12.2
+
+### Patch Changes
+
+- 5333315: fix(dynamic-table): don't rewrite a clean filtered deep-link (no URL flicker)
+
+  Normalise the `eq:` operator when fingerprinting the query string and stop
+  stamping `per_page` for the plain server default, so opening/clicking a
+  sidebar deep-link (`f_status=eq:in_progress&view=list`) is a true no-op: the
+  table adopts the filter without rewriting the URL to its own spelling
+  (`f_status=in_progress&per_page=15`). This removes the visible URL flicker and
+  keeps the sidebar active-state exact-href match working.
+
 ## 23.12.1
 
 ### Patch Changes

package/dist/dynamic-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-table.d.ts","sourceRoot":"","sources":["../src/dynamic-table.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAKH,KAAK,SAAS,EAajB,MAAM,uBAAuB,CAAA;AAgC9B,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAanF,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC/B,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,wBAAgB,YAAY,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,aAAoB,EACpB,aAAkB,EAClB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAiB,EACjB,iBAA4C,EAC5C,QAAQ,EACR,QAAQ,EACR,cAAsB,GACzB,EAAE,iBAAiB,+BAmlCnB"}
+{"version":3,"file":"dynamic-table.d.ts","sourceRoot":"","sources":["../src/dynamic-table.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAKH,KAAK,SAAS,EAajB,MAAM,uBAAuB,CAAA;AAgC9B,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAanF,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAA;IAC/B,cAAc,CAAC,EAAE,GAAG,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACpC,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,wBAAgB,YAAY,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,aAAoB,EACpB,aAAkB,EAClB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAiB,EACjB,iBAA4C,EAC5C,QAAQ,EACR,QAAQ,EACR,cAAsB,GACzB,EAAE,iBAAiB,+BAsnCnB"}

package/dist/dynamic-table.js

@@ -78,6 +78,24 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
     const [filterOptionsMap, setFilterOptionsMap] = useState(new Map());
     const initializedFromUrl = useRef(false);
     const urlHadPerPage = useRef(false);
+    // The model's server-declared default page size. When the current page size
+    // is just this default (the user hasn't paged/resized and the URL didn't
+    // pin one), we deliberately DON'T stamp `per_page` into the URL — otherwise
+    // the table appends `per_page=15` to the sidebar's clean deep-link on mount,
+    // which reads as a URL flicker and fights the router's spelling. Starts at 10
+    // to match the initial pagination state until metadata arrives.
+    const defaultPerPage = useRef(10);
+    // Has the table finished adopting its state FROM the URL yet? The write
+    // effect must not run before this flips true. `initializedFromUrl` is a ref
+    // set synchronously at the top of the init effect, so on the very first
+    // commit the write effect (which runs right after, in the SAME commit) sees
+    // `initialized=true` but `dynamicFilters` still EMPTY — the init effect's
+    // setState hasn't re-rendered yet — and writes a URL WITHOUT `f_status`,
+    // stripping a deep-linked filter (the "recarga quita el filtro y parpadea"
+    // bug). A STATE flag defers the first write to the render AFTER the URL has
+    // been adopted, where `dynamicFilters`/`pagination` already mirror the URL,
+    // so the write is a no-op and the filter never gets stripped.
+    const [urlSynced, setUrlSynced] = useState(false);
     useEffect(() => {
         if (prevBranchId.current !== currentBranch?.id) {
             prevBranchId.current = currentBranch?.id;
@@ -114,18 +132,26 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
         const alias = operatorToUrlAlias[prefix];
         return alias ? `${alias}:${rest}` : value;
     };
-    // Order- and encoding-independent fingerprint of a query string. The host
-    // router (TanStack) re-serializes the same params in its own canonical form
-    // — different key order and percent-encoded operator colons
-    // (`f_status=eq%3Areception`) — than the table writes (`f_status=eq:reception`).
-    // Comparing raw strings then NEVER matches, so the table's write effect and
-    // the router's re-serialize fight forever ("Throttling navigation…" +
-    // React #185). URLSearchParams decodes values, so a sorted `key=value` list
-    // is stable across both spellings and lets us detect real no-ops.
+    // Order-, encoding- and operator-independent fingerprint of a query string.
+    // The host router (TanStack) and the sidebar deep-link the filter in THEIR
+    // canonical form — different key order, percent-encoded operator colons, and
+    // the explicit `eq:` operator (`f_status=eq%3Ain_progress`) — while the table
+    // internally unwraps `eq:` for selects and would write the bare value
+    // (`f_status=in_progress`). Comparing raw (or even just decoded) strings then
+    // NEVER matches, so the table rewrites the URL on every navigation and the
+    // two spellings visibly ping-pong ("parpadeo", "Throttling navigation…" +
+    // React #185). Normalising each `f_` value through `urlValueToInternal`
+    // collapses `eq:X` and `X` to the same token, so a sorted `key=value` list is
+    // a true semantic fingerprint and the write effect can detect real no-ops —
+    // leaving the router's own spelling untouched (so the sidebar active-state
+    // match on the exact href keeps working too).
     const canonicalSearch = (searchStr) => {
         const p = new URLSearchParams(searchStr);
         const entries = [];
-        p.forEach((value, key) => entries.push(`${key}=${value}`));
+        p.forEach((value, key) => {
+            const norm = key.startsWith('f_') ? urlValueToInternal(value) : value;
+            entries.push(`${key}=${norm}`);
+        });
         entries.sort();
         return entries.join('&');
     };
@@ -166,13 +192,16 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
         });
         if (Object.keys(filters).length > 0)
             setDynamicFilters(filters);
+        // Adopted everything the URL carries; the write effect may now run on the
+        // NEXT render (where the setState above has landed) without clobbering it.
+        setUrlSynced(true);
     }, []); // eslint-disable-line react-hooks/exhaustive-deps
     // The exact query string this table last wrote to the URL — lets the
     // resync effect below tell "our own replaceState" apart from an external
     // rewrite by the host router.
     const lastSelfSearch = useRef(null);
     useEffect(() => {
-        if (!enableUrlSync || !initializedFromUrl.current)
+        if (!enableUrlSync || !urlSynced)
             return;
         const params = new URLSearchParams();
         // Preserve the route-owned view params. The table rebuilds the query
@@ -191,7 +220,10 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
         }
         if (pagination.pageIndex > 0)
             params.set('page', String(pagination.pageIndex + 1));
-        if (pagination.pageSize !== 10)
+        // Only pin per_page when it deviates from the model's default (an explicit
+        // user page-size change) or the URL already carried one — not for the
+        // plain server default, which would needlessly mutate a clean deep-link.
+        if (pagination.pageSize !== defaultPerPage.current || urlHadPerPage.current)
             params.set('per_page', String(pagination.pageSize));
         if (sorting.length > 0) {
             params.set('sortBy', sorting[0].id);
@@ -223,7 +255,7 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
         const newUrl = search ? `${window.location.pathname}?${search}` : window.location.pathname;
         lastSelfSearch.current = search ? `?${search}` : '';
         window.history.replaceState(null, '', newUrl);
-    }, [enableUrlSync, pagination, sorting, globalFilter, dynamicFilters, defaultFilters]);
+    }, [enableUrlSync, urlSynced, pagination, sorting, globalFilter, dynamicFilters, defaultFilters]);
     // The host router can rewrite the query string WITHOUT remounting the
     // table — e.g. sidebar sibling entries deep-link different `f_` filters
     // into the same model route. The mount-time init above never re-runs, so
@@ -296,6 +328,7 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
             // localStorage.
             if (cached) {
                 setMetadata(cached);
+                defaultPerPage.current = cached.defaultPerPage || 10;
                 if (!urlHadPerPage.current)
                     setPagination((prev) => ({ ...prev, pageSize: cached.defaultPerPage || 10 }));
                 setLoading(false);
@@ -311,6 +344,7 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
                     meta = fresh;
                     setMetadata(fresh);
                     cacheMetadata(model, fresh);
+                    defaultPerPage.current = fresh.defaultPerPage || 10;
                     if (!urlHadPerPage.current)
                         setPagination((prev) => ({ ...prev, pageSize: fresh.defaultPerPage || 10 }));
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "23.12.1",
+  "version": "23.12.3",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/dynamic-table.tsx

@@ -190,6 +190,24 @@ export function DynamicTable({
 
     const initializedFromUrl = useRef(false)
     const urlHadPerPage = useRef(false)
+    // The model's server-declared default page size. When the current page size
+    // is just this default (the user hasn't paged/resized and the URL didn't
+    // pin one), we deliberately DON'T stamp `per_page` into the URL — otherwise
+    // the table appends `per_page=15` to the sidebar's clean deep-link on mount,
+    // which reads as a URL flicker and fights the router's spelling. Starts at 10
+    // to match the initial pagination state until metadata arrives.
+    const defaultPerPage = useRef(10)
+    // Has the table finished adopting its state FROM the URL yet? The write
+    // effect must not run before this flips true. `initializedFromUrl` is a ref
+    // set synchronously at the top of the init effect, so on the very first
+    // commit the write effect (which runs right after, in the SAME commit) sees
+    // `initialized=true` but `dynamicFilters` still EMPTY — the init effect's
+    // setState hasn't re-rendered yet — and writes a URL WITHOUT `f_status`,
+    // stripping a deep-linked filter (the "recarga quita el filtro y parpadea"
+    // bug). A STATE flag defers the first write to the render AFTER the URL has
+    // been adopted, where `dynamicFilters`/`pagination` already mirror the URL,
+    // so the write is a no-op and the filter never gets stripped.
+    const [urlSynced, setUrlSynced] = useState(false)
 
     useEffect(() => {
         if (prevBranchId.current !== currentBranch?.id) {
@@ -229,18 +247,26 @@ export function DynamicTable({
         return alias ? `${alias}:${rest}` : value
     }
 
-    // Order- and encoding-independent fingerprint of a query string. The host
-    // router (TanStack) re-serializes the same params in its own canonical form
-    // — different key order and percent-encoded operator colons
-    // (`f_status=eq%3Areception`) — than the table writes (`f_status=eq:reception`).
-    // Comparing raw strings then NEVER matches, so the table's write effect and
-    // the router's re-serialize fight forever ("Throttling navigation…" +
-    // React #185). URLSearchParams decodes values, so a sorted `key=value` list
-    // is stable across both spellings and lets us detect real no-ops.
+    // Order-, encoding- and operator-independent fingerprint of a query string.
+    // The host router (TanStack) and the sidebar deep-link the filter in THEIR
+    // canonical form — different key order, percent-encoded operator colons, and
+    // the explicit `eq:` operator (`f_status=eq%3Ain_progress`) — while the table
+    // internally unwraps `eq:` for selects and would write the bare value
+    // (`f_status=in_progress`). Comparing raw (or even just decoded) strings then
+    // NEVER matches, so the table rewrites the URL on every navigation and the
+    // two spellings visibly ping-pong ("parpadeo", "Throttling navigation…" +
+    // React #185). Normalising each `f_` value through `urlValueToInternal`
+    // collapses `eq:X` and `X` to the same token, so a sorted `key=value` list is
+    // a true semantic fingerprint and the write effect can detect real no-ops —
+    // leaving the router's own spelling untouched (so the sidebar active-state
+    // match on the exact href keeps working too).
     const canonicalSearch = (searchStr: string): string => {
         const p = new URLSearchParams(searchStr)
         const entries: string[] = []
-        p.forEach((value, key) => entries.push(`${key}=${value}`))
+        p.forEach((value, key) => {
+            const norm = key.startsWith('f_') ? urlValueToInternal(value) : value
+            entries.push(`${key}=${norm}`)
+        })
         entries.sort()
         return entries.join('&')
     }
@@ -274,6 +300,9 @@ export function DynamicTable({
             }
         })
         if (Object.keys(filters).length > 0) setDynamicFilters(filters)
+        // Adopted everything the URL carries; the write effect may now run on the
+        // NEXT render (where the setState above has landed) without clobbering it.
+        setUrlSynced(true)
     }, []) // eslint-disable-line react-hooks/exhaustive-deps
 
     // The exact query string this table last wrote to the URL — lets the
@@ -282,7 +311,7 @@ export function DynamicTable({
     const lastSelfSearch = useRef<string | null>(null)
 
     useEffect(() => {
-        if (!enableUrlSync || !initializedFromUrl.current) return
+        if (!enableUrlSync || !urlSynced) return
         const params = new URLSearchParams()
         // Preserve the route-owned view params. The table rebuilds the query
         // string from scratch (it only knows its own page/sort/filter keys), but
@@ -298,7 +327,11 @@ export function DynamicTable({
             if (v) params.set(key, v)
         }
         if (pagination.pageIndex > 0) params.set('page', String(pagination.pageIndex + 1))
-        if (pagination.pageSize !== 10) params.set('per_page', String(pagination.pageSize))
+        // Only pin per_page when it deviates from the model's default (an explicit
+        // user page-size change) or the URL already carried one — not for the
+        // plain server default, which would needlessly mutate a clean deep-link.
+        if (pagination.pageSize !== defaultPerPage.current || urlHadPerPage.current)
+            params.set('per_page', String(pagination.pageSize))
         if (sorting.length > 0) {
             params.set('sortBy', sorting[0].id)
             params.set('order', sorting[0].desc ? 'desc' : 'asc')
@@ -324,7 +357,7 @@ export function DynamicTable({
         const newUrl = search ? `${window.location.pathname}?${search}` : window.location.pathname
         lastSelfSearch.current = search ? `?${search}` : ''
         window.history.replaceState(null, '', newUrl)
-    }, [enableUrlSync, pagination, sorting, globalFilter, dynamicFilters, defaultFilters])
+    }, [enableUrlSync, urlSynced, pagination, sorting, globalFilter, dynamicFilters, defaultFilters])
 
     // The host router can rewrite the query string WITHOUT remounting the
     // table — e.g. sidebar sibling entries deep-link different `f_` filters
@@ -389,6 +422,7 @@ export function DynamicTable({
             // localStorage.
             if (cached) {
                 setMetadata(cached)
+                defaultPerPage.current = cached.defaultPerPage || 10
                 if (!urlHadPerPage.current) setPagination((prev: PaginationState) => ({ ...prev, pageSize: cached.defaultPerPage || 10 }))
                 setLoading(false)
             } else {
@@ -402,6 +436,7 @@ export function DynamicTable({
                     meta = fresh
                     setMetadata(fresh)
                     cacheMetadata(model, fresh)
+                    defaultPerPage.current = fresh.defaultPerPage || 10
                     if (!urlHadPerPage.current) setPagination((prev: PaginationState) => ({ ...prev, pageSize: fresh.defaultPerPage || 10 }))
                 }
             } catch (error) {