Files
furumi-web/docs/admin-ui.md
T
Aleksandr Bogomiakov 9b923851ae
Build and Publish / Build and Publish Docker Image (push) Successful in 7m46s
Fixed build. Reworked mobile admin UI
2026-11-18 15:17:50 +00:00

5.3 KiB
Raw Blame History

Admin interface conventions

Project overview · Development

The admin UI uses one Alpine application and shared layout primitives for every section. Add features to this model rather than introducing a separate mobile page or section-specific navigation.

Ownership

  • templates/admin/navigation.html: the single navigation tree, grouped into Operations (reviews/tasks), Music (library/tools/statistics), and Instance (users/settings). Existing hash routes remain the source of navigation state.
  • templates/admin/styles.html: colors, typography and component appearance.
  • templates/admin/responsive.html: shared layout, breakpoints, touch targets, scroll regions, table cards and dialog sizing. Put responsive rules here.
  • templates/admin/ui.html: viewport state, task tabs, settings navigation and the shared overlay lifecycle. Business data and API actions remain in adminV2() in v2.html.

Layout

Width Navigation Workspaces Lists and dialogs
1280 px and above Persistent sidebar Task list/detail/log side by side Tables, centered bounded dialogs
1024–1279 px Persistent sidebar Task tabs; settings in one column Tables, bounded dialogs
768–1023 px Drawer Task tabs; settings section picker Tables in contained scroll areas
Below 768 px Drawer Single column Table cards, full viewport dialogs

Keep CSS and matchMedia breakpoints in ui.html synchronized. The main panel owns page scrolling. Use minmax(0, 1fr) and min-width:0 for grid/flex children; never restore a global minimum page width. The top bar stays available while content scrolls. Navigation closes after route changes and when switching to the desktop layout. It retains the active section and the existing URL routes.

Use .panel, .panel-head, .panel-title, .toolbar, .action-strip, .field and .editor-grid for new content. Toolbars wrap, inputs fill available space, and mobile controls use 44 px touch targets and 16 px input text. Long identifiers, paths and names must wrap. Avoid fixed column widths and inline grid definitions.

For tabular lists, add .responsive-table, a data-label to every cell, and data-primary to its identifying cell. Mobile CSS presents the same DOM as cards; do not duplicate rows or hide actions. Give clickable row titles real buttons using .row-link, so the operation also works with a keyboard. Dense comparisons, charts and logs may scroll inside a named, keyboard-focusable region; horizontal scrolling must never propagate to the page. Keep these exceptions intentional.

Task tabs change presentation only: configuration and selected run stay in memory when switching tabs or rotating the device. In settings, add a section ID and a matching entry to the section picker. Put related controls in .settings-grid.

Dialogs

Every dialog uses the same hierarchy and lifecycle:

<div class="modal-backdrop" x-show="exampleOpen"
     x-effect="adminOverlay.sync($el, !!exampleOpen)"
     @keydown="adminOverlay.keydown($event, $el)"
     @click.self="closeExample()">
    <section class="modal" role="dialog" aria-modal="true"
             aria-labelledby="example-title" tabindex="-1">
        <div class="modal-head">
            <strong id="example-title">Edit item</strong>
            <button class="icon-btn" data-dialog-close
                    aria-label="Close dialog" @click="closeExample()">…</button>
        </div>
        <form class="modal-body" @submit.prevent="saveExample()">
            <!-- .field and .editor-grid -->
            <div class="dialog-actions"><button type="submit" class="btn primary">Save</button></div>
        </form>
    </section>
</div>

The helper locks the background with inert, moves focus into the dialog, traps Tab/Shift+Tab, handles Escape through the existing close button, and restores focus on close. Keep business rules in the close handler and disable that button when closing is not allowed (for example, while merging). Nested pickers consume Escape with .stop before the dialog handles it. Headers remain fixed while the body scrolls; .dialog-actions keeps actions available at the bottom. On mobile, dialogs use 100dvh and safe-area padding. Reuse the helper for new overlays.

For content gated by an asynchronous load inside an animated dialog, use :hidden="loading" instead of nesting competing x-show transitions. Loading and content should not both stay hidden when a response arrives during opening.

Verification

Run node --test tests/*.test.cjs and build the Rust application (templates are compiled into the binary). tests/browser-admin-responsive.cjs checks all seven sections at 320, 390, 768, 1024 and 1440 px, navigation focus, task state retention, settings jumps, all five dialogs, long content and landscape geometry. It uses a disposable running instance with an admin and at least one release containing a track; browser fixtures do not modify server data. Supply FURU_TEST_URL, FURU_TEST_USERNAME, FURU_TEST_PASSWORD, PLAYWRIGHT_MODULE, and CHROME_PATH as appropriate. Set FURU_TEST_SCREENSHOTS to inspect screenshots visually.

Check both populated and empty views, long names/paths, loading states, keyboard navigation, reachable Save/Close controls, and resize while an overlay is open.