this.gui 1.3.40 → 1.3.42

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

@@ -0,0 +1,219 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button, Link } from '@/gui/components/atoms';
+import Icon from '@/gui/Theme/Icon/Icon';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Button> = {
+  title: 'Atoms/Forms & Inputs/Button',
+  component: Button,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Button** primitive is a thin wrapper around MUI's \`MuiButton\` that preserves **polymorphism** and adds **declarative icons** (string tokens like 
+\`mui:Send\` or \`lucide:bolt\`). It integrates with **This.GUI** theming and respects your token-built palette.
+
+---
+## Features
+- Variants: \`contained\`, \`outlined\`, \`text\`.
+- Colors: \`primary\`, \`secondary\`, \`success\`, \`info\`, \`warning\`, \`error\`, \`inherit\`.
+- Sizes: \`small\`, \`medium\`, \`large\`.
+- **Icons** via tokens (\`startIcon\` / \`endIcon\`) or React nodes.
+- **Polymorphic**: \`component\` can be \`'a'\` or a Link (e.g. the This.GUI wrapper \`Link\`) for routing.
+- Respects your theme from \`GuiProvider\` (no need to wrap with \`ThemeProvider\`).
+
+---
+## Key Props
+- \`startIcon?: string | ReactNode\` — accepts a name from the **icon registry** (\`mui:*\` / \`lucide:*\`) or a React element.
+- \`endIcon?: string | ReactNode\`.
+- \`component?: ElementType | string\` — for polymorphism (\`'a'\`, RouterLink, etc.).
+- \`href?: string\` — when \`component='a'\`.
+- \`to?: string\` — when \`component={Link}\`.
+
+> Note: \`to\` and \`href\` are not exposed as Storybook controls because they only apply in specific modes; they are shown in dedicated stories.
+
+---
+## Basic usage
+~~~jsx
+import { Button } from '@/gui/primitives';
+
+<Button variant="contained" color="primary">Save</Button>
+<Button variant="outlined" color="secondary">Cancel</Button>
+<Button variant="text">Learn more</Button>
+~~~
+
+## With declarative icons
+~~~jsx
+<Button variant="contained" color="secondary" startIcon="mui:Send" endIcon="lucide:bolt">
+  Send
+</Button>
+~~~
+
+## As native anchor link
+~~~jsx
+<Button component="a" href="https://neurons.me" /* target="_blank" rel="noreferrer" */>
+  Visit neurons.me
+</Button>
+~~~
+
+## With RouterLink (This.GUI Link)
+~~~jsx
+import { Button, Link } from '@/gui/primitives';
+
+<Button component={Link} to="/docs">Go to docs</Button>
+~~~
+## Declarative JSON / Config usage
+~~~json
+{
+  "type": "Button",
+  "props": {
+    "variant": "text",
+    "color": "primary",
+    "component": "a",
+    "href": "https://neurons.me",
+    "target": "_blank",
+    "rel": "noreferrer",
+    "children": "Visit neurons.me"
+  }
+}
+~~~
+
+Another example with a RouterLink:
+~~~json
+{
+  "type": "Button",
+  "props": {
+    "variant": "contained",
+    "color": "secondary",
+    "component": "Link",
+    "to": "/docs",
+    "startIcon": "mui:Send",
+    "children": "Go to docs"
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['contained', 'outlined', 'text'],
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'inherit'],
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['small', 'medium', 'large'],
+    },
+    startIcon: { control: 'text', description: 'Icon token or a React element.' },
+    endIcon: { control: 'text', description: 'Icon token or a React element.' },
+    onClick: { action: 'clicked' },
+  },
+  args: {
+    variant: 'contained',
+    color: 'primary',
+    size: 'medium',
+    children: 'Click me',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  args: { color: 'primary' },
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Button {...args} variant="contained">Contained</Button>
+      <Button {...args} variant="outlined">Outlined</Button>
+      <Button {...args} variant="text">Text</Button>
+    </div>
+  ),
+};
+
+export const Colors: Story = {
+  args: { variant: 'contained' },
+  render: (args) => {
+    const colors: Array<'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error'> =
+      ['primary', 'secondary', 'success', 'info', 'warning', 'error'];
+    return (
+      <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+        {colors.map((c) => (
+          <Button key={c} {...args} color={c}>
+            {c[0].toUpperCase() + c.slice(1)}
+          </Button>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  args: { color: 'primary', variant: 'contained' },
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
+      <Button {...args} size="small">Small</Button>
+      <Button {...args} size="medium">Medium</Button>
+      <Button {...args} size="large">Large</Button>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  args: {
+    variant: 'contained',
+    color: 'secondary',
+    startIcon: <Icon name="Power" />,
+    endIcon: <Icon name="bolt" />,
+    children: 'Send',
+  },
+};
+
+export const PolymorphicAnchor: Story = {
+  args: {
+    variant: 'text',
+    color: 'primary',
+    children: 'Go to neurons.me',
+  },
+  render: (args) => (
+    <Button component="a" href="https://neurons.me">
+      {args.children}
+    </Button>
+  ),
+};
+
+export const PolymorphicRouterLink: Story = {
+  args: {
+    variant: 'text',
+    color: 'primary',
+    children: 'Go to /docs',
+  },
+  render: (args) => (
+    <Button component={Link} to="/docs">
+      {args.children}
+    </Button>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { variant: 'contained', color: 'primary', disabled: true, children: 'Disabled' },
+};
+
+export const FullWidth: Story = {
+  args: { variant: 'contained', color: 'primary', fullWidth: true, children: 'Full Width' },
+};

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

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import MuiButton from '@mui/material/Button';
+import type { OverridableComponent } from '@mui/material/OverridableComponent';
+import type { ButtonTypeMap } from '@mui/material/Button';
+import type { ButtonProps as MuiButtonProps } from '@mui/material/Button';
+import Icon from '@/gui/Theme/Icon/Icon';
+/**
+ * Button (This.GUI primitive)
+ * ----------------------------------------
+ * - Polymorphic: preserves MUI's `component` API and typing via OverridableComponent.
+ * - Enhances MUI by allowing `startIcon` / `endIcon` to be a declarative string
+ *   (e.g., "mui:Settings" / "lucide:camera") or a ReactNode.
+ */
+// Polymorphic props type that matches MUI Button while letting us tweak icon props
+export type Iconish = ReactNode | string | undefined;
+export type ButtonProps = Omit<MuiButtonProps, 'startIcon' | 'endIcon'> & {
+  startIcon?: Iconish;
+  endIcon?: Iconish;
+};
+function resolveIcon(node: Iconish): ReactNode | null {
+  if (!node) return null;
+  return typeof node === 'string' ? <Icon name={node} fontSize={18} /> : node;
+}
+const ButtonImpl = React.forwardRef<any, ButtonProps>(function Button(
+  { startIcon, endIcon, ...rest },
+  ref
+) {
+  return (
+    <MuiButton
+      ref={ref}
+      startIcon={resolveIcon(startIcon)}
+      endIcon={resolveIcon(endIcon)}
+      {...rest}
+    />
+  );
+}) as unknown as OverridableComponent<ButtonTypeMap<{}, 'button'>>;
+(ButtonImpl as any).displayName = 'Button';
+export default ButtonImpl;
+export type GuiButtonProps = React.ComponentProps<typeof ButtonImpl>;

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

@@ -0,0 +1,63 @@
+import * as React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import Card from './Card';
+
+/**
+ * Declarative resolver for Card
+ * -----------------------------
+ * - Faithfully wraps MUI's Card.
+ * - Supports standard props like `variant`, `elevation`, `sx`, etc.
+ * - `children` maps directly to content inside the Card.
+ * - Supports polymorphic `component` prop and alias `as`.
+ */
+export type CardSpec = {
+  type: 'Card';
+  props?: {
+    children?: React.ReactNode;
+    variant?: 'elevation' | 'outlined';
+    raised?: boolean;
+    elevation?: number;
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    component?: React.ElementType;
+    as?: React.ElementType;
+    [key: string]: any;
+  };
+};
+
+const CardResolver: RegistryEntry = {
+  type: 'Card',
+  resolve(spec: CardSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const {
+      children,
+      id,
+      className,
+      sx,
+      component,
+      as,
+      ...rest
+    } = p;
+
+    const resolvedComponent = component ?? as;
+    const cardId = ensureNodeId('card', id);
+
+    return (
+      <Card
+        {...(resolvedComponent ? { component: resolvedComponent } : {})}
+        id={cardId}
+        className={className}
+        sx={sx}
+        {...rest}
+      >
+        {children}
+      </Card>
+    );
+  },
+};
+
+export default CardResolver;

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

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Card from './Card';
+import Typography from '@mui/material/Typography';
+
+const meta: Meta<typeof Card> = {
+  title: 'Atoms/Organization/Card/Card',
+  component: Card,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const BasicCard: Story = {
+  render: () => (
+    <Card sx={{ p: 2 }}>
+      <Typography variant="h6" gutterBottom>
+        Basic Card
+      </Typography>
+      <Typography variant="body2">
+        This is a simple card using the GUI Card atom. It supports all typical MUI props.
+      </Typography>
+    </Card>
+  ),
+  name: 'Basic Card',
+};
+
+export const OutlinedCard: Story = {
+  render: () => (
+    <Card variant="outlined" sx={{ p: 2 }}>
+      <Typography variant="h6" gutterBottom>
+        Outlined Card
+      </Typography>
+      <Typography variant="body2">
+        This card uses the `variant="outlined"` prop for a border style.
+      </Typography>
+    </Card>
+  ),
+  name: 'Outlined Card',
+};
+
+export const RaisedCard: Story = {
+  render: () => (
+    <Card raised sx={{ p: 2 }}>
+      <Typography variant="h6" gutterBottom>
+        Raised Card
+      </Typography>
+      <Typography variant="body2">
+        Raised cards use elevation to create visual depth.
+      </Typography>
+    </Card>
+  ),
+  name: 'Raised Card',
+};

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

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import MuiCard from '@mui/material/Card';
+/**
+ * This.GUI — Card (atom)
+ * Wrapper around MUI’s Card that preserves props & typing.
+ *
+ * - Full support for MUI’s props and styling (`sx`, `elevation`, `variant`, etc.).
+ * - No behavior changes; designed to keep consistent with the This.GUI atom model.
+ */
+const Card = MuiCard;
+export type CardProps = React.ComponentProps<typeof Card>;
+(Card as any).displayName = 'Gui.Card';
+export default Card;

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

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import CardActions from './CardActions';
+
+/**
+ * Declarative resolver for CardActions
+ *
+ * - Preserves MUI fidelity: `disableSpacing`, `sx`, and any pass-through props.
+ * - Supports polymorphism via `component` or `as`.
+ * - Accepts children and standard layout styling.
+ */
+export type CardActionsSpec = {
+  type: 'CardActions';
+  props?: {
+    children?: React.ReactNode;
+    disableSpacing?: boolean;
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    component?: React.ElementType;
+    as?: React.ElementType;
+    [key: string]: any;
+  };
+};
+
+const CardActionsResolver: RegistryEntry = {
+  type: 'CardActions',
+  resolve(spec: CardActionsSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const {
+      children,
+      sx,
+      className,
+      id,
+      component,
+      as,
+      ...rest
+    } = p;
+    const resolvedComponent = component ?? as;
+    const actionsId = ensureNodeId('cardActions', id);
+    return (
+      <CardActions
+        sx={sx}
+        className={className}
+        id={actionsId}
+        data-testid={p['data-testid']}
+        {...(resolvedComponent ? { component: resolvedComponent } : {})}
+        {...rest}
+      >
+        {children}
+      </CardActions>
+    );
+  },
+};
+
+export default CardActionsResolver;

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

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import CardActions from './CardActions';
+import Button from '@/gui/atoms/Button/Button';
+
+const meta: Meta<typeof CardActions> = {
+  title: 'Atoms/Organization/Card/CardActions',
+  component: CardActions,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof CardActions>;
+
+export const BasicActions: Story = {
+  render: () => (
+    <CardActions>
+      <Button>Cancel</Button>
+      <Button variant="contained" color="primary">Submit</Button>
+    </CardActions>
+  ),
+  name: 'Basic Actions',
+};
+
+export const WithSpacingDisabled: Story = {
+  render: () => (
+    <CardActions disableSpacing>
+      <Button>Back</Button>
+      <Button variant="outlined">Next</Button>
+    </CardActions>
+  ),
+  name: 'Actions without spacing',
+};

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

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import MuiCardActions from '@mui/material/CardActions';
+
+/**
+ * This.GUI — CardActions (atom)
+ * Thin wrapper around MUI’s CardActions.
+ *
+ * - Preserves all props from MUI.
+ * - Supports polymorphism, `sx`, layout spacing, and children.
+ */
+const CardActions = MuiCardActions;
+export type CardActionsProps = React.ComponentProps<typeof CardActions>;
+(CardActions as any).displayName = 'Gui.CardActions';
+export default CardActions;

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

@@ -0,0 +1,60 @@
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import CardContent from './CardContent';
+
+/**
+ * Declarative resolver for CardContent
+ *
+ * Maps JSON-friendly specs into a GUI-compatible CardContent wrapper.
+ * - Passes through `children`, `sx`, `className`, `id`, and `component`/`as`.
+ * - Allows custom styling and polymorphic rendering.
+ */
+export type CardContentSpec = {
+  type: 'CardContent';
+  props?: {
+    children?: React.ReactNode;
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    component?: React.ElementType;
+    as?: React.ElementType;
+    [key: string]: any;
+  };
+};
+
+const CardContentResolver: RegistryEntry = {
+  type: 'CardContent',
+  resolve(spec: CardContentSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const {
+      children,
+      sx,
+      className,
+      id,
+      component,
+      as,
+      ...rest
+    } = p;
+
+    const contentId = ensureNodeId('cardContent', id);
+    const resolvedComponent = component ?? as;
+
+    return (
+      <CardContent
+        sx={sx}
+        className={className}
+        id={contentId}
+        data-testid={p['data-testid']}
+        {...(resolvedComponent ? { component: resolvedComponent } : {})}
+        {...rest}
+      >
+        {children}
+      </CardContent>
+    );
+  },
+};
+
+export default CardContentResolver;

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

@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import CardContent from './CardContent';
+import Typography from '@mui/material/Typography';
+const meta: Meta<typeof CardContent> = {
+  title: 'Atoms/Organization/Card/CardContent',
+  component: CardContent,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof CardContent>;
+
+export const BasicContent: Story = {
+  render: () => (
+    <CardContent>
+      <Typography variant="body1">
+        This is the main content area inside a card. You can place any children here.
+      </Typography>
+    </CardContent>
+  ),
+  name: 'Basic CardContent',
+};
+
+export const WithPaddingAndText: Story = {
+  render: () => (
+    <CardContent sx={{ p: 4 }}>
+      <Typography variant="h6">Custom Padding</Typography>
+      <Typography variant="body2">
+        This CardContent component has extra padding applied via the `sx` prop.
+      </Typography>
+    </CardContent>
+  ),
+  name: 'CardContent with sx',
+};

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

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import MuiCardContent from '@mui/material/CardContent';
+/**
+ * This.GUI — CardContent (atom)
+ * Thin wrapper around MUI’s CardContent component.
+ *
+ * - Preserves props and typing directly from MUI.
+ * - Allows styling via `sx`, polymorphism via `component`, and content via `children`.
+ */
+const CardContent = MuiCardContent;
+export type CardContentProps = React.ComponentProps<typeof CardContent>;
+(CardContent as any).displayName = 'Gui.CardContent';
+export default CardContent;

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

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import CardHeader from './CardHeader';
+
+/**
+ * Declarative resolver for CardHeader
+ *
+ * Purpose:
+ * - Enables JSON-based rendering of card headers with title, subheader, and actions.
+ * - Supports polymorphism (`component` or `as`) and typical MUI props.
+ */
+export type CardHeaderSpec = {
+  type: 'CardHeader';
+  props?: {
+    title?: React.ReactNode;
+    subheader?: React.ReactNode;
+    action?: React.ReactNode;
+    avatar?: React.ReactNode;
+    component?: React.ElementType;
+    as?: React.ElementType;
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    [key: string]: any;
+  };
+};
+
+const CardHeaderResolver: RegistryEntry = {
+  type: 'CardHeader',
+  resolve(spec: CardHeaderSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const {
+      id,
+      component,
+      as,
+      sx,
+      className,
+      title,
+      subheader,
+      action,
+      avatar,
+      ...rest
+    } = p;
+
+    const headerId = ensureNodeId('cardHeader', id);
+    const resolvedComponent = component ?? as;
+
+    return (
+      <CardHeader
+        title={title}
+        subheader={subheader}
+        action={action}
+        avatar={avatar}
+        sx={sx}
+        className={className}
+        id={headerId}
+        data-testid={p['data-testid']}
+        {...(resolvedComponent ? { component: resolvedComponent } : {})}
+        {...rest}
+      />
+    );
+  },
+};
+
+export default CardHeaderResolver;