this.gui 1.3.41 → 1.3.42

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "this.gui",
   "private": false,
-  "version": "1.3.41",
+  "version": "1.3.42",
   "type": "module",
   "main": "./dist/this.gui.cjs",
   "module": "./dist/this.gui.es.js",
@@ -22,7 +22,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "bin": {
     "gui": "./dist/bin/cli.js"

package/src/GUI.tsx

@@ -0,0 +1,46 @@
+// src/GUI.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { GuiProvider } from '../index';
+import { QRouter } from '@/QRouter/QRouter';
+
+export const GUI = ({ title = 'this.GUI', children }: { title?: string; children?: React.ReactNode }) => {
+  return (
+    <GuiProvider>
+      <QRouter>
+        <main style={{ padding: '2rem' }}>
+          <h1>{title}</h1>
+          {children ?? <p>Ready to render declarative GUI components.</p>}
+        </main>
+      </QRouter>
+    </GuiProvider>
+  );
+};
+
+// ✅ Register as a Web Component for HTML usage
+if (typeof window !== 'undefined' && !customElements.get('gui-app')) {
+  customElements.define(
+    'gui-app',
+    class extends HTMLElement {
+      connectedCallback() {
+        const mount = document.createElement('div');
+        this.appendChild(mount);
+        ReactDOM.createRoot(mount).render(<GUI />);
+        console.log('[GUI] <gui-app> mounted');
+      }
+    }
+  );
+}
+
+// ✅ Auto-bootstrap if loaded directly (e.g., via <script src="this.gui.umd.js">)
+if (typeof window !== 'undefined') {
+  window.addEventListener('DOMContentLoaded', () => {
+    const rootTag = document.querySelector('gui-app');
+    if (rootTag) return; // already handled by custom element
+    const auto = document.getElementById('root');
+    if (auto) {
+      ReactDOM.createRoot(auto).render(<GUI />);
+      console.log('[GUI] Auto-booted inside #root');
+    }
+  });
+}

package/src/QRouter/QRegistry.tsx

@@ -0,0 +1,53 @@
+import React, { createContext, useContext, useState, ReactNode } from "react";
+export type QuantumNode = {
+  path: string;
+  derivedAt: number;
+  active?: boolean;
+};
+
+type QuantumRegistryContextType = {
+  nodes: QuantumNode[];
+  registerNode: (path: string) => void;
+  unregisterNode: (path: string) => void;
+  setActiveNode: (path: string) => void;
+};
+
+const QuantumRegistryContext = createContext<QuantumRegistryContextType | undefined>(undefined);
+export const QRegistryProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
+  const [nodes, setNodes] = useState<QuantumNode[]>([]);
+  const registerNode = (path: string) => {
+    setNodes((prev) => {
+      if (prev.find((n) => n.path === path)) return prev;
+      return [...prev, { path, derivedAt: Date.now(), active: false }];
+    });
+  };
+
+  const unregisterNode = (path: string) => {
+    setNodes((prev) => prev.filter((n) => n.path !== path));
+  };
+
+  const setActiveNode = (path: string) => {
+    setNodes((prev) =>
+      prev.map((n) => ({
+        ...n,
+        active: n.path === path,
+      }))
+    );
+  };
+
+  return (
+    <QuantumRegistryContext.Provider value={{ nodes, registerNode, unregisterNode, setActiveNode }}>
+      {children}
+    </QuantumRegistryContext.Provider>
+  );
+};
+
+export const useQuantumRegistry = () => {
+  const context = useContext(QuantumRegistryContext);
+  if (!context) {
+    throw new Error("useQuantumRegistry must be used within a QRegistryProvider");
+  }
+  return context;
+};
+
+export default QRegistryProvider;

