this.gui 1.3.40 → 1.3.42

package/src/gui/components/generics/Organization/TableOfContents.jsx

@@ -0,0 +1,51 @@
+import { List, ListItemButton, ListItemText, Typography } from "@mui/material";
+
+/**
+ * PageTableOfContents Component
+ * Generates a table of contents (TOC) from an array of headings.
+ *
+ * Props:
+ * - headings: Array of objects with { id, text, level }:
+ *   - id: The anchor or unique identifier (used for scrolling).
+ *   - text: The heading text to display.
+ *   - level: Heading level (1, 2, or 3). Used to indent items.
+ * - onNavigate: Optional callback when a TOC item is clicked (receives id).
+ */
+export default function TableOfContents({ headings = [], onNavigate }) {
+  if (!headings || headings.length === 0) return null;
+
+  const handleClick = (id) => {
+    if (onNavigate) {
+      onNavigate(id);
+    } else {
+      const el = document.getElementById(id);
+      if (el) el.scrollIntoView({ behavior: "smooth", block: "start" });
+    }
+  };
+
+  return (
+    <div style={{ padding: "1rem" }}>
+      <Typography variant="h6" sx={{ mb: 1 }}>
+        Table of Contents
+      </Typography>
+      <List dense>
+        {headings.map((heading, index) => (
+          <ListItemButton
+            key={index}
+            sx={{
+              pl: heading.level === 1 ? 1 : heading.level === 2 ? 3 : 5,
+            }}
+            onClick={() => handleClick(heading.id)}
+          >
+            <ListItemText
+              primaryTypographyProps={{
+                variant: heading.level === 1 ? "body1" : "body2",
+              }}
+              primary={heading.text}
+            />
+          </ListItemButton>
+        ))}
+      </List>
+    </div>
+  );
+}

package/src/gui/components/generics/Organization/Tabs.jsx

@@ -0,0 +1,45 @@
+import { useState } from "react";
+import { Tabs as MuiTabs, Tab, Box, Typography } from "@mui/material";
+
+/**
+ * Tabs Component
+ * A simple tab system to switch between different content sections.
+ *
+ * Props:
+ * - tabs: Array of objects { label, content } (required).
+ * - initialIndex: Index of the tab to show first (default: 0).
+ * - variant: Tabs variant ("standard" | "scrollable" | "fullWidth"). Default: "standard".
+ */
+export default function Tabs({ tabs = [], initialIndex = 0, variant = "standard" }) {
+  const [value, setValue] = useState(initialIndex);
+
+  const handleChange = (event, newValue) => {
+    setValue(newValue);
+  };
+
+  if (!tabs || tabs.length === 0) {
+    return <Typography variant="body2">No tabs available.</Typography>;
+  }
+
+  return (
+    <Box sx={{ width: "100%" }}>
+      <MuiTabs
+        value={value}
+        onChange={handleChange}
+        variant={variant}
+        sx={{ mb: 2 }}
+      >
+        {tabs.map((tab, index) => (
+          <Tab key={index} label={tab.label} />
+        ))}
+      </MuiTabs>
+      <Box sx={{ p: 2 }}>
+        {tabs[value]?.content || (
+          <Typography variant="body2" color="text.secondary">
+            No content for this tab.
+          </Typography>
+        )}
+      </Box>
+    </Box>
+  );
+}

package/src/gui/components/generics/Text/TextList.jsx

@@ -0,0 +1,41 @@
+import { List, ListItem, ListItemText } from "@mui/material";
+
+/**
+ * TextList Component
+ * Standardized list component for ordered or unordered lists.
+ *
+ * Props:
+ * - items: Array of strings or objects with { primary, secondary } (required).
+ * - type: "unordered" | "ordered" (default: "unordered").
+ * - dense: Reduces vertical spacing (default: false).
+ */
+export default function PageList({ items = [], type = "unordered", dense = false }) {
+  const isOrdered = type === "ordered";
+
+  if (!items || items.length === 0) return null;
+
+  return (
+    <List
+      dense={dense}
+      sx={{
+        listStyleType: isOrdered ? "decimal" : "disc",
+        pl: 3,
+        "& .MuiListItem-root": {
+          display: "list-item",
+          py: dense ? 0.25 : 0.5,
+        },
+      }}
+    >
+      {items.map((item, index) => {
+        const primary = typeof item === "string" ? item : item.primary;
+        const secondary = typeof item === "string" ? null : item.secondary;
+
+        return (
+          <ListItem key={index}>
+            <ListItemText primary={primary} secondary={secondary} />
+          </ListItem>
+        );
+      })}
+    </List>
+  );
+}

