this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,109 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Divider, Box, Typography, Stack } from '@/gui/atoms';
+
+const meta: Meta<typeof Divider> = {
+  title: 'Atoms/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/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/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/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/atoms/Drawer/Drawer.stories.tsx

@@ -0,0 +1,229 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Drawer, Box, Button, Typography } from '@/gui/atoms';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+// ======================= Meta =======================
+const meta: Meta<typeof Drawer> = {
+  title: 'Atoms/Drawer',
+  component: Drawer,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 320 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  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/atoms/Drawer/Drawer.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+import MuiDrawer from '@mui/material/Drawer';
+export type DrawerProps = React.ComponentProps<typeof MuiDrawer>;
+export const Drawer = React.forwardRef<HTMLDivElement, DrawerProps>(function Drawer(props, ref) {
+  return <MuiDrawer ref={ref} {...props} />;
+});
+
+export default Drawer;

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

@@ -0,0 +1,135 @@
+// src/gui/atoms/IconButton/IconButton.resolver.tsx
+import * as React from 'react';
+import IconButton from './IconButton';
+import Icon from '@/themes/icons/Icon';
+import Link from '../Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/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;
+    iconSx?: SxProps<Theme>;
+    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, iconSx, iconProps } = p;
+    const normalizedToken =
+      typeof icon === 'string' ? icon.trim().toLowerCase() : null;
+
+    const effectiveChildren =
+      children ??
+      (normalizedToken ? (
+        <Icon name={normalizedToken} sx={iconSx} {...(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;