@tidecloak/ui-framework 0.0.1

package/src/types/index.ts

@@ -0,0 +1,484 @@
+// ============================================================================
+// CORE TYPES - Generic data structures for the UI framework
+// ============================================================================
+
+import { ReactNode } from "react";
+
+// ============================================================================
+// BASE DATA TYPES
+// ============================================================================
+
+/**
+ * Base interface for all data items - requires an id
+ */
+export interface BaseDataItem {
+  id: string;
+}
+
+/**
+ * Generic change set request structure for approval workflows
+ */
+export interface ChangeSetRequest {
+  changeSetId: string;
+  changeSetType: string;
+  actionType: string;
+}
+
+/**
+ * Base interface for items that can be approved
+ */
+export interface ApprovableItem extends BaseDataItem {
+  status: string;
+  retrievalInfo?: ChangeSetRequest;
+}
+
+// ============================================================================
+// TABLE TYPES
+// ============================================================================
+
+/**
+ * Column definition for data tables
+ * Note: T can be any type with the properties needed for rendering
+ */
+export interface ColumnDef<T = any> {
+  /** Unique key for the column */
+  key: string;
+  /** Display header */
+  header: string | ReactNode;
+  /** Cell renderer */
+  cell: (item: T, index: number) => ReactNode;
+  /** Optional sorting key (if different from key) */
+  sortKey?: keyof T | string;
+  /** Enable sorting for this column */
+  sortable?: boolean;
+  /** Responsive visibility */
+  responsive?: "sm" | "md" | "lg" | "xl" | "always";
+  /** Column width class */
+  width?: string;
+  /** Alignment */
+  align?: "left" | "center" | "right";
+}
+
+/**
+ * Table action definition
+ */
+export interface TableAction<T extends BaseDataItem> {
+  /** Action identifier */
+  key: string;
+  /** Display label */
+  label: string;
+  /** Icon component */
+  icon?: ReactNode;
+  /** Action handler */
+  onClick: (item: T) => void | Promise<void>;
+  /** Visibility condition */
+  visible?: (item: T) => boolean;
+  /** Disabled condition */
+  disabled?: (item: T) => boolean;
+  /** Button variant */
+  variant?: "default" | "destructive" | "ghost" | "link" | "outline";
+  /** Color class */
+  colorClass?: string;
+}
+
+/**
+ * Bulk action definition for multi-select
+ */
+export interface BulkAction<T extends BaseDataItem> {
+  key: string;
+  label: string;
+  icon?: ReactNode;
+  onClick: (items: T[]) => void | Promise<void>;
+  disabled?: (items: T[]) => boolean;
+  variant?: "default" | "destructive" | "ghost" | "outline";
+}
+
+/**
+ * Sort configuration
+ */
+export interface SortConfig {
+  key: string;
+  direction: "asc" | "desc";
+}
+
+/**
+ * Pagination configuration
+ */
+export interface PaginationConfig {
+  page: number;
+  pageSize: number;
+  totalItems: number;
+  totalPages: number;
+}
+
+// ============================================================================
+// TAB TYPES
+// ============================================================================
+
+/**
+ * Tab definition
+ */
+export interface TabDef {
+  /** Unique tab key */
+  key: string;
+  /** Display label */
+  label: string;
+  /** Optional badge count */
+  badge?: number | null;
+  /** Badge variant */
+  badgeVariant?: "default" | "secondary" | "destructive" | "outline";
+  /** Tab icon */
+  icon?: ReactNode;
+  /** Tab content */
+  content: ReactNode;
+  /** Disabled state */
+  disabled?: boolean;
+}
+
+// ============================================================================
+// DIALOG TYPES
+// ============================================================================
+
+/**
+ * Dialog configuration
+ */
+export interface DialogConfig {
+  /** Dialog title */
+  title: string;
+  /** Dialog description */
+  description?: string;
+  /** Dialog size */
+  size?: "sm" | "md" | "lg" | "xl" | "full";
+}
+
+/**
+ * Confirmation dialog configuration
+ */
+export interface ConfirmDialogConfig extends DialogConfig {
+  /** Confirm button label */
+  confirmLabel?: string;
+  /** Cancel button label */
+  cancelLabel?: string;
+  /** Confirm button variant */
+  confirmVariant?: "default" | "destructive";
+  /** Whether action is in progress */
+  isLoading?: boolean;
+}
+
+/**
+ * Detail dialog field definition
+ */
+export interface DetailField<T> {
+  /** Field key */
+  key: string;
+  /** Display label */
+  label: string;
+  /** Value renderer */
+  render: (item: T) => ReactNode;
+  /** Full width */
+  fullWidth?: boolean;
+  /** Hide condition */
+  hidden?: (item: T) => boolean;
+}
+
+// ============================================================================
+// FORM TYPES
+// ============================================================================
+
+/**
+ * Form field types
+ */
+export type FormFieldType =
+  | "text"
+  | "number"
+  | "boolean"
+  | "select"
+  | "textarea"
+  | "code"
+  | "password"
+  | "email"
+  | "date"
+  | "datetime";
+
+/**
+ * Form field definition
+ */
+export interface FormFieldDef {
+  /** Field key */
+  key: string;
+  /** Display label */
+  label: string;
+  /** Field type */
+  type: FormFieldType;
+  /** Help text */
+  helpText?: string;
+  /** Required field */
+  required?: boolean;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Default value */
+  defaultValue?: unknown;
+  /** Options for select fields */
+  options?: SelectOption[];
+  /** Validation function */
+  validate?: (value: unknown) => string | null;
+  /** Code editor language */
+  codeLanguage?: string;
+  /** Disabled condition */
+  disabled?: boolean;
+  /** Full width */
+  fullWidth?: boolean;
+}
+
+/**
+ * Select option
+ */
+export interface SelectOption {
+  label: string;
+  value: string | number | boolean;
+  description?: string;
+}
+
+/**
+ * Dynamic parameter definition (for policy templates etc.)
+ */
+export interface ParameterDef {
+  name: string;
+  type: "string" | "number" | "boolean" | "select";
+  helpText: string;
+  required: boolean;
+  defaultValue?: unknown;
+  options?: string[];
+}
+
+// ============================================================================
+// STATUS & BADGE TYPES
+// ============================================================================
+
+/**
+ * Status types with associated colors
+ */
+export type StatusType =
+  | "pending"
+  | "approved"
+  | "rejected"
+  | "committed"
+  | "cancelled"
+  | "mixed"
+  | "ready"
+  | "error"
+  | "warning"
+  | "info"
+  | "success";
+
+/**
+ * Status configuration
+ */
+export interface StatusConfig {
+  label: string;
+  variant: StatusType;
+  icon?: ReactNode;
+}
+
+/**
+ * Badge configuration for custom badges
+ */
+export interface BadgeConfig {
+  label: string;
+  colorClass?: string;
+  variant?: "default" | "secondary" | "destructive" | "outline";
+}
+
+// ============================================================================
+// ACTION TYPES
+// ============================================================================
+
+/**
+ * Action result for async operations
+ */
+export interface ActionResult {
+  success: boolean;
+  message?: string;
+  error?: Error;
+}
+
+/**
+ * Async action handler type
+ */
+export type AsyncActionHandler<T = void, R = ActionResult> = (arg: T) => Promise<R>;
+
+// ============================================================================
+// APPROVAL WORKFLOW TYPES
+// ============================================================================
+
+/**
+ * Approval decision
+ */
+export interface ApprovalDecision {
+  userId: string;
+  userName?: string;
+  userEmail?: string;
+  approved: boolean;
+  timestamp: string | number;
+  signature?: string;
+}
+
+/**
+ * Approval status with threshold
+ */
+export interface ApprovalStatus {
+  approvalCount: number;
+  rejectionCount: number;
+  threshold: number;
+  decisions?: ApprovalDecision[];
+}
+
+/**
+ * Raw approval request for signing
+ */
+export interface RawApprovalRequest {
+  changesetId: string;
+  changeSetDraftRequests: string; // Base64 encoded
+  requiresApprovalPopup?: boolean;
+}
+
+/**
+ * Signed approval response
+ */
+export interface SignedApprovalResponse {
+  id: string;
+  approved?: {
+    request: Uint8Array;
+  };
+  denied?: boolean;
+}
+
+// ============================================================================
+// HOOK TYPES
+// ============================================================================
+
+export interface AutoRefreshOptions {
+  /** Refresh interval in seconds */
+  intervalSeconds: number;
+  /** Whether auto-refresh is enabled */
+  enabled?: boolean;
+  /** Refresh callback */
+  refresh: () => void | Promise<unknown>;
+  /** Block refresh while condition is true */
+  isBlocked?: boolean;
+  /** Error callback - called when refresh fails */
+  onError?: (error: Error) => void;
+  /** Max consecutive failures before stopping (default: unlimited) */
+  maxRetries?: number;
+}
+
+export interface AutoRefreshReturn {
+  /** Seconds until next refresh */
+  secondsRemaining: number | null;
+  /** Trigger immediate refresh */
+  refreshNow: () => Promise<void>;
+  /** Reset the timer */
+  resetTimer: () => void;
+  /** Last error from refresh (null if no error) */
+  lastError: Error | null;
+  /** Number of consecutive failures */
+  failureCount: number;
+  /** Whether auto-refresh stopped due to max retries */
+  isStopped: boolean;
+}
+
+/**
+ * Selection hook return type
+ */
+export interface SelectionReturn<T extends BaseDataItem> {
+  /** Currently selected item IDs */
+  selectedIds: string[];
+  /** Check if item is selected */
+  isSelected: (id: string) => boolean;
+  /** Toggle item selection */
+  toggle: (id: string) => void;
+  /** Select all items */
+  selectAll: (items: T[]) => void;
+  /** Clear all selections */
+  clearAll: () => void;
+  /** Toggle all items */
+  toggleAll: (items: T[]) => void;
+  /** Get selected items from a list */
+  getSelected: (items: T[]) => T[];
+  /** Whether all items are selected */
+  allSelected: (items: T[]) => boolean;
+  /** Whether some (but not all) items are selected */
+  someSelected: (items: T[]) => boolean;
+}
+
+/**
+ * Pagination hook return type
+ */
+export interface PaginationReturn {
+  page: number;
+  pageSize: number;
+  setPage: (page: number) => void;
+  setPageSize: (size: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+  canNextPage: boolean;
+  canPrevPage: boolean;
+  totalPages: number;
+  startIndex: number;
+  endIndex: number;
+}
+
+// ============================================================================
+// UTILITY TYPES
+// ============================================================================
+
+/**
+ * Toast notification type
+ */
+export interface ToastConfig {
+  title: string;
+  description?: string;
+  variant?: "default" | "destructive";
+  duration?: number;
+}
+
+/**
+ * Empty state configuration
+ */
+export interface EmptyStateConfig {
+  icon?: ReactNode;
+  title: string;
+  description?: string;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}
+
+/**
+ * Loading state configuration
+ */
+export interface LoadingStateConfig {
+  /** Number of skeleton rows */
+  rows?: number;
+  /** Type of skeleton */
+  type?: "table" | "card" | "list";
+}
+
+// ============================================================================
+// PROVIDER TYPES
+// ============================================================================
+
+/**
+ * Framework configuration
+ */
+export interface FrameworkConfig {
+  /** Toast function (from your toast library) */
+  toast?: (config: ToastConfig) => void;
+  /** Custom class name generator */
+  cn?: (...inputs: unknown[]) => string;
+  /** Default page size */
+  defaultPageSize?: number;
+  /** Default auto-refresh interval */
+  defaultRefreshInterval?: number;
+}

package/src/utils/index.ts

@@ -0,0 +1,121 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Merge Tailwind classes with clsx
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+/**
+ * Convert base64 string to Uint8Array
+ */
+export function base64ToBytes(base64: string): Uint8Array {
+  const binaryString = atob(base64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/**
+ * Convert Uint8Array to base64 string
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Format timestamp to locale string
+ */
+export function formatTimestamp(
+  timestamp: string | number,
+  options?: Intl.DateTimeFormatOptions
+): string {
+  const date = typeof timestamp === "number"
+    ? new Date(timestamp > 1e12 ? timestamp : timestamp * 1000) // Handle both ms and seconds
+    : new Date(timestamp);
+
+  return date.toLocaleString("en-US", options ?? {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/**
+ * Format date for logs (includes seconds)
+ */
+export function formatLogTimestamp(timestampMs: number): string {
+  const date = new Date(timestampMs);
+  return date.toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: true,
+  });
+}
+
+/**
+ * Compute optimal number of rows for viewport height
+ */
+export function computeRowsForViewportHeight(
+  viewportHeight: number,
+  headerPx = 48,
+  rowPx = 44
+): number {
+  const availablePx = Math.max(0, viewportHeight - headerPx);
+  const rows = Math.floor(availablePx / rowPx);
+  return Math.max(5, Math.min(200, rows));
+}
+
+/**
+ * Delay helper for async operations
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Safe JSON parse
+ */
+export function safeJsonParse<T>(json: string, fallback: T): T {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Truncate text with ellipsis
+ */
+export function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Check if a value is defined (not null or undefined)
+ */
+export function isDefined<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Generate unique ID
+ */
+export function generateId(): string {
+  return Math.random().toString(36).substring(2, 9);
+}