this.gui 1.3.24 → 1.3.26

package/src/gui/components/atoms/Typography/Typography.stories.tsx

@@ -0,0 +1,222 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Typography from './Typography';
+import Link from '../Link/Link';
+
+const meta = {
+  title: 'Atoms/Content/Typography',
+  component: Typography,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 24 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Typography** is a thin, polymorphic wrapper around MUI's Typography that keeps the full API
+while exposing it through This.GUI. Import it from **@/gui/primitives** instead of @mui/material so
+you can swap render engines in the future without breaking consumers.
+
+### Key points
+- Preserves MUI's polymorphism (\`component\`, \`as\`, \`variantMapping\`).
+- Works with routers and anchors: \`component={Link}\` + \`to\`, or \`component="a"\` + \`href\`.
+- Styled by your This.GUI theme (typography, palette, spacing).
+
+### Common variants
+MUI variants like \`h1..h6\`, \`subtitle1/2\`, \`body1/2\`, \`caption\`, \`overline\` are supported.
+
+### Declarative JSON example
+You can describe text nodes in JSON and hydrate them in a renderer:
+
+~~~json
+{
+  "type": "Typography",
+  "props": {
+    "variant": "h4",
+    "component": "h2",
+    "gutterBottom": true
+  },
+  "children": "Section Title"
+}
+~~~
+
+A naive hydration would look like:
+
+~~~tsx
+const spec = {
+  type: 'Typography',
+  props: { variant: 'h4', component: 'h2', gutterBottom: true },
+  children: 'Section Title'
+};
+
+<Typography {...spec.props}>{spec.children}</Typography>
+~~~
+        `,
+      },
+    },
+    controls: { exclude: ['component', 'to', 'href', 'variantMapping', 'ref'] },
+  },
+} satisfies Meta<typeof Typography>;
+
+export default meta;
+
+type Story = StoryObj<typeof Typography>;
+
+export const Basic: Story = {
+  args: {
+    variant: 'body1',
+    children: 'Hello from Typography',
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography variant="h1">h1. Heading</Typography>
+      <Typography variant="h2">h2. Heading</Typography>
+      <Typography variant="h3">h3. Heading</Typography>
+      <Typography variant="h4">h4. Heading</Typography>
+      <Typography variant="h5">h5. Heading</Typography>
+      <Typography variant="h6">h6. Heading</Typography>
+      <Typography variant="subtitle1">subtitle1</Typography>
+      <Typography variant="subtitle2">subtitle2</Typography>
+      <Typography variant="body1">body1</Typography>
+      <Typography variant="body2">body2</Typography>
+      <Typography variant="caption">caption</Typography>
+      <Typography variant="overline">overline</Typography>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Preview of common Material UI typography variants.'
+      }
+    }
+  }
+};
+
+export const AsPropAndGutter: Story = {
+  name: 'Semantic element (component) + gutter',
+  render: () => (
+    <div>
+      <Typography variant="h4" component="h2" gutterBottom>
+        Section title (rendered as h2)
+      </Typography>
+      <Typography variant="body1">
+        Body text below the title. The \`gutterBottom\` on the title adds spacing.
+      </Typography>
+    </div>
+  ),
+};
+
+export const Alignment: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography align="left">Left aligned</Typography>
+      <Typography align="center">Center aligned</Typography>
+      <Typography align="right">Right aligned</Typography>
+    </div>
+  ),
+};
+
+export const Colors: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography color="text.primary">text.primary</Typography>
+      <Typography color="text.secondary">text.secondary</Typography>
+      <Typography color="primary">primary</Typography>
+      <Typography color="#00aa96">#00aa96 (custom)</Typography>
+    </div>
+  ),
+};
+
+export const WithRouterAndAnchor: Story = {
+  name: 'Routing & anchors',
+  render: () => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      {/* Router link (uses This.GUI Link under the hood) */}
+      <Typography component={Link as any} to="/docs" underline="none">
+        Go to /docs (Router link)
+      </Typography>
+
+      {/* External anchor */}
+      <Typography component="a" href="https://neurons.me" target="_blank" rel="noopener noreferrer">
+        Visit neurons.me (anchor)
+      </Typography>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates polymorphism: render as router link (with `to`) and as anchor (with `href`).'
+      }
+    }
+  }
+};
+
+export const VariantMappingOverride: Story = {
+  name: 'variantMapping override',
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography
+        variant="subtitle1"
+        variantMapping={{ subtitle1: 'h3', body1: 'p' }}
+      >
+        subtitle1 text rendered as an H3 element via variantMapping
+      </Typography>
+      <Typography
+        variant="body1"
+        variantMapping={{ subtitle1: 'h3', body1: 'p' }}
+      >
+        body1 text rendered as a P element via variantMapping
+      </Typography>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'MUI Typography allows remapping variants to different HTML elements without changing visual style.'
+      }
+    }
+  }
+};
+
+export const DeclarativeSpec: Story = {
+  name: 'Declarative (JSON → Typography)',
+  render: () => {
+    const spec = {
+      type: 'Typography',
+      props: { variant: 'h5', component: 'h3', gutterBottom: true },
+      children: 'Declaratively rendered title',
+    } as const;
+
+    return (
+      <div style={{ display: 'grid', gap: 12 }}>
+        <pre style={{ background: 'rgba(127,127,127,0.08)', padding: 12, borderRadius: 8 }}>
+{`{
+  "type": "Typography",
+  "props": {
+    "variant": "h5",
+    "component": "h3",
+    "gutterBottom": true
+  },
+  "children": "Declaratively rendered title"
+}`}
+        </pre>
+        {/* naive renderer */}
+        <Typography {...spec.props}>{spec.children}</Typography>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example of hydrating a Typography node from a JSON spec. In production, your app would use a central registry/renderer.'
+      }
+    }
+  }
+};

package/src/gui/components/atoms/Typography/Typography.tsx

@@ -0,0 +1,27 @@
+/*
+ * This.GUI — Typography (polymorphic)
+ * Thin wrapper over MUI's Typography that preserves its full polymorphic API:
+ * - `component` / `as` (MUI OverridableComponent)
+ * - `variantMapping`
+ * - works with router links (`component={Link}`) or anchors (`component="a"`)
+ *
+ * Import from "@/gui/atoms" instead of "@mui/material" so we can change
+ * the underlying engine without breaking consumers.
+ */
+import * as React from 'react';
+import MuiTypography from '@mui/material/Typography';
+import type { OverridableComponent } from '@mui/material/OverridableComponent';
+import type { TypographyTypeMap } from '@mui/material/Typography';
+// Public prop type (mirrors MUI's polymorphic typing)
+export type TypographyProps = React.ComponentProps<
+  OverridableComponent<TypographyTypeMap<{}, 'span'>>
+>;
+// Component: preserve MUI OverridableComponent so `component` works as in MUI
+const Typography = MuiTypography as unknown as OverridableComponent<
+  TypographyTypeMap<{}, 'span'>
+>;
+// DevTools label
+(Typography as any).displayName = 'Gui.Typography';
+// Helpful alias for consumers who prefer a prefixed name
+export type GuiTypographyProps = TypographyProps;
+export default Typography;

package/src/gui/components/atoms.tsx

@@ -0,0 +1,138 @@
+/* 
+ * This.GUI — primitives
+ * Thin wrappers around MUI components to present a stable, library-owned API.
+ * Internally we use MUI, but components in the design system should import from
+ * "@/gui/primitives" instead of "@mui/material". This lets us swap engines later.
+ * 
+ * La regla estándar en tu wrapper
+ *   • Si MUI lo declaró polimórfico → usa OverridableComponent en tu wrapper.
+ *   • Si no lo es → usa forwardRef normal.
+ *
+ * Así garantizas dos cosas:
+ * ✅ Tu wrapper no pierde nada de lo que MUI ofrece.
+ * ✅ No te complicas agregando polimorfismo donde MUI no lo soporta.
+ */
+import * as React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+// AppBar is not polymorphic so we wrap it with forwardRef
+import AppBar from './atoms/AppBar/AppBar';
+export { default as AppBar } from './atoms/AppBar/AppBar';
+// Box is polymorphic so we re-export it directly
+import Box, { type BoxProps } from './atoms/Box/Box';
+export { default as Box } from './atoms/Box/Box';
+export type { BoxProps } from './atoms/Box/Box';
+// Avatar is not polymorphic so we wrap it with forwardRef
+import Avatar, { type AvatarProps } from './atoms/Avatar/Avatar';
+export { default as Avatar } from './atoms/Avatar/Avatar';
+export type { AvatarProps } from './atoms/Avatar/Avatar';
+//Button is polymorphic so we re-export it directly
+import Button from './atoms/Button/Button';
+export { default as Button } from './atoms/Button/Button';
+export type { GuiButtonProps as ButtonProps } from './atoms/Button/Button';
+//Collapse is not polymorphic so we wrap it with forwardRef
+import Collapse, { type CollapseProps } from './atoms/Collapse/Collapse';
+export { default as Collapse } from './atoms/Collapse/Collapse';
+export type { CollapseProps } from './atoms/Collapse/Collapse';
+//IconButton is polymorphic so we re-export it directly
+import IconButton, { type IconButtonProps } from './atoms/IconButton/IconButton';
+export { default as IconButton } from './atoms/IconButton/IconButton';
+export type { IconButtonProps } from './atoms/IconButton/IconButton';
+//Divider is not polymorphic so we wrap it with forwardRef
+import Divider, { type DividerProps } from './atoms/Divider/Divider';
+export { default as Divider } from './atoms/Divider/Divider';
+export type { DividerProps } from './atoms/Divider/Divider';
+//Drawer is not polymorphic so we wrap it with forwardRef
+import Drawer, { type DrawerProps } from './atoms/Drawer/Drawer';
+export { default as Drawer } from './atoms/Drawer/Drawer';
+export type { DrawerProps } from './atoms/Drawer/Drawer';
+//Link is polymorphic so we re-export it directly
+import Link from './atoms/Link/Link';
+export { default as Link } from './atoms/Link/Link';
+export type { LinkProps } from './atoms/Link/Link';
+// List and related are not polymorphic so we wrap them with forwardRef
+import List, { type ListProps } from './atoms/List/List';
+export { default as List } from './atoms/List/List';
+export type { ListProps } from './atoms/List/List';
+import ListItem, { type ListItemProps } from './atoms/ListItem/ListItem';
+export { default as ListItem } from './atoms/ListItem/ListItem';
+export type { ListItemProps } from './atoms/ListItem/ListItem';
+import ListItemButton, { type ListItemButtonProps } from './atoms/ListItemButton/ListItemButton';
+export { default as ListItemButton } from './atoms/ListItemButton/ListItemButton';
+export type { ListItemButtonProps } from './atoms/ListItemButton/ListItemButton';
+import ListItemIcon, { type ListItemIconProps } from './atoms/ListItemIcon/ListItemIcon';
+export { default as ListItemIcon } from './atoms/ListItemIcon/ListItemIcon';
+export type { ListItemIconProps } from './atoms/ListItemIcon/ListItemIcon';
+import ListItemText, { type ListItemTextProps } from './atoms/ListItemText/ListItemText';
+export { default as ListItemText } from './atoms/ListItemText/ListItemText';
+export type { ListItemTextProps } from './atoms/ListItemText/ListItemText';
+//Menu and related are polymorphic so we re-export them directly
+import Menu, { type MenuProps } from './atoms/Menu/Menu';
+export { default as Menu } from './atoms/Menu/Menu';
+export type { MenuProps } from './atoms/Menu/Menu';
+import MenuItem, { type MenuItemProps } from './atoms/MenuItem/MenuItem';
+export { default as MenuItem } from './atoms/MenuItem/MenuItem';
+export type { MenuItemProps } from './atoms/MenuItem/MenuItem';
+//Paper is not polymorphic so we wrap it with forwardRef
+import Paper, { type PaperProps } from './atoms/Paper/Paper';
+export { default as Paper } from './atoms/Paper/Paper';
+export type { PaperProps } from './atoms/Paper/Paper';
+//Stack is not polymorphic so we wrap it with forwardRef
+import Stack, { type StackProps } from './atoms/Stack/Stack';
+export { default as Stack } from './atoms/Stack/Stack';
+export type { StackProps } from './atoms/Stack/Stack';
+//Switch is not polymorphic so we wrap it with forwardRef
+import Switch, { type SwitchProps } from './atoms/Switch/Switch';
+export { default as Switch } from './atoms/Switch/Switch';
+export type { SwitchProps } from './atoms/Switch/Switch';
+//Toolbar is not polymorphic so we wrap it with forwardRef
+import Toolbar from './atoms/Toolbar/Toolbar';
+export { default as Toolbar } from './atoms/Toolbar/Toolbar';
+export type { ToolbarProps } from './atoms/Toolbar/Toolbar';
+//Tooltip is not polymorphic so we wrap it with forwardRef
+import Tooltip from './atoms/Tooltip/Tooltip';
+export { default as Tooltip } from './atoms/Tooltip/Tooltip';
+export type { TooltipProps } from './atoms/Tooltip/Tooltip';
+//Typography is polymorphic so we re-export it directly
+import Typography, { type TypographyProps } from './atoms/Typography/Typography';
+export { default as Typography } from './atoms/Typography/Typography';
+export type { TypographyProps } from './atoms/Typography/Typography';
+import Section from './atoms/Section/Section';
+export { default as Section } from './atoms/Section/Section';
+export type { SectionProps } from './atoms/Section/Section.types';
+
+/* -------------------------------------------------------------------------------------------------
+ * GuiSx — re-export of MUI’s SxProps<Theme>
+ * -------------------------------------------------------------------------------------------------*/
+
+/** Public sx type (kept for now to ease migration). */
+export type GuiSx = SxProps<Theme>;
+
+/* -------------------------------------------------------------------------------------------------
+ * Named bundle export (optional ergonomic import)
+ * -------------------------------------------------------------------------------------------------*/
+export const Atoms = {
+  Box,
+  Typography,
+  Link,
+  Stack,
+  Divider,
+  AppBar,
+  Toolbar,
+  IconButton,
+  Menu,
+  MenuItem,
+  Drawer,
+  List,
+  ListItem,
+  ListItemButton,
+  ListItemIcon,
+  ListItemText,
+  Collapse,
+  Button,
+  Tooltip,
+  Switch,
+  Paper,
+  Avatar,
+  Section,
+} as const;
+export default Atoms;

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/HeroSection/HeroSection.stories.tsx

@@ -0,0 +1,141 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { HeroSection } from './HeroSection';
+
+const meta: Meta<typeof HeroSection> = {
+  title: 'Molecules/Display/HeroSection',
+  component: HeroSection,
+  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 HeroSection>;
+
+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) => (
+        <HeroSection
+          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>
+    ),
+  },
+};