@axzydev/axzy_ui_system 1.2.7 → 1.2.9

package/src/components/search-select/search-select.doc.mdx

@@ -0,0 +1,72 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './search-select.stories';
+
+<Meta of={Stories} />
+
+# ITSearchSelect
+
+Searchable dropdown select with support for local client-side filtering and remote API search. Includes validation error display, label support, and customizable field mapping.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Name attribute for form integrations. |
+| `label` | `string` | — | Label displayed above the select input. |
+| `placeholder` | `string` | — | Placeholder text shown when no value is selected. |
+| `value` | `string \| number` | — | Currently selected value (controlled). |
+| `options` | `ITSearchSelectOption[]` | — | Array of options for static or remote data. `{ label, value, ...custom }`. |
+| `valueField` | `string` | `"value"` | Field used as the option value. |
+| `labelField` | `string` | `"label"` | Field used as the option display label. |
+| `onChange` | `(value: string \| number, option?: ITSearchSelectOption) => void` | — | Callback fired when selection changes. |
+| `onBlur` | `(e: FocusEvent<any>) => void` | — | Callback fired when input loses focus. |
+| `disabled` | `boolean` | `false` | Whether the component is disabled. |
+| `className` | `string` | — | Additional CSS classes for the container. |
+| `touched` | `boolean` | — | Whether the field has been touched (for form validation). |
+| `required` | `boolean` | `false` | Whether the field is required. Shows a red asterisk. |
+| `error` | `string \| boolean` | — | Error message or boolean indicating an error state. |
+| `readOnly` | `boolean` | `false` | Whether the field is read-only. |
+| `onSearch` | `(query: string) => void` | — | Callback for server-side search. Receives the search query string. |
+| `isLoading` | `boolean` | `false` | Whether options are being loaded from an external API. |
+| `noResultsMessage` | `string` | `"No se encontraron resultados"` | Message displayed when no results match the search. |
+
+## Usage
+
+```tsx
+import { ITSearchSelect } from '@axzydev/axzy_ui_system';
+
+<ITSearchSelect
+  name="user"
+  label="Select User"
+  placeholder="Search user..."
+  options={users}
+  value={selected}
+  onChange={(val) => setSelected(val)}
+/>
+
+<ITSearchSelect
+  name="remote"
+  label="API Search"
+  placeholder="Type to search..."
+  options={remoteOptions}
+  isLoading={loading}
+  onSearch={(query) => fetchResults(query)}
+  value={selected}
+  onChange={(val) => setSelected(val)}
+/>
+```
+
+## Notes
+
+- **Static mode**: provide an `options` array and the component filters client-side as the user types.
+- **Remote mode**: provide an `onSearch` callback and manage `options`/`isLoading` externally for API-driven searches.
+- `valueField` and `labelField` allow custom option object structures beyond `{ value, label }`.
+- Validation states: `error` string displays inline, `touched` gates error visibility, `required` adds a red asterisk.
+- `readOnly` mode renders the selected value as non-interactive text.
+- Supports `className` for style overrides and width control.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/search-select/search-select.props.ts

@@ -1,46 +1,51 @@
 import { FocusEvent } from "react";
 
+/** Represents an option in the search-select dropdown. */
 export interface ITSearchSelectOption {
+  /** Display label for the option. */
   label: string;
+  /** Value associated with the option. */
   value: string | number;
+  /** Additional custom fields can be attached. */
   [key: string]: any;
 }
 
