Add ICD-10-CM branch and refinement navigation to Codify search using `@mieweb/ui`

[horner]

The design is grounded in the official CDC browser, which supports Alphabetic Index main-term and subterm search, switching between Index and Tabular views, fiscal-year selection, and display of instructional information. ([CDC][1])

As of July 24, 2026, the FY2026 April 1 update is the currently applicable release through September 30, 2026. FY2027 files have already been published for use beginning October 1, 2026, so the ticket requires release-aware data rather than hard-coding one release. ([CDC FTP][2])

---

Scope

• Primary implementation: @mieweb/codify
• Shared interface components: @mieweb/ui
• A linked mieweb/ui issue may be created if a reusable hierarchy or refinement navigator does not already exist.

Summary

Enhance the ICD-10-CM search experience so a broad clinical search does not end with a flat list of similar codes.

A search such as “diabetes” should let the user navigate the official clinical refinements documented in the ICD-10-CM Alphabetic Index, then verify the resulting destination in the Tabular List. The interface should expose parent-child relationships, reportability, cross-references, and applicable instructional notes.

Use @mieweb/ui for the search and refinement experience. Where the component library does not already support this interaction, add a reusable RefinementNavigator or equivalent component to mieweb/ui.

Problem

ICD-10-CM is not a dictionary where every diagnosis term maps directly to one code.

A broad term such as diabetes may need refinement by:

• Type or etiology
• Presence of a complication
• Affected body system
• Specific manifestation
• Additional-code or sequencing requirements
• Applicable instructional notes

A flat search result list creates several problems:

1. Users must scan many nearly identical descriptions.
2. Parent categories can appear indistinguishable from final reportable codes.
3. The clinical relationship between results is hidden.
4. Alphabetic Index suggestions may be mistaken for fully verified Tabular results.
5. Required notes such as Code first, Use additional code, or Excludes1 may be missed.
6. Users must already understand the code hierarchy to refine the search successfully.

The search should behave more like a guided classification navigator:

Broad clinical term
  → official Index refinement
    → more specific refinement
      → Tabular category
        → reportable code

User story

As a Codify user, I want to search for a broad diagnosis and progressively navigate its official ICD-10-CM refinements so that I can understand how a final code relates to the original clinical term and avoid treating a non-final category as a reportable code.

Proposed search experience

1. Preserve free-text and exact-code search

The existing search input should continue to support:

• Broad clinical terms
• Synonyms and indexed terminology
• Partial descriptions
• Exact codes
• Partial code prefixes

Exact-code lookup must remain fast and backward compatible.

2. Identify the source of every result

Search results should clearly distinguish between:

• Alphabetic Index main term
• Alphabetic Index subterm
• Tabular category
• Tabular subcategory
• Final reportable code

Use visible and programmatic labels such as Index, Tabular, Parent category, and Reportable.

3. Open broad results in a refinement navigator

Selecting an Index entry or non-leaf Tabular node should open a navigator rather than treating the selection as the final result.

The navigator should show:

• Current term or code
• Full breadcrumb path
• Parent or Back action
• Direct children and available refinements
• Whether the selected node is reportable
• Alphabetic Index cross-references
• Associated Tabular destination
• Loading, empty, and error states

4. Display applicable Tabular instructions

For the selected category, subcategory, or code, expose applicable instructional content, including:

• Includes
• Excludes1
• Excludes2
• Code first
• Use additional code
• Code also
• Placeholder requirements
• Seventh-character requirements
• Other applicable notes inherited from a parent node

The interface should make it clear whether a note is attached directly to the selected node or inherited from a parent category or chapter.

5. Preserve and share the path

The search query, release, selected node, and branch path should be represented in the URL or another stable deep-link format.

Example:

/search?q=diabetes&release=2026-apr&node=E11.42

A copied link should restore the same search and navigation state.

Diabetes acceptance scenario

Given a user searches for “diabetes”:

1. Search displays relevant Alphabetic Index entries and matching Tabular entries in clearly labeled groups.
2. Selecting the broad Index entry opens related subterms and refinements.
3. The user can navigate a conceptual path such as:

Diabetes
  → type 2
    → with neurological complication
      → polyneuropathy

4. The destination resolves to:

E11.42 — Type 2 diabetes mellitus with diabetic polyneuropathy

5. E11.42 is identified as reportable.
6. Applicable Tabular notes are displayed.
7. The breadcrumb preserves the route by which the user reached the code.
8. Alternate branches can be explored, including destinations such as:

E11.9  — Type 2 diabetes mellitus without complications
E11.65 — Type 2 diabetes mellitus with hyperglycemia

9. A subdivided parent such as E11.4 is shown as a navigable parent, not as a final reportable code.
10. The interface does not imply that one diabetes code necessarily describes all documented complications.

The exact branch labels and available refinements must come from the selected official ICD-10-CM release. Do not hard-code a diabetes-specific decision tree.

