this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,294 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+import RightSidebar from './RightSidebar';
+import NavBar from '../TopBar/TopBar';
+
+const meta = {
+  title: 'Molecules/AppBars/RightSidebar',
+  component: RightSidebar,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ minHeight: '100vh' }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **RightSidebar** renders a contextual panel on the right side (persistent on desktop, temporary on mobile).
+It supports a hierarchical list with optional **icons** (via the This.GUI icon registry) and **nested groups**.
+
+### Two icon usage modes
+
+**1) Declarative mode (recommended)** — pass icon **strings** using the registry prefixes (\`mui:\`, \`lucide:\`).
+
+- Color: use \`iconColor\` with a theme key (\`primary\`, \`secondary\`, \`info\`, etc.) or any CSS color (e.g. \`#4caf50\`).
+- The component internally resolves these strings through the registry.
+
+**2) Direct React mode (advanced)** — pass a React element as the \`icon\` prop (you import icons yourself). 
+This gives you full control, but skips the registry.
+
+### Item shape (\`rightContext.items\`)
+
+Each item supports:
+- \`title\` (string) — 'label' or 'item'
+- \`label\` (string)
+- \`href\` (string, internal path or external URL)
+- \`external\` (boolean) — opens external links in new tab
+- \`icon\` (string | ReactNode | Component)
+- \`iconColor\` (string) — theme key or CSS color
+- \`children\` (array) — nested items
+
+### Quick example (declarative)
+
+\`\`\`js
+const rightContext = {
+  title: 'Quick actions',
+  items: [
+    { label: 'Inbox', href: '/inbox', icon: 'mui:Mail', iconColor: 'primary' },
+    {
+      label: 'Analytics',
+      icon: 'lucide:bar-chart-3',
+      children: [
+        { label: 'Reports', href: '/reports', icon: 'mui:Insights', iconColor: '#ff9800' },
+        { label: 'Trends', href: '/trends', icon: 'lucide:trending-up', iconColor: '#4caf50' },
+      ],
+    },
+  ],
+};
+<RightSidebar rightContext={rightContext} />
+\`\`\`
+
+---
+
+### Layout Insets (auto‑coordination)
+On **desktop**, RightSidebar is **permanent** and automatically updates the UI insets so other components (e.g., \`Footer\`, page containers) can adapt:
+
+- Sets **\`theme.insets.right = drawerWidth\`** when permanent.
+- Sets **\`theme.insets.right = 0\`** on mobile (temporary drawer) or when unmounted.
+- This is wired via the Theme Provider API **\`theme.updateInsets({ right })\`**.
+
+**Why it matters:** Layouts or containers can read \`theme.layout.insets.right\` (exposed in the MUI theme) to add padding/margins so content doesn’t go under the drawer.
+
+**Example (reading insets inside a component):**
+\`\`\`jsx
+import { useTheme, Box } from '@mui/material';
+
+export default function PageContainer({ children }) {
+  const theme = useTheme();
+  const rightInset = theme?.layout?.insets?.right || 0; // number in px
+  return (
+    <Box sx={{ pr: rightInset, transition: 'padding 200ms ease' }}>
+      {children}
+    </Box>
+  );
+}
+\`\`\`
+
+**Notes**
+- In mobile, the drawer overlays content (no reserved space).
+- Changing \`drawerWidth\` on desktop will propagate to \`theme.insets.right\` automatically.
+`,
+      },
+    },
+  },
+  argTypes: {
+    rightContext: {
+      description: 'Object with `title` and `items` describing the drawer content.',
+      control: 'object',
+    },
+  },
+} satisfies Meta<typeof RightSidebar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// --- Stories ---
+
+const BASE_TITLE = 'Context';
+
+export const Default: Story = {
+  args: {
+    rightContext: {
+      title: BASE_TITLE,
+      items: [
+        { label: 'Overview', href: '/overview' },
+        { label: 'Settings', href: '/settings' },
+        {
+          label: 'Resources',
+          children: [
+            { label: 'Docs', href: '/docs' },
+            { label: 'API', href: '/api' },
+          ],
+        },
+      ],
+    },
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    rightContext: {
+      title: BASE_TITLE,
+      items: [
+        { label: 'Inbox', href: '/inbox', icon: 'mui:Email' },
+        { label: 'Reports', href: '/reports', icon: 'mui:Insights' },
+        {
+          label: 'More',
+          icon: 'lucide:more-horizontal',
+          children: [
+            { label: 'Activity', href: '/activity', icon: 'lucide:activity' },
+            { label: 'Security', href: '/security', icon: 'mui:Security' },
+          ],
+        },
+      ],
+    },
+  },
+};
+
+export const WithColoredIcons: Story = {
+  args: {
+    rightContext: {
+      title: BASE_TITLE,
+      items: [
+        { label: 'Inbox', href: '/inbox', icon: 'mui:Email', iconColor: 'primary' },
+        { label: 'Billing', href: '/billing', icon: 'mui:AttachMoney', iconColor: '#2e7d32' },
+        {
+          label: 'Analytics',
+          icon: 'lucide:bar-chart-3',
+          iconColor: '#00aa96',
+          children: [
+            { label: 'Trends', href: '/trends', icon: 'lucide:trending-up', iconColor: '#4caf50' },
+            { label: 'Dashboards', href: '/dashboards', icon: 'mui:Insights', iconColor: 'secondary' },
+          ],
+        },
+      ],
+    },
+  },
+};
+
+export const Docs_UsageModes: Story = {
+  render: () => (
+    <div style={{ maxWidth: 920, padding: 24, lineHeight: 1.55 }}>
+      <h2 style={{ marginTop: 0 }}>Using Icons in RightSidebar</h2>
+
+      <h3>1. Declarative Mode (recommended)</h3>
+      <p>
+        Provide icon names as <code>strings</code> with the <code>mui:</code> or <code>lucide:</code> prefix.
+        Colors can be theme keys (e.g. <code>primary</code>, <code>secondary</code>) or CSS colors (e.g. <code>#4caf50</code>).
+      </p>
+      <pre style={{ background: '#0f111a', color: '#e6e6e6', padding: 16, borderRadius: 8, overflow: 'auto' }}>
+        <code>{`const rightContext = {
+  title: 'Context',
+  items: [
+    { label: 'Inbox', href: '/inbox', icon: 'mui:Email', iconColor: 'primary' },
+    { label: 'Reports', href: '/reports', icon: 'mui:Insights', iconColor: '#ff9800' },
+    {
+      label: 'More', icon: 'lucide:more-horizontal', children: [
+        { label: 'Activity', href: '/activity', icon: 'lucide:activity', iconColor: '#00aa96' },
+        { label: 'Security', href: '/security', icon: 'mui:Security', iconColor: 'info' },
+      ]
+    }
+  ]
+};
+<RightSidebar rightContext={rightContext} />`}</code>
+      </pre>
+
+      <h3>2. Direct React Mode (advanced)</h3>
+      <p>
+        Import icon components yourself and pass them as React elements in <code>icon</code>. This bypasses the registry.
+      </p>
+      <pre style={{ background: '#0f111a', color: '#e6e6e6', padding: 16, borderRadius: 8, overflow: 'auto' }}>
+        <code>{`import { Mail } from 'lucide-react';
+import InsightsIcon from '@mui/icons-material/Insights';
+
+const rightContext = {
+  title: 'Context',
+  items: [
+    { label: 'Inbox', href: '/inbox', icon: <Mail color="#4caf50" /> },
+    { label: 'Reports', href: '/reports', icon: <InsightsIcon htmlColor="#ff9800" /> },
+  ]
+};
+<RightSidebar rightContext={rightContext} />`}</code>
+      </pre>
+
+      <p>
+        In both modes, nested groups are declared via the <code>children</code> array of any item.
+      </p>
+    </div>
+  ),
+};
+
+export const Docs_Insets: Story = {
+  render: () => (
+    <div style={{ maxWidth: 920, padding: 24, lineHeight: 1.55 }}>
+      <h2 style={{ marginTop: 0 }}>RightSidebar & Layout Insets</h2>
+      <p>
+        On desktop, RightSidebar is permanent and reserves space by updating <code>theme.insets.right</code> via
+        the Theme Provider API (<code>theme.updateInsets</code>). On mobile it is temporary and does not reserve space.
+      </p>
+      <pre style={{ background: '#0f111a', color: '#e6e6e6', padding: 16, borderRadius: 8, overflow: 'auto' }}>
+        <code>{`// Inside RightSidebar (simplified)
+useEffect(() => {
+  if (isPermanent) theme.updateInsets?.({ right: drawerWidth });
+  else theme.updateInsets?.({ right: 0 });
+  return () => theme.updateInsets?.({ right: 0 });
+}, [isPermanent, drawerWidth]);
+`}</code>
+      </pre>
+      <p>
+        Consumers can read the value from <code>theme.layout.insets.right</code> to pad containers or footers:
+      </p>
+      <pre style={{ background: '#0f111a', color: '#e6e6e6', padding: 16, borderRadius: 8, overflow: 'auto' }}>
+        <code>{`const theme = useTheme();
+const rightInset = theme.layout.insets.right || 0;
+return <Box sx={{ pr: rightInset }}>Content</Box>;
+`}</code>
+      </pre>
+    </div>
+  ),
+};
+
+export const WithNavbar: Story = {
+  args: {
+    rightContext: {
+      title: 'Context',
+      items: [
+        { label: 'Inbox', href: '/inbox', icon: 'mui:Email' },
+        { label: 'Reports', href: '/reports', icon: 'mui:Insights' },
+        {
+          label: 'More',
+          icon: 'lucide:more-horizontal',
+          children: [
+            { label: 'Activity', href: '/activity', icon: 'lucide:activity' },
+            { label: 'Security', href: '/security', icon: 'mui:Security' },
+          ],
+        },
+      ],
+    },
+  },
+  render: (args) => (
+    <>
+      {/* Fixed AppBar that reports its height via ThemeContext */}
+      <NavBar title="Demo" />
+      <RightSidebar {...args} />
+    </>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'RightSidebar with a fixed NavBar on top. The NavBar updates `theme.insets.nav` (and `--gui-nav-height`) in real time, so the drawer aligns its `top`/`height` accordingly. Compare this with the default stories (without NavBar).',
+      },
+    },
+  },
+};

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

