@qumra/jisr 1.0.1 → 1.0.3

package/README.md

@@ -347,18 +347,18 @@ const myAction: AppBridgeAction = {
 
 | Package | Description |
 |---------|-------------|
-| [@qumra/jisr](https://www.npmjs.com/package/@qumra/jisr) | React hooks for app bridge communication |
-| [@qumra/config](https://www.npmjs.com/package/@qumra/config) | Centralized config management for Qumra apps |
-| [@qumra/logger](https://www.npmjs.com/package/@qumra/logger) | Structured logging utility |
-| [@qumra/ui](https://www.npmjs.com/package/@qumra/ui) | Reusable React component library |
-| [@qumra/api-client](https://www.npmjs.com/package/@qumra/api-client) | API client for Qumra services |
-| [@qumra/types](https://www.npmjs.com/package/@qumra/types) | Shared TypeScript type definitions |
-| [@qumra/utils](https://www.npmjs.com/package/@qumra/utils) | Common utility functions |
+| [@qumra/app-sdk](https://www.npmjs.com/package/@qumra/app-sdk) | Core SDK — sessions, security, errors |
+| [@qumra/app-react-router](https://www.npmjs.com/package/@qumra/app-react-router) | React Router 7 integration |
+| [@qumra/app-session-storage-prisma](https://www.npmjs.com/package/@qumra/app-session-storage-prisma) | Prisma session storage |
+| [@qumra/app-session-storage-mongodb](https://www.npmjs.com/package/@qumra/app-session-storage-mongodb) | MongoDB session storage |
+| [@qumra/jisr](https://www.npmjs.com/package/@qumra/jisr) | App Bridge for iframe communication |
+| [@qumra/manara](https://www.npmjs.com/package/@qumra/manara) | Design system & components |
+| [@qumra/riwaq](https://www.npmjs.com/package/@qumra/riwaq) | UI Extensions SDK |
 
 ## License
 
-ISC © [Nicetag](https://github.com/nicetag)
+ISC © Qumra
 
-## Repository
+## Documentation
 
-[github.com/nicetag/qumra-apps-sdk](https://github.com/nicetag/qumra-apps-sdk)
+https://docs.qumra.cloud

package/dist/hooks/context.d.ts

@@ -12,6 +12,8 @@ export interface QumraAppBridgeProviderProps {
     children: React.ReactNode;
     /** Configuration for the AppBridge instance */
     config: AppBridgeConfig;
+    /** Custom navigate handler. If not provided, uses built-in SPA navigation (pushState + popstate). */
+    navigate?: (url: string) => void;
 }
 /**
  * Provider component for AppBridge
@@ -19,18 +21,18 @@ export interface QumraAppBridgeProviderProps {
  *
  * @example
  * ```tsx
- * import { QumraAppBridgeProvider } from '@qumra/app-bridge-react';
+ * // Works out of the box — built-in navigation
+ * <QumraAppBridgeProvider config={{ apiKey: 'your-api-key' }}>
+ *   <YourApp />
+ * </QumraAppBridgeProvider>
  *
- * export default function App() {
- *   return (
- *     <QumraAppBridgeProvider config={{ apiKey: 'your-api-key' }}>
- *       <YourApp />
- *     </QumraAppBridgeProvider>
- *   );
- * }
+ * // Or with a custom navigate handler
+ * <QumraAppBridgeProvider config={{ apiKey }} navigate={(url) => navigate(url)}>
+ *   <YourApp />
+ * </QumraAppBridgeProvider>
  * ```
  */
-export declare function QumraAppBridgeProvider({ children, config, }: QumraAppBridgeProviderProps): JSX.Element;
+export declare function QumraAppBridgeProvider({ children, config, navigate, }: QumraAppBridgeProviderProps): JSX.Element;
 /**
  * Internal hook to get the AppBridge context
  * @internal
@@ -38,4 +40,9 @@ export declare function QumraAppBridgeProvider({ children, config, }: QumraAppBr
  * @throws Error if used outside of QumraAppBridgeProvider
  */
 export declare function useAppBridgeContext(): AppBridge;
+/**
+ * Internal hook to get the app-level navigate handler
+ * @internal
+ */
+export declare function useAppNavigate(): (url: string) => void;
 //# sourceMappingURL=context.d.ts.map

package/dist/hooks/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/hooks/context.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKzE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,8DAA8D;IAC9D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,MAAM,GACP,EAAE,2BAA2B,GAAG,GAAG,CAAC,OAAO,CAkB3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAU/C"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/hooks/context.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAoBzE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,8DAA8D;IAC9D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,eAAe,CAAC;IACxB,qGAAqG;IACrG,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,MAAM,EACN,QAAQ,GACT,EAAE,2BAA2B,GAAG,GAAG,CAAC,OAAO,CAwB3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAU/C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAGtD"}

package/dist/hooks/context.js

@@ -7,34 +7,49 @@ import React from 'react';
 import { AppBridge } from '../utils/app-bridge.js';
 /** React Context for AppBridge instance */
 const AppBridgeContext = React.createContext(null);
+/** App-level navigate handler */
+const NavigateContext = React.createContext(null);
+/**
+ * Built-in navigate that works with React Router and most SPA routers.
+ * Uses pushState + popstate event which routers listen to.
+ */
+function defaultNavigate(url) {
+    if (typeof window === 'undefined')
+        return;
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new PopStateEvent('popstate'));
+}
 /**
  * Provider component for AppBridge
  * Must wrap your application to provide the AppBridge to all hooks
  *
  * @example
  * ```tsx
- * import { QumraAppBridgeProvider } from '@qumra/app-bridge-react';
+ * // Works out of the box — built-in navigation
+ * <QumraAppBridgeProvider config={{ apiKey: 'your-api-key' }}>
+ *   <YourApp />
+ * </QumraAppBridgeProvider>
  *
- * export default function App() {
- *   return (
- *     <QumraAppBridgeProvider config={{ apiKey: 'your-api-key' }}>
- *       <YourApp />
- *     </QumraAppBridgeProvider>
- *   );
- * }
+ * // Or with a custom navigate handler
+ * <QumraAppBridgeProvider config={{ apiKey }} navigate={(url) => navigate(url)}>
+ *   <YourApp />
+ * </QumraAppBridgeProvider>
  * ```
  */
-export function QumraAppBridgeProvider({ children, config, }) {
+export function QumraAppBridgeProvider({ children, config, navigate, }) {
     const [bridge] = React.useState(() => new AppBridge(config));
+    const navigateRef = React.useRef(navigate ?? defaultNavigate);
+    navigateRef.current = navigate ?? defaultNavigate;
     React.useEffect(() => {
-        // Signal to the host that the app is ready
+        bridge.setNavigateHandler((path) => {
+            navigateRef.current(path);
+        });
         bridge.ready();
-        // Cleanup on unmount
         return () => {
             bridge.destroy();
         };
     }, [bridge]);
-    return (_jsx(AppBridgeContext.Provider, { value: bridge, children: children }));
+    return (_jsx(AppBridgeContext.Provider, { value: bridge, children: _jsx(NavigateContext.Provider, { value: navigateRef, children: children }) }));
 }
 /**
  * Internal hook to get the AppBridge context
@@ -49,4 +64,12 @@ export function useAppBridgeContext() {
     }
     return context;
 }
+/**
+ * Internal hook to get the app-level navigate handler
+ * @internal
+ */
+export function useAppNavigate() {
+    const ref = React.useContext(NavigateContext);
+    return ref?.current ?? defaultNavigate;
+}
 //# sourceMappingURL=context.js.map

package/dist/hooks/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/hooks/context.tsx"],"names":[],"mappings":";AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAwB,MAAM,wBAAwB,CAAC;AAEzE,2CAA2C;AAC3C,MAAM,gBAAgB,GAAG,KAAK,CAAC,aAAa,CAAmB,IAAI,CAAC,CAAC;AAYrE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,EACrC,QAAQ,EACR,MAAM,GACsB;IAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAE7D,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,2CAA2C;QAC3C,MAAM,CAAC,KAAK,EAAE,CAAC;QAEf,qBAAqB;QACrB,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,CACL,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YACrC,QAAQ,GACiB,CAC7B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAEnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/hooks/context.tsx"],"names":[],"mappings":";AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAwB,MAAM,wBAAwB,CAAC;AAEzE,2CAA2C;AAC3C,MAAM,gBAAgB,GAAG,KAAK,CAAC,aAAa,CAAmB,IAAI,CAAC,CAAC;AAErE,iCAAiC;AACjC,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,CAEzC,IAAI,CAAC,CAAC;AAER;;;GAGG;AACH,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO;IAC1C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;IACxC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;AACtD,CAAC;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,EACrC,QAAQ,EACR,MAAM,EACN,QAAQ,GACoB;IAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,IAAI,eAAe,CAAC,CAAC;IAC9D,WAAW,CAAC,OAAO,GAAG,QAAQ,IAAI,eAAe,CAAC;IAElD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,EAAE,EAAE;YACjC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,EAAE,CAAC;QAEf,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,CACL,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YACtC,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,WAAW,YACzC,QAAQ,GACgB,GACD,CAC7B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAEnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAC9C,OAAO,GAAG,EAAE,OAAO,IAAI,eAAe,CAAC;AACzC,CAAC"}

package/dist/hooks/useModal.d.ts

@@ -2,45 +2,44 @@
  * Hook for managing modal dialogs
  */
 import type { ModalOptions } from '../utils/actions.js';
+/**
+ * Options for modal.show() — modal config + event callbacks
+ */
+export interface ModalShowOptions extends ModalOptions {
+    /** Called when the user clicks the primary action */
+    onConfirm?: () => void | Promise<void>;
+    /** Called when the user clicks the secondary action or dismisses the modal */
+    onCancel?: () => void;
+}
 /**
  * Modal utility functions
  */
 export interface UseModalResult {
-    /** Open a modal dialog */
-    open: (options: ModalOptions) => void;
+    /** Show a modal dialog */
+    show: (options: ModalShowOptions) => void;
     /** Close the current modal */
-    close: () => void;
+    hide: () => void;
 }
 /**
  * Hook to manage modal dialogs
  *
  * @example
  * ```tsx
- * import { useModal } from '@qumra/app-bridge-react';
- *
- * export function MyComponent() {
- *   const modal = useModal();
- *
- *   const handleOpenSettings = () => {
- *     modal.open({
- *       title: 'Settings',
- *       url: '/settings',
- *       size: 'large',
- *       primaryAction: {
- *         content: 'Save',
- *         onAction: () => {
- *           // Handle save
- *           modal.close();
- *         }
- *       }
- *     });
- *   };
+ * const modal = useModal();
  *
- *   return <button onClick={handleOpenSettings}>Open Settings</button>;
- * }
+ * modal.show({
+ *   title: 'حذف المنتج؟',
+ *   message: 'هذا الإجراء لا يمكن التراجع عنه',
+ *   primaryAction: { label: 'حذف', variant: 'destructive' },
+ *   secondaryAction: { label: 'إلغاء' },
+ *   onConfirm: async () => {
+ *     await deleteProduct();
+ *     modal.hide();
+ *   },
+ * });
  * ```
  *
- * @returns Object with open and close methods
+ * @returns Object with show and hide methods
  */
 export declare function useModal(): UseModalResult;
 //# sourceMappingURL=useModal.d.ts.map

package/dist/hooks/useModal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useModal.d.ts","sourceRoot":"","sources":["../../src/hooks/useModal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IACtC,8BAA8B;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAezC"}
+{"version":3,"file":"useModal.d.ts","sourceRoot":"","sources":["../../src/hooks/useModal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC1C,8BAA8B;IAC9B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAyCzC"}

package/dist/hooks/useModal.js

@@ -1,48 +1,55 @@
 /**
  * Hook for managing modal dialogs
  */
-import { useCallback } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { useAppBridge } from './useAppBridge.js';
-import { openModal, closeModal } from '../utils/actions.js';
+import { ActionType, openModal, closeModal } from '../utils/actions.js';
 /**
  * Hook to manage modal dialogs
  *
  * @example
  * ```tsx
- * import { useModal } from '@qumra/app-bridge-react';
+ * const modal = useModal();
  *
- * export function MyComponent() {
- *   const modal = useModal();
- *
- *   const handleOpenSettings = () => {
- *     modal.open({
- *       title: 'Settings',
- *       url: '/settings',
- *       size: 'large',
- *       primaryAction: {
- *         content: 'Save',
- *         onAction: () => {
- *           // Handle save
- *           modal.close();
- *         }
- *       }
- *     });
- *   };
- *
- *   return <button onClick={handleOpenSettings}>Open Settings</button>;
- * }
+ * modal.show({
+ *   title: 'حذف المنتج؟',
+ *   message: 'هذا الإجراء لا يمكن التراجع عنه',
+ *   primaryAction: { label: 'حذف', variant: 'destructive' },
+ *   secondaryAction: { label: 'إلغاء' },
+ *   onConfirm: async () => {
+ *     await deleteProduct();
+ *     modal.hide();
+ *   },
+ * });
  * ```
  *
- * @returns Object with open and close methods
+ * @returns Object with show and hide methods
  */
 export function useModal() {
     const bridge = useAppBridge();
-    const open = useCallback((options) => {
-        bridge.dispatch(openModal(options));
+    const optionsRef = useRef();
+    useEffect(() => {
+        const unsubConfirm = bridge.subscribe(ActionType.MODAL_CONFIRM, () => {
+            optionsRef.current?.onConfirm?.();
+        });
+        const unsubCancel = bridge.subscribe(ActionType.MODAL_CANCEL, () => {
+            optionsRef.current?.onCancel?.();
+            optionsRef.current = undefined;
+        });
+        return () => {
+            unsubConfirm();
+            unsubCancel();
+        };
+    }, [bridge]);
+    const show = useCallback((options) => {
+        optionsRef.current = options;
+        const { onConfirm, onCancel, ...modalOptions } = options;
+        bridge.dispatch(openModal(modalOptions));
     }, [bridge]);
-    const close = useCallback(() => {
+    const hide = useCallback(() => {
+        optionsRef.current = undefined;
         bridge.dispatch(closeModal());
     }, [bridge]);
-    return { open, close };
+    return { show, hide };
 }
 //# sourceMappingURL=useModal.js.map

package/dist/hooks/useModal.js.map

@@ -1 +1 @@
-{"version":3,"file":"useModal.js","sourceRoot":"","sources":["../../src/hooks/useModal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAa5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAE9B,MAAM,IAAI,GAAG,WAAW,CACtB,CAAC,OAAqB,EAAE,EAAE;QACxB,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACtC,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}
+{"version":3,"file":"useModal.js","sourceRoot":"","sources":["../../src/hooks/useModal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAuBxE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,MAAM,EAAoB,CAAC;IAE9C,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,YAAY,GAAG,MAAM,CAAC,SAAS,CACnC,UAAU,CAAC,aAAa,EACxB,GAAG,EAAE;YACH,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC;QACpC,CAAC,CACF,CAAC;QAEF,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAClC,UAAU,CAAC,YAAY,EACvB,GAAG,EAAE;YACH,UAAU,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC;YACjC,UAAU,CAAC,OAAO,GAAG,SAAS,CAAC;QACjC,CAAC,CACF,CAAC;QAEF,OAAO,GAAG,EAAE;YACV,YAAY,EAAE,CAAC;YACf,WAAW,EAAE,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,MAAM,IAAI,GAAG,WAAW,CACtB,CAAC,OAAyB,EAAE,EAAE;QAC5B,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;QAC7B,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC;QACzD,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3C,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE;QAC5B,UAAU,CAAC,OAAO,GAAG,SAAS,CAAC;QAC/B,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/hooks/useNavigationMenu.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Hook for managing the navigation menu in the Qumra Admin host.
+ */
+import type { NavigationMenuItem } from '../utils/actions.js';
+/**
+ * Partial update for a navigation menu item (url cannot be changed)
+ */
+export type NavigationMenuItemUpdate = Partial<Omit<NavigationMenuItem, 'url'>>;
+/**
+ * Navigation menu utility functions
+ */
+export interface UseNavigationMenuResult {
+    /** Current navigation pages */
+    readonly pages: NavigationMenuItem[];
+    /** Replace all navigation pages */
+    set: (pages: NavigationMenuItem[]) => void;
+    /** Add a navigation item. If an item with the same url exists, it will be updated */
+    add: (item: NavigationMenuItem) => void;
+    /** Remove a navigation item by url */
+    remove: (url: string) => void;
+    /** Update properties of a single item by url */
+    update: (url: string, partial: NavigationMenuItemUpdate) => void;
+    /** Tell the host which page is currently active */
+    setActive: (path: string) => void;
+}
+/**
+ * Hook to manage the navigation menu shown in the Qumra Admin host.
+ *
+ * The returned object is **stable** — safe to use in useEffect dependencies
+ * without causing infinite loops.
+ *
+ * Navigation events from the host (HOST::NAVIGATION::NAVIGATE) are handled
+ * at the Provider level, so they work even when components unmount/remount.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const navigation = useNavigationMenu();
+ *
+ *   useEffect(() => {
+ *     navigation.set([
+ *       { label: 'الرئيسية', url: '/', icon: 'home' },
+ *       { label: 'الطلبات', url: '/orders', icon: 'orders', badge: 3 },
+ *     ]);
+ *   }, [navigation]); // safe — navigation is stable
+ *
+ *   // Update badge dynamically
+ *   navigation.update('/orders', { badge: 5 });
+ * }
+ * ```
+ *
+ * @returns Stable object with navigation management methods
+ */
+export declare function useNavigationMenu(): UseNavigationMenuResult;
+//# sourceMappingURL=useNavigationMenu.d.ts.map

package/dist/hooks/useNavigationMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavigationMenu.d.ts","sourceRoot":"","sources":["../../src/hooks/useNavigationMenu.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IACrC,mCAAmC;IACnC,GAAG,EAAE,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAC;IAC3C,qFAAqF;IACrF,GAAG,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACxC,sCAAsC;IACtC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,gDAAgD;IAChD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACjE,mDAAmD;IACnD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA+E3D"}

package/dist/hooks/useNavigationMenu.js

@@ -0,0 +1,81 @@
+/**
+ * Hook for managing the navigation menu in the Qumra Admin host.
+ */
+import { useCallback, useMemo, useRef } from 'react';
+import { useAppBridge } from './useAppBridge.js';
+import { ActionType } from '../utils/actions.js';
+/**
+ * Hook to manage the navigation menu shown in the Qumra Admin host.
+ *
+ * The returned object is **stable** — safe to use in useEffect dependencies
+ * without causing infinite loops.
+ *
+ * Navigation events from the host (HOST::NAVIGATION::NAVIGATE) are handled
+ * at the Provider level, so they work even when components unmount/remount.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const navigation = useNavigationMenu();
+ *
+ *   useEffect(() => {
+ *     navigation.set([
+ *       { label: 'الرئيسية', url: '/', icon: 'home' },
+ *       { label: 'الطلبات', url: '/orders', icon: 'orders', badge: 3 },
+ *     ]);
+ *   }, [navigation]); // safe — navigation is stable
+ *
+ *   // Update badge dynamically
+ *   navigation.update('/orders', { badge: 5 });
+ * }
+ * ```
+ *
+ * @returns Stable object with navigation management methods
+ */
+export function useNavigationMenu() {
+    const bridge = useAppBridge();
+    const pagesRef = useRef([]);
+    // Dispatch the full pages list to the host and update the ref
+    const dispatchPages = useCallback((nextPages) => {
+        pagesRef.current = nextPages;
+        bridge.dispatch({
+            type: ActionType.NAVIGATION_UPDATE,
+            payload: { pages: nextPages },
+        });
+    }, [bridge]);
+    const set = useCallback((nextPages) => {
+        dispatchPages(nextPages);
+    }, [dispatchPages]);
+    const add = useCallback((item) => {
+        const current = pagesRef.current;
+        const index = current.findIndex((i) => i.url === item.url);
+        const nextPages = index >= 0
+            ? current.map((i) => (i.url === item.url ? { ...i, ...item } : i))
+            : [...current, item];
+        dispatchPages(nextPages);
+    }, [dispatchPages]);
+    const remove = useCallback((url) => {
+        dispatchPages(pagesRef.current.filter((i) => i.url !== url));
+    }, [dispatchPages]);
+    const update = useCallback((url, partial) => {
+        dispatchPages(pagesRef.current.map((i) => i.url === url ? { ...i, ...partial } : i));
+    }, [dispatchPages]);
+    const setActive = useCallback((path) => {
+        bridge.dispatch({
+            type: ActionType.NAVIGATION_SET_ACTIVE,
+            payload: { path },
+        });
+    }, [bridge]);
+    // Stable object — all deps are stable (bridge never changes)
+    return useMemo(() => ({
+        get pages() {
+            return pagesRef.current;
+        },
+        set,
+        add,
+        remove,
+        update,
+        setActive,
+    }), [set, add, remove, update, setActive]);
+}
+//# sourceMappingURL=useNavigationMenu.js.map

package/dist/hooks/useNavigationMenu.js.map

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

package/dist/hooks/useSaveBar.d.ts

@@ -1,13 +1,37 @@
 /**
  * Hook for managing the save bar (unsaved changes indicator)
  */
-import type { SaveBarOptions } from '../utils/actions.js';
+/**
+ * Helpers passed to onSave for manual control over save result
+ */
+export interface SaveBarHelpers {
+    /** Signal that the save completed successfully */
+    complete: () => void;
+    /** Signal that the save failed */
+    error: (message?: string) => void;
+}
+/**
+ * Options passed to saveBar.show()
+ */
+export interface SaveBarShowOptions {
+    /**
+     * Callback when the save button is clicked.
+     *
+     * Receives `{ complete, error }` helpers for manual control.
+     * - If you call `complete()` or `error()`, you control the result.
+     * - If you don't call either, the hook auto-dispatches based on the promise:
+     *   resolves → SAVE_COMPLETE, throws → SAVE_ERROR.
+     */
+    onSave?: (helpers: SaveBarHelpers) => void | Promise<void>;
+    /** Callback when the discard button is clicked */
+    onDiscard?: () => void;
+}
 /**
  * Save bar utility functions
  */
 export interface UseSaveBarResult {
     /** Show the save bar */
-    show: (options?: SaveBarOptions) => void;
+    show: (options?: SaveBarShowOptions) => void;
     /** Hide the save bar */
     hide: () => void;
 }
@@ -15,31 +39,31 @@ export interface UseSaveBarResult {
  * Hook to manage the save bar for indicating unsaved changes
  *
  * @example
+ * Simple (auto mode):
  * ```tsx
- * import { useSaveBar } from '@qumra/app-bridge-react';
- *
- * export function MyComponent() {
- *   const saveBar = useSaveBar();
- *   const [hasChanges, setHasChanges] = React.useState(false);
- *
- *   const handleChange = () => {
- *     setHasChanges(true);
- *     saveBar.show();
- *   };
- *
- *   const handleSave = async () => {
+ * saveBar.show({
+ *   onSave: async () => {
  *     await saveData();
- *     setHasChanges(false);
- *     saveBar.hide();
- *   };
+ *     // resolves → SAVE_COMPLETE, throws → SAVE_ERROR
+ *   },
+ *   onDiscard: () => resetForm(),
+ * });
+ * ```
  *
- *   return (
- *     <>
- *       <input onChange={handleChange} />
- *       <button onClick={handleSave}>Save</button>
- *     </>
- *   );
- * }
+ * @example
+ * Dynamic (manual control):
+ * ```tsx
+ * saveBar.show({
+ *   onSave: async ({ complete, error }) => {
+ *     const res = await fetch('/api/save', { method: 'POST' });
+ *     if (res.ok) {
+ *       complete();
+ *     } else {
+ *       error('فشل الحفظ');
+ *     }
+ *   },
+ *   onDiscard: () => resetForm(),
+ * });
  * ```
  *
  * @returns Object with show and hide methods

package/dist/hooks/useSaveBar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSaveBar.d.ts","sourceRoot":"","sources":["../../src/hooks/useSaveBar.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,wBAAwB;IACxB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CAe7C"}
+{"version":3,"file":"useSaveBar.d.ts","sourceRoot":"","sources":["../../src/hooks/useSaveBar.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,kCAAkC;IAClC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC7C,wBAAwB;IACxB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CAqE7C"}