@papernote/ui 1.2.0 → 1.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
 'use strict';
 
 var jsxRuntime = require('react/jsx-runtime');
-var lucideReact = require('lucide-react');
 var React = require('react');
+var lucideReact = require('lucide-react');
 var reactDom = require('react-dom');
 var reactRouterDom = require('react-router-dom');
 
@@ -31,6 +31,8 @@ var React__namespace = /*#__PURE__*/_interopNamespaceDefault(React);
  * A versatile button component that supports multiple visual styles, sizes, icons,
  * loading states, and notification badges.
  *
+ * Supports ref forwarding for DOM access.
+ *
  * @example Basic usage
  * ```tsx
  * <Button variant="primary">Click me</Button>
@@ -57,8 +59,14 @@ var React__namespace = /*#__PURE__*/_interopNamespaceDefault(React);
  *   <Bell />
  * </Button>
  * ```
+ *
+ * @example With ref
+ * ```tsx
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * <Button ref={buttonRef}>Focusable</Button>
+ * ```
  */
-function Button({ variant = 'primary', size = 'md', loading = false, icon, iconPosition = 'left', fullWidth = false, iconOnly = false, badge, badgeVariant = 'error', children, disabled, className = '', ...props }) {
+const Button = React.forwardRef(({ variant = 'primary', size = 'md', loading = false, icon, iconPosition = 'left', fullWidth = false, iconOnly = false, badge, badgeVariant = 'error', children, disabled, className = '', ...props }, ref) => {
     const baseStyles = 'inline-flex items-center justify-center font-medium rounded-lg border transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-accent-400 disabled:opacity-40 disabled:cursor-not-allowed';
     const variantStyles = {
         primary: 'bg-accent-500 text-white border-accent-500 hover:bg-accent-600 hover:shadow-sm active:scale-[0.98]',
@@ -89,7 +97,7 @@ function Button({ variant = 'primary', size = 'md', loading = false, icon, iconP
         md: 'min-w-[18px] h-[18px] text-[11px] px-1.5',
         lg: 'min-w-[20px] h-5 text-xs px-1.5',
     };
-    const buttonElement = (jsxRuntime.jsxs("button", { className: `
+    const buttonElement = (jsxRuntime.jsxs("button", { ref: ref, className: `
         ${baseStyles}
         ${variantStyles[variant]}
         ${sizeStyles[size]}
@@ -112,7 +120,8 @@ function Button({ variant = 'primary', size = 'md', loading = false, icon, iconP
           shadow-sm
           pointer-events-none
         `, "aria-label": `${badgeContent} notifications`, children: badgeContent })] }));
-}
+});
+Button.displayName = 'Button';
 
 /**
  * ButtonGroup component - Toggle button group for single or multiple selection.
@@ -259,7 +268,7 @@ function ButtonGroup({ options, value, values = [], onChange, onChangeMultiple,
  * />
  * ```
  */
-const Input = React.forwardRef(({ label, helperText, validationState, validationMessage, icon, iconPosition = 'left', showCount = false, prefix, suffix, prefixIcon, suffixIcon, showPasswordToggle = false, clearable = false, onClear, className = '', id, type = 'text', value, maxLength, ...props }, ref) => {
+const Input = React.forwardRef(({ label, helperText, validationState, validationMessage, icon, iconPosition = 'left', showCount = false, prefix, suffix, prefixIcon, suffixIcon, showPasswordToggle = false, clearable = false, onClear, loading = false, className = '', id, type = 'text', value, maxLength, ...props }, ref) => {
     const inputId = id || `input-${Math.random().toString(36).substring(2, 9)}`;
     const [showPassword, setShowPassword] = React.useState(false);
     // Handle clear button click
@@ -331,7 +340,7 @@ const Input = React.forwardRef(({ label, helperText, validationState, validation
               ${validationState && !suffix && !suffixIcon && !showPasswordToggle ? 'pr-10' : ''}
               ${(showPasswordToggle && type === 'password') || validationState || suffix || suffixIcon ? 'pr-20' : ''}
               ${className}
-            `, ...props }), suffix && (jsxRuntime.jsx("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center pointer-events-none text-ink-500 text-sm", children: suffix })), jsxRuntime.jsxs("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center gap-2", children: [suffixIcon && !suffix && !validationState && !showPasswordToggle && !showClearButton && (jsxRuntime.jsx("div", { className: "pointer-events-none text-ink-400", children: suffixIcon })), showClearButton && (jsxRuntime.jsx("button", { type: "button", onClick: handleClear, className: "text-ink-400 hover:text-ink-600 focus:outline-none cursor-pointer pointer-events-auto", "aria-label": "Clear input", children: jsxRuntime.jsx(lucideReact.X, { className: "h-4 w-4" }) })), type === 'password' && showPasswordToggle && (jsxRuntime.jsx("button", { type: "button", onClick: () => setShowPassword(!showPassword), className: "text-ink-400 hover:text-ink-600 focus:outline-none cursor-pointer pointer-events-auto", "aria-label": showPassword ? 'Hide password' : 'Show password', children: showPassword ? jsxRuntime.jsx(lucideReact.EyeOff, { className: "h-5 w-5" }) : jsxRuntime.jsx(lucideReact.Eye, { className: "h-5 w-5" }) })), validationState && (jsxRuntime.jsx("div", { className: "pointer-events-none", children: getValidationIcon() })), icon && iconPosition === 'right' && !suffix && !suffixIcon && !validationState && (jsxRuntime.jsx("div", { className: "pointer-events-none text-ink-400", children: icon }))] })] }), jsxRuntime.jsxs("div", { className: "flex justify-between items-center mt-2", children: [(helperText || validationMessage) && (jsxRuntime.jsx("p", { className: `text-xs ${validationMessage ? getValidationMessageColor() : 'text-ink-600'}`, children: validationMessage || helperText })), showCounter && (jsxRuntime.jsxs("p", { className: `text-xs ml-auto ${currentLength > maxLength ? 'text-error-600' : 'text-ink-500'}`, children: [currentLength, " / ", maxLength] }))] })] }));
+            `, ...props }), suffix && (jsxRuntime.jsx("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center pointer-events-none text-ink-500 text-sm", children: suffix })), jsxRuntime.jsxs("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center gap-2", children: [loading && (jsxRuntime.jsx("div", { className: "pointer-events-none text-ink-400", children: jsxRuntime.jsx(lucideReact.Loader2, { className: "h-5 w-5 animate-spin" }) })), suffixIcon && !suffix && !validationState && !showPasswordToggle && !showClearButton && !loading && (jsxRuntime.jsx("div", { className: "pointer-events-none text-ink-400", children: suffixIcon })), showClearButton && (jsxRuntime.jsx("button", { type: "button", onClick: handleClear, className: "text-ink-400 hover:text-ink-600 focus:outline-none cursor-pointer pointer-events-auto", "aria-label": "Clear input", children: jsxRuntime.jsx(lucideReact.X, { className: "h-4 w-4" }) })), type === 'password' && showPasswordToggle && (jsxRuntime.jsx("button", { type: "button", onClick: () => setShowPassword(!showPassword), className: "text-ink-400 hover:text-ink-600 focus:outline-none cursor-pointer pointer-events-auto", "aria-label": showPassword ? 'Hide password' : 'Show password', children: showPassword ? jsxRuntime.jsx(lucideReact.EyeOff, { className: "h-5 w-5" }) : jsxRuntime.jsx(lucideReact.Eye, { className: "h-5 w-5" }) })), validationState && (jsxRuntime.jsx("div", { className: "pointer-events-none", children: getValidationIcon() })), icon && iconPosition === 'right' && !suffix && !suffixIcon && !validationState && (jsxRuntime.jsx("div", { className: "pointer-events-none text-ink-400", children: icon }))] })] }), jsxRuntime.jsxs("div", { className: "flex justify-between items-center mt-2", children: [(helperText || validationMessage) && (jsxRuntime.jsx("p", { className: `text-xs ${validationMessage ? getValidationMessageColor() : 'text-ink-600'}`, children: validationMessage || helperText })), showCounter && (jsxRuntime.jsxs("p", { className: `text-xs ml-auto ${currentLength > maxLength ? 'text-error-600' : 'text-ink-500'}`, children: [currentLength, " / ", maxLength] }))] })] }));
 });
 Input.displayName = 'Input';
 
@@ -538,11 +547,18 @@ const Select = React.forwardRef((props, ref) => {
 });
 Select.displayName = 'Select';
 
-function MultiSelect({ options, value = [], onChange, placeholder = 'Select options', searchable = false, disabled = false, label, helperText, error, maxHeight = 240, maxSelections, 'aria-label': ariaLabel, }) {
+const MultiSelect = React.forwardRef(({ options, value = [], onChange, placeholder = 'Select options', searchable = false, disabled = false, label, helperText, error, maxHeight = 240, maxSelections, loading = false, 'aria-label': ariaLabel, }, ref) => {
     const [isOpen, setIsOpen] = React.useState(false);
     const [searchQuery, setSearchQuery] = React.useState('');
     const selectRef = React.useRef(null);
     const searchInputRef = React.useRef(null);
+    const triggerRef = React.useRef(null);
+    // Expose imperative methods
+    React.useImperativeHandle(ref, () => ({
+        focus: () => triggerRef.current?.focus(),
+        open: () => !disabled && setIsOpen(true),
+        close: () => setIsOpen(false),
+    }));
     const selectedOptions = options.filter(opt => value.includes(opt.value));
     const hasReachedMax = maxSelections ? value.length >= maxSelections : false;
     const filteredOptions = searchable && searchQuery
@@ -589,11 +605,11 @@ function MultiSelect({ options, value = [], onChange, placeholder = 'Select opti
         e.stopPropagation();
         onChange?.([]);
     };
-    return (jsxRuntime.jsxs("div", { className: "w-full", children: [label && (jsxRuntime.jsx("label", { className: "label", children: label })), jsxRuntime.jsxs("div", { ref: selectRef, className: "relative", children: [jsxRuntime.jsxs("button", { type: "button", onClick: () => !disabled && setIsOpen(!isOpen), disabled: disabled, className: `
+    return (jsxRuntime.jsxs("div", { className: "w-full", children: [label && (jsxRuntime.jsx("label", { className: "label", children: label })), jsxRuntime.jsxs("div", { ref: selectRef, className: "relative", children: [jsxRuntime.jsxs("button", { ref: triggerRef, type: "button", onClick: () => !disabled && !loading && setIsOpen(!isOpen), disabled: disabled || loading, className: `
             input w-full flex items-center justify-between min-h-[42px]
             ${error ? 'border-error-400 focus:border-error-400 focus:ring-error-400' : ''}
-            ${disabled ? 'opacity-40 cursor-not-allowed' : 'cursor-pointer'}
-          `, "aria-haspopup": "listbox", "aria-expanded": isOpen, "aria-label": ariaLabel || label, children: [jsxRuntime.jsx("div", { className: "flex-1 flex items-center gap-2 flex-wrap", children: selectedOptions.length === 0 ? (jsxRuntime.jsx("span", { className: "text-ink-400", children: placeholder })) : (selectedOptions.map((option) => (jsxRuntime.jsxs("span", { className: "inline-flex items-center gap-1 px-2 py-1 bg-accent-100 text-accent-800 rounded text-sm", children: [option.icon && jsxRuntime.jsx("span", { className: "text-xs", children: option.icon }), option.label, jsxRuntime.jsx("button", { type: "button", onClick: (e) => handleRemove(option.value, e), className: "hover:text-accent-900", "aria-label": `Remove ${option.label}`, children: jsxRuntime.jsx(lucideReact.X, { className: "h-3 w-3" }) })] }, option.value)))) }), jsxRuntime.jsxs("div", { className: "flex items-center gap-2 ml-2", children: [selectedOptions.length > 0 && !disabled && (jsxRuntime.jsx("button", { type: "button", onClick: handleClearAll, className: "text-ink-400 hover:text-ink-600", "aria-label": "Clear all", children: jsxRuntime.jsx(lucideReact.X, { className: "h-4 w-4" }) })), jsxRuntime.jsx(lucideReact.ChevronDown, { className: `h-4 w-4 text-ink-500 transition-transform ${isOpen ? 'rotate-180' : ''}` })] })] }), isOpen && (jsxRuntime.jsxs("div", { className: "absolute z-50 w-full mt-2 bg-white bg-subtle-grain rounded-lg shadow-lg border border-paper-200 overflow-hidden animate-fade-in", style: { maxHeight: `${maxHeight}px` }, children: [searchable && (jsxRuntime.jsx("div", { className: "p-2 border-b border-paper-200", children: jsxRuntime.jsxs("div", { className: "relative", children: [jsxRuntime.jsx(lucideReact.Search, { className: "absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-ink-400" }), jsxRuntime.jsx("input", { ref: searchInputRef, type: "text", value: searchQuery, onChange: (e) => setSearchQuery(e.target.value), placeholder: "Search...", className: "w-full pl-9 pr-3 py-2 text-sm border border-paper-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-accent-400 focus:border-accent-400" })] }) })), jsxRuntime.jsx("div", { className: "overflow-y-auto", style: { maxHeight: `${maxHeight - 60}px` }, role: "listbox", "aria-multiselectable": "true", children: filteredOptions.length === 0 ? (jsxRuntime.jsx("div", { className: "px-4 py-3 text-sm text-ink-500 text-center", children: "No options found" })) : (filteredOptions.map((option) => {
+            ${disabled || loading ? 'opacity-40 cursor-not-allowed' : 'cursor-pointer'}
+          `, "aria-haspopup": "listbox", "aria-expanded": isOpen, "aria-label": ariaLabel || label, children: [jsxRuntime.jsx("div", { className: "flex-1 flex items-center gap-2 flex-wrap", children: selectedOptions.length === 0 ? (jsxRuntime.jsx("span", { className: "text-ink-400", children: placeholder })) : (selectedOptions.map((option) => (jsxRuntime.jsxs("span", { className: "inline-flex items-center gap-1 px-2 py-1 bg-accent-100 text-accent-800 rounded text-sm", children: [option.icon && jsxRuntime.jsx("span", { className: "text-xs", children: option.icon }), option.label, jsxRuntime.jsx("button", { type: "button", onClick: (e) => handleRemove(option.value, e), className: "hover:text-accent-900", "aria-label": `Remove ${option.label}`, children: jsxRuntime.jsx(lucideReact.X, { className: "h-3 w-3" }) })] }, option.value)))) }), jsxRuntime.jsxs("div", { className: "flex items-center gap-2 ml-2", children: [loading && (jsxRuntime.jsx(lucideReact.Loader2, { className: "h-4 w-4 text-ink-400 animate-spin" })), !loading && selectedOptions.length > 0 && !disabled && (jsxRuntime.jsx("button", { type: "button", onClick: handleClearAll, className: "text-ink-400 hover:text-ink-600", "aria-label": "Clear all", children: jsxRuntime.jsx(lucideReact.X, { className: "h-4 w-4" }) })), !loading && (jsxRuntime.jsx(lucideReact.ChevronDown, { className: `h-4 w-4 text-ink-500 transition-transform ${isOpen ? 'rotate-180' : ''}` }))] })] }), isOpen && (jsxRuntime.jsxs("div", { className: "absolute z-50 w-full mt-2 bg-white bg-subtle-grain rounded-lg shadow-lg border border-paper-200 overflow-hidden animate-fade-in", style: { maxHeight: `${maxHeight}px` }, children: [searchable && (jsxRuntime.jsx("div", { className: "p-2 border-b border-paper-200", children: jsxRuntime.jsxs("div", { className: "relative", children: [jsxRuntime.jsx(lucideReact.Search, { className: "absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-ink-400" }), jsxRuntime.jsx("input", { ref: searchInputRef, type: "text", value: searchQuery, onChange: (e) => setSearchQuery(e.target.value), placeholder: "Search...", className: "w-full pl-9 pr-3 py-2 text-sm border border-paper-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-accent-400 focus:border-accent-400" })] }) })), jsxRuntime.jsx("div", { className: "overflow-y-auto", style: { maxHeight: `${maxHeight - 60}px` }, role: "listbox", "aria-multiselectable": "true", children: filteredOptions.length === 0 ? (jsxRuntime.jsx("div", { className: "px-4 py-3 text-sm text-ink-500 text-center", children: "No options found" })) : (filteredOptions.map((option) => {
                                     const isSelected = value.includes(option.value);
                                     const isDisabled = option.disabled || (hasReachedMax && !isSelected);
                                     return (jsxRuntime.jsx("button", { type: "button", onClick: () => !isDisabled && handleToggle(option.value), disabled: isDisabled, className: `
@@ -605,7 +621,8 @@ function MultiSelect({ options, value = [], onChange, placeholder = 'Select opti
                           ${isSelected ? 'bg-accent-600 border-accent-600' : 'border-paper-300'}
                         `, children: isSelected && jsxRuntime.jsx(lucideReact.Check, { className: "h-3 w-3 text-white" }) }), option.icon && jsxRuntime.jsx("span", { children: option.icon }), option.label] }) }, option.value));
                                 })) })] }))] }), jsxRuntime.jsxs("div", { className: "flex justify-between items-center mt-2", children: [(helperText || error) && (jsxRuntime.jsx("p", { className: `text-xs ${error ? 'text-error-600' : 'text-ink-600'}`, children: error || helperText })), maxSelections && (jsxRuntime.jsxs("p", { className: `text-xs ml-auto ${hasReachedMax ? 'text-warning-600 font-medium' : 'text-ink-500'}`, children: [value.length, " / ", maxSelections, " selected"] }))] })] }));
-}
+});
+MultiSelect.displayName = 'MultiSelect';
 
 const Switch = React.forwardRef(({ checked, onChange, label, description, disabled = false, size = 'md', loading = false, }, ref) => {
     // Generate unique IDs for ARIA
@@ -652,7 +669,7 @@ const Switch = React.forwardRef(({ checked, onChange, label, description, disabl
 });
 Switch.displayName = 'Switch';
 
-const Textarea = React.forwardRef(({ label, helperText, validationState, validationMessage, maxLength, showCharCount = false, autoExpand = false, minRows = 2, maxRows = 10, resize = 'vertical', className = '', id, value, rows = 4, ...props }, ref) => {
+const Textarea = React.forwardRef(({ label, helperText, validationState, validationMessage, maxLength, showCharCount = false, autoExpand = false, minRows = 2, maxRows = 10, resize = 'vertical', loading = false, className = '', id, value, rows = 4, ...props }, ref) => {
     const textareaId = id || `textarea-${Math.random().toString(36).substring(2, 9)}`;
     const currentLength = typeof value === 'string' ? value.length : 0;
     const internalRef = React.useRef(null);
@@ -727,14 +744,15 @@ const Textarea = React.forwardRef(({ label, helperText, validationState, validat
                 return 'text-ink-600';
         }
     };
-    return (jsxRuntime.jsxs("div", { className: "w-full", children: [label && (jsxRuntime.jsxs("label", { htmlFor: textareaId, className: "label", children: [label, props.required && jsxRuntime.jsx("span", { className: "text-error-500 ml-1", children: "*" })] })), jsxRuntime.jsx("textarea", { ref: textareaRef, id: textareaId, value: value, maxLength: maxLength, rows: autoExpand ? minRows : rows, className: `
-            block w-full px-4 py-3 border rounded-lg text-sm text-ink-800 placeholder-ink-400
-            bg-white bg-subtle-grain transition-all duration-200
-            focus:outline-none focus:ring-2 ${getResizeClass()}
-            disabled:bg-paper-100 disabled:text-ink-400 disabled:cursor-not-allowed disabled:opacity-60
-            ${getValidationClasses()}
-            ${className}
-          `, "aria-invalid": validationState === 'error', "aria-describedby": validationMessage || helperText ? `${textareaId}-help` : undefined, "aria-required": props.required, ...props }), ((helperText || validationMessage) || (showCharCount && maxLength)) && (jsxRuntime.jsxs("div", { className: "mt-2 flex items-center justify-between", children: [jsxRuntime.jsxs("div", { className: "flex items-center gap-2", children: [validationState && getValidationIcon(), (helperText || validationMessage) && (jsxRuntime.jsx("p", { id: `${textareaId}-help`, className: `text-xs ${validationMessage ? getValidationMessageColor() : 'text-ink-600'}`, children: validationMessage || helperText }))] }), showCharCount && maxLength && (jsxRuntime.jsxs("p", { className: `text-xs ${currentLength >= maxLength ? 'text-error-600' : 'text-ink-500'}`, children: [currentLength, " / ", maxLength] }))] }))] }));
+    return (jsxRuntime.jsxs("div", { className: "w-full", children: [label && (jsxRuntime.jsxs("label", { htmlFor: textareaId, className: "label", children: [label, props.required && jsxRuntime.jsx("span", { className: "text-error-500 ml-1", children: "*" })] })), jsxRuntime.jsxs("div", { className: "relative", children: [jsxRuntime.jsx("textarea", { ref: textareaRef, id: textareaId, value: value, maxLength: maxLength, rows: autoExpand ? minRows : rows, className: `
+              block w-full px-4 py-3 border rounded-lg text-sm text-ink-800 placeholder-ink-400
+              bg-white bg-subtle-grain transition-all duration-200
+              focus:outline-none focus:ring-2 ${getResizeClass()}
+              disabled:bg-paper-100 disabled:text-ink-400 disabled:cursor-not-allowed disabled:opacity-60
+              ${getValidationClasses()}
+              ${loading ? 'pr-10' : ''}
+              ${className}
+            `, "aria-invalid": validationState === 'error', "aria-describedby": validationMessage || helperText ? `${textareaId}-help` : undefined, "aria-required": props.required, ...props }), loading && (jsxRuntime.jsx("div", { className: "absolute top-3 right-3 pointer-events-none", children: jsxRuntime.jsx(lucideReact.Loader2, { className: "h-5 w-5 text-ink-400 animate-spin" }) }))] }), ((helperText || validationMessage) || (showCharCount && maxLength)) && (jsxRuntime.jsxs("div", { className: "mt-2 flex items-center justify-between", children: [jsxRuntime.jsxs("div", { className: "flex items-center gap-2", children: [validationState && getValidationIcon(), (helperText || validationMessage) && (jsxRuntime.jsx("p", { id: `${textareaId}-help`, className: `text-xs ${validationMessage ? getValidationMessageColor() : 'text-ink-600'}`, children: validationMessage || helperText }))] }), showCharCount && maxLength && (jsxRuntime.jsxs("p", { className: `text-xs ${currentLength >= maxLength ? 'text-error-600' : 'text-ink-500'}`, children: [currentLength, " / ", maxLength] }))] }))] }));
 });
 Textarea.displayName = 'Textarea';
 
@@ -1950,6 +1968,8 @@ function SkeletonTable({ rows = 5, columns = 4 }) {
 /**
  * Card - Container component with paper aesthetic and subtle shadow
  *
+ * Supports ref forwarding for DOM access.
+ *
  * A content container with paper texture, border, and shadow effects. Supports
  * different sizes, variants (padding/shadow levels), and loading states.
  *
@@ -1979,8 +1999,14 @@ function SkeletonTable({ rows = 5, columns = 4 }) {
  *   <p>Content</p>
  * </Card>
  * ```
+ *
+ * @example With ref
+ * ```tsx
+ * const cardRef = useRef<HTMLDivElement>(null);
+ * <Card ref={cardRef}>Content</Card>
+ * ```
  */
-function Card({ children, variant = 'default', width = 'auto', className = '', onClick, hoverable = false, loading = false, }) {
+const Card = React.forwardRef(({ children, variant = 'default', width = 'auto', className = '', onClick, hoverable = false, loading = false, ...htmlProps }, ref) => {
     const baseStyles = 'bg-white bg-subtle-grain border-2 border-paper-300 transition-shadow duration-200';
     const variantStyles = {
         default: 'rounded-xl shadow-lg p-8',
@@ -1996,8 +2022,9 @@ function Card({ children, variant = 'default', width = 'auto', className = '', o
         full: 'w-full',
     };
     const interactiveStyles = onClick || hoverable ? 'cursor-pointer hover:shadow-md' : '';
-    return (jsxRuntime.jsx("div", { className: `${baseStyles} ${variantStyles[variant]} ${widthStyles[width]} ${interactiveStyles} ${className}`, onClick: !loading ? onClick : undefined, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, children: loading ? (jsxRuntime.jsxs("div", { className: "space-y-4", children: [jsxRuntime.jsx(Skeleton, { className: "h-6 w-3/4" }), jsxRuntime.jsx(Skeleton, { className: "h-4 w-full" }), jsxRuntime.jsx(Skeleton, { className: "h-4 w-5/6" }), jsxRuntime.jsx(Skeleton, { className: "h-4 w-4/6" })] })) : (children) }));
-}
+    return (jsxRuntime.jsx("div", { ref: ref, ...htmlProps, className: `${baseStyles} ${variantStyles[variant]} ${widthStyles[width]} ${interactiveStyles} ${className}`, onClick: !loading ? onClick : undefined, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, children: loading ? (jsxRuntime.jsxs("div", { className: "space-y-4", children: [jsxRuntime.jsx(Skeleton, { className: "h-6 w-3/4" }), jsxRuntime.jsx(Skeleton, { className: "h-4 w-full" }), jsxRuntime.jsx(Skeleton, { className: "h-4 w-5/6" }), jsxRuntime.jsx(Skeleton, { className: "h-4 w-4/6" })] })) : (children) }));
+});
+Card.displayName = 'Card';
 /**
  * CardHeader - Header section for Card component
  *
@@ -2095,15 +2122,34 @@ function Separator({ orientation = 'horizontal', className = '', spacing = 'md',
 /**
  * Stack component for arranging children vertically or horizontally with consistent spacing.
  *
- * Spacing scale:
+ * Supports ref forwarding for DOM access.
+ *
+ * Spacing scale (use either `spacing` or `gap` prop - they're aliases):
  * - none: 0
  * - xs: 0.5rem (2)
  * - sm: 0.75rem (3)
  * - md: 1.5rem (6)
  * - lg: 2rem (8)
  * - xl: 3rem (12)
+ *
+ * @example
+ * ```tsx
+ * // Using spacing prop
+ * <Stack spacing="md">
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ * </Stack>
+ *
+ * // Using gap prop (alias)
+ * <Stack gap="md">
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ * </Stack>
+ * ```
  */
-const Stack = ({ children, direction = 'vertical', spacing = 'md', align = 'stretch', justify = 'start', wrap = false, className = '', }) => {
+const Stack = React.forwardRef(({ children, direction = 'vertical', spacing, gap, align = 'stretch', justify = 'start', wrap = false, className = '', ...htmlProps }, ref) => {
+    // Use gap as alias for spacing (spacing takes precedence if both provided)
+    const effectiveSpacing = spacing ?? gap ?? 'md';
     const spacingClasses = {
         vertical: {
             none: '',
@@ -2135,20 +2181,23 @@ const Stack = ({ children, direction = 'vertical', spacing = 'md', align = 'stre
         between: 'justify-between',
         around: 'justify-around',
     };
-    return (jsxRuntime.jsx("div", { className: `
+    return (jsxRuntime.jsx("div", { ref: ref, ...htmlProps, className: `
         flex
         ${direction === 'vertical' ? 'flex-col' : 'flex-row'}
         ${wrap ? 'flex-wrap' : ''}
-        ${spacingClasses[direction][spacing]}
+        ${spacingClasses[direction][effectiveSpacing]}
         ${alignClasses[align]}
         ${justifyClasses[justify]}
         ${className}
       `, children: children }));
-};
+});
+Stack.displayName = 'Stack';
 
 /**
  * Grid component for arranging children in a CSS grid layout.
  *
+ * Supports ref forwarding for DOM access.
+ *
  * Column options: 1, 2, 3, 4, 6, 12
  *
  * Responsive breakpoints (mobile-first):
@@ -2173,7 +2222,7 @@ const Stack = ({ children, direction = 'vertical', spacing = 'md', align = 'stre
  *   <Card>Item 2</Card>
  * </Grid>
  */
-const Grid = ({ children, columns = 1, sm, md, lg, xl, gap = 'md', className = '', }) => {
+const Grid = React.forwardRef(({ children, columns = 1, sm, md, lg, xl, gap = 'md', className = '', ...htmlProps }, ref) => {
     // Base column classes
     const baseColumnClasses = {
         1: 'grid-cols-1',
@@ -2232,18 +2281,20 @@ const Grid = ({ children, columns = 1, sm, md, lg, xl, gap = 'md', className = '
         lg ? lgColumnClasses[lg] : '',
         xl ? xlColumnClasses[xl] : '',
     ].filter(Boolean).join(' ');
-    return (jsxRuntime.jsx("div", { className: `
+    return (jsxRuntime.jsx("div", { ref: ref, ...htmlProps, className: `
         grid
         ${columnClassList}
         ${gapClasses[gap]}
         ${className}
       `, children: children }));
-};
+});
+Grid.displayName = 'Grid';
 
 /**
  * Box component for generic containers with design system spacing and borders.
+ * Supports ref forwarding for DOM access.
  */
-const Box = ({ children, padding, paddingTop, paddingBottom, paddingLeft, paddingRight, margin, marginTop, marginBottom, marginLeft, marginRight, border = 'none', borderColor = 'default', rounded, width, height, className = '', ...htmlProps }) => {
+const Box = React.forwardRef(({ children, padding, paddingTop, paddingBottom, paddingLeft, paddingRight, margin, marginTop, marginBottom, marginLeft, marginRight, border = 'none', borderColor = 'default', rounded, width, height, className = '', ...htmlProps }, ref) => {
     const spacingMap = {
         none: '0',
         xs: '2',
@@ -2328,7 +2379,7 @@ const Box = ({ children, padding, paddingTop, paddingBottom, paddingLeft, paddin
         };
         return roundedClasses[rounded];
     };
-    return (jsxRuntime.jsx("div", { ...htmlProps, className: `
+    return (jsxRuntime.jsx("div", { ref: ref, ...htmlProps, className: `
         ${getPaddingClass()}
         ${getMarginClass()}
         ${borderClasses[border]}
@@ -2338,7 +2389,8 @@ const Box = ({ children, padding, paddingTop, paddingBottom, paddingLeft, paddin
         ${getHeightClass()}
         ${className}
       `, children: children }));
-};
+});
+Box.displayName = 'Box';
 
 /**
  * GridItem component for items within a Grid layout.
@@ -2383,6 +2435,8 @@ const GridItem = ({ colSpan, rowSpan, children, className = '', ...boxProps }) =
 /**
  * Text component for consistent typography across the application.
  *
+ * Supports ref forwarding for DOM access.
+ *
  * Size scale:
  * - xs: 0.75rem (12px)
  * - sm: 0.875rem (14px)
@@ -2390,8 +2444,21 @@ const GridItem = ({ colSpan, rowSpan, children, className = '', ...boxProps }) =
  * - lg: 1.125rem (18px)
  * - xl: 1.25rem (20px)
  * - 2xl: 1.5rem (24px)
+ *
+ * @example
+ * ```tsx
+ * <Text size="lg" weight="semibold" color="primary">
+ *   Hello World
+ * </Text>
+ *
+ * <Text color="warning">Warning message</Text>
+ *
+ * // With ref
+ * const textRef = useRef<HTMLParagraphElement>(null);
+ * <Text ref={textRef}>Measurable text</Text>
+ * ```
  */
-const Text = ({ children, as: Component = 'p', size = 'base', weight = 'normal', color = 'primary', align = 'left', truncate = false, lineClamp, transform, className = '', }) => {
+const Text = React.forwardRef(({ children, as: Component = 'p', size = 'base', weight = 'normal', color = 'primary', align = 'left', truncate = false, lineClamp, transform, className = '', ...htmlProps }, ref) => {
     const sizeClasses = {
         xs: 'text-xs',
         sm: 'text-sm',
@@ -2413,6 +2480,7 @@ const Text = ({ children, as: Component = 'p', size = 'base', weight = 'normal',
         accent: 'text-primary-600',
         error: 'text-error-600',
         success: 'text-success-600',
+        warning: 'text-warning-600',
     };
     const alignClasses = {
         left: 'text-left',
@@ -2444,8 +2512,9 @@ const Text = ({ children, as: Component = 'p', size = 'base', weight = 'normal',
         lineClamp ? lineClampClasses[lineClamp] : '',
         className,
     ].filter(Boolean).join(' ');
-    return (jsxRuntime.jsx(Component, { className: classes, children: children }));
-};
+    return (jsxRuntime.jsx(Component, { ref: ref, className: classes, ...htmlProps, children: children }));
+});
+Text.displayName = 'Text';
 
 const toastStyles = {
     success: {
@@ -6088,99 +6157,6 @@ function StepIndicator({ steps, currentStep, variant = 'horizontal', onStepClick
             }) }) }));
 }
 
-function Table$1({ data, columns, keyExtractor, selectable = false, expandable = false, onRowSelect, renderExpandedRow, emptyState, className = '', onSort, sortColumn: externalSortColumn, sortDirection: externalSortDirection, }) {
-    const [internalSortColumn, setInternalSortColumn] = React.useState(null);
-    const [internalSortDirection, setInternalSortDirection] = React.useState(null);
-    // Use external sort state if provided, otherwise use internal state
-    const sortColumn = externalSortColumn !== undefined ? externalSortColumn : internalSortColumn;
-    const sortDirection = externalSortDirection !== undefined ? externalSortDirection : internalSortDirection;
-    const [selectedRows, setSelectedRows] = React.useState(new Set());
-    const [expandedRows, setExpandedRows] = React.useState(new Set());
-    // Handle sorting
-    const handleSort = (columnKey) => {
-        let newDirection;
-        if (sortColumn === columnKey) {
-            if (sortDirection === 'asc') {
-                newDirection = 'desc';
-            }
-            else if (sortDirection === 'desc') {
-                newDirection = null;
-            }
-            else {
-                newDirection = 'asc';
-            }
-        }
-        else {
-            newDirection = 'asc';
-        }
-        // If using external sort control, call the callback
-        if (onSort) {
-            onSort(columnKey, newDirection);
-        }
-        else {
-            // Otherwise update internal state
-            setInternalSortColumn(newDirection === null ? null : columnKey);
-            setInternalSortDirection(newDirection);
-        }
-    };
-    // Handle row selection
-    const handleRowSelect = (rowKey) => {
-        const newSelected = new Set(selectedRows);
-        if (newSelected.has(rowKey)) {
-            newSelected.delete(rowKey);
-        }
-        else {
-            newSelected.add(rowKey);
-        }
-        setSelectedRows(newSelected);
-        onRowSelect?.(Array.from(newSelected));
-    };
-    // Handle select all
-    const handleSelectAll = () => {
-        if (selectedRows.size === data.length) {
-            setSelectedRows(new Set());
-            onRowSelect?.([]);
-        }
-        else {
-            const allKeys = new Set(data.map(keyExtractor));
-            setSelectedRows(allKeys);
-            onRowSelect?.(Array.from(allKeys));
-        }
-    };
-    // Handle row expansion
-    const handleRowExpand = (rowKey) => {
-        const newExpanded = new Set(expandedRows);
-        if (newExpanded.has(rowKey)) {
-            newExpanded.delete(rowKey);
-        }
-        else {
-            newExpanded.add(rowKey);
-        }
-        setExpandedRows(newExpanded);
-    };
-    const getSortIcon = (columnKey) => {
-        if (sortColumn !== columnKey) {
-            return jsxRuntime.jsx(lucideReact.ArrowUpDown, { className: "h-4 w-4 text-ink-400" });
-        }
-        if (sortDirection === 'asc') {
-            return jsxRuntime.jsx(lucideReact.ArrowUp, { className: "h-4 w-4 text-accent-600" });
-        }
-        if (sortDirection === 'desc') {
-            return jsxRuntime.jsx(lucideReact.ArrowDown, { className: "h-4 w-4 text-accent-600" });
-        }
-        return jsxRuntime.jsx(lucideReact.ArrowUpDown, { className: "h-4 w-4 text-ink-400" });
-    };
-    if (data.length === 0 && emptyState) {
-        return jsxRuntime.jsx("div", { children: emptyState });
-    }
-    return (jsxRuntime.jsx("div", { className: `overflow-x-auto ${className}`, children: jsxRuntime.jsxs("table", { className: "table", children: [jsxRuntime.jsx("thead", { className: "table-header", children: jsxRuntime.jsxs("tr", { children: [selectable && (jsxRuntime.jsx("th", { className: "table-header-cell w-12", children: jsxRuntime.jsx("input", { type: "checkbox", checked: selectedRows.size === data.length && data.length > 0, onChange: handleSelectAll, className: "w-4 h-4 text-accent-600 border-paper-300 rounded focus:ring-accent-400", "aria-label": "Select all rows" }) })), expandable && jsxRuntime.jsx("th", { className: "table-header-cell w-12" }), columns.map((column) => (jsxRuntime.jsx("th", { className: "table-header-cell", style: { width: column.width }, children: column.sortable ? (jsxRuntime.jsxs("button", { onClick: () => handleSort(column.key), className: "group inline-flex items-center gap-2 hover:text-ink-900 transition-colors", children: [jsxRuntime.jsx("span", { children: column.header }), getSortIcon(column.key)] })) : (column.header) }, column.key)))] }) }), jsxRuntime.jsx("tbody", { children: data.map((row) => {
-                        const rowKey = keyExtractor(row);
-                        const isSelected = selectedRows.has(rowKey);
-                        const isExpanded = expandedRows.has(rowKey);
-                        return (jsxRuntime.jsxs(React.Fragment, { children: [jsxRuntime.jsxs("tr", { className: `table-row ${isSelected ? 'bg-accent-50 border-l-2 border-accent-500' : ''}`, children: [selectable && (jsxRuntime.jsx("td", { className: "table-cell", children: jsxRuntime.jsx("input", { type: "checkbox", checked: isSelected, onChange: () => handleRowSelect(rowKey), className: "w-4 h-4 text-accent-600 border-paper-300 rounded focus:ring-accent-400", "aria-label": `Select row ${rowKey}` }) })), expandable && (jsxRuntime.jsx("td", { className: "table-cell", children: jsxRuntime.jsx("button", { onClick: () => handleRowExpand(rowKey), className: "text-ink-500 hover:text-ink-900 transition-colors", "aria-label": isExpanded ? 'Collapse row' : 'Expand row', children: isExpanded ? (jsxRuntime.jsx(lucideReact.ChevronDown, { className: "h-4 w-4" })) : (jsxRuntime.jsx(lucideReact.ChevronRight, { className: "h-4 w-4" })) }) })), columns.map((column) => (jsxRuntime.jsx("td", { className: "table-cell", children: column.accessor ? column.accessor(row) : row[column.key] }, column.key)))] }), expandable && isExpanded && renderExpandedRow && (jsxRuntime.jsx("tr", { children: jsxRuntime.jsx("td", { colSpan: columns.length + (selectable ? 1 : 0) + (expandable ? 1 : 0), className: "px-6 py-4 bg-paper-50", children: renderExpandedRow(row) }) }))] }, rowKey));
-                    }) })] }) }));
-}
-
 function Badge({ children, variant = 'neutral', size = 'md', icon, onRemove, className = '', dot = false, }) {
     const variantStyles = {
         success: 'bg-success-50 text-success-700 border-success-200',
@@ -6288,8 +6264,8 @@ const Avatar = ({ firstName, lastName, fallbackText = 'U', imageUrl, size = 'md'
         `, style: { textShadow: '0 1px 2px rgba(0,0,0,0.3)' }, children: getInitials() }) }));
 };
 
-function EmptyState({ icon, title, description, action, secondaryAction, }) {
-    return (jsxRuntime.jsxs("div", { className: "flex flex-col items-center justify-center py-16 px-6 text-center", children: [icon && (jsxRuntime.jsx("div", { className: "mb-6 text-ink-400", children: icon })), jsxRuntime.jsx("h3", { className: "text-lg font-medium text-ink-900 mb-2", children: title }), jsxRuntime.jsx("p", { className: "text-sm text-ink-600 max-w-md mb-8", children: description }), (action || secondaryAction) && (jsxRuntime.jsxs("div", { className: "flex items-center gap-3", children: [action && (jsxRuntime.jsx(Button, { variant: "primary", onClick: action.onClick, children: action.label })), secondaryAction && (jsxRuntime.jsx(Button, { variant: "secondary", onClick: secondaryAction.onClick, children: secondaryAction.label }))] }))] }));
+function EmptyState({ icon, title, description, action, secondaryAction, children, }) {
+    return (jsxRuntime.jsxs("div", { className: "flex flex-col items-center justify-center py-16 px-6 text-center", children: [icon && (jsxRuntime.jsx("div", { className: "mb-6 text-ink-400", children: icon })), jsxRuntime.jsx("h3", { className: "text-lg font-medium text-ink-900 mb-2", children: title }), jsxRuntime.jsx("p", { className: "text-sm text-ink-600 max-w-md mb-8", children: description }), children && (jsxRuntime.jsx("div", { className: "mb-8 w-full max-w-md", children: children })), (action || secondaryAction) && (jsxRuntime.jsxs("div", { className: "flex items-center gap-3", children: [action && (jsxRuntime.jsx(Button, { variant: "primary", onClick: action.onClick, children: action.label })), secondaryAction && (jsxRuntime.jsx(Button, { variant: "secondary", onClick: secondaryAction.onClick, children: secondaryAction.label }))] }))] }));
 }
 
 /**
@@ -7305,7 +7281,9 @@ function getColumnStyle(column, dynamicWidth) {
  */
 function DataTable({ data, columns, loading = false, error = null, emptyMessage = 'No data available', loadingRows = 5, className = '', onSortChange, currentSort = null, onEdit, onDelete, actions = [], enableContextMenu = true, onRowClick, onRowDoubleClick, selectable = false, selectedRows: externalSelectedRows, onRowSelect, keyExtractor, expandable = false, expandedRows: externalExpandedRows, renderExpandedRow, expandedRowConfig, showExpandChevron = false, 
 // Visual customization props
-striped = false, stripedColor, density = 'normal', rowClassName, rowHighlight, highlightedRowId, bordered = false, borderColor = 'border-paper-200', disableHover = false, hiddenColumns = [], headerClassName = '', renderEmptyState: customRenderEmptyState, resizable = false, onColumnResize, reorderable = false, onColumnReorder, virtualized = false, virtualHeight = '600px', virtualRowHeight = 60, }) {
+striped = false, stripedColor, density = 'normal', rowClassName, rowHighlight, highlightedRowId, bordered = false, borderColor = 'border-paper-200', disableHover = false, hiddenColumns = [], headerClassName = '', renderEmptyState: customRenderEmptyState, resizable = false, onColumnResize, reorderable = false, onColumnReorder, virtualized = false, virtualHeight = '600px', virtualRowHeight = 60, 
+// Pagination props
+paginated = false, currentPage = 1, pageSize = 10, totalItems, onPageChange, pageSizeOptions = [10, 25, 50, 100], onPageSizeChange, showPageSizeSelector = true, }) {
     // Column resizing state
     const [columnWidths, setColumnWidths] = React.useState({});
     const [resizingColumn, setResizingColumn] = React.useState(null);
@@ -7538,16 +7516,30 @@ striped = false, stripedColor, density = 'normal', rowClassName, rowHighlight, h
             }
         });
     }
+    // Combine all actions: built-in first, then custom actions, then delete last
+    // Delete is stored separately to ensure it's always last
+    let deleteAction = null;
     if (onDelete) {
-        builtInActions.push({
+        deleteAction = {
             label: 'Delete',
             icon: lucideReact.Trash,
             onClick: onDelete,
             variant: 'danger',
             tooltip: 'Delete item'
-        });
+        };
     }
-    const allActions = [...builtInActions, ...actions];
+    // Build final actions array with consistent ordering:
+    // 1. Edit (first - most common action)
+    // 2. View Details
+    // 3. Add Related actions
+    // 4. Manage Related actions
+    // 5. Custom actions (from actions prop)
+    // 6. Delete (always last - destructive action)
+    const allActions = [
+        ...builtInActions,
+        ...actions,
+        ...(deleteAction ? [deleteAction] : [])
+    ];
     // Convert actions to menu items for context menu
     const convertActionsToMenuItems = (item) => {
         const visibleActions = allActions.filter(action => !action.show || action.show(item));
@@ -7896,8 +7888,22 @@ striped = false, stripedColor, density = 'normal', rowClassName, rowHighlight, h
                                 })] }) }), jsxRuntime.jsx("tbody", { className: "bg-white table-loading transition-opacity duration-200", children: loading && data.length === 0 ? (renderLoadingSkeleton()) : data.length === 0 ? (renderEmptyStateContent()) : (renderDataRows()) })] })] }));
     // Wrap in scrollable container if virtualized
     const finalContent = virtualized ? (jsxRuntime.jsx("div", { ref: tableContainerRef, onScroll: handleScroll, style: { height: virtualHeight, overflow: 'auto' }, className: "rounded-lg", children: tableContent })) : tableContent;
+    // Calculate pagination values
+    const effectiveTotalItems = totalItems ?? data.length;
+    const totalPages = Math.ceil(effectiveTotalItems / pageSize);
+    // Page size selector options
+    const pageSizeSelectOptions = pageSizeOptions.map(size => ({
+        value: String(size),
+        label: `${size} per page`,
+    }));
+    // Render pagination controls
+    const renderPaginationControls = () => {
+        if (!paginated)
+            return null;
+        return (jsxRuntime.jsxs("div", { className: "flex items-center justify-between mb-4 px-1", children: [jsxRuntime.jsxs("div", { className: "flex items-center gap-4", children: [showPageSizeSelector && onPageSizeChange && (jsxRuntime.jsxs("div", { className: "flex items-center gap-2", children: [jsxRuntime.jsx("span", { className: "text-sm text-ink-600", children: "Show:" }), jsxRuntime.jsx(Select, { options: pageSizeSelectOptions, value: String(pageSize), onChange: (value) => onPageSizeChange?.(Number(value)) })] })), jsxRuntime.jsx("span", { className: "text-sm text-ink-600", children: effectiveTotalItems > 0 ? (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: ["Showing ", ((currentPage - 1) * pageSize) + 1, " - ", Math.min(currentPage * pageSize, effectiveTotalItems), " of ", effectiveTotalItems] })) : ('No items') })] }), totalPages > 1 && onPageChange && (jsxRuntime.jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: onPageChange }))] }));
+    };
     // Render with context menu
-    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [finalContent, contextMenuState.isOpen && contextMenuState.item && (jsxRuntime.jsx(Menu, { items: convertActionsToMenuItems(contextMenuState.item), position: contextMenuState.position, onClose: () => setContextMenuState({ isOpen: false, position: { x: 0, y: 0 }, item: null }) }))] }));
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [renderPaginationControls(), finalContent, contextMenuState.isOpen && contextMenuState.item && (jsxRuntime.jsx(Menu, { items: convertActionsToMenuItems(contextMenuState.item), position: contextMenuState.position, onClose: () => setContextMenuState({ isOpen: false, position: { x: 0, y: 0 }, item: null }) }))] }));
 }
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
@@ -60476,7 +60482,6 @@ exports.StatusBar = StatusBar;
 exports.StepIndicator = StepIndicator;
 exports.Stepper = Stepper;
 exports.Switch = Switch;
-exports.Table = Table$1;
 exports.Tabs = Tabs;
 exports.Text = Text;
 exports.Textarea = Textarea;