@checkstack/ui 0.0.2

package/src/hooks/usePagination.ts

@@ -0,0 +1,231 @@
+import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+
+/**
+ * Pagination parameters passed to the fetch function
+ */
+export interface PaginationParams {
+  limit: number;
+  offset: number;
+}
+
+/**
+ * Options for usePagination hook
+ */
+export interface UsePaginationOptions<TResponse, TItem, TExtraParams = object> {
+  /**
+   * Fetch function that receives pagination + extra params and returns response
+   */
+  fetchFn: (params: PaginationParams & TExtraParams) => Promise<TResponse>;
+
+  /**
+   * Extract items array from the response
+   */
+  getItems: (response: TResponse) => TItem[];
+
+  /**
+   * Extract total count from the response
+   */
+  getTotal: (response: TResponse) => number;
+
+  /**
+   * Extra parameters to pass to fetchFn (merged with pagination params)
+   * Changes to this object will trigger a refetch
+   */
+  extraParams?: TExtraParams;
+
+  /**
+   * Initial page number (1-indexed)
+   * @default 1
+   */
+  defaultPage?: number;
+
+  /**
+   * Items per page
+   * @default 10
+   */
+  defaultLimit?: number;
+
+  /**
+   * Whether to fetch on mount
+   * @default true
+   */
+  fetchOnMount?: boolean;
+}
+
+/**
+ * Pagination state returned by usePagination hook
+ */
+export interface PaginationState {
+  /** Current page (1-indexed) */
+  page: number;
+  /** Items per page */
+  limit: number;
+  /** Total number of items */
+  total: number;
+  /** Total number of pages */
+  totalPages: number;
+  /** Whether there is a next page */
+  hasNext: boolean;
+  /** Whether there is a previous page */
+  hasPrev: boolean;
+  /** Go to a specific page (1-indexed) */
+  setPage: (page: number) => void;
+  /** Change items per page (resets to page 1) */
+  setLimit: (limit: number) => void;
+  /** Go to next page */
+  nextPage: () => void;
+  /** Go to previous page */
+  prevPage: () => void;
+  /** Refresh current page */
+  refetch: () => void;
+}
+
+/**
+ * Return value of usePagination hook
+ */
+export interface UsePaginationResult<TItem> {
+  /** Current page items */
+  items: TItem[];
+  /** Loading state */
+  loading: boolean;
+  /** Error if fetch failed */
+  error: Error | undefined;
+  /** Pagination controls and state */
+  pagination: PaginationState;
+}
+
+/**
+ * Hook for managing paginated data fetching with automatic state management.
+ *
+ * @example
+ * ```tsx
+ * const { items, loading, pagination } = usePagination({
+ *   fetchFn: (p) => client.getNotifications(p),
+ *   getItems: (r) => r.notifications,
+ *   getTotal: (r) => r.total,
+ *   extraParams: { unreadOnly: true },
+ * });
+ *
+ * return (
+ *   <>
+ *     {items.map(item => <Card key={item.id} {...item} />)}
+ *     <Pagination {...pagination} />
+ *   </>
+ * );
+ * ```
+ */
+export function usePagination<TResponse, TItem, TExtraParams = object>({
+  fetchFn,
+  getItems,
+  getTotal,
+  extraParams,
+  defaultPage = 1,
+  defaultLimit = 10,
+  fetchOnMount = true,
+}: UsePaginationOptions<
+  TResponse,
+  TItem,
+  TExtraParams
+>): UsePaginationResult<TItem> {
+  const [items, setItems] = useState<TItem[]>([]);
+  const [loading, setLoading] = useState(fetchOnMount);
+  const [error, setError] = useState<Error>();
+  const [page, setPageState] = useState(defaultPage);
+  const [limit, setLimitState] = useState(defaultLimit);
+  const [total, setTotal] = useState(0);
+
+  // Use refs for callback functions to avoid re-creating fetchData when they change
+  // This is better DX - callers don't need to memoize their functions
+  const fetchFnRef = useRef(fetchFn);
+  const getItemsRef = useRef(getItems);
+  const getTotalRef = useRef(getTotal);
+  const extraParamsRef = useRef(extraParams);
+
+  // Update refs when functions change
+  fetchFnRef.current = fetchFn;
+  getItemsRef.current = getItems;
+  getTotalRef.current = getTotal;
+  extraParamsRef.current = extraParams;
+
+  // Memoize extraParams to detect changes
+  const extraParamsKey = useMemo(
+    () => JSON.stringify(extraParams ?? {}),
+    [extraParams]
+  );
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    setError(undefined);
+
+    try {
+      const offset = (page - 1) * limit;
+      const params = {
+        limit,
+        offset,
+        ...extraParamsRef.current,
+      } as PaginationParams & TExtraParams;
+
+      const response = await fetchFnRef.current(params);
+      setItems(getItemsRef.current(response));
+      setTotal(getTotalRef.current(response));
+    } catch (error_) {
+      setError(error_ instanceof Error ? error_ : new Error(String(error_)));
+      setItems([]);
+    } finally {
+      setLoading(false);
+    }
+  }, [page, limit, extraParamsKey]);
+
+  // Fetch on mount and when dependencies change
+  useEffect(() => {
+    if (fetchOnMount || page !== defaultPage || limit !== defaultLimit) {
+      void fetchData();
+    }
+  }, [fetchData, fetchOnMount, page, limit, defaultPage, defaultLimit]);
+
+  // Reset to page 1 when extraParams change
+  useEffect(() => {
+    setPageState(1);
+  }, [extraParamsKey]);
+
+  const totalPages = Math.max(1, Math.ceil(total / limit));
+  const hasNext = page < totalPages;
+  const hasPrev = page > 1;
+
+  const setPage = useCallback((newPage: number) => {
+    setPageState(Math.max(1, newPage));
+  }, []);
+
+  const setLimit = useCallback((newLimit: number) => {
+    setLimitState(newLimit);
+    setPageState(1); // Reset to first page when limit changes
+  }, []);
+
+  const nextPage = useCallback(() => {
+    if (hasNext) {
+      setPageState((p) => p + 1);
+    }
+  }, [hasNext]);
+
+  const prevPage = useCallback(() => {
+    if (hasPrev) {
+      setPageState((p) => p - 1);
+    }
+  }, [hasPrev]);
+
+  const pagination: PaginationState = {
+    page,
+    limit,
+    total,
+    totalPages,
+    hasNext,
+    hasPrev,
+    setPage,
+    setLimit,
+    nextPage,
+    prevPage,
+    refetch: fetchData,
+  };
+
+  return { items, loading, error, pagination };
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+export * from "./components/Button";
+export * from "./components/Input";
+export * from "./components/Card";
+export * from "./components/Label";
+export * from "./components/NavItem";
+export * from "./components/PermissionDenied";
+export * from "./components/PermissionGate";
+export * from "./components/SectionHeader";
+export * from "./components/StatusCard";
+export * from "./components/EmptyState";
+export * from "./components/LoadingSpinner";
+export * from "./components/DropdownMenu";
+export * from "./components/UserMenu";
+export * from "./components/EditableText";
+export * from "./components/ConfirmationModal";
+export * from "./components/HealthBadge";
+export * from "./components/Table";
+export * from "./utils";
+export * from "./components/Select";
+export * from "./components/Page";
+export * from "./components/Textarea";
+export * from "./components/Tooltip";
+export * from "./components/Toggle";
+export * from "./components/Checkbox";
+export * from "./components/Alert";
+export * from "./components/InfoBanner";
+export * from "./components/DynamicForm";
+export * from "./components/PageLayout";
+export * from "./components/PluginConfigForm";
+export * from "./components/Toast";
+export * from "./components/ToastProvider";
+export * from "./components/Dialog";
+export * from "./components/Badge";
+export * from "./components/Accordion";
+export * from "./components/Tabs";
+export * from "./components/ThemeProvider";
+export * from "./components/SubscribeButton";
+export * from "./components/Pagination";
+export * from "./components/PaginatedList";
+export * from "./hooks/usePagination";
+export * from "./components/DateTimePicker";
+export * from "./components/DateRangeFilter";
+export * from "./components/BackLink";
+export * from "./components/StatusUpdateTimeline";
+export * from "./components/DynamicIcon";
+export * from "./components/StrategyConfigCard";
+export * from "./components/Markdown";
+export * from "./components/ColorPicker";
+export * from "./components/TemplateEditor";
+export * from "./components/AnimatedCounter";
+export * from "./components/CommandPalette";
+export * from "./components/TerminalFeed";
+export * from "./components/AmbientBackground";

