@ramme-io/create-app 1.1.7 → 1.1.9

package/README.md

@@ -1,36 +1,25 @@
-# Ramme App Starter
+# Create Ramme App
 
 [![NPM Version](https://img.shields.io/npm/v/@ramme-io/create-app.svg)](https://www.npmjs.com/package/@ramme-io/create-app) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**A quick start for prototypes.**
+The easiest way to start a new **Ramme** project.
+This CLI tool scaffolds a production-ready React application configured with:
+- **@ramme/ui:** Our pre-built component library.
+- **Tailwind CSS:** Fully configured for the Ramme design system.
+- **Vite:** For lightning-fast development.
+- **TypeScript:** For type-safe code.
 
-This repository is the scaffolding tool for the Ramme collection. It spins up a standard frontend environment, with the **Ramme UI** component library included.
+## 🚀 Quick Start
 
-Designed for quick builds, this starter kit standardizes configurations so you can move from concept to interactive prototype in seconds.
-
----
-
-## Quick Start
-
-To spin up a new project, run the initialization command in your terminal. This will generate a new folder with all resources linked and configured.
-
-*(Replace `my-new-project` with your desired folder name).*
+Get started in seconds. No global installation required.
 
 ```bash
-npm create @ramme-io/app@latest my-new-project
+npm create @ramme-io/app@latest
+# or
+npm init @ramme-io/app@latest
 ```
 
-This single command will:
-1.  **Scaffold** a high-performance Vite project structure.
-2.  **Install** React 19, TypeScript, and Tailwind CSS.
-3.  **Configure** the `@ramme-io/ui` component library and design tokens.
-4.  **Optimize** limited configuration for customization.
-
----
-
-## Getting Started
-
-Once the scaffolding is complete, initialize your local environment:
+You will be prompted to name your project.
 
 **1. Enter the project directory**
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramme-io/create-app",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "type": "module",
   "bin": {
     "create-ramme-app": "./index.js"
@@ -13,10 +13,11 @@
     "dev": "cd template && vite",
     "build": "cd template && tsc && vite build",
     "preview": "cd template && vite preview",
-    "pack-tarball": "npm pack"
+    "pack-tarball": "npm pack",
+    "bundle:ai": "repomix --ignore '**/*.lock,**/dist/**,**/template/dist/**,**/template/node_modules/**' --output 'ramme-starter-context.txt'"
   },
   "dependencies": {
-    "@ramme-io/ui": "^1.1.1",
+    "@ramme-io/ui": "^1.1.3",
     "ag-grid-community": "^34.1.2",
     "ag-grid-enterprise": "^34.1.2",
     "ag-grid-react": "^34.1.2",

package/template/DESIGNER_GUIDE.md

@@ -1,36 +1,26 @@
-# Ramme App Starter
+## 🚀 Quick Start for Designers
 
-[![NPM Version](https://img.shields.io/npm/v/@ramme-io/create-app.svg)](https://www.npmjs.com/package/@ramme-io/create-app) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+You don't need to be a coding wizard to use this. Just follow these 3 steps:
 
-**A quick start for prototypes.**
+### 1. Setup (Do this once)
+You need **Node.js** installed on your computer.
+- Open your terminal (Command Prompt or Terminal app).
+- Type `node -v` to see if you have it. If not, download it from [nodejs.org](https://nodejs.org).
 
-This repository is the scaffolding tool for the Ramme collection. It spins up a standard frontend environment, with the **Ramme UI** component library included.
-
-Designed for quick builds, this starter kit standardizes configurations so you can move from concept to interactive prototype in seconds.
-
----
-
-## Quick Start
-
-To spin up a new project, run the initialization command in your terminal. This will generate a new folder with all resources linked and configured.
-
-*(Replace `my-new-project` with your desired folder name).*
+### 2. Create your Project
+Run this magic command in your terminal:
 
 ```bash
-npm create @ramme-io/app@latest my-new-project
+npm create @ramme-io/app@latest
 ```
 
-This single command will:
-1.  **Scaffold** a high-performance Vite project structure.
-2.  **Install** React 19, TypeScript, and Tailwind CSS.
-3.  **Configure** the `@ramme-io/ui` component library and design tokens.
-4.  **Optimize** limited configuration for customization.
+It will ask you for a project name (e.g., my-smart-home). Type it and hit Enter.
 
 ---
 
-## Getting Started
+## Run it!
 
-Once the scaffolding is complete, initialize your local environment:
+You will be prompted to name your project.
 
 **1. Enter the project directory**
 ```bash
@@ -50,28 +40,4 @@ pnpm run dev
 
 Your prototype is now running locally at `http://localhost:5173`.
 
----
-
-## The Tech Stack
-
-This starter kit is an opinionated selection of the best open-source tools available:
-
-* **Vite:** Next-generation tooling for instant server start and lightning-fast HMR (Hot Module Replacement).
-* **React:** The standard library for building composable user interfaces.
-* **TypeScript:** Statically typed JavaScript for scalable, robust application logic.
-* **Tailwind CSS:** A utility-first styling engine configured with Ramme design tokens.
-* **@ramme-io/ui:** A pre-installed suite of accessible, unstyled primitives based on Radix UI.
-
----
-
-## Project Links
-
-* **`@ramme-io/ui`**: The core library of visual primitives.
-* **`@ramme-io/create-app`** (This Repository): The quick start kit.
-
----
-
-## License
-
-Copyright © 2025 Excesspool Limited Liability Company.
-This project is licensed under the [MIT License](LICENSE).
+---

package/template/README.md

@@ -1,77 +1,47 @@
 # Ramme App Starter
 
-[![NPM Version](https://img.shields.io/npm/v/@ramme-io/create-app.svg)](https://www.npmjs.com/package/@ramme-io/create-app) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Welcome to your new **Ramme** application!
+This project was scaffolded using `create-ramme-app`.
 
-**A quick start for prototypes.**
-
-This repository is the scaffolding tool for the Ramme collection. It spins up a standard frontend environment, with the **Ramme UI** component library included.
-
-Designed for quick builds, this starter kit standardizes configurations so you can move from concept to interactive prototype in seconds.
-
----
-
-## Quick Start
-
-To spin up a new project, run the initialization command in your terminal. This will generate a new folder with all resources linked and configured.
-
-*(Replace `my-new-project` with your desired folder name).*
+## 🚦 Getting Started
 
+**Install dependencies:**
 ```bash
-npm create @ramme-io/app@latest my-new-project
-```
-
-This single command will:
-1.  **Scaffold** a high-performance Vite project structure.
-2.  **Install** React 19, TypeScript, and Tailwind CSS.
-3.  **Configure** the `@ramme-io/ui` component library and design tokens.
-4.  **Optimize** limited configuration for customization.
-
----
-
-## Getting Started
-
-Once the scaffolding is complete, initialize your local environment:
-
-**1. Enter the project directory**
-```bash
-cd my-new-project
-```
-
-**2. Install dependencies**
-```bash
+npm install
+# or
 pnpm install
-# or npm install
+# or
+yarn
 ```
 
-**3. Start the dev server**
+**Start the development server:**
 ```bash
-pnpm run dev
+npm run dev
 ```
 
-Your prototype is now running locally at `http://localhost:5173`.
-
----
-
-## The Tech Stack
-
-This starter kit is an opinionated selection of the best open-source tools available:
+**Open your browser:**
+Visit `http://localhost:5173` to see your app.
 
-* **Vite:** Next-generation tooling for instant server start and lightning-fast HMR (Hot Module Replacement).
-* **React:** The standard library for building composable user interfaces.
-* **TypeScript:** Statically typed JavaScript for scalable, robust application logic.
-* **Tailwind CSS:** A utility-first styling engine configured with Ramme design tokens.
-* **@ramme-io/ui:** A pre-installed suite of accessible, unstyled primitives based on Radix UI.
+## 🏗️ Project Structure
 
----
+**`src/config/app.manifest.ts`**: The "Brain" of your app. Define your app's title, description, and high-level settings here.
+**`src/config/sitemap.ts`**: The "Skeleton." Define your pages and navigation structure here.
+**`src/core/component-registry.tsx`**: Maps JSON component names (from the builder) to actual React components.
+**`src/pages`**: Your actual page components.
+**`src/data`**: Mock data generators and seed files.
 
-## Project Links
+## 🎨 Customization
 
-* **`@ramme-io/ui`**: The core library of visual primitives.
-* **`@ramme-io/create-app`** (This Repository): The quick start kit.
+### changing the Theme
+Go to `src/index.css` or `tailwind.config.js` to update your brand colors.
 
----
+### Adding New Pages
+1.  Create a new component in `src/pages`.
+2.  Register it in your `sitemap.ts` (or the relevant template sitemap).
+3.  The `RouteGenerator` will automatically handle the routing!
 
-## License
+## 📚 Learn More
 
-Copyright © 2025 Excesspool Limited Liability Company.
-This project is licensed under the [MIT License](LICENSE).
+- [Ramme UI Documentation](https://ramme.io/docs)
+- [Vite Documentation](https://vitejs.dev/)
+- [Tailwind CSS Documentation](https://tailwindcss.com/)

package/template/gitignore

@@ -0,0 +1 @@
+node_modules

package/template/pkg.json

@@ -9,8 +9,9 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@ramme-io/ui": "^1.1.1",
+    "@ramme-io/ui": "^1.1.3",
     "mqtt": "^5.3.5",
+    "zustand": "^4.5.0",
     "ag-grid-community": "^31.3.1",
     "ag-grid-enterprise": "^31.3.1",  
     "ag-grid-react": "^31.3.1",       

package/template/public/api_mock.json

@@ -0,0 +1,16 @@
+{
+  "meta": {
+    "status": 200,
+    "region": "us-east-1"
+  },
+  "data": {
+    "finance": {
+      "mrr": 99999.00,
+      "growth": 0.12
+    },
+    "users": {
+      "total": 1245,
+      "active": 890
+    }
+  }
+}

package/template/src/components/DynamicBlock.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { getComponent } from '../core/component-registry';
+import { useSignal } from '../hooks/useSignal';
+import { getMockData } from '../data/mockData'; 
+
+const mapSignalStatus = (status: string): string => {
+  switch (status) {
+    case 'fresh': return 'online';
+    case 'stale': return 'warning';
+    case 'disconnected': return 'offline';
+    case 'error': return 'error';        
+    default: return 'offline';
+  }
+};
+
+interface DynamicBlockProps {
+  block: {
+    id: string;
+    type: string;
+    props: Record<string, any>;
+  };
+}
+
+export const DynamicBlock: React.FC<DynamicBlockProps> = ({ block }) => {
+  const Component = getComponent(block.type);
+  const { signalId, dataId, ...staticProps } = block.props;
+
+  // 1. Resolve Data
+  const resolvedData = dataId ? getMockData(dataId) : staticProps.data;
+
+  // 2. Signal Wiring
+  const signalState = useSignal(signalId || '');
+
+  // 3. Merge Props
+  const dynamicProps: Record<string, any> = { 
+    ...staticProps,
+    // FIX: Pass data as BOTH 'data' (Charts) and 'rowData' (Tables)
+    data: resolvedData || [], 
+    rowData: resolvedData || [],
+  };
+
+  // 4. Inject Signal Data
+  if (signalId && signalState) {
+    dynamicProps.value = `${signalState.value}${signalState.unit || ''}`;
+    if (signalState.status) {
+      dynamicProps.status = mapSignalStatus(signalState.status);
+      if (signalState.status === 'error') {
+        dynamicProps.variant = 'destructive';
+      }
+    }
+  }
+
+  return <Component key={block.id} {...dynamicProps} />;
+};

package/template/src/components/dev/GhostOverlay.tsx

@@ -0,0 +1,101 @@
+/**
+ * @file GhostOverlay.tsx
+ * @repository ramme-app-starter
+ * @description
+ * A development-mode wrapper that provides "X-Ray vision" into the
+ * application's structure.
+ *
+ * INTENT & PHILOSOPHY:
+ * This component embodies the "Glass Box" doctrine of the Ramme Framework.
+ * It allows creators to peer behind the "Visual Fidelity" of the prototype
+ * and inspect the "Functional Fidelity" underneath.
+ *
+ * STRATEGIC VALUE:
+ * 1. Traceability: It visually links a UI element (e.g., a Gauge) back to
+ * its source definition in the manifest (e.g., Signal ID: 'temp_01').
+ * 2. Debugging: It helps creators understand layout boundaries (Grid Cells)
+ * and data flow without needing browser DevTools.
+ * 3. Education: It reinforces the "Architect" mindset by exposing the
+ * component hierarchy.
+ *
+ * USAGE:
+ * Wrap any dynamic component in the `Dashboard.tsx` loop with this overlay.
+ * It listens to a global `debugMode` state (likely from a store or context)
+ * to toggle its visibility.
+ */
+
+import React from 'react';
+import { Badge, Icon } from '@ramme-io/ui';
+// We'll need a way to check if we are in "Debug/Ghost" mode.
+// For now, we can pass it as a prop or assume a context hook exists.
+// import { useDevTools } from '../../contexts/DevToolsContext';
+
+interface GhostOverlayProps {
+  /** The actual UI component being wrapped (e.g., DeviceCard) */
+  children: React.ReactNode;
+  
+  /** The unique ID of the component from the manifest */
+  componentId: string;
+  
+  /** The name of the React component being rendered (e.g., "StatCard") */
+  componentType: string;
+  
+  /** (Optional) The ID of the data signal driving this component */
+  signalId?: string;
+  
+  /** Whether the overlay is currently active (X-Ray Mode on) */
+  isActive?: boolean;
+}
+
+export const GhostOverlay: React.FC<GhostOverlayProps> = ({
+  children,
+  componentId,
+  componentType,
+  signalId,
+  isActive = false, // Default to off
+}) => {
+  
+  if (!isActive) {
+    return <>{children}</>;
+  }
+
+  return (
+    <div className="relative group">
+      {/* The "Ghost" Border 
+        - dashed: indicates scaffolding/structure
+        - accent color: differentiates dev tools from UI
+      */}
+      <div className="absolute inset-0 z-50 pointer-events-none border-2 border-dashed border-accent/50 rounded-lg bg-accent/5 group-hover:bg-accent/10 transition-colors" />
+
+      {/* The "Info Tag" 
+        - Floats top-left
+        - Displays the technical 'bones' of the component
+      */}
+      <div className="absolute top-0 left-0 z-50 p-2 transform -translate-y-1/2 translate-x-2">
+        <div className="flex items-center gap-2 bg-accent text-accent-foreground text-xs font-mono py-1 px-2 rounded shadow-sm">
+          <Icon name="box" size={12} />
+          <span className="font-bold">{componentType}</span>
+          <span className="opacity-75">#{componentId}</span>
+        </div>
+      </div>
+
+      {/* The "Signal Wire" 
+        - Floats bottom-right if a signal is connected
+        - Shows the data source wiring
+      */}
+      {signalId && (
+        <div className="absolute bottom-0 right-0 z-50 p-2 transform translate-y-1/2 -translate-x-2">
+           <div className="flex items-center gap-1.5 bg-blue-600 text-white text-xs font-mono py-1 px-2 rounded shadow-sm">
+            <Icon name="activity" size={12} />
+            <span>Signal: {signalId}</span>
+          </div>
+        </div>
+      )}
+
+      {/* Render the actual component underneath */}
+      <div className="opacity-50 grayscale transition-all duration-200 group-hover:opacity-75 group-hover:grayscale-0">
+        {children}
+      </div>
+    </div>
+  );
+};

package/template/src/config/app.manifest.ts

@@ -1,55 +1,56 @@
 import type { AppSpecification } from '../types/schema';
 
-/**
- * ------------------------------------------------------------------
- * THE APP MANIFEST (The "Brain")
- * ------------------------------------------------------------------
- * This file is the Single Source of Truth for the application's
- * domain logic. It defines the signals (data), entities (things),
- * and global configuration.
- * * In the "App Builder" workflow, this file is programmatically 
- * generated by the AI Assistant.
- */
-
 export const appManifest: AppSpecification = {
   meta: {
-    name: "My Ramme App",
-    version: "0.1.0",
-    description: "A prototype application generated by Ramme.",
-    author: "Ramme User",
-    createdAt: new Date().toISOString(),
+    name: "Acme Corp Admin",
+    version: "2.0.0",
+    description: "Executive overview of KPI metrics.",
+    author: "Ramme Builder"
+  },
+  config: {
+    theme: 'corporate', // <--- Switches the visual theme automatically
+    mockMode: false     // <--- Critical: Tells the Adapter Factory to use REAL code (HTTP/MQTT)
   },
-
-  // The Data Layer
   domain: {
-    // 1. Signals: The raw data points (Sensors, Statuses, Commands)
     signals: [
-      // Example placeholder:
-      // {
-      //   id: 'temp_01',
-      //   label: 'Living Room Temp',
-      //   kind: 'sensor',
-      //   source: 'mock',
-      //   unit: '°C',
-      //   defaultValue: 22
-      // }
+      {
+        id: "mrr_stripe",
+        label: "Monthly Revenue",
+        kind: "metric",
+        source: "http", // <--- This triggers your new generateHttpImplementation()
+        endpoint: "/api_mock.json",
+        unit: "USD",
+        defaultValue: 0,
+        refreshRate: 0
+      },
+      {
+        id: "active_users",
+        label: "Active Users",
+        kind: "metric",
+        source: "http",
+        endpoint: "/api_mock.json",
+        unit: "",
+        defaultValue: 0,
+        refreshRate: 0
+      }
     ],
-
-    // 2. Entities: The logical groupings (Devices, Rooms, Systems)
     entities: [
-      // Example placeholder:
-      // {
-      //   id: 'dev_thermostat',
-      //   name: 'Smart Thermostat',
-      //   type: 'device',
-      //   signals: ['temp_01']
-      // }
-    ],
-  },
-
-  // Global Config
-  config: {
-    theme: 'system',
-    mockMode: true, // Default to "Mock Mode" for instant prototyping
-  },
+      {
+        id: "widget_mrr",
+        name: "Current MRR",
+        type: "kpi",
+        signals: ["mrr_stripe"],
+        ui: { dashboardComponent: "StatCard", icon: "dollar-sign" },
+        category: ''
+      },
+      {
+        id: "widget_users",
+        name: "Total Users",
+        type: "kpi",
+        signals: ["active_users"],
+        ui: { dashboardComponent: "StatCard", icon: "users" },
+        category: ''
+      }
+    ]
+  }
 };

package/template/src/config/dashboard.layout.ts

@@ -62,6 +62,18 @@ export const dashboardLayout: DashboardSection[] = [
           trend: "CPU Load"
         },
         signalId: "server_01"
+      },
+      {
+        id: "dev_4",
+        component: "DeviceCard",
+        props: {
+          title: "Front Door",
+          description: "Entryway • Camera 01",
+          icon: "lock", // This maps to the Lucide icon 'lock'
+          status: "offline", // Default state before data loads
+          trend: "Locked"
+        },
+        signalId: "front_door_lock" // <--- We will wire this next
       }
     ]
   },

package/template/src/core/component-registry.tsx

@@ -16,20 +16,38 @@ import {
  * to the actual React component implementation.
  */
 export const COMPONENT_REGISTRY: Record<string, React.FC<any>> = {
-  // IoT Primitives
+  // --- Core Components ---
   DeviceCard,
-  
-  // Data Display
   StatCard,
   BarChart,
   LineChart,
   PieChart,
   DataTable,
-  
-  // Layout & Feedback
   Card,
   Alert,
   EmptyState,
+
+  // --- 🛡️ ROBUSTNESS ALIASES ---
+  // These mappings allow the manifest to use lowercase or alternate names
+  // without crashing the application.
+  
+  // Tables
+  'table': DataTable,       // Fixes your specific error
+  'Table': DataTable,
+  'grid': DataTable,
+
+  // Charts
+  'chart': BarChart,        // Default generic chart to BarChart
+  'line': LineChart,
+  'bar': BarChart,
+  'pie': PieChart,
+
+  // IoT Fallbacks
+  'DataCard': DeviceCard,
+  'GaugeCard': DeviceCard,
+  'ToggleCard': DeviceCard,
+  'SliderCard': DeviceCard,
+  'SparklineCard': DeviceCard,
 };
 
 /**
@@ -37,11 +55,19 @@ export const COMPONENT_REGISTRY: Record<string, React.FC<any>> = {
  * Returns a fallback if the component name is unknown.
  */
 export const getComponent = (name: string) => {
-  const Component = COMPONENT_REGISTRY[name];
+  // 1. Try direct lookup
+  let Component = COMPONENT_REGISTRY[name];
+
+  // 2. If not found, try PascalCase (e.g. "deviceCard" -> "DeviceCard")
+  if (!Component) {
+    const pascalName = name.charAt(0).toUpperCase() + name.slice(1);
+    Component = COMPONENT_REGISTRY[pascalName];
+  }
+
   if (!Component) {
     console.warn(`[Registry] Unknown component type: "${name}"`);
     return () => (
-      <Alert variant="warning" title="Unknown Component">
+      <Alert variant="danger" title="Unknown Component">
         The system tried to render <code>{name}</code> but it was not found in the registry.
       </Alert>
     );