@reuters-graphics/graphics-components 3.10.0 → 4.0.0

package/dist/llm-docs/components/TileMap.md

@@ -0,0 +1,477 @@
+# TileMap
+
+**Category:** Components/Graphics/TileMap
+
+**Import:** `import { TileMap } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `title` | `string \| Snippet` | — |  | Title of the map as a string or a custom snippet. |
+| `description` | `string` | — |  | Description of the map, passed in as a markdown string. |
+| `notes` | `string \| Snippet` | — |  | Notes to the map, passed in as a markdown string or a custom snippet. |
+| `id` | `string` | ``map-${Math.random().toString(36).substring(2, 9)}`` |  | Map container id |
+| `center` | `[number, number]` | `[0, 0]` |  | Map center coordinates [longitude, latitude] |
+| `zoom` | `number` | `2` |  | Initial zoom level |
+| `minZoom` | `number` | `0` |  | Minimum zoom level |
+| `maxZoom` | `number` | `22` |  | Maximum zoom level |
+| `projection` | `ProjectionSpecification` | — |  | Map projection. Use 'globe' for 3D globe view. See https://maplibre.org/maplibre-style-spec/types/#projectiondefinition |
+| `interactive` | `boolean` | `true` |  | Enable interactive controls (zoom, pan, etc.) |
+| `styleUrl` | `string` | `'https://graphics.thomsonreuters.com/reuters-protomaps/style.json'` |  | Map style URL |
+| `emphasizeLabels` | `boolean` | `false` |  | Darken the basemap's place labels and give them a strong white halo, so city/region names stay readable over colored data layers. Applied once on map load; a no-op on styles without `place` labels (e.g. non-default `styleUrl`s), so it degrades gracefully. |
+| `height` | `string` | `'500px'` |  | Map height (default: '500px') |
+| `width` | `ContainerWidth` | `'normal'` |  | Width of the map within the text well. Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `textWidth` | `ContainerWidth` | `'normal'` |  | Set a different width for the text within the text well, for example, "normal" to keep the title, description and notes inline with the rest of the text well. Can't ever be wider than `width`. |
+| `onMapReady` | `(map: maplibregl.Map) => void` | — |  | Callback function that receives the map instance when ready |
+| `legend` | `Snippet` | — |  | 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`. |
+| `children` | `Snippet` | — |  | Child components (e.g., TileMapLayer) |
+
+## Examples
+
+### Demo
+
+```svelte
+<TileMap id="demo-map" center={[-98, 39]} zoom={3} interactive={true} height="500px" />
+```
+
+### Globe view
+
+```svelte
+<TileMap
+  id="globe-map"
+  center={[0, 0]}
+  zoom={2}
+  projection={{ type: 'globe' }}
+  interactive={true}
+  title="Globe View"
+  description="A 3D globe projection of the Earth."
+  height="600px"
+/>
+```
+
+### Non-interactive
+
+```svelte
+<TileMap
+  id="static-map"
+  center={[2.3522, 48.8566]}
+  zoom={12}
+  interactive={false}
+  title="Paris"
+  description="A static map of Paris, France."
+  height="400px"
+/>
+```
+
+### With GeoJSON layers
+
+```svelte
+<TileMap
+  id="geojson-map"
+  center={[-73.9712, 40.7831]}
+  zoom={11}
+  interactive={true}
+  title="Map with GeoJSON Layers"
+  description="Example showing multiple GeoJSON layers including local data and data fetched from a URL."
+  notes="Demonstrates polygon fills, line overlays, point markers, and text labels."
+  height="600px"
+>
+  <TileMapLayer
+    id="park-area"
+    data={centralParkData}
+    type="fill"
+    paint={{
+      'fill-color': '#179639',
+      'fill-opacity': 0.7,
+    }}
+  />
+  <TileMapLayer
+    id="park-outline"
+    data={centralParkData}
+    type="line"
+    paint={{
+      'line-color': '#228b22',
+      'line-width': 2,
+    }}
+  />
+  <TileMapLayer
+    id="route-line"
+    data="https://raw.githubusercontent.com/datanews/ny-marathon/refs/heads/master/route.geojson"
+    type="line"
+    paint={{
+      'line-color': '#4287f5',
+      'line-width': 2,
+    }}
+  />
+  <TileMapLayer
+    id="reuters-office-point"
+    data={reutersOfficePoint}
+    type="circle"
+    paint={{
+      'circle-radius': 4,
+      'circle-color': '#ff0000',
+      'circle-stroke-width': 2,
+      'circle-stroke-color': '#ffffff',
+    }}
+  />
+  <TileMapLayer
+    id="reuters-office-label"
+    data={reutersOfficePoint}
+    type="symbol"
+    layout={{
+      'text-field': 'Reuters Office',
+      'text-offset': [0.25, 0.5],
+      'text-anchor': 'top-left',
+      'text-size': 12,
+    }}
+    paint={{
+      'text-color': '#000000',
+      'text-halo-color': '#ffffff',
+      'text-halo-width': 2,
+    }}
+  />
+  <TileMapLayer
+    id="points-layer"
+    data={points}
+    type="circle"
+    paint={{
+      'circle-radius': 4,
+      'circle-color': '#9c27b0',
+      'circle-stroke-width': 2,
+      'circle-stroke-color': '#ffffff',
+    }}
+  />
+</TileMap>
+```
+
+### Labels above data
+
+```svelte
+<TileMap
+  id="labels-map"
+  center={[-93.5, 42]}
+  zoom={6}
+  interactive={true}
+  emphasizeLabels
+  title="Keeping labels readable over data"
+  description="`emphasizeLabels` (on the map) darkens the basemap's place labels and adds a white halo; `beneathLabels` (on the fill layer) inserts the data below the labels, so city names across Iowa stay on top of the colored overlay."
+  height="500px"
+>
+  <TileMapLayer
+    id="iowa-fill"
+    data={iowaData}
+    type="fill"
+    beneathLabels
+    paint={{
+      'fill-color': '#d64000',
+      'fill-opacity': 0.75,
+    }}
+  />
+</TileMap>
+```
+
+### With Geocoder
+
+```svelte
+<TileMap
+  id="geocoder-map"
+  center={[-98, 39]}
+  zoom={3}
+  interactive={true}
+  title="Map with Geocoder"
+  description="Search for a location to fly the map there."
+  height="500px"
+  onMapReady={(map) => {
+    geocoderMapRef = map;
+  }}
+>
+  <div
+    style="position: absolute; top: 10px; left: 50%; transform: translateX(-50%); z-index: 1000; width: min(500px, calc(100% - 20px));"
+  >
+    <Geocoder
+      accessToken={mapboxAccessToken}
+      onselect={(loc) => {
+        geocoderMapRef?.flyTo({ center: [loc.lng, loc.lat], zoom: 10 });
+      }}
+    />
+  </div>
+</TileMap>
+```
+
+## Documentation
+
+# TileMap
+
+Easily add an interactive map to your page using MapLibre GL and PMTiles.
+
+```svelte
+<script>
+  import { TileMap } from '@reuters-graphics/graphics-components';
+</script>
+
+<TileMap
+  id="my-map"
+  center={[-74.006, 40.7128]}
+  zoom={10}
+  interactive={true}
+  height="500px"
+/>
+```
+
+The TileMap component uses [MapLibre GL JS](https://maplibre.org/) and [PMTiles](https://protomaps.com/docs/pmtiles) for efficient, interactive mapping. It automatically configures the PMTiles protocol and uses the Reuters Protomaps style by default.
+
+## Globe view
+
+Use the `projection` prop to display a 3D globe. The projection accepts a [ProjectionSpecification](https://maplibre.org/maplibre-style-spec/types/#projectiondefinition) object:
+
+```svelte
+<TileMap
+  id="globe-map"
+  center={[0, 0]}
+  zoom={1}
+  projection={{ type: 'globe' }}
+  interactive={true}
+  height="600px"
+/>
+```
+
+## Non-interactive mode
+
+Disable interaction for static maps:
+
+## Adding GeoJSON layers
+
+Use the `TileMapLayer` component to add GeoJSON data to your map. You can pass GeoJSON data directly or fetch it from a URL. Layer rendering order will directly correspond to the order in which you add the layers in the code.
+
+> **Note for TypeScript users:** When passing GeoJSON data objects, you'll need to type cast them using `as GeoJSON` to ensure TypeScript recognizes the correct type. This provides better type safety and error messages. See examples below.
+
+### Basic example with local data
+
+```svelte
+<script lang="ts">
+  import { TileMap, TileMapLayer } from '@reuters-graphics/graphics-components';
+  import type { GeoJSON } from 'geojson';
+
+  const parkData = {
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        geometry: {
+          type: 'Polygon',
+          coordinates: [
+            [
+              [-73.9577, 40.8005],
+              [-73.9816, 40.7684],
+              [-73.973, 40.7649],
+              [-73.9492, 40.7969],
+              [-73.9577, 40.8005],
+            ],
+          ],
+        },
+        properties: { name: 'Central Park' },
+      },
+    ],
+  };
+</script>
+
+<TileMap center={[-73.9712, 40.7831]} zoom={13}>
+  <!-- Polygon fill -->
+  <TileMapLayer
+    id="park-fill"
+    data={parkData as GeoJSON}
+    type="fill"
+    paint={{
+      'fill-color': '#179639',
+      'fill-opacity': 0.7,
+    }}
+  />
+
+  <!-- Polygon outline -->
+  <TileMapLayer
+    id="park-outline"
+    data={parkData as GeoJSON}
+    type="line"
+    paint={{
+      'line-color': '#228b22',
+      'line-width': 2,
+    }}
+  />
+</TileMap>
+```
+
+### Fetching GeoJSON from a URL
+
+You can also pass a URL string to fetch GeoJSON data:
+
+```svelte
+<TileMap center={[-73.9712, 40.7831]} zoom={11}>
+  <TileMapLayer
+    id="marathon-route"
+    data="https://example.com/path/to/route.geojson"
+    type="line"
+    paint={{
+      'line-color': '#4287f5',
+      'line-width': 2,
+    }}
+  />
+</TileMap>
+```
+
+### Adding point markers
+
+```svelte
+<script lang="ts">
+  import type { GeoJSON } from 'geojson';
+
+  const officeLocation = {
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        geometry: {
+          type: 'Point',
+          coordinates: [-73.9868, 40.7567],
+        },
+        properties: { name: 'Office' },
+      },
+    ],
+  };
+</script>
+
+<TileMap center={[-73.9868, 40.7567]} zoom={14}>
+  <!-- Point marker -->
+  <TileMapLayer
+    id="office-point"
+    data={officeLocation as GeoJSON}
+    type="circle"
+    paint={{
+      'circle-radius': 6,
+      'circle-color': '#ff0000',
+      'circle-stroke-width': 2,
+      'circle-stroke-color': '#ffffff',
+    }}
+  />
+
+  <!-- Text label -->
+  <TileMapLayer
+    id="office-label"
+    data={officeLocation as GeoJSON}
+    type="symbol"
+    layout={{
+      'text-field': 'Office',
+      'text-offset': [0, 1],
+      'text-anchor': 'top',
+      'text-size': 12,
+    }}
+    paint={{
+      'text-color': '#000000',
+      'text-halo-color': '#ffffff',
+      'text-halo-width': 2,
+    }}
+  />
+</TileMap>
+```
+
+### TileMapLayer Props
+
+- **id**: `string` (required) - Unique identifier for the layer
+- **data**: `object | string` (required) - GeoJSON data or URL to fetch from
+- **type**: `'fill' | 'line' | 'circle' | 'symbol' | 'fill-extrusion' | 'raster' | 'background' | 'heatmap' | 'hillshade'` - Layer type (default: `'fill'`)
+- **paint**: `Record<string, unknown>` - Paint properties for the layer
+- **layout**: `Record<string, unknown>` - Layout properties for the layer
+- **beforeId**: `string` - Layer ID to insert before (for ordering)
+- **beneathLabels**: `boolean` - Insert the layer beneath the basemap's labels so place names stay readable on top of it (default: `false`). Ignored when `beforeId` is set. A no-op on styles with no symbol layers.
+- **minZoom**: `number` - Minimum zoom level to display layer
+- **maxZoom**: `number` - Maximum zoom level to display layer
+- **filter**: `unknown[]` - Filter expression for the layer
+
+### Multiple layers example
+
+You can combine multiple layers to create rich visualizations:
+
+```svelte
+<TileMap center={[-73.9712, 40.7831]} zoom={11}>
+  <!-- Background polygon -->
+  <TileMapLayer
+    id="area-fill"
+    data={areaData}
+    type="fill"
+    paint={{ 'fill-color': '#179639', 'fill-opacity': 0.7 }}
+  />
+
+  <!-- Border line -->
+  <TileMapLayer
+    id="area-border"
+    data={areaData}
+    type="line"
+    paint={{ 'line-color': '#228b22', 'line-width': 2 }}
+  />
+
+  <!-- Route from URL -->
+  <TileMapLayer
+    id="route"
+    data="https://example.com/route.geojson"
+    type="line"
+    paint={{ 'line-color': '#4287f5', 'line-width': 2 }}
+  />
+
+  <!-- Point markers -->
+  <TileMapLayer
+    id="markers"
+    data={pointsData}
+    type="circle"
+    paint={{
+      'circle-radius': 4,
+      'circle-color': '#9c27b0',
+      'circle-stroke-width': 2,
+      'circle-stroke-color': '#ffffff',
+    }}
+  />
+</TileMap>
+```
+
+## Advanced usage
+
+For more control over the map, you can use the `onMapReady` callback to access the MapLibre GL instance:
+
+```svelte
+<script>
+  import { TileMap } from '@reuters-graphics/graphics-components';
+  import type { Map as MaplibreMap } from 'maplibre-gl';
+
+  function handleMapReady(map: MaplibreMap) {
+    // Add custom layers, sources, or event handlers
+    map.addSource('my-source', {
+      type: 'geojson',
+      data: myGeoJsonData,
+    });
+
+    map.addLayer({
+      id: 'my-layer',
+      type: 'circle',
+      source: 'my-source',
+      paint: {
+        'circle-radius': 8,
+        'circle-color': '#007cbf',
+      },
+    });
+  }
+</script>
+
+<Map id="custom-map" center={[0, 0]} zoom={2} onMapReady={handleMapReady} />
+```
+
+## Props
+
+- **center**: `[longitude, latitude]` - Map center coordinates (default: `[0, 0]`)
+- **zoom**: `number` - Initial zoom level (default: `2`)
+- **minZoom**: `number` - Minimum zoom level (default: `0`)
+- **maxZoom**: `number` - Maximum zoom level (default: `22`)
+- **interactive**: `boolean` - Enable interactive controls (default: `true`)
+- **styleUrl**: `string` - Map style URL (default: Reuters Protomaps style)
+- **emphasizeLabels**: `boolean` - Darken the basemap's place labels and add a white halo so city/region names stay readable over colored data layers (default: `false`). Applied on map load; a no-op on styles without `place` labels.
+- **height**: `string` - Map height in CSS units (default: `'500px'`)
+- **width**: `ContainerWidth` - Width within the text well (default: `'normal'`)
+- **onMapReady**: `(map: maplibregl.Map) => void` - Callback when map is ready

package/dist/llm-docs/components/ToolsHeader.md

@@ -0,0 +1,46 @@
+# ToolsHeader
+
+**Category:** Components/Page furniture/ToolsHeader
+
+**Import:** `import { ToolsHeader } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `children` | `Snippet` | — |  | Snippet content |
+| `id` | `string` | `''` |  | ID of the header container |
+| `class` | `string` | `''` |  | Add a class to target with SCSS. |
+| `sticky` | `boolean` | `false` |  | Make the header stick when user scrolls. |
+| `background` | `string` | `'transparent'` |  | Background CSS |
+| `borderBottom` | `string` | `'1px solid #dedede'` |  | Border bottom CSS |
+| `logoProps` | `{       logoColour?: string;       textColor?: string;     }` | `{ logoColour: '#404040' }` |  | Colour props passed to `ReutersGraphicsLogo` component. |
+| `homeLink` | `string` | `'/'` |  | Link the logo points to. |
+
+## Examples
+
+### Demo
+
+```svelte
+<div>
+  <ToolsHeader />
+</div>
+```
+
+## Documentation
+
+# ToolsHeader
+
+The `ToolsHeader` component adds a header with the Reuters Graphics logo for internal tooling sites.
+
+> **Note:** Don't use this component for public pages.
+
+```svelte
+<script>
+  import { ToolsHeader } from '@reuters-graphics/graphics-components';
+</script>
+
+<ToolsHeader>
+  <!-- Anything else goes to the right of the logo -->
+</ToolsHeader>
+```