@papernote/ui 1.10.16 → 1.10.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papernote/ui",
-  "version": "1.10.16",
+  "version": "1.10.17",
   "type": "module",
   "description": "A modern React component library with a paper notebook aesthetic - minimal, professional, and expressive",
   "main": "dist/index.js",

package/src/components/Autocomplete.tsx

@@ -320,6 +320,7 @@ const Autocomplete = forwardRef<AutocompleteHandle, AutocompleteProps>(({
           aria-activedescendant={highlightedIndex >= 0 ? `autocomplete-option-${highlightedIndex}` : undefined}
           aria-invalid={error ? 'true' : undefined}
           aria-describedby={error ? errorId : undefined}
+          aria-required={required}
           aria-busy={loading}
         />
 

package/src/components/Combobox.tsx

@@ -312,6 +312,7 @@ const Combobox = forwardRef<ComboboxHandle, ComboboxProps>(({
             aria-activedescendant={isOpen && filteredOptions.length > 0 ? `option-${highlightedIndex}` : undefined}
             aria-invalid={validationState === 'error' ? 'true' : undefined}
             aria-describedby={validationMessage ? descriptionId : undefined}
+            aria-required={required}
             role="combobox"
           />
 

package/src/components/DatePicker.tsx

@@ -349,6 +349,7 @@ const DatePicker = forwardRef<DatePickerHandle, DatePickerProps>(({
           aria-controls={dialogId}
           aria-invalid={validationState === 'error' ? 'true' : undefined}
           aria-describedby={validationMessage ? descriptionId : undefined}
+          aria-required={required}
           role="combobox"
         />
 

package/src/components/DateRangePicker.tsx

@@ -342,6 +342,7 @@ const DateRangePicker = forwardRef<DateRangePickerHandle, DateRangePickerProps>(
           aria-controls={dialogId}
           aria-invalid={validationState === 'error' ? 'true' : undefined}
           aria-describedby={validationMessage ? descriptionId : (isOpen ? hintId : undefined)}
+          aria-required={required}
           role="combobox"
         />
 

package/src/components/Input.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef, useState } from 'react';
+import React, { forwardRef, useState, useId } from 'react';
 import { AlertCircle, CheckCircle, AlertTriangle, Eye, EyeOff, X, Loader2 } from 'lucide-react';
 
 /**
@@ -166,7 +166,9 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
     },
     ref
   ) => {
-    const inputId = id || `input-${Math.random().toString(36).substring(2, 9)}`;
+    const generatedId = useId();
+    const inputId = id || generatedId;
+    const helperId = `${inputId}-helper`;
     const [showPassword, setShowPassword] = useState(false);
 
     // Handle clear button click
@@ -299,6 +301,9 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
             maxLength={maxLength}
             inputMode={effectiveInputMode}
             enterKeyHint={enterKeyHint}
+            aria-invalid={validationState === 'error'}
+            aria-describedby={helperText || validationMessage ? helperId : undefined}
+            aria-required={props.required}
             className={`
               input
               ${sizeClasses[size]}
@@ -382,7 +387,12 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
         {/* Helper Text, Validation Message, or Character Counter */}
         <div className="flex justify-between items-center mt-2">
           {(helperText || validationMessage) && (
-            <p className={`text-xs ${validationMessage ? getValidationMessageColor() : 'text-ink-600'}`}>
+            <p
+              id={helperId}
+              className={`text-xs ${validationMessage ? getValidationMessageColor() : 'text-ink-600'}`}
+              role={validationState === 'error' ? 'alert' : undefined}
+              aria-live={validationState === 'error' ? 'assertive' : undefined}
+            >
               {validationMessage || helperText}
             </p>
           )}

package/src/components/Modal.tsx

@@ -1,9 +1,12 @@
-import React, { useEffect, useRef, useId } from 'react';
+import React, { useEffect, useRef, useId, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import { X } from 'lucide-react';
 import { useIsMobile } from '../hooks/useResponsive';
 import BottomSheet from './BottomSheet';
 
+// Selector for all focusable elements
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
 export interface ModalProps {
   isOpen: boolean;
   onClose: () => void;
@@ -118,34 +121,86 @@ export default function Modal({
 }: ModalProps) {
   const modalRef = useRef<HTMLDivElement>(null);
   const mouseDownOnBackdrop = useRef(false);
+  const previousActiveElement = useRef<HTMLElement | null>(null);
   const titleId = useId();
   const isMobile = useIsMobile();
 
+  // Get all focusable elements within the modal
+  const getFocusableElements = useCallback(() => {
+    if (!modalRef.current) return [];
+    return Array.from(modalRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+      .filter(el => el.offsetParent !== null); // Filter out hidden elements
+  }, []);
+
   // Determine if we should use BottomSheet
   const useBottomSheet = 
     mobileMode === 'sheet' || 
     (mobileMode === 'auto' && isMobile);
 
-  // Handle escape key (only for modal mode, BottomSheet handles its own)
+  // Handle escape key and focus trap (only for modal mode, BottomSheet handles its own)
   useEffect(() => {
-    if (useBottomSheet) return; // BottomSheet handles escape
-    
-    const handleEscape = (e: KeyboardEvent) => {
+    if (useBottomSheet) return; // BottomSheet handles its own focus
+
+    const handleKeyDown = (e: KeyboardEvent) => {
       if (e.key === 'Escape' && isOpen) {
         onClose();
+        return;
+      }
+
+      // Focus trap: keep focus within modal
+      if (e.key === 'Tab' && isOpen) {
+        const focusableElements = getFocusableElements();
+        if (focusableElements.length === 0) return;
+
+        const firstElement = focusableElements[0];
+        const lastElement = focusableElements[focusableElements.length - 1];
+
+        if (e.shiftKey) {
+          // Shift+Tab: if on first element, wrap to last
+          if (document.activeElement === firstElement) {
+            e.preventDefault();
+            lastElement.focus();
+          }
+        } else {
+          // Tab: if on last element, wrap to first
+          if (document.activeElement === lastElement) {
+            e.preventDefault();
+            firstElement.focus();
+          }
+        }
       }
     };
 
     if (isOpen) {
-      document.addEventListener('keydown', handleEscape);
+      // Store the currently focused element to restore later
+      previousActiveElement.current = document.activeElement as HTMLElement;
+
+      document.addEventListener('keydown', handleKeyDown);
       document.body.style.overflow = 'hidden';
+
+      // Set initial focus to first focusable element
+      // Use requestAnimationFrame to ensure the modal is rendered
+      requestAnimationFrame(() => {
+        const focusableElements = getFocusableElements();
+        if (focusableElements.length > 0) {
+          focusableElements[0].focus();
+        } else if (modalRef.current) {
+          // If no focusable elements, focus the modal container
+          modalRef.current.focus();
+        }
+      });
     }
 
     return () => {
-      document.removeEventListener('keydown', handleEscape);
+      document.removeEventListener('keydown', handleKeyDown);
       document.body.style.overflow = 'unset';
+
+      // Restore focus to the previously focused element
+      if (previousActiveElement.current && typeof previousActiveElement.current.focus === 'function') {
+        previousActiveElement.current.focus();
+      }
     };
-  }, [isOpen, onClose, useBottomSheet]);
+  }, [isOpen, onClose, useBottomSheet, getFocusableElements]);
 
   // Track if mousedown originated on the backdrop
   const handleBackdropMouseDown = (e: React.MouseEvent<HTMLDivElement>) => {
@@ -214,6 +269,7 @@ export default function Modal({
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}
+        tabIndex={-1}
       >
         {/* Header */}
         <div className="flex items-center justify-between px-6 py-4 border-b border-paper-200">

package/src/components/Select.tsx

@@ -85,6 +85,8 @@ export interface SelectProps {
   mobileMode?: 'auto' | 'dropdown' | 'native';
   /** Render dropdown via portal (default: true). Set to false when overflow clipping is not an issue */
   usePortal?: boolean;
+  /** Whether this field is required */
+  required?: boolean;
 }
 
 // Size classes for trigger button
@@ -194,6 +196,7 @@ const Select = forwardRef<SelectHandle, SelectProps>(
     size = 'md',
     mobileMode = 'auto',
     usePortal = true,
+    required = false,
   } = props;
   const [isOpen, setIsOpen] = useState(false);
   const [searchQuery, setSearchQuery] = useState('');
@@ -566,6 +569,7 @@ const Select = forwardRef<SelectHandle, SelectProps>(
         {label && (
           <label id={labelId} className="label">
             {label}
+            {required && <span className="text-error-500 ml-1">*</span>}
           </label>
         )}
 
@@ -584,6 +588,7 @@ const Select = forwardRef<SelectHandle, SelectProps>(
             aria-labelledby={label ? labelId : undefined}
             aria-invalid={error ? 'true' : undefined}
             aria-describedby={error ? errorId : (helperText ? helperTextId : undefined)}
+            aria-required={required}
           >
             <option value="" disabled>{placeholder}</option>
             {options.map((opt) => (
@@ -624,6 +629,7 @@ const Select = forwardRef<SelectHandle, SelectProps>(
       {label && (
         <label id={labelId} className="label">
           {label}
+          {required && <span className="text-error-500 ml-1">*</span>}
         </label>
       )}
 
@@ -651,6 +657,7 @@ const Select = forwardRef<SelectHandle, SelectProps>(
           aria-invalid={error ? 'true' : undefined}
           aria-describedby={error ? errorId : (helperText ? helperTextId : undefined)}
           aria-disabled={disabled}
+          aria-required={required}
         >
           <span className={`flex items-center gap-2 ${selectedOption ? 'text-ink-800' : 'text-ink-400'}`}>
             {loading && <Loader2 className="h-4 w-4 animate-spin text-ink-500" />}

package/src/components/TimePicker.tsx

@@ -292,6 +292,7 @@ const TimePicker = forwardRef<TimePickerHandle, TimePickerProps>(({
           aria-controls={dropdownId}
           aria-invalid={validationState === 'error' ? 'true' : undefined}
           aria-describedby={validationMessage ? descriptionId : undefined}
+          aria-required={required}
           role="combobox"
         />