@bravostudioai/react 0.1.0

package/src/README.md

@@ -0,0 +1,110 @@
+# Bravo Library
+
+This directory contains the Bravo library code that will be extracted as a standalone library.
+
+## Styling Rules
+
+**No Tailwind CSS classes are allowed in this directory.**
+
+To keep the library dependency-free and portable, all styling must be done using:
+- Inline styles (via the `style` prop)
+- Regular CSS classes (if needed, but prefer inline styles)
+- CSS-in-JS solutions that don't require build-time dependencies
+
+This rule is enforced via ESLint. If you see an error about Tailwind classes, refactor to use inline styles instead.
+
+### Example
+
+❌ **Don't:**
+```tsx
+<div className="flex items-center justify-center bg-white">
+```
+
+✅ **Do:**
+```tsx
+<div style={{ 
+  display: 'flex', 
+  alignItems: 'center', 
+  justifyContent: 'center', 
+  backgroundColor: 'white' 
+}}>
+```
+
+## Observations & Lessons (Rendering and Layout)
+
+These notes summarize fixes and principles we applied while aligning the renderer with Figma/Bravo semantics:
+
+1) Container positioning context
+- Absolutely positioned children must resolve relative to their nearest positioned ancestor.
+- We set `position: 'relative'` on layout containers (`ContainerComponent`, `TopBarContainerComponent`, page scroll area) so children with `style.positioning` use the correct reference box.
+- Background layers must not participate in normal flow. `BackgroundContainerComponent` stays `position: 'absolute'` with `zIndex: -1` to prevent pushing content offstage.
+
+2) Accurate container measurements
+- Percent-based sizes and radii should use the actual container dimensions, not the window.
+- Implemented `useContainerDimensions()` with a `ref` + `ResizeObserver` and pass `{ dimensions }` through `BravoContainerContext`.
+- Components use `ref={ref}` instead of `onLoad` to ensure reliable measurement updates.
+
+3) Percent sizing and aspect ratio
+- `useBravoStyle` now derives:
+  - width = `style.width * containerWidth * 0.01`
+  - height = `style.height * containerHeight * 0.01` (or from `aspectRatio` when present)
+- Border radii and corner radii are computed in pixels from parent width to match Figma scaling.
+
+4) Page scaffolding
+- `PageComponent` wraps content in a full-size positioned container and provides measured dimensions to children.
+- Non-scrollable layers (backgrounds, top bars) render in a separate provider; the main page area is `overflow: 'auto'` to match scrolling behavior.
+
+5) Error tolerance
+- Image preloading uses `Promise.allSettled` and resolves on `onerror` to avoid halting rendering due to asset hiccups during development.
+
+6) Flex container wrapping and spacing
+- When using `flex-wrap: wrap` with `gap: 0px`, also set `alignContent: "flex-start"` to prevent spacing between wrapped rows.
+- The `align-content` property controls spacing between wrapped flex lines, and default values can create unwanted gaps even when gap properties are zero.
+
+6) Debugging tips
+- If content appears “gone” behind a solid background, verify:
+  - Background layers are absolute and behind (`zIndex: -1`).
+  - Parent containers establishing positioning have `position: 'relative'`.
+  - Percent calculations use container dimensions (check `BravoContainerContext.dimensions`).
+
+These conventions help keep the renderer predictable and closer to the Bravo/Figma mental model while remaining dependency-free.
+
+## Common Pitfalls We Hit (and how we fixed them)
+
+1) Background layer covering or pushing content
+- Symptom: Only the preview’s green frame shows; content appears pushed offstage.
+- Cause: Background container participating in layout or measuring as 0×0.
+- Fix: Keep `BackgroundContainerComponent` absolute with `zIndex: -1`, size to `width:'100%', height:'100%'`, and measure via `ResizeObserver`.
+
+2) Text not visible due to extreme line-height
+- Symptom: Text node exists in DOM but height collapses or content clips.
+- Cause: Unitless `lineHeightPx` multiplied, applied without `px` → giant computed line-height.
+- Fix: Convert to pixels: `lineHeight = (lineHeightPx * scaleFactor) + 'px'`.
+
+3) Containers collapsing to 0×0, children positioned off-canvas
+- Symptom: Child elements show 0 width/height or absolutely position relative to the page.
+- Cause: Container had no explicit size and no positioned ancestor.
+- Fix: For container wrappers (`ContainerComponent`, `TopBarContainerComponent`, page scroll area), set `position:'relative'`. Default `width/height` to `'100%'` when not computed yet so measurement settles on first paint.
+
+4) Percent sizing using window instead of container
+- Symptom: Elements look “scaled wrong” inside the preview frame.
+- Cause: Converting `%` using `window.innerWidth/innerHeight`.
+- Fix: Convert `%` using nearest container’s measured dimensions from context.
+
+5) Preloading assets blocking rendering
+- Symptom: "Uncaught (in promise)" and blank screen if an image fails.
+- Fix: Use `Promise.allSettled` and resolve on `img.onerror` so rendering continues during development.
+
+6) Unwanted gaps between wrapped flex rows
+- Symptom: When flex items wrap (e.g., Banner at 100% width wrapping to its own row, with Slider/Header on next row), there's visible spacing between rows even when `gap: 0px` and `rowGap: 0px` are set.
+- Cause: When `flex-wrap: wrap` is enabled, the `align-content` property controls spacing between wrapped rows. The default value can create spacing even when gap properties are set to 0.
+- Fix: Explicitly set `alignContent: "flex-start"` when `flexWrap` is `"wrap"` or `"wrap-reverse"`. This ensures wrapped rows have no spacing between them.
+- Location: In `useEncoreStyle`, after setting gap properties for flex containers with wrapping enabled.
+
+## Audit checklist for new/changed components
+- Does this wrapper need to be a positioning context? If yes, add `position:'relative'`.
+- Could this container start at 0×0? If yes, consider default `width:'100%', height:'100%'` until measured.
+- Do any styles derived from numeric values need units (e.g., `px`)? Ensure units are added.
+- Are percent-based sizes converted using container dimensions (not window)?
+- Do overlays/action wrappers accidentally sit above content? Verify `zIndex` and hit areas.
+

