> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samplehc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Building screens with the SampleHC UI Library - a collection of React components built on shadcn/ui

## Overview

The Sample UI Library is a comprehensive collection of React components and hooks designed specifically for building workflow screens in the SampleHC platform. Built on top of [shadcn/ui](https://ui.shadcn.com/), it provides both low-level UI primitives and high-level, domain-specific components for healthcare workflows.

## Getting Started

All workflow templates come with the Sample UI library pre-configured. To use any component in your screen:

<CodeGroup>
  ```tsx React Screen Component theme={null}
  import { Button } from "@/components/ui/button";
  import { Card } from "@/components/ui/card";
  import { Form, RichTextEditor } from "@samplehc/ui/components";
  import { useTaskState } from "@samplehc/ui/data";
  import { useScreenFunctions } from "@samplehc/ui/contexts";

  export default function MyWorkflowScreen() {
    const [data, setData] = useTaskState("formData", {});
    const { handleComplete } = useScreenFunctions();

    return (
      <Card className="p-6">
        <Form 
          elements={[
            { type: "text", key: "patientName", label: "Patient Name" },
            { type: "document", key: "records", label: "Medical Records" }
          ]}
          onSubmit={(results) => {
            setData(results);
            handleComplete({ result: results });
          }}
        />
      </Card>
    );
  }
  ```

  ```tsx Import Patterns theme={null}
  // UI Primitives (shadcn/ui)
  import { Button, Card, Input, Dialog } from "@/components/ui";

  // Sample Components
  import { Form, RichTextEditor, PayerSearchCombobox } from "@samplehc/ui/components";

  // Data Hooks
  import { useTaskState, useDocumentUpload } from "@samplehc/ui/data";

  // Utility Hooks
  import { useDebounce } from "@samplehc/ui";

  // Contexts and Providers
  import { useScreenFunctions, useBackendConfig } from "@samplehc/ui/contexts";
  ```
</CodeGroup>

## Pre-installed Components

The following shadcn/ui components are pre-installed and available in every workflow template:

<Note>
  Older workflows built from the previous templates may not have all components available - please use the `shadcn` CLI to install any packages you need.
</Note>

## Workflow Integration

### Screen Functions

The `useScreenFunctions` hook provides essential workflow operations:

```tsx theme={null}
import { useScreenFunctions } from "@samplehc/ui/contexts";

function MyScreen() {
  const { handleComplete, handleCancel, isCompleting, taskId } = useScreenFunctions();

  const onSubmit = async (formData) => {
    await handleComplete({ result: formData });
  };

  return (
    <Button 
      onClick={onSubmit} 
      disabled={isCompleting}
    >
      {isCompleting ? "Processing..." : "Complete Task"}
    </Button>
  );
}
```

### Task State Management

As React components are stateless by default, the SampleHC UI library provides a hook to persist data across workflow steps.

```tsx theme={null}
import { useTaskState } from "@samplehc/ui/data";

function MyScreen() {
  // Automatically syncs with backend
  const [patientData, setPatientData] = useTaskState("patient", {
    name: "",
    age: null,
    records: []
  });

  return (
    <Form 
      onSubmit={(data) => setPatientData(data)}
      defaultValues={patientData}
    />
  );
}
```

## Data Fetching Hooks

Hooks for API integration and data management:

<Accordion title="Document Management Hooks">
  * `useDocumentUpload()` - Upload documents to the platform
  * `useDocumentMetadata(documentId)` - Fetch document metadata
  * `useDocuments(documentIds)` - Fetch multiple documents
  * `useDocumentExtractionResult(resultId)` - Monitor extraction results
</Accordion>

<Accordion title="Task & Workflow Hooks">
  * `useTaskState(key, initialValue)` - Persistent task state
  * `useFullTaskState(taskId)` - Complete task state object
  * `useTaskSuspendedPayload(taskId)` - Suspended task details
  * `useCompleteMutation()` - Complete workflow tasks
  * `useCancelMutation()` - Cancel workflow tasks
</Accordion>

<Accordion title="Search & Classification">
  * `useDocumentSearch()` - Search across documents
  * `usePayerSearch(query)` - Search healthcare payers
  * `useDocumentClassificationResult()` - Document classification results
</Accordion>

## Utility Hooks

Additional hooks for common patterns:

* **`useDebounce(value, delay)`** - Debounce rapidly changing values
* **`useLocalStorage(key, initialValue)`** - Persist data in browser storage

## Sample Components

Specialized components built for healthcare workflows:

<CardGroup cols={2}>
  <Card title="Form Component" icon="clipboard-list" href="/screens/ui-components/form">
    Advanced form builder with document upload, CSV processing, and validation.
  </Card>

  <Card title="Rich Text Editor" icon="letter-text" href="/screens/ui-components/rich-text-editor">
    Tiptap-based editor with healthcare-specific extensions and citation support.
  </Card>

  <Card title="Payer Search" icon="search" href="/screens/ui-components/payer-search">
    Searchable combobox for finding healthcare payers with autocomplete.
  </Card>

  <Card title="PDF Viewer" icon="file-text" href="/screens/ui-components/pdf-viewer">
    Interactive PDF viewer with annotation and highlighting capabilities.
  </Card>

  <Card title="Document Viewer" icon="file" href="/screens/ui-components/document-viewer">
    Unified viewer for various document types including PDFs and FHIR data.
  </Card>
</CardGroup>

## Configuration

The UI library is configured automatically in workflow templates through providers:

```tsx theme={null}
import { Providers } from "@samplehc/ui/contexts";

// This is already set up in your workflow template
function App() {
  return (
    <Providers>
      <YourWorkflowScreens />
    </Providers>
  );
}
```

This includes React Query for data fetching, backend configuration, and screen function contexts.