package/src/gui/components/generics/Text/TextParagraph.jsx

@@ -0,0 +1,28 @@
+import { Typography } from "@mui/material";
+
+/**
+ * TextParagraph Component
+ * Standardized paragraph text for pages with consistent spacing and alignment.
+ *
+ * Props:
+ * - children: Text or elements to display as paragraph content.
+ * - align: "left" | "center" | "right" | "justify" (default: "left").
+ * - variant: MUI Typography variant, e.g., "body1" | "body2" | "caption" (default: "body1").
+ * - gutterBottom: Adds bottom spacing (default: true).
+ */
+export default function PageParagraph({
+  children,
+  align = "left",
+  variant = "body1",
+  gutterBottom = true,
+}) {
+  return (
+    <Typography
+      variant={variant}
+      align={align}
+      sx={{ mb: gutterBottom ? 2 : 0 }}
+    >
+      {children}
+    </Typography>
+  );
+}

package/src/gui/components/generics/Text/TextQuote.jsx

@@ -0,0 +1,23 @@
+import { Box, Typography } from "@mui/material";
+import { useTheme } from "@mui/material/styles";
+
+export default function TextQuote({ children }) {
+  const theme = useTheme();
+  const isDark = theme.palette.mode === "dark";
+
+  return (
+    <Box
+      component="blockquote"
+      sx={{
+        borderLeft: `4px solid ${theme.palette.primary.main}`,
+        padding: "1rem 1.5rem",
+        margin: "1.5rem 0",
+        fontStyle: "italic",
+        color: theme.palette.text.secondary,
+        "& p": { margin: 0 },
+      }}
+    >
+      <Typography variant="body1">{children}</Typography>
+    </Box>
+  );
+}

package/src/gui/components/generics/Text/TextTitle.jsx

@@ -0,0 +1,44 @@
+import { Box, Typography, Divider } from "@mui/material";
+
+/**
+ * TextTitle Component
+ * Displays a title (h1-h3) and an optional subtitle/description at the top of the page.
+ * Meant to be used inside PageContainer for consistency across layouts.
+ */
+export default function TextTitle({ title, subtitle, h = 1, variant, showDivider = true }) {
+  const variants = {
+    1: "h1",
+    2: "h2",
+    3: "h3",
+    4: "h4",
+    5: "h5",
+    6: "h6",
+  };
+
+  const level = Math.min(Math.max(h, 1), 6);
+  const typographyVariant = variant || variants[level];
+  return (
+    <Box sx={{ width: "100%", mb: 3 }}>
+      <Typography
+        variant={typographyVariant}
+        component={`h${level}`}
+        sx={{
+          fontWeight: 600,
+          mb: subtitle ? 0.5 : 2,
+        }}
+      >
+        {title}
+      </Typography>
+      {subtitle && (
+        <Typography
+          variant="subtitle1"
+          color="text.secondary"
+          sx={{ mb: 1.5 }}
+        >
+          {subtitle}
+        </Typography>
+      )}
+      {showDivider && <Divider />}
+    </Box>
+  );
+}

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

@@ -0,0 +1,18 @@
+import Dialog from './Dialog';
+
+export default {
+  title: 'Molecules/Dialog/Dialog',
+  component: Dialog,
+};
+
+export const Basic = () => (
+  <Dialog>
+    This is the basic Dialog with default padding.
+  </Dialog>
+);
+
+export const WithCustomPadding = () => (
+  <Dialog  sx={{ p: 4, bgcolor: 'background.default' }}>
+    This Dialog has custom padding and background color.
+  </Dialog>
+);

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

