Dev Notes

This file documents some advices working on the app.

Debugging for iOS

You can debug on the Safari on iOS only if you have mac (and run macOS). The certain workarounds don't work well. Here are some tips:

GNOME Web (epiphany) uses webkit2gtk, the same engine from Safari. Most of bugs can be reproduced on it.
For visual bugs: on you iDevice, redirect the localhost.direct to your dev computer. Now you have the hot reload on you iDevice.
- You can use network debugging apps like "Shadowrocket" to do such thing.

The components don't react to the change as I setting the store, until the page reloaded

The WritableAtom<unknwon>.set might do an equals check. You must set a different object to ensure the atom sending a notify.

The code below may not notify the change:

export function updateAcctInf(idx: number) {
  const o = $accounts.get();
  // ...
  o[idx].inf = inf;
  $accounts.set(o);
}

Instead, set a new object:

export function updateAcctInf(idx: number) {
  const o = $accounts.get();
  // ...
  o[idx] = Object.assign({}, o[idx], { inf });
  $accounts.set(Array.from(o));
}

Ja, the code is weird, but that's the best we know. Anyway, you need new object on the path of your changed value.

`transition: -block or -inline` does not work on WebKit

Idk why, but transition on logical directions may not work on WebKit - sometimes they work.

Use physical directions to avoid trouble, like "margin-top, margin-bottom".

Safe area insets

For isolating control of the UI effect, we already setup css variables --safe-area-inset-*. In components, you should use the variables unless you have reasons to use env().

Using --safe-area-inset-*, you can control the global value in settings (under dev mode).

Module Isolation

Write the code that can be easily removed.

To limit the code impact, we organize the code based on "topic modules" (modules in short). Each module focus on a specific topic described by the name. Like the "accounts" contains the code about the accounts, "masto" contains the code about the masto (a library used to access mastodon) helpers.

Sidenote: This also helps easing "the landing problem". If you need something about accounts, no longer "common/accounts" and "hooks/accounts" and "helpers/accounts" and "components/accounts". Someone says this is clean - is it even if you need to jump between 6 directories for how one simple feature works? And you no longer needs to think about "where to place this file (between six directories, usually)". People often optimize their code structure too early - just like how they treat the runtime performance. The worse is, it's very hard to solve this problem later, because you had sent your code to different places.

There are two special modules in this project:

One is the platform. This module provides foundation of this app: deals with the host platform (like SizedTextarea - auto resized textarea), provides custom platform feature (like StackedRouter - provides mobile-native navigation experience).

The another is the material. This module provides Material styling toolkit, the stylesheets, MUI Theme, constants and components.

They (and only them) can be accessed by special aliases: ~{module name}, like the ~platform.

We discourage cross referencings between two topics. Reuse is not better than duplication. Cross referencing is still possible if required.

When a tool, a file or a component is required every-elsewhere, promoting is required to reduce the cross referencing. Thanksfully, it's usually automated process for moving files.

But, sometimes you need a redesigned (sometimes better) tool for the generic usage. Follow the idea:

Move slowly or crash. Only make the change if it's required.
Try to make the original part depends on your new tool, and keep the original for awhile.
Mark deprecated only if you think the original won't worth an existence. Reasons:
- Migrate to the new code only needs minor change.
- The original code has critical problems, like performance or compatibility.
Make notes. Communication is important, even with the future you.
- Why this move is decided?
- What this new tool does?
- How this tool works?
Clean up code regularly. Don't keep the unused code forever.

4.3 KiB Raw Blame History