@naniteninja/dashboard-components-lib 2.3.4 → 2.3.6

package/README.md

@@ -1,95 +1,86 @@
 # @naniteninja/dashboard-components-lib
 
-Angular presentational components and UI-enriched types for the Cyrano dashboard. **Wire types** (socket payloads, shared enums) live in `@naniteninja/cyrano-contracts`; this library extends them with presentation-only fields.
+Shared Angular/Ionic UI component library for the Cyrano dashboard ecosystem.
 
-## Role in the Ecosystem
+## Purpose
 
-```
-cyrano-contracts (wire SSOT)  →  CyranoServer / Cyrano  →  dashboard-components-lib (UI)
-Blackbox (Python stubs)       ↗
-```
+This library provides reusable UI components for messaging, scheduling, progress visualization, and match management. It is consumed by the Cyrano frontend application.
+
+## Key Interfaces
 
-This library provides **dashboard UI components and presentation types** consumed by:
-- **Cyrano** (host app — sockets, auth, state)
-- **dashboard-components-lib-test** (local component harness)
+| Interface | Purpose |
+|-----------|---------|
+| `IMessage` | Single chat message (sender, message, timestamp, attachments, sendOptions, origin) |
+| `IProspectData` | Per-match messaging state aligned with CyranoServer Chat document |
+| `ILibClientMatchOverview` | Dashboard card model: display profiles + prospectData + matchRequest |
+| `IChatSuggestion` | LLM-generated conversation suggestion |
+| `IAttachment` | Image/GIF attachment on messages |
+| `ISendOptionsMessage` | Delayed/immediate send scheduling options |
 
-Canonical wire definitions are in **`@naniteninja/cyrano-contracts`**. CyranoServer validates parity via `contract-alignment.spec.ts`.
+## Architecture
 
-## Canonical Types
+The library is **WebSocket-free** — it receives data and emits events, but does NOT manage network connections:
 
-### Core Messaging (from `@naniteninja/cyrano-contracts`)
+- **Host app (Cyrano)** owns: WebSocket connections, API calls, state management (BehaviorSubjects), server-to-UI data transformation
+- **This library** owns: UI rendering, display grouping (messages by day), progress visualization, user interaction events
 
-| Type | Purpose |
-|------|---------|
-| `IMessage` | Fundamental message unit |
-| `IAttachment` | Message media |
-| `ISendOptionsMessage` | Send timing preferences |
-| `IChatSuggestion` | LLM suggestion entry |
-| `SenderTypes` | `user` / `other` enum |
-| `SendMessageType` | Send timing enum |
-| `MatcherStatuses` | Pipeline status funnel |
+## Primary Components
 
-### Dashboard Models (UI extensions)
+| Component | Selector | Purpose |
+|-----------|----------|---------|
+| `ChatComponent` | `lib-chat` | Full chat UI with message display, input, GIF picker |
+| `LibClientHomeComponent` | `lib-client-home` | Main dashboard shell with tabs |
+| `LibClientMatchOverviewComponent` | `lib-client-match-overview` | Prospect card with progress rings |
+| `MatcherStatusesComponent` | `lib-matcher-statuses` | Status ladder with embedded chat |
+| `ClientViewportComponent` | `lib-client-viewport` | Client-side full viewport shell |
+| `MatcherViewportComponent` | `lib-matcher-viewport` | Matcher-side full viewport shell |
+| `LibHandoffPanelComponent` | `lib-handoff-panel` | Multi-tab handoff (messages, schedule, date prep) |
+| `LibSchedulerComponent` | `lib-scheduler` | Date booking UI |
 
-| Type | Purpose |
-|------|---------|
-| `IProspectData` | Chat/prospect card payload (+ UI-only fields like `llmPreferenceLoading$`) |
-| `ILibClientMatchOverview` | Client match overview envelope |
-| `IDashboardMatchRequest` | Match request metadata |
-| `ISchedulerEvent` | Calendar events |
-| `IChartData` | Compatibility chart data |
-| `IConversationFlag` | Unresponsive/redelegation flags |
+## Data Flow
 
