this.gui 1.0.18 → 1.1.0

package/nodes/overall approach.md

@@ -0,0 +1,93 @@
+compact technical brief of the overall approach (props vs config vs viewported configs), with structure, versatility, declarativity, and scope.
+
+1) Plain React props (current/“classic”)
+
+Structure: <Footer title="…" links={[…]} socialLinks={[…]} />
+Pros
+	•	Familiar React ergonomics.
+	•	Strong TypeScript IntelliSense on each prop.
+	•	Easy to tree-shake and to reason about in component code.
+
+Cons
+	•	Gets verbose as components grow.
+	•	Hard to switch “modes” (desktop/mobile/minimal/full) without duplicating prop sets.
+	•	Not naturally serializable (harder to hydrate from pure JSON or an external CMS).
+
+Use when
+	•	App code writes JSX directly.
+	•	Variations are small and local.
+
+2) Single config object
+
+Structure: <Footer config={{ title:"…", links:[…], socialLinks:[…] }} />
+Pros
+	•	Declarative & serializable: perfect for JSON-driven UIs, CMS/Llama/Lego-style composition.
+	•	One entrypoint for “shape evolution”: adding/removing options doesn’t churn the JSX signature.
+	•	Easier to diff/patch at runtime (hot updates, remote editing, A/B tests).
+
+Cons
+	•	Slightly less IDE precision unless you type config well (e.g., FooterConfig).
+	•	If you mix both props and config, you need clear precedence rules.
+
+Use when
+	•	You want to drive UI from data (JSON), live-edit, or swap configurations on the fly.
+	•	You’re aiming at a “player” model later (render UIs from configs).
+
+Recommended pattern
+	•	Support both: keep top-level props for ergonomics, plus an optional config. Component merges: final = { ...defaults, ...config, ...propsOverrides }.
+
+3) Viewport-aware configs (declarative responsiveness)
+
+Structure A (per-prop):
+size="pill" or size={{ xs: "icons", md: "pill" }}
+
+Structure B (whole-config overrides):
+
+<StickyOptionsTop
+  config={{ items: desktopItems }}
+  viewport={{
+    xs: { config: { items: mobileItems } },
+    sm: { config: { items: mobileItems } }
+  }}
+/>
+
+(Resolved by your viewport.ts: resolveViewportProp / resolveResponsiveConfig.)
+
+Pros
+	•	Responsiveness is data, not scattered useMediaQuery logic.
+	•	Plays great with JSON: one base config + sparse overrides per breakpoint.
+	•	Testable & SSR-friendly (you can inject a width override).
+
+Cons
+	•	Slightly more indirection; you need a tiny resolver layer (which you now have).
+	•	Authors must learn the pattern (base + per-breakpoint overrides).
+
+Use when
+	•	The same component must present different variants by viewport.
+	•	You want a single source of truth for mobile/desktop/XL differences.
+
+Putting it together (recommended architecture)
+	•	Component API supports both:
+	•	Classic props (ergonomic for app devs).
+	•	config (for JSON-driven/declarative scenarios).
+	•	Optional viewport to override either specific props or the whole config per breakpoint.
+	•	Resolver layer (inside each component):
+	1.	Gather defaults.
+	2.	Merge config.
+	3.	Apply classic prop overrides (if both exist, props win).
+	4.	Apply viewport overrides using your resolveViewportProp/resolveResponsiveConfig.
+	5.	Render.
+
+This yields:
+	•	Versatility: JSX convenience and data-driven control.
+	•	Declarativity: All variants can be expressed as JSON and swapped live.
+	•	Scope/Future-proofing: Same pattern works for a headless “GUI Player,” CMS, LLM emitters, or Web Components later (just feed the same config/viewport JSON).
+	•	Low coupling: Components don’t import useMediaQuery everywhere; the viewport resolver centralizes responsive decisions.
+
+Migration strategy (quick)
+	1.	Keep your existing props as-is.
+	2.	Add optional config and viewport to priority-merge.
+	3.	Start using viewport.ts in 1–2 components (e.g., StickyOptionsTop, Footer) to prove the flow.
+	4.	Document the precedence rule: defaults < config < props < viewport overrides.
+
+This gives you the best of all worlds: ergonomic props for developers, clean JSON for declarative UIs, and a compact, testable way to express responsive variants without scattering logic.

