tutu/docs/devnotes.md

# 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)](https://apps.gnome.org/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:

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

Instead, set a new object:

```ts
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.