this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,168 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Menu from './Menu';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+import Button from '@mui/material/Button';
+import MenuItem from '@mui/material/MenuItem';
+
+const meta: Meta<typeof Menu> = {
+  title: 'Atoms/Menu',
+  component: Menu,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Menu** atom is a thin wrapper around MUI's \`MuiMenu\`. It supports **granular styling** via:
+- \`sx\` — root popover/menu container
+- \`paperSx\` — Paper slot
+- \`listSx\` — MenuList slot
+
+You can also pass \`PaperProps\` and \`MenuListProps\`; their \`sx\` are **merged** with \`paperSx\`/\`listSx\`.
+
+---
+## Basic usage
+~~~jsx
+const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);
+const open = Boolean(anchorEl);
+
+<Button onClick={(e) => setAnchorEl(e.currentTarget)}>Open menu</Button>
+<Menu open={open} anchorEl={anchorEl} onClose={() => setAnchorEl(null)}>
+  <MenuItem onClick={() => setAnchorEl(null)}>Profile</MenuItem>
+  <MenuItem onClick={() => setAnchorEl(null)}>Settings</MenuItem>
+</Menu>
+~~~
+
+## Granular styling
+~~~jsx
+<Menu
+  open={open}
+  anchorEl={anchorEl}
+  onClose={handleClose}
+  sx={{ mt: 1 }}
+  paperSx={{ borderRadius: 10 }}
+  listSx={{ py: 0.5 }}
+  PaperProps={{ elevation: 3 }}
+/>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "Menu",
+  "props": {
+    "open": true,
+    "sx": { "mt": 1 },
+    "paperSx": { "borderRadius": 10 },
+    "listSx": { "py": 0.5 },
+    "PaperProps": { "elevation": 3 },
+    "children": [
+      { "type": "MenuItem", "props": { "children": "Profile" } },
+      { "type": "MenuItem", "props": { "children": "Settings" } }
+    ]
+  }
+}
+~~~
+
+*Note:* \`anchorEl\` is a runtime element reference and is typically provided by the renderer/context in declarative mode.
+        `,
+      },
+    },
+    controls: {
+      exclude: ['anchorEl', 'PaperProps', 'MenuListProps'],
+    },
+  },
+  argTypes: {
+    open: { control: 'boolean' },
+    keepMounted: { control: 'boolean' },
+    variant: { control: { type: 'radio' }, options: ['menu', 'selectedMenu'] },
+    elevation: { control: { type: 'number', min: 0, max: 24, step: 1 } },
+    sx: { control: 'object' },
+  },
+  args: {
+    open: false, // controlled within each story with local state
+    keepMounted: false,
+    variant: 'menu',
+    elevation: 1,
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Menu>;
+
+// Reusable demo component that owns anchor state but forwards args
+const DemoMenu: React.FC<React.ComponentProps<typeof Menu>> = (props) => {
+  const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);
+  const open = Boolean(anchorEl);
+  const handleOpen = (e: React.MouseEvent<HTMLButtonElement>) => setAnchorEl(e.currentTarget);
+  const handleClose = () => setAnchorEl(null);
+  return (
+    <>
+      <Button variant="outlined" onClick={handleOpen} data-testid="open-menu">
+        Open Menu
+      </Button>
+      <Menu
+        {...props}
+        open={open}
+        anchorEl={anchorEl}
+        onClose={handleClose}
+        onClick={handleClose}
+      >
+        {props.children ?? (
+          <>
+            <MenuItem onClick={handleClose}>Profile</MenuItem>
+            <MenuItem onClick={handleClose}>My account</MenuItem>
+            <MenuItem onClick={handleClose}>Logout</MenuItem>
+          </>
+        )}
+      </Menu>
+    </>
+  );
+};
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => <DemoMenu {...args} />,
+};
+
+export const WithPaperAndListSx: Story = {
+  args: {
+    sx: { mt: 1 },
+  },
+  render: (args) => (
+    <DemoMenu
+      {...args}
+      PaperProps={{ elevation: 2, sx: { borderRadius: 2 } }}
+      MenuListProps={{ sx: { py: 0.5 } }}
+    />
+  ),
+};
+
+export const KeepMounted: Story = {
+  args: { keepMounted: true },
+  render: (args) => <DemoMenu {...args} />,
+};
+
+export const CustomOrigins: Story = {
+  args: {
+    sx: { mt: 1 },
+    // Showcase custom anchor/transform origins
+    anchorOrigin: { vertical: 'bottom', horizontal: 'left' },
+    transformOrigin: { vertical: 'top', horizontal: 'left' },
+  },
+  render: (args) => <DemoMenu {...args} />,
+};

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

