this.gui 1.3.40 → 1.3.42

package/src/gui/contexts/RightSidebarContext.tsx

@@ -0,0 +1,25 @@
+import React, { createContext, useState } from 'react';
+
+export type RightSidebarView = 'rail' | 'expanded' | 'mobile';
+
+export type RightSidebarContextType = {
+  view: RightSidebarView;
+  setView: (view: RightSidebarView) => void;
+};
+
+export const RightSidebarContext = createContext<RightSidebarContextType | undefined>(undefined);
+
+export const RightSidebarProvider: React.FC<{ children: React.ReactNode; initialView?: RightSidebarView }> = ({
+  children,
+  initialView = 'rail',
+}) => {
+  const [view, setView] = useState<RightSidebarView>(initialView);
+
+  return (
+    <RightSidebarContext.Provider value={{ view, setView }}>
+      {children}
+    </RightSidebarContext.Provider>
+  );
+};
+
+export default RightSidebarProvider;

package/src/gui/contexts/ThemeContext.ts

@@ -0,0 +1,34 @@
+//src/themes/utils/themeContext.ts
+import React, { createContext, useContext } from 'react';
+import type { GuiContextValue } from '@/types/theme';
+/**
+ * ThemeContext
+ * ------------
+ * Provides access to the GUI theme context (`GuiContextValue`) throughout the application.
+ * 
+ * This context is intended to be consumed by components that need to access or manipulate:
+ *  - the current theme key (e.g., 'neurons-light')
+ *  - the selected family and mode
+ *  - available themes
+ *  - helper actions like `toggleMode`, `setMode`, etc.
+ * 
+ * The context value is expected to be provided by `GuiProvider`, which wraps the app.
+ */
+export const ThemeContext = createContext<GuiContextValue | undefined>(undefined);
+/**
+ * useThemeContext
+ * ---------------
+ * Custom hook to access the GUI theme context.
+ * 
+ * This hook ensures that it is only used within the `GuiProvider` tree.
+ * If accessed outside the provider, it throws an error to help with debugging.
+ * 
+ * @returns {GuiContextValue} - The full GUI theme context state and helpers.
+ */
+export const useThemeContext = (): GuiContextValue => {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useThemeContext must be used within a GuiProvider');
+  }
+  return context;
+};

package/src/gui/contexts/index.ts

@@ -0,0 +1,4 @@
+export * from './InsetsContext';
+export * from './LeftSidebarContext';
+export * from './RightSidebarContext';
+export * from './ThemeContext';

package/src/gui/hooks/index.ts

@@ -0,0 +1,11 @@
+// src/gui/hooks_index.ts
+export * from './useGuiMediaQuery';
+export * from './useGuiTheme';
+export * from './resolveColorToken';
+export * from './useInsets';
+export * from './useIsMobile';
+export * from './useIsTouchDevice';
+export * from './useViewportKey';
+export * from './useViewportProp';
+export * from './useLeftSidebar';
+export * from './useRightSidebar';

package/src/gui/hooks/resolveColorToken.ts

