@indiscale/linkahead-webui-ext-map 0.5.0

package/src/context/LoadingProvider.tsx

@@ -0,0 +1,117 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+  useCallback,
+  type ReactNode,
+} from "react";
+
+/**
+ * LoadingContext
+ * --------------
+ * Global loading state for the application.
+ *
+ * This context tracks whether *any* async operation is currently in progress.
+ * It supports multiple concurrent operations by keeping an internal counter.
+ *
+ * If at least one operation is running -> loading === true
+ * If all operations have finished -> loading === false
+ */
+type TLoadingContextValue = {
+  loading: boolean;
+  startLoading: () => void;
+  stopLoading: () => void;
+};
+
+const LoadingContext = createContext<TLoadingContextValue | null>(null);
+
+/**
+ * LoadingProvider
+ * ---------------
+ * Provides a global loading state using a reference counter.
+ *
+ * Why a counter?
+ * - Multiple components may start async work at the same time
+ * - We only want to hide the spinner when *all* of them are finished
+ *
+ * Implementation details:
+ * - `inFlightRef` tracks how many operations are currently running
+ * - `loading` is derived from whether the counter is > 0
+ *
+ * This avoids race conditions and works correctly with React Strict Mode.
+ */
+type TLoadingProviderProps = {
+  children: ReactNode;
+};
+
+export const LoadingProvider = ({ children }: TLoadingProviderProps) => {
+  // Global loading state
+  const [loading, setLoading] = useState(false);
+
+  // Internal counter for active async operations
+  const inFlightRef = useRef(0);
+
+  /**
+   * startLoading
+   * ------------
+   * Call this when an async operation starts.
+   *
+   * Increments the counter and ensures `loading` is true.
+   */
+  const startLoading = useCallback(() => {
+    inFlightRef.current += 1;
+    setLoading(true);
+  }, []);
+
+  /**
+   * stopLoading
+   * -----------
+   * Call this when an async operation finishes or is cancelled.
+   *
+   * Decrements the counter and only sets `loading` to false
+   * when *no* operations are left.
+   */
+  const stopLoading = useCallback(() => {
+    inFlightRef.current = Math.max(0, inFlightRef.current - 1);
+
+    if (inFlightRef.current === 0) {
+      setLoading(false);
+    }
+  }, []);
+
+  /**
+   * Memoized context value to avoid unnecessary re-renders.
+   */
+  const value = useMemo<TLoadingContextValue>(
+    () => ({ loading, startLoading, stopLoading }),
+    [loading, startLoading, stopLoading]
+  );
+
+  return (
+    <LoadingContext.Provider value={value}>{children}</LoadingContext.Provider>
+  );
+};
+
+/**
+ * useLoading
+ * ----------
+ * Hook to access the global loading state.
+ *
+ * Must be used inside a <LoadingProvider>.
+ *
+ * Returns:
+ * - loading: boolean
+ * - startLoading(): void
+ * - stopLoading(): void
+ */
+export const useLoading = (): TLoadingContextValue => {
+  const ctx = useContext(LoadingContext);
+
+  if (!ctx) {
+    throw new Error("useLoading must be used within a <LoadingProvider>");
+  }
+
+  return ctx;
+};

package/src/context/PathIdProvider.js