+/** Props for the ITSearchSelect component. */
 export interface ITSearchSelectProps {
-  /** Nombre del campo para integraciones con formularios */
+  /** Name attribute for form integrations. */
   name?: string;
-  /** Etiqueta que se muestra arriba del select */
+  /** Label displayed above the select input. */
   label?: string;
-  /** Texto que se muestra cuando no hay nada seleccionado */
+  /** Placeholder text shown when no value is selected. */
   placeholder?: string;
-  /** Valor seleccionado */
+  /** Currently selected value. */
   value?: string | number;
-  /** Arreglo de opciones (Modo 1: Lista estática) */
+  /** Array of options for static mode (Mode 1: local client-side filtering). */
   options?: ITSearchSelectOption[];
-  /** Campo que se usará como valor (por defecto "value") */
+  /** Field used as the option value. Default: "value". */
   valueField?: string;
-  /** Campo que se usará como etiqueta (por defecto "label") */
+  /** Field used as the option display label. Default: "label". */
   labelField?: string;
-  /** Callback cuando cambia el valor */
+  /** Callback fired when the selected value changes. Receives the value and the full option object. */
   onChange?: (value: string | number, option?: ITSearchSelectOption) => void;
-  /** Callback cuando pierde el foco */
+  /** Callback fired when the input loses focus. */
   onBlur?: (e: FocusEvent<any>) => void;
-  /** Indica si el componente está deshabilitado */
+  /** Whether the component is disabled. */
   disabled?: boolean;
-  /** Clase CSS adicional para el contenedor */
+  /** Additional CSS classes for the container. */
   className?: string;
-  /** Indica si el campo ha sido tocado (para validaciones) */
+  /** Whether the field has been touched (for form validation). */
   touched?: boolean;
-  /** Indica si el campo es requerido */
+  /** Whether the field is required. Shows a red asterisk on the label. */
   required?: boolean;
-  /** Mensaje de error */
+  /** Error message or boolean indicating an error state. */
   error?: string | boolean;
-  /** Indica si el campo es de solo lectura */
+  /** Whether the field is read-only. */
   readOnly?: boolean;
-  /** Callback para búsqueda en servidor (Modo 2: Conexión con API) */
+  /** Callback for server-side search (Mode 2: API connection). Receives the search query string. */
   onSearch?: (query: string) => void;
-  /** Indica si se está cargando información desde la API */
+  /** Whether options are being loaded from an external API. */
   isLoading?: boolean;
-  /** Mensaje cuando no hay resultados */
+  /** Message displayed when no results are found. Default: "No se encontraron resultados". */
   noResultsMessage?: string;
 }

package/src/components/search-select/search-select.tsx

