@axzydev/axzy_ui_system 1.2.7 → 1.2.8

package/src/components/page/page.props.ts

@@ -1,25 +1,46 @@
 import { ReactNode } from "react";
 import { ITBreadcrumbItem } from "../breadcrumbs/breadcrumbs.props";
 
+/** Props for the ITPage component. */
 export interface ITPageProps {
+  /** Page title passed to the header. */
   title?: string;
+  /** Description text shown below the title. */
   description?: string;
+  /** Array of breadcrumb items for navigation context. */
   breadcrumbs?: ITBreadcrumbItem[];
+  /** Action buttons rendered in the header. */
   actions?: ReactNode;
+  /** Callback fired when the back button is clicked. */
   backAction?: () => void;
+  /** Optional icon displayed next to the title. */
   icon?: ReactNode;
+  /** Custom color for the icon. Accepts any valid CSS color value. */
   iconColor?: string;
+  /** Whether the page is in a loading state. Shows skeleton placeholders when true. */
   loading?: boolean;
+  /** Error message to display. Shows an error state with retry button when provided. */
   error?: string | null;
+  /** Custom title for the error state. Default: "Error". */
   errorTitle?: string;
+  /** Label for the retry button in the error state. Default: "Reintentar". */
   errorActionLabel?: string;
+  /** Callback fired when the retry button is clicked in the error state. */
   onRetry?: () => void;
+  /** Whether the page is in an empty state. Shows a placeholder when true. */
   empty?: boolean;
+  /** Custom title for the empty state. Default: "Sin datos". */
   emptyTitle?: string;
+  /** Custom description for the empty state. */
   emptyDescription?: string;
+  /** Custom action element for the empty state. */
   emptyAction?: ReactNode;
+  /** Additional CSS classes for the page wrapper. */
   className?: string;
+  /** Content rendered inside the page wrapper. */
   children: ReactNode;
+  /** Maximum width of the page content. Options: "2xl", "3xl", "4xl", "5xl", "6xl", "7xl". Default: "7xl". */
   maxWidth?: "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl";
+  /** Whether to remove default padding from the page wrapper. */
   noPadding?: boolean;
 }

package/src/components/page/page.tsx

@@ -24,6 +24,24 @@ const renderHeader = (props: ITPageProps) => {
   );
 };
 
