@buoy-gg/core 1.7.2

package/README.md

@@ -0,0 +1,43 @@
+# @buoy/core
+
+[![npm](https://img.shields.io/npm/v/@buoy%2Fcore)](https://www.npmjs.com/package/@buoy/core)
+
+
+Floating dev tools launcher and host provider for React Native apps.
+
+## Install
+```bash
+pnpm add @buoy/core @buoy/shared-ui
+```
+
+## Quick Start
+```tsx
+import { AppHostProvider, FloatingMenu } from '@buoy/core';
+import type { InstalledApp } from '@buoy/core';
+import { EnvVarsModal } from '@buoy/env';
+
+const APPS: InstalledApp[] = [
+  {
+    id: 'env',
+    name: 'Environment',
+    icon: '🛰️',
+    component: EnvVarsModal,
+    singleton: true,
+  },
+];
+
+export function DevToolsHost() {
+  return (
+    <AppHostProvider>
+      <FloatingMenu apps={APPS} />
+    </AppHostProvider>
+  );
+}
+```
+
+## Key Exports
+- `AppHostProvider` – Context provider that manages installed dev tools.
+- `FloatingMenu` – Cyberpunk-inspired floating entrypoint for tools.
+- `AppOverlay` & `useAppHost()` – Programmatic APIs for opening tools.
+
+The menu hosts any `InstalledApp` descriptor. Combine it with other `@buoy/*` packages for a full suite of debug panels.

package/lib/commonjs/floatingMenu/AppHost.js

@@ -0,0 +1,410 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useAppHost = exports.AppOverlay = exports.AppHostProvider = void 0;
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _AppHostLogic = require("./AppHostLogic.js");
+var _MinimizedToolsContext = require("./MinimizedToolsContext.js");
+var _DevToolsSettingsModal = require("./DevToolsSettingsModal.js");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+const AppHostContext = /*#__PURE__*/(0, _react.createContext)(null);
+const STORAGE_KEY_OPEN_APPS = "@react_buoy_open_apps";
+const PERSISTENCE_DELAY = 500;
+
+// Type for persisted app state
+
+/**
+ * Provides the floating dev tools application host. Tracks open tool instances, restores
+ * persisted state, and exposes imperative helpers used by `FloatingMenu` and friends.
+ */
+const AppHostProvider = ({
+  children
+}) => {
+  const [openApps, setOpenApps] = (0, _react.useState)([]);
+  const [isRestored, setIsRestored] = (0, _react.useState)(false);
+  const persistenceTimeoutRef = (0, _react.useRef)(null);
+  const installedAppsRef = (0, _react.useRef)([]);
+  const pendingRestoreRef = (0, _react.useRef)(null);
+  const {
+    restore: removeFromMinimizedStack
+  } = (0, _MinimizedToolsContext.useMinimizedTools)();
+  const open = (0, _react.useCallback)(def => {
+    let resolvedId = "";
+    setOpenApps(current => {
+      const {
+        apps,
+        instanceId,
+        wasMinimized
+      } = (0, _AppHostLogic.resolveOpenAppsState)(current, def, () => `${def.id}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      resolvedId = instanceId;
+
+      // If the app was minimized, remove it from the minimized stack
+      // This needs to be done outside of setOpenApps to avoid nested state updates
+      if (wasMinimized) {
+        // Schedule the removal for after this state update completes
+        setTimeout(() => removeFromMinimizedStack(instanceId), 0);
+      }
+      return apps;
+    });
+    return resolvedId;
+  }, [removeFromMinimizedStack]);
+  const tryRestorePending = (0, _react.useCallback)(() => {
+    if (isRestored) return;
+    if (!installedAppsRef.current.length) return;
+    const pendingApps = pendingRestoreRef.current;
+    if (!pendingApps || pendingApps.length === 0) {
+      setIsRestored(true);
+      return;
+    }
+    pendingRestoreRef.current = null;
+    pendingApps.forEach(({
+      id: appId,
+      minimized
+    }) => {
+      const appDef = installedAppsRef.current.find(app => app.id === appId);
+      if (appDef) {
+        const resolvedIcon = typeof appDef.icon === "function" ? appDef.icon({
+          slot: "dial",
+          size: 20
+        }) : appDef.icon;
+        open({
+          id: appDef.id,
+          title: appDef.name,
+          component: appDef.component,
+          props: appDef.props,
+          launchMode: appDef.launchMode || "self-modal",
+          singleton: appDef.singleton,
+          icon: resolvedIcon,
+          color: appDef.color,
+          minimized: minimized // Preserve minimized state
+        });
+      }
+    });
+    setIsRestored(true);
+  }, [isRestored, open]);
+
+  // Restore open apps on mount
+  (0, _react.useEffect)(() => {
+    const restoreOpenApps = async () => {
+      try {
+        const saved = await (0, _sharedUi.safeGetItem)(STORAGE_KEY_OPEN_APPS);
+        if (saved) {
+          const parsed = JSON.parse(saved);
+          // Handle both old format (string[]) and new format (PersistedAppState[])
+          let savedApps;
+          if (Array.isArray(parsed) && parsed.length > 0) {
+            if (typeof parsed[0] === "string") {
+              // Old format: convert string[] to PersistedAppState[]
+              savedApps = parsed.map(id => ({
+                id,
+                minimized: false
+              }));
+            } else {
+              // New format: already PersistedAppState[]
+              savedApps = parsed;
+            }
+            if (savedApps.length) {
+              pendingRestoreRef.current = savedApps;
+              tryRestorePending();
+              return;
+            }
+          }
+        }
+      } catch (error) {
+        // Failed to restore open apps - continue with fresh state
+      }
+      setIsRestored(true);
+    };
+    restoreOpenApps();
+  }, [tryRestorePending]);
+
+  // Save open apps with debounce
+  (0, _react.useEffect)(() => {
+    if (!isRestored) return;
+
+    // Clear existing timeout
+    if (persistenceTimeoutRef.current) {
+      clearTimeout(persistenceTimeoutRef.current);
+    }
+
+    // Set new timeout to save
+    persistenceTimeoutRef.current = setTimeout(() => {
+      const appStates = openApps.map(app => ({
+        id: app.id,
+        minimized: app.minimized ?? false
+      }));
+      (0, _sharedUi.safeSetItem)(STORAGE_KEY_OPEN_APPS, JSON.stringify(appStates));
+    }, PERSISTENCE_DELAY);
+    return () => {
+      if (persistenceTimeoutRef.current) {
+        clearTimeout(persistenceTimeoutRef.current);
+      }
+    };
+  }, [openApps, isRestored]);
+
+  // Store reference to installed apps for restoration
+  const registerApps = (0, _react.useCallback)(apps => {
+    installedAppsRef.current = apps;
+    tryRestorePending();
+  }, [tryRestorePending]);
+  const close = (0, _react.useCallback)(instanceId => {
+    setOpenApps(s => {
+      if (!s.length) return s;
+      if (!instanceId) return s.slice(0, -1);
+      return s.filter(a => a.instanceId !== instanceId);
+    });
+  }, []);
+  const closeAll = (0, _react.useCallback)(() => setOpenApps([]), []);
+  const minimize = (0, _react.useCallback)(instanceId => {
+    setOpenApps(s => s.map(app => app.instanceId === instanceId ? {
+      ...app,
+      minimized: true
+    } : app));
+  }, []);
+  const restore = (0, _react.useCallback)((instanceId, restoreState) => {
+    setOpenApps(s => s.map(app => app.instanceId === instanceId ? {
+      ...app,
+      minimized: false,
+      restoreState
+    } : app));
+  }, []);
+  const isMinimized = (0, _react.useCallback)(instanceId => {
+    const app = openApps.find(a => a.instanceId === instanceId);
+    return app?.minimized ?? false;
+  }, [openApps]);
+  _react.default.useEffect(() => {
+    if (openApps.length === 0) return;
+    const handler = () => {
+      close();
+      return true;
+    };
+    const sub = _reactNative.BackHandler.addEventListener("hardwareBackPress", handler);
+    return () => sub.remove();
+  }, [openApps.length, close]);
+  const value = (0, _react.useMemo)(() => ({
+    openApps,
+    // Only count non-toggle-only and non-minimized tools as "open"
+    isAnyOpen: openApps.filter(app => app.launchMode !== "toggle-only" && !app.minimized).length > 0,
+    open,
+    close,
+    closeAll,
+    registerApps,
+    minimize,
+    restore,
+    isMinimized
+  }), [openApps, open, close, closeAll, registerApps, minimize, restore, isMinimized]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(AppHostContext.Provider, {
+    value: value,
+    children: children
+  });
+};
+
+/**
+ * Accessor hook for the dev tools app host. Components can open/close tools or inspect
+ * the active stack. Falls back to a no-op implementation when rendered outside the provider.
+ */
+exports.AppHostProvider = AppHostProvider;
+const useAppHost = () => {
+  const ctx = (0, _react.useContext)(AppHostContext);
+  // Return a default value if not in provider (for backwards compatibility)
+  if (!ctx) {
+    return {
+      openApps: [],
+      isAnyOpen: false,
+      open: () => "",
+      close: () => {},
+      closeAll: () => {},
+      minimize: () => {},
+      restore: (_instanceId, _restoreState) => {},
+      isMinimized: () => false
+    };
+  }
+  return ctx;
+};
+
+/**
+ * Renders a single app instance. Keeps component mounted even when minimized
+ * by passing visible={false} instead of unmounting.
+ *
+ * Supports multiple simultaneous modals - each gets its own z-index based on
+ * position in the open apps stack (later opened = higher z-index).
+ */
+exports.useAppHost = useAppHost;
+const AppRenderer = ({
+  app,
+  zIndex,
+  onClose,
+  onMinimize,
+  minimizeTargetPosition,
+  globalEnableSharedModalDimensions
+}) => {
+  const Comp = app.component;
+  // All non-minimized apps are visible - supports multiple simultaneous modals
+  const isVisible = !app.minimized;
+
+  // Merge props with global settings override
+  // Priority: Global settings (if defined) > Tool prop > Default (false)
+  const mergedProps = {
+    ...(app.props ?? {}),
+    // Only override if globalEnableSharedModalDimensions is explicitly true
+    // (when the user turns it on in settings)
+    ...(globalEnableSharedModalDimensions === true ? {
+      enableSharedModalDimensions: true
+    } : {})
+  };
+  if (app.launchMode === "self-modal") {
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(Comp, {
+      ...mergedProps,
+      visible: isVisible,
+      onClose: onClose,
+      onRequestClose: onClose,
+      onMinimize: onMinimize,
+      minimizeTargetPosition: minimizeTargetPosition,
+      initialModalState: app.restoreState,
+      instanceId: app.instanceId,
+      zIndex: zIndex
+    });
+  }
+  if (app.launchMode === "inline") {
+    if (!isVisible) return null;
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      pointerEvents: "box-none",
+      style: [_reactNative.StyleSheet.absoluteFill, {
+        zIndex
+      }],
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(Comp, {
+        ...mergedProps,
+        onClose: onClose,
+        onMinimize: onMinimize,
+        minimizeTargetPosition: minimizeTargetPosition,
+        initialModalState: app.restoreState,
+        instanceId: app.instanceId
+      })
+    });
+  }
+
+  // host-modal mode
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Modal, {
+    visible: isVisible,
+    transparent: true,
+    animationType: "slide",
+    onRequestClose: onClose,
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: styles.backdrop,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: styles.card,
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(Comp, {
+          ...mergedProps,
+          onClose: onClose,
+          onMinimize: onMinimize,
+          minimizeTargetPosition: minimizeTargetPosition,
+          initialModalState: app.restoreState,
+          instanceId: app.instanceId
+        })
+      })
+    })
+  });
+};
+
+/**
+ * Renders all dev tool surfaces. Keeps minimized apps mounted but hidden
+ * so their state and listeners are preserved (similar to React Navigation screens).
+ *
+ * Supports multiple simultaneous modals - each modal gets a z-index based on
+ * its position in the stack (later opened modals appear on top).
+ */
+const AppOverlay = () => {
+  const {
+    openApps,
+    close,
+    minimize
+  } = useAppHost();
+  const {
+    minimize: addToMinimizedStack,
+    getNextIconPosition,
+    minimizedTools
+  } = (0, _MinimizedToolsContext.useMinimizedTools)();
+  const {
+    settings
+  } = (0, _DevToolsSettingsModal.useDevToolsSettings)();
+
+  // Sync restored minimized apps to MinimizedToolsContext
+  // This handles apps that were restored from persistence with minimized=true
+  _react.default.useEffect(() => {
+    openApps.forEach(app => {
+      if (app.minimized && app.launchMode !== "toggle-only") {
+        // Check if this app is already in the minimized stack
+        const isInStack = minimizedTools.some(t => t.instanceId === app.instanceId);
+        if (!isInStack) {
+          // Add to minimized stack (restored from persistence)
+          addToMinimizedStack({
+            instanceId: app.instanceId,
+            id: app.id,
+            title: app.title || app.id,
+            icon: app.icon,
+            color: app.color
+          });
+        }
+      }
+    });
+  }, [openApps, minimizedTools, addToMinimizedStack]);
+
+  // Filter to renderable apps (exclude toggle-only)
+  const renderableApps = openApps.filter(app => app.launchMode !== "toggle-only");
+  if (renderableApps.length === 0) return null;
+
+  // Base z-index for modals - each subsequent modal gets +1
+  const BASE_ZINDEX = 9000;
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
+    children: renderableApps.map((app, index) => {
+      // z-index based on position - later in array = higher z-index (on top)
+      const zIndex = BASE_ZINDEX + index;
+      const minimizeTargetPosition = getNextIconPosition();
+      const handleMinimize = modalState => {
+        // IMPORTANT: Order matters here!
+        // 1. First mark the app as minimized in AppHost - this updates isAnyOpen
+        //    so that pushToSide becomes false before the icon component mounts
+        minimize(app.instanceId);
+        // 2. Then add to the minimized stack - this triggers the icon to mount
+        //    By now isAnyOpen is false, so the icon mounts with pushToSide=false
+        addToMinimizedStack({
+          instanceId: app.instanceId,
+          id: app.id,
+          title: app.title || app.id,
+          icon: app.icon,
+          color: app.color,
+          modalState: modalState
+        });
+      };
+      return /*#__PURE__*/(0, _jsxRuntime.jsx)(AppRenderer, {
+        app: app,
+        zIndex: zIndex,
+        onClose: () => close(app.instanceId),
+        onMinimize: handleMinimize,
+        minimizeTargetPosition: minimizeTargetPosition,
+        globalEnableSharedModalDimensions: settings.globalSettings?.enableSharedModalDimensions
+      }, app.instanceId);
+    })
+  });
+};
+exports.AppOverlay = AppOverlay;
+const styles = _reactNative.StyleSheet.create({
+  backdrop: {
+    flex: 1,
+    backgroundColor: "rgba(0,0,0,0.28)",
+    alignItems: "center",
+    justifyContent: "center"
+  },
+  card: {
+    maxHeight: "90%",
+    width: "94%",
+    borderRadius: 12,
+    backgroundColor: "white",
+    overflow: "hidden"
+  }
+});

package/lib/commonjs/floatingMenu/AppHostLogic.js

@@ -0,0 +1,44 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveOpenAppsState = void 0;
+/**
+ * Computes the new list of open tool instances when a user launches a dev app. Singleton
+ * tools reuse their existing instance while non-singletons create a new entry using the
+ * provided `generateId` helper.
+ *
+ * @param current - Current stack of open app instances.
+ * @param def - Descriptor of the tool to launch (without runtime instance id).
+ * @param generateId - Callback used to generate a unique instance identifier.
+ * @returns Updated instance list alongside the resolved instance id.
+ */
+const resolveOpenAppsState = (current, def, generateId) => {
+  if (def.singleton) {
+    const existing = current.find(app => app.id === def.id);
+    if (existing) {
+      const wasMinimized = existing.minimized ?? false;
+      return {
+        instanceId: existing.instanceId,
+        wasMinimized,
+        apps: [...current.filter(app => app.instanceId !== existing.instanceId),
+        // Un-minimize the existing app when re-opening it
+        {
+          ...existing,
+          minimized: false
+        }]
+      };
+    }
+  }
+  const instanceId = generateId();
+  return {
+    instanceId,
+    wasMinimized: false,
+    apps: [...current, {
+      ...def,
+      instanceId
+    }]
+  };
+};
+exports.resolveOpenAppsState = resolveOpenAppsState;

package/lib/commonjs/floatingMenu/DefaultConfigContext.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DefaultConfigProvider = DefaultConfigProvider;
+exports.useDefaultConfig = useDefaultConfig;
+var _react = _interopRequireWildcard(require("react"));
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/**
+ * Context value for default configuration settings.
+ */
+
+const DefaultConfigContext = /*#__PURE__*/(0, _react.createContext)({});
+
+/**
+ * Provider for default configuration that can be consumed by the settings system.
+ * This allows teams to set default tool configurations without prop drilling.
+ *
+ * @internal Used by FloatingDevTools to provide defaults to the settings hook.
+ */
+function DefaultConfigProvider({
+  children,
+  defaultFloatingTools,
+  defaultDialTools
+}) {
+  const value = _react.default.useMemo(() => ({
+    defaultFloatingTools,
+    defaultDialTools
+  }), [defaultFloatingTools, defaultDialTools]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(DefaultConfigContext.Provider, {
+    value: value,
+    children: children
+  });
+}
+
+/**
+ * Hook to access the default configuration from context.
+ *
+ * @internal Used by useDevToolsSettings to apply defaults.
+ */
+function useDefaultConfig() {
+  return (0, _react.useContext)(DefaultConfigContext);
+}