this.gui 1.3.41 → 1.3.42

package/src/gui/Theme/Layout/Sidebars/LeftSidebar/LeftSidebar.stories.tsx

@@ -0,0 +1,199 @@
+import { StoryFn } from "@storybook/react";
+import React from "react";
+import Layout from "@/gui/Theme/Layout/Layout/Layout";
+import ThemeModeToggle from "@/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle";
+
+export default {
+  title: "Layout/Sidebars/LeftSidebar",
+  component: Layout,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+`The **LeftSidebar** component provides the navigation rail for ResponsiveUI layouts. It keeps content aligned with other structural elements (TopBar, RightSidebar) while offering a consistent spot for primary navigation and quick actions.
+---
+## Features
+- **Rail-first layout:** Starts in rail view by default to maximize canvas space while keeping icons reachable.
+- **Expanded navigation:** Users can switch to an expanded width for descriptive labels and nested menus.
+- **Mobile overlay:** On compact viewports it becomes a temporary drawer that overlays content and releases the left inset.
+- **Footer actions:** Optional \`footerElements\` allow secondary actions (e.g. settings, help) that stay pinned to the bottom.
+- **Inset sync:** Updates \`theme.layout.insets.left\` so surrounding layouts and the TopBar shift automatically.
+
+---
+## Layout Variants
+- \`rail\`: 72px icon rail, best for dense productivity layouts.
+- \`expanded\`: 264px panel with labels and nested menu support.
+- \`mobile\`: Drawer that covers the screen content and is controlled by a floating toggle button.
+The sidebar transitions between these modes automatically based on breakpoints, but you can also set them manually via \`useLeftSidebar()\`.
+
+---
+## Props
+- \`elements: LeftSidebarElement[]\` — Main navigation items. Supports \`link\`, \`menu\`, and \`action\` types.
+- \`footerElements?: LeftSidebarElement[]\` — Optional persistent actions rendered in the footer.
+- \`initialView?: 'rail' | 'expanded' | 'mobile'\` — Starting layout; defaults to \`rail\`.
+- \`className?, ...rest\` — Standard layout props forwarded to the root container.
+
+---
+## Declarative usage
+~~~tsx
+import LeftSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/LeftSidebar/LeftSidebar';
+
+<LeftSidebar
+  initialView="rail"
+  elements={[
+    { type: 'link', props: { label: 'Dashboard', icon: 'dashboard' } },
+    { type: 'link', props: { label: 'Analytics', icon: 'bar_chart' } },
+    {
+      type: 'menu',
+      props: {
+        label: 'Projects',
+        icon: 'folder',
+        items: [
+          { label: 'Active', icon: 'task' },
+          { label: 'Archive', icon: 'inventory_2' },
+        ],
+      },
+    },
+  ]}
+  footerElements={[
+    { type: 'link', props: { label: 'Settings', icon: 'settings' } },
+    { type: 'action', props: { label: 'Sign out', icon: 'logout' } },
+  ]}
+/>;
+~~~
+
+---
+## React usage
+Wrap your layout with \`LeftSidebarProvider\` and consume \`useLeftSidebar()\` to control the view programmatically:
+~~~tsx
+import { LeftSidebarProvider } from '@/gui/contexts';
+import LeftSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/LeftSidebar/LeftSidebar';
+import { useLeftSidebar } from '@/gui/hooks';
+
+const navItems = [
+  { type: 'link', props: { label: 'Dashboard', icon: 'dashboard' } },
+  { type: 'link', props: { label: 'Billing', icon: 'receipt_long' } },
+];
+
+function Shell() {
+  const { view, setView } = useLeftSidebar();
+  return (
+    <>
+      <button onClick={() => setView(view === 'expanded' ? 'rail' : 'expanded')}>
+        Toggle mode
+      </button>
+      <LeftSidebar elements={navItems} />
+    </>
+  );
+}
+
+export function AppShell() {
+  return (
+    <LeftSidebarProvider>
+      <Shell />
+    </LeftSidebarProvider>
+  );
+}
+~~~
+
+---
+## Notes
+- Mobile mode is triggered automatically below the \`sm\` breakpoint; the floating toggle re-opens the drawer.
+- The sidebar updates the global inset each time the view changes, keeping the TopBar and page content aligned.
+- Combine with the \`TopBar\` story to see how the two components cooperate in responsive layouts.
+`,
+      },
+    },
+  },
+};
+
+const Template: StoryFn<React.ComponentProps<typeof Layout>> = (args) => (
+  <Layout {...args} />
+);
+
+export const Default = Template.bind({});
+Default.args = {
+  topBarConfig: {
+    title: "My Application",
+    elementsRight: [
+      { type: "link", props: { label: "Profile", icon: "account_circle" } },
+      {
+        type: "action",
+        props: {
+          element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)" } },
+    ],
+  },
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Analytics", icon: "bar_chart", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-warning)",
+          items: [
+            { label: "Project A", icon: "work", iconColor: "var(--gui-success)" },
+            { label: "Project B", icon: "assignment", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)", action: "handleLogout" } },
+    ],
+  },
+};
+
+export const WithoutTopBar = Template.bind({});
+WithoutTopBar.args = {
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Analytics", icon: "bar_chart", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-warning)",
+          items: [
+            { label: "Project A", icon: "work", iconColor: "var(--gui-success)" },
+            { label: "Project B", icon: "assignment", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)", action: "handleLogout" } },
+    ],
+  },
+};
+
+export const WithFooter = Template.bind({});
+WithFooter.args = {
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Analytics", icon: "bar_chart", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-warning)",
+          items: [
+            { label: "Project A", icon: "work", iconColor: "var(--gui-success)" },
+            { label: "Project B", icon: "assignment", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)", action: "handleLogout" } },
+    ],
+    footerElements: [
+      { type: "link", props: { label: "Settings", icon: "settings", iconColor: "var(--gui-primary)" } },
+      { type: "action", props: { label: "Help", icon: "help", iconColor: "var(--gui-success)" } },
+    ],
+  },
+};

