namirasoft-account-react 1.4.424 → 1.4.425

package/SKILLS.md

@@ -1,514 +1,514 @@
----
-name: namirasoft-account-react
-description: Use when working with the namirasoft-account-react npm package — a React UI library providing auth flows, workspace/access/product dialogs, CRUD layouts (list/view/edit), secret field components, and an auth-gated router for Namirasoft Console frontends.
-triggers:
-  - namirasoft-account-react
-  - NSARouterMaker
-  - NSALayout
-  - NSASectionList
-  - NSASectionEdit
-  - NSASectionView
-  - NSBoxSecret
-  - account react
----
-
-# namirasoft-account-react
-
-**Package:** `namirasoft-account-react` v1.4.413  
-**Purpose:** Enterprise React UI library for Namirasoft products. Provides the complete authentication flow (login, verification, consent), workspace/access/product management dialogs, generic CRUD layouts (list/view/edit), secret field components, and a router framework that gates pages behind authentication state.  
-**Stack:** React 18, TypeScript, React Router 7, Bootstrap 5, CSS Modules.
-
----
-
-## When to use this package
-
-Use `namirasoft-account-react` in every **frontend Console** (React SPA) that needs to:
-- Authenticate users via the Namirasoft Account service
-- Enforce email and phone verification before access
-- Show a consent/terms page when policies change
-- Provide workspace switching, access (impersonation), and product navigation
-- Render generic entity list / view / edit pages
-- Store and display sensitive secrets (encrypted fields)
-- Poll and display in-app messages
-
----
-
-## Environment Variables
-
-Copy `.env.template` and fill in all values before running:
-
-```bash
-REACT_APP_BASE_PATH=""                                          # sub-path if not at root
-REACT_APP_BASE_URL_ACCESS="https://access.namirasoft.com/api/v1"
-REACT_APP_BASE_URL_ACCOUNT="https://account.namirasoft.com/api/v1"
-REACT_APP_BASE_URL_ACCOUNT_CONSOLE="https://account.namirasoft.com"
-REACT_APP_BASE_URL_API_LINK="https://namirasoft.com/api/link/v1"
-REACT_APP_BASE_URL_API_PRODUCT="https://namirasoft.com/api/product/v1"
-REACT_APP_BASE_URL_FIELD="https://field.namirasoft.com/api/v1"
-REACT_APP_BASE_URL_HISTORY="https://history.namirasoft.com/api/v1"
-REACT_APP_BASE_URL_HISTORY_CONSOLE="https://history.namirasoft.com"
-REACT_APP_BASE_URL_MESSAGE="https://message.namirasoft.com/api/v1"
-REACT_APP_BASE_URL_MESSAGE_CONSOLE="https://message.namirasoft.com"
-REACT_APP_BASE_URL_SECRET="https://secret.namirasoft.com/api/v1"
-REACT_APP_BASE_URL_WORKSPACE="https://workspace.namirasoft.com/api/v1"
-```
-
----
-
-## Exports (`main.ts`)
-
-### Components
-
-| Export | File | Description |
-|--------|------|-------------|
-| `NSAAccessListDialog` | `components/NSAAccessListDialog.tsx` | Incoming permissions / impersonation switcher |
-| `NSAMessageListDialog` | `components/NSAMessageListDialog.tsx` | Unread message center (max 4, mark-all-seen) |
-| `NSAProductListDialog` | `components/NSAProductListDialog.tsx` | Searchable product list |
-| `NSAWorkspaceListDialog` | `components/NSAWorkspaceListDialog.tsx` | Workspace switcher |
-| `NSAUserDialog` | `components/NSAUserDialog.tsx` | User profile and settings dialog |
-| `NSAMasterMenu` | `components/NSAMasterMenu.tsx` | Sidebar navigation with search and collapse |
-| `NSAMasterMenuItem` | `components/NSAMasterMenuItem.tsx` | Individual menu item |
-| `NSBoxSecret` | `components/NSBoxSecret.tsx` | Secret/encrypted value input |
-| `NSLabelSecret` | `components/NSLabelSecret.tsx` | Secret/encrypted value display label |
-
-### Layouts
-
-| Export | File | Description |
-|--------|------|-------------|
-| `NSALayout` | `layouts/NSALayout.tsx` | Root layout: header, master menu, all dialogs, delete confirm |
-| `NSASectionList` | `layouts/NSASectionList.tsx` | Entity table with filter/sort/select |
-| `NSASectionEdit` | `layouts/NSASectionEdit.tsx` | Entity create/update form (tabbed) |
-| `NSASectionView` | `layouts/NSASectionView.tsx` | Entity read-only detail view (tabbed) |
-| `NSASectionViewTabPage` | `layouts/NSASectionViewTabPage.tsx` | Single tab inside `NSASectionView` |
-| `NSASectionEditTabPage` | `layouts/NSASectionEditTabPage.tsx` | Single tab inside `NSASectionEdit` |
-
-### Pages
-
-| Export | File | Description |
-|--------|------|-------------|
-| `NSALoginPage` | `pages/NSALoginPage.tsx` | Login page — opens OAuth flow |
-| `NSAConsentPage` | `pages/NSAConsentPage.tsx` | Terms/privacy acceptance |
-| `NSAEmailVerificationPage` | `pages/NSAEmailVerificationPage.tsx` | Email verification (send + verify code) |
-| `NSAPhoneVerificationPage` | `pages/NSAPhoneVerificationPage.tsx` | Phone verification (enter number + SMS code) |
-| `NSAVerificationPage` | `pages/NSAVerificationPage.tsx` | Generic verification base component |
-| `NSAHomePage` | `pages/NSAHomePage.tsx` | Product grid home page |
-| `PaymentRequired` | `pages/PaymentRequired.tsx` | Subscription gate wrapper |
-
-### Formatters
-
-| Export | File | Description |
-|--------|------|-------------|
-| `SecretFormatter` | `formatters/SecretFormatter.tsx` | Table cell formatter for encrypted secret values |
-
-### Router & Config
-
-| Export | File | Description |
-|--------|------|-------------|
-| `NSARouterMaker` | `NSARouterMaker.tsx` | Auth-aware router — gates pages by login/verification state |
-| `NSARouterMakerProps` | `NSARouterMakerProps.ts` | Props injected into routed components |
-| `NSARouterMakerConfig` | `NSARouterMakerConfig.ts` | Config callbacks for `NSARouterMaker` |
-
-### Utilities
-
-| Export | File | Description |
-|--------|------|-------------|
-| `IEntityInfo` | `IEntityInfo.ts` | Entity definition interface for CRUD pages |
-| `Actions` | `layouts/Actions.ts` | Menu action builder (new, view, edit, delete, …) |
-| `CFTUtil` | `layouts/CFTUtil.ts` | Custom Table Fields get/set helpers |
-| `UseParams` | `UseParams.tsx` | Hook wrapper for URL params |
-
----
-
-## Key Types & Interfaces
-
-### `NSARouterMakerConfig`
-
-Callbacks that configure the router's rendering behaviour:
-
-```typescript
-interface NSARouterMakerConfig {
-    // Called when user is authenticated and all verifications pass
-    onRenderOnLogin(props: NSARouterMakerProps): ReactNode;
-
-    // Called when user is not authenticated (banned = account suspended)
-    onRenderOnLogout(props: NSARouterMakerProps, banned: boolean): ReactNode;
-
-    // Wraps any page in NSALayout (called for all authenticated renders)
-    renderOnNSALayout(props: NSARouterMakerProps, children: ReactNode): ReactNode;
-
-    // Optional: custom render override
-    getCustomRender?(props: NSARouterMakerProps): ReactNode | null;
-
-    // Which verifications are required before granting access
-    requirement: {
-        verification: {
-            email: boolean;
-            phone: boolean;
-        };
-    };
-}
-```
-
-### `NSARouterMakerProps`
-
-Injected into every routed component. Extends `NSRouterMakerProps` from `namirasoft-site-react`.
-
-```typescript
-interface NSARouterMakerProps {
-    product_id: string;
-    account: {
-        token_manager: TokenManager;
-        server: NamirasoftAccountServer;
-    };
-    url: {
-        getQueryStrings(): Record<string, string>;
-        getQuery(key: string): string | null;
-        getLink(path: string): string;
-        redirect(path: string): void;
-    };
-    renderer: {
-        renderOnNSALayout(children: ReactNode): ReactNode;
-    };
-    // ... inherited from NSRouterMakerProps
-}
-```
-
-### `IEntityInfo<EntityType, EntityTypeInput>`
-
-Defines everything needed to build a list/view/edit page for an entity:
-
-```typescript
-interface IEntityInfo<EntityType, EntityTypeInput> {
-    product_id: string;
-    name: string;
-    tables: { table: BaseMetaTable; required: boolean }[];
-
-    server: {
-        value_list(column: string, table: string, ...): Promise<string[]>;
-        get(id: string): Promise<EntityType>;
-        list(query: any): Promise<EntityType[]>;
-        create(input: EntityTypeInput): Promise<EntityType>;
-        update(id: string, input: EntityTypeInput): Promise<EntityType>;
-        delete(id: string): Promise<EntityType>;
-    };
-
-    client: {
-        getListURL(): string;
-        getNewURL(): string;
-        getCopyURL(row: EntityType): string;
-        getEditURL(row: EntityType): string;
-        getViewURL(row: EntityType): string;
-        getColumns(): ColumnDefinition[];
-        onCreate?(row: EntityType): void;
-        onUpdate?(row: EntityType): void;
-        onSuccess?(row: EntityType): void;
-        getMenus?(row: EntityType): MenuItem[];
-    };
-}
-```
-
-### `CTFRow`
-
-Custom Table Fields structure attached to entities that support dynamic field definitions:
-
-```typescript
-interface CTFRow {
-    categories: EntityCategoryInputRow[];
-    fields:     EntityFieldInputRow[];
-    tags:       EntityTagInputRow[];
-}
-```
-
----
-
-## Router Authentication Flow
-
-`NSARouterMaker` automatically routes the user through these states in order:
-
-1. **Not authenticated** → renders `NSALoginPage` (opens OAuth popup via `NamirasoftAccountClient`)
-2. **Banned** → renders error; `onRenderOnLogout(props, true)` is called
-3. **Consent outdated** → renders `NSAConsentPage`
-4. **Email not verified** (if `requirement.verification.email`) → renders `NSAEmailVerificationPage`
-5. **Phone not verified** (if `requirement.verification.phone`) → renders `NSAPhoneVerificationPage`
-6. **All checks pass** → calls `onRenderOnLogin(props)`
-
----
-
-## Components — Details
-
-### `NSALayout`
-
-Root layout for all authenticated pages. Wraps content and mounts:
-- Top header with icon buttons for messages, access, workspaces, products, and user
-- `NSAMasterMenu` sidebar
-- `NSAAccessListDialog`, `NSAMessageListDialog`, `NSAProductListDialog`, `NSAWorkspaceListDialog`, `NSAUserDialog`
-- Delete confirmation dialog
-- Message count polling
-
-Props include the full `NSARouterMakerProps` plus section state managers for list/edit/view.
-
-### `NSASectionList`
-
-Table-based listing with:
-- Server-driven column schema
-- Client-side column override (custom renderers, formatters)
-- Multi-select checkboxes
-- Filter/sort query params
-- Action menus per row
-- Custom mode rendering (e.g. search-and-select mode)
-
-### `NSASectionEdit`
-
-Form for create and update:
-- Tab-based field groups (`NSASectionEditTabPage` per tab)
-- Validation from server schema
-- Handles create vs update automatically
-
-### `NSASectionView`
-
-Read-only detail page:
-- Tab-based layout (`NSASectionViewTabPage` per tab)
-- `NSASectionViewTabMore` for overflow tabs
-- Optional hooks before/after render
-
-### `NSBoxSecret`
-
-Encrypted input for passwords, API keys, or tokens:
-- Toggle between masked and plain text
-- Save value to Secret service (returns an ID)
-- Reference existing secret by ID
-- Handles encryption/decryption automatically
-
-### `NSLabelSecret`
-
-Display label for encrypted secrets:
-- Shows masked value by default
-- Decrypts and reveals on toggle
-- Reads from Secret service by ID
-
-### `NSAMasterMenu`
-
-Sidebar navigation:
-- Hierarchical menu items from `namirasoft-api-link`
-- Debounced search filter
-- Collapse/expand toggle (state persisted in `NSACacheService`)
-
-### `NSAMessageListDialog`
-
-- Fetches up to 4 unread messages
-- Mark all as seen button
-- Opens full message in new window
-- Integrates with message count badge in header
-
-### `NSAAccessListDialog`
-
-- Lists incoming permissions (accounts that can act as the user)
-- Switch to an impersonated account
-- Shows who is currently being impersonated
-
-### `NSAWorkspaceListDialog`
-
-- Lists all workspaces for the current product
-- Highlights default and current workspace
-- Switching workspace triggers page reload
-
-### `PaymentRequired`
-
-Wraps content and checks subscription status. If not subscribed:
-- Shows payment offer
-- Opens payment URL with return callback
-- Blocks child content until subscription confirmed
-
-### `SecretFormatter`
-
-A table column formatter factory:
-
-```typescript
-SecretFormatter(width?: number): ColumnFormatter
-// Returns a formatter that decrypts and masks secret cell values.
-```
-
----
-
-## Utilities
-
-### `Actions` — static menu item builders
-
-```typescript
-Actions.apply(onClick: () => void): MenuItem   // Apply button
-Actions._new(): MenuItem                        // "New" — navigate to create page
-Actions.list(): MenuItem                        // "List" — navigate to list page
-Actions.view(): MenuItem                        // "View" — view selected entity
-Actions.viewHistory(): MenuItem                 // "History" — view entity history
-Actions.copy(): MenuItem                        // "Copy" — copy selected entity
-Actions.edit(): MenuItem                        // "Edit" — edit selected entity
-Actions.delete(): MenuItem                      // "Delete" — trigger delete confirm dialog
-```
-
-### `CFTUtil` — custom field helpers
-
-```typescript
-CFTUtil.get(name: string, row: any): CTFRow
-// Extract CTF data from an entity row.
-
-CFTUtil.set(name: string, row: any, ctf: CTFRow): void
-// Store CTF data back into a row.
-```
-
-### `NSACacheService` — cached API calls
-
-All caches use `namirasoft-core` storage. These are called internally by components but can be used directly:
-
-```typescript
-NSACacheService.getProducts(server, current_product_id)
-// Cache: 7 days. Fetches all products, excludes current.
-
-NSACacheService.getConsent(server, product_id, user_id)
-// Cache: 7 days. Fetches user consent for a product.
-
-NSACacheService.getFilterLinks(server, product_id, search?)
-// Cache: 7 days. Fetches navigation links for sidebar.
-
-NSACacheService.getMasterMenuStatus()
-// Cache: 30 days. Persists sidebar open/closed state.
-```
-
----
-
-## Usage Pattern — Setting up a Console
-
-### 1 — Configure the router
-
-```tsx
-// src/index.tsx
-import { BrowserRouter } from 'react-router-dom';
-import { NSARouterMaker, NSARouterMakerConfig } from 'namirasoft-account-react';
-
-const config: NSARouterMakerConfig = {
-    requirement: { verification: { email: true, phone: false } },
-    onRenderOnLogout: (props, banned) => <div>Please log in</div>,
-    renderOnNSALayout: (props, children) => (
-        <NSALayout {...props}>{children}</NSALayout>
-    ),
-    onRenderOnLogin: (props) => <MyAppRoutes {...props} />,
-};
-
-const router = new NSARouterMaker('my-product-id', config);
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-    <BrowserRouter>
-        <router.Component />
-    </BrowserRouter>
-);
-```
-
-### 2 — Define an entity
-
-```typescript
-import { IEntityInfo } from 'namirasoft-account-react';
-
-const ProjectEntity: IEntityInfo<ProjectRow, ProjectInputRow> = {
-    product_id: 'my-product-id',
-    name: 'Project',
-    tables: [{ table: ProjectTable, required: true }],
-    server: {
-        get: (id) => projectServer.get(id),
-        list: (query) => projectServer.list(query),
-        create: (input) => projectServer.create(input),
-        update: (id, input) => projectServer.update(id, input),
-        delete: (id) => projectServer.delete(id),
-        value_list: (col, table, ...) => projectServer.valueList(col, table),
-    },
-    client: {
-        getListURL: () => '/projects',
-        getNewURL: () => '/projects/new',
-        getEditURL: (row) => `/projects/${row.id}/edit`,
-        getViewURL: (row) => `/projects/${row.id}`,
-        getCopyURL: (row) => `/projects/${row.id}/copy`,
-        getColumns: () => [ /* column definitions */ ],
-    },
-};
-```
-
-### 3 — Use layout sections
-
-```tsx
-// List page
-<NSASectionList entity={ProjectEntity} props={routerProps} />
-
-// Edit page
-<NSASectionEdit entity={ProjectEntity} props={routerProps} id={params.id} />
-
-// View page
-<NSASectionView entity={ProjectEntity} props={routerProps} id={params.id} />
-```
-
-### 4 — Use secret fields
-
-```tsx
-// In a form
-<NSBoxSecret
-    label="API Key"
-    value={form.api_key}
-    onChange={(val) => setForm({ ...form, api_key: val })}
-    server={secretServer}
-/>
-
-// In a detail view
-<NSLabelSecret value={row.api_key} server={secretServer} />
-
-// In a table column
-columns.push({
-    field: 'api_key',
-    formatter: SecretFormatter(200),
-});
-```
-
-### 5 — Subscription gate
-
-```tsx
-<PaymentRequired product_id="my-product-id" props={routerProps}>
-    <PremiumFeatureComponent />
-</PaymentRequired>
-```
-
----
-
-## Source Files
-
-| File | Responsibility |
-|------|---------------|
-| `src/main.ts` | All public exports |
-| `src/NSARouterMaker.tsx` | Auth-state router |
-| `src/NSARouterMakerConfig.ts` | Router config interface |
-| `src/NSARouterMakerProps.ts` | Injected props interface |
-| `src/IEntityInfo.ts` | Entity definition interface |
-| `src/NSACacheService.ts` | Cached API calls |
-| `src/CTFRow.ts` | CTF data structure |
-| `src/UseParams.tsx` | URL params hook wrapper |
-| `src/components/NSALayout.tsx` | Root layout |
-| `src/components/NSAMasterMenu.tsx` | Sidebar navigation |
-| `src/components/NSAAccessListDialog.tsx` | Access/impersonation dialog |
-| `src/components/NSAMessageListDialog.tsx` | Message center dialog |
-| `src/components/NSAProductListDialog.tsx` | Product picker dialog |
-| `src/components/NSAWorkspaceListDialog.tsx` | Workspace switcher dialog |
-| `src/components/NSAUserDialog.tsx` | User profile dialog |
-| `src/components/NSBoxSecret.tsx` | Secret input |
-| `src/components/NSLabelSecret.tsx` | Secret display label |
-| `src/layouts/NSALayout.tsx` | Layout with all dialogs |
-| `src/layouts/NSASectionList.tsx` | Entity list section |
-| `src/layouts/NSASectionEdit.tsx` | Entity edit section |
-| `src/layouts/NSASectionView.tsx` | Entity view section |
-| `src/layouts/NSASectionViewTabPage.tsx` | View tab |
-| `src/layouts/NSASectionEditTabPage.tsx` | Edit tab |
-| `src/layouts/Actions.ts` | Menu action builders |
-| `src/layouts/CFTUtil.ts` | CTF get/set helpers |
-| `src/formatters/SecretFormatter.tsx` | Table column secret formatter |
-| `src/pages/NSALoginPage.tsx` | Login page |
-| `src/pages/NSAConsentPage.tsx` | Consent page |
-| `src/pages/NSAEmailVerificationPage.tsx` | Email verification |
-| `src/pages/NSAPhoneVerificationPage.tsx` | Phone verification |
-| `src/pages/NSAVerificationPage.tsx` | Verification base |
-| `src/pages/NSAHomePage.tsx` | Home/product grid |
-| `src/pages/PaymentRequired.tsx` | Payment gate |
-| `.env.template` | Required environment variables |
+---
+name: namirasoft-account-react
+description: Use when working with the namirasoft-account-react npm package — a React UI library providing auth flows, workspace/access/product dialogs, CRUD layouts (list/view/edit), secret field components, and an auth-gated router for Namirasoft Console frontends.
+triggers:
+  - namirasoft-account-react
+  - NSARouterMaker
+  - NSALayout
+  - NSASectionList
+  - NSASectionEdit
+  - NSASectionView
+  - NSBoxSecret
+  - account react
+---
+
+# namirasoft-account-react
+
+**Package:** `namirasoft-account-react` v1.4.413  
+**Purpose:** Enterprise React UI library for Namirasoft products. Provides the complete authentication flow (login, verification, consent), workspace/access/product management dialogs, generic CRUD layouts (list/view/edit), secret field components, and a router framework that gates pages behind authentication state.  
+**Stack:** React 18, TypeScript, React Router 7, Bootstrap 5, CSS Modules.
+
+---
+
+## When to use this package
+
+Use `namirasoft-account-react` in every **frontend Console** (React SPA) that needs to:
+- Authenticate users via the Namirasoft Account service
+- Enforce email and phone verification before access
+- Show a consent/terms page when policies change
+- Provide workspace switching, access (impersonation), and product navigation
+- Render generic entity list / view / edit pages
+- Store and display sensitive secrets (encrypted fields)
+- Poll and display in-app messages
+
+---
+
+## Environment Variables
+
+Copy `.env.template` and fill in all values before running:
+
+```bash
+REACT_APP_BASE_PATH=""                                          # sub-path if not at root
+REACT_APP_BASE_URL_ACCESS="https://access.namirasoft.com/api/v1"
+REACT_APP_BASE_URL_ACCOUNT="https://account.namirasoft.com/api/v1"
+REACT_APP_BASE_URL_ACCOUNT_CONSOLE="https://account.namirasoft.com"
+REACT_APP_BASE_URL_API_LINK="https://namirasoft.com/api/link/v1"
+REACT_APP_BASE_URL_API_PRODUCT="https://namirasoft.com/api/product/v1"
+REACT_APP_BASE_URL_FIELD="https://field.namirasoft.com/api/v1"
+REACT_APP_BASE_URL_HISTORY="https://history.namirasoft.com/api/v1"
+REACT_APP_BASE_URL_HISTORY_CONSOLE="https://history.namirasoft.com"
+REACT_APP_BASE_URL_MESSAGE="https://message.namirasoft.com/api/v1"
+REACT_APP_BASE_URL_MESSAGE_CONSOLE="https://message.namirasoft.com"
+REACT_APP_BASE_URL_SECRET="https://secret.namirasoft.com/api/v1"
+REACT_APP_BASE_URL_WORKSPACE="https://workspace.namirasoft.com/api/v1"
+```
+
+---
+
+## Exports (`main.ts`)
+
+### Components
+
+| Export | File | Description |
+|--------|------|-------------|
+| `NSAAccessListDialog` | `components/NSAAccessListDialog.tsx` | Incoming permissions / impersonation switcher |
+| `NSAMessageListDialog` | `components/NSAMessageListDialog.tsx` | Unread message center (max 4, mark-all-seen) |
+| `NSAProductListDialog` | `components/NSAProductListDialog.tsx` | Searchable product list |
+| `NSAWorkspaceListDialog` | `components/NSAWorkspaceListDialog.tsx` | Workspace switcher |
+| `NSAUserDialog` | `components/NSAUserDialog.tsx` | User profile and settings dialog |
+| `NSAMasterMenu` | `components/NSAMasterMenu.tsx` | Sidebar navigation with search and collapse |
+| `NSAMasterMenuItem` | `components/NSAMasterMenuItem.tsx` | Individual menu item |
+| `NSBoxSecret` | `components/NSBoxSecret.tsx` | Secret/encrypted value input |
+| `NSLabelSecret` | `components/NSLabelSecret.tsx` | Secret/encrypted value display label |
+
+### Layouts
+
+| Export | File | Description |
+|--------|------|-------------|
+| `NSALayout` | `layouts/NSALayout.tsx` | Root layout: header, master menu, all dialogs, delete confirm |
+| `NSASectionList` | `layouts/NSASectionList.tsx` | Entity table with filter/sort/select |
+| `NSASectionEdit` | `layouts/NSASectionEdit.tsx` | Entity create/update form (tabbed) |
+| `NSASectionView` | `layouts/NSASectionView.tsx` | Entity read-only detail view (tabbed) |
+| `NSASectionViewTabPage` | `layouts/NSASectionViewTabPage.tsx` | Single tab inside `NSASectionView` |
+| `NSASectionEditTabPage` | `layouts/NSASectionEditTabPage.tsx` | Single tab inside `NSASectionEdit` |
+
+### Pages
+
+| Export | File | Description |
+|--------|------|-------------|
+| `NSALoginPage` | `pages/NSALoginPage.tsx` | Login page — opens OAuth flow |
+| `NSAConsentPage` | `pages/NSAConsentPage.tsx` | Terms/privacy acceptance |
+| `NSAEmailVerificationPage` | `pages/NSAEmailVerificationPage.tsx` | Email verification (send + verify code) |
+| `NSAPhoneVerificationPage` | `pages/NSAPhoneVerificationPage.tsx` | Phone verification (enter number + SMS code) |
+| `NSAVerificationPage` | `pages/NSAVerificationPage.tsx` | Generic verification base component |
+| `NSAHomePage` | `pages/NSAHomePage.tsx` | Product grid home page |
+| `PaymentRequired` | `pages/PaymentRequired.tsx` | Subscription gate wrapper |
+
+### Formatters
+
+| Export | File | Description |
+|--------|------|-------------|
+| `SecretFormatter` | `formatters/SecretFormatter.tsx` | Table cell formatter for encrypted secret values |
+
+### Router & Config
+
+| Export | File | Description |
+|--------|------|-------------|
+| `NSARouterMaker` | `NSARouterMaker.tsx` | Auth-aware router — gates pages by login/verification state |
+| `NSARouterMakerProps` | `NSARouterMakerProps.ts` | Props injected into routed components |
+| `NSARouterMakerConfig` | `NSARouterMakerConfig.ts` | Config callbacks for `NSARouterMaker` |
+
+### Utilities
+
+| Export | File | Description |
+|--------|------|-------------|
+| `IEntityInfo` | `IEntityInfo.ts` | Entity definition interface for CRUD pages |
+| `Actions` | `layouts/Actions.ts` | Menu action builder (new, view, edit, delete, …) |
+| `CFTUtil` | `layouts/CFTUtil.ts` | Custom Table Fields get/set helpers |
+| `UseParams` | `UseParams.tsx` | Hook wrapper for URL params |
+
+---
+
+## Key Types & Interfaces
+
+### `NSARouterMakerConfig`
+
+Callbacks that configure the router's rendering behaviour:
+
+```typescript
+interface NSARouterMakerConfig {
+    // Called when user is authenticated and all verifications pass
+    onRenderOnLogin(props: NSARouterMakerProps): ReactNode;
+
+    // Called when user is not authenticated (banned = account suspended)
+    onRenderOnLogout(props: NSARouterMakerProps, banned: boolean): ReactNode;
+
+    // Wraps any page in NSALayout (called for all authenticated renders)
+    renderOnNSALayout(props: NSARouterMakerProps, children: ReactNode): ReactNode;
+
+    // Optional: custom render override
+    getCustomRender?(props: NSARouterMakerProps): ReactNode | null;
+
+    // Which verifications are required before granting access
+    requirement: {
+        verification: {
+            email: boolean;
+            phone: boolean;
+        };
+    };
+}
+```
+
+### `NSARouterMakerProps`
+
+Injected into every routed component. Extends `NSRouterMakerProps` from `namirasoft-site-react`.
+
+```typescript
+interface NSARouterMakerProps {
+    product_id: string;
+    account: {
+        token_manager: TokenManager;
+        server: NamirasoftAccountServer;
+    };
+    url: {
+        getQueryStrings(): Record<string, string>;
+        getQuery(key: string): string | null;
+        getLink(path: string): string;
+        redirect(path: string): void;
+    };
+    renderer: {
+        renderOnNSALayout(children: ReactNode): ReactNode;
+    };
+    // ... inherited from NSRouterMakerProps
+}
+```
+
+### `IEntityInfo<EntityType, EntityTypeInput>`
+
+Defines everything needed to build a list/view/edit page for an entity:
+
+```typescript
+interface IEntityInfo<EntityType, EntityTypeInput> {
+    product_id: string;
+    name: string;
+    tables: { table: BaseMetaTable; required: boolean }[];
+
+    server: {
+        value_list(column: string, table: string, ...): Promise<string[]>;
+        get(id: string): Promise<EntityType>;
+        list(query: any): Promise<EntityType[]>;
+        create(input: EntityTypeInput): Promise<EntityType>;
+        update(id: string, input: EntityTypeInput): Promise<EntityType>;
+        delete(id: string): Promise<EntityType>;
+    };
+
+    client: {
+        getListURL(): string;
+        getNewURL(): string;
+        getCopyURL(row: EntityType): string;
+        getEditURL(row: EntityType): string;
+        getViewURL(row: EntityType): string;
+        getColumns(): ColumnDefinition[];
+        onCreate?(row: EntityType): void;
+        onUpdate?(row: EntityType): void;
+        onSuccess?(row: EntityType): void;
+        getMenus?(row: EntityType): MenuItem[];
+    };
+}
+```
+
+### `CTFRow`
+
+Custom Table Fields structure attached to entities that support dynamic field definitions:
+
+```typescript
+interface CTFRow {
+    categories: EntityCategoryInputRow[];
+    fields:     EntityFieldInputRow[];
+    tags:       EntityTagInputRow[];
+}
+```
+
+---
+
+## Router Authentication Flow
+
+`NSARouterMaker` automatically routes the user through these states in order:
+
+1. **Not authenticated** → renders `NSALoginPage` (opens OAuth popup via `NamirasoftAccountClient`)
+2. **Banned** → renders error; `onRenderOnLogout(props, true)` is called
+3. **Consent outdated** → renders `NSAConsentPage`
+4. **Email not verified** (if `requirement.verification.email`) → renders `NSAEmailVerificationPage`
+5. **Phone not verified** (if `requirement.verification.phone`) → renders `NSAPhoneVerificationPage`
+6. **All checks pass** → calls `onRenderOnLogin(props)`
+
+---
+
+## Components — Details
+
+### `NSALayout`
+
+Root layout for all authenticated pages. Wraps content and mounts:
+- Top header with icon buttons for messages, access, workspaces, products, and user
+- `NSAMasterMenu` sidebar
+- `NSAAccessListDialog`, `NSAMessageListDialog`, `NSAProductListDialog`, `NSAWorkspaceListDialog`, `NSAUserDialog`
+- Delete confirmation dialog
+- Message count polling
+
+Props include the full `NSARouterMakerProps` plus section state managers for list/edit/view.
+
+### `NSASectionList`
+
+Table-based listing with:
+- Server-driven column schema
+- Client-side column override (custom renderers, formatters)
+- Multi-select checkboxes
+- Filter/sort query params
+- Action menus per row
+- Custom mode rendering (e.g. search-and-select mode)
+
+### `NSASectionEdit`
+
+Form for create and update:
+- Tab-based field groups (`NSASectionEditTabPage` per tab)
+- Validation from server schema
+- Handles create vs update automatically
+
+### `NSASectionView`
+
+Read-only detail page:
+- Tab-based layout (`NSASectionViewTabPage` per tab)
+- `NSASectionViewTabMore` for overflow tabs
+- Optional hooks before/after render
+
+### `NSBoxSecret`
+
+Encrypted input for passwords, API keys, or tokens:
+- Toggle between masked and plain text
+- Save value to Secret service (returns an ID)
+- Reference existing secret by ID
+- Handles encryption/decryption automatically
+
+### `NSLabelSecret`
+
+Display label for encrypted secrets:
+- Shows masked value by default
+- Decrypts and reveals on toggle
+- Reads from Secret service by ID
+
+### `NSAMasterMenu`
+
+Sidebar navigation:
+- Hierarchical menu items from `namirasoft-api-link`
+- Debounced search filter
+- Collapse/expand toggle (state persisted in `NSACacheService`)
+
+### `NSAMessageListDialog`
+
+- Fetches up to 4 unread messages
+- Mark all as seen button
+- Opens full message in new window
+- Integrates with message count badge in header
+
+### `NSAAccessListDialog`
+
+- Lists incoming permissions (accounts that can act as the user)
+- Switch to an impersonated account
+- Shows who is currently being impersonated
+
+### `NSAWorkspaceListDialog`
+
+- Lists all workspaces for the current product
+- Highlights default and current workspace
+- Switching workspace triggers page reload
+
+### `PaymentRequired`
+
+Wraps content and checks subscription status. If not subscribed:
+- Shows payment offer
+- Opens payment URL with return callback
+- Blocks child content until subscription confirmed
+
+### `SecretFormatter`
+
+A table column formatter factory:
+
+```typescript
+SecretFormatter(width?: number): ColumnFormatter
+// Returns a formatter that decrypts and masks secret cell values.
+```
+
+---
+
+## Utilities
+
+### `Actions` — static menu item builders
+
+```typescript
+Actions.apply(onClick: () => void): MenuItem   // Apply button
+Actions._new(): MenuItem                        // "New" — navigate to create page
+Actions.list(): MenuItem                        // "List" — navigate to list page
+Actions.view(): MenuItem                        // "View" — view selected entity
+Actions.viewHistory(): MenuItem                 // "History" — view entity history
+Actions.copy(): MenuItem                        // "Copy" — copy selected entity
+Actions.edit(): MenuItem                        // "Edit" — edit selected entity
+Actions.delete(): MenuItem                      // "Delete" — trigger delete confirm dialog
+```
+
+### `CFTUtil` — custom field helpers
+
+```typescript
+CFTUtil.get(name: string, row: any): CTFRow
+// Extract CTF data from an entity row.
+
+CFTUtil.set(name: string, row: any, ctf: CTFRow): void
+// Store CTF data back into a row.
+```
+
+### `NSACacheService` — cached API calls
+
+All caches use `namirasoft-core` storage. These are called internally by components but can be used directly:
+
+```typescript
+NSACacheService.getProducts(server, current_product_id)
+// Cache: 7 days. Fetches all products, excludes current.
+
+NSACacheService.getConsent(server, product_id, user_id)
+// Cache: 7 days. Fetches user consent for a product.
+
+NSACacheService.getFilterLinks(server, product_id, search?)
+// Cache: 7 days. Fetches navigation links for sidebar.
+
+NSACacheService.getMasterMenuStatus()
+// Cache: 30 days. Persists sidebar open/closed state.
+```
+
+---
+
+## Usage Pattern — Setting up a Console
+
+### 1 — Configure the router
+
+```tsx
+// src/index.tsx
+import { BrowserRouter } from 'react-router-dom';
+import { NSARouterMaker, NSARouterMakerConfig } from 'namirasoft-account-react';
+
+const config: NSARouterMakerConfig = {
+    requirement: { verification: { email: true, phone: false } },
+    onRenderOnLogout: (props, banned) => <div>Please log in</div>,
+    renderOnNSALayout: (props, children) => (
+        <NSALayout {...props}>{children}</NSALayout>
+    ),
+    onRenderOnLogin: (props) => <MyAppRoutes {...props} />,
+};
+
+const router = new NSARouterMaker('my-product-id', config);
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+    <BrowserRouter>
+        <router.Component />
+    </BrowserRouter>
+);
+```
+
+### 2 — Define an entity
+
+```typescript
+import { IEntityInfo } from 'namirasoft-account-react';
+
+const ProjectEntity: IEntityInfo<ProjectRow, ProjectInputRow> = {
+    product_id: 'my-product-id',
+    name: 'Project',
+    tables: [{ table: ProjectTable, required: true }],
+    server: {
+        get: (id) => projectServer.get(id),
+        list: (query) => projectServer.list(query),
+        create: (input) => projectServer.create(input),
+        update: (id, input) => projectServer.update(id, input),
+        delete: (id) => projectServer.delete(id),
+        value_list: (col, table, ...) => projectServer.valueList(col, table),
+    },
+    client: {
+        getListURL: () => '/projects',
+        getNewURL: () => '/projects/new',
+        getEditURL: (row) => `/projects/${row.id}/edit`,
+        getViewURL: (row) => `/projects/${row.id}`,
+        getCopyURL: (row) => `/projects/${row.id}/copy`,
+        getColumns: () => [ /* column definitions */ ],
+    },
+};
+```
+
+### 3 — Use layout sections
+
+```tsx
+// List page
+<NSASectionList entity={ProjectEntity} props={routerProps} />
+
+// Edit page
+<NSASectionEdit entity={ProjectEntity} props={routerProps} id={params.id} />
+
+// View page
+<NSASectionView entity={ProjectEntity} props={routerProps} id={params.id} />
+```
+
+### 4 — Use secret fields
+
+```tsx
+// In a form
+<NSBoxSecret
+    label="API Key"
+    value={form.api_key}
+    onChange={(val) => setForm({ ...form, api_key: val })}
+    server={secretServer}
+/>
+
+// In a detail view
+<NSLabelSecret value={row.api_key} server={secretServer} />
+
+// In a table column
+columns.push({
+    field: 'api_key',
+    formatter: SecretFormatter(200),
+});
+```
+
+### 5 — Subscription gate
+
+```tsx
+<PaymentRequired product_id="my-product-id" props={routerProps}>
+    <PremiumFeatureComponent />
+</PaymentRequired>
+```
+
+---
+
+## Source Files
+
+| File | Responsibility |
+|------|---------------|
+| `src/main.ts` | All public exports |
+| `src/NSARouterMaker.tsx` | Auth-state router |
+| `src/NSARouterMakerConfig.ts` | Router config interface |
+| `src/NSARouterMakerProps.ts` | Injected props interface |
+| `src/IEntityInfo.ts` | Entity definition interface |
+| `src/NSACacheService.ts` | Cached API calls |
+| `src/CTFRow.ts` | CTF data structure |
+| `src/UseParams.tsx` | URL params hook wrapper |
+| `src/components/NSALayout.tsx` | Root layout |
+| `src/components/NSAMasterMenu.tsx` | Sidebar navigation |
+| `src/components/NSAAccessListDialog.tsx` | Access/impersonation dialog |
+| `src/components/NSAMessageListDialog.tsx` | Message center dialog |
+| `src/components/NSAProductListDialog.tsx` | Product picker dialog |
+| `src/components/NSAWorkspaceListDialog.tsx` | Workspace switcher dialog |
+| `src/components/NSAUserDialog.tsx` | User profile dialog |
+| `src/components/NSBoxSecret.tsx` | Secret input |
+| `src/components/NSLabelSecret.tsx` | Secret display label |
+| `src/layouts/NSALayout.tsx` | Layout with all dialogs |
+| `src/layouts/NSASectionList.tsx` | Entity list section |
+| `src/layouts/NSASectionEdit.tsx` | Entity edit section |
+| `src/layouts/NSASectionView.tsx` | Entity view section |
+| `src/layouts/NSASectionViewTabPage.tsx` | View tab |
+| `src/layouts/NSASectionEditTabPage.tsx` | Edit tab |
+| `src/layouts/Actions.ts` | Menu action builders |
+| `src/layouts/CFTUtil.ts` | CTF get/set helpers |
+| `src/formatters/SecretFormatter.tsx` | Table column secret formatter |
+| `src/pages/NSALoginPage.tsx` | Login page |
+| `src/pages/NSAConsentPage.tsx` | Consent page |
+| `src/pages/NSAEmailVerificationPage.tsx` | Email verification |
+| `src/pages/NSAPhoneVerificationPage.tsx` | Phone verification |
+| `src/pages/NSAVerificationPage.tsx` | Verification base |
+| `src/pages/NSAHomePage.tsx` | Home/product grid |
+| `src/pages/PaymentRequired.tsx` | Payment gate |
+| `.env.template` | Required environment variables |