@axzydev/axzy_ui_system 1.2.6 → 1.2.8

package/src/components/drawer/drawer.doc.mdx

@@ -0,0 +1,59 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './drawer.stories';
+
+<Meta of={Stories} />
+
+# ITDrawer
+
+A sliding panel that emerges from the left or right edge with a backdrop overlay. Includes an optional title bar with close button and a scrollable body. Ideal for side panels, navigation menus, filters, and detail views.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | `boolean` | — | Controls drawer visibility. |
+| `onClose` | `() => void` | — | Called on overlay click or close button press. |
+| `position` | `"left" \| "right"` | `"right"` | Screen edge the drawer attaches to. |
+| `size` | `string` | `"w-80"` | Tailwind width class (e.g., `"w-72"`, `"w-96"`). |
+| `title` | `ReactNode` | — | Optional heading in the drawer header. |
+| `children` | `ReactNode` | — | Content displayed in the drawer body. |
+| `className` | `string` | — | Additional CSS classes for the drawer panel. |
+| `style` | `CSSProperties` | — | Inline styles for the drawer panel. |
+
+## Usage
+
+```tsx
+import { ITDrawer } from '@axzydev/axzy_ui_system';
+
+<ITDrawer
+  isOpen={menuOpen}
+  onClose={() => setMenuOpen(false)}
+  title="Navigation"
+  position="left"
+  size="w-72"
+>
+  <NavMenu />
+</ITDrawer>
+
+<ITDrawer
+  isOpen={filterOpen}
+  onClose={() => setFilterOpen(false)}
+  title="Filters"
+>
+  <FilterPanel />
+</ITDrawer>
+```
+
+## Notes
+
+- The overlay uses `bg-black/40 backdrop-blur-sm` for a blurred background effect.
+- Overlay click outside the panel dismisses the drawer via `useClickOutside`.
+- The body area scrolls independently (`overflow-y-auto`), keeping the header fixed.
+- Default size `w-80` (320px); adjust with any Tailwind width class like `w-96` (384px) or `w-[400px]`.
+- No built-in footer slot — add buttons or actions directly in the children content.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/drawer/drawer.props.ts

@@ -1,14 +1,23 @@
 import { ReactNode, CSSProperties } from "react";
 
+/** Screen edge from which the drawer slides in: "left" | "right". */
 export type DrawerPosition = "left" | "right";
 
 export interface ITDrawerProps {
+  /** Controls whether the drawer is visible. */
   isOpen: boolean;
+  /** Callback fired when the overlay is clicked or the close button is pressed. */
   onClose: () => void;
+  /** Edge the drawer attaches to. @default "right" */
   position?: DrawerPosition;
+  /** Tailwind width class (e.g. "w-80", "w-96"). @default "w-80" */
   size?: string;
+  /** Optional heading rendered in the drawer header. */
   title?: ReactNode;
+  /** Content displayed in the drawer body. */
   children?: ReactNode;
+  /** Additional CSS classes for the drawer panel. */
   className?: string;
+  /** Inline styles for the drawer panel. */
   style?: CSSProperties;
 }

package/src/components/drawer/drawer.tsx

@@ -5,6 +5,26 @@ import useClickOutside from "@/hooks/useClickOutside";
 import { useRef } from "react";
 import ITText from "@/components/text/text";
 