Data requirements

Preserve both official structures

The ingestion process must preserve:

Alphabetic Index

• Main terms
• Indented subterms
• Nested subterms
• Cross-references
• Code or category destinations
• Applicable conventions

Tabular List

• Chapters
• Blocks
• Categories
• Subcategories
• Reportable codes
• Parent-child relationships
• Instructional notes
• Inclusion and exclusion notes
• Additional-code and sequencing instructions
• Seventh-character requirements

Model the result as a graph

Do not derive the refinement structure only by splitting or comparing code prefixes.

Code prefixes may assist with indexing, but the official hierarchy must be authoritative. Alphabetic Index references, Tabular hierarchy, and cross-references mean the complete structure is better represented as a graph with hierarchical and cross-reference edges rather than as one strict tree.

Suggested normalized shape:

type Icd10CmNode = {
  id: string;
  release: string;
  effectiveFrom: string;
  effectiveTo?: string;

  source: 'index' | 'tabular';

  nodeType:
    | 'main-term'
    | 'subterm'
    | 'chapter'
    | 'block'
    | 'category'
    | 'subcategory'
    | 'code';

  code?: string;
  title: string;
  reportable?: boolean;

  parentId?: string;
  childIds: string[];

  path: Array<{
    id: string;
    label: string;
    code?: string;
  }>;

  notes?: {
    includes?: string[];
    excludes1?: string[];
    excludes2?: string[];
    codeFirst?: string[];
    useAdditionalCode?: string[];
    codeAlso?: string[];
    seventhCharacter?: string[];
    other?: string[];
  };

  crossReferences?: Array<{
    type: string;
    label: string;
    targetId?: string;
    targetCode?: string;
  }>;
};

Make releases version-aware

Every node should retain:

• Release identifier
• Effective start date
• Effective end date, where applicable
• Source artifact or source version

Requirements:

• Release data should be immutable after ingestion.
• Search should identify the release currently in use.
• Where Codify supports date-of-service workflows, the release should be selected from the date of service.
• Do not permanently hard-code the FY2026 April update.
• Future-effective releases may be preloaded but must not silently replace the current release before their effective date.

Load branches incrementally

Do not send the full ICD-10-CM graph to the browser for every search.

Provide indexed or cached operations equivalent to:

GET /icd10cm/search?q={query}&release={release}
GET /icd10cm/nodes/{nodeId}
GET /icd10cm/nodes/{nodeId}/children
GET /icd10cm/nodes/{nodeId}/path

The final API shape may differ, but it must support lazy child loading, path restoration, and release selection.

@mieweb/ui requirements

Use @mieweb/ui as the component source for the updated search experience. Reuse existing accessible equivalents for:

• Search input
• Buttons
• Cards or panels
• Badges and statuses
• Breadcrumbs
• Alerts
• Tooltips
• Disclosure controls
• Loading placeholders
• Visually hidden labels
• Theme and brand integration

The @mieweb/ui package is published as an accessible, themeable React component library with its own repository and documentation. ([npm][3])

Add a shared refinement component when necessary

If the library has no suitable hierarchy component, add a reusable component such as:

<RefinementNavigator
  nodes={nodes}
  selectedId={selectedId}
  expandedIds={expandedIds}
  onSelect={handleSelect}
  onExpand={handleExpand}
  loadChildren={loadChildren}
  renderNodeMetadata={renderNodeMetadata}
/>

The shared component should support:

• Controlled selected and expanded state
• Asynchronous child loading
• Breadcrumb or path-rendering hooks
• Optional badges and metadata
• Loading, empty, and error states
• Predictable focus restoration after asynchronous updates
• Responsive layouts
• Supported light, dark, and brand themes
• Storybook examples
• Unit tests
• Automated accessibility tests

Accessibility behavior

The interaction must be fully keyboard operable.

Depending on the final design, support appropriate behavior for:

• Arrow keys
• Home and End
• Enter and Space
• Escape or Back
• Roving focus
• Expanded and collapsed state
• Selected state
• Hierarchical level
• Live announcements when children finish loading

Use the WAI-ARIA pattern that accurately matches the implemented interaction. Do not add role="tree" merely to style a nested list. A disclosure/list pattern may be more appropriate if users move through one level at a time.

Safety and content behavior

Codify should expose and explain the official classification structure. It should not:

• Infer undocumented clinical facts
• Diagnose a condition from symptoms
• Silently select a complication
• Automatically choose a final code from an ambiguous term
• Treat an Alphabetic Index entry as sufficient Tabular verification
• Hide required coding instructions
• Imply that one selected code describes every documented condition or complication

When the user is navigating from an Index entry, show an explicit state such as:

Index result — verify destination and instructions in the Tabular List

Acceptance criteria

