this.gui 1.3.24 → 1.3.26

package/src/gui/apis/codegen.api.ts

@@ -0,0 +1,38 @@
+/**
+ * codegen.api.ts
+ * -----------------
+ * API helper for generating code via OpenAI or local this.env endpoint.
+ * Centralizes all network logic for the ChatGPTInterface.
+ */
+
+export interface CodeGenRequest {
+  type: string;
+  prompt: string;
+}
+
+export interface CodeGenResponse {
+  output: string;
+}
+
+export async function generateCode(
+  { type, prompt }: CodeGenRequest,
+  endpoint: string = "/api/codegen"
+): Promise<CodeGenResponse> {
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type, prompt }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to generate code: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    return { output: data.output || "No output received." };
+  } catch (error: any) {
+    console.error("[CodeGen API] Error:", error);
+    return { output: `Error: ${error.message || "Unknown error."}` };
+  }
+}

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

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+import AppBar from './AppBar';
+import type { RegistryEntry } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import type { AppBarResolverSpec as AppBarSpec } from './AppBar.types';
+
+/**
+ * AppBarResolver
+ * - Maps a JSON-friendly spec to <AppBar /> props.
+ * - Keeps MUI polymorphism intact (`component` passthrough).
+ * - Allows `sx`, ids and className for styling & targeting.
+ */
+const AppBarResolver: RegistryEntry = {
+  type: 'AppBar',
+  resolve(spec: AppBarSpec) {
+    const p = spec.props ?? {};
+    const rootProps: any = {
+      position: p.position ?? 'fixed',
+      color: p.color ?? 'default',
+      elevation: p.elevation,
+      enableColorOnDark: p.enableColorOnDark,
+      sx: p.sx,
+      id: ensureNodeId('appbar', p.id),
+      className: p.className,
+      'data-testid': p['data-testid'],
+    };
+
+    if (p.component) {
+      rootProps.component = p.component;
+    }
+
+    return (
+      <AppBar {...rootProps}>
+        {p.children}
+      </AppBar>
+    );
+  },
+};
+
+export default AppBarResolver;

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

