@databiosphere/findable-ui 0.0.0

package/src/hooks/useLayoutState.ts

@@ -0,0 +1,13 @@
+import { useContext } from "react";
+import {
+  LayoutStateContext,
+  LayoutStateContextProps,
+} from "../providers/layoutState";
+
+/**
+ * Returns layout state context.
+ * @returns layout state context.
+ */
+export const useLayoutState = (): LayoutStateContextProps => {
+  return useContext(LayoutStateContext);
+};

package/src/hooks/useLocalStorage/common/utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Return the value for the specified key.
+ * @param key - Key.
+ * @returns value.
+ */
+export function getLocalStorage(key: string): string | null {
+  if (typeof window === "undefined") return null;
+  return window?.localStorage?.getItem(key) ?? null;
+}
+
+/**
+ * Set the value for the specified key.
+ * @param key - Key.
+ * @param value - Value.
+ */
+export function setLocalStorage(key: string, value: string): void {
+  if (typeof window === "undefined") return;
+  window?.localStorage?.setItem(key, value);
+}

package/src/hooks/useLocalStorage/useLocalStorage.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from "react";
+import { getLocalStorage } from "./common/utils";
+
+/**
+ * Determine local storage value.
+ * @param key - Local storage key.
+ * @returns local storage value.
+ */
+export function useLocalStorage(key: string): string | null {
+  const [value, setValue] = useState<string | null>(null);
+
+  useEffect(() => {
+    setValue(getLocalStorage(key));
+  }, [key]);
+
+  return value;
+}

package/src/hooks/useLocation.ts

@@ -0,0 +1,25 @@
+import { isSSR } from "../utils/ssr";
+
+interface Result {
+  href: string;
+  pathname: string;
+  search: URLSearchParams;
+}
+
+/**
+ * Hook used to get the url properties from the location object
+ * Most of the time you can get the same result with useRouter(). This hook has a single use case:
+ *  - When you need to get the url properties ready on the first render, before ReactDOM.hydrate
+ * @returns an object containing url's pathname and search params
+ */
+export const useLocation = (): Result | null => {
+  if (isSSR()) {
+    return null;
+  }
+  const { href, pathname, search } = window.location;
+  return {
+    href,
+    pathname,
+    search: new URLSearchParams(search),
+  };
+};

package/src/hooks/useRequestFileLocation.ts

