@banzamel/mineralui 0.7.0 → 0.9.0

package/README.md

@@ -3,7 +3,7 @@
 React component framework for dashboards, admin panels, documentation shells, settings screens and data-heavy internal products.
 
 - npm: `@banzamel/mineralui`
-- release version: `0.7.0`
+- release version: `0.9.0`
 - peer dependencies: `react >= 19`, `react-dom >= 19`
 - repository: `https://github.com/Banzamel/mineralui`
 - styles: auto-injected — CSS is bundled into JS and applied automatically on import
@@ -69,41 +69,59 @@ function AccountSettings() {
 - `MStack`, `MInline`, `MGrid`, `MGridItem`
 - `MSurface`, `MDivider`
 - `MHeader`, `MFooter`, `MNavbar`, `MNavs`, `MTabs`
-- `MSidebar`, `MSidebarItem`, `MSidebarGroup`, `MSidebarDivider`
+- `MSidebar`, `MSidebarItem`, `MSidebarGroup`, `MSidebarDivider` — top-level items outside groups now share group-header styling
 - `MSubNav`
-- `MBreadcrumb` — path-based navigation with collapsible middle items
+- `MBreadcrumb` — single-line path navigation with collapsible middle items and ellipsis overflow
 - `MPagination` — numbered and simple page navigation
-- `MAppShell`, `MBody` — top-level app structure (sidebar + content)
+- `MAppShell`, `MBody` — top-level app structure; auto-detects `MSidebar` among direct children and wraps the rest in an internal content column
 
-### Display
-- `MCard`, `MCardHeader`, `MCardBody`, `MCardFooter`, `MCardPayment`
-- `MBadge`, `MAlert`, `MBanner`
-- `MTag` — interactive tags with close buttons and outlined variant
-- `MTooltip` — hover/focus tooltip with 4 placements and delay
-- `MToastProvider`, `useToast` — toast notification system with auto-dismiss and animations
+### Cards
+- `MCard`, `MCardHeader`, `MCardBody`, `MCardFooter` — generic content card
+- `MCardPayment` — display-only payment card with balance, masked number, holder name and brand badge
+- `MCardBusiness` — business card with `user` and `company` variants, avatar, online status indicator, contact info, QR code and social links
+- `MCardService` — service/course/product card with `service`, `course` and `product` variants, gallery, rating, favorites, dropdown menu, participant avatars and add-to-cart
+- `MCardGrid` — grid container with built-in search, filter by object fields and sort toolbar
+
+### Data
 - `MDataTable` — data-driven table with sorting, filtering, pagination and row selection
-- `MAccordion`, `MAccordionItem` — disclosure group with single or multiple open state
-- `MCollapsible`, `MSpinner`, `MLoader`
-- `MAvatar`, `MModal`
+- `MTreeView` — hierarchical tree list with dashed indent guide lines, automatic file/folder icons by extension and selection
+- `MTaskList`, `MTaskItem` — checklist-style task tracking
+- `MCalendarBoard`, `MCalendarDayCell`, `MCalendarEventList`, `MCalendarEventItem`, `MCalendarEventPopover`, `MCalendarTimeline`
+
+### Feedback
+- `MAlert`, `MBanner` — inline and page-level messaging
+- `MBadge` — compact semantic label with `pulsing` prop for attention
+- `MTag` — interactive tags with close buttons and outlined variant
+- `MSpinner`, `MLoader` — loading indicators
+- `MToastProvider`, `useMToast` — toast notification system with auto-dismiss, smooth fade-out animation and 6 position options
+
+### Overlays
+- `MModal` — blocking overlay for dense details and mobile-friendly dialogs
 - `MDrawer` — slide-out panel from any edge of the screen
+- `MTooltip` — hover/focus tooltip with 4 placements, delay and Portal-based rendering
 - `MPopconfirm` — confirmation popover built on MPopover
-- `MImage`, `MGallery`
-- `MCarousel`
-- `MProgressBar`
-- `MRating`
-- `MCountUp`
+- `MDropdownMenu`, `MDropdownItem`, `MDropdownGroup`, `MDropdownDivider` — context menus and action lists
+
+### Media
+- `MAvatar` — user avatar with size, shape and fallback initials
+- `MImage` — image with aspect ratio, fallback and lazy loading
+- `MGallery` — responsive image grid
+- `MCarousel` — image and content slideshows
+
+### Display
+- `MAccordion`, `MAccordionItem` — disclosure group with single or multiple open state
+- `MCollapsible` — single collapsible section
+- `MProgressBar` — animated progress with label support
+- `MCountUp` — animated number counters
+- `MRating` — star-based interactive ratings
 - `MColorPicker` — visual color picker with hue/saturation area, hex/rgb/hsl input and swatches
-- `MTreeView` — hierarchical tree list with expand/collapse and selection
-- `MTaskList`, `MTaskItem`
-- `MDropdownMenu`, `MDropdownMenuItem`, `MDropdownMenuDivider`
-- `MCalendarBoard`, `MCalendarDayCell`, `MCalendarEventList`, `MCalendarEventItem`, `MCalendarEventPopover`, `MCalendarTimeline`
 
 ### Typography
 - `MHeading`, `MText`, `MSubText`, `MLink`, `MCode`, `MList`, `MListItem`
 - `MKbd` — inline keyboard key indicator for shortcuts and key combinations
 
 ### Controls
-- `MButton`
+- `MButton` — action primitive with `pulsing` prop for attention-drawing glow animation
 - `MCheckbox`
 - `MRadio`, `MRadioGroup`
 - `MToggle`
@@ -144,9 +162,17 @@ function AccountSettings() {
 ## Feature Highlights
 
 ### Layout-first API
+- `MAppShell` auto-detects `MSidebar` among its direct children — no separate prop needed. Place `MSidebar`, `MHeader`, `MBody` and other elements as siblings inside `MAppShell`.
+- `MBody` provides default padding for page content.
 - `MStack`, `MInline` and `MGrid` cover the majority of internal dashboard layouts without extra utility libraries.
 - `MGrid` supports equal columns by default and responsive span overrides with `sm`, `md`, `lg`, `xl`.
-- `MSidebar` provides collapsible, nested navigation with grouped items and dividers.
+- `MSidebar` provides collapsible, nested navigation with grouped items and dividers. Top-level items outside groups automatically inherit group-header styling.
+
+### Card system
+- `MCard` is the generic container; specialized cards (`MCardPayment`, `MCardBusiness`, `MCardService`) handle domain-specific layouts.
+- `MCardBusiness` supports `user` and `company` variants with pulsing online/offline status indicator, QR code and social links.
+- `MCardService` covers three use cases (`service`, `course`, `product`) with gallery, avatar stack, rating, favorites and add-to-cart.
+- `MCardGrid` wraps any card type with a toolbar for search, filtering by object fields and sort direction.
 
 ### Reveal animations
 - `reveal` prop on `MCard`, `MStack`, `MInline`, `MSurface`, `MSection` — elements animate into view when they enter the viewport.
@@ -159,9 +185,9 @@ function AccountSettings() {
 - `useGhostText` hook is exported for use in custom components like chat inputs or search bars.
 
 ### Toast notifications
-- `MToastProvider` wraps your app, `useToast()` fires notifications from anywhere.
+- `MToastProvider` wraps your app, `useMToast()` fires notifications from anywhere.
 - 6 positions, 7 color variants, auto-dismiss with configurable duration.
-- Enter/exit animations and manual close button.
+- Smooth fade-out animation with scale and blur transition.
 
 ### Form-heavy components
 - Specialized inputs handle formatting and validation instead of pushing that logic into every application.
@@ -178,31 +204,35 @@ function AccountSettings() {
 
 ### Data and navigation
 - `MDataTable` — sortable, filterable, paginated table with row selection and custom cell rendering.
-- `MBreadcrumb` — path navigation with automatic ellipsis collapsing for deep hierarchies.
+- `MBreadcrumb` — single-line path navigation with automatic ellipsis collapsing for deep hierarchies.
 - `MPagination` — numbered and simple page controls with dot collapsing.
-- `MTreeView` — hierarchical tree with expand/collapse and node selection.
-
-### Rich display components
-- `MCarousel` for image and content slideshows.
-- `MImage` with aspect ratio, fallback and lazy loading. `MGallery` for responsive image grids.
-- `MProgressBar` with animated fills and label support.
-- `MRating` for star-based interactive ratings.
-- `MCountUp` for animated number counters.
-- `MTaskList` for checklist-style task tracking.
-- `MDropdownMenu` for context menus and action lists.
-- `MBanner` for page-level messaging.
-- `MTooltip` for contextual hints on hover or focus.
-- `MDrawer` — slide-out panel from any screen edge for secondary content and navigation.
-- `MPopconfirm` — confirmation popover for destructive actions.
-- `MAccordion` — disclosure group with single or multiple open panels.
-- `MColorPicker` — visual color selection with hue/saturation, hex/rgb/hsl input and swatches.
-- `MTag` — interactive labels with close buttons for filters, chips and categorization.
-- `MKbd` — inline keyboard shortcut display.
+- `MTreeView` — hierarchical tree with dashed indent guide lines, automatic file/folder icons per extension and node selection.
 
 ### Interaction model
+- `MButton` and `MBadge` support a `pulsing` prop for attention-drawing glow animation in the component's color.
 - Buttons, cards, avatars, tabs and interactive inputs can share the same click effect model.
 - Navigation and picker overlays render through shared popover primitives.
 
+## Architecture
+
+Components are organized into focused groups under `src/components/`:
+
+| Group | Purpose |
+|-------|---------|
+| `cards` | Card containers and specialized card types |
+| `data` | Tables, trees, calendars and task lists |
+| `feedback` | Alerts, badges, tags, spinners and toasts |
+| `overlays` | Modals, drawers, tooltips and dropdown menus |
+| `media` | Images, galleries, carousels and avatars |
+| `display` | Accordions, progress bars, ratings and color picker |
+| `controls` | Buttons, checkboxes, radios, toggles and sliders |
+| `inputs` | Text inputs and specialized input variants |
+| `dropdowns` | Select, autocomplete and date/time pickers |
+| `layout` | Containers, grids, sidebars and navigation |
+| `typography` | Headings, text, links, code and lists |
+| `form` | Form context, field hooks and validators |
+| `primitives` | Portal and popover building blocks |
+
 ## Design System Notes
 
 MineralUI is driven by CSS variables and readable class names.
@@ -232,6 +262,12 @@ MineralUI is driven by CSS variables and readable class names.
     --mineral-border: rgba(255, 255, 255, 0.15);
     --mineral-border-hover: rgba(255, 255, 255, 0.25);
     --mineral-border-focus: var(--mineral-primary);
+
+    /* Z-index layers */
+    --mineral-z-popover: 1000;
+    --mineral-z-modal: 1100;
+    --mineral-z-tooltip: 1150;
+    --mineral-z-toast: 1200;
 }
 ```