@neasg/design-system 0.3.0 → 0.4.2

package/dist/tabs.d.ts

@@ -20,12 +20,35 @@ interface TabsContentProps extends React.ComponentPropsWithoutRef<typeof TabsPri
     value: string;
 }
 declare const TabsContent: React.ForwardRefExoticComponent<TabsContentProps & React.RefAttributes<HTMLDivElement>>;
+export interface TabDropdownSection {
+    id: string;
+    label: React.ReactNode;
+}
 export interface TabsItem {
     value: string;
     label: React.ReactNode;
     content: React.ReactNode;
     disabled?: boolean;
+    /** When provided, the tab shows a chevron and opens a dropdown menu of in-page sections. */
+    sections?: TabDropdownSection[];
+    /** Scroll offset in pixels when scrolling to a section (default 200). */
+    scrollOffset?: number;
+    /** Override the default scroll-to-id behavior when a section is picked. */
+    onSectionSelect?: (sectionId: string) => void;
+    /** Currently-active section id. When set, the parent tab renders as active and the item is highlighted in the dropdown. */
+    activeSection?: string;
+}
+export interface TabWithDropdownProps {
+    value: string;
+    label: React.ReactNode;
+    sections?: TabDropdownSection[];
+    disabled?: boolean;
+    scrollOffset?: number;
+    onSectionSelect?: (sectionId: string) => void;
+    activeSection?: string;
+    className?: string;
 }
+declare function TabWithDropdown({ value, label, sections, disabled, scrollOffset, onSectionSelect, activeSection, className, }: TabWithDropdownProps): import("react/jsx-runtime").JSX.Element;
 export interface TabsProps extends Omit<React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root>, "children" | "value" | "defaultValue" | "onValueChange"> {
     items: TabsItem[];
     defaultValue?: string;
@@ -36,4 +59,4 @@ export interface TabsProps extends Omit<React.ComponentPropsWithoutRef<typeof Ta
     panelClassName?: string;
 }
 declare function Tabs({ items, defaultValue, value, onValueChange, className, listClassName, triggerClassName, panelClassName, ...props }: TabsProps): import("react/jsx-runtime").JSX.Element | null;
-export { Tabs, TabsRoot, TabsList, TabsTrigger, TabsContent };
+export { Tabs, TabsRoot, TabsList, TabsTrigger, TabsContent, TabWithDropdown };

package/dist/tabs.js

@@ -2,7 +2,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
+import { ChevronDownIcon } from "./animated-icons/chevron-down";
 import { cn } from "./lib/utils";
