this.gui 1.3.24 → 1.3.26

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

@@ -0,0 +1,17 @@
+/**
+ * This.GUI — Collapse
+ * Thin wrapper around MUI’s Collapse that preserves props & typing.
+ *
+ * Fidelity
+ * - Directly re-exports MUI’s component so behavior/typing remain intact.
+ * - No custom logic; consumers keep using it exactly like MUI.
+ *
+ * Styling / Granular control
+ * - Supports MUI System styling via props exposed by MUI (e.g. `sx` on slots where applicable).
+ */
+import * as React from 'react';
+import MuiCollapse from '@mui/material/Collapse';
+const Collapse = MuiCollapse;
+export type CollapseProps = React.ComponentProps<typeof Collapse>;
+(Collapse as any).displayName = 'Gui.Collapse';
+export default Collapse;

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

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import { Divider } from '@/gui/components/atoms';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * DividerResolver — declarative adapter for MUI Divider
+ *
+ * Fidelity
+ * - Forwards MUI props faithfully (orientation, flexItem, light, variant, textAlign, etc.).
+ * - Supports polymorphism via `component` (and alias `as`) when compatible with MUI Divider.
+ * - Granular styling via `sx` on the root Divider.
+ *
+ * Sugar
+ * - `text`: convenience for inline content (maps to children). If both `children` and `text`
+ *   are provided, `children` takes precedence.
+ *
+ * JSON example:
+ * {
+ *   "type": "Divider",
+ *   "props": {
+ *     "orientation": "vertical",
+ *     "flexItem": true,
+ *     "text": "OR",
+ *     "sx": { "borderColor": "primary.main" }
+ *   }
+ * }
+ */
+export type DividerSpec = {
+  type: 'Divider';
+  props?: {
+    // Content
+    children?: React.ReactNode;
+    text?: React.ReactNode; // convenience alias for children
+
+    // Polymorphism
+    component?: React.ElementType | string;
+    as?: React.ElementType | string; // alias for component
+
+    // Common MUI Divider props (subset; passthrough handles the rest)
+    orientation?: 'horizontal' | 'vertical';
+    flexItem?: boolean;
+    light?: boolean;
+    variant?: 'fullWidth' | 'inset' | 'middle';
+    textAlign?: 'center' | 'left' | 'right';
+
+    // Styling & misc
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const DividerResolver: RegistryEntry = {
+  type: 'Divider',
+  resolve(spec: DividerSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    // Extract and sanitize resolver-only fields so they don't leak to DOM
+    const {
+      children,
+      text,
+      as: _as,
+      component: _component,
+      sx,
+      className,
+      id,
+      'data-testid': dataTestId,
+      ...rest
+    } = p;
+
+    const component = (_component ?? _as) as React.ElementType | string | undefined;
+    const content = children ?? text ?? undefined;
+    const dividerId = ensureNodeId('divider', id);
+
+    return (
+      <Divider
+        {...(component ? { component } : {})}
+        sx={sx}
+        className={className}
+        id={dividerId}
+        data-testid={dataTestId}
+        {...rest}
+      >
+        {content}
+      </Divider>
+    );
+  },
+};
+
+export default DividerResolver;

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

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Divider, Box, Typography, Stack } from '@/gui/components/atoms';
+
+const meta: Meta<typeof Divider> = {
+  title: 'Atoms/Content/Divider',
+  component: Divider,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The Divider component is a thin wrapper over MUI\'s `MuiDivider`. It preserves all props and allows styling via the `sx` prop.',
+      },
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: { type: 'radio' },
+      options: ['horizontal', 'vertical'],
+      description: 'The divider orientation.',
+    },
+    variant: {
+      control: { type: 'radio' },
+      options: ['fullWidth', 'inset', 'middle'],
+      description: 'The variant to use.',
+    },
+    flexItem: {
+      control: { type: 'boolean' },
+      description: 'If true, the divider is a flex item.',
+    },
+  },
+  args: {
+    orientation: 'horizontal',
+    variant: 'fullWidth',
+    flexItem: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Divider>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Stack spacing={2} sx={{ width: 300 }}>
+      <Typography>Item One</Typography>
+      <Divider {...args} />
+      <Typography>Item Two</Typography>
+      <Divider {...args} />
+      <Typography>Item Three</Typography>
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates the Divider component with customizable props in a vertical stack.',
+      },
+    },
+  },
+};
+
+export const VerticalDivider: Story = {
+  render: () => (
+    <Stack direction="row" spacing={2} alignItems="center" sx={{ height: 100 }}>
+      <Typography>Left</Typography>
+      <Divider orientation="vertical" flexItem />
+      <Typography>Right</Typography>
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Shows a vertical divider between two items in a horizontal stack.',
+      },
+    },
+  },
+};
+
+export const InsetDivider: Story = {
+  render: () => (
+    <Stack spacing={2} sx={{ width: 300 }}>
+      <Typography>First</Typography>
+      <Divider variant="inset" />
+      <Typography>Second</Typography>
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates the inset variant of the Divider between text items.',
+      },
+    },
+  },
+};
+
+export const TextDivider: Story = {
+  render: () => (
+    <Box sx={{ width: 300 }}>
+      <Divider>Text Content</Divider>
+    </Box>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Shows a divider with text content in the middle.',
+      },
+    },
+  },
+};

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

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import MuiDivider from '@mui/material/Divider';
+/**
+ * This.GUI — Divider (atom)
+ * Thin wrapper around MUI's Divider. Keeps the API stable under our namespace
+ * while preserving all props, including `sx`.
+ */
+export type DividerProps = React.ComponentProps<typeof MuiDivider>;
+const Divider = React.forwardRef<HTMLHRElement, DividerProps>(function Divider(props, ref) {
+  return <MuiDivider ref={ref} {...props} />;
+});
+
+(Divider as any).displayName = 'Divider';
+export default Divider;

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

