this.gui 1.3.40 → 1.3.42

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

@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Paper from './Paper';
+
+const meta: Meta<typeof Paper> = {
+  title: 'Atoms/Containers/Paper',
+  component: Paper,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 240, background: 'var(--mui-palette-background-default)' }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Paper** atom is a thin wrapper around MUI's \`MuiPaper\` that preserves **polymorphism** via the \`component\` prop and passes through all MUI props.
+It integrates with **This.GUI** theming and supports **declarative specs** through the Paper resolver.
+
+---
+## Features
+- Variants: \`elevation\`, \`outlined\`
+- Elevation: \`0..24\`
+- \`square\` boolean
+- **Polymorphic** via \`component\` (e.g., \`'div'\`, \`'section'\`, \`'a'\`)
+- **Routing default** in declarative mode: if \`to\` is provided (and no explicit \`component\`), resolver renders This.GUI \`Link\`
+- Full **system props** passthrough via \`sx\` (and regular MUI system props)
+
+---
+## Basic usage
+~~~jsx
+import Paper from '@/gui/atoms/Paper/Paper';
+
+<Paper elevation={2} sx={{ p: 2, borderRadius: 2 }}>
+  Content
+</Paper>
+~~~
+
+## Polymorphic
+~~~jsx
+<Paper component="section" variant="outlined" sx={{ p: 2 }}>
+  I'm a &lt;section&gt;
+</Paper>
+
+<Paper component="a" href="/docs" sx={{ p: 2, textDecoration: 'none' }}>
+  Go to docs
+</Paper>
+~~~
+
+*Note:* The \`component\` prop is demonstrated via dedicated stories (not Controls) because Storybook's args typing for MUI OverridableComponent can incorrectly narrow props and flag \`component\` as invalid in the Controls panel.
+
+## Declarative JSON / Resolver
+When using the registry-driven renderer, a Paper spec like this:
+
+~~~json
+{
+  "type": "Paper",
+  "props": {
+    "variant": "outlined",
+    "elevation": 0,
+    "component": "section",
+    "sx": { "p": 2, "borderRadius": 2 },
+    "children": "Content"
+  }
+}
+~~~
+
+**Routing (declarative default)** — If you provide \`to\` (and **omit** \`component\`), the resolver will render using This.GUI \`Link\`:
+
+~~~json
+{
+  "type": "Paper",
+  "props": {
+    "to": "/docs",
+    "sx": { "p": 2 },
+    "children": "Go to docs"
+  }
+}
+~~~
+
+The resolver:
+- Chooses \`component\` by priority: explicit \`component\` → \`as\` → (\`to\` ⇒ This.GUI \`Link\`) → (\`external\` ⇒ \`'a'\`)
+- For \`external: true\`, applies safe defaults: \`target="_blank"\`, \`rel="noopener noreferrer"\`
+- Cleans resolver-only keys so they don't leak into the DOM
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component'],
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['elevation', 'outlined'],
+    },
+    elevation: {
+      control: { type: 'range', min: 0, max: 24, step: 1 },
+    },
+    square: {
+      control: 'boolean',
+    },
+    sx: {
+      control: 'object',
+    },
+  },
+  args: {
+    variant: 'elevation',
+    elevation: 1,
+    square: false,
+    children: 'Paper content',
+    sx: { p: 2 },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Paper>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Paper {...args} variant="elevation">Elevation (default)</Paper>
+      <Paper {...args} variant="outlined">Outlined</Paper>
+    </div>
+  ),
+};
+
+export const Elevations: Story = {
+  args: { variant: 'elevation' },
+  render: (args) => {
+    const levels = [0, 1, 2, 3, 4, 6, 8, 12, 16, 24];
+    return (
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(140px, 1fr))', gap: 12 }}>
+        {levels.map((e) => (
+          <Paper key={e} {...args} elevation={e} sx={{ p: 2 }}>
+            elevation={e}
+          </Paper>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const PolymorphicSection: Story = {
+  args: { variant: 'outlined', children: 'I render as <section>' },
+  render: (args) => (
+    <Paper {...args} component="section">
+      {args.children}
+    </Paper>
+  ),
+};
+
+export const PolymorphicAnchor: Story = {
+  args: { children: 'I render as <a href="/docs">', sx: { p: 2, textDecoration: 'none' } },
+  render: (args) => (
+    <Paper component="a" href="/docs" sx={args.sx}>
+      {args.children}
+    </Paper>
+  ),
+};
+
+export const WithSystemProps: Story = {
+  name: 'With system props',
+  args: { variant: 'outlined' },
+  render: (args) => (
+    <Paper {...args} sx={{ p: 2, m: 1, display: 'inline-block', borderRadius: 2 }}>
+      Padding, margin, display via system props.
+    </Paper>
+  ),
+};
+
+export const WithSx: Story = {
+  args: { variant: 'outlined' },
+  render: (args) => (
+    <Paper {...args} sx={{ p: 2, borderRadius: 2, borderStyle: 'dashed' }}>
+      Custom \`sx\` styling (dashed outline).
+    </Paper>
+  ),
+};

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

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

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

@@ -0,0 +1,10 @@
+import Section from './Section';
+import type { SectionProps } from './Section.types';
+
+export const SectionResolver = {
+  type: 'Section',
+  component: Section,
+  resolve: (props: SectionProps) => <Section {...props} />,
+};
+
+export default SectionResolver;

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/atoms/Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/gui/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;