package/notes/Proyect.md

@@ -0,0 +1,109 @@
+Ocultar/mostrar barras, dar pantalla completa al lienzo, y encima montar un sistema de colocación (2D/3D) que se hidrate desde JSON.
+
+Aquí te dejo un plan claro (sin código) para que lo aterricemos paso a paso:
+
+1) API del Shell (layout declarativo)
+
+Define un spec de layout que controle visibilidad, posición y estilo de las barras (y que sea mutable en runtime):
+
+{
+  "layout": {
+    "navbar": { "visible": true,  "position": "fixed" },
+    "leftDrawer": { "visible": true,  "width": 260 },
+    "rightDrawer": { "visible": false, "width": 280 },
+    "stickyOptions": { "visible": false },
+    "footer": { "visible": true },
+    "canvas": {
+      "mode": "2d",         // "2d" | "3d"
+      "fullscreen": false,  // si true, el shell oculta barras y expande el lienzo
+      "bg": "transparent"
+    }
+  }
+}
+
+	•	El shell aplica el spec y actualiza insets (como ya haces) cuando algo es permanente.
+	•	Si canvas.fullscreen = true, el shell oculta NavBar/Drawers/Sticky/Footer y setea insets a 0 → el “campo” queda a pantalla completa.
+
+2) Motor de colocación (2D primero, 3D después)
+
+Para el colocador 2D, usa una cuadrícula declarativa. Piensa en áreas CSS Grid con responsive:
+
+{
+  "canvas2D": {
+    "grid": {
+      "template": {
+        "xs": { "cols": "1fr", "rows": "auto 1fr auto", "areas": ["header","content","hud"] },
+        "md": { "cols": "240px 1fr", "rows": "auto 1fr", "areas": ["sidebar header","sidebar content"] }
+      },
+      "gap": 8
+    },
+    "items": [
+      { "id": "header",  "component": { "type": "Text", "props": { "variant": "h4", "children": "Scene" } } },
+      { "id": "sidebar", "component": { "type": "Panel", "props": { "title": "Layers" } } },
+      { "id": "content", "component": { "type": "Viewport2D", "props": { "controls": true } } },
+      { "id": "hud",     "component": { "type": "StickyOptionsTop", "props": { "items": [/* … */] } } }
+    ]
+  }
+}
+
+	•	template define áreas por breakpoint (xs/md/etc.).
+	•	items asigna qué se renderiza en cada área (resuelto por tu registry + resolvers).
+	•	Esto te da un “layout engine” 2D declarativo, perfecto para AR-lite (HUDs, overlays).
+
+Para 3D, la misma idea, pero con un Viewport3D (three.js/Babylon) como componente. El grid sigue sirviendo para HUDs y paneles laterales mientras el lienzo 3D ocupa el área content.
+
+3) Controles de visibilidad y modos (runtime)
+
+Agrega un canal simple de acciones declarativas para mutar el spec:
+
+{
+  "actions": [
+    { "id": "toggleFull", "type": "toggle", "path": "layout.canvas.fullscreen" },
+    { "id": "showRight",  "type": "set",    "path": "layout.rightDrawer.visible", "value": true }
+  ],
+  "bindings": [
+    { "event": "kbd:F", "action": "toggleFull" },
+    { "event": "ui:openContext", "action": "showRight" }
+  ]
+}
+
+	•	El shell expone un dispatcher que entiende toggle/set sobre rutas JSON (path).
+	•	Permite atajos (teclado), botones de UI, o señales externas (servidor/IA).
+
+4) Resolver genérico + resolvers por componente
+	•	Mantén los resolvers por componente (Button, Link, NavBar, Viewport2D/3D, etc.) para mapear JSON → props reales.
+	•	El resolver genérico (inyector) toma el árbol JSON y delega por type al resolver adecuado (registrado en tu GuiRegistry).
+	•	Así puedes hidratar todo el shell (barras + canvas + grid + items) desde un único spec.
+
+5) Slots y Portal (overlay HUD)
+	•	Define “slots” especiales (ej. overlay, hud, notifications) que rendericen vía portal encima del canvas.
+	•	Tus StickyOptionsTop u otras capas pueden vivir ahí sin afectar insets del shell.
+
+6) Persistencia + Replay
+	•	Guarda el spec actual (y su historial) en localStorage o en backend para reproducir estados y compartir escenas/pantallas.
+	•	Útil para AR colaborativo y “deep links” a UIs derivadas por IA.
+
+7) Rendimiento
+	•	Evita re-render global del shell: cuando mutas visibilidad o áreas, memoriza subárboles.
+	•	Para 3D, desacopla el ciclo de render del estado de React cuando sea necesario.
+
+8) Roadmap chiquito (prioridades)
+	1.	Spec de layout con visibilidad + fullscreen (ya puedes hacerlo con tu shell actual).
+	2.	Grid 2D declarativo con áreas responsive (pequeño motor CSS Grid).
+	3.	Slots/Portal para HUD/Overlay.
+	4.	Registry + resolvers para los componentes que entren al grid (ya lo estás haciendo).
+	5.	Acciones declarativas (toggle/set) + bindings básicos.
+	6.	Viewport3D como primitivo (después).
+
+⸻
+
+Con esto:
+	•	Puedes ocultar/mostrar barras a voluntad o entrar en fullscreen.
+	•	Tienes un lienzo central controlado por spec.
+	•	Puedes colocar elementos 2D (y luego 3D) de forma declarativa y responsive.
+	•	Todo eso conversando con tu registry y los resolvers que ya estás construyendo.
+
+Cuando quieras, te redacto un spec mínimo de ejemplo (end-to-end) que tu shell pueda consumir hoy mismo para:
+	1.	navbar visible, leftDrawer visible, rightDrawer oculto;
+	2.	grid 2D con sidebar/header/content;
+	3.	botón que activa fullscreen.

