this.gui 1.3.22 → 1.3.26

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

@@ -0,0 +1,214 @@
+// src/gui/atoms/ListItemButton/ListItemButton.resolver.tsx
+import * as React from 'react';
+import ListItemButton from './ListItemButton';
+import Link from '@/gui/components/atoms/Link/Link';
+import Icon from '@/gui/Theme/Icon/Icon';
+// Use our own thin wrappers for consistency & display names
+import ListItemIcon from '@/gui/components/atoms/ListItemIcon/ListItemIcon';
+import ListItemText from '@/gui/components/atoms/ListItemText/ListItemText';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import Box from '../Box/Box';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for ListItemButton
+ *
+ * Goals
+ * - Be faithful to MUI's API: forward native props like `selected`, `disabled`, `dense`, `alignItems`, etc.
+ * - Preserve polymorphism via MUI's `component` prop (and alias `as`).
+ * - Add **declarative sugar** (optional):
+ *    - `startIcon` / `endIcon`: string token (e.g., "lucide:mail", "mui:settings") or ReactNode
+ *    - `label` / `secondary`: mapped to `<ListItemText primary/secondary />`
+ * - Add **granular styling** for slots:
+ *    - `sx`         → root ListItemButton
+ *    - `iconSx`     → ListItemIcon (leading)
+ *    - `textSx`     → ListItemText
+ *    - `endIconSx`  → trailing icon container
+ *
+ * Notes
+ * - If `children` are provided, they take precedence and render as-is (no sugar applied).
+ * - Tokens are normalized (lowercased & trimmed) to avoid missing icons due to casing.
+ * - Routing:
+ *    - If `to` is provided (and no explicit `component`), the resolver will default to This.GUI `Link`.
+ *    - If `external` is true (and no explicit `component`), it will default to an anchor `'a'` and add safe `target`/`rel`.
+ */
+export type ListItemButtonSpec = {
+  type: 'ListItemButton';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism / routing
+    component?: any; // 'div' | 'a' | Link | custom
+    as?: any;        // alias for component
+    to?: string;     // router target (when component={Link})
+    href?: string;   // anchor target (when component='a')
+    external?: boolean; // force external anchor
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+
+    // Sugar (optional)
+    startIcon?: React.ReactNode | string;
+    endIcon?: React.ReactNode | string;
+    iconColor?: string;       // applies to startIcon/endIcon when tokens
+    endIconColor?: string;    // override for trailing icon
+    size?: number;            // icon size (default 20)
+    label?: React.ReactNode | string;
+    secondary?: React.ReactNode | string;
+
+    // MUI props (subset; others passthrough)
+    selected?: boolean;
+    disabled?: boolean;
+    dense?: boolean;
+    alignItems?: 'flex-start' | 'center';
+    divider?: boolean;
+
+    // Granular styling
+    sx?: SxProps<Theme>;          // root
+    iconSx?: SxProps<Theme>;      // leading ListItemIcon
+    textSx?: SxProps<Theme>;      // ListItemText
+    endIconSx?: SxProps<Theme>;   // trailing icon container
+
+    // Slot props passthrough (their own sx can be merged)
+    ListItemIconProps?: { sx?: SxProps<Theme>; [k: string]: any };
+    ListItemTextProps?: { sx?: SxProps<Theme>; [k: string]: any };
+
+    // Editor / telemetry
+    'data-gui-id'?: string;
+
+    // Misc DOM
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const normalizeToken = (s: string) => s.trim().toLowerCase();
+
+function renderIcon(node: React.ReactNode | string | undefined, color?: string, size = 20) {
+  if (!node) return null;
+  return typeof node === 'string'
+    ? (
+      <Icon
+        name={normalizeToken(node)}
+        iconColor={color}
+        fontSize={size}
+      />
+    )
+    : node;
+}
+
+const ListItemButtonResolver: RegistryEntry = {
+  type: 'ListItemButton',
+  resolve(spec: ListItemButtonSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Generate/ensure a stable gui id (does not override an explicit one)
+    const dataGuiId = ensureNodeId('list-item-button', (p as any)['data-gui-id']);
+
+    // Decide polymorphic target (only pass when defined)
+    const decidedComponent = p.component ?? p.as ?? (p.to ? Link : p.external ? 'a' : undefined);
+    const componentProp = decidedComponent ? { component: decidedComponent } : undefined;
+
+    // Routing/anchor props
+    const routingProps =
+      decidedComponent === 'a' || p.external
+        ? {
+            href: p.href,
+            target: p.target ?? (p.external ? '_blank' : undefined),
+            rel: p.rel ?? (p.external ? 'noopener noreferrer' : undefined),
+          }
+        : decidedComponent === Link || (p.to && !p.component)
+        ? { to: p.to }
+        : {};
+
+    // Destructure and clean resolver-only fields
+    const {
+      children,
+      startIcon,
+      endIcon,
+      iconColor,
+      endIconColor,
+      size = 20,
+      ListItemIconProps,
+      ListItemTextProps,
+      iconSx,
+      textSx,
+      endIconSx,
+
+      // strip resolver-only aliasing keys so they don't leak to DOM
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+
+      // keep rest: native MUI props (selected, dense, disabled, divider, alignItems, sx, etc.)
+      ...rest
+    } = p as any;
+
+    // If explicit children, render as-is (no sugar)
+    if (children != null) {
+      return (
+        <ListItemButton
+          {...componentProp}
+          sx={p.sx}
+          id={p.id}
+          className={p.className}
+          data-testid={p['data-testid']}
+          data-gui-id={dataGuiId}
+          {...routingProps}
+          {...rest}
+        >
+          {children}
+        </ListItemButton>
+      );
+    }
+
+    // Build sugar content
+    const leadingIcon = renderIcon(startIcon, iconColor, size);
+    const trailingIcon = renderIcon(endIcon, endIconColor ?? iconColor, size);
+    const hasText = p.label != null || p.secondary != null;
+
+    // Merge sx for slot props safely (array merge preserves both)
+    const mergedIconSx =
+      iconSx != null && ListItemIconProps?.sx != null ? [iconSx, ListItemIconProps.sx] : iconSx ?? ListItemIconProps?.sx;
+    const mergedTextSx =
+      textSx != null && ListItemTextProps?.sx != null ? [textSx, ListItemTextProps.sx] : textSx ?? ListItemTextProps?.sx;
+
+    const finalIconProps = leadingIcon
+      ? (ListItemIconProps ? { ...ListItemIconProps, sx: mergedIconSx } : (mergedIconSx != null ? { sx: mergedIconSx } : undefined))
+      : undefined;
+
+    const finalTextProps = hasText
+      ? (ListItemTextProps ? { ...ListItemTextProps, sx: mergedTextSx } : (mergedTextSx != null ? { sx: mergedTextSx } : undefined))
+      : undefined;
+
+    return (
+      <ListItemButton
+        {...componentProp}
+        sx={p.sx}
+        id={p.id}
+        className={p.className}
+        data-testid={p['data-testid']}
+        data-gui-id={dataGuiId}
+        {...routingProps}
+        {...rest}
+      >
+        {leadingIcon ? <ListItemIcon {...finalIconProps}>{leadingIcon}</ListItemIcon> : null}
+        {hasText ? <ListItemText primary={p.label} secondary={p.secondary} {...finalTextProps} /> : null}
+        {trailingIcon ? (
+          <Box sx={[{ marginLeft: 'auto', display: 'inline-flex', alignItems: 'center' }, endIconSx as any]}>
+            {trailingIcon}
+          </Box>
+        ) : null}
+      </ListItemButton>
+    );
+  },
+};
+
+export default ListItemButtonResolver;

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

@@ -0,0 +1,155 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import ListItemButton from './ListItemButton';
+import ListItemIcon from '@/gui/components/atoms/ListItemIcon/ListItemIcon';
+import ListItemText from '@/gui/components/atoms/ListItemText/ListItemText';
+import Icon from '@/gui/Theme/Icon/Icon';
+import List from '@mui/material/List';
+import ListItem from '@mui/material/ListItem';
+
+const meta: Meta<typeof ListItemButton> = {
+  title: 'Atoms/Organization/ListItemButton',
+  component: ListItemButton,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 260, maxWidth: 560 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ListItemButton** atom is a thin wrapper around MUI's \`MuiListItemButton\`, staying faithful to its API and polymorphism.
+
+In **declarative** mode, the resolver adds sugar:
+- \`startIcon\` / \`endIcon\`: token (e.g., \`"lucide:mail"\`, \`"mui:settings"\`) or ReactNode — rendered via the icon registry
+- \`label\` / \`secondary\` → mapped to \`<ListItemText primary/secondary />\`
+- Granular styling:
+  - \`sx\` (root), \`iconSx\` (leading \`ListItemIcon\`), \`textSx\` (text), \`endIconSx\` (trailing icon container)
+
+---
+## React usage
+~~~jsx
+<List>
+  <ListItem disablePadding>
+    <ListItemButton selected>
+      <ListItemIcon>
+        <Icon name="lucide:mail" />
+      </ListItemIcon>
+      <ListItemText primary="Inbox" secondary="Messages" />
+    </ListItemButton>
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "ListItemButton",
+  "props": {
+    "startIcon": "lucide:mail",
+    "label": "Inbox",
+    "secondary": "Messages",
+    "sx": { "py": 1 },
+    "iconSx": { "minWidth": 36 },
+    "textSx": { "my": 0 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children'],
+    },
+  },
+  argTypes: {
+    selected: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    dense: { control: 'boolean' },
+    divider: { control: 'boolean' },
+    alignItems: { control: { type: 'radio' }, options: ['center', 'flex-start'] },
+    sx: { control: 'object' },
+  },
+  args: {
+    selected: false,
+    disabled: false,
+    dense: false,
+    divider: false,
+    alignItems: 'center',
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListItemButton>;
+
+const DemoList: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+  <List dense sx={{ bgcolor: 'background.paper', borderRadius: 1, overflow: 'hidden', border: '1px solid', borderColor: 'divider' }}>
+    <ListItem disablePadding>{children}</ListItem>
+  </List>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <DemoList>
+      <ListItemButton {...args}>
+        <ListItemIcon>
+          <Icon name="mail" />
+        </ListItemIcon>
+        <ListItemText primary="Inbox" secondary="Messages" />
+      </ListItemButton>
+    </DemoList>
+  ),
+};
+
+export const WithTrailingIcon: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemButton>
+        <ListItemIcon>
+          <Icon name="settings" />
+        </ListItemIcon>
+        <ListItemText primary="Settings" secondary="Preferences" />
+        <span style={{ marginLeft: 'auto', display: 'inline-flex' }}>
+          <Icon name="chevron_right" />
+        </span>
+      </ListItemButton>
+    </DemoList>
+  ),
+};
+
+export const AsAnchorLink: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemButton component="a" href="https://neurons.me">
+        <ListItemIcon>
+          <Icon name="link" />
+        </ListItemIcon>
+        <ListItemText primary="neurons.me" secondary="External link" />
+      </ListItemButton>
+    </DemoList>
+  ),
+};
+
+export const WithSx: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemButton sx={{ py: 1.25 }}>
+        <ListItemIcon sx={{ minWidth: 40 }}>
+          <Icon name="person" />
+        </ListItemIcon>
+        <ListItemText
+          primary="Profile"
+          secondary="Account"
+          slotProps={{ secondary: { sx: { color: 'text.secondary' } } }}
+        />
+      </ListItemButton>
+    </DemoList>
+  ),
+};

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

@@ -0,0 +1,15 @@
+/**
+ * This component is a thin wrapper around MUI’s ListItemButton.
+ * It preserves MUI’s props and typing, staying faithful to MUI.
+ * 
+ * Why wrap it?
+ * - Consistency with This.GUI’s atom pattern (each atom has its own file).
+ * - Supports declarative/resolver usage while keeping all MUI props intact.
+ * - Allows granular style control via `sx`.
+ */
+import * as React from 'react';
+import MuiListItemButton from '@mui/material/ListItemButton';
+const ListItemButton = MuiListItemButton;
+export type ListItemButtonProps = React.ComponentProps<typeof ListItemButton>;
+(ListItemButton as any).displayName = 'Gui.ListItemButton';
+export default ListItemButton;

package/src/gui/components/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 '@/gui/Theme/Icon/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} fontSize={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/components/atoms/ListItemIcon/ListItemIcon.stories.tsx

@@ -0,0 +1,132 @@
+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 '@/gui/components/atoms/ListItemText/ListItemText';
+import ListItemIcon from './ListItemIcon';
+import Icon from '@/gui/Theme/Icon/Icon';
+import GuiProvider from '@/gui/Theme/GuiProvider';
+
+const meta: Meta<typeof ListItemIcon> = {
+  title: 'Atoms/Organization/ListItemIcon',
+  component: ListItemIcon,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <GuiProvider>
+        <div style={{ padding: 16, minHeight: 260, maxWidth: 520 }}>
+          <Story />
+        </div>
+      </GuiProvider>
+    ),
+  ],
+  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="mail" fontSize={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/components/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;