package/src/themes.css

@@ -0,0 +1,204 @@
+/* Base theme colors using CSS custom properties */
+@layer base {
+  :root {
+    /* Primary - Purple/Indigo brand color */
+    --primary: 262 83% 58%;
+    --primary-foreground: 0 0% 100%;
+
+    /* Secondary - Complementary color */
+    --secondary: 240 5% 96%;
+    --secondary-foreground: 240 6% 10%;
+
+    /* Accent - Highlight color */
+    --accent: 240 5% 96%;
+    --accent-foreground: 240 6% 10%;
+
+    /* Destructive - Error/danger color */
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    /* white - for text on solid destructive backgrounds */
+
+    /* Muted - Subtle backgrounds */
+    --muted: 240 5% 96%;
+    --muted-foreground: 240 4% 46%;
+
+    /* Background and foreground */
+    --background: 0 0% 100%;
+    --foreground: 240 10% 4%;
+
+    /* Card - Elevated surfaces */
+    --card: 0 0% 98%;
+    --card-foreground: 240 10% 4%;
+
+    /* Popover - Floating elements */
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 4%;
+
+    /* Border and input */
+    --border: 240 6% 90%;
+    --input: 240 6% 90%;
+    --ring: 262 83% 58%;
+
+    /* Chart colors */
+    --chart-1: 262 83% 58%;
+    --chart-2: 173 58% 39%;
+    --chart-3: 197 37% 24%;
+    --chart-4: 43 74% 66%;
+    --chart-5: 27 87% 67%;
+
+    /* Semantic colors */
+    --success: 142 71% 45%;
+    /* green-600 */
+    --success-foreground: 0 0% 100%;
+    /* white - for text on solid success backgrounds */
+
+    --warning: 38 92% 50%;
+    /* yellow-500 */
+    --warning-foreground: 0 0% 0%;
+    /* black - for text on solid warning backgrounds (yellow needs dark text) */
+
+    --info: 217 91% 60%;
+    /* blue-500 */
+    --info-foreground: 0 0% 100%;
+    /* white - for text on solid info backgrounds */
+
+    /* Radius for rounded corners */
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    /* Primary - Brighter in dark mode */
+    --primary: 263 70% 65%;
+    --primary-foreground: 0 0% 100%;
+
+    /* Secondary */
+    --secondary: 240 4% 16%;
+    --secondary-foreground: 0 0% 100%;
+
+    /* Accent */
+    --accent: 240 4% 16%;
+    --accent-foreground: 0 0% 100%;
+
+    /* Destructive */
+    --destructive: 0 63% 50%;
+    --destructive-foreground: 0 0% 100%;
+
+    /* Muted */
+    --muted: 240 4% 16%;
+    --muted-foreground: 240 5% 65%;
+
+    /* Background and foreground */
+    --background: 240 10% 4%;
+    --foreground: 0 0% 98%;
+
+    /* Card */
+    --card: 240 6% 10%;
+    --card-foreground: 0 0% 98%;
+
+    /* Popover */
+    --popover: 240 10% 4%;
+    --popover-foreground: 0 0% 98%;
+
+    /* Border and input */
+    --border: 240 4% 16%;
+    --input: 240 4% 16%;
+    --ring: 263 70% 65%;
+
+    /* Chart colors - adjusted for dark mode */
+    --chart-1: 263 70% 65%;
+    --chart-2: 173 58% 49%;
+    --chart-3: 197 37% 34%;
+    --chart-4: 43 74% 76%;
+    --chart-5: 27 87% 77%;
+
+    /* Semantic colors - dark mode */
+    --success: 142 76% 36%;
+    /* green-700 - slightly darker */
+    --success-foreground: 138 76% 97%;
+    /* green-50 */
+
+    --warning: 48 96% 53%;
+    /* yellow-400 - brighter */
+    --warning-foreground: 48 96% 89%;
+    /* yellow-200 - light/bright for dark backgrounds */
+
+    --info: 213 94% 68%;
+    /* blue-400 - brighter */
+    --info-foreground: 214 100% 97%;
+    /* blue-50 */
+  }
+}
+
+/* Apply base styles */
+@layer base {
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings: "rlig" 1, "calt" 1;
+  }
+}
+
+/* Custom animations */
+@keyframes bell-ring {
+  0% {
+    transform: rotate(0deg);
+  }
+
+  10% {
+    transform: rotate(15deg);
+  }
+
+  20% {
+    transform: rotate(-15deg);
+  }
+
+  30% {
+    transform: rotate(10deg);
+  }
+
+  40% {
+    transform: rotate(-10deg);
+  }
+
+  50% {
+    transform: rotate(5deg);
+  }
+
+  60% {
+    transform: rotate(-5deg);
+  }
+
+  70% {
+    transform: rotate(0deg);
+  }
+
+  100% {
+    transform: rotate(0deg);
+  }
+}
+
+.animate-bell-ring {
+  animation: bell-ring 0.5s ease-in-out;
+  transform-origin: top center;
+}
+
+/* Subtle tile pulse animation - gentle breathing effect */
+@keyframes tile-pulse {
+
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.4;
+  }
+}
+
+.tile-glow {
+  animation: tile-pulse 12s ease-in-out infinite;
+  animation-delay: var(--glow-delay, 0s);
+}

