@launchdarkly/toolbar 0.10.1 → 0.11.1-beta.1

package/README.md

@@ -1,184 +1,201 @@
 # LaunchDarkly Toolbar
 
-> ⚠️ **Warning:** This package is currently not ready for production use and is considered unsupported. Features, APIs, and behavior may change without notice.
+> 🚧 **Beta:** This package is currently in beta. While functional and tested, APIs may still evolve based on feedback. Please report any issues or suggestions!
 
-A React component that provides a developer-friendly toolbar for interacting with LaunchDarkly during development.
+A React component that provides a developer-friendly toolbar for interacting with LaunchDarkly during development. The toolbar supports two modes:
+
+- **SDK Mode**: Integrate with your LaunchDarkly SDK for local flag overrides and testing (recommended)
+- **Dev Server Mode**: Connect to a LaunchDarkly CLI dev server for flag browsing and real-time updates
 
 ## Installation
 
 ```bash
-npm install @launchdarkly/toolbar
-# or
-yarn add @launchdarkly/toolbar
-# or
-pnpm add @launchdarkly/toolbar
-```
+# npm
+npm install @launchdarkly/toolbar@next
 
-1. **Import the component and styles:**
+# yarn
+yarn add @launchdarkly/toolbar@next
 
-```tsx
-import { LaunchDarklyToolbar } from '@launchdarkly/toolbar';
+# pnpm
+pnpm add @launchdarkly/toolbar@next
 ```
 
-2. **Add the toolbar to your app:**
+## Quick Start
+
+**SDK Mode** (recommended - integrates with your LaunchDarkly SDK):
 
 ```tsx
+import { useEffect, useState } from 'react';
+import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
+import { LaunchDarklyToolbar, FlagOverridePlugin } from '@launchdarkly/toolbar';
+
+// Create the plugin instance
+const flagOverridePlugin = new FlagOverridePlugin();
+
 function App() {
-  return (
-    <div>
-      {/* Your app content */}
-      <h1>My App</h1>
+  const [LDProvider, setLDProvider] = useState(null);
+
+  useEffect(() => {
+    const initializeLD = async () => {
+      const Provider = await asyncWithLDProvider({
+        clientSideID: 'your-client-side-id',
+        context: { key: 'user-key', name: 'User Name' },
+        options: {
+          // Pass the plugin to the SDK
+          plugins: [flagOverridePlugin],
+        },
+      });
+      setLDProvider(() => Provider);
+    };
+
+    initializeLD();
+  }, []);
+
+  if (!LDProvider) {
+    return <div>Loading LaunchDarkly...</div>;
+  }
 
-      {/* LaunchDarkly Toolbar */}
-      <LaunchDarklyToolbar devServerUrl="http://localhost:8765" position="right" />
-    </div>
+  return (
+    <LDProvider>
+      <div>
+        <h1>My App</h1>
+        {/* Pass the same plugin instance to the toolbar */}
+        <LaunchDarklyToolbar flagOverridePlugin={flagOverridePlugin} />
+      </div>
+    </LDProvider>
   );
 }
 ```
 
-3. **Start your LaunchDarkly dev server:**
-
-```bash
-# Make sure your LaunchDarkly dev server is running
-# The toolbar will automatically connect and display your flags
-```
-
-## Props
-
-| Prop           | Type                | Default                   | Description                                   |
-| -------------- | ------------------- | ------------------------- | --------------------------------------------- |
-| `devServerUrl` | `string`            | `"http://localhost:8765"` | URL of your LaunchDarkly development server   |
-| `position`     | `"left" \| "right"` | `"right"`                 | Position of the toolbar on screen             |
-| `projectKey`   | `string`            | `undefined`               | Optional project key for multi-project setups |
-
-## Usage Examples
-
-### Basic Usage
+**Dev Server Mode** (connects to LaunchDarkly CLI dev server):
 
 ```tsx
 import { LaunchDarklyToolbar } from '@launchdarkly/toolbar';
 
 function App() {
   return (
-    <>
-      <main>
-        <h1>My Application</h1>
-        {/* Your app content */}
-      </main>
-
-      <LaunchDarklyToolbar />
-    </>
+    <div>
+      <h1>My App</h1>
+      <LaunchDarklyToolbar devServerUrl="http://localhost:8765" />
+    </div>
   );
 }
 ```
 
