@juggernautlabs/views 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,195 @@
+
+# Juggernaut Labs React View SDK
+
+The **Juggernaut Labs React View SDK** (`@juggernautlabs/views`) is the bridge between your platform’s backend logic and rich, interactive user experiences.
+
+It empowers developers to inject custom React interfaces directly into specific platform contexts—such as **Process Job Results** or **Database Records**. Instead of viewing raw JSON or static tables, users interact with dynamic UIs that can visualize data and trigger complex downstream workflows.
+
+## Core Value Proposition
+
+* **Contextual Leverage:** Build views that are instantly aware of where they are running. Automatically hydrate your UI with data from a specific Job or Database Record without complex API fetching logic.
+* **Human-in-the-Loop Interactivity:** Transform static outputs into active decision points. Review AI-generated content, validate data, and trigger follow-up processes directly from the view.
+* **Dynamic Visualization:** Create meaningful visual layers for your data. Turn a standard database row into a rich profile, dashboard, or media player based on the record type.
+
+---
+
+## Installation & Setup
+
+### 1. Install the Package
+
+```bash
+npm install @juggernautlabs/views
+
+```
+
+### 2. Configure Your Project
+
+Add the following scripts to your `package.json`. The SDK includes a CLI that handles the heavy lifting for local development and deployment.
+
+```json
+"scripts": {
+  "dev": "npx @juggernautlabs/views dev index.tsx",
+  "build": "vite build",
+  "deploy": "npx @juggernautlabs/views deploy ./index.tsx"
+}
+
+```
+
+---
+
+## Usage: Process Jobs
+
+Build interactive interfaces for the results of a Process Job. This is essential for workflows requiring manual review or distinct "next steps" based on the job's output.
+
+### The Hooks
+
+* **`useJuggernautJob()`**: Returns the context of the current job, including all tasks and generated outputs.
+* **`useJuggernautActions()`**: Returns an object containing available follow-up actions.
+
+### Implementation Example
+
+Below is an example of a "Curriculum Review" interface where a user reviews generated content and triggers an approval process.
+
+```tsx
+import { useJuggernautJob, useJuggernautActions } from '@juggernautlabs/views';
+
+export const JobResultView = () => {
+  const job = useJuggernautJob();
+  const actions = useJuggernautActions();
+
+  // "approve_curriculum" corresponds to the API Name of the action
+  // defined in your Juggernaut output settings.
+  const handleApprove = () => {
+    if (actions.approve_curriculum) {
+      actions.approve_curriculum.execute({
+        // 'inputs' are passed to the triggered process
+        inputs: {
+          jobId: job.id,
+          status: 'approved',
+          reviewerNotes: 'Curriculum meets all standards.'
+        },
+        // 'metadata' (optional) helps with logging and audit trails
+        metadata: {
+          source: 'reviewer_dashboard_v1'
+        }
+      });
+    }
+  };
+
+  return (
+    <div className="review-container">
+      <h1>Reviewing: {job.title}</h1>
+      <pre>{JSON.stringify(job.output, null, 2)}</pre>
+      
+      <div className="footer">
+        <button onClick={handleApprove}>
+          Approve & Publish
+        </button>
+      </div>
+    </div>
+  );
+};
+
+```
+
+> **Configuration Note:** For an action to appear in the `useJuggernautActions` hook, it must be explicitly added to the **Trigger Actions** section within the **Outputs** tab of your Process configuration.
+
+---
+
+## Usage: Database Records
+
+Create a custom visual layer for your database records. This allows you to render distinct UIs based on the record's content.
+
+### The Hook
+
+* **`useJuggernautRecord()`**: Returns the full data object for the current database record context.
+
+### Implementation Example
+
+Transforming a standard "Movie" database row into a rich media profile.
+
+```tsx
+import { useJuggernautRecord } from '@juggernautlabs/views';
+
+export const MovieRecordView = () => {
+  const movie = useJuggernautRecord();
+
+  return (
+    <div className="movie-card">
+      <div className="header" style={{ backgroundImage: `url(${movie.backdrop})` }}>
+        <h1>{movie.title}</h1>
+      </div>
+      <div className="content">
+        <p>{movie.description}</p>
+        {/* Conditional rendering based on record data */}
+        {movie.trailerId && (
+           <iframe src={`https://youtube.com/embed/${movie.trailerId}`} />
+        )}
+      </div>
+    </div>
+  );
+};
+
+```
+
+---
+
+## Local Development (Mocking Data)
+
+You cannot effectively develop UI without data. The SDK allows you to simulate the platform environment locally using a JSON file.
+
+1. Create a `.demo.json` file in the root of your component directory.
+2. Populate it with mock data. You can copy JSON from a successful job run or database query in the platform.
+
+**`.demo.json` Structure:**
+
+```json
+{
+  "job": {
+    "id": "job_123",
+    "status": "completed",
+    "output": { "module_1": "Intro to React" }
+  },
+  "record": {
+    "id": "rec_456",
+    "title": "Inception",
+    "trailerId": "8hP9D6kZseM"
+  },
+  "actions": {
+    "approve_curriculum": {
+      "type": "process_trigger",
+      "label": "Approve"
+    }
+  }
+}
+
+```
+
+When you run `npm run dev`, the CLI will read this file and automatically hydrate `useJuggernautJob`, `useJuggernautRecord`, and `useJuggernautActions` with your mock data.
+
+---
+
+## Deployment
+
+When your view is ready, deploy it directly to the Juggernaut Labs platform using the CLI command configured in your scripts:
+
+```bash
+npm run deploy
+
+```
+
+This bundles your React code and uploads it to the view configuration specified in your `index.tsx`.
+
+---
+
+### API Reference: Action Execution
+
+When using `useJuggernautActions`, the returned object keys match the **API Name** of the action. To trigger an action, call the `.execute()` method on that key.
+
+**Method Signature:**
+`action.execute(payload: { inputs: object, metadata?: object })`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| **inputs** | `object` | Key-value pairs matching the input variables defined in the target process. |
+| **metadata** | `object` | *(Optional)* Additional context data useful for logging or auditing. |

package/dist/cli.js

@@ -77,6 +77,7 @@ class TemplateUploader {
     try {
       const fileContent = await fs2.readFileSync(filePath, "utf-8");
       const metadata = JSON52.parse(fileContent) || {};
+      const isValidSettings = metadata.settings && typeof metadata.settings === "object";
       return {
         name: metadata.name || "Untitled Template",
         description: metadata.description || "",
@@ -85,7 +86,8 @@ class TemplateUploader {
           role: metadata.target?.role,
           resource: metadata.target?.resource,
           resourceType: metadata.target?.resourceType
-        }
+        },
+        settings: isValidSettings ? metadata.settings : undefined
       };
     } catch (e) {
       throw new Error("Invalid JSON in metadata file");

package/dist/index.js

@@ -16,6 +16,56 @@ class ContextManager {
   };
 }
 
+// src/events.js
+var ActionEvents = {
+  START_JOB: "start:job",
+  SCHEDULE_JOB: "schedule:job",
+  OPEN_RESOURCE: "open:resource",
+  START_PLUGIN: "start:plugin",
+  DATABASE_OPERATION: "database:operation",
+  TRIGGER_ACTION: "trigger:action",
+  CONTEXT_REQUEST: "juggernaut:context:request",
+  CONTEXT_RESPONSE: "juggernaut:context:response",
+  CONTEXT_UPDATE: "juggernaut:context:update"
+};
+var generateTriggerActionEventKey = (eventKey) => {
+  return `${ActionEvents.TRIGGER_ACTION}-${eventKey}`;
+};
+
+// src/resource.js
+class JuggernautAction {
+  constructor(options = { name: "", label: "", apiName: "", description: "", allowUserInput }, handler) {
+    this.name = options.name;
+    this.label = options.label;
+    this.apiName = options.apiName;
+    this.description = options.description;
+    this.handler = handler;
+    this.allowUserInput = options.allowUserInput || true;
+  }
+  get resourceType() {
+    return "Action";
+  }
+  execute(params) {
+    if (this.handler) {
+      return this.handler(params);
+    }
+  }
+  static resolveActions(actionsData = []) {
+    let actions = {};
+    for (let actionData of actionsData) {
+      actions[actionData.apiName] = new JuggernautAction({
+        name: actionData.name,
+        label: actionData.label,
+        apiName: actionData.apiName,
+        description: actionData.description
+      }, (params) => {
+        return sendJuggernautActionEvent(generateTriggerActionEventKey(actionData.key), params);
+      });
+    }
+    return actions;
+  }
+}
+
 // src/hooks.jsx
 var IS_DEV_MODE = import.meta.env ? import.meta.env.DEV : process?.env.NODE_ENV === "development";
 var DEMO_FILE_PATH = "/.demo.json";
@@ -25,7 +75,7 @@ var handleContextWindowEvents = (event) => {
   const { type, payload } = event.data || {};
   if (!type || !payload)
     return;
-  const { resourceType, resource } = payload;
+  const { resourceType, resource, actions = [] } = payload;
   switch (type) {
     case "juggernaut:context:request":
       if (ContextManager[STORE_KEY] && ContextManager[STORE_KEY].hasOwnProperty(resourceType)) {
@@ -39,6 +89,7 @@ var handleContextWindowEvents = (event) => {
     case "juggernaut:context:update":
       if (ContextManager[STORE_KEY]) {
         ContextManager[STORE_KEY][resourceType] = resource;
+        ContextManager[STORE_KEY]["actions"] = JuggernautAction.resolveActions(actions);
         subscribers.forEach((callback) => callback(resourceType, resource));
       }
       break;
@@ -76,6 +127,10 @@ var useJuggernautResource = (resourceType) => {
           if (ContextManager[STORE_KEY]) {
             ContextManager[STORE_KEY][resourceType] = demoData[resourceType];
           }
+          if (resourceType === "actions") {
+            const actions = JuggernautAction.resolveActions(demoData.actions || []);
+            ContextManager[STORE_KEY]["actions"] = actions;
+          }
           setResource(demoData[resourceType]);
           return true;
         }
@@ -133,7 +188,9 @@ var useJuggernautRecord = () => useJuggernautResource("record");
 var useJuggernautData = () => useJuggernautResource("data");
 var useJuggernautPlugin = () => useJuggernautResource("plugin");
 var useJuggernautProcess = () => useJuggernautResource("process");
-var useJuggernautActions = () => useJuggernautResource("actions");
+var useJuggernautActions = () => {
+  return ContextManager[STORE_KEY]["actions"] || {};
+};
 var useJuggernautSystem = () => useJuggernautResource("system");
 var FILE_EVENTS = {
   GET_FILE: "juggernaut:file:get",
@@ -203,7 +260,7 @@ var useJuggernautFileSystem = () => {
 };
 // src/actions.jsx
 import { useEffect as useEffect2, useCallback as useCallback2, useRef as useRef2 } from "react";
-var ActionEvents = {
+var ActionEvents2 = {
   START_JOB: "start:job",
   SCHEDULE_JOB: "schedule:job",
   OPEN_RESOURCE: "open:resource",
@@ -262,22 +319,22 @@ var useBridge = () => {
     });
   }, []);
   const startJob = useCallback2((processId, inputs, metadata = {}) => {
-    return sendEvent(ActionEvents.START_JOB, { processId, inputs, metadata });
+    return sendEvent(ActionEvents2.START_JOB, { processId, inputs, metadata });
   }, [sendEvent]);
   const scheduleJob = useCallback2((processId, inputs, schedule, metadata = {}) => {
-    return sendEvent(ActionEvents.SCHEDULE_JOB, { processId, inputs, schedule, metadata });
+    return sendEvent(ActionEvents2.SCHEDULE_JOB, { processId, inputs, schedule, metadata });
   }, [sendEvent]);
   const openResource = useCallback2((type, id, extra = {}) => {
-    return sendEvent(ActionEvents.OPEN_RESOURCE, { resourceType: type, resourceId: id, ...extra });
+    return sendEvent(ActionEvents2.OPEN_RESOURCE, { resourceType: type, resourceId: id, ...extra });
   }, [sendEvent]);
-  const triggerAction = useCallback2((payload) => sendEvent(ActionEvents.TRIGGER_ACTION, payload), [sendEvent]);
+  const triggerAction = useCallback2((eventKey, payload) => sendEvent(`${ActionEvents2.TRIGGER_ACTION}-${eventKey}`, payload), [sendEvent]);
   const launchProcess = (id, options = {}) => openResource("process", id, options);
   const launchJob = (id, options = {}) => openResource("job", id, options);
   const launchPlugin = (id, options = {}) => openResource("plugin", id, options);
   const launchDatabase = (id, options = {}) => openResource("database", id, options);
   const launchRecord = (dbId, recordId, options = {}) => openResource("database:record", recordId, { database: dbId, ...options });
-  const startPlugin = useCallback2((payload) => sendEvent(ActionEvents.START_PLUGIN, payload), [sendEvent]);
-  const databaseOperation = useCallback2((payload) => sendEvent(ActionEvents.DATABASE_OPERATION, payload), [sendEvent]);
+  const startPlugin = useCallback2((payload) => sendEvent(ActionEvents2.START_PLUGIN, payload), [sendEvent]);
+  const databaseOperation = useCallback2((payload) => sendEvent(ActionEvents2.DATABASE_OPERATION, payload), [sendEvent]);
   return {
     startJob,
     scheduleJob,
@@ -304,5 +361,5 @@ export {
   useBridge,
   sendJuggernautActionEvent,
   listenForJuggernautPlatformEvents,
-  ActionEvents
+  ActionEvents2 as ActionEvents
 };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@juggernautlabs/views",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A way to build Juggernaut view templates using React.",
+  "readme": "README.md",
   "type": "module",
   "bin": {
     "juggernauttemplates": "./dist/cli.js"