+import { Popover } from "./popover";
+import { PopoverMenuItem, PopoverMenuSection } from "./popover-menu";
 const TabsContext = React.createContext(null);
 export function useTabsContext() {
     return React.useContext(TabsContext);
@@ -23,16 +26,71 @@ const TabsRoot = React.forwardRef(({ defaultValue = "", value: valueProp, onValu
 TabsRoot.displayName = TabsPrimitive.Root.displayName;
 const TabsList = React.forwardRef(({ className, ...props }, ref) => (_jsx(TabsPrimitive.List, { ref: ref, className: cn("inline-flex h-fit items-center justify-center rounded-lg bg-muted p-1 text-muted-foreground", className), ...props })));
 TabsList.displayName = TabsPrimitive.List.displayName;
-const TabsTrigger = React.forwardRef(({ className, value, ...props }, ref) => (_jsx(TabsPrimitive.Trigger, { ref: ref, value: value, className: cn("inline-flex cursor-pointer items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm", className), ...props })));
+const TabsTrigger = React.forwardRef(({ className, value, ...props }, ref) => (_jsx(TabsPrimitive.Trigger, { ref: ref, value: value, className: cn("inline-flex cursor-pointer items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=inactive]:hover:bg-background/50 data-[state=inactive]:hover:text-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm", className), ...props })));
 TabsTrigger.displayName = TabsPrimitive.Trigger.displayName;
 const TabsContent = React.forwardRef(({ className, value, ...props }, ref) => (_jsx(TabsPrimitive.Content, { ref: ref, value: value, className: cn("focus-visible:outline-none", className), ...props })));
 TabsContent.displayName = TabsPrimitive.Content.displayName;
+function TabTriggerWithDropdown({ item, triggerClassName, }) {
+    var _a, _b, _c, _d, _e;
+    const [open, setOpen] = React.useState(false);
+    const sections = (_a = item.sections) !== null && _a !== void 0 ? _a : [];
+    const [internalActiveSection, setInternalActiveSection] = React.useState((_c = (_b = sections[0]) === null || _b === void 0 ? void 0 : _b.id) !== null && _c !== void 0 ? _c : null);
+    const tabsContext = useTabsContext();
+    const scrollOffset = (_d = item.scrollOffset) !== null && _d !== void 0 ? _d : 200;
+    const activeSection = (_e = item.activeSection) !== null && _e !== void 0 ? _e : internalActiveSection;
+    const handleSectionClick = (sectionId) => {
+        setOpen(false);
+        setInternalActiveSection(sectionId);
+        if (item.onSectionSelect) {
+            item.onSectionSelect(sectionId);
+            return;
+        }
+        const doScroll = () => {
+            const el = document.getElementById(sectionId);
+            if (!el)
+                return;
+            const top = el.getBoundingClientRect().top + window.scrollY - scrollOffset;
+            window.scrollTo({ top, behavior: "smooth" });
+        };
+        if (tabsContext && tabsContext.value !== item.value) {
+            tabsContext.setValue(item.value);
+            setTimeout(doScroll, 50);
+        }
+        else {
+            doScroll();
+        }
+    };
+    // Clear the internal "active section" when the user switches away from
+    // this tab, so we don't leave a stale highlight in the dropdown menu.
+    const isTabSelected = tabsContext
+        ? tabsContext.value === item.value
+        : false;
+    React.useEffect(() => {
+        var _a, _b;
+        if (!isTabSelected && item.activeSection === undefined) {
+            setInternalActiveSection((_b = (_a = sections[0]) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : null);
+        }
+    }, [isTabSelected, item.activeSection, sections]);
+    return (_jsx(Popover, { open: open, onOpenChange: setOpen, surface: "menu", align: "start", contentClassName: "min-w-[12rem]", trigger: _jsxs(TabsTrigger, { value: item.value, disabled: item.disabled, "data-state": isTabSelected ? "active" : "inactive", className: cn("flex items-center gap-1", triggerClassName), children: [item.label, _jsx(ChevronDownIcon, { size: 12, className: cn("transition-transform duration-200", open && "rotate-180") })] }), children: _jsx(PopoverMenuSection, { children: sections.map((section) => (_jsx(PopoverMenuItem, { active: isTabSelected && activeSection === section.id, className: "py-2 pl-2 pr-8", onClick: () => handleSectionClick(section.id), children: section.label }, section.id))) }) }));
+}
+function TabWithDropdown({ value, label, sections, disabled, scrollOffset, onSectionSelect, activeSection, className, }) {
+    return (_jsx(TabTriggerWithDropdown, { item: {
+            value,
+            label,
+            content: null,
+            sections,
+            disabled,
+            scrollOffset,
+            onSectionSelect,
+            activeSection,
+        }, triggerClassName: className }));
+}
 function Tabs({ items, defaultValue, value, onValueChange, className, listClassName, triggerClassName, panelClassName, ...props }) {
     var _a, _b;
     const fallbackValue = (_b = defaultValue !== null && defaultValue !== void 0 ? defaultValue : (_a = items[0]) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : "";
     if (!items.length) {
         return null;
     }
-    return (_jsxs(TabsRoot, { defaultValue: fallbackValue, value: value, onValueChange: onValueChange, className: cn("space-y-4", className), ...props, children: [_jsx(TabsList, { className: listClassName, children: items.map((item) => (_jsx(TabsTrigger, { value: item.value, disabled: item.disabled, className: triggerClassName, children: item.label }, item.value))) }), items.map((item) => (_jsx(TabsContent, { value: item.value, className: cn("rounded-md border p-4", panelClassName), children: item.content }, item.value)))] }));
+    return (_jsxs(TabsRoot, { defaultValue: fallbackValue, value: value, onValueChange: onValueChange, className: cn("space-y-4", className), ...props, children: [_jsx(TabsList, { className: listClassName, children: items.map((item) => item.sections && item.sections.length > 0 ? (_jsx(TabTriggerWithDropdown, { item: item, triggerClassName: triggerClassName }, item.value)) : (_jsx(TabsTrigger, { value: item.value, disabled: item.disabled, className: triggerClassName, children: item.label }, item.value))) }), items.map((item) => (_jsx(TabsContent, { value: item.value, className: cn("pt-4", panelClassName), children: item.content }, item.value)))] }));
 }
-export { Tabs, TabsRoot, TabsList, TabsTrigger, TabsContent };
+export { Tabs, TabsRoot, TabsList, TabsTrigger, TabsContent, TabWithDropdown };

package/dist/tailwind-preset.js

@@ -64,6 +64,15 @@ export const neaTailwindPreset = {
                 semibold: "var(--font-weight-semibold)",
                 bold: "var(--font-weight-bold)",
             },
+            height: {
+                control: "var(--size-control)",
+            },
+            width: {
+                control: "var(--size-control)",
+            },
+            minHeight: {
+                control: "var(--size-control)",
+            },
             spacing: {
                 0: "var(--space-0)",
                 1: "var(--space-1)",

package/dist/textarea.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Field, FieldDescription, FieldError, FieldLabel } from "./field";
 import { cn } from "./lib/utils";
-const TextareaControl = React.forwardRef(({ className, ...props }, ref) => (_jsx("textarea", { ref: ref, "data-slot": "textarea", className: cn("flex min-h-20 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive/20 md:text-sm", className), ...props })));
+const TextareaControl = React.forwardRef(({ className, ...props }, ref) => (_jsx("textarea", { ref: ref, "data-slot": "textarea", className: cn("flex min-h-20 w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive/20", className), ...props })));
 TextareaControl.displayName = "TextareaControl";
 const Textarea = React.forwardRef(({ label, description, error, invalid = false, hideLabel = false, className, textareaClassName, labelClassName, descriptionClassName, errorClassName, id, disabled, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy, ...props }, ref) => {
     const generatedId = React.useId();

package/dist/toaster.js

@@ -1,17 +1,26 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Toaster as SonnerToaster, toast } from "sonner";
-function Toaster({ position = "bottom-right", visibleToasts = 3, closeButton = true, duration = 4000, }) {
-    return (_jsx(SonnerToaster, { position: position, visibleToasts: visibleToasts, closeButton: closeButton, duration: duration, toastOptions: {
+import { buttonVariants } from "./button";
+import { XIcon } from "./animated-icons/x";
+import { cn } from "./lib/utils";
+function Toaster({ position = "top-right", visibleToasts = 3, closeButton = true, duration = 4000, }) {
+    return (_jsx(SonnerToaster, { position: position, visibleToasts: visibleToasts, closeButton: closeButton, duration: duration, icons: {
+            close: _jsx(XIcon, { size: 14 }),
+        }, toastOptions: {
             classNames: {
-                toast: "group border border-border bg-background text-foreground shadow-md rounded-lg p-4 flex items-start gap-3",
-                title: "text-sm font-medium",
-                description: "text-sm text-muted-foreground",
-                closeButton: "text-muted-foreground hover:text-foreground",
-                success: "border-[hsl(var(--status-success-foreground))]/20",
-                error: "border-destructive/20",
-                warning: "border-[hsl(var(--status-warning-foreground))]/20",
-                info: "border-[hsl(var(--status-info-foreground))]/20",
+                toast: "group relative border border-border bg-background text-foreground shadow-md rounded-lg p-4 pr-10 flex items-start gap-3",
+                content: "min-w-0 flex-1 gap-1",
+                title: "text-sm font-medium leading-5",
+                description: "text-sm text-muted-foreground leading-5",
+                icon: "mt-0.5 text-muted-foreground",
+                actionButton: cn(buttonVariants({ variant: "link" }), "!h-auto !min-h-0 !self-start !p-0 !text-sm !font-medium !text-primary !no-underline hover:!text-primary/80 hover:!no-underline"),
+                cancelButton: cn(buttonVariants({ variant: "link" }), "!h-auto !min-h-0 !self-start !bg-transparent !p-0 !text-sm !font-medium !text-muted-foreground !no-underline hover:!bg-transparent hover:!text-foreground hover:!no-underline"),
+                closeButton: "!absolute !left-auto !right-2 !top-2 !h-6 !w-6 !translate-x-0 !translate-y-0 !rounded-md !border-0 !bg-transparent !text-muted-foreground hover:!bg-accent hover:!text-foreground",
+                success: "border-[hsl(var(--status-success-foreground))]/20 [&_[data-icon]]:text-[hsl(var(--status-success-foreground))]",
+                error: "border-destructive/20 [&_[data-icon]]:text-[hsl(var(--status-destructive-foreground))]",
+                warning: "border-[hsl(var(--status-warning-foreground))]/20 [&_[data-icon]]:text-[hsl(var(--status-warning-foreground))]",
+                info: "border-[hsl(var(--status-info-foreground))]/20 [&_[data-icon]]:text-[hsl(var(--status-info-foreground))]",
             },
         } }));
 }

package/dist/use-error-shake.d.ts

@@ -0,0 +1,7 @@
+export interface UseErrorShakeOptions {
+    durationMs?: number;
+}
+export declare function useErrorShake(options?: UseErrorShakeOptions): {
+    shouldShake: boolean;
+    triggerShake: () => void;
+};

package/dist/use-error-shake.js

@@ -0,0 +1,36 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+const DEFAULT_SHAKE_DURATION_MS = 500;
+export function useErrorShake(options = {}) {
+    const { durationMs = DEFAULT_SHAKE_DURATION_MS } = options;
+    const [shouldShake, setShouldShake] = useState(false);
+    const timeoutRef = useRef(null);
+    const frameRef = useRef(null);
+    const clearPendingAnimation = useCallback(() => {
+        if (timeoutRef.current !== null) {
+            window.clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+        if (frameRef.current !== null) {
+            window.cancelAnimationFrame(frameRef.current);
+            frameRef.current = null;
+        }
+    }, []);
+    const triggerShake = useCallback(() => {
+        clearPendingAnimation();
+        setShouldShake(false);
+        frameRef.current = window.requestAnimationFrame(() => {
+            frameRef.current = null;
+            setShouldShake(true);
+            timeoutRef.current = window.setTimeout(() => {
+                setShouldShake(false);
+                timeoutRef.current = null;
+            }, durationMs);
+        });
+    }, [clearPendingAnimation, durationMs]);
+    useEffect(() => clearPendingAnimation, [clearPendingAnimation]);
+    return {
+        shouldShake,
+        triggerShake,
+    };
+}

package/dist/use-file-upload.d.ts

@@ -0,0 +1,34 @@
+export type FileUploadStatus = "pending" | "uploading" | "complete" | "error";
+export interface FileUploadResult {
+    name: string;
+    size: string;
+    sizeBytes: number;
+    type: string;
+    key: string;
+    url: string;
+}
+export interface FileUploadProgress {
+    name: string;
+    progress: number;
+    status: FileUploadStatus;
+    error?: string;
+    result?: FileUploadResult;
+}
+export interface UseFileUploadOptions {
+    /** Upload endpoint URL. Defaults to `/api/upload`. */
+    endpoint?: string;
+    /** Folder path sent alongside each file as form field `folder`. */
+    folder?: string;
+    /** Additional form fields appended to every request. */
+    extraFields?: Record<string, string>;
+    onComplete?: (results: FileUploadProgress[]) => void;
+    onError?: (error: Error) => void;
+}
+export interface UseFileUploadReturn {
+    uploadProgress: Map<string, FileUploadProgress>;
+    isUploading: boolean;
+    uploadFiles: (files: File[], folder?: string) => Promise<FileUploadProgress[]>;
+    reset: () => void;
+    cancel: () => void;
+}
+export declare function useFileUpload(options?: UseFileUploadOptions): UseFileUploadReturn;

package/dist/use-file-upload.js

@@ -0,0 +1,133 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+export function useFileUpload(options = {}) {
+    const [uploadProgress, setUploadProgress] = useState(new Map());
+    const [isUploading, setIsUploading] = useState(false);
+    const xhrRefs = useRef([]);
+    const updateProgress = useCallback((fileName, updates) => {
+        setUploadProgress((prev) => {
+            var _a;
+            const newMap = new Map(prev);
+            const current = (_a = newMap.get(fileName)) !== null && _a !== void 0 ? _a : {
+                name: fileName,
+                progress: 0,
+                status: "pending",
+            };
+            newMap.set(fileName, { ...current, ...updates });
+            return newMap;
+        });
+    }, []);
+    const uploadSingleFile = useCallback((file, folder) => {
+        var _a;
+        const endpoint = (_a = options.endpoint) !== null && _a !== void 0 ? _a : "/api/upload";
+        const extraFields = options.extraFields;
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhrRefs.current.push(xhr);
+            xhr.upload.onprogress = (event) => {
+                if (event.lengthComputable) {
+                    const progress = Math.round((event.loaded / event.total) * 100);
+                    updateProgress(file.name, { progress, status: "uploading" });
+                }
+            };
+            xhr.onload = () => {
+                var _a;
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    try {
+                        const response = JSON.parse(xhr.responseText);
+                        const uploadedFile = (_a = response.files) === null || _a === void 0 ? void 0 : _a[0];
+                        const result = {
+                            name: file.name,
+                            progress: 100,
+                            status: "complete",
+                            result: uploadedFile,
+                        };
+                        updateProgress(file.name, result);
+                        resolve(result);
+                    }
+                    catch {
+                        const result = {
+                            name: file.name,
+                            progress: 0,
+                            status: "error",
+                            error: "Failed to parse response",
+                        };
+                        updateProgress(file.name, result);
+                        resolve(result);
+                    }
+                }
+                else {
+                    const result = {
+                        name: file.name,
+                        progress: 0,
+                        status: "error",
+                        error: `Upload failed: ${xhr.statusText}`,
+                    };
+                    updateProgress(file.name, result);
+                    resolve(result);
+                }
+            };
+            xhr.onerror = () => {
+                const result = {
+                    name: file.name,
+                    progress: 0,
+                    status: "error",
+                    error: "Network error",
+                };
+                updateProgress(file.name, result);
+                resolve(result);
+            };
+            xhr.onabort = () => {
+                const result = {
+                    name: file.name,
+                    progress: 0,
+                    status: "error",
+                    error: "Upload cancelled",
+                };
+                updateProgress(file.name, result);
+                resolve(result);
+            };
+            const formData = new FormData();
+            formData.append("files", file);
+            formData.append("folder", folder);
+            if (extraFields) {
+                for (const [key, value] of Object.entries(extraFields)) {
+                    formData.append(key, value);
+                }
+            }
+            updateProgress(file.name, { status: "pending", progress: 0 });
+            xhr.open("POST", endpoint);
+            xhr.send(formData);
+        });
+    }, [options.endpoint, options.extraFields, updateProgress]);
+    const uploadFiles = useCallback(async (files, folder) => {
+        var _a, _b, _c;
+        const uploadFolder = (_a = folder !== null && folder !== void 0 ? folder : options.folder) !== null && _a !== void 0 ? _a : "attachments";
+        setIsUploading(true);
+        xhrRefs.current = [];
+        const results = await Promise.all(files.map((file) => uploadSingleFile(file, uploadFolder)));
+        setIsUploading(false);
+        (_b = options.onComplete) === null || _b === void 0 ? void 0 : _b.call(options, results);
+        const errors = results.filter((r) => r.status === "error");
+        if (errors.length > 0) {
+            (_c = options.onError) === null || _c === void 0 ? void 0 : _c.call(options, new Error(`${errors.length} file(s) failed to upload`));
+        }
+        return results;
+    }, [options, uploadSingleFile]);
+    const reset = useCallback(() => {
+        setUploadProgress(new Map());
+        setIsUploading(false);
+    }, []);
+    const cancel = useCallback(() => {
+        xhrRefs.current.forEach((xhr) => xhr.abort());
+        xhrRefs.current = [];
+        setIsUploading(false);
+    }, []);
+    return {
+        uploadProgress,
+        isUploading,
+        uploadFiles,
+        reset,
+        cancel,
+    };
+}

package/dist/use-sticky-sentinel.d.ts

@@ -0,0 +1,16 @@
+import { type RefObject } from "react";
+export interface UseStickySentinelOptions {
+    root?: Element | Document | null;
+    rootMargin?: string;
+    threshold?: number;
+    debounceMs?: number;
+    initialSticky?: boolean;
+    disabled?: boolean;
+    resetOnUnmount?: boolean;
+    onStickyChange?: (isSticky: boolean) => void;
+}
+export interface UseStickySentinelReturn<TElement extends Element> {
+    isSticky: boolean;
+    sentinelRef: RefObject<TElement>;
+}
+export declare function useStickySentinel<TElement extends Element = HTMLDivElement>({ root, rootMargin, threshold, debounceMs, initialSticky, disabled, resetOnUnmount, onStickyChange, }?: UseStickySentinelOptions): UseStickySentinelReturn<TElement>;

package/dist/use-sticky-sentinel.js

@@ -0,0 +1,62 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+export function useStickySentinel({ root = null, rootMargin = "0px", threshold = 0, debounceMs = 0, initialSticky = false, disabled = false, resetOnUnmount = false, onStickyChange, } = {}) {
+    const [isSticky, setIsSticky] = useState(initialSticky);
+    const sentinelRef = useRef(null);
+    const timeoutRef = useRef(null);
+    const lastValueRef = useRef(null);
+    const onStickyChangeRef = useRef(onStickyChange);
+    useEffect(() => {
+        onStickyChangeRef.current = onStickyChange;
+    }, [onStickyChange]);
+    useEffect(() => {
+        if (disabled || typeof IntersectionObserver === "undefined")
+            return;
+        const sentinel = sentinelRef.current;
+        if (!sentinel)
+            return;
+        const clearPendingUpdate = () => {
+            if (timeoutRef.current !== null) {
+                window.clearTimeout(timeoutRef.current);
+                timeoutRef.current = null;
+            }
+        };
+        const commitStickyState = (nextSticky) => {
+            var _a;
+            lastValueRef.current = nextSticky;
+            setIsSticky(nextSticky);
+            (_a = onStickyChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStickyChangeRef, nextSticky);
+        };
+        const scheduleStickyState = (nextSticky) => {
+            if (nextSticky === lastValueRef.current)
+                return;
+            clearPendingUpdate();
+            if (debounceMs > 0) {
+                timeoutRef.current = window.setTimeout(() => {
+                    timeoutRef.current = null;
+                    commitStickyState(nextSticky);
+                }, debounceMs);
+                return;
+            }
+            commitStickyState(nextSticky);
+        };
+        const observer = new IntersectionObserver(([entry]) => scheduleStickyState(!entry.isIntersecting), {
+            root,
+            rootMargin,
+            threshold,
+        });
+        observer.observe(sentinel);
+        return () => {
+            var _a;
+            clearPendingUpdate();
+            observer.disconnect();
+            if (resetOnUnmount) {
+                (_a = onStickyChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStickyChangeRef, false);
+            }
+        };
+    }, [debounceMs, disabled, resetOnUnmount, root, rootMargin, threshold]);
+    return {
+        isSticky,
+        sentinelRef,
+    };
+}

package/dist/use-table-sort.d.ts

@@ -0,0 +1,28 @@
+import type { TableSortDirection, TableSortingProps } from "./table";
+export interface UseTableSortOptions<Field extends string = string> {
+    /** Initial sort field. */
+    defaultField?: Field | null;
+    /** Initial sort direction. */
+    defaultDirection?: TableSortDirection;
+    /**
+     * Toggle cycle when clicking the same column again.
+     * - "asc-desc" (default): asc → desc → asc
+     * - "asc-desc-none": asc → desc → unsorted → asc
+     */
+    cycle?: "asc-desc" | "asc-desc-none";
+    /** Called whenever sort changes — use for server-side query params. */
+    onChange?: (field: Field | null, direction: TableSortDirection) => void;
+}
+export interface UseTableSortReturn<Field extends string = string> {
+    field: Field | null;
+    direction: TableSortDirection;
+    /** Pass directly to `<Table sorting={...} />`. */
+    sorting: TableSortingProps;
+    /** Imperatively set sort (e.g. restore from URL). */
+    setSort: (field: Field | null, direction?: TableSortDirection) => void;
+    /** Reset to the default field/direction. */
+    reset: () => void;
+    /** Client-side helper: returns a sorted copy of rows using the given accessor. */
+    sortRows: <Row>(rows: Row[], accessor: (row: Row, field: Field) => unknown) => Row[];
+}
+export declare function useTableSort<Field extends string = string>({ defaultField, defaultDirection, cycle, onChange, }?: UseTableSortOptions<Field>): UseTableSortReturn<Field>;

package/dist/use-table-sort.js

@@ -0,0 +1,53 @@
+import * as React from "react";
+export function useTableSort({ defaultField = null, defaultDirection = "asc", cycle = "asc-desc", onChange, } = {}) {
+    const [field, setField] = React.useState(defaultField);
+    const [direction, setDirection] = React.useState(defaultDirection);
+    const emit = React.useCallback((nextField, nextDirection) => {
+        setField(nextField);
+        setDirection(nextDirection);
+        onChange === null || onChange === void 0 ? void 0 : onChange(nextField, nextDirection);
+    }, [onChange]);
+    const onSort = React.useCallback((nextField) => {
+        const typed = nextField;
+        if (field !== typed) {
+            emit(typed, "asc");
+            return;
+        }
+        if (direction === "asc") {
+            emit(typed, "desc");
+            return;
+        }
+        if (cycle === "asc-desc-none") {
+            emit(null, "asc");
+            return;
+        }
+        emit(typed, "asc");
+    }, [field, direction, cycle, emit]);
+    const setSort = React.useCallback((nextField, nextDirection = "asc") => {
+        emit(nextField, nextDirection);
+    }, [emit]);
+    const reset = React.useCallback(() => {
+        emit(defaultField, defaultDirection);
+    }, [emit, defaultField, defaultDirection]);
+    const sortRows = React.useCallback((rows, accessor) => {
+        if (!field)
+            return rows;
+        const multiplier = direction === "asc" ? 1 : -1;
+        return [...rows].sort((a, b) => {
+            const av = accessor(a, field);
+            const bv = accessor(b, field);
+            if (av == null && bv == null)
+                return 0;
+            if (av == null)
+                return 1;
+            if (bv == null)
+                return -1;
+            if (typeof av === "number" && typeof bv === "number") {
+                return (av - bv) * multiplier;
+            }
+            return String(av).localeCompare(String(bv)) * multiplier;
+        });
+    }, [field, direction]);
+    const sorting = React.useMemo(() => ({ field, direction, onSort }), [field, direction, onSort]);
+    return { field, direction, sorting, setSort, reset, sortRows };
+}

package/dist/use-viewport-threshold.d.ts

@@ -0,0 +1,12 @@
+import { type RefObject } from "react";
+export interface UseViewportThresholdOptions {
+    collapseAt: number;
+    expandAt?: number;
+    initialPastThreshold?: boolean;
+    disabled?: boolean;
+}
+export interface UseViewportThresholdReturn<TElement extends Element> {
+    isPastThreshold: boolean;
+    sentinelRef: RefObject<TElement>;
+}
+export declare function useViewportThreshold<TElement extends Element = HTMLDivElement>({ collapseAt, expandAt, initialPastThreshold, disabled, }: UseViewportThresholdOptions): UseViewportThresholdReturn<TElement>;

package/dist/use-viewport-threshold.js

@@ -0,0 +1,43 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+export function useViewportThreshold({ collapseAt, expandAt = collapseAt, initialPastThreshold = false, disabled = false, }) {
+    const [isPastThreshold, setIsPastThreshold] = useState(initialPastThreshold);
+    const sentinelRef = useRef(null);
+    useEffect(() => {
+        if (disabled)
+            return;
+        const sentinel = sentinelRef.current;
+        if (!sentinel)
+            return;
+        let frameId = null;
+        const updateThresholdState = () => {
+            frameId = null;
+            const sentinelTop = sentinel.getBoundingClientRect().top;
+            setIsPastThreshold((prev) => {
+                if (prev) {
+                    return sentinelTop <= expandAt;
+                }
+                return sentinelTop <= collapseAt;
+            });
+        };
+        const requestUpdate = () => {
+            if (frameId !== null)
+                return;
+            frameId = window.requestAnimationFrame(updateThresholdState);
+        };
+        requestUpdate();
+        window.addEventListener("scroll", requestUpdate, { passive: true });
+        window.addEventListener("resize", requestUpdate);
+        return () => {
+            if (frameId !== null) {
+                window.cancelAnimationFrame(frameId);
+            }
+            window.removeEventListener("scroll", requestUpdate);
+            window.removeEventListener("resize", requestUpdate);
+        };
+    }, [collapseAt, disabled, expandAt]);
+    return {
+        isPastThreshold,
+        sentinelRef,
+    };
+}