@asteby/metacore-runtime-react 23.11.2 → 23.12.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @asteby/metacore-runtime-react
 
+## 23.12.1
+
+### Patch Changes
+
+- 8788161: fix(dynamic-table): stop infinite URL replaceState loop on filtered deep-links
+
+  The host router re-serializes the query string in its own canonical form
+  (different key order, percent-encoded operator colons) than the table writes,
+  so the raw-string comparison never matched and the table's write effect fought
+  the router's re-serialize forever ("Throttling navigation…" + React #185),
+  hanging any filtered sidebar view (e.g. `f_status=eq:reception`). Both URL-sync
+  effects now compare an order/encoding-independent fingerprint and the write is
+  skipped when semantically a no-op.
+
+## 23.12.0
+
+### Minor Changes
+
+- 9376722: Add `useAddonSettings` / `useUpdateAddonSettings` — the standard primitive for reading an addon's per-organization configuration from a federated addon, backed by react-query and the host-injected api client. Merges caller-provided defaults (mirroring the manifest's `settings[].default`) under the saved org values, so a never-saved setting falls back to its default. Also exports the pure `mergeAddonSettings` helper and the stable `addonSettingsKey` query key.
+
 ## 23.11.2
 
 ### 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,+BAujCnB"}
+{"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"}

package/dist/dynamic-table.js

@@ -114,6 +114,21 @@ 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.
+    const canonicalSearch = (searchStr) => {
+        const p = new URLSearchParams(searchStr);
+        const entries = [];
+        p.forEach((value, key) => entries.push(`${key}=${value}`));
+        entries.sort();
+        return entries.join('&');
+    };
     useEffect(() => {
         if (!enableUrlSync || initializedFromUrl.current)
             return;
@@ -195,6 +210,16 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
                 params.set(`f_${key}`, `in:${values.join(',')}`);
         });
         const search = params.toString();
+        // If what we'd write is semantically identical to what's already in the
+        // bar (only key order / colon-encoding differ from the router's form),
+        // skip the write entirely. Rewriting would flip the raw string, the
+        // router would re-serialize back to its form, and the two would ping-pong
+        // forever. We still adopt the current location as "ours" so the resync
+        // effect below doesn't treat the router's spelling as an external change.
+        if (canonicalSearch(search) === canonicalSearch(window.location.search)) {
+            lastSelfSearch.current = window.location.search;
+            return;
+        }
         const newUrl = search ? `${window.location.pathname}?${search}` : window.location.pathname;
         lastSelfSearch.current = search ? `?${search}` : '';
         window.history.replaceState(null, '', newUrl);
@@ -209,7 +234,9 @@ export function DynamicTable({ model, endpoint, enableUrlSync = true, hiddenColu
     useEffect(() => {
         if (!enableUrlSync || !initializedFromUrl.current)
             return;
-        if (locationSearch === lastSelfSearch.current)
+        // Semantic compare: the router's spelling of the query string we just
+        // wrote (different order/encoding) is NOT an external change.
+        if (canonicalSearch(locationSearch) === canonicalSearch(lastSelfSearch.current ?? ''))
             return;
         lastSelfSearch.current = locationSearch;
         const params = new URLSearchParams(locationSearch);

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export * from './org-runtime-provider';
 export * from './navigation-builder';
 export * from './i18n-provider';
 export * from './api-context';
+export * from './use-addon-settings';
 export * from './metadata-cache';
 export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, type AddonManifestChangedMessage, type ManifestHotSwapClient, type WireHotSwapInvalidationOptions, } from './manifest-hotswap-subscriber';
 export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, type HotSwapReloadStrategy, type HotSwapReloadConfig, type HotSwapReloadAction, type HotSwapReloadDeps, type UseHotSwapReloadResult, } from './hotswap-reload-policy';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -30,6 +30,7 @@ export * from './org-runtime-provider';
 export * from './navigation-builder';
 export * from './i18n-provider';
 export * from './api-context';
+export * from './use-addon-settings';
 export * from './metadata-cache';
 export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, } from './manifest-hotswap-subscriber';
 export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, } from './hotswap-reload-policy';

