@buoy-gg/env 1.7.2

package/README.md

@@ -0,0 +1,388 @@
+# @buoy/env
+
+[![npm](https://img.shields.io/npm/v/@buoy%2Fenv)](https://www.npmjs.com/package/@buoy/env)
+
+Environment variables inspector and validator for React Native development tools.
+
+## Features
+
+- **Environment Variable Inspector**: Browse all environment variables in your app
+- **Required Variable Validation**: Define and validate required environment variables
+- **Type Checking**: Validate variable types (string, boolean, number, etc.)
+- **Value Validation**: Check if variables match expected values
+- **Search & Filtering**: Search and filter by variable name, value, or status
+- **Copy Functionality**: Easily copy variable values
+- **Beautiful UI**: Modern, game-themed interface matching other React Buoy tools
+
+## Installation
+
+This package is part of the React Buoy monorepo and is automatically available to other packages and the example app.
+
+For external projects:
+
+```bash
+npm install @buoy/env
+# or
+pnpm add @buoy/env
+# or
+yarn add @buoy/env
+```
+
+## Quick Start
+
+### Simplest Setup - Just 1 Line!
+
+**Import the preset and add it to your tools array. Done!**
+
+```typescript
+import { envToolPreset } from '@buoy/env';
+import { FloatingDevTools } from '@buoy/core';
+
+const installedApps = [
+  envToolPreset, // That's it! One line.
+  // ...your other tools
+];
+
+function App() {
+  return (
+    <FloatingDevTools
+      apps={installedApps}
+      environment="local"
+      userRole="admin"
+    />
+  );
+}
+```
+
+**Done!** The preset automatically:
+- ✅ Inspects all environment variables
+- ✅ Provides search and filtering
+- ✅ Includes copy functionality
+- ✅ No configuration required
+
+### Custom Configuration
+
+If you need to validate specific environment variables:
+
+```typescript
+import { createEnvTool, createEnvVarConfig, envVar } from '@buoy/env';
+
+// Define required environment variables
+const requiredEnvVars = createEnvVarConfig([
+  envVar("EXPO_PUBLIC_API_URL").exists(),
+  envVar("EXPO_PUBLIC_DEBUG_MODE").withType("boolean").build(),
+  envVar("EXPO_PUBLIC_ENVIRONMENT").withValue("development").build(),
+]);
+
+// Create custom tool with validation
+const myEnvTool = createEnvTool({
+  requiredEnvVars,
+  colorPreset: "cyan",
+  enableSharedModalDimensions: true,
+});
+
+const installedApps = [
+  myEnvTool,
+  // ...other tools
+];
+```
+
+### Alternative: Manual Setup
+
+If you're not using FloatingDevTools or want more control:
+
+```typescript
+import { EnvVarsModal, createEnvVarConfig, envVar } from '@buoy/env';
+
+const requiredEnvVars = createEnvVarConfig([
+  envVar("EXPO_PUBLIC_API_URL").exists(),
+  envVar("EXPO_PUBLIC_DEBUG_MODE").withType("boolean").build(),
+]);
+
+function App() {
+  const [showEnv, setShowEnv] = useState(false);
+
+  return (
+    <>
+      <Button onPress={() => setShowEnv(true)}>
+        Open Environment Inspector
+      </Button>
+
+      <EnvVarsModal
+        visible={showEnv}
+        onClose={() => setShowEnv(false)}
+        requiredEnvVars={requiredEnvVars}
+      />
+    </>
+  );
+}
+```
+
+## API Reference
+
+### Presets
+
+#### `envToolPreset`
+
+Pre-configured environment variables tool ready to use with FloatingDevTools.
+
+**Example:**
+```typescript
+import { envToolPreset } from '@buoy/env';
+
+const installedApps = [envToolPreset];
+```
+
+#### `createEnvTool(options?)`
+
+Create a custom environment variables tool configuration.
+
+**Options:**
+```typescript
+{
+  /** Tool name (default: "ENV") */
+  name?: string;
+  /** Tool description */
+  description?: string;
+  /** Icon color preset (default: "green") */
+  colorPreset?: "orange" | "cyan" | "purple" | "pink" | "yellow" | "green";
+  /** Custom tool ID (default: "env") */
+  id?: string;
+  /** Array of required environment variables to validate */
+  requiredEnvVars?: RequiredEnvVar[];
+  /** Enable shared modal dimensions */
+  enableSharedModalDimensions?: boolean;
+}
+```
+
+**Example:**
+```typescript
+import { createEnvTool, createEnvVarConfig, envVar } from '@buoy/env';
+
+const requiredEnvVars = createEnvVarConfig([
+  envVar("API_URL").exists(),
+  envVar("DEBUG").withType("boolean").build(),
+]);
+
+const myEnvTool = createEnvTool({
+  name: "ENVIRONMENT",
+  requiredEnvVars,
+  colorPreset: "purple",
+  enableSharedModalDimensions: true,
+});
+```
+
+### Components
+
+#### `EnvVarsModal`
+
+Main modal component for inspecting environment variables.
+
+**Props:**
+```typescript
+interface EnvVarsModalProps {
+  /** Whether the modal is visible */
+  visible: boolean;
+  /** Callback when modal is closed */
+  onClose: () => void;
+  /** List of required environment variables to validate */
+  requiredEnvVars: RequiredEnvVar[];
+  /** Optional back button handler */
+  onBack?: () => void;
+  /** Whether to use shared modal dimensions */
+  enableSharedModalDimensions?: boolean;
+}
+```
+
+**Example:**
+```typescript
+<EnvVarsModal
+  visible={isVisible}
+  onClose={handleClose}
+  requiredEnvVars={requiredEnvVars}
+/>
+```
+
+### Utilities
+
+#### `createEnvVarConfig(validators)`
+
+Create an array of required environment variables with validation rules.
+
+**Signature:**
+```typescript
+function createEnvVarConfig(
+  validators: EnvVarValidator[]
+): RequiredEnvVar[]
+```
+
+**Example:**
+```typescript
+import { createEnvVarConfig, envVar } from '@buoy/env';
+
+const config = createEnvVarConfig([
+  envVar("API_URL").exists(),
+  envVar("DEBUG").withType("boolean").build(),
+  envVar("ENVIRONMENT").withValue("production").build(),
+]);
+```
+
+#### `envVar(key)`
+
+Create a fluent validator for an environment variable.
+
+**Signature:**
+```typescript
+function envVar(key: string): EnvVarValidator
+```
+
+**Methods:**
+- `.exists()` - Validate that the variable exists
+- `.withType(type)` - Validate the variable type (string, boolean, number, etc.)
+- `.withValue(value)` - Validate the variable matches a specific value
+- `.build()` - Finalize the validator
+
+**Example:**
+```typescript
+import { envVar } from '@buoy/env';
+
+// Variable must exist
+envVar("API_URL").exists();
+
+// Variable must be a boolean
+envVar("DEBUG_MODE").withType("boolean").build();
+
+// Variable must match specific value
+envVar("ENVIRONMENT").withValue("staging").build();
+
+// Combined validation
+envVar("PORT")
+  .withType("number")
+  .withValue("3000")
+  .build();
+```
+
+### Types
+
+#### `RequiredEnvVar`
+
+```typescript
+interface RequiredEnvVar {
+  /** Environment variable key */
+  key: string;
+  /** Optional description */
+  description?: string;
+  /** Expected type */
+  expectedType?: "string" | "boolean" | "number" | "json";
+  /** Expected value */
+  expectedValue?: string;
+  /** Whether the variable must exist */
+  required?: boolean;
+}
+```
+
+#### `Environment`
+
+```typescript
+type Environment = 
+  | "local" 
+  | "development" 
+  | "staging" 
+  | "production" 
+  | string;
+```
+
+#### `UserRole`
+
+```typescript
+type UserRole = "admin" | "internal" | "user";
+```
+
+## Use Cases
+
+### API Configuration Validation
+
+```typescript
+import { createEnvTool, createEnvVarConfig, envVar } from '@buoy/env';
+
+const requiredEnvVars = createEnvVarConfig([
+  envVar("EXPO_PUBLIC_API_URL").exists(),
+  envVar("EXPO_PUBLIC_API_KEY").exists(),
+  envVar("EXPO_PUBLIC_API_TIMEOUT").withType("number").build(),
+]);
+
+const envTool = createEnvTool({ requiredEnvVars });
+```
+
+### Environment-Specific Validation
+
+```typescript
+import { createEnvVarConfig, envVar } from '@buoy/env';
+
+const requiredEnvVars = createEnvVarConfig([
+  envVar("EXPO_PUBLIC_ENVIRONMENT")
+    .withValue("development")
+    .build(),
+  envVar("EXPO_PUBLIC_DEBUG_MODE")
+    .withType("boolean")
+    .build(),
+  envVar("EXPO_PUBLIC_ENABLE_LOGGING")
+    .withType("boolean")
+    .build(),
+]);
+```
+
+### Feature Flag Configuration
+
+```typescript
+import { createEnvVarConfig, envVar } from '@buoy/env';
+
+const requiredEnvVars = createEnvVarConfig([
+  envVar("EXPO_PUBLIC_FEATURE_NEW_UI")
+    .withType("boolean")
+    .build(),
+  envVar("EXPO_PUBLIC_FEATURE_ANALYTICS")
+    .withType("boolean")
+    .build(),
+  envVar("EXPO_PUBLIC_FEATURE_BETA")
+    .withType("boolean")
+    .build(),
+]);
+```
+
+## Dependencies
+
+- `@buoy/shared-ui` - Common UI components and utilities
+- React and React Native (peer dependencies)
+
+## Development
+
+### Building
+
+```bash
+pnpm build
+```
+
+### Type Checking
+
+```bash
+pnpm typecheck
+```
+
+### Clean Build
+
+```bash
+pnpm clean
+```
+
+## License
+
+MIT
+
+## Contributing
+
+See the main repository [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.
+
+## Support
+
+For issues and feature requests, please visit the [GitHub repository](https://github.com/LovesWorking/react-native-buoy/issues).

package/lib/commonjs/env/EnvVariables.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "EnvVarsModal", {
+  enumerable: true,
+  get: function () {
+    return _EnvVarsModal.EnvVarsModal;
+  }
+});
+Object.defineProperty(exports, "createEnvVarConfig", {
+  enumerable: true,
+  get: function () {
+    return _helpers.createEnvVarConfig;
+  }
+});
+Object.defineProperty(exports, "envVar", {
+  enumerable: true,
+  get: function () {
+    return _helpers.envVar;
+  }
+});
+var _helpers = require("./utils/helpers");
+var _EnvVarsModal = require("./components/EnvVarsModal");

package/lib/commonjs/env/components/EnvStatsOverview.js

@@ -0,0 +1,134 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EnvStatsOverview = EnvStatsOverview;
+var _reactNative = require("react-native");
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _jsxRuntime = require("react/jsx-runtime");
+function EnvStatsOverview({
+  stats,
+  healthPercentage,
+  healthStatus,
+  healthColor,
+  activeFilter = "all",
+  onFilterChange
+}) {
+  const issuesCount = stats.wrongValueCount + stats.wrongTypeCount;
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+    style: styles.container,
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.CompactRow, {
+      statusDotColor: healthColor,
+      statusLabel: "System",
+      statusSublabel: healthStatus.toLowerCase(),
+      primaryText: "Environment Configuration",
+      secondaryText: `${healthPercentage}% healthy`,
+      customBadge: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: [styles.percentBadge, {
+          borderColor: healthColor + "40",
+          backgroundColor: healthColor + "10"
+        }],
+        children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
+          style: [styles.percentText, {
+            color: healthColor
+          }],
+          children: [healthPercentage, "%"]
+        })
+      })
+    }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.statsGrid,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
+        style: [styles.statCard, activeFilter === "all" && styles.statCardActive],
+        onPress: () => onFilterChange?.("all"),
+        activeOpacity: 0.8,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.statValue, activeFilter === "all" && styles.statValueActive],
+          children: stats.requiredCount + stats.optionalCount
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.statLabel, activeFilter === "all" && styles.statLabelActive],
+          children: "ALL"
+        })]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
+        style: [styles.statCard, activeFilter === "missing" && styles.statCardActive],
+        onPress: () => onFilterChange?.("missing"),
+        activeOpacity: 0.8,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.statValue, activeFilter === "missing" && styles.statValueActive],
+          children: stats.missingCount
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.statLabel, activeFilter === "missing" && styles.statLabelActive],
+          children: "MISSING"
+        })]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
+        style: [styles.statCard, activeFilter === "issues" && styles.statCardActive],
+        onPress: () => onFilterChange?.("issues"),
+        activeOpacity: 0.8,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.statValue, activeFilter === "issues" && styles.statValueActive],
+          children: issuesCount
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.statLabel, activeFilter === "issues" && styles.statLabelActive],
+          children: "ISSUES"
+        })]
+      })]
+    })]
+  });
+}
+const styles = _reactNative.StyleSheet.create({
+  container: {
+    gap: 8
+  },
+  statsGrid: {
+    flexDirection: "row",
+    gap: 8,
+    paddingHorizontal: 4
+  },
+  statCard: {
+    flex: 1,
+    backgroundColor: _sharedUi.buoyColors.card,
+    borderRadius: 10,
+    borderWidth: 1,
+    borderColor: _sharedUi.buoyColors.border,
+    padding: 12,
+    alignItems: "center",
+    justifyContent: "center",
+    minHeight: 64
+  },
+  statCardActive: {
+    borderColor: _sharedUi.buoyColors.primary,
+    backgroundColor: _sharedUi.buoyColors.primary + "10"
+  },
+  statValue: {
+    fontSize: 22,
+    fontWeight: "700",
+    fontFamily: "monospace",
+    lineHeight: 26,
+    color: _sharedUi.buoyColors.text
+  },
+  statValueActive: {
+    color: _sharedUi.buoyColors.primary
+  },
+  statLabel: {
+    fontSize: 9,
+    color: _sharedUi.buoyColors.textMuted,
+    marginTop: 4,
+    textTransform: "uppercase",
+    letterSpacing: 0.5,
+    fontWeight: "600"
+  },
+  statLabelActive: {
+    color: _sharedUi.buoyColors.primary
+  },
+  percentBadge: {
+    paddingHorizontal: 8,
+    paddingVertical: 4,
+    borderRadius: 6,
+    borderWidth: 1
+  },
+  percentText: {
+    fontSize: 14,
+    fontWeight: "700",
+    fontFamily: "monospace"
+  }
+});