package/src/gui/Theme/Layout/Sidebars/LeftSidebar/LeftSidebar.tsx

@@ -0,0 +1,311 @@
+// LeftSidebar.tsx
+import clsx from 'clsx';
+import { useEffect, useState, useRef } from 'react';
+import IconButton from '@mui/material/IconButton';
+import Icon from '@/gui/Theme/Icon/Icon';
+import { LeftSidebarElement } from './LeftSidebar.types';
+import LeftSidebarLink from './components/LeftSidebarLink/LeftSidebarLink';
+import LeftSidebarMenu from './components/LeftSidebarMenu/LeftSidebarMenu';
+import LeftSidebarAction from './components/LeftSidebarAction/LeftSidebarAction';
+import LeftSidebarToggleButton from './components/LeftSidebarToggleButton/LeftSidebarToggleButton';
+import { useLeftSidebar, useGuiTheme, useGuiMediaQuery, useUpdateInsets, useInsets } from '@/gui/hooks';
+import { Box, Drawer } from '@/gui/components/atoms';
+import type { LeftSidebarView } from '@/gui/contexts';
+
+const LeftSidebar = ({
+  elements = [],
+  className,
+  initialView = 'rail',
+  footerElements = [],
+}: {
+  elements: LeftSidebarElement[];
+  className?: string;
+  initialView?: LeftSidebarView;
+  footerElements?: LeftSidebarElement[];
+}) => {
+  const { view, setView } = useLeftSidebar();
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down('sm'));
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [lastNonMobileView, setLastNonMobileView] = useState<LeftSidebarView>(view === 'mobile' ? 'expanded' : view);
+  const setInsets = useUpdateInsets();
+  const insets = useInsets();
+  const navInset = Math.max(0, Number(insets?.nav ?? insets?.top ?? 0));
+  const headerHeight = navInset > 0 ? navInset : 48;
+  const toggleOffset = (navInset > 0 ? navInset : 0) + 12;
+  const hasFooterElements = Array.isArray(footerElements) && footerElements.length > 0;
+  const initialViewApplied = useRef(false);
+
+  useEffect(() => {
+    if (typeof setInsets !== 'function') return;
+    const desired = view === 'expanded' ? 220 : view === 'rail' ? 72 : 0;
+    setInsets({ left: desired });
+    return () => setInsets({ left: 0 });
+  }, [setInsets, view]);
+
+  useEffect(() => {
+    initialViewApplied.current = false;
+  }, [initialView]);
+
+  useEffect(() => {
+    if (initialViewApplied.current) return;
+    if (initialView !== 'mobile') {
+      if (lastNonMobileView !== initialView) setLastNonMobileView(initialView);
+      if (!isMobile && view !== initialView) {
+        setView(initialView);
+      }
+    } else if (view !== 'mobile') {
+      setView('mobile');
+    }
+    initialViewApplied.current = true;
+  }, [initialView, isMobile, lastNonMobileView, setView, view]);
+
+  useEffect(() => {
+    if (view === 'expanded' || view === 'rail') {
+      setLastNonMobileView(view);
+    }
+  }, [view]);
+
+  useEffect(() => {
+    if (isMobile && view !== 'mobile') {
+      setView('mobile');
+    } else if (!isMobile && view === 'mobile') {
+      setView(lastNonMobileView);
+    }
+  }, [isMobile, lastNonMobileView, setView, view]);
+
+  useEffect(() => {
+    if (view !== 'mobile' && mobileOpen) {
+      setMobileOpen(false);
+    }
+  }, [mobileOpen, view]);
+
+  const renderElements = () =>
+    elements.map((el, idx) => {
+      if (el.type === 'link') return <LeftSidebarLink key={idx} view={view} {...el.props} />;
+      if (el.type === 'menu') return <LeftSidebarMenu key={idx} view={view} {...el.props} />;
+      if (el.type === 'action') return <LeftSidebarAction key={idx} view={view} {...el.props} />;
+      return null;
+    });
+  const renderFooterItems = () =>
+    footerElements.map((el, idx) => {
+      if (el.type === 'link') return <LeftSidebarLink key={`footer-link-${idx}`} view={view} {...el.props} />;
+      if (el.type === 'menu') return <LeftSidebarMenu key={`footer-menu-${idx}`} view={view} {...el.props} />;
+      if (el.type === 'action') return <LeftSidebarAction key={`footer-action-${idx}`} view={view} {...el.props} />;
+      return null;
+    });
+
+  if (view === 'rail') {
+    return (
+      <Box
+        component="aside"
+        className={clsx('LeftSidebar', className)}
+        sx={{
+          position: 'fixed',
+          top: 0,
+          left: 0,
+          bottom: 0,
+          height: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          width: '72px',
+          overflow: 'visible',
+          borderRight: '1px solid',
+          borderColor: 'divider',
+          '--gui-rail-width': '72px',
+          zIndex: (theme) => theme.zIndex.drawer + 2,
+          backgroundColor: 'background.nav',
+        }}
+      >
+        <Box
+          component="header"
+          sx={{
+            flexShrink: 0,
+            borderBottom: '1px solid',
+            borderColor: 'divider',
+            height: `${headerHeight}px`,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'flex-end',
+            px: 1.5,
+            py: 0,
+            gap: 1.25,
+          }}
+        >
+          <LeftSidebarToggleButton
+            expanded={view === ('expanded' as any)}
+            onToggle={() => setView(view === 'rail' ? 'expanded' : 'rail')}
+          />
+        </Box>
+        <Box sx={{ flexGrow: 1, overflowY: 'auto' }}>{renderElements()}</Box>
+        {hasFooterElements && (
+          <Box
+            component="footer"
+            sx={{
+              flexShrink: 0,
+              px: 1,
+              py: 1.5,
+                      borderColor: 'divider',
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 0.5,
+            }}
+          >
+            {renderFooterItems()}
+          </Box>
+        )}
+      </Box>
+    );
+  }
+
+  if (view === 'mobile') {
+    return (
+      <>
+        <Box
+          sx={{
+            position: 'fixed',
+            top: `${toggleOffset}px`,
+            left: 0,
+            zIndex: ((theme as any)?.zIndex?.drawer ?? 1200) + 1,
+            display: mobileOpen ? 'none' : 'flex',
+          }}
+        >
+          <IconButton
+            aria-label="Abrir navegación"
+            onClick={() => setMobileOpen(true)}
+            sx={{
+              borderRadius: '0 16px 16px 0',
+              border: '1px solid',
+              borderColor: 'divider',
+              bgcolor: 'background.paper',
+              color: 'text.secondary',
+              boxShadow: 3,
+              '&:hover': {
+                bgcolor: 'background.nav',
+                color: 'text.primary',
+              },
+            }}
+          >
+            <Icon name="menu" />
+          </IconButton>
+        </Box>
+        <Drawer
+          anchor="left"
+          open={mobileOpen}
+          onClose={() => setMobileOpen(false)}
+          variant="temporary"
+          ModalProps={{ keepMounted: true }}
+          sx={{
+            '& .MuiDrawer-paper': {
+              width: 220,
+              top: `${navInset}px`,
+              height: `calc(100vh - ${navInset}px)`,
+              display: 'flex',
+              flexDirection: 'column',
+              borderRight: '1px solid',
+              borderColor: 'divider',
+            },
+          }}
+        >
+          <Box
+            component="header"
+            sx={{
+              flexShrink: 0,
+              borderBottom: '1px solid',
+              borderColor: 'divider',
+              height: `${headerHeight}px`,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'flex-end',
+              px: 1.5,
+              gap: 1.25,
+            }}
+          >
+            <LeftSidebarToggleButton expanded onToggle={() => setMobileOpen(false)} />
+          </Box>
+          <Box sx={{ flexGrow: 1, overflowY: 'auto' }}>{renderElements()}</Box>
+          {hasFooterElements && (
+            <Box
+              component="footer"
+              sx={{
+                flexShrink: 0,
+                px: 1.5,
+                py: 1.5,
+                          borderColor: 'divider',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 0.75,
+              }}
+            >
+              {renderFooterItems()}
+            </Box>
+          )}
+        </Drawer>
+      </>
+    );
+  }
+
+  // Default to 'expanded' view
+  return (
+    <Box
+      component="aside"
+      className={clsx('LeftSidebar', className)}
+      sx={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        bottom: 0,
+        height: '100vh',
+        display: 'flex',
+        flexDirection: 'column',
+        width: '220px',
+        overflow: 'visible',
+        borderRight: '1px solid',
+        borderColor: 'divider',
+        '--gui-expanded-width': '220px',
+        backgroundColor: 'background.nav',
+        zIndex: (theme) => theme.zIndex.drawer + 2,
+      }}
+    >
+      <Box
+        component="header"
+        sx={{
+          flexShrink: 0,
+          borderBottom: '1px solid',
+          borderColor: 'divider',
+          height: `${headerHeight}px`,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'flex-end',
+          px: 1.5,
+          py: 0,
+          gap: 1.25,
+        }}
+      >
+        <LeftSidebarToggleButton
+          expanded={view === ('expanded' as any)}
+          onToggle={() => setView(view === 'expanded' ? 'rail' : 'expanded')}
+        />
+      </Box>
+      <Box sx={{ flexGrow: 1, overflowY: 'auto' }}>{renderElements()}</Box>
+      {hasFooterElements && (
+        <Box
+          component="footer"
+          sx={{
+            flexShrink: 0,
+            px: 1.5,
+            py: 1.5,
+                  borderColor: 'divider',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 0.75,
+          }}
+        >
+          {renderFooterItems()}
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+export default LeftSidebar;

package/src/gui/Theme/Layout/Sidebars/LeftSidebar/LeftSidebar.types.ts

@@ -0,0 +1,41 @@
+import { LeftSidebarView } from '@/gui/contexts';
+import { ReactNode } from 'react';
+export type LeftSidebarMode = 'rail' | 'expanded' | 'mobile';
+
+export type LeftSidebarProps = {
+  open?: boolean; // used in mobile
+  mode?: LeftSidebarMode;
+  onClose?: () => void;
+  items?: any[];
+  children?: ReactNode;
+  brand?: ReactNode;
+  footer?: ReactNode;
+  footerElements?: LeftSidebarElement[];
+  style?: React.CSSProperties;
+  className?: string;
+  enableCollapse?: boolean;
+  defaultExpanded?: boolean;
+  expandButton?: ReactNode;
+  drawerLinks?: any[];
+  collapsedWidth?: number;
+  expandedWidth?: number;
+  expanded?: boolean;
+  id?: string;
+  shouldShowToggle?: boolean;
+  railMode?: boolean;
+  toggleLocation?: 'sidebar' | 'topbar' | 'none';
+  header?: ReactNode;
+};
+
+export type LeftSidebarElement =
+  | { type: 'link'; props: Record<string, any> }
+  | { type: 'menu'; props: Record<string, any> }
+  | { type: 'action'; props: Record<string, any> };
+
+export type SidebarMode = LeftSidebarMode;
+export type SidebarSection = {
+  title?: string;
+  items: any[];
+};
+
+export type SidebarToggleHandler = () => void;

package/src/gui/Theme/Layout/Sidebars/LeftSidebar/SidebarToggleButton.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { Box, IconButton } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+import Icon from '@/themes/Icon/Icon';
+
+export interface SidebarToggleButtonProps {
+  expanded: boolean;
+  onToggle: () => void;
+  collapsedWidth?: number;
+  style?: React.CSSProperties;
+  location?: 'topbar' | 'sidebar' | 'none';
+  sx?: SxProps<Theme>;
+  forceRender?: boolean;
+}
+
+const SidebarToggleButton: React.FC<SidebarToggleButtonProps> = ({
+  expanded,
+  onToggle,
+  collapsedWidth = 72,
+  style,
+  location,
+  sx,
+}) => {
+  const [locationState, setLocation] = React.useState<'topbar' | 'sidebar' | 'none'>(location ?? 'none');
+
+  React.useEffect(() => {
+    if (location) {
+      setLocation(location);
+    }
+  }, [location]);
+
+  if (locationState === 'none') return null;
+
+  return (
+    <Box
+      sx={{
+        ...(locationState === 'topbar'
+          ? { display: 'flex', alignItems: 'center', justifyContent: 'center', px: 1 }
+          : { width: collapsedWidth, display: 'flex', justifyContent: 'center', py: 1 }),
+        ...sx,
+      }}
+      style={style}
+    >
+      <IconButton size="small" onClick={onToggle} aria-label={expanded ? 'Collapse sidebar' : 'Expand sidebar'}>
+        <span className="material-symbols-rounded" style={{ fontSize: 20 }}>
+          {expanded ? 'chevron_left' : 'chevron_right'}
+        </span>
+      </IconButton>
+    </Box>
+  );
+};
+
+export default SidebarToggleButton;

package/src/gui/Theme/Layout/Sidebars/LeftSidebar/components/LeftSidebarAction/LeftSidebarAction.resolver.tsx

@@ -0,0 +1,19 @@
+export default function resolveLeftSidebarAction({
+  action,
+  context,
+}: {
+  action: string | (() => any);
+  context?: any;
+}) {
+  try {
+    if (typeof action === 'function') return action();
+    if (typeof action === 'string') {
+      const fn = (window as any)[action];
+      if (typeof fn === 'function') return fn(context);
+      console.warn(`LeftSidebarAction: No global function found for "${action}"`);
+    }
+  } catch (err) {
+    console.error(`Error executing LeftSidebarAction for "${action}":`, err);
+  }
+  return undefined;
+}