@buoy-gg/shared-ui 2.1.2 → 2.1.4-beta.3

package/lib/module/clipboard/clipboard-impl.js

@@ -1,20 +1,95 @@
 "use strict";
 
 /**
- * Auto-generated clipboard implementation
- * Detected: none
- * Generated at: 2026-01-29T01:02:34.738Z
+ * Runtime clipboard implementation
  *
- * DO NOT EDIT - This file is generated by scripts/detect-clipboard.js
+ * Uses Metro's allowOptionalDependencies with top-level try-catch
+ * so Metro marks these requires as optional (skipped if not installed).
  *
- * No clipboard library found. Install one of:
- * - expo-clipboard (for Expo projects)
- * - @react-native-clipboard/clipboard (for RN CLI projects)
+ * We grab module references eagerly (for Metro), but detect which one
+ * actually works lazily on first use — by trying to call it. This avoids
+ * NativeModules checks which don't work with TurboModules/new architecture.
+ *
+ * Consumers must set `transformer.allowOptionalDependencies = true`
+ * in their metro.config.js for this to work.
+ *
+ * Fallback chain:
+ * 1. expo-clipboard
+ * 2. @react-native-clipboard/clipboard
+ * 3. Graceful failure
  */
 
-export const clipboardType = null;
-export const isClipboardAvailable = () => false;
+// Grab module references at load time (top-level try-catch for Metro)
+// Always require both — we decide which actually works at call time
+let _expoClipboard = null;
+try {
+  _expoClipboard = require("expo-clipboard");
+} catch {}
+let _rnClipboard = null;
+try {
+  const mod = require("@react-native-clipboard/clipboard");
+  _rnClipboard = mod.default || mod;
+} catch {}
+
+// Lazy detection: resolved on first clipboardFunction() call
+let _detectedType = null;
+let _clipboardFn = null;
+let _detected = false;
+async function detect(text) {
+  // 1. Try expo-clipboard by actually calling it
+  if (_expoClipboard && typeof _expoClipboard.setStringAsync === "function") {
+    try {
+      await _expoClipboard.setStringAsync(text);
+      _detectedType = "expo";
+      _clipboardFn = async t => {
+        await _expoClipboard.setStringAsync(t);
+        return true;
+      };
+      _detected = true;
+      return true;
+    } catch {}
+  }
+
+  // 2. Try @react-native-clipboard/clipboard
+  if (_rnClipboard && typeof _rnClipboard.setString === "function") {
+    try {
+      _rnClipboard.setString(text);
+      _detectedType = "react-native";
+      _clipboardFn = async t => {
+        _rnClipboard.setString(t);
+        return true;
+      };
+      _detected = true;
+      return true;
+    } catch {}
+  }
+  _detected = true;
+  return false;
+}
+export const clipboardType = () => {
+  return _detectedType;
+};
+export const isClipboardAvailable = () => {
+  // Before first use, optimistically return true if we have a module ref
+  if (!_detected) return _expoClipboard != null || _rnClipboard != null;
+  return _clipboardFn != null;
+};
 export const clipboardFunction = async text => {
-  console.error("[RnBetterDevTools] Copy failed: No clipboard library found.\n" + `Attempted to copy: ${text.substring(0, 50)}${text.length > 50 ? "..." : ""}\n` + "Install expo-clipboard or @react-native-clipboard/clipboard, or provide a custom onCopy function.");
+  // If already detected, use the cached function
+  if (_detected && _clipboardFn) {
+    try {
+      return await _clipboardFn(text);
+    } catch (error) {
+      console.error("[buoy] Clipboard copy failed:", error);
+      return false;
+    }
+  }
+
+  // First call: detect which clipboard works by actually trying it
+  if (!_detected) {
+    const result = await detect(text);
+    if (result) return true;
+  }
+  console.warn("[buoy] No clipboard library available. Install expo-clipboard or @react-native-clipboard/clipboard.");
   return false;
 };

package/lib/module/hooks/safe-area-impl.js