@@ -0,0 +1,295 @@
+import React from "react";
+import Icon from "../../../../themes/icons/Icon";
+import {
+  Drawer,
+  List,
+  ListItem,
+  ListItemButton,
+  ListItemIcon,
+  ListItemText,
+  Box,
+  Typography,
+  Collapse,
+} from "@/gui/atoms";
+import { Link as RouterLink } from "react-router-dom";
+import { useGuiTheme, useGuiMediaQuery } from "@/gui";
+import type { GuiTheme } from "@/gui";
+import type * as ReactTypes from "react";
+export type RightSidebarIcon =
+  | string
+  | ReactTypes.ComponentType<any>
+  | React.ReactNode;
+export type RightSidebarItem = {
+  type?: "label";
+  label?: string;
+  href?: string;
+  external?: boolean;
+  onClick?: () => void;
+  icon?: RightSidebarIcon;
+  iconColor?: string;
+  children?: RightSidebarItem[];
+};
+
+export type RightContext = {
+  title?: string;
+  items: RightSidebarItem[];
+};
+
+export type RightSidebarProps = {
+  rightContext?: RightContext;
+  drawerWidth?: number;
+  open?: boolean;
+  onClose?: (event?: any) => void;
+  sx?: any;
+  paperSx?: any;
+  headerSx?: any;
+  contentSx?: any;
+  footerSx?: any;
+  id?: string;
+  className?: string;
+  "data-testid"?: string;
+};
+
+const drawerStyles = (
+  theme: GuiTheme,
+  width: number
+) => ({
+  width,
+  backgroundColor:
+    theme.palette.mode === "light"
+      ? theme.palette.background.paper
+      : theme.palette.background.default,
+  top: "var(--gui-nav-height, 48px)",
+  height: "calc(100vh - var(--gui-nav-height, 48px))",
+});
+
+function DrawerContent({ rightContext, headerSx, contentSx }: { rightContext?: RightContext; headerSx?: any; contentSx?: any }) {
+  const { title, items: contextItems } = rightContext || {};
+  const items = Array.isArray(contextItems) ? contextItems : [];
+  const [openItems, setOpenItems] = React.useState<Record<number, boolean>>({});
+  const toggleOpen = (index: number) => {
+    setOpenItems((prev) => ({ ...prev, [index]: !prev[index] }));
+  };
+
+  return (
+    <Box role="presentation">
+      {title && (
+        <Box
+          sx={{ px: 2, pt: 2, pb: 2, borderBottom: "1px solid", borderColor: "divider", ...headerSx }}
+        >
+          <Typography variant="h6" sx={{ fontWeight: 600 }}>
+            {title}
+          </Typography>
+        </Box>
+      )}
+      <List sx={contentSx}>
+        {items.map((item, index) => {
+          if (item.type === "label") {
+            return (
+              <ListItem key={index} sx={{ px: 2, py: 1.5, justifyContent: "center" }}>
+                <Typography
+                  variant="subtitle2"
+                  color="text.secondary"
+                  sx={{
+                    fontWeight: 600,
+                    fontSize: "0.85rem",
+                    textAlign: "center",
+                    backgroundColor: (theme) => theme.palette.action.hover,
+                    px: 1.5,
+                    py: 0.5,
+                    borderRadius: 1,
+                    width: "100%",
+                  }}
+                >
+                  {item.label}
+                </Typography>
+              </ListItem>
+            );
+          }
+          const hasChildren = Array.isArray(item.children) && item.children.length > 0;
+          const isOpen = openItems[index] || false;
+          return (
+            <React.Fragment key={index}>
+              <ListItem disablePadding>
+                <ListItemButton
+                  component={item.href ? RouterLink : "div"}
+                  to={item.href}
+                  onClick={
+                    hasChildren
+                      ? () => toggleOpen(index)
+                      : !item.href && item.onClick
+                      ? item.onClick
+                      : undefined
+                  }
+                  sx={{
+                    "& .MuiListItemText-primary": { fontWeight: 400 },
+                  }}
+                >
+                  {item.icon ? (
+                    <ListItemIcon sx={{ minWidth: 24, mr: 1 }}>
+                      {typeof item.icon === "string" ? (
+                        <Icon name={item.icon} iconColor={item.iconColor} size={18} />
+                      ) : typeof item.icon === "function" ? (
+                        React.createElement(item.icon as ReactTypes.ComponentType<any>)
+                      ) : (
+                        item.icon
+                      )}
+                    </ListItemIcon>
+                  ) : null}
+                  <ListItemText primary={item.label} />
+                  {hasChildren &&
+                    (isOpen ? (
+                      <Icon name="mui:ExpandLess" size={18} />
+                    ) : (
+                      <Icon name="mui:ExpandMore" size={18} />
+                    ))}
+                </ListItemButton>
+              </ListItem>
+              {hasChildren && (
+                <Collapse in={isOpen} timeout="auto" unmountOnExit>
+                  <Box sx={{ mr: 2, borderRight: "1px dashed", pr: 2 }}>
+                    {(item.children ?? []).map((child, childIndex) => (
+                      <ListItem key={childIndex} disablePadding>
+                        <ListItemButton
+                          component={child.href ? RouterLink : "div"}
+                          to={child.href}
+                          onClick={!child.href && child.onClick ? child.onClick : undefined}
+                          sx={{
+                            justifyContent: "flex-end",
+                            textAlign: "right",
+                            "& .MuiListItemText-primary": {
+                              fontWeight: 400,
+                              textAlign: "right",
+                            },
+                          }}
+                        >
+                          {child.icon ? (
+                            <ListItemIcon sx={{ minWidth: 24, mr: 1 }}>
+                              {typeof child.icon === "string" ? (
+                                <Icon
+                                  name={child.icon}
+                                  iconColor={child.iconColor}
+                                  size={18}
+                                />
+                              ) : typeof child.icon === "function" ? (
+                                React.createElement(
+                                  child.icon as ReactTypes.ComponentType<any>
+                                )
+                              ) : (
+                                child.icon
+                              )}
+                            </ListItemIcon>
+                          ) : null}
+                          <ListItemText primary={child.label} />
+                        </ListItemButton>
+                      </ListItem>
+                    ))}
+                  </Box>
+                </Collapse>
+              )}
+            </React.Fragment>
+          );
+        })}
+      </List>
+    </Box>
+  );
+}
+
+export default function RightSidebar({
+  rightContext,
+  drawerWidth = 260,
+  open,
+  onClose,
+  sx,
+  paperSx,
+  headerSx,
+  contentSx,
+  footerSx,
+  id,
+  className,
+  "data-testid": dataTestId,
+}: RightSidebarProps) {
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down("md"));
+  const isControlled = typeof open === "boolean";
+  const [internalOpen, setInternalOpen] = React.useState(false);
+  const effectiveOpen = isControlled ? open! : internalOpen;
+  const isPermanent = !isMobile;
+
+  React.useEffect(() => {
+    if (!isControlled) {
+      setInternalOpen(!isMobile);
+    }
+  }, [isMobile, isControlled]);
+
+  React.useEffect(() => {
+    const setInsets = theme?.updateInsets;
+    const currentRight = theme?.layout?.insets?.right ?? 0;
+    if (typeof setInsets === "function") {
+      const desired = isPermanent ? drawerWidth : 0;
+      if (currentRight !== desired) {
+        setInsets({ right: desired });
+      }
+      return () => {
+        const rightOnCleanup = theme?.layout?.insets?.right ?? 0;
+        if (rightOnCleanup !== 0) setInsets({ right: 0 });
+      };
+    }
+  }, [isPermanent, drawerWidth]);
+
+  if (!rightContext || !rightContext.items?.length) return null;
+
+  return (
+    <>
+      {!isControlled && isMobile && !effectiveOpen && (
+        <Box
+          sx={{
+            position: "fixed",
+            top: "50%",
+            right: 0,
+            transform: "translateY(-50%)",
+            zIndex: theme.zIndex.drawer + 1,
+          }}
+        >
+          <Box
+            onClick={() => setInternalOpen(true)}
+            sx={{
+              backgroundColor: theme.palette.primary.main,
+              color: "#fff",
+              p: 1,
+              borderRadius: "8px 0 0 8px",
+              cursor: "pointer",
+              width: drawerWidth,
+            }}
+          >
+            &gt;
+          </Box>
+        </Box>
+      )}
+      <Drawer
+        id={id}
+        className={className}
+        data-testid={dataTestId}
+        anchor="right"
+        open={effectiveOpen}
+        onClose={() => {
+          if (isControlled) {
+            onClose?.();
+          } else {
+            setInternalOpen(false);
+          }
+        }}
+        variant={isMobile ? "temporary" : "persistent"}
+        sx={{
+          ...sx,
+          "& .MuiDrawer-paper": {
+            ...drawerStyles(theme, drawerWidth),
+            ...paperSx,
+          },
+        }}
+      >
+        <DrawerContent rightContext={rightContext} headerSx={headerSx} contentSx={contentSx} />
+      </Drawer>
+    </>
+  );
+}