@undefine-ui/design-system 3.10.2 → 3.11.0

package/README.md

@@ -78,19 +78,20 @@ Storybook (`pnpm dev:storybook`) documents each component and token surface.
 
 ### Icon library
 
-The package includes a comprehensive icon library with 45+ SVG icons organized by category.
+The package includes a comprehensive icon library with 60+ SVG icons organized by category.
 
 **Available icons:**
 
 - **Navigation:** NavArrowLeft, NavArrowRight, NavArrowDown, NavArrowDownSolid, LongArrowUpLeftSolid
 - **User:** User, UserSolid, Building, Bank
 - **Form Controls:** CheckboxDefault, CheckboxSelect, CheckboxIndeterminate, RadioDefault, RadioSelect
-- **Actions:** Search, Copy, Trash, XMark, XMarkSolid, CloudUpload, Download, Settings, Plus, PlusSquare, Attachment, FilterList
-- **Feedback:** InfoCircle, InfoCircleSolid, CheckCircleSolid, HelpCircle, ClipboardCheck, Loader, BellNotification, Circle
-- **Visibility:** Eye, EyeClosed
+- **Actions:** Search, Copy, Edit, Trash, XMark, XMarkSolid, CloudUpload, Download, Settings, Plus, Minus, PlusSquare, Attachment, FilterList, RefreshDouble, MoreHorizontal
+- **Feedback:** InfoCircle, InfoCircleSolid, CheckCircleSolid, HelpCircle, ClipboardCheck, Loader, BellNotification, Circle, ChatBubbleQuestionSolid
+- **Visibility:** Eye, EyeClosed, ZoomIn, ZoomOut
 - **Date & Time:** Calendar, Clock
 - **Data:** SortUp, SortDown, StatUp, StatDown
 - **Toast:** InfoToast, SuccessToast, WarningToast, ErrorToast
+- **Files:** FilePdf, FileAudio, FileVideo, FileDocument, FileGeneric
 - **Location:** MapPinXMark
 - **System:** KeyCommand
 
@@ -1077,6 +1078,184 @@ import { CustomDialog, FeedbackDialog } from '@undefine-ui/design-system';
 - **Customizable:** Style individual elements via feedbackSlotProps
 - **Theme integration:** Uses theme variables for consistent styling
 
+### Lightbox
+
+A full-featured image gallery lightbox component with zoom, pan, navigation, thumbnails, and keyboard support. Perfect for image galleries, product showcases, and media viewers.
+
+**Usage:**
+
+```tsx
+import { Lightbox, useLightbox, type LightboxSlide } from '@undefine-ui/design-system';
+
+// Define your slides
+const slides: LightboxSlide[] = [
+  {
+    src: '/images/photo1.jpg',
+    thumbnail: '/images/photo1-thumb.jpg',
+    alt: 'Photo 1',
+    title: 'Mountain Landscape',
+    description: 'A beautiful mountain view at sunset'
+  },
+  {
+    src: '/images/photo2.jpg',
+    thumbnail: '/images/photo2-thumb.jpg',
+    alt: 'Photo 2'
+  }
+];
+
+// Using the useLightbox hook (recommended)
+const MyGallery = () => {
+  const lightbox = useLightbox(slides);
+
+  return (
+    <>
+      <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(3, 100px)', gap: 1 }}>
+        {slides.map((slide, index) => (
+          <Box
+            key={index}
+            component="img"
+            src={slide.thumbnail}
+            alt={slide.alt}
+            onClick={() => lightbox.onOpen(index)}
+            sx={{ cursor: 'pointer', width: 100, height: 75, objectFit: 'cover' }}
+          />
+        ))}
+      </Box>
+      <Lightbox
+        open={lightbox.open}
+        onClose={lightbox.onClose}
+        slides={lightbox.slides}
+        index={lightbox.selected}
+        onIndexChange={lightbox.onSetSelected}
+      />
+    </>
+  );
+};
+
+// Controlled usage
+const [open, setOpen] = useState(false);
+const [index, setIndex] = useState(0);
+
+<Lightbox
+  open={open}
+  onClose={() => setOpen(false)}
+  slides={slides}
+  index={index}
+  onIndexChange={setIndex}
+/>
+
+// Without thumbnails
+<Lightbox
+  open={open}
+  onClose={handleClose}
+  slides={slides}
+  showThumbnails={false}
+/>
+
+// Without zoom functionality
+<Lightbox
+  open={open}
+  onClose={handleClose}
+  slides={slides}
+  enableZoom={false}
+/>
+
+// Minimal UI (no thumbnails, no counter, no zoom)
+<Lightbox
+  open={open}
+  onClose={handleClose}
+  slides={slides}
+  showThumbnails={false}
+  showCounter={false}
+  enableZoom={false}
+/>
+
+// Custom zoom levels
+<Lightbox
+  open={open}
+  onClose={handleClose}
+  slides={slides}
+  zoomLevels={[0.5, 1, 6]} // [min, default, max]
+/>
+
+// Disable looping
+<Lightbox
+  open={open}
+  onClose={handleClose}
+  slides={slides}
+  loop={false}
+/>
+```
+
+**Lightbox Props:**
+
+- `open` - Controls lightbox visibility (required)
+- `onClose` - Callback when lightbox is closed (required)
+- `slides` - Array of slide objects `LightboxSlide[]` (required)
+- `index` - Current slide index (default: `0`)
+- `onIndexChange` - Callback when index changes `(index: number) => void`
+- `showThumbnails` - Show thumbnail strip at bottom (default: `true`)
+- `showCounter` - Show slide counter in toolbar (default: `true`)
+- `enableZoom` - Enable zoom functionality (default: `true`)
+- `loop` - Enable infinite navigation (default: `true`)
+- `zoomLevels` - Zoom levels as `[min, default, max]` (default: `[1, 1, 4]`)
+
+**LightboxSlide Interface:**
+
+```typescript
+interface LightboxSlide {
+  src: string; // Full-size image URL (required)
+  thumbnail?: string; // Thumbnail URL (falls back to src)
+  alt?: string; // Alt text for accessibility
+  title?: string; // Title displayed below image
+  description?: string; // Description displayed below title
+}
+```
+
+**useLightbox Hook:**
+
+The `useLightbox` hook provides a convenient way to manage lightbox state:
+
+```typescript
+const lightbox = useLightbox(slides);
+
+// Returns:
+{
+  open: boolean;              // Whether lightbox is open
+  selected: number;           // Current slide index
+  slides: LightboxSlide[];    // Slides array
+  onOpen: (index?: number) => void;  // Open at specific index
+  onClose: () => void;        // Close lightbox
+  onSetSelected: (index: number) => void; // Change slide
+  setSlides: (slides: LightboxSlide[]) => void; // Update slides
+}
+```
+
+**Keyboard Navigation:**
+
+- `←` / `→` - Navigate between slides
+- `Escape` - Close lightbox
+
+**Mouse/Touch Controls:**
+
+- **Scroll wheel** - Zoom in/out when zoom is enabled
+- **Double-click** - Toggle between default and max zoom
+- **Drag** - Pan around when zoomed in
+- **Click thumbnails** - Jump to specific slide
+- **Click arrows** - Navigate to previous/next slide
+
+**Features:**
+
+- **Zoom & Pan:** Mouse wheel zoom and drag-to-pan when zoomed
+- **Keyboard navigation:** Arrow keys and Escape support
+- **Thumbnail strip:** Quick navigation with visual thumbnails
+- **Slide counter:** Shows current position (e.g., "2 / 10")
+- **Captions:** Optional title and description per slide
+- **Loop navigation:** Seamlessly cycle through images
+- **Loading states:** Skeleton placeholders while images load
+- **Responsive:** Full-screen overlay with proper mobile handling
+- **Accessible:** Proper ARIA labels and keyboard support
+
 ### Drawer
 
 A drawer component with a fixed header containing a title and close button. The content area is scrollable while the header remains fixed. Built on top of MUI Drawer with enhanced styling and layout.
