schn33fuchs/ticketsystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Refined docs and stuff

Browse Source 
Docs link to each other and are generally better
This commit is contained in:
Silas
2026-05-20 12:50:00 +02:00
parent 0db9b76cad
commit 721e43c380
14 changed files with 256 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
frontend/src/lib.rs
View File

@@ -10,7 +10,9 @@ use yew_router::prelude::*;
/// Defines the application's various routes and their corresponding paths.
///
/// This enum is used by `yew-router` to map URLs to specific components,
/// enabling navigation within the single-page application.
/// enabling navigation within the single-page application. Each route is protected
/// by [`ProtectedRoute`] middleware where appropriate to enforce authentication and authorization.
/// See [`switch`] for the routing logic.
#[derive(Clone, PartialEq, Routable)]
enum Route {
/// The application's home page.
@@ -65,10 +67,10 @@ pub struct SidebarShellProps {
/// A shell component that provides a consistent layout with a sidebar and a main content area.
///
/// This component is designed to wrap page-specific content, ensuring that the sidebar
/// is always present for navigation.
/// is always present for navigation. Integrates with [`crate::pages::sidebar::Sidebar`] for navigation.
///
/// # Components
/// - [`sidebar::Sidebar`]: The navigation sidebar component.
/// - [`crate::pages::sidebar::Sidebar`]: The navigation sidebar component.
/// - Main content area: Renders the `children` passed to this component.
///
/// # Example
@@ -101,11 +103,11 @@ pub struct AdminCheckWrapperProps {
///
/// This component is used to gate access to pages that should only be accessible before
/// system initialization (e.g., login page). It performs an asynchronous check to the
/// `/api/check-admin` endpoint to determine system state.
/// backend's `/api/check-admin` endpoint (via `crate::handlers::auth::check_admin_exists`) to determine system state.
///
/// # Behavior
/// - **Loading**: Displays "Loading..." while checking admin status
/// - **No Admin**: Automatically redirects to `/setup` page to initialize
/// - **Loading**: Displays "Loading..." while checking admin status from the backend
/// - **No Admin**: Automatically redirects to [`Route::Setup`] page for initialization
/// - **Admin Exists**: Renders the wrapped children (e.g., login page)
///
/// # Example Usage
@@ -115,19 +117,9 @@ pub struct AdminCheckWrapperProps {
/// </AdminCheckWrapper>
/// ```
///
/// # Implementation Detail
/// The check happens in `use_effect_with` on component mount:
/// ```ignore
/// spawn_local(async move {
/// match Request::get("/api/check-admin").send().await {
/// Ok(resp) if resp.status() == 200 => {
/// let has_admin = data["has_admin"].as_bool().unwrap_or(false);
/// admin_exists.set(Some(has_admin));
/// }
/// _ => admin_exists.set(Some(false))
/// }
/// });
/// ```
/// # Backend Integration
/// The check queries the backend's `/api/check-admin` endpoint which returns `{"has_admin": bool}`.
/// This allows the frontend to determine if initial admin setup is required.
#[component(AdminCheckWrapper)]
fn admin_check_wrapper(props: &AdminCheckWrapperProps) -> Html {
let admin_exists = use_state(|| None::<bool>);
@@ -166,18 +158,24 @@ fn admin_check_wrapper(props: &AdminCheckWrapperProps) -> Html {
/// The main routing logic for the application.
///
/// This function takes a `Route` enum variant and returns the corresponding HTML
/// This function takes a [`Route`] enum variant and returns the corresponding HTML
/// content to be rendered. It acts as a central dispatcher for the application's
/// navigation.
/// navigation and authentication flow.
///
/// Many routes are wrapped in a [`ProtectedRoute`] to enforce authentication
/// and authorization, and in a [`SidebarShell`] to maintain consistent layout.
/// Most routes are wrapped in [`ProtectedRoute`] to enforce authentication
/// and authorization based on the `admin_page` flag, and in [`SidebarShell`] to maintain consistent layout.
/// Login and Setup routes use [`AdminCheckWrapper`] instead to handle pre-authentication states.
///
/// # Arguments
/// - `route`: The [`Route`] enum variant representing the current URL path.
///
/// # Returns
/// An `Html` component that should be rendered for the given route.
///
/// # Route Protection
/// - **Admin-required routes** (`admin_page={true}`): Require both authentication and admin privileges
/// - **Public routes** (`admin_page={false}`): Require only authentication
/// - **Pre-auth routes** (`AdminCheckWrapper`): Used before admin creation or login
fn switch(route: Route) -> Html {
match route {
Route::Home => html! {
@@ -259,12 +257,16 @@ fn switch(route: Route) -> Html {
/// The root component of the Yew application.
///
/// This component sets up the application's routing using `yew-router`'s
/// [`BrowserRouter`] and [`Switch`] components. All other application content
/// is rendered based on the current route.
/// `BrowserRouter` and `Switch` components. All other application content
/// is rendered based on the current [`Route`] matched by the `switch` function.
///
/// Uses [`switch`] as the routing dispatcher to handle all route-specific rendering,
/// which applies appropriate middleware like [`ProtectedRoute`] and [`AdminCheckWrapper`].
///
/// # Structure
/// - [`BrowserRouter`]: Enables client-side routing.
/// - [`Switch`]: Renders components based on the matched [`Route`].
/// - `BrowserRouter`: Enables client-side routing.
/// - `Switch`: Renders components based on the matched [`Route`].
/// - `switch` function: Determines which component to render for each route.
#[component(App)]
pub fn app() -> Html {
html! {