this.gui 1.3.22 → 1.3.26

package/src/gui/components/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/components/atoms/ListItemText/ListItemText.stories.tsx

@@ -0,0 +1,156 @@
+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';
+
+const meta: Meta<typeof ListItemText> = {
+  title: 'Atoms/Organization/ListItemText',
+  component: ListItemText,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 260, maxWidth: 520 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  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/components/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/components/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;

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

@@ -0,0 +1,162 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Menu from './Menu';
+import Button from '@mui/material/Button';
+import MenuItem from '@mui/material/MenuItem';
+
+const meta: Meta<typeof Menu> = {
+  title: 'Atoms/Navigation/Menu',
+  component: Menu,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 260 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  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/components/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;