@@ -0,0 +1,5 @@
+import MuiDialogContent, { DialogContentProps as MuiDialogContentProps } from '@mui/material/DialogContent';
+export type DialogProps = MuiDialogContentProps;
+export default function DialogContent(props: DialogProps) {
+  return <MuiDialogContent {...props} sx={{ p: 2, bgcolor: 'background.paper', ...props.sx }} />;
+}

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

@@ -0,0 +1,140 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Hero } from './Hero';
+
+const meta: Meta<typeof Hero> = {
+  title: 'Molecules/Display/Hero',
+  component: Hero,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ height: '100vh', overflow: 'hidden' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**HeroSection** is a full-screen display component that supports image, GIF, or video backgrounds with overlay and blur options.
+
+---
+## Features
+- Background types: \`image\`, \`gif\`, \`video\`.
+- Overlay color and opacity control.
+- Theme-aware blur effects: \`light\`, \`medium\`, \`heavy\`, \`all\`.
+- Fully responsive and fills viewport (100vh).
+
+---
+## Props
+- \`backgroundSrc\`: Media URL (image, gif, or video).
+- \`backgroundType\`: Type of background media ('image', 'gif', or 'video').
+- \`overlayOpacity\`: Opacity of overlay (0–1).
+- \`overlayColor\`: Color of overlay.
+- \`blur\`: Theme-based blur intensity (\`light\`, \`medium\`, \`heavy\`, \`all\`).
+        `,
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof Hero>;
+
+export const ImageBackground: Story = {
+  args: {
+    backgroundSrc: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e',
+    backgroundType: 'image',
+    blur: 'none',
+    children: (
+      <div style={{ color: 'white', fontSize: '2rem', fontWeight: 600, textAlign: 'center', marginTop: '40vh' }}>
+        Example: Image Background, Blur none
+      </div>
+    ),
+  },
+};
+
+export const GifBackground: Story = {
+  args: {
+    backgroundSrc: 'https://media.giphy.com/media/l0MYt5jPR6QX5pnqM/giphy.gif',
+    backgroundType: 'gif',
+    blur: 'light',
+    children: (
+      <div style={{ color: 'white', fontSize: '2rem', fontWeight: 600, textAlign: 'center', marginTop: '40vh' }}>
+        Example: GIF Background, Blur light
+      </div>
+    ),
+  },
+};
+
+export const VideoBackground: Story = {
+  args: {
+    backgroundSrc: 'https://www.neurons.me/media/neurons.mp4',
+    backgroundType: 'video',
+    blur: 'medium',
+    children: (
+      <div style={{ color: 'white', fontSize: '2rem', fontWeight: 600, textAlign: 'center', marginTop: '40vh' }}>
+        Example: Video Background, Blur medium
+      </div>
+    ),
+  },
+};
+
+export const HeavyExample: Story = {
+  args: {
+    backgroundSrc: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e',
+    backgroundType: 'image',
+    blur: 'heavy',
+    children: (
+      <div
+        style={{
+          color: 'white',
+          fontSize: '2rem',
+          fontWeight: 600,
+          textAlign: 'center',
+          marginTop: '40vh',
+        }}
+      >
+        Example: Heavy blur overlay (theme preset)
+      </div>
+    ),
+  },
+};
+
+export const BlurVariants: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 1fr)', gap: 16 }}>
+      {(['none', 'light', 'medium', 'heavy', 'all'] as const).map((b) => (
+        <Hero
+          key={b}
+          backgroundSrc="https://images.unsplash.com/photo-1507525428034-b723cf961d3e"
+          backgroundType="image"
+          blur={b}
+          children={
+            <div style={{ color: 'white', fontSize: '1.5rem', fontWeight: 600, textAlign: 'center', marginTop: '40vh' }}>
+              Blur = {b}
+            </div>
+          }
+        />
+      ))}
+    </div>
+  ),
+};
+
+export const CustomColorExample: Story = {
+  args: {
+    backgroundSrc: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e',
+    backgroundType: 'image',
+    overlayColor: 'rgba(15, 21, 37, 0.89)', // Semi-transparent dark overlay
+    children: (
+      <div style={{
+        color: 'white',
+        fontSize: '2rem',
+        fontWeight: 600,
+        textAlign: 'center',
+        marginTop: '40vh',
+      }}>
+        Example: Custom Color Overlay
+      </div>
+    ),
+  },
+};

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

