@mounaji_npm/saas-template 0.1.0

package/src/registry/ModuleRegistry.jsx

@@ -0,0 +1,131 @@
+/**
+ * ModuleRegistry — @mounaji/saas-template
+ *
+ * Central registry for navigation modules. Each page in the app registers
+ * a manifest here; the Sidebar reads the registry to build its nav tree.
+ *
+ * Two usage patterns:
+ *
+ * ── Static (recommended for most apps) ─────────────────────────────────────
+ *   Pass modules directly to AppShell:
+ *   <AppShell modules={[DASHBOARD_MODULE, CHAT_MODULE, MY_CUSTOM_MODULE]}>
+ *     {children}
+ *   </AppShell>
+ *
+ * ── Dynamic (for plugin-style architectures) ───────────────────────────────
+ *   Call useRegisterModule() at the top of a page component:
+ *   function MyPage() {
+ *     useRegisterModule(MY_MODULE);
+ *     return <div>...</div>;
+ *   }
+ *
+ * ── Module Manifest Shape ────────────────────────────────────────────────────
+ *   {
+ *     id:        string       — unique identifier (e.g. 'dashboard')
+ *     label:     string       — display name in sidebar
+ *     icon:      ReactNode    — icon element or render function
+ *     path:      string       — href for Link (e.g. '/dashboard')
+ *     section:   string|null  — sidebar section group label (null = top section)
+ *     order:     number       — sort order within section (lower = higher)
+ *     children:  Manifest[]   — optional sub-nav items
+ *     badge:     string|null  — badge text shown next to label (e.g. 'Beta')
+ *     disabled:  boolean      — grayed out, not clickable
+ *     hidden:    boolean      — completely omit from nav (useful for role-based hiding)
+ *     external:  boolean      — open in new tab
+ *   }
+ */
+
+import { createContext, useContext, useState, useCallback, useEffect, useMemo } from 'react';
+
+const RegistryContext = createContext({
+  modules: [],
+  register: () => {},
+  unregister: () => {},
+});
+
+export function ModuleRegistryProvider({ children, initialModules = [] }) {
+  const [dynamic, setDynamic] = useState([]);
+
+  const register = useCallback((manifest) => {
+    setDynamic(prev => {
+      const exists = prev.find(m => m.id === manifest.id);
+      if (exists) return prev.map(m => m.id === manifest.id ? manifest : m);
+      return [...prev, manifest];
+    });
+  }, []);
+
+  const unregister = useCallback((id) => {
+    setDynamic(prev => prev.filter(m => m.id !== id));
+  }, []);
+
+  // Merge initial (static) + dynamic modules, deduplicated by id
+  // Dynamic modules override static ones with the same id
+  const modules = useMemo(() => {
+    const map = new Map();
+    [...initialModules, ...dynamic].forEach(m => map.set(m.id, m));
+    return Array.from(map.values());
+  }, [initialModules, dynamic]);
+
+  return (
+    <RegistryContext.Provider value={{ modules, register, unregister }}>
+      {children}
+    </RegistryContext.Provider>
+  );
+}
+
+export function useModuleRegistry() {
+  return useContext(RegistryContext);
+}
+
+/**
+ * Dynamically register a module when a component mounts.
+ * Automatically unregisters when the component unmounts.
+ *
+ * @param {object} manifest
+ * @param {boolean} [enabled=true]  — set false to skip registration (for conditional modules)
+ */
+export function useRegisterModule(manifest, enabled = true) {
+  const { register, unregister } = useModuleRegistry();
+
+  useEffect(() => {
+    if (!enabled || !manifest?.id) return;
+    register(manifest);
+    return () => unregister(manifest.id);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [manifest?.id, enabled]);
+}
+
+/**
+ * Returns the nav tree sorted into sections, ready for Sidebar rendering.
+ *
+ * @returns {{ label: string|null, items: object[] }[]}
+ */
+export function useNavTree() {
+  const { modules } = useModuleRegistry();
+
+  return useMemo(() => {
+    const visible = modules.filter(m => !m.hidden);
+    const sectionMap = new Map();
+
+    visible.forEach(m => {
+      const key = m.section ?? '__TOP__';
+      if (!sectionMap.has(key)) sectionMap.set(key, []);
+      sectionMap.get(key).push(m);
+    });
+
+    // Sort items within each section
+    sectionMap.forEach(items => items.sort((a, b) => (a.order ?? 99) - (b.order ?? 99)));
+
+    // Order sections: __TOP__ first, then alphabetical
+    const sections = [];
+    if (sectionMap.has('__TOP__')) {
+      sections.push({ label: null, items: sectionMap.get('__TOP__') });
+    }
+    Array.from(sectionMap.entries())
+      .filter(([k]) => k !== '__TOP__')
+      .sort(([a], [b]) => a.localeCompare(b))
+      .forEach(([label, items]) => sections.push({ label, items }));
+
+    return sections;
+  }, [modules]);
+}

package/src/shell/AppShell.jsx

@@ -0,0 +1,192 @@
+/**
+ * AppShell — @mounaji/saas-template
+ *
+ * Root layout compositor. Wires together:
+ *   TokensProvider  → design tokens injected to :root
+ *   ModuleRegistry  → nav module list available to Sidebar
+ *   Sidebar         → collapsible left nav
+ *   TopNav          → sticky top bar
+ *   <children>      → page content
+ *
+ * ── Minimal usage (React app, e.g. Vite) ───────────────────────────────────
+ *   import { AppShell } from '@mounaji/saas-template';
+ *   import { DASHBOARD_MODULE, CHAT_MODULE } from '@mounaji/saas-template/modules';
+ *
+ *   <AppShell modules={[DASHBOARD_MODULE, CHAT_MODULE]} activePath={location.pathname}>
+ *     <Route path="/dashboard" element={<Dashboard />} />
+ *   </AppShell>
+ *
+ * ── Next.js App Router (app/layout.js) ─────────────────────────────────────
+ *   'use client'; // AppShell is a client component
+ *   import { AppShell } from '@mounaji/saas-template';
+ *   import { DASHBOARD_MODULE, CHAT_MODULE } from '@mounaji/saas-template/modules';
+ *   import { usePathname } from 'next/navigation';
+ *   import Link from 'next/link';
+ *
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html><body>
+ *         <AppShellWrapper>{children}</AppShellWrapper>
+ *       </body></html>
+ *     );
+ *   }
+ *
+ *   function AppShellWrapper({ children }) {
+ *     const pathname = usePathname();
+ *     return (
+ *       <AppShell
+ *         modules={[DASHBOARD_MODULE, CHAT_MODULE]}
+ *         activePath={pathname}
+ *         LinkComponent={Link}   // pass Next.js Link for client-side nav
+ *       >
+ *         {children}
+ *       </AppShell>
+ *     );
+ *   }
+ *
+ * ── Adding a custom page module ─────────────────────────────────────────────
+ *   // my-module.js — export a manifest
+ *   export const MY_MODULE = {
+ *     id: 'analytics',
+ *     label: 'Analytics',
+ *     icon: '📊',         // string emoji, or pass React element/function
+ *     path: '/analytics',
+ *     section: 'Workspace',
+ *     order: 10,
+ *   };
+ *
+ *   // in AppShell modules prop:
+ *   <AppShell modules={[...DEFAULT_MODULES, MY_MODULE]}>
+ *
+ * Props:
+ *   modules         — ModuleManifest[]  (nav items)
+ *   activePath      — string            (current route path)
+ *   onNavigate      — (path) => void    (router push — omit to use href links)
+ *   LinkComponent   — React component   (default: 'a'. Pass Next.js Link, React Router Link, etc.)
+ *   logo            — React node        (sidebar brand logo)
+ *   bottomModules   — ModuleManifest[]  (bottom nav items: Settings, Help)
+ *   org             — { name, logo? }
+ *   project         — { name }
+ *   onOrgClick      — () => void
+ *   onProjectClick  — () => void
+ *   onNewProject    — () => void
+ *   user            — { name, avatar?, email? }
+ *   onLogout        — () => void
+ *   isDark          — boolean (for theme toggle display)
+ *   onThemeToggle   — () => void
+ *   topNavLeft      — React node (override breadcrumb)
+ *   topNavCenter    — React node
+ *   topNavRight     — React node (appended to right side)
+ *   tokens          — Partial<DEFAULT_TOKENS>
+ *   tokenPersist    — boolean (persist tokens to localStorage, default: true)
+ *   tokenStorageKey — string (default: 'mn_design_tokens')
+ *   children        — React node (page content)
+ */
+
+import { useState } from 'react';
+import { TokensProvider } from '@mounaji_npm/tokens';
+import { ModuleRegistryProvider } from '../registry/ModuleRegistry.jsx';
+import { Sidebar } from './Sidebar.jsx';
+import { TopNav } from './TopNav.jsx';
+
+const SIDEBAR_EXPANDED = 220;
+const SIDEBAR_COLLAPSED = 60;
+
+export function AppShell({
+  // Nav
+  modules = [],
+  bottomModules = DEFAULT_BOTTOM_MODULES,
+  activePath = '/',
+  onNavigate,
+  LinkComponent = 'a',
+  logo,
+
+  // TopNav
+  org,
+  project,
+  onOrgClick,
+  onProjectClick,
+  onNewProject,
+  user,
+  onLogout,
+  isDark = true,
+  onThemeToggle,
+  topNavLeft,
+  topNavCenter,
+  topNavRight,
+
+  // Tokens
+  tokens,
+  tokenPersist = true,
+  tokenStorageKey = 'mn_design_tokens',
+
+  // Content
+  children,
+}) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  const sidebarWidth = collapsed ? SIDEBAR_COLLAPSED : SIDEBAR_EXPANDED;
+
+  return (
+    <TokensProvider
+      initialTokens={tokens}
+      persist={tokenPersist}
+      storageKey={tokenStorageKey}
+    >
+      <ModuleRegistryProvider initialModules={modules}>
+        <div style={{ display: 'flex', minHeight: '100vh', backgroundColor: 'var(--mn-color-bg-dark, #060919)' }}>
+
+          {/* Sidebar */}
+          <Sidebar
+            logo={logo}
+            bottomItems={bottomModules}
+            collapsed={collapsed}
+            onCollapse={setCollapsed}
+            activePath={activePath}
+            onNavigate={onNavigate}
+            LinkComponent={LinkComponent}
+          />
+
+          {/* Main area — offset by sidebar width */}
+          <div style={{
+            flex: 1,
+            marginLeft: sidebarWidth,
+            transition: `margin-left 340ms cubic-bezier(0.16,1,0.3,1)`,
+            display: 'flex',
+            flexDirection: 'column',
+            minWidth: 0,
+          }}>
+            {/* Top Nav */}
+            <TopNav
+              org={org}
+              project={project}
+              onOrgClick={onOrgClick}
+              onProjectClick={onProjectClick}
+              onNewProject={onNewProject}
+              user={user}
+              onLogout={onLogout}
+              isDark={isDark}
+              onThemeToggle={onThemeToggle}
+              leftSlot={topNavLeft}
+              centerSlot={topNavCenter}
+              rightSlot={topNavRight}
+            />
+
+            {/* Page content */}
+            <main style={{ flex: 1, minHeight: 0 }}>
+              {children}
+            </main>
+          </div>
+
+        </div>
+      </ModuleRegistryProvider>
+    </TokensProvider>
+  );
+}
+
+// ─── Default bottom modules ───────────────────────────────────────────────────
+
+export const DEFAULT_BOTTOM_MODULES = [
+  { id: 'settings', label: 'Settings', icon: '⚙', path: '/settings', order: 1 },
+  { id: 'help',     label: 'Help',     icon: '?',  path: '/help',     order: 2 },
+];

