@classytic/fluid 0.2.1 → 0.3.2

package/dist/client/error.d.mts

@@ -0,0 +1,125 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { ComponentType, ReactNode } from "react";
+import { FallbackProps } from "react-error-boundary";
+
+//#region src/components/error-boundary.d.ts
+interface ErrorBoundaryFallbackProps extends FallbackProps {}
+interface ErrorBoundaryProps {
+  /** Custom fallback component. Defaults to FullPageErrorFallback. */
+  fallback?: ComponentType<FallbackProps>;
+  /** Called when an error is caught */
+  onError?: (error: unknown, info: {
+    componentStack?: string | null;
+  }) => void;
+  /** Called when the error boundary resets */
+  onReset?: () => void;
+  children: ReactNode;
+}
+interface FeatureErrorBoundaryProps {
+  /** Name of the feature section (shown in error message) */
+  featureName?: string;
+  /** Called when an error is caught */
+  onError?: (error: unknown, info: {
+    componentStack?: string | null;
+  }) => void;
+  /** Called when the error boundary resets */
+  onReset?: () => void;
+  children: ReactNode;
+  className?: string;
+}
+/**
+ * Full-page error fallback with retry and go-home buttons.
+ * Used as the default for ErrorBoundary.
+ */
+declare function FullPageErrorFallback({
+  error,
+  resetErrorBoundary
+}: FallbackProps): react_jsx_runtime0.JSX.Element;
+/**
+ * Compact inline error fallback for feature sections.
+ * Used as the default for FeatureErrorBoundary.
+ */
+declare function InlineErrorFallback({
+  error,
+  resetErrorBoundary,
+  featureName,
+  className
+}: FallbackProps & {
+  featureName?: string;
+  className?: string;
+}): react_jsx_runtime0.JSX.Element;
+/**
+ * Global error boundary with full-page fallback.
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary onError={(e) => logError(e)}>
+ *   <App />
+ * </ErrorBoundary>
+ * ```
+ */
+declare function ErrorBoundary({
+  fallback: FallbackComponent,
+  onError,
+  onReset,
+  children
+}: ErrorBoundaryProps): react_jsx_runtime0.JSX.Element;
+/**
+ * Feature-scoped error boundary with compact inline fallback.
+ *
+ * @example
+ * ```tsx
+ * <FeatureErrorBoundary featureName="Analytics">
+ *   <AnalyticsDashboard />
+ * </FeatureErrorBoundary>
+ * ```
+ */
+declare function FeatureErrorBoundary({
+  featureName,
+  onError,
+  onReset,
+  children,
+  className
+}: FeatureErrorBoundaryProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/async-boundary.d.ts
+interface AsyncBoundaryProps {
+  /** Suspense fallback (shown while loading) */
+  fallback?: ReactNode;
+  /** Error fallback component (shown on error) */
+  errorFallback?: ComponentType<FallbackProps>;
+  /** Called when an error is caught */
+  onError?: (error: unknown, info: {
+    componentStack?: string | null;
+  }) => void;
+  /** Called when the error boundary resets */
+  onReset?: () => void;
+  children: ReactNode;
+}
+/**
+ * AsyncBoundary — Suspense + ErrorBoundary combined.
+ *
+ * If `errorFallback` is provided, wraps in ErrorBoundary from react-error-boundary.
+ * Otherwise, renders Suspense only.
+ *
+ * @example
+ * ```tsx
+ * import { AsyncBoundary, InlineErrorFallback } from "@classytic/fluid/client";
+ *
+ * <AsyncBoundary
+ *   fallback={<SkeletonTable rows={5} />}
+ *   errorFallback={InlineErrorFallback}
+ * >
+ *   <DataFetchingComponent />
+ * </AsyncBoundary>
+ * ```
+ */
+declare function AsyncBoundary({
+  fallback,
+  errorFallback: ErrorFallback,
+  onError,
+  onReset,
+  children
+}: AsyncBoundaryProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { AsyncBoundary, type AsyncBoundaryProps, ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, FeatureErrorBoundary, type FeatureErrorBoundaryProps, FullPageErrorFallback, InlineErrorFallback };

package/dist/client/error.mjs

@@ -0,0 +1,166 @@
+"use client";
+
+import { t as cn } from "../utils-DQ5SCVoW.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { AlertCircle, Home, RefreshCw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { ErrorBoundary as ErrorBoundary$1 } from "react-error-boundary";
+
+//#region src/components/error-boundary.tsx
+/**
+* Full-page error fallback with retry and go-home buttons.
+* Used as the default for ErrorBoundary.
+*/
+function FullPageErrorFallback({ error, resetErrorBoundary }) {
+	const isDev = process.env.NODE_ENV === "development";
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "flex min-h-[50vh] flex-col items-center justify-center gap-4 p-6",
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				className: "rounded-full bg-destructive/10 p-3",
+				children: /* @__PURE__ */ jsx(AlertCircle, { className: "h-8 w-8 text-destructive" })
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "text-center space-y-1.5",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-xl font-semibold",
+						children: "Something went wrong"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-sm text-muted-foreground max-w-md",
+						children: "An unexpected error occurred. Please try again or return to the home page."
+					}),
+					isDev && errorMessage && /* @__PURE__ */ jsx("pre", {
+						className: "mt-3 max-w-lg overflow-auto rounded-md bg-muted p-3 text-left text-xs text-destructive",
+						children: errorMessage
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex gap-2",
+				children: [/* @__PURE__ */ jsxs(Button, {
+					variant: "outline",
+					onClick: resetErrorBoundary,
+					children: [/* @__PURE__ */ jsx(RefreshCw, { className: "mr-2 h-4 w-4" }), "Try Again"]
+				}), /* @__PURE__ */ jsxs(Button, {
+					onClick: () => window.location.href = "/",
+					children: [/* @__PURE__ */ jsx(Home, { className: "mr-2 h-4 w-4" }), "Go Home"]
+				})]
+			})
+		]
+	});
+}
+/**
+* Compact inline error fallback for feature sections.
+* Used as the default for FeatureErrorBoundary.
+*/
+function InlineErrorFallback({ error, resetErrorBoundary, featureName, className }) {
+	const isDev = process.env.NODE_ENV === "development";
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return /* @__PURE__ */ jsx("div", {
+		className: cn("rounded-lg border border-destructive/20 bg-destructive/5 p-4", className),
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "flex items-start gap-3",
+			children: [/* @__PURE__ */ jsx(AlertCircle, { className: "h-5 w-5 text-destructive mt-0.5 shrink-0" }), /* @__PURE__ */ jsxs("div", {
+				className: "flex-1 min-w-0",
+				children: [
+					/* @__PURE__ */ jsx("h3", {
+						className: "text-sm font-medium",
+						children: featureName ? `Error loading ${featureName}` : "Something went wrong"
+					}),
+					isDev && errorMessage && /* @__PURE__ */ jsx("pre", {
+						className: "mt-1.5 text-xs text-destructive/80 whitespace-pre-wrap break-words",
+						children: errorMessage
+					}),
+					/* @__PURE__ */ jsxs(Button, {
+						variant: "outline",
+						size: "sm",
+						className: "mt-2 h-7 gap-1.5",
+						onClick: resetErrorBoundary,
+						children: [/* @__PURE__ */ jsx(RefreshCw, { className: "h-3 w-3" }), "Retry"]
+					})
+				]
+			})]
+		})
+	});
+}
+/**
+* Global error boundary with full-page fallback.
+*
+* @example
+* ```tsx
+* <ErrorBoundary onError={(e) => logError(e)}>
+*   <App />
+* </ErrorBoundary>
+* ```
+*/
+function ErrorBoundary({ fallback: FallbackComponent = FullPageErrorFallback, onError, onReset, children }) {
+	return /* @__PURE__ */ jsx(ErrorBoundary$1, {
+		FallbackComponent,
+		onError,
+		onReset,
+		children
+	});
+}
+/**
+* Feature-scoped error boundary with compact inline fallback.
+*
+* @example
+* ```tsx
+* <FeatureErrorBoundary featureName="Analytics">
+*   <AnalyticsDashboard />
+* </FeatureErrorBoundary>
+* ```
+*/
+function FeatureErrorBoundary({ featureName = "Feature", onError, onReset, children, className }) {
+	return /* @__PURE__ */ jsx(ErrorBoundary$1, {
+		FallbackComponent: (props) => /* @__PURE__ */ jsx(InlineErrorFallback, {
+			...props,
+			featureName,
+			className
+		}),
+		onError,
+		onReset,
+		children
+	});
+}
+
+//#endregion
+//#region src/components/async-boundary.tsx
+/**
+* AsyncBoundary — Suspense + ErrorBoundary combined.
+*
+* If `errorFallback` is provided, wraps in ErrorBoundary from react-error-boundary.
+* Otherwise, renders Suspense only.
+*
+* @example
+* ```tsx
+* import { AsyncBoundary, InlineErrorFallback } from "@classytic/fluid/client";
+*
+* <AsyncBoundary
+*   fallback={<SkeletonTable rows={5} />}
+*   errorFallback={InlineErrorFallback}
+* >
+*   <DataFetchingComponent />
+* </AsyncBoundary>
+* ```
+*/
+function AsyncBoundary({ fallback, errorFallback: ErrorFallback, onError, onReset, children }) {
+	const suspenseWrapped = /* @__PURE__ */ jsx(Suspense, {
+		fallback: fallback ?? null,
+		children
+	});
+	if (!ErrorFallback) return suspenseWrapped;
+	return /* @__PURE__ */ jsx(ErrorBoundary$1, {
+		FallbackComponent: ErrorFallback,
+		onError,
+		onReset,
+		children: suspenseWrapped
+	});
+}
+
+//#endregion
+export { AsyncBoundary, ErrorBoundary, FeatureErrorBoundary, FullPageErrorFallback, InlineErrorFallback };

