this.gui 1.3.24 → 1.3.26

package/src/gui/me/utils/Context.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext, useState, useEffect } from "react";
+import { meCore, MeIdentity } from "./Logic";
+const MeContext = createContext<{ me: MeIdentity | null }>({ me: null });
+export const MeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [me, setMe] = useState<MeIdentity | null>(null);
+
+  useEffect(() => {
+    meCore.init().then(setMe);
+  }, []);
+
+  return <MeContext.Provider value={{ me }}>{children}</MeContext.Provider>;
+};
+
+export const useMe = () => useContext(MeContext);

package/src/gui/me/utils/hooks/useMe.js

@@ -0,0 +1,37 @@
+import { useState, useEffect } from "react";
+import { me } from "../../../../../../../../npm/this/me/dist/this-me.es";
+/**
+ * ✅ useMe - React bridge for `.me`
+ * Keeps React in sync with the live `me` instance.
+ */
+export default function useMe() {
+  const [status, setStatus] = useState(me.state.status);
+  const [listUs, setListUs] = useState(me.state.listUs || []);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    // ✅ Sync React state with me instance
+    const handleStatusChange = () => setStatus({ ...me.state.status });
+    const handleListUsChange = () => setListUs([...me.state.listUs]);
+    me.on("statusChange", handleStatusChange);
+    me.on("listUsChange", handleListUsChange);
+    // Initial load
+    (async () => {
+      setLoading(true);
+      await me.status(); // triggers internal update
+      await me.listUs(); // updates list
+      setLoading(false);
+    })();
+    return () => {
+      me.off("statusChange", handleStatusChange);
+      me.off("listUsChange", handleListUsChange);
+    };
+  }, []);
+  return {
+    status,
+    listUs,
+    loading,
+    checkStatus: () => me.status(),
+    fetchListUs: () => me.listUs(),
+    loadMe: (alias, hash) => me.loadMe(alias, hash),
+  };
+}

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 "../gui/atoms/Button/Button.resolver";
+import LinkResolver from "../gui/atoms/Link/Link.resolver";
+import TypographyResolver from "@/gui/atoms/Typography/Typography.resolver";
+import DrawerResolver from "@/gui/atoms/Drawer/Drawer.resolver";
+import NavBarResolver from "@/gui/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/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/registry/index.ts

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

package/src/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/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 neurons.me 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 />;

package/src/stories/Theme/ThemeViewer.stories.tsx