+/**
+ * Sliding panel drawer from the left or right screen edge.
+ *
+ * Renders an overlay backdrop with a horizontally-anchored panel that slides
+ * in. Includes an optional title bar with close button and a scrollable body
+ * area. Uses the `useClickOutside` hook for overlay dismissal.
+ *
+ * @example
+ * ```tsx
+ * <ITDrawer
+ *   isOpen={menuOpen}
+ *   onClose={() => setMenuOpen(false)}
+ *   title="Navigation"
+ *   position="left"
+ *   size="w-72"
+ * >
+ *   <NavMenu />
+ * </ITDrawer>
+ * ```
+ */
 export default function ITDrawer({
   isOpen,
   onClose,

package/src/components/dropfile/dropfile.doc.mdx

@@ -0,0 +1,59 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './dropfile.stories';
+
+<Meta of={Stories} />
+
+# ITDropfile
+
+A drag-and-drop file upload zone with preview support for images. Tracks upload lifecycle with status enumeration and provides confirm/cancel actions. Configurable accepted file types limit which formats are allowed.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onFileSelect` | `(file: File \| null) => void` | — | Called when a file is selected or cleared. |
+| `onCancel` | `() => void` | — | Called when the user cancels the current selection. |
+| `onSubmit` | `(file: File) => void` | — | Called when the user confirms and submits the file. |
+| `acceptedFileTypes` | `FileTypeEnum[]` | — | List of accepted MIME types (PDF, XLS, CSV, PNG, JPG, etc.). |
+| `contentClassName` | `string` | — | CSS classes for the preview/content area. |
+| `containerClassName` | `string` | — | CSS classes for the outermost container. |
+| `showStatusBadge` | `boolean` | — | Whether to show the status badge (pending/uploading/uploaded/error). |
+| `uploadStatus` | `UploadStatus` | — | Externally controlled upload status. |
+| `onStatusChange` | `(status: UploadStatus) => void` | — | Callback when upload status changes. |
+| `initialPreviewUrl` | `string \| null` | — | Initial preview URL shown before any file is selected (e.g., editing an existing entry). |
+
+### Enums
+
+| Enum | Values |
+|------|--------|
+| `UploadStatus` | `PENDING` (`"pendiente"`), `UPLOADING` (`"subiendo"`), `UPLOADED` (`"subido"`), `ERROR` (`"error"`) |
+| `FileTypeEnum` | `PDF`, `XLS`, `XLSX`, `CSV`, `PNG`, `JPG`, `JPEG` |
+
+## Usage
+
+```tsx
+import { ITDropfile, UploadStatus, FileTypeEnum } from '@axzydev/axzy_ui_system';
+
+<ITDropfile
+  onFileSelect={(file) => setSelectedFile(file)}
+  onSubmit={(file) => uploadFile(file)}
+  onCancel={() => clearFile()}
+  acceptedFileTypes={[FileTypeEnum.PNG, FileTypeEnum.JPG, FileTypeEnum.PDF]}
+  uploadStatus={UploadStatus.PENDING}
+  showStatusBadge
+/>
+```
+
+## Notes
+
+- Displays image preview for image file types; shows a file icon for non-image types.
+- The `uploadStatus` and `showStatusBadge` props enable external lifecycle control and visual feedback.
+- `initialPreviewUrl` is useful for edit forms where an existing file is already associated.
+- Only one file at a time is supported — selecting a new file replaces the current one.
+- The confirm/cancel flow gives users a chance to review their selection before submission.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/dropfile/dropfile.props.ts

@@ -0,0 +1,41 @@
+/** Allowed file MIME types for the dropzone */
+export enum FileTypeEnum {
+  PDF = "application/pdf",
+  XLS = "application/vnd.ms-excel",
+  XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  CSV = "text/csv",
+  PNG = "image/png",
+  JPG = "image/jpg",
+  JPEG = "image/jpeg",
+}
+
+/** Upload lifecycle status */
+export enum UploadStatus {
+  PENDING = "pendiente",
+  UPLOADING = "subiendo",
+  UPLOADED = "subido",
+  ERROR = "error",
+}
+
+export interface ITDropfileProps {
+  /** Called when a file is selected or cleared. */
+  onFileSelect: (file: File | null) => void;
+  /** Called when the user cancels the current selection. */
+  onCancel?: () => void;
+  /** Called when the user confirms and submits the file. */
+  onSubmit?: (file: File) => void;
+  /** List of accepted MIME types. */
+  acceptedFileTypes?: FileTypeEnum[];
+  /** Additional classes for the preview/content area. */
+  contentClassName?: string;
+  /** Additional classes for the outermost container. */
+  containerClassName?: string;
+  /** Whether to show the status badge (pending/uploading/uploaded/error). */
+  showStatusBadge?: boolean;
+  /** Externally controlled upload status. */
+  uploadStatus?: UploadStatus;
+  /** Callback when upload status changes. */
+  onStatusChange?: (status: UploadStatus) => void;
+  /** An initial preview URL to display before any file is selected. */
+  initialPreviewUrl?: string | null;
+}

package/src/components/dropfile/dropfile.tsx

@@ -3,40 +3,28 @@ import { useDropzone } from "react-dropzone";
 // import pdfjsLib from "@/hooks/pdf"; // Disabled as hook is missing
 import clsx from "clsx";
 import ITText from "@/components/text/text";
+import { ITDropfileProps, FileTypeEnum, UploadStatus } from "./dropfile.props";
+export { FileTypeEnum, UploadStatus } from "./dropfile.props";
 
-/** Enum con tipos de archivo permitidos */
-export enum FileTypeEnum {
-  PDF = "application/pdf",
-  XLS = "application/vnd.ms-excel",
-  XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  CSV = "text/csv",
-  PNG = "image/png",
-  JPG = "image/jpg",
-  JPEG = "image/jpeg",
-}
-
-/** Enum para el estado de subida */
-export enum UploadStatus {
-  PENDING = "pendiente",
-  UPLOADING = "subiendo",
-  UPLOADED = "subido",
-  ERROR = "error",
-}
-
-/** Props del componente */
-export interface ITDropfileProps {
-  onFileSelect: (file: File | null) => void;
-  onCancel?: () => void;
-  onSubmit?: (file: File) => void;
-  acceptedFileTypes?: FileTypeEnum[];
-  contentClassName?: string;
-  containerClassName?: string;
-  showStatusBadge?: boolean;
-  uploadStatus?: UploadStatus;
-  onStatusChange?: (status: UploadStatus) => void;
-  initialPreviewUrl?: string | null;
-}
-
+/**
+ * Drag-and-drop file uploader with preview, status tracking, and confirmation flow.
+ *
+ * Supports configurable accepted file types (PDF, Excel, CSV, images), visual
+ * drag-active feedback, image previews, and a three-step workflow: select →
+ * confirm → upload. Upload status is tracked internally or controlled
+ * externally via the `uploadStatus` prop. Re-exports `FileTypeEnum` and
+ * `UploadStatus` enums for consuming code.
+ *
+ * @example
+ * ```tsx
+ * <ITDropfile
+ *   onFileSelect={(file) => setSelectedFile(file)}
+ *   onSubmit={(file) => uploadToServer(file)}
+ *   acceptedFileTypes={[FileTypeEnum.PDF, FileTypeEnum.XLSX]}
+ *   showStatusBadge
+ * />
+ * ```
+ */
 const ITDropfile: React.FC<ITDropfileProps> = ({
   onFileSelect,
   onCancel,

package/src/components/empty-state/empty-state.doc.mdx

@@ -0,0 +1,50 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './empty-state.stories';
+
+<Meta of={Stories} />
+
+# ITEmptyState
+
+A placeholder component for displaying a message when no data is available. Configurable icon, title, description, and an action slot for contextual buttons.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `ReactNode` | `<FaInbox size={40} />` | Icon or illustration displayed above the title. |
+| `title` | `string` | — | Primary heading text (required). |
+| `description` | `string` | — | Secondary explanatory text. |
+| `action` | `ReactNode` | — | Action element (typically a button) rendered below the description. |
+| `className` | `string` | — | Additional CSS classes for the wrapper. |
+
+## Usage
+
+```tsx
+import { ITEmptyState } from '@axzydev/axzy_ui_system';
+
+<ITEmptyState
+  title="No results"
+  description="No data found for the selected filters."
+  action={<ITButton label="Clear filters" variant="outlined" size="small" />}
+/>
+
+<ITEmptyState
+  icon={<FaDatabase size={48} />}
+  title="No records"
+  description="Create your first record to get started."
+  action={<ITButton label="Create Record" variant="primary" />}
+/>
+```
+
+## Notes
+
+- Default icon is `FaInbox` from react-icons — override with any ReactNode for custom illustrations.
+- The `action` slot accepts any ReactNode, most commonly an `ITButton` for navigation or reset actions.
+- Centers all content vertically and horizontally within its container.
+- Works well as a fallback inside tables, cards, and search result containers.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/empty-state/empty-state.props.ts

@@ -1,9 +1,14 @@
 import { ReactNode } from "react";
 
 export interface ITEmptyStateProps {
+  /** Icon or illustration displayed above the title. @default <FaInbox size={40} /> */
   icon?: ReactNode;
+  /** Primary heading text (required). */
   title: string;
+  /** Secondary explanatory text shown below the title. */
   description?: string;
+  /** Action element (typically a button) rendered below the description. */
   action?: ReactNode;
+  /** Additional CSS classes for the wrapper element. */
   className?: string;
 }

package/src/components/empty-state/empty-state.tsx

@@ -3,6 +3,22 @@ import { ITEmptyStateProps } from "./empty-state.props";
 import { FaInbox } from "react-icons/fa";
 import ITText from "@/components/text/text";
 
+/**
+ * Placeholder display for empty data sets.
+ *
+ * Shows a large icon, a title, an optional description, and an optional
+ * call-to-action element (usually a button). Centered vertically and
+ * horizontally within its container.
+ *
+ * @example
+ * ```tsx
+ * <ITEmptyState
+ *   title="No results found"
+ *   description="Try adjusting your search or filters."
+ *   action={<ITButton label="Clear filters" variant="outlined" onClick={clearFilters} />}
+ * />
+ * ```
+ */
 export default function ITEmptyState({
   icon = <FaInbox size={40} />,
   title,

package/src/components/flex/flex.doc.mdx

@@ -0,0 +1,59 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './flex.stories';
+
+<Meta of={Stories} />
+
+# ITFlex
+
+A complete flexbox layout container exposing the full CSS Flexbox API through React props. Supports direction, wrap, alignment, justification, gap, grow, shrink, basis, and custom element rendering.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | Child elements inside the flex container. |
+| `direction` | `"row" \| "column" \| "row-reverse" \| "column-reverse"` | — | Main axis direction. |
+| `align` | `"start" \| "end" \| "center" \| "stretch" \| "baseline"` | — | Cross-axis alignment. |
+| `justify` | `"start" \| "end" \| "center" \| "between" \| "around" \| "evenly"` | — | Main-axis justification. |
+| `wrap` | `"nowrap" \| "wrap" \| "wrap-reverse"` | — | Wrapping behavior. |
+| `gap` | `number` | — | Gap between children in units of `0.25rem`. |
+| `grow` | `boolean \| number` | — | Flex grow factor. `true` = 1, `false` = 0, or pass a number. |
+| `shrink` | `boolean \| number` | — | Flex shrink factor. Works like `grow`. |
+| `basis` | `string \| number` | — | Flex basis value. Numbers multiplied by `0.25rem`; strings used as-is. |
+| `className` | `string` | — | Additional CSS classes. |
+| `style` | `CSSProperties` | — | Inline styles. |
+| `as` | `ElementType` | `"div"` | Custom HTML element type to render. |
+| `onClick` | `(e: React.MouseEvent) => void` | — | Click handler. |
+
+## Usage
+
+```tsx
+import { ITFlex } from '@axzydev/axzy_ui_system';
+
+<ITFlex direction="row" gap={3} justify="between" align="center">
+  <div>Left</div>
+  <div>Center</div>
+  <div>Right</div>
+</ITFlex>
+
+<ITFlex direction="column" gap={2} className="h-60">
+  <ITFlex grow className="bg-primary-100 rounded-lg p-4">
+    <span>Grow (flex: 1)</span>
+  </ITFlex>
+  <div className="w-full">Fixed height</div>
+</ITFlex>
+```
+
+## Notes
+
+- `gap` accepts an integer where `1` = `0.25rem` (4px), `4` = `1rem` (16px), etc., matching Tailwind's spacing scale.
+- The `as` prop allows rendering as a `<section>`, `<nav>`, `<form>`, or any other semantic HTML element.
+- `grow` and `shrink` accept `boolean` for quick on/off or `number` for precise flex factor control.
+- Combine `basis`, `grow`, and `shrink` for complete flex item control on the container itself.
+- All flex props are optional — the component renders as a standard `div` when no layout props are set.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/flex/flex.props.ts

@@ -6,17 +6,30 @@ export type FlexJustify = "start" | "end" | "center" | "between" | "around" | "e
 export type FlexWrap = "nowrap" | "wrap" | "wrap-reverse";
 
 export interface ITFlexProps {
+  /** Child elements to render inside the flex container */
   children?: ReactNode;
+  /** Main axis direction: "row" | "column" | "row-reverse" | "column-reverse" */
   direction?: FlexDirection;
+  /** Cross-axis alignment: "start" | "end" | "center" | "stretch" | "baseline" */
   align?: FlexAlign;
+  /** Main-axis justification: "start" | "end" | "center" | "between" | "around" | "evenly" */
   justify?: FlexJustify;
+  /** Wrapping behavior: "nowrap" | "wrap" | "wrap-reverse" */
   wrap?: FlexWrap;
+  /** Gap between children in units of 0.25rem */
   gap?: number;
+  /** Flex grow factor. Pass `true` for 1, `false` for 0, or a number */
   grow?: boolean | number;
+  /** Flex shrink factor. Pass `true` for 1, `false` for 0, or a number */
   shrink?: boolean | number;
+  /** Flex basis value. Numbers are multiplied by 0.25rem; strings used as-is */
   basis?: string | number;
+  /** Additional CSS classes */
   className?: string;
+  /** Inline styles */
   style?: CSSProperties;
+  /** Custom HTML element type to render instead of the default `div` */
   as?: ElementType;
+  /** Click handler */
   onClick?: (e: React.MouseEvent) => void;
 }

package/src/components/flex/flex.tsx

@@ -37,6 +37,21 @@ const wrapMap: Record<FlexWrap, string> = {
   "wrap-reverse": "flex-wrap-reverse",
 };
 
+/**
+ * A complete flexbox container with all alignment and spacing options.
+ *
+ * @example
+ * <ITFlex direction="row" justify="between" align="center" gap={4}>
+ *   <div>Left</div>
+ *   <div>Right</div>
+ * </ITFlex>
+ *
+ * @example
+ * <ITFlex direction="column" gap={2} as="section">
+ *   <header>Title</header>
+ *   <main>Content</main>
+ * </ITFlex>
+ */
 export default function ITFlex({
   children,
   direction = "row",

package/src/components/form-builder/fieldRenderer.tsx

@@ -1,4 +1,4 @@
-import React, { memo, useCallback, useEffect } from "react";
+import React, { memo, useCallback, useEffect, useState } from "react";
 import clsx from "clsx";
 import { FieldConfigV2 } from "@/types/field.types";
 import { useITFormBuilderContext } from "./formBuilder.context";
@@ -6,9 +6,30 @@ import ITInput from "../input/input";
 import ITSelect from "../select/select";
 import ITDatePicker from "../date-picker/datePicker";
 import ITTimePicker from "../time-picker/timePicker";
+import ITSearchSelect from "../search-select/search-select";
 import { useFieldRules } from "./useFormBuilder";
 import { getColSpanClass, getGridColsClass } from "@/utils/styles";
 import ITText from "@/components/text/text";
+import { FaSpinner } from "react-icons/fa";
+
+function useAsyncOptions(options: FieldConfigV2["options"], depends: any[]) {
+  const [resolved, setResolved] = useState<{ value: string; label: string }[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (typeof options === "function") {
+      setLoading(true);
+      options().then((result) => {
+        setResolved(result.map(o => ({ value: String(o.value), label: o.label })));
+        setLoading(false);
+      });
+    } else if (Array.isArray(options)) {
+      setResolved(options.map(o => ({ value: String(o.value), label: o.label })));
+    }
+  }, depends);
+
+  return { options: resolved, loading };
+}
 
 
 
@@ -65,6 +86,8 @@ const ITFieldRenderer = ({
     rightIcon,
   } = activeConfig;
 
+  const { options: resolvedOptions, loading: optionsLoading } = useAsyncOptions(options, [options, dependentValues]);
+
   const handleChangeWrapper = useCallback(
     async (val: any) => {
       const finalValue = val?.target ? val.target.value : val;
@@ -107,9 +130,36 @@ const ITFieldRenderer = ({
         );
 
       case "select":
+        if (optionsLoading) {
+          return (
+            <div className="flex items-center gap-2 py-3">
+              <FaSpinner className="animate-spin text-primary-500" />
+              <ITText as="span" className="text-sm text-slate-500">Cargando opciones...</ITText>
+            </div>
+          );
+        }
+        if (typeof options === "function") {
+          return (
+            <ITSearchSelect
+              options={resolvedOptions}
+              name={name}
+              disabled={isDisabled as boolean}
+              label={label || ""}
+              placeholder={placeholder}
+              value={value !== undefined ? value : activeConfig.defaultValue || ""}
+              valueField={valueField || "value"}
+              labelField={labelField || "label"}
+              onChange={(val: any) => handleChangeWrapper(val)}
+              onBlur={context.handleBlur}
+              touched={touched}
+              error={error}
+              required={isRequired as boolean}
+            />
+          );
+        }
         return (
           <ITSelect
-            options={(Array.isArray(options) ? options : []) as any}
+            options={resolvedOptions}
             name={name}
             disabled={isDisabled as boolean}
             label={label || ""}