this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,102 @@
+// src/gui/atoms/ListItemIcon/ListItemIcon.resolver.tsx
+import * as React from 'react';
+import ListItemIcon from './ListItemIcon';
+import Icon from '@/themes/icons/Icon';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for ListItemIcon
+ *
+ * Fidelity
+ * - Forwards MUI props faithfully to `<ListItemIcon />`.
+ * - `children` has priority over any sugar props.
+ *
+ * Sugar
+ * - `icon`: string token (e.g., "lucide:mail", "mui:settings") or a ReactNode.
+ * - `iconProps`: forwarded to `<Icon />` when `icon` is a string.
+ * - `iconColor`: convenience alias mapped to Icon's color/htmlColor semantics.
+ * - `size`: sets Icon size (default 20).
+ *
+ * Editor/Inspector
+ * - Always emits a stable `data-gui-id` (auto via `ensureNodeId`) unless provided.
+ */
+export type ListItemIconSpec = {
+  type: 'ListItemIcon';
+  props?: {
+    // content
+    children?: React.ReactNode;
+
+    // sugar for registry-driven icons
+    icon?: React.ReactNode | string;
+    iconProps?: Record<string, any>;
+    iconColor?: string;
+    size?: number;
+
+    // styling
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // inspector id (auto if omitted)
+    'data-gui-id'?: string;
+
+    // passthrough
+    [key: string]: any;
+  };
+};
+
+const normalizeToken = (s: string) => String(s).trim().toLowerCase();
+
+const ListItemIconResolver: RegistryEntry = {
+  type: 'ListItemIcon',
+  resolve(spec: ListItemIconSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Build content with precedence: children > icon sugar
+    const { children, icon, iconColor, iconProps, size = 20 } = p;
+    let content: React.ReactNode = children;
+    if (content == null && icon) {
+      content =
+        typeof icon === 'string'
+          ? <Icon name={normalizeToken(icon)} iconColor={iconColor} size={size} {...iconProps} />
+          : icon;
+    }
+
+    // Prepare safe props for ListItemIcon (avoid leaking resolver-only keys)
+    const {
+      // sugar / resolver-only
+      icon: _icon,
+      iconProps: _iconProps,
+      iconColor: _iconColor,
+      size: _size,
+      'data-gui-id': providedNodeId,
+      // keep common
+      sx,
+      className,
+      id,
+      'data-testid': dataTestId,
+      // everything else passes through
+      ...rest
+    } = p;
+
+    const dataGuiId = ensureNodeId('list-item-icon', providedNodeId);
+
+    return (
+      <ListItemIcon
+        sx={sx}
+        className={className}
+        id={id}
+        data-testid={dataTestId}
+        data-gui-id={dataGuiId}
+        {...rest}
+      >
+        {content}
+      </ListItemIcon>
+    );
+  },
+};
+
+export default ListItemIconResolver;

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