@@ -0,0 +1,116 @@
+// src/gui/atoms/Drawer/Drawer.resolver.tsx
+import * as React from 'react';
+import { Drawer } from '@/gui/components/atoms';
+import type { RegistryEntry } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative resolver for Drawer
+ *
+ * Goals
+ * - Stay faithful to MUI props.
+ * - Add ergonomic sugar for JSON-driven UIs (width → PaperProps.sx.width, paperSx merge, content alias, keepMounted).
+ * - Keep types helpful (SxProps<Theme> where relevant).
+ *
+ * Notes
+ * - We deliberately DO NOT update layout insets here. That responsibility belongs to higher-level layout components.
+ */
+type DrawerSpec = {
+  type: 'Drawer';
+  props?: {
+    // Behavior & placement
+    variant?: 'temporary' | 'persistent' | 'permanent';
+    anchor?: 'left' | 'right' | 'top' | 'bottom';
+    open?: boolean; // if omitted in declarative JSON, default to false
+    /**
+     * Accept either MUI's full signature or a simple no-arg callback for declarative specs.
+     * In runtime, if a no-arg function is provided, we wrap it into MUI's signature.
+     */
+    onClose?: ((event: object, reason: 'backdropClick' | 'escapeKeyDown') => void) | (() => void);
+
+    // Styling
+    width?: number;                 // shortcut → merged into PaperProps.sx.width
+    sx?: SxProps<Theme>;            // root sx
+    PaperProps?: any;               // will be merged; sx merged with width/paperSx
+    paperSx?: SxProps<Theme>;       // optional convenience to add to Paper sx
+
+    // Container/Portal & Modal behavior (temporary/persistent)
+    container?: Element | (() => Element) | null;
+    ModalProps?: any;
+    keepMounted?: boolean;          // shorthand → ModalProps.keepMounted = true
+
+    // Content
+    children?: React.ReactNode;
+    content?: React.ReactNode;
+
+    // Misc
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+
+    // passthrough
+    [key: string]: any;
+  };
+};
+
+const DrawerResolver: RegistryEntry = {
+  type: 'Drawer',
+  resolve(spec: DrawerSpec) {
+    const p = spec.props ?? {};
+
+    // Merge Paper sx with `width` and optional `paperSx`
+    const mergedPaperSx = {
+      ...(typeof p.width === 'number' ? { width: p.width } : {}),
+      ...(p.paperSx ?? {}),
+      ...(p.PaperProps?.sx ?? {}),
+    };
+
+    const PaperProps = {
+      ...(p.PaperProps ?? {}),
+      ...(Object.keys(mergedPaperSx).length ? { sx: mergedPaperSx } : {}),
+    };
+
+    // ModalProps (support keepMounted shorthand and preserve provided values)
+    const ModalProps =
+      p.keepMounted != null
+        ? { ...(p.ModalProps ?? {}), keepMounted: p.keepMounted }
+        : p.ModalProps;
+
+    // Normalize onClose: support no-arg functions from declarative JSON
+    let onCloseProp: ((event: object, reason: 'backdropClick' | 'escapeKeyDown') => void) | undefined;
+    if (typeof p.onClose === 'function') {
+      onCloseProp = (event: object, reason: 'backdropClick' | 'escapeKeyDown') => {
+        // If the provided function expects no arguments (JSON sugar), just call it.
+        if ((p.onClose as Function).length === 0) {
+          (p.onClose as () => void)();
+          return;
+        }
+        // Otherwise, forward MUI's (event, reason)
+        (p.onClose as (event: object, reason: 'backdropClick' | 'escapeKeyDown') => void)(event, reason);
+      };
+    }
+
+    const children = p.children ?? p.content ?? null;
+
+    return (
+      <Drawer
+        variant={p.variant ?? 'temporary'}
+        anchor={p.anchor ?? 'left'}
+        open={p.open ?? false}
+        onClose={onCloseProp}
+        PaperProps={PaperProps}
+        ModalProps={ModalProps}
+        container={p.container}
+        sx={p.sx}
+        id={ensureNodeId('drawer', p.id)}
+        className={p.className}
+        data-testid={p['data-testid']}
+      >
+        {children}
+      </Drawer>
+    );
+  },
+};
+
+export default DrawerResolver;

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 '@/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;