this.gui 1.0.18 → 1.1.0

package/src/gui/molecules/AppBars/Footer/Footer.tsx

@@ -0,0 +1,307 @@
+import { Box, Typography, Link } from "@/gui/atoms";
+import { useGuiTheme, useGuiMediaQuery } from "@/gui";
+import Icon from "@/themes/icons/Icon";
+import type * as React from 'react';
+import type { SxProps, Theme } from '@mui/material/styles';
+// Utility: normalize optional SxProps into a single SxProps (filters out undefined)
+const sxN = (...parts: Array<SxProps<Theme> | undefined>): SxProps<Theme> =>
+  (parts.filter(Boolean) as unknown) as SxProps<Theme>;
+export type LinkItem = {
+  label: string;
+  href: string;
+  external?: boolean;
+};
+
+export type SocialLink = {
+  icon: string | React.ReactNode;
+  href: string;
+  iconColor?: string;
+};
+
+export type FooterProps = {
+  title?: string;
+  logoSrc?: string;
+  homeHref?: string;
+  brandComponent?: any;  // ElementType for SPA routing (e.g., Link)
+  brandTo?: string;      // Destination for SPA routing
+  onBrandClick?: () => void;
+  socialLinks?: SocialLink[];
+  links?: LinkItem[];
+  leftInset?: number;
+  rightInset?: number;
+  startSlot?: React.ReactNode;
+  endSlot?: React.ReactNode;
+  linkProps?: React.ComponentProps<typeof Link>;
+  iconProps?: Record<string, any>;
+  id?: string;
+  className?: string;
+  'data-testid'?: string;
+
+  // Granular styling overrides
+  sx?: SxProps<Theme>;              // root footer container
+  leftSx?: SxProps<Theme>;          // left cluster (social + startSlot)
+  centerSx?: SxProps<Theme>;        // center links container
+  rightSx?: SxProps<Theme>;         // right cluster (brand + endSlot)
+  brandSx?: SxProps<Theme>;         // wrapper around brand (logo + title)
+  logoSx?: SxProps<Theme>;          // logo image
+  titleSx?: SxProps<Theme>;         // title typography
+  socialLinkSx?: SxProps<Theme>;    // each social link <Link>
+  navLinkSx?: SxProps<Theme>;       // each center link <Link>
+};
+
+export default function Footer({
+  title = "neurons.me",
+  logoSrc,
+  homeHref,
+  brandComponent,
+  brandTo,
+  onBrandClick,
+  socialLinks = [],
+  links = [],
+  leftInset,
+  rightInset,
+  startSlot,
+  endSlot,
+  linkProps,
+  iconProps,
+  id,
+  className,
+  'data-testid': dataTestId,
+  sx,
+  leftSx,
+  centerSx,
+  rightSx,
+  brandSx,
+  logoSx,
+  titleSx,
+  socialLinkSx,
+  navLinkSx,
+}: FooterProps) {
+  // Theme + media
+  const theme = useGuiTheme();
+  const isMobile = useGuiMediaQuery(theme.breakpoints.down("sm"));
+  const toCssSize = (v: number | string | undefined, fallback: string = '0px'): string => {
+    if (v == null) return fallback;
+    if (typeof v === 'number') return `${v}px`;
+    const s = String(v);
+    // if already has unit, return as-is
+    return /[a-z%]+$/i.test(s) ? s : `${s}px`;
+  };
+
+  const themeLeftInset = theme?.layout?.insets?.left ?? theme?.insets?.left;
+  const themeRightInset = theme?.layout?.insets?.right ?? theme?.insets?.right;
+  const effectiveLeftInset = toCssSize(
+    leftInset != null ? leftInset : themeLeftInset,
+    '0px'
+  );
+  const effectiveRightInset = toCssSize(
+    rightInset != null ? rightInset : themeRightInset,
+    '0px'
+  );
+
+  const effectiveLogo =
+    logoSrc && String(logoSrc).trim().length > 0
+      ? logoSrc
+      : "https://www.neurons.me/media/neurons-grey.png"; // required fallback
+
+  const activateOnKey = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      if (onBrandClick) onBrandClick();
+    }
+  };
+
+  const Brand = onBrandClick ? (
+    // Button-like div when an explicit click handler is provided (keyboard accessible)
+    <Box
+      sx={sxN(
+        { display: 'flex', alignItems: 'center', gap: 1, cursor: 'pointer' },
+        brandSx
+      )}
+      onClick={onBrandClick}
+      onKeyDown={activateOnKey}
+      role="button"
+      tabIndex={0}
+      aria-label={title}
+    >
+      <Box component="img" src={effectiveLogo} alt={`${title} logo`} sx={sxN({ width: 28, height: 28 }, logoSx)} />
+      {title && (
+        <Typography
+          variant="subtitle1"
+          sx={sxN({ color: theme.palette.text.primary, fontWeight: 600 }, titleSx)}
+        >
+          {title}
+        </Typography>
+      )}
+    </Box>
+  ) : brandComponent && brandTo ? (
+    // SPA routing: use provided brandComponent (e.g., This.GUI Link) with `to`
+    <Box
+      component={brandComponent as any}
+      to={brandTo}
+      sx={sxN(
+        { display: 'flex', alignItems: 'center', gap: 1, textDecoration: 'none', cursor: 'pointer' },
+        brandSx
+      )}
+      aria-label={title}
+    >
+      <Box component="img" src={effectiveLogo} alt={`${title} logo`} sx={sxN({ width: 28, height: 28 }, logoSx)} />
+      {title && (
+        <Typography
+          variant="subtitle1"
+          sx={sxN({ color: theme.palette.text.primary, fontWeight: 600 }, titleSx)}
+        >
+          {title}
+        </Typography>
+      )}
+    </Box>
+  ) : homeHref ? (
+    // Semantic anchor when a homeHref is provided (SSR/router safe)
+    <Box
+      component="a"
+      href={homeHref}
+      sx={sxN(
+        { display: 'flex', alignItems: 'center', gap: 1, textDecoration: 'none', cursor: 'pointer' },
+        brandSx
+      )}
+      aria-label={title}
+    >
+      <Box component="img" src={effectiveLogo} alt={`${title} logo`} sx={sxN({ width: 28, height: 28 }, logoSx)} />
+      {title && (
+        <Typography
+          variant="subtitle1"
+          sx={sxN({ color: theme.palette.text.primary, fontWeight: 600 }, titleSx)}
+        >
+          {title}
+        </Typography>
+      )}
+    </Box>
+  ) : (
+    // Non-clickable brand
+    <Box
+      sx={sxN(
+        { display: 'flex', alignItems: 'center', gap: 1, cursor: 'default' },
+        brandSx
+      )}
+      aria-label={title}
+    >
+      <Box component="img" src={effectiveLogo} alt={`${title} logo`} sx={sxN({ width: 28, height: 28 }, logoSx)} />
+      {title && (
+        <Typography
+          variant="subtitle1"
+          sx={sxN({ color: theme.palette.text.primary, fontWeight: 600 }, titleSx)}
+        >
+          {title}
+        </Typography>
+      )}
+    </Box>
+  );
+
+  const renderIcon = (item: SocialLink): React.ReactNode => {
+    const { icon, iconColor } = item || {};
+    if (!icon) return null;
+    if (typeof icon === "string") {
+      // Declarative via registry
+      return (
+        <Icon
+          name={icon}
+          iconColor={iconColor}
+          size={20}
+          {...iconProps}
+        />
+      );
+    }
+    // React element provided directly
+    return icon;
+  };
+
+  const { sx: linkPropsSx, ...restLinkProps } = linkProps || ({} as any);
+
+  return (
+    // Footer respects global insets from ThemeProvider
+    <Box
+      component="footer"
+      id={id}
+      className={className}
+      data-testid={dataTestId}
+      sx={sxN(
+        {
+          width: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          py: 1,
+          pl: { xs: 2, sm: `calc(${effectiveLeftInset} + ${theme.spacing(3)})` },
+          pr: { xs: 2, sm: `calc(${effectiveRightInset} + ${theme.spacing(3)})` },
+          borderTop: `1px solid ${theme.palette.divider}`,
+          bgcolor: theme.palette.background.paper,
+          transition: 'padding-left 0.3s ease, padding-right 0.3s ease',
+          gap: 2,
+          boxSizing: 'border-box',
+        },
+        sx
+      )}
+    >
+      {/* Left cluster: social icons + optional start slot */}
+      <Box sx={sxN({ display: 'flex', alignItems: 'center', gap: 1, flex: '0 0 auto', minWidth: 0 }, leftSx)}>
+        {socialLinks?.map((item, idx) => (
+          <Box key={idx} sx={{ display: "flex", alignItems: "center" }}>
+            <Link
+              href={item.href}
+              target="_blank"
+              rel="noopener noreferrer"
+              underline="none"
+              aria-label={typeof item.icon === 'string' ? item.icon : 'social link'}
+              {...restLinkProps}
+              sx={sxN({ display: 'flex', alignItems: 'center' }, linkPropsSx as any, socialLinkSx)}
+            >
+              {renderIcon(item)}
+            </Link>
+          </Box>
+        ))}
+        {startSlot}
+      </Box>
+
+      {/* Center: links stack (responsive) */}
+      <Box
+        sx={sxN(
+          {
+            display: 'flex',
+            flexDirection: isMobile ? 'column' : 'row',
+            alignItems: isMobile ? 'flex-start' : 'center',
+            justifyContent: 'center',
+            flex: '1 1 auto',
+            minWidth: 0,
+            flexWrap: isMobile ? 'nowrap' : 'wrap',
+            gap: isMobile ? 0.5 : 2,
+          },
+          centerSx
+        )}
+      >
+        {links?.map(({ label, href, external }, idx) => (
+          <Link
+            key={`${label}-${idx}`}
+            href={href}
+            underline="none"
+            target={external ? '_blank' : undefined}
+            rel={external ? 'noopener noreferrer' : undefined}
+            {...restLinkProps}
+            sx={sxN(
+              { color: theme.palette.text.primary, fontSize: 14, fontWeight: 500, '&:hover': { textDecoration: 'underline' } },
+              linkPropsSx as any,
+              navLinkSx
+            )}
+          >
+            {label}
+          </Link>
+        ))}
+      </Box>
+
+      {/* Right cluster: branding + optional end slot */}
+      <Box sx={sxN({ display: 'flex', alignItems: 'center', gap: 2, flex: '0 0 auto', minWidth: 0 }, rightSx)}>
+        {Brand}
+        {endSlot}
+      </Box>
+    </Box>
+  );
+}

