@apptimate/core-lib 1.0.0 → 1.1.0

package/src/constants/menus.ts

@@ -0,0 +1,975 @@
+export interface SubMenuItem {
+  id: string;
+  label: string;
+  path: string;
+}
+
+export interface SubMenuGroup {
+  id: string;
+  label: string;
+  items: SubMenuItem[];
+}
+
+export interface MainMenuItem {
+  id: string;
+  label: string;
+  iconName: string;
+  groups: SubMenuGroup[];
+}
+
+/**
+ * A secondary item in a saved menu config.
+ * Can be a plain registry key (backward compat) or an enriched object
+ * with optional label/group overrides.
+ */
+export type SecondaryItemConfig = string | {
+  key: string;
+  /** Override the default label from the registry */
+  label?: string;
+  /** Override the default group from the registry */
+  group?: string;
+};
+
+/** Normalize a SecondaryItemConfig to its key string. */
+export function secondaryItemKey(item: SecondaryItemConfig): string {
+  return typeof item === 'string' ? item : item.key;
+}
+
+/** Normalize a SecondaryItemConfig to the enriched shape. */
+export function normalizeSecondaryItem(item: SecondaryItemConfig): { key: string; label?: string; group?: string } {
+  return typeof item === 'string' ? { key: item } : item;
+}
+
+// ─── MASTER REGISTRY ─────────────────────────────────────────────
+// Every possible secondary menu item across all modules.
+// These are the building blocks that can be assembled into custom menus.
+
+export interface RegistryItem {
+  /** Unique key used for selection, e.g. "core__users" */
+  key: string;
+  /** Human-readable label */
+  label: string;
+  /** URL path */
+  path: string;
+  /** Which module this belongs to */
+  module: string;
+  /** Default group label when added to a menu */
+  defaultGroup: string;
+}
+
+export const MENU_ITEM_REGISTRY: RegistryItem[] = [
+  // ── Core Module ──
+  { key: 'core__users', label: 'Users', path: '/users', module: 'Core', defaultGroup: 'User Management' },
+  { key: 'core__roles', label: 'Roles', path: '/roles', module: 'Core', defaultGroup: 'User Management' },
+  { key: 'core__organizations', label: 'Organizations', path: '/organizations', module: 'Core', defaultGroup: 'User Management' },
+  { key: 'core__design_system', label: 'Design System', path: '/design-system', module: 'Core', defaultGroup: 'Temporary' },
+  { key: 'core__activity_logs', label: 'Activity Logs', path: '/activity-logs', module: 'Core', defaultGroup: 'System Auditing' },
+  { key: 'core__api_requests', label: 'API Requests', path: '/system/api-requests', module: 'Core', defaultGroup: 'System Auditing' },
+  { key: 'core__feature_access_logs', label: 'Feature Access Logs', path: '/system/feature-access-logs', module: 'Core', defaultGroup: 'System Auditing' },
+  { key: 'core__issue_logs', label: 'Issue Logs', path: '/system/issue-logs', module: 'Core', defaultGroup: 'System Auditing' },
+  { key: 'core__feature_registry', label: 'Feature Registry', path: '/system/features', module: 'Core', defaultGroup: 'System Auditing' },
+  { key: 'core__menu_config', label: 'Menu Configuration', path: '/menu-config', module: 'Core', defaultGroup: 'System' },
+
+  // ── Inventory Module ──
+  { key: 'inv__items', label: 'Items', path: '/inventory/items', module: 'Inventory', defaultGroup: 'Catalog' },
+  { key: 'inv__categories', label: 'Categories', path: '/inventory/categories', module: 'Inventory', defaultGroup: 'Catalog' },
+  { key: 'inv__units', label: 'Units', path: '/inventory/units', module: 'Inventory', defaultGroup: 'Catalog' },
+  { key: 'inv__supplier_items', label: 'Supplier Items', path: '/inventory/supplier-items', module: 'Inventory', defaultGroup: 'Catalog' },
+  { key: 'inv__documents', label: 'Stock Documents', path: '/inventory/documents', module: 'Inventory', defaultGroup: 'Stock Control' },
+  { key: 'inv__warehouses', label: 'Warehouses', path: '/inventory/warehouses', module: 'Inventory', defaultGroup: 'Stock Control' },
+  { key: 'inv__lots', label: 'Lots & Serials', path: '/inventory/lots', module: 'Inventory', defaultGroup: 'Stock Control' },
+  { key: 'inv__stock_counts', label: 'Stock Counts', path: '/inventory/stock-counts', module: 'Inventory', defaultGroup: 'Stock Control' },
+  { key: 'inv__reservations', label: 'Reservations', path: '/inventory/reservations', module: 'Inventory', defaultGroup: 'Stock Control' },
+  { key: 'inv__inspection', label: 'Inspection', path: '/inventory/inspection', module: 'Inventory', defaultGroup: 'Quality & Alerts' },
+  { key: 'inv__alerts', label: 'Stock Alerts', path: '/inventory/alerts', module: 'Inventory', defaultGroup: 'Quality & Alerts' },
+  { key: 'inv__opening_balances', label: 'Opening Balances', path: '/inventory/opening-balances', module: 'Inventory', defaultGroup: 'Operations' },
+  { key: 'inv__transfer_requests', label: 'Transfer Requests', path: '/inventory/transfer-requests', module: 'Inventory', defaultGroup: 'Transfers' },
+  { key: 'inv__transfer_orders', label: 'Transfer Orders', path: '/inventory/transfer-orders', module: 'Inventory', defaultGroup: 'Transfers' },
+  { key: 'inv__consignment', label: 'Consignment', path: '/inventory/consignment', module: 'Inventory', defaultGroup: 'Operations' },
+  { key: 'inv__write_offs', label: 'Write-Offs', path: '/inventory/write-offs', module: 'Inventory', defaultGroup: 'Operations' },
+  { key: 'inv__dashboard', label: 'Dashboard', path: '/inventory/dashboard', module: 'Inventory', defaultGroup: 'Reports' },
+  { key: 'inv__balances', label: 'Stock Balances', path: '/inventory/balances', module: 'Inventory', defaultGroup: 'Reports' },
+  { key: 'inv__reports', label: 'All Reports', path: '/inventory/reports', module: 'Inventory', defaultGroup: 'Reports' },
+
+  // ── Sales Module: POS channel (current implementation) ──
+  { key: 'pos__dashboard', label: 'POS Dashboard', path: '/pos', module: 'Sales', defaultGroup: 'POS Overview' },
+  { key: 'pos__sell', label: 'Sell Screen', path: '/pos/sell', module: 'Sales', defaultGroup: 'POS Overview' },
+  { key: 'pos__quick_sell', label: 'Quick Sell', path: '/pos/quick-sell', module: 'Sales', defaultGroup: 'POS Overview' },
+  { key: 'pos__terminals', label: 'Terminals', path: '/pos/terminals', module: 'Sales', defaultGroup: 'POS Configuration' },
+  { key: 'pos__sessions', label: 'Sessions', path: '/pos/sessions', module: 'Sales', defaultGroup: 'POS Operations' },
+  { key: 'pos__invoices', label: 'Invoices', path: '/pos/invoices', module: 'Sales', defaultGroup: 'POS Transactions' },
+  { key: 'pos__returns', label: 'Returns', path: '/pos/returns', module: 'Sales', defaultGroup: 'POS Transactions' },
+  { key: 'pos__reports', label: 'Sales Reports', path: '/pos/reports', module: 'Sales', defaultGroup: 'POS Reports' },
+
+  // ── Finance Module ──
+  { key: 'fin__dashboard', label: 'Dashboard', path: '/finance', module: 'Finance', defaultGroup: 'Overview' },
+  { key: 'fin__settings', label: 'Settings', path: '/finance/settings', module: 'Finance', defaultGroup: 'Setup' },
+  { key: 'fin__chart_of_accounts', label: 'Chart of Accounts', path: '/finance/accounts', module: 'Finance', defaultGroup: 'General Ledger' },
+  { key: 'fin__fiscal_periods', label: 'Fiscal Periods', path: '/finance/fiscal-periods', module: 'Finance', defaultGroup: 'General Ledger' },
+  { key: 'fin__journal_entries', label: 'Journal Entries', path: '/finance/journals', module: 'Finance', defaultGroup: 'General Ledger' },
+  { key: 'fin__gl_transactions', label: 'GL Transactions', path: '/finance/gl-transactions', module: 'Finance', defaultGroup: 'General Ledger' },
+  { key: 'fin__receipts', label: 'Receipts', path: '/finance/receipts', module: 'Finance', defaultGroup: 'Receivables' },
+  { key: 'fin__customers', label: 'Customers (AR)', path: '/finance/customers', module: 'Finance', defaultGroup: 'Receivables' },
+  { key: 'fin__payments', label: 'Payments', path: '/finance/payments', module: 'Finance', defaultGroup: 'Payables' },
+  { key: 'fin__vendors', label: 'Vendors (AP)', path: '/finance/vendors', module: 'Finance', defaultGroup: 'Payables' },
+  { key: 'fin__bank_accounts', label: 'Bank Accounts', path: '/finance/bank/accounts', module: 'Finance', defaultGroup: 'Banking' },
+  { key: 'fin__bank_transactions', label: 'Bank Transactions', path: '/finance/bank/transactions', module: 'Finance', defaultGroup: 'Banking' },
+  { key: 'fin__bank_reconciliation', label: 'Bank Reconciliation', path: '/finance/bank/reconciliation', module: 'Finance', defaultGroup: 'Banking' },
+  { key: 'fin__cheques', label: 'Cheque Management', path: '/finance/cheques', module: 'Finance', defaultGroup: 'Banking' },
+  { key: 'fin__expense_income', label: 'Expense / Income', path: '/finance/expense-income', module: 'Finance', defaultGroup: 'Expense & Income' },
+  { key: 'fin__tax_codes', label: 'Tax Codes', path: '/finance/tax/codes', module: 'Finance', defaultGroup: 'Tax' },
+  { key: 'fin__tax_returns', label: 'Tax Returns', path: '/finance/tax/returns', module: 'Finance', defaultGroup: 'Tax' },
+  { key: 'fin__events', label: 'Accounting Events', path: '/finance/events', module: 'Finance', defaultGroup: 'System' },
+  { key: 'fin__reports', label: 'Reports', path: '/finance/reports', module: 'Finance', defaultGroup: 'Reports' },
+  { key: 'fin__assets', label: 'Fixed Assets', path: '/finance/assets', module: 'Finance', defaultGroup: 'Assets' },
+  { key: 'fin__budgets', label: 'Budgets', path: '/finance/budgets', module: 'Finance', defaultGroup: 'Budgets' },
+  { key: 'fin__period_close', label: 'Period Close', path: '/finance/period-close', module: 'Finance', defaultGroup: 'System' },
+
+  // ── Sales Module (umbrella / back-office) ──
+  { key: 'sales__orders', label: 'Sales Orders', path: '/sales/orders', module: 'Sales', defaultGroup: 'Orders' },
+  { key: 'sales__invoices', label: 'Sales Invoices', path: '/sales/invoices', module: 'Sales', defaultGroup: 'Billing' },
+  { key: 'sales__customers', label: 'Customers', path: '/sales/customers', module: 'Sales', defaultGroup: 'Customers' },
+  { key: 'sales__quotations', label: 'Quotations', path: '/sales/quotations', module: 'Sales', defaultGroup: 'Pre-Sales' },
+  { key: 'sales__pos', label: 'POS Workspace', path: '/pos', module: 'Sales', defaultGroup: 'Channels' },
+  { key: 'sales__returns', label: 'Returns', path: '/sales/returns', module: 'Sales', defaultGroup: 'Returns' },
+  { key: 'sales__reports', label: 'Sales Reports', path: '/sales/reports', module: 'Sales', defaultGroup: 'Reports' },
+
+  // ── Procurement Module ──
+  { key: 'purch__dashboard', label: 'Dashboard', path: '/procurement', module: 'Procurement', defaultGroup: 'Overview' },
+  { key: 'purch__suppliers', label: 'Suppliers', path: '/procurement/suppliers', module: 'Procurement', defaultGroup: 'Suppliers' },
+  { key: 'purch__requisitions', label: 'Requisitions', path: '/procurement/requisitions', module: 'Procurement', defaultGroup: 'Purchasing' },
+  { key: 'purch__orders', label: 'Purchase Orders', path: '/procurement/purchase-orders', module: 'Procurement', defaultGroup: 'Purchasing' },
+  { key: 'purch__grn', label: 'Goods Receipts (GRN)', path: '/procurement/grns', module: 'Procurement', defaultGroup: 'Receiving' },
+  { key: 'purch__returns', label: 'Purchase Returns', path: '/procurement/returns', module: 'Procurement', defaultGroup: 'Receiving' },
+  { key: 'purch__invoices', label: 'Supplier Invoices', path: '/procurement/invoices', module: 'Procurement', defaultGroup: 'Invoicing' },
+  { key: 'purch__consignment', label: 'Consignment', path: '/procurement/consignment', module: 'Procurement', defaultGroup: 'Consignment' },
+  { key: 'purch__settlements', label: 'Settlements', path: '/procurement/consignment/settlements', module: 'Procurement', defaultGroup: 'Consignment' },
+
+  // ── Manufacturing Module (future) ──
+  { key: 'mfg__bom', label: 'Bill of Materials', path: '/manufacturing/bom', module: 'Manufacturing', defaultGroup: 'Engineering' },
+  { key: 'mfg__work_orders', label: 'Work Orders', path: '/manufacturing/work-orders', module: 'Manufacturing', defaultGroup: 'Production' },
+  { key: 'mfg__routing', label: 'Routing', path: '/manufacturing/routing', module: 'Manufacturing', defaultGroup: 'Engineering' },
+  { key: 'mfg__reports', label: 'Production Reports', path: '/manufacturing/reports', module: 'Manufacturing', defaultGroup: 'Reports' },
+
+  // ── HR Module (future) ──
+  { key: 'hr__employees', label: 'Employees', path: '/hr/employees', module: 'HR', defaultGroup: 'Workforce' },
+  { key: 'hr__attendance', label: 'Attendance', path: '/hr/attendance', module: 'HR', defaultGroup: 'Workforce' },
+  { key: 'hr__payroll', label: 'Payroll', path: '/hr/payroll', module: 'HR', defaultGroup: 'Compensation' },
+  { key: 'hr__leave', label: 'Leave Management', path: '/hr/leave', module: 'HR', defaultGroup: 'Workforce' },
+  { key: 'hr__reports', label: 'HR Reports', path: '/hr/reports', module: 'HR', defaultGroup: 'Reports' },
+
+  // ── Jewelry Module ──
+  { key: 'jwl__dashboard', label: 'Dashboard', path: '/jewelry', module: 'Jewelry', defaultGroup: 'Overview' },
+  { key: 'jwl__metal_rates', label: 'Metal Rates', path: '/jewelry/metal-rates', module: 'Jewelry', defaultGroup: 'Setup' },
+  { key: 'jwl__master_metals', label: 'Metal Types', path: '/jewelry/master/metals', module: 'Jewelry', defaultGroup: 'Setup' },
+  { key: 'jwl__master_purities', label: 'Purity Master', path: '/jewelry/master/purities', module: 'Jewelry', defaultGroup: 'Setup' },
+  { key: 'jwl__items', label: 'Jewelry Items', path: '/jewelry/items', module: 'Jewelry', defaultGroup: 'Catalog' },
+  { key: 'jwl__stones', label: 'Loose Stones', path: '/jewelry/stones', module: 'Jewelry', defaultGroup: 'Catalog' },
+  { key: 'jwl__certifications', label: 'Certifications', path: '/jewelry/certifications', module: 'Jewelry', defaultGroup: 'Catalog' },
+  { key: 'jwl__karigars', label: 'Karigars', path: '/jewelry/karigars', module: 'Jewelry', defaultGroup: 'Operations' },
+  { key: 'jwl__custom_orders', label: 'Custom Orders', path: '/jewelry/custom-orders', module: 'Jewelry', defaultGroup: 'Operations' },
+  { key: 'jwl__repairs', label: 'Repairs', path: '/jewelry/repairs', module: 'Jewelry', defaultGroup: 'Operations' },
+  { key: 'jwl__melting', label: 'Old Gold / Melting', path: '/jewelry/melting', module: 'Jewelry', defaultGroup: 'Operations' },
+  { key: 'jwl__tags', label: 'Tag Printing', path: '/jewelry/tags', module: 'Jewelry', defaultGroup: 'Operations' },
+  { key: 'jwl__refinery', label: 'Refinery Batches', path: '/jewelry/refinery', module: 'Jewelry', defaultGroup: 'Manufacturing' },
+  { key: 'jwl__metal_issues', label: 'Metal Issues', path: '/jewelry/metal-issues', module: 'Jewelry', defaultGroup: 'Manufacturing' },
+  { key: 'jwl__designs', label: 'Design Library', path: '/jewelry/designs', module: 'Jewelry', defaultGroup: 'Manufacturing' },
+  { key: 'jwl__dealers', label: 'Wholesale Dealers', path: '/jewelry/dealers', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__installments', label: 'Installments', path: '/jewelry/installments', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__vouchers', label: 'Gift Vouchers', path: '/jewelry/vouchers', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__reservations', label: 'Reservations', path: '/jewelry/reservations', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__warranties', label: 'Warranties', path: '/jewelry/warranties', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__notifications', label: 'Notifications Queue', path: '/jewelry/notifications', module: 'Jewelry', defaultGroup: 'System' },
+  { key: 'jwl__reports', label: 'Reports', path: '/jewelry/reports', module: 'Jewelry', defaultGroup: 'Reports' },
+  { key: 'jwl__pos_sell', label: 'POS Sell', path: '/jewelry/pos/sell', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__pos_sales', label: 'View Sales', path: '/jewelry/pos/sales', module: 'Jewelry', defaultGroup: 'Sales & Billing' },
+  { key: 'jwl__stone_procurement', label: 'Stone Procurement', path: '/jewelry/stone-procurement', module: 'Jewelry', defaultGroup: 'Procurement' },
+  { key: 'jwl__consignment', label: 'Consignment Stock', path: '/jewelry/consignment', module: 'Jewelry', defaultGroup: 'Procurement' },
+  { key: 'jwl__procurement', label: 'Purchase Orders', path: '/jewelry/procurement', module: 'Jewelry', defaultGroup: 'Procurement' },
+  { key: 'jwl__purchase_pos', label: 'Purchase POS', path: '/jewelry/purchases', module: 'Jewelry', defaultGroup: 'Procurement' },
+  { key: 'jwl__processing', label: 'Inventory Processing', path: '/jewelry/purchases/processing', module: 'Jewelry', defaultGroup: 'Procurement' },
+  { key: 'jwl__purchase_returns', label: 'Purchase Returns', path: '/jewelry/purchases/returns', module: 'Jewelry', defaultGroup: 'Procurement' },
+  { key: 'jwl__repositories', label: 'Metal Repositories', path: '/jewelry/repositories', module: 'Jewelry', defaultGroup: 'Operations' },
+  { key: 'jwl__repository_settings', label: 'Repository Settings', path: '/jewelry/repository-settings', module: 'Jewelry', defaultGroup: 'Setup' },
+
+  // ── AI Intelligence Module ──
+  { key: 'ai__recommendations', label: 'Recommendations', path: '/jewelry/ai/recommendations', module: 'AI', defaultGroup: 'Intelligence' },
+  { key: 'ai__reports', label: 'AI Reports', path: '/jewelry/ai/reports', module: 'AI', defaultGroup: 'Intelligence' },
+  { key: 'ai__anomalies', label: 'Anomalies', path: '/jewelry/ai/anomalies', module: 'AI', defaultGroup: 'Intelligence' },
+  { key: 'ai__predictions', label: 'Predictions', path: '/jewelry/ai/predictions', module: 'AI', defaultGroup: 'Intelligence' },
+  { key: 'ai__usage', label: 'Usage', path: '/jewelry/ai/usage', module: 'AI', defaultGroup: 'Intelligence' },
+];
+
+/**
+ * Get all unique module names from the registry.
+ */
+export function getRegistryModules(): string[] {
+  const modules = new Set(MENU_ITEM_REGISTRY.map(item => item.module));
+  return Array.from(modules);
+}
+
+/**
+ * Get registry items filtered by module.
+ */
+export function getRegistryItemsByModule(module: string): RegistryItem[] {
+  return MENU_ITEM_REGISTRY.filter(item => item.module === module);
+}
+
+/**
+ * Resolve secondary item configs into MainMenuItem groups.
+ * Accepts both plain string keys (legacy) and enriched objects with
+ * optional label / group overrides.
+ */
+export function resolveRegistryKeys(items: SecondaryItemConfig[]): SubMenuGroup[] {
+  const groupMap = new Map<string, SubMenuItem[]>();
+  // Track insertion order of groups
+  const groupOrder: string[] = [];
+
+  for (const raw of items) {
+    const cfg = normalizeSecondaryItem(raw);
+    const reg = MENU_ITEM_REGISTRY.find(r => r.key === cfg.key);
+    if (!reg) continue;
+
+    const groupLabel = cfg.group || reg.defaultGroup;
+
+    if (!groupMap.has(groupLabel)) {
+      groupMap.set(groupLabel, []);
+      groupOrder.push(groupLabel);
+    }
+    groupMap.get(groupLabel)!.push({
+      id: cfg.key,
+      label: cfg.label || reg.label,
+      path: reg.path,
+    });
+  }
+
+  return groupOrder.map(label => ({
+    id: label.toLowerCase().replace(/[^a-z0-9]+/g, '_'),
+    label,
+    items: groupMap.get(label)!,
+  }));
+}
+
+
+// ─── PRESET MENU CONFIGURATIONS ──────────────────────────────────
+// These are the default/example configs for different business types.
+
+export interface MenuPreset {
+  id: string;
+  label: string;
+  description: string;
+  primaryMenus: {
+    id: string;
+    label: string;
+    iconName: string;
+    secondaryItems: string[];   // registry keys
+  }[];
+}
+
+export const MENU_PRESETS: MenuPreset[] = [
+  {
+    id: 'default_full',
+    label: 'Full ERP',
+    description: 'All modules visible — suitable for large enterprises',
+    primaryMenus: [
+      {
+        id: 'core',
+        label: 'Core',
+        iconName: 'Settings',
+        secondaryItems: [
+          'core__users', 'core__roles', 'core__organizations',
+          'core__activity_logs', 'core__api_requests', 'core__feature_access_logs',
+          'core__issue_logs', 'core__feature_registry', 'core__menu_config',
+        ],
+      },
+      {
+        id: 'inventory',
+        label: 'Inventory',
+        iconName: 'Package',
+        secondaryItems: [
+          'inv__items', 'inv__categories', 'inv__units', 'inv__supplier_items',
+          'inv__documents', 'inv__warehouses', 'inv__lots', 'inv__stock_counts', 'inv__reservations',
+          'inv__inspection', 'inv__alerts',
+          'inv__opening_balances',
+          'inv__dashboard', 'inv__balances', 'inv__reports',
+        ],
+      },
+      {
+        id: 'sales',
+        label: 'Sales',
+        iconName: 'ShoppingCart',
+        secondaryItems: [
+          'pos__dashboard', 'pos__sell',
+          'pos__terminals', 'pos__sessions',
+          'pos__invoices', 'pos__returns',
+          'pos__reports',
+        ],
+      },
+      {
+        id: 'finance',
+        label: 'Finance',
+        iconName: 'Landmark',
+        secondaryItems: [
+          'fin__dashboard', 'fin__settings',
+          'fin__chart_of_accounts', 'fin__fiscal_periods', 'fin__journal_entries', 'fin__gl_transactions',
+          'fin__customers', 'fin__vendors',
+          'fin__bank_accounts', 'fin__tax_codes',
+        ],
+      },
+      {
+        id: 'procurement',
+        label: 'Procurement',
+        iconName: 'Truck',
+        secondaryItems: [
+          'purch__dashboard', 'purch__suppliers',
+          'purch__requisitions', 'purch__orders',
+          'purch__grn', 'purch__returns',
+          'purch__invoices',
+          'purch__consignment', 'purch__settlements',
+        ],
+      },
+    ],
+  },
+  {
+    id: 'small_retail',
+    label: 'Small Retail / Jewelry Shop',
+    description: 'Sales, stock, finance — simplified for small retail businesses',
+    primaryMenus: [
+      {
+        id: 'sales',
+        label: 'Sales',
+        iconName: 'ShoppingCart',
+        secondaryItems: [
+          'sales__orders', 'sales__invoices', 'sales__customers',
+          'sales__returns', 'sales__reports',
+          'pos__dashboard', 'pos__sell',
+          'pos__terminals', 'pos__sessions',
+          'pos__invoices', 'pos__returns',
+          'pos__reports',
+        ],
+      },
+      {
+        id: 'stock',
+        label: 'Stock',
+        iconName: 'Package',
+        secondaryItems: [
+          'inv__items', 'inv__categories',
+          'inv__documents', 'inv__warehouses',
+          'inv__alerts', 'inv__balances',
+        ],
+      },
+      {
+        id: 'purchases',
+        label: 'Purchases',
+        iconName: 'Truck',
+        secondaryItems: [
+          'purch__orders', 'purch__grn', 'purch__suppliers', 'purch__reports',
+        ],
+      },
+      {
+        id: 'finance',
+        label: 'Finance',
+        iconName: 'Landmark',
+        secondaryItems: [
+          'fin__chart_of_accounts', 'fin__journal_entries',
+          'fin__invoices', 'fin__payments', 'fin__reports',
+        ],
+      },
+      {
+        id: 'settings',
+        label: 'Settings',
+        iconName: 'Settings',
+        secondaryItems: [
+          'core__users', 'core__roles', 'core__organizations', 'core__menu_config',
+        ],
+      },
+    ],
+  },
+  {
+    id: 'enterprise_mfg',
+    label: 'Enterprise / Manufacturing',
+    description: 'Full modules with procurement, manufacturing, and inventory',
+    primaryMenus: [
+      {
+        id: 'inventory',
+        label: 'Inventory',
+        iconName: 'Warehouse',
+        secondaryItems: [
+          'inv__items', 'inv__categories', 'inv__units', 'inv__supplier_items',
+          'inv__documents', 'inv__warehouses', 'inv__lots', 'inv__stock_counts', 'inv__reservations',
+          'inv__inspection', 'inv__alerts', 'inv__opening_balances',
+          'inv__dashboard', 'inv__balances', 'inv__reports',
+        ],
+      },
+      {
+        id: 'procurement',
+        label: 'Procurement',
+        iconName: 'Truck',
+        secondaryItems: [
+          'purch__requisitions', 'purch__orders', 'purch__grn',
+          'purch__suppliers', 'purch__contracts', 'purch__reports',
+        ],
+      },
+      {
+        id: 'manufacturing',
+        label: 'Manufacturing',
+        iconName: 'Factory',
+        secondaryItems: [
+          'mfg__bom', 'mfg__work_orders', 'mfg__routing', 'mfg__reports',
+        ],
+      },
+      {
+        id: 'finance',
+        label: 'Finance',
+        iconName: 'Landmark',
+        secondaryItems: [
+          'fin__chart_of_accounts', 'fin__journal_entries',
+          'fin__bank_accounts', 'fin__reconciliation',
+          'fin__invoices', 'fin__payments', 'fin__reports',
+        ],
+      },
+      {
+        id: 'hr',
+        label: 'HR',
+        iconName: 'Users',
+        secondaryItems: [
+          'hr__employees', 'hr__attendance', 'hr__payroll', 'hr__leave', 'hr__reports',
+        ],
+      },
+      {
+        id: 'admin',
+        label: 'Admin',
+        iconName: 'Settings',
+        secondaryItems: [
+          'core__users', 'core__roles', 'core__organizations',
+          'core__activity_logs', 'core__menu_config',
+        ],
+      },
+    ],
+  },
+  {
+    id: 'services_company',
+    label: 'Services Company',
+    description: 'HR, finance, and client management for service businesses',
+    primaryMenus: [
+      {
+        id: 'clients',
+        label: 'Clients',
+        iconName: 'Handshake',
+        secondaryItems: [
+          'sales__customers', 'sales__quotations', 'sales__orders',
+          'sales__invoices', 'sales__reports',
+        ],
+      },
+      {
+        id: 'team',
+        label: 'Team',
+        iconName: 'Users',
+        secondaryItems: [
+          'hr__employees', 'hr__attendance', 'hr__leave', 'hr__payroll', 'hr__reports',
+        ],
+      },
+      {
+        id: 'finance',
+        label: 'Finance',
+        iconName: 'Landmark',
+        secondaryItems: [
+          'fin__chart_of_accounts', 'fin__journal_entries',
+          'fin__invoices', 'fin__payments', 'fin__reports',
+        ],
+      },
+      {
+        id: 'settings',
+        label: 'Settings',
+        iconName: 'Settings',
+        secondaryItems: [
+          'core__users', 'core__roles', 'core__organizations', 'core__menu_config',
+        ],
+      },
+    ],
+  },
+  {
+    id: 'jewelry_shop',
+    label: 'Jewelry Shop',
+    description: 'Specialized for jewelry retail with metal rates, stones, karigars, and custom orders',
+    primaryMenus: [
+      {
+        id: 'dashboard',
+        label: 'Dashboard',
+        iconName: 'LayoutDashboard',
+        secondaryItems: [
+          'jwl__dashboard', 'jwl__metal_rates',
+          'jwl__reports', 'jwl__notifications',
+          'ai__recommendations', 'ai__reports', 'ai__anomalies', 'ai__predictions', 'ai__usage',
+        ],
+      },
+      {
+        id: 'catalog',
+        label: 'Catalog',
+        iconName: 'Gem',
+        secondaryItems: [
+          'jwl__items', 'jwl__stones', 'jwl__certifications',
+          'jwl__master_metals', 'jwl__master_purities',
+          'jwl__tags', 'jwl__designs',
+          'inv__categories', 'inv__units',
+        ],
+      },
+      {
+        id: 'sales',
+        label: 'Sales & POS',
+        iconName: 'ShoppingCart',
+        secondaryItems: [
+          'jwl__pos_sell', 'jwl__pos_sales',
+          'jwl__dealers', 'jwl__installments',
+          'jwl__vouchers', 'jwl__reservations',
+          'jwl__warranties', 'jwl__melting',
+        ],
+      },
+      {
+        id: 'orders',
+        label: 'Orders',
+        iconName: 'ClipboardList',
+        secondaryItems: [
+          'jwl__custom_orders', 'jwl__repairs',
+          'jwl__karigars',
+        ],
+      },
+      {
+        id: 'manufacturing',
+        label: 'Manufacturing',
+        iconName: 'Factory',
+        secondaryItems: [
+          'jwl__refinery', 'jwl__metal_issues', 'jwl__repositories',
+        ],
+      },
+      {
+        id: 'procurement',
+        label: 'Procurement',
+        iconName: 'Truck',
+        secondaryItems: [
+          'jwl__purchase_pos', 'jwl__processing', 'jwl__purchase_returns',
+          'jwl__stone_procurement', 'jwl__consignment', 'jwl__procurement',
+          'purch__suppliers', 'purch__orders', 'purch__grn',
+          'purch__consignment', 'purch__settlements',
+        ],
+      },
+      {
+        id: 'stock',
+        label: 'Stock',
+        iconName: 'Package',
+        secondaryItems: [
+          'inv__items', 'inv__documents', 'inv__warehouses', 'inv__lots',
+          'inv__alerts', 'inv__balances', 'inv__reports',
+        ],
+      },
+      {
+        id: 'finance',
+        label: 'Finance',
+        iconName: 'Landmark',
+        secondaryItems: [
+          'fin__chart_of_accounts', 'fin__journal_entries',
+          'fin__customers', 'fin__vendors',
+          'fin__bank_accounts', 'fin__tax_codes',
+        ],
+      },
+      {
+        id: 'settings',
+        label: 'Settings',
+        iconName: 'Settings',
+        secondaryItems: [
+          'core__users', 'core__roles', 'core__organizations', 'core__menu_config',
+          'jwl__repository_settings',
+        ],
+      },
+    ],
+  },
+];
+
+
+// ─── DEFAULT APP MENUS (legacy / fallback) ───────────────────────
+// This is the current static config, used when no custom config exists.
+
+export const APP_MENUS: MainMenuItem[] = [
+  {
+    id: "core",
+    label: "Core",
+    iconName: "Settings", // Translates to Settings icon from lucide-react
+    groups: [
+      {
+        id: "core_users",
+        label: "User Management",
+        items: [
+          { id: "users", label: "Users", path: "/users" },
+          { id: "roles", label: "Roles", path: "/roles" },
+          { id: "organizations", label: "Organizations", path: "/organizations" },
+        ],
+      },
+      {
+        id: "core_system",
+        label: "System",
+        items: [
+          { id: "menu_config", label: "Menu Configuration", path: "/menu-config" },
+        ],
+      },
+      {
+        id: "core_audit",
+        label: "System Auditing",
+        items: [
+          { id: "activity_logs", label: "Activity Logs", path: "/activity-logs" },
+          { id: "api_requests", label: "API Requests", path: "/system/api-requests" },
+          { id: "feature_access_logs", label: "Feature Access Logs", path: "/system/feature-access-logs" },
+          { id: "issue_logs", label: "Issue Logs", path: "/system/issue-logs" },
+          { id: "feature_registry", label: "Feature Registry", path: "/system/features" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "inventory",
+    label: "Inventory",
+    iconName: "Package", // Translates to Package icon from lucide-react
+    groups: [
+      {
+        id: "inv_catalog",
+        label: "Catalog",
+        items: [
+          { id: "items", label: "Items", path: "/inventory/items" },
+          { id: "categories", label: "Categories", path: "/inventory/categories" },
+          { id: "units", label: "Units", path: "/inventory/units" },
+          { id: "supplier_items", label: "Supplier Items", path: "/inventory/supplier-items" },
+        ],
+      },
+      {
+        id: "inv_stock",
+        label: "Stock Control",
+        items: [
+          { id: "documents", label: "Stock Documents", path: "/inventory/documents" },
+          { id: "warehouses", label: "Warehouses", path: "/inventory/warehouses" },
+          { id: "lots", label: "Lots & Serials", path: "/inventory/lots" },
+          { id: "stock_counts", label: "Stock Counts", path: "/inventory/stock-counts" },
+          { id: "reservations", label: "Reservations", path: "/inventory/reservations" },
+        ],
+      },
+      {
+        id: "inv_transfers",
+        label: "Transfers",
+        items: [
+          { id: "transfer_requests", label: "Transfer Requests", path: "/inventory/transfer-requests" },
+          { id: "transfer_orders", label: "Transfer Orders", path: "/inventory/transfer-orders" },
+        ],
+      },
+      {
+        id: "inv_quality",
+        label: "Quality & Alerts",
+        items: [
+          { id: "inspection", label: "Inspection", path: "/inventory/inspection" },
+          { id: "alerts", label: "Stock Alerts", path: "/inventory/alerts" },
+        ],
+      },
+      {
+        id: "inv_operations",
+        label: "Operations",
+        items: [
+          { id: "opening_balances", label: "Opening Balances", path: "/inventory/opening-balances" },
+          { id: "write_offs", label: "Write-Offs", path: "/inventory/write-offs" },
+          { id: "consignment", label: "Consignment", path: "/inventory/consignment" },
+        ],
+      },
+      {
+        id: "inv_reports",
+        label: "Reports",
+        items: [
+          { id: "dashboard", label: "Dashboard", path: "/inventory/dashboard" },
+          { id: "balances", label: "Stock Balances", path: "/inventory/balances" },
+          { id: "reports", label: "All Reports", path: "/inventory/reports" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "sales",
+    label: "Sales",
+    iconName: "ShoppingCart",
+    groups: [
+      {
+        id: "sales_pos_overview",
+        label: "POS Overview",
+        items: [
+          { id: "pos_dashboard", label: "POS Dashboard", path: "/pos" },
+          { id: "pos_sell", label: "Sell Screen", path: "/pos/sell" },
+          { id: "pos_quick_sell", label: "Quick Sell", path: "/pos/quick-sell" },
+        ],
+      },
+      {
+        id: "sales_pos_ops",
+        label: "POS Operations",
+        items: [
+          { id: "pos_terminals", label: "Terminals", path: "/pos/terminals" },
+          { id: "pos_sessions", label: "Sessions", path: "/pos/sessions" },
+        ],
+      },
+      {
+        id: "sales_pos_transactions",
+        label: "POS Transactions",
+        items: [
+          { id: "pos_invoices", label: "Invoices", path: "/pos/invoices" },
+          { id: "pos_returns", label: "Returns", path: "/pos/returns" },
+        ],
+      },
+      {
+        id: "sales_pos_reports",
+        label: "POS Reports",
+        items: [
+          { id: "pos_reports", label: "Sales Reports", path: "/pos/reports" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "finance",
+    label: "Finance",
+    iconName: "Landmark",
+    groups: [
+      {
+        id: "fin_overview",
+        label: "Overview",
+        items: [
+          { id: "fin_dashboard", label: "Dashboard", path: "/finance" },
+          { id: "fin_settings", label: "Settings", path: "/finance/settings" },
+        ],
+      },
+      {
+        id: "fin_gl",
+        label: "General Ledger",
+        items: [
+          { id: "chart_of_accounts", label: "Chart of Accounts", path: "/finance/accounts" },
+          { id: "fiscal_periods", label: "Fiscal Periods", path: "/finance/fiscal-periods" },
+          { id: "journals", label: "Journal Entries", path: "/finance/journals" },
+          { id: "gl_transactions", label: "GL Transactions", path: "/finance/gl-transactions" },
+        ],
+      },
+      {
+        id: "fin_receivables",
+        label: "Receivables (AR)",
+        items: [
+          { id: "receipts", label: "Receipts", path: "/finance/receipts" },
+          { id: "customers", label: "Customers", path: "/finance/customers" },
+        ],
+      },
+      {
+        id: "fin_payables",
+        label: "Payables (AP)",
+        items: [
+          { id: "payments", label: "Payments", path: "/finance/payments" },
+          { id: "vendors", label: "Vendors", path: "/finance/vendors" },
+        ],
+      },
+      {
+        id: "fin_banking",
+        label: "Banking",
+        items: [
+          { id: "bank_accounts", label: "Bank Accounts", path: "/finance/bank/accounts" },
+          { id: "bank_transactions", label: "Bank Transactions", path: "/finance/bank/transactions" },
+          { id: "bank_reconciliation", label: "Reconciliation", path: "/finance/bank/reconciliation" },
+          { id: "cheques", label: "Cheque Management", path: "/finance/cheques" },
+        ],
+      },
+      {
+        id: "fin_expense_income",
+        label: "Expense & Income",
+        items: [
+          { id: "expense_income", label: "Categories & Transactions", path: "/finance/expense-income" },
+        ],
+      },
+      {
+        id: "fin_tax",
+        label: "Tax",
+        items: [
+          { id: "tax_codes", label: "Tax Codes", path: "/finance/tax/codes" },
+          { id: "tax_returns", label: "Tax Returns", path: "/finance/tax/returns" },
+        ],
+      },
+      {
+        id: "fin_advanced",
+        label: "Advanced",
+        items: [
+          { id: "assets", label: "Fixed Assets", path: "/finance/assets" },
+          { id: "budgets", label: "Budgets", path: "/finance/budgets" },
+          { id: "events", label: "Accounting Events", path: "/finance/events" },
+          { id: "reports", label: "Reports", path: "/finance/reports" },
+          { id: "period_close", label: "Period Close", path: "/finance/period-close" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "procurement",
+    label: "Procurement",
+    iconName: "Truck",
+    groups: [
+      {
+        id: "purch_overview",
+        label: "Overview",
+        items: [
+          { id: "purch_dashboard", label: "Dashboard", path: "/procurement" },
+        ],
+      },
+      {
+        id: "purch_suppliers",
+        label: "Suppliers",
+        items: [
+          { id: "suppliers", label: "Suppliers", path: "/procurement/suppliers" },
+        ],
+      },
+      {
+        id: "purch_purchasing",
+        label: "Purchasing",
+        items: [
+          { id: "requisitions", label: "Requisitions", path: "/procurement/requisitions" },
+          { id: "purchase_orders", label: "Purchase Orders", path: "/procurement/purchase-orders" },
+        ],
+      },
+      {
+        id: "purch_receiving",
+        label: "Receiving",
+        items: [
+          { id: "grns", label: "Goods Receipts (GRN)", path: "/procurement/grns" },
+          { id: "returns", label: "Purchase Returns", path: "/procurement/returns" },
+        ],
+      },
+      {
+        id: "purch_invoicing",
+        label: "Invoicing",
+        items: [
+          { id: "invoices", label: "Supplier Invoices", path: "/procurement/invoices" },
+        ],
+      },
+      {
+        id: "purch_consignment",
+        label: "Consignment",
+        items: [
+          { id: "consignment", label: "Agreements", path: "/procurement/consignment" },
+          { id: "settlements", label: "Settlements", path: "/procurement/consignment/settlements" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "jewelry",
+    label: "Jewelry",
+    iconName: "Gem",
+    groups: [
+      {
+        id: "jwl_overview",
+        label: "Overview",
+        items: [
+          { id: "jwl_dashboard", label: "Dashboard", path: "/jewelry" },
+          { id: "jwl_metal_rates", label: "Metal Rates", path: "/jewelry/metal-rates" },
+        ],
+      },
+      {
+        id: "jwl_setup",
+        label: "Master Data",
+        items: [
+          { id: "jwl_master_metals", label: "Metal Types", path: "/jewelry/master/metals" },
+          { id: "jwl_master_purities", label: "Purity Master", path: "/jewelry/master/purities" },
+          { id: "jwl_repo_settings", label: "Repository Settings", path: "/jewelry/repository-settings" },
+        ],
+      },
+      {
+        id: "jwl_catalog",
+        label: "Catalog",
+        items: [
+          { id: "jwl_items", label: "Jewelry Items", path: "/jewelry/items" },
+          { id: "jwl_stones", label: "Loose Stones", path: "/jewelry/stones" },
+          { id: "jwl_certifications", label: "Certifications", path: "/jewelry/certifications" },
+        ],
+      },
+      {
+        id: "jwl_operations",
+        label: "Operations",
+        items: [
+          { id: "jwl_karigars", label: "Karigars", path: "/jewelry/karigars" },
+          { id: "jwl_custom_orders", label: "Custom Orders", path: "/jewelry/custom-orders" },
+          { id: "jwl_repairs", label: "Repairs", path: "/jewelry/repairs" },
+          { id: "jwl_melting", label: "Old Gold / Melting", path: "/jewelry/melting" },
+        ],
+      },
+      {
+        id: "jwl_manufacturing",
+        label: "Manufacturing",
+        items: [
+          { id: "jwl_refinery", label: "Refinery Batches", path: "/jewelry/refinery" },
+          { id: "jwl_metal_issues", label: "Metal Issues", path: "/jewelry/metal-issues" },
+          { id: "jwl_designs", label: "Design Library", path: "/jewelry/designs" },
+          { id: "jwl_repositories", label: "Metal Repositories", path: "/jewelry/repositories" },
+        ],
+      },
+      {
+        id: "jwl_procurement",
+        label: "Procurement",
+        items: [
+          { id: "jwl_purchase_pos", label: "Purchase POS", path: "/jewelry/purchases" },
+          { id: "jwl_processing", label: "Inventory Processing", path: "/jewelry/purchases/processing" },
+          { id: "jwl_purchase_returns", label: "Purchase Returns", path: "/jewelry/purchases/returns" },
+          { id: "jwl_stone_procurement", label: "Stone Procurement", path: "/jewelry/stone-procurement" },
+          { id: "jwl_consignment", label: "Consignment Stock", path: "/jewelry/consignment" },
+          { id: "jwl_procurement_orders", label: "Purchase Orders", path: "/jewelry/procurement" },
+        ],
+      },
+      {
+        id: "jwl_sales_billing",
+        label: "Sales & Billing",
+        items: [
+          { id: "jwl_pos_sell", label: "POS Sell", path: "/jewelry/pos/sell" },
+          { id: "jwl_pos_sales", label: "View Sales", path: "/jewelry/pos/sales" },
+          { id: "jwl_dealers", label: "Wholesale Dealers", path: "/jewelry/dealers" },
+          { id: "jwl_installments", label: "Installments", path: "/jewelry/installments" },
+          { id: "jwl_vouchers", label: "Gift Vouchers", path: "/jewelry/vouchers" },
+          { id: "jwl_reservations", label: "Reservations", path: "/jewelry/reservations" },
+          { id: "jwl_warranties", label: "Warranties", path: "/jewelry/warranties" },
+        ],
+      },
+      {
+        id: "jwl_reports",
+        label: "Reports",
+        items: [
+          { id: "jwl_reports", label: "Reports & Analytics", path: "/jewelry/reports" },
+        ],
+      },
+      {
+        id: "jwl_system",
+        label: "System",
+        items: [
+          { id: "jwl_notifications", label: "Notifications Queue", path: "/jewelry/notifications" },
+        ],
+      },
+      {
+        id: "jwl_ai",
+        label: "AI Intelligence",
+        items: [
+          { id: "ai_recommendations", label: "Recommendations", path: "/jewelry/ai/recommendations" },
+          { id: "ai_reports", label: "AI Reports", path: "/jewelry/ai/reports" },
+          { id: "ai_anomalies", label: "Anomalies", path: "/jewelry/ai/anomalies" },
+          { id: "ai_predictions", label: "Predictions", path: "/jewelry/ai/predictions" },
+          { id: "ai_usage", label: "Usage", path: "/jewelry/ai/usage" },
+        ],
+      },
+    ],
+  },
+];
+
+/**
+ * Builds MainMenuItem[] from a saved menu config (from the API).
+ * Supports both legacy string[] and enriched SecondaryItemConfig[] formats.
+ */
+export function buildMenusFromConfig(config: {
+  primaryMenus: { id: string; label: string; iconName: string; secondaryItems: SecondaryItemConfig[] }[];
+}): MainMenuItem[] {
+  return config.primaryMenus.map(pm => ({
+    id: pm.id,
+    label: pm.label,
+    iconName: pm.iconName,
+    groups: resolveRegistryKeys(pm.secondaryItems),
+  }));
+}