@axzydev/axzy_ui_system 1.2.7 → 1.2.8

package/src/components/data-table/dataTable.tsx

@@ -2,7 +2,7 @@ import { useTableState } from "@/hooks/useTableState";
 import { sizeStyles, variantStyles } from "@/types/table.types";
 import clsx from "clsx";
 import React, { useState, useEffect, useCallback, useRef } from "react";
-import { FaCheck, FaSpinner, FaTimes } from "react-icons/fa";
+import { FaCheck, FaSpinner, FaTimes, FaTable, FaThLarge } from "react-icons/fa";
 import { MdOutlineSwapVert } from "react-icons/md";
 import ITInput from "../input/input";
 import ITPagination from "../pagination/pagination";
@@ -18,6 +18,27 @@ const getNestedValue = (obj: unknown, path: string) => {
 
 const EMPTY_OBJECT = {};
 
+/**
+ * Async server-side data table with sorting, filtering, and pagination.
+ *
+ * Fetches data via the `fetchData` callback whenever pagination, sorting, or
+ * filters change. Supports column-level text/catalog/boolean filters, sortable
+ * columns, and a loading overlay. Built on-top of internal table hooks for
+ * automatic state coordination.
+ *
+ * @example
+ * ```tsx
+ * <ITDataTable
+ *   columns={[
+ *     { key: "name", label: "Name", sortable: true, filter: true },
+ *     { key: "status", label: "Status", type: "boolean", filter: true },
+ *   ]}
+ *   fetchData={async (params) => api.fetchItems(params)}
+ *   title="Users"
+ *   variant="bordered"
+ * />
+ * ```
+ */
 export default function ITDataTable<T extends Record<string, unknown>>({
   columns,
   fetchData,
@@ -33,7 +54,12 @@ export default function ITDataTable<T extends Record<string, unknown>>({
   itemsPerPageOptions = [5, 10, 20],
   defaultItemsPerPage = 10,
   title,
+  renderCard,
+  defaultView,
+  showVerticalBorder = true,
+  verticalBorderClassname,
 }: ITDataTableProps<T>) {
+  const [viewMode, setViewMode] = useState<"table" | "cards">(defaultView || "table");
   const [data, setData] = useState<T[]>([]);
   const [totalItems, setTotalItems] = useState(0);
   const [isLoading, setIsLoading] = useState(fetchOnMount);
@@ -194,17 +220,75 @@ export default function ITDataTable<T extends Record<string, unknown>>({
     }
   };
 
+  const renderDefaultCard = (row: T) => {
+    const dataCols = columns.filter((c) => c.type !== "actions");
+    const actionCol = columns.find((c) => c.type === "actions");
+    return (
+      <div className="bg-white dark:bg-slate-800 rounded-lg border border-slate-200 dark:border-slate-700 p-3 space-y-2 shadow-sm">
+        {dataCols.map((col) => (
+          <div key={col.key} className="flex items-center justify-between gap-2">
+            <span className="text-[10px] font-bold uppercase tracking-wider text-slate-400 whitespace-nowrap flex-shrink-0 min-w-[70px]">
+              {col.label}
+            </span>
+            <span className="text-sm font-medium text-slate-800 dark:text-white text-right truncate">
+              {renderCellContent(col, row) as React.ReactNode}
+            </span>
+          </div>
+        ))}
+        {actionCol?.actions && (
+          <div className="flex items-center justify-end gap-2 pt-2 border-t border-slate-100 dark:border-slate-700">
+            {actionCol.actions(row)}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  const segCtrlClass = (mode: "table" | "cards") =>
+    `flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-semibold transition-all ${
+      viewMode === mode
+        ? "bg-white dark:bg-slate-900 text-slate-900 dark:text-white shadow-sm border border-slate-200/50 dark:border-slate-700"
+        : "text-slate-500 dark:text-slate-400 hover:text-slate-700 dark:hover:text-slate-200"
+    }`;
+
   return (
     <div className={clsx("space-y-4 w-full relative", containerClassName)}>
       <div className="rounded-xl shadow-sm overflow-hidden" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
         {title && (
-          <div className="px-6 py-5 border-b border-secondary-100 flex justify-between items-center" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
+          <div className="px-6 py-5 flex items-center justify-between" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
             <ITText as="h2" className="text-xl font-bold text-secondary-900 leading-tight">{title}</ITText>
-            {isLoading && (
-              <div className="text-secondary-400">
-                {loadingIndicator || <FaSpinner className="animate-spin text-primary-500 text-xl" />}
+            <div className="flex items-center gap-3">
+              {isLoading && (
+                <div className="text-secondary-400">
+                  {loadingIndicator || <FaSpinner className="animate-spin text-primary-500 text-xl" />}
+                </div>
+              )}
+              <div className="flex items-center bg-slate-100 dark:bg-slate-800/80 rounded-lg p-0.5 border border-slate-200 dark:border-slate-700/50">
+                <button onClick={() => setViewMode("table")} className={segCtrlClass("table")}>
+                  <FaTable size={11} />
+                  Table
+                </button>
+                <button onClick={() => setViewMode("cards")} className={segCtrlClass("cards")}>
+                  <FaThLarge size={11} />
+                  Cards
+                </button>
               </div>
-            )}
+            </div>
+          </div>
+        )}
+
+        {!title && (
+          <div className="flex justify-end px-4 pt-3">
+            <div className="flex items-center bg-slate-100 dark:bg-slate-800/80 rounded-lg p-0.5 border border-slate-200 dark:border-slate-700/50">
+              <button onClick={() => setViewMode("table")} className={segCtrlClass("table")}>
+                <FaTable size={11} />
+                Table
+              </button>
+              <button onClick={() => setViewMode("cards")} className={segCtrlClass("cards")}>
+                <FaThLarge size={11} />
+                Cards
+              </button>
+            </div>
           </div>
         )}
 
@@ -222,81 +306,102 @@ export default function ITDataTable<T extends Record<string, unknown>>({
             </div>
           )}
 
-          <table
-            className={clsx(
-              "min-w-max w-full text-sm text-left text-secondary-600 transition-opacity duration-300",
-              isLoading ? "opacity-50" : "opacity-100",
-              variantStyles[variant],
-              sizeStyles[size],
-              className
-            )}
-          >
-            <thead>
-              <tr className="bg-white border-b border-secondary-200 text-xs uppercase tracking-wider font-semibold text-secondary-500">
-                {columns.map((col) => (
-                  <th key={col.key} scope="col" className={clsx("px-4 py-4 align-top", col.className)}>
-                    <div className="flex flex-col gap-3 min-w-[150px]">
-                      <div className="flex items-center justify-between gap-2">
-                        <ITText as="span" className="text-secondary-700 font-bold">{col.label}</ITText>
-                        {col.sortable && col.type !== "actions" && (
-                          <button
-                            onClick={() => handleSort(col.key)}
-                            disabled={isLoading}
-                            className={`p-1 rounded-md transition-colors ${
-                              sortConfig?.key === col.key
-                                ? "bg-secondary-200 text-secondary-900"
-                                : "hover:bg-secondary-200 text-secondary-400 hover:text-secondary-700"
-                            } disabled:opacity-50`}
-                            title={`Ordenar por ${col.label}`}
-                          >
-                            <MdOutlineSwapVert className="w-4 h-4" aria-hidden="true" />
-                          </button>
-                        )}
-                      </div>
-
-                      <div className="w-full">{col.filter ? renderFilterInput(col) : null}</div>
-                    </div>
-                  </th>
-                ))}
-              </tr>
-            </thead>
-            <tbody className="divide-y divide-secondary-100">
+          {viewMode === "cards" ? (
+            <div className="p-4 space-y-3 max-h-[400px] overflow-y-auto">
               {data.length > 0 ? (
-                data.map((row, rowIndex) => (
-                  <tr key={rowIndex} className="hover:bg-secondary-50/50 transition-colors duration-150 group">
-                    {columns.map((col) => (
-                      <td key={`${rowIndex}-${col.key}`} className={clsx("px-4 py-3 align-middle", col.className)}>
-                        {col.type === "actions" ? (
-                          <div className="flex items-center justify-center gap-2">
-                            {renderCellContent(col, row) as React.ReactNode}
-                          </div>
-                        ) : (
-                          <div className="text-secondary-700 font-medium">
-                            {renderCellContent(col, row) as React.ReactNode}
-                          </div>
-                        )}
-                      </td>
-                    ))}
-                  </tr>
+                data.map((row, i) => (
+                  <div key={i}>
+                    {renderCard ? renderCard(row) : renderDefaultCard(row)}
+                  </div>
                 ))
               ) : (
-                <tr>
-                  <td colSpan={columns.length} className="px-6 py-20 text-center">
-                    {!isLoading && (
-                      <div className="flex flex-col items-center justify-center text-secondary-400">
-                        <ITText as="span" className="text-lg">No se encontraron resultados</ITText>
-                        <ITText as="span" className="text-sm mt-1">Intenta ajustar los filtros</ITText>
+                !isLoading && (
+                  <div className="flex flex-col items-center justify-center py-12 text-secondary-400">
+                    <ITText as="span" className="text-lg">No se encontraron resultados</ITText>
+                    <ITText as="span" className="text-sm mt-1">Intenta ajustar los filtros</ITText>
+                  </div>
+                )
+              )}
+            </div>
+          ) : (
+            <table
+              className={clsx(
+                "min-w-max w-full text-sm text-left text-secondary-600 transition-opacity duration-300",
+                showVerticalBorder && "[&_th]:border-r [&_th:last-child]:border-r-0 [&_td]:border-r [&_td:last-child]:border-r-0",
+                showVerticalBorder && (verticalBorderClassname || "[&_th]:border-slate-100 dark:[&_th]:border-slate-700/30 [&_td]:border-slate-100 dark:[&_td]:border-slate-700/30"),
+                isLoading ? "opacity-50" : "opacity-100",
+                variantStyles[variant],
+                sizeStyles[size],
+                className
+              )}
+            >
+              <thead>
+                <tr className="bg-secondary-50 text-xs uppercase tracking-wider font-semibold text-slate-700 dark:text-slate-200">
+                  {columns.map((col) => (
+                    <th key={col.key} scope="col" className={clsx("px-4 py-4 align-top", col.className)}>
+                      <div className="flex flex-col gap-3 min-w-[150px]">
+                        <div className="flex items-center justify-between gap-2">
+                           <ITText as="span" className="text-slate-900 dark:text-white font-bold">{col.label}</ITText>
+                          {col.sortable && col.type !== "actions" && (
+                            <button
+                              onClick={() => handleSort(col.key)}
+                              disabled={isLoading}
+                              className={`p-1 rounded-md transition-colors ${
+                                sortConfig?.key === col.key
+                                  ? "bg-secondary-200 text-secondary-900"
+                                  : "hover:bg-secondary-200 text-secondary-400 hover:text-secondary-700"
+                              } disabled:opacity-50`}
+                              title={`Ordenar por ${col.label}`}
+                            >
+                              <MdOutlineSwapVert className="w-4 h-4" aria-hidden="true" />
+                            </button>
+                          )}
+                        </div>
+
+                        <div className="w-full">{col.filter ? renderFilterInput(col) : null}</div>
                       </div>
-                    )}
-                  </td>
+                    </th>
+                  ))}
                 </tr>
-              )}
-            </tbody>
-          </table>
+              </thead>
+              <tbody className="divide-y divide-slate-100 dark:divide-slate-700/30">
+                {data.length > 0 ? (
+                  data.map((row, rowIndex) => (
+                    <tr key={rowIndex} className={clsx("hover:bg-secondary-50/50 transition-colors duration-150 group", variant === "striped" && "odd:bg-secondary-50/40 dark:odd:bg-slate-800/20")}>
+                      {columns.map((col) => (
+                        <td key={`${rowIndex}-${col.key}`} className={clsx("px-4 py-3 align-middle", col.className)}>
+                          {col.type === "actions" ? (
+                            <div className="flex items-center justify-center gap-2">
+                              {renderCellContent(col, row) as React.ReactNode}
+                            </div>
+                          ) : (
+                            <div className="text-secondary-700 font-medium">
+                              {renderCellContent(col, row) as React.ReactNode}
+                            </div>
+                          )}
+                        </td>
+                      ))}
+                    </tr>
+                  ))
+                ) : (
+                  <tr>
+                    <td colSpan={columns.length} className="px-6 py-12 text-center">
+                      {!isLoading && (
+                        <div className="flex flex-col items-center justify-center text-secondary-400">
+                          <ITText as="span" className="text-lg">No se encontraron resultados</ITText>
+                          <ITText as="span" className="text-sm mt-1">Intenta ajustar los filtros</ITText>
+                        </div>
+                      )}
+                    </td>
+                  </tr>
+                )}
+              </tbody>
+            </table>
+          )}
         </div>
       </div>
 
-      <div className="rounded-b-xl border-t border-secondary-200 px-6 py-4" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
+      <div className="rounded-b-xl px-6 py-4" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
         <ITPagination
           currentPage={currentPage}
           totalPages={computedTotalPages}

package/src/components/date-picker/date-picker.doc.mdx

@@ -0,0 +1,65 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './date-picker.stories';
+
+<Meta of={Stories} />
+
+# ITDatePicker
+
+A date picker supporting single date and date range selection. Includes built-in validation error display, min/max date constraints, and placeholder formatting.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Unique name attribute for the input. |
+| `value` | `Date \| [Date \| null, Date \| null]` | — | Selected date or start–end tuple when `range` is true. |
+| `onChange` | `(event) => void` | — | Callback with `{ target: { name, value } }` on date selection. |
+| `onBlur` | `(event) => void` | — | Callback when the input loses focus. |
+| `range` | `boolean` | `false` | Enable date-range selection mode. |
+| `variant` | `ColorsTypes` | `"primary"` | Color variant from design system. |
+| `size` | `SizesTypes` | `"medium"` | Size variant from design system. |
+| `className` | `string` | — | CSS classes for the wrapper. |
+| `calendarClassName` | `string` | — | CSS classes for the calendar popover. |
+| `disabled` | `boolean` | `false` | Disables the date picker. |
+| `placeholder` | `string` | — | Placeholder text when no date is selected. |
+| `label` | `string` | — | Accessible label rendered above the input. |
+| `required` | `boolean` | — | Marks the field as required. |
+| `touched` | `boolean` | — | Visually indicates the field has been interacted with. |
+| `error` | `string \| boolean` | — | Error message string or `true` for default error styling. |
+| `minDate` | `Date` | — | Earliest selectable date. |
+| `maxDate` | `Date` | — | Latest selectable date. |
+
+## Usage
+
+```tsx
+import { ITDatePicker } from '@axzydev/axzy_ui_system';
+
+<ITDatePicker
+  name="birthdate"
+  label="Birth Date"
+  placeholder="DD/MM/YYYY"
+  value={date}
+  onChange={(e) => setDate(e.target.value)}
+/>
+
+<ITDatePicker
+  range
+  name="audit_range"
+  label="Audit Range"
+  value={range}
+  onChange={(e) => setRange(e.target.value)}
+/>
+```
+
+## Notes
+
+- When `range` is true, `value` must be a tuple `[startDate, endDate]` and the onChange target value will be the same shape.
+- The component emits a synthetic event with `target.name` and `target.value`, compatible with Formik integration.
+- Error state is shown when both `error` and `touched` are truthy.
+- Date format follows the locale configuration; placeholder text like `DD/MM/YYYY` guides the user.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/date-picker/date-picker.props.ts

@@ -2,29 +2,46 @@ import { ColorsTypes } from "@/types/colors.types";
 import { SizesTypes } from "@/types/sizes.types";
 
 export interface ITDatePickerProps {
+  /** Unique name attribute for the underlying input element. */
   name: string;
+  /** Selected date. Accepts a single Date or a tuple `[startDate, endDate]` when `range` is true. */
   value?: Date | [Date | null, Date | null];
+  /** Called when the selected date changes. The event object carries `name` and `value` in its target. */
   onChange: (
     event:
       | React.ChangeEvent<HTMLInputElement>
       | { target: { name: string; value: Date | [Date | null, Date | null] } }
   ) => void;
+  /** Called when the input loses focus. */
   onBlur?: (
     event:
       | React.FocusEvent<HTMLInputElement>
       | { target: { name: string; value: Date | [Date | null, Date | null] } }
   ) => void;
+  /** Enables date-range selection mode. When true, `value` is treated as a start-end tuple. @default false */
   range?: boolean;
+  /** Color variant matching the design system (ColorsTypes). @default "primary" */
   variant?: ColorsTypes;
+  /** Size variant matching the design system (SizesTypes). @default "medium" */
   size?: SizesTypes;
+  /** Additional CSS classes for the wrapper element. */
   className?: string;
+  /** Additional CSS classes for the calendar popover. */
   calendarClassName?: string;
+  /** Disables the date picker. @default false */
   disabled?: boolean;
+  /** Placeholder text shown when no date is selected. */
   placeholder?: string;
+  /** Accessible label rendered above the input. */
   label?: string;
+  /** Marks the field as required. */
   required?: boolean;
+  /** Visually indicates the field has been interacted with. */
   touched?: boolean;
+  /** Error state — pass a string message or `true` for default styling. */
   error?: string | boolean;
+  /** Earliest selectable date. */
   minDate?: Date;
+  /** Latest selectable date. */
   maxDate?: Date;
 }

package/src/components/date-picker/datePicker.tsx

@@ -7,6 +7,36 @@ import ITInput from "../input/input";
 import { ITDatePickerProps } from "./date-picker.props";
 import { theme } from "@/theme/theme";
 
+/**
+ * Date picker component with single-date and date-range modes.
+ *
+ * Supports manual text input (DD/MM/YYYY format) and a calendar popover.
+ * In range mode the user selects a start date then an end date; the calendar
+ * highlights the interval. Position-aware popover flips above the input when
+ * near the bottom of the viewport.
+ *
+ * @example
+ * ```tsx
+ * <ITDatePicker
+ *   name="birthDate"
+ *   label="Date of birth"
+ *   value={date}
+ *   onChange={(e) => setDate(e.target.value)}
+ *   maxDate={new Date()}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITDatePicker
+ *   name="travelRange"
+ *   label="Travel dates"
+ *   range
+ *   value={[startDate, endDate]}
+ *   onChange={(e) => setRange(e.target.value)}
+ * />
+ * ```
+ */
 export default function ITDatePicker({
   name,
   value,
@@ -257,7 +287,7 @@ export default function ITDatePicker({
           <span>
             <FaCalendarAlt
               onClick={handleIconClick}
-              className="text-slate-900 cursor-pointer"
+              className="text-slate-500 dark:text-slate-400 cursor-pointer"
             />
           </span>
         }

package/src/components/dialog/dialog.doc.mdx

@@ -0,0 +1,54 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './dialog.stories';
+
+<Meta of={Stories} />
+
+# ITDialog
+
+Modal dialog rendered via a React portal with a semi-transparent overlay backdrop. Supports optional title bar (plain or ITFormHeader), Escape-key dismissal, and a full-screen variant.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | `boolean` | — | Controls dialog visibility. |
+| `onClose` | `() => void` | — | Called on overlay click, close button, or Escape key. |
+| `children` | `ReactNode` | — | Content rendered in the dialog body. |
+| `className` | `string` | — | CSS classes for the dialog panel (e.g., `"w-96"` for width). |
+| `title` | `string` | — | Optional heading at the top of the dialog. |
+| `useFormHeader` | `boolean` | `false` | When true and `title` is set, renders an ITFormHeader with colored styling. |
+| `fullScreen` | `boolean` | `false` | Makes the dialog fill the entire viewport. |
+
+## Usage
+
+```tsx
+import { ITDialog } from '@axzydev/axzy_ui_system';
+
+<ITDialog
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  title="User Details"
+  useFormHeader
+  className="w-[500px]"
+>
+  <UserForm />
+</ITDialog>
+
+<ITDialog isOpen={open} onClose={close} fullScreen>
+  <FullPageEditor />
+</ITDialog>
+```
+
+## Notes
+
+- Content is portaled to `document.body` via `createPortal`, ensuring it renders above all page layers.
+- Click outside the dialog panel or pressing Escape dismisses it.
+- When `useFormHeader` is true, the header uses the ITFormHeader design pattern with brand coloring.
+- Control the dialog width via the `className` prop (e.g., `"w-96"`, `"w-[600px]"`).
+- The overlay uses `bg-black/50` for a darkened backdrop effect.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/dialog/dialog.props.ts

@@ -1,9 +1,16 @@
 export interface ITDialogProps {
+  /** Controls whether the dialog is visible. */
   isOpen: boolean;
+  /** Callback fired when the overlay or close button is clicked, or Escape is pressed. */
   onClose: () => void;
+  /** Content rendered inside the dialog body. */
   children: React.ReactNode;
+  /** Additional CSS classes for the dialog panel. */
   className?: string;
+  /** Optional heading displayed at the top of the dialog. */
   title?: string;
+  /** When true and `title` is provided, renders an ITFormHeader instead of the default title bar. @default false */
   useFormHeader?: boolean;
+  /** Makes the dialog fill the entire viewport. @default false */
   fullScreen?: boolean;
 }

package/src/components/dialog/dialog.tsx

@@ -7,6 +7,32 @@ import useClickOutside from "@/hooks/useClickOutside";
 import ITFormHeader from "../form-header/form-header";
 import ITText from "@/components/text/text";
 
+/**
+ * Modal dialog rendered via React portal with overlay backdrop.
+ *
+ * Supports Escape-key dismissal, click-outside-to-close, optional title bar
+ * (plain or ITFormHeader), and a full-screen variant. Content is portaled to
+ * `document.body` so it sits above all other page layers.
+ *
+ * @example
+ * ```tsx
+ * <ITDialog
+ *   isOpen={open}
+ *   onClose={() => setOpen(false)}
+ *   title="User details"
+ *   useFormHeader
+ * >
+ *   <UserForm />
+ * </ITDialog>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITDialog isOpen={open} onClose={close} fullScreen>
+ *   <FullPageEditor />
+ * </ITDialog>
+ * ```
+ */
 export default function ITDialog({
   isOpen,
   onClose,

package/src/components/divider/divider.doc.mdx

@@ -0,0 +1,42 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './divider.stories';
+
+<Meta of={Stories} />
+
+# ITDivider
+
+A thin horizontal or vertical separator line for visually dividing content sections. Supports custom color and thickness via Tailwind utility classes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction the divider flows. |
+| `className` | `string` | — | Additional CSS classes. |
+| `color` | `string` | `"bg-slate-200 dark:bg-slate-700"` | Tailwind background color class(es). |
+| `thickness` | `string` | `"h-px"` (horizontal) / `"w-px"` (vertical) | Tailwind width/height utility. |
+
+## Usage
+
+```tsx
+import { ITDivider } from '@axzydev/axzy_ui_system';
+
+<ITDivider />
+
+<ITDivider orientation="vertical" color="bg-red-500" thickness="w-1" />
+
+<ITDivider color="bg-primary-300" thickness="h-0.5" />
+```
+
+## Notes
+
+- Horizontal divider is full-width by default; vertical divider is full-height of its parent.
+- Use in combination with ITStack or ITFlex for consistent layout spacing between sections.
+- Auto-detects orientation for default thickness: `h-px` for horizontal, `w-px` for vertical.
+- The `color` prop accepts any valid Tailwind background color class, including dark mode variants.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/divider/divider.props.ts

@@ -1,8 +1,13 @@
+/** Direction the divider flows: "horizontal" | "vertical". */
 export type DividerOrientation = "horizontal" | "vertical";
 
 export interface ITDividerProps {
+  /** Layout direction. @default "horizontal" */
   orientation?: DividerOrientation;
+  /** Additional CSS classes for the divider element. */
   className?: string;
+  /** Tailwind background color class(es). @default "bg-slate-200 dark:bg-slate-700" */
   color?: string;
+  /** Tailwind width/height utility (e.g. "h-px", "h-1", "w-px"). Auto-set based on orientation if omitted. */
   thickness?: string;
 }

package/src/components/divider/divider.tsx

@@ -1,6 +1,22 @@
 import clsx from "clsx";
 import { ITDividerProps } from "./divider.props";
 
+/**
+ * Horizontal or vertical separator line.
+ *
+ * Renders a thin full-width (horizontal) or full-height (vertical) bar using
+ * Tailwind utility classes. Supports custom color and thickness overrides.
+ *
+ * @example
+ * ```tsx
+ * <ITDivider />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITDivider orientation="vertical" color="bg-red-500" thickness="w-1" />
+ * ```
+ */
 export default function ITDivider({
   orientation = "horizontal",
   className,