@@ -6,8 +6,33 @@ import { theme } from "@/theme/theme";
 import ITText from "@/components/text/text";
 
 /**
- * ITSearchSelect - Un componente de selección con buscador integrado.
- * Soporta filtrado local y búsqueda remota via API.
+ * Searchable dropdown select with local client-side filtering and server-side search via API.
+ *
+ * @example
+ * ```tsx
+ * // Static options (Mode 1)
+ * <ITSearchSelect
+ *   label="Country"
+ *   placeholder="Select a country"
+ *   options={[
+ *     { value: 'us', label: 'United States' },
+ *     { value: 'mx', label: 'Mexico' },
+ *   ]}
+ *   value={selectedCountry}
+ *   onChange={(value) => setSelectedCountry(value)}
+ * />
+ *
+ * // API search (Mode 2)
+ * <ITSearchSelect
+ *   label="User"
+ *   placeholder="Search users..."
+ *   onSearch={(query) => searchUsers(query)}
+ *   options={apiResults}
+ *   isLoading={isSearching}
+ *   value={selectedUser}
+ *   onChange={(value) => setSelectedUser(value)}
+ * />
+ * ```
  */
 export default function ITSearchSelect({
   name,

package/src/components/searchTable/searchTable.doc.mdx

@@ -0,0 +1,79 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './searchTable.stories';
+
+<Meta of={Stories} />
+
+# ITSearchTable
+
+Server-side data table with global search across all fields, column-level filtering, sortable columns, inline row editing, and integrated pagination. Supports six column types and optional Yup validation schema.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `SearchColumn<T>[]` | — | Column definitions with key, label, type, filter, sortable, editable, and custom render options. |
+| `data` | `T[]` | — | Array of row data objects (server-side paginated). |
+| `title` | `string` | — | Title displayed in the table header bar. |
+| `searchInputPlaceholder` | `string` | — | Placeholder text for the global search input. |
+| `variant` | `"default" \| "striped" \| "bordered"` | — | Table visual variant. |
+| `size` | `"sm" \| "md" \| "lg"` | — | Table row size. |
+| `containerClassName` | `string` | — | Additional CSS class for the outer container wrapper. |
+| `className` | `string` | — | Additional CSS class applied to the `<table>` element. |
+| `itemsPerPageOptions` | `number[]` | — | Available page-size options for the pagination dropdown. |
+| `defaultItemsPerPage` | `number` | — | Initial/default number of rows per page. |
+| `validationSchema` | `yup.ObjectSchema` | — | Yup validation schema for inline row editing. |
+| `pageIndex` | `number` | — | Current page index (0-based, server-side). |
+| `totalCount` | `number` | — | Total number of rows across all pages. |
+| `totalPages` | `number` | — | Total number of available pages. |
+| `hasPreviousPage` | `boolean` | — | Whether there is a previous page available. |
+| `hasNextPage` | `boolean` | — | Whether there is a next page available. |
+| `onPageChange` | `(page: number) => void` | — | Callback when the user navigates to a different page. |
+| `onItemsPerPageChange` | `(itemsPerPage: number) => void` | — | Callback when the user changes the page size. |
+| `onSortChange` | `(sortConfig: { key: string, direction: "asc" \| "desc" }) => void` | — | Callback when a column header sort is triggered. |
+| `onFilterChange` | `(filters: Record<string, string \| boolean \| number>) => void` | — | Callback when global search or column filter changes. |
+
+## Usage
+
+```tsx
+import { ITSearchTable } from '@axzydev/axzy_ui_system';
+import type { SearchColumn } from '@axzydev/axzy_ui_system';
+
+const columns: SearchColumn<MyRow>[] = [
+  { key: 'id', label: 'ID', type: 'number', sortable: true },
+  { key: 'name', label: 'Name', type: 'string', sortable: true, filter: true, editable: true },
+  { key: 'email', label: 'Email', type: 'string', sortable: true },
+  { key: 'status', label: 'Status', type: 'catalog', filter: 'catalog', sortable: true },
+];
+
+<ITSearchTable
+  columns={columns}
+  data={rows}
+  title="Users"
+  searchInputPlaceholder="Search users..."
+  pageIndex={0}
+  totalCount={100}
+  totalPages={10}
+  hasPreviousPage={false}
+  hasNextPage={true}
+  onPageChange={handlePageChange}
+  onSortChange={handleSort}
+  onFilterChange={handleFilter}
+/>
+```
+
+## Notes
+
+- **Column types**: `string`, `number`, `boolean`, `date`, `actions`, and `catalog` provide specialized filtering and rendering.
+- **Global search**: built-in search input filters across all filterable columns via `onFilterChange`.
+- **Column filtering**: `filter: true` enables text filtering; `filter: 'catalog'` renders a dropdown with `catalogOptions`.
+- **Sorting**: `sortable: true` on a column triggers `onSortChange` with `{ key, direction }`.
+- **Inline editing**: `editable: true` with `inputType` enables cell-level editing with optional `validation` and Yup `validationSchema` support.
+- **Pagination**: fully server-driven via `pageIndex`, `totalPages`, `hasPreviousPage`, `hasNextPage`, and callbacks.
+- **Rendering**: `currencyMX` formats numbers as MXN; `render` provides a custom cell render function; `actions` renders custom action buttons with edit helpers.
+- Variants `striped` and `bordered` provide alternative visual styles.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/searchTable/searchTable.props.ts

@@ -1,56 +1,95 @@
 import { TableSize, TableVariants } from "@/types/table.types";
 import * as yup from "yup";
 
+/** Allowed column data types: "string" | "date" | "number" | "boolean" | "actions" | "catalog" */
 export type ColumnType = "string" | "date" | "number" | "boolean" | "actions" | "catalog";
 
+/** Minimal catalog option with id and display name. */
 export interface CatalogOption {
+  /** Unique identifier, can be string or number. */
   id: string | number;
+  /** Display name for the catalog option. */
   name: string;
 }
 
+/** Definition of a single searchable, sortable, editable table column. */
 export interface SearchColumn<T = any> {
+  /** Unique key used for data access and sorting/filtering. */
   key: string;
+  /** Column header label displayed to the user. */
   label: string;
+  /** Data type of the column: "string" | "number" | "boolean" | "date" | "actions" | "catalog". */
   type: "string" | "number" | "boolean" | "date" | "actions" | "catalog";
+  /** Enables filtering on this column. Can be boolean or "catalog" for catalog-based filters. */
   filter?: boolean | 'catalog'; 
+  /** Whether the column is sortable by clicking its header. */
   sortable?: boolean;
+  /** Whether inline editing is allowed on this column. */
   editable?: boolean;
+  /** Inline edit input type: "text" | "number" | "select" | "checkbox" | "date". */
   inputType?: "text" | "number" | "select" | "checkbox" | "date";
-  // OK: text number
-  // PENDING: select checkbox date
+  /** Predefined select options when inputType is "select". */
   options?: { value: string | number; label: string }[];
+  /** Custom inline-edit validation. Return error string or undefined if valid. */
   validation?: (value: any, row?:any) => string | undefined;
+  /** Additional CSS class on the column cells. */
   className?: string;
+  /** Formats numeric values as Mexican pesos (MXN). */
   currencyMX?: boolean; 
+  /** Configuration for catalog-type columns: data array and optional key/label field names. */
   catalogOptions?: {
     data: Array<{ id: string | number; name: string }> | any[];
     key?: string;
     label?: string;
   };
+  /** Custom render function for the cell. Receives the full row object. */
   render?: (row: T) => React.ReactNode;
+  /** Custom action buttons rendered in the cell. Receives row and helper with onEdit. */
   actions?: (row: T, helpers: { onEdit: (row: T) => void }) => React.ReactNode;
+  /** Custom save/cancel action buttons in edit mode. Receives row and helpers. */
   saveActions?: (row: T, helpers: { onSave: (row: T) => void, onCancel: () => void, hasErrors: any}) => React.ReactNode;
 }
 
+/** Props for the ITSearchTable server-side data table component. */
 export interface ITSearchTableProps<T> {
+  /** Column definitions: key, label, type, filter, sortable, editable, etc. */
   columns: SearchColumn<T>[];
+  /** Additional CSS class for the outer container wrapper. */
   containerClassName?: string;
+  /** Placeholder text for the global search input field. */
   searchInputPlaceholder?: string;
+  /** Array of row data objects (server-side paginated). */
   data: T[];
+  /** Table visual variant: "default" | "striped" | "bordered". */
   variant?: TableVariants;
+  /** Additional CSS class applied to the `<table>` element. */
   className?: string;
+  /** Table row size: "sm" | "md" | "lg". */
   size?: TableSize;
+  /** Available page-size options (e.g. [10, 20, 50, 100]). */
   itemsPerPageOptions?: Array<number>;
+  /** Initial/default number of rows per page. */
   defaultItemsPerPage?: number;
+  /** Yup validation schema for inline editing. */
   validationSchema?:  yup.ObjectSchema<any>
+  /** Title displayed in the table header bar (teal background). */
   title?: string;
+  /** Current page index (0-based, server-side). */
   pageIndex: number;
+  /** Total number of rows across all pages (server-side). */
   totalCount: number;
+  /** Total number of available pages. */
   totalPages: number;
+  /** Whether there is a previous page available. */
   hasPreviousPage: boolean;
+  /** Whether there is a next page available. */
   hasNextPage: boolean;
+  /** Callback when the user navigates to a different page. Receives the new page index. */
   onPageChange?: (page: number) => void;
+  /** Callback when the user changes the page-size. Receives the new items-per-page value. */
   onItemsPerPageChange?: (itemsPerPage: number) => void;
-  onSortChange?: (sortConfig: { key: string, direction: "asc" | "desc" }) => void; // Se actualizó para incluir `key`
+  /** Callback when sorting changes. Receives { key, direction: "asc" | "desc" }. */
+  onSortChange?: (sortConfig: { key: string, direction: "asc" | "desc" }) => void;
+  /** Callback when global search/filter text changes. Receives a key-value filters record. */
   onFilterChange?: (filters: Record<string, string | boolean | number>) => void;
 }

package/src/components/searchTable/searchTable.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ITSearchTable from './searchTable';
+import { SearchColumn } from './searchTable.props';
+
+interface SampleRow {
+  id: number;
+  name: string;
+  email: string;
+  status: string;
+}
+
+const sampleColumns: SearchColumn<SampleRow>[] = [
+  { key: 'id', label: 'ID', type: 'number', sortable: true },
+  { key: 'name', label: 'Name', type: 'string', sortable: true, filter: true },
+  { key: 'email', label: 'Email', type: 'string', sortable: true },
+  { key: 'status', label: 'Status', type: 'catalog', filter: 'catalog', sortable: true },
+];
+
+const sampleData: SampleRow[] = [
+  { id: 1, name: 'Alice', email: 'alice@example.com', status: 'Active' },
+  { id: 2, name: 'Bob', email: 'bob@example.com', status: 'Inactive' },
+  { id: 3, name: 'Charlie', email: 'charlie@example.com', status: 'Active' },
+];
+
+const meta = {
+  title: 'Components/Data Display/ITSearchTable',
+  component: ITSearchTable,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+  argTypes: {
+    columns: { control: false, description: 'Column definitions' },
+    data: { control: false, description: 'Row data array' },
+    title: { control: 'text', description: 'Table header title' },
+    searchInputPlaceholder: { control: 'text', description: 'Placeholder for the search input' },
+    variant: { control: 'select', options: ['default', 'striped', 'bordered'], description: 'Visual variant' },
+    size: { control: 'select', options: ['sm', 'md', 'lg'], description: 'Row size' },
+    pageIndex: { control: 'number', description: 'Current page index (0-based)' },
+    totalCount: { control: 'number', description: 'Total number of rows across all pages' },
+    totalPages: { control: 'number', description: 'Total number of pages' },
+    hasPreviousPage: { control: 'boolean', description: 'Whether there is a previous page' },
+    hasNextPage: { control: 'boolean', description: 'Whether there is a next page' },
+  },
+} satisfies Meta<typeof ITSearchTable>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    columns: sampleColumns,
+    data: sampleData,
+    title: 'Users',
+    searchInputPlaceholder: 'Search users...',
+    pageIndex: 0,
+    totalCount: 3,
+    totalPages: 1,
+    hasPreviousPage: false,
+    hasNextPage: false,
+  } as any,
+};
+
+export const EmptyState: Story = {
+  args: {
+    columns: sampleColumns,
+    data: [],
+    title: 'Users',
+    searchInputPlaceholder: 'Search users...',
+    pageIndex: 0,
+    totalCount: 0,
+    totalPages: 0,
+    hasPreviousPage: false,
+    hasNextPage: false,
+  } as any,
+};

