# @intelligencebank/connectingib

UI components and integration patterns for building IntelligenceBank integrations.

## Installation

```bash
npm install @intelligencebank/connectingib
```

## Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install react react-dom @emotion/react @emotion/styled
```

## Usage

```tsx
import {
  // UI Primitives
  Button,
  Card,
  Icon,
  Input,
  Select,
  Modal,
  Tabs,
  Tooltip,
  DropdownMenu,
  
  // Integration Components
  AssetBrowser,
  LoginForm,
  NavBar,
  FolderTree,
  
  // Theme
  ThemeProvider,
  productionTheme,
} from '@intelligencebank/connectingib';

function App() {
  return (
    <ThemeProvider theme={productionTheme}>
      <NavBar
        logoSrc="/logo.svg"
        logoAlt="My App"
        title="Asset Browser"
        actions={[
          { id: 'help', icon: 'help', label: 'Help', onClick: () => {} },
        ]}
      />
      <AssetBrowser
        assets={assets}
        folders={folders}
        onAssetSelect={handleSelect}
      />
    </ThemeProvider>
  );
}
```

## Components

### UI Primitives

Foundation-level presentation components:

- **Button** - Primary, secondary, tertiary buttons with variants
- **Card** - Container with header, media, content, actions
- **Icon** - Material icons with size and color options
- **Input** - Text input with validation states
- **Select** - Single-select dropdown
- **Multiselect** - Multi-select with checkboxes
- **Modal** - Dialog with header, body, footer
- **Tabs** - Tab navigation
- **Tooltip** - Hover tooltips
- **DropdownMenu** - Context menus
- **Switch** - Toggle switch
- **Radio/RadioGroup** - Radio buttons
- **TextArea** - Multi-line text input
- **FormControl** - Form field wrapper
- **FieldLabel** - Form labels
- **Message** - Info, warning, error messages
- **Snackbar** - Toast notifications
- **Chip** - Tags and labels
- **Status** - Status indicators
- **LinearLoading** - Progress bars
- **Spinner** - Loading spinners
- **ActionMenuButtons** - Action button groups
- **Paginator** - Pagination controls
- **DropZone** - File upload dropzone
- **DataContainerCard** - Titled section container with optional expand/collapse

### Integration Components

Domain-specific components for IntelligenceBank integrations:

- **AssetBrowser** - Complete asset browsing experience
- **AssetCard** - Asset preview cards
- **FolderTree** - Folder navigation
- **FolderCard** - Folder preview cards
- **LoginForm** - Authentication form
- **BrowserLoginConfirmation** - Login confirmation
- **NavBar** - Navigation bar
- **FiltersPanel** - Asset filtering
- **PresetSelector** - Preset selection
- **SearchForm** - Search interface

### Risk Review Integration Components

Components for building AI-powered risk review workflows:

#### Core Components

- **ReviewProcessing** - Processing/loading overlay for single or batch reviews with progress indicators
- **ReviewDetails** - Displays review metadata (type, file, filters, timestamp, ID)
- **ReviewResults** - Displays risk findings with status and expandable multi-file sections
- **ReviewFiles** - File list with single/multiple selection, removal, and validation errors
- **CategoryFilters** - Dynamic filter dropdowns (single/multi-select) from API categories

#### Composite Components

- **CreateReview** - Complete review creation form with platform modes (extension/webapp)
- **LatestReview** - Complete results view with actions and Send to IB integration

#### Usage Example

```tsx
import {
  CreateReview,
  LatestReview,
  ReviewProcessing,
  ReviewDetails,
  ReviewResults,
  ReviewFiles,
  CategoryFilters,
  type ReviewContentType,
  type RiskItem,
  type ReviewFileItem,
} from '@intelligencebank/connectingib';

// Composite component for review creation
function ReviewCreationPage() {
  return (
    <CreateReview
      platform="webapp"
      files={files}
      onFilesChange={setFiles}
      categories={categories}
      selectedCategories={selectedCategories}
      onCategoryChange={handleCategoryChange}
      onSubmit={handleSubmit}
      isSubmitting={isSubmitting}
    />
  );
}

// Composite component for results display
function ReviewResultsPage() {
  return (
    <LatestReview
      reviewData={reviewData}
      onSendToIB={handleSendToIB}
      isSending={isSending}
    />
  );
}

