@axzydev/axzy_ui_system 1.4.0 → 1.4.2

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "sideEffects": [
     "*.css"

package/src/App.tsx

@@ -14,6 +14,7 @@ import "./index.css";
 // Import Showcases
 import { HomeShowcase } from "./showcases/HomeShowcase";
 import { GettingStartedShowcase } from "./showcases/GettingStartedShowcase";
+import { HelpShowcase } from "./showcases/HelpShowcase";
 import { SizesShowcase } from "./showcases/SizesShowcase";
 import {
   CardShowcase,
@@ -233,6 +234,8 @@ function App() {
     switch (itemId) {
       case "getting-started":
         return <GettingStartedShowcase />;
+      case "help":
+        return <HelpShowcase />;
       // Structure
       case "layout":
         return <LayoutShowcase />;

package/src/components/organisms/sidebar/sidebar.doc.mdx

@@ -20,6 +20,7 @@ Vertical navigation sidebar with collapsible submenus, tooltips when collapsed,
 | `subitemConnector` | `"dot" \| "\|" \| "none"` | `"dot"` | Visual connector style for sub-items. |
 | `className` | `string` | — | Additional CSS classes on the sidebar `<aside>`. |
 | `header` | `ReactNode` | — | Optional content rendered above the navigation list (e.g. a wordmark). Hidden while the sidebar is collapsed, so it only appears when the hover-expanded rail is shown. |
+| `notification` | `ITSidebarNotification` | — | Optional notification entry (icon + label + `ITBadget` counter) pinned above the navigation. Unlike `header`, it stays visible while collapsed, showing only the icon and counter. |
 
 ### ITNavigationItem
 
@@ -31,7 +32,18 @@ Vertical navigation sidebar with collapsible submenus, tooltips when collapsed,
 | `action` | `() => void` | Click handler for top-level items without submenus. |
 | `isActive` | `boolean` | Whether this item is active/highlighted. |
 | `subitems` | `ITNavigationSubItemEntry[]` | Array of entries: plain sub-items or titled groups (`ITNavigationSubItemGroup`). |
-| `badge` | `string` | Badge text (e.g. notification count). |
+| `badge` | `number \| string` | Notification content rendered with `ITBadget` (e.g. an unread count). |
+| `badgeProps` | `ITBadgetProps` | Styling forwarded to the item badge (`color`, `size`, `variant`, `className` for padding). |
+
+### ITSidebarNotification
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `count` | `number` | — | Count displayed inside the notification `ITBadget`. |
+| `icon` | `ReactNode` | — | Icon rendered left of the label (e.g. a bell). Omit for a count-only pill. |
+| `label` | `string` | `"Notificaciones"` | Accessible label and tooltip for the notification button. |
+| `onClick` | `() => void` | — | Click handler for the notification button. |
+| `badgeProps` | `ITBadgetProps` | `{ color: "danger", size: "sm" }` | Styling forwarded to the internal `ITBadget`; use `className` for padding. |
 
 ### ITNavigationSubItem
 
@@ -105,13 +117,46 @@ const items = [
 
 Discriminate entries with `"items" in entry`. The heading style (uppercase, `0.68rem`, weight 700, `0.08em` tracking, `var(--it-sidebar-icon-color, var(--color-secondary-400))`) is applied by the component and cannot be overridden per group.
 
+## Notifications and badges
+
+Item badges and the notification row both render the `ITBadget` atom. Use `badge` for a per-item counter and `notification` for a top-level entry (e.g. a bell):
+
+```tsx
+import { ITSidebar } from '@axzydev/axzy_ui_system';
+import { FaBell } from 'react-icons/fa';
+
+const items = [
+  { id: 'dashboard', label: 'Dashboard', isActive: true, action: () => {} },
+  { id: 'inbox', label: 'Inbox', badge: 12, action: () => {} },
+  {
+    id: 'alerts',
+    label: 'Alerts',
+    badge: 3,
+    badgeProps: { color: 'warning', variant: 'outlined' },
+    action: () => {},
+  },
+];
+
+<ITSidebar
+  navigationItems={items}
+  notification={{
+    count: 5,
+    icon: <FaBell />,
+    label: 'Notifications',
+    onClick: () => {},
+    // Tweak the ITBadget, incl. padding via className.
+    badgeProps: { color: 'danger', className: 'px-2' },
+  }}
+/>
+```
+
 ## Notes
 
 - There is no collapse toggle button: the collapsed 88px rail expands and collapses automatically on pointer hover (300 ms leave delay).
 - Collapsed mode shrinks to icon-only; a glassmorphism panel shows the item's sub-items on hover. For an item whose `subitems` contain groups, that panel **flattens** every group into one plain list and renders **no** group headings.
 - Submenus expand/collapse with smooth transitions when a parent item is clicked; the expanded submenu is animated with a `max-h` transition (cap `1000px`).
 - Active item highlighting uses a colored left-border accent and subtle background tint.
-- Badge support renders a notification-style counter on the item.
+- Badge support renders a notification-style counter on the item using the `ITBadget` atom; customize it with `badgeProps` (`color`, `size`, `variant`, `className`). The sidebar also accepts a `notification` entry (icon + label + `ITBadget` counter) pinned above the navigation, which stays visible while collapsed as icon + counter.
 - `subitemConnector` styles the visual link between parent and sub-items: `dot` (default), `|` (vertical bar), or `none`. Grouping does not change it: the `|` guide is a single `border-left` on the outer submenu `<ul>` only.
 - An active sub-item inside a group still auto-expands its parent, because auto-expand flattens groups the same way the collapsed flyout does.
 - `visibleOnMobile` forces the sidebar visible at every breakpoint and disables the collapsed rail, so it stays fully expanded.

package/src/components/organisms/sidebar/sidebar.props.ts

@@ -1,3 +1,5 @@
+import type { ITBadgetProps } from "@/components/atoms/badget/badget.props";
+
 /** A sub-navigation item nested under a parent menu. */
 export interface ITNavigationSubItem {
   /** Unique identifier for the sub-item. */
@@ -50,8 +52,38 @@ export interface ITNavigationItem {
    * The field `items` is reserved for {@link ITNavigationSubItemGroup}.
    */
   subitems?: ITNavigationSubItemEntry[];
-  /** Badge text displayed on the item (e.g. notification count). */
-  badge?: string;
+  /**
+   * Notification badge content rendered with the {@link ITBadget} atom
+   * (e.g. an unread count). Omit it to render no badge.
+   */
+  badge?: number | string;
+  /**
+   * Styling forwarded to the `ITBadget` rendered for {@link ITNavigationItem.badge}.
+   * `color`, `size`, `variant` and `className` are supported; use `className`
+   * to tweak the badge padding/positioning.
+   */
+  badgeProps?: ITBadgetProps;
+}
+
+/**
+ * Notification row pinned above the navigation in {@link ITSidebarProps}. It
+ * renders an optional icon, a label and an `ITBadget` counter — e.g. a bell with
+ * a number. When the rail is collapsed only the icon + counter are shown.
+ */
+export interface ITSidebarNotification {
+  /** Count displayed inside the notification `ITBadget`. */
+  count: number;
+  /** Icon rendered left of the label (e.g. a bell). Omit for a count-only pill. */
+  icon?: React.ReactNode;
+  /** Accessible label and tooltip for the notification button. @default "Notificaciones" */
+  label?: string;
+  /** Click handler for the notification button. */
+  onClick?: () => void;
+  /**
+   * Styling forwarded to the internal `ITBadget`. Defaults to `color: "danger"`
+   * and `size: "sm"`; override `color`/`variant`/`size` or use `className` for padding.
+   */
+  badgeProps?: ITBadgetProps;
 }
 
 /** Props for the ITSidebar vertical navigation component. */
@@ -77,5 +109,11 @@ export interface ITSidebarProps {
    * Hidden while the sidebar is collapsed, so it only shows on hover.
    */
   header?: React.ReactNode;
+  /**
+   * Optional notification entry pinned above the navigation (icon + label +
+   * `ITBadget` counter). Unlike {@link ITSidebarProps.header} it stays visible
+   * while collapsed, showing just the icon and the counter.
+   */
+  notification?: ITSidebarNotification;
 }
 

package/src/components/organisms/sidebar/sidebar.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import ITSidebar from '@/components/organisms/sidebar/sidebar';
-import { FaHome, FaUsers, FaCog, FaChartBar, FaShieldAlt, FaShoppingCart } from 'react-icons/fa';
+import { FaHome, FaUsers, FaCog, FaChartBar, FaShieldAlt, FaShoppingCart, FaRegBell } from 'react-icons/fa';
 import { expect, fn, userEvent, waitFor } from 'storybook/test';
 
 const meta: Meta<typeof ITSidebar> = {
@@ -174,3 +174,61 @@ export const Grouped: Story = {
     await expect(groupedSubItemActionSpy).toHaveBeenCalled();
   },
 };
+
+export const WithNotificationBadges: Story = {
+  args: {
+    navigationItems: [
+      { id: 'dashboard', label: 'Dashboard', icon: <FaHome />, isActive: true },
+      { id: 'inbox', label: 'Bandeja', icon: <FaUsers />, badge: 12 },
+      {
+        id: 'alerts',
+        label: 'Alertas',
+        icon: <FaShieldAlt />,
+        badge: 3,
+        badgeProps: { color: 'warning', variant: 'outlined' },
+      },
+      { id: 'settings', label: 'Configuración', icon: <FaCog />, action: fn() },
+    ],
+    notification: {
+      count: 5,
+      icon: <FaRegBell />,
+      label: 'Notificaciones',
+      onClick: fn(),
+    },
+    isCollapsed: false,
+    visibleOnMobile: true,
+  },
+  render: (args) => (
+    <div className="h-screen bg-gray-50 flex">
+      <ITSidebar {...args} />
+      <div className="flex-1 p-8 text-zinc-500 font-medium">
+        Cada ítem puede llevar un ITBadget con número (`badge` + `badgeProps`) y el sidebar admite una fila de notificación con contador (`notification`).
+      </div>
+    </div>
+  ),
+};
+
+export const CollapsedNotifications: Story = {
+  args: {
+    navigationItems: [
+      { id: 'dashboard', label: 'Dashboard', icon: <FaHome />, isActive: true },
+      { id: 'inbox', label: 'Bandeja', icon: <FaUsers />, badge: 12 },
+      { id: 'settings', label: 'Configuración', icon: <FaCog /> },
+    ],
+    notification: {
+      count: 9,
+      icon: <FaRegBell />,
+      label: 'Notificaciones',
+    },
+    isCollapsed: true,
+    visibleOnMobile: true,
+  },
+  render: (args) => (
+    <div className="h-screen bg-gray-50 flex">
+      <ITSidebar {...args} />
+      <div className="flex-1 p-8 text-zinc-500 font-medium">
+        Al colapsar, la fila de notificación queda como icono + contador, y los badges de cada ítem siguen visibles como píldoras con número.
+      </div>
+    </div>
+  ),
+};

package/src/components/organisms/sidebar/sidebar.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import clsx from "clsx";
 import { FaChevronDown } from "react-icons/fa";
 import {
   ITNavigationItem,
@@ -7,6 +8,7 @@ import {
   ITNavigationSubItemGroup,
   ITSidebarProps,
 } from "./sidebar.props";
+import ITBadget from "@/components/atoms/badget/badget";
 import ITText from "@/components/atoms/text/text";
 
 /** Narrows a submenu entry to a titled group. */
@@ -42,7 +44,14 @@ function flattenSubItems(
  *         { id: "billing", label: "Billing", isActive: true },
  *       ],
  *     },
+ *     { id: "inbox", label: "Inbox", icon: <FaEnvelope />, badge: 12 },
  *   ]}
+ *   notification={{
+ *     count: 5,
+ *     icon: <FaBell />,
+ *     label: "Notificaciones",
+ *     onClick: () => navigate("/notifications"),
+ *   }}
  *   isCollapsed
  * />
  * ```
@@ -56,6 +65,7 @@ export default function ITSidebar({
   onSubItemClick,
   subitemConnector = 'dot',
   header,
+  notification,
 }: ITSidebarProps) {
   const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set());
   const [isHovering, setIsHovering] = useState(false);
@@ -217,6 +227,88 @@ export default function ITSidebar({
     );
   };
 
+  const renderNotification = () => {
+    if (!notification) return null;
+
+    const {
+      count,
+      icon,
+      label = "Notificaciones",
+      onClick,
+      badgeProps,
+    } = notification;
+    const { className: badgeClassName, ...badgeRest } = badgeProps ?? {};
+
+    const badge = (
+      <ITBadget
+        color="danger"
+        size="sm"
+        {...badgeRest}
+        className={clsx("shadow-md", badgeClassName)}
+      >
+        {String(count)}
+      </ITBadget>
+    );
+
+    if (isSidebarCollapsed) {
+      return (
+        <button
+          type="button"
+          aria-label={label}
+          title={label}
+          onClick={onClick}
+          className="relative flex items-center justify-center w-full p-2 mb-1 rounded-xl transition-all duration-300"
+          style={{ color: "var(--it-sidebar-icon-color, var(--color-secondary-500))" }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.backgroundColor = "var(--it-sidebar-hover-bg, var(--color-secondary-100))";
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.backgroundColor = "transparent";
+          }}
+        >
+          {icon && (
+            <span className="flex items-center justify-center text-[1.05rem]">{icon}</span>
+          )}
+          <span className="absolute top-0.5 right-0.5 pointer-events-none">{badge}</span>
+        </button>
+      );
+    }
+
+    return (
+      <button
+        type="button"
+        aria-label={label}
+        title={label}
+        onClick={onClick}
+        className="flex items-center gap-2.5 w-full text-left px-3 py-2 mb-1 rounded-xl transition-all duration-300"
+        style={{ color: "var(--it-sidebar-label-color, var(--color-secondary-600))" }}
+        onMouseEnter={(e) => {
+          e.currentTarget.style.backgroundColor = "var(--it-sidebar-hover-bg, var(--color-secondary-100))";
+        }}
+        onMouseLeave={(e) => {
+          e.currentTarget.style.backgroundColor = "transparent";
+        }}
+      >
+        {icon && (
+          <span
+            className="flex-shrink-0 flex items-center justify-center text-[1.05rem]"
+            style={{ color: "var(--it-sidebar-icon-color, #9ca3af)" }}
+          >
+            {icon}
+          </span>
+        )}
+        <ITText
+          as="span"
+          className="truncate tracking-wide"
+          style={{ fontSize: "0.8rem", fontWeight: 500 }}
+        >
+          {label}
+        </ITText>
+        <span className="ml-auto flex-shrink-0">{badge}</span>
+      </button>
+    );
+  };
+
   return (
     <aside
       ref={sidebarRef}
@@ -240,12 +332,17 @@ export default function ITSidebar({
         <div className="px-4 pt-4 pb-1 flex-shrink-0">{header}</div>
       )}
 
+      {notification && (
+        <div className="px-4 pt-3 flex-shrink-0">{renderNotification()}</div>
+      )}
+
       {/* Navigation Items */}
       <nav aria-label="Componentes de la librería" className="flex-1 py-4 overflow-y-auto overflow-x-hidden custom-scrollbar px-4">
         <ul className="space-y-1">
           {navigationItems.map((item) => {
             const hasSubmenu = !!item.subitems && item.subitems.length > 0;
             const submenuId = `it-sidebar-submenu-${item.id}`;
+            const { className: badgeClassName, ...badgeRest } = item.badgeProps ?? {};
             return (
             <li key={item.id} className="relative group/navitem">
               <div
@@ -321,22 +418,21 @@ export default function ITSidebar({
                   </div>
                 )}
 
-                {item.badge && (
-                  <span
-                    className={`
-                      absolute flex items-center justify-center font-bold shadow-md
-                      ${isSidebarCollapsed
-                        ? "top-1 right-1 w-2.5 h-2.5 rounded-full ring-2 ring-white"
-                        : "right-3 top-1/2 transform -translate-y-1/2 px-1.5 py-0 text-[9px] rounded-full backdrop-blur-sm"}
-                    `}
-                    style={{
-                      backgroundColor: "var(--it-sidebar-badge-bg, var(--color-primary-500))",
-                      color: "var(--it-sidebar-badge-color, #ffffff)",
-                      boxShadow: isSidebarCollapsed ? "0 0 0 2px var(--it-sidebar-bg, var(--color-secondary-900))" : 'none'
-                    }}
+                {item.badge != null && item.badge !== "" && (
+                  <ITBadget
+                    color="primary"
+                    size="sm"
+                    {...badgeRest}
+                    className={clsx(
+                      "absolute shadow-md",
+                      isSidebarCollapsed
+                        ? "top-0.5 right-0.5"
+                        : "right-3 top-1/2 -translate-y-1/2",
+                      badgeClassName,
+                    )}
                   >
-                    {isSidebarCollapsed ? "" : item.badge}
-                  </span>
+                    {String(item.badge)}
+                  </ITBadget>
                 )}
               </div>
 

package/src/index.ts

@@ -103,7 +103,7 @@ import type { ITSearchSelectProps } from "./components/molecules/search-select/s
 import type { ITSelectProps } from "./components/molecules/select/select.props";
 import type { ITSearchTableProps } from "./components/organisms/searchTable/searchTable.props";
 import type { ITSegmentedControlProps } from "./components/atoms/segmented-control/segmented-control.props";
-import type { ITSidebarProps, ITNavigationItem, ITNavigationSubItem, ITNavigationSubItemEntry, ITNavigationSubItemGroup } from "./components/organisms/sidebar/sidebar.props";
+import type { ITSidebarProps, ITSidebarNotification, ITNavigationItem, ITNavigationSubItem, ITNavigationSubItemEntry, ITNavigationSubItemGroup } from "./components/organisms/sidebar/sidebar.props";
 import type { ITSkeletonProps } from "./components/atoms/skeleton/skeleton.props";
 import type { ITSlideToggleProps } from "./components/atoms/slide/slide.props";
 import type { ITSliderProps } from "./components/atoms/slider/slider.props";
@@ -176,6 +176,7 @@ export {
     ITPageProps, ITPageHeaderProps,
     ITNavigationItem, ITNavigationSubItem,
     ITNavigationSubItemEntry, ITNavigationSubItemGroup,
+    ITSidebarNotification,
     ITPaginationProps, ITPopoverProps, ITProgressProps,
     ITRadioGroupProps, ITRadioOption, ITSelectProps, ITSearchSelectProps,
     ITSearchTableProps,

package/src/sandbox/LandingShowcase.tsx

@@ -72,7 +72,7 @@ const GROUP_ACCENTS = [
   "from-primary-500 to-purple-500",
 ];
 
-const GITHUB_URL = "https://github.com/axzydev/axzy_ui_system";
+const GITHUB_URL = "https://github.com/maag070208/AXZY_UI_SYSTEM";
 const INSTALL_CMD = "pnpm add @axzydev/axzy_ui_system";
 
 /**

package/src/sandbox/navigation.ts

@@ -30,6 +30,7 @@ export const SANDBOX_GROUPS: SandboxGroup[] = [
     label: "General",
     subitems: [
       { id: "getting-started", label: "Getting Started" },
+      { id: "help", label: "Ayuda · Solución de Bugs" },
       { id: "sizes", label: "Medidas · sm / md / lg" },
     ],
   },