sea-dev 1.0.0

package/tests/crm-viewer-app/CURRENT_ASSETS_FIELDS.md

@@ -0,0 +1,148 @@
+# Current Assets Form Fields
+
+This document describes the Current Assets fields that have been integrated into the CRM viewer app with citation support.
+
+## Implemented Fields
+
+All fields are displayed in a two-column grid layout with proper labels, placeholders, COA codes, and citation support.
+
+### 1. Cash (L0005)
+- **Field ID**: `cash`
+- **Type**: Money
+- **Description**: Money on hand and in checking accounts available for daily operations
+- **Citation**: Registered to `doc-balance-sheet`, Page 1
+
+### 2. Certificate of Deposit (L0006)
+- **Field ID**: `certificate-of-deposit`
+- **Type**: Money
+- **Description**: Bank-issued deposit with a fixed date of maturity, not immediately accessible
+- **Citation**: Registered to `doc-balance-sheet`, Page 1
+
+### 3. Marketable Securities (L0007)
+- **Field ID**: `marketable-securities`
+- **Type**: Money
+- **Description**: Short-term financial instruments (stocks, bonds, etc.) that can be converted to cash quickly
+- **Citation**: Registered to `doc-balance-sheet`, Page 1
+
+### 4. Accounts Receivable (A/R) (L0010)
+- **Field ID**: `accounts-receivable`
+- **Type**: Money
+- **Description**: Amounts billed to customers for goods or services delivered, awaiting payment
+- **Citation**: Registered to `doc-balance-sheet`, Page 1
+
+### 5. Notes Receivable – Current (L0015)
+- **Field ID**: `notes-receivable-current`
+- **Type**: Money
+- **Description**: Short-term promissory notes owed to the business, due within one year
+- **Citation**: Registered to `doc-balance-sheet`, Page 1
+
+### 6. Inventory – Raw Materials (L0020)
+- **Field ID**: `inventory-raw-materials`
+- **Type**: Money
+- **Description**: Stock of basic materials to be used in manufacturing or production
+- **Citation**: Registered to `doc-balance-sheet`, Page 2
+
+### 7. Inventory – Work in Progress (L0021)
+- **Field ID**: `inventory-work-in-progress`
+- **Type**: Money
+- **Description**: Goods partway through the manufacturing process but not yet finished
+- **Citation**: Registered to `doc-balance-sheet`, Page 2
+
+### 8. Inventory – Finished Goods (L0022)
+- **Field ID**: `inventory-finished-goods`
+- **Type**: Money
+- **Description**: Completed products ready for sale but not yet sold
+- **Citation**: Registered to `doc-balance-sheet`, Page 2
+
+### 9. Prepaid Expenses (L0030)
+- **Field ID**: `prepaid-expenses`
+- **Type**: Money
+- **Description**: Payments made in advance for goods or services to be received in the future
+- **Citation**: Registered to `doc-balance-sheet`, Page 2
+
+### 10. Other Current Assets (L0055)
+- **Field ID**: `other-current-assets`
+- **Type**: Money
+- **Description**: Miscellaneous current assets not classified elsewhere, expected to be liquidated within a year
+- **Citation**: Registered to `doc-balance-sheet`, Page 2
+
+## Implementation Details
+
+### Component Structure
+
+Each field is rendered with:
+- Uppercase label displaying the field name
+- Input field with `data-sea-field` attribute for citation linking
+- Click handler `(click)="onFieldClick('field-id')"` to activate citations
+- Title attribute with full description for tooltips
+- Small text showing COA code and brief description
+
+### Citation Mappings
+
+All citations are registered in [citation.service.ts](src/app/citation.service.ts:42-135) with:
+- Unique field ID matching the `data-sea-field` attribute
+- Citation ID (e.g., `citation-cash`, `citation-ar`)
+- Document ID: `doc-balance-sheet` for all Current Assets fields
+- Page number: Pages 1-2 depending on the field
+
+### User Experience
+
+1. **Visual Indicators**: Fields with citations show a hover effect
+2. **Click Activation**: Clicking any field opens the PDF viewer with the relevant citation highlighted
+3. **Document Display**: PDF viewer shows "Balance Sheet - Current Assets.pdf"
+4. **Citation Info**: Right sidebar displays active citation details including field ID, citation ID, and page number
+
+## Testing
+
+To test the integration:
+
+```bash
+cd tests/crm-viewer-app
+pnpm start
+```
+
+Then:
+1. Navigate to http://localhost:4201
+2. Scroll to the "Current Assets" section
+3. Click any field to view its citation in the PDF viewer overlay
+4. Verify the citation information appears in the right sidebar
+5. Click the overlay background or close button to dismiss the PDF viewer
+
+## Next Steps
+
+To integrate with real data:
+
+1. **Update Citation Service**: Replace placeholder citations in `initializePlaceholderCitations()` with actual citation data from your API
+2. **Load Real Documents**: Update `activateCitation()` to fetch actual PDF URLs
+3. **Add Real Coordinates**: Replace the example polygon coordinates with actual bounding regions from document processing
+4. **Implement Data Fetching**: Add a service to load submission data and automatically register citations
+
+Example integration:
+
+```typescript
+// In your data loading service
+loadSubmissionData(submissionId: string) {
+  this.api.getSubmission(submissionId).subscribe(submission => {
+    submission.fields.forEach(field => {
+      if (field.citation) {
+        this.citationService.registerCitation({
+          fieldId: field.name,
+          citationId: field.citation.id,
+          documentId: field.citation.documentId,
+          pageNumber: field.citation.pageNumber,
+        });
+      }
+    });
+  });
+}
+```
+
+## Field Styling
+
+All fields include:
+- Consistent padding (8px)
+- Border color: #d8dde6
+- Border radius: 3px
+- Font size: 13px
+- Placeholder: $0.00
+- Helper text with COA code below each field