@@ -0,0 +1,17 @@
+/*
+ * This.GUI — Menu
+ * Thin wrapper that preserves MUI's own typing and API.
+ * Examples:
+ *   <Menu open={open} onClose={handleClose} anchorEl={anchorEl}>
+ *     {children}
+ *   </Menu>
+ */
+import MuiMenu from '@mui/material/Menu';
+import * as React from 'react';
+
+// Re-export using MUI's own component type to keep full typing
+const Menu = MuiMenu;
+export type MenuProps = React.ComponentProps<typeof Menu>;
+
+(Menu as any).displayName = 'Gui.Menu';
+export default Menu;

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

@@ -0,0 +1,183 @@
+// src/gui/atoms/MenuItem/MenuItem.resolver.tsx
+import * as React from 'react';
+import MenuItem from './MenuItem';
+import Link from '../Link/Link';
+import Icon from '@/themes/icons/Icon';
+import ListItemIcon from '@mui/material/ListItemIcon';
+import ListItemText from '@mui/material/ListItemText';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { ListItemIconProps as MuiListItemIconProps } from '@mui/material/ListItemIcon';
+import type { ListItemTextProps as MuiListItemTextProps } from '@mui/material/ListItemText';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+// Merge sx parts into a single SxProps (filters out undefined)
+const sxJoin = (...parts: Array<SxProps<Theme> | undefined>): SxProps<Theme> =>
+  (parts.filter(Boolean) as unknown) as SxProps<Theme>;
+
+/**
+ * Declarative spec for MenuItem
+ *
+ * Notes
+ * - Wraps MUI's MenuItem (supports `component` polymorphism).
+ * - Declarative sugar:
+ *    - `label` / `secondary` map to `<ListItemText primary/secondary />`
+ *    - `startIcon` accepts a token (e.g., "mui:Settings", "lucide:mail") or a React node
+ * - Granular styling:
+ *    - `sx` (root MenuItem)
+ *    - `iconSx` (ListItemIcon)
+ *    - `textSx` (ListItemText)
+ * - Slot props passthrough:
+ *    - `ListItemIconProps`, `ListItemTextProps` (their `sx` are merged with iconSx/textSx)
+ */
+export type MenuItemSpec = {
+  type: 'MenuItem';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism / routing
+    component?: any; // 'li' | '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
+    label?: React.ReactNode | string;
+    secondary?: React.ReactNode | string;
+    startIcon?: React.ReactNode | string;
+    iconColor?: string;
+
+    // Core MenuItem props (subset; others passthrough)
+    dense?: boolean;
+    disabled?: boolean;
+    divider?: boolean;
+    selected?: boolean;
+    autoFocus?: boolean;
+
+    // Granular styling
+    sx?: SxProps<Theme>;       // root
+    iconSx?: SxProps<Theme>;   // ListItemIcon
+    textSx?: SxProps<Theme>;   // ListItemText
+
+    // Slot props passthrough
+    ListItemIconProps?: MuiListItemIconProps;
+    ListItemTextProps?: MuiListItemTextProps;
+
+    // Misc
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+    'data-gui-id'?: string;
+
+    // Allow arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+function renderDeclarativeIcon(node: React.ReactNode | string | undefined, iconColor?: string) {
+  if (!node) return null;
+  if (typeof node === 'string') return <Icon name={node} iconColor={iconColor} size={20} />;
+  return node;
+}
+
+function coerceComponent(comp: any) {
+  // allow declarative string token "Link" to map to our Link component
+  if (comp === 'Link') return Link;
+  return comp;
+}
+
+const MenuItemResolver: RegistryEntry = {
+  type: 'MenuItem',
+  resolve(spec: MenuItemSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    const providedDataGuiId = p['data-gui-id'];
+
+    // Decide polymorphic target
+    const component = coerceComponent(p.component ?? p.as ?? (p.to ? Link : 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 }
+        : {};
+
+    const {
+      children,
+      label,
+      secondary,
+      startIcon,
+      iconColor,
+      ListItemIconProps,
+      ListItemTextProps,
+      // strip resolver-only keys
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+      'data-gui-id': _dataGuiId,
+      ...rest
+    } = p;
+
+    const iconNode = renderDeclarativeIcon(startIcon, iconColor);
+    const hasTextBlock = label != null || secondary != null;
+
+    // Merge sx for ListItemIcon/Text if provided both via shorthand and slot props
+    const mergedIconSx = (p.iconSx || ListItemIconProps?.sx)
+      ? sxJoin(p.iconSx, ListItemIconProps?.sx as SxProps<Theme>)
+      : undefined;
+
+    const mergedTextSx = (p.textSx || ListItemTextProps?.sx)
+      ? sxJoin(p.textSx, ListItemTextProps?.sx as SxProps<Theme>)
+      : undefined;
+
+    const finalIconProps: MuiListItemIconProps | undefined = iconNode
+      ? {
+          ...(ListItemIconProps || {}),
+          ...(mergedIconSx ? { sx: mergedIconSx } : {}),
+        }
+      : undefined;
+
+    const finalTextProps: MuiListItemTextProps | undefined = hasTextBlock
+      ? {
+          ...(ListItemTextProps || {}),
+          ...(mergedTextSx ? { sx: mergedTextSx } : {}),
+        }
+      : undefined;
+
+    const dataGuiId = ensureNodeId('menu-item', providedDataGuiId);
+
+    return (
+      <MenuItem
+        component={component}
+        sx={p.sx}
+        id={p.id}
+        className={p.className}
+        data-testid={p['data-testid']}
+        data-gui-id={dataGuiId}
+        {...routingProps}
+        {...rest}
+      >
+        {iconNode ? <ListItemIcon {...finalIconProps}>{iconNode}</ListItemIcon> : null}
+        {hasTextBlock ? (
+          <ListItemText primary={label} secondary={secondary} {...finalTextProps} />
+        ) : (
+          children
+        )}
+      </MenuItem>
+    );
+  },
+};
+
+export default MenuItemResolver;

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

@@ -0,0 +1,138 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import MenuItem from './MenuItem';
+import Menu from '../Menu/Menu';
+import Button from '@mui/material/Button';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+const meta: Meta<typeof MenuItem> = {
+  title: 'Atoms/MenuItem',
+  component: MenuItem,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **MenuItem** atom is a thin wrapper around MUI's \`MuiMenuItem\`.
+
+In **declarative** mode (registry), the resolver supports:
+- \`label\` / \`secondary\` → maps to \`<ListItemText primary/secondary />\`
+- \`startIcon\` → token (e.g., \`"mui:Settings"\`, \`"lucide:mail"\`) or React node → renders inside \`<ListItemIcon />\`
+- Granular styling via:
+  - \`sx\` (root)
+  - \`iconSx\` (ListItemIcon)
+  - \`textSx\` (ListItemText)
+
+---
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "MenuItem",
+  "props": {
+    "startIcon": "mui:Settings",
+    "label": "Settings",
+    "secondary": "Manage your preferences",
+    "sx": { "py": 1 },
+    "iconSx": { "minWidth": 36 },
+    "textSx": { "my": 0 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component'],
+    },
+  },
+  argTypes: {
+    dense: { control: 'boolean' },
+    divider: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    selected: { control: 'boolean' },
+    sx: { control: 'object' },
+  },
+  args: {
+    dense: false,
+    divider: false,
+    disabled: false,
+    selected: false,
+    sx: {},
+    children: 'Menu item',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MenuItem>;
+
+// Reusable demo wrapper that controls open/close
+const DemoMenu: React.FC<{ children?: React.ReactNode }> = ({ children }) => {
+  const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);
+  const open = Boolean(anchorEl);
+  const handleOpen = (e: React.MouseEvent<HTMLButtonElement>) => setAnchorEl(e.currentTarget);
+  const handleClose = () => setAnchorEl(null);
+  return (
+    <>
+      <Button variant="outlined" onClick={handleOpen} data-testid="open-menu">
+        Open Menu
+      </Button>
+      <Menu open={open} anchorEl={anchorEl} onClose={handleClose} onClick={handleClose}>
+        {children ?? (
+          <>
+            <MenuItem onClick={handleClose}>Profile</MenuItem>
+            <MenuItem onClick={handleClose} selected dense>
+              Settings
+            </MenuItem>
+            <MenuItem onClick={handleClose} disabled>
+              Disabled
+            </MenuItem>
+          </>
+        )}
+      </Menu>
+    </>
+  );
+};
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <DemoMenu>
+      <MenuItem {...args} />
+    </DemoMenu>
+  ),
+};
+
+export const States: Story = {
+  render: () => (
+    <DemoMenu>
+      <MenuItem>Default</MenuItem>
+      <MenuItem selected>Selected</MenuItem>
+      <MenuItem disabled>Disabled</MenuItem>
+      <MenuItem dense>Dense</MenuItem>
+    </DemoMenu>
+  ),
+};
+
+export const WithCustomChildren: Story = {
+  render: () => (
+    <DemoMenu>
+      <MenuItem>
+        <strong>Custom node as children</strong>
+      </MenuItem>
+      <MenuItem>
+        <span style={{ opacity: 0.75 }}>With inline styling</span>
+      </MenuItem>
+    </DemoMenu>
+  ),
+};

package/src/gui/atoms/MenuItem/MenuItem.tsx

@@ -0,0 +1,14 @@
+/*
+ * This.GUI — MenuItem
+ * Thin wrapper that preserves MUI's own typing and API.
+ * Examples:
+ *   <MenuItem onClick={...}>Profile</MenuItem>
+ *   <MenuItem selected dense>Settings</MenuItem>
+ */
+import MuiMenuItem from '@mui/material/MenuItem';
+import * as React from 'react';
+// Re-export using MUI's own component type to keep full typing
+const MenuItem = MuiMenuItem;
+export type MenuItemProps = React.ComponentProps<typeof MenuItem>;
+(MenuItem as any).displayName = 'Gui.MenuItem';
+export default MenuItem;

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

@@ -0,0 +1,98 @@
+// src/gui/atoms/Paper/Paper.resolver.tsx
+import * as React from 'react';
+import Paper from './Paper';
+import Link from '../Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for Paper (polymorphic container)
+ *
+ * Notes
+ * - You can choose the rendered element via `component` (e.g. 'div', 'section', 'a')
+ * - 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 apply
+ *   safe `target`/`rel` defaults.
+ * - Supports `sx` and arbitrary system props passthrough.
+ */
+export type PaperSpec = {
+  type: 'Paper';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism / routing
+    component?: any; // 'div' | 'section' | 'article' | '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;
+
+    // MUI Paper core props (subset; rest is passthrough)
+    elevation?: number;
+    square?: boolean;
+    variant?: 'elevation' | 'outlined';
+
+    // Styling & misc
+    sx?: any;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Allow system props / arbitrary passthrough (p, m, display, etc.)
+    [key: string]: any;
+  };
+};
+
+const PaperResolver: RegistryEntry = {
+  type: 'Paper',
+  resolve(spec: PaperSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const nodeId = ensureNodeId('Paper', p.id);
+
+    // Decide polymorphic target
+    const component = p.component ?? p.as ?? (p.to ? Link : 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 }
+        : {};
+
+    // Collect common props and avoid leaking resolver-only keys
+    const {
+      children,
+      // remove resolver-only keys so they don't end up as DOM attributes
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+      ...rest
+    } = p;
+
+    return (
+      <Paper
+        component={component}
+        sx={p.sx}
+        id={nodeId}
+        className={p.className}
+        data-testid={p['data-testid']}
+        {...routingProps}
+        {...rest}
+      >
+        {children}
+      </Paper>
+    );
+  },
+};
+
+export default PaperResolver;