@cdc/map 4.26.3 → 4.26.4

package/src/helpers/countyTerritories.ts

@@ -0,0 +1,38 @@
+export const US_TERRITORY_STATE_FIPS_PREFIXES = new Set(['60', '66', '69', '78'])
+
+export type CountyTerritoryVisibility = {
+  showTerritories: boolean
+  statePrefixes: Set<string>
+  countyIds: Set<string>
+  key: string
+}
+
+export const getCountyTerritoryVisibility = (
+  territoriesAlwaysShow: boolean | undefined,
+  runtimeData?: Record<string, any>
+): CountyTerritoryVisibility => {
+  const countyIds = new Set<string>()
+  const statePrefixes = new Set<string>()
+
+  if (runtimeData) {
+    Object.keys(runtimeData).forEach(key => {
+      if (key.length <= 2) return
+
+      const statePrefix = key.slice(0, 2)
+      if (!US_TERRITORY_STATE_FIPS_PREFIXES.has(statePrefix)) return
+
+      countyIds.add(key)
+      statePrefixes.add(statePrefix)
+    })
+  }
+
+  const showTerritories = territoriesAlwaysShow !== false && countyIds.size > 0
+  const key = `${showTerritories}:${showTerritories ? Array.from(countyIds).sort().join(',') : ''}`
+
+  return {
+    showTerritories,
+    statePrefixes,
+    countyIds,
+    key
+  }
+}

package/src/helpers/dataTableHelpers.ts

