this.gui 1.3.22 → 1.3.26

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

@@ -0,0 +1,189 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Section, Typography, Box, Button } from '@/gui/components/atoms';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Section> = {
+  title: 'Atoms/Containers/Section',
+  component: Section,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 0, minHeight: 400 }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Section** atom is a responsive container designed to create consistent layout sections that respect This.GUI’s **layout insets** and **theme palette**.
+
+It supports theming via the \`section\` palette keys (\`default\`, \`subtle\`, \`strong\`) and allows custom background colors for flexibility.
+
+---
+## Features
+- Reacts to global layout insets for responsive spacing.
+- Provides unified paddings with theme scaling.
+- Accepts **custom backgroundColor**, or one from \`theme.palette.section\`.
+- Supports responsive padding, height, and alignment.
+- Can wrap any children content.
+
+---
+## Margin Props
+Section supports **margin props** for controlling the outer spacing around the section:
+
+- \`marginTop\`
+- \`marginBottom\`
+- \`marginLeft\`
+- \`marginRight\`
+
+Each of these can be a \`number\`, \`string\`, or a **breakpoint object** (e.g. \`{ xs: 2, sm: 4, md: 6 }\`) for responsive margins.
+
+If not provided, Section will use the layout insets as fallback margins to ensure consistent spacing with the overall layout.
+
+---
+## Key Props
+- \`colorVariant?: 'default' | 'subtle' | 'strong'\` — Selects section background color from theme.
+- \`bgcolor?: string\` — Overrides the background with a custom color.
+- \`padding?: number | string | object\` — Adjusts inner spacing responsively.
+- \`height?: number | string\` — Sets the vertical height.
+- \`sx?: object\` — MUI system style overrides.
+- \`marginTop?: number | string | object\`
+- \`marginBottom?: number | string | object\`
+- \`marginLeft?: number | string | object\`
+- \`marginRight?: number | string | object\`
+
+---
+## Basic usage (React)
+~~~tsx
+import { Section, Typography } from '@/gui/atoms';
+
+<Section colorVariant="default" padding={4}>
+  <Typography variant="h4">Welcome</Typography>
+  <Typography>Section content goes here.</Typography>
+</Section>
+
+// Example with margin props
+<Section colorVariant="subtle" padding={4} marginTop={2} marginBottom={3}>
+  <Typography variant="h5">Section with Margins</Typography>
+  <Typography>Section content with custom top and bottom margins.</Typography>
+</Section>
+~~~
+
+---
+## Declarative JSON / Config usage
+~~~json
+{
+  "type": "Section",
+  "props": {
+    "colorVariant": "subtle",
+    "padding": 4,
+    "marginTop": 2,
+    "marginBottom": 3,
+    "children": [
+      { "type": "Typography", "props": { "variant": "h5", "children": "Hello world" } },
+      { "type": "Typography", "props": { "children": "This is a declarative section example." } }
+    ]
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+  argTypes: {
+    colorVariant: {
+      control: { type: 'select' },
+      options: ['default', 'subtle', 'strong'],
+      description: 'Predefined section variant based on theme.palette.section',
+    },
+    bgcolor: { control: 'color', description: 'Custom background color override' },
+    padding: { control: { type: 'number' }, description: 'Internal padding' },
+    height: { control: { type: 'text' }, description: 'Height (px, %, vh, etc.)' },
+  },
+  args: {
+    colorVariant: 'default',
+    padding: 4,
+    height: 'auto',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Section>;
+
+// ======================= Stories =======================
+
+export const Playground: Story = {
+  render: (args) => (
+    <Section {...args}>
+      <Typography variant="h5" sx={{ mb: 1 }}>Playground Section</Typography>
+      <Typography variant="body2">Easily tweak padding, background, and height.</Typography>
+    </Section>
+  ),
+};
+
+export const Variants: Story = {
+  render: (args) => (
+    <Box sx={{ display: 'grid', gap: 2 }}>
+      {(['default', 'subtle', 'strong'] as const).map((variant) => (
+        <Section key={variant} {...args} colorVariant={variant} padding={3}>
+          <Typography variant="subtitle1">colorVariant = {variant}</Typography>
+          <Typography variant="body2">
+            This uses <code>theme.palette.section.{variant}</code>
+          </Typography>
+        </Section>
+      ))}
+    </Box>
+  ),
+};
+
+export const CustomBackground: Story = {
+  args: { padding: 4, bgcolor: '#2fb0a3ff' },
+  render: (args) => (
+    <Section {...args}>
+      <Typography variant="h6" sx={{ color: 'text.primary' }}>
+        Custom background color
+      </Typography>
+      <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+        You can set <code>bgcolor</code> manually for any theme or design, and it will maintain good contrast for both light and dark text.
+      </Typography>
+    </Section>
+  ),
+};
+
+export const WithContentComposition: Story = {
+  render: () => (
+    <Section colorVariant="default" padding={4}>
+      <Typography variant="h5" sx={{ mb: 1 }}>Section with Composition</Typography>
+      <Box display="flex" gap={2}>
+        <Button variant="contained" color="primary">Accept</Button>
+        <Button variant="outlined" color="secondary">Cancel</Button>
+      </Box>
+    </Section>
+  ),
+};
+
+export const ResponsivePadding: Story = {
+  args: { padding: { xs: 2, sm: 4, md: 6 } },
+  render: (args) => (
+    <Section {...args}>
+      <Typography variant="h5">Responsive Padding</Typography>
+      <Typography variant="body2">
+        Resize the viewport to see the padding adjust responsively.
+      </Typography>
+    </Section>
+  ),
+};
+
+export const ResponsiveMargins: Story = {
+  args: { marginTop: { xs: 1, sm: 2, md: 4 }, marginBottom: { xs: 1, sm: 3, md: 5 } },
+  render: (args) => (
+    <Section {...args} padding={3}>
+      <Typography variant="h5">Responsive Margins</Typography>
+      <Typography variant="body2">
+        Adjusts top and bottom margins responsively across breakpoints.
+      </Typography>
+    </Section>
+  ),
+};

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

@@ -0,0 +1,76 @@
+import React from 'react';
+import { Box } from '@/gui/components/atoms';
+import { useInsets, useGuiTheme } from '@/gui/hooks';
+import type { SectionProps } from './Section.types';
+
+const Section: React.FC<SectionProps> = ({
+  children,
+  sx,
+  maxWidth = '100%',
+  component = 'section',
+  bgcolor,
+  colorVariant,
+  padding,
+  height,
+  marginTop,
+  marginBottom,
+  marginLeft,
+  marginRight,
+}) => {
+  const insets = useInsets();
+  const theme = useGuiTheme();
+  // Determine if bgcolor is a theme token or raw color
+  // We check if bgcolor matches a key path in theme.palette or if it is a raw color string
+  const isThemeToken = (color: string) => {
+    if (!color) return false;
+    // Simple heuristic: theme tokens contain dot notation or match keys in palette
+    if (color.includes('.')) {
+      const parts = color.split('.');
+      let obj: any = theme.palette;
+      for (const part of parts) {
+        if (obj && part in obj) {
+          obj = obj[part];
+        } else {
+          return false;
+        }
+      }
+      return true;
+    }
+    return color in theme.palette;
+  };
+
+  let finalBgcolor: string | undefined;
+  if (bgcolor) {
+    finalBgcolor = isThemeToken(bgcolor) ? bgcolor : bgcolor;
+  } else if (colorVariant && theme.palette.section && colorVariant in theme.palette.section) {
+    finalBgcolor = theme.palette.section[colorVariant];
+  }
+
+  return (
+    <Box
+      component={component}
+      sx={{
+        // Responsive width/height: fill viewport, but margin aligns with insets
+        width: `calc(100vw - ${insets.left + insets.right}px)`,
+        height: height ? height : `calc(100vh - ${insets.top + insets.bottom}px)`,
+        marginTop: marginTop !== undefined ? marginTop : insets.top,
+        marginBottom: marginBottom !== undefined ? marginBottom : insets.bottom,
+        marginLeft: marginLeft !== undefined ? marginLeft : insets.left,
+        marginRight: marginRight !== undefined ? marginRight : insets.right,
+        maxWidth,
+        // Responsive internal padding
+        padding: padding !== undefined ? padding : {
+          xs: 2,
+          sm: 3,
+          md: 4,
+        },
+        ...(finalBgcolor ? { bgcolor: finalBgcolor } : {}),
+        ...sx,
+      }}
+    >
+      {children}
+    </Box>
+  );
+};
+
+export default Section;

package/src/gui/components/atoms/Section/Section.types.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Theme } from '@mui/material/styles';
+import { SxProps } from '@mui/system';
+
+export interface SectionProps {
+  id?: string;
+  children?: React.ReactNode;
+  sx?: SxProps<Theme>;
+  colorVariant?: keyof Theme['palette']['section'];
+  bgcolor?: string;
+  className?: string;
+  component?: React.ElementType;
+  elevation?: number;
+  padded?: boolean;
+  centered?: boolean;
+  'data-testid'?: string;
+  maxWidth?: number | string;
+  padding?: number | string | Record<string, any>;
+  height?: number | string;
+  marginTop?: number | string | Record<string, any>;
+  marginBottom?: number | string | Record<string, any>;
+  marginLeft?: number | string | Record<string, any>;
+  marginRight?: number | string | Record<string, any>;
+}

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

@@ -0,0 +1,94 @@
+// src/gui/atoms/Stack/Stack.resolver.tsx
+import * as React from 'react';
+import Stack from './Stack';
+import Link from '@/gui/components/atoms/Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+/**
+ * Declarative spec for Stack (layout primitive)
+ *
+ * Notes
+ * - Choose the rendered element via `component` (e.g. 'div', 'section', 'a', custom).
+ * - If `to` is provided (and no explicit component), the resolver will default to This.GUI `Link`.
+ * - If `external` is true (and no explicit component), it will default to an anchor (`'a'`) and apply
+ *   safe `target`/`rel` defaults.
+ * - Common Stack props (direction, spacing, divider, alignItems, justifyContent, useFlexGap, flexWrap, etc.) are passed through.
+ */
+export type StackSpec = {
+  type: 'Stack';
+  props?: {
+    children?: React.ReactNode;
+    // Polymorphism / routing
+    component?: any; // 'div' | 'section' | 'a' | Link | custom
+    as?: any;        // alias for component
+    to?: string;     // router target (when component={Link})
+    href?: string;   // anchor target (when component='a')
+    external?: boolean; // force external anchor
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    // Core Stack props (subset; rest is passthrough)
+    direction?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+    spacing?: number | string;
+    divider?: React.ReactNode;
+    useFlexGap?: boolean;
+    alignItems?: React.CSSProperties['alignItems'];
+    justifyContent?: React.CSSProperties['justifyContent'];
+    flexWrap?: React.CSSProperties['flexWrap'];
+    // Styling & misc
+    sx?: any;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    // Allow system props / arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const StackResolver: RegistryEntry = {
+  type: 'Stack',
+  resolve(spec: StackSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const nodeId = ensureNodeId('Stack', p.id);
+    // Decide polymorphic target
+    const component = p.component ?? p.as ?? (p.to ? Link : 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 }
+        : {};
+    // Collect common props and avoid leaking resolver-only keys
+    const {
+      children,
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+      id: _id,
+      'data-testid': _dataTestId,
+      ...rest
+    } = p;
+    return (
+      <Stack
+        component={component}
+        sx={p.sx}
+        id={nodeId}
+        className={p.className}
+        data-testid={p['data-testid']}
+        {...routingProps}
+        {...rest}
+      >
+        {children}
+      </Stack>
+    );
+  },
+};
+
+export default StackResolver;

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

@@ -0,0 +1,160 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Stack from './Stack';
+import Paper from '@/gui/components/atoms/Paper/Paper';
+import Link from '@/gui/components/atoms/Link/Link';
+
+const meta: Meta<typeof Stack> = {
+  title: 'Atoms/Containers/Stack',
+  component: Stack,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Stack** atom is a thin wrapper around MUI's \`MuiStack\` that preserves **polymorphism** and forwards all layout props.
+It integrates with **This.GUI** theming and supports **declarative specs** through the Stack resolver.
+
+---
+## Features
+- Direction: \`row\`, \`column\`, and reverse variants
+- Spacing/gap via \`spacing\`
+- Optional \`divider\`
+- Alignment: \`alignItems\`, \`justifyContent\`, \`flexWrap\`
+- **Polymorphic** via \`component\` (e.g. 'div', 'section', 'a')
+- Full **system props** passthrough via \`sx\`
+
+---
+## Basic usage
+~~~jsx
+<Stack direction="row" spacing={2}>
+  <Item />
+  <Item />
+</Stack>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "Stack",
+  "props": {
+    "direction": "row",
+    "spacing": 2,
+    "sx": { "alignItems": "center" },
+    "children": [
+      { "type": "Paper", "props": { "sx": { "p": 1 }, "children": "A" } },
+      { "type": "Paper", "props": { "sx": { "p": 1 }, "children": "B" } }
+    ]
+  }
+}
+~~~
+
+*Note:* We demonstrate polymorphism in dedicated stories rather than Controls to avoid type-narrowing issues with MUI's OverridableComponent.
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component'],
+    },
+  },
+  argTypes: {
+    direction: {
+      control: { type: 'radio' },
+      options: ['row', 'row-reverse', 'column', 'column-reverse'],
+    },
+    spacing: {
+      control: { type: 'range', min: 0, max: 8, step: 0.5 },
+    },
+    useFlexGap: {
+      control: 'boolean',
+    },
+    sx: {
+      control: 'object',
+    },
+  },
+  args: {
+    direction: 'row',
+    spacing: 1.5,
+    useFlexGap: true,
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stack>;
+
+const Item = ({ children }: { children: React.ReactNode }) => (
+  <Paper variant="outlined" sx={{ p: 1.5, borderRadius: 1 }}>
+    {children}
+  </Paper>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <Stack {...args}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const RowSpacing: Story = {
+  args: { direction: 'row', spacing: 2 },
+  render: (args) => (
+    <Stack {...args}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const ColumnSpacing: Story = {
+  args: { direction: 'column', spacing: 1.5 },
+  render: (args) => (
+    <Stack {...args} sx={{ width: 240 }}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const WithDivider: Story = {
+  render: (args) => (
+    <Stack {...args} direction="row" spacing={2} divider={<span style={{ opacity: 0.5 }}>|</span>}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const PolymorphicSection: Story = {
+  render: (args) => (
+    <Stack {...args} component="section" spacing={1.5}>
+      <Item>Section A</Item>
+      <Item>Section B</Item>
+    </Stack>
+  ),
+};
+
+export const PolymorphicRouterLink: Story = {
+  render: (args) => (
+    <Link to="/docs" style={{ textDecoration: 'none' }}>
+      <Stack {...args} spacing={1.5}>
+        <Item>Go to Docs</Item>
+      </Stack>
+    </Link>
+  ),
+};

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

@@ -0,0 +1,15 @@
+/*
+ * This.GUI — Stack (polymorphic)
+ * Thin wrapper that preserves MUI's own typing and `component` API.
+ * Examples:
+ *   <Stack direction="row" spacing={2} />
+ *   <Stack component="section" gap={1} />
+ *   <Stack component="a" href="/docs" />
+ */
+import MuiStack from '@mui/material/Stack';
+import * as React from 'react';
+// Re-export using MUI's own component type to keep polymorphism and full typing
+const Stack = MuiStack;
+export type StackProps = React.ComponentProps<typeof Stack>;
+(Stack as any).displayName = 'Gui.Stack';
+export default Stack;

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

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+import Surface from './Surface';
+import type { RegistryEntry } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import type { SurfaceResolverSpec as SurfaceSpec } from './Surface.types';
+
+/**
+ * SurfaceResolver
+ * ---------------
+ * - Maps a JSON-friendly spec to <Surface /> props.
+ * - Preserves MUI styling (`sx`, `variant`, `elevation`).
+ * - Adds IDs and classNames for runtime targeting.
+ */
+const SurfaceResolver: RegistryEntry = {
+  type: 'Surface',
+  resolve(spec: SurfaceSpec) {
+    const p = spec.props ?? {};
+    const rootProps: any = {
+      variant: p.variant ?? 'elevation',
+      elevation: p.elevation ?? 1,
+      square: p.square ?? false,
+      sx: p.sx,
+      id: ensureNodeId('surface', p.id),
+      className: p.className,
+      'data-testid': p['data-testid'],
+    };
+
+    return (
+      <Surface {...rootProps}>
+        {p.children}
+      </Surface>
+    );
+  },
+};
+
+export default SurfaceResolver;

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

@@ -0,0 +1,49 @@
+import React from 'react';
+import MuiSurface from '@mui/material/Paper';
+import type { SurfaceProps } from './Surface.types';
+
+/**
+ * Surface
+ * -------
+ * A visual container primitive.
+ * Acts as a thin wrapper around MUI's Paper.
+ * Supports elevation, variant, square, and sx overrides.
+ */
+const Surface = React.forwardRef<HTMLDivElement, SurfaceProps>((props, ref) => {
+  const {
+    variant = 'elevation',
+    elevation: elevationProp,
+    sx,
+    ...rest
+  } = props;
+
+  const isCard = variant === 'card';
+  const mappedVariant = (isCard ? 'outlined' : variant) as 'elevation' | 'outlined';
+  const elevation = isCard ? 0 : elevationProp;
+
+  const cardSx = isCard
+    ? [
+        (theme: any) => ({
+          borderRadius: theme.shape?.borderRadius ?? 8,
+          borderColor: 'divider',
+          backgroundColor: 'background.paper',
+          boxShadow: theme.customShadows?.card ?? theme.shadows?.[3] ?? 'none',
+        }),
+      ]
+    : [];
+  const sxArray = Array.isArray(sx) ? sx : sx ? [sx] : [];
+  const composedSx = isCard ? [...cardSx, ...sxArray] : sx;
+
+  return (
+    <MuiSurface
+      ref={ref}
+      variant={mappedVariant}
+      elevation={elevation}
+      sx={composedSx}
+      {...rest}
+    />
+  );
+});
+
+Surface.displayName = 'Surface';
+export default Surface;

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

@@ -0,0 +1,20 @@
+import type { PaperProps } from '@mui/material/Paper';
+import type { ReactNode } from 'react';
+export type SurfaceVariant = 'elevation' | 'outlined' | 'card';
+export interface SurfaceProps extends Omit<PaperProps, 'variant'> {
+  /**
+   * Visual style for the surface.
+   * `card` maps to an outlined paper with subtle shadow + rounded corners.
+   */
+  variant?: SurfaceVariant;
+}
+
+export type SurfaceResolverSpec = {
+  type?: 'Surface';
+  props?: Partial<SurfaceProps> & {
+    children?: ReactNode;
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+  };
+};