@axzydev/axzy_ui_system 1.2.9 → 1.2.12

package/src/theme/theme.ts

@@ -160,7 +160,7 @@ export const components = {
       hover: semanticColors.primary[600],
       active: semanticColors.primary[700],
       focus: `0 0 0 2px ${semanticColors.primary[200]}`,
-      borderRadius: '0.375rem', 
+      borderRadius: 'var(--radius-md)', 
       padding: '0.5rem 1rem',
       fontSize: '0.875rem',
       fontWeight: '600',
@@ -172,7 +172,7 @@ export const components = {
       color: '#ffffff',
       hover: semanticColors.secondary[600],
       focus: `0 0 0 2px ${semanticColors.secondary[200]}`,
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
       padding: '0.5rem 1rem',
       fontSize: '0.875rem',
       fontWeight: '600',
@@ -183,7 +183,7 @@ export const components = {
       color: '#ffffff',
       hover: semanticColors.success[600],
       focus: `0 0 0 2px ${semanticColors.success[200]}`,
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
 
     danger: {
@@ -191,14 +191,14 @@ export const components = {
       color: '#ffffff',
       hover: semanticColors.danger[600],
       focus: `0 0 0 2px ${semanticColors.danger[200]}`,
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
 
     error: {
       backgroundColor: semanticColors.danger[500],
       color: '#ffffff',
       hover: semanticColors.danger[600],
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
 
     warning: {
@@ -206,7 +206,7 @@ export const components = {
       color: '#ffffff',
       hover: semanticColors.warning[600],
       focus: `0 0 0 2px ${semanticColors.warning[200]}`,
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
 
     info: {
@@ -214,7 +214,7 @@ export const components = {
       color: '#ffffff',
       hover: semanticColors.info[600],
       focus: `0 0 0 2px ${semanticColors.info[200]}`,
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
 
     purple: {
@@ -222,7 +222,7 @@ export const components = {
       color: '#ffffff',
       hover: semanticColors.purple[600],
       focus: `0 0 0 2px ${semanticColors.purple[200]}`,
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
     
     outline: {
@@ -231,7 +231,7 @@ export const components = {
       borderColor: semanticColors.primary[600],
       borderWidth: '2px', 
       hover: semanticColors.primary[50],
-      borderRadius: '0.375rem',
+      borderRadius: 'var(--radius-md)',
     },
   },
   
@@ -291,19 +291,19 @@ export const components = {
 
   card: {
     backgroundColor: 'var(--card-bg, #ffffff)',
-    borderRadius: '1rem',
+    borderRadius: 'var(--radius-2xl)',
     borderColor: `var(--card-border, ${semanticColors.gray[200]})`,
     borderWidth: '1px',
-    shadow: 'var(--card-shadow, 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1))',
+    shadow: 'var(--card-shadow, var(--shadow-md))',
     hover: {
-      shadow: 'var(--card-shadow-hover, 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1))',
+      shadow: 'var(--card-shadow-hover, var(--shadow-lg))',
     },
     header: {
       backgroundColor: `var(--card-header-bg, ${semanticColors.gray[50]})`,
       borderBottom: `1px solid var(--card-header-border, var(--color-secondary-200))`,
       padding: '1rem 1.5rem',
-      borderTopLeftRadius: '1rem',
-      borderTopRightRadius: '1rem',
+      borderTopLeftRadius: 'var(--radius-2xl)',
+      borderTopRightRadius: 'var(--radius-2xl)',
     },
     body: {
       padding: '1.5rem',
@@ -313,7 +313,7 @@ export const components = {
   input: {
     backgroundColor: 'var(--input-bg, #ffffff)',
     borderColor: `var(--input-border, ${semanticColors.gray[300]})`,
-    borderRadius: '0.5rem',
+    borderRadius: 'var(--radius-md)',
     padding: '0.5rem 0.75rem',
     fontSize: '0.875rem',
     focus: {
@@ -382,8 +382,8 @@ export const components = {
     },
     content: {
       backgroundColor: 'var(--modal-bg, #ffffff)',
-      borderRadius: '1rem',
-      shadow: 'var(--modal-shadow, 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1))',
+      borderRadius: 'var(--radius-2xl)',
+      shadow: 'var(--modal-shadow, var(--shadow-xl))',
     },
     header: {
       padding: '1.5rem 1.5rem 0.5rem 1.5rem',
@@ -452,6 +452,26 @@ export const typography = {
   },
 };
 
+/**
+ * 4.5. Escala de Z-Index (capas de UI global)
+ * Fuente de verdad documentada para las clases z-[N] usadas en overlays fixed/absolute.
+ * Tailwind JIT requiere clases estáticas en el JSX, así que los componentes aplican
+ * el valor literal correspondiente, pero SIEMPRE debe coincidir con esta escala.
+ * Orden ascendente = se pinta más arriba.
+ */
+export const zIndex = {
+  /** Barras sticky (ITTopbar) y overlays de navegación (sidebar/aside móvil). */
+  navOverlay: 40,
+  /** Paneles deslizantes (ITDrawer). */
+  drawer: 50,
+  /** Diálogos modales (ITDialog, ITConfirmDialog). */
+  modal: 60,
+  /** UI flotante contextual: dropdowns, ITPopover, ITTooltip, ITDatePicker/ITTimePicker. */
+  floating: 70,
+  /** Notificaciones globales (ITToast) — siempre por encima de todo lo demás. */
+  toast: 80,
+} as const;
+
 /**
  * 5. Theme final exportado
  */
@@ -459,5 +479,6 @@ export const theme = {
   palette, 
   colors: semanticColors,
   typography,
+  zIndex,
   ...components,
 };

package/src/types/field.types.ts

@@ -2,26 +2,47 @@ import React from "react";
 import * as Yup from "yup";
 
 // Legacy FieldConfig (kept for backward compatibility during migration)
+/** @deprecated Legacy (V1) field definition consumed by `ITFormBuilder`'s `fields` prop. Prefer `FieldConfigV2` via the `config` prop for new forms. */
 export interface FieldConfig {
+  /** Field name, matches the key in Formik's `values`/`errors`/`touched` objects. */
   name: string;
+  /** Label text rendered above the field. */
   label: string;
+  /** Input type. @default "text" */
   type?: "text" | "select" | "date" | "password" | "number";
+  /** Formats a numeric field with thousands separators/currency styling as the user types. @default false */
   currencyFormat?: boolean;
+  /** Placeholder text shown when the field is empty. */
   placeholder?: string;
+  /** Disables the field. @default false */
   disabled?: boolean;
+  /** Marks the field as required (shows an asterisk and enables the built-in required message). @default false */
   required?: boolean;
+  /** Yup schema used to validate this field. */
   validation?: Yup.AnySchema;
+  /** Grid column span (1-12), or `[sm, md, lg]` breakpoint-specific spans. */
   column?: number | number[];
+  /** Options for `type: "select"`. */
   options?: { value: string; label: string }[];
+  /** Icon element rendered on the right side of the field. */
   rightIcon?: React.ReactNode;
+  /** Icon element rendered on the left side of the field. */
   leftIcon?: React.ReactNode;
+  /** Key read from each option object as its value. @default "value" */
   valueField?: string;
+  /** Shows a live character-count hint below the field. @default false */
   showHintLength?: boolean;
+  /** Key read from each option object as its display label. @default "label" */
   labelField?: string;
+  /** Maximum character length allowed. */
   maxLength?: number;
+  /** Minimum character length required. */
   minLength?: number;
+  /** Number of visible text rows for a multi-line field. */
   rows?: number;
+  /** Applies number formatting (thousand separators) as the user types. @default false */
   formatNumber?: boolean;
+  /** Custom side-effect fired on change, in addition to the normal Formik update. Receives the new value and Formik's `setFieldValue`. */
   onChangeAction?: (value: any, setFieldValue: any) => void;
 }
 
@@ -29,6 +50,7 @@ export interface FieldConfig {
 // V2: ENTERPRISE FORM BUILDER ARCHITECTURE
 // -------------------------------------------------------------
 
+/** Supported field kinds for `FieldConfigV2`. */
 export type FieldTypeV2 = 
   | "text" 
   | "number" 
@@ -43,61 +65,102 @@ export type FieldTypeV2 =
   | "section"   // For grouping fields or wizard steps
   | "custom";   // For inversion of control (injecting external components)
 
+/** Form state/helpers passed into `dynamicProps`, `renderWhen`, and `onChangeAction` callbacks for `FieldConfigV2`. */
 export interface FieldContextV2 {
+  /** Current values for every field in the form, keyed by field `name`. */
   values: Record<string, any>;
+  /** Programmatically sets a field's value (mirrors Formik's `setFieldValue`). */
   setFieldValue: (field: string, value: any, shouldValidate?: boolean) => void;
+  /** Programmatically sets a field-level error message. */
   setFieldError: (field: string, error: string) => void;
+  /** Programmatically marks a field as touched, e.g. to surface its validation error. */
   setFieldTouched: (field: string, touched?: boolean, shouldValidate?: boolean) => void;
 }
 
+/**
+ * V2 field definition consumed by `ITFormBuilder`'s `config` prop. Supports
+ * conditional rendering/props, nested sections and repeatable arrays, async
+ * options, and custom-component injection.
+ */
 export interface FieldConfigV2 {
+  /** Field name, matches the key in Formik's `values`/`errors`/`touched` objects. For `type: "array"`/`"section"`, this is the key under which the nested `fields` values are grouped. */
   name: string;
+  /** Label text rendered above the field (or as the section/array heading). */
   label?: string;
+  /** Field kind. Determines which input is rendered and which of the props below apply. */
   type: FieldTypeV2;
-  
+
   // 1. Layout & Structure
+  /** Grid column span (1-12), or an object with per-breakpoint spans (`sm`/`md`/`lg`/`xl`). */
   column?: number | { sm?: number; md?: number; lg?: number; xl?: number };
+  /** Nested field definitions. Required when `type` is `"array"` (the repeatable item shape) or `"section"` (the grouped fields). */
   fields?: FieldConfigV2[]; // REQUIRED if type is "array" or "section"
+  /** For `type: "section"`, allows the section to be collapsed/expanded by the user. @default false */
   collapsible?: boolean;    // Optional for "section", default false
+  /** For a `collapsible` section, whether it starts collapsed. @default false */
   defaultCollapsed?: boolean;
-  
+
   // 2. Rules Engine & Dynamic Behavior
+  /** Sibling field names this field depends on; changes to any of them re-evaluate `renderWhen`/`dynamicProps`. */
   dependsOn?: string[]; // Array of sibling field names to listen to for re-evaluation
+  /** Determines whether this field is rendered (and included in submission) based on current form values. Re-evaluated when any field in `dependsOn` changes. Field is shown when omitted. */
   renderWhen?: (values: Record<string, any>) => boolean; // If false, field isn't rendered or submitted
+  /** Computes a partial override of this field's own config from current form values (e.g. make it `required` once another field exceeds a threshold). Re-evaluated when any field in `dependsOn` changes. */
   dynamicProps?: (values: Record<string, any>) => Partial<FieldConfigV2>; // E.g: if A > 100, make this required
-  
+
   // 3. Advanced Validations
+  /** Yup schema used to validate this field. */
   validation?: Yup.AnySchema; 
+  /** Async validator (e.g. a uniqueness check against an API). Return an error string when invalid, or `null`/`undefined` when valid. */
   asyncValidation?: (value: any, values: Record<string, any>) => Promise<string | null | undefined>; // Returns error string if invalid
-  
+
   // 4. Base Props
+  /** Initial value used when the form is first initialized/reset. */
   defaultValue?: any;
+  /** Placeholder text shown when the field is empty. */
   placeholder?: string;
+  /** Disables the field, either statically or computed from current form values. @default false */
   disabled?: boolean | ((values: Record<string, any>) => boolean);
+  /** Renders the field as read-only (visible but not editable). @default false */
   readOnly?: boolean;
+  /** Marks the field as required, either statically or computed from current form values. @default false */
   required?: boolean | ((values: Record<string, any>) => boolean);
-  
+
   // 5. Data Support (Sync & Async)
+  /** Options for `"select"`/`"radio"` fields: a static array, or an async loader function called once the field mounts. */
   options?: 
     | { value: string | number; label: string }[] 
     | (() => Promise<{ value: string | number; label: string }[]>);
+  /** Key read from each option object as its value. @default "value" */
   valueField?: string;
+  /** Key read from each option object as its display label. @default "label" */
   labelField?: string;
-  
+
   // 6. Extensibility & UI
+  /** Icon element rendered on the left side of the field. */
   leftIcon?: React.ReactNode;
+  /** Icon element rendered on the right side of the field. */
   rightIcon?: React.ReactNode;
+  /** Custom component rendered instead of a built-in input when `type` is `"custom"`. */
   component?: React.ComponentType<any>; // Custom component for type === "custom"
+  /** Additional CSS class applied to the field's container. */
   className?: string; // Custom container class
-  
+
   // Legacy specific overrides
+  /** Formats a numeric field with thousands separators/currency styling as the user types. @default false */
   currencyFormat?: boolean;
+  /** Shows a live character-count hint below the field. @default false */
   showHintLength?: boolean;
+  /** Maximum character length allowed. */
   maxLength?: number;
+  /** Minimum character length required. */
   minLength?: number;
+  /** Number of visible text rows for a multi-line field. */
   rows?: number;
+  /** Applies number formatting (thousand separators) as the user types. @default false */
   formatNumber?: boolean;
 
   // Lifecycle hook
+  /** Custom side-effect fired whenever this field's value changes. Receives the new value and the shared `FieldContextV2` helpers. */
   onChangeAction?: (val: any, context: FieldContextV2) => void | Promise<void>;
 }

package/src/utils/styles.ts

@@ -9,20 +9,20 @@ export function inputContainer(hasError?: boolean, disabled?: boolean) {
     "w-full border border-solid transition-all duration-200 rounded-lg px-3 py-2 text-sm",
     "focus:outline-none focus:ring-2",
     hasError
-      ? "border-red-500 ring-red-100"
-      : "border-gray-300 focus:border-primary-500 focus:ring-primary-100",
-    disabled && "opacity-50 cursor-not-allowed bg-gray-100"
+      ? "border-danger-500 ring-danger-100"
+      : "border-secondary-300 focus:border-primary-500 focus:ring-primary-100",
+    disabled && "opacity-50 cursor-not-allowed bg-secondary-100"
   );
 }
 
 export function inputLabel(error?: boolean) {
   return clsx(
     "text-sm font-medium",
-    error ? "text-red-500" : "text-gray-700 dark:text-slate-300"
+    error ? "text-danger-500" : "text-secondary-700 dark:text-secondary-300"
   );
 }
 
-export const inputError = "text-red-500 text-xs mt-1";
+export const inputError = "text-danger-500 text-xs mt-1";
 
 export function inputWrapper(className?: string) {
   return clsx("flex flex-col gap-1.5", className);