@@ -0,0 +1,159 @@
+import { MutableRefObject, useCallback, useEffect, useRef } from "react";
+import {
+  FILE_LOCATION_PENDING,
+  FILE_LOCATION_SUCCESSFULLY,
+} from "../apis/azul/common/constants";
+import { FileLocationResponse } from "../apis/azul/common/entities";
+import { useAsync } from "./useAsync";
+import { useAuthentication } from "./useAuthentication/useAuthentication";
+
+export interface FileLocation {
+  commandLine?: { [key: string]: string };
+  location: string;
+  retryAfter?: number;
+  status: number;
+}
+
+export interface UseRequestFileLocationResult {
+  data: FileLocation | undefined;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  run: () => void;
+}
+
+export type Method = METHOD;
+
+export enum METHOD {
+  GET = "GET",
+  PUT = "PUT",
+}
+
+type ResolveFn = (file: FileLocation | PromiseLike<FileLocation>) => void;
+type RejectFn = (reason: FileLocation) => void;
+
+/**
+ * Returns fetch request options.
+ * @param accessToken - Access token.
+ * @param method - Method to be used by the request
+ * @returns fetch request options.
+ */
+function createFetchOptions(
+  accessToken: string | undefined,
+  method: Method
+): RequestInit {
+  return {
+    headers: accessToken ? { Authorization: "Bearer " + accessToken } : {},
+    method,
+  };
+}
+
+/**
+ * Function to make a get request and map the result to camelCase
+ * @param url - url for the get request
+ * @param accessToken - Access token.
+ * @param method - Method to be used by the request
+ * @returns @see FileLocation
+ */
+export const getFileLocation = async (
+  url: string,
+  accessToken: string | undefined,
+  method: Method
+): Promise<FileLocation> => {
+  const options = createFetchOptions(accessToken, method);
+  const res = await fetch(url, options);
+  const jsonRes: FileLocationResponse = await res.json();
+  return {
+    commandLine: jsonRes.CommandLine,
+    location: jsonRes.Location,
+    retryAfter: jsonRes["Retry-After"],
+    status: jsonRes.Status,
+  };
+};
+
+/**
+ * Function that will recursively keep making requests to get the file location until gets a 302 or an error.
+ * @param url - url for the get request
+ * @param accessToken - Access token.
+ * @param resolve - function to resolve the running promise
+ * @param reject - function to reject the running promise
+ * @param active - Mutable object used to check if the page is still mounted and the requests should keep executing
+ * @param retryAfter - timeout value
+ * @param method - Method to be used by the request
+ */
+const scheduleFileLocation = (
+  url: string,
+  accessToken: string | undefined,
+  resolve: ResolveFn,
+  reject: RejectFn,
+  active: MutableRefObject<boolean>,
+  retryAfter = 0,
+  method: Method = METHOD.GET
+): void => {
+  setTimeout(() => {
+    getFileLocation(url, accessToken, method).then((result: FileLocation) => {
+      if (result.status === FILE_LOCATION_PENDING) {
+        if (!active.current) {
+          reject({
+            location: "",
+            status: 499, //Client Closed Request
+          });
+          return;
+        }
+        scheduleFileLocation(
+          result.location,
+          accessToken,
+          resolve,
+          reject,
+          active,
+          result.retryAfter
+        );
+      } else if (result.status === FILE_LOCATION_SUCCESSFULLY) {
+        resolve(result);
+      } else {
+        reject(result);
+      }
+    });
+  }, retryAfter * 1000);
+};
+
+/**
+ * Hook to get a file location using a retry-after approach
+ * @param url - to be used on the get request
+ * @param method - Method to be used by the request
+ * @returns data object with the file location
+ */
+export const useRequestFileLocation = (
+  url?: string,
+  method?: Method
+): UseRequestFileLocationResult => {
+  // Grab token from authentication.
+  const { token } = useAuthentication();
+  const {
+    data,
+    isIdle,
+    isLoading,
+    isSuccess,
+    run: runAsync,
+  } = useAsync<FileLocation>();
+  const active = useRef<boolean>(true);
+
+  useEffect(() => {
+    active.current = true;
+    return () => {
+      active.current = false;
+    };
+  }, []);
+
+  const run = useCallback(() => {
+    if (url) {
+      runAsync(
+        new Promise<FileLocation>((resolve, reject) => {
+          scheduleFileLocation(url, token, resolve, reject, active, 0, method);
+        })
+      );
+    }
+  }, [runAsync, token, url, method]);
+
+  return { data, isIdle, isLoading, isSuccess, run };
+};

package/src/hooks/useResetableState.ts

@@ -0,0 +1,18 @@
+import { Dispatch, SetStateAction, useEffect, useState } from "react";
+
+/**
+ * useState hook wrapper that will keep the state updated if the defaultValue changes
+ * @param defaultState - param that determine the default and current state
+ * @returns current state the setter function
+ */
+export const useResetableState = <T>(
+  defaultState: T
+): [T, Dispatch<SetStateAction<T>>] => {
+  const [state, setState] = useState<T>(defaultState);
+
+  useEffect(() => {
+    setState(defaultState);
+  }, [defaultState]);
+
+  return [state, setState];
+};

package/src/hooks/useResizeObserver.ts

