this.gui 1.3.22 → 1.3.26

package/src/gui/components/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 '@/gui/components/atoms/Link/Link';
+import Icon from '@/gui/Theme/Icon/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} fontSize={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/components/atoms/MenuItem/MenuItem.stories.tsx

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

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

@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Paper from './Paper';
+
+const meta: Meta<typeof Paper> = {
+  title: 'Atoms/Containers/Paper',
+  component: Paper,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240, background: 'var(--mui-palette-background-default)' }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Paper** atom is a thin wrapper around MUI's \`MuiPaper\` that preserves **polymorphism** via the \`component\` prop and passes through all MUI props.
+It integrates with **This.GUI** theming and supports **declarative specs** through the Paper resolver.
+
+---
+## Features
+- Variants: \`elevation\`, \`outlined\`
+- Elevation: \`0..24\`
+- \`square\` boolean
+- **Polymorphic** via \`component\` (e.g., \`'div'\`, \`'section'\`, \`'a'\`)
+- **Routing default** in declarative mode: if \`to\` is provided (and no explicit \`component\`), resolver renders This.GUI \`Link\`
+- Full **system props** passthrough via \`sx\` (and regular MUI system props)
+
+---
+## Basic usage
+~~~jsx
+import Paper from '@/gui/atoms/Paper/Paper';
+
+<Paper elevation={2} sx={{ p: 2, borderRadius: 2 }}>
+  Content
+</Paper>
+~~~
+
+## Polymorphic
+~~~jsx
+<Paper component="section" variant="outlined" sx={{ p: 2 }}>
+  I'm a &lt;section&gt;
+</Paper>
+
+<Paper component="a" href="/docs" sx={{ p: 2, textDecoration: 'none' }}>
+  Go to docs
+</Paper>
+~~~
+
+*Note:* The \`component\` prop is demonstrated via dedicated stories (not Controls) because Storybook's args typing for MUI OverridableComponent can incorrectly narrow props and flag \`component\` as invalid in the Controls panel.
+
+## Declarative JSON / Resolver
+When using the registry-driven renderer, a Paper spec like this:
+
+~~~json
+{
+  "type": "Paper",
+  "props": {
+    "variant": "outlined",
+    "elevation": 0,
+    "component": "section",
+    "sx": { "p": 2, "borderRadius": 2 },
+    "children": "Content"
+  }
+}
+~~~
+
+**Routing (declarative default)** — If you provide \`to\` (and **omit** \`component\`), the resolver will render using This.GUI \`Link\`:
+
+~~~json
+{
+  "type": "Paper",
+  "props": {
+    "to": "/docs",
+    "sx": { "p": 2 },
+    "children": "Go to docs"
+  }
+}
+~~~
+
+The resolver:
+- Chooses \`component\` by priority: explicit \`component\` → \`as\` → (\`to\` ⇒ This.GUI \`Link\`) → (\`external\` ⇒ \`'a'\`)
+- For \`external: true\`, applies safe defaults: \`target="_blank"\`, \`rel="noopener noreferrer"\`
+- Cleans resolver-only keys so they don't leak into the DOM
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component'],
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['elevation', 'outlined'],
+    },
+    elevation: {
+      control: { type: 'range', min: 0, max: 24, step: 1 },
+    },
+    square: {
+      control: 'boolean',
+    },
+    sx: {
+      control: 'object',
+    },
+  },
+  args: {
+    variant: 'elevation',
+    elevation: 1,
+    square: false,
+    children: 'Paper content',
+    sx: { p: 2 },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Paper>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Paper {...args} variant="elevation">Elevation (default)</Paper>
+      <Paper {...args} variant="outlined">Outlined</Paper>
+    </div>
+  ),
+};
+
+export const Elevations: Story = {
+  args: { variant: 'elevation' },
+  render: (args) => {
+    const levels = [0, 1, 2, 3, 4, 6, 8, 12, 16, 24];
+    return (
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(140px, 1fr))', gap: 12 }}>
+        {levels.map((e) => (
+          <Paper key={e} {...args} elevation={e} sx={{ p: 2 }}>
+            elevation={e}
+          </Paper>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const PolymorphicSection: Story = {
+  args: { variant: 'outlined', children: 'I render as <section>' },
+  render: (args) => (
+    <Paper {...args} component="section">
+      {args.children}
+    </Paper>
+  ),
+};
+
+export const PolymorphicAnchor: Story = {
+  args: { children: 'I render as <a href="/docs">', sx: { p: 2, textDecoration: 'none' } },
+  render: (args) => (
+    <Paper component="a" href="/docs" sx={args.sx}>
+      {args.children}
+    </Paper>
+  ),
+};
+
+export const WithSystemProps: Story = {
+  name: 'With system props',
+  args: { variant: 'outlined' },
+  render: (args) => (
+    <Paper {...args} sx={{ p: 2, m: 1, display: 'inline-block', borderRadius: 2 }}>
+      Padding, margin, display via system props.
+    </Paper>
+  ),
+};
+
+export const WithSx: Story = {
+  args: { variant: 'outlined' },
+  render: (args) => (
+    <Paper {...args} sx={{ p: 2, borderRadius: 2, borderStyle: 'dashed' }}>
+      Custom \`sx\` styling (dashed outline).
+    </Paper>
+  ),
+};

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

@@ -0,0 +1,15 @@
+/*
+ * This.GUI — Paper (polymorphic)
+ * Thin wrapper that preserves MUI's own typing and `component` API.
+ * Examples:
+ *   <Paper elevation={3} />
+ *   <Paper component="section" square variant="outlined" />
+ *   <Paper component="a" href="/docs" />
+ */
+import MuiPaper from '@mui/material/Paper';
+import * as React from 'react';
+// Re-export using MUI's own component type to keep polymorphism and full typing
+const Paper = MuiPaper;
+export type PaperProps = React.ComponentProps<typeof Paper>;
+(Paper as any).displayName = 'Gui.Paper';
+export default Paper;

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

@@ -0,0 +1,10 @@
+import Section from './Section';
+import type { SectionProps } from './Section.types';
+
+export const SectionResolver = {
+  type: 'Section',
+  component: Section,
+  resolve: (props: SectionProps) => <Section {...props} />,
+};
+
+export default SectionResolver;