this.gui 1.3.22 → 1.3.26

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

@@ -0,0 +1,263 @@
+// src/gui/atoms/Box/Box.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Link, Typography, Button } from '@/gui/components/atoms';
+// ======================= Meta =======================
+const meta: Meta<typeof Box> = {
+  title: 'Atoms/Containers/Box',
+  component: Box,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Box** is a thin wrapper around MUI's \`Box\` that preserves **polymorphism** and integrates with **This.GUI** theming.
+Use it as your default layout primitive: spacing, flex/grid, backgrounds, borders, etc.
+
+---
+## Features
+- **Polymorphic**: \`component\` (or \`as\`) can be an element tag (e.g. \`'section'\`, \`'img'\`, \`'a'\`) or a component (e.g. This.GUI \`Link\`).
+- **Routing-friendly**: when using \`component={Link}\` you can pass \`to\`; anchors use \`href\`.
+- **System props** & **sx**: use MUI system (p, m, display, gap, flex, grid, etc.) and the \`sx\` prop for deep styling.
+- **Image mode**: if \`component="img"\`, you can pass \`src\`, \`alt\`, \`width\`, \`height\`, \`loading\`, \`decoding\`, \`referrerPolicy\`, \`sizes\`, \`srcSet\`.
+
+---
+## Key Props
+- \`component?: ElementType | string\` / \`as?: ElementType | string\`
+- \`to?: string\` (when \`component={Link}\`)
+- \`href?: string\` (when \`component="a"\`)
+- \`sx?: SxProps\` + all MUI system props (e.g. \`p\`, \`m\`, \`display\`, \`gap\`)
+- **Image-only extras** (when \`component="img"\`): \`src\`, \`alt\`, \`width\`, \`height\`, \`loading\`, \`decoding\`, \`referrerPolicy\`, \`sizes\`, \`srcSet\`.
+
+> We don't expose \`component\`, \`to\`, \`href\` as Storybook controls—see the dedicated stories below.
+
+---
+## Basic usage
+~~~jsx
+import { Box } from '@/gui/atoms';
+
+<Box p={2} sx={{ border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+  Content
+</Box>
+~~~
+
+## Polymorphic (as a section)
+~~~jsx
+<Box component="section" p={2}>Section content</Box>
+~~~
+
+## Router link target
+~~~jsx
+import { Box, Link } from '@/gui/atoms';
+
+<Box component={Link} to="/docs" p={1} sx={{ display: 'inline-block' }}>
+  Go to docs
+</Box>
+~~~
+
+## Image mode
+~~~jsx
+<Box component="img" src="/logo.png" alt="Logo" sx={{ width: 120, height: 'auto' }} />
+~~~
+
+## Declarative JSON / Config usage
+~~~json
+{
+  "type": "Box",
+  "props": {
+    "component": "section",
+    "p": 2,
+    "sx": { "border": "1px solid", "borderColor": "divider", "borderRadius": 8 },
+    "children": "Section content"
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'as', 'to', 'href', 'sx'],
+    },
+  },
+  argTypes: {
+    // System props examples (you can add more if useful)
+    p: { control: { type: 'number' }, description: 'Padding (system prop)' },
+    m: { control: { type: 'number' }, description: 'Margin (system prop)' },
+    display: {
+      control: { type: 'select' },
+      options: ['block', 'inline-block', 'flex', 'grid', 'inline-flex', 'inline', 'none'],
+    },
+    gap: { control: { type: 'number' } },
+  },
+  args: {
+    p: 2,
+    display: 'block',
+    children: 'Box content',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Box>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const LayoutBasics: Story = {
+  name: 'Layout basics (spacing, border, radius)',
+  render: (args) => (
+    <Box
+      {...args}
+      sx={{
+        border: '1px solid',
+        borderColor: 'divider',
+        borderRadius: 2,
+        bgcolor: 'background.paper',
+      }}
+    />
+  ),
+};
+
+export const FlexRow: Story = {
+  args: {},
+  render: () => (
+    <Box display="flex" gap={2}>
+      <Box p={1} sx={{ border: '1px dashed', borderColor: 'divider' }}>A</Box>
+      <Box p={1} sx={{ border: '1px dashed', borderColor: 'divider' }}>B</Box>
+      <Box p={1} sx={{ border: '1px dashed', borderColor: 'divider' }}>C</Box>
+    </Box>
+  ),
+};
+
+export const GridLayout: Story = {
+  render: () => (
+    <Box display="grid" sx={{ gridTemplateColumns: 'repeat(3, 1fr)', gap: 2 }}>
+      {Array.from({ length: 6 }).map((_, i) => (
+        <Box key={i} p={2} sx={{ border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+          Cell {i + 1}
+        </Box>
+      ))}
+    </Box>
+  ),
+};
+
+export const AsSection: Story = {
+  name: 'Polymorphic: section',
+  render: () => (
+    <Box component="section" p={2} sx={{ borderLeft: '4px solid', borderColor: 'primary.main' }}>
+      <Typography variant="h6">Section title</Typography>
+      <Typography variant="body2" sx={{ opacity: 0.8 }}>
+        Section content goes here.
+      </Typography>
+    </Box>
+  ),
+};
+
+export const AsAnchor: Story = {
+  name: 'Polymorphic: anchor (href)',
+  render: () => (
+    <Box
+      component="a"
+      href="https://neurons.me"
+      target="_blank"
+      rel="noreferrer"
+      p={1}
+      sx={{
+        display: 'inline-block',
+        border: '1px solid',
+        borderColor: 'divider',
+        borderRadius: 1,
+        '&:hover': { textDecoration: 'none', bgcolor: 'action.hover' },
+      }}
+    >
+      Visit neurons.me
+    </Box>
+  ),
+};
+
+export const AsRouterLink: Story = {
+  name: 'Polymorphic: Link (to)',
+  render: () => (
+    <Box
+      component={Link}
+      to="/docs"
+      p={1}
+      sx={{
+        display: 'inline-block',
+        border: '1px solid',
+        borderColor: 'divider',
+        borderRadius: 1,
+        '&:hover': { textDecoration: 'none', bgcolor: 'action.hover' },
+      }}
+    >
+      Go to docs
+    </Box>
+  ),
+};
+
+export const ImageMode: Story = {
+  name: 'Image mode (component="img")',
+  render: () => (
+    <Box
+      component="img"
+      src="https://placekitten.com/320/160"
+      alt="Kitten"
+      sx={{ width: 320, height: 'auto', borderRadius: 1, border: '1px solid', borderColor: 'divider' }}
+      loading="lazy"
+      decoding="async"
+    />
+  ),
+};
+
+export const NestedComposition: Story = {
+  render: () => (
+    <Box p={2} sx={{ border: '1px solid', borderColor: 'divider', borderRadius: 1 }}>
+      <Typography variant="subtitle1" sx={{ mb: 1 }}>Nested composition</Typography>
+      <Box display="flex" gap={1}>
+        <Button variant="contained" color="primary">Action</Button>
+        <Box component={Link} to="/docs" sx={{ alignSelf: 'center' }}>
+          Learn more
+        </Box>
+      </Box>
+    </Box>
+  ),
+};
+
+export const SXDeepStyling: Story = {
+  name: 'Deep styling with sx',
+  render: () => (
+    <Box
+      p={2}
+      sx={{
+        borderRadius: 2,
+        bgcolor: 'background.paper',
+        border: '1px solid',
+        borderColor: 'divider',
+        '& .demo-title': {
+          fontWeight: 700,
+          color: 'text.primary',
+          mb: 1,
+        },
+        '& .demo-card': {
+          p: 1.5,
+          border: '1px solid',
+          borderColor: 'divider',
+          borderRadius: 1,
+          '&:hover': { bgcolor: 'action.hover' },
+        },
+      }}
+    >
+      <Typography className="demo-title">Cards</Typography>
+      <Box display="grid" sx={{ gridTemplateColumns: 'repeat(3, 1fr)', gap: 1.5 }}>
+        <Box className="demo-card">One</Box>
+        <Box className="demo-card">Two</Box>
+        <Box className="demo-card">Three</Box>
+      </Box>
+    </Box>
+  ),
+};

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

@@ -0,0 +1,15 @@
+// src/gui/atoms/Box/Box.tsx
+/*
+ * This.GUI — Box (polymorphic)
+ * Wrapper that keeps MUI's own typing, including the `component` prop.
+ * Ejemplos válidos:
+ *   <Box component="img" src="..." alt="..." />
+ *   <Box component="a" href="..." />
+ */
+import MuiBox from '@mui/material/Box';
+import * as React from 'react';
+// Re-export using MUI's own component type
+const Box = MuiBox;
+export type BoxProps = React.ComponentProps<typeof Box>;
+(Box as any).displayName = 'Gui.Box';
+export default Box;

package/src/gui/components/atoms/Button/Button.resolver.tsx

@@ -0,0 +1,103 @@
+// src/gui/primitives/Button/Button.resolver.tsx
+import * as React from 'react';
+import Button from './Button';
+import Icon from '@/gui/Theme/Icon/Icon';
+import Link from '../Link/Link';
+import type { RegistryEntry } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+/**
+ * Declarative spec for Button.
+ * This is the JSON-friendly shape your renderer/LLM can emit.
+ */
+type ButtonSpec = {
+  type: 'Button';
+  props?: {
+    // Content
+    label?: string;                  // convenience for children text
+    children?: React.ReactNode;      // optional explicit children
+    // Visual
+    variant?: 'text' | 'outlined' | 'contained';
+    color?: 'inherit' | 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error';
+    size?: 'small' | 'medium' | 'large';
+    startIcon?: React.ReactNode | string;
+    endIcon?: React.ReactNode | string;
+    sx?: SxProps<Theme>;
+    disabled?: boolean;
+    fullWidth?: boolean;
+    // Routing / polymorphism
+    external?: boolean | 'true' | 1;              // if true → anchor + target/rel
+    href?: string;                   // for anchors
+    to?: string;                     // for routers
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    component?: React.ElementType | string;                 // override polymorphic target (e.g., your Link)
+    as?: React.ElementType | string;
+    type?: 'button' | 'submit' | 'reset';
+    // You can extend with data-* attributes, id, className, etc.
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+    [key: string]: any;
+  };
+};
+
+/**
+ * ButtonResolver
+ * - Maps JSON-friendly spec → real <Button /> props.
+ * - Keeps MUI polymorphism intact. If `to` is provided and no `component`,
+ *   it defaults to your primitives Link; if `external` is true, it uses an anchor safely.
+ */
+const ButtonResolver: RegistryEntry = {
+  type: 'Button',
+  resolve(spec: ButtonSpec) {
+    const p = spec.props ?? {};
+    // Decide component priority
+    const isExternal = p.external === true || p.external === 'true' || p.external === 1;
+    let component: React.ElementType | string | undefined =
+      p.component ?? p.as ?? (p.to ? Link : (p.href || isExternal) ? 'a' : undefined);
+
+    const routingProps: Record<string, any> = {};
+    if (component === Link && p.to) {
+      routingProps.to = p.to;
+    } else if (component === 'a') {
+      routingProps.href = p.href;
+      if (isExternal) {
+        routingProps.target = p.target ?? '_blank';
+        routingProps.rel = p.rel ?? 'noopener noreferrer';
+      } else {
+        if (p.target) routingProps.target = p.target;
+        if (p.rel) routingProps.rel = p.rel;
+      }
+    }
+
+    // Children precedence: explicit children > label > fallback
+    const children = p.children ?? p.label ?? 'Button';
+    return (
+      <Button
+        {...(component ? { component } : {})}
+        variant={p.variant ?? 'text'}
+        color={p.color ?? 'inherit'}
+        size={p.size ?? 'medium'}
+        startIcon={
+          typeof p.startIcon === 'string' ? <Icon name={p.startIcon} /> : p.startIcon
+        }
+        endIcon={
+          typeof p.endIcon === 'string' ? <Icon name={p.endIcon} /> : p.endIcon
+        }
+        disabled={p.disabled}
+        fullWidth={p.fullWidth}
+        type={p.type}
+        sx={p.sx}
+        id={ensureNodeId('button', p.id)}
+        className={p.className}
+        data-testid={p['data-testid']}
+        {...routingProps}
+      >
+        {children}
+      </Button>
+    );
+  },
+};
+
+export default ButtonResolver;

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

@@ -0,0 +1,219 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button, Link } from '@/gui/components/atoms';
+import Icon from '@/gui/Theme/Icon/Icon';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Button> = {
+  title: 'Atoms/Forms & Inputs/Button',
+  component: Button,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Button** primitive is a thin wrapper around MUI's \`MuiButton\` that preserves **polymorphism** and adds **declarative icons** (string tokens like 
+\`mui:Send\` or \`lucide:bolt\`). It integrates with **This.GUI** theming and respects your token-built palette.
+
+---
+## Features
+- Variants: \`contained\`, \`outlined\`, \`text\`.
+- Colors: \`primary\`, \`secondary\`, \`success\`, \`info\`, \`warning\`, \`error\`, \`inherit\`.
+- Sizes: \`small\`, \`medium\`, \`large\`.
+- **Icons** via tokens (\`startIcon\` / \`endIcon\`) or React nodes.
+- **Polymorphic**: \`component\` can be \`'a'\` or a Link (e.g. the This.GUI wrapper \`Link\`) for routing.
+- Respects your theme from \`GuiProvider\` (no need to wrap with \`ThemeProvider\`).
+
+---
+## Key Props
+- \`startIcon?: string | ReactNode\` — accepts a name from the **icon registry** (\`mui:*\` / \`lucide:*\`) or a React element.
+- \`endIcon?: string | ReactNode\`.
+- \`component?: ElementType | string\` — for polymorphism (\`'a'\`, RouterLink, etc.).
+- \`href?: string\` — when \`component='a'\`.
+- \`to?: string\` — when \`component={Link}\`.
+
+> Note: \`to\` and \`href\` are not exposed as Storybook controls because they only apply in specific modes; they are shown in dedicated stories.
+
+---
+## Basic usage
+~~~jsx
+import { Button } from '@/gui/primitives';
+
+<Button variant="contained" color="primary">Save</Button>
+<Button variant="outlined" color="secondary">Cancel</Button>
+<Button variant="text">Learn more</Button>
+~~~
+
+## With declarative icons
+~~~jsx
+<Button variant="contained" color="secondary" startIcon="mui:Send" endIcon="lucide:bolt">
+  Send
+</Button>
+~~~
+
+## As native anchor link
+~~~jsx
+<Button component="a" href="https://neurons.me" /* target="_blank" rel="noreferrer" */>
+  Visit neurons.me
+</Button>
+~~~
+
+## With RouterLink (This.GUI Link)
+~~~jsx
+import { Button, Link } from '@/gui/primitives';
+
+<Button component={Link} to="/docs">Go to docs</Button>
+~~~
+## Declarative JSON / Config usage
+~~~json
+{
+  "type": "Button",
+  "props": {
+    "variant": "text",
+    "color": "primary",
+    "component": "a",
+    "href": "https://neurons.me",
+    "target": "_blank",
+    "rel": "noreferrer",
+    "children": "Visit neurons.me"
+  }
+}
+~~~
+
+Another example with a RouterLink:
+~~~json
+{
+  "type": "Button",
+  "props": {
+    "variant": "contained",
+    "color": "secondary",
+    "component": "Link",
+    "to": "/docs",
+    "startIcon": "mui:Send",
+    "children": "Go to docs"
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['contained', 'outlined', 'text'],
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'inherit'],
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['small', 'medium', 'large'],
+    },
+    startIcon: { control: 'text', description: 'Icon token or a React element.' },
+    endIcon: { control: 'text', description: 'Icon token or a React element.' },
+    onClick: { action: 'clicked' },
+  },
+  args: {
+    variant: 'contained',
+    color: 'primary',
+    size: 'medium',
+    children: 'Click me',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  args: { color: 'primary' },
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Button {...args} variant="contained">Contained</Button>
+      <Button {...args} variant="outlined">Outlined</Button>
+      <Button {...args} variant="text">Text</Button>
+    </div>
+  ),
+};
+
+export const Colors: Story = {
+  args: { variant: 'contained' },
+  render: (args) => {
+    const colors: Array<'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error'> =
+      ['primary', 'secondary', 'success', 'info', 'warning', 'error'];
+    return (
+      <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+        {colors.map((c) => (
+          <Button key={c} {...args} color={c}>
+            {c[0].toUpperCase() + c.slice(1)}
+          </Button>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  args: { color: 'primary', variant: 'contained' },
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
+      <Button {...args} size="small">Small</Button>
+      <Button {...args} size="medium">Medium</Button>
+      <Button {...args} size="large">Large</Button>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  args: {
+    variant: 'contained',
+    color: 'secondary',
+    startIcon: <Icon name="Power" />,
+    endIcon: <Icon name="bolt" />,
+    children: 'Send',
+  },
+};
+
+export const PolymorphicAnchor: Story = {
+  args: {
+    variant: 'text',
+    color: 'primary',
+    children: 'Go to neurons.me',
+  },
+  render: (args) => (
+    <Button component="a" href="https://neurons.me">
+      {args.children}
+    </Button>
+  ),
+};
+
+export const PolymorphicRouterLink: Story = {
+  args: {
+    variant: 'text',
+    color: 'primary',
+    children: 'Go to /docs',
+  },
+  render: (args) => (
+    <Button component={Link} to="/docs">
+      {args.children}
+    </Button>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { variant: 'contained', color: 'primary', disabled: true, children: 'Disabled' },
+};
+
+export const FullWidth: Story = {
+  args: { variant: 'contained', color: 'primary', fullWidth: true, children: 'Full Width' },
+};

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

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import MuiButton from '@mui/material/Button';
+import type { OverridableComponent } from '@mui/material/OverridableComponent';
+import type { ButtonTypeMap } from '@mui/material/Button';
+import type { ButtonProps as MuiButtonProps } from '@mui/material/Button';
+import Icon from '@/gui/Theme/Icon/Icon';
+/**
+ * Button (This.GUI primitive)
+ * ----------------------------------------
+ * - Polymorphic: preserves MUI's `component` API and typing via OverridableComponent.
+ * - Enhances MUI by allowing `startIcon` / `endIcon` to be a declarative string
+ *   (e.g., "mui:Settings" / "lucide:camera") or a ReactNode.
+ */
+// Polymorphic props type that matches MUI Button while letting us tweak icon props
+export type Iconish = ReactNode | string | undefined;
+export type ButtonProps = Omit<MuiButtonProps, 'startIcon' | 'endIcon'> & {
+  startIcon?: Iconish;
+  endIcon?: Iconish;
+};
+function resolveIcon(node: Iconish): ReactNode | null {
+  if (!node) return null;
+  return typeof node === 'string' ? <Icon name={node} fontSize={18} /> : node;
+}
+const ButtonImpl = React.forwardRef<any, ButtonProps>(function Button(
+  { startIcon, endIcon, ...rest },
+  ref
+) {
+  return (
+    <MuiButton
+      ref={ref}
+      startIcon={resolveIcon(startIcon)}
+      endIcon={resolveIcon(endIcon)}
+      {...rest}
+    />
+  );
+}) as unknown as OverridableComponent<ButtonTypeMap<{}, 'button'>>;
+(ButtonImpl as any).displayName = 'Button';
+export default ButtonImpl;
+export type GuiButtonProps = React.ComponentProps<typeof ButtonImpl>;