@@ -0,0 +1,39 @@
+//@/gui/hooks/resolveColorToken.ts
+/**
+ * Resolves a color token to a valid CSS color string.
+ *
+ * Supports raw CSS colors (e.g., '#fff', 'rgb(...)', 'hsl(...)'),
+ * and theme palette tokens such as 'primary.main', 'text.secondary', etc.
+ * Falls back to the raw token or undefined if it cannot be resolved.
+ *
+ * @param token - The color token or raw color string to resolve.
+ * @param theme - Optional MUI Theme object to resolve from. Defaults to useTheme() if not provided.
+ * @returns A resolved color string or undefined.
+ */
+import { useTheme } from '@mui/material/styles';
+import type { Theme } from '@mui/material/styles';
+
+export function resolveColorToken(token?: string, theme?: Theme): string | undefined {
+  if (!token) return undefined;
+  const resolvedTheme = theme ?? useTheme();
+  const pal: any = resolvedTheme?.palette ?? {};
+
+  // If raw CSS color (e.g. #fff, rgb(...), etc), return as is
+  if (/^#|^rgb\(|^hsl\(/i.test(token)) return token;
+
+  // If dot notation, try to resolve from palette (e.g., text.secondary)
+  if (token.includes('.')) {
+    const v = token.split('.').reduce<any>((acc, k) => (acc ? acc[k] : undefined), pal);
+    if (typeof v === 'string') return v;
+    if (v && typeof v === 'object') return v.main ?? v.default;
+    return undefined;
+  }
+
+  // Otherwise, try direct access (e.g., 'primary', 'secondary')
+  const v = pal[token];
+  if (typeof v === 'string') return v;
+  if (v && typeof v === 'object') return v.main ?? v.default;
+  return undefined;
+}
+
+export default resolveColorToken;

package/src/gui/hooks/useCodeGen.ts

@@ -0,0 +1,12 @@
+import { useCallback } from "react";
+export function useCodeGen() {
+  const generate = useCallback(async (type: string, payload: any) => {
+    console.log(`[CodeGen] Request: ${type}`, payload);
+    // For now, fake output:
+    return `Generated mock output for: ${payload.prompt}`;
+  }, []);
+
+  return { generate };
+}
+
+export default useCodeGen;

package/src/gui/hooks/useGuiMediaQuery.ts

@@ -0,0 +1,18 @@
+// src/gui/hooks/useGuiMediaQuery.ts
+import { useTheme } from '@mui/material/styles';
+import useMediaQuery from '@mui/material/useMediaQuery';
+/**
+ * Wrapper around MUI's useMediaQuery that accepts either a string or a function
+ * returning a string based on the theme. This allows using theme breakpoints
+ * easily within the media query.
+ *
+ * @param query - The media query string or a function that takes the theme and returns a string.
+ * @returns A boolean indicating whether the document matches the media query.  
+ */
+export function useGuiMediaQuery(query: string | ((theme: ReturnType<typeof useTheme>) => string)) {
+  const theme = useTheme();
+  const finalQuery = typeof query === 'function' ? query(theme) : query;
+  return useMediaQuery(finalQuery);
+}
+
+export default useGuiMediaQuery;

package/src/gui/hooks/useGuiTheme.ts

@@ -0,0 +1,18 @@
+//@/gui/hooks/useTheme.ts
+/**
+ * React hook wrapper for MUI's `useTheme`.
+ *
+ * This wrapper ensures consistent typing across your app by casting the returned theme
+ * as the expected MUI `Theme`. It allows your components to remain decoupled from direct MUI imports,
+ * making future migration or customization easier.
+ */
+import { useTheme } from '@mui/material/styles';
+import type { Theme } from '@mui/material/styles';
+/**
+ * Returns the current theme typed as MUI's `Theme`.
+ */
+export function useGuiTheme(): Theme {
+  return useTheme() as Theme;
+}
+
+export default useGuiTheme;

package/src/gui/hooks/useInsets.ts

@@ -0,0 +1,26 @@
+//@/gui/hooks/useInsets.ts
+import { useContext } from 'react';
+import { useGuiTheme } from '@/gui/hooks';
+import { InsetsContext } from '@/gui/contexts';
+/**
+ * Returns the current insets from the InsetsContext when available.
+ * Falls back to the theme's static layout insets if the provider is missing.
+ */
+export function useInsets() {
+  const theme = useGuiTheme();
+  const context = useContext(InsetsContext);
+  if (context) return context.insets;
+  const fallback = theme.layout?.insets ?? { top: 0, right: 0, bottom: 0, left: 0 };
+  return { nav: 0, ...fallback };
+}
+/**
+ * Returns the updater function for insets, defaulting to a no-op if unavailable.
+ */
+export function useUpdateInsets() {
+  const theme = useGuiTheme() as any;
+  const context = useContext(InsetsContext);
+  if (context) return context.updateInsets;
+  return typeof theme.updateInsets === 'function' ? theme.updateInsets : () => {};
+}
+
+export default useInsets;

package/src/gui/hooks/useIsMobile.ts

@@ -0,0 +1,13 @@
+//@/gui/hooks/useIsMobile.ts
+import { useTheme } from '@mui/material/styles';
+import useMediaQuery from '@mui/material/useMediaQuery';
+/**
+ * Returns `true` if the viewport width is at or below the "sm" breakpoint (mobile).
+ * Abstracts the mobile detection logic away from MUI internals.
+ */
+export function useIsMobile(): boolean {
+  const theme = useTheme();
+  return useMediaQuery(theme.breakpoints.down('sm'));
+}
+
+export default useIsMobile;

package/src/gui/hooks/useIsTouchDevice.ts

@@ -0,0 +1,25 @@
+// src/gui/hooks/useIsTouchDevice.ts
+
+/**
+ * useIsTouchDevice
+ * ---------------
+ * Hook that determines whether the current device supports touch events.
+ * Useful for adapting UI behavior depending on touch capabilities.
+ */
+
+import { useEffect, useState } from 'react';
+
+export function useIsTouchDevice(): boolean {
+  const [isTouch, setIsTouch] = useState(false);
+
+  useEffect(() => {
+    const hasTouchSupport =
+      typeof window !== 'undefined' &&
+      ('ontouchstart' in window || navigator.maxTouchPoints > 0);
+    setIsTouch(hasTouchSupport);
+  }, []);
+
+  return isTouch;
+}
+
+export default useIsTouchDevice;

package/src/gui/hooks/useLeftSidebar.ts

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+
+import { LeftSidebarContext } from "@/gui/contexts";
+export const useLeftSidebar = () => {
+  const context = useContext(LeftSidebarContext);
+  if (!context) {
+    throw new Error('useLeftSidebar must be used within a SidebarProvider');
+  }
+  return context;
+};

package/src/gui/hooks/useRightSidebar.ts

@@ -0,0 +1,12 @@
+import { useContext } from 'react';
+import { RightSidebarContext } from '@/gui/contexts';
+
+export const useRightSidebar = () => {
+  const context = useContext(RightSidebarContext);
+  if (!context) {
+    throw new Error('useRightSidebar must be used within a RightSidebarProvider');
+  }
+  return context;
+};
+
+export default useRightSidebar;

package/src/gui/hooks/useViewportKey.ts

@@ -0,0 +1,19 @@
+//@/gui/hooks/useViewportKey.ts
+/**
+ * Hook that returns the current viewport key ('xs', 'sm', 'md', 'lg', or 'xl')
+ * based on the browser's window.innerWidth and the theme's breakpoints.
+ * Useful for conditional rendering or styling based on screen size.
+ */
+import { useTheme } from '@mui/material/styles';
+export function useViewportKey(): 'xs' | 'sm' | 'md' | 'lg' | 'xl' {
+  const theme = useTheme();
+  const width = typeof window !== 'undefined' ? window.innerWidth : 0;
+  const breakpoints = theme.breakpoints.values;
+  if (width < breakpoints.sm) return 'xs';
+  if (width < breakpoints.md) return 'sm';
+  if (width < breakpoints.lg) return 'md';
+  if (width < breakpoints.xl) return 'lg';
+  return 'xl';
+}
+
+export default useViewportKey;

package/src/gui/hooks/useViewportProp.ts

@@ -0,0 +1,17 @@
+//@/gui/hooks/useViewportProp.ts
+import { useTheme } from '@mui/material/styles';
+import { resolveViewportProp } from '@/types/viewport';
+/**
+ * useViewportProp allows you to pass responsive props as objects (e.g., { sm: 'value', md: 'value' })
+ * and resolves the appropriate value based on the current screen width and theme breakpoints.
+ * This helps in adapting component behavior or styling dynamically based on the viewport.
+ */
+export function useViewportProp<T extends string | number | boolean | object>(
+  prop: T | Partial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', T>> & { default?: T },
+  opts?: { widthOverride?: number }
+): T | undefined {
+  const theme = useTheme();
+  return resolveViewportProp(prop as any, theme, opts);
+}
+
+export default useViewportProp;

package/src/gui/registry/GuiRegistry.ts

@@ -0,0 +1,19 @@
+import { createRegistry } from "./factory";
+import ButtonResolver from "../atoms/Button/Button.resolver";
+import LinkResolver from "../atoms/Link/Link.resolver";
+import TypographyResolver from "@/gui/atoms/Typography/Typography.resolver";
+import DrawerResolver from "@/gui/atoms/Drawer/Drawer.resolver";
+import NavBarResolver from "@/gui/Theme/Layout/TopBar/TopBar.resolver";
+import FooterResolver from "@/gui/Layouts/ResponsiveUI/Footer/Footer.resolver";
+// etc...
+export const GuiRegistry = createRegistry([
+  //Atoms
+  ButtonResolver,
+  TypographyResolver,
+  LinkResolver,
+  DrawerResolver,
+  //Molecules
+  NavBarResolver,
+  FooterResolver,
+  // ...
+]);

package/src/gui/registry/factory.ts

@@ -0,0 +1,12 @@
+import type { RegistryEntry, GuiRegistry } from "./types";
+
+export function createRegistry(entries: RegistryEntry[]): GuiRegistry {
+  return entries.reduce<GuiRegistry>((acc, e) => {
+    acc[e.type] = e;
+    return acc;
+  }, {} as GuiRegistry);
+}
+
+export function extendRegistry(base: GuiRegistry, entries: RegistryEntry[]): GuiRegistry {
+  return { ...base, ...createRegistry(entries) };
+}

package/src/gui/registry/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./factory";
+export { GuiRegistry } from "./GuiRegistry";

package/src/gui/registry/types.ts

@@ -0,0 +1,6 @@
+import type * as React from "react";
+export type RegistryEntry = {
+  type: string;
+  resolve: (spec: any, ctx?: ResolveCtx) => React.ReactElement | null;};
+export type GuiRegistry = Record<string, RegistryEntry>;
+export type ResolveCtx = { theme?: any; [key: string]: any };

package/src/gui/utils/nodeID.ts

@@ -0,0 +1,11 @@
+// src/gui/utils/nodeID.ts
+// Utility to ensure a unique node ID for each component in DOM. 
+// using crypto.randomUUID if available 
+// otherwise falling back to Math.random.
+export function ensureNodeId(type: string, providedId?: string): string {
+  if (providedId) return providedId;
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return `${type}-${crypto.randomUUID()}`;
+  }
+  return `${type}-${Math.random().toString(36).slice(2)}`;
+}

