flysoft-react-ui 1.3.3 → 1.4.1

package/claude/skills/flysoft-ui/references/display.md

@@ -0,0 +1,163 @@
+<!-- Generado desde los tipos de flysoft-react-ui@1.4.1. No editar a mano. -->
+<!-- Regenerar con: npm run docs:skill -->
+
+# Componentes de display
+
+Componentes de presentación de datos, estado y avatares.
+
+## DataTable\<T\>
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `columns` | `DataTableColumn<T>[]` | **sí** | — |  |
+| `fixedColumn` | `DataTableColumn<T>` |  | — |  |
+| `rows` | `T[]` | **sí** | — |  |
+| `className` | `string` |  | `""` |  |
+| `maxRows` | `number` |  | — |  |
+| `locale` | `string` |  | `"es-AR"` |  |
+| `isLoading` | `boolean` |  | `false` |  |
+| `loadingRows` | `number` |  | `5` |  |
+| `rowClassName` | `(row: T) => string` |  | — | Función opcional para aplicar clases CSS a una fila específica basada en sus datos. |
+| `headerClassName` | `string` |  | `""` |  |
+| `footerClassName` | `string` |  | `""` |  |
+| `headerCellClassName` | `string` |  | `""` |  |
+| `footerCellClassName` | `string` |  | `""` |  |
+| `cellClassName` | `string \| ((row: T, column: DataTableColumn<T>) => string)` |  | `""` |  |
+| `compact` | `boolean` |  | `false` |  |
+
+## DataField
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `string` |  | — |  |
+| `value` | `string \| number \| React.ReactNode` |  | — |  |
+| `inline` | `boolean` |  | `false` |  |
+| `align` | `"left" \| "right" \| "center"` |  | `"left"` |  |
+| `title` | `string` |  | — |  |
+| `link` | `string` |  | — |  |
+| `className` | `string` |  | `""` |  |
+| `labelClassName` | `string` |  | `""` |  |
+| `size` | `"sm" \| "md"` |  | `"md"` | Tamaño relativo a la densidad activa. - "md" (default): label = font-sm, value = font-base. - "sm": override local que baja un nivel — label = font-xs, value = font-sm. Útil para listas densas dentro de cards no-densas. |
+| `gap` | `"tight" \| "sm" \| "md"` |  | `"md"` | Gap entre label y value en modo stack (no inline). - "tight": pegado, 0px (label sobre value sin separación). - "sm": gap chico — usa --flysoft-density-gap-sm. - "md" (default): usa --flysoft-density-gap-sm también pero respeta densidad. |
+| `hideColon` | `boolean` |  | `false` | Si es true, oculta el ":" después del label en modo inline. Útil para campos donde el label ya es lo suficientemente claro por contexto. |
+
+## Badge
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `children` | `React.ReactNode` | **sí** | — |  |
+| `variant` | `"primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info"` |  | `"primary"` |  |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` |  |
+| `rounded` | `boolean` |  | `false` |  |
+| `className` | `string` |  | `""` |  |
+| `icon` | `string` |  | — |  |
+| `iconPosition` | `"left" \| "right"` |  | `"left"` |  |
+| `iconLabel` | `string` |  | — |  |
+| `bg` | `string` |  | — |  |
+| `textColor` | `string` |  | — |  |
+| `onClick` | `(event: React.MouseEvent<HTMLElement>) => void` |  | — |  |
+
+## Avatar
+
+Avatar component displays a circular avatar with initials or an image
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `text` | `string` | **sí** | — | Text to extract initials from The component will show the first letter of the first word and the first letter of the last word if there are multiple words |
+| `image` | `string` |  | — | Optional image URL to display instead of initials |
+| `bgColor` | `string` |  | `"gray-600"` | Optional background color (hexadecimal, rgb, or color name) Default: gray-600 (#4b5563) |
+| `textColor` | `string` |  | `"white"` | Optional text color (hexadecimal, rgb, or color name) Default: white (#ffffff) |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` | Optional size variant Default: md |
+| `className` | `string` |  | `""` | Optional additional CSS classes |
+
+```tsx
+// Basic usage with text
+<Avatar text="John Doe" />
+```
+
+```tsx
+// With image
+<Avatar text="John Doe" image="https://example.com/avatar.jpg" />
+```
+
+```tsx
+// Custom colors
+<Avatar text="Jane Smith" bgColor="#3b82f6" textColor="#ffffff" />
+```
+
+## RoadMap
+
+RoadMap component displays a series of stages like metro stations
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `stages` | `RoadMapStage[]` | **sí** | — | Array of stages to display |
+| `className` | `string` |  | `""` | Optional additional CSS classes |
+
+```tsx
+// Basic usage
+<RoadMap stages={[
+  { name: "Start", variant: "primary" },
+  { name: "Middle", variant: "success" },
+  { name: "End", variant: "info" }
+]} />
+```
+
+```tsx
+// With icons and descriptions
+<RoadMap stages={[
+  { name: "Planning", description: "Define requirements", icon: "fa-clipboard", variant: "primary" },
+  { name: "Development", description: "Build the feature", icon: "fa-code", variant: "success" },
+  { name: "Testing", description: "Test thoroughly", icon: "fa-check-circle", variant: "warning" }
+]} />
+```
+
+## Loader
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `isLoading` | `boolean` |  | `false` |  |
+| `text` | `string` |  | — |  |
+| `children` | `React.ReactNode` |  | — |  |
+| `keepContentWhileLoading` | `boolean` |  | — |  |
+| `contentLoadingNode` | `React.ReactNode` |  | — |  |
+| `overlayClassName` | `string` |  | — |  |
+
+## Skeleton
+
+Componente Skeleton para mostrar estados de carga. Consiste en un div con una animación de pulso y un fondo grisáceo por defecto.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `className` | `string` |  | — | Clases adicionales de Tailwind para personalizar el skeleton (medidas, bordes, etc.) La animación y el fondo base se mantendrán a menos que se sobreescriban explícitamente. |
+
+## ThemeSwitcher
+
+Sin props.
+
+## Tipos auxiliares
+
+### `DataTableColumn`
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `align` | `"left" \| "right" \| "center"` |  | — |  |
+| `width` | `string` |  | — |  |
+| `header` | `string \| React.ReactNode` |  | — |  |
+| `footer` | `string \| React.ReactNode` |  | — |  |
+| `value` | `string \| number \| ((row: T) => string \| React.ReactNode)` |  | — |  |
+| `tooltip` | `(row: T) => string \| React.ReactNode` |  | — |  |
+| `type` | `"text" \| "numeric" \| "currency" \| "date"` |  | — |  |
+| `actions` | `(row: T) => Array<React.ReactNode>` |  | — | Acciones para cada fila. Retorna un array de ReactNode que se mostrarán en un DropdownMenu. |
+| `headerActions` | `() => Array<React.ReactNode>` |  | — | Acciones para el header de la columna. Retorna un array de ReactNode que se mostrarán en un DropdownMenu. |
+
+### `RoadMapStage`
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `name` | `string` | **sí** | — | Name of the stage |
+| `description` | `string` |  | — | Optional description shown below the name |
+| `icon` | `string` |  | — | Optional FontAwesome 5 icon class (e.g., "fa-check", "fa-user") |
+| `disabled` | `boolean` |  | — | Whether the stage is disabled (shown with 0.5 opacity) |
+| `variant` | `"primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info"` |  | — | Color variant for the stage circle |
+| `bg` | `string` |  | — | Custom background color (hexadecimal, rgb, or color name) Takes precedence over variant if provided |

