semaphor 0.0.1 → 0.0.12

package/README.md

@@ -0,0 +1,125 @@
+Integrating dashboard into your React app is a straightforward three-step process.
+
+### **1) Install Semaphor Package**
+
+Open your terminal in your project directory and run the following command. This command installs the `semaphor` package and adds it to your project dependencies.
+
+```markdown copy
+npm i semaphor
+```
+
+### **2) Get Auth Token**
+
+Before rendering the `Dashboard`, first acquire the `AuthToken`. This token enhances the security of your dashboard by restricting access to only users with the token. Make a POST fetch call as shown below.
+
+```jsx copy {1-3}
+const DASHBOARD_ID = 'd_cf007a8b-19bc-46ad-8787-2915445b7b86'; // Replace with your actual dashboard ID
+const DASHBOARD_SECRET = 'ds_f32f0b30-b7e1-40f9-ba6a-9804a5b9d635'; // Replace with your actual dashboard secret
+const TOKEN_URL = 'https://semaphor.cloud/api/v1/token';
+
+async function fetchToken() {
+  try {
+    const response = await fetch(TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        dashboardId: DASHBOARD_ID,
+        dashboardSecret: DASHBOARD_SECRET,
+      }),
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const token = await response.json();
+    if (token?.accessToken) {
+      setAuthToken(token);
+    }
+  } catch (error) {
+    console.error('There was an error!', error);
+  }
+}
+```
+
+### **3) Initialize Dashboard**
+
+Here is a simple example of a React component that demonstrates how to use the `Dashboard` component from the `semaphor` package. Make sure you import style.css either at the beginning of your component or in your global CSS file. This step is necessary for correctly loading your dashboard styles.
+
+```tsx copy {3, 11}
+import { useEffect, useState } from 'react';
+import { AuthToken, Dashboard } from 'semaphor';
+import '../node_modules/semaphor/dist/style.css'; // IMPORTANT! Include the CSS file. This is the default style, you can customize it.
+
+function App() {
+  const [authToken, setAuthToken] = useState<AuthToken>();
+
+  return (
+    <div>
+      <h2>My cool dashboard</h2>
+      <Dashboard authToken={authToken} id={DASHBOARD_ID} />
+    </div>
+  );
+}
+```
+
+### **Full Code**
+
+Here is the complete React code that uses the above steps. You can copy and paste this example into your own application.
+
+```tsx {3-7, 31, 43} copy filename="App.tsx"
+import { useEffect, useState } from 'react';
+import { AuthToken, Dashboard } from 'semaphor';
+import '../node_modules/semaphor/dist/style.css'; // IMPORTANT! Include the CSS file. This is the default style, you can customize it.
+
+const DASHBOARD_ID = 'd_cf007a8b-19bc-46ad-8787-2915445b7b86'; // Replace with your actual dashboard ID
+const DASHBOARD_SECRET = 'ds_f32f0b30-b7e1-40f9-ba6a-9804a5b9d635'; // Replace with your actual dashboard secret
+const TOKEN_URL = 'https://semaphor.cloud/api/v1/token';
+
+function App() {
+  const [authToken, setAuthToken] = useState<AuthToken>();
+
+  useEffect(() => {
+    async function fetchToken() {
+      try {
+        const response = await fetch(TOKEN_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            dashboardId: DASHBOARD_ID,
+            dashboardSecret: DASHBOARD_SECRET,
+          }),
+        });
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const token = await response.json();
+        if (token?.accessToken) {
+          setAuthToken(token);
+        }
+      } catch (error) {
+        console.error('There was an error!', error);
+      }
+    }
+    fetchToken();
+  }, []);
+
+  return (
+    <div>
+      <h2>My cool dashboard</h2>
+      <Dashboard authToken={authToken} id={DASHBOARD_ID} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### **Key Considerations**
+
+- **Security Note:** Keep the `DASHBOARD_SECRET` secure and do not expose it in client-side code in production. This example is for demonstration purposes only. When deploying in production, obtain the authentication token from a secure, server-side environment.
+- **Fetching the AuthToken:** Before the dashboard can be displayed, an authentication token must be fetched. The `useEffect` hook is used to perform this action when the component mounts.

package/dist/react-semaphor.d.ts

@@ -10,6 +10,7 @@ declare type Actions = {
     setAuthToken: (authToken: AuthToken) => void;
     setThemeStyle: (themeStyle: StyleProps) => void;
     setIsEditorSaveEvent: (isEditorSaveEvent: boolean) => void;
+    setBookmarkKey: (bookmarkKey: string) => void;
     setDashboard: (dashboard: TDashboard) => void;
     setDashboardTheme: (theme: 'light' | 'dark' | 'system') => void;
     setDashboardTitle: (title: string) => void;
@@ -91,6 +92,7 @@ declare type DashboardStore = {
     authToken?: AuthToken;
     theme?: 'light' | 'dark' | 'system';
     themeStyle?: StyleProps;
+    bookmarkKey?: string;
     dashboard: TDashboard;
     selectedSheetId?: string | null | undefined;
     selectedCardId?: string | null;
@@ -145,6 +147,8 @@ declare type FilterForString = BaseFilter & {
     values: [string];
 };
 
+export declare function getBookmarkKey(dashboardId: string): string;
+
 export declare function getDashbaordStateWithoutData(dashboardState: TDashboard): {
     sheets: {
         cards: TCard[] | undefined;
@@ -164,20 +168,30 @@ export declare type LoadingProps = {
     message?: string;
 };
 
+/**
+ * Style propeerites for the dashboard
+ */
 export declare type StyleProps = {
+    /** css class for `dashboard-panel` */
     dashboardPanel?: string;
+    /** css class for `dashboard-tabs-container` */
     dashboardTabsContainer?: string;
+    /** css class for `dashboard-card` */
+    /** css class for `dashboard-card-container` */
+    dashboardCardContainer?: string;
     dashboardCard?: string;
-    dashboardHeader?: string;
-    dashboardTitle?: string;
-    dashboardDescription?: string;
+    /** grid-layout config */
     gridLayout?: {
+        /** css class for `react-grid-layout` */
         className?: string;
         margin?: [number, number];
     };
+    /** chart config */
     chart?: {
+        /** chart font config */
         font?: Partial<FontSpec>;
         dataset?: any;
+        /** chart options */
         options?: any;
     };
 };
@@ -241,6 +255,9 @@ export declare type TSheet = {
     cards?: TCard[];
 };
 
+/**
+ * Style for the dashboard
+ */
 export declare type TStyle = {
     default: StyleProps;
     dark?: StyleProps;
@@ -266,10 +283,8 @@ export declare const useDashboardStore: UseBoundStore<Omit<StoreApi<DashboardSto
         themeStyle?: {
             dashboardPanel?: string | undefined;
             dashboardTabsContainer?: string | undefined;
+            dashboardCardContainer?: string | undefined;
             dashboardCard?: string | undefined;
-            dashboardHeader?: string | undefined;
-            dashboardTitle?: string | undefined;
-            dashboardDescription?: string | undefined;
             gridLayout?: {
                 className?: string | undefined;
                 margin?: [number, number] | undefined;
@@ -286,6 +301,7 @@ export declare const useDashboardStore: UseBoundStore<Omit<StoreApi<DashboardSto
                 options?: any;
             } | undefined;
         } | undefined;
+        bookmarkKey?: string | undefined;
         dashboard: {
             id: string;
             title?: string | undefined;
@@ -335,10 +351,8 @@ export declare const useDashboardStore: UseBoundStore<Omit<StoreApi<DashboardSto
                 default: {
                     dashboardPanel?: string | undefined;
                     dashboardTabsContainer?: string | undefined;
+                    dashboardCardContainer?: string | undefined;
                     dashboardCard?: string | undefined;
-                    dashboardHeader?: string | undefined;
-                    dashboardTitle?: string | undefined;
-                    dashboardDescription?: string | undefined;
                     gridLayout?: {
                         className?: string | undefined;
                         margin?: [number, number] | undefined;
@@ -358,10 +372,8 @@ export declare const useDashboardStore: UseBoundStore<Omit<StoreApi<DashboardSto
                 dark?: {
                     dashboardPanel?: string | undefined;
                     dashboardTabsContainer?: string | undefined;
+                    dashboardCardContainer?: string | undefined;
                     dashboardCard?: string | undefined;
-                    dashboardHeader?: string | undefined;
-                    dashboardTitle?: string | undefined;
-                    dashboardDescription?: string | undefined;
                     gridLayout?: {
                         className?: string | undefined;
                         margin?: [number, number] | undefined;
@@ -474,6 +486,7 @@ export declare const useDashboardStore: UseBoundStore<Omit<StoreApi<DashboardSto
             setAuthToken: (authToken: AuthToken) => void;
             setThemeStyle: (themeStyle: StyleProps) => void;
             setIsEditorSaveEvent: (isEditorSaveEvent: boolean) => void;
+            setBookmarkKey: (bookmarkKey: string) => void;
             setDashboard: (dashboard: TDashboard) => void;
             setDashboardTheme: (theme: 'light' | 'dark' | 'system') => void;
             setDashboardTitle: (title: string) => void;