this.gui 1.0.17 → 1.1.0

package/src/gui/molecules/AppBars/TopBar/TopBar.stories.tsx

@@ -0,0 +1,297 @@
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '../../../../context/GuiProvider';
+import TopBar from './TopBar';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta = {
+  title: 'Molecules/AppBars/TopBar',
+  component: TopBar,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <Story />
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+`The **TopBar** component provides a responsive, application top bar for navigation, branding and other actions.
+---
+## Features
+- **Branding:** Display a logo and title.
+- **Navigation Links:** With optional icons and dropdown menus (nested children).
+- **Custom actions:** Theme toggle, hamburger menu, etc.
+- **Responsive:** Adapts to mobile layouts.
+- **Inset-aware:** Reads global left/right/nav insets from the theme to align with permanent drawers.
+- **Icon support:** Via the This.GUI icon registry (declarative strings) or direct React elements.
+
+---
+
+### Props
+Each link can specify:
+  - \`label\` (string): Displayed text.
+  - \`href\` (string): Navigation URL (internal or external).
+  - \`icon\` (string): Icon name, prefixed with \`mui:\` or \`lucide:\`.
+  - \`iconColor\` (string): Icon color (theme key like \`primary\`, \`secondary\`, or any CSS color).
+  - \`children\` (array): Nested links for dropdown menus.
+---
+
+**Example:**
+~~~jsx
+<TopBar
+  title="neurons.me"
+  logo="https://neurons.me/neurons.me.png"
+  TopBarLinks={[
+    { label: 'Home', href: '/', icon: 'mui:BarChart', iconColor: 'primary' },
+    { label: 'Docs', href: '/docs', icon: 'mui:Insights', iconColor: 'secondary' },
+    {
+      label: 'More',
+      icon: 'lucide:Info',
+      iconColor: '#00aa96',
+      children: [
+        { label: 'About', href: '/about', icon: 'mui:Message', iconColor: 'info' },
+        { label: 'Contact', href: '/contact', icon: 'lucide:Mail', iconColor: '#4caf50' },
+      ],
+    },
+  ]}
+  showThemeToggle
+  position="fixed"
+/>
+~~~
+
+---
+
+#### Dropdown Menus
+- To create a dropdown, provide a \`children\` array to any link.
+
+~~~jsx
+<TopBar
+  TopBarLinks={[
+    {
+      label: 'More',
+      icon: 'lucide:Info',
+      children: [
+        { label: 'About', href: '/about' },
+        { label: 'Contact', href: '/contact' },
+      ],
+    },
+  ]}
+/>
+~~~
+
+---
+
+#### Icon Usage
+- **Material UI:** Use \`mui:IconName\` (e.g. \`mui:Insights\`). See [MUI Icons Catalog](https://mui.com/material-ui/material-icons/).
+- **Lucide:** Use \`lucide:IconName\` (e.g. \`lucide:Mail\`). See [Lucide Icons Catalog](https://lucide.dev/icons/).
+- **Color:** Use \`iconColor\` prop for theme colors (\`primary\`, \`secondary\`, \`info\`) or any CSS color (e.g. \`#4caf50\`).
+
+---
+
+### React Component Mode (Advanced)
+You may also use TopBar as a React component and manually import icons, passing them into \`TopBarLinks\`:
+
+~~~jsx
+import TopBar from './TopBar';
+import { BarChart, Insights } from '@mui/icons-material';
+import { Mail, Info } from 'lucide-react';
+
+<TopBar
+  TopBarLinks={[
+    { label: 'Home', href: '/', icon: <BarChart color="primary" /> },
+    { label: 'Docs', href: '/docs', icon: <Insights htmlColor="#f50057" /> },
+    {
+      label: 'More',
+      icon: <Info color="success" />,
+      children: [
+        { label: 'About', href: '/about', icon: <Mail htmlColor="#4caf50" /> },
+      ],
+    },
+  ]}
+  position="static"
+/>
+~~~
+- **Note:** When using this mode, you can pass any valid React element as the \`icon\` property. For Material UI icons, use the \`color\` or \`htmlColor\` prop to customize color. For Lucide icons, use the \`color\` prop.
+
+---
+
+## Notes
+- TopBar uses \`react-router-dom\` internally. Stories wrap it in a \`MemoryRouter\` for demo purposes.
+- Dropdown menus are created by providing a \`children\` array for any link.
+- Icon colors can be set with theme color keys (\`primary\`, \`secondary\`, \`info\`, etc.) or any valid CSS color string.
+- TopBarLinks accepts objects with label, href, external, icon (string for your registry), and iconColor, and also supports submenus via children.
+- Toggles like showMenuButton, showThemeToggle, and homeTo/position.
+Inset handling:
+  - Measure Toolbar with toolbarRef, call theme.updateInsets({ nav: h }), and clean up in return → this updates theme.layout.insets.nav in GuiProvider and also the CSS vars (--gui-nav-height).
+Theme integration:
+  - Use useTheme()/useMediaQuery(). In GuiProvider, inject updateInsets and layout.insets into the memoized MUI theme, so TopBar sees them correctly.
+  
+        `,
+      },
+    },
+  },
+  argTypes: {
+    title: {
+      description: 'Title text displayed next to the logo.',
+      control: 'text',
+    },
+    logo: {
+      description: 'Logo image URL shown in the top-left.',
+      control: 'text',
+    },
+    TopBarLinks: {
+      description: 'Array of navigation links, supporting nested dropdown menus.',
+      control: 'object',
+    },
+    showMenuButton: {
+      description: 'Displays a hamburger menu button on the left.',
+      control: 'boolean',
+    },
+    onMenuClick: {
+      description: 'Callback executed when the hamburger menu is clicked.',
+      action: 'menuClicked',
+    },
+    showThemeToggle: {
+      description: 'Shows a dark/light mode toggle button.',
+      control: 'boolean',
+    },
+    homeTo: {
+      description: 'Router path for clicking on logo/title.',
+      control: 'text',
+    },
+  },
+} satisfies Meta<typeof TopBar>;
+export default meta;
+
+export type Story = StoryObj<typeof TopBar>;
+
+export const Default: Story = {
+  args: {
+    title: 'neurons.me',
+    logo: 'https://neurons.me/neurons.me.png',
+    TopBarLinks: [
+      { label: 'Home', href: '/' },
+      { label: 'Docs', href: '/docs' },
+      {
+        label: 'More',
+        children: [
+          { label: 'About', href: '/about' },
+          { label: 'Contact', href: '/contact' },
+        ],
+      },
+    ],
+    showMenuButton: false,
+    showThemeToggle: true,
+    homeTo: '/',
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    title: 'neurons.me',
+    logo: 'https://neurons.me/neurons.me.png',
+    TopBarLinks: [
+     {
+  label: 'Home',
+  href: '/',
+  icon: 'mui:BarChart',
+  iconColor: 'primary'
+},
+{
+  label: 'Docs',
+  href: '/docs',
+  icon: 'mui:Insights',
+  iconColor: 'secondary'
+},
+{
+  label: 'More',
+  icon: 'lucide:Info',
+  iconColor: '#00aa96',
+  children: [
+    { label: 'About', href: '/about', icon: 'mui:Message', iconColor: 'info' },
+    { label: 'Contact', href: '/contact', icon: 'lucide:Mail', iconColor: '#4caf50' },
+  ],
+}
+    ],
+    showMenuButton: false,
+    showThemeToggle: true,
+    homeTo: '/',
+  },
+};
+
+export const FixedTopBar = () => (
+  <>
+    <TopBar
+      title="neurons.me"
+      logo="https://neurons.me/neurons.me.png"
+      TopBarLinks={[
+        { label: 'Home', href: '/' },
+        { label: 'Docs', href: '/docs' },
+        {
+          label: 'More',
+          children: [
+            { label: 'About', href: '/about' },
+            { label: 'Contact', href: '/contact' },
+          ],
+        },
+      ]}
+      showMenuButton={false}
+      showThemeToggle={true}
+      homeTo="/"
+      position="fixed"
+    />
+    <div style={{ marginTop: 80, padding: 20, height: '200vh'}}>
+      {Array(100).fill('Lorem ipsum dolor sit amet, consectetur adipiscing elit. ').join('')}
+    </div>
+  </>
+);
+
+FixedTopBar.storyName = 'Fixed TopBar';
+FixedTopBar.parameters = {
+  docs: {
+    description: {
+      story: 'Demonstrates the TopBar with `position="fixed"`. Scroll down to see the TopBar stay fixed at the top.',
+    },
+  },
+};
+
+export const StaticTopBar = () => (
+  <>
+    <TopBar
+      title="neurons.me"
+      logo="https://neurons.me/neurons.me.png"
+      TopBarLinks={[
+        { label: 'Home', href: '/' },
+        { label: 'Docs', href: '/docs' },
+        {
+          label: 'More',
+          children: [
+            { label: 'About', href: '/about' },
+            { label: 'Contact', href: '/contact' },
+          ],
+        },
+      ]}
+      showMenuButton={false}
+      showThemeToggle={true}
+      homeTo="/"
+      position="static"
+    />
+    <div style={{ padding: 20, height: '200vh'}}>
+      {Array(100).fill('Lorem ipsum dolor sit amet, consectetur adipiscing elit. ').join('')}
+    </div>
+  </>
+);
+
+StaticTopBar.storyName = 'Static TopBar';
+StaticTopBar.parameters = {
+  docs: {
+    description: {
+      story: 'Demonstrates the TopBar with `position="static"`. Scroll down to see the TopBar scroll with the page.',
+    },
+  },
+};