package/claude/skills/flysoft-ui/references/forms.md

@@ -0,0 +1,203 @@
+<!-- Generado desde los tipos de flysoft-react-ui@1.4.1. No editar a mano. -->
+<!-- Regenerar con: npm run docs:skill -->
+
+# Componentes de formulario
+
+Controles de entrada. Todos se importan desde `'flysoft-react-ui'`.
+
+Los que declaran `extends` heredan además todos los atributos nativos del elemento HTML correspondiente (`onFocus`, `placeholder`, `name`, `required`, etc.); acá sólo se listan las props propias de la librería.
+
+## Button
+
+Extiende `React.ButtonHTMLAttributes<HTMLButtonElement>` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `variant` | `"primary" \| "outline" \| "ghost"` |  | `"primary"` |  |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` |  |
+| `color` | `"primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info"` |  | `"primary"` |  |
+| `bg` | `string` |  | — |  |
+| `textColor` | `string` |  | — |  |
+| `icon` | `string` |  | — |  |
+| `iconPosition` | `"left" \| "right"` |  | `"left"` |  |
+| `loading` | `boolean` |  | `false` |  |
+| `children` | `React.ReactNode` |  | — |  |
+
+## LinkButton
+
+Extiende `Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href">` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `to` | `string` | **sí** | — |  |
+| `target` | `string` |  | — |  |
+| `variant` | `"primary" \| "outline" \| "ghost"` |  | `"primary"` |  |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` |  |
+| `color` | `"primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info"` |  | `"primary"` |  |
+| `bg` | `string` |  | — |  |
+| `textColor` | `string` |  | — |  |
+| `icon` | `string` |  | — |  |
+| `iconPosition` | `"left" \| "right"` |  | `"left"` |  |
+| `children` | `React.ReactNode` |  | — |  |
+
+## Input
+
+Extiende `Omit< React.InputHTMLAttributes<HTMLInputElement>, "size" >` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `string` |  | — |  |
+| `error` | `string` |  | — |  |
+| `icon` | `string` |  | — |  |
+| `iconPosition` | `"left" \| "right"` |  | `"left"` |  |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` |  |
+| `children` | `React.ReactNode` |  | — |  |
+| `onIconClick` | `(event: React.MouseEvent<HTMLElement>) => void` |  | — | Callback cuando se hace click en el ícono. Si está definido, el ícono será clickeable. |
+| `readOnly` | `boolean` |  | `false` | Si es true, el input será de solo lectura. No se podrá modificar pero no se verá como disabled. Por defecto es false. |
+
+## AutocompleteInput\<T, K\>
+
+Extiende `Omit<InputProps, "onChange" \| "value" \| "ref">` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `options` | `T[]` | **sí** | — |  |
+| `value` | `string \| string[]` |  | — |  |
+| `onChange` | `\| React.ChangeEventHandler<HTMLInputElement> \| ((value: string \| string[]) => void)` |  | — | Valor de texto del input (controlado) Puede ser un ChangeEventHandler (de register) o una función que recibe string (API personalizada) |
+| `onSelectOption` | `(option: T, value: K) => void` |  | — | Callback al seleccionar una opción. Devuelve el item completo (T) y el valor mapeado (K) |
+| `noResultsText` | `string` |  | `"Sin resultados"` |  |
+| `getOptionLabel` | `(item: T) => string` |  | — | Obtiene el label que se muestra para cada opción. Por defecto usa la propiedad "label". |
+| `getOptionValue` | `(item: T) => K` |  | — | Obtiene el valor que se devuelve al seleccionar una opción. Por defecto usa la propiedad "value". |
+| `getOptionDescription` | `(item: T) => string \| number \| undefined` |  | — | Obtiene la descripción opcional para cada opción. Por defecto usa la propiedad "description". |
+| `renderOption` | `(item: T) => React.ReactNode` |  | — | Renderizado personalizado de cada opción. Si se define, se ignora el render por defecto. |
+| `readOnly` | `boolean` |  | `false` | Si es true, el input será de solo lectura. No se podrá modificar ni desplegar las opciones. Por defecto es false. |
+| `multiple` | `boolean` |  | `false` | Si es true, permite seleccionar múltiples opciones usando Checkboxes. El valor será un array con los valores (K) de las opciones seleccionadas. |
+
+## SearchSelectInput\<T, K\>
+
+Extiende `Omit<InputProps, "onChange" \| "value" \| "ref">` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `value` | `T \| K \| string` |  | — |  |
+| `onChange` | `\| ((value: T \| K) => void) \| React.ChangeEventHandler<HTMLInputElement>` |  | — | Callback cuando cambia el valor del input. Recibe la opción completa (T) si no hay getOptionValue, o el valor extraído (K) si hay getOptionValue. También es compatible con react-hook-form: acepta el onChange estándar de HTML. |
+| `onSearchPromiseFn` | `(text: string) => Promise<Array<T> \| PaginationInterface<T>>` | **sí** | — | Función que realiza la búsqueda y devuelve un Promise con los resultados |
+| `onSingleSearchPromiseFn` | `(value: K) => Promise<T \| undefined>` | **sí** | — | Función que busca un elemento individual usando su valor (K). Se usa cuando hay un valor por defecto que no está presente en las opciones cargadas. Recibe el valor (K) y devuelve una Promise con el objeto completo (T) o undefined si no se encuentra. |
+| `onSelectOption` | `(option: T, value: K) => void` |  | — | Callback al seleccionar una opción. Devuelve el item completo (T) y el valor mapeado (K) |
+| `dialogTitle` | `string` |  | `"Seleccione una opción"` | Título del dialog de selección. Por defecto "Seleccione una opción" |
+| `icon` | `string` |  | `"fa-search"` | Posición del botón de búsqueda. Por defecto "right" |
+| `iconPosition` | `"left" \| "right"` |  | `"right"` |  |
+| `noResultsText` | `string` |  | `"Sin resultados"` | Texto a mostrar cuando no hay resultados |
+| `getOptionLabel` | `(item: T) => string` |  | — | Obtiene el label que se muestra para cada opción. Por defecto usa la propiedad "label". |
+| `getOptionValue` | `(item: T) => K` |  | — | Obtiene el valor que se devuelve al seleccionar una opción. Por defecto usa la propiedad "value". |
+| `getOptionDescription` | `(item: T) => string \| number \| undefined` |  | — | Obtiene la descripción opcional para cada opción. Por defecto usa la propiedad "description". |
+| `renderOption` | `(item: T) => React.ReactNode` |  | — | Renderizado personalizado de cada opción. Si se define, se ignora el render por defecto. |
+| `readOnly` | `boolean` |  | `false` | Si es true, el input será de solo lectura. No se podrá modificar ni abrir el diálogo de selección. Por defecto es false. |
+
+## DateInput
+
+Extiende `Omit<InputProps, "type" \| "value" \| "onChange" \| "ref">` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `value` | `Dayjs \| null \| string` |  | — | Valor de la fecha. En modo register con FormProvider: Dayjs \| null (se guarda como Dayjs en el formulario) En modo register sin FormProvider: string ISO (se guarda como ISO string, se puede parsear a Dayjs) En modo Controller: Dayjs \| null |
+| `onChange` | `\| ((date: Dayjs \| null) => void) \| React.ChangeEventHandler<HTMLInputElement>` |  | — | Callback cuando cambia la fecha. En modo register: ChangeEventHandler (de register) En modo Controller: (date: Dayjs \| null) => void NOTA: Para usar Dayjs directamente con register, el formulario debe estar envuelto en FormProvider. Sin FormProvider, el valor se guarda como ISO string y se puede parsear de vuelta a Dayjs usando normalizeToDayjs. |
+| `format` | `"dd/mm/yyyy" \| "mm/dd/yyyy"  (DateInputFormat)` |  | `"dd/mm/yyyy"` |  |
+| `datePickerProps` | `Omit<DatePickerProps, "value" \| "onChange">` |  | — |  |
+| `readOnly` | `boolean` |  | `false` | Si es true, el input será de solo lectura. No se podrá modificar ni desplegar el DatePicker. Por defecto es false. |
+
+## DatePicker
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `value` | `Dayjs \| null` |  | — |  |
+| `onChange` | `(date: Dayjs) => void` |  | — |  |
+| `initialViewDate` | `Dayjs` |  | — |  |
+| `startWeekOn` | `"monday" \| "sunday"` |  | `"sunday"` |  |
+| `className` | `string` |  | `""` |  |
+
+## Checkbox
+
+Extiende `Omit< React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size" >` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `string` |  | — |  |
+| `labelPosition` | `"left" \| "right"` |  | `"right"` |  |
+| `error` | `string` |  | — |  |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` |  |
+| `readOnly` | `boolean` |  | `false` | Si es true, el checkbox será de solo lectura. No se podrá modificar pero se verá igual visualmente. Por defecto es false. |
+
+## RadioButtonGroup
+
+Extiende `Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" \| "children">` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `options` | `RadioOption[]` | **sí** | — | Array de opciones para renderizar radios automáticamente |
+| `value` | `string \| number` |  | — | Valor seleccionado (controlado) |
+| `onChange` | `\| ((value: string \| number) => void) \| React.ChangeEventHandler<HTMLInputElement>` |  | — | Callback cuando cambia la selección Puede recibir un valor directo o un evento (para compatibilidad con react-hook-form) |
+| `labelPosition` | `"left" \| "right"` |  | `"right"` | Posición del label para todas las opciones |
+| `size` | `"sm" \| "md" \| "lg"` |  | `"md"` | Tamaño de los radio buttons |
+| `error` | `string` |  | — | Mensaje de error a mostrar |
+| `direction` | `"vertical" \| "horizontal"` |  | `"vertical"` | Dirección del layout: vertical (columna) o horizontal (fila) |
+| `gap` | `"sm" \| "md" \| "lg"` |  | `"md"` | Espaciado entre opciones |
+| `name` | `string` |  | — | Nombre del campo (para react-hook-form) |
+| `disabled` | `boolean` |  | — | Estado deshabilitado |
+| `onBlur` | `(() => void) \| React.FocusEventHandler<HTMLInputElement>` |  | — | Callback cuando pierde el foco Puede recibir un evento (para compatibilidad con react-hook-form) o ser una función sin parámetros |
+| `readOnly` | `boolean` |  | `false` | Si es true, el radio group será de solo lectura. Las opciones no seleccionadas se verán deshabilitadas y la seleccionada se verá igual, pero no se podrá cambiar el valor. Por defecto es false. |
+
+## CurrencyInput
+
+Componente de entrada para valores monetarios. Muestra el valor formateado con separadores de miles (puntos) y decimales (comas). Al recibir el foco, quita los puntos para facilitar la edición.
+
+Extiende `Omit< InputProps, "value" \| "onChange" \| "type" >` — hereda además sus atributos nativos.
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `value` | `number \| null` |  | — | Valor numérico del input. |
+| `onChange` | `(value: any) => void` |  | — | Callback que se ejecuta al perder el foco, devolviendo el valor numérico actualizado. Si se usa con react-hook-form (register), este callback será el de register. |
+
+## Pagination
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `fieldName` | `string` |  | `"pagina"` |  |
+| `page` | `number` |  | `1` |  |
+| `pages` | `number` |  | `1` |  |
+| `total` | `number` |  | `0` |  |
+| `isLoading` | `boolean` |  | `false` |  |
+
+## Tipos auxiliares
+
+### `AutocompleteOption`
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `string` | **sí** | — |  |
+| `value` | `string` | **sí** | — |  |
+| `description` | `string \| number` |  | — |  |
+| `icon` | `string` |  | — |  |
+
+### `DateInputFormat`
+
+```ts
+type DateInputFormat = "dd/mm/yyyy" | "mm/dd/yyyy"
+```
+
+### `RadioOption`
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `string` | **sí** | — |  |
+| `value` | `string \| number` | **sí** | — |  |
+| `disabled` | `boolean` |  | — |  |
+
+### `SearchSelectOption`
+
+| Prop | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `string` | **sí** | — |  |
+| `value` | `string` |  | — |  |
+| `description` | `string \| number` |  | — |  |
+| `icon` | `string` |  | — |  |