@kosmeo-ui/react 0.1.0

package/src/hooks/useInfinite.ts

@@ -0,0 +1,151 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { AxiosInstance } from "axios";
+
+interface InfiniteResponse<T> {
+  data: T[];
+  total: number;
+  hasMore: boolean;
+}
+
+interface UseInfiniteOptions {
+  axiosInstance: AxiosInstance;
+  /** The API endpoint to fetch from (e.g., "/buckets/my-bucket/objects") */
+  endpoint: string;
+  /** The query key for React Query caching */
+  queryKey: string;
+  /** Organization ID to scope cache keys (prevents stale cross-org data) */
+  orgId?: string | null;
+  /** Initial limit (default: 10) */
+  initialLimit?: number;
+  /** Whether or not the query should be enabled */
+  enabled?: boolean;
+}
+
+export interface UseInfiniteReturn<T> {
+  data: T[];
+  hasMore: boolean;
+  isLoading: boolean;
+  isReloading: boolean;
+  total: number;
+  onQueryChange: (queryString: string) => void;
+  reload: () => void;
+}
+
+const useInfinite = <T extends { id: number | string }>(
+  options: UseInfiniteOptions
+): UseInfiniteReturn<T> => {
+  const {
+    axiosInstance,
+    endpoint,
+    queryKey,
+    orgId,
+    initialLimit = 10,
+  } = options;
+
+  const [queryString, setQueryString] = useState(
+    `limit=${initialLimit}&offset=0`
+  );
+  const [allData, setAllData] = useState<T[]>([]);
+  const [reloadKey, setReloadKey] = useState(0);
+  const isNextPageRef = useRef(false);
+  const lastQueryStringRef = useRef(queryString);
+  const queryStringRef = useRef(queryString);
+
+  // Keep ref in sync with state
+  queryStringRef.current = queryString;
+
+  const queryFn = async (): Promise<InfiniteResponse<T>> => {
+    const res = await axiosInstance.get(`${endpoint}?${queryString}`);
+    return res.data;
+  };
+
+  const query = useQuery({
+    queryKey: [`${queryKey}-infinite`, orgId ?? null, queryString, reloadKey],
+    queryFn,
+    staleTime: 0,
+    gcTime: 0,
+  });
+
+  // Handle query change from InfiniteScroll
+  const handleQueryChange = useCallback((newQueryString: string) => {
+    // Prevent unnecessary updates if query string hasn't changed
+    if (newQueryString === lastQueryStringRef.current) return;
+    lastQueryStringRef.current = newQueryString;
+
+    const params = new URLSearchParams(newQueryString);
+    const offset = parseInt(params.get("offset") || "0", 10);
+
+    if (offset === 0) {
+      // Fresh fetch - reset data only if we have data
+      setAllData((prev) => (prev.length > 0 ? [] : prev));
+      isNextPageRef.current = false;
+    } else {
+      // Next page fetch
+      isNextPageRef.current = true;
+    }
+
+    setQueryString(newQueryString);
+  }, []);
+
+  // Reload from the beginning (reset offset to 0)
+  const reload = useCallback(() => {
+    const params = new URLSearchParams(queryStringRef.current);
+    params.set("offset", "0");
+    const newQueryString = params.toString();
+
+    // Force update even if query string is the same
+    lastQueryStringRef.current = "";
+    isNextPageRef.current = false;
+
+    setAllData([]);
+    setReloadKey((k) => k + 1);
+    setQueryString(newQueryString);
+  }, []);
+
+  // Merge data when query succeeds
+  useEffect(() => {
+    if (!query.data) return;
+
+    const newData = query.data.data;
+    if (!newData) return;
+
+    if (isNextPageRef.current) {
+      // Append new data for next page
+      setAllData((prev) => {
+        const existingIds = new Set(prev.map((item) => item.id));
+        const uniqueNewData = newData.filter(
+          (item) => !existingIds.has(item.id)
+        );
+        if (uniqueNewData.length === 0) return prev;
+        return [...prev, ...uniqueNewData];
+      });
+      isNextPageRef.current = false;
+    } else {
+      // Replace data for fresh fetch - only update if different
+      setAllData((prev) => {
+        if (
+          prev.length === newData.length &&
+          prev.every((item, i) => item.id === newData[i]?.id)
+        ) {
+          return prev;
+        }
+        return newData;
+      });
+    }
+  }, [query.data]);
+
+  return {
+    data: allData,
+    hasMore: query.data?.hasMore ?? true,
+    isLoading: query.isLoading,
+    isReloading: query.isFetching && allData.length > 0,
+    total: query.data?.total ?? 0,
+    onQueryChange: handleQueryChange,
+    reload,
+  };
+};
+
+export default useInfinite;

