this.gui 1.3.41 → 1.3.42

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

@@ -0,0 +1,289 @@
+import React from "react";
+import type { Meta, StoryFn, StoryObj } from "@storybook/react";
+import Layout from "./Layout";
+import Page from '@/gui/components/molecules/Page/Page';
+import ThemeModeToggle from "@/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle";
+const meta: Meta<typeof Layout> = {
+  title: "Layout/Layout",
+  component: Layout,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Layout** component wires the responsive shell used across This.GUI demos. It coordinates the TopBar, left/right sidebars, and Footer so their insets remain in sync while your application content renders inside.
+---
+## Features
+- **Context wiring** – wraps children with the required providers (LeftSidebar, RightSidebar) so hooks and insets work automatically.
+- **Composable regions** – optional \`topBarConfig\`, \`leftSidebarConfig\`, \`rightSidebarConfig\`, and \`footerConfig\` let you enable only what you need.
+- **Inset aware** – whenever a sidebar expands or collapses, the layout updates theme insets so the TopBar/Footer and main content stay aligned.
+- **Story-friendly** – serves as an orchestration helper in Storybook; in production you can lift the same pattern to your app shell.
+
+---
+## Declarative usage
+~~~json
+{
+  "type": "Layout",
+  "props": {
+    "topBarConfig": {
+      "title": "Workspace",
+      "elementsRight": [
+        {
+          "type": "action",
+          "props": {
+            "element": "ThemeModeToggle"
+          }
+        }
+      ]
+    },
+    "leftSidebarConfig": {
+      "elements": [
+        {
+          "type": "link",
+          "props": {
+            "label": "Dashboard",
+            "icon": "dashboard"
+          }
+        },
+        {
+          "type": "menu",
+          "props": {
+            "label": "Projects",
+            "icon": "folder",
+            "items": [
+              {
+                "label": "Project A",
+                "icon": "work"
+              },
+              {
+                "label": "Project B",
+                "icon": "assignment"
+              }
+            ]
+          }
+        }
+      ]
+    },
+    "footerConfig": {
+      "brandLabel": "Neuroverse",
+      "centerElements": [
+        {
+          "type": "link",
+          "props": {
+            "label": "Docs",
+            "href": "/docs",
+            "icon": "menu_book"
+          }
+        }
+      ]
+    }
+  },
+  "Content": [
+    {
+      "children": [
+        {
+          "type": "Section",
+          "props": {
+            "title": "Overview"
+          }
+        },
+        {
+          "type": "Card",
+          "props": {
+            "title": "AI Metrics"
+          }
+        }
+      ]
+    }
+  ]
+}
+~~~
+
+---
+## React usage
+Use the layout as a shell around your routes or dashboard pages. Pass config objects when you need a region; use \`false\` to omit it.
+~~~tsx
+function DashboardPage() {
+  return (
+    <Layout
+      topBarConfig={{
+        title: "Analytics",
+        elementsRight: [
+          { type: "action", props: { element: <ThemeModeToggle variant="minimal" /> } },
+        ],
+      }}
+      leftSidebarConfig={{
+        elements: [
+          { type: "link", props: { label: "Overview", icon: "home" } },
+          { type: "link", props: { label: "Reports", icon: "insights" } },
+        ],
+      }}
+      rightSidebarConfig={{
+        elements: [
+          { type: "link", props: { label: "Alerts", icon: "notifications" } },
+        ],
+      }}
+    >
+      <Outlet />
+    </Layout>
+  );
+}
+~~~
+
+---
+## Notes
+- Config objects mirror the props of the individual components (TopBar, LeftSidebar, RightSidebar, Footer). Anything you can pass there can be forwarded through the layout.
+- Set a config to \`false\` (or omit it) to exclude that region entirely.
+- Children render in document order beneath any enabled sidebars/top bar – for sticky layouts remember to add padding or section containers as shown below.
+`,
+      },
+    },
+  },
+};
+
+export default meta;
+
+const Template: StoryFn<React.ComponentProps<typeof Layout>> = (args) => (
+  <Layout {...args}>
+    <div
+      style={{
+        minHeight: "120vh",
+        padding: "72px 24px 120px",
+        display: "flex",
+        flexDirection: "column",
+        gap: 16,
+      }}
+    >
+      <h2>Responsive Layout Demo</h2>
+      <p>
+        Resize the viewport or toggle sidebars to observe how insets are coordinated.
+        The content block is intentionally tall to show how fixed bars interact with scrolling.
+      </p>
+    </div>
+  </Layout>
+);
+
+type Story = StoryObj<typeof Layout>;
+
+export const TopOnly: Story = {
+  render: Template,
+  args: {
+    topBarConfig: {
+      title: "Neuroverse",
+      elementsRight: [
+        {
+          type: "action",
+          props: {
+            element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+          },
+        },
+      ],
+    },
+    leftSidebarConfig: false,
+    rightSidebarConfig: false,
+    footerConfig: false,
+  },
+};
+
+export const TopWithLeftSidebar: Story = {
+  render: Template,
+  args: {
+    ...TopOnly.args,
+    leftSidebarConfig: {
+      elements: [
+        { type: "link", props: { label: "Overview", icon: "dashboard" } },
+        {
+          type: "menu",
+          props: {
+            label: "Projects",
+            icon: "folder",
+            items: [
+              { label: "Project Alpha", icon: "work" },
+              { label: "Project Beta", icon: "assignment" },
+            ],
+          },
+        },
+      ],
+      footerElements: [
+        { type: "link", props: { label: "Settings", icon: "settings" } },
+      ],
+    },
+  },
+};
+
+export const TopWithLeftAndRight: Story = {
+  render: Template,
+  args: {
+    ...TopWithLeftSidebar.args,
+    rightSidebarConfig: {
+      elements: [
+        { type: "link", props: { label: "Activity", icon: "history" } },
+        { type: "action", props: { label: "Export", icon: "download" } },
+      ],
+    },
+  },
+};
+
+export const FullShellWithFooter: Story = {
+  render: Template,
+  args: {
+    ...TopWithLeftAndRight.args,
+    footerConfig: {
+      brandLabel: "Neuroverse",
+      brandLogo: "https://neurons.me/neurons.me.png",
+      centerElements: [
+        { type: "link", props: { label: "Docs", href: "/docs", icon: "menu_book", iconColor: "var(--gui-primary)" } },
+        { type: "link", props: { label: "API", href: "/api", icon: "code", iconColor: "var(--gui-secondary)" } },
+      ],
+      rightElements: [
+        { type: "link", props: { label: "Community", href: "https://community.neuroverse.ai", icon: "forum", iconColor: "var(--gui-info)", external: true } },
+        { type: "link", props: { label: "GitHub", href: "https://github.com", icon: "code", iconColor: "var(--gui-warning)", external: true } },
+      ],
+      position: "fixed",
+    },
+  },
+};
+
+export const ContentOnly: Story = {
+  render: Template,
+  args: {
+    topBarConfig: false,
+    leftSidebarConfig: false,
+    rightSidebarConfig: false,
+    footerConfig: false,
+  },
+};
+
+
+export const LayoutWithPage: Story = {
+  render: () => (
+    <Layout
+      topBarConfig={{ title: 'Neuroverse Workspace' }}
+      leftSidebarConfig={{
+        elements: [
+          { type: 'link', props: { label: 'Home', icon: 'home' } },
+          { type: 'link', props: { label: 'Analytics', icon: 'insights' } },
+        ],
+      }}
+      rightSidebarConfig={{
+        elements: [
+          { type: 'link', props: { label: 'Chat', icon: 'chat' } },
+        ],
+      }}
+      footerConfig={{
+        brandLabel: 'Neuroverse',
+        centerElements: [
+          { type: 'link', props: { label: 'Docs', icon: 'menu_book' } },
+        ],
+      }}
+    >
+      <Page background="linear-gradient(135deg, #0a192f, #172a45)" padding={4}>
+        <h2 style={{ color: 'white', marginBottom: 16 }}>Page inside Layout</h2>
+        <p style={{ color: 'white', maxWidth: 600 }}>
+          This example shows how a Page component can be used inside the responsive Layout,
+          automatically adapting to inset updates from the TopBar, sidebars, and Footer.
+        </p>
+      </Page>
+    </Layout>
+  ),
+};

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

