@axzydev/axzy_ui_system 1.2.8 → 1.2.11

package/src/showcases/GettingStartedShowcase.tsx

@@ -0,0 +1,207 @@
+import { FaNpm, FaReact, FaCheck } from "react-icons/fa";
+import { SiTailwindcss, SiTypescript, SiVite } from "react-icons/si";
+import { useState } from "react";
+import ITBadget from "../components/badget/badget";
+import ITButton from "../components/button/button";
+import ITCard from "../components/card/card";
+import ITDivider from "../components/divider/divider";
+import ITFlex from "../components/flex/flex";
+import ITGrid from "../components/grid/grid";
+import ITStack from "../components/stack/stack";
+import ITText from "../components/text/text";
+
+const CopyButton = ({ text }: { text: string }) => {
+  const [copied, setCopied] = useState(false);
+  return (
+    <ITButton
+      variant="text"
+      color="gray"
+      size="small"
+      onClick={() => { navigator.clipboard.writeText(text); setCopied(true); setTimeout(() => setCopied(false), 2000); }}
+    >
+      <ITFlex align="center" gap={1.5}>
+        {copied ? <FaCheck size={10} className="text-emerald-400" /> : <FaNpm size={10} />}
+        {copied ? "Copiado" : "Copiar"}
+      </ITFlex>
+    </ITButton>
+  );
+};
+
+const CodeBlock = ({ code, filename, color }: { code: string; filename?: string; color?: string }) => (
+  <div className="overflow-hidden rounded-xl border border-slate-200 dark:border-slate-700 bg-white dark:bg-slate-900">
+    {filename && (
+      <div className={`px-4 py-2 border-b border-slate-200 dark:border-slate-700 ${color || "bg-slate-50 dark:bg-slate-800/80"}`}>
+        <ITText as="span" className="!text-xs !font-mono !text-slate-400">{filename}</ITText>
+      </div>
+    )}
+    <div className="relative bg-slate-950">
+      <pre className="p-4 text-xs font-mono overflow-x-auto leading-relaxed text-slate-200">
+        <code>{code}</code>
+      </pre>
+    </div>
+  </div>
+);
+
+const codeFileColors = [
+  "bg-emerald-50 dark:bg-emerald-950/30",
+  "bg-blue-50 dark:bg-blue-950/30",
+  "bg-cyan-50 dark:bg-cyan-950/30",
+  "bg-violet-50 dark:bg-violet-950/30",
+  "bg-amber-50 dark:bg-amber-950/30",
+  "bg-rose-50 dark:bg-rose-950/30",
+];
+
+const stepStyles = [
+  { iconBg: "bg-emerald-100 dark:bg-emerald-950/40 text-emerald-600 dark:text-emerald-400" },
+  { iconBg: "bg-blue-100 dark:bg-blue-950/40 text-blue-600 dark:text-blue-400" },
+  { iconBg: "bg-cyan-100 dark:bg-cyan-950/40 text-cyan-600 dark:text-cyan-400" },
+  { iconBg: "bg-violet-100 dark:bg-violet-950/40 text-violet-600 dark:text-violet-400" },
+  { iconBg: "bg-amber-100 dark:bg-amber-950/40 text-amber-600 dark:text-amber-400" },
+  { iconBg: "bg-rose-100 dark:bg-rose-950/40 text-rose-600 dark:text-rose-400" },
+];
+
+const steps = [
+  {
+    icon: <FaNpm size={14} />,
+    title: "Instalar dependencias",
+    desc: "Tailwind v4 y su plugin para Vite.",
+    filename: "terminal",
+    code: "npm install @axzydev/axzy_ui_system\nnpm install -D tailwindcss @tailwindcss/vite @vitejs/plugin-react-swc",
+  },
+  {
+    icon: <SiVite size={14} />,
+    title: "Configurar Vite",
+    desc: "Agrega Tailwind como plugin de Vite.",
+    filename: "vite.config.ts",
+    code: `import { defineConfig } from "vite"
+import react from "@vitejs/plugin-react-swc"
+import tailwindcss from "@tailwindcss/vite"
+
+export default defineConfig({
+  plugins: [tailwindcss(), react()],
+})`,
+  },
+  {
+    icon: <SiTailwindcss size={14} />,
+    title: "Agregar Tailwind",
+    desc: "Importa Tailwind en tu archivo CSS.",
+    filename: "src/index.css",
+    code: `@import "tailwindcss";
+@variant dark (&:is(.dark &));`,
+  },
+  {
+    icon: <FaReact size={14} />,
+    title: "Importar estilos",
+    desc: "Envuelve tu app con el provider.",
+    filename: "src/main.tsx",
+    code: `import { ITThemeProvider } from "@axzydev/axzy_ui_system"
+import "@axzydev/axzy_ui_system/dist/index.css"
+
+<ITThemeProvider>
+  <App />
+</ITThemeProvider>`,
+  },
+  {
+    icon: <SiTypescript size={14} />,
+    title: "Declaración de tipos",
+    desc: "Para que TS acepte imports CSS.",
+    filename: "src/vite-env.d.ts",
+    code: `/// <reference types="vite/client" />
+
+declare module "*.css" {
+  const content: string
+  export default content
+}`,
+  },
+  {
+    icon: <FaReact size={14} />,
+    title: "Primer componente",
+    desc: "Ya puedes usar cualquier componente.",
+    filename: "src/App.tsx",
+    code: `import { ITButton } from "@axzydev/axzy_ui_system"
+
+export default function App() {
+  return <ITButton variant="rounded">Empezar</ITButton>
+}`,
+  },
+];
+
+export const GettingStartedShowcase = () => {
+  return (
+    <ITStack spacing={10}>
+      {/* ─── HERO ─── */}
+      <ITCard className="overflow-hidden border-0 bg-gradient-to-br from-primary-50 via-white to-purple-50 dark:from-primary-950/20 dark:via-slate-900 dark:to-purple-950/20 shadow-sm">
+        <div className="relative">
+          <div className="absolute -top-40 -right-40 w-[500px] h-[500px] bg-primary-500/10 rounded-full blur-[120px] pointer-events-none" />
+          <div className="absolute -bottom-40 -left-40 w-[500px] h-[500px] bg-purple-500/10 rounded-full blur-[120px] pointer-events-none" />
+
+          <ITStack spacing={5} className="relative z-10">
+            <ITStack spacing={2}>
+              <ITBadget label="v1.0.0" color="primary" variant="outlined" className="w-fit" />
+              <ITText as="h1" className="!text-4xl !font-bold !tracking-tight">
+                AXZY UI System
+              </ITText>
+              <ITText as="p" muted className="!text-base !leading-relaxed max-w-xl">
+                Librería de componentes React con Tailwind CSS v4. Diseñada para apps enterprise con experiencia de desarrollo fluida.
+              </ITText>
+            </ITStack>
+
+            <ITFlex gap={3} wrap="wrap" align="center">
+              <div className="px-4 py-2 rounded-xl bg-gradient-to-r from-primary-50 to-purple-50 dark:from-primary-950/30 dark:to-purple-950/30 border border-primary-200 dark:border-primary-800/50 shadow-sm">
+                <ITFlex align="center" gap={2}>
+                  <FaNpm size={16} className="text-primary-500" />
+                  <code className="text-sm font-mono text-slate-800 dark:text-slate-200">npm install @axzydev/axzy_ui_system</code>
+                  <CopyButton text="npm install @axzydev/axzy_ui_system" />
+                </ITFlex>
+              </div>
+            </ITFlex>
+          </ITStack>
+        </div>
+      </ITCard>
+
+      {/* ─── SETUP STEPS ─── */}
+      <ITGrid container spacing={6}>
+        {steps.map((step, i) => (
+          <ITGrid item xs={12} md={6} key={i}>
+            <ITCard className="border-slate-200/60 dark:border-slate-800/60 shadow-sm h-full">
+              <ITStack spacing={4}>
+                <ITFlex align="center" gap={2.5}>
+                  <div className={`w-8 h-8 rounded-lg ${stepStyles[i].iconBg} flex items-center justify-center`}>
+                    {step.icon}
+                  </div>
+                  <div>
+                    <ITText as="p" className="!text-sm !font-semibold">{step.title}</ITText>
+                    <ITText as="p" className="!text-xs !text-slate-400">{step.desc}</ITText>
+                  </div>
+                </ITFlex>
+                <CodeBlock code={step.code} filename={step.filename} color={codeFileColors[i]} />
+              </ITStack>
+            </ITCard>
+          </ITGrid>
+        ))}
+      </ITGrid>
+
+      {/* ─── THEMING ─── */}
+      <ITCard title="Theming" className="border-purple-200/60 dark:border-purple-800/60 shadow-sm">
+        <ITStack spacing={4}>
+          <ITText as="p" className="!text-sm" muted>
+            Personaliza colores en runtime. Solo necesitas los que quieras cambiar.
+          </ITText>
+          <div className="bg-gradient-to-r from-purple-50 via-fuchsia-50 to-pink-50 dark:from-purple-950/20 dark:via-fuchsia-950/20 dark:to-pink-950/20 rounded-xl p-5 border border-purple-200 dark:border-purple-800/30">
+            <CodeBlock
+              code={`const myTheme = {
+  colors: {
+    primary: { 50: "#fef2f2", 500: "#ef4444" },
+  },
+}
+
+<ITThemeProvider theme={myTheme}>
+  <App />
+</ITThemeProvider>`}
+            />
+          </div>
+        </ITStack>
+      </ITCard>
+    </ITStack>
+  );
+};

