@fluxo-dev/shell 26.3.6 → 26.4.1

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@fluxo-dev/shell",
-  "version": "26.3.6",
+  "version": "26.4.1",
   "peerDependencies": {
     "react": "^18.3.1",
     "@mantine/core": "^7.12.2",
     "react-router-dom": "^6.11.2",
     "react-redux": "^8.0.5",
     "@reduxjs/toolkit": "^1.9.1",
-    "@fluxo-dev/api-client-base": "^26.3.6",
-    "@fluxo-dev/shell-bi": "^26.3.6",
-    "@fluxo-dev/shell-hub": "^26.3.6",
-    "@fluxo-dev/shell-mfe": "^26.3.6",
-    "@fluxo-dev/shell-printing": "^26.3.6",
-    "@fluxo-dev/shell-reporting": "^26.3.6",
-    "@fluxo-dev/shell-workflow": "^26.3.6",
-    "@fluxo-dev/shell-ravify": "^26.3.6",
-    "@fluxo-dev/state": "^26.3.6",
-    "@fluxo-dev/ui-components": "^26.3.6",
+    "@fluxo-dev/api-client-base": "^26.4.0",
+    "@fluxo-dev/shell-bi": "^26.4.0",
+    "@fluxo-dev/shell-hub": "^26.4.0",
+    "@fluxo-dev/shell-mfe": "^26.4.0",
+    "@fluxo-dev/shell-printing": "^26.4.0",
+    "@fluxo-dev/shell-reporting": "^26.4.0",
+    "@fluxo-dev/shell-workflow": "^26.4.0",
+    "@fluxo-dev/shell-ravify": "^26.4.0",
+    "@fluxo-dev/state": "^26.4.0",
+    "@fluxo-dev/ui-components": "^26.4.0",
     "@scalar/api-reference-react": "0.9.1",
     "@devexpress/analytics-core": "25.2.6",
     "devexpress-dashboard": "25.2.6",

package/src/index.d.ts

@@ -1,4 +1,5 @@
-export { FluxoShell, type FluxoShellProps, type ShellFrontend, type ShellUI, ShellUINavigation, ShellUISearchPosition, ShellUISearchType } from './lib/app';
+export { FluxoShell, type FluxoShellProps, type ShellFrontend, type ShellUI, ShellLayoutVariant, ShellUINavigation, ShellUISearchPosition, ShellUISearchType } from './lib/app';
+export { ShellBrandingProvider, useShellBranding, useShellBrandSurface, resolveShellBackground, resolveShellBackgroundTopColor, isBrandCustomizationAllowed, type ShellBranding, type ShellFixedBrand, type ShellSidebarBackground, type ShellBrandSurface, } from './lib/branding';
 export { FrontendSwitch } from './lib/components/frontend-switch';
 export { ScreenSharingProvider, useScreenSharingContext } from './lib/contexts/screen-sharing-context';
 export { ScreenSharingWidget, type ScreenSharingWidgetProps } from './lib/components/screen-sharing-widget';

package/src/lib/app.d.ts

@@ -4,6 +4,7 @@ import './app.module.css';
 import '../style.css';
 import 'dayjs/locale/it';
 import { FrontendSwitcherUiProps } from './pages/frontend-switcher/frontend-switcher';
+import { ShellBranding } from './branding';
 /**
  * The ShellFrontend interface represents a frontend that can be rendered by the FluxoShell component.
  */
@@ -24,9 +25,24 @@ export type ShellFrontend = {
      * Optional properties for the admin layout. If you use custom layouts, this props will be ignored.
      */
     adminLayoutProps?: {
-        ui?: ShellUI;
+        /**
+         * Sovrascrive (in modo parziale) la configurazione `ui` della shell per questo frontend.
+         * Qui è possibile scegliere anche il layout da usare tramite `layout`.
+         */
+        ui?: Partial<ShellUI>;
     };
 };
+/**
+ * Layout disponibili per il frontend "admin".
+ *
+ * - `Classic`: layout storico (app bar colorata a tutta larghezza + sidebar chiara).
+ * - `Modern`: sidebar laterale colorata a tutta altezza, striscia dello stesso colore
+ *   che prosegue in alto a tutta larghezza e contenuto arrotondato in alto a sinistra.
+ */
+export declare enum ShellLayoutVariant {
+    Classic = "classic",
+    Modern = "modern"
+}
 export declare enum ShellUINavigation {
     Sidebar = 1,
     Topbar = 2,
@@ -45,6 +61,11 @@ export declare enum ShellUISearchType {
 }
 export interface ShellUI {
     navigation: ShellUINavigation;
+    /**
+     * Layout della shell. Se omesso viene usato {@link ShellLayoutVariant.Classic},
+     * quindi il comportamento resta identico alle installazioni esistenti.
+     */
+    layout?: ShellLayoutVariant;
     security: {
         showMyProfile: boolean;
     };
@@ -92,6 +113,15 @@ export interface FluxoShellProps {
     loginConfig?: ShellLoginConfig;
     ui: ShellUI;
     slots?: ShellSlots;
+    /**
+     * Branding del progetto consumer.
+     *
+     * Se non valorizzato, logo e colori continuano ad arrivare dal backend e restano
+     * modificabili dalla scheda "Brand" dell'amministrazione (comportamento storico).
+     * Se viene impostato un brand fisso (`branding.fixed`) oppure
+     * `branding.allowCustomization: false`, la scheda "Brand" non è più visibile né raggiungibile.
+     */
+    branding?: ShellBranding;
     routing?: {
         basename?: string;
     };

package/src/lib/branding/branding-context.d.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { ShellBranding, ShellFixedBrand } from './branding';
+export interface ShellBrandingContextValue {
+    /** Configurazione di branding passata dal progetto consumer (se presente) */
+    branding?: ShellBranding;
+    /** Brand fisso, se impostato */
+    fixed?: ShellFixedBrand;
+    /** Se `false` la scheda "Brand" dell'amministrazione è nascosta e non raggiungibile */
+    allowCustomization: boolean;
+}
+export interface ShellBrandingProviderProps {
+    branding?: ShellBranding;
+    children: React.ReactNode;
+}
+export declare function ShellBrandingProvider({ branding, children }: ShellBrandingProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Restituisce la configurazione di branding corrente.
+ * Se il progetto consumer non ha configurato nulla, la personalizzazione è permessa
+ * e non esiste nessun brand fisso (comportamento storico).
+ */
+export declare function useShellBranding(): ShellBrandingContextValue;
+export interface ShellBrandSurface {
+    /** Valore CSS per lo sfondo di sidebar / app bar (colore pieno o gradiente) */
+    background: string;
+    /** Colore pieno corrispondente alla parte alta dello sfondo */
+    topColor: string;
+    /** Logo orizzontale */
+    logo?: string;
+    /** Logo compatto (icona). In assenza di brand fisso coincide con `logo` */
+    logoIcon?: string;
+    logoHeight: number;
+    logoIconHeight: number;
+    /** `true` quando il brand è fissato dal progetto consumer */
+    isFixed: boolean;
+}
+/**
+ * Risolve logo e colori da usare nella chrome della shell:
+ * - se è impostato un brand fisso vince quello (nessuna chiamata al backend);
+ * - altrimenti si usa la configurazione salvata lato server (comportamento storico).
+ */
+export declare function useShellBrandSurface(): ShellBrandSurface;

package/src/lib/branding/branding.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Modello di branding della shell.
+ *
+ * Tutto quello che è definito qui è completamente opzionale: se il progetto consumer
+ * non passa nessuna configurazione di branding la shell continua a comportarsi
+ * esattamente come prima (logo e colori arrivano dal backend e sono modificabili
+ * dalla scheda "Brand" dell'amministrazione).
+ */
+/**
+ * Colore di sfondo della sidebar / barra superiore.
+ * Può essere un colore fisso (es. `#1d2e63`) oppure un gradiente.
+ */
+export type ShellSidebarBackground = string | {
+    /** Colore iniziale del gradiente (in alto) */
+    from: string;
+    /** Colore finale del gradiente (in basso) */
+    to: string;
+    /** Angolo del gradiente in gradi. Default: 180 (dall'alto verso il basso) */
+    angle?: number;
+};
+/**
+ * Brand "fisso" deciso dal progetto consumer.
+ * Quando è valorizzato la personalizzazione del brand viene disabilitata:
+ * la scheda "Brand" dell'amministrazione non è più visibile né raggiungibile.
+ */
+export interface ShellFixedBrand {
+    /** Logo orizzontale completo (PNG/SVG: url oppure data-uri) */
+    logoFull: string;
+    /** Solo icona / simbolo, usato quando la sidebar è compressa */
+    logoIcon: string;
+    /** Altezza massima (px) del logo orizzontale. Default: 24 */
+    logoHeight?: number;
+    /** Altezza massima (px) dell'icona. Default: valore di `logoHeight` */
+    logoIconHeight?: number;
+    /** Colore (o gradiente) della sidebar e della striscia superiore */
+    sidebarBackground: ShellSidebarBackground;
+    /**
+     * Palette del brand a 10 tonalità. Se fornita sovrascrive quella restituita
+     * dal backend, così anche i colori del tema restano bloccati sul brand del progetto.
+     */
+    colors?: string[];
+}
+export interface ShellBranding {
+    /**
+     * Se `false` la scheda "Brand" dell'amministrazione viene nascosta e la relativa
+     * pagina non è raggiungibile. Default: `true`, oppure `false` quando è impostato `fixed`.
+     */
+    allowCustomization?: boolean;
+    /** Brand fisso del progetto consumer. Se valorizzato disabilita la personalizzazione. */
+    fixed?: ShellFixedBrand;
+}
+/**
+ * Converte uno {@link ShellSidebarBackground} nel corrispondente valore CSS.
+ */
+export declare function resolveShellBackground(background?: ShellSidebarBackground): string | undefined;
+/**
+ * Colore "pieno" da usare dove un gradiente non è applicabile
+ * (es. la striscia superiore che deve combaciare con la parte alta della sidebar).
+ */
+export declare function resolveShellBackgroundTopColor(background?: ShellSidebarBackground): string | undefined;
+/**
+ * Determina se la personalizzazione del brand è permessa in base alla configurazione.
+ */
+export declare function isBrandCustomizationAllowed(branding?: ShellBranding): boolean;

package/src/lib/branding/index.d.ts

@@ -0,0 +1,2 @@
+export { isBrandCustomizationAllowed, resolveShellBackground, resolveShellBackgroundTopColor, type ShellBranding, type ShellFixedBrand, type ShellSidebarBackground, } from './branding';
+export { ShellBrandingProvider, useShellBranding, useShellBrandSurface, type ShellBrandingContextValue, type ShellBrandingProviderProps, type ShellBrandSurface, } from './branding-context';

package/src/lib/layouts/main/content.d.ts

@@ -3,6 +3,15 @@ export interface AppContentProps {
     withMultipleSessions: boolean;
     shellUi: ShellUI;
     asideWidth?: number;
+    /**
+     * Altezza della chrome superiore. Se omessa viene dedotta dal tipo di navigazione
+     * (comportamento storico: 48px con sidebar, 88px con top menu).
+     */
+    headerHeight?: number;
+    /**
+     * Stile della barra multi-sessione. `classic` (default) mantiene l'aspetto storico.
+     */
+    tabsVariant?: 'classic' | 'modern';
 }
 declare function AppContent(props: AppContentProps): import("react/jsx-runtime").JSX.Element;
 export default AppContent;

package/src/lib/layouts/main/navbar-item.d.ts

@@ -7,6 +7,11 @@ interface NavBarItemProps {
     links?: AppMenuItem[];
     level: number;
     isMinimal?: boolean;
+    /**
+     * `default`: voce su sfondo chiaro (comportamento storico).
+     * `onColor`: voce su sfondo colorato (sidebar del layout "modern").
+     */
+    variant?: 'default' | 'onColor';
 }
-export declare function NavBarItem({ icon: Icon, label, routerLink, initiallyOpened, links, level, isMinimal }: NavBarItemProps): import("react/jsx-runtime").JSX.Element;
+export declare function NavBarItem({ icon: Icon, label, routerLink, initiallyOpened, links, level, isMinimal, variant }: NavBarItemProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/src/lib/layouts/modern/modern-app-bar.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { ShellUI } from '../../app';
+import './modern.css';
+export interface ModernAppBarProps {
+    brandName: string;
+    /**
+     * Elemento di brand del progetto consumer (es. "powered by").
+     * Nel layout "modern" viene mostrato nel popover utente, che ha sfondo chiaro:
+     * la sidebar è colorata e un logo scuro rischierebbe di risultare illeggibile.
+     */
+    brandElement?: React.ReactNode;
+    shellUi: ShellUI;
+    /** Larghezza corrente della sidebar (0 su mobile) */
+    sidebarWidth: number;
+    /** Se true mostra il pulsante per aprire/chiudere l'aside AI */
+    isAiEnabled?: boolean;
+    aiAsideOpened?: boolean;
+    onAiAsideToggle?: () => void;
+}
+/**
+ * Barra superiore del layout "modern".
+ *
+ * È composta da due parti:
+ *  - una striscia del colore della sidebar che prosegue a tutta larghezza in alto;
+ *  - una barra bianca arrotondata in alto a sinistra, che apre il contenuto.
+ */
+export declare function ModernAppBar(props: ModernAppBarProps): import("react/jsx-runtime").JSX.Element;
+export default ModernAppBar;

package/src/lib/layouts/modern/modern-constants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Costanti geometriche del layout "modern".
+ *
+ * L'altezza complessiva della chrome superiore viene comunicata allo stato della shell
+ * (`dispatchSetAppBarHeight`), così `useShellLayout`, `ShellPage` e `PageHeader`
+ * calcolano gli offset corretti senza valori hardcoded.
+ */
+/** Striscia superiore, a tutta larghezza, con il colore della sidebar */
+export declare const MODERN_STRIP_HEIGHT = 8;
+/** Barra bianca con ricerca e azioni, arrotondata in alto a sinistra */
+export declare const MODERN_BAR_HEIGHT = 56;
+/** Altezza totale della chrome superiore */
+export declare const MODERN_HEADER_HEIGHT: number;
+/**
+ * Scala degli arrotondamenti del layout "modern".
+ * Volutamente contenuta: morbido ma non "a pillola".
+ */
+/** Controlli: bottoni, input, icone, tab, voci di menu */
+export declare const MODERN_RADIUS_CONTROL = 6;
+/** Contenitori: card, griglie */
+export declare const MODERN_RADIUS_SURFACE = 10;
+/** Superfici grandi: contenuto, pannelli laterali, card di login */
+export declare const MODERN_RADIUS_PANEL = 12;
+/** Raggio dell'angolo in alto a sinistra del contenuto */
+export declare const MODERN_CONTENT_RADIUS = 12;
+export declare const MODERN_SIDEBAR_WIDTH_OPEN = 248;
+export declare const MODERN_SIDEBAR_WIDTH_CLOSED = 64;
+/**
+ * Il layout "modern" non ha footer bar: le informazioni essenziali (stato connessione,
+ * utente, amministrazione, versione) stanno in fondo alla sidebar.
+ */
+export declare const MODERN_FOOTER_HEIGHT = 0;
+export declare const MODERN_ASIDE_WIDTH = 400;
+/** Larghezza della sidebar in funzione dello stato di apertura */
+export declare function getModernSidebarWidth(navbarOpened: boolean): number;

package/src/lib/layouts/modern/modern-layout.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import { FluxoClientConfiguration } from '@fluxo-dev/state';
+import { ShellUI } from '../../app';
+export interface ModernShellLayoutProps {
+    appVersion: string;
+    brandName: string;
+    brandElement?: React.ReactNode;
+    currentShellUI: ShellUI;
+    navbarOpened: boolean;
+    isMobile: boolean | undefined;
+    hasAdminAccess: boolean;
+    fluxoClientConfig: FluxoClientConfiguration | null;
+    showDisconnectionOverlay: boolean;
+    maxAttemptsReached: boolean;
+    reconnectAttempts: number;
+    isRetrying: boolean;
+    handleManualRetry: () => Promise<void>;
+    isAiEnabled: boolean;
+    aiAsideOpened: boolean;
+    onAiAsideToggle: () => void;
+}
+/**
+ * Layout "modern": sidebar laterale colorata a tutta altezza, striscia dello stesso
+ * colore che prosegue in alto a tutta larghezza e contenuto arrotondato in alto a sinistra.
+ *
+ * L'altezza complessiva della chrome superiore è identica a quella del layout classico
+ * (48px), così tutti i componenti di pagina condivisi continuano a funzionare senza modifiche.
+ */
+export declare const ModernShellLayout: React.FC<ModernShellLayoutProps>;
+export default ModernShellLayout;

package/src/lib/layouts/modern/modern-navbar.d.ts

@@ -0,0 +1,10 @@
+export interface ModernNavbarProps {
+    brandName: string;
+    appVersion: string;
+}
+/**
+ * Sidebar del layout "modern": colorata (colore fisso o gradiente del brand),
+ * a tutta altezza, con logo in alto e toggle di apertura/chiusura in basso.
+ */
+export declare function ModernNavbar({ brandName, appVersion }: ModernNavbarProps): import("react/jsx-runtime").JSX.Element;
+export default ModernNavbar;

package/src/lib/layouts/modern/modern-sidebar-footer.d.ts

@@ -0,0 +1,17 @@
+export interface ModernSidebarFooterProps {
+    appVersion: string;
+    brandName: string;
+    /** Sidebar compressa: mostra solo le icone */
+    collapsed: boolean;
+    /** Mostra la riga di apertura/chiusura della sidebar (nascosta su mobile: c'è il burger) */
+    withCollapseToggle: boolean;
+}
+/**
+ * Blocco in fondo alla sidebar del layout "modern".
+ *
+ * Il layout "modern" non ha la footer bar: qui vivono le informazioni essenziali che
+ * nel layout classico stanno nel footer (stato della connessione, stato utente,
+ * link all'amministrazione, versione) più il tracciamento dell'attività utente.
+ */
+export declare function ModernSidebarFooter({ appVersion, brandName, collapsed, withCollapseToggle, }: ModernSidebarFooterProps): import("react/jsx-runtime").JSX.Element;
+export default ModernSidebarFooter;

package/src/lib/layouts/shared/disconnection-overlay.d.ts

@@ -0,0 +1,12 @@
+export interface DisconnectionOverlayProps {
+    maxAttemptsReached: boolean;
+    reconnectAttempts: number;
+    isRetrying: boolean;
+    onRetry: () => Promise<void> | void;
+}
+/**
+ * Overlay di blocco applicazione mostrato quando la connessione WebSocket è persa.
+ * Condiviso da tutti i layout della shell.
+ */
+export declare function DisconnectionOverlay({ maxAttemptsReached, reconnectAttempts, isRetrying, onRetry, }: DisconnectionOverlayProps): import("react/jsx-runtime").JSX.Element;
+export default DisconnectionOverlay;

package/src/lib/layouts/shared/with-ravify-provider.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { FluxoClientConfiguration } from '@fluxo-dev/state';
+/**
+ * Wrapper condiviso dai layout della shell: il RavifyProvider viene montato
+ * solo per gli utenti con accesso amministrativo.
+ */
+export declare const WithRavifyProvider: React.FC<{
+    children: React.ReactNode;
+    hasAdminAccess: boolean;
+    fluxoClientConfig: FluxoClientConfiguration | null;
+}>;
+export default WithRavifyProvider;

package/src/lib/pages/login/forgot-password.d.ts

@@ -1,5 +1,9 @@
-import { ShellLoginConfig } from '../../app';
-export declare function ForgotPassword(props: {
+import { ShellLayoutVariant, ShellLoginConfig } from '../../app';
+export interface ForgotPasswordProps {
     loginConfig?: ShellLoginConfig;
-}): import("react/jsx-runtime").JSX.Element;
+    brandName?: string;
+    /** Variante di layout della shell: con `modern` usa la card centrata */
+    layout?: ShellLayoutVariant;
+}
+export declare function ForgotPassword(props: ForgotPasswordProps): import("react/jsx-runtime").JSX.Element;
 export default ForgotPassword;

package/src/lib/pages/login/login-page.d.ts

@@ -1,7 +1,12 @@
-import { ShellLoginConfig } from '../../app';
+import { ShellLayoutVariant, ShellLoginConfig } from '../../app';
 export interface LoginPageProps {
     brandName: string;
     loginConfig?: ShellLoginConfig;
+    /**
+     * Variante di layout della shell. Con {@link ShellLayoutVariant.Modern} la pagina
+     * usa la card centrata su sfondo scuro derivato dal brand.
+     */
+    layout?: ShellLayoutVariant;
 }
 declare function LoginPage(props: LoginPageProps): import("react/jsx-runtime").JSX.Element;
 export default LoginPage;

package/src/lib/pages/login/modern-auth-shell.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface ModernAuthShellProps {
+    brandName: string;
+    children: React.ReactNode;
+}
+/**
+ * Cornice delle pagine di autenticazione nel layout "modern": card centrata su
+ * sfondo scuro derivato dal brand.
+ *
+ * Il logo sta fuori dalla card di proposito: quello del brand è pensato per la
+ * sidebar colorata (tipicamente chiaro) e su fondo bianco rischierebbe di sparire.
+ */
+export declare function ModernAuthShell({ brandName, children }: ModernAuthShellProps): import("react/jsx-runtime").JSX.Element;
+export default ModernAuthShell;

package/src/lib/pages/login/reset-password.d.ts

@@ -1,2 +1,8 @@
-export declare function ResetPassword(): import("react/jsx-runtime").JSX.Element;
+import { ShellLayoutVariant } from '../../app';
+export interface ResetPasswordProps {
+    brandName?: string;
+    /** Variante di layout della shell: con `modern` usa la card centrata */
+    layout?: ShellLayoutVariant;
+}
+export declare function ResetPassword(props?: ResetPasswordProps): import("react/jsx-runtime").JSX.Element;
 export default ResetPassword;