@@ -0,0 +1,117 @@
+// Layout/Layout/Layout.tsx
+import { LeftSidebarProvider } from '@/gui/contexts/LeftSidebarContext';
+import { RightSidebarProvider } from '@/gui/contexts/RightSidebarContext';
+import Box from '@/gui/atoms/Box/Box';
+import TopBar from '@/gui/Theme/Layout/TopBar/TopBar';
+import LeftSidebar from '@/gui/Theme/Layout/Sidebars/LeftSidebar/LeftSidebar';
+import RightSidebar from '@/gui/Theme/Layout/Sidebars/RightSidebar/RightSidebar';
+import Footer from '@/gui/Theme/Layout/Footer/Footer';
+import Namespace from '@/gui/Theme/Layout/Namespace/Namespace';
+import Content from '@/gui/Theme/Layout/Content/Content';
+import type { LayoutProps } from './Layout.types';
+function Layout({
+  topBarConfig = false,
+  leftSidebarConfig = false,
+  rightSidebarConfig = false,
+  footerConfig = false,
+  children,
+}: LayoutProps) {
+  const hasTopBar = Boolean(topBarConfig);
+  const hasLeftSidebar = Boolean(leftSidebarConfig);
+  const hasRightSidebar = Boolean(rightSidebarConfig);
+  const leftInitialView =
+    typeof leftSidebarConfig === 'object' && 'initialView' in leftSidebarConfig
+      ? leftSidebarConfig.initialView
+      : undefined;
+  const rightInitialView =
+    typeof rightSidebarConfig === 'object' && 'initialView' in rightSidebarConfig
+      ? rightSidebarConfig.initialView
+      : undefined;
+  return (
+    <LeftSidebarProvider initialView={leftInitialView}>
+      <RightSidebarProvider initialView={rightInitialView}>
+        <Box
+          id="layout-root"
+          sx={{ display: 'flex', flexDirection: 'column', minHeight: '100vh' }}
+        >
+          {hasTopBar && (
+            <TopBar
+              {...(typeof topBarConfig === 'object'
+                ? (() => {
+                    const { showMenuButton, brandLogo, ...rest } = topBarConfig as any;
+                    return {
+                      ...rest,
+                      // Convention: use `brandLogo` as the config field, but TopBar expects `logo`.
+                      ...(brandLogo ? { logo: brandLogo } : {}),
+                    };
+                  })()
+                : {})}
+            />
+          )}
+          <Box sx={{ display: 'flex', flex: 1 }}>
+            {hasLeftSidebar && (
+              <LeftSidebar
+                elements={[]}
+                {...(typeof leftSidebarConfig === 'object' ? leftSidebarConfig : {})}
+              />
+            )}
+<Content>
+  {children ?? <Namespace />}
+</Content>
+            {hasRightSidebar && (
+              <RightSidebar
+                elements={[]}
+                {...(typeof rightSidebarConfig === 'object' ? rightSidebarConfig : {})}
+              />
+            )}
+          </Box>
+          {footerConfig && (
+            <Footer
+              {...(typeof footerConfig === 'object'
+                ? (() => {
+                    const {
+                      title,
+                      brandLabel,
+                      brandLogo,
+                      brandHref,
+                      brandAvatarFallback,
+                      leftElements,
+                      centerElements,
+                      rightElements,
+                      position,
+                      elevation,
+                      className,
+                      id,
+                      sx,
+                      appBarSx,
+                      sectionSx,
+                      'data-testid': dataTestId,
+                    } = footerConfig;
+                    return {
+                      brandLabel: brandLabel ?? title,
+                      brandLogo,
+                      brandHref,
+                      brandAvatarFallback,
+                      leftElements,
+                      centerElements,
+                      rightElements,
+                      position,
+                      elevation,
+                      className,
+                      id,
+                      sx,
+                      appBarSx,
+                      sectionSx,
+                      'data-testid': dataTestId,
+                    };
+                  })()
+                : {})}
+            />
+          )}
+        </Box>
+      </RightSidebarProvider>
+    </LeftSidebarProvider>
+  );
+}
+
+export default Layout;

