@cdc/map 4.26.4 → 4.26.5

package/CONFIG.md

@@ -1,6 +1,6 @@
 # `@cdc/map` Configuration Reference
 
-This document covers the `@cdc/map`-owned config contract. Shared nested structures such as `filters`, `table`, `annotations`, `markupVariables`, `general.palette`, `general.headerColor`, and the shared column/property shapes are documented in the [`@cdc/core` config reference](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md).
+This document covers the `@cdc/map`-owned config contract. Shared nested structures such as `filters`, `table`, `annotations`, `markupVariables`, `general.palette`, and the shared column/property shapes are documented in the [`@cdc/core` config reference](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md).
 
 To follow those shared types locally, use `packages/core/CONFIG.md` in this monorepo or `node_modules/@cdc/core/CONFIG.md` in an installed app. If neither path is available, use the GitHub link above.
 
@@ -27,24 +27,25 @@ The copy-pasteable minimum config lives in [README.md](./README.md). Its source
 | Field | Type | Required | Default | Description | Allowed values / Notes |
 | --- | --- | --- | --- | --- | --- |
 | `type` | `string` | Yes | None | Identifies the package. | Must be `map`. |
-| `version` | `string` | No | None | Saved COVE version for migration purposes. | Use the current package version when authoring a new config. |
-| `color` | `string` | No | Legacy fallback | Legacy palette name kept for backward compatibility. | Prefer `general.palette.name` when authoring new configs. |
+| `version` | `string` | No | None | Saved COVE version for migration purposes. | Use a semantic COVE version for authored configs so migrations can reason about saved-version order. |
+| `locale` | `string` | No | Browser/runtime default | Locale used by markup-variable and shared formatting helpers. | Any valid `Intl` locale is accepted. |
 
-The following data-loading fields are shared and documented in core: `data`, `dataUrl`, `runtimeDataUrl`, `dataDescription`, `dataMetadata`, and `dataKey` for dashboard-driven embeds.
+The following authorable data-loading fields are shared and documented in core: `data`, `dataUrl`, `dataDescription`, `dataMetadata`, and `dataKey` for dashboard-driven embeds. `dataMetadata` may be loader-populated, but consumers should preserve or author it when metadata-backed alt text, markup variables, or footnotes need it. Runtime/file metadata such as `runtimeDataUrl` may still appear in saved configs, but consumers usually do not author those fields directly.
 
 ## Geography and Columns
 
 | Field | Type | Required | Default | Description | Allowed values / Notes |
 | --- | --- | --- | --- | --- | --- |
-| `general.geoType` | `string` | Yes | `single-state` | Chooses the geography family being rendered. | `us`, `us-region`, `us-county`, `world`, `us-geocode`, `world-geocode`, `bubble`, `single-state`, `google-map` |
+| `general.geoType` | `string` | Yes | `single-state` | Chooses the geography family being rendered. | `us`, `us-region`, `us-county`, `world`, `single-state`, `google-map`. Geocode maps use `general.type: "us-geocode"` with `geoType: "us-county"` or `general.type: "world-geocode"` with `geoType: "world"`. Bubble maps use `general.type: "bubble"` with a supported geography such as `us` or `world`. |
 | `general.type` | `string` | Yes | `data` | Chooses the interaction mode. | `data`, `navigation`, `us-geocode`, `world-geocode`, `bubble` |
 | `columns.geo` | `object` | Yes | See package defaults | Geography lookup column. | Uses shared column properties from core; `displayColumn` is map-specific and is used when the displayed geography label differs from the lookup field. |
 | `columns.primary` | `object` | Conditionally | See package defaults | Main data column used for classification and tooltips. | Uses shared column properties from core. Required for data maps and bubble maps. |
 | `columns.navigate` | `object` | Conditionally | `{ name: '' }` | URL column used in navigation mode. | Required when `general.type` is `navigation`. |
