mobile-design 0.1.1 → 0.1.2

package/README.md

@@ -4,9 +4,9 @@
 
 Componentes Material Design 3 para React Native y React Native Web. El paquete integra el tema, las fuentes y los componentes sobre React Native Paper.
 
-[Instalación](#instalación-desde-npm) · [Primer componente](#primer-componente) · [Proveedor](#configurar-el-proveedor) · [Temas y colores](#temas-y-colores) · [Iconos](#tipografía-e-iconos) · [Componentes](#referencia-de-componentes)
+[Instalación](#instalación-desde-npm) · [Dependencias](#para-qué-sirve-cada-dependencia) · [Primer componente](#primer-componente) · [Proveedor](#configurar-el-proveedor) · [Temas y colores](#temas-y-colores) · [Tipografía e iconos](#tipografía-e-iconos) · [Índice de componentes](#índice-de-componentes)
 
-La referencia detallada de propiedades, configuraciones y ejemplos se incluye como `COMPONENTS.md` en el paquete. [Referencia completa de componentes en la versión 0.1.1](https://cdn.jsdelivr.net/npm/mobile-design@0.1.1/COMPONENTS.md)
+La referencia detallada de propiedades y ejemplos viaja con el paquete. Puedes abrir `node_modules/mobile-design/COMPONENTS.md` para consultar la versión instalada. [Referencia en este código fuente](COMPONENTS.md) · [Referencia de la versión publicada](https://cdn.jsdelivr.net/npm/mobile-design@latest/COMPONENTS.md)
 
 ## Instalación desde npm
 
@@ -31,6 +31,34 @@ npx expo start --web
 
 `mobile-design` instala `@mobile-design/tokens` como dependencia e incluye Roboto y los símbolos MD3 que necesitan los componentes. Con estas versiones se verificaron TypeScript, la exportación de Metro en Android, iOS y web, y el renderizado de fuentes y símbolos en Chromium con dependencias públicas.
 
+### Para qué sirve cada dependencia
+
+Los *peers* forman parte de la configuración de la app. Los comandos anteriores fijan las versiones probadas. En una app Expo, el SDK ya determina las versiones de `react` y `react-native`.
+
+| Paquete | Dónde se necesita | Qué aporta |
+| --- | --- | --- |
+| `mobile-design` | Android, iOS y web | Componentes, proveedor MD3, Roboto y los símbolos incluidos. |
+| `@mobile-design/tokens` | Se instala con `mobile-design` | Paletas clara y oscura, tamaños, tipografía y movimiento. Se puede instalar solo si tu app consume únicamente los valores. |
+| `expo` | App Expo o proyecto React Native con módulos Expo configurados | Integra los módulos Expo como fuentes e imágenes. Metro procesa el TypeScript que distribuye el paquete. |
+| `react` | Peer común | Estado, hooks y composición de componentes. |
+| `react-native` | Peer común | Vistas, estilos, accesibilidad y eventos. En web, Metro resuelve los hosts mediante React Native Web. |
+| `react-native-paper` | Peer común | Tema base, iconos por nombre, dirección de lectura, portal y primitivas como `Avatar` y `TouchableRipple`. |
+| `expo-font` | Peer común | Registra Roboto y la fuente de símbolos. También carga las familias que aporta tu app. |
+| `expo-image` | Peer común | Renderiza las imágenes de `Carousel` y `FullScreenCarousel`. |
+| `react-native-gesture-handler` | Peer común | Gestos de arrastre y desplazamiento en hojas, sliders, listas y otros controles. Monta `GestureHandlerRootView` en la raíz. |
+| `react-native-reanimated` | Peer común | Valores compartidos, transiciones de estado y animaciones de los componentes. |
+| `react-native-worklets` | Peer común | Ejecuta callbacks de gestos y animación en UI y comunica resultados al estado de React. |
+| `react-native-safe-area-context` | Peer común | Proporciona los bordes seguros para barras y superficies superpuestas. Monta `SafeAreaProvider` en la raíz. |
+| `react-native-svg` | Peer común | Dibuja indicadores de progreso y las rutas SVG de símbolos disponibles antes de cargar la fuente. |
+| `@gorhom/bottom-sheet` | Peer común | Motor de `BottomSheet` y sus listas, scroll y campos de texto coordinados con el teclado. |
+| `react-dom` | Peer de web | Monta el árbol de React en el DOM. |
+| `react-native-web` | Peer de web | Traduce las primitivas React Native a elementos y eventos del navegador. |
+| `@expo/metro-runtime` | App Expo con Metro en web | Runtime para los bundles web de Expo. Se instala en la app. |
+| `@mobile-design/icons` | Opcional en las tres plataformas | Catálogo completo de Material Symbols Rounded. Instala la versión que corresponda a `mobile-design`. |
+| `@expo/vector-icons` | Opcional en las tres plataformas | Proveedor alternativo si tu app elige, por ejemplo, Ionicons. |
+
+### Elegir la entrada del paquete
+
 | Entrada | Cuándo usarla |
 | --- | --- |
 | `mobile-design/react-native` | Android e iOS. |
@@ -89,18 +117,18 @@ export default function App() {
 
 Monta un `MobileDesignProvider` en la raíz para compartir el tema, la dirección de lectura y los portales. `GestureHandlerRootView` da soporte a los gestos y `SafeAreaProvider` permite a las barras y hojas respetar los bordes de la pantalla. Mantén ambos por fuera del proveedor.
 
-| Propiedad | Valores y comportamiento |
-| --- | --- |
-| `children` | Pantallas y componentes que consumen el tema y el host de `Portal`. |
-| `colorScheme` | `'light'` o `'dark'`. Si se omite, el proveedor sigue el esquema del sistema y usa claro cuando el sistema no declara modo oscuro. |
-| `theme` | Tema parcial de Paper. Fusiona por rol objetos como `colors`, `fonts`, `shapes`, `elevation` y `motion`. `theme.dark` explícito prevalece sobre `colorScheme`. |
-| `fontFamily` | Nombre de una familia registrada. Por defecto usa `'Roboto'`. Aplica la familia a la escala tipográfica y puedes ajustar un estilo concreto con `theme.fonts`. |
-| `languageHeight` | `'small'`, `'medium'`, `'large'` o `'extraLarge'`. El valor inicial es `'small'`. Cambia el interlineado de los estilos MD3 base y enfatizados. |
-| `motion` | `'expressive'` o `'standard'`. El valor inicial es `'expressive'`. Selecciona el perfil de los resortes espaciales. |
-| `reduceMotion` | `'auto'`, `'on'` u `'off'`. El valor inicial es `'auto'` y sigue la preferencia del sistema. |
-| `direction` | `'ltr'` o `'rtl'`. Si se omite, Paper usa la dirección del entorno. |
-| `settings.icon` | Renderizador para iconos pedidos por nombre. Por defecto usa los Material Symbols del paquete base. |
-| `settings.rippleEffectEnabled` | Habilita el ripple en los controles que consultan este ajuste. Paper lo habilita de forma predeterminada. |
+| Propiedad | Valores y comportamiento | Ejemplo |
+| --- | --- | --- |
+| `children` | Pantallas y componentes que consumen el tema y el host de `Portal`. | `<MobileDesignProvider><Button>Guardar</Button></MobileDesignProvider>` |
+| `colorScheme` | `'light'` o `'dark'`. Si se omite, el proveedor sigue el esquema del sistema y usa claro cuando el sistema no declara modo oscuro. | `colorScheme="dark"` para una vista previa fija. |
+| `theme` | Tema parcial de Paper. Fusiona por rol objetos como `colors`, `fonts`, `shapes`, `elevation` y `motion`. `theme.dark` explícito prevalece sobre `colorScheme`. | `theme={{ fonts: { titleLarge: { fontWeight: '700' } } }}` para enfatizar los títulos grandes. |
+| `fontFamily` | Nombre de una familia registrada. Por defecto usa `'Roboto'`. Aplica la familia a la escala tipográfica y puedes ajustar un estilo concreto con `theme.fonts`. | `fontFamily="Inter"` después de registrar Inter. |
+| `languageHeight` | `'small'`, `'medium'`, `'large'` o `'extraLarge'`. El valor inicial es `'small'`. Cambia el interlineado de los estilos MD3 base y enfatizados. | `languageHeight="large"` para texto que requiera más altura de línea. |
+| `motion` | `'expressive'` o `'standard'`. El valor inicial es `'expressive'`. Selecciona el perfil de los resortes espaciales. | `motion="standard"` para usar el perfil espacial estándar. |
+| `reduceMotion` | `'auto'`, `'on'` u `'off'`. El valor inicial es `'auto'` y sigue la preferencia del sistema. | `reduceMotion="on"` para habilitar la reducción en una vista previa. |
+| `direction` | `'ltr'` o `'rtl'`. Si se omite, Paper usa la dirección del entorno. | `direction="rtl"` para una interfaz en árabe. |
+| `settings.icon` | Renderizador para iconos pedidos por nombre. Por defecto usa los Material Symbols del paquete base. | `settings={{ icon: renderMaterialIcon }}` con el renderizador de la colección opcional. |
+| `settings.rippleEffectEnabled` | Habilita el ripple en los controles que consultan este ajuste. Paper lo habilita de forma predeterminada. | `settings={{ rippleEffectEnabled: false }}` para desactivar el efecto en esos controles. |
 
 El proveedor carga las fuentes predeterminadas que necesita el tema o el renderizador elegido. Antes de la primera carga completa puede mostrar el árbol vacío. Registra las caras y pesos de una fuente personalizada en tu app con `expo-font` antes de pasar su `fontFamily`.
 
@@ -292,12 +320,16 @@ Los ejemplos se montan bajo el proveedor de la instalación. Importan desde `mob
 
 El archivo `node_modules/mobile-design/COMPONENTS.md` amplía la tabla de cada familia, las piezas relacionadas y los ejemplos completos.
 
-- [Acciones y botones](#acciones-y-botones). Button, IconButton, ButtonGroup, SegmentedButtons, SplitButton, FAB, FAB.Extended, FAB.Menu.
-- [Campos y selección](#campos-y-selección). TextField, Select, Autocomplete, Checkbox, RadioButton, Switch, Slider y RangeSlider, DatePicker y DockedDatePicker, TimePicker.
-- [Navegación y búsqueda](#navegación-y-búsqueda). TopAppBar, NavigationBar, NavigationRail, NavigationDrawer, Tabs y TabsPager, Searchbar y SearchView, Toolbar.
-- [Contenido y tipografía](#contenido-y-tipografía). Text, Badge y BadgedBox, Card, Carousel, Chip, Divider, List.
-- [Superficies y ayuda](#superficies-y-ayuda). Menu, Dialog y FullScreenDialog, BottomSheet, SideSheet, Snackbar, Tooltip y RichTooltip.
-- [Carga y progreso](#carga-y-progreso). LoadingIndicator y PullToRefresh, ProgressIndicator.
+## Índice de componentes
+
+| Familia | Fichas |
+| --- | --- |
+| [Acciones y botones](#acciones-y-botones) | [`Button`](#button), [`IconButton`](#iconbutton), [`ButtonGroup`](#buttongroup), [`SegmentedButtons`](#segmentedbuttons), [`SplitButton`](#splitbutton), [`FAB`](#fab), [`FAB.Extended`](#fabextended), [`FAB.Menu`](#fabmenu) |
+| [Campos y selección](#campos-y-selección) | [`TextField`](#textfield), [`Select`](#select), [`Autocomplete`](#autocomplete), [`Checkbox`](#checkbox), [`RadioButton`](#radiobutton), [`Switch`](#switch), [`Slider`](#slider-y-rangeslider), [`RangeSlider`](#slider-y-rangeslider), [`DatePicker`](#datepicker-y-dockeddatepicker), [`DockedDatePicker`](#datepicker-y-dockeddatepicker), [`TimePicker`](#timepicker) |
+| [Navegación y búsqueda](#navegación-y-búsqueda) | [`TopAppBar`](#topappbar), [`NavigationBar`](#navigationbar), [`NavigationRail`](#navigationrail), [`NavigationDrawer`](#navigationdrawer), [`Tabs`](#tabs-y-tabspager), [`TabsPager`](#tabs-y-tabspager), [`Searchbar`](#searchbar-y-searchview), [`SearchView`](#searchbar-y-searchview), [`Toolbar`](#toolbar) |
+| [Contenido y tipografía](#contenido-y-tipografía) | [`Text`](#text), [`Badge`](#badge-y-badgedbox), [`BadgedBox`](#badge-y-badgedbox), [`Card`](#card), [`Carousel`](#carousel), [`Chip`](#chip), [`Divider`](#divider), [`List`](#list) |
+| [Superficies y ayuda](#superficies-y-ayuda) | [`Menu`](#menu), [`Dialog`](#dialog-y-fullscreendialog), [`FullScreenDialog`](#dialog-y-fullscreendialog), [`BottomSheet`](#bottomsheet), [`SideSheet`](#sidesheet), [`Snackbar`](#snackbar), [`Tooltip`](#tooltip-y-richtooltip), [`RichTooltip`](#tooltip-y-richtooltip) |
+| [Carga y progreso](#carga-y-progreso) | [`LoadingIndicator`](#loadingindicator-y-pulltorefresh), [`PullToRefresh`](#loadingindicator-y-pulltorefresh), [`ProgressIndicator`](#progressindicator) |
 
 ### Acciones y botones
 
@@ -361,7 +393,7 @@ El componente usa `mode` y `sizeClass`. `mode="contained"` aplica Filled, `conta
 
 Reúne acciones relacionadas o alternativas de selección. Standard redistribuye el espacio al pulsar. Connected mantiene el grupo unido.
 
-Cada ítem puede tener icono y `selectedIcon`. `maxVisibleItems` limita cuántos se muestran y el resto aparece en el menú. Con selección múltiple el valor es un arreglo de claves.
+Cada ítem puede tener `icon`. Con `showSelectedIcon`, el ítem seleccionado muestra una marca de verificación. `maxVisibleItems` limita cuántos se muestran y el resto aparece en el menú. Con selección múltiple el valor es un arreglo de claves.
 
 | Propiedad | Tipo | Inicial | Uso |
 | --- | --- | --- | --- |
@@ -461,58 +493,6 @@ Controla expanded y ciérralo desde onDismiss. Trigger define el FAB y su nombre
 | `expanded` · requerida | `boolean` | — | Estado controlado de expansión. |
 | `onDismiss` · requerida | `() => void` | — | Solicita cerrar la superficie. |
 
-**Ejemplo**
-
-```tsx
-import { useState } from 'react';
-import { View } from 'react-native';
-import { FAB, Text } from 'mobile-design/react-native';
-
-export default function Example() {
-  const [feedback, setFeedback] = useState('');
-  const [expanded, setExpanded] = useState(false);
-
-  return (
-    <View style={{ gap: 16 }}>
-      <View
-        style={{
-          minHeight: 280,
-          justifyContent: 'flex-end',
-          alignItems: 'flex-end',
-        }}
-      >
-        <FAB.Menu
-          presentation="expressive"
-          expanded={expanded}
-          onDismiss={() => setExpanded(false)}
-          trigger={{
-            icon: 'plus',
-            size: 'medium',
-            accessibilityLabel: 'Crear',
-            onPress: () => setExpanded(true),
-          }}
-          items={[
-            {
-              key: 'note',
-              label: 'Nota',
-              icon: 'pencil-outline',
-              onPress: () => setFeedback('Nueva nota'),
-            },
-            {
-              key: 'folder',
-              label: 'Carpeta',
-              icon: 'folder-outline',
-              onPress: () => setFeedback('Nueva carpeta'),
-            },
-          ]}
-        />
-      </View>
-      <Text accessibilityLiveRegion="polite">{feedback}</Text>
-    </View>
-  );
-}
-```
-
 ### Campos y selección
 
 #### TextField
@@ -844,61 +824,6 @@ Para deslizar entre paneles comparte `value`, `position` y la solicitud de selec
 | `onValueChange` · requerida | `(key: string) => void` | — | Entrega el siguiente valor para actualizar el estado del consumidor. |
 | `variant` | `"primary" \| "secondary"` | `'primary'` | Tratamiento visual o modalidad del componente. |
 
-**Ejemplo**
-
-```tsx
-import { useState } from 'react';
-import { View } from 'react-native';
-import { useSharedValue } from 'react-native-reanimated';
-import { Tabs, TabsPager, Text } from 'mobile-design/react-native';
-
-export default function Example() {
-  const [value, setValue] = useState('files');
-  const [request, setRequest] = useState(0);
-  const position = useSharedValue(0);
-  const items = [
-    {
-      key: 'files',
-      label: 'Archivos',
-      icon: 'folder',
-      nativeID: 'library-files-tab',
-      panelID: 'library-files-panel',
-    },
-    {
-      key: 'recent',
-      label: 'Recientes',
-      icon: 'schedule',
-      nativeID: 'library-recent-tab',
-      panelID: 'library-recent-panel',
-    },
-  ];
-
-  return (
-    <View style={{ flex: 1 }}>
-      <Tabs
-        items={items}
-        value={value}
-        onValueChange={setValue}
-        position={position}
-        onTabPress={() => setRequest((value) => value + 1)}
-      />
-      <TabsPager
-        items={items}
-        value={value}
-        onValueChange={setValue}
-        position={position}
-        selectionRequest={request}
-        renderPage={(item) => (
-          <View style={{ padding: 24 }}>
-            <Text>{item.label}</Text>
-          </View>
-        )}
-      />
-    </View>
-  );
-}
-```
-
 #### Searchbar y SearchView
 
 Conecta una barra de búsqueda con una vista que presenta consulta, sugerencias y resultados.
@@ -1065,37 +990,6 @@ Usa `List.Accordion` con `title`, `expanded` y `onPress`. Configura las acciones
 | `variant` | `"expressive" \| "baseline"` | `'expressive'` | Tratamiento visual o modalidad del componente. |
 | `selectionMode` | `"single" \| "multiple"` | — | Define si la selección es inexistente, única o múltiple. |
 
-**Ejemplo**
-
-```tsx
-import { useState } from 'react';
-import { View } from 'react-native';
-import { List, IconButton, Text } from 'mobile-design/react-native';
-
-export default function Example() {
-  const [feedback, setFeedback] = useState('');
-
-  return (
-    <View style={{ gap: 16 }}>
-      <List.Item
-        title="Informe trimestral"
-        description="Documento compartido"
-        lines={2}
-        onPress={() => setFeedback('Detalle del documento')}
-        trailing={
-          <IconButton
-            icon="bookmark-outline"
-            accessibilityLabel="Guardar Informe trimestral"
-            onPress={() => setFeedback('Guardado Informe trimestral')}
-          />
-        }
-      />
-      <Text accessibilityLiveRegion="polite">{feedback}</Text>
-    </View>
-  );
-}
-```
-
 ### Superficies y ayuda
 
 #### Menu
@@ -1113,48 +1007,6 @@ Controla visible y onDismiss y proporciona un anchor que abra el menú.
 | `onDismiss` | `(() => void)` | — | Solicita cerrar la superficie. |
 | `onClosed` | `(() => void)` | — | Avisa cuando concluye la salida de la superficie. |
 
-**Ejemplo**
-
-```tsx
-import { useState } from 'react';
-import { View } from 'react-native';
-import { Menu, Button, Text } from 'mobile-design/react-native';
-
-export default function Example() {
-  const [feedback, setFeedback] = useState('');
-  const [visible, setVisible] = useState(false);
-
-  return (
-    <View style={{ gap: 16 }}>
-      <Menu
-        visible={visible}
-        onDismiss={() => setVisible(false)}
-        anchor={
-          <Button
-            variant="tonal"
-            onPress={() => setVisible(true)}
-          >
-            Opciones
-          </Button>
-        }
-      >
-        <Menu.Item
-          title="Guardar"
-          leadingIcon="bookmark-outline"
-          onPress={() => setFeedback('Guardado')}
-        />
-        <Menu.Item
-          title="Enviar"
-          leadingIcon="send-outline"
-          onPress={() => setFeedback('Enviar')}
-        />
-      </Menu>
-      <Text accessibilityLiveRegion="polite">{feedback}</Text>
-    </View>
-  );
-}
-```
-
 #### Dialog y FullScreenDialog
 
 Presenta información o una tarea que necesita atención antes de volver al contenido anterior.
@@ -1183,47 +1035,6 @@ Monta `GestureHandlerRootView` como se muestra en el ejemplo de instalación. Us
 | `variant` | `"standard" \| "modal"` | `'modal'` | `standard` comparte el layout y `modal` presenta una hoja superpuesta. |
 | `snapPoints` | `(string \| number)[]` | — | Posiciones de reposo de la hoja. Admite puntos en dp o porcentajes según el tipo. |
 
-**Ejemplo**
-
-```tsx
-import { useState } from 'react';
-import {
-  BottomSheet,
-  BottomSheetScrollView,
-  Text,
-  Button,
-} from 'mobile-design/react-native';
-
-export default function Example() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <Button onPress={() => setOpen(true)}>Ver detalles</Button>
-      <BottomSheet
-        open={open}
-        onOpenChange={setOpen}
-        variant="modal"
-        scrollable
-        snapPoints={['50%', '85%']}
-        accessibilityLabel="Detalles de la colección"
-      >
-        <BottomSheetScrollView contentContainerStyle={{ padding: 24 }}>
-          <Text variant="headlineSmall">Tu colección</Text>
-          <Text>Información adicional de la colección guardada.</Text>
-          <Button
-            variant="text"
-            onPress={() => setOpen(false)}
-          >
-            Cerrar
-          </Button>
-        </BottomSheetScrollView>
-      </BottomSheet>
-    </>
-  );
-}
-```
-
 #### SideSheet
 
 Muestra una tarea complementaria desde un borde lateral, como parte del layout o en una superficie modal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-design",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Material Design 3 components for React Native and React Native Web, built on React Native Paper",
   "keywords": [
     "material-design",
@@ -38,7 +38,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@mobile-design/tokens": "0.1.1"
+    "@mobile-design/tokens": "0.1.2"
   },
   "peerDependencies": {
     "react": ">=19.2.0",