package/src/gui/Theme/Layout/Layout/Layout.types.ts

@@ -0,0 +1,57 @@
+//@/gui/layouts/ResponsiveUI/Layout/Layout.types.ts
+import type { FooterElement } from '@/gui/Layouts/ResponsiveUI/Footer/Footer.types';
+
+export interface TopBarConfig {
+  showMenuButton?: boolean;
+  [key: string]: any;
+}
+
+export interface LeftSidebarConfig {
+  [key: string]: any;
+}
+
+export interface RightSidebarConfig {
+  [key: string]: any;
+}
+
+export interface FooterConfig {
+  title?: string;
+  brandLabel?: string;
+  brandLogo?: string;
+  brandHref?: string;
+  brandAvatarFallback?: string;
+  leftElements?: FooterElement[];
+  centerElements?: FooterElement[];
+  rightElements?: FooterElement[];
+  position?: 'static' | 'fixed' | 'sticky';
+  elevation?: number;
+  className?: string;
+  id?: string;
+  'data-testid'?: string;
+  sx?: any;
+  appBarSx?: any;
+  sectionSx?: any;
+}
+
+export interface LayoutProps {
+  topBarConfig?: TopBarConfig | boolean;
+  leftSidebarConfig?: LeftSidebarConfig | boolean;
+  rightSidebarConfig?: RightSidebarConfig | boolean;
+  footerConfig?: FooterConfig | boolean;
+  children?: React.ReactNode;
+}
+
+export interface ContentChild {
+  type: string;
+  props?: Record<string, any>;
+}
+
+export interface ContentProps {
+  children?: ContentChild[];
+}
+
+export interface LayoutSpec {
+  type: 'Layout';
+  props?: LayoutProps;
+  Content?: ContentProps[];
+}

