Narrative API

Complete API reference for the Narrative component, which automatically generates human-readable clinical narratives from form responses.

Overview

The Narrative component:

Generates clinical narratives automatically from QuestionnaireResponse data
Updates in real-time as users fill out forms
Produces human-readable text suitable for clinical documentation
Integrates seamlessly with FormFiller
Supports custom formatting based on Questionnaire configuration

Constructor

Signature

new Narrative(config: NarrativeConfig): Narrative

Parameters

config NarrativeConfig (required)

Configuration object with the following properties:

Property	Type	Required	Description
`filler`	`FormFiller`	Yes	FormFiller instance to generate narrative from
`visualize`	`boolean`	No	Enable visualization border (default: false)

Basic Example

import { FormFiller, Narrative } from '@tiro-health/web-sdk'

const filler = new FormFiller({
  questionnaire: 'clinical-assessment',
  sdcEndpoint: { /* ... */ }
})

const narrative = new Narrative({
  filler: filler
})

Configuration Options

filler

Type: FormFiller (required)

The FormFiller instance to generate narrative text from.

const filler = new FormFiller({ /* ... */ })

const narrative = new Narrative({
  filler: filler
})

How it works:

Listens to filler's onChange events
Generates narrative from current QuestionnaireResponse
Updates automatically as user fills the form
Uses Questionnaire structure for formatting

visualize

Type: boolean (optional, default: false)

Enable colored border around the component for development and debugging.

visualize: import.meta.env.DEV  // Enable in development only

Methods

mount()

Mounts the Narrative component to a DOM element.

Signature:

mount(element: HTMLElement): void

Parameters:

element: DOM element to mount the narrative into

Example:

const container = document.getElementById('narrative-container')
narrative.mount(container)

What it displays:

Real-time clinical narrative text
Formatted based on Questionnaire structure
Updates as user answers questions
Empty state when no answers provided

unmount()

Unmounts the Narrative component and cleans up resources.

Signature:

unmount(): void

Example:

narrative.unmount()

Cleanup performed:

Removes all DOM elements
Stops listening to filler changes
Clears event listeners
Frees memory

Use Cases

Clinical Documentation

Generate clinical notes automatically from patient questionnaires:

const filler = new FormFiller({
  questionnaire: 'patient-assessment',
  sdcEndpoint: { /* ... */ }
})

const narrative = new Narrative({ filler })

filler.mount(document.getElementById('form'))
narrative.mount(document.getElementById('clinical-note'))

// As patient answers questions, clinical note updates automatically

Progress Review

Show patients a summary of their responses:

const filler = new FormFiller({
  questionnaire: 'health-screening',
  sdcEndpoint: { /* ... */ }
})

const narrative = new Narrative({ filler })

// Split layout: form on left, narrative on right
filler.mount(document.getElementById('form-column'))
narrative.mount(document.getElementById('summary-column'))

Report Generation

Extract narrative for reports and documentation:

const filler = new FormFiller({
  questionnaire: 'discharge-summary',
  sdcEndpoint: { /* ... */ },
  onSubmit: (response) => {
    // Get the narrative text
    const narrativeText = extractNarrativeText()

    // Include in report
    generateReport({
      response: response,
      narrative: narrativeText
    })
  }
})

const narrative = new Narrative({ filler })
narrative.mount(document.getElementById('narrative'))

Examples

Basic Integration

import { FormFiller, Narrative } from '@tiro-health/web-sdk'

// Create FormFiller
const filler = new FormFiller({
  questionnaire: 'symptom-checker',
  sdcEndpoint: {
    resourceType: 'Endpoint',
    address: 'https://sdc.example.com/fhir'
  }
})

// Create Narrative
const narrative = new Narrative({
  filler: filler,
  visualize: import.meta.env.DEV
})

// Mount both components
filler.mount(document.getElementById('form'))
narrative.mount(document.getElementById('narrative'))

Side-by-Side Layout

<div class="container">
  <div class="form-column">
    <h2>Patient Questionnaire</h2>
    <div id="form"></div>
  </div>

  <div class="narrative-column">
    <h2>Clinical Summary</h2>
    <div id="narrative"></div>
  </div>
