@apia/dashboard-controller 2.0.8 → 2.0.9

package/dist/index.d.ts

@@ -1,24 +1,410 @@
-export { usePanelPosition } from './position/usePanelPosition.js';
-export { LandingPagePanelWrapper } from './splash/panels/LandingPagePanelWrapper.js';
-export { PanelIdentifier, PanelIdentifierContext } from './splash/panels/PanelIdentifier.js';
-export { TPanelContext, usePanelContext } from './splash/panels/PanelContext/index.js';
-export { TActionBehavior, TActionSource, TBasicAction, handleAction } from './actions/basicAction.js';
-export { externalFirePanelAction } from './actions/externalFirePanelAction.js';
-export { TActionDispatcher, TActionResult, TFooter, usePanelActions } from './actions/usePanelActions.js';
-export { usePanelIsLoading } from './actions/usePanelIsLoading.js';
-export { usePanelNetworkState } from './actions/usePanelNetworkState.js';
-export { usePanelIdentity } from './common/usePanelIdentity.js';
-export { saveParameters } from './config/saveParameters.js';
-export { usePanelParametersSelector } from './config/usePanelParametersSelector.js';
-export { TParamsStore, parametersStore } from './config/parametersStore.js';
-export { useDashboardContext } from './dashboard/DashboardContext.js';
-export { useDashboardPanel } from './dashboard/DashboardPanelContext.js';
-export { Dashboard } from './dashboard/dashboard.js';
-export { eventsController } from './eventsController/eventsController.js';
-export { usePanelFireEvent } from './eventsController/usePanelFireEvent.js';
-export { usePanelOnEvent } from './eventsController/usePanelOnEvent.js';
-export { TPanelEvent, TPanelEventCallback, TPanelEventIdentifier, TPanelEventRegister, TPanelIdentifier } from './eventsController/types.js';
-export { changePanelTitle, usePanelChangeTitle } from './panelsUtil/usePanelChangeTitle.js';
-export { createPanelStore } from './panelsStore/createPanelStore.js';
-export { useYieldPanelIsReady } from './splash/panels/PanelContext/useYieldPanelIsReady.js';
+import { TId, EventEmitter } from '@apia/util';
+import * as react from 'react';
+import { ReactNode, FC, KeyboardEvent, MouseEvent, ComponentType, ReactPortal } from 'react';
+import { TSpacingLayout } from '@apia/theme';
+import { TApiaApiResult, IApiaApiRequestConfig } from '@apia/api';
+import * as _reduxjs_toolkit_dist_configureStore from '@reduxjs/toolkit/dist/configureStore';
+import * as redux_thunk from 'redux-thunk';
+import * as redux from 'redux';
+import { SliceCaseReducers } from '@apia/store';
+
+/**
+ * Permite conocer la posición del panel, se actualiza automáticamente cuando
+ * ésta cambia provocando un renderizado en el padre
+ */
+declare function usePanelPosition(): {
+    containerId: TId;
+    position: number;
+} | undefined;
+
+interface TPanelProps$1 {
+    canMove: boolean;
+    children: ReactNode;
+    hasRss: boolean;
+    id: string;
+    initialData: {
+        initialData: unknown;
+    };
+    isConfigurable: boolean;
+    isRefreshable: boolean;
+    name: string;
+    refreshOnStart: boolean;
+    refreshOnHome: boolean;
+    showTitle: boolean;
+    title: string;
+    type: string;
+}
+type TLoadedPanelProps = Omit<TPanelProps$1, 'children'>;
+type TPanelId = TPanelProps$1['id'];
+type TPanelName = TPanelProps$1['name'];
+type TPanelType = TPanelProps$1['type'];
+type PanelContainer = FC<TPanelProps$1>;
+
+declare const LandingPagePanelWrapper: PanelContainer;
+
+interface TPanelIdentifier {
+    panelId: TPanelId;
+    panelName: TPanelName;
+    panelTitle: string;
+    panelType: TPanelType;
+}
+type TPanelEventIdentifier = TPanelIdentifier & {
+    eventType: string;
+};
+type TPanelEvent<PayloadEvent = unknown> = TPanelEventIdentifier & {
+    payload: PayloadEvent;
+};
+type TPanelEventCallback<PayloadEvent> = (event: TPanelEvent<PayloadEvent>) => unknown;
+type TPanelEventRegister<PayloadEvent> = {
+    callback: TPanelEventCallback<PayloadEvent>;
+} & Partial<TPanelEventIdentifier>;
+
+declare const PanelIdentifierContext: react.Context<TPanelIdentifier | undefined>;
+interface TPanelIdentifierProps {
+    children: ReactNode;
+    id: string;
+    name: string;
+    title: string;
+    type: string;
+}
+declare const PanelIdentifier: ({ children, name, id, title, type, }: TPanelIdentifierProps) => react.JSX.Element;
+
+type TActionBehavior = 'DO_NOTHING' | 'NAVIGATE_URL' | 'CALL_AJAX_URL' | 'RUN_ACTION' | 'OPEN_TAB';
+type TActionSource = 'CLICK' | 'DOUBLE_CLICK';
+type TBasicAction = {
+    action: string;
+    actionBehavior: TActionBehavior;
+    actionSource: TActionSource;
+    actionNewTabTitle: string;
+    text: string;
+};
+declare function handleAction(panelId: string, event: KeyboardEvent | MouseEvent, action: TBasicAction): void;
+
+type TOnSucceed = (hasSucceed: boolean, data: TActionResult) => unknown;
+
+type TFooter = TBasicAction;
+type TCommonActionResult = {
+    title: string;
+    footer: TFooter;
+};
+type TActionResult<T = any> = null | NonNullable<Awaited<TApiaApiResult<T extends Record<string, unknown> ? T & TCommonActionResult : T>>>;
+type TActionDispatcherOptions = {
+    onComplete?: TOnSucceed;
+    requestConfig?: IApiaApiRequestConfig<object>;
+};
+type TExternalActionDispatcher = (panelId: string, { action, ...parameters }: {
+    action: string;
+} & Record<string, unknown>, options?: TActionDispatcherOptions) => void;
+type TActionDispatcher = ({ action, ...parameters }: {
+    action: string;
+} & Record<string, unknown>, options?: TActionDispatcherOptions) => Promise<TActionResult>;
+type TActionHandler = (result: TActionResult) => unknown;
+/**
+ * El hook usePanelActions es el método principal de comunicación entre el
+ * módulo cliente y el módulo server de un panel.
+ *
+ * Acepta un actionsHandler y devuelve un actionDispatcher.
+ *
+ * **Existe la acción refresh** que será llamada automáticamente cada vez que
+ * se guarde la configuración del panel o se haga click en el botón refrescar
+ * del mismo.
+ *
+ * @param actionsHandler Es un objeto de tipo clave-valor en donde cada clave debe corresponderse con una acción que puede ser ejecutada en el panel. El valor debe ser una función que recibe la respuesta del servidor a la ejecución de la acción.
+ *
+ * @returns Un método actionDispatcher que permite ejecutar acciones para ser procesadas por la contraparte del panel en el servidor. Al ser llamado acepta un objeto que debe tener como mínimo la propiedad action: string, que indica qué acción será ejecutada. Acepta opcionalmente cualquier cantidad adicional de propiedades en el objeto.
+ *
+ * @example
+ *
+  const dispatch = usePanelActions({
+    refresh() {
+      console.log('Refresh');
+    },
+    revert(response: TActionResult<TApiaLoadText>) {
+      if (response?.data?.text.label !== undefined)
+        setLabel(response?.data?.text.label);
+    },
+  });
+
+  return  <Button
+    onClick={() => {
+      dispatch({
+        action: 'revert',
+          text: (document.getElementById('Text') as
+          HTMLInputElement).value,
+      });
+    }}
+  >
+    Revert
+  </Button>
+ */
+declare function usePanelActions(actionsHandler?: Record<string, TActionHandler>): TActionDispatcher;
+
+declare const externalFirePanelAction: TExternalActionDispatcher;
+
+declare function usePanelIsLoading(): boolean;
+
+/**
+ * Permite saber en todo momento si el panel actual tuvo un error en su
+ * conexión de red
+ */
+declare const usePanelNetworkState: () => boolean;
+
+type TPanelLayout = TSpacingLayout;
+
+/**
+ * **Favor de leer con cuidado el siguiente contenido, es muy importante para
+ * la performance**
+ *
+ * El hook useYieldPanelIsReady es una parte muy importante del flujo de
+ * trabajo de los dashboards. **El no reportar la carga de un panel tiene
+ * penalizaciones graves en el tiempo de renderizado inicial**, esto es porque
+ * el dashboard espera que todos los paneles hayan terminado la carga
+ * estructural básica antes de empezar con los refresh iniciales, y esto termina
+ * impactando en el tiempo que demora en bajar la cortina.
+ *
+ * **Aclaración:** Actualmente se espera las cargas estructurales para lanzar
+ * los refresh iniciales por motivos de arquitectura. Esa restricción será
+ * eliminada probablemente en el corto plazo, pero eso no cambia la necesidad de
+ * reportar las estructuras ya que esta información es igualmente utilizada para
+ * el bajado de la cortina de Skeletons.
+ *
+ * Por ejemplo, si todos los paneles están optimizados para lograr cargas
+ * iniciales rápidas pero el logo de la aplicación no reporta que su estructura
+ * está pronta, el dashboard va a bajar su cortina solamente luego de que expire
+ * el timeout **DASH_COURTAIN_TRESHOLD**, que por defecto viene establecido en 5
+ * segundos.
+ *
+ * Esto significa que aún cuando la cortina se hubiera podido bajar quizás a
+ * los pocos ms de cargado el html inicial, no lo hará porque supone que el
+ * panel Logo aún no terminó su carga estructural.
+ *
+ * Siempre que un panel esté presente en un dashboard, deberá reportar cuando
+ * la carga estructural esté pronta. Esto puede ser hecho de dos formas:
+ *
+ * - Usando { setRef } = usePanelContext(): En el elemento crucial de HTML del
+ * elemento hacer ref={setRef}. Esta es la forma más óptima ya que nos garantiza
+ * que el panel se reporte cuando su estructura HTML ya esté disponible,
+ * evitando ninguna demora.
+ *
+ * - Usando useYieldPanelIsReady(): Este hook es una alternativa disponible
+ * para las situaciones en las que no tenemos ningún elemento HTML de
+ * importancia o cuando ese elemento no está disponible hasta después de la
+ * carga inicial. Al usar este hook el panel se reportará automáticamente una
+ * vez que haya hecho el renderizado inicial.
+ */
+declare function useYieldPanelIsReady(): void;
+
+type TPanelContext = {
+    /**
+     * setLayout es una función que permite decidir en qué formato se muestran
+     * los contenidos del panel.
+     *
+     * dense: No hay paddings
+     * clever: Hay paddings grandes
+     */
+    setLayout: (newLayout: TPanelLayout) => void;
+    setTitle: (newTitle: string) => void;
+    panelProps: Omit<TPanelProps$1, 'children'>;
+    /**
+     * Cuando un panel renderiza sus hijos en pantalla, debe setear el ref de
+     * modo que se pueda continuar con el flujo normal del panel. Este ref puede
+     * estar en cualquier nivel, cuando sea instanciado, se llamará al refresh
+     * inicial.
+     */
+    setRef: (el: HTMLElement | null) => void;
+};
+declare function usePanelContext(): TPanelContext;
+
+/**
+ * Permite acceder a la identidad del panel actual.
+ */
+declare function usePanelIdentity(): TPanelIdentifier;
+
+type TPanelParameter = string | number | boolean;
+type TParamsStore = Record<string, TPanelParameter>;
+type TParamsSlice = Record<string, TParamsStore>;
+declare const store: _reduxjs_toolkit_dist_configureStore.ToolkitStore<{
+    panelParameters: TParamsSlice;
+}, redux.AnyAction, [redux_thunk.ThunkMiddleware<{
+    panelParameters: TParamsSlice;
+}>]>;
+
+/**
+ * Actualiza los parámetros de un panel a nivel de cliente. Este método se
+ * expone con el único fin de ser llamado por la acción saveParams del api.
+ */
+declare function saveParameters(panelId: TPanelId, parameters: TParamsStore, refresh?: boolean): void;
+
+type TParametersSelector<Selected> = (parameters: Record<string, TPanelParameter>) => Selected;
+/**
+ // eslint-disable-next-line comment-length/limit-multi-line-comments
+ * Este hook permite seleccionar parámetros de un panel. Cada vez que los
+ * parámetros del panel sean actualizados, se llamará a la función selector y en
+ * caso de que la selección actual de parámetros difiera de la anterior, se
+ * provocará un renderizado en el componente que lo utiliza.
+ *
+ * Si se quiere obtener los parámetros del panel en el que se está trabajando,
+ * el segundo parámetro es innecesario. En caso de querer obtener los
+ * parámetros de otro panel, se puede pasar su nombre como segundo parámetro y
+ * la selección se hará de acuerdo a los parámetros de éste.
+ *
+ * Es importante ver que es imposible prever qué parámetros tendrá cada panel,
+ * por ello el tipo entregado al selector es Record, que puede entenderse como
+ * un mapa de entradas con clave string y valor TPanelParameter = string |
+ * boolean | number.
+ */
+declare function usePanelParametersSelector<Selected>(selector: TParametersSelector<Selected>, panelName?: TPanelName): Selected;
+
+declare global {
+    interface Window {
+        DASH_COURTAIN_TRESHOLD?: number;
+    }
+}
+declare class DashboardPanelsBootstraper {
+    #private;
+    dashboard: Dashboard;
+    constructor(dashboard: Dashboard);
+    /**
+     * El bootstraper se basa en dos elementos: setHasLoadedInitialData y
+     * SuspendPanelUntilDashboardReady.
+     *
+     * El funcionamiento es muy elemental: Cada panel utiliza el Suspend como
+     * wrapper y éste registra el id del panel en un array de paneles pendientes
+     * por cargar.
+     *
+     * Una vez que todos los paneles cargaron, el suspense retoma su tarea y
+     * renderiza el panel normalmente.
+     */
+    setPanelHasLoaded: (panelId: string) => void;
+    SuspendPanelUntilDashbordReady: ({ children, panelId, }: {
+        children: ReactNode;
+        panelId: string;
+    }) => react.JSX.Element;
+}
+
+declare function importPanel(path: string): ComponentType<{
+    initialData: unknown;
+}>;
+
+type TPanelProps = Omit<TLoadedPanelProps, 'initialData'>;
+declare class DashboardPanel extends EventEmitter<{
+    hasLoaded: boolean;
+    isVisible: boolean;
+}> {
+    #private;
+    dashboard: Dashboard;
+    hasInited: boolean;
+    hasLoaded: boolean;
+    id: string;
+    initialData: Promise<unknown> | null;
+    isVisible: boolean;
+    portal: ReactPortal;
+    props: TPanelProps;
+    constructor({ id, dashboard, PanelContainer, }: {
+        id: string;
+        dashboard: Dashboard;
+        PanelContainer: PanelContainer;
+    });
+    fireAction: ({ action, ...parameters }: {
+        action: string;
+    } & Record<string, unknown>, options?: TActionDispatcherOptions) => Promise<TActionResult>;
+    getContainer(): HTMLElement;
+    getParameters(): TParamsStore;
+    hide(): void;
+    refresh(): Promise<TActionResult>;
+    setHasLoaded(): void;
+    show(): void;
+    PanelElement: ({ ActualPanelContainer, Element, }: {
+        ActualPanelContainer: PanelContainer;
+        Element: ReturnType<typeof importPanel>;
+    }) => react.JSX.Element | null;
+}
+
+type TSwitchRoute = {
+    /**
+     * El callback será llamado si la ruta coincide.
+     */
+    callback: (result: RegExpMatchArray) => unknown;
+    route: RegExp;
+};
+type TUseSwitch = TSwitchRoute[];
+declare class Router extends EventEmitter<{
+    newRoute: string;
+}> {
+    #private;
+    constructor();
+    /**
+     * Se evaluarán las rutas en orden y la primera en coincidir será tomada como
+     * resultado del cambio de ruta.
+     *
+     * Las rutas provistas deberán matchear contra el path actual. El path actual
+     * es la porción de la ruta luego del dominio y el contexto. Ejemplo:
+     *
+     * http://localhost/apia                              =>      path='/'
+     * http://localhost/apia/spa/categories/comidas/1     =>      path='/spa/categories/comidas/1'
+     */
+    useSwitch: (routes: TUseSwitch) => void;
+}
+
+declare class Dashboard extends EventEmitter<{
+    changeScene: string;
+}> {
+    #private;
+    urlContext: string;
+    bootstrapper: DashboardPanelsBootstraper;
+    panels: Record<string, DashboardPanel> | null;
+    router: Router;
+    scenes: Record<string, string[]>;
+    getPanel: (id: string) => DashboardPanel;
+    getPanelByName: (name: string) => DashboardPanel | undefined;
+    constructor(panelsContainer: PanelContainer | undefined, urlContext: string);
+    loadScene: (scene?: string) => ReactPortal[];
+    Component: () => react.JSX.Element;
+}
+
+declare function useDashboardContext(): Dashboard;
+
+declare function useDashboardPanel(): DashboardPanel;
+
+declare const eventsController: {
+    callbacks: TPanelEventRegister<any>[];
+    broadcast(eventType: string, payload: any): void;
+    fireEvent(origin: TPanelIdentifier, eventType: string, payload: any): void;
+    onEvent<PayloadEvent>(distinction: Partial<TPanelEventIdentifier>, callback: TPanelEventCallback<PayloadEvent>): () => void;
+};
+
+/**
+ * Este hook devuelve un método que puede ser llamado para emitir un evento en
+ * el panel desde el cual es llamado. Los eventos de panel son emitidos con id
+ * de panel, tipo de panel, nombre de panel y tipo de evento y las suscripciones
+ * pueden ser realizadas a un conjunto arbitrario de estos identificadores.
+ *
+ * El segundo parámetro del método fireEvent devuelto es el payload, que puede
+ * ser de cualquier tipo.
+ */
+declare function usePanelFireEvent(): (eventType: string, payload: any) => void;
+
+/**
+ * Este hook permite realizar suscripciones a eventos de paneles. Deberá ser
+ * llamado una vez por cada suscripción que desee hacerse dentro de un panel y
+ * no se deberán ejecutar acciones para romper las suscripciones hechas, ya que
+ * este hook maneja esa lógica de forma automática.
+ */
+declare function usePanelOnEvent<PayloadEvent>(distinction: Partial<TPanelEventIdentifier>, callback: TPanelEventCallback<PayloadEvent>): void;
+
+declare function changePanelTitle(panelId: string, newTitle: string): void;
+declare function usePanelChangeTitle(): (newTitle: string) => void;
+
+declare type ActionCreatorForCaseReducer<CR> = CR extends (state: any, action: infer Action) => any ? Action extends {
+    payload: infer P;
+} ? (payload: P, panelName?: string) => unknown : () => unknown : () => unknown;
+type CaseReducerActions<CaseReducers extends SliceCaseReducers<any>> = {
+    [Type in keyof CaseReducers]: ActionCreatorForCaseReducer<CaseReducers[Type]>;
+};
+declare function createPanelStore<PanelState = any, Reducers extends SliceCaseReducers<PanelState> = SliceCaseReducers<PanelState>>(panelType: TPanelType, initialState: PanelState, reducers: Reducers): [
+    () => CaseReducerActions<Reducers>,
+    <Selected>(panelName: TPanelName, selector: (state: PanelState) => Selected, comparator?: (a: Selected, b: Selected) => boolean) => Selected
+];
+
+export { Dashboard, LandingPagePanelWrapper, PanelIdentifier, PanelIdentifierContext, type TActionBehavior, type TActionDispatcher, type TActionResult, type TActionSource, type TBasicAction, type TFooter, type TPanelContext, type TPanelEvent, type TPanelEventCallback, type TPanelEventIdentifier, type TPanelEventRegister, type TPanelIdentifier, type TParamsStore, changePanelTitle, createPanelStore, eventsController, externalFirePanelAction, handleAction, store as parametersStore, saveParameters, useDashboardContext, useDashboardPanel, usePanelActions, usePanelChangeTitle, usePanelContext, usePanelFireEvent, usePanelIdentity, usePanelIsLoading, usePanelNetworkState, usePanelOnEvent, usePanelParametersSelector, usePanelPosition, useYieldPanelIsReady };
 //# sourceMappingURL=index.d.ts.map