package/src/components/searchTable/searchTable.tsx

@@ -25,6 +25,29 @@ interface CustomITSearchTableProps<T> extends ITSearchTableProps<T> {
   };
 }
 
+/**
+ * Server-side data table with global search, column sorting, inline editing, and pagination.
+ *
+ * @example
+ * ```tsx
+ * <ITSearchTable
+ *   columns={[
+ *     { key: "name", label: "Name", type: "string", sortable: true, editable: true },
+ *     { key: "status", label: "Status", type: "string", filter: true },
+ *   ]}
+ *   data={rows}
+ *   title="Users"
+ *   pageIndex={0}
+ *   totalCount={100}
+ *   totalPages={10}
+ *   hasPreviousPage={false}
+ *   hasNextPage={true}
+ *   onPageChange={(p) => fetchPage(p)}
+ *   onSortChange={(s) => sortData(s)}
+ *   onFilterChange={(f) => filterData(f)}
+ * />
+ * ```
+ */
 export default function ITSearchTable<T extends Record<string, unknown>>({
   columns,
   data,

package/src/components/segmented-control/segmented-control.doc.mdx

@@ -0,0 +1,60 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './segmented-control.stories';
+
+<Meta of={Stories} />
+
+# ITSegmentedControl
+
+iOS-style segmented toggle for mutually exclusive options with optional icons. Supports two sizes and a disabled state. Ideal for filter and view switching.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `ISegmentedOption[]` | — | Array of mutually exclusive options: `{ value: string, label: string, icon?: ReactNode }`. |
+| `value` | `string` | — | Currently selected value (controlled). |
+| `onChange` | `(value: string) => void` | — | Callback fired when the user selects a different option. |
+| `size` | `"sm" \| "md"` | `"md"` | Control size. |
+| `className` | `string` | — | Additional CSS classes on the container. |
+| `disabled` | `boolean` | `false` | Whether the entire control is disabled. |
+
+## Usage
+
+```tsx
+import { ITSegmentedControl } from '@axzydev/axzy_ui_system';
+
+<ITSegmentedControl
+  options={[
+    { value: "day", label: "Day" },
+    { value: "week", label: "Week" },
+    { value: "month", label: "Month" },
+  ]}
+  value={selected}
+  onChange={setSelected}
+/>
+
+<ITSegmentedControl
+  size="sm"
+  options={[
+    { value: "list", label: "List", icon: <FaList /> },
+    { value: "grid", label: "Grid", icon: <FaTh /> },
+  ]}
+  value={view}
+  onChange={setView}
+/>
+```
+
+## Notes
+
+- Only one option can be selected at a time — mutually exclusive by design.
+- Each option may include an optional `icon` rendered alongside the label.
+- Two sizes available: `sm` (compact) and `md` (default).
+- `disabled` applies to all segments simultaneously.
+- Commonly used for view toggling (list/grid), date range selection (day/week/month), and filter switching.
+- Fully controlled component: `value` and `onChange` are required.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/segmented-control/segmented-control.props.ts

@@ -1,18 +1,30 @@
 import { ReactNode } from "react";
 
+/** Available sizes for the segmented control: "sm" | "md". */
 export type SegmentedControlSize = "sm" | "md";
 
+/** A single option within the segmented control. */
 export interface ISegmentedOption {
+  /** Unique value for the option. */
   value: string;
+  /** Display label for the option. */
   label: string;
+  /** Optional icon rendered alongside the label. */
   icon?: ReactNode;
 }
 
+/** Props for the ITSegmentedControl component. */
 export interface ITSegmentedControlProps {
+  /** Array of mutually exclusive options: { label, value, icon? }. */
   options: ISegmentedOption[];
+  /** Currently selected value (controlled). */
   value: string;
+  /** Callback fired when the user selects a different option. Receives the new value. */
   onChange: (value: string) => void;
+  /** Control size: "sm" | "md". Default: "md". */
   size?: SegmentedControlSize;
+  /** Additional CSS classes on the container. */
   className?: string;
+  /** Whether the entire control is disabled. */
   disabled?: boolean;
 }

package/src/components/segmented-control/segmented-control.tsx

@@ -7,6 +7,21 @@ const sizeMap = {
   md: { button: "px-3 py-2 text-xs", container: "p-1" },
 };
 
+/**
+ * iOS-style segmented toggle for switching between mutually exclusive options.
+ *
+ * @example
+ * ```tsx
+ * <ITSegmentedControl
+ *   options={[
+ *     { value: "day", label: "Day" },
+ *     { value: "week", label: "Week", icon: <FaCalendar /> },
+ *   ]}
+ *   value={view}
+ *   onChange={setView}
+ * />
+ * ```
+ */
 export default function ITSegmentedControl({
   options,
   value,

package/src/components/select/select.doc.mdx

@@ -0,0 +1,75 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './select.stories';
+
+<Meta of={Stories} />
+
+# ITSelect
+
+Native-like dropdown select with validation error display, label support, and read-only mode. Styled consistently with ITInput for seamless form integration.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Name attribute for the underlying `<select>` element. |
+| `options` | `OptionType[]` | — | Array of option objects with value/label key-value pairs. `{ [key: string]: string }`. |
+| `valueField` | `string` | `"value"` | Key in each option object used as the option value. |
+| `labelField` | `string` | `"label"` | Key in each option object used as the display label. |
+| `label` | `string` | — | Label text rendered above the select. |
+| `placeholder` | `string` | — | Placeholder text for the default empty option. |
+| `value` | `string` | — | Currently selected value (controlled). |
+| `onChange` | `(event: ChangeEvent<HTMLSelectElement>) => void` | — | Callback fired on selection change. |
+| `onBlur` | `(event: FocusEvent<HTMLSelectElement>) => void` | — | Callback fired on blur. |
+| `variant` | `ColorsTypes` | — | Theme color variant for the select border and focus ring. |
+| `size` | `SizesTypes` | — | Control size: `"sm"`, `"md"`, or `"lg"`. |
+| `disabled` | `boolean` | `false` | Whether the select is disabled. |
+| `className` | `string` | — | Additional CSS classes on the `<select>` element. |
+| `touched` | `boolean` | — | Marks the field as touched (for validation error display). |
+| `error` | `string \| boolean` | — | Error message string, or `true` for a default required error message. |
+| `required` | `boolean` | `false` | Whether the field is required. Shows a red asterisk on the label. |
+| `autoFocus` | `boolean` | `false` | Autofocus the select on mount. |
+| `readOnly` | `boolean` | `false` | Read-only mode: shows the current value as a single disabled option. |
+
+## Usage
+
+```tsx
+import { ITSelect } from '@axzydev/axzy_ui_system';
+
+<ITSelect
+  name="country"
+  label="Country"
+  placeholder="Select a country"
+  options={[
+    { value: "mx", label: "Mexico" },
+    { value: "us", label: "United States" },
+  ]}
+  value={selected}
+  onChange={(e) => setSelected(e.target.value)}
+/>
+
+<ITSelect
+  name="status"
+  label="Status"
+  options={statusOptions}
+  value={status}
+  onChange={(e) => setStatus(e.target.value)}
+  required
+  error={touched && !status ? "This field is required" : undefined}
+/>
+```
+
+## Notes
+
+- Custom `valueField` and `labelField` support option objects with arbitrary key names.
+- Error state: provides a red border and inline error message when `touched` is true and `error` is set.
+- `required` adds a red asterisk on the label and shows a default required error if no custom error is given.
+- `readOnly` renders the selected value as a single non-interactive option.
+- Arrow-down icon rendered via `FaAngleDown` from react-icons.
+- Styles inherited from the theme's `input` configuration for visual consistency with ITInput.
+- The `variant` prop maps to theme color tokens for border and focus ring colors.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />