@flusys/ng-iam 1.0.0-beta → 1.0.0-rc

package/README.md

@@ -14,6 +14,7 @@
 | Version | 1.0.0 |
 | Dependencies | ng-core, ng-shared, ng-layout (IMenuItem only) |
 | NO dependency on | ng-auth (fully independent via Provider Pattern) |
+| CSS Framework | Tailwind CSS (not PrimeFlex) |
 | Build | `npm run build:ng-iam` |
 | Entry point | `public-api.ts` |
 
@@ -64,21 +65,34 @@ ng-iam requires these provider interfaces:
 
 ### How Components Use Providers
 
+User selection uses `lib-user-select` component from ng-shared (encapsulates USER_PROVIDER):
+
+```html
+<!-- UserActionSelectorComponent / UserRoleSelectorComponent -->
+<lib-user-select
+  [(value)]="selectedUserId"
+  [isEditMode]="true"
+  placeHolder="Select a user"
+/>
+```
+
+Company context is accessed via `LAYOUT_AUTH_STATE`:
+
 ```typescript
-// UserActionSelectorComponent / UserRoleSelectorComponent
-private readonly userProvider = inject(USER_PROVIDER);
 private readonly companyContext = inject(LAYOUT_AUTH_STATE);
 
-async loadUsers() {
-  const response = await firstValueFrom(
-    this.userProvider.getUsers({
-      page: 0,
-      pageSize: MAX_DROPDOWN_ITEMS,
-      companyId: this.companyContext.currentCompanyInfo()?.id || undefined,
-    })
-  );
-  this.users.set(response?.data ?? []);
-}
+// Get current company
+const companyId = this.companyContext.currentCompanyInfo()?.id;
+```
+
+Branch permissions loaded from `USER_PERMISSION_PROVIDER`:
+
+```typescript
+private readonly userPermissionProvider = inject(USER_PERMISSION_PROVIDER);
+
+const response = await this.userPermissionProvider
+  .getUserBranchPermissions(userId)
+  .toPromise();
 ```
 
 ---
@@ -363,12 +377,14 @@ Assigns actions directly to users (DIRECT/FULL mode).
 | Standalone | Yes |
 | Change Detection | OnPush |
 
-**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PROVIDER`, `USER_PERMISSION_PROVIDER`, `ActionApiService`, `ActionPermissionLogicService`, `PermissionApiService`, `MessageService`
+**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PERMISSION_PROVIDER`, `ActionApiService`, `ActionPermissionLogicService`, `PermissionApiService`, `MessageService`
 
 **Features:**
-- User dropdown (loaded from USER_PROVIDER)
+- User dropdown (`lib-user-select` component from ng-shared)
 - Branch selector (conditional, loaded from USER_PERMISSION_PROVIDER)
 - Hierarchical TreeTable with checkboxes
+- Responsive table with `overflow-x-auto` container
+- Responsive columns (Code hidden on mobile, Description hidden until lg)
 - Action type tags (backend/frontend/both)
 - Prerequisite validation with tooltips
 - Change tracking with pending add/remove summary
@@ -387,11 +403,13 @@ Assigns roles to users (RBAC/FULL mode).
 | Standalone | Yes |
 | Change Detection | OnPush |
 
-**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PROVIDER`, `USER_PERMISSION_PROVIDER`, `RoleApiService`, `PermissionApiService`, `MessageService`
+**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PERMISSION_PROVIDER`, `RoleApiService`, `PermissionApiService`, `MessageService`
 
 **Features:**
-- User dropdown with branch selector
-- DataTable with pagination
+- User dropdown (`lib-user-select` component from ng-shared)
+- Branch selector (conditional)
+- DataTable with pagination and `overflow-x-auto` container
+- Responsive columns (Code hidden on mobile, Description hidden until md)
 - Change tracking with pending add/remove summary
 - Select/deselect all
 - No prerequisite validation (roles are simple assignments)
@@ -411,12 +429,13 @@ Assigns actions to roles (RBAC/FULL mode).
 **Dependencies:** `RoleApiService`, `ActionApiService`, `PermissionApiService`, `MessageService`, `ActionPermissionLogicService`
 
 **Features:**
-- Role dropdown
-- Hierarchical TreeTable with checkboxes
+- Role dropdown with filter
+- Hierarchical TreeTable with checkboxes and `overflow-x-auto` container
+- Responsive columns (Code hidden until md, Requirements hidden until lg)
 - Prerequisite validation with smart dependency handling
 - Request cancellation with AbortController
 - Pre-save validation with auto-fix dialog
-- Change tracking
+- Change tracking with pending add/remove summary
 
 ---
 