package/dist/use-addon-settings.d.ts

@@ -0,0 +1,56 @@
+/** Stable react-query key for an addon's per-org settings. */
+export declare function addonSettingsKey(addonKey: string): readonly ["addon-settings", string];
+/**
+ * Merge saved org values over the caller's defaults so a never-saved setting
+ * falls back to its default. Pure + exported for unit testing. Only keys that
+ * are actually present in `stored` win — an explicit `undefined` in the stored
+ * payload is treated as "not saved" and yields the default (the host omits
+ * unsaved keys, but this keeps a sparse payload well-behaved).
+ */
+export declare function mergeAddonSettings<T extends Record<string, unknown>>(defaults: Partial<T> | undefined, stored: Partial<T> | null | undefined): T;
+export interface UseAddonSettingsOptions<T> {
+    /**
+     * Fallback values (typically the addon manifest's `settings[].default`)
+     * merged UNDER the saved org values. A setting the org hasn't saved
+     * resolves to its default here.
+     */
+    defaults?: Partial<T>;
+    /** Override staleTime (default 30s — org config changes rarely). */
+    staleTime?: number;
+    /** Defer fetching (e.g. until the addon key is known). */
+    enabled?: boolean;
+}
+export interface UseAddonSettingsResult<T> {
+    /** Saved org values merged over `defaults`. Never null. */
+    settings: T;
+    isLoading: boolean;
+    error: unknown;
+    refetch: () => void;
+}
+/**
+ * Read an addon's per-organization settings.
+ *
+ * This is the ecosystem-standard way for a federated addon to read its own
+ * config; prefer it over a hand-rolled fetch so every addon caches, merges
+ * defaults, and invalidates identically.
+ *
+ * @example
+ * type PosSettings = { allowNegativeStock: boolean; roundingMode: string }
+ * const { settings, isLoading } = useAddonSettings<PosSettings>('pos', {
+ *   defaults: { allowNegativeStock: false, roundingMode: 'nearest' },
+ * })
+ * if (!isLoading && settings.allowNegativeStock) { ... }
+ */
+export declare function useAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(addonKey: string, opts?: UseAddonSettingsOptions<T>): UseAddonSettingsResult<T>;
+/**
+ * Optional write companion — PUTs a (partial) settings object and invalidates
+ * the read query so `useAddonSettings` re-resolves. The host's generic config
+ * modal does its own PUT; this exists for addons that ship a custom config
+ * surface. Backward-compatible: purely additive.
+ *
+ * @example
+ * const update = useUpdateAddonSettings('pos')
+ * update.mutate({ allowNegativeStock: true })
+ */
+export declare function useUpdateAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(addonKey: string): import("@tanstack/react-query").UseMutationResult<Partial<T>, Error, Partial<T>, unknown>;
+//# sourceMappingURL=use-addon-settings.d.ts.map

package/dist/use-addon-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-addon-settings.d.ts","sourceRoot":"","sources":["../src/use-addon-settings.ts"],"names":[],"mappings":"AA6BA,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,uCAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAChC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GACtC,CAAC,CAQH;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,CAAA;IACX,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxF,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACtC,sBAAsB,CAAC,CAAC,CAAC,CA8B3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9F,QAAQ,EAAE,MAAM,6FAgBnB"}

package/dist/use-addon-settings.js