package/package.json

@@ -1,68 +1,85 @@
 {
   "name": "this.gui",
-  "version": "1.0.18",
-  "description": "This Graphic User Interface.",
+  "private": false,
+  "version": "1.1.0",
+  "type": "module",
   "main": "dist/this-gui.umd.js",
   "module": "dist/this-gui.es.js",
-  "type": "module",
-  "author": "suiGn",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/neurons-me/GUI.git"
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/this-gui.es.js",
+      "require": "./dist/this-gui.umd.js"
+    }
   },
   "scripts": {
-    "start": "node ./src/scripts/logASCIIArt.js && concurrently \"vite --open\" \"storybook dev -p 6006 --no-open\"",
-    "dev": "vite",
     "build": "vite build",
-    "prepublishOnly": "npm run build",
-    "storybook": "storybook dev -p ${STORYBOOK_PORT:-6006}",
-    "build-storybook": "storybook build",
-    "postinstall": "node src/scripts/postinstall.js"
+    "lint": "eslint .",
+    "dev": "vite",
+    "dev:lib": "vite build --watch",
+    "preview": "vite preview",
+    "storybook": "STORYBOOK=true storybook dev -p 6006",
+    "build-storybook": "STORYBOOK=true storybook build",
+    "chromatic": "STORYBOOK=true chromatic --project-token=$CHROMATIC_PROJECT_TOKEN"
   },
   "dependencies": {
-    "@storybook/builder-vite": "^8.2.9",
-    "classnames": "^2.5.1",
-    "dotenv": "^16.4.5",
-    "figlet": "^1.7.0",
-    "fs": "^0.0.1-security",
-    "postcss": "^8.4.45",
-    "react-icons": "^5.3.0",
-    "react-router-dom": "^6.26.2"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.0",
+    "@lexical/link": "^0.33.1",
+    "@lexical/list": "^0.33.1",
+    "@lexical/react": "^0.33.1",
+    "@lexical/rich-text": "^0.33.1",
+    "@mdx-js/loader": "^3.1.0",
+    "@mdx-js/react": "^3.1.0",
+    "@mdx-js/rollup": "^3.1.0",
+    "@mui/material": "^6.4.6",
+    "@storybook/addon-docs": "^9.1.5",
+    "file-saver": "^2.0.5",
+    "js-cookie": "^3.0.5",
+    "lexical": "^0.33.1",
+    "lucide-react": "^0.542.0",
+    "react-draggable": "^4.4.6",
+    "react-feather": "^2.0.10",
+    "react-syntax-highlighter": "^15.6.6"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^1.8.0",
-    "@mdx-js/loader": "^3.0.1",
-    "@mdx-js/react": "^3.0.1",
-    "@mdx-js/rollup": "^3.0.1",
-    "@storybook/addon-docs": "^8.3.4",
-    "@storybook/addon-essentials": "^8.3.0",
-    "@storybook/addon-interactions": "^8.3.0",
-    "@storybook/addon-links": "^8.3.0",
-    "@storybook/addon-onboarding": "^8.2.9",
-    "@storybook/blocks": "^8.2.9",
-    "@storybook/manager-api": "^8.2.9",
-    "@storybook/react": "^8.3.0",
-    "@storybook/react-vite": "^8.3.4",
-    "@storybook/test": "^8.2.9",
-    "@storybook/theming": "^8.2.9",
-    "@vitejs/plugin-react": "^4.3.2",
-    "concurrently": "^9.0.1",
-    "cross-env": "^7.0.3",
+    "@chromatic-com/storybook": "^4.1.1",
+    "@eslint/js": "^9.21.0",
+    "@mui/icons-material": "^6.5.0",
+    "@storybook/addon-a11y": "^9.1.4",
+    "@storybook/addon-onboarding": "^9.1.4",
+    "@storybook/addon-themes": "^9.1.4",
+    "@storybook/addon-vitest": "^9.1.4",
+    "@storybook/react-vite": "^9.1.4",
+    "@types/node": "^24.3.2",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@vitejs/plugin-react-swc": "^3.8.0",
+    "@vitest/browser": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "chromatic": "^13.1.4",
+    "eslint": "^9.21.0",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "eslint-plugin-storybook": "^9.1.4",
+    "globals": "^15.15.0",
+    "playwright": "^1.55.0",
     "prop-types": "^15.8.1",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "storybook": "^8.2.9",
-    "vite": "^5.4.8"
+    "react-router-dom": "^6.30.1",
+    "storybook": "^9.1.4",
+    "typescript": "^5.9.2",
+    "vite": "^6.2.0",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "package.json"
-  ]
+  "eslintConfig": {
+    "extends": [
+      "plugin:storybook/recommended"
+    ]
+  }
 }