@@ -0,0 +1,135 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import List from '@mui/material/List';
+import ListItem from '@mui/material/ListItem';
+import ListItemText from '../ListItemText/ListItemText';
+import ListItemIcon from './ListItemIcon';
+import Icon from '@/themes/icons/Icon';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+const meta: Meta<typeof ListItemIcon> = {
+  title: 'Atoms/ListItemIcon',
+  component: ListItemIcon,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260, maxWidth: 520 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ListItemIcon** atom is a thin wrapper around MUI's \`MuiListItemIcon\` and remains faithful to its API.
+
+In **declarative** mode, the resolver adds sugar to render icons by **token** via the registry:
+- \`icon\`: string token (e.g., \`"lucide:mail"\`, \`"mui:settings"\`) or React node
+- \`iconProps\`: forwarded to the registry \`<Icon />\` when \`icon\` is a token
+- \`iconColor\`: convenience color for the registry icon
+- \`size\`: icon size (default 20)
+
+Tokens are **normalized** (lowercased & trimmed) to avoid missing icons due to casing.
+
+---
+## React usage
+~~~jsx
+<List>
+  <ListItem>
+    <ListItemIcon sx={{ minWidth: 36 }}>
+      <Icon name="lucide:mail" size={20} />
+    </ListItemIcon>
+    <ListItemText primary="Inbox" />
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "ListItemIcon",
+  "props": {
+    "icon": "lucide:mail",
+    "sx": { "minWidth": 36 },
+    "iconProps": { "strokeWidth": 1.5 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['children'],
+    },
+  },
+  argTypes: {
+    sx: { control: 'object', table: { category: 'Style' } },
+    className: { control: 'text' },
+  },
+  args: {
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListItemIcon>;
+
+const DemoList: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+  <List dense>
+    <ListItem>{children}</ListItem>
+  </List>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <DemoList>
+      <ListItemIcon {...args}>
+        <Icon name="lucide:mail" />
+      </ListItemIcon>
+      <ListItemText primary="Item with icon slot" />
+    </DemoList>
+  ),
+};
+
+export const WithTokenViaResolverExample: Story = {
+  name: 'Declarative token (doc example)',
+  render: () => (
+    <DemoList>
+      {/* Emula el resultado del resolver al usar icon="lucide:mail" */}
+      <ListItemIcon sx={{ minWidth: 36 }}>
+        <Icon name="lucide:mail" size={20} />
+      </ListItemIcon>
+      <ListItemText primary="Inbox (token)" />
+    </DemoList>
+  ),
+};
+
+export const WithReactChild: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemIcon sx={{ minWidth: 40 }}>
+        <Icon name="mui:settings" />
+      </ListItemIcon>
+      <ListItemText primary="Settings (React child)" />
+    </DemoList>
+  ),
+};
+
+export const WithSx: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemIcon sx={{ minWidth: 48 }}>
+        <Icon name="lucide:user" />
+      </ListItemIcon>
+      <ListItemText primary="Custom minWidth via sx" />
+    </DemoList>
+  ),
+};

package/src/gui/atoms/ListItemIcon/ListItemIcon.tsx

@@ -0,0 +1,11 @@
+/*
+ * This.GUI — ListItemIcon
+ * Thin wrapper that preserves MUI typing.
+ * Use our resolver for declarative sugar (icon tokens) and granular styling patterns.
+ */
+import * as React from 'react';
+import MuiListItemIcon from '@mui/material/ListItemIcon';
+const ListItemIcon = MuiListItemIcon;
+export type ListItemIconProps = React.ComponentProps<typeof ListItemIcon>;
+(ListItemIcon as any).displayName = 'Gui.ListItemIcon';
+export default ListItemIcon;

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

@@ -0,0 +1,112 @@
+// src/gui/atoms/ListItemText/ListItemText.resolver.tsx
+import * as React from 'react';
+import ListItemText from './ListItemText';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for ListItemText
+ *
+ * Goals
+ * - Be faithful to MUI's API: pass through native props like `primary`, `secondary`,
+ *   `inset`, `disableTypography`, `primaryTypographyProps`, `secondaryTypographyProps`, etc.
+ * - Add **granular styling** sugar for slots:
+ *    - `sx`            → root container
+ *    - `primarySx`     → merged into `primaryTypographyProps.sx`
+ *    - `secondarySx`   → merged into `secondaryTypographyProps.sx`
+ *
+ * Notes
+ * - Not a routing component; we simply respect optional `component` (or `as`) for polymorphism.
+ * - We avoid inserting `undefined` inside `sx` arrays; we compute merged values safely.
+ */
+export type ListItemTextSpec = {
+  type: 'ListItemText';
+  props?: {
+    // MUI core props (subset; the rest are forwarded)
+    primary?: React.ReactNode;
+    secondary?: React.ReactNode;
+    inset?: boolean;
+    disableTypography?: boolean;
+    primaryTypographyProps?: any;
+    secondaryTypographyProps?: any;
+
+    // Polymorphism
+    component?: any;
+    as?: any; // alias of component
+
+    // Granular styling
+    sx?: SxProps<Theme>;            // root
+    primarySx?: SxProps<Theme>;     // Typography for primary
+    secondarySx?: SxProps<Theme>;   // Typography for secondary
+
+    // Misc
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+    'data-gui-id'?: string;
+
+    // Allow arbitrary passthrough (Typography props, etc.)
+    [key: string]: any;
+  };
+};
+
+const ListItemTextResolver: RegistryEntry = {
+  type: 'ListItemText',
+  resolve(spec: ListItemTextSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    const dataGuiId = ensureNodeId('list-item-text', (p as any)['data-gui-id']);
+
+    // Determine component target (no routing here)
+    const component = p.component ?? p.as;
+
+    const {
+      // extract slot style sugar and slot props to merge
+      primarySx,
+      secondarySx,
+      primaryTypographyProps,
+      secondaryTypographyProps,
+      // strip resolver-only alias
+      as: _as,
+      "data-gui-id": dataGuiIdProp,
+      // keep the rest (includes primary/secondary/sx/etc.)
+      ...rest
+    } = p;
+
+    // Merge sx into Typography slot props without introducing undefined in arrays
+    const mergedPrimarySx =
+      primarySx != null && primaryTypographyProps?.sx != null
+        ? [primarySx, primaryTypographyProps.sx]
+        : primarySx ?? primaryTypographyProps?.sx;
+
+    const mergedSecondarySx =
+      secondarySx != null && secondaryTypographyProps?.sx != null
+        ? [secondarySx, secondaryTypographyProps.sx]
+        : secondarySx ?? secondaryTypographyProps?.sx;
+
+    const finalPrimaryTypographyProps = primaryTypographyProps
+      ? { ...primaryTypographyProps, sx: mergedPrimarySx }
+      : mergedPrimarySx != null
+      ? { sx: mergedPrimarySx }
+      : undefined;
+
+    const finalSecondaryTypographyProps = secondaryTypographyProps
+      ? { ...secondaryTypographyProps, sx: mergedSecondarySx }
+      : mergedSecondarySx != null
+      ? { sx: mergedSecondarySx }
+      : undefined;
+
+    return (
+      <ListItemText
+        component={component}
+        primaryTypographyProps={finalPrimaryTypographyProps}
+        secondaryTypographyProps={finalSecondaryTypographyProps}
+        data-gui-id={dataGuiId}
+        {...rest}
+      />
+    );
+  },
+};
+
+export default ListItemTextResolver;

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

@@ -0,0 +1,162 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import ListItemText from './ListItemText';
+import List from '@mui/material/List';
+import ListItem from '@mui/material/ListItem';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+const meta: Meta<typeof ListItemText> = {
+  title: 'Atoms/ListItemText',
+  component: ListItemText,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260, maxWidth: 520 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ListItemText** atom is a thin wrapper around MUI's \`MuiListItemText\`.  
+It preserves MUI props and typing (faithful to the original), and fits naturally into This.GUI's declarative/resolver pattern.
+
+---
+## Basic usage
+~~~jsx
+<List>
+  <ListItem>
+    <ListItemText primary="Single line" />
+  </ListItem>
+  <ListItem>
+    <ListItemText primary="Primary" secondary="Secondary description" />
+  </ListItem>
+</List>
+~~~
+
+## Typography control
+~~~jsx
+<List>
+  <ListItem>
+    <ListItemText
+      primary="Custom primary"
+      primaryTypographyProps={{ variant: 'subtitle1', sx: { fontWeight: 600 } }}
+    />
+  </ListItem>
+  <ListItem>
+    <ListItemText
+      primary="Primary"
+      secondary="Secondary"
+      secondaryTypographyProps={{ color: 'text.secondary', sx: { fontStyle: 'italic' } }}
+    />
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "ListItemText",
+  "props": {
+    "primary": "Primary",
+    "secondary": "Secondary",
+    "primarySx": { "fontWeight": 600 },
+    "secondarySx": { "color": "text.secondary", "fontStyle": "italic" }
+  }
+}
+~~~
+
+*Note:* In React usage, use \`primaryTypographyProps.sx\` / \`secondaryTypographyProps.sx\`.  
+In declarative mode, you can also use \`primarySx\` / \`secondarySx\` and the resolver will merge them into the Typography slot props.
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'primaryTypographyProps', 'secondaryTypographyProps'],
+    },
+  },
+  argTypes: {
+    primary: { control: 'text' },
+    secondary: { control: 'text' },
+    inset: { control: 'boolean' },
+    disableTypography: { control: 'boolean' },
+    sx: { control: 'object' },
+  },
+  args: {
+    primary: 'Primary',
+    secondary: 'Secondary',
+    inset: false,
+    disableTypography: false,
+    sx: {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListItemText>;
+
+const DemoList: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+  <List dense>
+    <ListItem>{children}</ListItem>
+  </List>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <DemoList>
+      <ListItemText {...args} />
+    </DemoList>
+  ),
+};
+
+export const PrimaryOnly: Story = {
+  args: { secondary: '' },
+  render: (args) => (
+    <DemoList>
+      <ListItemText {...args} />
+    </DemoList>
+  ),
+};
+
+export const WithTypographyProps: Story = {
+  render: () => (
+    <List>
+      <ListItem>
+        <ListItemText
+          primary="Custom primary"
+          primaryTypographyProps={{ variant: 'subtitle1', sx: { fontWeight: 600 } }}
+        />
+      </ListItem>
+      <ListItem>
+        <ListItemText
+          primary="Primary"
+          secondary="Secondary"
+          secondaryTypographyProps={{ color: 'text.secondary', sx: { fontStyle: 'italic' } }}
+        />
+      </ListItem>
+    </List>
+  ),
+};
+
+export const InsetAndDisabledTypography: Story = {
+  render: () => (
+    <List>
+      <ListItem>
+        <ListItemText primary="Inset item" inset />
+      </ListItem>
+      <ListItem>
+        <ListItemText
+          primary={<strong>Disable Typography wrapper</strong>}
+          disableTypography
+        />
+      </ListItem>
+    </List>
+  ),
+};

package/src/gui/atoms/ListItemText/ListItemText.tsx

@@ -0,0 +1,15 @@
+/**
+ * This component is a thin wrapper around MUI’s ListItemText.
+ * It preserves MUI’s own props and typing.
+ * It is kept polymorphic in line with MUI’s design.
+ * This wrapper enables consistency with This.GUI’s declarative/resolver pattern.
+ *
+ * It is faithful to MUI because it re-exports MuiListItemText directly,
+ * keeping props intact and typing consistent.
+ */
+import React from 'react';
+import MuiListItemText from '@mui/material/ListItemText';
+const ListItemText = MuiListItemText;
+export type ListItemTextProps = React.ComponentProps<typeof ListItemText>;
+(ListItemText as any).displayName = 'Gui.ListItemText';
+export default ListItemText;

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

@@ -0,0 +1,112 @@
+// src/gui/atoms/Menu/Menu.resolver.tsx
+import * as React from 'react';
+import Menu from './Menu';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { PopoverOrigin } from '@mui/material/Popover';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for Menu
+ *
+ * Notes
+ * - Wraps MUI's Menu. Not polymorphic.
+ * - Supports granular styling via:
+ *    - `sx` (root Popover/Menu container)
+ *    - `paperSx` (Paper slot)
+ *    - `listSx` (MenuList slot)
+ * - You can also pass through `PaperProps` and `MenuListProps`; their `sx` will be merged with `paperSx`/`listSx`.
+ * - Supports `"data-gui-id"` for editor instrumentation.
+ */
+export type MenuSpec = {
+  type: 'Menu';
+  props?: {
+    children?: React.ReactNode;
+
+    // Core Menu props (subset; rest is passthrough)
+    open?: boolean;
+    anchorEl?: Element | null;
+    onClose?: (...args: any[]) => void;
+    onClick?: (...args: any[]) => void;
+    keepMounted?: boolean;
+    elevation?: number;
+    variant?: 'menu' | 'selectedMenu';
+    anchorOrigin?: PopoverOrigin;
+    transformOrigin?: PopoverOrigin;
+    TransitionProps?: any;
+
+    // Granular styling
+    sx?: SxProps<Theme>;         // root (Popover)
+    paperSx?: SxProps<Theme>;    // Paper slot
+    listSx?: SxProps<Theme>;     // MenuList slot
+
+    // Slot props passthrough
+    PaperProps?: any;
+    MenuListProps?: any;
+
+    // Misc passthrough
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+    "data-gui-id"?: string;
+
+    // Allow arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const MenuResolver: RegistryEntry = {
+  type: 'Menu',
+  resolve(spec: MenuSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Extract resolver-only style helpers and children
+    const {
+      sx,
+      id,
+      className,
+      paperSx,
+      listSx,
+      PaperProps,
+      MenuListProps,
+      open,
+      "data-gui-id": dataGuiId,
+      // keep other props in `rest`
+      ...rest
+    } = p;
+
+    const guiId = ensureNodeId('menu', dataGuiId);
+
+    // Merge sx for Paper/MenuList without inserting `undefined` inside arrays
+    const mergedPaperSx =
+      paperSx != null && PaperProps?.sx != null
+        ? [paperSx, PaperProps.sx]
+        : paperSx ?? PaperProps?.sx;
+
+    const mergedListSx =
+      listSx != null && MenuListProps?.sx != null
+        ? [listSx, MenuListProps.sx]
+        : listSx ?? MenuListProps?.sx;
+
+    const finalPaperProps = PaperProps ? { ...PaperProps, sx: mergedPaperSx } : (mergedPaperSx != null ? { sx: mergedPaperSx } : undefined);
+    const finalMenuListProps = MenuListProps ? { ...MenuListProps, sx: mergedListSx } : (mergedListSx != null ? { sx: mergedListSx } : undefined);
+
+    return (
+      <Menu
+        open={!!open}
+        sx={sx}
+        id={id}
+        className={className}
+        data-testid={p['data-testid']}
+        data-gui-id={guiId}
+        {...rest}
+        PaperProps={finalPaperProps}
+        MenuListProps={finalMenuListProps}
+      >
+        {p.children}
+      </Menu>
+    );
+  },
+};
+
+export default MenuResolver;