rbac doc adapted

appdoc/doc_security_role_based_access.md

@@ -47,31 +47,50 @@ The new RBAC system implements a **matrix-based access model** with database-lev
 
 ### Frontend Options Format
 
-The `frontend_options` attribute in Field definitions supports two formats:
+The `frontend_options` attribute in Field definitions supports **two formats**:
 
-1. **Static List** (for basic data types): A list of option dictionaries
+#### 1. Static List (for basic data types)
-   ```python
+A list of option dictionaries for static, predefined options:
-   frontend_options=[
+```python
+frontend_options=[
     {"value": "a", "label": {"en": "All Records", "fr": "Tous les enregistrements"}},
     {"value": "m", "label": {"en": "My Records", "fr": "Mes enregistrements"}}
-   ]
+]
-   ```
+```
 
-2. **String Reference** (for custom types): A string identifier that references dynamic options
+**Use static lists when:**
-   ```python
+- Options are fixed and don't change based on user context
-   frontend_options="user.role"  # Frontend fetches from /api/options/user.role
+- Options are simple enums or constants
-   ```
+- Options don't require database queries
 
-**Dynamic Options API**: When `frontend_options` is a string reference, the frontend must fetch options from `/api/options/{optionsName}`. This allows for:
+#### 2. String Reference (for dynamic/custom types)
-- Database-driven options (e.g., user connections loaded from database)
+A string identifier that references dynamic options from the Options API:
-- Context-aware options (e.g., options filtered by current user's permissions)
+```python
-- Centralized option management (e.g., role definitions managed in one place)
+frontend_options="user.role"  # Frontend fetches from /api/options/user.role
+```
+
+**Use string references when:**
+- Options come from the database (e.g., user connections)
+- Options are context-aware (filtered by current user's permissions)
+- Options need centralized management (e.g., role definitions)
+- Options may change frequently
+
+**Dynamic Options API**: When `frontend_options` is a string reference, the frontend must:
+1. Detect that it's a string (not a list)
+2. Fetch options from `/api/options/{optionsName}`
+3. Use the returned options for the select/multiselect field
 
 **Available Option Names**:
 - `"user.role"` - User role options (sysadmin, admin, user, viewer)
-- `"user.connection"` - User connection types
+- `"user.connection"` - User connection types (context-aware, requires currentUser)
-- `"auth.authority"` - Authentication authorities
+- `"auth.authority"` - Authentication authorities (local, google, msft)
-- `"connection.status"` - Connection statuses
+- `"connection.status"` - Connection statuses (active, inactive, expired, error)
+
+**Type Definition**: The `frontend_options` attribute is typed as `Union[List[Dict[str, Any]], str]`:
+- `List[Dict[str, Any]]`: Static list format
+- `str`: String reference format
+
+See `gateway/modules/shared/frontendOptionsTypes.py` for type definitions and utility functions.
 
 ### Access Rule Model