@naniteninja/profile-comparison-lib 1.0.3 → 1.0.4

package/README.md

@@ -1,8 +1,8 @@
 # Profile Comparison Library
 
-Angular library that renders a side-by-side profile comparison (two profile images, a central draggable shape, and aligned interest lists). It is a **thin client**: you provide a backend URL; the library sends user config to your backend and displays the payload it returns. No API keys or key-entry modals in the library.
+Angular library that renders a side-by-side profile comparison (two profile images, a central draggable shape, and semantically aligned interest lists). It is a **thin client** — the library sends user config to a backend and displays the payload it returns. No API keys or key-entry modals live in the library.
 
-**You need a backend** that implements the profile comparison API (e.g. the **profile-comparison-server** repo). Provide its base URL via `PROFILE_COMPARISON_API_BASE_URL`. If not provided, the component shows **"Configure backend"**.
+**You need a backend** that implements the profile comparison API (e.g. the **profile-comparison-server** repo). By default the component points at the real deployed backend. Set `[backendMode]="BackendMode.Mock"` to use `localhost:3000` during development.
 
 ---
 
@@ -11,255 +11,150 @@ Angular library that renders a side-by-side profile comparison (two profile imag
 ### 1. Install
 
 ```bash
-npm install @naniteninja/profile-comparison-lib @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
+npm install @naniteninja/profile-comparison-lib
 ```
 
-### 2. Wire up the module and backend URL
+### 2. Wire up the module
 
 ```typescript
 import { NgModule } from '@angular/core';
 import { HttpClientModule } from '@angular/common/http';
-import {
-  ProfileComparisonLibModule,
-  PROFILE_COMPARISON_API_BASE_URL,
-} from '@naniteninja/profile-comparison-lib';
+import { ProfileComparisonLibModule } from '@naniteninja/profile-comparison-lib';
 
 @NgModule({
   imports: [HttpClientModule, ProfileComparisonLibModule],
-  providers: [
-    { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'http://localhost:3000/api' },
-  ],
 })
 export class AppModule {}
 ```
 
 ### 3. Add the component to a template
 
+Minimal — uses the real deployed backend with all edges faded:
+
+```html
+<lib-profile-comparison [config]="profileConfig"></lib-profile-comparison>
+```
+
+During development, point at a local backend:
+
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendMode]="BackendMode.Mock"
+></lib-profile-comparison>
+```
+
+Or supply a fully custom URL (overrides `backendMode`):
+
 ```html
 <lib-profile-comparison
   [config]="profileConfig"
-  [fadeAllEdges]="false"
+  [backendUrl]="'https://my-custom-api.example.com/api'"
+></lib-profile-comparison>
+```
+
+Full example with all inputs and outputs:
+
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendMode]="backendMode"
+  [backendUrl]="customUrl"
+  [fadeAllEdges]="true"
   (matrixDataChange)="onMatrixData($event)"
   (rawLLMOutputChange)="onRawLLM($event)"
   (viewProfileClick)="onViewProfile($event)"
 ></lib-profile-comparison>
 ```
 
-### 4. Provide config data in the component
+### 4. Component class
 
 ```typescript
-import { IProfileConfig } from '@naniteninja/profile-comparison-lib';
-
-profileConfig: IProfileConfig = {
-  person1Interests: [
-    'Gaming', 'Programming', 'AI/ML', 'Startups',
-    'Blockchain', 'Cybersecurity', 'Web Development', 'Data Science',
-  ],
-  person2Interests: [
-    'AI machine learning', 'Mobile Games', 'Hardware',
-    'Data Science', 'Entrepreneurship', 'Design Thinking', 'Blockchain',
-  ],
-  person3Interests: ['Board Games', 'Machine Learning'],
-  user1Image: './assets/user1.jpg',   // data URL or asset path
-  user2Image: './assets/user2.jpg',
-};
-
-onMatrixData(data: any) { console.log('Matrix:', data); }
-onRawLLM(raw: string)   { console.log('LLM:', raw); }
-onViewProfile(e: { side: 'left' | 'right' }) {
-  console.log('View profile:', e.side);
+import { Component } from '@angular/core';
+import { IProfileConfig, IMatrixData, BackendMode } from '@naniteninja/profile-comparison-lib';
+
+@Component({ /* ... */ })
+export class AppComponent {
+  readonly BackendMode = BackendMode; // expose enum to template
+
+  backendMode = BackendMode.Real;
+  customUrl: string | null = null;
+
+  profileConfig: IProfileConfig = {
+    person1Interests: [
+      'Gaming', 'Programming', 'AI/ML', 'Startups',
+      'Blockchain', 'Cybersecurity', 'Web Development', 'Data Science',
+    ],
+    person2Interests: [
+      'AI machine learning', 'Mobile Games', 'Hardware',
+      'Data Science', 'Entrepreneurship', 'Design Thinking', 'Blockchain',
+    ],
+    person3Interests: ['Board Games', 'Machine Learning'],
+    user1Image: './assets/user1.jpg',   // data-URL or asset path
+    user2Image: './assets/user2.jpg',
+  };
+
+  onMatrixData(data: IMatrixData) { console.log('Matrix:', data); }
+  onRawLLM(raw: string)          { console.log('LLM:', raw); }
+  onViewProfile(e: { side: 'left' | 'right' }) {
+    console.log('View profile:', e.side);
+  }
 }
 ```
 