@@ -433,11 +452,14 @@ Manages company action whitelisting (when company feature enabled).
 **Dependencies:** `COMPANY_API_PROVIDER`, `ActionApiService`, `PermissionApiService`, `MessageService`, `ConfirmationService`, `ActionPermissionLogicService`
 
 **Features:**
-- Company dropdown (loaded from COMPANY_API_PROVIDER)
+- Company dropdown with filter (loaded from COMPANY_API_PROVIDER)
 - Full action tree (not filtered by company whitelist)
-- Prerequisite validation
+- Hierarchical TreeTable with `overflow-x-auto` container
+- Responsive columns (Code hidden until md, Description hidden until lg)
+- Prerequisite validation with tooltips
 - Backend prerequisite error handling with auto-fix
 - Request cancellation with AbortController
+- Change tracking with pending whitelist/remove summary
 
 ---
 
@@ -453,8 +475,34 @@ Tabbed navigation container for IAM pages.
 |----------|-------|
 | Selector | `lib-iam-container` |
 | Tabs | Actions (always), Roles (RBAC/FULL), Permissions (always) |
+| Change Detection | OnPush |
 
-Uses `RouterLink` and `RouterLinkActive` for navigation. Tab visibility based on permission mode.
+**Features:**
+- Responsive page title (`text-xl sm:text-2xl`)
+- Horizontally scrollable tabs on mobile (hidden scrollbar)
+- Uses `RouterLink` and `RouterLinkActive` for navigation
+- Tab visibility based on permission mode
+
+**Responsive Patterns:**
+
+```html
+<!-- Page title -->
+<h1 class="text-xl sm:text-2xl font-bold m-0">Identity & Access Management</h1>
+
+<!-- Horizontally scrollable tabs (hidden scrollbar) -->
+<div class="scrollbar-hide flex gap-1 overflow-x-auto flex-nowrap">
+  <!-- tabs -->
+</div>
+```
+
+**Scrollbar hide CSS:**
+```css
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar { display: none; }
+}
+```
 
 ---
 
@@ -467,6 +515,11 @@ Hierarchical action list with CRUD operations.
 | Selector | `lib-action-list-page` |
 | Features | TreeTable display, create/edit/delete, read-only indicators, company context awareness |
 
+**Responsive features:**
+- TreeTable with `overflow-x-auto -mx-4 sm:mx-0` container
+- Responsive columns: Code (hidden until md), Active (hidden until sm), Read Only (hidden until lg)
+- Responsive header with stacked layout on mobile
+
 Reloads actions when company context changes via effect.
 
 ---
@@ -493,6 +546,11 @@ Paginated role list with CRUD operations.
 | Selector | `lib-role-list-page` |
 | Features | Paginated table (10/25/50), create/edit/delete, company context filtering, read-only indicators |
 
+**Responsive features:**
+- Table with `overflow-x-auto -mx-4 sm:mx-0` container
+- Responsive columns: Description (hidden until md), Read Only (hidden until sm)
+- Conditional paginator (only shown when data exists)
+
 ---
 
 ### RoleFormPageComponent
@@ -883,6 +941,96 @@ GET  /iam/permissions/company-actions/:id     # Get company's whitelisted action
 
 ---
 
