@kaltura-apps/genie-chat-react 1.4.1 → 1.5.0-tools.0

package/README.md

@@ -1,175 +1 @@
-# Unisphere - {{company-name|human-readable}} {{project-name|human-readable}}
-
-## Running The avatar
-
-The following will enable the avatar in the chat in local machine and nvq2:
-1. you can run the avatar in dev mode by using the query param `debugGenieAvatar=dev` (for qa you should use the value qa)
-2. you can also use the cmd+k - `>` and then select **Enable Avatar Mode**
-
-## Showing the debug panel for avatars
-
-It is automatically shown in avatar-dev application. 
-
-When in NVQ2, you can show the debug panel by using the query param `debugAvatarChat=true`. 
-
-## Open avatar automatically when showing the chat
-
-When in NVQ2, you can open the avatar automatically when showing the chat by using the query param `debugGenieAutoAvatar=true`. 
-
-## Develop Avatar Locally
-
-> Copy the .env file from `/unisphere/applications/avatar-dev/.env-(dev|qa)-template` to `/unisphere/applications/avatar-dev/.env` and update settings
-
-1. run `npm run dev:avatar`
-2. open the browser in http://localhost:4002/
-
-You will now use the nvq2 avatar in local development.
-
-If you would like to use the Avatar runtime, override port 8400
-
-## Develop Chat Locally
-
-> Copy the .env file from `/unisphere/applications/chat-dev/.env-template` to `/unisphere/applications/chat-dev/.env` and update settings
-
-1. run `npm run dev:chat`
-2. open the browser in http://localhost:4002/
-
-You will now use the nvq2 chat in local development.
-
-If you would like to use the Chat runtime, override port 8300
-If you would like to use the Avatar runtime, override port 8400
-
----
-
-## Overview
-
-This repository is a **Unisphere workspace** for an experience named **{{project-name|human-readable}}**.
-
-It contains everything you need to:
-- Create and publish npm / JFrog packages  
-- Bundle and version runtime artifacts  
-- Build and deploy applications  
-- Develop locally and promote changes to production  
-
-The Unisphere workspace acts as the single entry point for the entire lifecycle — from local development, through CI/CD, and all the way to production deployment.
-
-To better understand the ideas behind Unisphere and how it works, read more at:  
-https://unisphere.kaltura.com/
-
----
-
-## Prerequisites
-
-At the moment, **deploying Unisphere experiences is available only to Kaltura employees**.
-
-Before doing anything else, make sure your machine is properly configured to access:
-- Kaltura GitHub repositories  
-- Kaltura JFrog Artifactory registries  
-
-Follow the setup guide here:  
-https://unisphere.kaltura.com/docs/create/kaltura-employees/setup-machine
-
----
-
-## Add the Experience to Kaltura Github Organization
-
-Before you can deploy or activate this experience, it must be registered in Github under Kaltura Organization.
-
-This step connects your Unisphere workspace to the relevant Kaltura infrastructure and enables CI/CD, deployment, and activation flows.
-
-Follow the guide here:  
-https://unisphere.kaltura.com/docs/create/devops/create-github-repository
-
----
-
-## Create Artifacts
-
-Unisphere allows you to create and manage different types of artifacts, including:
-- Packages  
-- Runtimes  
-- Applications  
-
-Each artifact type has its own role in the ecosystem, but they all live and evolve together inside this workspace.
-
-Read more about creating artifacts here:  
-https://unisphere.kaltura.com/docs/create/overview
-
----
-
-## Deploy
-
-To deploy **packages, applications, and runtimes**, follow the deployment guide:  
-https://unisphere.kaltura.com/docs/create/devops/deploy
-
-For **applications and runtimes**, deployment is only part of the process.  
-After deployment, they must also be activated to become available in production.
-
-Activation guide:  
-https://unisphere.kaltura.com/docs/create/devops/activate
-
----
-
-## Local Development
-
-Unisphere provides a structured local development flow that mirrors production as closely as possible, while still keeping things fast and developer-friendly.
-
-This includes:
-- Local builds  
-- Watching and rebuilding artifacts  
-- Running applications in isolation or as part of a larger workspace  
-
-Read more about local development here:  
-https://unisphere.kaltura.com/docs/create/local-development
-
----
-
-## Available Commands
-
-This workspace exposes a small set of opinionated commands to help you explore, validate, and manage the experience.
-
-### Start
-Lists all available commands for each artifact in the experience, including how to build and serve runtimes, and how to spawn applications.
-
-```bash
-npm run start
-```
-
-
-### Info
-Displays information about the current workspace, including detected artifacts, configuration, and environment details.
-
-```bash
-npm run info
-```
-
-### Check
-Validates the workspace setup and verifies that all required artifacts and configurations are in place.
-
-```bash
-npm run check
-```
-
-### Reset
-Resets the workspace to a clean state. Useful when experimenting or when local state becomes inconsistent.
-
-```bash
-npm run reset
-```
-
-
----
-
-## Next Steps
-
-If this is your first time working with Unisphere, a great next step is to **create a runtime with a playground**.
-
-Follow the Hello World walkthrough here:
-[https://unisphere.kaltura.com/docs/create/overview](https://unisphere.kaltura.com/docs/create/overview)
-
-The walkthrough will guide you through:
-
-* Creating your first runtime
-* Running it locally with a playground
-* Understanding how runtimes, packages, and applications connect together
-
-This will give you a strong foundation for building and evolving the experience over time.
+# Unisphere Genie - Package Genie Chat React

package/index.esm.js

@@ -7,6 +7,38 @@ const GenieChatSandbox = createUnisphereSandbox({
   widgetName: 'unisphere.widget.genie',
   runtimeName: 'chat'
 });
+/**
+ * Provider component that initializes the Genie chat workspace and runtime.
+ *
+ * This component sets up the Unisphere sandbox, loads the chat runtime,
+ * and provides context for child components. Wrap your application with
+ * this provider to use Genie chat features.
+ *
+ * @param props - Component props
+ * @returns JSX element
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <GenieChatProvider runtimeSettings={{ /* chat settings *\/ }}>
+ *   <GenieChatVisual />
+ * </GenieChatProvider>
+ * ```
+ *
+ * @example
+ * With optional configuration:
+ * ```tsx
+ * <GenieChatProvider
+ *   env="irp2"
+ *   lang="es"
+ *   theme="dark"
+ *   runtimeSettings={{ /* chat settings *\/ }}
+ *   onStatusChange={(status) => console.log(status)}
+ * >
+ *   <GenieChatVisual />
+ * </GenieChatProvider>
+ * ```
+ */
 const GenieChatProvider = ({
   children,
   runtimeSettings,
@@ -29,8 +61,21 @@ const GenieChatProvider = ({
     children: children
   });
 };
-// Export the Visual component for use in consumer code
+/**
+ * Visual component that renders the Genie chat interface.
+ *
+ * This component must be used within a GenieChatProvider. It renders
+ * the actual chat UI with all interactive elements.
+ *
+ * @example
+ * ```tsx
+ * <GenieChatProvider runtimeSettings={{ /* settings *\/ }}>
+ *   <GenieChatVisual />
+ * </GenieChatProvider>
+ * ```
+ */
 const GenieChatVisual = GenieChatSandbox.Visual;
+const GenieChatSandboxContext = GenieChatSandbox.Context;
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
@@ -1093,6 +1138,50 @@ $({ target: 'Object', stat: true, arity: 2, forced: Object.assign !== assign },
   assign: assign
 });
 
+/**
+ * Standalone Genie chat component with page visual display.
+ *
+ * This component provides a complete chat interface in page mode,
+ * rendering the chat visual with customizable settings and appearance.
+ * Use this for embedding chat directly in your application pages.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <GenieChat />
+ * ```
+ *
+ * @example
+ * With custom settings and styling:
+ * ```tsx
+ * <GenieChat
+ *   settings={{
+ *     customization: {
+ *       scroll: 'container',
+ *       theme: { translucent: true }
+ *     }
+ *   }}
+ *   style={{ maxWidth: '800px', margin: '0 auto' }}
+ * />
+ * ```
+ *
+ * @example
+ * With custom loading and error components:
+ * ```tsx
+ * <GenieChat
+ *   loadingComponent={<CustomSpinner />}
+ *   errorComponent={<CustomError />}
+ *   style={{ height: '600px' }}
+ * />
+ * ```
+ *
+ * @param settings - Page visual settings for customizing chat behavior
+ * @param initialSettings - Initial visual settings loaded before runtime
+ * @param loadingComponent - Custom component to show while chat is loading
+ * @param errorComponent - Custom component to show when chat errors occur
+ * @param style - Custom CSS styles to apply to the chat container
+ * @returns JSX element rendering the Genie chat interface
+ */
 const GenieChat = ({
   style,
   settings,
@@ -1115,4 +1204,4 @@ const GenieChat = ({
   });
 };
 
-export { GenieChat, GenieChatProvider, GenieChatVisual };
+export { GenieChat, GenieChatProvider, GenieChatSandboxContext, GenieChatVisual };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaltura-apps/genie-chat-react",
-  "version": "1.4.1",
+  "version": "1.5.0-tools.0",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {
@@ -9,8 +9,8 @@
   },
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@unisphere/genie-types": "^1.13.1",
-    "@unisphere/runtime-react": "^1.84.0",
+    "@unisphere/genie-types": "^1.22.0-tools.1",
+    "@unisphere/runtime-react": "^1.89.0",
     "react": "^19.0.0"
   },
   "module": "./index.esm.js",

package/src/lib/genie-chat-component.d.ts

@@ -1,6 +1,53 @@
 import React from 'react';
 import { PageVisualSettings } from '@unisphere/genie-types';
+/**
+ * Visual settings for GenieChat component, excluding internal schema version.
+ */
 type GenieChatSettings = Omit<PageVisualSettings, 'schemaVersion'>;
+/**
+ * Standalone Genie chat component with page visual display.
+ *
+ * This component provides a complete chat interface in page mode,
+ * rendering the chat visual with customizable settings and appearance.
+ * Use this for embedding chat directly in your application pages.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <GenieChat />
+ * ```
+ *
+ * @example
+ * With custom settings and styling:
+ * ```tsx
+ * <GenieChat
+ *   settings={{
+ *     customization: {
+ *       scroll: 'container',
+ *       theme: { translucent: true }
+ *     }
+ *   }}
+ *   style={{ maxWidth: '800px', margin: '0 auto' }}
+ * />
+ * ```
+ *
+ * @example
+ * With custom loading and error components:
+ * ```tsx
+ * <GenieChat
+ *   loadingComponent={<CustomSpinner />}
+ *   errorComponent={<CustomError />}
+ *   style={{ height: '600px' }}
+ * />
+ * ```
+ *
+ * @param settings - Page visual settings for customizing chat behavior
+ * @param initialSettings - Initial visual settings loaded before runtime
+ * @param loadingComponent - Custom component to show while chat is loading
+ * @param errorComponent - Custom component to show when chat errors occur
+ * @param style - Custom CSS styles to apply to the chat container
+ * @returns JSX element rendering the Genie chat interface
+ */
 export declare const GenieChat: React.FC<{
     settings?: GenieChatSettings;
     initialSettings?: GenieChatSettings;

package/src/lib/genie-chat-provider.d.ts

@@ -1,12 +1,67 @@
 import React from 'react';
 import { ChatRuntimeSettings } from '@unisphere/genie-types';
+/**
+ * Props for the GenieChatProvider component.
+ */
 export type GenieChatProviderProps = {
+    /** Environment to connect to (e.g., 'nvp1', 'irp2'). Defaults to 'nvp1' */
     env?: string;
+    /** Language code (e.g., 'en', 'es'). Defaults to 'en' */
     lang?: string;
+    /** Theme mode ('light', 'dark') or custom theme object. Defaults to 'light' */
     theme?: 'light' | 'dark' | object;
+    /** Runtime configuration settings for the chat. Required. */
     runtimeSettings?: Omit<ChatRuntimeSettings, 'schemaVersion'>;
+    /** Callback when sandbox status changes */
     onStatusChange?: (status: 'idle' | 'loading' | 'ready' | 'error') => void;
+    /** Child components to render */
     children: React.ReactNode;
 };
+/**
+ * Provider component that initializes the Genie chat workspace and runtime.
+ *
+ * This component sets up the Unisphere sandbox, loads the chat runtime,
+ * and provides context for child components. Wrap your application with
+ * this provider to use Genie chat features.
+ *
+ * @param props - Component props
+ * @returns JSX element
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <GenieChatProvider runtimeSettings={{ /* chat settings *\/ }}>
+ *   <GenieChatVisual />
+ * </GenieChatProvider>
+ * ```
+ *
+ * @example
+ * With optional configuration:
+ * ```tsx
+ * <GenieChatProvider
+ *   env="irp2"
+ *   lang="es"
+ *   theme="dark"
+ *   runtimeSettings={{ /* chat settings *\/ }}
+ *   onStatusChange={(status) => console.log(status)}
+ * >
+ *   <GenieChatVisual />
+ * </GenieChatProvider>
+ * ```
+ */
 export declare const GenieChatProvider: React.FC<GenieChatProviderProps>;
+/**
+ * Visual component that renders the Genie chat interface.
+ *
+ * This component must be used within a GenieChatProvider. It renders
+ * the actual chat UI with all interactive elements.
+ *
+ * @example
+ * ```tsx
+ * <GenieChatProvider runtimeSettings={{ /* settings *\/ }}>
+ *   <GenieChatVisual />
+ * </GenieChatProvider>
+ * ```
+ */
 export declare const GenieChatVisual: React.FC<import("@unisphere/runtime-react").UnisphereSandboxVisualProps>;
+export declare const GenieChatSandboxContext: React.Context<import("@unisphere/runtime-react").SandboxContextValue | null>;