package/src/gui/Theme/Layout/Layout/useLayoutBreakpoints.ts

@@ -0,0 +1,9 @@
+import { useGuiMediaQuery, useGuiTheme } from '@/gui/hooks';
+
+export function useLayoutBreakpoints() {
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down('md'));
+  const isTablet = useGuiMediaQuery(theme.breakpoints.between('md', 'lg'));
+  const isDesktop = useGuiMediaQuery(theme.breakpoints.up('lg'));
+  return { isMobile, isTablet, isDesktop };
+}

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

@@ -0,0 +1,105 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import Namespace from "./Namespace";
+import { GuiProvider } from "@/gui/Theme/GuiProvider";
+
+function withPath(path: string) {
+  return (Story: any) => {
+    // If Storybook (or your preview) already wraps stories in a Router,
+    // we must NOT render another Router here.
+    // Pushing a new history state is enough for BrowserRouter to pick up the path.
+    if (typeof window !== "undefined") {
+      window.history.pushState({}, "", path);
+    }
+    return <Story />;
+  };
+}
+
+const meta: Meta<typeof Namespace> = {
+  title: "Layout/Namespace",
+  component: Namespace,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Namespace** component is a tiny route resolver used inside the This.GUI layout shell.
+It reads the current URL **pathname** and decides which **namespace view** to render.
+
+---
+## What it does
+- Uses React Router (\`useLocation()\`) to read the current path.
+- Displays a simple **Unknown namespace** fallback that reflects the current pathname.
+- Useful as a placeholder outlet while namespace routing is being designed.
+
+---
+## When to use
+- As an internal “outlet” for layout shells that want to map namespaces/paths to organism-level views.
+- In Storybook to quickly test how new namespaces resolve without wiring a full app router.
+
+---
+## Notes
+- These stories assume Storybook (or your app shell) already provides a Router. The story uses \`window.history.pushState\` to simulate navigation.
+`,
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Namespace>;
+
+function Shell({ children }: { children: React.ReactNode }) {
+  return (
+    <GuiProvider>
+      <div
+        style={{
+          minHeight: "100vh",
+          display: "flex",
+          flexDirection: "column",
+        }}
+      >
+        {children}
+      </div>
+    </GuiProvider>
+  );
+}
+
+export const RootNamespace: Story = {
+  decorators: [withPath("/")],
+  render: () => (
+    <Shell>
+      <Namespace />
+    </Shell>
+  ),
+};
+
+export const VisorNamespace: Story = {
+  decorators: [withPath("/visor")],
+  render: () => (
+    <Shell>
+      <Namespace />
+    </Shell>
+  ),
+};
+
+export const VisorNamespaceDeepPath: Story = {
+  name: "Visor (deep path)",
+  decorators: [withPath("/visor/room/AB12CD")],
+  render: () => (
+    <Shell>
+      <Namespace />
+    </Shell>
+  ),
+};
+
+export const UnknownNamespace: Story = {
+  decorators: [withPath("/something/else")],
+  render: () => (
+    <Shell>
+      <Namespace />
+    </Shell>
+  ),
+};

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

@@ -0,0 +1,26 @@
+// Layout/Namespace/Namespace.tsx
+import React, { useMemo } from 'react';
+import { useLocation } from 'react-router-dom';
+import { Box, Typography } from '@/gui/components/atoms/atoms';
+// Import concrete blocks/views you want to render
+type Resolved =
+  | { kind: 'unknown'; path: string };
+function resolve(pathname: string): Resolved {
+  return { kind: 'unknown', path: pathname };
+}
+
+export default function Namespace() {
+  const { pathname } = useLocation();
+  const resolved = useMemo(() => resolve(pathname), [pathname]);
+  return (
+    <Box sx={{ p: 2 }}>
+      <Typography sx={{ fontWeight: 800 }}>Namespace</Typography>
+      <Typography sx={{ opacity: 0.75, fontFamily: 'monospace' }}>
+        {resolved.path}
+      </Typography>
+      <Typography sx={{ mt: 1, opacity: 0.7 }}>
+        View not wired yet.
+      </Typography>
+    </Box>
+  );
+}

package/src/gui/Theme/Layout/Sidebars/LeftSidebar/LeftSidebar.resolver.tsx

@@ -0,0 +1,87 @@
+// src/components/generics/AppBars/LeftSidebar/LeftSidebar.resolver.tsx
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/gui/registry/types';
+import LeftSidebar from './LeftSidebar';
+import Icon from '@/themes/Icon/Icon';
+/**
+ * Declarative spec for LeftSidebar.
+ * This is the JSON-friendly shape your renderer/LLM can emit.
+ */
+type RouteItemSpec = {
+  label: string;
+  href?: string;
+  external?: boolean;
+  icon?: string | React.ReactNode | React.ComponentType<any>;
+  iconColor?: string;
+  children?: RouteItemSpec[];
+};
+
+type LeftSidebarHeaderSpec = {
+  title?: string;
+  icon?: string | React.ReactNode | React.ComponentType<any>;
+  iconColor?: string;
+};
+
+type LeftSidebarSpec = {
+  type: 'LeftSidebar';
+  props?: {
+    // Behavior / layout
+    drawerWidth?: number; // px, default 240 (component default)
+    open?: boolean; // controlled open (temporary/mobile)
+    onCloseId?: string; // resolves to a function from ctx.handlers[onCloseId]
+    // Content
+    header?: LeftSidebarHeaderSpec; // optional header (title + icon)
+    drawerLinks?: RouteItemSpec[]; // navigation tree
+    // Style passthrough / misc
+    sx?: any;
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+  };
+};
+
+/**
+ * LeftSidebarResolver
+ * - Maps a JSON-friendly spec into <LeftSidebar /> props.
+ * - Doesn’t make layout decisions (permanent vs temporary): that logic lives in the component
+ *   via breakpoints. We just pass data and optional controlled "open"/"onClose".
+ * - `onCloseId` lets you bind to a handler from the outside world through the ResolveCtx.
+ */
+const LeftSidebarResolver: RegistryEntry = {
+  type: 'LeftSidebar',
+  resolve(spec: LeftSidebarSpec, ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    // Resolve handler by id from ctx (optional)
+    const onClose =
+      (p.onCloseId && ctx?.handlers && typeof ctx.handlers[p.onCloseId] === 'function')
+        ? ctx.handlers[p.onCloseId]
+        : undefined;
+    return (
+      <LeftSidebar
+        open={p.open}
+        onClose={onClose}
+        header={
+          p.header ? (
+            <div style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '0.5rem 1rem' }}>
+              {typeof p.header.icon === 'string'
+                ? <Icon name={p.header.icon} iconColor={p.header.iconColor} />
+                : React.isValidElement(p.header.icon)
+                  ? p.header.icon
+                  : typeof p.header.icon === 'function'
+                    ? React.createElement(p.header.icon)
+                    : null}
+              {p.header.title && <span>{p.header.title}</span>}
+            </div>
+          ) : undefined
+        }
+        drawerLinks={p.drawerLinks ?? []}
+        // style/misc passthrough
+        id={p.id}
+        className={p.className}
+        data-testid={p['data-testid']}
+      />
+    );
+  },
+};
+
+export default LeftSidebarResolver;