this.gui 1.3.40 → 1.3.42

package/src/gui/Theme/Layout/Content/Content.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { Box } from '@/gui/components/atoms';
+import { useInsets } from '@/gui/hooks';
+import type { ContentProps } from './Content.types';
+
+const Content: React.FC<ContentProps> = ({ children }) => {
+  const insets = useInsets();
+  const safeTop = Math.max(0, Number(insets?.top ?? 0));
+  const navHeight = Math.max(0, Number(insets?.nav ?? 0));
+  const topInset = safeTop + navHeight;
+  const bottomInset = Math.max(0, Number(insets?.bottom ?? 0));
+  const leftInset = Math.max(0, Number(insets?.left ?? 0));
+  const rightInset = Math.max(0, Number(insets?.right ?? 0));
+
+  return (
+    <Box
+      id="content"
+      component="main"
+      sx={{
+        position: 'relative',
+        flex: 1,
+        display: 'flex',
+        flexDirection: 'column',
+        minHeight: 0,
+        width: '100%',
+        overflow: 'hidden',
+        paddingTop: `${topInset}px`,
+        paddingBottom: `${bottomInset}px`,
+        paddingLeft: `${leftInset}px`,
+        paddingRight: `${rightInset}px`,
+        boxSizing: 'border-box',
+        backgroundColor: 'background.default',
+        transition: 'padding 0.3s ease',
+      }}
+    >
+      <Box
+        sx={{
+          flex: 1,
+          minHeight: 0,
+          width: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          overflowY: 'auto',
+          overflowX: 'hidden',
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+};
+
+export default Content;

package/src/gui/Theme/Layout/Content/Content.types.tsx

@@ -0,0 +1,40 @@
+import type React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export type ContentSection = {
+  type: string;
+  props?: Record<string, any>;
+  children?: ContentSection[];
+};
+
+export interface ContentProps {
+  /**
+   * Array of layout sections or components to render within the Content area.
+   */
+  sections?: ContentSection[];
+
+  /**
+   * Optional unique identifier.
+   */
+  id?: string;
+
+  /**
+   * Custom CSS class name for additional styling.
+   */
+  className?: string;
+
+  /**
+   * Optional style overrides for the main container.
+   */
+  sx?: SxProps<Theme>;
+
+  /**
+   * Optional data-testid for testing purposes.
+   */
+  'data-testid'?: string;
+
+  /**
+   * Optional React children that can be rendered directly.
+   */
+  children?: React.ReactNode;
+}

package/src/gui/Theme/Layout/Footer/Footer.resolver.tsx

@@ -0,0 +1,45 @@
+import * as React from 'react';
+import type { RegistryEntry } from '@/gui/registry/types';
+import Footer from './Footer';
+import type { FooterElement } from './Footer.types';
+
+type FooterSpec = {
+  type: 'Footer';
+  props?: {
+    brandLabel?: string;
+    brandLogo?: string;
+    brandHref?: string;
+    leftElements?: FooterElement[];
+    centerElements?: FooterElement[];
+    rightElements?: FooterElement[];
+    position?: 'static' | 'fixed' | 'sticky';
+    elevation?: number;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+  };
+};
+
+const FooterResolver: RegistryEntry = {
+  type: 'Footer',
+  resolve(spec: FooterSpec) {
+    const props = spec.props ?? {};
+    return (
+      <Footer
+        brandLabel={props.brandLabel}
+        brandLogo={props.brandLogo}
+        brandHref={props.brandHref}
+        leftElements={props.leftElements}
+        centerElements={props.centerElements}
+        rightElements={props.rightElements}
+        position={props.position}
+        elevation={props.elevation}
+        className={props.className}
+        id={props.id}
+        data-testid={props['data-testid']}
+      />
+    );
+  },
+};
+
+export default FooterResolver;

package/src/gui/Theme/Layout/Footer/Footer.stories.tsx

@@ -0,0 +1,205 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Footer from "./Footer";
+import Layout from "@/gui/Theme/Layout/Layout/Layout";
+import ThemeModeToggle from "@/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle";
+
+const meta: Meta<typeof Footer> = {
+  title: "Layout/Footer/Footer",
+  component: Footer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+`The **Footer** component serves as a foundational UI element that anchors actions and secondary navigation at the bottom of the viewport, while seamlessly integrating with responsive layouts and respecting insets caused by sidebars and other layout elements.
+
+---
+## Declarative Usage
+You can declare the Footer directly in JSX by passing branding information and arrays of elements for the left, center, and right zones. Each element can be a link or an action, allowing flexible customization of navigation and controls.
+
+---
+## Responsive React Layout Integration
+The Footer automatically adjusts its width and position based on the presence of left and right sidebars, ensuring it does not overlap with other UI components. It also adapts to different screen sizes by hiding labels on tablet and mobile views, showing only icons with tooltips for accessibility.
+
+---
+## Props Overview
+- \`brandLabel\`: Text label representing the brand, used as fallback or alongside the logo.
+- \`brandLogo\`: URL or path to the brand logo image.
+- \`brandHref\`: Link URL for the brand element, typically the home page.
+- \`leftElements\`, \`centerElements\`, \`rightElements\`: Arrays of elements defining the content for each segment of the footer. Each element is an object with a \`type\` ('link' or 'action') and \`props\` defining its properties such as label, icon, href, and event handlers.
+
+---
+## Features
+- **Inset-aware:** Automatically offsets its width to accommodate left and right sidebars, avoiding overlap.
+- **Responsive Design:** Collapses labels to icons only on smaller screens, maintaining usability and accessibility with tooltips.
+- **Segmented Layout:** Divides the footer into three distinct zones (left, center, right) for organized content placement.
+- **Flexible Positioning:** Supports \`static\`, \`fixed\`, and \`sticky\` positioning modes to suit various layout needs.
+- **Customizable Styling:** Allows style overrides via \`sx\`, \`appBarSx\`, and \`sectionSx\` for fine-grained control.
+
+---
+## Layout Zones
+- **Left Zone:** Typically contains branding and primary links.
+- **Center Zone:** Ideal for documentation links, community resources, or other central navigation.
+- **Right Zone:** Often used for actions such as theme toggles or contact buttons.
+
+---
+## Responsiveness
+Below the \`md\` breakpoint, the Footer hides text labels and displays only icons, preserving space and clarity on smaller devices. Tooltips are provided to maintain accessibility despite the reduced label visibility.
+
+---
+## Integration Tips
+- Combine the Footer with responsive layout shells that include TopBar and Sidebars to maintain consistent insets and layout harmony.
+- Use the \`position="fixed"\` prop to create persistent footers that remain visible and update the global bottom inset dynamically.
+- Leverage the segmented layout to organize navigation and actions intuitively.
+
+---
+## Example: Declarative Usage
+~~~tsx
+<Footer
+  brandLabel="Neuroverse"
+  brandLogo="/logo.svg"
+  leftElements={[
+    { type: 'link', props: { label: 'Changelog', icon: 'history', href: '/changelog' } },
+  ]}
+  centerElements={[
+    { type: 'link', props: { label: 'Docs', icon: 'menu_book', href: '/docs' } },
+    { type: 'link', props: { label: 'Community', icon: 'forum', href: '/community', external: true } },
+  ]}
+  rightElements={[
+    { type: 'action', props: { label: 'Toggle Theme', icon: 'dark_mode', onClick: toggleMode } },
+  ]}
+/>
+~~~
+
+---
+## Example: React Integration with Layout
+~~~tsx
+<Layout
+  topBarConfig={{
+    title: "Responsive Shell",
+    elementsRight: [
+      {
+        type: "action",
+        props: {
+          element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+        },
+      },
+    ],
+  }}
+  leftSidebarConfig={{
+    elements: [
+      { type: "link", props: { label: "Overview", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Reports", icon: "insights", iconColor: "var(--gui-secondary)" } },
+    ],
+  }}
+  rightSidebarConfig={{
+    elements: [
+      { type: "link", props: { label: "Alerts", icon: "notifications", iconColor: "var(--gui-warning)" } },
+      { type: "action", props: { label: "Export", icon: "download", iconColor: "var(--gui-success)" } },
+    ],
+  }}
+  footerConfig={{
+    title: "Neuroverse",
+    logoSrc: "/logo.svg",
+    links: [
+      { name: "Docs", url: "/docs", icon: "menu_book" },
+      { name: "API", url: "/api", icon: "code" },
+    ],
+    socialLinks: [
+      { name: "GitHub", url: "https://github.com", icon: "code" },
+      { name: "Community", url: "https://community.neuroverse.ai", icon: "forum" },
+    ],
+    position: "fixed",
+  }} 
+>
+  {/* Main content goes here */}
+</Layout>
+~~~
+`,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Footer>;
+
+export const Default: Story = {
+  args: {
+    brandLabel: "Neuroverse",
+    brandLogo: "https://neurons.me/neurons.me.png",
+    brandHref: "/",
+    leftElements: [
+      { type: "link", props: { label: "Status", icon: "monitor_heart", href: "/status", iconColor: "var(--gui-info)" } },
+      { type: "link", props: { label: "Changelog", icon: "history", href: "/changelog", iconColor: "var(--gui-warning)" } },
+    ],
+    centerElements: [
+      { type: "link", props: { label: "Docs", icon: "menu_book", href: "/docs", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Community", icon: "forum", href: "https://community.neuroverse.ai", external: true, iconColor: "var(--gui-secondary)" } },
+    ],
+    rightElements: [
+      { type: "action", props: { label: "Contact", icon: "support_agent", iconColor: "var(--gui-success)" } },
+      { type: "action", props: { label: "Theme", icon: "dark_mode", iconColor: "var(--gui-primary)" } },
+    ],
+    position: "static",
+  },
+};
+
+export const FixedFooter: Story = {
+  args: {
+    ...Default.args,
+    position: "fixed",
+  },
+};
+
+export const WithLayout: Story = {
+  render: () => (
+    <Layout
+      topBarConfig={{
+        title: "Responsive Shell",
+        elementsRight: [
+          {
+            type: "action",
+            props: {
+              element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+            },
+          },
+        ],
+      }}
+      leftSidebarConfig={{
+        elements: [
+          { type: "link", props: { label: "Overview", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+          { type: "link", props: { label: "Reports", icon: "insights", iconColor: "var(--gui-secondary)" } },
+        ],
+      }}
+      rightSidebarConfig={{
+        elements: [
+          { type: "link", props: { label: "Alerts", icon: "notifications", iconColor: "var(--gui-warning)" } },
+          { type: "action", props: { label: "Export", icon: "download", iconColor: "var(--gui-success)" } },
+        ],
+      }}
+      footerConfig={ {
+        title: "Neuroverse",
+        logoSrc: "https://neurons.me/neurons.me.png",
+        links: [
+          { name: "Docs", url: "/docs", icon: "menu_book" },
+          { name: "API", url: "/api", icon: "code" },
+        ],
+        socialLinks: [
+          { name: "GitHub", url: "https://github.com", icon: "code" },
+          { name: "Community", url: "https://community.neuroverse.ai", icon: "forum" },
+        ],
+        position: "fixed",
+      } as any}
+    >
+      <div style={{ minHeight: '120vh', padding: '72px 24px 120px' }}>
+        <h2 style={{ marginBottom: 16 }}>Dashboard Content</h2>
+        <p>
+          Resize the viewport to see how the TopBar, LeftSidebar, RightSidebar, and Footer coordinate
+          their insets. The footer collapses labels below the medium breakpoint while keeping icons and
+          tooltips.
+        </p>
+      </div>
+    </Layout>
+  ),
+};

package/src/gui/Theme/Layout/Footer/Footer.tsx

@@ -0,0 +1,337 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { AppBar, Box, Toolbar, Typography, Avatar, Tooltip } from '@/gui/components/atoms';
+import { Link as RouterLink } from 'react-router-dom';
+import Icon from '@/gui/Theme/Icon/Icon';
+import { useGuiTheme, useGuiMediaQuery, useInsets, useUpdateInsets } from '@/gui/hooks';
+import type { FooterProps, FooterElement } from './Footer.types';
+import type { FooterLinkProps, FooterActionProps } from './Footer.types';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+const sxN = (...parts: Array<SxProps<Theme> | undefined>): SxProps<Theme> =>
+  (parts.filter(Boolean) as unknown) as SxProps<Theme>;
+
+type FooterLinkRenderProps = FooterLinkProps & {
+  showLabel: boolean;
+};
+
+type FooterActionRenderProps = FooterActionProps & {
+  showLabel: boolean;
+};
+
+const FooterLink = ({
+  label,
+  icon,
+  iconColor,
+  href,
+  external,
+  onClick,
+  showLabel,
+}: FooterLinkRenderProps) => {
+  const content = (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: showLabel ? 1 : 0,
+        color: 'inherit',
+        textDecoration: 'none',
+        px: showLabel ? 1.5 : 0.75,
+        py: 0.75,
+        borderRadius: 1,
+        transition: 'background-color 0.2s ease, color 0.2s ease',
+        '&:hover': {
+          backgroundColor: 'action.hover',
+        },
+      }}
+    >
+      {icon && <Icon name={icon} iconColor={iconColor} />}
+      {showLabel && label && (
+        <Typography variant="body2" sx={{ fontWeight: 500 }}>
+          {label}
+        </Typography>
+      )}
+    </Box>
+  );
+
+  const wrappedContent =
+    !showLabel && label ? (
+      <Tooltip title={label} placement="top">
+        <span style={{ display: 'inline-flex' }}>{content}</span>
+      </Tooltip>
+    ) : (
+      content
+    );
+
+  const commonProps = {
+    onClick,
+    style: { color: 'inherit' },
+  };
+
+  if (href) {
+    const component = href.startsWith('http')
+      ? 'a'
+      : RouterLink;
+    return (
+      <Box
+        component={component as any}
+        to={!href.startsWith('http') ? href : undefined}
+        href={href.startsWith('http') ? href : undefined}
+        target={external ? '_blank' : undefined}
+        rel={external ? 'noopener noreferrer' : undefined}
+        sx={{ display: 'inline-flex' }}
+        {...commonProps}
+      >
+        {wrappedContent}
+      </Box>
+    );
+  }
+
+  return (
+    <Box component="button" type="button" sx={{ display: 'inline-flex', background: 'none', border: 'none', p: 0 }} {...commonProps}>
+      {wrappedContent}
+    </Box>
+  );
+};
+
+const FooterAction = ({
+  label,
+  icon,
+  iconColor,
+  onClick,
+  element,
+  showLabel,
+}: FooterActionRenderProps) => {
+  if (element) {
+    return <Box sx={{ display: 'inline-flex', alignItems: 'center' }}>{element}</Box>;
+  }
+
+  const content = (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: showLabel ? 1 : 0,
+        px: showLabel ? 1.5 : 0.75,
+        py: 0.75,
+        borderRadius: 1,
+        transition: 'background-color 0.2s ease',
+        '&:hover': { backgroundColor: 'action.hover' },
+        color: 'inherit',
+      }}
+      onClick={onClick}
+      role="button"
+    >
+      {icon && <Icon name={icon} iconColor={iconColor} />}
+      {showLabel && label && (
+        <Typography variant="body2" sx={{ fontWeight: 500 }}>
+          {label}
+        </Typography>
+      )}
+    </Box>
+  );
+
+  if (!showLabel && label) {
+    return (
+      <Tooltip title={label} placement="top">
+        <span style={{ display: 'inline-flex' }}>{content}</span>
+      </Tooltip>
+    );
+  }
+
+  return content;
+};
+
+function renderFooterElement(el: FooterElement, showLabel: boolean, key: string | number) {
+  if (el.type === 'link') return <FooterLink key={key} {...el.props} showLabel={showLabel} />;
+  if (el.type === 'action') return <FooterAction key={key} {...el.props} showLabel={showLabel} />;
+  return null;
+}
+
+export default function Footer(props: FooterProps) {
+  const {
+    brandLabel = '',
+    brandLogo = '',
+    brandHref = '/',
+    brandAvatarFallback,
+    leftElements = [],
+    centerElements = [],
+    rightElements = [],
+    position = 'static',
+    elevation = 0,
+    className,
+    id,
+    sx,
+    appBarSx,
+    sectionSx,
+    'data-testid': dataTestId,
+  } = props;
+
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down('sm'));
+  const isTablet = useGuiMediaQuery(theme.breakpoints.between('sm', 'md'));
+  const isDesktop = useGuiMediaQuery(theme.breakpoints.up('md'));
+  const showLabels = isDesktop;
+  const showBrandLabel = !isMobile;
+
+  const insets = useInsets();
+  const updateInsets = useUpdateInsets();
+  const toolbarRef = useRef<HTMLDivElement | null>(null);
+  const appBarRef = useRef<HTMLDivElement | null>(null);
+
+  const insetLeft = Math.max(0, Number(insets?.left ?? 0));
+  const insetRight = Math.max(0, Number(insets?.right ?? 0));
+  const horizontalInset = insetLeft + insetRight;
+
+  const brandVisual = useMemo(() => {
+    if (brandLogo) {
+      return <Box component="img" src={brandLogo} alt={brandLabel ? `${brandLabel} logo` : 'Footer logo'} sx={{ height: 24 }} />;
+    }
+    const fallback = brandAvatarFallback || brandLabel?.trim().charAt(0)?.toUpperCase() || '?';
+    return <Avatar sx={{ width: 28, height: 28, fontSize: '0.875rem' }}>{fallback}</Avatar>;
+  }, [brandAvatarFallback, brandLabel, brandLogo]);
+
+  useEffect(() => {
+    if (typeof updateInsets !== 'function') return;
+    const measure = () => {
+      const target = appBarRef.current ?? toolbarRef.current;
+      const h = target?.offsetHeight ?? 56;
+      updateInsets({ bottom: position === 'fixed' || position === 'sticky' ? h : 0 });
+    };
+    measure();
+
+    let ro: ResizeObserver | undefined;
+    if (typeof ResizeObserver !== 'undefined') {
+      const target = appBarRef.current ?? toolbarRef.current;
+      if (target) {
+        ro = new ResizeObserver(() => measure());
+        ro.observe(target);
+      }
+    }
+
+    return () => {
+      if (ro) ro.disconnect();
+      updateInsets({ bottom: 0 });
+    };
+  }, [position, updateInsets, isMobile, isTablet]);
+
+  const isFixed = position === 'fixed' || position === 'sticky';
+  const baseAppBarSx = {
+    top: 'auto',
+    bottom: 0,
+    backgroundColor: theme.palette.background.paper ?? theme.palette.grey[900],
+    borderTop: '1px solid',
+    borderColor: theme.palette.divider,
+    minHeight: 56,
+    zIndex: (theme.zIndex?.appBar ?? 1100) - 1,
+    boxShadow: 'none',
+    ...(isFixed
+      ? {
+          position: 'fixed',
+          left: `${insetLeft}px`,
+          right: `${insetRight}px`,
+          width: `calc(100% - ${horizontalInset}px)`,
+          transition: 'left 0.3s ease, right 0.3s ease, width 0.3s ease',
+        }
+      : {
+          position: 'static',
+          left: `${insetLeft}px`,
+          right: `${insetRight}px`,
+          width: `calc(100% - ${horizontalInset}px)`,
+          transition: 'margin-left 0.3s ease, margin-right 0.3s ease, width 0.3s ease',
+        }),
+  } as const;
+
+  const flowAppBarSx = !isFixed
+    ? ({
+        ml: `${insetLeft}px`,
+        mr: `${insetRight}px`,
+        width: `calc(100% - ${horizontalInset}px)`,
+        transition: 'margin-left 0.3s ease, margin-right 0.3s ease, width 0.3s ease',
+      } as SxProps<Theme>)
+    : undefined;
+
+  return (
+    <AppBar
+      ref={appBarRef}
+      id={id}
+      className={className}
+      data-testid={dataTestId}
+      position={position}
+      elevation={elevation}
+      sx={sxN(baseAppBarSx as SxProps<Theme>, flowAppBarSx, sx, appBarSx)}
+    >
+      <Toolbar
+        ref={toolbarRef}
+        variant="dense"
+        disableGutters
+        sx={sxN(
+          {
+            minHeight: 56,
+            px: 1.5,
+            py: 1,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 1.5,
+          },
+          sectionSx
+        )}
+      >
+        <Box
+          sx={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: showLabels ? 1 : 0.5,
+            color: 'text.secondary',
+            flexShrink: 0,
+          }}
+        >
+          {leftElements.map((el, idx) => renderFooterElement(el, showLabels, `left-${idx}`))}
+        </Box>
+
+        <Box
+          sx={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: showLabels ? 1 : 0.5,
+            flex: 1,
+            justifyContent: 'center',
+            color: 'text.secondary',
+          }}
+        >
+          {centerElements.map((el, idx) => renderFooterElement(el, showLabels, `center-${idx}`))}
+        </Box>
+
+        <Box
+          sx={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: showLabels ? 1 : 0.75,
+            color: 'text.secondary',
+            flexShrink: 0,
+          }}
+        >
+          {rightElements.map((el, idx) => renderFooterElement(el, showLabels, `right-${idx}`))}
+          <Box
+            sx={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: showBrandLabel ? 1 : 0.75,
+              textDecoration: 'none',
+              color: 'inherit',
+            }}
+            component={brandHref ? RouterLink : 'div'}
+            to={brandHref ? brandHref : undefined}
+          >
+            {brandVisual}
+            {showBrandLabel && brandLabel && (
+              <Typography variant="body2" sx={{ fontWeight: 600 }}>
+                {brandLabel}
+              </Typography>
+            )}
+          </Box>
+        </Box>
+      </Toolbar>
+    </AppBar>
+  );
+}