this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,171 @@
+import * as React from 'react';
+import Box from './Box';
+import Link from '../Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for Box (polymorphic container)
+ *
+ * JSON-friendly rules:
+ * - Prefer `to` / `href` / `external` over passing a string `"Link"`.
+ * - We accept intrinsic element strings (e.g. 'div', 'section', 'span', 'a', 'img').
+ * - If `to` is present and no explicit React component was provided, we render with This.GUI `Link`.
+ * - If `href`/`external` are present and no explicit component was provided, we render an anchor (`'a'`).
+ * - When `component="img"`, image attributes (`src`, `alt`, `width`, `height`, etc.) are passed through.
+ */
+export type BoxSpec = {
+  type: 'Box';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism / routing
+  component?: React.ElementType | string;
+    as?: React.ElementType | string; // alias for component
+    to?: string;     // router target (when component={Link} or inferred)
+    href?: string;   // anchor target (when component='a' or inferred)
+    external?: boolean | 'true' | 1; // if truthy, anchor gets safe target/rel
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+
+    // IMG-specific (when component='img')
+    src?: string;
+    alt?: string;
+    width?: number | string;
+    height?: number | string;
+    loading?: 'eager' | 'lazy';
+    decoding?: 'auto' | 'sync' | 'async';
+    referrerPolicy?: React.HTMLAttributeReferrerPolicy;
+    sizes?: string;
+    srcSet?: string;
+
+    // Styling & misc
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Allow system props / arbitrary passthrough (gap, p, m, display, etc.)
+    [key: string]: any;
+  };
+};
+
+const BoxResolver: RegistryEntry = {
+  type: 'Box',
+  resolve(spec: BoxSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Decide polymorphic target (safe for JSON):
+    // - Accept real React components (functions/classes).
+    // - Accept intrinsic strings ('div','section','span','a','img', etc.) EXCEPT the string "Link".
+    // - Infer Link/'a' from `to`/`href` when no explicit component is provided.
+    const rawComp = p.component ?? p.as;
+
+    const isReactComp = typeof rawComp === 'function';
+    const isString = typeof rawComp === 'string';
+
+    // Normalize strings (e.g. 'Img' -> 'img'); disallow the literal "Link"
+    const normalizedString = isString ? String(rawComp).trim() : undefined;
+    const lowered = normalizedString ? normalizedString.toLowerCase() : undefined;
+    const isIntrinsicString = !!normalizedString && lowered !== 'link';
+
+    let component: any | undefined =
+      isReactComp ? (rawComp as React.ElementType) :
+      isIntrinsicString ? normalizedString :
+      undefined;
+
+    if (!component) {
+      if (p.to) {
+        component = Link;
+      } else if (p.href || p.external) {
+        component = 'a';
+      }
+    }
+
+    // Build routing/anchor props only if they match the chosen component
+    const routingProps: Record<string, any> = {};
+    if (component === Link && p.to) {
+      routingProps.to = p.to;
+    }
+    if (component === 'a') {
+      routingProps.href = p.href;
+      const isExternal = p.external === true || p.external === 'true' || p.external === 1;
+      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;
+      }
+    }
+
+    // IMG specific passthrough (only when explicitly rendering an <img>)
+    const imgProps =
+      component === 'img'
+        ? {
+            src: p.src,
+            alt: p.alt,
+            width: p.width,
+            height: p.height,
+            loading: p.loading,
+            decoding: p.decoding,
+            referrerPolicy: p.referrerPolicy,
+            sizes: p.sizes,
+            srcSet: p.srcSet,
+          }
+        : {};
+
+    // Dev-time nudge if someone picked 'img' without a src
+    if (process.env.NODE_ENV !== 'production' && component === 'img' && !p.src) {
+      // eslint-disable-next-line no-console
+      console.warn('[Box.resolver] component="img" used without a `src` prop.');
+    }
+
+    // Collect common props and avoid leaking resolver-only keys
+    const {
+      children,
+      // resolver-only / routing keys to strip
+      as: _as,
+      to: _to,
+      href: _href,
+      external: _external,
+      target: _target,
+      rel: _rel,
+      // img-only keys already handled
+      src: _src,
+      alt: _alt,
+      width: _width,
+      height: _height,
+      loading: _loading,
+      decoding: _decoding,
+      referrerPolicy: _referrerPolicy,
+      sizes: _sizes,
+      srcSet: _srcSet,
+      // passthrough everything else (system props, data-*, aria-*, etc.)
+      ...rest
+    } = p;
+
+    // Build root props, conditionally attach `component`
+    const rootProps: Record<string, any> = {
+      sx: p.sx,
+      id: ensureNodeId('box', p.id),
+      className: p.className,
+      'data-testid': p['data-testid'],
+      ...routingProps,
+      ...imgProps,
+      ...rest,
+    };
+    if (component) {
+      rootProps.component = component;
+    }
+
+    return (
+      <Box {...rootProps}>
+        {children}
+      </Box>
+    );
+  },
+};
+
+export default BoxResolver;

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

@@ -0,0 +1,271 @@
+// src/gui/atoms/Box/Box.stories.tsx
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Link, Typography, Button } from '@/gui/atoms';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Box> = {
+  title: 'Atoms/Box',
+  component: Box,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 240 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  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/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/atoms/Button/Button.resolver.tsx

@@ -0,0 +1,98 @@
+// src/gui/primitives/Button/Button.resolver.tsx
+import * as React from 'react';
+import Button from './Button';
+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={p.startIcon}
+        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;