@@ -0,0 +1,152 @@
+import React from 'react';
+import { Box, useTheme } from '@mui/material';
+import type { HeroProps } from './Hero.types';
+
+function resolveBlurRadius(theme: any, blur?: 'none'|'light'|'medium'|'heavy'|'all'): string {
+  if (!blur || blur === 'none') return '0px';
+  const fromTheme = theme?.custom?.blurRadius?.[blur];
+  return fromTheme ?? '0px';
+}
+
+function resolveOverlayColor(
+  theme: any,
+  blur?: 'none' | 'light' | 'medium' | 'heavy' | 'all',
+  customColor?: string,
+  overlayColor?: string
+): string {
+  const paletteBlur = blur ? theme?.palette?.blur?.[blur] : undefined;
+
+  const resolved =
+    customColor
+      ? customColor
+      : paletteBlur?.$value
+      ? paletteBlur.$value
+      : typeof paletteBlur === 'string'
+      ? paletteBlur
+      : overlayColor || 'transparent';
+
+  console.log('resolveOverlayColor inputs:', { blur, customColor, overlayColor, paletteBlur });
+  console.log('resolveOverlayColor resolved:', resolved);
+
+  return resolved;
+}
+
+function resolveMediaFilter(blurRadius: string, blur?: 'none'|'light'|'medium'|'heavy'|'all'): string | undefined {
+  if (!blur || blur === 'none') return 'none';
+  return blur === 'all' ? 'saturate(1.05) brightness(0.96)' : 'none';
+}
+
+export const Hero: React.FC<HeroProps> = ({
+  backgroundSrc,
+  backgroundType = 'image',
+  overlayColor,
+  children,
+  height = '100vh',
+  padding = 4,
+  blur,
+  customColor,
+}) => {
+  const theme = useTheme();
+
+  //console.log('theme.palette.blur:', theme.palette.blur);
+  //console.log('theme.custom.blurRadius:', theme.custom.blurRadius);
+  //console.log(theme.palette.blur);
+  const blurRadius = resolveBlurRadius(theme, blur);
+  const overlayBg  = resolveOverlayColor(theme, blur, customColor, overlayColor);
+  const mediaFilter = resolveMediaFilter(blurRadius, blur);
+
+  return (
+    <Box
+      component="section"
+      sx={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: '100vw',
+        height,
+        margin: 0,
+        padding: 0,
+        overflow: 'hidden',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        boxSizing: 'border-box',
+        zIndex: 0,
+        backgroundColor: 'transparent',
+      }}
+    >
+      {backgroundSrc && (
+        <>
+          {backgroundType === 'video' ? (
+            <Box
+              component="video"
+              src={backgroundSrc}
+              autoPlay
+              muted
+              loop
+              playsInline
+              sx={{
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                height: '100%',
+                objectFit: 'cover',
+                zIndex: 0,
+                filter: mediaFilter,
+                willChange: 'transform, filter',
+                transform: 'translateZ(0)',
+              }}
+            />
+          ) : (
+            <Box
+              component="img"
+              src={backgroundSrc}
+              alt=""
+              sx={{
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                height: '100%',
+                objectFit: 'cover',
+                zIndex: 0,
+                filter: mediaFilter,
+                willChange: 'transform, filter',
+                transform: 'translateZ(0)',
+              }}
+            />
+          )}
+
+          {/* Overlay Layer */}
+          <Box
+            sx={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              height: '100%',
+              backgroundColor: overlayBg,
+              // backdropFilter: blur ? `blur(${blurRadius})` : undefined,
+              // WebkitBackdropFilter: blur ? `blur(${blurRadius})` : undefined,
+              zIndex: 2,
+              transition: 'opacity 0.4s ease',
+            }}
+          />
+        </>
+      )}
+
+      <Box
+        sx={{
+          position: 'relative',
+          zIndex: 3,
+          textAlign: 'center',
+          color: 'text.primary',
+          px: padding,
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+};

package/src/gui/components/molecules/Hero/Hero.types.tsx

@@ -0,0 +1,18 @@
+export interface HeroProps {
+  /** Imagen, video o GIF de fondo */
+  backgroundSrc?: string;
+  /** Tipo de medio: 'image' | 'video' | 'gif' */
+  backgroundType?: 'image' | 'video' | 'gif';
+  /** Color del overlay (default: theme.palette.background.default) */
+  overlayColor?: string;
+  /** Contenido principal (texto, botones, etc.) */
+  children?: React.ReactNode;
+  /** Altura opcional (por defecto: 100vh) */
+  height?: string | number;
+  /** Padding interno (por defecto: responsive según theme.spacing) */
+  padding?: number | string;
+  /** Nivel de desenfoque: 'none' | 'light' | 'medium' | 'heavy' | 'all' */
+  blur?: 'none' | 'light' | 'medium' | 'heavy' | 'all';
+  /** Color personalizado del overlay (anula overlayColor si se define) */
+  customColor?: string;
+}

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

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import type { RegistryEntry } from '@/gui/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import Modal from './Modal';
+import type { ModalProps } from './Modal.types';
+
+/**
+ * ModalBoxResolver
+ * - Declaratively maps a JSON-friendly spec to <ModalBox /> props.
+ * - Supports declarative 3D position via xyz prop.
+ * - Keeps it registry-compatible for GUI schema systems.
+ */
+const ModalResolver: RegistryEntry = {
+  type: 'ModalBox',
+  resolve(spec: any) {
+    const p: ModalProps = spec.props ?? {};
+    const rootProps: any = {
+      open: p.open ?? false,
+      title: p.title ?? '',
+      onClose: p.onClose ?? (() => {}),
+      width: p.width ?? 'auto',
+      height: p.height ?? 'auto',
+      blurBackground: p.blurBackground ?? true,
+      xyz: p.xyz,
+      id: ensureNodeId('modalbox', p.id),
+      className: p.className,
+      'data-testid': p['data-testid'],
+    };
+
+    return (
+      <ModalBox {...rootProps}>
+        {p.children}
+      </ModalBox>
+    );
+  },
+};
+
+export default ModalResolver;

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

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import React, { useState } from "react";
+import ModalBox from "./Modal";
+import { Button } from "@mui/material";
+
+const meta: Meta<typeof ModalBox> = {
+  title: "Molecules/Display/ModalBox",
+  component: ModalBox,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div style={{ height: "100vh", overflow: "hidden" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**ModalBox** is a flexible, theme-aware modal container with optional background blur and 3D placement support via \`xyz\` props.
+
+---
+## Features
+- Supports background blur overlay for visual depth.
+- Centered responsive layout with dynamic width and height.
+- Declarative 3D placement via \`xyz: [x, y, z]\`.
+- Works with any child components (forms, dialogs, previews, etc.).
+- Compatible with GUI registry and schema resolvers.
+
+---
+## Props
+- \`open\`: Boolean that controls visibility.
+- \`title\`: Optional modal header title.
+- \`onClose\`: Function triggered when closing.
+- \`width\`, \`height\`: Custom modal dimensions.
+- \`blurBackground\`: Enables or disables background blur.
+- \`xyz\`: 3D position array for spatial positioning.
+- \`children\`: Modal content.
+        `,
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof ModalBox>;
+
+export const Default: Story = {
+  render: (args) => {
+    const [open, setOpen] = useState(true); // force open for debugging
+    console.log("ModalBox render", { open, args });
+
+    return (
+      <div
+        style={{
+          position: "relative",
+          height: "100vh",
+          background: "rgba(0,0,0,0.2)",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        <ModalBox
+          {...args}
+          open={open}
+          onClose={() => setOpen(false)}
+          title={args.title || "Modal Title"}
+        >
+          <p style={{ color: "#fff" }}>This is an example modal content.</p>
+          <p style={{ color: "#ccc" }}>If you see this text, the modal is visible.</p>
+        </ModalBox>
+      </div>
+    );
+  },
+  args: {
+    title: "Example Modal",
+    blurBackground: true,
+    width: 400,
+    height: "auto",
+  },
+};