package/dist/client/hooks.d.mts

@@ -0,0 +1,162 @@
+import { n as UseBaseSearchReturn, r as useBaseSearch, t as UseBaseSearchConfig } from "../use-base-search-BGgWnWaF.mjs";
+import { n as useKeyboardShortcut, t as UseKeyboardShortcutOptions } from "../use-keyboard-shortcut-_mRCh3QO.mjs";
+import { RefObject } from "react";
+
+//#region src/hooks/use-mobile.d.ts
+declare function useIsMobile(): boolean;
+//#endregion
+//#region src/hooks/use-media-query.d.ts
+declare function useMediaQuery(query: string, defaultValue?: boolean): boolean;
+//#endregion
+//#region src/hooks/use-scroll-detection.d.ts
+declare const useScrollDetection: (ref: RefObject<HTMLDivElement | null>, delay?: number) => {
+  checkScroll: () => void;
+  canScrollLeft: boolean;
+  canScrollRight: boolean;
+  isScrollable: boolean;
+};
+//#endregion
+//#region src/hooks/use-debounce.d.ts
+/**
+ * useDebounce — Returns a debounced version of the input value.
+ *
+ * @example
+ * ```tsx
+ * const [search, setSearch] = useState("");
+ * const debouncedSearch = useDebounce(search, 300);
+ *
+ * useEffect(() => {
+ *   fetchResults(debouncedSearch);
+ * }, [debouncedSearch]);
+ * ```
+ */
+declare function useDebounce<T>(value: T, delay?: number): T;
+/**
+ * useDebouncedCallback — Returns a debounced version of a callback function.
+ *
+ * @example
+ * ```tsx
+ * const debouncedSave = useDebouncedCallback((value: string) => {
+ *   saveToApi(value);
+ * }, 500);
+ *
+ * <Input onChange={(e) => debouncedSave(e.target.value)} />
+ * ```
+ */
+declare function useDebouncedCallback<T extends (...args: any[]) => any>(callback: T, delay?: number): (...args: Parameters<T>) => void;
+//#endregion
+//#region src/hooks/use-copy-to-clipboard.d.ts
+interface UseCopyToClipboardReturn {
+  /** Copy text to clipboard */
+  copy: (text: string) => Promise<boolean>;
+  /** Whether text was recently copied (resets after timeout) */
+  copied: boolean;
+  /** Any error that occurred during copy */
+  error: Error | null;
+  /** Reset the copied state manually */
+  reset: () => void;
+}
+/**
+ * useCopyToClipboard — Copy text to clipboard with status tracking.
+ *
+ * @param resetDelay - How long (ms) the `copied` state stays true. Default: 2000
+ *
+ * @example
+ * ```tsx
+ * const { copy, copied } = useCopyToClipboard();
+ *
+ * <Button onClick={() => copy(apiKey)}>
+ *   {copied ? "Copied!" : "Copy API Key"}
+ * </Button>
+ * ```
+ */
+declare function useCopyToClipboard(resetDelay?: number): UseCopyToClipboardReturn;
+//#endregion
+//#region src/hooks/use-local-storage.d.ts
+/**
+ * useLocalStorage — Persist state in localStorage with type safety and optional expiry.
+ *
+ * @param key - The localStorage key
+ * @param initialValue - Default value if no stored value exists
+ * @param ttl - Time to live in milliseconds (optional)
+ *
+ * @example
+ * ```tsx
+ * const [theme, setTheme] = useLocalStorage("theme", "light");
+ * const [cache, setCache] = useLocalStorage("api-cache", {}, 60000); // 1 min TTL
+ * ```
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, ttl?: number): [T, (value: T | ((prev: T) => T)) => void, () => void];
+//#endregion
+//#region src/lib/storage.d.ts
+/**
+ * A utility module for handling localStorage operations with error handling and SSR safety
+ */
+/**
+ * Gets an item from localStorage with parsing and expiry check
+ * @param {string} key - The key to retrieve from localStorage
+ * @param {any} defaultValue - Default value to return if key doesn't exist or on error
+ * @returns {any} The parsed value or defaultValue
+ */
+declare const getStorageItem: <T>(key: string, defaultValue?: T | null) => T | null;
+/**
+ * Sets an item in localStorage with serialization and optional expiry
+ * @param {string} key - The key to set in localStorage
+ * @param {any} value - The value to serialize and store
+ * @param {number} [ttl] - Time to live in milliseconds (optional)
+ * @returns {boolean} Success status
+ */
+declare const setStorageItem: <T>(key: string, value: T, ttl?: number | null) => boolean;
+/**
+ * Removes an item from localStorage
+ * @param {string} key - The key to remove from localStorage
+ * @returns {boolean} Success status
+ */
+declare const removeStorageItem: (key: string) => boolean;
+/**
+ * Clears all items from localStorage
+ * @returns {boolean} Success status
+ */
+declare const clearStorage: () => boolean;
+/**
+ * Checks if localStorage is empty for a specific key
+ * @param {string} key - The key to check in localStorage
+ * @returns {boolean} True if empty or doesn't exist
+ */
+declare const isStorageEmpty: (key: string) => boolean;
+/**
+ * Generates a UUID (v4)
+ * Uses crypto.randomUUID() when available, with a fallback for older environments.
+ * @returns {string} A random UUID
+ */
+declare const generateUUID: () => string;
+/**
+ * Common expiry durations in milliseconds
+ */
+declare const TTL: {
+  readonly MINUTE: number;
+  readonly HOUR: number;
+  readonly DAY: number;
+  readonly WEEK: number;
+  readonly MONTH: number;
+};
+/**
+ * Shorthand object for all localStorage operations
+ */
+declare const storage: {
+  get: <T>(key: string, defaultValue?: T | null) => T | null;
+  set: <T>(key: string, value: T, ttl?: number | null) => boolean;
+  remove: (key: string) => boolean;
+  clear: () => boolean;
+  isEmpty: (key: string) => boolean;
+  generateUUID: () => string;
+  TTL: {
+    readonly MINUTE: number;
+    readonly HOUR: number;
+    readonly DAY: number;
+    readonly WEEK: number;
+    readonly MONTH: number;
+  };
+};
+//#endregion
+export { TTL, type UseBaseSearchConfig, type UseBaseSearchReturn, type UseCopyToClipboardReturn, type UseKeyboardShortcutOptions, clearStorage, generateUUID, getStorageItem, isStorageEmpty, removeStorageItem, setStorageItem, storage, useBaseSearch, useCopyToClipboard, useDebounce, useDebouncedCallback, useIsMobile, useKeyboardShortcut, useLocalStorage, useMediaQuery, useScrollDetection };