OASIS_MOBILE/GUIA_DE_DESARROLLO.md

Guía de desarrollo

Notas para quien vaya a meter mano en la rama del móvil. Leedlas antes de empezar, que nos ahorramos disgustos.

Esta rama va encima de Oasis, que es de epsylon. Él saca versión casi cada día (39 entre la 1.0.1 y la 1.3.3, en siete semanas) y cada versión llega en un solo commit. Si metemos cosas en sus ficheros, en cada integración hay que volver a pelearse con ellas. Por eso la idea es sencilla: lo de Oasis lo cambia él; nosotros cambiamos cómo se ve y se usa en el móvil, y lo hacemos en ficheros nuestros.

Los números y de dónde salen están en docs/FRONTERA_UPSTREAM.md.

Lo que no se toca

• src/backend/backend.js. Cambia en 34 de cada 39 versiones. Ni rutas nuevas, ni middleware, ni envolver funciones suyas como checkMod.
• La cadena de middleware del final de backend.js. Crece en cada versión.
• Los modelos de src/models/, salvo los nuestros (karvan_model.js, fork_workflows.js). Ahí se decide qué se publica en la red y cómo se cuenta. Si lo cambiamos, nuestro móvil cuenta distinto que el escritorio de al lado. Un ejemplo real: quien crea una votación no puede votar en ella. No nos gusta, pero es una regla del modelo, así que se explica en pantalla y punto.
• src/server/ (arranque de SSB, ssb_config.js, package.json).
• src/backend/request_guards.js, que lleva la CSP. Nada de style="" ni de <script> en la página.
• Las traducciones del dev, translations/oasis_*.js. Se reescriben casi en cada versión.
• styles/style.css y styles/mobile.css.
• Los temas del dev: Dark, Clear, Purple, Matrix y también OasisMobile.css, que aunque parezca nuestro es suyo (lo toca en 21 de 39 versiones).

Las vistas del dev: una línea y ya