@@ -0,0 +1,225 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AppBar, Toolbar, Typography, Box, Button } from '@/gui/components/atoms';
+
+// ======================= Meta =======================
+const meta: Meta<typeof AppBar> = {
+  title: 'Atoms/Containers/AppBar',
+  component: AppBar,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 0, minHeight: 240 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **AppBar** atom is a thin wrapper around MUI's \`AppBar\` that keeps the original API while letting you style it with \`sx\` and use it declaratively through the **resolver**.
+
+---
+## Features
+- Positions: \`fixed\`, \`absolute\`, \`sticky\`, \`static\`, \`relative\`.
+- Colors: \`default\`, \`inherit\`, \`primary\`, \`secondary\`, \`transparent\`. AppBar **only supports** these colors for the \`color\` prop.
+- Note: \`success\`, \`info\`, \`warning\`, and \`error\` are **not supported** by the \`color\` prop. Use \`sx={{ bgcolor: '...' }}\` for these colors.
+- Additional theme colors can be applied via \`sx={{ bgcolor: 'success.main' }}\` etc.
+- Elevation & dark-mode override with \`enableColorOnDark\`.
+- Accepts any children (e.g., \`<Toolbar/>\`, actions, brand, etc.).
+- Fully themeable via **This.GUI** tokens and \`sx\`.
+
+---
+## Key Props
+- \`position?: 'fixed' | 'absolute' | 'sticky' | 'static' | 'relative'\`.
+- \`color?: 'default' | 'inherit' | 'primary' | 'secondary' | 'transparent'\` — AppBar **only supports** these values.
+- \`success\`, \`info\`, \`warning\`, and \`error\` are **not supported** by \`color\`; use \`sx={{ bgcolor: '...' }}\` instead.
+- \`elevation?: number\`.
+- \`enableColorOnDark?: boolean\`.
+- \`sx?: object\` — granular styling via the system.
+
+---
+## Basic usage (React)
+~~~tsx
+import { AppBar, Toolbar, Typography, Button, Box } from '@/gui/atoms';
+
+<AppBar position="fixed" color="default" sx={{ borderBottom: '1px solid', borderColor: 'divider' }}>
+  <Toolbar variant="dense">
+    <Typography variant="h6" sx={{ flexGrow: 1 }}>My App</Typography>
+    <Button variant="text">Login</Button>
+  </Toolbar>
+</AppBar>
+~~~
+
+---
+## Declarative JSON / Config usage
+This GUI's **resolver** lets you describe an app bar via a config object. Example payload for the \`AppBarResolver\`:
+
+~~~json
+{
+  "type": "AppBar",
+  "props": {
+    "position": "fixed",
+    "color": "default",
+    "sx": { "borderBottom": "1px solid", "borderColor": "divider" },
+    "children": {
+      "type": "Toolbar",
+      "props": {
+        "variant": "dense",
+        "children": [
+          { "type": "Typography", "props": { "variant": "h6", "sx": { "flexGrow": 1 }, "children": "My App" } },
+          { "type": "Button", "props": { "variant": "text", "children": "Login" } }
+        ]
+      }
+    }
+  }
+}
+~~~
+
+> The resolver maps this spec to real React elements, preserving polymorphism and \`sx\` styling.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    position: {
+      control: { type: 'select' },
+      options: ['fixed', 'absolute', 'sticky', 'static', 'relative'],
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['default', 'inherit', 'primary', 'secondary', 'transparent'],
+    },
+    elevation: { control: { type: 'number' } },
+    enableColorOnDark: { control: { type: 'boolean' } },
+    // component polymorphism is supported but not exposed as a control in SB
+    component: { table: { disable: true } },
+  },
+  args: {
+    position: 'fixed',
+    elevation: 0,
+    enableColorOnDark: false,
+    sx: { borderBottom: '1px solid', borderColor: 'divider' },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof AppBar>;
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <AppBar {...args}>
+      <Toolbar variant="dense">
+        <Typography variant="h6" sx={{ flexGrow: 1 }}>Playground</Typography>
+        <Button variant="text">Action</Button>
+      </Toolbar>
+    </AppBar>
+  ),
+};
+
+export const Positions: Story = {
+  render: (args) => (
+    <div style={{ display: 'grid', gap: 16 }}>
+      {(['fixed', 'absolute', 'sticky', 'static', 'relative'] as const).map((pos) => (
+        <AppBar key={pos} {...args} position={pos}>
+          <Toolbar variant="dense">
+            <Typography variant="subtitle1" sx={{ flexGrow: 1 }}>
+              position = {pos}
+            </Typography>
+            <Button variant="text">Action</Button>
+          </Toolbar>
+        </AppBar>
+      ))}
+    </div>
+  ),
+};
+
+export const Colors: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+The AppBar component only supports the following values for the \`color\` prop: \`default\`, \`inherit\`, \`primary\`, \`secondary\`, and \`transparent\`.
+For colors like \`success\`, \`info\`, \`warning\`, and \`error\`, use the \`sx\` prop with \`bgcolor\` instead, e.g. \`sx={{ bgcolor: 'success.main' }}\`.
+        `,
+      },
+    },
+  },
+  args: { position: 'static' },
+  render: (args) => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      {(['default', 'inherit', 'primary', 'secondary', 'transparent'] as const).map((c) => (
+        <AppBar key={c} {...args} color={c}>
+          <Toolbar variant="dense">
+            <Typography variant="subtitle2" sx={{ flexGrow: 1 }}>color = {c}</Typography>
+            <Button variant="text">Action</Button>
+          </Toolbar>
+        </AppBar>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * The AppBar component does not support 'success', 'info', 'warning', or 'error' as values for the color prop.
+ * To use these colors, apply them via the sx prop with bgcolor instead.
+ */
+export const CustomColorsWithSx: Story = {
+  args: { position: 'static' },
+  render: (args) => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      {(['success.main', 'info.main', 'warning.main', 'error.main'] as const).map((bgcolor) => (
+        <AppBar key={bgcolor} {...args} sx={{ bgcolor }}>
+          <Toolbar variant="dense">
+            <Typography variant="subtitle2" sx={{ flexGrow: 1 }}>{`sx.bgcolor = ${bgcolor}`}</Typography>
+            <Button variant="text">Action</Button>
+          </Toolbar>
+        </AppBar>
+      ))}
+    </div>
+  ),
+};
+
+export const WithToolbar: Story = {
+  args: { position: 'static', color: 'default' },
+  render: (args) => (
+    <AppBar {...args} sx={{ px: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+      <Toolbar variant="dense">
+        <Typography variant="h6" sx={{ flexGrow: 1 }}>With Toolbar</Typography>
+        <Box sx={{ display: 'flex', gap: 1 }}>
+          <Button variant="text">Login</Button>
+          <Button variant="contained" color="primary">Sign up</Button>
+        </Box>
+      </Toolbar>
+    </AppBar>
+  ),
+};
+
+export const Elevation: Story = {
+  args: { position: 'static', color: 'default' },
+  render: (args) => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      {[0, 1, 2, 4, 8].map((elev) => (
+        <AppBar key={elev} {...args} elevation={elev}>
+          <Toolbar variant="dense">
+            <Typography variant="subtitle2" sx={{ flexGrow: 1 }}>elevation = {elev}</Typography>
+            <Button variant="text">Action</Button>
+          </Toolbar>
+        </AppBar>
+      ))}
+    </div>
+  ),
+};
+
+export const EnableColorOnDark: Story = {
+  args: { position: 'static', color: 'primary', enableColorOnDark: true },
+  render: (args) => (
+    <AppBar {...args}>
+      <Toolbar variant="dense">
+        <Typography variant="subtitle2" sx={{ flexGrow: 1 }}>enableColorOnDark = true</Typography>
+        <Button variant="text">Action</Button>
+      </Toolbar>
+    </AppBar>
+  ),
+};

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

@@ -0,0 +1,8 @@
+import React from 'react';
+import MuiAppBar from '@mui/material/AppBar';
+import type { AppBarProps } from './AppBar.types.ts';
+const AppBar = React.forwardRef<HTMLDivElement, AppBarProps>((props, ref) => {
+  return <MuiAppBar ref={ref} {...props} />;
+});
+AppBar.displayName = 'AppBar';
+export default AppBar;

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

@@ -0,0 +1,28 @@
+import type { AppBarProps as MuiAppBarProps } from '@mui/material/AppBar';
+
+/**
+ * AppBarProps
+ * -----------
+ * Extends MUI's AppBarProps to add This.GUI-specific fields (id, data-testid).
+ */
+export interface AppBarProps extends MuiAppBarProps {
+  /** Optional id for targeting/testing */
+  id?: string;
+  /** Optional data-testid for testing */
+  ['data-testid']?: string;
+}
+
+/**
+ * AppBarResolverSpec
+ * ------------------
+ * JSON-friendly spec for declarative usage.
+ */
+export type AppBarResolverSpec = {
+  type?: 'AppBar';
+  props?: Partial<AppBarProps> & {
+    /** Optional polymorphic component (Link, 'a', etc.) */
+    component?: React.ElementType;
+    /** Children to render inside the AppBar */
+    children?: React.ReactNode;
+  };
+};

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

@@ -0,0 +1,61 @@
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import Avatar from './Avatar';
+export type AvatarSpec = {
+  type: 'Avatar';
+  props?: {
+    children?: React.ReactNode;
+    alt?: string;
+    src?: string;
+    variant?: 'circular' | 'rounded' | 'square';
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    component?: React.ElementType;
+    as?: React.ElementType;
+    [key: string]: any;
+  };
+};
+
+const AvatarResolver: RegistryEntry = {
+  type: 'Avatar',
+  resolve(spec: AvatarSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const {
+      children,
+      alt,
+      src,
+      variant,
+      sx,
+      className,
+      id,
+      component,
+      as,
+      ...rest
+    } = p;
+
+    const resolvedComponent = component ?? as;
+    const avatarId = ensureNodeId('avatar', id);
+
+    return (
+      <Avatar
+        src={src}
+        alt={alt}
+        variant={variant}
+        sx={sx}
+        className={className}
+        id={avatarId}
+        data-testid={p['data-testid']}
+        {...(resolvedComponent ? { component: resolvedComponent } : {})}
+        {...rest}
+      >
+        {children}
+      </Avatar>
+    );
+  },
+};
+
+export default AvatarResolver;

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

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import Avatar from './Avatar';
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Atoms/Avatar',
+  component: Avatar,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+export const InitialsAvatar: Story = {
+  render: () => (
+    <Avatar>
+      AB
+    </Avatar>
+  ),
+  name: 'With Initials',
+};
+
+export const ImageAvatar: Story = {
+  render: () => (
+    <Avatar alt="Abella" src="https://i.pravatar.cc/150?img=32" />
+  ),
+  name: 'With Image',
+};
+
+export const SquareAvatar: Story = {
+  render: () => (
+    <Avatar variant="square">
+      SQ
+    </Avatar>
+  ),
+  name: 'Square Variant',
+};

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

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import MuiAvatar from '@mui/material/Avatar';
+
+/**
+ * This.GUI — Avatar (atom)
+ * Thin wrapper around MUI’s Avatar component.
+ *
+ * Supports standard avatar props like `src`, `alt`, `variant`, and `sx`.
+ * Enables consistent use of avatar styling across the system.
+ */
+const Avatar = MuiAvatar;
+export type AvatarProps = React.ComponentProps<typeof Avatar>;
+(Avatar as any).displayName = 'Gui.Avatar';
+export default Avatar;

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

@@ -0,0 +1,171 @@
+import * as React from 'react';
+import Box from './Box';
+import Link from '../Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for Box (polymorphic container)
+ *
+ * JSON-friendly rules:
+ * - Prefer `to` / `href` / `external` over passing a string `"Link"`.
+ * - We accept intrinsic element strings (e.g. 'div', 'section', 'span', 'a', 'img').
+ * - If `to` is present and no explicit React component was provided, we render with This.GUI `Link`.
+ * - If `href`/`external` are present and no explicit component was provided, we render an anchor (`'a'`).
+ * - When `component="img"`, image attributes (`src`, `alt`, `width`, `height`, etc.) are passed through.
+ */
+export type BoxSpec = {
+  type: 'Box';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism / routing
+  component?: React.ElementType | string;
+    as?: React.ElementType | string; // alias for component
+    to?: string;     // router target (when component={Link} or inferred)
+    href?: string;   // anchor target (when component='a' or inferred)
+    external?: boolean | 'true' | 1; // if truthy, anchor gets safe target/rel
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+
+    // IMG-specific (when component='img')
+    src?: string;
+    alt?: string;
+    width?: number | string;
+    height?: number | string;
+    loading?: 'eager' | 'lazy';
+    decoding?: 'auto' | 'sync' | 'async';
+    referrerPolicy?: React.HTMLAttributeReferrerPolicy;
+    sizes?: string;
+    srcSet?: string;
+
+    // Styling & misc
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Allow system props / arbitrary passthrough (gap, p, m, display, etc.)
+    [key: string]: any;
+  };
+};
+
+const BoxResolver: RegistryEntry = {
+  type: 'Box',
+  resolve(spec: BoxSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Decide polymorphic target (safe for JSON):
+    // - Accept real React components (functions/classes).
+    // - Accept intrinsic strings ('div','section','span','a','img', etc.) EXCEPT the string "Link".
+    // - Infer Link/'a' from `to`/`href` when no explicit component is provided.
+    const rawComp = p.component ?? p.as;
+
+    const isReactComp = typeof rawComp === 'function';
+    const isString = typeof rawComp === 'string';
+
+    // Normalize strings (e.g. 'Img' -> 'img'); disallow the literal "Link"
+    const normalizedString = isString ? String(rawComp).trim() : undefined;
+    const lowered = normalizedString ? normalizedString.toLowerCase() : undefined;
+    const isIntrinsicString = !!normalizedString && lowered !== 'link';
+
+    let component: any | undefined =
+      isReactComp ? (rawComp as React.ElementType) :
+      isIntrinsicString ? normalizedString :
+      undefined;
+
+    if (!component) {
+      if (p.to) {
+        component = Link;
+      } else if (p.href || p.external) {
+        component = 'a';
+      }
+    }
+
+    // Build routing/anchor props only if they match the chosen component
+    const routingProps: Record<string, any> = {};
+    if (component === Link && p.to) {
+      routingProps.to = p.to;
+    }
+    if (component === 'a') {
+      routingProps.href = p.href;
+      const isExternal = p.external === true || p.external === 'true' || p.external === 1;
+      if (isExternal) {
+        routingProps.target = p.target ?? '_blank';
+        routingProps.rel = p.rel ?? 'noopener noreferrer';
+      } else {
+        if (p.target) routingProps.target = p.target;
+        if (p.rel) routingProps.rel = p.rel;
+      }
+    }
+
+    // IMG specific passthrough (only when explicitly rendering an <img>)
+    const imgProps =
+      component === 'img'
+        ? {
+            src: p.src,
+            alt: p.alt,
+            width: p.width,
+            height: p.height,
+            loading: p.loading,
+            decoding: p.decoding,
+            referrerPolicy: p.referrerPolicy,
+            sizes: p.sizes,
+            srcSet: p.srcSet,
+          }
+        : {};
+
+    // Dev-time nudge if someone picked 'img' without a src
+    if (process.env.NODE_ENV !== 'production' && component === 'img' && !p.src) {
+      // eslint-disable-next-line no-console
+      console.warn('[Box.resolver] component="img" used without a `src` prop.');
+    }
+
+    // Collect common props and avoid leaking resolver-only keys
+    const {
+      children,
+      // resolver-only / routing keys to strip
+      as: _as,
+      to: _to,
+      href: _href,
+      external: _external,
+      target: _target,
+      rel: _rel,
+      // img-only keys already handled
+      src: _src,
+      alt: _alt,
+      width: _width,
+      height: _height,
+      loading: _loading,
+      decoding: _decoding,
+      referrerPolicy: _referrerPolicy,
+      sizes: _sizes,
+      srcSet: _srcSet,
+      // passthrough everything else (system props, data-*, aria-*, etc.)
+      ...rest
+    } = p;
+
+    // Build root props, conditionally attach `component`
+    const rootProps: Record<string, any> = {
+      sx: p.sx,
+      id: ensureNodeId('box', p.id),
+      className: p.className,
+      'data-testid': p['data-testid'],
+      ...routingProps,
+      ...imgProps,
+      ...rest,
+    };
+    if (component) {
+      rootProps.component = component;
+    }
+
+    return (
+      <Box {...rootProps}>
+        {children}
+      </Box>
+    );
+  },
+};
+
+export default BoxResolver;