package/src/showcases/HomeShowcase.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react";
-import { FaCloud, FaCode, FaDatabase, FaDownload, FaGithub, FaLayerGroup, FaLinkedin, FaMapMarkerAlt, FaMobileAlt, FaSearch, FaServer, FaMedium } from "react-icons/fa";
+import { FaArrowRight, FaCheck, FaCloud, FaCode, FaDatabase, FaDownload, FaExternalLinkAlt, FaGithub, FaLayerGroup, FaLinkedin, FaMapMarkerAlt, FaMobileAlt, FaSearch, FaServer, FaMedium } from "react-icons/fa";
+import { SiReact, SiNodedotjs } from "react-icons/si";
 import ITBadget from "../components/badget/badget";
 import ITButton from "../components/button/button";
 import ITCard from "../components/card/card";
@@ -94,7 +95,7 @@ export const HomeShowcase = () => {
                   <div className="w-56 h-56 md:w-64 md:h-64 rounded-full shadow-xl overflow-hidden ring-2 ring-slate-200 dark:ring-slate-700">
                     <img
                       src="/personalFoto.jpg"
-                      alt="Asael Amaroaqui"
+                      alt="Asael Amaro"
                       className="w-full h-full object-cover"
                     />
                   </div>
@@ -109,7 +110,7 @@ export const HomeShowcase = () => {
                 <ITStack spacing={2}>
                   <ITBadget label="Portafolio Personal" color="primary" variant="outlined" className="w-fit" />
                   <ITText as="h1" className="text-4xl md:text-5xl font-bold tracking-tight text-slate-900 dark:text-white">
-                    Hola, soy <span className="text-primary-600 dark:text-primary-400">Asael Amaroaqui</span>
+                    Hola, soy <span className="text-primary-600 dark:text-primary-400">Asael Amaro</span>
                   </ITText>
                   <ITText as="p" muted className="text-base leading-relaxed max-w-xl">
                     Fullstack Developer con 4+ años de experiencia creando aplicaciones web modernas. 
@@ -299,6 +300,97 @@ export const HomeShowcase = () => {
           </ITText>
         </ITStack>
       </ITCard>
+
+      {/* ─── MIS PRODUCTOS ─── */}
+      <ITCard
+        title="Mis Productos"
+        className="border-slate-200/60 dark:border-slate-800/60 shadow-sm"
+      >
+        <ITText as="p" muted className="!text-sm !mb-4">
+          Productos destacados que he construido.
+        </ITText>
+        <ITGrid container spacing={5}>
+          {/* AXZY UI System */}
+          <ITGrid item xs={12} md={6}>
+            <a
+              href="#ui-system"
+              className="group block h-full rounded-2xl border border-slate-200 dark:border-slate-800 bg-white dark:bg-slate-900/50 p-6 hover:border-primary-400/40 hover:shadow-lg hover:-translate-y-1 transition-all duration-200"
+            >
+              <ITStack spacing={4} className="h-full" justifyContent="between">
+                <ITStack spacing={3}>
+                  <ITFlex align="center" justify="between">
+                    <div className="w-12 h-12 rounded-xl bg-gradient-to-br from-primary-500 to-purple-500 text-white flex items-center justify-center shadow-md">
+                      <FaLayerGroup size={20} />
+                    </div>
+                    <ITBadget label="Propio" color="primary" variant="filled" />
+                  </ITFlex>
+                  <div>
+                    <ITText as="h3" className="!text-lg !font-bold flex items-center gap-2">
+                      AXZY UI System
+                      <FaArrowRight size={14} className="text-primary-500 opacity-0 -translate-x-1 group-hover:opacity-100 group-hover:translate-x-0 transition-all duration-200" />
+                    </ITText>
+                    <ITText as="p" muted className="!text-sm !leading-relaxed mt-1.5">
+                      Librería de componentes React con Tailwind CSS v4. Más de 50
+                      componentes enterprise con theming en runtime, TypeScript nativo y
+                      accesibilidad.
+                    </ITText>
+                  </div>
+                  <ITFlex gap={2} wrap="wrap">
+                    <ITBadget label="React" color="gray" variant="outlined" />
+                    <ITBadget label="TypeScript" color="gray" variant="outlined" />
+                    <ITBadget label="Tailwind" color="gray" variant="outlined" />
+                    <ITBadget label="npm" color="gray" variant="outlined" />
+                  </ITFlex>
+                </ITStack>
+                <ITText as="span" className="!text-xs !font-semibold !text-primary-600 dark:!text-primary-400 inline-flex items-center gap-1.5">
+                  <SiReact size={12} />
+                  Ver proyecto
+                </ITText>
+              </ITStack>
+            </a>
+          </ITGrid>
+
+          {/* CheckApp */}
+          <ITGrid item xs={12} md={6}>
+            <a
+              href="https://checkapp.axzy.dev/"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="group block h-full rounded-2xl border border-slate-200 dark:border-slate-800 bg-white dark:bg-slate-900/50 p-6 hover:border-emerald-400/40 hover:shadow-lg hover:-translate-y-1 transition-all duration-200"
+            >
+              <ITStack spacing={4} className="h-full" justifyContent="between">
+                <ITStack spacing={3}>
+                  <ITFlex align="center" justify="between">
+                    <div className="w-12 h-12 rounded-xl bg-gradient-to-br from-emerald-500 to-cyan-500 text-white flex items-center justify-center shadow-md">
+                      <FaCheck size={20} />
+                    </div>
+                    <ITBadget label="En vivo" color="gray" variant="outlined" />
+                  </ITFlex>
+                  <div>
+                    <ITText as="h3" className="!text-lg !font-bold flex items-center gap-2">
+                      CheckApp
+                      <FaExternalLinkAlt size={12} className="text-slate-400 opacity-0 -translate-x-1 group-hover:opacity-100 group-hover:translate-x-0 transition-all duration-200" />
+                    </ITText>
+                    <ITText as="p" muted className="!text-sm !leading-relaxed mt-1.5">
+                      Aplicación web para consultar información de manera rápida y
+                      sencilla. Desplegada y disponible en línea.
+                    </ITText>
+                  </div>
+                  <ITFlex gap={2} wrap="wrap">
+                    <ITBadget label="Node.js" color="gray" variant="outlined" />
+                    <ITBadget label="React" color="gray" variant="outlined" />
+                    <ITBadget label="Deploy" color="gray" variant="outlined" />
+                  </ITFlex>
+                </ITStack>
+                <ITText as="span" className="!text-xs !font-semibold !text-emerald-600 dark:!text-emerald-400 inline-flex items-center gap-1.5">
+                  <SiNodedotjs size={12} />
+                  Abrir CheckApp
+                </ITText>
+              </ITStack>
+            </a>
+          </ITGrid>
+        </ITGrid>
+      </ITCard>
     </ITStack>
   );
 };

package/src/theme/theme.ts

@@ -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>;
 }