package/src/gui/molecules/AppBars/TopBar/TopBar.tsx

@@ -0,0 +1,299 @@
+import { useState, useEffect, useRef, MouseEvent } from 'react';
+import { Link, useNavigate, useLocation } from 'react-router-dom';
+import type { SxProps, Theme } from '@mui/material/styles';
+import {
+  AppBar,
+  Toolbar,
+  IconButton,
+  Typography,
+  Box,
+  Button,
+  Menu,
+  MenuItem,
+} from '@/gui/atoms';
+import { useGuiTheme, useGuiMediaQuery } from '@/gui';
+import ThemeSelector from '../../Utilities/ThemeSelector';
+import Icon from '../../../../themes/icons/Icon';
+import SidebarToggleButton from '../LeftSidebar/SidebarToggleButton';
+
+const sxN = (...parts: Array<SxProps<Theme> | undefined>): SxProps<Theme> => (parts.filter(Boolean) as unknown) as SxProps<Theme>;
+
+interface TopBarLinkChild {
+  label: string;
+  href?: string;
+  external?: boolean;
+  icon?: string;
+  iconColor?: string;
+}
+
+interface TopBarLink {
+  label: string;
+  href?: string;
+  external?: boolean;
+  icon?: string;
+  iconColor?: string;
+  children?: TopBarLinkChild[];
+}
+
+interface TopBarProps {
+  title?: string;
+  logo?: string;
+  TopBarLinks?: TopBarLink[];
+  showMenuButton?: boolean;
+  onMenuClick?: () => void;
+  showThemeToggle?: boolean;
+  homeTo?: string;
+  position?: "fixed" | "static" | "sticky";
+  sx?: SxProps<Theme>;
+  appBarSx?: SxProps<Theme>;
+  toolbarSx?: SxProps<Theme>;
+  brandSx?: SxProps<Theme>;
+  logoSx?: SxProps<Theme>;
+  titleSx?: SxProps<Theme>;
+  linksSx?: SxProps<Theme>;
+  linkSx?: SxProps<Theme>;
+  menuSx?: SxProps<Theme>;
+  menuItemSx?: SxProps<Theme>;
+  actionsSx?: SxProps<Theme>;
+  id?: string;
+  className?: string;
+  'data-testid'?: string;
+  toggleLocation?: 'topbar' | 'sidebar' | 'none';
+}
+
+/**
+ * TopBar (presentational)
+ *
+ * Props:
+ * - title?: string = 'neurons.me'
+ * - logo?: string (URL)
+ * - TopBarLinks?: Array<{ label: string, href?: string, external?: boolean, icon?: string, iconColor?: string, children?: Array<{label: string, href?: string, external?: boolean, icon?: string, iconColor?: string}> }>
+ *   // icon: string from This.GUI icon registry (e.g., 'mui:Settings', 'lucide:home')
+ *   // iconColor: CSS color or theme key (e.g., '#00aa96', 'primary', 'text.secondary')
+ * - showMenuButton?: boolean (controls left hamburger visibility)
+ * - onMenuClick?: () => void (called when hamburger is clicked)
+ * - showThemeToggle?: boolean (renders theme toggle icon)
+ * - homeTo?: string (router link for brand/title)
+ * - position?: "fixed" | "static" | "sticky" (AppBar position, default is "fixed")
+ * - toggleLocation?: 'topbar' | 'sidebar' | 'none' (location prop for SidebarToggleButton)
+ */
+export default function TopBar({
+  title = 'neurons.me',
+  logo = 'https://neurons.me/neurons.me.png',
+  TopBarLinks = [],
+  showMenuButton = false,
+  onMenuClick,
+  showThemeToggle = true,
+  homeTo = '/',
+  position = 'fixed',
+  sx,
+  appBarSx,
+  toolbarSx,
+  brandSx,
+  logoSx,
+  titleSx,
+  linksSx,
+  linkSx,
+  menuSx,
+  menuItemSx,
+  actionsSx,
+  id,
+  className,
+  'data-testid': dataTestId,
+  toggleLocation = 'topbar',
+}: TopBarProps) {
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down('md'));
+
+  let navigate: ReturnType<typeof useNavigate> | null = null;
+  try {
+    navigate = useNavigate();
+  } catch (err) {
+    navigate = null;
+  }
+
+
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null);
+  const [openMenu, setOpenMenu] = useState<null | string>(null);
+
+  const toolbarRef = useRef<HTMLDivElement | null>(null);
+
+  // Sync nav inset with real rendered height (idempotent via provider)
+  useEffect(() => {
+    const setInsets = theme?.updateInsets;
+    if (typeof setInsets !== 'function') return;
+
+    const measure = () => {
+      const h = (toolbarRef.current?.offsetHeight ?? 48);
+      setInsets({ nav: h });
+    };
+
+    // initial measure
+    measure();
+
+    // observe toolbar size changes (density, breakpoints, etc.)
+    let ro: ResizeObserver | undefined;
+    if (typeof ResizeObserver !== 'undefined' && toolbarRef.current) {
+      ro = new ResizeObserver(() => measure());
+      ro.observe(toolbarRef.current);
+    }
+
+    return () => {
+      if (ro) ro.disconnect();
+      setInsets({ nav: 0 });
+    };
+  }, [isMobile, theme.updateInsets]);
+
+  const handleMenuOpen = (event: MouseEvent<HTMLElement>, label: string) => {
+    setAnchorEl(event.currentTarget);
+    setOpenMenu(label);
+  };
+
+  const handleMenuClose = () => {
+    setAnchorEl(null);
+    setOpenMenu(null);
+  };
+
+  // Indentation handled by Toolbar padding-left via --gui-inset-left CSS variable
+  const baseAppBarSx = {
+    minHeight: 48,
+    backgroundColor: theme.palette.background.nav,
+    borderBottom: '1px solid',
+    borderColor: theme.palette.divider,
+    // Keep AppBar *below* the Drawer so the Drawer edge sits flush over it.
+    zIndex: (theme as any)?.zIndex?.appBar ?? 1100,
+    position: 'fixed',
+    top: 0,
+    left: 0,
+    right: 0,
+    width: '100%',
+    boxSizing: 'border-box',
+  } as const;
+
+  return (
+    <AppBar
+      id={id}
+      className={className}
+      data-testid={dataTestId}
+      position={position}
+      elevation={0}
+      sx={sxN(baseAppBarSx as SxProps<Theme>, { '--has-topbar': 1 } as any, sx, appBarSx)}
+    >
+      <Toolbar
+        ref={toolbarRef}
+        variant="dense"
+        disableGutters
+        sx={sxN(
+          {
+            minHeight: 48,
+            pl: 'var(--gui-rail-width, 0px)',
+            pr: 'var(--gui-inset-right, 0px)',
+          },
+          toolbarSx
+        )}
+      >
+        <SidebarToggleButton
+          expanded={showMenuButton}
+          onToggle={onMenuClick || (() => {})}
+          location={toggleLocation}
+          sx={{ mr: 1 }}
+        />
+        {showMenuButton && (
+          <IconButton
+            color="inherit"
+            edge="start"
+            onClick={onMenuClick}
+            sx={{ mr: 2 }}
+            aria-label="open navigation"
+          >
+            <Icon name="mui:Menu" color={theme.palette.icon?.main || theme.palette.text.primary} size={24} />
+          </IconButton>
+        )}
+
+        <Box
+          sx={sxN({ display: 'flex', alignItems: 'center', flexGrow: 1, textDecoration: 'none', ml: showMenuButton ? 2 : 0 }, brandSx)}
+          component={Link}
+          to={homeTo}
+        >
+          {logo && (
+            <Box component="img" src={logo} alt={`${title} logo`} sx={sxN({ height: 28, mr: 0.75 }, logoSx)} />
+          )}
+          <Typography variant="h6" noWrap component="div" sx={sxN({ color: theme.palette.text.primary }, titleSx)}>
+            {title}
+          </Typography>
+        </Box>
+
+        {/* TopBarLinks */}
+        <Box sx={sxN({ display: 'flex', alignItems: 'center', gap: 1.25 }, linksSx)}>
+          {TopBarLinks.map((link) => {
+            const hasChildren = Array.isArray(link.children) && link.children.length > 0;
+            if (hasChildren) {
+              return (
+                <Box key={link.label}>
+                  <Button
+                    onClick={(e: MouseEvent<HTMLElement>) => handleMenuOpen(e, link.label)}
+                    sx={sxN({
+                      color: theme.palette.text.primary,
+                      '&:hover': { backgroundColor: 'transparent', color: theme.palette.text.secondary },
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: 0.5,
+                      minWidth: 0,
+                      px: 1,
+                    }, linkSx)}
+                  >
+                    {link.icon && <Icon name={link.icon} color={link.iconColor} size={18} />}
+                    {link.label}
+                  </Button>
+                  <Menu anchorEl={anchorEl} open={openMenu === link.label} onClose={handleMenuClose} sx={menuSx}>
+                    {link.children!.map((child) => (
+                      <MenuItem
+                        key={child.label}
+                        component={child.external ? 'a' : Link}
+                        {...(child.external
+                          ? { href: child.href, target: '_blank', rel: 'noopener noreferrer' }
+                          : { to: child.href })}
+                        onClick={handleMenuClose}
+                        sx={sxN({ display: 'flex', alignItems: 'center', gap: 0.5 }, menuItemSx)}
+                      >
+                        {child.icon && <Icon name={child.icon} color={child.iconColor} size={18} />}
+                        {child.label}
+                      </MenuItem>
+                    ))}
+                  </Menu>
+                </Box>
+              );
+            }
+            return (
+              <Button
+                key={link.label}
+                component={link.external ? 'a' : Link}
+                {...(link.external
+                  ? { href: link.href, target: '_blank', rel: 'noopener noreferrer' }
+                  : { to: link.href })}
+                sx={sxN({
+                  color: theme.palette.text.primary,
+                  '&:hover': { backgroundColor: 'transparent', color: theme.palette.text.secondary },
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 0.5,
+                  minWidth: 0,
+                  px: 1,
+                }, linkSx)}
+              >
+                {link.icon && <Icon name={link.icon} color={link.iconColor} size={18} />}
+                {link.label}
+              </Button>
+            );
+          })}
+        </Box>
+
+        {showThemeToggle && (
+          <Box sx={sxN({ ml: 1 }, actionsSx)}>
+            <ThemeSelector tooltip="Select theme" />
+          </Box>
+        )}
+      </Toolbar>
+    </AppBar>
+  );
+}

