@naniteninja/dashboard-components-lib 2.2.1 → 2.3.4

package/README.md

@@ -1,43 +1,44 @@
 # @naniteninja/dashboard-components-lib
 
-Canonical source of truth for shared TypeScript types, enums, and Angular presentational components used across the Cyrano ecosystem.
+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.
 
 ## Role in the Ecosystem
 
 ```
-Blackbox (Python)  →  CyranoServer (NestJS)  →  Cyrano (Angular)  →  dashboard-components-lib
-     wire types         wire envelopes          host state           canonical types + components
+cyrano-contracts (wire SSOT)  →  CyranoServer / Cyrano  →  dashboard-components-lib (UI)
+Blackbox (Python stubs)       ↗
 ```
 
-This library owns the **canonical TypeScript definitions** consumed by:
-- **CyranoServer** (mirrors types for parity; contract-tested via `contract-alignment.spec.ts`)
-- **Cyrano** (imports directly via `@naniteninja/dashboard-components-lib`)
-- **Blackbox** (wire equivalence via Python TypedDicts mirroring these 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)
 
-## Canonical Types
-
-### Core Messaging
-
-| Type | File | Purpose |
-|------|------|---------|
-| `IMessage` | `interfaces/message.interface.ts` | Fundamental message unit |
-| `IAttachment` | `interfaces/message-attachment.interface.ts` | Message media |
-| `ISendOptionsMessage` | `interfaces/send-options-message.interface.ts` | Send timing preferences |
-| `IChatSuggestion` | `interfaces/chat-suggestion.interface.ts` | LLM suggestion entry |
-| `SenderTypes` | `enums/sender-types.enum.ts` | `user` / `other` enum |
-| `SendMessageType` | `enums/type-send-message.enum.ts` | Send timing enum |
-| `MatcherStatuses` | `enums/matcher-statuses.enum.ts` | Pipeline status funnel |
+Canonical wire definitions are in **`@naniteninja/cyrano-contracts`**. CyranoServer validates parity via `contract-alignment.spec.ts`.
 
-### Dashboard Models
+## Canonical Types
 
-| Type | File | Purpose |
-|------|------|---------|
-| `IProspectData` | `interfaces/prospect-data.interface.ts` | Chat/prospect card payload |
-| `ILibClientMatchOverview` | `interfaces/client-match-overview.interface.ts` | Client match overview envelope |
-| `IDashboardMatchRequest` | `interfaces/dashboard-match-request.interface.ts` | Match request metadata |
-| `ISchedulerEvent` | `interfaces/scheduler.event.interface.ts` | Calendar events |
-| `IChartData` | `interfaces/chart-data.interface.ts` | Compatibility chart data |
-| `IConversationFlag` | `interfaces/conversation-flag.interface.ts` | Unresponsive/redelegation flags |
+### Core Messaging (from `@naniteninja/cyrano-contracts`)
+
+| 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 |
+
+### Dashboard Models (UI extensions)
+
+| 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 |
 
 ### Enums
 
@@ -68,32 +69,27 @@ This library owns the **canonical TypeScript definitions** consumed by:
 
 ## Contract Ownership Rules
 
-1. **New shared types** belong here if consumed by UI components
-2. **CyranoServer** maintains compile-time mirrors validated by `contract-alignment.spec.ts`
-3. **Cyrano** imports directly; never forks a parallel interface
-4. **Blackbox** mirrors via Python TypedDicts in `shared_web_utils/base/typed_payloads.py`
+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`
 
 ## Adding a New Contract
 
-1. Define the interface/enum in `src/lib/interfaces/` or `src/lib/enums/`
-2. Export from `src/public-api.ts`
-3. Add a mirror to CyranoServer's `contract-alignment.spec.ts` with compile-time assertion
-4. Update `FIELD_CONSISTENCY_MATRIX.md` in the CyranoServer docs
-5. If the type crosses the Python boundary, add a TypedDict in Blackbox's `typed_payloads.py`
+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
 
 ## Development
 
 ```bash
-# Build the library
-ng build dashboard-components-lib
-
-# Run tests
-ng test dashboard-components-lib
+npm run build
+npm test
 ```
 
 ## Related Documentation
 
+- `cyrano-contracts/README.md` — wire SSOT package
 - `cyranoserver/docs/CANONICAL_MESSAGING_CONTRACTS.md` — full contract reference
-- `cyranoserver/docs/FIELD_CONSISTENCY_MATRIX.md` — cross-repo field comparison
-- `cyranoserver/docs/CROSS_REPO_TYPE_OWNERSHIP.md` — ownership map
-- `cyranoserver/docs/TESTING_CONTRACTS.md` — test enforcement matrix
+- `cyrano/docs/MESSAGING_ARCHITECTURE.md` — frontend socket integration