this.gui 1.3.22 → 1.3.26

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

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Grid from './Grid';
+import Box from '@/gui/components/atoms/Box/Box';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Grid> = {
+  title: 'Atoms/Containers/Grid',
+  component: Grid,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 0, minHeight: 240 }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Grid** atom is a thin wrapper around MUI's \`Grid\` component. It keeps the original API and polymorphism but integrates with **This.GUI** tokens and allows declarative usage via the resolver.
+
+---
+## Features
+- Supports all MUI Grid props like \`container\`, \`item\`, \`spacing\`, \`xs\`, \`sm\`, \`md\`, etc.
+- Fully themeable via **This.GUI** tokens and \`sx\`.
+- Works both as a container and as an item.
+- Can be described declaratively via JSON specs for resolvers.
+
+---
+## Key Props
+- \`container?: boolean\` — defines a grid container.
+- \`item?: boolean\` — defines a grid item.
+- \`spacing?: number | object\` — gap between items (when container).
+- \`xs | sm | md | lg | xl?: number\` — responsive column sizes.
+- \`sx?: object\` — granular styling.
+
+---
+## Basic usage (React)
+~~~tsx
+import { Grid, Box } from '@/gui/atoms';
+
+<Grid container spacing={2}>
+  <Grid item xs={6}>
+    <Box sx={{ backgroundColor: 'primary.main', p: 2, color: '#fff' }}>Item 1</Box>
+  </Grid>
+  <Grid item xs={6}>
+    <Box sx={{ backgroundColor: 'secondary.main', p: 2, color: '#fff' }}>Item 2</Box>
+  </Grid>
+</Grid>
+~~~
+
+---
+## Declarative JSON / Config usage
+This GUI's **resolver** lets you describe a Grid via a config object:
+
+~~~json
+{
+  "type": "Grid",
+  "props": {
+    "container": true,
+    "spacing": 2,
+    "children": [
+      {
+        "type": "Grid",
+        "props": {
+          "item": true,
+          "xs": 6,
+          "children": {
+            "type": "Box",
+            "props": {
+              "sx": { "backgroundColor": "primary.main", "p": 2, "color": "#fff" },
+              "children": "Item 1"
+            }
+          }
+        }
+      },
+      {
+        "type": "Grid",
+        "props": {
+          "item": true,
+          "xs": 6,
+          "children": {
+            "type": "Box",
+            "props": {
+              "sx": { "backgroundColor": "secondary.main", "p": 2, "color": "#fff" },
+              "children": "Item 2"
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+~~~
+
+> The resolver maps this spec to real React elements, preserving polymorphism and \`sx\` styling.
+        `,
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Grid>;
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <Grid {...args} container spacing={2}>
+      <Grid item xs={6}>
+        <Box sx={{ backgroundColor: 'primary.main', p: 2, color: '#fff' }}>Item 1</Box>
+      </Grid>
+      <Grid item xs={6}>
+        <Box sx={{ backgroundColor: 'secondary.main', p: 2, color: '#fff' }}>Item 2</Box>
+      </Grid>
+    </Grid>
+  ),
+};
+
+export const ResponsiveGrid: Story = {
+  render: (args) => (
+    <Grid {...args} container spacing={2}>
+      <Grid item xs={12} sm={6} md={4}>
+        <Box sx={{ backgroundColor: 'info.main', p: 2, color: '#fff' }}>xs=12 sm=6 md=4</Box>
+      </Grid>
+      <Grid item xs={12} sm={6} md={4}>
+        <Box sx={{ backgroundColor: 'success.main', p: 2, color: '#fff' }}>xs=12 sm=6 md=4</Box>
+      </Grid>
+      <Grid item xs={12} sm={12} md={4}>
+        <Box sx={{ backgroundColor: 'warning.main', p: 2, color: '#fff' }}>xs=12 sm=12 md=4</Box>
+      </Grid>
+    </Grid>
+  ),
+  name: 'Responsive Grid Layout',
+};

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

@@ -0,0 +1,15 @@
+// File: Grid.tsx
+import MuiGrid from '@mui/material/Grid';
+import type { GridProps } from './Grid.types';
+
+/**
+ * This.GUI — Grid
+ * Wrapper around MUI’s Grid that preserves props & typing.
+ * 
+ * Purpose:
+ * - Consistent namespace integration (This.GUI).
+ * - Supports full MUI Grid props including `sx`, `container`, `item`, etc.
+ */
+const Grid = MuiGrid;
+(Grid as any).displayName = 'Gui.Grid';
+export default Grid;

package/src/gui/components/atoms/Grid/Grid.types.ts

