this.gui 1.3.22 → 1.3.26

package/src/gui/Layouts/ResponsiveUI/Layout/Layout.tsx

@@ -0,0 +1,112 @@
+import { LeftSidebarProvider } from '@/gui/contexts/LeftSidebarContext';
+import { RightSidebarProvider } from '@/gui/contexts/RightSidebarContext';
+import { Box } from '@/gui/components/atoms';
+import TopBar from '@/gui/Layouts/ResponsiveUI/TopBar/TopBar';
+import LeftSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/LeftSidebar/LeftSidebar';
+import RightSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/RightSidebar/RightSidebar';
+import Footer from '@/gui/Layouts/ResponsiveUI/Footer/Footer';
+import { Outlet } from 'react-router-dom';
+import Content from '@/gui/Layouts/ResponsiveUI/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, ...rest } = topBarConfig;
+                    return rest;
+                  })()
+                : {})}
+            />
+          )}
+          <Box sx={{ display: 'flex', flex: 1 }}>
+            {hasLeftSidebar && (
+              <LeftSidebar
+                elements={[]}
+                {...(typeof leftSidebarConfig === 'object' ? leftSidebarConfig : {})}
+              />
+            )}
+            <Content>
+              {children ?? <Outlet />}
+            </Content>
+            {hasRightSidebar && (
+              <RightSidebar
+                elements={[]}
+                {...(typeof rightSidebarConfig === 'object' ? rightSidebarConfig : {})}
+              />
+            )}
+          </Box>
+          {footerConfig && (
+            <Footer
+              {...(typeof footerConfig === 'object'
+                ? (() => {
+                    const {
+                      brandLabel,
+                      brandLogo,
+                      brandHref,
+                      brandAvatarFallback,
+                      leftElements,
+                      centerElements,
+                      rightElements,
+                      position,
+                      elevation,
+                      className,
+                      id,
+                      sx,
+                      appBarSx,
+                      sectionSx,
+                      'data-testid': dataTestId,
+                    } = footerConfig;
+                    return {
+                      brandLabel,
+                      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/Layouts/ResponsiveUI/Layout/Layout.types.ts

@@ -0,0 +1,56 @@
+//@/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 {
+  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/Layouts/ResponsiveUI/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/Layouts/ResponsiveUI/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 '@/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;

package/src/gui/Layouts/ResponsiveUI/Sidebars/LeftSidebar/LeftSidebar.stories.tsx

@@ -0,0 +1,199 @@
+import { StoryFn } from "@storybook/react";
+import React from "react";
+import Layout from "@/gui/Layouts/ResponsiveUI/Layout/Layout";
+import ThemeModeToggle from "@/gui/components/molecules/Theme/ThemeModeToggle/ThemeModeToggle";
+
+export default {
+  title: "Layouts/ResponsiveUI/Sidebars/LeftSidebar",
+  component: Layout,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+`The **LeftSidebar** component provides the navigation rail for ResponsiveUI layouts. It keeps content aligned with other structural elements (TopBar, RightSidebar) while offering a consistent spot for primary navigation and quick actions.
+---
+## Features
+- **Rail-first layout:** Starts in rail view by default to maximize canvas space while keeping icons reachable.
+- **Expanded navigation:** Users can switch to an expanded width for descriptive labels and nested menus.
+- **Mobile overlay:** On compact viewports it becomes a temporary drawer that overlays content and releases the left inset.
+- **Footer actions:** Optional \`footerElements\` allow secondary actions (e.g. settings, help) that stay pinned to the bottom.
+- **Inset sync:** Updates \`theme.layout.insets.left\` so surrounding layouts and the TopBar shift automatically.
+
+---
+## Layout Variants
+- \`rail\`: 72px icon rail, best for dense productivity layouts.
+- \`expanded\`: 264px panel with labels and nested menu support.
+- \`mobile\`: Drawer that covers the screen content and is controlled by a floating toggle button.
+The sidebar transitions between these modes automatically based on breakpoints, but you can also set them manually via \`useLeftSidebar()\`.
+
+---
+## Props
+- \`elements: LeftSidebarElement[]\` — Main navigation items. Supports \`link\`, \`menu\`, and \`action\` types.
+- \`footerElements?: LeftSidebarElement[]\` — Optional persistent actions rendered in the footer.
+- \`initialView?: 'rail' | 'expanded' | 'mobile'\` — Starting layout; defaults to \`rail\`.
+- \`className?, ...rest\` — Standard layout props forwarded to the root container.
+
+---
+## Declarative usage
+~~~tsx
+import LeftSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/LeftSidebar/LeftSidebar';
+
+<LeftSidebar
+  initialView="rail"
+  elements={[
+    { type: 'link', props: { label: 'Dashboard', icon: 'dashboard' } },
+    { type: 'link', props: { label: 'Analytics', icon: 'bar_chart' } },
+    {
+      type: 'menu',
+      props: {
+        label: 'Projects',
+        icon: 'folder',
+        items: [
+          { label: 'Active', icon: 'task' },
+          { label: 'Archive', icon: 'inventory_2' },
+        ],
+      },
+    },
+  ]}
+  footerElements={[
+    { type: 'link', props: { label: 'Settings', icon: 'settings' } },
+    { type: 'action', props: { label: 'Sign out', icon: 'logout' } },
+  ]}
+/>;
+~~~
+
+---
+## React usage
+Wrap your layout with \`LeftSidebarProvider\` and consume \`useLeftSidebar()\` to control the view programmatically:
+~~~tsx
+import { LeftSidebarProvider } from '@/gui/contexts';
+import LeftSidebar from '@/gui/Layouts/ResponsiveUI/Sidebars/LeftSidebar/LeftSidebar';
+import { useLeftSidebar } from '@/gui/hooks';
+
+const navItems = [
+  { type: 'link', props: { label: 'Dashboard', icon: 'dashboard' } },
+  { type: 'link', props: { label: 'Billing', icon: 'receipt_long' } },
+];
+
+function Shell() {
+  const { view, setView } = useLeftSidebar();
+  return (
+    <>
+      <button onClick={() => setView(view === 'expanded' ? 'rail' : 'expanded')}>
+        Toggle mode
+      </button>
+      <LeftSidebar elements={navItems} />
+    </>
+  );
+}
+
+export function AppShell() {
+  return (
+    <LeftSidebarProvider>
+      <Shell />
+    </LeftSidebarProvider>
+  );
+}
+~~~
+
+---
+## Notes
+- Mobile mode is triggered automatically below the \`sm\` breakpoint; the floating toggle re-opens the drawer.
+- The sidebar updates the global inset each time the view changes, keeping the TopBar and page content aligned.
+- Combine with the \`TopBar\` story to see how the two components cooperate in responsive layouts.
+`,
+      },
+    },
+  },
+};
+
+const Template: StoryFn<React.ComponentProps<typeof Layout>> = (args) => (
+  <Layout {...args} />
+);
+
+export const Default = Template.bind({});
+Default.args = {
+  topBarConfig: {
+    title: "My Application",
+    elementsRight: [
+      { type: "link", props: { label: "Profile", icon: "account_circle" } },
+      {
+        type: "action",
+        props: {
+          element: <ThemeModeToggle variant="minimal" show="icons" iconSize="small" />,
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)" } },
+    ],
+  },
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Analytics", icon: "bar_chart", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-warning)",
+          items: [
+            { label: "Project A", icon: "work", iconColor: "var(--gui-success)" },
+            { label: "Project B", icon: "assignment", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)", action: "handleLogout" } },
+    ],
+  },
+};
+
+export const WithoutTopBar = Template.bind({});
+WithoutTopBar.args = {
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Analytics", icon: "bar_chart", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-warning)",
+          items: [
+            { label: "Project A", icon: "work", iconColor: "var(--gui-success)" },
+            { label: "Project B", icon: "assignment", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)", action: "handleLogout" } },
+    ],
+  },
+};
+
+export const WithFooter = Template.bind({});
+WithFooter.args = {
+  leftSidebarConfig: {
+    elements: [
+      { type: "link", props: { label: "Dashboard", icon: "dashboard", iconColor: "var(--gui-primary)" } },
+      { type: "link", props: { label: "Analytics", icon: "bar_chart", iconColor: "var(--gui-secondary)" } },
+      {
+        type: "menu",
+        props: {
+          label: "Projects",
+          icon: "folder",
+          iconColor: "var(--gui-warning)",
+          items: [
+            { label: "Project A", icon: "work", iconColor: "var(--gui-success)" },
+            { label: "Project B", icon: "assignment", iconColor: "var(--gui-info)" },
+          ],
+        },
+      },
+      { type: "action", props: { label: "Logout", icon: "logout", iconColor: "var(--gui-error)", action: "handleLogout" } },
+    ],
+    footerElements: [
+      { type: "link", props: { label: "Settings", icon: "settings", iconColor: "var(--gui-primary)" } },
+      { type: "action", props: { label: "Help", icon: "help", iconColor: "var(--gui-success)" } },
+    ],
+  },
+};