Yes, the layer types (and series in facetchart/timechart as well) do not work particularly well with the typescript definition files. Since their structure was created before we migrated to TypeScript we haven't had the opportunity to switch to something that is better suited for .d.ts definitions.
The problem is that the layers array can contain different types but the definition file specify only the base type. We have to specify the actual type as a cast when writing the configuration:
layers: [ <ZoomCharts.Configuration.GeoChartSettingsLayerShapes>{
type: "shapes", // this instructs the runtime which type to use
style: { ... }
}
Since the documentation follows the same structure as the .d.ts file, it also only shows the base type there. If you want to see all properties, you can see them under layerTypes
, for example, layerTypes.shapes
.
It seems that TypeScript 2.1 might enable a better flow for this kind of structure - we would specify the valid types as union for the layers
property and the language service would actually look at the value of type
field to detect which is the correct type to use for compilation. We are currently in progress of switching to 2.1 (for now blocked by a bug in the compiler), once that is done we will also update the definition file with the new features so this issue might be resolved.
As for the data
property - the internal type is an array however the settings parser automatically handles simple objects as well to ensure proper compatibility. The reason why the .d.ts file contains data: SettingsData[]
instead of data:SettingsData|SettingsData[]
is that at least when we created the first .d.ts file generator (it was with TypeScript 1.5 if I am not mistaken) the language service got really confused with the union and the result was that it did not provide the list of property names neither with the object nor the object within an array. So we had to specify only the array to make sure that the autocomplete provided the correct list of properties. This might have changed now - we will test it once we get it to typescript 2.1.
And lastly about the data object - this is one of the cases when the documentation lists what we think would be the correct behavior, however the runtime contains different shims to make sure simple errors are automatically resolved - in this case, the coordinates are copied from the request if they are not specified in the response. Though our examples should match the desired behavior, instead of what works. (@valts or @eizens - please see the example).