@@ -0,0 +1,9 @@
+import MuiGrid from '@mui/material/Grid';
+import type { GridProps as MuiGridProps } from '@mui/material/Grid';
+export type GridProps = React.ComponentProps<typeof MuiGrid> & MuiGridProps;
+
+export type GridResolverSpec = {
+  type: 'Grid';
+  props?: GridProps; // or GridProps if you want to alias it
+};
+

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

@@ -0,0 +1,137 @@
+// src/gui/atoms/IconButton/IconButton.resolver.tsx
+import * as React from 'react';
+import IconButton from './IconButton';
+import Icon from '@/gui/Theme/Icon/Icon';
+import Link from '@/gui/components/atoms/Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative resolver for IconButton
+ * -----------------------------------
+ * - Forwards all MUI IconButton props faithfully.
+ * - Supports polymorphism via `component` / `as`.
+ * - Adds sugar:
+ *    • `icon` string → rendered through our Icon registry (mui:/lucide: tokens), normalized to lowercase.
+ *    • Routing helpers: if `to` w/o `component` → uses This.GUI `Link`; if `href`/`external` → uses anchor with safe target/rel.
+ * - Provides granular styling via `sx` (root) and optional `iconSx`.
+ *
+ * A11y note: when rendering only an icon (no visible text), pass an `aria-label`.
+ */
+export type IconButtonSpec = {
+  type: 'IconButton';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism
+    component?: any;
+    as?: any; // alias for component
+
+    // Routing sugar
+    to?: string;
+    href?: string;
+    external?: boolean;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+
+    // Sugar: icon may be a token or a node
+    icon?: string | React.ReactNode;
+    iconProps?: Record<string, any>;
+
+    // MUI props passthrough (subset; others go via index signature)
+    color?:
+      | 'inherit'
+      | 'default'
+      | 'primary'
+      | 'secondary'
+      | 'success'
+      | 'error'
+      | 'info'
+      | 'warning';
+    size?: 'small' | 'medium' | 'large';
+    edge?: 'start' | 'end' | false;
+    disabled?: boolean;
+
+    // Styling
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough (MUI will validate)
+    [key: string]: any;
+  };
+};
+
+const IconButtonResolver: RegistryEntry = {
+  type: 'IconButton',
+  resolve(spec: IconButtonSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const nodeId = ensureNodeId('iconbutton', p.id as string | undefined);
+
+    // Decide polymorphic target
+    const component =
+      p.component ??
+      p.as ??
+      (p.to ? Link : (p.href || p.external) ? 'a' : undefined);
+
+    // Routing / anchor props
+    const routingProps =
+      component === 'a' || p.external
+        ? {
+            href: p.href,
+            target: p.target ?? (p.external ? '_blank' : undefined),
+            rel: p.rel ?? (p.external ? 'noopener noreferrer' : undefined),
+          }
+        : component === Link || (p.to && !p.component)
+        ? { to: p.to }
+        : {};
+
+    // Prepare children (icon sugar)
+    const { children, icon, iconProps } = p;
+    const normalizedToken =
+      typeof icon === 'string' ? icon.trim() : null;
+
+    const effectiveChildren =
+      children ??
+      (normalizedToken ? (
+        <Icon
+          name={normalizedToken}
+          {...(iconProps || {})}
+        />
+      ) : (
+        icon ?? null
+      ));
+
+    // Collect & strip resolver-only keys so they don't leak to DOM
+    const {
+      as: _as,
+      to: _to,
+      href: _href,
+      external: _external,
+      target: _target,
+      rel: _rel,
+      icon: _icon,
+      iconSx: _iconSx,
+      iconProps: _iconProps,
+      ...rest
+    } = p;
+
+    return (
+      <IconButton
+        {...(component ? { component } : {})}
+        sx={p.sx}
+        className={p.className}
+        id={nodeId}
+        data-testid={p['data-testid']}
+        {...routingProps}
+        {...rest}
+      >
+        {effectiveChildren}
+      </IconButton>
+    );
+  },
+};
+
+export default IconButtonResolver;

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

