this.gui 1.3.40 → 1.3.42

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

@@ -0,0 +1,223 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Drawer, Box, Button, Typography } from '@/gui/components/atoms';
+// ======================= Meta =======================
+const meta: Meta<typeof Drawer> = {
+  title: 'Atoms/Containers/Drawer',
+  component: Drawer,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 320 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Drawer** primitive is a thin wrapper over MUI's \`MuiDrawer\`. It preserves all of MUI's props and behavior, while keeping the import surface stable via \`@/gui/primitives\`.
+
+---
+## Features
+- Variants: \`temporary\`, \`persistent\`, \`permanent\`.
+- Anchors: \`left\`, \`right\`, \`top\`, \`bottom\`.
+- Works with This.GUI theme (via \`GuiProvider\`).
+- Accepts \`sx\` and \`PaperProps\` for styling the surface.
+
+> Note: For \`temporary\` drawers, you control visibility with the \`open\` prop and \`onClose\`.  
+> For \`permanent\` drawers, \`open\` is ignored by MUI; the drawer is always visible.
+
+---
+## Basic usage
+~~~tsx
+import { Drawer } from '@/gui/primitives';
+
+<Drawer anchor="left" variant="temporary" open={open} onClose={() => setOpen(false)}>
+  <div style={{ width: 260, padding: 16 }}>Content</div>
+</Drawer>
+~~~
+
+## Permanent sidebar
+~~~tsx
+<Drawer anchor="left" variant="permanent" PaperProps={{ sx: { width: 260 } }}>
+  <div style={{ width: 260, padding: 16 }}>Navigation</div>
+</Drawer>
+~~~
+
+## Declarative JSON / Config
+~~~json
+{
+  "type": "Drawer",
+  "props": {
+    "variant": "temporary",
+    "anchor": "right",
+    "PaperProps": { "sx": { "width": 300 } },
+    "children": "<YourMenu />"
+  }
+}
+~~~
+
+When used via your registry/resolver, the object above is resolved into a live Drawer with the provided props.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['temporary', 'persistent', 'permanent'],
+    },
+    anchor: {
+      control: { type: 'radio' },
+      options: ['left', 'right', 'top', 'bottom'],
+    },
+    open: {
+      control: { type: 'boolean' },
+      description: 'Only relevant for temporary/persistent variants.',
+    },
+    // Not useful as a control in SB; better shown in examples
+    container: { table: { disable: true } },
+  },
+  args: {
+    variant: 'temporary',
+    anchor: 'left',
+    open: false,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Drawer>;
+
+// ======================= Helpers =======================
+const DemoList = ({ label = 'Menu' }: { label?: string }) => (
+  <Box sx={{ width: 260, p: 2 }}>
+    <Typography variant="subtitle1" sx={{ mb: 1.5 }}>{label}</Typography>
+    <ul style={{ margin: 0, paddingLeft: 16, lineHeight: 1.9 }}>
+      <li><a href="#">Item one</a></li>
+      <li><a href="#">Item two</a></li>
+      <li><a href="#">Item three</a></li>
+    </ul>
+  </Box>
+);
+
+// ======================= Stories =======================
+
+export const Playground: Story = {
+  render: (args) => (
+    <>
+      <Typography variant="body1" sx={{ mb: 1 }}>
+        Toggle <strong>open</strong> in controls (temporary/persistent).
+      </Typography>
+      <Drawer {...args}>
+        <DemoList />
+      </Drawer>
+    </>
+  ),
+};
+
+export const TemporaryWithToggle: Story = {
+  name: 'Temporary (with toggle button)',
+  render: () => {
+    const [open, setOpen] = React.useState(false);
+    return (
+      <>
+        <Button variant="contained" color="primary" onClick={() => setOpen(true)}>
+          Open drawer
+        </Button>
+        <Drawer
+          anchor="left"
+          variant="temporary"
+          open={open}
+          onClose={() => setOpen(false)}
+          ModalProps={{ keepMounted: true }}
+        >
+          <DemoList label="Temporary drawer" />
+        </Drawer>
+      </>
+    );
+  },
+};
+
+export const PermanentLeft: Story = {
+  name: 'Permanent (left)',
+  render: () => (
+    <div style={{ display: 'flex', minHeight: 320 }}>
+      <Drawer
+        anchor="left"
+        variant="permanent"
+        PaperProps={{ sx: { width: 240, position: 'relative' } }}
+      >
+        <DemoList label="Permanent left" />
+      </Drawer>
+      <Box sx={{ flex: 1, p: 2 }}>
+        <Typography variant="h6" sx={{ mb: 1 }}>Content area</Typography>
+        <Typography variant="body2">
+          The permanent drawer is always visible and does not use the <code>open</code> prop.
+        </Typography>
+      </Box>
+    </div>
+  ),
+};
+
+export const RightAnchorTemporary: Story = {
+  name: 'Temporary (right anchor)',
+  render: () => {
+    const [open, setOpen] = React.useState(false);
+    return (
+      <>
+        <Button variant="outlined" onClick={() => setOpen(true)}>
+          Open right drawer
+        </Button>
+        <Drawer
+          anchor="right"
+          variant="temporary"
+          open={open}
+          onClose={() => setOpen(false)}
+          PaperProps={{ sx: { width: 300 } }}
+        >
+          <DemoList label="Right side" />
+        </Drawer>
+      </>
+    );
+  },
+};
+
+export const TopAndBottom: Story = {
+  name: 'Top & bottom anchors',
+  render: () => {
+    const [openTop, setOpenTop] = React.useState(false);
+    const [openBottom, setOpenBottom] = React.useState(false);
+    return (
+      <>
+        <div style={{ display: 'flex', gap: 12, marginBottom: 12 }}>
+          <Button variant="outlined" onClick={() => setOpenTop(true)}>Open top</Button>
+          <Button variant="outlined" onClick={() => setOpenBottom(true)}>Open bottom</Button>
+        </div>
+        <Drawer
+          anchor="top"
+          variant="temporary"
+          open={openTop}
+          onClose={() => setOpenTop(false)}
+          PaperProps={{ sx: { height: 200 } }}
+        >
+          <Box sx={{ p: 2 }}>
+            <Typography variant="subtitle1">Top drawer</Typography>
+          </Box>
+        </Drawer>
+        <Drawer
+          anchor="bottom"
+          variant="temporary"
+          open={openBottom}
+          onClose={() => setOpenBottom(false)}
+          PaperProps={{ sx: { height: 200 } }}
+        >
+          <Box sx={{ p: 2 }}>
+            <Typography variant="subtitle1">Bottom drawer</Typography>
+          </Box>
+        </Drawer>
+      </>
+    );
+  },
+};

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

@@ -0,0 +1,25 @@
+import React from 'react';
+import MuiDrawer from '@mui/material/Drawer';
+export type DrawerProps = React.ComponentProps<typeof MuiDrawer>;
+/**
+ * `Drawer` is a wrapper around MUI's `Drawer` component.
+ *
+ * It provides a consistent drawer interface for side navigation or temporary content containers.
+ * All props from MUI's `Drawer` are forwarded via `DrawerProps`, ensuring type safety and
+ * autocomplete support.
+ *
+ * This component also uses `React.forwardRef` to support ref forwarding for advanced use cases
+ * like controlling the drawer programmatically or integrating with custom animations.
+ *
+ * Example usage:
+ * ```tsx
+ * <Drawer anchor="left" open={open} onClose={handleClose}>
+ *   <List>...</List>
+ * </Drawer>
+ * ```
+ */
+export const Drawer = React.forwardRef<HTMLDivElement, DrawerProps>(function Drawer(props, ref) {
+  return <MuiDrawer ref={ref} {...props} />;
+});
+
+export default Drawer;

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

@@ -0,0 +1,33 @@
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import Grid from './Grid';
+import type { GridResolverSpec } from './Grid.types';
+
+const GridResolver: RegistryEntry = {
+  type: 'Grid',
+  resolve(spec: GridResolverSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const {
+      children,
+      id,
+      className,
+      sx,
+      ...rest
+    } = p;
+
+    const gridId = ensureNodeId('grid', id);
+
+    return (
+      <Grid
+        id={gridId}
+        className={className}
+        sx={sx}
+        {...rest}
+      >
+        {children}
+      </Grid>
+    );
+  },
+};
+
+export default GridResolver;

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

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Grid from './Grid';
+import Box from '@/gui/atoms/Box/Box';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Grid> = {
+  title: 'Atoms/Containers/Grid',
+  component: Grid,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 0, minHeight: 240 }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Grid** atom is a thin wrapper around MUI's \`Grid\` component. It keeps the original API and polymorphism but integrates with **This.GUI** tokens and allows declarative usage via the resolver.
+
+---
+## Features
+- Supports all MUI Grid props like \`container\`, \`item\`, \`spacing\`, \`xs\`, \`sm\`, \`md\`, etc.
+- Fully themeable via **This.GUI** tokens and \`sx\`.
+- Works both as a container and as an item.
+- Can be described declaratively via JSON specs for resolvers.
+
+---
+## Key Props
+- \`container?: boolean\` — defines a grid container.
+- \`item?: boolean\` — defines a grid item.
+- \`spacing?: number | object\` — gap between items (when container).
+- \`xs | sm | md | lg | xl?: number\` — responsive column sizes.
+- \`sx?: object\` — granular styling.
+
+---
+## Basic usage (React)
+~~~tsx
+import { Grid, Box } from '@/gui/atoms';
+
+<Grid container spacing={2}>
+  <Grid item xs={6}>
+    <Box sx={{ backgroundColor: 'primary.main', p: 2, color: '#fff' }}>Item 1</Box>
+  </Grid>
+  <Grid item xs={6}>
+    <Box sx={{ backgroundColor: 'secondary.main', p: 2, color: '#fff' }}>Item 2</Box>
+  </Grid>
+</Grid>
+~~~
+
+---
+## Declarative JSON / Config usage
+This GUI's **resolver** lets you describe a Grid via a config object:
+
+~~~json
+{
+  "type": "Grid",
+  "props": {
+    "container": true,
+    "spacing": 2,
+    "children": [
+      {
+        "type": "Grid",
+        "props": {
+          "item": true,
+          "xs": 6,
+          "children": {
+            "type": "Box",
+            "props": {
+              "sx": { "backgroundColor": "primary.main", "p": 2, "color": "#fff" },
+              "children": "Item 1"
+            }
+          }
+        }
+      },
+      {
+        "type": "Grid",
+        "props": {
+          "item": true,
+          "xs": 6,
+          "children": {
+            "type": "Box",
+            "props": {
+              "sx": { "backgroundColor": "secondary.main", "p": 2, "color": "#fff" },
+              "children": "Item 2"
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+~~~
+
+> The resolver maps this spec to real React elements, preserving polymorphism and \`sx\` styling.
+        `,
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Grid>;
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <Grid {...args} container spacing={2}>
+      <Grid item xs={6}>
+        <Box sx={{ backgroundColor: 'primary.main', p: 2, color: '#fff' }}>Item 1</Box>
+      </Grid>
+      <Grid item xs={6}>
+        <Box sx={{ backgroundColor: 'secondary.main', p: 2, color: '#fff' }}>Item 2</Box>
+      </Grid>
+    </Grid>
+  ),
+};
+
+export const ResponsiveGrid: Story = {
+  render: (args) => (
+    <Grid {...args} container spacing={2}>
+      <Grid item xs={12} sm={6} md={4}>
+        <Box sx={{ backgroundColor: 'info.main', p: 2, color: '#fff' }}>xs=12 sm=6 md=4</Box>
+      </Grid>
+      <Grid item xs={12} sm={6} md={4}>
+        <Box sx={{ backgroundColor: 'success.main', p: 2, color: '#fff' }}>xs=12 sm=6 md=4</Box>
+      </Grid>
+      <Grid item xs={12} sm={12} md={4}>
+        <Box sx={{ backgroundColor: 'warning.main', p: 2, color: '#fff' }}>xs=12 sm=12 md=4</Box>
+      </Grid>
+    </Grid>
+  ),
+  name: 'Responsive Grid Layout',
+};

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