-### Enums
+```
+Host App (Cyrano)
+  -> Provides ILibClientMatchOverview[] via config/inputs
+    -> lib-client-viewport / lib-matcher-viewport
+      -> lib-client-home
+        -> lib-chat (displays IMessage[], emits sendMessage)
+        -> lib-matcher-statuses (displays status progression)
+        -> lib-scheduler (displays schedule events)
+        -> lib-spider-chart (compatibility visualization)
+```
 
-| Enum | File | Purpose |
-|------|------|---------|
-| `CONVERSATION_FLAG` | `enums/conversation-flag.enum.ts` | Unresponsive / redelegation |
-| `COUNTER_FLAG_BASE` | `enums/counter-flag-base.enum.ts` | Flag timing base |
+## Consuming from a Host App
 
-## Key Components
+1. Import `LibChatComponentModule` or viewport modules
+2. Provide `ILibClientMatchOverview[]` data (typically from a BehaviorSubject)
+3. Handle output events: `addMessage`, `getMessages`, status changes
+4. Transform server data to library interfaces using a mapper utility (e.g. `buildClientMatchOverviews`)
 
-| Component | Selector | Purpose |
-|-----------|----------|---------|
-| `ChatComponent` | `lib-chat` | Message list + input with virtual scroll |
-| `ClientHomeComponent` | `lib-client-home` | Client dashboard shell |
-| `ClientViewportComponent` | `lib-client-viewport` | Tabbed viewport (chat, scheduler, suggestions) |
-| `MatcherViewportComponent` | `lib-matcher-viewport` | Matcher dashboard viewport |
-| `DashboardSwipeableTabsComponent` | `lib-dashboard-swipeable-tabs` | Prospect card swipe strip |
-| `MatcherStatusesComponent` | `lib-matcher-statuses` | Status milestone ladder |
-| `ChatSuggestionComponent` | `lib-chat-suggestion` | AI suggestion chips |
+## Key Enums
 
-## Key Services
+| Enum | Values |
+|------|--------|
+| `SenderTypes` | `USER` ('user'), `OTHER` ('other') |
+| `MatcherStatuses` | STATUS0 ('no contact') through STATUS10 ('all followup') |
+| `SendMessageType` | `send_immediately`, `send_after`, `specify_time` |
 
-| Service | Purpose |
-|---------|---------|
-| `ChatService` | `transformMessages()` — groups messages by date for rendering |
-| `CalendarUtilsService` | Calendar event helpers |
-| `ProgressTickerService` | Progress ring animation |
+## Contract Alignment
 
-## Contract Ownership Rules
+The `IMessage` interface in this library is the **canonical messaging contract** for the entire Cyrano ecosystem. CyranoServer mirrors it (verified via `contract-alignment.spec.ts`). The host app's primary responsibility is timestamp coercion (ISO string -> Date) since Socket.IO serializes Dates as strings.
 
-1. **New wire types** belong in `@naniteninja/cyrano-contracts`
-2. **UI-only extensions** belong here (e.g. `llmPreferenceLoading$` on `IProspectData`)
-3. **Cyrano** imports wire types from contracts; lib types for components
-4. **Blackbox** mirrors wire types via Python stubs from `cyrano-contracts/scripts/generate-python.ts`
+## Building
 
-## Adding a New Contract
+```bash
+npm run build_lib && npm run npm_pack
+```
 
-1. Define wire interface/enum in `cyrano-contracts`
-2. Re-export or extend in this library if UI needs extra fields
-3. Run contract alignment tests in cyranoserver and cyrano
-4. Regenerate Python stubs for Blackbox if the type crosses the wire boundary
+Output: `dist/dashboard-components-lib/naniteninja-dashboard-components-lib-{version}.tgz`
 
-## Development
+## Testing
 
 ```bash
-npm run build
-npm test
+ng test dashboard-components-lib
 ```
 
-## Related Documentation
-
-- `cyrano-contracts/README.md` — wire SSOT package
-- `cyranoserver/docs/CANONICAL_MESSAGING_CONTRACTS.md` — full contract reference
-- `cyrano/docs/MESSAGING_ARCHITECTURE.md` — frontend socket integration
+Demo app available at `projects/dashboard-components-lib-test/` (port 4400).