@bravostudioai/react 0.1.28 → 0.1.30

package/README.md

@@ -0,0 +1,589 @@
+# @bravostudioai/react
+
+> Stream your Figma designs directly into production-ready, type-safe React components for your MCP apps.
+
+[![npm version](https://img.shields.io/npm/v/@bravostudioai/react.svg)](https://www.npmjs.com/package/@bravostudioai/react)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18%2B%20%7C%2019%2B-blue.svg)](https://reactjs.org/)
+
+**The Figma → React Pipeline:**
+- 🎨 Design in Figma → Stream to typed React components
+- 🤖 Perfect for MCP (Model Context Protocol) apps
+- 🔒 100% TypeScript with full IntelliSense support
+- 🚀 Zero configuration, instant productivity
+- 📝 Auto-generated documentation for every component
+- 🎯 Human-readable prop names, not cryptic IDs
+
+**At a Glance:**
+
+| Feature | Included |
+|---------|----------|
+| TypeScript Interfaces | ✅ Yes |
+| Form Handling | ✅ Yes |
+| Event Handlers | ✅ Yes |
+| List/Array Props | ✅ Yes |
+| Dropdown Controls | ✅ Yes |
+| Auto Documentation | ✅ Yes |
+| Production Bundles | ✅ Yes |
+| Live Updates | ✅ Yes (via Pusher) |
+
+## Table of Contents
+
+- [What is Bravo Studio AI?](#what-is-bravo-studio-ai)
+- [Perfect For](#perfect-for)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [What Gets Generated](#what-gets-generated)
+- [Real-World Examples](#real-world-examples)
+- [How It Works](#how-it-works)
+- [CLI Commands](#cli-commands)
+- [Advanced Features](#advanced-features)
+- [Package Exports](#package-exports)
+- [Troubleshooting](#troubleshooting)
+- [Support](#support)
+
+## Why This Matters
+
+Stop manually translating Figma designs into code. Stop writing boilerplate. Stop maintaining prop interfaces that fall out of sync with your designs.
+
+With `@bravostudioai/react`, you design in Figma and Bravo Studio AI streams them into:
+
+- **Type-safe React components** with full TypeScript interfaces
+- **Intelligent prop detection** that understands your data bindings, forms, buttons, and interactive elements
+- **Human-readable APIs** with clean, semantic prop names (not cryptic IDs)
+- **Automatic event handlers** for clicks, form submissions, and state changes
+- **Self-documenting code** with README files for every component
+- **Zero manual configuration** - the generator understands your design intent
+
+## What is Bravo Studio AI?
+
+**Bravo Studio AI** is a Figma-to-React pipeline that transforms your designs into production-ready components. Design in Figma, and Bravo Studio AI automatically generates type-safe React components with intelligent prop detection, form handling, and event routing.
+
+### The Perfect MCP Companion
+
+This package is optimized for **MCP (Model Context Protocol) applications**, where AI agents need to interact with real, functional UI components. By streaming Figma designs into typed React components, you can:
+
+- Rapidly prototype AI-powered interfaces
+- Let designers iterate without code changes
+- Build MCP apps with production-ready UI in minutes
+- Maintain type safety across your entire AI app stack
+
+## Perfect For
+
+✅ **MCP app developers** building AI-powered applications with real UI
+✅ **Design teams** who want to iterate in Figma and see changes instantly
+✅ **Full-stack developers** building prototypes or MVPs at lightning speed
+✅ **Product teams** validating designs with real functionality
+✅ **Agencies** shipping client projects with tight deadlines
+✅ **Startups** optimizing for speed without sacrificing code quality
+
+**Not ideal for:**
+❌ Projects without Figma designs processed through Bravo Studio AI
+❌ Teams needing 100% custom, hand-coded components
+
+## Installation
+
+```bash
+npm install @bravostudioai/react
+```
+
+**Requirements:**
+- Node.js 16+
+- React 18.2.0+ or 19.0.0+
+- TypeScript (recommended)
+
+## Quick Start
+
+### The Figma → React Workflow
+
+1. **Design in Figma** - Create your interface with your team
+2. **Process through Bravo Studio AI** - Your designs get app/page IDs
+3. **Generate React components** - Stream them into your codebase
+4. **Use in your MCP app** - Import and use with full type safety
+
+### Generate Components from Your Bravo Studio AI App
+
+```bash
+# Generate all pages from an app
+npx @bravostudioai/react generate <appId> ./src/components
+
+# Generate a specific page
+npx @bravostudioai/react generate <appId> <pageId> ./src/components
+```
+
+This creates a folder structure like:
+
+```
+src/components/
+  YourApp/
+    PageName/
+      index.tsx       # Type-safe React component
+      README.md       # Complete documentation
+```
+
+### Use Your Generated Component
+
+```tsx
+import { PageName } from './components/YourApp/PageName';
+
+function MCPApp() {
+  return (
+    <PageName
+      headline="Welcome to our app"
+      items={[
+        { title: "Item 1", image: "https://..." },
+        { title: "Item 2", image: "https://..." }
+      ]}
+      onSubmitClick={() => console.log('Submitted!')}
+    />
+  );
+}
+```
+
+That's it. No configuration files. No manual prop mapping. Just clean, typed React components streamed from Figma.
+
+## What Gets Generated
+
+### 1. Type-Safe Component Interfaces
+
+Every data binding, form input, and interactive element in your design becomes a typed prop:
+
+```typescript
+export interface SalaryCalculatorProps {
+  // Data bindings from your design
+  estimatedCost?: string;
+
+  // Dropdown controls
+  contractType?: string;
+  contractTypeOptions?: Array<string | { value: string; label: string }>;
+  onContractTypeChange?: (value: string) => void;
+
+  // Button actions
+  onBookButtonClick?: () => void;
+}
+```
+
+### 2. Smart List/Repeater Support
+
+Repeating containers become typed array props:
+
+```typescript
+export interface TimelineItem {
+  title: string;
+  description: string;
+  image: string;
+}
+
+export interface PageProps {
+  timeline: TimelineItem[];
+  timelineCurrentIndex?: number;
+  onTimelineIndexChange?: (index: number) => void;
+}
+```
+
+Use it like this:
+
+```tsx
+<Page
+  timeline={[
+    { title: "Step 1", description: "...", image: "..." },
+    { title: "Step 2", description: "...", image: "..." }
+  ]}
+  timelineCurrentIndex={currentSlide}
+  onTimelineIndexChange={setCurrentSlide}
+/>
+```
+
+### 3. Complete Form Handling
+
+Forms get typed interfaces and submission callbacks:
+
+```typescript
+export interface ContactFormData {
+  name: string;
+  email: string;
+  message: string;
+}
+
+export interface PageProps {
+  onContactFormSubmit?: (formData: ContactFormData) => void;
+}
+```
+
+Your form handler receives clean, typed data:
+
+```tsx
+<Page
+  onContactFormSubmit={(data) => {
+    console.log(data.name);    // Type-safe!
+    console.log(data.email);   // Type-safe!
+    console.log(data.message); // Type-safe!
+  }}
+/>
+```
+
+### 4. Comprehensive Documentation
+
+Every component includes a README with:
+
+- Complete prop documentation
+- Type information for every prop
+- Usage examples
+- Component metadata (App ID, Page ID)
+
+## Real-World Examples
+
+### Example 1: Interactive Salary Calculator
+
+A salary calculator with multiple dropdowns and a submit button:
+
+```typescript
+export interface DeelSalaryCalculatorProps {
+  estimatedCost?: string;
+
+  // Three interconnected dropdowns
+  contractTypeSelectInput?: string;
+  contractTypeSelectInputOptions?: Array<string | { value: string; label: string }>;
+  onContractTypeSelectInputChange?: (value: string) => void;
+
+  contractCountrySelectInput?: string;
+  contractCountrySelectInputOptions?: Array<string | { value: string; label: string }>;
+  onContractCountrySelectInputChange?: (value: string) => void;
+
+  contractSalarySelectInput?: string;
+  contractSalarySelectInputOptions?: Array<string | { value: string; label: string }>;
+  onContractSalarySelectInputChange?: (value: string) => void;
+
+  onBookButtonClick?: () => void;
+}
+```
+
+**Using it in your app:**
+
+```tsx
+function SalaryCalculator() {
+  const [contractType, setContractType] = useState('full-time');
+  const [country, setCountry] = useState('US');
+  const [salary, setSalary] = useState('100000');
+
+  return (
+    <DeelSalaryCalculator
+      contractTypeSelectInput={contractType}
+      contractTypeSelectInputOptions={['full-time', 'contractor', 'part-time']}
+      onContractTypeSelectInputChange={setContractType}
+      contractCountrySelectInput={country}
+      contractCountrySelectInputOptions={['US', 'UK', 'CA', 'AU']}
+      onContractCountrySelectInputChange={setCountry}
+      contractSalarySelectInput={salary}
+      contractSalarySelectInputOptions={['50000', '75000', '100000', '150000']}
+      onContractSalarySelectInputChange={setSalary}
+      onBookButtonClick={() => console.log('Booking consultation')}
+    />
+  );
+}
+```
+
+### Example 2: Content Sections with Data Bindings
+
+A simple layout with text content:
+
+```typescript
+export interface ContentSectionProps {
+  headline?: string;
+  topline?: string;
+  line1?: string;
+  line2?: string;
+}
+```
+
+**Using it in your app:**
+
+```tsx
+<ContentSection
+  headline="Transform Your Business"
+  topline="Introducing Our New Platform"
+  line1="Built for modern teams"
+  line2="Scales with your growth"
+/>
+```
+
+Simple, clean props that map directly to your design's data bindings.
+
+## How It Works
+
+Bravo Studio AI processes your Figma designs and the generator:
+
+1. **Detects data bindings** - Components tagged in Figma become typed props
+2. **Identifies repeating containers** - Lists and sliders become array props with typed items
+3. **Finds forms** - Input groups become typed form data interfaces
+4. **Discovers interactive elements** - Buttons, selects, and inputs get event handlers
+5. **Generates human-readable names** - Component names become `headline`, not `component_01ABC123`
+6. **Streams updates** - Optional live updates when Figma designs change
+
+## CLI Commands
+
+### Generate Components
+
+```bash
+# Generate all pages from an app
+npx @bravostudioai/react generate <appId> <outputPath>
+
+# Generate a specific page
+npx @bravostudioai/react generate <appId> <pageId> <outputPath>
+
+# Generate with bundled production data (offline mode)
+npx @bravostudioai/react generate <appId> <pageId> <outputPath> --production
+```
+
+### Download Raw Data
+
+```bash
+# Download page data for inspection
+npx @bravostudioai/react download <appId> <pageId> <targetPath>
+```
+
+## Environment Variables
+
+Configure the Bravo Studio AI API endpoint:
+
+```bash
+APPS_SERVICE_URL=https://your-custom-endpoint.com
+```
+
+Or use in your `.env` file:
+
+```env
+VITE_APPS_SERVICE_URL=https://your-custom-endpoint.com
+```
+
+## Advanced Features
+
+### Controlled vs Uncontrolled Components
+
+Sliders and repeating containers support both modes:
+
+```tsx
+// Uncontrolled (component manages its own state)
+<Page items={myItems} />
+
+// Controlled (you control the current slide)
+<Page
+  items={myItems}
+  itemsCurrentIndex={currentIndex}
+  onItemsIndexChange={setCurrentIndex}
+/>
+```
+
+### Production Mode
+
+Bundle your app/page definitions directly into components for offline usage:
+
+```bash
+npx @bravostudioai/react generate <appId> <pageId> ./src/components --production
+```
+
+This creates a `data.json` file with all necessary data baked in.
+
+### Page Metadata
+
+Every component exports metadata about the original design:
+
+```typescript
+export const PageMeta = {
+  width: 375,
+  height: 812,
+  aspectRatio: 0.46,
+};
+```
+
+Use this for responsive layouts or aspect ratio containers.
+
+## Package Exports
+
+```typescript
+// Main component
+import { EncoreApp } from '@bravostudioai/react';
+
+// All components
+import * from '@bravostudioai/react/components';
+
+// Hooks
+import { useFontLoader } from '@bravostudioai/react/hooks/useFontLoader';
+import { usePusherUpdates } from '@bravostudioai/react/hooks/usePusherUpdates';
+
+// State management
+import { useEncoreState } from '@bravostudioai/react/stores/useEncoreState';
+
+// Version info
+import { VERSION } from '@bravostudioai/react/version';
+```
+
+## TypeScript Support
+
+Full TypeScript support out of the box. Every generated component includes:
+
+- Exported interfaces for component props
+- Exported interfaces for list item types
+- Exported interfaces for form data
+- Complete type safety for all callbacks
+
+## Requirements
+
+- React 18.2.0+ or 19.0.0+
+- React DOM 18.2.0+ or 19.0.0+
+- TypeScript (recommended but not required)
+
+## Developer Experience
+
+This isn't just code generation - it's a complete Figma → React pipeline:
+
+1. **Design in Figma** - Work with your design team in their native tool
+2. **Process through Bravo Studio AI** - Designs get structured and tagged
+3. **Run the generator** - One command streams your components
+4. **Import and use** - Type-safe components with IntelliSense support
+5. **Iterate quickly** - Regenerate anytime Figma designs change
+
+The generated code is clean, readable, and maintainable. You can read it, understand it, and even modify it if needed.
+
+### Why This Matters for MCP Apps
+
+MCP applications need real UI components that AI agents can reason about and manipulate. By streaming Figma designs into typed React components, you get:
+
+- **Type safety** - AI agents work with strongly-typed interfaces
+- **Rapid iteration** - Designers update Figma, you regenerate
+- **Production quality** - Not prototypes, but real components
+- **Developer-friendly** - Clean code that developers can read and extend
+
+## Example Output
+
+Here's what the generator creates for a real-world salary calculator:
+
+**Generated TypeScript Interface:**
+```typescript
+export interface DeelSalaryCalculatorProps {
+  estimatedCost?: string;
+  contractTypeSelectInput?: string;
+  contractTypeSelectInputOptions?: Array<string | { value: string; label: string }>;
+  onContractTypeSelectInputChange?: (value: string) => void;
+  // ... and more typed props
+}
+```
+
+**Generated Component:**
+```typescript
+export function DeelSalaryCalculator(props: DeelSalaryCalculatorProps) {
+  const handleAction = (payload: any) => {
+    // Automatically generated event routing
+    if (action?.action === "select-change") {
+      if (nodeId === "..." && props.onContractTypeSelectInputChange) {
+        props.onContractTypeSelectInputChange(value);
+        return;
+      }
+    }
+  };
+
+  return (
+    <EncoreApp
+      appId="..."
+      pageId="..."
+      data={{ /* auto-mapped props */ }}
+      onAction={handleAction}
+    />
+  );
+}
+```
+
+**Generated README.md:**
+Complete documentation with prop descriptions, types, and usage examples.
+
+## Why Developers Love This
+
+**"Figma to code in seconds, not days"**
+Your designers iterate in Figma while you work with production-ready components. No translation layer.
+
+**"Perfect for MCP apps"**
+AI agents need typed interfaces. This gives you exactly that, streamed from design files.
+
+**"Type safety everywhere"**
+Catch errors at compile time, not runtime. IntelliSense shows you every available prop.
+
+**"Self-documenting components"**
+Every component includes documentation. No need to ask "what props does this take?"
+
+**"Zero configuration"**
+No webpack configs, no babel plugins, no setup guides. Just `npm install` and `generate`.
+
+**"Actually readable code"**
+The generated code looks like code you'd write by hand. Clean, idiomatic React.
+
+## Troubleshooting
+
+### Common Issues
+
+**Q: The generated component shows "Failed to load"**
+- Ensure your `appId` and `pageId` are correct
+- Check that you have network access to the Bravo Studio AI API
+- For offline use, use `--production` flag during generation
+
+**Q: TypeScript errors in generated code**
+- Make sure you have `@types/react` installed
+- Verify your TypeScript version is 5.0+
+- Try regenerating the component with the latest package version
+
+**Q: Props not updating the component**
+- Remember that data bindings need to be properly tagged in your Figma design
+- Check the generated README.md for the exact prop names
+- Verify the component is receiving props correctly using React DevTools
+
+**Q: How do I get my App ID and Page ID?**
+- Contact your Bravo Studio AI team for access credentials
+- IDs are provided when your Figma designs are processed through Bravo Studio AI
+
+**Q: Can I use this with regular Figma files?**
+- Figma files must be processed through Bravo Studio AI first
+- This adds the necessary metadata and structure for component generation
+
+### Best Practices
+
+1. **Regenerate components when designs change** - Keep your code in sync
+2. **Read the generated README** - Each component documents its own API
+3. **Use TypeScript** - Get the full benefit of type safety
+4. **Version control generated code** - Treat it like any other source code
+5. **Customize carefully** - Remember that regeneration will overwrite changes
+
+## Support
+
+For questions, issues, or feature requests, please contact the Bravo Studio team.
+
+Package: `@bravostudioai/react`
+
+## Version & Updates
+
+Check your installed version:
+
+```bash
+npm list @bravostudioai/react
+```
+
+Or programmatically:
+
+```typescript
+import { VERSION } from '@bravostudioai/react/version';
+console.log(VERSION);
+```
+
+**Updating to the latest version:**
+
+```bash
+npm update @bravostudioai/react
+```
+
+## Keywords
+
+`react`, `typescript`, `code-generation`, `design-to-code`, `figma`, `figma-to-react`, `bravo-studio`, `bravo-studio-ai`, `component-generator`, `type-safe`, `mcp`, `model-context-protocol`, `ai-apps`, `design-streaming`, `design-system`, `ui-components`, `figma-plugin`
+
+---
+
+**Stream Figma designs directly into your MCP apps. Start with @bravostudioai/react.**
+
+Made with ❤️ by the Bravo Studio AI team

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bravostudioai/react",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/src/index.d.ts",

package/src/codegen/generator.ts

@@ -12,12 +12,51 @@ import {
   sanitizePropName,
 } from "./parser";
 
+/**
+ * Metadata extracted from generated component
+ */
 export interface ComponentMetadata {
+  /** List of prop names */
   props: string[];
+  /** List of event handler names */
   events: string[];
+  /** Example JSX usage string */
   jsx: string;
 }
 
+/**
+ * Generates React component wrapper code for an Encore page
+ *
+ * Creates a TypeScript React component that wraps EncoreApp with typed props
+ * for all data-bound components, sliders, forms, and interactive elements.
+ *
+ * @param appId - Encore app ID
+ * @param pageId - Encore page ID
+ * @param componentName - Name for the generated component
+ * @param sliders - Slider/list metadata from parser
+ * @param standaloneComponents - Standalone component metadata
+ * @param inputGroups - Input group metadata
+ * @param forms - Form metadata
+ * @param selectInputs - Select input metadata
+ * @param actionButtons - Action button metadata
+ * @param isProduction - Whether to include bundled data for production
+ * @param pageMeta - Optional page dimensions and aspect ratio
+ * @returns TypeScript component source code
+ *
+ * @example
+ * const code = generateComponentCode(
+ *   "01ABC123",
+ *   "01DEF456",
+ *   "MyPage",
+ *   sliders,
+ *   components,
+ *   inputGroups,
+ *   forms,
+ *   selectInputs,
+ *   actionButtons
+ * );
+ * fs.writeFileSync("MyPage.tsx", code);
+ */
 export function generateComponentCode(
   appId: string,
   pageId: string,
@@ -453,6 +492,25 @@ export const PageMeta = {
 `;
 }
 
+/**
+ * Generates README documentation for a generated component
+ *
+ * Creates comprehensive Markdown documentation explaining all props,
+ * events, and usage examples for the generated wrapper component.
+ *
+ * @param appId - Encore app ID
+ * @param pageId - Encore page ID
+ * @param appName - Human-readable app name
+ * @param pageName - Human-readable page name
+ * @param componentName - Generated component name
+ * @param sliders - Slider/list metadata
+ * @param standaloneComponents - Component metadata
+ * @param inputGroups - Input group metadata
+ * @param forms - Form metadata
+ * @param selectInputs - Select input metadata
+ * @param actionButtons - Action button metadata
+ * @returns Markdown documentation string
+ */
 export function generateReadme(
   appId: string,
   pageId: string,
@@ -811,6 +869,22 @@ ${controlExample}
 `;
 }
 
+/**
+ * Extracts component metadata for programmatic use
+ *
+ * Generates a simplified metadata object listing all props and events
+ * without the full code generation.
+ *
+ * @param _appName - App name (currently unused)
+ * @param pageName - Page name for component naming
+ * @param sliders - Slider metadata
+ * @param standaloneComponents - Component metadata
+ * @param inputGroups - Input group metadata
+ * @param forms - Form metadata
+ * @param selectInputs - Select input metadata
+ * @param actionButtons - Action button metadata
+ * @returns Component metadata object
+ */
 export function generateComponentMetadata(
   _appName: string,
   pageName: string,