@reuters-graphics/graphics-components 3.4.1 → 3.5.0

package/dist/components/Legend/Legend.svelte.d.ts

@@ -0,0 +1,100 @@
+export type LegendMode = 'threshold' | 'continuous' | 'diverging' | 'categorical' | 'proportional-symbols';
+/** A formatter that turns a numeric value into a display string. */
+export type LegendFormatter = (value: number) => string;
+/**
+ * A threshold/diverging bin. Define at least one of `from`/`to`. Colors are
+ * passed through directly, so use any CSS color or design token.
+ */
+export interface LegendItem {
+    /** CSS color for the bin or category swatch. */
+    color: string;
+    /** Lower bound of the bin (inclusive). Omit for an open-ended first bin. */
+    from?: number | null;
+    /** Upper bound of the bin (exclusive). Omit for an open-ended last bin. */
+    to?: number | null;
+    /** Optional explicit label. Generated from the bounds when omitted. */
+    label?: string;
+}
+/** A continuous gradient stop. */
+export interface LegendStop {
+    /** Numeric position of the stop along the domain. */
+    value: number;
+    /** CSS color at this stop. */
+    color: string;
+    /** Optional explicit label. */
+    label?: string;
+}
+/** A continuous-mode axis tick. */
+export interface LegendTick {
+    /** Numeric position of the tick along the domain. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+}
+/** The highlighted center of a diverging legend. */
+export interface LegendMidpoint {
+    /** Numeric value of the midpoint within the legend domain. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+}
+/** A proportional-symbols entry. */
+export interface LegendSymbolItem {
+    /** Non-negative numeric value mapped to circle area. */
+    value: number;
+    /** Optional explicit label. Formatted from `value` when omitted. */
+    label?: string;
+}
+/** Fallback swatch for missing/unknown values. */
+export interface LegendNoData {
+    /** Label shown next to the fallback swatch. */
+    label: string;
+    /** Optional CSS color for the fallback swatch. */
+    color?: string;
+}
+import type { ContainerWidth } from '../@types/global';
+interface Props {
+    /** Optional legend heading displayed above the scale. */
+    title?: string;
+    /** Optional subtitle displayed beneath the title. */
+    subtitle?: string;
+    /** Legend rendering mode. */
+    mode?: LegendMode;
+    /**
+     * Legend entries. Threshold/diverging modes use numeric bounds and colors;
+     * categorical mode uses label and color pairs; proportional-symbols mode
+     * uses numeric values and optional labels.
+     */
+    items?: LegendItem[] | LegendSymbolItem[];
+    /** Ordered continuous color stops with numeric values. */
+    stops?: LegendStop[];
+    /** Optional tick values and labels for continuous mode. */
+    ticks?: LegendTick[];
+    /** Diverging midpoint with a numeric value and optional label. */
+    midpoint?: LegendMidpoint | null;
+    /** Optional formatter applied to numeric values. */
+    formatter?: LegendFormatter | null;
+    /** Optional fallback swatch for missing values. */
+    noData?: LegendNoData | null;
+    /** Width of the legend within the text well. */
+    width?: ContainerWidth;
+}
+/**
+ * `Legend` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-graphics-legend--docs)
+ *
+ * Quantitative and categorical legend for maps and data displays.
+ *
+ * Renders one of five legend types:
+ * - `threshold`: discrete bins with color swatches
+ * - `continuous`: a continuous gradient with ticks
+ * - `diverging`: threshold bins with a highlighted midpoint
+ * - `categorical`: square swatches with labels in a horizontal row
+ * - `proportional-symbols`: nested circles with leader lines and labels
+ *
+ * The component is presentational and can be placed anywhere in page layout. The
+ * optional `noData` prop renders a separate fallback swatch for missing, unknown,
+ * or unavailable values across all legend modes.
+ */
+declare const Legend: import("svelte").Component<Props, {}, "">;
+type Legend = ReturnType<typeof Legend>;
+export default Legend;

package/dist/components/TileMap/TileMap.svelte

@@ -79,6 +79,12 @@
     textWidth?: ContainerWidth;
     /** Callback function that receives the map instance when ready */
     onMapReady?: (map: maplibregl.Map) => void;
+    /**
+     * Optional content rendered inside the map's `GraphicBlock`, directly above
+     * the map. Use it to share a single block — with one title and the standard
+     * spacing — between the map and an accompanying element such as a `Legend`.
+     */
+    legend?: Snippet;
     /** Child components (e.g., TileMapLayer) */
     children?: Snippet;
   }
@@ -99,6 +105,7 @@
     width = 'normal',
     textWidth = 'normal',
     onMapReady,
+    legend,
     children,
   }: Props = $props();
 