@@ -3,7 +3,7 @@
 /**
  * Auto-generated safe area implementation
  * Detected: none
- * Generated at: 2026-01-29T01:02:34.764Z
+ * Generated at: 2026-02-10T20:29:38.101Z
  *
  * DO NOT EDIT - This file is generated by scripts/detect-safe-area.js
  *

package/lib/module/index.js

@@ -3,6 +3,9 @@
 // UI exports
 export * from "./ui/index.js";
 
+// Store base classes
+export * from "./stores/index.js";
+
 // Utils exports - selectively export to avoid conflicts
 export {
 // Display utilities
@@ -18,7 +21,13 @@ getValueType, isPrimitive, isJsonSerializable, isValidJson, getConstructorName,
 // Value formatting utilities
 parseValue, formatValue, getTypeColor, truncateText, flattenObject, formatPath,
 // Optional module loading utilities
-loadOptionalModule, getCachedOptionalModule } from "./utils/index.js";
+loadOptionalModule, getCachedOptionalModule,
+// Subscribable base class for self-managing listeners
+Subscribable,
+// Subscriber count notifier for cross-package notifications
+subscriberCountNotifier, subscribeToSubscriberCountChanges, notifySubscriberCountChange,
+// Safe expo-router wrappers (falls back to no-ops on RN CLI)
+useSafeRouter, useSafePathname, useSafeSegments, useSafeGlobalSearchParams, getSafeRouter, isExpoRouterAvailable } from "./utils/index.js";
 
 // Also export formatting utils
 export * from "./utils/formatting/index.js";

package/lib/module/storage/devToolsStorageKeys.js

@@ -164,6 +164,8 @@ export const devToolsStorageKeys = {
     modal: () => `${devToolsStorageKeys.events.root()}_modal`,
     /** Selected badge/source filters */
     enabledSources: () => `${devToolsStorageKeys.events.root()}_enabled_sources`,
+    /** Whether event capturing is active */
+    isCapturing: () => `${devToolsStorageKeys.events.root()}_is_capturing`,
     /** Copy/export settings */
     copySettings: () => `${devToolsStorageKeys.events.root()}_copy_settings`
   }
