@axzydev/axzy_ui_system 1.2.6 → 1.2.8

package/src/components/form-builder/formBuilder.doc.mdx

@@ -0,0 +1,124 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './formBuilder.stories';
+
+<Meta of={Stories} />
+
+# ITFormBuilder
+
+A dynamic form generator that renders fields from JSON-like configuration (V1 or V2). Integrates with Formik and Yup for validation. Supports conditional rendering, calculated fields, grid layout, async validation, and custom components.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields` | `FieldConfig[]` | — | Legacy V1 field definitions (backward compatible). |
+| `config` | `FieldConfigV2[]` | — | V2 field configuration array with conditional logic, dynamic props, and grid layout. |
+| `columns` | `number` | — | Number of grid columns (1–12). |
+| `values` | `any` | — | Current form values keyed by field name. |
+| `handleChange` | `(event) => void` | — | Change handler for input, select, and textarea elements. |
+| `handleBlur` | `(event) => void` | — | Blur handler for input, select, and textarea elements. |
+| `touched` | `any` | — | Touch state keyed by field name. |
+| `errors` | `any` | — | Validation errors keyed by field name. |
+| `setFieldValue` | `(field, value, shouldValidate?) => Promise<void>` | — | Programmatically set a field value. |
+| `setFieldTouched` | `(field, touched?, shouldValidate?) => Promise<void>` | — | Programmatically mark a field as touched. |
+| `setFieldError` | `(field, message?) => void` | — | Programmatically set a field-level error. |
+| `isSubmitting` | `boolean` | — | Whether the form is currently submitting. |
+
+### FieldConfigV2 Key Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `"text" \| "number" \| "password" \| "email" \| "select" \| "date" \| "time" \| "checkbox" \| "radio" \| "array" \| "section" \| "custom"` | Field input type. |
+| `column` | `number \| { sm?, md?, lg?, xl? }` | Grid column span (responsive object or single number). |
+| `dependsOn` | `string[]` | Sibling field names to watch for conditional re-evaluation. |
+| `renderWhen` | `(values) => boolean` | When false, the field is not rendered or submitted. |
+| `dynamicProps` | `(values) => Partial<FieldConfigV2>` | Dynamically override field props based on form state. |
+| `validation` | `Yup.AnySchema` | Per-field Yup validation schema. |
+| `asyncValidation` | `(value, values) => Promise<string \| null>` | Async per-field validation returning error string. |
+| `onChangeAction` | `(val, context) => void \| Promise<void>` | Lifecycle hook for side effects (e.g., calculate totals). |
+| `options` | `Array \| () => Promise<Array>` | Select/radio options, sync or async. |
+| `component` | `React.ComponentType` | Custom renderer for `type: "custom"`. |
+
+## Usage
+
+```tsx
+import { ITFormBuilder } from '@axzydev/axzy_ui_system';
+import { Formik } from 'formik';
+import * as Yup from 'yup';
+
+const schema = Yup.object({
+  email: Yup.string().email("Invalid email").required("Required"),
+  password: Yup.string().min(8).required("Required"),
+});
+
+const fields = [
+  { name: "email", label: "Email", type: "email", required: true, column: { sm: 12 } },
+  { name: "password", label: "Password", type: "password", required: true, column: { sm: 12 } },
+  {
+    name: "subtotal",
+    label: "Subtotal",
+    type: "number",
+    currencyFormat: true,
+    column: { sm: 12, md: 4 },
+    onChangeAction: (val, { setFieldValue }) => {
+      const num = parseFloat(val) || 0;
+      setFieldValue("total", (num * 1.16).toFixed(2));
+    },
+  },
+  {
+    name: "total",
+    label: "Total",
+    type: "number",
+    currencyFormat: true,
+    disabled: true,
+    column: { sm: 12, md: 4 },
+  },
+  {
+    name: "rfc",
+    label: "RFC",
+    type: "text",
+    dependsOn: ["country"],
+    renderWhen: (vals) => vals.country === "MX",
+    required: true,
+    column: { sm: 12, md: 6 },
+  },
+];
+
+<Formik
+  initialValues={{ email: "", password: "", subtotal: "", total: "", rfc: "" }}
+  validationSchema={schema}
+  onSubmit={handleSubmit}
+>
+  {(formikProps) => (
+    <form onSubmit={formikProps.handleSubmit}>
+      <ITFormBuilder
+        config={fields}
+        columns={12}
+        values={formikProps.values}
+        handleChange={formikProps.handleChange}
+        handleBlur={formikProps.handleBlur}
+        touched={formikProps.touched}
+        errors={formikProps.errors}
+        setFieldValue={formikProps.setFieldValue}
+      />
+      <button type="submit">Submit</button>
+    </form>
+  )}
+</Formik>
+```
+
+## Notes
+
+- Supports both legacy V1 (`fields` prop) and enterprise V2 (`config` prop) field configurations.
+- V2 fields support a powerful rules engine: `dependsOn`, `renderWhen`, and `dynamicProps` for conditional behavior.
+- `onChangeAction` enables real-time field calculations and cross-field updates.
+- Grid layout uses a responsive 12-column system with per-breakpoint column span configuration.
+- Field types include `section` (grouping with collapsible regions) and `array` (dynamic repeatable lists).
+- Fully Formik-compatible — requires Formik context wrapping for state management.
+- `custom` type allows injecting arbitrary React components for complete layout control.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/form-builder/formBuilder.props.ts

@@ -1,14 +1,17 @@
 import { FieldConfig, FieldConfigV2 } from "@/types/field.types";
 
 export interface ITFormBuilderProps {
-  // Legacy
+  /** Legacy field definitions (V1). Use `config` for the V2 architecture instead */
   fields?: FieldConfig[];
   
-  // V2 Architecture
+  /** V2 field configuration array. Preferred over the legacy `fields` prop */
   config?: FieldConfigV2[];
   
+  /** Number of grid columns (1-12) */
   columns?: number;
+  /** Current form values keyed by field name */
   values: any;
+  /** Change handler for input, select, and textarea elements */
   handleChange: (
     event:
       | React.ChangeEvent<HTMLInputElement>
@@ -16,6 +19,7 @@ export interface ITFormBuilderProps {
       | React.ChangeEvent<HTMLSelectElement>
       | { target: { name: string; value: any } }
   ) => void;
+  /** Blur handler for input, select, and textarea elements */
   handleBlur: (
     event:
       | React.FocusEvent<HTMLInputElement>
@@ -23,21 +27,27 @@ export interface ITFormBuilderProps {
       | React.FocusEvent<HTMLTextAreaElement, Element>
       | { target: { name: string; value: any } }
   ) => void;
+  /** Touch state keyed by field name */
   touched: any;
+  /** Validation errors keyed by field name */
   errors: any;
+  /** Programmatically set a field value */
   setFieldValue?: (
     field: string,
     value: any,
     shouldValidate?: boolean
   ) => Promise<void | any>;
+  /** Programmatically mark a field as touched */
   setFieldTouched?: (
     field: string,
     touched?: boolean,
     shouldValidate?: boolean
   ) => Promise<void | any>;
+  /** Programmatically set a field-level error message */
   setFieldError?: (
     field: string,
     message: string | undefined
   ) => void;
+  /** Whether the form is currently submitting */
   isSubmitting?: boolean;
 }

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

@@ -20,6 +20,37 @@ function buildDependentValues(
   return deps;
 }
 
+/**
+ * Dynamic form generator from field definitions with validation support.
+ * Renders a responsive grid of inputs, selects, and date pickers based on
+ * the provided field configuration. Supports both legacy (`fields`) and
+ * V2 (`config`) field definition formats.
+ *
+ * @example
+ * <ITFormBuilder
+ *   fields={[
+ *     { name: "email", label: "Email", type: "text", required: true, column: 6 },
+ *     { name: "role", label: "Role", type: "select", options: [{ id: 1, label: "Admin" }], column: 6 },
+ *   ]}
+ *   values={formValues}
+ *   handleChange={handleChange}
+ *   handleBlur={handleBlur}
+ *   touched={touched}
+ *   errors={errors}
+ *   columns={12}
+ * />
+ *
+ * @example
+ * <ITFormBuilder
+ *   config={v2FieldConfigs}
+ *   values={formValues}
+ *   handleChange={handleChange}
+ *   handleBlur={handleBlur}
+ *   touched={touched}
+ *   errors={errors}
+ *   isSubmitting={loading}
+ * />
+ */
 export default function ITFormBuilder({
   fields,
   config,

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

@@ -0,0 +1,38 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './form-header.stories';
+
+<Meta of={Stories} />
+
+# ITFormHeader
+
+A colored header bar for modal dialogs and form containers. Displays a title centered on a primary-colored background, with an optional close (X) button on the right side.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | required | Header title text, centered in the bar. |
+| `onClose` | `() => void` | `undefined` | Optional close button handler. When provided, an X button renders. |
+| `className` | `string` | `undefined` | Additional CSS classes applied to the container. |
+
+## Usage
+
+```tsx
+import { ITFormHeader } from '@axzydev/axzy_ui_system';
+
+<ITFormHeader title="Edit Record" />
+<ITFormHeader title="Confirm" onClose={() => handleClose()} />
+```
+
+## Notes
+
+- Uses the theme primary color as the background.
+- The title truncates with ellipsis when it overflows the available width.
+- Close button is only rendered when `onClose` is provided.
+- Intended for use inside modals, drawers, or form panels.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

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

@@ -1,5 +1,8 @@
 export interface ITFormHeaderProps {
+  /** Header title text */
   title: string;
+  /** Optional close button click handler. If omitted, no close button is rendered */
   onClose?: () => void;
+  /** Additional CSS classes */
   className?: string;
 } 

package/src/components/form-header/form-header.stories.tsx

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ITFormHeader from './form-header';
+
+const meta = {
+  title: 'Components/Feedback/ITFormHeader',
+  component: ITFormHeader,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  argTypes: {
+    title: { control: 'text', description: 'The title displayed in the header' },
+    onClose: { control: false, description: 'Optional close button handler' },
+    className: { control: 'text', description: 'Additional CSS classes' },
+  },
+} satisfies Meta<typeof ITFormHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { title: 'Form Header' },
+  render: (args) => (
+    <div className="w-80">
+      <ITFormHeader {...args} />
+    </div>
+  ),
+};
+
+export const WithClose: Story = {
+  args: { title: 'Editable Form' },
+  render: (args) => (
+    <div className="w-80">
+      <ITFormHeader {...args} onClose={() => alert('Close clicked')} />
+    </div>
+  ),
+};
+
+export const LongTitle: Story = {
+  args: { title: 'Confirmación de Auditoría de Expediente Clínico' },
+  render: (args) => (
+    <div className="w-80">
+      <ITFormHeader {...args} />
+    </div>
+  ),
+};
+
+export const ShortTitle: Story = {
+  args: { title: 'Edit' },
+  render: (args) => (
+    <div className="w-80">
+      <ITFormHeader {...args} />
+    </div>
+  ),
+};

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

@@ -4,6 +4,17 @@ import { useITThemeSafe } from "../theme-provider/themeProvider";
 import { getContrastTextColor } from "@/utils/color.utils";
 import ITText from "@/components/text/text";
 
+/**
+ * Colored header bar for modals and forms with an optional close button.
+ * Uses the theme's primary color as the background and automatically
+ * calculates a contrasting text color for readability.
+ *
+ * @example
+ * <ITFormHeader title="Create User" onClose={() => setOpen(false)} />
+ *
+ * @example
+ * <ITFormHeader title="Details" className="rounded-none" />
+ */
 export default function ITFormHeader({
   title,
   onClose,

package/src/components/grid/grid.doc.mdx

@@ -0,0 +1,54 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './grid.stories';
+
+<Meta of={Stories} />
+
+# ITGrid
+
+A responsive 12-column CSS grid system for building flexible layouts. Supports grid container and item modes, configurable column spans per breakpoint, and customizable gap spacing.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | `undefined` | Child elements rendered inside the grid. |
+| `container` | `boolean` | `false` | When true, renders as a CSS grid parent. |
+| `item` | `boolean` | `false` | When true, renders as a CSS grid child with column span. |
+| `spacing` | `number` | `undefined` | Gap between children in units of 0.25rem. Container only. |
+| `columns` | `number` | `12` | Number of grid columns (1-12). Container only. |
+| `xs` | `number` | `undefined` | Column span at base breakpoint (mobile). Falls back to `sm`. |
+| `sm` | `number` | `undefined` | Column span at the `sm` breakpoint. |
+| `md` | `number` | `undefined` | Column span at the `md` breakpoint. |
+| `lg` | `number` | `undefined` | Column span at the `lg` breakpoint. |
+| `xl` | `number` | `undefined` | Column span at the `xl` breakpoint. |
+| `className` | `string` | `undefined` | Additional CSS classes. |
+| `style` | `CSSProperties` | `undefined` | Inline styles. |
+| `as` | `ElementType` | `'div'` | Custom HTML element type to render instead of div. |
+
+## Usage
+
+```tsx
+import { ITGrid } from '@axzydev/axzy_ui_system';
+
+<ITGrid container spacing={3}>
+  <ITGrid item xs={12} md={8}>
+    <div>Main content</div>
+  </ITGrid>
+  <ITGrid item xs={12} md={4}>
+    <div>Sidebar</div>
+  </ITGrid>
+</ITGrid>
+```
+
+## Notes
+
+- Uses CSS Grid under the hood with responsive breakpoint classes.
+- Omitting both `container` and `item` renders a plain `div` with no grid behavior.
+- Breakpoint spans cascade down: if `lg` is not set, it inherits `md`, then `sm`, then `xs`.
+- `spacing` multiplies by 0.25rem internally (spacing={2} = 0.5rem gap).
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/grid/grid.props.ts

@@ -1,17 +1,30 @@
 import { ReactNode, CSSProperties, ElementType } from "react";
 
 export interface ITGridProps {
+  /** Child elements */
   children?: ReactNode;
+  /** Render as a grid container (CSS grid parent) */
   container?: boolean;
+  /** Render as a grid item (CSS grid child). If neither `container` nor `item` is set, renders a plain div */
   item?: boolean;
+  /** Gap between grid children in units of 0.25rem. Only applies when `container` is true */
   spacing?: number;
+  /** Number of grid columns (1-12). Only applies when `container` is true */
   columns?: number;
+  /** Column span at the base breakpoint (mobile). Falls back to `sm` if not set */
   xs?: number;
+  /** Column span at the `sm` breakpoint */
   sm?: number;
+  /** Column span at the `md` breakpoint */
   md?: number;
+  /** Column span at the `lg` breakpoint */
   lg?: number;
+  /** Column span at the `xl` breakpoint */
   xl?: number;
+  /** Additional CSS classes */
   className?: string;
+  /** Inline styles */
   style?: CSSProperties;
+  /** Custom HTML element type to render instead of the default `div` */
   as?: ElementType;
 }

package/src/components/grid/grid.tsx

@@ -13,6 +13,30 @@ function breakpointSpan(span: number | undefined, bp: string, cols: number) {
   return `${bp}:col-span-${clamped}`;
 }
 
+function gridColsClass(cols: number) {
+  const clamped = Math.min(Math.max(cols, 1), 12);
+  return `grid-cols-${clamped}`;
+}
+
+/**
+ * Responsive 12-column CSS grid layout system.
+ * Renders as a grid container when `container` is true, as a column-spanning
+ * item when `item` is true. Supports breakpoint-aware column spans and
+ * configurable spacing between items.
+ *
+ * @example
+ * <ITGrid container columns={12} spacing={4}>
+ *   <ITGrid item xs={12} md={6}>Sidebar</ITGrid>
+ *   <ITGrid item xs={12} md={6}>Content</ITGrid>
+ * </ITGrid>
+ *
+ * @example
+ * <ITGrid container columns={3} spacing={2} as="section">
+ *   <ITGrid item>Card 1</ITGrid>
+ *   <ITGrid item>Card 2</ITGrid>
+ *   <ITGrid item>Card 3</ITGrid>
+ * </ITGrid>
+ */
 export default function ITGrid({
   children,
   container,
@@ -31,9 +55,8 @@ export default function ITGrid({
   if (container) {
     return (
       <Component
-        className={clsx("grid", className)}
+        className={clsx("grid", gridColsClass(columns), className)}
         style={{
-          gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
           gap: spacing > 0 ? `${spacing * 0.25}rem` : undefined,
           ...style,
         }}
@@ -47,6 +70,7 @@ export default function ITGrid({
     return (
       <Component
         className={clsx(
+          "col-span-full",
           colSpanClass(xs ?? sm, columns),
           sm !== undefined && breakpointSpan(sm, "sm", columns),
           md !== undefined && breakpointSpan(md, "md", columns),

package/src/components/image/image.doc.mdx

@@ -0,0 +1,44 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './image.stories';
+
+<Meta of={Stories} />
+
+# ITImage
+
+An image component with automatic fallback on load error. Uses a native `<img>` element with an error boundary that swaps the source to a fallback URL when the primary image fails to load.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Source URL of the image. |
+| `alt` | `string` | `undefined` | Alt text for accessibility. |
+| `className` | `string` | `undefined` | Additional CSS classes for the wrapper. |
+| `fallback` | `string` | `undefined` | Fallback image URL shown when `src` fails to load. |
+| `onClick` | `() => void` | `undefined` | Click handler on the image. |
+
+## Usage
+
+```tsx
+import { ITImage } from '@axzydev/axzy_ui_system';
+
+<ITImage
+  src="https://example.com/photo.jpg"
+  alt="Profile photo"
+  fallback="https://example.com/default-avatar.jpg"
+/>
+<ITImage src="https://example.com/logo.png" />
+```
+
+## Notes
+
+- Handles `onerror` internally to swap to the `fallback` URL.
+- The wrapper is an inline-block `div` with full width/height for responsive sizing within a sized parent.
+- If no `fallback` is provided and the image errors, the broken image icon is shown.
+- Uses `object-cover` to fill the container while maintaining aspect ratio.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/image/image.props.ts

@@ -1,7 +1,12 @@
 export interface ITImageProps {
+  /** Source URL of the image */
   src: string;
+  /** Alt text for accessibility */
   alt?: string;
+  /** Additional CSS classes */
   className?: string;
+  /** Fallback image URL shown when the primary `src` fails to load */
   fallback?: string;
+  /** Click handler */
   onClick?: () => void;
 }

package/src/components/image/image.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ITImage from './image';
+
+const meta = {
+  title: 'Components/Data Display/ITImage',
+  component: ITImage,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  argTypes: {
+    src: { control: 'text', description: 'Image source URL' },
+    alt: { control: 'text', description: 'Alternative text for accessibility' },
+    fallback: { control: 'text', description: 'Fallback image URL shown when the primary src fails to load' },
+    className: { control: 'text', description: 'Additional CSS classes for the wrapper' },
+    onClick: { control: false, description: 'Click handler' },
+  },
+} satisfies Meta<typeof ITImage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const containerStyle = { width: 256, height: 192 };
+
+export const Default: Story = {
+  args: {
+    src: 'https://picsum.photos/256/192',
+    alt: 'Random image',
+    className: 'rounded-lg overflow-hidden',
+  },
+  render: (args) => <div style={containerStyle}><ITImage {...args} /></div>,
+};
+
+export const WithFallbackError: Story = {
+  args: {
+    src: 'https://invalid-url/does-not-exist.jpg',
+    alt: 'Broken image',
+    fallback: 'https://picsum.photos/256/192?grayscale',
+    className: 'rounded-lg overflow-hidden',
+  },
+  render: (args) => <div style={containerStyle}><ITImage {...args} /></div>,
+};
+
+export const SquareAspectRatio: Story = {
+  args: {
+    src: 'https://picsum.photos/200/200',
+    alt: 'Square image',
+    className: 'rounded-full overflow-hidden',
+  },
+  render: (args) => <div style={{ width: 128, height: 128 }}><ITImage {...args} /></div>,
+};

package/src/components/image/image.tsx

@@ -1,6 +1,25 @@
 import { useState } from "react";
 import { ITImageProps } from "./image.props";
 
+/**
+ * Image component with automatic fallback on load error.
+ * Displays the primary `src` image and gracefully switches to the
+ * `fallback` image if loading fails.
+ *
+ * @example
+ * <ITImage
+ *   src="https://example.com/photo.jpg"
+ *   fallback="/images/placeholder.png"
+ *   alt="User photo"
+ * />
+ *
+ * @example
+ * <ITImage
+ *   src="/assets/logo.svg"
+ *   alt="Company Logo"
+ *   className="w-32 h-32 rounded-full"
+ * />
+ */
 const ITImage = ({
   src,
   alt,