package/src/hooks/useInfiniteArchivableCursor.ts

@@ -0,0 +1,143 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { UseInfiniteReturn } from "./useInfinite.js";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import type { AxiosInstance } from "axios";
+
+interface CursorPageResponse<T> {
+  data: T[];
+  hasMore: boolean;
+  limit: number;
+  nextCursor: string | null;
+}
+
+interface UseInfiniteArchivableCursorOptions {
+  axiosInstance: AxiosInstance;
+  /** API endpoint to fetch from (e.g., "/v1/projects"). */
+  endpoint: string;
+  /**
+   * Query key stem. A string keys the list under `${queryKey}-infinite`; an
+   * array keys it under `[...queryKey, "infinite"]`, for apps that invalidate
+   * by a multi-segment prefix.
+   */
+  queryKey: string | (string | null)[];
+  /** Organization ID to scope cache keys (prevents stale cross-org data). */
+  orgId?: string | null;
+  /** Initial page size (default: 10). */
+  initialLimit?: number;
+  enabled?: boolean;
+}
+
+/**
+ * Cursor-paginated list hook for archivable resources.
+ * It behaves like `useInfiniteCursor` — same `-infinite` query
+ * key and `UseInfiniteReturn` shape, so existing prefix-matched invalidations
+ * keep working — but lifts the "Archived" menu filter out of the generic
+ * `filter[...]` bag: InfiniteScroll emits it as `filter[includeArchived]`,
+ * whereas the backend reads a top-level `includeArchived` flag.
+ */
+const useInfiniteArchivableCursor = <T extends { id: number | string }>(
+  options: UseInfiniteArchivableCursorOptions
+): UseInfiniteReturn<T> => {
+  const {
+    axiosInstance,
+    endpoint,
+    queryKey,
+    orgId,
+    initialLimit = 10,
+    enabled = true,
+  } = options;
+
+  const [queryString, setQueryString] = useState(`limit=${initialLimit}`);
+  const lastQueryRef = useRef(queryString);
+
+  // An array stem nests "infinite" as its own segment so prefix invalidations
+  // like `["projects", projectId]` still match; a string keeps the legacy
+  // `${queryKey}-infinite` stem.
+  const infiniteKey = Array.isArray(queryKey)
+    ? [...queryKey, "infinite", orgId ?? null, queryString]
+    : [`${queryKey}-infinite`, orgId ?? null, queryString];
+
+  const query = useInfiniteQuery<CursorPageResponse<T>, Error>({
+    queryKey: infiniteKey,
+    enabled,
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (last) =>
+      last.hasMore && last.nextCursor ? last.nextCursor : undefined,
+    queryFn: async ({ pageParam }) => {
+      const params = new URLSearchParams(queryString);
+      // Cursor mode never uses offset — strip it if a caller leaks one in.
+      params.delete("offset");
+      // The "Archived" menu filter arrives as `filter[includeArchived]`, but the
+      // backend reads it as a top-level flag (not a filter clause). Lift it out
+      // so the default — flag absent — excludes archived rows.
+      const archived = params.get("filter[includeArchived]");
+      params.delete("filter[includeArchived]");
+      params.delete("filter[includeArchived_op]");
+      if (archived === "true") params.set("includeArchived", "true");
+      if (pageParam) params.set("cursor", pageParam as string);
+      const res = await axiosInstance.get<CursorPageResponse<T>>(
+        `${endpoint}?${params.toString()}`
+      );
+      return res.data;
+    },
+    staleTime: 0,
+    gcTime: 0,
+  });
+
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
+  const onQueryChange = useCallback((newQueryString: string) => {
+    const params = new URLSearchParams(newQueryString);
+    params.delete("offset");
+    const normalized = params.toString();
+
+    // Same filter/sort? InfiniteScroll is asking for the next page. The offset
+    // value it passes is meaningless for cursor mode — just fetch the next page.
+    if (normalized === lastQueryRef.current) {
+      const q = queryRef.current;
+      if (q.hasNextPage && !q.isFetchingNextPage) q.fetchNextPage();
+      return;
+    }
+    lastQueryRef.current = normalized;
+    setQueryString(normalized);
+  }, []);
+
+  const reload = useCallback(() => {
+    queryRef.current.refetch();
+  }, []);
+
+  const [allData, setAllData] = useState<T[]>([]);
+
+  useEffect(() => {
+    const pages = query.data?.pages ?? [];
+    const flat = pages.flatMap((p) => p.data);
+    // Dedup defensively — composite cursors on merged proxies can yield repeats.
+    const seen = new Set<string | number>();
+    const unique: T[] = [];
+    for (const item of flat) {
+      if (!seen.has(item.id)) {
+        seen.add(item.id);
+        unique.push(item);
+      }
+    }
+    setAllData(unique);
+  }, [query.data]);
+
+  const lastPage = query.data?.pages[query.data.pages.length - 1];
+  const hasMore = lastPage?.hasMore ?? query.hasNextPage ?? false;
+
+  return {
+    data: allData,
+    hasMore,
+    isLoading: query.isLoading,
+    isReloading: query.isRefetching && allData.length > 0,
+    total: 0,
+    onQueryChange,
+    reload,
+  };
+};
+
+export default useInfiniteArchivableCursor;