-### Custom Configuration
+## Props
 
-```tsx
-import { LaunchDarklyToolbar } from '@launchdarkly/toolbar';
+| Prop                 | Type                  | Default     | Description                                                               |
+| -------------------- | --------------------- | ----------- | ------------------------------------------------------------------------- |
+| `flagOverridePlugin` | `IFlagOverridePlugin` | `undefined` | Flag override plugin for SDK Mode. Enables flag overrides and testing     |
+| `devServerUrl`       | `string` (optional)   | `undefined` | URL of your LaunchDarkly dev server. If provided, enables Dev Server Mode |
+| `position`           | `"left" \| "right"`   | `"right"`   | Position of the toolbar on screen                                         |
+| `projectKey`         | `string` (optional)   | `undefined` | Optional project key for multi-project setups (Dev Server Mode only)      |
+| `pollIntervalInMs`   | `number` (optional)   | `5000`      | Polling interval for dev server updates (Dev Server Mode only)            |
 
-function App() {
-  return (
-    <>
-      <main>{/* Your app content */}</main>
+## Configuration
 
-      <LaunchDarklyToolbar devServerUrl="http://localhost:3001" position="left" projectKey="my-project" />
-    </>
-  );
-}
-```
+### Mode Determination
 
-### Usage
+The toolbar automatically determines its mode:
 
-```tsx
-import { LaunchDarklyToolbar } from '@launchdarkly/toolbar';
+- **SDK Mode**: When `flagOverridePlugin` is provided (recommended for most use cases)
+- **Dev Server Mode**: When `devServerUrl` is provided
 
-function App() {
-  return (
-    <>
-      <main>{/* Your app content */}</main>
+### Available Features by Mode
 
-      {/* Only show toolbar in development */}
-      {process.env.NODE_ENV === 'development' && <LaunchDarklyToolbar />}
-    </>
-  );
-}
-```
+| Mode                | Available Tabs      |
+| ------------------- | ------------------- |
+| **SDK Mode**        | Overrides, Settings |
+| **Dev Server Mode** | Flags, Settings     |
 
-## How It Works
+## Setup
 
-The LaunchDarkly Toolbar connects to your LaunchDarkly development server to provide real-time flag management capabilities:
+### SDK Mode (Recommended)
 
-1. **Automatic Discovery** - The toolbar automatically discovers available flags from your dev server
-2. **Real-time Updates** - Flag changes are reflected immediately in your application
-3. **Event Stream** - Monitor flag evaluation events as they happen
-4. **Search & Filter** - Quickly find flags using the built-in search functionality
+SDK Mode integrates directly with your LaunchDarkly client, allowing you to:
 
-## Toolbar Visibility Control
+- Override flag values locally without affecting other users
+- Test different flag variations instantly
+- Work offline or with any LaunchDarkly environment
+- Maintain full type safety with your existing SDK setup
 
-The toolbar includes built-in visibility controls that allow developers to easily show/hide the toolbar during development. When the toolbar loads, it automatically exposes a global API on the browser's window object.
+Setup is straightforward:
 
-### Global API
+1. Create a `FlagOverridePlugin` instance
+2. Pass the plugin to your LaunchDarkly SDK's `plugins` array
+3. Pass the same plugin instance to the toolbar component
+4. Wrap your app with the LaunchDarkly provider
 
-The toolbar provides a `window.ldToolbar` API with the following methods:
+```tsx
+import { useEffect, useState } from 'react';
+import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
+import { LaunchDarklyToolbar, FlagOverridePlugin } from '@launchdarkly/toolbar';
 
-```javascript
-// Enable the toolbar (removes it from localStorage and shows the toolbar)
-window.ldToolbar.enable();
+// Create the plugin instance (outside component to avoid recreating)
+const flagOverridePlugin = new FlagOverridePlugin({
+  storageNamespace: 'my-app-overrides', // Optional: customize storage key
+});
 