@@ -0,0 +1,15 @@
+// File: Grid.tsx
+import MuiGrid from '@mui/material/Grid';
+import type { GridProps } from './Grid.types';
+
+/**
+ * This.GUI — Grid
+ * Wrapper around MUI’s Grid that preserves props & typing.
+ * 
+ * Purpose:
+ * - Consistent namespace integration (This.GUI).
+ * - Supports full MUI Grid props including `sx`, `container`, `item`, etc.
+ */
+const Grid = MuiGrid;
+(Grid as any).displayName = 'Gui.Grid';
+export default Grid;

package/src/gui/components/atoms/Grid/Grid.types.ts

@@ -0,0 +1,9 @@
+import MuiGrid from '@mui/material/Grid';
+import type { GridProps as MuiGridProps } from '@mui/material/Grid';
+export type GridProps = React.ComponentProps<typeof MuiGrid> & MuiGridProps;
+
+export type GridResolverSpec = {
+  type: 'Grid';
+  props?: GridProps; // or GridProps if you want to alias it
+};
+

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

@@ -0,0 +1,137 @@
+// src/gui/atoms/IconButton/IconButton.resolver.tsx
+import * as React from 'react';
+import IconButton from './IconButton';
+import Icon from '@/gui/Theme/Icon/Icon';
+import Link from '@/gui/atoms/Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative resolver for IconButton
+ * -----------------------------------
+ * - Forwards all MUI IconButton props faithfully.
+ * - Supports polymorphism via `component` / `as`.
+ * - Adds sugar:
+ *    • `icon` string → rendered through our Icon registry (mui:/lucide: tokens), normalized to lowercase.
+ *    • Routing helpers: if `to` w/o `component` → uses This.GUI `Link`; if `href`/`external` → uses anchor with safe target/rel.
+ * - Provides granular styling via `sx` (root) and optional `iconSx`.
+ *
+ * A11y note: when rendering only an icon (no visible text), pass an `aria-label`.
+ */
+export type IconButtonSpec = {
+  type: 'IconButton';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism
+    component?: any;
+    as?: any; // alias for component
+
+    // Routing sugar
+    to?: string;
+    href?: string;
+    external?: boolean;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+
+    // Sugar: icon may be a token or a node
+    icon?: string | React.ReactNode;
+    iconProps?: Record<string, any>;
+
+    // MUI props passthrough (subset; others go via index signature)
+    color?:
+      | 'inherit'
+      | 'default'
+      | 'primary'
+      | 'secondary'
+      | 'success'
+      | 'error'
+      | 'info'
+      | 'warning';
+    size?: 'small' | 'medium' | 'large';
+    edge?: 'start' | 'end' | false;
+    disabled?: boolean;
+
+    // Styling
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough (MUI will validate)
+    [key: string]: any;
+  };
+};
+
+const IconButtonResolver: RegistryEntry = {
+  type: 'IconButton',
+  resolve(spec: IconButtonSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const nodeId = ensureNodeId('iconbutton', p.id as string | undefined);
+
+    // Decide polymorphic target
+    const component =
+      p.component ??
+      p.as ??
+      (p.to ? Link : (p.href || 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 }
+        : {};
+
+    // Prepare children (icon sugar)
+    const { children, icon, iconProps } = p;
+    const normalizedToken =
+      typeof icon === 'string' ? icon.trim() : null;
+
+    const effectiveChildren =
+      children ??
+      (normalizedToken ? (
+        <Icon
+          name={normalizedToken}
+          {...(iconProps || {})}
+        />
+      ) : (
+        icon ?? null
+      ));
+
+    // Collect & strip resolver-only keys so they don't leak to DOM
+    const {
+      as: _as,
+      to: _to,
+      href: _href,
+      external: _external,
+      target: _target,
+      rel: _rel,
+      icon: _icon,
+      iconSx: _iconSx,
+      iconProps: _iconProps,
+      ...rest
+    } = p;
+
+    return (
+      <IconButton
+        {...(component ? { component } : {})}
+        sx={p.sx}
+        className={p.className}
+        id={nodeId}
+        data-testid={p['data-testid']}
+        {...routingProps}
+        {...rest}
+      >
+        {effectiveChildren}
+      </IconButton>
+    );
+  },
+};
+
+export default IconButtonResolver;