package/src/registry/GuiRegistry.ts

@@ -0,0 +1,19 @@
+import { createRegistry } from "./factory";
+import ButtonResolver from "../atoms/Button/Button.resolver";
+import LinkResolver from "../atoms/Link/Link.resolver";
+import TypographyResolver from "@/gui/atoms/Typography/Typography.resolver";
+import DrawerResolver from "@/gui/atoms/Drawer/Drawer.resolver";
+import NavBarResolver from "@/gui/Theme/Layout/TopBar/TopBar.resolver";
+import FooterResolver from "@/gui/Layouts/ResponsiveUI/Footer/Footer.resolver";
+// etc...
+export const GuiRegistry = createRegistry([
+  //Atoms
+  ButtonResolver,
+  TypographyResolver,
+  LinkResolver,
+  DrawerResolver,
+  //Molecules
+  NavBarResolver,
+  FooterResolver,
+  // ...
+]);

package/src/stories/01.Home.mdx

@@ -0,0 +1,22 @@
+<div
+  style={{
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: '70vh',
+    background: 'var(--gui-bg-default)',
+    color: 'var(--gui-text-primary)',
+    padding: '40px',
+  }}
+>
+  <img
+    src="/GUI.png"
+    alt="This.GUI"
+    style={{ width: '377px', height: 'auto', imageRendering: 'auto', marginBottom: '10px', marginTop: '-34px' }}
+  />
+  <h1 style={{ fontSize: '4rem', margin: '0 0 5px 0' }}>.GUI</h1>
+  <div style={{ maxWidth: '600px', textAlign: 'center', fontSize: '1.2rem', lineHeight: '1.3', marginTop: '-8px' }}>
+    A collection of components and building blocks for the <a href="https://neurons.me" target="_blank" rel="noopener noreferrer">neurons.me</a> environment, enabling declarative GUI generation powered by AI.
+  </div>
+</div>

