@tidecloak/ui-framework 0.0.1

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useAutoRefresh } from "./useAutoRefresh";
+export { useSelection } from "./useSelection";
+export { usePagination, type PageSizeMode, type UsePaginationOptions } from "./usePagination";

package/src/hooks/useAutoRefresh.ts

@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { AutoRefreshOptions, AutoRefreshReturn } from "../types";
+
+/**
+ * Hook for auto-refreshing data at a configurable interval
+ *
+ * @example
+ * ```tsx
+ * const { secondsRemaining, refreshNow, lastError, failureCount } = useAutoRefresh({
+ *   intervalSeconds: 15,
+ *   refresh: fetchData,
+ *   isBlocked: isLoading,
+ *   onError: (err) => console.error('Refresh failed:', err),
+ *   maxRetries: 3,
+ * });
+ * ```
+ */
+export function useAutoRefresh(options: AutoRefreshOptions): AutoRefreshReturn {
+  const {
+    intervalSeconds,
+    enabled = true,
+    refresh,
+    isBlocked = false,
+    onError,
+    maxRetries,
+  } = options;
+
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  const isBlockedRef = useRef(isBlocked);
+  useEffect(() => {
+    isBlockedRef.current = isBlocked;
+  }, [isBlocked]);
+
+  const [nextRefreshAt, setNextRefreshAt] = useState(() => Date.now() + intervalSeconds * 1000);
+  const [now, setNow] = useState(() => Date.now());
+  const [lastError, setLastError] = useState<Error | null>(null);
+  const [failureCount, setFailureCount] = useState(0);
+  const [isStopped, setIsStopped] = useState(false);
+
+  const secondsRemaining = useMemo(() => {
+    if (!enabled || isStopped) return null;
+    return Math.max(0, Math.ceil((nextRefreshAt - now) / 1000));
+  }, [enabled, isStopped, nextRefreshAt, now]);
+
+  // Update current time every 250ms
+  useEffect(() => {
+    if (!enabled || isStopped) return;
+    const id = window.setInterval(() => setNow(Date.now()), 250);
+    return () => window.clearInterval(id);
+  }, [enabled, isStopped]);
+
+  const runRefresh = useCallback(async () => {
+    if (!enabled || isStopped) return;
+    if (isBlockedRef.current) return;
+
+    try {
+      await refreshRef.current();
+      // Success - reset error state
+      setLastError(null);
+      setFailureCount(0);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setLastError(error);
+      setFailureCount(prev => {
+        const newCount = prev + 1;
+        // Stop if max retries exceeded
+        if (maxRetries !== undefined && newCount >= maxRetries) {
+          setIsStopped(true);
+        }
+        return newCount;
+      });
+      // Call error callback
+      onErrorRef.current?.(error);
+    }
+
+    setNextRefreshAt(Date.now() + intervalSeconds * 1000);
+  }, [enabled, isStopped, intervalSeconds, maxRetries]);
+
+  // Trigger refresh when time is up
+  useEffect(() => {
+    if (!enabled || isStopped) return;
+    if (isBlockedRef.current) return;
+    if (now < nextRefreshAt) return;
+    void runRefresh();
+  }, [enabled, isStopped, now, nextRefreshAt, runRefresh]);
+
+  const refreshNow = useCallback(async () => {
+    // Allow manual refresh even if stopped
+    if (!enabled) return;
+    if (isBlockedRef.current) return;
+
+    try {
+      await refreshRef.current();
+      setLastError(null);
+      setFailureCount(0);
+      setIsStopped(false); // Resume auto-refresh on successful manual refresh
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setLastError(error);
+      onErrorRef.current?.(error);
+    }
+
+    setNextRefreshAt(Date.now() + intervalSeconds * 1000);
+  }, [enabled, intervalSeconds]);
+
+  const resetTimer = useCallback(() => {
+    setNextRefreshAt(Date.now() + intervalSeconds * 1000);
+    setIsStopped(false); // Also resume auto-refresh
+    setFailureCount(0);
+    setLastError(null);
+  }, [intervalSeconds]);
+
+  return { secondsRemaining, refreshNow, resetTimer, lastError, failureCount, isStopped };
+}

package/src/hooks/usePagination.ts