@@ -0,0 +1,111 @@
+import { RefObject, useCallback, useEffect, useRef, useState } from "react";
+
+export type ElementRect = {
+  bottom: number;
+  height: number;
+  left: number;
+  right: number;
+  top: number;
+  width: number;
+  x: number;
+  y: number;
+};
+
+/**
+ * Element resizing and repositioning observer.
+ * @param ref - element to be observed for changes to its size or position.
+ * @param onResizeFn - action to be performed when the observed element is resized or repositioned.
+ * @returns Element size and position properties for the given element.
+ */
+export function useResizeObserver(
+  ref: RefObject<HTMLElement>,
+  onResizeFn: (entries: ResizeObserverEntry[]) => Partial<ElementRect>
+): Partial<ElementRect> | undefined {
+  const [elementRect, setElementRect] = useState<Partial<ElementRect>>();
+  const observerRef = useRef<ResizeObserver>();
+
+  // Observed element is resized or repositioned - set state elementRect with the element's new dimensions or position.
+  const onResize = useCallback(
+    (entries: ResizeObserverEntry[]) => {
+      if (entries && entries.length > 0) {
+        const nextElementRect = onResizeFn(entries);
+        setElementRect((elRect) => getNextElementRect(elRect, nextElementRect));
+      }
+    },
+    [onResizeFn]
+  );
+
+  // Creates a new ResizeObserver object which can be used to report changes to an "observed" element's dimensions or position.
+  useEffect(() => {
+    if (!ref.current) return;
+    observerRef.current = new ResizeObserver(onResize);
+    const observer = observerRef.current;
+    const observedEl = ref.current;
+    observer.observe(observedEl);
+    return () => {
+      observer.unobserve(observedEl);
+    };
+  }, [onResize, ref]);
+
+  return elementRect;
+}
+
+/**
+ * Return's the observed element's border box size.
+ * @param entries - Resize observer entries.
+ * @returns observed element's border box size.
+ */
+export function getBorderBoxSize(
+  entries: ResizeObserverEntry[]
+): Partial<ElementRect> {
+  const entry = entries[0]; // grab the first entry; observing a single element.
+  const borderBoxSize = entry.borderBoxSize[0];
+  return {
+    height: borderBoxSize.blockSize,
+    width: borderBoxSize.inlineSize,
+  };
+}
+
+/**
+ * Return's the observed element's border box height.
+ * @param entries - Resize observer entries.
+ * @returns observed element's border box height.
+ */
+export function getBorderBoxSizeHeight(
+  entries: ResizeObserverEntry[]
+): Partial<ElementRect> {
+  const { height } = getBorderBoxSize(entries);
+  return { height };
+}
+
+/**
+ * Return's the observed element's size and position properties.
+ * @param entries - Resize observer entries.
+ * @returns the observed element's size and position properties.
+ */
+export function getContentRect(entries: ResizeObserverEntry[]): ElementRect {
+  const entry = entries[0]; // grab the first entry; observing a single element
+  const contentRect = entry.contentRect.toJSON();
+  return {
+    ...contentRect,
+  };
+}
+
+/**
+ * Return's the next observed element's size and position properties.
+ * @param elementRect - Current observed element's rect properties.
+ * @param nextElementRect - Next observed element's rect properties.
+ * @returns the next observed element's size and position properties.
+ */
+export function getNextElementRect(
+  elementRect: Partial<ElementRect> | undefined,
+  nextElementRect: Partial<ElementRect> | undefined
+): Partial<ElementRect> | undefined {
+  if (!nextElementRect) return elementRect;
+  for (const [key, value] of Object.entries(nextElementRect)) {
+    if (elementRect?.[key as keyof ElementRect] !== value) {
+      return { ...elementRect, ...nextElementRect };
+    }
+  }
+  return elementRect;
+}

package/src/hooks/useScroll.ts

@@ -0,0 +1,21 @@
+import { useCallback } from "react";
+
+type ScrollType = "top" | "bottom";
+
+type UseScrollReturn = () => void;
+
+/**
+ * Hook used to scroll the to top or bottom of the page.
+ * This hook can only be used on the client-side.
+ * @param scrollType - top or bottom of the page. Default = top
+ * @returns scroll function
+ */
+export const useScroll = (scrollType: ScrollType = "top"): UseScrollReturn => {
+  return useCallback(
+    () =>
+      window.scrollTo({
+        top: scrollType === "top" ? 0 : document.body.scrollHeight,
+      }),
+    [scrollType]
+  );
+};

package/src/hooks/useSessionTimeout.ts