package/src/shell/Sidebar.jsx

@@ -0,0 +1,357 @@
+/**
+ * Sidebar — @mounaji/saas-template
+ *
+ * Collapsible sidebar that renders nav sections from ModuleRegistry.
+ * All styles are token-driven via CSS variables.
+ *
+ * Props:
+ *   logo          — React node (brand logo/name)
+ *   bottomItems   — Manifest[] (always-visible bottom nav items like Settings, Help)
+ *   collapsed     — boolean (controlled)
+ *   onCollapse    — (collapsed: boolean) => void
+ *   activePath    — string (current pathname — compare to module.path)
+ *   onNavigate    — (path: string) => void (call router.push internally)
+ *   LinkComponent — React component for links (default: <a>; pass Next.js <Link>)
+ *   tokens        — Partial<DEFAULT_TOKENS>
+ */
+
+import { useState, useCallback } from 'react';
+import { useNavTree } from '../registry/ModuleRegistry.jsx';
+import { TOKEN_CSS_MAP } from '@mounaji_npm/tokens';
+
+function buildInlineTokens(tokens) {
+  if (!tokens) return {};
+  const s = {};
+  Object.entries(tokens).forEach(([k, v]) => { const c = TOKEN_CSS_MAP[k]; if (c) s[c] = v; });
+  return s;
+}
+
+const SIDEBAR_EXPANDED_WIDTH = 220;
+const SIDEBAR_COLLAPSED_WIDTH = 60;
+
+export function Sidebar({
+  logo,
+  bottomItems = [],
+  collapsed = false,
+  onCollapse,
+  activePath = '/',
+  onNavigate,
+  LinkComponent = 'a',
+  tokens,
+  style,
+}) {
+  const sections = useNavTree();
+  const [expandedIds, setExpandedIds] = useState(new Set());
+
+  const toggleExpand = useCallback((id) => {
+    setExpandedIds(prev => {
+      const next = new Set(prev);
+      next.has(id) ? next.delete(id) : next.add(id);
+      return next;
+    });
+  }, []);
+
+  function isActive(path) {
+    if (path === '/') return activePath === '/';
+    return activePath === path || activePath.startsWith(path + '/');
+  }
+
+  const width = collapsed ? SIDEBAR_COLLAPSED_WIDTH : SIDEBAR_EXPANDED_WIDTH;
+
+  return (
+    <aside
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        bottom: 0,
+        width,
+        display: 'flex',
+        flexDirection: 'column',
+        backgroundColor: 'var(--mn-color-nav-dark, #07091C)',
+        borderRight: '1px solid var(--mn-border-dark, rgba(255,255,255,0.07))',
+        transition: `width 340ms cubic-bezier(0.16,1,0.3,1)`,
+        overflow: 'hidden',
+        zIndex: 40,
+        fontFamily: 'var(--mn-font-family, inherit)',
+        ...buildInlineTokens(tokens),
+        ...style,
+      }}
+    >
+      {/* Brand / Logo */}
+      <div style={{
+        height: 56,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: collapsed ? 'center' : 'space-between',
+        padding: collapsed ? '0' : '0 12px 0 16px',
+        borderBottom: '1px solid var(--mn-border-dark, rgba(255,255,255,0.07))',
+        flexShrink: 0,
+        gap: 8,
+      }}>
+        {!collapsed && (
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8, minWidth: 0, overflow: 'hidden' }}>
+            {logo ?? <DefaultLogo />}
+          </div>
+        )}
+
+        <CollapseButton collapsed={collapsed} onCollapse={() => onCollapse?.(!collapsed)} />
+      </div>
+
+      {/* Nav sections — scrollable */}
+      <nav style={{ flex: 1, overflowY: 'auto', overflowX: 'hidden', padding: '8px 0' }}>
+        {sections.map(section => (
+          <SidebarSection
+            key={section.label ?? '__top__'}
+            section={section}
+            collapsed={collapsed}
+            isActive={isActive}
+            expandedIds={expandedIds}
+            onToggle={toggleExpand}
+            onNavigate={onNavigate}
+            LinkComponent={LinkComponent}
+          />
+        ))}
+      </nav>
+
+      {/* Bottom items (Settings, Help, etc.) */}
+      {bottomItems.length > 0 && (
+        <div style={{
+          borderTop: '1px solid var(--mn-border-dark, rgba(255,255,255,0.07))',
+          padding: '8px 0',
+          flexShrink: 0,
+        }}>
+          {bottomItems.map(item => (
+            <NavItem
+              key={item.id}
+              item={item}
+              collapsed={collapsed}
+              active={isActive(item.path)}
+              onNavigate={onNavigate}
+              LinkComponent={LinkComponent}
+            />
+          ))}
+        </div>
+      )}
+    </aside>
+  );
+}
+
+// ─── Section ──────────────────────────────────────────────────────────────────
+
+function SidebarSection({ section, collapsed, isActive, expandedIds, onToggle, onNavigate, LinkComponent }) {
+  return (
+    <div style={{ marginBottom: 4 }}>
+      {/* Section label */}
+      {section.label && !collapsed && (
+        <p style={{
+          padding: '8px 16px 4px',
+          fontSize: 10,
+          fontWeight: 600,
+          letterSpacing: '0.08em',
+          textTransform: 'uppercase',
+          color: 'var(--mn-text-muted-dark, #64748B)',
+          margin: 0,
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+        }}>
+          {section.label}
+        </p>
+      )}
+      {section.label && collapsed && <div style={{ height: 8 }} />}
+
+      {section.items.map(item => (
+        <NavItem
+          key={item.id}
+          item={item}
+          collapsed={collapsed}
+          active={isActive(item.path)}
+          expanded={expandedIds.has(item.id)}
+          onToggle={() => item.children?.length && onToggle(item.id)}
+          onNavigate={onNavigate}
+          LinkComponent={LinkComponent}
+          isActive={isActive}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ─── NavItem ──────────────────────────────────────────────────────────────────
+
+function NavItem({ item, collapsed, active, expanded, onToggle, onNavigate, LinkComponent, isActive }) {
+  const hasChildren = item.children?.length > 0;
+  const isDisabled = Boolean(item.disabled);
+
+  const itemStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: collapsed ? 'center' : 'flex-start',
+    gap: collapsed ? 0 : 10,
+    width: '100%',
+    padding: collapsed ? '0' : '0 12px',
+    margin: '1px 6px',
+    width: 'calc(100% - 12px)',
+    height: 36,
+    borderRadius: 'var(--mn-radius-lg, 0.75rem)',
+    fontSize: 'var(--mn-font-size-sm, 0.875rem)',
+    fontWeight: 500,
+    cursor: isDisabled ? 'not-allowed' : 'pointer',
+    opacity: isDisabled ? 0.4 : 1,
+    textDecoration: 'none',
+    border: 'none',
+    outline: 'none',
+    transition: 'background-color 150ms, color 150ms',
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    fontFamily: 'var(--mn-font-family, inherit)',
+    ...(active
+      ? {
+          backgroundColor: 'rgba(255,255,255,0.08)',
+          color: 'var(--mn-text-primary-dark, #F0F4FF)',
+        }
+      : {
+          backgroundColor: 'transparent',
+          color: 'var(--mn-text-secondary-dark, #94A3B8)',
+        }),
+  };
+
+  const content = (
+    <>
+      {/* Icon */}
+      <IconWrapper icon={item.icon} active={active} />
+
+      {/* Label (hidden when collapsed) */}
+      {!collapsed && (
+        <>
+          <span style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' }}>
+            {item.label}
+          </span>
+
+          {item.badge && (
+            <span style={{
+              fontSize: 10, fontWeight: 600,
+              padding: '1px 6px',
+              borderRadius: 'var(--mn-radius-full, 9999px)',
+              backgroundColor: 'rgba(99,102,241,0.2)',
+              color: 'var(--mn-color-accent, #8B5CF6)',
+              flexShrink: 0,
+            }}>
+              {item.badge}
+            </span>
+          )}
+
+          {hasChildren && (
+            <span style={{
+              fontSize: 10,
+              color: 'var(--mn-text-muted-dark, #64748B)',
+              flexShrink: 0,
+              transform: expanded ? 'rotate(180deg)' : 'none',
+              transition: 'transform 200ms',
+            }}>▾</span>
+          )}
+        </>
+      )}
+    </>
+  );
+
+  const handleClick = (e) => {
+    if (isDisabled) { e.preventDefault(); return; }
+    if (hasChildren) { e.preventDefault(); onToggle?.(); return; }
+    if (item.external) return; // let native link handle it
+    if (onNavigate) { e.preventDefault(); onNavigate(item.path); }
+  };
+
+  const linkProps = {
+    href: item.path,
+    onClick: handleClick,
+    style: itemStyle,
+    ...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {}),
+    title: collapsed ? item.label : undefined,
+  };
+
+  return (
+    <>
+      {hasChildren
+        ? <button style={{ ...itemStyle, background: active ? 'rgba(255,255,255,0.08)' : 'transparent', width: 'calc(100% - 12px)', margin: '1px 6px' }} onClick={handleClick}>{content}</button>
+        : <LinkComponent {...linkProps}>{content}</LinkComponent>
+      }
+
+      {/* Children */}
+      {hasChildren && expanded && !collapsed && (
+        <div style={{ paddingLeft: 16, marginBottom: 4 }}>
+          {item.children.map(child => (
+            <NavItem
+              key={child.id ?? child.path}
+              item={{ id: child.id ?? child.path, ...child }}
+              collapsed={false}
+              active={isActive ? isActive(child.path) : false}
+              onNavigate={onNavigate}
+              LinkComponent={LinkComponent}
+            />
+          ))}
+        </div>
+      )}
+    </>
+  );
+}
+
+// ─── Icon Wrapper ─────────────────────────────────────────────────────────────
+
+function IconWrapper({ icon, active }) {
+  const style = {
+    width: 16,
+    height: 16,
+    flexShrink: 0,
+    color: active ? 'var(--mn-color-primary, #3B82F6)' : 'inherit',
+  };
+
+  if (!icon) return <span style={{ width: 16 }} />;
+  if (typeof icon === 'string') return <span style={{ fontSize: 14, width: 16, textAlign: 'center' }}>{icon}</span>;
+  if (typeof icon === 'function') return icon({ style });
+
+  // React element
+  return <span style={style}>{icon}</span>;
+}
+
+// ─── Collapse Button ──────────────────────────────────────────────────────────
+
+function CollapseButton({ collapsed, onCollapse }) {
+  return (
+    <button
+      onClick={onCollapse}
+      aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+      style={{
+        width: 28,
+        height: 28,
+        borderRadius: 'var(--mn-radius-md, 0.5rem)',
+        background: 'rgba(255,255,255,0.04)',
+        border: '1px solid var(--mn-border-dark, rgba(255,255,255,0.07))',
+        cursor: 'pointer',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        color: 'var(--mn-text-muted-dark, #64748B)',
+        fontSize: 12,
+        flexShrink: 0,
+        transition: 'background-color 150ms',
+      }}
+    >
+      {collapsed ? '›' : '‹'}
+    </button>
+  );
+}
+
+function DefaultLogo() {
+  return (
+    <div style={{
+      width: 24, height: 24,
+      borderRadius: 6,
+      background: 'var(--mn-color-primary, #3B82F6)',
+      display: 'flex', alignItems: 'center', justifyContent: 'center',
+      fontSize: 11, fontWeight: 800, color: '#fff',
+    }}>
+      M
+    </div>
+  );
+}