@interopio/home-ui-react 1.2.6 → 1.2.8

package/README.md

@@ -1,308 +1,57 @@
-## Overview
-
-The [`@interopio/home-ui-react`](https://www.npmjs.com/package/@interopio/home-ui-react) library provides React components and hooks that enable you to create and customize a Home App for your [**io.Connect Browser**](https://interop.io/products/io-connect/) projects.
-
-The Home App is meant to enhance the user and developer experience when creating an **io.Connect Browser** project. It provides flows for authentication and authorization using Auth0 integration, and for initial setup in order to acquire all necessary browser permissions from the user. The Home App also includes a Launchpad app which is the central hub for io.Connect apps, Workspaces, Global Layouts, notifications, search and user profile settings. For **io.Connect Browser** projects, the Home App can be built as a Main app, or as a Main app that's also a Workspaces App.
-
-## Using the Home App
-
-The following examples show a Home App that's also a Workspaces App and demonstrate its basic end-user functionalities - from initial user setup to a more advanced usage of its UI elements.
-
-The Home App is the entry point of an **io.Connect Browser** project. When you first load the Home App in the browser, you will be presented with a login form. After a successful login, the app will initiate a first-time user setup flow which includes granting all required browser permissions to ensure that the **io.Connect Browser** project will function properly:
-
-![Initial Setup](./images/initial-setup.gif)
-
-If you don't grant all required permissions, the **io.Connect Browser** platform won't be able to operate and a page for unsuccessful user setup will appear. You will then have to grant the necessary browser permissions manually:
-
-![Manual Permissions](./images/manual-permissions.gif)
-
-If the setup flow completes successfully, you will be able to start exploring and using the Home App. The main operational hub of the Home App is the Launchpad, accessible from the logo button of the Home App. The Launchpad is the place from which you can manage Workspaces and Global Layouts, start apps, select favorites for easy access, use the search bar to find anything within the platform, see notifications and user profile settings.
-
-## Install
-
-To use the [`@interopio/home-ui-react`](https://www.npmjs.com/package/@interopio/home-ui-react) library in your project, execute the following command:
-
-```cmd
-npm install @interopio/home-ui-react
-```
-
-## Usage
-
-The [`@interopio/home-ui-react`](https://www.npmjs.com/package/@interopio/home-ui-react) library offers React hooks and components that your can use to customize the look and functionalities of the Home App.
-
-The [`@interopio/home-ui-react`](https://www.npmjs.com/package/@interopio/home-ui-react) library is meant to be used within a Main app of an **io.Connect Browser** project or a Main app that's also a Workspaces App.
-
-### Hooks
-
-The `useIOConnectHome()` hook provides information about the current state of the required browser permissions:
-
-```javascript
-const { permissions } = useIOConnectHome();
-```
-
-The returned object has the following properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `isDenied` | `boolean` | If `true`, the current browser permission has been denied by the user. |
-| `isLoading` | `boolean` | If `true`, the current browser permission is being set. |
-| `isSetupCompleted` | `boolean` | If `true`, the first-time user setup flow has been completed. |
-| `statuses` | `object[]` | Array of objects each describing the state of the required browser permissions. |
-
-Each permission status object has the following properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `"notifications"` \| `"window-management"` | The name of the browser permission. |
-| `state` | `"denied"` \| `"granted"` \| `"prompt"` | The state of the browser permission. |
-
-### Components
-
-The following lists the more important default components exported by the library:
-
-| Component | Description |
-|-----------|-------------|
-| `<IOConnectHomeProvider />` | Context provider component containing information about the current state of the required browser permissions. |
-| `<Launchpad />` | The main component containing the Launchpad. |
-| `<LaunchpadSlidePanel />` | Wrapper component around the `<Launchpad />` component allowing it to open as a sliding panel. |
-| `<PermissionsSetup />` | Component providing a setup flow for obtaining the required browser permissions from the user. |
-| `<LoginAuth0 />` | Component for handling the integrated Auth0 authentication and authorization process. |
-
-The following lists the main components comprising the `<Launchpad />` component and exported by the library:
-
-| Component | Description |
-|-----------|-------------|
-| `<ApplicationsSection />` | Component containing a section in the Launchpad with the available io.Connect apps. |
-| `<FavoritesSection />` | Component containing a section in the Launchpad with favorite items. |
-| `<LayoutSettingsContainer />` | Component containing a section in the Launchpad with Global Layout settings. |
-| `<NotificationsPanel />` | Component containing the notifications panel shown when the user clicks on the notifications icon in the Launchpad. |
-| `<ProfileSettings />` | Component containing a profile and settings section shown when the user clicks on the profile icon in the Launchpad. |
-| `<SearchBar />` | Component containing the search bar providing the Global Search functionality. |
-| `<SearchResultsSection />` | Component containing the search results and shown when the user starts typing in the search bar. |
-| `<WorkspacesSection />` | Component containing a section in the Launchpad with Workspace Layouts. |
-
-#### Launchpad Slide Panel Component
-
-The following demonstrates the default structure of the `<LaunchpadSlidePanel />` component:
-
-```javascript
-<LaunchpadSlidePanel>
-    <SlidePanel>
-        <Launchpad />
-    </SlidePanel>
-</LaunchpadSlidePanel>
-```
-
-#### Launchpad Component
-
-The following demonstrates the default structure of the `<Launchpad />` component:
-
-```javascript
-<Launchpad>
-    <LaunchpadAPIProvider>
-        <div>
-            <header>
-                <SearchBar />
-                <div>
-                    <NotificationsIcon />
-                    <ProfileIcon />
-                </div>
-                <Icon />
-            </header>
-            <main>
-                {searchTerm.trim().length < 3 ?
-                   <SectionProvider>
-                        <ul>
-                            <>
-                                <FavoritesSection />
-                                <WorkspacesSection />
-                                <ApplicationsSection />
-                            </>
-                        </ul>
-                    </SectionProvider> :
-                    <SearchResultsSection searchTerm={searchTerm} />
-                }
-            </main>
-            <LayoutSettingsContainer />
-        </div>
-        <Dialog>
-            <NotificationsPanel />
-        </Dialog>
-        <Dialog>
-            <ProfileSettings />
-        </Dialog>
-    </LaunchpadAPIProvider>
-</Launchpad>
-```
-
-The `<Launchpad />` component has the following properties:
-
-```javascript
-<Launchpad
-    components={{
-        sections: <></>
-    }}
-
-    onLogout={() => {}}
-
-    open={false}
-
-    setOpen={() => {}}
-
-    user={{
-        name: "N A"
-    }}
-/>
-```
-
-### Authentication & Authorization
-
-The Home App provides a process for authentication and authorization using Auth0 integration. If your organization uses other authentication and authorization mechanisms, you can substitute the default implementation with your custom one when building your Home App.
-
-### Examples
-
-The following examples demonstrate a basic implementations of a Home App with authentication and browser permission flows, using the default library hooks and components.
-
-Wrapping the `<App />` component in the `<IOConnectHomeProvider />` and the `<Auth0Provider />` context provider components in order to obtain the necessary data related to authentication and browser permissions:
-
-```javascript
-import { StrictMode } from "react";
-import * as ReactDOM from "react-dom/client";
-import { Auth0Provider } from "@auth0/auth0-react";
-import { IOConnectHomeProvider } from "@interopio/home-ui-react";
-import App from "./app/App";
-
-const root = ReactDOM.createRoot(
-    document.getElementById("root") as HTMLElement
-);
-
-root.render(
-   <StrictMode>
-        <Auth0Provider
-            domain={"platform-auth-domain"}
-            clientId={"client-id"}
-            authorizationParams={{
-                redirect_uri: window.location.origin,
-            }}
-        >
-            <IOConnectHomeProvider>
-                <App />
-            </IOConnectHomeProvider>
-        </Auth0Provider>
-   </StrictMode>
-);
-```
-
-Creating a Workspaces App that will act as a Main App for the **io.Connect Browser** project:
-
-```javascript
-import { useAuth0 } from "@auth0/auth0-react";
-import IOBrowserPlatform from "@interopio/browser-platform";
-import { IOConnectProvider } from "@interopio/react-hooks";
-import IOWorkspaces from "@interopio/workspaces-api";
-import Workspaces from "@interopio/workspaces-ui-react";
-import { PermissionsSetup, useIOConnectHome } from "@interopio/home-ui-react";
-import LoginPage from "../login/LoginPage";
-import LaunchpadButton from "../LaunchpadButton";
-import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
-
-const App = () => {
-    const { isAuthenticated } = useAuth0();
-    const { permission } = useIOConnectHome();
-
-    // Settings for initializing the io.Connect Browser platform.
-    const ioConnectSettings = {
-        browserPlatform: {
-            factory: IOBrowserPlatform,
-            config: {
-                workspaces: {
-                    src: "/",
-                    isFrame: true
-                },
-                layouts: {
-                    mode: "idb"
-                },
-                browser: {
-                    libraries: [IOWorkspaces]
-                },
-                licenseKey: "my-license-key"
-            }
-        }
-    };
-
-    // Initiate the authentication flow.
-    if (!isAuthenticated) {
-        return <LoginPage />;
-    };
-
-    // Initiate the flow for acquiring browser permissions.
-    if (!permission.isSetupCompleted) {
-        return <PermissionsSetup />;
-    };
-
-    return (
-        <IOConnectProvider settings={platformSettings}>
-            <Workspaces
-                components={{
-                    // Replace the default Workspaces App logo
-                    // with a button that will open the Launchpad.
-                    header: { LogoComponent: LaunchpadButton }
-                }}
-            />
-        </IOConnectProvider>
-    );
-};
-
-export default App;
-```
-
-Implementing a login page:
-
-```javascript
-import { useAuth0 } from "@auth0/auth0-react";
-import { LoginLoader, LoginAuth0 } from "@interopio/home-ui-react";
-import { LoginLoaderHeading } from "./LoginLoaderHeading";
-
-const LoginPage = () => {
-  const { loginWithPopup, isLoading } = useAuth0();
-
-    return (
-        <div>
-            {isLoading ?
-                <LoginLoader components={{ Heading: LoginLoaderHeading }} /> :
-                <LoginAuth0 onLogin={loginWithPopup} />
-            }
-        </div>
-    );
-};
-
-export default LoginPage;
-```
-
-Implementing the button that will open the Launchpad:
-
-```javascript
-import { useContext } from "react";
-import { useAuth0 } from "@auth0/auth0-react";
-import { IOConnectContext } from "@interopio/react-hooks";
-import { Logo } from "@interopio/workspaces-ui-react";
-import { LaunchPadSlidePanel } from "@interopio/home-ui-react";
-
-const LaunchpadButton = () => {
-    const { logout, user } = useAuth0();
-    const io = useContext(IOConnectContext);
-
-    // Logout handler.
-    const handleLogout = async () => {
-        // Shutting down the io.Connect Browser platform.
-        await io.webPlatform?.system.shutdown();
-
-        logout();
-    };
-
-    // Slide panel that contains the `<Launchpad />` component with its default structure.
-    return <LaunchPadSlidePanel user={user} onLogout={handleLogout} icon={<Logo />} />
-};
-
-export default LaunchpadButton;
-```
+# @interopio/home-ui-react
+
+The `@interopio/home-ui-react` library offers React components and hooks for building a [Home App](https://docs.interop.io/browser/capabilities/home-app/overview/index.html) for **io.Connect Browser** projects.
+
+![Using Home](https://docs.interop.io/browser/images/home/using-home.gif)
+
+## Installation
+
+To install the `@interopio/home-ui-react` library in your project, execute the following command:
+
+```cmd
+npm install @interopio/home-ui-react
+```
+
+## Usage
+
+The following example demonstrates initializing the `@interopio/home-ui-react` library with basic configuration:
+
+```javascript
+import { IOConnectHome } from "@interopio/home-ui-react";
+import "@interopio/workspaces-ui-react/dist/styles/workspaces.css";
+import "@interopio/home-ui-react/src/index.css";
+
+const getConfig = () => {
+    // Platform configuration.
+    const platformConfig = {
+        browserPlatform: {
+            factory: IOBrowserPlatform,
+            config: {
+                // Required license key.
+                licenseKey: "my-license-key",
+                // Workspaces App configuration.
+                workspaces: {
+                    src: "/",
+                    isFrame: true
+                }
+            }
+        }
+    };
+
+    return platformConfig;
+};
+
+// Configuration for the `<IOConnectHome />` component.
+const config = {
+    // Retrieve the platform configuration.
+    getIOConnectConfig: getConfig
+};
+
+export function App() {
+    return <IOConnectHome config={config} />
+};
+
+export default App;
+```
+
+For more details on using the library, see the [official documentation](https://docs.interop.io/browser/capabilities/home-app/library-features/index.html) of **io.Connect Browser**.

package/constants/storageKeys.d.ts

@@ -1,3 +1,4 @@
 export declare const SELECTED_LAYOUT_SESSION_STORAGE_KEY = "interopio_home_ui_selected_layout";
+export declare const AUTH0_VALIDATION_ERROR_SESSION_STORAGE_KEY = "interopio_home_ui_auth0_validation_error";
 export declare const FAVORITE_ENTITIES_LOCAL_STORAGE_KEY = "interopio_home_ui_favorite_entities";
 export declare const USER_LOCAL_STORAGE_KEY = "interopio_home_ui_user";

package/decoders/validation.d.ts

@@ -0,0 +1,3 @@
+import { Decoder } from 'decoder-validate';
+import { Auth0ValidationError } from '../lib/io-connect-home/types';
+export declare const auth0ValidationErrorDecoder: Decoder<Auth0ValidationError>;