@@ -0,0 +1,34 @@
+import { useEffect, useState } from "react";
+import { useLocation } from "./useLocation";
+
+export const INACTIVITY_PARAM = "inactivityTimeout";
+
+interface UseSessionTimeout {
+  clearSessionTimeout: () => void;
+  isSessionTimeout: boolean;
+}
+
+/**
+ * Session timeout hook.
+ * @returns flag indicating if the session has timed out.
+ */
+export const useSessionTimeout = (): UseSessionTimeout => {
+  const [isSessionTimeout, setIsSessionTimeout] = useState<boolean>(false);
+  // Get the session timeout from URL parameters.
+  const { search } = useLocation() || {};
+  const sessionTimeout = search?.get(INACTIVITY_PARAM);
+
+  // Clears session timeout state.
+  const clearSessionTimeout = (): void => {
+    setIsSessionTimeout(false);
+  };
+
+  useEffect(() => {
+    setIsSessionTimeout(sessionTimeout === "true");
+  }, [sessionTimeout]);
+
+  return {
+    clearSessionTimeout,
+    isSessionTimeout,
+  };
+};

package/src/hooks/useSummary.ts

@@ -0,0 +1,47 @@
+import { useEffect } from "react";
+import { AzulSummaryResponse } from "../apis/azul/common/entities";
+import { useAsync } from "./useAsync";
+import { useAuthentication } from "./useAuthentication/useAuthentication";
+import { useConfig } from "./useConfig";
+import { useEntityService } from "./useEntityService";
+import { useExploreState } from "./useExploreState";
+
+interface UseSummaryResponse {
+  isLoading: boolean;
+  response?: AzulSummaryResponse;
+}
+
+/**
+ * Hook responsible for handling the load of the summary values displayed on an entity index page.
+ * @returns an object with the loaded data and a flag indicating is the data is loading
+ */
+export const useSummary = (): UseSummaryResponse => {
+  const { token } = useAuthentication();
+  const { config } = useConfig();
+  const { exploreState } = useExploreState();
+  const { filterState } = exploreState;
+  const { summaryConfig } = config;
+  const {
+    data: response,
+    isLoading: apiIsLoading,
+    run,
+  } = useAsync<AzulSummaryResponse>();
+  const { catalog, fetchSummary } = useEntityService(); // Determine type of fetch to be executed, either API endpoint or TSV.
+
+  useEffect(() => {
+    if (summaryConfig) {
+      run(fetchSummary(filterState, catalog, token));
+    }
+  }, [catalog, fetchSummary, filterState, run, summaryConfig, token]);
+
+  // Return if there's no summary config for this site.
+  if (!summaryConfig) {
+    return { isLoading: false }; //TODO: return a summary placeholder
+  }
+
+  // Return the fetch status and summary data once fetch is complete..
+  return {
+    isLoading: apiIsLoading,
+    response,
+  };
+};

package/src/hooks/useSystemStatus.ts

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+import { SystemStatus, SystemStatusContext } from "../providers/systemStatus";
+
+/**
+ * Returns system status.
+ * @returns system status.
+ */
+export const useSystemStatus = (): SystemStatus => {
+  return useContext(SystemStatusContext);
+};

package/src/hooks/useURLFilterParams.ts