package/tests/crm-viewer-app/FIELD_ID_MAPPING.md

@@ -0,0 +1,206 @@
+# Field ID Mapping - API to HTML
+
+This document shows how HTML form fields are mapped to the exact field IDs from the Sea.dev API.
+
+## ✅ Updated Field IDs
+
+The HTML `data-sea-field` attributes now match the **exact field IDs** from the API response.
+
+### Current Assets Fields (Implemented)
+
+| HTML Label | data-sea-field | API fieldId | Status |
+|-----------|----------------|-------------|--------|
+| CASH | `Cash` | `Cash` | ✅ Mapped |
+| ACCOUNTS RECEIVABLE (A/R) | `Accounts Receivable (A/R)` | `Accounts Receivable (A/R)` | ✅ Mapped |
+| PREPAID EXPENSES | `Prepaid Expenses` | `Prepaid Expenses` | ✅ Mapped |
+| OTHER CURRENT ASSETS | `Other Current Assets` | `Other Current Assets` | ✅ Mapped |
+
+### Other Fields from API (Not Yet Implemented in HTML)
+
+These fields exist in the API but are not yet displayed in the HTML form:
+
+| Field ID from API | Citation ID | Page | Status |
+|------------------|-------------|------|--------|
+| `Due from Affiliates/Related Parties/Officers/Employees` | `boesieiva5etav6s4t86t` | 9 | ⏳ Not in HTML |
+| `Gross Fixed Assets` | `m5jfexogo53fchqrnul5i` | 9 | ⏳ Not in HTML |
+| `Accumulated Depreciation` | `5bq6vfscbq2fthg4p242h` | 9 | ⏳ Not in HTML |
+| `Net Fixed Assets` | `n4xszdn5xkkxtdrbyinxp` | 9 | ⏳ Not in HTML |
+| `TOTAL ASSETS` | `ol2xaxeuk8vgkq25ggkbd` | 4 | ⏳ Not in HTML |
+| `Current Portion of LT Debt` | `ngqkm4coohtfb8hkufskb` | 9 | ⏳ Not in HTML |
+| `Accounts Payable` | `aqpcfqdj35okiooaoevnc` | 9 | ⏳ Not in HTML |
+| `Accrued Expenses` | `kbumiwoqtjgfhnffhlkwx` | 30 | ⏳ Not in HTML |
+| `Federal Income Taxes Payable` | `injndrsz6czeqgf6tsri3` | 30 | ⏳ Not in HTML |
+| `Other Current Liabilities` | `ark4gxkd6ts6nf6d5val5` | 30 | ⏳ Not in HTML |
+| `Total Current Liabilities` | `b5hpxrsw3jiyukqltzq5f` | 9 | ⏳ Not in HTML |
+| `Long Term Debt` | `uwdrjn8adj2dowgycbnyg` | 9 | ⏳ Not in HTML |
+| `Total Liabilities` | `c4mb4csf5xzo4njlgaxde` | 9 | ⏳ Not in HTML |
+
+## Field ID Format
+
+The API uses **human-readable labels** as field IDs, not kebab-case identifiers:
+
+❌ **Old (Incorrect):**
+```html
+<input data-sea-field="cash" (click)="onFieldClick('cash')" />
+```
+
+✅ **New (Correct):**
+```html
+<input data-sea-field="Cash" (click)="onFieldClick('Cash')" />
+```
+
+## How Field Matching Works
+
+### 1. API Response Structure
+
+```json
+{
+  "groups": [
+    {
+      "items": [
+        {
+          "formField": {
+            "id": "field-abc",
+            "name": "Cash",  // ← This is the fieldId we use
+            "label": "Cash"
+          },
+          "documentCitationId": "4s248bury4omnik4vwl8l",
+          "value": 50000
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 2. Citation Registration
+
+```typescript
+// app.component.ts - processCitations()
+this.citationService.registerCitation({
+  fieldId: item.formField.name,  // "Cash"
+  citationId: item.documentCitationId,
+  documentId: document.id,
+  pageNumber: pageNumber,
+});
+```
+
+### 3. HTML Field
+
+```html
+<input
+  data-sea-field="Cash"
+  (click)="onFieldClick('Cash')"
+/>
+```
+
+### 4. Citation Lookup
+
+```typescript
+// When field is clicked:
+onFieldClick('Cash')
+  → citationService.activateCitationWithDocument('Cash')
+    → Looks up citation by fieldId "Cash"
+      → Finds document and displays PDF with highlighted region
+```
+
+## Testing Field Mappings
+
+### Check Console Logs
+
+When the app loads, you should see:
+
+```
+[CRM Viewer] Registered citation: {
+  fieldId: "Cash",
+  documentId: "doc-xyz",
+  documentName: "Balance Sheet.pdf",
+  pageNumber: 9
+}
+```
+
+### Verify Field Matching
+
+1. **Open browser console**
+2. **Look for registration logs** - Each field from the API should show up
+3. **Click a field** - Should see: `[CRM Viewer] Field clicked: Cash`
+4. **PDF opens** - Should highlight the correct region on page 9
+
+### Debug Mismatches
+
+If a field doesn't work:
+
+```javascript
+// Check what fields were registered
+console.log('[Debug] Registered citations:');
+// In browser console, the citation service stores fieldId as the key
+
+// Check HTML attribute
+document.querySelector('[data-sea-field="Cash"]')  // Should find element
+
+// Check if they match
+'Cash' === 'cash'  // false - case matters!
+'Cash' === 'Cash'  // true - exact match
+```
+
+## Adding More Fields
+
+To add the remaining fields from the API:
+
+### 1. Add HTML Field
+
+```html
+<div>
+  <label style="display: block; font-size: 11px; color: #706e6b; margin-bottom: 4px; font-weight: 600;">
+    GROSS FIXED ASSETS
+  </label>
+  <input
+    type="text"
+    data-sea-field="Gross Fixed Assets"
+    placeholder="$0.00"
+    (click)="onFieldClick('Gross Fixed Assets')"
+    title="Fixed assets at original cost"
+    style="width: 100%; padding: 8px; border: 1px solid #d8dde6; border-radius: 3px; font-size: 13px;"
+  />
+</div>
+```
+
+### 2. Field ID Must Match Exactly
+
+The `data-sea-field` attribute must match the API's `formField.name` **exactly**:
+- Same capitalization
+- Same spaces
+- Same punctuation (parentheses, slashes, etc.)
+
+### 3. No Code Changes Needed
+
+Once the HTML field is added with the correct `data-sea-field`, the citation will automatically:
+- Be registered when the app loads
+- Link to the document when clicked
+- Display the PDF with highlighted region
+
+## Current Status
+
+✅ 4 fields implemented and working:
+- Cash
+- Accounts Receivable (A/R)
+- Prepaid Expenses
+- Other Current Assets
+
+⏳ 13 additional fields available in API (not yet in HTML):
+- Can be added by copying HTML template above
+- Just ensure `data-sea-field` matches API fieldId exactly
+
+## Summary
+
+The key change is using **exact field names from the API** as field IDs, rather than creating custom kebab-case identifiers. This ensures perfect matching between HTML fields and API citations.
+
+### Before
+- HTML: `data-sea-field="cash"`
+- API: `formField.name = "Cash"`
+- Result: ❌ No match (case mismatch)
+
+### After
+- HTML: `data-sea-field="Cash"`
+- API: `formField.name = "Cash"`
+- Result: ✅ Perfect match!

package/tests/crm-viewer-app/INTEGRATION_GUIDE.md

@@ -0,0 +1,309 @@
+# Integration Guide: Adding Citation Support to Your Forms
+
+This guide explains how to add citation support to any form field in your application.
+
+## Quick Start
+
+1. **Add the `data-sea-field` attribute** to any element you want to make citation-aware
+2. **Register the citation** in `CitationService`
+3. **Add a click handler** to activate the citation
+
+## Step-by-Step Example
+
+### 1. Identify Your Field
+
+Let's say you have a form field for "Total Assets":
+
+```html
+<input type="text" placeholder="Enter total assets" />
+```
+
+### 2. Add the Citation Attribute
+
+Add a unique `data-sea-field` attribute:
+
+```html
+<input
+  type="text"
+  data-sea-field="total-assets"
+  placeholder="Enter total assets"
+/>
+```
+
+### 3. Add Click Handler
+
+Make it clickable to activate the citation:
+
+```html
+<input
+  type="text"
+  data-sea-field="total-assets"
+  (click)="onFieldClick('total-assets')"
+  placeholder="Enter total assets"
+/>
+```
+
+### 4. Register the Citation
+
+In `citation.service.ts`, add the field mapping:
+
+```typescript
+this.registerCitation({
+  fieldId: 'total-assets',           // Must match data-sea-field
+  citationId: 'citation-assets-01',  // From your document
+  documentId: 'doc-financial-2024',  // Document ID
+  pageNumber: 5,                     // Page number
+});
+```
+
+## Field Types
+
+### Text Inputs
+
+```html
+<input
+  type="text"
+  data-sea-field="company-name"
+  (click)="onFieldClick('company-name')"
+/>
+```
+
+### Select Dropdowns
+
+```html
+<select
+  data-sea-field="industry-type"
+  (click)="onFieldClick('industry-type')"
+>
+  <option>Financial Services</option>
+  <option>Technology</option>
+</select>
+```
+
+### Display-Only Fields
+
+```html
+<div
+  class="sf-field-value"
+  data-sea-field="calculated-revenue"
+  (click)="onFieldClick('calculated-revenue')"
+>
+  $1,234,567
+</div>
+```
+
+### Textareas
+
+```html
+<textarea
+  data-sea-field="business-description"
+  (click)="onFieldClick('business-description')"
+  rows="4"
+></textarea>
+```
+
+## Advanced Usage
+
+### Grouping Related Citations
+
+If multiple fields come from the same section of a document, you can organize them:
+
+```typescript
+// Financial statement section
+const financialFields = [
+  { fieldId: 'revenue', citationId: 'fin-01', page: 1 },
+  { fieldId: 'expenses', citationId: 'fin-02', page: 1 },
+  { fieldId: 'net-income', citationId: 'fin-03', page: 2 },
+];
+
+financialFields.forEach(field => {
+  this.registerCitation({
+    fieldId: field.fieldId,
+    citationId: field.citationId,
+    documentId: 'financial-statement-2024',
+    pageNumber: field.page,
+  });
+});
+```
+
+### Dynamic Field Registration
+
+For forms generated dynamically:
+
+```typescript
+// In your component
+ngOnInit() {
+  this.loadFormData().subscribe(formData => {
+    formData.fields.forEach(field => {
+      if (field.hasCitation) {
+        this.citationService.registerCitation({
+          fieldId: field.id,
+          citationId: field.citationId,
+          documentId: field.documentId,
+          pageNumber: field.pageNumber,
+        });
+      }
+    });
+  });
+}
+```
+
+### Custom Citation UI
+
+Add visual indicators for fields with citations:
+
+```css
+/* Add icon to fields with citations */
+[data-sea-field]::after {
+  content: "📄";
+  margin-left: 5px;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+
+[data-sea-field]:hover::after {
+  opacity: 1;
+}
+
+/* Highlight active citation field */
+[data-sea-field].active-citation {
+  background-color: #fff3cd;
+  border-color: #ffc107;
+}
+```
+
+Then in your component:
+
+```typescript
+protected onFieldClick(fieldId: string): void {
+  // Remove active class from all fields
+  document.querySelectorAll('[data-sea-field]').forEach(el => {
+    el.classList.remove('active-citation');
+  });
+
+  // Add active class to clicked field
+  const field = document.querySelector(`[data-sea-field="${fieldId}"]`);
+  field?.classList.add('active-citation');
+
+  // Activate the citation
+  this.citationService.activateCitation(fieldId);
+}
+```
+
+## Using the Full HTML Template
+
+The `template.html` file in this directory contains the complete CRM interface. To use it:
+
+1. **Extract the body content** - Copy everything inside `<body>` tags
+2. **Convert to Angular template** - Replace inline event handlers with Angular syntax:
+   - `onclick="func()"` → `(click)="func()"`
+   - Add `data-sea-field` attributes where needed
+3. **Add to component** - Place in your component's template
+
+Example conversion:
+
+```html
+<!-- Original HTML -->
+<button onclick="submitForm()">Submit</button>
+
+<!-- Angular template -->
+<button (click)="submitForm()">Submit</button>
+```
+
+## Real-World Integration
+
+### Connecting to Sea.dev API
+
+```typescript
+import { HttpClient } from '@angular/common/http';
+import { Injectable } from '@angular/core';
+
+@Injectable({ providedIn: 'root' })
+export class SeaApiService {
+  constructor(
+    private http: HttpClient,
+    private citationService: CitationService
+  ) {}
+
+  loadSubmission(submissionId: string) {
+    return this.http.get(`/api/submissions/${submissionId}`).pipe(
+      tap((submission: any) => {
+        // Register citations from API response
+        submission.fields.forEach(field => {
+          if (field.citation) {
+            this.citationService.registerCitation({
+              fieldId: field.name,
+              citationId: field.citation.id,
+              documentId: field.citation.document.id,
+              pageNumber: field.citation.pageNumber,
+            });
+          }
+        });
+      })
+    );
+  }
+}
+```
+
+### Document Loading
+
+```typescript
+activateCitation(fieldId: string): void {
+  const citation = this.getCitation(fieldId);
+  if (!citation) return;
+
+  // Load the actual document
+  this.documentService.getDocument(citation.documentId).subscribe(doc => {
+    this.activeDocument.set({
+      id: doc.id,
+      name: doc.name,
+      url: doc.signedUrl, // Use signed URL from API
+      citations: doc.citations.map(c => ({
+        id: c.id,
+        boundingRegions: c.boundingRegions,
+        text: c.extractedText,
+        path: c.fieldPath,
+      })),
+    });
+
+    this.selectedCitation.set(citation);
+    this.pdfViewerVisible.set(true);
+  });
+}
+```
+
+## Troubleshooting
+
+### Citation Not Appearing
+
+1. Check that `fieldId` in `registerCitation()` matches `data-sea-field` attribute
+2. Verify the citation is registered before the component renders
+3. Check browser console for errors
+
+### PDF Not Loading
+
+1. Verify the document URL is accessible
+2. Check CORS settings if loading from different domain
+3. Ensure PDF URL is properly signed/authenticated
+
+### Click Handler Not Working
+
+1. Make sure you're using Angular event binding: `(click)="..."`
+2. Verify the component method is defined and accessible
+3. Check that the element isn't disabled or behind another element
+
+## Best Practices
+
+1. **Use semantic field IDs**: `revenue`, `company-name`, not `field1`, `field2`
+2. **Register citations early**: In `ngOnInit` or service constructor
+3. **Handle missing citations**: Check `hasCitation()` before activating
+4. **Provide feedback**: Show loading states while fetching documents
+5. **Clean up**: Remove citation registrations when component is destroyed
+
+## Examples
+
+See [app.component.ts](src/app/app.component.ts) for a complete working example with:
+- Multiple field types with citations
+- PDF viewer integration
+- Bidirectional navigation
+- Visual feedback