@@ -0,0 +1,109 @@
+// useAddonSettings — THE standard primitive for reading an addon's
+// per-organization configuration from a federated addon (or any host
+// surface) without every addon re-implementing its own fetch.
+//
+// The host (ops) persists settings per org on `AddonInstallation.settings`
+// (jsonb) and exposes:
+//   GET  /api/addons/:key/settings  → { success, data: { <key>: <value> } }
+//   PUT  /api/addons/:key/settings  → body = object of values
+// A setting the org has never saved simply isn't present in `data`; the
+// caller supplies the fallback via `opts.defaults` (which mirror the
+// manifest's `settings[].default`). runtime-react has no access to the
+// addon manifest at runtime, so defaults are a parameter, not automatic.
+//
+// react-query is a PEER dependency of runtime-react: `useQuery`/`useMutation`
+// resolve to the HOST's singleton QueryClient (the MF shared singleton), so
+// this hook never constructs its own client and stays cache-coherent with
+// the rest of the app. Do not add a QueryClientProvider here.
+//
+// Server-side gating (wasm/Go backends) is out of scope here: a backend that
+// must gate behaviour on org config reads the same `AddonInstallation.settings`
+// jsonb directly — this hook is the client-read half of that contract.
+import { useMemo } from 'react';
+import { useMutation, useQuery, useQueryClient, } from '@tanstack/react-query';
+import { useApi } from './api-context';
+/** Stable react-query key for an addon's per-org settings. */
+export function addonSettingsKey(addonKey) {
+    return ['addon-settings', addonKey];
+}
+/**
+ * Merge saved org values over the caller's defaults so a never-saved setting
+ * falls back to its default. Pure + exported for unit testing. Only keys that
+ * are actually present in `stored` win — an explicit `undefined` in the stored
+ * payload is treated as "not saved" and yields the default (the host omits
+ * unsaved keys, but this keeps a sparse payload well-behaved).
+ */
+export function mergeAddonSettings(defaults, stored) {
+    const out = { ...(defaults ?? {}) };
+    if (stored) {
+        for (const [k, v] of Object.entries(stored)) {
+            if (v !== undefined)
+                out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Read an addon's per-organization settings.
+ *
+ * This is the ecosystem-standard way for a federated addon to read its own
+ * config; prefer it over a hand-rolled fetch so every addon caches, merges
+ * defaults, and invalidates identically.
+ *
+ * @example
+ * type PosSettings = { allowNegativeStock: boolean; roundingMode: string }
+ * const { settings, isLoading } = useAddonSettings<PosSettings>('pos', {
+ *   defaults: { allowNegativeStock: false, roundingMode: 'nearest' },
+ * })
+ * if (!isLoading && settings.allowNegativeStock) { ... }
+ */
+export function useAddonSettings(addonKey, opts = {}) {
+    const api = useApi();
+    const { defaults, staleTime, enabled } = opts;
+    const query = useQuery({
+        queryKey: addonSettingsKey(addonKey),
+        queryFn: async () => {
+            const res = await api.get(`/api/addons/${addonKey}/settings`);
+            const body = res.data;
+            // Host envelope: { success, data: { <key>: <value> } }.
+            const values = body?.success ? body.data : body;
+            return (values ?? {});
+        },
+        staleTime: staleTime ?? 30_000,
+        enabled: (enabled ?? true) && !!addonKey,
+    });
+    const settings = useMemo(() => mergeAddonSettings(defaults, query.data), [defaults, query.data]);
+    return {
+        settings,
+        isLoading: query.isLoading,
+        error: query.error,
+        refetch: () => {
+            void query.refetch();
+        },
+    };
+}
+/**
+ * Optional write companion — PUTs a (partial) settings object and invalidates
+ * the read query so `useAddonSettings` re-resolves. The host's generic config
+ * modal does its own PUT; this exists for addons that ship a custom config
+ * surface. Backward-compatible: purely additive.
+ *
+ * @example
+ * const update = useUpdateAddonSettings('pos')
+ * update.mutate({ allowNegativeStock: true })
+ */
+export function useUpdateAddonSettings(addonKey) {
+    const api = useApi();
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: async (values) => {
+            const res = await api.put(`/api/addons/${addonKey}/settings`, values);
+            const body = res.data;
+            const saved = body?.success ? body.data : body;
+            return (saved ?? values);
+        },
+        onSuccess: () => {
+            void qc.invalidateQueries({ queryKey: addonSettingsKey(addonKey) });
+        },
+    });
+}

package/package.json

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

package/src/__tests__/use-addon-settings.test.ts

@@ -0,0 +1,74 @@
+// Locks the default-merge semantics of the useAddonSettings primitive: saved
+// org values win over caller defaults, never-saved keys fall back to their
+// default, and a sparse/undefined stored payload stays well-behaved. The hook
+// itself is a thin react-query wrapper over `useApi`; the load-bearing logic
+// is this pure merge, so that's what we test directly.
+import { describe, it, expect } from 'vitest'
+import { mergeAddonSettings, addonSettingsKey } from '../use-addon-settings'
+
+interface PosSettings extends Record<string, unknown> {
+    allowNegativeStock: boolean
+    roundingMode: string
+    taxRate: number
+}
+
+describe('mergeAddonSettings', () => {
+    const defaults: Partial<PosSettings> = {
+        allowNegativeStock: false,
+        roundingMode: 'nearest',
+        taxRate: 0,
+    }
+
+    it('falls back to defaults when nothing is stored', () => {
+        expect(mergeAddonSettings<PosSettings>(defaults, null)).toEqual({
+            allowNegativeStock: false,
+            roundingMode: 'nearest',
+            taxRate: 0,
+        })
+        expect(mergeAddonSettings<PosSettings>(defaults, undefined)).toEqual(defaults)
+        expect(mergeAddonSettings<PosSettings>(defaults, {})).toEqual(defaults)
+    })
+
+    it('lets saved org values override defaults', () => {
+        expect(
+            mergeAddonSettings<PosSettings>(defaults, { allowNegativeStock: true, taxRate: 16 }),
+        ).toEqual({
+            allowNegativeStock: true,
+            roundingMode: 'nearest',
+            taxRate: 16,
+        })
+    })
+
+    it('keeps falsy saved values (0, false, "") instead of treating them as unset', () => {
+        expect(
+            mergeAddonSettings<PosSettings>(
+                { allowNegativeStock: true, roundingMode: 'up', taxRate: 5 },
+                { allowNegativeStock: false, roundingMode: '', taxRate: 0 },
+            ),
+        ).toEqual({ allowNegativeStock: false, roundingMode: '', taxRate: 0 })
+    })
+
+    it('treats an explicit undefined in the stored payload as unset', () => {
+        expect(
+            mergeAddonSettings<PosSettings>(defaults, { roundingMode: undefined }),
+        ).toEqual(defaults)
+    })
+
+    it('returns an object even with no defaults', () => {
+        expect(mergeAddonSettings(undefined, { a: 1 })).toEqual({ a: 1 })
+        expect(mergeAddonSettings(undefined, null)).toEqual({})
+    })
+
+    it('does not mutate the provided defaults object', () => {
+        const d = { ...defaults }
+        mergeAddonSettings<PosSettings>(d, { taxRate: 99 })
+        expect(d).toEqual(defaults)
+    })
+})
+
+describe('addonSettingsKey', () => {
+    it('is stable and namespaced per addon', () => {
+        expect(addonSettingsKey('pos')).toEqual(['addon-settings', 'pos'])
+        expect(addonSettingsKey('inventory')).toEqual(['addon-settings', 'inventory'])
+    })
+})

package/src/dynamic-table.tsx

@@ -229,6 +229,22 @@ 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.
+    const canonicalSearch = (searchStr: string): string => {
+        const p = new URLSearchParams(searchStr)
+        const entries: string[] = []
+        p.forEach((value, key) => entries.push(`${key}=${value}`))
+        entries.sort()
+        return entries.join('&')
+    }
+
     useEffect(() => {
         if (!enableUrlSync || initializedFromUrl.current) return
         initializedFromUrl.current = true
@@ -295,6 +311,16 @@ export function DynamicTable({
             else params.set(`f_${key}`, `in:${values.join(',')}`)
         })
         const search = params.toString()
+        // If what we'd write is semantically identical to what's already in the
+        // bar (only key order / colon-encoding differ from the router's form),
+        // skip the write entirely. Rewriting would flip the raw string, the
+        // router would re-serialize back to its form, and the two would ping-pong
+        // forever. We still adopt the current location as "ours" so the resync
+        // effect below doesn't treat the router's spelling as an external change.
+        if (canonicalSearch(search) === canonicalSearch(window.location.search)) {
+            lastSelfSearch.current = window.location.search
+            return
+        }
         const newUrl = search ? `${window.location.pathname}?${search}` : window.location.pathname
         lastSelfSearch.current = search ? `?${search}` : ''
         window.history.replaceState(null, '', newUrl)
@@ -309,7 +335,9 @@ export function DynamicTable({
     const locationSearch = typeof window !== 'undefined' ? window.location.search : ''
     useEffect(() => {
         if (!enableUrlSync || !initializedFromUrl.current) return
-        if (locationSearch === lastSelfSearch.current) return
+        // Semantic compare: the router's spelling of the query string we just
+        // wrote (different order/encoding) is NOT an external change.
+        if (canonicalSearch(locationSearch) === canonicalSearch(lastSelfSearch.current ?? '')) return
         lastSelfSearch.current = locationSearch
         const params = new URLSearchParams(locationSearch)
         const filters: Record<string, string[]> = {}

package/src/index.ts

@@ -165,6 +165,7 @@ export * from './org-runtime-provider'
 export * from './navigation-builder'
 export * from './i18n-provider'
 export * from './api-context'
+export * from './use-addon-settings'
 export * from './metadata-cache'
 export {
     ADDON_MANIFEST_CHANGED_TYPE,

package/src/use-addon-settings.ts

@@ -0,0 +1,152 @@
+// useAddonSettings — THE standard primitive for reading an addon's
+// per-organization configuration from a federated addon (or any host
+// surface) without every addon re-implementing its own fetch.
+//
+// The host (ops) persists settings per org on `AddonInstallation.settings`
+// (jsonb) and exposes:
+//   GET  /api/addons/:key/settings  → { success, data: { <key>: <value> } }
+//   PUT  /api/addons/:key/settings  → body = object of values
+// A setting the org has never saved simply isn't present in `data`; the
+// caller supplies the fallback via `opts.defaults` (which mirror the
+// manifest's `settings[].default`). runtime-react has no access to the
+// addon manifest at runtime, so defaults are a parameter, not automatic.
+//
+// react-query is a PEER dependency of runtime-react: `useQuery`/`useMutation`
+// resolve to the HOST's singleton QueryClient (the MF shared singleton), so
+// this hook never constructs its own client and stays cache-coherent with
+// the rest of the app. Do not add a QueryClientProvider here.
+//
+// Server-side gating (wasm/Go backends) is out of scope here: a backend that
+// must gate behaviour on org config reads the same `AddonInstallation.settings`
+// jsonb directly — this hook is the client-read half of that contract.
+import { useMemo } from 'react'
+import {
+    useMutation,
+    useQuery,
+    useQueryClient,
+} from '@tanstack/react-query'
+import { useApi } from './api-context'
+
+/** Stable react-query key for an addon's per-org settings. */
+export function addonSettingsKey(addonKey: string) {
+    return ['addon-settings', addonKey] as const
+}
+
+/**
+ * Merge saved org values over the caller's defaults so a never-saved setting
+ * falls back to its default. Pure + exported for unit testing. Only keys that
+ * are actually present in `stored` win — an explicit `undefined` in the stored
+ * payload is treated as "not saved" and yields the default (the host omits
+ * unsaved keys, but this keeps a sparse payload well-behaved).
+ */
+export function mergeAddonSettings<T extends Record<string, unknown>>(
+    defaults: Partial<T> | undefined,
+    stored: Partial<T> | null | undefined,
+): T {
+    const out: Record<string, unknown> = { ...(defaults ?? {}) }
+    if (stored) {
+        for (const [k, v] of Object.entries(stored)) {
+            if (v !== undefined) out[k] = v
+        }
+    }
+    return out as T
+}
+
+export interface UseAddonSettingsOptions<T> {
+    /**
+     * Fallback values (typically the addon manifest's `settings[].default`)
+     * merged UNDER the saved org values. A setting the org hasn't saved
+     * resolves to its default here.
+     */
+    defaults?: Partial<T>
+    /** Override staleTime (default 30s — org config changes rarely). */
+    staleTime?: number
+    /** Defer fetching (e.g. until the addon key is known). */
+    enabled?: boolean
+}
+
+export interface UseAddonSettingsResult<T> {
+    /** Saved org values merged over `defaults`. Never null. */
+    settings: T
+    isLoading: boolean
+    error: unknown
+    refetch: () => void
+}
+
+/**
+ * Read an addon's per-organization settings.
+ *
+ * This is the ecosystem-standard way for a federated addon to read its own
+ * config; prefer it over a hand-rolled fetch so every addon caches, merges
+ * defaults, and invalidates identically.
+ *
+ * @example
+ * type PosSettings = { allowNegativeStock: boolean; roundingMode: string }
+ * const { settings, isLoading } = useAddonSettings<PosSettings>('pos', {
+ *   defaults: { allowNegativeStock: false, roundingMode: 'nearest' },
+ * })
+ * if (!isLoading && settings.allowNegativeStock) { ... }
+ */
+export function useAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(
+    addonKey: string,
+    opts: UseAddonSettingsOptions<T> = {},
+): UseAddonSettingsResult<T> {
+    const api = useApi()
+    const { defaults, staleTime, enabled } = opts
+
+    const query = useQuery<Partial<T>>({
+        queryKey: addonSettingsKey(addonKey),
+        queryFn: async () => {
+            const res = await api.get(`/api/addons/${addonKey}/settings`)
+            const body = (res as { data: any }).data
+            // Host envelope: { success, data: { <key>: <value> } }.
+            const values = body?.success ? body.data : body
+            return (values ?? {}) as Partial<T>
+        },
+        staleTime: staleTime ?? 30_000,
+        enabled: (enabled ?? true) && !!addonKey,
+    })
+
+    const settings = useMemo(
+        () => mergeAddonSettings<T>(defaults, query.data),
+        [defaults, query.data],
+    )
+
+    return {
+        settings,
+        isLoading: query.isLoading,
+        error: query.error,
+        refetch: () => {
+            void query.refetch()
+        },
+    }
+}
+
+/**
+ * Optional write companion — PUTs a (partial) settings object and invalidates
+ * the read query so `useAddonSettings` re-resolves. The host's generic config
+ * modal does its own PUT; this exists for addons that ship a custom config
+ * surface. Backward-compatible: purely additive.
+ *
+ * @example
+ * const update = useUpdateAddonSettings('pos')
+ * update.mutate({ allowNegativeStock: true })
+ */
+export function useUpdateAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(
+    addonKey: string,
+) {
+    const api = useApi()
+    const qc = useQueryClient()
+
+    return useMutation<Partial<T>, Error, Partial<T>>({
+        mutationFn: async (values) => {
+            const res = await api.put(`/api/addons/${addonKey}/settings`, values)
+            const body = (res as { data: any }).data
+            const saved = body?.success ? body.data : body
+            return (saved ?? values) as Partial<T>
+        },
+        onSuccess: () => {
+            void qc.invalidateQueries({ queryKey: addonSettingsKey(addonKey) })
+        },
+    })
+}