@applica-software-guru/react-admin 1.3.163 → 1.3.166

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './time';
 export * from './lang';
 export * from './localizedValue';
+export * from './localStorage';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/utils/localStorage.d.ts

@@ -0,0 +1,16 @@
+type IListener = (value: unknown) => void;
+interface ILocalStorage {
+    get: (key: string) => unknown | null;
+    set: (key: string, value: unknown) => unknown | null;
+    watch: (key: string, callback: IListener) => void;
+    unwatch: (key: string, callback?: IListener) => void;
+}
+declare class LocalStorage implements ILocalStorage {
+    #private;
+    get(key: string): unknown | null;
+    set(key: string, value: unknown): unknown | null;
+    watch(key: string, callback: IListener): void;
+    unwatch(key: string, callback?: IListener | undefined): void;
+}
+export { LocalStorage };
+//# sourceMappingURL=localStorage.d.ts.map

package/dist/utils/localStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localStorage.d.ts","sourceRoot":"","sources":["../../../src/utils/localStorage.ts"],"names":[],"mappings":"AAOA,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAC1C,UAAU,aAAa;IACrB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACrC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,CAAC;IACrD,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IAClD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;CACtD;AAED,cAAM,YAAa,YAAW,aAAa;;IAOzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAUhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAUhD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI;IAa7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;CAe7D;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applica-software-guru/react-admin",
-  "version": "1.3.163",
+  "version": "1.3.166",
   "private": false,
   "repository": {
     "type": "git",
@@ -68,7 +68,8 @@
     "react-router-dom": "^6.1.0",
     "react-sticky-box": "2.0.4",
     "simplebar": "6.2.5",
-    "simplebar-react": "3.2.4"
+    "simplebar-react": "3.2.4",
+    "yup": "^1.3.3"
   },
   "devDependencies": {
     "@applica-software-guru/crud-client": "^1.1",

package/src/ApplicaAdmin.tsx

@@ -21,98 +21,98 @@ const defaultQueryClient = new QueryClient({
 
 export type ApplicaAdminProps = AdminProps & {
   /**
-   * Eventuali configurazioni aggiuntive da passare al tema.
-   * @remarks Questo tema è basato su Mantis Theme (https://mantisdashboard.io/)
+   * Optionally, a custom theme to use in the application.
+   * @remarks This theme is based on Mantis Theme (https://mantisdashboard.io/)
    *
    * @see https://marmelab.com/react-admin/Theming.html
    * @see https://material-ui.com/customization/theming/
    */
   theme: any;
   /**
-   * Consente di personalizzare ulteriormente il tema in base alle specifiche esposte dal tema stesso.
-   * Divertiti con cautela a modificare variabili di configurazione del tema, se fai un casino Marco Colucci potrebbe usare l'estintore (ho detto tutto).
+   * Optionally, a custom theme configuration to use in the application.
+   * Have fun with caution to modify theme configuration variables, if you make a mess Marco Colucci could use the fire extinguisher (I said everything).
    */
   themeConfig: ThemeConfig;
   /**
-   * URL dell'API da utilizzare nell'applicazione.
-   * Sebbene venga già definito un dataProvider ed authProvider di default, è possibile che l'app
-   * utilizzi l'apiUrl specificato per ulteriori operazioni (es. getstione delle notifiche).
+   * The URL of the API to use in the application.
+   * Although a default dataProvider and authProvider are already defined, it is possible that the app
+   * uses the specified apiUrl for further operations (e.g. handling notifications).
    */
   apiUrl: string;
   /**
-   * La lingua di default da utilizzare nell'applicazione.
+   * The default language to use in the application (default: en).
    */
   defaultLocale: string;
   /**
-   * Se impostato a true, l'applicazione lavora in modalità sviluppo.
-   * La modalità sviluppo è utile per effettuare test e debug ed esegue attività che non sono
-   * consigliate in produzione (es. cattura e inoltro dei messaggi non localizzati).
+   * If set to true, the application works in development mode.
+   * Development mode is useful for testing and debugging and performs activities that are not
+   * recommended in production (e.g. capturing and forwarding non-localized messages).
    */
   development: boolean;
   /**
-   * Il logo da visualizzare nella barra laterale quando il menu è espanso lateralmente.
+   * The main logo to display in the sidebar when the menu is expanded laterally.
    */
   logoMain: any;
   /**
-   * Eventuale logo da visualizzare nella barra laterale quando il menu è ridotto lateralmente.
+   * The icon to display in the sidebar when the menu is collapsed laterally.
    */
   logoIcon: any;
   /**
-   * Configurazione del menu da visualizzare nell'applicazione.
+   * Configured menu to display in the application.
    */
   menu: MenuProps;
   /**
-   * Nome dell'applicazione da mostrare nell'header.
+   * The name of the application to display in the header.
    */
   name: string;
   /**
-   * Testo da mostrare nel footer. Default: '© Applica Software Guru for'.
+   * Text to display in the footer. Default: '© Applica Software Guru for'.
    */
   copy: string;
   /**
-   * Versione dell'applicazione da mostrare nel footer.
+   * Application version to display in the footer.
    */
   version: string;
   /**
-   * Il provider di autenticazione da utilizzare nell'applicazione.
+   * The data provider to use in the application.
    */
   dataProvider: DataProvider;
   /**
-   * Il provider di dati da utilizzare nell'applicazione.
+   * The auth provider to use in the application.
    */
   authProvider: AuthProvider;
   /**
-   * Indica l'eventuale handler da utilizzare per la gestione degli errori.
-   * Di default è eseguita una chiamata PUT /api/ui/error con il messaggio di errore "error".
-   * Puoi implementare un tuo handler per gestire gli errori in modo diverso.
+   * Indicates the handler to use for error management.
+   * By default, a PUT /api/ui/error call is made with the error message "error".
+   * You can implement your own handler to manage errors differently.
    */
   errorHandler?: IErrorEventHandler | undefined;
   /**
-   * Indica il componente da visualizzare in caso di errore.
+   * Indicates the component to display in case of error.
    */
   error: React.Component;
   /**
-   * Indica il nome della risorsa REST da utilizzare per la gestione delle notifiche.
+   * Indicates the name of the REST resource to use for notification management.
    * @default "entities/notification"
    * @example
-   * // In questo caso, le notifiche verranno gestite tramite la risorsa "entities/notification"
+   * // In this case, notifications will be managed through the "entities/notification" resource
    * <ApplicaAdmin notification="entities/notification" />
    */
   notification: string;
   /**
-   * Indica se le notifiche devono essere disabilitate.
-   * Se le notifiche sono abilitate comparirà automaticamente un'icona in alto a destra nell'header.
+   * Indicates whether notifications should be disabled.
+   * If notifications are enabled, an icon will automatically appear in the top right of the header.
    *
    * @example
    * <ApplicaAdmin enableNotification />
    */
   enableNotification: boolean;
   /**
-   * Indica se la schermata di registrazione deve essere disabilitata.
-   * Se abilitata è necessario registrare una pagina, nelle rotte, che punti a /register
+   * Indicates whether the registration screen should be disabled.
+   * If enabled, it is necessary to register a page, in the routes, that points to /register
    *
    * @example
-   * // Pagina di base realizzata da Applica
+   * // Basic page made by Applica
    * import { RegisterPage } from "@applica-software-guru/react-admin";
    * <CustomRoutes noLayout>
    *  <Route path="/register" component={RegisterPage} />
@@ -120,11 +120,11 @@ export type ApplicaAdminProps = AdminProps & {
    */
   enableRegistration: boolean;
   /**
-   * Indica se la schermata di recupero password deve essere disabilitata.
-   * Se abilitata è necessario registrare una pagina, nelle rotte, che punti a /recover
+   * Indicates whether the password recovery screen should be disabled.
+   * If enabled, it is necessary to register a page, in the routes, that points to /recover
    *
    * @example
-   * // Pagina di base realizzata da Applica
+   * // Basic page made by Applica
    * import { RecoverPage } from "@applica-software-guru/react-admin";
    * <CustomRoutes noLayout>
    *  <Route path="/recover" component={RecoverPage} />
@@ -132,13 +132,20 @@ export type ApplicaAdminProps = AdminProps & {
    */
   enablePasswordRecover: boolean;
   /**
-   * L'instanza di QueryClient da utilizzare nell'applicazione
+   * The query client instance to use in the application.
    */
   queryClient: QueryClient;
+  /**
+   * Background image to display in login, recover, and register pages.
+   * This image must be a component with absolute positioning.
+   */
+  background?: React.ReactNode;
 };
 
 /**
- * Definisce un'applicazione super figa basata su React Admin, Mantis Theme ed il nostro stile.
+ * Define a basic super cool application based on React Admin, Mantis Theme and our style.
+ *
+ * @author A-Team - The Applica Software Guru
  * @param {ApplicaAdminProps}
  * @returns {React.ReactElement}
  */
@@ -164,6 +171,7 @@ const ApplicaAdmin = ({
   enableRegistration,
   enablePasswordRecover,
   queryClient,
+  background,
   ...props
 }: ApplicaAdminProps) => {
   useErrorEventCatcher({
@@ -196,13 +204,15 @@ const ApplicaAdmin = ({
         // @ts-ignore
         name,
         copy,
+        logo: logoMain,
         version,
+        background,
         enableRegistration,
         enablePasswordRecover
       });
     }
     return loginPage;
-  }, [loginPage, name, version, copy, enableRegistration, enablePasswordRecover]);
+  }, [loginPage, name, version, copy, background, logoMain, enableRegistration, enablePasswordRecover]);
   const layout = useMemo(
     () => (props: any) => {
       const _logoMain = name ? <MainIcon title={name} /> : logoMain;

package/src/components/{AuthWrapper.jsx → AuthWrapper.tsx}

@@ -7,10 +7,19 @@ import MainIcon from './MainIcon';
 import PropTypes from 'prop-types';
 import React from 'react';
 
-const AuthWrapper = ({ version, name, copy, children, background = AuthBackground }) => {
+export type AuthWrapperProps = {
+  version: string;
+  name: string;
+  copy?: string;
+  background?: React.ReactNode | React.ComponentType;
+  children: React.ReactNode;
+  logo?: React.ReactNode;
+};
+
+const AuthWrapper = ({ version, name, copy, children, logo, background = AuthBackground }: AuthWrapperProps) => {
   return (
     <Box sx={{ minHeight: '100vh' }}>
-      {React.isValidElement(background) ? background : React.createElement(background)}
+      {React.isValidElement(background) ? background : React.createElement(background as any)}
       <Grid
         container
         direction="column"
@@ -19,8 +28,8 @@ const AuthWrapper = ({ version, name, copy, children, background = AuthBackgroun
           minHeight: '100vh'
         }}
       >
-        <Grid item xs={12} sx={{ ml: 3, mt: 3 }}>
-          <MainIcon title={name} />
+        <Grid item xs={12} sx={{ ml: 3 }}>
+          {logo ? logo : <MainIcon title={name} />}
         </Grid>
         <Grid item xs={12}>
           <Grid

package/src/components/{MainIcon.jsx → MainIcon.tsx}

@@ -1,8 +1,8 @@
 import { Stack, Typography } from '@mui/material';
-
-import PropTypes from 'prop-types';
-
-const MainIcon = ({ title }) => (
+export type MainIconProps = {
+  title: string;
+};
+const MainIcon = ({ title }: MainIconProps) => (
   <Stack direction="row">
     <Typography variant="h2" sx={{ fontWeight: 'regular', letterSpacing: -2.5 }}>
       a.
@@ -14,8 +14,4 @@ const MainIcon = ({ title }) => (
   </Stack>
 );
 
-MainIcon.propTypes = {
-  title: PropTypes.string.isRequired
-};
-
 export default MainIcon;

package/src/components/Onboarding/OnboardingTip.tsx

@@ -0,0 +1,52 @@
+import _ from 'lodash';
+import { ITipDescriptor } from './types';
+import { useOnboardingTip } from './hooks';
+import { Optional } from 'src/types';
+import { Button, Stack, TooltipProps, Typography, buttonClasses, styled, tooltipClasses } from '@mui/material';
+import { Tooltip } from '../@extended';
+
+type IOnboardingTipProps = TooltipProps & Optional<Pick<ITipDescriptor, 'id' | 'step' | 'completeOnboarding'>, 'step'>;
+
+function BaseOnboardingTip(props: IOnboardingTipProps) {
+  const { id, step = 0, title, completeOnboarding } = props,
+    { tip, dismiss } = useOnboardingTip({ id: id, step: step, completeOnboarding: completeOnboarding }),
+    { open } = tip,
+    passProps = _.omit(props, ['id', 'step', 'title', 'completeOnboarding']);
+  return (
+    <Tooltip
+      {...passProps}
+      arrow={true}
+      open={open}
+      title={
+        <Stack gap={1}>
+          <Typography>{title}</Typography>
+          <Button onClick={dismiss} variant="text" color="primary" size="small">
+            Got it!
+          </Button>
+        </Stack>
+      }
+    >
+      {props.children}
+    </Tooltip>
+  );
+}
+
+const OnboardingTip = styled(BaseOnboardingTip)(({ theme }) => {
+  const { palette, spacing } = theme,
+    { primary, background } = palette;
+  return {
+    [`& .${tooltipClasses.tooltip}`]: {
+      padding: `${spacing(1)} ${spacing(1.5)}`,
+      backgroundColor: primary.main,
+      color: primary.contrastText,
+      [`& .${buttonClasses.root}`]: {
+        backgroundColor: background.paper
+      }
+    },
+    [`& .${tooltipClasses.arrow}`]: {
+      color: primary.main
+    }
+  };
+});
+
+export { OnboardingTip };

package/src/components/Onboarding/Provider.tsx

@@ -0,0 +1,145 @@
+import _ from 'lodash';
+import { PropsWithChildren, createContext, useEffect, useMemo, useReducer } from 'react';
+import { OnboardingModes } from './enums';
+import { useOnboardingDataProvider } from './onboardingDataProvider';
+import { ITipDescriptor } from './types';
+
+enum OnboardingActionType {
+  RESTART = 'RESTART',
+  SET_SHOW = 'SET_SHOW',
+  REGISTER_TIP = 'REGISTER_TIP',
+  UNREGISTER_TIP = 'UNREGISTER_TIP',
+  DISMISS_TIP = 'DISMISS_TIP',
+  SET_ON_COMPLETE = 'SET_ON_COMPLETE'
+}
+
+type IOnboardingProviderProps = PropsWithChildren<{
+  mode: OnboardingModes;
+  topic?: string;
+}>;
+type IOnCompleteCallback = () => void;
+type IOnboardingState = {
+  show: boolean;
+  tips: Array<ITipDescriptor>;
+  currentStep: number;
+  onComplete: IOnCompleteCallback;
+};
+type IOnboardingAction =
+  | { type: OnboardingActionType.RESTART }
+  | { type: OnboardingActionType.SET_SHOW; payload: boolean }
+  | { type: OnboardingActionType.REGISTER_TIP; payload: ITipDescriptor }
+  | { type: OnboardingActionType.UNREGISTER_TIP; payload: ITipDescriptor | string }
+  | { type: OnboardingActionType.DISMISS_TIP; payload: ITipDescriptor | string }
+  | { type: OnboardingActionType.SET_ON_COMPLETE; payload: IOnCompleteCallback };
+type IOnboardingContext = { state: IOnboardingState; dispatch: (action: IOnboardingAction) => void };
+
+function reducer(state: IOnboardingState, action: IOnboardingAction): IOnboardingState {
+  const newState = _.clone(state),
+    { type } = action;
+
+  switch (type) {
+    case OnboardingActionType.SET_SHOW: {
+      const { payload } = action;
+      return _.extend(newState, { show: payload });
+    }
+    case OnboardingActionType.REGISTER_TIP: {
+      const { payload } = action,
+        { id } = payload,
+        tips = _.chain(newState.tips)
+          .clone()
+          .reject((t) => t.id === id)
+          .value(),
+        existingTip = _.find(newState.tips, { id: id }),
+        newTip = _.chain(existingTip ?? {})
+          .clone()
+          .extend(payload)
+          .value();
+
+      tips.push(newTip);
+      return _.extend(newState, { tips: _.sortBy(tips, ['step']) });
+    }
+    case OnboardingActionType.UNREGISTER_TIP: {
+      const { payload } = action,
+        id = _.isString(payload) ? payload : payload.id,
+        tips = _.chain(newState.tips)
+          .reject((t) => t.id === id)
+          .sortBy(['step'])
+          .value();
+      return _.extend(newState, { tips: tips });
+    }
+    case OnboardingActionType.DISMISS_TIP: {
+      const { payload } = action,
+        id = _.isString(payload) ? payload : payload.id,
+        tips = _.chain(newState.tips)
+          .reject((t) => t.id === id)
+          .value(),
+        tip = _.find(newState.tips, { id: id });
+
+      if (_.isNil(tip)) {
+        return newState;
+      }
+
+      const newTip = _.chain(tip).clone().extend({ dismissed: true }).value();
+      tips.push(newTip);
+      const updatedStep =
+          _.chain(tips)
+            .reject((t) => t.dismissed ?? false)
+            .minBy('step')
+            .value()?.step ?? 0,
+        isOnboardingComplete =
+          newTip?.completeOnboarding &&
+          _.chain(tips)
+            .reject((t) => t.step < updatedStep)
+            .reject((t) => t.dismissed ?? false)
+            .isEmpty()
+            .value();
+
+      if (isOnboardingComplete) {
+        state.onComplete();
+      }
+
+      return _.extend(newState, { tips: _.sortBy(tips, ['step']), currentStep: updatedStep });
+    }
+    case OnboardingActionType.SET_ON_COMPLETE: {
+      const { payload } = action;
+      return _.extend(newState, { onComplete: payload });
+    }
+    case OnboardingActionType.RESTART: {
+      const tips = _.chain(newState.tips)
+        .clone()
+        .map((t) => _.omit(t, 'dismissed'))
+        .value();
+      return _.extend(newState, { tips: tips, currentStep: 0 });
+    }
+    default:
+      return newState;
+  }
+}
+
+const OnboardingContext = createContext<IOnboardingContext | undefined>(undefined);
+
+function OnboardingProvider(props: IOnboardingProviderProps) {
+  const { mode, topic = 'default' } = props,
+    { onboardingRequired, acknowledgeOnboarding } = useOnboardingDataProvider(mode, topic),
+    [state, dispatch] = useReducer(reducer, { show: onboardingRequired, tips: [], currentStep: 0, onComplete: () => {} }),
+    value = useMemo(() => ({ state, dispatch }), [state, dispatch]);
+
+  useEffect(() => {
+    dispatch({ type: OnboardingActionType.SET_SHOW, payload: onboardingRequired });
+  }, [onboardingRequired, dispatch]);
+
+  useEffect(() => {
+    function onComplete() {
+      acknowledgeOnboarding().then(() => {
+        dispatch({ type: OnboardingActionType.SET_SHOW, payload: false });
+      });
+    }
+    dispatch({ type: OnboardingActionType.SET_ON_COMPLETE, payload: onComplete });
+  }, [acknowledgeOnboarding, dispatch]);
+
+  return <OnboardingContext.Provider value={value}>{props.children}</OnboardingContext.Provider>;
+}
+
+export type { IOnboardingContext, IOnboardingState, IOnboardingAction };
+
+export { OnboardingProvider, OnboardingContext, OnboardingActionType };

package/src/components/Onboarding/enums.ts

@@ -0,0 +1,7 @@
+enum OnboardingModes {
+  NONE = 'none',
+  BROWSER = 'browser',
+  USER = 'user'
+}
+
+export { OnboardingModes };

package/src/components/Onboarding/hooks.tsx

@@ -0,0 +1,80 @@
+import _ from 'lodash';
+import { useCallback, useContext, useEffect } from 'react';
+import { ITipDescriptor } from './types';
+import * as yup from 'yup';
+import { IOnboardingAction, IOnboardingContext, IOnboardingState, OnboardingActionType, OnboardingContext } from './Provider';
+
+function useOnboardingContext(): IOnboardingContext {
+  const context = useContext(OnboardingContext);
+  if (context === undefined) {
+    throw new Error(
+      '[Onboarding] useOnboardingContext: context undefined. Please provide a valid OnboardingContext using OnboardingProvider'
+    );
+  }
+  return context;
+}
+
+function useOnboardingState(): IOnboardingState {
+  const context = useOnboardingContext();
+  return context.state;
+}
+
+function useOnboardingDispatch(): React.Dispatch<IOnboardingAction> {
+  const context = useOnboardingContext();
+  return context.dispatch;
+}
+
+function useOnboardingTip(config: ITipDescriptor): {
+  tip: ITipDescriptor & { open: boolean };
+  dismiss: () => void;
+} {
+  yup.object({ id: yup.string().required(), step: yup.number().required() }).validateSync(config);
+
+  const { id, step, completeOnboarding } = config,
+    { show, tips, currentStep } = useOnboardingState(),
+    tip = _.find(tips, { id: id }),
+    { dismissed } = tip ?? {},
+    dispatch = useOnboardingDispatch(),
+    dismiss = useCallback(() => {
+      dispatch({
+        type: OnboardingActionType.DISMISS_TIP,
+        payload: id
+      });
+    }, [dispatch, id]);
+
+  useEffect(() => {
+    if (_.isNil(tip) || step !== tip?.step) {
+      dispatch({
+        type: OnboardingActionType.REGISTER_TIP,
+        payload: {
+          id: id,
+          step: step,
+          completeOnboarding: completeOnboarding
+        }
+      });
+    }
+  }, [id, step, completeOnboarding, tip]);
+
+  useEffect(() => {
+    return () => {
+      dispatch({ type: OnboardingActionType.UNREGISTER_TIP, payload: id });
+    };
+  }, [id, dispatch]);
+
+  return {
+    tip: _.chain(tip ?? config)
+      .clone()
+      .extend({ open: show && !_.isNil(tip) && currentStep === step && !dismissed })
+      .value(),
+    dismiss: dismiss
+  };
+}
+
+function useRestartOnboarding(): () => void {
+  const dispatch = useOnboardingDispatch();
+  return useCallback(() => {
+    dispatch({ type: OnboardingActionType.RESTART });
+  }, [dispatch]);
+}
+
+export { useOnboardingTip, useRestartOnboarding };

package/src/components/Onboarding/index.ts

@@ -0,0 +1,6 @@
+export * from './enums';
+export * from './hooks';
+export * from './onboardingDataProvider';
+export * from './OnboardingTip';
+export * from './Provider';
+export * from './schemas';