@mapcomponents/react-maplibre 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Change Log
 
+## [v1.0.4] - 2024-06-21
+
+### Added
+- cab1848: add hints to buttons in catalogue stories
+- c621883: Feature/add layer and source events (#167) …
+- fcb3c75: add feature for additional pdf form info to MlPdfForm (#162) …
+- 7994580: add client search component MlClientSearch (#166) …
+- b0d2c32: add makeMapContextDecorators function to enable changing MapLibreMap options inside the sb-story (#165) …
+
+### Changed
+- 20378bc: refactor geojson stories
+- af7e0c4, 6fa9a9b: update README.md
+- 8735ac8: redefiened MlLayer useLayerProps (#160) …
+
+### Fixed
+- a48a8fa: fix MlImageMarkerLayer story
+- 3afbe7b: remove useLayer hook initializedRef anti-pattern and fix reinitializa… (#169) …
+- 14ef756: Fix/usesource stylechange (#168) …
+
+
+## [v1.0.3] - 2024-02-22
+
+### Fixed
+- a80667a: import missing maplibre-gl.css again in MapLibreMap component (#164)
+
 
 ## [v1.0.1] - 2024-02-16
 

package/README.md

@@ -29,13 +29,20 @@ The easiest way to start a new project using this framework is to bootstrap a re
 
 Run the following commands in the terminal:
 
-1. `npx degit mapcomponents/template {your-app-name}`
-2. `cd {your-app-name}`
-3. `yarn`
-4. `yarn dev`
+```
+npx degit mapcomponents/template {your-app-name}
+cd {your-app-name}
+yarn
+yarn dev
+```
+
+<img src="docs_md/initial_0.gif" />
+
 
 This will start a development server that serves the mapcomponents app on port 5174 of your local machine as well as a browser tab with live reload enabled. This reloads the affected parts of the application if changes are detected to the corresponding files in the filesystem. Open the project folder in the IDE of your choice and start building your map client.
 
+<img src="docs_md/initial_3.gif" width="400" />
+
 ### **... an existing react project**
 
 In this case, navigate to your project folder in a terminal and execute the following steps:
@@ -44,70 +51,44 @@ In this case, navigate to your project folder in a terminal and execute the foll
 2. Add the MapComponentsProvider (named export of this module) to your applications react-DOM where it makes sense. Only children of this component will be able to render a map canvas or interact with a maplibre-gl instance. Place it in the index.js entrypoint if your application is a dedicated map app and all components have a high probability to interact with the maplibre-gl instance. Place it somewhere higher in the JSX tree if the map constitutes only a small portion of your app and components outside of the MapComponentsProvider have no need to interact with the map instance.
 3. Add a MapLibreMap component to the react-DOM wherever the map canvas is supposed to be placed.
 
-## How it works
-### Anatomy of a MapComponent
-
-A MapComponent is a react component that accepts at least 1 attribute "mapId" (there are some exceptions) and is expected to retrieve a maplibre-gl instance from mapContext and directly manipulate it or watch its state. 
-An example implementation of basic required functions for the maplibre instance retrieval process using the useMap hook, can be seen in [./components/MlComponentTemplate/MlComponentTemplate.tsx](https://github.com/mapcomponents/react-map-components-maplibre/blob/main/src/components/MlComponentTemplate/MlComponentTemplate.tsx)
-If no attribute mapId is provided the map component is expected to work with the map instance provided by mapContext at ```mapContext.map``` (the first maplibre instance that is registered in MapContext).
-
-
-### Cleanup functions
-
-Once a component is removed from reactDOM we need to make sure everything it has added to the maplibre-gl instance is removed with it. The mapHook offers a convenient way to do this. 
-
-**- Retrieve the maplibre instance using the useMap hook**
-
-Add `mapHook.map` to the dependency array of e.g. a useEffect hook to trigger it once the map instance becomes available.
-
-```js
-
-  const mapHook = useMap({
-    mapId: props.mapId,
-    waitForLayer: props.insertBeforeLayer,
-  });
-
-  useEffect(() => {
-    if (!mapHook.map) return;
-    // the MapLibre-gl instance (mapHook.map) is accessible here
-    // initialize the layer and add it to the MapLibre-gl instance 
-
-    // optionally add layers, sources, event listeners, controls, images to the MapLibre instance that are required by this component
-    mapHook.map.addLayer(
-        {/*layer-config*/},
-        props.insertBeforeLayer,
-        mapHook.componentId)
-
-    return () => {
-      mapHook.cleanup();
-    }
-
-  }, [mapHook.map]);
-
+## Adding data to the map
+
+The easiest way to add data to the map is using GeoJSON data and the MlGeoJsonLayer component. The MlGeoJsonLayer component is designed to require only the `geojson` property to be set, while it provides properties to fully customize it to your needs.
+
+Insert the following code in your app below index.tsx to add a GeoJSON layer to your map.
+
+```JSX
+import MlGeoJsonLayer from '@mapcomponents/react-maplibre';
+
+const geojson_data = {
+	"type": "Feature",
+	"properties": {},
+	"geometry": {
+		"coordinates": [
+			[
+				[0.7415817264899545, 56.91203727013931],
+				[0.7743616447289128, 55.2757658775181],
+				[4.609612078732766, 55.23840364745948],
+				[4.642391996971725, 56.91203727013931],
+				[0.7415817264899545, 56.91203727013931]
+			]
+		],
+		"type": "Polygon"
+	}
+}
 ```
-**- Component cleanup function**
-
-`mapHook.cleanup()` will remove all ressources from the maplibre-gl instance that have been added using `mapHook.componentId` as additional parameter in `map.addLayer`, `map.addSource`, `map.on`, `map.addImage` or `map.addControl` calls.
-
-```js
-
-  useEffect(() => {
 
-    return () => {
-      // This is the cleanup function, it is called when this react component is removed from react-dom
-        mapHook.cleanup();
-    };
-  }, []);
+And add the following within the JSX.
 
+```JSX
+<MlGeoJsonLayer geojson={geojson_data} />
 ```
 
-**- addLayer, addSource, addImage, addControls, on**
+<img src="docs_md/sample_screenshot.png" />
 
-The functions mentioned above have been overridden in the MapLibreGlWrapper instance that is referenced by mapHook.map.
-All five functions expect an additional optional parameter "component_id" (string) as their last or optional parameter (except for the beforeLayerId parameter of the addLayer function, which should be defined as props.beforeLayerId to make sure the parent component is able to control the layer order).
-A uuid `componentId` property is generated and available on the object returned by mapHook.
-MapLibreGlWrapper uses the component_id to keep track of everything that has been added by a specific component (including implicitly added sources), enabling a safe and simple cleanup by calling ```mapHook.cleanup()``` as shown in the cleanup function example above.
+Please take a look at our storybooks and the code examples provided in the {ComponentName}.stories.tsx files next to the Components in the `./src/components/` folder.
 
 ## more links
 
+- @mapcomponents/react-maplibre storybook: https://mapcomponents.github.io/react-map-components-maplibre
 - @mapcomponents/react-maplibre-lab storybook: https://mapcomponents.github.io/react-map-components-maplibre-lab

package/dist/components/MapLibreMap/MapLibreMap.d.ts

@@ -1,5 +1,6 @@
 import { FC } from 'react';
 import { MapOptions as MapOptionsType } from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
 export type MapLibreMapProps = {
     /**
      * Id of the MapLibreGl(Wrapper) instance in mapContext

package/dist/components/MapLibreMap/lib/MapLibreGlWrapper.d.ts

@@ -1,6 +1,6 @@
 import { Map, IControl, MapOptions as MapOptionsType, MapEventType, MapLayerEventType, StyleImageInterface, LayerSpecification, CustomLayerInterface, SourceSpecification, ControlPosition, StyleImageMetadata } from 'maplibre-gl';
 import { Map as MapType, Style } from 'maplibre-gl';
-type WrapperEventArgArray = [string, (arg0: unknown) => void];
+type WrapperEventArgArray = [MapLibreGlWrapperEventName, MapLibreGlWrapperEventHandlerType];
 type EventArgArray = [
     keyof MapLayerEventType | keyof MapEventType,
     string | ((arg0: unknown) => void),
@@ -41,7 +41,30 @@ interface MapLibreGlWrapper extends MapType {
     }), beforeId?: string | undefined, componentId?: string | undefined) => this;
     cancelled: boolean;
 }
+interface MapLibreGlWrapperEventHandlers {
+    layerchange: {
+        handler: (ev: unknown) => void;
+        options?: object | string;
+    }[];
+    viewportchange: {
+        handler: (ev: unknown) => void;
+        options?: object | string;
+    }[];
+    addsource: {
+        handler: (ev: unknown, wrapper?: MapLibreGlWrapper, data?: {
+            [source_id: string]: string;
+        }) => void;
+    }[];
+    addlayer: {
+        handler: (ev: unknown) => void;
+        options?: object | string;
+    }[];
+}
+export type MapLibreGlWrapperEventHandlerType = MapLibreGlWrapperEventHandlers['layerchange'][number]['handler'] | MapLibreGlWrapperEventHandlers['viewportchange'][number]['handler'] | MapLibreGlWrapperEventHandlers['addsource'][number]['handler'] | MapLibreGlWrapperEventHandlers['addlayer'][number]['handler'];
+export type MapLibreGlEventName = keyof MapLayerEventType | keyof MapEventType | string;
+export type MapLibreGlWrapperEventName = keyof MapLibreGlWrapperEventHandlers;
 declare class MapLibreGlWrapper {
+    [key: string]: any;
     registeredElements: {
         [key: string]: {
             layers: [string?];
@@ -54,18 +77,10 @@ declare class MapLibreGlWrapper {
     };
     baseLayers: [string?];
     firstSymbolLayer: string | undefined;
-    eventHandlers: {
-        layerchange: {
-            handler: (ev: unknown) => void;
-            options?: object | string;
-        }[];
-        viewportchange: {
-            handler: (ev: unknown) => void;
-        }[];
-    };
+    eventHandlers: MapLibreGlWrapperEventHandlers;
     wrapper: {
-        on: (eventName: string, handler: (ev: unknown) => void, options?: object | string, componentId?: string) => void;
-        off: (type: string, listener: (ev: unknown) => void) => void;
+        on: (eventName: MapLibreGlWrapperEventName, handler: MapLibreGlWrapperEventHandlerType, options?: object | string, componentId?: string) => void;
+        off: (type: string, handler: MapLibreGlWrapperEventHandlerType) => void;
         fire: (eventName: string, context?: unknown) => void;
         layerState: LayerState[];
         layerStateString: string;
@@ -94,7 +109,7 @@ declare class MapLibreGlWrapper {
     styleJson: object;
     addSource: (id: string, source: SourceSpecification, componentId?: string | undefined) => this;
     addControl: (control: IControl | unknown, position?: ControlPosition | undefined, componentId?: string | undefined) => this;
-    on: (type: keyof MapLayerEventType | keyof MapEventType | string, layerId: string | ((ev: unknown) => void), handler?: ((ev: MapEventType & unknown) => Map | void) | string, componentId?: string | undefined) => this;
+    on: (type: MapLibreGlEventName, layerId: string | ((ev: unknown) => void), handler?: ((ev: MapEventType & unknown) => Map | void) | string, componentId?: string | undefined) => this;
     cleanup: (componentId: string) => void;
     constructor(props: {
         mapOptions: MapOptionsType;

package/dist/components/MlClientSearch/MlClientSearch.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import { SearchContextInterface } from './lib/searchContext';
+interface MlClientSearchProps {
+    /**
+     * Search Engine: http://elasticlunr.com/
+     */
+    searchIndex: SearchContextInterface['searchIndex'];
+    /**
+     * Docs: http://elasticlunr.com/docs/configuration.js.html
+     */
+    fields: SearchContextInterface['fields'];
+    /**
+     * Docs: 	https://mui.com/material-ui/api/autocomplete/
+     */
+    renderOption?: SearchContextInterface['renderOption'];
+    /**
+     * Label search field
+     */
+    searchFieldLabel?: SearchContextInterface['searchFieldLabel'];
+}
+export type { MlClientSearchProps };
+/**
+ * Component template
+ *
+ */
+declare const MlClientSearch: {
+    ({ searchIndex, fields, renderOption, searchFieldLabel, }: MlClientSearchProps): React.JSX.Element;
+    defaultProps: {};
+};
+export default MlClientSearch;

package/dist/components/MlClientSearch/lib/SearchContext.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { SearchContextInterface } from './searchContext.js';
+interface SearchContextProviderProps {
+    children: React.ReactNode;
+    searchIndex: SearchContextInterface['searchIndex'];
+    fields: SearchContextInterface['fields'];
+    renderOption?: SearchContextInterface['renderOption'];
+    searchFieldLabel?: SearchContextInterface['searchFieldLabel'];
+}
+declare const SearchContext: React.Context<SearchContextInterface>;
+declare const SearchContextProvider: React.FC<SearchContextProviderProps>;
+export { SearchContextProvider };
+export default SearchContext;

package/dist/components/MlClientSearch/lib/SearchForm.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export default function SearchForm(): React.JSX.Element;

package/dist/components/MlClientSearch/lib/createGeojsonFeature.d.ts

@@ -0,0 +1,3 @@
+type ExcludedGeometryCollection = GeoJSON.Point | GeoJSON.MultiPoint | GeoJSON.LineString | GeoJSON.MultiLineString | GeoJSON.Polygon;
+export declare function createGeoJSONFeature(coordinates: ExcludedGeometryCollection['coordinates']): GeoJSON.Feature<ExcludedGeometryCollection>;
+export {};

package/dist/components/MlCreatePdfForm/MlCreatePdfForm.d.ts

@@ -1,28 +1,11 @@
 import React from 'react';
-import { createPdfResolverParams } from '../../hooks/useExportMap/lib';
-import { SxProps } from '@mui/material';
-interface MlCreatePdfFormProps {
-    /**
-     * Id of the target MapLibre instance in mapContext
-     */
-    mapId?: string;
-    /**
-     * sx props that will be applied to the form control components
-     */
-    formControlStyles?: SxProps;
-    /**
-     * Function that will be called before the PDF is created.
-     * Allowing to access and manipulate the jspdf instance before the PDF is created.
-     */
-    onCreatePdf?: (options: createPdfResolverParams) => createPdfResolverParams;
-}
-export type { MlCreatePdfFormProps };
+import { PdfFormProps } from './lib/PdfForm';
 /**
  * Create PDF Form Component
  *
  */
 declare const MlCreatePdfForm: {
-    (props: MlCreatePdfFormProps): React.JSX.Element;
+    (props: PdfFormProps): React.JSX.Element;
     defaultProps: {
         mapId: undefined;
     };

package/dist/components/MlCreatePdfForm/lib/PdfForm.d.ts

@@ -1,11 +1,25 @@
 import React from 'react';
+import { SxProps } from '@mui/material';
 import { createPdfResolverParams } from '../../../hooks/useExportMap/lib';
-interface PdfFormProps {
+export interface PdfFormProps {
     /**
      * Id of the target MapLibre instance in mapContext
      */
     mapId?: string;
+    /**
+     * Function that will be called before the PDF is created.
+     * Allowing to access and manipulate the jspdf instance before the PDF is created.
+     */
     onCreatePdf?: (options: createPdfResolverParams) => createPdfResolverParams;
+    /**
+     * sx props that will be applied to the form control components
+     */
+    formControlStyles?: SxProps;
+    /**
+     * Define additional form fields that will be added to the bottom of the create-PDF form.
+     * Values of form elements added this way are accessible inside the function passed to the onCreatePdf property using options.formData.get('{form_el_name}').
+     * Make sure all form elements added this way have a name property defined to be able to access the value when rendering the PDF.
+     */
+    additionalFields?: React.ReactNode;
 }
 export default function PdfForm(props: PdfFormProps): React.JSX.Element;
-export {};

package/dist/decorators/MapContextDecorator.d.ts

@@ -1,4 +1,7 @@
+import { MapLibreMapProps } from '../components/MapLibreMap/MapLibreMap';
 import './style.css';
 import { Decorator } from '@storybook/react';
-declare const decorators: Decorator[];
-export default decorators;
+declare const makeMapContextDecorators: (options: MapLibreMapProps['options']) => Decorator[];
+declare const _default: Decorator[];
+export default _default;
+export { makeMapContextDecorators };

package/dist/hooks/useExportMap/lib.d.ts

@@ -27,6 +27,7 @@ interface createJsPdfOptions extends createExportOptions {
 }
 export type { createJsPdfOptions };
 interface createPdfResolverParams extends createJsPdfOptions {
+    formData: FormData;
     pdf: jsPDF;
     downloadPdf: (_options?: downloadPdfOptions) => Promise<downloadPdfOptions>;
 }

package/dist/hooks/useMapState.d.ts

@@ -1,4 +1,3 @@
-import PropTypes from "prop-types";
 import { LayerState, ViewportState } from "../components/MapLibreMap/lib/MapLibreGlWrapper";
 type useMapStateType = {
     layers: (LayerState | undefined)[];
@@ -34,29 +33,5 @@ declare namespace useMapState {
             includeBaseLayers: boolean;
         };
     };
-    var propTypes: {
-        /**
-         * Id of the target MapLibre instance in mapContext
-         */
-        mapId: PropTypes.Requireable<string>;
-        /**
-         * Defines map Resources to watch
-         */
-        watch: PropTypes.Requireable<PropTypes.InferProps<{
-            layers: PropTypes.Requireable<boolean>;
-            sources: PropTypes.Requireable<boolean>;
-            viewport: PropTypes.Requireable<boolean>;
-        }>>;
-        /**
-         * Filter string or RegExp to more explicitly define the elements watched and increase performance
-         * strings will be matched using layerId.includes(matchString)
-         * RegExps will be matched using matchRegExp.test(layerId)
-         */
-        filter: PropTypes.Requireable<PropTypes.InferProps<{
-            includeBaseLayers: PropTypes.Requireable<boolean>;
-            matchLayerIds: PropTypes.Requireable<NonNullable<string | RegExp | null | undefined>>;
-            matchSourceIds: PropTypes.Requireable<NonNullable<string | RegExp | null | undefined>>;
-        }>>;
-    };
 }
 export default useMapState;