@@ -1332,13 +1511,13 @@ function LineChart() {
 
 Everything is re-exported from `src/index.ts`. Key groups:
 
-| Group      | Exports                                                                                                                                                                                                          |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Components | `CopyButton`, `CustomDialog`, `CustomDrawer`, `EmptyContent`, `FeedbackDialog`, `HookForm` helpers (`Form`, `Field`, `RHFSwitch`, etc.), `Icon`, `Image`, `Logo`, `LoadingScreen`, `OTPInput`, `Table`, `Upload` |
-| Hooks      | `useBoolean`, `useCopyToClipboard`, `useEventListener`, `useLocalStorage`, `useResponsive`, `useSettings`, `useSetState`, `useScrollOffsetTop`, `usePopover`, `useCountdown`                                     |
-| Contexts   | `SettingsProvider`, `SettingsContext`, `defaultSettings`, `SettingsValueProps`                                                                                                                                   |
-| Theme      | `ThemeProvider`, `createTheme`, `colorSchemes`, `components`, `palette`, `radius`, `shadows`, `customSpacing`, utilities such as `varAlpha`, `bgGradient`, `hideScrollX/Y`                                       |
-| Utilities  | `changeCase` helpers, `formatNumber`, `fullname-utils`, generic `helpers`                                                                                                                                        |
+| Group      | Exports                                                                                                                                                                                                                      |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components | `CopyButton`, `CustomDialog`, `CustomDrawer`, `EmptyContent`, `FeedbackDialog`, `HookForm` helpers (`Form`, `Field`, `RHFSwitch`, etc.), `Icon`, `Image`, `Lightbox`, `Logo`, `LoadingScreen`, `OTPInput`, `Table`, `Upload` |
+| Hooks      | `useBoolean`, `useCopyToClipboard`, `useEventListener`, `useLightbox`, `useLocalStorage`, `useResponsive`, `useSettings`, `useSetState`, `useScrollOffsetTop`, `usePopover`, `useCountdown`                                  |
+| Contexts   | `SettingsProvider`, `SettingsContext`, `defaultSettings`, `SettingsValueProps`                                                                                                                                               |
+| Theme      | `ThemeProvider`, `createTheme`, `colorSchemes`, `components`, `palette`, `radius`, `shadows`, `customSpacing`, utilities such as `varAlpha`, `bgGradient`, `hideScrollX/Y`                                                   |
+| Utilities  | `changeCase` helpers, `formatNumber`, `fullname-utils`, generic `helpers`                                                                                                                                                    |
 
 You can also import the theme pieces directly to compose your own MUI theme or to extend tokens in Storybook.