-| `columns.latitude` | `object` | Conditionally | `{ name: '' }` | Latitude column for geocode and bubble maps. | Required for `us-geocode` and `world-geocode`. |
-| `columns.longitude` | `object` | Conditionally | `{ name: '' }` | Longitude column for geocode and bubble maps. | Required for `us-geocode` and `world-geocode`. |
+| `columns.latitude` | `object` | Conditionally | `{ name: '' }` | Latitude column for coordinate-based geocode and Google maps. | Required for `us-geocode`, `world-geocode`, and `google-map`. US/world bubble maps can resolve positions from built-in geography coordinates. |
+| `columns.longitude` | `object` | Conditionally | `{ name: '' }` | Longitude column for coordinate-based geocode and Google maps. | Required for `us-geocode`, `world-geocode`, and `google-map`. US/world bubble maps can resolve positions from built-in geography coordinates. |
 | `columns.categorical` | `object` | No | `{ name: '' }` | Category column for bubble maps using categorical legends. | `name` only. |
 | `columns.hsa` | `object` | No | `{ name: '' }` | Optional HSA column used by county maps when HSA boundaries are shown. | `name` only. |
+| `columns.additionalColumnN` | `object` | No | None | Additional persisted column configs for tooltip and data-table output. | Editor-created keys such as `additionalColumn0` use shared column display fields. |
 
 ## Copy And Shell Controls
 