package/src/gui/molecules/AppBars/LeftSidebar/LeftSidebar.resolver.tsx

@@ -0,0 +1,75 @@
+// src/components/generics/AppBars/LeftSidebar/LeftSidebar.resolver.tsx
+import * as React from 'react';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import LeftSidebar from './LeftSidebar';
+/**
+ * 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
+        drawerWidth={p.drawerWidth}
+        open={p.open}
+        onClose={onClose}
+        header={p.header}
+        drawerLinks={p.drawerLinks ?? []}
+        // style/misc passthrough
+        sx={p.sx as any}
+        id={p.id}
+        className={p.className}
+        data-testid={p['data-testid']}
+      />
+    );
+  },
+};
+
+export default LeftSidebarResolver;

package/src/gui/molecules/AppBars/LeftSidebar/LeftSidebar.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box } from '@mui/material';
+import LeftSidebar from './LeftSidebar';
+import TopBar from '../TopBar/TopBar';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '../../../../context/GuiProvider';
+import Layout from '@/templates/Layout';
+
+// Demo routes with icons + nested items
+const sampleLinks = [
+  { label: 'Home', href: '/', icon: 'lucide:Home' },
+  { label: 'Sockets', href: '/sockets', icon: 'mui:Power' },
+  {
+    label: 'Settings',
+    icon: 'mui:Settings',
+    children: [
+      { label: 'Profile', href: '/settings/profile', icon: 'lucide:User' },
+      { label: 'Billing', href: '/settings/billing', icon: 'lucide:CreditCard' },
+    ],
+  },
+  { label: 'Docs (ext)', href: 'https://neurons.me', external: true, icon: 'lucide:BookOpen' },
+];
+
+const meta: Meta<typeof LeftSidebar> = {
+  title: 'Molecules/AppBars/LeftSidebar',
+  component: LeftSidebar,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <MemoryRouter initialEntries={["/"]}>
+        <GuiProvider>
+          <Story />
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof LeftSidebar>;
+
+export const SidebarOnly: Story = {
+  render: () => (
+    <Layout hasLeftSidebar>
+      <LeftSidebar railMode drawerLinks={sampleLinks} />
+      <Box sx={{ flex: 1, bgcolor: 'background.default' }} />
+    </Layout>
+  ),
+};
+
+export const SidebarWithTopbar: Story = {
+  render: () => (
+    <Layout hasLeftSidebar hasTopBar>
+      <TopBar title="Demo" showMenuButton={false} />
+      <LeftSidebar railMode={false} drawerLinks={sampleLinks} />
+      <Box sx={{ flex: 1, bgcolor: 'background.default' }} />
+    </Layout>
+  ),
+};