package/src/app.ts

@@ -0,0 +1,5 @@
+import EncoreAppContext from "./contexts/EncoreAppContext";
+import EncoreBindingContext from "./contexts/EncoreBindingContext";
+import useEncoreState from "./stores/useEncoreState";
+
+export { EncoreAppContext, EncoreBindingContext, useEncoreState };

package/src/cli/commands/download.ts

@@ -0,0 +1,133 @@
+
+
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { existsSync } from "fs";
+import dotenv from "dotenv";
+import { CONST_APPS_SERVICE_URL, CONST_COMPONENTS_CDN_URL } from "../../../constants";
+
+dotenv.config();
+
+// Default apps service URL (can be overridden with APPS_SERVICE_URL env var)
+const APPS_SERVICE_URL =
+  process.env.VITE_APPS_SERVICE_URL ||
+  CONST_APPS_SERVICE_URL ||
+  "https://apps-service-dev.bravostudio.app";
+const COMPONENTS_CDN_URL =
+  CONST_COMPONENTS_CDN_URL || "https://apps-public-dev.bravostudio.app";
+
+interface DownloadOptions {
+  appId: string;
+  pageId: string;
+  targetPath: string;
+}
+
+async function downloadFile(
+  url: string,
+  headers?: Record<string, string>
+): Promise<string> {
+  const response = await fetch(url, {
+    headers: headers || {},
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+
+  return await response.text();
+}
+
+async function downloadEncoreFiles({
+  appId,
+  pageId,
+  targetPath,
+}: DownloadOptions) {
+  console.log(`Downloading Encore files for app: ${appId}, page: ${pageId}`);
+  console.log(`Target path: ${targetPath}`);
+
+  // Ensure target directory exists
+  if (!existsSync(targetPath)) {
+    await mkdir(targetPath, { recursive: true });
+    console.log(`Created directory: ${targetPath}`);
+  }
+
+  const files: Array<{
+    url: string;
+    filename: string;
+    headers?: Record<string, string>;
+  }> = [
+    {
+      url: `${APPS_SERVICE_URL}/devices/apps/${appId}`,
+      filename: "app.json",
+      headers: { "x-app-clientrendered": "true" },
+    },
+    {
+      url: `${APPS_SERVICE_URL}/devices/apps/${appId}/node/${pageId}`,
+      filename: "page.json",
+      headers: { "x-app-clientrendered": "true" },
+    },
+    {
+      url: `${COMPONENTS_CDN_URL}/${appId}/draft/components/${pageId}.js`,
+      filename: "component.js",
+    },
+  ];
+
+  for (const file of files) {
+    try {
+      console.log(`Downloading ${file.filename} from ${file.url}...`);
+      const content = await downloadFile(file.url, file.headers);
+      const filePath = join(targetPath, file.filename);
+      await writeFile(filePath, content, "utf-8");
+      console.log(`✓ Saved ${file.filename} to ${filePath}`);
+    } catch (error) {
+      console.error(`✗ Failed to download ${file.filename} at :`, error);
+      throw error;
+    }
+  }
+
+  console.log("\n✓ All files downloaded successfully!");
+}
+
+function printUsage() {
+  console.log(`
+Usage: download-bravo.ts <appId> <pageId> <targetPath>
+
+Arguments:
+  appId      The Encore app ID
+  pageId     The Encore page ID
+  targetPath Path where files should be saved
+
+Environment variables:
+  APPS_SERVICE_URL  Base URL for the apps service (default: https://apps-service-dev.bravostudio.app)
+
+Example:
+  download-bravo.ts my-app-id my-page-id ./bravo-files
+  APPS_SERVICE_URL=https://api.example.com download-bravo.ts my-app-id my-page-id ./bravo-files
+`);
+}
+
+
+export async function runDownload(args: string[]) {
+  if (args.length < 3 || args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    process.exit(args.includes("--help") || args.includes("-h") ? 0 : 1);
+  }
+
+  const [appId, pageId, targetPath] = args;
+
+  if (!appId || !pageId || !targetPath) {
+    console.error("Error: Missing required arguments");
+    printUsage();
+    process.exit(1);
+  }
+
+  try {
+    await downloadEncoreFiles({ appId, pageId, targetPath });
+  } catch (error) {
+    console.error("\nError:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+