@@ -188,11 +190,16 @@ const LEGACY_DEV_TOOL_PATTERNS = ["@devtools", "@dev_tools_", "@modal_state_",
 export function isDevToolsStorageKey(key) {
   if (!key) return false;
 
-  // Check if it starts with our base prefix
+  // Check if it starts with our base prefix (@react_buoy)
   if (key.startsWith(devToolsStorageKeys.base)) {
     return true;
   }
 
+  // Check for buoy- prefixed keys (modal persistence, license, etc.)
+  if (key.startsWith("buoy-")) {
+    return true;
+  }
+
   // Check for legacy dev tool keys that need cleanup
   for (const pattern of LEGACY_DEV_TOOL_PATTERNS) {
     if (key.startsWith(pattern)) {

package/lib/module/stores/BaseEventStore.js

@@ -0,0 +1,253 @@
+"use strict";
+
+/**
+ * BaseEventStore - Abstract base class for event aggregation stores
+ *
+ * Handles dual subscription patterns (array listeners + individual event callbacks)
+ * and automatically manages start/stop lifecycle based on subscriber count.
+ *
+ * Follows TanStack Query's Subscribable pattern with extensions for:
+ * - Array subscriptions (get full event list on each update)
+ * - Individual event subscriptions (get each event as it occurs)
+ * - Auto-start capturing when first subscriber joins
+ * - Auto-stop capturing when last subscriber leaves
+ * - Subscriber count notifications for debugging UI
+ *
+ * @example
+ * ```typescript
+ * class StorageEventStore extends BaseEventStore<StorageEvent> {
+ *   protected storeName = 'storage';
+ *
+ *   protected startCapturing(): void {
+ *     // Start listening to storage changes
+ *   }
+ *
+ *   protected stopCapturing(): void {
+ *     // Stop listening to storage changes
+ *   }
+ *
+ *   isCapturing(): boolean {
+ *     return this.unsubscribe !== null;
+ *   }
+ * }
+ * ```
+ */
+
+import { Subscribable } from "../utils/subscribable.js";
+import { notifySubscriberCountChange } from "../utils/subscriberCountNotifier.js";
+
+/**
+ * Callback type for receiving full events array
+ */
+
+/**
+ * Callback type for receiving individual events
+ */
+
+/**
+ * Configuration options for BaseEventStore
+ */
+
+/**
+ * Abstract base class for event stores.
+ *
+ * Subclasses must implement:
+ * - `startCapturing()` - Begin listening to the underlying event source
+ * - `stopCapturing()` - Stop listening to the underlying event source
+ * - `isCapturing()` - Check if currently capturing events
+ */
+export class BaseEventStore extends Subscribable {
+  events = [];
+  arrayListeners = new Set();
+  constructor(options) {
+    super();
+    this.maxEvents = options.maxEvents ?? 500;
+    this.storeName = options.storeName;
+  }
+
+  // ===========================================================================
+  // ABSTRACT METHODS - Must be implemented by subclasses
+  // ===========================================================================
+
+  /**
+   * Start capturing events from the underlying source.
+   * Called automatically when first subscriber joins.
+   */
+
+  /**
+   * Stop capturing events from the underlying source.
+   * Called automatically when last subscriber leaves.
+   */
+
+  /**
+   * Check if the store is actively capturing events.
+   */
+
+  // ===========================================================================
+  // LIFECYCLE HOOKS - Called by Subscribable base class
+  // ===========================================================================
+
+  /**
+   * Called when first subscriber joins (via onEvent).
+   * Starts capturing if no one was subscribed.
+   */
+  onSubscribe() {
+    if (this.getTotalSubscriberCount() === 1) {
+      this.startCapturing();
+    }
+    notifySubscriberCountChange(this.storeName);
+  }
+
+  /**
+   * Called when a subscriber leaves (via onEvent unsubscribe).
+   * Stops capturing if no one is subscribed anymore.
+   */
+  onUnsubscribe() {
+    if (this.getTotalSubscriberCount() === 0) {
+      this.stopCapturing();
+    }
+    notifySubscriberCountChange(this.storeName);
+  }
+
+  // ===========================================================================
+  // SUBSCRIPTION METHODS
+  // ===========================================================================
+
+  /**
+   * Get total count of all subscribers (both individual and array listeners)
+   */
+  getTotalSubscriberCount() {
+    return this.listeners.size + this.arrayListeners.size;
+  }
+
+  /**
+   * Subscribe to the full events array.
+   * Automatically starts capturing when first subscriber joins.
+   *
+   * @param listener - Callback that receives the full events array on each update
+   * @returns Unsubscribe function
+   */
+  subscribeToEvents(listener) {
+    const wasEmpty = this.getTotalSubscriberCount() === 0;
+    this.arrayListeners.add(listener);
+
+    // Start capturing if this is the first subscriber
+    if (wasEmpty) {
+      this.startCapturing();
+    }
+
+    // Notify subscriber count change
+    notifySubscriberCountChange(this.storeName);
+
+    // Immediately call with current events
+    listener(this.getEvents());
+
+    // Return unsubscribe function
+    return () => {
+      this.arrayListeners.delete(listener);
+
+      // Stop capturing if no one is subscribed anymore
+      if (this.getTotalSubscriberCount() === 0) {
+        this.stopCapturing();
+      }
+
+      // Notify subscriber count change
+      notifySubscriberCountChange(this.storeName);
+    };
+  }
+
+  /**
+   * Subscribe to individual events as they occur.
+   * Automatically starts capturing when first subscriber joins.
+   *
+   * @param callback - Callback that receives each event as it occurs
+   * @returns Unsubscribe function
+   */
+  onEvent(callback) {
+    // Use Subscribable's subscribe method (triggers onSubscribe hook)
+    return this.subscribe(callback);
+  }
+
+  // ===========================================================================
+  // EVENT MANAGEMENT
+  // ===========================================================================
+
+  /**
+   * Add an event to the store.
+   * Call this from subclasses when a new event is received.
+   *
+   * @param event - The event to add
+   */
+  addEvent(event) {
+    // Add to beginning (newest first) and limit to maxEvents
+    this.events = [event, ...this.events].slice(0, this.maxEvents);
+
+    // Notify individual event callbacks (via Subscribable)
+    this.notify(event);
+
+    // Notify array listeners
+    this.notifyArrayListeners();
+  }
+
+  /**
+   * Notify all array listeners of changes
+   */
+  notifyArrayListeners() {
+    const events = this.getEvents();
+    this.arrayListeners.forEach(listener => {
+      try {
+        listener(events);
+      } catch {
+        // Ignore listener errors
+      }
+    });
+  }
+
+  /**
+   * Get all events (newest first)
+   */
+  getEvents() {
+    return this.events;
+  }
+
+  /**
+   * Get event count
+   */
+  getEventCount() {
+    return this.events.length;
+  }
+
+  /**
+   * Clear all events
+   */
+  clearEvents() {
+    this.events = [];
+    this.notifyArrayListeners();
+  }
+
+  /**
+   * Set maximum number of events to keep
+   */
+  setMaxEvents(max) {
+    this.maxEvents = max;
+    if (this.events.length > max) {
+      this.events = this.events.slice(0, max);
+      this.notifyArrayListeners();
+    }
+  }
+
+  // ===========================================================================
+  // DEBUGGING
+  // ===========================================================================
+
+  /**
+   * Get current subscriber counts for debugging
+   */
+  getSubscriberCounts() {
+    return {
+      eventCallbacks: this.listeners.size,
+      arrayListeners: this.arrayListeners.size,
+      total: this.getTotalSubscriberCount()
+    };
+  }
+}

package/lib/module/stores/index.js

@@ -0,0 +1,7 @@
+"use strict";
+
+/**
+ * Shared store utilities and base classes
+ */
+
+export { BaseEventStore } from "./BaseEventStore.js";

package/lib/module/utils/index.js

@@ -6,4 +6,7 @@ export { persistentStorage, isUsingPersistentStorage, getStorageBackendType } fr
 export { safeStringify } from "./safeStringify.js";
 export { getValueType, isPrimitive, isJsonSerializable, isValidJson, getConstructorName, isEmpty, getValueSize } from "./typeHelpers.js";
 export { parseValue, formatValue, getTypeColor, truncateText, flattenObject, formatPath } from "./valueFormatting.js";
-export { loadOptionalModule, getCachedOptionalModule } from "./loadOptionalModule.js";
+export { loadOptionalModule, getCachedOptionalModule } from "./loadOptionalModule.js";
+export { Subscribable } from "./subscribable.js";
+export { subscriberCountNotifier, subscribeToSubscriberCountChanges, notifySubscriberCountChange } from "./subscriberCountNotifier.js";
+export { useSafeRouter, useSafePathname, useSafeSegments, useSafeGlobalSearchParams, getSafeRouter, isExpoRouterAvailable } from "./safeExpoRouter.js";

package/lib/module/utils/safeExpoRouter.js

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * Safe wrapper for expo-router
+ *
+ * Provides optional imports for expo-router hooks and utilities.
+ * Falls back to no-op implementations when expo-router is not installed.
+ *
+ * On RN CLI (without Expo native modules), expo-router's JS is bundled but
+ * its hooks crash at runtime because the ExpoLinking native module is missing.
+ * We check for the native module BEFORE attempting to use any expo-router hooks.
+ */
+
+import { NativeModules } from "react-native";
+let expoRouter = null;
+let isAvailable = false;
+let checkedAvailability = false;
+function checkExpoRouterAvailability() {
+  if (checkedAvailability) return isAvailable;
+  try {
+    // expo-router depends on ExpoLinking native module.
+    // On RN CLI the JS is bundled but the native module isn't registered,
+    // so require() succeeds but hooks crash at runtime. Check native side first.
+    if (!NativeModules.ExpoLinking) {
+      checkedAvailability = true;
+      return false;
+    }
+    expoRouter = require("expo-router");
+    isAvailable = expoRouter != null;
+  } catch (error) {
+    isAvailable = false;
+    expoRouter = null;
+  }
+  checkedAvailability = true;
+  return isAvailable;
+}
+
+// ============================================================================
+// No-op implementations when expo-router is not available
+// ============================================================================
+
+function noOpUseRouter() {
+  return {
+    push: () => console.warn("[buoy] expo-router not installed: push() unavailable"),
+    replace: () => console.warn("[buoy] expo-router not installed: replace() unavailable"),
+    back: () => console.warn("[buoy] expo-router not installed: back() unavailable"),
+    canGoBack: () => false,
+    setParams: () => console.warn("[buoy] expo-router not installed: setParams() unavailable"),
+    navigate: () => console.warn("[buoy] expo-router not installed: navigate() unavailable")
+  };
+}
+function noOpUsePathname() {
+  return "/";
+}
+function noOpUseSegments() {
+  return [];
+}
+function noOpUseGlobalSearchParams() {
+  return {};
+}
+
+// ============================================================================
+// Safe hook exports
+// ============================================================================
+
+export function useSafeRouter() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUseRouter();
+  }
+  try {
+    return expoRouter.useRouter();
+  } catch (error) {
+    console.warn("[buoy] Failed to use expo-router.useRouter:", error);
+    return noOpUseRouter();
+  }
+}
+export function useSafePathname() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUsePathname();
+  }
+  try {
+    return expoRouter.usePathname();
+  } catch (error) {
+    console.warn("[buoy] Failed to use expo-router.usePathname:", error);
+    return noOpUsePathname();
+  }
+}
+export function useSafeSegments() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUseSegments();
+  }
+  try {
+    return expoRouter.useSegments();
+  } catch (error) {
+    console.warn("[buoy] Failed to use expo-router.useSegments:", error);
+    return noOpUseSegments();
+  }
+}
+export function useSafeGlobalSearchParams() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUseGlobalSearchParams();
+  }
+  try {
+    return expoRouter.useGlobalSearchParams();
+  } catch (error) {
+    console.warn("[buoy] Failed to use expo-router.useGlobalSearchParams:", error);
+    return noOpUseGlobalSearchParams();
+  }
+}
+
+// ============================================================================
+// Router instance getter (for imperative navigation)
+// ============================================================================
+
+export function getSafeRouter() {
+  if (!checkExpoRouterAvailability()) {
+    return null;
+  }
+  try {
+    return expoRouter.router || null;
+  } catch (error) {
+    return null;
+  }
+}
+
+// ============================================================================
+// Availability check
+// ============================================================================
+
+export function isExpoRouterAvailable() {
+  return checkExpoRouterAvailability();
+}

