this.gui 1.3.40 → 1.3.42

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/atoms/Paper/Paper';
+import Link from '@/gui/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 '@/gui/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;
+  };
+};

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

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import Switch from './Switch';
+import { FormControlLabel } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Switch.resolver
+ * ------------------------------------------------------------
+ * Allows declarative usage of the Switch atom. You can pass any
+ * MUI Switch prop through, plus optional `label` support. If
+ * `label` is provided, we wrap the control in `FormControlLabel`.
+ *
+ * Examples (JSON-ish):
+ *  {
+ *    type: 'Switch',
+ *    props: { checked: true, color: 'primary', size: 'small' }
+ *  }
+ *
+ *  {
+ *    type: 'Switch',
+ *    props: { label: 'Enable feature', defaultChecked: true }
+ *  }
+ */
+
+export type SwitchResolverProps = React.ComponentProps<typeof Switch> & {
+  /** Optional text/element label to render alongside the switch */
+  label?: React.ReactNode;
+  /** Label position when `label` is provided */
+  labelPlacement?: 'end' | 'start' | 'top' | 'bottom';
+  sx?: SxProps<Theme>;
+  guiId?: string;
+};
+
+export default function resolveSwitch(props: SwitchResolverProps) {
+  const { label, labelPlacement = 'end', guiId, sx, ...rest } = props || ({} as SwitchResolverProps);
+
+  const nodeId = ensureNodeId('Switch', guiId);
+
+  const control = <Switch id={nodeId} sx={sx} {...rest} />;
+
+  if (label != null) {
+    return (
+      <FormControlLabel
+        control={control}
+        label={label}
+        labelPlacement={labelPlacement}
+      />
+    );
+  }
+
+  return control;
+}

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

@@ -0,0 +1,236 @@
+// src/gui/atoms/Switch/Switch.stories.tsx
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Stack, Typography, Switch } from '@/gui/components/atoms';
+import { FormControlLabel } from '@mui/material';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Switch> = {
+  title: 'Atoms/Forms & Inputs/Switch',
+  component: Switch,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <Box sx={{ p: 2 }}>
+          <Story />
+        </Box>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Switch (This.GUI atom)** is a thin wrapper around MUI's \`Switch\`.
+It keeps MUI behavior, styling, and typing, but you import it from \`@/gui/atoms\` to keep your app decoupled from MUI.
+
+---
+
+# Usage
+
+## React (imperative)
+~~~tsx
+import { Switch } from '@/gui/atoms';
+
+export function Example() {
+  const [enabled, setEnabled] = React.useState(false);
+  return (
+    <Switch
+      checked={enabled}
+      onChange={(_, v) => setEnabled(v)}
+      color="primary"
+      size="medium"
+    />
+  );
+}
+~~~
+
+With an accessible label (MUI way):
+~~~tsx
+import { FormControlLabel } from '@mui/material';
+
+<FormControlLabel control={<Switch defaultChecked />} label="Enable notifications" />
+~~~
+
+---
+
+## Declarative (resolver)
+If you’re rendering via a JSON/registry resolver, you can pass the same props:
+
+~~~json
+{
+  "type": "Switch",
+  "props": {
+    "label": "Enable feature",
+    "defaultChecked": true,
+    "color": "primary",
+    "size": "small",
+    "id": "feat-toggle",
+    "sx": { "ml": 1 }
+  }
+}
+~~~
+
+The resolver supports:
+- All native MUI Switch props (\`checked\`, \`defaultChecked\`, \`onChange\`, \`color\`, \`size\`, \`disabled\`, \`edge\`, \`inputProps\`, \`sx\`, etc.).
+- \`label?: ReactNode\` and \`labelPlacement?: 'start' | 'end' | 'top' | 'bottom'\` (wraps in \`FormControlLabel\` when present).
+- \`id\`, \`className\`, \`data-testid\` passthrough for testing and DOM hooks.
+
+---
+        `,
+      },
+    },
+  },
+  argTypes: {
+    checked: {
+      control: 'boolean',
+      description: 'Controlled state. Use with onChange.',
+      table: { category: 'Behavior' },
+    },
+    defaultChecked: {
+      control: 'boolean',
+      description: 'Uncontrolled initial state.',
+      table: { category: 'Behavior' },
+    },
+    disabled: {
+      control: 'boolean',
+      table: { category: 'Behavior' },
+    },
+    color: {
+      control: 'select',
+      options: ['primary', 'secondary', 'default'],
+      table: { category: 'Appearance' },
+    },
+    size: {
+      control: 'radio',
+      options: ['small', 'medium'],
+      description: 'Same as MUI Switch (no large by default).',
+      table: { category: 'Appearance' },
+    },
+    edge: {
+      control: 'radio',
+      options: [false, 'start', 'end'],
+      table: { category: 'Appearance' },
+    },
+    sx: { table: { category: 'Style' } },
+    id: { table: { category: 'DOM' } },
+    className: { table: { category: 'DOM' } },
+    // Not useful to control live in SB
+    onChange: { table: { disable: true } },
+    inputProps: { table: { disable: true } },
+  },
+  args: {
+    defaultChecked: false,
+    color: 'primary',
+    size: 'medium',
+    edge: false,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Switch>;
+
+// ======================= Stories =======================
+
+export const Playground: Story = {
+  render: (args) => <Switch {...args} />,
+};
+
+export const LabeledVariants: Story = {
+  name: 'With label & placement',
+  render: () => (
+    <Stack spacing={2}>
+      <FormControlLabel control={<Switch defaultChecked />} label="End (default)" />
+      <FormControlLabel control={<Switch defaultChecked />} label="Start" labelPlacement="start" />
+      <FormControlLabel control={<Switch />} label="Top" labelPlacement="top" />
+      <FormControlLabel control={<Switch />} label="Bottom" labelPlacement="bottom" />
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'When `label` is present, the atom wraps the control with `FormControlLabel`. Use `labelPlacement` to position it.',
+      },
+    },
+  },
+};
+
+export const SizesAndColors: Story = {
+  name: 'Sizes & colors',
+  render: () => (
+    <Stack spacing={2}>
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Typography variant="body2" sx={{ minWidth: 88 }}>small</Typography>
+        <Switch size="small" color="default" defaultChecked />
+        <Switch size="small" color="primary" defaultChecked />
+        <Switch size="small" color="secondary" defaultChecked />
+      </Stack>
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Typography variant="body2" sx={{ minWidth: 88 }}>medium</Typography>
+        <Switch size="medium" color="default" defaultChecked />
+        <Switch size="medium" color="primary" defaultChecked />
+        <Switch size="medium" color="secondary" defaultChecked />
+      </Stack>
+    </Stack>
+  ),
+};
+
+export const ControlledExample: Story = {
+  name: 'Controlled (React state)',
+  render: () => {
+    const [on, setOn] = React.useState(false);
+    return (
+      <Stack spacing={1.5}>
+        <Typography variant="body2">Value: <b>{on ? 'true' : 'false'}</b></Typography>
+        <FormControlLabel
+          control={
+            <Switch
+              checked={on}
+              onChange={(_, v) => setOn(v)}
+              color={on ? 'primary' : 'secondary'}
+            />
+          }
+          label="Controlled switch"
+        />
+      </Stack>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Classic controlled pattern: bind `checked` and update via `onChange`. You can also change appearance based on state.',
+      },
+    },
+  },
+};
+
+export const EdgeAndSx: Story = {
+  name: 'Edge & custom sx',
+  render: () => (
+    <Stack spacing={2}>
+      <FormControlLabel control={<Switch edge="start" defaultChecked />} label="Edge start" />
+      <FormControlLabel
+        control={
+          <Switch
+            defaultChecked
+            sx={{
+              '& .MuiSwitch-switchBase.Mui-checked + .MuiSwitch-track': {
+                opacity: 0.7,
+              },
+            }}
+          />
+        }
+        label="Custom sx"
+      />
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass any `sx` overrides exactly as you would with MUI. Useful for fine-grained tuning without creating a new variant.',
+      },
+    },
+  },
+};

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

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import MuiSwitch from '@mui/material/Switch';
+import type { SwitchProps as MuiSwitchProps } from '@mui/material/Switch';
+/**
+ * Switch (This.GUI primitive)
+ * ----------------------------------------
+ * Thin wrapper over MUI's `Switch`.
+ * - Non‑polymorphic (same as MUI): forwards ref to the root element.
+ * - Preserves all MUI props (`checked`, `onChange`, `size`, `color`, etc.).
+ *
+ * Usage:
+ *   import { Switch } from '@/gui/atoms';
+ *   <Switch checked={on} onChange={(e) => setOn(e.target.checked)} size="small" />
+ */
+
+// Re-export MUI's prop types so consumers can import from our surface.
+export type SwitchProps = MuiSwitchProps;
+const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(function Switch(props, ref) {
+  return <MuiSwitch ref={ref} {...props} />;
+});
+export default Switch;
+export type { MuiSwitchProps };

