this.gui 1.3.22 → 1.3.26

package/src/gui/Layouts/ResponsiveUI/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>
+  );
+}

package/src/gui/Layouts/ResponsiveUI/Footer/Footer.types.ts

@@ -0,0 +1,40 @@
+import type React from 'react';
+
+export type FooterLinkProps = {
+  label?: string;
+  href?: string;
+  icon?: string;
+  iconColor?: string;
+  external?: boolean;
+  onClick?: () => void;
+};
+
+export type FooterActionProps = {
+  label?: string;
+  icon?: string;
+  iconColor?: string;
+  onClick?: () => void;
+  element?: React.ReactNode;
+};
+
+export type FooterElement =
+  | { type: 'link'; props: FooterLinkProps }
+  | { type: 'action'; props: FooterActionProps };
+
+export type FooterProps = {
+  brandLabel?: string;
+  brandLogo?: string;
+  brandHref?: string;
+  brandAvatarFallback?: string;
+  leftElements?: FooterElement[];
+  centerElements?: FooterElement[];
+  rightElements?: FooterElement[];
+  position?: 'static' | 'fixed' | 'sticky';
+  elevation?: number;
+  className?: string;
+  id?: string;
+  'data-testid'?: string;
+  sx?: any;
+  appBarSx?: any;
+  sectionSx?: any;
+};

package/src/gui/Layouts/ResponsiveUI/Layout/Layout.resolver.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import Layout from './Layout';
+import type { RegistryEntry } from '@/registry/types';
+import type { LayoutSpec } from './Layout.types';
+/**
+ * The LayoutResolver dynamically constructs a responsive layout
+ * using declarative JSON configuration.
+ *
+ * It resolves topBar, sidebars, footer, and content sections
+ * by passing their configs into the Layout component.
+ */
+const LayoutResolver: RegistryEntry = {
+  type: 'Layout',
+  resolve(spec: LayoutSpec) {
+    const props = spec.props ?? {};
+    const contentSections = spec.Content ?? [];
+    return (
+      <Layout
+        {...props}
+      >
+        {contentSections.map((section, index) => (
+          <React.Fragment key={index}>
+            {Array.isArray(section.children)
+              ? section.children.map((child, i) => (
+                  <div key={`${index}-${i}`} {...(child.props ?? {})}>
+                    {child.type}
+                  </div>
+                ))
+              : null}
+          </React.Fragment>
+        ))}
+      </Layout>
+    );
+  },
+};
+
+export default LayoutResolver;

package/src/gui/Layouts/ResponsiveUI/Layout/Layout.stories.tsx