• Searching diabetes returns clearly labeled Index and Tabular results.
• Broad Index terms can be expanded into official subterms and refinements.
• Non-leaf Tabular categories can be expanded into their official children.
• The current branch path is visible as a breadcrumb or equivalent path control.
• Users can navigate to parent, child, and applicable cross-referenced nodes without restarting the search.
• Reportable codes and non-reportable parents are visually and programmatically distinguishable.
• The diabetes example can navigate to E11.42.
• E11.4 remains a navigable parent and is not presented as the final selection.
• Relevant inclusion, exclusion, sequencing, additional-code, and seventh-character notes are available where applicable.
• Alphabetic Index suggestions remain distinct from verified Tabular destinations.
• Search and branch state can be restored from a shared URL.
• The active ICD-10-CM release and effective dates are visible.
• The implementation uses official release hierarchy data rather than a curated diabetes-only menu.
• Child branches load incrementally without downloading the complete release for each search.
• Existing exact-code search remains backward compatible.
• The interface is fully keyboard operable.
• Automated accessibility checks pass.
• Parser tests cover Index hierarchy, Tabular hierarchy, cross-references, reportability, inherited notes, and malformed input.
• Integration tests cover the diabetes branch and direct-code lookup.
• @mieweb/ui Storybook and component tests cover the refinement-navigation states when a new shared component is introduced.

Suggested implementation slices

1. Official release ingestion

• Parse the official XML and table/index artifacts.
• Normalize Index and Tabular nodes.
• Preserve notes and cross-references.
• Store immutable release versions.
• Add parser fixtures and regression tests.

2. Search and branch API

• Return mixed Index and Tabular search results.
• Include source, node type, reportability, and release metadata.
• Add node, children, path, and cross-reference operations.
• Cache by release.

3. Codify search interface

• Add or update the @mieweb/ui dependency.
• Group search results by source.
• Add the refinement navigator and breadcrumb.
• Display reportability and instructional notes.
• Preserve search state in the URL.

4. Shared UI component

• Add RefinementNavigator, TreeNavigator, or an equivalent primitive to mieweb/ui when needed.
• Document its interaction model.
• Add Storybook, unit, keyboard, theme, and accessibility coverage.
• Publish and consume the resulting package release in Codify.

5. End-to-end validation

• Test broad-term search.
• Test exact-code search.
• Test asynchronous branch loading.
• Test release switching.
• Test deep-link restoration.
• Test desktop and mobile keyboard/focus behavior.
• Test the complete diabetes flow.

Non-goals

• Replacing coder or clinician judgment
• Diagnosing a patient
• Selecting a code without documented clinical details
• Hard-coding a diabetes questionnaire
• Treating the Alphabetic Index alone as final verification
• Automatically adding every potentially related code

Reference URLs

Official ICD-10-CM sources

CDC ICD-10-CM overview and browser information:

https://www.cdc.gov/nchs/icd/icd-10-cm/index.html

CDC ICD-10-CM browser:

https://icd10cmtool.cdc.gov/

CDC browser help:

https://icd10cmtool.cdc.gov/ICD-10-CM-Web-Help.pdf

CDC ICD-10-CM files page:

https://www.cdc.gov/nchs/icd/icd-10-cm/files.html

FY2026 April 1 update directory, effective through September 30, 2026:

https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/

FY2026 April 1 Official Coding Guidelines:

https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/ICD-10-CM%20April%201%202026%20Guidelines%20Final.pdf

FY2026 April 1 XML release:

https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/icd10cm-April-1-2026-XML.zip

FY2026 April 1 Tabular List and Alphabetic Index files:

https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/icd10cm-table-and-index-April-1-2026.zip

FY2026 April 1 code descriptions:

https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/icd10cm-Code%20Descriptions-April-1-2026.zip

FY2027 release directory, effective beginning October 1, 2026:

https://ftp.cdc.gov/pub/health_statistics/nchs/publications/ICD10CM/2027/

MIE UI sources

@mieweb/ui repository:

https://github.com/mieweb/ui

@mieweb/ui documentation:

https://ui.mieweb.org/

@mieweb/ui npm package:

https://www.npmjs.com/package/%40mieweb/ui

Accessibility reference

WAI-ARIA Authoring Practices tree-view pattern:

https://www.w3.org/WAI/ARIA/apg/patterns/treeview/

---

To file this issue through the connected GitHub account, the account must first be authorized for the MIE organization’s SAML SSO, and the actual repository URL associated with @mieweb/codify must be accessible.

[1]: https://www.cdc.gov/nchs/icd/icd-10-cm/index.html"ICD-10-CM | Classification of Diseases, Functioning, and Disability | CDC"
[2]: https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/ "ftp.cdc.gov - /pub/Health_Statistics/NCHS/Publications/ICD10CM/2026-update/"
[3]: https://www.npmjs.com/package/%40mieweb/ui "@mieweb/ui - npm"