package/src/gui/components/atoms/Table/Body/TableBody.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MuiTableBody from '@mui/material/TableBody';
+// Re-export using MUI's own component type to keep full typing
+const TableBody = MuiTableBody;
+export type TableBodyProps = React.ComponentProps<typeof TableBody>;
+(TableBody as any).displayName = 'Gui.TableBody';
+export default TableBody;

package/src/gui/components/atoms/Table/Cell/TableCell.tsx

@@ -0,0 +1,18 @@
+/**
+ * This.GUI — TableCell
+ * Thin wrapper that preserves MUI's own typing and API.
+ *
+ * Examples:
+ *   <TableCell align="right">123</TableCell>
+ *
+ * Notes:
+ * - Preserves full MUI TableCell props and typing.
+ * - Integrates into This.GUI namespace and resolver pattern.
+ */
+import * as React from 'react';
+import MuiTableCell from '@mui/material/TableCell';
+// Re-export using MUI's own component type to keep full typing
+const TableCell = MuiTableCell;
+export type TableCellProps = React.ComponentProps<typeof TableCell>;
+(TableCell as any).displayName = 'Gui.TableCell';
+export default TableCell;

package/src/gui/components/atoms/Table/Head/TableHead.tsx

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import MuiTableHead from '@mui/material/TableHead';
+
+// Re-export using MUI's own component type to keep full typing
+const TableHead = MuiTableHead;
+export type TableHeadProps = React.ComponentProps<typeof TableHead>;
+
+(TableHead as any).displayName = 'Gui.TableHead';
+export default TableHead;

package/src/gui/components/atoms/Table/Row/TableRow.tsx

@@ -0,0 +1,20 @@
+/**
+ * This.GUI — TableRow
+ * Thin wrapper that preserves MUI's own typing and API.
+ *
+ * Examples:
+ *   <TableRow hover>
+ *     <TableCell>...</TableCell>
+ *   </TableRow>
+ *
+ * Notes:
+ * - Preserves full MUI TableRow props and typing.
+ * - Integrates into This.GUI namespace and resolver pattern.
+ */
+import * as React from 'react';
+import MuiTableRow from '@mui/material/TableRow';
+// Re-export using MUI's own component type to keep full typing
+const TableRow = MuiTableRow;
+export type TableRowProps = React.ComponentProps<typeof TableRow>;
+(TableRow as any).displayName = 'Gui.TableRow';
+export default TableRow;