-### 5. Start the backend and run
+### 5. Run
 
 ```bash
-# Terminal 1 — backend (profile-comparison-server repo)
-cd ../profile-comparison-server && npm install && npm start
-
-# Terminal 2 — your app
 ng serve
 ```
 
-The component renders two profile images with a draggable center shape, semantically aligned interest lists on each side, and a "View Profile" link per side. If the backend is unreachable, a **"Configure backend"** message appears instead.
-
----
-
-## Quickstart
-
-1. **Install the package and peer dependencies** (including TensorFlow; required for Vite and other bundlers):
-
-   ```bash
-   npm install @naniteninja/profile-comparison-lib @angular/core@^20 @angular/common@^20 @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
-   ```
-
-2. **Provide the backend URL**
-
-   In `app.config.ts` (or `AppModule`):
-
-   ```typescript
-   import { PROFILE_COMPARISON_API_BASE_URL } from '@naniteninja/profile-comparison-lib';
-
-   providers: [
-     { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
-   ]
-   ```
-
-   Or with a factory (e.g. runtime toggle between backends):
-
-   ```typescript
-   providers: [{
-     provide: PROFILE_COMPARISON_API_BASE_URL,
-     useFactory: (backendUrl: BackendUrlService) => () => backendUrl.getBaseUrl(),
-     deps: [BackendUrlService],
-   }]
-   ```
-
-3. **Use the component**
-
-   Import the module and add the component to a template:
-
-   ```typescript
-   import { ProfileComparisonLibModule } from '@naniteninja/profile-comparison-lib';
-   ```
+If using `BackendMode.Mock`, start the local backend first:
 
-   ```html
-   <lib-profile-comparison [config]="config"></lib-profile-comparison>
-   ```
-
----
-
-## What the element looks like
-
-When you use `<lib-profile-comparison>` in another Angular app you get:
-
-- **Side-by-side profile comparison**: two profile images (left and right) with a central draggable “shape” and aligned interest lists between them.
-- **Main regions**: left image, right image, center shape with text, loading indicator when a request is in progress.
-- **Action**: “View Profile” on each side; the component emits `viewProfileClick` with `{ side: 'left' | 'right' }` so the host can route or act.
-
-No key-entry modals or API key inputs appear in the library; all keys and third-party API calls live on your backend.
-
----
-
-## Full setup (copy-paste)
-
-1. Create or open an Angular app (Angular ^20.0.0).
-
-2. Install the library and peer dependencies (TensorFlow is required for dependency optimization in Vite etc.):
-
-   ```bash
-   npm install @naniteninja/profile-comparison-lib @angular/core@^20 @angular/common@^20 @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
-   ```
-
-3. Add the backend URL provider in `app.config.ts`:
-
-   ```typescript
-   import { ApplicationConfig } from '@angular/core';
-   import { provideHttpClient } from '@angular/common/http';
-   import { PROFILE_COMPARISON_API_BASE_URL } from '@naniteninja/profile-comparison-lib';
-
-   export const appConfig: ApplicationConfig = {
-     providers: [
-       provideHttpClient(),
-       { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
-     ],
-   };
-   ```
-
-   Or in `AppModule`:
-
-   ```typescript
-   import { PROFILE_COMPARISON_API_BASE_URL } from '@naniteninja/profile-comparison-lib';
-
-   @NgModule({
-     providers: [
-       { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
-     ],
-   })
-   export class AppModule {}
-   ```
-
-4. Import the module where you use the component:
-
-   ```typescript
-   import { ProfileComparisonLibModule } from '@naniteninja/profile-comparison-lib';
-
-   @NgModule({
-     imports: [ProfileComparisonLibModule, ...],
-   })
-   export class YourModule {}
-   ```
-
-5. Add the component to a template with required `[config]`:
-
-   ```html
-   <lib-profile-comparison
-     [config]="config"
-     [fadeAllEdges]="fadeAllEdges"
-     (matrixDataChange)="onMatrixData($event)"
-     (rawLLMOutputChange)="onRawLLMOutput($event)"
-     (viewProfileClick)="onViewProfile($event)"
-   ></lib-profile-comparison>
-   ```
-
-6. Run the app and ensure your backend is reachable at the URL you provided.
+```bash
+cd ../profile-comparison-server && npm install && npm start   # listens on :3000
+```
 
 ---
 