package/src/hooks/useInfiniteCursor.ts

@@ -0,0 +1,125 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { UseInfiniteReturn } from "./useInfinite.js";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { AxiosInstance } from "axios";
+
+interface CursorPageResponse<T> {
+  data: T[];
+  hasMore: boolean;
+  limit: number;
+  nextCursor: string | null;
+}
+
+interface UseInfiniteCursorOptions {
+  axiosInstance: AxiosInstance;
+  /** API endpoint to fetch from (e.g., "/v1/projects"). */
+  endpoint: string;
+  /** Query key for React Query caching. */
+  queryKey: string;
+  /** Organization ID to scope cache keys (prevents stale cross-org data). */
+  orgId?: string | null;
+  /** Initial page size (default: 10). */
+  initialLimit?: number;
+  enabled?: boolean;
+}
+
+/**
+ * Cursor-paginated counterpart to `useInfinite`. Returns the same
+ * `UseInfiniteReturn` shape so it's a drop-in replacement for callers that
+ * have migrated their backend list endpoint to cursor pagination
+ * (`{ data, hasMore, limit, nextCursor }`).
+ *
+ * `total` is always 0 — cursor endpoints intentionally do not expose `COUNT(*)`.
+ */
+const useInfiniteCursor = <T extends { id: number | string }>(
+  options: UseInfiniteCursorOptions
+): UseInfiniteReturn<T> => {
+  const {
+    axiosInstance,
+    endpoint,
+    queryKey,
+    orgId,
+    initialLimit = 10,
+    enabled = true,
+  } = options;
+
+  const [queryString, setQueryString] = useState(`limit=${initialLimit}`);
+  const lastQueryRef = useRef(queryString);
+
+  const query = useInfiniteQuery<CursorPageResponse<T>, Error>({
+    queryKey: [`${queryKey}-infinite`, orgId ?? null, queryString],
+    enabled,
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (last) =>
+      last.hasMore && last.nextCursor ? last.nextCursor : undefined,
+    queryFn: async ({ pageParam }) => {
+      const params = new URLSearchParams(queryString);
+      // Cursor mode never uses offset — strip it if a caller leaks one in.
+      params.delete("offset");
+      if (pageParam) params.set("cursor", pageParam as string);
+      const res = await axiosInstance.get<CursorPageResponse<T>>(
+        `${endpoint}?${params.toString()}`
+      );
+      return res.data;
+    },
+    staleTime: 0,
+    gcTime: 0,
+  });
+
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
+  const onQueryChange = useCallback((newQueryString: string) => {
+    const params = new URLSearchParams(newQueryString);
+    params.delete("offset");
+    const normalized = params.toString();
+
+    // Same filter/sort? InfiniteScroll is asking for the next page. The offset
+    // value it passes is meaningless for cursor mode — just trigger fetchNextPage.
+    if (normalized === lastQueryRef.current) {
+      const q = queryRef.current;
+      if (q.hasNextPage && !q.isFetchingNextPage) q.fetchNextPage();
+      return;
+    }
+    lastQueryRef.current = normalized;
+    setQueryString(normalized);
+  }, []);
+
+  const reload = useCallback(() => {
+    queryRef.current.refetch();
+  }, []);
+
+  const [allData, setAllData] = useState<T[]>([]);
+
+  useEffect(() => {
+    const pages = query.data?.pages ?? [];
+    const flat = pages.flatMap((p) => p.data);
+    // Dedup defensively — composite cursors on merged proxies can yield repeats.
+    const seen = new Set<string | number>();
+    const unique: T[] = [];
+    for (const item of flat) {
+      if (!seen.has(item.id)) {
+        seen.add(item.id);
+        unique.push(item);
+      }
+    }
+    setAllData(unique);
+  }, [query.data]);
+
+  const lastPage = query.data?.pages[query.data.pages.length - 1];
+  const hasMore = lastPage?.hasMore ?? query.hasNextPage ?? false;
+
+  return {
+    data: allData,
+    hasMore,
+    isLoading: query.isLoading,
+    isReloading: query.isRefetching && allData.length > 0,
+    total: 0,
+    onQueryChange,
+    reload,
+  };
+};
+
+export default useInfiniteCursor;

