@undefine-ui/design-system 3.2.0 → 3.4.0

package/README.md

@@ -84,7 +84,7 @@ The package includes a comprehensive icon library with 45+ SVG icons organized b
 - **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
+- **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
 - **Date & Time:** Calendar, Clock
@@ -364,6 +364,241 @@ const MyForm = () => {
 - **Theme-styled:** Uses your theme's TextField styling
 - **Click-to-open:** Opens picker on text field click
 
+### DateRangePicker
+
+A date range picker with preset options (Today, Last 7 Days, etc.), dual calendars for start/end date selection, and custom date range support. Includes both a standalone `DateRangePicker` component and a `DateRangeDropdown` for toolbar integration.
+
+**Usage:**
+
+```tsx
+import {
+  DateRangePicker,
+  DateRangeDropdown,
+  defaultPresets,
+  getDateRangeFromPreset,
+  type DateRange,
+  type DatePreset
+} from '@undefine-ui/design-system';
+
+// Standalone DateRangePicker
+const [range, setRange] = useState<DateRange>({ start: null, end: null });
+const [preset, setPreset] = useState<DatePreset>('last30days');
+
+<DateRangePicker
+  value={range}
+  preset={preset}
+  onChange={(newRange, newPreset) => {
+    setRange(newRange);
+    setPreset(newPreset);
+  }}
+  onCancel={() => console.log('Cancelled')}
+/>
+
+// DateRangeDropdown (for toolbars)
+<DateRangeDropdown
+  value={range}
+  preset={preset}
+  onChange={(newRange, newPreset) => {
+    setRange(newRange);
+    setPreset(newPreset);
+  }}
+/>
+
+// With custom presets
+const customPresets = [
+  { value: 'today', label: 'Today' },
+  { value: 'last7days', label: 'This Week' },
+  { value: 'last30days', label: 'This Month' },
+  { value: 'custom', label: 'Pick Dates' }
+];
+
+<DateRangePicker presets={customPresets} {...props} />
+
+// Get date range programmatically
+const last7DaysRange = getDateRangeFromPreset('last7days');
+// { start: Date, end: Date }
+```
+
+**DateRangePicker Props:**
+
+- `value` - Currently selected date range `{ start: Date | null, end: Date | null }`
+- `preset` - Currently selected preset (`'today'`, `'yesterday'`, `'last7days'`, `'last30days'`, `'last6months'`, `'lastyear'`, `'alltime'`, `'custom'`)
+- `onChange` - Callback when date range changes `(range, preset) => void`
+- `onCancel` - Callback when cancel is clicked
+- `presets` - Custom preset options array (default: `defaultPresets`)
+- `showPresets` - Show preset radio buttons (default: `true`)
+- `showActions` - Show Cancel/Apply buttons (default: `true`)
+- `dateFormat` - Date format for input display (default: `'dd/MM/yyyy'`)
+- `minDate` / `maxDate` - Date constraints
+
+**DateRangeDropdown Props:**
+
+- Inherits all `DateRangePicker` props
+- `buttonLabel` - Fallback label for the dropdown button (default: `'Date'`)
+- `disabled` - Disable the dropdown
+- `popoverSx` - Custom styles for the popover
+- Button label automatically updates to show selected preset or custom date range (e.g., "Dec 1 - Dec 15, 2024")
+
+**Exported Helpers:**
+
+- `defaultPresets` - Default preset options array
+- `getDateRangeFromPreset(preset)` - Convert preset to actual date range
+
+**React Hook Form Integration (Field.DateRange):**
+
+```tsx
+import { Form, Field } from '@undefine-ui/design-system';
+import { useForm } from 'react-hook-form';
+
+const MyForm = () => {
+  const methods = useForm({
+    defaultValues: {
+      dateRange: { start: null, end: null, preset: 'today' }
+    }
+  });
+
+  return (
+    <Form methods={methods} onSubmit={(data) => console.log(data)}>
+      <Field.DateRange name="dateRange" label="Select Date Range" />
+    </Form>
+  );
+};
+```
+
+**Field.DateRange Props:**
+
+- `name` - Form field name (required, stores `{ start, end, preset }`)
+- `label` - Label for the text field
+- `placeholder` - Placeholder text (default: `'Select date range'`)
+- `helperText` - Helper text below the input
+- `dateFormat` - Date format for display (default: `'MMM d, yyyy'`)
+- `presets` - Custom preset options
+- `disabled` - Disable the field
+- `size` - TextField size (`'small'` | `'medium'`)
+- `fullWidth` - Full width mode (default: `true`)
+
+### Toolbar Components
+
+A collection of components for building data table toolbars with search, filters, sorting, view switching, and date range selection.
+
+**Usage:**
+
+```tsx
+import {
+  ToolbarButton,
+  ToolbarSearchField,
+  ToolbarViewSwitcher,
+  ToolbarFilterButton,
+  ToolbarSortButton,
+  ToolbarSettingsButton,
+  ToolbarTodayButton,
+  ToolbarDatePickerButton,
+  FilterDropdown,
+  SortDropdown,
+  DateRangeDropdown,
+  type ViewOption,
+  type SortOption,
+  type SortDirection
+} from '@undefine-ui/design-system';
+
+// Base toolbar button with icon and label
+<ToolbarButton icon="Filter" label="Filter" onClick={handleClick} />
+
+// Specialized button components
+<ToolbarFilterButton onClick={handleFilter} />
+<ToolbarSortButton onClick={handleSort} />
+<ToolbarSettingsButton onClick={handleSettings} />
+<ToolbarTodayButton onClick={handleToday} />
+<ToolbarDatePickerButton label="Last 30 days" onClick={handleDate} />
+
+// Search field with clear button
+<ToolbarSearchField
+  value={search}
+  onChange={(e) => setSearch(e.target.value)}
+  onClear={() => setSearch('')}
+  placeholder="Search..."
+/>
+
+// View switcher (year/month/week/day dropdown button)
+const [view, setView] = useState<ViewOption>('week');
+<ToolbarViewSwitcher value={view} onClick={() => setView('month')} />
+
+// Filter dropdown - manages its own popover state, just pass children
+<FilterDropdown>
+  <Form methods={methods}>
+    <Field.Text name="status" label="Status" size="small" select>
+      <MenuItem value="active">Active</MenuItem>
+      <MenuItem value="inactive">Inactive</MenuItem>
+    </Field.Text>
+    {/* Add more filter controls */}
+  </Form>
+</FilterDropdown>
+
+// Sort dropdown with unified onChange callback
+const [sortValue, setSortValue] = useState('name');
+const [sortDirection, setSortDirection] = useState<SortDirection>('asc');
+
+const sortOptions: SortOption[] = [
+  { value: 'name', label: 'Name' },
+  { value: 'date', label: 'Date Created' }
+];
+
+<SortDropdown
+  options={sortOptions}
+  value={sortValue}
+  direction={sortDirection}
+  onChange={(value, direction) => {
+    setSortValue(value);
+    setSortDirection(direction);
+  }}
+/>
+
+// Complete toolbar example
+<Stack direction="row" spacing={1} alignItems="center">
+  <ToolbarSearchField value={search} onChange={...} onClear={...} />
+  <Box sx={{ flexGrow: 1 }} />
+  <DateRangeDropdown value={range} preset={preset} onChange={...} />
+  <FilterDropdown>{filterContent}</FilterDropdown>
+  <SortDropdown options={sortOptions} value={sortValue} direction={sortDirection} onChange={...} />
+  <Divider orientation="vertical" flexItem />
+  <ToolbarViewSwitcher value={view} onClick={...} />
+</Stack>
+```
+
+**ToolbarButton Props:**
+
+- `icon` - Icon name from the icon library
+- `label` - Button label text
+- `open` - Whether the button is in open/active state
+- `disabled` - Disable the button
+- All standard MUI ButtonBase props
+
+**FilterDropdown Props:**
+
+- `children` - Content to render inside the popover (use Form + Field components)
+- `buttonLabel` - Custom label for the filter button (default: `'Filter'`)
+- `onClose` - Called when the popover closes
+- `disabled` - Disable the dropdown
+- `popoverSx` - Custom styles for the popover paper
+- `PopoverProps` - Additional popover props
+
+**SortDropdown Props:**
+
+- `options` - Array of sort options `{ value: string, label: string }[]`
+- `value` - Currently selected sort field
+- `direction` - Current sort direction (`'asc'` or `'desc'`)
+- `onChange` - Callback when sort changes `(value: string, direction: SortDirection) => void`
+- `buttonLabel` - Custom label for the sort button (default: `'Sort'`)
+- `ascLabel` - Custom label for ascending (default: `'Ascending'`)
+- `descLabel` - Custom label for descending (default: `'Descending'`)
+- `disabled` - Disable the dropdown
+
+**ToolbarViewSwitcher Props:**
+
+- `value` - Currently selected view (`'year'` | `'month'` | `'week'` | `'day'`)
+- `open` - Whether the button is in open/active state
+- All standard MUI ButtonBase props
+
 ### OTP Input
 
 A one-time password input component with keyboard navigation, paste support, and validation. Perfect for email/SMS verification, PIN codes, and security codes.
@@ -425,6 +660,177 @@ import { OTPInput, Field } from '@undefine-ui/design-system';
 
 The `Field.OTP` component automatically integrates with React Hook Form, providing validation and error handling out of the box.
 
+### Dialog
+
+Custom dialog components with close button and feedback variations. Includes a base `CustomDialog` with a close button positioned on the right, and a `FeedbackDialog` for success, error, and confirmation states.
+
+**Usage:**
+
+```tsx
+import { CustomDialog, FeedbackDialog } from '@undefine-ui/design-system';
+
+// Basic CustomDialog with close button
+<CustomDialog open={open} onClose={handleClose}>
+  <Typography variant="h6">Custom Dialog Title</Typography>
+  <Typography variant="body2">
+    This is a custom dialog with a close button on the right.
+  </Typography>
+</CustomDialog>
+
+// Success feedback dialog
+<FeedbackDialog
+  open={open}
+  onClose={handleClose}
+  image="/path/to/success-image.png"
+  title="Board added successfully"
+  description="Your new board has been created."
+  actions={
+    <>
+      <Button variant="contained" fullWidth onClick={handleGoToBoard}>
+        Go to board
+      </Button>
+      <Button variant="text" color="inherit" fullWidth onClick={handleClose}>
+        Close
+      </Button>
+    </>
+  }
+/>
+
+// Confirmation dialog with horizontal actions
+<FeedbackDialog
+  open={open}
+  onClose={handleClose}
+  title="Confirm deletion"
+  description="Are you sure you want to delete this item?"
+  actions={
+    <Stack direction="row" spacing={1.5} sx={{ width: '100%' }}>
+      <Button variant="outlined" fullWidth onClick={handleClose}>
+        Cancel
+      </Button>
+      <Button variant="contained" color="error" fullWidth onClick={handleDelete}>
+        Delete
+      </Button>
+    </Stack>
+  }
+  feedbackSlotProps={{
+    actions: { flexDirection: 'row' }
+  }}
+/>
+
+// Custom styling
+<FeedbackDialog
+  open={open}
+  onClose={handleClose}
+  title="Welcome aboard! 🎉"
+  description="Your account has been created successfully."
+  actions={
+    <Button variant="contained" fullWidth>Get Started</Button>
+  }
+  feedbackSlotProps={{
+    title: { fontSize: '1.5rem', color: 'primary.main' },
+    description: { maxWidth: 280 }
+  }}
+/>
+```
+
+**CustomDialog Props:**
+
+- `open` - Controls dialog visibility (required)
+- `onClose` - Callback when close button is clicked
+- All MUI `DialogProps` are supported
+
+**FeedbackDialog Props:**
+
+- `open` - Controls dialog visibility (required)
+- `onClose` - Callback when close button is clicked
+- `image` - URL for the feedback image
+- `title` - Title text to display
+- `description` - Description text below the title
+- `actions` - Action elements (buttons, etc.)
+- `feedbackSlotProps` - Custom styles for `image`, `title`, `description`, and `actions` slots
+
+**Features:**
+
+- **Close button:** Positioned on the top-right for easy dismissal
+- **Flexible content:** CustomDialog accepts any children content
+- **Feedback states:** FeedbackDialog supports success, error, and confirmation patterns
+- **Customizable:** Style individual elements via feedbackSlotProps
+- **Theme integration:** Uses theme variables for consistent styling
+
+### 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.
+
+**Usage:**
+
+```tsx
+import { CustomDrawer } from '@undefine-ui/design-system';
+
+// Basic drawer
+<CustomDrawer open={open} onClose={handleClose} title="Drawer Title">
+  <Typography variant="body2">
+    This is the drawer content. It scrolls independently while the header stays fixed.
+  </Typography>
+</CustomDrawer>
+
+// Drawer with details layout
+<CustomDrawer open={open} onClose={handleClose} title="Booking details">
+  <Stack spacing={3}>
+    <Box>
+      <Typography variant="body2" color="text.body">Status</Typography>
+      <Chip label="Confirm" color="success" size="small" />
+    </Box>
+    <Box>
+      <Typography variant="body2" color="text.body">Booking ID</Typography>
+      <Typography variant="subtitle2">#001</Typography>
+    </Box>
+    <Box>
+      <Typography variant="body2" color="text.body">Amount</Typography>
+      <Typography variant="subtitle2">N250,000</Typography>
+    </Box>
+  </Stack>
+</CustomDrawer>
+
+// Left-anchored drawer
+<CustomDrawer
+  open={open}
+  onClose={handleClose}
+  title="Left Drawer"
+  anchor="left"
+>
+  <Typography variant="body2">
+    This drawer opens from the left side.
+  </Typography>
+</CustomDrawer>
+
+// Drawer with form
+<CustomDrawer open={open} onClose={handleClose} title="Time slot">
+  <Stack spacing={3}>
+    <TextField label="Date" size="small" fullWidth />
+    <TextField label="Time" size="small" fullWidth />
+    <Button variant="contained" fullWidth>Save</Button>
+  </Stack>
+</CustomDrawer>
+```
+
+**Props:**
+
+- `open` - Controls drawer visibility (required)
+- `title` - Title text displayed in the fixed header
+- `onClose` - Callback when close button is clicked
+- `anchor` - Side from which the drawer appears (default: `'right'`)
+- `slotProps` - Custom props for MUI Drawer slots (paper, etc.)
+- All MUI `DrawerProps` are supported
+
+**Features:**
+
+- **Fixed header:** Title and close button stay visible while scrolling
+- **Scrollable content:** Content area scrolls independently
+- **Responsive width:** Full width on mobile, 400px on larger screens
+- **Multiple anchors:** Supports left, right, top, and bottom positioning
+- **Close button:** XMark icon button for easy dismissal
+- **Theme integration:** Uses theme variables for consistent styling
+
 ### Empty Content
 
 A flexible empty state component for displaying placeholder content when data is unavailable. Perfect for empty lists, search results, or any state where content hasn't been loaded yet.
@@ -551,17 +957,68 @@ The animated logo automatically plays on mount with:
 
 Ideal for splash screens, loading overlays, or brand storytelling moments.
 
+### ApexCharts Styling
+
+The design system provides styling utilities for ApexCharts integration, ensuring charts match the Define theme.
+
+**Installation:**
+
+```bash
+pnpm add apexcharts react-apexcharts
+```
+
+**Usage:**
+
+```tsx
+import ReactApexChart from 'react-apexcharts';
+import { useTheme, styled } from '@mui/material/styles';
+import { apexChartsStyles, getDefaultChartOptions } from '@undefine-ui/design-system';
+
+// Create a styled wrapper
+const ChartWrapper = styled('div')(({ theme }) => ({
+  ...apexChartsStyles(theme)
+}));
+
+function LineChart() {
+  const theme = useTheme();
+
+  const chartOptions = {
+    ...getDefaultChartOptions(theme),
+    xaxis: {
+      ...getDefaultChartOptions(theme).xaxis,
+      categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul']
+    }
+  };
+
+  const chartSeries = [
+    { name: 'Bookings', data: [10, 41, 35, 51, 49, 62, 69] },
+    { name: 'Revenue', data: [20, 35, 50, 30, 45, 55, 40] }
+  ];
+
+  return (
+    <ChartWrapper>
+      <ReactApexChart type="line" series={chartSeries} options={chartOptions} height={350} />
+    </ChartWrapper>
+  );
+}
+```
+
+**Available exports:**
+
+- `apexChartsStyles(theme)` - CSS styles to apply to a wrapper element (tooltips, legends, labels)
+- `getDefaultChartOptions(theme)` - Default ApexCharts options with theme colors, typography, and grid styling
+
 ## Export surface
 
 Everything is re-exported from `src/index.ts`. Key groups:
 
-| Group      | Exports                                                                                                                                                                      |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Components | `CopyButton`, `EmptyContent`, `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`, `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`                                                                                                                                        |
 
 You can also import the theme pieces directly to compose your own MUI theme or to extend tokens in Storybook.