package/src/components/generics/Cards/Gridme.jsx

@@ -0,0 +1,52 @@
+import { Box } from '@mui/material';
+
+// Gridme is a generic grid layout component based on MUI's Box.
+// It allows you to quickly define a grid layout with customizable number of columns and spacing.
+// You can also control the maximum width of each grid item via the `itemMaxWidth` prop.
+// This wrapper is part of this.GUI's declarative approach to layout construction.
+const Gridme = ({
+  children,
+  columns = 3,
+  columnGap = '0.5rem',
+  rowGap = '1rem',
+  marginTop = '0px',
+  marginBottom = '0px',
+  sx = {},
+}) => {
+  return (
+    <Box
+      sx={{
+        display: 'grid',
+        gridTemplateColumns: `repeat(${columns}, 1fr)`,
+        columnGap: columnGap,
+        rowGap: rowGap,
+        width: '100%',
+        alignItems: 'stretch',
+        justifyItems: 'stretch',
+        mt: marginTop,
+        mb: marginBottom,
+        '& > *': {
+          width: '100%',
+          height: '100%',
+        },
+        ...sx,
+      }}
+    >
+      {children}
+    </Box>
+  );
+};
+
+export default Gridme;
+
+// Example usage:
+// 
+// import Gridme from './Gridme';
+// 
+// const Example = () => (
+//   <Gridme columns={3} gap="1rem">
+//     <Box sx={{ backgroundColor: 'red', height: 100 }} />
+//     <Box sx={{ backgroundColor: 'blue', height: 100 }} />
+//     <Box sx={{ backgroundColor: 'green', height: 100 }} />
+//   </Gridme>
+// );

package/src/components/generics/Cards/LilBox.jsx

