this.gui 1.0.18 → 1.1.0

package/src/context/GuiProvider.tsx

@@ -0,0 +1,243 @@
+// src/context/GuiProvider.tsx
+import React, { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { ThemeProvider, CssBaseline } from '@mui/material';
+import type { Theme } from '@mui/material/styles';
+import { getTheme, AVAILABLE_THEMES } from '../themes';
+
+/**
+ * New theme model (family + mode)
+ * --------------------------------
+ * AVAILABLE_THEMES now comes as a flat list of entries like:
+ *   { id: 'neurons-light', family: 'neurons', name: 'Neurons Light', mode: 'light', manifest }
+ * We normalize that into:
+ *   • availableFlat: same flat array
+ *   • availableFamilies: [{ family, name, manifest, modes: ['light','dark'] }]
+ *
+ * Provider state keeps a single `themeKey` (e.g. 'neurons-light').
+ * We expose helpers to change mode or family without callers knowing the key format.
+ */
+
+// -------------------------------- Types --------------------------------
+export type ThemeMode = 'light' | 'dark';
+
+export type ThemeEntry = {
+  id: string;
+  family: string;
+  name?: string;
+  mode: ThemeMode;
+  manifest?: Record<string, any>;
+};
+
+export type ThemeFamilyGroup = {
+  family: string;
+  name?: string;
+  manifest?: Record<string, any>;
+  modes: ThemeMode[];
+};
+
+export type Insets = { left: number; right: number; nav: number };
+
+export type GuiContextValue = {
+  // identity of the active theme entry (e.g. 'neurons-light')
+  themeKey: string;
+  setThemeKey: React.Dispatch<React.SetStateAction<string>>;
+
+  // derived
+  family: string;
+  mode: ThemeMode;
+
+  // catalog
+  availableFlat: ThemeEntry[];
+  availableFamilies: ThemeFamilyGroup[];
+  getManifestForFamily: (family: string) => Record<string, any>;
+
+  // actions
+  setMode: (mode: ThemeMode) => void;
+  setFamilyAndMode: (family: string, mode: ThemeMode) => void;
+  toggleMode: () => void;
+};
+
+export type GuiProviderProps = {
+  initialTheme?: string;
+  children?: React.ReactNode;
+};
+
+// Normalize AVAILABLE_THEMES as ThemeEntry[] (best-effort)
+const THEMES_SOURCE: ThemeEntry[] = Array.isArray(AVAILABLE_THEMES)
+  ? (AVAILABLE_THEMES as any[]).map((e) => ({
+      id: String(e?.id ?? `${e?.family ?? 'neurons'}-${e?.mode ?? 'dark'}`),
+      family:
+        String((e?.family ?? String(e?.id ?? '').replace(/-(light|dark)$/i, '')) || 'default'),
+      name: e?.name ?? e?.family ?? e?.id,
+      mode: (String(e?.mode ?? (String(e?.id).includes('dark') ? 'dark' : 'light')).toLowerCase() as ThemeMode),
+      manifest: (e?.manifest ?? {}) as Record<string, any>,
+    }))
+  : [];
+
+// Context (with safe defaults for tooling/tests)
+const ThemeCtx = createContext<GuiContextValue>({
+  themeKey: 'neurons-dark',
+  setThemeKey: () => {},
+  family: 'neurons',
+  mode: 'dark',
+  availableFlat: [],
+  availableFamilies: [],
+  getManifestForFamily: () => ({}),
+  setMode: () => {},
+  setFamilyAndMode: () => {},
+  toggleMode: () => {},
+});
+
+export function GuiProvider({ initialTheme = 'neurons-dark', children }: GuiProviderProps) {
+  // Persist last chosen `themeKey`
+  const [themeKey, setThemeKey] = useState<string>(() => {
+    try {
+      return localStorage.getItem('this.gui:theme') || initialTheme;
+    } catch {
+      return initialTheme;
+    }
+  });
+
+  useEffect(() => {
+    try {
+      localStorage.setItem('this.gui:theme', themeKey);
+    } catch {}
+  }, [themeKey]);
+
+  // Flat catalog straight from AVAILABLE_THEMES (normalized)
+  const availableFlat = useMemo<ThemeEntry[]>(() => {
+    return THEMES_SOURCE.map((e) => ({
+      id: e.id || `${e.family}-${e.mode}`,
+      family: e.family || String(e.id || '').replace(/-(light|dark)$/i, '') || 'default',
+      name: e.name || e.family || e.id,
+      mode: (e.mode ?? (String(e.id).includes('dark') ? 'dark' : 'light')) as ThemeMode,
+      manifest: e.manifest || {},
+    })).filter((e) => !!e.id && !!e.family && !!e.mode);
+  }, []);
+
+  // Group by family to know which modes each theme provides
+  const availableFamilies = useMemo<ThemeFamilyGroup[]>(() => {
+    const byFamily = new Map<string, ThemeFamilyGroup>();
+    for (const it of availableFlat) {
+      const curr: ThemeFamilyGroup =
+        byFamily.get(it.family) || {
+          family: it.family,
+          name: (it.manifest as any)?.name || it.family,
+          manifest: it.manifest,
+          modes: [] as ThemeMode[],
+        };
+      if (!curr.modes.includes(it.mode)) curr.modes.push(it.mode);
+      byFamily.set(it.family, curr);
+    }
+    return Array.from(byFamily.values());
+  }, [availableFlat]);
+
+  // Derive family/mode from active key
+  const active = useMemo<ThemeEntry>(() => {
+    const found = availableFlat.find((e) => e.id === themeKey);
+    if (found) return found;
+    // fallback: try to coerce from saved string
+    const isDark = /dark$/i.test(themeKey);
+    const fam = String(themeKey).replace(/-(light|dark)$/i, '') || 'neurons';
+    // pick a valid entry in that family
+    const fallback =
+      availableFlat.find((e) => e.family === fam && e.mode === (isDark ? 'dark' : 'light')) ||
+      availableFlat[0];
+    return (
+      fallback || { id: 'neurons-dark', family: 'neurons', mode: 'dark', manifest: {} }
+    ) as ThemeEntry;
+  }, [themeKey, availableFlat]);
+
+  // Build MUI theme from tokens using the single source of truth: themeKey
+  const theme = useMemo<Theme>(() => getTheme({ key: active.id }) as Theme, [active.id]);
+
+  // Insets state (unchanged)
+  const [insets, setInsets] = useState<Insets>({ left: 0, right: 0, nav: 0 });
+  const updateInsetsCb = React.useCallback(
+    ({ left, right, nav }: Partial<Insets> = {}) => {
+      setInsets((prev) => {
+        const next: Insets = {
+          left: left != null ? left : prev.left,
+          right: right != null ? right : prev.right,
+          nav: nav != null ? nav : prev.nav,
+        };
+        if (next.left === prev.left && next.right === prev.right && next.nav === prev.nav)
+          return prev;
+        return next;
+      });
+    },
+    []
+  );
+
+  useEffect(() => {
+    // Browser-only side effect: safe in CSR; skipped in SSR
+    if (typeof document !== 'undefined') {
+      const style = document.documentElement.style;
+      style.setProperty('--gui-inset-left', `${insets.left || 0}px`);
+      style.setProperty('--gui-inset-right', `${insets.right || 0}px`);
+      style.setProperty('--gui-nav-height', `${insets.nav || 0}px`);
+    }
+  }, [insets]);
+
+  // Inject insets helpers into the theme object
+  const themed = useMemo(() => {
+    // Note: we intentionally use `any` to avoid module augmentation here.
+    const t: any = { ...theme };
+    t.layout = { ...(theme as any).layout, insets: { left: insets.left || 0, right: insets.right || 0, nav: insets.nav || 0 } };
+    t.updateInsets = updateInsetsCb;
+    return t as Theme & { layout: { insets: Insets }; updateInsets: typeof updateInsetsCb };
+  }, [theme, insets, updateInsetsCb]);
+
+  // Ensure saved key is valid with the current catalog
+  useEffect(() => {
+    if (availableFlat.length === 0) return;
+    const ok = availableFlat.some((e) => e.id === themeKey);
+    if (!ok) setThemeKey(availableFlat[0].id);
+  }, [availableFlat, themeKey]);
+
+  // Helpers ------------------------------------------------------------
+  const getManifestForFamily = (family: string): Record<string, any> => {
+    const fam = availableFamilies.find((f) => f.family === family);
+    return fam?.manifest || {};
+  };
+
+  const setMode = (mode: ThemeMode) => {
+    const target = availableFlat.find((e) => e.family === active.family && e.mode === mode);
+    if (target) setThemeKey(target.id);
+  };
+
+  const setFamilyAndMode = (family: string, mode: ThemeMode) => {
+    const target =
+      availableFlat.find((e) => e.family === family && e.mode === mode) ||
+      availableFlat.find((e) => e.family === family); // any mode of that family
+    if (target) setThemeKey(target.id);
+  };
+
+  const toggleMode = () => setMode(active.mode === 'dark' ? 'light' : 'dark');
+
+  const ctxValue: GuiContextValue = useMemo(
+    () => ({
+      themeKey: active.id,
+      setThemeKey,
+      family: active.family,
+      mode: active.mode,
+      availableFlat,
+      availableFamilies,
+      getManifestForFamily,
+      setMode,
+      setFamilyAndMode,
+      toggleMode,
+    }),
+    [active.id, active.family, active.mode, availableFlat, availableFamilies]
+  );
+
+  return (
+    <ThemeProvider theme={themed}>
+      <CssBaseline />
+      <ThemeCtx.Provider value={ctxValue}>{children}</ThemeCtx.Provider>
+    </ThemeProvider>
+  );
+}
+
+export const useThemeContext = () => useContext(ThemeCtx);
+export default GuiProvider;

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

@@ -0,0 +1,77 @@
+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';
+
+/**
+ * Declarative spec for AppBar.
+ * This is the JSON-friendly shape your renderer/LLM can emit.
+ */
+type AppBarSpec = {
+  type: 'AppBar';
+  props?: {
+    /** Content inside the AppBar (text, Toolbar, actions, etc.) */
+    children?: React.ReactNode;
+
+    /** Visual props (passthrough to MUI AppBar) */
+    position?: 'fixed' | 'absolute' | 'sticky' | 'static' | 'relative';
+    color?:
+      | 'inherit'
+      | 'default'
+      | 'primary'
+      | 'secondary'
+      | 'transparent'
+      | 'info'
+      | 'success'
+      | 'warning'
+      | 'error';
+    elevation?: number;
+    enableColorOnDark?: boolean;
+    sx?: SxProps<Theme>;
+
+    /** Polymorphism passthrough (AppBar extends Paper → supports `component`) */
+    component?: React.ElementType;
+
+    /** Common DOM props */
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+  };
+};
+
+/**
+ * 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/atoms/AppBar/AppBar.stories.tsx

@@ -0,0 +1,232 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+import { AppBar, Toolbar, Typography, Box, Button } from '@/gui/atoms';
+
+// ======================= Meta =======================
+const meta: Meta<typeof AppBar> = {
+  title: 'Atoms/AppBar',
+  component: AppBar,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 0, minHeight: 240 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  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/atoms/AppBar/AppBar.tsx

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