+/**
+ * Page template combining a page header and content area with built-in states for loading, error, and empty.
+ *
+ * @example
+ * ```tsx
+ * <ITPage
+ *   title="Dashboard"
+ *   description="Overview of your account"
+ *   breadcrumbs={[{ label: 'Home' }, { label: 'Dashboard' }]}
+ *   actions={<ITButton label="Refresh" />}
+ *   loading={isLoading}
+ *   error={errorMessage}
+ *   onRetry={fetchData}
+ * >
+ *   <ITCard>Dashboard content</ITCard>
+ * </ITPage>
+ * ```
+ */
 export default function ITPage(props: ITPageProps) {
   const {
     loading = false,

package/src/components/page-header/page-header.doc.mdx

@@ -0,0 +1,54 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './page-header.stories';
+
+<Meta of={Stories} />
+
+# ITPageHeader
+
+A page title bar component that displays a heading with optional breadcrumbs, description text, action buttons, and a back navigation button. Designed to sit at the top of page content for consistent page-level navigation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | required | Page title displayed as the main heading. |
+| `description` | `string` | `undefined` | Optional description text shown below the title. |
+| `breadcrumbs` | `ITBreadcrumbItem[]` | `undefined` | Breadcrumb navigation items above the title. |
+| `actions` | `ReactNode` | `undefined` | Action buttons or elements rendered on the right side. |
+| `backAction` | `() => void` | `undefined` | Callback fired when the back button is clicked. |
+| `icon` | `ReactNode` | `undefined` | Optional icon displayed next to the title. |
+| `iconColor` | `string` | `undefined` | Custom CSS color value for the icon. |
+| `className` | `string` | `undefined` | Additional CSS classes for the container. |
+
+## Usage
+
+```tsx
+import { ITPageHeader } from '@axzydev/axzy_ui_system';
+import { FaUsers } from 'react-icons/fa';
+
+<ITPageHeader
+  title="Users"
+  description="Manage system users"
+  breadcrumbs={[{ label: 'Dashboard', href: '#' }, { label: 'Users' }]}
+  actions={<ITButton label="Add User" />}
+/>
+<ITPageHeader
+  title="Edit User"
+  backAction={() => navigate(-1)}
+  breadcrumbs={[{ label: 'Users', href: '/users' }, { label: 'Edit' }]}
+/>
+```
+
+## Notes
+
+- Breadcrumbs render above the title using the ITBreadcrumbs component.
+- `backAction` renders a left-arrow button before the content; breadcrumbs shift to the right of the back button.
+- The `icon` slot places an icon beside the title, colored by `iconColor` or the primary theme color.
+- Actions area accepts any React nodes; typically ITButton components with `small` sizing.
+- The component uses a flex layout: breadcrumbs + back button on the left, actions on the right.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/page-header/page-header.props.ts

@@ -1,13 +1,22 @@
 import { ReactNode } from "react";
 import { ITBreadcrumbItem } from "../breadcrumbs/breadcrumbs.props";
 
+/** Props for the ITPageHeader component. */
 export interface ITPageHeaderProps {
+  /** Page title displayed as the main heading. */
   title: string;
+  /** Optional description text shown below the title. */
   description?: string;
+  /** Array of breadcrumb items for navigation context. */
   breadcrumbs?: ITBreadcrumbItem[];
+  /** Action buttons or elements rendered on the right side. */
   actions?: ReactNode;
+  /** Callback fired when the back button is clicked. */
   backAction?: () => void;
+  /** Optional icon displayed next to the title. */
   icon?: ReactNode;
+  /** Custom color for the icon. Accepts any valid CSS color value. */
   iconColor?: string;
+  /** Additional CSS classes for the container. */
   className?: string;
 }

package/src/components/page-header/page-header.tsx

@@ -3,6 +3,21 @@ import { ITPageHeaderProps } from "./page-header.props";
 import ITBreadcrumbs from "../breadcrumbs/breadcrumbs";
 import ITText from "@/components/text/text";
 
+/**
+ * Page title bar with breadcrumbs, description, back button, and action buttons.
+ *
+ * @example
+ * ```tsx
+ * <ITPageHeader
+ *   title="Users"
+ *   description="Manage all system users"
+ *   breadcrumbs={[{ label: 'Admin', href: '/admin' }, { label: 'Users' }]}
+ *   backAction={() => history.back()}
+ *   actions={<ITButton label="Add User" />}
+ *   icon={<FaUsers />}
+ * />
+ * ```
+ */
 export default function ITPageHeader({
   title,
   description,

package/src/components/pagination/pagination.doc.mdx

@@ -0,0 +1,62 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './pagination.stories';
+
+<Meta of={Stories} />
+
+# ITPagination
+
+Page navigation with current/total pages display, first/last buttons, sibling page count control, and an optional items-per-page selector with summary text.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currentPage` | `number` | — | Current active page (1-indexed). |
+| `totalPages` | `number` | — | Total number of pages available. |
+| `onPageChange` | `(page: number) => void` | — | Callback fired when a page is clicked or prev/next is activated. |
+| `siblingCount` | `number` | `1` | Number of visible page siblings before and after the current page. |
+| `color` | `"primary" \| "secondary" \| "success" \| "danger" \| "warning" \| "info" \| "purple"` | `"primary"` | Semantic color for active page and buttons. |
+| `className` | `string` | — | Additional CSS classes for the container. |
+| `itemsPerPageOptions` | `number[]` | — | Available options for the items-per-page selector dropdown. |
+| `itemsPerPage` | `number` | — | Current items per page value. Required if `itemsPerPageOptions` is provided. |
+| `onItemsPerPageChange` | `(value: number) => void` | — | Callback fired when the items per page value is changed. |
+| `totalItems` | `number` | — | Total number of items across all pages. Used for the "1-10 of 50" summary text. |
+
+## Usage
+
+```tsx
+import { ITPagination } from '@axzydev/axzy_ui_system';
+
+<ITPagination
+  currentPage={1}
+  totalPages={5}
+  onPageChange={(page) => setCurrentPage(page)}
+/>
+
+<ITPagination
+  currentPage={1}
+  totalPages={50}
+  siblingCount={2}
+  color="primary"
+  onPageChange={(page) => setCurrentPage(page)}
+  itemsPerPageOptions={[10, 20, 30, 50]}
+  itemsPerPage={10}
+  onItemsPerPageChange={(val) => setItemsPerPage(val)}
+  totalItems={500}
+/>
+```
+
+## Notes
+
+- First and last page buttons are always visible for quick navigation.
+- Ellipsis indicators appear when sibling gaps exceed the page range.
+- The `siblingCount` prop controls how many page numbers appear around the current page.
+- All seven semantic colors are supported for the active page highlight.
+- When `itemsPerPageOptions` is provided, a dropdown and summary text render alongside pagination.
+- Compatible with server-side pagination via the `currentPage` and `onPageChange` controlled pattern.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/pagination/pagination.props.ts

@@ -1,53 +1,32 @@
+/** Props for the ITPagination component. */
 export interface ITPaginationProps {
-  /**
-   * Current active page (1-indexed).
-   */
+  /** Current active page (1-indexed). */
   currentPage: number;
 
-  /**
-   * Total number of pages available.
-   */
+  /** Total number of pages available. */
   totalPages: number;
 
-  /**
-   * Callback fired when a page is clicked or next/prev is activated.
-   */
+  /** Callback fired when a page is clicked or prev/next is activated. Receives the new page number. */
   onPageChange: (page: number) => void;
 
-  /**
-   * Number of visible pages before and after the current page.
-   * Default: 1
-   */
+  /** Number of visible page siblings before and after the current page. Default: 1. */
   siblingCount?: number;
 
-  /**
-   * Semantic color from the theme (primary, secondary, success, danger, warning, info, purple).
-   * Default: primary
-   */
+  /** Semantic color from the theme. Options: primary, secondary, success, danger, warning, info, purple. Default: "primary". */
   color?: string;
 
-  /**
-   * Additional CSS classes for the container.
-   */
+  /** Additional CSS classes for the container. */
   className?: string;
 
-  /**
-   * Options for items per page selector.
-   */
+  /** Available options for the items-per-page selector dropdown. */
   itemsPerPageOptions?: number[];
 
-  /**
-   * Current items per page value. Required if itemsPerPageOptions is provided.
-   */
+  /** Current items per page value. Required if `itemsPerPageOptions` is provided. */
   itemsPerPage?: number;
 
-  /**
-   * Callback fired when items per page is changed.
-   */
+  /** Callback fired when the items per page value is changed. */
   onItemsPerPageChange?: (value: number) => void;
 
-  /**
-   * Total number of items across all pages. Used to render "1-10 of 50" text.
-   */
+  /** Total number of items across all pages. Used to render the "1-10 of 50" summary text. */
   totalItems?: number;
 }

package/src/components/pagination/pagination.tsx

@@ -74,6 +74,23 @@ const usePagination = ({
   }, [totalPages, currentPage, siblingCount]);
 };
 
+/**
+ * Page navigation controls with previous/next buttons, page number display, and optional items-per-page selector.
+ *
+ * @example
+ * ```tsx
+ * <ITPagination
+ *   currentPage={1}
+ *   totalPages={10}
+ *   onPageChange={(page) => setPage(page)}
+ *   color="primary"
+ *   itemsPerPageOptions={[10, 25, 50]}
+ *   itemsPerPage={10}
+ *   onItemsPerPageChange={(value) => setItemsPerPage(value)}
+ *   totalItems={95}
+ * />
+ * ```
+ */
 export default function ITPagination({
   currentPage,
   totalPages,

package/src/components/popover/popover.doc.mdx

@@ -0,0 +1,53 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './popover.stories';
+
+<Meta of={Stories} />
+
+# ITPopover
+
+Floating content panel triggered by click on a trigger element. Supports four position placements and offers both uncontrolled (click toggle) and controlled (`isOpen`/`onClose`) modes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `trigger` | `ReactNode` | — | Element that triggers the popover when clicked. |
+| `children` | `ReactNode` | — | Content rendered inside the popover panel. |
+| `position` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Position of the popover relative to the trigger element. |
+| `isOpen` | `boolean` | — | Controlled open state. When provided, the component acts in controlled mode. |
+| `onClose` | `() => void` | — | Callback fired when the popover is closed in controlled mode. |
+| `className` | `string` | — | Additional CSS classes for the container. |
+
+## Usage
+
+```tsx
+import { ITPopover } from '@axzydev/axzy_ui_system';
+
+<ITPopover trigger={<ITButton label="Abrir" />}>
+  <button>Editar</button>
+  <button>Eliminar</button>
+</ITPopover>
+
+<ITPopover
+  trigger={<ITButton label="Controlled" />}
+  position="top"
+  isOpen={open}
+  onClose={() => setOpen(false)}
+>
+  <p>Contenido controlado</p>
+</ITPopover>
+```
+
+## Notes
+
+- Default mode is uncontrolled: clicking the trigger toggles the popover open/closed.
+- Controlled mode via `isOpen` and `onClose` allows external state management.
+- Four positions available: `top`, `bottom`, `left`, `right` relative to the trigger element.
+- Popover is dismissed automatically when clicking outside the panel.
+- Ideal for dropdown menus, action lists, and contextual tool panels.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/popover/popover.props.ts

@@ -1,12 +1,20 @@
 import { ReactNode } from "react";
 
+/** Available positions for the popover relative to the trigger element. */
 export type PopoverPosition = "top" | "bottom" | "left" | "right";
 
+/** Props for the ITPopover component. */
 export interface ITPopoverProps {
+  /** Element that triggers the popover when clicked. */
   trigger: ReactNode;
+  /** Content rendered inside the popover panel. */
   children: ReactNode;
+  /** Position of the popover relative to the trigger. Options: "top", "bottom", "left", "right". Default: "bottom". */
   position?: PopoverPosition;
+  /** Controlled open state. When provided, the component acts in controlled mode. */
   isOpen?: boolean;
+  /** Callback fired when the popover is closed in controlled mode. */
   onClose?: () => void;
+  /** Additional CSS classes for the container. */
   className?: string;
 }

package/src/components/popover/popover.tsx

@@ -10,6 +10,19 @@ const positionClasses: Record<PopoverPosition, string> = {
   right: "left-full top-1/2 -translate-y-1/2 ml-2",
 };
 
+/**
+ * Floating content panel triggered by click on a trigger element, with position control and click-outside dismissal.
+ *
+ * @example
+ * ```tsx
+ * <ITPopover trigger={<ITButton label="Options" />} position="bottom">
+ *   <ul>
+ *     <li><button onClick={handleEdit}>Edit</button></li>
+ *     <li><button onClick={handleDelete}>Delete</button></li>
+ *   </ul>
+ * </ITPopover>
+ * ```
+ */
 export default function ITPopover({
   trigger,
   children,

package/src/components/progress/progress.doc.mdx

@@ -0,0 +1,48 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './progress.stories';
+
+<Meta of={Stories} />
+
+# ITProgress
+
+Progress indicator with determinate and indeterminate variants. Supports multiple semantic colors and three sizes for indicating completion or loading states.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | `0` | Current progress value. |
+| `max` | `number` | `100` | Maximum progress value. |
+| `variant` | `"determinate" \| "indeterminate"` | `"determinate"` | Progress variant. `"determinate"` shows a fixed-width fill, `"indeterminate"` shows an animated pulsing bar. |
+| `color` | `"primary" \| "secondary" \| "success" \| "danger" \| "warning" \| "info" \| "purple" \| "error" \| "gray"` | `"primary"` | Semantic color for the progress fill. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height and visual scale of the progress bar. |
+| `className` | `string` | — | Additional CSS classes for the container. |
+| `style` | `CSSProperties` | — | Inline styles applied to the container. |
+
+## Usage
+
+```tsx
+import { ITProgress } from '@axzydev/axzy_ui_system';
+
+<ITProgress value={70} />
+
+<ITProgress value={45} color="success" size="lg" />
+
+<ITProgress variant="indeterminate" />
+
+<ITProgress value={90} color="danger" size="sm" />
+```
+
+## Notes
+
+- `determinate` mode shows a solid fill proportional to `value / max`.
+- `indeterminate` mode renders a continuous animated bar for loading states where progress is unknown.
+- All nine semantic colors are available for the fill.
+- Sizes `sm`, `md`, and `lg` control bar height and overall scale.
+- Use `style` for custom width or container-level overrides.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/progress/progress.props.ts

@@ -1,12 +1,20 @@
 import { CSSProperties } from "react";
 import { ColorsTypes } from "@/types/colors.types";
 
+/** Props for the ITProgress component. */
 export interface ITProgressProps {
+  /** Current progress value. Default: 0. */
   value?: number;
+  /** Maximum progress value. Default: 100. */
   max?: number;
+  /** Progress variant. "determinate" shows a fixed-width fill, "indeterminate" shows an animated pulsing bar. Default: "determinate". */
   variant?: "determinate" | "indeterminate";
+  /** Semantic color from the theme. Options: primary, secondary, success, danger, warning, info, purple, error, gray. Default: "primary". */
   color?: ColorsTypes;
+  /** Size of the progress bar. Options: "sm", "md", "lg". Default: "md". */
   size?: "sm" | "md" | "lg";
+  /** Additional CSS classes for the container. */
   className?: string;
+  /** Inline styles applied to the container. */
   style?: CSSProperties;
 }

package/src/components/progress/progress.tsx

@@ -20,6 +20,15 @@ const sizeMap = {
   lg: "h-3",
 };
 
+/**
+ * Progress bar indicator with support for determinate and indeterminate variants, themed colors, and multiple sizes.
+ *
+ * @example
+ * ```tsx
+ * <ITProgress value={75} max={100} color="success" size="lg" />
+ * <ITProgress variant="indeterminate" color="primary" />
+ * ```
+ */
 export default function ITProgress({
   value = 0,
   max = 100,

package/src/components/radio/radio.doc.mdx

@@ -0,0 +1,62 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './radio.stories';
+
+<Meta of={Stories} />
+
+# ITRadioGroup
+
+Radio button group for selecting a single option from a set. Supports horizontal and vertical layouts, disabled state, and an options-array API for declarative rendering.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Name attribute for the radio input group. Used for form accessibility. |
+| `value` | `string` | — | Currently selected value (controlled). |
+| `onChange` | `(value: string) => void` | — | Callback fired when a radio option is selected. |
+| `options` | `ITRadioOption[]` | — | Array of radio options: `{ value: string, label: ReactNode }`. |
+| `disabled` | `boolean` | `false` | Whether the entire radio group is disabled. |
+| `direction` | `"row" \| "column"` | `"column"` | Layout direction of the radio options. |
+| `className` | `string` | — | Additional CSS classes for the container. |
+
+## Usage
+
+```tsx
+import { ITRadioGroup } from '@axzydev/axzy_ui_system';
+
+<ITRadioGroup
+  name="size"
+  value={selected}
+  onChange={setSelected}
+  options={[
+    { value: "sm", label: "Small" },
+    { value: "md", label: "Medium" },
+    { value: "lg", label: "Large" },
+  ]}
+/>
+
+<ITRadioGroup
+  name="layout"
+  value={selected}
+  onChange={setSelected}
+  direction="row"
+  options={[
+    { value: "option1", label: "Option 1" },
+    { value: "option2", label: "Option 2" },
+  ]}
+/>
+```
+
+## Notes
+
+- Fully controlled component: `value` and `onChange` must be provided.
+- `direction="column"` stacks options vertically; `direction="row"` lays them out horizontally.
+- `disabled` disables all radio inputs in the group at once.
+- Label accepts `ReactNode`, allowing rich content like icons or custom markup.
+- Group uses a shared `name` attribute, ensuring mutual exclusivity across options.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/radio/radio.props.ts

@@ -1,16 +1,27 @@
 import { ReactNode } from "react";
 
+/** Represents a single radio option within a group. */
 export interface ITRadioOption {
+  /** Value of the radio option. */
   value: string;
+  /** Display label for the radio option. */
   label: ReactNode;
 }
 
+/** Props for the ITRadioGroup component. */
 export interface ITRadioGroupProps {
+  /** Name attribute for the radio input group. Used for form accessibility. */
   name: string;
+  /** Currently selected value. */
   value: string;
+  /** Callback fired when a radio option is selected. Receives the selected value. */
   onChange: (value: string) => void;
+  /** Array of radio options to render. */
   options: ITRadioOption[];
+  /** Whether the entire radio group is disabled. */
   disabled?: boolean;
+  /** Layout direction of the radio options. Options: "row", "column". Default: "column". */
   direction?: "row" | "column";
+  /** Additional CSS classes for the container. */
   className?: string;
 }

package/src/components/radio/radio.tsx

@@ -2,6 +2,24 @@ import clsx from "clsx";
 import { ITRadioGroupProps } from "./radio.props";
 import ITText from "@/components/text/text";
 
+/**
+ * Radio button group with configurable layout direction and themed selection styling.
+ *
+ * @example
+ * ```tsx
+ * <ITRadioGroup
+ *   name="color"
+ *   value={selectedColor}
+ *   onChange={(value) => setSelectedColor(value)}
+ *   options={[
+ *     { value: 'red', label: 'Red' },
+ *     { value: 'blue', label: 'Blue' },
+ *     { value: 'green', label: 'Green' },
+ *   ]}
+ *   direction="row"
+ * />
+ * ```
+ */
 export default function ITRadioGroup({
   name,
   value,