src/views/*_view.js y main_views.js son del dev y las reescribe a menudo (tribes_view.js en 23 versiones, main_views.js en 31). Si en una pantalla suya hace falta otro HTML en el móvil, el código va en src/views/mobile_ui.js y en la vista solo queda la llamada:

const mobileUi = require('./mobile_ui');
// ...
if (mobileUi.isMobile()) return mobileUi.tribeTabs(tribe, section, sections);

Cuando el dev reescribe la vista, se vuelve a poner esa línea y listo. En escritorio no cambia nada porque la bandera OASIS_MOBILE solo la pone main.js en el móvil.

Ahora mismo hay enganches en main_views.js, tribes_view.js, vote_view.js, settings_view.js y welcome_view.js. Para verlos: grep -n mobileUi src/views/*.js.

Lo que es nuestro

Aquí se puede hacer lo que haga falta.

• src/client/assets/styles/mobile_base.css: la maqueta del móvil (lanzador, barras, tarjetas, formularios). Se carga siempre en el móvil, antes del skin.
• src/client/assets/styles/mobile_ux.css: márgenes, letra, botones y todas las piezas nuevas. Vale para los dos skins de móvil.
• src/client/assets/themes/Acampada.css y styles/hive_acampada.css: el skin Acampada.
• styles/karvan.css, src/views/karvan_view.js, src/models/karvan_model.js, src/client/public/js/karvan.js: Karvan entero.
• src/views/mobile_ui.js: lo que se enchufa en vistas del dev.
• src/views/mobile_modules_view.js, identities_view.js: pantallas propias.
• src/views/hive_views.js: lanzador y barras de arriba y abajo.
• src/views/mobile_icons.js: los iconos.
• src/backend/karvan_routes.js: nuestro router. Va justo delante del del dev.
• src/models/fork_workflows.js: nuestros workflows.
• src/client/assets/translations/i18n_fork.js: nuestros textos.
• src/client/assets/images/ux-*.svg: nuestras imágenes.
• android/.

Cómo hacer cada cosa

Cambiar cómo se ve algo. Se busca la clase en el HTML (servidor local e inspector) y se escribe la regla en mobile_ux.css. Para los colores usad las variables --ux-* (--ux-bg, --ux-fg, --ux-accent, --ux-muted, --ux-line, --ux-danger), que tiran de Acampada si está y si no de la paleta de OasisMobile. Si la regla no gana, es que mobile.css o Acampada.css mandan con !important y selectores largos: hay que subir la especificidad y poner !important también. Ojo con una trampa: Acampada.css quita el borde a todos los div, así que para ponérselo a uno hace falta .main-column div.la-clase.

Letra: Anton para títulos y para el botón negro principal de cada pantalla (.create-button). Lo demás, letra del sistema en negrita.

Márgenes: 14 px a cada lado y ya. Los contenedores de en medio sin relleno, que antes se iban sumando y una ficha perdía 74 px por lado.

Cambiar el HTML de una pantalla del dev. Función en mobile_ui.js y una línea en la vista, como arriba.

Una pantalla o una ruta nueva. En karvan_routes.js. Lo que no atiende nuestro router pasa al del dev con next():

.get('/modules', async (ctx, next) => {
  if (!isMobile()) return next();   // escritorio: la del dev
  ctx.body = mobileModulesView({ ... });
})

Retocar lo que contesta el dev. También en karvan_routes.js, en wrapUpstream: deja que el dev conteste y luego mira la respuesta. Así sabemos a qué sección apagada se quería entrar (el dev solo manda a /modules) o añadimos ?saved=1 al guardar.

Textos. En i18n_fork.js y en los 11 idiomas (en, es, fr, eu, de, it, pt, zh, ar, hi, ru). Antes, mirad que la clave no exista ya en oasis_en.js, porque si existe la estaríais cambiando también en escritorio. En el código siempre con texto de reserva: i18n.miClave || 'My text'.

Un workflow. En fork_workflows.js, que lo mete en las listas que exporta el modelo del dev. No se toca workflows_model.js.

Un icono. En mobile_icons.js, trazo de 2 px sobre rejilla de 24 y currentColor. El nombre es el de la ruta: /tribes es tribes.

Antes de hacer commit

• Que git diff --stat no toque nada de la lista de lo que no se toca. En las vistas del dev, solo líneas de enganche.
• node --check en los .js que hayáis cambiado.
• Arrancar en local y ver que /activity, /tribes, /modules, /settings, /votes, /karvan e /inbox cargan.
• Mirarlo a 412 px de ancho, y a 360 si es algo ancho.
• Los textos nuevos, en los 11 idiomas.
• Nada en línea, que la CSP lo bloquea.
• Commit en castellano, sin coautorías de herramientas.
• Sin claves, contraseñas ni nada de .ssb.

Cuando sale versión nueva del dev

1. Lo suyo se coge tal cual.
2. En sus vistas se vuelven a poner los enganches. El grep -n mobileUi sobre la versión anterior de la rama dice dónde iban.
3. Se repite la medición de docs/FRONTERA_UPSTREAM.md: qué ha tocado y si ha desaparecido alguna clase que usen nuestras hojas.
4. Se repasan a 412 px las pantallas de la lista de arriba.
5. Se compila la APK con la oficial de esa misma versión como base (android/scripts/release.sh con OASIS_APK_BASE).

Probar en local

HOME=/tmp/oasis-prueba OASIS_NETWORK_PAUSED=1 node main.js

Y en el navegador http://localhost:3000 con el inspector en modo móvil a 412x915. Va con una identidad de usar y tirar y con la red parada.

Cosas que pasan:

• src/server/node_modules no está en git. Sirve el de la APK base.
• Si al reiniciar sale "Another Oasis instance is already running", el anterior sigue vivo y estáis viendo código viejo. Matadlo primero.
• Al arrancar desaparecen src/configs/banking-eco-history.json y fediverse-accounts.json. Antes del commit, git checkout -- src/configs/.

En el emulador (Pixel_9_API_36 de Android Studio), la APK de depuración deja inspeccionar la WebView desde chrome://inspect.

Lo que todavía está mal

Cosas de antes de estas normas que aún no las cumplen, por orden de lo que más duele:

1. Quedan 21 trozos nuestros en backend.js (copia de seguridad, avatar de la barra de arriba, vídeos, filtro del lanzador...). Tienen que irse al router propio.
2. En workflows_model.js queda la logica de skins del movil (themeOf, sameTheme): settings_view.js coge currentWorkflow al cargar y no se puede envolver desde fuera sin tocar esa vista. Es poco, pero es del dev.
3. Selectores que ya no apuntan a nada: unos 60 en styles/mobile_base.css, 29 en hive_acampada.css y 5 en Acampada.css.