// Building blocks for custom layouts
function CustomReviewLayout() {
  return (
    <>
      <ReviewProcessing
        isProcessing={isProcessing}
        mode="multi"
        progressData={progressData}
      />
      <ReviewDetails
        contentType="document"
        fileName="report.pdf"
        timestamp={new Date()}
        reviewId="abc123"
      />
      <CategoryFilters
        categories={categories}
        selectedCategories={selectedCategories}
        onCategoryChange={handleCategoryChange}
      />
      <ReviewFiles
        files={files}
        mode="multiple"
        onSelect={handleSelect}
        onRemove={handleRemove}
      />
      <ReviewResults
        risks={risks}
        status="completed"
        mode="single"
      />
    </>
  );
}
```

#### Types

```tsx
import type {
  // Content and risk types
  ReviewContentType,
  RiskItem,
  ReviewFileItem,
  ReviewResultData,
  
  // Multi-file review types
  MultiFileReviewResultData,
  MultiFileProgressData,
  FileProgressData,
  
  // Filter types
  FilterCategoryData,
  FilterValueData,
  CategorySelection,
  
  // Upload types
  UploadFieldData,
} from '@intelligencebank/connectingib';
```

See [Storybook](http://localhost:6006) for interactive examples of all Risk Review components.

## Theming

The library uses Emotion for theming. Wrap your app with `ThemeProvider`:

```tsx
import { ThemeProvider, theme } from '@intelligencebank/connectingib';

<ThemeProvider theme={theme}>
  {/* Your app */}
</ThemeProvider>
```

### Dynamic Tenant Colors

The theme has 6 colors that can be customized per tenant from the IntelligenceBank login API response:

| Login API Field | Theme Property | Purpose |
|-----------------|----------------|---------|
| `colourPrimary` | `theme.colors.primary` | Header, primary backgrounds |
| `colourPrimaryText` | `theme.colors.primaryText` | Text on primary backgrounds |
| `colourSecondary` | `theme.colors.secondary` | Secondary buttons, accents |
| `colourSecondaryText` | `theme.colors.secondaryText` | Text on secondary backgrounds |
| `colourHighlight` | `theme.colors.highlight` | CTA buttons, selection, accent |
| `colourHighlightText` | `theme.colors.highlightText` | Text on highlight backgrounds |

After login, apply the tenant's brand colors:

```tsx
import { ThemeProvider, theme } from '@intelligencebank/connectingib';

function App() {
  const [tenantTheme, setTenantTheme] = useState(theme);
  
  const handleLoginSuccess = (response) => {
    // Apply tenant colors from login API response
    setTenantTheme({
      ...theme,
      colors: {
        ...theme.colors,
        primary: response.colourPrimary,
        primaryText: response.colourPrimaryText,
        secondary: response.colourSecondary,
        secondaryText: response.colourSecondaryText,
        highlight: response.colourHighlight,
        highlightText: response.colourHighlightText,
      },
    });
  };
  
  return (
    <ThemeProvider theme={tenantTheme}>
      {/* Components now use tenant's brand colors */}
    </ThemeProvider>
  );
}
```

### Fixed Design Tokens

These colors never change per tenant (part of the design system):

```tsx
// Text colors
theme.colors.text.primary      // Main text
theme.colors.text.secondary    // Secondary text
theme.colors.text.muted        // Muted text

// Status colors
theme.colors.status.success    // Green
theme.colors.status.error      // Red

// Background colors
theme.colors.background.default // Page background
theme.colors.background.hover   // Hover state

// Border colors
theme.colors.border.medium     // Standard borders
theme.colors.border.input      // Input borders
```

For complete documentation, see the [main README](https://bitbucket.org/IB-IntelligenceBank/ib-integration-libraries).

## Adapters

Data adapters for transforming API responses:

```tsx
import { assetAdapter, folderAdapter, presetAdapter } from '@intelligencebank/connectingib';

const assets = apiAssets.map(assetAdapter.fromApiAsset);
const folders = apiFolders.map(folderAdapter.fromApiFolder);
```

## Utilities

Helper functions for common operations:

```tsx
import { formatFileSize, formatDimensions, truncateFilename } from '@intelligencebank/connectingib';

formatFileSize(1024 * 1024); // "1 MB"
formatDimensions(1920, 1080); // "1920 × 1080"
```

## Storybook

View all components in Storybook:

```bash
cd apps/storybook
npm run storybook
```

## Migration from Previous Packages

If migrating from `@intelligencebank/ui-primitives` and `@intelligencebank/integration-components`:

```bash
# Remove old packages
npm uninstall @intelligencebank/ui-primitives @intelligencebank/integration-components

# Install new unified package
npm install @intelligencebank/connectingib
```

Update imports:

```tsx
// Before
import { Button } from '@intelligencebank/ui-primitives';
import { AssetBrowser } from '@intelligencebank/integration-components';

// After
import { Button, AssetBrowser } from '@intelligencebank/connectingib';
```

## License

UNLICENSED - IntelligenceBank proprietary