package/src/gui/molecules/Utilities/ThemeModeToggle/ThemeModeToggle.resolver.tsx

@@ -0,0 +1,72 @@
+import * as React from 'react';
+import ThemeModeToggle from './ThemeModeToggle';
+
+/**
+ * Resolver for ThemeModeToggle
+ * ----------------------------
+ * Allows you to render the ThemeModeToggle from a plain JSON/config object.
+ *
+ * Minimal accepted shape:
+ * {
+ *   "type": "ThemeModeToggle",
+ *   "props": {
+ *     "variant": "minimal" | "switch",
+ *     "show": "icons" | "label" | "both",
+ *     "id": "optional-id",
+ *     "className": "optional-class",
+ *     "data-testid": "test-id",
+ *     // Optional granular styling
+ *     "sx": {  root styles  },
+ *     "iconSx": { icons styles },
+ *     "switchSx": { switch styles (variant='switch')  },
+ *     "labelSx": { label Typography styles  }
+ *   }
+ * }
+ */
+
+export type ThemeModeToggleSpec = {
+  type?: 'ThemeModeToggle';
+  /** Render style: compact IconButton ("minimal") or labeled Switch ("switch") */
+  variant?: 'minimal' | 'switch';
+  /** What to display: icons only, label only, or both */
+  show?: 'icons' | 'label' | 'both';
+  /** DOM passthroughs */
+  id?: string;
+  className?: string;
+  ['data-testid']?: string;
+  /** Granular styling (forwarded to the component) */
+  sx?: any;
+  iconSx?: any;
+  switchSx?: any;
+  labelSx?: any;
+};
+
+export function resolveThemeModeToggle(p: ThemeModeToggleSpec = {}) {
+  const {
+    variant = 'minimal',
+    show = 'icons',
+    id,
+    className,
+    ['data-testid']: dataTestId,
+    sx,
+    iconSx,
+    switchSx,
+    labelSx,
+  } = p;
+
+  return (
+    <ThemeModeToggle
+      variant={variant}
+      show={show}
+      id={id}
+      className={className}
+      data-testid={dataTestId}
+      sx={sx}
+      iconSx={iconSx}
+      switchSx={switchSx}
+      labelSx={labelSx}
+    />
+  );
+}
+
+export default resolveThemeModeToggle;