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

# LoC History

> Read-only chronological list of all ASAM and LOCUS level-of-care assessments for a patient chart with step-up/step-down indicators.

The LoC History screen at `/cl/charts/:chartId/loc-history` lists every level-of-care (ASAM/LOCUS) assessment recorded for a patient chart, ordered newest-first, with trend indicators comparing each assessment to the prior one.

## Overview

The page calls `useLocAssessmentsByChart` which queries `cl_loc_assessments` ordered by `assessed_at` descending. For each row a `delta` is computed as `total_score` of the current row minus `total_score` of the next-older row in the sorted list. A `DirectionBadge` renders: "Step-up (+N)" in destructive style when delta > 0, "Step-down (N)" in success style when delta \< 0, or "Lateral" in outline style when delta = 0. The first row in the list always shows a dash (no prior to compare). Each card links to the assessment detail at `/cl/loc-assessments/:id` and shows recommended LoC code, final LoC code, total score, and status. Human-readable level labels are resolved from `ASAM_LOC_LABELS` or `LOCUS_LOC_LABELS` depending on `instrument_type`.

## Who it's for

Requires permission: `cl.loc_assessment.view`

## Before you start

* Must hold `cl.loc_assessment.view`.
* Navigate here from within a Patient Chart context via the chart's `/cl/charts/:chartId/loc-history` route.

## Steps

<Steps>
  <Step title="Open LoC History">Navigate to `/cl/charts/:chartId/loc-history` from within a patient chart context. The page loads all ASAM/LOCUS assessments for the chart, newest first.</Step>
  <Step title="Read trend indicators">Each card displays a `DirectionBadge` comparing its `total_score` to the next-older assessment: Step-up (higher score), Step-down (lower score), or Lateral (equal score). The most recent row shows a dash.</Step>
  <Step title="Review assessment details">Each card shows: instrument type (ASAM or LOCUS), assessment datetime, recommended LoC code with label, final LoC code with label, total score, and status badge.</Step>
  <Step title="Open assessment detail">Click the card title link to navigate to the full assessment detail at `/cl/loc-assessments/:id`.</Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Instrument types">
    Assessments use `instrument_type` of either `asam` or `locus`. The page resolves human-readable level labels from `ASAM_LOC_LABELS` for ASAM rows and `LOCUS_LOC_LABELS` for LOCUS rows.
  </Accordion>

  <Accordion title="Recommended vs. final LoC code">
    Each row exposes `recommended_loc_code` and `final_loc_code`. The page displays both; the preview card shows `final_loc_code ?? recommended_loc_code` as the "Final" value. SME: confirm clinical/regulatory distinction.
  </Accordion>

  <Accordion title="Step-up / step-down direction badge">
    The badge compares `total_score` between consecutive rows (newest-first ordering). Positive delta = step-up (higher intensity); negative delta = step-down; zero = lateral. The first row has no prior to compare and displays "—".
  </Accordion>

  <Accordion title="Empty state">
    When no assessments exist for the chart, an empty-state component is shown with the message "No assessments yet — No level-of-care assessments have been recorded for this chart."
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/cl.tsx
  * src/cores/cl/pages/LocAssessmentHistoryPage.tsx
  * src/cores/cl/hooks/useLocAssessments.ts
  * src/cores/cl/types/loc-assessment.ts
</Accordion>