@@ -174,6 +181,11 @@
 </script>
 
 <GraphicBlock {width} {textWidth} {title} {description} {notes}>
+  {#if legend}
+    <div class="map-legend">
+      {@render legend()}
+    </div>
+  {/if}
   <div class="map" {id}>
     <div
       bind:this={mapContainer}
@@ -196,4 +208,9 @@
     width: 100%;
     position: relative;
   }
+
+  /* Sit the legend snug above the map, sharing the block's spacing. */
+  .map-legend {
+    margin-bottom: 0.5rem;
+  }
 </style>

package/dist/components/TileMap/TileMap.svelte.d.ts

@@ -59,6 +59,12 @@ interface Props {
     textWidth?: ContainerWidth;
     /** Callback function that receives the map instance when ready */
     onMapReady?: (map: maplibregl.Map) => void;
+    /**
+     * Optional content rendered inside the map's `GraphicBlock`, directly above
+     * the map. Use it to share a single block — with one title and the standard
+     * spacing — between the map and an accompanying element such as a `Legend`.
+     */
+    legend?: Snippet;
     /** Child components (e.g., TileMapLayer) */
     children?: Snippet;
 }

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export { default as InlineAd } from './components/AdSlot/InlineAd.svelte';
 export { default as KinesisLogo } from './components/KinesisLogo/KinesisLogo.svelte';
 export { default as LanguageButton } from './components/LanguageButton/LanguageButton.svelte';
 export { default as LeaderboardAd } from './components/AdSlot/LeaderboardAd.svelte';
+export { default as Legend } from './components/Legend/Legend.svelte';
 export { default as TileMap } from './components/TileMap/TileMap.svelte';
 export { default as TileMapLayer } from './components/TileMap/TileMapLayer.svelte';
 export { default as PaddingReset } from './components/PaddingReset/PaddingReset.svelte';
@@ -59,3 +60,4 @@ export { default as Video } from './components/Video/Video.svelte';
 export { default as Visible } from './components/Visible/Visible.svelte';
 export type { ContainerWidth, HeadlineSize, ScrollerVideoInstance, } from './components/@types/global';
 export type { GeocodeOptions, GeocodeFeature, GeocodeFeatureType, } from './components/Geocoder/geocode';
+export type { LegendMode, LegendFormatter, LegendItem, LegendStop, LegendTick, LegendMidpoint, LegendSymbolItem, LegendNoData, } from './components/Legend/Legend.svelte';

package/dist/index.js

@@ -32,6 +32,7 @@ export { default as InlineAd } from './components/AdSlot/InlineAd.svelte';
 export { default as KinesisLogo } from './components/KinesisLogo/KinesisLogo.svelte';
 export { default as LanguageButton } from './components/LanguageButton/LanguageButton.svelte';
 export { default as LeaderboardAd } from './components/AdSlot/LeaderboardAd.svelte';
+export { default as Legend } from './components/Legend/Legend.svelte';
 export { default as TileMap } from './components/TileMap/TileMap.svelte';
 export { default as TileMapLayer } from './components/TileMap/TileMapLayer.svelte';
 export { default as PaddingReset } from './components/PaddingReset/PaddingReset.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reuters-graphics/graphics-components",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "type": "module",
   "private": false,
   "homepage": "https://reuters-graphics.github.io/graphics-components",