package/lib/module/utils/subscribable.js

@@ -0,0 +1,108 @@
+"use strict";
+
+/**
+ * Subscribable - Base class for pub/sub pattern with lifecycle hooks
+ *
+ * Ported from TanStack Query's subscription architecture.
+ * Provides a foundation for self-managing listeners that automatically
+ * start when the first subscriber joins and stop when the last leaves.
+ *
+ * @example
+ * ```typescript
+ * class NetworkEventStore extends Subscribable<NetworkEventListener> {
+ *   protected onSubscribe(): void {
+ *     if (this.listeners.size === 1) {
+ *       // First subscriber - start listening
+ *       this.startNetworkListener();
+ *     }
+ *   }
+ *
+ *   protected onUnsubscribe(): void {
+ *     if (this.listeners.size === 0) {
+ *       // Last subscriber left - stop listening
+ *       this.stopNetworkListener();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+export class Subscribable {
+  listeners = new Set();
+  constructor() {
+    this.subscribe = this.subscribe.bind(this);
+  }
+
+  /**
+   * Subscribe to updates.
+   * @param listener - Callback function to receive updates
+   * @returns Unsubscribe function
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    this.onSubscribe();
+    return () => {
+      this.listeners.delete(listener);
+      this.onUnsubscribe();
+    };
+  }
+
+  /**
+   * Check if there are any active listeners.
+   */
+  hasListeners() {
+    return this.listeners.size > 0;
+  }
+
+  /**
+   * Get the current number of listeners.
+   */
+  getListenerCount() {
+    return this.listeners.size;
+  }
+
+  /**
+   * Notify all listeners with given arguments.
+   */
+  notify(...args) {
+    this.listeners.forEach(listener => {
+      listener(...args);
+    });
+  }
+
+  /**
+   * Called when a listener is added.
+   * Override to start resources when first subscriber joins.
+   *
+   * @example
+   * ```typescript
+   * protected onSubscribe(): void {
+   *   if (this.listeners.size === 1) {
+   *     this.startCapturing();
+   *   }
+   * }
+   * ```
+   */
+  onSubscribe() {
+    // Override in subclasses
+  }
+
+  /**
+   * Called when a listener is removed.
+   * Override to stop resources when last subscriber leaves.
+   *
+   * @example
+   * ```typescript
+   * protected onUnsubscribe(): void {
+   *   if (this.listeners.size === 0) {
+   *     this.stopCapturing();
+   *   }
+   * }
+   * ```
+   */
+  onUnsubscribe() {
+    // Override in subclasses
+  }
+}