package/src/QRouter/QRouter.stories.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { QRouter } from "./QRouter";
+import { Link, Routes, Route } from "react-router-dom";
+
+const meta: Meta<typeof QRouter> = {
+  title: "Routing/QRouter",
+  component: QRouter,
+};
+
+export default meta;
+type Story = StoryObj<typeof QRouter>;
+
+export const Default: Story = {
+  render: () => (
+    <QRouter>
+      <div style={{ padding: "2rem" }}>
+        <h2>🌀 QRouter Demo</h2>
+        <p>This story demonstrates dynamic quantum routing.</p>
+        <p>
+          Try navigating to <Link to="/hello">/hello</Link> or{" "}
+          <Link to="/world">/world</Link>.
+        </p>
+        <Routes>
+          <Route path="/hello" element={<div>Hello Quantum 🌐</div>} />
+          <Route path="/world" element={<div>World Quantum ⚛️</div>} />
+        </Routes>
+      </div>
+    </QRouter>
+  ),
+};

package/src/QRouter/QRouter.tsx

@@ -0,0 +1,57 @@
+import React, { createContext, useContext, useMemo, useState, ReactNode } from "react";
+import { BrowserRouter, useInRouterContext } from "react-router-dom";
+type QuantumNode = { id: string; path: string; element: ReactNode; derived?: boolean };
+type LinkObject = { href: string; rel?: string; label?: string };
+type QRouterContextValue = {
+  nodes: QuantumNode[];
+  addNode: (node: QuantumNode) => void;
+  deriveRoute: (path: string) => void;
+  registerLinks: (links: LinkObject[]) => void;
+};
+const QRouterContext = createContext<QRouterContextValue | null>(null);
+export const useQRouter = () => {
+  const ctx = useContext(QRouterContext);
+  if (!ctx) throw new Error("useQRouter must be used within QRouter");
+  return ctx;
+};
+
+export const QRouter: React.FC<{ children?: ReactNode }> = ({ children }) => {
+  const [nodes, setNodes] = useState<QuantumNode[]>(() => [
+    { id: "__default_root__", path: "/", element: <div style={{ padding: 16 }}>🏠 Home</div> },
+  ]);
+  const [links, setLinks] = useState<LinkObject[]>([]);
+  const inRouter = useInRouterContext(); // detecta si ya existe un router activo
+
+  const addNode = (node: QuantumNode) =>
+    setNodes((prev) => {
+      const idx = prev.findIndex((n) => n.path === node.path);
+      if (idx === -1) return [...prev, node];
+      const next = prev.slice();
+      // Override by path (the app should be able to replace the default root route)
+      next[idx] = { ...prev[idx], ...node };
+      return next;
+    });
+
+  const deriveRoute = (path: string) => {
+    if (path === "/") return; // never overwrite root
+    const id = path.replace(/\//g, "_") || "root";
+    addNode({ id, path, element: <div style={{ padding: 16 }}>✨ Quantum derived: {path}</div>, derived: true });
+  };
+
+  const registerLinks = (newLinks: LinkObject[]) => {
+    setLinks((prev) => {
+      const existing = new Set(prev.map((l) => l.href));
+      const filtered = newLinks.filter((l) => !existing.has(l.href));
+      return [...prev, ...filtered];
+    });
+  };
+
+  const value = useMemo(() => ({ nodes, addNode, deriveRoute, registerLinks }), [nodes]);
+
+  const Inner = <QRouterContext.Provider value={value}>{children}</QRouterContext.Provider>;
+
+  // 🧩 Si ya hay router, úsalo. Si no, crea uno.
+  return inRouter ? Inner : <BrowserRouter>{Inner}</BrowserRouter>;
+};
+
+export default QRouter;

package/src/gui/Theme/GuiProvider.tsx

@@ -0,0 +1,111 @@
+// src/themes/GuiProvider.tsx
+import React, { useEffect, useMemo, useState } from 'react';
+import { generatePaletteCssVars } from './utils/themeUtils';
+import { ThemeContext } from '@/gui/contexts/ThemeContext';
+import { ThemeProvider, CssBaseline } from '@mui/material';
+import type { Theme } from '@mui/material/styles';
+import { themeTokens } from '@/gui/Theme/styles/theme.tokens';
+import { usePersistentThemeId, usePersistentThemeMode } from './utils/persistence';
+import { makeMuiTheme } from '@/gui/Theme/fromTokens';
+import { GuiThemes, getGuiTheme } from './utils/catalog';
+import { InsetsProvider, useInsetsContext } from '@/gui/contexts/InsetsContext';
+// -------------------------------- Types --------------------------------
+import type {
+  GuiContextValue,
+} from '@/types/theme';
+export type GuiProviderProps = {
+  initialThemeId?: string;
+  initialMode?: 'light' | 'dark'; // <-- añadido
+  children?: React.ReactNode;
+};
+
+export function GuiProvider({
+  initialThemeId = 'neurons.me',
+  initialMode = 'light', // default
+  children,
+}: GuiProviderProps) {
+  // Persist last chosen `themeId`
+  const [themeId, setThemeId] = usePersistentThemeId(initialThemeId);
+  // Persist last chosen `mode`
+  const [mode, setModeState] = usePersistentThemeMode(initialMode);
+  // Resolve manifest for current themeId (the GuiTheme which contains both modes)
+  const manifest = useMemo(() => {
+    return getGuiTheme(themeId) ?? GuiThemes[0];
+  }, [themeId]);
+  // Expose an `active` object for convenience (manifest + current selected mode)
+  const active = useMemo(() => {
+    return {
+      ...(manifest ?? {}),
+      mode,
+    } as (typeof manifest & { mode: 'light' | 'dark' });
+  }, [manifest, mode]);
+  // Build MUI themes for both dark and light using the manifest's mode tokens.
+  // IMPORTANT: makeMuiTheme signature assumed: makeMuiTheme(baseTokens, modeTokens, mode)
+  const { mode: manifestModes } = manifest || ({} as any);
+  const lightMuiTheme = useMemo<Theme>(() => {
+    const lightTokens = manifestModes?.light ?? {};
+    return makeMuiTheme(themeTokens, lightTokens, 'light');
+  }, [manifestModes]);
+  const darkMuiTheme = useMemo<Theme>(() => {
+    const darkTokens = manifestModes?.dark ?? {};
+    return makeMuiTheme(themeTokens, darkTokens, 'dark');
+  }, [manifestModes]);
+  const theme = mode === 'dark' ? darkMuiTheme : lightMuiTheme;
+  useEffect(() => {
+    generatePaletteCssVars(theme);
+  }, [theme]);
+  // Ensure saved key is valid with the current catalog
+  useEffect(() => {
+    if (GuiThemes.length === 0) return;
+    const ok = GuiThemes.some((e) => e.themeId === themeId);
+    if (!ok) setThemeId(GuiThemes[0].themeId ?? '');
+  }, [themeId, setThemeId]);
+  // API for changing mode without touching themeId
+  const setMode = (nextMode: 'light' | 'dark') => {
+    setModeState(nextMode);
+  };
+
+  const toggleMode = () => setModeState((m) => (m === 'dark' ? 'light' : 'dark'));
+  const ctxValue: GuiContextValue = useMemo(
+    () => ({
+      themeId: manifest?.themeId ?? '',
+      setThemeId,
+      themeName: manifest?.themeName ?? '',
+      mode,
+      setMode,
+      toggleMode,
+    }),
+    [manifest?.themeId, manifest?.themeName, mode, setThemeId]
+  );
+
+  return (
+    <InsetsProvider>
+      <GuiThemeBridge theme={theme} ctxValue={ctxValue}>
+        {children}
+      </GuiThemeBridge>
+    </InsetsProvider>
+  );
+}
+
+const GuiThemeBridge: React.FC<{ theme: Theme; ctxValue: GuiContextValue; children?: React.ReactNode }> = ({ theme, ctxValue, children }) => {
+  const { insets, updateInsets } = useInsetsContext();
+  const themeWithInsets = useMemo(() => {
+    return {
+      ...theme,
+      layout: {
+        ...(theme as any).layout,
+        insets,
+      },
+      updateInsets,
+    } as Theme & { layout: any; updateInsets: typeof updateInsets };
+  }, [insets, theme, updateInsets]);
+
+  return (
+    <ThemeProvider theme={themeWithInsets}>
+      <CssBaseline />
+      <ThemeContext.Provider value={ctxValue}>{children}</ThemeContext.Provider>
+    </ThemeProvider>
+  );
+};
+
+export default GuiProvider;

package/src/gui/Theme/Icon/Icon.resolver.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import Icon from '@/gui/Theme/Icon/Icon';
+
+export type IconSpec = {
+  type: 'Icon';
+  props: {
+    name: string;
+    fill?: number;
+    weight?: number;
+    grade?: number;
+    opticalSize?: number;
+    fontSize?: number | string;
+    iconColor?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    [key: string]: any; // permite pasar props adicionales
+  };
+};
+
+const IconResolver: RegistryEntry = {
+  type: 'Icon',
+  resolve(spec: IconSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    return <Icon {...p} />;
+  },
+};
+
+export default IconResolver;

package/src/gui/Theme/Icon/Icon.tsx

@@ -0,0 +1,43 @@
+import * as React from 'react';
+import clsx from 'clsx';
+import 'material-symbols';
+
+export type IconProps = {
+  name: string; // e.g., 'material:home'
+  iconColor?: string; // CSS color value
+  fontSize?: number | string; // optional font size
+  weight?: number; // font variation setting
+  fill?: number; // font variation setting (0 = outlined, 1 = filled)
+  grade?: number;
+  opticalSize?: number;
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+export default function Icon({
+  name,
+  iconColor,
+  fontSize,
+  weight = 400,
+  fill = 0,
+  grade = 0,
+  opticalSize = 24,
+  className,
+  style,
+}: IconProps) {
+  const iconName = name;
+  const variationSettings = `"FILL" ${fill}, "wght" ${weight}, "GRAD" ${grade}, "opsz" ${opticalSize}`;
+  return (
+    <span
+      className={clsx('material-symbols-rounded', className)}
+      style={{
+        fontVariationSettings: variationSettings,
+        color: iconColor,
+        fontSize,
+        ...style,
+      }}
+    >
+      {iconName}
+    </span>
+  );
+}

package/src/gui/Theme/Layout/Content/Content.stories.tsx

@@ -0,0 +1,88 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Layout from '@/gui/Theme/Layout/Layout/Layout';
+import Box from '@/gui/atoms/Box/Box';
+import Typography from '@/gui/atoms/Typography/Typography';
+
+const meta: Meta<typeof Layout> = {
+  title: 'Layout/Content/Content',
+  component: Layout,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+interface DemoContentProps {
+  text: string;
+}
+
+const DemoContent: React.FC<DemoContentProps> = ({ text }) => (
+  <Box
+    sx={{
+      minHeight: '100vh',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      bgcolor: 'background.default',
+      color: 'text.primary',
+    }}
+  >
+    <Typography variant="h4">{text}</Typography>
+  </Box>
+);
+
+const Template = (args: React.ComponentProps<typeof Layout>): React.JSX.Element => (
+  <Layout {...args}>
+    <DemoContent text="This is the Content area" />
+  </Layout>
+);
+
+type Story = StoryObj<typeof Layout>;
+
+export const OnlyContent: Story = {
+  render: Template,
+  args: {
+    topBarConfig: false,
+    leftSidebarConfig: false,
+    rightSidebarConfig: false,
+    footerConfig: false,
+  },
+};
+
+export const WithTopBar: Story = {
+  render: Template,
+  args: {
+    topBarConfig: { title: 'Top Bar Example' },
+  },
+};
+
+export const WithSidebars: Story = {
+  render: Template,
+  args: {
+    leftSidebarConfig: { initialView: 'expanded' },
+    rightSidebarConfig: { initialView: 'expanded' },
+  },
+};
+
+export const WithTopBarAndSidebars: Story = {
+  render: Template,
+  args: {
+    topBarConfig: { title: 'Top Bar Example' },
+    leftSidebarConfig: { initialView: 'rail' },
+    rightSidebarConfig: { initialView: 'expanded' },
+  },
+};
+
+export const FullLayout: Story = {
+  render: Template,
+  args: {
+    topBarConfig: { title: 'Full Layout' },
+    leftSidebarConfig: { initialView: 'rail' },
+    rightSidebarConfig: { initialView: 'rail' },
+    footerConfig: {
+      brandLabel: 'neurons.me',
+      position: 'static',
+      leftElements: [{ type: 'link', props: { label: 'Docs', href: '/docs' } }],
+      rightElements: [{ type: 'link', props: { label: 'GitHub', href: 'https://github.com/neurons-me' } }],
+    },
+  },
+};

package/src/gui/Theme/Layout/Content/Content.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { Box } from '@/gui/components/atoms';
+import { useInsets } from '@/gui/hooks';
+import type { ContentProps } from './Content.types';
+
+const Content: React.FC<ContentProps> = ({ children }) => {
+  const insets = useInsets();
+  const safeTop = Math.max(0, Number(insets?.top ?? 0));
+  const navHeight = Math.max(0, Number(insets?.nav ?? 0));
+  const topInset = safeTop + navHeight;
+  const bottomInset = Math.max(0, Number(insets?.bottom ?? 0));
+  const leftInset = Math.max(0, Number(insets?.left ?? 0));
+  const rightInset = Math.max(0, Number(insets?.right ?? 0));
+
+  return (
+    <Box
+      id="content"
+      component="main"
+      sx={{
+        position: 'relative',
+        flex: 1,
+        display: 'flex',
+        flexDirection: 'column',
+        minHeight: 0,
+        width: '100%',
+        overflow: 'hidden',
+        paddingTop: `${topInset}px`,
+        paddingBottom: `${bottomInset}px`,
+        paddingLeft: `${leftInset}px`,
+        paddingRight: `${rightInset}px`,
+        boxSizing: 'border-box',
+        backgroundColor: 'background.default',
+        transition: 'padding 0.3s ease',
+      }}
+    >
+      <Box
+        sx={{
+          flex: 1,
+          minHeight: 0,
+          width: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          overflowY: 'auto',
+          overflowX: 'hidden',
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+};
+
+export default Content;

package/src/gui/Theme/Layout/Content/Content.types.tsx

@@ -0,0 +1,40 @@
+import type React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export type ContentSection = {
+  type: string;
+  props?: Record<string, any>;
+  children?: ContentSection[];
+};
+
+export interface ContentProps {
+  /**
+   * Array of layout sections or components to render within the Content area.
+   */
+  sections?: ContentSection[];
+
+  /**
+   * Optional unique identifier.
+   */
+  id?: string;
+
+  /**
+   * Custom CSS class name for additional styling.
+   */
+  className?: string;
+
+  /**
+   * Optional style overrides for the main container.
+   */
+  sx?: SxProps<Theme>;
+
+  /**
+   * Optional data-testid for testing purposes.
+   */
+  'data-testid'?: string;
+
+  /**
+   * Optional React children that can be rendered directly.
+   */
+  children?: React.ReactNode;
+}

package/src/gui/Theme/Layout/Footer/Footer.resolver.tsx

@@ -0,0 +1,45 @@
+import * as React from 'react';
+import type { RegistryEntry } from '@/gui/registry/types';
+import Footer from './Footer';
+import type { FooterElement } from './Footer.types';
+
+type FooterSpec = {
+  type: 'Footer';
+  props?: {
+    brandLabel?: string;
+    brandLogo?: string;
+    brandHref?: string;
+    leftElements?: FooterElement[];
+    centerElements?: FooterElement[];
+    rightElements?: FooterElement[];
+    position?: 'static' | 'fixed' | 'sticky';
+    elevation?: number;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+  };
+};
+
+const FooterResolver: RegistryEntry = {
+  type: 'Footer',
+  resolve(spec: FooterSpec) {
+    const props = spec.props ?? {};
+    return (
+      <Footer
+        brandLabel={props.brandLabel}
+        brandLogo={props.brandLogo}
+        brandHref={props.brandHref}
+        leftElements={props.leftElements}
+        centerElements={props.centerElements}
+        rightElements={props.rightElements}
+        position={props.position}
+        elevation={props.elevation}
+        className={props.className}
+        id={props.id}
+        data-testid={props['data-testid']}
+      />
+    );
+  },
+};
+
+export default FooterResolver;