@@ -0,0 +1,65 @@
+import { Box, Typography } from '@mui/material';
+import * as Icons from 'react-feather';
+import PropTypes from 'prop-types';
+import { Link } from 'react-router-dom';
+
+const LilBox = ({
+  icon,
+  featherIcon,
+  label,
+  href,
+  aspectRatio = '5 / 4',
+}) => {
+  const FeatherIcon = featherIcon && Icons[featherIcon] ? Icons[featherIcon] : null;
+
+  return (
+    <Box
+      component={href ? Link : 'div'}
+      to={href}
+      sx={{
+        width: '100%',
+        aspectRatio,
+        backgroundColor: (theme) =>
+          theme.palette.mode === 'dark'
+            ? 'rgba(255, 255, 255, 0.05)'
+            : 'rgba(0, 0, 0, 0.03)',
+        border: '1px solid',
+        borderColor: (theme) =>
+          theme.palette.mode === 'dark'
+            ? 'rgba(255, 255, 255, 0.1)'
+            : 'rgba(0, 0, 0, 0.1)',
+        borderRadius: '8px',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        color: (theme) => theme.palette.text.primary,
+        fontSize: '1rem',
+        fontWeight: 300,
+        transition: 'transform 0.2s ease',
+        textDecoration: 'none',
+        cursor: 'pointer',
+        '&:hover': {
+          transform: 'scale(1.05)',
+        },
+      }}
+    >
+      <Box sx={{ fontSize: '1.5rem', mb: 0.5 }}>
+        {icon ? icon : FeatherIcon ? <FeatherIcon size={24} /> : null}
+      </Box>
+      <Typography variant="body2" align="center">
+        {label}
+      </Typography>
+    </Box>
+  );
+};
+
+LilBox.propTypes = {
+  icon: PropTypes.node,
+  featherIcon: PropTypes.string,
+  label: PropTypes.string.isRequired,
+  href: PropTypes.string,
+  aspectRatio: PropTypes.string,
+};
+
+export default LilBox;

package/src/components/generics/Cards/ModuleCard.jsx

@@ -0,0 +1,106 @@
+import { Link as RouterLink } from "react-router-dom";
+import { Box, Typography, Card, CardActionArea, CardContent } from "@mui/material";
+
+/**
+ * ModuleCard
+ * Clickable card for modules/features.
+ *
+ * Props:
+ * - title: string (required)
+ * - description: string
+ * - image: string (url to image)
+ * - href?: string  -> preferred navigation prop (internal route or external URL)
+ * - link?: string  -> alias of href for backward compatibility
+ * - target?: string -> optional target for external links (e.g., "_blank")
+ *
+ * Behavior:
+ * - If `href` (or `link`) starts with http/https, renders an <a>.
+ * - Otherwise, renders a React Router <Link> for client-side routing.
+ * - Avoids nested anchors: do NOT wrap ModuleCard with another <Link>.
+ */
+const ModuleCard = ({ title, description, image, href, link, target }) => {
+  const to = href ?? link ?? null;
+  const isExternal = typeof to === "string" && /^https?:\/\//i.test(to);
+
+  // Decide which props to pass to CardActionArea to avoid <a> inside <a>.
+  const navProps = to
+    ? isExternal
+      ? { component: "a", href: to, target: target ?? "_self", rel: "noopener noreferrer" }
+      : { component: RouterLink, to }
+    : {}; // No navigation if no href/link provided
+
+  return (
+    <Card
+      sx={{
+        height: "100%",
+        backgroundColor: "background.paper",
+        boxShadow: 2,
+        borderRadius: 2,
+        "&:hover": {
+          boxShadow: 4,
+          transform: "translateY(-2px)",
+          transition: "0.3s ease-in-out",
+        },
+      }}
+    >
+      <CardActionArea
+        {...navProps}
+        sx={{ height: "100%", display: "flex", flexDirection: "column" }}
+      >
+        <CardContent
+          sx={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "center",
+            textAlign: "center",
+            padding: 2,
+            height: "100%",
+          }}
+        >
+          {/* Image */}
+          {image && (
+            <Box
+              component="img"
+              src={image}
+              alt={title}
+              sx={{
+                width: "80px",
+                height: "80px",
+                marginBottom: 1,
+                objectFit: "contain",
+              }}
+            />
+          )}
+
+          {/* Title */}
+          <Typography
+            variant="body1"
+            sx={{
+              fontWeight: 600,
+              color: "text.primary",
+              marginBottom: 1,
+            }}
+          >
+            {title}
+          </Typography>
+
+          {/* Description */}
+          {description && (
+            <Typography
+              variant="body2"
+              sx={{
+                fontSize: "0.85rem",
+                color: "text.secondary",
+              }}
+            >
+              {description}
+            </Typography>
+          )}
+        </CardContent>
+      </CardActionArea>
+    </Card>
+  );
+};
+
+export default ModuleCard;