# Configuration

## `CareConekt.CodeSystems.configure(settings)`

Call this once before `bind()`. Sets global configuration for all widget instances.

```javascript
CareConekt.CodeSystems.configure({
  // Required
  apiBaseUrl: "https://gw.careconekt.net/api/codesystems-search",
  apiKey: "ck_your_api_key",

  // Optional
  tenantId: "tenant-uuid",
  defaultCodeSystem: "icd10cm",
  debounceMs: 300,
  autocompleteMinChars: 2,
  searchResultsSize: 20,
  theme: "light",

  // Callbacks
  onSelect: function (concept, instanceId) {},
  onSearchStart: function (query, instanceId) {},
  onSearchEnd: function (total, instanceId) {},
  onError: function (error, instanceId) {},
});
```

## Settings Reference

### Required

`apiBaseUrl`
: **Type:** `string`
: The CareConekt API base URL for code system search.
: Value: `"https://gw.careconekt.net/api/codesystems-search"`

`apiKey`
: **Type:** `string`
: Your CareConekt API key (prefixed with `ck_`). Sent as the `X-API-Key` header on every request. Obtain this from your organization's admin portal.

### Optional

`tenantId`
: **Type:** `string | null`
: **Default:** `null`
: Tenant UUID for multi-tenant search. When set, all API calls include `tenant_id` as a query parameter, scoping results to the tenant's code systems.

`defaultCodeSystem`
: **Type:** `string | null`
: **Default:** `null`
: Pre-filter searches to a specific code system by slug (e.g., `"icd10cm"`, `"cpt"`, `"loinc"`). Users can change this via the code system dropdown. Pass `null` to search across all code systems.

`debounceMs`
: **Type:** `number`
: **Default:** `300`
: Milliseconds to wait after the user stops typing before firing an autocomplete request. Lower values feel more responsive but generate more API calls.

`autocompleteMinChars`
: **Type:** `number`
: **Default:** `2`
: Minimum characters before autocomplete suggestions appear. Set higher to reduce noise on short inputs.

`searchResultsSize`
: **Type:** `number`
: **Default:** `20`
: Number of results per page for full search (triggered by pressing Enter). Valid range: 1–100.

`theme`
: **Type:** `"light" | "dark" | "auto"`
: **Default:** `"light"`
: Colour theme of the widget. `"auto"` follows the visitor's system preference. Does not affect the input element, which is part of your page.

## Callbacks

All callbacks receive the `instanceId` as the second argument, so you can distinguish which widget instance fired the event.

`onSelect(concept, instanceId)`
: Fired when the user selects a concept — from autocomplete, search results, or the detail panel.
: The `concept` object varies by source:

  **From autocomplete:**
  ```javascript
  {
    code: "E11.9",
    display: "Type 2 diabetes mellitus without complications",
    code_system_slug: "icd10cm",
    code_system_name: "ICD10-CM"
  }
  ```

  **From search results:**
  ```javascript
  {
    concept_id: "icd10cm-E11.9",
    code: "E11.9",
    display: "Type 2 diabetes mellitus without complications",
    code_system_slug: "icd10cm",
    code_system_name: "ICD10-CM",
    status: "active",
    score: 12.5,
    highlights: { display: ["Type 2 <em>diabetes</em> mellitus..."] }
  }
  ```

  **From concept detail:**
  ```javascript
  {
    concept_id: "icd10cm-E11.9",
    code: "E11.9",
    display: "Type 2 diabetes mellitus without complications",
    code_system_slug: "icd10cm",
    code_system_name: "ICD10-CM",
    version: "2024",
    status: "active",
    definition: "...",
    synonyms: ["DM2", "NIDDM"],
    parent_codes: ["E11"],
    child_codes: [],
    properties: {}
  }
  ```

`onSearchStart(query, instanceId)`
: Fired when a full search begins (user presses Enter). Use this to show loading indicators in your surrounding UI.

`onSearchEnd(total, instanceId)`
: Fired when search results arrive. `total` is the total number of matching concepts (not just the current page).

`onError(error, instanceId)`
: Fired on API errors. The `error` object has a `.message` property. Common errors:
  - `"Invalid API key"` — the key is missing, mistyped or revoked
  - `"Access denied — check your subscription plan"` — the plan does not include code system search
  - `"Rate limit exceeded — try again later"` — the plan's request limit was reached
  - `"API error: <status>"` — other errors from the service (see [Authentication](authentication.html))

## Handler Methods

### `CareConekt.CodeSystems.bind(ino)`

Initialize a widget instance. Finds the `<input class="ccs-input" data-ccs-ino="...">` and `<div class="ccs-window" data-ccs-ino="...">` elements, attaches Shadow DOM, and starts listening for user input.

```javascript
CareConekt.CodeSystems.bind("1");
```

**Throws** if `configure()` hasn't been called, or if the HTML elements aren't found.

### `CareConekt.CodeSystems.clear(ino)`

Clear the input, results, and selection for an instance.

```javascript
CareConekt.CodeSystems.clear("1");
```

### `CareConekt.CodeSystems.destroy(ino)`

Tear down an instance — removes event listeners, clears Shadow DOM content, and unregisters from the internal registry. The HTML elements remain in the page.

```javascript
CareConekt.CodeSystems.destroy("1");
```

### `CareConekt.CodeSystems.getSelection(ino)`

Returns the last selected concept object, or `null` if nothing has been selected.

```javascript
const concept = CareConekt.CodeSystems.getSelection("1");
if (concept) {
  console.log(concept.code, concept.display);
}
```

### `CareConekt.CodeSystems.setCodeSystem(ino, slug)`

Programmatically set the code system filter. Pass `null` to clear the filter.

```javascript
CareConekt.CodeSystems.setCodeSystem("1", "cpt");  // Filter to CPT codes
CareConekt.CodeSystems.setCodeSystem("1", null);    // Search all systems
```

### `CareConekt.CodeSystems.search(ino, query)`

Programmatically trigger a full search. Sets the input value and fires the search.

```javascript
CareConekt.CodeSystems.search("1", "diabetes");
```

### `CareConekt.CodeSystems.version`

Returns the widget version string.

```javascript
console.log(CareConekt.CodeSystems.version); // "0.1.0"
```

## Theming with CSS Custom Properties

Your page's CSS cannot accidentally break the widget. To change its colours and shadow, set these CSS custom properties on the `.ccs-window` element; the widget picks them up in every theme:

```css
.ccs-window[data-ccs-ino="1"] {
  --ccs-bg: #ffffff;
  --ccs-bg-hover: #f3f4f6;
  --ccs-bg-active: #e5e7eb;
  --ccs-text: #111827;
  --ccs-text-muted: #6b7280;
  --ccs-border: #d1d5db;
  --ccs-accent: #2563eb;
  --ccs-code-bg: #eff6ff;
  --ccs-code-text: #1e40af;
  --ccs-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
```

The input element is in your page's DOM — style it directly with your own CSS.