@william-callao/antonella-ui 1.0.5 → 2.0.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default, { ComponentType, ReactNode, ReactElement } from 'react';
-import { StyleProp, ViewStyle, PressableProps, ViewProps, TextStyle, TextInputProps, KeyboardTypeOptions, TextProps as TextProps$1, ScrollViewProps } from 'react-native';
+import { StyleProp, ViewStyle, PressableProps, ViewProps, TextStyle, TextInputProps, View, KeyboardTypeOptions, TextProps as TextProps$1, ScrollViewProps } from 'react-native';
 import { DashboardShellTokens, LayoutRowSize, LayoutColumnSize, TextType } from '@william-callao/antonella-theme';
 export { LayoutColumnSize, LayoutRowSize } from '@william-callao/antonella-theme';
 import { SharedValue } from 'react-native-reanimated';
@@ -50,7 +50,7 @@ interface CardTitleProps {
 }
 declare function CardTitle({ title, subtitle, style }: CardTitleProps): React__default.JSX.Element;
 
-type IconName = "home" | "home-filled" | "mail" | "mail-filled" | "calendar" | "calendar-filled" | "bar-chart" | "bar-chart-filled" | "cart" | "settings" | "settings-filled" | "user" | "user-filled" | "search" | "clipboard" | "clipboard-filled" | "checklist" | "checklist-filled" | "menu" | "close" | "chevron-down" | "chevron-forward" | "chevron-back" | "arrow-back" | "arrow-forward" | "arrow-down" | "arrow-up" | "arrow-up-filled" | "add" | "checkmark" | "pencil" | "trash" | "chevron-up" | "alert-circle" | "checkmark-circle" | "information-circle" | "notifications" | "notifications-filled" | "more-horizontal" | "more-vertical" | "log-in" | "log-out" | "git-network" | "construct" | "chatbubble" | "camera" | "time" | "analytics" | "barn" | "barn-filled" | "farm" | "farm-filled" | "people" | "people-filled" | "document-text" | "document-text-filled" | "backspace" | "palette" | "folder" | "folder-open" | "file" | "loader" | "inbox" | "triangle-alert" | "eye" | "eye-off" | "flash" | "flash-off" | "torch" | "torch-off" | "flip-camera" | "scan" | "tag" | "tag-filled";
+type IconName = "home" | "home-filled" | "mail" | "mail-filled" | "calendar" | "calendar-filled" | "bar-chart" | "bar-chart-filled" | "cart" | "settings" | "settings-filled" | "user" | "user-filled" | "search" | "clipboard" | "clipboard-filled" | "checklist" | "checklist-filled" | "menu" | "close" | "chevron-down" | "chevron-forward" | "chevron-back" | "arrow-back" | "arrow-forward" | "arrow-down" | "arrow-up" | "arrow-up-filled" | "add" | "checkmark" | "pencil" | "trash" | "chevron-up" | "alert-circle" | "checkmark-circle" | "information-circle" | "notifications" | "notifications-filled" | "more-horizontal" | "more-vertical" | "log-in" | "log-out" | "git-network" | "construct" | "chatbubble" | "camera" | "time" | "analytics" | "barn" | "barn-filled" | "farm" | "farm-filled" | "people" | "people-filled" | "document-text" | "document-text-filled" | "backspace" | "palette" | "folder" | "folder-open" | "file" | "loader" | "lock" | "inbox" | "triangle-alert" | "eye" | "eye-off" | "flash" | "flash-off" | "torch" | "torch-off" | "flip-camera" | "scan" | "tag" | "tag-filled";
 declare const iconMap: Record<IconName, ComponentType<{
     size?: number;
     color?: string;
@@ -75,11 +75,14 @@ type ChipProps = {
     size?: ChipSize;
     icon?: IconName;
     uppercase?: boolean;
+    /** Marca el chip como seleccionado para el lector de pantalla (filtros,
+     *  selectores). El estilo visual lo define el caller con `variant`/`color`. */
+    selected?: boolean;
     style?: StyleProp<ViewStyle>;
     textStyle?: StyleProp<TextStyle>;
     onPress?: () => void;
 };
-declare function Chip({ label, color, backgroundColor, variant, size, icon, uppercase, style, textStyle, onPress, }: ChipProps): React__default.JSX.Element;
+declare function Chip({ label, color, backgroundColor, variant, size, icon, uppercase, selected, style, textStyle, onPress, }: ChipProps): React__default.JSX.Element;
 
 declare enum ItemStyle {
     DEFAULT = "DEFAULT",
@@ -120,10 +123,29 @@ type ChipTabsProps = {
 };
 declare function ChipTabs({ options, selected: controlledSelected, onSelect, style, fullWidth, }: ChipTabsProps): React__default.JSX.Element;
 
+type AppStepIndicatorProps = {
+    /** Paso actual, 1-based. */
+    current: number;
+    /** Cantidad total de pasos. */
+    total: number;
+    /** Texto del chip, p. ej. "Paso 2 de 3". */
+    label: string;
+    /** Nombre corto del paso actual, p. ej. "Descripción". */
+    caption?: string;
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Indicador compacto de un flujo por pasos. El chip comunica el avance y el
+ * caption opcional dice en qué paso está el usuario sin ocupar una fila extra.
+ */
+declare function AppStepIndicator({ current, total, label, caption, style, }: AppStepIndicatorProps): React__default.JSX.Element;
+
 declare enum LabelStyle {
     DEFAULT = "DEFAULT",
     LIGHT = "LIGHT",
-    DARKNESS = "DARKNESS"
+    DARKNESS = "DARKNESS",
+    /** Acción de alto contraste sobre superficies oscuras. */
+    DARKNESS_ACTION = "DARKNESS_ACTION"
 }
 type LabelProps = {
     label: string;
@@ -268,6 +290,58 @@ type SectionHeaderProps = {
 };
 declare function SectionHeader({ title, subtitle, hideDescription, action, onAction, actionIcon, onActionIcon, style, horizontalPadding, containerStyle, }: SectionHeaderProps): React__default.JSX.Element;
 
+type SelectableTableColumn = {
+    key: string;
+    label: string;
+    /** Ancho fijo de la columna. */
+    width?: number;
+    /** Factor de reparto para columnas flexibles. */
+    flex?: number;
+};
+type SelectableTableItem = {
+    id: string;
+    values: Record<string, string>;
+};
+type SelectableTableRowAction = {
+    icon: IconName;
+    color?: string;
+    onPress: (item: SelectableTableItem) => void;
+    accessibilityLabel?: (item: SelectableTableItem) => string;
+};
+type SelectableTableProps = {
+    columns: SelectableTableColumn[];
+    items: SelectableTableItem[];
+    /** Fila opcional para "ninguno"; se selecciona con id `""`. */
+    noneItem?: SelectableTableItem;
+    selectedId?: string;
+    /** Si se pasa, las filas son seleccionables. */
+    onSelect?: (id: string) => void;
+    /** Acción al final de cada fila (ej. eliminar en gestión). */
+    rowAction?: SelectableTableRowAction;
+    emptyLabel?: string;
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Tabla compacta de filas seleccionables: cabecera, separadores y estado de
+ * selección. La usan los selectores de unidades/cuentas y las pantallas de
+ * gestión.
+ */
+declare function SelectableTable({ columns, items, noneItem, selectedId, onSelect, rowAction, emptyLabel, style, }: SelectableTableProps): React__default.JSX.Element;
+
+type ScreenOverlayProps = {
+    visible: boolean;
+    title: string;
+    onClose: () => void;
+    children: React__default.ReactNode;
+    accessibilityLabel?: string;
+};
+/**
+ * Pantalla completa que se monta por delante de la pantalla actual sin
+ * navegación de router. Sirve para flujos secundarios que deben preservar el
+ * estado de la pantalla de abajo (formularios, pickers, etc.).
+ */
+declare function ScreenOverlay({ visible, title, onClose, children, accessibilityLabel, }: ScreenOverlayProps): React__default.JSX.Element;
+
 type SheetProps = {
     visible: boolean;
     onClose: () => void;
@@ -276,6 +350,8 @@ type SheetProps = {
     icon?: IconName;
     title?: string;
     caption?: string;
+    /** Contenido opcional centrado sobre el header (p. ej. indicador de pasos). */
+    headerAccessory?: React__default.ReactNode;
     children: React__default.ReactNode;
     contentStyle?: StyleProp<ViewStyle>;
     snapPoints?: Array<string | number>;
@@ -288,7 +364,7 @@ type SheetProps = {
      */
     embedded?: boolean;
 };
-declare function Sheet({ visible, onClose, dismissible, showCloseButton, icon, title, caption, children, contentStyle, snapPoints, actions, embedded, }: SheetProps): React__default.JSX.Element;
+declare function Sheet({ visible, onClose, dismissible, showCloseButton, icon, title, caption, headerAccessory, children, contentStyle, snapPoints, actions, embedded, }: SheetProps): React__default.JSX.Element;
 
 declare enum AppDialogMode {
     Dismissable = "dismissable",
@@ -298,9 +374,13 @@ type BottomSheetProps = {
     visible: boolean;
     onClose: () => void;
     mode?: AppDialogMode;
+    /** Muestra la X aunque `mode` sea Required (cierre solo por botón). */
+    showCloseButton?: boolean;
     icon?: IconName;
     title?: string;
     caption?: string;
+    /** Contenido opcional centrado sobre el header (p. ej. indicador de pasos). */
+    headerAccessory?: React__default.ReactNode;
     children: React__default.ReactNode;
     contentStyle?: React__default.ComponentProps<typeof Sheet>["contentStyle"];
     snapPoints?: React__default.ComponentProps<typeof Sheet>["snapPoints"];
@@ -309,7 +389,28 @@ type BottomSheetProps = {
     /** Monta el diálogo sin RN Modal (para hosts modales nativos tipo expo-router). */
     embedded?: boolean;
 };
-declare function BottomSheet({ visible, onClose, mode, icon, title, caption, children, contentStyle, snapPoints, actions, embedded, }: BottomSheetProps): React__default.JSX.Element;
+declare function BottomSheet({ visible, onClose, mode, showCloseButton, icon, title, caption, headerAccessory, children, contentStyle, snapPoints, actions, embedded, }: BottomSheetProps): React__default.JSX.Element;
+
+type BottomDialogProps = {
+    visible: boolean;
+    onClose: () => void;
+    title: string;
+    description?: string;
+    children?: React__default.ReactNode;
+    /** Botones del pie. El diálogo los acomoda en una fila con separación. */
+    actions?: React__default.ReactNode;
+    dismissible?: boolean;
+    contentStyle?: StyleProp<ViewStyle>;
+    /** Monta el diálogo sin RN Modal (host modal nativo tipo expo-router). */
+    embedded?: boolean;
+};
+/**
+ * Diálogo compacto anclado al pie de la pantalla. A diferencia de
+ * `BottomSheet`, no toca los bordes: flota con margen, tiene esquinas
+ * redondeadas y un título corto (`BodyBold`) en vez del header grande del
+ * sheet. Pensado para confirmaciones breves.
+ */
+declare function BottomDialog({ visible, onClose, title, description, children, actions, dismissible, contentStyle, embedded, }: BottomDialogProps): React__default.JSX.Element;
 
 type AppBottomSheetProps = {
     visible: boolean;
@@ -392,6 +493,8 @@ type ModalProps = {
     icon?: IconName;
     title?: string;
     caption?: string;
+    /** Contenido opcional centrado sobre el header (p. ej. indicador de pasos). */
+    headerAccessory?: React__default.ReactNode;
     children: React__default.ReactNode;
     contentStyle?: StyleProp<ViewStyle>;
     /** Zona de acciones fija al pie del modal. */
@@ -403,7 +506,7 @@ type ModalProps = {
      */
     embedded?: boolean;
 };
-declare function Modal({ visible, onClose, dismissible, showCloseButton, icon, title, caption, children, contentStyle, actions, embedded, }: ModalProps): React__default.JSX.Element;
+declare function Modal({ visible, onClose, dismissible, showCloseButton, icon, title, caption, headerAccessory, children, contentStyle, actions, embedded, }: ModalProps): React__default.JSX.Element;
 
 type AppFilterChipOption = {
     label: string;
@@ -578,6 +681,64 @@ type ProductCardProps = {
 };
 declare function ProductCard({ name, price, code, cart, maxQuantity, onQuantityChange, imageIcon, style, containerStyle, }: ProductCardProps): React__default.JSX.Element;
 
+type PropertySummaryItem = {
+    label: string;
+    value?: string;
+    /** Texto cuando no hay valor. Por defecto, `-`. */
+    emptyLabel?: string;
+};
+type PropertySummaryProps = {
+    title?: string;
+    items: PropertySummaryItem[];
+    emptyLabel?: string;
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Resumen compacto de propiedades para el paso de revisión: label a la
+ * izquierda y valor a la derecha, con un ritmo más bajo que una fila de input.
+ */
+declare function PropertySummary({ title, items, emptyLabel, style, }: PropertySummaryProps): React__default.JSX.Element | null;
+
+type PressKind = "button" | "card" | "item" | "tab" | "chip" | "fab" | "header" | "other";
+/**
+ * Evento semántico de interacción. NO hay coordenadas: un tap en una zona vacía no
+ * interesa a nadie y llenaría la DB de ruido.
+ */
+type PressEvent = {
+    component: string;
+    label?: string;
+    kind: PressKind;
+    data?: Record<string, unknown>;
+    ts: number;
+};
+type PressObserver = (event: PressEvent) => void;
+/**
+ * La app registra un único observer (que escribe a logwood). El DS no sabe nada de
+ * logging: solo avisa que un componente semántico recibió un tap.
+ */
+declare function setPressObserver(next: PressObserver | null): void;
+declare function getPressObserver(): PressObserver | null;
+declare function emitPress(event: Omit<PressEvent, "ts">): void;
+type PressTracking = {
+    component: string;
+    label?: string;
+    kind: PressKind;
+    data?: Record<string, unknown>;
+};
+type TrackedPressableProps = PressableProps & {
+    /** Si se omite, el componente se comporta como un Pressable normal y no emite nada. */
+    tracking?: PressTracking;
+};
+/**
+ * Reemplazo de `Pressable` para componentes con significado (un botón "Guardar", un card
+ * de acción, un ítem de lista, una tab). Cada caso pasa su `tracking`; el observer global
+ * convierte eso en un evento de log.
+ */
+declare const TrackedPressable: React__default.ForwardRefExoticComponent<PressableProps & {
+    /** Si se omite, el componente se comporta como un Pressable normal y no emite nada. */
+    tracking?: PressTracking;
+} & React__default.RefAttributes<View>>;
+
 declare enum ElementCardStyle {
     DEFAULT = "DEFAULT",
     LIGHT = "LIGHT",
@@ -595,6 +756,14 @@ type ElementCardProps = {
     trailing?: IconName;
     /** Llamado al presionar el ícono de la derecha. Si no se pasa, el ícono no es táctil. */
     onTrailingPress?: () => void;
+    /**
+     * Etiqueta de accesibilidad del ícono de la derecha. Obligatoria cuando hay
+     * `onTrailingPress`: sin ella el botón queda con `content-desc=""`, invisible
+     * para lectores de pantalla y para los selectores de tests E2E.
+     */
+    trailingLabel?: string;
+    /** Alias para compatibilidad con algunos llamadores. */
+    trailingAccessibilityLabel?: string;
     /** Elemento oculto/inactivo: atenúa la card. */
     dimmed?: boolean;
     style?: ElementCardStyle;
@@ -605,7 +774,7 @@ type ElementCardProps = {
     /** Color del icono del elemento visual (opcional). */
     visualIconColor?: string;
 };
-declare function ElementCard({ name, subtitle, icon, onPress, trailing, onTrailingPress, dimmed, style, containerStyle, visualBg, visualIconColor, }: ElementCardProps): React__default.JSX.Element;
+declare function ElementCard({ name, subtitle, icon, onPress, trailing, onTrailingPress, trailingLabel, trailingAccessibilityLabel, dimmed, style, containerStyle, visualBg, visualIconColor, }: ElementCardProps): React__default.JSX.Element;
 
 declare enum KeyValueListStyle {
     DEFAULT = "DEFAULT",
@@ -864,6 +1033,40 @@ type ReverseHeaderCardLayoutProps = {
 };
 declare function ReverseHeaderCardLayout({ headerBackgroundColor, bodyBackgroundColor, header, children, style, }: ReverseHeaderCardLayoutProps): React__default.JSX.Element;
 
+declare function isEmbeddedOverlayLocked(): boolean;
+
+type InfoNoteTone = "light" | "dark";
+declare enum InfoNoteStatus {
+    INFO = "INFO",
+    WARNING = "WARNING",
+    SUCCESS = "SUCCESS"
+}
+type InfoNoteAction = {
+    label: string;
+    icon?: IconName;
+    onPress: () => void;
+    accessibilityLabel?: string;
+};
+type InfoNoteProps = {
+    title?: string;
+    message: string;
+    icon?: IconName;
+    /** Estado semántico de la nota. Default: `INFO`. */
+    status?: InfoNoteStatus;
+    /** Acciones que se muestran debajo de la nota, alineadas a la izquierda. */
+    actions?: InfoNoteAction[];
+    /** Superficie sobre la que se pinta la nota. */
+    tone?: InfoNoteTone;
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Nota informativa compacta para formularios y selectores. El estado (`INFO`,
+ * `WARNING`, `SUCCESS`) define el color de fondo, borde e icono; las acciones
+ * usan el botón de alto contraste cuando la nota vive sobre una superficie
+ * oscura.
+ */
+declare function InfoNote({ title, message, icon, status, actions, tone, style, }: InfoNoteProps): React__default.JSX.Element;
+
 interface InputProps extends TextInputProps {
     icon?: IconName;
     /** Estilos aplicados al campo de texto interno (también cuando hay icono/ojito). */
@@ -967,10 +1170,13 @@ interface ToolsCardProps {
 }
 declare function ToolsCard({ tools, style }: ToolsCardProps): React__default.JSX.Element;
 
+type TreeNodeKind = "group" | "item";
 type TreeNode = {
     id: string;
     code: string;
     name: string;
+    /** Contenedor (grupo/cuenta título) o contenido (artículo/cuenta movimiento). */
+    kind: TreeNodeKind;
     children: TreeNode[];
 };
 type TreeEditorMode = "view" | "edit";
@@ -996,9 +1202,17 @@ type TreeEditorProps = {
     onRequestEdit?: (node: TreeNode) => void;
     /** Called when the user confirms deletion of a node. When provided, the built-in removal is bypassed (the node is NOT deleted). */
     onRequestDelete?: (node: TreeNode) => void;
+    /**
+     * Menú de acciones en modo edición: `"menu"` (default) muestra el botón de
+     * tres puntos por fila; `"longPress"` lo oculta. En ambos casos una pulsación
+     * larga sobre la fila abre las acciones.
+     */
+    nodeActions?: "menu" | "longPress";
+    /** Toque corto en una hoja (nodo sin hijas). Los grupos siguen expandiendo/colapsando. */
+    onPressNode?: (node: TreeNode) => void;
     style?: StyleProp<ViewStyle>;
 };
-declare function createNode(code: string, name: string, children?: TreeNode[]): TreeNode;
+declare function createNode(code: string, name: string, children?: TreeNode[], kind?: TreeNodeKind): TreeNode;
 declare function addChild(nodes: TreeNode[], parentId: string, node: TreeNode): TreeNode[];
 declare function addSibling(nodes: TreeNode[], nodeId: string, node: TreeNode): TreeNode[];
 declare function updateNode(nodes: TreeNode[], nodeId: string, patch: Partial<Pick<TreeNode, "code" | "name">>): TreeNode[];
@@ -1011,7 +1225,7 @@ declare function countNodes(nodes: TreeNode[]): number;
  * expandida con su primer nivel visible.
  */
 declare function buildInitialCollapsed(nodes: TreeNode[]): Record<string, boolean>;
-declare function TreeEditor({ value, onChange, mode, variant, collapsed: collapsedProp, onCollapsedChange, rootLabel, renderNode, onRequestAdd, onRequestEdit, onRequestDelete, style }: TreeEditorProps): React__default.JSX.Element;
+declare function TreeEditor({ value, onChange, mode, variant, collapsed: collapsedProp, onCollapsedChange, rootLabel, renderNode, onRequestAdd, onRequestEdit, onRequestDelete, nodeActions, onPressNode, style }: TreeEditorProps): React__default.JSX.Element;
 
 interface TextFieldProps {
     label: string;
@@ -1090,24 +1304,56 @@ interface EmptyStateProps {
 }
 declare function EmptyState({ icon, iconSize, title, caption, style }: EmptyStateProps): React__default.JSX.Element;
 
+type AppFormProps = {
+    children: React__default.ReactNode;
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Contenedor de un formulario dentro de un `BottomSheet`: el ritmo estándar
+ * entre el card de campos y las notas que van debajo (gap 8, margen superior 8).
+ */
+declare function AppForm({ children, style }: AppFormProps): React__default.JSX.Element;
+
 type AppInputProps = {
     label: string;
     labelWidth?: number;
+    /** Mensaje de error de validación: se muestra como caption roja debajo de la
+     *  fila. */
+    error?: string;
 };
 type AppInputElement = ReactElement<AppInputProps>;
 
+type AppFormCardVariant = "filled" | "outlined" | "readOnly";
+type AppFormCardTone = "light" | "dark";
 type AppFormCardProps = {
     children: AppInputElement | AppInputElement[];
     labelWidth?: number;
+    /**
+     * `readOnly` convierte el card en una lista de datos: sin superficie, borde
+     * ni padding horizontal, con divisores a sangre. Se declara explícitamente
+     * porque el estilo no debe depender de cómo se compongan los hijos
+     * (wrappers, fragmentos o condicionales).
+     */
+    variant?: AppFormCardVariant;
+    /** Superficie del grupo. `dark` es para fichas de solo lectura sobre fondo oscuro. */
+    tone?: AppFormCardTone;
     style?: ViewStyle;
 };
-declare function AppFormCard({ children, labelWidth, style }: AppFormCardProps): React__default.JSX.Element;
+declare function AppFormCard({ children, labelWidth, variant, tone, style, }: AppFormCardProps): React__default.JSX.Element;
 
 type AppTextInputProps = AppInputProps & {
     type?: "text";
     value: string;
-    /** Opcional: los campos de solo lectura (readOnly u onPress) completados por
-     *  escaneo no necesitan proveer un handler de texto. */
+    /**
+     * Componente único para filas de input de `card-form`:
+     * - editable (default): abre teclado.
+     * - `readOnly`: no abre teclado; combinar con `onPress` (selector) o
+     *   `trailingAction` (escáner).
+     * - `selectable`: fila de selección; cualquier toque dispara `onPress` y el
+     *   input no captura texto ni foco.
+     * - `editable={false}`: fila deshabilitada; usar `trailingIcon` (p. ej. lock).
+     * - `error`: pinta label y mensaje en rojo.
+     */
     onChangeText?: (value: string) => void;
     placeholder?: string;
     autoCapitalize?: "none" | "sentences" | "words" | "characters";
@@ -1127,8 +1373,15 @@ type AppTextInputProps = AppInputProps & {
         onPress: () => void;
         accessibilityLabel?: string;
     };
+    /** Icono decorativo a la derecha (ej. `lock` en un campo bloqueado). */
+    trailingIcon?: IconName;
+    /**
+     * Fila de selección: cualquier toque dispara `onPress` y el input no captura
+     * texto ni foco. Requiere `onPress`.
+     */
+    selectable?: boolean;
 };
-declare function AppTextInput({ label, labelWidth, value, onChangeText, placeholder, autoCapitalize, keyboardType, maxLength, editable, readOnly, trailingAction, onPress: onPressOverride, }: AppTextInputProps): React__default.JSX.Element;
+declare function AppTextInput({ label, labelWidth, error, value, onChangeText, placeholder, autoCapitalize, keyboardType, maxLength, editable, readOnly, selectable, trailingAction, trailingIcon, onPress: onPressOverride, }: AppTextInputProps): React__default.JSX.Element;
 
 type AppTextAreaProps = AppInputProps & {
     value: string;
@@ -1139,7 +1392,7 @@ type AppTextAreaProps = AppInputProps & {
     maxLength?: number;
     editable?: boolean;
 };
-declare function AppTextArea({ label, value, onChangeText, placeholder, autoCapitalize, keyboardType, maxLength, editable, }: AppTextAreaProps): React__default.JSX.Element;
+declare function AppTextArea({ label, error, value, onChangeText, placeholder, autoCapitalize, keyboardType, maxLength, editable, }: AppTextAreaProps): React__default.JSX.Element;
 
 type AppSelectorOption = {
     label: string;
@@ -1153,7 +1406,34 @@ type AppSelectorProps = AppInputProps & {
     placeholder?: string;
     disabled?: boolean;
 };
-declare function AppSelector({ label, labelWidth, value, onChange, options, placeholder, disabled, }: AppSelectorProps): React__default.JSX.Element;
+declare function AppSelector({ label, labelWidth, error, value, onChange, options, placeholder, disabled, }: AppSelectorProps): React__default.JSX.Element;
+
+type AppReadOnlyFieldTone = "light" | "dark";
+type AppReadOnlyFieldProps = {
+    label: string;
+    labelWidth?: number;
+    value?: string | null;
+    /** Texto cuando no hay valor (la app pasa su copy i18n; por defecto "—"). */
+    emptyLabel?: string;
+    onPress?: () => void;
+    /** Campo bloqueado: el valor se pinta como dato fijo, no como placeholder, y
+     *  la fila anuncia el estado `disabled` al lector de pantalla. */
+    disabled?: boolean;
+    /** Icono decorativo al final de la fila (p. ej. `lock` en campos bloqueados). */
+    trailingIcon?: IconName;
+    /** Error de validación mostrado debajo de la fila, como en `AppTextInput`. */
+    error?: string;
+    /** Superficie sobre la que se pinta la fila. */
+    tone?: AppReadOnlyFieldTone;
+    accessibilityHint?: string;
+};
+/**
+ * Fila de solo lectura con el mismo ritmo que `AppTextInput`: etiqueta a la
+ * izquierda y valor a la derecha, sin apariencia de input. El label va en
+ * negro y el valor en gris (dato fijo); si no hay valor, el `emptyLabel` baja
+ * a Caption para que nunca se confunda con un valor escrito.
+ */
+declare function AppReadOnlyField({ label, labelWidth, value, emptyLabel, onPress, disabled, trailingIcon, error, tone, accessibilityHint, }: AppReadOnlyFieldProps): React__default.JSX.Element;
 
 type AppToggleProps = AppInputProps & {
     value: boolean;
@@ -1167,13 +1447,15 @@ type AppButtonProps = {
     label: string;
     onPress?: () => void;
     disabled?: boolean;
+    /** Muestra un spinner a la derecha del texto y bloquea el tap mientras dura. */
+    loading?: boolean;
     variant?: AppButtonVariant;
     backgroundColor?: string;
     textColor?: string;
     borderColor?: string;
     style?: ViewStyle;
 };
-declare function AppButton({ label, onPress, disabled, variant, backgroundColor, textColor, borderColor, style, }: AppButtonProps): React__default.JSX.Element;
+declare function AppButton({ label, onPress, disabled, loading, variant, backgroundColor, textColor, borderColor, style, }: AppButtonProps): React__default.JSX.Element;
 
 type KeyboardSafeScreenProps = {
     children: React__default.ReactNode;
@@ -1269,13 +1551,30 @@ type MainLayoutProps = {
  */
 declare function MainLayout({ children, backgroundColor, scroll, contentContainerStyle, style, }: MainLayoutProps): React__default.JSX.Element;
 
+/**
+ * Matemática pura del motor de layout (`AppLayout`).
+ *
+ * Este módulo NO importa `react-native` ni toca el ciclo de vida de React: solo
+ * derivaciones deterministas sobre el estado, las alturas naturales medidas y el
+ * alto de ventana. Vive aparte para poder testearse en node (vitest) y para que
+ * la lógica del motor deje de ser una caja negra embebida en el componente.
+ *
+ * Reglas del modelo (ver `APPLAYOUT.md`):
+ *  - Las secciones son dinámicas (`content`/`minFillRest`) o estáticas
+ *    (`fill`/`fillRest`/`third`/px). Solo las dinámicas se miden.
+ *  - El alto de una sección derivada nunca inventa colas ni overscans: la
+ *    cobertura del fondo se resuelve pintando el fondo del page con el color del
+ *    cuerpo/mid (`selectPageBackground`).
+ *  - El scroll se resetea al tope SOLO cuando cambia el nombre de ruta; los
+ *    cambios de contenido dentro de la misma ruta preservan la posición.
+ */
 type SectionKey = "top" | "mid" | "bottom";
 type HeightSpec = "content" | "fill" | "fillRest" | "minFillRest" | "third" | number;
 type SlotName = "header" | "body" | "footer";
 type SectionBehavior = {
     /** Si la sección se renderiza. Default true. */
     visible?: boolean;
-    /** Cómo se determina su alto: contenido medido, llenar (H), rellenar resto, al menos rellenar el resto creciendo con el contenido, un tercio, o px fijos. Default "content". */
+    /** Cómo se determina su alto. `content`/`minFillRest` son dinámicas (se miden). Default "content". */
     height?: HeightSpec;
     /** La sección scrollea internamente (ScrollView propio). */
     scroll?: boolean;
@@ -1285,7 +1584,7 @@ type SectionBehavior = {
     fadeOnScroll?: boolean;
     /** A qué slot de contenido está asociada (header/body/footer). */
     slot?: SlotName;
-    /** Para height "fillRest": de qué sección (su alto natural) se descuenta H. */
+    /** Para height "fillRest"/"minFillRest": de qué sección (su alto natural) se descuenta H. */
     restsOn?: SectionKey;
     /** Color de fondo de la sección. */
     backgroundColor?: string;
@@ -1304,6 +1603,15 @@ type AppRoute = {
     /** Contenido por slot. Cada slot se renderiza en su sección mapeada. */
     slots?: Partial<Record<SlotName, ReactNode>>;
 };
+/**
+ * Presets = las 5 variantes del motor, reutilizables por nombre.
+ *
+ * Nota: `bottom` ya NO estira la hoja con una cola artificial (`BODY_TAIL`).
+ * La costura bajo la hoja la cubre `selectPageBackground` (fondo del page =
+ * color de la última sección visible), no el alto de la sección.
+ */
+declare const layoutStates: Record<LayoutStateName, LayoutState>;
+
 type AppNavigation = {
     navigate: (route: AppRoute) => void;
     back: () => void;
@@ -1312,8 +1620,6 @@ type AppNavigation = {
     stack: AppRoute[];
     replace: (route: AppRoute) => void;
 };
-/** Presets = las 5 variantes del motor, reutilizables por nombre. */
-declare const layoutStates: Record<LayoutStateName, LayoutState>;
 declare function useAppNavigation(): AppNavigation;
 type AppLayoutProps = {
     initialRoute: AppRoute;
@@ -1333,8 +1639,45 @@ type AppLayoutProps = {
      * transiciona y se desvanece al terminar. Default "always".
      */
     contentReveal?: "always" | "after";
+    /**
+     * Enciende el log de instrumentación del motor a consola (equivale a
+     * `EXPO_PUBLIC_LAYOUT_DEBUG=1` o a `__ANTONELLA_LAYOUT_DEBUG__(true)`).
+     * El buffer de eventos se llena igual; ver `layoutDebug.ts`.
+     */
+    debug?: boolean;
 };
-declare function AppLayout({ initialRoute, showBackButton, animateTransitions, contentReveal, }: AppLayoutProps): React__default.JSX.Element;
+/**
+ * Motor de layout por estados. Ver `APPLAYOUT.md`.
+ *
+ * Modelo de medición (robusto, sin heurísticas de valor):
+ *  - Cada sección dinámica (`content`/`minFillRest`) se mide con un PROXY
+ *    offscreen NO restringido (posición absoluta, alto auto, `opacity:0`,
+ *    `pointerEvents:none`). Al no fijarle alto, la medida es siempre la altura
+ *    intrínseca real: el artefacto del `flex:1` que medía ~32px de padding en el
+ *    contenedor visible es estructuralmente imposible, así que nunca se descarta
+ *    una medición legítima (no existe guard de umbral).
+ *  - El proxy vive FUERA del contenedor que recorta (`overflow:hidden`) durante
+ *    las transiciones, y se re-mide con `measure()` hasta estabilizar, para no
+ *    quedar con el alto "capado" por una animación de un descendiente.
+ *  - Los naturales medidos se cachean por nombre de ruta (`NaturalsSnapshot`).
+ *    Al volver a una ruta ya vista, se siembran sus naturales y el primer frame
+ *    se pinta con el alto correcto → sin "header distinto al volver".
+ *  - NUNCA se hereda el alto de otra pantalla: una ruta nunca vista se siembra
+ *    con un neutro derivado de la ventana, jamás con los naturales de la ruta
+ *    previa (sin "vestigios" entre pantallas).
+ *  - El scroll de página e interno se resetea al tope SOLO cuando cambia el
+ *    nombre de ruta; los cambios de contenido dentro de la misma ruta preservan
+ *    la posición.
+ *  - El fondo del page toma el color del cuerpo/mid (`selectPageBackground`) y
+ *    se interpola durante la transición: el lienzo no salta a negro antes de que
+ *    el header claro termine de contraerse, y no hace falta sobredimensionar el
+ *    body con colas.
+ *
+ * Contrato de slots dinámicos: el contenido de una sección `content`/
+ * `minFillRest` se monta DOS veces (proxy + visible). Debe ser puro e
+ * idempotente (sin efectos destructivos al montar).
+ */
+declare function AppLayout({ initialRoute, showBackButton, animateTransitions, contentReveal, debug, }: AppLayoutProps): React__default.JSX.Element;
 
 type AppShellNavigation = {
     /** Nombre de la ruta actual del shell (lockedRoute si está bloqueada). */
@@ -1390,6 +1733,35 @@ type DivisorProps = {
 };
 declare function Divisor({ position, color, baseColor, height, handle, extend, handleColor, style, }: DivisorProps): React__default.JSX.Element;
 
+/**
+ * Instrumentación del motor de layout (`AppLayout`).
+ *
+ * Objetivo: poder ver, paso a paso, CÓMO se calcula cada pantalla —qué se mide,
+ * cuánto, con qué naturales, qué targets se derivan y qué se aplica— sin tener
+ * que adivinar. No cambia el comportamiento: solo observa.
+ *
+ * Dos formas de activarla:
+ *  1. Variable de entorno `EXPO_PUBLIC_LAYOUT_DEBUG=1` (Metro la inyecta en el
+ *     bundle; requiere reiniciar el dev server tras definirla).
+ *  2. En runtime, desde la consola del dev server / debugger:
+ *     `__ANTONELLA_LAYOUT_DEBUG__(true)`.
+ *
+ * El buffer de eventos (últimos 400) SIEMPRE se llena, esté o no activado el log
+ * a consola. Para volcarlo:
+ *   `__ANTONELLA_LAYOUT_DUMP__()`   → imprime el buffer y lo devuelve.
+ *   `__ANTONELLA_LAYOUT_LOG__`      → el array crudo.
+ */
+type LayoutDebugEvent = {
+    t: number;
+    event: string;
+    data?: Record<string, unknown>;
+};
+/** Activa/desactiva el log a consola en runtime. */
+declare function setLayoutDebug(on: boolean): void;
+declare function isLayoutDebug(): boolean;
+/** Registra un evento de layout (siempre en el buffer; a consola si está activo). */
+declare function layoutDebug(event: string, data?: Record<string, unknown>): void;
+
 /**
  * Dirección de entrada/salida de una capa durante una transición.
  * Es la pieza extensible del sistema: agregar un nuevo SheetKind solo
@@ -1589,4 +1961,4 @@ declare const AppIcon: {
     readonly Inbox: IconName;
 };
 
-export { ActionCard, type ActionCardProps, ActionCardStyle, type ActionTile, ActionTiles, type ActionTilesProps, ActionTilesStyle, AppBottomSheet, type AppBottomSheetProps, AppButton, type AppButtonProps, type AppButtonVariant, AppCheckItem, type AppCheckItemProps, type AppCheckItemStatus, AppDialogMode, type AppFilterChipOption, AppFilterChips, type AppFilterChipsProps, AppFormCard, type AppFormCardProps, AppIcon, type AppInputElement, type AppInputProps, AppLayout, type AppLayoutProps, type AppNavigation, type AppRoute, AppSelector, type AppSelectorOption, type AppSelectorProps, AppShell, type AppShellNavigation, type AppShellProps, AppTextArea, type AppTextAreaProps, AppTextHeader, type AppTextHeaderProps, AppTextInput, type AppTextInputProps, AppToggle, type AppToggleProps, Avatar, type AvatarProps, type AvatarSize, BarcodeScannerScreen, type BarcodeScannerScreenProps, type BaseColorKey, BottomSheet, type BottomSheetProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, CameraCaptureScreen, type CameraCaptureScreenProps, type CameraFacing, type CameraFlashMode, CameraHud, type CameraHudProps, CameraPermissionGate, type CameraPermissionGateProps, CameraScreenContainer, type CameraScreenContainerProps, type CapturePhoto, Card, type CardProps, CardTitle, type CardTitleProps, type CardVariant, Chip, type ChipProps, type ChipSize, ChipTabs, type ChipTabsOption, type ChipTabsProps, type ChipVariant, ColorCustomizerDialog, type ColorToken, ColorWheel, ComposingOrb, type Composition, DashboardShell, type DashboardShellProps, Divisor, type DivisorPosition, type DivisorProps, Dock, type DockItem, type DockProps, DonutChart, type DonutChartProps, type DonutSegment, DrawerMenu, DrawerMenuItem, type DrawerMenuItemProps, DrawerMenuItemStyle, type DrawerMenuItemType, type DrawerMenuProps, Dropdown, type DropdownOption, type DropdownProps, type DropdownState, ElementCard, type ElementCardProps, ElementCardStyle, EmptyState, type EmptyStateProps, FloatingActionButton, type FloatingActionButtonPosition, type FloatingActionButtonProps, HeaderCardLayout, type HeaderCardLayoutProps, type HeightSpec, type HostKey, HudIconButton, type HudIconButtonProps, Icon, type IconName, type IconProps, Input, type InputProps, Item, type ItemProps, ItemStyle, type KeyValueItem, KeyValueList, type KeyValueListProps, KeyValueListStyle, KeyboardSafeScreen, type KeyboardSafeScreenProps, Label, type LabelProps, LabelStyle, type LayerDirection, type LayerRole, LayoutColumn, LayoutRow, type LayoutState, type LayoutStateName, ListItem, type ListItemProps, ListItemStyle, MainLayout, type MainLayoutProps, Modal, type ModalProps, OptionListItem, type OptionListItemProps, OptionListItemVariant, PinKeypad, type PinKeypadProps, ProductCard, type ProductCardCart, type ProductCardProps, ProductCardStyle, ReverseHeaderCardLayout, type ReverseHeaderCardLayoutProps, type Route, type RouteOptions, type ScanResult, SearchBar, type SearchBarProps, SearchBarStyle, type SectionBehavior, SectionHeader, type SectionHeaderProps, SectionHeaderStyle, type SectionKey, SectionTitle, type SectionTitleProps, Sheet, type SheetKind, SheetLayout, type SheetLayoutProps, type SheetProps, SheetSlot, type SheetSlotProps, ShortcutCard, type ShortcutCardProps, ShortcutCardStyle, type ShortcutItem, ShutterButton, type SidebarItem, type SidebarSection, type SidebarType, Skeleton, SkeletonCard, type SkeletonCardProps, SkeletonCircle, type SkeletonCircleProps, type SkeletonProps, type SkeletonShape, SkeletonText, type SkeletonTextProps, type SlotName, SplitColorCard, SplitDarknessCard, SplitTextCard, StackDetails, type StackDetailsAction, type StackDetailsProps, type StackDetailsRow, StackDetailsStyle, StateMessage, type StateMessageProps, StateMessageStyle, StateMessageType, TOAST_DEFAULT_DURATION_MS, TabNavigation, type TabNavigationOption, type TabNavigationProps, TabNavigationStyle, Text, TextField, type TextFieldProps, type TextProps, type TextVariant, Toast, type ToastOptions, type ToastProps, ToastProvider, ToastStyle, ToastTone, type ToolItem, ToolsCard, type ToolsCardProps, TopAction, type TopActionProps, TopActionStyle, TopBar, type TopBarProps, type TransitionSpec, TreeEditor, type TreeEditorMode, type TreeEditorProps, type TreeEditorVariant, type TreeNode, addChild, addSibling, buildInitialCollapsed, countNodes, createNode, directionSign, findNode, hasCode, hostDirection, iconMap, layoutStates, removeNode, resolveComposition, resolveTransition, updateNode, useAppNavigation, useAppShell, useSheetLayout, useToast };
+export { ActionCard, type ActionCardProps, ActionCardStyle, type ActionTile, ActionTiles, type ActionTilesProps, ActionTilesStyle, AppBottomSheet, type AppBottomSheetProps, AppButton, type AppButtonProps, type AppButtonVariant, AppCheckItem, type AppCheckItemProps, type AppCheckItemStatus, AppDialogMode, type AppFilterChipOption, AppFilterChips, type AppFilterChipsProps, AppForm, AppFormCard, type AppFormCardProps, type AppFormCardTone, type AppFormCardVariant, type AppFormProps, AppIcon, type AppInputElement, type AppInputProps, AppLayout, type AppLayoutProps, type AppNavigation, AppReadOnlyField, type AppReadOnlyFieldProps, type AppReadOnlyFieldTone, type AppRoute, AppSelector, type AppSelectorOption, type AppSelectorProps, AppShell, type AppShellNavigation, type AppShellProps, AppStepIndicator, type AppStepIndicatorProps, AppTextArea, type AppTextAreaProps, AppTextHeader, type AppTextHeaderProps, AppTextInput, type AppTextInputProps, AppToggle, type AppToggleProps, Avatar, type AvatarProps, type AvatarSize, BarcodeScannerScreen, type BarcodeScannerScreenProps, type BaseColorKey, BottomDialog, type BottomDialogProps, BottomSheet, type BottomSheetProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, CameraCaptureScreen, type CameraCaptureScreenProps, type CameraFacing, type CameraFlashMode, CameraHud, type CameraHudProps, CameraPermissionGate, type CameraPermissionGateProps, CameraScreenContainer, type CameraScreenContainerProps, type CapturePhoto, Card, type CardProps, CardTitle, type CardTitleProps, type CardVariant, Chip, type ChipProps, type ChipSize, ChipTabs, type ChipTabsOption, type ChipTabsProps, type ChipVariant, ColorCustomizerDialog, type ColorToken, ColorWheel, ComposingOrb, type Composition, DashboardShell, type DashboardShellProps, Divisor, type DivisorPosition, type DivisorProps, Dock, type DockItem, type DockProps, DonutChart, type DonutChartProps, type DonutSegment, DrawerMenu, DrawerMenuItem, type DrawerMenuItemProps, DrawerMenuItemStyle, type DrawerMenuItemType, type DrawerMenuProps, Dropdown, type DropdownOption, type DropdownProps, type DropdownState, ElementCard, type ElementCardProps, ElementCardStyle, EmptyState, type EmptyStateProps, FloatingActionButton, type FloatingActionButtonPosition, type FloatingActionButtonProps, HeaderCardLayout, type HeaderCardLayoutProps, type HeightSpec, type HostKey, HudIconButton, type HudIconButtonProps, Icon, type IconName, type IconProps, InfoNote, type InfoNoteAction, type InfoNoteProps, InfoNoteStatus, type InfoNoteTone, Input, type InputProps, Item, type ItemProps, ItemStyle, type KeyValueItem, KeyValueList, type KeyValueListProps, KeyValueListStyle, KeyboardSafeScreen, type KeyboardSafeScreenProps, Label, type LabelProps, LabelStyle, type LayerDirection, type LayerRole, LayoutColumn, type LayoutDebugEvent, LayoutRow, type LayoutState, type LayoutStateName, ListItem, type ListItemProps, ListItemStyle, MainLayout, type MainLayoutProps, Modal, type ModalProps, OptionListItem, type OptionListItemProps, OptionListItemVariant, PinKeypad, type PinKeypadProps, type PressEvent, type PressKind, type PressObserver, type PressTracking, ProductCard, type ProductCardCart, type ProductCardProps, ProductCardStyle, PropertySummary, type PropertySummaryItem, type PropertySummaryProps, ReverseHeaderCardLayout, type ReverseHeaderCardLayoutProps, type Route, type RouteOptions, type ScanResult, ScreenOverlay, type ScreenOverlayProps, SearchBar, type SearchBarProps, SearchBarStyle, type SectionBehavior, SectionHeader, type SectionHeaderProps, SectionHeaderStyle, type SectionKey, SectionTitle, type SectionTitleProps, SelectableTable, type SelectableTableColumn, type SelectableTableItem, type SelectableTableProps, type SelectableTableRowAction, Sheet, type SheetKind, SheetLayout, type SheetLayoutProps, type SheetProps, SheetSlot, type SheetSlotProps, ShortcutCard, type ShortcutCardProps, ShortcutCardStyle, type ShortcutItem, ShutterButton, type SidebarItem, type SidebarSection, type SidebarType, Skeleton, SkeletonCard, type SkeletonCardProps, SkeletonCircle, type SkeletonCircleProps, type SkeletonProps, type SkeletonShape, SkeletonText, type SkeletonTextProps, type SlotName, SplitColorCard, SplitDarknessCard, SplitTextCard, StackDetails, type StackDetailsAction, type StackDetailsProps, type StackDetailsRow, StackDetailsStyle, StateMessage, type StateMessageProps, StateMessageStyle, StateMessageType, TOAST_DEFAULT_DURATION_MS, TabNavigation, type TabNavigationOption, type TabNavigationProps, TabNavigationStyle, Text, TextField, type TextFieldProps, type TextProps, type TextVariant, Toast, type ToastOptions, type ToastProps, ToastProvider, ToastStyle, ToastTone, type ToolItem, ToolsCard, type ToolsCardProps, TopAction, type TopActionProps, TopActionStyle, TopBar, type TopBarProps, TrackedPressable, type TrackedPressableProps, type TransitionSpec, TreeEditor, type TreeEditorMode, type TreeEditorProps, type TreeEditorVariant, type TreeNode, type TreeNodeKind, addChild, addSibling, buildInitialCollapsed, countNodes, createNode, directionSign, emitPress, findNode, getPressObserver, hasCode, hostDirection, iconMap, isEmbeddedOverlayLocked, isLayoutDebug, layoutDebug, layoutStates, removeNode, resolveComposition, resolveTransition, setLayoutDebug, setPressObserver, updateNode, useAppNavigation, useAppShell, useSheetLayout, useToast };