package/src/utils/strip-markdown.ts

@@ -0,0 +1,44 @@
+/**
+ * Strip markdown formatting to plain text.
+ *
+ * A lightweight client-side utility for displaying markdown content as plain text.
+ * This is a simplified version that handles common markdown syntax.
+ */
+export function stripMarkdown(markdown: string): string {
+  let result = markdown;
+
+  // Remove bold: **text** or __text__
+  result = result.replaceAll(/\*\*(.+?)\*\*/g, "$1");
+  result = result.replaceAll(/__(.+?)__/g, "$1");
+
+  // Remove italic: *text* or _text_ (but not if it's part of bold)
+  result = result.replaceAll(/(?<!\*)\*([^*]+)\*(?!\*)/g, "$1");
+  result = result.replaceAll(/(?<!_)_([^_]+)_(?!_)/g, "$1");
+
+  // Remove strikethrough: ~~text~~
+  result = result.replaceAll(/~~(.+?)~~/g, "$1");
+
+  // Remove links: [text](url) -> text
+  result = result.replaceAll(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+
+  // Remove inline code: `code` -> code
+  result = result.replaceAll(/`([^`]+)`/g, "$1");
+
+  // Remove code blocks (simple version)
+  result = result.replaceAll(/```[\s\S]*?```/g, "");
+
+  // Remove headers: # text -> text
+  result = result.replaceAll(/^#+\s*/gm, "");
+
+  // Remove blockquotes: > text -> text
+  result = result.replaceAll(/^>\s*/gm, "");
+
+  // Remove horizontal rules
+  result = result.replaceAll(/^---+$/gm, "");
+  result = result.replaceAll(/^\*\*\*+$/gm, "");
+
+  // Collapse multiple whitespace
+  result = result.replaceAll(/\n\s*\n/g, "\n").trim();
+
+  return result;
+}

package/src/utils.ts

@@ -0,0 +1,8 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export { stripMarkdown } from "./utils/strip-markdown";

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/frontend.json",
+  "include": [
+    "src"
+  ]
+}