@asteby/metacore-runtime-react 23.11.1 → 23.12.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @asteby/metacore-runtime-react
 
+## 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
+
+- 990bb63: DynamicForm oculta los campos readonly (estado de conexión, valores escritos por sync): el servidor los posee, el form no los captura ni los envía en el submit.
+
 ## 23.11.1
 
 ### Patch Changes

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-form.d.ts","sourceRoot":"","sources":["../src/dynamic-form.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EACH,cAAc,EACd,aAAa,EAKhB,MAAM,uBAAuB,CAAA;AAO9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAuB,EACvB,WAAwB,EACxB,QAAgB,GACnB,EAAE,gBAAgB,+BAoFlB"}
+{"version":3,"file":"dynamic-form.d.ts","sourceRoot":"","sources":["../src/dynamic-form.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EACH,cAAc,EACd,aAAa,EAKhB,MAAM,uBAAuB,CAAA;AAO9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAuB,EACvB,WAAwB,EACxB,QAAgB,GACnB,EAAE,gBAAgB,+BA8FlB"}

package/dist/dynamic-form.js

@@ -19,22 +19,28 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
     const [values, setValues] = useState({});
     const [errors, setErrors] = useState({});
     const [submitting, setSubmitting] = useState(false);
-    const schema = useMemo(() => buildZodSchema(fields), [fields]);
+    // Readonly fields are system-owned (connection state, sync-written values):
+    // the server writes them, so the form never captures them — hidden outright
+    // instead of rendered disabled, matching the metadata contract
+    // (ColumnDef.Readonly). They are also excluded from defaults/submit so a
+    // create never posts e.g. `status: ""` over the column default.
+    const editableFields = useMemo(() => fields.filter((f) => !f.readonly), [fields]);
+    const schema = useMemo(() => buildZodSchema(editableFields), [editableFields]);
     // Line-items fields carrying a balance rule gate submit: an unbalanced entry
     // (Σdebit ≠ Σcredit, or all-zero when require_nonzero) can't be saved. This
     // is fully declarative — `evaluateBalance` returns undefined for fields with
     // no rule, so non-balanced forms are unaffected.
     const balanceBlocked = useMemo(() => {
-        for (const f of fields) {
+        for (const f of editableFields) {
             const state = evaluateBalance(f, values[f.key]);
             if (state && !state.balanced)
                 return true;
         }
         return false;
-    }, [fields, values]);
+    }, [editableFields, values]);
     useEffect(() => {
         const defaults = {};
-        for (const f of fields) {
+        for (const f of editableFields) {
             if (isLineItemsField(f)) {
                 defaults[f.key] = initialValues?.[f.key] ?? f.defaultValue ?? [];
                 continue;
@@ -43,7 +49,7 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
         }
         setValues(defaults);
         setErrors({});
-    }, [fields, initialValues]);
+    }, [editableFields, initialValues]);
     const update = (k, v) => setValues((prev) => ({ ...prev, [k]: v }));
     const handleSubmit = async (e) => {
         e.preventDefault();
@@ -73,7 +79,7 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
     // line-items grids (and textareas) span the full width so the row table /
     // memo gets room. Mirrors the pro look of the federated journal modal but
     // stays fully declarative — driven only by field shape.
-    return (_jsxs("form", { onSubmit: handleSubmit, className: "grid gap-4", children: [_jsx("div", { className: "grid gap-4 sm:grid-cols-2", children: fields.map((field) => (_jsx(FieldRow, { field: field, value: values[field.key], onChange: (v) => update(field.key, v), values: values, error: errors[field.key], initialValues: initialValues }, field.key))) }), _jsxs("div", { className: "flex justify-end gap-2 pt-2", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: submitting || disabled, children: cancelLabel })), _jsx(Button, { type: "submit", disabled: submitting || disabled || balanceBlocked, children: submitLabel })] })] }));
+    return (_jsxs("form", { onSubmit: handleSubmit, className: "grid gap-4", children: [_jsx("div", { className: "grid gap-4 sm:grid-cols-2", children: editableFields.map((field) => (_jsx(FieldRow, { field: field, value: values[field.key], onChange: (v) => update(field.key, v), values: values, error: errors[field.key], initialValues: initialValues }, field.key))) }), _jsxs("div", { className: "flex justify-end gap-2 pt-2", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: submitting || disabled, children: cancelLabel })), _jsx(Button, { type: "submit", disabled: submitting || disabled || balanceBlocked, children: submitLabel })] })] }));
 }
 // One form field row: label + renderer + inline error. Encapsulated as its own
 // component so a STATIC enum select whose options are all gated out by a sibling

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.1",
+  "version": "23.12.0",
   "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-form.tsx

@@ -58,23 +58,33 @@ export function DynamicForm({
     const [errors, setErrors] = useState<Record<string, string>>({})
     const [submitting, setSubmitting] = useState(false)
 
-    const schema = useMemo(() => buildZodSchema(fields), [fields])
+    // Readonly fields are system-owned (connection state, sync-written values):
+    // the server writes them, so the form never captures them — hidden outright
+    // instead of rendered disabled, matching the metadata contract
+    // (ColumnDef.Readonly). They are also excluded from defaults/submit so a
+    // create never posts e.g. `status: ""` over the column default.
+    const editableFields = useMemo(
+        () => fields.filter((f) => !(f as { readonly?: boolean }).readonly),
+        [fields],
+    )
+
+    const schema = useMemo(() => buildZodSchema(editableFields), [editableFields])
 
     // Line-items fields carrying a balance rule gate submit: an unbalanced entry
     // (Σdebit ≠ Σcredit, or all-zero when require_nonzero) can't be saved. This
     // is fully declarative — `evaluateBalance` returns undefined for fields with
     // no rule, so non-balanced forms are unaffected.
     const balanceBlocked = useMemo(() => {
-        for (const f of fields) {
+        for (const f of editableFields) {
             const state = evaluateBalance(f, values[f.key])
             if (state && !state.balanced) return true
         }
         return false
-    }, [fields, values])
+    }, [editableFields, values])
 
     useEffect(() => {
         const defaults: Record<string, any> = {}
-        for (const f of fields) {
+        for (const f of editableFields) {
             if (isLineItemsField(f)) {
                 defaults[f.key] = initialValues?.[f.key] ?? f.defaultValue ?? []
                 continue
@@ -83,7 +93,7 @@ export function DynamicForm({
         }
         setValues(defaults)
         setErrors({})
-    }, [fields, initialValues])
+    }, [editableFields, initialValues])
 
     const update = (k: string, v: any) =>
         setValues((prev: Record<string, any>) => ({ ...prev, [k]: v }))
@@ -113,7 +123,7 @@ export function DynamicForm({
     return (
         <form onSubmit={handleSubmit} className="grid gap-4">
             <div className="grid gap-4 sm:grid-cols-2">
-                {fields.map((field) => (
+                {editableFields.map((field) => (
                     <FieldRow
                         key={field.key}
                         field={field}

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) })
+        },
+    })
+}