this.gui 1.3.22 → 1.3.26

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.resolver.tsx

@@ -0,0 +1,58 @@
+import ThemeModeToggle from './ThemeModeToggle';
+import { ThemeModeToggleResolverSpec } from './ThemeModeToggle.types';
+/**
+ * Resolver for ThemeModeToggle
+ * ----------------------------
+ * Allows you to render the ThemeModeToggle from a plain JSON/config object.
+ *
+ * Minimal accepted shape:
+ * {
+ *   "type": "ThemeModeToggle",
+ *   "props": {
+ *     "variant": "minimal" | "switchMinimal" | "switchWithLabel",
+ *     "show": "icons" | "label" | "both",
+ *     "id": "optional-id",
+ *     "className": "optional-class",
+ *     "data-testid": "test-id",
+ *     // Optional granular styling
+ *     "sx": {  root styles  },
+ *     "iconSx": { icons styles },
+ *     "switchSx": { switch styles (variant='switch')  },
+ *     "labelSx": { label Typography styles  }
+ *   }
+ * }
+ */
+
+export function resolveThemeModeToggle(p: ThemeModeToggleResolverSpec = {}) {
+  const {
+    variant = 'minimal',
+    show = 'icons',
+    id,
+    className,
+    ['data-testid']: dataTestId,
+    sx,
+    iconSx,
+    switchSx,
+    labelSx,
+    switchSize,
+    iconSize,
+  } = p;
+
+  return (
+    <ThemeModeToggle
+      variant={variant}
+      show={show}
+      id={id}
+      className={className}
+      data-testid={dataTestId}
+      sx={sx}
+      iconSx={iconSx}
+      switchSx={switchSx}
+      labelSx={labelSx}
+      switchSize={switchSize}
+      iconSize={iconSize}
+    />
+  );
+}
+
+export default resolveThemeModeToggle;

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ThemeModeToggle from './ThemeModeToggle';
+
+// ======================= Meta =======================
+const meta: Meta<typeof ThemeModeToggle> = {
+  title: 'Theme/ThemeModeToggle',
+  component: ThemeModeToggle,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 24, minHeight: 160, display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ThemeModeToggle** is a theme control molecule that allows users to toggle between **light**, **dark**, and optionally **system** themes in a UI.
+
+---
+## What it does
+ThemeModeToggle provides a way to change the global color mode of the app via UI toggles. It connects with \`useThemeMode\` from This.GUI, so any updates reflect instantly in your theme context.
+
+---
+## Visual Variants
+This component supports multiple visual representations depending on how much context or control you want to show the user:
+
+- **minimal**: Just a clickable icon (uses IconButton).
+- **switchMinimal**: Shows a switch with sun/moon icons.
+- **switchWithLabel**: Shows the switch, icons, and a label that updates dynamically between "Light" and "Dark".
+
+---
+## Props
+- \`variant?: 'minimal' | 'switchMinimal' | 'switchWithLabel'\`
+  - Determines the UI structure.
+- \`show?: 'icons' | 'label' | 'both'\`
+  - For \`variant="minimal"\` only. Controls whether to show icon, label or both.
+- \`switchSize?: 'small' | 'medium'\` — size of the MUI Switch.
+- \`iconSize?: 'small' | 'medium' | 'large'\` — size of the icons.
+- \`sx\`, \`iconSx\`, \`switchSx\`, \`labelSx\` — MUI system styling overrides.
+- \`id\`, \`className\`, \`data-testid\` — standard element props.
+
+---
+## Internal Logic
+- Uses \`useThemeContext()\` to read current mode (\`light\` or \`dark\`) and the \`toggleMode()\` handler.
+- Dynamically determines whether current mode is \`light\` or not to drive the state of the UI (like whether switch is \`checked\` or not).
+- Automatically updates \`labelText\` based on the mode.
+
+---
+## Usage Examples
+
+### Basic usage in React:
+~~~tsx
+<ThemeModeToggle variant="minimal" />
+<ThemeModeToggle variant="switchMinimal" />
+<ThemeModeToggle variant="switchWithLabel" />
+~~~
+
+### Declarative JSON usage:
+~~~json
+{
+  "type": "ThemeModeToggle",
+  "props": {
+    "variant": "switchWithLabel",
+    "iconSize": "medium",
+    "switchSize": "small",
+    "sx": { "ml": 2 }
+  }
+}
+~~~
+
+---
+## Design Notes
+This component is designed to be:
+- **Declarative-first**: usable directly from This.GUI config structures.
+- **Minimal footprint**: all styling is optional and overrideable.
+- **Context-integrated**: updates global theme state through context, not local component state.
+
+Ideal for UIs where users are expected to switch theme modes or where accessible, theme-aware interfaces are critical.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['minimal', 'switch'],
+    },
+    sx: {
+      control: 'object',
+      description: 'MUI system style overrides.',
+    },
+    show: {
+      control: { type: 'radio' },
+      options: ['icons', 'label', 'both'],
+      description: 'Controls whether to show icons, label, or both.',
+    },
+  },
+  args: {
+    variant: 'minimal',
+    sx: {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ThemeModeToggle>;
+
+// ======================= Stories =======================
+
+export const Playground: Story = {
+  render: (args) => <ThemeModeToggle {...args} />,
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 24, flexDirection: 'column' }}>
+      <div>
+        <h4>minimal (icon only)</h4>
+        <ThemeModeToggle variant="minimal" />
+      </div>
+      <div>
+        <h4>switchMinimal (switch with icons)</h4>
+        <ThemeModeToggle variant="switchMinimal" show="icons" />
+      </div>
+      <div>
+        <h4>switchWithLabel (switch with icons + label)</h4>
+        <ThemeModeToggle variant="switchWithLabel" show="both" />
+      </div>
+    </div>
+  ),
+};

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.tsx

@@ -0,0 +1,101 @@
+import React from 'react';
+import { IconButton, Switch } from '@/gui/components/atoms';
+import Icon from '@/gui/Theme/Icon/Icon';
+import { useThemeContext } from '@/gui/Theme';
+import { Typography, Box } from '@/gui/components/atoms';
+import type { ThemeModeToggleProps } from './ThemeModeToggle.types';
+
+const ThemeModeToggle: React.FC<ThemeModeToggleProps> = ({
+  variant = 'minimal',
+  show = 'icons',
+  switchSize = 'medium',
+  iconSize = 'medium',
+  sx,
+  iconSx,
+  switchSx,
+  labelSx,
+  id,
+  className,
+  ['data-testid']: dataTestId,
+}) => {
+  const { mode, toggleMode } = useThemeContext();
+  const isLight = mode === 'light';
+  const labelText = isLight ? 'Light' : 'Dark';
+  const iconFontSize = {
+    small: '1rem',
+    medium: '1.5rem',
+    large: '2rem',
+  }[iconSize];
+
+  const handleToggle = () => {
+    toggleMode();
+  };
+  if (variant === 'switchMinimal' || variant === 'switchWithLabel') {
+    return (
+      <Box
+        id={id}
+        display="flex"
+        alignItems="center"
+        sx={sx ? ([{ cursor: 'pointer' }, sx] as any) : ({ cursor: 'pointer' } as any)}
+        className={className}
+        data-testid={dataTestId}
+      >
+        {/* Always show icons for both switch variants */}
+        <Icon
+          name="light_mode"
+          iconColor={isLight ? 'primary' : 'disabled'}
+          fontSize={iconFontSize}
+        />
+        <Switch
+          checked={!isLight}
+          onChange={handleToggle}
+          color="primary"
+          size={switchSize}
+          inputProps={{ 'aria-label': 'toggle theme mode' }}
+          sx={switchSx}
+        />
+        <Icon
+          name="dark_mode"
+          iconColor={!isLight ? 'primary' : 'disabled'}
+          fontSize={iconFontSize}
+        />
+        {variant === 'switchWithLabel' && (
+          <Typography
+            sx={
+              labelSx
+                ? ([{ ml: 1 }, labelSx] as any)
+                : ({ ml: 1 } as any)
+            }
+          >
+            {labelText}
+          </Typography>
+        )}
+      </Box>
+    );
+  }
+
+  // variant === 'minimal'
+  return (
+    <IconButton id={id} onClick={handleToggle} color="inherit" aria-label="toggle theme mode" size={iconSize} className={className} data-testid={dataTestId} sx={sx}>
+      {show !== 'label' &&
+        (isLight ? (
+          <Icon name="light_mode" iconColor="primary" fontSize={iconFontSize} />
+        ) : (
+          <Icon name="dark_mode" iconColor="primary" fontSize={iconFontSize} />
+        ))}
+      {(show === 'label' || show === 'both') && (
+        <Typography
+          sx={
+            labelSx
+              ? ([{ ml: show === 'both' ? 1 : 0 }, labelSx] as any)
+              : ({ ml: show === 'both' ? 1 : 0 } as any)
+          }
+        >
+          {labelText}
+        </Typography>
+      )}
+    </IconButton>
+  );
+};
+
+export default ThemeModeToggle;

package/src/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle.types.ts

@@ -0,0 +1,29 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+export type ThemeModeToggleProps = {
+  variant?: 'minimal' | 'switchMinimal' | 'switchWithLabel';
+  show?: 'icons' | 'label' | 'both';
+  id?: string;
+  className?: string;
+  ['data-testid']?: string;
+  sx?: SxProps<Theme>;
+  iconSx?: SxProps<Theme>;
+  switchSx?: SxProps<Theme>;
+  labelSx?: SxProps<Theme>;
+  switchSize?: 'small' | 'medium';
+  iconSize?: 'small' | 'medium' | 'large';
+};
+
+export type ThemeModeToggleResolverSpec = {
+  type?: 'ThemeModeToggle';
+  variant?: 'minimal' | 'switchMinimal' | 'switchWithLabel';
+  show?: 'icons' | 'label' | 'both';
+  id?: string;
+  className?: string;
+  ['data-testid']?: string;
+  sx?: SxProps<Theme>;
+  iconSx?: SxProps<Theme>;
+  switchSx?: SxProps<Theme>;
+  labelSx?: SxProps<Theme>;
+  switchSize?: 'small' | 'medium';
+  iconSize?: 'small' | 'medium' | 'large';
+};

package/src/gui/components/molecules/Theme/ThemesCatalog/ThemesCatalog.resolver.tsx

@@ -0,0 +1,15 @@
+import ThemesCatalog from './ThemesCatalog';
+import type { ThemesCatalogResolverSpec } from './ThemesCatalog.types';
+
+const resolver = {
+  type: 'ThemesCatalog',
+  resolve: (props?: ThemesCatalogResolverSpec) => {
+    const { variant, sx } = props || {};
+    return {
+      component: () => <ThemesCatalog variant={variant} sx={sx} />,
+      props,
+    };
+  },
+};
+
+export default resolver;

package/src/gui/components/molecules/Theme/ThemesCatalog/ThemesCatalog.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ThemesCatalog from './ThemesCatalog';
+
+// ======================= Meta =======================
+const meta: Meta<typeof ThemesCatalog> = {
+  title: 'Theme/ThemesCatalog',
+  component: ThemesCatalog,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 16, minHeight: 320 }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ThemesCatalog** component renders a visual interface to explore and select available GUI themes for your application.
+
+It fetches all theme configurations from the \`getGuiThemes()\` utility and displays them using a visually rich card interface. You can toggle between **grid** and **list** layouts and switch between light/dark previews per theme. When a theme is selected, it is applied globally via the context provided by \`useThemeContext()\`.
+
+---
+## Features
+- Visual layout for theme browsing.
+- Switch between **grid** and **list** variants.
+- Light/dark mode preview toggle.
+- Swatches preview for key palette values: \`primary\`, \`secondary\`, and \`background\`.
+- Selectable themes that apply across your GUI via context.
+- JSON-compatible configuration for declarative UI building.
+- Fully themed with **This.GUI** primitives.
+
+---
+## Props
+- \`variant?: 'grid' | 'list'\` — controls layout format. Defaults to \`grid\`.
+- \`sx?: SxProps\` — accepts style overrides via MUI’s \`sx\` prop.
+
+---
+## Basic Usage
+~~~jsx
+<ThemesCatalog variant="grid" />
+<ThemesCatalog variant="list" />
+~~~
+
+## Declarative JSON Configuration
+~~~json
+{
+  "type": "ThemesCatalog",
+  "props": {
+    "variant": "list"
+  }
+}
+~~~
+
+This component is ideal for apps that allow users to select their visual theme from a set of predefined theme options. It pairs well with This.GUI’s theme management context and is useful in both developer-facing configuration tools and end-user customization interfaces.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['grid', 'list'],
+      description: 'Choose layout variant',
+    },
+  },
+  args: {
+    variant: 'grid',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ThemesCatalog>;
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  args: {
+    variant: 'grid',
+  },
+};
+
+export const ListVariant: Story = {
+  name: 'List layout',
+  args: {
+    variant: 'list',
+  },
+};

package/src/gui/components/molecules/Theme/ThemesCatalog/ThemesCatalog.tsx

@@ -0,0 +1,167 @@
+// ThemesCatalog.tsx
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { ThemesCatalogProps } from './ThemesCatalog.types';
+import { getGuiThemes } from '@/gui/Theme/utils/catalog';
+import type { ThemeManifest } from '@/types/theme';
+import Grid from '@/gui/components/atoms/Grid/Grid';
+import Card from '@/gui/components/atoms/Card/Card';
+import CardHeader from '@/gui/components/atoms/CardHeader/CardHeader';
+import CardContent from '@/gui/components/atoms/CardContent/CardContent';
+import CardActions from '@/gui/components/atoms/CardActions/CardActions';
+import Typography from '@/gui/components/atoms/Typography/Typography';
+import Box from '@/gui/components/atoms/Box/Box';
+import Avatar from '@/gui/components/atoms/Avatar/Avatar';
+import Checkbox from '@mui/material/Checkbox';
+import Tooltip from '@mui/material/Tooltip';
+import MuiSwitch from '@mui/material/Switch';
+import Icon from '@/gui/Theme/Icon/Icon';
+import { useThemeContext } from '@/gui/contexts/ThemeContext';
+function getPreviewSwatches(item: ThemeManifest) {
+  const swatches = [];
+  const lightMode = item.mode?.light;
+  if (typeof lightMode === 'object' && lightMode?.palette) {
+    if (lightMode.palette.primary?.main) {
+      swatches.push({ label: 'Primary', value: lightMode.palette.primary.main });
+    }
+    if (lightMode.palette.secondary?.main) {
+      swatches.push({ label: 'Secondary', value: lightMode.palette.secondary.main });
+    }
+    if (lightMode.palette.background?.default) {
+      swatches.push({ label: 'Background', value: lightMode.palette.background.default });
+    }
+  }
+  return swatches;
+}
+export default function ThemesCatalog({ sx, variant = 'grid' }: ThemesCatalogProps = {}) {
+  const themes = getGuiThemes();
+  const { setMode, mode: activeMode, themeId, setThemeId } = useThemeContext();
+  if (!themes || themes.length === 0) {
+    return <Typography>No themes available.</Typography>;
+  }
+
+  // Shared card rendering logic as a helper
+  const ThemeCard = ({ theme }: { theme: ThemeManifest }) => {
+    const light = Boolean(theme.mode?.light);
+    const dark = Boolean(theme.mode?.dark);
+    const isDarkSelected = activeMode === 'dark';
+    return (
+      <Box sx={{ position: 'relative' }}>
+        <Card
+          sx={{
+            p: 1,
+            display: 'flex',
+            flexDirection: 'column',
+            justifyContent: 'space-between',
+            backgroundColor: 'background.default',
+            border: (theme.mode.light as any).palette?.primary?.main
+              ? `1px solid ${(theme.mode.light as any).palette.primary.main}`
+              : '1px solid rgba(0,0,0,0.04)',
+            borderRadius: 1.5,
+            boxShadow: 'none',
+            height: '100%',
+            gap: 0.25,
+          }}
+        >
+          <CardHeader
+            sx={{ mb: 0, '& .MuiCardHeader-content': { overflow: 'hidden' } }}
+            avatar={
+              theme.badgeUrl ? (
+                <Avatar src={theme.badgeUrl} alt={theme.themeName} />
+              ) : (
+                <Avatar>{theme.themeName?.[0] ?? 'T'}</Avatar>
+              )
+            }
+            title={theme.themeName}
+            subheader={theme.author}
+          />
+          <Box sx={{ display: 'flex', gap: 0.75, flexWrap: 'wrap', mt: 1 }}>
+            {getPreviewSwatches(theme).map((sw, i) => (
+              <Tooltip key={`${theme.themeId}-swatch-${i}`} title={sw.label}>
+                <Box
+                  sx={{
+                    width: 14,
+                    height: 14,
+                    borderRadius: 1,
+                    ...(String(sw.value).includes('gradient')
+                      ? { background: sw.value }
+                      : { bgcolor: sw.value }),
+                    border: '1px solid rgba(0,0,0,0.2)',
+                  }}
+                />
+              </Tooltip>
+            ))}
+          </Box>
+          <Box sx={{ position: 'absolute', top: 8, right: 8 }}>
+            <Checkbox
+              size="small"
+              color="primary"
+              checked={theme.themeId === themeId}
+              onChange={() => {
+                if (typeof setThemeId === 'function') {
+                  setThemeId(theme.themeId ?? '');
+                }
+                if (typeof setMode === 'function') {
+                  const fallbackMode: 'light' | 'dark' = theme.defaultMode === 'dark' ? 'dark' : 'light';
+                  setMode(fallbackMode);
+                }
+              }}
+              sx={{
+                p: 0.5,
+                backgroundColor: 'background.paper',
+                borderRadius: 1,
+              }}
+            />
+          </Box>
+          <CardContent sx={{ p: 0.75, pt: 0.25 }}>
+            <Typography variant="body2" color="text.secondary">
+              {theme.description}
+            </Typography>
+            {theme.themeId === themeId && (
+              <Box sx={{ display: 'flex', justifyContent: 'flex-end', alignItems: 'center', mt: 0.5, mb: 0.25 }}>
+                <Icon name="light_mode" style={{ opacity: light ? 1 : 0.4 }} />
+                <MuiSwitch
+                  size="small"
+                  checked={isDarkSelected}
+                  disabled={!light || !dark}
+                  onChange={(e) => {
+                    const checked = e.target.checked;
+                    const nextMode = checked ? 'dark' : 'light';
+                    if (typeof setMode === 'function') {
+                      try { setMode(nextMode); } catch {}
+                    }
+                  }}
+                  inputProps={{ 'aria-label': 'Toggle light/dark mode' }}
+                />
+                <Icon name="dark_mode" style={{ opacity: dark ? 1 : 0.4 }} />
+              </Box>
+            )}
+          </CardContent>
+          <CardActions>
+          </CardActions>
+        </Card>
+      </Box>
+    );
+  };
+
+  if (variant === 'list') {
+    return (
+      <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, ...sx }}>
+        {themes.map((theme: ThemeManifest) => (
+          <Box key={theme.themeId}>
+            <ThemeCard theme={theme} />
+          </Box>
+        ))}
+      </Box>
+    );
+  }
+
+  return (
+    <Grid container spacing={2} sx={sx}>
+      {themes.map((theme: ThemeManifest) => (
+        <Grid item key={theme.themeId} xs={12} sm={6} md={4} lg={3}>
+          <ThemeCard theme={theme} />
+        </Grid>
+      ))}
+    </Grid>
+  );
+}

package/src/gui/components/molecules/Theme/ThemesCatalog/ThemesCatalog.types.ts

@@ -0,0 +1,34 @@
+import type { SxProps, Theme } from '@mui/system';
+export type ThemesCatalogVariant = 'grid' | 'list';
+
+/**
+ * Props passed directly to the ThemesCatalog React component.
+ */
+export interface ThemesCatalogProps {
+  /**
+   * Whether to display the themes as a grid or list.
+   */
+  variant?: ThemesCatalogVariant;
+  /**
+   * Custom styles for the component container.
+   */
+  sx?: SxProps<Theme>;
+}
+
+/**
+ * JSON/declarative spec for ThemesCatalog used in resolvers.
+ * This is the shape accepted by the resolver when rendering via config.
+ */
+export interface ThemesCatalogResolverSpec {
+  type?: 'ThemesCatalog';
+
+  /**
+   * Whether to render the themes in a grid or list layout.
+   */
+  variant?: ThemesCatalogVariant;
+
+  /**
+   * Styles applied to the root element.
+   */
+  sx?: SxProps<Theme>;
+}

package/src/gui/components/organism/ChatGPTInterface/ChatGPTInterface.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import ChatGPTInterface from "./ChatGPTInterface";
+
+const meta: Meta<typeof ChatGPTInterface> = {
+  title: "Organisms/ChatGPTInterface",
+  component: ChatGPTInterface,
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatGPTInterface>;
+
+export const Default: Story = {
+  render: () => <ChatGPTInterface />,
+};