dynim-react 1.0.0

package/README.md

@@ -0,0 +1,447 @@
+# dynim-react
+
+React components, hooks, and providers for visual page building, AI chat, and multi-tenant customization. Built on top of `dynim-core`.
+
+## Installation
+
+```bash
+npm install dynim-react
+# dynim-core is included as a dependency
+```
+
+**Peer Dependencies:**
+- `react` >= 17.0.0
+- `react-dom` >= 17.0.0
+
+## Overview
+
+This package has two main modules:
+
+1. **Builder** - Visual builder integration for editing pages/components with AI chat and code generation
+2. **Inference** - Dynamic loading of tenant-specific customization bundles
+
+## Folder Structure
+
+```
+src/
+├── index.ts                    # Main entry point
+├── builder/
+│   ├── BuilderProvider.tsx     # Visual builder React provider
+│   ├── EditableZone.tsx        # Zone wrappers for customization control
+│   ├── ChatContext.tsx         # Chat state context
+│   ├── useChatbot.ts           # Headless chat hook
+│   ├── MessageList.tsx         # Message display component
+│   └── ChatInput.tsx           # Chat input component
+└── inference/
+    ├── types.ts                # TypeScript definitions
+    ├── sharedContext.ts        # Shared context registration
+    └── InferenceProvider.tsx   # Tenant bundle loader
+```
+
+## Builder Module
+
+### BuilderProvider
+
+Main provider component that integrates the visual builder UI into your app.
+
+```tsx
+import { BuilderProvider, useBuilder } from 'dynim-react';
+
+function App() {
+  return (
+    <BuilderProvider
+      config={{
+        apiBase: 'https://api.example.com',
+        pageId: '/dashboard',
+        sessionToken: jwtToken,
+        onCodeEdit: (edit) => console.log('Code changed:', edit),
+      }}
+      onBuilderReady={(ctx) => console.log('Builder ready!')}
+    >
+      <YourApp />
+    </BuilderProvider>
+  );
+}
+```
+
+**Config Options:**
+
+```tsx
+interface BuilderConfig {
+  apiBase?: string;                                    // Default: 'http://localhost:8080'
+  pageId?: string;                                     // Default: window.location.pathname
+  logo?: string;                                       // Builder UI logo text
+  contentRoot?: HTMLElement;                           // Default: document.body
+  sessionToken?: string;                               // JWT authentication token
+  refreshToken?: string;                               // For token renewal
+  getSession?: () => Promise<{ token: string }>;       // Dynamic token fetching
+  onMessage?: (data: BuilderMessage) => void;          // Chat message callback
+  onError?: (error: Error) => void;                    // Error callback
+  onCodeMessage?: (event: CodeEvent) => void;          // Code generation events
+  onCodeEdit?: (edit: CodeEdit) => void;               // Code edit callback
+}
+```
+
+### useBuilder Hook
+
+Access builder controls from any child component:
+
+```tsx
+function EditorToolbar() {
+  const {
+    // Builder controls
+    enterBuilder,      // () => void - Enter edit mode
+    exitBuilder,       // () => void - Exit without saving
+    saveBuilder,       // () => Promise<void> - Save and exit
+    isBuilderActive,   // boolean - Current edit state
+
+    // Chat
+    sendChat,          // (message: string) => Promise<void>
+    sendElementChat,   // (message: string, element: HTMLElement) => Promise<void>
+
+    // Code generation (Flexcode)
+    sendCode,          // (projectId: string, prompt: string) => Promise<void>
+    saveCode,          // (projectId: string) => Promise<void>
+    abandonCode,       // (projectId: string) => Promise<void>
+    codeEdits,         // CodeEdit[] - Pending code changes
+
+    // Builder instance
+    getBuilder,        // () => Builder - Get underlying builder instance
+  } = useBuilder();
+
+  return (
+    <div>
+      <button onClick={enterBuilder} disabled={isBuilderActive}>
+        Edit Page
+      </button>
+      <button onClick={saveBuilder} disabled={!isBuilderActive}>
+        Save Changes
+      </button>
+    </div>
+  );
+}
+```
+
+### Chat Components
+
+Pre-built chat UI components:
+
+```tsx
+import { ChatProvider, MessageList, ChatInput } from 'dynim-react';
+
+function BuilderChat() {
+  return (
+    <ChatProvider endpoint="/api/chat" apiKey="...">
+      <MessageList showAvatars showTimestamps={false} />
+      <ChatInput placeholder="Ask the builder..." />
+    </ChatProvider>
+  );
+}
+```
+
+### useChatbot Hook
+
+Headless hook for building custom chat UIs:
+
+```tsx
+import { useChatbot } from 'dynim-react';
+
+function CustomChat() {
+  const {
+    messages,      // Message[] - Array of chat messages
+    isLoading,     // boolean - Response being fetched
+    isTyping,      // boolean - AI typing indicator
+    sendMessage,   // (text: string) => Promise<void>
+    clearMessages, // () => void - Clear history
+  } = useChatbot({
+    endpoint: '/api/chat',
+    apiKey: 'your-api-key',
+    onError: (error) => console.error(error),
+  });
+
+  return (
+    <div>
+      {messages.map(msg => (
+        <div key={msg.id} className={msg.role}>
+          {msg.text}
+        </div>
+      ))}
+      <form onSubmit={(e) => {
+        e.preventDefault();
+        sendMessage(e.target.message.value);
+        e.target.reset();
+      }}>
+        <input name="message" disabled={isLoading} />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+**Message Type:**
+
+```tsx
+interface Message {
+  id: string;
+  role: 'user' | 'assistant';
+  text: string;
+  timestamp: Date;
+}
+```
+
+### Zone Components
+
+Control which parts of your UI can be customized in the builder:
+
+```tsx
+import { LockedZone, EditableZone } from 'dynim-react';
+
+function App() {
+  return (
+    <div>
+      <LockedZone>
+        <Navigation />  {/* Protected - cannot be modified */}
+      </LockedZone>
+
+      <main>
+        {/* Editable by default */}
+        <Hero />
+        <Features />
+      </main>
+
+      <LockedZone>
+        <Sidebar>
+          <Logo />  {/* Locked */}
+          <EditableZone>
+            <CustomWidgets />  {/* Editable island inside locked zone */}
+          </EditableZone>
+        </Sidebar>
+      </LockedZone>
+    </div>
+  );
+}
+```
+
+**Zone Props:**
+
+```tsx
+// Custom wrapper element
+<EditableZone as="section" className="content">
+  <Content />
+</EditableZone>
+
+// Aliases
+<NonCustomizable>  {/* Same as LockedZone */}
+<Customizable>     {/* Same as EditableZone */}
+```
+
+- `LockedZone` / `NonCustomizable` - Prevents builder customization (sets `vis="false"`)
+- `EditableZone` / `Customizable` - Creates editable areas (sets `vis="true"`)
+
+## Inference Module
+
+### InferenceProvider
+
+Dynamically loads and renders tenant-specific customization bundles.
+
+```tsx
+import { InferenceProvider } from 'dynim-react';
+
+function App() {
+  const { tenantId } = useAuth();
+
+  return (
+    <InferenceProvider
+      tenantId={tenantId}
+      bundleUrl={(id) => `https://cdn.example.com/bundles/${id}.js`}
+      checkCustomizations={async (id) => {
+        const res = await fetch(`/api/customizations/${id}`);
+        return res.ok;
+      }}
+      loadingComponent={<Spinner />}
+      errorBanner={true}
+      onLoad={(id) => console.log(`Loaded for ${id}`)}
+      onError={(err, id) => console.error(`Failed for ${id}:`, err)}
+    >
+      <BaseApp />
+    </InferenceProvider>
+  );
+}
+```
+
+**Props:**
+
+```tsx
+interface InferenceProviderProps {
+  tenantId: string | null;                              // Current tenant (null = no customization)
+  bundleUrl: string | ((id: string) => string);         // Bundle URL or URL builder
+  bundleToken?: string;                                 // Auth token for bundle fetch
+  checkCustomizations?: (id: string) => Promise<bool>;  // Pre-check if tenant has bundle
+  loadingComponent?: ReactNode;                         // Custom loading UI
+  errorBanner?: boolean | ReactNode;                    // Show errors (default: false)
+  onError?: (error: Error, tenantId: string) => void;
+  onLoad?: (tenantId: string) => void;
+  children: ReactNode;                                  // Fallback/default app
+}
+```
+
+**Loading States:**
+
+`idle` → `checking` → `loading` → `loaded` / `error` / `no-customization`
+
+### Shared Context
+
+Tenant bundles access the host app's React and custom hooks via a shared context on `window.__DYNIM__`:
+
+```tsx
+import { createSharedContext, getSharedContext, isSharedContextReady } from 'dynim-react';
+
+// Register shared context (call once at app initialization)
+createSharedContext({
+  React,
+  ReactDOM,
+  hooks: { useAuth, useTheme, useNotifications },
+  contexts: { AuthContext, ThemeContext },
+  globals: { utils: myUtils },
+});
+
+// Check if ready
+if (isSharedContextReady()) {
+  const ctx = getSharedContext();
+  // ...
+}
+```
+
+**Writing a Tenant Bundle:**
+
+```typescript
+// tenant-bundle.ts
+const { React, ReactDOM, hooks, contexts } = window.__DYNIM__;
+const { useAuth, useTheme } = hooks;
+
+function TenantCustomization() {
+  const { user } = useAuth();
+  const { theme } = useTheme();
+
+  return (
+    <div style={{ background: theme.bg }}>
+      <h1>Welcome, {user.name}!</h1>
+      <p>Custom content for {user.tenantId}</p>
+    </div>
+  );
+}
+
+// Render into the designated root
+const root = document.getElementById('dynim-root');
+ReactDOM.render(<TenantCustomization />, root);
+```
+
+## Architecture
+
+```
+Application
+    │
+    ├── BuilderProvider (visual editing)
+    │   ├── Creates builder instance (dynim-core)
+    │   ├── Manages SSE streaming for chat/code
+    │   ├── Handles drag-and-drop, history, diffs
+    │   └── Exposes useBuilder hook
+    │
+    └── InferenceProvider (tenant customization)
+        ├── Registers global SDK (window.__DYNIM__)
+        ├── Loads tenant bundle script
+        ├── Renders bundle into #dynim-root
+        └── Falls back to children if no customizations
+```
+
+## Exports
+
+```tsx
+// Builder
+export { BuilderProvider, useBuilder } from './builder';
+export { ChatProvider, useChatContext } from './builder';
+export { MessageList, ChatInput, useChatbot } from './builder';
+export { LockedZone, EditableZone, NonCustomizable, Customizable } from './builder';
+
+// Inference
+export { InferenceProvider } from './inference';
+export { createSharedContext, getSharedContext, isSharedContextReady } from './inference';
+
+// Re-exports everything from dynim-core
+export * from 'dynim-core';
+```
+
+## Re-exports from dynim-core
+
+For convenience, `dynim-react` re-exports all of `dynim-core`:
+
+```tsx
+import {
+  // State
+  createState,
+
+  // Clients
+  createClient,
+  createBuilderClient,
+  createCodeClient,
+
+  // Builder
+  createBuilder,
+  createEditorState,
+  createHistoryState,
+  createTreeState,
+  createDiffState,
+
+  // UI
+  createWidget,
+  createOverlays,
+  createFreezeOverlay,
+  createDragEngine,
+  createAIPromptPopover,
+
+  // DOM utilities
+  scanDOM,
+  getStableId,
+  findByStableId,
+  buildElementIdentifier,
+
+  // Classifier
+  createClassifier,
+} from 'dynim-react';
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  // Config
+  BuilderConfig,
+  BuilderContextValue,
+  ChatbotConfig,
+  InferenceProviderProps,
+  DynimSDKConfig,
+
+  // Props
+  ZoneProps,
+  MessageListProps,
+  ChatInputProps,
+
+  // Data
+  Message,
+  ChatState,
+  CodeEdit,
+  CodeEvent,
+  DiffEntry,
+  BuilderMessage,
+
+  // Global
+  DynimGlobal,
+} from 'dynim-react';
+```
+
+## License
+
+MIT

package/dist/builder/BuilderProvider.d.ts

@@ -0,0 +1,99 @@
+/**
+ * BuilderProvider - React integration for the visual builder
+ *
+ * Integrates the visual builder UI (floating bar, drag engine, overlays)
+ * from dynim-core.
+ */
+import { type ReactNode } from 'react';
+import type { BuilderInstance, CodeEdit, CodeEvent, CodeMessage, StyleChange } from 'dynim-core';
+export interface BuilderConfig {
+    apiBase?: string;
+    pageId?: string;
+    logo?: string;
+    contentRoot?: HTMLElement;
+    /** JWT session token for authentication */
+    sessionToken?: string;
+    /** Refresh token for getting new session tokens */
+    refreshToken?: string;
+    /** Function to fetch a new session when current one expires */
+    getSession?: () => Promise<{
+        token: string;
+        refreshToken?: string;
+    }>;
+    onError?: (error: Event | Error) => void;
+    /** Called when the structured code message updates (recommended) */
+    onCodeMessageUpdate?: (message: CodeMessage) => void;
+    /** Called when a code edit is received */
+    onCodeEdit?: (edit: CodeEdit) => void;
+    /** @deprecated Use onCodeMessageUpdate instead */
+    onCodeMessage?: (event: CodeEvent) => void;
+    /** @deprecated No longer needed - BuilderProvider creates internal container */
+    previewContainer?: HTMLElement;
+    /** Function to resolve bundle URL from project ID */
+    getBundleUrl?: (projectId: string) => string | Promise<string>;
+    /** If true, bundles replace children when loaded. If false, uses external previewContainer (default: true) */
+    inPlacePreview?: boolean;
+    /** Whether to auto-apply style changes from code edits (default: true) */
+    autoApplyStyles?: boolean;
+    /** Transition duration for bundle crossfade in ms (default: 300) */
+    previewTransitionDuration?: number;
+    /** Called when a style change is applied */
+    onStyleApplied?: (change: StyleChange, elements: Element[]) => void;
+    /** Called when bundle starts loading */
+    onBundleLoadStart?: (bundleUrl: string) => void;
+    /** Called when bundle finishes loading */
+    onBundleLoadComplete?: (bundleUrl: string) => void;
+}
+export interface BuilderContextValue {
+    enterBuilder: () => void;
+    exitBuilder: () => void;
+    saveBuilder: () => Promise<void>;
+    isBuilderActive: boolean;
+    getBuilder: () => BuilderInstance | null;
+    sendCode: (query: string) => Promise<void>;
+    saveCode: () => Promise<void>;
+    abandonCode: () => Promise<void>;
+    warmCache: () => Promise<void>;
+    /** Current structured code message state */
+    codeMessage: CodeMessage;
+    /** Reset code message state */
+    resetCodeMessage: () => void;
+    /** @deprecated Use codeMessage.edits instead */
+    codeEdits: CodeEdit[];
+    /** Load a bundle into the preview container */
+    loadBundle: (bundleUrl: string) => Promise<void>;
+    /** Load bundle for a project (uses getBundleUrl from config) */
+    loadProjectBundle: (projectId: string) => Promise<void>;
+    /** Load saved (permanent) bundle for a project */
+    loadSavedBundle: (projectId: string) => Promise<void>;
+    /** Load temp bundle for a project (AI edits preview) */
+    loadTempBundle: (projectId: string) => Promise<void>;
+    /** Apply styles directly to preview DOM */
+    applyStyles: (selector: string, styles: Record<string, string>) => void;
+    /** Apply className to preview DOM */
+    applyClassName: (selector: string, className: string) => void;
+    /** Toggle CSS classes on preview DOM */
+    toggleClasses: (selector: string, add: string[], remove: string[]) => void;
+    /** Check if bundle manager is available */
+    hasBundleManager: boolean;
+    /** Check if a bundle is currently loaded */
+    isBundleLoaded: boolean;
+    /** Check if bundle is loading */
+    isBundleLoading: boolean;
+    /** Unload current bundle */
+    unloadBundle: () => void;
+}
+export interface BuilderProviderProps {
+    children: ReactNode;
+    config?: BuilderConfig;
+    onBuilderReady?: (context: BuilderContextValue) => void;
+}
+/**
+ * BuilderProvider - Wraps your app with builder support
+ */
+export declare function BuilderProvider({ children, config, onBuilderReady, }: BuilderProviderProps): JSX.Element;
+/**
+ * Hook to access builder functionality
+ */
+export declare function useBuilder(): BuilderContextValue;
+//# sourceMappingURL=BuilderProvider.d.ts.map

package/dist/builder/BuilderProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuilderProvider.d.ts","sourceRoot":"","sources":["../../src/builder/BuilderProvider.tsx"],"names":[],"mappings":"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"}