package/src/hooks/useListKeyboard.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { Dispatch, KeyboardEvent, SetStateAction, useCallback } from "react";
+
+interface UseListKeyboardOptions {
+  isOpen: boolean;
+  length: number;
+  highlightedIndex: number;
+  setHighlightedIndex: Dispatch<SetStateAction<number>>;
+  onSelect: (index: number) => void;
+  onClose: () => void;
+  /** If true, Tab selects highlighted (or first) option. */
+  selectOnTab?: boolean;
+}
+
+/**
+ * Returns a keydown handler that drives arrow-key list navigation,
+ * Enter to select, Escape to close, and optional Tab-to-select.
+ * Shared by Typeahead and SearchList.
+ */
+const useListKeyboard = ({
+  isOpen,
+  length,
+  highlightedIndex,
+  setHighlightedIndex,
+  onSelect,
+  onClose,
+  selectOnTab = false,
+}: UseListKeyboardOptions) =>
+  useCallback(
+    (e: KeyboardEvent<HTMLElement>) => {
+      if (!isOpen) return;
+      switch (e.key) {
+        case "ArrowDown":
+          e.preventDefault();
+          setHighlightedIndex((prev) => Math.min(prev + 1, length - 1));
+          break;
+        case "ArrowUp":
+          e.preventDefault();
+          setHighlightedIndex((prev) => Math.max(0, prev - 1));
+          break;
+        case "Enter":
+          e.preventDefault();
+          if (highlightedIndex > -1) onSelect(highlightedIndex);
+          break;
+        case "Tab":
+          if (selectOnTab && length > 0) {
+            onSelect(highlightedIndex > -1 ? highlightedIndex : 0);
+          }
+          break;
+        case "Escape":
+          onClose();
+          setHighlightedIndex(-1);
+          break;
+      }
+    },
+    [
+      isOpen,
+      length,
+      highlightedIndex,
+      setHighlightedIndex,
+      onSelect,
+      onClose,
+      selectOnTab,
+    ]
+  );
+
+export default useListKeyboard;