@@ -0,0 +1,134 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import IconButton from './IconButton';
+import Icon from '@/gui/Theme/Icon/Icon';
+const meta: Meta<typeof IconButton> = {
+  title: 'Atoms/Forms & Inputs/IconButton',
+  component: IconButton,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 200 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **IconButton** atom is a thin wrapper around MUI's \`MuiIconButton\`, staying faithful to its API and polymorphism (\`component\`).
+
+In **declarative** mode (resolver), you can pass an \`icon\` token (e.g., \`"lucide:menu"\`, \`"mui:Close"\`) and it will render through the Icon registry. You can also style the icon with \`iconSx\` while using \`sx\` for the button root.
+
+---
+## React usage
+~~~jsx
+<IconButton color="primary" size="medium" aria-label="open menu">
+  <Icon name="lucide:menu" />
+</IconButton>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "IconButton",
+  "props": {
+    "color": "primary",
+    "size": "medium",
+    "icon": "lucide:menu",
+    "sx": { "border": "1px solid", "borderColor": "divider" },
+    "iconSx": { "opacity": 0.9 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children'],
+    },
+  },
+  argTypes: {
+    color: {
+      control: { type: 'select' },
+      options: ['inherit', 'default', 'primary', 'secondary', 'success', 'error', 'info', 'warning'],
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['small', 'medium', 'large'],
+    },
+    edge: {
+      control: { type: 'radio' },
+      options: ['start', 'end', false],
+    },
+    disabled: { control: 'boolean' },
+    sx: { control: 'object' },
+  },
+  args: {
+    color: 'default',
+    size: 'medium',
+    edge: false,
+    disabled: false,
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof IconButton>;
+export const Playground: Story = {
+  render: (args) => (
+    <IconButton {...args} aria-label="menu">
+      <Icon name="lucide:menu" />
+    </IconButton>
+  ),
+};
+
+export const Colors: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
+      {(['default', 'primary', 'secondary', 'success', 'info', 'warning', 'error'] as const).map((c) => (
+        <IconButton key={c} color={c} aria-label={c}>
+          <Icon name="mui:Favorite" />
+        </IconButton>
+      ))}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
+      <IconButton size="small" aria-label="small">
+        <Icon name="lucide:bell" />
+      </IconButton>
+      <IconButton size="medium" aria-label="medium">
+        <Icon name="lucide:bell" />
+      </IconButton>
+      <IconButton size="large" aria-label="large">
+        <Icon name="lucide:bell" />
+      </IconButton>
+    </div>
+  ),
+};
+
+export const WithEdge: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
+      <IconButton edge="start" aria-label="start">
+        <Icon name="lucide:chevron-left" />
+      </IconButton>
+      <IconButton edge="end" aria-label="end">
+        <Icon name="lucide:chevron-right" />
+      </IconButton>
+    </div>
+  ),
+};
+
+export const WithSx: Story = {
+  render: () => (
+    <IconButton sx={{ border: '1px solid', borderColor: 'divider' }} aria-label="styled">
+      <Icon name="mui:Close" />
+    </IconButton>
+  ),
+};

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

@@ -0,0 +1,22 @@
+/**
+ * This.GUI — IconButton
+ * ----------------------------------------
+ * Thin wrapper around MUI’s IconButton.
+ *
+ * Fidelity:
+ * - Directly re-exports MUI’s IconButton so all typing and props remain intact.
+ * - Preserves polymorphism (`component` prop) via OverridableComponent.
+ * - Supports granular styling via the standard `sx` prop (MUI System).
+ *
+ * Why wrap?
+ * - Consistency with This.GUI’s atom pattern (every MUI primitive wrapped).
+ * - Provides a clean declarative/resolver entry point.
+ */
+import * as React from 'react';
+import MuiIconButton from '@mui/material/IconButton';
+import type { OverridableComponent } from '@mui/material/OverridableComponent';
+import type { IconButtonTypeMap } from '@mui/material/IconButton';
+const IconButton = MuiIconButton as OverridableComponent<IconButtonTypeMap<{}, 'button'>>;
+export type IconButtonProps = React.ComponentProps<typeof IconButton>;
+(IconButton as any).displayName = 'Gui.IconButton';
+export default IconButton;

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

@@ -0,0 +1,74 @@
+// src/gui/atoms/Link/Link.resolver.tsx
+import * as React from 'react';
+import type { RegistryEntry } from '@/registry/types';
+import Link, { LinkProps as GuiLinkProps } from './Link';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import { useInRouterContext } from 'react-router-dom';
+
+/** Declarative spec for Link (JSON-friendly) */
+type LinkSpec = {
+  type: 'Link';
+  props?: {
+    label?: React.ReactNode;              // convenience: text content
+    children?: React.ReactNode;           // explicit children (wins over label)
+    href?: string;                        // external
+    to?: string;                          // internal (react-router)
+    external?: boolean;                   // force anchor + target/rel
+    underline?: 'none' | 'hover' | 'always';
+    // pass-through styling/attrs
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    target?: string;
+    rel?: string;
+    color?: GuiLinkProps['color'];
+    variant?: GuiLinkProps['variant'];
+    // ...cualquier otro prop permitido por tu Link
+    'data-testid'?: string;
+    ariaLabel?: string;
+  };
+};
+
+const LinkResolver: RegistryEntry = {
+  type: 'Link',
+  resolve(spec: LinkSpec) {
+    const p = spec.props ?? {};
+    const nodeId = ensureNodeId('link', p.id as string | undefined);
+    const hasRouter = useInRouterContext();
+
+    // Routing / destino
+    const routingProps: Partial<GuiLinkProps> =
+      p.external
+        ? {
+            href: p.href,
+            ...(p.target ? { target: p.target } : { target: '_blank' }),
+            ...(p.rel ? { rel: p.rel } : { rel: 'noopener noreferrer' }),
+          }
+        : p.to && hasRouter
+        ? { to: p.to }
+        : p.href
+        ? { href: p.href }
+        : {};
+
+    const children = p.children ?? p.label ?? null;
+
+    return (
+      <Link
+        underline={p.underline ?? 'hover'}
+        color={p.color}
+        variant={p.variant}
+        sx={p.sx}
+        className={p.className}
+        id={nodeId}
+        data-testid={p['data-testid']}
+        {...(p.ariaLabel ? { 'aria-label': p.ariaLabel } : {})}
+        {...routingProps}
+      >
+        {children}
+      </Link>
+    );
+  },
+};
+
+export default LinkResolver;

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

@@ -0,0 +1,157 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Link, Button } from '@/gui/components/atoms';
+// ======================= Meta =======================
+const meta: Meta<typeof Link> = {
+  title: 'Atoms/Navigation/Link',
+  component: Link,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Link** primitive is a thin wrapper over MUI's \`MuiLink\` that supports **both** external links (\`href\`) and internal routing (\`to\`) using **react-router-dom**. It integrates with **This.GUI** theming via \`GuiProvider\`.
+
+---
+## Features
+- External links with \`href\` (renders an anchor).
+- Internal navigation with \`to\` (renders a RouterLink under the hood).
+- Works seamlessly as a child or as a render target for other primitives (e.g. \`<Button component={Link} to="/docs"/>\`).
+- Inherits typography and color from the theme tokens.
+
+---
+## Key Props
+- \`href?: string\` — external URL.
+- \`to?: string | LocationDescriptor\` — internal route (react-router-dom).
+- \`underline?: 'none' | 'hover' | 'always'\` — underline behavior.
+- \`color?: 'primary' | 'secondary' | 'inherit' | 'textPrimary' | 'textSecondary' | 'error' | 'info' | 'success' | 'warning'\`.
+
+> Note: \`to\` and \`href\` are demonstrated in dedicated stories rather than Storybook controls.
+
+---
+## Basic Usage
+~~~jsx
+import { Link } from '@/gui/primitives';
+
+<Link href="https://neurons.me" target="_blank" rel="noreferrer">Visit neurons.me</Link>
+~~~
+
+## Internal Routing
+~~~jsx
+import { Link } from '@/gui/primitives';
+
+<Link to="/docs">Go to docs</Link>
+~~~
+
+## As render target for Button
+~~~jsx
+import { Button, Link } from '@/gui/primitives';
+
+<Button component={Link} to="/docs">Docs</Button>
+~~~
+
+## Declarative JSON / Config usage
+~~~json
+{
+  "type": "Link",
+  "props": {
+    "to": "/docs",
+    "children": "Go to docs"
+  }
+}
+~~~
+
+Another example with an external URL:
+~~~json
+{
+  "type": "Link",
+  "props": {
+    "href": "https://neurons.me",
+    "target": "_blank",
+    "rel": "noreferrer",
+    "children": "Visit neurons.me"
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+  argTypes: {
+    underline: {
+      control: { type: 'radio' },
+      options: ['none', 'hover', 'always'],
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'inherit', 'textPrimary', 'textSecondary', 'error', 'info', 'success', 'warning'],
+    },
+    // Do not expose component/to/href as controls — they are shown in dedicated stories
+    component: { table: { disable: true } },
+  },
+  args: {
+    underline: 'hover',
+    color: 'primary',
+    children: 'Example link',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Link>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const ExternalHref: Story = {
+  name: 'External (href)',
+  render: () => (
+    <Link href="https://neurons.me" target="_blank" rel="noreferrer">
+      Visit neurons.me
+    </Link>
+  ),
+};
+
+export const InternalTo: Story = {
+  name: 'Internal (to)',
+  render: () => <Link to="/docs">Go to docs</Link>,
+};
+
+export const Colors: Story = {
+  render: (args) => {
+    const colors: Array<any> = ['primary', 'secondary', 'success', 'info', 'warning', 'error'];
+    return (
+      <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+        {colors.map((c) => (
+          <Link key={c} {...args} color={c} href="#">
+            {c[0].toUpperCase() + c.slice(1)}
+          </Link>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const UnderlineVariants: Story = {
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Link {...args} underline="none" href="#">None</Link>
+      <Link {...args} underline="hover" href="#">Hover</Link>
+      <Link {...args} underline="always" href="#">Always</Link>
+    </div>
+  ),
+};
+
+export const AsButtonTarget: Story = {
+  name: 'As Button component',
+  render: () => (
+    <Button component={Link} to="/docs">
+      Docs via Link
+    </Button>
+  ),
+};