this.gui 1.3.40 → 1.3.42

package/src/gui/components/molecules/Modal/Modal.tsx

@@ -0,0 +1,110 @@
+import React from "react";
+import { Box, Typography, IconButton } from "@/gui/components/atoms";
+import { useGuiTheme } from "@/gui/hooks";
+// Try importing CloseIcon from MUI; fallback to a local SVG if missing
+let CloseIcon: any;
+try {
+  // @ts-ignore
+  CloseIcon = require("@mui/icons-material/Close").default;
+} catch {
+  CloseIcon = () => (
+    <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+      <path d="M6 6L18 18M6 18L18 6" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+    </svg>
+  );
+}
+
+interface ModalProps {
+  open: boolean;
+  title?: string;
+  onClose: () => void;
+  children?: React.ReactNode;
+  width?: number | string;
+  height?: number | string;
+  blurBackground?: boolean;
+  xyz?: { x?: number; y?: number; z?: number };
+  insets?: { top?: number; right?: number; bottom?: number; left?: number };
+}
+
+const Modal: React.FC<ModalProps> = ({
+  open,
+  title,
+  onClose,
+  children,
+  width = 400,
+  height = "auto",
+  blurBackground = true,
+  xyz,
+  insets,
+}) => {
+  const theme = useGuiTheme();
+  const zIndex = (theme as any)?.zIndex?.modal ?? (theme as any)?.zIndex?.drawer ?? 1300;
+
+  if (!open) return null;
+
+  return (
+    <Box
+      sx={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        width: "100vw",
+        height: "100vh",
+        bgcolor: blurBackground ? "rgba(0,0,0,0.35)" : "rgba(0,0,0,0.6)",
+        backdropFilter: blurBackground ? "blur(8px)" : "none",
+        display: "flex",
+        justifyContent: "center",
+        alignItems: "center",
+        p: 2,
+        pt: `calc(16px + ${Number(insets?.top ?? 0)}px)`,
+        pr: `calc(16px + ${Number(insets?.right ?? 0)}px)`,
+        pb: `calc(16px + ${Number(insets?.bottom ?? 0)}px)`,
+        pl: `calc(16px + ${Number(insets?.left ?? 0)}px)`,
+        boxSizing: "border-box",
+        zIndex,
+      }}
+      onClick={onClose}
+    >
+      <Box
+        sx={{
+          width,
+          height,
+          bgcolor: "background.paper",
+          color: "text.primary",
+          borderRadius: 4,
+          border: "1px solid",
+          borderColor: "divider",
+          boxShadow: 8,
+          p: 3,
+          animation: "fadeIn 0.2s ease",
+          position: "relative",
+          transform: `translate3d(${xyz?.x || 0}px, ${xyz?.y || 0}px, ${xyz?.z || 0}px)`,
+          transformStyle: "preserve-3d",
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        {title && (
+          <Typography variant="h6" sx={{ mb: 2, fontWeight: 600 }}>
+            {title}
+          </Typography>
+        )}
+        <IconButton
+          onClick={onClose}
+          sx={{
+            position: "absolute",
+            top: 8,
+            right: 8,
+            color: "text.secondary",
+            "&:hover": { color: "text.primary" },
+          }}
+        >
+          <CloseIcon />
+        </IconButton>
+
+        <Box>{children}</Box>
+      </Box>
+    </Box>
+  );
+};
+
+export default Modal;

package/src/gui/components/molecules/Modal/Modal.types.ts

@@ -0,0 +1,29 @@
+/**
+ * ModalBoxProps
+ * Declarative prop types for the ModalBox component.
+ * Supports basic modal behavior and 3D positioning.
+ */
+export interface ModalProps {
+  /** Controls whether the modal is open or closed */
+  open: boolean;
+  /** Optional title to display in the modal header */
+  title?: string;
+  /** Handler to call when the modal should close */
+  onClose?: () => void;
+  /** Modal width (e.g., '400px', '60%', etc.) */
+  width?: string | number;
+  /** Modal height (e.g., 'auto', '80vh', etc.) */
+  height?: string | number;
+  /** Applies a background blur effect when true */
+  blurBackground?: boolean;
+  /** Optional 3D position vector for experimental modal placement */
+  xyz?: [number, number, number];
+  /** Additional className for styling */
+  className?: string;
+  /** Optional ID for targeting and registry mapping */
+  id?: string;
+  /** Optional test ID for automated testing */
+  ['data-testid']?: string;
+  /** Modal content */
+  children?: React.ReactNode;
+}

package/src/gui/components/molecules/Page/Page.stories.tsx

@@ -0,0 +1,135 @@
+import { Hero } from '@/gui/components/molecules/Hero/Hero';
+import { InsetsProvider } from '@/gui/contexts/InsetsContext';
+import Layout from '@/gui/Theme/Layout/Layout/Layout';
+import type { Meta, StoryObj } from '@storybook/react';
+import Page from './Page';
+
+const meta: Meta<typeof Page> = {
+  title: 'Molecules/Content/Page',
+  component: Page,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Page** is a layout container used to render content inside a layout or route.
+
+---
+## Features
+- Acts as a flexible container for layout content.
+- Supports padding, background color, and custom \`sx\` overrides.
+- Centers and spaces content using responsive defaults.
+- Works seamlessly inside \`Layout\` components.
+
+---
+## Props
+- \`children\`: React nodes to render within the page.
+- \`padding\`: Number or string for inner spacing.
+- \`background\`: Background color or gradient.
+- \`sx\`: MUI style overrides.
+- \`insets\`: Optional positioning insets (top, right, bottom, left) for dynamic positioning.
+        `,
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Page>;
+
+export const Default: Story = {
+  args: {
+    children: (
+      <div style={{ textAlign: 'center', fontSize: '1.5rem', marginTop: '40vh' }}>
+        This is a default Page.
+      </div>
+    ),
+  },
+};
+
+export const WithPadding: Story = {
+  args: {
+    padding: 6,
+    children: (
+      <div style={{ textAlign: 'center', fontSize: '1.5rem' }}>
+        Page with custom padding (6)
+      </div>
+    ),
+  },
+};
+
+export const WithBackground: Story = {
+  args: {
+    background: 'linear-gradient(135deg, #00bcd4, #006064)',
+    children: (
+      <div style={{ color: 'white', fontSize: '1.5rem', textAlign: 'center', marginTop: '40vh' }}>
+        Page with gradient background
+      </div>
+    ),
+  },
+};
+
+export const CustomSx: Story = {
+  args: {
+    sx: {
+      border: '2px dashed #29b6f6',
+      borderRadius: '16px',
+      backgroundColor: '#e3f2fd',
+    },
+    children: (
+      <div style={{ textAlign: 'center', fontSize: '1.5rem', marginTop: '40vh' }}>
+        Page with custom sx styles
+      </div>
+    ),
+  },
+};
+
+export const InsetsAwarePage: Story = {
+  render: (args) => (
+    <InsetsProvider>
+      <Page {...args}>
+        <div style={{ textAlign: 'center', fontSize: '1.5rem', marginTop: '40vh' }}>
+          Page with padding that adapts to layout insets.
+        </div>
+      </Page>
+    </InsetsProvider>
+  ),
+  args: {
+    background: "rgba(0, 188, 212, 0.15)",
+    padding: 24,
+    insetsAware: true,
+  },
+};
+
+export const LayoutWithPageAndHero: Story = {
+  render: () => (
+    <InsetsProvider>
+      <Layout
+        topBarConfig={{ title: 'Neuroverse Layout' }}
+        leftSidebarConfig={{ initialView: 'menu' }}
+        rightSidebarConfig={{ initialView: 'chat' }}
+      >
+        <Page background="linear-gradient(135deg, #0a192f, #172a45)" padding={4}>
+          <Hero
+            backgroundSrc="https://images.unsplash.com/photo-1522202195463-8f34a5fa1d15"
+            backgroundType="image"
+            overlayColor="rgba(10, 25, 47, 0.6)"
+            blur="light"
+          >
+            <div
+              style={{
+                color: 'white',
+                fontSize: '2rem',
+                fontWeight: 600,
+                textAlign: 'center',
+                marginTop: '40vh',
+              }}
+            >
+              Layout with TopBar, LeftSidebar and a HeroSection inside Page
+            </div>
+          </Hero>
+        </Page>
+      </Layout>
+    </InsetsProvider>
+  ),
+};

package/src/gui/components/molecules/Page/Page.tsx

@@ -0,0 +1,94 @@
+// Page.tsx
+import React, { useMemo } from 'react';
+import { Box } from '@/gui/components/atoms';
+import { useInsetsContext } from '@/gui/contexts/InsetsContext';
+import { useGuiTheme } from '@/gui/hooks';
+export interface PageProps {
+  children?: React.ReactNode;
+  padding?: number | string;
+  background?: string;
+  sx?: any;
+  insetsAware?: boolean;
+}
+/**
+ * Page
+ * ----------
+ * A flexible container for rendering page-level content within layouts.
+ * Typically used inside Layout components or Routes.
+ *
+ * Features:
+ * - Applies consistent padding and layout structure.
+ * - Supports background color/image and custom sx overrides.
+ * - Fully responsive by default.
+ */
+export default function Page({
+  children,
+  padding = 3,
+  background = 'transparent',
+  sx = {},
+  insetsAware = true,
+}: PageProps) {
+  useInsetsContext();
+  const theme = useGuiTheme();
+
+  const resolvedPadding = useMemo(() => {
+    if (typeof padding === 'number') {
+      if (padding <= 10 && typeof theme.spacing === 'function') {
+        return theme.spacing(padding);
+      }
+      return `${padding}px`;
+    }
+    return padding ?? '0px';
+  }, [padding, theme]);
+
+  const isUniformPadding =
+    typeof resolvedPadding === 'string' && resolvedPadding.trim().split(/\s+/).length === 1;
+
+  const basePadding = isUniformPadding ? resolvedPadding : undefined;
+  const topCalc =
+    insetsAware && basePadding
+      ? `calc(${basePadding} + var(--gui-inset-top, 0px))`
+      : undefined; 
+  const bottomCalc =
+    insetsAware && basePadding
+      ? `calc(${basePadding} + var(--gui-inset-bottom, 0px))`
+      : undefined;
+  const leftCalc =
+    insetsAware && basePadding
+      ? `calc(${basePadding} + var(--gui-inset-left, 0px))`
+      : undefined;
+  const rightCalc =
+    insetsAware && basePadding
+      ? `calc(${basePadding} + var(--gui-inset-right, 0px))`
+      : undefined;
+
+  return (
+    <Box
+      id="page-container"
+      sx={{
+        flex: 1,
+        flexGrow: 1,
+        width: '100%',
+        minHeight: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        overflowY: 'auto',
+        overflowX: 'hidden',
+        padding: resolvedPadding,
+        background,
+        boxSizing: 'border-box',
+        ...(insetsAware &&
+          basePadding && {
+            padding: 0,
+            paddingTop: topCalc,
+            paddingBottom: bottomCalc,
+            paddingLeft: leftCalc,
+            paddingRight: rightCalc,
+          }),
+        ...sx,
+      }}
+    >
+      {children}
+    </Box>
+  );
+}

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.resolver.tsx

@@ -0,0 +1,58 @@
+import ThemeModeToggle from './ThemeModeToggle';
+import { ThemeModeToggleResolverSpec } from './ThemeModeToggle.types';
+/**
+ * Resolver for ThemeModeToggle
+ * ----------------------------
+ * Allows you to render the ThemeModeToggle from a plain JSON/config object.
+ *
+ * Minimal accepted shape:
+ * {
+ *   "type": "ThemeModeToggle",
+ *   "props": {
+ *     "variant": "minimal" | "switchMinimal" | "switchWithLabel",
+ *     "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 function resolveThemeModeToggle(p: ThemeModeToggleResolverSpec = {}) {
+  const {
+    variant = 'minimal',
+    show = 'icons',
+    id,
+    className,
+    ['data-testid']: dataTestId,
+    sx,
+    iconSx,
+    switchSx,
+    labelSx,
+    switchSize,
+    iconSize,
+  } = p;
+
+  return (
+    <ThemeModeToggle
+      variant={variant}
+      show={show}
+      id={id}
+      className={className}
+      data-testid={dataTestId}
+      sx={sx}
+      iconSx={iconSx}
+      switchSx={switchSx}
+      labelSx={labelSx}
+      switchSize={switchSize}
+      iconSize={iconSize}
+    />
+  );
+}
+
+export default resolveThemeModeToggle;

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ThemeModeToggle from './ThemeModeToggle';
+
+// ======================= Meta =======================
+const meta: Meta<typeof ThemeModeToggle> = {
+  title: 'Theme/ThemeModeToggle',
+  component: ThemeModeToggle,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 24, minHeight: 160, display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ThemeModeToggle** is a theme control molecule that allows users to toggle between **light**, **dark**, and optionally **system** themes in a UI.
+
+---
+## What it does
+ThemeModeToggle provides a way to change the global color mode of the app via UI toggles. It connects with \`useThemeMode\` from This.GUI, so any updates reflect instantly in your theme context.
+
+---
+## Visual Variants
+This component supports multiple visual representations depending on how much context or control you want to show the user:
+
+- **minimal**: Just a clickable icon (uses IconButton).
+- **switchMinimal**: Shows a switch with sun/moon icons.
+- **switchWithLabel**: Shows the switch, icons, and a label that updates dynamically between "Light" and "Dark".
+
+---
+## Props
+- \`variant?: 'minimal' | 'switchMinimal' | 'switchWithLabel'\`
+  - Determines the UI structure.
+- \`show?: 'icons' | 'label' | 'both'\`
+  - For \`variant="minimal"\` only. Controls whether to show icon, label or both.
+- \`switchSize?: 'small' | 'medium'\` — size of the MUI Switch.
+- \`iconSize?: 'small' | 'medium' | 'large'\` — size of the icons.
+- \`sx\`, \`iconSx\`, \`switchSx\`, \`labelSx\` — MUI system styling overrides.
+- \`id\`, \`className\`, \`data-testid\` — standard element props.
+
+---
+## Internal Logic
+- Uses \`useThemeContext()\` to read current mode (\`light\` or \`dark\`) and the \`toggleMode()\` handler.
+- Dynamically determines whether current mode is \`light\` or not to drive the state of the UI (like whether switch is \`checked\` or not).
+- Automatically updates \`labelText\` based on the mode.
+
+---
+## Usage Examples
+
+### Basic usage in React:
+~~~tsx
+<ThemeModeToggle variant="minimal" />
+<ThemeModeToggle variant="switchMinimal" />
+<ThemeModeToggle variant="switchWithLabel" />
+~~~
+
+### Declarative JSON usage:
+~~~json
+{
+  "type": "ThemeModeToggle",
+  "props": {
+    "variant": "switchWithLabel",
+    "iconSize": "medium",
+    "switchSize": "small",
+    "sx": { "ml": 2 }
+  }
+}
+~~~
+
+---
+## Design Notes
+This component is designed to be:
+- **Declarative-first**: usable directly from This.GUI config structures.
+- **Minimal footprint**: all styling is optional and overrideable.
+- **Context-integrated**: updates global theme state through context, not local component state.
+
+Ideal for UIs where users are expected to switch theme modes or where accessible, theme-aware interfaces are critical.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['minimal', 'switch'],
+    },
+    sx: {
+      control: 'object',
+      description: 'MUI system style overrides.',
+    },
+    show: {
+      control: { type: 'radio' },
+      options: ['icons', 'label', 'both'],
+      description: 'Controls whether to show icons, label, or both.',
+    },
+  },
+  args: {
+    variant: 'minimal',
+    sx: {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ThemeModeToggle>;
+
+// ======================= Stories =======================
+
+export const Playground: Story = {
+  render: (args) => <ThemeModeToggle {...args} />,
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 24, flexDirection: 'column' }}>
+      <div>
+        <h4>minimal (icon only)</h4>
+        <ThemeModeToggle variant="minimal" />
+      </div>
+      <div>
+        <h4>switchMinimal (switch with icons)</h4>
+        <ThemeModeToggle variant="switchMinimal" show="icons" />
+      </div>
+      <div>
+        <h4>switchWithLabel (switch with icons + label)</h4>
+        <ThemeModeToggle variant="switchWithLabel" show="both" />
+      </div>
+    </div>
+  ),
+};

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.tsx

@@ -0,0 +1,101 @@
+import React from 'react';
+import { IconButton, Switch } from '@/gui/components/atoms';
+import Icon from '@/gui/Theme/Icon/Icon';
+import { useThemeContext } from '@/gui/Theme';
+import { Typography, Box } from '@/gui/components/atoms';
+import type { ThemeModeToggleProps } from './ThemeModeToggle.types';
+
+const ThemeModeToggle: React.FC<ThemeModeToggleProps> = ({
+  variant = 'minimal',
+  show = 'icons',
+  switchSize = 'medium',
+  iconSize = 'medium',
+  sx,
+  iconSx,
+  switchSx,
+  labelSx,
+  id,
+  className,
+  ['data-testid']: dataTestId,
+}) => {
+  const { mode, toggleMode } = useThemeContext();
+  const isLight = mode === 'light';
+  const labelText = isLight ? 'Light' : 'Dark';
+  const iconFontSize = {
+    small: '1rem',
+    medium: '1.5rem',
+    large: '2rem',
+  }[iconSize];
+
+  const handleToggle = () => {
+    toggleMode();
+  };
+  if (variant === 'switchMinimal' || variant === 'switchWithLabel') {
+    return (
+      <Box
+        id={id}
+        display="flex"
+        alignItems="center"
+        sx={sx ? ([{ cursor: 'pointer' }, sx] as any) : ({ cursor: 'pointer' } as any)}
+        className={className}
+        data-testid={dataTestId}
+      >
+        {/* Always show icons for both switch variants */}
+        <Icon
+          name="light_mode"
+          iconColor={isLight ? 'primary' : 'disabled'}
+          fontSize={iconFontSize}
+        />
+        <Switch
+          checked={!isLight}
+          onChange={handleToggle}
+          color="primary"
+          size={switchSize}
+          inputProps={{ 'aria-label': 'toggle theme mode' }}
+          sx={switchSx}
+        />
+        <Icon
+          name="dark_mode"
+          iconColor={!isLight ? 'primary' : 'disabled'}
+          fontSize={iconFontSize}
+        />
+        {variant === 'switchWithLabel' && (
+          <Typography
+            sx={
+              labelSx
+                ? ([{ ml: 1 }, labelSx] as any)
+                : ({ ml: 1 } as any)
+            }
+          >
+            {labelText}
+          </Typography>
+        )}
+      </Box>
+    );
+  }
+
+  // variant === 'minimal'
+  return (
+    <IconButton id={id} onClick={handleToggle} color="inherit" aria-label="toggle theme mode" size={iconSize} className={className} data-testid={dataTestId} sx={sx}>
+      {show !== 'label' &&
+        (isLight ? (
+          <Icon name="light_mode" iconColor="primary" fontSize={iconFontSize} />
+        ) : (
+          <Icon name="dark_mode" iconColor="primary" fontSize={iconFontSize} />
+        ))}
+      {(show === 'label' || show === 'both') && (
+        <Typography
+          sx={
+            labelSx
+              ? ([{ ml: show === 'both' ? 1 : 0 }, labelSx] as any)
+              : ({ ml: show === 'both' ? 1 : 0 } as any)
+          }
+        >
+          {labelText}
+        </Typography>
+      )}
+    </IconButton>
+  );
+};
+
+export default ThemeModeToggle;

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.types.ts

@@ -0,0 +1,29 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+export type ThemeModeToggleProps = {
+  variant?: 'minimal' | 'switchMinimal' | 'switchWithLabel';
+  show?: 'icons' | 'label' | 'both';
+  id?: string;
+  className?: string;
+  ['data-testid']?: string;
+  sx?: SxProps<Theme>;
+  iconSx?: SxProps<Theme>;
+  switchSx?: SxProps<Theme>;
+  labelSx?: SxProps<Theme>;
+  switchSize?: 'small' | 'medium';
+  iconSize?: 'small' | 'medium' | 'large';
+};
+
+export type ThemeModeToggleResolverSpec = {
+  type?: 'ThemeModeToggle';
+  variant?: 'minimal' | 'switchMinimal' | 'switchWithLabel';
+  show?: 'icons' | 'label' | 'both';
+  id?: string;
+  className?: string;
+  ['data-testid']?: string;
+  sx?: SxProps<Theme>;
+  iconSx?: SxProps<Theme>;
+  switchSx?: SxProps<Theme>;
+  labelSx?: SxProps<Theme>;
+  switchSize?: 'small' | 'medium';
+  iconSize?: 'small' | 'medium' | 'large';
+};