@mieweb/ui 0.11.0-dev.32 → 0.11.0-dev.33

package/dist/esheet.d.cts

@@ -3,6 +3,7 @@ export { FormDefinition } from '@esheet/core';
 import * as React from 'react';
 export { EsheetBuilder, EsheetBuilderProps } from '@esheet/builder';
 export { EsheetRenderer, EsheetRendererHandle, EsheetRendererProps } from '@esheet/renderer';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface CodifyResult {
     fullid: string;
@@ -732,8 +733,98 @@ declare function EncounterVitalsField({ field, response, isPreview, isEnabled, i
 /** Native eSheet adapter for the shared Assessment and plan editor. */
 declare function EncounterAssessmentField({ field, form, response, isPreview, isEnabled, isReadOnly, onResponse, }: FieldComponentProps): React.JSX.Element;
 
+/** Standard coding reference attached to a finding (SNOMED, ICD, …). */
+interface NarrativeCode {
+    system: string;
+    code: string;
+    display?: string;
+}
+/** Explicit quick selections; free prose never becomes a coded finding automatically. */
+interface NarrativeFinding {
+    id: string;
+    label: string;
+    text: string;
+    code?: NarrativeCode;
+}
+/**
+ * Response attribute names a narrative field publishes under. Hosts with a
+ * published attribute contract (e.g. EncounterVisit's `encounterNarrative*`)
+ * supply their own namespace; everyone else uses {@link NARRATIVE_ATTRIBUTES}.
+ */
+interface NarrativeAttributeNames {
+    /** Sanitized rich HTML mirroring the plain answer. */
+    html: string;
+    /** Plain text derived from the HTML; must equal the answer to be trusted. */
+    text: string;
+    /** JSON provenance of explicitly picked findings. */
+    findings: string;
+    /** Answer snapshot the findings provenance was recorded against. */
+    findingsText: string;
+}
+/** Default attribute namespace for the generic narrative field. */
+declare const NARRATIVE_ATTRIBUTES: NarrativeAttributeNames;
+/** Whitelist configured or persisted selection provenance, never arbitrary attributes. */
+declare function validNarrativeFindings(value: unknown): NarrativeFinding[];
+/** Match complete inserted lines, never a phrase inside unrelated free prose. */
+declare function hasNarrativeFindingText(answer: string, text: string): boolean;
+/** Codes represent explicit picks and are invalidated by external plain-answer edits. */
+declare function getNarrativeFindings(response?: FieldResponse, attributes?: NarrativeAttributeNames): NarrativeFinding[];
+/**
+ * The plain-response equivalent of an explicit quick-pick action, also used by
+ * MCP. Valid existing rich formatting is retained without needing a DOM.
+ */
+declare function applyNarrativeFinding(response: FieldResponse | undefined, finding: NarrativeFinding, attributes?: NarrativeAttributeNames): FieldResponse;
+
+/**
+ * EsheetNarrativeField — generic esheet-guided narrative field.
+ *
+ * A report-like rich text surface backed by eSheet text: the field rests as a
+ * plain one-line input, expands while the author writes, docks the section's
+ * common findings as a macro group (each with a derived dot-phrase), and
+ * records explicit finding picks as provenance on the response.
+ *
+ * The response attribute namespace, findings source, and styling slot are
+ * parameterized so hosts with a published contract (EncounterNarrativeField's
+ * `encounterNarrative*`) configure it without forking the behavior.
+ *
+ * Exposed via the `@mieweb/ui/esheet` entry point (NOT the main bundle) so
+ * that @esheet/* stays an optional dependency.
+ */
+
+/**
+ * Keep document formatting small: no links, media, styles, or imported
+ * document chrome. Every block format the editor's block menu and markdown
+ * shortcuts offer (headings 1–3, quote, lists) is allowed, so published
+ * formatting survives reopening the field.
+ */
+declare function sanitizeNarrativeHtml(html: string): string;
+/** Extract readable narrative text without flattening paragraphs or list items together. */
+declare function narrativeText(html: string): string;
+interface EsheetNarrativeFieldProps extends FieldComponentProps {
+    /** Response attribute namespace; defaults to {@link NARRATIVE_ATTRIBUTES}. */
+    attributes?: NarrativeAttributeNames;
+    /** `definition._sourceData` key holding the section's common findings. */
+    findingsKey?: string;
+    /** `definition._sourceData` key that hides the visible field label. */
+    hideLabelKey?: string;
+    /** `data-slot` value for host CSS hooks. */
+    slot?: string;
+}
 /** A report-like narrative surface that grows with its content, backed by eSheet text. */
-declare function EncounterNarrativeField({ field, response, isPreview, isEnabled, isReadOnly, isRequired, isSoftRequired, onResponse, }: FieldComponentProps): React.JSX.Element;
+declare function EsheetNarrativeField({ field, response, isPreview, isEnabled, isReadOnly, isRequired, isSoftRequired, onResponse, attributes, findingsKey, hideLabelKey, slot, }: EsheetNarrativeFieldProps): React.JSX.Element;
+/**
+ * Register the `esheetNarrative` field type with eSheet.
+ * Call once before rendering EsheetBuilder or EsheetRenderer. Hosts that
+ * already registered their own `esheetNarrative` component keep it.
+ */
+declare function registerEsheetNarrativeFieldType(): void;
+
+/**
+ * The generic EsheetNarrativeField configured for encounter visits: the
+ * published `encounterNarrative*` response attributes, findings sourced from
+ * the section definition's `encounterFindings`, and the encounter CSS slot.
+ */
+declare function EncounterNarrativeField(props: FieldComponentProps): React.JSX.Element;
 
 /** Register encounter fields when missing, retaining any host-supplied editors. */
 declare function registerEncounterFieldTypes(): void;
@@ -750,6 +841,99 @@ declare function EncounterConditionsField({ field, form, response, isPreview, is
 /** Native eSheet coded care orders, using the shared Assessment plan editor. */
 declare function EncounterPlanField({ field, form, response, isPreview, isEnabled, isReadOnly, onResponse, }: FieldComponentProps): React.JSX.Element;
 
+/** A person or system the document references, e.g. a patient and a provider. */
+interface RichTextEsheetParty {
+    /** Displayed role, e.g. "Patient", "Provider", "Reporter". */
+    role: string;
+    name: string;
+    /** Identifying line shown beside the name, e.g. a DOB, NPI or email. */
+    detail?: string;
+}
+interface RichTextEsheetSection {
+    id: string;
+    title: string;
+    /** Guidance shown above the section's field. */
+    description?: string;
+    /** Memory-aid phrases docked as macros, each with a derived dot-phrase. */
+    findings?: NarrativeFinding[];
+    /** Require content in this section before submitting. */
+    required?: boolean;
+    /**
+     * Registered custom eSheet field type for non-narrative sections. Defaults
+     * to the built-in guided narrative; any other value must be registered with
+     * `registerCustomFieldTypes` before the component mounts.
+     */
+    fieldType?: string;
+}
+/** Document sections and their memory aids; contains no identity data. */
+interface RichTextEsheetDefinition {
+    id: string;
+    title: string;
+    sections: RichTextEsheetSection[];
+}
+/** Native eSheet answers, keyed by generated field id. */
+type RichTextEsheetResponses = Record<string, FieldResponse>;
+interface RichTextEsheetIssue {
+    sectionId: string;
+    message: string;
+}
+interface RichTextEsheetSnapshot {
+    definition: RichTextEsheetDefinition;
+    /** Native eSheet responses — the canonical draft state. */
+    responses: RichTextEsheetResponses;
+    /** Ids of sections with recorded content. */
+    documentedSections: string[];
+    /** Required sections still missing content. */
+    errors: RichTextEsheetIssue[];
+    /** Portable document: YAML front matter + Markdown body. */
+    mdy: string;
+}
+/** Encode the identifier separately so punctuation cannot collide with delimiters. */
+declare function getRichTextEsheetFieldId(sectionId: string): string;
+declare function getRichTextEsheetSectionFieldId(sectionId: string): string;
+/** Reject ambiguous identifiers and invalid configuration before constructing an eSheet. */
+declare function validateRichTextEsheetDefinition(definition: RichTextEsheetDefinition): void;
+/** Each party becomes an insertable macro so authors can drop names into the text. */
+declare function partyFindings(parties: RichTextEsheetParty[] | undefined): NarrativeFinding[];
+/** All sections remain native eSheet sections with native FieldResponse values. */
+declare function createRichTextEsheetFormDefinition(definition: RichTextEsheetDefinition, parties?: RichTextEsheetParty[]): FormDefinition;
+/** Derive the full document state — progress, validation and portable MDY — from native responses. */
+declare function createRichTextEsheetSnapshot(definition: RichTextEsheetDefinition, responses: RichTextEsheetResponses, parties?: RichTextEsheetParty[]): RichTextEsheetSnapshot;
+
+interface RichTextEsheetProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'onSubmit' | 'title'> {
+    /** Document sections and their memory aids. */
+    definition: RichTextEsheetDefinition;
+    /**
+     * People or systems the document references — for example a patient and a
+     * provider on a letter, or a reporter and a system on a support ticket.
+     * Shown in the header, docked as insertable macros beside every narrative
+     * section, and retained in the exported document's front matter.
+     */
+    parties?: RichTextEsheetParty[];
+    /** Translate built-in labels and messages. */
+    messages?: ComponentMessages;
+    /** Loaded once per definition.id. Change the id to open another document. */
+    initialResponses?: RichTextEsheetResponses;
+    /** Every edit returns the same native eSheet responses. */
+    onChange?: (document: RichTextEsheetSnapshot) => void;
+    /** Host-owned persistence. Reject to keep the draft and show the failure. */
+    onSubmit?: (document: RichTextEsheetSnapshot) => void | Promise<void>;
+    readOnly?: boolean;
+}
+interface RichTextEsheetHandle {
+    getSnapshot: () => RichTextEsheetSnapshot;
+    focusSection: (sectionId: string) => void;
+}
+/**
+ * A guided rich text document backed by a native eSheet: letters, support
+ * tickets, any templated prose where an eSheet acts as the memory aid. Each
+ * section is a narrative field with docked finding macros; parties (patient,
+ * provider, reporter…) become insertable macros. For clinical visit
+ * documentation use EncounterVisit, which layers coded clinical sections on
+ * the same foundations.
+ */
+declare const RichTextEsheet: React.ForwardRefExoticComponent<RichTextEsheetProps & React.RefAttributes<RichTextEsheetHandle>>;
+
 /** Reconciliation status of a medication. */
 type MedicationStatus = 'unreconciled' | 'taking' | 'taking-noncompliant' | 'not-taking' | 'unknown';
 /** Coding-system reference for a medication (RxNorm / FDB / NDC …). */
@@ -1010,6 +1194,29 @@ declare function registerAllergyListFieldType(options?: {
     codeLookup?: CodeLookupConfig | false;
 }): void;
 
+type EsheetSectionFieldProps = FieldComponentProps & {
+    nestedChildren?: React.ReactNode;
+};
+/**
+ * Guided documents (RichTextEsheet, EncounterVisit) opt into the lightweight
+ * section chrome by providing `true`; everywhere else the stock eSheet
+ * SectionField renders unchanged.
+ */
+declare const EsheetSectionContext: React.Context<boolean>;
+/**
+ * Section renderer registered for guided documents: inside the document
+ * composition, preview-mode sections render as a plain labelled group
+ * (heading + always-visible children); builder mode and other hosts
+ * delegate to the stock SectionField.
+ */
+declare function EsheetSectionField(props: EsheetSectionFieldProps): react_jsx_runtime.JSX.Element;
+/**
+ * Take over the built-in section renderer (the component itself delegates to
+ * the stock SectionField outside EsheetSectionContext). Hosts that registered
+ * their own section component keep it.
+ */
+declare function registerEsheetSectionFieldType(): void;
+
 /**
  * registerMieEsheetFields — one-call registration for every @mieweb/ui custom
  * eSheet field type (medication reconciliation + allergy list).
@@ -1046,4 +1253,4 @@ interface RegisterMieEsheetFieldsOptions {
  */
 declare function registerMieEsheetFields(options?: RegisterMieEsheetFieldsOptions): void;
 
-export { AllergyListField, type AllergyListFieldValue, DEFAULT_ENCOUNTER_VISIT_DEFINITION, ENCOUNTER_DOCUMENT_FIELD_ID, ENCOUNTER_VISIT_SYSTEM_PROMPT, ENCOUNTER_VISIT_TOOL_DEFINITIONS, EXAMPLE_ENCOUNTER_VISIT_RESPONSES, EncounterAllergyField, EncounterAssessmentField, type EncounterAssessmentValue, type EncounterCode, EncounterConditionsField, type EncounterConditionsValue, type EncounterMdyDiagnostic, type EncounterMdyField, EncounterMedicationField, type MessageTranslator as EncounterMessageTranslator, type MessageValues as EncounterMessageValues, EncounterNarrativeField, type EncounterNarrativeFinding, type EncounterObservation, type EncounterObservationComponent, type EncounterObservationDefinition, EncounterPlanField, type EncounterPlanValue, type EncounterResponses, type EncounterSectionDefinition, type EncounterSectionKind, type EncounterValidationIssue, EncounterVisit, type EncounterVisitDefinition, type EncounterVisitHandle, type EncounterVisitMcpResult, type EncounterVisitMcpToolDefinition, type ComponentMessages as EncounterVisitMessages, type EncounterVisitMode, type EncounterVisitProps, type EncounterVisitSnapshot, type EncounterVisitToolErrorCode, type EncounterVisitToolOptions, type EncounterVisitToolResult, type EncounterVisitTools, type EncounterVitalInputDraft, type EncounterVitalNumericKey, type EncounterVitalReading, EncounterVitalsField, type EncounterVitalsValue, MedicationListField, type MedicationListFieldValue, type ParsedEncounterMdy, type RegisterMieEsheetFieldsOptions, createEncounterFormDefinition, createEncounterMdy, createEncounterSnapshot, createEncounterVisitTools, encounterDocumentResponse, executeEncounterVisitToolCall, getEncounterConcerns, getEncounterDocumentBody, getEncounterFieldId, getEncounterMdyFields, getEncounterSectionFieldId, getEncounterSectionFieldIds, parseEncounterAssessment, parseEncounterConditions, parseEncounterMdy, parseEncounterPlan, parseEncounterVitals, refreshEncounterMdyLinks, registerAllergyListFieldType, registerEncounterFieldTypes, registerMedicationListFieldType, registerMieEsheetFields, renderEncounterMdy, updateEncounterDocumentBody, validAssessmentItem, validateEncounterAllergyValue, validateEncounterAssessment, validateEncounterConditions, validateEncounterDefinition, validateEncounterMedicationValue, validateEncounterPlan, validateEncounterResponses, validateEncounterVitals };
+export { AllergyListField, type AllergyListFieldValue, DEFAULT_ENCOUNTER_VISIT_DEFINITION, ENCOUNTER_DOCUMENT_FIELD_ID, ENCOUNTER_VISIT_SYSTEM_PROMPT, ENCOUNTER_VISIT_TOOL_DEFINITIONS, EXAMPLE_ENCOUNTER_VISIT_RESPONSES, EncounterAllergyField, EncounterAssessmentField, type EncounterAssessmentValue, type EncounterCode, EncounterConditionsField, type EncounterConditionsValue, type EncounterMdyDiagnostic, type EncounterMdyField, EncounterMedicationField, type MessageTranslator as EncounterMessageTranslator, type MessageValues as EncounterMessageValues, EncounterNarrativeField, type EncounterNarrativeFinding, type EncounterObservation, type EncounterObservationComponent, type EncounterObservationDefinition, EncounterPlanField, type EncounterPlanValue, type EncounterResponses, type EncounterSectionDefinition, type EncounterSectionKind, type EncounterValidationIssue, EncounterVisit, type EncounterVisitDefinition, type EncounterVisitHandle, type EncounterVisitMcpResult, type EncounterVisitMcpToolDefinition, type ComponentMessages as EncounterVisitMessages, type EncounterVisitMode, type EncounterVisitProps, type EncounterVisitSnapshot, type EncounterVisitToolErrorCode, type EncounterVisitToolOptions, type EncounterVisitToolResult, type EncounterVisitTools, type EncounterVitalInputDraft, type EncounterVitalNumericKey, type EncounterVitalReading, EncounterVitalsField, type EncounterVitalsValue, EsheetNarrativeField, type EsheetNarrativeFieldProps, EsheetSectionContext, EsheetSectionField, MedicationListField, type MedicationListFieldValue, NARRATIVE_ATTRIBUTES, type NarrativeAttributeNames, type NarrativeCode, type NarrativeFinding, type ParsedEncounterMdy, type RegisterMieEsheetFieldsOptions, RichTextEsheet, type RichTextEsheetDefinition, type RichTextEsheetHandle, type RichTextEsheetIssue, type RichTextEsheetParty, type RichTextEsheetProps, type RichTextEsheetResponses, type RichTextEsheetSection, type RichTextEsheetSnapshot, applyNarrativeFinding, createEncounterFormDefinition, createEncounterMdy, createEncounterSnapshot, createEncounterVisitTools, createRichTextEsheetFormDefinition, createRichTextEsheetSnapshot, encounterDocumentResponse, executeEncounterVisitToolCall, getEncounterConcerns, getEncounterDocumentBody, getEncounterFieldId, getEncounterMdyFields, getEncounterSectionFieldId, getEncounterSectionFieldIds, getNarrativeFindings, getRichTextEsheetFieldId, getRichTextEsheetSectionFieldId, hasNarrativeFindingText, narrativeText, parseEncounterAssessment, parseEncounterConditions, parseEncounterMdy, parseEncounterPlan, parseEncounterVitals, partyFindings, refreshEncounterMdyLinks, registerAllergyListFieldType, registerEncounterFieldTypes, registerEsheetNarrativeFieldType, registerEsheetSectionFieldType, registerMedicationListFieldType, registerMieEsheetFields, renderEncounterMdy, sanitizeNarrativeHtml, updateEncounterDocumentBody, validAssessmentItem, validNarrativeFindings, validateEncounterAllergyValue, validateEncounterAssessment, validateEncounterConditions, validateEncounterDefinition, validateEncounterMedicationValue, validateEncounterPlan, validateEncounterResponses, validateEncounterVitals, validateRichTextEsheetDefinition };

package/dist/esheet.d.ts

@@ -3,6 +3,7 @@ export { FormDefinition } from '@esheet/core';
 import * as React from 'react';
 export { EsheetBuilder, EsheetBuilderProps } from '@esheet/builder';
 export { EsheetRenderer, EsheetRendererHandle, EsheetRendererProps } from '@esheet/renderer';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface CodifyResult {
     fullid: string;
@@ -732,8 +733,98 @@ declare function EncounterVitalsField({ field, response, isPreview, isEnabled, i
 /** Native eSheet adapter for the shared Assessment and plan editor. */
 declare function EncounterAssessmentField({ field, form, response, isPreview, isEnabled, isReadOnly, onResponse, }: FieldComponentProps): React.JSX.Element;
 
+/** Standard coding reference attached to a finding (SNOMED, ICD, …). */
+interface NarrativeCode {
+    system: string;
+    code: string;
+    display?: string;
+}
+/** Explicit quick selections; free prose never becomes a coded finding automatically. */
+interface NarrativeFinding {
+    id: string;
+    label: string;
+    text: string;
+    code?: NarrativeCode;
+}
+/**
+ * Response attribute names a narrative field publishes under. Hosts with a
+ * published attribute contract (e.g. EncounterVisit's `encounterNarrative*`)
+ * supply their own namespace; everyone else uses {@link NARRATIVE_ATTRIBUTES}.
+ */
+interface NarrativeAttributeNames {
+    /** Sanitized rich HTML mirroring the plain answer. */
+    html: string;
+    /** Plain text derived from the HTML; must equal the answer to be trusted. */
+    text: string;
+    /** JSON provenance of explicitly picked findings. */
+    findings: string;
+    /** Answer snapshot the findings provenance was recorded against. */
+    findingsText: string;
+}
+/** Default attribute namespace for the generic narrative field. */
+declare const NARRATIVE_ATTRIBUTES: NarrativeAttributeNames;
+/** Whitelist configured or persisted selection provenance, never arbitrary attributes. */
+declare function validNarrativeFindings(value: unknown): NarrativeFinding[];
+/** Match complete inserted lines, never a phrase inside unrelated free prose. */
+declare function hasNarrativeFindingText(answer: string, text: string): boolean;
+/** Codes represent explicit picks and are invalidated by external plain-answer edits. */
+declare function getNarrativeFindings(response?: FieldResponse, attributes?: NarrativeAttributeNames): NarrativeFinding[];
+/**
+ * The plain-response equivalent of an explicit quick-pick action, also used by
+ * MCP. Valid existing rich formatting is retained without needing a DOM.
+ */
+declare function applyNarrativeFinding(response: FieldResponse | undefined, finding: NarrativeFinding, attributes?: NarrativeAttributeNames): FieldResponse;
+
+/**
+ * EsheetNarrativeField — generic esheet-guided narrative field.
+ *
+ * A report-like rich text surface backed by eSheet text: the field rests as a
+ * plain one-line input, expands while the author writes, docks the section's
+ * common findings as a macro group (each with a derived dot-phrase), and
+ * records explicit finding picks as provenance on the response.
+ *
+ * The response attribute namespace, findings source, and styling slot are
+ * parameterized so hosts with a published contract (EncounterNarrativeField's
+ * `encounterNarrative*`) configure it without forking the behavior.
+ *
+ * Exposed via the `@mieweb/ui/esheet` entry point (NOT the main bundle) so
+ * that @esheet/* stays an optional dependency.
+ */
+
+/**
+ * Keep document formatting small: no links, media, styles, or imported
+ * document chrome. Every block format the editor's block menu and markdown
+ * shortcuts offer (headings 1–3, quote, lists) is allowed, so published
+ * formatting survives reopening the field.
+ */
+declare function sanitizeNarrativeHtml(html: string): string;
+/** Extract readable narrative text without flattening paragraphs or list items together. */
+declare function narrativeText(html: string): string;
+interface EsheetNarrativeFieldProps extends FieldComponentProps {
+    /** Response attribute namespace; defaults to {@link NARRATIVE_ATTRIBUTES}. */
+    attributes?: NarrativeAttributeNames;
+    /** `definition._sourceData` key holding the section's common findings. */
+    findingsKey?: string;
+    /** `definition._sourceData` key that hides the visible field label. */
+    hideLabelKey?: string;
+    /** `data-slot` value for host CSS hooks. */
+    slot?: string;
+}
 /** A report-like narrative surface that grows with its content, backed by eSheet text. */
-declare function EncounterNarrativeField({ field, response, isPreview, isEnabled, isReadOnly, isRequired, isSoftRequired, onResponse, }: FieldComponentProps): React.JSX.Element;
+declare function EsheetNarrativeField({ field, response, isPreview, isEnabled, isReadOnly, isRequired, isSoftRequired, onResponse, attributes, findingsKey, hideLabelKey, slot, }: EsheetNarrativeFieldProps): React.JSX.Element;
+/**
+ * Register the `esheetNarrative` field type with eSheet.
+ * Call once before rendering EsheetBuilder or EsheetRenderer. Hosts that
+ * already registered their own `esheetNarrative` component keep it.
+ */
+declare function registerEsheetNarrativeFieldType(): void;
+
+/**
+ * The generic EsheetNarrativeField configured for encounter visits: the
+ * published `encounterNarrative*` response attributes, findings sourced from
+ * the section definition's `encounterFindings`, and the encounter CSS slot.
+ */
+declare function EncounterNarrativeField(props: FieldComponentProps): React.JSX.Element;
 
 /** Register encounter fields when missing, retaining any host-supplied editors. */
 declare function registerEncounterFieldTypes(): void;
@@ -750,6 +841,99 @@ declare function EncounterConditionsField({ field, form, response, isPreview, is
 /** Native eSheet coded care orders, using the shared Assessment plan editor. */
 declare function EncounterPlanField({ field, form, response, isPreview, isEnabled, isReadOnly, onResponse, }: FieldComponentProps): React.JSX.Element;
 
+/** A person or system the document references, e.g. a patient and a provider. */
+interface RichTextEsheetParty {
+    /** Displayed role, e.g. "Patient", "Provider", "Reporter". */
+    role: string;
+    name: string;
+    /** Identifying line shown beside the name, e.g. a DOB, NPI or email. */
+    detail?: string;
+}
+interface RichTextEsheetSection {
+    id: string;
+    title: string;
+    /** Guidance shown above the section's field. */
+    description?: string;
+    /** Memory-aid phrases docked as macros, each with a derived dot-phrase. */
+    findings?: NarrativeFinding[];
+    /** Require content in this section before submitting. */
+    required?: boolean;
+    /**
+     * Registered custom eSheet field type for non-narrative sections. Defaults
+     * to the built-in guided narrative; any other value must be registered with
+     * `registerCustomFieldTypes` before the component mounts.
+     */
+    fieldType?: string;
+}
+/** Document sections and their memory aids; contains no identity data. */
+interface RichTextEsheetDefinition {
+    id: string;
+    title: string;
+    sections: RichTextEsheetSection[];
+}
+/** Native eSheet answers, keyed by generated field id. */
+type RichTextEsheetResponses = Record<string, FieldResponse>;
+interface RichTextEsheetIssue {
+    sectionId: string;
+    message: string;
+}
+interface RichTextEsheetSnapshot {
+    definition: RichTextEsheetDefinition;
+    /** Native eSheet responses — the canonical draft state. */
+    responses: RichTextEsheetResponses;
+    /** Ids of sections with recorded content. */
+    documentedSections: string[];
+    /** Required sections still missing content. */
+    errors: RichTextEsheetIssue[];
+    /** Portable document: YAML front matter + Markdown body. */
+    mdy: string;
+}
+/** Encode the identifier separately so punctuation cannot collide with delimiters. */
+declare function getRichTextEsheetFieldId(sectionId: string): string;
+declare function getRichTextEsheetSectionFieldId(sectionId: string): string;
+/** Reject ambiguous identifiers and invalid configuration before constructing an eSheet. */
+declare function validateRichTextEsheetDefinition(definition: RichTextEsheetDefinition): void;
+/** Each party becomes an insertable macro so authors can drop names into the text. */
+declare function partyFindings(parties: RichTextEsheetParty[] | undefined): NarrativeFinding[];
+/** All sections remain native eSheet sections with native FieldResponse values. */
+declare function createRichTextEsheetFormDefinition(definition: RichTextEsheetDefinition, parties?: RichTextEsheetParty[]): FormDefinition;
+/** Derive the full document state — progress, validation and portable MDY — from native responses. */
+declare function createRichTextEsheetSnapshot(definition: RichTextEsheetDefinition, responses: RichTextEsheetResponses, parties?: RichTextEsheetParty[]): RichTextEsheetSnapshot;
+
+interface RichTextEsheetProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'onSubmit' | 'title'> {
+    /** Document sections and their memory aids. */
+    definition: RichTextEsheetDefinition;
+    /**
+     * People or systems the document references — for example a patient and a
+     * provider on a letter, or a reporter and a system on a support ticket.
+     * Shown in the header, docked as insertable macros beside every narrative
+     * section, and retained in the exported document's front matter.
+     */
+    parties?: RichTextEsheetParty[];
+    /** Translate built-in labels and messages. */
+    messages?: ComponentMessages;
+    /** Loaded once per definition.id. Change the id to open another document. */
+    initialResponses?: RichTextEsheetResponses;
+    /** Every edit returns the same native eSheet responses. */
+    onChange?: (document: RichTextEsheetSnapshot) => void;
+    /** Host-owned persistence. Reject to keep the draft and show the failure. */
+    onSubmit?: (document: RichTextEsheetSnapshot) => void | Promise<void>;
+    readOnly?: boolean;
+}
+interface RichTextEsheetHandle {
+    getSnapshot: () => RichTextEsheetSnapshot;
+    focusSection: (sectionId: string) => void;
+}
+/**
+ * A guided rich text document backed by a native eSheet: letters, support
+ * tickets, any templated prose where an eSheet acts as the memory aid. Each
+ * section is a narrative field with docked finding macros; parties (patient,
+ * provider, reporter…) become insertable macros. For clinical visit
+ * documentation use EncounterVisit, which layers coded clinical sections on
+ * the same foundations.
+ */
+declare const RichTextEsheet: React.ForwardRefExoticComponent<RichTextEsheetProps & React.RefAttributes<RichTextEsheetHandle>>;
+
 /** Reconciliation status of a medication. */
 type MedicationStatus = 'unreconciled' | 'taking' | 'taking-noncompliant' | 'not-taking' | 'unknown';
 /** Coding-system reference for a medication (RxNorm / FDB / NDC …). */
@@ -1010,6 +1194,29 @@ declare function registerAllergyListFieldType(options?: {
     codeLookup?: CodeLookupConfig | false;
 }): void;
 
+type EsheetSectionFieldProps = FieldComponentProps & {
+    nestedChildren?: React.ReactNode;
+};
+/**
+ * Guided documents (RichTextEsheet, EncounterVisit) opt into the lightweight
+ * section chrome by providing `true`; everywhere else the stock eSheet
+ * SectionField renders unchanged.
+ */
+declare const EsheetSectionContext: React.Context<boolean>;
+/**
+ * Section renderer registered for guided documents: inside the document
+ * composition, preview-mode sections render as a plain labelled group
+ * (heading + always-visible children); builder mode and other hosts
+ * delegate to the stock SectionField.
+ */
+declare function EsheetSectionField(props: EsheetSectionFieldProps): react_jsx_runtime.JSX.Element;
+/**
+ * Take over the built-in section renderer (the component itself delegates to
+ * the stock SectionField outside EsheetSectionContext). Hosts that registered
+ * their own section component keep it.
+ */
+declare function registerEsheetSectionFieldType(): void;
+
 /**
  * registerMieEsheetFields — one-call registration for every @mieweb/ui custom
  * eSheet field type (medication reconciliation + allergy list).
@@ -1046,4 +1253,4 @@ interface RegisterMieEsheetFieldsOptions {
  */
 declare function registerMieEsheetFields(options?: RegisterMieEsheetFieldsOptions): void;
 
-export { AllergyListField, type AllergyListFieldValue, DEFAULT_ENCOUNTER_VISIT_DEFINITION, ENCOUNTER_DOCUMENT_FIELD_ID, ENCOUNTER_VISIT_SYSTEM_PROMPT, ENCOUNTER_VISIT_TOOL_DEFINITIONS, EXAMPLE_ENCOUNTER_VISIT_RESPONSES, EncounterAllergyField, EncounterAssessmentField, type EncounterAssessmentValue, type EncounterCode, EncounterConditionsField, type EncounterConditionsValue, type EncounterMdyDiagnostic, type EncounterMdyField, EncounterMedicationField, type MessageTranslator as EncounterMessageTranslator, type MessageValues as EncounterMessageValues, EncounterNarrativeField, type EncounterNarrativeFinding, type EncounterObservation, type EncounterObservationComponent, type EncounterObservationDefinition, EncounterPlanField, type EncounterPlanValue, type EncounterResponses, type EncounterSectionDefinition, type EncounterSectionKind, type EncounterValidationIssue, EncounterVisit, type EncounterVisitDefinition, type EncounterVisitHandle, type EncounterVisitMcpResult, type EncounterVisitMcpToolDefinition, type ComponentMessages as EncounterVisitMessages, type EncounterVisitMode, type EncounterVisitProps, type EncounterVisitSnapshot, type EncounterVisitToolErrorCode, type EncounterVisitToolOptions, type EncounterVisitToolResult, type EncounterVisitTools, type EncounterVitalInputDraft, type EncounterVitalNumericKey, type EncounterVitalReading, EncounterVitalsField, type EncounterVitalsValue, MedicationListField, type MedicationListFieldValue, type ParsedEncounterMdy, type RegisterMieEsheetFieldsOptions, createEncounterFormDefinition, createEncounterMdy, createEncounterSnapshot, createEncounterVisitTools, encounterDocumentResponse, executeEncounterVisitToolCall, getEncounterConcerns, getEncounterDocumentBody, getEncounterFieldId, getEncounterMdyFields, getEncounterSectionFieldId, getEncounterSectionFieldIds, parseEncounterAssessment, parseEncounterConditions, parseEncounterMdy, parseEncounterPlan, parseEncounterVitals, refreshEncounterMdyLinks, registerAllergyListFieldType, registerEncounterFieldTypes, registerMedicationListFieldType, registerMieEsheetFields, renderEncounterMdy, updateEncounterDocumentBody, validAssessmentItem, validateEncounterAllergyValue, validateEncounterAssessment, validateEncounterConditions, validateEncounterDefinition, validateEncounterMedicationValue, validateEncounterPlan, validateEncounterResponses, validateEncounterVitals };
+export { AllergyListField, type AllergyListFieldValue, DEFAULT_ENCOUNTER_VISIT_DEFINITION, ENCOUNTER_DOCUMENT_FIELD_ID, ENCOUNTER_VISIT_SYSTEM_PROMPT, ENCOUNTER_VISIT_TOOL_DEFINITIONS, EXAMPLE_ENCOUNTER_VISIT_RESPONSES, EncounterAllergyField, EncounterAssessmentField, type EncounterAssessmentValue, type EncounterCode, EncounterConditionsField, type EncounterConditionsValue, type EncounterMdyDiagnostic, type EncounterMdyField, EncounterMedicationField, type MessageTranslator as EncounterMessageTranslator, type MessageValues as EncounterMessageValues, EncounterNarrativeField, type EncounterNarrativeFinding, type EncounterObservation, type EncounterObservationComponent, type EncounterObservationDefinition, EncounterPlanField, type EncounterPlanValue, type EncounterResponses, type EncounterSectionDefinition, type EncounterSectionKind, type EncounterValidationIssue, EncounterVisit, type EncounterVisitDefinition, type EncounterVisitHandle, type EncounterVisitMcpResult, type EncounterVisitMcpToolDefinition, type ComponentMessages as EncounterVisitMessages, type EncounterVisitMode, type EncounterVisitProps, type EncounterVisitSnapshot, type EncounterVisitToolErrorCode, type EncounterVisitToolOptions, type EncounterVisitToolResult, type EncounterVisitTools, type EncounterVitalInputDraft, type EncounterVitalNumericKey, type EncounterVitalReading, EncounterVitalsField, type EncounterVitalsValue, EsheetNarrativeField, type EsheetNarrativeFieldProps, EsheetSectionContext, EsheetSectionField, MedicationListField, type MedicationListFieldValue, NARRATIVE_ATTRIBUTES, type NarrativeAttributeNames, type NarrativeCode, type NarrativeFinding, type ParsedEncounterMdy, type RegisterMieEsheetFieldsOptions, RichTextEsheet, type RichTextEsheetDefinition, type RichTextEsheetHandle, type RichTextEsheetIssue, type RichTextEsheetParty, type RichTextEsheetProps, type RichTextEsheetResponses, type RichTextEsheetSection, type RichTextEsheetSnapshot, applyNarrativeFinding, createEncounterFormDefinition, createEncounterMdy, createEncounterSnapshot, createEncounterVisitTools, createRichTextEsheetFormDefinition, createRichTextEsheetSnapshot, encounterDocumentResponse, executeEncounterVisitToolCall, getEncounterConcerns, getEncounterDocumentBody, getEncounterFieldId, getEncounterMdyFields, getEncounterSectionFieldId, getEncounterSectionFieldIds, getNarrativeFindings, getRichTextEsheetFieldId, getRichTextEsheetSectionFieldId, hasNarrativeFindingText, narrativeText, parseEncounterAssessment, parseEncounterConditions, parseEncounterMdy, parseEncounterPlan, parseEncounterVitals, partyFindings, refreshEncounterMdyLinks, registerAllergyListFieldType, registerEncounterFieldTypes, registerEsheetNarrativeFieldType, registerEsheetSectionFieldType, registerMedicationListFieldType, registerMieEsheetFields, renderEncounterMdy, sanitizeNarrativeHtml, updateEncounterDocumentBody, validAssessmentItem, validNarrativeFindings, validateEncounterAllergyValue, validateEncounterAssessment, validateEncounterConditions, validateEncounterDefinition, validateEncounterMedicationValue, validateEncounterPlan, validateEncounterResponses, validateEncounterVitals, validateRichTextEsheetDefinition };