this.gui 1.3.22 → 1.3.26

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarAction/TopBarAction.stories.tsx

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import TopBarAction from './TopBarAction';
+import Icon from '@/gui/Theme/Icon/Icon';
+
+const meta: Meta<typeof TopBarAction> = {
+  title: 'Layouts/ResponsiveUI/TopBar/TopBarAction',
+  component: TopBarAction,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **TopBarAction** component is a simple wrapper designed for placing interactive or visual elements (like icons, buttons, or toggles) inside the TopBar.
+
+It standardizes alignment, spacing, and styling for small atomic actions in the top navigation area.
+
+---
+
+### 🧩 Features
+- Wraps any ReactNode element inside a styled container.
+- Accepts custom \`className\` and \`style\` props for styling flexibility.
+- Commonly used to host action icons, buttons, or mini components in the TopBar.
+
+---
+
+### ⚙️ Props
+| Name | Type | Default | Description |
+|------|------|----------|-------------|
+| \`element\` | \`ReactNode\` | — | The element to render inside the TopBar action slot. |
+| \`className?\` | \`string\` | — | Optional class name for extra styling. |
+| \`style?\` | \`React.CSSProperties\` | — | Inline style overrides. |
+
+---
+
+### 🧠 Behavior
+TopBarAction is purely structural — it doesn’t manage state or events.
+It ensures consistent alignment and padding so that icons or buttons within the TopBar remain visually balanced.
+
+---
+
+### 🧩 Example Usage
+
+#### React
+~~~tsx
+import TopBarAction from '@/gui/Layouts/TopBar/TopBarAction';
+import Icon from '@/themes/Icon/Icon';
+
+export const Example = () => (
+  <div style={{ display: 'flex', gap: '1rem' }}>
+    <TopBarAction element={<Icon name="notifications" />} />
+    <TopBarAction element={<Icon name="settings" iconColor="#1976d2" />} />
+    <TopBarAction element={<button>Click me</button>} />
+  </div>
+);
+~~~
+
+#### Declarative JSON
+~~~json
+{
+  "type": "TopBarAction",
+  "props": {
+    "element": {
+      "type": "Icon",
+      "props": { "name": "notifications" }
+    },
+    "style": { "marginRight": "8px" }
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TopBarAction>;
+
+export const Playground: Story = {
+  args: {
+    element: <Icon name="notifications" />,
+  },
+};

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarAction/TopBarAction.tsx

@@ -0,0 +1,18 @@
+import React, { ReactNode } from 'react';
+import clsx from 'clsx';
+
+export type TopBarActionProps = {
+  element: ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+const TopBarAction: React.FC<TopBarActionProps> = ({ element, className, style }) => {
+  return (
+    <div className={clsx('TopBarAction', className)} style={style}>
+      {element}
+    </div>
+  );
+};
+
+export default TopBarAction;

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarAction/TopBarAction.types.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export type TopBarActionProps = {
+  element: ReactNode;
+};

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarLink/TopBarLink.stories.tsx

@@ -0,0 +1,189 @@
+/**
+ * ## TopBarLink Component
+ *
+ * `TopBarLink` represents an individual navigation link for the TopBar.
+ * It supports icons, color customization, and responsive label visibility.
+ *
+ * ---
+ *
+ * ### 🧩 Props
+ *
+ * | Prop         | Type        | Description |
+ * |---------------|-------------|-------------|
+ * | `label`       | `string`    | The text displayed next to the icon. |
+ * | `href`        | `string`    | The target URL or route. |
+ * | `icon`        | `string?`   | Optional icon name from the `Icon` component (Material Symbols). |
+ * | `iconColor`   | `string?`   | Optional custom color for the icon (defaults to `currentColor`). |
+ * | `external`    | `boolean?`  | If true, opens the link in a new tab (`target="_blank"`). |
+ * | `showLabel`   | `boolean?`  | Determines whether to show the label (used for responsive collapse). Defaults to `true`. |
+ *
+ * ---
+ *
+ * ### 💡 Responsive Behavior
+ *
+ * The `TopBarLink` component automatically adapts to screen size:
+ *
+ * | Viewport | Behavior |
+ * |-----------|-----------|
+ * | **Desktop (≥900px)** | Shows icon + label. |
+ * | **Tablet (600–899px)** | Shows only icons (`showLabel = false`). |
+ * | **Mobile (<600px)** | Collapsed within grouped menus (managed by `TopBar`). |
+ *
+ * In mobile view, individual `TopBarLink` components are typically grouped under a collapsed menu icon (such as `settings` or `more_horiz`), handled by the TopBar responsiveness system.
+ *
+ * ---
+ *
+ * ### 📘 Examples
+ * - `Basic` → Simple text link.
+ * - `WithIcon` → Link with an icon.
+ * - `IconOnly` → Icon-only mode (used for tablet responsiveness).
+ * - `ExternalLink` → Opens an external page in a new tab.
+ * - `ColoredIcon` → Example with custom icon color.
+ */
+import type { Meta, StoryObj } from '@storybook/react';
+import TopBarLink from './TopBarLink';
+// ======================= Meta =======================
+const meta: Meta<typeof TopBarLink> = {
+  title: 'Layouts/ResponsiveUI/TopBar/TopBarLink',
+  component: TopBarLink,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **TopBarLink** component represents an individual link or navigation item inside the TopBar.
+It supports icons, color customization, and responsive label visibility.
+
+---
+
+## Features
+- Displays a **label**, **icon**, or both depending on viewport size.
+- Automatically adapts to screen width through responsive breakpoints.
+- External links open in a new tab when \`external = true\`.
+- The label visibility can be controlled with the \`showLabel\` prop for tablet responsiveness.
+- Works seamlessly with **TopBar** to handle desktop, tablet, and mobile layouts.
+
+---
+
+## Responsiveness
+The \`TopBarLink\` automatically adapts to viewport width using MUI's breakpoints:
+
+| Viewport | Range | Behavior |
+|-----------|--------|-----------|
+| **Desktop** | ≥ 900px | Shows icon + label |
+| **Tablet** | 600–899px | Shows icons only (label hidden) |
+| **Mobile** | < 600px | Included in collapsed TopBar menu |
+
+---
+
+## Key Props
+| Prop | Type | Description |
+|------|------|-------------|
+| \`label\` | \`string\` | The text shown beside the icon. |
+| \`href\` | \`string\` | The URL or route the link navigates to. |
+| \`icon\` | \`string\` | Material icon name. Optional. |
+| \`iconColor\` | \`string\` | Custom icon color. Defaults to \`currentColor\`. |
+| \`external\` | \`boolean\` | Opens the link in a new tab if true. |
+| \`showLabel\` | \`boolean\` | Controls label visibility (used in responsive layouts). |
+
+---
+
+### Basic usage (React)
+~~~tsx
+import TopBarLink from '@/gui/Layouts/TopBar/TopBarLink';
+
+<TopBarLink label="Home" href="/" icon="home" />
+~~~
+
+---
+### In a responsive TopBar
+~~~tsx
+<TopBar
+  title="neurons.me"
+  elementsRight={[
+    { type: 'link', props: { label: 'Home', href: '/', icon: 'home' } },
+    { type: 'link', props: { label: 'Settings', href: '/settings', icon: 'settings' } }
+  ]}
+/>
+~~~
+
+---
+
+## Declarative JSON / Config usage
+The **TopBarLink** can also be described declaratively within a resolver-driven UI definition.
+
+### 🧩 Example usage
+
+#### React
+~~~tsx
+import TopBarLink from '@/gui/Layouts/TopBar/TopBarLink';
+
+export const Example = () => (
+  <div style={{ display: 'flex', gap: '1rem' }}>
+    <TopBarLink label="Home" href="/" icon="home" />
+    <TopBarLink label="Profile" href="/profile" icon="person" />
+    <TopBarLink label="Settings" href="/settings" icon="settings" iconColor="#1976d2" />
+  </div>
+);
+~~~
+
+#### Declarative JSON
+~~~json
+{
+  "type": "TopBar",
+  "props": {
+    "title": "neurons.me",
+    "elementsRight": [
+      { "type": "TopBarLink", "props": { "label": "Home", "href": "/", "icon": "home" } },
+      { "type": "TopBarLink", "props": { "label": "Profile", "href": "/profile", "icon": "person" } },
+      { "type": "TopBarLink", "props": { "label": "Settings", "href": "/settings", "icon": "settings", "iconColor": "#1976d2" } }
+    ]
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+  argTypes: {
+    label: { control: 'text', description: 'Text label displayed next to the icon.' },
+    href: { control: 'text', description: 'URL or route target.' },
+    icon: { control: 'text', description: 'Material icon name (string).' },
+    iconColor: { control: 'color', description: 'Custom icon color.' },
+    external: { control: 'boolean', description: 'Open link in new tab if true.' },
+    showLabel: { control: 'boolean', description: 'Determines label visibility.' },
+  },
+  args: {
+    label: 'Home',
+    href: '/',
+    icon: 'home',
+    iconColor: 'currentColor',
+    external: false,
+    showLabel: true,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof TopBarLink>;
+
+// ======================= Stories =======================
+export const Basic: Story = {
+  args: { label: 'Home', href: '/' },
+};
+
+export const WithIcon: Story = {
+  args: { label: 'Dashboard', href: '/dashboard', icon: 'dashboard' },
+};
+
+export const IconOnly: Story = {
+  args: { label: 'Profile', href: '/profile', icon: 'person', showLabel: false },
+};
+
+export const ExternalLink: Story = {
+  args: { label: 'GitHub', href: 'https://github.com', external: true, icon: 'code' },
+};
+
+export const ColoredIcon: Story = {
+  args: { label: 'Settings', href: '/settings', icon: 'settings', iconColor: '#1976d2' },
+};

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarLink/TopBarLink.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import Link from '@/gui/components/atoms/Link/Link'; // Adjust import path if necessary
+import Icon from '@/gui/Theme/Icon/Icon'; // Import Icon component
+import type { TopBarLinkProps } from './TopBarLink.types';
+const TopBarLink: React.FC<TopBarLinkProps> = ({ label, href, icon, iconColor, external, showLabel = true }) => {
+  const content = (
+    <>
+      {icon && (
+        <Icon
+          name={icon}
+          iconColor={iconColor || 'currentColor'}
+          style={{ marginRight: 3, fontSize: 20, position: 'relative', top: -1 }}
+        />
+      )}
+      {showLabel && <span>{label}</span>}
+    </>
+  );
+
+  return (
+    <Link
+      href={href ?? '#'}
+      target={external ? '_blank' : '_self'}
+      style={{ display: 'inline-flex', alignItems: 'center', color: 'inherit', textDecoration: 'none' }}
+    >
+      {content}
+    </Link>
+  );
+};
+
+export default TopBarLink;

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarLink/TopBarLink.types.ts

@@ -0,0 +1,9 @@
+export type TopBarLinkProps = {
+  label: string;
+  href: string;
+  icon?: string;
+  external?: boolean;
+  iconColor?: string;
+  /** Whether to display the label next to the icon. Defaults to true. */
+  showLabel?: boolean;
+};

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarMenu/TopBarMenu.resolver.tsx

@@ -0,0 +1,14 @@
+import type { TopBarMenuResolverSpec } from './TopBarMenu.types';
+
+const resolver: TopBarMenuResolverSpec = {
+  type: 'TopBarMenu',
+  props: {
+    label: 'Menu',
+    items: [
+      { label: 'About', href: '/about' },
+      { label: 'Contact', href: '/contact' },
+    ],
+  },
+};
+
+export default resolver;

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarMenu/TopBarMenu.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta } from '@storybook/react';
+import TopBarMenu from './TopBarMenu';
+const meta: Meta<typeof TopBarMenu> = {
+  component: TopBarMenu,
+  title: 'Layouts/ResponsiveUI/TopBar/TopBarMenu',
+};
+
+export default meta;
+export const ReactUsage = () => (
+  <TopBarMenu
+    label="More"
+    items={[
+      { label: 'About', href: '/about' },
+      { label: 'Contact', href: '/contact' },
+      { label: 'External', href: 'https://external.com', external: true },
+    ]}
+  />
+);
+
+export const DeclarativeUsage = {
+  type: 'menu',
+  props: {
+    label: 'More',
+    items: [
+      { label: 'About', href: '/about' },
+      { label: 'Contact', href: '/contact' },
+      { label: 'External', href: 'https://external.com', external: true },
+    ],
+  },
+};
+
+export const NestedItemsExample = () => (
+  <TopBarMenu
+    label="Services"
+    items={[
+      { label: 'Web Development', href: '/services/web' },
+      {
+        label: 'Design',
+        href: '/services/design',
+        items: [
+          { label: 'UI Design', href: '/services/design/ui' },
+          { label: 'UX Research', href: '/services/design/ux' },
+          {
+            label: 'Branding',
+            href: '/services/design/branding',
+            items: [
+              { label: 'Logo Design', href: '/services/design/branding/logo' },
+              { label: 'Identity Systems', href: '/services/design/branding/identity' },
+            ],
+          },
+        ],
+      },
+      { label: 'Consulting', href: '/services/consulting' },
+    ]}
+  />
+);

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarMenu/TopBarMenu.tsx

@@ -0,0 +1,123 @@
+import Icon from '@/gui/Theme/Icon/Icon';
+import React, { useState } from 'react';
+import { Menu, MenuItem, Typography } from '@mui/material';
+import Link from '@/gui/components/atoms/Link/Link';
+import type { TopBarMenuProps, TopBarMenuItemProps } from './TopBarMenu.types';
+
+const renderMenuItems = (
+  items: TopBarMenuItemProps[],
+  handleClose: () => void,
+  expandedItems: Set<string>,
+  toggleExpand: (label: string) => void
+): React.ReactElement[] =>
+  items.map(({ label, href, icon, iconColor, external, items: subItems }) => {
+    const isExpanded = expandedItems.has(label);
+
+    const content = (
+      <Link
+        to={!external ? href : undefined}
+        href={external ? href : undefined}
+        target={external ? '_blank' : undefined}
+        style={{ display: 'inline-flex', alignItems: 'center', color: 'inherit', textDecoration: 'none', flexGrow: 1 }}
+      >
+        {icon && (
+          <Icon
+            name={typeof icon === 'string' ? icon : 'info'}
+            iconColor={iconColor || 'currentColor'}
+            style={{ marginRight: 2, fontSize: 20, position: 'relative', top: -1 }}
+          />
+        )}
+        {label}
+      </Link>
+    );
+
+    if (subItems && subItems.length > 0) {
+      return (
+        <React.Fragment key={label}>
+          <MenuItem
+            onClick={() => toggleExpand(label)}
+            sx={{ color: 'inherit', display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}
+          >
+            {content}
+            <Icon
+              name={isExpanded ? 'expand_less' : 'expand_more'}
+              iconColor="currentColor"
+              style={{ fontSize: 20, position: 'relative', top: -1, marginLeft: 1 }}
+            />
+          </MenuItem>
+          <div
+            style={{
+              maxHeight: isExpanded ? '500px' : '0px',
+              opacity: isExpanded ? 1 : 0,
+              overflow: 'hidden',
+              transition: 'max-height 0.2s ease-out, opacity 0.2s ease-out',
+              paddingLeft: 16,
+            }}
+          >
+            {renderMenuItems(subItems, handleClose, expandedItems, toggleExpand)}
+          </div>
+        </React.Fragment>
+      );
+    }
+
+    return (
+      <MenuItem key={label} onClick={handleClose} sx={{ color: 'inherit' }}>
+        {content}
+      </MenuItem>
+    );
+  });
+
+const TopBarMenu: React.FC<TopBarMenuProps> = ({ label, icon, iconColor, items, showLabel = true }) => {
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null);
+  const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set());
+
+  const handleOpen = (event: React.MouseEvent<HTMLElement>) => {
+    setAnchorEl(event.currentTarget);
+  };
+
+  const handleClose = () => {
+    setAnchorEl(null);
+    setExpandedItems(new Set());
+  };
+
+  const toggleExpand = (label: string) => {
+    setExpandedItems(prev => {
+      const newSet = new Set(prev);
+      if (newSet.has(label)) {
+        newSet.delete(label);
+      } else {
+        newSet.add(label);
+      }
+      return newSet;
+    });
+  };
+
+  return (
+    <>
+      <Typography
+        onClick={handleOpen}
+        sx={{
+          cursor: 'pointer',
+          px: 1,
+          display: 'inline-flex',
+          alignItems: 'center',
+          color: 'inherit',
+        }}
+      >
+        {icon && (
+          <Icon
+            name={typeof icon === 'string' ? icon : 'info'}
+            iconColor={iconColor || 'currentColor'}
+            style={{ marginRight: showLabel ? 2 : 0, fontSize: 20, position: 'relative', top: -1 }}
+          />
+        )}
+        {showLabel && <span>{label}</span>}
+      </Typography>
+      <Menu anchorEl={anchorEl} open={Boolean(anchorEl)} onClose={handleClose} sx={{ color: 'inherit' }}>
+        {items && renderMenuItems(items, handleClose, expandedItems, toggleExpand)}
+      </Menu>
+    </>
+  );
+};
+
+export default TopBarMenu;

package/src/gui/Layouts/ResponsiveUI/TopBar/components/TopBarMenu/TopBarMenu.types.ts

@@ -0,0 +1,44 @@
+import type { ReactNode } from 'react';
+
+export type TopBarMenuProps = {
+  label: string;
+  icon?: ReactNode;
+  iconColor?: string;
+  /** Whether to display the label next to the icon in the top-level menu trigger. Defaults to true. */
+  showLabel?: boolean;
+  items?: TopBarMenuItemProps[];
+};
+
+export type TopBarMenuItemProps = {
+  label: string;
+  href: string;
+  icon?: ReactNode;
+  iconColor?: string;
+  external?: boolean;
+  items?: TopBarMenuItemProps[]; 
+};
+
+// Note: The items property in TopBarMenuItemProps is added to support nested menu items if needed.
+// This allows for multi-level dropdown menus in the TopBarMenu component.
+// The iconColor property allows customization of each menu item’s icon color.
+
+// Example usage:
+// const menu: TopBarMenuProps = {
+//   label: 'Menu',
+//   icon: <MenuIcon />,
+//   items: [
+//     { label: 'Item 1', href: '/item1', icon: <Item1Icon /> },
+//     { label: 'Item 2', href: '/item2', icon: <Item2Icon />, items: [ // Nested items
+//       { label: 'Subitem 1', href: '/item2/subitem1' },
+//       { label: 'Subitem 2', href: '/item2/subitem2' },
+//     ] },
+//   ],
+// };   
+// The above example shows how to define a menu with nested items using the updated types.
+// The items property in TopBarMenuProps is optional, allowing for menus without dropdowns.
+
+
+export type TopBarMenuItemResolverSpec = {
+  type: 'TopBarMenuItem';
+  props?: TopBarMenuItemProps;
+};