Dawnline 0.20.0
Build packages / CI (push) Blocked by required conditions
Build packages / Version (push) Waiting to run
CI / Web (format, types, tests, bundles) (push) Blocked by required conditions
CI / ShellCheck (push) Blocked by required conditions
CI / Backend (Go: vet, tests, a real ubusd and uhttpd) (push) Blocked by required conditions
CI / Package files (push) Blocked by required conditions
Build packages / CI (push) Blocked by required conditions
Build packages / Version (push) Waiting to run
CI / Web (format, types, tests, bundles) (push) Blocked by required conditions
CI / ShellCheck (push) Blocked by required conditions
CI / Backend (Go: vet, tests, a real ubusd and uhttpd) (push) Blocked by required conditions
CI / Package files (push) Blocked by required conditions
- **Backend rewritten in Go.** One daemon, `dawnlined`, replaces the whole ucode backend: the rpcd plugin, the agent, the CLI and the updater. The package no longer depends on ucode. - **Per-architecture builds.** The release carries the backend for arm64, ARMv7, mips, mipsle and amd64; the router fetches its own after the package is installed and checks its sha256. Dawnline does not run on other architectures (older ARM, 32-bit x86, RISC-V). - **Faster on the router.** A firewall sync takes 0.06 s instead of 0.9 s; a full apply takes about 300 ms. The portal is served by the daemon itself, without a CGI process per request. - **Live pages.** The admin and the portal follow a live stream from the router instead of re-fetching the whole state every 30 seconds. - **Admin redesigned in the portal's style.** Three sections (Overview · Log · Settings); a server is a page of its own with People, Places and Settings; a device opens as a dialog over its person. - **Changes wait for «Apply».** Every setting, and a person's access, is staged in one dock before it reaches the router. - **Configuration rollout.** After a change that makes devices fetch their configuration again, the admin shows how many have fetched it and who has not. Every setting shows beforehand (⟳N) how many devices it will touch. - **Waiting for a decision.** Overview and People put first the people who need one (access ended, limit reached, a device that does not connect), each with its one action a tap away. - **Bulk actions on people.** «Select» (or a long press on a card) picks several people to extend by a month, pause or resume at once. - **Undo.** An action done from a card or a request is undone from its toast. - **Update dialogs redesigned.** An update is one view from its question to its result; Dawnline's own update runs in it like every other, and the page reloads itself once the new version answers. Other versions are a list, each with its notes and Install on a page of its own. - **Site to site: networks behind a router.** A router connected as a device can have networks behind it (up to eight, /16 to /30): the server routes them and applies the router's access to them. A network that shares addresses with a tunnel, the router's own networks or another site is refused by name. - **Routers from the portal.** People can add a router and name its networks on their own page; the admin accepts or declines with a reason, or lets them through without asking. - **Check access and Health know the networks behind routers.** - **Usage limits reworked.** A monthly limit no longer follows the calendar. A person's month starts with their first traffic and ends a month later; the next one starts only when they connect again, so time away uses up none of it. Before, everyone's limit reset on the 1st. - Extra data lasts until that person's month ends; «Reset usage» starts the month anew. - A limit is for a month or for the whole term; the admin and the portal show when it resets. - Charts that said «this month» show the last 30 days. - After the update nobody loses what was counted: the month that was running becomes the person's first and ends on the 1st. - **Access by time of day removed.** The Hours limit is gone from the admin, the portal and the backend; saved hours are dropped. - **Expiry simplified.** An end date always stops access, with a heads-up three days before; the per-person choice is gone. - **No false disconnects from sleeping phones.** A phone or a tablet stays online through ten minutes of silence. - **Mobile Safari fixes.** Pressing a control no longer sends the page to its top; tab tracks that do not fit scroll; switches animate after a press.
This commit is contained in:
1 parent
f8130e39a8
commit
ac90575b0b
788 files changed
+139244
-41720
No files matched your search
@@ -0,0 +1,37 @@
|
||||
# Backend (Go: `backend/`)
|
||||
|
||||
Read with `code-standards.md` (it applies whole: one job per package, layers one way, validate at the boundary, one writer, fail closed) and `docs/backend.md` (where the backend is going and the stream's protocol).
|
||||
|
||||
## Packages
|
||||
|
||||
- One package, one job, named after it, with a package comment that says what it owns, what it does not and what callers rely on. `backend/version.go` lists them and the layers.
|
||||
- **Layers:** `ubus` and `hub` know nothing of Dawnline or of each other; `api`, `bridge` (and later the producers) join them; `daemon` runs them; only `cmd/dawnlined` knows the router's paths.
|
||||
- **One door per outside system.** Only `ubus` speaks ubus; when they come, only one package runs `awg`, one talks nftables, one writes UCI. A new version of the thing behind a door is one package to change.
|
||||
- **Seams are interfaces declared by the user** (`bridge.Caller`, `api.Notifier`), so a test hands in a stand-in. No package-level state.
|
||||
- **No dependency without a reason written in the change that adds it.** The standard library covers the stream; nftables and netlink will need libraries.
|
||||
- **Not copied from podkop-exp** (GPL; Dawnline is MIT): its patterns, never its code.
|
||||
|
||||
## The stream
|
||||
|
||||
- A producer **puts whole documents** (`hub.Put`) and never builds a patch; it may put as often as it likes.
|
||||
- Documents hold **no `null`** and publish lists of things with ids as **keyed lists** (`{ order, items }`).
|
||||
- What costs something to produce runs **only under a lease** (`Audience.Wants`).
|
||||
- A new topic or method is added to `docs/backend.md`, and a method to the rpcd ACL (`acl.d/luci-app-dawnline.json`) in the same change.
|
||||
- Text people read is not put into topics: the page translates (`i18n.md`). A topic carries codes and values.
|
||||
|
||||
## Failures
|
||||
|
||||
- **A refusal is a sentence for a person, capital first**, in English through the catalog (`access.Said`, `said`, `github.Failure`, `w.die`), listed in `i18n/messages.js`. An error Go or a library wrote for programmers (lower-case first, by Go's convention: «open /etc/config/dawnline: no such file») is never sent to a page: `methods.wordsOf` sends the plain sentence (`methods.Unworded`) and puts the error itself in the system log. The page holds the same line (`web/src/admin/failure.ts`).
|
||||
|
||||
## Cost on the router
|
||||
|
||||
- Nothing periodic without a measurement on the router. What was measured there: `nft` reads the router's whole ruleset to change a set in place (0.9 s beside a proxy's lists) and nothing to replace our own table (0.06 s), so a sync replaces the table; `auto-merge` on an interval set costs the same 0.9 s, so networks are collapsed before they are written.
|
||||
- A goroutine per job, not per event; channels that can fill say what happens when they do (the hub lets a slow follower go).
|
||||
|
||||
## Checks
|
||||
|
||||
- **The goldens are the ucode backend's own answers.** `backend/*/testdata/*.json` were made by the ucode backend (0.18.0) from the fixtures beside them, before it was removed; nothing regenerates them. A test that compares with one holds Go to what that backend did. Changing behaviour on purpose means editing the golden by hand in the same change, and saying why in it.
|
||||
- `scripts/backend-container.sh` (needs docker): gofmt, `go vet` (all build tags), the unit tests, then the tests against a real `ubusd`, `rpcd` and `uhttpd` in the OpenWrt 24.10 and 25.12 rootfs images.
|
||||
- A pure function gets a table test beside it; what speaks to the router gets a case in a tagged test (`ubusd`, `e2e`) that the script runs.
|
||||
- **Local time is the router's, asked of `zone.Local()`**, never `time.Local`: OpenWrt keeps the zone in `/etc/TZ`, where Go does not look, so a Go program there is in UTC unless told (`backend/zone`). A golden made with `TZ=UTC` cannot see a mistake here: test what counts days or hours in a zone east of Greenwich.
|
||||
- **There is no second backend to fall back to.** What changes how the router is kept is tried first where it changes nothing (`ubus call dawnline apply_plan` and `sync_plan` say what an apply or a sync would do), and on the real router only on objects made for the try. A person's link code is never logged, printed or put in an error.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Backend (ucode on the router)
|
||||
|
||||
Read with `code-standards.md`. Everything here runs on a small router (2 × Cortex-A53 on the reference Cudy WR3000P): cost is part of correctness.
|
||||
|
||||
## Layers
|
||||
|
||||
- `util`, `schema` (validation) → `core` (model, allocation) → `store` (the only writer of `/etc/config/dawnline`) → domain modules (`net`, `nft`, `fw`, `netifd`, `awg`, `loop`, `resolver`, `live`, `health`, `backup`, …) → `apply` (reconciliation) → entry points (`rpc/*`, `portal`, the `dawnline` CLI, the agent, the updater).
|
||||
- Read models for the UI live in `view`; RPC modules translate arguments and call down, they hold no business logic.
|
||||
- The updater is a thin dispatcher over `upd_app` / `upd_awg` / `upd_pkgs`, with GitHub in `github`, the package manager in `pkg`, policy/locks/history in `updates`.
|
||||
- Live state: the agent's watcher owns who is online (`live.PRESENCE`); readers ask `live.online()`, never re-derive it from handshake ages. Online means the WireGuard session lives (`live.online_window()`: 190 s, longer for a device with a long keep-alive): traffic silence is no signal, a phone asleep is silent too. A device's link trouble (trying, shared, dropped, unstable) is the watcher's too (`dawnline.link`, `live.LINK`).
|
||||
|
||||
## ucode
|
||||
|
||||
- `'use strict'` in entry points; modules `import { … } from 'fs'` / `'dawnline.x'`. Subdirectories map to dots (`dawnline.rpc.status` → `dawnline/rpc/status.uc`).
|
||||
- Exported functions end with `};` (the compiler requires it). No destructuring. Regexes are POSIX (no `(?:)`, `\s\S` classes, lazy quantifiers); anchor them.
|
||||
- Modules with `export` cannot be loaded with `require()`: imports are static and compiled on every start of the script.
|
||||
- Doc comments (`/** … */`) on every export: what it returns, including the null/empty case.
|
||||
- Shell out through one small helper per module (`run()`/`sh()`), with `2>&1` captured and the exit code checked.
|
||||
- Messages people read (`die()` texts, check titles and details, phases) go through `_()` / `N_()` of `dawnline.i18n`, inside functions, with `sprintf()` for values (`i18n.md`).
|
||||
- nft changes load as one script (`nft.load()`, a transaction); tables Dawnline owns are named `dawnline*` and rebuilt whole (`table X` + `delete table X` + the table).
|
||||
|
||||
## Cost on the router
|
||||
|
||||
- **The portal is CGI:** every request starts ucode and compiles the module graph, about 140 ms of CPU before any work (a full `state` answer about 180 ms). No periodic polling from the portal; one request per user action. A person's answers read only their server's tunnel (`live.dump(m, sid)`: one `awg` process, however many servers).
|
||||
- **rpcd keeps the admin backend loaded:** LuCI RPC calls are cheap, so the admin UI may poll small methods often (`rev`), and the heavy ones (`status`) only on change or rarely.
|
||||
- **Code on the agent's 1-second watcher stays in the low milliseconds:** one `awg show <ifname> dump` per Dawnline tunnel, never `all` (another AmneziaWG interface's peers are not Dawnline's; about 4 ms with process start, 1 ms to parse), the model cached by the config file's mtime/inode (`core.load()` is about 4 ms), files written only when something changed. Slow work (geo lookups, apply) runs only on a transition.
|
||||
- **A regex literal is compiled every time it runs:** ucode calls regcomp for `/…/` each time the expression is evaluated, and musl's regcomp grows with the pattern. Bounded repeats are copied out (`{42}` about 1.7 ms on the WR3000P, `[A-Za-z0-9_.@-]{1,32}` 3 ms, two `{0,61}` 10 ms), alternations and classes add up (`/^(PrivateKey|Jc|Jmin|Jmax) /` 0.11 ms, `/^[0-9]+$/` 0.02 ms); matching a compiled regex takes 0.01–0.1 ms. In a loop or on a hot path, hoist the regex into a module `const` (compiled once, when the module loads — every portal request pays that too) or check with `length`/`substr`/`ltrim` (`util.valid_key`, `valid_host`, `valid_iface`).
|
||||
- Measure before and after on the router (a loop of 20–200 calls, `/proc/self/stat` CPU ticks, system busy from `/proc/stat`) when adding anything periodic.
|
||||
|
||||
## Checks
|
||||
|
||||
- `scripts/lint-ucode.py` and `scripts/ucode-container.sh` (compiles and runs `tests/ucode` in the OpenWrt rootfs containers; `scripts/check-ucode.sh` compiles on the router instead) pass before any deploy; new directories and entry points are added to `lint-ucode.py` and `scripts/compile-ucode.sh`, and executables to the mode check in `.github/workflows/ci.yml`.
|
||||
- Pure functions get a case in `tests/ucode/<module>.test.uc`; what reads the clock takes an optional `ts` so a test can pass one.
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
How code in our own projects (Dawnline first, the same spirit for Tachyon, liminal and the rest) is written. This file holds what applies everywhere; per area:
|
||||
|
||||
- `backend.md` — ucode on the router: layers, conventions, what things cost there.
|
||||
- `backend-go.md` — the backend (Go): packages, the stream, what things cost on the router.
|
||||
- `frontend.md` — TypeScript admin UI and portal: layout, live data.
|
||||
- `shell.md` — install, uninstall, init and CI scripts.
|
||||
- `ui-design.md` — how anything visible looks and how it gets approved.
|
||||
@@ -13,7 +13,7 @@ Match the code around you: its naming, comment density and idiom win over person
|
||||
|
||||
- **One module, one job, named after it.** A file you cannot describe in one sentence is two files. Starting points: ~300–400 lines for a ucode/TS module, ~60 lines for a function. Past that, split by responsibility, not by line count.
|
||||
- **Every module opens with a header comment**: what it owns, what it deliberately does not (and where that lives), and any invariant callers rely on (locks, files it writes, who may call it).
|
||||
- **Layers point one way.** Pure helpers and the data model know nothing about the router or the UI; orchestration calls them, never the reverse. Dawnline's layers are in `backend.md`.
|
||||
- **Layers point one way.** Pure helpers and the data model know nothing about the router or the UI; orchestration calls them, never the reverse. Dawnline's layers are in `backend-go.md` and `backend/version.go`.
|
||||
- **No god files, no grab-bag `ops`/`misc`/`kit` modules.** When a helper is used by one module, it stays private in that module.
|
||||
- **Delete, don't deprecate.** When something is replaced, move every caller and remove the old code in the same change; no shims, no commented-out blocks. The same goes for its strings: new text is translated in the same change, removed text leaves the catalogs (`i18n.md`).
|
||||
|
||||
|
||||
+27
-3
@@ -5,14 +5,38 @@ Read with `code-standards.md` and, for anything visible, `ui-design.md` and `i18
|
||||
## Code
|
||||
|
||||
- Strict TS, no `any` without a comment; types for RPC answers live in `shared/types.ts` / `admin/api.ts` and mirror the backend's shapes.
|
||||
- Layout of `web/src/admin`: `ui/` generic components (button, menu, modal, drawer, tooltip, toast, controls), `widgets/` composite house widgets, `state/` polling and scoping, `events/` the activity vocabulary (model without DOM, render separate), `updater/` the Components data layer, `cores/` per-protocol bits, `pages/<page>/` one folder per page split by section, `styles/*.css` one file per feature joined in `styles/index.ts`. Shared with the portal: `src/shared/`.
|
||||
- Layout of `web/src/admin`: `main.ts` (the LuCI module `dawnline.app`: one factory per view), `pages/<page>/` one folder per page split by part (overview; people with its cards, the notices over them, a person's and a device's page `person/` and `device/`, and its map view; log; settings with the server's path in the folder itself and the router's own sections in `router/`), `ui/` generic components (toast, files, glass, icons, tabs, page head and block head, edit rows, the choice row of the Updates block, stepper, and the kit below), `widgets/` composite house widgets (the rollout strip, timeline, line chart, live line, map box, the event feed, the address row, the disguise presets, and a panel's parts below), `flows/` sheets that do one thing in steps (a device's set-up, adding a device, new keys, a question, a close-up, a new server, the one question before a server's staged changes, a Health check's fix, an updater job as an operation and a restore or import on the job's stage (`job-stage.ts`: one view from a job's start to its end), Dawnline's versions, a release's notes, removing Dawnline), `shell/` the pages' frame inside LuCI (below), `state/` polling, the live revision and the live meter, `events/` the activity vocabulary (model without DOM, render separate; `scope.ts`: the Log's filters as its address says them), `updater/` the updater's jobs, release notes and automatic-update policy as data (pure), and the pure models of what pages say: `people/` (people and devices, the diagnosis; `card.ts` the parts of a person's card by state, its group and its order, the one source of every count of people; `presence.ts` since when someone is online and their week's hours, from the log), `servers/` (a server's path by Health check ids, its state, the rollout and ⟳N counts, the changes that wait to be applied, who reaches what, the disguise's parameters), `places/` (places and their replay; `places/render.ts` draws a device's places, or all of a person's devices), `system/` (the router sections' words), `overview/` (Overview's: the state line, the checks as a list and where each is fixed, who waits, the servers' numbers, today by the hour, the watchdog's news). `map.ts` is the admin's map (MapLibre). `demo/` is the admin outside LuCI over a made-up router in the page (LuCI's globals, the backend's answers from a fixed cast, the Outline theme's shell): what `scripts/capture-screenshots.mjs` takes the README's pictures from, built by `npm run build:demo` beside the portal's demo, never into a package; it answers questions only, and a page that asks it something new gets that answer added to `demo/router.ts`. Shared with the portal: `src/shared/`.
|
||||
- **Three sections and a server's page, pages inside a view instead of LuCI pages.** The row is Overview · Log · Settings (`shell/routes.ts`), each a LuCI view of its own. A server is a page behind Overview (`pages/server`), drawn by two views inside one frame (the way back, the server's head, the track Overview · People · Places · Settings): `server?server=&p=general|core|network` is its own Overview and the three parts of its settings (`&s=<stage>` brings a section into view; `serverUrl()`, and `settingsUrl(stage, server)` for «where this is set»), `people` is the People page scoped to it (`pages/server/people.ts` extends `PeoplePage` through its `scope()` and `chrome()`): a person's page takes the list's place (`ui/subpage.ts`; the list waits with its scroll and filters), Places is its map view, a device opens as a dialog over its person's page (`pages/server/device-dialog.ts`): `people?id=`, `people?device=`, `people?view=map` (`people/route.ts`, pure: the route, its query, and what a link inside the page leads to). Which server a People address means: the one its person or device is on, else the one this tab looked at last (`sessionStorage`), else the first. Settings keeps the router's own sections, one at a time behind a rail (`settings?p=updates|portal|defaults|history|backups|remove`, `pages/settings/route.ts`, pure). A page moves inside itself without a load: a pick that changes what is on screen is `pushState` (a person's page, a part of the server's page, Settings' section: Back returns; a page's own way back steps back in history when the entry before is where it leads), a filter or the order `replaceState`; a plain click on any link to the view is taken by the page, and code goes there with `visit()` (`shell/visit.ts`), never `location.href`. The old `person`, `device`, `places`, `system`, `health`, `diagnostics`, `updates` and `activity` nodes only send the browser on, and `settings` and `server` send on their own old queries (a stage of a server's path was Settings' `?p=`; `shell/redirects.ts`). A server's settings are keyed parts (`pages/settings/parts.ts`): a section is built again only when what it shows moved, and never while it is typed in.
|
||||
- **The kit** (`ui/`, classes `kt-*` in `styles/shadow/kit.css`): `filter-bar.ts` (the search, chips with counts, Reset, the count), `list-drop.ts` (a list of choices under its button: the picked one checked, a long list scrolling inside the glass), `subpage.ts` (a list and the page of one thing in it, in its place: the way back and ×, the list back where it was with the opened item ringed), `tip.ts` (the tooltip of a thing without words, above it or under it), `rail.ts` and `section.ts` (a page of sections: the rail with its highlight and jump pill, a section's head, cards, captions and notes), `option-tiles.ts` (a choice of two or three drawn, not described: a picture, a name, facts as pills, a round mark on the one in use), `range.ts` (a value on a scale with its named marks), `combo.ts` (a field that picks from its list as it is typed in), `measure.ts` (a measure with its limit; a value picked from a few), `inline-edit.ts` (a value edited where it stands), `comp-row.ts` (a row of a list of things with a state, its actions in sight), `empty.ts`, `face.ts`, `meter.ts`, `split.ts` (a map with its inspector as one stage: side by side as high as the window leaves, the inspector's body scrolling inside; narrower, the map over it), `page-head.ts` `blockHead`, and the glass dock at the window's foot (`.kt-dock`: People's selection, Settings' waiting changes). A page's parts (`widgets/`, `styles/shadow/widgets.css`): `term.ts`, `limit-meter.ts`, `reach.ts` (what they reach: two switch rows), `config-card.ts` (a device's set-up), `place-rows.ts` (place rows with strips), `feed.ts` (the feed's rows and their short form). They read `people/ctx.ts` (what a page's parts are given) and act through `flows/person-acts.ts`; a page's own classes are `pp-*` (`people.css`: the cards, the notices, picking; `panel.css`: a person's and a device's page; a person's is two columns, the main one and the access stack that stays in sight, one column under 760 with the stack first), `st-*` (`settings.css`, `settings-router.css`), `lg-*` (`log.css`), `ov-*` (`overview.css`).
|
||||
- **A server's changes wait.** In Settings no change of how a server works is made on the spot, whether devices fetch their configuration again after it (⟳N on its field) or not: it is staged (`servers/pending.ts`, pure: one staged change a kind, one `server_update` patch of every field, one `server_interfaces` patch of the home networks, the route and the WAN, what applying means for devices), its field shows the new value as not applied, the dock at the window's foot counts the changes and the devices, and «Apply» makes them (`pages/settings/changes.ts`): after one question that names them all (`flows/server-change.ts`) and one rollout when devices fetch again, at once when none does. Leaving the page while changes wait is asked about first (`pages/settings/pending-dock.ts`).
|
||||
- **Pick from a list as it is typed in: `ui/combo.ts`**, never a `<datalist>` (its popup and arrow are the system's). A list picked without typing is `ui/list-drop.ts` under its button.
|
||||
- **⟳N goes at the right end** of its row, head or caption (`reMark`; DESIGN.md › ⟳N): a builder that takes `re` places it there itself.
|
||||
- **The router-wide settings wait in the same dock.** A router section never calls `settings_update`: it hands values to `RouterCtx.save` (or `router/save.ts put`), `pages/settings/changes.ts` stages them (`system/draft.ts`, pure: what equals the router's value stops waiting, `withDraft` puts each staged value where its section reads it: `settings`, `effective`, `logs.policy`, `effective.updates`), and «Apply» sends them in ONE call before the server's own. A new setting key that a section reads from somewhere else gets its place in `system/draft.ts`.
|
||||
- **A person's changes wait too.** On a person's page what they reach, their limit and its period and their device limit go through `people/draft.ts` (pure: what waits and what is saved at once, the person as they would be, the devices that fetch again): the page draws `preview(person, draft)`, marks the parts with «not applied», and the same dock applies the draft in ONE `person_update` (a question first when devices fetch again). A widget keeps calling `PersonCtx.patch`; the page decides what waits.
|
||||
- **A fix stands where the problem is.** A Settings section shows the Health checks that are about it (`servers/path.ts` for a stage, the portal's by id) with the fix as a button or the advice (`pages/settings/health.ts`, `flows/health-fix.ts`); Overview lists the same check as a link to that section, and keeps a fix button only for a check no section is about (`overview/model.ts` `fixPlace`, `ownFix`).
|
||||
- **Four LuCI modules**, built by one tsup entry list with `splitting: false` (one self-contained file per module, `patchForLuci` on each), each refused by the build over 576 KiB (uhttpd sends them uncompressed; 512 until 2026-11-12, when the owner raised it for the networks behind routers rather than split the pages' module):
|
||||
- `dawnline.app` (`main.ts`): every page; the thin files in `view/dawnline/*.js` do `return view.extend(app.<view>())` with `'require dawnline.app as app'`. The old addresses' views are factories here too, each sending the browser on at once (`shell/redirects.ts`, pure and tested).
|
||||
- `dawnline.style` (`style-module.ts`): the pages' stylesheet as text; each view loads it with its data (`shell/style.ts`). It also brings the pictures a page draws as soon as it stands, which the pages' module has no room for: the admin's glass shapes (`ui/glass-shapes.ts`), its line icons (`ui/line-icons.ts`) and the products' marks; a new shape or line icon goes into those files, not into `ui/glass.ts` or `ui/icons.ts` (a shape that carries a mark is the exception: `ui/glass.ts`).
|
||||
- `dawnline.map` (`map-module.ts`): `map.ts`, `places/render.ts` and their sheet (`styles/shadow/maps.css`), loaded with `L.require` the first time a page draws a map (`shell/maps.ts`): the map box holds its place meanwhile (`widgets/map-box.ts`), the close-up opens once it is in. The app module imports the map's **types only**; the build fails if `app.js` bundles MapLibre's loader or the stylesheet.
|
||||
- `dawnline.qr` (`qr-module.ts`): the QR generator (`shared/qr.ts` with its library), loaded with `L.require` when a sheet draws a code (`shell/qr.ts`: `loadQr()` beside the sheet's request to the router, `qrBox()` holds the code's place). It is pure; the build fails if `app.js` bundles the generator.
|
||||
- A module loaded on demand has its own copy of what it shares with the pages, so it must not depend on their state: what it needs (the layer) is handed in (`bind`). Put there only what a page rarely needs and what keeps a module under its budget.
|
||||
- `shell/` is the pages' frame inside LuCI: `host.ts` (a Shadow DOM host adopting the constructed stylesheets, the page's and those added later by a module loaded on demand, theme from `html[data-darkmode]`, focus rings), `layer.ts` (the second host on `<body>` for the sheet, menus, toasts and the map's marker card; the portal's modules draw there through `portal/ui/layer.ts`), `nav.ts` (the page's own section row), `routes.ts` (addresses and sections), `redirects.ts` and `moved.ts` (old addresses), `role.ts` (read-only logins), `toast.ts` (the portal's toast in the layer, with undo; `ui/toast.ts` `notify()` goes there), `style.ts` and `maps.ts` (the modules loaded with a view or on demand).
|
||||
- `styles/shadow/*.css` are the stylesheets: `index.css` (the pages': the portal's `styles/index.css`, then the admin's parts, which only add classes on the portal's tokens) and `maps.css` (the map's module: `map.css`, `closeup.css`). The build bundles each, runs `build/shadow-css.ts` (`:root`/`html`/`body` → `:host`, the colour scheme → `:host([data-theme=…])`) and imports the result as text.
|
||||
- The pages use the portal's own modules (`portal/dom`, `motion`, `ui/sheet`, `ui/menu`, `ui/feedback`, `ui/glass`; and the small parts both sides need, which live there for that reason: `ui/tip`, `ui/inline-edit`, `ui/carry`, `ui/grown`, `ui/chips-motion`, `ui/fold`, styled in `portal/styles/kit.css` and `behind.css`; the rules of a typed network are `shared/nets.ts`; the portal never imports from `admin/`) and the admin's portal-style parts in `ui/` (`tabs`, `page-head`, `glass`, `icons`); their strings are in the admin's catalog (the extractor follows the admin's imports into `src/portal`). Inside a Shadow DOM `document.activeElement` is the host: read the focus from the element's root (`focusInside`), find elements from the host's root, and route keys through `composedPath()`.
|
||||
- **A region drawn again swaps its children with `portal/ui/put.ts` `putChildren`, never `replaceChildren`.** `replaceChildren` empties the box first. WebKit lays the page out when the node that holds the focus leaves it (the switch just pressed), finds the page shorter than its scroll position and clamps it: on an iPhone every press in Settings sent the page to its top (the owner, 2026-11-12: «кликая на разные кнопки у меня слетает в самый верх»). `putChildren` puts the new nodes in before it takes the old ones out and leaves alone what stays, so the page is never shorter than it was or will be. It also holds the scroll position of every box around the one it fills (read before, put back after, in the same task): a section on screen swapped for a newly built one of the same height still put the page at its top, with nothing emptied (the chips of «What it installs», the owner the same day: «все еще телепортируют вью вверх»); it takes a new node whose styles answer the page's container queries, and what WebKit does there is not known. So a part that is pressed is better kept than built again (`carryOn`), and the hold is what stands when it is not. A redraw that takes nodes out before it comes to `putChildren` (the people's cards build their next groups around the cards they keep) runs inside `keepPlace(box, fn)`, the same hold around a whole function. Chromium does not show any of it: such a change is checked in WebKit (Playwright's, with an iPhone profile), not only in Chrome.
|
||||
- Enter in a text field with its own key handler does nothing while a word is being composed (`shared/keys.ts` `composing`): an input method's Enter picks a candidate. A field in a `<form>` that is submitted needs none of it.
|
||||
- Pages build from `ui/` and `widgets/`; a page never defines a generic component. Logic that does not touch the DOM (formatting, models, CSV, sorting) lives outside the render code and gets tests.
|
||||
|
||||
## Live data
|
||||
|
||||
- Admin pages use `createPoller` (`state/poller.ts`): newest answer wins, no repaint of a region that holds focus, every RPC failure shows a toast or an inline error, never a blank section.
|
||||
- Changes reach open pages through the revision (`state/live.ts`): one small `rev` call every 2 s while the page is visible; pollers that opt in (`live: true`) refresh when it moves. Their own `every` stays as a slow fallback.
|
||||
- The portal does not poll (each request is a CGI process on the router, see `backend.md`): it loads once, after the visitor's own changes, and while it waits for a new device's first connection.
|
||||
- **A failure reaches the page only as words for a person** (`admin/failure.ts`; the owner, 2026-11-12: «нужно как-то правильно показывать их по всей админке»). What is thrown goes through `errorText(e)` (`ui/toast.ts`): the backend's refusals and the page's own `new Error(_('…'))` are sentences and are shown as they came; LuCI's reports of the bus and the network («RPC call to … failed with ubus code 4») are told by their code (restarting, too slow, session ended, may not, page and router disagree, unreachable); the engine's errors and a program's text (lower-case first) get one plain sentence, and the original goes to the console. A failure the router keeps in its state (a component's check, an update job, the updates' history) goes through `routerSaid(text)` the same way. Never put `e.message`, `String(e)` or a state's `error` on the page directly. Throw your own failures as sentences, capital first, in `_()`.
|
||||
- Changes reach open pages through the revision (`state/live.ts`): one small `rev` call every 2 s while the page is visible; pollers that opt in (`live: true`) refresh when it moves. Their own `every` stays as a slow fallback (30 s for the status).
|
||||
- What costs the router more is asked for only while it is seen: the live meter once a second only while a speed is on screen (an IntersectionObserver on its tile; the agent writes the meter out each second someone asks), `health` when a page that shows it opens and then at most every 2 minutes, never on the revision (Overview and Settings run it in the background after drawing), `updates_status` every 10 s only while Settings' Updates is on screen, the portal's addresses (`portal_info`) once its section is, a server's interfaces when Settings opens and after a change made there. Overview reads 60 days of status (its line and the 30 before). A part of Settings is built again only when what it shows changed (a key of its data), and never while a value is typed in it.
|
||||
- **Opening a page never waits under LuCI's spinner, and comes in as the portal's page does: no skeleton** (the owner, 2026-11-12, after skullet: «убрать скелетон загрузку с админки и сделать анимацию появления и перехода по страницам как на портале»). A view's LuCI `load` ends with the stylesheet (`shell/view.ts`); the page's own `load()` asks the router then, and only then (no answer is kept between visits or shared between pages, and no sample stands in for it). Until it answers the view is its section row (`shell/waiting.ts`), and after 600 ms the reason it waits under it (the backend starting, the router slow, a failed question asked again every 3 s): never a black page; then the page is drawn whole and its blocks rise (`ui/entrance.ts enter`, the portal's `portal/ui/rise.ts`). A view a page swaps in on its own (a server's part, a Settings section, People's cards and map, a person's page and the list back) is put in place and given to `enter` too, once it is drawn. Nothing else on a page moves on a repaint (DESIGN.md › Motion › 16). **A move between Dawnline's own pages does not go through LuCI** (`shell/pages.ts`): a link or `visit()` to another section pushes the address and changes the page under the section row in place (`stagePage`), so the row never blinks; the page that goes is told through `onNavigate` (`ui/nav.ts`: it fires for the theme's navigation and for this), and the listeners it put on the window and the document while it was made and drawn are taken off. So a page cleans up through `onNavigate`, never by listening for `luci-navigate` itself, and reads its address from `location` when it is made. A view is whole when it is handed to a sheet (`go`, `openSheet`): what it draws later goes through the sheet's `glide`.
|
||||
- **The portal follows its stream where the router offers one.** With the Go backend serving the portal, the page's shell carries `data-live` and `portal/live.ts` follows `GET <link>/api/live` (`put` the whole state, `patch` a merge patch, `gone`): `main.ts took()` lays each state over the last and draws in place, as after a visitor's own change. Without it the page asks once (`refresh()`), as before; flows that ask for themselves (`flows/wait.ts`) are unchanged. Nothing is asked on a timer either way. Before its first state the page stands as its breadcrumb over its last shape (`page/waiting.ts`).
|
||||
- **Being replaced** (`docs/backend.md`): pages follow the backend's stream through `shared/live` (signals, a store of topics, `follow.ts`) and bind each node to the place it shows, instead of fetching `status` and rebuilding. New live code is written against `shared/live`; the pollers and the revision go when the last page has moved.
|
||||
- The portal does not poll: it follows its page's stream (`/<code>/api/live`, `web/src/portal/live.ts`) and asks again only after the visitor's own changes.
|
||||
|
||||
## Checks
|
||||
|
||||
|
||||
+2
-3
@@ -1,6 +1,6 @@
|
||||
# Translations (admin UI, portal, backend messages)
|
||||
|
||||
Dawnline is written in English and translated through gettext catalogs. Russian is the first translation. Read with `frontend.md` (and `backend.md` for messages the router sends).
|
||||
Dawnline is written in English and translated through gettext catalogs. Russian is the first translation. Read with `frontend.md` (and `backend-go.md` for messages the router sends).
|
||||
|
||||
## The rule
|
||||
|
||||
@@ -13,7 +13,7 @@ Dawnline is written in English and translated through gettext catalogs. Russian
|
||||
- **Admin UI (LuCI).** Every visible string goes through LuCI's globals `_()` and `N_()`. The catalog is `package/luci-app-dawnline/po/ru/dawnline.po`; luci.mk compiles it with po2lmo into the separate package `luci-i18n-dawnline-ru` (`/usr/lib/lua/luci/i18n/dawnline.ru.lmo`, plus the uci-defaults that adds Russian to LuCI's languages). LuCI loads it when the page language is Russian (`luci.main.lang`, or `auto` with a Russian browser). Without the package everything stays English. The LuCI menu titles (`menu.d`) are in the same catalog.
|
||||
- **Portal.** Not LuCI: it carries its own catalog (`web/src/portal/i18n/ru.po`, made into a lookup table at build time and bundled into `portal.js`), so it speaks Russian on every router, with or without the admin's package. `portal/i18n.ts` installs `_()`/`N_()` with LuCI's meaning, opens in the visitor's kept choice or the browser's language, and the language menu in the breadcrumb switches it in place. The demo's own strings are in `web/src/portal/demo/i18n/`.
|
||||
- **Shared code** (`web/src/shared`) runs in both and is in both catalogs.
|
||||
- **Backend messages** (ucode: `die()` texts, health checks, endpoint verdicts, the updater's phases) go through `_()` / `N_()` from `dawnline.i18n` and are in the `dawnline` catalog too. The admin page sends its language with every RPC call (`lang`, added by `web/src/admin/api.ts` and stripped by `rpcd/ucode/luci.dawnline`), the updater gets it from the job's start (`DAWNLINE_LANG`), the portal's CGI from `Accept-Language` (the portal's fetch sends the visitor's choice). `dawnline.i18n` reads LuCI's catalog through `luci.core`, so the backend speaks Russian where `luci-i18n-dawnline-ru` is installed; the portal page translates what reaches it in English from `portal.uc`, `devices.uc`, `core.uc` and `awg.uc` with its own catalog. The agent's and the CLI's terminal output stay English. Text the backend stores and shows later is stored as a code (or, for service log lines, as `L_()` templates) and put into words when it is read.
|
||||
- **Backend messages** (refusals, health checks, endpoint verdicts, the updater's phases, the portal's answers) are English sentences in the Go code, put into the reader's language by the catalog (`i18n.Catalog.T`, `N`) and listed in `backend/i18n/messages.js` (and `portal-messages.js` for what reaches the portal's visitors): the extractor reads those two files, not Go. **A sentence the backend says that is not listed there has no translation**: add or change it there in the same change, then `npm run i18n` and translate. `L_()` there marks a line of the service log (written in English, translated where it is shown). The admin page sends its language with every call (`lang`, added by `web/src/admin/api.ts`), the updater gets it from the job's start (`DAWNLINE_LANG`), the portal from `Accept-Language`.
|
||||
- **Delivery.** The release has `luci-i18n-dawnline-ru-<version>.{ipk,apk}` next to the app. `install.sh` adds it when LuCI is in Russian (its setting, or `luci-i18n-base-ru` installed) or with `--lang ru`; the updater installs it with every Dawnline update when it is installed; Components → Dawnline → Translation adds or removes it. LuCI reads a language's catalogs once per web server process, so each of these restarts uhttpd afterwards.
|
||||
- **Collecting.** `npm run i18n` (in `web/`) reads the code and rewrites the `.pot` templates and the `.po` files: new strings are added untranslated, gone ones removed, translations kept (and reused across catalogs). `npm run i18n:check` (CI) fails when a catalog is out of date, a string is untranslated, or a translation lost a placeholder. After changing visible text: run `npm run i18n`, translate the new entries in each `ru.po`, commit the catalogs with the code.
|
||||
|
||||
@@ -70,7 +70,6 @@ Write like a careful Russian product (Telegram, Яндекс), not a word-for-wo
|
||||
| data limit | лимит трафика |
|
||||
| usage, traffic | трафик |
|
||||
| end date; ends in 3 days | дата окончания; закончится через 3 дня |
|
||||
| allowed hours; outside allowed hours | часы доступа; вне часов доступа |
|
||||
| pause / resume; paused | приостановить / возобновить; на паузе |
|
||||
| online / offline; last seen 12 min ago | в сети / не в сети; «В сети 12 мин назад» (not «Было в сети») |
|
||||
| set up a device; setup | настроить устройство; настройка |
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# Release notes: how the list of changes is collected
|
||||
|
||||
A release's `- ` points (`AGENTS.md` › Releases) and any list of «what changed» asked for along the way are collected the same way. The owner set it on 2026-11-12, after a list made from commit messages came out long, mixed trivia with what matters and missed whole features: «в будущем мне нужно чтобы ты так всегда логи собирал».
|
||||
|
||||
## The rule
|
||||
|
||||
- **From the code, against production.** Production is the last release: the tip of `origin/main`, the last tag `vX.Y.Z`. Go through the difference itself (`git diff vX.Y.Z..HEAD`), not only the commits' titles and bodies: the backend's methods that came and went (`backend/methods`), the settings (`backend/model`), the admin's pages, flows and widgets (`web/src/admin`), the portal (`web/src/portal`), the package's dependencies, the scripts. The commit messages are where to start, never the source: the list made from them alone missed bulk actions on people, the rollout of a new configuration, «Waiting for a decision», Undo and the simplified expiry.
|
||||
- **Key changes only.** What somebody who runs Dawnline wants to know: what was rebuilt (the backend in Go), what is faster and by how much, what can be done now that could not, what is gone, what behaves differently. One short line each, the thing first.
|
||||
- **Not the trivia.** The owner's own examples of what does not belong: «Show speeds in bytes per second (KB/s, MB/s), the measure the traffic beside them is counted in» («околобесполезная инфа») and «New README screenshots of the redesigned admin» («юзелесс»). A unit, a label, a picture, a move of code nobody sees: left out.
|
||||
- **A rework is told whole.** What it was, what it is now, and what happens to what people had before the update. One line for the limits counted by a person's own month was not enough (the owner: «а как же реворк системы юседжа и времени старта отсчета»): it takes the rule (the month begins with their first traffic, the next only when they connect again), what follows from it (extra data, «Reset usage», the charts) and what an update does to the month that was running.
|
||||
- **A number says where it is from.** Measured for this list, or taken from `docs/` or a commit's message (and on which router). Nothing is called checked that was only read in the code.
|
||||
- **In English.** The points are English whatever language they were asked for in: what the owner writes in Russian is what he means, not how to write it («то что я пишу на русском это то что я имею ввиду а не как написать»). The talk around the list stays in his language.
|
||||
|
||||
## How
|
||||
|
||||
1. Find production: `git fetch`, then the default branch's tip and its tag.
|
||||
2. Size the difference by area (`git diff --numstat`), then read each area for what came, went and changed: names that exist on one side only are the quickest lead (methods, options, files added and deleted), and each lead is checked in the code before it is written down, since a thing drawn again is not a thing added.
|
||||
3. Read the commits' bodies for the reasons and the measurements.
|
||||
4. Write the short list; expand the reworks; say what was left out on purpose only if asked.
|
||||
+34
-16
@@ -2,33 +2,51 @@
|
||||
|
||||
The bar is a modern product UI (Linear / Vercel / Raycast level), not a "native" LuCI form. A plain label + input row, a bare radio list, three columns of check marks or a text dump is a first draft, never the result.
|
||||
|
||||
**The portal has its own design system, `DESIGN.md`** (repo root): read it before any portal work, mocks included. Build from its tokens, components and spring tokens, follow its Do's and Don'ts, and update it in the same change when the portal's look or motion changes. The admin follows this file and the LuCI theme.
|
||||
**One design system, `DESIGN.md`** (repo root): the personal portal's, and the admin's too. Read it before any work on either, mocks included. Build from its tokens, components and spring tokens, follow its Do's and Don'ts, and update it in the same change when the look or motion changes.
|
||||
|
||||
## The admin on the portal's design system
|
||||
|
||||
Every admin page is drawn on `DESIGN.md` inside LuCI (the concept: `dawnline-admin-concept`; the structure: its `docs/ia2/`, decisions in `06-decisions.md`). Three sections answer three questions: **Overview** (does everything work now: «now» in numbers, the servers, Health), **Log** (what happened: the feed with its filters) and **Settings** (how the router, the portal and Dawnline itself are set up: a rail of sections shown one at a time). Everything of one server stands behind one door (the owner's structure, 2026-11-11): a server's card on Overview opens **the server's page**, whose track across the page is Overview (does this server work, who on it waits for a decision, its rollout, its checks, the path check) · People (their cards grouped by state; a person's page takes the list's place) · Places (the map of where they connect from) · Settings (General: its name, whether it runs, its address, removing it; Core: what is the tunnel core's own; Network: where the tunnel leads; a rail names the three, a jump pill on a phone). A device is not a page: it opens from its person as a dialog in two columns (what it does on the left, what it is set up with on the right), and «Map and replay» and «Show set-up» are steps of that dialog. A person, a device and Places are not LuCI pages: they are People's `?id=`, `?device=` and `?view=map` inside the server's frame. One fact, one place holds across the frame: the server's state is its head's, who waits is its Overview's (the main Overview only counts them on the server's card), a device's state is said once in its dialog. The old addresses (Person, Device, Places, System, Activity, Health, Diagnostics, Updates, the old Settings, Server and Servers pages' sections) lead to their places now.
|
||||
|
||||
- **A card says only what is true now and changes something.** A person's card on People has its parts by their state (`people/card.ts`, DESIGN.md › Person card): a decision is its line and its button, someone fine is presence and traffic, a quiet state is one line. What stops many people at once (a server turned off, a rollout) is one notice over the list, not a part of each card. Counts of people (chips, group heads, Overview's «Waiting for a decision») come from the same matrix.
|
||||
- **No page of accordion rows.** An object's page is not a stack of «name — value» rows that fold: each thing it has gets a form of its own that shows its state and is edited on itself (a term with its calendar, a measure with its limit, switches of what is reached, a file card). A fold is allowed inside such a part for what is read always and changed rarely (the interfaces a server does not offer as home networks), never as the page's skeleton.
|
||||
- **Run the padding lint before showing or shipping a look change:** `node tools/ia3-pads.mjs` in the concept repo (`SHEETS=<openers.jsonl>` walks the sheets too, `W=390` the phone), DESIGN.md › «Paddings, checked». It must print «0 findings»; a finding is fixed in the stylesheet, not silenced in the tool, unless the tool misread a clipped or pinned element.
|
||||
- **A name and a note never look alike, and a note sits with what it explains** (DESIGN.md › «A name, a value, a note»): a label or caption in the text's colour with a weight, a note in the second tone 6 px under its thing and well clear of the next name, one note a thing. Before adding a line of grey text, say which thing it explains and put it there; if it explains nothing in particular, it is a lead or it goes.
|
||||
- **One home per fact and control**; elsewhere only a pointer to it (a number or a phrase that leads there).
|
||||
- **A fix stands where the problem is.** A check that did not pass is shown in the Settings section it is about, with its fix as a button or its advice; Overview shows the same signal as a link to that section, without a second button (it keeps a button only for a check no section is about).
|
||||
- **Settings wait for «Apply».** Nothing that changes how a server works or what a person may do is made by one press (the owner, 2026-11-11: «половина настроек не имеет подтверждения»): the edit waits, its place shows the new value as not applied, a dock at the window's foot says «N changes · M devices will fetch the configuration · Apply / Cancel». «Apply» makes them all: when devices must fetch their configuration again it asks one question naming every change first and starts one rollout, which the page then shows open; when none must, «Apply» is the whole confirmation. This holds for a server's Settings (every field, the disguise, the home networks, how internet traffic leaves, the WAN, who sees whom), for the router-wide sections (the portal with its addresses, port, certificate files and unknown links; new people's defaults; the update policy; history and what is recorded: one dock with the server's changes, «not applied» at the end of the section's head) and for a person's page (what they reach, the limit and its period, the device limit). Not settings, so made at once: a name or a note typed and confirmed with Return; the one-tap actions with Undo in their toast (pause and resume, extend, more data this month, a device or a server turned on or off as before); what destroys or cannot be undone asks its own question (remove, new keys, reset). Leaving with changes waiting is asked about.
|
||||
- **The rollout is open on the page**, not behind a pill: how many fetched, the change it follows, a cell a device, who still waits with their links (no «Remind everyone»: the owner removed it, a person is reminded with their own link).
|
||||
- **Inside LuCI, in a Shadow DOM.** The theme's rules stop at the page's host and ours never reach the theme. What floats (the sheet, ⋯ menus, toasts, the map's marker card) is in a second host on `<body>`, above Outline's header and sidebar, below LuCI's own modal.
|
||||
- **No ground of our own.** The page stands on the theme's background: dark keeps the portal's ladder on the theme's black; light steps raised → field → knob down in tone from the theme's near-white (`styles/shadow/ground.css`).
|
||||
- **Theme from LuCI** (`html[data-darkmode]`, Outline's button switches it in place), else the system's. **The system font**, as the portal.
|
||||
- **Own navigation, no LuCI tabs.** LuCI's menu keeps one Dawnline item (an alias of Overview); every section is a view of its own (Back and bookmarks work) and the page draws its own row: Overview · Log · Settings, the portal's segmented track with words (`shell/nav.ts`); a server's page keeps Overview lit and draws its own track under its head. What is picked inside a section (a panel, a view, a filter) is in its address too.
|
||||
- **Layout by the page's width**, not the window's (container `dlpage`: inside LuCI the column is ~910 px on a 1440 screen).
|
||||
- **Admin-only parts on the portal's tokens:** the page head (glass, name, facts after dots, ⋯ on the right), a labelled segmented track with counts or icons (narrow: icons, the picked one with its word), the kit (`rules/frontend.md`: a person's card by state with its device tiles, the filter bar with its search and chips, a list of choices under its button, a list and the page of one thing in it (the way back and ×), a tooltip for a thing without words, a rail of sections with a jump pill on a phone, a section with its cards, option tiles that draw their choice, a measure with its limit, a server's way in as two named cells and the router's verdicts as rows, a row of a thing with its actions in sight, the empty state, a map with its list, and a panel's parts: term, traffic measure, what-they-reach switch rows, set-up card, place rows with strips, the short feed), rows of a feed in a raised card under day heads, the way back (‹ parent), charts in the map's language (`--live`, `--past`: the line of days with the period before it dashed, the live line under a speed, today by the hour as bars).
|
||||
- **Approved deviations from the portal:** an undo beside a toast's words for a reversible one-tap action (5 s, held under the pointer or focus); toasts wrap (the admin's sentences are longer); the portal's buttons, sheet and menus as they are, nothing restyled.
|
||||
- **Read-only logins** see values without the controls that would fail (`shell/role.ts`), and a «View only» fact in the head.
|
||||
- **Four LuCI modules, each under 576 KiB** (uhttpd sends them uncompressed; the build refuses more): the pages (`dawnline.app`), their stylesheet (`dawnline.style`), the map (`dawnline.map`, loaded when a page draws one) and the QR generator (`dawnline.qr`, loaded when a sheet draws a code). Something a page rarely needs and that would push a module over goes into a module of its own, loaded on demand (`rules/frontend.md`).
|
||||
|
||||
## Approach
|
||||
|
||||
- **Mock first.** Any visible change beyond a one-line fix: show a mockup (2–4 genuinely different options when the direction is open) with a recommendation, then build the chosen one. Do not start coding a layout the user has not seen.
|
||||
- **Think past the obvious.** When an option is rejected as "not it", propose new concepts, not variations of the same layout.
|
||||
- **Structure over text.** Tiles, segmented controls, pills, round icon buttons, inline status, folded "Advanced" sections. Summaries first ("All 6 checks passed"), details on demand.
|
||||
- **No duplication.** One place per fact (usage, device count, links). Remove what is repeated elsewhere on the page.
|
||||
- **Reuse the house patterns** before inventing new ones: `dl-params` folded details with a rotating chevron, `dl-tile2` tiles, round icon buttons with tooltips, `⋯` menus (destructive and Pause inside, Pause in warn colour, "Delete" without an ellipsis), bottom toasts instead of LuCI banners, the same tiles on server and person pages.
|
||||
- **Alignment and spacing are part of the design.** Shared margins and edges, equal heights in a row, controls pinned consistently (top, not centred, when the user says so), nothing clipped or overflowing, single-line labels where they fit.
|
||||
- **No ellipsis on buttons or menu items** ("Remove", not "Remove…"), even when they open a dialog. "…" only for progress ("Loading…") and truncated values.
|
||||
- **Colour means something:** ok = green, warn/pause = orange, danger = red, accent = blue. Icons for states instead of words where obvious.
|
||||
- **Structure over text.** Tiles, segmented tracks, pills, round knobs, inline status, folded rows. Summaries first ("All 6 checks passed"), details on demand.
|
||||
- **No duplication.** One place per fact (usage, device count, links), a state said once (DESIGN.md › Principles). Remove what is repeated elsewhere on the page.
|
||||
- **Reuse the house parts** before inventing new ones: the portal's components (DESIGN.md) and the admin's `ui/` and `widgets/` (page head, tabs, the kit, edit rows, stepper, the rows of checks and components, the rollout strip, line chart, live line, map box). An edit row is for a number without a picture of its own (MTU, keep-alive), at most four in a card, never a page of them. A new class only when nothing fits, and then on the portal's tokens.
|
||||
- **Alignment and spacing are part of the design.** Shared margins and edges, equal heights in a row, controls pinned consistently, nothing clipped or overflowing, single-line labels where they fit.
|
||||
- **No ellipsis on buttons or menu items** ("Remove", not "Remove…"), even when they open a sheet. "…" only for progress ("Loading…") and truncated values.
|
||||
- **Colour means something:** ok = green, warn/pause = orange, danger = red, accent = blue; on charts and the map, live = blue, the past = grey. Icons for states instead of words where obvious.
|
||||
- **Honest warnings** belong in the UI (e.g. plain HTTP, Cloudflare throttling), shown where the choice is made.
|
||||
|
||||
## Mocks look like the real product
|
||||
|
||||
A mock is judged against the page it will live on, so it must already look like it. Hand-drawn look-alikes with invented styles get rejected ("выбивается из дизайна").
|
||||
|
||||
- **Study the existing pages first** (the section being changed and its neighbours) and build only from their components: `dl-setsec` cards with `dl-setsec-foot`, `dl-setrow` rows with a `dl-need-ic` icon tile and `dl-switch`, `dl-seg` (`sm`, `wide`), `dl-chip` / `dl-chipbtn`, `dl-list` + `dl-row`, `dl-table`, `dl-checks` (the Health check list), `dl-tile2` tiles, `dl-panel`. A new class only when nothing fits, and then in the same tokens (`--dl-*`).
|
||||
- **Buttons are `cbi-button`**: actions like Edit, Change, Rescan are `neutral` pills (as "Edit in Settings", "+ Add device"); Save and Install are `positive`. No blue text links for actions.
|
||||
- **Show only what changes.** Do not add existing, unrelated controls (e.g. Devices or Access ends tiles) to a mock; say in the caption that the rest of the page stays.
|
||||
- **Build it from the real code and CSS**, not from a copy:
|
||||
- theme: `scp root@outline.lan:/www/luci-static/outline/{main.css,geist-*.woff2}` into the mock folder, strip `/luci-static/outline/` from the font URLs, `<html data-darkmode="true">`;
|
||||
- Dawnline CSS: the files in `web/src/admin/styles/*.css` concatenated in the order of `styles/index.ts` into `dl.css`;
|
||||
- markup: a small `mock.ts` that imports the real `admin/e`, `shared/icons`, `admin/ui/*` and `admin/widgets/*` (stub the LuCI globals `window.E`, `dom.content`, `L.url`), bundled with `web/node_modules/.bin/esbuild --bundle --format=iife`.
|
||||
- Keep mocks outside the product repo, serve them with `python3 -m http.server` started from Bash (the preview server cannot read `~/Documents` on macOS), open them in the built-in browser, and delete the folder when the feature ships.
|
||||
- **Study the existing pages first** (the section being changed and its neighbours) and build only from their parts: the portal's components and tokens (DESIGN.md), the admin's `ui/` and `widgets/`.
|
||||
- **Build it from the real code and CSS**, not from a copy: the concept repo's mock pages run the real `web/src` modules (the portal's, the admin's) on demo data; a change to an existing page is mocked in a LuCI stand-in (Outline's shell and `main.css`, LuCI's globals stubbed, the RPC answered from fixtures) that loads the built `app.js`, `style.js` and `map.js`.
|
||||
- **Show only what changes.** Do not add existing, unrelated controls to a mock; say in the caption that the rest of the page stays.
|
||||
- Keep mocks outside the product repo, serve them with `python3 -m http.server` started from Bash (the preview server cannot read `~/Documents` on macOS), and delete the folder when the feature ships.
|
||||
|
||||
## Done means seen
|
||||
|
||||
Deploy, then look at it in the browser (desktop width, and narrow when layout changes) before reporting. Check modals and drawers stack correctly and long values do not overflow. Look at it in Russian too: a visible change is localized in the same change (`i18n.md`), and Russian text is longer.
|
||||
Look at it in the browser before reporting (a LuCI stand-in, or the router after a deploy): 1440 and 390 (touch), both themes switched from Outline's button, read-only too. Look at whole screens, not crops alone, and measure overflow at 390 inside the shadow roots (the page's and the layer's). Check sheets and menus stack correctly and long values do not overflow. Look at it in Russian too: a visible change is localized in the same change (`i18n.md`), and Russian text is longer.
|
||||
Reference in new issue
Block a user