@@ -57,43 +58,62 @@ The following data-loading fields are shared and documented in core: `data`, `da
 | `general.language` | `string` | No | `en` | Language code used by some map helpers and editor defaults. | Usually an ISO locale/language code. |
 | `general.introText` | `string` | No | `''` | Intro copy shown in the shell. | Supports markup variables when enabled. |
 | `general.subtext` | `string` | No | `''` | Supporting copy shown below the visualization. | Supports basic HTML plus markup variables when enabled. |
-| `general.footnotes` | `string` | No | `''` | Optional footnote copy. | Shared footnotes shape is documented in core. |
+| `general.footnotes` | `string` | No | `''` | Legacy/simple footnote copy. | Prefer top-level `footnotes` for structured static or data-driven footnotes. |
+| `footnotes` | [`Footnotes`](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md#footnotes) | No | None | Structured static or data-driven footnotes rendered below the map. | Shared footnotes shape from `@cdc/core`. |
 | `general.navigationTarget` | `string` | No | `_self` | Target used when the map opens navigation URLs. | `_self`, `_blank` |
-| `general.showSidebar` | `boolean` | No | `true` | Shows the legend/sidebar region. | Set to `false` for navigation and bubble layouts. |
+| `general.showSidebar` | `boolean \| "hidden"` | No | `true` | Shows the legend/sidebar region. | Author booleans for normal configs. Set to `false` for navigation and bubble layouts. Editor exports may contain `"hidden"`, but runtime treats that string as truthy, so it does not hide the legend. |
 | `general.noDataMessage` | `string` | No | `No State Selected` | Message shown when a single-state map has no active selection. | Package-specific copy. |
 | `general.annotationDropdownText` | `string` | No | `Annotations` | Label shown for the annotation dropdown. | Used when annotation dropdowns are enabled. |
-| `general.showAnnotationDropdown` | `boolean` | No | `false` | Shows the annotation dropdown in the shell. | Editor-driven toggle. |
+| `general.showAnnotationDropdown` | `boolean` | No | `false` | Changes desktop visibility classes for the annotation dropdown. | Annotation dropdown markup renders when annotations exist; this flag controls whether it is shown in desktop layouts. |
 | `general.geoBorderColor` | `string` | No | `darkGray` | Border color used for geography outlines. | `darkGray`, `sameAsBackground`, and other editor-supported color tokens. |
 | `general.geoLabelOverride` | `string` | No | `''` | Overrides the geography label used in tooltips and other copy. | Useful when the map should say "Country", "State/Territory", or similar. |
 | `general.fullBorder` | `boolean` | No | `false` | Adds a full border around navigation maps. | Mainly relevant when `general.type` is `navigation`. |
-| `general.headerColor` | `string` | No | `theme-blue` | Shared header theme token. | See core docs for the full token list. |
+| `general.headerColor` | `string` | No | `theme-blue` | Map-owned header theme token. | Accepts shared [`ComponentThemes`](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md#componentthemes) values. |
 | `general.displayStateLabels` | `boolean` | No | `true` | Shows state labels directly on the map. | `true`, `false` |
 | `general.displayAsHex` | `boolean` | No | `false` | Switches the US map to a hex-style treatment. | Works with `hexMap`. |
 | `general.equalNumberOptIn` | `boolean` | No | `false` | Enables the newer equal-number legend path. | Used when `legend.separateZero` and equal-number classification interact. |
 | `general.allowMapZoom` | `boolean` | No | `true` | Enables zooming on supported map types. | Disabled in some editor flows and unsupported map modes. |
-| `general.convertFipsCodes` | `boolean` | No | `true` | Normalizes FIPS-like geography values. | Helpful for US maps that use mixed FIPS formats. |
+| `general.showClearSelectionButton` | `boolean` | No | `true` | Shows a Clear Selection control for dashboard maps that set a shared filter. | Only meaningful when the map is used inside a dashboard as a `setBy` control and a selection is currently active. Current runtime support is implemented for the U.S. map. |
 | `general.hideGeoColumnInTooltip` | `boolean` | No | `false` | Hides the geography field name in tooltips. | `true`, `false` |
 | `general.hidePrimaryColumnInTooltip` | `boolean` | No | `false` | Hides the primary data field name in tooltips. | `true`, `false` |
-| `general.showDownloadMediaButton` | `boolean` | No | `false` | Enables the media download button. | Often paired with the image/PDF toggles below. |
 | `general.showDownloadImgButton` | `boolean` | No | `false` | Enables PNG/image download. | Editor-managed field. |
 | `general.includeContextInDownload` | `boolean` | No | `false` | Includes heading and explanatory context in image downloads. | Only meaningful when image downloads are enabled. |
 | `general.showDownloadPdfButton` | `boolean` | No | `false` | Enables PDF download. | Editor-managed field. |
 | `general.showHSABoundaries` | `boolean` | No | `false` | Shows HSA boundaries on supported county maps. | Mainly relevant for health-system maps. |
 | `general.showNeighboringStates` | `boolean` | No | `false` | Includes neighboring states in the county map outline. | Only relevant for county maps. |
 | `general.showStateDropdown` | `boolean` | No | `false` | Shows a state picker in county views. | Only relevant for county maps. |
+| `general.countyCensusYear`, `general.filterControlsCountyYear` | `string` | No | Package defaults | County census-year controls used by county map helpers and editor flows. | Only meaningful for county maps. |
+| `general.filterControlsStatesPicked` | `string` | No | `''` | Source column used to derive selected states from filtered data. | Related to `general.statesPicked`; consumed by single-state/county helper logic. |
 | `general.hideUnselectedStates` | `boolean` | No | `true` when states are picked | Controls whether selected-state maps hide or keep unselected states visible. | Only meaningful when `statesPicked` is populated on single-state maps. |
 | `general.statesPicked` | `object[]` | No | `[]` | Selected states for single-state maps. | Each item has `fipsCode` and `stateName`. |
-| `general.countriesPicked` | `object[]` | No | `[]` | Selected countries for world maps. | Each item has `iso` and `name`. |
+| `general.countriesPicked` | `object[]` | No | `[]` | Selected countries for world maps. | Each item has `iso` and `name`. Use supported ISO 3166-1 alpha-3 codes for `iso`; two-letter codes can fail selection and centering. |
 | `general.hideUnselectedCountries` | `boolean` | No | `false` | Controls whether unselected countries are hidden or grayed out. | Only meaningful when `countriesPicked` is populated. |
-| `general.territoriesAlwaysShow` | `boolean` | No | `true` | Controls how U.S. territories are rendered on U.S. maps. | `true`, `false`. On county maps, `false` hides all territory counties; `true` renders only territory counties with matching runtime data. On state maps, `false` renders only territories with matching runtime data; `true` renders all supported territories whether data exists or not. When omitted, the editor/runtime treat it as `true`, and legacy configs are backfilled to `true` during migration. |
-| `general.territoriesLabel` | `string` | No | `Territories` | Label used for territories in US maps. | Often left at the default. |
+| `general.territoriesAlwaysShow` | `boolean` | No | `false` in package initial state | Controls how U.S. territories are rendered on U.S. maps. | `true`, `false`. On county maps, `false` hides all territory counties, except migrated legacy configs with `migrations.showPuertoRico` can still render Puerto Rico for compatibility; `true` renders only territory counties with matching runtime data. On state maps, `false` renders only territories with matching runtime data; `true` renders all supported territories whether data exists or not. Normal loaded configs are seeded or migrated before rendering; lower-level geography helpers still treat an undefined value as enabled for legacy compatibility. |
+| `general.territoriesLabel` | `string` | No | None | Label shown for the territories group in U.S. region maps. | Mainly relevant for `us-region`; legacy and example configs commonly use `Territories`. |
 | `general.hasRegions` | `boolean` | No | `false` | Marks the map as region-aware for some data-loading and editor flows. | Mainly used by US regional map flows. |
 
 The canonical palette configuration is shared in core. This package still accepts the legacy `color` field for older saved configs, but new configs should author `general.palette` instead.
 
 ## Classification And Palette
 
-Legend configuration is shared with core. The map package honors the shared legend contract plus these map-specific behaviors:
+Legend configuration is shared with core. The map package honors the shared legend contract plus these map-specific fields and behaviors:
+
+| Field | Type | Required | Default | Description | Allowed values / Notes |
+| --- | --- | --- | --- | --- | --- |
+| `legend.type` | `string` | No | `equalnumber` | Chooses the classification strategy. | `equalnumber`, `equalinterval`, `category` |
+| `legend.numberOfItems` | `number` | No | `5` | Number of legend classes for numeric legends. | Editor usually limits this to small integer values. |
+| `legend.position` | `string` | No | `top` | Legend placement. | `top`, `bottom`, `left`, `right`, `side`, depending on layout. |
+| `legend.style` | `string` | No | `gradient` | Legend marker or gradient style. | `circles`, `boxes`, `gradient` |
+| `legend.subStyle` | `string` | No | `linear blocks` | Gradient legend treatment. | `linear blocks`, `smooth` |
+| `legend.title`, `legend.description` | `string` | No | `''` | Legend heading and description. | Supports markup-variable processing in supported map flows. |
+| `legend.descriptions` | `Record<string, string \| string[]>` | No | `{}` | Dynamic legend-description lookup used when `legend.dynamicDescription` is `true`. | Keys use the filter index and selected filter-value index, such as `0,0`. Editor-saved values may be strings or one-item string arrays. |
+| `legend.specialClasses` | `{ key; label; value }[]` | No | `[]` | Extra legend classes for special cases. | Used for no-data or other override classes. |
+| `legend.unified` | `boolean` | No | `false` | Uses unified legend behavior for compatible map modes. | `true`, `false` |
+| `legend.singleColumn`, `legend.singleRow`, `legend.verticalSorted` | `boolean` | No | `false` | Layout and sorting controls for legend items. | Runtime may still adapt for available space. |
+| `legend.showSpecialClassesLast` | `boolean` | No | `false` | Moves special classes to the end of the legend. | `true`, `false` |
+| `legend.dynamicDescription` | `boolean` | No | `false` | Enables dynamic legend description behavior. | `true`, `false` |
+
+When `legend` is omitted entirely, the package initial state supplies the defaults above. When a config provides a partial `legend` object, missing `numberOfItems`, `position`, `style`, and `hideBorder` can be backfilled from legacy defaults: `3`, `side`, `circles`, and `false`.
 
 | Behavior | Details |
 | --- | --- |
@@ -108,13 +128,16 @@ Legend configuration is shared with core. The map package honors the shared lege
 
 ## Filtering And Tables
 
-Shared filter and table structures are documented in core. Map-specific behavior includes:
+Shared filter and table structures are documented in [`@cdc/core`](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md#filters) and [`@cdc/core` table docs](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md#table). Map-specific behavior includes:
 
 | Behavior | Details |
 | --- | --- |
 | `filterBehavior` | Controls whether the map updates immediately or waits for an explicit filter change in supporting editor flows. |
 | `filterIntro` | Intro copy shown near the filter UI. |
 | `table.forceDisplay` | Keeps the data table visible even when the current mode would normally hide it. |
+| `table.showNonGeoData` | Includes non-geographic rows in map-related table output. |
+| `table.showFullGeoNameInCSV` | Adds full geography names to CSV downloads when the formatter can resolve them. |
+| `table.wrapColumns` | Allows map table cell content to wrap instead of staying on one line. |
 
 ## Map Features
 
@@ -124,14 +147,14 @@ Custom overlay or base layers added by the editor.
 
 | Field | Type | Required | Default | Description | Allowed values / Notes |
 | --- | --- | --- | --- | --- | --- |
-| `name` | `string` | Yes | None | Display name for the layer. | Used in the editor accordion label. |
-| `url` | `string` | Yes | None | Layer source URL. | Usually GeoJSON or TopoJSON. |
-| `namespace` | `string` | No | `''` | SVG namespace / layer prefix. | Used when building layer ids. |
-| `fill` | `string` | No | `''` | Fill color for the layer. | CSS color string. |
-| `fillOpacity` | `number` | No | `''` | Fill opacity for the layer. | Numeric opacity value. |
-| `stroke` | `string` | No | `''` | Stroke color for the layer. | CSS color string. |
-| `strokeWidth` | `number` | No | `''` | Stroke width for the layer. | Numeric width value. |
-| `tooltip` | `boolean` | No | `false` | Enables hover/click tooltips on the layer. | `true`, `false` |
+| `name` | `string` | No | None | Display name for the layer. | Editor-label metadata used in the accordion label; runtime rendering depends on `url` and `namespace`, not `name`. |
+| `url` | `string` | Yes | None | Layer source URL. | Current runtime expects TopoJSON. Raw GeoJSON is not handled by this layer reader. |
+| `namespace` | `string` | Yes | None | TopoJSON `objects` key used to select the layer geometry. | Required for rendering and also used when building layer ids. |
+| `fill` | `string` | No | TopoJSON feature fill, then `transparent` | Fill color for the layer. | CSS color string. |
+| `fillOpacity` | `number \| string` | No | TopoJSON `fill-opacity`, then `1` | Fill opacity for the layer. | Saved configs may contain either a number or numeric string. |
+| `stroke` | `string` | No | TopoJSON feature stroke, then `transparent` | Stroke color for the layer. | CSS color string. |
+| `strokeWidth` | `number \| string` | No | TopoJSON `stroke-width` when present | Stroke width for the layer. | Saved configs may contain either a number or numeric string. |
+| `tooltip` | `string` | No | `''` | Tooltip text or HTML for the layer. | Empty string disables layer-specific tooltip content. |
 
 ### `map.patterns`
 
@@ -145,7 +168,6 @@ Pattern overlays applied to matching geography rows.
 | `label` | `string` | No | `''` | Optional legend label for the pattern. | Displayed in the legend when present. |
 | `size` | `string` | No | `medium` | Pattern density / size. | `small`, `medium`, `large` |
 | `color` | `string` | No | `''` | Pattern color. | CSS color string. |
-| `contrastCheck` | `boolean` | No | `true` | Result of the editor contrast check. | Usually managed by the editor. |
 
 ### `hexMap`
 
@@ -160,17 +182,16 @@ Pattern overlays applied to matching geography rows.
 | --- | --- | --- | --- | --- | --- |
 | `legendTitle` | `string` | No | `''` | Title for the shape group in the legend. | Optional. |
 | `legendDescription` | `string` | No | `''` | Description for the shape group. | Optional. |
-| `items` | `object[]` | No | `[]` | Shape rules that determine which arrow or icon is shown. | Each item can match by `key`, `column`, `operator`, and `value`. |
+| `items` | `object[]` | No | `[]` | Shape rules that determine which arrow or icon is shown. | Each item matches by `key`, `operator`, and `value`. |
 
 `hexMap.shapeGroups[].items[]`
 
 | Field | Type | Required | Default | Description | Allowed values / Notes |
 | --- | --- | --- | --- | --- | --- |
-| `key` | `string` | No | `''` | Internal key for the hex-map rule. | Usually left blank in hand-authored configs. |
 | `shape` | `string` | No | `Arrow Up` | Shape rendered for the rule. | Editor values include arrow directions. |
-| `column` | `string` | No | `''` | Source column to inspect. | Can be blank for some legacy flows. |
+| `key` | `string` | No | `''` | Source column/key to inspect. | Current editor and runtime use this field for hex-shape matching. |
 | `operator` | `string` | No | `=` | Comparison operator. | `=`, `≠`, `<`, `>`, `<=`, `>=` |
-| `value` | `string` | No | `''` | Comparison value. | Compared against the configured column. |
+| `value` | `string` | No | `''` | Comparison value. | Compared against the configured key. |
 
 ### `smallMultiples`
 
@@ -189,10 +210,16 @@ Only supported for `us`, `single-state`, and `us-region` map types.
 
 ### `annotations` and `markupVariables`
 
-These structures are shared with core. In map configs, the important package-specific behavior is that annotation dropdowns are only visible when `general.showAnnotationDropdown` is enabled, and markup variables are applied to title, intro, subtext, legend, and other supported text fields when `enableMarkupVariables` is true.
+These structures are shared with core. In map configs, annotation dropdown markup renders when annotations exist; `general.showAnnotationDropdown` controls the desktop visibility treatment. Markup variables are applied to title, intro, subtext, legend, and other supported text fields when `enableMarkupVariables` is true.
 
 ## Layout And Interactivity
 
+### Accessibility
+
+Map configs can include [`altText`](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md#alttextconfig), the shared `AltTextConfig` object from core. The map runtime first builds a map-specific SVG `aria-label` from the rendered geography and data context, then appends the resolved static or metadata-driven `altText` description when one is available.
+
+Shared shell styling flags on `visual` follow core [`ComponentStyles`](https://github.com/CDCgov/cdc-open-viz/blob/main/packages/core/CONFIG.md#componentstyles). Map-specific `visual` fields are listed here because they affect marker, bubble, and geocode rendering.
+
 | Field | Type | Required | Default | Description | Allowed values / Notes |
 | --- | --- | --- | --- | --- | --- |
 | `mapPosition.coordinates` | `[number, number]` | No | `[0, 30]` | Initial map center. | The runtime may reset this when the geography changes. |
@@ -214,7 +241,7 @@ These structures are shared with core. In map configs, the important package-spe
 | `visual.additionalCityStyles` | `object[]` | No | `[]` | Extra city-style rules added in the editor. | Each rule uses `label`, `column`, `value`, and `shape`. |
 | `tooltips.appearanceType` | `string` | No | `hover` | Chooses hover or click-based detail displays. | `hover`, `click` |
 | `tooltips.linkLabel` | `string` | No | `Learn More` | Tooltip link label. | Used when `appearanceType` is `click`. |
-| `tooltips.noDataLabel` | `string` | No | `''` | Text shown for missing data in the tooltip. | Optional. |
+| `tooltips.noDataLabel` | `string` | No | `No Data` render fallback | Text shown for missing data in the tooltip. | Omitted or empty values render as `No Data`. |
 | `tooltips.opacity` | `number` | No | `90` | Tooltip opacity. | 0-100 in editor flows. |
 
 ## Fields You Can Ignore
@@ -224,12 +251,18 @@ These fields may appear in saved configs, editor exports, or runtime state, but
 | Field or group | Why you can ignore it |
 | --- | --- |
 | `runtime.*` | Internal runtime state created by the package during initialization. |
-| `defaultData`, `formattedData`, `datasets`, `runtimeDataUrl`, `dataMetadata` | Loader/runtime artifacts rather than hand-authored standalone config. |
+| `defaultData`, `formattedData`, `datasets`, `runtimeDataUrl` | Loader/runtime artifacts rather than hand-authored standalone config. |
+| `color` | Legacy top-level palette token. Author `general.palette` for current configs. |
 | `sharing.*` | Loader/export metadata that belongs to editor or embed flows. |
+| `migrations.*` | Migration bookkeeping that records which update steps have run. Preserve `migrations.showPuertoRico` when encountered in migrated county maps; runtime still reads it as legacy compatibility metadata. Only set `migrations.showPuertoRico: false` when explicitly opting a county map out of the legacy Puerto Rico rendering shim. |
+| `dataTable` | Top-level legacy/export artifact; table behavior is configured through `table`. |
 | `usingWidgetLoader` | Internal loader flag. |
 | `newViz` | Editor-only preview/confirmation flag. |
-| `columns.additionalColumnN` | Editor-generated extra columns for data-table and tooltip workflows. |
-| `general.countyCensusYear`, `general.filterControlsCountyYear`, `general.filterControlsStatesPicked` | Editor-only controls that are surfaced for some county and single-state flows. |
+| `general.filterControlsStatePicked` | Legacy singular editor-control artifact; use `general.statesPicked` for authored selected-state config. |
+| `general.convertFipsCodes` | Legacy/editor-authored FIPS conversion flag. Current runtime normalizes FIPS-like values during U.S. and county map load regardless of this value. |
+| `general.showDownloadMediaButton` | Legacy editor control; current rendering uses `general.showDownloadImgButton` and `general.showDownloadPdfButton` directly. |
 | `general.territoriesAlwayShow` | Misspelled legacy artifact from an older migration bug. The runtime repairs this to `general.territoriesAlwaysShow`; do not author it manually. |
+| `map.patterns[].contrastCheck` | Editor validation state for pattern contrast; changing it does not affect rendered pattern matching or styling. |
+| `hexMap.shapeGroups[].items[].column` | Legacy/stale hex-shape field; author `hexMap.shapeGroups[].items[].key` for current runtime matching. |
 | `statePicked` | Legacy saved-config artifact from older editor flows. |
-| `showDownloadButton`, `expandDataTable` | Legacy editor state from older configs. |
+| `general.showDownloadButton`, `general.expandDataTable` | Legacy editor state from older configs. Current table behavior uses `table.download` and `table.expanded`. |

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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.

package/README.md

@@ -20,12 +20,16 @@ import CdcMap from '@cdc/map'
 
 const config = {
   version: '4.26.4',
-  color: 'pinkpurple',
   general: {
     title: 'Minimal US Map',
     geoType: 'us',
     type: 'data',
-    showTitle: true
+    showTitle: true,
+    palette: {
+      name: 'sequential_blue',
+      version: '2.0',
+      isReversed: false
+    }
   },
   type: 'map',
   columns: {