Files
dawnline/rules/frontend.md
T
Aemeath ac90575b0b
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
Dawnline 0.20.0
- **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.
2026-11-13 09:43:50 +03:00

21 KiB
Raw Blame History

Frontend (TypeScript: admin UI and portal)

Read with code-standards.md and, for anything visible, ui-design.md and i18n.md (every visible string goes through _()). Portal work starts with DESIGN.md (its tokens, components and motion).

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: 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.
  • 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

  • In web/: npm run format:check, npm run typecheck, npm run lint, npm run knip, npm run i18n:check, npm test, npm run build; the catalogs are committed, the bundles under package/ are git-ignored (CI builds them before packaging).