@@ -1,6 +1,6 @@
 import {
   stateFipsToTwoDigit as stateFipsToAbbreviation,
-  supportedStatesFipsCodes as supportedStateCodes
+  supportedStatesFipsCodes as supportedStateFipsCodes
 } from '../data/supported-geos'
 
 /**
@@ -13,18 +13,46 @@ export const shouldShowDataTable = (config: any, table: any, general: any, loadi
 /**
  * Filters county runtime data to a selected state code for data table display.
  * Keeps the original non-enumerable fromHash metadata when present.
+ * Fail-safe: if no recognizable state columns exist in the data, returns original
+ * data unfiltered (avoids breaking misconfigured datasets). If valid state columns
+ * exist but a state has no data, returns empty result as expected.
  */
 export const filterCountyTableRuntimeDataByStateCode = (runtimeData: any, stateCode: string, config?: any) => {
   if (!runtimeData || runtimeData.init || !stateCode) return runtimeData
 
-  const filtered = {}
-  const stateName = supportedStateCodes[stateCode]
-  const stateAbbreviation = stateFipsToAbbreviation[stateCode]
+  const runtimeKeys = Object.keys(runtimeData)
+  if (runtimeKeys.length === 0) return runtimeData
+
+  const stateName = supportedStateFipsCodes?.[stateCode]
+  const stateAbbreviation = stateFipsToAbbreviation?.[stateCode]
   const normalizedSelectedStateCode = String(stateCode).replace(/^0+/, '')
   const paddedSelectedStateCode = normalizedSelectedStateCode.padStart(2, '0')
   const stateColumnNames = Object.values(config?.columns || {})
     .map((column: any) => column?.name)
-    .filter((name: string) => !!name && /(state|territory|fips)/i.test(name))
+    .filter((name: string) => !!name && /(state|territory|fips|jurisdiction)/i.test(name))
+
+  // Also check common state field names directly in the data rows
+  const commonStateFieldNames = [
+    'jurisdiction',
+    'state',
+    'State',
+    'state_name',
+    'stateName',
+    'State/Territory',
+    'state_territory_name'
+  ]
+  const allStateColumns = [...new Set([...stateColumnNames, ...commonStateFieldNames])]
+
+  // Fail-safe: check if UIDs look like county FIPS codes (5 digits) OR if any state column exists in the data
+  const hasCountyFipsUids = runtimeKeys.some(uid => /^\d{5}$/.test(String(uid)))
+  const hasStateColumn = runtimeKeys.some(uid => allStateColumns.some(col => runtimeData[uid]?.[col] !== undefined))
+
+  // If data has neither county FIPS UIDs nor any recognizable state columns, don't filter
+  if (!hasCountyFipsUids && !hasStateColumn) {
+    return runtimeData
+  }
+
+  const filtered = {}
 
   if (runtimeData.fromHash !== undefined) {
     Object.defineProperty(filtered, 'fromHash', {
@@ -38,7 +66,8 @@ export const filterCountyTableRuntimeDataByStateCode = (runtimeData: any, stateC
     const normalizedUidPrefix = uidPrefix.startsWith('0') ? uidPrefix.slice(1) : uidPrefix
     const matchesUidPrefix =
       uidPrefix === paddedSelectedStateCode || normalizedUidPrefix === normalizedSelectedStateCode
-    const matchesStateColumn = stateColumnNames.some((columnName: string) => {
+
+    const matchesStateColumn = allStateColumns.some((columnName: string) => {
       const rawValue = row?.[columnName]
       if (rawValue === undefined || rawValue === null) return false
 

package/src/helpers/tests/countyTerritories.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import { getCountyTerritoryVisibility } from '../countyTerritories'
+
+describe('countyTerritories', () => {
+  it('collects visible territory prefixes and county ids from runtime data', () => {
+    const runtimeData = {
+      '06001': { uid: '06001', value: 1 },
+      '72001': { uid: '72001', value: 2 }
+    }
+
+    const visibility = getCountyTerritoryVisibility(true, runtimeData)
+
+    expect(visibility.showTerritories).toBe(true)
+    expect(Array.from(visibility.statePrefixes).sort()).toEqual(['72'])
+    expect(Array.from(visibility.countyIds).sort()).toEqual(['72001'])
+    expect(visibility.key).toBe('true:72001')
+  })
+
+  it('collects multiple territory prefixes and ignores non-territory counties', () => {
+    const runtimeData = {
+      '72001': { uid: '72001', value: 1 },
+      '72003': { uid: '72003', value: 2 },
+      '78010': { uid: '78010', value: 3 },
+      '06001': { uid: '06001', value: 4 }
+    }
+
+    const visibility = getCountyTerritoryVisibility(true, runtimeData)
+
+    expect(Array.from(visibility.statePrefixes).sort()).toEqual(['72', '78'])
+    expect(Array.from(visibility.countyIds).sort()).toEqual(['72001', '72003', '78010'])
+    expect(visibility.key).toBe('true:72001,72003,78010')
+  })
+
+  it('hides county territories when the config flag is disabled even if territory data exists', () => {
+    const runtimeData = {
+      '72001': { uid: '72001', value: 1 }
+    }
+
+    const visibility = getCountyTerritoryVisibility(false, runtimeData)
+
+    expect(visibility.showTerritories).toBe(false)
+    expect(Array.from(visibility.statePrefixes).sort()).toEqual(['72'])
+    expect(Array.from(visibility.countyIds).sort()).toEqual(['72001'])
+    expect(visibility.key).toBe('false:')
+  })
+
+  it('hides county territories when the config flag is enabled but no territory data exists', () => {
+    const runtimeData = {
+      '06001': { uid: '06001', value: 1 }
+    }
+
+    const visibility = getCountyTerritoryVisibility(true, runtimeData)
+
+    expect(visibility.showTerritories).toBe(false)
+    expect(Array.from(visibility.statePrefixes).sort()).toEqual([])
+    expect(Array.from(visibility.countyIds).sort()).toEqual([])
+    expect(visibility.key).toBe('false:')
+  })
+
+  it('treats an omitted config flag as enabled by default but still hides territories when no territory data exists', () => {
+    const runtimeData = {
+      '06001': { uid: '06001', value: 1 }
+    }
+
+    const visibility = getCountyTerritoryVisibility(undefined, runtimeData)
+
+    expect(visibility.showTerritories).toBe(false)
+    expect(Array.from(visibility.statePrefixes)).toEqual([])
+    expect(Array.from(visibility.countyIds)).toEqual([])
+    expect(visibility.key).toBe('false:')
+  })
+
+  it('changes the key when visible territory county ids change within the same territory prefix', () => {
+    const firstVisibility = getCountyTerritoryVisibility(true, {
+      '72001': { uid: '72001', value: 1 }
+    })
+    const secondVisibility = getCountyTerritoryVisibility(true, {
+      '72003': { uid: '72003', value: 1 }
+    })
+
+    expect(Array.from(firstVisibility.statePrefixes)).toEqual(['72'])
+    expect(Array.from(secondVisibility.statePrefixes)).toEqual(['72'])
+    expect(firstVisibility.key).toBe('true:72001')
+    expect(secondVisibility.key).toBe('true:72003')
+    expect(firstVisibility.key).not.toBe(secondVisibility.key)
+  })
+})

package/src/hooks/useApplyTooltipsToGeo.tsx

@@ -1,8 +1,7 @@
 import { type ReactNode, useContext } from 'react'
-import { displayGeoName, navigationHandler } from '../helpers'
+import { navigationHandler } from '../helpers'
 import ConfigContext from '../context'
 import useTooltip from './useTooltip'
-import { supportedStatesFipsCodes } from './../data/supported-geos'
 import parse from 'html-react-parser'
 import isDomainExternal from '@cdc/core/helpers/isDomainExternal'
 import ExternalIcon from './../images/external-link.svg'
@@ -10,7 +9,7 @@ import ExternalIcon from './../images/external-link.svg'
 const useApplyTooltipsToGeo = () => {
   const { config, customNavigationHandler } = useContext(ConfigContext)
   const navigationColumnName = config.columns.navigate.name
-  const { buildTooltip } = useTooltip({ config, displayGeoName, supportedStatesFipsCodes })
+  const { buildTooltip } = useTooltip(config)
 
   const applyTooltipsToGeo = (geoName: string, row: Object, returnType = 'string') => {
     let toolTipText: string | ReactNode = buildTooltip(row, geoName, '')
@@ -18,7 +17,11 @@ const useApplyTooltipsToGeo = () => {
     // We convert the markup into JSX and add a navigation link if it's going into a modal.
     if ('jsx' === returnType) {
       if (typeof toolTipText === 'string') {
-        toolTipText = [<div key='modal-content'>{parse(toolTipText)}</div>]
+        toolTipText = [
+          <div key='modal-content' className='cove-prose'>
+            {parse(toolTipText)}
+          </div>
+        ]
       }
 
       if (config.columns.hasOwnProperty('navigate') && row[navigationColumnName]) {

package/src/hooks/useMapLayers.tsx

@@ -53,7 +53,7 @@ export default function useMapLayers(config: MapConfig, setConfig, pathGenerator
     setConfig(newConfig)
   }
 
-  const handleAddLayer = (e: Event) => {
+  const handleAddLayer = (e: MouseEvent<HTMLButtonElement>) => {
     e.preventDefault()
     const placeHolderLayer = {
       name: 'New Custom Layer',

package/src/hooks/useTooltip.ts

@@ -1,9 +1,9 @@
 import { displayDataAsText } from '@cdc/core/helpers/displayDataAsText'
 import { displayGeoName } from '../helpers/displayGeoName'
+import { MapConfig } from '../types/MapConfig'
+import { supportedStatesFipsCodes } from '../data/supported-geos'
 
-const useTooltip = props => {
-  const { config, supportedStatesFipsCodes } = props
-
+const useTooltip = (config: MapConfig) => {
   /**
    * On county maps there's a need to append the state name
    * @param {String} toolTipText - previous tooltip text to build upon
@@ -11,17 +11,25 @@ const useTooltip = props => {
    * @returns {String} toolTipText - new toolTipText
    */
   const handleTooltipStateNameColumn = (toolTipText, row) => {
-    const { geoType, type, hideGeoColumnInTooltip } = config.general
+    const { geoType, type, hideGeoColumnInTooltip, showHSABoundaries } = config.general
     if (geoType === 'us-county' && type !== 'us-geocode') {
       let stateFipsCode = row[config.columns.geo.name].substring(0, 2)
       const stateName = supportedStatesFipsCodes[stateFipsCode]
-      toolTipText += hideGeoColumnInTooltip
-        ? `<strong>${stateName}</strong><br/>`
-        : `<strong>Location:  ${stateName}</strong><br/>`
+      toolTipText +=
+        hideGeoColumnInTooltip || showHSABoundaries
+          ? `<strong>${stateName}</strong><br/>`
+          : `<strong>Location:  ${stateName}</strong><br/>`
     }
     return toolTipText
   }
 
+  const getHSAColumnText = (config: MapConfig, row: Object) => {
+    const { hsa } = config.columns
+    if (!hsa || !config.general.showHSABoundaries) return ''
+    const hsaDescription = row[hsa.name]
+    return `<p class="tooltip-heading">HSA: ${hsaDescription}</p>`
+  }
+
   /**
    * On county and state maps, adds the ability to hide the geo column name (prefix)
    * @param {String} geoName - feature name
@@ -144,6 +152,9 @@ const useTooltip = props => {
     // Handle County Location Columns
     toolTipText += handleTooltipStateNameColumn(toolTipText, row)
 
+    // Handle HSA Column
+    toolTipText += getHSAColumnText(config, row)
+
     // Handle Columns > Data Column In tooltips
     toolTipText += handleTooltipGeoColumn(geoName, row)
 

package/src/store/map.actions.ts

@@ -11,7 +11,10 @@ type SET_CONFIG = Action<'SET_CONFIG', MapConfig>
 type SET_COVE_LOADED_HAS_RAN = Action<'SET_COVE_LOADED_HAS_RAN', boolean>
 type SET_DISPLAY_PANEL = Action<'SET_DISPLAY_PANEL', boolean>
 type SET_FILTERED_COUNTRY_CODE = Action<'SET_FILTERED_COUNTRY_CODE', string>
-type SET_FILTERED_STATE_CODE = Action<'SET_FILTERED_STATE_CODE', string>
+type SET_FILTERED_STATE_COUNTY_CODE = Action<
+  'SET_FILTERED_STATE_COUNTY_CODE',
+  { stateCode?: string; countyCode?: string }
+>
 type SET_IS_DRAGGING_ANNOTATION = Action<'SET_IS_DRAGGING_ANNOTATION', boolean>
 type SET_LOADING = Action<'SET_LOADING', boolean>
 type SET_MODAL = Action<'SET_MODAL', Modal>
@@ -31,7 +34,7 @@ type MapActions =
   | SET_COVE_LOADED_HAS_RAN
   | SET_DISPLAY_PANEL
   | SET_FILTERED_COUNTRY_CODE
-  | SET_FILTERED_STATE_CODE
+  | SET_FILTERED_STATE_COUNTY_CODE
   | SET_IS_DRAGGING_ANNOTATION
   | SET_LOADING
   | SET_MODAL

package/src/store/map.reducer.ts

@@ -6,8 +6,11 @@ import _ from 'lodash'
 import { Modal } from '../types/Modal'
 import { GeneratedLegend } from '../helpers/generateRuntimeLegend'
 import { RuntimeData } from '../types/RuntimeData'
+import { getQueryParam } from '@cdc/core/helpers/queryStringUtils'
 
 export const getInitialState = (configObj = {}): MapState => {
+  const filteredStateCode = typeof window !== 'undefined' ? getQueryParam('state-code') || '' : ''
+  const filteredCountyCode = typeof window !== 'undefined' ? getQueryParam('county-code') || '' : ''
   // Create defaults without palette version to avoid overriding legacy configs
   const defaultsWithoutPaletteaName = { ...defaults }
 
@@ -24,7 +27,8 @@ export const getInitialState = (configObj = {}): MapState => {
     coveLoadedHasRan: false,
     displayPanel: false,
     filteredCountryCode: '',
-    filteredStateCode: '',
+    filteredCountyCode,
+    filteredStateCode,
     isDraggingAnnotation: false,
     topoData: null,
     translate: [0, 0],
@@ -47,6 +51,7 @@ export type MapState = {
   coveLoadedHasRan: boolean
   displayPanel: boolean
   filteredCountryCode: string
+  filteredCountyCode: string
   filteredStateCode: string
   isDraggingAnnotation: boolean
   topoData: object | null
@@ -77,8 +82,12 @@ const reducer = (state: MapState, action: MapActions): MapState => {
       return { ...state, displayPanel: action.payload }
     case 'SET_FILTERED_COUNTRY_CODE':
       return { ...state, filteredCountryCode: action.payload }
-    case 'SET_FILTERED_STATE_CODE':
-      return { ...state, filteredStateCode: action.payload }
+    case 'SET_FILTERED_STATE_COUNTY_CODE':
+      return {
+        ...state,
+        filteredStateCode: action.payload.stateCode || '',
+        filteredCountyCode: action.payload.countyCode || ''
+      }
     case 'SET_IS_DRAGGING_ANNOTATION':
       return { ...state, isDraggingAnnotation: action.payload }
     case 'SET_TOPO_DATA':

package/src/test/CdcMap.test.jsx

@@ -1,11 +1,35 @@
 import path from 'node:path'
+import fs from 'node:fs'
+import vm from 'node:vm'
 import { testStandaloneBuild } from '@cdc/core/helpers/tests/testStandaloneBuild.ts'
 import { describe, it, expect } from 'vitest'
 
+const extractMarkedExampleConfig = (content, label) => {
+  const match = content.match(
+    /<!-- README_EXAMPLE_CONFIG_START -->\s*```jsx\s*([\s\S]*?)\s*```\s*<!-- README_EXAMPLE_CONFIG_END -->/
+  )
+  expect(match, `${label} should contain a marked README example block`).toBeTruthy()
+  const configMatch = match[1].match(/const config = (\{[\s\S]*?\})\n\nfunction App\(\)/)
+  expect(configMatch, `${label} should define const config before function App()`).toBeTruthy()
+  return vm.runInNewContext(`(${configMatch[1]})`)
+}
+
 describe('Map', () => {
   it('Can be built in isolation', async () => {
     const pkgDir = path.join(__dirname, '..')
     const result = await testStandaloneBuild(pkgDir)
     expect(result).toBe(true)
   }, 300000)
+
+  it('keeps the minimal example in sync with the README docs', () => {
+    const pkgRoot = path.join(__dirname, '..', '..')
+    const minimalExamplePath = path.join(pkgRoot, 'examples', 'minimal-example.json')
+    const readmePath = path.join(pkgRoot, 'README.md')
+
+    const minimalExample = JSON.parse(fs.readFileSync(minimalExamplePath, 'utf8'))
+    const readmeBlock = extractMarkedExampleConfig(fs.readFileSync(readmePath, 'utf8'), 'README.md')
+
+    expect(readmeBlock).toEqual(minimalExample)
+    expect(minimalExample.version).toBeTruthy()
+  })
 })

package/src/types/MapConfig.ts

@@ -66,6 +66,7 @@ type SimpleColumnProperties = Pick<EditorColumnProperties, 'name'>
 
 // Specific column types for better semantics
 type GeoColumnProperties = BaseColumnProperties & { displayColumn?: string }
+type HSAColumnProperties = SimpleColumnProperties
 type LatitudeColumnProperties = SimpleColumnProperties
 type LongitudeColumnProperties = SimpleColumnProperties
 type NavigateColumnProperties = SimpleColumnProperties
@@ -114,6 +115,7 @@ export type MapConfig = Visualization & {
   color: string
   columns: {
     geo: GeoColumnProperties
+    hsa: HSAColumnProperties
     primary: PrimaryColumnProperties
     navigate: NavigateColumnProperties
     latitude: LatitudeColumnProperties
@@ -164,7 +166,10 @@ export type MapConfig = Visualization & {
     showDownloadImgButton: boolean
     includeContextInDownload?: boolean
     showDownloadPdfButton: boolean
+    showHSABoundaries?: boolean
+    showNeighboringStates?: boolean
     showSidebar: boolean
+    showStateDropdown?: boolean
     showTitle: boolean
     statesPicked: {
       fipsCode: string
@@ -215,6 +220,7 @@ export type MapConfig = Visualization & {
     download: boolean
     downloadDataLabel?: string
     downloadImageLabel?: string
+    downloadUrlLabel?: string
     showDownloadUrl: boolean
     showFullGeoNameInCSV: boolean
     forceDisplay: boolean

package/src/types/MapContext.ts

@@ -7,12 +7,14 @@ import { MutableRefObject } from 'react'
 
 export type MapContext = {
   currentViewport: ViewPort
+  customNavigationHandler?: Function
   vizViewport?: ViewPort
   content: { geoName: string; keyedData: Record<string, any> }
   dimensions: DimensionsType
   displayDataAsText: string | number
   displayGeoName: (key: string, displayOverride?: string) => string
   filteredCountryCode: string
+  filteredCountyCode: string
   filteredStateCode: string
   generateRuntimeData: (
     configObj: MapConfig,
@@ -37,7 +39,7 @@ export type MapContext = {
   runtimeLegend
   setParentConfig: Function
   setRuntimeData: Function
-  setFilteredStateCode: (stateCode: string) => void
+  setFilteredStateCountyCode: (stateCode: string, countyCode?: string) => void
   setSharedFilterValue: Function
   setConfig: (newState: MapConfig) => MapConfig
   config: MapConfig

package/topojson-updater/README.txt

@@ -4,7 +4,7 @@ Node script to convert shapefile data from census.gov to topojson, and format/op
 
 
 Usage
-1. Run yarn install at root folder
+1. Run "yarn install" inside the packages/map/topojson-updater folder (this package is not part of the root Yarn workspace)
 2. Download shapefiles from census.gov (https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.html) for the year that needs to be supported to the "shapefiles" folder of the project
     - Always choose the options with the smallest file size
     - Shapefiles for both states and counties should be downloaded for each year being added

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.