this.gui 1.3.40 → 1.3.42

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

@@ -0,0 +1,40 @@
+import type React from 'react';
+
+export type FooterLinkProps = {
+  label?: string;
+  href?: string;
+  icon?: string;
+  iconColor?: string;
+  external?: boolean;
+  onClick?: () => void;
+};
+
+export type FooterActionProps = {
+  label?: string;
+  icon?: string;
+  iconColor?: string;
+  onClick?: () => void;
+  element?: React.ReactNode;
+};
+
+export type FooterElement =
+  | { type: 'link'; props: FooterLinkProps }
+  | { type: 'action'; props: FooterActionProps };
+
+export type FooterProps = {
+  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;
+};

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

@@ -0,0 +1,37 @@
+import React from 'react';
+import Layout from './Layout';
+import type { RegistryEntry } from '@/gui/registry/types';
+import type { LayoutSpec } from './Layout.types';
+/**
+ * The LayoutResolver dynamically constructs a responsive layout
+ * using declarative JSON configuration.
+ *
+ * It resolves topBar, sidebars, footer, and content sections
+ * by passing their configs into the Layout component.
+ */
+const LayoutResolver: RegistryEntry = {
+  type: 'Layout',
+  resolve(spec: LayoutSpec) {
+    const props = spec.props ?? {};
+    const contentSections = spec.Content ?? [];
+    return (
+      <Layout
+        {...props}
+      >
+        {contentSections.map((section, index) => (
+          <React.Fragment key={index}>
+            {Array.isArray(section.children)
+              ? section.children.map((child, i) => (
+                  <div key={`${index}-${i}`} {...(child.props ?? {})}>
+                    {child.type}
+                  </div>
+                ))
+              : null}
+          </React.Fragment>
+        ))}
+      </Layout>
+    );
+  },
+};
+
+export default LayoutResolver;

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>
+  );
+}