package/src/hooks/useLocalStorage.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+
+const LOCAL_STORAGE_CHANGE_EVENT = "localStorageChange";
+
+interface LocalStorageChangeDetail<T> {
+  key: string;
+  value: T | null;
+}
+
+/**
+ * Hook to track and sync localStorage changes across the app and tabs.
+ * Dispatches custom events so all instances stay in sync within the same tab,
+ * and listens to storage events for cross-tab synchronization.
+ */
+function useLocalStorage<T>(
+  key: string,
+  initialValue: T | null = null
+): [T | null, (value: T | null) => void, () => void] {
+  const [storedValue, setStoredValue] = useState<T | null>(() => {
+    const item = localStorage.getItem(key);
+    if (!item) return initialValue;
+    try {
+      return JSON.parse(item) as T;
+    } catch {
+      return initialValue;
+    }
+  });
+
+  const setValue = useCallback(
+    (value: T | null) => {
+      setStoredValue(value);
+      if (value === null) {
+        localStorage.removeItem(key);
+      } else {
+        localStorage.setItem(key, JSON.stringify(value));
+      }
+      // Dispatch custom event for same-tab listeners
+      window.dispatchEvent(
+        new CustomEvent<LocalStorageChangeDetail<T>>(
+          LOCAL_STORAGE_CHANGE_EVENT,
+          { detail: { key, value } }
+        )
+      );
+    },
+    [key]
+  );
+
+  const removeValue = useCallback(() => {
+    setValue(null);
+  }, [setValue]);
+
+  useEffect(() => {
+    // Handle changes from other instances of this hook within the same tab
+    const handleCustomChange = (e: Event) => {
+      const event = e as CustomEvent<LocalStorageChangeDetail<T>>;
+      if (event.detail.key === key) {
+        setStoredValue(event.detail.value);
+      }
+    };
+
+    // Handle changes from other tabs/windows (storage event fires cross-tab for localStorage)
+    const handleStorageChange = (e: StorageEvent) => {
+      if (e.storageArea === localStorage && e.key === key) {
+        if (e.newValue === null) setStoredValue(null);
+        else {
+          try {
+            setStoredValue(JSON.parse(e.newValue) as T);
+          } catch {
+            setStoredValue(null);
+          }
+        }
+      }
+    };
+
+    window.addEventListener(LOCAL_STORAGE_CHANGE_EVENT, handleCustomChange);
+    window.addEventListener("storage", handleStorageChange);
+
+    return () => {
+      window.removeEventListener(
+        LOCAL_STORAGE_CHANGE_EVENT,
+        handleCustomChange
+      );
+      window.removeEventListener("storage", handleStorageChange);
+    };
+  }, [key]);
+
+  return [storedValue, setValue, removeValue];
+}
+
+export default useLocalStorage;

package/src/hooks/useOutsideClick.ts

@@ -0,0 +1,27 @@
+"use client";
+
+import { RefObject, useEffect } from "react";
+
+/**
+ * Calls `onOutside` when a mousedown event lands outside every passed-in ref.
+ * Pass the container ref AND any portal/floating ref so clicks inside the
+ * floating layer aren't treated as outside clicks.
+ */
+const useOutsideClick = (
+  refs: RefObject<HTMLElement | null>[],
+  onOutside: () => void,
+  enabled = true
+) => {
+  useEffect(() => {
+    if (!enabled) return;
+    const handler = (event: MouseEvent) => {
+      const target = event.target as Node;
+      const inside = refs.some((r) => r.current && r.current.contains(target));
+      if (!inside) onOutside();
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [refs, onOutside, enabled]);
+};
+
+export default useOutsideClick;

package/src/hooks/useScrollIntoView.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import { RefObject, useEffect } from "react";
+
+/**
+ * Scrolls the element at `refs.current[index]` into view whenever `index`
+ * changes while `enabled` is true. Used for keyboard navigation in list-style
+ * dropdowns.
+ */
+const useScrollIntoView = (
+  refs: RefObject<(HTMLElement | null)[]>,
+  index: number,
+  enabled = true,
+  options: ScrollIntoViewOptions = { block: "nearest" }
+) => {
+  useEffect(() => {
+    if (!enabled || index < 0) return;
+    const el = refs.current?.[index];
+    if (!el) return;
+    el.scrollIntoView(options);
+  }, [index, enabled]);
+};
+
+export default useScrollIntoView;

package/src/index.ts

@@ -0,0 +1,13 @@
+// Re-export all components
+export * from "./components/index.js";
+
+// Re-export all hooks
+export * from "./hooks/index.js";
+
+// Export shared types
+export type {
+  Variant,
+  Size,
+  PropsWithVariant,
+  PropsWithSize,
+} from "./components/types.js";