this.gui 1.3.40 → 1.3.42

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

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import CardHeader from './CardHeader';
+import Avatar from '@mui/material/Avatar';
+import IconButton from '@mui/material/IconButton';
+import Icon from '@/gui/Theme/Icon/Icon';
+
+const meta: Meta<typeof CardHeader> = {
+  title: 'Atoms/Organization/Card/CardHeader',
+  component: CardHeader,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof CardHeader>;
+
+export const BasicHeader: Story = {
+  render: () => (
+    <CardHeader
+      title="Card Title"
+      subheader="September 20, 2025"
+    />
+  ),
+  name: 'Basic Header',
+};
+
+export const WithAvatarAndAction: Story = {
+  render: () => (
+    <CardHeader
+      avatar={<Avatar aria-label="recipe">R</Avatar>}
+      action={
+        <IconButton aria-label="settings">
+          <Icon name="more_vert" />
+        </IconButton>
+      }
+      title="Shrimp and Chorizo Paella"
+      subheader="September 20, 2025"
+    />
+  ),
+  name: 'Header with Avatar and Action',
+};

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

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import MuiCardHeader from '@mui/material/CardHeader';
+
+/**
+ * This.GUI — CardHeader (atom)
+ * Thin wrapper around MUI’s CardHeader that preserves props & typing.
+ * Useful for defining title, subheader, and action areas in cards with consistent API.
+ */
+const CardHeader = MuiCardHeader;
+export type CardHeaderProps = React.ComponentProps<typeof CardHeader>;
+(CardHeader as any).displayName = 'Gui.CardHeader';
+export default CardHeader;

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

@@ -0,0 +1,85 @@
+// src/gui/atoms/Collapse/Collapse.resolver.tsx
+import * as React from 'react';
+import Collapse from './Collapse';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { TransitionProps } from '@mui/material/transitions';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative resolver for Collapse
+ * ---------------------------------
+ * Fidelity
+ * - Forwards MUI props faithfully (in, orientation, collapsedSize, timeout, easing, unmountOnExit, etc.).
+ * - Supports polymorphism via `component` (and alias `as`).
+ * - Provides granular styling through `sx` on the root.
+ *
+ * Usage (declarative JSON):
+ * {
+ *   "type": "Collapse",
+ *   "props": {
+ *     "in": true,
+ *     "orientation": "vertical",
+ *     "sx": { "border": "1px dashed", "borderColor": "divider" }
+ *   }
+ * }
+ */
+export type CollapseSpec = {
+  type: 'Collapse';
+  props?: {
+    children?: React.ReactNode;
+
+    // Note: MUI Collapse's `component` must be a React component (not a string tag) due to Transition typing.
+    component?: React.ElementType<TransitionProps>;
+    as?: any; // alias of component
+
+    // Core MUI props (subset; others passthrough)
+    in?: boolean;
+    orientation?: 'vertical' | 'horizontal';
+    collapsedSize?: number | string;
+    timeout?: 'auto' | number | { appear?: number; enter?: number; exit?: number };
+    easing?: string | { enter?: string; exit?: string };
+    unmountOnExit?: boolean;
+    mountOnEnter?: boolean;
+    appear?: boolean;
+
+    // Styling
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const CollapseResolver: RegistryEntry = {
+  type: 'Collapse',
+  resolve(spec: CollapseSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const { children, as: _as, component: _component, ...rest } = p;
+    // Collapse's `component` must be a React component (not a string tag), otherwise TS will error.
+    const rawComponent = _component ?? _as;
+    const component = (typeof rawComponent === 'string'
+      ? undefined
+      : (rawComponent as React.ElementType<TransitionProps>)) as React.ElementType<TransitionProps> | undefined;
+
+    // Guarantee a stable, prefixed id for editor tooling
+    const collapseId = ensureNodeId('collapse', p.id);
+    return (
+      <Collapse
+        {...(component ? { component: component as React.ElementType<TransitionProps> } : {})}
+        sx={p.sx}
+        className={p.className}
+        id={collapseId}
+        data-testid={p['data-testid']}
+        {...rest}
+      >
+        {children}
+      </Collapse>
+    );
+  },
+};
+
+export default CollapseResolver;

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

@@ -0,0 +1,130 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Collapse from './Collapse';
+
+const meta: Meta<typeof Collapse> = {
+  title: 'Atoms/Content/Collapse',
+  component: Collapse,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 220 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Collapse** atom is a thin wrapper around MUI's \`MuiCollapse\`, staying faithful to its API and polymorphism.
+
+In **declarative** mode (resolver), it forwards MUI props as-is and supports granular styling via \`sx\` on the root.
+
+---
+## React usage
+~~~jsx
+const [open, setOpen] = React.useState(true);
+
+<Collapse in={open}>
+  <div style={{ padding: 12, border: '1px solid var(--mui-palette-divider)', borderRadius: 8 }}>
+    Collapsible content
+  </div>
+</Collapse>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "Collapse",
+  "props": {
+    "in": true,
+    "orientation": "vertical",
+    "sx": { "border": "1px dashed", "borderColor": "divider", "p": 1 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children', 'as', 'timeout', 'easing'],
+    },
+  },
+  argTypes: {
+    in: { control: 'boolean', description: 'Show/Hide content' },
+    orientation: { control: { type: 'radio' }, options: ['vertical', 'horizontal'] },
+    collapsedSize: { control: 'text', description: 'number or CSS size' },
+    unmountOnExit: { control: 'boolean' },
+    mountOnEnter: { control: 'boolean' },
+    appear: { control: 'boolean' },
+    sx: { control: 'object' },
+  },
+  args: {
+    in: true,
+    orientation: 'vertical',
+    collapsedSize: 0,
+    unmountOnExit: false,
+    mountOnEnter: false,
+    appear: false,
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Collapse>;
+
+const DemoBlock: React.FC<{ label?: string } & React.HTMLAttributes<HTMLDivElement>> = ({ label = 'Collapsible content', ...rest }) => (
+  <div
+    {...rest}
+    style={{
+      padding: 12,
+      border: '1px solid var(--mui-palette-divider)',
+      borderRadius: 8,
+      background: 'var(--mui-palette-background-paper)',
+      ...rest.style,
+    }}
+  >
+    {label}
+  </div>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => <Collapse {...args}><DemoBlock /></Collapse>,
+};
+
+export const Horizontal: Story = {
+  args: { orientation: 'horizontal', in: true, collapsedSize: 0 },
+  render: (args) => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+      <Collapse {...args}>
+        <DemoBlock label="Horizontal content" style={{ width: 240 }} />
+      </Collapse>
+      <span style={{ opacity: 0.7, fontSize: 12 }}>(Try toggling the \"in\" control)</span>
+    </div>
+  ),
+};
+
+export const WithSx: Story = {
+  args: { sx: { border: '1px dashed', borderColor: 'divider', p: 1 } },
+  render: (args) => (
+    <Collapse {...args}>
+      <DemoBlock label="Styled via sx on Collapse" />
+    </Collapse>
+  ),
+};
+
+export const UnmountOnExit: Story = {
+  args: { unmountOnExit: true, in: false },
+  render: (args) => (
+    <div>
+      <p style={{ margin: 0, opacity: 0.75 }}>Content is removed from the DOM when closed.</p>
+      <Collapse {...args}>
+        <DemoBlock label="Unmounts when closed" />
+      </Collapse>
+    </div>
+  ),
+};

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