@kosmeo-ui/react 0.1.1 → 1.0.0

package/src/components/overlays/confirmationModal/index.tsx

@@ -1,7 +1,10 @@
 "use client";
 
 import Button from "../../buttons/button/index.js";
+import Input from "../../inputs/input/index.js";
 import Modal from "../modal/index.js";
+import { useState } from "react";
+import "./styles.css";
 
 export interface ConfirmationModalProps {
   show: boolean;
@@ -12,14 +15,34 @@ export interface ConfirmationModalProps {
   confirmButtonText: string;
   cancelButtonText?: string;
   isLoading?: boolean;
+  /** **_Optional_** text the user must type, exactly, before the confirm button enables (e.g. the name of what's being deleted) */
+  confirmationText?: string;
+  /** **_Optional_** whether Escape and a click outside close the modal. Defaults to `true` */
+  dismissible?: boolean;
 }
 
 const ConfirmationModal = (props: ConfirmationModalProps) => {
+  const [typed, setTyped] = useState("");
+  const [wasShown, setWasShown] = useState(props.show);
+
+  // Clear the typed text each time the modal opens, so a match from a
+  // previous confirmation never carries over.
+  if (props.show !== wasShown) {
+    setWasShown(props.show);
+    if (props.show) setTyped("");
+  }
+
+  const confirmed =
+    props.confirmationText === undefined || typed === props.confirmationText;
+  const canConfirm = confirmed && !props.isLoading;
+
   return (
     <Modal
       show={props.show}
       title={props.title}
       onClose={props.handleHide}
+      // Cancel is disabled while loading; Escape and the backdrop follow suit.
+      dismissible={props.dismissible !== false && !props.isLoading}
       footerButtons={[
         <Button
           key="cancel"
@@ -34,13 +57,26 @@ const ConfirmationModal = (props: ConfirmationModalProps) => {
           variant="danger"
           onClick={props.handleConfirm}
           isLoading={props.isLoading}
-          disabled={props.isLoading}
+          disabled={!canConfirm}
         >
           {props.confirmButtonText}
         </Button>,
       ]}
     >
       {props.body}
+      {props.confirmationText !== undefined && (
+        <div className="k-confirmation-modal-check">
+          <Input
+            label={`Type "${props.confirmationText}" to confirm`}
+            value={typed}
+            onChange={(e) => setTyped(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && canConfirm) props.handleConfirm();
+            }}
+            autoComplete="off"
+          />
+        </div>
+      )}
     </Modal>
   );
 };

package/src/components/overlays/confirmationModal/styles.css

@@ -0,0 +1,3 @@
+.k-confirmation-modal-check {
+  margin-top: 1rem;
+}

package/src/components/overlays/modal/index.tsx

@@ -23,13 +23,16 @@ interface ModalProps extends PropsWithChildren {
    * editors) that would feel cramped at `lg`.
    */
   size?: ModalSize;
+  /** **_Optional_** whether Escape and a click on the backdrop close the modal. When `false`, only the modal's own buttons can close it. Defaults to `true` */
+  dismissible?: boolean;
 }
 
 const Modal = (props: ModalProps) => {
-  const { size = "md" } = props;
+  const { size = "md", dismissible = true } = props;
   const [shouldRender, setShouldRender] = useState(props.show);
   const [isAnimating, setIsAnimating] = useState(false);
   const contentRef = useRef<HTMLDivElement>(null);
+  const pressStartedOnOverlay = useRef(false);
 
   useEffect(() => {
     if (props.show) {
@@ -46,13 +49,13 @@ const Modal = (props: ModalProps) => {
   }, [props.show]);
 
   useEffect(() => {
-    if (!props.show) return;
+    if (!props.show || !dismissible) return;
     const handler = (e: KeyboardEvent) => {
       if (e.key === "Escape") props.onClose();
     };
     document.addEventListener("keydown", handler);
     return () => document.removeEventListener("keydown", handler);
-  }, [props.show, props.onClose]);
+  }, [props.show, props.onClose, dismissible]);
 
   useFocusTrap(contentRef, !!props.show && !!shouldRender);
 
@@ -60,7 +63,23 @@ const Modal = (props: ModalProps) => {
 
   return (
     <Portal>
-      <div className={`k-modal-overlay ${isAnimating ? "closing" : ""}`}>
+      {/* Close only when the press starts and ends on the backdrop, so a text
+          selection dragged out of the dialog doesn't close it. */}
+      <div
+        className={`k-modal-overlay ${isAnimating ? "closing" : ""}`}
+        onMouseDown={(e) => {
+          pressStartedOnOverlay.current = e.target === e.currentTarget;
+        }}
+        onClick={(e) => {
+          if (
+            dismissible &&
+            pressStartedOnOverlay.current &&
+            e.target === e.currentTarget
+          ) {
+            props.onClose();
+          }
+        }}
+      >
         <div
           ref={contentRef}
           className={`k-modal-content ${isAnimating ? "closing" : ""} ${size}`}

package/src/components/overlays/modal/styles.css

@@ -1,4 +1,4 @@
-@keyframes fadeIn {
+@keyframes k-fade-in {
   from {
     opacity: 0;
   }
@@ -7,7 +7,7 @@
   }
 }
 
-@keyframes fadeOut {
+@keyframes k-fade-out {
   from {
     opacity: 1;
   }
@@ -16,7 +16,7 @@
   }
 }
 
-@keyframes scaleIn {
+@keyframes k-scale-in {
   from {
     transform: scale(0.95);
   }
@@ -25,7 +25,7 @@
   }
 }
 
-@keyframes scaleOut {
+@keyframes k-scale-out {
   from {
     transform: scale(1);
   }
@@ -37,7 +37,7 @@
 .k-modal-overlay {
   position: fixed;
   inset: 0;
-  background-color: var(--background-color-overlay);
+  background-color: var(--k-background-color-overlay);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -45,16 +45,16 @@
   padding: 1rem;
   opacity: 1;
   pointer-events: auto;
-  animation: fadeIn 0.2s ease-out forwards;
+  animation: k-fade-in 0.2s ease-out forwards;
 }
 
 .k-modal-content {
-  background-color: var(--background-color-light);
+  background-color: var(--k-background-color-light);
   border-radius: 0.5rem;
   padding: 1rem;
   box-shadow:
-    0 1.25rem 1.5625rem -0.3125rem var(--shadow-color),
-    0 0.5rem 0.625rem -0.375rem var(--shadow-color);
+    0 1.25rem 1.5625rem -0.3125rem var(--k-shadow-color),
+    0 0.5rem 0.625rem -0.375rem var(--k-shadow-color);
   max-width: 40rem;
   width: 100%;
   display: flex;
@@ -63,7 +63,7 @@
   opacity: 1;
   transform: scale(1);
   pointer-events: auto;
-  animation: scaleIn 0.2s ease-out forwards;
+  animation: k-scale-in 0.2s ease-out forwards;
   max-height: 80vh;
   overflow: hidden;
 }
@@ -88,21 +88,21 @@
 }
 
 .k-modal-overlay.closing {
-  animation: fadeOut 0.2s ease-in forwards;
+  animation: k-fade-out 0.2s ease-in forwards;
   pointer-events: none;
 }
 
 .k-modal-content.closing {
-  animation: scaleOut 0.2s ease-in forwards;
+  animation: k-scale-out 0.2s ease-in forwards;
   pointer-events: none;
 }
 
 .k-modal-header {
   padding-bottom: 0.5rem;
-  border-bottom: 0.0625rem solid var(--border-color);
-  font-size: var(--text-size-xl);
+  border-bottom: 0.0625rem solid var(--k-border-color);
+  font-size: var(--k-text-size-xl);
   font-weight: 700;
-  color: var(--text-color);
+  color: var(--k-text-color);
 }
 
 .k-modal-body {
@@ -110,22 +110,22 @@
   flex-direction: column;
   padding-top: 0.5rem;
   padding-bottom: 0.5rem;
-  color: var(--text-color-secondary);
+  color: var(--k-text-color-secondary);
   overflow-y: auto;
   min-height: 0;
   flex: 1;
 }
 
 .k-modal-message {
-  font-size: var(--text-size-lg);
+  font-size: var(--k-text-size-lg);
   font-weight: 600;
-  color: var(--text-color);
+  color: var(--k-text-color);
   margin-bottom: 1rem;
 }
 
 .k-modal-footer {
   padding-top: 0.5rem;
-  border-top: 0.0625rem solid var(--border-color);
+  border-top: 0.0625rem solid var(--k-border-color);
   display: flex;
   justify-content: end;
   gap: 0.5rem;

package/src/hooks/index.ts

@@ -4,6 +4,10 @@ export {
   type UseInfiniteReturn,
 } from "./useInfinite.js";
 export { default as useInfiniteCursor } from "./useInfiniteCursor.js";
+export {
+  default as usePaginated,
+  type UsePaginatedReturn,
+} from "./usePaginated.js";
 export { default as useScrollIntoView } from "./useScrollIntoView.js";
 export { default as useDebouncedValue } from "./useDebouncedValue.js";
 export { default as useOutsideClick } from "./useOutsideClick.js";

package/src/hooks/useInfinite.ts

@@ -18,7 +18,7 @@ interface UseInfiniteOptions {
   queryKey: string;
   /** Organization ID to scope cache keys (prevents stale cross-org data) */
   orgId?: string | null;
-  /** Initial limit (default: 10) */
+  /** Initial limit (default: 25, InfiniteScroll's default page size) */
   initialLimit?: number;
   /** Whether or not the query should be enabled */
   enabled?: boolean;
@@ -29,6 +29,8 @@ export interface UseInfiniteReturn<T> {
   hasMore: boolean;
   isLoading: boolean;
   isReloading: boolean;
+  /** The failed request's error, or null; cleared once a load succeeds. */
+  error: Error | null;
   total: number;
   onQueryChange: (queryString: string) => void;
   reload: () => void;
@@ -42,7 +44,7 @@ const useInfinite = <T extends { id: number | string }>(
     endpoint,
     queryKey,
     orgId,
-    initialLimit = 10,
+    initialLimit = 25,
   } = options;
 
   const [queryString, setQueryString] = useState(
@@ -139,9 +141,11 @@ const useInfinite = <T extends { id: number | string }>(
 
   return {
     data: allData,
-    hasMore: query.data?.hasMore ?? true,
+    // After a failure, stop offering pages: reload() retries.
+    hasMore: query.isError ? false : (query.data?.hasMore ?? true),
     isLoading: query.isLoading,
     isReloading: query.isFetching && allData.length > 0,
+    error: query.error,
     total: query.data?.total ?? 0,
     onQueryChange: handleQueryChange,
     reload,

package/src/hooks/useInfiniteArchivableCursor.ts

@@ -24,7 +24,7 @@ interface UseInfiniteArchivableCursorOptions {
   queryKey: string | (string | null)[];
   /** Organization ID to scope cache keys (prevents stale cross-org data). */
   orgId?: string | null;
-  /** Initial page size (default: 10). */
+  /** Initial page size (default: 25, InfiniteScroll's default). */
   initialLimit?: number;
   enabled?: boolean;
 }
@@ -45,7 +45,7 @@ const useInfiniteArchivableCursor = <T extends { id: number | string }>(
     endpoint,
     queryKey,
     orgId,
-    initialLimit = 10,
+    initialLimit = 25,
     enabled = true,
   } = options;
 
@@ -98,7 +98,10 @@ const useInfiniteArchivableCursor = <T extends { id: number | string }>(
     // 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();
+      // cancelRefetch: false joins a request already in flight. The default
+      // cancels and resends it, and isFetchingNextPage can't stop that: it's
+      // read from a render, so two calls in one tick both see it false.
+      if (q.hasNextPage) q.fetchNextPage({ cancelRefetch: false });
       return;
     }
     lastQueryRef.current = normalized;
@@ -127,13 +130,17 @@ const useInfiniteArchivableCursor = <T extends { id: number | string }>(
   }, [query.data]);
 
   const lastPage = query.data?.pages[query.data.pages.length - 1];
-  const hasMore = lastPage?.hasMore ?? query.hasNextPage ?? false;
+  // After a failure, stop offering pages: reload() retries.
+  const hasMore = query.isError
+    ? false
+    : (lastPage?.hasMore ?? query.hasNextPage ?? false);
 
   return {
     data: allData,
     hasMore,
     isLoading: query.isLoading,
     isReloading: query.isRefetching && allData.length > 0,
+    error: query.error,
     total: 0,
     onQueryChange,
     reload,

package/src/hooks/useInfiniteCursor.ts

@@ -20,7 +20,7 @@ interface UseInfiniteCursorOptions {
   queryKey: string;
   /** Organization ID to scope cache keys (prevents stale cross-org data). */
   orgId?: string | null;
-  /** Initial page size (default: 10). */
+  /** Initial page size (default: 25, InfiniteScroll's default). */
   initialLimit?: number;
   enabled?: boolean;
 }
@@ -41,7 +41,7 @@ const useInfiniteCursor = <T extends { id: number | string }>(
     endpoint,
     queryKey,
     orgId,
-    initialLimit = 10,
+    initialLimit = 25,
     enabled = true,
   } = options;
 
@@ -80,7 +80,10 @@ const useInfiniteCursor = <T extends { id: number | string }>(
     // 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();
+      // cancelRefetch: false joins a request already in flight. The default
+      // cancels and resends it, and isFetchingNextPage can't stop that: it's
+      // read from a render, so two calls in one tick both see it false.
+      if (q.hasNextPage) q.fetchNextPage({ cancelRefetch: false });
       return;
     }
     lastQueryRef.current = normalized;
@@ -109,13 +112,17 @@ const useInfiniteCursor = <T extends { id: number | string }>(
   }, [query.data]);
 
   const lastPage = query.data?.pages[query.data.pages.length - 1];
-  const hasMore = lastPage?.hasMore ?? query.hasNextPage ?? false;
+  // After a failure, stop offering pages: reload() retries.
+  const hasMore = query.isError
+    ? false
+    : (lastPage?.hasMore ?? query.hasNextPage ?? false);
 
   return {
     data: allData,
     hasMore,
     isLoading: query.isLoading,
     isReloading: query.isRefetching && allData.length > 0,
+    error: query.error,
     total: 0,
     onQueryChange,
     reload,

package/src/hooks/usePaginated.ts

@@ -0,0 +1,123 @@
+"use client";
+
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useState } from "react";
+import { AxiosInstance } from "axios";
+
+interface OffsetPageResponse<T> {
+  data: T[];
+  total: number;
+}
+
+type QueryParams = Record<string, string | number | boolean | undefined>;
+
+interface UsePaginatedOptions {
+  axiosInstance: AxiosInstance;
+  /** API endpoint to fetch from (e.g., "/v1/projects"). It takes `limit` and `offset` and returns `{ data, total }`. */
+  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). */
+  initialPageSize?: number;
+  /** Extra query params such as filters and sort. Changing them returns to page 1. */
+  params?: QueryParams;
+  enabled?: boolean;
+}
+
+export interface UsePaginatedReturn<T> {
+  /** The current page's rows. */
+  data: T[];
+  /** Total matching rows across all pages. */
+  total: number;
+  /** Current page, starting at 1. */
+  page: number;
+  pageSize: number;
+  pageCount: number;
+  setPage: (page: number) => void;
+  /** Changes the page size and returns to page 1. */
+  setPageSize: (pageSize: number) => void;
+  /** True until the first page arrives. */
+  isLoading: boolean;
+  /** True whenever a page is loading, including after the first. */
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/**
+ * One page at a time from an offset endpoint (`limit` + `offset` in,
+ * `{ data, total }` out), for `Pagination`. The previous page stays on screen
+ * while the next one loads. Use `useInfiniteCursor` for `InfiniteScroll`.
+ */
+const usePaginated = <T>(
+  options: UsePaginatedOptions
+): UsePaginatedReturn<T> => {
+  const {
+    axiosInstance,
+    endpoint,
+    queryKey,
+    orgId,
+    initialPageSize = 10,
+    params,
+    enabled = true,
+  } = options;
+
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSizeState] = useState(initialPageSize);
+
+  // New filters or sort make the old page number meaningless.
+  const paramsKey = JSON.stringify(params ?? {});
+  const [prevParamsKey, setPrevParamsKey] = useState(paramsKey);
+  if (paramsKey !== prevParamsKey) {
+    setPrevParamsKey(paramsKey);
+    setPage(1);
+  }
+
+  const query = useQuery<OffsetPageResponse<T>, Error>({
+    queryKey: [`${queryKey}-paged`, orgId ?? null, paramsKey, page, pageSize],
+    enabled,
+    placeholderData: keepPreviousData,
+    queryFn: async () => {
+      const res = await axiosInstance.get<OffsetPageResponse<T>>(endpoint, {
+        params: { ...params, limit: pageSize, offset: (page - 1) * pageSize },
+      });
+      return res.data;
+    },
+  });
+
+  const total = query.data?.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+
+  // Rows deleted from the last page can leave it empty; step back.
+  useEffect(() => {
+    if (query.data && !query.isPlaceholderData && page > pageCount) {
+      setPage(pageCount);
+    }
+  }, [query.data, query.isPlaceholderData, page, pageCount]);
+
+  const setPageSize = useCallback((size: number) => {
+    setPageSizeState(size);
+    setPage(1);
+  }, []);
+
+  const { refetch } = query;
+  const refetchPage = useCallback(() => void refetch(), [refetch]);
+
+  return {
+    data: query.data?.data ?? [],
+    total,
+    page,
+    pageSize,
+    pageCount,
+    setPage,
+    setPageSize,
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+    error: query.error,
+    refetch: refetchPage,
+  };
+};
+
+export default usePaginated;