@@ -0,0 +1,290 @@
+import React from "react";
+import type { Meta, StoryFn, StoryObj } from "@storybook/react";
+import Layout from "./Layout";
+import Page from '@/gui/components/molecules/Page/Page';
+import ThemeModeToggle from "@/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle";
+
+const meta: Meta<typeof Layout> = {
+  title: "Layouts/ResponsiveUI/Layout",
+  component: Layout,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Layout** component wires the responsive shell used across This.GUI demos. It coordinates the TopBar, left/right sidebars, and Footer so their insets remain in sync while your application content renders inside.
+---
+## Features
+- **Context wiring** – wraps children with the required providers (LeftSidebar, RightSidebar) so hooks and insets work automatically.
+- **Composable regions** – optional \`topBarConfig\`, \`leftSidebarConfig\`, \`rightSidebarConfig\`, and \`footerConfig\` let you enable only what you need.
+- **Inset aware** – whenever a sidebar expands or collapses, the layout updates theme insets so the TopBar/Footer and main content stay aligned.
+- **Story-friendly** – serves as an orchestration helper in Storybook; in production you can lift the same pattern to your app shell.
+
+---
+## Declarative usage
+~~~json
+{
+  "type": "Layout",
+  "props": {
+    "topBarConfig": {
+      "title": "Workspace",
+      "elementsRight": [
+        {
+          "type": "action",
+          "props": {
+            "element": "ThemeModeToggle"
+          }
+        }
+      ]
+    },
+    "leftSidebarConfig": {
+      "elements": [
+        {
+          "type": "link",
+          "props": {
+            "label": "Dashboard",
+            "icon": "dashboard"
+          }
+        },
+        {
+          "type": "menu",
+          "props": {
+            "label": "Projects",
+            "icon": "folder",
+            "items": [
+              {
+                "label": "Project A",
+                "icon": "work"
+              },
+              {
+                "label": "Project B",
+                "icon": "assignment"
+              }
+            ]
+          }
+        }
+      ]
+    },
+    "footerConfig": {
+      "brandLabel": "Neuroverse",
+      "centerElements": [
+        {
+          "type": "link",
+          "props": {
+            "label": "Docs",
+            "href": "/docs",
+            "icon": "menu_book"
+          }
+        }
+      ]
+    }
+  },
+  "Content": [
+    {
+      "children": [
+        {
+          "type": "Section",
+          "props": {
+            "title": "Overview"
+          }
+        },
+        {
+          "type": "Card",
+          "props": {
+            "title": "AI Metrics"
+          }
+        }
+      ]
+    }
+  ]
+}
+~~~
+
+---
+## React usage
+Use the layout as a shell around your routes or dashboard pages. Pass config objects when you need a region; use \`false\` to omit it.
+~~~tsx
+function DashboardPage() {
+  return (
+    <Layout
+      topBarConfig={{
+        title: "Analytics",
+        elementsRight: [
+          { type: "action", props: { element: <ThemeModeToggle variant="minimal" /> } },
+        ],
+      }}
+      leftSidebarConfig={{
+        elements: [
+          { type: "link", props: { label: "Overview", icon: "home" } },
+          { type: "link", props: { label: "Reports", icon: "insights" } },
+        ],
+      }}
+      rightSidebarConfig={{
+        elements: [
+          { type: "link", props: { label: "Alerts", icon: "notifications" } },
+        ],
+      }}
+    >
+      <Outlet />
+    </Layout>
+  );
+}
+~~~
+
+---
+## Notes
+- Config objects mirror the props of the individual components (TopBar, LeftSidebar, RightSidebar, Footer). Anything you can pass there can be forwarded through the layout.
+- Set a config to \`false\` (or omit it) to exclude that region entirely.
+- Children render in document order beneath any enabled sidebars/top bar – for sticky layouts remember to add padding or section containers as shown below.
+`,
+      },
+    },
+  },
+};
+
+export default meta;
+
+const Template: StoryFn<React.ComponentProps<typeof Layout>> = (args) => (
+  <Layout {...args}>
+    <div
+      style={{
+        minHeight: "120vh",
+        padding: "72px 24px 120px",
+        display: "flex",
+        flexDirection: "column",
+        gap: 16,
+      }}
+    >
+      <h2>Responsive Layout Demo</h2>
+      <p>
+        Resize the viewport or toggle sidebars to observe how insets are coordinated.
+        The content block is intentionally tall to show how fixed bars interact with scrolling.
+      </p>
+    </div>
+  </Layout>
+);
+
+type Story = StoryObj<typeof Layout>;
+
+export const TopOnly: Story = {
+  render: Template,
+  args: {
+    topBarConfig: {
+      title: "Neuroverse",
+      elementsRight: [
+        {
+          type: "action",
+          props: {
+            element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+          },
+        },
+      ],
+    },
+    leftSidebarConfig: false,
+    rightSidebarConfig: false,
+    footerConfig: false,
+  },
+};
+
+export const TopWithLeftSidebar: Story = {
+  render: Template,
+  args: {
+    ...TopOnly.args,
+    leftSidebarConfig: {
+      elements: [
+        { type: "link", props: { label: "Overview", icon: "dashboard" } },
+        {
+          type: "menu",
+          props: {
+            label: "Projects",
+            icon: "folder",
+            items: [
+              { label: "Project Alpha", icon: "work" },
+              { label: "Project Beta", icon: "assignment" },
+            ],
+          },
+        },
+      ],
+      footerElements: [
+        { type: "link", props: { label: "Settings", icon: "settings" } },
+      ],
+    },
+  },
+};
+
+export const TopWithLeftAndRight: Story = {
+  render: Template,
+  args: {
+    ...TopWithLeftSidebar.args,
+    rightSidebarConfig: {
+      elements: [
+        { type: "link", props: { label: "Activity", icon: "history" } },
+        { type: "action", props: { label: "Export", icon: "download" } },
+      ],
+    },
+  },
+};
+
+export const FullShellWithFooter: Story = {
+  render: Template,
+  args: {
+    ...TopWithLeftAndRight.args,
+    footerConfig: {
+      brandLabel: "Neuroverse",
+      brandLogo: "https://neurons.me/neurons.me.png",
+      centerElements: [
+        { type: "link", props: { label: "Docs", href: "/docs", icon: "menu_book", iconColor: "var(--gui-primary)" } },
+        { type: "link", props: { label: "API", href: "/api", icon: "code", iconColor: "var(--gui-secondary)" } },
+      ],
+      rightElements: [
+        { type: "link", props: { label: "Community", href: "https://community.neuroverse.ai", icon: "forum", iconColor: "var(--gui-info)", external: true } },
+        { type: "link", props: { label: "GitHub", href: "https://github.com", icon: "code", iconColor: "var(--gui-warning)", external: true } },
+      ],
+      position: "fixed",
+    },
+  },
+};
+
+export const ContentOnly: Story = {
+  render: Template,
+  args: {
+    topBarConfig: false,
+    leftSidebarConfig: false,
+    rightSidebarConfig: false,
+    footerConfig: false,
+  },
+};
+
+
+export const LayoutWithPage: Story = {
+  render: () => (
+    <Layout
+      topBarConfig={{ title: 'Neuroverse Workspace' }}
+      leftSidebarConfig={{
+        elements: [
+          { type: 'link', props: { label: 'Home', icon: 'home' } },
+          { type: 'link', props: { label: 'Analytics', icon: 'insights' } },
+        ],
+      }}
+      rightSidebarConfig={{
+        elements: [
+          { type: 'link', props: { label: 'Chat', icon: 'chat' } },
+        ],
+      }}
+      footerConfig={{
+        brandLabel: 'Neuroverse',
+        centerElements: [
+          { type: 'link', props: { label: 'Docs', icon: 'menu_book' } },
+        ],
+      }}
+    >
+      <Page background="linear-gradient(135deg, #0a192f, #172a45)" padding={4}>
+        <h2 style={{ color: 'white', marginBottom: 16 }}>Page inside Layout</h2>
+        <p style={{ color: 'white', maxWidth: 600 }}>
+          This example shows how a Page component can be used inside the responsive Layout,
+          automatically adapting to inset updates from the TopBar, sidebars, and Footer.
+        </p>
+      </Page>
+    </Layout>
+  ),
+};