this.gui 1.3.41 → 1.3.42

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

@@ -0,0 +1,239 @@
+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/RightSidebar",
+  component: Layout,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+`The **RightSidebar** component mirrors the LeftSidebar experience on the opposite edge of the screen. Use it for complementary tools, contextual insights, and secondary actions without losing alignment with the primary content area.
+---
+## Features
+- **Rail-first orientation:** Defaults to a compact 72px rail so charts or documents remain visible.
+- **Expandable workspace:** Switch to a wide panel (264px) for verbose content, filters, or inspectors.
+- **Mobile-friendly drawer:** On small screens it becomes a temporary drawer that slides over content from the right.
+- **Footer actions:** Accepts \`footerElements\` so pinned tools (settings, help) stay reachable.
+- **Inset synchronization:** Updates \`theme.layout.insets.right\` so TopBar and other surfaces adapt automatically.
+
+---
+## Layout Modes
+- \`rail\`: icon-only column hugging the right edge.
+- \`expanded\`: full-width tools panel with labels and nested menus.
+- \`mobile\`: overlay drawer controlled by a floating button.
+Modes can be toggled programmatically via \`useRightSidebar()\` or automatically through built-in breakpoints.
+
+---
+## Props
+- \`elements?: RightSidebarElement[]\` — Declarative items (\`link\`, \`menu\`, \`action\`) rendered in order.
+- \`footerElements?: RightSidebarElement[]\` — Optional sticky footer actions.
+- \`initialView?: 'rail' | 'expanded' | 'mobile'\` — Starting mode (defaults to \`rail\`).
+- \`className?\` and other DOM props are forwarded to the root \`aside\`.
+
+---
+## Declarative usage
+~~~tsx
+import RightSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/RightSidebar/RightSidebar';
+
+<RightSidebar
+  elements={[
+    { type: 'link', props: { label: 'Notifications', icon: 'notifications' } },
+    { type: 'link', props: { label: 'Activity', icon: 'history' } },
+    {
+      type: 'menu',
+      props: {
+        label: 'Views',
+        icon: 'view_cozy',
+        items: [
+          { label: 'Timeline', icon: 'timeline' },
+          { label: 'JSON', icon: 'code' },
+        ],
+      },
+    },
+  ]}
+  footerElements={[
+    { type: 'link', props: { label: 'Settings', icon: 'settings' } },
+    { type: 'action', props: { label: 'Support', icon: 'help' } },
+  ]}
+/>;
+~~~
+
+---
+## React usage
+Combine the context provider and hook to manage the view explicitly:
+~~~tsx
+import { RightSidebarProvider } from '@/gui/contexts';
+import { useRightSidebar } from '@/gui/hooks';
+import RightSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/RightSidebar/RightSidebar';
+
+const items = [{ type: 'link', props: { label: 'History', icon: 'history' } }];
+
+function Inspector() {
+  const { view, setView } = useRightSidebar();
+  return (
+    <>
+      <button onClick={() => setView(view === 'expanded' ? 'rail' : 'expanded')}>
+        Toggle inspector
+      </button>
+      <RightSidebar elements={items} />
+    </>
+  );
+}
+
+export function InspectorShell() {
+  return (
+    <RightSidebarProvider>
+      <Inspector />
+    </RightSidebarProvider>
+  );
+}
+~~~
+
+---
+## Notes
+- The floating toggle only appears in mobile mode; closing the drawer restores the underlying layout insets.
+- Footer elements share the same declarative shape as main items, so you can reuse links or action buttons.
+- Works seamlessly alongside \`LeftSidebar\` and \`TopBar\` when using the responsive Layout shell.
+`,
+      },
+    },
+  },
+};
+
+const Template: StoryFn<React.ComponentProps<typeof Layout>> = (args) => (
+  <Layout {...args} />
+);
+
+export const Default = Template.bind({});
+Default.args = {
+  topBarConfig: {
+    title: "Analytics",
+    elementsRight: [
+      {
+        type: "action",
+        props: {
+          element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+        },
+      },
+      { type: "action", props: { label: "Share", icon: "ios_share", iconColor: "var(--gui-primary)" } },
+    ],
+  },
+  rightSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Notifications", icon: "notifications", iconColor: "var(--gui-warning)" } },
+      { type: "link", props: { label: "Activity", icon: "history", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Views",
+          icon: "view_cozy",
+          iconColor: "var(--gui-primary)",
+          items: [
+            { label: "Timeline", icon: "timeline", iconColor: "var(--gui-success)" },
+            { label: "JSON", icon: "code", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Download", icon: "download", iconColor: "var(--gui-primary)" } },
+    ],
+  },
+};
+
+export const WithFooter = Template.bind({});
+WithFooter.args = {
+  topBarConfig: {
+    title: "Analytics",
+    elementsRight: [
+      {
+        type: "action",
+        props: {
+          element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+        },
+      },
+      { type: "action", props: { label: "Share", icon: "ios_share", iconColor: "var(--gui-primary)" } },
+    ],
+  },
+  rightSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Notifications", icon: "notifications", iconColor: "var(--gui-warning)" } },
+      { type: "link", props: { label: "Activity", icon: "history", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Views",
+          icon: "view_cozy",
+          iconColor: "var(--gui-primary)",
+          items: [
+            { label: "Timeline", icon: "timeline", iconColor: "var(--gui-success)" },
+            { label: "JSON", icon: "code", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Download", icon: "download", iconColor: "var(--gui-primary)" } },
+    ],
+    footerElements: [
+      { type: "link", props: { label: "Settings", icon: "settings", iconColor: "var(--gui-secondary)" } },
+      { type: "action", props: { label: "Support", icon: "help", iconColor: "var(--gui-success)" } },
+    ],
+  },
+};
+
+export const WithBothSidebars = Template.bind({});
+WithBothSidebars.args = {
+  topBarConfig: {
+    title: "Analytics",
+    elementsRight: [
+      {
+        type: "action",
+        props: {
+          element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+        },
+      },
+      { type: "action", props: { label: "Share", icon: "ios_share", iconColor: "var(--gui-primary)" } },
+    ],
+  },
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-secondary)",
+          items: [
+            { label: "Project A", icon: "folder_open" },
+            { label: "Project B", icon: "folder_open" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Create", icon: "add_circle", iconColor: "var(--gui-success)" } },
+    ],
+    footerElements: [
+      { type: "link", props: { label: "Settings", icon: "settings", iconColor: "var(--gui-secondary)" } },
+      { type: "action", props: { label: "Help", icon: "help_outline", iconColor: "var(--gui-info)" } },
+    ],
+  },
+  rightSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Notifications", icon: "notifications", iconColor: "var(--gui-warning)" } },
+      { type: "link", props: { label: "Activity", icon: "history", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Views",
+          icon: "view_cozy",
+          iconColor: "var(--gui-primary)",
+          items: [
+            { label: "Timeline", icon: "timeline", iconColor: "var(--gui-success)" },
+            { label: "JSON", icon: "code", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Download", icon: "download", iconColor: "var(--gui-primary)" } },
+    ],
+  },
+};

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

@@ -0,0 +1,319 @@
+import clsx from 'clsx';
+import { useEffect, useState, useRef } from 'react';
+import IconButton from '@mui/material/IconButton';
+import Icon from '@/gui/Theme/Icon/Icon';
+import { Box, Drawer } from '@/gui/components/atoms';
+import { useRightSidebar, useGuiTheme, useGuiMediaQuery, useUpdateInsets, useInsets } from '@/gui/hooks';
+import type { RightSidebarView } from '@/gui/contexts';
+import type { RightSidebarElement, RightSidebarProps } from './RightSidebar.types';
+import RightSidebarLink from './components/RightSidebarLink/RightSidebarLink';
+import RightSidebarMenu from './components/RightSidebarMenu/RightSidebarMenu';
+import RightSidebarAction from './components/RightSidebarAction/RightSidebarAction';
+import RightSidebarToggleButton from './components/RightSidebarToggleButton/RightSidebarToggleButton';
+
+const RAIL_WIDTH = 72;
+const EXPANDED_WIDTH = 264;
+
+const RightSidebar = ({
+  elements = [],
+  footerElements = [],
+  className,
+  initialView = 'rail',
+  id,
+  style,
+  'data-testid': dataTestId,
+}: RightSidebarProps) => {
+  const { view, setView } = useRightSidebar();
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down('sm'));
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [lastNonMobileView, setLastNonMobileView] = useState<RightSidebarView>(
+    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 =
+      isMobile || view === 'mobile' ? 0 : view === 'expanded' ? EXPANDED_WIDTH : RAIL_WIDTH;
+    setInsets({ right: desired });
+    return () => setInsets({ right: 0 });
+  }, [isMobile, 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 = (items: RightSidebarElement[]) =>
+    items.map((el, idx) => {
+      if (el.type === 'link') return <RightSidebarLink key={idx} {...el.props} />;
+      if (el.type === 'menu') return <RightSidebarMenu key={idx} view={view} {...el.props} />;
+      if (el.type === 'action') return <RightSidebarAction key={idx} view={view} {...el.props} />;
+      return null;
+    });
+
+  const renderFooterItems = (items: RightSidebarElement[]) =>
+    items.map((el, idx) => {
+      if (el.type === 'link') return <RightSidebarLink key={`footer-link-${idx}`} {...el.props} />;
+      if (el.type === 'menu')
+        return <RightSidebarMenu key={`footer-menu-${idx}`} view={view} {...el.props} />;
+      if (el.type === 'action')
+        return <RightSidebarAction key={`footer-action-${idx}`} view={view} {...el.props} />;
+      return null;
+    });
+
+  if (view === 'rail') {
+    return (
+      <Box
+        component="aside"
+        className={clsx('RightSidebar', className)}
+        id={id}
+        data-testid={dataTestId}
+        style={style}
+        sx={{
+          position: 'fixed',
+          top: 0,
+          right: 0,
+          bottom: 0,
+          height: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          width: `${RAIL_WIDTH}px`,
+          overflow: 'hidden',
+          borderLeft: '1px solid',
+          borderColor: 'divider',
+          backgroundColor: 'background.paper',
+        }}
+      >
+        <Box
+          component="header"
+          sx={{
+            flexShrink: 0,
+            borderBottom: '1px solid',
+            borderColor: 'divider',
+            height: `${headerHeight}px`,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'flex-start',
+            px: 1.5,
+            py: 0,
+            gap: 1.25,
+          }}
+        >
+            <RightSidebarToggleButton
+              expanded={view === ('expanded' as any)}
+              onToggle={() => setView(view === 'rail' ? 'expanded' : 'rail')}
+          />
+        </Box>
+        <Box sx={{ flexGrow: 1, overflowY: 'auto' }}>{renderElements(elements)}</Box>
+        {hasFooterElements && (
+          <Box
+            component="footer"
+            sx={{
+              flexShrink: 0,
+              px: 1,
+              py: 1.5,
+                      borderColor: 'divider',
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 0.5,
+            }}
+          >
+            {renderFooterItems(footerElements)}
+          </Box>
+        )}
+      </Box>
+    );
+  }
+
+  if (view === 'mobile') {
+    return (
+      <>
+        <Box
+          sx={{
+            position: 'fixed',
+            top: `${toggleOffset}px`,
+            right: 0,
+            zIndex: ((theme as any)?.zIndex?.drawer ?? 1200) + 1,
+            display: mobileOpen ? 'none' : 'flex',
+          }}
+        >
+          <IconButton
+            aria-label="Open right sidebar"
+            onClick={() => setMobileOpen(true)}
+            sx={{
+              borderRadius: '16px 0 0 16px',
+              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="right"
+          open={mobileOpen}
+          onClose={() => setMobileOpen(false)}
+          variant="temporary"
+          ModalProps={{ keepMounted: true }}
+          sx={{
+            '& .MuiDrawer-paper': {
+              width: EXPANDED_WIDTH,
+              top: `${navInset}px`,
+              height: `calc(100vh - ${navInset}px)`,
+              display: 'flex',
+              flexDirection: 'column',
+              borderLeft: '1px solid',
+              borderColor: 'divider',
+            },
+          }}
+          PaperProps={{ id, 'data-testid': dataTestId, style, className }}
+        >
+          <Box
+            component="header"
+            sx={{
+              flexShrink: 0,
+              borderBottom: '1px solid',
+              borderColor: 'divider',
+              height: `${headerHeight}px`,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'flex-start',
+              px: 1.5,
+              gap: 1.25,
+            }}
+          >
+            <RightSidebarToggleButton expanded onToggle={() => setMobileOpen(false)} />
+          </Box>
+          <Box sx={{ flexGrow: 1, overflowY: 'auto' }}>{renderElements(elements)}</Box>
+          {hasFooterElements && (
+            <Box
+              component="footer"
+              sx={{
+                flexShrink: 0,
+                px: 1.5,
+                py: 1.5,
+                          borderColor: 'divider',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 0.75,
+              }}
+            >
+              {renderFooterItems(footerElements)}
+            </Box>
+          )}
+        </Drawer>
+      </>
+    );
+  }
+
+  return (
+    <Box
+      component="aside"
+      className={clsx('RightSidebar', className)}
+      id={id}
+      data-testid={dataTestId}
+      style={style}
+      sx={{
+        position: 'fixed',
+        top: 0,
+        right: 0,
+        bottom: 0,
+        height: '100vh',
+        display: 'flex',
+        flexDirection: 'column',
+        width: `${EXPANDED_WIDTH}px`,
+        overflow: 'hidden',
+        borderLeft: '1px solid',
+        borderColor: 'divider',
+        backgroundColor: 'background.paper',
+      }}
+    >
+      <Box
+        component="header"
+        sx={{
+          flexShrink: 0,
+          borderBottom: '1px solid',
+          borderColor: 'divider',
+          height: `${headerHeight}px`,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'flex-start',
+          px: 1.5,
+          py: 0,
+          gap: 1.25,
+        }}
+      >
+        <RightSidebarToggleButton
+          expanded={view === ('expanded' as any)}
+          onToggle={() => setView(view === 'expanded' ? 'rail' : 'expanded')}
+        />
+      </Box>
+      <Box sx={{ flexGrow: 1, overflowY: 'auto' }}>{renderElements(elements)}</Box>
+      {hasFooterElements && (
+        <Box
+          component="footer"
+          sx={{
+            flexShrink: 0,
+            px: 1.5,
+            py: 1.5,
+                  borderColor: 'divider',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 0.75,
+          }}
+        >
+          {renderFooterItems(footerElements)}
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+export default RightSidebar;

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

@@ -0,0 +1,17 @@
+import type React from 'react';
+import { RightSidebarView } from '@/gui/contexts';
+
+export type RightSidebarElement =
+  | { type: 'link'; props: Record<string, any> }
+  | { type: 'menu'; props: Record<string, any> }
+  | { type: 'action'; props: Record<string, any> };
+
+export type RightSidebarProps = {
+  elements?: RightSidebarElement[];
+  footerElements?: RightSidebarElement[];
+  className?: string;
+  initialView?: RightSidebarView;
+  id?: string;
+  style?: React.CSSProperties;
+  'data-testid'?: string;
+};

package/src/gui/Theme/Layout/Sidebars/RightSidebar/components/RightSidebarAction/RightSidebarAction.tsx

@@ -0,0 +1,102 @@
+import React from 'react';
+import clsx from 'clsx';
+import { Box, Typography, Tooltip } from '@/gui/components/atoms';
+import Icon from '@/gui/Theme/Icon/Icon';
+import type { RightSidebarView } from '../../RightSidebar.types';
+
+export type RightSidebarActionProps = {
+  label?: string;
+  icon?: string;
+  iconColor?: string;
+  onClick?: () => void;
+  active?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  view: RightSidebarView;
+};
+
+const RightSidebarAction: React.FC<RightSidebarActionProps> = ({
+  label,
+  icon,
+  iconColor,
+  onClick,
+  active = false,
+  className,
+  style,
+  view,
+}) => {
+  const content = (
+    <Box
+      sx={{
+        display: 'flex',
+        gap: 1.123,
+        justifyContent: view === 'rail' ? 'center' : 'flex-start',
+        alignItems: 'center',
+        width: '100%',
+        textAlign: view === 'rail' ? 'center' : 'left',
+        px: view === 'rail' ? 0 : 1.23,
+      }}
+    >
+      <Icon name={icon ?? ''} iconColor={iconColor || (active ? 'primary.main' : undefined)} />
+      {view !== 'rail' && (
+        <Typography
+          variant="body2"
+          sx={{
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            color: active ? 'primary.main' : 'text.primary',
+          }}
+        >
+          {label}
+        </Typography>
+      )}
+    </Box>
+  );
+
+  return (
+    <Box
+      component="button"
+      onClick={onClick}
+      className={clsx('RightSidebarAction', className)}
+      style={style}
+      sx={{
+        p: 1.123,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: view === 'rail' ? 'center' : 'flex-start',
+        borderRight: 2,
+        borderRightColor: active ? 'primary.main' : 'transparent',
+        borderRightStyle: 'solid',
+        cursor: 'pointer',
+        backgroundColor: active ? 'action.selected' : 'transparent',
+        '&:hover': {
+          backgroundColor: 'action.hover',
+          borderRightColor: 'primary.main',
+        },
+        color: active ? 'primary.main' : 'text.primary',
+        width: '100%',
+        textAlign: view === 'rail' ? 'center' : 'left',
+        outline: 'none',
+        border: 'none',
+      }}
+      aria-pressed={active}
+      type="button"
+    >
+      {view === 'rail' ? (
+        <Tooltip
+          title={label}
+          placement="left"
+          arrow
+          slotProps={{ tooltip: { sx: { fontSize: '0.9rem', py: 0.5, px: 1 } } }}
+        >
+          {content}
+        </Tooltip>
+      ) : (
+        content
+      )}
+    </Box>
+  );
+};
+
+export default RightSidebarAction;