mobile-design 0.1.1 → 0.1.3

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) · [Stack](#tema-del-stack) · [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`.
 
@@ -223,39 +251,76 @@ export function createBrandTheme(mode: 'light' | 'dark') {
 
 Pasa `theme={createBrandTheme(mode)}` al proveedor, donde `mode` viene del sistema o de la preferencia guardada por tu app. Para ofrecer varios temas de marca, conserva un mapa de roles por marca y modo y usa la marca activa al construir el tema. `createMobileDesignColors` adapta roles existentes y espera un registro completo de tokens. En particular, `surfaceDisabled`, `onSurfaceDisabled` y `backdrop` son roles planos de compatibilidad que el adaptador de Paper no incorpora.
 
-En el workspace de desarrollo existe el comando `pnpm theme:generate '#246B57'`. Genera las dos paletas mediante Material Color Utilities y escribe el módulo de colores, sus tipos y el bloque CSS generado del workspace. `pnpm theme:generate md3-baseline` restaura la paleta MD3 publicada y `pnpm theme:generate neutral` genera el preset neutro. Estos comandos corresponden al código fuente del workspace. En una app que instala el paquete usa los roles de tokens, el exportador externo y las APIs de tema anteriores.
+En el workspace de desarrollo existe el comando `pnpm theme:generate '#246B57'`. Genera las dos paletas mediante Material Color Utilities y escribe el módulo de colores y sus tipos dentro de @mobile-design/tokens. `pnpm theme:generate md3-baseline` restaura la paleta MD3 publicada y `pnpm theme:generate neutral` genera el preset neutro. Estos comandos corresponden al código fuente del workspace. En una app que instala el paquete usa los roles de tokens, el exportador externo y las APIs de tema anteriores.
+
+### Tema del stack
+
+```ts
+import { DarkTheme, DefaultTheme } from '@react-navigation/native';
+import { createMobileDesignTheme } from 'mobile-design/react-native';
+import { adaptNavigationTheme } from 'react-native-paper';
+
+export const { LightTheme: navLight, DarkTheme: navDark } = adaptNavigationTheme({
+  reactNavigationLight: DefaultTheme,
+  reactNavigationDark: DarkTheme,
+  materialLight: createMobileDesignTheme({ colorScheme: 'light' }),
+  materialDark: createMobileDesignTheme({ colorScheme: 'dark' })
+});
+```
+
+Dentro de `MobileDesignProvider`, usa `useMobileTheme().dark` para elegir el tema de `NavigationContainer`. Con `headerShown: false`, tu `TopAppBar` usa los colores y Roboto del proveedor. [Stack completo](examples/navigation-stack.tsx) con tres pantallas y un `ScreenLayout` reutilizable. Usa `<ScreenLayout title="Perfil">…</ScreenLayout>` para componer otra pantalla.
 
 ## Tipografía e iconos
 
-Roboto es la tipografía predeterminada. El proveedor usa un subconjunto de Material Symbols Rounded que cubre los controles y ejemplos de integración. El proveedor carga las fuentes predeterminadas que utiliza el tema o el renderizador activo. Para elegir otra tipografía, registra su familia y los pesos que utilices en tu app y pasa, por ejemplo, `fontFamily="Inter"`.
+Para **Roboto y los símbolos incluidos**, basta `MobileDesignProvider`. El proveedor carga esas fuentes cuando se usan.
+
+### Incrustar fuentes con Expo
+
+Usa el plugin si necesitas una fuente incrustada en Android o iOS, disponible desde el arranque. Añade la entrada a `expo.plugins` en `app.json` y recompila. Las rutas parten de la raíz de la app.
+
+```json
+{
+  "expo": {
+    "plugins": [["expo-font", {
+      "android": { "fonts": [{
+        "fontFamily": "Inter",
+        "fontDefinitions": [
+          { "path": "./assets/fonts/Inter-Regular.ttf", "weight": 400 },
+          { "path": "./assets/fonts/Inter-Bold.ttf", "weight": 700 }
+        ]
+      }] },
+      "ios": { "fonts": ["./assets/fonts/Inter-Regular.ttf", "./assets/fonts/Inter-Bold.ttf"] }
+    }]]
+  }
+}
+```
+
+Selecciona `fontFamily="Inter"` en el proveedor. En iOS usa el nombre interno de la familia. Incluye los pesos y estilos que necesites.
+
+### Cargar una fuente propia al iniciar
 
-Agrupa las caras de una misma familia para que Expo pueda elegir el peso correcto. Coloca los archivos de tu fuente en la app y adapta las rutas del ejemplo. Monta `CustomTypeface` en el lugar que ocupa el proveedor en el primer ejemplo.
+Usa `useFonts` para cargar la familia en ejecución, también en web.
 
 ```tsx
 import { useFonts } from 'expo-font';
 import { MobileDesignProvider, Text } from 'mobile-design/react-native';
 
-const fonts = [
-    {
-        fontFamily: 'Inter',
-        fontDefinitions: [
-            { path: require('./assets/fonts/Inter-Regular.ttf'), weight: 400 },
-            { path: require('./assets/fonts/Inter-Bold.ttf'), weight: 700 },
-        ],
-    },
-] satisfies Parameters<typeof useFonts>[0];
-
 export function CustomTypeface() {
-    const [ready, error] = useFonts(fonts);
-    if (error) throw error;
-    if (!ready) return null;
-
-    return (
-        <MobileDesignProvider fontFamily="Inter">
-            <Text variant="bodyLarge">Contenido</Text>
-            <Text variant="titleLarge" style={{ fontWeight: '700' }}>Encabezado</Text>
-        </MobileDesignProvider>
-    );
+  const [ready, error] = useFonts([{
+    fontFamily: 'Inter',
+    fontDefinitions: [
+      { path: require('./assets/fonts/Inter-Regular.ttf'), weight: 400 },
+      { path: require('./assets/fonts/Inter-Bold.ttf'), weight: 700 },
+    ],
+  }]);
+  if (error) throw error;
+  if (!ready) return null;
+  return (
+    <MobileDesignProvider fontFamily="Inter">
+      <Text variant="bodyLarge">Contenido</Text>
+      <Text variant="titleLarge" style={{ fontWeight: '700' }}>Encabezado</Text>
+    </MobileDesignProvider>
+  );
 }
 ```
 
@@ -292,12 +357,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 +430,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 +530,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
@@ -525,6 +542,7 @@ El contador muestra la longitud. `maxLength` establece el límite. El ref `TextF
 | --- | --- | --- | --- |
 | `value` · requerida | `string` | — | Valor actual controlado por la pantalla. |
 | `onChangeText` · requerida | `(value: string) => void` | — | Comunica el nuevo texto para actualizar el valor controlado. |
+| `size` | `"standard" \| "compact"` | `'standard'` | Altura base de una línea de 56 dp con `standard` o 48 dp con `compact`, en Filled y Outlined. Respeta el escalado del texto. |
 | `variant` | `"filled" \| "outlined"` | — | Tratamiento visual o modalidad del componente. |
 | `error` | `boolean` | — | Activa el tratamiento visual y accesible de error. |
 
@@ -539,6 +557,7 @@ export default function Example() {
 
   return (
     <TextField
+      size="compact"
       variant="outlined"
       label="Nombre de la colección"
       value={name}
@@ -844,61 +863,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 +1029,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 +1046,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 +1074,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/examples/navigation-stack.tsx

@@ -0,0 +1,132 @@
+import { mobileDesignTokens } from '@mobile-design/tokens';
+import { DarkTheme, DefaultTheme, NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator, type NativeStackScreenProps } from '@react-navigation/native-stack';
+import type { PropsWithChildren } from 'react';
+import { ScrollView, StatusBar, StyleSheet, View } from 'react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { adaptNavigationTheme } from 'react-native-paper';
+import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
+import { Button, MobileDesignProvider, Text, TopAppBar, createMobileDesignTheme, useMobileTheme } from 'mobile-design/react-native';
+
+type RootStackParamList = {
+    SignIn: undefined;
+    SignUp: undefined;
+    ForgotPassword: undefined;
+};
+
+type ScreenProps<Route extends keyof RootStackParamList> = NativeStackScreenProps<RootStackParamList, Route>;
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+
+const { LightTheme: navigationLightTheme, DarkTheme: navigationDarkTheme } = adaptNavigationTheme({
+    reactNavigationLight: DefaultTheme,
+    reactNavigationDark: DarkTheme,
+    materialLight: createMobileDesignTheme({ colorScheme: 'light', fontFamily: 'Roboto' }),
+    materialDark: createMobileDesignTheme({ colorScheme: 'dark', fontFamily: 'Roboto' }),
+});
+
+type ScreenLayoutProps = PropsWithChildren<{
+    title: string;
+    heading?: string;
+    description?: string;
+    onBack?: () => void;
+    scroll?: boolean;
+}>;
+
+export function ScreenLayout({ title, heading, description, onBack, scroll = true, children }: ScreenLayoutProps) {
+    const { colors } = useMobileTheme();
+    const content = (
+        <>
+            {heading ? <Text variant="headlineSmall" accessibilityRole="header">{heading}</Text> : null}
+            {description ? <Text variant="bodyMedium" style={{ color: colors.onSurfaceVariant }}>{description}</Text> : null}
+            {children}
+        </>
+    );
+
+    return (
+        <View style={[styles.fill, { backgroundColor: colors.surface }]}>
+            <TopAppBar
+                title={title}
+                navigationIcon={onBack ? 'arrow_back' : undefined}
+                navigationLabel="Volver"
+                onNavigationPress={onBack}
+            />
+            <SafeAreaView style={styles.fill} edges={['left', 'right', 'bottom']}>
+                {scroll ? <ScrollView contentContainerStyle={styles.content}>{content}</ScrollView> : content}
+            </SafeAreaView>
+        </View>
+    );
+}
+
+function SignInScreen({ navigation }: ScreenProps<'SignIn'>) {
+    return (
+        <ScreenLayout title="Iniciar sesión" heading="Bienvenido" description="Elige cómo continuar con tu cuenta.">
+            <Button variant="filled" onPress={() => navigation.navigate('SignUp')}>Crear cuenta</Button>
+            <Button variant="text" onPress={() => navigation.navigate('ForgotPassword')}>Olvidé mi contraseña</Button>
+        </ScreenLayout>
+    );
+}
+
+function SignUpScreen({ navigation }: ScreenProps<'SignUp'>) {
+    return (
+        <ScreenLayout
+            title="Crear cuenta"
+            description="Aquí puedes integrar los pasos de registro de tu app."
+            onBack={() => navigation.goBack()}
+        />
+    );
+}
+
+function ForgotPasswordScreen({ navigation }: ScreenProps<'ForgotPassword'>) {
+    return (
+        <ScreenLayout
+            title="Recuperar contraseña"
+            description="Aquí puedes integrar la solicitud del código y el cambio de contraseña."
+            onBack={() => navigation.goBack()}
+        />
+    );
+}
+
+function RootNavigator() {
+    const { animation, colors, dark } = useMobileTheme();
+    const navigationTheme = dark ? navigationDarkTheme : navigationLightTheme;
+
+    return (
+        <NavigationContainer theme={navigationTheme}>
+            <StatusBar barStyle={dark ? 'light-content' : 'dark-content'} />
+            <Stack.Navigator
+                initialRouteName="SignIn"
+                screenOptions={{
+                    headerShown: false,
+                    animation: animation.scale === 0 ? 'none' : 'default',
+                    contentStyle: { backgroundColor: colors.surface },
+                }}
+            >
+                <Stack.Screen name="SignIn" component={SignInScreen} />
+                <Stack.Screen name="SignUp" component={SignUpScreen} />
+                <Stack.Screen name="ForgotPassword" component={ForgotPasswordScreen} />
+            </Stack.Navigator>
+        </NavigationContainer>
+    );
+}
+
+export default function App() {
+    return (
+        <GestureHandlerRootView style={styles.fill}>
+            <SafeAreaProvider>
+                <MobileDesignProvider fontFamily="Roboto">
+                    <RootNavigator />
+                </MobileDesignProvider>
+            </SafeAreaProvider>
+        </GestureHandlerRootView>
+    );
+}
+
+const styles = StyleSheet.create({
+    fill: { flex: 1 },
+    content: {
+        gap: mobileDesignTokens.spacing.small,
+        paddingHorizontal: mobileDesignTokens.spacing.medium,
+        paddingVertical: mobileDesignTokens.spacing.large,
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-design",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Material Design 3 components for React Native and React Native Web, built on React Native Paper",
   "keywords": [
     "material-design",
@@ -32,13 +32,14 @@
     "assets/logo.svg",
     "README.md",
     "COMPONENTS.md",
+    "examples/navigation-stack.tsx",
     "LICENSE",
     "NOTICE",
     "LICENSE-Apache-2.0.txt"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@mobile-design/tokens": "0.1.1"
+    "@mobile-design/tokens": "0.1.3"
   },
   "peerDependencies": {
     "react": ">=19.2.0",
@@ -62,5 +63,10 @@
     "react-native-web": {
       "optional": true
     }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicolas-rm/mobile-design.git",
+    "directory": "library/packages/mobile-design"
   }
 }