package/lib/commonjs/env/components/EnvVarRow.js

@@ -0,0 +1,170 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EnvVarRow = EnvVarRow;
+var _reactNative = require("react-native");
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _envTypeDetector = require("../utils/envTypeDetector");
+var _jsxRuntime = require("react/jsx-runtime");
+const getStatusConfig = (status, expectedType) => {
+  switch (status) {
+    case "required_present":
+      return {
+        label: "Valid",
+        color: _sharedUi.buoyColors.success,
+        sublabel: "Required"
+      };
+    case "required_missing":
+      return {
+        label: "Missing",
+        color: _sharedUi.buoyColors.error,
+        sublabel: "Required"
+      };
+    case "required_wrong_value":
+      return {
+        label: "Wrong",
+        color: _sharedUi.buoyColors.warning,
+        sublabel: "Invalid value"
+      };
+    case "required_wrong_type":
+      return {
+        label: "Type Error",
+        color: _sharedUi.buoyColors.info,
+        sublabel: "Wrong type"
+      };
+    case "optional_present":
+      return {
+        label: "Set",
+        color: _sharedUi.buoyColors.textSecondary,
+        sublabel: "Optional"
+      };
+  }
+};
+const formatEnvKey = key => {
+  // Format key similar to React Query: "section > subsection"
+  return key.split("_").join(" › ");
+};
+const formatValue = value => {
+  if (value === undefined || value === null) {
+    return "undefined";
+  }
+  const str = typeof value === "string" ? value : String(value);
+  return str;
+};
+function EnvVarRow({
+  envVar,
+  isExpanded,
+  onPress
+}) {
+  const config = getStatusConfig(envVar.status, envVar.expectedType);
+  const hasValue = envVar.value !== undefined && envVar.value !== null;
+
+  // Format primary text like React Query does: "section › subsection"
+  // For env vars, we'll show the key formatted nicely
+  const keyParts = envVar.key.split("_");
+  const primaryText = keyParts.map(part => part.toLowerCase()).join(" › ");
+
+  // Create expanded content for value and expected value
+  const expandedContent = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+    style: styles.expandedContainer,
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.expandedRow,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.expandedLabel,
+        children: "Value:"
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.expandedValue,
+        numberOfLines: 3,
+        children: formatValue(envVar.value) || "undefined"
+      })]
+    }), envVar.status === "required_wrong_type" && envVar.expectedType && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.expandedRow,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.expandedLabel,
+          children: "Type:"
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.TypeBadge, {
+          type: (0, _envTypeDetector.getEnvVarType)(envVar.value)
+        })]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.expandedRow,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.expandedLabel,
+          children: "Expected:"
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.TypeBadge, {
+          type: envVar.expectedType
+        })]
+      })]
+    }), envVar.status === "required_wrong_value" && envVar.expectedValue && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.expandedRow,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.expandedLabel,
+        children: "Expected:"
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.expandedExpected,
+        children: String(envVar.expectedValue)
+      })]
+    }), envVar.description && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.expandedRow,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.expandedLabel,
+        children: "Info:"
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.expandedDescription,
+        children: envVar.description
+      })]
+    })]
+  });
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.CompactRow, {
+    statusDotColor: config.color,
+    statusLabel: config.label,
+    statusSublabel: config.sublabel,
+    primaryText: primaryText,
+    secondaryText: undefined // Don't show value inline anymore
+    ,
+    expandedContent: expandedContent,
+    isExpanded: isExpanded,
+    expandedGlowColor: config.color,
+    customBadge: envVar.expectedType ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.TypeBadge, {
+      type: envVar.expectedType
+    }) : undefined,
+    showChevron: true,
+    onPress: onPress ? () => onPress(envVar) : undefined
+  });
+}
+const styles = _reactNative.StyleSheet.create({
+  expandedContainer: {
+    gap: 6
+  },
+  expandedRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8
+  },
+  expandedLabel: {
+    fontSize: 10,
+    color: _sharedUi.buoyColors.textMuted,
+    fontWeight: "600",
+    minWidth: 60,
+    fontFamily: "monospace"
+  },
+  expandedValue: {
+    fontSize: 11,
+    color: _sharedUi.buoyColors.textSecondary,
+    fontFamily: "monospace",
+    flex: 1
+  },
+  expandedExpected: {
+    fontSize: 11,
+    color: _sharedUi.buoyColors.warning,
+    fontFamily: "monospace",
+    flex: 1
+  },
+  expandedDescription: {
+    fontSize: 11,
+    color: _sharedUi.buoyColors.textSecondary,
+    flex: 1
+  }
+});