@@ -0,0 +1,91 @@
+/**
+ * ## Theme Viewer Story
+ *
+ * This story provides a live JSON visualization of your theme context and MUI theme.
+ *
+ * ### What you will see:
+ * - `mode`: Comes from your `ThemeContext`, shows if your theme is in `light` or `dark` mode.
+ * - `palette`: Full palette details from MUI's `createTheme`, including all primary/secondary colors, actions, background, etc.
+ * - `insets`: Comes from `InsetsContext`, gives layout-safe-area insets for notch-aware designs (top, right, bottom, left).
+ *
+ * ### Why use this?
+ * It’s useful for debugging:
+ * - If your theme is being applied correctly
+ * - How your layout adjusts with different inset values
+ * - How palettes resolve across modes
+ *
+ * Great for verifying dynamic theme changes or testing new color tokens.
+ */
+import type { Meta } from '@storybook/react';
+import { useTheme } from '@mui/material/styles';
+import { useThemeContext } from '@/gui/contexts/ThemeContext';
+import { useInsets } from '@/gui/hooks';
+
+/**
+ * Story: CurrentThemeState
+ *
+ * This Storybook story displays the current theme state injected via MUI's ThemeProvider
+ * along with custom context values such as `mode` (from ThemeContext) and `insets` (from InsetsContext).
+ *
+ * The output includes:
+ * - `mode`: Light/dark mode from the app's ThemeContext
+ * - `palette`: Full palette object from MUI's `createTheme`, including color tokens and UI actions
+ * - `insets`: Safe area insets (top/right/bottom/left) for layout padding/margin
+ *
+ * Useful for debugging how the current theme looks, understanding the applied color system,
+ * and ensuring injected context values are correctly picked up across the app.
+ */
+export const CurrentThemeState = () => {
+  const theme = useTheme();
+  const { mode, themeId } = useThemeContext();
+  const { insets } = useInsets();
+  return (
+    <pre style={{ padding: 16 }}>
+      <code>
+        {JSON.stringify(
+          {
+            mode,
+            themeId,
+            palette: theme.palette,
+            fontFamily: theme.typography?.fontFamily,
+            typography: theme.typography,
+            insets,
+          },
+          null,
+          2
+        )}
+      </code>
+    </pre>
+  );
+};
+
+export default {
+  title: 'Theme/Viewer',
+  component: CurrentThemeState,
+tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+This story renders the **active theme state** used throughout your app.
+
+### What you will see:
+- \`mode\`: Current light/dark mode from ThemeContext
+- \`palette\`: Full MUI palette object generated from createTheme(), including:
+  - primary, secondary, error, warning, success, info colors
+  - background and text colors
+  - action states (hover, focus, selected, etc.)
+- \`insets\`: Safe area layout padding (top/right/bottom/left) from InsetsContext (useful for notch-aware design)
+
+### Why this is useful:
+- Debug whether the correct theme is being used
+- Inspect how palette tokens resolve dynamically
+- Verify how inset values change (iOS, Android, desktop)
+- Helps debug dynamic theme toggles and token propagation
+
+Ideal for inspecting changes in real-time while modifying theme-related code or tokens.
+          `,
+      },
+    },
+  },
+} satisfies Meta<typeof CurrentThemeState>;

package/src/stories/Theme/Typography.stories.jsx