-## Inputs and outputs
+## Inputs
 
-### Inputs
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `config` | `IProfileConfig` | *required* | Profile data (interests, images) for the comparison. |
+| `backendMode` | `BackendMode` | `BackendMode.Real` (0) | `Real` = deployed backend, `Mock` = `localhost:3000`. |
+| `backendUrl` | `string \| null` | `null` | When non-empty, overrides `backendMode` entirely. |
+| `fadeAllEdges` | `boolean` | `true` | Fade the outer edges of the profile area. |
 
-- **`config`** (required) — `IProfileConfig`:
+## Outputs
 
-  ```json
-  {
-    "person1Interests": ["Gaming", "Programming", "AI/ML"],
-    "person2Interests": ["AI machine learning", "Mobile Games", "Data Science"],
-    "person3Interests": ["Board Games", "Machine Learning"],
-    "user1Image": "data:image/jpeg;base64,...",
-    "user2Image": "data:image/jpeg;base64,..."
-  }
-  ```
+All outputs are optional — bind only what you need.
 
-  `user1Image` and `user2Image` can be data URLs or URLs; the library sends them to the backend as needed.
+| Output | Type | Description |
+|--------|------|-------------|
+| `matrixDataChange` | `IMatrixData` | Legend, headers, and rows for the similarity matrix. |
+| `rawLLMOutputChange` | `string` | Raw LLM output from the backend (if any). |
+| `viewProfileClick` | `{ side: 'left' \| 'right' }` | Emitted when the user clicks "View Profile". |
 
-- **`fadeAllEdges`** (optional) — `boolean`, default `false`. When true, fades the outer edges of the profile area.
+## BackendMode enum
 
-### Outputs
-
-- **`matrixDataChange`** — `IMatrixData`: legend, headers, and rows for the similarity matrix.
-
-  Example payload:
-
-  ```json
-  {
-    "legend": [{ "abbr": "Gam", "full": "Gaming" }, { "abbr": "Pro", "full": "Programming" }],
-    "headers": ["Gam", "Pro", "AI/ML"],
-    "rows": [
-      { "label": "Gam", "values": ["1.00", "0.2", "0.5"] },
-      { "label": "Pro", "values": ["0.2", "1.00", "0.8"] }
-    ]
-  }
-  ```
-
-- **`rawLLMOutputChange`** — `string`: raw LLM output from the backend (if any).
+```typescript
+import { BackendMode } from '@naniteninja/profile-comparison-lib';
 
-- **`viewProfileClick`** — `{ side: 'left' | 'right' }`: emitted when the user clicks “View Profile” on the left or right side. Use this to navigate or open a profile page.
+BackendMode.Real  // 0 — deployed backend (default)
+BackendMode.Mock  // 1 — localhost:3000
+```
 
-  Example:
+### URL resolution priority
 
-  ```typescript
-  onViewProfile(payload: { side: 'left' | 'right' }) {
-    this.router.navigate(['/profile', payload.side]);
-  }
-  ```
+1. `backendUrl` input (if non-empty)
+2. `backendMode` enum mapping
+3. Legacy `PROFILE_COMPARISON_API_BASE_URL` injection token (backward compatible)
 
 ---
 
 ## Backend API contract
 
-The library calls your backend at `POST {baseUrl}/profile/compare-full` with body `{ config: IProfileConfig }`. The backend should return a display payload (face results, aligned lists, center item, matrix data, raw LLM output). See the **profile-comparison-server** repo and the lib interface `IComparisonPayload` for the response shape.
+The library calls `POST {baseUrl}/profile/compare-full` with body `{ config: IProfileConfig }`. The backend returns a display payload (face results, aligned lists, center item, matrix data, raw LLM output). See the **profile-comparison-server** repo and the `IComparisonPayload` interface for the response shape.
 
 ---
 
@@ -269,4 +164,4 @@ The library calls your backend at `POST {baseUrl}/profile/compare-full` with bod
 ng build profile-comparison-lib
 ```
 
-Output is in `dist/profile-comparison-lib/` (FESM, typings, package.json). Peer dependencies: Angular `^20.0.0` and TensorFlow (`@tensorflow/tfjs`, `@tensorflow-models/universal-sentence-encoder`).
+Output is in `dist/profile-comparison-lib/` (FESM bundles, typings, package.json). Peer dependencies: Angular `^20.0.0`.