@@ -0,0 +1,102 @@
+import { createContext, useContext, useMemo, useState } from "react";
+
+/**
+ * PathIdContext
+ * -------------
+ * Holds the currently selected path ID for the map.
+ *
+ * The path ID represents which logical path / filter is currently active
+ * (e.g. "same", a concrete path key, etc.).
+ *
+ * This value is shared across components via React Context.
+ */
+const PathIdContext = createContext(null);
+
+/**
+ * get_last_path_id
+ * ----------------
+ * Reads the last selected path ID from sessionStorage.
+ *
+ * Why sessionStorage?
+ * - The selected path should persist across page reloads
+ * - But NOT across browser sessions (unlike localStorage)
+ * - Accessable in other parts of the App
+ *
+ * Edge case handling:
+ * - older code has written "undefined"
+ *   into sessionStorage — we treat that as invalid and return null.
+ *
+ * @returns {string | null}
+ */
+const get_last_path_id = () => {
+  const old = sessionStorage.getItem("caosdb_map.display_path");
+
+  if (old === "undefined") {
+    // Defensive fallback for corrupted values
+    return null;
+  }
+
+  return old;
+};
+
+/**
+ * PathIdProvider
+ * --------------
+ * Provides the current path ID and a setter function to all descendants.
+ *
+ * Initialization logic:
+ * - If a previously selected path exists in sessionStorage, use it
+ * - Otherwise fall back to the special value `"same"`
+ *
+ * The context value is memoized to avoid unnecessary re-renders.
+ */
+export const PathIdProvider = ({ children }) => {
+  const [pathId, setPathId] = useState(() => get_last_path_id() ?? "same");
+
+  /**
+   * Memoized context value:
+   * - `setPathId` is stable by React guarantees
+   * - `pathId` changes trigger updates where needed
+   */
+  const value = useMemo(() => ({ pathId, setPathId }), [pathId]);
+
+  return (
+    <PathIdContext.Provider value={value}>{children}</PathIdContext.Provider>
+  );
+};
+
+/**
+ * Runtime prop validation.
+ *
+ * Ensures that PathIdProvider is always used with children.
+ */
+PathIdProvider.propTypes = {
+  children: (props, propName, componentName) => {
+    if (!props[propName]) {
+      return new Error(`${componentName} requires children`);
+    }
+    return null;
+  },
+};
+
+/**
+ * usePathId
+ * ---------
+ * Convenience hook to access the PathIdContext.
+ *
+ * Must be used inside a <PathIdProvider>.
+ *
+ * @returns {{
+ *   pathId: string,
+ *   setPathId: (value: string) => void
+ * }}
+ */
+export const usePathId = () => {
+  const ctx = useContext(PathIdContext);
+
+  if (!ctx) {
+    throw new Error("usePathId must be used within a <PathIdProvider>");
+  }
+
+  return ctx;
+};

package/src/contrib/latlnggraticule/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) JS Foundation and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/src/contrib/latlnggraticule/README.md

@@ -0,0 +1,68 @@
+# leaflet.latlng-graticule
+
+Create a Canvas as ImageOverlay to draw the Lat/Lon Graticule,
+
+and show the grid tick label at the edges of the map.
+
+Check out the [demo](https://cloudybay.github.io/leaflet.latlng-graticule/example/).
+
+### Usage example
+
+```javascript
+L.latlngGraticule({
+  showLabel: true,
+  dashArray: [5, 5],
+  zoomInterval: [
+    { start: 2, end: 3, interval: 30 },
+    { start: 4, end: 4, interval: 10 },
+    { start: 5, end: 7, interval: 5 },
+    { start: 8, end: 10, interval: 1 },
+  ],
+}).addTo(map);
+```
+
+### Options
+
+- **showLabel**: Show the grid tick label at the edges of the map. Default `true`
+- **opacity**: Opacity of the Graticule and Label. Default `1`
+- **weight**: The width of the graticule lines. Default `0.8`
+- **color**: The color of the graticule lines. Default `#aaa`
+- **font**: Font Style for the tick label. Default `12px Verdana`
+- **fontColor**: Color of the tick label. Default `#aaa`
+- **dashArray**: Used to achieve dashed lines. Default `[0,0]`
+- **sides**: Used to name sides of the world. Default `['N', 'S', 'E', 'W']`
+- **zoomInterval**: Use different intervals in different zoom levels. You can set for both latitude and longitude lines as the example, or set different intervals for latitude and longitude like below:
+
+```javascript
+  zoomInterval: {
+    latitude: [
+      {start: 4, end: 6, interval: 5},
+      {start: 7, end: 20, interval: 1}
+    ],
+    longitude: [
+      {start: 4, end: 6, interval: 10},
+      {start: 7, end: 20, interval: 2}
+    ]
+  }
+```
+
+- **_Default_**:
+
+```javascript
+zoomInterval: [
+  { start: 2, end: 2, interval: 40 },
+  { start: 3, end: 3, interval: 20 },
+  { start: 4, end: 4, interval: 10 },
+  { start: 5, end: 7, interval: 5 },
+  { start: 8, end: 20, interval: 1 },
+];
+```
+
+#### Special Options
+
+Some of the projections (like Lambert) is no straight line, set those options to draw a polyline graticule.
+
+- **lngLineCurved**: Interval of polyline. Deafult `0`
+- **latLineCurved**: Interval of polyline. Deafult `0`
+
+Check out the [Lambert projection example](https://cloudybay.github.io/leaflet.latlng-graticule/example/lambert.html).