@burdenoff/fe-libs 2026.528.10 → 2026.529.1

package/dist/shared/hooks/usePWA.d.ts

@@ -0,0 +1,57 @@
+interface PWAState {
+    /** Whether the app can be installed */
+    canInstall: boolean;
+    /** Whether the app is already installed */
+    isInstalled: boolean;
+    /** Whether the app is running in standalone mode (installed PWA) */
+    isStandalone: boolean;
+    /** Whether the service worker is registered */
+    isServiceWorkerReady: boolean;
+    /** Whether there's a new version available */
+    hasUpdate: boolean;
+}
+interface UsePWAReturn extends PWAState {
+    /** Trigger the install prompt */
+    install: () => Promise<boolean>;
+    /** Update the service worker */
+    update: () => void;
+    /** Dismiss the install prompt */
+    dismissInstall: () => void;
+}
+interface UsePWAOptions {
+    /**
+     * Auto-activate a waiting service worker and reload the page so users
+     * always run the latest deployed code. Defaults to true.
+     */
+    autoUpdate?: boolean;
+    /**
+     * How often (ms) to poll the SW registration for an updated worker.
+     * Defaults to 60_000 (1 minute). Set to 0 to disable polling.
+     */
+    updateCheckIntervalMs?: number;
+}
+/**
+ * usePWA Hook
+ *
+ * Manages PWA installation state and service worker updates.
+ *
+ * @example
+ * ```tsx
+ * function InstallBanner() {
+ *   const { canInstall, isInstalled, install, dismissInstall } = usePWA();
+ *
+ *   if (!canInstall || isInstalled) return null;
+ *
+ *   return (
+ *     <div className="install-banner">
+ *       <p>Install for a better experience!</p>
+ *       <button onClick={install}>Install</button>
+ *       <button onClick={dismissInstall}>Not now</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePWA(options?: UsePWAOptions): UsePWAReturn;
+export {};
+//# sourceMappingURL=usePWA.d.ts.map

package/dist/shared/hooks/usePWA.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePWA.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/usePWA.ts"],"names":[],"mappings":"AAWA,UAAU,QAAQ;IAChB,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,WAAW,EAAE,OAAO,CAAC;IACrB,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,YAAa,SAAQ,QAAQ;IACrC,iCAAiC;IACjC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,gCAAgC;IAChC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,iCAAiC;IACjC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,UAAU,aAAa;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,YAAY,CAqLhE"}

package/dist/shared/hooks/usePrevious.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Tracks the previous value of a state or prop.
+ * Returns undefined on the first render, then returns the previous value on subsequent renders.
+ *
+ * @template T - The type of the value being tracked
+ * @param value - The current value to track
+ * @returns The previous value, or undefined on first render
+ *
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const [count, setCount] = useState(0);
+ *   const prevCount = usePrevious(count);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current count: {count}</p>
+ *       <p>Previous count: {prevCount ?? 'N/A'}</p>
+ *       <button onClick={() => setCount(count + 1)}>Increment</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function SearchResults({ query }: { query: string }) {
+ *   const prevQuery = usePrevious(query);
+ *   const [results, setResults] = useState([]);
+ *
+ *   useEffect(() => {
+ *     if (query !== prevQuery) {
+ *       console.log(`Query changed from "${prevQuery}" to "${query}"`);
+ *       fetchResults(query).then(setResults);
+ *     }
+ *   }, [query, prevQuery]);
+ *
+ *   return <ResultsList results={results} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Animation({ isVisible }: { isVisible: boolean }) {
+ *   const wasVisible = usePrevious(isVisible);
+ *
+ *   const animationClass = useMemo(() => {
+ *     if (isVisible && !wasVisible) return 'fade-in';
+ *     if (!isVisible && wasVisible) return 'fade-out';
+ *     return '';
+ *   }, [isVisible, wasVisible]);
+ *
+ *   return <div className={animationClass}>Content</div>;
+ * }
+ * ```
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * Tracks the previous value with a custom comparison function.
+ * Only updates the previous value when the comparison function returns false.
+ *
+ * @template T - The type of the value being tracked
+ * @param value - The current value to track
+ * @param compare - Function that returns true if values should be considered equal
+ * @returns The previous distinct value
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ user }: { user: User }) {
+ *   // Only update previous user when the ID changes
+ *   const prevUser = usePreviousDistinct(
+ *     user,
+ *     (prev, next) => prev?.id === next?.id
+ *   );
+ *
+ *   useEffect(() => {
+ *     if (prevUser && prevUser.id !== user.id) {
+ *       console.log(`User changed from ${prevUser.name} to ${user.name}`);
+ *     }
+ *   }, [user, prevUser]);
+ *
+ *   return <div>{user.name}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ArrayComponent({ items }: { items: string[] }) {
+ *   // Only track when array length changes
+ *   const prevItems = usePreviousDistinct(
+ *     items,
+ *     (prev, next) => prev?.length === next?.length
+ *   );
+ *
+ *   if (prevItems && prevItems.length !== items.length) {
+ *     console.log(`Array length changed from ${prevItems.length} to ${items.length}`);
+ *   }
+ *
+ *   return <ul>{items.map(item => <li key={item}>{item}</li>)}</ul>;
+ * }
+ * ```
+ */
+export declare function usePreviousDistinct<T>(value: T, compare: (prev: T | undefined, next: T) => boolean): T | undefined;
+/**
+ * Tracks multiple previous values in a history array.
+ * Useful for implementing undo/redo or tracking value changes over time.
+ *
+ * @template T - The type of the value being tracked
+ * @param value - The current value to track
+ * @param maxHistory - Maximum number of previous values to keep (default: 10)
+ * @returns Array of previous values, most recent first
+ *
+ * @example
+ * ```tsx
+ * function DrawingCanvas() {
+ *   const [drawing, setDrawing] = useState<Point[]>([]);
+ *   const history = usePreviousHistory(drawing, 20);
+ *
+ *   const undo = () => {
+ *     if (history.length > 0) {
+ *       setDrawing(history[0]);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <Canvas points={drawing} />
+ *       <button onClick={undo} disabled={history.length === 0}>
+ *         Undo ({history.length})
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function TextEditor() {
+ *   const [text, setText] = useState('');
+ *   const history = usePreviousHistory(text, 50);
+ *
+ *   const showHistory = () => {
+ *     console.log('Recent changes:', history);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <textarea value={text} onChange={(e) => setText(e.target.value)} />
+ *       <button onClick={showHistory}>Show History</button>
+ *       <p>History size: {history.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePreviousHistory<T>(value: T, maxHistory?: number): T[];
+//# sourceMappingURL=usePrevious.d.ts.map

package/dist/shared/hooks/usePrevious.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePrevious.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/usePrevious.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,GACjD,CAAC,GAAG,SAAS,CAWf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,GAAE,MAAW,GAAG,CAAC,EAAE,CAU5E"}

package/dist/shared/hooks/useQuotaErrorToast.d.ts

@@ -0,0 +1,50 @@
+import { QuotaExhaustedExtensions } from '../utils/quotaErrors';
+/**
+ * Global error event the host shell can dispatch when any GraphQL response
+ * carries a QUOTA_EXHAUSTED error. The hook listens for it and surfaces a
+ * toast through the shell's GlobalUiProvider — this avoids every MFE having
+ * to wire its own error link/handler for a global concern.
+ */
+export declare const QUOTA_EXHAUSTED_EVENT = "burdenoff:quota-exhausted";
+export interface QuotaExhaustedEventDetail {
+    /** The raw error object surfaced by Apollo (or any GraphQL client). */
+    error?: unknown;
+    /** Pre-extracted extensions, if the dispatcher already parsed the error. */
+    extensions?: QuotaExhaustedExtensions;
+}
+export interface UseQuotaErrorToastOptions {
+    /** Toast cooldown in ms — suppresses duplicate toasts inside this window. */
+    cooldownMs?: number;
+    /** Override the default toast message builder. */
+    buildMessage?: (ext: QuotaExhaustedExtensions | null) => string;
+}
+/**
+ * `useQuotaErrorToast` — install a global listener that surfaces a toast
+ * whenever a `QUOTA_EXHAUSTED` GraphQL error is observed anywhere in the app.
+ *
+ * Mount once per shell (e.g. inside the AppShellProvider). Returns a manual
+ * `report(error)` callback that MFEs can call directly when their mutation
+ * fails so the toast shows immediately without waiting for the global event.
+ *
+ * @example
+ * ```tsx
+ * function AppShell() {
+ *   useQuotaErrorToast();
+ *   return <Routes>{/* ... *\/}</Routes>;
+ * }
+ *
+ * // From a mutation handler
+ * const { report } = useQuotaErrorToast();
+ * try { await mutate(); } catch (e) { if (!report(e)) throw e; }
+ * ```
+ */
+export declare function useQuotaErrorToast(options?: UseQuotaErrorToastOptions): {
+    report: (err: unknown) => boolean;
+};
+/**
+ * Dispatch the global `QUOTA_EXHAUSTED` event. Call from an Apollo error link
+ * (or any GraphQL client error handler) so a host shell that mounts
+ * `useQuotaErrorToast` will surface a toast.
+ */
+export declare function dispatchQuotaExhausted(detail: QuotaExhaustedEventDetail): void;
+//# sourceMappingURL=useQuotaErrorToast.d.ts.map