@@ -0,0 +1,57 @@
+import { useRouter } from "next/router";
+import { useCallback } from "react";
+import { SelectedFilter } from "../common/entities";
+import { CatalogState } from "../providers/exploreState";
+import { useLocation } from "./useLocation";
+
+interface UseURLFilterParamsResult {
+  decodedCatalogParam: string | undefined;
+  decodedFilterParam: string;
+  updateFilterQueryString: (
+    catalogState: CatalogState,
+    filterState: SelectedFilter[]
+  ) => void;
+}
+
+/**
+ * useURLFilterParams hook is used to keep track of the url search params, and update them,
+ * if needed
+ * @returns an object containing a update function and the current filter
+ */
+export const useURLFilterParams = (): UseURLFilterParamsResult => {
+  const { basePath, push } = useRouter();
+  const { href, pathname, search } = useLocation() || {};
+  const filterParam = search?.get("filter") ?? "[]";
+  const catalogParam = search?.get("catalog") ?? undefined;
+
+  const updateFilterQueryString = useCallback(
+    (catalogState: CatalogState, filterState: SelectedFilter[]) => {
+      if (
+        catalogParam !== catalogState ||
+        filterParam !== JSON.stringify(filterState)
+      ) {
+        const filter =
+          filterState.length > 0 ? { filter: JSON.stringify(filterState) } : {};
+        const catalog = catalogState ? { catalog: catalogState } : {};
+        push(
+          {
+            pathname: pathname?.replace(basePath, ""),
+            query: { ...catalog, ...filter },
+          },
+          undefined,
+          {
+            shallow: true,
+          }
+        );
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- push method isn't memoized and shouldn't be added as deps https://github.com/vercel/next.js/issues/18127
+    [catalogParam, filterParam, href]
+  );
+
+  return {
+    decodedCatalogParam: catalogParam,
+    decodedFilterParam: filterParam,
+    updateFilterQueryString,
+  };
+};

package/src/hooks/useUpdateURLCatalogParam.ts

@@ -0,0 +1,21 @@
+import Router, { useRouter } from "next/router";
+import { useEffect } from "react";
+import { useExploreState } from "./useExploreState";
+
+/**
+ * Updates URL catalog params.
+ */
+export const useUpdateURLCatalogParams = (): void => {
+  const { exploreState } = useExploreState();
+  const { basePath, pathname, query } = useRouter();
+  const { catalogState } = exploreState;
+
+  useEffect(() => {
+    if (!catalogState) return;
+    if ("catalog" in query && query.catalog === catalogState) return;
+    Router.replace({
+      pathname: pathname?.replace(basePath, ""),
+      query: { ...query, catalog: catalogState },
+    });
+  }, [basePath, catalogState, pathname, query]);
+};

package/src/hooks/useUpdateURLSearchParams.ts

@@ -0,0 +1,19 @@
+import { useEffect } from "react";
+import { useExploreState } from "./useExploreState";
+import { useURLFilterParams } from "./useURLFilterParams";
+
+/**
+ * Updates URL search params when the filter state changes.
+ */
+export const useUpdateURLSearchParams = (): void => {
+  const { exploreState } = useExploreState();
+  const { updateFilterQueryString } = useURLFilterParams();
+  const { catalogState, filterState } = exploreState;
+
+  /**
+   * Update the URL search params when the filter state changes.
+   */
+  useEffect(() => {
+    updateFilterQueryString(catalogState, filterState);
+  }, [catalogState, filterState, updateFilterQueryString]);
+};

package/src/hooks/useWindowResize.ts

@@ -0,0 +1,47 @@
+import { useEffect, useRef, useState } from "react";
+
+export interface WindowSize {
+  height: number;
+  width: number;
+}
+
+/**
+ * Listens to window resize event and returns window height and width values.
+ * @param timeout - Timeout in milliseconds to wait before recalculating window size.
+ * @returns window height and width values.
+ */
+export const useWindowResize = (timeout = 200): WindowSize => {
+  const timeoutRef = useRef<NodeJS.Timeout>();
+  const [windowSize, setWindowSize] = useState<WindowSize>(getWindowSize());
+
+  useEffect(() => {
+    /**
+     * Resize event fired; window size recalculated.
+     */
+    const onResize = (): void => {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => {
+        setWindowSize(getWindowSize());
+      }, timeout);
+    };
+    // Add resize event listener.
+    window.addEventListener("resize", onResize);
+    return () => {
+      // Remove resize event listener.
+      window.removeEventListener("resize", onResize);
+      // Clear timeout.
+      clearTimeout(timeoutRef.current);
+    };
+  }, [timeout]);
+
+  return windowSize;
+};
+
+/**
+ * Returns window height and width.
+ * @returns window height and width.
+ */
+function getWindowSize(): WindowSize {
+  const { innerHeight, innerWidth } = window;
+  return { height: innerHeight, width: innerWidth };
+}

package/src/images/logo.svg

@@ -0,0 +1,3 @@
+<svg width="178" height="200" viewBox="0 0 178 200" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M177.323 50.4336L90.251 -0.000976562L0.800781 50.4336V148.694L90.251 199.999L177.323 148.694V50.4336ZM168.497 55.3906L90.1321 9.99902L9.62695 55.3906V143.825L90.1321 189.999L168.497 143.825V55.3906Z" fill="#82BE37"/>
+</svg>

package/src/index.ts

@@ -0,0 +1 @@
+export type {} from "../types/data-explorer-ui";