+## Responsive Table Patterns
+
+All IAM tables and tree tables use consistent responsive patterns with Tailwind CSS.
+
+### Table Container Pattern
+
+```html
+<!-- Wrapper enables horizontal scroll on mobile, full-width on desktop -->
+<div class="overflow-x-auto -mx-4 sm:mx-0">
+  <p-treeTable
+    [value]="treeNodes()"
+    dataKey="id"
+    styleClass="p-treetable-sm"
+    [tableStyle]="{ 'min-width': '50rem' }"
+  >
+    <!-- ... -->
+  </p-treeTable>
+</div>
+```
+
+**Key properties:**
+- `overflow-x-auto` - Enables horizontal scroll when content exceeds container
+- `-mx-4 sm:mx-0` - Edge-to-edge on mobile, normal margins on desktop
+- `[tableStyle]="{ 'min-width': '50rem' }"` - Minimum width ensures consistent layout
+
+### Responsive Column Visibility
+
+```html
+<ng-template #header>
+  <tr>
+    <th class="w-12"><!-- checkbox --></th>
+    <th>Name</th>                           <!-- Always visible -->
+    <th class="hidden sm:table-cell">Code</th>     <!-- Hidden on xs -->
+    <th>Type</th>                           <!-- Always visible -->
+    <th class="hidden md:table-cell">Status</th>   <!-- Hidden until md -->
+    <th class="hidden lg:table-cell">Description</th> <!-- Hidden until lg -->
+  </tr>
+</ng-template>
+```
+
+**Breakpoint classes:**
+| Class | Visibility |
+|-------|------------|
+| (none) | Always visible |
+| `hidden sm:table-cell` | Visible at 640px+ |
+| `hidden md:table-cell` | Visible at 768px+ |
+| `hidden lg:table-cell` | Visible at 1024px+ |
+
+### Header Layout Pattern
+
+```html
+<div class="flex flex-col md:flex-row justify-between items-start md:items-center gap-3 mb-4">
+  <div>
+    <h5 class="m-0 mb-1">Section Title</h5>
+    <p class="text-sm text-muted-color m-0">{{ count }} items available</p>
+  </div>
+  <div class="flex flex-wrap gap-2">
+    <!-- Action buttons -->
+  </div>
+</div>
+```
+
+### Dark Mode Styling
+
+```css
+/* Light mode */
+.validation-warning {
+  background-color: var(--p-yellow-50, #fefce8);
+  border-left: 4px solid var(--p-yellow-500, #eab308);
+  color: var(--p-yellow-700, #a16207);
+}
+
+/* Dark mode */
+:host-context(.p-dark) .validation-warning {
+  background-color: rgba(234, 179, 8, 0.1);
+  color: var(--p-yellow-400, #facc15);
+}
+```
+
+**Color classes (Tailwind):**
+| Purpose | Class |
+|---------|-------|
+| Muted text | `text-muted-color` |
+| Success | `text-green-500` |
+| Danger | `text-red-500` |
+| Warning | `text-orange-500` |
+| Primary | `text-primary` |
+
+---
+
 ## Best Practices
 
 ### Permission Loading
@@ -986,6 +1134,9 @@ const logic: ILogicNode = {
 | 401 on IAM endpoints with external auth | Auth token not forwarded | Ensure your auth interceptor adds `Authorization` header to IAM requests |
 | Provider not configured error | Missing DI registration | Add required providers to `app.config.ts` (USER_PROVIDER, LAYOUT_AUTH_STATE) |
 | Empty user/company dropdowns | API response format mismatch | Ensure adapters return `IListResponse<T>` format with `data` array |
+| TreeTable has excessive whitespace | Using `scrollHeight="flex"` without fixed-height parent | Remove `scrollHeight="flex"` and `[scrollable]="true"`, use `overflow-x-auto` container instead |
+| Table not horizontally scrollable on mobile | Missing responsive wrapper | Add `<div class="overflow-x-auto -mx-4 sm:mx-0">` around table |
+| Columns visible on mobile causing overflow | Missing responsive column classes | Add `hidden sm:table-cell` or `hidden md:table-cell` to non-essential columns |
 
 ---
 
@@ -1015,6 +1166,56 @@ IAM_PERMISSION_MODE=FULL  # DIRECT, RBAC, or FULL
 
 ---
 
+## Provider Functions
+
+### provideIamProviders()
+
+Registers provider adapters that enable other packages (ng-auth) to access IAM functionality without direct dependencies.
+
+```typescript
+import { provideIamProviders } from '@flusys/ng-iam';
+
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideIamProviders(),  // Register IAM providers
+  ],
+};
+```
+
+**Registers:**
+
+| Token | Adapter | Purpose |
+|-------|---------|---------|
+| `PROFILE_PERMISSION_PROVIDER` | `ProfilePermissionProviderAdapter` | User roles/actions for profile page |
+
+### ProfilePermissionProviderAdapter
+
+Implements `IProfilePermissionProvider` from ng-shared. Enables ng-auth's profile page to display user permissions.
+
+```typescript
+interface IProfilePermissionProvider {
+  getUserRoles(userId: string, branchId?: string): Observable<ISingleResponse<IProfileRoleInfo[]>>;
+  getUserActions(userId: string, branchId?: string): Observable<ISingleResponse<IProfileActionInfo[]>>;
+}
+```
+
+**Usage in ng-auth profile page:**
+
+```typescript
+// Optional injection - graceful degradation when IAM disabled
+private readonly permissionProvider = inject(PROFILE_PERMISSION_PROVIDER, { optional: true });
+
+// Load user permissions
+if (this.permissionProvider) {
+  this.permissionProvider.getUserRoles(userId, branchId).subscribe(response => {
+    this.roles.set(response.data ?? []);
+  });
+}
+```
+
+---
+
 ## See Also
 
 - **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration system (APP_CONFIG)
@@ -1024,5 +1225,5 @@ IAM_PERMISSION_MODE=FULL  # DIRECT, RBAC, or FULL
 
 ---
 
-**Last Updated:** 2026-02-15
+**Last Updated:** 2026-02-18 (Updated responsive patterns documentation)
 **Angular Version:** 21