package/dist/shared/hooks/useQuotaErrorToast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuotaErrorToast.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useQuotaErrorToast.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAEjE,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,wBAAwB,CAAC;CACvC;AAED,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,KAAK,MAAM,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG;IAC3E,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACnC,CAsCA;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAO9E"}

package/dist/shared/hooks/useRecordProductVisit.d.ts

@@ -0,0 +1,11 @@
+interface RecordProductVisitOptions {
+    /** Override the app-shell-provided product slug if needed. */
+    productSlug?: string;
+    /** Override the CTA URL the welcome email uses. Defaults to the current origin. */
+    appUrl?: string;
+    /** Set false to disable the side effect entirely (e.g. during E2E tests). */
+    enabled?: boolean;
+}
+export declare function useRecordProductVisit(options?: RecordProductVisitOptions): void;
+export {};
+//# sourceMappingURL=useRecordProductVisit.d.ts.map

package/dist/shared/hooks/useRecordProductVisit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRecordProductVisit.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useRecordProductVisit.ts"],"names":[],"mappings":"AAmDA,UAAU,yBAAyB;IACjC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAkCD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,yBAA8B,GAAG,IAAI,CAmEnF"}

package/dist/shared/hooks/useReferralAttribution.d.ts

@@ -0,0 +1,2 @@
+export declare function useReferralAttribution(): void;
+//# sourceMappingURL=useReferralAttribution.d.ts.map

