this.gui 1.0.18 → 1.1.0

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

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

@@ -0,0 +1,75 @@
+// 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';
+
+/** 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);
+
+    // 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
+        ? { 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/atoms/Link/Link.stories.tsx

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

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

@@ -0,0 +1,14 @@
+import React, { forwardRef } from 'react';
+import { Link as MuiLink, LinkProps as MuiLinkProps } from '@mui/material';
+import { Link as RouterLink, LinkProps as RouterLinkProps } from 'react-router-dom';
+type GuiLinkProps = MuiLinkProps & { to?: RouterLinkProps['to'] };
+const Link = forwardRef<HTMLAnchorElement, GuiLinkProps>(function Link(props, ref) {
+  const { to, ...rest } = props;
+  if (to) {
+    return <MuiLink component={RouterLink} to={to} ref={ref} {...rest} />;
+  }
+  return <MuiLink ref={ref} {...rest} />;
+});
+
+export default Link;
+export type { GuiLinkProps as LinkProps };

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

@@ -0,0 +1,95 @@
+// src/gui/atoms/List/List.resolver.tsx
+import * as React from 'react';
+import List from './List';
+import ListSubheader from '@mui/material/ListSubheader';
+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 resolver for List
+ *
+ * Fidelity
+ * - Forwards MUI props faithfully (dense, disablePadding, subheader, etc.).
+ * - Supports polymorphism via `component` (and alias `as`).
+ * - Provides **granular styling** via `sx` (root) and optional `subheaderSx`.
+ * - Generates a stable id via `ensureNodeId`.
+ *
+ * Sugar
+ * - `subheaderText`: if provided (and `subheader` not provided), we render
+ *   a `<ListSubheader />` with that text. You can style it via `subheaderSx`.
+ *
+ * Note: Routing props (`href`, `to`, `external`) are not handled at the List level.
+ */
+export type ListSpec = {
+  type: 'List';
+  props?: {
+    children?: React.ReactNode;
+    // Polymorphism
+    component?: any;
+    as?: any; // alias of component
+    // MUI props (subset; others passthrough)
+    dense?: boolean;
+    disablePadding?: boolean;
+    subheader?: React.ReactNode;
+    // Sugar
+    subheaderText?: React.ReactNode;
+    subheaderSx?: SxProps<Theme>;
+    // Styling
+    sx?: SxProps<Theme>; // root styles
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const ListResolver: RegistryEntry = {
+  type: 'List',
+  resolve(spec: ListSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const id = ensureNodeId('list', p.id);
+    const component = p.component ?? p.as;
+    const {
+      children,
+      subheader,
+      subheaderText,
+      subheaderSx,
+      // strip resolver-only alias
+      as: _as,
+      // passthrough rest (dense, disablePadding, sx, etc.)
+      ...rest
+    } = p;
+    const effectiveSubheader =
+      subheader != null
+        ? subheader
+        : subheaderText != null
+        ? (
+            <ListSubheader component="div" sx={subheaderSx}>
+              {subheaderText}
+            </ListSubheader>
+          )
+        : undefined;
+
+    const rootProps: any = {
+      ...rest,
+      sx: p.sx,
+      className: p.className,
+      id,
+      'data-testid': p['data-testid'],
+      subheader: effectiveSubheader,
+    };
+    if (component !== undefined) {
+      rootProps.component = component;
+    }
+
+    return (
+      <List {...rootProps}>
+        {children}
+      </List>
+    );
+  },
+};
+
+export default ListResolver;

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

@@ -0,0 +1,143 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import List from './List';
+import ListItem from '../ListItem/ListItem';
+import ListItemIcon from '../ListItemIcon/ListItemIcon';
+import ListItemText from '../ListItemText/ListItemText';
+import Icon from '@/themes/icons/Icon';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+import ListSubheader from '@mui/material/ListSubheader';
+
+const meta: Meta<typeof List> = {
+  title: 'Atoms/List',
+  component: List,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260, maxWidth: 560 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **List** atom is a thin wrapper around MUI's \`MuiList\`, staying faithful to its API and polymorphism.
+
+In **declarative** mode (resolver), it forwards MUI props and supports granular styling via \`sx\`.
+It also provides sugar: \`subheaderText\` (and \`subheaderSx\`) to easily render a \`<ListSubheader/>\` when you don't pass \`subheader\` explicitly.
+
+---
+## React usage
+~~~jsx
+<List dense subheader={<li />}> // arbitrary subheader (from MUI API)
+  <ListItem>
+    <ListItemIcon>
+      <Icon name="lucide:inbox" />
+    </ListItemIcon>
+    <ListItemText primary="Inbox" />
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "List",
+  "props": {
+    "dense": true,
+    "disablePadding": false,
+    "subheaderText": "Shortcuts",
+    "subheaderSx": { "fontWeight": 600 },
+    "sx": { "bgcolor": "background.paper", "borderRadius": 8 }
+  }
+}
+~~~
+*Note:* \`subheaderText\`/\`subheaderSx\` are **resolver-only** sugar; they are not MUI props.
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children', 'subheader'],
+    },
+  },
+  argTypes: {
+    dense: { control: 'boolean' },
+    disablePadding: { control: 'boolean' },
+    sx: { control: 'object', table: { category: 'Style' } },
+  },
+  args: {
+    dense: false,
+    disablePadding: false,
+    sx: { bgcolor: 'background.paper', borderRadius: 1, border: '1px solid', borderColor: 'divider' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof List>;
+
+const SampleRows: React.FC = () => (
+  <>
+    <ListItem>
+      <ListItemIcon>
+        <Icon name="lucide:inbox" />
+      </ListItemIcon>
+      <ListItemText primary="Inbox" />
+    </ListItem>
+    <ListItem>
+      <ListItemIcon>
+        <Icon name="lucide:send" />
+      </ListItemIcon>
+      <ListItemText primary="Sent" />
+    </ListItem>
+    <ListItem>
+      <ListItemIcon>
+        <Icon name="lucide:star" />
+      </ListItemIcon>
+      <ListItemText primary="Starred" />
+    </ListItem>
+  </>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <List {...args}>
+      <SampleRows />
+    </List>
+  ),
+};
+
+export const WithSubheader: Story = {
+  name: 'With subheader (MUI prop)',
+  render: () => (
+    <List subheader={<ListSubheader component="div" sx={{ fontWeight: 600 }}>Shortcuts</ListSubheader>}>
+      <SampleRows />
+    </List>
+  ),
+};
+
+export const DenseAndNoPadding: Story = {
+  args: { dense: true, disablePadding: true },
+  render: (args) => (
+    <List {...args}>
+      <SampleRows />
+    </List>
+  ),
+};
+
+export const StyledWithSx: Story = {
+  args: { sx: { bgcolor: 'background.paper', borderRadius: 2, boxShadow: 1 } },
+  render: (args) => (
+    <List {...args}>
+      <SampleRows />
+    </List>
+  ),
+};

package/src/gui/atoms/List/List.tsx

@@ -0,0 +1,20 @@
+/**
+ * This.GUI — List
+ * Thin wrapper around MUI’s List that preserves MUI props & typing.
+ *
+ * Fidelity
+ * - We directly re-export MUI’s component so all behavior/typing remain intact.
+ * - Granular styling is supported via the standard `sx` prop (MUI System).
+ *
+ * Why wrap it?
+ * - Consistency with This.GUI’s atom pattern (each atom in its own module).
+ * - Provides a clean surface for a resolver (declarative mode) without
+ *   altering React usage.
+ */
+import * as React from 'react';
+import MuiList from '@mui/material/List';
+const List = MuiList;
+export type ListProps = React.ComponentProps<typeof List>;
+// Helpful display name in React DevTools
+(List as any).displayName = 'Gui.List';
+export default List;