@atlashub/smartstack-cli 3.23.0 → 3.25.0

package/templates/skills/apex/references/smartstack-frontend.md

@@ -0,0 +1,1101 @@
+# SmartStack Frontend Patterns — Mandatory Reference
+
+> **Loaded by:** step-03 (execution) and step-04 (validation)
+> **Purpose:** Defines mandatory frontend patterns extracted from SmartStack.app.
+> **Enforcement:** POST-CHECKs in step-04 verify compliance.
+
+---
+
+## 1. Lazy Loading (React.lazy + Suspense)
+
+> **ALL page components MUST be lazy-loaded.** Only critical entry pages (HomePage, LoginPage) may use static imports.
+
+### Import Pattern
+
+```tsx
+// Named exports — use .then() to wrap
+const EmployeesPage = lazy(() =>
+  import('@/pages/Business/HumanResources/Employees/EmployeesPage')
+    .then(m => ({ default: m.EmployeesPage }))
+);
+
+// Default exports — direct lazy
+const DashboardPage = lazy(() => import('@/pages/Platform/Admin/DashboardPage'));
+```
+
+### Suspense Wrapper
+
+```tsx
+import { Suspense } from 'react';
+import { PageLoader } from '@/components/ui/PageLoader';
+
+// Route element wrapping
+element: (
+  <Suspense fallback={<PageLoader />}>
+    <PermissionGuard permissions={ROUTES['business.hr.employees'].permissions}>
+      <EmployeesPage />
+    </PermissionGuard>
+  </Suspense>
+)
+```
+
+### Rules
+
+- **NEVER** static-import page components in route files
+- **ALWAYS** use `<Suspense fallback={<PageLoader />}>` around lazy components
+- **ALWAYS** use the `.then(m => ({ default: m.ComponentName }))` pattern for named exports
+- Layout components (AdminLayout, BusinessLayout, UserLayout) are ALSO lazy-loaded
+
+**FORBIDDEN:**
+```tsx
+// WRONG: static import in route file
+import { EmployeesPage } from '@/pages/Business/HumanResources/Employees/EmployeesPage';
+
+// WRONG: no Suspense wrapper
+element: <EmployeesPage />
+
+// WRONG: no fallback
+<Suspense><EmployeesPage /></Suspense>
+```
+
+### Client App.tsx — Lazy Imports Mandatory
+
+> **CRITICAL:** In the client `App.tsx` (where `contextRoutes` are defined), ALL page imports MUST use `React.lazy()`.
+
+**CORRECT — Lazy imports in client App.tsx:**
+```tsx
+const ClientsListPage = lazy(() =>
+  import('@/pages/Business/HumanResources/Clients/ClientsListPage')
+    .then(m => ({ default: m.ClientsListPage }))
+);
+```
+
+**FORBIDDEN — Static imports in client App.tsx:**
+```tsx
+// WRONG: Static import kills code splitting
+import { ClientsListPage } from '@/pages/Business/HumanResources/Clients/ClientsListPage';
+```
+
+> **Note:** The `smartstackRoutes.tsx` from the npm package may use static imports internally — this is acceptable for the package. But client `App.tsx` code MUST always use lazy imports for business pages.
+
+---
+
+## 2. I18n / Translations (react-i18next)
+
+> **ALL user-facing text MUST use translations.** 4 languages required: fr, en, it, de.
+
+### File Structure
+
+```
+src/i18n/
+├── config.ts                    # i18n initialization
+├── locales/
+│   ├── fr/
+│   │   ├── common.json          # Shared keys (actions, errors, validation)
+│   │   ├── navigation.json      # Menu labels
+│   │   └── {module}.json        # Module-specific keys
+│   ├── en/
+│   │   └── {module}.json
+│   ├── it/
+│   │   └── {module}.json
+│   └── de/
+│       └── {module}.json
+```
+
+### Module JSON Template
+
+Each new module MUST generate a translation file with this structure:
+
+```json
+{
+  "title": "Module display name",
+  "description": "Module description",
+  "actions": {
+    "create": "Create {entity}",
+    "edit": "Edit {entity}",
+    "delete": "Delete {entity}",
+    "save": "Save",
+    "cancel": "Cancel",
+    "search": "Search...",
+    "export": "Export",
+    "refresh": "Refresh"
+  },
+  "labels": {
+    "name": "Name",
+    "code": "Code",
+    "description": "Description",
+    "status": "Status",
+    "createdAt": "Created at",
+    "updatedAt": "Updated at",
+    "createdBy": "Created by",
+    "isActive": "Active"
+  },
+  "columns": {
+    "name": "Name",
+    "code": "Code",
+    "status": "Status",
+    "actions": "Actions"
+  },
+  "form": {
+    "name": "Name",
+    "namePlaceholder": "Enter name...",
+    "code": "Code",
+    "codePlaceholder": "Enter code...",
+    "description": "Description",
+    "descriptionPlaceholder": "Enter description..."
+  },
+  "errors": {
+    "loadFailed": "Failed to load data",
+    "saveFailed": "Failed to save",
+    "deleteFailed": "Failed to delete",
+    "notFound": "Not found",
+    "permissionDenied": "Permission denied"
+  },
+  "validation": {
+    "nameRequired": "Name is required",
+    "codeRequired": "Code is required",
+    "nameMaxLength": "Name must be less than {{max}} characters"
+  },
+  "messages": {
+    "created": "{entity} created successfully",
+    "updated": "{entity} updated successfully",
+    "deleted": "{entity} deleted successfully",
+    "confirmDelete": "Are you sure you want to delete this {entity}?"
+  },
+  "empty": {
+    "title": "No {entity} found",
+    "description": "Create your first {entity} to get started"
+  }
+}
+```
+
+### Usage in Components
+
+```tsx
+// Hook — specify namespace(s)
+const { t } = useTranslation(['employees']);
+
+// Simple key with MANDATORY fallback
+t('employees:title', 'Employees')
+
+// Key with interpolation
+t('employees:messages.created', '{{entity}} created successfully', { entity: 'Employee' })
+
+// Namespace prefix syntax
+t('employees:actions.create', 'Create employee')
+t('common:actions.save', 'Save')
+t('common:errors.network', 'Network error')
+```
+
+### Rules
+
+- **ALWAYS** provide a fallback value as 2nd argument to `t()`
+- **ALWAYS** use namespace prefix: `t('namespace:key')`
+- **ALWAYS** generate 4 language files (fr, en, it, de) with identical key structures
+- **NEVER** hardcode user-facing strings in JSX
+- **NEVER** use `t('key')` without namespace prefix
+
+**FORBIDDEN:**
+```tsx
+// WRONG: no fallback
+t('employees:title')
+
+// WRONG: no namespace
+t('title')
+
+// WRONG: hardcoded text
+<h1>Employees</h1>
+
+// WRONG: only 2 languages generated
+// Must have fr, en, it, de
+```
+
+---
+
+## 3. Page Structure Pattern
+
+> **ALL pages MUST follow this structure.** Extracted from SmartStack.app reference implementation.
+
+### Standard List Page Template
+
+```tsx
+import { useState, useCallback, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate, useParams } from 'react-router-dom';
+import { Loader2 } from 'lucide-react';
+
+// API hook (generated by scaffold_api_client)
+import { useEntityList } from '@/hooks/useEntity';
+
+export function EntityListPage() {
+  // 1. HOOKS — always at the top
+  const { t } = useTranslation(['{module}']);
+  const navigate = useNavigate();
+
+  // 2. STATE
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [data, setData] = useState<Entity[]>([]);
+
+  // 3. DATA LOADING (useCallback + useEffect)
+  const loadData = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+      const result = await entityApi.getAll();
+      setData(result.items);
+    } catch (err: any) {
+      setError(err.message || t('{module}:errors.loadFailed', 'Failed to load data'));
+    } finally {
+      setLoading(false);
+    }
+  }, [t]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  // 4. LOADING STATE
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-[400px]">
+        <Loader2 className="w-8 h-8 animate-spin text-[var(--color-accent-500)]" />
+      </div>
+    );
+  }
+
+  // 5. ERROR STATE
+  if (error) {
+    return (
+      <div className="flex items-center justify-center min-h-[400px]">
+        <div className="text-center">
+          <p className="text-[var(--text-secondary)]">{error}</p>
+          <button
+            onClick={loadData}
+            className="mt-4 px-4 py-2 bg-[var(--color-accent-500)] text-white rounded"
+          >
+            {t('common:actions.retry', 'Retry')}
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  // 6. CONTENT — create button navigates to /create route
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <h1 className="text-2xl font-bold text-[var(--text-primary)]">
+          {t('{module}:title', 'Module Title')}
+        </h1>
+        <button
+          onClick={() => navigate('create')}
+          className="px-4 py-2 bg-[var(--color-accent-500)] text-white rounded"
+        >
+          {t('{module}:actions.create', 'Create')}
+        </button>
+      </div>
+
+      {/* Content: SmartTable with row click → detail, edit action → /:id/edit */}
+    </div>
+  );
+}
+```
+
+### Detail Page Pattern
+
+```tsx
+export function EntityDetailPage() {
+  const { entityId } = useParams<{ entityId: string }>();
+  const { t } = useTranslation(['{module}']);
+  const navigate = useNavigate();
+
+  const [entity, setEntity] = useState<Entity | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [activeTab, setActiveTab] = useState('info');
+
+  // Lazy tab loading — load data only when tab is first visited
+  const visitedTabsRef = useRef<Set<string>>(new Set(['info']));
+
+  useEffect(() => {
+    if (!visitedTabsRef.current.has(activeTab)) {
+      visitedTabsRef.current.add(activeTab);
+      // Load tab-specific data here
+    }
+  }, [activeTab]);
+
+  // Edit button navigates to /:id/edit route (NEVER opens a modal)
+  const handleEdit = () => navigate(`/${basePath}/${entityId}/edit`);
+
+  // ... loading/error/content pattern
+}
+```
+
+---
+
+## 3b. Form Pages Pattern (Create / Edit)
+
+> **CRITICAL: ALL forms MUST be full pages with their own URL route.**
+> **NEVER use modals, dialogs, drawers, or popups for create/edit forms.**
+
+### Route Convention
+
+| Action | Route pattern | Page component | File location |
+|--------|--------------|----------------|---------------|
+| Create | `/{module}/create` | `EntityCreatePage` | `src/pages/{Context}/{App}/{Module}/EntityCreatePage.tsx` |
+| Edit | `/{module}/:id/edit` | `EntityEditPage` | `src/pages/{Context}/{App}/{Module}/EntityEditPage.tsx` |
+
+### Create Page Template
+
+```tsx
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate } from 'react-router-dom';
+
+export function EntityCreatePage() {
+  const { t } = useTranslation(['{module}']);
+  const navigate = useNavigate();
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleSubmit = async (data: CreateEntityDto) => {
+    try {
+      setSubmitting(true);
+      await entityApi.create(data);
+      navigate(-1); // Back to list
+    } catch (err: any) {
+      // Handle validation errors
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Back button */}
+      <button
+        onClick={() => navigate(-1)}
+        className="text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+      >
+        {t('common:actions.back', 'Back')}
+      </button>
+
+      {/* Page title */}
+      <h1 className="text-2xl font-bold text-[var(--text-primary)]">
+        {t('{module}:actions.create', 'Create {Entity}')}
+      </h1>
+
+      {/* SmartForm — NEVER in a modal */}
+      <SmartForm
+        fields={formFields}
+        onSubmit={handleSubmit}
+        onCancel={() => navigate(-1)}
+        submitting={submitting}
+      />
+    </div>
+  );
+}
+```
+
+### Edit Page Template
+
+```tsx
+import { useState, useEffect, useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate, useParams } from 'react-router-dom';
+import { Loader2 } from 'lucide-react';
+
+export function EntityEditPage() {
+  const { entityId } = useParams<{ entityId: string }>();
+  const { t } = useTranslation(['{module}']);
+  const navigate = useNavigate();
+  const [entity, setEntity] = useState<Entity | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+
+  const loadEntity = useCallback(async () => {
+    try {
+      setLoading(true);
+      const result = await entityApi.getById(entityId!);
+      setEntity(result);
+    } catch {
+      navigate(-1);
+    } finally {
+      setLoading(false);
+    }
+  }, [entityId, navigate]);
+
+  useEffect(() => { loadEntity(); }, [loadEntity]);
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-[400px]">
+        <Loader2 className="w-8 h-8 animate-spin text-[var(--color-accent-500)]" />
+      </div>
+    );
+  }
+
+  const handleSubmit = async (data: UpdateEntityDto) => {
+    try {
+      setSubmitting(true);
+      await entityApi.update(entityId!, data);
+      navigate(-1); // Back to detail or list
+    } catch (err: any) {
+      // Handle validation errors
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Back button */}
+      <button
+        onClick={() => navigate(-1)}
+        className="text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+      >
+        {t('common:actions.back', 'Back')}
+      </button>
+
+      {/* Page title */}
+      <h1 className="text-2xl font-bold text-[var(--text-primary)]">
+        {t('{module}:actions.edit', 'Edit {Entity}')}
+      </h1>
+
+      {/* SmartForm pre-filled — NEVER in a modal */}
+      <SmartForm
+        fields={formFields}
+        initialValues={entity}
+        onSubmit={handleSubmit}
+        onCancel={() => navigate(-1)}
+        submitting={submitting}
+      />
+    </div>
+  );
+}
+```
+
+### Lazy Loading for Form Pages
+
+```tsx
+// In route files — form pages are also lazy-loaded
+const EntityCreatePage = lazy(() =>
+  import('@/pages/Business/HumanResources/Employees/EntityCreatePage')
+    .then(m => ({ default: m.EntityCreatePage }))
+);
+const EntityEditPage = lazy(() =>
+  import('@/pages/Business/HumanResources/Employees/EntityEditPage')
+    .then(m => ({ default: m.EntityEditPage }))
+);
+
+// Route registration — form pages have their own routes
+{
+  path: 'employees',
+  children: [
+    { index: true, element: <Suspense fallback={<PageLoader />}><EmployeesPage /></Suspense> },
+    { path: 'create', element: <Suspense fallback={<PageLoader />}><EntityCreatePage /></Suspense> },
+    { path: ':id', element: <Suspense fallback={<PageLoader />}><EntityDetailPage /></Suspense> },
+    { path: ':id/edit', element: <Suspense fallback={<PageLoader />}><EntityEditPage /></Suspense> },
+  ]
+}
+```
+
+### Rules
+
+- **NEVER** use `<Modal>`, `<Dialog>`, `<Drawer>`, or `<Popup>` for create/edit forms
+- **NEVER** use `useState(isOpen)` to toggle form visibility — forms are pages, not overlays
+- **ALWAYS** create a dedicated `EntityCreatePage.tsx` and `EntityEditPage.tsx` page component
+- **ALWAYS** register create/edit routes alongside list/detail routes
+- **ALWAYS** use `navigate('create')` or `navigate(\`${id}/edit\`)` from list/detail pages
+- **ALWAYS** include a back button that uses `navigate(-1)` to return to previous page
+
+**FORBIDDEN:**
+```tsx
+// WRONG: modal for create form
+const [showCreateModal, setShowCreateModal] = useState(false);
+<Modal open={showCreateModal}><CreateForm /></Modal>
+
+// WRONG: dialog for edit form
+<Dialog open={editDialogOpen}><EditForm entity={selected} /></Dialog>
+
+// WRONG: drawer for form
+<Drawer open={isDrawerOpen}><SmartForm /></Drawer>
+
+// WRONG: inline form toggle
+{isEditing ? <EditForm /> : <DetailView />}
+```
+
+---
+
+## 4. CSS Variables (Theme System)
+
+> **NEVER use hardcoded Tailwind colors.** ALWAYS use CSS variables for theme support.
+
+### Variable Reference
+
+| Usage | CSS Variable | Example |
+|-------|-------------|---------|
+| Background | `var(--bg-primary)` | `bg-[var(--bg-primary)]` |
+| Card background | `var(--bg-card)` | `bg-[var(--bg-card)]` |
+| Text primary | `var(--text-primary)` | `text-[var(--text-primary)]` |
+| Text secondary | `var(--text-secondary)` | `text-[var(--text-secondary)]` |
+| Borders | `var(--border-color)` | `border-[var(--border-color)]` |
+| Accent | `var(--color-accent-500)` | `text-[var(--color-accent-500)]` |
+| Card radius | `var(--radius-card)` | `style={{ borderRadius: 'var(--radius-card)' }}` |
+
+### Card Pattern
+
+```tsx
+<div
+  className="bg-[var(--bg-card)] border border-[var(--border-color)] p-6"
+  style={{ borderRadius: 'var(--radius-card)' }}
+>
+  <h2 className="text-lg font-semibold text-[var(--text-primary)]">Title</h2>
+  <p className="text-sm text-[var(--text-secondary)]">Description</p>
+</div>
+```
+
+**FORBIDDEN:**
+```tsx
+// WRONG: hardcoded Tailwind colors
+className="bg-white border-gray-200 text-gray-900"
+
+// WRONG: hardcoded hex/rgb
+style={{ backgroundColor: '#ffffff', color: '#1a1a1a' }}
+```
+
+---
+
+## 5. Component Rules
+
+| Need | Component | Source |
+|------|-----------|--------|
+| Data table | `SmartTable` | `@/components/SmartTable` |
+| Filters | `SmartFilter` | `@/components/SmartFilter` |
+| Entity cards | `EntityCard` | `@/components/EntityCard` |
+| Forms | `SmartForm` | `@/components/SmartForm` |
+| FK field lookup | `EntityLookup` | `@/components/ui/EntityLookup` |
+| Statistics | `StatCard` | `@/components/StatCard` |
+| Loading spinner | `Loader2` | `lucide-react` |
+| Page loader | `PageLoader` | `@/components/ui/PageLoader` |
+
+### Rules
+
+- **NEVER** use raw `<table>` — use SmartTable
+- **NEVER** create custom spinners — use `Loader2` from lucide-react
+- **NEVER** import axios directly — use `@/services/api/apiClient`
+- **ALWAYS** use `PageLoader` as Suspense fallback
+- **ALWAYS** use existing shared components before creating new ones
+
+---
+
+## 6. Foreign Key Fields & Entity Lookup (CRITICAL)
+
+> **NEVER render a foreign key (Guid) as a plain text input.** FK fields MUST use a searchable lookup component.
+> A form asking the user to type a GUID manually is a UX failure. ALL FK fields must provide entity search & selection.
+
+### Field Type Classification
+
+When generating form fields, determine the field type from the entity property:
+
+| Property type | Form field type | Component |
+|---------------|----------------|-----------|
+| `string` | Text input | `<input type="text" />` |
+| `string?` | Text input (optional) | `<input type="text" />` |
+| `Guid` (FK — e.g., `EmployeeId`, `DepartmentId`) | **Entity Lookup** | `<EntityLookup />` |
+| `bool` | Toggle/Checkbox | `<input type="checkbox" />` |
+| `int` / `decimal` | Number input | `<input type="number" />` |
+| `DateTime` | Date picker | `<input type="date" />` |
+| `enum` | Select dropdown | `<select>` |
+
+**How to detect FK fields:** Any property named `{Entity}Id` of type `Guid` that has a corresponding navigation property is a foreign key. Examples: `EmployeeId`, `DepartmentId`, `CategoryId`, `ParentId`.
+
+### EntityLookup Component Pattern
+
+```tsx
+import { useState, useCallback, useMemo, useRef, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Search, X, ChevronDown } from 'lucide-react';
+import { apiClient } from '@/services/api/apiClient';
+
+interface EntityLookupOption {
+  id: string;
+  label: string;        // Display name (e.g., employee full name)
+  sublabel?: string;     // Secondary info (e.g., department, code)
+}
+
+interface EntityLookupProps {
+  /** API endpoint to search entities (e.g., '/api/business/human-resources/employees') */
+  apiEndpoint: string;
+  /** Currently selected entity ID */
+  value: string | null;
+  /** Callback when entity is selected */
+  onChange: (id: string | null) => void;
+  /** Field label */
+  label: string;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Map API response item to display option */
+  mapOption: (item: any) => EntityLookupOption;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+  /** Error message to display */
+  error?: string;
+}
+
+export function EntityLookup({
+  apiEndpoint,
+  value,
+  onChange,
+  label,
+  placeholder,
+  mapOption,
+  required = false,
+  disabled = false,
+  error,
+}: EntityLookupProps) {
+  const { t } = useTranslation(['common']);
+  const [search, setSearch] = useState('');
+  const [options, setOptions] = useState<EntityLookupOption[]>([]);
+  const [selectedOption, setSelectedOption] = useState<EntityLookupOption | null>(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>();
+
+  // Load selected entity display on mount (when value is set but no label)
+  useEffect(() => {
+    if (value && !selectedOption) {
+      apiClient.get(`${apiEndpoint}/${value}`)
+        .then(res => setSelectedOption(mapOption(res.data)))
+        .catch(() => { /* Entity not found — clear */ });
+    }
+  }, [value, apiEndpoint, mapOption, selectedOption]);
+
+  // Debounced search — 300ms delay, minimum 2 characters
+  const handleSearch = useCallback((term: string) => {
+    setSearch(term);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+
+    if (term.length < 2) {
+      setOptions([]);
+      return;
+    }
+
+    debounceRef.current = setTimeout(async () => {
+      setLoading(true);
+      try {
+        const res = await apiClient.get(apiEndpoint, {
+          params: { search: term, pageSize: 20 },
+        });
+        setOptions((res.data.items || res.data).map(mapOption));
+      } catch {
+        setOptions([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 300);
+  }, [apiEndpoint, mapOption]);
+
+  // Load initial options when dropdown opens (show first 20)
+  const handleOpen = useCallback(async () => {
+    if (disabled) return;
+    setIsOpen(true);
+    if (options.length === 0 && search.length < 2) {
+      setLoading(true);
+      try {
+        const res = await apiClient.get(apiEndpoint, {
+          params: { pageSize: 20 },
+        });
+        setOptions((res.data.items || res.data).map(mapOption));
+      } catch {
+        setOptions([]);
+      } finally {
+        setLoading(false);
+      }
+    }
+  }, [disabled, apiEndpoint, mapOption, options.length, search.length]);
+
+  // Select entity
+  const handleSelect = useCallback((option: EntityLookupOption) => {
+    setSelectedOption(option);
+    onChange(option.id);
+    setIsOpen(false);
+    setSearch('');
+  }, [onChange]);
+
+  // Clear selection
+  const handleClear = useCallback(() => {
+    setSelectedOption(null);
+    onChange(null);
+    setSearch('');
+  }, [onChange]);
+
+  // Close on outside click
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  return (
+    <div ref={containerRef} className="relative">
+      <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
+        {label} {required && <span className="text-[var(--error-text)]">*</span>}
+      </label>
+
+      {/* Selected value display OR search input */}
+      {selectedOption && !isOpen ? (
+        <div className="flex items-center gap-2 px-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)]">
+          <div className="flex-1">
+            <span className="text-[var(--text-primary)]">{selectedOption.label}</span>
+            {selectedOption.sublabel && (
+              <span className="ml-2 text-sm text-[var(--text-secondary)]">{selectedOption.sublabel}</span>
+            )}
+          </div>
+          {!disabled && (
+            <button type="button" onClick={handleClear} className="text-[var(--text-secondary)] hover:text-[var(--text-primary)]">
+              <X className="w-4 h-4" />
+            </button>
+          )}
+          <button type="button" onClick={handleOpen} className="text-[var(--text-secondary)]">
+            <ChevronDown className="w-4 h-4" />
+          </button>
+        </div>
+      ) : (
+        <div className="relative">
+          <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-[var(--text-secondary)]" />
+          <input
+            type="text"
+            value={search}
+            onChange={(e) => handleSearch(e.target.value)}
+            onFocus={handleOpen}
+            placeholder={placeholder || t('common:actions.search', 'Search...')}
+            disabled={disabled}
+            className="w-full pl-9 pr-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)] text-[var(--text-primary)] placeholder:text-[var(--text-secondary)] focus:ring-2 focus:ring-[var(--color-accent-500)] focus:border-transparent"
+          />
+        </div>
+      )}
+
+      {/* Dropdown */}
+      {isOpen && (
+        <div className="absolute z-50 w-full mt-1 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] shadow-lg max-h-60 overflow-auto">
+          {loading ? (
+            <div className="p-3 text-center text-[var(--text-secondary)]">
+              {t('common:actions.loading', 'Loading...')}
+            </div>
+          ) : options.length === 0 ? (
+            <div className="p-3 text-center text-[var(--text-secondary)]">
+              {search.length < 2
+                ? t('common:actions.typeToSearch', 'Type at least 2 characters to search...')
+                : t('common:empty.noResults', 'No results found')}
+            </div>
+          ) : (
+            options.map((option) => (
+              <button
+                key={option.id}
+                type="button"
+                onClick={() => handleSelect(option)}
+                className="w-full px-3 py-2 text-left hover:bg-[var(--bg-hover)] transition-colors"
+              >
+                <div className="text-[var(--text-primary)]">{option.label}</div>
+                {option.sublabel && (
+                  <div className="text-sm text-[var(--text-secondary)]">{option.sublabel}</div>
+                )}
+              </button>
+            ))
+          )}
+        </div>
+      )}
+
+      {/* Error message */}
+      {error && (
+        <p className="mt-1 text-sm text-[var(--error-text)]">{error}</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Usage in Form Pages
+
+```tsx
+// In EntityCreatePage.tsx or EntityEditPage.tsx
+import { EntityLookup } from '@/components/ui/EntityLookup';
+
+// Inside the form:
+<EntityLookup
+  apiEndpoint="/api/business/human-resources/employees"
+  value={formData.employeeId}
+  onChange={(id) => handleChange('employeeId', id)}
+  label={t('module:form.employee', 'Employee')}
+  placeholder={t('module:form.employeePlaceholder', 'Search for an employee...')}
+  mapOption={(emp) => ({
+    id: emp.id,
+    label: `${emp.firstName} ${emp.lastName}`,
+    sublabel: emp.department || emp.code,
+  })}
+  required
+  error={errors.employeeId}
+/>
+
+// For DepartmentId FK:
+<EntityLookup
+  apiEndpoint="/api/business/human-resources/departments"
+  value={formData.departmentId}
+  onChange={(id) => handleChange('departmentId', id)}
+  label={t('module:form.department', 'Department')}
+  placeholder={t('module:form.departmentPlaceholder', 'Search for a department...')}
+  mapOption={(dept) => ({
+    id: dept.id,
+    label: dept.name,
+    sublabel: dept.code,
+  })}
+  required
+/>
+```
+
+### API Search Endpoint Convention (Backend)
+
+For EntityLookup to work, each entity's API MUST support search via query parameter:
+
+```
+GET /api/{resource}?search={term}&pageSize=20
+```
+
+Response format:
+```json
+{
+  "items": [
+    { "id": "guid", "code": "EMP001", "name": "John Doe", ... }
+  ],
+  "totalCount": 42
+}
+```
+
+The backend service's `GetAllAsync` method should accept search parameters:
+
+```csharp
+public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
+    string? search = null,
+    int page = 1,
+    int pageSize = 20,
+    CancellationToken ct = default)
+{
+    var query = _db.Entities
+        .Where(x => x.TenantId == _currentUser.TenantId);
+
+    if (!string.IsNullOrWhiteSpace(search))
+    {
+        query = query.Where(x =>
+            x.Name.Contains(search) ||
+            x.Code.Contains(search));
+    }
+
+    var totalCount = await query.CountAsync(ct);
+    var items = await query
+        .OrderBy(x => x.Name)
+        .Skip((page - 1) * pageSize)
+        .Take(pageSize)
+        .Select(x => new EntityResponseDto { ... })
+        .ToListAsync(ct);
+
+    return new PaginatedResult<EntityResponseDto>(items, totalCount, page, pageSize);
+}
+```
+
+### Rules
+
+- **NEVER** render a `Guid` FK field as `<input type="text">` — always use `EntityLookup`
+- **NEVER** ask the user to manually type or paste a GUID/ID
+- **ALWAYS** provide a search-based selection for FK fields
+- **ALWAYS** show the entity's display name (Name, FullName, Code+Name) not the GUID
+- **ALWAYS** include `mapOption` to define how the related entity is displayed
+- **ALWAYS** load the selected entity's display name on mount (for edit forms)
+- **ALWAYS** support clearing the selection (unless required + already set)
+
+**FORBIDDEN:**
+```tsx
+// WRONG: Plain text input for FK field
+<input
+  type="text"
+  value={formData.employeeId}
+  onChange={(e) => handleChange('employeeId', e.target.value)}
+  placeholder="Enter Employee ID..."
+/>
+
+// WRONG: Raw GUID displayed to user
+<span>{entity.departmentId}</span>
+
+// WRONG: Select with hardcoded options for FK
+<select onChange={(e) => handleChange('departmentId', e.target.value)}>
+  <option value="guid-1">Department A</option>
+</select>
+```
+
+### I18n Keys for EntityLookup
+
+Add these keys to the module's translation files:
+
+```json
+{
+  "form": {
+    "employee": "Employee",
+    "employeePlaceholder": "Search for an employee...",
+    "department": "Department",
+    "departmentPlaceholder": "Search for a department..."
+  }
+}
+```
+
+---
+
+## 7. Checklist for /apex Frontend Execution
+
+Before marking frontend tasks as complete, verify:
+
+- [ ] All page imports use `React.lazy()` with named export wrapping
+- [ ] `<Suspense fallback={<PageLoader />}>` wraps all lazy components in routes
+- [ ] Translation files exist for **all 4 languages** (fr, en, it, de)
+- [ ] All `t()` calls include namespace prefix AND fallback value
+- [ ] No hardcoded strings in JSX — all text goes through `t()`
+- [ ] CSS uses variables only — no hardcoded Tailwind colors
+- [ ] Pages follow loading → error → content pattern
+- [ ] Pages use `src/pages/{Context}/{App}/{Module}/` hierarchy
+- [ ] API calls use generated hooks or `apiClient` (never raw axios)
+- [ ] Components use SmartTable/SmartFilter/EntityCard (never raw HTML tables)
+- [ ] **FK fields use `EntityLookup` — ZERO plain text inputs for Guid FK fields**
+- [ ] **All FK fields have `mapOption` showing display name, not GUID**
+- [ ] **Backend APIs support `?search=` query parameter for EntityLookup**
+- [ ] **Create/Edit forms are full pages with own routes — ZERO modals/popups/drawers**
+- [ ] `EntityCreatePage.tsx` exists with route `/{module}/create`
+- [ ] `EntityEditPage.tsx` exists with route `/{module}/:id/edit`
+- [ ] No `<Modal>`, `<Dialog>`, `<Drawer>` imports in form-related pages
+- [ ] Form pages include back button with `navigate(-1)`
+- [ ] Form pages are covered by frontend tests (see section 8)
+
+---
+
+## 8. Frontend Form Testing
+
+> **ALL form pages MUST have tests.** Forms are critical user interaction points and MUST be verified.
+
+### Required Test Coverage per Form Page
+
+| Test category | What to verify | Tool |
+|---------------|---------------|------|
+| Rendering | Form renders with all expected fields | Vitest + React Testing Library |
+| Validation | Required fields show errors on empty submit | Vitest + React Testing Library |
+| Submission | Successful submit calls API and navigates back | Vitest + MSW (mock API) |
+| Pre-fill (edit) | Edit form loads entity data into fields | Vitest + React Testing Library |
+| Navigation | Back button calls `navigate(-1)` | Vitest + React Testing Library |
+| Error handling | API error displays error message | Vitest + MSW |
+
+### Test File Convention
+
+```
+src/pages/{Context}/{App}/{Module}/
+├── EntityCreatePage.tsx
+├── EntityCreatePage.test.tsx    ← MANDATORY
+├── EntityEditPage.tsx
+├── EntityEditPage.test.tsx      ← MANDATORY
+├── EntityListPage.tsx
+└── EntityDetailPage.tsx
+```
+
+### Create Page Test Template
+
+```tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter } from 'react-router-dom';
+import { describe, it, expect, vi } from 'vitest';
+import { EntityCreatePage } from './EntityCreatePage';
+
+// Mock API
+vi.mock('@/services/api/apiClient');
+const mockNavigate = vi.fn();
+vi.mock('react-router-dom', async () => ({
+  ...(await vi.importActual('react-router-dom')),
+  useNavigate: () => mockNavigate,
+}));
+
+describe('EntityCreatePage', () => {
+  it('renders the create form with all fields', () => {
+    render(<MemoryRouter><EntityCreatePage /></MemoryRouter>);
+    expect(screen.getByRole('textbox', { name: /name/i })).toBeInTheDocument();
+    // Verify all expected form fields
+  });
+
+  it('shows validation errors on empty submit', async () => {
+    render(<MemoryRouter><EntityCreatePage /></MemoryRouter>);
+    await userEvent.click(screen.getByRole('button', { name: /save|create/i }));
+    await waitFor(() => {
+      expect(screen.getByText(/required/i)).toBeInTheDocument();
+    });
+  });
+
+  it('submits form and navigates back on success', async () => {
+    render(<MemoryRouter><EntityCreatePage /></MemoryRouter>);
+    await userEvent.type(screen.getByRole('textbox', { name: /name/i }), 'Test');
+    await userEvent.click(screen.getByRole('button', { name: /save|create/i }));
+    await waitFor(() => {
+      expect(mockNavigate).toHaveBeenCalledWith(-1);
+    });
+  });
+
+  it('navigates back on cancel/back button', async () => {
+    render(<MemoryRouter><EntityCreatePage /></MemoryRouter>);
+    await userEvent.click(screen.getByRole('button', { name: /back|cancel/i }));
+    expect(mockNavigate).toHaveBeenCalledWith(-1);
+  });
+});
+```
+
+### Edit Page Test Template
+
+```tsx
+describe('EntityEditPage', () => {
+  it('loads entity data and pre-fills the form', async () => {
+    render(<MemoryRouter initialEntries={['/entities/123/edit']}><EntityEditPage /></MemoryRouter>);
+    await waitFor(() => {
+      expect(screen.getByDisplayValue('Existing Name')).toBeInTheDocument();
+    });
+  });
+
+  it('submits updated data and navigates back', async () => {
+    render(<MemoryRouter initialEntries={['/entities/123/edit']}><EntityEditPage /></MemoryRouter>);
+    await waitFor(() => screen.getByDisplayValue('Existing Name'));
+    await userEvent.clear(screen.getByRole('textbox', { name: /name/i }));
+    await userEvent.type(screen.getByRole('textbox', { name: /name/i }), 'Updated');
+    await userEvent.click(screen.getByRole('button', { name: /save/i }));
+    await waitFor(() => {
+      expect(mockNavigate).toHaveBeenCalledWith(-1);
+    });
+  });
+
+  it('displays error when API call fails', async () => {
+    // Mock API to reject
+    render(<MemoryRouter initialEntries={['/entities/123/edit']}><EntityEditPage /></MemoryRouter>);
+    // ... trigger submit with mocked failure
+    await waitFor(() => {
+      expect(screen.getByText(/failed/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+### Rules
+
+- **EVERY** `EntityCreatePage.tsx` MUST have a companion `EntityCreatePage.test.tsx`
+- **EVERY** `EntityEditPage.tsx` MUST have a companion `EntityEditPage.test.tsx`
+- Tests MUST cover: rendering, validation, submit success, submit error, navigation
+- Use `@testing-library/react` + `@testing-library/user-event` (NEVER enzyme)
+- Mock API with `vi.mock()` or MSW — NEVER make real API calls in tests
+- Test files live next to their component (co-located, NOT in a separate `__tests__/` folder)