package/src/stories/02.Understanding.This.GUI.mdx

@@ -0,0 +1,149 @@
+# Declarative GUI with `this.GUI`
+`this.GUI` is designed as a **declarative layout system**, where all building blocks (NavBar, Drawers, StickyOptions, Footer) expose **clear JSON-friendly props**.  
+This **allows UIs to be described** and even generated by tools like **LLMs**, using nothing more than structured data.
+
+---
+
+## 🔑 Core Idea
+- Every component exposes a **schema-like props API**.
+- Layout respects **insets** (nav height, drawer widths) reported into the theme via `CustomThemeProvider`.
+- The provider also mirrors these values into CSS variables (`--gui-inset-left`, `--gui-inset-right`, `--gui-nav-height`).
+- With this contract, GUIs can be built from **JSON specs** instead of imperative React code.
+
+Example JSON spec:
+
+```json
+{
+  "route": "/dashboard",
+  "layout": {
+    "navbar": { "title": "Dashboard", "position": "fixed" },
+    "stickyOptions": {
+      "items": [
+        { "icon": "mui:BarChart", "label": "Stats", "href": "/stats" },
+        { "icon": "lucide:bolt", "label": "Power", "href": "/power" }
+      ]
+    },
+    "drawerLeft": { "title": "Menu", "items": [...] },
+    "drawerRight": { "title": "Context", "items": [...] },
+    "footer": { "text": "© 2025 neurons.me" }
+  }
+}
+
+Your renderer simply hydrates this into React components.
+
+
+---
+
+## 📦 Components
+
+### NavBar
+
+**Props:**
+- `title`: string
+- `logo`: string (URL)
+- `NavBarLinks`: array of `{ label, href, icon?, children? }`
+- `position`: `"fixed"` | `"static"` | `"sticky"` (default: `"fixed"`)
+- `showMenuButton`, `showThemeToggle`
+
+NavBar measures its height and updates `theme.layout.insets.nav`.
+
+```jsx
+<NavBar title="Demo" position="fixed" />
+```
+
+---
+
+### LeftDrawer & RightDrawer
+
+**Props:**
+- `drawerWidth`: number (default: 260)
+- `variant`: `"permanent"` | `"temporary"` (auto-chooses based on screen size)
+- `title`: optional with label + icon
+
+Each drawer updates `theme.layout.insets.left` or `theme.layout.insets.right` when permanent.
+
+```jsx
+<LeftDrawer title="Menu" items={[{ icon: 'mui:Home', label: 'Home' }]} />
+<RightDrawer title="Context" items={[{ icon: 'mui:Info', label: 'Details' }]} />
+```
+
+---
+
+### StickyOptionsTop
+
+Compact quick-actions bar that lives under the NavBar.
+
+**Props:**
+- `items`: actions `{ icon, label?, href?, iconColor?, variant? }`
+- `positioning`: `{ mode: 'sticky' | 'fixed', topOffset, reserveSpace }`
+- `mobileVariant`: `"auto"` | `"fab"` | `"inline"`
+- `dense`: boolean
+
+```jsx
+<StickyOptionsTop
+  items={[
+    { icon: 'mui:Settings', label: 'Settings', href: '/settings' },
+    { icon: 'lucide:bolt', label: 'Power', href: '/power', iconColor: 'primary' }
+  ]}
+  positioning={{ mode: 'sticky' }}
+/>
+```
+
+---
+
+### Footer
+
+**Props:**
+- `text`: string or ReactNode
+- Automatically respects left/right insets from permanent drawers.
+
+```jsx
+<Footer text="© 2025 neurons.me" />
+```
+
+---
+
+## 🌐 Why Declarative?
+
+Every prop is JSON-serializable, so LLMs or external systems can generate full UIs declaratively:
+- “Add a right drawer with a title and an insights icon”
+- “Place a sticky options bar under the navbar with capture + settings”
+- “On /reports, show the drawer and a compact navbar”
+
+These map directly into JSON specs that your app hydrates into React.
+
+---
+
+## 🚀 Benefits
+- **Schema-driven:** easy to serialize, validate, and diff.
+- **LLM-ready:** prompt-to-UI becomes natural.
+- **Layout-safe:** insets keep everything aligned automatically.
+- **Composable:** any route can declare its layout in one object.
+
+---
+
+## Example: Full Route Layout
+
+```jsx
+<NavBar title="Dashboard" />
+<LeftDrawer title="Menu" />
+<StickyOptionsTop items={items} />
+<PageContent />
+<Footer text="© 2025 neurons.me" />
+```
+
+Or as JSON:
+
+```json
+{
+  "navbar": { "title": "Dashboard" },
+  "drawerLeft": { "title": "Menu" },
+  "stickyOptions": { "items": [ ... ] },
+  "footer": { "text": "© 2025 neurons.me" }
+}
+```
+
+---
+That’s the philosophy: declarative contracts for every GUI building block, so your UI can be described, generated, and remixed by humans, scripts, or LLMs.
+---
+

package/src/stories/Theme/Palette.stories.tsx

@@ -0,0 +1,86 @@
+import React from 'react';
+import { Meta, StoryFn } from '@storybook/react';
+import { useTheme, Box, Typography } from '@mui/material';
+
+const meta: Meta = {
+  title: 'Theme/Palette',
+};
+
+export default meta;
+
+const PaletteViewer: React.FC = () => {
+  const theme = useTheme();
+  const palette = theme.palette;
+
+  return (
+    <Box
+      sx={{
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))',
+        gap: 2,
+        maxHeight: '80vh',
+        overflowY: 'auto',
+        p: 2,
+      }}
+    >
+      {Object.entries(palette).map(([colorKey, colorValue]) => {
+        if (typeof colorValue === 'string') {
+          // Sometimes palette keys can be strings (rare)
+          return (
+            <Box key={colorKey} sx={{ border: '1px solid', borderColor: 'divider', borderRadius: 1, p: 1 }}>
+              <Typography variant="subtitle1" gutterBottom>
+                {colorKey}
+              </Typography>
+              <Box
+                sx={{
+                  backgroundColor: colorValue,
+                  height: 48,
+                  borderRadius: 1,
+                  mb: 1,
+                }}
+              />
+              <Typography variant="caption">{colorValue}</Typography>
+            </Box>
+          );
+        }
+
+        if (typeof colorValue === 'object' && colorValue !== null) {
+          return (
+            <Box
+              key={colorKey}
+              sx={{ border: '1px solid', borderColor: 'divider', borderRadius: 1, p: 1, display: 'flex', flexDirection: 'column' }}
+            >
+              <Typography variant="subtitle1" gutterBottom>
+                {colorKey}
+              </Typography>
+              {Object.entries(colorValue).map(([shadeKey, shadeValue]) => {
+                if (typeof shadeValue !== 'string') return null;
+                return (
+                  <Box key={shadeKey} sx={{ mb: 1 }}>
+                    <Box
+                      sx={{
+                        backgroundColor: shadeValue,
+                        height: 32,
+                        borderRadius: 1,
+                        mb: 0.5,
+                        border: '1px solid',
+                        borderColor: 'divider',
+                      }}
+                    />
+                    <Typography variant="caption" sx={{ userSelect: 'text' }}>
+                      {shadeKey}: {shadeValue}
+                    </Typography>
+                  </Box>
+                );
+              })}
+            </Box>
+          );
+        }
+
+        return null;
+      })}
+    </Box>
+  );
+};
+
+export const Default: StoryFn = () => <PaletteViewer />;