@@ -0,0 +1,211 @@
+// src/stories/Theme/Typography.stories.jsx
+import { Box, Typography, Paper, Divider, Stack, Chip } from '@mui/material';
+import { useTheme } from '@mui/material/styles';
+
+/**
+ * Small helper to render a sample block for a variant
+ */
+const TypeRow = ({ variant, sample = 'The quick brown fox jumps over the lazy dog 1234', extra }) => {
+  const theme = useTheme();
+  const v = theme.typography?.[variant] || {};
+  const lineHeight = typeof v.lineHeight === 'number' ? v.lineHeight : String(v.lineHeight || '');
+  const fontSize = v.fontSize || '';
+  const weight = v.fontWeight || '';
+
+  return (
+    <Paper
+      variant="outlined"
+      sx={{
+        p: 1.25,
+        borderColor: theme.custom?.border || theme.palette.divider,
+        bgcolor: 'background.paper',
+        minWidth: 280,
+        flex: '1 1 320px',
+      }}
+    >
+      <Typography variant="caption" sx={{ color: 'text.secondary', fontWeight: 700 }}>
+        {variant}
+      </Typography>
+      <Typography variant={variant} sx={{ mt: 0.5 }}>
+        {sample}
+      </Typography>
+      <Divider sx={{ my: 1 }} />
+      <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+        <strong>font-size:</strong> {fontSize}{'  '}
+        <strong>line-height:</strong> {lineHeight}{'  '}
+        <strong>font-weight:</strong> {weight || '—'}
+        {extra ? <> · {extra}</> : null}
+      </Typography>
+    </Paper>
+  );
+};
+
+const Section = ({ title, hint, children }) => (
+  <Box sx={{ my: 3 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+      <Typography variant="h5" sx={{ fontWeight: 700 }}>
+        {title}
+      </Typography>
+      {hint ? <Chip size="small" label={hint} /> : null}
+    </Box>
+    <Divider sx={{ my: 1.5 }} />
+    {children}
+  </Box>
+);
+
+/**
+ * Preview of the main typography scale coming from the active theme.
+ * Uses whatever your token engine compiled into theme.typography.
+ */
+function TypographyScale() {
+  const theme = useTheme();
+
+  const variants = [
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'subtitle1',
+    'body1',
+    'body2',
+    'button',
+  ];
+
+  return (
+    <Box sx={{ p: 2, bgcolor: 'background.default', color: 'text.primary' }}>
+      <Section title="Font Family">
+        <Typography variant="body2">
+          <strong>theme.typography.fontFamily:</strong>{' '}
+          <code>{theme.typography?.fontFamily}</code>
+        </Typography>
+      </Section>
+
+      <Section title="Variants">
+        <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+          {variants.map((v) => (
+            <TypeRow key={v} variant={v} />
+          ))}
+        </Stack>
+      </Section>
+    </Box>
+  );
+}
+
+/**
+ * Extra details from tokens exposed in the runtime:
+ * - lineHeights scale (if defined in theme.typography.lineHeights)
+ * - weights (if your tokens encode them)
+ */
+function TypographyDetails() {
+  const theme = useTheme();
+  const lh = theme.typography?.lineHeights || {};
+  const weights = {
+    bold: theme.typography?.fontWeightBold,
+    medium: theme.typography?.fontWeightMedium,
+    regular: theme.typography?.fontWeightRegular,
+  };
+
+  return (
+    <Box sx={{ p: 2, bgcolor: 'background.default', color: 'text.primary' }}>
+      <Section title="Line Heights Scale" hint="From tokens → theme.typography.lineHeights">
+        {Object.keys(lh).length ? (
+          <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+            {Object.entries(lh).map(([k, v]) => (
+              <Paper
+                key={k}
+                variant="outlined"
+                sx={{
+                  p: 1.25,
+                  minWidth: 160,
+                  borderColor: theme.custom?.border || theme.palette.divider,
+                }}
+              >
+                <Typography variant="body2" sx={{ fontWeight: 700 }}>
+                  {k}
+                </Typography>
+                <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+                  {String(v)}
+                </Typography>
+                <Divider sx={{ my: 1 }} />
+                <Typography sx={{ lineHeight: Number(v) || v }}>
+                  The quick brown fox jumps over the lazy dog.
+                </Typography>
+              </Paper>
+            ))}
+          </Stack>
+        ) : (
+          <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+            No custom line height scale found in theme.typography.lineHeights.
+          </Typography>
+        )}
+      </Section>
+
+      <Section title="Font Weights (if provided)">
+        <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+          {Object.entries(weights).map(([k, v]) => (
+            <Paper
+              key={k}
+              variant="outlined"
+              sx={{
+                p: 1.25,
+                minWidth: 160,
+                borderColor: theme.custom?.border || theme.palette.divider,
+              }}
+            >
+              <Typography variant="body2" sx={{ fontWeight: 700 }}>
+                {k}
+              </Typography>
+              <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+                {v ?? '—'}
+              </Typography>
+              <Divider sx={{ my: 1 }} />
+              <Typography sx={{ fontWeight: v ?? 600 }}>
+                The quick brown fox jumps over the lazy dog.
+              </Typography>
+            </Paper>
+          ))}
+        </Stack>
+      </Section>
+    </Box>
+  );
+}
+
+export default {
+  title: 'Theme/Typography',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Typography scale compiled from tokens. Shows font family, variant sizes/weights/line-height, and optional line-height scale & weights if your tokens expose them.',
+      },
+    },
+  },
+};
+
+export const Scale = {
+  name: 'Scale',
+  render: () => <TypographyScale />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Core typography variants from the active theme (h1–h5, subtitle1, body1, body2, button).',
+      },
+    },
+  },
+};
+
+export const Details = {
+  name: 'Details (Line Heights & Weights)',
+  render: () => <TypographyDetails />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Optional token-driven extras: line-height scale and font weights if present in the compiled theme.',
+      },
+    },
+  },
+};