-// Disable the toolbar (saves preference to localStorage and hides the toolbar)
-window.ldToolbar.disable();
+function App() {
+  const [LDProvider, setLDProvider] = useState(null);
 
-// Toggle the toolbar visibility
-window.ldToolbar.toggle();
+  useEffect(() => {
+    const initializeLD = async () => {
+      const Provider = await asyncWithLDProvider({
+        clientSideID: 'your-client-side-id',
+        context: { key: 'user-key', name: 'User Name' },
+        options: {
+          plugins: [flagOverridePlugin], // Add plugin to SDK
+        },
+      });
+      setLDProvider(() => Provider);
+    };
+
+    initializeLD();
+  }, []);
 
-// Check current status (returns true if enabled, false if disabled)
-window.ldToolbar.status();
+  if (!LDProvider) return <div>Loading...</div>;
+
+  return (
+    <LDProvider>
+      <YourAppContent />
+      <LaunchDarklyToolbar flagOverridePlugin={flagOverridePlugin} />
+    </LDProvider>
+  );
+}
 ```
 
-### Console Information
+### Dev Server Mode
 
-When the toolbar loads, you'll see helpful console output showing the available commands:
+For teams using the LaunchDarkly CLI dev server, start it with CORS enabled:
 
-```
-🔧 LaunchDarkly toolbar controls available:
-   window.ldToolbar.enable() - Enable toolbar
-   window.ldToolbar.disable() - Disable toolbar
-   window.ldToolbar.toggle() - Toggle toolbar
-   window.ldToolbar.status() - Check current status
+```bash
+ldcli dev-server start --project your-project --cors-enabled true
 ```
 
-### Persistent State
+Then connect the toolbar:
+
+```tsx
+<LaunchDarklyToolbar devServerUrl="http://localhost:8765" />
+```
 
-The toolbar's visibility state is automatically saved to localStorage and persists across browser sessions. The state is also synchronized across multiple tabs of the same application.
+## Visibility Control
 
-### Usage Examples
+The toolbar provides a global API for show/hide control:
 
 ```javascript
-// Hide the toolbar for focused development
-window.ldToolbar.disable();
-// Console: ✅ LaunchDarkly toolbar disabled.
+// Toggle visibility
+window.ldToolbar.toggle();
 
-// Show the toolbar when you need it
+// Enable/disable explicitly
 window.ldToolbar.enable();
-// Console: ✅ LaunchDarkly toolbar enabled.
-
-// Check if the toolbar is currently visible
-const isEnabled = window.ldToolbar.status();
-// Console: LaunchDarkly toolbar is currently: ✅ ENABLED
-// Returns: true
+window.ldToolbar.disable();
 
-// Quick toggle
-window.ldToolbar.toggle();
+// Check current status
+window.ldToolbar.status(); // returns true/false
 ```
 
-## Development Server Setup
-
-The toolbar requires a LaunchDarkly CLI dev-server to be running with CORS enabled.
-
-```bash
-ldcli dev-server start --project demo-project --cors-enabled true
-```
+Visibility preferences are automatically saved to localStorage.
 
 ## TypeScript
 
@@ -186,12 +203,8 @@ The package includes complete TypeScript definitions. No additional `@types` pac
 
 ```tsx
 import type { LaunchDarklyToolbarProps } from '@launchdarkly/toolbar';
-
-const toolbarConfig: LaunchDarklyToolbarProps = {
-  devServerUrl: 'http://localhost:8765',
-  position: 'right',
-  projectKey: 'my-project',
-};
 ```
 
+---
+
 Built with ❤️ for the LaunchDarkly developer community.

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 import './globals.css';
 export { LaunchDarklyToolbar } from './ui/Toolbar/LaunchDarklyToolbar';
 export type { LaunchDarklyToolbarProps } from './ui/Toolbar/LaunchDarklyToolbar';
+export type { IFlagOverridePlugin } from './types/plugin';
+export { FlagOverridePlugin } from './plugins';
+export type { FlagOverridePluginConfig } from './plugins';