Modern state management following TanStack/Zustand patterns. Minimal base styles for full developer control

Author: josephfusco

examples/vanilla/toolbar-demo/example-app/index.html

@@ -29,7 +29,7 @@ <h2>Try This</h2>
         <li>Click "Login" to authenticate with WordPress</li>
         <li>Click "Fetch Posts" to load posts from WordPress</li>
         <li>Click a post to view toolbar controls</li>
-        <li>Use the toolbar at the bottom to preview or edit</li>
+        <li>Check the state below to see how it updates</li>
       </ol>
     </section>
   </main>

examples/vanilla/toolbar-demo/example-app/src/main.js

@@ -22,9 +22,7 @@ const renderer = new VanillaRenderer(toolbar, 'toolbar');
 // Register Custom Nodes
 // ============================================================================
 
-// Simple home button
 toolbar.register('home', 'Home', () => {
-  console.log('Navigate to home');
   window.location.href = '/';
 });
 

packages/toolbar/README.md

@@ -7,10 +7,10 @@ A lightweight, performant toolbar for headless WordPress. Works with any JavaScr
 ## Features
 
 - 🎯 **Framework Agnostic** - Works with React, Vue, Svelte, or vanilla JavaScript
-- ⚡ **Zero Dependencies** - Lightweight and fast
+- ⚡ **Zero Dependencies** - Core library has no dependencies
 - 🔒 **Type Safe** - Full TypeScript support
-- 🎨 **Themeable** - CSS custom properties for styling
-- 🌓 **Dark Mode** - Automatic support
+- 🪝 **React Hooks** - First-class React support with hooks
+- 🎨 **Headless UI** - Full control over rendering and styling
 
 ## Installation
 
@@ -20,28 +20,55 @@ npm install @wpengine/hwp-toolbar
 
 ## Quick Start
 
+### Vanilla JavaScript
+
 ```javascript
 import { Toolbar, VanillaRenderer } from '@wpengine/hwp-toolbar';
 import '@wpengine/hwp-toolbar/styles';
 
-// Create toolbar
 const toolbar = new Toolbar({
   onPreviewChange: (enabled) => {
     console.log('Preview mode:', enabled);
   }
 });
 
-// Set WordPress context
 toolbar.setWordPressContext({
   user: { id: 1, name: 'Admin' },
   site: { url: 'https://example.com', adminUrl: 'https://example.com/wp-admin' },
   post: { id: 123, title: 'Hello World', type: 'post', status: 'draft', slug: 'hello-world' }
 });
 
-// Render
 const renderer = new VanillaRenderer(toolbar, 'toolbar');
 ```
 
+### React (Recommended)
+
+```tsx
+import { Toolbar } from '@wpengine/hwp-toolbar';
+import { useToolbar } from '@wpengine/hwp-toolbar/react';
+
+const toolbar = new Toolbar({
+  onPreviewChange: (enabled) => {
+    console.log('Preview mode:', enabled);
+  }
+});
+
+function MyToolbar() {
+  const { state, nodes } = useToolbar(toolbar);
+
+  return (
+    <div className="toolbar">
+      {nodes.map(node => (
+        <button key={node.id} onClick={node.onClick}>
+          {typeof node.label === 'function' ? node.label() : node.label}
+        </button>
+      ))}
+      {state.user && <span>User: {state.user.name}</span>}
+    </div>
+  );
+}
+```
+
 ## API
 
 ### Toolbar
@@ -122,34 +149,57 @@ Available variables:
 - `--hwp-toolbar-primary-hover` - Primary button hover
 - And more...
 
-## Framework Examples
+## React Hooks API
+
+### `useToolbar(toolbar)`
 
-### React
+Returns both state and nodes in a single hook:
 
 ```tsx
-import { useEffect, useRef } from 'react';
-import { Toolbar, VanillaRenderer } from '@wpengine/hwp-toolbar';
+import { useToolbar } from '@wpengine/hwp-toolbar/react';
+
+function MyToolbar() {
+  const { state, nodes } = useToolbar(toolbar);
+  // Full control over rendering
+}
+```
+
+### `useToolbarState(toolbar)`
 
-function WordPressToolbar({ user, post, site }) {
-  const ref = useRef<HTMLDivElement>(null);
+Subscribe to toolbar state only:
 
-  useEffect(() => {
-    if (!ref.current) return;
+```tsx
+import { useToolbarState } from '@wpengine/hwp-toolbar/react';
+
+function UserDisplay() {
+  const state = useToolbarState(toolbar);
+  return <div>{state.user?.name}</div>;
+}
+```
 
-    const toolbar = new Toolbar();
-    toolbar.setWordPressContext({ user, post, site });
-    const renderer = new VanillaRenderer(toolbar, ref.current);
+### `useToolbarNodes(toolbar)`
 
-    return () => {
-      renderer.destroy();
-      toolbar.destroy();
-    };
-  }, [user, post, site]);
+Subscribe to visible nodes only:
 
-  return <div ref={ref} />;
+```tsx
+import { useToolbarNodes } from '@wpengine/hwp-toolbar/react';
+
+function ToolbarButtons() {
+  const nodes = useToolbarNodes(toolbar);
+  return (
+    <>
+      {nodes.map(node => (
+        <button key={node.id} onClick={node.onClick}>
+          {typeof node.label === 'function' ? node.label() : node.label}
+        </button>
+      ))}
+    </>
+  );
 }
 ```
 
+## Framework Examples
+
 ### Vue
 
 ```vue

packages/toolbar/package.json

@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
     "./styles": "./src/toolbar.css"
   },
   "files": [
@@ -31,7 +35,17 @@
   ],
   "author": "WP Engine",
   "license": "BSD-0-Clause",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
     "typescript": "^5.8.3"
   },
   "engines": {