@@ -0,0 +1,152 @@
+import { useCallback, useMemo, useState, useEffect, useRef } from "react";
+import type { PaginationReturn } from "../types";
+import { computeRowsForViewportHeight } from "../utils";
+
+export type PageSizeMode = "auto" | "manual";
+
+export interface UsePaginationOptions {
+  /** Initial page (0-indexed) */
+  initialPage?: number;
+  /** Initial page size */
+  initialPageSize?: number;
+  /** Total number of items (for calculating total pages) */
+  totalItems?: number;
+  /** Whether to enable auto page size based on viewport */
+  autoPageSize?: boolean;
+  /** Ref to viewport element for auto sizing */
+  viewportRef?: React.RefObject<HTMLDivElement>;
+  /** Callback when page changes */
+  onPageChange?: (page: number) => void;
+  /** Callback when page size changes */
+  onPageSizeChange?: (pageSize: number) => void;
+}
+
+/**
+ * Hook for managing pagination state
+ *
+ * @example
+ * ```tsx
+ * const pagination = usePagination({
+ *   initialPageSize: 25,
+ *   totalItems: data.length,
+ * });
+ *
+ * // Use in query
+ * const { data } = useQuery({
+ *   queryKey: ['items', pagination.page, pagination.pageSize],
+ *   queryFn: () => fetchItems(pagination.pageSize, pagination.page * pagination.pageSize),
+ * });
+ * ```
+ */
+export function usePagination(options: UsePaginationOptions = {}): PaginationReturn & {
+  pageSizeMode: PageSizeMode;
+  setPageSizeMode: (mode: PageSizeMode) => void;
+  pageSizeSelectValue: string;
+  onPageSizeSelect: (value: string) => void;
+} {
+  const {
+    initialPage = 0,
+    initialPageSize = 25,
+    totalItems = 0,
+    autoPageSize = false,
+    viewportRef,
+    onPageChange,
+    onPageSizeChange,
+  } = options;
+
+  const [page, setPageState] = useState(initialPage);
+  const [pageSize, setPageSizeState] = useState(initialPageSize);
+  const [pageSizeMode, setPageSizeMode] = useState<PageSizeMode>(
+    autoPageSize ? "auto" : "manual"
+  );
+
+  // Handle auto page size with ResizeObserver
+  useEffect(() => {
+    if (pageSizeMode !== "auto" || !viewportRef?.current) return;
+
+    const el = viewportRef.current;
+    const ro = new ResizeObserver((entries) => {
+      const h = entries[0]?.contentRect.height ?? 0;
+      if (!h) return;
+      const newSize = computeRowsForViewportHeight(h);
+      setPageSizeState(newSize);
+      onPageSizeChange?.(newSize);
+    });
+
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [pageSizeMode, viewportRef, onPageSizeChange]);
+
+  const setPage = useCallback(
+    (newPage: number) => {
+      setPageState(newPage);
+      onPageChange?.(newPage);
+    },
+    [onPageChange]
+  );
+
+  const setPageSize = useCallback(
+    (newSize: number) => {
+      setPageSizeState(newSize);
+      onPageSizeChange?.(newSize);
+      // Reset to first page when page size changes
+      setPageState(0);
+      onPageChange?.(0);
+    },
+    [onPageChange, onPageSizeChange]
+  );
+
+  const totalPages = useMemo(
+    () => Math.max(1, Math.ceil(totalItems / pageSize)),
+    [totalItems, pageSize]
+  );
+
+  const nextPage = useCallback(() => {
+    const newPage = Math.min(page + 1, totalPages - 1);
+    setPage(newPage);
+  }, [page, totalPages, setPage]);
+
+  const prevPage = useCallback(() => {
+    const newPage = Math.max(0, page - 1);
+    setPage(newPage);
+  }, [page, setPage]);
+
+  const canNextPage = page < totalPages - 1;
+  const canPrevPage = page > 0;
+
+  const startIndex = page * pageSize;
+  const endIndex = Math.min(startIndex + pageSize, totalItems);
+
+  // For select component
+  const pageSizeSelectValue = pageSizeMode === "auto" ? "auto" : String(pageSize);
+
+  const onPageSizeSelect = useCallback(
+    (value: string) => {
+      if (value === "auto") {
+        setPageSizeMode("auto");
+      } else {
+        setPageSizeMode("manual");
+        setPageSize(parseInt(value, 10));
+      }
+    },
+    [setPageSize]
+  );
+
+  return {
+    page,
+    pageSize,
+    setPage,
+    setPageSize,
+    nextPage,
+    prevPage,
+    canNextPage,
+    canPrevPage,
+    totalPages,
+    startIndex,
+    endIndex,
+    pageSizeMode,
+    setPageSizeMode,
+    pageSizeSelectValue,
+    onPageSizeSelect,
+  };
+}

package/src/hooks/useSelection.ts

@@ -0,0 +1,81 @@
+import { useCallback, useState } from "react";
+import type { BaseDataItem, SelectionReturn } from "../types";
+
+/**
+ * Hook for managing multi-select state in tables
+ *
+ * @example
+ * ```tsx
+ * const selection = useSelection<MyItem>();
+ *
+ * // Toggle single item
+ * selection.toggle(item.id);
+ *
+ * // Check if selected
+ * const isSelected = selection.isSelected(item.id);
+ *
+ * // Toggle all
+ * selection.toggleAll(items);
+ * ```
+ */
+export function useSelection<T extends BaseDataItem>(): SelectionReturn<T> {
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+
+  const isSelected = useCallback(
+    (id: string) => selectedIds.includes(id),
+    [selectedIds]
+  );
+
+  const toggle = useCallback((id: string) => {
+    setSelectedIds((prev) =>
+      prev.includes(id) ? prev.filter((p) => p !== id) : [...prev, id]
+    );
+  }, []);
+
+  const selectAll = useCallback((items: T[]) => {
+    setSelectedIds(items.map((item) => item.id));
+  }, []);
+
+  const clearAll = useCallback(() => {
+    setSelectedIds([]);
+  }, []);
+
+  const toggleAll = useCallback(
+    (items: T[]) => {
+      if (selectedIds.length === items.length) {
+        setSelectedIds([]);
+      } else {
+        setSelectedIds(items.map((item) => item.id));
+      }
+    },
+    [selectedIds.length]
+  );
+
+  const getSelected = useCallback(
+    (items: T[]) => items.filter((item) => selectedIds.includes(item.id)),
+    [selectedIds]
+  );
+
+  const allSelected = useCallback(
+    (items: T[]) => items.length > 0 && selectedIds.length === items.length,
+    [selectedIds.length]
+  );
+
+  const someSelected = useCallback(
+    (items: T[]) =>
+      selectedIds.length > 0 && selectedIds.length < items.length,
+    [selectedIds.length]
+  );
+
+  return {
+    selectedIds,
+    isSelected,
+    toggle,
+    selectAll,
+    clearAll,
+    toggleAll,
+    getSelected,
+    allSelected,
+    someSelected,
+  };
+}

package/src/index.ts

@@ -0,0 +1,256 @@
+// @tidecloak/ui-framework
+
+// Theme (colors, spacing, CSS variables)
+export {
+  colors,
+  spacing,
+  radius,
+  fontSize,
+  zIndex,
+  duration,
+  focusRing,
+  shadow,
+  themeCSS,
+  injectThemeCSS,
+} from "./theme";
+
+// Re-export react-query so users don't need to install it separately
+export {
+  QueryClient,
+  QueryClientProvider,
+  useQuery,
+  useMutation,
+  useQueryClient,
+  type QueryClientConfig,
+} from "@tanstack/react-query";
+
+// Types
+export * from "./types";
+
+// Utils
+export {
+  cn,
+  base64ToBytes,
+  bytesToBase64,
+  formatTimestamp,
+  formatLogTimestamp,
+  computeRowsForViewportHeight,
+  delay,
+  safeJsonParse,
+  truncate,
+  isDefined,
+  generateId,
+} from "./utils";
+
+// Hooks
+export {
+  useAutoRefresh,
+  useSelection,
+  usePagination,
+  type PageSizeMode,
+  type UsePaginationOptions,
+} from "./hooks";
+
+// Common Components
+export {
+  RefreshButton,
+  StatusBadge,
+  STATUS_COLORS,
+  STATUS_ICONS,
+  getStatusConfig,
+  ActionButton,
+  ActionButtonGroup,
+  ACTION_COLORS,
+  ACTION_ICONS,
+  EmptyState,
+  EmptyStateNoData,
+  EmptyStateNoResults,
+  EmptyStateNoFiles,
+  Skeleton,
+  LoadingSkeleton,
+  TableRowSkeleton,
+  type RefreshButtonProps,
+  type StatusBadgeProps,
+  type ActionButtonProps,
+  type ActionButtonGroupProps,
+  type ActionType,
+  type EmptyStateProps,
+  type SkeletonProps,
+  type LoadingSkeletonProps,
+} from "./components/common";
+
+// Data Table Components
+export {
+  DataTable,
+  PaginatedTable,
+  type DataTableProps,
+  type PaginatedTableProps,
+} from "./components/data-table";
+
+// Tabs Components
+export {
+  TabsView,
+  type TabsViewProps,
+} from "./components/tabs";
+
+// Dialog Components
+export {
+  DetailDialog,
+  ConfirmDialog,
+  CollapsibleSection,
+  CodePreview,
+  type DetailDialogProps,
+  type ConfirmDialogProps,
+  type CollapsibleSectionProps,
+} from "./components/dialogs";
+
+// Page Components - Base (headless)
+export {
+  // Approvals
+  ApprovalsPageBase,
+  type ApprovalsPageBaseProps,
+  type ApprovalTabConfig,
+  type BaseApprovalItem,
+  type AccessApprovalItem,
+  type RoleApprovalItem,
+  type PolicyApprovalItem,
+  type ApprovalDecision,
+  createUserColumn,
+  createRoleColumn,
+  createTimestampColumn,
+  createStatusColumn,
+  createProgressColumn,
+  // Logs
+  LogsPageBase,
+  type LogsPageBaseProps,
+  type LogsTabConfig,
+  type BaseLogItem,
+  type AccessLogItem,
+  type PolicyLogItem,
+  createLogTimestampColumn,
+  createActionColumn,
+  createLogProgressColumn,
+  // Templates
+  TemplatesPageBase,
+  type TemplatesPageBaseProps,
+  type PolicyTemplateItem,
+  type TemplateParameter,
+  type TemplateFormData,
+  // Users
+  UsersPageBase,
+  type UsersPageBaseProps,
+  type UserItem,
+  type UserRoleItem,
+  type UserFormData,
+  type CreateUserFormData,
+  // Roles
+  RolesPageBase,
+  type RolesPageBaseProps,
+  type RoleItem,
+  type PolicyConfig,
+  type RolePolicyTemplateItem,
+  type RoleTemplateParameter,
+} from "./components/pages";
+
+// Page Components - Pre-made (uses @tidecloak/react)
+export {
+  RolesPage,
+  UsersPage,
+  TemplatesPage,
+  LogsPage,
+  ApprovalsPage,
+  // Template API helpers
+  createLocalStorageTemplateAPI,
+  // Policy API helpers
+  createLocalStoragePolicyAPI,
+  // Policy Approvals API helpers
+  createLocalStoragePolicyApprovalsAPI,
+  // Access Metadata API helpers
+  createLocalStorageAccessMetadataAPI,
+  // Policy Logs API helpers
+  createLocalStoragePolicyLogsAPI,
+  type RolesPageProps,
+  type UsersPageProps,
+  type ChangeSetInfo,
+  type TemplatesPageProps,
+  type TemplateAPI,
+  type PolicyAPI,
+  type RolePolicy,
+  type LogsPageProps,
+  type PolicyLogsAPI,
+  type PolicyLogData,
+  type ApprovalsPageProps,
+  type PolicyApprovalsAPI,
+  type PolicyApprovalData,
+  type AccessMetadataAPI,
+  type AccessMetadataRecord,
+  type TideApprovalContext,
+  type TideApprovalResult,
+  type EnclaveApprovalTabConfig,
+} from "./components/pages/connected";
+
+// Tide Policy Workflow Helpers
+export {
+  loadTideLibs,
+  areTideLibsAvailable,
+  computeContractId,
+  createTidePolicyRequest,
+  createTidePolicyHandler,
+  rolePolicyToTideConfig,
+  DEFAULT_MODEL_IDS,
+  DEFAULT_ROLE_CONTRACT,
+  type TidePolicyConfig,
+  type TideContextMethods,
+} from "./tide";
+
+// Default UI Components (works out of the box with inline styles)
+export {
+  defaultComponents,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  Button,
+  Badge,
+  Input,
+  Label,
+  Textarea,
+  Checkbox,
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+  Skeleton as UIComponentSkeleton,
+  Switch,
+  ScrollArea,
+  Alert,
+  AlertDescription,
+  CodeEditor,
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogCancel,
+  AlertDialogAction,
+  Separator,
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from "./components/ui";