</div>

<style>
  .container {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 2rem;
  }

  .narrative-column {
    background: #f5f5f5;
    padding: 1.5rem;
    border-radius: 8px;
  }
</style>

<script type="module">
  import { FormFiller, Narrative } from '@tiro-health/web-sdk'

  const filler = new FormFiller({ /* ... */ })
  const narrative = new Narrative({ filler })

  filler.mount(document.getElementById('form'))
  narrative.mount(document.getElementById('narrative'))
</script>

React Integration

import { useEffect, useRef } from 'react'
import { FormFiller, Narrative } from '@tiro-health/web-sdk'

export function FormWithNarrative() {
  const formRef = useRef<HTMLDivElement>(null)
  const narrativeRef = useRef<HTMLDivElement>(null)
  const fillerRef = useRef<FormFiller | null>(null)
  const narrativeCompRef = useRef<Narrative | null>(null)

  useEffect(() => {
    if (!formRef.current || !narrativeRef.current) return

    // Create components
    const filler = new FormFiller({
      questionnaire: 'patient-intake',
      sdcEndpoint: { /* ... */ }
    })

    const narrative = new Narrative({
      filler: filler,
      visualize: import.meta.env.DEV
    })

    // Mount
    filler.mount(formRef.current)
    narrative.mount(narrativeRef.current)

    // Store refs
    fillerRef.current = filler
    narrativeCompRef.current = narrative

    // Cleanup
    return () => {
      filler.unmount()
      narrative.unmount()
    }
  }, [])

  return (
    <div className="form-with-narrative">
      <div className="form-section">
        <h2>Questionnaire</h2>
        <div ref={formRef} />
      </div>

      <div className="narrative-section">
        <h2>Clinical Summary</h2>
        <div ref={narrativeRef} />
      </div>
    </div>
  )
}

Angular Integration

import { Component, AfterViewInit, OnDestroy, ViewChild, ElementRef } from '@angular/core'
import { FormFiller, Narrative } from '@tiro-health/web-sdk'

@Component({
  selector: 'app-form-with-narrative',
  templateUrl: './form-with-narrative.component.html',
  styleUrls: ['./form-with-narrative.component.css']
})
export class FormWithNarrativeComponent implements AfterViewInit, OnDestroy {
  @ViewChild('formContainer') formContainer!: ElementRef
  @ViewChild('narrativeContainer') narrativeContainer!: ElementRef

  private filler?: FormFiller
  private narrative?: Narrative

  ngAfterViewInit(): void {
    this.filler = new FormFiller({
      questionnaire: 'patient-intake',
      sdcEndpoint: { /* ... */ }
    })

    this.narrative = new Narrative({
      filler: this.filler
    })

    this.filler.mount(this.formContainer.nativeElement)
    this.narrative.mount(this.narrativeContainer.nativeElement)
  }

  ngOnDestroy(): void {
    this.filler?.unmount()
    this.narrative?.unmount()
  }
}

With All Components

import {
  FormFiller,
  LaunchContextProvider,
  Narrative,
  ValidationFeedback
} from '@tiro-health/web-sdk'

// Create FormFiller
const filler = new FormFiller({
  questionnaire: 'comprehensive-assessment',
  sdcEndpoint: { /* ... */ }
})

// Create supporting components
const contextProvider = new LaunchContextProvider({
  dataEndpoint: { /* ... */ },
  filler: filler,
  patientId: 'patient-123'
})

const narrative = new Narrative({ filler })
const validation = new ValidationFeedback({ filler })

// Mount all components
contextProvider.mount(document.getElementById('context'))
filler.mount(document.getElementById('form'))
narrative.mount(document.getElementById('narrative'))
validation.mount(document.getElementById('validation'))

// Cleanup
window.addEventListener('beforeunload', () => {
  contextProvider.unmount()
  filler.unmount()
  narrative.unmount()
  validation.unmount()
})

Next Steps

Learn about FormFiller for complete form capabilities
Explore ValidationFeedback for real-time validation
See LaunchContextProvider for patient context
Check integration guides for framework patterns

For questions or support, please contact the Tiro.health team.