package/dist/shared/hooks/useReferralAttribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReferralAttribution.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useReferralAttribution.ts"],"names":[],"mappings":"AAkDA,wBAAgB,sBAAsB,IAAI,IAAI,CA6I7C"}

package/dist/shared/hooks/useSessionStorage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Synchronizes state with sessionStorage, providing persistent storage for the current session.
+ * Data persists only for the duration of the page session (until the tab is closed).
+ * Automatically serializes/deserializes JSON values.
+ *
+ * @template T - The type of the stored value
+ * @param key - The sessionStorage key
+ * @param initialValue - The initial value if no stored value exists
+ * @returns A tuple containing [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * function WizardForm() {
+ *   const [formData, setFormData, clearFormData] = useSessionStorage('wizardForm', {
+ *     step: 1,
+ *     data: {}
+ *   });
+ *
+ *   const nextStep = () => {
+ *     setFormData(prev => ({ ...prev, step: prev.step + 1 }));
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Step {formData.step}</p>
+ *       <button onClick={nextStep}>Next</button>
+ *       <button onClick={clearFormData}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function TemporaryFilter() {
+ *   const [filter, setFilter] = useSessionStorage('searchFilter', '');
+ *
+ *   // Filter persists across page refreshes but not after closing the tab
+ *   return <input value={filter} onChange={(e) => setFilter(e.target.value)} />;
+ * }
+ * ```
+ */
+export declare function useSessionStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void, () => void];
+//# sourceMappingURL=useSessionStorage.d.ts.map

package/dist/shared/hooks/useSessionStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionStorage.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useSessionStorage.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC,CA0DxD"}

package/dist/shared/hooks/useThrottle.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Throttles a function call, ensuring it's only called once within the specified delay period.
+ * Useful for rate-limiting event handlers like scroll, resize, or mousemove.
+ *
+ * @template T - The function type to be throttled
+ * @param callback - The function to throttle
+ * @param delay - The minimum time in milliseconds between function calls (default: 300ms)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```tsx
+ * function ScrollComponent() {
+ *   const handleScroll = useThrottle(() => {
+ *     console.log('Scrolled');
+ *   }, 100);
+ *
+ *   return <div onScroll={handleScroll}>Content</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ResizeObserver() {
+ *   const handleResize = useThrottle((width: number, height: number) => {
+ *     console.log('Window resized:', width, height);
+ *   }, 200);
+ *
+ *   useEffect(() => {
+ *     const listener = () => handleResize(window.innerWidth, window.innerHeight);
+ *     window.addEventListener('resize', listener);
+ *     return () => window.removeEventListener('resize', listener);
+ *   }, [handleResize]);
+ * }
+ * ```
+ */
+export declare function useThrottle<TArgs extends unknown[]>(callback: (...args: TArgs) => void, delay?: number): (...args: TArgs) => void;
+//# sourceMappingURL=useThrottle.d.ts.map

package/dist/shared/hooks/useThrottle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottle.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useThrottle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,OAAO,EAAE,EACjD,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,EAClC,KAAK,GAAE,MAAY,GAClB,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,CAe1B"}

package/dist/shared/hooks/useToggle.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Manages a boolean state with convenient toggle and set functions.
+ * Simplifies the common pattern of toggling boolean values.
+ *
+ * @param initialValue - The initial boolean value (default: false)
+ * @returns A tuple containing [value, toggle, setValue]
+ *
+ * @example
+ * ```tsx
+ * function Modal() {
+ *   const [isOpen, toggle, setIsOpen] = useToggle(false);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={toggle}>Toggle Modal</button>
+ *       <button onClick={() => setIsOpen(true)}>Open Modal</button>
+ *       <button onClick={() => setIsOpen(false)}>Close Modal</button>
+ *       {isOpen && <ModalContent onClose={() => setIsOpen(false)} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Accordion({ title, children }: AccordionProps) {
+ *   const [isExpanded, toggleExpanded] = useToggle(false);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={toggleExpanded}>
+ *         {title} {isExpanded ? '▼' : '▶'}
+ *       </button>
+ *       {isExpanded && <div>{children}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function PasswordInput() {
+ *   const [showPassword, toggleShowPassword, setShowPassword] = useToggle(false);
+ *   const [password, setPassword] = useState('');
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type={showPassword ? 'text' : 'password'}
+ *         value={password}
+ *         onChange={(e) => setPassword(e.target.value)}
+ *       />
+ *       <button onClick={toggleShowPassword}>
+ *         {showPassword ? 'Hide' : 'Show'}
+ *       </button>
+ *       <button onClick={() => setShowPassword(false)}>Always Hide</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useToggle(initialValue?: boolean): [boolean, () => void, (value: boolean) => void];
+/**
+ * Alternative version with more descriptive return object instead of tuple.
+ * Useful when you prefer named properties over array destructuring.
+ *
+ * @param initialValue - The initial boolean value (default: false)
+ * @returns Object with value, toggle, setTrue, setFalse, and setValue functions
+ *
+ * @example
+ * ```tsx
+ * function Sidebar() {
+ *   const sidebar = useToggleObject(true);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={sidebar.toggle}>Toggle Sidebar</button>
+ *       <button onClick={sidebar.setTrue}>Open Sidebar</button>
+ *       <button onClick={sidebar.setFalse}>Close Sidebar</button>
+ *       {sidebar.value && <SidebarContent />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function LoadingButton() {
+ *   const loading = useToggleObject(false);
+ *
+ *   const handleClick = async () => {
+ *     loading.setTrue();
+ *     try {
+ *       await performAction();
+ *     } finally {
+ *       loading.setFalse();
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleClick} disabled={loading.value}>
+ *       {loading.value ? 'Loading...' : 'Click Me'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useToggleObject(initialValue?: boolean): {
+    value: boolean;
+    toggle: () => void;
+    setTrue: () => void;
+    setFalse: () => void;
+    setValue: (value: boolean) => void;
+};
+/**
+ * Advanced version with conditional toggle based on a predicate function.
+ * Only toggles if the predicate returns true.
+ *
+ * @param initialValue - The initial boolean value
+ * @param predicate - Function that determines if toggle should occur
+ * @returns Tuple with [value, conditionalToggle, setValue]
+ *
+ * @example
+ * ```tsx
+ * function ConditionalFeature() {
+ *   const [hasPermission, setHasPermission] = useState(true);
+ *   const [isEnabled, toggle, setEnabled] = useConditionalToggle(
+ *     false,
+ *     () => hasPermission
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       <label>
+ *         <input
+ *           type="checkbox"
+ *           checked={hasPermission}
+ *           onChange={(e) => setHasPermission(e.target.checked)}
+ *         />
+ *         Has Permission
+ *       </label>
+ *       <button onClick={toggle}>
+ *         Toggle Feature (only works with permission)
+ *       </button>
+ *       <p>Feature is {isEnabled ? 'enabled' : 'disabled'}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useConditionalToggle(initialValue: boolean | undefined, predicate: () => boolean): [boolean, () => void, (value: boolean) => void];
+//# sourceMappingURL=useToggle.d.ts.map

package/dist/shared/hooks/useToggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToggle.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useToggle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,SAAS,CACvB,YAAY,GAAE,OAAe,GAC5B,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,CAcjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,eAAe,CAAC,YAAY,GAAE,OAAe,GAAG;IAC9D,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAaA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,OAAO,YAAQ,EAC7B,SAAS,EAAE,MAAM,OAAO,GACvB,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,CAcjD"}

package/dist/shared/hooks/useUpgradePrompt.d.ts

@@ -0,0 +1,50 @@
+import { UpgradePromptDetail } from '../components/UpgradePromptModal';
+import { STORAGE_QUOTA_EXCEEDED_CODE, RESOURCE_CAP_EXCEEDED_CODE, QUOTA_EXHAUSTED_CODE } from '../utils/quotaErrors';
+export interface PlanUsageEntry {
+    resource: string;
+    current: number;
+    limit: number | null;
+    unit?: 'bytes' | 'count';
+}
+export interface PlanUsageSnapshot {
+    planName: string;
+    isFree: boolean;
+    usage: PlanUsageEntry[];
+}
+/**
+ * Window event consumers can dispatch to share the latest plan/usage snapshot
+ * (e.g. from the host shell's session query) without forcing every consumer
+ * to wire its own GraphQL query.
+ */
+export declare const PLAN_USAGE_SNAPSHOT_EVENT = "burdenoff:plan-usage-snapshot";
+export declare function publishPlanUsageSnapshot(snapshot: PlanUsageSnapshot): void;
+export interface UseUpgradePromptOptions {
+    /** Threshold for `nearLimit`/`isApproaching` flags. Defaults to 0.8. */
+    warnAtPercent?: number;
+    /** Filter to a single resource (e.g. "storage"). */
+    resource?: string;
+}
+export interface UseUpgradePromptResult {
+    plan: PlanUsageSnapshot | null;
+    isFree: boolean;
+    /** True when ANY tracked resource is at or above `warnAtPercent`. */
+    isApproachingAnyLimit: boolean;
+    /** Resource entries currently at/over `warnAtPercent`. */
+    approachingLimits: PlanUsageEntry[];
+    /** Surface the upgrade modal manually. */
+    promptUpgrade: (detail?: Partial<UpgradePromptDetail>) => void;
+    /** Inspect a thrown error; if it's an upgrade error, prompt + return true. */
+    reportError: (err: unknown) => boolean;
+}
+/**
+ * `useUpgradePrompt` — listens to plan/usage snapshots published via
+ * `publishPlanUsageSnapshot` (set up once in the shell from the user/session
+ * query) and exposes the helpers MFEs need for cap-triggered + key-event CTAs.
+ *
+ * - `isApproachingAnyLimit` flips true at 80% of any cap by default
+ * - `promptUpgrade(detail?)` opens the global modal
+ * - `reportError(err)` opens the modal when err matches an upgrade code
+ */
+export declare function useUpgradePrompt(options?: UseUpgradePromptOptions): UseUpgradePromptResult;
+export { STORAGE_QUOTA_EXCEEDED_CODE, RESOURCE_CAP_EXCEEDED_CODE, QUOTA_EXHAUSTED_CODE };
+//# sourceMappingURL=useUpgradePrompt.d.ts.map

package/dist/shared/hooks/useUpgradePrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUpgradePrompt.d.ts","sourceRoot":"","sources":["../../../src/shared/hooks/useUpgradePrompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACnG,OAAO,EAGL,2BAA2B,EAC3B,0BAA0B,EAC1B,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,kCAAkC,CAAC;AAEzE,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAU1E;AAaD,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,0DAA0D;IAC1D,iBAAiB,EAAE,cAAc,EAAE,CAAC;IACpC,0CAA0C;IAC1C,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,KAAK,IAAI,CAAC;IAC/D,8EAA8E;IAC9E,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CAqD9F;AAGD,OAAO,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/shared/index.d.ts

@@ -0,0 +1,14 @@
+export * from './components';
+export * from './config';
+export * from './events';
+export * from './graphql';
+export * from './hooks';
+export * from './providers';
+export * from './tours';
+export * from './types';
+export * from './utils';
+export * from './feature-flags';
+export * from './native';
+export * from './actors';
+export declare const FE_SHARED_VERSION = "1.0.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAQA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AAEzB,eAAO,MAAM,iBAAiB,UAAU,CAAC"}